Enterprise COBOL for z/OS

6.2

Programming Guide

IBM

SC27-8714-01
 Note
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page 867.

Second edition (30 June 2023 update)

This edition applies to Version 6 Release 2 of IBM® Enterprise COBOL for z/OS® (program number 5655-EC6) 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 view or download softcopy publications free of charge in the Enterprise COBOL for z/OS library. Because
Enterprise COBOL for z/OS supports the continuous delivery (CD) model and publications are updated to document the
features delivered under the CD model, it is a good idea to check for updates once every two months.
It is our intention to update the product documentation for this release periodically, without updating the order number.
If you need to uniquely refer to the version of your product documentation, refer to the order number with the date of
update.
© Copyright International Business Machines Corporation 1991, 2023.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

Tables.................................................................................................................xix

Preface.............................................................................................................. xxv
About this information..............................................................................................................................xxv
How this information will help you..................................................................................................... xxv
Abbreviated terms...............................................................................................................................xxv
Comparison of commonly used terms...............................................................................................xxvi
How to read syntax diagrams............................................................................................................xxvii
How examples are shown................................................................................................................ xxviii
Additional documentation and support................................................................................................ xxviii
Summary of changes............................................................................................................................... xxix
Version 6 Release 2 with PTFs installed............................................................................................xxix
Version 6 Release 2...........................................................................................................................xxxii
How to send your comments.................................................................................................................xxxiii

Part 1. Coding your program.................................................................................. 1

Chapter 1. Structuring your program...........................................................................................................3

Identifying a program............................................................................................................................. 3
Identifying a program as recursive...................................................................................................4
Marking a program as callable by containing programs.................................................................. 4
Setting a program to an initial state................................................................................................. 4
Changing the header of a source listing........................................................................................... 5
Describing the computing environment.................................................................................................5
Example: FILE-CONTROL entries..................................................................................................... 6
Specifying the collating sequence.................................................................................................... 7
Defining symbolic characters........................................................................................................... 8
Defining a user-defined class........................................................................................................... 8
Defining files to the operating system.............................................................................................. 8
Describing the data.............................................................................................................................. 11
Using data in input and output operations.....................................................................................11
Comparison of WORKING-STORAGE and LOCAL-STORAGE......................................................... 14
Using data from another program.................................................................................................. 16
Processing the data.............................................................................................................................. 17
How logic is divided in the PROCEDURE DIVISION.......................................................................18
Declaratives.................................................................................................................................... 21

Chapter 2. Using data................................................................................................................................ 23

Using variables, structures, literals, and constants............................................................................ 23
Using variables................................................................................................................................23
Using data items and group items..................................................................................................24
Using literals................................................................................................................................... 25
Using constants...............................................................................................................................26
Using figurative constants.............................................................................................................. 26
Assigning values to data items.............................................................................................................27
Examples: initializing data items....................................................................................................28
Initializing a structure (INITIALIZE).............................................................................................. 31
Assigning values to elementary data items (MOVE)...................................................................... 32
Assigning values to group data items (MOVE)............................................................................... 33
Assigning arithmetic results (MOVE or COMPUTE)........................................................................ 34

iii
 Assigning input from a screen or file (ACCEPT)............................................................................. 35
Displaying values on a screen or in a file (DISPLAY)........................................................................... 35
Displaying data on the system logical output device.....................................................................36
Using WITH NO ADVANCING..........................................................................................................37
Using intrinsic functions (built-in functions)....................................................................................... 38
Using tables (arrays) and pointers....................................................................................................... 39
Storage and its addressability..............................................................................................................39

Chapter 3. Working with numbers and arithmetic.................................................................................... 43

Defining numeric data.......................................................................................................................... 43
Displaying numeric data.......................................................................................................................45
Controlling how numeric data is stored...............................................................................................46
Formats for numeric data.....................................................................................................................47
Examples: numeric data and internal representation................................................................... 50
Data format conversions...................................................................................................................... 51
Conversions and precision..............................................................................................................52
Sign representation of zoned and packed-decimal data.................................................................... 53
Checking for incompatible data (numeric class test)..........................................................................53
Performing arithmetic.......................................................................................................................... 55
Using COMPUTE and other arithmetic statements........................................................................55
Using arithmetic expressions......................................................................................................... 56
Using numeric intrinsic functions................................................................................................... 56
Using math-oriented callable services...........................................................................................58
Using date callable services........................................................................................................... 59
Examples: numeric intrinsic functions........................................................................................... 60
Fixed-point contrasted with floating-point arithmetic........................................................................62
Examples: fixed-point and floating-point evaluations...................................................................63
Using currency signs............................................................................................................................ 64
Example: multiple currency signs.................................................................................................. 65

Chapter 4. Handling tables........................................................................................................................ 67

Defining a table (OCCURS)................................................................................................................... 67
Nesting tables.......................................................................................................................................69
Example: subscripting.................................................................................................................... 70
Example: indexing...........................................................................................................................70
Referring to an item in a table..............................................................................................................70
Subscripting.................................................................................................................................... 71
Indexing.......................................................................................................................................... 72
Putting values into a table....................................................................................................................73
Loading a table dynamically........................................................................................................... 73
Initializing a table (INITIALIZE)..................................................................................................... 73
Assigning values when you define a table (VALUE)....................................................................... 74
Example: PERFORM and subscripting............................................................................................76
Example: PERFORM and indexing.................................................................................................. 77
Creating variable-length tables (DEPENDING ON)............................................................................. 78
Loading a variable-length table...................................................................................................... 80
Assigning values to a variable-length table................................................................................... 80
Complex OCCURS DEPENDING ON..................................................................................................... 81
Example: complex ODO.................................................................................................................. 81
Effects of change in ODO object value........................................................................................... 82
Searching a table.................................................................................................................................. 84
Doing a serial search (SEARCH)......................................................................................................85
Doing a binary search (SEARCH ALL)............................................................................................. 86
Sorting a table...................................................................................................................................... 87
Processing table items using intrinsic functions................................................................................. 87
Example: processing tables using intrinsic functions....................................................................88
Working with unbounded tables and groups.......................................................................................88
Example: Using unbounded tables for parsing XML documents...................................................89

iv
Chapter 5. Selecting and repeating program actions............................................................................... 91
Selecting program actions................................................................................................................... 91
Coding a choice of actions.............................................................................................................. 91
Coding conditional expressions......................................................................................................95
Repeating program actions.................................................................................................................. 99
Choosing inline or out-of-line PERFORM....................................................................................... 99
Coding a loop................................................................................................................................ 100
Looping through a table................................................................................................................101
Executing multiple paragraphs or sections................................................................................. 101

Chapter 6. Handling strings.....................................................................................................................103

Joining data items (STRING)............................................................................................................. 103
Example: STRING statement....................................................................................................... 104
Splitting data items (UNSTRING).......................................................................................................105
Example: UNSTRING statement.................................................................................................. 106
Manipulating null-terminated strings................................................................................................ 108
Example: null-terminated strings................................................................................................ 108
Referring to substrings of data items................................................................................................ 109
Reference modifiers..................................................................................................................... 110
Example: arithmetic expressions as reference modifiers........................................................... 111
Example: intrinsic functions as reference modifiers................................................................... 111
Tallying and replacing data items (INSPECT)....................................................................................112
Examples: INSPECT statement....................................................................................................112
Converting data items (intrinsic functions)....................................................................................... 113
Changing case (UPPER-CASE, LOWER-CASE)............................................................................. 114
Transforming to reverse order (REVERSE)...................................................................................114
Converting to numbers (NUMVAL, NUMVAL-C, NUMVAL-F)........................................................115
Converting from one code page to another................................................................................. 116
Converting to hexadecimal or bit data (HEX-OF, BIT-OF)........................................................... 116
Converting from hexadecimal or bit data (HEX-TO-CHAR, BIT-TO-CHAR).................................117
Evaluating data items (intrinsic functions)........................................................................................ 117
Evaluating single characters for collating sequence................................................................... 118
Finding the largest or smallest data item.................................................................................... 118
Finding the length of data items...................................................................................................120
Finding the date of compilation....................................................................................................121

Chapter 7. Processing data in an international environment................................................................. 123

COBOL statements and national data............................................................................................... 124
Intrinsic functions and national data.................................................................................................127
Unicode and the encoding of language characters........................................................................... 129
Using national data (Unicode) in COBOL........................................................................................... 129
Defining national data items........................................................................................................ 130
Using national literals................................................................................................................... 130
Using national-character figurative constants.............................................................................131
Defining national numeric data items.......................................................................................... 132
National groups.............................................................................................................................132
Using national groups................................................................................................................... 133
Storage of character data............................................................................................................. 136
Converting to or from national (Unicode) representation.................................................................136
Converting alphanumeric, DBCS, and integer to national (MOVE).............................................. 137
Converting alphanumeric or DBCS to national (NATIONAL-OF)................................................. 138
Converting national to alphanumeric (DISPLAY-OF)................................................................... 138
Overriding the default code page................................................................................................. 138
Conversion exceptions................................................................................................................. 139
Example: converting to and from national data...........................................................................139
Processing UTF-8 data.......................................................................................................................140
Using intrinsic functions to process UTF-8 encoded data...........................................................140

v
 Processing Chinese GB 18030 data.................................................................................................. 144
Comparing national (UTF-16) data....................................................................................................145
Comparing two class national operands......................................................................................145
Comparing class national and class numeric operands.............................................................. 146
Comparing national numeric and other numeric operands.........................................................146
Comparing national and other character-string operands.......................................................... 147
Comparing national data and alphanumeric-group operands.................................................... 147
Coding for use of DBCS support.........................................................................................................147
Defining DBCS data.......................................................................................................................148
Using DBCS literals....................................................................................................................... 148
Testing for valid DBCS characters................................................................................................ 149
Processing alphanumeric data items that contain DBCS data....................................................149

Chapter 8. Processing files...................................................................................................................... 151

File organization and input-output devices.......................................................................................151
Choosing file organization and access mode.................................................................................... 152
Format for coding input and output............................................................................................. 153
Allocating files.................................................................................................................................... 154
Checking for input or output errors................................................................................................... 155

Chapter 9. Processing QSAM files........................................................................................................... 157

Defining QSAM files and records in COBOL....................................................................................... 157
Establishing record formats......................................................................................................... 158
Setting block sizes........................................................................................................................ 164
Coding input and output statements for QSAM files.........................................................................166
Opening QSAM files...................................................................................................................... 166
Dynamically creating QSAM files..................................................................................................167
Adding records to QSAM files.......................................................................................................167
Updating QSAM files..................................................................................................................... 167
Writing QSAM files to a printer or spooled data set.....................................................................168
Closing QSAM files........................................................................................................................168
Handling errors in QSAM files............................................................................................................ 169
Working with QSAM files.................................................................................................................... 169
Defining and allocating QSAM files.............................................................................................. 170
Retrieving QSAM files................................................................................................................... 172
Ensuring that file attributes match your program....................................................................... 173
Using striped extended-format QSAM data sets......................................................................... 175
Allocation of buffers for QSAM files............................................................................................. 176
Accessing z/OS UNIX files using QSAM.............................................................................................176
Processing QSAM ASCII files on tape................................................................................................177

Chapter 10. Processing VSAM files......................................................................................................... 179

VSAM files...........................................................................................................................................180
Defining VSAM file organization and records.................................................................................... 181
Specifying sequential organization for VSAM files...................................................................... 182
Specifying indexed organization for VSAM files...........................................................................182
Specifying relative organization for VSAM files........................................................................... 183
Specifying access modes for VSAM files......................................................................................184
Defining record lengths for VSAM files.........................................................................................185
Coding input and output statements for VSAM files......................................................................... 186
File position indicator................................................................................................................... 188
Opening a file (ESDS, KSDS, or RRDS)......................................................................................... 188
Reading records from a VSAM file................................................................................................ 191
Updating records in a VSAM file................................................................................................... 191
Adding records to a VSAM file...................................................................................................... 192
Replacing records in a VSAM file..................................................................................................193
Deleting records from a VSAM file............................................................................................... 193
Closing VSAM files........................................................................................................................ 193

vi
 Handling errors in VSAM files............................................................................................................ 194
Protecting VSAM files with a password............................................................................................. 194
Example: password protection for a VSAM indexed file..............................................................195
Working with VSAM data sets under z/OS and z/OS UNIX............................................................... 195
Defining VSAM files.......................................................................................................................196
Creating alternate indexes........................................................................................................... 196
Allocating VSAM files....................................................................................................................198
Sharing VSAM files through RLS...................................................................................................199
Allocation of record areas for VSAM files.......................................................................................... 201
Improving VSAM performance...........................................................................................................201
Extended addressability support.......................................................................................................202

Chapter 11. Processing line-sequential files.......................................................................................... 205

Defining line-sequential files and records in COBOL........................................................................ 205
Describing the structure of a line-sequential file........................................................................ 206
Control characters in line-sequential files...................................................................................206
Allocating line-sequential files.......................................................................................................... 206
Coding input-output statements for line-sequential files................................................................ 207
Opening line-sequential files....................................................................................................... 208
Reading records from line-sequential files..................................................................................208
Adding records to line-sequential files........................................................................................ 209
Closing line-sequential files......................................................................................................... 209
Handling errors in line-sequential files............................................................................................. 210

Chapter 12. Sorting and merging files.....................................................................................................211

Sort and merge process..................................................................................................................... 212
Describing the sort or merge file....................................................................................................... 212
Describing the input to sorting or merging........................................................................................ 213
Example: describing sort and input files for SORT...................................................................... 214
Coding the input procedure............................................................................................................... 214
Describing the output from sorting or merging................................................................................. 215
Coding the output procedure.............................................................................................................216
Example: coding the output procedure when using DFSORT..................................................... 216
Restrictions on input and output procedures....................................................................................217
Defining sort and merge data sets.....................................................................................................217
Sorting variable-length records......................................................................................................... 218
Requesting the sort or merge............................................................................................................ 218
Setting sort or merge criteria....................................................................................................... 219
Example: sorting with input and output procedures................................................................... 220
Choosing alternate collating sequences...................................................................................... 221
Preserving the original sequence of records with equal keys..................................................... 221
Determining whether the sort or merge was successful.................................................................. 221
Stopping a sort or merge operation prematurely.............................................................................. 222
Improving sort performance with FASTSRT...................................................................................... 222
FASTSRT requirements for JCL.................................................................................................... 223
FASTSRT requirements for sort input and output files................................................................223
Checking for sort errors with NOFASTSRT........................................................................................ 224
Controlling sort behavior................................................................................................................... 225
Changing DFSORT defaults with control statements.................................................................. 226
Allocating storage for sort or merge operations.......................................................................... 226
Allocating space for sort files....................................................................................................... 227
Using checkpoint/restart with DFSORT............................................................................................. 227
Using COBOL user exit routines with DFSORT.................................................................................. 228
Sorting under CICS.............................................................................................................................228
CICS SORT application restrictions..............................................................................................228

Chapter 13. Handling errors.................................................................................................................... 231

Requesting dumps............................................................................................................................. 231

vii
 Handling errors in joining and splitting strings..................................................................................232
Handling errors in arithmetic operations.......................................................................................... 232
Example: checking for division by zero........................................................................................ 233
Handling errors in input and output operations................................................................................ 233
Using the end-of-file condition (AT END).....................................................................................236
Coding ERROR declaratives..........................................................................................................236
Using file status keys.................................................................................................................... 237
Example: file status key................................................................................................................238
Using VSAM status codes (VSAM files only)................................................................................ 238
Example: checking VSAM status codes....................................................................................... 239
Coding INVALID KEY phrases.......................................................................................................240
Example: FILE STATUS and INVALID KEY................................................................................... 241
Handling errors when calling programs............................................................................................ 241
Writing routines for handling errors...................................................................................................242

Part 2. Compiling and debugging your program...................................................243

Chapter 14. Compiling under z/OS..........................................................................................................245

Compiling with JCL.............................................................................................................................245
Using a cataloged procedure........................................................................................................246
Writing JCL to compile programs................................................................................................. 250
Compiling under TSO......................................................................................................................... 252
Example: ALLOCATE and CALL for compiling under TSO............................................................ 253
Example: CLIST for compiling under TSO.................................................................................... 253
Starting the compiler from an assembler program........................................................................... 254
Defining compiler input and output................................................................................................... 256
Data sets used by the compiler under z/OS.................................................................................256
Defining the source code data set (SYSIN).................................................................................. 259
Defining a compiler-option data set (SYSOPTF).......................................................................... 260
Specifying source libraries (SYSLIB)............................................................................................ 260
Defining the output data set (SYSPRINT).................................................................................... 261
Directing compiler messages to your terminal (SYSTERM).........................................................261
Creating object code (SYSLIN or SYSPUNCH)............................................................................. 261
Defining an associated-data file (SYSADATA)..............................................................................262
Defining the Java-source output file (SYSJAVA)..........................................................................262
Defining the debug data set (SYSDEBUG)....................................................................................262
Defining the library-processing output file (SYSMDECK)............................................................ 263
Specifying compiler options under z/OS........................................................................................... 263
Specifying compiler options in the PROCESS (CBL) statement...................................................264
Example: specifying compiler options using JCL........................................................................ 265
Example: specifying compiler options under TSO.......................................................................265
Compiler options and compiler output under z/OS..................................................................... 265
Compiling multiple programs (batch compilation)........................................................................... 266
Example: batch compilation.........................................................................................................267
Specifying compiler options in a batch compilation....................................................................268
Example: precedence of options in a batch compilation............................................................ 268
Example: LANGUAGE option in a batch compilation...................................................................269
Correcting errors in your source program......................................................................................... 270
Generating a list of compiler messages....................................................................................... 271
Messages and listings for compiler-detected errors................................................................... 271
Format of compiler diagnostic messages.................................................................................... 271
Severity codes for compiler diagnostic messages.......................................................................272

Chapter 15. Compiling under z/OS UNIX................................................................................................ 273

Setting environment variables under z/OS UNIX.............................................................................. 273
Specifying compiler options under z/OS UNIX..................................................................................274
Compiling and linking with the cob2 command................................................................................ 275

viii
 Creating a DLL under z/OS UNIX.................................................................................................. 276
Example: using cob2 to compile and link under z/OS UNIX....................................................... 276
cob2 syntax and options...............................................................................................................277
cob2 input and output files.......................................................................................................... 279
Compiling using scripts...................................................................................................................... 280

Chapter 16. Compiling, linking, and running OO applications............................................................... 281

Compiling, linking, and running OO applications under z/OS UNIX................................................. 281
Compiling OO applications under z/OS UNIX.............................................................................. 281
Preparing OO applications under z/OS UNIX...............................................................................282
Example: compiling and linking a COBOL class definition under z/OS UNIX............................. 283
Running OO applications under z/OS UNIX................................................................................. 283
Compiling, linking, and running OO applications in JCL or TSO/E.................................................... 285
Compiling OO applications in JCL or TSO/E.................................................................................285
Preparing and running OO applications in JCL or TSO/E............................................................. 286
Example: compiling, linking, and running an OO application using JCL..................................... 287
Using Java SDKs for z/OS...................................................................................................................288
Object-oriented syntax, and Java 6 or later.................................................................................289

Chapter 17. Compiler options................................................................................................................. 291

Option settings for 85 COBOL Standard conformance..................................................................... 295
Conflicting compiler options.............................................................................................................. 295
ADATA................................................................................................................................................. 297
ADV..................................................................................................................................................... 297
AFP..................................................................................................................................................... 298
APOST/QUOTE....................................................................................................................................298
ARCH...................................................................................................................................................299
ARITH................................................................................................................................................. 300
AWO.................................................................................................................................................... 302
BLOCK0...............................................................................................................................................302
BUFSIZE............................................................................................................................................. 303
CICS.................................................................................................................................................... 303
CODEPAGE..........................................................................................................................................304
COMPILE.............................................................................................................................................307
COPYLOC............................................................................................................................................ 307
COPYRIGHT........................................................................................................................................309
CURRENCY......................................................................................................................................... 309
DATA................................................................................................................................................... 310
DBCS...................................................................................................................................................311
DECK................................................................................................................................................... 311
DEFINE............................................................................................................................................... 311
DIAGTRUNC........................................................................................................................................312
DISPSIGN........................................................................................................................................... 313
DLL...................................................................................................................................................... 314
DUMP.................................................................................................................................................. 316
DYNAM................................................................................................................................................317
EXIT.................................................................................................................................................... 317
EXPORTALL.........................................................................................................................................319
FASTSRT............................................................................................................................................. 320
FLAG................................................................................................................................................... 320
FLAGSTD.............................................................................................................................................321
HGPR.................................................................................................................................................. 323
INITCHECK......................................................................................................................................... 323
INITIAL...............................................................................................................................................325
INLINE................................................................................................................................................ 325
INTDATE............................................................................................................................................. 326
INVDATA............................................................................................................................................. 326
LANGUAGE......................................................................................................................................... 330

ix
 LINECOUNT........................................................................................................................................ 331
LIST.....................................................................................................................................................331
MAP.....................................................................................................................................................332
MAXPCF.............................................................................................................................................. 333
MDECK................................................................................................................................................ 334
NAME.................................................................................................................................................. 335
NSYMBOL........................................................................................................................................... 335
NUMBER............................................................................................................................................. 336
NUMCHECK........................................................................................................................................ 336
NUMPROC...........................................................................................................................................340
OBJECT...............................................................................................................................................341
OFFSET............................................................................................................................................... 341
OPTFILE..............................................................................................................................................342
OPTIMIZE........................................................................................................................................... 343
OUTDD................................................................................................................................................ 344
PARMCHECK.......................................................................................................................................344
PGMNAME.......................................................................................................................................... 345
QUALIFY............................................................................................................................................. 347
RENT................................................................................................................................................... 348
RMODE................................................................................................................................................349
RULES................................................................................................................................................. 350
SEQUENCE..........................................................................................................................................352
SERVICE............................................................................................................................................. 352
SOURCE.............................................................................................................................................. 353
SPACE................................................................................................................................................. 353
SQL......................................................................................................................................................354
SQLCCSID........................................................................................................................................... 355
SQLIMS............................................................................................................................................... 355
SSRANGE............................................................................................................................................ 356
STGOPT...............................................................................................................................................357
SUPPRESS.......................................................................................................................................... 358
TERMINAL.......................................................................................................................................... 358
TEST....................................................................................................................................................359
THREAD.............................................................................................................................................. 363
TRUNC................................................................................................................................................ 364
VBREF................................................................................................................................................. 366
VLR......................................................................................................................................................366
VSAMOPENFS.....................................................................................................................................368
WORD................................................................................................................................................. 369
XMLPARSE.......................................................................................................................................... 369
XREF................................................................................................................................................... 370
ZONECHECK....................................................................................................................................... 371
ZONEDATA.......................................................................................................................................... 372
ZWB.................................................................................................................................................... 375

Chapter 18. Compiler-directing statements........................................................................................... 377

Chapter 19. Debugging............................................................................................................................381

Debugging with source language.......................................................................................................382
Tracing program logic................................................................................................................... 382
Finding and handling input-output errors....................................................................................383
Validating data.............................................................................................................................. 383
Moving, initializing or setting uninitialized data...........................................................................383
Generating information about procedures.................................................................................. 384
Debugging using compiler options.................................................................................................... 385
Finding coding errors....................................................................................................................386
Finding line sequence problems.................................................................................................. 386
Checking for invalid COBOL data or invalid COBOL programs.....................................................386

x
 Checking for valid ranges............................................................................................................. 387
Selecting the level of error to be diagnosed................................................................................ 388
Finding program entity definitions and references......................................................................390
Listing data items..........................................................................................................................390
Using the debugger............................................................................................................................ 391
Getting listings................................................................................................................................... 391
Example: short listing................................................................................................................... 393
Example: SOURCE and NUMBER output......................................................................................396
Example: MAP output................................................................................................................... 396
Reading LIST output..................................................................................................................... 402
Example: XREF output: data-name cross-references................................................................. 420
Example: OFFSET compiler output.............................................................................................. 424
Example: VBREF compiler output................................................................................................ 424
Example: conditional compilation output....................................................................................425
Suppressing information in CEEDUMP processing (IGZ1OPT).........................................................426

Part 3. Targeting COBOL programs for certain environments............................... 427

Chapter 20. Developing COBOL programs for CICS............................................................................... 429

Coding COBOL programs to run under CICS..................................................................................... 429
Getting the system date under CICS............................................................................................431
Calling to or from COBOL programs............................................................................................. 431
Determining the success of ECI calls...........................................................................................432
Compiling with the CICS option......................................................................................................... 433
Separating CICS suboptions.........................................................................................................434
Integrated CICS translator........................................................................................................... 434
Using the separate CICS translator................................................................................................... 435
CICS reserved-word table..................................................................................................................436
Handling errors by using CICS HANDLE............................................................................................ 437
Example: handling errors by using CICS HANDLE....................................................................... 438

Chapter 21. Programming for a Db2 environment................................................................................. 439

Db2 coprocessor................................................................................................................................ 439
Using the separate Db2 precompiler.................................................................................................440
Coding SQL statements......................................................................................................................440
Using SQL INCLUDE with the Db2 coprocessor...........................................................................441
Using character data in SQL statements......................................................................................441
Using national decimal data in SQL statements.......................................................................... 442
Using national group items in SQL statements............................................................................442
Using binary items in SQL statements......................................................................................... 443
Determining the success of SQL statements............................................................................... 443
Compiling with the SQL option.......................................................................................................... 443
Separating Db2 suboptions.......................................................................................................... 444
COBOL and Db2 CCSID determination.............................................................................................. 444
Code-page determination for string host variables in SQL statements...................................... 445
Programming with the SQLCCSID or NOSQLCCSID option......................................................... 446
Differences in how the Db2 precompiler and coprocessor behave..................................................446
Choosing the DYNAM or NODYNAM compiler option........................................................................448

Chapter 22. Developing COBOL programs for IMS................................................................................. 451

IMS SQL coprocessor......................................................................................................................... 451
Coding SQLIMS statements............................................................................................................... 452
Using SQLIMS INCLUDE with the IMS SQL coprocessor............................................................. 452
Using character data in SQLIMS statements............................................................................... 452
Using binary items in SQLIMS statements...................................................................................453
Determining the success of SQLIMS statements........................................................................ 453
Compiling with the SQLIMS option.................................................................................................... 453

xi
 Separating IMS suboptions.......................................................................................................... 454
Compiling and linking COBOL programs for running under IMS.......................................................454
Using object-oriented COBOL and Java under IMS.......................................................................... 455
Calling a COBOL method from a Java application under IMS..................................................... 455
Building a mixed COBOL-Java application that starts with COBOL............................................ 456
Writing mixed-language IMS applications................................................................................... 456

Chapter 23. Running COBOL programs under z/OS UNIX......................................................................459

Running in z/OS UNIX environments.................................................................................................459
Setting and accessing environment variables...................................................................................460
Setting environment variables that affect execution...................................................................461
Runtime environment variables................................................................................................... 461
Example: setting and accessing environment variables............................................................. 462
Calling UNIX/POSIX APIs.................................................................................................................. 462
Accessing main program parameters under z/OS UNIX................................................................... 464
Example: accessing main program parameters under z/OS UNIX............................................. 464

Chapter 24. Developing COBOL programs in the mixed AMODE Language Environment.....................467
COBOL programs in AMODE 31 interacting with Java programs in AMODE 64............................... 467
Application calls between COBOL programs in AMODE 31 and Java programs in AMODE 64..467
Building the mixed AMODE COBOL/Java interoperability application .......................................468
Running the mixed AMODE COBOL/Java interoperability program............................................468
Examples for mixed AMODE COBOL/Java interoperability application .....................................469

Part 4. Structuring complex applications............................................................ 471

Chapter 25. Using subprograms..............................................................................................................473

Main programs, subprograms, and calls........................................................................................... 473
Ending and reentering main programs or subprograms................................................................... 474
Transferring control to another program........................................................................................... 475
Making static calls........................................................................................................................ 476
Making dynamic calls................................................................................................................... 476
AMODE switching..........................................................................................................................478
Performance considerations of static and dynamic calls............................................................480
Making both static and dynamic calls.......................................................................................... 480
Examples: static and dynamic CALL statements.........................................................................481
Calling nested COBOL programs.................................................................................................. 482
Making recursive calls........................................................................................................................485
Calling to and from object-oriented programs.................................................................................. 485
Using procedure and function pointers............................................................................................. 485
Deciding which type of pointer to use..........................................................................................487
Calling alternate entry points....................................................................................................... 488
Making programs reentrant............................................................................................................... 488

Chapter 26. Sharing data.........................................................................................................................491

Passing data....................................................................................................................................... 491
Describing arguments in the calling program.............................................................................. 494
Describing parameters in the called program............................................................................. 494
Testing for OMITTED arguments.................................................................................................. 495
Coding the LINKAGE SECTION.......................................................................................................... 495
Coding the PROCEDURE DIVISION for passing arguments..............................................................496
Grouping data to be passed......................................................................................................... 496
Handling null-terminated strings................................................................................................. 497
Using pointers to process a chained list...................................................................................... 497
Passing return-code information....................................................................................................... 500
Using the RETURN-CODE special register................................................................................... 500
Using PROCEDURE DIVISION RETURNING . . ............................................................................ 500

xii
 Specifying CALL . . . RETURNING................................................................................................. 501
Sharing data by using the EXTERNAL clause.................................................................................... 501
Sharing files between programs (external files)............................................................................... 501
Example: using external files....................................................................................................... 502
Accessing main program parameters under z/OS.............................................................................504
Example: accessing main program parameters under z/OS....................................................... 505

Chapter 27. Creating a DLL or a DLL application.................................................................................... 507

Dynamic link libraries (DLLs)............................................................................................................. 507
Compiling programs to create DLLs...................................................................................................508
Linking DLLs........................................................................................................................................508
Example: sample JCL for a procedural DLL application....................................................................509
Using CALL identifier with DLLs......................................................................................................... 510
Search order for DLLs in the z/OS UNIX file system.................................................................... 510
Using DLL linkage and dynamic calls together.................................................................................. 511
Using procedure or function pointers with DLLs..........................................................................512
Calling DLLs from non-DLLs......................................................................................................... 512
Example: calling DLLs from non-DLLs..........................................................................................513
Using COBOL DLLs with C/C++ programs..........................................................................................514
Using DLLs in OO COBOL applications...............................................................................................514

Chapter 28. Preparing COBOL programs for multithreading..................................................................517

Multithreading.................................................................................................................................... 517
Choosing THREAD to support multithreading................................................................................... 518
Transferring control to multithreaded programs.............................................................................. 519
Ending multithreaded programs........................................................................................................519
Processing files with multithreading................................................................................................. 520
File-definition (FD) storage.......................................................................................................... 520
Serializing file access with multithreading.................................................................................. 521
Example: usage patterns of file input and output with multithreading...................................... 521
Handling COBOL limitations with multithreading............................................................................. 522

Part 5. Using COBOL for Web Services................................................................ 525

Chapter 29. Web Services interface .......................................................................................................527

Chapter 30. Processing JSON input ....................................................................................................... 529

Parsing JSON documents ..................................................................................................................529
How to match JSON names that are not valid COBOL data names to data items .......................... 530
Preventing data items from being populated by the JSON PARSE statement ................................ 530
Handling JSON arrays........................................................................................................................ 531
JSON PARSE example........................................................................................................................ 532

Chapter 31. Producing JSON output ...................................................................................................... 535

Chapter 32. Processing XML input.......................................................................................................... 537

XML parser in COBOL......................................................................................................................... 538
Accessing XML documents................................................................................................................ 539
Parsing XML documents.....................................................................................................................540
Writing procedures to process XML............................................................................................. 541
XML events....................................................................................................................................543
Transforming XML text to COBOL data items.............................................................................. 548
Parsing XML documents with validation...................................................................................... 548
Parsing XML documents one segment at a time..........................................................................551
Handling splits using the XML-INFORMATION special register.................................................. 553
The encoding of XML documents.......................................................................................................554
XML input document encoding.....................................................................................................555

xiii
 Parsing XML documents encoded in UTF-8.................................................................................558
Handling XML PARSE exceptions.......................................................................................................559
How the XML parser handles errors.............................................................................................561
Handling encoding conflicts......................................................................................................... 562
Terminating XML parsing................................................................................................................... 563
XML PARSE examples........................................................................................................................ 563
Example: parsing a simple document..........................................................................................564
Example: program for processing XML........................................................................................ 564
Example: parsing an XML document that uses namespaces...................................................... 569
Example: parsing an XML document one segment at a time...................................................... 572
Example: parsing XML documents with validation......................................................................574

Chapter 33. Producing XML output......................................................................................................... 577

Generating XML output...................................................................................................................... 577
Controlling the encoding of generated XML output.......................................................................... 582
Handling XML GENERATE exceptions................................................................................................582
Example: generating XML.................................................................................................................. 583
Enhancing XML output....................................................................................................................... 587
Example: enhancing XML output..................................................................................................588

Part 6. Developing object-oriented programs......................................................591

Chapter 34. Writing object-oriented programs.......................................................................................593

Example: accounts............................................................................................................................. 594
Defining a class.................................................................................................................................. 596
CLASS-ID paragraph for defining a class..................................................................................... 597
REPOSITORY paragraph for defining a class............................................................................... 598
WORKING-STORAGE SECTION for defining class instance data................................................599
Example: defining a class............................................................................................................. 600
Defining a class instance method...................................................................................................... 600
METHOD-ID paragraph for defining a class instance method.................................................... 601
INPUT-OUTPUT SECTION for defining a class instance method................................................ 602
DATA DIVISION for defining a class instance method................................................................ 602
PROCEDURE DIVISION for defining a class instance method.................................................... 603
Overriding an instance method.................................................................................................... 604
Overloading an instance method................................................................................................. 605
Coding attribute (get and set) methods....................................................................................... 605
Example: defining a method.........................................................................................................606
Defining a client..................................................................................................................................608
REPOSITORY paragraph for defining a client.............................................................................. 609
DATA DIVISION for defining a client............................................................................................ 610
Comparing and setting object references....................................................................................611
Invoking methods (INVOKE)........................................................................................................ 612
Creating and initializing instances of classes.............................................................................. 616
Freeing instances of classes.........................................................................................................617
Example: defining a client............................................................................................................ 618
Defining a subclass............................................................................................................................ 618
CLASS-ID paragraph for defining a subclass............................................................................... 619
REPOSITORY paragraph for defining a subclass......................................................................... 620
WORKING-STORAGE SECTION for defining subclass instance data..........................................620
Defining a subclass instance method.......................................................................................... 620
Example: defining a subclass (with methods)............................................................................. 621
Defining a factory section.................................................................................................................. 622
WORKING-STORAGE SECTION for defining factory data........................................................... 623
Defining a factory method............................................................................................................ 623
Example: defining a factory (with methods)................................................................................ 625
Wrapping procedure-oriented COBOL programs.............................................................................. 630

xiv
 Structuring OO applications...............................................................................................................630
Examples: COBOL applications that run using the java command............................................. 631

Chapter 35. Communicating with Java methods....................................................................................633

Accessing JNI services...................................................................................................................... 633
Handling Java exceptions.............................................................................................................634
Managing local and global references......................................................................................... 635
Java access controls.....................................................................................................................637
Sharing data with Java....................................................................................................................... 637
Coding interoperable data types in COBOL and Java.................................................................. 638
Declaring arrays and strings for Java........................................................................................... 638
Manipulating Java arrays..............................................................................................................640
Manipulating Java strings.............................................................................................................642
Example: J2EE client written in COBOL............................................................................................ 645
Example: invoking Java from a batch COBOL program.....................................................................648

Part 7. Specialized processing............................................................................653

Chapter 36. Interrupts and checkpoint/restart...................................................................................... 655

Setting checkpoints............................................................................................................................655
Designing checkpoints..................................................................................................................656
Testing for a successful checkpoint............................................................................................. 656
DD statements for defining checkpoint data sets....................................................................... 656
Messages generated during checkpoint...................................................................................... 658
Restarting programs...........................................................................................................................658
Requesting automatic restart.......................................................................................................658
Requesting deferred restart......................................................................................................... 659
Formats for requesting deferred restart...................................................................................... 659
Resubmitting jobs for restart........................................................................................................660
Example: restarting a job at a specific checkpoint step.............................................................. 660
Example: requesting a step restart.............................................................................................. 660
Example: resubmitting a job for a step restart............................................................................ 661
Example: resubmitting a job for a checkpoint restart................................................................. 661

Chapter 37. Using zlib compression from a COBOL program.................................................................663

Part 8. Improving performance and productivity.................................................667

Chapter 38. Tuning your program........................................................................................................... 669

Using an optimal programming style.................................................................................................669
Using structured programming.................................................................................................... 670
Factoring expressions...................................................................................................................670
Using symbolic constants.............................................................................................................670
Choosing efficient data types............................................................................................................ 670
Choosing efficient computational data items.............................................................................. 671
Using consistent data types......................................................................................................... 671
Making arithmetic expressions efficient...................................................................................... 671
Making exponentiations efficient................................................................................................. 672
Using VOLATILE clauses efficiently..............................................................................................672
Handling tables efficiently................................................................................................................. 672
Optimization of table references..................................................................................................673
Optimizing your code......................................................................................................................... 674
Optimization..................................................................................................................................674
Choosing compiler features to enhance performance......................................................................675
Performance-related compiler options........................................................................................676
Evaluating performance............................................................................................................... 679
Running efficiently with CICS, IMS, or VSAM.................................................................................... 680

xv
 Choosing static or dynamic calls....................................................................................................... 681

Chapter 39. Simplifying coding............................................................................................................... 683

Eliminating repetitive coding............................................................................................................. 683
Example: using the COPY statement........................................................................................... 684
Using Language Environment callable services................................................................................ 685
Sample list of Language Environment callable services............................................................. 686
Calling Language Environment services...................................................................................... 687
Example: Language Environment callable services.................................................................... 687
Using the format 2 SORT statement to sort a table.......................................................................... 688

Appendix A. Intermediate results and arithmetic precision.................................691

Terminology used for intermediate results.............................................................................................692
Example: calculation of intermediate results......................................................................................... 692
Fixed-point data and intermediate results............................................................................................. 693
Addition, subtraction, multiplication, and division........................................................................... 693
Exponentiation................................................................................................................................... 694
Example: exponentiation in fixed-point arithmetic...........................................................................695
Truncated intermediate results......................................................................................................... 695
Binary data and intermediate results................................................................................................ 696
Intrinsic functions evaluated in fixed-point arithmetic.......................................................................... 696
Integer functions................................................................................................................................696
Mixed functions.................................................................................................................................. 697
Floating-point data and intermediate results......................................................................................... 698
Exponentiations evaluated in floating-point arithmetic................................................................... 698
Intrinsic functions evaluated in floating-point arithmetic................................................................ 699
Arithmetic expressions in nonarithmetic statements............................................................................ 699

Appendix B. Converting double-byte character set (DBCS) data.......................... 701

DBCS notation..........................................................................................................................................701
Alphanumeric to DBCS data conversion (IGZCA2D).............................................................................. 701
IGZCA2D syntax................................................................................................................................. 701
IGZCA2D return codes....................................................................................................................... 702
Example: IGZCA2D............................................................................................................................ 703
DBCS to alphanumeric data conversion (IGZCD2A)...............................................................................703
IGZCD2A syntax................................................................................................................................. 703
IGZCD2A return codes....................................................................................................................... 704
Example: IGZCD2A............................................................................................................................ 705

Appendix C. XML reference material...................................................................707

XML PARSE exceptions with XMLPARSE(XMLSS) in effect.....................................................................707
XML PARSE exceptions with XMLPARSE(COMPAT) in effect.................................................................. 709
XML PARSE exceptions that allow continuation................................................................................709
XML PARSE exceptions that do not allow continuation.................................................................... 712
XML GENERATE exceptions.....................................................................................................................715

Appendix D. JSON reference material.................................................................717

JSON GENERATE exceptions...................................................................................................................717
JSON PARSE conditions and associated codes and runtime messages................................................ 717
Nonexception conditions and corresponding values of JSON-STATUS............................................718
Exception conditions, and corresponding values of JSON-CODE.....................................................718
Nonexception condition runtime messages......................................................................................719
Exception condition runtime messages............................................................................................ 720

Appendix E. EXIT compiler option...................................................................... 721

Using the user-exit work area................................................................................................................. 721
Calling from exit modules........................................................................................................................722

xvi
 Processing of INEXIT...............................................................................................................................722
INEXIT parameters............................................................................................................................ 722
Processing of LIBEXIT............................................................................................................................. 723
Processing of LIBEXIT with nested COPY statements......................................................................724
LIBEXIT parameters...........................................................................................................................725
Processing of PRTEXIT............................................................................................................................ 726
PRTEXIT parameters..........................................................................................................................727
Processing of ADEXIT.............................................................................................................................. 728
ADEXIT parameters........................................................................................................................... 728
Processing of MSGEXIT........................................................................................................................... 729
MSGEXIT parameters.........................................................................................................................730
Customizing compiler-message severities........................................................................................731
Example: MSGEXIT user exit............................................................................................................. 733
Error handling for exit modules...............................................................................................................738
Using the EXIT compiler option with CICS, SQL and SQLIMS statements............................................ 740

Appendix F. JNI.cpy copybook........................................................................... 743

Appendix G. COBOL SYSADATA file contents.......................................................749

Compiler options that affect the SYSADATA file..................................................................................... 749
SYSADATA record types...........................................................................................................................750
Example: SYSADATA................................................................................................................................ 751
SYSADATA record descriptions............................................................................................................... 752
Common header section......................................................................................................................... 753
Job identification record: X'0000'...........................................................................................................755
ADATA identification record: X'0001'......................................................................................................756
Compilation unit start | end record: X'0002'.......................................................................................... 756
Options record: X'0010'.......................................................................................................................... 757
External symbol record: X'0020'.............................................................................................................767
Parse tree record: X'0024'...................................................................................................................... 768
Token record: X'0030'............................................................................................................................. 794
Source error record: X'0032'...................................................................................................................821
Source record: X'0038'............................................................................................................................821
COPY REPLACING record: X'0039'......................................................................................................... 822
Symbol record: X'0042'........................................................................................................................... 823
Symbol cross-reference record: X'0044'................................................................................................ 835
Nested program record: X'0046'.............................................................................................................837
Library record: X'0060'............................................................................................................................837
Statistics record: X'0090'........................................................................................................................ 838
EVENTS record: X'0120'.......................................................................................................................... 838

Appendix H. Using sample programs.................................................................. 843

IGYTCARA: batch application..................................................................................................................843
Input data for IGYTCARA................................................................................................................... 844
Report produced by IGYTCARA......................................................................................................... 845
Preparing to run IGYTCARA............................................................................................................... 846
IGYTCARB: interactive program.............................................................................................................. 847
Preparing to run IGYTCARB............................................................................................................... 847
IGYTSALE: nested program application..................................................................................................849
Input data for IGYTSALE.................................................................................................................... 850
Reports produced by IGYTSALE........................................................................................................ 852
Preparing to run IGYTSALE................................................................................................................ 856
Language elements and concepts that are illustrated........................................................................... 857

Appendix I. Accessing JCL parameters...............................................................863

Appendix J. Accessibility features for Enterprise COBOL for z/OS........................865

xvii
 Notices..............................................................................................................867
Trademarks.............................................................................................................................................. 868
Glossary............................................................................................................ 871
List of resources................................................................................................ 915
Enterprise COBOL for z/OS...................................................................................................................... 915
Related publications................................................................................................................................915

Index................................................................................................................ 919

xviii
Tables

1. FILE-CONTROL entries..................................................................................................................................6

2. FILE SECTION entries................................................................................................................................. 12

3. Assignment to data items in a program......................................................................................................27

4. Effect of RMODE and RENT compiler options on the RMODE attribute.....................................................41

5. Ranges in value of COMP-5 data items.......................................................................................................49

6. Internal representation of numeric items.................................................................................................. 50

7. NUMCLS(PRIM) and valid signs.................................................................................................................. 54

8. NUMCLS(ALT) and valid signs..................................................................................................................... 54

9. Order of evaluation of arithmetic operators............................................................................................... 56

10. Numeric intrinsic functions.......................................................................................................................57

11. Compatibility of math intrinsic functions and callable services.............................................................. 58

12. INTDATE(LILIAN) and compatibility of date intrinsic functions and callable services...........................59

13. INTDATE(ANSI) and compatibility of date intrinsic functions and callable services..............................59

14. Hexadecimal values of the euro sign........................................................................................................65

15. COBOL statements and national data.................................................................................................... 124

16. Intrinsic functions and national character data.....................................................................................127

17. National group items that are processed with group semantics...........................................................135

18. Encoding and size of alphanumeric, DBCS, and national data.............................................................. 136

19. Summary of file organizations, access modes, and record formats of COBOL files............................. 153

20. QSAM file allocation................................................................................................................................170

21. Maximum record length of QSAM files................................................................................................... 174

22. Comparison of VSAM, COBOL, and non-VSAM terminology.................................................................. 179

23. Comparison of VSAM data-set types......................................................................................................180

xix
 24. VSAM file organization, access mode, and record format..................................................................... 181

25. Definition of VSAM fixed-length records................................................................................................ 185

26. Definition of VSAM variable-length records........................................................................................... 186

27. I/O statements for VSAM sequential files.............................................................................................. 187

28. I/O statements for VSAM relative and indexed files.............................................................................. 187

29. Statements to load records into a VSAM file..........................................................................................190

30. Statements to update records in a VSAM file.........................................................................................192

31. Methods for improving VSAM performance........................................................................................... 201

32. Methods for checking for sort errors with NOFASTSRT......................................................................... 225

33. Methods for controlling sort behavior.................................................................................................... 225

34. Compiler data sets.................................................................................................................................. 256

35. Block size of fixed-length compiler data sets........................................................................................ 259

36. Block size of variable-length compiler data sets................................................................................... 259

37. Types of compiler output under z/OS.....................................................................................................265

38. Severity codes for compiler diagnostic messages................................................................................. 272

39. Input files to the cob2 command........................................................................................................... 279

40. Output files from the cob2 command.................................................................................................... 279

41. Commands for compiling and linking a class definition........................................................................ 282

42. java command options for customizing the JVM................................................................................... 284

43. Compiler options.....................................................................................................................................291

44. Mutually exclusive compiler options...................................................................................................... 296

45. EBCDIC multibyte coded character set identifiers................................................................................ 306

46. DISPLAY output with the DISPSIGN(COMPAT) option or the DISPSIGN(SEP) option specified:.........314

47. Setting INVDATA and NUMPROC options when migrating from earlier COBOL versions..................... 327

48. Values of the LANGUAGE compiler option............................................................................................. 330

xx
49. Mapping of removed options to new options......................................................................................... 343

50. Length of record read and file status......................................................................................................368

51. Severity levels of compiler messages.................................................................................................... 388

52. Using compiler options to get listings.................................................................................................... 391

53. Terms used in MAP output......................................................................................................................399

54. Symbols used in LIST and MAP output.................................................................................................. 400

55. Compiler options in the INFO BYTE section.......................................................................................... 403

56. Signature information bytes................................................................................................................... 404

57. Calls between COBOL and assembler under CICS................................................................................ 432

58. Compiler options required for the integrated CICS translator.............................................................. 433

59. Compiler options required for the separate CICS translator.................................................................435

60. TRUNC compiler options recommended for the separate CICS translator.......................................... 436

61. Samples with POSIX function calls........................................................................................................ 463

62. Effects of termination statements..........................................................................................................474

63. Methods for passing data in the CALL statement.................................................................................. 492

64. Compiler options for DLL applications................................................................................................... 508

65. Binder options for DLL applications....................................................................................................... 509

66. Special registers used by the XML parser.............................................................................................. 541

67. Results of processing-procedure changes to XML-CODE with XMLPARSE(XMLSS) in effect...............544

68. Results of processing-procedure changes to XML-CODE with XMLPARSE(COMPAT) in effect............ 545

69. Coded character sets for XML documents............................................................................................. 554

70. Hexadecimal values of white-space characters.................................................................................... 556

71. Aliases for XML encoding declarations.................................................................................................. 557

72. Hexadecimal values of special characters for various EBCDIC CCSIDs............................................... 558

73. XML events and special registers........................................................................................................... 564

xxi
 74. XML events and special registers........................................................................................................... 569

75. XML events and special registers from parsing XML document with an undeclared namespace
prefix.........................................................................................................................................................571

76. Encoding of generated XML if the ENCODING phrase is omitted..........................................................582

77. Structure of class definitions..................................................................................................................596

78. Structure of instance method definitions...............................................................................................601

79. Structure of COBOL clients..................................................................................................................... 608

80. Conformance of arguments in a COBOL client.......................................................................................613

81. Conformance of the returned data item in a COBOL client................................................................... 615

82. Structure of factory definitions...............................................................................................................622

83. Structure of factory method definitions................................................................................................. 623

84. JNI services for local and global references..........................................................................................636

85. Interoperable data types in COBOL and Java........................................................................................ 638

86. Interoperable arrays and strings in COBOL and Java............................................................................ 638

87. Noninteroperable array types in COBOL and Java.................................................................................639

88. JNI array services................................................................................................................................... 640

89. Services that convert between jstring references and national data....................................................642

90. Services that convert between jstring references and alphanumeric data...........................................643

91. Performance-related compiler options..................................................................................................676

92. Performance-tuning worksheet..............................................................................................................680

93. Language Environment callable services............................................................................................... 686

94. Comparison of format 1 and format 2 SORT statements...................................................................... 688

95. IGZCA2D return codes............................................................................................................................702

96. IGZCD2A return codes............................................................................................................................704

97. Reason codes for XML PARSE exceptions that are unique to Enterprise COBOL................................. 707

98. XML PARSE exceptions that allow continuation.................................................................................... 709

xxii
99. XML PARSE exceptions that do not allow continuation (for XMLPARSE(COMPAT))............................. 712

100. XML GENERATE exceptions..................................................................................................................715

101. JSON GENERATE exceptions................................................................................................................717

102. Reason codes for JSON nonexception conditions............................................................................... 718

103. Reason codes for JSON exception conditions..................................................................................... 718

104. Layout of the user-exit work area........................................................................................................ 721

105. INEXIT processing................................................................................................................................ 722

106. INEXIT parameters...............................................................................................................................722

107. LIBEXIT processing.............................................................................................................................. 723

108. LIBEXIT processing with nonnested COPY statements...................................................................... 724

109. LIBEXIT processing with nested COPY statements............................................................................ 725

110. LIBEXIT parameters............................................................................................................................. 725

111. PRTEXIT processing............................................................................................................................. 726

112. PRTEXIT parameters............................................................................................................................ 727

113. ADEXIT processing............................................................................................................................... 728

114. ADEXIT parameters.............................................................................................................................. 728

115. MSGEXIT processing............................................................................................................................ 729

116. MSGEXIT parameters........................................................................................................................... 730

117. FIPS (FLAGSTD) message categories.................................................................................................. 732

118. Actions possible in exit modules for CICS, SQL and SQLIMS statements.......................................... 740

119. SYSADATA record types........................................................................................................................750

120. SYSADATA common header section.....................................................................................................753

121. SYSADATA job identification record..................................................................................................... 755

122. ADATA identification record................................................................................................................. 756

123. SYSADATA compilation unit start | end record.................................................................................... 756

xxiii
 124. SYSADATA options record.................................................................................................................... 757

125. SYSADATA external symbol record...................................................................................................... 767

126. SYSADATA parse tree record................................................................................................................ 768

127. SYSADATA token record....................................................................................................................... 795

128. SYSADATA source error record.............................................................................................................821

129. SYSADATA source record......................................................................................................................821

130. SYSADATA COPY REPLACING record...................................................................................................822

131. SYSADATA symbol record.....................................................................................................................823

132. SYSADATA symbol cross-reference record.......................................................................................... 835

133. SYSADATA nested program record.......................................................................................................837

134. SYSADATA library record...................................................................................................................... 837

135. SYSADATA statistics record.................................................................................................................. 838

136. SYSADATA EVENTS TIMESTAMP record layout................................................................................... 839

137. SYSADATA EVENTS PROCESSOR record layout...................................................................................839

138. SYSADATA EVENTS FILE END record layout........................................................................................ 839

139. SYSADATA EVENTS PROGRAM record layout...................................................................................... 840

140. SYSADATA EVENTS FILE ID record layout........................................................................................... 840

141. SYSADATA EVENTS ERROR record layout............................................................................................840

xxiv
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 for z/OS 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 for
z/OS Language Reference.
For information about migrating programs to Enterprise COBOL, see the IBM Enterprise COBOL for z/OS
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 xxvi.

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 Long form

CICS® CICS Transaction Server
Debug Tool IBM Debug for z/OS (formerly IBM Debug Tool for z/OS and IBM
Debug for z Systems®)1
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, 2023 xxv

 Term used Long form

Note:
1. IBM Debug for z/OS supersedes IBM Debug for z Systems and IBM Debug Tool for z/OS. Not all
references to IBM Debug for z Systems and IBM Debug Tool for z/OS have been changed in the
COBOL documentation library. It is recommended that you upgrade your debugger to the latest level
in order to have the full range of debugging features available. In some cases, you must upgrade your
debugger to a certain version depending on what level of Enterprise COBOL you are using to create
the COBOL application:
• IBM Debug Tool V13.1 supports Enterprise COBOL V5.1 and earlier versions
• IBM Debug for z Systems V14.0 supports Enterprise COBOL V6.1 and earlier versions
• IBM Debug for z Systems V14.1 supports Enterprise COBOL V6.2 and earlier versions
To find out which IBM debug product best suits
your needs, see https://www.ibm.com/support/knowledgecenter/SSQ2R2_14.2.0/
com.ibm.debug.cg.doc/common/dcompo.html?sc=SSQ2R2_latest.

In addition to these abbreviated terms, the term "85 COBOL Standard" is used to refer to the combination
of the following standards:
• ISO 1989:1985, Programming languages - COBOL
• ISO/IEC 1989/AMD1:1992, Programming languages - COBOL: Intrinsic function module
• ISO/IEC 1989/AMD2:1994, Programming languages - Correction and clarification amendment for
COBOL
• ANSI INCITS 23-1985, Programming Languages - COBOL
• ANSI INCITS 23a-1989, Programming Languages - Intrinsic Function Module for COBOL
• ANSI INCITS 23b-1993, Programming Language - Correction Amendment for COBOL
The term "2002 COBOL Standard" is used to refer to the following standard:
• INCITS/ISO/IEC 1989-2002, Information technology - Programming languages - COBOL
The term "2014 COBOL Standard" is used to refer to the following standard:
• INCITS/ISO/IEC 1989:2014, Information technology - Programming languages, their environments and
system software interfaces - Programming language 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

xxvi Preface
 Language Environment term Enterprise COBOL equivalent
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.
• 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.
Diagrams of syntactical units other than complete statements start with the ►─── symbol and end with
the ───► symbol.
• Required items appear on the horizontal line (the main path):

required_item

• Optional items appear below the main path:

required_item
optional_item

• 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:

Preface xxvii
 default_choice
required_item
optional_choice

optional_choice

• An arrow returning to the left, above the main line, indicates an item that can be repeated:

required_item repeatable_item

If the repeat arrow contains a comma, you must separate repeated items with a comma:

required_item repeatable_item

• 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.
• 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.
If you copy and paste examples from the PDF format documentation, make sure that the spaces in the
examples (if any) are in place; you might need to manually add some missing spaces to ensure that
COBOL source text aligns to the required columns per the COBOL reference format in the Enterprise
COBOL for z/OS Language Reference. Alternatively, you can copy and paste examples from the HTML
format documentation and the spaces should be already in place.

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 library page at http://www.ibm.com/support/
docview.wss?uid=swg27036733. These documents are also available in Japanese.
Support information is also available at https://www.ibm.com/support/home/product/
B984385H82239E03/Enterprise_COBOL_for_z/OS.

xxviii Preface
Summary of changes
This section lists the major changes that have been made to this document for Enterprise COBOL
Version 6 Release 2 and Version 6 Release 2 with PTFs installed. The changes that are described in
this information have an associated cross-reference for your convenience. The latest technical changes
are marked within >| and |< in the HTML version, or marked by vertical bars (|) in the left margin in the
PDF version.
For a complete list of new and improved features in Enterprise COBOL 6.2 and COBOL 6.2 with PTFs
installed, see What is new in Enterprise COBOL for z/OS 6.2 and COBOL 6.2 with PTFs installed in the
Enterprise COBOL for z/OS What's New.

Version 6 Release 2 with PTFs installed

New and changed compiler options

• The following compiler options are new:
– PI91584: COPYLOC: The new COPYLOC compiler option can be used to add either a PDSE (or PDS)
dataset or z/OS UNIX directory as an additional location to be searched for copy members during the
library phase. (“COPYLOC” on page 307)
– PH05855: INITIAL: The new INITIAL compiler option allows you to get a program that has initial
values in data items each time the program is called, without having to add the IS INITIAL clause
to the PROGRAM-ID paragraph, and without having to use dynamic CALL and CANCEL statements.
(“INITIAL” on page 325)
– PH31500: INVDATA: The new INVDATA compiler option replaces the deprecated ZONEDATA
compiler option and provides users fine-grained control over how the compiler generates code
to handle USAGE DISPLAY and USAGE PACKED-DECIMAL data items that contain invalid data.
(“INVDATA” on page 326)
• The following compiler options are modified:
– PI90571: ZONEDATA: The ZONEDATA option is updated to affect the behaviour of MOVE statements,
comparisons, and computations for USAGE DISPLAY or PACKED-DECIMAL data items that could
contain invalid digits, an invalid sign code, or invalid zone bits. (“ZONEDATA” on page 372)
– PI91585: RULES: New suboptions OMITODOMIN | NOOMITODOMIN are added to the RULES option
to control whether the compiler will issue warning messages for any OCCURS DEPENDING ON
clauses that are specified without integer-1 (the minimum number of occurrences). (“RULES” on page
350)
– PI91586: RULES: New suboptions UNREF | NOUNREFALL | NOUNREFSOURCE are added to the
RULES option to control whether the compiler will report unreferenced data items, and to control
whether the reporting is done only for data items not declared in a copy member (NOUNREFSOURCE)
or all data items (NOUNREFALL). (“RULES” on page 350)
– PI96135: NUMCHECK(PAC): For packed decimal (COMP-3) data items that have an even number of
digits, the unused bits are checked for zeros. (“NUMCHECK” on page 336)
– PI98480: NUMCHECK(ZON): New suboptions ALPHNUM | NOALPHNUM are added to the
NUMCHECK(ZON) option to control whether the compiler will generate code for an implicit numeric
class test for zoned decimal data items that are being compared with an alphanumeric data item,
alphanumeric literal or alphanumeric figurative constant. (“NUMCHECK” on page 336)
– PH04369: RULES(NOEVENPACK) will not issue messages for even-digit PACKED-DECIMAL data
items whose names start with DFH, DSN, EYU or SQL, that is, data items generated for/by CICS
and Db2®. (“RULES” on page 350)
– PH04485: TEST： New suboptions DSNAME | NODSNAME are added to the TEST|
NOTEST(SEPARATE) option to control whether the external file name, which is the SYSDEBUG
dataset name used during compilation, will or will not be stored in the object program. (“TEST”
on page 359)

Preface xxix
 – PH08642: NUMCHECK: Redundant checks previously added by the NUMCHECK option have been
removed, improving performance, and some checks can be done at compile time. Specifying
NUMCHECK may also cause the compiler to produce some messages at compile time instead of at
run time. (“NUMCHECK” on page 336)
– PH09225: INITCHECK: The INITCHECK option can be specified with OPTIMIZE(0). (“INITCHECK”
on page 323)
– PH11667: NUMCHECK(BIN): NUMCHECK(BIN) will check for binary data items (COMP, COMP-4, and
USAGE BINARY) even when TRUNC(BIN) is in effect. (“NUMCHECK” on page 336)
– PH24340: NUMCHECK(ZON): New suboptions LAXREDEF | STRICTREDEF are added to the
NUMCHECK(ZON) option to control whether the compiler will check and issue warning messages
for redefined items. (“NUMCHECK” on page 336)
– PH24413: INITCHECK: New suboptions LAX | STRICT are added to the INITCHECK option to
control whether the compiler will issue warning messages for data items unless they are initialized on
at least one, or on all, logical paths to a statement. (“INITCHECK” on page 323)
– PH26794: NUMCHECK(BIN): New suboptions TRUNCBIN | NOTRUNCBIN are added to the
NUMCHECK(BIN) option to control whether the compiler will generate the checking code for binary
data items. (“NUMCHECK” on page 336)
– PH28546: A new "CONVERTING" phrase is added to the JSON GENERATE and JSON PARSE
statements so that you can generate and parse JSON boolean values. (Chapter 31, “Producing JSON
output ,” on page 535 and Chapter 30, “Processing JSON input ,” on page 529)
Note that COBOL Runtime LE APAR PH26698 must also be applied on all systems where programs
that make use of this new feature are linked or run.
– PTF UI71111 (No APAR number): New functionality is added to NUMCHECK to check alphanumeric
senders whose contents are being moved to a numeric receiver. For alphanumeric senders whose
contents are being moved to a numeric receiver, the compiler treats the sender as a numeric integer
so NUMCHECK generates an implicit numeric class test for each alphanumeric sender. (“NUMCHECK”
on page 336)
– Runtime APAR PH20569(V2R2/V2R3/V2R4): The included DWARF diagnostic information when
TEST(NOSEPARATE) is in effect can be extracted from the LLA/VLF managed programs. (TEST)
– PH36688: RULES: New suboptions LAXREDEF | NOLAXREDEF are added to the RULES option to
inform users of redefined items with mismatched lengths. (“RULES” on page 350)
– PH36690: OFFSET: The OFFSET option behavior is changed. If there are multiple blocks of
instructions for a single line of COBOL code, multiple entries will be generated for those instructions
in the OFFSET table. (“OFFSET” on page 341)
– PH41362: NUMCHECK(ZON): LAXREDEF|STRICTREDEF is deprecated but is tolerated for
compatibility, and it is replaced by the LAX|STRICT option. (“NUMCHECK” on page 336)
– PH50301: NUMCHECK: The NUMCHECK compiler option is updated to avoid generating runtime
checking code of zoned decimal senders in MOVE statements when the receiver is an alphanumeric
data item and NUMCHECK(ZON(LAX)) is in effect. (“NUMCHECK” on page 336)
• The following compiler option is deprecated:
– PH31500: ZONEDATA: This compiler option is deprecated but tolerated and is automatically mapped
to an equivalent form of the new INVDATA compiler option. (“ZONEDATA” on page 372)

IBM-supplied CICS reserved-word table changes

• PI91589: New COBOL words are added to the IBM-supplied CICS reserved-word table. (“CICS
reserved-word table” on page 436)

Statement changes
• PI95081: A new LOC(24|31) phrase is added to the ALLOCATE statement to control the location of
dynamic storage that is acquired, which overrides the influence of the DATA compiler option. (“Storage
and its addressability” on page 39)

xxx Preface
Intrinsic function enhancements
• PI97434: Add support for processing national data items with the following intrinsic functions:
– REVERSE
– ULENGTH
– UPOS
– USUBSTR
– UWIDTH
(“Intrinsic functions and national data” on page 127)
If the updated intrinsic functions (REVERSE, ULENGTH, UPOS, USUBSTR, UWIDTH) in the May
compiler PTFs (UI56120, UI56121, UI56122) are used, then the May Runtime PTF UI56043(V2R1)/
UI56042(V2R2)/UI55861(V2R3) must also be applied to Language Environment on all systems where
these programs are linked or run.
• PI99703:
– The following intrinsic functions are added as IBM extensions:
- BIT-OF
- HEX-OF
(“Converting to hexadecimal or bit data (HEX-OF, BIT-OF)” on page 116)
– The following intrinsic functions are added as part of the 2014 COBOL Standard:
- E
- PI
- TRIM
If the new intrinsic functions (BIT-OF, HEX-OF, E, PI, TRIM) in the July compiler PTFs (UI57342,
UI57343, UI57344, UI57345) are used, then the July Runtime PTF UI57304(V2R1)/UI57303(V2R2)/
UI57302(V2R3) must also be applied to Language Environment on all systems where these programs
are linked or run.
• PH02183:
– The following intrinsic functions are added as IBM extensions:
- BIT-TO-CHAR
- HEX-TO-CHAR
(“Converting from hexadecimal or bit data (HEX-TO-CHAR, BIT-TO-CHAR)” on page 117)
– The following intrinsic functions are added as part of the 2014 COBOL Standard:
- ABS
- BYTE-LENGTH (“Finding the length of data items” on page 120)
- EXP
- EXP10
- NUMVAL-F
- SIGN
- TEST-NUMVAL
- TEST-NUMVAL-C
- TEST-NUMVAL-F
If the new intrinsic functions (BIT-TO-CHAR, HEX-TO-CHAR, NUMVAL-F, TEST-NUMVAL, TEST-NUMVAL-
C, TEST-NUMVAL-F) in the September compiler PTFs (UI58632, UI58633, UI58634) are used, then
the September Runtime PTF UI58596(V2R1)/UI58595(V2R2)/UI58603(V2R3) must also be applied to
Language Environment on all systems where these programs are linked or run.

Preface xxxi
 COBOL/JNI interface enhancement
Runtime APAR PH37101(V2R3/V2R4): An enhancement is made to assist COBOL programs running in
AMODE 31 to interact with Java™ programs in AMODE 64. (“COBOL programs in AMODE 31 interacting
with Java programs in AMODE 64” on page 467)
Note: IBM SDK, Java Technology Edition V8.0.6.35 (JVM) is needed for this enhancement.

Version 6 Release 2

New, changed, and removed compiler options

• The following compiler options are new:
– DEFINE (“DEFINE” on page 311)
– INITCHECK (“INITCHECK” on page 323)
– INLINE (“INLINE” on page 325)
– NUMCHECK (“NUMCHECK” on page 336)
– PARMCHECK (“PARMCHECK” on page 344)
• The following compiler options are modified:
– AFP: The default value is changed to AFP(NOVOLATILE). (“AFP” on page 298)
– ARCH: A new higher level of ARCH(12) is accepted. ARCH(7) is still the default. (“ARCH” on page
299)
– MAXPCF: The default value is changed to MAXPCF(100000) to reflect the increased capacity of the
V6 compiler. (“MAXPCF” on page 333)
– NOSTGOPT: In earlier versions, data items can get optimized with OPT(2) even when NOSTGOPT was
in effect. NOSTGOPT was changed in this version so that no optimization of storage or data items
occurs even with OPT(2). This is especially helpful for WORKING-STORAGE eye-catchers. (“STGOPT”
on page 357)
– SSRANGE: New suboptions MSG and ABD are added to the SSRANGE compiler option to control how
the compiler checks reference modification lengths. (“SSRANGE” on page 356)
– TEST: New suboptions SEPARATE and NOSEPARATE are added to the TEST compiler option
to control program object size on disk while retaining debugging capability. In addition, new
combinations of suboptions are supported in both the TEST and NOTEST compiler options, including
TEST(NODWARF), TEST(SEPARATE), and NOTEST(DWARF,SOURCE). (“TEST” on page 359)
• The following compiler option is removed:
– ZONECHECK is deprecated but is tolerated for compatibility, and it is replaced by NUMCHECK(ZON).
(“ZONECHECK” on page 371)

New statements
• The new JSON PARSE statement converts JSON text to COBOL data formats. (Chapter 30, “Processing
JSON input ,” on page 529)

Debugging changes
• TEST(SEPARATE) supports generating the debug information into side files to control module size
while retaining debugging capability. (“TEST” on page 359)

Listing changes
• Compiler diagnostic messages now appear at the end of the listing, as was the case in COBOL compilers
before Enterprise COBOL V5.

xxxii Preface
 • Addition of MD5 signature to program objects and debug data to allow matching of debug data with
executables even if a program is recompiled. (“Example: MD5 signature” on page 413)
• Three new fields are added at the end of PPA4:
– Offset of the first user-defined data item in WORKING-STORAGE.
– Total length of user-defined data items in WORKING-STORAGE.
– Bit to indicate whether there are EXTERNAL data items.
(“Example: Program prolog areas” on page 415)

Usability enhancements
• Improves usability of the compiler in the z/OS UNIX System Services environment with addition of help
information for the cob2 compiler invocation command. (“cob2 syntax and options” on page 277)

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, send your comments to:
[email protected].
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.

Preface xxxiii
xxxiv Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Part 1. Coding your program

© Copyright IBM Corp. 1991, 2023 1

2 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Chapter 1. Structuring your program

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” on page 3
“Describing the computing environment” on page 5
“Describing the data” on page 11
“Processing the data” on page 17
“Defining a class” on page 596
“Defining a class instance method” on page 600
“Structuring OO applications” on page 630

Identifying a program
Use the IDENTIFICATION DIVISION to name a program and optionally provide other identifying
information.
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 DIVISION.
Program-ID. Helloprog.
Author. A. Programmer.
Installation. Computing Laboratories.
Date-Written. 09/04/2017.
Date-Compiled. 09/08/2017.

Use the PROGRAM-ID paragraph to name your program. The program-name that you assign is used in
these ways:
• Other programs use that name to call your program.
• The name appears in the header on each page, except the first, of the program listing that is generated
when you compile the program.
• If you use the NAME compiler option, the name is placed on the NAME binder (linkage-editor) 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:
– AFB
– AFH
– CBC
– CEE
– CEH
– CEL
– CEQ
– CEU

© Copyright IBM Corp. 1991, 2023 3

 – 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” on page 4
“Marking a program as callable by containing programs” on page 4
“Setting a program to an initial state” on page 4

related references
Compiler limits (Enterprise COBOL for z/OS Language Reference)
Conventions for program-names (Enterprise COBOL for z/OS 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.
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.
Refer to the “Example: storage sections” on page 14, which shows that a recursive program uses both
WORKING-STORAGE and LOCAL-STORAGE.

related tasks
“Sharing data in recursive
or multithreaded programs” on page 16
“Making recursive calls” on page 485

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.
Only contained programs can have the COMMON attribute.

related concepts
“Nested programs” on page 483

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.
When a program is set to its initial state:
• Data items that have VALUE clauses are set to the specified values.

4 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 • Changed GO TO statements and PERFORM statements are in their initial states.
• Non-EXTERNAL files are closed.

related tasks
“Ending and reentering main programs or subprograms” on page 474
“Making static calls” on page 476
“Making dynamic calls” on page 476

related references
“INITIAL” on page 325

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.
The following example shows these five elements:

PP 5655-EC6 IBM Enterprise COBOL for z/OS 6.2.0 P170724 Date 09/08/2017 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.
Notes:
1. If you are using the IBM Enterprise COBOL Value Unit Edition for z/OS product, the header on the first
page of a source listing is the same as that for IBM Enterprise COBOL for z/OS. The product number
will show 5655-EC6 rather than 5697-V61. The 5697-V61 product number for the Value Unit Edition
product is only significant for product ordering purposes and product registration at installation time.
2. If you are using the IBM Enterprise COBOL Developer Trial for z/OS product, the header on the first
page of a source listing will show the product identifier and current release level of the Developer Trial
product.

related references
TITLE statement (Enterprise COBOL for z/OS 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.
Use the CONFIGURATION SECTION to specify the following items:
• Computer for compiling the program (in the SOURCE-COMPUTER paragraph)
• Computer for running the program (in the OBJECT-COMPUTER paragraph)
• Special items such as the currency sign and symbolic characters (in the SPECIAL-NAMES paragraph)
• User-defined classes (in the REPOSITORY paragraph)
Use the FILE-CONTROL and I-O-CONTROL paragraphs of the INPUT-OUTPUT SECTION to:
• Identify and describe the characteristics of the files in the program.
• 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.

Chapter 1. Structuring your program 5

 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.
• Provide information to control efficient transmission of the data records between your program and the
external medium.
“Example: FILE-CONTROL entries” on page 6

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 8

related references
Sections and paragraphs (Enterprise COBOL for z/OS 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 Line-sequential file

SELECT PRINTFILE1 SELECT COMMUTER-FILE1 SELECT PRINTFILE1

ASSIGN TO UPDPRINT2 ASSIGN TO COMMUTER2 ASSIGN TO UPDPRINT2
ORGANIZATION IS ORGANIZATION IS ORGANIZATION IS LINE
SEQUENTIAL3 INDEXED3 SEQUENTIAL3
ACCESS IS SEQUENTIAL.4 ACCESS IS RANDOM4 ACCESS IS SEQUENTIAL.4
RECORD KEY IS
COMMUTER-KEY5
FILE STATUS IS5
COMMUTER-FILE-
STATUS
COMMUTER-VSAM-
STATUS.

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 157
Chapter 10, “Processing VSAM files,” on page 179

6 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 Chapter 11, “Processing line-sequential files,” on page 205
“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.
These clauses specify the collating sequence for the following operations on alphanumeric items:
• Comparisons explicitly specified in relation conditions and condition-name conditions
• HIGH-VALUE and LOW-VALUE settings
• SEARCH ALL
• SORT and MERGE unless overridden by a COLLATING SEQUENCE phrase in the SORT or MERGE
statement
“Example: specifying the collating sequence” on page 7
The sequence that you use can be based on one of these alphabets:
• EBCDIC: references the collating sequence associated with the EBCDIC character set
• NATIVE: references the same collating sequence as EBCDIC
• 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)
• 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
• 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 221
“Comparing national (UTF-16)
data” on page 145

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. 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"

Chapter 1. Structuring your program 7

 "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'.
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.
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.)

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.
Depending on the operating system, this system data definition can take any of the following forms:
• DD statement for MVS JCL.
• ALLOCATE command under TSO.
• 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:
• JCL DD statement:

(1)

8 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 //OUTFILE DD DSNAME=MY.OUT171,UNIT=SYSDA,SPACE=(TRK,(50,5))
/*

• Environment variable (export command):

(1)
export OUTFILE=DSN(MY.OUT171),UNIT(SYSDA),SPACE(TRK,(50,5))

• 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:
• //OUTFILE DD DSNAME=OUT171 . . ., or
• 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 10

related references
“FILE SECTION entries” on page 12
FILE SECTION (Enterprise COBOL for z/OS Language Reference)

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.
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.

Chapter 1. Structuring your program 9

 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.

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.
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.
There is a record area allocated for file processing. However, due to buffer and device space optimization,
the record area may or may not contain the actual record data for processing by the program:
• The file processing occurs in the record area and the data in the record area can be accessed by the
program if one of the following is true:
– The file is EXTERNAL
– The file is contained in a "SAME RECORD AREA" statement in the I-O-CONTROL section
– The program is compiled with the AWO compiler option
• The file processing typically occurs in a buffer and the data in the record area is not guaranteed to be
accessible by the program (storage undefined) if all of the following is true:
– The file is not EXTERNAL
– The file is not contained in a "SAME RECORD AREA" statement in the I-O-CONTROL section

10 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 – The program is compiled with the NOAWO compiler option
Therefore, programs should not reference data directly in the file's record area. Instead, when a file
record is read in, it should be read into a data item defined in WORKING-STORAGE or if read into the
record area, should be immediately moved to a data item in WORKING-STORAGE for use by the program.
For example:

FD MY-INPUT-FILE
LABEL RECORDS ARE STANDARD
RECORDING MODE IS V
BLOCK CONTAINS 0 RECORDS
DATA RECORD IS IN-RECORD-AREA.
01 IN-RECORD-AREA PIC X(100).

WORKING-STORAGE.
01 WS-IN-RECORD-AREA PIC X(100).

PROCEDURE DIVISION.
...
READ MY-INPUT-FILE INTO WS-IN-RECORD-AREA.

related references
“AWO” on page 302

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.
You can use these sections for defining the following types of data:
• Data used in input-output operations: FILE SECTION
• 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
• 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 11
“Using data from another program” on page 16

related references
Compiler limits (Enterprise COBOL for z/OS Language Reference)

Using data in input and output operations

Define the data that you use in input and output operations in the FILE SECTION.
Provide the following information about the data:
• 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.

Chapter 1. Structuring your program 11

 • 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 483

related tasks
“Sharing files between programs
(external files)” on page 501

related references
“FILE SECTION entries” on page 12

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 Must match file-name in the SELECT clause. file-
to in PROCEDURE DIVISION name is associated with a ddname through the
input-output statements assignment-name.
(OPEN, CLOSE, READ, also
START and DELETE for VSAM)

12 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Table 2. FILE SECTION entries (continued)
Clause To define Notes
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 Size of logical records (fixed Integer size indicates the number of bytes in a
CONTAINS n length) 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 Size of logical records Integer size or sizes, if specified, indicate the
VARYING (variable length) 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 Size of logical records The integer sizes indicate the number of bytes
CONTAINS n TO m (variable length) 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
VALUE OF An item in the label records Comments only
associated with file
DATA RECORDS Names of records associated Comments only
with file
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.

Chapter 1. Structuring your program 13

 Table 2. FILE SECTION entries (continued)
Clause To define Notes
RECORDING MODE Physical record description QSAM only

related references
FILE SECTION (Enterprise COBOL for z/OS 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:
• 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.
• 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.
“Example: storage sections” on page 14

related tasks
“Ending and reentering main programs or subprograms” on page 474
Chapter 28, “Preparing COBOL programs
for multithreading,” on page 517
“WORKING-STORAGE SECTION for defining class instance data” on page 599

related references
WORKING-STORAGE SECTION (Enterprise COBOL for z/OS Language Reference)
LOCAL-STORAGE SECTION (Enterprise COBOL for z/OS 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.

14 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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! = 00000001
0001! = 00000001
0002! = 00000002
0003! = 00000006
0004! = 00000024
0005! = 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 Value for numb in Value for fact in
LOCAL-STORAGE WORKING-STORAGE WORKING-STORAGE
Main 5 5 0
1 4 4 0
2 3 3 0
3 2 2 0
4 1 1 0
5 0 0 0

Gobacks Value for num in Value for numb in Value for fact in
LOCAL-STORAGE WORKING-STORAGE 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

Chapter 1. Structuring your program 15

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.

related tasks
“Sharing data in separately compiled programs” on page 16
“Sharing data in nested programs” on page 16
“Sharing data in recursive
or multithreaded programs” on page 16
“Passing data” on page 491

Sharing data in separately compiled programs

Many applications consist of separately compiled programs that call and pass data to one another. Use
the LINKAGE SECTION in the called program to describe the data passed from another program.
In the calling program, code a CALL . . . USING or INVOKE . . . USING statement to pass the
data.

related tasks
“Passing data” on page 491
“Coding the LINKAGE SECTION” on page 495

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 clause. The GLOBAL clause specifies that a data-name is
available to every program contained within the program that defines it, as long as the contained program
does not itself have a definition for that name.
A nested program cannot access data items in a sibling program (one at the same nesting level in the
same containing program), but they can both refer to data items defined with the EXTERNAL clause or
data items in the containing program if they are defined with the GLOBAL clause.

related concepts
“Nested programs” on page 483

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.
To address a record in the LINKAGE SECTION, use either of these techniques:
• Pass an argument to the program and specify the record in an appropriate position in the USING phrase
in the program.
• 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 517

related tasks
“Making recursive calls” on page 485
“Processing files with multithreading” on page 520

16 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 related references
“THREAD” on page 363
SET statement (Enterprise COBOL for z/OS 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.
The PROCEDURE DIVISION begins with the division header and a procedure-name header. The division
header for a program can simply be:

PROCEDURE DIVISION.

You can code 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” on page 18

related tasks
“Coding the LINKAGE SECTION” on page 495
“Coding the PROCEDURE DIVISION
for passing arguments” on page 496
“Using PROCEDURE DIVISION RETURNING . . .” on page 500
“Eliminating repetitive coding” on page 683

related references
The procedure division header (Enterprise COBOL for z/OS Language Reference)
The USING phrase (Enterprise COBOL for z/OS Language Reference)
CALL statement (Enterprise COBOL for z/OS Language Reference)

Chapter 1. Structuring your program 17

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.
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 statement. 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 19
“Scope terminators” on page 20
“Imperative statements” on page 18
“Conditional statements” on page 18
“Declaratives” on page 21

related references
PROCEDURE DIVISION structure
(Enterprise COBOL for z/OS 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” on page 18
“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).

18 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
You can use a delimited scope statement in these ways:
• 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.
• To code a conditional statement where the COBOL syntax calls for an imperative statement
For example, code a conditional statement as the object of an inline PERFORM:

PERFORM UNTIL TRANSACTION-EOF

PERFORM 200-EDIT-UPDATE-TRANSACTION
IF NO-ERRORS
PERFORM 300-UPDATE-COMMUTER-RECORD
ELSE
PERFORM 400-PRINT-TRANSACTION-ERRORS
END-IF
READ UPDATE-TRANSACTION-FILE INTO WS-TRANSACTION-RECORD
AT END
SET TRANSACTION-EOF TO TRUE
END-READ
END-PERFORM

An explicit scope terminator is required for the inline PERFORM statement, but it is not valid for the
out-of-line PERFORM statement.
For additional program control, you can use the NOT phrase with conditional statements. For example, you
can provide instructions to be performed when a particular exception does not occur, such as NOT ON
SIZE ERROR. The NOT phrase cannot be used with the ON OVERFLOW phrase of the CALL statement, but
it can be used with the ON EXCEPTION phrase.
Do not nest conditional statements. Nested statements must be imperative statements (or delimited
scope statements) and must follow the rules for imperative statements.
The following statements are examples of conditional statements if they are coded without scope
terminators:
• Arithmetic statement with ON SIZE ERROR
• Data-manipulation statements with ON OVERFLOW
• CALL statements with ON OVERFLOW
• I/O statements with INVALID KEY, AT END, or AT END-OF-PAGE
• RETURN with AT END

related concepts
“Imperative statements” on page 18
“Scope terminators” on page 20
related tasks
“Selecting program actions” on page 91

related references
Conditional statements (Enterprise COBOL for z/OS 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 377
Compiler-directing statements (Enterprise COBOL for z/OS Language Reference)

Chapter 1. Structuring your program 19

 Scope terminators
A scope terminator ends a statement. Scope terminators can be explicit or implicit.
Explicit scope terminators end a statement without ending a sentence. They consist of END followed by a
hyphen and the name of the statement 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

20 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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 18
“Imperative statements” on page 18

Declaratives
Declaratives provide one or more special-purpose sections that are executed when an exception
condition occurs.
Start each declarative section with a USE statement that identifies the function of the section. In the
procedures, specify the actions to be taken when the condition occurs.

related tasks
“Finding and handling input-output
errors” on page 383

related references
Declaratives (Enterprise COBOL for z/OS Language Reference)

Chapter 1. Structuring your program 21

22 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Chapter 2. Using data

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 39

related tasks
“Using variables, structures, literals, and constants” on page 23
“Assigning values to data items” on page 27
“Displaying values on a
screen or in a file (DISPLAY)” on page 35
“Using intrinsic functions (built-in functions)” on page 38
“Using tables (arrays) and pointers” on page 39
Chapter 7, “Processing data in an international
environment,” on page 123

Using variables, structures, literals, and constants

Most high-level programming languages share the concept of data being represented as variables (data
items), structures (group items), literals, or constants.
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 variables” on page 23
“Using data items and group
items” on page 24
“Using literals” on page 25
“Using constants” on page 26
“Using figurative constants” on page 26

related references
Classes and categories of data (Enterprise COBOL for z/OS 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.
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:

Data Division.
01 Customer-Name Pic X(20).
01 Original-Customer-Name Pic X(20).
. . .
Procedure Division.
Move Customer-Name to Original-Customer-Name
. . .

© Copyright IBM Corp. 1991, 2023 23

 You could instead define 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 129

related tasks
“Using national data (Unicode)
in COBOL” on page 129

related references
“NSYMBOL” on page 335
“Storage of character data” on page 136
PICTURE clause (Enterprise COBOL for z/OS 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.
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).
. . .
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.

24 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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 129
“National groups” on page 132

related tasks
“Using national data (Unicode)
in COBOL” on page 129
“Using national groups” on page 133

related references
“FILE SECTION entries” on page 12
“Storage of character data” on page 136
Classes and categories of group items
(Enterprise COBOL for z/OS Language Reference)
PICTURE clause (Enterprise COBOL for z/OS Language Reference)
MOVE statement (Enterprise COBOL for z/OS Language Reference)
USAGE clause (Enterprise COBOL for z/OS Language Reference)

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.
You do not need to define 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"

Chapter 2. Using data 25

 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 129

related tasks
“Using national literals” on page 130
“Using DBCS literals” on page 148

related references
“NSYMBOL” on page 335
Literals (Enterprise COBOL for z/OS 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).

Data Division.
01 Report-Header pic x(50) value "Company Sales Report".
. . .
01 Interest 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.

related tasks
“Using national data (Unicode)
in COBOL” on page 129
“Coding for use of DBCS support” on page 147

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.
For example:

Move Spaces To Report-Header

related tasks
“Using national-character
figurative constants” on page 131
“Coding for use of DBCS support” on page 147

related references
Figurative constants (Enterprise COBOL for z/OS Language Reference)

26 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Assigning values to data items
After you have defined a data item, you can assign a value to it at any time. Assignment takes many forms
in COBOL, depending on what you want to do.

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:
• INITIALIZE statement
• MOVE statement
• STRING or UNSTRING statement
• 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 Use the INSPECT statement.
data 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.
One of these actions: Use the SET statement.
• Place a value associated with a table element in an index.
• Set the status of an external switch to ON or OFF.
• Move data to a condition-name to make the condition
true.
• Set a POINTER, PROCEDURE-POINTER, or FUNCTION-
POINTER data item to an address.
• Associate an OBJECT REFERENCE data item with an
object instance.

“Examples: initializing data items” on page 28

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 103
“Splitting data items (UNSTRING)” on page 105
“Assigning arithmetic results

Chapter 2. Using data 27

 (MOVE or COMPUTE)” on page 34
“Tallying and replacing
data items (INSPECT)” on page 112
Chapter 7, “Processing data in an international
environment,” on page 123

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

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

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".

28 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 . . .
INITIALIZE ANJUST
REPLACING ALPHANUMERIC DATA BY ALPHABETIC-1

ALPHABETIC-1 ANJUST before ANJUST after

ABCD bbbbbbbb1 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 ALPHANUM-EDIT-1 before ALPHANUM-EDIT-1 after

M/bb1 ABbC/DEF1 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
INITIALIZE NATIONAL-1 NATIONAL TO VALUE

NATIONAL-3 NATIONAL-1 before NATIONAL-1 after first NATIONAL-1 after

first INITIALIZE INITIALIZE second INITIALIZE
004300441 004100422 004300441 004100422

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'

Chapter 2. Using data 29

 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 NAT-DEC-1 before NAT-DEC-1 after

12 0039003800371 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-EDITED 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:

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-EDITED DATA BY NUM-NATL-3

NUM-NATL-3 NUM-EDIT-NATL-1 before NUM-EDIT-NATL-1 after

0030003100321 00240031003200372 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

30 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 (INITIALIZE)” on page 31
“Initializing a table (INITIALIZE)” on page 73
“Defining numeric data” on page 43

related references
“NSYMBOL” on page 335

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.
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 PIC X.
05 PART-NUMBER PIC 9(6).
05 TRANSACTION-QUANTITY PIC 9(5).
05 PRICE-FIELDS.
10 UNIT-PRICE PIC 9(5)V9(2).
10 DISCOUNT PIC V9(2).
10 SALES-PRICE PIC 9(5)V9(2).
. . .
INITIALIZE TRANSACTION-OUT

Record 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.

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 NATIONAL.

05 TRANSACTION-CODE PIC N.
05 PART-NUMBER PIC 9(6).
05 TRANSACTION-QUANTITY PIC 9(5).
05 PRICE-FIELDS.
10 UNIT-PRICE PIC 9(5)V9(2).
10 DISCOUNT PIC V9(2).
10 SALES-PRICE PIC 9(5)V9(2).
. . .
INITIALIZE TRANSACTION-OUT

Regardless of the previous contents of the transaction record, after the INITIALIZE statement above is
executed:
• TRANSACTION-CODE contains NX"0020" (a national space).
• Each of the remaining 27 national character positions of TRANSACTION-OUT contains NX"0030" (a
national-decimal zero).

Chapter 2. Using data 31

 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:
• SPACE is the implied sending item for alphabetic, alphanumeric, alphanumeric-edited, DBCS, category
national, and national-edited receiving items.
• ZERO is the implied sending item for numeric and numeric-edited receiving items.

related concepts
“National groups” on page 132

related tasks
“Initializing a table (INITIALIZE)” on page 73
“Using national groups” on page 133

related references
INITIALIZE statement (Enterprise COBOL for z/OS Language Reference)

Assigning values to elementary data items (MOVE)

Use a MOVE statement to assign a value to an elementary data item.
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.
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

32 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 related concepts
“Unicode and the encoding
of language characters” on page 129

related tasks
“Assigning values to group
data items (MOVE)” on page 33
“Converting to or from national (Unicode) representation” on page 136

related references
“CODEPAGE” on page 304
Classes and categories of data (Enterprise COBOL for z/OS Language Reference)
MOVE statement (Enterprise COBOL for z/OS Language Reference)

Assigning values to group data items (MOVE)

Use the MOVE statement to assign values to group data items.

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.
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 129
“National groups” on page 132

Chapter 2. Using data 33

 related tasks
“Assigning values to elementary
data items (MOVE)” on page 32
“Using national groups” on page 133
“Converting to or from national (Unicode) representation” on page 136

related references
Classes and categories of group items
(Enterprise COBOL for z/OS Language Reference)
MOVE statement (Enterprise COBOL for z/OS Language Reference)
CORRESPONDING phrase (Enterprise COBOL for z/OS 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.

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 312

34 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 Intrinsic functions (Enterprise COBOL for z/OS 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.
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:

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:
• 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 129

related tasks
“Converting alphanumeric
or DBCS to national (NATIONAL-OF)” on page 138

related references
“CODEPAGE” on page 304
ACCEPT statement (Enterprise COBOL for z/OS Language Reference)
SPECIAL-NAMES paragraph (Enterprise COBOL for z/OS 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.

Display "No entry for surname '" Customer-Name "' found in the file.".

Chapter 2. Using data 35

 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.

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 129

related tasks
“Displaying data on the
system logical output device” on page 36
“Using WITH NO ADVANCING” on page 37
“Converting national to
alphanumeric (DISPLAY-OF)” on page 138
“Coding COBOL programs to run under CICS” on page 429

related references
“CODEPAGE” on page 304
DISPLAY statement (Enterprise COBOL for z/OS 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.

Display "Hello" upon sysout.

36 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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:
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 460
related references
“OUTDD” on page 344
DISPLAY statement (Enterprise COBOL for z/OS 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.
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 "ABC"
DISPLAY "CDEF" WITH NO ADVANCING
DISPLAY "GHIJK" WITH NO ADVANCING
DISPLAY "LMNOPQ"
DISPLAY "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.
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 for z/OS Language Reference)

Chapter 2. Using data 37

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.
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 value 2.
01 y Pic 99 value 4.
01 z Pic 99 value 0.
01 Sqrt Pic 99 value 0.
. . .
Compute Sqrt = 16 ** .5
Compute z = x + Function 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.
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 87
“Converting data items (intrinsic functions)” on page 113
“Evaluating data items (intrinsic functions)” on page 117

38 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Using tables (arrays) and pointers
In COBOL, arrays are called tables. A table is a set of logically consecutive data items that you define in
the DATA DIVISION by using the OCCURS clause.
Pointers are data items that contain virtual storage addresses. You define them 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:
• Pass them between programs by using the CALL . . . BY REFERENCE statement.
• Set a pointer to allocated storage or free storage by using the ALLOCATE and FREE statements.
• Move them to other pointers by using the SET statement.
• Compare them to other pointers for equality by using a relation condition.
• Initialize them to contain an invalid address by using VALUE IS NULL.
Use pointer data items to:
• 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.
• Handle a chained list.
related tasks
“Defining a table (OCCURS)” on page 67
“Using procedure and function
pointers” on page 485

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.
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: 24-bit addressing, 31-bit addressing, or either 24-bit or 31-bit addressing. These attributes are
AMODE 24, AMODE 31, and AMODE ANY, respectively. The program object and the executing program
each have an AMODE attribute. Enterprise COBOL V5.1.1 object programs are either AMODE MIN for cases
where AMODE 24 is possible, or AMODE 31 in all other cases. See “Restrictions for AMODE” on page 40.
Residency mode (RMODE) is the attribute of a program object 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.

Chapter 2. Using data 39

 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 when the COBOL program is compiled with the RENT option and is in
one of the following cases:
• Compiled with Enterprise COBOL V4.2 or earlier releases
• Compiled with the DATA(24) compiler option
• Running in CICS
• A COBOL V5.1.1 or later program in a program object that contains only COBOL programs (except
COBOL 5.1.0) and assembler. There are no Language Environment interlanguage calls within the
program object and no COBOL V5.1.0 programs.
• A COBOL V5 program in a program object where the main entry point is COBOL V5. In this case, the
program object can contain Language Environment interlanguage calls, with COBOL statically linking
with C, C++ or PL/I. All COBOL V5 programs within such program objects (even if they are not the
main entry point) have their WORKING-STORAGE allocated from heap storage.
• A COBOL V6.1 or later program
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.

Restrictions for AMODE

AMODE 24 execution is not supported in the following cases, and the applications must run in AMODE 31.
This is the same set of AMODE 24 restrictions as COBOL V3 and V4.
• Programs containing XML PARSE statements
• Programs containing XML GENERATE statements
• Program objects containing COBOL bound together with C, C++, or PL/I programs, and communicating
via static CALL
• Programs containing object-oriented language syntax, such as INVOKE statements, or object-oriented
class definitions
• Programs compiled with any of the following compiler options:
– DLL
– PGMNAME(LONGUPPER)
– PGMNAME(LONGMIXED)
• Multithreaded applications
Note: A program compiled with the THREAD option can run in AMODE 24, but only in an application that
does not have multiple threads or PL/I tasks.
• Programs run from the z/OS UNIX file system
Note: An AMODE 31 driver program resident in the z/OS UNIX file system can contain a dynamic call to
an AMODE 24 program module resident in an MVS PDSE.
• Programs used as COBOL compiler exit modules that are specified on the EXIT compiler option
• Language Environment enclaves that use XPLINK, including either the enclaves that contain non-
COBOL programs compiled with the XPLINK compiler option, or run with the XPLINK runtime option
Note: To run COBOL programs with addressing mode 24, you must compile all COBOL programs
with Enterprise COBOL V5.1.1, or later versions; or Enterprise COBOL V4.2 or earlier versions. If any
component of a program object is compiled with Enterprise COBOL V5.1.0, the program object must run

40 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
in addressing mode 31. COBOL programs that run with addressing mode 24 must be linked with the
binder option RMODE(24).

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.

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.

Storage restrictions for passing data

Do not pass parameters that are allocated in storage above the 16 MB line to AMODE 24 subprograms.
Force the WORKING-STORAGE data and parameter lists below the line for programs that run in 31-bit
addressing mode and pass data to programs that run in AMODE 24:
• Compile with the RENT and DATA(24) compiler options, or if the WORKING-STORAGE is on the HEAP
(see previous description of the HEAP option), run them with the HEAP(,,BELOW) runtime option.
• Compile with the NORENT compiler option.

Location of data areas

For reentrant programs, the DATA compiler option, and the HEAP runtime option control 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 and RMODE(ANY) or RMODE(AUTO) 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 that are compiled with NORENT.

Storage for LOCAL-STORAGE data

The location of LOCAL-STORAGE data items is controlled by the STACK runtime option and the
AMODE of the program. LOCAL-STORAGE data items are acquired in unrestricted storage when the
STACK(,,ANYWHERE) runtime option is in effect and the program is running in AMODE 31. 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

Chapter 2. Using data 41

 data is obtained. Storage required for EXTERNAL data is obtained from unrestricted storage if the
following conditions are met:
• The program is compiled with the DATA(31) and RENT compiler options.
• The HEAP(,,ANYWHERE) runtime option is in effect.
• 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.

Storage for ALLOCATE statement

The DATA compiler option setting influences how ALLOCATE acquires storage:
• If DATA(24) is in effect and the LOC 31 phrase of the ALLOCATE statement is not specified, ALLOCATE
acquires storage from below the 16 MB line.
• If DATA(31) is in effect and the LOC 24 phrase of the ALLOCATE statement is not specified, ALLOCATE
will attempt to acquire storage from above the 16 MB line.

related concepts
“AMODE switching” on page 478
AMODE considerations for heap storage
(Language Environment Programming Guide)

related tasks
Chapter 25, “Using subprograms,” on page 473
Chapter 26, “Sharing data,” on page 491

related references
“Allocation of buffers for QSAM files” on page 176
“Allocation of record areas for VSAM files” on page 201
“DATA” on page 310
“RENT” on page 348
“RMODE” on page 349
“Performance-related compiler options” on page 676
ALLOCATE statement (Enterprise COBOL for z/OS Language Reference)
HEAP, STACK, ALL31 (Language Environment Programming Reference)
MVS Program Management: User's Guide and Reference

42 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Chapter 3. Working with numbers and arithmetic

In general, you can view COBOL numeric data as a series of decimal digit positions. However, numeric
items can also have special properties such as an arithmetic sign or a currency sign.
To define, display, and store numeric data so that you can perform arithmetic operations efficiently:
• Use the PICTURE clause and the characters 9, +, -, P, S, and V to define numeric data.
• Use the PICTURE clause and editing characters (such as Z, comma, and period) along with MOVE and
DISPLAY statements to display numeric data.
• Use the USAGE clause with various formats to control how numeric data is stored.
• Use the numeric class test to validate that data values are appropriate.
• Use ADD, SUBTRACT, MULTIPLY, DIVIDE, and COMPUTE statements to perform arithmetic.
• Use the CURRENCY SIGN clause and appropriate PICTURE characters to designate the currency you
want.

related tasks
“Defining numeric data” on page 43
“Displaying numeric data” on page 45
“Controlling how numeric data is stored” on page 46
“Checking for incompatible data (numeric class test)” on page 53
“Performing arithmetic” on page 55
“Using currency signs” on page 64

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.
For example, Count-y below is a numeric data item, an external decimal item that has USAGE DISPLAY
(a zoned decimal item):

05 Count-y Pic 9(4) Value 25.

05 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.
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

© Copyright IBM Corp. 1991, 2023 43

 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 50
related concepts
“Formats for numeric
data” on page 47
Appendix A, “Intermediate results and arithmetic precision,” on page 691

related tasks
“Displaying numeric data” on page 45
“Controlling how numeric data is stored” on page 46
“Performing arithmetic” on page 55
“Defining national numeric
data items” on page 132

related references
“Sign representation of zoned and packed-decimal data” on page 53
“Storage of character data” on page 136
“ARITH” on page 300
“NUMPROC” on page 340
SIGN clause (Enterprise COBOL for z/OS Language Reference)

44 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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.
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, define 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 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

Chapter 3. Working with numbers and arithmetic 45

 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 50

related tasks
“Displaying values on a
screen or in a file (DISPLAY)” on page 35
“Controlling how numeric data is stored” on page 46
“Defining numeric data” on page 43
“Performing arithmetic” on page 55
“Defining national numeric
data items” on page 132
“Converting to or from national (Unicode) representation” on page 136

related references
MOVE statement (Enterprise COBOL for z/OS Language Reference)
BLANK WHEN ZERO clause (Enterprise COBOL for z/OS Language Reference)

Controlling how numeric data is stored

You can control how the computer stores numeric data items by coding the USAGE clause in your data
description entries.
You might want to control the format for any of several reasons such as these:
• Arithmetic performed with computational data types is more efficient than with USAGE DISPLAY or
USAGE NATIONAL data types.
• Packed-decimal format requires less storage per digit than USAGE DISPLAY or USAGE NATIONAL data
types.
• Packed-decimal format converts to and from DISPLAY or NATIONAL format more efficiently than binary
format does.
• Floating-point format is well suited for arithmetic operands and results with widely varying scale, while
maintaining the maximal number of significant digits.
• 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:
• 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)
• 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.

46 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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 50

related concepts
“Formats for numeric
data” on page 47
“Data format conversions” on page 51
Appendix A, “Intermediate results and arithmetic precision,” on page 691

related tasks
“Defining numeric data” on page 43
“Displaying numeric data” on page 45
“Performing arithmetic” on page 55

related references
“Conversions and precision” on page 52
“Sign representation of zoned and packed-decimal data” on page 53

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 must only contain valid UTF-16 digits. If they do not, the data is illegal and the behaviour of
the generated code is undefined. External decimal items that have USAGE NATIONAL are referred to as
national decimal data items.
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

Chapter 3. Working with numbers and arithmetic 47

 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.

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 define 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.

48 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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 Binary doubleword (8 bytes) -9,223,372,036,854,775,808 through
S9(18) +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.
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 for z/OS 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 129
Appendix A, “Intermediate results and arithmetic precision,” on page 691

related tasks
“Defining numeric data” on page 43
“Defining national numeric
data items” on page 132

related references
“Storage of character data” on page 136
“TRUNC” on page 364
Classes and categories of data (Enterprise COBOL for z/OS Language Reference)
SIGN clause (Enterprise COBOL for z/OS Language Reference)
VALUE clause (Enterprise COBOL for z/OS Language Reference)

Chapter 3. Working with numbers and arithmetic 49

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 Value Internal representation
optional SIGN clause
External PIC S9999 DISPLAY + 1234 F1 F2 F3 C4
decimal
- 1234 F1 F2 F3 D4
1234 F1 F2 F3 C4
PIC 9999 DISPLAY 1234 F1 F2 F3 F4
PIC 9999 NATIONAL 1234 00 31 00 32 00 33 00 34
+ 1234 C1 F2 F3 F4
PIC S9999 DISPLAY - 1234 D1 F2 F3 F4
SIGN LEADING

+ 1234 4E F1 F2 F3 F4
PIC S9999 DISPLAY - 1234 60 F1 F2 F3 F4
SIGN LEADING SEPARATE

+ 1234 F1 F2 F3 F4 4E
PIC S9999 DISPLAY - 1234 F1 F2 F3 F4 60
SIGN TRAILING
SEPARATE

+ 1234 00 2B 00 31 00 32 00 33 00
34
PIC S9999 NATIONAL
SIGN LEADING - 1234 00 2D 00 31 00 32 00 33 00
SEPARATE 34

+ 1234 00 31 00 32 00 33 00 34 00
2B
PIC S9999 NATIONAL
SIGN TRAILING - 1234 00 31 00 32 00 33 00 34 00
SEPARATE 2D

Binary + 1234 04 D2
PIC S9999 BINARY - 1234 FB 2E
PIC S9999 COMP
PIC S9999 COMP-4

PIC S9999 COMP-5 + 123451 30 39

- 123451 CF C7
1234 04 D2
PIC 9999 BINARY
PIC 9999 COMP
PIC 9999 COMP-4

PIC 9999 COMP-5 600001 EA 60

50 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Table 6. Internal representation of numeric items (continued)
Numeric type PICTURE and USAGE and Value Internal representation
optional SIGN clause
Internal + 1234 01 23 4C
decimal PIC S9999 PACKED- - 1234 01 23 4D
DECIMAL
PIC S9999 COMP-3

1234 01 23 4F
PIC 9999 PACKED-
DECIMAL
PIC 9999 COMP-3

Internal COMP-1 + 1234 43 4D 20 00

floating point
- 1234 C3 4D 20 00
COMP-2 + 1234 43 4D 20 00 00 00 00 00
- 1234 C3 4D 20 00 00 00 00 00
External PIC +9(2).9(2)E+99 + 12.34E+02 4E F1 F2 4B F3 F4 C5 4E F0
floating point DISPLAY F2
- 12.34E+02 60 F1 F2 4B F3 F4 C5 4E F0
F2
PIC +9(2).9(2)E+99 + 12.34E+02
NATIONAL 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

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.

Chapter 3. Working with numbers and arithmetic 51

 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” on page 52
“Sign representation of zoned and packed-decimal data” on page 53

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.

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.

52 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 related concepts
Appendix A, “Intermediate results and arithmetic precision,” on page 691

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

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 340
“ZWB” on page 375

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.
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.

Chapter 3. Working with numbers and arithmetic 53

 You can use the numeric class test to perform data validation. For example:

Linkage Section.
01 Count-x Pic 999.
. . .
Procedure Division Using Count-x.
If Count-x is numeric then display "Data is good"

The numeric class test checks the contents of a data item against a set of values that are valid for the
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). An external decimal data item that has USAGE DISPLAY is checked for
hexadecimal values X'0' through X'9' in the digit positions (the lower 4 bits of each byte), for a valid
zone code in the upper 4 bits of each byte and for a valid sign value in the sign position (whether separate
or nonseparate). The sign code is in the upper 4 bits of the sign byte or in a separate byte if SIGN IS
SEPARATE was specified. If the SIGN IS SEPARATE clause is used, the upper four bits of all bytes must
be x'F'.
Note: Although the INVDATA compiler option allows toleration of invalid zone codes in USAGE DISPLAY
numeric (zoned decimal) data items in numeric comparisons, invalid zone codes in zoned decimal data
items will be treated as nonnumeric by the numeric class test.
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)

For more information about numeric class condition, see Class condition in the Enterprise COBOL for z/OS
Language Reference.
You can also use the NUMCHECK(ZON,PAC) option to have the compiler generate implicit numeric class
tests for zoned decimal (numeric USAGE DISPLAY) and packed decimal (COMP-3) data items that are
used as sending data items. This numeric class test validates data and also validates sign fields against
the NUMPROC compiler option to help you decide whether you can use NUMPROC(PFD) or not. For details,
see “NUMCHECK” on page 336.
For more information about other invalid data issues, in particular for COBOL migration purposes, see the
FAQ about invalid data in the Enterprise COBOL Migration Guide.

54 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 related references
“NUMCHECK” on page 336
“NUMPROC” on page 340
“INVDATA” on page 326

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.
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 55
“Using arithmetic expressions” on page 56
“Using numeric intrinsic functions” on page 56
“Using math-oriented callable services” on page 58
“Using date callable services” on page 59

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.
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 = Subtract Overdraft from Balance

Balance - Overdraft

Compute IncrementOne = Add 1 to IncrementOne,

IncrementOne + 1 IncrementTwo,
Compute IncrementTwo = IncrementThree
IncrementTwo + 1
Compute IncrementThree =
IncrementThree + 1

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.

Chapter 3. Working with numbers and arithmetic 55

 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 62
Appendix A, “Intermediate results and arithmetic precision,” on page 691

related tasks
“Defining numeric data” on page 43

Using arithmetic expressions

You can use arithmetic expressions in many (but not all) places in statements where numeric data items
are allowed.
For example, you can use arithmetic expressions as comparands in relation conditions:

If (a + b) > (c - d + 5) Then. . .

Arithmetic expressions can consist of a single numeric literal, a single numeric data item, or a single
intrinsic function reference. They can also consist of several of these items connected by arithmetic
operators.
Arithmetic operators are evaluated in the following order of precedence:

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 62
Appendix A, “Intermediate results and arithmetic precision,” on page 691

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.
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

56 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.

Table 10. Numeric intrinsic functions

Number Date and time Finance Mathematics Statistics
handling

LENGTH CURRENT-DATE ANNUITY ABS MEAN

MAX DATE-OF-INTEGER PRESENT-VALUE ACOS MEDIAN
MIN DATE-TO-YYYYMMDD ASIN MIDRANGE
NUMVAL DAY-OF-INTEGER ATAN RANDOM
NUMVAL-C DAY-TO-YYYYDDD COS RANGE
NUMVAL-F INTEGER-OF-DATE E STANDARD-DEVIATION
SIGN INTEGER-OF-DAY EXP VARIANCE
TEST-NUMVAL WHEN-COMPILED EXP10
TEST- YEAR-TO-YYYY FACTORIAL
NUMVAL-C INTEGER
TEST- INTEGER-PART
NUMVAL-F LOG
ORD-MAX LOG10
ORD-MIN MOD
PI
REM
SIN
SQRT
SUM
TAN

“Examples: numeric intrinsic functions” on page 60

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 62
Appendix A, “Intermediate results and arithmetic precision,” on page 691

Chapter 3. Working with numbers and arithmetic 57

 related references
“ARITH” on page 300

Using math-oriented callable services

Most COBOL intrinsic functions have corresponding math-oriented callable services that you can use to
produce the same results.
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 Corresponding long- Corresponding extended- Results same for intrinsic
function precision Language precision Language function and callable
Environment callable Environment callable service?
service service
ACOS CEESDACS CEESQACS Yes
ASIN CEESDASN CEESQASN Yes
ATAN CEESDATN CEESQATN Yes
COS CEESDCOS CEESQCOS Yes
E CEESDEXP with parm1 set CEESQEXP with parm1 set Yes
to 1.0 to 1.0
EXP CEESDEXP CEESQEXP Yes
EXP10 CEESDXPD with parm1 set CEESQXPQ with parm1 set Yes
to 10.0 to 10.0
LOG CEESDLOG CEESQLOG Yes
LOG10 CEESDLG1 CEESQLG1 Yes
RANDOM1 CEERAN0 none No
REM CEESDMOD CEESQMOD Yes
SIN CEESDSIN CEESQSIN Yes
SQRT CEESDSQT CEESQSQT Yes
TAN CEESDTAN CEESQTAN Yes

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,

58 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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 62
Appendix A, “Intermediate results and arithmetic precision,” on page 691

related tasks
“Using Language Environment callable
services” on page 685

related references
“ARITH” on page 300

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.
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
COBOL intrinsic function Language Environment callable service Results
DATE-OF-INTEGER CEEDATE with picture string YYYYMMDD Compatible
DAY-OF-INTEGER CEEDATE with picture string YYYYDDD Compatible
INTEGER-OF-DATE CEEDAYS Compatible
INTEGER-OF-DATE CEECBLDY Incompatible

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
COBOL intrinsic function Language Environment callable service Results
INTEGER-OF-DATE CEECBLDY Compatible
DATE-OF-INTEGER CEEDATE with picture string YYYYMMDD Incompatible
DAY-OF-INTEGER CEEDATE with picture string YYYYDDD Incompatible
INTEGER-OF-DATE CEEDAYS Incompatible

related tasks
“Using Language Environment callable
services” on page 685

Chapter 3. Working with numbers and arithmetic 59

 related references
“INTDATE” on page 326

Examples: numeric intrinsic functions

The following examples and accompanying explanations show intrinsic functions in each of several
categories.
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 X Pic 9(2).
01 Price1 Pic x(8) Value "$8000".
01 Price2 Pic x(8) Value "$2000".
01 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.

60 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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 Series-Amt1 Pic 9(9)V99 Value 100.

01 Series-Amt2 Pic 9(9)V99 Value 200.
01 Series-Amt3 Pic 9(9)V99 Value 300.
01 Discount-Rate Pic S9(2)V9(6) Value .10.
01 Todays-Value Pic 9(9)V99.
. . .
Compute Todays-Value =
Function
Present-Value(Discount-Rate Series-Amt1 Series-Amt2 Series-Amt3)

You can use the ANNUITY function in business problems that require you to determine the amount of
an installment payment (annuity) necessary to repay the principal and interest of a loan. The series of
payments is characterized by an equal amount each period, periods of equal length, and an equal interest
rate each period. The following example shows how you can calculate the monthly payment required to
repay a $15,000 loan in three years at a 12% annual interest rate (36 monthly payments, interest per
month = .12/12):

01 Loan Pic 9(9)V99.

01 Payment Pic 9(9)V99.
01 Interest Pic 9(9)V99.
01 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 Tax-S Pic 99v999 value .045.

01 Tax-T Pic 99v999 value .02.
01 Tax-W Pic 99v999 value .035.
01 Tax-B Pic 99v999 value .03.
01 Ave-Tax Pic 99v999.
01 Median-Tax Pic 99v999.
01 Tax-Range Pic 99v999.
. . .
Compute Ave-Tax = Function Mean (Tax-S Tax-T Tax-W Tax-B)
Compute Median-Tax = Function Median (Tax-S Tax-T Tax-W Tax-B)
Compute Tax-Range = Function Range (Tax-S Tax-T Tax-W Tax-B)

related tasks
“Converting to numbers (NUMVAL, NUMVAL-C, NUMVAL-F)” on page 115

Chapter 3. Working with numbers and arithmetic 61

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.
Note: Fixed-point evaluations are sometimes done with decimal floating-point instructions, which are
quite different from hex floating-point instructions.
Many statements in a program could involve arithmetic. For example, each of the following types of
COBOL statements requires some arithmetic evaluation:
• General arithmetic

compute report-matrix-col = (emp-count ** .5) + 1

add report-matrix-min to report-matrix-max giving report-matrix-tot

• Expressions and functions

compute report-matrix-col = function sqrt(emp-count) + 1

compute whole-hours = function integer-part((average-hours) + 1)

• 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:
• 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.
• 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.

62 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 Arithmetic comparisons (relation conditions)
When you compare numeric expressions using a relational operator, the numeric expressions (whether
they are data items, arithmetic expressions, function references, or some combination of these) are
comparands in the context of the entire evaluation. That is, the attributes of each can influence the
evaluation of the other: both expressions are evaluated in fixed point, or both are evaluated in floating
point. This is also true of abbreviated comparisons even though one comparand does not explicitly appear
in the comparison. For example:

if (a + d) = (b + e) and c

This statement has two comparisons: (a + d) = (b + e), and (a + d) = c. Although (a + d)

does not explicitly appear in the second comparison, it is a comparand in that comparison. Therefore, the
attributes of c can influence the evaluation of (a + d).
The compiler handles comparisons (and the evaluation of any arithmetic expressions nested in
comparisons) in floating-point arithmetic if either comparand is a floating-point value or resolves to a
floating-point value.
The compiler handles comparisons (and the evaluation of any arithmetic expressions nested in
comparisons) in fixed-point arithmetic if both comparands are fixed-point values or resolve to fixed-point
values.
Implicit comparisons (no relational operator used) are not handled as a unit, however; the two
comparands are treated separately as to their evaluation in floating-point or fixed-point arithmetic. In the
following example, five arithmetic expressions are evaluated independently of one another's attributes,
and then are compared to each other.

evaluate (a + d)
when (b + e) thru c
when (f / g) thru (h * i)
. . .
end-evaluate

“Examples: fixed-point and floating-point evaluations” on page 63

related references
“Arithmetic expressions in nonarithmetic statements” on page 699

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 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)ve+99.
. . .
01 report-matrix-col pic 9(3).
01 report-matrix-min pic 9(3).
01 report-matrix-max pic 9(3).
01 report-matrix-tot pic 9(3).
01 average-hours pic 9(3)v9.
01 whole-hours pic 9(4).

These statements are evaluated using floating-point arithmetic:

compute report-matrix-col = (emp-count ** .5) + 1

Chapter 3. Working with numbers and arithmetic 63

 compute report-matrix-col = function sqrt(emp-count) + 1
if report-matrix-tot < function sqrt(emp-count) + 1

These statements are evaluated using fixed-point arithmetic:

add report-matrix-min to report-matrix-max giving report-matrix-tot

compute report-matrix-max =
function max(report-matrix-max report-matrix-tot)
if whole-hours not = function integer-part((average-hours) + 1)

Using currency signs

Many programs need to process financial information and present that information using the appropriate
currency signs. With COBOL currency support (and the appropriate code page for your printer or display
unit), you can use several currency signs in a program.
You can use one or more of the following signs:
• Symbols such as the dollar sign ($)
• Currency signs of more than one character (such as USD or EUR)
• 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.

64 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 Table 14. Hexadecimal values of the euro sign
Code page Applicable countries Modified Euro sign
CCSID from
1140 USA, Canada, Netherlands, Portugal, Australia, New 037 X'9F'
Zealand
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'
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 309
CURRENCY SIGN clause (Enterprise COBOL for z/OS 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.

Chapter 3. Working with numbers and arithmetic 65

 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.

66 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Chapter 4. Handling tables

A table is a collection of data items that have the same description, such as account totals or monthly
averages. A table 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:
• The code clearly shows the unity of the items (the table elements).
• You can use subscripts and indexes to refer to the table elements.
• 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 81

related tasks
“Defining a table (OCCURS)” on page 67
“Nesting tables” on page 69
“Referring to an item in a table” on page 70
“Putting values into a table” on page 73
“Creating variable-length
tables (DEPENDING ON)” on page 78
“Searching a table” on page 84
“Sorting
a table” on page 87
“Processing table items
using intrinsic functions” on page 87
“Working with
unbounded tables and groups” on page 88

“Handling tables efficiently” on page 672

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.

01 table-name.
05 element-name OCCURS n TIMES.
. . . (subordinate items of the table element)

© Copyright IBM Corp. 1991, 2023 67

 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. You can use a format 2 SORT statement to order the table according to its
defined keys, thereby making the table searchable by the SEARCH ALL statement. Note that SEARCH
ALL will return unpredictable results if the table has not been ordered according to the keys.
“Example: binary search” on page 86
related concepts
“National groups” on page 132

related tasks
“Nesting tables” on page 69
“Referring to an item in a table” on page 70
“Putting values into a table” on page 73
“Creating variable-length
tables (DEPENDING ON)” on page 78
“Using national groups” on page 133
“Doing a binary search (SEARCH
ALL)” on page 86
“Defining numeric data” on page 43

related references
OCCURS clause (Enterprise COBOL for z/OS Language Reference)
SIGN clause (Enterprise COBOL for z/OS Language Reference)
ASCENDING KEY and DESCENDING KEY phrases
(Enterprise COBOL for z/OS Language Reference)
SORT statement (Enterprise COBOL for z/OS Language Reference)

68 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Nesting tables
To create a two-dimensional table, define a one-dimensional table in each occurrence of another one-
dimensional table.

For example, in SAMPLE-TABLE-TWO 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 70

“Example: indexing” on page 70

related tasks
“Defining a table (OCCURS)” on page 67
“Referring to an item in a table” on page 70
“Putting values into a table” on page 73
“Creating variable-length
tables (DEPENDING ON)” on page 78
“Searching a table” on page 84
“Processing table items
using intrinsic functions” on page 87
“Handling tables efficiently” on page 672

related references
OCCURS clause (Enterprise COBOL for z/OS Language Reference)

Chapter 4. Handling tables 69

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 71

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:

• Each occurrence of TABLE-DEPTH is 256 bytes in length (4 * 8 * 8).
• Each occurrence of TABLE-ROW is 64 bytes in length (8 * 8).
• Each occurrence of TABLE-COLUMN is 8 bytes in length.

related tasks
“Indexing” on page 72

Referring to an item in a table

A table element has a collective name, but the individual items within it do not have unique data-names.
To refer to an item, you have a choice of three techniques:

70 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 • Use the data-name of the table element, along with its occurrence number (called a subscript) in
parentheses. This technique is called subscripting.
• 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.
• Use both subscripts and indexes together.

related tasks
“Subscripting” on page 71
“Indexing” on page 72

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.
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.

“Example: subscripting” on page 70

related tasks
“Indexing” on page 72
“Putting values into a table” on page 73
“Searching a table” on page 84
“Handling tables efficiently” on page 672

Chapter 4. Handling tables 71

Indexing
You create an index by using the INDEXED BY phrase of the OCCURS clause to identify an index-name.
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 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 70
related tasks
“Subscripting” on page 71
“Putting values into a table” on page 73
“Searching a table” on page 84
“Processing table items
using intrinsic functions” on page 87
“Handling tables efficiently” on page 672

72 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 related references
INDEXED BY phrase (Enterprise COBOL for z/OS Language Reference)
INDEX phrase (Enterprise COBOL for z/OS Language Reference)
SET statement (Enterprise COBOL for z/OS 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.

related tasks
“Loading a table dynamically” on page 73
“Loading a variable-length table” on page 80
“Initializing a table (INITIALIZE)” on page 73
“Assigning values when you define a table (VALUE)” on page 74
“Assigning values to a variable-length
table” on page 80

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.
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 76

“Example: PERFORM and indexing” on page 77

related references
PERFORM statement (Enterprise COBOL for z/OS Language Reference)

Initializing a table (INITIALIZE)

You can load a table by coding one or more INITIALIZE statements.
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.

Chapter 4. Handling tables 73

 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 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)” on page 74
“Assigning values to a variable-length
table” on page 80
“Looping through a table” on page 101
“Using data items and group
items” on page 24
“Using national groups” on page 133
related references
INITIALIZE statement (Enterprise COBOL for z/OS 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.
Set static values in tables in one of these ways:
• Initialize each table item individually.
• Initialize an entire table at the group level.
• Initialize all occurrences of a given table element to the same value.

74 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
related tasks
“Initializing each table
item individually” on page 75
“Initializing a table at
the group level” on page 76
“Initializing all occurrences
of a given table element” on page 76
“Initializing 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.
Use the following technique, which is shown in the example code below:
1. Define 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.

***********************************************************
*** 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 80

related references
REDEFINES clause (Enterprise COBOL for z/OS Language Reference)
OCCURS clause (Enterprise COBOL for z/OS Language Reference)

Chapter 4. Handling tables 75

 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.
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 VALUE "1234".

05 TABLE-TWO OCCURS 4 TIMES 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.

01 Table-OneN Group-Usage National Value "AB12CD34EF56".

05 Table-TwoN Occurs 3 Times Indexed By MyI.
10 ElementOneN Pic nn.
10 ElementTwoN Pic 99.

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 for z/OS Language Reference)
GROUP-USAGE clause (Enterprise COBOL for z/OS 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.

01 T2.
05 T-OBJ PIC 9 VALUE 3.
05 T OCCURS 5 TIMES
DEPENDING ON T-OBJ.
10 X PIC XX VALUE "AA".
10 Y PIC 99 VALUE 19.
10 Z PIC XX 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 80

related references
OCCURS clause (Enterprise COBOL for z/OS 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 ***

76 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 ***********************************************************
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.".
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.

Chapter 4. Handling tables 77

 05 Filler Pic X(25) Value
"Transaction Type Invalid".
05 Filler Pic X(25) Value
"Shift Code Invalid".
05 Filler Pic X(25) Value
"Home Location Code Inval.".
05 Filler Pic X(25) Value
"Work Location Code Inval.".
05 Filler Pic X(25) Value
"Last Name - Blanks".
05 Filler Pic X(25) Value
"Initials - Blanks".
05 Filler Pic X(25) Value
"Duplicate Record Found".
05 Filler Pic X(25) Value
"Commuter Record Not Found".
01 Filler Redefines Error-Message-Table.
05 Error-Message Occurs 8 Times
Indexed By Message-Index Pic X(25).
. . .
PROCEDURE DIVISION.
. . .
Set Flag-Index To 1
Perform Until No-Errors
Search Error-Flag
When Error-Flag (Flag-Index) = Error-On
Move Space To Error-Flag (Flag-Index)
Set Message-Index To Flag-Index
Move Error-Message (Message-Index) To
Print-Message
Perform 260-Print-Report
End-Search
End-Perform
. . .

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.

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 for
z/OS Language Reference for details.
Two factors affect the successful manipulation of variable-length records:
• 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.
• 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 PIC 9.
05 FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-1 PIC X(05).

78 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 01 REC-2.
03 REC-2-DATA 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 PIC 9.
05 FIELD-3 PIC 9.
05 FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-1 PIC X(05).
03 REC-2.
05 FIELD-4 OCCURS 1 TO 5 TIMES
DEPENDING ON 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. ***
*****************************************************************
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 81

Chapter 4. Handling tables 79

 related tasks
“Assigning values to a variable-length
table” on page 80
“Loading a variable-length table” on page 80
“Preventing overlay when adding elements to a variable table” on page 83
“Finding the length of data
items” on page 120

related references
OCCURS DEPENDING ON clause
(Enterprise COBOL for z/OS Language Reference)
Variable-length tables (Enterprise COBOL for z/OS 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.

DATA DIVISION.
FILE SECTION.
FD LOCATION-FILE
RECORDING MODE F
BLOCK 0 RECORDS
RECORD 80 CHARACTERS
LABEL RECORD STANDARD.
01 LOCATION-RECORD.
05 LOC-CODE PIC XX.
05 LOC-DESCRIPTION PIC X(20).
05 FILLER PIC X(58).
. . .
WORKING-STORAGE SECTION.
01 FLAGS.
05 LOCATION-EOF-FLAG PIC X(5) VALUE SPACE.
88 LOCATION-EOF VALUE "YES".
01 MISC-VALUES.
05 LOCATION-TABLE-LENGTH PIC 9(3) VALUE ZERO.
05 LOCATION-TABLE-MAX PIC 9(3) VALUE 100.
*****************************************************************
*** L O C A T I O N T A B L E ***
*** FILE CONTAINS LOCATION CODES. ***
*****************************************************************
01 LOCATION-TABLE.
05 LOCATION-CODE OCCURS 1 TO 100 TIMES
DEPENDING ON LOCATION-TABLE-LENGTH PIC X(80).
. . .
PROCEDURE DIVISION.
. . .
Perform Test After
Varying Location-Table-Length From 1 By 1
Until Location-EOF
Or Location-Table-Length = Location-Table-Max
Move Location-Record To
Location-Code (Location-Table-Length)
Read Location-File
At End Set Location-EOF To True
End-Read
End-Perform

Assigning values to a variable-length table

You can 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.

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.

80 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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 74
related references
OCCURS DEPENDING ON clause
(Enterprise COBOL for z/OS 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 the 85 COBOL Standard.
The basic forms of complex ODO permitted by the compiler are as follows:
• 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.
• 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.
• 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.
• Index name for a table that has variable-length elements.
• Element of a table that has variable-length elements.

“Example: complex ODO” on page 81

related tasks
“Preventing index errors
when changing ODO object value” on page 83
“Preventing overlay when adding elements to a variable table” on page 83

related references
“Effects of change in ODO object value” on page 82
OCCURS DEPENDING ON clause
(Enterprise COBOL for z/OS Language Reference)

Example: complex ODO

The following example illustrates the possible types of occurrence of complex ODO.

01 FIELD-A.
02 COUNTER-1 PIC S99.
02 COUNTER-2 PIC S99.
02 TABLE-1.
03 RECORD-1 OCCURS 1 TO 5 TIMES
DEPENDING ON COUNTER-1 PIC X(3).
02 EMPLOYEE-NUMBER PIC X(5). (1)
02 TABLE-2 OCCURS 5 TIMES (2)(3)
INDEXED BY INDX. (4)
03 TABLE-ITEM PIC 99. (5)
03 RECORD-2 OCCURS 1 TO 3 TIMES

Chapter 4. Handling tables 81

 DEPENDING ON COUNTER-2.
04 DATA-NUM 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:
• 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).
• 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.
• 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.

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:
• The size of any group that contains the relevant ODO clause reflects the new value of the ODO object.
• A MOVE to a group that contains the ODO subject is made based on the new value of the ODO object.
• 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.)

82 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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” on page 83
“Preventing overlay when adding elements to a variable table” on page 83

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.

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:
• A reference to an element of the table
• A SET statement of the form SET integer-data-item TO index-name (format 1)
• A SET statement of the form SET index-name UP|DOWN BY integer (format 2)
To avoid this type of error, do these steps:
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.)
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.)
The following code shows how to save and restore the index-name (shown in “Example: complex ODO”
on page 81) 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 for z/OS 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.
To avoid this type of error, do these steps:
1. Save the variably located data items that follow the table in another data area.
2. Increment the value of the ODO object.

Chapter 4. Handling tables 83

 3. Move data into the new table element (if needed).
4. Restore the variably located data items from the data area where you saved them.
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 PIC X(10).
05 CONTROL-1 PIC S99.
05 CONTROL-2 PIC S99.
05 VARY-FIELD-1 OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-1 PIC X(5).
05 GROUP-ITEM-1.
10 VARY-FIELD-2
OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-2 PIC X(9).
01 STORE-VARY-FIELD-2.
05 GROUP-ITEM-2.
10 VARY-FLD-2
OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-2 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:

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:

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.
To do serial searches, use SEARCH and indexing. For variable-length tables, you can use PERFORM with
subscripting or indexing.

84 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 To do binary searches, use SEARCH ALL and indexing.
A binary search can be considerably more efficient than a serial search. For a serial search, the number
of comparisons is of the order of n, the number of entries in the table. For a binary search, the number of
comparisons is 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)” on page 85
“Doing a binary search (SEARCH
ALL)” on page 86

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.
The conditions in the WHEN phrase are evaluated in the order in which they appear:
• 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.
• If one of the WHEN conditions is satisfied, the search ends. The index remains pointing to the table
element that satisfied the condition.
• 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” on page 85

related references
SEARCH statement (Enterprise COBOL for z/OS 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.
. . .
SET TE1-INDEX TO 1
SET TE2-INDEX TO 4

Chapter 4. Handling tables 85

 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.
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. You can use a format 2 SORT
statement to order the table according to its defined keys, thereby making the table searchable by the
SEARCH ALL statement. Note that SEARCH ALL will return unpredictable results if the table has not
been ordered according to the keys.
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” on page 86

related tasks
“Defining a table (OCCURS)” on page 67

related references
SEARCH statement (Enterprise COBOL for z/OS Language Reference)
General relation conditions (Enterprise COBOL for z/OS Language Reference)

Example: binary search

The following example shows how you can code a binary search of a table.
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.

86 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.

Sorting a table
You can sort a table by using the format 2 SORT statement. It is part of the 2002 COBOL Standard.
The format 2 SORT statement sorts table elements according to the specified table keys, and it is
especially useful for tables used with SEARCH ALL. You can specify the keys for sorting as part of the
table definition, which can also be used in the SEARCH ALL statement. Alternatively, you can also specify
the keys for sorting as part of the SORT statement, either if you want to sort the table using different keys
than those specified in the table definition, or if the table has no keys specified.
With the format 2 SORT statement, you don't need to use the input and output procedures as you do with
the format 1 SORT statement.
See the following example in which the table is sorted based on specified keys:

WORKING-STORAGE SECTION.
01 GROUP-ITEM.
05 TABL OCCURS 10 TIMES
10 ELEM-ITEM1 PIC X.
10 ELEM-ITEM2 PIC X.
10 ELEM-ITEM3 PIC X.
...
PROCEDURE DIVISION.
...
SORT TABL DESCENDING ELEM-ITEM2 ELEM-ITEM3.
IF TABL (1)...

related references
SORT statement (Enterprise COBOL for z/OS Language Reference)
“Using the format 2 SORT statement to sort a table” on page 688

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.
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))

Chapter 4. Handling tables 87

 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 88

related tasks
“Using intrinsic functions (built-in functions)” on page 38
“Converting data items (intrinsic functions)” on page 113
“Evaluating data items (intrinsic functions)” on page 117

related references
Intrinsic functions (Enterprise COBOL for z/OS 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 Pic s9(4) usage binary.
05 Emp-Record Occurs 1 to 500 times
depending on Emp-Count.
10 Emp-Name Pic x(20).
10 Emp-Idme Pic 9(9).
10 Emp-Salary Pic 9(7)v99.
. . .
Procedure Division.
Compute Max-Salary = Function Max(Emp-Salary(ALL))
Compute I = Function Ord-Max(Emp-Salary(ALL))
Compute Avg-Salary = Function Mean(Emp-Salary(ALL))
Compute Salary-Range = Function Range(Emp-Salary(ALL))
Compute Total-Payroll = Function Sum(Emp-Salary(ALL))

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.
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.

88 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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).
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:
• You can reference unbounded tables in COBOL syntax anywhere a table can be referenced.
• 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” on page 89
Example: ALLOCATE and FREE storage for unbounded tables
(Enterprise COBOL for z/OS Language Reference)
Variable-length tables (Enterprise COBOL for z/OS Language Reference)
OCCURS DEPENDING ON clause
(Enterprise COBOL for z/OS 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:
• 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.
• 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.

XML schema
<?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">

Chapter 4. Handling tables 89

 <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 document
<?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>

XML processing program

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.

related tasks
“Working with
unbounded tables and groups” on page 88

90 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Chapter 5. Selecting and repeating program actions

Use COBOL control language to choose program actions based on the outcome of logical tests, to iterate
over selected parts of your program and data, and to identify statements to be performed as a group.
These controls include the IF, EVALUATE, and PERFORM statements, and the use of switches and flags.

related tasks
“Selecting program actions” on page 91
“Repeating program actions” on page 99

Selecting program actions

You can provide for different program actions depending on the tested value of one or more data items.
The IF and EVALUATE statements in COBOL test one or more data items by means of a conditional
expression.

related tasks
“Coding a choice of actions” on page 91
“Coding conditional expressions” on page 95

related references
IF statement (Enterprise COBOL for z/OS Language Reference)
EVALUATE statement (Enterprise COBOL for z/OS 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.

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

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

© Copyright IBM Corp. 1991, 2023 91

 Note: NEXT SENTENCE can be very different from CONTINUE, based on location of the following period,
as shown in this example:

IF condition-r
statement-1
ELSE
CONTINUE or NEXT SENTENCE
END-IF
*> CONTINUE goes to statement-2
statement-2
statement-3.
*> NEXT SENTENCE goes to statement-4
statement-4

For details about NEXT SENTENCE, see IF statement in the Enterprise COBOL for z/OS Language
Reference.
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” on page 92
“Using the EVALUATE statement” on page 93
“Coding conditional expressions” on page 95

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.
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.

92 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
related tasks
“Coding a choice of actions” on page 91

related references
Explicit scope terminators (Enterprise COBOL for z/OS 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.

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 94

“Example: EVALUATE using multiple WHEN phrases” on page 94

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 95
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 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:
• The statements associated with the selected WHEN phrase are performed.

Chapter 5. Selecting and repeating program actions 93

 • The statements associated with the WHEN OTHER phrase are performed.
• 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 91

related references
EVALUATE statement (Enterprise COBOL for z/OS Language Reference)
General relation conditions (Enterprise COBOL for z/OS 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

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

94 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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"
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.
You can specify the following conditions:
• Relation conditions, such as:
– Numeric comparisons
– Alphanumeric comparisons
– DBCS comparisons

Chapter 5. Selecting and repeating program actions 95

 – National comparisons
• Class conditions; for example, to test whether a data item:
– IS NUMERIC
– IS ALPHABETIC
– IS ALPHABETIC-LOWER
– IS ALPHABETIC-UPPER
– IS DBCS
– IS 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 96

related tasks
“Defining switches and flags” on page 97
“Resetting switches and flags” on page 98
“Checking for incompatible data (numeric class test)” on page 53
“Comparing national (UTF-16)
data” on page 145
“Testing for valid DBCS
characters” on page 149

related references
General relation conditions (Enterprise COBOL for z/OS Language Reference)
Class condition (Enterprise COBOL for z/OS Language Reference)
Rules for condition-name entries (Enterprise COBOL for z/OS Language Reference)
Sign condition (Enterprise COBOL for z/OS Language Reference)
Combined conditions (Enterprise COBOL for z/OS 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” on page 97
“Resetting switches and flags” on page 98

96 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Defining switches and flags
In the DATA DIVISION, define level-88 items that will act as switches or flags, and give them meaningful
names.
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” on page 97

“Example: flags” on page 97

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 in effect when
Transaction-EOF-Switch has value 'y'. Referencing Transaction-EOF in the PROCEDURE
DIVISION expresses the same condition as testing Transaction-EOF-Switch = "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
End-if

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 Pic X.
88 Add-Transaction Value "A".
88 Change-Transaction Value "C".
88 Delete-Transaction 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

Chapter 5. Selecting and repeating program actions 97

 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.
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” on page 98

“Example: set switch off” on page 99

Example: set switch on

The following examples show how you can set a switch on by coding a SET statement that moves the
condition name value to the conditional variable.
For example, the SET statement in the following example has the same effect as coding the statement
Move "y" to Transaction-EOF-Switch:

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

98 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 Example: set switch off
The following example shows how you can set a switch off by coding a MOVE statement that moves the
condition name value to the conditional variable.
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.
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.

related tasks
“Choosing inline or out-of-line PERFORM” on page 99
“Coding a loop” on page 100
“Looping through a table” on page 101
“Executing multiple paragraphs
or sections” on page 101

related references
PERFORM statement (Enterprise COBOL for z/OS 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.
To determine whether to code an inline or out-of-line PERFORM statement, answer the following
questions:
• 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.
• 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.)
• 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 procedure and an implicit return. If the performed procedure is in the subsequent sequential

Chapter 5. Selecting and repeating program actions 99

 flow of your program, it is also executed in that logic flow. To avoid this additional execution, place the
procedure 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” on page 100

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
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 procedure a specified number of times.

PERFORM 010-PROCESS-ONE-MONTH 12 TIMES

INSPECT . . .

In the example above, when control reaches the PERFORM statement, the code for the procedure 010-
PROCESS-ONE-MONTH is executed 12 times before control is transferred to the INSPECT statement.
Use the PERFORM . . . UNTIL statement to execute a procedure 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
procedure 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 . . .

100 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.)

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.
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.
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 87

related references
EXIT PERFORM or EXIT PERFORM CYCLE statement
(Enterprise COBOL for z/OS Language Reference)
EXIT PARAGRAPH or EXIT SECTION statement
(Enterprise COBOL for z/OS Language Reference)

Chapter 5. Selecting and repeating program actions 101

102 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Chapter 6. Handling strings

COBOL provides language constructs for performing many different operations on string data items.
For example, you can:
• Join or split data items.
• Manipulate null-terminated strings, such as count or move characters.
• Refer to substrings by their ordinal position and, if needed, length.
• Tally and replace data items, such as count the number of times a specific character occurs in a data
item.
• Convert data items, such as change to uppercase or lowercase.
• Evaluate data items, such as determine the length of a data item.

related tasks
“Joining data items (STRING)” on page 103
“Splitting data items (UNSTRING)” on page 105
“Manipulating null-terminated
strings” on page 108
“Referring to substrings
of data items” on page 109
“Tallying and replacing
data items (INSPECT)” on page 112
“Converting data items (intrinsic functions)” on page 113
“Evaluating data items (intrinsic functions)” on page 117
Chapter 7, “Processing data in an international
environment,” on page 123

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.
The STRING statement transfers data into a receiving data item in the order that you indicate. In the
STRING statement you also specify:
• A delimiter for each set of sending fields that, if encountered, causes those sending fields to stop being
transferred (DELIMITED BY phrase)
• (Optional) Action to be taken if the receiving field is filled before all of the sending data has been
processed (ON OVERFLOW phrase)
• (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:
• USAGE DISPLAY, each identifier in the statement except the POINTER identifier must have USAGE
DISPLAY, and each literal in the statement must be alphanumeric
• USAGE NATIONAL, each identifier in the statement except the POINTER identifier must have USAGE
NATIONAL, and each literal in the statement must be national
• 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” on page 104

© Copyright IBM Corp. 1991, 2023 103

 related tasks
“Handling errors in joining and splitting strings” on page 232

related references
STRING statement (Enterprise COBOL for z/OS 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 PIC X(15).
10 CUST-ADDR PIC X(35).
05 BILL-INFO.
10 INV-NO PIC X(6).
10 INV-AMT PIC $$,$$$.99.
10 AMT-PAID PIC $$,$$$.99.
10 DATE-PAID PIC X(8).
10 BAL-DUE PIC $$,$$$.99.
10 DATE-DUE PIC X(8).

The WORKING-STORAGE SECTION defines the following fields:

77 RPT-LINE PIC X(120).

77 LINE-POS PIC S9(3).
77 LINE-NO PIC 9(5) VALUE 1.
77 DEC-POINT PIC 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:
• RPT-LINE is set to SPACES.
• 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
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.

104 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.
In the UNSTRING statement you can specify:
• 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)
• A field for the delimiter that, when encountered in the sending field, causes the current receiving field to
stop receiving (DELIMITER IN phrase)
• An integer data item that stores the number of characters placed in the current receiving field (COUNT
IN phrase)
• An integer data item that indicates the leftmost character position within the sending field at which
UNSTRING processing should begin (WITH POINTER phrase)
• An integer data item that stores a tally of the number of receiving fields that are acted on (TALLYING
IN phrase)
• 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:
• 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
• 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

Chapter 6. Handling strings 105

 • 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” on page 106

related concepts
“Unicode and the encoding
of language characters” on page 129

related tasks
“Handling errors in joining and splitting strings” on page 232

related references
UNSTRING statement (Enterprise COBOL for z/OS Language Reference)
Classes and categories of data (Enterprise COBOL for z/OS 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).
05 FILLER PIC X VALUE SPACE.
05 DISPLAY-DOLS 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:
• A period (.) is placed in DBY-1 for use as a delimiter.
• CHAR-CT (the POINTER field) is set to 3.
• The value zero (0) is placed in FLDS-FILLED (the TALLYING field).
• Data is read into record INV-RCD, whose format is as shown below.

106 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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.
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 000379
WORK-REC 475120000122BBA
CHAR-CT (the POINTER field) 55
FLDS-FILLED (the TALLYING field) 6

Chapter 6. Handling strings 107

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.
For example, you can:
• Use null-terminated literal constants (Z". . . ").
• 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"

• Use an UNSTRING statement to move characters in a null-terminated string to a target field, and get the
character count:

WORKING-STORAGE SECTION.
01 source-field PIC X(1001).
01 char-count COMP-5 PIC 9(4).
01 target-area.
02 individual-char OCCURS 1 TO 1000 TIMES DEPENDING ON char-count
PIC X.
. . .
PROCEDURE DIVISION.
UNSTRING source-field DELIMITED BY X"00"
INTO target-area
COUNT IN char-count
ON OVERFLOW
DISPLAY "source not null terminated or target too short"
END-UNSTRING

• Use a SEARCH statement to locate trailing null or space characters. Define the string being examined as
a table of single characters.
• 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” on page 108

related tasks
“Handling null-terminated
strings” on page 497
related references
Alphanumeric literals (Enterprise COBOL for z/OS 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

108 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.
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 140.
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)

Chapter 6. Handling strings 109

 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 111

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 111

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” on page 110
“Unicode and the encoding
of language characters” on page 129

related tasks
“Referring to an item in a table” on page 70

related references
“SSRANGE” on page 356
Reference modification (Enterprise COBOL for z/OS Language Reference)
Function definitions (Enterprise COBOL for z/OS 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

110 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 * the number of hours:
REFMOD-TIME-ITEM (1:2)
":"
* Retrieve the portion of the time value that corresponds to
* the number of minutes:
REFMOD-TIME-ITEM (3:2)
":"
* Retrieve the portion of the time value that corresponds to
* the number of seconds:
REFMOD-TIME-ITEM (5:2)

“Example: arithmetic expressions as reference modifiers” on page 111

“Example: intrinsic
functions as reference modifiers” on page 111

related tasks
“Assigning input from a
screen or file (ACCEPT)” on page 35
“Referring to substrings
of data items” on page 109
“Using national data (Unicode)
in COBOL” on page 129

related references
Reference modification (Enterprise COBOL for z/OS 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 LEFTY PIC X(30).

01 RIGHTY PIC X(30) JUSTIFIED RIGHT.
01 I 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.

Chapter 6. Handling strings 111

 05 I Pic 99.
. . .
Move Customer-Record(Function Min(Left-posn I):Function Length(WS-name)) to WS-name

If you want to use a noninteger function in a position 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 for z/OS Language Reference)
INTEGER-PART (Enterprise COBOL for z/OS 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.
Use the INSPECT statement to do the following tasks:
• Count the number of times a specific character occurs in a data item (TALLYING phrase).
• Fill a data item or selected portions of a data item with specified characters such as spaces, asterisks,
or zeros (REPLACING phrase).
• 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:
• An elementary item described explicitly or implicitly as USAGE DISPLAY, USAGE DISPLAY-1, or
USAGE NATIONAL
• An alphanumeric group item or national group item
If the inspected item has:
• 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
• 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
• 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” on page 112

related concepts
“Unicode and the encoding
of language characters” on page 129

related references
INSPECT statement (Enterprise COBOL for z/OS 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 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 PIC 9 VALUE ZERO.

01 DATA-2 PIC X(11).

112 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 . . .
INSPECT DATA-2
TALLYING COUNTR FOR LEADING "0"
REPLACING FIRST "A" BY "2" AFTER INITIAL "C"

DATA-2 before COUNTR after DATA-2 after

00ACADEMY00 2 00AC2DEMY00
0000ALABAMA 4 0000ALABAMA
CHATHAM0000 0 CH2THAM0000

In the following example, the INSPECT statement 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, to one code page from another, or to
hexadecimal or binary digits. You can also convert hexadecimal character strings or bit character strings
to alphanumeric data items.
You can use the NATIONAL-OF and DISPLAY-OF intrinsic functions to convert to and from national
(Unicode) strings.

Chapter 6. Handling strings 113

 You can also use the INSPECT statement to convert characters.
“Examples: INSPECT statement” on page 112

related tasks
“Changing case (UPPER-CASE, LOWER-CASE)” on page 114
“Transforming to reverse order (REVERSE)” on page 114
“Converting to numbers (NUMVAL, NUMVAL-C, NUMVAL-F)” on page 115
“Converting from one code page to another” on page 116

“Converting
to hexadecimal or bit data (HEX-OF, BIT-OF)” on page 116
“Converting
from hexadecimal or bit data (HEX-TO-CHAR, BIT-TO-CHAR)” on page 117

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.

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 World!
HELLO WORLD!
hello world!
HELLO 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 35

Transforming to reverse order (REVERSE)

You can reverse the order of the characters in a string by using the REVERSE intrinsic function.

Move Function Reverse(Orig-cust-name) To Orig-cust-name

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 129

114 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Converting to numbers (NUMVAL, NUMVAL-C, NUMVAL-F)
The NUMVAL, NUMVAL-C and NUMVAL-F 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.

01 R Pic x(20) Value "- 1234.5678".

01 S Pic x(20) Value " $12,345.67CR".
01 T Pic x(20) Value "+ 12.345678E+2".
01 Total Usage is Comp-1.
. . .
Compute Total = Function Numval(R) + Function Numval-C(S) + Function Numval-F(T)

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.
Use NUMVAL-F when the argument includes an exponent value, as shown in the example above. You can
also place an algebraic sign before 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, NUMVAL-C and NUMVAL-F 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). Internally NUMVAL uses long-precision
floating calculations to convert the given number to the output, so if the argument to NUMVAL, NUMVAL-C,
or NUMVAL-F 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. Otherwise, the result may lose precision in an unexpected manner.

When you use NUMVAL, NUMVAL-C, or NUMVAL-F, you do not need to statically define 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)

Chapter 6. Handling strings 115

 The input could then be:

1.23
-300

related concepts
“Formats for numeric
data” on page 47
“Data format conversions” on page 51
“Unicode and the encoding
of language characters” on page 129

related tasks
“Converting to or from national (Unicode) representation” on page 136

related references
“Conversions and precision” on page 52
“ARITH” on page 300

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.
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 129

related tasks
“Converting to or from national (Unicode) representation” on page 136

Converting to hexadecimal or bit data (HEX-OF, BIT-OF)

You can use the HEX-OF or BIT-OF intrinsic functions to convert data of any type to hexadecimal or
binary digits.
The HEX-OF intrinsic function can be used to convert data of any type to a human readable string of
hexadecimal digits ("0" through "9", "A" through "F", and "a" through "f") that represent, in hexadecimal
form, the underlying byte values of the data to be converted. The length of the output hex string in bytes is
two times the length of the input argument string in bytes.
For example, FUNCTION HEX-OF('Hello, world!') returns 'C8859393966B40A6969993845A'.
Note: The first two hexadecimal digits 'C8' correspond to the EBCDIC encoding of the letter 'H'.
The argument to the HEX-OF intrinsic function can be a literal, a data item, or the result of an intrinsic
function.
The BIT-OF intrinsic function can be used to convert data of any type to a human readable string of
binary digits ("0" or "1") that represent, in bit string form, the underlying byte values of the data to be

116 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 converted. The length of the output bit string in bytes is eight times the length of the input argument
string in bytes.
For example, FUNCTION BIT-OF('Hello, world!') returns
'110010001000010110010011100100111001011001101011010000001010011010010110
10011001100100111000010001011010'.
Note: The first eight characters '11001000' of the output string correspond to the hexadecimal value
x'C8', which matches the output of the HEX-OF intrinsic function shown above and corresponds to the
EBCDIC encoding of the letter 'H'.
The argument to the BIT-OF intrinsic function can be a literal, a data item, or the result of an intrinsic
function.

related references
BIT-OF (Enterprise COBOL for z/OS Language Reference)
HEX-OF (Enterprise COBOL for z/OS Language Reference)

Converting from hexadecimal or bit data (HEX-TO-CHAR, BIT-TO-CHAR)

You can use the HEX-TO-CHAR or BIT-TO-CHAR intrinsic functions to convert hexadecimal character
strings (consisting of characters "0" through "9", "A" through "F", and "a" through "f") or bit character
strings (consisting of characters "0" and "1") to alphanumeric data items.
HEX-TO-CHAR
The HEX-TO-CHAR intrinsic function can be used to convert a character string consisting of hexadecimal
digits ("0" through "9", "A" through "F", and "a" through "f") to an alphanumeric character string consisting
of bytes that correspond to the hexadecimal digits in the input character string.
For example,

MOVE 'FFAABB' TO MY-HEX-DATA

FUNCTION HEX-TO-CHAR(MY-HEX-DATA) returns a character string with value x'FFAABB'.

The argument to the HEX-TO-CHAR intrinsic function can be an alphanumeric literal, alphanumeric data
item, or alphanumeric group item. The length of the argument must be a multiple of 2 bytes.
BIT-TO-CHAR
The BIT-TO-CHAR intrinsic function can be used to convert a character string consisting of characters
"0" and "1" to an alphanumeric character string consisting of bytes that correspond to the bit pattern
indicated by the sequence of "0" and "1" characters in the input character string.
For example,

MOVE '1111001000000110' TO MY-BIT-DATA

FUNCTION BIT-TO-CHAR(MY-BIT-DATA) returns a character string with value x'F206'.

The argument to the BIT-TO-CHAR intrinsic function can be an alphanumeric literal, alphanumeric data
item or alphanumeric group item. The length of the argument must be a multiple of 8 bytes.

related references
BIT-TO-CHAR (Enterprise COBOL for z/OS Language Reference)
HEX-TO-CHAR (Enterprise COBOL for z/OS Language Reference)

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.
Use these intrinsic functions:

Chapter 6. Handling strings 117

 • CHAR and ORD to evaluate integers and single alphabetic or alphanumeric characters with respect to the
collating sequence used in a program
• 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
• LENGTH to find the length of data items, including USAGE NATIONAL data items, and BYTE-LENGTH to
find the length of data items in bytes, including DBCS data items
• WHEN-COMPILED to find the date and time when a program was compiled

related concepts
“Unicode and the encoding
of language characters” on page 129

related tasks
“Evaluating single characters
for collating sequence” on page 118
“Finding the largest or
smallest data item” on page 118
“Finding the length of data
items” on page 120
“Finding the date of compilation” on page 121

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.
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)

The ordinal number associated with a character is not the same as the numeric value (in decimal) of
the hex value of the character. For example, if you are using the EBCDIC collating sequence, the ordinal
number of X'00' is one instead of zero. Similarly, the ordinal number of X'FF' is 256 instead of 255.
Therefore, the ordinal values returned from the ORD intrinsic function when using the EBCDIC collating
sequence range from 1 - 256, not 0 - 255 that are the decimal values of the hex values of the valid
EBCDIC characters.

related references
CHAR (Enterprise COBOL for z/OS Language Reference)
ORD (Enterprise COBOL for z/OS 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.
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.

118 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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 Arg1 Pic x(10) Value "THOMASSON ".

05 Arg2 Pic x(10) Value "THOMAS ".
05 Arg3 Pic x(10) 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 value in the list of arguments that you
supply. If you used the ORD-MAX function in the previous example, the compiler would issue an error
message because the reference to a numeric function is not in a valid place. Using the same arguments as
in the previous example, ORD-MAX can be used as follows:

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 55
“Processing table items
using intrinsic functions” on page 87
“Returning variable results
with alphanumeric or national functions” on page 119

related references
MAX (Enterprise COBOL for z/OS Language Reference)
MIN (Enterprise COBOL for z/OS Language Reference)
ORD-MAX (Enterprise COBOL for z/OS Language Reference)
ORD-MIN (Enterprise COBOL for z/OS 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.
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 R1 Pic x(10) value "e".

01 R2 Pic x(05) value "f".
01 R3 Pic x(20) value spaces.
01 L Pic 99.
. . .
Move Function Max(R1 R2) to R3
Compute L = Function Length(Function Max(R1 R2))

This code has the following results:

• R2 is evaluated to be larger than R1.

Chapter 6. Handling strings 119

 • The string 'fbbbb' is moved to R3, where b represents a blank space. (The unfilled character positions in
R3 are padded with spaces.)
• L evaluates to the value 5.
If R1 contained 'g' instead of 'e', the code would have the following results:
• R1 would evaluate as larger than R2.
• The string 'gbbbbbbbbb' would be moved to R3. (The unfilled character positions in R3 would be padded
with spaces.)
• The value 10 would be assigned to L.
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 R1 Pic n(10) national value "e".

01 R2 Pic n(05) national value "f".
01 R3 Pic n(20) national value spaces.
01 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:
• R2 is evaluated to be larger than R1.
• 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.
• 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 118
“Performing arithmetic” on page 55

related references
MAX (Enterprise COBOL for z/OS 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

120 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 alphanumeric or national literal, or a data item of any type except DBCS. You can also use the BYTE-
LENGTH function to determine the length of an item in bytes.
LENGTH intrinsic function
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 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))

BYTE-LENGTH intrinsic function

The BYTE-LENGTH function returns the length of a national item, an alphanumeric item, or a DBCS literal
as an integer equal to the length of the argument in bytes.
LENGTH OF special register
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. The BYTE-LENGTH function
returns the same result as the LENGTH OF special register for all arguments types.
You can use the LENGTH and BYTE-LENGTH functions 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 55
“Creating variable-length
tables (DEPENDING ON)” on page 78
“Processing table items
using intrinsic functions” on page 87

related references
BYTE-LENGTH (Enterprise COBOL for z/OS Language Reference)
LENGTH (Enterprise COBOL for z/OS Language Reference)
LENGTH OF (Enterprise COBOL for z/OS 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.
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

Chapter 6. Handling strings 121

 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 for z/OS Language Reference)

122 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 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.

Use these COBOL facilities to code and compile programs that process national data:
• 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
• The COBOL statements shown in the related reference below about COBOL statements and national
data
• 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
• 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
• 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 129
“National groups” on page 132

related tasks
“Using national data (Unicode)
in COBOL” on page 129
“Converting to or from national (Unicode) representation” on page 136
“Processing UTF-8 data” on page 140
“Processing Chinese GB 18030 data” on page 144

© Copyright IBM Corp. 1991, 2023 123

 “Comparing national (UTF-16)
data” on page 145
“Coding for use of DBCS support” on page 147
Appendix B, “Converting double-byte character set (DBCS) data,” on page 701

related references
“COBOL statements and national data” on page 124
“Intrinsic functions and national data” on page 127
“CODEPAGE” on page 304
“NSYMBOL” on page 335
Classes and categories of data (Enterprise COBOL for z/OS Language Reference)
Data categories and PICTURE rules
(Enterprise COBOL for z/OS Language Reference)
MOVE statement (Enterprise COBOL for z/OS Language Reference)
General relation conditions (Enterprise COBOL for z/OS 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 Can be national Comment For more information
statement
ACCEPT identifier-1, identifier-2 identifier-1 is converted “Assigning input from a screen or file
from the native code page (ACCEPT)” on page 35
specified in the CODEPAGE
compiler option only if
input is from CONSOLE.
ADD All identifiers can be “Using COMPUTE and other
numeric items that arithmetic statements” on page 55
have USAGE NATIONAL.
identifier-3 (GIVING) can
be numeric-edited with
USAGE NATIONAL.
CALL identifier-2, identifier-3, “Passing data” on page 491
identifier-4, identifier-5;
literal-2, literal-3
COMPUTE identifier-1 can be “Using COMPUTE and other
numeric or numeric- arithmetic statements” on page 55
edited with USAGE
NATIONAL. arithmetic-
expression can contain
numeric items that have
USAGE NATIONAL.
COPY . . . operand-1, operand-2 of Chapter 18, “Compiler-directing
REPLACING the REPLACING phrase statements,” on page 377
DISPLAY identifier-1 identifier-1 is converted “Displaying values on a screen or in a
to EBCDIC only if file (DISPLAY)” on page 35
the CONSOLE mnemonic-
name is specified directly
or indirectly.

124 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Table 15. COBOL statements and national data (continued)
COBOL Can be national Comment For more information
statement
DIVIDE All identifiers can be “Using COMPUTE and other
numeric items that arithmetic statements” on page 55
have USAGE NATIONAL.
identifier-3 (GIVING) and
identifier-4 (REMAINDER)
can be numeric-edited
with USAGE NATIONAL.
INITIALIZE identifier-1; identifier-2 If you specify REPLACING “Examples: initializing data items” on
or literal-1 of the NATIONAL or REPLACING page 28
REPLACING phrase NATIONAL-EDITED,
identifier-2 or literal-1
must be valid as a sending
operand in a move to
identifier-1.
INSPECT All identifiers and If any of these (other “Tallying and replacing data items
literals. (identifier-2, the than identifier-2, the (INSPECT)” on page 112
TALLYING integer data TALLYING identifier) have
item, can have USAGE USAGE NATIONAL, all
NATIONAL.) must be national.
INVOKE Method-name as “Invoking methods (INVOKE)” on
identifier-2 or literal-1; page 612
identifier-3 or literal-2 in
the BY VALUE phrase
JSON PARSE identifier-2 (the target identifier-1 is not Chapter 30, “Processing JSON
data item); identifier-3 supported as a national input ,” on page 529
(the NAME identifier); data item.
literal-1 (the NAME
substitution); identifier-4
(the SUPPRESS identifier)
MERGE Merge keys The COLLATING “Setting sort or merge criteria” on
SEQUENCE phrase does page 219
not apply.
MOVE Both the sender and Implicit conversions are “Assigning values to elementary data
receiver, or only the performed for valid MOVE items (MOVE)” on page 32
receiver operands.
“Assigning values to group data items
(MOVE)” on page 33

MULTIPLY All identifiers can be “Using COMPUTE and other

numeric items that arithmetic statements” on page 55
have USAGE NATIONAL.
identifier-3 (GIVING) can
be numeric-edited with
USAGE NATIONAL.

Chapter 7. Processing data in an international environment 125

Table 15. COBOL statements and national data (continued)
COBOL Can be national Comment For more information
statement
SEARCH ALL Both the key data The key data item and “Doing a binary search (SEARCH
(binary search) item and its object of its object of comparison ALL)” on page 86
comparison must be compatible
according to the rules of
comparison. If the object
of comparison is of class
national, the key must be
also.
SORT Sort keys The COLLATING “Setting sort or merge criteria” on
SEQUENCE phrase does page 219
not apply.
STRING All identifiers and literals. If identifier-3, the “Joining data items (STRING)” on
(identifier-4, the POINTER receiving data item, is page 103
integer data item, can national, all identifiers
have USAGE NATIONAL.) and literals (other than
identifier-4, the POINTER
identifier) must be
national.
SUBTRACT All identifiers can be “Using COMPUTE and other
numeric items that arithmetic statements” on page 55
have USAGE NATIONAL.
identifier-3 (GIVING) can
be numeric-edited with
USAGE NATIONAL.
UNSTRING All identifiers and If identifier-4, a receiving “Splitting data items (UNSTRING)” on
literals. (identifier-6 and data item, has USAGE page 105
identifier-7, the COUNT NATIONAL, the sending
and TALLYING integer data item and each
data items, respectively, delimiter must have
can have USAGE USAGE NATIONAL, and
NATIONAL.) each literal must be
national.
XML identifier-1 (the generated Chapter 33, “Producing XML output,”
GENERATE XML document); on page 577
identifier-2 (the source
field or fields); identifier-4
or literal-4 (the
namespace identifier);
identifier-5 or literal-5 (the
namespace prefix)

126 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Table 15. COBOL statements and national data (continued)
COBOL Can be national Comment For more information
statement
XML PARSE identifier-1 (the XML The XML-NTEXT special Chapter 32, “Processing XML input,”
document) register contains on page 537
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 43
“Displaying numeric data” on page 45
“Using national data (Unicode)
in COBOL” on page 129
“Comparing national (UTF-16)
data” on page 145

related references
“CODEPAGE” on page 304
Classes and categories of data (Enterprise COBOL for z/OS 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
BIT-OF Alphanumeric BIT-OF (Enterprise COBOL for z/OS Language Reference)
BYTE-LENGTH Integer “Finding the length of data items” on page 120
CONTENT-OF Alphanumeric, CONTENT-OF (Enterprise COBOL for z/OS Language
national, UTF-8, Reference)
integer, or numeric
DISPLAY-OF Alphanumeric “Converting national to alphanumeric (DISPLAY-OF)” on
page 138
FORMATTED-CURRENT-DATE, Alphanumeric, • FORMATTED-CURRENT-DATE (Enterprise COBOL for
FORMATTED-DATE, national, or UTF-8 z/OS Language Reference)
FORMATTED-TIME,
• FORMATTED-DATE (Enterprise COBOL for z/OS Language
FORMATTED-DATETIME
Reference)
• FORMATTED-TIME (Enterprise COBOL for z/OS Language
Reference)
• FORMATTED-DATETIME (Enterprise COBOL for z/OS
Language Reference)

HEX-OF Alphanumeric HEX-OF (Enterprise COBOL for z/OS Language Reference)

Chapter 7. Processing data in an international environment 127

Table 16. Intrinsic functions and national character data (continued)
Intrinsic function Function type For more information
INTEGER-OF-FORMATTED- Integer INTEGRE-OF-FORMATTED-DATE (Enterprise COBOL for
DATE z/OS Language Reference)
LENGTH Integer “Finding the length of data items” on page 120
LOWER-CASE, UPPER-CASE National “Changing case (UPPER-CASE, LOWER-CASE)” on page
114
NUMVAL, NUMVAL-C, NUMVAL- Numeric “Converting to numbers (NUMVAL, NUMVAL-C, NUMVAL-
F F)” on page 115
MAX, MIN National “Finding the largest or smallest data item” on page 118
ORD-MAX, ORD-MIN Integer “Finding the largest or smallest data item” on page 118
REVERSE Alphanumeric or REVERSE (Enterprise COBOL for z/OS Language Reference)
national
SECONDS-FORM- Numeric SECONDS-FROM-FORMATTED-TIME (Enterprise COBOL
FORMATTED-TIME for z/OS Language Reference)
TEST-FORMATTED- Integer TEST-FORMATTED-DATETIME (Enterprise COBOL for z/OS
DATETIME Language Reference)
TEST-NUMVAL, TEST- Integer • TEST-NUMVAL (Enterprise COBOL for z/OS Language
NUMVAL-C, TEST-NUMVAL-F Reference)
• TEST-NUMVAL-C (Enterprise COBOL for z/OS Language
Reference)
• TEST-NUMVAL-F (Enterprise COBOL for z/OS Language
Reference)

TRIM Alphanumeric or TRIM (Enterprise COBOL for z/OS Language Reference)

national
ULENGTH Integer ULENGTH (Enterprise COBOL for z/OS Language Reference)
UPOS Integer UPOS (Enterprise COBOL for z/OS Language Reference)
USUBSTR Alphanumeric or USUBSTR (Enterprise COBOL for z/OS Language Reference)
national
USUPPLEMENTARY Integer USUPPLEMENTARY (Enterprise COBOL for z/OS Language
Reference)
UVALID Integer UVALID (Enterprise COBOL for z/OS Language Reference)
UWIDTH Integer UWIDTH (Enterprise COBOL for z/OS Language Reference)

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 43
“Using national data (Unicode)
in COBOL” on page 129

Related references
Arguments (Enterprise COBOL for z/OS Language Reference)

128 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 Classes and categories of data (Enterprise COBOL for z/OS Language Reference)
Intrinsic functions (Enterprise COBOL for z/OS 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 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. 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 136

related references
“Storage of character data” on page 136
Character sets and code pages (Enterprise COBOL for z/OS Language Reference)

Using national data (Unicode) in COBOL

In Enterprise COBOL, you can specify national (UTF-16) data in any of several ways.
These types of national data are available:
• National data items (categories national, national-edited, and numeric-edited)
• National literals
• Figurative constants as national characters
• 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

Chapter 7. Processing data in an international environment 129

 of language characters” on page 129
“National groups” on page 132

related tasks
“Defining national data
items” on page 130
“Using national literals” on page 130
“Using national-character
figurative constants” on page 131
“Defining national numeric
data items” on page 132
“Using national groups” on page 133
“Converting to or from national (Unicode) representation” on page 136
“Comparing national (UTF-16)
data” on page 145

related references
“Storage of character data” on page 136
Classes and categories of data (Enterprise COBOL for z/OS Language Reference)

Defining national data items

Define national data items with the USAGE NATIONAL clause to hold national (UTF-16) character strings.

You can define national data items of the following categories:

• National
• National-edited
• 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:
• Symbol N
• 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 45

related references
“NSYMBOL” on page 335
BLANK WHEN ZERO clause (Enterprise COBOL for z/OS Language Reference)

Using national literals

To specify national literals, use the prefix character N and compile with the option NSYMBOL(NATIONAL).

130 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 You can use either of these notations:
• N"character-data"
• N'character-data'
If you compile with the option NSYMBOL(DBCS), the literal prefix character N specifies a DBCS literal, not
a national literal.
To specify a national literal as a hexadecimal value, use the prefix NX. You can use either of these
notations:
• NX"hexadecimal-digits"
• 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 NN usage national.

. . .
Move NX"00410042" to Y
Move N"AB" to Y
Move "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 25
related references
“NSYMBOL” on page 335
National literals (Enterprise COBOL for z/OS 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.

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 QUOTE in a context that requires national characters, and the
QUOTE compiler option is in effect, its value is NX'0022'. If the APOST compiler option is in effect, its
value is NX'0027'.
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

Chapter 7. Processing data in an international environment 131

 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:

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 136
“Comparing national (UTF-16)
data” on page 145
related references
Figurative constants (Enterprise COBOL for z/OS Language Reference)
DISPLAY-OF (Enterprise COBOL for z/OS 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.

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 43
“Displaying numeric data” on page 45

related references
SIGN clause (Enterprise COBOL for z/OS 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.
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.

132 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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:

• 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.
• 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.
• 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.
• 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 103
“Splitting data items (UNSTRING)” on page 105
“Tallying and replacing
data items (INSPECT)” on page 112
“Using national groups” on page 133

related references
GROUP-USAGE clause (Enterprise COBOL for z/OS Language Reference)

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.
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.

Chapter 7. Processing data in an international environment 133

 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 132
related tasks
“Using national groups
as elementary items” on page 134
“Using national groups
as group items” on page 135

related references
GROUP-USAGE clause (Enterprise COBOL for z/OS Language Reference)

Using national groups as elementary items

In most cases, you can use a national group as though it were an elementary data item.
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 Edited-date PIC NN/NN/NNNN USAGE NATIONAL.

01 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.

134 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
related tasks
“Assigning values to group
data items (MOVE)” on page 33
“Comparing national data
and alphanumeric-group operands” on page 147
“Using national groups
as group items” on page 135

related references
MOVE statement (Enterprise COBOL for z/OS 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.

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.

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 Elementary items within the
of the ADD, SUBTRACT, processing as a group in accordance national group are processed like
or MOVE statement with the rules of the CORRESPONDING elementary items that have USAGE
phrase. NATIONAL within an alphanumeric
group.
Host variable in EXEC Specify a national group item as a host The national group item is in effect
SQL statement variable. shorthand for the set of host
variables that are subordinate to
the group item.
INITIALIZE statement Specify a national group for processing Elementary items within the
as a group in accordance with the rules national group are initialized like
of the INITIALIZE statement. elementary items that have USAGE
NATIONAL within an alphanumeric
group.
Name qualification Use the name of a national group item Follow the same rules
to qualify the names of elementary data for qualification as for an
items and of subordinate group items in alphanumeric group.
the national group.
THROUGH phrase of the To specify a national group item in the The result is an alphanumeric
RENAMES clause THROUGH phrase, use the same rules as group item.
for an alphanumeric group item.

Chapter 7. Processing data in an international environment 135

 Table 17. National group items that are processed with group semantics (continued)
Language feature Uses of national group items Comment
FROM phrase of the XML Specify a national group item in the Elementary items within the
GENERATE statement FROM phrase for processing as a group national group are processed like
in accordance with the rules of the XML elementary items that have USAGE
GENERATE statement. NATIONAL within an alphanumeric
group.

related tasks
“Initializing a structure
(INITIALIZE)” on page 31
“Initializing a table (INITIALIZE)” on page 73
“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 120
“Generating XML output” on page 577
“Using national group items in SQL statements” on page 442
related references
Qualification (Enterprise COBOL for z/OS Language Reference)
RENAMES clause (Enterprise COBOL for z/OS 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
Encoding units per graphic 1 1 1 or 22
character
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:
• COBOL characters A-Z, a-z, 0-9, space, + - * / = $ , ; . " ( ) > < :'
• All characters that are converted from an EBCDIC or ASCII code page

related concepts
“Unicode and the encoding
of language characters” on page 129

Converting to or from national (Unicode) representation

You can implicitly or explicitly convert data items to national (UTF-16) representation.

136 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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)” on page 137
“Converting alphanumeric
or DBCS to national (NATIONAL-OF)” on page 138
“Converting national to
alphanumeric (DISPLAY-OF)” on page 138
“Overriding the default code page” on page 138
“Comparing national (UTF-16)
data” on page 145

related references
“CODEPAGE” on page 304
“Conversion exceptions” on page 139

Converting alphanumeric, DBCS, and integer to national (MOVE)

You can use a MOVE statement to implicitly convert data to national representation.

You can move the following kinds of data to category national or national-edited data items, and thus
convert the data to national representation:
• Alphabetic
• 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:
• Alphanumeric
• Display floating-point (floating-point of USAGE DISPLAY)
• Numeric-edited of USAGE DISPLAY
• 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'.

Chapter 7. Processing data in an international environment 137

 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 45
“Coding for use of DBCS support” on page 147

related references
MOVE statement (Enterprise COBOL for z/OS 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.
“Example: converting to and from national data” on page 139
related tasks
“Processing UTF-8 data” on page 140
“Processing Chinese GB 18030 data” on page 144
“Processing alphanumeric data items that contain DBCS data” on page 149

related references
“CODEPAGE” on page 304
NATIONAL-OF (Enterprise COBOL for z/OS 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.
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 139
related tasks
“Processing UTF-8 data” on page 140
“Processing Chinese GB 18030 data” on page 144

related references
DISPLAY-OF (Enterprise COBOL for z/OS 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.

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

138 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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 304

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.
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 304

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

Chapter 7. Processing data in an international environment 139

 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.
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”
on page 140.
Take the following steps to convert ASCII or 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.
The following example converts Greek EBCDIC data 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 109
“Converting to or from national (Unicode) representation” on page 136
“Parsing XML documents
encoded in UTF-8” on page 558
“Using intrinsic functions to process UTF-8 encoded data” on page 140

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.
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 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
To determine the total number of Unicode code points in the string

140 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
UPOS
To determine the byte position in the string of the nth Unicode code point
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:

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.

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':

x'6162D0B0E4BA8CF5646364'

The output from checkUTF-8-validity for this string is as follows:

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.

The following code fragment illustrates checking for the presence of a Unicode supplementary code point,
requiring a 4-byte representation in UTF-8:

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.

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'):

x'6162D0B0E4BA8CF0908C826364'

The output from checkUTF-8-supp for this string is as follows:

checkUTF-8-supp hit:
The 04th code point of the string, starting at byte 08,
is a Unicode supplementary code point, width 04 bytes.

related references
“CODEPAGE” on page 304

Example: deriving initials from UTF-8 names

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.

Chapter 7. Processing data in an international environment 141

 Program initials

142 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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')

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'.

Chapter 7. Processing data in an international environment 143

 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.
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.

Enterprise COBOL does not have explicit support for GB 18030, but does support the processing of GB
18030 characters in several ways. You can:

• Use DBCS data items to process GB 18030 characters that are represented in CCSID 1388.
• Use national data items to define and process GB 18030 characters that are represented in UTF-16,
CCSID 01200.
• 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:

144 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 related tasks
“Converting to or from national (Unicode) representation” on page 136
“Coding for use of DBCS support” on page 147

related references
“Storage of character data” on page 136

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.
You can code conditional expressions that use national data in the following statements:
• EVALUATE
• IF
• INSPECT
• PERFORM
• SEARCH
• STRING
• UNSTRING
For full details about comparing national data items to other data items, see the related references.

related tasks
“Comparing two class national
operands” on page 145
“Comparing class national
and class numeric operands” on page 146
“Comparing national numeric
and other numeric operands” on page 146
“Comparing national and
other character-string operands” on page 147
“Comparing national data
and alphanumeric-group operands” on page 147

related references
Relation conditions (Enterprise COBOL for z/OS Language Reference)
General relation conditions (Enterprise COBOL for z/OS Language Reference)
National comparisons (Enterprise COBOL for z/OS Language Reference)
Group comparisons (Enterprise COBOL for z/OS Language Reference)

Comparing two class national operands

You can compare the character values of two operands of class national.

Either operand (or both) can be any of the following types of items:
• A national group
• An elementary category national or national-edited data item

Chapter 7. Processing data in an international environment 145

 • 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 132

related tasks
“Using national groups” on page 133

related references
National comparisons (Enterprise COBOL for z/OS 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.

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 for z/OS 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.

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 132

related references
General relation conditions (Enterprise COBOL for z/OS Language Reference)

146 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
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.

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 131

related references
National comparisons (Enterprise COBOL for z/OS 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.

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 for z/OS 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).
The following list summarizes the support for DBCS:
• DBCS characters in user-defined words (DBCS names)
• DBCS characters in comments
• DBCS data items (defined with PICTURE N, G, or G and B)
• DBCS literals
• DBCS compiler option

Chapter 7. Processing data in an international environment 147

 related tasks
“Defining DBCS data” on page 148
“Using DBCS literals” on page 148
“Testing for valid DBCS
characters” on page 149
“Processing alphanumeric data items that contain DBCS data” on page 149
Appendix B, “Converting double-byte character set (DBCS) data,” on page 701

related references
“DBCS” on page 311

Defining DBCS data

Use the PICTURE and USAGE clauses to define 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.

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 definition 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 335

Using DBCS literals

You can use the prefix N or G to represent a DBCS literal.

That is, you can specify a DBCS literal in either of these ways:
• N'dbcs characters' (provided that the compiler option NSYMBOL(DBCS) is in effect)
• G'dbcs characters'
You can use quotation marks (") or apostrophes (') 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 26

148 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 related references
“APOST/QUOTE” on page 298
“DBCS” on page 311
“NSYMBOL” on page 335
DBCS literals (Enterprise COBOL for z/OS 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.

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 95

related references
Class condition (Enterprise COBOL for z/OS 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.
That is, do these steps:
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.

related tasks
“Joining data items (STRING)” on page 103
“Splitting data items (UNSTRING)” on page 105
“Referring to substrings
of data items” on page 109
“Converting to or from national (Unicode) representation” on page 136

Chapter 7. Processing data in an international environment 149

150 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Chapter 8. Processing files

Processing 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:
• Another program
• Hierarchical or relational database
• Messages from subsystem software
• Direct-access storage device
• Magnetic tape
• Printer
• Terminal
• Card reader or punch
The information as it exists on an external device might be 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” on page 151

related tasks
“Choosing file organization and access mode” on page 152
“Allocating files” on page 154
“Checking for input or output errors” on page 155

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.
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

© Copyright IBM Corp. 1991, 2023 151

 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. When you
read or write indexed files randomly, the sequence is in a programmer-specified manner. When you
read or write indexed files dynamically, the sequence is sequential or random or both, determined by
the input-output statements used.
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 you can use several types of file
organization:
• Sequential (VSAM or QSAM)
• Line sequential (z/OS UNIX)
• Indexed (VSAM)
• Relative (VSAM)

related tasks
“Allocating files” on page 154
Chapter 9, “Processing QSAM files,” on page 157
Chapter 10, “Processing VSAM files,” on page 179
Chapter 11, “Processing line-sequential files,” on page 205
“Choosing file organization and access mode” on page 152

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.
Consider the following guidelines when choosing file organization:

152 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 • 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.
• 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.
• 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.
• If an application inserts and deletes records randomly, a relative file works well.
Consider the following guidelines when choosing access mode:
• If a large percentage of a file is referenced or updated in an application, sequential access is faster than
random or dynamic access.
• 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 Random Dynamic Fixed length Variable
access access access 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 153
“Control characters in line-sequential files” on page 206

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

Chapter 8. Processing files 153

 . . .
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 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 157
Chapter 10, “Processing VSAM files,” on page 179
Chapter 11, “Processing line-sequential files,” on page 205

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.
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.

154 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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:
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:
• The contents (including a value of null or all blanks) of the environment variable are not valid.
• The dynamic allocation of the file fails.
• 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.
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 460
“Defining and allocating QSAM files” on page 170
“Dynamically creating QSAM files” on page 167
“Allocating VSAM files” on page 198

Checking for input or output errors

After each input or output statement is performed, the file status key is updated with a value that
indicates the success or failure of the operation.
Using a FILE STATUS clause, test the file status key after each input or output statement, and call an
error-handling procedure if a nonzero file status code is returned. With VSAM files, you can use a second
data 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 233
“Coding ERROR declaratives” on page 236
“Using file status keys” on page 237

Chapter 8. Processing files 155

156 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 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.
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:
• Identify and describe the QSAM files in the ENVIRONMENT DIVISION and the DATA DIVISION.
• 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” on page 157
“Coding input and output
statements for QSAM files” on page 166
“Handling errors in QSAM files” on page 169
“Working with QSAM files” on page 169
“Accessing z/OS UNIX files
using QSAM” on page 176
“Processing QSAM ASCII files on tape” on page 177

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.
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:

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” on page 158
“Setting block sizes” on page 164

© Copyright IBM Corp. 1991, 2023 157

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.
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” on page 158

related tasks
“Requesting fixed-length format” on page 158
“Requesting variable-length format” on page 159
“Requesting spanned format” on page 161
“Requesting undefined format” on page 163
“Defining QSAM files and records in COBOL” on page 157

related references
“FILE SECTION entries” on page 12

Logical records
COBOL uses the term logical record in a slightly different way than z/OS QSAM.
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 of format-F records” on page 159
“Layout of format-V records” on page 160
“Layout of format-S records” on page 162
“Layout of format-U records” on page 163

Requesting fixed-length format

Fixed-length records are in format F. Use RECORDING MODE F to explicitly request this format.
You can omit the RECORDING MODE clause. The compiler determines the recording mode to be F if the
length of the largest level-01 record associated with the file is not greater than the block size coded in the
BLOCK CONTAINS clause, and you take one of the following actions:
• Use the RECORD CONTAINS integer clause (format-1 RECORD clause) to indicate the length of the
record in bytes.

158 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.
• 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 158

related tasks
“Requesting variable-length format” on page 159
“Requesting spanned format” on page 161
“Requesting undefined format” on page 163
“Establishing record formats” on page 158

related references
“Layout of format-F records” on page 159

Layout of format-F records

The layout of format-F QSAM records is shown below.

related concepts
“Logical records” on page 158

related tasks
“Requesting fixed-length format” on page 158
z/OS DFSMS: Using Data Sets (Fixed-length record formats)

related references
“Layout of format-V records” on page 160
“Layout of format-S records” on page 162
“Layout of format-U records” on page 163

Requesting variable-length format

Variable-length records can be in format V or format D. Format-D records are variable-length records on
ASCII tape files. Format-D records are processed in the same way as format-V records.
Use RECORDING MODE V for both. You can omit the RECORDING MODE clause. The compiler determines
the recording mode to be V if the largest level-01 record associated with the file is not greater than the
block size set in the BLOCK CONTAINS clause, and you take one of the following actions:
• Use the RECORD IS VARYING clause (format-3 RECORD clause).

Chapter 9. Processing QSAM files 159

 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.
• 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.
• Omit the RECORD clause, but code multiple level-01 records (associated with the file) that are of
different sizes or contain an OCCURS DEPENDING ON clause.
The maximum record length is determined to be the size of the largest level-01 record description entry
associated with the file.
When you specify a READ INTO statement for a format-V file, the record size read for that file is used in
the MOVE statement generated by the compiler. Consequently, you might not get the result you expect if
the record just read does not correspond to the level-01 record description. All other rules of the MOVE
statement apply. For example, when you specify a MOVE statement for a format-V record read in by the
READ statement, the size of the record moved corresponds to its level-01 record description.
When you specify a READ statement for a format-V file followed by a MOVE of the level-01 record, the
actual record length is not used. The program will attempt to move the number of bytes described by
the level-01 record description. If this number exceeds the actual record length and extends outside
the area addressable by the program, results are unpredictable. If the number of bytes described by
the level-01 record description is shorter than the physical record read, truncation of bytes beyond the
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 158
“Requesting spanned format” on page 161
“Requesting undefined format” on page 163
“Establishing record formats” on page 158

related references
“FILE SECTION entries” on page 12
“Layout of format-V records” on page 160
Enterprise COBOL for z/OS 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.

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).

160 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 BB Represents 2 bytes reserved for system use.
cc
The first 4 bytes of each logical record contain control information.
ll Represents 2 bytes designating the logical record length (including the cc field).
bb Represents 2 bytes reserved for system use.
The block length is determined as follows:
• Unblocked format-V records: CC + cc + the data portion
• 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 158

related tasks
“Requesting variable-length format” on page 159

related references
“Layout of format-F records” on page 159
“Layout of format-S records” on page 162
“Layout of format-U records” on page 163

Requesting spanned format

Spanned records are in format S. A spanned record is a QSAM logical record that can be contained in one
or more physical blocks.
You can code RECORDING MODE S for spanned records in QSAM files 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:
• You can set block lengths to efficiently use track capacities on direct access devices.
• 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.
• 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.

Chapter 9. Processing QSAM files 161

 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 158
“Spanned blocked and unblocked files” on page 162

related tasks
“Requesting fixed-length format” on page 158
“Requesting variable-length format” on page 159
“Requesting undefined format” on page 163
“Establishing record formats” on page 158

related references
“FILE SECTION entries” on page 12
“Layout of format-S records” on page 162

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 158

related tasks
“Requesting spanned format” on page 161

Layout of format-S records

Spanned records are preceded by control fields, as explained below.

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 161

related references
“Layout of format-F records” on page 159

162 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
“Layout of format-V records” on page 160
“Layout of format-U records” on page 163

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.
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:
• 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.
• 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 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.
• 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.
• 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 158
“Requesting variable-length format” on page 159
“Requesting spanned format” on page 161
“Establishing record formats” on page 158

related references
“FILE SECTION entries” on page 12
“Layout of format-U records” on page 163

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.

Chapter 9. Processing QSAM files 163

 related concepts
“Logical records” on page 158

related tasks
“Requesting undefined format” on page 163

related references
“Layout of format-F records” on page 159
“Layout of format-V records” on page 160
“Layout of format-S records” on page 162

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.
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:
• Reading a block of records of fewer than 12 bytes
• 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:
• Code BLOCK CONTAINS 0 in your source program or compile with the BLOCK0 option. For details
about BLOCK0, see “BLOCK0” on page 302.
• Do not code RECORD CONTAINS 0 in your source program.
• 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:
• Code BLOCK CONTAINS 0 in your source program or compile with the BLOCK0 option.
• 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:

164 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
• Code BLOCK CONTAINS 0 in your source program or compile with the BLOCK0 option.
• Not code a BLKSIZE value in the ddname definition.
When you omit the BLKSIZE from the ddname definition, the block size is automatically obtained by the
system from the data-set label.
Taking advantage of LBI: You can improve the performance of tape data sets by using 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:
• Spanned records
• 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:
• The BLKSZLIM keyword on the DD statement for the data set
• BLKSZLIM for the data class by using the BLKSZLIM keyword (must be set by your systems
programmer)
• 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:
• Specify a BLKSZLIM value greater than 32760 in the DD statement for the file and use BLOCK
CONTAINS 0 in your COBOL source.
• 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:
• 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.
• The T (track overflow) option for QSAM files is no longer useful.

related tasks
“Defining QSAM files and records in COBOL” on page 157
z/OS DFSMS: Using Data Sets

related references
“FILE SECTION entries” on page 12
“BLOCK0” on page 302
BLOCK CONTAINS clause (Enterprise COBOL for z/OS Language Reference)

Chapter 9. Processing QSAM files 165

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.
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” on page 166
“Dynamically creating QSAM files” on page 167
“Adding records to QSAM
files” on page 167
“Updating QSAM files” on page 167
“Writing QSAM files to a
printer or spooled data set” on page 168
“Closing QSAM files” on page 168

related references
OPEN statement (Enterprise COBOL for z/OS Language Reference)
READ statement (Enterprise COBOL for z/OS Language Reference)
WRITE statement (Enterprise COBOL for z/OS Language Reference)
REWRITE statement (Enterprise COBOL for z/OS Language Reference)
CLOSE statement (Enterprise COBOL for z/OS Language Reference)
File status key (Enterprise COBOL for z/OS 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.
An OPEN statement works if both of the following conditions are true:
• The file is available or has been dynamically allocated.
• 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.

166 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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” on page 167
“Ensuring that file attributes match your program” on page 173

related references
OPEN statement (Enterprise COBOL for z/OS 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.
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:
• 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.
• The file is being opened for OUTPUT, regardless of the OPTIONAL phrase.
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 166

Adding records to QSAM files

To add to a QSAM file, open the file as EXTEND and use the WRITE statement to add records immediately
after the last record in the file.
To add records to a file opened as I-O, you must first close the file and open it as EXTEND.

related references
READ statement (Enterprise COBOL for z/OS Language Reference)
WRITE statement (Enterprise COBOL for z/OS 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.
Replace an existing record with another record of the same length by doing these steps:

Chapter 9. Processing QSAM files 167

 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.)

You cannot open as I-O an extended format data set that you allocate in compressed format.

related references
REWRITE statement (Enterprise COBOL for z/OS Language Reference)

Writing QSAM files to a printer or spooled data set

COBOL provides language statements to control the size of a printed page and control the vertical
positioning of records.

Controlling the page size: Use the LINAGE clause of the FD entry to control the size of your printed page:
the number of lines in the top and bottom margins and in the footing area of the page. When you use the
LINAGE clause, COBOL handles the file as if you had also requested the ADV compiler option.
If you use the LINAGE clause in combination with WRITE BEFORE|AFTER ADVANCING nn LINES, be
careful about the values you set. With the ADVANCING nn LINES 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 for z/OS 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.
If you do not close a QSAM file, the file is automatically closed for you under the following conditions:
• When the run unit ends normally, the run time closes all open files that are defined in any COBOL
programs in the run unit.
• 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.
• 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.

168 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.
• When you use CANCEL for a COBOL subprogram, the run time closes any open nonexternal files that are
defined in that program.
• When a COBOL subprogram with the INITIAL attribute returns control, the run time closes any open
nonexternal files that are defined in that program.
• 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 for z/OS 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.

COBOL provides these ways for you to intercept and handle certain QSAM input and output errors:
• End-of-file phrase (AT END)
• EXCEPTION/ERROR declarative
• FILE STATUS clause
• 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 233

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.

related tasks
“Defining and allocating QSAM files” on page 170
“Retrieving QSAM files” on page 172

Chapter 9. Processing QSAM files 169

 “Ensuring that file attributes match your program” on page 173
“Using striped extended-format QSAM data sets” on page 175

related references
“Allocation of buffers for QSAM files” on page 176

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.
When you use an environment variable, the name must be in uppercase. Specify the MVS data set in one
of these ways:
• DSN(data-set-name)
• 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:
• A disposition value, one of: NEW, OLD, SHR, or MOD
• TRACKS or CYL
• SPACE(nnn,mmm)
• VOL(volume-serial)
• UNIT(type)
• KEEP, DELETE, CATALOG, or UNCATALOG
• STORCLAS(storage-class)
• MGMTCLAS(management-class)
• DATACLAS(data-class)
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:
• A DD allocation that uses PATH='absolute-path-name' and FILEDATA=BINARY
• An environment variable with a value PATH(pathname), where pathname is an absolute path name
(starting with /)
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- UNIT UNIT for type only
output devices to be allocated for the
file.

170 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Table 20. QSAM file allocation (continued)
What you want to do DD parameter to use EV keyword to use
Give instructions for the volume in which VOLUME (or let the system VOL
the file will reside and for volume choose an output volume)
mounting.
Allocate the type and amount of space SPACE SPACE for the amount of
the file needs. (Only for direct-access space (primary and secondary
storage devices.) only); TRACKS or CYL for the
type of space
Specify the type and some of the LABEL n/a
contents of the label associated with the
file.
Indicate whether you want to catalog, DISP NEW, OLD, SHR, MOD plus
pass, or keep the file after the job step is KEEP, DELETE, CATALOG, or
completed. UNCATALOG
Complete any data control block DCB subparameters n/a
information that you want to add.

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:
• Block size (BLKSIZE=), if BLOCK CONTAINS 0 RECORDS or BLOCK0 option was specified at compile
time (recommended)
• Options to be executed if an error occurs in reading or writing a record
• TRACK OVERFLOW or standard blocks
• 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.
“Example: setting and accessing environment variables” on page 462

related tasks
“Setting block sizes” on page 164
“Defining QSAM files and records in COBOL” on page 157
“Allocating files” on page 154

related references
“BLOCK0” on page 302
“Parameters for creating QSAM files” on page 172
MVS Program Management: User's Guide and Reference

Chapter 9. Processing QSAM files 171

 Parameters for creating QSAM files
The following DD statement parameters are frequently used to create QSAM files.

related tasks
“Defining and allocating QSAM files” on page 170

Retrieving QSAM files

You retrieve QSAM files, cataloged or not, by using job control statements or environment variables.
Cataloged files
All data set information, such as volume and space, is stored in the catalog and file label. All you have
to code are the data set name and a disposition. When you use a DD statement, this is the DSNAME
parameter and the DISP parameter. When you use an environment variable, this is the DSN parameter
and one of the parameters OLD, SHR, or MOD.
Noncataloged files
Some information is stored in the file label, but you must code the unit and volume information, 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” on page 173

172 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 Parameters for retrieving QSAM files
The following DD statement parameters are used to retrieve previously created files.

related tasks
“Retrieving QSAM files” on page 172

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.
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.

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” on page 174
“Processing new files” on page 175
“Opening QSAM files” on page 166

related references
“FILE SECTION entries” on page 12

Chapter 9. Processing QSAM files 173

 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.

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).

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” on page 175
“Requesting fixed-length format” on page 158
“Requesting variable-length format” on page 159
“Requesting undefined format” on page 163
“Opening QSAM files” on page 166

related references
“FILE SECTION entries” on page 12

174 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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.
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:
• For format-V and format-S files, set a length attribute that is 4 bytes larger than that defined in the
program.
• For format-F and format-U files, set a length attribute that is the same as that defined in the program.
• 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 174
“Requesting fixed-length format” on page 158
“Requesting variable-length format” on page 159
“Requesting undefined format” on page 163
“Opening QSAM files” on page 166
“Dynamically creating QSAM files” on page 167

related references
“FILE SECTION entries” on page 12

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.
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:
• Avoid using a QSAM striped data set for a file that cannot have buffers allocated above the 16 MB line.
• 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.
• Compile your program with the DATA(31) and RENT compiler options, and make the program object
AMODE 31.
• Specify the ALL31(ON) runtime option if the file is an EXTERNAL file with format-F, format-V, or
format-U records.

Chapter 9. Processing QSAM files 175

 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:
• Programs running in AMODE 24.
• Programs compiled with the DATA(24) and RENT options.
• Programs compiled with the NORENT option.
• 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.
• Files allocated to the TSO terminal.
• 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

related concepts
“Storage and its addressability” on page 39

related tasks
“Using striped extended-format QSAM data sets” on page 175

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.
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:
• Spanned record format is not supported.
• 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
• 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)
• 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.

176 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
 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 154
“Defining and allocating QSAM files” on page 170
z/OS DFSMS: Using Data Sets (Using HFS data sets)

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).
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:
• 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:
• For input, from 0 through 99
• For output, either 0 or 4
Use this value if you coded BLOCK CONTAINS 0.

Chapter 9. Processing QSAM files 177

 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
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)

178 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 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.
VSAM processing has these advantages over QSAM:
• Protection of data against unauthorized access
• Compatibility across systems
• Independence of devices (no need to be concerned with block size and other control information)
• Simpler JCL (information needed by the system is provided in integrated catalogs)
• 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 180

related tasks
“Defining VSAM file organization and records” on page 181
“Coding input and output
statements for VSAM files” on page 186
“Handling errors in VSAM files” on page 194
“Protecting VSAM files with a password” on page 194
“Working with VSAM data sets under z/OS and z/OS UNIX” on page 195
“Improving VSAM performance” on page 201

© Copyright IBM Corp. 1991, 2023 179

 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 201
“Extended addressability support” on page 202

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.
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

Characteristic Entry-sequenced data Key-sequenced data set Relative-record data set
set (ESDS) (KSDS) (RRDS)
Order of records Order in which they are Collating sequence by key Order of relative record
written field number
Access Sequential By key through an index By relative record number,
which is handled like a key

180 Enterprise COBOL for z/OS: Enterprise COBOL for z/OS, V6.2 Programming Guide
Table 23. Comparison of VSAM data-set types (continued)
Characteristic Entry-sequenced data Key-sequenced data set Relative-record data set
set (ESDS) (KSDS) (RRDS)
Alternate indexes Can have one or Can have one or more Cannot have alternate
more alternate indexes, alternate indexes indexes
although not supported in
COBOL
Relative byte RBA cannot change. RBA can change. RRN cannot change.
address (RBA) and
relative record
number (RRN) of a
record
Space for adding Uses space at the end of Uses distributed free space For fixed-length RRDS, uses
records the data set for inserting records and empty slots in the data set
changing their lengths in
For variable-length RRDS,
place
uses distributed free space
and changes the lengths of
added records in place

Space from deleting You cannot delete a Space from a deleted Space from a deleted record
records record, but you can reuse or shortened record is can be reused.
its space for a record of automatically reclaimed in a
the same length. control interval.
Spanned records Can have spanned records Can have spanned records Cannot have spanned records
Reuse as work file Can be reused unless it Can be reused unless it Can be reused
has an alternate index, has an alternate index, is
is associated with key associated with key ranges,
ranges, or exceeds 123 or exceeds 123 extents per
extents per volume volume

related tasks
“Specifying sequential organization for VSAM files” on page 182
“Specifying indexed organization
for VSAM files” on page 182
“Specifying relative organization for VSAM files” on page 183
“Defining VSAM files” on page 196

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.
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.<