Enterprise COBOL for z/OS, V5.1 Programming Guide

Enterprise COBOL for z/OS, V5.1 Programming Guide
Enterprise COBOL for z/OS
Programming Guide
Version 5 Release 1
SC14-7382-00
Enterprise COBOL for z/OS
Programming Guide
Version 5 Release 1
SC14-7382-00
Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
811.
First edition
This edition applies to Version 5 Release 1 of IBM Enterprise COBOL for z/OS (program number 5655-W32) and to
all subsequent releases and modifications until otherwise indicated in new editions. Make sure that you are using
the correct edition for the level of the product.
You can order publications online at www.ibm.com/shop/publications/order/, or order 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 that serves your locality.
© Copyright IBM Corporation 1991, 2013.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . xiii
Preface . . . . . . . . . . . . . . xv
|
|
About this information . . . . . . . . . . xv
How this information will help you . . . . . xv
Abbreviated terms . . . . . . . . . . . xv
Comparison of commonly used terms . . . . xvi
How to read syntax diagrams . . . . . . . xvi
How examples are shown . . . . . . . . xviii
Additional documentation and support . . . . xviii
Summary of changes . . . . . . . . . . xviii
Version 5 Release 1 . . . . . . . . . . xix
How to send your comments . . . . . . . . xx
Accessibility . . . . . . . . . . . . . . xxi
Interface information . . . . . . . . . . xxi
Keyboard navigation . . . . . . . . . . xxi
Accessibility of this information . . . . . . xxi
IBM and accessibility. . . . . . . . . . xxii
Part 1. Coding your program . . . . 1
Chapter 1. Structuring your program . . 3
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 . . . . . . . . . . .
.
.
. 3
. 4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4
5
5
5
6
7
8
8
9
. 11
. 12
.
.
.
. 14
. 16
. 17
.
.
. 18
. 22
Chapter 2. Using data . . . . . . . . 23
Using variables, structures, literals, and
Using variables . . . . . . .
Using data items and group items .
Using literals . . . . . . . .
Using constants . . . . . . .
Using figurative constants . . .
Assigning values to data items . . .
Examples: initializing data items .
Initializing a structure (INITIALIZE)
© Copyright IBM Corp. 1991, 2013
constants
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
23
23
24
26
26
27
27
28
31
Assigning values to elementary data items
(MOVE) . . . . . . . . . . . . . .
Assigning values to group data items (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) . . .
Using tables (arrays) and pointers . . . . . . .
Storage and its addressability . . . . . . . .
Settings for RMODE . . . . . . . . . . .
Location of data areas . . . . . . . . . .
Storage for LOCAL-STORAGE data . . . . .
Storage for external data . . . . . . . . .
Storage for QSAM input-output buffers . . . .
32
33
34
35
36
37
38
39
40
40
41
42
42
42
42
Chapter 3. Working with numbers and
arithmetic . . . . . . . . . . . . . 45
Defining numeric data. . . . . . . . . . .
Displaying numeric data . . . . . . . . . .
Controlling how numeric data is stored . . . . .
Formats for numeric data. . . . . . . . . .
External decimal (DISPLAY and NATIONAL)
items . . . . . . . . . . . . . . .
External floating-point (DISPLAY and
NATIONAL) items . . . . . . . . . . .
Binary (COMP) items . . . . . . . . . .
Native binary (COMP-5) items . . . . . . .
Packed-decimal (COMP-3) items . . . . . .
Internal floating-point (COMP-1 and COMP-2)
items . . . . . . . . . . . . . . .
Examples: numeric data and internal
representation . . . . . . . . . . . .
Data format conversions . . . . . . . . . .
Conversions and precision . . . . . . . .
Sign representation of zoned and packed-decimal
data . . . . . . . . . . . . . . . . .
Checking for incompatible data (numeric class test)
Performing arithmetic . . . . . . . . . . .
Using COMPUTE and other arithmetic
statements . . . . . . . . . . . . . .
Using arithmetic expressions . . . . . . .
Using numeric intrinsic functions . . . . . .
Using math-oriented callable services . . . . .
Using date callable services . . . . . . . .
Examples: numeric intrinsic functions . . . .
Fixed-point contrasted with floating-point arithmetic
Floating-point evaluations . . . . . . . .
Fixed-point evaluations . . . . . . . . .
Arithmetic comparisons (relation conditions) . .
Examples: fixed-point and floating-point
evaluations . . . . . . . . . . . . .
45
47
48
49
49
50
51
51
52
52
53
54
54
55
56
57
58
58
59
60
62
62
64
65
65
65
66
iii
Using currency signs . . . . . .
Example: multiple currency signs .
.
.
.
.
.
.
.
.
Converting data items (intrinsic functions) . .
Changing case (UPPER-CASE, LOWER-CASE)
Transforming to reverse order (REVERSE) . .
Converting to numbers (NUMVAL,
NUMVAL-C) . . . . . . . . . . .
Converting from one code page to another .
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 . . . . .
. 67
. 68
Chapter 4. Handling tables . . . . . . 69
|
|
|
Defining a table (OCCURS) . . . . . . . .
Nesting tables . . . . . . . . . . . .
Example: subscripting . . . . . . . . .
Example: indexing . . . . . . . . . .
Referring to an item in a table . . . . . . .
Subscripting . . . . . . . . . . . .
Indexing . . . . . . . . . . . . .
Putting values into a table . . . . . . . .
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 . .
Complex OCCURS DEPENDING ON . . . .
Example: complex ODO . . . . . . . .
Effects of change in ODO object value . . .
Searching a table . . . . . . . . . . .
Doing a serial search (SEARCH) . . . . .
Doing a binary search (SEARCH ALL) . . .
Processing table items using intrinsic functions .
Example: processing tables using intrinsic
functions . . . . . . . . . . . . .
Working with unbounded tables and groups . .
Example: Using unbounded tables for parsing
XML documents . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
69
71
72
72
73
73
74
75
75
76
.
.
. 77
. 79
. 80
81
. 83
. 84
. 84
. 85
. 86
. 88
. 89
. 90
. 91
. 92
. 92
. 93
.
.
.
.
.
.
. 97
. 97
. 102
. 105
. 106
. 107
. 108
. 108
Chapter 6. Handling strings . . . . . 109
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. . . . .
iv
. . 109
. . 110
. . 111
. . 112
. . 114
. . 115
. . 115
. . 117
.
. 118
.
.
.
. 118
. 119
. 119
Enterprise COBOL for z/OS, V5.1 Programming Guide
. 122
. 123
. 123
.
.
.
.
124
124
126
127
Chapter 7. Processing data in an
international environment . . . . . . 129
Chapter 5. Selecting and repeating
program actions . . . . . . . . . . 97
Selecting program actions . . . . . . .
Coding a choice of actions . . . . . .
Coding conditional expressions . . . .
Repeating program actions . . . . . . .
Choosing inline or out-of-line PERFORM .
Coding a loop . . . . . . . . . .
Looping through a table . . . . . . .
Executing multiple paragraphs or sections.
. 120
121
. 121
|
|
|
COBOL statements and national data . . . . .
Intrinsic functions and national data. . . . . .
Unicode and the encoding of language characters
Using national data (Unicode) in COBOL . . . .
Defining national data items . . . . . . .
Using national literals . . . . . . . . .
Using national-character figurative constants
Defining national numeric data items . . . .
National groups . . . . . . . . . . .
Using national groups . . . . . . . . .
Storage of character data . . . . . . . .
Converting to or from national (Unicode)
representation . . . . . . . . . . . . .
Converting alphanumeric, DBCS, and integer to
national (MOVE) . . . . . . . . . . .
Converting alphanumeric or DBCS to national
(NATIONAL-OF) . . . . . . . . . . .
Converting national to alphanumeric
(DISPLAY-OF) . . . . . . . . . . . .
Overriding the default code page. . . . . .
Conversion exceptions . . . . . . . . .
Example: converting to and from national data
Processing UTF-8 data . . . . . . . . . .
Using intrinsic functions to process UTF-8
encoded data . . . . . . . . . . . .
Processing Chinese GB 18030 data . . . . . .
Comparing national (UTF-16) data . . . . . .
Comparing two class national operands . . .
Comparing class national and class numeric
operands . . . . . . . . . . . . . .
Comparing national numeric and other numeric
operands . . . . . . . . . . . . . .
Comparing national and other character-string
operands . . . . . . . . . . . . . .
Comparing national data and
alphanumeric-group operands . . . . . . .
Coding for use of DBCS support . . . . . . .
Declaring DBCS data . . . . . . . . . .
Using DBCS literals . . . . . . . . . .
Testing for valid DBCS characters . . . . .
Processing alphanumeric data items that contain
DBCS data . . . . . . . . . . . . .
130
132
133
134
135
135
136
137
137
139
141
142
142
143
144
144
144
145
145
146
151
152
153
153
154
154
154
155
155
156
157
157
Chapter 8. Processing files . . . . . 159
File organization and input-output devices
.
.
. 159
Choosing file organization and access mode
Format for coding input and output . .
Allocating files . . . . . . . . . .
Checking for input or output errors . . .
.
.
.
.
.
.
.
.
.
.
.
.
161
162
163
164
Chapter 9. Processing QSAM files . . 165
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. . . . . .
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 . . . . . . . . .
Defining and allocating QSAM files . . . . .
Retrieving QSAM files . . . . . . . . .
Ensuring that file attributes match your
program . . . . . . . . . . . . . .
Using striped extended-format QSAM data sets
Allocation of buffers for QSAM files. . . . .
Accessing z/OS UNIX files using QSAM . . . .
Processing QSAM ASCII files on tape . . . . .
Chapter 10. Processing VSAM files
|
165
166
173
176
176
177
178
178
178
179
180
181
181
183
184
187
187
188
189
191
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 . . . .
Example: password protection for a VSAM
indexed file . . . . . . . . . . . . .
Working with VSAM data sets under z/OS and
z/OS UNIX . . . . . . . . . . . . . .
Defining VSAM files . . . . . . . . . .
Creating alternate indexes . . . . . . . .
Allocating VSAM files . . . . . . . . .
Sharing VSAM files through RLS . . . . . .
Allocation of record areas for VSAM files . . . .
Improving VSAM performance . . . . . . .
192
193
194
195
196
197
198
199
201
202
205
205
206
207
207
207
208
209
209
210
210
211
213
215
216
217
Chapter 11. Processing line-sequential
files . . . . . . . . . . . . . . . 219
Defining line-sequential files and records in
COBOL . . . . . . . . . . . . . . .
Describing the structure of a line-sequential file
Control characters in line-sequential files . . .
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 12. Sorting and merging files
219
220
220
221
221
222
222
223
223
224
225
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 . . . . . . . .
Example: coding the output procedure when
using DFSORT . . . . . . . . . . . .
Restrictions on input and output procedures . . .
Defining sort and merge data sets . . . . . .
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 . . . .
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 . . . . . .
FASTSRT requirements for sort input and
output files . . . . . . . . . . . . .
Checking for sort errors with NOFASTSRT . . .
Controlling sort behavior . . . . . . . . .
Changing DFSORT defaults with control
statements . . . . . . . . . . . . .
Allocating storage for sort or merge operations
Allocating space for sort files . . . . . . .
Using checkpoint/restart with DFSORT . . . .
Sorting under CICS . . . . . . . . . . .
CICS SORT application restrictions . . . . .
226
226
227
228
228
229
230
231
231
232
232
233
234
235
235
236
236
237
237
238
238
240
240
241
242
243
243
244
244
Chapter 13. Handling errors . . . . . 245
Requesting dumps . . . . . . . . . .
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) . .
.
.
.
.
245
246
246
247
247
. 249
Contents
v
Coding ERROR declaratives . . . . . .
Using file status keys . . . . . . . . .
Example: file status key . . . . . . . .
Using VSAM status 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 . . . . .
Chapter 15. Compiling under z/OS
UNIX . . . . . . . . . . . . . . . 291
. 250
. 251
. 252
253
. 254
. 255
. 255
. 256
. 256
Setting environment variables under z/OS UNIX
Specifying compiler options under z/OS UNIX .
Compiling and linking with the cob2 command
Creating a DLL under z/OS UNIX . . . .
Example: using cob2 to compile and link under
z/OS UNIX . . . . . . . . . . . .
cob2 syntax and options . . . . . . . .
cob2 input and output files . . . . . . .
Compiling using scripts . . . . . . . . .
Part 2. Compiling and debugging
your program . . . . . . . . . . 259
Chapter 14. Compiling under z/OS
vi
Compiling, linking, and running OO applications
under z/OS UNIX. . . . . . . . . . . .
Compiling OO applications under z/OS UNIX
Preparing OO applications under z/OS UNIX
Example: compiling and linking a COBOL class
definition under z/OS UNIX . . . . . . .
Running OO applications under z/OS UNIX
Compiling, linking, and running OO applications
in JCL or TSO/E . . . . . . . . . . . .
Compiling OO applications in JCL or TSO/E
Preparing and running OO applications in JCL
or TSO/E. . . . . . . . . . . . . .
Example: compiling, linking, and running an
OO application using JCL . . . . . . . .
Using Java SDKs for z/OS . . . . . . . . .
Object-oriented syntax, and Java 5 or Java 6 . .
261
262
267
269
269
270
271
273
273
275
276
276
277
277
277
278
278
|
|
281
281
282
283
284
284
285
286
287
287
288
288
Enterprise COBOL for z/OS, V5.1 Programming Guide
295
295
297
298
299
299
300
301
302
303
304
305
306
308
309
Chapter 17. Compiler options . . . . 311
278
279
280
281
.
.
.
.
Chapter 16. Compiling, linking, and
running OO applications . . . . . . 299
261
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 z/OS . .
Defining the source code data set (SYSIN) . . .
Defining a compiler-option data set (SYSOPTF)
Specifying source libraries (SYSLIB) . . . . .
Defining the output data set (SYSPRINT) . . .
Directing compiler messages to your terminal
(SYSTERM) . . . . . . . . . . . . .
Creating object code (SYSLIN or SYSPUNCH)
Defining an associated-data file (SYSADATA)
Defining the Java-source output file (SYSJAVA)
Defining the library-processing output file
(SYSMDECK) . . . . . . . . . . . .
Specifying compiler options under z/OS . . . .
Specifying compiler options in the PROCESS
(CBL) statement . . . . . . . . . . .
Example: specifying compiler options using JCL
Example: specifying compiler options under
TSO . . . . . . . . . . . . . . .
Compiler options and compiler output under
z/OS . . . . . . . . . . . . . . .
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 messages . . . .
Messages and listings for compiler-detected
errors . . . . . . . . . . . . . . .
Format of compiler diagnostic messages . . .
Severity codes for compiler diagnostic messages
291
. 292
293
. 294
|
Option settings for Standard
conformance. . . . . .
Conflicting compiler options
ADATA . . . . . . .
ADV . . . . . . . .
AFP . . . . . . . .
ARCH. . . . . . . .
ARITH . . . . . . .
AWO . . . . . . . .
BLOCK0 . . . . . . .
BUFSIZE . . . . . . .
CICS . . . . . . . .
CODEPAGE . . . . . .
COMPILE . . . . . .
CURRENCY . . . . . .
DATA . . . . . . . .
DBCS . . . . . . . .
DECK . . . . . . . .
DIAGTRUNC . . . . .
DISPSIGN . . . . . .
DLL . . . . . . . .
DUMP . . . . . . .
DYNAM . . . . . . .
EXIT . . . . . . . .
EXPORTALL . . . . .
FASTSRT . . . . . . .
FLAG . . . . . . . .
FLAGSTD . . . . . .
COBOL 85
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
313
314
315
315
316
317
318
319
319
321
321
322
325
325
326
327
328
328
329
330
331
332
332
335
335
336
337
|
|
|
HGPR . . . . . . . . .
INTDATE . . . . . . .
LANGUAGE . . . . . .
LINECOUNT . . . . . .
LIST . . . . . . . . .
MAP . . . . . . . . .
MAXPCF . . . . . . . .
MDECK . . . . . . . .
NAME . . . . . . . .
NSYMBOL . . . . . . .
NUMBER . . . . . . .
NUMPROC . . . . . . .
OBJECT . . . . . . . .
OFFSET . . . . . . . .
OPTFILE . . . . . . . .
OPTIMIZE . . . . . . .
OUTDD . . . . . . . .
PGMNAME . . . . . . .
PGMNAME(COMPAT) . .
PGMNAME(LONGUPPER).
PGMNAME(LONGMIXED)
Usage notes . . . . . .
QUOTE/APOST . . . . .
RENT . . . . . . . . .
RMODE . . . . . . . .
SEQUENCE . . . . . . .
SIZE . . . . . . . . .
SOURCE . . . . . . . .
SPACE . . . . . . . .
SQL . . . . . . . . .
SQLCCSID . . . . . . .
SSRANGE . . . . . . .
STGOPT . . . . . . . .
TERMINAL . . . . . . .
TEST . . . . . . . . .
THREAD . . . . . . . .
TRUNC . . . . . . . .
TRUNC example 1 . . .
TRUNC example 2 . . .
VBREF . . . . . . . .
WORD . . . . . . . .
XREF . . . . . . . . .
ZWB . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
338
339
340
341
341
342
343
344
345
346
347
347
348
349
350
351
352
353
353
354
354
354
355
355
357
358
358
359
359
360
361
362
363
363
364
366
368
369
370
370
371
371
373
Chapter 18. Compiler-directing
statements . . . . . . . . . . . . 375
Chapter 19. Debugging . . . . . . . 379
Debugging with source language . . . . .
Tracing program logic . . . . . . .
Finding and handling input-output errors .
Validating data . . . . . . . . . .
Moving, initializing or setting uninitialized
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
. .
. .
. .
. .
data
. .
. .
. .
. .
. .
. .
379
380
381
381
382
382
384
384
385
385
386
Finding program entity definitions and
references . . . . . . . . . .
Listing data items . . . . . . . .
Using the debugger . . . . . . . .
Getting listings . . . . . . . . . .
Example: short listing . . . . . .
Example: SOURCE and NUMBER output
Example: MAP output . . . . . .
Reading LIST output . . . . . . .
Example: XREF output: data-name
cross-references. . . . . . . . .
Example: OFFSET compiler output . .
Example: VBREF compiler output . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
388
388
389
390
392
394
395
399
.
.
.
.
.
.
. 414
. 417
. 418
Part 3. Targeting COBOL programs
for certain environments . . . . . 419
Chapter 20. Developing COBOL
programs for CICS . . . . . . . . . 421
Coding COBOL programs to run under CICS
Getting the system date under CICS. . .
Calling to or from COBOL programs . .
Determining the success of ECI calls. . .
Compiling with the CICS option . . . . .
Separating CICS suboptions . . . . .
Integrated CICS translator . . . . . .
Using the separate CICS translator . . . .
CICS reserved-word table . . . . . . .
Handling errors by using CICS HANDLE . .
Example: handling errors by using CICS
HANDLE . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
421
423
424
425
425
427
427
428
430
430
.
. 431
Chapter 21. Programming for a DB2
environment . . . . . . . . . . . . 433
DB2 coprocessor . . . . . . . . . . . .
Coding SQL statements . . . . . . . . . .
Using SQL INCLUDE with the DB2 coprocessor
Using character data in SQL statements . . .
Using national decimal data in SQL statements
Using national group items in SQL statements
Using binary items in SQL statements . . . .
Determining the success of SQL statements . .
Compiling with the SQL option . . . . . . .
Separating DB2 suboptions . . . . . . . .
COBOL and DB2 CCSID determination. . . . .
Code-page determination for string host
variables in SQL statements . . . . . . .
Programming with the SQLCCSID or
NOSQLCCSID option . . . . . . . . .
Differences in how the DB2 precompiler and
coprocessor behave . . . . . . . . . . .
Period at the end of EXEC SQL INCLUDE
statements . . . . . . . . . . . . .
EXEC SQL INCLUDE and nested COPY
REPLACING . . . . . . . . . . . .
EXEC SQL and REPLACE or COPY
REPLACING . . . . . . . . . . . .
Source code after an END-EXEC statement . .
Multiple definitions of host variables . . . .
Contents
433
434
435
435
436
437
437
437
438
439
439
440
440
441
441
442
442
442
442
vii
EXEC SQL statement continuation lines . .
Bit-data host variables . . . . . . . .
SQL-INIT-FLAG . . . . . . . . . .
Choosing the DYNAM or NODYNAM compiler
option . . . . . . . . . . . . . . .
. 443
. 443
. 443
. 443
Chapter 22. Developing COBOL
programs for IMS. . . . . . . . . . 445
Compiling and linking COBOL programs for
running under IMS . . . . . . . . . . .
Using object-oriented COBOL and Java under IMS
Calling a COBOL method from a Java
application under IMS . . . . . . . . .
Building a mixed COBOL-Java application that
starts with COBOL . . . . . . . . . .
Writing mixed-language IMS applications . . .
445
446
446
447
448
Chapter 23. Running COBOL
programs under z/OS UNIX . . . . . 451
Running in z/OS UNIX environments . . . .
Setting and accessing environment variables . .
Setting environment variables that affect
execution . . . . . . . . . . . . .
Runtime environment variables . . . . .
Example: setting and accessing environment
variables . . . . . . . . . . . . .
Calling UNIX/POSIX APIs . . . . . . . .
Accessing main program parameters under z/OS
UNIX . . . . . . . . . . . . . . .
Example: accessing main program parameters
under z/OS UNIX. . . . . . . . . .
. 451
. 452
. 453
. 453
. 454
. 454
. 456
. 457
Part 4. Structuring complex
applications . . . . . . . . . . . 459
Chapter 24. Using subprograms . . . 461
Main programs, subprograms, and calls . . . .
Ending and reentering main programs or
subprograms . . . . . . . . . . . . .
Transferring control to another program . . . .
Making static calls. . . . . . . . . . .
Making dynamic calls . . . . . . . . .
AMODE switching . . . . . . . . . .
Performance considerations of static and
dynamic calls . . . . . . . . . . . .
Making both static and dynamic calls . . . .
Examples: static and dynamic CALL statements
Calling nested COBOL programs . . . . . .
Making recursive calls . . . . . . . . . .
Calling to and from object-oriented programs . .
Using procedure and function pointers . . . . .
Deciding which type of pointer to use . . . .
Calling alternate entry points . . . . . . .
Making programs reentrant . . . . . . . .
461
462
463
464
465
468
469
470
470
472
475
475
476
477
477
478
Chapter 25. Sharing data . . . . . . 481
Passing data . . . . . . . . . . . . .
Describing arguments in the calling program
Describing parameters in the called program
viii
. 481
483
484
Enterprise COBOL for z/OS, V5.1 Programming Guide
Testing for OMITTED arguments . . . . .
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 . . . . . .
Using 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 . . . . . .
Accessing main program parameters under z/OS
Example: accessing main program parameters
under z/OS . . . . . . . . . . . .
. 484
. 485
.
.
.
.
.
.
.
.
.
.
.
.
486
486
486
487
490
490
490
491
491
491
492
495
. 496
Chapter 26. Creating a DLL or a DLL
application . . . . . . . . . . . . 497
Dynamic link libraries (DLLs) . . . . . . . .
Compiling programs to create DLLs . . . . . .
Linking DLLs . . . . . . . . . . . . .
Example: sample JCL for a procedural DLL
application . . . . . . . . . . . . . .
Using CALL identifier with DLLs . . . . . .
Search order for DLLs in the z/OS UNIX file
system . . . . . . . . . . . . . .
Using DLL linkage and dynamic calls together . .
Using procedure or function 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 . . . .
497
498
499
500
501
501
502
503
504
504
506
506
Chapter 27. Preparing COBOL
programs for multithreading . . . . . 509
Multithreading . . . . . . . . . . . .
Choosing THREAD to support multithreading .
Transferring control to multithreaded programs .
Ending multithreaded programs . . . . . .
Processing files with multithreading . . . . .
File-definition (FD) storage . . . . . . .
Serializing file access with multithreading . .
Example: usage patterns of file input and
output with multithreading. . . . . . .
Handling COBOL limitations with multithreading
.
.
.
.
.
.
.
510
511
511
512
512
513
513
. 514
515
Part 5. Using XML and COBOL
together . . . . . . . . . . . . . 517
Chapter 28. Processing XML input
519
XML parser in COBOL . . . . . . . . .
Accessing XML documents . . . . . . . .
Parsing XML documents . . . . . . . .
Writing procedures to process XML . . . .
XML events . . . . . . . . . . . .
Transforming XML text to COBOL data items
.
.
.
.
.
520
522
522
524
525
529
|
|
Parsing XML documents with validation . . .
Parsing XML documents one segment at a time
Handling splits using the XML-INFORMATION
special register . . . . . . . . . . . .
The encoding of XML documents. . . . . . .
XML input document encoding . . . . . .
Parsing XML documents encoded in UTF-8 . .
Handling XML PARSE exceptions . . . . . .
How the XML parser handles errors. . . . .
Handling encoding conflicts . . . . . . .
Terminating XML parsing . . . . . . . . .
XML PARSE examples . . . . . . . . . .
Example: parsing a simple document . . . .
Example: program for processing XML . . . .
Example: parsing an XML document that uses
namespaces . . . . . . . . . . . . .
Example: parsing an XML document one
segment at a time . . . . . . . . . . .
Example: parsing XML documents with
validation . . . . . . . . . . . . .
Chapter 29. Producing XML output
530
534
536
537
538
540
542
542
543
544
544
545
545
549
551
553
557
Generating XML output . . . . . . . . . .
Controlling the encoding of generated XML output
Handling XML GENERATE exceptions . . . . .
Example: generating XML . . . . . . . . .
Program XGFX . . . . . . . . . . . .
Program Pretty . . . . . . . . . . . .
Output from program XGFX . . . . . . .
Enhancing XML output . . . . . . . . . .
Example: enhancing XML output . . . . . .
557
562
563
564
564
566
569
569
569
Part 6. Developing object-oriented
programs . . . . . . . . . . . . 573
Chapter 30. Writing object-oriented
programs . . . . . . . . . . . . . 575
Example: accounts. . . . . . . . . . .
Subclasses . . . . . . . . . . . .
Defining a class . . . . . . . . . . .
CLASS-ID paragraph for defining a class . .
REPOSITORY paragraph for defining a class
WORKING-STORAGE SECTION for defining
class instance data . . . . . . . . . .
Example: defining a class . . . . . . .
Defining a class instance method . . . . . .
METHOD-ID paragraph for defining a class
instance method . . . . . . . . . .
INPUT-OUTPUT SECTION for defining a class
instance method . . . . . . . . . .
DATA DIVISION for defining a class instance
method . . . . . . . . . . . . .
PROCEDURE DIVISION for defining a class
instance method . . . . . . . . . .
Overriding an instance method . . . . .
Overloading an instance method . . . . .
Coding attribute (get and set) methods . . .
Example: defining a method . . . . . .
Defining a client . . . . . . . . . . .
.
.
.
.
576
577
578
580
580
. 582
. 583
. 583
. 584
. 585
. 585
.
.
.
.
.
.
586
587
588
589
590
592
REPOSITORY paragraph for defining a client
DATA DIVISION for defining a client . . . .
Comparing and setting object references . . .
Invoking methods (INVOKE) . . . . . . .
Creating and initializing instances of classes . .
Freeing instances of classes . . . . . . . .
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
subclass instance data . . . . . . . . .
Defining a subclass instance method . . . .
Example: defining a subclass (with methods)
Defining a factory section . . . . . . . . .
WORKING-STORAGE SECTION for defining
factory data . . . . . . . . . . . . .
Defining a factory method . . . . . . . .
Example: defining a factory (with methods) . .
Wrapping procedure-oriented COBOL programs
Structuring OO applications . . . . . . . .
Examples: COBOL applications that run using
the java command . . . . . . . . . . .
593
594
595
596
601
603
603
604
605
605
606
606
607
608
609
609
612
617
618
618
Chapter 31. Communicating with Java
methods . . . . . . . . . . . . . 621
Accessing JNI services . . . . . . . . . .
Handling Java exceptions . . . . . . . .
Managing local and global references . . . .
Java access controls . . . . . . . . . .
Sharing data with Java . . . . . . . . . .
Coding interoperable data types in COBOL and
Java . . . . . . . . . . . . . . .
Declaring arrays and strings for Java . . . .
Manipulating Java arrays . . . . . . . .
Manipulating Java strings . . . . . . . .
Example: J2EE client written in COBOL . . . .
COBOL client (ConverterClient.cbl) . . . . .
Java client (ConverterClient.java) . . . . . .
621
623
624
626
626
626
627
629
631
633
634
636
Part 7. Specialized processing . . 639
Chapter 32. Interrupts and
checkpoint/restart . . . . . . . . . 641
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 . . . . . . . . . . . . . . .
Contents
641
642
643
643
644
644
645
645
646
647
647
647
648
648
ix
Part 8. Improving performance and
productivity . . . . . . . . . . . 651
Chapter 33. Tuning your program . . . 653
|
Using an optimal programming style . . .
Using structured programming . . . .
Factoring expressions. . . . . . . .
Using symbolic constants . . . . . .
Choosing efficient data types . . . . . .
Choosing efficient computational data items
Using consistent data types. . . . . .
Making arithmetic expressions efficient . .
Making exponentiations efficient . . . .
Handling tables efficiently . . . . . . .
Optimization of table references . . . .
Optimizing your code . . . . . . . .
Optimization . . . . . . . . . .
Choosing compiler features to enhance
performance . . . . . . . . . . . .
Performance-related compiler options . .
Evaluating performance . . . . . . .
Running efficiently with CICS, IMS, or VSAM
Choosing static or dynamic calls . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
654
654
654
655
655
655
656
656
656
657
658
659
659
.
.
.
.
.
.
.
.
.
.
660
661
664
665
666
Chapter 34. Simplifying coding . . . . 667
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 . . . . . . . . . . . . .
. 667
. 668
. 669
. 670
. 671
. 672
Part 9. Appendixes . . . . . . . . 675
Appendix A. Intermediate results and
arithmetic precision . . . . . . . . 677
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 . . . .
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 . . . . . . . . . . . . .
Arithmetic expressions in nonarithmetic statements
x
678
679
679
679
680
681
681
682
682
682
683
684
685
685
685
Enterprise COBOL for z/OS, V5.1 Programming Guide
Appendix B. Converting double-byte
character set (DBCS) data . . . . . . 687
DBCS notation . . . . . . . . . . . . .
Alphanumeric to DBCS data conversion
(IGZCA2D) . . . . . . . . . . . . . .
IGZCA2D syntax . . . . . . . . . . .
IGZCA2D return codes . . . . . . . . .
Example: IGZCA2D . . . . . . . . . .
DBCS to alphanumeric data conversion (IGZCD2A)
IGZCD2A syntax . . . . . . . . . . .
IGZCD2A return codes . . . . . . . . .
Example: IGZCD2A . . . . . . . . . .
Appendix C. XML reference material
XML PARSE exceptions . . .
XML GENERATE exceptions .
.
.
.
.
.
.
.
.
.
.
687
687
688
688
689
690
690
691
691
693
.
.
. 693
. 695
Appendix D. EXIT compiler option . . 697
Using the user-exit work area . . . . . .
Calling from exit modules . . . . . . .
Processing of INEXIT. . . . . . . . .
INEXIT parameters . . . . . . . .
Processing of LIBEXIT . . . . . . . .
Processing of LIBEXIT with nested COPY
statements . . . . . . . . . . .
LIBEXIT parameters . . . . . . . .
Processing of PRTEXIT . . . . . . . .
PRTEXIT parameters . . . . . . . .
Processing of ADEXIT . . . . . . . .
ADEXIT parameters . . . . . . . .
Processing of MSGEXIT . . . . . . . .
MSGEXIT parameters . . . . . . .
Customizing compiler-message severities .
Example: MSGEXIT user exit . . . . .
Error handling for exit modules . . . . .
Using the EXIT compiler option with CICS and
SQL statements . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
697
698
698
698
699
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
700
701
702
703
703
704
705
705
706
709
713
.
. 714
Appendix E. JNI.cpy copybook . . . . 717
Appendix F. COBOL SYSADATA file
contents . . . . . . . . . . . . . 723
Compiler options that affect the SYSADATA file
SYSADATA record types . . . . . . . .
Example: SYSADATA . . . . . . . . .
SYSADATA record descriptions . . . . . .
Common header section . . . . . . . . .
Job identification record: X'0000' . . . . . .
ADATA identification record: X'0001' . . . .
Compilation unit start | end record: X'0002' . .
Options record: X'0010' . . . . . . . . .
External symbol record: X'0020' . . . . . .
Parse tree record: X'0024' . . . . . . . .
Token record: X'0030' . . . . . . . . . .
Source error record: X'0032'. . . . . . . .
Source record: X'0038' . . . . . . . . .
COPY REPLACING record: X'0039' . . . . .
Symbol record: X'0042' . . . . . . . . .
Symbol cross-reference record: X'0044' . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
723
724
725
726
727
729
730
730
731
740
740
756
770
770
771
772
783
Nested program record:
Library record: X'0060'
Statistics record: X'0090'
EVENTS record: X'0120'
X'0046'
. . .
. . .
. . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
785
785
786
786
Preparing to run IGYTSALE . . . .
Language elements and concepts that are
illustrated . . . . . . . . . . .
.
.
. 804
.
.
. 805
Notices . . . . . . . . . . . . . . 811
Appendix G. Using sample programs
IGYTCARA: batch application . . . .
Input data for IGYTCARA . . . .
Report produced by IGYTCARA . .
Preparing to run IGYTCARA . . .
IGYTCARB: interactive program . . .
Preparing to run IGYTCARB . . .
IGYTSALE: nested program application
Input data for IGYTSALE . . . .
Reports produced by IGYTSALE . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
791
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
791
792
793
794
795
796
798
799
801
Trademarks .
.
.
.
.
.
.
.
.
.
.
.
.
. 813
Glossary . . . . . . . . . . . . . 815
List of resources . . . . . . . . . . 847
Enterprise COBOL for z/OS
Related publications . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. 847
. 847
Index . . . . . . . . . . . . . . . 849
Contents
xi
xii
Enterprise COBOL for z/OS, V5.1 Programming Guide
Tables
|
|
|
|
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
39.
40.
FILE-CONTROL entries . . . . . . . . 6
FILE SECTION entries . . . . . . . . 13
Assignment to data items in a program
27
Effect of RMODE and RENT compiler
options on the RMODE attribute . . . . . 41
Ranges in value of COMP-5 data items
51
Internal representation of numeric items
53
NUMCLS(PRIM) and valid signs . . . . . 57
NUMCLS(ALT) and valid signs . . . . . 57
Order of evaluation of arithmetic operators
59
Numeric intrinsic functions . . . . . . . 60
Compatibility of math intrinsic functions and
callable services . . . . . . . . . . . 61
INTDATE(LILIAN) and compatibility of date
intrinsic functions and callable services. . . 62
INTDATE(ANSI) and compatibility of date
intrinsic functions and callable services. . . 62
Hexadecimal values of the euro sign . . . . 67
COBOL statements and national data
130
Intrinsic functions and national character
data. . . . . . . . . . . . . . . 132
National group items that are processed
with group semantics . . . . . . . . 141
Encoding and size of alphanumeric, DBCS,
and national data . . . . . . . . . . 141
Summary of file organizations, access
modes, and record formats of COBOL files . 161
QSAM file allocation. . . . . . . . . 182
Maximum record length of QSAM files
185
Comparison of VSAM, COBOL, and
non-VSAM terminology. . . . . . . . 191
Comparison of VSAM data-set types
193
VSAM file organization, access mode, and
record format . . . . . . . . . . . 194
Definition of VSAM fixed-length records
198
Definition of VSAM variable-length records 199
I/O statements for VSAM sequential files
200
I/O statements for VSAM relative and
indexed files . . . . . . . . . . . 201
Statements to load records into a VSAM file 204
Statements to update records in a VSAM
file . . . . . . . . . . . . . . . 206
Methods for improving VSAM performance 217
Methods for checking for sort errors with
NOFASTSRT . . . . . . . . . . . 240
Methods for controlling sort behavior
240
Compiler data sets . . . . . . . . . 273
Block size of fixed-length compiler data sets 275
Block size of variable-length compiler data
sets . . . . . . . . . . . . . . . 275
Types of compiler output under z/OS
281
Severity codes for compiler diagnostic
messages . . . . . . . . . . . . . 288
Input files to the cob2 command . . . . . 297
Output files from the cob2 command
297
© Copyright IBM Corp. 1991, 2013
|
|
|
|
|
|
|
41. Commands for compiling and linking a
class definition . . . . . . . . . . .
42. java command options for customizing the
JVM . . . . . . . . . . . . . .
43. Compiler options . . . . . . . . . .
44. Mutually exclusive compiler options
45. EBCDIC multibyte coded character set
identifiers . . . . . . . . . . . .
46. DISPLAY output with the DISPSIGN(SEP)
option or the DISPSIGN(SEP) option specified: .
47. Values of the LANGUAGE compiler option
48. Mapping of deprecated options to new
options . . . . . . . . . . . . .
49. Severity levels of compiler messages
50. Using compiler options to get listings
51. Terms used in MAP output . . . . . .
52. Symbols used in LIST and MAP output
53. Compiler options in the INFO BYTE section
54. Signature information bytes . . . . . .
55. Calls between COBOL and assembler under
CICS . . . . . . . . . . . . . .
56. Compiler options required for the integrated
CICS translator . . . . . . . . . . .
57. Compiler options required for the separate
CICS translator . . . . . . . . . . .
58. TRUNC compiler options recommended for
the separate CICS translator . . . . . .
59. Compiler options required with the DB2
coprocessor . . . . . . . . . . . .
60. Samples with POSIX function calls . . . .
61. Effects of termination statements. . . . .
62. Methods for passing data in the CALL
statement . . . . . . . . . . . . .
63. Compiler options for DLL applications
64. Binder options for DLL applications
65. Special registers used by the XML parser
66. Result of processing-procedure changes to
XML-CODE . . . . . . . . . . . . .
67. Coded character sets for XML documents
68. Hexadecimal values of white-space
characters. . . . . . . . . . . . .
69. Aliases for XML encoding declarations
70. Hexadecimal values of special characters for
various EBCDIC CCSIDs . . . . . . .
71. XML events and special registers . . . .
72. XML events and special registers . . . .
73. Encoding of generated XML if the
ENCODING phrase is omitted . . . . .
74. Structure of class definitions . . . . . .
75. Structure of instance method definitions
76. Structure of COBOL clients . . . . . .
77. Conformance of arguments in a COBOL
client . . . . . . . . . . . . . .
78. Conformance of the returned data item in a
COBOL client . . . . . . . . . . .
79. Structure of factory definitions . . . . .
301
302
311
314
324
329
340
352
386
390
397
398
401
402
424
426
429
429
438
455
462
482
498
499
524
527
537
538
540
540
545
550
563
578
584
592
598
600
608
xiii
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
95.
96.
97.
98.
99.
100.
101.
102.
103.
104.
105.
xiv
Structure of factory method definitions
JNI services for local and global references
Interoperable data types in COBOL and Java
Interoperable arrays and strings in COBOL
and Java . . . . . . . . . . . . .
Noninteroperable array types in COBOL
and Java . . . . . . . . . . . . .
JNI array services . . . . . . . . . .
Services that convert between jstring
references and national data . . . . . .
Services that convert between jstring
references and alphanumeric data . . . .
Performance-related compiler options
Performance-tuning worksheet . . . . .
Language Environment callable services
IGZCA2D return codes . . . . . . . .
IGZCD2A return codes . . . . . . . .
Reason codes for XML PARSE exceptions
that are unique to Enterprise COBOL . . .
XML GENERATE exceptions . . . . . .
Layout of the user-exit work area . . . .
INEXIT processing . . . . . . . . .
INEXIT parameters . . . . . . . . .
LIBEXIT processing . . . . . . . . .
LIBEXIT processing with nonnested COPY
statements . . . . . . . . . . . .
LIBEXIT processing with nested COPY
statements . . . . . . . . . . . .
LIBEXIT parameters . . . . . . . . .
PRTEXIT processing . . . . . . . . .
PRTEXIT parameters . . . . . . . . .
ADEXIT processing . . . . . . . . .
ADEXIT parameters . . . . . . . . .
610
625
627
106.
107.
108.
109.
627
628
629
631
110.
111.
112.
113.
114.
693
695
697
698
699
699
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
700
128.
701
701
702
703
704
704
129.
632
661
664
670
688
691
Enterprise COBOL for z/OS, V5.1 Programming Guide
130.
131.
132.
MSGEXIT processing . . . . . . . .
MSGEXIT parameters . . . . . . . .
FIPS (FLAGSTD) message categories . . . .
Actions possible in exit modules for CICS
and SQL statements . . . . . . . . .
SYSADATA record types . . . . . . .
SYSADATA common header section
SYSADATA job identification record
ADATA identification record . . . . . .
SYSADATA compilation unit start | end
record . . . . . . . . . . . . . .
SYSADATA options record . . . . . . .
SYSADATA external symbol record
SYSADATA parse tree record . . . . . .
SYSADATA token record . . . . . . .
SYSADATA source error record . . . . .
SYSADATA source record . . . . . . .
SYSADATA COPY REPLACING record
SYSADATA symbol record . . . . . . .
SYSADATA symbol cross-reference record
SYSADATA nested program record . . . .
SYSADATA library record . . . . . . .
SYSADATA statistics record . . . . . .
SYSADATA EVENTS TIMESTAMP record
layout . . . . . . . . . . . . . .
SYSADATA EVENTS PROCESSOR record
layout . . . . . . . . . . . . . .
SYSADATA EVENTS FILE END record
layout . . . . . . . . . . . . . .
SYSADATA EVENTS PROGRAM record
layout . . . . . . . . . . . . . .
SYSADATA EVENTS FILE ID record layout
SYSADATA EVENTS ERROR record layout
705
706
708
715
724
727
729
730
730
731
740
740
756
770
770
771
772
783
785
785
786
786
787
787
788
788
788
Preface
About this information
|
|
|
|
This information is for COBOL programmers and system programmers. It helps
you understand how to use Enterprise COBOL for z/OS® to compile COBOL
programs. It also describes the operating system features that you might need to
optimize program performance or handle errors.
|
|
For information about COBOL language, and for references needed to write a
program for an IBM COBOL compiler, see the Enterprise COBOL Language Reference.
|
|
Important: Enterprise COBOL for z/OS is referred to as Enterprise COBOL
throughout this information.
How this information will help you
This information will help you write and compile Enterprise COBOL programs. It
will also help you define object-oriented classes and methods, invoke methods, and
refer to objects in your programs.
This information assumes experience in developing application programs and
some knowledge of COBOL. It focuses on using Enterprise COBOL to meet your
programming objectives and not on the definition of the COBOL language. For
complete information about COBOL syntax, see the IBM Enterprise COBOL
Language Reference.
For information about migrating programs to Enterprise COBOL, see the IBM
Enterprise COBOL Migration Guide.
IBM z/OS Language Environment® provides the runtime environment and runtime
services that are required to run Enterprise COBOL programs. You can find
information about link-editing and running programs in the IBM z/OS Language
Environment Programming Guide and IBM z/OS Language Environment Programming
Reference.
For a comparison of commonly used Enterprise COBOL and Language
Environment terms, see “Comparison of commonly used terms” on page xvi.
Abbreviated terms
Certain terms are used in a shortened form in this information. Abbreviations for
the product names used most frequently are listed alphabetically in the following
table.
Term used
CICS
®
Long form
CICS Transaction Server
Enterprise COBOL
IBM Enterprise COBOL for z/OS
Language Environment
IBM z/OS Language Environment
MVS
MVS/ESA
z/OS UNIX
z/OS UNIX System Services
© Copyright IBM Corp. 1991, 2013
xv
In addition to these abbreviated terms, the term "Standard COBOL 85" is used to
refer to the combination of the following standards:
v ISO 1989:1985, Programming languages - COBOL
v ISO/IEC 1989/AMD1:1992, Programming languages - COBOL: Intrinsic function
module
v ISO/IEC 1989/AMD2:1994, Programming languages - Correction and
clarification amendment for COBOL
v ANSI INCITS 23-1985, Programming Languages - COBOL
v ANSI INCITS 23a-1989, Programming Languages - Intrinsic Function Module for
COBOL
v ANSI INCITS 23b-1993, Programming Language - Correction Amendment for
COBOL
The ISO standards are identical to the American National standards.
Other terms, if not commonly understood, are shown in italics the first time that
they appear, and are listed in the glossary.
Comparison of commonly used terms
To better understand the terms used throughout the IBM z/OS Language
Environment and IBM Enterprise COBOL for z/OS information, and to understand
which terms are meant to be equivalent, see the following table.
Language Environment term
Enterprise COBOL equivalent
Aggregate
Group item
Array
A table created using the OCCURS clause
Array element
Table element
Enclave
Run unit
External data
WORKING-STORAGE data defined using the 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
How to read syntax diagrams
Use the following description to read the syntax diagrams in this information.
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 syntax diagram.
The ---> symbol indicates that the syntax diagram is continued on the next line.
The >--- symbol indicates that the syntax diagram is continued from the
previous line.
The --->< symbol indicates the end of a syntax diagram.
xvi
Enterprise COBOL for z/OS, V5.1 Programming Guide
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):
required_item
v Optional items appear below the main path:
required_item
optional_item
v 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:
required_item
required_choice1
required_choice2
If choosing one of the items is optional, the entire stack appears below the main
path:
required_item
optional_choice1
optional_choice2
If one of the items is the default, it appears above the main path and the
remaining choices are shown below:
default_choice
required_item
optional_choice
optional_choice
v An arrow returning to the left, above the main line, indicates an item that can be
repeated:
Preface
xvii
required_item repeatable_item
If the repeat arrow contains a comma, you must separate repeated items with a
comma:
,
required_item repeatable_item
v Keywords appear in uppercase (for example, FROM). They must be spelled exactly
as shown. Variables appear in lowercase italics (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 information shows numerous examples of sample COBOL statements,
program fragments, and small programs to illustrate the coding techniques being
described. 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.
To more clearly separate some examples from the explanatory text, they are
presented in a monospace font.
COBOL keywords and compiler options that appear in text are generally shown in
SMALL UPPERCASE. Other terms such as program variable names are sometimes
shown in an italic font for clarity.
|
Additional documentation and support
|
|
|
IBM Enterprise COBOL for z/OS provides Portable Document Format (PDF)
versions of the entire library for this version and for previous versions on the
product site at www.ibm.com/software/awdtools/cobol/zos/library/.
|
|
|
Support information is also available on the product site at http://www.ibm.com/
support/entry/portal/Overview/Software/Rational/Enterprise_COBOL_for_z~OS
.
Summary of changes
This section lists the major changes that have been made to this document for
Enterprise COBOL in Version 5 Release 1. The changes that are described in this
information have an associated cross-reference for your convenience. The latest
technical changes are marked by a vertical bar (|) in the left margin in the PDF
version.
|
Other changes for Version 5 Release 1 of Enterprise COBOL are described in the
Enterprise COBOL Language Reference.
|
|
xviii
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Version 5 Release 1
v
Several changes are made to compiler options:
– The following compiler options are new:
- AFP(VOLATILE | NOVOLATILE) (“AFP” on page 316)
- ARCH(n) (“ARCH” on page 317)
- DISPSIGN(SEP | COMPAT) (“DISPSIGN” on page 329)
- HGPR(PRESERVE | NOPRESERVE) (“HGPR” on page 338)
- MAXPCF(n) (“MAXPCF” on page 343)
- STGOPT | NOSTGOPT(“STGOPT” on page 363)
– The following compiler options are modified:
- The MDECK option no longer has a dependency on the LIB option.
(“MDECK” on page 344)
- The MIG suboption of the NUMPROC compiler option is no longer supported.
(“NUMPROC” on page 347)
- The compiled-in range checks cannot be disabled at run time using the
runtime option NOCHECK. (“SSRANGE” on page 362)
- Execution of NORENT programs above the 16 MB line is not supported.
(“RENT” on page 355 and “RMODE” on page 357)
- The HOOK | NOHOOK and SEPARATE | NOSEPARATE suboptions of the TEST
compiler option are no longer supported, but continue to be tolerated to
ease migration. New suboptions SOURCE and NOSOURCE are added to the TEST
compiler option. (“TEST” on page 364)
- The NOTEST option is enhanced to include the suboptions DWARF and
NODWARF. (“TEST” on page 364)
- The EXIT compiler option is no longer mutually exclusive with the DUMP
compiler option, and the compiler exits rules are updated. (“EXIT” on page
332)
- The OPTIMIZE option is modified to allow several level of optimization.
(“OPTIMIZE” on page 351)
– The following compiler options are deprecated, but continue to be tolerated to
ease migration. Informational or warning diagnostics will be displayed if you
specify any of these options.
- DATEPROC - Year 2000 support is no longer provided.
- LIB - Library processing is always done.
- SIZE(MAX) - This choice has become meaningless.
- YEARWINDOW - Year 2000 support is no longer provided.
|
|
|
|
|
|
- XMLPARSE - The XML System Services parser is always used.
v New intrinsic functions are added to provide additional Unicode capability:
– ULENGTH
– UPOS
– USUBSTR
|
|
|
|
|
– USUPPLEMENTARY
– UVALID
– UWIDTH
v AMODE 24 execution of programs is no longer supported. Enterprise COBOL V5
executable modules must be AMODE 31.
Preface
xix
|
|
|
v The IGZERRE and ILBOSTP0 interfaces for managing a reusable COBOL
environment are not supported for applications containing programs compiled
with Enterprise COBOL V5.
|
|
|
|
|
|
v A new special register, XML-INFORMATION, provides a mechanism to easily
determine whether the XML content delivered for an XML event is complete, or
will be continued on the next event. (“XML-INFORMATION” on page 527)
v The compatibility-mode COBOL XML parser from the COBOL library is no
longer supported. XML PARSE statements in V5 programs always use the z/OS
XML System Services parser.
|
|
|
|
|
|
|
|
v New phrases, NAME, TYPE and SUPPRESS are added to the XML GENERATE
statement.
v Numerous changes are added to compiler listings. (“Reading LIST output” on
page 399)
v JCL catalogue procedure changes:
– The COBOL compiler now requires 15 utility data sets (SYSUT1 - SYSUT15) and
the SYSMDECK data set when compiling under z/OS TSO or batch. The
following JCL catalogued procedures are modified:
|
|
|
|
|
|
|
|
|
|
|
- IGYWC (“Compile procedure (IGYWC)” on page 263)
- IGYWCL (“Compile and link-edit procedure (IGYWCL)” on page 264)
- IGYWCLG (“Compile, link-edit, and run procedure (IGYWCLG)” on page 265)
– The following JCL catalogued procedures are no longer supported. Because
they all use the Language Environment Prelinker or the DFSMS Loader,
which are no longer supported.
- IGYWCG
- IGYWCPG
- IGYWCPL
- IGYWCPLG
- IGYWPL
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
v A new keyword UNBOUNDED is added to the OCCURS clause, which enables you to
work with unbounded tables and groups. (“Working with unbounded tables and
groups” on page 92)
v For reentrant COBOL programs, VSAM record areas are allocated above 16 MB
by default. (“Allocation of record areas for VSAM files” on page 216)
v Debugging enhancements:
– With NOLOAD debug segments in the program object, Enterprise COBOL V5
debug data always matches the executable file, and is always available
without giving lists of data sets to search, and does not increase the size of
the loaded program.
– For other improvements about Debug Tool with Enterprise COBOL V5, see
Debug Tool changes with IBM Enterprise COBOL, Version 5 in the Enterprise
COBOL Migration Guide.
v Restrictions are added in the interoperability of Enterprise COBOL Version 5
Release 1 with earlier versions of COBOL. For details, see Interoperation with
older levels of Enterprise COBOL programs in the Enterprise COBOL Migration
Guide.
How to send your comments
Your feedback is important in helping us to provide accurate, high-quality
information. If you have comments about this information or any other Enterprise
COBOL documentation, contact us in one of these ways:
xx
Enterprise COBOL for z/OS, V5.1 Programming Guide
v Use the Online Readers' Comments Form at www.ibm.com/software/awdtools/
rcf/.
v Send your comments to the following address: compinfo@ca.ibm.com.
|
Be sure to include the name of the document, the publication number, the version
of Enterprise COBOL, and, if applicable, the specific location (for example, the
page number or section heading) of the text that you are commenting on.
When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any way that IBM believes appropriate without
incurring any obligation to you.
Accessibility
Accessibility features help users who have a disability, such as restricted mobility
or limited vision, to use information technology products successfully. The
accessibility features in z/OS provide accessibility for Enterprise COBOL.
The major accessibility features in z/OS are:
v Interfaces that are commonly used by screen readers and screen-magnifier
software
v Keyboard-only navigation
v Ability to customize display attributes such as color, contrast, and font size
Interface information
Assistive technology products work with the user interfaces that are found in
z/OS. For specific guidance information, see the documentation for the assistive
technology product that you use to access z/OS interfaces.
Keyboard navigation
Users can access z/OS user interfaces by using TSO/E or ISPF. For information
about accessing TSO/E or ISPF interfaces, see the following publications:
v z/OS TSO/E Primer
v z/OS TSO/E User's Guide
v z/OS ISPF User's Guide Volume I
These guides describe how to use TSO/E and ISPF, including the use of keyboard
shortcuts or function keys (PF keys). Each guide includes the default settings for
the PF keys and explains how to modify their functions.
Accessibility of this information
The English-language XHTML format of this information that will be provided in
the IBM System z Enterprise Development Tools & Compilers Information Center
at publib.boulder.ibm.com/infocenter/pdthelp/index.jsp is accessible to visually
impaired individuals who use a screen reader.
To enable your screen reader to accurately read syntax diagrams, source code
examples, and text that contains the period or comma PICTURE symbols, you must
set the screen reader to speak all punctuation.
Preface
xxi
IBM and accessibility
See the IBM Human Ability and Accessibility Center at www.ibm.com/able for
more information about the commitment that IBM has to accessibility.
xxii
Enterprise COBOL for z/OS, V5.1 Programming Guide
Part 1. Coding your program
© Copyright IBM Corp. 1991, 2013
1
2
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 1. Structuring your program
About this task
COBOL programs consist of four divisions: IDENTIFICATION DIVISION, ENVIRONMENT
DIVISION, DATA DIVISION, and PROCEDURE DIVISION. Each division has a specific
logical function.
To define a program, only the IDENTIFICATION DIVISION is required.
To define a COBOL class or method, you need to define some divisions differently
than you do for a program.
RELATED TASKS
“Identifying a program”
“Describing the computing environment” on page 5
“Describing the data” on page 11
“Processing the data” on page 17
“Defining a class” on page 578
“Defining a class instance method” on page 583
“Structuring OO applications” on page 618
Identifying a program
Use the IDENTIFICATION DIVISION to name a program and optionally provide other
identifying information.
About this task
You can use the optional AUTHOR, INSTALLATION, DATE-WRITTEN, and DATE-COMPILED
paragraphs for descriptive information about a program. The data you enter in the
DATE-COMPILED paragraph is replaced with the latest compilation date.
IDENTIFICATION
Program-ID.
Author.
Installation.
Date-Written.
Date-Compiled.
DIVISION.
Helloprog.
A. Programmer.
Computing Laboratories.
07/30/2009.
03/30/2013.
Use the PROGRAM-ID paragraph to name your program. The program-name that you
assign is used in these ways:
v Other programs use that name to call your program.
v The name appears in the header on each page, except the first, of the program
listing that is generated when you compile the program.
v If you use the NAME compiler option, the name is placed on the NAME
linkage-editor or binder control statement to identify the object module that the
compilation creates.
Tip: Do not use program-names that start with prefixes used by IBM products.
If you use program-names that start with any of the following prefixes, your
CALL statements might resolve to IBM library or compiler routines rather than to
your intended program:
© Copyright IBM Corp. 1991, 2013
3
–
–
–
–
–
AFB
AFH
CBC
CEE
CEH
–
–
–
–
–
–
–
CEL
CEQ
CEU
DFH
DSN
EDC
FOR
–
–
–
–
–
IBM
IFY
IGY
IGZ
ILB
Tip: If a program-name is case sensitive, avoid mismatches with the name that the
compiler is looking for. Verify that the appropriate setting of the PGMNAME compiler
option is in effect.
RELATED TASKS
“Changing the header of a source listing” on page 5
“Identifying a program as recursive”
“Marking a program as callable by containing programs”
“Setting a program to an initial state” on page 5
RELATED REFERENCES
Compiler limits (Enterprise COBOL Language Reference)
Conventions for program-names (Enterprise COBOL Language Reference)
Identifying a program as recursive
Code the RECURSIVE attribute on the PROGRAM-ID clause to specify that a program
can be recursively reentered while a previous invocation is still active.
About this task
You can code RECURSIVE only on the outermost program of a compilation unit.
Neither nested subprograms nor programs that contain nested subprograms can be
recursive. You must code RECURSIVE for programs that you compile with the THREAD
option.
RELATED TASKS
“Sharing data in recursive or multithreaded programs” on page 17
“Making recursive calls” on page 475
Marking a program as callable by containing programs
Use the COMMON attribute in the PROGRAM-ID paragraph to specify that a 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.
4
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
Only contained programs can have the COMMON attribute.
RELATED CONCEPTS
“Nested programs” on page 473
Setting a program to an initial state
Use the INITIAL clause in the PROGRAM-ID paragraph to specify that whenever a
program is called, that program and any nested programs that it contains are to be
placed in their initial state.
About this task
When a program is set to its initial state:
v Data items that have VALUE clauses are set to the specified values.
v Changed GO TO statements and PERFORM statements are in their initial states.
v Non-EXTERNAL files are closed.
RELATED TASKS
“Ending and reentering main programs or subprograms” on page 462
“Making static calls” on page 464
“Making dynamic calls” on page 465
Changing the header of a source listing
The header on the first page of a source listing contains the identification of the
compiler and the current release level, the date and time of compilation, and the
page number.
About this task
The following example shows these five elements:
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.0
Date 03/30/2013 Time 15:05:19
Page
1
The header indicates the compilation platform. You can customize the header on
succeeding pages of the listing by using the compiler-directing TITLE statement.
RELATED REFERENCES
TITLE statement (Enterprise COBOL Language Reference)
Describing the computing environment
In the ENVIRONMENT DIVISION of a program, you describe the aspects of the
program that depend on the computing environment.
About this task
Use the CONFIGURATION SECTION to specify the following items:
v Computer for compiling the program (in the SOURCE-COMPUTER paragraph)
v Computer for running the 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)
Chapter 1. Structuring your program
5
Use the FILE-CONTROL and I-O-CONTROL paragraphs of the INPUT-OUTPUT SECTION to:
v Identify and describe the characteristics of the files in the program.
v Associate your files with the external QSAM, VSAM, or z/OS UNIX file system
data sets where they physically reside.
The terms file in COBOL terminology and data set in operating-system
terminology have essentially the same meaning and are used interchangeably in
this information.
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. Do
not code file definitions in your COBOL programs that will run under CICS.
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 7
“Defining symbolic characters” on page 8
“Defining a user-defined class” on page 8
“Defining files to the operating system” on page 9
RELATED REFERENCES
Sections and paragraphs (Enterprise COBOL Language Reference)
Example: FILE-CONTROL entries
The following table shows example FILE-CONTROL entries for a QSAM sequential
file, a VSAM indexed file, and a line-sequential file.
Table 1. FILE-CONTROL entries
QSAM file
VSAM file
1
SELECT PRINTFILE
ASSIGN TO UPDPRINT2
ORGANIZATION IS SEQUENTIAL3
ACCESS IS SEQUENTIAL.4
Line-sequential file
1
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.
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 9, “Processing QSAM files,” on page 165
Chapter 10, “Processing VSAM files,” on page 191
6
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 11, “Processing line-sequential files,” on page 219
“Describing the computing environment” on page 5
Specifying the collating sequence
You can use the PROGRAM COLLATING SEQUENCE clause and the ALPHABET clause of the
SPECIAL-NAMES paragraph to establish the collating sequence that is used in several
operations on alphanumeric items.
About this task
These clauses specify the collating sequence for the following operations on
alphanumeric items:
v Comparisons explicitly specified in relation conditions and condition-name
conditions
v HIGH-VALUE and LOW-VALUE settings
v SEARCH ALL
v SORT and MERGE unless overridden by a COLLATING SEQUENCE phrase in 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: references the collating sequence associated with the EBCDIC character
set
v NATIVE: references the same collating sequence as EBCDIC
v STANDARD-1: references the collating sequence associated with the ASCII
character set defined by ANSI INCITS X3.4, Coded Character Sets - 7-bit American
National Standard Code for Information Interchange (7-bit ASCII)
v STANDARD-2: references the collating sequence associated with the character set
defined by ISO/IEC 646 -- Information technology -- ISO 7-bit coded character set for
information interchange, International Reference Version
v An alteration of the EBCDIC sequence that you define in the SPECIAL-NAMES
paragraph
The PROGRAM COLLATING SEQUENCE clause does not affect comparisons that involve
national or DBCS operands.
RELATED TASKS
“Choosing alternate collating sequences” on page 235
“Comparing national (UTF-16) data” on page 152
Example: specifying the collating sequence
The following example shows the ENVIRONMENT DIVISION coding that you can use
to specify a collating sequence in which uppercase and lowercase letters are
similarly handled in comparisons and in sorting and merging.
When you change the EBCDIC sequence in the SPECIAL-NAMES paragraph, the
overall collating sequence is affected, not just the collating sequence of the
characters that are included in the SPECIAL-NAMES paragraph.
IDENTIFICATION DIVISION.
. . .
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
Source-Computer. IBM-390.
Chapter 1. Structuring your program
7
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 7
Defining symbolic characters
Use the SYMBOLIC CHARACTERS clause to give symbolic names to any character of the
specified alphabet. Use ordinal position to identify the character, where position 1
corresponds to character X'00'.
About this task
For 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 that you list in the
clause.
About this task
For example, name the set of digits by coding the following clause:
CLASS DIGIT IS "0" THROUGH "9"
You can reference the class-name only in a class condition. (This user-defined class
is not the same as an object-oriented class.)
8
Enterprise COBOL for z/OS, V5.1 Programming Guide
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.
About this task
Depending on the operating system, this system data definition can take any of the
following forms:
v DD statement for MVS JCL.
v ALLOCATE command under TSO.
v Environment variable for z/OS or z/OS UNIX. The contents can define either an
MVS data set or a file in the z/OS UNIX file system.
The following examples show 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))
v Environment variable (export command):
(1)
export OUTFILE=DSN(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
(1)
The assignment-name in the ASSIGN clause points to the ddname OUTFILE in
the DD statement or the environment variable OUTFILE in the export
command:
v //OUTFILE DD DSNAME=OUT171 . . ., or
v export OUTFILE= . . .
(2)
When you specify a file file-name in a FILE-CONTROL entry, you must
describe the file in an FD entry:
SELECT CARPOOL
. . .
FD CARPOOL
RELATED TASKS
“Optimizing buffer and device space” on page 11
RELATED REFERENCES
“FILE SECTION entries” on page 13
FILE SECTION (Enterprise COBOL Language Reference)
Chapter 1. Structuring your program
9
Varying the input or output file at run time
The file-name that you code in a SELECT clause is used as a constant throughout
your COBOL program, but you can associate the name of that file with a different
system file at run time.
About this task
Changing a file-name within a COBOL program would require changing the input
statements and output statements and recompiling the program. Alternatively, you
can change the DSNAME value in the DD statement or the DSN or PATH value in the
export command to use a different file at run time.
Environment variable values that are in effect at the time of the OPEN statement are
used for associating COBOL file-names to the system file-names (including any
path specifications).
The name that you use in the assignment-name of the ASSIGN clause must be the
same as the ddname in the DD statement or the environment variable in the export
command.
The file-name that you use in 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
output is directed to SYSOUT, do not use SYSOUT as the ddname or environment
variable name in the SELECT clause for a file.
Example: using different input files:
This example shows that you use the same COBOL program to access different
files by coding a DD statement or an export command before the programs runs.
Consider a COBOL program that contains the following SELECT clause:
SELECT MASTER ASSIGN TO DA-3330-S-MASTERA
Assume the three possible input files are MASTER1, MASTER2, and MASTER3. Before
running the program, 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:
//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 MASTER will therefore be a reference to the file that
is currently assigned to the 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 z/OS UNIX file system, because
you cannot specify an organization field (S- or AS-) with a line-sequential file.
10
Enterprise COBOL for z/OS, V5.1 Programming Guide
Optimizing buffer and device space
Use the APPLY WRITE-ONLY clause to make optimum use of buffer and device space
when you create a sequential file with blocked variable-length records.
About this task
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 319
Describing the data
Define the characteristics of your data, and group your data definitions into one or
more of the sections in the DATA DIVISION.
About this task
You can use these sections for defining the following types of data:
v Data used in input-output operations: FILE SECTION
v 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 entered, and deallocated
on return from the program: LOCAL-STORAGE SECTION
v Data from another program: LINKAGE SECTION
The Enterprise COBOL compiler limits the maximum size of DATA DIVISION
elements. For details, see the related reference about compiler limits below.
RELATED CONCEPTS
“Comparison of WORKING-STORAGE and LOCAL-STORAGE” on page 14
RELATED TASKS
“Using data in input and output operations” on page 12
“Using data from another program” on page 16
RELATED REFERENCES
Compiler limits (Enterprise COBOL Language Reference)
Chapter 1. Structuring your program
11
Using data in input and output operations
Define the data that you use in input and output operations in the FILE SECTION.
About this task
Provide the following information about the data:
v Name the input and output files that the program will use. Use the FD entry to
give names to the 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 that follows 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 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 z/OS data management
facilities (including a DD file job-control statement).
– 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 in bytes,
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.
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 473
RELATED TASKS
“Sharing files between programs (external files)” on page 491
12
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
“FILE SECTION entries”
FILE SECTION entries
The entries that you can use in the FILE SECTION are summarized in the table
below.
Table 2. FILE SECTION entries
Clause
To define
Notes
FD
The file-name to be
referred to in PROCEDURE
DIVISION input-output
statements (OPEN, CLOSE,
READ, also START and
DELETE for VSAM)
Must match file-name in the SELECT clause.
file-name is associated with a ddname
through the assignment-name.
BLOCK CONTAINS
Size of physical records
If the CHARACTERS phrase is specified, size
indicates the number of bytes in a record
regardless of the USAGE of the data items in
the record.
QSAM: If provided, must match
information on JCL or data-set label. If
specified as BLOCK CONTAINS 0, or not
provided, the system determines the
optimal block size for you.
Line sequential: Can be specified to control
buffering for WRITE statements.
VSAM: Syntax-checked, but has no effect on
execution.
RECORD CONTAINS
n
Size of logical records
(fixed length)
Integer size indicates the number of bytes
in a record regardless of the USAGE of the
data items in the record. If the clause is
provided, it 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)
Integer size or sizes, if specified, indicate
the number of bytes in a record regardless
of the USAGE of the data items in the record.
If the clause is provided, it must match
information on JCL or data-set label;
compiler checks that record descriptions
match.
RECORD CONTAINS
n TO m
Size of logical records
(variable length)
The integer sizes indicate the number of
bytes in a record regardless of the USAGE of
the data items in the record. If the clause is
provided, it must match information on JCL
or data-set label; compiler checks that
record descriptions match.
LABEL RECORDS
Labels for QSAM files
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
Chapter 1. Structuring your program
13
Table 2. FILE SECTION entries (continued)
Clause
To define
Notes
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
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, COBOL for OS/390® & VM, or
IBM Enterprise COBOL for z/OS.
RECORDING MODE
Physical record
description
QSAM only
RELATED REFERENCES
FILE SECTION (Enterprise COBOL Language Reference)
Comparison of WORKING-STORAGE and LOCAL-STORAGE
How data items are allocated and initialized varies depending on whether the
items are in the WORKING-STORAGE SECTION or LOCAL-STORAGE SECTION.
WORKING-STORAGE for programs is allocated when the run unit is started.
|
Any data items that have 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 in the PROGRAM-ID paragraph
In this case, WORKING-STORAGE data items are reinitialized each time that 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.
See the related tasks for information about WORKING-STORAGE in COBOL class
definitions.
A separate copy of LOCAL-STORAGE data is allocated for each call of a program or
invocation of a method, and is freed on return from the program or method. If you
specify a VALUE clause for a LOCAL-STORAGE item, the item is initialized to that value
on each call or invocation. If a VALUE clause is not specified, the initial value of the
item is undefined.
Threading: Each invocation of a program that runs simultaneously on multiple
threads shares access to a single copy of WORKING-STORAGE data. Each invocation
has a separate copy of LOCAL-STORAGE data.
14
Enterprise COBOL for z/OS, V5.1 Programming Guide
“Example: storage sections”
RELATED TASKS
“Ending and reentering main programs or subprograms” on page 462
Chapter 27, “Preparing COBOL programs for multithreading,” on page 509
“WORKING-STORAGE SECTION for defining class instance data” on page 582
RELATED REFERENCES
WORKING-STORAGE SECTION (Enterprise COBOL Language Reference)
LOCAL-STORAGE SECTION (Enterprise COBOL Language Reference)
Example: storage sections
The following example is a recursive program that uses both WORKING-STORAGE and
LOCAL-STORAGE.
CBL pgmn(lu)
*********************************
* Recursive Program - Factorials
*********************************
IDENTIFICATION DIVISION.
Program-Id. factorial recursive.
ENVIRONMENT DIVISION.
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 program produces the following output:
0000!
0001!
0002!
0003!
0004!
0005!
=
=
=
=
=
=
00000001
00000001
00000002
00000006
00000024
00000120
The following tables show the changing values of the data items in LOCAL-STORAGE
and WORKING-STORAGE 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
Value for num in
LOCAL-STORAGE
Value for numb in
WORKING-STORAGE
Value for fact in
WORKING-STORAGE
Main
5
5
0
1
4
4
0
2
3
3
0
Chapter 1. Structuring your program
15
Recursive calls
Value for num in
LOCAL-STORAGE
Value for numb in
WORKING-STORAGE
Value for fact in
WORKING-STORAGE
3
2
2
0
4
1
1
0
5
0
0
0
Gobacks
Value for num in
LOCAL-STORAGE
Value for numb in
WORKING-STORAGE
Value for fact in
WORKING-STORAGE
5
0
0
1
4
1
0
1
3
2
0
2
2
3
0
6
1
4
0
24
Main
5
0
120
RELATED CONCEPTS
“Comparison of WORKING-STORAGE and LOCAL-STORAGE” on page 14
Using data from another program
How you share data depends on the type of program. You share data differently in
programs that are separately compiled than you do for programs that are nested or
for programs that are recursive or multithreaded.
About this task
RELATED TASKS
“Sharing data in separately compiled programs”
“Sharing data in nested programs” on page 17
“Sharing data in recursive or multithreaded programs” on page 17
“Passing data” on page 481
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.
About this task
In the calling program, code a CALL . . . USING or INVOKE . . . USING statement
to pass the data.
RELATED TASKS
“Passing data” on page 481
“Coding the LINKAGE SECTION” on page 485
16
Enterprise COBOL for z/OS, V5.1 Programming Guide
Sharing data in nested programs
Some applications consist of nested programs, that is, programs that are contained
in other programs. Level-01 data items can include the GLOBAL attribute. This
attribute allows any nested program that includes the declarations to access these
data items.
About this task
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 473
Sharing data in recursive or multithreaded programs
If your program has the RECURSIVE attribute or is compiled with the THREAD
compiler option, data that is defined in the LINKAGE SECTION is not accessible on
subsequent invocations of the program.
About this task
To address a record in the LINKAGE SECTION, use either of these techniques:
v Pass an argument to the program and specify the record in an appropriate
position in the USING phrase in the program.
v Use the format-5 SET statement.
If your program has the RECURSIVE attribute or is compiled with the THREAD
compiler option, the address of the record is valid for a particular instance of the
program invocation. The address of the record in another execution instance of the
same program must be reestablished for that execution instance. Unpredictable
results will occur if you refer to a data item for which the address has not been
established.
RELATED CONCEPTS
“Multithreading” on page 510
RELATED TASKS
“Making recursive calls” on page 475
“Processing files with multithreading” on page 512
RELATED REFERENCES
“THREAD” on page 366
SET statement (Enterprise COBOL Language Reference)
Processing the data
In the PROCEDURE DIVISION of a program, you code the executable statements that
process the data that you defined in the other divisions. The PROCEDURE DIVISION
contains one or two headers and the logic of your program.
About this task
The PROCEDURE DIVISION begins with the division header and a procedure-name
header. The division header for a program can simply be:
Chapter 1. Structuring your program
17
PROCEDURE DIVISION.
You can code the division header to receive parameters by using the USING phrase,
or to return a value by using 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 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.
RELATED CONCEPTS
“How logic is divided in the PROCEDURE DIVISION”
RELATED TASKS
“Coding the LINKAGE SECTION” on page 485
“Coding the PROCEDURE DIVISION for passing arguments” on page 486
“Using PROCEDURE DIVISION RETURNING . . .” on page 490
“Eliminating repetitive coding” on page 667
RELATED REFERENCES
The procedure division header (Enterprise COBOL Language Reference)
The USING phrase (Enterprise COBOL Language Reference)
CALL statement (Enterprise COBOL Language Reference)
How logic is divided in the PROCEDURE DIVISION
The PROCEDURE DIVISION of a program is divided into sections and paragraphs,
which contain sentences, statements, and phrases.
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.
18
Enterprise COBOL for z/OS, V5.1 Programming Guide
Sentence
Series of one or more COBOL statements that ends with a period.
Statement
Performs a defined step of COBOL processing, such as adding two
numbers.
A statement is a valid combination of words, and begins 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”
“Declaratives” on page 22
RELATED REFERENCES
PROCEDURE DIVISION structure (Enterprise COBOL Language Reference)
Imperative statements
An imperative statement (such as ADD, MOVE, INVOKE, or CLOSE) indicates an
unconditional action to be taken.
You can end an imperative statement 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”
“Scope terminators” on page 20
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 phrase 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:
Chapter 1. Structuring your program
19
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 Arithmetic statement with ON SIZE ERROR
v Data-manipulation statements with ON OVERFLOW
v CALL statements with ON OVERFLOW
v I/O statements with INVALID KEY, AT END, or AT END-OF-PAGE
v RETURN with AT END
RELATED CONCEPTS
“Imperative statements” on page 19
“Scope terminators”
RELATED TASKS
“Selecting program actions” on page 97
RELATED REFERENCES
Conditional statements (Enterprise COBOL Language Reference)
Compiler-directing statements
A compiler-directing statement causes the compiler to take specific action about the
program structure, COPY processing, listing control, or control flow.
A compiler-directing statement is not part of the program logic.
RELATED REFERENCES
Chapter 18, “Compiler-directing statements,” on page 375
Compiler-directing statements (Enterprise COBOL Language Reference)
Scope terminators
A scope terminator ends a verb or statement. Scope terminators can be explicit or
implicit.
20
Enterprise COBOL for z/OS, V5.1 Programming Guide
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.
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
Chapter 1. Structuring your program
21
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 19
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 381
RELATED REFERENCES
Declaratives (Enterprise COBOL Language Reference)
22
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 2. Using data
About this task
This information is intended to help non-COBOL programmers relate terms for
data used in other programming languages to COBOL terms. It introduces COBOL
fundamentals for variables, structures, literals, and constants; assigning and
displaying values; intrinsic (built-in) functions, and tables (arrays) and pointers.
RELATED CONCEPTS
“Storage and its addressability” on page 40
RELATED TASKS
“Using variables, structures, literals, and constants”
“Assigning values to data items” on page 27
“Displaying values on a screen or in a file (DISPLAY)” on page 36
“Using intrinsic functions (built-in functions)” on page 39
“Using tables (arrays) and pointers” on page 40
Chapter 7, “Processing data in an international environment,” on page 129
Using variables, structures, literals, and constants
Most high-level programming languages share the concept of data being
represented as variables, structures (group items), literals, or constants.
About this task
The data in a COBOL program can be alphabetic, alphanumeric, double-byte
character set (DBCS), national, or numeric. You can also define index-names and
data items described as USAGE POINTER, USAGE FUNCTION-POINTER, USAGE
PROCEDURE-POINTER, or USAGE OBJECT REFERENCE. You place all data definitions in
the DATA DIVISION of your program.
RELATED TASKS
“Using
“Using
“Using
“Using
“Using
variables”
data items and group items” on page 24
literals” on page 26
constants” on page 26
figurative constants” on page 27
RELATED REFERENCES
Classes and categories of data (Enterprise COBOL Language Reference)
Using variables
A variable is a data item whose value can change during a program. The value is
restricted, however, to the data type that you define when you specify a name and
a length for the data item.
About this task
For example, if a customer name is an alphanumeric data item in your program,
you could define and use the customer name as shown below:
© Copyright IBM Corp. 1991, 2013
23
Data Division.
01 Customer-Name
Pic X(20).
01 Original-Customer-Name Pic X(20).
. . .
Procedure Division.
Move Customer-Name to Original-Customer-Name
. . .
You could instead declare the customer names above as national data items by
specifying their PICTURE clauses as Pic N(20) and specifying the USAGE NATIONAL
clause for the items. National data items are represented in Unicode UTF-16, in
which most characters are represented in 2 bytes of storage.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Using national data (Unicode) in COBOL” on page 134
RELATED REFERENCES
“NSYMBOL” on page 346
“Storage of character data” on page 141
PICTURE clause (Enterprise COBOL Language Reference)
Using data items and group items
Related data items can be parts of a hierarchical data structure. A data item that
does not have subordinate data items is called an elementary item. A data item that
is composed of one or more subordinate data items is called a group item.
About this task
A record can be either an elementary item or a group item. A group item can be
either an alphanumeric group item or a national group item.
For example, Customer-Record below is an alphanumeric group item that is
composed of two subordinate alphanumeric group items (Customer-Name and
Part-Order), each of which contains elementary data items. These groups items
implicitly have USAGE DISPLAY. You can refer to an entire group item or to parts of
a group item in MOVE statements in the PROCEDURE DIVISION as shown below:
Data Division.
File Section.
FD Customer-File
Record Contains 45 Characters.
01 Customer-Record.
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).
. . .
24
Enterprise COBOL for z/OS, V5.1 Programming Guide
Procedure Division.
Move Customer-Name to Orig-Customer-Name
Move Part-Name to Inventory-Part-Name
. . .
You could instead define Customer-Record as a national group item that is
composed of two subordinate national group items by changing the declarations in
the DATA DIVISION as shown below. National group items behave in the same way
as elementary category national data items in most operations. The GROUP-USAGE
NATIONAL clause indicates that a group item and any group items subordinate to it
are national groups. Subordinate elementary items in a national group must be
explicitly or implicitly described as USAGE NATIONAL.
Data Division.
File Section.
FD Customer-File
Record Contains 90 Characters.
01 Customer-Record
Group-Usage National.
05 Customer-Name.
10 Last-Name
Pic n(17).
10 Filler
Pic n.
10 Initials
Pic nn.
05 Part-Order.
10 Part-Name
Pic n(15).
10 Part-Color
Pic n(10).
Working-Storage Section.
01 Orig-Customer-Name
Group-Usage National.
05 Surname
Pic n(17).
05 Initials
Pic n(3).
01 Inventory-Part-Name
Pic n(15) Usage National.
. . .
Procedure Division.
Move Customer-Name to Orig-Customer-Name
Move Part-Name to Inventory-Part-Name
. . .
In the example above, the group items could instead specify the USAGE NATIONAL
clause at the group level. A USAGE clause at the group level applies to each
elementary data item in a group (and thus serves as a convenient shorthand
notation). However, a group that specifies the USAGE NATIONAL clause is not a
national group despite the representation of the elementary items within the group.
Groups that specify the USAGE clause are alphanumeric groups and behave in many
operations, such as moves and compares, like elementary data items of USAGE
DISPLAY (except that no editing or conversion of data occurs).
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
“National groups” on page 137
RELATED TASKS
“Using national data (Unicode) in COBOL” on page 134
“Using national groups” on page 139
RELATED REFERENCES
“FILE SECTION entries” on page 13
“Storage of character data” on page 141
Classes and categories of group items (Enterprise COBOL Language Reference)
PICTURE clause (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
USAGE clause (Enterprise COBOL Language Reference)
Chapter 2. Using data
25
Using literals
A literal is a character string whose value is given by the characters themselves. If
you know the value you want a data item to have, you can use a literal
representation of the data value in the PROCEDURE DIVISION.
About this task
You do not need to declare a data item for the value nor refer to it by using a
data-name. For example, you can prepare an error message for an output file by
moving an alphanumeric literal:
Move "Name is not valid" To Customer-Name
You can compare a data item to a specific integer value by using a numeric literal.
In the example below, "Name is not valid" is an alphanumeric literal, and 03519 is
a numeric literal:
01 Part-number
Pic 9(5).
. . .
If Part-number = 03519 then display "Part number was found"
You can use the opening delimiter N" or N’ to designate a national literal if the
NSYMBOL(NATIONAL) compiler option is in effect, or to designate a DBCS literal if the
NSYMBOL(DBCS) compiler option is in effect.
You can use the opening delimiter NX" or NX’ to designate national literals in
hexadecimal notation (regardless of the setting of the NSYMBOL compiler option).
Each group of four hexadecimal digits designates a single national character.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Using national literals” on page 135
“Using DBCS literals” on page 156
RELATED REFERENCES
“NSYMBOL” on page 346
Literals (Enterprise COBOL Language Reference)
Using constants
A constant is a data item that has only one value. COBOL does not define a
construct for constants. However, you can define a data item with an initial value
by coding a VALUE clause in the data description (instead of coding an INITIALIZE
statement).
About this task
Data Division.
01 Report-Header
. . .
01 Interest
pic x(50)
value "Company Sales Report".
pic 9v9999 value 1.0265.
The example above initializes an alphanumeric and a numeric data item. You can
likewise use a VALUE clause in defining a national or DBCS constant.
26
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED TASKS
“Using national data (Unicode) in COBOL” on page 134
“Coding for use of DBCS support” on page 155
Using figurative constants
Certain commonly used constants and literals are available as reserved words
called figurative constants: ZERO, SPACE, HIGH-VALUE, LOW-VALUE, QUOTE, NULL, and ALL
literal. Because they represent fixed values, figurative constants do not require a
data definition.
About this task
For example:
Move Spaces To Report-Header
RELATED TASKS
“Using national-character figurative constants” on page 136
“Coding for use of DBCS support” on page 155
RELATED REFERENCES
Figurative constants (Enterprise COBOL Language Reference)
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.
About this task
Table 3. Assignment to data items in a program
What you want to do
How to do it
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
initial state)
Assign the results of arithmetic.
Use COMPUTE, ADD, SUBTRACT, MULTIPLY, or DIVIDE
statements.
Examine or replace characters or groups of characters in a data Use the INSPECT statement.
item.
Receive values from a file.
Use the READ (or READ INTO) statement.
Receive values from a system input device or a file.
Use the ACCEPT statement.
Establish a constant.
Use the VALUE clause in the definition of the data
item, and do not use the data item as a receiver.
Such an item is in effect a constant even though the
compiler does not enforce read-only constants.
Chapter 2. Using data
27
Table 3. Assignment to data items in a program (continued)
What you want to do
How to do it
One of these actions:
Use the SET statement.
v Place a value associated with a table element in an index.
v Set the status of an external switch to ON or OFF.
v Move data to a condition-name to make the condition true.
v Set a POINTER, PROCEDURE-POINTER, or FUNCTION-POINTER data
item to an address.
v Associate an OBJECT REFERENCE data item with an object
instance.
“Examples: initializing data items”
RELATED TASKS
“Initializing a structure (INITIALIZE)” on page 31
“Assigning values to elementary data items (MOVE)” on page 32
“Assigning values to group data items (MOVE)” on page 33
“Assigning input from a screen or file (ACCEPT)” on page 35
“Joining data items (STRING)” on page 109
“Splitting data items (UNSTRING)” on page 111
“Assigning arithmetic results (MOVE or COMPUTE)” on page 34
“Tallying and replacing data items (INSPECT)” on page 119
Chapter 7, “Processing data in an international environment,” on page 129
Examples: initializing data items
The following examples show how you can initialize many kinds of data items,
including alphanumeric, national-edited, and numeric-edited data items, by using
INITIALIZE statements.
An INITIALIZE statement is functionally equivalent to one or more MOVE statements.
The related tasks about initializing show how you can use an INITIALIZE statement
on a group item to conveniently initialize all the subordinate data items that are in
a given data category.
Initializing a data item to blanks or zeros:
INITIALIZE identifier-1
28
identifier-1 PICTURE
identifier-1 before
identifier-1 after
9(5)
12345
00000
X(5)
AB123
bbbbb1
N(3)
0041004200312
0020002000203
99XX9
12AB3
bbbbb1
XXBX/XX
ABbC/DE
bbbb/bb1
**99.9CR
1234.5CR
**00.0bb1
A(5)
ABCDE
bbbbb1
+99.99E+99
+12.34E+02
+00.00E+00
Enterprise COBOL for z/OS, V5.1 Programming Guide
identifier-1 PICTURE
identifier-1 before
identifier-1 after
1. The symbol b represents a blank space.
2. Hexadecimal representation of the national (UTF-16) characters 'AB1'. The example
assumes that identifier-1 has Usage National.
3. Hexadecimal representation of the national (UTF-16) characters ' ' (three blank
spaces). Note that if identifier-1 were not defined as Usage National, and if
NSYMBOL(DBCS) were in effect, INITIALIZE would instead store DBCS spaces ('4040') into
identifier-1.
Initializing an alphanumeric data item:
01 ALPHANUMERIC-1
PIC X
VALUE "y".
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 an alphanumeric right-justified data item:
01 ANJUST
PIC X(8) VALUE SPACES JUSTIFIED RIGHT.
01 ALPHABETIC-1
PIC A(4) VALUE "ABCD".
. . .
INITIALIZE ANJUST
REPLACING ALPHANUMERIC DATA BY ALPHABETIC-1
ALPHABETIC-1
ABCD
ANJUST before
bbbbbbbb
1
ANJUST after
bbbbABCD1
1. The symbol b represents a blank space.
Initializing an alphanumeric-edited data item:
01 ALPHANUM-EDIT-1
PIC XXBX/XXX VALUE "ABbC/DEF".
01 ALPHANUM-EDIT-3
PIC X/BB
VALUE "M/bb".
. . .
INITIALIZE ALPHANUM-EDIT-1
REPLACING ALPHANUMERIC-EDITED DATA BY ALPHANUM-EDIT-3
ALPHANUM-EDIT-3
M/bb
1
ALPHANUM-EDIT-1 before
ABbC/DEF
1
ALPHANUM-EDIT-1 after
M/bb/bbb1
1. The symbol b represents a blank space.
Initializing a national data item:
01 NATIONAL-1
PIC NN USAGE NATIONAL VALUE N"AB".
01 NATIONAL-3
PIC NN USAGE NATIONAL VALUE N"CD".
. . .
INITIALIZE NATIONAL-1
REPLACING NATIONAL DATA BY NATIONAL-3
NATIONAL-3
00430044
1
NATIONAL-1 before
00410042
2
NATIONAL-1 after
004300441
Chapter 2. Using data
29
NATIONAL-1 before
NATIONAL-3
NATIONAL-1 after
1. Hexadecimal representation of the national characters 'CD'
2. Hexadecimal representation of the national characters 'AB'
Initializing a national-edited data item:
01 NATL-EDIT-1
PIC 0NN USAGE NATIONAL VALUE N"123".
01 NATL-3
PIC NNN USAGE NATIONAL VALUE N"456".
. . .
INITIALIZE NATL-EDIT-1
REPLACING NATIONAL-EDITED DATA BY NATL-3
NATL-3
NATL-EDIT-1 before
NATL-EDIT-1 after
0034003500361
0031003200332
0030003400353
1. Hexadecimal representation of the national characters '456'
2. Hexadecimal representation of the national characters '123'
3. Hexadecimal representation of the national characters '045'
Initializing a numeric (zoned decimal) data item:
01 NUMERIC-1
PIC 9(8)
VALUE 98765432.
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 a numeric (national decimal) data item:
01 NAT-DEC-1
PIC 9(3) USAGE NATIONAL VALUE 987.
01 NUM-INT-BIN-3
PIC 9(2) BINARY VALUE 12.
. . .
INITIALIZE NAT-DEC-1
REPLACING NUMERIC DATA BY NUM-INT-BIN-3
NUM-INT-BIN-3
12
NAT-DEC-1 before
003900380037
1
NAT-DEC-1 after
0030003100322
1. Hexadecimal representation of the national characters '987'
2. Hexadecimal representation of the national characters '012'
Initializing a numeric-edited (USAGE DISPLAY) data item:
01 NUM-EDIT-DISP-1 PIC $ZZ9V VALUE "$127".
01 NUM-DISP-3
PIC 999V
VALUE 12.
. . .
INITIALIZE NUM-EDIT-DISP-1
REPLACING NUMERIC DATA BY NUM-DISP-3
NUM-DISP-3
NUM-EDIT-DISP-1 before
NUM-EDIT-DISP-1 after
012
$127
$ 12
Initializing a numeric-edited (USAGE NATIONAL) data item:
30
Enterprise COBOL for z/OS, V5.1 Programming Guide
01 NUM-EDIT-NATL-1
PIC $ZZ9V NATIONAL VALUE N"$127".
01 NUM-NATL-3
PIC 999V
NATIONAL VALUE 12.
. . .
INITIALIZE NUM-EDIT-NATL-1
REPLACING NUMERIC DATA BY NUM-NATL-3
NUM-EDIT-NATL-1 before
NUM-NATL-3
003000310032
1
0024003100320037
2
NUM-EDIT-NATL-1 after
00240020003100323
1. Hexadecimal representation of the national characters '012'
2. Hexadecimal representation of the national characters '$127'
3. Hexadecimal representation of the national characters '$ 12'
RELATED TASKS
“Initializing a structure (INITIALIZE)”
“Initializing a table (INITIALIZE)” on page 76
“Defining numeric data” on page 45
RELATED REFERENCES
“NSYMBOL” on page 346
Initializing a structure (INITIALIZE)
You can reset the values of all subordinate data items in a group item by applying
the INITIALIZE statement to that group item. However, it is inefficient to initialize
an entire group unless you really need all the items in the group to be initialized.
About this task
The following example shows how you can reset fields to spaces and zeros in
transaction records that a program produces. The values of the fields are not
identical in each record that is produced. (The transaction record is defined as an
alphanumeric group item, TRANSACTION-OUT.)
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
Record
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
b0000000000000000000000000001
2
R001390000480000000000000000
b0000000000000000000000000001
3
S001410000120000000000000000
b0000000000000000000000000001
4
C001383000000000425000000000
b0000000000000000000000000001
5
C002010000000000000100000000
b0000000000000000000000000001
1. The symbol b represents a blank space.
Chapter 2. Using data
31
You can likewise reset the values of all the subordinate data items in a national
group item by applying the INITIALIZE statement to that group item. The
following structure is similar to the preceding structure, but instead uses Unicode
UTF-16 data:
01
TRANSACTION-OUT GROUP-USAGE
05 TRANSACTION-CODE
05 PART-NUMBER
05 TRANSACTION-QUANTITY
05 PRICE-FIELDS.
10 UNIT-PRICE
10 DISCOUNT
10 SALES-PRICE
. . .
INITIALIZE TRANSACTION-OUT
NATIONAL.
PIC N.
PIC 9(6).
PIC 9(5).
PIC 9(5)V9(2).
PIC V9(2).
PIC 9(5)V9(2).
Regardless of the previous contents of the transaction record, after the INITIALIZE
statement above is executed:
v TRANSACTION-CODE contains NX"0020" (a national space).
v Each of the remaining 27 national character positions of TRANSACTION-OUT
contains NX"0030" (a national-decimal zero).
When you use an INITIALIZE statement to initialize an alphanumeric or national
group data item, the data item is processed as a group item, that is, with group
semantics. The elementary data items within the group are recognized and
processed, as shown in the examples above. If you do not code the REPLACING
phrase of the INITIALIZE statement:
v SPACE is the implied sending item for alphabetic, alphanumeric,
alphanumeric-edited, DBCS, category national, and national-edited receiving
items.
v ZERO is the implied sending item for numeric and numeric-edited receiving
items.
RELATED CONCEPTS
“National groups” on page 137
RELATED TASKS
“Initializing a table (INITIALIZE)” on page 76
“Using national groups” on page 139
RELATED REFERENCES
INITIALIZE statement (Enterprise COBOL Language Reference)
Assigning values to elementary data items (MOVE)
Use a MOVE statement to assign a value to an elementary data item.
About this task
The following statement assigns the contents of an elementary data item,
Customer-Name, to the elementary data item Orig-Customer-Name:
Move Customer-Name to Orig-Customer-Name
If Customer-Name is longer than Orig-Customer-Name, truncation occurs on the right.
If Customer-Name is shorter, the extra character positions on the right in
Orig-Customer-Name are filled with spaces.
32
Enterprise COBOL for z/OS, V5.1 Programming Guide
For data items that contain numbers, moves can be more complicated than with
character data items because there are several ways in which numbers can be
represented. In general, the algebraic values of numbers are moved if possible, as
opposed to the digit-by-digit moves that are performed with character data. For
example, after the MOVE statement below, Item-x contains the value 3.0, represented
as 0030:
01 Item-x
Pic 999v9.
. . .
Move 3.06 to Item-x
You can move an alphabetic, alphanumeric, alphanumeric-edited, DBCS, integer, or
numeric-edited data item to a category national or national-edited data item; the
sending item is converted. You can move a national data item to a category
national or national-edited data item. If the content of a category national data
item has a numeric value, you can move that item to a numeric, numeric-edited,
external floating-point, or internal floating-point data item. You can move a
national-edited data item only to a category national data item or another
national-edited data item. Padding or truncation might occur.
For complete details about elementary moves, see the related reference below
about the MOVE statement.
The following example shows an alphanumeric data item in the Greek language
that is moved to a national data item:
CBL CODEPAGE(00875)
. . .
01 Data-in-Unicode
Pic N(100) usage national.
01 Data-in-Greek
Pic X(100).
. . .
Read Greek-file into Data-in-Greek
Move Data-in-Greek to Data-in-Unicode
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Assigning values to group data items (MOVE)”
“Converting to or from national (Unicode) representation” on page 142
RELATED REFERENCES
“CODEPAGE” on page 322
Classes and categories of data (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
Assigning values to group data items (MOVE)
Use the MOVE statement to assign values to group data items.
About this task
You can move a national group item (a data item that is described with the
GROUP-USAGE NATIONAL clause) to another national group item. The compiler
processes the move as though each national group item were an elementary item
of category national, that is, as if each item were described as PIC N(m), where m
is the length of that item in national character positions.
Chapter 2. Using data
33
You can move an alphanumeric group item to an alphanumeric group item or to a
national group item. You can also move a national group item to an alphanumeric
group item. The compiler performs such moves as group moves, that is, without
consideration of the individual elementary items in the sending or receiving group,
and without conversion of the sending data item. Be sure that the subordinate data
descriptions in the sending and receiving group items are compatible. The moves
occur even if a destructive overlap could occur at run time.
You can code the CORRESPONDING phrase in a MOVE statement to move subordinate
elementary items from one group item to the identically named corresponding
subordinate elementary items in another group item:
01
Group-X.
02 T-Code
Pic X
Value "A".
02 Month
Pic 99
Value 04.
02 State
Pic XX
Value "CA".
02 Filler
PIC X.
01 Group-N
Group-Usage National.
02 State
Pic NN.
02 Month
Pic 99.
02 Filler
Pic N.
02 Total
Pic 999.
. . .
MOVE CORR Group-X TO Group-N
In the example above, State and Month within Group-N receive the values in
national representation of State and Month, respectively, from Group-X. The other
data items in Group-N are unchanged. (Filler items in a receiving group item are
unchanged by a MOVE CORRESPONDING statement.)
In a MOVE CORRESPONDING statement, sending and receiving group items are treated
as group items, not as elementary data items; group semantics apply. That is, the
elementary data items within each group are recognized, and the results are the
same as if each pair of corresponding data items were referenced in a separate
MOVE statement. Data conversions are performed according to the rules for the MOVE
statement as specified in the related reference below. For details about which types
of elementary data items correspond, see the related reference about the
CORRESPONDING phrase.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
“National groups” on page 137
RELATED TASKS
“Assigning values to elementary data items (MOVE)” on page 32
“Using national groups” on page 139
“Converting to or from national (Unicode) representation” on page 142
RELATED REFERENCES
Classes and categories of group items (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
CORRESPONDING phrase (Enterprise COBOL Language Reference)
Assigning arithmetic results (MOVE or COMPUTE)
When assigning a number to a data item, consider using the COMPUTE statement
instead of the MOVE statement.
34
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
Move w to z
Compute z = w
In the example above, the two statements in most cases have the same effect. The
MOVE statement however carries out the assignment with truncation. You can use
the DIAGTRUNC compiler option to request that the compiler issue a warning 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. If 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 you do not
specify the ON SIZE ERROR phrase, 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 data item. For example:
Compute z = y + (x ** 3)
Compute x = Function Max(x y z)
You can assign the results of date, time, mathematical, and other calculations to
data items by using Language Environment callable services. Language
Environment services are available through a standard COBOL CALL statement, and
the values they return are passed in the parameters of the CALL statement. For
example, you can call the Language Environment service CEESIABS to find the
absolute value of a data item by coding the following statement:
Call ’CEESIABS’ Using Arg, Feedback-code, Result.
As a result of this call, data item Result is assigned the absolute value of the value
in data item Arg; data item Feedback-code contains the return code that indicates
whether the service completed successfully. You have to define all the data items in
the DATA DIVISION using the correct descriptions according to the requirements of
the particular callable service. For the example above, the data items could be
defined as follows:
77 Arg
Pic s9(9) Binary.
77 Feedback-code Pic x(12) Display.
77 Result
Pic s9(9) Binary.
RELATED REFERENCES
“DIAGTRUNC” on page 328
Intrinsic functions (Enterprise COBOL Language Reference)
Language Environment Programming Reference (Callable services)
Assigning input from a screen or file (ACCEPT)
One way to assign a value to a data item is to read the value from a screen or a
file.
About this task
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 data item. For example:
Chapter 2. Using data
35
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:
v Change Console to device, where device is any valid system device (for example,
SYSIN). For example:
SYSIN is Names-Input
device can be a ddname that references a z/OS UNIX file system path. If this
ddname is not defined and your program is running in the z/OS UNIX
environment, stdin is the input source. If this ddname is not defined and your
program is not running in the z/OS UNIX environment, the ACCEPT statement
fails.
When you use the ACCEPT statement, you can assign a value to an alphanumeric or
national group item, or to an elementary data item that has USAGE DISPLAY, USAGE
DISPLAY-1, or USAGE NATIONAL.
When you assign a value to a USAGE NATIONAL data item, input data from the
console is converted from the EBCDIC code page specified in the CODEPAGE
compiler option to national (Unicode UTF-16) representation. This is the only case
where conversion of national data is done when you use the ACCEPT statement.
Conversion is done in this case because the input is known to be coming from a
screen.
To have conversion done when the input data is from any other device, use the
NATIONAL-OF intrinsic function.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Converting alphanumeric or DBCS to national (NATIONAL-OF)” on page 143
RELATED REFERENCES
“CODEPAGE” on page 322
ACCEPT statement (Enterprise COBOL Language Reference)
SPECIAL-NAMES paragraph (Enterprise COBOL Language Reference)
Displaying values on a screen or in a file (DISPLAY)
You can display the value of a data item on a screen or write it to a file by using
the DISPLAY statement.
About this task
Display "No entry for surname ’" Customer-Name "’ found in the file.".
In the example above, if the content of data item Customer-Name is JOHNSON,
then the statement displays the following message on the system logical output
device:
No entry for surname ’JOHNSON’ found in the file.
36
Enterprise COBOL for z/OS, V5.1 Programming Guide
To write data to a destination other than the system logical output device, use the
UPON phrase with a destination other than SYSOUT. For example, the following
statement writes to the file that is specified in the SYSPUNCH DD statement:
Display "Hello" upon syspunch.
You can specify a file in the z/OS UNIX file system by using the SYSPUNCH DD
statement. For example, the following definition causes DISPLAY output to be
written to the 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 and to the TSO screen if
you are running under TSO:
Display "Hello" upon console.
When you display the value of a USAGE NATIONAL data item to the console, the data
item is converted from Unicode (UTF-16) representation to EBCDIC based on the
value of the CODEPAGE option. This is the only case in which conversion of national
data is done when you use the DISPLAY statement. Conversion is done in this case
because the output is known to be directed to a screen.
To have a national data item be converted when you direct output to a different
device, use the DISPLAY-OF intrinsic function, as in the following example:
01 Data-in-Unicode pic N(10) usage national.
. . .
Display function Display-of(Data-in-Unicode, 00037)
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Displaying data on the system logical output device”
“Using WITH NO ADVANCING” on page 38
“Converting national to alphanumeric (DISPLAY-OF)” on page 144
“Coding COBOL programs to run under CICS” on page 421
RELATED REFERENCES
“CODEPAGE” on page 322
DISPLAY statement (Enterprise COBOL Language Reference)
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.
About this task
Display "Hello" upon sysout.
The output is directed to the ddname that you specify in the OUTDD compiler
option. You can specify a file in the z/OS UNIX file system with this ddname.
If the OUTDD ddname is not allocated and you are not running in the z/OS UNIX
environment, a default DD of SYSOUT=* is allocated. If the OUTDD ddname is not
allocated and you are running in the z/OS UNIX environment, the _IGZ_SYSOUT
environment variable is used as follows:
Chapter 2. Using data
37
Undefined or set to stdout
Output is routed to stdout (file descriptor 1).
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. The output is written as a single stream of characters without line
breaks.
If OUTDD and the Language Environment runtime option MSGFILE specify the same
ddname, both DISPLAY output and Language Environment runtime diagnostics are
routed to the Language Environment message file.
RELATED TASKS
“Setting and accessing environment variables” on page 452
RELATED REFERENCES
“OUTDD” on page 352
DISPLAY statement (Enterprise COBOL Language Reference)
Using WITH NO ADVANCING
If you specify the WITH NO ADVANCING phrase, and 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.
About this task
If you specify the WITH NO ADVANCING phrase and the output is going to stdout or
stderr, a newline 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.
DISPLAY
DISPLAY
DISPLAY
DISPLAY
DISPLAY
"ABC"
"CDEF" WITH NO ADVANCING
"GHIJK" WITH NO ADVANCING
"LMNOPQ"
"RSTUVWX"
If you code the statements above, the result sent to the output device is:
ABC
CDEF
+GHIJK
+LMNOPQ
RSTUVMX
The output that is printed depends on how the output device interprets printer
control characters.
38
Enterprise COBOL for z/OS, V5.1 Programming Guide
If you do not specify the WITH NO ADVANCING phrase and the output is going to
stdout or stderr, a newline character is appended to the end of the stream.
RELATED REFERENCES
DISPLAY statement (Enterprise COBOL Language Reference)
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 that have defined attributes
and a predetermined value. In COBOL, these functions are called intrinsic functions.
They provide capabilities for manipulating strings and numbers.
About this task
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). For example, the groups of
highlighted words below are 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 that has 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 data item.
For example, you could use Sqrt to invoke an intrinsic function and to name a
data item 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)
A function-identifier represents a value that is of one of these types: alphanumeric,
national, numeric, or integer. You can include a substring specification (reference
modifier) in a function-identifier for alphanumeric or national functions. Numeric
intrinsic functions are further classified according to the type of numbers they
return.
|
The functions MAX and MIN can return either type of value depending on the type of
arguments you supply.
Chapter 2. Using data
39
Functions can reference other functions as arguments provided that the results of
the nested functions meet the requirements for the arguments of the outer function.
For example, Function Sqrt(5) returns a numeric value. Thus, the three arguments
to the MAX function below are all numeric, which is an allowable argument type for
this function:
Compute x = Function Max((Function Sqrt(5)) 2.5 3.5)
RELATED TASKS
“Processing table items using intrinsic functions” on page 91
“Converting data items (intrinsic functions)” on page 120
“Evaluating data items (intrinsic functions)” on page 123
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.
About this task
Pointers are data items that contain virtual storage addresses. You define them
either explicitly with the USAGE IS POINTER clause in the DATA DIVISION or
implicitly as ADDRESS OF special registers.
You can perform the following operations with 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 invalid address 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.
RELATED TASKS
“Defining a table (OCCURS)” on page 69
“Using procedure and function pointers” on page 476
Storage and its addressability
When you run COBOL programs, the programs and the data that they use reside
in virtual storage. Storage that you use with COBOL can be either below the 16
MB line or above the 16 MB line but below the 2 GB bar. Two modes of addressing
are available to address this storage: 24-bit and 31-bit.
You can address storage below (but not above) the 16 MB line with 24-bit
addressing. You can address storage either above or below the 16 MB line with
31-bit addressing. Unrestricted storage is addressable by 31-bit addressing and
therefore encompasses all the storage available to your program, both above and
below the 16 MB line.
40
Enterprise COBOL for z/OS, V5.1 Programming Guide
Enterprise COBOL does not directly exploit the 64-bit virtual addressing capability
of z/OS; however, COBOL applications running in 31-bit or 24-bit addressing
mode are fully supported on 64-bit z/OS systems.
|
Addressing mode (AMODE) is the attribute that tells which hardware addressing mode
is supported by your program: 31-bit addressing. This attribute is AMODE 31. The
object program, the load module, and the executing program each has an AMODE
attribute. All Enterprise COBOL object programs are AMODE 31.
Residency mode (RMODE) is the attribute of a program load module that identifies
where in virtual storage the program will reside: below the 16 MB line, or either
below or above. This attribute is RMODE 24 or RMODE ANY.
Enterprise COBOL uses Language Environment services to control the storage used
at run time. Thus COBOL compiler options and Language Environment runtime
options influence the AMODE and RMODE attributes of your program and data, alone
and in combination:
DATA
Compiler option that influences the location of storage for WORKING-STORAGE
data, I-O buffers, and parameter lists for programs compiled with RENT.
RMODE
Compiler option that influences the residency mode and also influences the
location of storage for WORKING-STORAGE data, I-O buffers, and parameter
lists for programs compiled with NORENT.
RENT
Compiler option to generate a reentrant program.
HEAP
Runtime option that controls storage for the runtime heap. For example,
COBOL WORKING-STORAGE is allocated from heap storage in CICS
environments .
STACK
Runtime option that controls storage for the runtime stack. For example,
COBOL LOCAL-STORAGE is allocated from stack storage.
ALL31
Runtime option that specifies whether an application can run entirely in
AMODE 31.
|
|
Settings for RMODE
The RMODE and RENT options determine the RMODE attribute of your program.
|
Table 4. Effect of RMODE and RENT compiler options on the RMODE attribute
|
RMODE compiler option
RENT compiler option
RMODE attribute
|
RMODE(AUTO)
RENT
RMODE ANY
|
RMODE(AUTO)
NORENT
RMODE 24
|
RMODE(24)
RENT or NORENT
RMODE 24
|
RMODE(ANY)
RENT
RMODE ANY
|
RMODE(ANY)
NORENT
Compiler option conflict.
|
|
|
|
|
If the NORENT option is
specified, the RMODE(24)
or RMODE(AUTO) compiler
option must be specified.
Chapter 2. Using data
41
Link-edit considerations: When the object code that COBOL generates has an
attribute of RMODE 24, you must link-edit it with RMODE 24. When the object code
that COBOL generates has an attribute of RMODE ANY, you can link-edit it with
RMODE ANY or RMODE 24.
Location of data areas
For reentrant programs, the DATA compiler optioncontrols whether storage for data
areas such as WORKING-STORAGE SECTION and FD record areas is obtained from below
the 16 MB line or from unrestricted storage. Compile programs with RENT or
RMODE(ANY) if they will be run with 31-bit addressing in virtual storage addresses
above the 16 MB line. The DATA option does not affect programs compiled with
NORENT.
|
Storage for LOCAL-STORAGE data
The location of LOCAL-STORAGE data items is controlled by the STACK runtime
option. LOCAL-STORAGE data items are acquired in unrestricted storage when the
STACK(,,ANYWHERE) runtime option is in effect. Otherwise LOCAL-STORAGE is
acquired below the 16 MB line. The DATA compiler option does not influence the
location of LOCAL-STORAGE data.
Storage for external data
In addition to affecting how storage is obtained for dynamic data areas
(WORKING-STORAGE, FD record areas, and parameter lists), the DATA compiler option
can also influence where storage for EXTERNAL data is obtained. Storage required for
EXTERNAL data is obtained from unrestricted storage if the following conditions are
met:
v The program is compiled with the DATA(31) and RENT compiler options.
v The HEAP(,,ANYWHERE) runtime option is in effect.
v The ALL31(ON) runtime option is in effect.
In all other cases, the storage for EXTERNAL data is obtained from below the 16 MB
line. If you specify the ALL31(ON) runtime option, all the programs in the run unit
must be capable of running in 31-bit addressing mode.
Storage for QSAM input-output buffers
The DATA compiler option can also influence where input-output buffers for QSAM
files are obtained. See the related references below for information about allocation
of buffers for QSAM files and the DATA compiler option.
RELATED CONCEPTS
“AMODE switching” on page 468
Language Environment Programming Guide (AMODE considerations for heap
storage)
RELATED TASKS
Chapter 24, “Using subprograms,” on page 461
Chapter 25, “Sharing data,” on page 481
RELATED REFERENCES
“Allocation of buffers for QSAM files” on page 187
“Allocation of record areas for VSAM files” on page 216
“DATA” on page 326
“RENT” on page 355
|
|
42
Enterprise COBOL for z/OS, V5.1 Programming Guide
“RMODE” on page 357
“Performance-related compiler options” on page 661
Language Environment Programming Reference (HEAP, STACK, ALL31)
MVS Program Management: User's Guide and Reference
Chapter 2. Using data
43
44
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 3. Working with numbers and arithmetic
About this task
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.
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 47
“Controlling how numeric data is stored” on page 48
“Checking for incompatible data (numeric class test)” on page 56
“Performing arithmetic” on page 57
“Using currency signs” on page 67
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 data items.
About this task
For example, Count-y below is a numeric data item, an external decimal item that
has USAGE DISPLAY (a zoned decimal item):
05
05
Count-y
Pic 9(4) Value 25.
Customer-name Pic X(20) Value "Johnson".
You can similarly define numeric data items to hold national characters (UTF-16).
For example, Count-n below is an external decimal data item that has USAGE
NATIONAL (a national decimal item):
05
Count-n
Pic 9(4)
Value 25
Usage National.
You can code up to 18 digits in the PICTURE clause when you compile using the
default compiler option ARITH(COMPAT) (referred to as compatibility mode). When
you compile using ARITH(EXTEND) (referred to as extended mode), you can code up
to 31 digits in the PICTURE clause.
© Copyright IBM Corp. 1991, 2013
45
Other characters of special significance that you can code are:
P
Indicates leading or trailing zeros
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
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 s 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 for a zoned decimal data item as a separate position
in storage. In the following 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 zoned decimal data items that will be printed
or displayed.
Separate signs are required for national decimal data items that are signed. The
sign takes 2 bytes of storage, as in the following example:
05 Price Pic s99V99 Usage National Sign Is Leading, Separate.
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 an
internal floating-point literal:
05
Compute-result
Usage Comp-2
Value 06.23E-24.
For information about external floating-point data, see the examples referenced
below and the related concept about formats for numeric data.
“Examples: numeric data and internal representation” on page 53
RELATED CONCEPTS
“Formats for numeric data” on page 49
Appendix A, “Intermediate results and arithmetic precision,” on page 677
RELATED TASKS
“Displaying numeric data” on page 47
“Controlling how numeric data is stored” on page 48
“Performing arithmetic” on page 57
“Defining national numeric data items” on page 137
RELATED REFERENCES
“Sign representation of zoned and packed-decimal data” on page 55
“Storage of character data” on page 141
“ARITH” on page 318
46
Enterprise COBOL for z/OS, V5.1 Programming Guide
“NUMPROC” on page 347
SIGN clause (Enterprise COBOL Language Reference)
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 items easier to read
and understand when you display or print them.
About this task
For example, in the code below, Edited-price is a numeric-edited item that has
USAGE DISPLAY. (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.)
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), $ 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 can define numeric-edited data items to hold national (UTF-16) characters
instead of alphanumeric characters. To do so, declare the numeric-edited items as
USAGE NATIONAL. The effect of the editing symbols is the same for numeric-edited
items that have USAGE NATIONAL as it is for numeric-edited items that have USAGE
DISPLAY, except that the editing is done with national characters. For example, if
Edited-price is declared as USAGE NATIONAL in the code above, the item is edited
and displayed using national characters.
To display numeric or numeric-edited data items that have USAGE NATIONAL in
EBCDIC, direct them to CONSOLE. For example, if Edited-price in the code above
has USAGE NATIONAL, $ 1,500.99 is displayed when you run the program if the last
statement above is:
Display Edited-price Upon Console
You can cause an elementary numeric or numeric-edited item to be filled with
spaces when a value of zero is stored into it by coding the BLANK WHEN ZERO clause
for the item. For example, each of the DISPLAY statements below causes blanks to
be displayed instead of zeros:
05 Price
Pic
9(5)v99.
05 Edited-price-D Pic $99,999.99
Blank When Zero.
05 Edited-price-N Pic $99,999.99 Usage National
Blank When Zero.
. . .
Move 0 to Price
Move Price to Edited-price-D
Move Price to Edited-price-N
Display Edited-price-D
Display Edited-price-N upon console
You cannot use numeric-edited items as sending operands in arithmetic
expressions or in ADD, SUBTRACT, MULTIPLY, DIVIDE, or COMPUTE statements. (Numeric
editing takes place when a numeric-edited item is the receiving field for one of
Chapter 3. Working with numbers and arithmetic
47
these statements, or when a MOVE statement has a numeric-edited receiving field
and a numeric-edited or numeric sending field.) You use numeric-edited items
primarily for displaying or printing numeric data.
You can move numeric-edited items to numeric or numeric-edited items. In the
following example, the value of the numeric-edited item (whether it has USAGE
DISPLAY or USAGE NATIONAL) is moved to the numeric item:
Move Edited-price to Price
Display Price
If these two statements immediately followed the statements in the first example
above, then Price would be displayed as 0150099, representing the value 1,500.99.
Price would also be displayed as 0150099 if Edited-price had USAGE NATIONAL.
You can also move numeric-edited items to alphanumeric, alphanumeric-edited,
floating-point, and national data items. For a complete list of the valid receiving
items for numeric-edited data, see the related reference about the MOVE statement.
“Examples: numeric data and internal representation” on page 53
RELATED TASKS
“Displaying values on a screen or in a file (DISPLAY)” on page 36
“Controlling how numeric data is stored”
“Defining numeric data” on page 45
“Performing arithmetic” on page 57
“Defining national numeric data items” on page 137
“Converting to or from national (Unicode) representation” on page 142
RELATED REFERENCES
MOVE statement (Enterprise COBOL Language Reference)
BLANK WHEN ZERO clause (Enterprise 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.
About this task
You might want to control the format for any of several reasons such as these:
v Arithmetic performed with computational data types is more efficient than with
USAGE DISPLAY or USAGE NATIONAL data types.
v Packed-decimal format requires less storage per digit than USAGE DISPLAY or
USAGE NATIONAL data types.
v Packed-decimal format converts to and from DISPLAY or NATIONAL 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:
48
Enterprise COBOL for z/OS, V5.1 Programming Guide
v
v
v
v
v
External decimal (USAGE DISPLAY or USAGE NATIONAL)
External floating point (USAGE DISPLAY or USAGE NATIONAL)
Internal decimal (USAGE PACKED-DECIMAL)
Binary (USAGE BINARY)
Native binary (USAGE COMP-5)
v Internal floating point (USAGE COMP-1 or 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 than as
DISPLAY or NATIONAL. For example:
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 internal floating-point data, for which you cannot use a
PICTURE clause).
“Examples: numeric data and internal representation” on page 53
RELATED CONCEPTS
“Formats for numeric data”
“Data format conversions” on page 54
Appendix A, “Intermediate results and arithmetic precision,” on page 677
RELATED TASKS
“Defining numeric data” on page 45
“Displaying numeric data” on page 47
“Performing arithmetic” on page 57
RELATED REFERENCES
“Conversions and precision” on page 54
“Sign representation of zoned and packed-decimal data” on page 55
Formats for numeric data
Several formats are available for numeric data.
External decimal (DISPLAY and NATIONAL) items
When USAGE DISPLAY is in effect for a category numeric data item (either because
you have coded it, or by default), each position (byte) of storage contains one
decimal digit. The items are stored in displayable form. External decimal items that
have USAGE DISPLAY are referred to as zoned decimal data items.
When USAGE NATIONAL is in effect for a category numeric data item, 2 bytes of
storage are required for each decimal digit. The items are stored in UTF-16 format.
External decimal items that have USAGE NATIONAL are referred to as national decimal
data items.
Chapter 3. Working with numbers and arithmetic
49
National decimal data items, if signed, must have the SIGN SEPARATE clause in
effect. All other rules for zoned decimal items apply to national decimal items. You
can use national decimal items anywhere that other category numeric data items
can be used.
External decimal (both zoned decimal and national decimal) data 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 and NATIONAL) items
When USAGE DISPLAY is in effect for a floating-point data item (either because you
have coded it, or by default), each PICTURE character position (except for v, an
implied decimal point, if used) takes 1 byte of storage. The items are stored in
displayable form. External floating-point items that have USAGE DISPLAY are
referred to as display floating-point data items in this information when necessary to
distinguish them from external floating-point items that have USAGE NATIONAL.
In the following example, Compute-Result is implicitly defined as a display
floating-point item:
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.
When USAGE NATIONAL is in effect for a floating-point data item, each PICTURE
character position (except for v, if used) takes 2 bytes of storage. The items are
stored as national characters (UTF-16). External floating-point items that have
USAGE NATIONAL are referred to as national floating-point data items.
The existing rules for display floating-point items apply to national floating-point
items.
In the following example, Compute-Result-N is a national floating-point item:
05
Compute-Result-N
Pic -9v9(9)E-99
Usage National.
If Compute-Result-N is displayed, the signs appear as described above for
Compute-Result, but in national characters. To instead display Compute-Result-N in
EBCDIC characters, direct it to the console:
Display Compute-Result-N Upon Console
You cannot use the VALUE clause for external floating-point items.
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.
50
Enterprise COBOL for z/OS, V5.1 Programming Guide
Binary (COMP) items
BINARY, COMP, and COMP-4 are synonyms. Binary-format numbers occupy 2, 4, or 8
bytes of storage. If the PICTURE clause specifies that an 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
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 that originate in
non-COBOL programs where the data might not conform to a COBOL PICTURE
clause.
The table below shows the ranges of possible values for COMP-5 data items.
Table 5. Ranges in value of 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
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.
Chapter 3. Working with numbers and arithmetic
51
Large literals in VALUE clauses: Literals specified in VALUE clauses for COMP-5 items
can, with a few exceptions, contain values of magnitude up to the capacity of the
native binary representation. See Enterprise COBOL Language Reference for the
exceptions.
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. 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.
Internal 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.
COMP-1 and COMP-2 data items are stored in System z® hexadecimal format.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
Appendix A, “Intermediate results and arithmetic precision,” on page 677
RELATED TASKS
“Defining numeric data” on page 45
“Defining national numeric data items” on page 137
RELATED REFERENCES
“Storage of character data” on page 141
“TRUNC” on page 368
Classes and categories of data (Enterprise COBOL Language Reference)
SIGN clause (Enterprise COBOL Language Reference)
VALUE clause (Enterprise COBOL Language Reference)
52
Enterprise COBOL for z/OS, V5.1 Programming Guide
Examples: numeric data and internal representation
The following table shows the internal representation of numeric items.
Table 6. Internal representation of numeric items
Numeric type
PICTURE and USAGE and
optional SIGN clause
External decimal PIC S9999 DISPLAY
Binary
Value
+ 1234
F1 F2 F3 C4
- 1234
F1 F2 F3 D4
1234
F1 F2 F3 C4
PIC 9999 DISPLAY
1234
F1 F2 F3 F4
PIC 9999 NATIONAL
1234
PIC S9999 DISPLAY
SIGN LEADING
+ 1234
C1 F2 F3 F4
- 1234
D1 F2 F3 F4
PIC S9999 DISPLAY
SIGN LEADING SEPARATE
+ 1234
4E F1 F2 F3 F4
- 1234
60 F1 F2 F3 F4
PIC S9999 DISPLAY
SIGN TRAILING SEPARATE
+ 1234
F1 F2 F3 F4 4E
- 1234
F1 F2 F3 F4 60
PIC S9999 NATIONAL
SIGN LEADING SEPARATE
+ 1234
00 2B 00 31 00 32 00 33 00 34
- 1234
00 2D 00 31 00 32 00 33 00 34
PIC S9999 NATIONAL
SIGN TRAILING SEPARATE
+ 1234
00 31 00 32 00 33 00 34 00 2B
- 1234
00 31 00 32 00 33 00 34 00 2D
PIC S9999 BINARY
PIC S9999 COMP
PIC S9999 COMP-4
+ 1234
04 D2
- 1234
FB 2E
PIC S9999 COMP-5
+ 123451
30 39
1
CF C7
- 12345
00 31 00 32 00 33 00 34
PIC 9999
PIC 9999
PIC 9999
BINARY
COMP
COMP-4
1234
04 D2
PIC 9999
COMP-5
600001
EA 60
Internal decimal PIC S9999 PACKED-DECIMAL
PIC S9999 COMP-3
PIC 9999
PIC 9999
Internal floating
point
Internal representation
PACKED-DECIMAL
COMP-3
COMP-1
COMP-2
External floating PIC +9(2).9(2)E+99 DISPLAY
point
PIC +9(2).9(2)E+99 NATIONAL
+ 1234
01 23 4C
- 1234
01 23 4D
1234
01 23 4F
+ 1234
43 4D 20 00
- 1234
C3 4D 20 00
+ 1234
43 4D 20 00 00 00 00 00
- 1234
C3 4D 20 00 00 00 00 00
+ 12.34E+02
4E F1 F2 4B F3 F4 C5 4E F0 F2
- 12.34E+02
60 F1 F2 4B F3 F4 C5 4E F0 F2
+ 12.34E+02
00 2B 00 31 00 32 00 2E 00 33
00 34 00 45 00 2B 00 30 00 32
- 12.34E+02
00 2D 00 31 00 32 00 2E 00 33
00 34 00 45 00 2B 00 30 00 32
Chapter 3. Working with numbers and arithmetic
53
Table 6. Internal representation of numeric items (continued)
Numeric type
PICTURE and USAGE and
optional SIGN clause
Value
Internal representation
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 that have
different data formats, the compiler converts those items either temporarily, for
comparisons and arithmetic operations, or 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 by using the same rules that are used for MOVE and
COMPUTE statements.
When possible, the compiler performs a move to preserve numeric value instead of
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 provided that the target field can contain
all the digits of the source operand.
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 of zoned and packed-decimal data” on page 55
Conversions and precision
In some numeric conversions, a loss of precision is possible; other conversions
preserve precision or result in rounding.
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 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.
54
Enterprise COBOL for z/OS, V5.1 Programming Guide
Conversions that lose precision
When a USAGE COMP-1 data item is moved to a fixed-point data item that has 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 that has 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 that has 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 that has 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.
RELATED CONCEPTS
Appendix A, “Intermediate results and arithmetic precision,” on page 677
Sign representation of zoned and packed-decimal data
Sign representation affects the processing and interaction of zoned decimal and
internal decimal data.
Given X’sd’, where s is the sign representation and d represents the digit, the valid
sign representations for zoned decimal (USAGE DISPLAY) data without the SIGN IS
SEPARATE clause are:
Positive:
C, A, E, and F
Negative:
D and B
Chapter 3. Working with numbers and arithmetic
55
The COBOL NUMPROC compiler option affects sign processing for zoned decimal and
internal decimal data. NUMPROC has no effect on binary data, national decimal 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, zoned-decimal sender is moved to an alphanumeric
receiver, the sign is unchanged (even with NUMPROC(NOPFD) in effect).
RELATED REFERENCES
“NUMPROC” on page 347
“ZWB” on page 373
Checking for incompatible data (numeric class test)
The compiler assumes that values you supply for a data item are valid for the
PICTURE and USAGE clauses, and does not check their validity. Ensure that the
contents of a data item conform to the PICTURE and USAGE clauses before using the
item in additional processing.
About this task
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 either case, the
receiving fields contain invalid data. 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 are unpredictable.
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"
56
Enterprise COBOL for z/OS, V5.1 Programming Guide
The numeric class test checks the contents of a data item against a set of values
that are valid for the 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 zoned decimal 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.
|
Table 7. NUMCLS(PRIM) and valid signs
|
NUMPROC(NOPFD)
NUMPROC(PFD)
|
Signed
C, D, F
C, D, +0 (positive zero)
|
Unsigned
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.
|
Table 8. NUMCLS(ALT) and valid signs
|
NUMPROC(NOPFD)
NUMPROC(PFD)
|
Signed
A to F
C, D, +0 (positive zero)
|
Unsigned
F
F
|
|
Separate sign
+, -
+, -, +0 (positive zero)
RELATED REFERENCES
“NUMPROC” on page 347
Performing arithmetic
You can use any of several COBOL language features (including COMPUTE,
arithmetic expressions, numeric intrinsic functions, and math and date callable
services) to perform arithmetic. Your choice depends on whether a feature meets
your particular needs.
About this task
For most common arithmetic evaluations, the COMPUTE statement is appropriate. If
you need to use numeric literals, numeric data, or arithmetic operators, you might
want to use arithmetic expressions. In places where numeric expressions are
allowed, you can save time by using numeric intrinsic functions. Language
Environment callable services for mathematical functions and for date and time
operations also provide a means of assigning arithmetic results to data items.
RELATED TASKS
“Using COMPUTE and other arithmetic statements” on page 58
“Using arithmetic expressions” on page 58
Chapter 3. Working with numbers and arithmetic
57
“Using numeric intrinsic functions” on page 59
“Using math-oriented callable services” on page 60
“Using date callable services” on page 62
Using 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 only one COMPUTE
statement instead of several individual arithmetic statements.
About this task
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 calculations 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.
When you perform arithmetic calculations, you can use national decimal data
items as operands just as you use zoned decimal data items. You can also use
national floating-point data items as operands just as you use display
floating-point operands.
RELATED CONCEPTS
“Fixed-point contrasted with floating-point arithmetic” on page 64
Appendix A, “Intermediate results and arithmetic precision,” on page 677
RELATED TASKS
“Defining numeric data” on page 45
Using arithmetic expressions
You can use arithmetic expressions in many (but not all) places in statements
where numeric data items are allowed.
About this task
For example, you can use arithmetic expressions as comparands in relation
conditions:
58
Enterprise COBOL for z/OS, V5.1 Programming Guide
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:
Table 9. Order of evaluation of arithmetic operators
Operator
Meaning
Order of evaluation
Unary + or -
Algebraic sign
First
**
Exponentiation
Second
/ 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, whether necessary or not, make your program easier to read.
RELATED CONCEPTS
“Fixed-point contrasted with floating-point arithmetic” on page 64
Appendix A, “Intermediate results and arithmetic precision,” on page 677
Using 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.
About this task
Numeric intrinsic functions return a signed numeric value, and are treated as
temporary numeric data items.
Numeric functions are classified into the following 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.
Chapter 3. Working with numbers and arithmetic
59
Table 10. Numeric intrinsic functions
Number
handling
LENGTH
MAX
MIN
NUMVAL
NUMVAL-C
ORD-MAX
ORD-MIN
Date and time
Finance
Mathematics
Statistics
CURRENT-DATE
DATE-OF-INTEGER
DATE-TO-YYYYMMDD
DAY-OF-INTEGER
DAY-TO-YYYYDDD
INTEGER-OF-DATE
INTEGER-OF-DAY
WHEN-COMPILED
YEAR-TO-YYYY
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 62
You can reference one function as the argument of another. A nested function is
evaluated independently of the outer function (except when the compiler
determines 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.
For example, in the statement below, there are three function arguments (a, b, and
the arithmetic expression (c / d)):
Compute x = Function Sum(a b (c / d))
You can reference all the elements of a table (or array) as function arguments by
using the ALL subscript.
You can also use the integer special registers as arguments wherever integer
arguments are allowed.
Many of the capabilities of numeric intrinsic functions are also provided by
Language Environment callable services.
RELATED CONCEPTS
“Fixed-point contrasted with floating-point arithmetic” on page 64
Appendix A, “Intermediate results and arithmetic precision,” on page 677
RELATED REFERENCES
“ARITH” on page 318
Using math-oriented callable services
Most COBOL intrinsic functions have corresponding math-oriented callable
services that you can use to produce the same results.
60
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
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.
For example (considering the first row of the table below), 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.
Table 11. Compatibility of math intrinsic functions and callable services
COBOL intrinsic
function
Corresponding
Corresponding
Results same for intrinsic
long-precision Language
extended-precision Language function and callable
Environment callable service Environment callable service service?
ACOS
CEESDACS
CEESQACS
Yes
ASIN
CEESDASN
CEESQASN
Yes
ATAN
CEESDATN
CEESQATN
Yes
COS
CEESDCOS
CEESQCOS
Yes
LOG
CEESDLOG
CEESQLOG
Yes
CEESDLG1
CEESQLG1
Yes
CEERAN0
none
No
REM
CEESDMOD
CEESQMOD
Yes
SIN
CEESDSIN
CEESQSIN
Yes
SQRT
CEESDSQT
CEESQSQT
Yes
TAN
CEESDTAN
CEESQTAN
Yes
LOG10
RANDOM
1
1. RANDOM returns a long (64-bit) floating-point result even if you pass it a 31-digit argument and compile with
ARITH(EXTEND).
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 (generally
COMP-1 or COMP-2) required by that service.
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.
RELATED CONCEPTS
“Fixed-point contrasted with floating-point arithmetic” on page 64
Appendix A, “Intermediate results and arithmetic precision,” on page 677
Chapter 3. Working with numbers and arithmetic
61
RELATED TASKS
“Using Language Environment callable services” on page 669
RELATED REFERENCES
“ARITH” on page 318
Using 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.
About this task
When INTDATE(LILIAN) is in effect, COBOL uses October 15, 1582 as day 1.
Language Environment always uses October 15, 1582 as day 1. If you use
INTDATE(LILIAN), you get equivalent results from COBOL intrinsic functions and
Language Environment date callable services. The following table compares the
results when INTDATE(LILIAN) is in effect.
Table 12. INTDATE(LILIAN) and compatibility of date intrinsic functions and callable
services
Language Environment callable
COBOL intrinsic function 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
When the default setting of INTDATE(ANSI) is in effect, COBOL uses January 1, 1601
as day 1. The following table compares the results when INTDATE(ANSI) is in effect.
Table 13. INTDATE(ANSI) and compatibility of date intrinsic functions and callable
services
Language Environment callable
COBOL intrinsic function 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
RELATED TASKS
“Using Language Environment callable services” on page 669
RELATED REFERENCES
“INTDATE” on page 339
Examples: numeric intrinsic functions
The following examples and accompanying explanations show intrinsic functions
in each of several categories.
62
Enterprise COBOL for z/OS, V5.1 Programming Guide
Where the examples below show zoned decimal data items, national decimal items
could instead be used. (Signed national decimal items, however, require that the
SIGN SEPARATE clause be in effect.)
General number handling
Suppose you want to find the maximum value of two prices (represented below 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 or national
literal, or an alphanumeric or national data item) and the MAX and LENGTH functions
to do so:
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.
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
Series-Amt2
Series-Amt3
Discount-Rate
Todays-Value
Pic
Pic
Pic
Pic
Pic
9(9)V99
9(9)V99
9(9)V99
S9(2)V9(6)
9(9)V99.
Value
Value
Value
Value
100.
200.
300.
.10.
Chapter 3. Working with numbers and arithmetic
63
. . .
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
. .
Tax-S
Pic
Tax-T
Pic
Tax-W
Pic
Tax-B
Pic
Ave-Tax
Pic
Median-Tax
Pic
Tax-Range
Pic
.
Compute Ave-Tax
=
Compute Median-Tax =
Compute Tax-Range =
99v999 value
99v999 value
99v999 value
99v999 value
99v999.
99v999.
99v999.
.045.
.02.
.035.
.03.
Function Mean
(Tax-S Tax-T Tax-W Tax-B)
Function Median (Tax-S Tax-T Tax-W Tax-B)
Function Range (Tax-S Tax-T Tax-W Tax-B)
RELATED TASKS
“Converting to numbers (NUMVAL, NUMVAL-C)” on page 122
Fixed-point contrasted with floating-point arithmetic
How you code arithmetic in a program (whether an arithmetic statement, an
intrinsic function, an expression, or some combination of these nested within each
other) determines whether the evaluation is done with floating-point or fixed-point
arithmetic.
64
Enterprise COBOL for z/OS, V5.1 Programming Guide
Many statements in a 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)
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.
An operand is floating point if you code it as a floating-point literal or if you
code it as a data item that is defined as USAGE COMP-1, USAGE COMP-2, or external
floating point (USAGE DISPLAY or USAGE NATIONAL 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
conditions 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 that contains decimal places, or use an arithmetic
expression or function whose result has decimal places.
An arithmetic expression or numeric function yields a result that has 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 causes 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.
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
Chapter 3. Working with numbers and arithmetic
65
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 685
Examples: fixed-point and floating-point evaluations
The following example shows statements that are evaluated using fixed-point
arithmetic and using floating-point arithmetic.
Assume that 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:
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)
66
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 several
currency signs in a program.
About this task
You can use one or more of the following signs:
v Symbols such as the dollar sign ($)
v Currency signs of more than one character (such as USD or 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 those 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. Using a
hexadecimal literal 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 hexadecimal 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.
Table 14. Hexadecimal values of the euro sign
Code page
CCSID
Modified
from
Applicable countries
Euro sign
1140
USA, Canada, Netherlands, Portugal, Australia, 037
New Zealand
X'9F'
1141
Austria, Germany
273
X'9F'
1142
Denmark, Norway
277
X'5A'
1143
Finland, Sweden
278
X'5A'
1144
Italy
280
X'9F'
1145
Spain, Latin America - Spanish
284
X'9F'
Chapter 3. Working with numbers and arithmetic
67
Table 14. Hexadecimal values of the euro sign (continued)
Code page
CCSID
Applicable countries
Modified
from
Euro sign
1146
UK
285
X'9F'
1147
France
297
X'9F'
1148
Belgium, Canada, Switzerland
500
X'9F'
1149
Iceland
871
X'9F'
RELATED REFERENCES
“CURRENCY” on page 325
CURRENCY SIGN clause (Enterprise COBOL Language Reference)
Example: multiple currency signs
The following example shows how you can display values in both euro currency
(as EUR) and Swiss francs (as CHF).
IDENTIFICATION DIVISION.
PROGRAM-ID. EuroSamp.
Environment Division.
Configuration Section.
Special-Names.
Currency Sign is "CHF " 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-CHF
Pic S99999V99.
01 Deposit-Report.
02 Report-in-Franc
Pic -FFFFF9.99.
02 Report-in-Euro
Pic -UUUUU9.99.
01 EUR-to-CHF-Conv-Rate
Pic 9V99999 Value 1.53893.
. . .
PROCEDURE DIVISION.
Report-Deposit-in-CHF-and-EUR.
Move Deposit-in-Euro to Report-in-Euro
Compute Deposit-in-CHF Rounded
= Deposit-in-Euro * EUR-to-CHF-Conv-Rate
On Size Error
Perform Conversion-Error
Not On Size Error
Move Deposit-in-CHF 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 CHF"
Display "Euro value: " Report-in-Euro.
The above example produces the following display output:
Deposit in euro = EUR 8000.00
Deposit in franc = CHF 12311.44
The exchange rate used in this example is for illustrative purposes only.
68
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 4. Handling tables
About this task
A table is a collection of data items that have the same description, such as account
totals or monthly averages. A table consists of a table name and subordinate items
called table elements. A table is the COBOL equivalent of an array.
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 defining repetitious items as separate, consecutive entries in the DATA
DIVISION, you 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 a program
that looks up records.
RELATED CONCEPTS
“Complex OCCURS DEPENDING ON” on page 84
RELATED TASKS
|
“Nesting tables” on page 71
“Defining a table (OCCURS)”
“Referring to an item in a table” on page 73
“Putting values into a table” on page 75
“Creating variable-length tables (DEPENDING ON)” on page 81
“Searching a table” on page 88
“Processing table items using intrinsic functions” on page 91
“Handling tables efficiently” on page 657
“Working with unbounded tables and groups” on page 92
Defining a table (OCCURS)
To code a table, give the table a group name and define a subordinate item (the
table element) to be repeated n times.
© Copyright IBM Corp. 1991, 2013
69
About this task
01
table-name.
05 element-name OCCURS n TIMES.
. . . (subordinate items of the table element)
In the example above, table-name is the name of an alphanumeric group item. The
table element definition (which includes the OCCURS clause) is subordinate to the
group item that contains the table. The OCCURS clause cannot be used in a level-01
description.
If a table is to contain only Unicode (UTF-16) data, and you want the group item
that contains the table to behave like an elementary category national item in most
operations, code the GROUP-USAGE NATIONAL clause for the group item:
01
table-nameN Group-Usage National.
05 element-nameN OCCURS m TIMES.
10 elementN1 Pic nn.
10 elementN2 Pic S99 Sign Is Leading, Separate.
. . .
Any elementary item that is subordinate to a national group must be explicitly or
implicitly described as USAGE NATIONAL, and any subordinate numeric data item
that is signed must be implicitly or explicitly described with the SIGN IS SEPARATE
clause.
To create tables of two to seven dimensions, use nested OCCURS clauses.
To create a variable-length table, code the DEPENDING ON phrase of the OCCURS
clause.
To specify that table elements will be arranged in ascending or descending order
based on the values in one or more key fields of the table, code the ASCENDING or
DESCENDING KEY phrases of the OCCURS clause, or both. Specify the names of the
keys in decreasing order of significance. Keys can be of class alphabetic,
alphanumeric, DBCS, national, or numeric. (If it has USAGE NATIONAL, a key can be
of category national, or can be a national-edited, numeric-edited, national decimal,
or national floating-point item.)
You must code the ASCENDING or DESCENDING KEY phrase of the OCCURS clause to do
a binary search (SEARCH ALL) of a table.
“Example: binary search” on page 90
RELATED CONCEPTS
“National groups” on page 137
RELATED TASKS
“Nesting tables” on page 71
“Referring to an item in a table” on page 73
“Putting values into a table” on page 75
“Creating variable-length tables (DEPENDING ON)” on page 81
“Using national groups” on page 139
“Doing a binary search (SEARCH ALL)” on page 90
“Defining numeric data” on page 45
RELATED REFERENCES
OCCURS clause (Enterprise COBOL Language Reference)
SIGN clause (Enterprise COBOL Language Reference)
70
Enterprise COBOL for z/OS, V5.1 Programming Guide
ASCENDING KEY and DESCENDING KEY phrases
(Enterprise COBOL Language Reference)
Nesting tables
To create a two-dimensional table, define a one-dimensional table in each
occurrence of another one-dimensional table.
About this task
For example, in SAMPLE-TABLE-TWO above, 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.
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.
“Example: subscripting” on page 72
“Example: indexing” on page 72
RELATED TASKS
“Defining a table (OCCURS)” on page 69
“Referring to an item in a table” on page 73
“Putting values into a table” on page 75
“Creating variable-length tables (DEPENDING ON)” on page 81
Chapter 4. Handling tables
71
“Searching a table” on page 88
“Processing table items using intrinsic functions” on page 91
“Handling tables efficiently” on page 657
RELATED REFERENCES
OCCURS clause (Enterprise COBOL Language Reference)
Example: subscripting
The following example shows valid references to SAMPLE-TABLE-THREE that use
literal subscripts. The spaces are required in the second example.
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)
RELATED TASKS
“Subscripting” on page 73
Example: indexing
The following example shows how displacements to elements that are referenced
with indexes are calculated.
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
“Indexing” on page 74
72
Enterprise COBOL for z/OS, V5.1 Programming Guide
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.
About this task
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.
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 (as a displacement from the
beginning of the table). This technique is called indexing, or subscripting using
index-names.
v Use both subscripts and indexes together.
RELATED TASKS
“Subscripting”
“Indexing” on page 74
Subscripting
The lowest possible subscript value is 1, which references the first occurrence of a
table element. In a one-dimensional table, the subscript corresponds to the row
number.
About this task
You can use a literal or a data-name as a subscript. If a data item that has 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 that is 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. To do so,
refer to the character position and length of the substring to be changed. 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 in the example above moves the string '??' into table element
number 1, beginning at character position 3, for a length of 2 characters.
Chapter 4. Handling tables
73
“Example: subscripting” on page 72
RELATED TASKS
“Indexing”
“Putting values into a table” on page 75
“Searching a table” on page 88
“Handling tables efficiently” on page 657
Indexing
You create an index by using the INDEXED BY phrase of the OCCURS clause to
identify an index-name.
About this task
For example, INX-A in the following code is an index-name:
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 an index-name to reference another table only if both table
descriptions have the same number of table elements, and the table elements are of
the same length.
You can use the USAGE IS INDEX clause to create an index data item, and can use
an index data item with any table. For example, INX-B in the following code is an
index data item:
77 INX-B USAGE IS INDEX.
. . .
SET INX-A TO 10
SET INX-B TO INX-A.
PERFORM VARYING INX-A FROM 1 BY 1 UNTIL INX-A > INX-B
DISPLAY TABLE-ITEM (INX-A)
. . .
END-PERFORM.
The index-name INX-A is used to traverse table TABLE-ITEM above. The index data
item INX-B is used to hold the index of the last element of the table. The advantage
of this type of coding is that calculation of offsets of table elements is minimized,
and no conversion is necessary for the UNTIL condition.
You can use the SET statement to assign to an index data item the value that you
stored in an index-name, as in the statement SET INX-B TO INX-A above. For
example, when you load records into a variable-length table, you can store the
index value of the last record into a data item defined as USAGE IS INDEX. Then
74
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 a table.
You can increment or decrement an index-name by an elementary integer data
item or a nonzero integer literal, for example:
SET INX-A DOWN BY 3
The integer represents a number of occurrences. It is converted to an index value
before being added to or subtracted from the index.
Initialize the index-name by using a SET, PERFORM VARYING, or SEARCH ALL
statement. You can then use the index-name in SEARCH or relational condition
statements. To change the value, use a PERFORM, SEARCH, or SET statement.
Because you are comparing a physical displacement, you can directly use index
data items only in SEARCH and SET statements or in comparisons with indexes or
other index data items. You cannot use index data items as subscripts or indexes.
“Example: indexing” on page 72
RELATED TASKS
“Subscripting” on page 73
“Putting values into a table”
“Searching a table” on page 88
“Processing table items using intrinsic functions” on page 91
“Handling tables efficiently” on page 657
RELATED REFERENCES
INDEXED BY phrase (Enterprise COBOL Language Reference)
INDEX phrase (Enterprise COBOL Language Reference)
SET statement (Enterprise COBOL Language Reference)
Putting values into a table
You can put values into a table by loading the table dynamically, initializing the
table with the INITIALIZE statement, or assigning values with the VALUE clause
when you define the table.
About this task
RELATED TASKS
“Loading a table dynamically”
“Loading a variable-length table” on page 83
“Initializing a table (INITIALIZE)” on page 76
“Assigning values when you define a table (VALUE)” on page 77
“Assigning values to a variable-length table” on page 84
Loading a table dynamically
If the initial values of a table are different with each execution of your program,
you can define the table without initial values. You can instead read the changed
values into the table dynamically before the program refers to the table.
Chapter 4. Handling tables
75
About this task
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 maximum 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 79
“Example: PERFORM and indexing” on page 80
RELATED REFERENCES
PERFORM statement (Enterprise COBOL Language Reference)
Initializing a table (INITIALIZE)
You can load a table by coding one or more INITIALIZE statements.
About this task
For example, to move the value 3 into each of the elementary numeric data items
in a table called TABLE-ONE, shown below, you can code the following statement:
INITIALIZE TABLE-ONE REPLACING NUMERIC DATA BY 3.
To move the character 'X' into each of the elementary alphanumeric data items in
TABLE-ONE, you can code the following statement:
INITIALIZE TABLE-ONE REPLACING ALPHANUMERIC DATA BY "X".
When you use the INITIALIZE statement to initialize a table, the table is processed
as a group item (that is, with group semantics); elementary data items within the
group are recognized and processed. For example, suppose that TABLE-ONE is an
alphanumeric group that is defined like this:
01 TABLE-ONE.
02 Trans-out Occurs 20.
05 Trans-code
Pic X
Value "R".
05 Part-number
Pic XX
Value "13".
05 Trans-quan
Pic 99
Value 10.
05 Price-fields.
10 Unit-price
Pic 99V Value 50.
10 Discount
Pic 99V Value 25.
10 Sales-Price Pic 999 Value 375.
. . .
Initialize TABLE-ONE Replacing Numeric Data By 3
Alphanumeric Data By "X"
The table below shows the content that each of the twenty 12-byte elements
Trans-out(n) has before execution and after execution of the INITIALIZE statement
shown above:
Trans-out(n) before
Trans-out(n) after
R13105025375
XXb0303030031
1. The symbol b represents a blank space.
You can similarly use an INITIALIZE statement to load a table that is defined as a
national group. For example, if TABLE-ONE shown above specified the GROUP-USAGE
76
Enterprise COBOL for z/OS, V5.1 Programming Guide
NATIONAL clause, and Trans-code and Part-number had N instead of X in their
PICTURE clauses, the following statement would have the same effect as the
INITIALIZE statement above, except that the data in TABLE-ONE would instead be
encoded in UTF-16:
Initialize TABLE-ONE Replacing Numeric Data By 3
National Data By N"X"
The REPLACING NUMERIC phrase initializes floating-point data items also.
You can use the REPLACING phrase of the INITIALIZE statement similarly to
initialize all of the elementary ALPHABETIC, DBCS, ALPHANUMERIC-EDITED,
NATIONAL-EDITED, and NUMERIC-EDITED data items in a table.
The INITIALIZE statement cannot assign values to a variable-length table (that is, a
table that was defined using the OCCURS DEPENDING ON clause).
“Examples: initializing data items” on page 28
RELATED TASKS
“Initializing a structure (INITIALIZE)” on page 31
“Assigning values when you define a table (VALUE)”
“Assigning values to a variable-length table” on page 84
“Looping through a table” on page 108
“Using data items and group items” on page 24
“Using national groups” on page 139
RELATED REFERENCES
INITIALIZE statement (Enterprise COBOL Language Reference)
Assigning values when you define a table (VALUE)
If a table is to contain stable values (such as days and months), you can set the
specific values when you define the table.
About this task
Set static values in tables in one of these ways:
v Initialize each table item individually.
v Initialize an entire table at the group level.
v Initialize all occurrences of a given table element to the same value.
RELATED TASKS
“Initializing
“Initializing
“Initializing
“Initializing
each table item individually”
a table at the group level” on page 78
all occurrences of a given table element” on page 79
a structure (INITIALIZE)” on page 31
Initializing each table item individually
If a table is small, you can set the value of each item individually by using a VALUE
clause.
About this task
Use the following technique, which is shown in the example code below:
Chapter 4. Handling tables
77
Procedure
1. Declare a record (such as Error-Flag-Table below) that contains the items that
are to be in the 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.
Results
***********************************************************
***
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 the example above, the VALUE clause at the 01 level initializes each of the table
items to the same value. Each table item could instead be described with its own
VALUE clause to initialize that item to a distinct value.
To initialize larger tables, use MOVE, PERFORM, or INITIALIZE statements.
RELATED TASKS
“Initializing a structure (INITIALIZE)” on page 31
“Assigning values to a variable-length table” on page 84
RELATED REFERENCES
REDEFINES clause (Enterprise COBOL Language Reference)
OCCURS clause (Enterprise COBOL Language Reference)
Initializing a table at the group level
Code an alphanumeric or national group data item and assign to it, through the
VALUE clause, the contents of the whole table. Then, in a subordinate data item, use
an OCCURS clause to define the individual table items.
About this task
In the following example, the alphanumeric group data item TABLE-ONE uses a
VALUE clause that initializes each of the four elements of TABLE-TWO:
01
TABLE-ONE
05 TABLE-TWO OCCURS 4 TIMES
VALUE "1234".
PIC X.
In the following example, the national group data item Table-OneN uses a VALUE
clause that initializes each of the three elements of the subordinate data item
Table-TwoN (each of which is implicitly USAGE NATIONAL). Note that you can
initialize a national group data item with a VALUE clause that uses an alphanumeric
literal, as shown below, or a national literal.
78
Enterprise COBOL for z/OS, V5.1 Programming Guide
01
Table-OneN Group-Usage National
05 Table-TwoN Occurs 3 Times
10 ElementOneN Pic nn.
10 ElementTwoN Pic 99.
Value "AB12CD34EF56".
Indexed By MyI.
After Table-OneN is initialized, ElementOneN(1) contains NX"00410042" (the UTF-16
representation of 'AB'), the national decimal item ElementTwoN(1) contains
NX"00310032" (the UTF-16 representation of '12'), and so forth.
RELATED REFERENCES
OCCURS clause (Enterprise COBOL Language Reference)
GROUP-USAGE clause (Enterprise COBOL Language Reference)
Initializing all occurrences of a given table element
You can use the VALUE clause in the data description of a table element to initialize
all instances of that element to the specified value.
About this task
01
T2.
05 T-OBJ
PIC 9
05 T OCCURS 5 TIMES
DEPENDING ON T-OBJ.
10 X
PIC XX
10 Y
PIC 99
10 Z
PIC XX
VALUE 3.
VALUE "AA".
VALUE 19.
VALUE "BB".
For example, the code above 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.
RELATED TASKS
“Assigning values to a variable-length table” on page 84
RELATED REFERENCES
OCCURS clause (Enterprise 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
Indexed By Flag-Index
Pic X.
77 Error-on
Pic X Value "E".
***********************************************************
***
E R R O R
M E S S A G E
T A B L E
***
***********************************************************
Chapter 4. Handling tables
79
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
. . .
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.
77 Error-on
Pic X Value "E".
***********************************************************
***
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.".
80
Enterprise COBOL for z/OS, V5.1 Programming Guide
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
. . .
Creating variable-length tables (DEPENDING ON)
If you do not know before run time how many times a table element occurs, define
a variable-length table. To do so, use the OCCURS DEPENDING ON (ODO) clause.
About this task
X OCCURS 1 TO 10 TIMES DEPENDING ON Y
In the example above, X is called the ODO subject, and Y is called the ODO object.
|
|
You can also specify unbounded tables and groups, see Variable-length tables in
the Enterprise COBOL Language Reference for details.
Two factors affect the successful manipulation of variable-length records:
v Correct calculation of record lengths
The length of the variable portions of a group item is the product of the object
of the DEPENDING ON phrase 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 terminate abnormally. 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
PIC 9.
Chapter 4. Handling tables
81
01
DEPENDING ON FIELD-1
REC-2.
03 REC-2-DATA
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 clause (that is, if FIELD-1
contains a zoned 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, five
occurrences of FIELD-2, plus FIELD-1, yields a length of 26 bytes. In this case, you
do not need to 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.
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, using the current value of the
ODO object (FIELD-1). 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:
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).
The compiler issues a message that lets 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 (LOCATION-TABLE-LENGTH below) 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.
***
82
Enterprise COBOL for z/OS, V5.1 Programming Guide
*****************************************************************
01 LOCATION-TABLE.
05 LOCATION-CODE OCCURS 1 TO 100 TIMES
DEPENDING ON LOCATION-TABLE-LENGTH
PIC X(80).
RELATED CONCEPTS
“Complex OCCURS DEPENDING ON” on page 84
RELATED TASKS
“Assigning values to a variable-length table” on page 84
“Loading a variable-length table”
“Preventing overlay when adding elements to a variable table” on page 87
“Finding the length of data items” on page 126
Enterprise COBOL Migration Guide
RELATED REFERENCES
|
|
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Variable-length tables (Enterprise COBOL Language Reference)
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.
About this task
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)
Chapter 4. Handling tables
83
Read Location-File
At End Set Location-EOF To True
End-Read
End-Perform
Assigning values to a variable-length table
You can code a VALUE clause for an alphanumeric or national group item that has a
subordinate data item that contains the OCCURS clause with the DEPENDING ON
phrase. Each subordinate structure that contains the DEPENDING ON phrase is
initialized using the maximum number of occurrences.
About this task
If you define the entire table by using the DEPENDING ON phrase, all the elements
are initialized using the maximum defined value of the ODO (OCCURS DEPENDING
ON) object.
If the ODO object is initialized by a VALUE clause, it is logically initialized after the
ODO subject has been initialized.
01
TABLE-THREE
VALUE "3ABCDE".
05 X
PIC 9.
05 Y OCCURS 5 TIMES
DEPENDING ON X PIC X.
For example, in the code above, 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 X and the first
three elements, Y(1) through Y(3), of the table.
RELATED TASKS
“Assigning values when you define a table (VALUE)” on page 77
RELATED REFERENCES
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Complex OCCURS DEPENDING ON
Several types of complex OCCURS DEPENDING ON (complex ODO) are possible.
Complex ODO is supported as an extension to Standard COBOL 85.
The basic forms of complex ODO permitted by the compiler are as follows:
v Variably located item or group: A data item described by an OCCURS clause with
the DEPENDING ON phrase is followed by a nonsubordinate elementary or group
data item.
v Variably located table: A data item described by an OCCURS clause with the
DEPENDING ON phrase is followed by a nonsubordinate data item described by an
OCCURS clause.
v Table that has variable-length elements: A data item described by an OCCURS
clause contains a subordinate data item described by an OCCURS clause with the
DEPENDING ON phrase.
v Index name for a table that has variable-length elements.
v Element of a table that has variable-length elements.
“Example: complex ODO” on page 85
84
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED TASKS
“Preventing index errors when changing ODO object value” on page 86
“Preventing overlay when adding elements to a variable table” on page 87
RELATED REFERENCES
“Effects of change in ODO object value” on page 86
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Example: complex ODO
The following example illustrates the possible types of occurrence of complex
ODO.
01
FIELD-A.
02 COUNTER-1
02 COUNTER-2
02 TABLE-1.
03 RECORD-1 OCCURS 1 TO 5 TIMES
DEPENDING ON COUNTER-1
02 EMPLOYEE-NUMBER
02 TABLE-2 OCCURS 5 TIMES
INDEXED BY INDX.
03 TABLE-ITEM
03 RECORD-2 OCCURS 1 TO 3 TIMES
DEPENDING ON COUNTER-2.
04 DATA-NUM
PIC S99.
PIC S99.
PIC X(3).
PIC X(5). (1)
(2)(3)
(4)
PIC 99.
(5)
PIC S99.
Definition: In the example, COUNTER-1 is an ODO object, that is, it is the object of
the DEPENDING ON clause of RECORD-1. RECORD-1 is said to be an ODO subject.
Similarly, COUNTER-2 is the ODO object of the corresponding ODO subject,
RECORD-2.
The types of complex ODO occurrences shown in the example above are as
follows:
(1)
A variably located item: EMPLOYEE-NUMBER is a data item that follows, but is
not subordinate to, a variable-length table in the same level-01 record.
(2)
A variably located table: TABLE-2 is a table that follows, but is not
subordinate to, a variable-length table in the same level-01 record.
(3)
A table with variable-length elements: TABLE-2 is a table that contains a
subordinate data item, RECORD-2, whose number of occurrences varies
depending on the content of its ODO object.
(4)
An index-name, INDX, for a table that has variable-length elements.
(5)
An element, TABLE-ITEM, of a table that has variable-length elements.
How length is calculated
The length of the variable portion of each record is the product of its ODO object
and the length of its ODO subject. For example, whenever a reference is made to
one of the complex ODO items shown above, the actual length, if used, is
computed as follows:
v The length of TABLE-1 is calculated by multiplying the contents of COUNTER-1 (the
number of occurrences of RECORD-1) by 3 (the length of RECORD-1).
v The length of TABLE-2 is calculated by multiplying the contents of COUNTER-2 (the
number of occurrences of RECORD-2) by 2 (the length of RECORD-2), and adding
the length of TABLE-ITEM.
v The length of FIELD-A is calculated by adding the lengths of COUNTER-1,
COUNTER-2, TABLE-1, EMPLOYEE-NUMBER, and TABLE-2 times 5.
Chapter 4. Handling tables
85
Setting values of ODO objects
You must set every ODO object in a group item before you reference any complex
ODO item in the group. For example, before you refer to EMPLOYEE-NUMBER in the
code above, you must set COUNTER-1 and COUNTER-2 even though EMPLOYEE-NUMBER
does not directly depend on either ODO object for its value.
Restriction: An ODO object cannot be variably located.
Effects of change in ODO object value
If a data item that is described by an OCCURS clause with the DEPENDING ON phrase
is followed in the same group by one or more nonsubordinate data items (a form
of complex ODO), any change in value of the ODO object affects subsequent
references to complex ODO items in the record.
For example:
v The size of any group that contains the relevant ODO clause reflects the new
value of the ODO object.
v A MOVE to a group that contains the ODO subject is made based on the new
value of the ODO object.
v The location of any nonsubordinate items that follow the item described with
the ODO clause is affected by the new value of the ODO object. (To preserve the
contents of the nonsubordinate items, move them to a work area before the
value of the ODO object changes, then move them back.)
The value of an ODO object can change when you move data to the ODO object or
to the group in which it is contained. The value can also change if the ODO object
is contained in a record that is the target of a READ statement.
RELATED TASKS
“Preventing index errors when changing ODO object value”
“Preventing overlay when adding elements to a variable table” on page 87
Preventing index errors when changing ODO object value
Be careful if you reference a complex-ODO index-name, that is, an index-name for
a table that has variable-length elements, after having changed the value of the
ODO object for a subordinate data item in the table.
About this task
When you change the value of an ODO object, the byte offset in an associated
complex-ODO index is no longer valid because the table length has changed.
Unless you take precautions, you will have unexpected results if you then code a
reference to the index-name such as:
v A reference to an element of the table
v A SET statement of the form SET integer-data-item TO index-name (format 1)
v A SET statement of the form SET index-name UP|DOWN BY integer (format 2)
To avoid this type of error, do these steps:
Procedure
1. Save the index in an integer data item. (Doing so causes an implicit conversion:
the integer item receives the table element occurrence number that corresponds
to the offset in the index.)
86
Enterprise COBOL for z/OS, V5.1 Programming Guide
2. Change the value of the ODO object.
3. Immediately restore the index from the integer data item. (Doing so causes an
implicit conversion: the index-name receives the offset that corresponds to the
table element occurrence number in the integer item. The offset is computed
according to the table length then in effect.)
Results
The following code shows how to save and restore the index-name (shown in
“Example: complex ODO” on page 85) when the ODO object COUNTER-2 changes.
77 INTEGER-DATA-ITEM-1
PIC 99.
. . .
SET INDX TO 5.
*
INDX is valid at this point.
SET INTEGER-DATA-ITEM-1 TO INDX.
*
INTEGER-DATA-ITEM-1 now has the
*
occurrence number that corresponds to INDX.
MOVE NEW-VALUE TO COUNTER-2.
*
INDX is not valid at this point.
SET INDX TO INTEGER-DATA-ITEM-1.
*
INDX is now valid, containing the offset
*
that corresponds to INTEGER-DATA-ITEM-1, and
*
can be used with the expected results.
RELATED REFERENCES
SET statement (Enterprise COBOL Language Reference)
Preventing overlay when adding elements to a variable table
Be careful if you increase the number of elements in a variable-occurrence table
that is followed by one or more nonsubordinate data items in the same group.
When you increment the value of the ODO object and add an element to a table,
you can inadvertently overlay the variably located data items that follow the table.
About this task
To avoid this type of error, do these steps:
Procedure
1.
2.
3.
4.
Save the variably located data items that follow the table in another data area.
Increment the value of the ODO object.
Move data into the new table element (if needed).
Restore the variably located data items from the data area where you saved
them.
Results
In the following example, suppose you want to add an element to the table
VARY-FIELD-1, whose number of elements depends on the ODO object CONTROL-1.
VARY-FIELD-1 is followed by the nonsubordinate variably located data item
GROUP-ITEM-1, whose elements could potentially be overlaid.
WORKING-STORAGE SECTION.
01 VARIABLE-REC.
05 FIELD-1
05 CONTROL-1
05 CONTROL-2
05 VARY-FIELD-1 OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-1
05 GROUP-ITEM-1.
PIC X(10).
PIC S99.
PIC S99.
PIC X(5).
Chapter 4. Handling tables
87
10
VARY-FIELD-2
OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-2
01 STORE-VARY-FIELD-2.
05 GROUP-ITEM-2.
10 VARY-FLD-2
OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-2
PIC X(9).
PIC X(9).
Each element of VARY-FIELD-1 has 5 bytes, and each element of VARY-FIELD-2 has 9
bytes. If CONTROL-1 and CONTROL-2 both contain the value 3, you can picture storage
for VARY-FIELD-1 and VARY-FIELD-2 as follows:
VARY-FIELD-1(1)
VARY-FIELD-1(2)
VARY-FIELD-1(3)
VARY-FIELD-2(1)
VARY-FIELD-2(2)
VARY-FIELD-2(3)
To add a fourth element to VARY-FIELD-1, code as follows to prevent overlaying the
first 5 bytes of VARY-FIELD-2. (GROUP-ITEM-2 serves as temporary storage for the
variably located GROUP-ITEM-1.)
MOVE GROUP-ITEM-1 TO GROUP-ITEM-2.
ADD 1 TO CONTROL-1.
MOVE five-byte-field TO
VARY-FIELD-1 (CONTROL-1).
MOVE GROUP-ITEM-2 TO GROUP-ITEM-1.
You can picture the updated storage for VARY-FIELD-1 and VARY-FIELD-2 as follows:
VARY-FIELD-1(1)
VARY-FIELD-1(2)
VARY-FIELD-1(3)
VARY-FIELD-1(4)
VARY-FIELD-2(1)
VARY-FIELD-2(2)
VARY-FIELD-2(3)
Note that the fourth element of VARY-FIELD-1 did not overlay the first element of
VARY-FIELD-2.
Searching a table
COBOL provides two search techniques for tables: serial and binary.
About this task
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
88
Enterprise COBOL for z/OS, V5.1 Programming Guide
the table. For a binary search, the number of comparisons is of the order of only
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 90
Doing a serial search (SEARCH)
Use the SEARCH statement to do a serial (sequential) search beginning at the current
index setting. To modify the index setting, use the SET statement.
About this task
The conditions in the WHEN phrase 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 did not code AT END,
control passes to the next statement in the 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.
Performance: If the found condition comes after some intermediate point in the
table, you can speed up the search by using 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 of the table also enables more efficient serial searching. If
the table is large and is presorted, a binary search is more efficient.
“Example: serial search”
RELATED REFERENCES
SEARCH statement (Enterprise COBOL Language Reference)
Example: serial search
The following example shows how you might find a particular string in the
innermost table of a three-dimensional table.
Each dimension of the table has its own index (set to 1, 4, and 1, respectively). The
innermost table (TABLE-ENTRY3) has an ascending key.
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.
. . .
Chapter 4. Handling tables
89
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)
If you use SEARCH ALL to do a binary search, you do not need to set the index
before you begin. The index is always the one that is associated with the first
index-name in the OCCURS clause. The index varies during execution to maximize
the search efficiency.
About this task
To use the SEARCH ALL statement to search a table, the table must specify the
ASCENDING or DESCENDING KEY phrases of the OCCURS clause, or both, and must
already be ordered on the key or keys that are specified in the ASCENDING and
DESCENDING KEY phrases.
In the WHEN phrase of the SEARCH ALL statement, you can test any key that is named
in the ASCENDING or DESCENDING KEY phrases for the table, but you must test all
preceding keys, if any. The test must be an equal-to condition, and the WHEN phrase
must specify either a key (subscripted by the first index-name associated with the
table) or a condition-name that is associated with the key. The WHEN condition can
be a compound condition that is formed from simple conditions that use AND as the
only logical connective.
Each key and its object of comparison must be compatible according to the rules
for comparison of data items. Note though that if a key is compared to a national
literal or identifier, the key must be a national data item.
“Example: binary search”
RELATED TASKS
“Defining a table (OCCURS)” on page 69
RELATED REFERENCES
SEARCH statement (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
Example: binary search
The following example shows how you can code a binary search of a table.
90
Enterprise COBOL for z/OS, V5.1 Programming Guide
Suppose you define a table that contains 90 elements of 40 bytes each, and 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 by using the following statements:
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 each of the three keys is equal to the value to which
it is compared (VALUE-1, VALUE-2, and VALUE-3, respectively), PART-1 of that entry is
moved to OUTPUT-AREA. If no matching key is found in the entries in TABLE-A, the
NOENTRY routine is performed.
Processing table items using intrinsic functions
You can use intrinsic functions to process alphabetic, alphanumeric, national, or
numeric table items. (You can process DBCS data items only with the NATIONAL-OF
intrinsic function.) The data descriptions of the table items must be compatible
with the requirements for the function arguments.
About this task
Use a subscript or index to reference an individual data item as a function
argument. For example, assuming that Table-One is a 3 x 3 array of numeric items,
you can find the square root of the middle element by using this statement:
Compute X = Function Sqrt(Table-One(2,2))
You might often need to iteratively process the data in tables. For intrinsic
functions that accept multiple arguments, you can use the subscript ALL to
reference all the items in the table or in a single dimension of the table. The
iteration is handled automatically, which can make 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: processing tables using intrinsic functions” on page 92
RELATED TASKS
“Using intrinsic functions (built-in functions)” on page 39
Chapter 4. Handling tables
91
“Converting data items (intrinsic functions)” on page 120
“Evaluating data items (intrinsic functions)” on page 123
RELATED REFERENCES
Intrinsic functions (Enterprise COBOL Language Reference)
Example: processing tables using intrinsic functions
These examples show how you can apply an intrinsic function to some or all of the
elements in a table by using the ALL subscript.
Assuming that Table-Two is a 2 x 3 x 2 array, the following statement adds the
values in elements Table-Two(1,3,1), Table-Two(1,3,2), Table-Two(2,3,1), and
Table-Two(2,3,2):
Compute Table-Sum = FUNCTION SUM (Table-Two(ALL, 3, ALL))
The following example computes various salary values for all the employees
whose salaries are encoded in Employee-Table:
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
Compute I
Compute Avg-Salary
Compute Salary-Range
Compute Total-Payroll
|
=
=
=
=
=
Function
Function
Function
Function
Function
Max(Emp-Salary(ALL))
Ord-Max(Emp-Salary(ALL))
Mean(Emp-Salary(ALL))
Range(Emp-Salary(ALL))
Sum(Emp-Salary(ALL))
Working with unbounded tables and groups
|
|
|
|
You can process an unbounded group as the input parameter to a called program.
The memory for the unbounded group is provided by the calling program.
Alternatively, you can define, initialize, and process unbounded groups in a single
program.
|
About this task
|
|
|
|
|
|
|
|
|
|
|
|
|
To work with unbounded tables and groups in a single program, do these steps:
1. In the LINKAGE SECTION, define an unbounded table (with the syntax of OCCURS
n TO UNBOUNDED), which will be part of an unbounded group.
2. In the WORKING-STORAGE SECTION or LOCAL-STORAGE SECTION, define the OCCURS
DEPENDING ON objects.
3. In the PROCEDURE DIVISION, do these steps to process unbounded groups:
a. Set the OCCURS DEPENDING ON objects.
b. Use the LENGTH special register or the LENGTH intrinsic function to compute
the total size of the group.
c. Use the CALL statement to call a storage allocation service, such as the
Language Environment service CEEGTST. Allocate enough memory for the
total length of the group. You will need a pointer to this memory (the
CEEGTST service returns a pointer).
92
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
|
|
|
d. Use the SET statement to establish addressability. For example, SET ADDRESS
OF group TO pointer.
4. Use the unbounded table and its containing unbounded group according to the
following rules:
v You can reference unbounded tables in COBOL syntax anywhere a table can
be referenced.
|
|
|
|
|
|
|
|
|
v You can reference unbounded groups in COBOL syntax anywhere an
alphanumeric or national group can be referenced, with the following
exceptions:
– You cannot specify unbounded groups as a BY CONTENT argument in a CALL
statement.
– You cannot specify unbounded groups as data-name-2 on the PROCEDURE
DIVISION RETURNING phrase.
– You cannot specify unbounded groups as arguments to intrinsic functions,
except as an argument to the LENGTH intrinsic function.
|
|
|
|
|
|
RELATED REFERENCES
“Example: Using unbounded tables for parsing XML documents”
Variable-length tables (Enterprise COBOL Language Reference)
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Example: Using unbounded tables for parsing XML
documents
|
|
Consider using unbounded tables when parsing an XML document with an
unknown number of repetitive elements.
|
|
|
|
|
|
|
You can use any of the following methods:
v Predetermine the number of elements to expect. One method to determine the
number of elements is to parse the XML document twice. During the first parse,
count the number of occurrences of each unbounded element in the
corresponding OCCURS UNBOUNDED DEPENDING ON object. Then, allocate storage for
the data items using these computed values, and parse the XML document a
second time to process its payload.
|
|
|
|
|
|
v Pick initial sizes and allow for expansion of the tables. It might be more efficient
to set arbitrary limits in the OCCURS UNBOUNDED DEPENDING ON objects based on
previous experience, and parse the document directly to process its content. For
each unbounded element, check if the current limit is about to be exceeded. If
so, allocate more storage for the corresponding array, copy the data from the old
array to the expanded array, then free the storage for the old array.
|
|
|
|
|
The following examples illustrate the first method. See the XML schema example,
and note that elements B and C have a maxOccurs value of unbounded, and thus can
occur an unlimited number of times in the sequence within element G. In the XML
document example, element B in fact occurs three times, and element C occurs five
times.
|
|
|
|
In the XML processing program example, the processing procedure for the first XML
PARSE statement simply computes the number of occurrences of elements B and C.
After allocating the required storage, the program executes a second XML PARSE
statement to process the XML payload.
Chapter 4. Handling tables
93
|
|
|
|
|
|
|
|
|
|
|
|
|
|
XML schema
|
|
|
|
|
|
|
|
|
|
|
|
|
XML document
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
XML processing program
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://example.org"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="G">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="A" type="xsd:string" maxOccurs="1" />
<xsd:element name="B" type="xsd:int" maxOccurs="unbounded" />
<xsd:element name="C" type="xsd:int" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
<?xml version="1.0" encoding="UTF-8"?>
<p:G xmlns:p="http://example.org" >
<A>Hello</A>
<B>1</B>
<B>2</B>
<B>3</B>
<C>1</C>
<C>2</C>
<C>3</C>
<C>4</C>
<C>5</C>
</p:G>
Identification division.
Program-id. XMLProc.
Data division.
Working-storage section.
01 NB pic S9(9) binary value zero.
01 NC pic S9(9) binary value zero.
01 Gptr pointer.
01 Gsize pic 9(9) binary.
01 Heap0 pic 9(9) binary value zero.
Linkage section.
01 XML-Doc pic X(500000).
01 G.
02 A pic x(5).
02 B pic s9(9) occurs 1 to unbounded depending on NB.
02 C pic s9(9) occurs 1 to unbounded depending on NC.
Procedure division using XML-Doc.
XML parse XML-Doc processing procedure CountElements
Move length of G to Gsize
Call "CEEGTST" using Heap0 Gsize Gptr omitted
Set address of G to Gptr
XML parse XML-doc processing procedure acquireContent
...
Goback.
CountElements.
If xml-event = ’START-OF-ELEMENT’
Evaluate xml-text
When ’B’
Add 1 to NB
When ’C’
Add 1 to NC
When other
Continue
End-evaluate
End-if.
End program XMLProc.
94
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
RELATED TASKS
“Working with unbounded tables and groups” on page 92
|
Chapter 4. Handling tables
95
96
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 5. Selecting and repeating program actions
About this task
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 the IF, EVALUATE, and PERFORM statements, and the use of
switches and flags.
RELATED TASKS
“Selecting program actions”
“Repeating program actions” on page 105
Selecting program actions
You can provide for different program actions depending on the tested value of
one or more data items.
About this task
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 102
RELATED REFERENCES
IF statement (Enterprise COBOL Language Reference)
EVALUATE statement (Enterprise COBOL Language Reference)
Coding a choice of actions
Use IF . . . ELSE to code a choice between two processing actions. (The word
THEN is optional.) Use the EVALUATE statement to code a choice among three or
more possible actions.
About this task
IF condition-p
statement-1
ELSE
statement-2
END-IF
When one of two processing choices is no action, code the IF statement with or
without ELSE. Because the ELSE clause is optional, you can code the IF statement as
follows:
IF condition-q
statement-1
END-IF
© Copyright IBM Corp. 1991, 2013
97
Such coding is suitable for simple cases. For complex logic, you probably need to
use the ELSE clause. For example, suppose you have nested IF statements in which
there is 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:
IF condition-q
statement-1
ELSE
CONTINUE
END-IF
The EVALUATE statement is an expanded form of the IF statement that allows you to
avoid nesting IF statements, a common source of logic errors and debugging
problems.
RELATED TASKS
“Using nested IF statements”
“Using the EVALUATE statement” on page 99
“Coding conditional expressions” on page 102
Using nested IF statements
If an IF statement contains an IF statement as one of its possible branches, the IF
statements are said to be nested. Theoretically, there is no limit to the depth of
nested IF statements.
About this task
However, use nested IF statements sparingly. The logic can be difficult to follow,
although explicit scope terminators and indentation can help. If a program has to
test a variable for more than two values, EVALUATE is probably a better choice.
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
In the pseudocode above, an IF statement and a sequential structure are nested in
one branch of the outer IF. In this structure, the END-IF that closes the nested IF is
very important. Use END-IF instead of a period, because a period would end the
outer IF structure also.
The following figure shows the logic structure of the pseudocode above.
98
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED TASKS
“Coding a choice of actions” on page 97
RELATED REFERENCES
Explicit scope terminators (Enterprise COBOL Language Reference)
Using the EVALUATE statement
You can use the EVALUATE statement instead of a series of nested IF statements to
test several conditions and specify a different action for each. Thus you can use the
EVALUATE statement to implement a case structure or decision table.
About this task
You can also use the EVALUATE statement to cause multiple conditions to lead to the
same processing, as shown in these examples:
“Example: EVALUATE using THRU phrase” on page 100
“Example: EVALUATE using multiple WHEN phrases” on page 101
In an EVALUATE statement, the operands before the WHEN phrase are referred to as
selection subjects, and the operands in the WHEN phrase are called the selection objects.
Selection subjects can be identifiers, literals, conditional expressions, or the word
TRUE or FALSE. Selection objects can be identifiers, literals, conditional or arithmetic
expressions, or the word TRUE, FALSE, or ANY.
You can separate multiple selection subjects with the ALSO phrase. You can separate
multiple selection objects with the ALSO phrase. The number of selection objects
within each set of selection objects must be equal to the number of selection
subjects, as shown in this example:
“Example: EVALUATE testing several conditions” on page 101
Identifiers, literals, or arithmetic expressions that appear within a selection object
must be valid operands for comparison to the corresponding operand in the set of
Chapter 5. Selecting and repeating program actions
99
selection subjects. Conditions or the word TRUE or FALSE that appear in a selection
object must correspond to a conditional expression or the word TRUE or FALSE in
the set of selection subjects. (You can use the word ANY as a selection object to
correspond to any type of selection subject.)
The execution of the EVALUATE statement ends when one of the following
conditions occurs:
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 that they appear in the source program.
Therefore, you should order these phrases for the best performance. First code the
WHEN phrase that contains selection objects that are 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 97
RELATED REFERENCES
EVALUATE statement (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
Example: EVALUATE using THRU phrase:
This example shows how you can code several conditions in a range of values to
lead to the same processing action by coding the THRU phrase. Operands in a THRU
phrase must be of the same class.
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
100
Enterprise COBOL for z/OS, V5.1 Programming Guide
Example: EVALUATE using multiple WHEN phrases:
The following example shows that you can code multiple WHEN phrases if several
conditions should lead to the same action. Doing so gives you more flexibility than
using only the THRU phrase, because the conditions do not have to evaluate to
values in a range nor have the same class.
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:
This example shows the use of the ALSO phrase to separate two selection subjects
(True ALSO True) and to separate the two corresponding selection objects within
each set of selection objects (for example, When A + B < 10 Also C = 10).
Both selection objects in a WHEN phrase must satisfy the TRUE, TRUE condition before
the associated action is performed. If both objects do not evaluate to TRUE, the next
WHEN phrase is processed.
Identification Division.
Program-ID. MiniEval.
Environment Division.
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"
Chapter 5. Selecting and repeating program actions
101
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.
About this task
You can specify the following conditions:
v Relation conditions, such as:
– Numeric comparisons
– Alphanumeric comparisons
– DBCS comparisons
– National comparisons
v Class
– IS
– IS
– IS
– IS
v
v
v
v
conditions; for example, to test whether a data item:
NUMERIC
ALPHABETIC
DBCS
KANJI
– IS NOT KANJI
Condition-name conditions, to test the value of a conditional variable that you
define
Sign conditions, to test whether a numeric operand IS POSITIVE, NEGATIVE, or
ZERO
Switch-status conditions, to test the status of UPSI switches that you name in the
SPECIAL-NAMES paragraph
Complex conditions, such as:
– Negated conditions; for example, NOT (A IS EQUAL TO B)
– Combined conditions (conditions combined with logical operators AND or OR)
RELATED CONCEPTS
“Switches and flags” on page 103
RELATED TASKS
“Defining switches and flags” on page 103
“Resetting switches and flags” on page 104
“Checking for incompatible data (numeric class test)” on page 56
“Comparing national (UTF-16) data” on page 152
“Testing for valid DBCS characters” on page 157
102
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
General relation conditions (Enterprise COBOL Language Reference)
Class condition (Enterprise COBOL Language Reference)
Rules for condition-name entries (Enterprise COBOL Language Reference)
Sign condition (Enterprise COBOL Language Reference)
Combined conditions (Enterprise 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 by using 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 104
Defining switches and flags
In the DATA DIVISION, define level-88 items that will act as switches or flags, and
give them meaningful names.
About this task
To test for more than two values with 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 to them have some association with logical values.
“Example: switches”
“Example: flags” on page 104
Example: switches
The following examples show how you can use level-88 items to test for various
binary-valued (on-off) conditions in your program.
For example, to test for the end-of-file condition for an input file named
Transaction-File, you can 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 that a condition named Transaction-EOF is turned on
when Transaction-EOF-Switch has value 'y'. Referencing Transaction-EOF in the
Chapter 5. Selecting and repeating program actions
103
PROCEDURE DIVISION expresses the same condition as testing Transaction-EOFSwitch = "y". For example, the following statement causes a report to be printed
only if Transaction-EOF-Switch has been set to 'y':
If Transaction-EOF Then
Perform Print-Report-Summary-Lines
Example: flags
The following examples show how you can use several level-88 items together
with an EVALUATE statement to determine which of several conditions in a program
is true.
Consider for example a program that updates a master file. The updates are read
from a transaction file. The records in the file contain a field that indicates which
of the three functions is 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 to determine
which function is to be performed might look like this:
Evaluate True
When Add-Transaction
Perform Add-Master-Record-Paragraph
When Change-Transaction
Perform Update-Existing-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 flags to the
original values they had in their data descriptions. To do so, either use a SET
statement or define a data item to move to the switch or flag.
About this task
When you use the SET condition-name TO TRUE statement, the switch or flag is set to
the original value that it was assigned in its data description. For a level-88 item
that has multiple values, SET condition-name TO TRUE assigns the first value (A in the
example below):
88 Record-is-Active Value "A" "O" "S"
Using the SET statement and meaningful condition-names makes it easier for
readers to follow your code.
“Example: set switch on”
“Example: set switch off” on page 105
Example: set switch on
The following examples show how you can set a switch on by coding a SET
statement that moves the value TRUE to a level-88 item.
For example, the SET statement in the following example has the same effect as
coding the statement Move "y" to Transaction-EOF-Switch:
104
Enterprise COBOL for z/OS, V5.1 Programming Guide
01
Switches
05 Transaction-EOF-Switch
Pic X Value space.
88 Transaction-EOF
Value "y".
. . .
Procedure Division.
000-Do-Main-Logic.
Perform 100-Initialize-Paragraph
Read Update-Transaction-File
At End Set Transaction-EOF to True
End-Read
The following example shows how to assign a value to a field in an output record
based on the transaction code of an input record:
01
Input-Record.
05 Transaction-Type
Pic X(9).
01 Data-Record-Out.
05 Data-Record-Type
Pic X.
88 Record-Is-Active
Value "A".
88 Record-Is-Suspended
Value "S".
88 Record-Is-Deleted
Value "D".
05 Key-Field
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
The following example shows how you can set a switch off by coding a MOVE
statement that moves a value to a level-88 item.
For example, you can use a data item called SWITCH-OFF to set an on-off switch to
off, as in the following code, which resets a switch to indicate that end-of-file has
not been reached:
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
Repeating program actions
Use a PERFORM statement to repeat the same code (that is, loop) either a specified
number of times or based on the outcome of a decision.
About this task
You can also use a PERFORM statement to execute a paragraph and then implicitly
return control to the next executable statement. In effect, this PERFORM statement is
a way of coding a closed subroutine that you can enter from many different parts
of the program.
PERFORM statements can be inline or out-of-line.
Chapter 5. Selecting and repeating program actions
105
RELATED TASKS
“Choosing inline or out-of-line PERFORM”
“Coding a loop” on page 107
“Looping through a table” on page 108
“Executing multiple paragraphs or sections” on page 108
RELATED REFERENCES
PERFORM statement (Enterprise COBOL Language Reference)
Choosing inline or out-of-line PERFORM
An inline PERFORM is an imperative statement that is executed in the normal flow of
a program; an out-of-line PERFORM entails a branch to a named paragraph and an
implicit return from that paragraph.
About this task
To determine whether to code an inline or out-of-line PERFORM statement, answer
the following questions:
v Is the PERFORM statement used in several places?
Use an out-of-line PERFORM when you want to use the same portion of code in
several places in your program.
v Which placement of the statement will be easier to read?
If the code to be performed is short, an inline PERFORM can be easier to read. But
if the code extends over several screens, the logical flow of the program might
be clearer if you use an out-of-line PERFORM. (Each paragraph in structured
programming should perform one logical function, however.)
v What are the efficiency tradeoffs?
An inline PERFORM avoids the overhead of branching that occurs with an
out-of-line PERFORM. But 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
a branch to a separate paragraph and an implicit return. If the performed
paragraph is in the subsequent sequential flow of your program, it is also executed
in that logic flow. To avoid this additional execution, 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.
“Example: inline PERFORM statement”
Example: inline PERFORM statement
This example shows the structure of an inline PERFORM statement that has the
required scope terminators and the required END-PERFORM phrase.
Perform 100-Initialize-Paragraph
* The following statement 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
106
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 specified number
of times.
About this task
PERFORM 010-PROCESS-ONE-MONTH 12 TIMES
INSPECT . . .
In the example above, 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 statement if you want to
execute the paragraph at least once, and test before any subsequent execution. This
statement is equivalent to a 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 GREATER THAN 12
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.)
Chapter 5. Selecting and repeating program actions
107
Looping through a table
You can use the PERFORM . . . VARYING statement to initialize a table. In this form
of the PERFORM statement, a variable is increased or decreased and tested until a
condition is satisfied.
About this task
Thus you use the PERFORM statement to control looping through a table. You can
use either of these forms:
PERFORM . . . WITH TEST AFTER . . . . VARYING . . . UNTIL . . .
PERFORM . . . [WITH TEST BEFORE] . . . VARYING . . . UNTIL . . .
The following section of code shows an example of looping through a table to
check for invalid data:
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 . . .
When control reaches the PERFORM statement above, 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
the condition 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.
The loop above controls input-checking for the 12 fields of item WS-DATA. Empty
fields are not allowed in the application, so the section of code loops and issues
error messages as appropriate.
Executing multiple paragraphs or sections
In structured programming, you usually execute a single paragraph. However, you
can execute a group of paragraphs, or a single section or group of sections, by
coding the PERFORM . . . THRU statement.
About this task
When you use the PERFORM . . . THRU statement, code a paragraph-EXIT statement
to clearly indicate the end point of a series of paragraphs.
RELATED TASKS
“Processing table items using intrinsic functions” on page 91
108
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 6. Handling strings
About this task
COBOL provides language constructs for performing many different operations on
string data items.
For example, you can:
v Join or split data items.
v Manipulate null-terminated strings, such as count or move characters.
v Refer to substrings by their ordinal position and, if needed, length.
v Tally and replace data items, such as count the number of times a specific
character occurs in a data item.
v Convert data items, such as change to uppercase or lowercase.
v Evaluate data items, such as determine the length of a data item.
RELATED TASKS
“Joining data items (STRING)”
“Splitting data items (UNSTRING)” on page 111
“Manipulating null-terminated strings” on page 114
“Referring to substrings of data items” on page 115
“Tallying and replacing data items (INSPECT)” on page 119
“Converting data items (intrinsic functions)” on page 120
“Evaluating data items (intrinsic functions)” on page 123
Chapter 7, “Processing data in an international environment,” on page 129
Joining data items (STRING)
Use the STRING statement to join all or parts of several data items or literals into
one data item. One STRING statement can take the place of several MOVE statements.
About this task
The STRING statement transfers data into a receiving data item in the order that you
indicate. In the STRING statement you also specify:
v A delimiter for each set of sending fields that, if encountered, causes those
sending fields to stop being transferred (DELIMITED BY phrase)
v (Optional) Action to be taken if the receiving field is filled before all of the
sending data has been processed (ON OVERFLOW phrase)
v (Optional) An integer data item that indicates the leftmost character position
within the receiving field into which data should be transferred (WITH POINTER
phrase)
The receiving data item must not be an edited item, or a display or national
floating-point item. If the receiving data item has:
v USAGE DISPLAY, each identifier in the statement except the POINTER identifier
must have USAGE DISPLAY, and each literal in the statement must be
alphanumeric
v USAGE NATIONAL, each identifier in the statement except the POINTER identifier
must have USAGE NATIONAL, and each literal in the statement must be national
© Copyright IBM Corp. 1991, 2013
109
v USAGE DISPLAY-1, each identifier in the statement except the POINTER identifier
must have USAGE DISPLAY-1, and each literal in the statement must be DBCS
Only that portion of the receiving field into which data is written by the STRING
statement is changed.
“Example: STRING statement”
RELATED TASKS
“Handling errors in joining and splitting strings” on page 246
RELATED REFERENCES
STRING statement (Enterprise COBOL Language Reference)
Example: STRING statement
The following example shows the STRING statement selecting and formatting
information from a record into an output line.
The FILE SECTION defines the following record:
01
RCD-01.
05 CUST-INFO.
10 CUST-NAME
10 CUST-ADDR
05 BILL-INFO.
10 INV-NO
10 INV-AMT
10 AMT-PAID
10 DATE-PAID
10 BAL-DUE
10 DATE-DUE
PIC X(15).
PIC X(35).
PIC
PIC
PIC
PIC
PIC
PIC
X(6).
$$,$$$.99.
$$,$$$.99.
X(8).
$$,$$$.99.
X(8).
The WORKING-STORAGE SECTION defines the following fields:
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 b indicates a
blank space):
J.B.bSMITHbbbbb
444bSPRINGbST.,bCHICAGO,bILL.bbbbbb
A14275
$4,736.85
$2,400.00
09/22/76
$2,336.85
10/22/76
In the PROCEDURE DIVISION, these settings occur before the STRING statement:
v RPT-LINE is set to SPACES.
v LINE-POS, the data item to be used as the POINTER field, is set to 4.
Here is the STRING statement:
STRING
LINE-NO SPACE CUST-INFO INV-NO SPACE DATE-DUE SPACE
DELIMITED BY SIZE
110
Enterprise COBOL for z/OS, V5.1 Programming Guide
BAL-DUE
DELIMITED BY DEC-POINT
INTO RPT-LINE
WITH POINTER LINE-POS.
Because the POINTER field LINE-POS has value 4 before the STRING statement is
performed, data is moved into the receiving field RPT-LINE beginning at character
position 4. Characters in positions 1 through 3 are unchanged.
The sending items that specify DELIMITED BY SIZE are moved in their entirety to
the receiving field. Because BAL-DUE is delimited by DEC-POINT, the moving of
BAL-DUE to the receiving field stops when a decimal point (the value of DEC-POINT)
is encountered.
STRING 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
has the values shown below.
Splitting data items (UNSTRING)
Use the UNSTRING statement to split a sending field into several receiving fields.
One UNSTRING statement can take the place of several MOVE statements.
About this task
In the UNSTRING statement you can specify:
v Delimiters that, when one of them is encountered in the sending field, cause the
current receiving field to stop receiving and the next, if any, to begin receiving
(DELIMITED BY phrase)
v A field for the delimiter that, when encountered in the sending field, causes the
current receiving field to stop receiving (DELIMITER IN phrase)
v An integer data item that stores the number of characters placed in the current
receiving field (COUNT IN phrase)
Chapter 6. Handling strings
111
v An integer data item that indicates the leftmost character position within the
sending field at which UNSTRING processing should begin (WITH POINTER phrase)
v An integer data item that stores a tally of the number of receiving fields that are
acted on (TALLYING IN phrase)
v Action to be taken if all of the receiving fields are filled before the end of the
sending data item is reached (ON OVERFLOW phrase)
The sending data item and the delimiters in the DELIMITED BY phrase must be of
category alphabetic, alphanumeric, alphanumeric-edited, DBCS, national, or
national-edited.
Receiving data items can be of category alphabetic, alphanumeric, numeric, DBCS,
or national. If numeric, a receiving data item must be zoned decimal or national
decimal. If a receiving data item has:
v USAGE DISPLAY, the sending item and each delimiter item in the statement must
have USAGE DISPLAY, and each literal in the statement must be alphanumeric
v USAGE NATIONAL, the sending item and each delimiter item in the statement must
have USAGE NATIONAL, and each literal in the statement must be national
v USAGE DISPLAY-1, the sending item and each delimiter item in the statement
must have USAGE DISPLAY-1, and each literal in the statement must be DBCS
“Example: UNSTRING statement”
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Handling errors in joining and splitting strings” on page 246
RELATED REFERENCES
UNSTRING statement (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Example: UNSTRING statement
The following example shows the UNSTRING statement transferring selected
information from an input record. Some information is organized for printing and
some for further processing.
The FILE SECTION defines the following records:
*
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).
112
Enterprise COBOL for z/OS, V5.1 Programming Guide
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
PIC X.
77 CTR-1
PIC S9(3).
77 CTR-2
PIC S9(3).
77 CTR-3
PIC S9(3).
77 CTR-4
PIC S9(3).
77 DLTR-1
PIC X.
77 DLTR-2
PIC X.
77 CHAR-CT
PIC S9(3).
77 FLDS-FILLED
PIC S9(3).
In the PROCEDURE DIVISION, these settings occur before the UNSTRING statement:
v A period (.) is placed in DBY-1 for use as a delimiter.
v CHAR-CT (the POINTER field) is set to 3.
v The value zero (0) is placed in FLDS-FILLED (the TALLYING field).
v Data is read into record INV-RCD, whose format is as shown below.
Here is the 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.
Because the POINTER field CHAR-CT has value 3 before the UNSTRING statement is
performed, the two character positions of the CONTROL-CHARS field in INV-RCD are
ignored.
UNSTRING 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.
Chapter 6. Handling strings
113
3. Positions 24 through 29 (707890) are placed in INV-NO. The delimiter character
slash (/) is placed in DLTR-1, and the value 6 is placed in CTR-2.
4. Positions 31 through 33 (BBA) are placed in INV-CLASS. The delimiter is 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 placed in M-UNITS. The value 6 is placed in
CTR-3. The delimiter is 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 zero (0). The delimiter is
SPACE, but because no field was 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 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 in INV-RCD
have not been examined, the ON OVERFLOW statement is executed. 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 (for example, strings that
are passed to or from a C program) by various mechanisms.
About this task
For example, you can:
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
114
Enterprise COBOL for z/OS, V5.1 Programming Guide
COUNT IN char-count
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 a field by using a reference modifier such as source-field (I:1).
“Example: null-terminated strings”
RELATED TASKS
“Handling null-terminated strings” on page 486
RELATED REFERENCES
Alphanumeric literals (Enterprise COBOL Language Reference)
Example: null-terminated strings
The following example shows several ways in which you can process
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 data item that has USAGE DISPLAY, DISPLAY-1, or NATIONAL
by using a reference modifier. You can also refer to a substring of an alphanumeric
or national character string that is returned by an intrinsic function by using a
reference modifier.
About this task
|
|
|
Note: To get a substring of a character string argument that is encoded in UTF-8,
use the USUBSTR function as described in “Using intrinsic functions to process
UTF-8 encoded data” on page 146.
Chapter 6. Handling strings
115
The following example shows how to use a reference modifier to refer to a
twenty-character substring of a data item called Customer-Record:
Move Customer-Record(1:20) to Orig-Customer-Name
You code a reference modifier in parentheses immediately after the data item. As
the example shows, a reference modifier can contain two values that are separated
by a colon, in this order:
1. Ordinal position (from the left) of the character that you want the substring to
start with
2. (Optional) Length of the required substring in character positions
The reference-modifier position and length for an item that has USAGE DISPLAY are
expressed in terms of single-byte characters. The reference-modifier position and
length for items that have USAGE DISPLAY-1 or NATIONAL are expressed in terms of
DBCS character positions and national character positions, respectively.
If you omit the length in a reference modifier (coding only the ordinal position of
the first character, followed by a colon), the substring extends to the end of the
item. Omit the length where possible as a simpler and less error-prone coding
technique.
You can refer to substrings of USAGE DISPLAY data items, including alphanumeric
groups, alphanumeric-edited data items, numeric-edited data items, display
floating-point data items, and zoned decimal data items, by using reference
modifiers. When you reference-modify any of these data items, the result is of
category alphanumeric. When you reference-modify an alphabetic data item, the
result is of category alphabetic.
You can refer to substrings of USAGE NATIONAL data items, including national
groups, national-edited data items, numeric-edited data items, national
floating-point data items, and national decimal data items, by using reference
modifiers. When you reference-modify any of these data items, the result is of
category national. For example, suppose that you define a national decimal data
item as follows:
01
NATL-DEC-ITEM
Usage National
Pic 999
Value 123.
You can use NATL-DEC-ITEM in an arithmetic expression because NATL-DEC-ITEM is of
category numeric. But you cannot use NATL-DEC-ITEM(2:1) (the national character
2, which in hexadecimal notation is NX"0032") in an arithmetic expression, because
it is of category national.
You can refer to substrings of table entries, including variable-length entries, by
using reference modifiers. To refer to a substring of a table entry, code the
subscript expression before the reference modifier. For example, assume that
PRODUCT-TABLE is a properly coded table of character strings. To move D to the
fourth character in the second string in the table, you can code this statement:
MOVE ’D’ to PRODUCT-TABLE (2), (4:1)
You can code either or both of the two values in a reference modifier as a variable
or as an arithmetic expression.
“Example: arithmetic expressions as reference modifiers” on page 118
116
Enterprise COBOL for z/OS, V5.1 Programming Guide
Because numeric function identifiers can be used anywhere that arithmetic
expressions can be used, you can code a numeric function identifier in a reference
modifier as the leftmost character position or as the length, or both.
“Example: intrinsic functions as reference modifiers” on page 118
Each number in the reference modifier must have a value of at least 1. The sum of
the two numbers must not exceed the total length of the data item by more than 1
character position so that you do not reference beyond the end of the 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 SSRANGE compiler option detects out-of-range reference modifiers, and flags
violations with a runtime message.
RELATED CONCEPTS
“Reference modifiers”
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Referring to an item in a table” on page 73
RELATED REFERENCES
“SSRANGE” on page 362
Reference modification (Enterprise COBOL Language Reference)
Function definitions (Enterprise COBOL Language Reference)
Reference modifiers
Reference modifiers let you easily refer to a substring of a data item.
For example, 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:
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)
":"
Chapter 6. Handling strings
117
* 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
“Assigning input from a screen or file (ACCEPT)” on page 35
“Referring to substrings of data items” on page 115
“Using national data (Unicode) in COBOL” on page 134
RELATED REFERENCES
Reference modification (Enterprise COBOL Language Reference)
Example: arithmetic expressions as reference modifiers
Suppose that a field contains some right-justified characters, and you want to
move those characters to another field where they will be left justified. You can do
so by using reference modifiers and an INSPECT statement.
Suppose a 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
You can use intrinsic functions in reference modifiers if you do not know the
leftmost position or length of a substring at compile time.
For example, the following code fragment causes a substring of Customer-Record to
be moved into the data item 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
118
Enterprise COBOL for z/OS, V5.1 Programming Guide
If you want to use a noninteger function in a position that requires 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
RELATED REFERENCES
INTEGER (Enterprise COBOL Language Reference)
INTEGER-PART (Enterprise COBOL Language Reference)
Tallying and replacing data items (INSPECT)
Use the INSPECT statement to inspect characters or groups of characters in a data
item and to optionally replace them.
About this task
Use the INSPECT statement to do the following tasks:
v Count the number of times a specific character occurs in a data item (TALLYING
phrase).
v Fill a data item or selected portions of a data item with specified characters such
as spaces, asterisks, or zeros (REPLACING phrase).
v Convert all occurrences of a specific character or string of characters in a data
item to replacement characters that you specify (CONVERTING phrase).
You can specify one of the following data items as the item to be inspected:
v An elementary item described explicitly or implicitly as USAGE DISPLAY, USAGE
DISPLAY-1, or USAGE NATIONAL
v An alphanumeric group item or national group item
If the inspected item has:
v USAGE DISPLAY, each identifier in the statement (except the TALLYING count field)
must have USAGE DISPLAY, and each literal in the statement must be
alphanumeric
v USAGE NATIONAL, each identifier in the statement (except the TALLYING count field)
must have USAGE NATIONAL, and each literal in the statement must be national
v USAGE DISPLAY-1, each identifier in the statement (except the TALLYING count
field) must have USAGE DISPLAY-1, and each literal in the statement must be a
DBCS literal
“Examples: INSPECT statement”
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED REFERENCES
INSPECT statement (Enterprise COBOL Language Reference)
Examples: INSPECT statement
The following examples show some uses of the INSPECT statement to examine and
replace characters.
In the following example, the INSPECT statement examines and replaces characters
in data item DATA-2. The number of times a leading zero (0) occurs in the data item
Chapter 6. Handling strings
119
is accumulated in COUNTR. The first instance of the character A that follows the first
instance of the character C is replaced by the character 2.
77 COUNTR
01 DATA-2
. . .
INSPECT DATA-2
TALLYING COUNTR
REPLACING FIRST
PIC 9
VALUE ZERO.
PIC X(11).
FOR LEADING "0"
"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 examines and replaces characters
in data item DATA-3. Each character that precedes the first instance of a quotation
mark (") 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
characters that follow the first instance of the character / but that precede 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 data items (intrinsic functions)
You can use intrinsic functions to convert character-string data items to several
other formats, for example, to uppercase or lowercase, to reverse order, to
numbers, or to one code page from another.
120
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
You can use the NATIONAL-OF and DISPLAY-OF intrinsic functions to convert to and
from national (Unicode) strings.
You can also use the INSPECT statement to convert characters.
“Examples: INSPECT statement” on page 119
RELATED TASKS
“Changing case (UPPER-CASE, LOWER-CASE)”
“Transforming to reverse order (REVERSE)”
“Converting to numbers (NUMVAL, NUMVAL-C)” on page 122
“Converting from one code page to another” on page 123
Changing case (UPPER-CASE, LOWER-CASE)
You can use the UPPER-CASE and LOWER-CASE intrinsic functions to easily change the
case of alphanumeric, alphabetic, or national strings.
About this task
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
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 replace the contents of Item-2.
|
|
Note: The UPPER-CASE and LOWER-CASE intrinsic functions do not support
alphanumeric arguments that contain UTF-8 encoded data.
RELATED TASKS
“Assigning input from a screen or file (ACCEPT)” on page 35
“Displaying values on a screen or in a file (DISPLAY)” on page 36
Transforming to reverse order (REVERSE)
You can reverse the order of the characters in a string by using the REVERSE
intrinsic function.
About this task
Move Function Reverse(Orig-cust-name) To Orig-cust-name
Chapter 6. Handling strings
121
For example, the statement above reverses the order of the characters in
Orig-cust-name. If the starting value is JOHNSONbbb, the value after the statement is
performed is bbbNOSNHOJ, where b represents a blank space.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
Converting to numbers (NUMVAL, NUMVAL-C)
The NUMVAL and NUMVAL-C functions convert character strings (alphanumeric or
national literals, or class alphanumeric or class national data items) to numbers.
Use these functions to convert free-format character-representation numbers to
numeric form so that you can process them numerically.
About this task
01
01
01
. .
R
S
Total
.
Compute
Pic x(20) Value "- 1234.5678".
Pic x(20) Value " $12,345.67CR".
Usage is Comp-1.
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 above. 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 represents a reference to a numeric
data item.
At most 15 decimal digits can be converted accurately to long-precision floating
point (as described in the related reference below about conversions and precision).
If the argument to NUMVAL or NUMVAL-C has more than 15 digits, it is recommended
that you specify the ARITH(EXTEND) compiler option so that an extended-precision
function result that can accurately represent the value of the argument is returned.
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 leading sign is separate.
. . .
Accept X from Console
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:
01 A
Pic x(10).
01 B
Pic S999V99.
. . .
Accept A from Console
Compute B = Function Numval(A)
122
Enterprise COBOL for z/OS, V5.1 Programming Guide
The input could then be:
1.23
-300
RELATED CONCEPTS
“Formats for numeric data” on page 49
“Data format conversions” on page 54
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Converting to or from national (Unicode) representation” on page 142
RELATED REFERENCES
“Conversions and precision” on page 54
“ARITH” on page 318
Converting from one code page to another
You can nest the DISPLAY-OF and NATIONAL-OF intrinsic functions to easily convert
from any code page to any other code page.
About this task
For example, the following code converts an EBCDIC string to an ASCII string:
77 EBCDIC-CCSID PIC 9(4) BINARY VALUE 1140.
77 ASCII-CCSID PIC 9(4) BINARY VALUE 819.
77 Input-EBCDIC PIC X(80).
77 ASCII-Output PIC X(80).
. . .
* Convert EBCDIC to ASCII
Move Function Display-of
(Function National-of (Input-EBCDIC EBCDIC-CCSID),
ASCII-CCSID)
to ASCII-output
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Converting to or from national (Unicode) representation” on page 142
Evaluating data items (intrinsic functions)
You can use intrinsic functions to determine the ordinal position of a character in
the collating sequence, to find the largest or smallest item in a series, to find the
length of data item, or to determine when a program was compiled.
About this task
Use these intrinsic functions:
v CHAR and ORD to evaluate integers and single alphabetic or alphanumeric
characters with respect to the collating sequence used in a program
v MAX, MIN, ORD-MAX, and ORD-MIN to find the largest and smallest items in a series
of data items, including USAGE NATIONAL data items
v LENGTH to find the length of data items, including USAGE NATIONAL data items
v WHEN-COMPILED to find the date and time when a program was compiled
Chapter 6. Handling strings
123
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
RELATED TASKS
“Evaluating single characters for collating sequence”
“Finding the largest or smallest data item”
“Finding the length of data items” on page 126
“Finding the date of compilation” on page 127
Evaluating single characters for collating sequence
To find out the ordinal position of a given alphabetic or alphanumeric character in
the collating sequence, use the ORD function with the character as the argument. ORD
returns an integer that represents that ordinal position.
About this task
You can 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 find the character that it corresponds to, use the CHAR function with the integer
ordinal position as the argument. CHAR returns the required character. For example:
INITIALIZE Customer-Name REPLACING ALPHABETIC BY Function Char(65)
RELATED REFERENCES
CHAR (Enterprise COBOL Language Reference)
ORD (Enterprise COBOL Language Reference)
Finding the largest or smallest data item
To determine which of two or more alphanumeric, alphabetic, or national data
items has the largest value, use the MAX or ORD-MAX intrinsic function. To determine
which item has the smallest value, use MIN or ORD-MIN. These functions evaluate
according to the collating sequence.
About this task
To compare numeric items, including those that have USAGE NATIONAL, you can use
MAX, ORD-MAX, MIN, or ORD-MIN. With these intrinsic functions, the algebraic values of
the arguments are compared.
The MAX and MIN functions return the content of one of the arguments that you
supply. For example, suppose that your program has the following 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 VALLEJObbb to the first 10 character positions of
Customer-record, where b represents a blank space:
Move Function Max(Arg1 Arg2 Arg3) To Customer-record(1:10)
If you used MIN instead, then THOMASbbbb would be assigned.
The functions ORD-MAX and ORD-MIN return an integer that represents the ordinal
position (counting from the left) of the argument that has the largest or smallest
124
Enterprise COBOL for z/OS, V5.1 Programming Guide
value in the list of arguments that you supply. If you used the ORD-MAX function in
the example above, the compiler would issue an error message because the
reference to a numeric function is not in a valid place. The following statement is a
valid use of ORD-MAX:
Compute x = Function Ord-max(Arg1 Arg2 Arg3)
The statement above assigns the integer 3 to x if the same arguments are used as
in the previous example. If you used ORD-MIN instead, the integer 2 would be
returned. The examples above might be more realistic if Arg1, Arg2, and Arg3 were
successive elements of an array (table).
If you specify a national item for any argument, you must specify all arguments as
class national.
RELATED TASKS
“Performing arithmetic” on page 57
“Processing table items using intrinsic functions” on page 91
“Returning variable results with alphanumeric or national functions”
RELATED REFERENCES
MAX (Enterprise COBOL Language Reference)
MIN (Enterprise COBOL Language Reference)
ORD-MAX (Enterprise COBOL Language Reference)
ORD-MIN (Enterprise COBOL Language Reference)
Returning variable results with alphanumeric or national
functions
The results of alphanumeric or national functions could be of varying lengths and
values depending on the function arguments.
About this task
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))
This code has the following results:
v R2 is evaluated to be larger than R1.
v The string 'fbbbb' is moved to R3, where b represents a blank space. (The unfilled
character positions in R3 are padded with spaces.)
v L evaluates to the value 5.
If R1 contained 'g' instead of 'e', the code would have the following results:
v R1 would evaluate as larger than R2.
v The string 'gbbbbbbbbb' 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.
Chapter 6. Handling strings
125
If a program uses national data for function arguments, the lengths and values of
the function results could likewise vary. For example, the following code is
identical to the fragment above, but uses national data instead of alphanumeric
data.
01
01
01
01
. .
R1
Pic n(10) national value "e".
R2
Pic n(05) national value "f".
R3
Pic n(20) national value spaces.
L
Pic 99
national.
.
Move Function Max(R1 R2) to R3
Compute L = Function Length(Function Max(R1 R2))
This code has the following results, which are similar to the first set of results
except that these are for national characters:
v R2 is evaluated to be larger than R1.
v The string NX"0066 0020 0020 0020 0020" (the equivalent in national characters
of 'fbbbb', where b represents a blank space), shown here in hexadecimal notation
with added spaces for readability, is moved to R3. The unfilled character
positions in R3 are padded with national spaces.
v L evaluates to the value 5, the length in national character positions of R2.
You might be dealing with variable-length output from alphanumeric or national
functions. Plan your program accordingly. For example, you might need to think
about using variable-length files when the records that 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
“Finding the largest or smallest data item” on page 124
“Performing arithmetic” on page 57
RELATED REFERENCES
MAX (Enterprise COBOL Language Reference)
Finding the length of data items
You can use the LENGTH function in many contexts (including tables and numeric
data) to determine the length of an item. For example, you can use the LENGTH
function to determine the length of an alphanumeric or national literal, or a data
item of any type except DBCS.
About this task
The LENGTH function returns the length of a national item (a literal, or any item that
has USAGE NATIONAL, including national group items) as an integer equal to the
126
Enterprise COBOL for z/OS, V5.1 Programming Guide
length of the argument in national character positions. It returns the length of any
other data item as an integer equal to the length of the argument in alphanumeric
character positions.
The following COBOL statement demonstrates moving a data item into the field in
a record that holds customer names:
Move Customer-name To Customer-record(1:Function Length(Customer-name))
You can also use the LENGTH OF special register, which returns the length in bytes
even for national data. Coding either Function Length(Customer-name) or LENGTH
OF Customer-name returns the same result for alphanumeric items: 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 accepts 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 57
“Creating variable-length tables (DEPENDING ON)” on page 81
“Processing table items using intrinsic functions” on page 91
RELATED REFERENCES
LENGTH (Enterprise COBOL Language Reference)
LENGTH OF (Enterprise COBOL Language Reference)
Finding the date of compilation
You can use the WHEN-COMPILED intrinsic function to determine when a program
was compiled. The 21-character result indicates the four-digit year, month, day, and
time (in hours, minutes, seconds, and hundredths of seconds) of compilation, and
the difference in hours and minutes from Greenwich mean time.
About this task
The first 16 positions are in the following format:
YYYYMMDDhhmmsshh
You can instead use the WHEN-COMPILED special register to determine the date and
time of compilation in the following format:
MM/DD/YYhh.mm.ss
The WHEN-COMPILED special register supports only a two-digit year, and does not
carry fractions of a second. You can use this special register only as the sending
field in a MOVE statement.
RELATED REFERENCES
WHEN-COMPILED (Enterprise COBOL Language Reference)
Chapter 6. Handling strings
127
128
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 7. Processing data in an international environment
Enterprise COBOL supports Unicode UTF-16 as national character data at run
time. UTF-16 provides a consistent and efficient way to encode plain text. Using
UTF-16, you can develop software that will work with various national languages.
About this task
Use these COBOL facilities to code and compile programs that process national
data:
v Data types and literals:
– Character data types, defined with the USAGE NATIONAL clause and a PICTURE
clause that defines data of category national, national-edited, or
numeric-edited
– Numeric data types, defined with the USAGE NATIONAL clause and a PICTURE
clause that defines a numeric data item (a national decimal item) or an external
floating-point data item (a national floating-point item)
– National literals, specified with literal prefix N or NX
– Figurative constant ALL national-literal
– Figurative constants QUOTE, SPACE, HIGH-VALUE, LOW-VALUE, or ZERO, which have
national character (UTF-16) values when used in national-character contexts
v The COBOL statements shown in the related reference below about COBOL
statements and national data
v Intrinsic functions:
– NATIONAL-OF to convert an alphanumeric or double-byte character set (DBCS)
character string to USAGE NATIONAL (UTF-16)
– DISPLAY-OF to convert a national character string to USAGE DISPLAY in a
selected code page (EBCDIC, ASCII, EUC, or UTF-8)
– The other intrinsic functions shown in the related reference below about
intrinsic functions and national data
v The GROUP-USAGE NATIONAL clause to define groups that contain only USAGE
NATIONAL data items and that behave like elementary category national items in
most operations
v Compiler options:
– CODEPAGE to specify the code page to use for alphanumeric and DBCS data in
your program
– NSYMBOL to control whether national or DBCS processing is used for the N
symbol in literals and PICTURE clauses
You can also take advantage of implicit conversions of alphanumeric or DBCS data
items to national representation. The compiler performs such conversions (in most
cases) when you move these items to national data items, or compare these items
with national data items.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
“National groups” on page 137
© Copyright IBM Corp. 1991, 2013
129
RELATED TASKS
“Using national data (Unicode) in COBOL” on page 134
“Converting to or from national (Unicode) representation” on page 142
“Processing UTF-8 data” on page 145
“Processing Chinese GB 18030 data” on page 151
“Comparing national (UTF-16) data” on page 152
“Coding for use of DBCS support” on page 155
Appendix B, “Converting double-byte character set (DBCS) data,” on page 687
RELATED REFERENCES
“COBOL statements and national data”
“Intrinsic functions and national data” on page 132
“CODEPAGE” on page 322
“NSYMBOL” on page 346
Classes and categories of data (Enterprise COBOL Language Reference)
Data categories and PICTURE rules (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
COBOL statements and national data
You can use national data with the PROCEDURE DIVISION and compiler-directing
statements shown in the table below.
Table 15. COBOL statements and national data
COBOL
statement
Can be national
Comment
For more information
ACCEPT
identifier-1, identifier-2
identifier-1 is converted
from the native code page
specified in the CODEPAGE
compiler option only if
input is from CONSOLE.
“Assigning input from a screen or file
(ACCEPT)” on page 35
ADD
All identifiers can be
numeric items that have
USAGE NATIONAL. identifier-3
(GIVING) can be
numeric-edited with USAGE
NATIONAL.
“Using COMPUTE and other
arithmetic statements” on page 58
CALL
identifier-2, identifier-3,
identifier-4, identifier-5;
literal-2, literal-3
“Passing data” on page 481
COMPUTE
identifier-1 can be numeric
or numeric-edited with
USAGE NATIONAL.
arithmetic-expression can
contain numeric items that
have USAGE NATIONAL.
“Using COMPUTE and other
arithmetic statements” on page 58
COPY . . .
REPLACING
operand-1, operand-2 of the
REPLACING phrase
Chapter 18, “Compiler-directing
statements,” on page 375
DISPLAY
identifier-1
130
“Displaying values on a screen or in a
identifier-1 is converted to
EBCDIC only if the CONSOLE file (DISPLAY)” on page 36
mnemonic-name is
specified directly or
indirectly.
Enterprise COBOL for z/OS, V5.1 Programming Guide
Table 15. COBOL statements and national data (continued)
COBOL
statement
Can be national
Comment
For more information
DIVIDE
All identifiers can be
numeric items that have
USAGE NATIONAL. identifier-3
(GIVING) and identifier-4
(REMAINDER) can be
numeric-edited with USAGE
NATIONAL.
“Using COMPUTE and other
arithmetic statements” on page 58
INITIALIZE
identifier-1; identifier-2 or
literal-1 of the REPLACING
phrase
“Examples: initializing data items” on
If you specify REPLACING
NATIONAL or REPLACING
page 28
NATIONAL-EDITED, identifier-2
or literal-1 must be valid as
a sending operand in a
move to identifier-1.
INSPECT
All identifiers and literals.
(identifier-2, the TALLYING
integer data item, can have
USAGE NATIONAL.)
If any of these (other than
identifier-2, the TALLYING
identifier) have USAGE
NATIONAL, all must be
national.
INVOKE
Method-name as identifier-2
or literal-1; identifier-3 or
literal-2 in the BY VALUE
phrase
MERGE
Merge keys
The COLLATING SEQUENCE
phrase does not apply.
“Setting sort or merge criteria” on
page 234
MOVE
Both the sender and
receiver, or only the
receiver
Implicit conversions are
performed for valid MOVE
operands.
“Assigning values to elementary data
items (MOVE)” on page 32
“Tallying and replacing data items
(INSPECT)” on page 119
“Invoking methods (INVOKE)” on
page 596
“Assigning values to group data items
(MOVE)” on page 33
“Using COMPUTE and other
arithmetic statements” on page 58
MULTIPLY
All identifiers can be
numeric items that have
USAGE NATIONAL. identifier-3
(GIVING) can be
numeric-edited with USAGE
NATIONAL.
SEARCH ALL
(binary search)
Both the key data item and
its object of comparison
The key data item and its
object of comparison must
be compatible according to
the rules of comparison. If
the object of comparison is
of class national, the key
must be also.
“Doing a binary search (SEARCH
ALL)” on page 90
SORT
Sort keys
The COLLATING SEQUENCE
phrase does not apply.
“Setting sort or merge criteria” on
page 234
STRING
All identifiers and literals.
(identifier-4, the POINTER
integer data item, can have
USAGE NATIONAL.)
If identifier-3, the receiving
data item, is national, all
identifiers and literals
(other than identifier-4, the
POINTER identifier) must be
national.
“Joining data items (STRING)” on
page 109
Chapter 7. Processing data in an international environment
131
Table 15. COBOL statements and national data (continued)
COBOL
statement
Can be national
SUBTRACT
All identifiers can be
numeric items that have
USAGE NATIONAL. identifier-3
(GIVING) can be
numeric-edited with USAGE
NATIONAL.
UNSTRING
All identifiers and literals.
(identifier-6 and identifier-7,
the COUNT and TALLYING
integer data items,
respectively, can have USAGE
NATIONAL.)
XML GENERATE
identifier-1 (the generated
XML document); identifier-2
(the source field or fields);
identifier-4 or literal-4 (the
namespace identifier);
identifier-5 or literal-5 (the
namespace prefix)
XML PARSE
identifier-1 (the XML
document)
Comment
For more information
“Using COMPUTE and other
arithmetic statements” on page 58
If identifier-4, a receiving
data item, has USAGE
NATIONAL, the sending data
item and each delimiter
must have USAGE NATIONAL,
and each literal must be
national.
“Splitting data items (UNSTRING)” on
page 111
Chapter 29, “Producing XML output,”
on page 557
Chapter 28, “Processing XML input,”
The XML-NTEXT special
on page 519
register contains national
character document
fragments during parsing.
XML-NNAMESPACE and
XML-NNAMESPACE-PREFIX
special registers contain the
associated namespace
identifier and namespace
prefix, if any, in national
characters.
RELATED TASKS
“Defining numeric data” on page 45
“Displaying numeric data” on page 47
“Using national data (Unicode) in COBOL” on page 134
“Comparing national (UTF-16) data” on page 152
RELATED REFERENCES
“CODEPAGE” on page 322
Classes and categories of data (Enterprise COBOL Language Reference)
Intrinsic functions and national data
You can use arguments of class national with the intrinsic functions shown in the
table below.
Table 16. Intrinsic functions and national character data
Intrinsic function
Function type
For more information
DISPLAY-OF
Alphanumeric
“Converting national to alphanumeric (DISPLAY-OF)” on
page 144
LENGTH
Integer
“Finding the length of data items” on page 126
132
Enterprise COBOL for z/OS, V5.1 Programming Guide
Table 16. Intrinsic functions and national character data (continued)
Intrinsic function
Function type
For more information
LOWER-CASE, UPPER-CASE
National
“Changing case (UPPER-CASE, LOWER-CASE)” on page 121
NUMVAL, NUMVAL-C
Numeric
“Converting to numbers (NUMVAL, NUMVAL-C)” on page
122
MAX, MIN
National
“Finding the largest or smallest data item” on page 124
ORD-MAX, ORD-MIN
Integer
“Finding the largest or smallest data item” on page 124
REVERSE
National
“Transforming to reverse order (REVERSE)” on page 121
You can use national decimal arguments wherever zoned decimal arguments are
allowed. You can use national floating-point arguments wherever display
floating-point arguments are allowed. (See the related reference below about
arguments for a complete list of intrinsic functions that can take integer or numeric
arguments.)
RELATED TASKS
“Defining numeric data” on page 45
“Using national data (Unicode) in COBOL” on page 134
RELATED REFERENCES
Arguments (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Unicode and the encoding of language characters
Enterprise COBOL provides basic runtime support for Unicode, which can handle
tens of thousands of characters that cover all commonly used characters and
symbols in the world.
A character set is a defined set of characters, but is not associated with a coded
representation. A coded character set (also referred to in this documentation as a code
page) is a set of unambiguous rules that relate the characters of the set to their
coded representation. Each code page has a name and is like a table that sets up
the symbols for representing a character set; each symbol is associated with a
unique bit pattern, or code point. Each code page also has a coded character set
identifier (CCSID), which is a value from 1 to 65,536.
Unicode has several encoding schemes, called Unicode Transformation Format (UTF),
such as UTF-8, UTF-16, and UTF-32. Enterprise COBOL uses UTF-16 (CCSID 1200)
in big-endian format as the representation for national literals and data items that
have USAGE NATIONAL.
UTF-8 represents ASCII invariant characters a-z, A-Z, 0-9, and certain special
characters such as ' @ , . + - = / * ( ) the same way that they are represented in
ASCII. UTF-16 represents these characters as NX’00nn’, where X’nn’ is the
representation of the character in ASCII.
For example, the string ’ABC’ is represented in UTF-16 as NX’004100420043’. In
UTF-8, ’ABC’ is represented as X’414243’.
One or more encoding units are used to represent a character from a coded
character set. For UTF-16, an encoding unit takes 2 bytes of storage. Any character
Chapter 7. Processing data in an international environment
133
defined in any EBCDIC, ASCII, or EUC code page is represented in one UTF-16
encoding unit when the character is converted to the national data representation.
Cross-platform considerations: Enterprise COBOL and COBOL for AIX® support
UTF-16 in big-endian format in national data. COBOL for Windows supports
UTF-16 in little-endian format (UTF-16LE) in national data. If you are porting
Unicode data that is encoded in UTF-16LE representation to Enterprise COBOL
from another platform, you must convert that data to UTF-16 in big-endian format
to process the data as national data.
RELATED TASKS
“Converting to or from national (Unicode) representation” on page 142
RELATED REFERENCES
“Storage of character data” on page 141
Character sets and code pages (Enterprise COBOL Language Reference)
Using national data (Unicode) in COBOL
In Enterprise COBOL, you can specify national (UTF-16) data in any of several
ways.
About this task
These types of national data are available:
v National data items (categories national, national-edited, and numeric-edited)
v National literals
v Figurative constants as national characters
v Numeric data items (national decimal and national floating-point)
In addition, you can define national groups that contain only data items that
explicitly or implicitly have USAGE NATIONAL, and that behave in the same way as
elementary category national data items in most operations.
These declarations affect the amount of storage that is needed.
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
“National groups” on page 137
RELATED TASKS
“Defining national data items” on page 135
“Using national literals” on page 135
“Using national-character figurative constants” on page 136
“Defining national numeric data items” on page 137
“Using national groups” on page 139
“Converting to or from national (Unicode) representation” on page 142
“Comparing national (UTF-16) data” on page 152
RELATED REFERENCES
“Storage of character data” on page 141
Classes and categories of data (Enterprise COBOL Language Reference)
134
Enterprise COBOL for z/OS, V5.1 Programming Guide
Defining national data items
Define national data items with the USAGE NATIONAL clause to hold national
(UTF-16) character strings.
About this task
You can define national data items of the following categories:
v National
v National-edited
v Numeric-edited
To define a category national data item, code a PICTURE clause that contains only
one or more PICTURE symbols N.
To define a national-edited data item, code a PICTURE clause that contains at least
one of each of the following symbols:
v Symbol N
v Simple insertion editing symbol B, 0, or /
To define a numeric-edited data item of class national, code a PICTURE clause that
defines a numeric-edited item (for example, -$999.99) and code a USAGE NATIONAL
clause. You can use a numeric-edited data item that has USAGE NATIONAL in the
same way that you use a numeric-edited item that has USAGE DISPLAY.
You can also define a data item as numeric-edited by coding the BLANK WHEN ZERO
clause for an elementary item that is defined as numeric by its PICTURE clause.
If you code a PICTURE clause but do not code a USAGE clause for data items that
contain only one or more PICTURE symbols N, you can use the compiler option
NSYMBOL(NATIONAL) to ensure that such items are treated as national data items
instead of as DBCS items.
RELATED TASKS
“Displaying numeric data” on page 47
RELATED REFERENCES
“NSYMBOL” on page 346
BLANK WHEN ZERO clause (Enterprise COBOL Language Reference)
Using national literals
To specify national literals, use the prefix character N and compile with the option
NSYMBOL(NATIONAL).
About this task
You can use either of these notations:
v N"character-data"
v N’character-data’
If you compile with the option NSYMBOL(DBCS), the literal prefix character N
specifies a DBCS literal, not a national literal.
Chapter 7. Processing data in an international environment
135
To specify a national literal as a hexadecimal value, use the prefix NX. You can use
either of these notations:
v NX"hexadecimal-digits"
v NX’hexadecimal-digits’
Each of the following MOVE statements sets the national data item Y to the UTF-16
value of the characters 'AB':
01 Y pic
. . .
Move
Move
Move
NN usage national.
NX"00410042" to Y
N"AB"
to Y
"AB"
to Y
Do not use alphanumeric hexadecimal literals in contexts that call for national
literals, because such usage is easily misunderstood. For example, the following
statement also results in moving the UTF-16 characters 'AB' (not the hexadecimal bit
pattern C1C2) to Y, where Y is defined as USAGE NATIONAL:
Move X"C1C2" to Y
You cannot use national literals in the SPECIAL-NAMES paragraph or as
program-names. You can use a national literal to name an object-oriented method
in the METHOD-ID paragraph or to specify a method-name in an INVOKE statement.
RELATED TASKS
“Using literals” on page 26
RELATED REFERENCES
“NSYMBOL” on page 346
National literals (Enterprise COBOL Language Reference)
Using national-character figurative constants
You can use the figurative constant ALL national-literal in a context that requires
national characters. ALL national-literal represents all or part of the string that is
generated by successive concatenations of the encoding units that make up the
national literal.
About this task
You can use the figurative constants QUOTE, SPACE, HIGH-VALUE, LOW-VALUE, or ZERO
in a context that requires national characters, such as a MOVE statement, an implicit
move, or a relation condition that has national operands. In these contexts, the
figurative constant represents a national-character (UTF-16) value.
When you use the figurative constant HIGH-VALUE in a context that requires
national characters, its value is NX’FFFF’. When you use LOW-VALUE in a context
that requires national characters, its value is NX’0000’.
Restrictions: You must not use HIGH-VALUE or the value assigned from HIGH-VALUE
in a way that results in conversion of the value from one data representation to
another (for example, between USAGE DISPLAY and USAGE NATIONAL). X’FF’ (the
value of HIGH-VALUE in an alphanumeric context when the EBCDIC collating
sequence is being used) does not represent a valid EBCDIC character, and NX’FFFF’
does not represent a valid national character. Conversion of such a value to
another representation results in a substitution character being used (not X’FF’ or
NX’FFFF’). Consider the following example:
136
Enterprise COBOL for z/OS, V5.1 Programming Guide
01 natl-data PIC NN Usage National.
01 alph-data PIC XX.
. . .
MOVE HIGH-VALUE TO natl-data, alph-data
IF natl-data = alph-data. . .
The IF statement above evaluates as false even though each of its operands was set
to HIGH-VALUE. Before an elementary alphanumeric operand is compared to a
national operand, the alphanumeric operand is treated as though it were moved to
a temporary national data item, and the alphanumeric characters are converted to
the corresponding national characters. When X’FF’ is converted to UTF-16,
however, the UTF-16 item gets a substitution character value and so does not
compare equally to NX’FFFF’.
RELATED TASKS
“Converting to or from national (Unicode) representation” on page 142
“Comparing national (UTF-16) data” on page 152
RELATED REFERENCES
Figurative constants (Enterprise COBOL Language Reference)
DISPLAY-OF (Enterprise COBOL Language Reference)
Support for Unicode: Using Unicode Services
Defining national numeric data items
Define data items with the USAGE NATIONAL clause to hold numeric data that is
represented in national characters (UTF-16). You can define national decimal items
and national floating-point items.
About this task
To define a national decimal item, code a PICTURE clause that contains only the
symbols 9, P, S, and V. If the PICTURE clause contains S, the SIGN IS SEPARATE
clause must be in effect for that item.
To define a national floating-point item, code a PICTURE clause that defines a
floating-point item (for example, +99999.9E-99).
You can use national decimal items in the same way that you use zoned decimal
items. You can use national floating-point items in the same way that you use
display floating-point items.
RELATED TASKS
“Defining numeric data” on page 45
“Displaying numeric data” on page 47
RELATED REFERENCES
SIGN clause (Enterprise COBOL Language Reference)
National groups
National groups, which are specified either explicitly or implicitly with the
GROUP-USAGE NATIONAL clause, contain only data items that have USAGE NATIONAL. In
most cases, a national group item is processed as though it were redefined as an
elementary category national item described as PIC N(m), where m is the number
of national (UTF-16) characters in the group.
Chapter 7. Processing data in an international environment
137
For some operations on national groups, however (just as for some operations on
alphanumeric groups), group semantics apply. Such operations (for example, MOVE
CORRESPONDING and INITIALIZE) recognize or process the elementary items within
the national group.
Where possible, use national groups instead of alphanumeric groups that contain
USAGE NATIONAL items. National groups provide several advantages for the
processing of national data compared to the processing of national data within
alphanumeric groups:
v When you move a national group to a longer data item that has USAGE NATIONAL,
the receiving item is padded with national characters. By contrast, if you move
an alphanumeric group that contains national characters to a longer
alphanumeric group that contains national characters, alphanumeric spaces are
used for padding. As a result, mishandling of data items could occur.
v When you move a national group to a shorter data item that has USAGE
NATIONAL, the national group is truncated at national-character boundaries. By
contrast, if you move an alphanumeric group that contains national characters to
a shorter alphanumeric group that contains national characters, truncation might
occur between the 2 bytes of a national character.
v When you move a national group to a national-edited or numeric-edited item,
the content of the group is edited. By contrast, if you move an alphanumeric
group to an edited item, no editing takes place.
v When you use a national group as an operand in a STRING, UNSTRING, or INSPECT
statement:
– The group content is processed as national characters rather than as
single-byte characters.
– TALLYING and POINTER operands operate at the logical level of national
characters.
– The national group operand is supported with a mixture of other national
operand types.
By contrast, if you use an alphanumeric group that contains national characters
in these contexts, the characters are processed byte by byte. As a result, invalid
handling or corruption of data could occur.
USAGE NATIONAL groups: A group item can specify the USAGE NATIONAL clause at the
group level as a convenient shorthand for the USAGE of each of the elementary data
items within the group. Such a group is not a national group, however, but an
alphanumeric group, and behaves in many operations, such as moves and
compares, like an elementary data item of USAGE DISPLAY (except that no editing or
conversion of data occurs).
RELATED TASKS
“Assigning values to group data items (MOVE)” on page 33
“Joining data items (STRING)” on page 109
“Splitting data items (UNSTRING)” on page 111
“Tallying and replacing data items (INSPECT)” on page 119
“Using national groups” on page 139
RELATED REFERENCES
GROUP-USAGE clause (Enterprise COBOL Language Reference)
138
Enterprise COBOL for z/OS, V5.1 Programming Guide
Using national groups
To define a group data item as a national group, code a GROUP-USAGE NATIONAL
clause at the group level for the item. The group can contain only data items that
explicitly or implicitly have USAGE NATIONAL.
About this task
The following data description entry specifies that a level-01 group and its
subordinate groups are national group items:
01
Nat-Group-1
GROUP-USAGE NATIONAL.
02 Group-1.
04 Month
PIC 99.
04 DayOf
PIC 99.
04 Year
PIC 9999.
02 Group-2
GROUP-USAGE NATIONAL.
04 Amount PIC 9(4).99 USAGE NATIONAL.
In the example above, Nat-Group-1 is a national group, and its subordinate groups
Group-1 and Group-2 are also national groups. A GROUP-USAGE NATIONAL clause is
implied for Group-1, and USAGE NATIONAL is implied for the subordinate items in
Group-1. Month, DayOf, and Year are national decimal items, and Amount is a
numeric-edited item that has USAGE NATIONAL.
You can subordinate national groups within alphanumeric groups as in the
following example:
01
Alpha-Group-1.
02 Group-1.
04 Month
PIC 99.
04 DayOf
PIC 99.
04 Year
PIC 9999.
02 Group-2
GROUP-USAGE NATIONAL.
04 Amount PIC 9(4).99.
In the example above, Alpha-Group-1 and Group-1 are alphanumeric groups; USAGE
DISPLAY is implied for the subordinate items in Group-1. (If Alpha-Group-1 specified
USAGE NATIONAL at the group level, USAGE NATIONAL would be implied for each of
the subordinate items in Group-1. However, Alpha-Group-1 and Group-1 would be
alphanumeric groups, not national groups, and would behave like alphanumeric
groups during operations such as moves and compares.) Group-2 is a national
group, and USAGE NATIONAL is implied for the numeric-edited item Amount.
You cannot subordinate alphanumeric groups within national groups. All
elementary items within a national group must be explicitly or implicitly described
as USAGE NATIONAL, and all group items within a national group must be explicitly
or implicitly described as GROUP-USAGE NATIONAL.
RELATED CONCEPTS
“National groups” on page 137
RELATED TASKS
“Using national groups as elementary items” on page 140
“Using national groups as group items” on page 140
RELATED REFERENCES
GROUP-USAGE clause (Enterprise COBOL Language Reference)
Chapter 7. Processing data in an international environment
139
Using national groups as elementary items
In most cases, you can use a national group as though it were an elementary data
item.
About this task
In the following example, a national group item, Group-1, is moved to a
national-edited item, Edited-date. Because Group-1 is treated as an elementary
data item during the move, editing takes place in the receiving data item. The
value in Edited-date after the move is 06/23/2010 in national characters.
01
01
Edited-date PIC NN/NN/NNNN USAGE NATIONAL.
Group-1
GROUP-USAGE NATIONAL.
02 Month
PIC 99
VALUE 06.
02 DayOf
PIC 99
VALUE 23.
02 Year
PIC 9999 VALUE 2010.
. . .
MOVE Group-1 to Edited-date.
If Group-1 were instead an alphanumeric group in which each of its subordinate
items had USAGE NATIONAL (specified either explicitly with a USAGE NATIONAL clause
on each elementary item, or implicitly with a USAGE NATIONAL clause at the group
level), a group move, rather than an elementary move, would occur. Neither
editing nor conversion would take place during the move. The value in the first
eight character positions of Edited-date after the move would be 06232010 in
national characters, and the value in the remaining two character positions would
be 4 bytes of alphanumeric spaces.
RELATED TASKS
“Assigning values to group data items (MOVE)” on page 33
“Comparing national data and alphanumeric-group operands” on page 154
“Using national groups as group items”
RELATED REFERENCES
MOVE statement (Enterprise COBOL Language Reference)
Using national groups as group items
In some cases when you use a national group, it is handled with group semantics;
that is, the elementary items in the group are recognized or processed.
About this task
In the following example, an INITIALIZE statement that acts upon national group
item Group-OneN causes the value 15 in national characters to be moved to only the
numeric items in the group:
01
Group-OneN
Group-Usage National.
05 Trans-codeN
Pic N
Value "A".
05 Part-numberN
Pic NN Value "XX".
05 Trans-quanN
Pic 99 Value 10.
. . .
Initialize Group-OneN Replacing Numeric Data By 15
Because only Trans-quanN in Group-OneN above is numeric, only Trans-quanN
receives the value 15. The other subordinate items are unchanged.
The table below summarizes the cases where national groups are processed with
group semantics.
140
Enterprise COBOL for z/OS, V5.1 Programming Guide
Table 17. National group items that are processed with group semantics
Language feature
Uses of national group items
Comment
CORRESPONDING phrase Specify a national group item for
of the ADD, SUBTRACT, processing as a group in
or MOVE statement
accordance with the rules of the
CORRESPONDING phrase.
Elementary items within the
national group are processed
like elementary items that
have USAGE NATIONAL within
an alphanumeric group.
Host variable in EXEC
SQL statement
Specify a national group item as a
host variable.
The national group item is in
effect shorthand for the set of
host variables that are
subordinate to the group item.
INITIALIZE statement
Specify a national group for
processing as a group in
accordance with the rules of the
INITIALIZE statement.
Elementary items within the
national group are initialized
like elementary items that
have USAGE NATIONAL within
an alphanumeric group.
Name qualification
Use the name of a national group
item to qualify the names of
elementary data items and of
subordinate group items in the
national group.
Follow the same rules for
qualification as for an
alphanumeric group.
THROUGH phrase of the To specify a national group item in The result is an alphanumeric
group item.
RENAMES clause
the THROUGH phrase, use the same
rules as for an alphanumeric group
item.
FROM phrase of the
XML GENERATE
statement
Specify a national group item in
the FROM phrase for processing as a
group in accordance with the rules
of the XML GENERATE statement.
Elementary items within the
national group are processed
like elementary items that
have USAGE NATIONAL within
an alphanumeric group.
RELATED TASKS
“Initializing a structure (INITIALIZE)” on page 31
“Initializing a table (INITIALIZE)” on page 76
“Assigning values to elementary data items (MOVE)” on page 32
“Assigning values to group data items (MOVE)” on page 33
“Finding the length of data items” on page 126
“Generating XML output” on page 557
“Using national group items in SQL statements” on page 437
RELATED REFERENCES
Qualification (Enterprise COBOL Language Reference)
RENAMES clause (Enterprise COBOL Language Reference)
Storage of character data
Use the table below to compare alphanumeric (DISPLAY), DBCS (DISPLAY-1), and
Unicode (NATIONAL) encoding and to plan storage usage.
Table 18. Encoding and size of alphanumeric, DBCS, and national data
Characteristic
DISPLAY
DISPLAY-1
NATIONAL
Character encoding unit
1 byte
2 bytes
2 bytes
Code page
EBCDIC
EBCDIC DBCS
UTF-16BE1
Chapter 7. Processing data in an international environment
141
Table 18. Encoding and size of alphanumeric, DBCS, and national data (continued)
Characteristic
DISPLAY
DISPLAY-1
NATIONAL
Encoding units per graphic
character
1
1
1 or 22
Bytes per graphic character
1 byte
2 bytes
2 or 4 bytes
1. Use the CODEPAGE compiler option to specify the EBCDIC code page that is applicable to
alphanumeric or DBCS data.
2. Most characters are represented in UTF-16 using one encoding unit. In particular, the
following characters are represented using a single UTF-16 encoding unit per character:
v COBOL characters A-Z, a-z, 0-9, space, + - * / = $ , ; . " ( ) > < :'
v All characters that are converted from an EBCDIC or ASCII code page
RELATED CONCEPTS
“Unicode and the encoding of language characters” on page 133
Converting to or from national (Unicode) representation
You can implicitly or explicitly convert data items to national (UTF-16)
representation.
About this task
You can implicitly convert alphabetic, alphanumeric, DBCS, or integer data to
national data by using the MOVE statement. Implicit conversions also take place in
other COBOL statements, such as IF statements that compare an alphanumeric
data item with a data item that has USAGE NATIONAL.
You can explicitly convert to and from national data items by using the intrinsic
functions NATIONAL-OF and DISPLAY-OF, respectively. By using these intrinsic
functions, you can specify a code page for the conversion that is different from the
code page that is in effect with the CODEPAGE compiler option.
RELATED TASKS
“Converting alphanumeric, DBCS, and integer to national (MOVE)”
“Converting alphanumeric or DBCS to national (NATIONAL-OF)” on page 143
“Converting national to alphanumeric (DISPLAY-OF)” on page 144
“Overriding the default code page” on page 144
“Comparing national (UTF-16) data” on page 152
RELATED REFERENCES
“CODEPAGE” on page 322
“Conversion exceptions” on page 144
Converting alphanumeric, DBCS, and integer to national
(MOVE)
You can use a MOVE statement to implicitly convert data to national representation.
About this task
You can move the following kinds of data to category national or national-edited
data items, and thus convert the data to national representation:
v Alphabetic
142
Enterprise COBOL for z/OS, V5.1 Programming Guide
v
v
v
v
v
Alphanumeric
Alphanumeric-edited
DBCS
Integer of USAGE DISPLAY
Numeric-edited of USAGE DISPLAY
You can likewise move the following kinds of data to numeric-edited data items
that have USAGE NATIONAL:
v Alphanumeric
v Display floating-point (floating-point of USAGE DISPLAY)
v Numeric-edited of USAGE DISPLAY
v Integer of USAGE DISPLAY
For complete rules about moves to national data, see the related reference about
the MOVE statement.
For example, the MOVE statement below moves the alphanumeric literal "AB" to the
national data item UTF16-Data:
01
UTF16-Data Pic N(2) Usage National.
. . .
Move "AB" to UTF16-Data
After the MOVE statement above, UTF16-Data contains NX’00410042’, the national
representation of the alphanumeric characters 'AB'.
If padding is required in a receiving data item that has USAGE NATIONAL, the default
UTF-16 space character (NX’0020’) is used. If truncation is required, it occurs at the
boundary of a national-character position.
RELATED TASKS
“Assigning values to elementary data items (MOVE)” on page 32
“Assigning values to group data items (MOVE)” on page 33
“Displaying numeric data” on page 47
“Coding for use of DBCS support” on page 155
RELATED REFERENCES
MOVE statement (Enterprise COBOL Language Reference)
Converting alphanumeric or DBCS to national (NATIONAL-OF)
Use the NATIONAL-OF intrinsic function to convert alphabetic, alphanumeric, or
DBCS data to a national data item. Specify the source code page as the second
argument if the source is encoded in a different code page than is in effect with the
CODEPAGE compiler option.
About this task
“Example: converting to and from national data” on page 145
RELATED TASKS
“Processing UTF-8 data” on page 145
“Processing Chinese GB 18030 data” on page 151
“Processing alphanumeric data items that contain DBCS data” on page 157
Chapter 7. Processing data in an international environment
143
RELATED REFERENCES
“CODEPAGE” on page 322
NATIONAL-OF (Enterprise COBOL Language Reference)
Converting national to alphanumeric (DISPLAY-OF)
Use the DISPLAY-OF intrinsic function to convert national data to an alphanumeric
(USAGE DISPLAY) character string that is represented in a code page that you specify
as the second argument.
About this task
If you omit the second argument, the output code page is the one that was in
effect with the CODEPAGE compiler option when the source was compiled.
If you specify an EBCDIC or ASCII code page that combines single-byte character
set (SBCS) and DBCS characters, the returned string might contain a mixture of
SBCS and DBCS characters. The DBCS substrings are delimited by shift-in and
shift-out characters if the code page in effect for the function is an EBCDIC code
page.
“Example: converting to and from national data” on page 145
RELATED TASKS
“Processing UTF-8 data” on page 145
“Processing Chinese GB 18030 data” on page 151
RELATED REFERENCES
DISPLAY-OF (Enterprise COBOL Language Reference)
Overriding the default code page
In some cases, you might need to convert data to or from a code page that differs
from the CCSID that is specified as the CODEPAGE option value. To do so, convert
the item by using a conversion function in which you explicitly specify the code
page.
About this task
If you specify a code page as an argument to the DISPLAY-OF intrinsic function, and
the code page differs from the code page that is in effect with the CODEPAGE
compiler option, do not use the function result in any operations that involve
implicit conversion (such as an assignment to, or comparison with, a national data
item). Such operations assume the EBCDIC code page that is specified with the
CODEPAGE compiler option.
RELATED REFERENCES
“CODEPAGE” on page 322
Conversion exceptions
Implicit or explicit conversion between national data and alphanumeric data can
fail and generate a severity-3 Language Environment condition.
Failure can occur if the code page that you specified implicitly or explicitly is not a
valid code page.
144
Enterprise COBOL for z/OS, V5.1 Programming Guide
A character that does not have a counterpart in the target CCSID does not result in
a conversion exception. Such a character is converted to a substitution character in
the target code page.
RELATED REFERENCES
“CODEPAGE” on page 322
Example: converting to and from national data
The following example shows the NATIONAL-OF and DISPLAY-OF intrinsic functions
and the MOVE statement for converting to and from national (UTF-16) data items. It
also demonstrates the need for explicit conversions when you operate on strings
that are encoded in multiple code pages.
CBL CODEPAGE(00037)
* . . .
01 Data-in-Unicode
pic N(100) usage national.
01 Data-in-Greek
pic X(100).
01 other-data-in-US-English pic X(12) value "PRICE in $ =".
* . . .
Read Greek-file into Data-in-Greek
Move function National-of(Data-in-Greek, 00875)
to Data-in-Unicode
* . . . process Data-in-Unicode here . . .
Move function Display-of(Data-in-Unicode, 00875)
to Data-in-Greek
Write Greek-record from Data-in-Greek
The example above works correctly because the input code page is specified.
Data-in-Greek is converted as data represented in CCSID 00875 (Greek). However,
the following statement results in an incorrect conversion unless all the characters
in the item happen to be among those that have a common representation in both
the Greek and the English code pages:
Move Data-in-Greek to Data-in-Unicode
The MOVE statement above converts Data-in-Greek to Unicode representation based
on the CCSID 00037 (U.S. English) to UTF-16 conversion. This conversion does not
produce the expected results because Data-in-Greek is encoded in CCSID 00875.
If you can correctly set the CODEPAGE compiler option to CCSID 00875 (that is, the
rest of your program also handles EBCDIC data in Greek), you can code the same
example correctly as follows:
CBL CODEPAGE(00875)
* . . .
01 Data-in-Unicode pic N(100) usage national.
01 Data-in-Greek
pic X(100).
* . . .
Read Greek-file into Data-in-Greek
* . . . process Data-in-Greek here ...
* . . . or do the following (if need to process data in Unicode):
Move Data-in-Greek to Data-in-Unicode
* . . . process Data-in-Unicode
Move function Display-of(Data-in-Unicode) to Data-in-Greek
Write Greek-record from Data-in-Greek
|
|
|
|
|
Processing UTF-8 data
To process UTF-8 data, first convert the UTF-8 data to UTF-16 in a national data
item. After processing the national data, convert it back to UTF-8 for output. For
the conversions, use the intrinsic functions NATIONAL-OF and DISPLAY-OF,
respectively. Use code page 1208 for UTF-8 data.
Chapter 7. Processing data in an international environment
145
|
About this task
|
|
|
|
|
|
National data is encoded in UTF-16, which uses one encoding unit for almost all
commonly encountered characters. With this property, you can use string
operations such as reference modification on the national data. If it is more
convenient to retain the UTF-8 encoding, use the Unicode intrinsic functions to
assist with processing the data. For details, see “Using intrinsic functions to
process UTF-8 encoded data”.
|
Take the following steps to convert ASCII or EBCDIC data to UTF-8:
|
|
|
|
Procedure
|
Results
|
The following example converts Greek EBCDIC data to UTF-8:
1. Use the function NATIONAL-OF to convert the ASCII or EBCDIC string to a
national (UTF-16) string.
2. Use the function DISPLAY-OF to convert the national string to UTF-8.
|
|
|
|
Usage note: Use care if you use reference modification to refer to data encoded in
UTF-8. UTF-8 characters are encoded with a varying number of bytes per
character. Avoid operations that might split a multibyte character.
|
|
|
|
|
RELATED TASKS
“Referring to substrings of data items” on page 115
“Converting to or from national (Unicode) representation” on page 142
“Parsing XML documents encoded in UTF-8” on page 540
“Using intrinsic functions to process UTF-8 encoded data”
Using intrinsic functions to process UTF-8 encoded data
|
|
|
If it is more convenient to keep your data encoded in UTF-8, use the Unicode
intrinsic functions to facilitate testing and processing the UTF-8 data.
|
About this task
|
You can use the following intrinsic functions:
|
UVALID To verify that the UTF-8 character data is well-formed
|
|
|
|
|
|
|
USUPPLEMENTARY
If the data is to be converted to national, and it is important that every
character can be represented by a single 16-bit encoding unit, use the
USUPPLEMENTARY function to determine whether a valid UTF-8 character
string contains a Unicode supplementary code point; that is, a code point
with a Unicode scalar value above U+FFFF, requiring a 4-byte
representation in UTF-8.
|
|
|
USUBSTR
It provides a convenient alternative to reference modification for referring
to substrings of the UTF-8 character string. USUBSTR expects character
146
Enterprise COBOL for z/OS, V5.1 Programming Guide
position and length arguments versus the computed byte locations and
counts required by reference modification.
|
|
|
|
Auxiliary functions can provide additional information about a valid UTF-8
character string:
|
|
ULENGTH
|
UPOS
|
|
UWIDTH To determine the width in bytes of the nth Unicode code point in the
string
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following code fragment illustrates UTF-8 validity checking, and the use of the
auxiliary functions:
|
|
|
In the following string, the sequence that starts with x'F5' is not valid UTF-8
because no byte can have a value in the range x'F5' to x'FF':
|
|
|
|
The output from checkUTF-8-validity for this string is as follows:
|
|
|
|
|
|
|
|
|
|
|
|
|
The following code fragment illustrates checking for the presence of a Unicode
supplementary code point, requiring a 4-byte representation in UTF-8:
|
|
|
In the following string, the sequence x'F0908C82' is a supplementary character (as
is any valid UTF-8 sequence beginning with a byte in the range x'F0' to x'F4'):
|
|
|
|
The output from checkUTF-8-supp for this string is as follows:
To determine the total number of Unicode code points in the string
To determine the byte position in the string of the nth Unicode code point
checkUTF-8-validity.
Compute u = function UVALID(UTF-8-testStr)
If u not = 0
Display ’checkUTF-8-validity failure:’
Display ’ The UTF-8 representation is not valid,’
’starting at byte ’ u ’.’
Compute v = function ULENGTH(UTF-8-testStr(1:u - 1))
Compute u = function UPOS(UTF-8-testStr v)
Compute w = function UWIDTH(UTF-8-testStr v)
Display ’ The ’ v ’th and last valid code point starts ’
’at byte ’ u ’ for ’ w ’ bytes.’
End-if.
x’6162D0B0E4BA8CF5646364’
checkUTF-8-validity failure:
The UTF-8 representation is not valid, starting at byte 08.
The 04th and last valid code point starts at byte 05 for 03 bytes.
checkUTF-8-supp.
Compute u = function USUPPLEMENTARY(UTF-8-testStr)
If u not = 0
Display ’ checkUTF-8-supp hit:’
Compute v = function ULENGTH(UTF-8-testStr(1:u - 1))
Compute w = function UWIDTH(UTF-8-testStr v + 1)
Display ’ The ’ v ’th code point of the string
’, starting at byte ’ u ’,’
Display ’ is a Unicode supplementary code point, ’
’width ’ w ’ bytes.’
End-if.
x’6162D0B0E4BA8CF0908C826364’
checkUTF-8-supp hit:
The 04th code point of the string, starting at byte 08,
is a Unicode supplementary code point, width 04 bytes.
Chapter 7. Processing data in an international environment
147
|
|
RELATED REFERENCES
|
|
|
|
|
|
|
|
Example: deriving initials from UTF-8 names
“CODEPAGE” on page 322
The following program uses the Unicode functions to derive composers’ initials
from a table of names in Czech. It is intended to illustrate these functions, and is
not necessarily the most efficient way of doing the task. Although the program
processes the composer names in UTF-8, the data begins and ends in EBCDIC in
order to permit a meaningful display of the program source and output. The
compiler option CODEPAGE(1153) ensures that the names are interpreted correctly
when translated to and from Unicode.
148
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
Program initials
|
Chapter 7. Processing data in an international environment
149
Program initials, continued
|
|
|
|
|
|
|
|
|
|
|
Output from program initials
Compute composer initials...
#1: ALD (x’414C44’)
#2: LJ (x’4C4A’)
#3: RJK (x’524A4B’)
#4: PK (x’504B’)
#5: JVHV (x’4A564856’)
150
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Program toHex
Identification division.
Program-id. toHex.
Data division.
Working-storage section.
1 hexv.
2 pic x(32) value ’000102030405060708090A0B0C0D0E0F’.
2 pic x(32) value ’101112131415161718191A1B1C1D1E1F’.
2 pic x(32) value ’202122232425262728292A2B2C2D2E2F’.
2 pic x(32) value ’303132333435363738393A3B3C3D3E3F’.
2 pic x(32) value ’404142434445464748494A4B4C4D4E4F’.
2 pic x(32) value ’505152535455565758595A5B5C5D5E5F’.
2 pic x(32) value ’606162636465666768696A6B6C6D6E6F’.
2 pic x(32) value ’707172737475767778797A7B7C7D7E7F’.
2 pic x(32) value ’808182838485868788898A8B8C8D8E8F’.
2 pic x(32) value ’909192939495969798999A9B9C9D9E9F’.
2 pic x(32) value ’A0A1A2A3A4A5A6A7A8A9AAABACADAEAF’.
2 pic x(32) value ’B0B1B2B3B4B5B6B7B8B9BABBBCBDBEBF’.
2 pic x(32) value ’C0C1C2C3C4C5C6C7C8C9CACBCCCDCECF’.
2 pic x(32) value ’D0D1D2D3D4D5D6D7D8D9DADBDCDDDEDF’.
2 pic x(32) value ’E0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF’.
2 pic x(32) value ’F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF’.
1 redefines hexv.
2 hex pic xx occurs 256 times.
Local-storage section.
1 i pic 9(4) binary.
1 j pic 9(4) binary value 0.
1 jx redefines j.
2 pic x.
2 jxd pic x.
Linkage section.
1 ostr.
2 ostrv pic xx occurs 1024 times.
1 istr.
2 istrv pic x occurs 1024 times.
1 len pic 9(9) binary.
Procedure division using ostr istr value len.
If len > 1024
Display ’>> Error: length ’ len ’ greater than toHex ’
’supported maximum of 1024.’
Stop run
End-if
Perform with test before varying i from 1 by 1 until i > len
Move 0 to j
Move istrv(i) to jxd
Add 1 to j
Move hex(j) to ostrv(i)
End-perform
Goback
.
End program toHex.
|
Processing Chinese GB 18030 data
GB 18030 is a national-character standard specified by the government of the
People's Republic of China.
About this task
GB 18030 characters can be encoded in either UTF-16 or in code page CCSID 1392.
Code page 1392 is an ASCII multibyte code page that uses 1, 2, or 4 bytes per
character. A subset of the GB 18030 characters can be encoded in the Chinese ASCII
code page, CCSID 1386, or in the Chinese EBCDIC code page, CCSID 1388.
Chapter 7. Processing data in an international environment
151
Enterprise COBOL does not have explicit support for GB 18030, but does support
the processing of GB 18030 characters in several ways. You can:
v Use DBCS data items to process GB 18030 characters that are represented in
CCSID 1388.
v Use national data items to define and process GB 18030 characters that are
represented in UTF-16, CCSID 01200.
v Process data in any code page (including CCSID 1388 or 1392) by converting the
data to UTF-16, processing the UTF-16 data, and then converting the data back
to the original code-page representation.
When you need to process Chinese GB 18030 data that requires conversion, first
convert the input data to UTF-16 in a national data item. After you process the
national data item, convert it back to Chinese GB 18030 for output. For the
conversions, use the intrinsic functions NATIONAL-OF and DISPLAY-OF, respectively,
and specify code page 1388 or 1392 as the second argument of each function.
The following example illustrates these conversions:
RELATED TASKS
“Converting to or from national (Unicode) representation” on page 142
“Coding for use of DBCS support” on page 155
RELATED REFERENCES
“Storage of character data” on page 141
Comparing national (UTF-16) data
You can compare national (UTF-16) data, that is, national literals and data items
that have USAGE NATIONAL (whether of class national or class numeric), explicitly or
implicitly with other kinds of data in relation conditions.
About this task
You can code conditional expressions that use national data in the following
statements:
v EVALUATE
v IF
v
v
v
v
v
INSPECT
PERFORM
SEARCH
STRING
UNSTRING
For full details about comparing national data items to other data items, see the
related references.
152
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED TASKS
“Comparing
“Comparing
“Comparing
“Comparing
“Comparing
two class national operands”
class national and class numeric operands”
national numeric and other numeric operands” on page 154
national and other character-string operands” on page 154
national data and alphanumeric-group operands” on page 154
RELATED REFERENCES
Relation conditions (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
National comparisons (Enterprise COBOL Language Reference)
Group comparisons (Enterprise COBOL Language Reference)
Comparing two class national operands
You can compare the character values of two operands of class national.
About this task
Either operand (or both) can be any of the following types of items:
v A national group
v An elementary category national or national-edited data item
v A numeric-edited data item that has USAGE NATIONAL
One of the operands can instead be a national literal or a national intrinsic
function.
When you compare two class national operands that have the same length, they
are determined to be equal if all pairs of the corresponding characters are equal.
Otherwise, comparison of the binary values of the first pair of unequal characters
determines the operand with the larger binary value.
When you compare operands that have unequal lengths, the shorter operand is
treated as if it were padded on the right with default UTF-16 space characters
(NX’0020’) to the length of the longer operand.
The PROGRAM COLLATING SEQUENCE clause does not affect the comparison of two
class national operands.
RELATED CONCEPTS
“National groups” on page 137
RELATED TASKS
“Using national groups” on page 139
RELATED REFERENCES
National comparisons (Enterprise COBOL Language Reference)
Comparing class national and class numeric operands
You can compare national literals or class national data items to integer literals or
numeric data items that are defined as integer (that is, national decimal items or
zoned decimal items). At most one of the operands can be a literal.
Chapter 7. Processing data in an international environment
153
About this task
You can also compare national literals or class national data items to floating-point
data items (that is, display floating-point or national floating-point items).
Numeric operands are converted to national (UTF-16) representation if they are not
already in national representation. A comparison is made of the national character
values of the operands.
RELATED REFERENCES
General relation conditions (Enterprise COBOL Language Reference)
Comparing national numeric and other numeric operands
National numeric operands (national decimal and national floating-point operands)
are data items of class numeric that have USAGE NATIONAL.
About this task
You can compare the algebraic values of numeric operands regardless of their
USAGE. Thus you can compare a national decimal item or a national floating-point
item with a binary item, an internal-decimal item, a zoned decimal item, a display
floating-point item, or any other numeric item.
RELATED TASKS
“Defining national numeric data items” on page 137
RELATED REFERENCES
General relation conditions (Enterprise COBOL Language Reference)
Comparing national and other character-string operands
You can compare the character value of a national literal or class national data item
with the character value of any of the following other character-string operands:
alphabetic, alphanumeric, alphanumeric-edited, DBCS, or numeric-edited of USAGE
DISPLAY.
About this task
These operands are treated as if they were moved to an elementary national data
item. The characters are converted to national (UTF-16) representation, and the
comparison proceeds with two national character operands.
RELATED TASKS
“Using national-character figurative constants” on page 136
RELATED REFERENCES
National comparisons (Enterprise COBOL Language Reference)
Comparing national data and alphanumeric-group operands
You can compare a national literal, a national group item, or any elementary data
item that has USAGE NATIONAL to an alphanumeric group.
154
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
Neither operand is converted. The national operand is treated as if it were moved
to an alphanumeric group item of the same size in bytes as the national operand,
and the two groups are compared. An alphanumeric comparison is done regardless
of the representation of the subordinate items in the alphanumeric group operand.
For example, Group-XN is an alphanumeric group that consists of two subordinate
items that have USAGE NATIONAL:
01
Group-XN.
02 TransCode PIC NN
Value "AB" Usage National.
02 Quantity PIC 999 Value 123
Usage National.
. . .
If N"AB123" = Group-XN Then Display "EQUAL"
Else Display "NOT EQUAL".
When the IF statement above is executed, the 10 bytes of the national literal
N"AB123" are compared byte by byte to the content of Group-XN. The items compare
equally, and "EQUAL" is displayed.
RELATED REFERENCES
Group comparisons (Enterprise COBOL Language Reference)
Coding for use of DBCS support
IBM Enterprise COBOL for z/OS supports using applications in any of many
national languages, including languages that use double-byte character sets
(DBCS).
About this task
The following list summarizes the support for DBCS:
v DBCS characters in user-defined words (DBCS names)
v DBCS characters in comments
v DBCS data items (defined with PICTURE N, G, or G and B)
v DBCS literals
v DBCS compiler option
RELATED TASKS
“Declaring DBCS data”
“Using DBCS literals” on page 156
“Testing for valid DBCS characters” on page 157
“Processing alphanumeric data items that contain DBCS data” on page 157
Appendix B, “Converting double-byte character set (DBCS) data,” on page 687
RELATED REFERENCES
“DBCS” on page 327
Declaring DBCS data
Use the PICTURE and USAGE clauses to declare DBCS data items. DBCS data items
can use PICTURE symbols G, G and B, or N. Each DBCS character position is 2 bytes
in length.
Chapter 7. Processing data in an international environment
155
About this task
You can specify a DBCS data item by using the USAGE DISPLAY-1 clause. When you
use PICTURE symbol G, you must specify USAGE DISPLAY-1. When you use PICTURE
symbol N but omit the USAGE clause, USAGE DISPLAY-1 or USAGE NATIONAL is implied
depending on the setting of the NSYMBOL compiler option.
If you use a VALUE clause with the USAGE clause in the declaration of a DBCS item,
you must specify a DBCS literal or the figurative constant SPACE or SPACES.
For the purpose of handling reference modifications, each character in a DBCS data
item is considered to occupy the number of bytes that corresponds to the
code-page width (that is, 2).
RELATED REFERENCES
“NSYMBOL” on page 346
Using DBCS literals
You can use the prefix N or G to represent a DBCS literal.
About this task
That is, you can specify a DBCS literal in either of these ways:
v N’dbcs characters’ (provided that the compiler option NSYMBOL(DBCS) is in effect)
v G’dbcs characters’
You can use quotation marks (") or single quotation marks (’) as the delimiters of
a DBCS literal irrespective of the setting of the APOST or QUOTE compiler option. You
must code the same opening and closing delimiter for a DBCS literal.
The shift-out (SO) control character X’0E’ must immediately follow the opening
delimiter, and the shift-in (SI) control character X’0F’ must immediately precede
the closing delimiter.
In addition to DBCS literals, you can use alphanumeric literals to specify any
character in one of the supported code pages. However, any string of DBCS
characters that is within an alphanumeric literal must be delimited by the SO and
SI characters, and the DBCS compiler option must be in effect for the SO and SI
characters to be recognized as shift codes.
You cannot continue an alphanumeric literal that contains DBCS characters. The
length of a DBCS literal is likewise limited by the available space in Area B on a
single source line. The maximum length of a DBCS literal is thus 28 double-byte
characters.
An alphanumeric literal that contains DBCS characters is processed byte by byte,
that is, with semantics appropriate for single-byte characters, except when it is
converted explicitly or implicitly to national data representation, as for example in
an assignment to or comparison with a national data item.
RELATED TASKS
“Using figurative constants” on page 27
RELATED REFERENCES
“DBCS” on page 327
156
Enterprise COBOL for z/OS, V5.1 Programming Guide
“NSYMBOL” on page 346
“QUOTE/APOST” on page 355
DBCS literals (Enterprise COBOL Language Reference)
Testing for valid DBCS characters
The Kanji class test tests for valid Japanese graphic characters. This testing includes
Katakana, Hiragana, Roman, and Kanji character sets.
About this task
The Kanji class test is done by checking characters for the range X’41’ through
X’7E’ in the first byte and X’41’ through X’FE’ in the second byte, plus the space
character X’4040’.
The DBCS class test tests for valid graphic characters for the code page.
The DBCS class test is done by checking characters for the range X’41’ through
X’FE’ in both the first and second byte of each character, plus the space character
X’4040’.
RELATED TASKS
“Coding conditional expressions” on page 102
RELATED REFERENCES
Class condition (Enterprise COBOL Language Reference)
Processing alphanumeric data items that contain DBCS data
If you use byte-oriented operations (for example, STRING, UNSTRING, or reference
modification) on an alphanumeric data item that contains DBCS characters, results
are unpredictable. You should instead convert the item to a national data item
before you process it.
About this task
That is, do these steps:
Procedure
1. Convert the item to UTF-16 in a national data item by using a MOVE statement
or the NATIONAL-OF intrinsic function.
2. Process the national data item as needed.
3. Convert the result back to an alphanumeric data item by using the DISPLAY-OF
intrinsic function.
Results
RELATED TASKS
“Joining data items (STRING)” on page 109
“Splitting data items (UNSTRING)” on page 111
“Referring to substrings of data items” on page 115
“Converting to or from national (Unicode) representation” on page 142
Chapter 7. Processing data in an international environment
157
158
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 8. Processing files
About this task
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 items:
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 161
“Allocating files” on page 163
“Checking for input or output errors” on page 164
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, 2013
159
Line-sequential file organization
Line-sequential files are sequential files that reside in the z/OS UNIX file
system and that contain only characters as data. Each record ends with a
newline 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 IBM Enterprise COBOL for z/OS, 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 z/OS 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.
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)
v Line sequential (z/OS UNIX)
160
Enterprise COBOL for z/OS, V5.1 Programming Guide
v Indexed (VSAM)
v Relative (VSAM)
RELATED TASKS
“Allocating files” on page 163
Chapter 9, “Processing QSAM files,” on page 165
Chapter 10, “Processing VSAM files,” on page 191
Chapter 11, “Processing line-sequential files,” on page 219
“Choosing file organization and access mode”
Choosing file organization and access mode
There are several guidelines you can use to determine which file organization and
access mode to use in an application.
About this task
Consider the following guidelines when choosing file organization:
v If an application accesses records (whether fixed-length or variable-length) only
sequentially and does not insert records between existing records, a QSAM or
VSAM sequential file is the simplest type.
v If you are developing an application for z/OS UNIX file system that sequentially
accesses records that contain only printable characters and certain control
characters, line-sequential files work best.
v If an application requires both sequential and random access (whether records
are fixed length or variable length), a VSAM indexed file is the most flexible
type.
v If an application inserts and deletes records randomly, a relative file works well.
Consider the following guidelines when choosing access mode:
v If a large percentage of a file is referenced or updated in an application,
sequential access is faster than random or dynamic access.
v If a small percentage of records is processed during each run of an application,
use random or dynamic access.
Table 19. Summary of file organizations, access modes, and record formats of COBOL
files
File organization
Sequential
access
Random
access
Dynamic
access
Fixed
length
Variable
length
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” on page 162
“Control characters in line-sequential files” on page 220
Chapter 8. Processing files
161
Format for coding input and output
The following example shows the general format of input-output coding.
Explanations of the user-supplied information are shown after the code.
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 described below:
(1) filename
Any legal COBOL name. You must use the same file-name in the SELECT
clause and in the FD entry, and in 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 clause, FD entry,
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 in a DD statement, in an ALLOCATE command (TSO), or
as an environment variable (for example, in an export command) (z/OS
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 COBOL file status key. You can specify the file status key as a
162
Enterprise COBOL for z/OS, V5.1 Programming Guide
two-character category alphanumeric or category national item, or as a
two-digit zoned decimal (USAGE DISPLAY) or national decimal (USAGE
NATIONAL) item.
(6) recordname
The name of the record used in the WRITE or REWRITE statements.
(7) fieldlength
The logical length of the field.
(8) type
The record format of the file. If you break the record entry beyond the
level-01 description, map each element 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 a file, code OUTPUT or EXTEND. If you are both
reading and writing, code I-O, except for organization LINE SEQUENTIAL.
RELATED TASKS
Chapter 9, “Processing QSAM files,” on page 165
Chapter 10, “Processing VSAM files,” on page 191
Chapter 11, “Processing line-sequential files,” on page 219
Allocating files
For any type of file (sequential, line sequential, indexed, or relative) in your z/OS
or z/OS 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.
About this task
If the file is in the z/OS UNIX file system, 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:
Procedure
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 cases:
Chapter 8. Processing files
163
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.
v The dynamic deallocation 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.
3. If neither a ddname nor an environment variable is defined, the following steps
occur:
a. If the allocation is for a QSAM file and the CBLQDA runtime 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.
b. Otherwise, the allocation fails.
Results
The COBOL run time deallocates all dynamic allocations at run unit termination,
except for implicit CBLQDA allocations.
RELATED TASKS
“Setting and accessing environment variables” on page 452
“Defining and allocating QSAM files” on page 181
“Dynamically creating QSAM files” on page 177
“Allocating VSAM files” on page 213
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.
About this task
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 item in the FILE STATUS
clause to get additional VSAM status code information.
Another way of handling errors in input and output operations is to code ERROR
(synonymous with EXCEPTION) declaratives.
RELATED TASKS
“Handling errors in input and output operations” on page 247
“Coding ERROR declaratives” on page 250
“Using file status keys” on page 251
164
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 9. 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.
About this task
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 z/OS UNIX file
system.
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 z/OS UNIX file system 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
z/OS DFSMS: Using Data Sets (Access methods)
RELATED TASKS
“Defining QSAM files and records in COBOL”
“Coding input and output statements for QSAM files” on page 176
“Handling errors in QSAM files” on page 180
“Working with QSAM files” on page 181
“Accessing z/OS UNIX files using QSAM” on page 188
“Processing QSAM ASCII files on tape” on page 189
Defining QSAM files and records in COBOL
Use the FILE-CONTROL entry to define the files in a COBOL program as QSAM files,
and to associate the files with their external file-names.
About this task
An external file-name (a ddname or environment variable 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, 2013
165
FILE-CONTROL.
SELECT COMMUTER-FILE-MST
ASSIGN TO S-COMMUTR
ORGANIZATION IS SEQUENTIAL
ACCESS MODE IS SEQUENTIAL.
The ASSIGN clause name can include an S- before the external 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 173
Establishing record formats
In the FD entry in the DATA DIVISION, code the record format and indication of
whether the records are blocked. In the associated record description entry or
entries, specify the record-name and record length.
About this task
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 the FD entry for the file. If you want the records to be
blocked, code the BLOCK CONTAINS clause in the FD entry.
The following example shows how the FD entry might look for a file that has
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 z/OS UNIX file system. The
above example is appropriate for such a file.
RELATED CONCEPTS
“Logical records”
RELATED TASKS
“Requesting fixed-length format” on page 167
“Requesting variable-length format” on page 168
“Requesting spanned format” on page 170
“Requesting undefined format” on page 172
“Defining QSAM files and records in COBOL” on page 165
RELATED REFERENCES
“FILE SECTION entries” on page 13
Logical records
COBOL uses the term logical record in a slightly different way than z/OS QSAM.
166
Enterprise COBOL for z/OS, V5.1 Programming Guide
For format-V and format-S files, a 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 byte-stream files in the z/OS UNIX file
system, the definitions of QSAM logical record and COBOL logical record are
identical.
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” on page 168
format-V records” on page 169
format-S records” on page 172
format-U records” on page 173
Requesting fixed-length format
Fixed-length records are in format F. Use RECORDING MODE F to explicitly request
this format.
About this task
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 (format-1 RECORD clause) to indicate the
length of the record in bytes.
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 z/OS UNIX file system are never blocked.
RELATED CONCEPTS
“Logical records” on page 166
RELATED TASKS
“Requesting variable-length format” on page 168
“Requesting spanned format” on page 170
“Requesting undefined format” on page 172
“Establishing record formats” on page 166
RELATED REFERENCES
“Layout of format-F records” on page 168
Chapter 9. Processing QSAM files
167
Layout of format-F records:
The layout of format-F QSAM records is shown below.
RELATED CONCEPTS
“Logical records” on page 166
RELATED TASKS
“Requesting fixed-length format” on page 167
z/OS DFSMS: Using Data Sets (Fixed-length record formats)
RELATED REFERENCES
“Layout of format-V records” on page 169
“Layout of format-S records” on page 172
“Layout of format-U records” on page 173
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.
About this task
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 (format-3 RECORD clause).
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. The integer sizes indicate the minimum and maximum
record lengths in numbers of bytes regardless of the USAGE of the data items in
the record.
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 (format-2 RECORD clause).
Make integer-1 and integer-2 match the minimum length and the maximum
length in bytes 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.
168
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 level-01 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).
RELATED TASKS
“Requesting fixed-length format” on page 167
“Requesting spanned format” on page 170
“Requesting undefined format” on page 172
“Establishing record formats” on page 166
RELATED REFERENCES
“FILE SECTION entries” on page 13
“Layout of format-V records”
Enterprise COBOL Migration Guide (Moving from the
VS COBOL II run time)
Layout of format-V records:
Format-V QSAM records have control fields that precede 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. However, you must not include these 4
bytes in the description of the record and record length.
Block Size
QSAM Logical Record
Data Record
(Level -01 Record)
4
bytes
LL BB
'CC'
CC
4
bytes
ll
bb
'cc'
Variable
bytes
Data
Variable
4
bytes bytes
ll
bb
Data
'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.
Chapter 9. Processing QSAM files
169
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 the description of the logical record in the DATA
DIVISION of your program. COBOL allocates input and output buffers that are
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, the records will be moved without the control bytes.
Files in the z/OS UNIX file system are never blocked.
RELATED CONCEPTS
“Logical records” on page 166
RELATED TASKS
“Requesting variable-length format” on page 168
RELATED REFERENCES
“Layout of format-F records” on page 168
“Layout of format-S records” on page 172
“Layout of format-U records” on page 173
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.
About this task
You can code RECORDING MODE S for spanned records in QSAM files that are
assigned to magnetic tape or to direct access devices. Do not request spanned
records for files in the z/OS UNIX file system. You can omit the RECORDING MODE
clause. The compiler determines the recording mode to be S if the maximum
record length (in bytes) 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 as are used for format V. The length is based on
your usage of the RECORD clause.
When creating files that contain 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 32,760 bytes in length.
When retrieving files that have format-S records, a 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:
170
Enterprise COBOL for z/OS, V5.1 Programming Guide
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: When you specify a READ INTO statement for a
format-S file, the compiler generates a MOVE statement that uses the size of the
record that it just read for that file. If the record just read does not correspond to
the level-01 record description, you might not get the result that you expect. All
other rules of the MOVE statement apply.
RELATED CONCEPTS
“Logical records” on page 166
“Spanned blocked and unblocked files”
RELATED TASKS
“Requesting fixed-length format” on page 167
“Requesting variable-length format” on page 168
“Requesting undefined format” on page 172
“Establishing record formats” on page 166
RELATED REFERENCES
“FILE SECTION entries” on page 13
“Layout of format-S records” on page 172
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. A spanned unblocked file is made
up of physical blocks, each containing one logical record or one segment of a
logical record.
In a spanned blocked file, a logical record can be either fixed or variable in length,
and its 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.
In a spanned unblocked file, 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 166
RELATED TASKS
“Requesting spanned format” on page 170
Chapter 9. Processing QSAM files
171
Layout of format-S records:
Spanned records are preceded by control fields, as explained below.
4 bytes
LL BB
BDF
4 bytes
ll
bb
Variable bytes
Data Record or Segment
SDF
Each block is preceded by a 4-byte block descriptor field ('BDF' in the image
above). There is only one block descriptor field at the beginning of each physical
block.
Each segment of a record in a block is preceded by a 4-byte segment descriptor
field ('SDF' in the image) even if the segment is the entire record. 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, and the fields are not
available for you to use in your COBOL program.
RELATED TASKS
“Requesting spanned format” on page 170
RELATED REFERENCES
“Layout of format-F records” on page 168
“Layout of format-V records” on page 169
“Layout of format-U records” on page 173
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.
About this task
When you use format-U files, each block of storage is one logical record. A read of
a format-U file returns the entire block as a record. A write to a format-U file
writes a record out as a block. The compiler determines the recording mode to be
U only if you code RECORDING MODE U.
It is recommended that you not use format U to update or extend a file that was
written with a different record format. If you use format U to update a file that
was written with a different format, the RECFM value in the data-set label could be
changed or the data set could contain records written in different formats.
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 (format-1 RECORD clause), the record
length is the integer value regardless of the lengths of the level-01 record
description entries associated with the file. The integer size indicates the number
of bytes in a record regardless of the USAGE of its data items.
v If you use the RECORD IS VARYING clause (format-3 RECORD clause), 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
172
Enterprise COBOL for z/OS, V5.1 Programming Guide
lengths of the level-01 record description entries associated with the file. The
integer sizes indicate the minimum and maximum record lengths in numbers of
bytes regardless of the USAGE of the data items in the record.
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 (format-2 RECORD
clause), with integer-1 and integer-2 matching the minimum length and the
maximum length in bytes 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 compiler generates a MOVE statement that uses the size of the
record that it just read for that file. If the record just read does not correspond to
the level-01 record description, you might not get the result that you expect. All
other rules of the MOVE statement apply.
RELATED TASKS
“Requesting fixed-length format” on page 167
“Requesting variable-length format” on page 168
“Requesting spanned format” on page 170
“Establishing record formats” on page 166
RELATED REFERENCES
“FILE SECTION entries” on page 13
“Layout of format-U records”
Layout of format-U records:
With format-U, 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 166
RELATED TASKS
“Requesting undefined format” on page 172
RELATED REFERENCES
“Layout of format-F records” on page 168
“Layout of format-V records” on page 169
“Layout of format-S records” on page 172
Setting block sizes
In COBOL, you establish the size of a physical record by using the BLOCK CONTAINS
clause. If you omit this clause, the compiler assumes that the records are not
blocked.
Chapter 9. Processing QSAM files
173
About this task
Blocking QSAM files on tape and disk can enhance processing speed and minimize
storage requirements. You can block files in the z/OS UNIX file system, 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, the size must not
be greater than the maximum block size for the device. If you specify the
CHARACTERS phrase of the BLOCK CONTAINS clause, size must indicate the number of
bytes in a record regardless of the USAGE of the data items in the record. The block
size that is 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
during one of the following actions:
v Reading a block of records of fewer than 12 bytes
v Writing a block of records of fewer than 18 bytes
Larger blocks generally give you better performance. Blocks of only a few kilobytes
are particularly inefficient; you should choose a block size of at least tens of
kilobytes. If you specify record blocking and omit the block size, the system will
pick a block size that is optimal for device utilization and for data transfer speed.
Letting z/OS determine block size: To maximize performance, do not explicitly set
the block size for a blocked file in your COBOL source program. For new blocked
data sets, it is simpler to allow z/OS to supply a system-determined block size. To
use this feature, follow these guidelines:
v Code BLOCK CONTAINS 0 in your source program or compile with the BLOCK0
option. For details about BLOCK0, see “BLOCK0” on page 319.
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, your
program will be most flexible if you follow these guidelines:
v Code BLOCK CONTAINS 0 in your source program.
v Code a BLKSIZE value in the ddname definition (the JCL DD statement).
For extended-format data sets on z/OS, z/OS 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. z/OS DFSMS allocates the space used to
read in the block suffix. However, when you calculate how many blocks of an
extended-format 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 that is larger than 32760 directly in the BLOCK CONTAINS
clause or indirectly with the use of BLOCK CONTAINS n RECORDS, the OPEN of the data
set fails with file status code 90 unless you define the data set to be on tape.
For existing blocked data sets, it is simplest to:
v Code BLOCK CONTAINS 0 in your source program.
v Not code a BLKSIZE value in the ddname definition.
174
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 the large block interface (LBI) for large block sizes. When the LBI 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 a system that 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 runtime message is issued.
To limit a system-determined block size to 32760, do not specify BLKSIZE anywhere,
and set one of the following items to 32760:
v The BLKSZLIM keyword on the DD statement for the data set
v BLKSZLIM for the data class by using the BLKSZLIM keyword (must be set by your
systems programmer)
v A block-size limit for the system in the DEVSUPxx member of SYS1.PARMLIB
by using the keyword TAPEBLKSZLIM (must be set by your systems programmer)
The block-size limit is the first nonzero value that the compiler finds by checking
these items.
If no BLKSIZE or BLKSZLIM value is available from any source, the system limits
BLKSIZE to 32760. You can then enable block sizes larger than 32760 in one of two
ways:
v Specify a BLKSZLIM value greater than 32760 in the DD statement for the file and
use BLOCK CONTAINS 0 in your COBOL source.
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 z/OS, 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.
Chapter 9. Processing QSAM files
175
RELATED TASKS
“Defining QSAM files and records in COBOL” on page 165
z/OS DFSMS: Using Data Sets
RELATED REFERENCES
“FILE SECTION entries” on page 13
“BLOCK0” on page 319
BLOCK CONTAINS clause (Enterprise COBOL Language Reference)
Coding input and output statements for QSAM files
You can code the following input and output statements to process a QSAM file or
a byte-stream file in the z/OS UNIX file system using QSAM: OPEN, READ, WRITE,
REWRITE, and CLOSE.
About this task
OPEN
Initiates the processing of files. 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 z/OS UNIX files as I-O; a file status of 37 results 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 z/OS UNIX file system
using REWRITE.
CLOSE
Releases the connection between the file and your program.
RELATED TASKS
“Opening QSAM files”
“Dynamically creating QSAM files” on page 177
“Adding records to QSAM files” on page 178
“Updating QSAM files” on page 178
“Writing QSAM files to a printer or spooled data set” on page 178
“Closing QSAM files” on page 179
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
READ statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise COBOL Language Reference)
REWRITE statement (Enterprise COBOL Language Reference)
CLOSE statement (Enterprise COBOL Language Reference)
File status key (Enterprise COBOL Language Reference)
Opening QSAM files
Before a program can use any READ, WRITE, or REWRITE statements to process records
in a file, it must first open the file by using an OPEN statement.
176
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
An OPEN statement works if both of the following conditions 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
the file match the attributes coded for that file in the SELECT clause and FD entry.
Mismatches in the file-organization attributes, code set, maximum record size, or
record format (fixed or variable) result in file status code 39, and the failure of
the OPEN statement. Mismatches in maximum record size and record format are
not errors when opening files in the z/OS UNIX file system.
For fixed-length QSAM files, if you code RECORD CONTAINS 0 in the FD entry, 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.
The file is positioned at the end, and READ statements read the data records in
reverse order, starting with the last record. The REVERSED option is supported only
for files that have fixed-length records.
RELATED TASKS
“Dynamically creating QSAM files”
“Ensuring that file attributes match your program” on page 184
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
Dynamically creating QSAM files
Sometimes a QSAM file is unavailable on the operating system, but a COBOL
program specifies that the file be created. Under certain circumstances, the file is
created for you dynamically.
About this task
A QSAM file is considered to be available on z/OS when it has been identified to
the operating system using a valid DD statement, an export command for an
environment variable, or a TSO ALLOCATE command. Otherwise the file is
unavailable.
Note that a DD statement with a misspelled ddname is equivalent to a missing DD
statement, and an environment variable with a value that is not valid is equivalent
to an unset variable.
The QSAM file is implicitly created if you use the runtime option CBLQDA and one
of the following circumstances exists:
v An optional file is being opened as EXTEND or I-O.
Optional files are files that are not necessarily available each time the program is
run. You define a file that is being opened in INPUT, I-O, or EXTEND mode as
optional by coding the SELECT OPTIONAL clause in the FILE-CONTROL paragraph.
v The file is being opened for OUTPUT, regardless of the OPTIONAL phrase.
Chapter 9. Processing QSAM files
177
The file is allocated with the system default attributes established at your
installation and the attributes coded in the SELECT clause and FD entry in your
program.
Do not confuse this implicit allocation mechanism with the explicit dynamic
allocation of files by means of environment variables. Explicit dynamic allocation
requires that a valid environment variable be set. CBLQDA support is used only
when the QSAM file is unavailable as defined above, which includes no valid
environment variable being set.
Under z/OS, files created using the CBLQDA option are temporary data sets and do
not exist after the program has run.
RELATED TASKS
“Opening QSAM files” on page 176
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.
About this task
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 (Enterprise COBOL Language Reference)
WRITE statement (Enterprise COBOL Language Reference)
Updating QSAM files
You can update QSAM files only if they reside on direct access storage devices.
You cannot update files in the z/OS UNIX file system.
About this task
Replace an existing record with another record of the same length by doing these
steps:
Procedure
1. Open the file as I-O.
2. Use REWRITE to update an existing record. (The last file processing statement
before REWRITE must have been a successful READ statement.)
Results
You cannot open as I-O an extended format data set that you allocate in
compressed format.
RELATED REFERENCES
REWRITE statement (Enterprise 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.
178
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
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 phrase,
COBOL first calculates the sum of LINAGE-COUNTER plus nn. Subsequent actions
depend on the size of nn. The END-OF-PAGE imperative phrase 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 phrase is performed.
AT END-OF-PAGE or NOT AT END-OF-PAGE imperative phrases 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, and all conditional phrases are
omitted.
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.
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 phrase from
a WRITE statement, the effect is as if you had coded:
AFTER ADVANCING 1 LINE
RELATED REFERENCES
WRITE statement (Enterprise COBOL Language Reference)
Closing QSAM files
Use the CLOSE statement to disconnect your program from a QSAM file. If you try
to close a file that is already closed, you will get a logic error.
About this task
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 COBOL programs in the run unit.
v If the run unit ends abnormally and the TRAP(ON) runtime option is in effect, the
run time closes all open files that are defined in any COBOL programs in the
run unit.
v When Language Environment condition handling has 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 COBOL programs in the
run unit that might be called again and reentered.
Chapter 9. Processing QSAM files
179
You can change the location 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 language constructs such as
a C longjmp.
v When you use CANCEL for a COBOL subprogram, the run time closes any open
nonexternal files that are defined in that program.
v When a COBOL subprogram with the INITIAL attribute returns control, the run
time closes any open nonexternal files that are defined in that program.
v When a thread of a multithreaded application ends, both external and
nonexternal files that you opened from within that same thread are closed.
File status key data items in the DATA DIVISION are set when these implicit CLOSE
operations are performed, but your EXCEPTION/ERROR declarative is not invoked.
|
|
Errors: If you open a QSAM file in a multithreaded application, you must close it
from the same thread of execution from which the file was opened. Attempting to
close the file from a different thread results in a close failure with file-status
condition 90.
RELATED REFERENCES
CLOSE statement (Enterprise COBOL Language Reference)
Handling errors in QSAM files
When an input statement or output statement fails, COBOL does not take
corrective action for you. You choose whether your program should continue
running after a less-than-severe input or output error occurs.
About this task
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
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 runtime 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 247
180
Enterprise COBOL for z/OS, V5.1 Programming Guide
Working with QSAM files
To work with QSAM files in a COBOL program, you define and allocate the files,
retrieve them, and ensure that their file attributes match those in the program. You
can also use striped extended-format QSAM data sets to help improve
performance.
About this task
RELATED TASKS
“Defining and allocating QSAM files”
“Retrieving QSAM files” on page 183
“Ensuring that file attributes match your program” on page 184
“Using striped extended-format QSAM data sets” on page 187
RELATED REFERENCES
“Allocation of buffers for QSAM files” on page 187
Defining and allocating QSAM files
You can define a QSAM file or a byte-stream file in the z/OS UNIX file system by
using either a DD statement or an environment variable. Allocation of these files
follows the general rules for the allocation of COBOL files.
About this task
When you use an environment variable, the name must be in uppercase. Specify
the MVS data set in one of these ways:
v DSN(data-set-name)
v DSN(data-set-name(member-name))
data-set-name must be fully qualified and cannot be a temporary data set (that is, it
must not start with &).
Restriction: You cannot create a PDS or PDSE by using an environment variable.
You can optionally specify the following attributes in any order after DSN:
v A disposition value, one of: NEW, OLD, SHR, or MOD
v
v
v
v
v
TRACKS or CYL
SPACE(nnn,mmm)
VOL(volume-serial)
UNIT(type)
KEEP, DELETE, CATALOG, or UNCATALOG
v STORCLAS(storage-class)
v MGMTCLAS(management-class)
v DATACLAS(data-class)
You can use either an environment variable or a DD definition to define a file in the
z/OS UNIX file system. To do so, define one of the following items with a name
that matches the external name in the 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 /)
Chapter 9. Processing QSAM files
181
For compatibility with releases of COBOL before COBOL for OS/390 & VM
Version 2 Release 2, you can also specify FILEDATA=TEXT when using a DD allocation
for z/OS UNIX files, but this use is not recommended. To process text files in the
z/OS UNIX file system, use LINE SEQUENTIAL organization. If you do use QSAM to
process text files in the z/OS UNIX file system, you cannot use environment
variables to define the files.
When you define a QSAM file, use the parameters as shown below.
Table 20. QSAM file allocation
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. (Only for
direct-access storage devices.)
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 that you want to add.
DCB subparameters
n/a
Some of the information about the QSAM file must always be coded in the
FILE-CONTROL paragraph, 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 by 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 items:
v Block size (BLKSIZE=), if BLOCK CONTAINS 0 RECORDS was coded at compile time
(recommended)
v Options to be executed if an error occurs in reading or writing a record
v TRACK OVERFLOW or standard blocks
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.
182
Enterprise COBOL for z/OS, V5.1 Programming Guide
“Example: setting and accessing environment variables” on page 454
RELATED TASKS
“Setting block sizes” on page 173
“Defining QSAM files and records in COBOL” on page 165
“Allocating files” on page 163
RELATED REFERENCES
“Parameters for creating QSAM files”
MVS Program Management: User's Guide and Reference
Parameters for creating QSAM files
The following DD statement parameters are frequently used to create QSAM files.
DSNAME=
DSN=
UNIT=
dataset-name
dataset-name(member-name)
&&name
&&name(member-name)
( name[,unitcount] )
VOLUME= ( [PRIVATE] [,RETAIN] [,vol-sequence-num] [,volume-count] ...
VOL=
... ,SER=(volume-serial[,volume-serial]...)
(
,REF= dsname
*.ddname
*.stepname.ddname
*.stepname.procstep.ddname
SPACE= ( TRK
,(primary-quantity[,secondary-quantity][,directory-quantity]))
CYL
average-record-length
LABEL= ( [Data-set-sequence-number,] NL
SL
SUL
DISP=
( NEW
MOD
,DELETE
,KEEP
,PASS
,CATLG
,DELETE
,KEEP
,CATLG
DCB=
( subparameter-list )
,EXPDT=
yyddd
yyyy/ddd
,RETPD=xxxx
(
)
RELATED TASKS
“Defining and allocating QSAM files” on page 181
Retrieving QSAM files
You retrieve QSAM files, cataloged or not, by using job control statements or
environment variables.
About this task
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
the DISP parameter. When you use an environment variable, this is the DSN
parameter and one of the parameters OLD, SHR, or MOD.
Chapter 9. Processing QSAM files
183
Noncataloged files
Some information is stored in the file label, but you must code the unit
and volume information, and 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 183
Ensuring that file attributes match your program
When the fixed file attributes in the DD statement or the data-set label and the
attributes that are coded for that file in the SELECT clause and FD entry are not
consistent, an OPEN statement in your program might not work.
About this task
Mismatches in the attributes for file organization, record format (fixed or variable),
record length, or the code set result in file status code 39 and the failure of the
OPEN statement. An exception exists for files in the z/OS UNIX file system:
mismatches in record format and record length do not cause an error.
To prevent common file status 39 problems, follow the guidelines for processing
existing or new files.
184
Enterprise COBOL for z/OS, V5.1 Programming Guide
If you have not made a file available with a DD statement or a TSO ALLOCATE
command, and your COBOL program specifies that the file be created, Enterprise
COBOL dynamically allocates the file. When the file is opened, the file attributes
that are coded in your program are used. You do not have to worry about file
attribute conflicts.
Remember that information in the JCL or environment variable overrides
information in the data-set label.
RELATED TASKS
“Processing existing files”
“Processing new files” on page 186
“Opening QSAM files” on page 176
RELATED REFERENCES
“FILE SECTION entries” on page 13
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
the guidelines below to define the maximum record length.
About this task
Table 21. Maximum record length of QSAM files
For this format:
Specify this:
V or S
Exactly 4 bytes less than the length attribute of the data set
F
Same value as the length attribute of the data set
U
Same value as the length attribute of the data set
The easiest way to define variable-length (format-V) records in a program is to use
the RECORD IS VARYING FROM integer-1 TO integer-2 clause in the FD entry and set an
appropriate value for integer-2. Express the integer sizes in bytes regardless of the
underlying USAGE of the data items in the record. For example, assume that you
determine that the length attribute of the data set is 104 bytes (LRECL=104).
Remembering that the maximum record length is determined from the RECORD IS
VARYING clause 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).
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).
Chapter 9. Processing QSAM files
185
To define fixed-length records in your program, either code 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. If you intend to use the same program to process different
files at run time, and those files have differing fixed lengths, avoid record-length
conflicts by coding RECORD CONTAINS 0.
If the existing file is an ASCII data set (DCB=(OPTCD=Q)), you must use the CODE-SET
clause in the FD entry for the file.
RELATED TASKS
“Processing new files”
“Requesting fixed-length format” on page 167
“Requesting variable-length format” on page 168
“Requesting undefined format” on page 172
“Opening QSAM files” on page 176
RELATED REFERENCES
“FILE SECTION entries” on page 13
Processing new files
If your COBOL program writes records to a new file that will be made available
before the program runs, ensure that the file attributes in the DD statement, the
environment variable, or the allocation do not conflict with the attributes in the
program.
About this task
Usually you need to code only a minimum of parameters when predefining files.
But if you need to explicitly set a length attribute for the data set (for example, you
are using an ISPF allocation panel, or your DD statement is for a batch job in which
the program uses RECORD CONTAINS 0), follow these guidelines:
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 the 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 language used in your program. In such a
case, take the added byte into account when coding the LRECL value.
For example, if your program contains the following code for a file that has
variable-length records, the LRECL value in the DD statement or allocation should be
54.
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).
RELATED TASKS
“Processing existing files” on page 185
“Requesting fixed-length format” on page 167
“Requesting variable-length format” on page 168
“Requesting undefined format” on page 172
186
Enterprise COBOL for z/OS, V5.1 Programming Guide
“Opening QSAM files” on page 176
“Dynamically creating QSAM files” on page 177
RELATED REFERENCES
“FILE SECTION entries” on page 13
Using striped extended-format QSAM data sets
Striped extended-format QSAM data sets can benefit applications that process files
that have large amounts of data or in which the time needed for I/O operations
significantly affects overall performance.
About this task
A striped extended-format QSAM data set is an extended-format QSAM data set that
is spread over multiple volumes, thus allowing parallel data access.
For you to gain the maximum benefit from using QSAM striped data sets, z/OS
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.
v Omit the RESERVE clause in the FILE-CONTROL entry for the file. Doing so lets
z/OS DFSMS 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) runtime option if the file is an EXTERNAL file with format-F,
format-V, or format-U records.
Note that all striped data sets are extended-format data sets, but not all
extended-format data sets are striped.
RELATED TASKS
z/OS DFSMS: Using Data Sets
Allocation of buffers for QSAM files
z/OS DFSMS automatically allocates buffers for storing input and output for a
QSAM file above or below the 16 MB line as appropriate for the file.
Most QSAM files have buffers allocated above the 16 MB line. Exceptions are:
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) runtime option is specified. To specify the
ALL31(ON) runtime 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 ones:
– An EXTERNAL file (even if ALL31(ON) 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
Chapter 9. Processing QSAM files
187
RELATED CONCEPTS
“Storage and its addressability” on page 40
RELATED TASKS
“Using striped extended-format QSAM data sets” on page 187
Accessing z/OS UNIX files using QSAM
You can process byte-stream files in the z/OS UNIX file system as ORGANIZATION
SEQUENTIAL files using QSAM. To do this, specify as the assignment-name in the
ASSIGN clause either a ddname or an environment-variable name.
About this task
ddname
A DD allocation that identifies the file with the keywords PATH= and
FILEDATA=BINARY
Environment-variable name
An environment variable that holds the runtime value of the z/OS UNIX
file system path for the file
Observe the following restrictions:
v Spanned record format is not supported.
v OPEN I-O and REWRITE are not supported. If you attempt one of these operations,
one of the following file-status conditions results:
– 37 from OPEN I-O
– 47 from REWRITE (because you could not have successfully opened the file as
I-O)
Usage notes
v File status 39 (fixed file attribute conflict) is not enforced for either of the
following types of conflicts:
– Record-length conflict
– Record-type conflict (fixed as opposed to variable)
v A READ returns the number of bytes of the maximum logical record size for the
file except for the last record, which might be shorter.
For example, suppose that a file definition has level-01 record descriptions of 3,
5, and 10 bytes long, and you write the following three records: 'abc', 'defgh',
and 'ijklmnopqr', in that order. The first READ of this file returns 'abcdefghij', the
second READ returns 'klmnopqr ', and the third READ results in the AT END
condition.
For compatibility with releases of IBM COBOL before COBOL for OS/390 & VM
Version 2 Release 2, you can also specify FILEDATA=TEXT when using a DD allocation
for z/OS UNIX files, but this use is not recommended. To process text files in the
z/OS UNIX file system, use LINE SEQUENTIAL organization. If you use QSAM to
process text files in the z/OS UNIX file system, you cannot use environment
variables to define the files.
RELATED TASKS
“Allocating files” on page 163
“Defining and allocating QSAM files” on page 181
z/OS DFSMS: Using Data Sets (Using HFS data sets)
188
Enterprise COBOL for z/OS, V5.1 Programming Guide
Processing QSAM ASCII files on tape
If your program processes a QSAM ASCII file, you must request the ASCII
alphabet, define the record formats, and define the ddname (with JCL).
About this task
In addition, if your program processes signed numeric data items from ASCII files,
define the numeric data as zoned decimal items with separate signs, that is, as
USAGE DISPLAY and with the SEPARATE phrase of the SIGN clause.
The CODEPAGE compiler option has no effect on the code page used for conversions
between ASCII and EBCDIC for ASCII tape support. For information about how
CCSIDs used for the ASCII tape support are selected and what the default CCSIDs
are, see the z/OS DFSMS documentation.
Requesting the ASCII alphabet: In the SPECIAL-NAMES paragraph, code STANDARD-1
for ASCII:
ALPHABET-NAME IS STANDARD-1
In the FD entry 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
v
v
Fixed length (format F)
Undefined (format U)
Variable length (format V)
If you use 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 z/OS, 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]
AL
American National Standard (ANS) labels
AUL
ANS and user labels
NL
No labels
OPTCD=Q
Chapter 9. Processing QSAM files
189
Q
This value is required for ASCII files and is the default if the file is
created using Enterprise COBOL.
RELATED REFERENCES
z/OS DFSMS: Using Data Sets (Character data conversion)
190
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 10. Processing VSAM files
Virtual storage access method (VSAM) is an access method for files on
direct-access storage devices. With VSAM you can load files, retrieve records from
files, update files, and add, replace, and delete records in files.
About this task
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 following table shows how VSAM terms differ from COBOL terms and other
terms that you might be familiar with.
Table 22. Comparison of VSAM, COBOL, and non-VSAM terminology
VSAM term
COBOL term
Similar non-VSAM term
Data set
File
Data set
Entry-sequenced data set (ESDS)
Sequential file
QSAM data set
Key-sequenced data set (KSDS)
Indexed file
ISAM data set
Relative-record data set (RRDS)
Relative file
BDAM data set
Control interval
Block
Control interval size (CISZ)
Block size
Buffers (BUFNI/BUFND)
BUFNO
Access method control block (ACB)
Data control block (DCB)
Cluster (CL)
Data set
Cluster definition
Data-set allocation
AMP parameter of JCL DD statement
DCB parameter of JCL DD statement
Record size
Record length
The term file in this VSAM documentation refers to either a COBOL file or a
VSAM data set.
If you have complex requirements or frequently use VSAM, se the VSAM
publications for your operating system.
RELATED CONCEPTS
“VSAM files” on page 192
RELATED TASKS
“Defining VSAM file organization and records” on page 193
“Coding input and output statements for VSAM files” on page 199
© Copyright IBM Corp. 1991, 2013
191
“Handling errors in VSAM files” on page 208
“Protecting VSAM files with a password” on page 209
“Working with VSAM data sets under z/OS and z/OS UNIX” on page 210
“Improving VSAM performance” on page 217
RELATED REFERENCES
z/OS DFSMS: Using Data Sets
z/OS DFSMS Macro Instructions for Data Sets
z/OS DFSMS: Access Method Services for Catalogs
“Allocation of record areas for VSAM files” on page 216
|
|
VSAM files
The physical organization of VSAM data sets differs considerably from the
organizations used by other access methods.
VSAM data sets are held in control intervals (CI) and control areas (CA). The size
of the CI and CA 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, which 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 that contains 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.
192
Enterprise COBOL for z/OS, V5.1 Programming Guide
Throughout this information, 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 characteristics of the different types of VSAM
data sets.
Table 23. Comparison of VSAM data-set types
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 cannot change.
(RBA) and relative
record number (RRN)
of a record
RBA can change.
RRN cannot change.
Space for adding
records
Uses distributed free space
for inserting records and
changing their lengths in
place
For fixed-length RRDS, uses
empty slots in the data set
Characteristic
Uses space at the end of
the data set
For variable-length RRDS, uses
distributed free space and
changes the lengths of added
records in place
Space from deleting
records
You cannot delete a record,
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 unless it has
Can be reused
an alternate index, is
associated with key ranges, or
exceeds 123 extents per
volume
RELATED TASKS
“Specifying sequential organization for VSAM files” on page 194
“Specifying indexed organization for VSAM files” on page 195
“Specifying relative organization for VSAM files” on page 196
“Defining VSAM files” on page 210
Defining VSAM file organization and records
Use an entry in the FILE-CONTROL paragraph in the ENVIRONMENT DIVISION to define
the file organization and access modes for the VSAM files in your COBOL
program.
Chapter 10. Processing VSAM files
193
About this task
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 by using the RECORD clause.
Important: You can process VSAM data sets in Enterprise COBOL programs only
after you define them by using access method services.
Table 24. VSAM file organization, access mode, and record format
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” on page 195
“Specifying relative organization for VSAM files” on page 196
“Specifying access modes for VSAM files” on page 197
“Defining record lengths for VSAM files” on page 198
“Using file status keys” on page 251
“Using VSAM status codes (VSAM files only)” on page 253
“Defining VSAM files” on page 210
Specifying sequential organization for VSAM files
Identify VSAM ESDS files in a COBOL program with the ORGANIZATION IS
SEQUENTIAL clause. You can access (read or write) records in sequential files only
sequentially.
About this task
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 192
194
Enterprise COBOL for z/OS, V5.1 Programming Guide
Specifying indexed organization for VSAM files
Identify a VSAM KSDS file in a COBOL program by using the ORGANIZATION IS
INDEXED clause. Code a prime key for the record by using the RECORD KEY clause.
You can also use alternate keys and an alternate index.
About this task
RECORD KEY IS data-name
In the example above, data-name is the name of the prime key field as you define it
in the record description entry in the DATA DIVISION. The prime key data item can
be class alphabetic, alphanumeric, DBCS, numeric, or national. If it has USAGE
NATIONAL, the prime key can be category national, or can be a national-edited,
numeric-edited, national decimal, or national floating-point data item. The collation
of record keys is based on the binary value of the keys regardless of the class or
category of the keys.
The following example shows the statements for a VSAM indexed file (KSDS) that
is accessed dynamically. In addition to the primary key, COMMUTER-NO, an alternate
key, LOCATION-NO, is specified:
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.
RELATED CONCEPTS
“VSAM files” on page 192
RELATED TASKS
“Using alternate keys”
“Using an alternate index” on page 196
RELATED REFERENCES
RECORD KEY clause (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Using alternate keys
In addition to the primary key, you can code one or more alternate keys for a
VSAM KSDS file. By using alternate keys, you can access an indexed file to read
records in some sequence other than the prime-key sequence.
About this task
Alternate keys do not need to be unique. More than one record could be accessed
if alternate keys are coded to allow duplicates. For example, you could access the
file through employee department rather than through employee number.
You define the alternate key in your COBOL program with the ALTERNATE RECORD
KEY clause:
ALTERNATE RECORD KEY IS data-name
In the example above, data-name is the name of the alternate key field as you
define it in the record description entry in the DATA DIVISION. Alternate key data
items, like prime key data items, can be class alphabetic, alphanumeric, DBCS,
Chapter 10. Processing VSAM files
195
numeric, or national. The collation of alternate keys is based on the binary value of
the keys regardless of the class or category of the keys.
Using an alternate index
To use an alternate index for a VSAM KSDS file, you need to define a data set
called the alternate index (AIX) by using access method services.
About this task
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 TASKS
“Creating alternate indexes” on page 211
Specifying relative organization for VSAM files
Identify VSAM RRDS files in a COBOL program by using the ORGANIZATION IS
RELATIVE clause. Use the RELATIVE KEY IS clause to associate each logical record
with its relative record number.
About this task
The following example shows a relative-record data set (RRDS) that is accessed
randomly by the value in the relative key:
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 is the
division/remainder technique. With this technique, 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 is a valid relative record number.
Alternate indexes are not supported for VSAM RRDS.
RELATED CONCEPTS
“VSAM files” on page 192
“Fixed-length and variable-length RRDS”
RELATED TASKS
“Using variable-length RRDS” on page 197
“Defining VSAM files” on page 210
Fixed-length and variable-length RRDS
In an RRDS that has fixed-length records, each record occupies one slot. You store
and retrieve records according to the relative record number of the slot. A
variable-length RRDS does not have slots; instead, the free space that you define
allows for more efficient record insertions.
196
Enterprise COBOL for z/OS, V5.1 Programming Guide
When you load an RRDS that has fixed-length records, you have the option of
skipping over slots and leaving them empty. When you load an RRDS that has
variable-length records, you can skip over relative record numbers.
Using variable-length RRDS
To use relative-record data sets (RRDS) that have variable-length records, you must
use VSAM variable-length RRDS support.
About this task
Do these steps:
Procedure
1.
2.
3.
4.
Define the file with the ORGANIZATION IS RELATIVE clause.
Use FD entries to describe the records with variable-length sizes.
Use the NOSIMVRD runtime option.
Define the VSAM file through access-method services as an RRDS.
Results
RELATED TASKS
“Defining VSAM files” on page 210
RELATED REFERENCES
z/OS DFSMS: Access Method Services for Catalogs
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.
About this task
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” on page 198
RELATED TASKS
“Reading records from a VSAM file” on page 205
Chapter 10. Processing VSAM files
197
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.
If your program processes those employees who earn between $15.00 and $20.00
per hour and those who earn $25.00 per hour and above, using dynamic access of
VSAM files, the program would:
1. Retrieve the first record randomly (with a random-retrieval READ) based on the
key of 1500.
2. Read sequentially (using READ NEXT) until the salary field exceeds 2000.
3. Retrieve the next record randomly, based on a key of 2500.
4. Read sequentially until the end of the file.
RELATED TASKS
“Reading records from a VSAM file” on page 205
Defining record lengths for VSAM files
You can define VSAM records to be fixed or variable in length. COBOL determines
the record format from the RECORD clause and the record descriptions that are
associated with the FD entry for a file.
About this task
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.
RELATED TASKS
“Defining fixed-length records”
“Defining variable-length records” on page 199
Enterprise COBOL Migration Guide
RELATED REFERENCES
“FILE SECTION entries” on page 13
Defining fixed-length records
To define VSAM records as fixed length, use one of these coding options.
About this task
Table 25. Definition of VSAM fixed-length records
RECORD clause
Code RECORD CONTAINS
integer.
198
Clause
format
1
Enterprise COBOL for z/OS, V5.1 Programming Guide
Record length
Comments
Fixed in size with a
length of integer-3 bytes
The lengths of the
level-01 record
description entries
associated with the file
do not matter.
Table 25. Definition of VSAM fixed-length records (continued)
RECORD clause
Clause
format
Omit the RECORD clause,
but code all level-01
records that are
associated with the file as
the same size; and code
none with an OCCURS
DEPENDING ON clause.
Record length
Comments
The fixed size that you
coded
RELATED REFERENCES
RECORD clause (Enterprise COBOL Language Reference)
Defining variable-length records
To define VSAM records as variable length, use one of these coding options.
About this task
Table 26. Definition of VSAM variable-length records
RECORD clause
Clause
format
Maximum record length
Comments
Code RECORD IS VARYING 3
FROM integer-6 TO integer-7.
integer-7 bytes
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-4 TO integer-5.
2
integer-5 bytes
Omit the RECORD clause,
but code multiple level-01
records that are
associated with the file
and are of different sizes
or contain an OCCURS
DEPENDING ON clause.
The minimum record
length is integer-4 bytes.
Size of the largest level-01 The compiler determines
record description entry
the maximum record
associated with the file
length.
When you specify a READ INTO statement for a format-V file, the record size that is
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 REFERENCES
RECORD clause (Enterprise COBOL Language Reference)
Coding input and output statements for VSAM files
Use the COBOL statements shown below to process VSAM files.
Chapter 10. Processing VSAM files
199
About this task
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 of statements and open
modes for sequential files (ESDS). The X indicates that you can use a statement
with the open mode shown at the top of the column.
Table 27. I/O statements for VSAM sequential files
Access mode
COBOL
statement
Sequential
OPEN
OPEN INPUT
OPEN OUTPUT
OPEN I-O
OPEN EXTEND
X
X
X
X
X
WRITE
X
START
READ
X
X
X
REWRITE
DELETE
CLOSE
X
X
X
X
The following table shows the possible combinations of statements and open
modes that you can use with indexed (KSDS) files and relative (RRDS) files. The X
indicates that you can use the statement with the open mode shown at the top of
the column.
200
Enterprise COBOL for z/OS, V5.1 Programming Guide
Table 28. I/O statements for VSAM relative and indexed files
Access mode
COBOL
statement
Sequential
OPEN
OPEN INPUT
OPEN OUTPUT
OPEN I-O
OPEN EXTEND
X
X
X
X
X
WRITE
Random
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 that 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 202
“Reading records from a VSAM file” on page 205
“Updating records in a VSAM file” on page 205
“Adding records to a VSAM file” on page 206
“Replacing records in a VSAM file” on page 207
“Deleting records from a VSAM file” on page 207
“Closing VSAM files” on page 207
RELATED REFERENCES
File status key (Enterprise COBOL Language Reference)
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 in your program. It is
set by successful OPEN, START, READ, and READ NEXT statements.
Chapter 10. Processing VSAM files
201
Subsequent READ or READ NEXT requests use the established file position indicator
location and update it.
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 205
Opening a file (ESDS, KSDS, or RRDS)
Before you can use WRITE, START, READ, REWRITE, or DELETE statements to process
records in a file, you must first open the file with an OPEN statement.
About this task
Whether a file is available or optional affects OPEN processing, file creation, and the
resulting file status key. For example, if you open in EXTEND, I-O, or INPUT mode a
nonexistent non-OPTIONAL file, the result is an OPEN error, and file status 35 is
returned. If the file is OPTIONAL, however, the same OPEN statement returns file
status 05, and, for open modes EXTEND and I-O, creates the file.
An OPEN operation works successfully only if you set fixed file attributes in the DD
statement or data-set label for a file, and specify consistent attributes for the file in
the SELECT clause and FD entries of your COBOL program. Mismatches in the
following items result in a file status key 39 and the failure of the OPEN statement:
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 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 204
RELATED REFERENCES
“Statements to load records into a VSAM file” on page 204
Opening an empty file
To open a file that has never contained records (an empty file), use a form of the
OPEN statement.
About this task
Depending on the type of file that you are opening, use one of the following
statements:
v OPEN OUTPUT for ESDS files.
202
Enterprise COBOL for z/OS, V5.1 Programming Guide
v OPEN OUTPUT or OPEN EXTEND for KSDS and RRDS files. (Either coding has the
same effect.) If you 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 available each time a program is run.
You can define files opened in INPUT, I-O, or OUTPUT mode as optional by defining
them with the SELECT OPTIONAL clause in the FILE-CONTROL paragraph.
Initially loading a file sequentially: Initially loading a file means writing records
into the file for the first time. Doing so is not the same as writing records into a
file from which all previous records have been deleted. To initially load a VSAM
file:
Procedure
1. Open the file.
2. Use sequential processing (ACCESS IS SEQUENTIAL). (Sequential processing is
faster than random or dynamic processing.)
3. Use WRITE to add a record to the file.
Results
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 effect 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 because it has 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.
When you are loading an extended-format VSAM data set, file status 30 will occur
for the OPEN if z/OS DFSMS system-managed buffering sets the buffering to local
shared resources (LSR). To successfully load the VSAM data set in this case, specify
ACCBIAS=USER in the DD AMP parameter for the VSAM data set to bypass
system-managed buffering.
Chapter 10. Processing VSAM files
203
Loading a VSAM data set with access method services: You can load or update a
VSAM data set by using the access method services REPRO command. Use REPRO
whenever possible.
RELATED TASKS
“Opening a loaded file (a file with records)”
RELATED REFERENCES
“Statements to load records into a VSAM file”
z/OS DFSMS: Access Method Services for Catalogs (REPRO)
Statements to load records into a VSAM file
Use the statements shown below to load records into a VSAM file.
Table 29. 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 202
“Updating records in a VSAM file” on page 205
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.
About this task
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 202
“Working with VSAM data sets under z/OS and z/OS UNIX” on page 210
RELATED REFERENCES
“Statements to load records into a VSAM file”
z/OS DFSMS: Access Method Services for Catalogs
204
Enterprise COBOL for z/OS, V5.1 Programming Guide
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.
About this task
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
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 201
RELATED TASKS
“Specifying access modes for VSAM files” on page 197
Updating records in a VSAM file
To update a VSAM file, use these PROCEDURE DIVISION statements.
Chapter 10. Processing VSAM files
205
About this task
Table 30. Statements to update records in a VSAM file
Access
method
ESDS
KSDS
RRDS
OPEN EXTEND
WRITE
CLOSE
OPEN EXTEND
WRITE
CLOSE
OPEN EXTEND
WRITE
CLOSE
or
or
or
OPEN I-O
READ
REWRITE
CLOSE
OPEN I-O
READ
REWRITE
DELETE
CLOSE
OPEN I-O
READ
REWRITE
DELETE
CLOSE
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
ACCESS IS
SEQUENTIAL
RELATED REFERENCES
“Statements to load records into a VSAM file” on page 204
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.
About this task
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.
206
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 a record in a VSAM file, use REWRITE on a file that you opened as I-O. If
the file was not opened as I-O, the record is not rewritten and the status key is set
to 49. Check the file status key after each REWRITE statement.
About this task
For sequential files, the length of the replacement record must be the same as the
length of the original record. For indexed files or variable-length relative files, you
can change the length of the record you replace.
To replace a record randomly or dynamically, you do not have to first READ the
record. Instead, locate the record you want to replace 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
To remove an existing record from an indexed or relative file, open the file I-O and
use the DELETE statement. You cannot use DELETE on a sequential file.
About this task
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 does not
have to 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 a 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.
About this task
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
programs in the run unit are closed.
Chapter 10. Processing VSAM files
207
v When the run unit ends abnormally, if the TRAP(ON) runtime option has been set,
all open files defined in any COBOL programs in the run unit are closed.
v When Language Environment condition handling has 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.
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 language constructs such as a C
longjmp statement.
v When you issue CANCEL for a COBOL subprogram, any open nonexternal files
defined in that program are closed.
v When a COBOL subprogram with the INITIAL attribute returns control, any
open nonexternal files defined in that program are closed.
v When a thread of a multithreaded application ends, both external and
nonexternal files that were opened from within that same thread are closed.
File status key data items in the DATA DIVISION are set when these implicit CLOSE
operations are performed, but your EXCEPTION/ERROR declarative is not invoked.
|
Errors: If you open a VSAM file in a multithreaded application, you must close it
from the same thread of execution. Attempting to close the file from a different
thread results in a close failure with file-status condition 90.
Handling errors in VSAM files
When an input or output statement operation fails, COBOL does not perform
corrective action for you.
About this task
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 if you 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 error.
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 status 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 each 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 runtime option
ABTERMENC(ABEND).
208
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED TASKS
“Handling errors in input and output operations” on page 247
“Using VSAM status codes (VSAM files only)” on page 253
RELATED REFERENCES
z/OS DFSMS Macro Instructions for Data Sets (VSAM macro return and
reason codes)
Protecting VSAM files with a password
Although the preferred security mechanism on a z/OS system is RACF®,
Enterprise COBOL also supports using explicit passwords on VSAM files to
prevent unauthorized access and update.
About this task
To use explicit passwords, code the PASSWORD clause in the FILE-CONTROL
paragraph. 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.
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
each alternate index in order to be fully password protected. Where you place the
PASSWORD clause is 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
The following example shows the COBOL code used for a VSAM indexed file that
has 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
. . .
Chapter 10. Processing VSAM files
209
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 z/OS and z/OS UNIX
Be aware of special coding considerations for VSAM files under z/OS and z/OS
UNIX for access method services (IDCAMS) commands, environment variables,
and JCL.
About this task
A VSAM file is available if all of the following conditions 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.
v It has previously contained a record.
A VSAM file is unavailable if it has never contained a record, even if you have
defined the file.
You always get a return code of zero on completion of the OPEN statement for a
VSAM sequential file.
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 9
“Defining VSAM files”
“Creating alternate indexes” on page 211
“Allocating VSAM files” on page 213
“Sharing VSAM files through RLS” on page 215
Defining VSAM files
You can process VSAM entry-sequenced, key-sequenced, and relative-record data
sets in Enterprise COBOL only after you define them through access method
services (IDCAMS).
About this task
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 DEFINE CLUSTER access-method services command to define 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)
210
Enterprise COBOL for z/OS, V5.1 Programming Guide
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)
If you define a data set in this way, all records are 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 uses the length specified in 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:
DEFINE CLUSTER NUMBERED
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 213
“Specifying relative organization for VSAM files” on page 196
RELATED REFERENCES
z/OS DFSMS: Access Method Services for Catalogs
Creating alternate indexes
An alternate index provides access to the records in a data set that uses more than
one key. It accesses records in the same way as the prime index key of an indexed
data set (KSDS).
About this task
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
Chapter 10. Processing VSAM files
211
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, do these steps:
Procedure
1. Define the alternate index by using the DEFINE ALTERNATEINDEX command. In it,
specify these items:
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
v Whether 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)
In your COBOL program, the alternate index is identified solely by the
ALTERNATE RECORD KEY clause in the FILE-CONTROL paragraph. The ALTERNATE
RECORD KEY definitions must match the definitions in the catalog entry. Any
password entries that you 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, specify these
items:
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. BLDINDEX reads all the records in the VSAM indexed
data set (or base cluster) and extracts the data needed to build the alternate
index.
Alternatively, you can use the runtime option AIXBLD to build the alternate
index at run time. However, this option might adversely affect performance.
Results
“Example: entries for alternate indexes”
RELATED TASKS
“Using an alternate index” on page 196
RELATED REFERENCES
Language Environment Programming Reference (AIXBLD (COBOL only))
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 that
has two alternate indexes.
212
Enterprise COBOL for z/OS, V5.1 Programming Guide
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.
(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 211
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, so you need to specify only minimal DD or environment variable
information.
About this task
Allocation of VSAM files (indexed, relative, and sequential) follows the general
rules for the allocation of COBOL files.
When you use an environment variable to allocate a VSAM file, the variable name
must be in uppercase. Usually the input and data buffers are the only variables
that you are concerned about. You must specify these options in the order shown,
but no others:
1. DSN(dsname), where dsname is the name of the base cluster
2. OLD or SHR
The basic DD statement that you need for VSAM files and the corresponding export
command are these:
//ddname
DD
DSN=dsname,DISP=SHR,AMP=AMORG
export evname="DSN(dsname),SHR"
Chapter 10. Processing VSAM files
213
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 that supplements 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 required only 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 a VSAM data set with an environment
variable.
For a VSAM base cluster, specify the same system-name (ddname or environment
variable name) that you specify in the ASSIGN clause after the SELECT clause.
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 a system-name 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 FILE-CONTROL
paragraph).
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 together with the 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 163
RELATED REFERENCES
MVS Program Management: User's Guide and Reference
214
Enterprise COBOL for z/OS, V5.1 Programming Guide
Sharing VSAM files through RLS
By using the VSAM JCL parameter RLS, you can specify record-level sharing with
VSAM. Specifying RLS is the only way to request the RLS mode when running
COBOL programs.
About this task
Use RLS=CR when consistent read protocols are required, and RLS=NRI when no read
integrity protocols are required. You cannot specify RLS if you allocate your VSAM
data set with an environment variable
RELATED TASKS
“Preventing update problems with VSAM files in RLS mode”
“Handling errors in VSAM files in RLS mode” on page 216
RELATED REFERENCES
“Restrictions when using RLS” on page 216
Preventing update problems with VSAM files in RLS mode
When you open a VSAM data set in RLS mode for I-O (updates), the first READ
causes an exclusive lock of the record regardless of the value of RLS (RLS=CR or
RLS=NRI) that you specify.
About this task
If the COBOL file is defined as ACCESS RANDOM, VSAM releases the exclusive lock
on the record after a WRITE or REWRITE statement is executed or a READ statement is
executed for another record. When a WRITE or REWRITE is done, VSAM writes the
record immediately.
However, if the COBOL file is defined as ACCESS DYNAMIC, VSAM does not release
the exclusive lock on the record after a WRITE or REWRITE statement, nor after a READ
statement, unless the I-O statement causes VSAM to move to another control
interval (CI). As a result, if a WRITE or REWRITE was done, VSAM does not write the
record until processing is moved to another CI and the lock is released. When you
use ACCESS DYNAMIC, one way to cause the record to be written immediately, to
release the exclusive lock immediately, or both, is to define the VSAM data set to
allow only one record per CI.
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 executed. Another user might update the record.
The locking rules for RLS=CR can cause the application to wait for availability of a
record lock. This wait might slow down the READ for input. You might need to
modify your application logic to use RLS=CR. Do not use the RLS 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
good to issue an OPEN or START immediately before a READ. If there is a delay
between the OPEN or START and the 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
Chapter 10. Processing VSAM files
215
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
When you use RLS mode, several restrictions apply to VSAM cluster attributes and
to runtime options.
Be aware of these restrictions:
v The VSAM cluster attributes KEYRANGE and IMBED are not supported when you
open a VSAM file.
v The VSAM cluster attribute REPLICATE is not recommended because the benefits
are negated by the system-wide buffer pool and potentially large CF cache
structure in the storage hierarchy.
v The AIXBLD runtime option is not supported when you open a VSAM file
because VSAM does not allow an empty path to be opened. If you need the
AIXBLD runtime option to build the alternate index data set, open the VSAM data
set in non-RLS mode.
v The SIMVRD runtime option is not supported for VSAM files.
v Temporary data sets are not allowed.
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.
About this task
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 such failures, and there is no feedback code.
You can have COBOL programs check the first 2 bytes of the second file status
area for 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.
RELATED TASKS
“Using VSAM status codes (VSAM files only)” on page 253
|
Allocation of record areas for VSAM files
|
|
For reentrant COBOL programs, the record areas for VSAM files are allocated
above the 16 MB line by default.
|
|
If you specify the DATA(24) compiler option, the VSAM record areas and other
dynamic storage areas are allocated in storage below 16 MB.
|
|
|
|
Programs that pass data in VSAM file records as CALL...USING parameters to
AMODE(24) subprograms are impacted. You can recompile such programs with the
DATA(24) compiler option, or use the Language Environment HEAP runtime option,
to ensure that the records are addressable by the AMODE(24) programs.
216
Enterprise COBOL for z/OS, V5.1 Programming Guide
Improving VSAM performance
Your system programmer is most likely responsible for tuning the performance of
COBOL and VSAM. As an application programmer, you can control the aspects of
VSAM that are listed in the following table.
About this task
Table 31. Methods for improving VSAM performance
Aspect of VSAM What you can do
Invoking access
methods service
Build your alternate indexes in
advance, using IDCAMS.
Buffering
For sequential access, request
more data buffers; for random
access, request more index
buffers. Specify both BUFND
and BUFNI if ACCESS IS
DYNAMIC.
Rationale and comments
The default is one index (BUFNI) and
two data buffers (BUFND).
Avoid coding additional
buffers unless your application
will run interactively; then
code buffers only when
response-time problems arise
that might be caused by
delays in input and output.
Loading records,
using access
methods services
Use the access methods service The REPRO command can update an
indexed data set as fast or faster than
REPRO command when:
v The target indexed data set any COBOL program under these
conditions.
already contains records.
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.
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 Updates must be applied through the
indexes.
primary paths and are reflected
through multiple alternate paths,
perhaps slowing performance.
Chapter 10. Processing VSAM files
217
Table 31. Methods for improving VSAM performance (continued)
Aspect of VSAM What you can do
Rationale and comments
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.
Control interval
sizes (CISZ)
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).
VSAM calculates CISZ to best fit the
direct-access storage device (DASD)
usage algorithm, which might not,
however, be efficient for your
application.
An average CISZ of 4K is suitable for
most applications. A smaller CISZ
means faster retrieval for random
processing at the expense of inserts
(that is, more CISZ splits and therefore
Choose proper values for CISZ more space in the data set). A larger
and FSPC to minimize control CISZ results in the transfer of more data
across the channel for each READ. This is
area (CA) splits. You can
more efficient for sequential processing,
diagnose the current number
similar to a large OS BLKSIZE.
of CA splits by issuing the
LISTCAT ALL command on the
Many control area (CA) splits are
cluster, and then compress
unfavorable for VSAM performance.
(using EXPORT, IMPORT, or
The FREESPACE value can affect CA
REPRO) the cluster to omit all
splits, depending on how the file is
CA splits periodically.
used.
RELATED TASKS
“Specifying access modes for VSAM files” on page 197
z/OS DFSMS: Using Data Sets (Building a resource pool, Selecting the optimal
percentage of free space)
RELATED REFERENCES
z/OS DFSMS: Access Method Services for Catalogs
218
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 11. Processing line-sequential files
Line-sequential files reside in the z/OS UNIX file system and can contain both
printable characters and control characters as data. Each record ends with an
EBCDIC newline character (X’15’), which is not included in the record length.
About this task
Because line-sequential files are sequential, 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 a program, code 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 TASKS
“Defining line-sequential files and records in COBOL”
“Allocating line-sequential files” on page 221
“Coding input-output statements for line-sequential files” on page 221
“Handling errors in line-sequential files” on page 224
UNIX System Services User's Guide
Defining line-sequential files and records in COBOL
Use the FILE-CONTROL paragraph in the ENVIRONMENT DIVISION to define the files in
a COBOL program as line-sequential files, and to associate the files with the
corresponding external file-names (ddnames or environment variable names).
About this task
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.
The ASSIGN assignment-name clause must not include an organization field (S- or
AS-) before the external name. The ACCESS phrase and the FILE STATUS clause are
optional.
RELATED TASKS
“Describing the structure of a line-sequential file” on page 220
© Copyright IBM Corp. 1991, 2013
219
“Allocating line-sequential files” on page 221
“Coding input-output statements for line-sequential files” on page 221
RELATED REFERENCES
“Control characters in line-sequential files”
Describing the structure of a line-sequential file
In the FILE SECTION, code a file description (FD) entry for the file. In the associated
record description entry or entries, define the record-name and record length.
About this task
Code the logical size in bytes of the records by using 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:
With fixed-length records:
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 variable-length records:
FILE SECTION.
FD COMMUTER-FILE
RECORD VARYING FROM 16 TO 80 CHARACTERS.
01 COMMUTER-RECORD.
05 COMMUTER-NUMBER
PIC X(16).
05 COMMUTER-DESCRIPTION
PIC X(64).
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.
RELATED TASKS
“Allocating line-sequential files” on page 221
“Coding input-output statements for line-sequential files” on page 221
RELATED REFERENCES
Data division--file description entries (Enterprise COBOL Language Reference)
Control characters in line-sequential files
A line-sequential file can contain control characters. Be aware though that if a
line-sequential file contains a newline character (X’15’), the newline character will
function as a record delimiter.
Control characters other than newline are treated as data and are part of the
record.
220
Enterprise COBOL for z/OS, V5.1 Programming Guide
Allocating line-sequential files
You can allocate a line-sequential file in the z/OS UNIX file system by using either
a DD statement or an environment variable. Allocation of line-sequential files
follows the general rules for allocating COBOL files.
About this task
To allocate a line-sequential file, code a DD allocation or an environment variable
that has a name that matches the external name in the 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 that has a value of PATH(absolute-path-name). No other
values can be specified.
For example, to have your program use z/OS UNIX file /u/myfiles/
commuterfile for a COBOL file that has an assignment-name of COMMUTR, you can
use the following command:
export COMMUTR="PATH(/u/myfiles/commuterfile)"
RELATED TASKS
“Allocating files” on page 163
“Defining line-sequential files and records in COBOL” on page 219
RELATED REFERENCES
MVS Program Management: User's Guide and Reference
Coding input-output statements for line-sequential files
Code the input and output statements shown below to process a line-sequential
file.
About this task
OPEN
To initiate the processing of a file.
You can open a line-sequential file as INPUT, OUTPUT, or EXTEND. You cannot
open a line-sequential file as I-O.
READ
To read a record from a file.
With sequential processing, a program reads one record after another in
the same order in which the records were entered when the file was
created.
WRITE
To create a record in a file.
A program writes new records to the end of the file.
CLOSE
To release the connection between a file and the program.
RELATED TASKS
“Defining line-sequential files and records in COBOL” on page 219
Chapter 11. Processing line-sequential files
221
“Describing the structure of a line-sequential file” on page 220
“Opening line-sequential files”
“Reading records from line-sequential files”
“Adding records to line-sequential files” on page 223
“Closing line-sequential files” on page 223
“Handling errors in line-sequential files” on page 224
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
READ statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise COBOL Language Reference)
CLOSE statement (Enterprise 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.
About this task
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 223
“Closing line-sequential files” on page 223
“Allocating line-sequential files” on page 221
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
CLOSE statement (Enterprise COBOL Language Reference)
Reading records from line-sequential files
To read from a line-sequential file, open the file and use the READ statement. Your
program reads one record after another in the same order in which the records
were entered when the file was created.
About this task
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 newline 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.)
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.)
v End-of-file is encountered.
222
Enterprise COBOL for z/OS, V5.1 Programming Guide
The remainder of the record area is filled with spaces. (Record area is longer
than the file record.)
RELATED TASKS
“Opening line-sequential files” on page 222
“Adding records to line-sequential files”
“Closing line-sequential files”
“Allocating line-sequential files” on page 221
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise 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.
About this task
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. Zoned decimal data items must be unsigned or declared with the
SEPARATE phrase of the SIGN clause if signed.
RELATED TASKS
“Opening line-sequential files” on page 222
“Reading records from line-sequential files” on page 222
“Closing line-sequential files”
“Allocating line-sequential files” on page 221
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise 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.
About this task
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) runtime 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 11. Processing line-sequential files
223
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 222
“Reading records from line-sequential files” on page 222
“Adding records to line-sequential files” on page 223
“Allocating line-sequential files” on page 221
RELATED REFERENCES
CLOSE statement (Enterprise COBOL Language Reference)
Handling errors in line-sequential files
When an input or output statement fails, COBOL does not take corrective action
for you. You choose whether your program should continue running after an input
or output statement fails.
About this task
COBOL provides these language elements 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, your program might
continue, but the results will probably not be what you expected.
RELATED TASKS
“Coding input-output statements for line-sequential files” on page 221
“Handling errors in input and output operations” on page 247
224
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 12. Sorting and merging files
About this task
You can arrange records in a particular sequence by using a SORT or MERGE
statement. You can mix SORT and MERGE statements in the same COBOL program.
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.
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 Enterprise COBOL, 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 that contain SORT or MERGE statements can reside above or below
the 16 MB line.
The steps you take to sort or merge are generally as follows:
Procedure
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.
Results
Restrictions:
v You cannot run a COBOL program that contains SORT or MERGE statements under
z/OS UNIX. This restriction includes BPXBATCH.
v You cannot use SORT or MERGE statements in programs compiled with the THREAD
option. This includes programs that use object-oriented syntax and
multithreaded applications, both of which require the THREAD option.
RELATED CONCEPTS
“Sort and merge process” on page 226
© Copyright IBM Corp. 1991, 2013
225
RELATED TASKS
“Describing the sort or merge file”
“Describing the input to sorting or merging” on page 227
“Describing the output from sorting or merging” on page 229
“Requesting the sort or merge” on page 233
“Determining whether the sort or merge was successful” on page 236
“Stopping a sort or merge operation prematurely” on page 237
“Improving sort performance with FASTSRT” on page 237
“Controlling sort behavior” on page 240
DFSORT Application Programming Guide
RELATED REFERENCES
“CICS SORT application restrictions” on page 244
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise COBOL Language Reference)
Sort and merge process
During the sorting of a file, all of the records in the file are ordered according to
the contents of one or more fields (keys) in each record. You can sort the records in
either ascending or descending order of each key.
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.
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. You can order the records in either ascending or descending order of
each key. 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.
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 TASKS
“Setting sort or merge criteria” on page 234
RELATED REFERENCES
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise COBOL Language Reference)
Describing the sort or merge file
Describe the sort file to be used for sorting or merging. You need SELECT clauses
and SD entries even if you are sorting or merging data items only from
WORKING-STORAGE or LOCAL-STORAGE.
About this task
Code as follows:
226
Enterprise COBOL for z/OS, V5.1 Programming Guide
Procedure
1. Write one or more SELECT clauses 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).
Results
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 and you
do not need to provide a ddname definition for it.
RELATED REFERENCES
“FILE SECTION entries” on page 13
Describing the input to sorting or merging
Describe the input file or files for sorting or merging by following the procedure
below.
About this task
Procedure
1. Write one or more SELECT clauses 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).
Chapter 12. Sorting and merging files
227
Results
RELATED TASKS
“Coding the input procedure”
“Requesting the sort or merge” on page 233
RELATED REFERENCES
“FILE SECTION entries” on page 13
Example: describing sort and input files for SORT
The following example shows the ENVIRONMENT DIVISION and DATA DIVISION entries
needed to describe sort work 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).
05 Filler
Pic X(80).
SD 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).
. . .
RELATED TASKS
“Requesting the sort or merge” on page 233
Coding the input procedure
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.
228
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
You can use an input procedure to:
v Release data items to the sort file from WORKING-STORAGE or LOCAL-STORAGE.
v Release records that have already been read 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 or LOCAL-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.
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 231
RELEASE statement (Enterprise 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 the
procedure below.
About this task
Procedure
1. Write a SELECT clause in the FILE-CONTROL paragraph of the ENVIRONMENT
DIVISION to name the output file. For example:
Chapter 12. Sorting and merging files
229
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).
Results
RELATED TASKS
“Coding the output procedure”
“Requesting the sort or merge” on page 233
RELATED REFERENCES
“FILE SECTION entries” on page 13
Coding the output procedure
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.
About this task
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 statement or one RETURN statement with the INTO phrase
v Any statements necessary to process the records that are made available, one at
a time, by the RETURN statement
The RETURN statement makes each sorted record available to the 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 in 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 RETURN INTO instead of RETURN, the records will be returned to
WORKING-STORAGE, LOCAL-STORAGE, or to an output area.
DFSORT coding: If you use DFSORT and a RETURN statement does not encounter
an AT END condition before a COBOL program finishes running, the SORT statement
could end abnormally with DFSORT message IEC025A. To avoid this situation, be
sure to code the RETURN statement with the AT END phrase. In addition, ensure that
the RETURN statement is executed until the AT END condition is encountered. The AT
230
Enterprise COBOL for z/OS, V5.1 Programming Guide
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”
RETURN statement (Enterprise 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: ’.
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
Several restrictions apply to each input or output procedure called by SORT and to
each output procedure called by MERGE.
Observe these restrictions:
v The procedure must not contain any SORT or MERGE 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.
Chapter 12. Sorting and merging files
231
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.
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 let user-written condition
handlers be established in an input or output procedure.
RELATED TASKS
“Coding the input procedure” on page 228
“Coding the output procedure” on page 230
Language Environment Programming Guide (Preparing to link-edit and run)
Defining sort and merge data sets
To use DFSORT under z/OS, code DD statements in the runtime JCL to describe the
necessary data sets that are listed below.
About this task
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 z/OS
UNIX file system.
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.
Input and output
Define input and output data sets, if any.
SORTLIB (DFSORT library)
Define the library that contains the sort modules, for example,
SYS1.SORTLIB.
RELATED TASKS
“Controlling sort behavior” on page 240
“Using checkpoint/restart with DFSORT” on page 243
Sorting variable-length records
About this task
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 determines that the sort work file is variable length if you code one
of the following elements in the SD entry:
232
Enterprise COBOL for z/OS, V5.1 Programming Guide
v A RECORD IS VARYING clause
v Two or more record descriptions that define records that have different sizes, or
records that contain an OCCURS DEPENDING ON clause
You cannot use RECORDING MODE V for the sort work file because the SD entry does
not allow the RECORDING MODE clause.
Performance consideration: To improve sort performance of 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 241
“Controlling sort behavior” on page 240
Requesting the sort or merge
To read records from an input file (files for MERGE) without preliminary processing,
use SORT . . . USING or MERGE . . . USING and the name of the input file (files)
that you declared in a SELECT clause.
About this task
To transfer sorted or merged records from the sort or merge program to another
file without any further processing, use SORT . . . GIVING or MERGE . . . GIVING
and the name of the output file that you declared in a SELECT clause. For example:
SORT Sort-Work-1
ON ASCENDING KEY Sort-Key-1
USING Input-File
GIVING Output-File.
For SORT . . . USING or MERGE . . . USING, the compiler generates an input
procedure to open the file (files), read the records, release the records to the sort or
merge program, and close the file (files). The file (files) must not be open when the
SORT or MERGE statement begins execution. For SORT . . . GIVING or MERGE . . .
GIVING, the compiler generates an output procedure to open the file, return the
records, write the records, and close the file. The file must not be open when the
SORT or MERGE statement begins execution.
The USING or GIVING files in a SORT or MERGE statement can be sequential files
residing in the z/OS UNIX file system.
“Example: describing sort and input files for SORT” on page 228
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 235
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.
Chapter 12. Sorting and merging files
233
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.
In the FILE SECTION, you must define Merge-Work in an SD entry, and the input files
in FD entries.
RELATED TASKS
“Defining sort and merge data sets” on page 232
RELATED REFERENCES
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise COBOL Language Reference)
Setting sort or merge criteria
To set sort or merge criteria, define the keys on which the operation is to be
performed.
About this task
Do these steps:
Procedure
1. In the record description of the files to be sorted or merged, define the key or
keys.
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
by coding the ASCENDING or DESCENDING KEY phrase, or both. When you code
more than one key, some can be ascending, and some descending.
Specify the names of the keys in decreasing order of significance. The leftmost
key is the primary key. The next key is the secondary key, and so on.
Results
SORT and MERGE keys can be of class alphabetic, alphanumeric, national, or numeric
(but not numeric of USAGE NATIONAL). If it has USAGE NATIONAL, a key can be of
category national or can be a national-edited or numeric-edited data item. A key
cannot be a national decimal data item or a national floating-point data item.
The collation order for national keys is determined by the binary order of the keys.
If you specify a national data item as a key, any COLLATING SEQUENCE phrase in the
SORT or MERGE statement does not apply to that key.
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.
234
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
DFSORT Application Programming Guide (SORT control statement)
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise 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 a primary key
(SORT-GRID-LOCATION) and a secondary key (SORT-SHIFT) 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).
. . .
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 233
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.
Chapter 12. Sorting and merging files
235
About this task
To override the default sequence, 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.
The PROGRAM COLLATING SEQUENCE clause and the COLLATING SEQUENCE phrase apply
only to keys of class alphabetic or alphanumeric.
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, and define the alphabet-name as STANDARD-1 in the SPECIAL-NAMES
paragraph.
RELATED TASKS
“Specifying the collating sequence” on page 7
“Setting sort or merge criteria” on page 234
RELATED REFERENCES
OBJECT-COMPUTER paragraph (Enterprise COBOL Language Reference)
SORT statement (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Preserving the original sequence of records with equal keys
About this task
You can preserve the order of identical collating records from input to output.
Use one of these techniques:
v Install DFSORT with the EQUALS option as the default.
v Provide, at run time, an OPTION card that has 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 both the NOEQUALS keyword on the OPTION card and the DUPLICATES
phrase, or the run unit will end.
RELATED REFERENCES
DFSORT Application Programming Guide (OPTION control statement)
Determining whether the sort or merge was successful
The DFSORT program returns a completion code of either 0 (successful
completion) or 16 (unsuccessful completion) after each sort or merge has finished.
The completion code is stored in the SORT-RETURN special register.
About this task
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
236
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 completion code. If it is 16, COBOL issues a runtime diagnostic
message.
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.
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 completion code.
RELATED TASKS
“Checking for sort errors with NOFASTSRT” on page 240
“Controlling sort behavior” on page 240
RELATED REFERENCES
DFSORT Application Programming Guide (DFSORT messages and return codes)
Stopping a sort or merge operation prematurely
To stop a sort or merge operation, move the integer 16 into the SORT-RETURN special
register.
About this task
Move 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 Enterprise COBOL)
performs the I/O on the input and output files you name in the SORT . . . USING
and SORT . . . GIVING statements.
About this task
The compiler issues informational messages to point out statements in which
FASTSRT can improve performance.
Chapter 12. Sorting and merging files
237
Usage notes
v 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.
v If you specify file status and use FASTSRT, file status is ignored during the sort.
RELATED REFERENCES
“FASTSRT” on page 335
“FASTSRT requirements for JCL”
“FASTSRT requirements for sort input and output files”
FASTSRT requirements for JCL
In the runtime 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 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 that are
otherwise possible.
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 name only one input file in the USING phrase. You can name 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 these
DFSORT control statements:
– INREC
– OUTFILE
– 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 or 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.
238
Enterprise COBOL for z/OS, V5.1 Programming Guide
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.
If you code a RELATIVE KEY clause for an output file, it will not be set by the sort.
Performance 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 this:
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
Then in your JCL, assuming that data set INOUT has been cataloged, you would
code:
//INPUTF DD DSN=INOUT,DISP=SHR
//OUTPUTF DD DSN=INOUT,DISP=SHR
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
v
v
v
A VSAM input file must not be empty.
VSAM files cannot be password-protected.
You cannot name the same VSAM file in both the USING and GIVING phrases.
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 fails.)
RELATED TASKS
DFSORT Application Programming Guide
Chapter 12. Sorting and merging files
239
Checking for sort errors with NOFASTSRT
When you compile with the NOFASTSRT option, the sort process does not check for
errors in open, close, or input or output operations for files that you reference in
the USING or GIVING phrase of the SORT statement. Therefore, you might need to
check whether SORT completed successfully.
About this task
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.
Table 32. Methods for checking for sort errors with NOFASTSRT
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:
RELATED TASKS
“Determining whether the sort or merge was successful” on page 236
“Using file status keys” on page 251
“Coding ERROR declaratives” on page 250
“Stopping a sort or merge operation prematurely” on page 237
Controlling sort behavior
You can control several aspects of sort behavior by inserting values in special
registers before the sort or by using compiler options. You might also have a choice
of control statements and keywords.
About this task
You can 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 by using
special registers or compiler options, and the equivalent sort control statement
keywords if any are available.
Table 33. Methods for controlling sort behavior
To set or test
Amount of main storage to be
reserved
240
Enterprise COBOL for z/OS, V5.1 Programming Guide
Use this special register or
compiler option
Or this control statement
(and keyword if
applicable)
SORT-CORE-SIZE special register OPTION (keyword RESINV)
Table 33. Methods for controlling sort behavior (continued)
Or this control statement
(and keyword if
applicable)
To set or test
Use this special register or
compiler option
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
OPTION (keyword MSGDDN)
Number of sort records
SORT-FILE-SIZE special register OPTION (keyword FILSZ)
Sort completion code
SORT-RETURN special register
None
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
run time, however, any parameters in 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.
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 236
“Stopping a sort or merge operation prematurely” on page 237
“Changing DFSORT defaults with control statements”
“Allocating space for sort files” on page 243
DFSORT Application Programming Guide (Using DFSORT program
control statements)
RELATED REFERENCES
“Default characteristics of the IGZSRTCD data set” on page 242
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 runtime data set
IGZSRTCD.
About this task
The control statements that you can include in IGZSRTCD (in the order listed) are:
Chapter 12. Sorting and merging files
241
Procedure
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).
Results
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. You cannot use labels or comments on a record, and a record itself
cannot be a DFSORT comment statement.
RELATED TASKS
“Controlling sort behavior” on page 240
DFSORT Application Programming Guide (Using DFSORT program
control statements)
RELATED REFERENCES
“Default characteristics of the IGZSRTCD data set”
Default characteristics of the IGZSRTCD data set
The IGZSRTCD data set is optional. Its defaults are LRECL=80, BLKSIZE=400, and
ddname IGZSRTCD.
You can use a different ddname by coding it in the SORT-CONTROL special register. 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.
RELATED TASKS
“Controlling sort behavior” on page 240
Allocating storage for sort or merge operations
About this task
Certain parameters set during the installation of DFSORT determine the amount of
storage that DFSORT 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:
v COBOL programs that are dynamically called from an input or output procedure
v Language Environment runtime 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.
242
Enterprise COBOL for z/OS, V5.1 Programming Guide
Be careful not to override the storage allocation to the extent that all the free space
in the region is used for sort operations for your COBOL program.
RELATED TASKS
“Controlling sort behavior” on page 240
DFSORT Installation and Customization
RELATED REFERENCES
DFSORT Application Programming Guide (OPTION control statement)
Allocating space for sort files
If you use NOFASTSRT or an input procedure, DFSORT does not know the size of
the file that you are sorting. This can lead to an out-of-space condition when you
sort large files or to overallocation of resources when you sort small files.
About this task
If this occurs, you can use the SORT-FILE-SIZE special register to help DFSORT
determine the amount of resource (for example, workspace or hiperspace) needed
for the sort. Set SORT-FILE-SIZE to a reasonable estimate of the number of input
records. This value is passed to DFSORT as its FILSZ=En value.
RELATED TASKS
“Controlling sort behavior” on page 240
“Coding the input procedure” on page 228
DFSORT Application Programming Guide
Using checkpoint/restart with DFSORT
You cannot use checkpoints taken while DFSORT is running under z/OS to restart,
unless the checkpoints are taken by DFSORT.
About this task
Checkpoints taken by a COBOL program while SORT or MERGE statements execute
are invalid; such restarts are detected and canceled.
To take a checkpoint during a sort or merge operation, do these steps:
Procedure
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).
Results
RELATED CONCEPTS
Chapter 32, “Interrupts and checkpoint/restart,” on page 641
RELATED TASKS
“Changing DFSORT defaults with control statements” on page 241
“Setting checkpoints” on page 641
Chapter 12. Sorting and merging files
243
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.
About this task
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 228
“Coding the output procedure” on page 230
“Coding COBOL programs to run under CICS” on page 421
RELATED REFERENCES
“CICS SORT application restrictions”
“CICS reserved-word table” on page 430
CICS SORT application restrictions
Several restrictions apply to COBOL applications that run under CICS and use the
SORT statement.
The restrictions are:
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 These 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
You can use CICS commands other than these if you use the NOHANDLE or RESP
option. Unpredictable results can occur if you do not use NOHANDLE or RESP.
RELATED REFERENCES
“CICS reserved-word table” on page 430
244
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 13. Handling errors
About this task
Put code in your programs that anticipates possible system or runtime problems. If
you do not include such code, output data or files could be corrupted, and the
user might not even be aware that there is a problem.
The error-handling code can take actions such as handling the situation, issuing a
message, or halting the program. You might for example create error-detection
routines for data-entry errors or for errors as your installation defines them. In any
event, coding a warning message is a good idea.
Enterprise 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 ON SIZE ERROR in arithmetic operations
v Elements for handling input or output errors
v ON EXCEPTION or ON OVERFLOW in CALL statements
v User-written routines for handling errors
RELATED TASKS
“Handling errors in joining and splitting strings” on page 246
“Handling errors in arithmetic operations” on page 246
“Handling errors in input and output operations” on page 247
“Handling errors when calling programs” on page 256
“Writing routines for handling errors” on page 256
Requesting dumps
About this task
You can cause a formatted dump of the Language Environment runtime
environment and the member language libraries at any prespecified point in your
program by coding a call to the Language Environment callable service CEE3DMP.
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, compile with the TEST
compiler option and use the VARIABLES subparameter of CEE3DMP. You can also
request, through runtime options, that a dump be produced for error conditions of
your choosing.
You can cause a system dump at any prespecified point in your program. 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.
© Copyright IBM Corp. 1991, 2013
245
RELATED REFERENCES
“TEST” on page 364
Language Environment Debugging Guide
Language Environment Programming Reference (CEE3DMP--generate dump)
Handling errors in joining and splitting strings
During the joining or splitting of strings, the pointer used by STRING or UNSTRING
might fall outside the range of the receiving field. A potential overflow condition
exists, but COBOL does not let the overflow happen.
About this task
Instead, the STRING or UNSTRING operation is not completed, the receiving field
remains unchanged, and control passes to the next sequential statement. If you do
not code the ON OVERFLOW phrase of the STRING or UNSTRING statement, 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
EA
1
Item-4
X(8)
bbbbbbbb
bbbbbbbb1
String-ptr
9(2)
0
0
1. The symbol b represents a blank space.
Because String-ptr has a value (0) that falls short of the receiving field, an
overflow condition occurs and the STRING operation is not completed. (Overflow
would also occur if String-ptr were greater than 9.) If ON OVERFLOW had not been
specified, you would not be notified that the contents of Item-4 remained
unchanged.
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.
About this task
For ON SIZE ERROR to work correctly for fixed-point overflow and decimal
overflow, you must specify the TRAP(ON) runtime option.
246
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 z 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
The following example shows how you can code an ON SIZE ERROR imperative
statement so that the program issues an informative message if division by zero
occurs.
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.
If division by zero occurs, the program writes a message 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.
About this task
You can use any of the following techniques for intercepting and handling certain
input or output conditions or errors:
v End-of-file condition (AT END)
v ERROR declaratives
v FILE STATUS clause and file status key
v File system status code
v Imperative-statement phrases in READ or WRITE statements
For VSAM files, if you specify a FILE STATUS clause, you can also test the VSAM
status code to direct your program to error-handling logic.
v INVALID KEY phrase
To have your program continue, you must code the appropriate error-recovery
procedure. You might code, for example, a procedure to check the value of the file
Chapter 13. Handling errors
247
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 figure shows the flow of logic after a VSAM input or output error:
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).
248
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 250
“Using file status keys” on page 251
“Handling errors in QSAM files” on page 180
“Using VSAM status codes (VSAM files only)” on page 253
“Handling errors in line-sequential files” on page 224
“Coding INVALID KEY phrases” on page 255
RELATED REFERENCES
File status key (Enterprise COBOL Language Reference)
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. At end-of-file, the AT END phrase is
performed. If you do not code an AT END phrase, the associated ERROR declarative is
performed.
Chapter 13. Handling errors
249
About this task
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
that contains 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 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 any associated declarative
procedure is performed.
You might choose not to code either an AT END phrase or an EXCEPTION declarative
procedure, but to code a status key clause for the file instead. In that case, control
passes to the next sequential instruction after the input or output statement that
detected the end-of-file condition. At that place, have some code that takes
appropriate action.
RELATED REFERENCES
AT END phrases (Enterprise COBOL Language Reference)
Coding ERROR declaratives
You can code one or more ERROR declarative procedures that will be given control
if an input or output error occurs during the execution of your program. If you do
not code such procedures, your job could be canceled or abnormally terminated
after an input or output error occurs.
About this task
Place each such procedure in the declaratives section of the PROCEDURE DIVISION.
You can code:
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 file
In an ERROR declarative procedure, you can code corrective action, retry the
operation, continue, or end execution. (If you continue processing a blocked file,
though, you might lose the remaining records in a block after the record that
caused the error.) You can use the ERROR declaratives procedure in combination
with the file status key if you want a further analysis of the error.
Multithreading: Avoid deadlocks when coding I/O declaratives in multithreaded
applications. When an I/O operation results in a transfer of control to an I/O
declarative, the automatic serialization lock associated with the file is held during
the execution of the statements within the declarative. If you code I/O operations
within your declaratives, your logic might result in a deadlock as illustrated by the
following sample:
250
Enterprise COBOL for z/OS, V5.1 Programming Guide
Declaratives.
D1 section.
Use after standard error procedure on F1
Read F2.
. . .
D2 section.
Use after standard error procedure on F2
Read F1.
. . .
End declaratives.
. . .
Rewrite R1.
Rewrite R2.
When this program is running on two threads, the following sequence of events
could occur:
Procedure
1. Thread 1: Rewrite R1 acquires lock on F1 and encounters I/O error.
2. Thread 1: Enter declarative D1, holding lock on F1.
3. Thread 2: Rewrite R2 acquires lock on F2 and encounters I/O error.
4. Thread 2: Enter declarative D2.
5. Thread 1: Read F2 from declarative D1; wait on F2 lock held by thread 2.
6. Thread 2: Read F1 from declarative D2; wait on F1 lock held by thread 1.
7. Deadlock.
Results
RELATED REFERENCES
EXCEPTION/ERROR declarative (Enterprise 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 digit positions of the file status key. In general, a zero in the first
position indicates a successful operation, and a zero in both positions means that
nothing abnormal occurred.
About this task
Establish a file status key by coding:
v The FILE STATUS clause in the FILE-CONTROL paragraph:
FILE STATUS IS data-name-1
v Data definitions in the DATA DIVISION (WORKING-STORAGE, LOCAL-STORAGE, or
LINKAGE SECTION), for example:
WORKING-STORAGE SECTION.
01 data-name-1 PIC 9(2)
USAGE NATIONAL.
Specify the file status key data-name-1 as a two-character category alphanumeric or
category national item, or as a two-digit zoned decimal or national decimal item.
This data-name-1 cannot be variably located.
Your program can check the file status key to discover whether an error occurred,
and, if so, what type of error occurred. For example, suppose that a FILE STATUS
clause is coded like this:
FILE STATUS IS FS-CODE
Chapter 13. Handling errors
251
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.
Doing so means that you can 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 each input or output request.
If the file status key contains a value other than 0, your program can issue an
error message or can take action based on that value.
You do not have to reset the file status key code, because it is set after each
input or output attempt.
For VSAM files, you can additionally code a second identifier in the FILE STATUS
clause to get more detailed information about VSAM input or output requests.
You can use the file status key alone or in conjunction with the INVALID KEY
phrase, or to supplement the EXCEPTION or ERROR declarative. Using the file status
key in this way gives you precise information about the results of each input or
output operation.
“Example: file status key”
RELATED TASKS
“Using VSAM status codes (VSAM files only)” on page 253
“Coding INVALID KEY phrases” on page 255
“Finding and handling input-output errors” on page 381
RELATED REFERENCES
FILE STATUS clause (Enterprise COBOL Language Reference)
File status key (Enterprise COBOL Language Reference)
Example: file status key
The following example shows how you can perform a simple check of the file
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.
. . .
WORKING-STORAGE SECTION.
01 MASTER-CHECK-KEY
PIC X(2).
. . .
PROCEDURE DIVISION.
252
Enterprise COBOL for z/OS, V5.1 Programming Guide
OPEN INPUT MASTERFILE
IF MASTER-CHECK-KEY NOT = "00"
DISPLAY "Nonzero file status returned from OPEN " MASTER-CHECK-KEY
. . .
Using VSAM status codes (VSAM files only)
Often the COBOL 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 data item in the FILE STATUS clause.
About this task
FILE STATUS IS data-name-1 data-name-8
The data item data-name-1 shown above specifies the COBOL file status key, which
you define as a two-character alphanumeric or national data item, or as a two-digit
zoned decimal or national decimal item.
The data item data-name-8 specifies the VSAM status code, which you define as a
6-byte alphanumeric group data item that has three subordinate 2-byte binary
fields. The VSAM status code contains meaningful values when the COBOL file
status key is not 0.
You can define data-name-8 in the WORKING-STORAGE SECTION, as in VSAM-CODE below.
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 Comp-5.
PIC S9(4) Usage Comp-5.
PIC S9(4) Usage Comp-5.
Enterprise COBOL 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” on page 254
RELATED REFERENCES
FILE STATUS clause (Enterprise COBOL Language Reference)
File status key (Enterprise COBOL Language Reference)
z/OS DFSMS Macro Instructions for Data Sets (VSAM macro return and
reason codes)
Chapter 13. Handling errors
253
Example: checking VSAM status codes
The following example reads an indexed file (starting at the fifth record), checks
the file status key after each input or output request, and displays the VSAM
status codes when the file status key is not zero.
This example also illustrates how output from this program might look if the file
being processed contained 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 ==>"
254
Enterprise COBOL for z/OS, V5.1 Programming Guide
" 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
status-code information:
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 an INVALID KEY phrase in READ, START, WRITE, REWRITE, and DELETE
statements for VSAM indexed and relative files. The INVALID KEY phrase is given
control if an input or output error occurs due to a faulty index key.
About this task
You can also include the INVALID KEY phrase in WRITE requests for QSAM files, but
the phrase has limited meaning for QSAM files. It is used only if you try to write
to a disk that is full.
Use the FILE STATUS clause with the INVALID KEY phrase to evaluate the status key
and determine the specific INVALID KEY condition.
INVALID KEY phrases differ from ERROR declaratives in several ways. INVALID KEY
phrases:
v Operate for only limited types of errors. ERROR declaratives encompass all forms.
v Are coded directly with the input or output statement. ERROR declaratives are
coded separately.
v Are specific for a single input or output operation. 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. Any ERROR
declaratives that you coded are not performed.
If you code a NOT INVALID KEY phrase, it 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, after the program performs any associated ERROR declaratives,
control passes to the end of the statement.
“Example: FILE STATUS and INVALID KEY”
Example: FILE STATUS and INVALID KEY
The following example shows how you can use the file status code and the
INVALID KEY phrase to determine more specifically why an input or output
statement failed.
Assume that you have a file that contains master customer records and you need
to update some of these records with information from a transaction update file.
Chapter 13. Handling errors
255
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
that define indexed organization, random access, MASTER-CUSTOMER-NUMBER as the
prime record key, and CUSTOMER-FILE-STATUS as the file status key.
.
. (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. For example, the system might be out of storage or
unable to locate the load module. If the CALL statement does not have an ON
EXCEPTION or ON OVERFLOW phrase, your application might abend.
About this task
Use the ON EXCEPTION phrase to perform a series of statements and to perform your
own error handling. For example, in the code fragment below, if program REPORTA
is unavailable, control passes to the ON EXCEPTION phrase.
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
The ON EXCEPTION phrase applies only to the availability of the called program on
its initial load. If the called program is loaded but fails for any other reason (such
as initialization), the ON EXCEPTION phrase is not performed.
RELATED TASKS
Enterprise COBOL Migration Guide
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, ON SIZE ERROR phrase, or other
language constructs. But if an extraordinary condition such as a machine check
occurs, usually your application is abnormally terminated.
256
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
Enterprise COBOL and Language Environment provide a way for a user-written
program to gain control when such conditions occur. Using Language Environment
condition handling, you can write your own error-handling routines in COBOL.
They can report, analyze, or even fix up a program and enable it to resume
running.
|
|
|
When you write your own error-handling routines for an application, the COBOL
programs must be compiled with appropriate compiler options. For more
information, see “OPTIMIZE” on page 351.
To have Language Environment pass control to a user-written error program, you
must first identify and register its entry point to Language Environment.
PROCEDURE-POINTER data items enable you to pass the entry address of procedure
entry points to Language Environment services.
RELATED TASKS
“Using procedure and function pointers” on page 476
|
|
RELATED REFERENCES
“OPTIMIZE” on page 351
Chapter 13. Handling errors
257
258
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
Part 2. Compiling and debugging your program
© Copyright IBM Corp. 1991, 2013
259
260
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 14. Compiling under z/OS
You can compile Enterprise COBOL programs under z/OS using job control
language (JCL), TSO commands, CLISTs, or ISPF panels.
About this task
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.
When compiling under TSO, you can use TSO commands, CLISTs, or ISPF panels.
You can also compile in a z/OS UNIX shell by using the cob2 command.
You might instead want to start the Enterprise COBOL compiler from an assembler
program, for example, if your shop has developed a tool or interface that calls the
Enterprise COBOL compiler.
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
required 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 269
Chapter 15, “Compiling under z/OS UNIX,” on page 291
“Starting the compiler from an assembler program” on page 271
“Defining compiler input and output” on page 273
“Specifying compiler options under z/OS” on page 279
“Compiling multiple programs (batch compilation)” on page 282
“Correcting errors in your source program” on page 286
RELATED REFERENCES
Chapter 18, “Compiler-directing statements,” on page 375
“Data sets used by the compiler under z/OS” on page 273
“Compiler options and compiler output under z/OS” on page 281
Compiling with JCL
Include the following information in the JCL for compilation: job description,
statement to invoke the compiler, and definitions of the needed data sets
(including the directory paths of z/OS UNIX files, if any).
© Copyright IBM Corp. 1991, 2013
261
About this task
The simplest way to compile your program under z/OS is to code JCL that uses a
cataloged procedure. A cataloged procedure is a set of job control statements 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 a procedural DLL application” on page 500
RELATED TASKS
“Using a cataloged procedure”
“Writing JCL to compile programs” on page 267
“Specifying compiler options under z/OS” on page 279
“Specifying compiler options in a batch compilation” on page 284
“Compiling programs to create DLLs” on page 498
RELATED REFERENCES
“Data sets used by the compiler under z/OS” on page 273
Using a cataloged procedure
Specify a cataloged procedure in an EXEC statement in your JCL.
About this task
For example, the following JCL calls the IBM-supplied cataloged procedure
IGYWC for compiling an Enterprise COBOL program and defining the required
data sets:
//JOB1
JOB1
//STEPA
EXEC PROC=IGYWC
//COBOL.SYSIN DD *
000100 IDENTIFICATION DIVISION
* (the source code)
. . .
/*
You can omit /* after the source code. If your source code is stored in a data set,
replace SYSIN DD * with appropriate parameters that describe the data set.
You can use these procedures with any of the job schedulers that are part of z/OS.
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 required options.
262
Enterprise COBOL for z/OS, V5.1 Programming Guide
You can specify data sets to be in the z/OS UNIX 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.
Additional details about 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 264
“Compile, link-edit, and run procedure (IGYWCLG)” on page 265
MVS Program Management: User's Guide and Reference
Compile procedure (IGYWC)
IGYWC is a single-step cataloged 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)
If you use copybooks in the program that you are compiling, you must also supply
a DD statement for SYSLIB or other libraries that you specify in COPY statements. For
example:
//COBOL.SYSLIB
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
DD
DISP=SHR,DSN=DEPT88.BOBS.COBLIB
//IGYWC PROC LNGPRFX=’IGY.V5R1M0’,
//
LIBPREFIX=’CEE’
//*
//* COMPILE A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//* LNGPRFX IGY.V5R1M0
PREFIX FOR LANGUAGE DATA SET NAMES
//* LIBPRFX CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//* CALLER MUST ALSO SUPPLY //COBOL.SYSLIB DD . . . for COPY statements
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=0M
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,DISP=SHR
(1)
//
DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
//
DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSNAME=&&LOADSET,UNIT=SYSALLDA,
//
DISP=(MOD,PASS),SPACE=(CYL,(1,1)),
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT8 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
Chapter 14. Compiling under z/OS
263
(1)
STEPLIB can be installation-dependent.
“Example: JCL for compiling in the z/OS UNIX file system”
Example: JCL for compiling in the z/OS UNIX file system:
The following job uses procedure IGYWC to compile a COBOL program, demo.cbl,
that is located in the z/OS UNIX file system. The job writes the generated
compiler listing demo.lst, object file demo.o, and SYSADATA file demo.adt in the
z/OS UNIX file system.
//UNIXDEMO 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’
//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
//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
(1)
PATH specifies the path name of a file in the z/OS UNIX file system.
(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 as binary.
You can use a mixture of files in the z/OS UNIX file system (PATH=’unix-directorypath’) and traditional MVS data sets (DSN=mvs-data-set-name) in 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.
RELATED REFERENCES
“Data sets used by the compiler under z/OS” on page 273
UNIX System Services Command Reference
MVS JCL Reference
Compile and link-edit procedure (IGYWCL)
IGYWCL is a two-step cataloged procedure to compile and link-edit a program.
The COBOL job step produces an object module that is input to the linkage editor
or binder. You can add other object modules. You must supply the following DD
statement, indicating the location of the source program, in the input stream:
//COBOL.SYSIN DD
*
(or appropriate parameters)
If the program uses copybooks, you must also supply a DD statement for SYSLIB or
other libraries that you specify in COPY statements. For example:
264
Enterprise COBOL for z/OS, V5.1 Programming Guide
//COBOL.SYSLIB
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
DD
DISP=SHR,DSN=DEPT88.BOBS.COBLIB
//IGYWCL PROC LNGPRFX=’IGY.V5R1M0’,
//
LIBPRFX=’CEE’,
//
PGMLIB=’&&GOSET’,GOPGM=GO
//*
//* COMPILE AND LINK EDIT A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX
IGY.V5R1M0
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 . . .
//*
//* CALLER MUST ALSO SUPPLY //COBOL.SYSLIB DD . . . for COPY statements
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=0M
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,DISP=SHR
(1)
//
DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
//
DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSALLDA,
//
DISP=(MOD,PASS),SPACE=(CYL,(1,1)),
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT8
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//LKED
EXEC PGM=IEWBLINK,COND=(8,LT,COBOL),REGION=0M
//SYSLIB
DD DSNAME=&LIBPRFX..SCEELKED,DISP=SHR
(2)
//
DD DSNAME=&LIBPRFX..SCEELKEX,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&PGMLIB(&GOPGM),
//
SPACE=(CYL,(3,1,1)),
//
UNIT=SYSALLDA,DISP=(MOD,PASS),DSNTYPE=LIBRARY
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
(1)
STEPLIB can be installation-dependent.
(2)
SYSLIB can be installation-dependent.
Compile, link-edit, and run procedure (IGYWCLG)
IGYWCLG is a three-step cataloged procedure to compile, link-edit, and run a
program.
The COBOL job step produces an object module that is input to the linkage editor
or binder. You can add other object modules. If the COBOL program refers to any
data sets, you must also supply DD statements that define these data sets. You must
supply the following DD statement, indicating the location of the source program,
in the input stream:
Chapter 14. Compiling under z/OS
265
//COBOL.SYSIN DD
*
(or appropriate parameters)
If the program uses copybooks, you must also supply a DD statement for SYSLIB or
other libraries that you specify in COPY statements. For example:
//COBOL.SYSLIB
DD
DISP=SHR,DSN=DEPT88.BOBS.COBLIB
//IGYWCLG PROC LNGPRFX=’IGY.V5R1M0’,
//
LIBPRFX=’CEE’,GOPGM=GO
//*
//* COMPILE, LINK EDIT AND RUN A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE
USAGE
//*
LNGPRFX
IGY.V5R1M0
PREFIX FOR LANGUAGE DATA SET NAMES
//*
LIBPRFX
CEE
PREFIX FOR LIBRARY DATA SET NAMES
//*
GOPGM
GO
MEMBER NAME FOR LOAD MODULE
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//* CALLER MUST ALSO SUPPLY //COBOL.SYSLIB DD . . . for COPY statements
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=0M
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,DISP=SHR
(1)
//
DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
//
DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,UNIT=SYSALLDA,
//
DISP=(MOD,PASS),SPACE=(CYL,(1,1)),
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT8
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//LKED
EXEC PGM=IEWBLINK,COND=(8,LT,COBOL),REGION=0M
//SYSLIB
DD DSNAME=&LIBPRFX..SCEELKED,DISP=SHR
(2)
//SYSPRINT DD SYSOUT=*
//SYSLIN
DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
//
DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&&GOSET(&GOPGM),SPACE=(CYL,(1,1,1)),
//
UNIT=SYSALLDA,DISP=(MOD,PASS),DSNTYPPE=LIBRARY
//SYSUT1
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//GO
EXEC PGM=*.LKED.SYSLMOD,COND=((8,LT,COBOL),(4,LT,LKED)),
//
REGION=0M
//STEPLIB DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
(1)
//
DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
266
(1)
STEPLIB can be installation-dependent.
(2)
SYSLIB can be installation-dependent.
Enterprise COBOL for z/OS, V5.1 Programming Guide
Writing JCL to compile programs
If the cataloged procedures do not provide you with the flexibility that you need
for more complex programs, write your own job control statements. The following
example shows the general format of JCL used to compile a program.
About this task
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//jobname
//stepname
//STEPLIB
//
//
//SYSUT1
//SYSUT2
//SYSUT3
//SYSUT4
//SYSUT5
//SYSUT6
//SYSUT7
//SYSUT8
//SYSUT9
//SYSUT10
//SYSUT11
//SYSUT12
//SYSUT13
//SYSUT14
//SYSUT15
//SYSMDECK
//SYSPRINT
//SYSLIN
//
//SYSIN
JOB acctno,name,MSGCLASS=1
EXEC PGM=IGYCRCTL,PARM=(options)
DD
DSNAME=IGY.V5R1M0.SIGYCOMP,DISP=SHR
DD
DSNAME=SYS1.SCEERUN,DISP=SHR
DD
DSNAME=SYS1.SCEERUN2,DISP=SHR
DD
UNIT=SYSALLDA,SPACE=(subparms)
DD
UNIT=SYSALLDA,SPACE=(subparms)
DD
UNIT=SYSALLDA,SPACE=(subparms)
DD
UNIT=SYSALLDA,SPACE=(subparms)
DD
UNIT=SYSALLDA,SPACE=(subparms)
DD
UNIT=SYSALLDA,SPACE=(subparms)
DD
UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE)=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD UNIT=SYSALLDA,SPACE=(subparms)
DD
SYSOUT=A
DD
DSNAME=MYPROG,UNIT=SYSALLDA,
DISP=(MOD,PASS),SPACE=(subparms)
DD
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 Enterprise COBOL compiler
(IGYCRCTL) is to be invoked.
(3)
This DD statement defines the data set where the Enterprise COBOL
compiler resides.
The Language Environment SCEERUN and SCEERUN2 data sets must be
included in the concatenation (together with the compiler SIGYCOMP data
set), unless the Language Environment data sets are available in the
LNKLST.
|
|
|
|
(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.
(5)
The SYSPRINT DD statement defines the data set that receives output from
compiler 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 (the object module) that
receives output from the OBJECT compiler option.
(7)
The SYSIN DD statement defines the data set (source code) to be used as
input to the job step.
You can use a mixture of files in the z/OS UNIX file system (PATH=’unix-directorypath’) and traditional MVS data sets (DSN=mvs-data-set-name) in the compilation DD
statements for the following data sets:
Chapter 14. Compiling under z/OS
267
v
v
v
v
v
Sources files
Object files
Listings
ADATA files
Debug files
v Executable modules
However, the compiler utility files (DD statements SYSUTx) and COPY libraries (DD
statement SYSLIB) must be MVS data sets.
“Example: user-written JCL for compiling”
“Example: sample JCL for a procedural DLL application” on page 500
RELATED REFERENCES
MVS Program Management: User's Guide and Reference
Example: user-written JCL for compiling
The following example shows a few possibilities for adapting the basic JCL.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//JOB1
JOB
(1)
//STEP1
EXEC PGM=IGYCRCTL,PARM=’OBJECT’
(2)
//STEPLIB DD
DSNAME=IGY.V5R1M0.SIGYCOMP,DISP=SHR
//
DD
DSNAME=SYS1.SCEERUN,DISP=SHR
//
DD
DSNAME=SYS1.SCEERUN2,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))
//SYSUT8
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,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)
268
(1)
JOB1 is the name of the job.
(2)
STEP1 is the name of the sole job step in the job. The EXEC statement also
specifies that the generated object code should be placed on disk or tape
(to be used as input to the link step).
(3)
The asterisk indicates that the input data set follows in the input stream.
(4)
The delimiter statement /* separates data from subsequent control
statements in the input stream.
Enterprise COBOL for z/OS, V5.1 Programming Guide
Compiling under TSO
Under TSO, you can use TSO commands, command lists (CLISTs), REXX execs, or
ISPF to compile programs using traditional MVS data sets. You can use TSO
commands or REXX execs to compile programs using z/OS UNIX files.
About this task
With each method, you need to allocate the data sets and request the compilation:
Procedure
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, you must allocate other data sets. For
example, if you specify the TERMINAL compiler option, you must allocate the
SYSTERM data set to receive compiler messages at your terminal.
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 at the READY prompt to request compilation:
CALL ’IGY.V5R1M0.SIGYCOMP(IGYCRCTL)’
Results
You can specify the ALLOCATE and CALL commands on the TSO command line, or, if
you are not using z/OS UNIX files, you can include them in a CLIST.
You can allocate z/OS UNIX files for all the compiler data sets except the SYSUTx
utility data sets and the SYSLIB libraries. 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 270
RELATED REFERENCES
“Data sets used by the compiler under z/OS” on page 273
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
[READY]
ALLOCATE
[READY]
ALLOCATE
[READY]
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)
FILE(SYSUT7) CYLINDERS SPACE(1 1)
FILE(SYSUT8) CYLINDERS SPACE(1 1)
Chapter 14. Compiling under z/OS
269
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ALLOCATE FILE(SYSUT9) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT10) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT11) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT12) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT13) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT14) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT15) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSMDECK) 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.V5R1M0.SIGYCOMP(IGYCRCTL)’ ’LIST,NOCOMPILE(S),OBJECT,FLAG(E,E),TERMINAL’
.
(COBOL listings and messages)
.
[READY]
FREE FILE(SYSUT1,SYSUT2,SYSUT3,SYSUT4,SYSUT5,SYSUT6,SYSUT7,SYSUT8,SYSUT9,SYSUT10,SYSUT11,SYSUT12,
SYSUT13,SYSUT14,SYSUT15,SYSMDECK,SYSPRINT,SYSTERM,+
SYSIN,SYSLIN)
[READY]
Example: CLIST for compiling under TSO
The following example shows a CLIST for compiling under TSO. The FREE
commands are not required. However, good programming practice dictates that
you free files before you allocate them.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PROC 1 MEM
CONTROL LIST
FREE F(SYSUT1)
FREE F(SYSUT2)
FREE F(SYSUT3)
FREE F(SYSUT4)
FREE F(SYSUT5)
FREE F(SYSUT6)
FREE F(SYSUT7)
FREE F(SYSUT8)
FREE F(SYSUT9)
FREE F(SYSUT10)
FREE F(SYSUT11)
FREE F(SYSUT12)
FREE F(SYSUT13)
FREE F(SYSUT14)
FREE F(SYSUT15)
FREE F(SYSMDECK)
FREE F(SYSPRINT)
FREE F(SYSIN)
FREE F(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(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT2) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT3) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT4) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT5) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT6) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT7) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT8) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
270
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
|
|
|
|
|
|
ALLOC F(SYSUT9) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT10) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT11) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT12) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT13) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT14) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT15) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSMDECK) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
CALL ’IGY.V5R1M0.SIGYCOMP(IGYCRCTL)’
RELATED REFERENCES
TSO/E Command Reference
Starting the compiler from an assembler program
You can start the Enterprise COBOL compiler from within an assembler program
by using the ATTACH or the LINK macro by dynamic invocation. You must identify
the compiler options and the ddnames of the data sets to be used during
processing.
About this task
For example:
symbol {LINK|ATTACH} EP=IGYCRCTL,PARAM=(optionlist[,ddnamelist]),VL=1
EP
Specifies the symbolic name of the 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 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 that contains the COBOL
options specified for compilation. This address must be written even if no
list is provided.
The optionlist must begin on a halfword boundary. The 2 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 freeform,
with each field separated from the next by a comma. No blanks or zeros
should appear. The compiler recognizes only the first 100 characters.
ddnamelist
Specifies the address of a variable-length list that contains alternative
ddnames for the data sets used during compiler processing. If standard
ddnames are used, the ddnamelist can be omitted.
The ddnamelist must begin on a halfword boundary. The 2 high-order bytes
contain a count of the number of bytes in the remainder of the list. Each
name of less than 8 bytes must be left justified and padded with blanks. If
an alternate ddname is omitted from the list, the standard name is
assumed. If the name is omitted, the 8-byte entry must contain binary
zeros. You can omit names from the end by shortening the list.
Chapter 14. Compiling under z/OS
271
All SYSUTn data sets specified must be on direct-access storage devices
and have physical sequential organization. They must not reside in the
z/OS UNIX file system.
The following table shows the sequence of the 8-byte entries in the
ddnamelist.
Alternative ddname 8-byte entry
Name for which alternative ddname is substituted
1
SYSLIN
2
Not applicable
3
Not applicable
4
SYSLIB
5
SYSIN
6
SYSPRINT
7
SYSPUNCH
8
SYSUT1
9
SYSUT2
10
SYSUT3
11
SYSUT4
12
SYSTERM
13
SYSUT5
14
SYSUT6
15
SYSUT7
16
SYSADATA
17
SYSJAVA
18
Not applicable
19
SYSMDECK
|
20
DBRMLIB
|
21
SYSOPTF
|
22
SYSUT8
|
23
SYSUT9
|
24
SYSUT10
|
25
SYSUT11
|
26
SYSUT12
|
27
SYSUT13
|
28
SYSUT14
|
29
SYSUT15
|
VL
Specifies that the sign bit is to be set to 1 in the last fullword of the
address parameter list.
When the compiler completes processing, it puts a return code in register 15.
RELATED TASKS
“Defining compiler input and output” on page 273
272
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
“Data sets used by the compiler under z/OS”
“Compiler options and compiler output under z/OS” on page 281
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.
About this task
RELATED TASKS
“Defining the source code data set (SYSIN)” on page 275
“Defining a compiler-option data set (SYSOPTF)” on page 276
“Specifying source libraries (SYSLIB)” on page 276
“Defining the output data set (SYSPRINT)” on page 277
“Directing compiler messages to your terminal (SYSTERM)” on page 277
“Creating object code (SYSLIN or SYSPUNCH)” on page 277
“Defining an associated-data file (SYSADATA)” on page 278
“Defining the Java-source output file (SYSJAVA)” on page 278
“Defining the library-processing output file (SYSMDECK)” on page 278
RELATED REFERENCES
“Data sets used by the compiler under z/OS”
“Compiler options and compiler output under z/OS” on page 281
Data sets used by the compiler under z/OS
The following table lists the function, device requirements, and allowable device
classes for each data set that the compiler uses.
Table 34. Compiler data sets
Allowable
Device
device
requirements classes
Can be in
z/OS UNIX
file
system?
Type
ddname
Function
Required?
Input
SYSIN1
Reading source
program
Yes
Card reader;
intermediate
storage
SYSOPTF
Reading compiler
options
If OPTFILE is in effect
Card reader; Any
intermediate
storage; direct
access
Yes
SYSLIB or
other copy
libraries1
Reading user source
libraries (PDSs or
PDSEs)
If program has COPY or
BASIS statements
Direct access
No
Any
SYSDA
Yes
Chapter 14. Compiling under z/OS
273
Table 34. Compiler data sets (continued)
Type
ddname
Function
Required?
Utility
SYSUT1,
SYSUT2,
SYSUT3,
SYSUT4,
SYSUT62
Work data set used
by compiler during
compilation
Yes
Direct access
SYSALLDA
No
SYSUT52
Work data set used
by compiler during
compilation
If program has COPY,
REPLACE, or BASIS
statements
Direct access
SYSALLDA
No
SYSUT72
Work data set used
Yes
by compiler to create
listing
Direct access
SYSALLDA
No
SYSUT8,
SYSUT9,
SYSUT10,
SYSUT11,
SYSUT12,
SYSUT13,
SYSUT14,
SYSUT15,
Work data set used
by compiler during
compilation
Yes
Direct access
SYSALLDA
No
SYSPRINT1
Writing storage map, Yes
listings, and
messages
Printer;
intermediate
storage
SYSSQ, SYSDA,
standard
output class
A
Yes
SYSTERM
Writing progress and If TERM is in effect
diagnostic messages
Output
device; TSO
terminal
SYSPUNCH
Creating object code
Card punch;
direct access
SYSSQ, SYSDA
Yes
SYSLIN
Creating object
If OBJECT is in effect
module data set as
output from compiler
and input to linkage
editor or binder
Direct access
SYSSQ, SYSDA
Yes
SYSADATA1
Writing associated
data file records
If ADATA is in effect
Output
device
Yes
SYSJAVA
Creating generated
Java source file for a
class definition
If compiling a class
definition
(Must be a
z/OS UNIX
file)
Yes
If DUMP is in effect
(should be rarely used)
Direct access
SYSDA
Yes
Yes
Direct access
SYSALLDA
Yes
|
|
|
|
|
|
|
|
|
|
|
|
Can be in
z/OS UNIX
file
system?
Allowable
Device
device
requirements classes
Output
2
SYSUDUMP,
Writing dump
SYSABEND, or
SYSMDUMP
|
|
|
|
SYSMDECK
Processing for the
MDECK option, or a
work data set if
NOMDECK is specified.
If DECK is in effect
1. You can use the EXIT option to provide user exits from these data sets.
2. These data sets must be single volume.
274
Enterprise COBOL for z/OS, V5.1 Programming Guide
Yes
RELATED REFERENCES
“Logical record length and block size”
“EXIT” on page 332
Logical record length and block size
For compiler data sets other than the work data sets (SYSUTn) and z/OS UNIX
files, you can set the block size by 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.
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
theSYSPRINT data set. You can specify BLKSIZE=0, which results in a
system-determined block size.
Table 35. Block size of fixed-length compiler data sets
Data set
RECFM
LRECL (bytes)
BLKSIZE1
SYSIN
F or FB
80
80 x n
SYSLIB or other copy libraries
F or FB
80
80 x n
SYSLIN
F or FB
80
80 x n
SYSMDECK
F or FB
80
80 x n
SYSOPTF
F or FB
80
80 x n
F or FB
133
133 x n
SYSPUNCH
F or FB
80
80 x n
SYSTERM
F or FB
80
80 x n
SYSPRINT
2
1. n = blocking factor
2. If you specify BLKSIZE=0, the system determines the block size.
For variable-length records (RECFM=V), LRECL is the logical record length, and
BLKSIZE equals LRECL plus 4.
Table 36. Block size of variable-length compiler data sets
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 by using the SYSIN DD statement
as shown below.
About this task
//SYSIN
DD
DSNAME=dsname,UNIT=SYSSQ,VOLUME=(subparms),DISP=SHR
You can place your source code or BASIS statement directly in the input stream. To
do so, use this SYSIN DD statement:
//SYSIN
DD
*
Chapter 14. Compiling under z/OS
275
The source code or BASIS statement must follow theDD * statement. If another job
step follows the compilation, the EXEC statement for that step must follow the /*
statement or the last source statement.
Defining a compiler-option data set (SYSOPTF)
Define a data set that contains the compiler options for your COBOL program by
coding the SYSOPTF DD statement as shown below.
About this task
//SYSOPTF
DD
DSNAME=dsname,UNIT=SYSDA,VOLUME=(subparms),DISP=SHR
To use a compiler-option data set, specify OPTFILE either as a compiler invocation
option or in a PROCESS or CBL statement in your source program.
Within the SYSOPTF data set:
v Specify compiler options in free form between columns 2 and 72, using the same
syntax as you use for invocation options or for compiler options in a PROCESS or
CBL statement.
v Code an asterisk (*) in column 1 to cause a line to be treated as a comment.
v Optionally code sequence numbers in columns 73 through 80; those columns are
ignored.
You can optionally place the compiler options directly in the input stream after the
SYSOPTF DD statement if you compile using the OPTFILE option:
//COB
EXEC PGM=IGYCRCTL,PARM=’OPTFILE’
//SYSOPTF DD DATA,DLM=@@
SSRANGE
ARITH(COMPAT)
OPTIMIZE
. . .
@@
//SYSIN
DD . . .
You can concatenate multiple SYSOPTF DD statements if you have multiple
compiler-option data sets:
//SYSOPTF DD DSNAME=dsname1, . . .
//
DD DSNAME=dsname2, . . .
Compiler options that are in later data sets in the concatenation take precedence
over options in earlier data sets in the concatenation.
RELATED REFERENCES
“Logical record length and block size” on page 275
“OPTFILE” on page 350
Specifying source libraries (SYSLIB)
Use 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 BASIS statements in the
input stream.
About this task
//SYSLIB
DD
DSNAME=copylibname,DISP=SHR
Concatenate multiple DD statements if you have multiple copy or basis libraries:
276
Enterprise COBOL for z/OS, V5.1 Programming Guide
//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 z/OS UNIX
file system when you compile with 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 ddname SYSPRINT to produce a listing. The listing includes the results
of the default or requested options of the PARM parameter (that is, diagnostic
messages and the object-code listing).
About this task
You can direct the output to a SYSOUT data set, a printer, a direct-access storage
device, or a magnetic-tape device. For example:
//SYSPRINT DD SYSOUT=A
The SYSPRINT data set can be a sequential data set, a PDS or PDSE member, or a
z/OS UNIX file. For details about how to specify the record format, record length,
and block size of the SYSPRINT data set, see the related reference below.
RELATED REFERENCES
“Logical record length and block size” on page 275
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.
About this task
ALLOC F(SYSTERM) DA(*)
You can define SYSTERM in various other ways, for example to a SYSOUT data set,
a data set on disk, a file in the z/OS UNIX file system, 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 a z/OS UNIX file, or on tape. The compiler uses the
file that you define in the SYSLIN or SYSPUNCH DD statement.
About this task
//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
v
v
v
Passed to the linkage editor or binder
Cataloged
Kept
Added to an existing cataloged library
Chapter 14. Compiling under z/OS
277
In the example above, the data is created and passed to another job step, the
linkage editor or binder job step.
Your installation might use the DECK option and the SYSPUNCH DD statement. B is the
standard output class for punch data sets:
//SYSPUNCH DD
SYSOUT=B
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 348
“DECK” on page 328
Defining an associated-data file (SYSADATA)
Define a SYSADATA file if you use the ADATA compiler option.
About this task
//SYSADATA DD DSNAME=dsname,UNIT=SYSDA
The SYSADATA file will be a sequential file that contains specific record types that
have information about the program that is collected during compilation. The file
can be a traditional MVS data set or a z/OS UNIX file.
RELATED REFERENCES
“ADATA” on page 315
Defining the Java-source output file (SYSJAVA)
Add the SYSJAVA DD statement if you are compiling an OO program. The generated
Java source file is written to the SYSJAVA ddname.
About this task
//SYSJAVA
DD PATH=’/u/userid/java/Classname.java’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU,
// FILEDATA=TEXT
The SYSJAVA file must be in the z/OS UNIX file system.
RELATED TASKS
“Compiling OO applications in JCL or TSO/E” on page 304
Defining the library-processing output file (SYSMDECK)
The SYSMDECK data set is required for all compilations. If you specify the MDECK
compiler option, the SYSMDECK DD allocation must specify a permanent data set.
However, if you use the NOMDECK option, SYSMDECK can be specified as a utility
(temporary) data set.
|
|
|
|
About this task
//SYSMDECK DD DSNAME=dsname,UNIT=SYSDA
278
Enterprise COBOL for z/OS, V5.1 Programming Guide
The SYSMDECK file will contain a copy of the updated input source after library
processing, that is, the result of COPY, BASIS, REPLACE, and EXEC SQL INCLUDE
statements. The file can be a traditional MVS data set or a z/OS UNIX file.
RELATED REFERENCES
“MDECK” on page 344
Specifying compiler options under z/OS
The compiler is installed with default compiler options. While installing the
compiler, the system programmer can fix compiler option settings to, for example,
ensure better performance or maintain certain standards. You cannot override any
compiler options that are fixed.
About this task
For options that are not fixed, you can override the default settings by specifying
compiler options in any of these ways:
v Code them on the PROCESS or CBL statement in COBOL source.
v Include them when you start the compiler, either on the PARM parameter on the
EXEC statement in the JCL or on the command line under TSO.
v Include them in a SYSOPTF data set, and specify the OPTFILE compiler option in
either of the above ways.
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, 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.
The precedence of options in a SYSOPTF data set depends on where you specify the
OPTFILE compiler option. For example, if you specify OPTFILE in a PROCESS
statement, the SYSOPTF options supersede the options that you specify in the
compiler invocation. For further details, see the related reference below about the
OPTFILE option.
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, 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 281
“Example: specifying compiler options under TSO” on page 281
Chapter 14. Compiling under z/OS
279
RELATED TASKS
“Defining a compiler-option data set (SYSOPTF)” on page 276
“Specifying compiler options in the PROCESS (CBL) statement”
“Specifying compiler options in a batch compilation” on page 284
RELATED REFERENCES
“Compiler options and compiler output under z/OS” on page 281
Chapter 17, “Compiler options,” on page 311
“Conflicting compiler options” on page 314
“OPTFILE” on page 350
Specifying compiler options in the PROCESS (CBL) statement
Within a COBOL program, you can code most compiler options in PROCESS (CBL)
statements. Code the statements before the IDENTIFICATION DIVISION header and
before any comment lines or compiler-directing statements.
About this task
CBL/PROCESS statement syntax
CBL
PROCESS
options-list
If you do not use a sequence field, you can start a PROCESS statement in column 1
or after. If you use a sequence field, the sequence number must start in column 1
and must contain six characters; the first character must be numeric. If used with a
sequence field, PROCESS can start in column 8 or after.
You can use CBL as a synonym for PROCESS. CBL can likewise start in column 1 or
after if you do not use a sequence field. If used with a sequence field, CBL can start
in column 8 or after.
You must end PROCESS and CBL statements at or before column 72.
Use one or more blanks to separate a PROCESS or CBL statement 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 code more than one PROCESS or CBL statement. If you do so, the statements
must follow one another with no intervening statements. You cannot continue
options across multiple PROCESS or CBL statements.
Your programming organization can inhibit the use of PROCESS (CBL) statements by
using the default options module of the COBOL compiler. If PROCESS or CBL
statements that are not allowed by the organization are found in a COBOL
program, the COBOL compiler generates error diagnostics.
RELATED REFERENCES
Reference format (Enterprise COBOL Language Reference)
CBL (PROCESS) statement (Enterprise COBOL Language Reference)
280
Enterprise COBOL for z/OS, V5.1 Programming Guide
Example: specifying compiler options using JCL
The following example shows how to specify compiler options under z/OS 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 z/OS
When the compiler finishes processing your source program, it will have produced
one or more outputs, depending on the compiler options that were in effect.
Table 37. Types of compiler output under z/OS
Compiler option
Compiler output
Type of output
ADATA
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 used rarely
Listing
EXPORTALL
Exported symbols for a DLL
Object
FLAG
List of errors that the compiler found in your program
Listing
LIST
Listing of object code in machine and assembler
language
Listing
MAP
Map of the data items in your program
Listing
MDECK
Expansion of library-processing statements in your
program
Library-processing side file
NUMBER
User-supplied line numbers shown in listing
Listing
OBJECT or DECK with COMPILE Your object code
OFFSET
|
Object
Map of the relative addresses in your object code
OPTIMIZE(1) or OPTIMIZE(2) Optimized object code
Listing
Object
RENT
Reentrant object code
Object
SOURCE
Listing of your source program
Listing
SQL
SQL statements and host variable information for DB2
bind process
Database request module
(DBRM)
SSRANGE
Extra code for checking references within tables
In object
TERMINAL
Progress and diagnostic messages sent to terminal
Terminal
|
|
TEST
DWARF format debugging information in the object
module, to enable interactive debugging
Object
|
|
NOTEST(DWARF)
Basic DWARF format diagnostic information, to enable
application failure analysis tools
Object
VBREF
Cross-reference listing of verbs in your source program
Listing
XREF
Sorted cross-reference listing of names of procedures,
programs, and data
Listing
Chapter 14. Compiling under z/OS
281
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 and included in the SYSPRINT data set. The
database request module (DBRM) is the data set defined in DBRMLIB.
Save the listings you produced during compilation. You can use them during the
testing of your work if you need to debug or tune. You might also use the listings
for diagnosis and debugging after the application is in production.
|
|
After compilation, fix any errors that the compiler found in your program. If no
errors were 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 object code.)
RELATED TASKS
Language Environment Programming Guide (Preparing to link-edit and run)
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 287
Chapter 17, “Compiler options,” on page 311
Compiling multiple programs (batch compilation)
You can compile a sequence of separate COBOL programs by using 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.
About this task
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
compiler option. When the compiler encounters the NAME option, the first program
in the sequence and all subsequent programs until the next NAME compiler option is
encountered are link-edited into a single load module. Then each successive
program that is compiled with the NAME option is included in a separate load
module.
Use the END PROGRAM marker to terminate each program in the sequence except the
last program in the batch (for which the END PROGRAM marker is optional).
Alternatively, you can precede each program in the sequence with a CBL or PROCESS
statement.
If you omit the END PROGRAM marker 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).
282
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 284
RELATED REFERENCES
“NAME” on page 345
Example: batch compilation
The following example shows a batch compilation for three programs (PROG1,
PROG2, and PROG3) and the creation of two load modules using one invocation of
the IGYWCL cataloged procedure.
The following steps occur:
v PROG1 and PROG2 are link-edited together to form one load module that has the
name PROG2. The entry point of this load module defaults to the first program in
the load module, PROG1.
v PROG3 is link-edited by itself into a load module that has 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)
(4)
(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 Language Environment library does
not reside in shared storage, you must also add the library data set as a DD
statement for STEPLIB.
Chapter 14. Compiling under z/OS
283
(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
Language Environment Programming Guide (IBM-supplied cataloged procedures)
Specifying compiler options in a batch compilation
You can specify compiler options for each program in the batch sequence either
with a CBL or PROCESS statement that precedes the program, or upon invocation of
the compiler.
About this task
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.
You should be aware of the effect of certain compiler options on the precedence of
compiler option settings for each program in the batch sequence. Compiler options
are recognized in the following order of precedence, from highest to lowest:
1. Installation defaults that are fixed at your site
2. Values of the BUFSIZE, , 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 in the compiler invocation (JCL PARM or TSO CALL)
5. Installation defaults that are not fixed
If any program in the batch sequence requires the BUF, , 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 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 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 285
Example: precedence of options in a batch compilation
The following example listing shows the precedence of compiler options for batch
compilation.
284
Enterprise COBOL for z/OS, V5.1 Programming Guide
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.0
Date 03/30/2013. . .
Invocation parameters:
NOTERM
PROCESS(CBL) statements:
CBL CURRENCY,FLAG(I,I)
Options in effect: All options are installation defaults unless otherwise noted:
NOADATA
ADV
QUOTE
ARITH(COMPAT)
NOAWO
NOBLOCK0
BUFSIZE(4096)
. . .
CURRENCY
Process option PROGRAM 1
. . .
FLAG(I,I)
Process option PROGRAM 1
. . .
NOTERM
INVOCATION option
. . .
End of compilation for program 1
. . .
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.0
Date 03/30/2013. . .
PROCESS(CBL) statements:
CBL APOST
Options in effect:
NOADATA
ADV
APOST
Process option PROGRAM 2
ARITH(COMPAT)
NOAWO
NOBLOCK0
BUFSIZE(4096)
. . .
NOCURRENCY
Installation default option for PROGRAM 2
. . .
FLAG(I)
Installation default option
. . .
NOTERM
INVOCATION option remains in effect
. . .
End of compilation for 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 EN), and
the invocation option is XX, a nonexistent language.
|
CBL LANG(JP),FLAG(I,I),APOST,SIZE(5000000) (1)
IDENTIFICATION DIVISION.
(2)
PROGRAM-ID. COMPILE1.
. . .
END PROGRAM COMPILE1.
CBL LANGUAGE(YY)
(3)
CBL LANGUAGE(JP),LANG(!!)
(4)
IDENTIFICATION DIVISION.
(2)
PROGRAM-ID. COMPILE2.
. . .
END PROGRAM COMPILE2.
IDENTIFICATION DIVISION.
PROGRAM-ID. COMPILE3.
. . .
END PROGRAM COMPILE3.
CBL LANGUAGE(JP),LANGUAGE(YY)
(5)
. . .
(1)
The installation default is EN. The invocation option was XX, a nonexistent
language. EN is the language in effect.
Chapter 14. Compiling under z/OS
285
(2)
After the CBL statement is scanned, JP is the language in effect.
(3)
CBL resets the language to EN. YY is ignored because it is superseded by JP.
(4)
!! is not alphanumeric and is discarded.
(5)
CBL resets the language to EN. 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).
Therefore Japanese becomes the language in effect when the compiler finishes
processing the CBL options. If you want diagnostics in Japanese for the options in
the CBL and PROCESS statements, the language in effect before COMPILE1 must be
Japanese.
The program COMPILE3 has no CBL statement. 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, 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 occurred (LINEID). The
text of a message tells you what the problem is. With this information, you can
correct the source program.
About this task
Although you should try to correct errors, it is not always necessary to correct
source code for every diagnostic message. You can leave a warning-level or
informational-level message in a program without much risk, and you might
decide that the recoding and compilation that are needed to remove the message
are not worth the effort. Severe-level and error-level errors, however, indicate
probable program failure and should be corrected.
In contrast with the four lower levels of severities, an unrecoverable (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 such cases, the problem must
be resolved, because the compiler is forced to end early and does not produce
complete object code or a complete listing. If the message occurs for a program
that has many S-level syntax errors, correct those errors and compile the program
again. You can also resolve job set-up problems (such as missing data-set
definitions or insufficient storage for compiler processing) by making changes to
286
Enterprise COBOL for z/OS, V5.1 Programming Guide
the compile job. If your compile job setup is correct and you have corrected the
S-level syntax errors, you need to contact IBM to investigate other U-level errors.
After correcting the errors in your source program, recompile the program. If this
second compilation is successful, proceed 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 messages”
RELATED REFERENCES
“Messages and listings for compiler-detected errors”
Generating a list of compiler messages
You can generate a complete listing of compiler diagnostic messages with their
message numbers, severities, and text by compiling a program that has
program-name ERRMSG.
About this task
You can code just the PROGRAM-ID paragraph, as shown below, and omit the rest of
the program.
Identification Division.
Program-ID. ErrMsg.
RELATED TASKS
“Customizing compiler-message severities” on page 706
RELATED REFERENCES
“Messages and listings for compiler-detected errors”
“Format of compiler diagnostic messages” on page 288
Messages and listings for compiler-detected errors
As the compiler processes your source program, it checks for COBOL language
errors, and issues diagnostic messages. These messages are collated in the compiler
listing (subject to the FLAG option).
Each message in the listing provides information about the nature of the problem,
its severity, and the compiler phase that detected it. Wherever possible, the
message provides specific instructions for correcting an error.
The messages for errors found during processing of compiler options, CBL and
PROCESS statements, and BASIS, COPY, or REPLACE statements are displayed near the
top of the listing.
The messages for compilation errors (ordered by line number) are displayed near
the end of the listing for each program.
A summary of all problems found during compilation is displayed near the bottom
of the listing.
RELATED TASKS
“Correcting errors in your source program” on page 286
“Generating a list of compiler messages”
Chapter 14. Compiling under z/OS
287
RELATED REFERENCES
“Format of compiler diagnostic messages”
“Severity codes for compiler diagnostic messages”
“FLAG” on page 336
Format of compiler diagnostic messages
Each message issued by the compiler has a source line number, a message
identifier, and message text.
Each message has the following form:
nnnnnn IGYppxxxx-l message-text
nnnnnn
The number of the source statement of the last line that 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, the
numbers are the original source program numbers. If you specified
NONUMBER, the numbers are those generated by the compiler.
IGY
A prefix that identifies that the message was issued by the COBOL
compiler.
pp
Two characters that identify which phase or subphase of the compiler
detected the condition that resulted in a message. 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 message.
l
A character that indicates the severity level of the message: I, W, E, S, or U.
message-text
The message text; for an error message, a short explanation of the
condition that caused the error.
Tip: If you used the FLAG option to suppress messages, there might be additional
errors in your program.
RELATED REFERENCES
“Severity codes for compiler diagnostic messages”
“FLAG” on page 336
Severity codes for compiler diagnostic messages
Conditions that the compiler can detect fall into five levels or categories of severity.
Table 38. Severity codes for compiler diagnostic messages
288
Level or category
of message
Return
code
Informational (I)
0
To inform you. No action is required, and the program
runs correctly.
Warning (W)
4
To indicate a possible error. The program probably runs
correctly as written.
Error (E)
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.
Enterprise COBOL for z/OS, V5.1 Programming Guide
Purpose
Table 38. Severity codes for compiler diagnostic messages (continued)
Level or category
of message
Return
code
Severe (S)
12
To indicate a condition that is a serious error. The
compiler was unable to correct the error. The program
does not run correctly, and execution should not be
attempted. Object code might not be created.
Unrecoverable (U)
16
To indicate an error condition of such magnitude that the
compilation was terminated.
Purpose
The final return code at the end of compilation is generally the highest return code
that occurred for any message during the compilation.
You can suppress compiler diagnostic messages or change their severities, however,
which can have an effect upon the final compilation return code. For details, see
the related information.
RELATED TASKS
“Customizing compiler-message severities” on page 706
RELATED REFERENCES
“Processing of MSGEXIT” on page 705
Chapter 14. Compiling under z/OS
289
290
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 15. Compiling under z/OS UNIX
Compile Enterprise COBOL programs under z/OS UNIX by using the cob2
command. Under z/OS UNIX, you can compile any COBOL program that you can
compile under z/OS. The object code generated by the COBOL compiler can run
under z/OS.
About this task
As part of the compilation step, you define the files needed for the compilation,
and specify any compiler options or compiler-directing statements that are
necessary for your program and for the output that you want.
The main job of the compiler is to translate COBOL programs into language that
the computer can process (object code). The compiler also lists errors in source
statements and provides supplementary information to help you debug and tune
programs.
RELATED TASKS
“Setting environment variables under z/OS UNIX”
“Specifying compiler options under z/OS UNIX” on page 292
“Compiling and linking with the cob2 command” on page 293
“Compiling using scripts” on page 298
“Compiling, linking, and running OO applications under z/OS UNIX” on page 299
RELATED REFERENCES
“Data sets used by the compiler under z/OS” on page 273
“Compiler options and compiler output under z/OS” on page 281
Setting environment variables under z/OS UNIX
An environment variable is a name that is associated with a string of characters and
that defines some variable aspect of the program environment. You use
environment variables to set values that programs, including the compiler, need.
About this task
Set the environment variables for the compiler by using the export command. For
example, to set the SYSLIB variable, issue the export command from the shell or
from a script file:
export SYSLIB=/u/mystuff/copybooks
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
© Copyright IBM Corp. 1991, 2013
291
variable value are ignored. Delimit the list of options with quotation marks
if it contains blanks or characters that are significant to the z/OS UNIX
shell. For example:
export COBOPT="TRUNC(OPT) XREF"
SYSLIB
Specify paths to directories to be used in searching for COBOL copybooks
if you do not specify an explicit library-name in the COPY statement.
Separate multiple paths with a colon. 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 in which you have not coded an explicit library-name,
the compiler searches for copybooks 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 in 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 z/OS UNIX”
“Compiling and linking with the cob2 command” on page 293
“Setting and accessing environment variables” on page 452
RELATED REFERENCES
Chapter 18, “Compiler-directing statements,” on page 375
Chapter 17, “Compiler options,” on page 311
COPY statement (Enterprise COBOL Language Reference)
Specifying compiler options under z/OS UNIX
The compiler is installed and set up with default compiler options. While installing
the compiler, a system programmer can fix compiler option settings to ensure
better performance or maintain certain standards. You cannot override any
compiler options that your site has fixed.
About this task
For options that are not fixed, you can override the default settings by specifying
compiler options in any of three ways:
v Code them on the PROCESS or CBL statement in your COBOL source.
v Specify the -q option of the cob2 command.
v Set the COBOPT environment variable.
292
Enterprise COBOL for z/OS, V5.1 Programming Guide
The compiler recognizes the options in the above order of precedence, from highest
to lowest. 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, SQL, OUTDD, and SIZE options in effect for the first
program in a batch compilation
3. The values that you specify on PROCESS or CBL statements in 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
Restrictions:
v Do not use the SQL compiler option under z/OS UNIX.
Neither the separate SQL precompiler nor the integrated SQL coprocessor run
under z/OS UNIX.
v The OPTFILE option is ignored when you compile using the cob2 command
under z/OS UNIX.
You can use the COBOPT environment variable, which provides a capability that
is comparable to OPTFILE, instead.
RELATED TASKS
“Specifying compiler options in the PROCESS (CBL) statement” on page 280
“Setting environment variables under z/OS UNIX” on page 291
“Compiling and linking with the cob2 command”
RELATED REFERENCES
“Conflicting compiler options” on page 314
Chapter 17, “Compiler options,” on page 311
Compiling and linking with the cob2 command
Use the cob2 command to compile and link COBOL programs from the z/OS
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.
About this task
To compile multiple files (batch compilation), specify multiple source-file names.
When you compile COBOL programs for z/OS 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 LNKLST,
or if more than one level of IBM COBOL compiler is installed on your system, you
can specify in the STEPLIB environment variable the compiler PDS that you want
to use. For example, the following statement specifies IGY.V5R1M0 as the compiler
PDS:
Chapter 15. Compiling under z/OS UNIX
293
export STEPLIB=IGY.V5R1M0.SIGYCOMP
The cob2 command implicitly uses the z/OS UNIX shell command c89 for the link
step. c89 is the shell interface to the linker (the z/OS program management
binder).
The default location for compiler input and output is the current directory.
Only files with the suffix .cbl are passed to the compiler; cob2 passes all other files
to the linker.
The listing output that you request from the compilation of a COBOL source
program file.cbl is written to file.lst. The listing output that you request from the
linker is written to stdout.
The linker causes execution to begin at the first main program.
RELATED TASKS
“Creating a DLL under z/OS UNIX”
“Preparing OO applications under z/OS UNIX” on page 300
UNIX System Services User's Guide
RELATED REFERENCES
“cob2 syntax and options” on page 295
“cob2 input and output files” on page 297
UNIX System Services Command Reference
Creating a DLL under z/OS UNIX
To create a DLL from the z/OS UNIX shell, you must specify the cob2 option
-bdll.
About this task
cob2 -o mydll -bdll mysub.cbl
When you specify cob2 -bdll:
v The COBOL compiler uses the compiler options DLL, EXPORTALL, and RENT, which
are required for DLLs.
v The link step produces a DLL definition side file that 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 a suffix, that suffix 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 file later when you create a module that calls that
DLL, specify the side file with any other object files (file.o) that you need to link.
For example, the following command compiles myappl.cbl, uses the DLL option to
enable myappl.o to reference DLLs, and links to produce the module myappl:
cob2 -o myappl -qdll myappl.cbl mydll.x
“Example: using cob2 to compile and link under z/OS UNIX” on page 295
RELATED TASKS
Chapter 26, “Creating a DLL or a DLL application,” on page 497
“Compiling programs to create DLLs” on page 498
294
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
“cob2 syntax and options”
“cob2 input and output files” on page 297
Example: using cob2 to compile and link under z/OS UNIX
The following examples illustrate the use of cob2.
v To compile one file called alpha.cbl, enter:
cob2 -c alpha.cbl
The compiled file is named alpha.o.
v To compile two files called alpha.cbl and beta.cbl, enter:
cob2 -c alpha.cbl beta.cbl
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:
cob2 alpha.cbl beta.cbl -o gamma
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 -qlist,noadata alpha.cbl
cob2 syntax and options
You can use the options listed below with the cob2 command. (Do not capitalize
cob2.)
cob2 command syntax
cob2
filenames
options
-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 (except for the special cases noted
below). The name and value 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 LIST=NOIMPORT
v ALIASES=ALL
v COMPAT=CURRENT
v DYNAM=DLL
One special value for xxx is dll, which specifies that the executable
module is to be a DLL. This string is not passed to the linker.
-c
Compiles programs but does not link them.
Chapter 15. Compiling under z/OS UNIX
295
-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.
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 copybooks 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 in which you have not coded an explicit library-name,
the compiler searches for copybooks in the following 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
-L xxx Specifies the directory paths to be used to search for archive libraries
specified by the -l operand.
-l xxx
Specifies the name of an archive library for the linker. The cob2 command
searches for the name libxxx.a in the directories specified in the -L option,
then in the usual search order. (This option is lowercase l, not uppercase I.)
-o xxx Names the object module xxx. If the -o option is not used, the name of the
object module is a.out.
-qxxx
Passes xxx to the compiler, where xxx is a list of compiler options
separated by blanks or commas.
Enclose xxx in quotation marks 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.
Here is sample output:
cob2 -v -o mini -qssrange mini.cbl
compiler: ATTCRCTL PARM=RENT,TERM,SSRANGE /u/userid/cobol/mini.cbl
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.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 293
296
Enterprise COBOL for z/OS, V5.1 Programming Guide
“Creating a DLL under z/OS UNIX” on page 294
“Setting environment variables under z/OS UNIX” on page 291
cob2 input and output files
You can specify the following files as input file-names when you use the cob2
command.
Table 39. Input files to 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)
If you use the cob2 command, the following files are created in the current
directory.
Table 40. Output files from the cob2 command
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
compiler option ADATA
file.dbg
Symbolic information tables for
Created by the compiler if you specify
Debug Tool corresponding to input compiler option TEST(. . .,SEP,. . .)
COBOL source program file.cbl
file.dek
Extended COBOL source output
from library processing
Created by the compiler if you specify
compiler option MDECK
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 file.dll
class.java
Java class definition (source)
Created when you compile a class
definition
RELATED TASKS
“Compiling and linking with the cob2 command” on page 293
RELATED REFERENCES
“ADATA” on page 315
Chapter 15. Compiling under z/OS UNIX
297
“MDECK” on page 344
“TEST” on page 364
UNIX System Services Command Reference
Compiling using scripts
If you use a shell script to automate cob2 tasks, you must code option syntax
carefully to prevent the shell from passing invalid strings to cob2.
About this task
Code option strings in scripts as follows:
v Use an equal sign and colon rather than a left and right parenthesis, respectively,
to specify compiler suboptions. For example, code -qOPT=FULL:,XREF instead of
-qOPT(FULL),XREF.
v Use an underscore rather than a single quotation mark where a compiler option
requires single quotation marks for delimiting a suboption.
v Do not use blanks in the option string.
298
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 16. Compiling, linking, and running OO applications
It is recommended that you compile, link, and run object-oriented (OO)
applications in the z/OS UNIX environment. However, with certain limitations
explained in the related tasks, it is possible to compile, link, and run OO COBOL
applications by using standard batch JCL or TSO/E commands.
About this task
RELATED TASKS
“Compiling, linking, and running OO applications under z/OS UNIX”
“Compiling, linking, and running OO applications in JCL or TSO/E” on page 303
“Using Java SDKs for z/OS” on page 308
Compiling, linking, and running OO applications under z/OS UNIX
When you compile, link, and run object-oriented applications in a z/OS UNIX
environment, application components reside in the z/OS UNIX file system. You
compile and link them by using shell commands, and run them at a shell
command prompt or with the BPXBATCH utility from JCL or TSO/E.
About this task
RELATED TASKS
“Compiling OO applications under z/OS UNIX”
“Preparing OO applications under z/OS UNIX” on page 300
“Running OO applications under z/OS UNIX” on page 302
Compiling OO applications under z/OS UNIX
When you compile OO applications in a z/OS UNIX shell, use the cob2 command
to compile COBOL client programs and class definitions, and the javac command
to compile Java class definitions to produce bytecode (suffix .class).
About this task
To compile COBOL source code that contains OO syntax such as INVOKE statements
or class definitions, or that uses Java services, you must use these compiler
options: RENT, DLL, THREAD, and DBCS. (The RENT and DBCS options are defaults.)
A COBOL source file that contains a class definition must not contain any other
class or program definitions.
When you compile a COBOL class definition, two output files are generated:
v The object file (.o) for the class definition.
v A Java source program (.java) that contains a class definition that corresponds to
the COBOL class definition. Do not edit this generated Java class definition in
any way. If you change the COBOL class definition, you must regenerate both
the object file and the Java class definition by recompiling the updated COBOL
class definition.
If a COBOL client program or class definition includes the file JNI.cpy by using a
COPY statement, specify the include subdirectory of the COBOL install directory
© Copyright IBM Corp. 1991, 2013
299
(typically /usr/lpp/cobol/include) in the search order for copybooks. You can
specify the include subdirectory by using the -I option of the cob2 command or
by setting the SYSLIB environment variable.
RELATED TASKS
Chapter 15, “Compiling under z/OS UNIX,” on page 291
“Preparing OO applications under z/OS UNIX”
“Running OO applications under z/OS UNIX” on page 302
“Setting and accessing environment variables” on page 452
“Accessing JNI services” on page 621
RELATED REFERENCES
“cob2 syntax and options” on page 295
“DBCS” on page 327
“DLL” on page 330
“RENT” on page 355
“THREAD” on page 366
Preparing OO applications under z/OS UNIX
Use the cob2 command to link OO COBOL applications.
About this task
To prepare an OO COBOL client program for execution, link the object file with
the following two DLL side files to create an executable module:
v libjvm.x, which is provided with your IBM Java Software Development Kit.
v igzcjava.x, which is provided in the lib subdirectory of the cobol directory in
the z/OS UNIX file system. The typical complete path is /usr/lpp/cobol/lib/
igzcjava.x. This DLL side file is also available as the member IGZCJAVA in the
SCEELIB PDS (part of Language Environment).
To prepare a COBOL class definition for execution:
Procedure
1. Link the object file using the two DLL side files mentioned above to create an
executable DLL module.
You must name the resulting DLL module libClassname.so, where Classname is
the external class-name. If the class is part of a package and thus there are
periods in the external class-name, you must change the periods to underscores
in the DLL module name. For example, if class Account is part of the com.acme
package, the external class-name (as defined in the REPOSITORY paragraph entry
for the class) must be com.acme.Account, and the DLL module for the class
must be libcom_acme_Account.so.
2. Compile the generated Java source with the Java compiler to create a class file
(.class).
Results
For a COBOL source file Classname.cbl that contains the class definition for
Classname, you would use the following commands to compile and link the
components of the application:
300
Enterprise COBOL for z/OS, V5.1 Programming Guide
Table 41. Commands for compiling and linking a class definition
Command
Input
Output
cob2 -c -qdll,thread Classname.cbl
Classname.cbl
Classname.o,
Classname.java
cob2 -bdll -o libClassname.so Classname.o
/usr/lpp/java/J5.0/bin/j9vm/libjvm.x
/usr/lpp/cobol/lib/igzcjava.x
Classname.o
libClassname.so
javac Classname.java
Classname.java
Classname.class
After you issue the cob2 and javac commands successfully, you have the
executable components for the program: the executable DLL module
libClassname.so and the class file Classname.class. All files from these commands
are generated in the current working directory.
“Example: compiling and linking a COBOL class definition under z/OS UNIX”
RELATED TASKS
Chapter 15, “Compiling under z/OS UNIX,” on page 291
“REPOSITORY paragraph for defining a class” on page 580
RELATED REFERENCES
“cob2 syntax and options” on page 295
“Object-oriented syntax, and Java 5 or Java 6” on page 309
Example: compiling and linking a COBOL class definition
under z/OS UNIX
This example illustrates the commands that you use and the files that are produced
when you compile and link a COBOL class definition, Manager.cbl, using z/OS
UNIX shell commands.
Manager.cbl
Identification division.
Class-id Manager inherits Employee.
Environment division.
Configuration section.
Repository.
Class Manager is "Manager"
...
End class Manager.
cob2 -c -qdll,thread Manager.cbl
Manager.java
Manager.o
javac Manager.java
cob2 -bdll -o libManager.so Manager.o
/usr/lpp/java/J5.0/bin/j9vm/libjvm.x
/usr/lpp/cobol/lib/igzcjava.x
Manager.class
libManager.so
Chapter 16. Compiling, linking, and running OO applications
301
The class file Manager.class and the DLL module libManager.so are the executable
components of the application, and are generated in the current working directory.
Running OO applications under z/OS UNIX
It is recommended that you run object-oriented COBOL applications as z/OS
UNIX applications. You must do so if an application begins with a Java program or
the main factory method of a COBOL class.
About this task
Specify the directory that contains the DLLs for the COBOL classes in the LIBPATH
environment variable. Specify the directory paths for the Java class files that are
associated with the COBOL classes in the CLASSPATH environment variable as
follows:
v For classes that are not part of a package, end the class path with the directory
that contains the .class files.
v For classes that are part of a package, end the class path with the directory that
contains the "root" package (the first package in the full package name).
v For a .jar file that contains .class files, end the class path with the name of the
.jar file.
Separate multiple path entries with colons.
RELATED TASKS
“Running OO applications that start with a main method”
“Running OO applications that start with a COBOL program” on page 303
“Running J2EE COBOL clients” on page 303
Chapter 23, “Running COBOL programs under z/OS UNIX,” on page 451
“Setting and accessing environment variables” on page 452
Chapter 30, “Writing object-oriented programs,” on page 575
“Structuring OO applications” on page 618
Running OO applications that start with a main method
If the first routine of a mixed COBOL and Java application is the main method of a
Java class or the main factory method of a COBOL class, run the application by
using the java command and by specifying the name of the class that contains the
main method.
About this task
The java command initializes the Java virtual machine (JVM). To customize the
initialization of the JVM, specify options on the java command as in the following
examples:
Table 42. java command options for customizing the JVM
Purpose
Option
To set a system property
-Dname=value
To request that the JVM generate verbose messages about
garbage collection
-verbose:gc
To request that the JVM generate verbose messages about class -verbose:class
loading
To request that the JVM generate verbose messages about
native methods and other Java Native Interface activity
302
Enterprise COBOL for z/OS, V5.1 Programming Guide
-verbose:jni
Table 42. java command options for customizing the JVM (continued)
Purpose
Option
To set the initial Java heap size to value bytes
-Xmsvalue
To set the maximum Java heap size to value bytes
-Xmxvalue
For details about the options that the JVM supports, see the output from the java
-h command, or see the related references.
RELATED REFERENCES
IBM SDK for Java - Tools Documentation
WebSphere for z/OS: Applications (Java Naming and Directory Interface (JNDI))
Running OO applications that start with a COBOL program
If the first routine of a mixed COBOL and Java application is a COBOL program,
run the application by specifying the program name at the command prompt. If a
JVM is not already running in the process of the COBOL program, the COBOL run
time automatically initializes a JVM.
About this task
To customize the initialization of the JVM, specify options by setting the
COBJVMINITOPTIONS environment variable. Use blanks to separate options. For
example:
export COBJVMINITOPTIONS="-Xms10000000 -Xmx20000000 -verbose:gc"
RELATED TASKS
“Using Java SDKs for z/OS” on page 308
Chapter 23, “Running COBOL programs under z/OS UNIX,” on page 451
“Setting and accessing environment variables” on page 452
RELATED REFERENCES
IBM SDK for Java - Tools Documentation
WebSphere for z/OS: Applications (Java Naming and Directory Interface (JNDI))
Running J2EE COBOL clients:
You can use OO syntax in a COBOL program to implement a Java 2 Platform,
Enterprise Edition (J2EE) client. You can, for example, invoke methods on
enterprise beans that run in the WebSphere® for z/OS environment.
About this task
Before you run a COBOL J2EE client, you must set the Java system property
java.naming.factory.initial to access WebSphere naming services. For example:
export COBJVMINITOPTIONS
="-Djava.naming.factory.initial=com.ibm.websphere.naming.WsnInitialContextFactory"
“Example: J2EE client written in COBOL” on page 633
Compiling, linking, and running OO applications in JCL or TSO/E
It is recommended that you compile, link, and run applications that use OO syntax
in the z/OS UNIX environment.
Chapter 16. Compiling, linking, and running OO applications
303
About this task
However, in limited circumstances it is possible to compile, prepare, and run OO
applications by using standard batch JCL or TSO/E commands. To do so, you
must follow the guidelines that are in the related tasks. For example, you might
follow this approach for applications that consist of a COBOL main program and
subprograms that:
v Access objects that are all implemented in Java
v Access enterprise beans that run in a WebSphere server
RELATED TASKS
“Compiling OO applications in JCL or TSO/E”
“Preparing and running OO applications in JCL or TSO/E” on page 305
“Compiling, linking, and running OO applications under z/OS UNIX” on page 299
Compiling OO applications in JCL or TSO/E
If you use batch JCL or TSO/E to compile an OO COBOL program or class
definition, the generated object file is written, as usual, to the data set that has
ddname SYSLIN or SYSPUNCH. You must use compiler options RENT, DLL, THREAD, and
DBCS. (RENT and DBCS are defaults.)
About this task
If the COBOL program or class definition uses the JNI environment structure to
access JNI callable services, copy the file JNI.cpy from the z/OS UNIX file system
to a PDS or PDSE member called JNI, identify that library with a SYSLIB DD
statement, and use a COPY statement of the form COPY JNI in the COBOL source.
A COBOL source file that contains a class definition must not contain any other
class or program definitions.
When you compile a COBOL class definition, a Java source program that contains
a class definition that corresponds to the COBOL class definition is generated in
addition to the object file. Use the SYSJAVA ddname to write the generated Java
source file to a file in the z/OS UNIX file system. For example:
//SYSJAVA DD PATH=’/u/userid/java/Classname.java’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU,
// FILEDATA=TEXT
Do not edit this generated Java class definition in any way. If you change the
COBOL class definition, you must regenerate both the object file and the Java class
definition by recompiling the updated COBOL class definition.
Compile Java class definitions by using the javac command from a z/OS UNIX
shell command prompt, or by using the BPXBATCH utility.
“Example: compiling, linking, and running an OO application using JCL” on page
306
RELATED TASKS
“Compiling with JCL” on page 261
“Compiling under TSO” on page 269
“Specifying source libraries (SYSLIB)” on page 276
“Defining the Java-source output file (SYSJAVA)” on page 278
304
Enterprise COBOL for z/OS, V5.1 Programming Guide
“Accessing JNI services” on page 621
“Compiling OO applications under z/OS UNIX” on page 299
“Preparing OO applications under z/OS UNIX” on page 300
RELATED REFERENCES
“DBCS” on page 327
“DLL” on page 330
“RENT” on page 355
“THREAD” on page 366
Appendix E, “JNI.cpy copybook,” on page 717
UNIX System Services User's Guide (The BPXBATCH utility)
Preparing and running OO applications in JCL or TSO/E
It is recommended that you run OO applications in a z/OS UNIX environment. To
run OO applications from batch JCL or TSO/E, you should therefore use the
BPXBATCH utility.
About this task
In limited circumstances, however, you can run an OO application by using
standard batch JCL (EXEC PGM=COBPROG) or the TSO/E CALL command. To do so,
follow these requirements when preparing the application:
v Structure the application to start with a COBOL program. (If an application
starts with a Java program or with the main factory method of a COBOL class,
you must run the application under z/OS UNIX, and the application
components must reside in the z/OS UNIX file system.)
v Link-edit considerations: Link the load module for the COBOL program into a
PDSE. COBOL programs that contain object-oriented syntax must be link-edited
with AMODE 31.
v Ensure that the class files and DLLs associated with the COBOL or Java classes
that are used by the application reside in the z/OS UNIX file system. You must
name the class files and DLLs as described in the related task about preparing
OO applications.
v Specify INCLUDE control statements for the DLL side files libjvm.x and
igzcjava.x when you bind the object deck for the main program. For example:
INCLUDE ’/usr/lpp/java/J5.0/bin/j9vm/libjvm.x’
INCLUDE ’/usr/lpp/cobol/lib/igzcjava.x’
v
Create a file that contains the environment variable settings that are required for
Java. For example, a file /u/userid/javaenv might contain the three lines shown
below to set the PATH, LIBPATH, and CLASSPATH environment variables.
PATH=/bin:/usr/lpp/java/J5.0/bin
LIBPATH=/lib:/usr/lib:/usr/lpp/java/J5.0/bin:/usr/lpp/java/J5.0/bin/j9vm
CLASSPATH=/u/userid/applications
To customize the initialization of the JVM that will be used by the application,
you can set the COBJVMINITOPTIONS environment variable in the same file.
For example, to access enterprise beans that run in a WebSphere server, you
must set the Java system property java.naming.factory.initial. For details, see the
related task about running OO applications.
When you run an OO application that starts with a COBOL program by using
standard batch JCL or the TSO/E CALL command, follow these guidelines:
v Use the _CEE_ENVFILE environment variable to indicate the location of the file
that contains the environment variable settings required by Java. Set
_CEE_ENVFILE by using the ENVAR runtime option.
Chapter 16. Compiling, linking, and running OO applications
305
Specify the POSIX(ON) and XPLINK(ON) runtime option.
Use DD statements to specify files in the z/OS UNIX file system for the standard
input, output, and error streams for Java:
– JAVAIN DD for the input from statements such as c=System.in.read();
– JAVAOUT DD for the output from statements such as
System.out.println(string);
– JAVAERR DD for the output from statements such as
System.err.println(string);
v Ensure that the SCEERUN2 and SCEERUN load libraries are available in the
system library search order, for example, by using a STEPLIB DD statement.
|
v
v
“Example: compiling, linking, and running an OO application using JCL”
RELATED TASKS
“Preparing OO applications under z/OS UNIX” on page 300
“Running OO applications under z/OS UNIX” on page 302
“Structuring OO applications” on page 618
UNIX System Services User's Guide (The BPXBATCH utility)
Language Environment Programming Guide (Running an application under batch)
RELATED REFERENCES
XL C/C++ Programming Guide (_CEE_ENVFILE)
Language Environment Programming Reference (ENVAR)
Example: compiling, linking, and running an OO application
using JCL
This example shows sample JCL that you could use to compile, link, and run a
COBOL client that invokes a Java method.
The example shows:
v JCL to compile, link, and run an OO COBOL program, TSTHELLO
v A Java class definition, HelloJ, that contains a method that the COBOL program
invokes
v A z/OS UNIX file, ENV, that contains the environment variable settings that
Java requires
JCL for program TSTHELLO
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//TSTHELLO JOB ,
// TIME=(1),MSGLEVEL=(1,1),MSGCLASS=H,CLASS=A,REGION=128M,
// NOTIFY=&SYSUID,USER=&SYSUID
//*
// SET COBPRFX=’IGY.V5R1M0’
// SET LIBPRFX=’CEE’
//*
//COMPILE EXEC PGM=IGYCRCTL,
// PARM=’SIZE(5000K)’
//SYSLIN
DD DSNAME=&&OBJECT(TSTHELLO),UNIT=VIO,DISP=(NEW,PASS),
//
SPACE=(CYL,(1,1,1))
//SYSPRINT DD SYSOUT=*
//STEPLIB DD DSN=&COBPRFX..SIGYCOMP,DISP=SHR
//
DD DSN=&LIBPRFX..SCEERUN,DISP=SHR
//
DD DSN=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSUT1
DD UNIT=VIO,SPACE=(CYL,(1,1))
//SYSUT2
DD UNIT=VIO,SPACE=(CYL,(1,1))
//SYSUT3
DD UNIT=VIO,SPACE=(CYL,(1,1))
//SYSUT4
DD UNIT=VIO,SPACE=(CYL,(1,1))
306
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
//SYSUT5
DD UNIT=VIO,SPACE=(CYL,(1,1))
//SYSUT6
DD UNIT=VIO,SPACE=(CYL,(1,1))
//SYSUT7
DD UNIT=VIO,SPACE=(CYL,(1,1))
//SYSUT8
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9
DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSIN
DD *
cbl dll,thread
Identification division.
Program-id. "TSTHELLO" recursive.
Environment division.
Configuration section.
Repository.
Class HelloJ is "HelloJ".
Data Division.
Procedure division.
Display "COBOL program TSTHELLO entered"
Invoke HelloJ "sayHello"
Display "Returned from java sayHello to TSTHELLO"
Goback.
End program "TSTHELLO".
/*
//LKED EXEC PGM=IEWL,PARM=’RENT,LIST,LET,DYNAM(DLL),CASE(MIXED)’
//SYSLIB
DD DSN=&LIBPRFX..SCEELKED,DISP=SHR
//
DD DSN=&LIBPRFX..SCEELKEX,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSTERM DD SYSOUT=*
//SYSLMOD DD DSN=&&GOSET(TSTHELLO),DISP=(MOD,PASS),UNIT=VIO,
//
SPACE=(CYL,(1,1,1)),DSNTYPE=LIBRARY
//SYSDEFSD DD DUMMY
//OBJMOD
DD DSN=&&OBJECT,DISP=(OLD,DELETE)
//SYSLIN
DD *
INCLUDE OBJMOD(TSTHELLO)
INCLUDE ’/usr/lpp/java/J5.0/bin/j9vm/libjvm.x’
INCLUDE ’/usr/lpp/cobol/lib/igzcjava.x’
/*
//GO EXEC PGM=TSTHELLO,COND=(4,LT,LKED),
//
PARM=’/ENVAR("_CEE_ENVFILE=/u/userid/ootest/tsthello/ENV")
//
POSIX(ON)
XPLINK(ON)’
//STEPLIB DD DSN=*.LKED.SYSLMOD,DISP=SHR
//
DD DSN=&LIBPRFX..SCEERUN2,DISP=SHR
//
DD DSN=&LIBPRFX..SCEERUN,DISP=SHR
//SYSOUT
DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//SYSUDUMP DD DUMMY
//JAVAOUT DD PATH=’/u/userid/ootest/tsthello/javaout’,
//JAVAERR DD PATH=’/u/userid/ootest/tsthello/javaerr’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=(SIRUSR,SIWUSR,SIRGRP)
Definition of class HelloJ
class HelloJ {
public static void sayHello() {
System.out.println("Hello World, from Java!");
}
}
Chapter 16. Compiling, linking, and running OO applications
307
HelloJ.java is compiled with the javac command. The resulting .class file resides in
the z/OS UNIX file system directory u/userid/ootest/tsthello, which is specified
in the CLASSPATH environment variable in the environment variable settings file.
Environment variable settings file, ENV
PATH=/bin:/usr/lpp/java/J5.0/bin.
LIBPATH=/lib:/usr/lib:/usr/lpp/java/J5.0/bin:/usr/lpp/java/J5.0/bin/j9vm
CLASSPATH=/u/userid/ootest/tsthello
The environment variable settings file also resides in directory
u/userid/ootest/tsthello, as specified in the _CEE_ENVFILE environment variable
in the JCL.
Using Java SDKs for z/OS
The Java SDKs for z/OS are based on the XPLINK linkage convention defined by
Language Environment.
About this task
If the application starts with a Java program or the main factory method of a
COBOL class, the XPLINK environment is automatically started by the java
command that starts the JVM and runs the application.
If an application starts with a COBOL program that invokes methods on COBOL
or Java classes, you must specify the XPLINK(ON) runtime option so that the
XPLINK environment is initialized. XPLINK(ON) is not recommended as a default
setting, however; you should use XPLINK(ON) only for applications that specifically
require it.
When you are running an application under z/OS UNIX, you can set the
XPLINK(ON) option by using the _CEE_RUNOPTS environment variable as follows:
_CEE_RUNOPTS="XPLINK(ON)"
Exporting _CEE_RUNOPTS="XPLINK(ON)" so that it is in effect for the entire z/OS
UNIX shell session is not recommended, however. Suppose for example that an
OO COBOL application starts with a COBOL program called App1Driver. One way
to limit the effect of the XPLINK option to the execution of the App1Driver
application is to set the _CEE_RUNOPTS variable on the command-line invocation
of App1Driver as follows:
_CEE_RUNOPTS="XPLINK(ON)" App1Driver
RELATED TASKS
“Running OO applications under z/OS UNIX” on page 302
“Setting and accessing environment variables” on page 452
RELATED REFERENCES
“Object-oriented syntax, and Java 5 or Java 6” on page 309
“Runtime environment variables” on page 453
Language Environment Programming Reference (XPLINK)
XL C/C++ Programming Guide (_CEE_RUNOPTS)
308
Enterprise COBOL for z/OS, V5.1 Programming Guide
Object-oriented syntax, and Java 5 or Java 6
Though Enterprise COBOL applications that use object-oriented syntax for Java
interoperability are still supported with Java SDK 1.4.2, you can now run them
using Java 5 or Java 6 instead.
To run existing applications using Java 5 or Java 6 instead of Java SDK 1.4.2, do
these steps:
1. Recompile and relink the applications using the current version of Enterprise
COBOL.
2. Recompile the generated Java class that is associated with each object-oriented
COBOL class using the javac command from Java 5 or Java 6.
RELATED TASKS
“Preparing OO applications under z/OS UNIX” on page 300
Chapter 16. Compiling, linking, and running OO applications
309
310
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 17. Compiler options
You can direct and control your compilation by using compiler options or by using
compiler-directing statements (compiler 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.
Table 43. Compiler options
Aspect of your
program
Compiler option
Default
Option abbreviations
Source language
“ARITH” on page 318
ARITH(COMPAT)
AR(C|E)
“CICS” on page 321
NOCICS
None
“CODEPAGE” on page 322
CODEPAGE(01140)
CP(ccsid)
“CURRENCY” on page 325
NOCURRENCY
CURR|NOCURR
“DBCS” on page 327
DBCS
None
“NSYMBOL” on page 346
NSYMBOL(NATIONAL)
NS(DBCS|NAT)
“NUMBER” on page 347
NONUMBER
NUM|NONUM
“QUOTE/APOST” on page 355
QUOTE
Q|APOST
“SEQUENCE” on page 358
SEQUENCE
SEQ|NOSEQ
“SQL” on page 360
NOSQL
None
“SQLCCSID” on page 361
SQLCCSID
SQLC|NOSQLC
“WORD” on page 371
NOWORD
WD|NOWD
Date processing
“INTDATE” on page 339
INTDATE(ANSI)
None
Maps and listings
“LANGUAGE” on page 340
LANGUAGE(ENGLISH)
LANG(EN|UE|JA|JP)
“LINECOUNT” on page 341
LINECOUNT(60)
LC
“LIST” on page 341
NOLIST
None
“MAP” on page 342
NOMAP
None
“OFFSET” on page 349
NOOFFSET
OFF|NOOFF
“SOURCE” on page 359
SOURCE
S|NOS
“SPACE” on page 359
SPACE(1)
None
“TERMINAL” on page 363
NOTERMINAL
TERM|NOTERM
“VBREF” on page 370
NOVBREF
None
“XREF” on page 371
XREF(FULL)
X|NOX
“COMPILE” on page 325
NOCOMPILE(S)
C|NOC
“DECK” on page 328
NODECK
D|NOD
“NAME” on page 345
NONAME, or NAME(NOALIAS)
if only NAME is specified
None
“OBJECT” on page 348
OBJECT
OBJ|NOOBJ
“PGMNAME” on page 353
PGMNAME(COMPAT)
PGMN(CO|LU|LM)
Object deck
generation
© Copyright IBM Corp. 1991, 2013
311
Table 43. Compiler options (continued)
Aspect of your
program
Compiler option
Default
Option abbreviations
Object code control
“ADV” on page 315
ADV
None
|
“AFP” on page 316
AFP(VOLATILE)
None
|
“ARCH” on page 317
ARCH(6)
None
“AWO” on page 319
NOAWO
None
“BLOCK0” on page 319
NOBLOCK0
None
“DISPSIGN” on page 329
DISPSIGN(COMPAT)
DS(S|C)
“DLL” on page 330
NODLL
None
“EXPORTALL” on page 335
NOEXPORTALL
EXP|NOEXP
“FASTSRT” on page 335
NOFASTSRT
FSRT|NOFSRT
|
“MAXPCF” on page 343
MAXPCF(60000)
None
|
“HGPR” on page 338
HGPR(PRESERVE)
None
“NUMPROC” on page 347
NUMPROC(NOPFD)
None
“OPTIMIZE” on page 351
OPTIMIZE(0)
OPT(n)
“OUTDD” on page 352
OUTDD(SYSOUT)
OUT
“TRUNC” on page 368
TRUNC(STD)
None
“ZWB” on page 373
ZWB
None
“BUFSIZE” on page 321
4096
BUF
“DATA” on page 326
DATA(31)
None
“DYNAM” on page 332
NODYNAM
DYN|NODYN
“RENT” on page 355
RENT
None
“RMODE” on page 357
AUTO
None
|
“SIZE” on page 358
SIZE(5000000)
SZ
|
“STGOPT” on page 363
NOSTGOPT
SO|NOSO
“DIAGTRUNC” on page 328
NODIAGTRUNC
DTR|NODTR
“DUMP” on page 331
NODUMP
DU|NODU
“FLAG” on page 336
FLAG(I,I)
F|NOF
“FLAGSTD” on page 337
NOFLAGSTD
None
“SSRANGE” on page 362
NOSSRANGE
SSR|NOSSR
“TEST” on page 364
NOTEST
None
“ADATA” on page 315
NOADATA
None
“EXIT” on page 332
NOEXIT
NOEX|EX(INX|NOINX,
LIBX|NOLIBX, PRTX|NOPRTX,
ADX|NOADX, MSGX|NOMSGX)
“MDECK” on page 344
NOMDECK
NOMD|MD|MD(C|NOC)
“OPTFILE” on page 350
None
None
“THREAD” on page 366
NOTHREAD
None
|
|
Virtual storage
usage
Debugging and
diagnostics
Other
Installation defaults: The default compiler options that were set up when your
compiler was installed are in effect for your program unless you override those
options. (In some installations, certain compiler options are fixed so that you
cannot override them. If you have problems with the default options, contact your
312
Enterprise COBOL for z/OS, V5.1 Programming Guide
system administrator.) To determine which are the default options, run a test
compilation without specifying any compiler options. The output listing lists the
default options in effect at your site.
Nonoverridable options: In some installations, certain compiler options are fixed
so that you cannot override them. If you have problems with those options, contact
your system administrator.
Option specification: Compiler options and suboptions are not case sensitive.
|
|
Performance considerations: The AFP, ARCH, ARITH, AWO, BLOCK0, DYNAM, FASTSRT,
HGPR, MAXPCF, NUMPROC, OPTIMIZE, RENT, SQLCCSID, SSRANGE, STGOPT, TEST, THREAD, and
TRUNC compiler options can affect runtime performance.
RELATED TASKS
Chapter 14, “Compiling under z/OS,” on page 261
“Compiling under TSO” on page 269
Chapter 15, “Compiling under z/OS UNIX,” on page 291
Chapter 33, “Tuning your program,” on page 653
RELATED REFERENCES
“Conflicting compiler options” on page 314
Chapter 18, “Compiler-directing statements,” on page 375
“Option settings for Standard COBOL 85 conformance”
“Performance-related compiler options” on page 661
Option settings for Standard COBOL 85 conformance
Compiler options and runtime options are required for conformance with Standard
COBOL 85.
|
The following compiler options are required:
v ADV
v NOBLOCK0
v NOCICS
v NODLL
v
v
v
v
v
DYNAM
NOEXPORTALL
NOFASTSRT
NAME(ALIAS) or NAME(NOALIAS)
NUMPROC(NOPFD)
v
v
v
v
v
v
PGMNAME(COMPAT) or PGMNAME(LONGUPPER)
QUOTE
NOTHREAD
TRUNC(STD)
NOWORD
ZWB
You can use the FLAGSTD compiler option to flag nonconforming elements such as
IBM extensions.
The following runtime options are required:
Chapter 17. Compiler options
313
v AIXBLD
v CBLQDA(ON)
v TRAP(ON)
RELATED REFERENCES
Language Environment Programming Reference
Conflicting compiler options
The Enterprise COBOL compiler can encounter conflicting compiler options in
either of two ways: both the positive and negative form of an option are specified
at the same level in the hierarchy of precedence, or mutually exclusive options are
specified at the same level in the hierarchy.
When conflicting options are specified at the same level in the hierarchy (such as
specifying both DECK and NODECK in a PROCESS or CBL statement), the option
specified last takes effect.
If you specify mutually exclusive compiler options at the same level, the compiler
generates an error message and forces one of the options to a nonconflicting value.
For example, if you specify both OFFSET and LIST in a 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 a JCL
statement but LIST in a PROCESS statement, LIST takes 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.
Table 44. Mutually exclusive compiler options
Specified
Ignored1
Forced on1
CICS
DYNAM
NODYNAM
NORENT
RENT
DYNAM
NODYNAM
NORENT
RENT
NODLL
DLL
DYNAM
NODYNAM
NORENT
RENT
NORENT
RMODE(ANY)
RMODE(24)
NSYMBOL(NATIONAL)
NODBCS
DBCS
OBJECT
DECK
NODECK
OFFSET
LIST
NOLIST
PGMNAME(LM|LU)
NAME
NONAME
TEST
NOOBJECT and NODECK
OBJECT and NODECK
THREAD
NORENT
RENT
WORD
FLAGSTD
NOFLAGSTD
DLL
EXPORTALL
|
|
|
1. Unless in conflict with a fixed installation default option.
314
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED TASKS
“Specifying compiler options under z/OS” on page 279
“Specifying compiler options in a batch compilation” on page 284
“Specifying compiler options under z/OS UNIX” on page 292
RELATED REFERENCES
“OPTFILE” on page 350
ADATA
Use ADATA when you want the compiler to create a SYSADATA file that contains
records of additional compilation information.
ADATA option syntax
NOADATA
ADATA
Default is: NOADATA
Abbreviations are: None
ADATA is required for remote compilation using an IBM Windows COBOL compiler.
On z/OS, the SYSADATA file is written to ddname SYSADATA.
The size of the SYSADATA file generally grows with the size of the associated
program.
Option specification: You cannot specify the ADATA option in a PROCESS (or CBL)
statement. You can specify it only in one of the following ways:
v In the PARM parameter of JCL
v As a cob2 command option
v As an installation default
v In the COBOPT environment variable
RELATED REFERENCES
“Setting environment variables under z/OS UNIX” on page 291
“cob2 syntax and options” on page 295
Appendix F, “COBOL SYSADATA file contents,” on page 723
ADV
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.
Chapter 17. Compiler options
315
ADV option syntax
ADV
NOADV
Default is: ADV
Abbreviations are: None
Use NOADV if you already adjusted record length to include 1 byte for the printer
control character.
|
AFP
The AFP option controls the compiler usage of the Additional Floating Point (AFP)
registers that are provided by z/Architecture processors.
|
|
|
AFP option syntax
|
|
AFP(
VOLATILE
NOVOLATILE
)
|
||
|
Default is: AFP(VOLATILE)
|
Abbreviations are: None
|
|
|
|
|
The Enterprise COBOL compiler generates code that uses the full complement of
16 floating point registers (FPR) provided by a z/Architecture processor. These
FPRs are as follows:
v Original FPRs, which are numbered 0, 2, 4, and 6
v AFP registers, which are numbered 1, 3, 5, 7, and 8-15
|
|
Note: If your code runs on a version of CICS Transaction Server that is earlier than
V4.1, you must specify AFP(VOLATILE).
|
|
|
|
|
AFP(VOLATILE)
If you specify AFP(VOLATILE), the AFP registers 8-15 are considered volatile,
which means that they might be changed by a called subprogram.
Therefore, the COBOL compiler generates extra code to protect the values
in these registers.
|
|
|
|
|
|
AFP(NOVOLATILE)
If you specify AFP(NOVOLATILE), the AFP registers 8-15 are considered
nonvolatile, which means that they are known to be unchanged or
preserved by every called subprogram. Therefore, the compiler can
generate more efficient code sequences for programs with floating point
operations. It is the normal z/OS architecture convention.
316
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
ARCH
The ARCH option specifies the machine architecture for which the executable
program instructions are to be generated.
|
ARCH option syntax
|
|
ARCH(
6
7
8
9
10
)
|
||
|
Default is: ARCH(6)
|
Abbreviations are: None
|
|
|
|
If you specify a higher ARCH level, the compiler generates code that uses newer and
faster instructions. Your application might abend if it runs on a processor with an
architecture level lower than what you specified with the ARCH option. Use the ARCH
level that matches the lowest machine architecture where your application runs.
|
Current supported architecture levels and groups of models are as follows:
|
|
6
Specifically, these ARCH(6) machines and their follow-ons include
instructions supported by the long-displacement facility.
|
|
|
|
Produces code that uses instructions available on the 2084-xxx (z990) and
2086-xxx (z890) models in z/Architecture mode.
7
Produces code that uses instructions available on the 2096-xxx (IBM System
z9 BC) and 2094-xxx (IBM System z9 EC) models in z/Architecture mode.
|
|
|
Specifically, these ARCH(7) machines and their follow-ons add instructions
supported by the following facilities:
v Extended-immediate facility
|
|
v Decimal floating point facility. These instructions might be generated if
decimal data is used in numeric operations.
|
|
8
Specifically, these ARCH(8) machines and their follow-ons add instructions
supported by the general instruction extensions facility.
|
|
|
|
|
|
|
|
|
|
Produces code that uses instructions available on the 2097-xxx (IBM System
z10 EC) models in z/Architecture mode.
9
Produces code that uses instructions available on 2817-xxx (IBM
zEnterprise 196) and 2818-xxx (IBM zEnterprise 114) models in
z/Architecture mode.
Specifically, these ARCH(9) machines and their follow-ons add instructions
supported by the following facilities:
v High-word facility
v Interlocked access facility
v Load/store-on-condition facility
Chapter 17. Compiler options
317
v Distinct-operands facility
v Population-count facility
|
|
10
|
|
Produces code that uses instructions available on the 2827-xxxx (IBM
zEnterprise EC12) models in z/Architecture mode.
Specifically, these ARCH(10) machines and their follow-ons add instructions
supported by the following facilities:
v Execution-hint facility
v Load-and-trap facility
v Miscellaneous-instructions-extension facility
v Transactional-execution facility
|
|
|
|
|
|
|
|
Note: A higher ARCH level includes the facilities of the lower ARCH level. For
example, ARCH(10) includes all the facilities of the lower ARCH levels.
|
For more information about these facilities, see z/Architecture Principles of Operation.
ARITH
ARITH affects the maximum number of digits that you can code for integers, and
the number of digits used in fixed-point intermediate results.
ARITH option syntax
ARITH(
COMPAT
EXTEND
)
Default is: ARITH(COMPAT)
Abbreviations are: AR(C|E)
When you specify ARITH(EXTEND):
v The maximum number of digit positions that you can specify in the PICTURE
clause for packed-decimal, external-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:
– Operands of PROCEDURE DIVISION statements
– VALUE clauses (for numeric data items with large-precision PICTURE)
– Condition-name values (on numeric data items with large-precision PICTURE)
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):
318
Enterprise COBOL for z/OS, V5.1 Programming Guide
v The maximum number of digit positions in the PICTURE clause for
packed-decimal, external-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 677
AWO
If you specify AWO, an implicit APPLY WRITE-ONLY clause is activated for all QSAM
files in the program that have blocked variable-length records.
AWO option syntax
NOAWO
AWO
Default is: NOAWO
Abbreviations are: None
RELATED TASKS
“Optimizing buffer and device space” on page 11
RELATED REFERENCES
“BLOCK0”
APPLY WRITE-ONLY clause (Enterprise COBOL Language Reference)
BLOCK0
Use BLOCK0 to change the compiler default for QSAM files from unblocked to
blocked (as if BLOCK CONTAINS 0 were specified) and thus gain the benefit of
system-determined blocking for output files.
BLOCK0 option syntax
NOBLOCK0
BLOCK0
Default is: NOBLOCK0
Chapter 17. Compiler options
319
Abbreviations are: None
Specifying BLOCK0 activates an implicit BLOCK CONTAINS 0 clause for each file in the
program that meets the following three criteria:
v The FILE-CONTROL paragraph either specifies ORGANIZATION SEQUENTIAL or omits
the ORGANIZATION clause.
v The FD entry does not specify RECORDING MODE U.
v The FD entry does not specify a BLOCK CONTAINS clause.
Files for which the resulting BLOCK CONTAINS 0 clause is in effect have a blocking
factor that is determined at run time from the data definition or from the data-set
characteristics.
Interaction of the APPLY WRITE-ONLY clause and the AWO compiler option with
BLOCK0:
v If NOBLOCK0 is in effect, and the file description of a file that meets the three
criteria listed above specifies APPLY WRITE-ONLY, the compiler issues an error
message because APPLY WRITE-ONLY applies only to blocked files. But if BLOCK0 is
in effect, the result is that the file is blocked, and the APPLY WRITE-ONLY clause is
therefore accepted.
v AWO applies to any QSAM files that have blocked variable-length records. If
BLOCK0 is in effect, the result is that more files might be blocked than if NOBLOCK0
were in effect; thus AWO might apply to more files than it otherwise would.
Specifying BLOCK0 for existing programs might result in a change of behavior, and
in some cases produce undesirable results for files opened as INPUT. For example:
v The OPEN INPUT statement fails for files for which no block size can be
determined.
v Programs that continue after handling nonzero FILE STATUS codes for files
opened as INPUT might abnormally terminate when executing subsequent I/O
statements on those files.
For these reasons, after compiling with BLOCK0 you should investigate and test the
effects on your program.
For recommendations about blocking, see the related reference from the Enterprise
COBOL Migration Guide (in the information about migrating from CMPR2 to
NOCMPR2).
RELATED TASKS
“Optimizing buffer and device space” on page 11
“Setting block sizes” on page 173
RELATED REFERENCES
“AWO” on page 319
APPLY WRITE-ONLY clause (Enterprise COBOL Language Reference)
BLOCK CONTAINS clause (Enterprise COBOL Language Reference)
Enterprise COBOL Migration Guide
(Recommendation for DCB= parameters of JCL)
320
Enterprise COBOL for z/OS, V5.1 Programming Guide
BUFSIZE
Use BUFSIZE to allocate an amount of main storage to the buffer for each compiler
work data set. Usually, a large buffer size improves the performance of the
compiler.
BUFSIZE option syntax
BUFSIZE(
nnnnn
nnnK
)
Default is: 4096
Abbreviations are: BUF
nnnnn specifies a decimal number that must be at least 256.
nnnK specifies a decimal number in 1 KB increments, where 1 KB = 1024 bytes.
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.
CICS
The CICS compiler option enables the integrated CICS translator and lets you
specify CICS suboptions. You must use the CICS option if your COBOL source
program contains EXEC CICS or EXEC DLI statements and the program has not been
processed by the separate CICS translator.
CICS option syntax
NOCICS
CICS
("CICS-suboption-string")
Default is: NOCICS
Abbreviations are: None
Use the CICS option only to compile CICS programs. Programs compiled with the
CICS option will not run in a non-CICS environment.
Chapter 17. Compiler options
321
If you specify the NOCICS option, any CICS statements found in the source program
are diagnosed and discarded.
Use either quotation marks or single quotation marks to delimit the string of CICS
suboptions.
You can partition a long CICS suboption string into multiple suboption strings in
multiple CBL or PROCESS statements. The CICS suboptions are concatenated in the
order of their appearance. For example:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL=’CICS("string1")’
//COBOL.SYSIN DD *
CBL CICS(’string2’)
CBL CICS("string3")
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
. . .
The compiler passes the following suboption string to the integrated CICS
translator:
"string1 string2 string3"
The concatenated strings are delimited with single spaces as shown. If multiple
instances of the same CICS suboption are found, the last specification of that
suboption in the concatenated string prevails. The compiler limits the size of the
concatenated suboption string to 4 KB.
RELATED CONCEPTS
“Integrated CICS translator” on page 427
RELATED TASKS
“Compiling with the CICS option” on page 425
“Separating CICS suboptions” on page 427
CICS Application Programming Guide (Specifying CICS translator options)
RELATED REFERENCES
“Conflicting compiler options” on page 314
CODEPAGE
Use CODEPAGE to specify the coded character set identifier (CCSID) for an EBCDIC
code page for processing compile-time and runtime COBOL operations that are
sensitive to character encoding.
CODEPAGE option syntax
CODEPAGE(ccsid)
Default is: CODEPAGE(1140)
Abbreviations are: CP(ccsid)
322
Enterprise COBOL for z/OS, V5.1 Programming Guide
ccsid must be an integer that represents a valid CCSID for an EBCDIC code page.
|
The default CCSID 1140 is the equivalent of CCSID 37 (COM EUROPE EBCDIC),
but additionally includes the euro symbol.
ccsid specifies these encodings:
v The encoding for alphanumeric, national, and DBCS literals in a COBOL source
program
v The default encoding of the content of alphanumeric and DBCS data items at
run time
v The encoding for DBCS user-defined words when processed by an XML GENERATE
statement to create XML element and attribute names
v The default encoding of an XML document created by an XML GENERATE
statement if the receiving data item for the document is alphanumeric
v The default encoding assumed for an XML document in an alphanumeric data
item when the document is processed by an XML PARSE statement
The CODEPAGE ccsid is used when code-page-sensitive operations are performed at
compile time or run time, and an explicit CCSID that overrides the default code
page is not specified. Such operations include:
v Conversion of literal values to Unicode
v Conversion of alphanumeric data to and from national (Unicode) data as part of
move operations, comparison, or the intrinsic functions DISPLAY-OF and
NATIONAL-OF
v Object-oriented language such as INVOKE statements or class definitions and
method definitions
v XML parsing
v XML generation
v Processing of DBCS names as part of XML generation at run time
v Processing of SQL string host variables if the SQLCCSID option is in effect
v Processing of source code for EXEC SQL statements
However, the encoding of the following items in a COBOL source program is not
affected by the CODEPAGE compiler option:
v Data items that have USAGE NATIONAL
These items are always encoded in UTF-16 in big-endian format, CCSID 1200.
v Characters from the basic COBOL character set (see the table of these characters
in the related reference below about characters)
Though the encoding of the basic COBOL characters default currency sign ($),
quotation mark ("), and the lowercase Latin letters varies in different EBCDIC
code pages, the compiler always interprets these characters using the EBCDIC
code page 1140 encoding. In particular, the default currency sign is always the
character with value X’5B’ (unless changed by the CURRENCY compiler option or
the CURRENCY SIGN clause in the SPECIAL-NAMES paragraph), and the quotation
mark is always the character with value X’7F’.
Some COBOL operations can override the CODEPAGE ccsid by using an explicit
encoding specification, for example:
v DISPLAY-OF and NATIONAL-OF intrinsic functions that specify a code page as the
second argument
v XML PARSE statements that specify the WITH ENCODING phrase
Chapter 17. Compiler options
323
v XML GENERATE statements that specify the WITH ENCODING phrase
Additionally, you can use the CURRENCY compiler option or the CURRENCY SIGN
clause in the SPECIAL-NAMES paragraph to override:
v The default currency symbol used in the PICTURE character-strings for
numeric-edited data items in your source program
v The currency sign value used in the content of numeric-edited data items at run
time
DBCS code pages:
Compile your COBOL program using the CODEPAGE option with the ccsid set to one
of the EBCDIC multibyte character set (MBCS) CCSIDs shown in the table below if
the program contains any of the following items:
v User-defined words formed with DBCS characters
v DBCS (USAGE DISPLAY-1) data items
v DBCS literals
All of the CCSIDs in the table below identify mixed code pages that refer to a
combination of SBCS and DBCS coded character sets. These are also the CCSIDs
that are supported for mixed data by DB2.
Table 45. EBCDIC multibyte coded character set identifiers
National language
MBCS CCSID
SBCS CCSID
component
DBCS CCSID
component
Japanese (Katakana-Kanji)
930
290
300
Japanese (Katakana-Kanji with euro)
1390
8482
16684
Japanese (Katakana-Kanji)
5026
290
4396
Japanese (Latin-Kanji)
939
1027
300
Japanese (Latin-Kanji with euro)
1399
5123
16684
Japanese (Latin-Kanji)
5035
1027
4396
Korean
933
833
834
Korean
1364
13121
4930
Simplified Chinese
935
836
837
Simplified Chinese
1388
13124
4933
Traditional Chinese
937
28709
835
Note: If you specify the TEST option, you must set the CODEPAGE option to the
CCSID that is used for the COBOL source program. In particular, programs that
use Japanese characters in DBCS literals or DBCS user-defined words must be
compiled with the CODEPAGE option set to a Japanese codepage CCSID.
|
|
|
|
RELATED CONCEPTS
“COBOL and DB2 CCSID determination” on page 439
RELATED TASKS
“Using currency signs” on page 67
Chapter 28, “Processing XML input,” on page 519
Chapter 29, “Producing XML output,” on page 557
324
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
“CURRENCY”
“SQLCCSID” on page 361
“TEST” on page 364
“The encoding of XML documents” on page 537
Characters (Enterprise COBOL Language Reference)
|
|
COMPILE
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 if the compilation resulted in serious errors: the
results could be unpredictable or an abnormal termination could occur.
COMPILE option syntax
NOCOMPILE(
S
E
W
)
COMPILE
NOCOMPILE
Default is: NOCOMPILE(S)
Abbreviations are: C|NOC
Use NOCOMPILE without any suboption to request a syntax check (only diagnostics
produced, no object code). If you use NOCOMPILE without any suboption, several
compiler options will have no effect because no object code will be produced, for
example: DECK, LIST, OBJECT, OFFSET, OPTIMIZE, SSRANGE, and TEST.
Use NOCOMPILE with suboption 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.
RELATED TASKS
“Finding coding errors” on page 384
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 287
CURRENCY
You can use the CURRENCY option to provide an alternate default currency symbol
to be used for a COBOL program. (The default currency symbol is the dollar sign
($).)
Chapter 17. Compiler options
325
CURRENCY option syntax
NOCURRENCY
CURRENCY(literal)
Default is: NOCURRENCY
Abbreviations are: CURR|NOCURR
NOCURRENCY specifies that no alternate default currency symbol will be used.
To change the default currency symbol, specify CURRENCY(literal), where literal is a
valid COBOL alphanumeric literal (optionally a hexadecimal literal) that represents
a single character. The literal must not be from the following list:
v Digits zero (0) through nine (9)
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
v
v
v
v
Special characters * + - / , . ; ( ) " =
A figurative constant
A null-terminated literal
A DBCS literal
A national literal
If your program processes only one currency type, you can use the CURRENCY
option as an alternative to the CURRENCY SIGN clause for indicating 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: You can delimit the CURRENCY option literal with either quotation marks
or single quotation marks, regardless of the QUOTE|APOST compiler option setting.
RELATED TASKS
“Using currency signs” on page 67
DATA
The DATA option affects whether storage for dynamic data areas and other dynamic
runtime storage is obtained from above or below the 16 MB line.
326
Enterprise COBOL for z/OS, V5.1 Programming Guide
DATA option syntax
DATA(
31
24
)
Default is: DATA(31)
Abbreviations are: None
For reentrant programs, the DATA compiler optioncontrols whether storage for
dynamic data areas (such as WORKING-STORAGE and FD record areas) is obtained from
below the 16 MB line (DATA(24)) or from unrestricted storage (DATA(31)). (DATA
does not affect the location of LOCAL-STORAGE data; the STACK runtime option
controls that location instead, along with the AMODE of the program.)
|
Specify DATA(24) for programs that run in 31-bit addressing mode and that pass
data arguments to programs in 24-bit addressing mode. Doing so ensures that the
data will be addressable by the called program.
External data and QSAM buffers: The DATA option interacts with other compiler
options and runtime options that affect storage and its addressability. See the
related information for details.
RELATED CONCEPTS
“Storage and its addressability” on page 40
RELATED TASKS
Language Environment Programming Guide (Using runtime options)
RELATED REFERENCES
“Allocation of buffers for QSAM files” on page 187
DBCS
Using DBCS causes the compiler to recognize X’0E’ (SO) and X’0F’ (SI) as shift
codes for the double-byte portion of an alphanumeric literal.
DBCS option syntax
DBCS
NODBCS
Default is: DBCS
Abbreviations are: None
With DBCS in effect, the double-byte portion of the literal is syntax-checked and the
literal remains category alphanumeric.
Chapter 17. Compiler options
327
RELATED REFERENCES
“Conflicting compiler options” on page 314
DECK
Use DECK to produce object code in the form of 80-column records. If you use the
DECK option, be certain that SYSPUNCH is defined in your JCL for compilation.
DECK option syntax
NODECK
DECK
Default is: NODECK
Abbreviations are: D|NOD
RELATED TASKS
“Creating object code (SYSLIN or SYSPUNCH)” on page 277
DIAGTRUNC
DIAGTRUNC causes the compiler to issue a severity-4 (Warning) diagnostic message
for MOVE statements that have numeric receivers when the receiving data item has
fewer integer positions than the sending data item or literal. In statements that
have multiple receivers, the message is issued separately for each receiver that
could be truncated.
DIAGTRUNC option syntax
NODIAGTRUNC
DIAGTRUNC
Default is: NODIAGTRUNC
Abbreviations are: DTR|NODTR
The diagnostic message is also issued for implicit moves associated with
statements such as these:
v INITIALIZE
v
v
v
v
328
READ . . . INTO
RELEASE . . . FROM
RETURN . . . INTO
REWRITE . . . FROM
Enterprise COBOL for z/OS, V5.1 Programming Guide
v WRITE . . . FROM
The diagnostic message 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 message for COMP-5 receivers, nor for binary receivers when
you specify the TRUNC(BIN) option.
RELATED CONCEPTS
“Formats for numeric data” on page 49
“Reference modifiers” on page 117
RELATED REFERENCES
“TRUNC” on page 368
|
|
|
DISPSIGN
The DISPSIGN option controls output formatting for DISPLAY of signed numeric
items.
|
|
DISPSIGN option syntax
|
DISPSIGN(
COMPAT
SEP
)
|
||
|
Default is: DISPSIGN(COMPAT)
|
Abbreviations are: DS(C | S)
|
|
|
|
DISPSIGN(COMPAT)
If you specify DISPSIGN(COMPAT), formatting for displayed values of signed
numeric items is compatible with prior versions of Enterprise COBOL.
Overpunch signs are generated in some cases.
|
|
|
|
DISPSIGN(SEP)
If you specify DISPSIGN(SEP), the displayed values for signed binary,
signed packed-decimal, or overpunch signed zoned-decimal items are
always formatted with a leading separate sign.
|
|
The following example shows the DISPLAY output with the DISPSIGN(COMPAT)
option or the DISPSIGN(SEP) option specified:
|
|
Table 46. DISPLAY output with the DISPSIGN(SEP) option or the DISPSIGN(SEP) option
specified:
|
|
|
Data items
DISPLAY output with the
DISPSIGN(COMPAT) option
specified
DISPLAY output with the
DISPSIGN(SEP) option
specified
|
Unsigned binary
111
111
|
Positive binary
111
+111
|
Negative binary
11J
-111
Chapter 17. Compiler options
329
|
|
|
|
|
Table 46. DISPLAY output with the DISPSIGN(SEP) option or the DISPSIGN(SEP) option
specified: (continued)
Data items
DISPLAY output with the
DISPSIGN(COMPAT) option
specified
DISPLAY output with the
DISPSIGN(SEP) option
specified
|
Unsigned packed-decimal
222
222
|
Positive packed-decimal
222
+222
|
Negative packed-decimal
22K
-222
|
Zoned-decimal unsigned
333
333
|
|
Zoned-decimal trailing
positive
33C
+333
|
|
Zoned-decimal trailing
negative
33L
-333
|
|
Zoned-decimal leading
positive
C33
+333
|
|
|
Zoned-decimal leading
negative
L33
-333
|
DLL
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 or class definitions.
DLL option syntax
NODLL
DLL
Default is: NODLL
Abbreviations are: None
Link-edit considerations: COBOL programs that are compiled with the DLL option
must be link-edited with the RENT and AMODE(31) link-edit options.
NODLL instructs the compiler to generate an object module that is not enabled for
DLL usage.
RELATED TASKS
“Making dynamic calls” on page 465
RELATED REFERENCES
“Conflicting compiler options” on page 314
330
Enterprise COBOL for z/OS, V5.1 Programming Guide
DUMP
Use DUMP to produce a system dump at compile time for an internal compiler error.
DUMP option syntax
NODUMP
DUMP
Default is: NODUMP
Abbreviations are: DU|NODU
Not for general use: The DUMP option should be used only 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 Diagnostic messages produced so far in compilation.
v A description of the error.
v The name of the compiler phase currently executing.
|
|
v The line number of the COBOL statement being processed when the error was
found. (If you compiled with OPTIMIZE(1|2), 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(1|2) 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 does not represent a compiler error. Using the NODUMP option will
allow the compiler to issue message IGYOP3124-W and continue processing.
RELATED TASKS
Language Environment Debugging Guide (Understanding abend codes)
Chapter 17. Compiler options
331
RELATED REFERENCES
“Conflicting compiler options” on page 314
DYNAM
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.
CALL identifier statements always result in a runtime load of the target program and
are not affected by this option.
DYNAM option syntax
NODYNAM
DYNAM
Default is: NODYNAM
Abbreviations are: DYN|NODYN
Restriction: The DYNAM compiler option must not be used in the following cases:
v COBOL programs that are processed by the CICS translator or the CICS compiler
option
v COBOL programs that have EXEC SQL statements and are run under CICS or
DB2 call attach facility (CAF)
If your COBOL program calls programs that have been linked as dynamic link
libraries (DLLs), you must not use the DYNAM option. You must instead compile the
program with the NODYNAM and DLL options.
RELATED TASKS
“Making both static and dynamic calls” on page 470
“Choosing the DYNAM or NODYNAM compiler option” on page 443
RELATED REFERENCES
“Conflicting compiler options” on page 314
EXIT
Use the EXIT option to provide user-supplied modules in place of various compiler
functions.
For compiler input, use the INEXIT and LIBEXIT suboptions to provide modules in
place of SYSIN and SYSLIB (or copy library), respectively. For compiler output, use
the PRTEXIT suboption to provide a module in place of SYSPRINT.
To provide a module that will be called for each SYSADATA record immediately
after the record has been written out to the file, use the ADEXIT suboption.
332
Enterprise COBOL for z/OS, V5.1 Programming Guide
To customize compiler messages (change their severity or suppress them, including
converting FIPS (FLAGSTD) messages to diagnostic messages to which you assign a
severity), use the MSGEXIT suboption. The module that you provide to customize
the messages will be called each time the compiler issues a diagnostic message or a
FIPS message.
EXIT option syntax
NOEXIT
EXIT( )
INEXIT(
mod1)
str1,
NOINEXIT
LIBEXIT(
mod2)
str2,
NOLIBEXIT
PRTEXIT(
mod3)
str3,
NOPRTEXIT
ADEXIT(
mod4)
str4,
NOADEXIT
MSGEXIT(
mod5)
str5,
NOMSGEXIT
Default is: NOEXIT
Abbreviations are: NOEX|EX(INX|NOINX, LIBX|NOLIBX, PRTX|NOPRTX, ADX|NOADX,
MSGX|NOMSGX)
You can specify the suboptions in any order, and can separate them by either
commas or spaces. If you specify both the positive and negative form of a
suboption, the form specified last takes effect. If you specify the same suboption
more than once, the last one specified takes effect.
If you specify the EXIT option without specifying at least one suboption, NOEXIT
will be in effect.
You can specify the EXIT option only at invocation in the JCL PARM field (under
TSO/E, in a command argument) or at installation time. Do not specify the EXIT
option in a PROCESS (CBL) statement.
INEXIT([’str1’,]mod1)
The compiler reads source code from a user-supplied load module (where
mod1 is the module name) instead of SYSIN.
LIBEXIT([’str2’,]mod2)
The compiler obtains copybooks from a user-supplied load module (where
mod2 is the module name) instead of library-name or SYSLIB. For use with
either COPY or BASIS statements.
Chapter 17. Compiler options
333
PRTEXIT([’str3’,]mod3)
The compiler passes printer-destined output to the user-supplied load
module (where mod3 is the module name) instead of SYSPRINT.
ADEXIT([’str4’,]mod4)
The compiler passes the SYSADATA output to the user-supplied load
module (where mod4 is the module name).
MSGEXIT([’str5’,]mod5)
The compiler passes the message number, and passes the default severity
of a compiler diagnostic message, or the category (as a numeric code) of a
FIPS compiler message, to the user-supplied load module (where mod5 is
the module name).
The names mod1, mod2, mod3, mod4, and mod5 can refer to the same module.
The suboptions str1, str2, str3, str4, and str5 are character strings that are passed to
the load module. These strings are optional. They can be up to 64 characters in
length, and you must enclose them in single quotation marks. You can use any
character in the strings, but any included single quotation marks must be doubled.
Lowercase characters are folded to uppercase.
If one of str1, str2, str3, str4, or str5 is specified, that string is passed to the
appropriate user-exit module in the following format, where LL is a halfword (on a
halfword boundary) that contains the length of the string.
LL string
“Example: MSGEXIT user exit” on page 709
|
|
|
|
|
Compiler exit modules that are specified on the EXIT option can be implemented
either in an assembler language or in a high-level programming language such as
COBOL. However, when exits are written in a Language Environment conforming
programming language or Language Environment conforming assembler language,
the exit must be reentrant.
|
|
|
|
|
|
|
|
|
The Enterprise COBOL compiler automatically manages a preinitialized Language
Environment at compile time, and calls compiler exits within this environment.
Therefore, the following rules apply:
v Compiler exits are run as subprograms instead of main programs.
v Compiler exits must not include logic for explicitly initializing or terminating
Language Environment. In particular, exits must not use the RTEREUS runtime
option, the IGZERRE callable service, or the CEEPIPI callable service for
environment management.
v Compiler exits must not use the STOP RUN statement.
RELATED REFERENCES
“Conflicting compiler options” on page 314
“FLAGSTD” on page 337
Appendix D, “EXIT compiler option,” on page 697
334
Enterprise COBOL for z/OS, V5.1 Programming Guide
EXPORTALL
Use EXPORTALL to instruct the compiler to automatically export the PROGRAM-ID
name and each alternate entry-point name from each program definition when the
object deck is link-edited to form a DLL.
EXPORTALL option syntax
NOEXPORTALL
EXPORTALL
Default is: NOEXPORTALL
Abbreviations are: EXP|NOEXP
With these symbols exported from the DLL, the exported program and entry-point
names can be called from programs in the root load module, in other DLL load
modules in the application, and from programs that are linked into that DLL.
Specification of the EXPORTALL option requires that the RENT linker option also be
used.
NOEXPORTALL instructs the compiler to not export any symbols. In this case the
programs are accessible only from other routines that are link-edited into the same
load module as the COBOL program definition.
RELATED REFERENCES
“Conflicting compiler options” on page 314
FASTSRT
Use FASTSRT to let IBM DFSORT, or an equivalent product, perform sort input and
output instead of Enterprise COBOL.
FASTSRT option syntax
NOFASTSRT
FASTSRT
Default is: NOFASTSRT
Abbreviations are: FSRT|NOFSRT
RELATED TASKS
“Improving sort performance with FASTSRT” on page 237
Chapter 17. Compiler options
335
FLAG
Use FLAG(x) to produce diagnostic messages at the end of the source listing for
errors of a severity level x or above.
FLAG option syntax
FLAG(x
)
,y
NOFLAG
Default is: FLAG(I,I)
Abbreviations are: F|NOF
x and y can be either I, W, E, S, or U.
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 the embedding of the statement
number in an arrow that points to the message code. The message code is 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.
. . .
When FLAG(x,y) is in effect, messages of severity y and above are embedded in the
listing after the line that caused the message. (See the related reference below for
information about messages for exceptions.)
Use NOFLAG to suppress error flagging. NOFLAG does not suppress error messages for
compiler options.
Embedded messages
v Embedding level-U messages is not recommended. The specification of
embedded level-U messages is accepted, but does not produce any messages in
the source.
v The FLAG option does not affect diagnostic messages that are produced before
the compiler options are processed.
v Diagnostic messages that are produced during processing of compiler options,
CBL or PROCESS statements, or BASIS, COPY, or REPLACE statements are not
embedded in the source listing. All such messages appear at the beginning of
the compiler output.
336
Enterprise COBOL for z/OS, V5.1 Programming Guide
v Messages that are produced during processing of the *CONTROL or *CBL statement
are not embedded in the source listing.
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 287
FLAGSTD
Use FLAGSTD to specify the level or subset of Standard COBOL 85 to be regarded as
conforming, and to get informational messages about Standard COBOL 85
elements that are included in your program.
You can specify any of the following items for flagging:
v A selected Federal Information Processing Standard (FIPS) COBOL subset
v Any of the optional modules
v Obsolete language elements
v Any combination of subset and optional modules
v Any combination of subset and obsolete elements
v IBM extensions (these are flagged any time that FLAGSTD is specified, and
identified as "nonconforming nonstandard")
FLAGSTD option syntax
NOFLAGSTD
FLAGSTD(x
)
yy
,O
Default is: NOFLAGSTD
Abbreviations are: None
x specifies the subset of Standard COBOL 85 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.
Elements that are IBM extensions 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."
Chapter 17. Compiler options
337
S
Elements from segmentation module level 2 are not flagged as
"nonconforming standard."
If S is specified, N is included (N is a subset of S).
O (the letter) specifies that obsolete language elements are flagged as "obsolete."
The informational messages appear in the source program listing, and identify:
v The element as "obsolete," "nonconforming standard," or "nonconforming
nonstandard" (a language element that is both obsolete and nonconforming is
flagged as obsolete only)
v The clause, statement, or header that contains the element
v The source program line and beginning location of the clause, statement, or
header that contains the element
v 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 with the associated message code and
text. After that is a summary of the total number of 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
obsolete element
NONSTANDARD
1
OBSOLETE
1
You can convert FIPS informational messages into diagnostic messages, and can
suppress FIPS messages, by using the MSGEXIT suboption of the EXIT compiler
option. For details, see the related reference about the processing of MSGEXIT, and
see the related task.
RELATED TASKS
“Customizing compiler-message severities” on page 706
RELATED REFERENCES
“Conflicting compiler options” on page 314
“Processing of MSGEXIT” on page 705
|
HGPR
The HGPR option controls the compiler usage of the 64-bit registers provided by
z/Architecture processors.
|
|
|
338
Enterprise COBOL for z/OS, V5.1 Programming Guide
HGPR option syntax
|
|
HGPR(
PRESERVE
NOPRESERVE
)
|
||
|
Default is: HGPR(PRESERVE)
|
Abbreviations are: None
|
|
|
The Enterprise COBOL compiler uses the 64-bit width of the z/Architecture
General Purpose Registers (GPRs). HGPR stands for "High-halves of 64-bit GPRs",
which means the use of native 64-bit instructions.
|
|
|
|
|
|
HGPR(PRESERVE)
If you specify HGPR(PRESERVE), the compiler preserves the high halves of
the 64-bit GPRs that a program is using, by saving them in the prolog for
the function and restoring them in the epilog. The PRESERVE suboption is
necessary only if the caller of the program is not Enterprise COBOL,
Enterprise PL/I, or z/OS XL C/C++ compiler-generated code.
|
|
|
|
HGPR(NOPRESERVE)
If you specify HGPR(NOPRESERVE), the compiler omits preserving the
high-halves of the 64-bit GPRs that a program is using, which improves
performance.
INTDATE
INTDATE(ANSI) instructs the compiler to use the Standard COBOL 85 starting date
for integer dates used with date intrinsic functions. Day 1 is Jan 1, 1601.
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.
INTDATE option syntax
INTDATE(
ANSI
LILIAN
)
Default is: INTDATE(ANSI)
Abbreviations are: None
With INTDATE(LILIAN), the date intrinsic functions return results that are
compatible with the Language Environment date callable services.
Usage note: When INTDATE(LILIAN) is in effect, CEECBLDY is not usable because
you have no way to turn an ANSI integer into a meaningful date by using either
intrinsic functions or callable services. If you code a CALL literal statement with
CEECBLDY as the target of the call when INTDATE(LILIAN) in effect, the compiler
diagnoses this and converts the call target to CEEDAYS.
Chapter 17. Compiler options
339
RELATED TASKS
“Using date callable services” on page 62
LANGUAGE
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).
LANGUAGE option syntax
LANGUAGE(name)
Default is: LANGUAGE(ENGLISH)
Abbreviations are: LANG(EN|UE|JA|JP)
name specifies the language for compiler output messages. Possible values for the
LANGUAGE option are shown in the table below.
Table 47. Values of the LANGUAGE compiler option
Name
Abbreviation1
Output language
ENGLISH
EN
Mixed-case English (the default)
JA, JP
Japanese, using the Japanese character set
UE
Uppercase English
JAPANESE
UENGLISH
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.
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 runtime option allows you to control the national language
to be used for the runtime environment, including error messages, month names,
and day-of-the-week names. The LANGUAGE compiler option and the NATLANG
runtime option act independently of each other. You can use them together with
neither taking precedence over the other.
340
Enterprise COBOL for z/OS, V5.1 Programming Guide
LINECOUNT
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.
LINECOUNT option syntax
LINECOUNT(nnn)
Default is: LINECOUNT(60)
Abbreviations are: LC
nnn must be an integer between 10 and 255, or 0.
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.
LIST
Use the LIST compiler option to produce a listing of the assembler-language
expansion of your source code.
LIST option syntax
NOLIST
LIST
Default is: NOLIST
Abbreviations are: None
|
|
|
|
|
|
|
|
These items will also be written to the output listing:
v Constant area
v Program prolog areas (PPA1, PPA2, PPA3, PPA4)
v Time stamp and compiler version information
v Compiler options and program information
v Base locator table
v External symbols dictionary
v Static maps
v Automatic maps
Chapter 17. Compiler options
341
The output is generated if:
v You specify the COMPILE option, or the NOCOMPILE(x) option is in effect and an
error of 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 (or *CBL) LIST or
NOLIST statements in the PROCEDURE DIVISION. Source statements that follow a
*CONTROL NOLIST statement are not included in the listing until a subsequent
*CONTROL LIST statement switches the output back to normal LIST format.
RELATED TASKS
“Getting listings” on page 390
RELATED REFERENCES
“Conflicting compiler options” on page 314
*CONTROL (*CBL) statement (Enterprise COBOL Language Reference)
MAP
Use MAP to produce a listing of the items defined in the DATA DIVISION.
MAP option syntax
NOMAP
MAP
Default is: NOMAP
Abbreviations are: None
The output includes the following items:
v DATA DIVISION map
v
v
v
v
Global tables
Literal pools
Nested program structure map, and program attributes
Size of the program's WORKING-STORAGE and LOCAL-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 that follow *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
342
Enterprise COBOL for z/OS, V5.1 Programming Guide
data-name definitions in the FILE SECTION, LOCAL-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 395
RELATED CONCEPTS
Chapter 19, “Debugging,” on page 379
RELATED TASKS
“Getting listings” on page 390
RELATED REFERENCES
*CONTROL (*CBL) statement (Enterprise COBOL Language Reference)
|
|
|
|
|
|
|
MAXPCF
Use the MAXPCF option to specify a maximum program complexity factor value. The
program complexity factor (PCF) is computed by the compiler and the computed
value is in the listing file. If the PCF of your program exceeds the maximum value,
the compiler will automatically reduce the optimization level to speed up the
compilation and use less storage. Therefore, when you compile a suite of
programs, you do not have to specify an OPTIMIZE option value for each program.
|
|
MAXPCF option syntax
|
|
||
MAXPCF(n)
|
Default is: MAXPCF(60000)
|
Abbreviations are: None
|
n must be an integer of 0 - 999999.
|
|
|
|
|
|
The aspects of the program taken into consideration when computing the
complexity factor include:
v The number of COBOL statements in the PROCEDURE DIVISION, including
generated statements from the SQL or CICS options and the expansion of COPY
statements
v Initialization operations for WORKING-STORAGE or LOCAL-STORAGE data items with
value clauses
v Operations for variable-length groups or subgroups in the DATA DIVISION, which
compute their size at run time
|
|
If you specify MAXPCF(0), no limit is enforced on the complexity of the program,
and the MAXPCF option has no effect.
|
|
|
If you specify MAXPCF(n) and n is not zero, when the program complexity factor
exceeds n, any specification of OPTIMIZE(1) or OPTIMIZE(2) is reset to OPTIMIZE(0),
and a warning message is generated.
|
|
|
Chapter 17. Compiler options
343
|
|
If the COBOL source file contains a sequence of source programs (a batch compile),
the MAXPCF limit is applied on per program basis.
|
|
|
|
Note: If the OPTIMIZE(1) or OPTIMIZE(2) option is set at installation time as a fixed,
nonoverridable option, then MAXPCF(n) with a nonzero n is an option conflict. In
this case, the OPTIMIZE option takes precedence and the MAXPCF(0) option is forced
on.
|
|
RELATED REFERENCES
“OPTIMIZE” on page 351
|
MDECK
The MDECK compiler option specifies that a copy of the updated input source after
library processing (that is, the result of COPY, BASIS, REPLACE, and EXEC SQL INCLUDE
statements) is written to a file.
If Enterprise COBOL is running under z/OS UNIX, the MDECK output is written in
the current directory to a file that has the same name as the COBOL source file and
a suffix of .dek. For Enterprise COBOL running under TSO or batch, the MDECK
output is written to the data set defined by the SYSMDECK DD allocation, which must
specify an MVS data set that has RECFM F or FB and an LRECL of 80 bytes.
Note: When compiling under z/OS TSO or batch, the COBOL compiler requires
the SYSMDECK data set allocation for all compilations, no matter if you specify the
MDECK or NOMDECK option:
|
|
|
|
|
|
|
v If you specify the MDECK option, the SYSMDECK DD allocation must specify a
permanent data set.
v If you specify the NOMDECK option, the SYSMDECK DD allocation can specify either
a temporary utility data set or a permanent data set.
MDECK option syntax
NOMDECK
MDECK
(
COMPILE
NOCOMPILE
)
Default is: NOMDECK
Abbreviations are: NOMD|MD|MD(C|NOC)
Option specification:
You cannot specify the MDECK option in a PROCESS (or CBL) statement. You can
specify it only in one of the following ways:
v In the PARM parameter of JCL
v As a cob2 command option
v As an installation default
344
Enterprise COBOL for z/OS, V5.1 Programming Guide
v In the COBOPT environment variable
Suboptions:
v When MDECK(COMPILE) is in effect, compilation continues normally after library
processing and generation of the MDECK output file have completed, subject to the
settings of the COMPILE|NOCOMPILE, DECK|NODECK, and OBJECT|NOOBJECT compiler
options.
v When MDECK(NOCOMPILE) is in effect, compilation is terminated after library
processing has completed and the expanded source program file has been
written. The compiler does no further syntax checking or code generation
regardless of the settings of the COMPILE, DECK, and OBJECT compiler options.
If you specify MDECK with no suboption, MDECK(COMPILE) is implied.
Contents of the MDECK output file:
If you use the MDECK option with programs that contain EXEC CICS or EXEC SQL
statements, these EXEC statements are included in the MDECK output as is. However,
if you compile using the SQL option, EXEC SQL INCLUDE statements are expanded in
the MDECK output.
CBL, PROCESS, *CONTROL, and *CBL card images are passed to the MDECK output file in
the proper locations.
For a batch compilation (multiple COBOL source programs in a single input file), a
single MDECK output file that contains the complete expanded source is created.
Any SEQUENCE compiler-option processing is reflected in the MDECK file.
COPY statements are included in the MDECK file as comments.
RELATED TASKS
“Starting the compiler from an assembler program” on page 271
“Defining the library-processing output file (SYSMDECK)” on page 278
RELATED REFERENCES
“Conflicting compiler options” on page 314
Chapter 18, “Compiler-directing statements,” on page 375
NAME
Use NAME to generate a link-edit NAME card for each object module. You can also use
NAME to generate names for each load module when you are 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.
Chapter 17. Compiler options
345
NAME option syntax
NONAME
NAME
NOALIAS
ALIAS
(
)
Default is: NONAME, or NAME(NOALIAS) if only NAME is specified
Abbreviations are: None
If you specify NAME(ALIAS), and your program contains ENTRY statements, a
link-edit ALIAS card is generated for each ENTRY statement.
RELATED REFERENCES
PROGRAM-ID paragraph (Enterprise COBOL Language Reference)
NSYMBOL
The NSYMBOL option controls the interpretation of the N symbol used in literals and
PICTURE clauses, indicating whether national or DBCS processing is assumed.
NSYMBOL option syntax
NSYMBOL(
NATIONAL
DBCS
)
Default is: NSYMBOL(NATIONAL)
Abbreviations are: NS(NAT|DBCS)
With NSYMBOL(NATIONAL):
v Data items defined with a PICTURE clause that consists only of the symbol N
without the USAGE clause are treated as if the USAGE NATIONAL clause is specified.
v Literals of the form N". . ." or N’. . .’ are treated as national literals.
With NSYMBOL(DBCS):
v Data items defined with a PICTURE clause that consists only of the symbol N
without the USAGE clause are treated as if the USAGE DISPLAY-1 clause is specified.
v Literals of the form N". . ." or N’. . .’ are treated as DBCS literals.
The NSYMBOL(DBCS) option provides compatibility with previous releases of IBM
COBOL, and the NSYMBOL(NATIONAL) option makes the handling of the above
language elements consistent with Standard COBOL 2002 in this regard.
NSYMBOL(NATIONAL) is recommended for applications that use Unicode data or
object-oriented syntax for Java interoperability.
346
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
“Conflicting compiler options” on page 314
NUMBER
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.
NUMBER option syntax
NONUMBER
NUMBER
Default is: NONUMBER
Abbreviations are: NUM|NONUM
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 copybook line numbers are coordinated.
If you are doing a batch compilation and NUMBER is 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.
NUMPROC
Use NUMPROC(NOPFD) if your internal decimal and zoned decimal data might use
nonpreferred signs.
|
Chapter 17. Compiler options
347
NUMPROC option syntax
|
|
NUMPROC(
NOPFD
PFD
)
|
Default is: NUMPROC(NOPFD)
Abbreviations are: None
The compiler accepts any valid sign configuration: X'A', X'B', X'C', X'D', X'E', or
X'F'. NUMPROC(NOPFD) is the recommended option in most cases.
Performance considerations: NUMPROC(PFD) improves the performance of
processing internal decimal and zoned decimal data. Use this option however only
if your numeric data agrees exactly with the following IBM system standards:
v Zoned decimal, unsigned: High-order 4 bits of the sign byte contain X'F'.
v Zoned decimal, signed overpunch: High-order 4 bits of the sign byte contain
X'C' if a number is positive or 0, and X'D' if it is not.
v Zoned decimal, separate sign: Separate sign contains the character '+' if a
number is positive or 0, and '-' if it is not.
v Internal decimal, unsigned: Low-order 4 bits of the low-order byte contain X'F'.
v Internal decimal, signed: Low-order 4 bits of the low-order byte contain X'C' if
a number is positive or 0, and X'D' if it is not.
Data produced by COBOL arithmetic statements conforms to the IBM system
standards described above. 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. Use NUMPROC(NOPFD) if a
COBOL program calls programs written in PL/I or FORTRAN.
Sign representation is affected not only by the NUMPROC option, but also by the
NUMCLS installation option.
RELATED TASKS
“Checking for incompatible data (numeric class test)” on page 56
RELATED REFERENCES
“Sign representation of zoned and packed-decimal data” on page 55
OBJECT
Use OBJECT to write the generated object code to a file to be used as input for the
linkage editor or binder.
348
Enterprise COBOL for z/OS, V5.1 Programming Guide
OBJECT option syntax
OBJECT
NOOBJECT
Default is: OBJECT
Abbreviations are: OBJ|NOOBJ
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 output to 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 that your installation guidelines recommend.
RELATED REFERENCES
“Conflicting compiler options” on page 314
OFFSET
Use OFFSET to produce a condensed PROCEDURE DIVISION listing.
OFFSET option syntax
NOOFFSET
OFFSET
Default is: NOOFFSET
Abbreviations are: OFF|NOOFF
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 listing also shows:
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 314
Chapter 17. Compiler options
349
OPTFILE
Use OPTFILE to enable the specifying of COBOL compiler options in a data set.
Using a compiler-option data set circumvents the 100-character limit on options
specified in a JCL PARM string.
OPTFILE option syntax
OPTFILE
Default is: None
Abbreviations are: None
You can specify OPTFILE as a compiler invocation option or in the PROCESS or CBL
statement in your COBOL source program. OPTFILE cannot be specified as an
installation default.
OPTFILE is ignored if you compile using the cob2 command in the z/OS UNIX
environment. (In that environment, the COBOPT environment variable provides a
capability that is comparable to OPTFILE.)
If OPTFILE is in effect, compiler options are read from the data set that you identify
in a SYSOPTF DD statement. A SYSOPTF data set must have RECFM F or FB and an
LRECL of 80 bytes. For further details about the format of a SYSOPTF data set, see the
related task below about defining a compiler-option data set.
The precedence of options in the SYSOPTF data set is determined by where you
specify the OPTFILE option. For example, if you specify OPTFILE in the invocation
PARM string, an option specified later in the PARM string supersedes any option
specified in the SYSOPTF data set that conflicts with it.
(Conceptually, OPTFILE in an options specification is replaced with the options that
are in the SYSOPTF data set; then the usual rules about precedence of compiler
options and conflicting compiler options apply.)
If you start the COBOL compiler from within an assembler program, you can use
the alternate ddname list to specify a ddname to be used instead of SYSOPTF to
identify the compiler-option data set.
RELATED TASKS
“Starting the compiler from an assembler program” on page 271
“Defining a compiler-option data set (SYSOPTF)” on page 276
“Specifying compiler options under z/OS” on page 279
Chapter 15, “Compiling under z/OS UNIX,” on page 291
RELATED REFERENCES
“Conflicting compiler options” on page 314
350
Enterprise COBOL for z/OS, V5.1 Programming Guide
OPTIMIZE
Use OPTIMIZE to reduce the run time of your object program. Optimization might
also reduce the amount of storage your object program uses.
|
|
OPTIMIZE option syntax
|
OPTIMIZE (
0
1
2
)
|
||
|
Default is: OPTIMIZE(0)
|
Abbreviations are: OPT(0), OPT(1) or OPT(2)
|
|
|
|
|
|
|
The OPTIMIZE option specifies increasing levels of optimization to improve
application runtime performance. However, specifying the OPTIMIZE option
increases the compilation time and compilation storage requirements, and reduces
debugging capabilities.
v OPTIMIZE(0) specifies limited optimizations, which result in the shortest
compilation time. When the TEST option is specified, full debug capabilities are
available.
v OPTIMIZE(1) specifies optimizations that improve application runtime
performance. Optimizations at this level include basic inlining, strength
reduction, simplification of complex operations into equivalent simpler
operations, removal of some unreachable code and block rearrangement. Also,
OPTIMIZE(1) includes some intrablock optimizations such as common sub
expression elimination and value propagation. When the TEST option is
specified, most debug capabilities are available.
|
|
|
|
|
|
|
|
|
|
|
v OPTIMIZE(2) specifies further optimizations, which include more aggressive
simplifications and instruction scheduling. Also, some interblock optimizations
such as global value propagation and loop invariant code motion are included.
When the TEST option is specified, some debug capabilities are available.
|
|
|
|
All COBOL programs in an application that use the Language Environment service
CEEHDLR to register a user-written condition handler must be compiled with one of
the following configurations of compiler options:
v OPTIMIZE(0)
|
|
v OPTIMIZE(1) and TEST
v OPTIMIZE(2) and TEST
|
|
|
Use of user-written condition handling services is incompatible with the advanced
optimizations done with OPTIMIZE(1) or OPTIMIZE(2) and NOTEST, and can cause
unpredictable results.
|
|
|
Note: In Enterprise COBOL V5, the NOOPTIMIZE, OPTIMIZE, OPTIMIZE(STD), and
OPTIMIZE(FULL) options are deprecated but are tolerated for compatibility. If one of
those options is specified, it is mapped to the new option as follows:
Chapter 17. Compiler options
351
|
Table 48. Mapping of deprecated options to new options
|
Deprecated options
New options
|
NOOPTIMIZE
OPTIMIZE(0)
|
OPTIMIZE
OPTIMIZE(1)
|
OPTIMIZE(STD)
OPTIMIZE(1)
|
|
OPTIMIZE(FULL)
OPTIMIZE(1) and STGOPT
|
|
RELATED CONCEPTS
|
|
RELATED TASKS
|
|
|
|
|
RELATED REFERENCES
“Optimization” on page 659
“Writing routines for handling errors” on page 256
“Conflicting compiler options” on page 314
“MAXPCF” on page 343
“TEST” on page 364
“STGOPT” on page 363
|
OUTDD
Use OUTDD to specify that you want DISPLAY output that is directed to the system
logical output device to go to a specific ddname.
You can specify a file in the z/OS UNIX file system with the ddname named in
OUTDD. To understand where output is directed when this ddname is not allocated,
see the related task about displaying data.
OUTDD option syntax
OUTDD(ddname)
Default is: OUTDD(SYSOUT)
Abbreviations are: OUT
The MSGFILE runtime option lets you specify the ddname of the file to which all
runtime diagnostics and reports generated by the RPTOPTS and RPTSTG runtime
options are to be written. The IBM-supplied default is MSGFILE(SYSOUT). If the
OUTDD compiler option and the MSGFILE runtime option both specify the same
ddname, the error message information and DISPLAY output directed to the system
logical output device are routed to the same destination.
Restriction: The OUTDD option has no effect under CICS.
RELATED TASKS
“Displaying data on the system logical output device” on page 37
“Coding COBOL programs to run under CICS” on page 421
352
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
Language Environment Programming Reference (MSGFILE)
PGMNAME
The PGMNAME option controls the handling of program-names and entry-point
names.
PGMNAME option syntax
PGMNAME(
COMPAT
LONGMIXED
LONGUPPER
)
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.
PGMNAME controls the handling of names used in the following contexts:
v Program-names defined in the PROGRAM-ID paragraph
v Program entry-point names in the ENTRY statement
v Program-name references in:
– CALL statements that reference nested programs, statically linked programs, or
DLLs
– SET procedure-pointer or function-pointer statements that reference statically
linked programs or DLLs
– CANCEL statements that reference nested programs
PGMNAME(COMPAT)
With PGMNAME(COMPAT), program-names are handled in a manner compatible with
older versions of COBOL compilers:
v The program-name can be up to 30 characters in length.
v All the characters used in the name must be alphabetic, digits, the hyphen, or
the underscore, except that if the program-name is a literal and is in the
outermost program, then the literal can also contain the extension characters @,
#, and $, and the first character can be an underscore.
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).
Chapter 17. Compiler options
353
v If the first character is not alphabetic, and is not an underscore, it is converted as
follows:
– 1-9 are translated to A-I.
– Anything else is translated to J.
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 The program-name can be up to 30 characters in length.
v All the characters used in the name must be alphabetic, digits, the hyphen, or
the underscore.
v At least one character must be alphabetic.
v The hyphen cannot be used as the first or last character.
v The underscore cannot be used as the first character.
When a program-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, the hyphen, or
the underscore.
v At least one character must be alphabetic.
v The hyphen cannot be used as the first or last character.
v The underscore can be used in any position.
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, and is not an underscore, it is converted as
follows:
– 1-9 are translated to A-I.
– Anything else is translated to J.
Names of nested programs 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 user for a program-name can contain any character in the
range X’41’-X’FE’.
Usage notes
v The following elements 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 in COPY statements).
354
Enterprise COBOL for z/OS, V5.1 Programming Guide
– Dynamic calls.
Dynamic calls are resolved with truncation of the program-name to eight
characters, folding to uppercase, and translation of embedded hyphens or a
leading digit.
– CANCEL of nonnested programs. Name resolution uses the same mechanism as
for a dynamic call.
v Link-edit considerations: COBOL programs that are compiled with the
PGMNAME(LONGUPPER) or PGMNAME(LONGMIXED) option must be link-edited in AMODE
31.
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 When using the extended character set supported by PGMNAME(LONGMIXED), be
sure to use names that conform to the linkage-editor, binder, or system
conventions that apply, depending on the mechanism used to resolve the names.
Using characters such as commas or parentheses is not recommended, because
these characters are used in the syntax of linkage-editor and binder control
statements.
RELATED REFERENCES
PROGRAM-ID paragraph (Enterprise COBOL Language Reference)
QUOTE/APOST
Use QUOTE if you want the figurative constant [ALL] QUOTE or [ALL] QUOTES to
represent one or more quotation mark (") characters. Use APOST if you want the
figurative constant [ALL] QUOTE or [ALL] QUOTES to represent one or more single
quotation mark (') characters.
QUOTE/APOST option syntax
QUOTE
APOST
Default is: QUOTE
Abbreviations are: Q|APOST
Delimiters: You can use either quotation marks or single quotation marks 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
A program compiled as RENT is generated as a reentrant object program. A program
compiled as NORENT is generated as a nonreentrant object program.
Chapter 17. Compiler options
355
Either a reentrant or a nonreentrant program can be invoked as a main program or
as a subprogram.
RENT option syntax
RENT
NORENT
Default is: RENT
Abbreviations are: None
|
|
|
|
|
DATA and RMODE settings: The RENT option interacts with other compiler options that
affect storage and its addressability. Use the DATA(24|31) option for reentrant
programs to control whether dynamic data areas are allocated in unrestricted
storage or in storage obtained from below 16 MB. Compile programs with RENT if
they will be run in virtual storage addresses above 16 MB.
|
|
Execution of nonreentrant programs above 16 MB is not supported. Programs
compiled with NORENT must be RMODE(24).
The setting of the DATA option does not affect programs compiled with NORENT.
For information about which Enterprise COBOL programs need to be reentrant, see
the related task about making programs reentrant.
|
|
|
|
|
Link-edit considerations: If all programs in a load module are compiled with RENT,
it is recommended that the load module be link-edited with the RENT linkage-editor
or binder option. (Use the REUS linkage-editor or binder option instead if the load
module will also contain any non-COBOL programs that are only serially
reusable.)
|
If any program in a load module is not reentrant, the load module must not be
link-edited with the RENT or REUS link-edit attributes. The NOREUS linkage-editor or
binder option is needed to ensure that the CANCEL statement will guarantee a fresh
copy of the program on a subsequent CALL.
RELATED CONCEPTS
“Storage and its addressability” on page 40
RELATED TASKS
“Making programs reentrant” on page 478
DB2 Application Programming and SQL Guide (Using reentrant code)
RELATED REFERENCES
“Conflicting compiler options” on page 314
“RMODE” on page 357
|
356
Enterprise COBOL for z/OS, V5.1 Programming Guide
RMODE
The RMODE setting influences the RMODE (residency mode) of your generated object
program.
RMODE option syntax
RMODE(
AUTO
24
ANY
)
Default is: AUTO
Abbreviations are: None
A program compiled with the RMODE(AUTO) option will have RMODE 24 if NORENT is
specified, or RMODE ANY if RENT is specified. RMODE(AUTO) is compatible with older
compilers such as VS COBOL II, which produced RMODE 24 for programs compiled
with NORENT, and RMODE ANY for programs compiled with RENT.
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 must also be compiled with the
RENT option. The program will have the RMODE(ANY) attribute.
|
|
|
If the NORENT option is specified, the RMODE(24) or RMODE(AUTO) compiler option
must be specified. Overriding the module RMODE with a binder option or control
statement is not supported.
DATA and RENT: The RMODE option interacts with other compiler options and runtime
options that affect storage and its addressability. For information about passing
data between programs with different modes, see the related concept about storage
and its addressability.
Link-edit considerations: If the object code that COBOL generates has an attribute
of RMODE 24, you must link-edit the code with RMODE 24. If the object code that
COBOL generates has an attribute of RMODE ANY, you can link-edit the code with
either RMODE ANY or RMODE 24.
RELATED CONCEPTS
“Storage and its addressability” on page 40
RELATED REFERENCES
“Allocation of buffers for QSAM files” on page 187
“Conflicting compiler options” on page 314
Chapter 17. Compiler options
357
SEQUENCE
When you use SEQUENCE, the compiler examines columns 1 through 6 to check that
the source 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 order.
Source statements with blanks in columns 1 through 6 do not participate in this
sequence check and do not result in messages.
SEQUENCE option syntax
SEQUENCE
NOSEQUENCE
Default is: SEQUENCE
Abbreviations are: SEQ|NOSEQ
If you use COPY statements with the SEQUENCE option in effect, be sure that your
source program's sequence fields and the copybook 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 SEQUENCE is in effect, all programs in the
batch compilation are 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.
RELATED TASKS
“Finding line sequence problems” on page 385
SIZE
Use SIZE to indicate the amount of main storage to be made available for
compilation.
SIZE option syntax
SIZE(
nnnnn
nnnK
)
Default is: 5000000 bytes (5 MB)
|
358
Enterprise COBOL for z/OS, V5.1 Programming Guide
Abbreviations are: SZ
nnnnn specifies a decimal number, which must be at least 851968.
nnnK specifies a decimal number in 1 KB increments, where 1 KB = 1024 bytes.
The minimum acceptable value is 832K.
The value specified by the SIZE option is no longer an upper limit for the total
storage used by a COBOL compilation. Storage used by the code-generation and
optimization phases of the compiler is not restricted by the value specified by the
SIZE option. Code generation and optimization can require a variable amount of
compile-time storage, depending on the size and complexity of the COBOL source
program that is compiled, and is limited only by the MVS region size. A region
size of at least 200 MB is recommended for typical COBOL program compilations.
|
|
|
|
|
|
|
SOURCE
Use SOURCE to get a listing of your source program. This listing will include any
statements embedded by PROCESS or COPY statements.
SOURCE option syntax
SOURCE
NOSOURCE
Default is: SOURCE
Abbreviations are: S|NOS
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. Source statements that follow a *CONTROL
NOSOURCE statement are not included in the listing until a subsequent *CONTROL
SOURCE statement switches the output back to normal SOURCE format.
“Example: MAP output” on page 395
RELATED REFERENCES
*CONTROL (*CBL) statement (Enterprise COBOL Language Reference)
SPACE
Use SPACE to select single-, double-, or triple-spacing in your source code listing.
Chapter 17. Compiler options
359
SPACE option syntax
SPACE(
1
2
3
)
Default is: SPACE(1)
Abbreviations are: None
SPACE has meaning only when the SOURCE compiler option is in effect.
RELATED REFERENCES
“SOURCE” on page 359
SQL
Use the SQL compiler option to enable the DB2 coprocessor and to specify DB2
suboptions. You must specify the SQL option if a COBOL source program contains
SQL statements and the program has not been processed by the DB2 precompiler.
SQL option syntax
NOSQL
SQL
("DB2-suboption-string")
Default is: NOSQL
Abbreviations are: None
When you use the SQL option, the DB2 coprocessor writes the database request
module (DBRM) to ddname DBRMLIB. DB2 must be available on the machine on
which you compile.
If you specify the NOSQL option, any SQL statements found in the source program
are diagnosed and discarded.
Use either quotation marks or single quotation marks to delimit the string of DB2
suboptions.
You can partition a long suboption string into multiple suboption strings in
multiple CBL statements. For example:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL=’SQL("string1")’
//COBOL.SYSIN DD *
CBL SQL("string2")
360
Enterprise COBOL for z/OS, V5.1 Programming Guide
CBL SQL(’string3’)
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
. . .
The DB2 suboptions are concatenated in the order of their appearance. Thus in the
example above, the compiler passes the following suboption string to the DB2
coprocessor:
"string1 string2 string3"
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 suboption string
to 4 KB.
RELATED CONCEPTS
“DB2 coprocessor” on page 433
“COBOL and DB2 CCSID determination” on page 439
RELATED TASKS
“Compiling with the SQL option” on page 438
“Separating DB2 suboptions” on page 439
RELATED REFERENCES
“Conflicting compiler options” on page 314
SQLCCSID
Use the SQLCCSID compiler option to control whether the CODEPAGE compiler option
will influence the processing of SQL statements in your COBOL programs.
SQLCCSID option syntax
SQLCCSID
NOSQLCCSID
Default is: SQLCCSID
Abbreviations are: SQLC|NOSQLC
The SQLCCSID option has an effect only if you use the integrated DB2 coprocessor
(SQL compiler option).
If SQLCCSID is in effect, the setting of the CODEPAGE compiler option will influence
the processing of SQL statements within your COBOL programs when you use the
integrated DB2 coprocessor. If NOSQLCCSID is in effect, the CODEPAGE setting will not
influence the processing of SQL statements when you use the integrated DB2
coprocessor; only COBOL statements will be sensitive to the CCSID specified in the
CODEPAGE option.
For further information about this option, see the related task.
Chapter 17. Compiler options
361
RELATED CONCEPTS
“DB2 coprocessor” on page 433
“COBOL and DB2 CCSID determination” on page 439
RELATED TASKS
“Programming with the SQLCCSID or NOSQLCCSID option” on page 440
RELATED REFERENCES
“Code-page determination for string host variables in SQL statements” on page 440
“CODEPAGE” on page 322
“SQL” on page 360
SSRANGE
Use SSRANGE to generate code that checks for out-of-range storage references.
SSRANGE option syntax
NOSSRANGE
SSRANGE
Default is: NOSSRANGE
Abbreviations are: SSR|NOSSR
SSRANGE generates code that checks whether subscripts, including ALL subscripts, or
indexes try to reference areas outside the region of their associated tables. Each
subscript or index is not individually checked for validity. Instead, the effective
address is checked to ensure that it does not reference outside the table.
Note: If you specify the SSRANGE option, range checks are generated by the
compiler and the checks are always conducted at run time. You cannot disable the
compiled-in range checks at run time by specifying the runtime option NOCHECK.
|
|
|
Variable-length items are also checked to ensure that references are within their
maximum defined length.
Reference modification expressions are checked to ensure that:
v The starting position is greater than or equal to 1.
v The starting position is not greater than the current length of the subject data
item.
v The length value (if specified) is greater than or equal to 1.
v The 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 and an out-of-range condition is detected, an error message is
generated, and the program is terminated.
362
Enterprise COBOL for z/OS, V5.1 Programming Guide
For unbounded groups or their subordinate items, checking is done only for
reference modification expressions. Subscripted or indexed references to tables
subordinate to an unbounded group are not checked.
|
|
|
RELATED CONCEPTS
“Reference modifiers” on page 117
RELATED TASKS
“Checking for valid ranges” on page 385
|
STGOPT
The STGOPT option controls storage optimization.
|
|
STGOPT option syntax
|
|
NOSTGOPT
STGOPT
|
||
|
Default is: NOSTGOPT
|
Abbreviations are: SO, NOSO
|
|
|
|
|
|
|
If you specify STGOPT, the compiler might discard any or all of the following data
items, and does not allocate storage for them.
v Unreferenced LOCAL-STORAGE and non-external WORKING-STORAGE level-77 and
level-01 elementary data items
v Non-external level-01 group items if none of their subordinate items are
referenced
v Unreferenced special registers
|
|
The compiler will not generate code to initialize these data items to the values in
their VALUE clauses.
|
|
In addition, with STGOPT, data items in the LOCAL-STORAGE SECTION can be
reordered in memory to optimize performance.
TERMINAL
Use TERMINAL to send progress and diagnostic messages to the SYSTERM ddname.
TERMINAL option syntax
NOTERMINAL
TERMINAL
Chapter 17. Compiler options
363
Default is: NOTERMINAL
Abbreviations are: TERM|NOTERM
Use NOTERMINAL if you do not want this additional output.
TEST
Use TEST to produce object code that enables Debug Tool to perform batch and
interactive debugging. With TEST, you can also enable the inclusion of symbolic
variables in the formatted dumps that are produced by Language Environment.
TEST option syntax
|
NODWARF
NOTEST
DWARF
NOEJPD
SOURCE
EJPD
NOSOURCE
TEST
|
Option default is: NOTEST(NODWARF)
|
|
|
Suboption defaults are:
v NODWARF if only NOTEST is specified
v NOEJPD,SOURCE if only TEST is specified
Abbreviations are: None
|
Suboption abbreviation is: NOS | S
|
NOTEST suboptions
|
|
|
|
DWARF
If you specify NOTEST(DWARF), basic DWARF diagnostic information is
included in the application module. This option enables the best usability
for application failure analysis tools, such as CEEDUMP and IBM Fault
Analyzer.
Debugging information generated by the compiler is in the
industry-standard DWARF format. For more information about DWARF,
see About Common Debug Architecture in the DWARF/ELF Extensions Library
Reference.
|
|
|
|
|
|
|
NODWARF
If you specify NOTEST(NODWARF), DWARF diagnostic information is not
included in the application module.
TEST suboptions
When the TEST option is specified, DWARF debugging information is included in the
application module.
|
|
364
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
The EJPD and NOEJPD suboptions control enablement of the Debug Tool commands
JUMPTO and GOTO in production debugging sessions. These suboptions take effect
only if you specify the TEST option and a non-zero OPTIMIZE level (OPTIMIZE(1) or
OPTIMIZE(2)).
|
EJPD
|
|
|
|
|
NOEJPD If you specify TEST(NOEJPD) and a non-zero OPTIMIZE level:
v The JUMPTO and GOTO commands are not enabled. However, you can still
use JUMPTO and GOTO if you use the SET WARNING OFF Debug Tool
command. In this scenario, JUMPTO and GOTO will have unpredictable
results.
v The normal amount of program optimization is done.
|
|
|
SOURCE If you specify TEST(SOURCE), the generated DWARF debug information
generated by the compiler includes the expanded source code, and the
compiler listing is not needed by IBM® Debug Tool.
|
|
|
|
NOSOURCE
If you specify TEST(NOSOURCE), the generated DWARF debugging information
does not include the expanded source code, and you will need access to
the compiler listing to use IBM Debug Tool.
|
|
|
|
|
Note: If you specify the TEST option, you must set the CODEPAGE option to the
CCSID that is used for the COBOL source program. In particular, programs that
use Japanese characters in DBCS literals or DBCS user-defined words must be
compiled with the CODEPAGE option set to a Japanese codepage CCSID. For more
information, see “CODEPAGE” on page 322.
If you specify TEST(EJPD) and a non-zero OPTIMIZE level:
v The JUMPTO and GOTO commands are enabled.
v The amount of program optimization is reduced. Optimization is done
within statements, but most optimizations do not cross statement
boundaries.
Performance versus debugging capability:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You can control the amount of debugging capability that you get and so also the
program performance, as follows:
v For the best performance, but with some restrictions on debugging, compile
using a non-zero OPTIMIZE level, STGOPT and TEST(NOEJPD).
– The Debug Tool commands JUMPTO and GOTO are not supported. However, you
can still use JUMPTO and GOTO if you use the SET WARNING OFF Debug Tool
command. In this scenario, JUMPTO and GOTO will have unpredictable results.
– Except for the DESCRIBE ATTRIBUTES command, Debug Tool commands cannot
refer to any data item that was discarded from a program by the STGOPT
option.
– The Debug Tool command AT CALL entry-name is not supported.
v For some reduction in program performance from the production-debugging
scenario above, but to enable predictable behavior for the Debug Tool commands
JUMPTO and GOTO, specify a non-zero OPTIMIZE level and TEST(EJPD).
The restrictions above about referring to items discarded by the STGOPT option,
and about the AT CALL command also apply when you use a non-zero OPTIMIZE
level and TEST(EJPD).
v For slowest performance but maximum debugging capability, specify
OPTIMIZE(0), NOSTGOPT and TEST.
Chapter 17. Compiler options
365
The OPTIMIZE(0) option causes the compiler to generate slower code, but all
Debug Tool commands are supported.
|
|
Language Environment:
The TEST option specified with any of its suboptions can improve your formatted
dumps from Language Environment by adding these two features to the dumps:
v A line number that indicates the failing statement, rather than just an offset
v The values of the program variables
With NOTEST(DWARF), the dump will have program variables but will not have the
line number of the failing statement. With NOTEST(NODWARF), the dump will not
have program variables nor the line number of the failing statement.
|
|
|
Enterprise COBOL uses the Language Environment-provided dump services to
produce dumps that are consistent in content and format with those that are
produced by other Language Environment-conforming member languages.
Whether Language Environment produces a dump for unhandled conditions
depends on the setting of the runtime option TERMTHDACT. If you specify
TERMTHDACT(DUMP), a dump is generated when a condition of severity 2 or greater
goes unhandled.
|
|
|
RELATED CONCEPTS
|
RELATED TASKS
DWARF/ELF Extensions Library Reference (About Common Debug
Architecture)
“Using the debugger” on page 389
Language Environment Debugging Guide (Generating a
Language Environment dump with TERMTHDACT)
Debug Tool User's Guide (Special considerations while using the TEST
runtime option)
RELATED REFERENCES
“Logical record length and block size” on page 275
“cob2 input and output files” on page 297
“Conflicting compiler options” on page 314
“OPTIMIZE” on page 351
Language Environment Programming Reference (TEST | NOTEST)
THREAD
THREAD indicates that a COBOL program is to be enabled for execution in a
Language Environment enclave that has multiple POSIX threads or PL/I tasks.
THREAD option syntax
NOTHREAD
THREAD
366
Enterprise COBOL for z/OS, V5.1 Programming Guide
Default is: NOTHREAD
Abbreviations are: None
A program that has been compiled using the THREAD option can also be used in a
nonthreaded application. However, if a COBOL program is to be run in a threaded
application, all the COBOL programs in the Language Environment enclave must
be compiled using the THREAD option.
NOTHREAD indicates that the COBOL program is not to be enabled for execution in
an enclave that has multiple POSIX threads or PL/I tasks.
Programs that are compiled using compilers earlier than Enterprise COBOL are
treated as if compiled using NOTHREAD.
If the THREAD option is in effect, the following elements are not supported. If
encountered, they are diagnosed as errors:
v ALTER statement
v DEBUG-ITEM special register
v
v
v
v
v
GO TO statement without procedure-name
INITIAL phrase in PROGRAM-ID clause
Nested programs
RERUN
Segmentation module
v SORT or MERGE statements
v STOP literal statement
v USE FOR DEBUGGING statement
Additionally, some language constructs have different semantics than in the
nonthreaded case.
Although threaded applications are subject to a number of programming and
environment restrictions, the use of a program in nonthreaded applications is not
so restricted. For example, a program compiled using the THREAD option can run in
the CICS and IMS environments, can run AMODE 24, and can call and be called by
other programs that are not enabled for multithreading, provided that the
application does not contain multiple POSIX threads or PL/I tasks at run time.
Programs compiled using the THREAD option are supported in the reusable
environment that is created by calling the Language Environment preinitialization
routine CEEPIPI. But a reusable environment created by using the RTEREUS runtime
option is not supported for programs compiled using the THREAD option.
Performance consideration: If you use the THREAD option, you can expect some
runtime performance degradation due to the overhead of serialization logic that is
automatically generated.
RELATED TASKS
Chapter 27, “Preparing COBOL programs for multithreading,” on page 509
RELATED REFERENCES
“Conflicting compiler options” on page 314
Chapter 17. Compiler options
367
TRUNC
TRUNC affects the way that binary data is truncated during moves and arithmetic
operations.
TRUNC option syntax
TRUNC(
STD
OPT
BIN
)
Default is: TRUNC(STD)
Abbreviations are: None
TRUNC has no effect on COMP-5 data items; COMP-5 items are handled as if
TRUNC(BIN) is in effect regardless of the TRUNC suboption specified.
TRUNC(STD)
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:
v 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 are 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.
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.
368
Enterprise COBOL for z/OS, V5.1 Programming Guide
v The full binary content of fields is significant.
v DISPLAY will convert the entire content of binary fields with no
truncation.
Recommendations: 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 use TRUNC(OPT) with CICS programs provided that your data conforms
to the PICTURE clause for your BINARY data items.
USAGE COMP-5 has the effect of applying TRUNC(BIN) behavior to individual
data items. Therefore, you can avoid the performance overhead of using
TRUNC(BIN) for every binary data item by specifying COMP-5 on only some
of the binary data items, such as those data items that are passed to
non-COBOL programs or other products and subsystems. The use of
COMP-5 is not affected by the TRUNC suboption in effect.
Large literals in VALUE clauses: When you use the compiler option
TRUNC(BIN), numeric literals specified in VALUE clauses for binary data
items (COMP, COMP-4, or BINARY) can generally contain a value 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.
TRUNC example 1
01 BIN-VAR
PIC S99 USAGE BINARY.
. . .
MOVE 123451 to BIN-VAR
The following table shows values of the data items after the MOVE statement.
Data item
Decimal
Hex
Display
Sender
123451
00|01|E2|3B
123451
Receiver TRUNC(STD)
51
00|33
51
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 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 obtained by not doing a
decimal truncation.
Chapter 17. Compiler options
369
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 statement.
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 truncation 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 49
RELATED TASKS
“Compiling with the CICS option” on page 425
RELATED REFERENCES
VALUE clause (Enterprise COBOL Language Reference)
VBREF
Use VBREF to get a cross-reference between all verbs used in the source program
and the line numbers in which they are used. VBREF also produces a summary of
the number of times each verb was used in the program.
VBREF option syntax
NOVBREF
VBREF
Default is: NOVBREF
Abbreviations are: None
Use NOVBREF for more efficient compilation.
370
Enterprise COBOL for z/OS, V5.1 Programming Guide
WORD
Use WORD(xxxx) to specify that an alternate reserved-word table is to be used during
compilation.
WORD option syntax
NOWORD
WORD(xxxx)
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.
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.
Enterprise 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).
RELATED TASKS
“Compiling with the CICS option” on page 425
RELATED REFERENCES
“Conflicting compiler options” on page 314
“CICS reserved-word table” on page 430
XREF
Use XREF to produce a sorted cross-reference listing.
XREF option syntax
XREF
(
FULL
SHORT
)
NOXREF
Chapter 17. Compiler options
371
Default is: XREF(FULL)
Abbreviations are: X|NOX
You can choose XREF, XREF(FULL), or XREF(SHORT). If you specify XREF without any
suboptions, XREF(FULL) will be in effect.
A section of the listing shows all the program-names, data-names, and
procedure-names that are referenced in your program, and the line numbers where
those names are defined. External program-names are identified.
“Example: XREF output: data-name cross-references” on page 414
“Example: XREF output: program-name cross-references” on page 415
A section is also included that cross-references COPY or BASIS statements in the
program with the data sets or files from which associated copybooks were
obtained.
“Example: XREF output: COPY/BASIS cross-references” on page 415
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; they are shown before the EBCDIC data-names and procedure-names
unless the DBCSXREF installation option is selected with a DBCS ordering program.
In that case, DBCS data-names and procedure-names are in the order specified by
the DBCS ordering program.
If you use XREF and SOURCE, data-name and procedure-name cross-reference
information is printed on the same line as the original source. Line-number
references or other information appears on the right-hand side of the listing page.
On the right of source lines that reference an intrinsic function, the letters IFN are
printed with the line number of the locations where the function arguments are
defined. Information included in the embedded references lets you know if an
identifier is undefined (UND) or defined more than once (DUP), if items are implicitly
defined (IMP) (such as special registers or figurative constants), or if a
program-name is external (EXT).
If you use XREF and NOSOURCE, you get only the sorted cross-reference listing.
XREF(SHORT) prints only the explicitly referenced data items in the cross-reference
listing. XREF(SHORT) applies to DBCS data-names and procedure-names as well as
to single-byte names.
NOXREF suppresses this listing.
Usage notes
v Group names used in a MOVE CORRESPONDING statement are in the XREF listing.
The elementary names in those groups are also listed.
v In the data-name XREF listing, line numbers that are preceded by the letter M
indicate that the data item is explicitly modified by a statement on that line.
v XREF listings take additional storage.
v If there is more than one data set in your SYSLIB concatenation, in some cases
the COPY/BASIS cross-reference might be incomplete or missing. This loss can
occur if XREF is set only in a CBL or PROCESS statement, and XREFOPT=NO is set as
an installation default or NOXREF is coded in your JCL PARM parameter.
372
Enterprise COBOL for z/OS, V5.1 Programming Guide
To ensure that the COPY/BASIS cross-reference is complete, either verify with your
system programmer that XREFOPT=FULL or XREFOPT=SHORT is your installation
default, or code the XREF option in your JCL PARM parameter.
RELATED CONCEPTS
Chapter 19, “Debugging,” on page 379
RELATED TASKS
“Getting listings” on page 390
RELATED REFERENCES
Language Environment Debugging Guide (COBOL compiler options)
ZWB
If you compile using ZWB, the compiler removes the sign from a signed zoned
decimal (DISPLAY) field before comparing this field to an alphanumeric elementary
field during execution.
ZWB option syntax
ZWB
NOZWB
Default is: ZWB
Abbreviations are: None
If the zoned decimal item is a scaled item (that is, it contains the symbol P in its
PICTURE string), comparisons that use the decimal item are not affected by ZWB.
Such items always have their sign removed before the comparison is made to an
alphanumeric field.
ZWB affects how a program runs. The same COBOL program can produce different
results depending on the setting of this option.
Use NOZWB if you want to test input numeric fields for SPACES.
Chapter 17. Compiler options
373
374
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 18. Compiler-directing statements
Several statements help you to direct the compilation of your program.
These are the compiler-directing statements:
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 of text-name for 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
COPY statement syntax
COPY
text-name
literal-1
OF
IN
library-name
literal-2
SUPPRESS
REPLACING operand-1
BY
operand-2
This library statement places prewritten text into a COBOL program.
Neither text-name nor library-name need to be unique within a program.
They can be identical to other user-defined words in the program, except
that they cannot contain the underscore.
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.
Compiling with JCL:
text-name, library-name, and literal-1 and literal-2 are processed as follows:
v The name (which can be from 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 any COBOL library.
v The name is folded to uppercase.
v Hyphens that are not the first or last character are translated to zero (0),
and a warning message is issued.
v If the first character is numeric, then the characters 1-9 are translated to
A-I, zero (0) is converted to J, and a warning message is issued.
For example:
© Copyright IBM Corp. 1991, 2013
375
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:
//COPYLIB DD DSNAME=ABC.COB,VOLUME=SER=111111,
//
DISP=SHR,UNIT=3380
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 in your DD
statement for SYSLIB. Alternatively, define multiple DD statements and
include the IN/OF phrase in your COPY statements.
The maximum block size for the copy library depends on the device on
which your data set resides.
Compiling in the z/OS UNIX shell:
When you compile using the cob2 command, copybooks are included from
the z/OS UNIX file system. text-name, library-name, and literal-1 and literal-2
are processed as follows:
v User-defined words are folded to uppercase. Literals are not folded.
Because UNIX is case sensitive, if your file-name is lowercase or mixed
case, you must specify it as a literal.
v If 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 If 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 that contains the copybook.
If an environment variable of that name is not defined, the copybook is
searched for under the following names, in this order:
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 If library-name is a literal, it is treated as the actual path, relative or
absolute, from which to copy file text-name.
v If 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 copybook 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
376
Enterprise COBOL for z/OS, V5.1 Programming Guide
These settings result in:
/u/user1/mystuff/today.cpy
If library-name is an environment variable that identifies the path from
which copybooks are to be copied, use an export command to define
library-name, as in this example:
export COPYLIB=/u/mystuff/copybooks
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 (:).
If library-name is omitted and text-name is not an absolute path name, the
copybook is searched for in this order:
1. In the current directory
2. In the paths specified on the -I cob2 option
3. In the paths specified in the SYSLIB environment variable
For additional information about the COPY statement, for example, the rules
for text replacement, see the related reference.
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 statement is treated as a comment.
INSERT statement
This library statement adds COBOL statements to the BASIS source
program.
PROCESS (CBL) statement
This statement, which you place 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,
and should be used at the resume point for a call to CEE3SRP. It is not
intended for general use.
SKIP1/2/3 statement
These statements indicate lines to be skipped in the source listing.
TITLE statement
This statement specifies that a title (header) should be printed at the top of
each page of the source listing.
|
|
USE statement
The USE statement provides declaratives to specify these elements:
v Error-handling procedures: EXCEPTION/ERROR
v Debugging lines and sections: DEBUGGING
Chapter 18. Compiler-directing statements
377
RELATED TASKS
“Changing the header of a source listing” on page 5
“Specifying compiler options under z/OS” on page 279
“Specifying compiler options under z/OS UNIX” on page 292
“Setting environment variables under z/OS UNIX” on page 291
“Eliminating repetitive coding” on page 667
RELATED REFERENCES
“cob2 syntax and options” on page 295
COPY statement (Enterprise COBOL Language Reference)
378
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 19. Debugging
You can choose between two different approaches to determine the cause of
problems in the behavior of your application: source-language debugging or
interactive debugging.
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.
For interactive debugging, you can use Debug Tool. Debug Tool offers these
productivity enhancements:
v Interactive debugging (in full-screen or line mode), or debugging in batch mode
During an interactive full-screen mode session, you can use Debug Tool's
full-screen services and session panel windows on a 3270 device to debug your
program while 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.
v Mixed-language debugging
You can debug an application that contains programs written in a 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 Debug Tool Plug-in for Eclipse or the IBM
Problem Determination Tools with Rational® Developer for System z for
debugging programs that run on z/OS.
RELATED TASKS
“Debugging with source language”
“Debugging using compiler options” on page 384
“Using the debugger” on page 389
“Getting listings” on page 390
Debug Tool User's Guide
RELATED REFERENCES
Debug Tool Reference and Messages
Language Environment Debugging Guide (Formatting and analyzing system
dumps, Debugging example COBOL programs)
Debugging with source language
You can use several COBOL language features to pinpoint the cause of a failure in
a program.
© Copyright IBM Corp. 1991, 2013
379
About this task
If a failing program is part of a large application that is already in production
(precluding source updates), write a small test case to simulate the failing part of
the program. Code 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 381
“Validating data” on page 381
“Moving, initializing or setting uninitialized data” on page 382
“Generating information about procedures” on page 382
RELATED REFERENCES
Source language debugging (Enterprise COBOL Language Reference)
Tracing program logic
Trace the logic of your program by adding DISPLAY statements.
About this task
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 use explicit scope terminators to end statements in your program, the logic
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
in 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.
380
Enterprise COBOL for z/OS, V5.1 Programming Guide
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.
RELATED CONCEPTS
“Scope terminators” on page 20
RELATED REFERENCES
DISPLAY statement (Enterprise 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.
About this task
To use file status keys in debugging, check for a nonzero value in the status key
after each input-output statement. If the value is nonzero (as reported in an error
message), 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 determine 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 that follows the
DECLARATIVES keyword in the PROCEDURE DIVISION.
RELATED TASKS
“Coding ERROR declaratives” on page 250
“Using file status keys” on page 251
RELATED REFERENCES
File status key (Enterprise COBOL Language Reference)
Validating data
If you suspect that your program is trying to perform arithmetic on nonnumeric
data or is receiving the wrong type of data on an input record, use the class test
(the class condition) to validate the type of data.
About this task
You can use the class test to check whether the content of a data item is
ALPHABETIC, ALPHABETIC-LOWER, ALPHABETIC-UPPER, DBCS, KANJI, or NUMERIC. If the
data item is described implicitly or explicitly as USAGE NATIONAL, the class test
checks the national character representation of the characters associated with the
specified character class.
|
|
|
You can use the UVALID intrinsic function to check whether a national data item
contains valid UTF-16 encoded data, or whether an alphanumeric or alphabetic
item contains valid UTF-8 encoded data.
Chapter 19. Debugging
381
RELATED TASKS
“Coding conditional expressions” on page 102
“Testing for valid DBCS characters” on page 157
RELATED REFERENCES
Class condition (Enterprise COBOL Language Reference)
UVALID (Enterprise COBOL Language Reference)
|
Moving, initializing or setting uninitialized data
Use an INITIALIZE or SET statement to initialize a table or data item when you
suspect that a problem might be caused by residual data in those fields.
About this task
If the problem happens intermittently and not always with the same data, it could
be that a switch was not initialized but is generally set to the right value (0 or 1)
by chance. By using a SET statement to ensure that the switch is initialized, you
can determine that the uninitialized switch is the cause of the problem or remove
it as a possible cause.
RELATED REFERENCES
INITIALIZE statement (Enterprise COBOL Language Reference)
SET statement (Enterprise COBOL Language Reference)
Generating information about procedures
Generate information about your program or test case and how it is running by
coding 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.
About this task
For example, to determine 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 that control passes to that procedure. You can
use the counter technique to check items such as these:
v How many times a PERFORM statement runs, and thus whether a particular
routine is being used and whether the control structure is correct
v How many times a loop runs, and thus whether the loop is executing and
whether the number for the loop is accurate
You can use debugging lines or debugging statements or both in your program.
Debugging lines are statements that are identified by a D in column 7. To make
debugging lines in your program active, code the WITH DEBUGGING MODE clause on
the SOURCE-COMPUTER line in the ENVIRONMENT DIVISION. Otherwise debugging lines
are treated as comments.
Debugging statements are the statements that are 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.
382
Enterprise COBOL for z/OS, V5.1 Programming Guide
v Only in the outermost program; they are not valid in nested programs.
Debugging statements are also never triggered by procedures that are contained
in nested programs.
To use debugging statements in your program, you must include the WITH
DEBUGGING MODE clause and use the DEBUG runtime option.
Options restrictions:
v You cannot use the USE FOR DEBUGGING declarative in a program that you
compile with the THREAD option.
“Example: USE FOR DEBUGGING”
RELATED REFERENCES
SOURCE-COMPUTER paragraph (Enterprise COBOL Language Reference)
Debugging lines (Enterprise COBOL Language Reference)
Debugging sections (Enterprise COBOL Language Reference)
DEBUGGING declarative (Enterprise COBOL Language Reference)
Example: USE FOR DEBUGGING
This example shows the kind of statements that are needed to use a DISPLAY
statement and a USE FOR DEBUGGING declarative to test a program.
The DISPLAY statement writes information to the terminal or to an output data set.
The USE FOR DEBUGGING declarative is used with a counter to show how many
times a routine runs.
Environment Division.
. . .
Data Division.
. . .
Working-Storage Section.
. . . (other entries your program needs)
01 Trace-Msg
PIC X(30) Value " Trace for Procedure-Name : ".
01 Total
PIC 9(9) Value 1.
. . .
Procedure Division.
Declaratives.
Debug-Declaratives Section.
Use For Debugging On Some-Routine.
Debug-Declaratives-Paragraph.
Display Trace-Msg, Debug-Name, Total.
End Declaratives.
Main-Program Section.
. . . (source program statements)
Perform Some-Routine.
. . . (source program statements)
Stop Run.
Some-Routine.
. . . (whatever statements you need in this paragraph)
Add 1 To Total.
Some-Routine-End.
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 indicates the number of times Some-Routine has run. The statements
in the debugging declarative are performed before the named procedure runs.
Chapter 19. Debugging
383
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.
As a result, a message is displayed before each nondebugging procedure in the
outermost program runs.
Debugging using compiler options
You can use certain compiler options to help you find errors in your program, find
various elements in your program, obtain listings, and prepare your program for
debugging.
About this task
You can find the following errors by using compiler options (the options are
shown in parentheses):
v Syntax errors such as duplicate data-names (NOCOMPILE)
v Missing sections (SEQUENCE)
v Invalid subscript values (SSRANGE)
You can find the following elements in your program by using compiler options:
v Error messages and locations of the associated errors (FLAG)
v Program entity definitions and references; text-names and library-names from
COPY or BASIS statements, and the associated data sets or files from which
copybooks are obtained (XREF)
v Data items in the DATA DIVISION (MAP)
v Verb references (VBREF)
You can get a copy of your source (SOURCE) or a listing of generated code (LIST).
You prepare your program for debugging by using the TEST compiler option.
RELATED TASKS
“Finding coding errors”
“Finding line sequence problems” on page 385
“Checking for valid ranges” on page 385
“Selecting the level of error to be diagnosed” on page 386
“Finding program entity definitions and references” on page 388
“Listing data items” on page 388
“Getting listings” on page 390
RELATED REFERENCES
Chapter 17, “Compiler options,” on page 311
Finding coding errors
Use the NOCOMPILE option to compile conditionally or to only check syntax. When
used with the SOURCE option, NOCOMPILE produces a listing that will help you find
coding mistakes such as missing definitions, improperly defined data items, and
duplicate data-names.
384
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
If you are compiling in the TSO foreground, you can send the messages to your
screen by using the TERM compiler option and defining your data set as the
SYSTERM data set.
Checking syntax only: To only check the syntax of your program, and not produce
object code, use NOCOMPILE without a suboption. If you also specify the SOURCE
option, the compiler produces a listing.
When you specify NOCOMPILE, several compiler options are suppressed. See the
related reference below about the COMPILE option for details.
Compiling conditionally: To compile conditionally, use NOCOMPILE(x), where x is
one of the severity levels of errors. Your program is compiled if all the errors are of
a lower severity than x. The severity levels that you can use, from highest to
lowest, are S (severe), E (error), and W (warning).
If an error of level x or higher occurs, the compilation stops and your program is
only checked for syntax.
RELATED REFERENCES
“COMPILE” on page 325
Finding line sequence problems
Use the SEQUENCE compiler option to find statements that are out of sequence.
Breaks in sequence indicate that a section of a source program was moved or
deleted.
About this task
When you use SEQUENCE, the compiler checks the source statement numbers to
determine whether they are in ascending sequence. Two asterisks are placed beside
statement numbers that are out of sequence. The total number of these statements
is printed as the first line in the diagnostics after the source listing.
RELATED REFERENCES
“SEQUENCE” on page 358
Checking for valid ranges
Use the SSRANGE compiler option to check whether addresses fall within proper
ranges.
About this task
SSRANGE causes the following addresses to be checked:
|
|
|
|
|
|
v Subscripted or indexed data references: Is the effective address of the specified
table element within the maximum boundary of the containing group? (This
checking is not done for UNBOUNDED tables and groups.)
v Variable-length data references (a reference to a data item that contains an
OCCURS DEPENDING ON clause): Is the actual length greater than or equal to zero,
and within the maximum defined length for the group data item? (This checking
is not done for UNBOUNDED groups.)
Chapter 19. Debugging
385
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?
If the SSRANGE option is in effect, checking is performed at run time if the COBOL
statement that contains the indexed, subscripted, variable-length, or
reference-modified data item is executed.
|
|
|
If an effective address is outside the range of the data item that contains the
referenced data, an error message is generated and the program stops. The
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, and reference modifiers in a given data reference are
literals and they result in a reference outside the data item, the error is diagnosed
at compile time regardless of the setting of the SSRANGE option.
Performance consideration: SSRANGE can somewhat degrade performance because
of the extra overhead to check each subscripted or indexed item.
RELATED REFERENCES
“SSRANGE” on page 362
“Performance-related compiler options” on page 661
Selecting the level of error to be diagnosed
Use the FLAG compiler option to specify the level of error to be diagnosed during
compilation and to indicate whether error messages are to be embedded in the
listing. Use FLAG(I) or FLAG(I,I) to be notified of all errors.
About this task
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.
Table 49. Severity levels of compiler messages
Severity level
Resulting messages
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 that 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 that had 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.
386
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
Note: You can suppress some error messages and change the severity of others
with the MSGEXIT suboption of the EXIT option.
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 TASKS
“Generating a list of compiler messages” on page 287
RELATED REFERENCES
“Severity codes for compiler diagnostic messages” on page 288
“Messages and listings for compiler-detected errors” on page 287
“FLAG” on page 336
Example: embedded messages
The following example shows the embedded messages generated by specifying a
second parameter to the FLAG option. Some messages in the summary apply to
more than one COBOL statement.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
LineID PL SL ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|--+----8 Map and Cross Reference
...
090671**
/
090672**
*****************************************************************
090673**
***
I N I T I A L I Z E P A R A G R A P H
**
090674**
*** Open files. Accept date, time and format header lines.
**
090675**
*** Load location-table.
**
090676**
*****************************************************************
090677**
100-initialize-paragraph.
090678**
move spaces to ws-transaction-record
IMP 331
090679**
move spaces to ws-commuter-record
IMP 307
090680**
move zeroes to commuter-zipcode
IMP 318
090681**
move zeroes to commuter-home-phone
IMP 319
090682**
move zeroes to commuter-work-phone
IMP 320
090683**
move zeroes to commuter-update-date
IMP 324
090684**
open input update-transaction-file
204
==090684==> IGYPS2052-S An error was found in the definition of file "LOCATION-FILE". The
reference to this file was discarded.
090685**
location-file
193
090686**
i-o commuter-file
181
090687**
output print-file
217
090688**
if commuter-file-status not = "00" and not = "97"
241
090689**
1
display "100-OPEN"
090690**
1
move 100 to comp-code
231
090691**
1
perform 500-vsam-error
91069
090692**
1
perform 900-abnormal-termination
91114
090693**
end-if
090694**
accept ws-date from date
UND
==090694==> IGYPS2121-S "WS-DATE" was not defined as a data-name. The statement was discarded.
090695**
move corr ws-date to header-date
UND 455
==090695==> IGYPS2121-S "WS-DATE" was not defined as a data-name. The statement was discarded.
090696**
accept ws-time from time
UND
==090696==> IGYPS2121-S "WS-TIME" was not defined as a data-name. The statement was discarded.
090697**
move corr ws-time to header-time
UND 449
==090697==> IGYPS2121-S "WS-TIME" was not defined as a data-name. The statement was discarded.
090698**
read location-file
193
==090698==> IGYPS2053-S An error was found in the definition of file "LOCATION-FILE". This
input/output statement was discarded.
090699**
at end
090700**
1
set location-eof to true
256
090701**
end-read
...
LineID Message code Message text
IGYSC0090-W 1700 sequence errors were found in this program.
IGYSC3002-I A severe error was found in the program. The "OPTIMIZE" compiler option was cancelled.
160 IGYDS1089-S "ASSIGNN" was invalid. Scanning was resumed at the next area "A" item, level-number, or
the start of the next clause.
Chapter 19. Debugging
387
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
193 IGYGR1207-S
The "ASSIGN" clause was missing or invalid in the "SELECT" entry for file "LOCATION-FILE".
The file definition was discarded.
269 IGYDS1066-S "REDEFINES" object "WS-DATE" was not the immediately preceding level-1 data item.
The "REDEFINES" clause was discarded.
90602 IGYPS2052-S An error was found in the definition of file "LOCATION-FILE". The reference to this file
was discarded. Same message on line: 90684
90694 IGYPS2121-S "WS-DATE" was not defined as a data-name. The statement was discarded.
Same message on line: 90695
90696 IGYPS2121-S "WS-TIME" was not defined as a data-name. The statement was discarded.
Same message on line: 90697
90698 IGYPS2053-S An error was found in the definition of file "LOCATION-FILE". This input/output statement
was discarded. Same message on line: 90709
Messages
Total
Informational
Warning
Error
Severe
Terminating
Printed:
13
1
1
11
* Statistics for COBOL program IGYTCARA:
*
Source records = 1755
*
Data Division statements = 295
*
Procedure Division statements = 479
*
Generated COBOL statements = 0
*
Program complexity factor = 486
End of compilation 1, program IGYTCARA, highest severity 12.
Return code 12
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. Use it also to
produce a cross-reference of COPY or BASIS statements to the data sets or files from
which copybooks were obtained.
About this task
A sorted cross-reference includes the line number where the data-name,
procedure-name, or program-name was defined and the line numbers of all
references to it.
To include only the explicitly referenced data items, use the XREF(SHORT) option.
Use both the XREF (either FULL or SHORT) and the SOURCE options to print a modified
cross-reference to the right of the source listing. This embedded cross-reference
shows the line number where the data-name or procedure-name was defined.
For further details, see the related reference about the XREF compiler option.
“Example:
“Example:
“Example:
“Example:
XREF
XREF
XREF
XREF
output:
output:
output:
output:
data-name cross-references” on page 414
program-name cross-references” on page 415
COPY/BASIS cross-references” on page 415
embedded cross-reference” on page 416
RELATED TASKS
“Getting listings” on page 390
RELATED REFERENCES
“XREF” on page 371
Listing data items
Use the MAP compiler option to produce a listing of the DATA DIVISION items and all
implicitly declared items. Use the MAP output to locate the contents of a data item
in a system dump.
388
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
When you use the MAP option, an embedded MAP summary that contains condensed
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|NOMAP (or *CBL MAP|NOMAP) statements throughout the source.
For example:
*CONTROL NOMAP
01 A
02 B
*CONTROL MAP
“Example: MAP output” on page 395
RELATED TASKS
“Getting listings” on page 390
RELATED REFERENCES
“MAP” on page 342
Using the debugger
You can use Debug Tool to debug your Enterprise COBOL programs. Use the TEST
compiler option to prepare your COBOL program so that you can step through the
executable program with the debugger.
About this task
|
|
|
|
|
For remote debugging, there is an Eclipse plugin that provides a client graphical
user interface to the debugging information provided by the Debug Tool engine
running under z/OS or z/OS UNIX. The IBM Debug Tool Plug-in for Eclipse is
included with Rational Developer for System z and also with the IBM Problem
Determination Tools Studio.
|
|
|
|
|
You can specify the TEST suboption NOSOURCE to have smaller object programs
stored on disk. The loaded size does not change, the debug information is never
loaded unless requested, for example, by a debugger such as Debug Tool or by LE
(for CEEDUMP). With the NOSOURCE suboption, the compiler listing will be required
at debug time for the Debug Tool source window.
|
|
Specify the OPTIMIZE(0), NOSTGOPT and TEST compiler options to get the most
debugging function.
|
|
Specify a non-zero OPTIMIZE level, NOSTGOPT and TEST(EJPD) compiler options to
get better performance with a few restrictions on debugging function.
|
|
|
Specify a non-zero OPTIMIZE level, STGOPT and TEST(NOEJPD) compiler options to
get the best performance but still be able to use Debug Tool, with some restrictions
on debugging function.
For details about which compiler options to use for maximum debugging
capability versus best performance, see the related reference about the TEST
compiler option.
Chapter 19. Debugging
389
RELATED TASKS
Debug Tool User's Guide (Preparing your program for debugging)
RELATED REFERENCES
“TEST” on page 364
Getting listings
Get the information that you need for debugging by requesting the appropriate
compiler listing with the use of compiler options.
About this task
Attention: The listings produced by the compiler are not a programming interface
and are subject to change.
Table 50. Using compiler options to get listings
Use
Listing
To check a list of the
Short listing
options in effect for the
program, statistics about
the content of the program,
and diagnostic messages
about the compilation
To aid in testing and
debugging your program;
to have a record after the
program has been
debugged
Source listing
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
Contents
Compiler option
v List of options in effect
for the program
NOSOURCE, NOXREF, NOVBREF,
NOMAP, NOOFFSET, NOLIST
v Statistics about the
content of the program
v Diagnostic messages
about the compilation1
Copy of your source
“SOURCE” on page 359
All DATA DIVISION items
and all implicitly declared
items
“MAP” on page 3422
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)
390
Enterprise COBOL for z/OS, V5.1 Programming Guide
Table 50. Using compiler options to get listings (continued)
Use
Listing
Contents
Compiler option
To find where a name is
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 determine
the data set or file from
which a copybook was
obtained
Sorted cross-reference
listing of names; sorted
cross-reference listing of
COPY/BASIS statements and
copybook data sets or files
Data-names,
procedure-names, and
program-names; references
to these names
“XREF” on page 3712,3
COPY/BASIS text-names and
library names, and the data
sets or files from which
associated copybooks were
obtained
Embedded modified
cross-reference provides
line numbers where
data-names and
procedure-names were
defined
|
|
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
is moved while the
program is running
Generated code
“LIST” on page 3412,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 349
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 370
1. To eliminate messages, turn off the options (such as FLAG) that govern the level of compile diagnostic
information. You can also selectively suppress messages by using the MSGEXIT suboption of the EXIT compiler
option.
2. 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.
3. The context of the procedure reference is indicated by the characters preceding the line number.
4. You can control the listing of generated object code by selectively placing *CONTROL LIST and *CONTROL NOLIST
(or equivalently, *CBL LIST and *CBL NOLIST) statements in your source. Note that the *CONTROL statement is
different than 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:
short listing” on page 392
SOURCE and NUMBER output” on page 394
MAP output” on page 395
embedded map summary” on page 396
nested program map” on page 399
Chapter 19. Debugging
391
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
XREF output: data-name cross-references” on page 414
XREF output: program-name cross-references” on page 415
XREF output: COPY/BASIS cross-references” on page 415
XREF output: embedded cross-reference” on page 416
OFFSET compiler output” on page 417
VBREF compiler output” on page 418
RELATED TASKS
“Generating a list of compiler messages” on page 287
“Reading LIST output” on page 399
Language Environment Debugging Guide (Debugging COBOL programs)
RELATED REFERENCES
“Messages and listings for compiler-detected errors” on page 287
Example: short listing
The parenthetical numbers shown in the listing below correspond to numbered
explanations that follow the listing. For illustrative purposes, some errors that
cause diagnostic messages were deliberately introduced.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Invocation parameters:
(1)
OPTFILE
PROCESS(CBL) statements:
(2)
CBL NODECK
CBL NOADV,NODYN,NONAME,NONUMBER,QUOTE,SEQ,DUMP
CBL NOSOURCE, NOXREF, NOVBREF, NOMAP, NOOFFSET, NOLIST
Options from SYSOPTF:
(3)
C,NODU,FLAG(I),X,MAP,NOLIST,RENT,OPT(1),SSR
TEST TRUNC(OPT)
Options in effect:
(4)
NOADATA
NOADV
AFP(VOLATILE)
QUOTE
ARCH(6)
ARITH(COMPAT)
NOAWO
NOBLOCK0
BUFSIZE(4096)
NOCICS
CODEPAGE(1140)
COMPILE
NOCURRENCY
DATA(31)
DBCS
NODECK
NODIAGTRUNC
DISPSIGN(COMPAT)
NODLL
DUMP
NODYNAM
NOEXIT
NOEXPORTALL
NOFASTSRT
FLAG(I)
NOFLAGSTD
HGPR(PRESERVE)
INTDATE(ANSI)
LANGUAGE(EN)
LINECOUNT(60)
NOLIST
NOMAP
MAXPCF(60000)
NOMDECK
NONAME
NSYMBOL(NATIONAL)
NONUMBER
NUMPROC(NOPFD)
OBJECT
NOOFFSET
OPTIMIZE(1)
OUTDD(SYSOUT)
392
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PGMNAME(COMPAT)
RENT
RMODE(AUTO)
SEQUENCE
SIZE(5000000)
NOSOURCE
SPACE(1)
NOSQL
SQLCCSID
SSRANGE
NOSTGOPT
NOTERM
TEST(NOEJPD,SOURCE)
NOTHREAD
TRUNC(OPT)
NOVBREF
NOWORD
NOXREF
ZWB
LineID
Message code
Message text
(5)
IGYSC3002-I
A severe error was found in the program.
options were cancelled.
160
IGYDS1089-S
"ASSIGNN" was invalid. Scanning was resumed at the next area "A" item, level-number,
or the start of the next clause.
192
IGYDS1050-E
File "LOCATION-FILE" contained no data record descriptions.
discarded.
192
IGYGR1207-S
The "ASSIGN" clause was missing or invalid in the "SELECT" entry for file "LOCATION-FILE".
The file definition was discarded.
888
IGYPS2052-S
An error was found in the definition of file "LOCATION-FILE".
was discarded.
1000
IGYPS2121-S
Same message on line:
1004
IGYPS2053-S
The reference to this file
The statement was discarded.
1001
An error was found in the definition of file "LOCATION-FILE".
was discarded.
Same message on line:
The file definition was
979
"WS-DATE" was not defined as a data-name.
Same message on line:
The "OPTIMIZE" and the "STGOPT" compiler
This input/output statement
1016
1015
IGYPS2121-S
"LOC-CODE" was not defined as a data-name.
The statement was discarded.
1212
IGYPS2121-S
"WS-NUMERIC-DATE" was not defined as a data-name.
1655
IGYPG3113-W
The statement was discarded.
Truncation of high-order digit positions may occur due to precision of intermediate results
exceeding 30 digits.
Messages
Total
Informational
Warning
Error
Severe
Terminating
(6)
Printed:
13
1
1
1
10
* Statistics for COBOL program IGYTCARA:
(7)
*
Source records = 1755
*
Data Division statements = 295
*
Procedure Division statements = 479
*
Generated COBOL statements = 0
*
Program complexity factor = 486
End of compilation 1, program IGYTCARA, highest severity 12.
(8)
Return code 12
(1)
Message about options passed to the compiler at compiler invocation. This
message does not appear if no options were passed.
OPTFILE
Requests options from a SYSOPTF data set.
(2)
Options coded in the PROCESS (or CBL) statement.
NOOFFSET
Suppresses a condensed listing of the PROCEDURE DIVISION.
NOMAP
(3)
Suppresses a map report of the items defined in the DATA DIVISION.
Options obtained from the SYSOPTF data set (because the OPTFILE
compiler option was specified).
NOLIST Suppresses an assembler-language expansion of the source code.
Chapter 19. Debugging
393
The program was compiled for use with Debug Tool or formatted
dumps.
TEST
(4)
Status of options at the start of this compilation.
(5)
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.
(6)
Count of diagnostic messages in this program, grouped by severity level.
(7)
Program statistics for the program IGYTCARA.
(8)
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.
Example: SOURCE and NUMBER output
In the portion of the listing shown below, the programmer numbered two of the
statements out of sequence. The note numbers in the listing correspond to
numbered explanations that follow the listing.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
LineID
(2)
000870
000871
000872
000873
000874
000875
000876
000877
000878
000879
000880
000881
000882
000883
000884
000885
000886
000887
000888
000889
000890
000891
000892
000893
000894
000895
000896
000897
000898
000899
000900
000901
000902
000903
000904
000905
000906
000907
000908
000909
000910
000911
000912
000913
000914
000915
000916
000917
000918
000919
000920
394
(1)
PL SL ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|--+----8
(3) (4)
/****************************************************************
***
D O M A I N
L O G I C
**
***
**
*** Initialization. Read and process update transactions until **
*** EOE. Close files and stop run.
**
*****************************************************************
procedure division.
000-do-main-logic.
display "PROGRAM IGYTCARA - Beginning".
perform 050-create-vsam-master-file.
perform 100-initialize-paragraph.
read update-transaction-file into ws-transaction-record
at end
1 IA4390
set transaction-eof to true
end-read.
IA4410
perform until transaction-eof
1
perform 200-edit-update-transaction
1 IA4430
if no-errors
2
perform 300-update-commuter-record
1
else
2
perform 400-print-transaction-errors
1
end-if
1
perform 410-re-initialize-fields
1 IA4480
read update-transaction-file into ws-transaction-record
1
at end
2 IA4500
set transaction-eof to true
1 IA4510
end-read
IA4520
end-perform.
close commuter-file update-transaction-file location-file
print-file.
Map and Cross Reference
930
982
203 338
253
253
1050
372
1159
1312
1373
203 338
253
180 203 192
216
*----------------------------------------------------*
*
File status checked after I/O operation.
*
*----------------------------------------------------*
IA4600
1
1
1
1
if not i-o-okay
display "000-close"
move 0000 to comp-code
IA4620
perform 500-vsam-error
perform 900-abnormal-termination
IA4630
end-if.
*********************************************************
*
Paragraphs 1100 and 1200 illustrates the intrinsic *
*
function computations.
*
*********************************************************
perform 1100-print-i-f-headings.
perform 1200-print-i-f-data.
display " ".
display " ".
display "PROGRAM IGYTCARA - Normal end".
stop run.
241
230
1386
1432
1441
1481
(1)
Scale line, which labels Area A, Area B, and source-code column numbers
(2)
Source-code line number assigned by the compiler
(3)
Program (PL) and statement (SL) nesting level
(4)
Columns 1 through 6 of program (the sequence number area)
Enterprise COBOL for z/OS, V5.1 Programming Guide
Example: MAP output
The following example shows output from the MAP option. The numbers used in
the explanation below correspond to the numbers that annotate the output.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Data Division Map
(1)
Data Definition Attribute codes (rightmost column) have the following meanings:
D = Object of OCCURS DEPENDING
G = GLOBAL
S = Spanned file
E = EXTERNAL
O = Has OCCURS clause
U = Undefined format file
F = Fixed-length file
OG= Group has own length definition
V = Variable-length file
FB= Fixed-length blocked file
R = REDEFINES
VB= Variable-length blocked file
X = Unallocated
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)
Source
Hierarchy and
Base
Displacement Asmblr Data
Data Def
LineID
Data Name
Locator
Structure Definition
Data Type
Attributes
4 PROGRAM-ID IGYTCARA----------------------------------------------------------------------------------------------------*
58
FD COMMUTER-FILE . . . . . . . . . . . . . . . . BLF=00001
VSAM
F
60
1 COMMUTER-RECORD . . . . . . . . . . . . . . . BLF=00001
DS 0CL80
Group
61
2 COMMUTER-KEY. . . . . . . . . . . . . . . . BLF=00001 000000000 DS 16C
Display
62
2 FILLER. . . . . . . . . . . . . . . . . . . BLF=00001 000000016 DS 64C
Display
64
FD COMMUTER-FILE-MST . . . . . . . . . . . . . . BLF=00002
VSAM
F
66
1 COMMUTER-RECORD-MST . . . . . . . . . . . . . BLF=00002
DS 0CL80
Group
67
2 COMMUTER-KEY-MST. . . . . . . . . . . . . . BLF=00002 000000000 DS 16C
Display
68
2 FILLER. . . . . . . . . . . . . . . . . . . BLF=00002 000000016 DS 64C
Display
140
1 STATUS-AREA . . . . . . . . . . . . . . . . .
DS 0CL8
Group
141
2 COMMUTER-FILE-STATUS. . . . . . . . . . . .
000000000 DS 2C
Display
142
88 I-O-OKAY. . . . . . . . . . . . . . . . . .
143
2 COMMUTER-VSAM-STATUS. . . . . . . . . . . .
000000002 DS 0CL6
Group
144
3 VSAM-R15-RETURN-CODE. . . . . . . . . . .
000000002 DS 2C
Binary
145
3 VSAM-FUNCTION-CODE. . . . . . . . . . . .
000000004 DS 2C
Binary
146
3 VSAM-FEEDBACK-CODE. . . . . . . . . . . .
000000006 DS 2C
Binary
148
77 UPDATE-FILE-STATUS. . . . . . . . . . . . . .
DS 2C
Display
149
77 LOCCODE-FILE-STATUS . . . . . . . . . . . . .
DS 2C
Display
150
77 UPDPRINT-FILE-STATUS. . . . . . . . . . . . .
DS 2C
Display
152
1 FLAGS . . . . . . . . . . . . . . . . . . . .
DS 0CL3
Group
153
2 TRANSACTION-EOF-FLAG. . . . . . . . . . . .
000000000 DS 1C
Display
154
88 TRANSACTION-EOF . . . . . . . . . . . . . .
155
2 LOCATION-EOF-FLAG . . . . . . . . . . . . .
000000001 DS 1C
Display
156
88 LOCATION-EOF. . . . . . . . . . . . . . . .
157
2 TRANSACTION-MATCH-FLAG. . . . . . . . . . .
000000002 DS 1C
Display
158
88 TRANSACTION-MATCH . . . . . . . . . . . . .
159
88 TRANSACTION-MATCH-OFF . . . . . . . . . . .
216
1 WS-COMMUTER-RECORD. . . . . . . . . . . . . . BLX=00001
DS 0CL81
Group
E
217
2 WS-COMMUTER-KEY . . . . . . . . . . . . . . BLX=00001 000000000 DS 0CL16
Group
E
218
3 WS-COMMUTER-GENERIC-KEY . . . . . . . . . BLX=00001 000000000 DS 0CL5
Group
E
219
4 COMMUTER-SHIFT. . . . . . . . . . . . . BLX=00001 000000000 DS 1C
Display
E
220
4 COMMUTER-HOME-CODE. . . . . . . . . . . BLX=00001 000000001 DS 2C
Display
E
221
4 COMMUTER-WORK-CODE. . . . . . . . . . . BLX=00001 000000003 DS 2C
Display
E
222
3 COMMUTER-NAME . . . . . . . . . . . . . . BLX=00001 000000005 DS 9C
Display
E
223
3 COMMUTER-INITIALS . . . . . . . . . . . . BLX=00001 000000014 DS 2C
Display
E
224
2 COMMUTER-ADDRESS. . . . . . . . . . . . . . BLX=00001 000000016 DS 18C
Display
E
225
2 COMMUTER-CITY . . . . . . . . . . . . . . . BLX=00001 000000034 DS 13C
Display
E
226
2 COMMUTER-STATE. . . . . . . . . . . . . . . BLX=00001 000000047 DS 2C
Display
E
227
2 COMMUTER-ZIPCODE. . . . . . . . . . . . . . BLX=00001 000000049 DS 3P
Packed-Dec
E
396
1 DETAIL1-LINE. . . . . . . . . . . . . . . . . BLL=00001
DS 0CL121
Group
397
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000000 DS 2C
Display
398
2 PRINT-TRANSACTION-CODE. . . . . . . . . . . BLL=00001 000000002 DS 1C
Display
399
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000003 DS 4C
Display
400
2 PRINT-RECORD-TYPE . . . . . . . . . . . . . BLL=00001 000000007 DS 3C
Display
401
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000010 DS 3C
Display
402
2 PRINT-SHIFT . . . . . . . . . . . . . . . . BLL=00001 000000013 DS 1C
Display
403
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000014 DS 1C
Display
404
2 PRINT-HOME-CODE . . . . . . . . . . . . . . BLL=00001 000000015 DS 2C
Display
405
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000017 DS 1C
Display
406
2 PRINT-WORK-CODE . . . . . . . . . . . . . . BLL=00001 000000018 DS 2C
Display
407
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000020 DS 2C
Display
408
2 PRINT-NAME. . . . . . . . . . . . . . . . . BLL=00001 000000022 DS 9C
Display
454
1 DETAILX-LINE. . . . . . . . . . . . . . . . . BLL=XXXXX
DS 0CL121
Group
X
455
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX
DS 36C
Display
X
456
2 PRINT-CITY. . . . . . . . . . . . . . . . . BLL=XXXXX
DS 13C
Display
X
457
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX
DS 3C
Display
X
458
2 PRINT-STATE . . . . . . . . . . . . . . . . BLL=XXXXX
DS 2C
Display
X
459
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX
DS 1C
Display
X
460
2 PRINT-ZIPCODE . . . . . . . . . . . . . . . BLL=XXXXX
DS 5C
Display
X
461
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX
DS 1C
Display
X
462
2 PRINT-WORK-PHONE. . . . . . . . . . . . . . BLL=XXXXX
DS 14C
Display
X
463
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX
DS 1C
Display
X
464
2 PRINT-WORK-JUNCTION . . . . . . . . . . . . BLL=XXXXX
DS 25C
Display
X
465
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX
DS 20C
Display
X (10)
467
1 DETAIL2-LINE. . . . . . . . . . . . . . . . . BLL=00002
DS 0CL121
Group
468
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000000 DS 36C
Display
469
2 PRINT-CITY. . . . . . . . . . . . . . . . . BLL=00002 000000036 DS 13C
Display
470
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000049 DS 3C
Display
471
2 PRINT-STATE . . . . . . . . . . . . . . . . BLL=00002 000000052 DS 2C
Display
472
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000054 DS 1C
Display
473
2 PRINT-ZIPCODE . . . . . . . . . . . . . . . BLL=00002 000000055 DS 5C
Display
474
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000060 DS 1C
Display
475
2 PRINT-WORK-PHONE. . . . . . . . . . . . . . BLL=00002 000000061 DS 14C
Display
476
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000075 DS 1C
Display
477
2 PRINT-WORK-JUNCTION . . . . . . . . . . . . BLL=00002 000000076 DS 25C
Display
478
2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000101 DS 20C
Display
(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:
Chapter 19. Debugging
395
v First level of any hierarchy is always 01. Increase 1 for each level (any
item you coded as level 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 containing structure.
(7)
Pseudoassembler code showing how the data is defined. When a structure
contains variable-length fields, the maximum length of the structure is
shown.
(8)
Data type and usage.
(9)
Data definition attribute codes. The definitions are explained at the top of
the DATA DIVISION map.
(10)
DETAILX-LINE was not referenced in the PROCEDURE DIVISION. Because
STGOPT was specified, DETAILX-LINE was deleted, resulting in the base
locator being set to XXXXX.
“Example: embedded map summary”
“Example: nested program map” on page 399
RELATED REFERENCES
“Terms used in MAP output” on page 397
“Symbols used in LIST and MAP output” on page 398
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
000002
000003
000004
. . .
000054
000055
000056
000058
000059
. . .
000060
000061
000062
. . .
000105
000106
000107
000108
000109
000135
000136
000137
000138
000139
000140
000141
000142
000143
000144
000145
000146
000147
000148
000149
000150
000151
000216
000217
000218
396
Identification Division.
Program-id.
IGYTCARA.
Data division.
File section.
FD
COMMUTER-FILE
record 80 characters.
01 commuter-record.
05 commuter-key
05 filler
Working-storage section.
01 Working-storage-for-IGYCARA
77 comp-code
77 ws-type
01 i-f-status-area.
05 i-f-file-status
88 i-o-successful
PIC x(16).
PIC x(64).
pic x.
pic S9999 comp.
pic x(3) value spaces.
pic x(2).
value zeroes.
01 status-area.
05 commuter-file-status
88 i-o-okay
05 commuter-vsam-status.
10 vsam-r15-return-code
10 vsam-function-code
10 vsam-feedback-code
pic 9(2) comp.
pic 9(1) comp.
pic 9(3) comp.
77 update-file-status
77 loccode-file-status
77 updprint-file-status
pic xx.
pic xx.
pic xx.
01 ws-commuter-record EXTERNAL.
05 ws-commuter-key.
10 ws-commuter-generic-key.
Enterprise COBOL for z/OS, V5.1 Programming Guide
(1)
(2)
BLF=00001
BLF=00001,000000000
BLF=00001,000000016
pic x(2).
value zeroes.
(3)
0CL80
16C
64C
1C
2C
3C
0CL2
000000000 2C
0CL8
000000000 2C
000000002
000000002
000000004
000000006
0CL6
2C
2C
2C
2C
2C
2C
BLX=00001
0CL81
BLX=00001,000000000 0CL16
BLX=00001,000000000 0CL5
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
000219
000220
000221
000222
000223
000224
000225
000226
000227
. . .
000395
000396
000397
000398
000399
000400
000401
000402
000403
000404
000405
000406
000407
000408
000409
000410
. . .
000487
000488
000489
15 commuter-shift
15 commuter-home-code
15 commuter-work-code
10 commuter-name
10 commuter-initials
05 commuter-address
05 commuter-city
05 commuter-state
05 commuter-zipcode
pic
pic
pic
pic
pic
pic
pic
pic
pic
x.
xx.
xx.
x(9).
xx.
x(18).
x(13).
xx.
9(5) comp-3.
BLX=00001,000000000
BLX=00001,000000001
BLX=00001,000000003
BLX=00001,000000005
BLX=00001,000000014
BLX=00001,000000016
BLX=00001,000000034
BLX=00001,000000047
BLX=00001,000000049
1C
2C
2C
9C
2C
18C
13C
2C
3P
Linkage Section.
01 detail1-line.
05 filler
05 print-transaction-code
05 filler
05 print-record-type
05 filler
05 print-shift
05 filler
05 print-home-code
05 filler
05 print-work-code
05 filler
05 print-name
05 filler
05 print-initials
pic
pic
pic
pic
pic
pic
pic
pic
pic
pic
pic
pic
pic
pic
xx.
x.
x(4).
x(3).
xxx.
x.
x.
xx.
x.
xx.
xx.
x(9).
xx.
xx.
BLL=00001
BLL=00001,000000000
BLL=00001,000000002
BLL=00001,000000003
BLL=00001,000000007
BLL=00001,000000010
BLL=00001,000000013
BLL=00001,000000014
BLL=00001,000000015
BLL=00001,000000017
BLL=00001,000000018
BLL=00001,000000020
BLL=00001,000000022
BLL=00001,000000031
BLL=00001,000000033
0CL121
2C
1C
4C
3C
3C
1C
1C
2C
1C
2C
2C
9C
2C
2C
procedure division.
000-do-main-logic.
display "PROGRAM IGYTCARA - Beginning".
|
(1)
Base locator used for this data item
|
(2)
Decimal displacement from the beginning of the containing structure
|
(3)
Pseudoassembler code showing how the data is defined
RELATED REFERENCES
“Symbols used in LIST and MAP output” on page 398
Terms used in MAP output
The following table describes the terms used in the listings produced by the MAP
compiler option.
Table 51. Terms used in MAP output
Term
Definition
Description
ALPHABETIC
DS nC
Alphabetic data item (PICTURE A)
ALPHA-EDIT
DS nC
Alphabetic-edited data item
AN-EDIT
DS nC
Alphanumeric-edited data item
2
2
2
BINARY
DS 1H , 1F , 2F , 2C,
4C, or 8C
Binary data item (USAGE BINARY, COMPUTATIONAL, or
COMPUTATIONAL-5)
COMP-1
DS 4C
Single-precision internal floating-point data item (USAGE
COMPUTATIONAL-1)
COMP-2
DS 8C
Double-precision internal floating-point data item (USAGE
COMPUTATIONAL-2)
DBCS
DS nC
DBCS data item (USAGE DISPLAY-1)
DBCS-EDIT
DS nC
DBCS-edited data item (USAGE DISPLAY-1)
DISP-FLOAT
DS nC
Display floating-point data item (USAGE DISPLAY)
DISPLAY
DS nC
Alphanumeric data item (PICTURE X)
DISP-NUM
DS nC
Zoned decimal data item (USAGE DISPLAY)
DISP-NUM-EDIT
DS nC
Numeric-edited data item (USAGE DISPLAY)
FD
FUNCTION-PTR
GROUP
File definition
DS nC
DS 0CLn
Function pointer (USAGE FUNCTION-POINTER)
1
Fixed-length alphanumeric group data item
Chapter 19. Debugging
397
Table 51. Terms used in MAP output (continued)
Term
Definition
1
Description
Variable-length alphanumeric group data item
GRP-VARLEN
DS 0CLn
INDEX
DS nC
Index data item (USAGE INDEX)
INDEX-NAME
DS nC
Index name
NATIONAL
DS nC
Category national data item (USAGE NATIONAL)
NAT-EDIT
DS nC
National-edited data item (USAGE NATIONAL)
NAT-FLOAT
DS nC
National floating-point data item (USAGE NATIONAL)
DS 0CLn
1
National group (GROUP-USAGE NATIONAL)
NAT-GRP-VARLEN
DS 0CLn
1
National variable-length group (GROUP-USAGE NATIONAL)
NAT-NUM
DS nC
National decimal data item (USAGE NATIONAL)
NAT-NUM-EDIT
DS nC
National numeric-edited data item (USAGE NATIONAL)
OBJECT-REF
DS nC
Object-reference data item (USAGE OBJECT REFERENCE)
PACKED-DEC
DS nP
Internal decimal data item (USAGE PACKED-DECIMAL or
COMPUTATIONAL-3)
POINTER
DS nC
Pointer data item (USAGE POINTER)
PROCEDURE-PTR
DS nC
Procedure pointer (USAGE PROCEDURE-POINTER)
NAT-GROUP
SD
Sort 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
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
The following table describes the symbols used in the listings produced by the
LIST or MAP option.
|
Table 52. Symbols used in LIST and MAP output
|
Symbol
|
|
BLF_n
Definition
1
Base locator for files
1
Base locator for LINKAGE SECTION
1
Base locator for object instance data
BLL_n
|
BLO_n
|
1
Base locator for XML-TEXT and XML-NTEXT
1
Base locator for variably located data
1
Base locator for external data
|
BLT_n
BLV_n
|
BLX_n
|
ODOsv_cell
ODO save cell number
|
Pfm_cell
PERFORM cell number
|
Pfmsv_cell
Perform save cell number
|
VLC_cell
Variable length cell (ODO)
|
VN_cell
Variable name cell for PERFORM statement
|
VNGO_cell
Variable name cell for ALTER statement
398
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
Table 52. Symbols used in LIST and MAP output (continued)
|
Symbol
Definition
|
VNI_cell
Variable name initialization
|
|
#Calc00000000n
Code to compute addresses of data that is present after an OCCURS DEPENDING
ON clause
|
#WSVal0000000n
Code to initialize the WORKING-STORAGE area for a procedure
|
_ArgumentList
Outgoing arguments to a procedure
|
_ACON
Address of a symbol
|
_BEtempNNN
Temporary created by the optimizer
|
_CAA
Address of the start of the Language Environment Common Anchor Area
|
_CACHED_$STATIC
Copy of the start address of the static area (for this procedure)
|
_CONSTANT_AREA+n
Offset in the Constant Area
|
_CRENT
Address of the writeable static area (for this module), from the CAA
|
_incomingArgumentList
Incoming parameters to the procedure
|
_parentDSA
For a nested procedure, it is the address of its parent's stack
|
_QCON
Offset to a symbol
|
_returnValue
Return value of the procedure
|
_VTS_n
Temporary created by the optimizer
|
|
|
1. n is the number of the entry. For base locators, it can also be XXXXX, indicating a data item that was deleted by
STGOPT processing.
Example: nested program map
This example shows a map of nested procedures produced by specifying the MAP
compiler option. Numbers in parentheses refer to notes that follow the example.
Nested Program Map
Program Attribute codes (rightmost column) have the following meanings:
C = COMMON
I = INITIAL (1)
U = PROCEDURE DIVISION USING...
(5)
Source Nesting
Program
LineID Level
Program Name from PROGRAM-ID paragraph
Attributes
2
0
NESTMAIN. . . . . . . . . . . . . . . . . . . U
120
1 (4) SUBPRO1 . . . . . . . . . . . . . . . . . . I,C,U
(2)199
2
NESTED1 . . . . . . . . . . . . . . . . . I,C,U
253
1
SUBPRO2 . . . . . . . . . . . . . . . . . . U
335
2
NESTED2 . . . . . . . . . . . . . . . . . C,U
(3)
(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 a program.
Chapter 19. Debugging
399
About this task
|
|
|
|
The LIST compiler option produces several 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:
– 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 that corresponds to that instruction.
After you find the address of the failing instruction, go to the assembler listing
and find the verb for which that instruction was generated. The line number is
in the 3rd column of the assembler listing for your program. Using the line
number, you can locate the VERB by looking at the corresponding line in the
Source Output section of the listing.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
v Information about WORKING-STORAGE. This information is contained in the Data
Division Map and in the Static Map.
v A description of the writeable static area (WSA) is found in the Static Map or
WSA24 Map sections of the listing. The symbols in WORKING-STORAGE area of the
source are mapped into the writable static area that is shown in the Static Map.
You can use the Data Division Map along with the Static Map section to find the
location of data items defined in WORKING-STORAGE. These data items reside in the
Writeable Static Area (WSA or WSA24). The Static Map gives the offset of each
level-1 data item relative to the beginning of the writable static area. The Data
Division Map section gives the offset of the level-n data items relative to their
respective level-1 member. By using both pieces of information, you can
determine the offset of any data member within the writable static area.
If you compile with the DATA24 option, data items mapped below the line will
appear in the WSA24 Map. You can follow the same process to determine their
locations.
v Information about the constants and the literals used in the program. The
Constant Area contains information about the constants and literals in the
program, as well as those created by the compiler. This section contains the
offset of each constant or literal within the Constant Area.
|
|
|
|
v Program prolog areas (PPA1, PPA2, PPA3, PPA4) contain information about the
characteristics of the compiled program.
v Externals symbols dictionary contains the list of external symbols defined by or
referred to, in your program.
|
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 each time a separately compiled procedure
is entered.
You do not need to be able to program in assembler language to understand the
LIST output. The comments that accompany most of the assembler code provide
you with a conceptual understanding of the functions performed by the code.
“Example: program initialization code” on page 407
“Example: Timestamp and version information” on page 408
“Example: Compiler options and program information” on page 408
400
Enterprise COBOL for z/OS, V5.1 Programming Guide
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
“Example:
assembler code generated from source code” on page 409
Program prolog areas” on page 409
Static map” on page 410
Constant area” on page 411
Base locator table” on page 412
External symbols” on page 412
DSA memory map (Automatic map)” on page 413
RELATED REFERENCES
“Signature information bytes”
“Example: MAP output” on page 395
Language Environment Programming Guide (Stack storage overview)
|
|
|
|
Signature information bytes
|
Table 53. Compiler options in the INFO BYTE section
|
|
Offset in
decimal
Option
Value
|
00
CODEPAGE
CCSID value specified for EBCDIC code page
|
02
ARCH
6
The tables in this topic show program signature information that is part of the
listing of program initialization code provided when you use the LIST compiler
option.
|
7
|
8
|
9
|
10
|
03
OPTIMIZE
0
|
1
|
|
2
|
|
|
The INFO BYTE section of the listing also provides the following values:
v The number of DATA DIVISION statements
v The number of PROCEDURE DIVISION statements
|
|
In the following table, different signature bytes represent different information:
v Signature bytes 1-5, and 26-29 refer to the compiler options
v Signature bytes 6-7 refer to the DATA DIVISION items
v Signature byte 8 refers to the ENVIRONMENT DIVISION items
v Signature bytes 9-25 refer to the PROCEDURE DIVISION verbs and items
|
|
|
Chapter 19. Debugging
401
|
Table 54. Signature information bytes
|
|
|
|
Offset
in
Signature
decimal byte
Bit
On
Off
|
04
0
SQL
NOSQL
|
1
CICS
NOCICS
|
2
MDECK
NOMDECK
|
3
SQLCCSID
NOSQLCCSID
|
4
OPTFILE
NOOPTFILE
|
5
XMLPARSE(XMLSS) (always on)
|
6
BLOCK0
NOBLOCK0
|
7
DISPSIGN(SEP)
DISPSIGN(COMPAT)
0
Program uses Java-based OO syntax
|
1
Program uses RANDOM function
|
2
Program uses NATIONAL data (Unicode)
|
3
XML PARSE with schema validation
|
4
STGOPT
NOSTGOPT
|
5
AFP(VOLATILE)
AFP(NOVOLATILE)
|
6
HGPR(PRESERVE)
HGPR(NOPRESERVE)
|
7
NOTEST(DWARF)
Not NOTEST(DWARF)
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
0
LIB (always on)
|
1
LIST
NOLIST
|
2
MAP
NOMAP
|
3
NUM
NONUM
|
4
OBJECT
NOOBJECT
|
5
OFFSET
NOOFFSET
|
6
OPT(1), OPT(2)
NOOPT, OPT(0)
|
7
OUTDD
NOOUTDD
|
|
|
05
08
09
402
28
29
1
2
Item
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
Table 54. Signature information bytes (continued)
|
|
|
|
Offset
in
Signature
decimal byte
Bit
On
Off
|
10
0
NUMPROC(PFD)
NUMPROC(NOPFD)
|
1
RENT
NORENT
|
2
RESIDENT (always on)
|
3
SEQUENCE
|
4
Reserved
|
5
SOURCE
NOSOURCE
|
6
SSRANGE
NOSSRANGE
|
7
TERM
NOTERM
0
TEST
NOTEST
|
1
TRUNC(STD)
Not TRUNC(STD)
|
2
WORD
NOWORD
|
3
VBREF
NOVBREF
|
4
XREF
NOXREF
|
5
ZWB
NOZWB
|
6
NAME
NONAME
|
7
|
|
11
4
NOCMPR2 (always off)
Reserved
NONUMPROC
|
1
NUMCLS=ALT
NUMCLS=PRIM
|
2
DBCS
NODBCS
|
3
AWO
NOAWO
|
4
TRUNC(BIN)
Not TRUNC(BIN)
|
5
ADATA
NOADATA
|
6
CURRENCY
NOCURRENCY
|
7
Compilation unit is a class
Compilation unit is a program
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
13
5
NOSEQUENCE
0
|
12
3
Item
6
Chapter 19. Debugging
403
|
Table 54. Signature information bytes (continued)
|
|
|
|
Offset
in
Signature
decimal byte
Bit
On
|
14
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 or FUNCTION-POINTER item
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
0
ACCEPT
|
1
ADD
|
2
ALTER
|
3
CALL
|
4
CANCEL
|
6
CLOSE
0
COMPUTE
|
2
DELETE
|
4
DISPLAY
|
|
|
15
16
17
7
8
9
10
|
Item
5
DIVIDE
1
END-PERFORM
|
2
ENTER
|
3
ENTRY
|
4
EXIT
|
5
EXEC
|
6
GO TO
|
7
IF
0
INITIALIZE
|
1
INVOKE
|
2
INSPECT
|
3
MERGE
|
4
MOVE
|
5
MULTIPLY
|
6
OPEN
|
7
PERFORM
|
|
18
19
404
11
12
Enterprise COBOL for z/OS, V5.1 Programming Guide
Off
|
Table 54. Signature information bytes (continued)
|
|
|
|
Offset
in
Signature
decimal byte
Bit
On
|
20
0
READ
|
2
RELEASE
|
3
RETURN
|
4
REWRITE
|
5
SEARCH
|
7
SET
0
SORT
|
1
START
|
2
STOP
|
3
STRING
|
4
SUBTRACT
|
7
UNSTRING
0
USE
|
1
WRITE
|
2
CONTINUE
|
3
END-ADD
|
4
END-CALL
|
5
END-COMPUTE
|
6
END-DELETE
|
7
END-DIVIDE
|
|
|
21
22
14
15
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
|
23
13
24
16
Item
17
Off
Chapter 19. Debugging
405
|
Table 54. Signature information bytes (continued)
|
|
|
|
Offset
in
Signature
decimal byte
Bit
On
|
25
0
END-INVOKE
|
1
END-EXEC
|
2
XML
|
3
END-XML
18
Item
Off
|
26
19
0-7
Reserved
|
27
20
0-7
Reserved
|
28
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
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
|
|
|
29
30
40
406
22
23
24
Enterprise COBOL for z/OS, V5.1 Programming Guide
|
Table 54. Signature information bytes (continued)
|
|
|
|
Offset
in
Signature
decimal byte
Bit
On
|
41
0
GLOBAL
|
1
RECORD IS VARYING
|
5
Intrinsic function was used
|
6
Z-literal found
|
7
RECURSIVE
0
RMODE(ANY)
|
1–3
Reserved
|
4
Reserved
|
5
INTDATE(LILIAN)
|
6
Reserved
|
7
Reserved
0
PGMNAME(LONGUPPER)
Not PGMNAME(LONGUPPER)
|
1
PGMNAME(LONGMIXED)
Not PGMNAME(LONGMIXED)
|
2
DLL
NODLL
|
3
EXPORTALL
NOEXPORTALL
|
4
TEST(SOURCE)
Not TEST(SOURCE)
|
5
ARITH(EXTEND)
ARITH(COMPAT)
|
6
THREAD
NOTHREAD
|
|
7
TEST(EJPD)
TEST(NOEJPD)
|
|
42
43
25
26
27
Item
Off
Not RMODE(ANY)
INTDATE(ANSI)
|
|
|
Check return code: A return code greater than 4 from the compiler could mean
that some of the verbs shown in the information bytes might have been discarded
from the program.
|
|
RELATED REFERENCES
|
Example: program initialization code
“LIST” on page 341
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(1)
000000
000000
000004
000008
00000C
000010
000014
000014
000018
00001C
000020
000022
000024
000024
000028
00002C
000030
000034
000038
00003C
00003C
000040
000044
(2)
47F0
01C3
0000
0000
47F0
F014
C5C5
0978
8910
F001
90EC D00C
4110 F024
98EF F034
07FF
0000
0000
0000
0000
0000
0000
0000
0000
0000
8A0C
8948
0054
0000
0000 0024
0000 8A1C
(3)
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
000003
(4)
L3282:
L3284:
L3285:
L3280:
PROC
BC
DC
DC
DC
BC
EQU
STM
LA
LM
BR
DC
EQU
DC
DC
DC
DC
DC
DC
EQU
DC
DC
EQU
IGYTCARA
R15,20(,R15)
X’01C3C5C5’
X’00000978’
X’00008910’
R15,1(,R15)
*
R14,R12,12(,R13)
R1,36(,R15)
R14,R15,52(,R15)
R15
X’0000’
*
X’00000000’
X’00000000’
X’00008A0C’
X’00008948’
X’00000054’
X’00000000’
*
X’00000024’
X’00008A1C’
*
(5)
#
#
#
#
#
Skip over constant area
Eyecatcher: CEE
Stack Size
Offset to PPA1
Wrong Entry Point: cause exception
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Save GPRs Used
Args for boot strap routine
Branch to boot strap routine
Available half-word
Boot Strap Info Block
address of entry label
WSA24 allocation size
address of Saved Option String
address of entry point name
A(Label L3283)
address of boot strap routine(IGZXBST)
CEE Parameter Block
address of infoBlockLabel
A(PARMCEE-CEEEPARMBlock)
Handle growing stack
Chapter 19. Debugging
407
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
000044
000048
00004A
00004C
000050
000054
000054
000054
000056
00005A
00005E
000062
000062
000066
00006A
00006E
000072
000076
00007A
00007C
000080
000084
000088
58F0 C31C
184E
05EF
0000 0000
A7F4 0009
000003
L
000003
LR
000003
BALR
000003
DC
000003
J
000003 @MAINENT DS
000003 L3283:
EQU
000003
LR
000003
LA
000003
CL
000003
JH
000003 L3281:
EQU
000003
ST
000003
LHI
000003
SLL
000003
AHI
000003
ST
000003
ST
000003
LR
000003
LA
000003
ST
000003
LA
000003
ST
18EF
4100 E978
5500 C314
A724 FFF3
5000
A708
8900
A70A
5000
50D0
18DE
4100
5000
4100
5000
E04C
0010
0010
0301
E000
E004
D6D0
D074
0000
D070
R15,796(,R12)
R4,R14
R14,R15
X’00000000’
L3281
0H
*
R14,R15
R0,2424(,R14)
R0,788(,R12)
L3280
*
R0,76(,R14)
R0,16
R0,16
R0,769
R0,0(,R14)
R13,4(,R14)
R13,R14
R0,1744(,R13)
R0,116(,R13)
R0,0(,R0)
R0,112(,R13)
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
Load CEECAAOGETS
Required NAB
Extend Stack
Argument list size = 0
Branch back
PRIMARY ENTRY POINT ADDRESS
User Code Entry Point
Load NAB
New NAB Address
Exceed current storage segment?
Yes: branch to recovery code
Stack now has sufficient room
Update NAB
COBOL Language Word upper half
shift to upper half of register
add COBOL Language Word lower half
Save Language Word
Save Back Chain
Set new DSA
Address of COBDSACB
Saved in member slot1
zero member slot0
(1)
Offset from the start of the COBOL program
(2)
Hexadecimal representation of assembler instructions
|
(3)
Source line number
|
|
(4)
Pseudo-assembler representation of the code generated for the COBOL
program
|
(5)
Comments that explain the pseudo-assembler code
RELATED REFERENCES
“Signature information bytes” on page 401
Example: Timestamp and version information
|
|
|
|
|
|
|
|
|
The following example shows LIST output about the version of the compiler and
the data and time of compilation.
Timestamp and Version Information
0029C8
0029CC
0029D0
0029D6
F2F0
F0F3
F1F2
F0F5
F1F3
F2F7
F3F1
F0F1
=C’2013’
=C’0327’
=C’123122’
=C’050100’
F2F2
F0F0
Compiled Year
Compiled Date MMDD
Compiled Time HHMMSS
VERSION/RELEASE/MOD LEVEL OF PROD
Timestamp and Version End
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example: Compiler options and program information
|
(1)
Offset in the load module
|
(2)
Offset in decimal
|
(3)
Contents of the bytes in hexadecimal format
|
(4)
Assembler representation of the bytes
|
(5)
Explanation of the bytes in the section
The following example shows LIST output for the compiler options and program
information.
DATA VALIDATION AND UPDATE PROGRAM
(1)
0029DC
0029DE
0029E0
0029E1
0029E2
0029E4
0029E6
0029EC
0029F2
0029F8
0029FD
0029FE
002A02
002A06
002A0A
408
(2)
(3)
(+00)
(+02)
(+03)
(+04)
(+06)
(+08)
(+14)
(+20)
(+26)
(+31)
(+32)
(+36)
(+40)
(+44)
0030
0474
06
00
1406
0000
A04875CC2001
100010884909
002008800C00
000001A000
00
0000002F
0000005B
18808008
40404040
IGYTCARA Date 03/30/2013 Time 10:48:16
Compiler Options and Program Information Section
(4)
(5)
=X’0030’
Size of Compiler Options and Prog Info Section
=X’0474’
UNSIGNED BINARY CODE PAGE CCSID VALUE
=X’06’
ARCHITECTURE LEVEL
=X’00’
OPTIMIZATION LEVEL
=X’1406’
INFO. BYTES 28-29
=X’0000’
RESERVED
=X’A04875CC2001’ INFO. BYTES 1-6
=X’100010884909’ INFO. BYTES 7-12
=X’002008800C00’ INFO. BYTES 13-18
=X’000001A000’
INFO. BYTES 19-23
=X’00’
COBOL SIGNATURE LEVEL
=X’0000002F’
# DATA DIVISION STATEMENTS
=X’0000005B’
# PROCEDURE DIVISION STATEMENTS
=X’18808008’
INFO. BYTES 24-27
=C’
’
USER LEVEL INFO (LVLINFO)
Compiler Options and Program Information Section End
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 that corresponds to the instruction that failed.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
000964:
display "PROGRAM IGYTCARA - Beginning".
(2)
0001EA
0001F0
0001F6
0001FC
000202
000206
00020A
000210
000216
00021C
000222
000228
00022C
000232
000236
000965:
000238
00023C
000240
000246
00024A
00024E
000252
(1)
(3)
(4)
(5)
E320 3394 0171
000964
LAY
R2,5012(,R3)
#
D203 D5E8 2000
000964
MVC
1512(4,R13),0(R2)
#
E320 3398 0171
000964
LAY
R2,5016(,R3)
#
D203 D5EC 2000
000964
MVC
1516(4,R13),0(R2)
#
4120 39C8
000964
LA
R2,2504(,R3)
#
5020 D5F0
000964
ST
R2,1520(,R13)
#
E320 338C 0171
000964
LAY
R2,5004(,R3)
#
D203 D5F4 2000
000964
MVC
1524(4,R13),0(R2)
#
E320 339C 0171
000964
LAY
R2,5020(,R3)
#
D203 D5F8 2000
000964
MVC
1528(4,R13),0(R2)
#
D703 D5FC D5FC
000964
XC
1532(4,R13),1532(R13) #
4110 D5E8
000964
LA
R1,1512(,R13)
# _ArgumentList
E3F0 31D4 0158
000964
LY
R15,4564(,R3)
# _ACON
58C0 D080
000964
L
R12,128(,R13)
# _@CAA
0DEF
000964
BASR
R14,R15
# Call "IGZXDSP"
perform 050-create-vsam-master-file.
5820 D670
000965
L
R2,1648(,R13)
# VN_cell
5020 D544
000965
ST
R2,1348(,R13)
# PfmSv_Cell
C020 0000 0007
000965
LARL
R2
5020 D670
000965
ST
R2,1648(,R13)
# VN_cell
A7F4 02F4
000965
J
050-CREATE-VSAM-MASTER-FILE
5820 D544
000965
L
R2,1348(,R13)
# PfmSv_Cell
5020 D670
000965
ST
R2,1648(,R13)
# VN_cell
(6)
_$CONSTANT_AREA+5012
_$CONSTANT_AREA+5016
_$CONSTANT_AREA+5004
_$CONSTANT_AREA+5020
(1)
Source code interspersed with the pseudo-assembler instructions
(2)
Relative location of the object code instruction in the module, in
hexadecimal notation
(3)
Object code instructions, 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)
Source line number associated with this assembler code
|
(5)
Object code instructions, in compiler-generated pseudo assembler
|
(6)
Explanation of the instruction and the operands used by the instructions
RELATED REFERENCES
“Symbols used in LIST and MAP output” on page 398
|
|
|
|
Example: Program prolog areas
|
|
|
|
There is a PPA1 for every procedure in your program, including procedures
generated by the compiler. The offset to its corresponding PPA1 is recorded at offset
12 (X'C') from the start of each procedure. The PPA1 contains information about the
procedure as well as offsets to the PPA2 and PPA3 sections.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For details on how to use the program prolog areas to locate information in the
listing file, see z/OS Language Environment Vendor Interfaces.
The following example shows LIST output for the program prolog area. The
Program Prologue Area (PPA) is comprised of several sections that contain
information about the compiled program.
DATA VALIDATION AND UPDATE PROGRAM
1
2
0081E0
0081E4
0081E8
0081EC
0081F0
0081F4
0081F8
0081F9
0081FC
0081FE
008200
1CCEA506
00008310
00008378
00000000
FFFE0000
40000000
90
000978
0000
0012
D00006D0
IGYTCARA Date 03/30/2013 Time 10:48:16
3
PPA1:
4
Entry Point Constants
=F’483304710’
=A(PPA2-IGYTCARA)
=A(PPA3-IGYTCARA)
=F’0’
=F’-131072’
=F’1073741824’
=AL1(144)
=AL3(2424)
=AL1(0)
=H’18’
=F’-805304624’
Flags
No EPD
Register Save Mask
Member Flags
Flags
Callee’s DSA use/8
Flags
Offset/2 to CDL
State variable location
Chapter 19. Debugging
409
|
|
|
|
|
|
|
008204
008208
00820C
008210
008214
008218
00000000
00000000
00000000
00000000
00000000
0008 ****
=F’0’
=F’0’
=F’0’
=F’0’
=F’0’
AL2(8),C’IGYTCARA’
PPA1
CDL
CDL
CDL
CDL
CDL
function length/2
function EP offset
prolog
epilog
end
End
|
|
|
|
|
|
|
|
|
|
|
There is one PPA2 for each program. The offset to the PPA2 is recorded in each PPA1.
The PPA2 contains offsets to the Time Stamp and Version Information section of
the listing as well as to the PPA4 section.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
There is one PPA4 for each program. It has offsets to various compiler generated
tables, such as the writable static area ( the Static Map and WSA24 sections). The
offset to the PPA4 is recorded in a field of the PPA2.
|
|
|
|
|
|
There is one PPA3 for each procedure in the program. The PPA3 contains the offset
to the base locator table for its procedure.
|
|
1
Relative location, in hexadecimal format, of the PPA field in the object
module
|
2
The contents of the field, in hexadecimal
|
3
An assembler-like syntax defining the field
|
4
A description of the contents of the field.
|
|
RELATED REFERENCES
|
|
Example: Static map
|
|
|
|
|
|
|
|
|
|
|
|
|
The STATIC MAP contains the level-1 symbols defined in the WORKING-STORAGE part
of the program. If compiled with the RENT option, the first column contains the
offset of the level-1 symbol from the start of the Working Storage Area (WSA) for
the program. For NORENT compilations, the offset is the start of the level-1 from a
block of storage allocated by the compiler. The starting address of this block
resides in the Constant Area. The second column is the size of the symbol,
including all of its sub-level members. The third column is the name.
PPA2:
008310
008314
008318
00831C
008320
008324
=F’67117571’
Flags
=A(CEESTART-PPA2)
=F’48’
A(PPA4-PPA2)
=A(TIMESTMP-PPA2)
=A(PrimaryEntryPoint-PPA2)
=F’35651584’
Flags
PPA2
PPA4:
008340
008344
008348
00834C
008350
008354
008358
00835C
008360
008364
008368
End
Entry Point Constants
08000000
00020100
00000000
00000000
00000000
FFFF7CC0
00008398
00000000
00002204
00000000
002A
=F’134217728’
=F’131328’
=F’0’
=F’0’
=F’0’
=F’-33600’
=F’33688’
=F’0’
=F’8708’
=F’0’
=X’2A’
PPA4
PPA3:
008378
00837C
Entry Point Constants
04002203
FFFF7CF0
00000030
FFFFFFB8
FFFF7CF0
02200000
End
Entry Point Constants
00000000
00000008
=F’0’
=F’8’
PPA3
Flags 1
Flags 2
A(NORENTstatic)
Q(RENTstatic)
A(DATA24_address_cell-RENTstatic)
A(Code-PPA4)
Code Length
Length NORENTstatic
Length RENTstatic
Length DATA24
A(CUName-PPA4)
Flags
A(Base_Locator_Table-PPA3)
End
z/OS Language Environment Vendor Interfaces
The following example shows LIST output about the writable static area.
* * * * *
OFFSET (HEX)
0
14
410
LENGTH (HEX)
14
C
Enterprise COBOL for z/OS, V5.1 Programming Guide
S T A T I C
NAME
BLF_Ptrs
BLT_Ptrs
M A P
* * * * *
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
20
28
30
38
40
48
50
58
60
68
70
78
80
A0
A8
F8
148
1C8
1D0
1D8
1E0
1E8
1F0
1F8
200
208
4
2
2
8
4
4
4
8
4
1
1
4
1E
4
50
50
7A
1
2
3
2
8
2
2
2
3
JNIENVPTR
RETURN-CODE
SORT-RETURN
SORT-CONTROL
SORT-CORE-SIZE
SORT-FILE-SIZE
SORT-MODE-SIZE
SORT-MESSAGE
TALLY
SHIFT-OUT
SHIFT-IN
XML-CODE
XML-EVENT
XML-INFORMATION
COMMUTER-FILE
COMMUTER-FILE-MST
PRINT-FILE
WORKING-STORAGE-FOR-IGYCARA
COMP-CODE
WS-TYPE
I-F-STATUS-AREA
STATUS-AREA
UPDATE-FILE-STATUS
LOCCODE-FILE-STATUS
UPDPRINT-FILE-STATUS
FLAGS
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If you compile with the compiler option DATA(24), a WSA 24 Map is generated. It
shows the names of the symbols that are mapped below the 16 MB line. The
symbols in the WORKING-STORAGE area in the source are mapped into the writable
static area which is shown in the Static Map.
|
|
|
Example: Constant area
* * * * *
OFFSET (HEX)
LENGTH (HEX)
0
8
10
18
20
28
30
38
40
48
50
58
60
80
88
D8
128
1A8
1B0
1B8
1C0
1C8
1D0
4
2
2
8
4
4
4
8
4
1
1
4
1E
4
50
50
7A
1
2
3
2
8
2
W S A
2 4
M A P
* * * * *
NAME
JNIENVPTR
RETURN-CODE
SORT-RETURN
SORT-CONTROL
SORT-CORE-SIZE
SORT-FILE-SIZE
SORT-MODE-SIZE
SORT-MESSAGE
TALLY
SHIFT-OUT
SHIFT-IN
XML-CODE
XML-EVENT
XML-INFORMATION
COMMUTER-FILE
COMMUTER-FILE-MST
PRINT-FILE
WORKING-STORAGE-FOR-IGYCARA
COMP-CODE
WS-TYPE
I-F-STATUS-AREA
STATUS-AREA
UPDATE-FILE-STATUS
The following example shows LIST output about strings and other literals from the
COBOL source as well as those generated by the compiler.
Chapter 19. Debugging
411
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The compiler generates loads from (and stores to) the Constant Area by loading
the starting address of Constant Area and adding the fixed offsets to the respective
constants or literals.
|
(1)
Offset in csect.
|
(2)
Offset in base 10.
|
(3)
8 columns containing the bytes in the Constant Area
|
(4)
Character representation. A dot (.) is used for non-printable characters.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example: Base locator table
|
|
For more information about the base locator table, see z/OS Language Environment
Vendor Interfaces.
|
|
RELATED REFERENCES
|
|
|
|
Example: External symbols
|
Each entry contains the address, length and symbol type. Symbol types are:
|
ED
External Definition
|
SD
Section Definition
|
LD
Label Definition
|
ER
External Reference
|
|
|
|
|
PR
Pseudo Register
CONSTANT AREA:
(1)
006A98
006AB8
006AD8
006AF8
006B18
006B38
006B58
006B78
006B98
006BB8
006BD8
006BF8
006C18
006C38
006C58
006C78
006C98
006CB8
006CD8
(2)
(+0)
(+32)
(+64)
(+96)
(+128)
(+160)
(+192)
(+224)
(+256)
(+288)
(+320)
(+352)
(+384)
(+416)
(+448)
(+480)
(+512)
(+544)
(+576)
(3)
00CCDDFF
40000A00
0E000000
000FE800
0000000E
4B40C3D6
C5404040
C540D9C5
40404040
C4C54040
D5C54040
C3E3C9D6
E2E3C1E3
40404040
C3D6D4D4
40404040
D7C1C7C5
C3C1D9C1
00000030
00000000
40000000
00000001
9F0F0000
00000000
C4C50000
40400000
C34B0000
40400000
40400000
40400000
D5400000
E4E20000
40404040
E4E3C5D9
40404040
407B7A40
40404040
00000000
C9C7E8E3
00000008
0F000000
00000011
E2C8C9C6
E6D6D9D2
C9D5C9E3
D9C5C34B
C3C9E3E8
E9C9D7C3
E6D6D9D2
E6D6D9D2
40D9C5D7
40404040
40C6C9D3
40404040
00000000
404040D9
D9E4D540
(4)
C3C1D9C1
00000000
0000001E
00000000
E340C3D6
40D3D6C3
C9C1D3E2
40D5D6E3
40404040
D6C4C540
40D7C8D6
40D1E4D5
D6D9E340
40404040
C540E4D7
40404040
00000010
E4D540E3
C4C1E3C5
00000000
E2E8E2D6
00000000
E3D9C1D5
C4C54040
4B40C3D6
40404040
40C6D6E4
40404040
40404040
D5C54040
C3E3C9D6
407B7A40
40404040
C4C1E3C5
40400000
40D7D9D6
C9D4C57A
7A400000
00000000
E4E34040
40000000
E2C1C3E3
40400000
C4C50000
40400000
D5C40000
40400000
40400000
40400000
D5400000
C9C7E8E3
40404040
40D3C9E2
00000032
C7D9C1D4
40000000
0000000A
C9C7E9E2
00100000
00000003
4B40C3D6
C8D6D4C5
D3C1E2E3
C4E4D7D3
C1C4C4D9
E2E3C1E3
C8D6D4C5
C8D6D4C5
C4D9C9E5
C3C1D9C1
40404000
E3404040
40404040
407B7A40
00000025
61000000
D9E3C3C4
00000000
0064003C
C4C50000
40D3D6C3
40D5C1D4
C9C3C1E3
C5E2E240
C540C3D6
40D7C8D6
40D1E4D5
C9D5C740
40404040
00000033
40404040
40404040
C9C7E8E3
7A000000
0000000B
|........IGYTCARA........IGZSRTCD|
| ... ...........SYSOUT ........|
|.................... ...........|
|..Y.............TRANSACT. CODE..|
|........SHIFT CODE
..HOME LOC|
|. CODE..WORK LOC. CODE..LAST NAM|
|E
..INITIALS
..DUPLICAT|
|E REC...REC. NOT FOUND..ADDRESS |
|
..CITY
..STATE CO|
|DE
..ZIPCODE
..HOME PHO|
|NE
..WORK PHONE
..HOME JUN|
|CTION ..WORK JUNCTION ..DRIVING |
|STATUS.. REPORT #: IGYTCARA
|
|
.....|
|COMMUTER FILE UPDATE LIST
|
|
......
|
|PAGE #: ........ PROGRAM #: IGYT|
|CARA
RUN TIME: .......:...|
|........RUN DATE: ....../.......|
The following example shows LIST output for the base locator table.
Base Locator Table
008AB0
008AB1
008AB2
008AB4
008AB8
008ABA
008ABE
008ABF
008AC1
008AC5
008AC6
01
00
0008
00000010
2A00
00000014
03
0A00
00000000
05
0000
=X’1’
=X’0’
=H’8’
=F’16’
=X’2A00’
=X’14’
=X’3’
=X’A00’
=X’0’
=X’5’
=X’0’
Table Version
Reserved
Header length
Array byte length
Flags & info (element 1)
Offset to cells
Cell count
Flags & info (element 2)
Offset to cells
Cell count
Flags & info (end of array)
Base Locator Table End
z/OS Language Environment Vendor Interfaces (Base locator table)
The following example shows LIST output for external symbols defined by, or
referred to in your program. The external symbol dictionary contains one entry per
external symbol defined by or referred to in the program.
E X T E R N A L
TYPE
412
Enterprise COBOL for z/OS, V5.1 Programming Guide
ID
S Y M B O L
ADDR
LENGTH
D I C T I O N A R Y
NAME
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
SD
ED
ED
LD
ER
ER
ED
PR
ED
ER
ER
ER
ER
ER
ER
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
000000
008AC8
000000
000000
000000
000000
002204
000022
000000
000000
000000
000000
000000
000000
IGYTCARA
C_CEESG003
C_CODE
IGYTCARA#C
CEESTART
CEEBETBL
C_WSA
IGYTCARA#S
B_IDRL
IGZXBST
IGYTCARA
IGZXPRS
IGZXCMSG
IGZXDSP
IGZXVCLS
|
|
Example: DSA memory map (Automatic map)
The following example shows LIST output for the dynamic save area (DSA). The
DSA contains information about the contents of the storage acquired when a
separately compiled procedure is entered.
* * * * * A U T O M A T I C
1
2
OFFSET (HEX)
LENGTH (HEX)
M A P
3
NAME
* * * * *
Block name: IGYTCARA
80
C8
CC
D0
D4
D8
DC
E0
E4
E8
F8
118
138
13C
140
144
148
14C
150
154
158
15C
160
164
168
16C
170
174
178
4
3
3
3
3
3
3
3
3
10
20
20
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
_@CAA
_BEtemp200
_BEtemp204
_BEtemp208
_BEtemp212
_BEtemp216
_BEtemp220
_BEtemp224
_BEtemp228
_BEtemp232
_BEtemp248
_BEtemp280
_BEtemp312
_BEtemp316
_BEtemp320
_BEtemp324
_BEtemp328
_BEtemp332
_BEtemp336
_BEtemp340
_BEtemp344
_BEtemp348
_BEtemp352
_BEtemp356
_BEtemp360
_BEtemp364
_BEtemp368
_BEtemp372
_BEtemp376
(1)
Hexadecimal offset of the DSA field from the start of the DSA
|
(2)
Length (in hexidecimal) of the DSA field
|
(3)
Symbol name
Chapter 19. Debugging
413
Example: XREF output: data-name cross-references
The following example shows a sorted cross-reference of data-names that is
produced by the XREF compiler option. Numbers in parentheses refer to notes after
the example.
An "M" preceding a data-name reference indicates that the
data-name is modified by this reference.
(1)
Defined
265
266
347
381
280
382
(2)
Cross-reference of data-names
(3)
References
ABEND-ITEM1
ABEND-ITEM2
ADD-CODE . . .
ADDRESS-ERROR.
AREA-CODE. . .
CITY-ERROR . .
1102 1162
M1126
1236 1261 1324 1345
M1129
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
(4)
Context usage is indicated by the letter preceding a procedure-name
reference. These letters and their meanings are:
A = ALTER (procedure-name)
D = GO TO (procedure-name) DEPENDING ON
E = End of range of (PERFORM) through (procedure-name)
G = GO TO (procedure-name)
P = PERFORM (procedure-name)
T = (ALTER) TO PROCEED TO (procedure-name)
U = USE FOR DEBUGGING (procedure-name)
(5)
Defined
877
930
982
1441
1481
1543
1636
1652
1676
1050
1124
1159
1207
1258
1288
1312
(6)
Cross-reference of procedures
(7)
References
000-DO-MAIN-LOGIC
050-CREATE-STL-MASTER-FILE .
100-INITIALIZE-PARAGRAPH . .
1100-PRINT-I-F-HEADINGS. . .
1200-PRINT-I-F-DATA. . . . .
1210-GET-MILES-TIME. . . . .
1220-STORE-MILES-TIME. . . .
1230-PRINT-SUB-I-F-DATA. . .
1240-COMPUTE-SUMMARY . . . .
200-EDIT-UPDATE-TRANSACTION.
210-EDIT-THE-REST. . . . . .
300-UPDATE-COMMUTER-RECORD .
310-FORMAT-COMMUTER-RECORD .
320-PRINT-COMMUTER-RECORD. .
330-PRINT-REPORT . . . . . .
400-PRINT-TRANSACTION-ERRORS
P879
P880
P915
P916
P1510
P1511
P1532
P1533
P886
P1116
P888
P1164 P1179
P1165 P1176 P1182 P1192
P1178 P1202 P1256 P1280 P1340 P1365 P1369
P890
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
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:
(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.
“Example: XREF output: program-name cross-references” on page 415
“Example: XREF output: COPY/BASIS cross-references” on page 415
“Example: XREF output: embedded cross-reference” on page 416
414
Enterprise COBOL for z/OS, V5.1 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. Numbers in parentheses refer to notes that follow the
example.
(1)
Defined
(2)
Cross-reference of programs
(3)
References
EXTERNAL
2
12
20
27
35
EXTERNAL1. . . . . . . . . . .
X. . . . . . . . . . . . . . .
X1 . . . . . . . . . . . . . .
X11. . . . . . . . . . . . . .
X12. . . . . . . . . . . . . .
X2 . . . . . . . . . . . . . .
25
41
33
25
32
40
7
16
17
8
(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: XREF output: COPY/BASIS cross-references
The following example shows a sorted cross-reference of copybooks to the
library-names and data-set names of the associated copybooks, produced by the
XREF compiler option under z/OS. Numbers in parentheses refer to notes after the
example.
COPY/BASIS cross-reference of text-names, library names
(1)
Text-name
(Member)
(1)
Library
(DDNAME)
(2)
File name
(Data set name)
ACTIONS
ACTIONS
CUSTOMER
CUSTOMER
HOUSE
HOUSE
IMOTOR
ISOVERFY
NSMAP
OTHERLIB
SYSLIB
ALTDDXXY
SYSLIB
ALTDDXXY
SYSLIB
SYSLIB
SYSLIB
SYSLIB
USERID.COBOL.COPY
USERID.COBOL.COPY
USERID.COBOL.LIB3
USERID.COBOL.LIB2PDSE
USERID.COBOL.LIB2
USERID.COBOL.LIB2PDSE
USERID.COBOL.LIB4X
USERID.COBOL.COPY
USERID.COBOL.LIB3
(3)
Concat
Level
(4)
ISPF
Created
0
0
0
1
1
1
3
0
2
1992/07/11
1992/07/11
2007/06/01
2007/06/07
2007/06/07
2007/06/07
(1)
Text-name and library (an abbreviation for library-name) are from the
statement COPY text-name OF library-name in the source, for example,
Copy ACTIONS Of OTHERLIB.
(2)
The name of the data set from which the COPY member was copied.
(3)
Abbreviation for concatenation level. Indicates how many levels deep a
given data set is from the first data set in the concatenation for a given
ddname.
For example, four data sets in the example above are concatenated to
ddname SYSLIB:
DDNAME
SYSLIB
DSNAME
DD
DD
DD
DD
DSN=USERID.COBOL.COPY,
DSN=USERID.COBOL.LIB2PDSE,
DSN=USERID.COBOL.LIB3,
DSN=USERID.COBOL.LIB4X
(concatenation level)
0
1
2
3
Chapter 19. Debugging
415
Thus for example member NSMAP shown in the listing above was found
in data set USERID.COBOL.LIB3, which is two levels down from the first
data set in the SYSLIB concatenation.
(4)
Creation date is shown if the PDS or PDSE was edited with STATS ON in
ISPF.
Tip: Under z/OS, if there is more than one data set in your SYSLIB concatenation,
the COPY/BASIS cross-reference might in some cases be incomplete or missing. For
details, see the related reference about the XREF compiler option.
If you compile in the z/OS UNIX shell, the cross-reference looks like the excerpt
shown below.
COPY/BASIS cross-reference of text-names, library names, and file names
(5)
Text-name
(5)
Library-name
’/copydir/copyM.cbl’
’/copyA.cpy’
’cobol/copyA.cpy’
’copy/stuff.cpy’
’copydir/copyM.cbl’
’copydir/copyM.cbl’
’stuff.cpy’
"copyA.cpy"
(7)
"reallyXXVeryLongLon>
OTHERDD
. . .
SYSLIB
SYSLIB
ALTDD2
ALTDD2
SYSLIB
SYSLIB (default)
ALTDD
SYSLIB (default)
SYSLIB (default)
ALTDD2
Note: Some names were truncated.
(5)
(6)
File name
/u/JSMITH/cobol//copydir/copyM.cbl
/u/JSMITH/cobol//copyA.cpy
/u/JSMITH/cobol/copyA.cpy
/u/JSMITH/copy/stuff.cpy
/u/JSMITH/cobol/copydir/copyM.cbl
/u/JSMITH/cobol/copydir/copyM.cbl
/u/JSMITH/copy/stuff.cpy
/u/JSMITH/cobol/copyA.cpy
(8)<JSMITH/cobol/reallyXXVeryLongLongName.cpy
/u/JSMITH//copy/other.cob
> = truncated on right
< = truncated on left
From the COPY statement in the source; for example the COPY statement
corresponding to the third item in the cross-reference above would be:
COPY ’cobol/copyA.cpy’ Of ALTDD2
(6)
The fully qualified path of the file from which the COPY member was
copied
(7)
Truncation of a long text-name or library-name on the right is marked by a
greater-than sign (>).
(8)
Truncation of a long file name on the left is marked by a less-than sign (<).
RELATED REFERENCES
“XREF” on page 371
Example: XREF output: embedded cross-reference
The following example shows a modified cross-reference that is embedded in the
source listing. The cross-reference is produced by the XREF compiler option.
LineID PL SL
. . .
000878
000879
000880
000881
000882
000883
000884
000885
1
000886
. . .
000984
000985
000986
000987
000988
000989
000990
000991
000992
416
----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|--+----8
procedure division.
000-do-main-logic.
display "PROGRAM IGYTCARA - Beginning".
perform 050-create-vsam-master-file.
perform 100-initialize-paragraph.
read update-transaction-file into ws-transaction-record
at end
set transaction-eof to true
end-read.
100-initialize-paragraph.
move spaces to ws-transaction-record
move spaces to ws-commuter-record
move zeroes to commuter-zipcode
move zeroes to commuter-home-phone
move zeroes to commuter-work-phone
move zeroes to commuter-update-date
open input update-transaction-file
location-file
Enterprise COBOL for z/OS, V5.1 Programming Guide
Map and Cross Reference
932 (1)
984
204 340
254
IMP
IMP
IMP
IMP
IMP
IMP
204
193
340 (2)
316
327
328
329
333
000993
000994
. . .
001442
001443
001444
001445
001446
001447
001448
001449
001450
001451
001452
001453
001454
001455
001456
. . .
i-o commuter-file
output print-file
181
217
1100-print-i-f-headings.
open output print-file.
217
move
move
move
move
IFN
698
698
698
function when-compiled to when-comp.
when-comp (5:2) to compile-month.
when-comp (7:2) to compile-day.
when-comp (3:2) to compile-year.
698 (2)
640
642
644
move function current-date (5:2) to current-month.
move function current-date (7:2) to current-day.
move function current-date (3:2) to current-year.
IFN 649
IFN 651
IFN 653
write print-record from i-f-header-line-1
after new-page.
222 635
138
(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.
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 compiler listing that has a condensed verb listing,
global tables, WORKING-STORAGE information, and literals. The listing is output from
the OFFSET compiler option.
DATA VALIDATION AND UPDATE
. . .
(1)
(2)
(3)
LINE # HEXLOC VERB
000880 0026F0 DISPLAY
000934 002722 IF
001389 002736 DISPLAY
001392 002754 DISPLAY
001395 002772 DISPLAY
001435 002786 STOP
000941 0027D6 IF
001389 0027EA DISPLAY
001392 002808 DISPLAY
001395 002826 DISPLAY
001403 00283A DISPLAY
001406 002858 DISPLAY
PROGRAM
LINE #
000881
000935
001390
001393
000937
000939
000942
001390
001393
000944
001404
001407
IGYTCARA Date 03/30/2013
HEXLOC VERB
002702 PERFORM
00272C DISPLAY
002740 DISPLAY
00275E DISPLAY
00277C PERFORM
0027A2 MOVE
0027E0 DISPLAY
0027F4 DISPLAY
002812 DISPLAY
002830 DISPLAY
002844 DISPLAY
002862 CALL
LINE #
000933
000936
001391
001394
001434
000940
000943
001391
001394
000945
001405
000947
Time 10:48:16
HEXLOC VERB
002702 OPEN
002736 PERFORM
00274A DISPLAY
002768 DISPLAY
00277C DISPLAY
0027AC WRITE
0027EA PERFORM
0027FE DISPLAY
00281C DISPLAY
00283A PERFORM
00284E DISPLAY
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 are listed once
for each time they are used.
(3)
Verb used.
RELATED REFERENCES
“OFFSET” on page 349
Chapter 19. Debugging
417
Example: VBREF compiler output
The following example shows an alphabetic listing of all the verbs in a program,
and shows where each is referenced. The listing is produced by the VBREF compiler
option.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
418
(1)
2
2
1
5
20
(2)
ACCEPT .
ADD. . .
CALL . .
CLOSE. .
COMPUTE.
2
2
48
CONTINUE . . . . . . . . . . .
DELETE . . . . . . . . . . . .
DISPLAY. . . . . . . . . . . .
2
47
EVALUATE . . . . . . . . . . .
IF . . . . . . . . . . . . . .
183
MOVE . . . . . . . . . . . . .
5
62
OPEN . . . . . . . . . . . . .
PERFORM. . . . . . . . . . . .
8
1
4
46
READ . .
REWRITE.
SEARCH .
SET. . .
2
4
33
STOP . . . . . . . . . . . . .
STRING . . . . . . . . . . . .
WRITE. . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
(3)
. .
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1010 1012
1290 1306
1406
898 945 970 1526 1535
1506 1640 1644 1657 1660 1663 1664 1665 1678 1682 1686 1691 1696 1701 1709 1713
1718 1723 1728 1733
1062 1069
964 1193
878 906 917 918 919 933 940 942 947 953 960 966 972 996 997 998 999 1003 1006 1037
1090 1168 1171 1185 1195 1387 1388 1389 1390 1391 1392 1393 1401 1402 1403 1404
1405 1433 1485 1486 1492 1497 1498 1520 1521 1528 1529 1624
1161 1557
887 905 932 939 946 952 959 965 971 993 1002 1036 1051 1054 1071 1074 1077 1089
1102 1111 1115 1125 1128 1131 1134 1137 1141 1145 1148 1151 1167 1184 1194 1240
1247 1265 1272 1289 1321 1330 1339 1351 1361 1484 1496 1519 1527
907 937 957 983 984 985 986 987 988 1004 1011 1013 1025 1038 1052 1055 1060 1067
1072 1075 1078 1079 1080 1081 1082 1083 1091 1103 1112 1126 1129 1132 1135 1139
1143 1146 1149 1152 1160 1163 1169 1175 1177 1180 1181 1186 1191 1196 1201 1208
1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1229 1230
1231 1232 1233 1234 1235 1239 1241 1244 1248 1250 1251 1253 1254 1255 1257 1258
1259 1260 1264 1266 1269 1273 1275 1276 1278 1279 1291 1294 1299 1301 1303 1307
1313 1314 1315 1316 1317 1318 1319 1320 1322 1323 1327 1328 1331 1333 1334 1336
1338 1341 1342 1343 1344 1348 1349 1352 1354 1355 1357 1362 1364 1368 1374 1375
1376 1377 1378 1379 1380 1381 1414 1417 1422 1425 1445 1446 1447 1448 1450 1451
1452 1457 1464 1489 1502 1507 1508 1509 1517 1551 1561 1566 1571 1576 1581 1586
1591 1596 1601 1606 1611 1616 1621 1626 1627 1679 1683 1688 1693 1698 1703 1710
1715 1720 1725 1730 1735
931 951 989 1443 1483
879 880 885 886 888 890 892 908 909 915 916 934 935 941 943 948 949 954 955 961
962 967 968 973 974 1000 1005 1008 1023 1039 1092 1093 1116 1164 1165 1170 1172
1176 1178 1179 1182 1187 1188 1192 1197 1198 1202 1246 1256 1271 1280 1329 1340
1350 1359 1365 1369 1504 1510 1511 1532 1533
881 893 958 1014 1026 1085 1490 1514
1183
1058 1065 1413 1421
883 895 1016 1028 1041 1057 1064 1084 1087 1363 1412 1420 1493 1499 1516 1522 1548
1550 1559 1560 1564 1565 1569 1570 1574 1575 1579 1580 1584 1585 1589 1590 1594
1595 1599 1600 1604 1605 1609 1610 1614 1615 1619 1620 1639 1643
920 1434
1236 1261 1324 1345
938 1166 1292 1293 1295 1296 1297 1298 1300 1302 1305 1454 1459 1462 1465 1467 1469
1471 1512 1654 1655 1667 1668 1669 1740 1742 1744 1745 1746 1747 1748 1749 1750
(1)
Number of times the verb is used in the program
(2)
Verb
(3)
Line numbers where the verb is used
Enterprise COBOL for z/OS, V5.1 Programming Guide
Part 3. Targeting COBOL programs for certain environments
© Copyright IBM Corp. 1991, 2013
419
420
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 20. Developing COBOL programs for CICS
About this task
COBOL programs that are written for CICS can run under CICS Transaction Server.
CICS COBOL application programs that use CICS services must use the CICS
command-level interface.
When you use the CICS compiler option, the Enterprise COBOL compiler handles
both native COBOL statements and embedded CICS statements in the source
program. You can still use the separate CICS translator to translate CICS
statements to COBOL code, but use of the integrated CICS translator is
recommended instead.
After you compile and link-edit 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 scope of COBOL information. For
further information, see the related tasks.
You can determine how runtime errors are handled by setting the CBLPSHPOP
runtime option. For information about CICS HANDLE and CBLPSHPOP, see the related
tasks.
RELATED CONCEPTS
“Integrated CICS translator” on page 427
RELATED TASKS
“Coding COBOL programs to run under CICS”
“Compiling with the CICS option” on page 425
“Using the separate CICS translator” on page 428
“Handling errors by using CICS HANDLE” on page 430
Language Environment Programming Guide (Condition handling under CICS:
using the CBLPSHPOP runtime option)
CICS Application Programming Guide
RELATED REFERENCES
“CICS” on page 321
Coding COBOL programs to run under CICS
To code a program to run under CICS, code CICS commands in the PROCEDURE
DIVISION by using the EXEC CICS command format.
About this task
EXEC CICS command-name command-options
END-EXEC
CICS commands have the basic format shown above. Within EXEC commands, use
the space as a word separator; do not use a comma or a semicolon. Do not code
COBOL statements within EXEC CICS commands.
© Copyright IBM Corp. 1991, 2013
421
Restriction: You cannot run COBOL programs that have object-oriented syntax for
Java interoperability in a CICS environment. In addition, if you write programs to
run under CICS, do not use the following code:
v FILE-CONTROL entry in the ENVIRONMENT DIVISION, unless the FILE-CONTROL entry
is used for a SORT statement
v FILE SECTION of the DATA DIVISION, unless the FILE SECTION is used for a SORT
statement
v User-specified parameters to the main program
v USE declaratives (except USE FOR DEBUGGING)
v 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 CONSOLE
DISPLAY UPON SYSPUNCH
MERGE
OPEN
READ
– RERUN
– REWRITE
– START
– STOP literal
– WRITE
If you plan to use the separate CICS translator, you must put any REPLACE
statements that contain EXEC commands after the PROCEDURE DIVISION header for
the program, otherwise the commands will not be translated.
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.
Coding a COBOL program to run above the 16 MB line: Under Enterprise
COBOL, the following restrictions apply when you code a COBOL program to run
above the 16 MB line:
v If you use IMS/ESA® without DBCTL, DL/I CALL statements are supported only if
all the data passed in the call resides below the 16 MB line. Therefore, you must
specify the DATA(24) compiler option. However, if you use IMS/ESA 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 level of the IMS product.
v If the receiving program is link-edited with AMODE 31, addresses that are 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 that are passed
must be 24 bits long.
422
Enterprise COBOL for z/OS, V5.1 Programming Guide
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 not
allowed.
RELATED CONCEPTS
“Integrated CICS translator” on page 427
RELATED TASKS
“Sorting under CICS” on page 244
“Getting the system date under CICS”
“Calling to or from COBOL programs” on page 424
“Determining the success of ECI calls” on page 425
“Using the separate CICS translator” on page 428
RELATED REFERENCES
“CICS SORT application restrictions” on page 244
Getting the system date under CICS
To retrieve the system date in a CICS program, use a format-2 ACCEPT statement or
the CURRENT-DATE intrinsic function.
About this task
You can use any of these format-2 ACCEPT statements in the CICS environment to
get the system date:
v ACCEPT identifier-2 FROM DATE (two-digit year)
v ACCEPT identifier-2 FROM DATE YYYYMMDD
v ACCEPT identifier-2 FROM DAY (two-digit year)
v ACCEPT identifier-2 FROM DAY YYYYDDD
v ACCEPT identifier-2 FROM DAY-OF-WEEK (one-digit integer, where 1 represents
Monday)
You can use this format-2 ACCEPT statement in the CICS environment to get the
system time:
v ACCEPT identifier-2 FROM TIME
Alternatively, you can use the CURRENT-DATE intrinsic function, which can also
provide the time.
These methods work in both CICS and non-CICS environments.
Do not use a format-1 ACCEPT statement in a CICS program.
RELATED TASKS
“Assigning input from a screen or file (ACCEPT)” on page 35
RELATED REFERENCES
CURRENT-DATE (Enterprise COBOL Language Reference)
Chapter 20. Developing COBOL programs for CICS
423
Calling to or from COBOL programs
You can make calls to or from VS COBOL II, COBOL for MVS & VM, COBOL for
OS/390 & VM, and Enterprise COBOL programs by using the CALL statement.
About this task
If you are calling a separately compiled COBOL program that was processed with
either the separate CICS translator or the integrated CICS translator, you must pass
DFHEIBLK and DFHCOMMAREA as the first two parameters in the CALL statement.
Called programs that are processed by the separate CICS translator or the
integrated CICS translator can contain any function that is supported by CICS for
the language.
Dynamic calls:
You can use COBOL dynamic calls when running under CICS. If a COBOL
program contains EXEC CICS statements or contains EXEC SQL statements, the
NODYNAM compiler option is required. To dynamically call a program in this case,
you can use CALL identifier with the NODYNAM compiler option.
If a COBOL program contains no EXEC CICS statements and contains no EXEC SQL
statements, there is no requirement to compile with NODYNAM. To dynamically call a
program in this case, you can use either CALL literal with the DYNAM compiler option,
or CALL identifier.
You must define dynamically called programs in the CICS program processing
table (PPT) if you are not using CICS autoinstall. Under CICS, COBOL programs
do not support dynamic calls to subprograms that have the RELOAD=YES option
coded in their CICS PROGRAM definition. Dynamic calls to programs that are defined
with RELOAD=YES can cause a storage shortage. Use the RELOAD=NO option for
programs that are to be dynamically called by COBOL.
Interlanguage communication (ILC):
Support for ILC with other high-level languages is available. Where ILC is not
supported, you can use CICS LINK, XCTL, and RETURN instead.
The following table shows the calling relationship between COBOL and assembler
programs. In the table, assembler programs that conform to the interface that is
described in the Language Environment Programming Guide are called Language
Environment-conforming assembler programs. Those that do not conform to the
interface are non-Language Environment-conforming assembler programs.
Table 55. Calls between COBOL and assembler under CICS
Language
Environment-conforming
assembler program
Non-Language
Environment-conforming
assembler program
From an Enterprise COBOL
program to the assembler
program?
Yes
Yes
From the assembler program to
an Enterprise COBOL program?
Yes
No
Calls between COBOL and
assembler programs
424
Enterprise COBOL for z/OS, V5.1 Programming Guide
Nested programs:
When you compile with the integrated CICS translator, the translator generates the
DFHEIBLK and DFHCOMMAREA control blocks with the GLOBAL clause in the outermost
program. Therefore if you code nested programs, you do not have to pass these
control blocks as arguments on calls to the nested programs.
If you code nested programs and you plan to use the separate CICS translator,
pass DFHEIBLK and DFHCOMMAREA as parameters to the nested programs that contain
EXEC commands or references to the EXEC interface block (EIB). You must pass the
same parameters also to any program that forms part of the control hierarchy
between such a program and its top-level program.
RELATED CONCEPTS
“Integrated CICS translator” on page 427
RELATED TASKS
“Using the separate CICS translator” on page 428
“Choosing the DYNAM or NODYNAM compiler option” on page 443
“Handling errors when calling programs” on page 256
Language Environment Writing ILC Communication Applications (ILC under CICS)
CICS External Interfaces Guide
Language Environment Programming Guide
RELATED REFERENCES
“DYNAM” on page 332
Determining the success of ECI calls
After calls to the external CICS interface (ECI), the content of the RETURN-CODE
special register is set to an unpredictable value. Therefore, even if your COBOL
program terminates normally after successfully using the external CICS interface,
the job step could end with an undefined return code.
About this task
To ensure that a meaningful return code occurs at termination, set the RETURN-CODE
special register before you terminate your program. To make the job return code
reflect the status of the last call to CICS, set the RETURN-CODE special register based
on the response codes from the last call to the external CICS interface.
RELATED TASKS
CICS External Interfaces Guide
Compiling with the CICS option
Use the CICS compiler option to enable the integrated CICS translator and to
specify CICS suboptions.
About this task
If you specify the NOCICS option, the compiler diagnoses and discards any CICS
statements that it finds in your source program. If you have already used the
separate CICS translator, you must use NOCICS.
Chapter 20. Developing COBOL programs for CICS
425
You can specify the CICS option in any of the compiler option sources: compiler
invocation, PROCESS or CBL statements, or installation default. If the CICS option is
the COBOL installation default, you cannot specify CICS suboptions. However,
making the CICS option the installation default is not recommended, because the
changes that are made by the integrated CICS translator are not appropriate for
non-CICS applications.
All CBL or PROCESS statements must precede any comment lines, in accordance with
the rules for Enterprise COBOL.
The COBOL compiler passes to the integrated CICS translator the CICS suboption
string that you provide in the CICS compiler option. The compiler does not analyze
the suboption string.
When you use the integrated CICS translator, you must compile with the following
options:
Table 56. Compiler options required for the integrated CICS translator
Compiler option
Comment
CICS
If you specify NOLIB, DYNAM, or NORENT, the compiler forces
NODYNAM, and RENT on.
NODYNAM
Must be in effect with CICS
RENT
Must be in effect with CICS
SIZE(xxx)
xxx must be a size value that leaves enough storage in your
user region for the integrated CICS translation process.
In addition, IBM recommends that you use the compiler option WORD(CICS) to
cause the compiler to flag language elements that are not supported under CICS.
To compile your program with the integrated CICS translator, you can use the
standard JCL procedural statements that are supplied with COBOL. In addition to
specifying the above compiler options, you must change your JCL in two ways:
v Specify the STEPLIB override for the COBOL step.
v Add the data set that contains the integrated CICS translator services, unless
these services are in the linklist.
The default name of the data set for CICS Transaction Server V4R1 is
CICSTS41.CICS.SDFHLOAD, but your installation might have changed the name.
For example, you might have the following line in your JCL:
//STEPLIB
DD
DSN=CICSTS41.CICS.SDFHLOAD,DISP=SHR
The COBOL compiler listing includes the error diagnostics (such as syntax errors
in the CICS statements) that the integrated CICS translator generates. The listing
reflects the input source; it does not include the COBOL statements that the
integrated CICS translator generates.
Compiling a sequence of programs: When you use the CICS option to compile a
source file that contains a sequence of COBOL programs, the order of precedence
of the options from highest to lowest is:
v Options that are specified in the CBL or PROCESS card that initiates the unit of
compilation
v Options that are specified when the compiler is started
v CICS default options
426
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED CONCEPTS
“Integrated CICS translator”
RELATED TASKS
“Coding COBOL programs to run under CICS” on page 421
“Separating CICS suboptions”
CICS Application Programming Guide
RELATED REFERENCES
“CICS” on page 321
“Conflicting compiler options” on page 314
Separating CICS suboptions
You can partition the specification of CICS suboptions into multiple CBL statements.
CICS suboptions are cumulative. The compiler concatenates them from multiple
sources in the order that they are specified.
About this task
For example, suppose that a JCL file has the following code:
//STEP1 EXEC IGYWC, . . .
//PARM.COBOL="CICS("FLAG(I)")"
//COBOL.SYSIN DD *
CBL CICS("DEBUG")
CBL CICS("LINKAGE")
IDENTIFICATION DIVISION.
PROGRAM-ID. COBOL1.
During compilation, the compiler passes the following CICS suboption string to
the integrated CICS translator:
"FLAG(I) DEBUG LINKAGE"
The concatenated strings are delimited with single spaces and with a quotation
mark or single quotation mark around the group. When the compiler finds
multiple instances of the same CICS suboption, the last specification of the
suboption in the concatenated string takes effect. The compiler limits the length of
the concatenated CICS suboption string to 4 KB.
RELATED REFERENCES
“CICS” on page 321
Integrated CICS translator
When you compile a COBOL program using the CICS compiler option, the COBOL
compiler works with the integrated CICS translator to handle both native COBOL
and embedded CICS statements in the source program.
When the compiler encounters CICS statements, and at other significant points in
the source program, the compiler interfaces with the integrated CICS translator. All
text between EXEC CICS and END-EXEC statements is passed to the translator. The
translator takes appropriate actions and then returns to the compiler, typically
indicating which native language statements to generate.
Although you can still translate embedded CICS statements separately, it is
recommended that you use the integrated CICS translator instead. Certain
Chapter 20. Developing COBOL programs for CICS
427
restrictions that apply when you use the separate translator do not apply when
you use the integrated translator, and using the integrated translator provides
several advantages:
v You can use Debug Tool to debug the original source instead of the expanded
source that the separate CICS translator generates.
v You do not need to separately translate the EXEC CICS or EXEC DLI statements
that are in copybooks.
v There is no intermediate data set for a translated but not compiled version of the
source program.
v Only one output listing instead of two is produced.
v Using nested programs that contain EXEC CICS statements is simpler.
DFHCOMMAREA and DFHEIBLK are generated with the GLOBAL attribute in the
outermost program. You do not need to pass them as arguments on calls to
nested programs or specify them in the USING phrase of the PROCEDURE DIVISION
header of nested programs.
v You can keep nested programs that contain EXEC CICS statements in separate
files, and include those nested programs by using COPY statements.
v REPLACE statements can affect EXEC CICS statements.
v You can compile programs that contain CICS statements in a batch compilation
(compilation of a sequence of programs).
v Because the compiler generates binary fields in CICS control blocks with format
COMP-5 instead of BINARY, there is no dependency on the setting of the TRUNC
compiler option. You can use any setting of the TRUNC option in CICS programs,
subject only to the requirements of the application logic and use of user-defined
binary fields.
RELATED CONCEPTS
CICS Application Programming Guide (The integrated CICS translator)
RELATED TASKS
“Coding COBOL programs to run under CICS” on page 421
“Compiling with the CICS option” on page 425
RELATED REFERENCES
“CICS” on page 321
“TRUNC” on page 368
Using the separate CICS translator
To run a COBOL program under CICS, you can use the separate CICS translator to
convert the CICS commands to COBOL statements, and then compile and link the
program to create the executable module. However, using the CICS translator that
is integrated with Enterprise COBOL is recommended.
About this task
To translate CICS statements separately, use the COBOL3 translator option. This
option causes the following line to be inserted:
CBL RENT,NODYNAM,
You can suppress the insertion of a CBL statement by using the CICS translator
option NOCBLCARD.
428
Enterprise COBOL for z/OS, V5.1 Programming Guide
CICS provides the translator option ANSI85, which supports the following language
features (introduced by Standard COBOL 85):
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 Nested programs
v
v
v
v
Reference modification
GLOBAL variables
Interchangeability of comma, semicolon, and space
Symbolic character definition
After you use the separate CICS translator, use the following compiler options
when you compile the program:
Table 57. Compiler options required for the separate CICS translator
Required compiler option Condition
RENT
NODYNAM
The program is translated by the CICS translator.
In addition, IBM recommends that you use the compiler option WORD(CICS) to
cause the compiler to flag language elements that are not supported under CICS.
The following TRUNC compiler option recommendations are based on expected
values for binary data items:
Table 58. TRUNC compiler options recommended for the separate CICS translator
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.
For example, if you use the separate CICS translator and have a data item defined
as PIC S9(8) BINARY that might receive a value greater than eight digits, use the
TRUNC(BIN) compiler option, change the item to USAGE COMP-5, or change the
PICTURE clause.
You might also want to avoid using these options, which have no effect:
v ADV
v FASTSRT
v OUTDD
The input data set for the compiler is the data set that you received as a result of
translation, which is SYSPUNCH by default.
RELATED CONCEPTS
“Integrated CICS translator” on page 427
Chapter 20. Developing COBOL programs for CICS
429
RELATED TASKS
“Compiling with the CICS option” on page 425
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
that are not supported under CICS are flagged 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:
v CLOSE
v
v
v
v
v
v
v
v
DELETE
FD
FILE
FILE-CONTROL
INPUT-OUTPUT
I-O-CONTROL
MERGE
OPEN
v READ
v
v
v
v
v
RERUN
REWRITE
SD
SORT
START
v 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 to remove the words in bold above from the list of words marked as
restricted.
RELATED TASKS
“Compiling with the CICS option” on page 425
“Sorting under CICS” on page 244
RELATED REFERENCES
“WORD” on page 371
Handling errors by using CICS HANDLE
The setting of the CBLPSHPOP runtime option affects the state of the HANDLE
specifications when a program calls COBOL subprograms using a CALL statement.
About this task
When CBLPSHPOP is ON and a COBOL subprogram (not a nested program) is called
with a CALL statement, the following actions occur:
430
Enterprise COBOL for z/OS, V5.1 Programming Guide
Procedure
1. As part of program initialization, the run time suspends the HANDLE
specifications of the calling program (using EXEC CICS PUSH HANDLE).
2. The default actions for HANDLE apply until the called program issues its own
HANDLE commands.
3. As part of program termination, the run time reinstates the HANDLE
specifications of the calling program (using EXEC CICS POP HANDLE).
Results
If you use the CICS HANDLE CONDITION or CICS 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,
or abends that were caused by another program invoked with 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 occur.
Performance considerations: When CBLPSHPOP is OFF, the run time does not
perform CICS PUSH or POP on a CALL to any COBOL subprogram. If the
subprograms do not use any of the EXEC CICS condition-handling commands, you
can run with CBLPSHPOP(OFF), thus eliminating the overhead of the PUSH HANDLE
and POP HANDLE commands. As a result, performance can be improved compared to
running with CBLPSHPOP(ON).
If you are migrating an application from the VS COBOL II run time to the
Language Environment run time, see the related reference for information about
the CBLPSHPOP option for additional considerations.
“Example: handling errors by using CICS HANDLE”
RELATED TASKS
“Running efficiently with CICS, IMS, or VSAM” on page 665
RELATED REFERENCES
Enterprise COBOL Migration Guide (CICS HANDLE
commands and the CBLPSHPOP runtime option)
Enterprise COBOL Version 4 Performance Tuning
Example: handling errors by using CICS HANDLE
The following example shows 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. A condition is handled in one of three scenarios.
(1)
CBLPSHPOP(ON): If the CICS READ command in program B causes a
condition, the condition is not handled by program A (the HANDLE
specifications are suspended because the run time performs a CICS PUSH
HANDLE). The condition turns into a transaction abend.
(2)
CBLPSHPOP(OFF): If the CICS READ command in program B causes a
Chapter 20. Developing COBOL programs for CICS
431
condition, the condition is not handled by program A (the run time
diagnoses the attempt to perform cross-program branching by using a CICS
HANDLE command with the LABEL option). The condition turns 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 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’.
. . .
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.
432
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 21. Programming for a DB2 environment
In general, the coding for a COBOL program will be the same if you want the
program to access a DB2 database. However, to retrieve, update, insert, and delete
DB2 data and use other DB2 services, you must use SQL statements.
About this task
To communicate with DB2, do these steps:
v Code any SQL statements that you need, delimiting them with EXEC SQL and
END-EXEC statements.
v Either use the DB2 stand-alone precompiler, or compile with the SQL compiler
option and use the DB2 coprocessor.
RELATED CONCEPTS
“DB2 coprocessor”
“COBOL and DB2 CCSID determination” on page 439
RELATED TASKS
“Coding SQL statements” on page 434
“Compiling with the SQL option” on page 438
“Choosing the DYNAM or NODYNAM compiler option” on page 443
RELATED REFERENCES
“Differences in how the DB2 precompiler and coprocessor behave” on page 441
DB2 coprocessor
When you use the DB2 coprocessor (called SQL statement coprocessor by DB2), the
compiler handles your source program that contains embedded SQL statements
without your having to use a separate precompile step.
To use the DB2 coprocessor, specify the SQL compiler option.
When the compiler encounters SQL statements in the source program, it interfaces
with the DB2 coprocessor. All text between EXEC SQL and END-EXEC statements is
passed to the coprocessor. The coprocessor takes appropriate actions for the SQL
statements and indicates to the compiler which native COBOL statements to
generate for them.
Although the use of a separate precompile step continues to be supported, it is
recommended that you use the coprocessor instead:
v Interactive debugging with Debug Tool is enhanced when you use the
coprocessor because you see the SQL statements (not the generated COBOL
source) in the listing.
v The COBOL compiler listing includes the error diagnostics (such as syntax errors
in the SQL statements) that the DB2 coprocessor generates.
v 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. With the
coprocessor:
© Copyright IBM Corp. 1991, 2013
433
– You can use SQL statements in any nested program. (With the precompiler,
SQL statements are restricted to the outermost program.)
– You can use SQL statements in copybooks.
– REPLACE statements work in SQL statements.
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 in the DBRMLIB 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.
RELATED CONCEPTS
“COBOL and DB2 CCSID determination” on page 439
RELATED TASKS
“Compiling with the SQL option” on page 438
RELATED REFERENCES
“Differences in how the DB2 precompiler and coprocessor behave” on page 441
“SQL” on page 360
Coding SQL statements
Delimit SQL statements with EXEC SQL and END-EXEC. The EXEC SQL and END-EXEC
delimiters must each be complete on one line. You cannot continue them across
multiple lines. Do not code COBOL statements within EXEC SQL statements.
About this task
You also need to do these special steps:
v Code an EXEC SQL INCLUDE statement to include an SQL communication area
(SQLCA) in the WORKING-STORAGE SECTION or LOCAL-STORAGE SECTION of the
outermost program. LOCAL-STORAGE is recommended for recursive programs and
programs that use the THREAD compiler option.
v Declare all host variables that you use in SQL statements in the WORKING-STORAGE
SECTION, LOCAL-STORAGE SECTION, or LINKAGE SECTION. However, you do not need
to identify them with EXEC SQL BEGIN DECLARE SECTION and EXEC SQL END
DECLARE SECTION.
Restriction: You cannot use SQL statements in object-oriented classes or methods.
RELATED TASKS
“Using SQL INCLUDE with the DB2 coprocessor” on page 435
“Using character data in SQL statements” on page 435
“Using national decimal data in SQL statements” on page 436
“Using national group items in SQL statements” on page 437
“Using binary items in SQL statements” on page 437
“Determining the success of SQL statements” on page 437
DB2 Application Programming and SQL Guide (Coding SQL statements in a
COBOL application)
RELATED REFERENCES
“Code-page determination for string host variables in SQL statements” on page 440
DB2 SQL Reference
434
Enterprise COBOL for z/OS, V5.1 Programming Guide
Using SQL INCLUDE with the DB2 coprocessor
An SQL INCLUDE statement is treated identically to a native COBOL COPY statement
when you use the SQL compiler option.
About this task
The following two lines are therefore treated the same way. (The period that ends
the EXEC SQL INCLUDE statement is required.)
EXEC SQL INCLUDE name END-EXEC.
COPY "name".
The processing of the name in an SQL INCLUDE statement follows the same rules as
those of the literal in a COPY literal-1 statement that does not have a REPLACING
phrase.
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.
RELATED REFERENCES
Chapter 18, “Compiler-directing statements,” on page 375
“Differences in how the DB2 precompiler and coprocessor behave” on page 441
COPY statement (Enterprise COBOL Language Reference)
Using character data in SQL statements
You can code any of the following USAGE clauses to describe host variables for
character data that you use in EXEC SQL statements: USAGE DISPLAY for single-byte
or UTF-8 data, USAGE DISPLAY-1 for DBCS data, or USAGE NATIONAL for UTF-16
data.
About this task
When you use the stand-alone DB2 precompiler, you must specify the code page
(CCSID) in EXEC SQL DECLARE statements for host variables that are declared with
USAGE NATIONAL. You must specify the code page for host variables that are
declared with USAGE DISPLAY or DISPLAY-1 only if the CCSID that is in effect for
the COBOL CODEPAGE compiler option does not match the CCSIDs that are used by
DB2 for character and graphic data.
Consider the following code. The two highlighted statements are unnecessary
when you use the integrated DB2 coprocessor (with the SQLCCSID compiler option,
as detailed in the related concept below), because the code-page information is
handled implicitly.
CBL CODEPAGE(1140) NSYMBOL(NATIONAL)
. . .
WORKING-STORAGE SECTION.
EXEC SQL INCLUDE SQLCA END-EXEC.
01 INT1 PIC S9(4) USAGE COMP.
01 C1140.
49 C1140-LEN PIC S9(4) USAGE COMP.
49 C1140-TEXT PIC X(50).
EXEC SQL DECLARE :C1140 VARIABLE CCSID 1140 END-EXEC.
01 G1200.
49 G1200-LEN PIC S9(4) USAGE COMP.
49 G1200-TEXT PIC N(50) USAGE NATIONAL.
Chapter 21. Programming for a DB2 environment
435
EXEC SQL DECLARE :G1200 VARIABLE CCSID 1200 END-EXEC.
. . .
EXEC SQL FETCH C1 INTO :INT1, :C1140, :G1200 END-EXEC.
If you specify EXEC SQL DECLARE variable-name VARIABLE CCSID nnnn END-EXEC, that
specification overrides the implied CCSID. For example, the following code would
cause DB2 to treat C1208-TEXT as encoded in UTF-8 (CCSID 1208) rather than as
encoded in the CCSID in effect for the COBOL CODEPAGE compiler option:
01 C1208.
49 C1208-LEN PIC S9(4) USAGE COMP.
49 C1208-TEXT PIC X(50).
EXEC SQL DECLARE :C1208 VARIABLE CCSID 1208 END-EXEC.
The NSYMBOL compiler option has no effect on a character literal inside an EXEC SQL
statement. Character literals in an EXEC SQL statement follow the SQL rules for
character constants.
RELATED CONCEPTS
“COBOL and DB2 CCSID determination” on page 439
RELATED TASKS
DB2 Application Programming and SQL Guide (Coding SQL statements in a
COBOL application)
RELATED REFERENCES
“Differences in how the DB2 precompiler and coprocessor behave” on page 441
“CODEPAGE” on page 322
DB2 SQL Reference
Using national decimal data in SQL statements
You can use national decimal host variables in EXEC SQL statements when you use
either the integrated DB2 coprocessor or the DB2 precompiler. You do not need to
specify the CCSID in EXEC SQL DECLARE statements in either case. CCSID 1200 is
used automatically.
About this task
Any national decimal host variable that you specify in an EXEC SQL statement must
have the following characteristics:
v It must be signed.
v It must be specified with the SIGN LEADING SEPARATE clause.
v USAGE NATIONAL must be in effect implicitly or explicitly.
RELATED CONCEPTS
“Formats for numeric data” on page 49
RELATED TASKS
“Defining national numeric data items” on page 137
RELATED REFERENCES
“Differences in how the DB2 precompiler and coprocessor behave” on page 441
436
Enterprise COBOL for z/OS, V5.1 Programming Guide
Using national group items in SQL statements
You can use a national group item as a host variable in an EXEC SQL statement. The
national group item is treated with group semantics (that is, as shorthand for the
set of host variables that are subordinate to the group item) rather than as an
elementary item.
About this task
Because all subordinate items in a national group must have USAGE NATIONAL, a
national group item cannot describe a variable-length string.
RELATED TASKS
“Using national groups” on page 139
Using binary items in SQL statements
For binary data items that you specify in an EXEC SQL statement, you can declare
the data items as either USAGE COMP-5 or as USAGE BINARY, COMP, or COMP-4.
About this task
If you declare the binary data items as USAGE BINARY, COMP, or COMP-4, use the
TRUNC(BIN) option. (This technique might have a larger effect on performance than
using USAGE COMP-5 on individual data items.) If instead TRUNC(OPT) or TRUNC(STD)
is in effect, the compiler accepts the items 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.
RELATED CONCEPTS
“Formats for numeric data” on page 49
RELATED REFERENCES
“TRUNC” on page 368
Determining the success of SQL statements
When DB2 finishes executing an SQL statement, DB2 sends a return code in the
SQLCA structure, with one exception, to indicate whether the operation succeeded
or failed. In your program, test the return code and take any necessary action.
About this task
The exception 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.
After execution of SQL statements, the content of the RETURN-CODE special register
might not be valid. Therefore, even if your COBOL program terminates normally
after successfully using SQL statements, the job step could end with an undefined
return code. To ensure that a meaningful return code is given at termination, set
the RETURN-CODE special register before terminating your program.
RELATED TASKS
DB2 Application Programming and SQL Guide (Coding SQL statements in a
COBOL application)
Chapter 21. Programming for a DB2 environment
437
Compiling with the SQL option
You use the SQL compiler option to enable the DB2 coprocessor and to specify DB2
suboptions.
About this task
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 in the SQL compiler option is made
available to the DB2 coprocessor. Only the DB2 coprocessor views the contents of
the string.
To use the DB2 coprocessor, you must compile with the options that are shown in
the table below, and DB2 must be available on the machine on which you compile.
Table 59. Compiler options required with the DB2 coprocessor
Compiler option
Comment
SIZE(xxx)
xxx is a size value that leaves enough storage in the user region for
the DB2 coprocessor services.
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 DSN910.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=DSN910.SDSNLOAD,DISP=SHR
Compiling a batch of programs: If you use the SQL option when compiling a
source file that contains a sequence of COBOL programs (a batch compile
sequence), SQL must be in effect for only the first program of the sequence.
Although you can specify SQL upon compiler invocation, the option will be in
effect for only the first program. If you specify SQL in a CBL or PROCESS statement
for a program other than the first program in the batch, you will receive a
compiler diagnostic message.
RELATED CONCEPTS
“DB2 coprocessor” on page 433
“COBOL and DB2 CCSID determination” on page 439
RELATED TASKS
“Separating DB2 suboptions” on page 439
“Choosing the DYNAM or NODYNAM compiler option” on page 443
438
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED REFERENCES
“DYNAM” on page 332
“SQL” on page 360
DB2 Command Reference
Separating DB2 suboptions
Because of the concatenation of multiple SQL option specifications, you can
separate DB2 suboptions (which might not fit in one CBL statement) into multiple
CBL statements.
About this task
The options 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("string1")’
//COBOL.SYSIN DD *
CBL SQL("string2")
CBL SQL("string3")
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
During compilation, the compiler passes the following suboption string to the DB2
coprocessor:
"string1 string2 string3"
The concatenated strings are delimited with single spaces. If the compiler finds
multiple instances of the same SQL suboption, the last specification of that
suboption in the concatenated string takes effect. The compiler limits the length of
the concatenated DB2 suboption string to 4 KB.
COBOL and DB2 CCSID determination
All DB2 string data other than BLOB, BINARY, and VARBINARY data has an
associated encoding scheme and a coded character set ID (CCSID). This is true for
fixed-length and variable-length character strings, fixed-length and variable-length
graphic character strings, CLOB host variables, and DBCLOB host variables.
When you use the integrated DB2 coprocessor, the determination of the code page
CCSID that will be associated with the string host variables used in SQL statement
processing depends on the setting of the COBOL SQLCCSID option, on the
programming techniques used, and on various DB2 configuration options.
When you use the SQL and SQLCCSID COBOL compiler options, the CCSID value
nnnnn that is specified in the CODEPAGE compiler option, or that is determined from
the COBOL data type of a host variable, is communicated automatically from
COBOL to DB2. DB2 associates the COBOL CCSID with host variables, overriding
the CCSID that would otherwise be implied by DB2 external mechanisms and
defaults. This associated CCSID is used for the processing of the SQL statements
that reference host variables.
When you use the SQL and NOSQLCCSID compiler options, the CCSID value nnnnn
that is specified in the CODEPAGE compiler option is used only for processing
COBOL statements within the COBOL program; that CCSID is not used for the
processing of SQL statements. Instead, DB2 assumes in processing SQL statements
Chapter 21. Programming for a DB2 environment
439
that host variable data values are encoded according to the CCSID or CCSIDs that
are specified through DB2 external mechanisms and defaults.
RELATED CONCEPTS
“DB2 coprocessor” on page 433
RELATED TASKS
“Programming with the SQLCCSID or NOSQLCCSID option”
RELATED REFERENCES
“Code-page determination for string host variables in SQL statements”
“CODEPAGE” on page 322
“SQL” on page 360
“SQLCCSID” on page 361
Code-page determination for string host variables in SQL
statements
When you use the integrated DB2 coprocessor (SQL compiler option), the code page
for processing string host variables in SQL statements is determined as shown
below, in descending order of precedence.
v A host variable that has USAGE NATIONAL is always processed by DB2 using
CCSID 1200 (Unicode UTF-16). For example:
01 hostvariable pic n(10) usage national.
v An alphanumeric host variable that has an explicit FOR BIT DATA declaration is
set by DB2 to CCSID 66535, which indicates that the variable does not represent
encoded characters. For example:
EXEC SQL DECLARE hostvariable VARIABLE FOR BIT DATA END-EXEC
v A BLOB, BINARY, or VARBINARY host variable has no CCSID association.
These string types do not represent encoded characters.
v A host variable for which you specify an explicit CCSID override in the SQLDA
is processed with that CCSID.
v A host variable that you specify in a declaration with an explicit CCSID is
processed with that CCSID. For example:
EXEC SQL DECLARE hostvariable VARIABLE CCSID nnnnn END-EXEC
v An alphanumeric host variable, if the SQLCCSID compiler option is in effect, is
processed with the CCSID nnnnn from the CODEPAGE compiler option.
v A DBCS host variable, if the SQLCCSID option is in effect, is processed with the
mapped value mmmmm, which is the pure DBCS CCSID component of the
mixed (MBCS) CCSID nnnnn from the CODEPAGE(nnnnn) compiler option.
v An alphanumeric or DBCS host variable, if the NOSQLCCSID option is in effect, is
processed with the CCSID from the DB2 ENCODING bind option, if specified,
or from the APPLICATION ENCODING set in DSNHDECP through the DB2
installation panel DSNTIPF.
RELATED REFERENCES
“CODEPAGE” on page 322
“SQLCCSID” on page 361
Programming with the SQLCCSID or NOSQLCCSID option
In general, the SQLCCSID option is recommended for new applications that use the
integrated DB2 coprocessor, and as a long-term direction for existing applications.
440
Enterprise COBOL for z/OS, V5.1 Programming Guide
The NOSQLCCSID option is recommended as a mechanism for migrating existing
precompiler-based applications to use the integrated DB2 coprocessor.
About this task
The SQLCCSID option is recommended for COBOL-DB2 applications that have any
of these characteristics:
v Use COBOL Unicode support
v Use other COBOL syntax that is indirectly sensitive to CCSID encoding, such as
XML support or object-oriented syntax for Java interoperability
v Process character data that is encoded in a CCSID that is different from the
default CCSID assumed by DB2
The NOSQLCCSID option is recommended for applications that require the highest
compatibility with the behavior of the DB2 precompiler.
For applications that use COBOL alphanumeric data items as host variables
interacting with DB2 string data that is defined with the FOR BIT DATA subtype,
you must either:
v Use the NOSQLCCSID compiler option
v Specify explicit FOR BIT DATA declarations for those host variables, for example:
EXEC SQL DECLARE hostvariable VARIABLE FOR BIT DATA END-EXEC
Usage notes
v If you use the DB2 DCLGEN command to generate COBOL declarations for a table,
you can optionally create FOR BIT DATA declarations automatically. To do so,
specify the DCLBIT(YES) option of the DCLGEN command.
v Performance consideration: Using the SQLCCSID compiler option could result in
some performance overhead in SQL processing, because with SQLCCSID in effect
the default DB2 CCSID association mechanism is overridden with a mechanism
that works on a per-host-variable basis.
RELATED CONCEPTS
“DB2 coprocessor” on page 433
RELATED REFERENCES
“SQLCCSID” on page 361
Differences in how the DB2 precompiler and coprocessor behave
The sections that follow enumerate the differences in behavior between the
stand-alone COBOL DB2 precompiler and the integrated COBOL DB2 coprocessor.
Period at the end of EXEC SQL INCLUDE statements
Precompiler: The DB2 precompiler does not require that a period end each EXEC
SQL INCLUDE statement. If a period is specified, the precompiler processes it as part
of the statement. If a period is not specified, the precompiler accepts the statement
as if a period had been specified.
Coprocessor: The DB2 coprocessor treats each EXEC SQL INCLUDE statement like a
COPY statement, and requires that a period end the statement. For example:
Chapter 21. Programming for a DB2 environment
441
IF A = B THEN
EXEC SQL INCLUDE some_code_here END-EXEC.
ELSE
. . .
END-IF
Note that the period does not terminate the IF statement.
EXEC SQL INCLUDE and nested COPY REPLACING
Precompiler: With the DB2 precompiler, an EXEC SQL INCLUDE statement can
reference a copybook that contains a COPY statement that uses the REPLACING
phrase.
Coprocessor: With the DB2 coprocessor, an EXEC SQL INCLUDE statement cannot
reference a copybook that contains a COPY statement that uses the REPLACING
phrase. The coprocessor processes each EXEC SQL INCLUDE statement identically to a
COPY statement, and nested COPY statements cannot have the REPLACING phrase.
EXEC SQL and REPLACE or COPY REPLACING
Precompiler: With the DB2 precompiler, COBOL REPLACE statements and the
REPLACING phrase of the COPY statement act on the expanded source created from
the EXEC SQL statement. COBOL rules for REPLACE and REPLACING are used.
Coprocessor: With the DB2 coprocessor, REPLACE and COPY . . . REPLACING
statements act on the original source program, including EXEC SQL statements.
Different behavior can result, as in the following example:
REPLACE == ABC == By == XYZ ==.
01 G.
02 ABC PIC X(10).
. . .
EXEC SQL SELECT * INTO :G.ABC FROM TABLE1 END-EXEC
With the precompiler, the reference to G.ABC will appear as ABC of G in the
expanded source and will be replaced with XYZ of G. With the coprocessor,
replacement will not occur, because ABC is not delimited by separators in the
original source string G.ABC.
Source code after an END-EXEC statement
Precompiler: The DB2 precompiler ignores any code that follows END-EXEC
statements on the same line.
Coprocessor: The DB2 coprocessor processes code that follows END-EXEC statements
on the same line.
Multiple definitions of host variables
Precompiler: The DB2 precompiler does not require that host variable references be
unique. The first definition that maps to a valid DB2 data type is used.
Coprocessor: The DB2 coprocessor requires that each host variable reference be
unique. The coprocessor diagnoses nonunique references to host variables. You
must fully qualify host variable references to make them unique.
442
Enterprise COBOL for z/OS, V5.1 Programming Guide
EXEC SQL statement continuation lines
Precompiler: The DB2 precompiler requires that EXEC SQL statements start in
columns 12 through 72. Continuation lines of the statements can start anywhere in
columns 8 through 72.
Coprocessor: The DB2 coprocessor requires that all lines of an EXEC SQL statement,
including continuation lines, be coded in columns 12 through 72.
Bit-data host variables
Precompiler: With the DB2 precompiler, a COBOL alphanumeric data item can be
used as a host variable to hold DB2 character data that has subtype FOR BIT DATA.
An explicit EXEC SQL DECLARE VARIABLE statement that declares that host variable
as FOR BIT DATA is not required.
Coprocessor: With the DB2 coprocessor, a COBOL alphanumeric data item can be
used as a host variable to hold DB2 character data that has subtype FOR BIT DATA
if an explicit EXEC SQL DECLARE VARIABLE statement for that host variable is
specified in the COBOL program. For example:
EXEC SQL DECLARE :HV1 VARIABLE FOR BIT DATA END-EXEC.
As an alternative to adding EXEC SQL DECLARE . . . FOR BIT DATA statements, you
can use the NOSQLCCSID compiler option. For details, see the related reference about
code-page determination below.
SQL-INIT-FLAG
Precompiler: With the DB2 precompiler, if you pass host variables that might be
located at different addresses when the program is called more than once, the
called program must reset SQL-INIT-FLAG. Resetting this flag indicates to DB2 that
storage must be initialized when the next SQL statement runs. To reset the flag,
insert the statement MOVE ZERO TO SQL-INIT-FLAG in the PROCEDURE DIVISION of the
called program ahead of any executable SQL statements that use those host
variables.
Coprocessor: With the DB2 coprocessor, the called program does not need to reset
SQL-INIT-FLAG. An SQL-INIT-FLAG is automatically defined in the program to aid
program portability. However, statements that modify SQL-INIT-FLAG, such as MOVE
ZERO TO SQL-INIT-FLAG, have no effect on the SQL processing in the program.
RELATED CONCEPTS
“DB2 coprocessor” on page 433
RELATED REFERENCES
“Code-page determination for string host variables in SQL statements” on page 440
“SQLCCSID” on page 361
Choosing the DYNAM or NODYNAM compiler option
For COBOL programs that have EXEC SQL statements, your choice of the compiler
option DYNAM or NODYNAM depends on the operating environment.
About this task
When you run under:
v TSO or IMS: You can use either the DYNAM or NODYNAM compiler option.
Chapter 21. Programming for a DB2 environment
443
Note that IMS and DB2 share a common alias name, DSNHLI, for the language
interface module. You must concatenate your libraries as follows:
– If you use IMS with the DYNAM option, concatenate the IMS library first.
– If you run your application only under DB2, concatenate the DB2 library first.
v CICS or the DB2 call attach facility (CAF): You must use the NODYNAM compiler
option.
Because stored procedures use CAF, you must also compile COBOL stored
procedures with the NODYNAM option.
RELATED TASKS
“Compiling with the SQL option” on page 438
DB2 Application Programming and SQL Guide (Programming for the call
attachment facility)
RELATED REFERENCES
“DYNAM” on page 332
444
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 22. Developing COBOL programs for 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.
About this task
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 Enterprise COBOL, you can invoke IMS facilities using the following
interfaces:
v CBLTDLI call
v Language Environment callable service CEETDLI
|
|
|
|
CEETDLI behaves essentially the same way as CBLTDLI, except that CEETDLI
enables LE condition handling to be used. There are some instances when you
cannot use Language Environment condition handling when using CBLTDLI under
IMS.
You can also run object-oriented COBOL programs in a Java dependent region. You
can mix the object-oriented COBOL and Java languages in a single application.
RELATED TASKS
“Compiling and linking COBOL programs for running under IMS”
“Using object-oriented COBOL and Java under IMS” on page 446
“Calling a COBOL method from a Java application under IMS” on page 446
“Building a mixed COBOL-Java application that starts with COBOL” on page 447
“Writing mixed-language IMS applications” on page 448
Compiling and linking COBOL programs for running under IMS
For best performance in the IMS environment, use the RENT compiler option. RENT
causes COBOL to generate reentrant code. You can then run your application
programs in either preloaded mode (the programs are always resident in storage) or
nonpreload mode without having to recompile using different options.
About this task
Preloading can boost performance because subsequent requests for a program can
be handled faster when the program is already in storage (rather than being
fetched from a library each time it is needed).
For IMS programs, using the RENT compiler option is recommended. You must use
the RENT compiler option for a program that is to be run preloaded or both
preloaded and nonpreloaded. When you preload a load module that contains
COBOL programs, all of the COBOL programs in that load module must be
compiled using the RENT option.
You can place programs compiled with the RENT option in the z/OS link pack area.
There they can be shared among the IMS dependent regions.
© Copyright IBM Corp. 1991, 2013
445
To run above the 16 MB line, an application program must be compiled with RENT.
The data for IMS application programs can reside above the 16 MB line, and you
can use DATA(31) RENT for programs that use IMS services.
|
For proper execution of COBOL programs under IMS, observe the following
guidelines for the link-edit attributes:
v To link load modules that contain only COBOL programs compiled with the
RENT compiler option, link as RENT.
v To link load modules that contain a mixture of COBOL RENT programs and other
programs, use the link-edit attributes recommended for the other programs.
RELATED CONCEPTS
“Storage and its addressability” on page 40
RELATED TASKS
“Choosing the DYNAM or NODYNAM compiler option” on page 443
Language Environment Programming Guide (Condition handling under IMS)
RELATED REFERENCES
“DATA” on page 326
“RENT” on page 355
Enterprise COBOL Migration Guide (IMS considerations)
Using object-oriented COBOL and Java under IMS
You can mix object-oriented COBOL and Java in an application that runs in a Java
dependent region.
About this task
For example, you can:
v Call a COBOL method from a Java application. You can build the messaging
portion of your application in Java and call COBOL methods to access IMS
databases.
v Build a mixed COBOL and Java application that starts with the main method of
a COBOL class and that invokes Java routines.
You must run these applications in either a Java message processing (JMP)
dependent region or a Java batch processing (JBP) dependent region. A program
that reads from the message queue (regardless of the language) must run in a JMP
dependent region.
RELATED TASKS
“Defining a factory section” on page 608
Chapter 30, “Writing object-oriented programs,” on page 575
Chapter 31, “Communicating with Java methods,” on page 621
Chapter 16, “Compiling, linking, and running OO applications,” on page 299
IMS Application Programming Guide
Calling a COBOL method from a Java application under IMS
You can use the object-oriented language support in Enterprise COBOL to write
COBOL methods that a Java program can call under IMS.
446
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
When you define a COBOL class and compile it using Enterprise COBOL, the
compiler generates a Java class definition with native methods and the object code
that implements those native methods. You can then create an instance and invoke
the methods of this class from a Java program that runs in a Java dependent
region, just as you would use any other class.
For example, you can define a COBOL class that uses the appropriate DL/I calls to
access an IMS database. To make the implementation of this class available to a
Java program, do the following steps:
Procedure
1. Compile the COBOL class using Enterprise COBOL. The compiler generates a
Java source file (.java) that contains the class definition, and an object module
(.o) that contains the implementation of the native methods.
2. Compile the generated Java source file using the Java compiler. The Java
compiler creates a class file (.class).
3. Link the object code into a dynamic link library (DLL) in the z/OS UNIX file
system (.so). The directory that contains the COBOL DLLs must be listed in the
LIBPATH, as specified in the IMS.PROCLIB member that is indicated by the
ENVIRON= parameter of the IMS region procedure.
4. Update the sharable application class path in the master JVM options member
(ibm.jvm.sharable.application.class.path in the IMS.PROCLIB member that is
specified by the JVMOPMAS= parameter of the IMS region procedure) to
enable the JVM to access the Java class file.
Results
A Java program cannot call procedural COBOL programs directly. To reuse existing
COBOL IMS code, use one of the following techniques:
v Restructure the COBOL code as a method in a COBOL class.
v Write a COBOL class definition and method that serves as a wrapper for the
existing procedural code. The wrapper code can use COBOL CALL statements to
access procedural COBOL programs.
RELATED TASKS
Chapter 16, “Compiling, linking, and running OO applications,” on page 299
“Structuring OO applications” on page 618
“Wrapping procedure-oriented COBOL programs” on page 617
IMS Application Programming Guide
Building a mixed COBOL-Java application that starts with
COBOL
An application that runs in a Java dependent region must start with the main
method of a class.
About this task
A COBOL class definition that has a main factory method meets this requirement;
therefore, you can use a main factory method as the first routine of a mixed
COBOL and Java application under IMS.
Chapter 22. Developing COBOL programs for IMS
447
Enterprise COBOL generates a Java class with a main method, which the Java
dependent region can find, instantiate, and invoke. Although you can code the
entire application in COBOL, you would probably build this type of application to
call a Java routine. When the COBOL run time runs within the JVM of a Java
dependent region, it automatically finds and uses this JVM to invoke methods on
Java classes.
The COBOL application should use DL/I calls for processing messages (GU and GN)
and synchronizing transactions (CHKP).
RELATED TASKS
“Structuring OO applications” on page 618
IMS Application Programming Guide
IBM SDK for Java - Tools Documentation
Writing mixed-language IMS applications
When you write mixed-language IMS applications, you need to be aware of the
effects of the STOP RUN statement. You also need to understand how to process
messages and synchronize transactions, access databases, and use the application
interface block (AIB).
About this task
RELATED TASKS
“Using the STOP RUN statement”
“Processing messages and synchronizing transactions”
“Accessing databases” on page 449
“Using the application interface block” on page 449
Using the STOP RUN statement
If you use the STOP RUN statement in the COBOL portion of your application, the
statement terminates all COBOL and Java routines (including the JVM).
About this task
Control is returned immediately to IMS. The program and the transaction are left
in a stopped state.
Processing messages and synchronizing transactions
IMS message-processing applications must do all message processing and
transaction synchronization either in COBOL or Java, rather than distributing this
logic between application components written in both languages.
About this task
COBOL components use CALL statements to DL/I services to process messages (GU
and GN) and synchronize transactions (CHKP). Java components use Java classes for
IMS to do these functions. You can use object instances of classes derived from
IMSFieldMessage to communicate entire IMS messages between the COBOL and
Java components of the application.
RELATED TASKS
IMS Application Programming Guide
RELATED REFERENCES
IMS Application Programming API Reference
448
Enterprise COBOL for z/OS, V5.1 Programming Guide
Accessing databases
You can use either Java, COBOL, or a mixture of the two languages to access IMS
databases.
About this task
Limitation: EXEC SQL statements for DB2 database access are not supported in
COBOL routines that run in a Java dependent region.
Recommendation: Do not access the same database program communication block
(PCB) from both Java and COBOL. The Java and COBOL parts of the application
share the same database position. Changes in database position from calls in one
part of the application affect the database position in another part of the
application. (This problem occurs whether the affected parts of an application are
written in the same language or in different languages.)
Suppose that a Java component of a mixed application builds an SQL SELECT clause
and uses Java Database Connectivity (JDBC) to query and retrieve results from an
IMS database. The Java class libraries for IMS construct the appropriate request to
IMS to establish the correct position in the database. If you then invoke a COBOL
method that builds a segment search argument (SSA) and issues a GU (Get Unique)
request to IMS against the same database PCB, the request probably altered the
position in the database for that PCB. If so, subsequent JDBC requests to retrieve
more records by using the initial SQL SELECT clause are incorrect because the
database position changed. If you must access the same PCB from multiple
languages, reestablish the database position after an interlanguage call before you
access more records in the database.
RELATED TASKS
IMS Application Programming Guide
Using the application interface block
COBOL applications that run in a Java dependent region normally must use the
AIB interface because the Java dependent region does not provide PCB addresses
to its application.
About this task
To use the AIB interface, specify the PCB requested for the call by placing the PCB
name (which must be defined as part of the PSBGEN) in the resource name field of
the AIB. (The AIB requires that all PCBs in a program specification block (PSB)
definition have a name.) You do not specify the PCB address directly, and your
application does not need to know the relative PCB position in the PCB list. Upon
the completion of the call, the AIB returns the PCB address that corresponds to the
PCB name that the application passed.
Alternatively, you can obtain PCB addresses by making an IMS INQY call using
subfunction FIND, and the PCB name as the resource name. The call returns the
address of the PCB, which you can then pass to a COBOL program. (This approach
still requires that the PCB name be defined as part of the PSBGEN, but the
application does not have to use the AIB interface.)
“Example: using the application interface block” on page 450
RELATED TASKS
IMS Application Programming Guide
Chapter 22. Developing COBOL programs for IMS
449
Example: using the application interface block:
The following example shows how you can use the AIB interface in a COBOL
application.
Local-storage section.
copy AIB.
. . .
Linkage section.
01 IOPCB.
05 logtterm
pic x(08).
05
pic x(02).
05 tpstat
pic x(02).
05 iodate
pic s9(7)
comp-3.
05 iotime
pic s9(7)
comp-3.
05
pic x(02).
05 seqnum
pic x(02).
05 mod
pic x(08).
Procedure division.
Move spaces to input-area
Move spaces to AIB
Move "DFSAIB" to AIBRID
Move length of AIB to AIBRLEN
Move "IOPCB" to AIBRSNM1
Move length of input-area to AIBOALEN
Call "CEETDLI" using GU, AIB, input-area
Set address of IOPCB to AIBRESA1
If tpstat = spaces
* . . process input message
450
Enterprise COBOL for z/OS, V5.1 Programming Guide
Chapter 23. Running COBOL programs under z/OS UNIX
To run COBOL programs in the z/OS UNIX environment, compile them using
Enterprise COBOL or COBOL for OS/390 & VM. The programs must be reentrant,
so use the compiler and linker option RENT.
About this task
If you are going to run the programs from the z/OS UNIX file system, use the
linker option AMODE 31. Any AMODE 24 program that you call from within a z/OS
UNIX application must reside in an MVS PDS or PDSE.
Restrictions: The following restrictions apply to running under z/OS UNIX:
v SORT and MERGE statements are not supported.
v You cannot use the old COBOL interfaces for preinitialization (runtime option
RTEREUS) to establish a reusable environment.
v You cannot run a COBOL program compiled with the NOTHREAD option 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 NOTHREAD COBOL
programs in the initial process thread (IPT) or in one non-IPT that you create
from a C or PL/I routine.
You can run a COBOL program in more than one thread if you compile all the
COBOL programs in the application with the THREAD option.
You can use Debug Tool to debug z/OS UNIX programs in remote debug mode,
for example, by using the Debug Perspective of Rational Developer for System z,
or in full-screen mode (MFI) using a VTAM® terminal.
RELATED TASKS
Chapter 15, “Compiling under z/OS UNIX,” on page 291
“Running OO applications under z/OS UNIX” on page 302
“Running in z/OS UNIX environments”
“Setting and accessing environment variables” on page 452
“Calling UNIX/POSIX APIs” on page 454
“Accessing main program parameters under z/OS UNIX” on page 456
Language Environment Programming Guide
RELATED REFERENCES
“RENT” on page 355
Running in z/OS UNIX environments
You can run COBOL programs in any of the z/OS UNIX execution environments,
either from within a z/OS UNIX shell or from outside a shell.
About this task
v You can run programs in either the OMVS shell (OMVS) or the ISPF shell
(ISHELL).
Enter the program-name at the shell prompt. The program must be in the
current directory or in your search path.
© Copyright IBM Corp. 1991, 2013
451
You can specify runtime options only by setting the environment variable
_CEE_RUNOPTS before starting the program.
You can run programs that reside in a cataloged MVS data set from a shell by
using the tso utility. For example:
tso "call ’my.loadlib(myprog)’"
The ISPF shell can direct stdout and stderr only to a z/OS UNIX file, not to
your terminal.
v From outside a shell, you can run programs either under TSO/E or in batch.
To call a COBOL program that resides in a z/OS UNIX file from the TSO/E
prompt, use the BPXBATCH utility or a spawn() syscall in a REXX exec.
To call a COBOL program that resides in a z/OS UNIX file with the EXEC JCL
statement, use the BPXBATCH utility.
RELATED TASKS
“Running OO applications under z/OS UNIX” on page 302
“Setting and accessing environment variables”
“Calling UNIX/POSIX APIs” on page 454
“Accessing main program parameters under z/OS UNIX” on page 456
“Defining and allocating QSAM files” on page 181
“Allocating line-sequential files” on page 221
“Allocating VSAM files” on page 213
“Displaying values on a screen or in a file (DISPLAY)” on page 36
Language Environment Programming Guide (Running POSIX-enabled programs)
RELATED REFERENCES
“TEST” on page 364
UNIX System Services User's Guide (The BPXBATCH utility)
Language Environment Programming Reference
Setting and accessing environment variables
You can set environment variables for z/OS UNIX COBOL programs either from
the shell with commands export and set, or from the program.
About this task
Although setting and resetting environment variables from the shell before you
begin to run a program is a typical procedure, you can set, reset, and access
environment variables from the program while it is running.
If you are running a program with BPXBATCH, you can set environment variables
by using an STDENV DD statement.
To reset an environment variable as if it had not been set, use the z/OS UNIX shell
command unset. To reset an environment variable from a COBOL program, call
the setenv() function.
To see the values of all environment variables, use the export command with no
parameters. To access the value of an environment variable from a COBOL
program, call the getenv() function.
“Example: setting and accessing environment variables” on page 454
452
Enterprise COBOL for z/OS, V5.1 Programming Guide
RELATED TASKS
“Running in z/OS UNIX environments” on page 451
“Setting environment variables that affect execution”
“Accessing main program parameters under z/OS UNIX” on page 456
“Running OO applications under z/OS UNIX” on page 302
“Setting environment variables under z/OS UNIX” on page 291
RELATED REFERENCES
“Runtime environment variables”
Language Environment Programming Reference
MVS Program Management: User's Guide and Reference
Setting environment variables that affect execution
To set environment variables for z/OS UNIX COBOL programs from a shell, use
the export or set command. To set environment variables from within the
program, call POSIX functions setenv() or putenv().
About this task
For example, to set the environment variable MYFILE:
export MYFILE=/usr/mystuff/notes.txt
“Example: setting and accessing environment variables” on page 454
RELATED TASKS
“Calling UNIX/POSIX APIs” on page 454
“Setting environment variables under z/OS UNIX” on page 291
RELATED REFERENCES
“Runtime environment variables”
Runtime environment variables
Several runtime variables are of interest for COBOL programs.
These are the runtime environment variables:
_CEE_ENVFILE
Specifies a file from which to read environment variables.
_CEE_RUNOPTS
Specifies runtime options.
CLASSPATH
Specifies directory paths of Java .class files required for an OO application.
COBJVMINITOPTIONS
Specifies Java virtual machine (JVM) options to be used when COBOL
initializes a JVM.
_IGZ_SYSOUT
Specifies where to direct DISPLAY output. stdout and stderr are the only
allowable values.
LIBPATH
Specifies directory paths of dynamic link libraries.
PATH Specifies directory paths of executable programs.
Chapter 23. Running COBOL programs under z/OS UNIX
453
STEPLIB
Specifies location of programs that are not in the LNKLST.
RELATED TASKS
“Displaying data on the system logical output device” on page 37
RELATED REFERENCES
XL C/C++ Programming Guide (_CEE_ENVFILE)
Language Environment Programming Reference
Example: setting and accessing environment variables
The following example shows how you can access and set environment variables
from a COBOL program by calling the standard POSIX functions getenv() and
putenv().
Because getenv() and putenv() are C functions, you must pass arguments BY VALUE.
Pass character strings as BY VALUE pointers that point to null-terminated strings.
Compile programs that call these functions with the NODYNAM and
PGMNAME(LONGMIXED) options.
CBL pgmname(longmixed),nodynam
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.
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 z/OS UNIX COBOL programs
and from traditional z/OS COBOL programs by using the CALL literal statement.
These functions are part of Language Environment.
454
Enterprise COBOL for z/OS, V5.1 Programming Guide
About this task
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.
|
You can call the fork(), exec(), and spawn() functions from a COBOL program or
from a non-COBOL program in the same process as COBOL programs. However,
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. File status code 92 is
returned if you attempt such 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
conditions are 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 a VS COBOL II program.
v With one exception, 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 inv