Enterprise COBOL for z/OS IBM

Language Reference
Version 6.1

SC27-8713-00
Enterprise COBOL for z/OS IBM

Language Reference
Version 6.1

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

Fifth edition (September 2017)

| This edition applies to Version 6 Release 1 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 at www.ibm.com/shop/publications/order/.
© Copyright IBM Corporation 1991, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
 Contents
Tables . . . . . . . . . . . . . . . ix XML-EVENT . . . . . . . . . . . . . 26
XML-INFORMATION . . . . . . . . . . 32
Preface . . . . . . . . . . . . . . . xi XML-NAMESPACE. . . . . . . . . . . 33
XML-NNAMESPACE . . . . . . . . . . 34
About this information. . . . . . . . . . . xi
XML-NAMESPACE-PREFIX . . . . . . . . 34
How to read the syntax diagrams . . . . . . xi
XML-NNAMESPACE-PREFIX . . . . . . . 35
IBM extensions . . . . . . . . . . . . xiv
XML-NTEXT . . . . . . . . . . . . . 36
Obsolete language elements . . . . . . . xiv
XML-TEXT . . . . . . . . . . . . . 37
DBCS notation . . . . . . . . . . . . xv
Literals . . . . . . . . . . . . . . . . 37
Acknowledgment . . . . . . . . . . . xv
Alphanumeric literals . . . . . . . . . . 37
Additional documentation and support . . . . . xvi
Numeric literals . . . . . . . . . . . . 41
Summary of changes . . . . . . . . . . . xvi
DBCS literals . . . . . . . . . . . . . 42
| Version 6 Release 1 with PTF for APAR PI71621
National literals . . . . . . . . . . . . 43
| installed . . . . . . . . . . . . . . xvi
PICTURE character-strings . . . . . . . . . 46
| Version 6 Release 1 . . . . . . . . . . xvi
Comments. . . . . . . . . . . . . . . 46
Version 5 Release 2 . . . . . . . . . . xvi
Version 5 Release 1 Modification 1 . . . . . xvii
Version 5 Release 1 . . . . . . . . . . xvii Chapter 4. Separators . . . . . . . . 49
How to send your comments . . . . . . . . xviii Rules for separators . . . . . . . . . . . 49

Part 1. COBOL language structure . . 1 Chapter 5. Sections and paragraphs . . 53

Sentences, statements, and entries . . . . . . . 53
Entries . . . . . . . . . . . . . . . 54
Chapter 1. Characters . . . . . . . . . 3 Clauses . . . . . . . . . . . . . . . 54
Sentences . . . . . . . . . . . . . . 54
Chapter 2. Character sets and code Statements. . . . . . . . . . . . . . 54
pages. . . . . . . . . . . . . . . . 5 Phrases . . . . . . . . . . . . . . . 54
Character encoding units . . . . . . . . . . 5
Chapter 6. Reference format . . . . . 55
Chapter 3. Character-strings: COBOL Sequence number area. . . . . . . . . . . 55
words and literals . . . . . . . . . . 9 Indicator area. . . . . . . . . . . . . . 55
COBOL words with single-byte characters . . . . 9 Area A . . . . . . . . . . . . . . . . 56
User-defined words with DBCS characters . . . . 10 Division headers. . . . . . . . . . . . 56
User-defined words. . . . . . . . . . . . 10 Section headers . . . . . . . . . . . . 56
System-names . . . . . . . . . . . . . 12 Paragraph headers or paragraph names . . . . 56
Function-names . . . . . . . . . . . . . 12 Level indicators (FD and SD) or level-numbers
Reserved words . . . . . . . . . . . . . 12 (01 and 77) . . . . . . . . . . . . . 57
Figurative constants . . . . . . . . . . . 13 DECLARATIVES and END DECLARATIVES . . 57
Special registers . . . . . . . . . . . . . 16 End program, end class, and end method
ADDRESS OF . . . . . . . . . . . . 17 markers . . . . . . . . . . . . . . 57
DEBUG-ITEM . . . . . . . . . . . . 17 Area B . . . . . . . . . . . . . . . . 58
JNIENVPTR . . . . . . . . . . . . . 19 Entries, sentences, statements, clauses . . . . 58
| JSON-CODE . . . . . . . . . . . . . 19 Continuation lines . . . . . . . . . . . 58
LENGTH OF . . . . . . . . . . . . . 19 Area A or Area B . . . . . . . . . . . . 60
LINAGE-COUNTER . . . . . . . . . . 20 Level-numbers . . . . . . . . . . . . 60
RETURN-CODE . . . . . . . . . . . . 21 Comment lines . . . . . . . . . . . . 60
SHIFT-OUT and SHIFT-IN . . . . . . . . 22 Floating comment indicators (*>) . . . . . . 61
SORT-CONTROL . . . . . . . . . . . 22 Compiler-directing statements . . . . . . . 61
SORT-CORE-SIZE . . . . . . . . . . . 23 Compiler directives . . . . . . . . . . . 61
SORT-FILE-SIZE . . . . . . . . . . . . 23 Debugging lines . . . . . . . . . . . . 61
SORT-MESSAGE . . . . . . . . . . . 24 Pseudo-text . . . . . . . . . . . . . 62
SORT-MODE-SIZE . . . . . . . . . . . 24 Blank lines . . . . . . . . . . . . . 62
SORT-RETURN . . . . . . . . . . . . 24
TALLY . . . . . . . . . . . . . . . 25 Chapter 7. Scope of names . . . . . . 63
WHEN-COMPILED . . . . . . . . . . 25 Types of names . . . . . . . . . . . . . 63
XML-CODE . . . . . . . . . . . . . 25 External and internal resources . . . . . . . . 65

© Copyright IBM Corp. 1991, 2017 iii

Resolution of names . . . . . . . . . . . 66 DECIMAL-POINT IS COMMA clause . . . . . 124
XML-SCHEMA clause . . . . . . . . . . 124
Chapter 8. Referencing data names, REPOSITORY paragraph . . . . . . . . . 125
copy libraries, and PROCEDURE General rules . . . . . . . . . . . . 126
Identifying and referencing a class . . . . . 127
DIVISION names . . . . . . . . . . 69
Uniqueness of reference . . . . . . . . . . 69
Qualification . . . . . . . . . . . . . 69
Chapter 15. Input-Output section . . . 129
Identical names . . . . . . . . . . . . 70 FILE-CONTROL paragraph. . . . . . . . . 130
References to COPY libraries . . . . . . . 70 SELECT clause . . . . . . . . . . . . . 134
References to PROCEDURE DIVISION names . . 71 ASSIGN clause . . . . . . . . . . . . . 134
References to DATA DIVISION names . . . . 71 RESERVE clause . . . . . . . . . . . . 139
Condition-name . . . . . . . . . . . . 74 ORGANIZATION clause . . . . . . . . . 139
Index-name . . . . . . . . . . . . . 75 File organization . . . . . . . . . . . 139
Index data item . . . . . . . . . . . . 75 PADDING CHARACTER clause . . . . . . . 141
Subscripting . . . . . . . . . . . . . 75 RECORD DELIMITER clause . . . . . . . . 142
Reference modification . . . . . . . . . 79 ACCESS MODE clause . . . . . . . . . . 142
Function-identifier . . . . . . . . . . . 81 File organization and access modes . . . . . 143
Data attribute specification . . . . . . . . . 82 Access modes . . . . . . . . . . . . 143
Relationship between data organizations and
access modes . . . . . . . . . . . . 143
Chapter 9. Transfer of control . . . . . 83 RECORD KEY clause . . . . . . . . . . . 144
ALTERNATE RECORD KEY clause . . . . . . 145
Part 2. COBOL source unit RELATIVE KEY clause . . . . . . . . . . 146
structure . . . . . . . . . . . . . 85 PASSWORD clause . . . . . . . . . . . 147
FILE STATUS clause . . . . . . . . . . . 147
I-O-CONTROL paragraph . . . . . . . . . 148
Chapter 10. COBOL program structure 87 RERUN clause . . . . . . . . . . . . . 150
Nested programs . . . . . . . . . . . . 89 SAME AREA clause . . . . . . . . . . . 151
Conventions for program-names . . . . . . 90 SAME RECORD AREA clause . . . . . . . . 152
SAME SORT AREA clause . . . . . . . . . 153
Chapter 11. COBOL class definition SAME SORT-MERGE AREA clause . . . . . . 153
structure . . . . . . . . . . . . . . 93 MULTIPLE FILE TAPE clause . . . . . . . . 153
APPLY WRITE-ONLY clause . . . . . . . . 153
Chapter 12. COBOL method definition
structure . . . . . . . . . . . . . . 97 Part 5. Data division . . . . . . . 155

Part 3. Identification division . . . . 99 Chapter 16. DATA DIVISION overview 157

FILE SECTION . . . . . . . . . . . . . 158
WORKING-STORAGE SECTION . . . . . . . 159
Chapter 13. IDENTIFICATION DIVISION 101 LOCAL-STORAGE SECTION . . . . . . . . 160
PROGRAM-ID paragraph . . . . . . . . . 104 LINKAGE SECTION . . . . . . . . . . . 161
CLASS-ID paragraph . . . . . . . . . . . 107 Data units . . . . . . . . . . . . . . 161
General rules . . . . . . . . . . . . 107 File data . . . . . . . . . . . . . . 161
Inheritance . . . . . . . . . . . . . 107 Program data . . . . . . . . . . . . 162
FACTORY paragraph . . . . . . . . . . . 108 Method data . . . . . . . . . . . . 162
OBJECT paragraph . . . . . . . . . . . 108 Factory data . . . . . . . . . . . . . 162
METHOD-ID paragraph . . . . . . . . . . 108 Instance data . . . . . . . . . . . . 162
Optional paragraphs . . . . . . . . . . . 109 Data relationships . . . . . . . . . . . . 162
Levels of data . . . . . . . . . . . . 163
Part 4. Environment division . . . 111 Levels of data in a record description entry . . 163
Special level-numbers . . . . . . . . . 165
Chapter 14. Configuration section . . 113 Indentation . . . . . . . . . . . . . 165
Classes and categories of group items . . . . 165
SOURCE-COMPUTER paragraph. . . . . . . 114
Classes and categories of data . . . . . . . 166
OBJECT-COMPUTER paragraph . . . . . . . 114
Category descriptions . . . . . . . . . 168
SPECIAL-NAMES paragraph . . . . . . . . 116
Alignment rules . . . . . . . . . . . 170
ALPHABET clause . . . . . . . . . . . 119
Character-string and item size . . . . . . . 171
SYMBOLIC CHARACTERS clause . . . . . . 121
Signed data . . . . . . . . . . . . . 172
CLASS clause . . . . . . . . . . . . . 122
Operational signs . . . . . . . . . . . 172
CURRENCY SIGN clause . . . . . . . . . 122
Editing signs . . . . . . . . . . . . 172

iv Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 17. DATA DIVISION--file FUNCTION-POINTER phrase . . . . . . . 238
description entries . . . . . . . . . 173 INDEX phrase . . . . . . . . . . . . 238
FILE SECTION . . . . . . . . . . . . . 178 NATIONAL phrase . . . . . . . . . . 239
EXTERNAL clause . . . . . . . . . . . 178 OBJECT REFERENCE phrase . . . . . . . 239
GLOBAL clause . . . . . . . . . . . . 179 POINTER phrase . . . . . . . . . . . 240
BLOCK CONTAINS clause . . . . . . . . . 179 PROCEDURE-POINTER phrase . . . . . . 240
RECORD clause . . . . . . . . . . . . 181 NATIVE phrase . . . . . . . . . . . 241
Format 1 . . . . . . . . . . . . . . 181 VALUE clause . . . . . . . . . . . . . 241
Format 2 . . . . . . . . . . . . . . 182 Format 1 . . . . . . . . . . . . . . 242
Format 3 . . . . . . . . . . . . . . 182 Format 2 . . . . . . . . . . . . . . 244
LABEL RECORDS clause . . . . . . . . . 183 Format 3 . . . . . . . . . . . . . . 247
VALUE OF clause . . . . . . . . . . . . 184 VOLATILE clause . . . . . . . . . . . . 247
DATA RECORDS clause . . . . . . . . . . 184
LINAGE clause. . . . . . . . . . . . . 184 Part 6. Procedure division. . . . . 251
LINAGE-COUNTER special register . . . . . 186
RECORDING MODE clause . . . . . . . . 186 Chapter 19. Procedure division
CODE-SET clause . . . . . . . . . . . . 187
structure . . . . . . . . . . . . . 253
Requirements for a method procedure division . . 254
Chapter 18. DATA DIVISION--data The PROCEDURE DIVISION header . . . . . 255
description entry . . . . . . . . . . 189 The USING phrase . . . . . . . . . . 256
Format 1 . . . . . . . . . . . . . . . 189 RETURNING phrase . . . . . . . . . . 258
Format 2 . . . . . . . . . . . . . . . 189 References to items in the LINKAGE SECTION 258
Format 3 . . . . . . . . . . . . . . . 190 Declaratives . . . . . . . . . . . . . . 259
Level-numbers . . . . . . . . . . . . . 190 Procedures . . . . . . . . . . . . . . 260
BLANK WHEN ZERO clause . . . . . . . . 192 Arithmetic expressions . . . . . . . . . . 261
EXTERNAL clause . . . . . . . . . . . 192 Arithmetic operators . . . . . . . . . . 262
GLOBAL clause . . . . . . . . . . . . 193 Conditional expressions . . . . . . . . . . 264
JUSTIFIED clause . . . . . . . . . . . . 193 Simple conditions . . . . . . . . . . . 264
GROUP-USAGE clause . . . . . . . . . . 194 Class condition . . . . . . . . . . . . 264
OCCURS clause . . . . . . . . . . . . 195 Condition-name condition . . . . . . . . 266
Fixed-length tables . . . . . . . . . . 196 Relation conditions . . . . . . . . . . 267
ASCENDING KEY and DESCENDING KEY General relation conditions . . . . . . . . 268
phrases . . . . . . . . . . . . . . 197 Data pointer relation conditions . . . . . . 275
INDEXED BY phrase . . . . . . . . . . 199 Procedure-pointer and function-pointer relation
Variable-length tables. . . . . . . . . . 199 conditions . . . . . . . . . . . . . 276
OCCURS DEPENDING ON clause . . . . . 201 Object-reference relation conditions . . . . . 277
PICTURE clause . . . . . . . . . . . . 203 Sign condition . . . . . . . . . . . . 278
Symbols used in the PICTURE clause . . . . 204 Switch-status condition . . . . . . . . . 278
Character-string representation . . . . . . 208 Complex conditions . . . . . . . . . . 279
Data categories and PICTURE rules . . . . . 209 Negated simple conditions . . . . . . . . 279
PICTURE clause editing . . . . . . . . . 215 Combined conditions . . . . . . . . . . 280
Simple insertion editing . . . . . . . . . 216 Abbreviated combined relation conditions . . . 282
Special insertion editing . . . . . . . . . 217 Statement categories . . . . . . . . . . . 284
Fixed insertion editing . . . . . . . . . 217 Imperative statements . . . . . . . . . 284
Floating insertion editing . . . . . . . . 218 Conditional statements . . . . . . . . . 286
Zero suppression and replacement editing. . . 219 Delimited scope statements. . . . . . . . 288
REDEFINES clause . . . . . . . . . . . 221 Explicit scope terminators . . . . . . . . 288
REDEFINES clause considerations . . . . . 222 Implicit scope terminators . . . . . . . . 289
REDEFINES clause examples . . . . . . . 223 Compiler-directing statements . . . . . . . 289
Undefined results . . . . . . . . . . . 224 Statement operations . . . . . . . . . . . 289
RENAMES clause . . . . . . . . . . . . 224 CORRESPONDING phrase . . . . . . . . 289
SIGN clause . . . . . . . . . . . . . . 226 GIVING phrase. . . . . . . . . . . . 291
SYNCHRONIZED clause . . . . . . . . . 228 ROUNDED phrase . . . . . . . . . . 291
Slack bytes . . . . . . . . . . . . . 230 SIZE ERROR phrases . . . . . . . . . . 291
Slack bytes within records . . . . . . . . 230 Arithmetic statements . . . . . . . . . 293
Slack bytes between records . . . . . . . 232 Arithmetic statement operands . . . . . . 293
USAGE clause . . . . . . . . . . . . . 233 Data manipulation statements . . . . . . . 294
Computational items . . . . . . . . . . 235 Input-output statements . . . . . . . . . 294
DISPLAY phrase . . . . . . . . . . . 237 Common processing facilities . . . . . . . 295
DISPLAY-1 phrase . . . . . . . . . . . 238

Contents v
 Chapter 20. PROCEDURE DIVISION MOVE statement . . . . . . . . . . . . 393
statements . . . . . . . . . . . . 303 Elementary moves. . . . . . . . . . . 394
ACCEPT statement . . . . . . . . . . . 304 Moves involving file record areas. . . . . . 398
Data transfer . . . . . . . . . . . . 304 Group moves . . . . . . . . . . . . 398
System date-related information transfer . . . 305 MULTIPLY statement . . . . . . . . . . . 400
DATE, DATE YYYYMMDD, DAY, DAY OPEN statement . . . . . . . . . . . . 403
YYYYDDD, DAY-OF-WEEK, and TIME. . . . 306 General rules . . . . . . . . . . . . 405
ADD statement . . . . . . . . . . . . . 308 OPEN statement notes . . . . . . . . . 406
| ALLOCATE statement . . . . . . . . . . 310 PERFORM statement . . . . . . . . . . . 408
| Example: ALLOCATE and FREE storage for Basic PERFORM statement . . . . . . . . 410
| UNBOUNDED tables. . . . . . . . . . 312 PERFORM with TIMES phrase . . . . . . 411
ALTER statement . . . . . . . . . . . . 314 PERFORM with UNTIL phrase . . . . . . 412
Segmentation considerations . . . . . . . 314 PERFORM with VARYING phrase . . . . . 413
CALL statement . . . . . . . . . . . . 316 READ statement . . . . . . . . . . . . 420
CANCEL statement . . . . . . . . . . . 324 Processing files with variable-length records or
CLOSE statement . . . . . . . . . . . . 326 multiple record descriptions . . . . . . . 422
Effect of CLOSE statement on file types . . . 327 Sequential access mode . . . . . . . . . 423
COMPUTE statement. . . . . . . . . . . 330 Random access mode. . . . . . . . . . 425
CONTINUE statement . . . . . . . . . . 332 Dynamic access mode . . . . . . . . . 425
DELETE statement . . . . . . . . . . . 333 READ statement notes . . . . . . . . . 425
DISPLAY statement . . . . . . . . . . . 335 RELEASE statement . . . . . . . . . . . 427
DIVIDE statement . . . . . . . . . . . . 338 RETURN statement . . . . . . . . . . . 429
ENTRY statement . . . . . . . . . . . . 343 REWRITE statement . . . . . . . . . . . 431
EVALUATE statement . . . . . . . . . . 344 Reusing a logical record . . . . . . . . . 432
Determining values . . . . . . . . . . 345 Sequential files . . . . . . . . . . . . 432
Comparing selection subjects and objects . . . 346 Indexed files . . . . . . . . . . . . 432
Executing the EVALUATE statement . . . . 347 Relative files. . . . . . . . . . . . . 433
EXIT statement . . . . . . . . . . . . . 348 SEARCH statement . . . . . . . . . . . 434
Format 1 (simple) . . . . . . . . . . . 348 Serial search . . . . . . . . . . . . . 435
Format 2 (program) . . . . . . . . . . 349 Binary search . . . . . . . . . . . . 438
Format 3 (method) . . . . . . . . . . 350 Search statement considerations . . . . . . 440
Format 5 (inline-perform) . . . . . . . . 350 SET statement . . . . . . . . . . . . . 441
Format 6 (procedure) . . . . . . . . . . 351 Format 1: SET for basic table handling . . . . 441
| FREE statement . . . . . . . . . . . . 351 Format 2: SET for adjusting indexes . . . . . 442
GOBACK statement . . . . . . . . . . . 353 Format 3: SET for external switches . . . . . 443
GO TO statement . . . . . . . . . . . . 354 Format 4: SET for condition-names . . . . . 443
Unconditional GO TO . . . . . . . . . 354 Format 5: SET for USAGE IS POINTER data
Conditional GO TO . . . . . . . . . . 354 items . . . . . . . . . . . . . . . 444
Altered GO TO . . . . . . . . . . . . 355 Format 6: SET for procedure-pointer and
IF statement . . . . . . . . . . . . . . 356 function-pointer data items . . . . . . . . 445
Transferring control . . . . . . . . . . 357 Format 7: SET for USAGE OBJECT REFERENCE
Nested IF statements . . . . . . . . . . 357 data items . . . . . . . . . . . . . 446
INITIALIZE statement . . . . . . . . . . 358 SORT statement . . . . . . . . . . . . 448
INITIALIZE statement rules . . . . . . . 360 SORT special registers . . . . . . . . . 456
INSPECT statement . . . . . . . . . . . 362 Segmentation considerations . . . . . . . 456
Data flow . . . . . . . . . . . . . 369 START statement . . . . . . . . . . . . 458
Comparison cycle . . . . . . . . . . . 370 Indexed files . . . . . . . . . . . . 459
Example of the INSPECT statement . . . . . 370 Relative files. . . . . . . . . . . . . 460
INVOKE statement . . . . . . . . . . . 372 STOP statement . . . . . . . . . . . . 461
Interoperable data types for COBOL and Java 377 STRING statement. . . . . . . . . . . . 462
Miscellaneous argument types for COBOL and Data flow . . . . . . . . . . . . . 464
Java . . . . . . . . . . . . . . . 378 Example of the STRING statement . . . . . 465
| JSON GENERATE statement . . . . . . . . 380 SUBTRACT statement . . . . . . . . . . 467
| Nested JSON GENERATE statements . . . . 384 UNSTRING statement . . . . . . . . . . 470
| Operation of JSON GENERATE . . . . . . 384 Data flow . . . . . . . . . . . . . 474
| Format conversion of elementary data . . . . 385 Values at the end of execution of the
| Trimming of generated JSON data . . . . . 387 UNSTRING statement . . . . . . . . . 476
| JSON name formation . . . . . . . . . 387 Example of the UNSTRING statement . . . . 476
MERGE statement . . . . . . . . . . . . 388 WRITE statement . . . . . . . . . . . . 478
MERGE special registers. . . . . . . . . 392 WRITE for sequential files . . . . . . . . 483
Segmentation considerations . . . . . . . 392 WRITE for indexed files . . . . . . . . . 485

vi Enterprise COBOL for z/OS, V6.1 Language Reference

 WRITE for relative files . . . . . . . . . 485 RANGE . . . . . . . . . . . . . . . 543
XML GENERATE statement . . . . . . . . 486 REM . . . . . . . . . . . . . . . . 544
Nested XML GENERATE or XML PARSE REVERSE. . . . . . . . . . . . . . . 544
statements . . . . . . . . . . . . . 494 SIN. . . . . . . . . . . . . . . . . 545
Operation of XML GENERATE . . . . . . 494 SQRT . . . . . . . . . . . . . . . . 545
Format conversion of elementary data . . . . 496 STANDARD-DEVIATION . . . . . . . . . 546
Trimming of generated XML data . . . . . 497 SUM . . . . . . . . . . . . . . . . 546
XML element name and attribute name TAN . . . . . . . . . . . . . . . . 547
formation. . . . . . . . . . . . . . 497 ULENGTH . . . . . . . . . . . . . . 547
XML PARSE statement . . . . . . . . . . 499 UPOS . . . . . . . . . . . . . . . . 548
Nested XML GENERATE or XML PARSE UPPER-CASE . . . . . . . . . . . . . 548
statements . . . . . . . . . . . . . 503 USUBSTR . . . . . . . . . . . . . . 549
Control flow. . . . . . . . . . . . . 504 USUPPLEMENTARY . . . . . . . . . . . 550
UVALID . . . . . . . . . . . . . . . 551
UWIDTH. . . . . . . . . . . . . . . 553
Part 7. Intrinsic functions . . . . . 507
VARIANCE . . . . . . . . . . . . . . 553
WHEN-COMPILED . . . . . . . . . . . 554
Chapter 21. Intrinsic functions . . . . 509 YEAR-TO-YYYY . . . . . . . . . . . . 555
Specifying a function . . . . . . . . . . . 509
Function definition and evaluation . . . . . 510
Types of functions . . . . . . . . . . . 510 Part 8. Compiler-directing
Rules for usage . . . . . . . . . . . . 511 statements and compiler
Arguments . . . . . . . . . . . . . 512 directives . . . . . . . . . . . . 557
Examples . . . . . . . . . . . . . . 514
ALL subscripting . . . . . . . . . . . 514
Chapter 22. Compiler-directing
Function definitions . . . . . . . . . . . 516
ACOS . . . . . . . . . . . . . . . . 519 statements . . . . . . . . . . . . 559
ANNUITY . . . . . . . . . . . . . . 520 BASIS statement . . . . . . . . . . . . 559
ASIN . . . . . . . . . . . . . . . . 521 CBL (PROCESS) statement . . . . . . . . . 560
ATAN . . . . . . . . . . . . . . . . 521 *CONTROL (*CBL) statement . . . . . . . . 560
CHAR. . . . . . . . . . . . . . . . 521 Source code listing . . . . . . . . . . 562
COS . . . . . . . . . . . . . . . . 522 Object code listing. . . . . . . . . . . 562
CURRENT-DATE . . . . . . . . . . . . 522 Storage map listing . . . . . . . . . . 562
DATE-OF-INTEGER . . . . . . . . . . . 523 COPY statement . . . . . . . . . . . . 562
DATE-TO-YYYYMMDD . . . . . . . . . . 524 Comparison and replacement rules . . . . . 566
DAY-OF-INTEGER . . . . . . . . . . . 525 Comparison and replacement examples . . . 568
DAY-TO-YYYYDDD . . . . . . . . . . . 525 DELETE statement . . . . . . . . . . . 572
DISPLAY-OF . . . . . . . . . . . . . 526 EJECT statement . . . . . . . . . . . . 573
FACTORIAL. . . . . . . . . . . . . . 528 ENTER statement . . . . . . . . . . . . 574
INTEGER . . . . . . . . . . . . . . 528 INSERT statement . . . . . . . . . . . . 574
INTEGER-OF-DATE . . . . . . . . . . . 528 READY or RESET TRACE statement . . . . . 575
INTEGER-OF-DAY . . . . . . . . . . . 529 REPLACE statement . . . . . . . . . . . 575
INTEGER-PART . . . . . . . . . . . . 530 Comparison rules . . . . . . . . . . . 577
LENGTH . . . . . . . . . . . . . . . 530 Replacement rules . . . . . . . . . . . 578
LOG . . . . . . . . . . . . . . . . 531 SERVICE LABEL statement . . . . . . . . . 580
LOG10 . . . . . . . . . . . . . . . 532 SERVICE RELOAD statement . . . . . . . . 580
LOWER-CASE . . . . . . . . . . . . . 532 SKIP statements . . . . . . . . . . . . 580
MAX . . . . . . . . . . . . . . . . 533 TITLE statement . . . . . . . . . . . . 581
MEAN . . . . . . . . . . . . . . . 534 USE statement . . . . . . . . . . . . . 582
MEDIAN . . . . . . . . . . . . . . . 534 EXCEPTION/ERROR declarative. . . . . . 582
MIDRANGE. . . . . . . . . . . . . . 535 Precedence rules for nested programs . . . . 584
MIN . . . . . . . . . . . . . . . . 535 DEBUGGING declarative . . . . . . . . 584
MOD . . . . . . . . . . . . . . . . 536
NATIONAL-OF . . . . . . . . . . . . 537 Chapter 23. Compiler directives . . . 587
NUMVAL . . . . . . . . . . . . . . 537 CALLINTERFACE. . . . . . . . . . . . 587
NUMVAL-C . . . . . . . . . . . . . . 539 | INLINE . . . . . . . . . . . . . . . 588
ORD . . . . . . . . . . . . . . . . 540
ORD-MAX . . . . . . . . . . . . . . 541
Part 9. Appendixes . . . . . . . . 591
ORD-MIN . . . . . . . . . . . . . . 541
PRESENT-VALUE . . . . . . . . . . . . 542
RANDOM . . . . . . . . . . . . . . 542

Contents vii
 Appendix A. IBM extensions . . . . . 593 DATA DIVISION . . . . . . . . . . . . 640
FD Entry: CODE-SET clause . . . . . . . 641
Appendix B. Compiler limits . . . . . 605 Data description entries . . . . . . . . . 641
PROCEDURE DIVISION . . . . . . . . . 641

Appendix C. EBCDIC and ASCII

Appendix H. Industry specifications 643
collating sequences . . . . . . . . 609
EBCDIC collating sequence . . . . . . . . . 609
US English ASCII code page . . . . . . . . 612
Appendix I. 2002 COBOL Standard
features implemented in Enterprise
Appendix D. Source language COBOL Version 3 or later versions . . 645
debugging. . . . . . . . . . . . . 617
Debugging lines . . . . . . . . . . . . 617 | Appendix J. Accessibility features for
Debugging sections . . . . . . . . . . . 617 | Enterprise COBOL for z/OS . . . . . 651
DEBUG-ITEM special register . . . . . . . . 618
Activate compile-time switch . . . . . . . . 618 Notices . . . . . . . . . . . . . . 653
Activate object-time switch . . . . . . . . . 618 Programming interface information . . . . . . 655
Trademarks . . . . . . . . . . . . . . 655
Appendix E. Reserved words . . . . 621
Glossary . . . . . . . . . . . . . 657
| Appendix F. Context-sensitive words 637
List of resources . . . . . . . . . . 683
Appendix G. ASCII considerations 639 Enterprise COBOL for z/OS . . . . . . . . 683
ENVIRONMENT DIVISION . . . . . . . . 639 Related publications . . . . . . . . . . . 683
OBJECT-COMPUTER and SPECIAL-NAMES
paragraphs . . . . . . . . . . . . . 639 Index . . . . . . . . . . . . . . . 685
FILE-CONTROL paragraph. . . . . . . . 640
I-O-CONTROL paragraph . . . . . . . . 640

viii Enterprise COBOL for z/OS, V6.1 Language Reference

Tables
1. Basic COBOL character set . . . . . . . 3 34. Indexed and relative file types and CLOSE
2. DEBUG-ITEM subfield contents . . . . . 18 statement phrases . . . . . . . . . . 328
3. XML events and associated special register 35. Line-sequential file types and CLOSE
contents . . . . . . . . . . . . . 27 statement phrases . . . . . . . . . . 328
4. Separators . . . . . . . . . . . . . 49 36. Meanings of key letters for sequential file
5. Meanings of environment names. . . . . 118 types . . . . . . . . . . . . . . 328
6. Types of files . . . . . . . . . . . 130 37. Treatment of the content of data items 368
7. Classes and categories of group items 166 38. Interoperable Java and COBOL data types 377
8. Class, category, and usage of elementary 39. Interoperable COBOL and Java array and
data items . . . . . . . . . . . . 167 String data types . . . . . . . . . . 378
9. Classes and categories of functions . . . . 167 40. COBOL miscellaneous argument types and
10. Classes and categories of literals . . . . . 167 corresponding Java types . . . . . . . 379
11. Where national group items are processed as 41. COBOL literal argument types and
groups . . . . . . . . . . . . . . 195 corresponding Java types . . . . . . . 379
12. PICTURE clause symbol meanings . . . . 204 42. Valid and invalid elementary moves 397
13. Numeric types . . . . . . . . . . . 210 43. Availability of a file . . . . . . . . . 406
14. Data categories . . . . . . . . . . . 216 44. Permissible statements for sequential files 406
15. SYNCHRONIZE clause effect on other 45. Permissible statements for indexed and
language elements. . . . . . . . . . 228 relative files . . . . . . . . . . . . 407
16. Relation test references for condition-names 246 46. Permissible statements for line-sequential
17. Binary and unary operators . . . . . . 262 files . . . . . . . . . . . . . . 407
18. Valid arithmetic symbol pairs . . . . . . 263 47. Sending and receiving fields for format-1
19. Valid forms of the class condition for SET statement . . . . . . . . . . . 442
different types of data items . . . . . . 266 48. Sending and receiving fields for format-5
20. Relational operators and their meanings 269 SET statement . . . . . . . . . . . 445
21. Comparisons involving data items and 49. Character positions examined when
literals . . . . . . . . . . . . . . 270 DELIMITED BY is not specified . . . . . 475
22. Comparisons involving figurative constants 271 50. Meanings of environment-names in
23. Comparisons for index-names and index SPECIAL NAMES paragraph . . . . . . 484
data items . . . . . . . . . . . . 275 51. Table of functions . . . . . . . . . . 517
24. Permissible comparisons for USAGE 52. ULENGTH function of character ä . . . . 548
POINTER, NULL, and ADDRESS OF . . . 276 53. Byte validity for UTF-8 data . . . . . . 552
25. Logical operators and their meanings 279 54. Encoding unit validity for UTF-16 data 552
26. Combined conditions—permissible element 55. Execution of debugging declaratives . . . . 585
sequences . . . . . . . . . . . . 280 56. IBM extension language elements . . . . 593
27. Logical operators and evaluation results of 57. Compiler limits . . . . . . . . . . 605
combined conditions . . . . . . . . . 281 58. EBCDIC collating sequence . . . . . . 609
28. Abbreviated combined conditions: 59. ASCII collating sequence . . . . . . . 612
permissible element sequences . . . . . 283 60. Reserved words . . . . . . . . . . 621
29. Abbreviated combined conditions: | 61. Context-sensitive words . . . . . . . . 637
unabbreviated equivalents . . . . . . . 284 62. 2002 COBOL Standard features implemented
30. Exponentiation size error conditions 292 | in V3 or later versions that will potentially
31. How the composite of operands is affect existing programs . . . . . . . . 645
determined . . . . . . . . . . . . 293 63. 2002 COBOL Standard features implemented
32. File status key values and meanings 296 | in V3 or later versions that will not affect
33. Sequential files and CLOSE statement existing programs . . . . . . . . . . 646
phrases . . . . . . . . . . . . . 328

© Copyright IBM Corp. 1991, 2017 ix

x Enterprise COBOL for z/OS, V6.1 Language Reference
Preface
About this information
This information describes the COBOL language supported by IBM® Enterprise
COBOL for z/OS®, referred to in this information as Enterprise COBOL.

See the IBM Enterprise COBOL for z/OS Programming Guide for information and
examples that will help you write, compile, and debug programs and classes.

How to read the syntax diagrams

Throughout the document, diagrams illustrate Enterprise COBOL syntax.

Use the following description to read the syntax diagrams in this document:
v Read the syntax diagrams from left to right, from top to bottom, following the
path of the line.
The >>--- symbol indicates the beginning of a syntax diagram.
The ---> symbol indicates that the syntax diagram is continued on the next line.
The >--- symbol indicates that the syntax diagram is continued from the
previous line.
The --->< symbol indicates the end of a syntax diagram.
Diagrams of syntactical units other than complete statements start with the >---
symbol and end with the ---> symbol.
v Required items appear on the horizontal line (the main path).

Format

►► STATEMENT required item ►◄

v Optional items appear below the main path.

Format

►► STATEMENT ►◄
optional item

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

© Copyright IBM Corp. 1991, 2017 xi

 Format

►► STATEMENT required choice 1 ►◄

required choice 2

If choosing one of the items is optional, the entire stack appears below the main
path.

Format

►► STATEMENT ►◄
optional choice 1
optional choice 2

v An arrow returning to the left above the main line indicates an item that can be
repeated.

Format

►► STATEMENT ▼ repeatable item ►◄

A repeat arrow above a stack indicates that you can make more than one choice
from the stacked items, or repeat a single choice.
v Variables appear in italic lowercase letters (for example, parmx). They represent
user-supplied names or values.
v If punctuation marks, parentheses, arithmetic operators, or other such symbols
are shown, they must be entered as part of the syntax.

The following example shows how the syntax is used.

xii Enterprise COBOL for z/OS, V6.1 Language Reference

Format

(1) (2)
►► STATEMENT identifier-1 ▼ ►
literal-1 (3)
item 1

(4)
► ▼ TO identifier-3 ►
ROUNDED

(5)
► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
(6)
END-STATEMENT

item 1:

identifier-2
literal-2
arithmetic-expression-1

Notes:
1 The STATEMENT keyword must be specified and coded as shown.
2 This operand is required. Either identifier-1 or literal-1 must be coded.
3 The item 1 fragment is optional; it can be coded or not, as required by the
application. If item 1 is coded, it can be repeated with each entry separated
by one or more COBOL separators. Entry selections allowed for this
fragment are described at the bottom of the diagram.
4 The operand identifier-3 and associated TO keyword are required and can
be repeated with one or more COBOL separators separating each entry.
Each entry can be assigned the keyword ROUNDED.
5 The ON SIZE ERROR phrase with associated imperative-statement-1 is
optional. If the ON SIZE ERROR phrase is coded, the keyword ON is
optional.
6 The END-STATEMENT keyword can be coded to end the statement. It is
not a required delimiter.

Preface xiii
 IBM extensions
IBM extensions generally add features, syntax, or rules that are not specified in the
ANSI and ISO COBOL standards that are listed in Appendix H, “Industry
specifications,” on page 643. In this document, the term 85 COBOL Standard refers
to those standards.

Extensions range from minor relaxation of rules to major capabilities, such as XML
support, Unicode support, object-oriented COBOL for Java™ interoperability, and
DBCS character handling.

The rest of this document describes the complete language without identifying
extensions. You will need to review Appendix A, “IBM extensions,” on page 593
and the Compiler options in the Enterprise COBOL Programming Guide if you want to
use only standard language elements.

Obsolete language elements

Obsolete language elements are elements that are categorized as obsolete in the 85
COBOL Standard. Those elements are not part of the 2002 COBOL Standard.

This does not imply that IBM will remove the 85 COBOL Standard obsolete
elements from a future release of Enterprise COBOL.

The following language elements are categorized as obsolete by the 85 COBOL

Standard:
v ALTER statement
v AUTHOR paragraph
v Comment entry
v DATA RECORDS clause
v DATE-COMPILED paragraph
v DATE-WRITTEN paragraph
v DEBUG-ITEM special register
v Debugging sections
v ENTER statement
v GO TO without a specified procedure-name
v INSTALLATION paragraph
v LABEL RECORDS clause
v MEMORY SIZE clause
v MULTIPLE FILE TAPE clause
v RERUN clause
v REVERSED phrase
v SECURITY paragraph
v Segmentation module
v STOP literal format of the STOP statement
v USE FOR DEBUGGING declarative
v VALUE OF clause
v The figurative constant ALL literal with a length greater than one, when the
figurative constant is associated with a numeric or numeric-edited item

xiv Enterprise COBOL for z/OS, V6.1 Language Reference

DBCS notation
Double-Byte Character Set (DBCS) strings in literals, comments, and user-defined
words are delimited by shift-out and shift-in characters.

In this document, the shift-out delimiter is represented pictorially by the <

character, and the shift-in character is represented pictorially by the > character.
The single-byte EBCDIC codes for the shift-out and shift-in delimiters are X'0E' and
X'0F', respectively.

The <> symbol denotes contiguous shift-out and shift-in characters. The >< symbol
denotes contiguous shift-in and shift-out characters.

DBCS characters are shown in this form: D1D2D3. Latin alphabet characters in
DBCS representation are shown in this form: .A.B.C. The dots that precede the
letters represent the hexadecimal value X'42'.

Notes:
v In EBCDIC DBCS data containing mixed single-byte and double-byte characters,
double-byte character strings are delimited by shift-out and shift-in characters.
v In ASCII DBCS data containing mixed single-byte and double-byte characters,
double-byte character strings are not delimited by shift-out and shift-in
characters.

Acknowledgment
The following extract from Government Printing Office Form Number
1965-0795689 is presented for the information and guidance of the user:

Any organization interested in reproducing the COBOL report and

specifications in whole or in part, using ideas taken from this report as the
basis for an instruction manual or for any other purpose is free to do so.
However, all such organizations are requested to reproduce this section as
part of the introduction to the document. Those using a short passage, as in a
book review, are requested to mention COBOL in acknowledgment of the
source, but need not quote this entire section.

COBOL is an industry language and is not the property of any company or

group of companies, or of any organization or group of organizations.

No warranty, expressed or implied, is made by any contributor or by the

COBOL Committee as to the accuracy and functioning of the programming
system and language. Moreover, no responsibility is assumed by any
contributor, or by the committee, in connection there with.

Procedures have been established for the maintenance of COBOL. Inquiries

concerning the procedures for proposing changes should be directed to the
Executive Committee of the Conference on Data Systems Languages.

The authors and copyright holders of copyrighted material:

v FLOW-MATIC (Trademark of Sperry Rand Corporation), Programming for
the UNIVAC(R) I and II, Data Automation Systems copyrighted 1958, 1959,
by Sperry Rand Corporation
v IBM Commercial Translator, Form No. F28-8013, copyrighted 1959 by IBM
v FACT, DSI 27A5260-2760, copyrighted 1960 by Minneapolis-Honeywell

Preface xv
 have specifically authorized the use of this material in whole or in part, in the
COBOL specifications. Such authorization extends to the reproduction and
use of COBOL specifications in programming manuals or similar publications.

Note: The Conference on Data Systems Languages (CODASYL), mentioned above,

is no longer in existence.

Additional documentation and support

Enterprise COBOL provides Portable Document Format (PDF) versions of the
entire library for this version and for previous versions on the product site at
www.ibm.com/software/awdtools/cobol/zos/library/. These documents are also
available in Japanese.

Support information is also available on the product site at http://www.ibm.com/

support/entry/portal/Overview/Software/Rational/Enterprise_COBOL_for_z~OS
.

Summary of changes
| This section lists the key changes that have been made to this document since
| Enterprise COBOL for z/OS Version 5. The changes that are described in this
information have an associated cross-reference for your convenience. The technical
changes are marked by a vertical bar (|) in the left margin in the PDF version.

| Version 6 Release 1 with PTF for APAR PI71621 installed

| v The JSON GENERATE statement is redesigned and improved (“JSON
| GENERATE statement” on page 380).

| Version 6 Release 1
| v The new ALLOCATE statement obtains dynamic storage, while the new FREE
| statement releases dynamic storage that was previously obtained with an
| ALLOCATE statement. Both statements are part of the 2002 COBOL Standard
| (“ALLOCATE statement” on page 310 and “FREE statement” on page 351).
| v Enhancements are made to the INITIALIZE statement as part of the 2002
| COBOL Standard (“INITIALIZE statement” on page 358):
| – A new FILLER phrase is added so that FILLER data items can be initialized
| with the INITIALIZE statement.
| – A new VALUE phrase is added so that elementary data items can be
| initialized to the literal specified in the VALUE clause.
| v The new JSON GENERATE statement converts data to JSON format (“JSON
| GENERATE statement” on page 380).
| v The new VSAMOPENFS option affects the user file status reported from
| successful OPEN statements on VSAM files (“OPEN statement notes” on page
| 406).

Version 5 Release 2
v New keywords LEADING and TRAILING are added to the REPLACING phrase
of the COPY statement and the REPLACE statement to improve partial-word
replacement operations. The new keywords are part of the 2002 COBOL
Standard (“COPY statement” on page 562 and “REPLACE statement” on page
575).

xvi Enterprise COBOL for z/OS, V6.1 Language Reference

 v The new CALLINTERFACE directive specifies the interface convention for CALL
and SET statements. The convention specified stays in effect until another
CALLINTERFACE directive is encountered in the source. The CALLINTERFACE
directive has three suboptions: DLL, DYNAMIC, and STATIC.
v The EXIT statement includes the following new formats, which provide a
structured way to exit without using a GO TO statement. The new formats are
part of the 2002 COBOL Standard.
– Format 5, EXIT PERFORM statement for exiting from an inline PERFORM
statement
– Format 6, EXIT PARAGRAPH or EXIT SECTION statement for exiting from
the middle of a paragraph or exiting from a section respectively
v A new format of the SORT statement, the table SORT statement, arranges table
elements in a user-specified sequence. It is part of the 2002 COBOL Standard
(“SORT statement” on page 448).
v A new compiler option, VLR(COMPAT|STANDARD), affects the READ
statement processing of variable-length records (“READ statement notes” on
page 425).
v XML PARSE COMPAT support is restored. You can specify the
XMLPARSE(XMLSS|COMPAT) compiler option to choose between parsing with
the z/OS XML System Services parser, or with the compatibility-mode COBOL
XML parser from the COBOL library. It can ease your migration to the
Enterprise COBOL V5 compiler.
v Enhancements are made to the “XML GENERATE statement” on page 486:
– The WHEN phrase of the XML GENERATE statement can be omitted to
allow unconditional suppression of an item when generating XML output. If
the WHEN phrase is omitted, that item can be a group data item.
– A new keyword CONTENT is added to the generic-suppression-phrase to
limit suppression to only TYPE IS CONTENT items.
v A new keyword VOLATILE is added to the format 1 data description entry. The
VOLATILE clause indicates that a data item's value can be modified or
referenced in ways that the compiler cannot detect, such as by a Language
Environment® (LE) condition handler routine or by some other asynchronous
process or thread. Thus, optimization is restricted for the data item (“VOLATILE
clause” on page 247).

Version 5 Release 1 Modification 1

Several changes were made to Enterprise COBOL V5.1 via service to make V5.1.1.
See the Enterprise COBOL Programming Guide for details.

Version 5 Release 1
v A new special register, XML-INFORMATION, provides a mechanism to easily
determine whether the XML content delivered for an XML event is complete or
will be continued on the next event. (“XML-INFORMATION” on page 32)
v New phrases, NAME, TYPE and SUPPRESS are added to the XML GENERATE
statement. The generic-suppression-phrase of the XML GENERATE statement
behavior is changed to be more flexible by deferring the decision about what
gets excluded until run time. This way entire classes and categories of data items
can be excluded from the generated XML output based on suppression criteria.
The data items to which the suppression specifications apply and that meet the
criteria at run time will be excluded. (“XML GENERATE statement” on page
486)
v New intrinsic functions are added to provide additional Unicode capability:

Preface xvii
 – ULENGTH (“ULENGTH” on page 547)
– UPOS (“UPOS” on page 548)
– USUBSTR (“USUBSTR” on page 549)
– USUPPLEMENTARY (“USUPPLEMENTARY” on page 550)
– UVALID (“UVALID” on page 551)
– UWIDTH (“UWIDTH” on page 553)
v Several compiler limits are raised (Appendix B, “Compiler limits,” on page 605).
v The information about reference format has been updated to reflect that:
– A new floating comment indicator (the character string '*>') can be coded to
indicate that the ensuing text on a line is an inline comment (“Floating
comment indicators (*>)” on page 61).
– Add inline comments as another format of comments (“Comments” on page
46).
v The Millennium Language Extensions are no longer supported, which include
the following compiler options and language elements:
– DATE FORMAT clause on data description entries
– DATEVAL intrinsic function
– UNDATE intrinsic function
– YEARWINDOW intrinsic function
– DATEPROC compiler option
– YEARWINDOW compiler option
v Format 2 declarative syntax: USE...AFTER...LABEL PROCEDURE..., and the
syntax: GO TO MORE-LABELS are no longer supported.
v The compatibility-mode COBOL XML parser from the COBOL library is no
longer supported for use by Enterprise COBOL V5 programs. XML PARSE
statements in V5 programs always use the z/OS XML System Services parser.
v Correct the READ statement processing of wrong-length records (“READ
statement” on page 420).
v The following compiler options are no longer supported, but are tolerated with
Enterprise COBOL V5 to ease migration. Informational or warning diagnostics
will be displayed if you specify any of these options.
– DATEPROC - Year 2000 support is no longer provided.
– YEARWINDOW - Year 2000 support is no longer provided.
– XMLPARSE - The XML System Services parser is always used.
v A new keyword UNBOUNDED is added to the OCCURS...DEPENDING ON
clause, which enables you to define unbounded tables and groups
(“Variable-length tables” on page 199).
v To be compatible with the convention used by C and C++, the linkage
convention for returning a doubleword binary item specified in the
RETURNING phrase of the PROCEDURE DIVISION header and the CALL
statement is changed (CALL statement).

How to send your comments

Your feedback is important in helping us to provide accurate, high-quality
information. If you have comments about this document or any other
documentation for this product, contact us in one of the following ways:
v Use the Online Readers' Comments Form at http://www.ibm.com/software/
awdtools/rcf.

xviii Enterprise COBOL for z/OS, V6.1 Language Reference

v Send your comments to the following address: [email protected].

Be sure to include the name of the document, the publication number of the
document, the version of the product, and, if applicable, the specific location (for
example, 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 xix
xx Enterprise COBOL for z/OS, V6.1 Language Reference
Part 1. COBOL language structure

© Copyright IBM Corp. 1991, 2017 1

2 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 1. Characters
The most basic and indivisible unit of the COBOL language is the character. The
basic character set includes the letters of the Latin alphabet, digits, and special
characters.

In the COBOL language, individual characters are joined to form character-strings

and separators. Character-strings and separators, then, are used to form the words,
literals, phrases, clauses, statements, and sentences that form the language.

The basic characters used in forming character-strings and separators in source

code are shown in Table 1.

For certain language elements, the basic character set is extended with the EBCDIC
Double-Byte Character Set (DBCS).

DBCS characters can be used in forming user-defined words.

The content of alphanumeric literals, comment lines, and comment entries can
include any of the characters in the computer's compile-time character set, and can
include both single-byte and DBCS characters.

Runtime data can include any characters from the runtime character set of the
computer. The runtime character set of the computer can include alphanumeric
characters, DBCS characters, and national characters. National characters are
represented in UTF-16, a 16-bit encoding form of Unicode.

When the NSYMBOL (NATIONAL) compiler option is in effect, literals identified

by the opening delimiter N" or N' are national literals and can contain any
single-byte or double-byte characters, or both, that are valid for the compile-time
code page in effect (either the default code page or the code page specified for the
CODEPAGE compiler option). Characters contained in national literals are
represented as national characters at run time.

For details, see “User-defined words with DBCS characters” on page 10, “DBCS
literals” on page 42, and “National literals” on page 43.
Table 1. Basic COBOL character set. This table lists basic COBOL character set.
Character Meaning
Space
+ Plus sign
- Minus sign or hyphen
* Asterisk
/ Forward slash or solidus
= Equal sign
$ Currency sign1
, Comma
; Semicolon
. Decimal point or period

© Copyright IBM Corp. 1991, 2017 3

 Table 1. Basic COBOL character set (continued). This table lists basic COBOL character
set.
Character Meaning
" Quotation mark2
’ Apostrophe
( Left parenthesis
) Right parenthesis
> Greater than
< Less than
: Colon
_ Underscore
A-Z Alphabet (uppercase)
a-z Alphabet (lowercase)
0-9 Numeric characters

1. The currency sign is the character with the value X'5B', regardless of the code page in
effect. The assigned graphic character can be the dollar sign or a local currency sign.
2. The quotation mark is the character with the value X'7F'.

4 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 2. Character sets and code pages
A character set is a set of letters, numbers, special characters, and other elements
used to represent information. The term code page refers to a coded character set.

A character set is independent of a coded representation. A coded character set is the

coded representation of a set of characters, where each character is assigned a
numerical position, called a code point, in the encoding scheme. ASCII and EBCDIC
are examples of types of coded character sets. Each variation of ASCII or EBCDIC
is a specific coded character set.

Each code page that IBM defines is identified by a code page name, for example
IBM-1252, and a coded character set identifier (CCSID), for example 1252.

Enterprise COBOL provides the CODEPAGE compiler option for specifying a

coded character set for use at compile time and run time for code-page-sensitive
elements, such as:
v The encoding of literals in the source program
v The default encoding for data items described with USAGE DISPLAY or
DISPLAY-1
v The default encoding for XML parsing and XML generation

Some COBOL operations can override the encoding established by the CODEPAGE
compiler option, for example:
v The DISPLAY-OF and NATIONAL-OF intrinsic functions can specify a CCSID as
argument-2.
v The XML PARSE and XML GENERATE statements can specify a code page in
the ENCODING phrase.

For further details about the CODEPAGE compiler option, see CODEPAGE in the
Enterprise COBOL Programming Guide.

If you do not specify a code page, the default is code page IBM-1140, CCSID 1140.

The encoding of national data is not affected by the CODEPAGE compiler option.
The encoding for national literals and data items described with usage NATIONAL
is UTF-16BE (big endian), CCSID 1200. A reference to UTF-16 in this document is a
reference to UTF-16BE.

Character encoding units

A character encoding unit (or encoding unit) is the unit of data that COBOL treats as
a single character at run time. In this information, the terms character and character
position refer to a single encoding unit.

The size of an encoding unit for data items and literals depends on the USAGE
clause of the data item or the category of the literal as follows:
v For data items described with USAGE DISPLAY and for alphanumeric literals,
an encoding unit is 1 byte, regardless of the code page used and regardless of
the number of bytes used to represent a given graphic character.

© Copyright IBM Corp. 1991, 2017 5

 v For data items described with USAGE DISPLAY-1 (DBCS data items) and for
DBCS literals, an encoding unit is 2 bytes.
v For data items described with USAGE NATIONAL and for national literals, an
encoding unit is 2 bytes.

The relationship between a graphic character and an encoding unit depends on the
type of code page used for the data item or literal. See the following types of
runtime code pages:
v Single-byte EBCDIC
v EBCDIC DBCS
v Unicode UTF-16

See the following sections for the details of each type of code page.

Also see the section Specifying the encoding in the Enterprise COBOL Programming
Guide.

Single-byte code pages

You can use a single-byte EBCDIC code page in data items described with USAGE
DISPLAY and in literals of category alphanumeric. An encoding unit is 1 byte and
each graphic character is represented in 1 byte. For these data items and literals,
you need not be concerned with encoding units.

EBCDIC DBCS code pages

USAGE DISPLAY

You can use a mixture of single-byte and double-byte EBCDIC characters in data
items described with USAGE DISPLAY and in literals of category alphanumeric.
Double-byte characters must be delimited by shift-out and shift-in characters. An
encoding unit is 1 byte and the size of a graphic character is 1 byte or 2 bytes.

When alphanumeric data items or literals contain DBCS data, programmers are
responsible for ensuring that operations do not unintentionally separate the
multiple encoding units that form a graphic character. Care should be taken with
reference modification, and truncation during moves should be avoided. The
COBOL runtime system does not check for a split between the encoding units that
form a graphic character or for the loss of shift-out or shift-in codes.

To avoid problems, you can convert alphanumeric literals and data items described
with usage DISPLAY to national data (UTF-16) by moving the data items or literals
to data items described with usage NATIONAL or by using the NATIONAL-OF
intrinsic function. You can then perform operations on the national data with less
concern for splitting graphic characters. You can convert the data back to USAGE
DISPLAY by using the DISPLAY-OF intrinsic function.

USAGE DISPLAY-1

You can use double-byte characters of an EBCDIC DBCScode page in data items
described with USAGE DISPLAY-1 and in literals of category DBCS. An encoding
unit is 2 bytes and each graphic character is represented in a single 2-byte
encoding unit. For these data items and literals, you need not be concerned with
encoding units.

6 Enterprise COBOL for z/OS, V6.1 Language Reference

Unicode UTF-16

You can use UTF-16 in data items described with USAGE NATIONAL. National
literals are stored as UTF-16 characters regardless of the code page used for the
source program. An encoding unit for data items of usage NATIONAL and
national literals is 2 bytes.

For most of the characters in UTF-16, a graphic character is one encoding unit.
Characters converted to UTF-16 from an EBCDIC, ASCII, or EUC code page are
represented in one UTF-16 encoding unit. Some of the other graphic characters in
UTF-16 are represented by a surrogate pair or a combining character sequence. A
surrogate pair consists of two encoding units (4 bytes). A combining character
sequence consists of a base character and one or more combining marks or a
sequence of one or more combining marks (4 bytes or more, in 2-byte increments).
In data items of usage NATIONAL, each 2-byte encoding unit is treated as a
character.

When national data contains surrogate pairs or combining character sequences,

programmers are responsible for ensuring that operations on national characters do
not unintentionally separate the multiple encoding units that form a graphic
character. Care should be taken with reference modification, and truncation during
moves should be avoided. The COBOL runtime system does not check for a split
between the encoding units that form a graphic character.

Chapter 2. Character sets and code pages 7

8 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 3. Character-strings: COBOL words and literals
A character-string is a character or a sequence of contiguous characters that forms a
COBOL word, a literal, a PICTURE character-string, or a comment-entry. A
character-string is delimited by separators.

A separator is a string of contiguous characters used to delimit character strings.

Separators are described in detail under Chapter 4, “Separators,” on page 49.

Character strings and certain separators form text words. A text word is a character
or a sequence of contiguous characters (possibly continued across lines) between
character positions 8 and 72 inclusive in source text, library text, or pseudo-text.
For more information about pseudo-text, see “Pseudo-text” on page 62.

Source text, library text, and pseudo-text can be written in single-byte EBCDIC
and, for some character-strings, DBCS. (The compiler cannot process source code
written in ASCII or Unicode.)

You can use single-byte and double-byte character-strings to form the following
items:
v COBOL words
v Literals
v Comment text

You can use only single-byte characters to form PICTURE character-strings.

COBOL words with single-byte characters

A COBOL word is a character-string that forms a user-defined word, a
system-name, or a reserved word. The maximum size of a COBOL user-defined
word is 30 bytes. The number of characters that can be specified depends on the
code page indicated by the compile-time locale.

Except for arithmetic operators and relation characters, each character of a COBOL
word is selected from the following set:
v Latin uppercase letters A through Z
v Latin lowercase letters a through z
v digits 0 through 9
v - (hyphen)
v _ (underscore)

The hyphen cannot appear as the first or last character in such words. The
underscore cannot appear as the first character in such words. Most user-defined
words (all except section-names, paragraph-names, priority-numbers, and
level-numbers) must contain at least one alphabetic character. Priority numbers and
level numbers need not be unique; a given specification of a priority-number or
level-number can be identical to any other priority-number or level-number.

In COBOL words (but not in the content of alphanumeric, DBCS, and national
literals), each lowercase single-byte alphabetic letter is considered to be equivalent
to its corresponding single-byte uppercase alphabetic letter.

© Copyright IBM Corp. 1991, 2017 9

 The following rules apply for all COBOL words:
v A reserved word cannot be used as a user-defined word or as a system-name.
v The same COBOL word, however, can be used as both a user-defined word and
as a system-name. The classification of a specific occurrence of a COBOL word is
determined by the context of the clause or phrase in which it occurs.

User-defined words with DBCS characters

There are the rules for forming user-defined words with DBCS characters.

The rules are:

Contained characters
DBCS user-defined words can contain only double-byte characters, and
must contain at least one DBCS character that is not in the set A through Z,
a through z, 0 through 9, hyphen, and underscore (DBCS representation of
these characters has X'42' in the first byte).
DBCS user-defined words can contain characters that correspond to
single-byte EBCDIC characters and those that do not correspond to
single-byte EBCDIC characters. DBCS characters that correspond to
single-byte EBCDIC characters follow the normal rules for COBOL
user-defined words; that is, the characters A - Z, a - z, 0 - 9, the hyphen (-),
and the underscore (_) are allowed. The hyphen cannot appear as the first
or last character. The underscore cannot appear as the first character. Any
of the DBCS characters that have no corresponding single-byte EBCDIC
character can be used in DBCS user-defined words.
Uppercase and lowercase letters
In COBOL words, each lowercase single-byte encoded character "a"
through "z" is considered to be equivalent to its corresponding single-byte
encoded uppercase character.DBCS-encoded uppercase and lowercase
letters are not equivalent.
Value range
DBCS user-defined words can contain characters whose values range from
X'41' to X'FE' for both bytes.
Maximum length
14 characters
Continuation
Words formed with DBCS characters cannot be continued across lines.
Use of shift-out and shift-in characters
DBCS user-defined words begin with a shift-out character and end with a
shift-in character.

User-defined words
A user-defined word is a COBOL word that must be supplied by the user to satisfy
the format of a clause or statement.

The following sets of user-defined words are supported. The second column
indicates whether DBCS characters are allowed in words of a given set.

User-defined word DBCS characters allowed?

Alphabet-name Yes

10 Enterprise COBOL for z/OS, V6.1 Language Reference

User-defined word DBCS characters allowed?
Class-name (of data) Yes
Condition-name Yes
Data-name Yes
File-name Yes
Index-name Yes
Level-numbers: 01–49, 66, 77, 88 No
Library-name No
Mnemonic-name Yes
Object-oriented class-name No
Paragraph-name Yes
Priority-numbers: 00–99 No
Program-name No
Record-name Yes
Section-name Yes
Symbolic-character Yes
Text-name No
XML-schema-name Yes

The maximum length of a user-defined word is 30 bytes, except for level-numbers

and priority-numbers. Level-numbers and priority numbers must each be a
one-digit or two-digit integer.

A given user-defined word can belong to only one of these sets, except that a given
number can be both a priority-number and a level-number. Each user-defined
word within a set must be unique, except for priority-numbers and level-numbers
and except as specified in Chapter 8, “Referencing data names, copy libraries, and
PROCEDURE DIVISION names,” on page 69.

The following types of user-defined words can be referenced by statements and

entries in the program in which the user-defined word is declared:
v Paragraph-name
v Section-name

The following types of user-defined words can be referenced by any COBOL

program, provided that the compiling system supports the associated library or
other system and that the entities referenced are known to that system:
v Library-name
v Text-name

The following types of names, when they are declared within a configuration
section, can be referenced by statements and entries in the program that contains
the configuration section or in any program contained within that program:
v Alphabet-name
v Class-name
v Condition-name
v Mnemonic-name

Chapter 3. Character-strings: COBOL words and literals 11

 v Symbolic-character
v XML-schema-name

The function of each user-defined word is described in the clause or statement in

which it appears.

| RELATED REFERENCES
| Appendix F, “Context-sensitive words,” on page 637
|
System-names
A system-name is a character string that has a specific meaning to the system.

There are three types of system-names:

v Computer-name
v Language-name
v Implementor-name

There are four types of implementer-names:

v Environment-name
v External-class-name
v External-fileid
v Assignment-name

The meaning of each system-name is described with the format in which it

appears.

Computer-name can be written in DBCS characters, but the other system-names

cannot.

Function-names
A function-name specifies the mechanism provided to determine the value of an
intrinsic function.

The same word, in a different context, can appear in a program as a user-defined

word or a system-name. For a list of function-names and their definitions, see
Table 51 on page 517.

Reserved words
A reserved word is a character-string with a predefined meaning in a COBOL source
unit.

Reserved words are listed in Appendix E, “Reserved words,” on page 621. There
are six types of reserved words:
v Keywords
v Optional words
v Figurative constants
v Special character words
v Special object identifiers
v Special registers

12 Enterprise COBOL for z/OS, V6.1 Language Reference

 Keywords
Keywords are reserved words that are required within a given clause,
entry, or statement. Within each format, such words appear in uppercase
on the main path.
Optional words
Optional words are reserved words that can be included in the format of a
clause, entry, or statement in order to improve readability. They have no
effect on the execution of the program.
Figurative constants
See “Figurative constants.”
Special character words
There are five types of special character words, which are recognized as
special characters only when represented in single-byte characters:
v Arithmetic operators: + - / * **
See “Arithmetic expressions” on page 261.
v Relational operators: < > = <= >=
See “Conditional expressions” on page 264.
v Floating comment indicators: *>
See “Floating comment indicators (*>)” on page 61.
v Pseudo-text delimiters in COPY and REPLACE statements: ==
See “COPY statement” on page 562 and “REPLACE statement” on page
575.
v Compiler directive indicators: >>
See Chapter 23, “Compiler directives,” on page 587.
Special object identifiers
COBOL provides two special object identifiers, SELF and SUPER:
SELF A special object identifier that you can use in the PROCEDURE
DIVISION of a method. SELF refers to the object instance used to
invoke the currently executing method. You can specify SELF only
in places that are explicitly listed in the syntax diagrams.
SUPER
A special object identifier that you can use in the PROCEDURE
DIVISION of a method only as the object identifier in an INVOKE
statement. When used in this way, SUPER refers to the object
instance used to invoke the currently executing method. The
resolution of the method to be invoked ignores any methods
declared in the class definition of the currently executing method
and methods defined in any class derived from that class. Thus,
the method invoked is inherited from an ancestor class.
Special registers
See “Special registers” on page 16.

Figurative constants
Figurative constants are reserved words that name and refer to specific constant
values. The reserved words for figurative constants and their meanings are listed
in this section.

Chapter 3. Character-strings: COBOL words and literals 13

 ZERO, ZEROS, ZEROES
Represents the numeric value zero (0) or one or more occurrences of the
character zero, depending on context.
When the figurative constant ZERO, ZEROS, or ZEROES is used in a
context that requires an alphanumeric character, an alphanumeric character
zero is used. When the context requires a national character zero, a
national character zero is used (value NX'0030'). When the context cannot
be determined, an alphanumeric character zero is used.
SPACE, SPACES
Represents one or more blanks or spaces. SPACE is treated as an
alphanumeric literal when used in a context that requires an alphanumeric
character, as a DBCS literal when used in a context that requires a DBCS
character, and as a national literal when used in a context that requires a
national character. The EBCDIC DBCS space character has the value
X'4040', and the national space character has the value NX'0020'.
HIGH-VALUE, HIGH-VALUES
Represents one or more occurrences of the character that has the highest
ordinal position in the collating sequence used.
HIGH-VALUE is treated as an alphanumeric literal in a context that
requires an alphanumeric character. For alphanumeric data with the
EBCDIC collating sequence, the value is X'FF'. For other alphanumeric
data, the value depends on the collating sequence in effect.
HIGH-VALUE is treated as a national literal when used in a context that
requires a national literal. The value is national character NX'FFFF'.
When the context cannot be determined, an alphanumeric context is
assumed and the value X'FF' is used.
Usage note: You should not use HIGH-VALUE (or a value assigned from
HIGH-VALUE) in a way that results in conversion between one data
representation and another. X'FF' does not represent a valid EBCDIC
character, and NX'FFFF' does not represent a valid national character.
Conversion of either the alphanumeric or the national HIGH-VALUE
representation to another representation results in a substitution character.
For example, conversion of X'FF' to UTF-16 would give a substitution
character, not NX'FFFF'.
LOW-VALUE, LOW-VALUES
Represents one or more occurrences of the character that has the lowest
ordinal position in the collating sequence used.
LOW-VALUE is treated as an alphanumeric literal in a context that requires
an alphanumeric character. For alphanumeric data with the EBCDIC
collating sequence, the value is X'00'. For other alphanumeric data, the
value depends on the collating sequence in effect.
LOW-VALUE is treated as a national literal when used in a context that
requires a national literal. The value is national character NX'0000'.
When the context cannot be determined, an alphanumeric context is
assumed and the value X'00' is used.
QUOTE, QUOTES
Represents one or more occurrences of:
v The quotation mark character ("), if the QUOTE compiler option is in
effect

14 Enterprise COBOL for z/OS, V6.1 Language Reference

 v The apostrophe character (’), if the APOST compiler option is in effect
QUOTE or QUOTES represents an alphanumeric character when used in a
context that requires an alphanumeric character, and represents a national
character when used in a context that requires a national character. The
national character value of quotation mark is NX'0022'. The national
character value of apostrophe is NX'0027'.
QUOTE and QUOTES cannot be used in place of a quotation mark or an
apostrophe to enclose an alphanumeric literal.
ALL literal
literal can be an alphanumeric literal, a DBCS literal, a national literal, or a
figurative constant other than the ALL literal.
When literal is not a figurative constant, ALL literal represents one or more
occurrences of the string of characters that compose the literal.
When literal is a figurative constant, the word ALL has no meaning and is
used only for readability.
The figurative constant ALL literal must not be used with the CALL,
INSPECT, INVOKE, STOP, or STRING statements.
symbolic-character
Represents one or more of the characters specified as a value of the
symbolic-character in the SYMBOLIC CHARACTERS clause of the
SPECIAL-NAMES paragraph.
symbolic-character always represents an alphanumeric character; it can be
used in a context that requires a national character only when implicit
conversion of alphanumeric to national characters is defined. (It can be
used, for example, in a MOVE statement where the receiving item is of
class national because implicit conversion is defined when the sending
item is alphanumeric and the receiving item is national.)
NULL, NULLS
Represents a value used to indicate that data items defined with USAGE
POINTER, USAGE PROCEDURE-POINTER, USAGE FUNCTION-
POINTER, USAGE OBJECT REFERENCE, or the ADDRESS OF special
register do not contain a valid address. NULL can be used only where
explicitly allowed in the syntax formats. NULL has the value zero.

The singular and plural forms of NULL, ZERO, SPACE, HIGH-VALUE,

LOW-VALUE, and QUOTE can be used interchangeably. For example, if
DATA-NAME-1 is a five-character data item, each of the following statements moves
five spaces to DATA-NAME-1:
MOVE SPACE TO DATA-NAME-1
MOVE SPACES TO DATA-NAME-1
MOVE ALL SPACES TO DATA-NAME-1

When the rules of COBOL permit any one spelling of a figurative constant name,
any alternative spelling of that figurative constant name can be specified.

You can use a figurative constant wherever literal appears in a syntax diagram,
except where explicitly prohibited. When a numeric literal appears in a syntax
diagram, only the figurative constant ZERO (or ZEROS or ZEROES) can be used.
Figurative constants are not allowed as function arguments except in an arithmetic
expression, where the expression is an argument to a function.

Chapter 3. Character-strings: COBOL words and literals 15

 The length of a figurative constant depends on the context of its use. The following
rules apply:
v When a figurative constant is specified in a VALUE clause or associated with a
data item (for example, when it is moved to or compared with another item), the
length of the figurative constant character-string is equal to 1 or the number of
character positions in the associated data item, whichever is greater.
v When a figurative constant, other than the ALL literal, is not associated with
another data item (for example, in a CALL, INVOKE, STOP, STRING, or
UNSTRING statement), the length of the character-string is one character.

Special registers
Special registers are reserved words that name storage areas generated by the
compiler. Their primary use is to store information produced through specific
COBOL features. Each such storage area has a fixed name, and must not be
defined within the program.

For programs with the RECURSIVE attribute, for programs compiled with the
THREAD option, and for methods, storage for the following special registers is
allocated on a per-invocation basis:
v ADDRESS OF
| v JSON-CODE
v RETURN-CODE
v SORT-CONTROL
v SORT-CORE-SIZE
v SORT-FILE-SIZE
v SORT-MESSAGE
v SORT-MODE-SIZE
v SORT-RETURN
v TALLY
v XML-CODE
v XML-EVENT
v XML-INFORMATION
v XML-NAMESPACE
v XML-NAMESPACE-PREFIX
v XML-NNAMESPACE
v XML-NNAMESPACE-PREFIX
v XML-NTEXT
v XML-TEXT

For the first call to a program after a cancel of that program, or for a method
invocation, the compiler initializes the special register fields to their initial values.

For the following four cases:

v Programs that have the INITIAL clause specified
v Programs that have the RECURSIVE clause specified
v Programs compiled with the THREAD option
v Methods

16 Enterprise COBOL for z/OS, V6.1 Language Reference

 the following special registers are reset to their initial value on each program or
method entry:
| v JSON-CODE
v RETURN-CODE
v SORT-CONTROL
v SORT-CORE-SIZE
v SORT-FILE-SIZE
v SORT-MESSAGE
v SORT-MODE-SIZE
v SORT-RETURN
v TALLY
v XML-CODE
v XML-EVENT

Further, in the above four cases, values set in ADDRESS OF special registers persist
only for the span of the particular program or method invocation.

In all other cases, the special registers will not be reset; they will be unchanged
from the value contained on the previous CALL or INVOKE.

Unless otherwise explicitly restricted, a special register can be used wherever a

data-name or identifier that has the same definition as the implicit definition of the
special register can be used. Implicit definitions, if applicable, are given in the
specification of each special register.

You can specify an alphanumeric special register in a function wherever an

alphanumeric argument to a function is allowed, unless specifically prohibited.

If qualification is allowed, special registers can be qualified as necessary to provide

uniqueness. (For more information, see “Qualification” on page 69.)

ADDRESS OF
The ADDRESS OF special register references the address of a data item in the
LINKAGE SECTION, the LOCAL-STORAGE SECTION, or the
WORKING-STORAGE SECTION.

For 01 and 77 level items in the LINKAGE SECTION, the ADDRESS OF special
register can be used as either a sending item or a receiving item. For all other
operands, the ADDRESS OF special register can be used only as a sending item.

The ADDRESS OF special register is implicitly defined as USAGE POINTER.

A function-identifier is not allowed as the operand of the ADDRESS OF special

register.

DEBUG-ITEM
The DEBUG-ITEM special register provides information for a debugging
declarative procedure about the conditions that cause debugging section execution.

DEBUG-ITEM has the following implicit description:

Chapter 3. Character-strings: COBOL words and literals 17

 01 DEBUG-ITEM.
02 DEBUG-LINE PICTURE IS X(6).
02 FILLER PICTURE IS X VALUE SPACE.
02 DEBUG-NAME PICTURE IS X(30).
02 FILLER PICTURE IS X VALUE SPACE.
02 DEBUG-SUB-1 PICTURE IS S9999 SIGN IS LEADING SEPARATE CHARACTER.
02 FILLER PICTURE IS X VALUE SPACE.
02 DEBUG-SUB-2 PICTURE IS S9999 SIGN IS LEADING SEPARATE CHARACTER.
02 FILLER PICTURE IS X VALUE SPACE.
02 DEBUG-SUB-3 PICTURE IS S9999 SIGN IS LEADING SEPARATE CHARACTER.
02 FILLER PICTURE IS X VALUE SPACE.
02 DEBUG-CONTENTS PICTURE IS X(n).

Before each debugging section is executed, DEBUG-ITEM is filled with spaces. The
contents of the DEBUG-ITEM subfields are updated according to the rules for the
MOVE statement, with one exception: DEBUG-CONTENTS is updated as if the
move were an alphanumeric-to-alphanumeric elementary move without conversion
of data from one form of internal representation to another.

After updating, the contents of the DEBUG-ITEM subfields are:

DEBUG-LINE
The source-statement sequence number (or the compiler-generated
sequence number, depending on the compiler option chosen) that caused
execution of the debugging section.
DEBUG-NAME
The first 30 characters of the name that caused execution of the debugging
section. Any qualifiers are separated by the word 'OF'.
DEBUG-SUB-1, DEBUG-SUB-2, DEBUG-SUB-3
Always set to spaces. These subfields are documented for compatibility
with previous COBOL products.
DEBUG-CONTENTS
Data is moved into DEBUG-CONTENTS, as shown in the following table.
Table 2. DEBUG-ITEM subfield contents
Cause of debugging Statement referred to in Contents of Contents of
section execution DEBUG-LINE DEBUG-NAME DEBUG-CONTENTS
procedure-name-1 ALTER ALTER statement procedure-name-1 procedure-name-n in TO
reference PROCEED TO phrase
GO TO procedure-name-n GO TO statement procedure-name-n Spaces
procedure-name-n in SORT or SORT or MERGE statement procedure-name-n "SORT INPUT", "SORT
MERGE input/output OUTPUT", or "MERGE
procedure OUTPUT" (as applicable)
PERFORM statement This PERFORM statement procedure-name-n "PERFORM LOOP"
transfer of control
procedure-name-n in a USE Statement causing USE procedure-name-n "USE PROCEDURE"
procedure procedure execution
Implicit transfer from a Previous statement procedure-name-n "FALL THROUGH"
previous sequential executed in previous
procedure sequential procedure1
First execution of first Line number of first Name of first "START PROGRAM"
nondeclarative procedure nondeclarative nondeclarative procedure
procedure-name

1. If this procedure is preceded by a section header, and control is passed through the section header, the statement
number refers to the section header.

18 Enterprise COBOL for z/OS, V6.1 Language Reference

 JNIENVPTR
The JNIENVPTR special register references the Java Native Interface (JNI)
environment pointer. The JNI environment pointer is used in calling Java callable
services.

JNIENVPTR is implicitly defined as USAGE POINTER, and cannot be specified as

a receiving data item.

For information about using JNIENVPTR and JNI callable services, see Accessing
JNI services in the Enterprise COBOL Programming Guide.

| JSON-CODE
| The JSON-CODE special register is used to indicate either that a JSON GENERATE
| statement executed successfully or that an exception occurred during JSON
| generation.

| The JSON-CODE special register has the implicit definition:

| 01 JSON-CODE PICTURE S9(9) USAGE BINARY VALUE 0.

| When used in nested programs, this special register is implicitly defined with the
| global attribute in the outermost program.

| At termination of a JSON GENERATE statement, JSON-CODE contains either zero,

| indicating successful completion of JSON generation, or a nonzero error code,
| indicating that an exception occurred during JSON generation. JSON GENERATE
| exception codes are detailed in JSON GENERATE exceptions in the Enterprise
| COBOL Programming Guide.

| LENGTH OF
The LENGTH OF special register contains the number of bytes used by a data
item.

LENGTH OF creates an implicit special register that contains the current byte
length of the data item referenced by the identifier.

For data items described with usage DISPLAY-1 (DBCS data items) and data items
described with usage NATIONAL, each character occupies 2 bytes of storage.

LENGTH OF can be used in the PROCEDURE DIVISION anywhere a numeric

data item that has the same definition as the implied definition of the LENGTH OF
special register can be used.

The LENGTH OF special register has the implicit definition:

USAGE IS BINARY PICTURE 9(9).

If the data item referenced by the identifier contains the GLOBAL clause, the
LENGTH OF special register is a global data item.

The LENGTH OF special register can appear within either the starting character
position or the length expressions of a reference-modification specification.
However, the LENGTH OF special register cannot be applied to any operand that
is reference-modified.

Chapter 3. Character-strings: COBOL words and literals 19

 The LENGTH OF operand cannot be a function, but the LENGTH OF special
register is allowed in a function where an integer argument is allowed.

If the LENGTH OF special register is used as the argument to the LENGTH

function, the result is always 4, independent of the argument specified for
LENGTH OF.

If the ADDRESS OF special register is used as the argument to the LENGTH

function, the result is always 4, independent of the argument specified for
ADDRESS OF.

LENGTH OF cannot be either of the following items:

v A receiving data item
v A subscript

When the LENGTH OF special register is used as a parameter on a CALL

statement, it must be passed BY CONTENT or BY VALUE.

When a table element is specified, the LENGTH OF special register contains the
length in bytes of one occurrence. When referring to a table element, the element
name need not be subscripted.

A value is returned for any identifier whose length can be determined, even if the
area referenced by the identifier is currently not available to the program.

A separate LENGTH OF special register exists for each identifier referenced with
the LENGTH OF phrase. For example:
MOVE LENGTH OF A TO B
DISPLAY LENGTH OF A, A
ADD LENGTH OF A TO B
CALL "PROGX" USING BY REFERENCE A BY CONTENT LENGTH OF A

The intrinsic function LENGTH can also be used to obtain the length of a data
item. For data items of usage NATIONAL, the length returned by the LENGTH
function is the number of national character positions, rather than bytes; thus the
LENGTH OF special register and the LENGTH intrinsic function have different
results for data items of usage NATIONAL. Also, for table elements, the intrinsic
function LENGTH requires a subscript, while the LENGTH OF special register
does not. For all other data items, the result is the same.

The LENGTH intrinsic function, when applied to a null-terminated alphanumeric

literal, returns the number of bytes in the literal prior to but not including the
terminating null. (The LENGTH special register does not support literal operands.)
For details about null-terminated alphanumeric literals, see “Null-terminated
alphanumeric literals” on page 40.

LINAGE-COUNTER
A separate LINAGE-COUNTER special register is generated for each FD entry that
contains a LINAGE clause. When more than one is generated, you must qualify
each reference to a LINAGE-COUNTER with its related file-name.

The implicit description of the LINAGE-COUNTER special register is in one of the

following cases:
v If the LINAGE clause specifies a data-name, LINAGE-COUNTER has the same
PICTURE and USAGE as that data-name.

20 Enterprise COBOL for z/OS, V6.1 Language Reference

 v If the LINAGE clause specifies an integer, LINAGE-COUNTER is a binary item
with the same number of digits as that integer.

For more information, see “LINAGE clause” on page 184.

The value in LINAGE-COUNTER at any given time is the line number at which
the device is positioned within the current page. LINAGE-COUNTER can be
referred to in PROCEDURE DIVISION statements; it must not be modified by
them.

LINAGE-COUNTER is initialized to 1 when an OPEN statement for its associated

file is executed.

LINAGE-COUNTER is automatically modified by any WRITE statement for this

file. (See “WRITE statement” on page 478.)

If the file description entry for a sequential file contains the LINAGE clause and
the EXTERNAL clause, the LINAGE-COUNTER data item is an external data item.
If the file description entry for a sequential file contains the LINAGE clause and
the GLOBAL clause, the LINAGE-COUNTER data item is a global data item.

You can specify the LINAGE-COUNTER special register wherever an integer

argument to a function is allowed.

RETURN-CODE
The RETURN-CODE special register can be used to pass a return code to the
calling program or operating system when the current COBOL program ends.

When a COBOL program ends:

v If control returns to the operating system, the value of the RETURN-CODE
special register is passed to the operating system as a user return code. The
supported user return code values are determined by the operating system, and
might not include the full range of RETURN-CODE special register values.
v If control returns to a calling program, the value of the RETURN-CODE special
register is passed to the calling program. If the calling program is a COBOL
program, the RETURN-CODE special register in the calling program is set to the
value of the RETURN-CODE special register in the called program.

The RETURN-CODE special register has the implicit definition:

01 RETURN-CODE GLOBAL PICTURE S9(4) USAGE BINARY VALUE ZERO.

When used in nested programs, this special register is implicitly defined with the
GLOBAL clause in the outermost program.

The following examples show how to set the RETURN-CODE special register:
v COMPUTE RETURN-CODE = 8.
v MOVE 8 to RETURN-CODE.

The RETURN-CODE special register does not return a value from an invoked
method or from a program that uses CALL ... RETURNING. For more information,
see “INVOKE statement” on page 372 or “CALL statement” on page 316.

You can specify the RETURN-CODE special register in a function wherever an

integer argument is allowed.

Chapter 3. Character-strings: COBOL words and literals 21

 The RETURN-CODE special register does not return information from a service
call for a Language Environment callable service. For more information, see Using
Language Environment callable services in the Enterprise COBOL Programming Guide
and the Language Environment Programming Guide.

SHIFT-OUT and SHIFT-IN

You can specify the SHIFT-OUT and SHIFT-IN special registers in a function
wherever an alphanumeric argument is allowed.

The SHIFT-OUT and SHIFT-IN special registers are implicitly defined as

alphanumeric data items of the format:
01 SHIFT-OUT GLOBAL PICTURE X(1) USAGE DISPLAY VALUE X"0E".
01 SHIFT-IN GLOBAL PICTURE X(1) USAGE DISPLAY VALUE X"0F".

When used in nested programs, these special registers are implicitly defined with
the global attribute in the outermost program.

These special registers represent EBCDIC shift-out and shift-in control characters,
which are unprintable characters.

These special registers cannot be receiving items. SHIFT-OUT and SHIFT-IN cannot
be used in place of the keyboard control characters when you are defining DBCS
user-defined words or specifying EBCDIC DBCS literals.

The following example shows how SHIFT-OUT and SHIFT-IN might be used:
DATA DIVISION.
WORKING-STORAGE.
01 DBCSGRP.
05 SO PIC X.
05 DBCSITEM PIC G(3) USAGE DISPLAY-1.
05 SI PIC X.
...
PROCEDURE DIVISION.
MOVE SHIFT-OUT TO SO
MOVE G"<D1D2D3>" TO DBCSITEM
MOVE SHIFT-IN TO SI
DISPLAY DBCSGRP

SORT-CONTROL
The SORT-CONTROL special register is the name of an alphanumeric data item.

Restriction: The SORT-CONTROL special register is not applicable to sorting a

table with the format 2 SORT statement.

The SORT-CONTROL special register has the implicit definition:

01 SORT-CONTROL GLOBAL PICTURE X(8) USAGE DISPLAY VALUE "IGZSRTCD".

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

This register contains the ddname of the data set that holds the control statements
used to improve the performance of a sorting or merging operation.

You can provide a DD statement for the data set identified by the
SORT-CONTROL special register. Enterprise COBOL will attempt to open the data
set at execution time. Any error will be diagnosed with an informational message.

22 Enterprise COBOL for z/OS, V6.1 Language Reference

 You can specify the SORT-CONTROL special register in a function wherever an
alphanumeric argument is allowed.

The SORT-CONTROL special register is not necessary for a successful sorting or

merging operation.

The sort control file takes precedence over the SORT special registers.

SORT-CORE-SIZE
The SORT-CORE-SIZE special register is the name of a binary data item that you
can use to specify the number of bytes of storage available to the sort utility.

Restriction: The SORT-CORE-SIZE special register is not applicable to sorting a

table with the format 2 SORT statement.

The SORT-CORE-SIZE special register has the implicit definition:

01 SORT-CORE-SIZE GLOBAL PICTURE S9(8) USAGE BINARY VALUE ZERO.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

SORT-CORE-SIZE can be used in place of the MAINSIZE or RESINV control

statements in the sort control file:
v The 'MAINSIZE=' option control statement keyword is equivalent to
SORT-CORE-SIZE with a positive value.
v The 'RESINV=' option control statement keyword is equivalent to
SORT-CORE-SIZE with a negative value.
v The 'MAINSIZE=MAX' option control statement keyword is equivalent to
SORT-CORE-SIZE with a value of +999999 or +99999999.

You can specify the SORT-CORE-SIZE special register in a function wherever an

integer argument is allowed.

SORT-FILE-SIZE
The SORT-FILE-SIZE special register is the name of a binary data item that you can
use to specify the estimated number of records in the sort input file, file-name-1.

Restriction: The SORT-FILE-SIZE special register is not applicable to sorting a

table with the format 2 SORT statement.

The SORT-FILE-SIZE special register has the implicit definition:

01 SORT-FILE-SIZE GLOBAL PICTURE S9(8) USAGE BINARY VALUE ZERO.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

SORT-FILE-SIZE is equivalent to the 'FILSZ=Ennn' control statement in the sort

control file.

You can specify the SORT-FILE-SIZE special register in a function wherever an

integer argument is allowed.

Chapter 3. Character-strings: COBOL words and literals 23

 SORT-MESSAGE
The SORT-MESSAGE special register is the name of an alphanumeric data item
that is available to both sort and merge programs.

Restriction: The SORT-MESSAGE special register is not applicable to sorting a

table with the format 2 SORT statement.

The SORT-MESSAGE special register has the implicit definition:

01 SORT-MESSAGE GLOBAL PICTURE X(8) USAGE DISPLAY VALUE "SYSOUT".

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

You can use the SORT-MESSAGE special register to specify the ddname of a data
set that the sort utility should use in place of the SYSOUT data set.

The ddname specified in SORT-MESSAGE is equivalent to the name specified on

the 'MSGDDN=' control statement in the sort control file.

You can specify the SORT-MESSAGE special register in a function wherever an

alphanumeric argument is allowed.

SORT-MODE-SIZE
The SORT-MODE-SIZE special register is the name of a binary data item that you
can use to specify the length of variable-length records that occur most frequently.

Restriction: The SORT-MODE-SIZE special register is not applicable to sorting a

table with the format 2 SORT statement.

The SORT-MODE-SIZE special register has the implicit definition:

01 SORT-MODE-SIZE GLOBAL PICTURE S9(5) USAGE BINARY VALUE ZERO.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

SORT-MODE-SIZE is equivalent to the 'SMS=' control statement in the sort control

file.

You can specify the SORT-MODE-SIZE special register in a function wherever an

integer argument is allowed.

SORT-RETURN
The SORT-RETURN special register is the name of a binary data item and is
available to both sort and merge programs.

Restriction: The SORT-RETURN special register is not applicable to sorting a table

with the format 2 SORT statement.

The SORT-RETURN special register has the implicit definition:

01 SORT-RETURN GLOBAL PICTURE S9(4) USAGE BINARY VALUE ZERO.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

24 Enterprise COBOL for z/OS, V6.1 Language Reference

 The SORT-RETURN special register contains a return code of 0 (successful) or 16
(unsuccessful) at the completion of a sort or merge operation. If the sort or merge
is unsuccessful and there is no reference to this special register anywhere in the
program, a message is displayed on the terminal.

You can set the SORT-RETURN special register to 16 in an error declarative or

input/output procedure to terminate a sort or merge operation before all records
are processed. The operation is terminated on the next input or output function for
the sort or merge operation.

You can specify the SORT-RETURN special register in a function wherever an

integer argument is allowed.

TALLY
The TALLY special register is the name of a binary data item.

See the following definition of a binary data item:

01 TALLY GLOBAL PICTURE 9(5) USAGE BINARY VALUE ZERO.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

You can refer to or modify the contents of TALLY.

You can specify the TALLY special register in a function wherever an integer
argument is allowed.

WHEN-COMPILED
The WHEN-COMPILED special register contains the date at the start of the
compilation.

WHEN-COMPILED is an alphanumeric data item that has the implicit definition:

01 WHEN-COMPILED GLOBAL PICTURE X(16) USAGE DISPLAY.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

The WHEN-COMPILED special register has the format:

MM/DD/YYhh.mm.ss (MONTH/DAY/YEARhour.minute.second)

For example, if compilation began at 2:04 PM on 15 October 2007,

WHEN-COMPILED would contain the value 10/15/0714.04.00.

WHEN-COMPILED can be used only as the sending field in a MOVE statement.

WHEN-COMPILED special register data cannot be reference-modified.

The compilation date and time can also be accessed with the intrinsic function
WHEN-COMPILED (see “WHEN-COMPILED” on page 554). That function
supports four-digit year values and provides additional information.

XML-CODE
The XML-CODE special register is used to communicate status between the XML
parser and the processing procedure that was identified in an XML PARSE

Chapter 3. Character-strings: COBOL words and literals 25

 statement, and to indicate either that an XML GENERATE statement executed
successfully or that an exception occurred during XML generation.

The XML-CODE special register has the implicit definition:

01 XML-CODE PICTURE S9(9) USAGE BINARY VALUE 0.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

When the XML parser encounters an XML event, it sets XML-CODE and then
passes control to the processing procedure. For all events except an EXCEPTION
event, XML-CODE contains zero when the processing procedure receives control.

For an EXCEPTION event, the parser sets XML-CODE to an exception code that
indicates the nature of the exception. XML PARSE exception codes are discussed in
Handling XML PARSE exceptions in the Enterprise COBOL Programming Guide.

For some XML events, you can set XML-CODE before returning to the parser to
control subsequent processing of the document. For details, see XML-CODE in the
Enterprise COBOL Programming Guide.

When the parser returns control to the XML PARSE statement, XML-CODE
contains the most recent value set by the processing procedure or the parser. In
some cases, the parser overrides the value set by the processing procedure.

At termination of an XML GENERATE statement, XML-CODE contains either zero,

indicating successful completion of XML generation, or a nonzero error code,
indicating that an exception occurred during XML generation. XML GENERATE
exception codes are detailed in XML GENERATE exceptions in the Enterprise COBOL
Programming Guide.

RELATED CONCEPTS
XML-CODE (Enterprise COBOL Programming Guide)

RELATED TASKS
Handling XML PARSE exceptions (Enterprise COBOL Programming Guide)

RELATED REFERENCES
XML GENERATE exceptions (Enterprise COBOL Programming Guide)

XML-EVENT
The XML-EVENT special register communicates event information from the XML
parser to the processing procedure identified in the XML PARSE statement.

Before passing control to the processing procedure, the XML parser sets the
XML-EVENT special register to the name of the XML event. The specific events
and the associated special registers that are set depend on the setting of the
XMLPARSE compiler option, XMLPARSE(XMLSS) or XMLPARSE(COMPAT).

The parser uses the following special registers when XMLPARSE(XMLSS) is in

effect:
v XML-CODE
v XML-EVENT
v XML-TEXT or XML-NTEXT

26 Enterprise COBOL for z/OS, V6.1 Language Reference

 v XML-NAMESPACE or XML-NNAMESPACE
v XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX

The parser uses the following special registers when XMLPARSE(COMPAT) is in

effect:
v XML-CODE
v XML-EVENT
v XML-TEXT or XML-NTEXT

The parser sets XML-NTEXT to associated XML text when the XML document is in
a national data item, and sets XML-TEXT when the XML document is in an
alphanumeric data item. When the XMLPARSE(COMPAT) compiler option is in
effect, the parser sets XML-NTEXT to the text of any numeric character reference
(for events ATTRIBUTE-NATIONAL-CHARACTER and CONTENT-NATIONAL-
CHARACTER) regardless of the type of the XML document data item.

When the XMLPARSE(XMLSS) compiler option is in effect, the parser sets

XML-NNAMESPACE and XML-NNAMESPACE-PREFIX when the XML document
is in a national data item and when the RETURNING NATIONAL phrase is
specified in the XML PARSE statement; otherwise, the parser sets
XML-NAMESPACE and XML-NAMESPACE-PREFIX.

Table 3 shows XML events and special register contents for parsing with the
XMLPARSE(XMLSS) and XMLPARSE(COMPAT) options.

XML-EVENT has the implicit definition:

01 XML-EVENT USAGE DISPLAY PICTURE X(30) VALUE SPACE.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

XML-EVENT cannot be used as a receiving data item.

Table 3. XML events and associated special register contents
XML-EVENT XMLPARSE(XMLSS)1 XMLPARSE(COMPAT)1
ATTRIBUTE-CHARACTER n/a5 XML-TEXT or XML-NTEXT
contains the single character that
corresponds with the predefined
entity reference in the attribute
value.
ATTRIBUTE-CHARACTERS XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the value within quotation marks or contains the value within
apostrophes. This can be a substring of quotation marks or apostrophes.
the attribute value. This can be a substring of the
attribute value if the value
includes a character reference or
an entity reference.

Chapter 3. Character-strings: COBOL words and literals 27

Table 3. XML events and associated special register contents (continued)
XML-EVENT XMLPARSE(XMLSS)1 XMLPARSE(COMPAT)1
ATTRIBUTE-NAME For attribute names that are not in a XML-TEXT or XML-TEXT
namespace, XML-TEXT or contains the attribute name (the
XML-NTEXT contains the attribute string to the left of the equal
name. sign).

For attributes with names in a

nondefault namespace, attribute names
are always prefixed and have the form:
prefix:local-part = "AttValue".

XML-TEXT or XML-NTEXT contains

the local-part, XML-NAMESPACE or
XML-NNAMESPACE contains the
namespace identifier, and
XML-NAMESPACE-PREFIX or
XML-NNAMESPACE-PREFIX contains
the prefix.
ATTRIBUTE-NATIONAL- Regardless of the type of the XML XML-TEXT or XML-NTEXT
CHARACTER document, XML-TEXT is empty with content is the same as for
length zero and XML-NTEXT contains XMLPARSE(XMLSS).
the single national character that
correponds with the numeric character
reference. 2
COMMENT XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the text of the comment between the always contains the complete text
opening character sequence "<!--" and of the comment.
the closing character sequence "-->".
This can be a substring of the text.
CONTENT-CHARACTER n/a5 XML-TEXT or XML-NTEXT
contains the single character that
corresponds with the predefined
entity reference in the element
content.
CONTENT-CHARACTERS XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the character content of the element contains the character content of
between start and end tags. This can be the element between start and
a substring of the content. end tags. This can be a substring
of the character content if the
content includes a character
reference or an entity reference.
CONTENT-NATIONAL-CHARACTER Regardless of the type of the XML XML-TEXT or XML-NTEXT
document, XML-TEXT is empty with content is the same as for
length zero and XML-NTEXT contains XMLPARSE(XMLSS).
the single national character that
corresponds with the numeric character
reference.2
DOCUMENT-TYPE-DECLARATION XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the name of the root element, as contains the entire document type
specified in the document type declaration, including the
delcaration. opening and closing character
sequences "<!DOCTYPE" and ">".
ENCODING-DECLARATION XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the value, between quotation marks or content is the same as for
apostrophes, of the encoding XMLPARSE(XMLSS).
declaration in the XML declaration.

28 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 3. XML events and associated special register contents (continued)
XML-EVENT XMLPARSE(XMLSS)1 XMLPARSE(COMPAT)1
END-OF-CDATA-SECTION All XML special registers except XML-TEXT or XML-NTEXT
XML-CODE and XML-EVENT are contains the string "]]>".
empty with length zero.
END-OF-DOCUMENT All XML special registers except XML-TEXT or XML-NTEXT
XML-CODE and XML-EVENT are content is the same as for
empty with length zero. XMLPARSE(XMLSS).
END-OF-ELEMENT XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the local part of the end element tag or contains the name of the end
empty element tag name. element tag or empty element
tag.
If the element name is in a nondefault
namespace, XML-NAMESPACE or
XML-NNAMESPACE contains the
namespace identifier.

If the element name is in a namespace

and is prefixed (of the form
prefix:local-part), XML-NAMESPACE-
PREFIX or XML-NNAMESPACE-
PREFIX contains the prefix.
END-OF-INPUT All XML special registers except n/a6
XML-CODE and XML-EVENT are
empty with length zero.

To parse an additional segment of an

XML document, move the next
segment to identifier-1 and set
XML-CODE to 1.
EXCEPTION XML-CODE contains the unique return XML-CODE contains the unique
code and reason code that identifies the error code that identifies the
exception. exception.3

XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT

the document fragment up to the point contains the part of the document
of the error or anomaly that caused the that was successfully scanned, up
exception.4 to and including the point at
which the exception was
All other XML special registers are detected.
empty with length zero.

Chapter 3. Character-strings: COBOL words and literals 29

Table 3. XML events and associated special register contents (continued)
XML-EVENT XMLPARSE(XMLSS)1 XMLPARSE(COMPAT)1
NAMESPACE-DECLARATION XML-TEXT and XML-NTEXT are both n/a6
empty with length zero.
(ATTRIBUTE-NAME and
XML-NAMESPACE or ATTRIBUTE-CHARACTERS
XML-NNAMESPACE contains the events are signaled instead.)
declared namespace identifier. If the
namespace is "undeclared" by
specifying the empty string,
XML-NAMESPACE and
XML-NNAMESPACE are empty with
length zero.

XML-NAMESPACE-PREFIX or
XML-NNAMESPACE-PREFIX contains
the prefix if the namespace declaration
is of the form xmlns:prefix =
"namespace-identifier"; otherwise, if the
declaration is for the default
namespace and thus the attribute name
is xmlns, XML-NAMESPACE-PREFIX
and XML-NNAMESPACE-PREFIX are
both empty with length zero.
PROCESSING-INSTRUCTION-DATA XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the rest of the processing instruction always contains the complete
(after the target name), not including processing instruction data.
the closing sequence "?>", but including
trailing, and not leading, white space
characters. This can be a substring of
the processing instruction data.
PROCESSING-INSTRUCTION- XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
TARGET the processing instruction target name, content is the same as for
which occurs immediately after the XMLPARSE(XMLSS). This event
processing instruction opening occurs only once for a given
sequence, "<?". This event can occur processing instruction.
multiple times for a given processing
instruction: one occurrence preceding
each substring of the data.
STANDALONE-DECLARATION XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the value, between quotation marks or content is the same as for
apostrophes ("yes" or "no"), of the XMLPARSE(XMLSS).
stand-alone declaration in the XML
declaration.
START-OF-CDATA-SECTION All XML special registers except XML-TEXT or XML-NTEXT
XML-CODE and XML-EVENT are contains the string "<![CDATA[".
empty with length zero.
START-OF-DOCUMENT All XML special registers except XML-TEXT or XML-NTEXT
XML-CODE and XML-EVENT are contains the entire document.
empty with length zero.

30 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 3. XML events and associated special register contents (continued)
XML-EVENT XMLPARSE(XMLSS)1 XMLPARSE(COMPAT)1
START-OF-ELEMENT XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the local part of the start element tag contains the name of the start
name or the local part of the empty element tag or empty element
element tag name. tag, also known as the element
type.
If the element name is in a namespace,
XML-NAMESPACE or
XML-NNAMESPACE contains the
namespace identifier.

If the element name is in a namespace

and is prefixed (of the form
prefix:local-part, XML-NAMESPACE-
PREFIX or XML-NNAMESPACE-
PREFIX contains the prefix.
UNKNOWN-REFERENCE-IN- n/a5 XML-TEXT or XML-NTEXT
ATTRIBUTE contains the entity reference
For XMLPARSE(XMLSS), the parser name, not including the "&" and
always signals EXCEPTION. ";" delimiters.
UNKNOWN-REFERENCE-IN- n/a5 XML-TEXT or XML-NTEXT
CONTENT contains the entity reference
For XMLPARSE(XMLSS), the parser name, not including the "&" and
signals UNRESOLVED-REFERENCE or ";" delimiters.
EXCEPTION instead.

See "Unresolved references" below for

additional details.
UNRESOLVED-REFERENCE XML-TEXT or XML-NTEXT contains n/a6
the entity name from XML content, not
including the "&" and ";" delimiters. (The parser signals
UNKNOWN-REFERENCE-IN-
See "Unresolved references" below for CONTENT instead.)
additional details.
VERSION-INFORMATION XML-TEXT or XML-NTEXT contains XML-TEXT or XML-NTEXT
the value, between quotation marks or content is the same as for
apostrophes, of the version information XMLPARSE(XMLSS).
in the XML declaration.

Chapter 3. Character-strings: COBOL words and literals 31

Table 3. XML events and associated special register contents (continued)
XML-EVENT XMLPARSE(XMLSS)1 XMLPARSE(COMPAT)1

1. For all events except EXCEPTION, XML-CODE contains zero. Unless stated otherwise, the namespace XML
registers (XML-NAMESPACE, XML-NNAMESPACE, XML-NAMESPACE-PREFIX, and XML-NNAMESPACE-
PREFIX) are empty and have length zero.
2. National characters with scalar values greater than 65,535 (NX"FFFF") are represented using two encoding units
(a "surrogate pair"). Programmers are responsible for ensuring that operations on the content of XML-NTEXT do
not split the pair of encoding units that together form a graphic character, thereby forming invalid data.
3. For XMLPARSE(COMPAT), exceptions for encoding conflicts are signaled before parsing begins. For these
exceptions, XML-TEXT or XML-NTEXT is either zero length or contains only the encoding declaration value
from the document. See XML PARSE exceptions with XMLPARSE(COMPAT) in effect in the Enterprise COBOL
Programming Guide for information about XML exception codes.
4. If an END-OF-INPUT XML event previously occurred and the processing procedure provided a new document
segment, XML-TEXT or XML-NTEXT contains only the new segment.
If the anomaly occurs before parsing begins (for example, the encoding specification is invalid), XML-TEXT or
XML-NTEXT are empty with length zero.
The fragment might or might not include the anomaly. For a duplicate attribute name, for example, the fragment
includes the incorrect attribute. For an invalid character, the fragment includes document text up to, but not
including, the invalid character.
5. n/a. Not applicable; occurs only with XMLPARSE(COMPAT).
6. n/a. Not applicable; occurs only wtih XMLPARSE(XMLSS).

Unresolved References:

An unresolved entity reference is a reference to the name of an entity that has no

declaration in the document type definition (DTD).

The parser signals an UNRESOLVED-REFERENCE event only if all of the

following conditions are true:
v The unresolved reference is within element content, not an attribute value.
v The XML document starts with an XML declaration that specifies
standalone="no".
v The XML document contains a document type declaration, for example,
<!DOCTYPE rootElementName>
v If the VALIDATING phrase is specified on the XML PARSE statement, the
document type declaration must also specify an external DTD subset, for
example:
<!DOCTYPE rootElementName SYSTEM "someOther.dtd">
Otherwise the parser signals an EXCEPTION event instead of
UNRESOLVED-REFERENCE.

XML-INFORMATION
The XML-INFORMATION special register is used to provide additional
information to an XML PARSE processing procedure about the status of the parse.

The XML-INFORMATION special register has the implicit definition:

01 XML-INFORMATION PICTURE S9(9) USAGE BINARY VALUE 0.

This register provides a mechanism to easily determine whether an XML EVENT is

complete. Sometimes XML content might be split across multiple events and the

32 Enterprise COBOL for z/OS, V6.1 Language Reference

 application must concatenate the pieces of content together. The
XML-INFORMATION register is used to indicate whether or not content of the
XML event is complete.

The value of the XML-INFORMATION register is set as follows for the various
XML events:
v ATTRIBUTE-CHARACTERS
– 1 indicates that the attribute value in XML-TEXT or XML-NTEXT special
register is complete
– 2 indicates that the attribute value in XML-TEXT or XML-NTEXT special
register is not complete
– 4, 8, 16, ... are reserved for future use
v CONTENT-CHARACTERS
– 1 indicates that the content value in XML-TEXT or XML-NTEXT special
register is complete
– 2 indicates that the content value in XML-TEXT or XML-NTEXT special
register is not complete
– 4, 8, 16, ... are reserved for future use
v All other events
– 0 indicates that no additional information is currently available
– 2, 4, 8, 16, ... are reserved for future use

XML-NAMESPACE
The XML-NAMESPACE special register is defined during XML parsing to contain
the identifier of the namespace, if any, associated with the name in XML-TEXT for
XML events START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME,
and to contain the declared namespace identifier for XML event
NAMESPACE-DECLARATION.

The parser sets XML-NAMESPACE to the identifier of the namespace associated

with a name before transferring control to the processing procedure when the
operand of the XML PARSE statement is an alphanumeric data item and the
RETURNING NATIONAL phrase is not specified in the XML PARSE statement.

To use XML-NAMESPACE, you must compile with the XMLPARSE(XMLSS)

compiler option.

XML-NAMESPACE is an elementary data item of category alphanumeric. The

length of XML-NAMESPACE can vary from 0 through 32,768 bytes. The length at
run time is the length of the contained namespace identifier.

There is no equivalent COBOL data description entry.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

XML-NAMESPACE has a length of zero for:

v The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML
events if there is no namespace associated with a name
v The NAMESPACE-DECLARATION XML event if the namespace is undeclared by
specifying the empty string
v All other XML events

Chapter 3. Character-strings: COBOL words and literals 33

 When XML-NAMESPACE is set, the XML-NNAMESPACE special register has a
length of zero. At any given time, only one of the two special registers
XML-NAMESPACE and XML-NNAMESPACE has a nonzero length.

Use the LENGTH function or the LENGTH OF special register to determine the
number of bytes that XML-NAMESPACE contains.

XML-NAMESPACE cannot be used as a receiving item.

XML-NNAMESPACE
The XML-NNAMESPACE special register is defined during XML parsing to
contain the identifier of the namespace, if any, associated with the name in
XML-NTEXT for XML events START-OF-ELEMENT, END-OF-ELEMENT, and
ATTRIBUTE-NAME, and to contain the declared namespace identifier for XML
event NAMESPACE-DECLARATION.

The parser sets XML-NNAMESPACE to the identifier of the namespace associated

with a name before transferring control to the processing procedure when the
RETURNING NATIONAL phrase is specified in the XML PARSE statement or the
operand of the XML PARSE statement is a national data item.

To use XML-NNAMESPACE, you must compile with the XMLPARSE(XMLSS)

compiler option.

XML-NNAMESPACE is an elementary data item of category national. The length

of XML-NNAMESPACE can vary from 0 through 16,384 national characters (0
through 32,768 bytes). The length at run time is the length of the contained
namespace identifier.

There is no equivalent COBOL data description entry.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

XML-NNAMESPACE has a length of zero for:

v The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML
events, if there is no namespace associated with a name
v The NAMESPACE-DECLARATION XML event if the namespace is undeclared by
specifying the empty string
v All other XML events

When XML-NNAMESPACE is set, the XML-NAMESPACE special register has a

length of zero. At any given time, only one of the two special registers
XML-NNAMESPACE and XML-NAMESPACE has a nonzero length.

Use the LENGTH function to determine the number of national character positions
that XML-NNAMESPACE contains; use the LENGTH OF special register to
determine the number of bytes.

XML-NNAMESPACE cannot be used as a receiving item.

XML-NAMESPACE-PREFIX
The XML-NAMESPACE-PREFIX special register is defined during XML parsing to
contain the prefix, if any, of the name in XML-TEXT for XML events

34 Enterprise COBOL for z/OS, V6.1 Language Reference

 START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to
contain the local attribute name for XML event NAMESPACE-DECLARATION.

The namespace prefix is used as an alias for the complete namespace identifier.

The parser sets XML-NAMESPACE-PREFIX before transferring control to the

processing procedure when the operand of the XML PARSE statement is an
alphanumeric data item and the RETURNING NATIONAL phrase is not specified.

To use XML-NAMESPACE-PREFIX, you must compile with the

XMLPARSE(XMLSS) compiler option.

XML-NAMESPACE-PREFIX is an elementary data item of category national. The

length of XML-NAMESPACE-PREFIX can vary from 0 through 4,096 bytes. The
length at run time is the length of the contained namespace prefix.

There is no equivalent COBOL data description entry.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

XML-NAMESPACE-PREFIX has a length of zero for:

v The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML
events if the name does not have a prefix
v The NAMESPACE-DECLARATION XML event if the declaration is for the
default namespace, in which case the namespace declaration attribute name is
not prefixed.
v All other XML events

When XML-NAMESPACE-PREFIX is set, the XML-NNAMESPACE-PREFIX special

register has a length of zero. At any given time, only one of the two special
registers XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX has a
nonzero length.

Use the LENGTH function or the LENGTH OF special register to determine the
number of bytes that XML-NAMESPACE-PREFIX contains.

XML-NAMESPACE-PREFIX cannot be used as a receiving item.

XML-NNAMESPACE-PREFIX
The XML-NNAMESPACE-PREFIX special register is defined during XML parsing
to contain the prefix, if any, of the name in XML-NTEXT for XML events
START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME, and to
contain the local attribute name for XML event NAMESPACE-DECLARATION.

The namespace prefix is used as an alias for the complete namespace identifier.

The parser sets XML-NNAMESPACE-PREFIX before transferring control to the

processing procedure when the operand of the XML PARSE statement is a national
data item or the RETURNING NATIONAL phrase is specified in the XML PARSE
statement.

To use XML-NNAMESPACE-PREFIX, you must compile with the

XMLPARSE(XMLSS) compiler option.

Chapter 3. Character-strings: COBOL words and literals 35

 XML-NNAMESPACE-PREFIX is an elementary data item of category national. The
length of XML-NNAMESPACE-PREFIX can vary from 0 through 2048 national
character positions (0 through 4096 bytes). The length at run time is the length of
the contained namespace prefix.

There is no equivalent COBOL data description entry.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

XML-NNAMESPACE-PREFIX has a length of zero for:

v The START-OF-ELEMENT, END-OF-ELEMENT, and ATTRIBUTE-NAME XML
events if the name does not have a prefix
v NAMESPACE-DECLARATION XML event if the declaration is for the default
namespace, in which case the namespace declaration attribute name is not
prefixed.
v All other XML events

When XML-NNAMESPACE-PREFIX is set, the XML-NAMESPACE-PREFIX special

register has a length of zero. At any given time, only one of the two special
registers XML-NNAMESPACE-PREFIX and XML-NAMESPACE-PREFIX has a
nonzero length.

Use the LENGTH function to determine the number of national character positions
that XML-NNAMESPACE contains; use the LENGTH OF special register to
determine the number of bytes.

XML-NNAMESPACE-PREFIX cannot be used as a receiving item.

XML-NTEXT
The XML-NTEXT special register is defined during XML parsing to contain
document fragments that are represented in usage NATIONAL.

XML-NTEXT is an elementary data item of category national of the length of the

contained XML document fragment. The length of XML-NTEXT can vary from 0
through 67,090,431 national character positions. The maximum byte length is
134,180,862.

There is no equivalent COBOL data description entry.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

The parser sets XML-NTEXT to the document fragment associated with an event
before transferring control to the processing procedure in these cases:
v When the operand of the XML PARSE statement is a data item of category
national or the RETURNING NATIONAL phrase is specified in the XML PARSE
statement
v For the ATTRIBUTE-NATIONAL-CHARACTER event
v For the CONTENT-NATIONAL-CHARACTER event

When XML-NTEXT is set, the XML-TEXT special register has a length of zero. At
any given time, only one of the two special registers XML-NTEXT and XML-TEXT
has a nonzero length.

36 Enterprise COBOL for z/OS, V6.1 Language Reference

 Use the LENGTH function to determine the number of national characters that
XML-NTEXT contains. Use the LENGTH OF special register to determine the
number of bytes, rather than the number of national characters, that XML-NTEXT
contains.

XML-NTEXT cannot be used as a receiving item.

XML-TEXT
The XML-TEXT special register is defined during XML parsing to contain
document fragments that are represented in usage DISPLAY.

XML-TEXT is an elementary data item of category alphanumeric of the length of

the contained XML document fragment. The length of XML-TEXT can vary from 0
through 134,180,862 bytes.

There is no equivalent COBOL data description entry.

When used in nested programs, this special register is implicitly defined with the
global attribute in the outermost program.

The parser sets XML-TEXT to the document fragment associated with an event
before transferring control to the processing procedure when the operand of the
XML PARSE statement is an alphanumeric data item and the RETURNING
NATIONAL phrase is not specified in the XML PARSE statement, except for the
ATTRIBUTE-NATIONAL-CHARACTER event and the CONTENT-NATIONAL-
CHARACTER event.

When XML-TEXT is set, the XML-NTEXT special register has a length of zero. At
any given time, only one of the two special registers XML-NTEXT and XML-TEXT
has a nonzero length.

Use the LENGTH function or the LENGTH OF special register for XML-TEXT to
determine the number of bytes that XML-TEXT contains.

XML-TEXT cannot be used as a receiving item.

Literals
A literal is a character-string whose value is specified either by the characters of
which it is composed or by the use of a figurative constant.

For more information about figurative constants, see “Figurative constants” on

page 13.

For descriptions of the different types of literals, see the following topics:
v “Alphanumeric literals”
v “DBCS literals” on page 42
v “National literals” on page 43
v “Numeric literals” on page 41

Alphanumeric literals
Enterprise COBOL provides several formats of alphanumeric literals.

The formats of alphanumeric literals are:

Chapter 3. Character-strings: COBOL words and literals 37

 v Format 1: “Basic alphanumeric literals”
v Format 2: “Alphanumeric literals with DBCS characters”
v Format 3: “Hexadecimal notation for alphanumeric literals” on page 40
v Format 4: “Null-terminated alphanumeric literals” on page 40

Basic alphanumeric literals

Basic alphanumeric literals can contain any character in a single-byte EBCDIC
character set.

The following format is for a basic alphanumeric literal:

Format 1: Basic alphanumeric literals

"single-byte-characters"
’single-byte-characters’

The enclosing quotation marks or apostrophes are excluded from the literal when
the program is compiled.

An embedded quotation mark or apostrophe must be represented by a pair of

quotation marks ("") or a pair of apostrophes (’’), respectively, when it is the
character used as the opening delimiter. For example:
"THIS ISN""T WRONG"
’THIS ISN’’T WRONG’

The delimiter character used as the opening delimiter for a literal must be used as
the closing delimiter for that literal. For example:
’THIS IS RIGHT’
"THIS IS RIGHT"
’THIS IS WRONG"

You can use apostrophes or quotation marks as the literal delimiters independent
of the APOST/QUOTE compiler option.

Any punctuation characters included within an alphanumeric literal are part of the
value of the literal.

The maximum length of an alphanumeric literal is 160 bytes. The minimum length
is 1 byte.

Alphanumeric literals are in the alphanumeric data class and category. (Data
classes and categories are described in “Classes and categories of data” on page
166.)

Alphanumeric literals with DBCS characters

When the DBCS compiler option is in effect, the characters X'0E' and X'0F' in an
alphanumeric literal will be recognized as shift codes for DBCS characters. That is,
the characters between paired shift codes will be recognized as DBCS characters.
Unlike an alphanumeric literal compiled under the NODBCS option, additional
syntax rules apply to DBCS characters in an alphanumeric literal.

Alphanumeric literals with DBCS characters have the following format:

38 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 2: Alphanumeric literals with DBCS characters

"mixed-SBCS-and-DBCS-characters"
’mixed-SBCS-and-DBCS-characters’

" or ’ The opening and closing delimiter. The closing delimiter must match the
opening delimiter.
mixed-SBCS-and-DBCS-characters
Any mix of single-byte and DBCS characters.
Shift-out and shift-in control characters are part of the literal and must be
paired. They must contain zero or an even number of intervening bytes.
Nested shift codes are not allowed in the DBCS portion of the literal.
The syntax rules for single-byte characters in the literal follow the rules for
basic alphanumeric literals. The syntax rules for DBCS characters in the
literal follow the rules for DBCS literals.

The move and comparison rules for alphanumeric literals with DBCS characters
are the same as those for any alphanumeric literal.

The length of an alphanumeric literal with DBCS characters is its byte length,
including the shift control characters. The maximum length is limited by the
available space on one line in Area B. An alphanumeric literal with DBCS
characters cannot be continued.

An alphanumeric literal with DBCS characters is of the alphanumeric category.

Alphanumeric literals with DBCS characters cannot be used:

v As a literal in the following cases:
– ALPHABET clause
– ASSIGN clause
– CALL statement program-ID
– CANCEL statement
– CLASS clause
– CURRENCY SIGN clause
– END PROGRAM marker
– ENTRY statement
– PADDING CHARACTER clause
– PROGRAM-ID paragraph
– RERUN clause
– STOP statement
– XML-SCHEMA clause
v As the external class-name for an object-oriented class
v As the basis-name in a BASIS statement
v As the text-name in a COPY statement
v As the library-name in a COPY statement

Enterprise COBOL statements process alphanumeric literals with DBCS characters

without sensitivity to the shift codes and character codes. The use of statements
that operate on a byte-to-byte basis (for example, STRING and UNSTRING) can

Chapter 3. Character-strings: COBOL words and literals 39

 result in strings that are not valid mixtures of single-byte EBCDIC and DBCS
characters. See Processing alphanumeric data items that contain DBCS data in the
Enterprise COBOL Programming Guide for more information about using
alphanumeric literals and data items with DBCS characters in statements that
operate on a byte-by-byte basis.

Hexadecimal notation for alphanumeric literals

Hexadecimal notation can be used for alphanumeric literals.

Hexadecimal notation has the following format:

Format 3: Hexadecimal notation for alphanumeric literals

X"hexadecimal-digits"
X’hexadecimal-digits’

X" or X’
The opening delimiter for the hexadecimal notation of an alphanumeric
literal.
" or ’ The closing delimiter for the hexadecimal notation of an alphanumeric
literal. If a quotation mark is used in the opening delimiter, a quotation
mark must be used as the closing delimiter. Similarly, if an apostrophe is
used in the opening delimiter, an apostrophe must be used as the closing
delimiter.

Hexadecimal digits are characters in the range '0' to '9', 'a' to 'f', and 'A' to 'F',
inclusive. Two hexadecimal digits represent one character in a single-byte character
set (EBCDIC or ASCII). Four hexadecimal digits represent one character in a DBCS
character set. A string of EBCDIC DBCS characters represented in hexadecimal
notation must be preceded by the hexadecimal representation of a shift-out control
character (X'0E') and followed by the hexadecimal representation of a shift-in
control character (X'0F'). An even number of hexadecimal digits must be specified.
The maximum length of a hexadecimal literal is 320 hexadecimal digits.

The continuation rules are the same as those for any alphanumeric literal. The
opening delimiter (X" or X’) cannot be split across lines.

The DBCS compiler option has no effect on the processing of hexadecimal notation
of alphanumeric literals.

An alphanumeric literal in hexadecimal notation has data class and category

alphanumeric. Hexadecimal notation for alphanumeric literals can be used
anywhere alphanumeric literals can be used.

See also “Hexadecimal notation for national literals” on page 45.

Null-terminated alphanumeric literals

Alphanumeric literals can be null-terminated.

The format for null-terminated alphanumeric literals is:

Format 4: Null-terminated alphanumeric literals

Z"mixed-characters"
Z’mixed-characters’

40 Enterprise COBOL for z/OS, V6.1 Language Reference

 Z" or Z’
The opening delimiter for a null-terminated alphanumeric literal. Both
characters of the opening delimiter (Z" or Z’) must be on the same source
line.
" or ’ The closing delimiter for a null-terminated alphanumeric literal.
If a quotation mark is used in the opening delimiter, a quotation mark
must be used as the closing delimiter. Similarly, if an apostrophe is used in
the opening delimiter, an apostrophe must be used as the closing delimiter.
mixed-characters
Can be any of the following characters:
v Solely single-byte characters
v Mixed single-byte and DBCS characters
v Solely DBCS characters
However, you cannot specify the single-byte character with the value X'00'.
X'00' is the null character automatically appended to the end of the literal.
The content of the literal is otherwise subject to the same rules and
restrictions as an alphanumeric literal with DBCS characters (format 2).

The length of the string of characters in the literal content can be 0 to 159 bytes.
The actual length of the literal includes the terminating null character, and is a
maximum of 160 bytes.

A null-terminated alphanumeric literal has data class and category alphanumeric.

It can be used anywhere an alphanumeric literal can be used except that
null-terminated literals are not supported in ALL literal figurative constants.

The LENGTH intrinsic function, when applied to a null-terminated alphanumeric

literal, returns the number of bytes in the literal prior to but not including the
terminating null. (The LENGTH special register does not support literal operands.)

Numeric literals
A numeric literal is a character-string whose characters are selected from the digits 0
through 9, a sign character (+ or -), and the decimal point.

If the literal contains no decimal point, it is an integer. (In this documentation, the
word integer appearing in a format represents a numeric literal of nonzero value
that contains no sign and no decimal point, except when other rules are included
with the description of the format.) The following rules apply:
v If the ARITH(COMPAT) compiler option is in effect, one through 18 digits are
allowed. If the ARITH(EXTEND) compiler option is in effect, one through 31
digits are allowed.
v Only one sign character is allowed. If included, it must be the leftmost character
of the literal. If the literal is unsigned, it is a positive value.
v Only one decimal point is allowed. If a decimal point is included, it is treated as
an assumed decimal point (that is, as not taking up a character position in the
literal). The decimal point can appear anywhere within the literal except as the
rightmost character.

The value of a numeric literal is the algebraic quantity expressed by the characters
in the literal. The size of a numeric literal is equal to the number of digits specified
by the user.

Chapter 3. Character-strings: COBOL words and literals 41

 Numeric literals can be fixed-point or floating-point numbers.

Numeric literals are in the numeric data class and category. (Data classes and
categories are described under “Classes and categories of data” on page 166.)

Rules for floating-point literal values

The format and rules for floating-point literals are listed below.

Format

►► mantissa E exponent ►◄
+ +
- -

v The sign is optional before the mantissa and the exponent; if you omit the sign,
the compiler assumes a positive number.
v The mantissa can contain between one and 16 digits. A decimal point must be
included in the mantissa.
v The exponent is represented by an E followed by an optional sign and one or
two digits.
v The magnitude of a floating-point literal value must fall between 0.54E-78 and
0.72E+76. For values outside of this range, an E-level diagnostic message is
produced and the value is replaced by either 0 or 0.72E+76, respectively.

DBCS literals
The formats and rules for DBCS literals are listed in this section.

Format for DBCS literals

G"<DBCS-characters>"
G’<DBCS-characters>’
N"<DBCS-characters>"
N’<DBCS-characters>’

G", G’, N", or N’

Opening delimiters.
N" and N’ identify a DBCS literal when the NSYMBOL(DBCS) compiler
option is in effect. They identify a national literal when the
NSYMBOL(NATIONAL) compiler option is in effect, and the rules
specified in “National literals” on page 43 apply.
The opening delimiter must be followed immediately by a shift-out control
character.
For literals with opening delimiter N" or N’, when embedded quotes or
apostrophes are specified as part of DBCS characters in a DBCS literal, a
single embedded DBCS quote or apostrophe is represented by two DBCS
quotes or apostrophes. If a single embedded DBCS quote or apostrophe is
found, an E-level compiler message will be issued and a second embedded
DBCS quote or apostrophe will be assumed.
< Represents the shift-out control character (X'0E')

42 Enterprise COBOL for z/OS, V6.1 Language Reference

 > Represents the shift-in control character (X'0F')
" or ’ The closing delimiter. If a quotation mark is used in the opening delimiter,
a quotation mark must be used as the closing delimiter. Similarly, if an
apostrophe is used in the opening delimiter, an apostrophe must be used
as the closing delimiter.
The closing delimiter must appear immediately after the shift-in control
character.
DBCS-characters
DBCS-characters can be one or more characters in the range of X'00'
through X'FF' for either byte. Any value will be accepted in the content of
the literal, although whether it is a valid value at run time depends on the
CCSID in effect for the CODEPAGE compiler option.
Maximum length
28 characters
Continuation rules
Cannot be continued across lines

Where DBCS literals can be used

DBCS literals can be used in the following places:
v DATA DIVISION
– In the VALUE clause of data description entries that define a data item of
class DBCS.
– In the VALUE OF clause of file description entries.
v PROCEDURE DIVISION
– In a relation condition when the comparand is a DBCS data item, an
elementary data item of class national, a national group item, or an
alphanumeric group item
– As an argument passed BY CONTENT in a CALL statement
– In the DISPLAY and EVALUATE statements
– In the following statements:
- INITIALIZE; for details, see “INITIALIZE statement” on page 358.
- INSPECT; for details, see “INSPECT statement” on page 362.
- MOVE; for details, see “MOVE statement” on page 393.
- STRING; for details, see “STRING statement” on page 462.
- UNSTRING, for details, see “UNSTRING statement” on page 470.
– In figurative constant ALL
– As an argument to the NATIONAL-OF intrinsic function
v Compiler-directing statements COPY, REPLACE, and TITLE

National literals
The national literal formats that Enterprise COBOL provides are basic national
literals and hexadecimal notation for national literals.

For more information about the formats, see “Basic national literals” on page 44
and “Hexadecimal notation for national literals” on page 45.

Chapter 3. Character-strings: COBOL words and literals 43

 Basic national literals
The format and rules for basic national literals are listed in this section.

Format 1: Basic national literals

N"character-data"
N’character-data’

When the NSYMBOL(NATIONAL) compiler option is in effect, the opening

delimiter N" or N’ identifies a national literal. A national literal is of the class and
category national.

When the NSYMBOL(DBCS) compiler option is in effect, the opening delimiter N"
or N’ identifies a DBCS literal, and the rules specified in “DBCS literals” on page
42 apply.
N" or N’
Opening delimiters. The opening delimiter must be coded as single-byte
characters. It cannot be split across lines.
" or ’ The closing delimiter. The closing delimiter must be coded as a single-byte
character. If a quotation mark is used in the opening delimiter, it must be
used as the closing delimiter. Similarly, if an apostrophe is used in the
opening delimiter, it must be used as the closing delimiter.
To include the quotation mark or apostrophe used in the opening delimiter
in the content of the literal, specify a pair of quotation marks or
apostrophes, respectively. Examples:
N’This literal’’s content includes an apostrophe’
N’This literal includes ", which is not used in the opening delimiter’
N"This literal includes "", which is used in the opening delimiter"
character-data
The source text representation of the content of the national literal.
character-data can include any combination of EBCDIC single-byte
characters and double-byte characters encoded in the Coded Character Set
ID (CCSID) specified by the CODEPAGE compiler option.
DBCS characters in the content of the literal must be delimited by shift-out
and shift-in control characters.
Maximum length
The maximum length of a national literal is 80 character positions,
excluding the opening and closing delimiters. If the source content of the
literal contains one or more DBCS characters, the maximum length is
limited by the available space in Area B of a single source line.
The literal must contain at least one character. Each single-byte character in
the literal counts as one character position and each DBCS character in the
literal counts as one character position. Shift-in and shift-out delimiters for
DBCS characters are not counted.
Continuation rules
When the content of the literal includes DBCS characters, the literal cannot
be continued. When the content of the literal does not include DBCS
characters, normal continuation rules apply.

The source text representation of character-data is automatically converted to

UTF-16 for use at run time (for example, when the literal is moved to or compared
with a data item of category national).

44 Enterprise COBOL for z/OS, V6.1 Language Reference

Hexadecimal notation for national literals
The format and rules for the hexadecimal notation format of national literals are
listed in this section.

Format 2: Hexadecimal notation for national literals

NX"hexadecimal-digits"
NX’hexadecimal-digits’

The hexadecimal notation format of national literals is not affected by the

NSYMBOL compiler option.
NX" or NX’
Opening delimiters. The opening delimiter must be represented in
single-byte characters. It must not be split across lines.
" or ’ The closing delimiter. The closing delimiter must be represented as a
single-byte character.
If a quotation mark is used in the opening delimiter, a quotation mark
must be used as the closing delimiter. Similarly, if an apostrophe is used in
the opening delimiter, an apostrophe must be used as the closing delimiter.
hexadecimal-digits
Hexadecimal digits in the range '0' to '9', 'a' - f', and 'A' to 'F', inclusive.
Each group of four hexadecimal digits represents a single national
character and must represent a valid code point in UTF-16. The number of
hexadecimal digits must be a multiple of four.
Maximum length
The length of a national literal in hexadecimal notation must be from four
to 320 hexadecimal digits, excluding the opening and closing delimiters.
The length must be a multiple of four.
Continuation rules
Normal continuation rules apply.

The content of a national literal in hexadecimal notation is stored as national

characters. The resulting content has the same meaning as a basic national literal
that specifies the same national characters.

A national literal in hexadecimal notation has data class and category national and
can be used anywhere that a basic national literal can be used.

Where national literals can be used

National literals can be used in multiple ways.

National literals can be used:

v In a VALUE clause associated with a data item of class national or a VALUE
clause associated with a condition-name for a conditional variable that is defined
with usage NATIONAL
v In figurative constant ALL
v In a relation condition
v In the WHEN phrase of a format-2 SEARCH statement (binary search)
v In the ALL, LEADING, or FIRST phrase of an INSPECT statement
v In the BEFORE or AFTER phrase of an INSPECT statement
v In the DELIMITED BY phrase of a STRING statement

Chapter 3. Character-strings: COBOL words and literals 45

 v In the DELIMITED BY phrase of an UNSTRING statement
v As the method-name in a METHOD-ID paragraph, an END METHOD marker,
and an INVOKE statement
v As an argument passed BY CONTENT in the CALL statement
v As an argument passed BY VALUE in an INVOKE or CALL statement
v In the DISPLAY and EVALUATE statements
v As a sending item in the following procedural statements:
– INITIALIZE
– INSPECT
– MOVE
– STRING
– UNSTRING
v In the argument list to the following intrinsic functions:
DISPLAY-OF, LENGTH, LOWER-CASE, MAX, MIN, ORD-MAX, ORD-MIN,
REVERSE, UPPER-CASE, USUPPLEMENTARY and UVALID

Note: DBCS literals can't be used in the USUPPLEMENTARY and UVALID

functions.
v In the compiler-directing statements COPY, REPLACE, and TITLE

A national literal can be used only as specified in the detailed rules in this
document.

PICTURE character-strings
A PICTURE character-string is composed of the currency symbol and certain
combinations of characters in the COBOL character set. PICTURE character-strings
are delimited only by the separator space, separator comma, separator semicolon,
or separator period.

A chart of PICTURE clause symbols appears in Table 12 on page 204.

Comments
A comment is a character-string that can contain any combination of characters from
the character set of the computer.

It has no effect on the execution of the program. There are three forms of
comments:
Comment entry (IDENTIFICATION DIVISION)
This form is described under “Optional paragraphs” on page 109.
Comment line (any division)
This form is described under “Comment lines” on page 60.
Inline comments (any division)
An inline comment is identified by a floating comment indicator (*>)
preceded by one or more character-strings in the program-text area, and
can be written on any line of a compilation group. All characters that
follow the floating comment indicator up to the end of area B are comment
text.

46 Enterprise COBOL for z/OS, V6.1 Language Reference

Character-strings that form comments can contain DBCS characters or a
combination of DBCS and single-byte EBCDIC characters.

Multiple comment lines that contain DBCS strings are allowed. The embedding of
DBCS characters in a comment line must be done on a line-by-line basis. Words
containing those characters cannot be continued to a following line. No syntax
checking for valid strings is provided in comment lines.

Chapter 3. Character-strings: COBOL words and literals 47

48 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 4. Separators
A separator is a character or a string of two or more contiguous characters that
delimits character-strings.

The separators are shown in the following table.

Table 4. Separators
Separator Meaning
1
b Space
1
,b Comma
1
.b Period
1
;b Semicolon
( Left parenthesis
) Right parenthesis
: Colon
1
"b Quotation mark
1
’b Apostrophe
X" Opening delimiter for a hexadecimal format alphanumeric literal
X’ Opening delimiter for a hexadecimal format alphanumeric literal
Z" Opening delimiter for a null-terminated alphanumeric literal
Z’ Opening delimiter for a null-terminated alphanumeric literal
N" Opening delimiter for a national literal2
N’ Opening delimiter for a national literal2
NX" Opening delimiter for a hexadecimal format national literal
NX’ Opening delimiter for a hexadecimal format national literal
G" Opening delimiter for a DBCS literal
G’ Opening delimiter for a DBCS literal
== Pseudo-text delimiter

1. b represents a blank.
2. N" and N’ are the opening delimiter for a DBCS literal when the NSYMBOL(DBCS)
compiler option is in effect.

Rules for separators

A separator is a string of one or more punctuation characters.

In the following description, {} (curly braces) enclose each separator, and b

represents a space. Anywhere a space is used as a separator or as part of a
separator, more than one space can be used.
Space {b}
A space can immediately precede or follow any separator except:
v The opening pseudo-text delimiter, where the preceding space is
required.

© Copyright IBM Corp. 1991, 2017 49

 v Within quotation marks. Spaces between quotation marks are considered
part of the alphanumeric literal; they are not considered separators.
Period {.b}, Comma {,b}, Semicolon {;b}
A separator comma is composed of a comma followed by a space. A
separator period is composed of a period followed by a space. A separator
semicolon is composed of a semicolon followed by a space.
The separator period must be used only to indicate the end of a sentence,
or as shown in formats. The separator comma and separator semicolon can
be used anywhere the separator space is used.
v In the IDENTIFICATION DIVISION, each paragraph must end with a
separator period.
v In the ENVIRONMENT DIVISION, the SOURCE-COMPUTER,
OBJECT-COMPUTER, SPECIAL-NAMES, and I-O-CONTROL
paragraphs must each end with a separator period. In the
FILE-CONTROL paragraph, each file-control entry must end with a
separator period.
v In the DATA DIVISION, file (FD), sort/merge file (SD), and data
description entries must each end with a separator period.
v In the PROCEDURE DIVISION, separator commas or separator
semicolons can separate statements within a sentence and operands
within a statement. Each sentence and each procedure must end with a
separator period.
Parentheses { ( } ... { ) }
Except in pseudo-text, parentheses can appear only in balanced pairs of left
and right parentheses. They delimit subscripts, a list of function
arguments, reference-modifiers, arithmetic expressions, or conditions.
Colon { : }
The colon is a separator and is required when shown in general formats.
Quotation marks {"} ... {"}
An opening quotation mark must be immediately preceded by a space or a
left parenthesis. A closing quotation mark must be immediately followed
by a separator space, comma, semicolon, period, right parenthesis, or
pseudo-text delimiter. Quotation marks must appear as balanced pairs.
They delimit alphanumeric literals, except when the literal is continued
(see “Continuation lines” on page 58).
Apostrophes {’} ... {’}
An opening apostrophe must be immediately preceded by a space or a left
parenthesis. A closing apostrophe must be immediately followed by a
separator space, comma, semicolon, period, right parenthesis, or
pseudo-text delimiter. Apostrophes must appear as balanced pairs. They
delimit alphanumeric literals, except when the literal is continued (see
“Continuation lines” on page 58).
Null-terminated literal delimiters {Z"} ... {"}, {Z’} ... {’}
The opening delimiter must be immediately preceded by a space or a left
parenthesis. The closing delimiter must be immediately followed by a
separator space, comma, semicolon, period, right parenthesis, or
pseudo-text delimiter.
DBCS literal delimiters {G"} ... {"}, {G’} ... {’}, {N"} ... {"}, {N’} ... {’}
The opening delimiter must be immediately preceded by a space or a left
parenthesis. The closing delimiter must be immediately followed by a
separator space, comma, semicolon, period, right parenthesis, or

50 Enterprise COBOL for z/OS, V6.1 Language Reference

 pseudo-text delimiter. N" and N’ are DBCS literal delimiters when the
NSYMBOL(DBCS) compiler option is in effect.
National literal delimiters {N"} ... {"}, {N’} ... {’}, {NX"} ... {"}, {NX’} ... {’}
The opening delimiter must be immediately preceded by a space or a left
parenthesis. The closing delimiter must be immediately followed by a
separator space, comma, semicolon, period, right parenthesis, or
pseudo-text delimiter. N" and N’ are DBCS literal delimiters when the
NSYMBOL(DBCS) compiler option is in effect.
Pseudo-text delimiters {b==} ... {==b}
An opening pseudo-text delimiter must be immediately preceded by a
space. A closing pseudo-text delimiter must be immediately followed by a
separator space, comma, semicolon, or period. Pseudo-text delimiters must
appear as balanced pairs. They delimit pseudo-text. (See “COPY statement”
on page 562.)

Any punctuation character included in a PICTURE character-string, a comment

character-string, or an alphanumeric literal is not considered a punctuation
character, but is part of the character-string or literal.

Chapter 4. Separators 51
52 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 5. Sections and paragraphs
Sections and paragraphs define a program. Sections and paragraphs are
subdivided into sentences, statements, and entries.

Sentences are subdivided into statements, and statements are subdivided into
phrases. Entries are subdivided into clauses.

For details, see:

v “Sentences, statements, and entries”
v “Statements” on page 54
v “Phrases” on page 54
v “Clauses” on page 54

For more information about sections, paragraphs, and statements, see “Procedures”
on page 260.

Sentences, statements, and entries

Unless the associated rules explicitly state otherwise, each required clause or
statement must be written in the sequence shown in its format. If optional clauses
or statements are used, they must be written in the sequence shown in their
formats. These rules are true even for clauses and statements treated as comments.

The syntactical hierarchy follows this form:

v IDENTIFICATION DIVISION
– Paragraphs
- Entries
v Clauses
v ENVIRONMENT DIVISION
– Sections
- Paragraphs
v Entries
– Clauses
- Phrases
v DATA DIVISION
– Sections
- Entries
v Clauses
– Phrases
v PROCEDURE DIVISION
– Sections
- Paragraphs
v Sentences
– Statements
- Phrases

© Copyright IBM Corp. 1991, 2017 53

 Entries
An entry is a series of clauses that ends with a separator period. Entries are
constructed in the identification, environment, and data divisions.

Clauses
A clause is an ordered set of consecutive COBOL character-strings that specifies an
attribute of an entry. Clauses are constructed in the identification, environment,
and data divisions.

Sentences
A sentence is a sequence of one or more statements that ends with a separator
period. Sentences are constructed in the PROCEDURE DIVISION.

Statements
A statement specifies an action to be taken by the program. Statements are
constructed in the PROCEDURE DIVISION.

For descriptions of the different types of statements, see:

v “Imperative statements” on page 284
v “Conditional statements” on page 286
v Chapter 7, “Scope of names,” on page 63
v Chapter 22, “Compiler-directing statements,” on page 559

Phrases
Each clause or statement in a program can be subdivided into smaller units called
phrases.

54 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 6. Reference format
COBOL source text must be written in COBOL reference format.

Reference format consists of the following areas in a 72-character line.

Sequence number area
Columns 1 through 6
Indicator area
Column 7
Area A
Columns 8 through 11
Area B
Columns 12 through 72

This figure illustrates reference format for a COBOL source line.

1 2 3 4 5 6 7 8 9 10 11 12 13 ... 71 72

Sequence Number Area Area A Area B

Indicator Area

The following topics provide details about these areas:

v “Sequence number area”
v “Indicator area”
v “Area A” on page 56
v “Area B” on page 58
v “Area A or Area B” on page 60

Sequence number area

The sequence number area can be used to label a source statement line. The
content of this area can consist of any character in the character set of the
computer.

Indicator area
Use the indicator area to specify the continuation of words or alphanumeric literals
from the previous line onto the current line, the treatment of text as
documentation, and debugging lines.

See “Continuation lines” on page 58, “Comment lines” on page 60, and
“Debugging lines” on page 61.

The indicator area can be used for source listing formatting. A slash (/) placed in
the indicator column causes the compiler to start a new page for the source listing,
and the corresponding source record to be treated as a comment. The effect can be
dependent on the LINECOUNT compiler option. For information about the
LINECOUNT compiler option, see LINECOUNT in the Enterprise COBOL
Programming Guide.

© Copyright IBM Corp. 1991, 2017 55

Area A
Certain items must begin in Area A.

These items are:

v Division headers
v “Section headers”
v Paragraph headers or paragraph names
v Level indicators or level-numbers (01 and 77)
v DECLARATIVES and END DECLARATIVES
v End program, end class, and end method markers

Division headers
A division header is a combination of words, followed by a separator period to
indicate the beginning of a division.

See the following division headers:

v IDENTIFICATION DIVISION.
v ENVIRONMENT DIVISION.
v DATA DIVISION.
v PROCEDURE DIVISION.

A division header (except when a USING phrase is specified with a PROCEDURE

DIVISION header) must be immediately followed by a separator period. Except for
the USING phrase, no text can appear on the same line.

Section headers
In the environment and procedure divisions, a section header indicates the
beginning of a series of paragraphs.

For example:
INPUT-OUTPUT SECTION.

In the DATA DIVISION, a section header indicates the beginning of an entry; for
example:
FILE SECTION.

LINKAGE SECTION.

LOCAL-STORAGE SECTION.

WORKING-STORAGE SECTION.

A section header must be immediately followed by a separator period.

Paragraph headers or paragraph names

A paragraph header or paragraph name indicates the beginning of a paragraph.

In the ENVIRONMENT DIVISION, a paragraph consists of a paragraph header

followed by one or more entries. For example:
OBJECT-COMPUTER. computer-name.

56 Enterprise COBOL for z/OS, V6.1 Language Reference

 In the PROCEDURE DIVISION, a paragraph consists of a paragraph-name
followed by one or more sentences.

Level indicators (FD and SD) or level-numbers (01 and 77)

A level indicator can be either FD or SD.

A level indicator must begin in Area A and be followed by a space. (See “FILE
SECTION” on page 178.) A level-number that must begin in Area A is a one- or
two-digit integer with a value of 01 or 77. It must be followed by a space or
separator period.

DECLARATIVES and END DECLARATIVES

DECLARATIVES and END DECLARATIVES are keywords that begin and end the
declaratives part of the source unit.

In the PROCEDURE DIVISION, each of the keywords DECLARATIVES and END

DECLARATIVES must begin in Area A and be followed immediately by a
separator period; no other text can appear on the same line. After the keywords
END DECLARATIVES, no text can appear before the following section header. (See
“Declaratives” on page 259.)

End program, end class, and end method markers

The end markers are a combination of words followed by a separator period that
indicates the end of a COBOL program, method, class, factory, or object definition.

For example:
END PROGRAM program-name.
END CLASS class-name.
END METHOD "method-name".
END OBJECT.
END FACTORY.
For programs
program-name must be identical to the program-name of the corresponding
PROGRAM-ID paragraph. Every COBOL program, except an outermost
program that contains no nested programs and is not followed by another
batch program, must end with an END PROGRAM marker.
For classes
class-name must be identical to the class-name in the corresponding
CLASS-ID paragraph.
For methods
method-name must be identical to the method-name in the corresponding
METHOD-ID paragraph.
For object paragraphs
There is no name in an object paragraph header or in its end marker. The
syntax is simply END OBJECT.
For factory paragraphs
There is no name in a factory paragraph header or in its end marker. The
syntax is simply END FACTORY.

Chapter 6. Reference format 57

Area B
Certain items must begin in Area B.

These items are:

v Entries, sentences, statements, and clauses
v Continuation lines

Entries, sentences, statements, clauses

The first entry, sentence, statement, or clause begins on either the same line as the
header or paragraph-name that it follows, or in Area B of the next nonblank line
that is not a comment line. Successive sentences or entries either begin in Area B of
the same line as the preceding sentence or entry, or in Area B of the next nonblank
line that is not a comment line.

Within an entry or sentence, successive lines in Area B can have the same format
or can be indented to clarify program logic. The output listing is indented only if
the input statements are indented. Indentation does not affect the meaning of the
program. The programmer can choose the amount of indentation, subject only to
the restrictions on the width of Area B. See also Chapter 5, “Sections and
paragraphs,” on page 53.

Continuation lines
Any sentence, entry, clause, or phrase that requires more than one line can be
continued in Area B of the next line that is neither a comment line nor a blank line.

The line being continued is a continued line; the succeeding lines are continuation
lines. Area A of a continuation line must be blank.

If there is no hyphen (-) in the indicator area (column 7) of a line, the last character
of the preceding line is assumed to be followed by a space.

The following items cannot be continued:

v DBCS user-defined words
v DBCS literals
v Alphanumeric literals containing DBCS characters
v National literals containing DBCS characters

However, alphanumeric literals and national literals in hexadecimal notation can be

continued regardless of the kind of characters expressed in hexadecimal notation.

All characters that make up an opening literal delimiter must be on the same line.
For example, Z", G", N", NX", or X".

Both characters that make up the pseudo-text delimiter separator, ==, the floating
comment indicator, *>, or the compiler directive indicator, >>, must be on the same
line.

If there is a hyphen in the indicator area of a line, the first nonblank character of
the continuation line immediately follows the last nonblank character of the
continued line without an intervening space.

58 Enterprise COBOL for z/OS, V6.1 Language Reference

Continuation of alphanumeric and national literals

Alphanumeric and national literals can be continued only when there are no DBCS
characters in the content of the literal.

The following rules apply to alphanumeric and national literals that do not contain
DBCS characters:
v If the continued line contains an alphanumeric or national literal without a
closing quotation mark, all spaces at the end of the continued line (through
column 72) are considered to be part of the literal. The continuation line must
contain a hyphen in the indicator area, and the first nonblank character must be
a quotation mark. The continuation of the literal begins with the character
immediately following the quotation mark.
v If an alphanumeric or national literal that is to be continued on the next line has
as its last character a quotation mark in column 72, the continuation line must
start with two consecutive quotation marks. This will result in a single quotation
mark as part of the value of the literal.
If the last character on the continued line of an alphanumeric or national literal
is a single quotation mark in Area B, the continuation line can start with a single
quotation mark. This will result in two consecutive literals instead of one
continued literal.

The rules are the same when an apostrophe is used instead of a quotation mark in
delimiters.

If you want to continue a literal such that the continued lines and the continuation
lines are part of one literal:
v Code a hyphen in the indicator area of each continuation line.
v Code the literal value using all columns of each continued line, up to and
including column 72. (Do not terminate the continued lines with a single
quotation mark followed by a space.)
v Code a quotation mark before the first character of the literal on each
continuation line.
v Terminate the last continuation line with a single quotation mark followed by a
space.

In the following examples, the number and size of literals created are indicated
below the example:
|...+.*..1....+....2....+....3....+....4....+....5....+....6....+....7..
000001 "AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDDEEEEEEEEEE
- "GGGGGGGGGGHHHHHHHHHHIIIIIIIIIIJJJJJJJJJJKKKKKKKKKK
- "LLLLLLLLLLMMMMMMMMMM"
v Literal 000001 is interpreted as one alphanumeric literal that is 120 bytes long.
Each character between the starting quotation mark and up to and including
column 72 of continued lines is counted as part of the literal.
|...+.*..1....+....2....+....3....+....4....+....5....+....6....+....7..
000003 N"AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDDEEEEEEEEEE
- "GGGGGGGGGG"
v Literal 000003 is interpreted as one national literal that is 60 national character
positions in length (120 bytes). Each character between the starting quotation
mark and the ending quotation mark on the continued line is counted as part of
the literal. Although single-byte characters are entered, the value of the literals is
stored as national characters.

Chapter 6. Reference format 59

 |...+.*..1....+....2....+....3....+....4....+....5....+....6....+....7..
000005 "AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDDEEEEEEEEEE
- "GGGGGGGGGGHHHHHHHHHHIIIIIIIIIIJJJJJJJJJJKKKKKKKKKK
- "LLLLLLLLLLMMMMMMMMMM"
v Literal 000005 is interpreted as one literal that is 140 bytes long. The blanks at
the end of each continued line are counted as part of the literal because the
continued lines do not end with a quotation mark.
|...+.*..1....+....2....+....3....+....4....+....5....+....6....+....7..
000010 "AAAAAAAAAABBBBBBBBBBCCCCCCCCCCDDDDDDDDDDEEEEEEEEEE"
- "GGGGGGGGGGHHHHHHHHHHIIIIIIIIIIJJJJJJJJJJKKKKKKKKKK"
- "LLLLLLLLLLMMMMMMMMMM"
v Literal 000010 is interpreted as three separate literals that have lengths of 50, 50,
and 20, respectively. The quotation mark with the following space terminates the
continued line. Only the characters within the quotation marks are counted as
part of the literals. Literal 000010 is not valid as a VALUE clause literal for
non-level-88 data items.

To code a continued literal where the length of each continued part of the literal is
less than the length of Area B, adjust the starting column such that the last
character of the continued part is in column 72.

Area A or Area B
Certain items can begin in either Area A or Area B.

These items are:

v Level-numbers
v Comment lines
v Floating comment indicators (*>)
v Compiler-directing statements
v Debugging lines
v Pseudo-text
v Blank lines

Level-numbers
A level-number that can begin in Area A or B is a one- or two-digit integer with a
value of 02 through 49, 66, or 88.

A level-number that must begin in Area A is a one- or two-digit integer with a

value of 01 or 77. A level-number must be followed by a space or a separator
period. For more information, see “Level-numbers” on page 190.

Comment lines
A comment line is any line with an asterisk (*) or slash (/) in the indicator area
(column 7) of the line, or with a floating comment indicator (*>) as the first
character-string in the program text area (Area A plus Area B).

The comment can be written anywhere in the program text area of that line, and
can consist of any combination of characters from the character set of the
computer.

Comment lines can be placed anywhere in a program, method, or class definition.

Comment lines placed before the IDENTIFICATION DIVISION header must follow
any control cards (for example, PROCESS or CBL).
60 Enterprise COBOL for z/OS, V6.1 Language Reference
 Important: Comments intermixed with control cards could nullify some of the
control cards and cause them to be diagnosed as errors.

Multiple comment lines are allowed. Each must begin with an asterisk (*) or a
slash (/) in the indicator area, or with a floating comment indicator (*>).

For more information about floating comment indicators, see “Floating comment
indicators (*>).”

An asterisk (*) comment line is printed on the next available line in the output
listing. The effect can be dependent on the LINECOUNT compiler option. For
information about the LINECOUNT compiler option, see LINECOUNT in the
Enterprise COBOL Programming Guide. A slash (/) comment line is printed on the
first line of the next page, and the current page of the output listing is ejected.

The compiler treats a comment line as documentation, and does not check it
syntactically.

Floating comment indicators (*>)

In addition to the fixed indicators that can only be specified in the indicator area of
the source reference format, a floating comment indicator (*>) can be specified
anywhere in the program-text area to indicate a comment line or an inline
comment.

A floating comment indicator indicates a comment line if it is the first character

string in the program-text area (Area A plus Area B), or indicates an inline
comment if it is after one or more character strings in the program-text area.

These are the rules for floating comment indicators:

v Both characters (* and >) that form the multiple-character floating indicator must
be contiguous and on the same line.
v The floating comment indicator for an inline comment must be preceded by a
separator space, and can be specified wherever a separator space can be
specified.
v All characters following the floating comment indicator up to the end of Area B
are comment text.

Compiler-directing statements
Most compiler-directing statements, including COPY and REPLACE, can start in
either Area A or Area B.

BASIS, CBL (PROCESS), *CBL (*CONTROL), DELETE, EJECT, INSERT, SKIP1,

SKIP2, SKIP3, and TITLE statements can also start in Area A or Area B.

Compiler directives
Compiler directives must start in Area B.

Currently, the only compiler directive is CALLINTERFACE. For more information,

see Chapter 23, “Compiler directives,” on page 587.

Debugging lines
A debugging line is any line with a D (or d) in the indicator area of the line.

Chapter 6. Reference format 61

 Debugging lines can be written in the ENVIRONMENT DIVISION (after the
OBJECT-COMPUTER paragraph), the DATA DIVISION, and the PROCEDURE
DIVISION. If a debugging line contains only spaces in Area A and Area B, it is
considered a blank line.

See "WITH DEBUGGING MODE" in “SOURCE-COMPUTER paragraph” on page

114.

Pseudo-text
The character-strings and separators that comprise pseudo-text can start in either
Area A or Area B.

If, however, there is a hyphen in the indicator area (column 7) of a line that follows
the opening pseudo-text delimiter, Area A of the line must be blank, and the rules
for continuation lines apply to the formation of text words. See “Continuation
lines” on page 58 for details.

Blank lines
A blank line contains nothing but spaces in column 7 through column 72. A blank
line can be anywhere in a program.

62 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 7. Scope of names
A user-defined word names a data resource or a COBOL programming element.
Examples of named data resources are a file, a data item, or a record. Examples of
named programming elements are a program, a paragraph, a method, or a class
definition.

The sections below define the types of names in COBOL and explain where the
names can be referenced:
v “Types of names”
v “External and internal resources” on page 65
v “Resolution of names” on page 66

Types of names
In addition to identifying a resource, a name can have global or local attributes.
Some names are always global, some names are always local, and some names are
either local or global depending on specifications in the program in which the
names are defined.
For programs
A global name can be used to refer to the resource with which it is
associated both:
v From within the program in which the global name is defined
v From within any other program that is contained in the program that
defines the global name
Use the GLOBAL clause in the data description entry to indicate that a
name is global. For more information about using the GLOBAL clause, see
“GLOBAL clause” on page 179.
A local name can be used only to refer to the resource with which it is
associated from within the program in which the local name is defined.
By default, if a data-name, a file-name, a record-name, or a condition-name
definition in a data description entry does not include the GLOBAL clause,
the name is local.
For methods
All names defined in methods are implicitly local.
For classes
Names defined in a class definition are global to all the methods contained
in that class definition.
For object paragraphs
Names defined in the DATA DIVISION of an object paragraph are global
to the methods contained in that object paragraph.
For factory paragraphs
Names defined in the DATA DIVISION of a factory paragraph are global
to the methods contained in that factory paragraph.

Restriction: Specific rules sometimes prohibit specifying the GLOBAL clause for
certain data description, file description, or record description entries.

© Copyright IBM Corp. 1991, 2017 63

 The following list indicates the names that you can use and whether the name can
be local or global:
data-name
data-name assigns a name to a data item.
A data-name is global if the GLOBAL clause is specified either in the data
description entry that defines the data-name or in another entry to which
that data description entry is subordinate.
file-name
file-name assigns a name to a file connector.
A file-name is global if the GLOBAL clause is specified in the file
description entry for that file-name.
record-name
record-name assigns a name to a record.
A record-name is global if the GLOBAL clause is specified in the record
description that defines the record-name, or in the case of record
description entries in the FILE SECTION, if the GLOBAL clause is
specified in the file description entry for the file name associated with the
record description entry.
condition-name
condition-name associates a value with a conditional variable.
A condition-name that is defined in a data description entry is global if
that entry is subordinate to another entry that specifies the GLOBAL
clause.
A condition-name that is defined within the configuration section is always
global.
program-name
program-name assigns a name to an external or internal (nested) program.
For more information, see “Conventions for program-names” on page 90.
A program-name is neither local nor global. For more information, see
“Conventions for program-names” on page 90.
method-name
method-name assigns a name to a method. method-name must be specified as
the content of an alphanumeric literal or a national literal.
section-name
section-name assigns a name to a section in the PROCEDURE DIVISION.
A section-name is always local.
paragraph-name
paragraph-name assigns a name to a paragraph in the PROCEDURE
DIVISION.
A paragraph-name is always local.
basis-name
basis-name specifies the name of source text that is be included by the
compiler into the source unit. For details, see “BASIS statement” on page
559.
library-name
library-name specifies the COBOL library that the compiler uses for
including COPY text. For details, see “COPY statement” on page 562.

64 Enterprise COBOL for z/OS, V6.1 Language Reference

 text-name
text-name specifies the name of COPY text to be included by the compiler
into the source unit. For details, see “COPY statement” on page 562.
alphabet-name
alphabet-name assigns a name to a specific character set or collating
sequence, or both, in the SPECIAL-NAMES paragraph of the
ENVIRONMENT DIVISION.
An alphabet-name is always global.
class-name (of data)
class-name assigns a name to the proposition in the SPECIAL-NAMES
paragraph of the ENVIRONMENT DIVISION for which a truth value can
be defined.
A class-name is always global.
class-name (object-oriented)
class-name assigns a name to an object-oriented class or subclass.
mnemonic-name
mnemonic-name assigns a user-defined word to an implementer-name.
A mnemonic-name is always global.
symbolic-character
symbolic-character specifies a user-defined figurative constant.
A symbolic-character is always global.
index-name
index-name assigns a name to an index associated with a specific table.
If a data item that possesses the global attribute includes a table accessed
with an index, that index also possesses the global attribute. In addition,
the scope of that index-name is identical to the scope of the data-name that
includes the table.
xml-schema-name
xml-schema-name assigns a name to the system identifier of a file containing
an XML schema.
An xml-schema-name is always global.

External and internal resources

The storage associated with a data item or a file connector can be external or
internal to the program or method in which the resource is declared.

A data item or file connector is external if the storage associated with that resource
is associated with the run unit rather than with any particular program or method
within the run unit. An external resource can be referenced by any program or
method in the run unit that describes the resource. References to an external
resource from different programs or methods using separate descriptions of the
resource are always to the same resource. In a run unit, there is only one
representation of an external resource.

A resource is internal if the storage associated with that resource is associated only
with the program or method that describes the resource.

External and internal resources can have either global or local names.

Chapter 7. Scope of names 65

 A data record described in the WORKING-STORAGE SECTION is given the
external attribute by the presence of the EXTERNAL clause in its data description
entry. Any data item described by a data description entry subordinate to an entry
that describes an external record also attains the external attribute. If a record or
data item does not have the external attribute, it is part of the internal data of the
program or method in which it is described.

Two programs or methods in a run unit can reference the same file connector in
the following circumstances:
v An external file connector can be referenced from any program or method that
describes that file connector.
v If a program is contained within another program, both programs can refer to a
global file connector by referring to an associated global file-name either in the
containing program or in any program that directly or indirectly contains the
containing program.

Two programs or methods in a run unit can reference common data in the
following circumstances:
v The data content of an external data record can be referenced from any program
or method provided that program or method has described that data record.
v If a program is contained within another program, both programs can refer to
data that possesses the global attribute either in the program or in any program
that directly or indirectly contains the containing program.

The data records described as subordinate to a file description entry that does not
contain the EXTERNAL clause or to a sort-merge file description entry, as well as
any data items described subordinate to the data description entries for such
records, are always internal to the program or method that describes the file-name.
If the EXTERNAL clause is included in the file description entry, the data records
and the data items attain the external attribute.

Resolution of names
The rules for resolution of names depend on whether the names are specified in a
program or in a class definition.

Names within programs

When a program, program B, is directly contained within another program,

program A, both programs can define a condition-name, a data-name, a file-name,
or a record-name using the same user-defined word. When such a duplicated name
is referenced in program B, the following steps determine the referenced resource
(these rules also apply to classes and contained methods):
1. The referenced resource is identified from the set of all names that are defined
in program B and all global names defined in program A and in any programs
that directly or indirectly contain program A. The normal rules for qualification
and any other rules for uniqueness of reference are applied to this set of names
until one or more resources is identified.
2. If only one resource is identified, it is the referenced resource.
3. If more than one resource is identified, no more than one resource can have a
name local to program B. If zero or one of the resources has a name local to
program B, the following rules apply:
v If the name is declared in program B, the resource in program B is the
referenced resource.

66 Enterprise COBOL for z/OS, V6.1 Language Reference

 v If the name is not declared in program B, the referenced resource is:
– The resource in program A if the name is declared in program A
– The resource in the containing program if the name is declared in the
program that contains program A
This rule is applied to further containing programs until a valid resource is
found.

Names within a class definition

Within a class definition, resources can be defined within the following units:
v The factory data division
v The object data division
v A method data division

If a resource is defined with a given name in the DATA DIVISION of an object

definition, and there is no resource defined with the same name in an instance
method of that object definition, a reference to that name from an instance method
is a reference to the resource in the object DATA DIVISION.

If a resource is defined with a given name in the DATA DIVISION of a factory

definition, and there is no resource defined with the same name in a factory
method of that factory definition, a reference to that name from a factory method
is a reference to the resource in the factory data division.

If a resource is defined within a method, any reference within the method to that
resource name is always a reference to the resource in the method.

The normal rules for qualification and uniqueness of reference apply when the
same name is associated with more than one resource within a given method data
division, object data division, or factory data division.

Chapter 7. Scope of names 67

68 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 8. Referencing data names, copy libraries, and
PROCEDURE DIVISION names
References can be made to external and internal resources. References to data and
procedures can be either explicit or implicit.

For more information about rules for qualification, and for explicit and implicit
data references, see the following topics:
v “Uniqueness of reference”
v “Data attribute specification” on page 82

Uniqueness of reference
Every user-defined name in a COBOL program is assigned by the user to name a
resource for solving a data processing problem. To use a resource, a statement in a
COBOL program must contain a reference that uniquely identifies that resource.

To ensure uniqueness of reference, a user-defined name can be qualified. A

subscript is required for unique reference to a table element, except as specified in
“Subscripting” on page 75. A data-name or function-name, any subscripts, and the
specified reference-modifier uniquely reference a data item defined by reference
modification.

When the same name has been assigned in separate programs to two or more
occurrences of a resource of a given type, and when qualification by itself does not
allow the references in one of those programs to differentiate between the
identically named resources, then certain conventions that limit the scope of names
apply. The conventions ensure that the resource identified is that described in the
program containing the reference. For more information about resolving
program-names, see “Resolution of names” on page 66.

Unless otherwise specified by the rules for a statement, any subscripts and
reference modification are evaluated only once as the first step in executing that
statement.

Qualification
A name that exists within a hierarchy of names can be made unique by specifying
one or more higher-level names in the hierarchy. The higher-level names are called
qualifiers, and the process by which such names are made unique is called
qualification.

Qualification is specified by placing one or more phrases after a user-specified

name, with each phrase made up of the word IN or OF followed by a qualifier. (IN
and OF are logically equivalent.)

If there is only one 01 level with a given name, that name can be referenced even if
it is not unique when the QUALIFY(EXTEND) option is in effect.

© Copyright IBM Corp. 1991, 2017 69

 You must specify enough qualification to make the name unique; however, it is not
always necessary to specify all the levels of the hierarchy. For example, if there is
more than one file whose records contain the field EMPLOYEE-NO, but only one of the
files has a record named MASTER-RECORD:
v EMPLOYEE-NO OF MASTER-RECORD sufficiently qualifies EMPLOYEE-NO.
v EMPLOYEE-NO OF MASTER-RECORD OF MASTER-FILE is valid but unnecessary.

Qualification rules

The rules for qualifying a name are:

v A name can be qualified even though it does not need qualification except in a
REDEFINES clause, in which case it must not be qualified.
v Each qualifier must be of a higher level than the name it qualifies and must be
within the same hierarchy.
v If there is more than one combination of qualifiers that ensures uniqueness, any
of those combinations can be used.
v If compiler option QUALIFY(EXTEND) is in effect, and if there is only one fully
qualified name that matches your combination of qualifiers, that reference will
be considered unique, even if the set of qualifiers also matches a partial
qualification for a different data item. Fully qualified means every qualifier is
specified.

| RELATED REFERENCES
| QUALIFY (Enterprise COBOL Programming Guide)

| Identical names
When programs are directly or indirectly contained within other programs, each
program can use identical user-defined words to name resources.

A program references the resources that program describes rather than the
same-named resources described in another program, even if the names are
different types of user-defined words.

These same rules apply to classes and their contained methods.

References to COPY libraries

If library-name-1 is not specified, SYSLIB is assumed as the library name.

Format

►► text-name-1 ►◄
IN library-name-1
OF

For rules on referencing COPY libraries, see “COPY statement” on page 562.

70 Enterprise COBOL for z/OS, V6.1 Language Reference

References to PROCEDURE DIVISION names
PROCEDURE DIVISION names that are explicitly referenced in a program must be
unique within a section.

Format 1

►► paragraph-name-1 ►◄
IN section-name-1
OF

Format 2

►► section-name-1 ►◄

A section-name is the highest and only qualifier available for a paragraph-name

and must be unique if referenced. (Section-names are described under
“Procedures” on page 260.)

If explicitly referenced, a paragraph-name must not be duplicated within a section.

When a paragraph-name is qualified by a section-name, the word SECTION must
not appear. A paragraph-name need not be qualified when referred to within the
section in which it appears. A paragraph-name or section-name that appears in a
program cannot be referenced from any other program.

References to DATA DIVISION names

This section discusses the following types of references.
v “Simple data reference”
v “Identifiers” on page 72

Simple data reference

The most basic method of referencing data items in a COBOL program is simple
data reference, which is data-name-1 without qualification, subscripting, or reference
modification. Simple data reference is used to reference a single elementary or
group item.

Format

►► data-name-1 ►◄

Chapter 8. Referencing data names, copy libraries, and PROCEDURE DIVISION names 71
 data-name-1
Can be any data description entry.
data-name-1 must be unique in a program.

Identifiers

When used in a syntax diagram in this information, the term identifier refers to a
valid combination of a data-name or function-identifier with its qualifiers,
subscripts, and reference-modifiers as required for uniqueness of reference.

Rules for identifiers associated with a format can however specifically prohibit
qualification, subscripting, or reference modification.

The term data-name refers to a name that must not be qualified, subscripted, or
reference modified unless specifically permitted by the rules for the format.
v For a description of qualification, see “Qualification” on page 69.
v For a description of subscripting, see “Subscripting” on page 75.
v For a description of reference modification, see “Reference modification” on
page 79.

Format 1

►► data-name-1 ▼ ►
IN data-name-2 IN file-name-1
OF OF

► ►

( ▼ subscript )

► ►◄
( leftmost-character-position : )
length

data-name-1 , data-name-2
Can be a record-name.
file-name-1
Must be identified by an FD or SD entry in the DATA DIVISION.
file-name-1 must be unique within this program.

72 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 2

►► condition-name-1 ▼ ►
data-name-1 IN data-name-2
OF

► ►◄
IN file-name-1
OF

Format 3

►► LINAGE-COUNTER ►◄
IN file-name-2
OF

data-name-1 , data-name-2
Can be a record-name.
condition-name-1
Can be referenced by statements and entries either in the program that
contains the configuration section or in a program contained within that
program.
file-name-1
Must be identified by an FD or SD entry in the DATA DIVISION.
Must be unique within this program.
LINAGE-COUNTER
Must be qualified each time it is referenced if more than one file
description entry that contains a LINAGE clause has been specified in the
source unit.
file-name-2
Must be identified by the FD or SD entry in the DATA DIVISION.
file-name-2 must be unique within this program.

Duplication of data-names must not occur in those places where the data-names
cannot be made unique by qualification.

In the same program, the data-name specified as the subject of the entry whose
level-number is 01 that includes the EXTERNAL clause must not be the same
data-name specified for any other data description entry that includes the
EXTERNAL clause.

In the same DATA DIVISION, the data description entries for any two data items
for which the same data-name is specified must not include the GLOBAL clause.

Chapter 8. Referencing data names, copy libraries, and PROCEDURE DIVISION names 73
 DATA DIVISION names that are explicitly referenced must either be uniquely
defined or made unique through qualification. Unreferenced data items need not
be uniquely defined. The highest level in a data hierarchy (a data item associated
with a level indicator (FD or SD in the FILE SECTION) or with level-number 01)
must be uniquely named if referenced. Data items associated with level-numbers
02 through 49 are successively lower levels of the hierarchy.

Condition-name
See the syntax and description for details.

Format 1: condition-name in data division

►► condition-name-1 ▼ ►
IN data-name-1 IN file-name-1
OF OF

► ►◄

( ▼ subscript )

Format 2: condition-name in SPECIAL-NAMES paragraph

►► condition-name-1 ▼ ►◄
IN mnemonic-name-1
OF

condition-name-1
Can be referenced by statements and entries either in the program that
contains the definition of condition-name-1, or in a program contained
within that program.
If explicitly referenced, a condition-name must be unique or be made
unique through qualification or subscripting (or both) except when the
scope of names by itself ensures uniqueness of reference.
If qualification is used to make a condition-name unique, the associated
conditional variable can be used as the first qualifier. If qualification is
used, the hierarchy of names associated with the conditional variable itself
must be used to make the condition-name unique.
If references to a conditional variable require subscripting, reference to any
of its condition-names also requires the same combination of subscripting.

74 Enterprise COBOL for z/OS, V6.1 Language Reference

 In this information, condition-name refers to a condition-name qualified or
subscripted, as necessary.
data-name-1
Can be a record-name.
file-name-1
Must be identified by an FD or SD entry in the DATA DIVISION.
file-name-1 must be unique within this program.
mnemonic-name-1
For information about acceptable values for mnemonic-name-1, see
“SPECIAL-NAMES paragraph” on page 116.

Index-name
An index-name identifies an index. An index can be regarded as a private special
register that the compiler generates for working with a table. You name an index
by specifying the INDEXED BY phrase in the OCCURS clause that defines a table.

You can use an index-name in only the following language elements:

v SET statements
v PERFORM statements
v SEARCH statements
v Subscripts
v Relation conditions

An index-name is not the same as the name of an index data item, and an
index-name cannot be used like a data-name.

Index data item

An index data item is a data item that can hold the value of an index.

You define an index data item by specifying the USAGE IS INDEX clause in a data
description entry. The name of an index data item is a data-name. An index data
item can be used anywhere a data-name or identifier can be used, unless stated
otherwise in the rules of a particular statement. You can use the SET statement to
save the value of an index (referenced by index-name) in an index data item.

Subscripting
Subscripting is a method of providing table references through the use of
subscripts. A subscript is a positive integer whose value specifies the occurrence
number of a table element.

Chapter 8. Referencing data names, copy libraries, and PROCEDURE DIVISION names 75
 Format

►► condition-name-1 ▼ ►
data-name-1 IN data-name-2
OF

► ►
IN file-name-1
OF

► ( ▼ integer-1 ) ►◄
ALL
data-name-3
+ integer-2
-
index-name-1
+ integer-3
-

condition-name-1
The conditional variable for condition-name-1 must contain an OCCURS
clause or must be subordinate to a data description entry that contains an
OCCURS clause.
data-name-1
Must contain an OCCURS clause or must be subordinate to a data
description entry that contains an OCCURS clause.
data-name-2 , file-name-1
Must name data items or records that contain data-name-1.
integer-1
Can be signed. If signed, it must be positive.
| ALL Shall not be specified if condition-name-1 is specified.
| Must be used only when the subscripted identifier is used as an intrinsic
| function argument or to identify a table in a format 2 SORT statement
| (table SORT statement).
| If ALL is specified, the subscript is all of the possible values of a subscript
| for the associated table as specified in the rules for the functions for which
| the subscript ALL is allowed.
data-name-3
Must be a numeric elementary item representing an integer.
data-name-3 can be qualified.
index-name-1
Corresponds to a data description entry in the hierarchy of the table being
referenced that contains an INDEXED BY phrase that specifies that name.

76 Enterprise COBOL for z/OS, V6.1 Language Reference

 integer-2 , integer-3
Cannot be signed.

The subscripts, enclosed in parentheses, are written immediately following any

qualification for the name of the table element. The number of subscripts in such a
reference must equal the number of dimensions in the table whose element is
being referenced. That is, there must be a subscript for each OCCURS clause in the
hierarchy that contains the data-name including the data-name itself.

When more than one subscript is required, they are written in the order of
successively less inclusive dimensions of the data organization. If a
multidimensional table is thought of as a series of nested tables and the most
inclusive or outermost table in the nest is considered to be the major table with the
innermost or least inclusive table being the minor table, the subscripts are written
from left to right in the order major, intermediate, and minor.

For example, if TABLE-THREE is defined as:

01 TABLE-THREE.
05 ELEMENT-ONE OCCURS 3 TIMES.
10 ELEMENT-TWO OCCURS 3 TIMES.
15 ELEMENT-THREE OCCURS 2 TIMES PIC X(8).

a valid subscripted reference to TABLE-THREE is:

ELEMENT-THREE (2 2 1)

Subscripted references can also be reference modified. See the third example under
“Reference modification examples” on page 81. A reference to an item must not be
subscripted unless the item is a table element or an item or condition-name
associated with a table element.

Each table element reference must be subscripted except when such reference
appears:
v In a USE FOR DEBUGGING statement
v As the subject of a SEARCH statement
v In a REDEFINES clause
v In the KEY IS phrase of an OCCURS clause
| v In a format 2 SORT statement (table SORT statement)

| In a format 2 SORT statement, subscripting may be specified with the rightmost

| subscript being the word ALL.

The lowest permissible occurrence number represented by a subscript is 1. The

highest permissible occurrence number in any particular case is the maximum
number of occurrences of the item as specified in the OCCURS clause.

Subscripting using data-names

When a data-name is used to represent a subscript, it can be used to reference

items within different tables. These tables need not have elements of the same size.
The same data-name can appear as the only subscript with one item and as one of
two or more subscripts with another item. A data-name subscript can be qualified;
it cannot be subscripted or indexed. For example, valid subscripted references to
TABLE-THREE, assuming that SUB1, SUB2, and SUB3 are all items subordinate to
SUBSCRIPT-ITEM, include:

Chapter 8. Referencing data names, copy libraries, and PROCEDURE DIVISION names 77
 ELEMENT-THREE (SUB1 SUB2 SUB3)

ELEMENT-THREE IN TABLE-THREE (SUB1 OF SUBSCRIPT-ITEM,

SUB2 OF SUBSCRIPT-ITEM, SUB3 OF SUBSCRIPT-ITEM)

Subscripting using index-names (indexing)

Indexing allows such operations as table searching and manipulating specific

items. To use indexing, you associate one or more index-names with an item
whose data description entry contains an OCCURS clause.

An index associated with an index-name acts as a subscript, and its value

corresponds to an occurrence number for the item to which the index-name is
associated.

The INDEXED BY phrase, by which the index-name is identified and associated

with its table, is an optional part of the OCCURS clause. There is no separate entry
to describe the index associated with index-name. At run time, the contents of the
index corresponds to an occurrence number for that specific dimension of the table
with which the index is associated.

The initial value of an index at run time is undefined, and the index must be
initialized before it is used as a subscript. An initial value is assigned to an index
with one of the following statements:
v The PERFORM statement with the VARYING phrase
v The SEARCH statement with the ALL phrase
v The SET statement

The use of an integer or data-name as a subscript that references a table element or

an item within a table element does not cause the alteration of any index
associated with that table.

An index-name can be used to reference any table. However, the element length of
the table being referenced and of the table that the index-name is associated with
should match. Otherwise, the reference will not be to the same table element in
each table, and you might get runtime errors.

Data that is arranged in the form of a table is often searched. The SEARCH
statement provides facilities for producing serial and nonserial searches. It is used
to search for a table element that satisfies a specific condition and to adjust the
value of the associated index to indicate that table element.

To be valid during execution, an index value must correspond to a table element

occurrence of neither less than one, nor greater than the highest permissible
occurrence number.

For more information about index-names, see “Index-name” on page 75 and

“INDEXED BY phrase” on page 199.

Relative subscripting

In relative subscripting, the name of a table element is followed by a subscript of the

form data-name or index-name followed by the operator + or -, and a positive or
unsigned integer literal.

78 Enterprise COBOL for z/OS, V6.1 Language Reference

 The operators + and - must be preceded and followed by a space. The value of the
subscript used is the same as if the index-name or data-name had been set up or
down by the value of the integer. The use of relative indexing does not cause the
program to alter the value of the index.

Reference modification
Reference modification defines a data item by specifying a leftmost character and
optional length for the data item.

Format: reference modification

►► data-name-1 ( leftmost-character-position : ) ►◄
length
FUNCTION function-name-1

( ▼ argument-1 )

data-name-1
Must reference a data item described explicitly or implicitly with usage
DISPLAY, DISPLAY-1, or NATIONAL. A national group item is processed
as an elementary data item of category national.
data-name-1 can be qualified or subscripted.
leftmost-character-position
Must be an arithmetic expression. The evaluation of leftmost-character-
position must result in a positive nonzero integer that is less than or equal
to the number of characters in the data item referenced by data-name-1.
length
Must be an arithmetic expression.
The evaluation of length must result in a positive nonzero integer.
The sum of leftmost-character-position and length minus the value 1 must be
less than or equal to the number of character positions in data-name-1. If
length is omitted, the length used will be equal to the number of character
positions in data-name-1 plus 1, minus leftmost-character-position.
function-name-1
Must reference an alphanumeric or national function.

For usages DISPLAY-1 and NATIONAL, each character position occupies 2 bytes.
Reference modification operates on whole character positions and not on the
individual bytes of the characters in usages DISPLAY-1 and NATIONAL. For usage
DISPLAY, reference modification operates as though each character were a
single-byte character.

Unless otherwise specified, reference modification is allowed anywhere an

identifier or function-identifier that references a data item or function with the
same usage as the reference-modified data item is permitted.

Each character position referenced by data-name-1 or function-name-1 is assigned an

ordinal number incrementing by one from the leftmost position to the rightmost

Chapter 8. Referencing data names, copy libraries, and PROCEDURE DIVISION names 79
 position. The leftmost position is assigned the ordinal number one. If the data
description entry for data-name-1 contains a SIGN IS SEPARATE clause, the sign
position is assigned an ordinal number within that data item.

If data-name-1 is described with usage DISPLAY and category numeric,

numeric-edited, alphabetic, alphanumeric-edited, or external floating-point,
data-name-1 is operated upon for purposes of reference modification as if it were
redefined as a data item of category alphanumeric with the same size as the data
item referenced by data-name-1.

If data-name-1 is described with usage NATIONAL and category numeric,

numeric-edited, national-edited, or external floating-point, data-name-1 is operated
upon for purposes of reference modification as if it were redefined as a data item
of category national with the same size as the data item referenced by data-name-1.

If data-name-1 is a national group item, data-name-1 is processed as an elementary

data item of category national.

Reference modification creates a unique data item that is a subset of data-name-1 or

a subset of the value referenced by function-name-1 and its arguments, if any. This
unique data item is considered an elementary data item without the JUSTIFIED
clause.

When a function is reference-modified, the unique data item has class, category,
and usage national if the type of the function is national; otherwise, it has class
and category alphanumeric and usage display.

When data-name-1 is reference-modified, the unique data item has the same class,
category, and usage as that defined for the data item referenced by data-name-1
except that:
v If data-name-1 has category national-edited, the unique data item has category
national.
v If data-name-1 has usage NATIONAL and category numeric-edited, numeric, or
external floating-point, the unique data item has category national.
v If data-name-1 has usage DISPLAY, and category numeric-edited,
alphanumeric-edited, numeric, or external floating-point, the unique data item
has category alphanumeric.
v If data-name-1 references an alphanumeric group item, the unique data item is
considered to have usage DISPLAY and category alphanumeric.
v If data-name-1 references a national group item, the unique data item has usage
NATIONAL and category national.

If length is not specified, the unique data item created extends from and includes
the character position identified by leftmost-character-position up to and including
the rightmost character position of the data item referenced by data-name-1.

Evaluation of operands

Reference modification for an operand is evaluated as follows:

v If subscripting is specified for the operand, the reference modification is
evaluated immediately after evaluation of the subscript.
v If subscripting is not specified for the operand, the reference modification is
evaluated at the time subscripting would be evaluated if subscripts had been
specified.

80 Enterprise COBOL for z/OS, V6.1 Language Reference

 Reference modification examples

The statements in the examples transfer the first 10 characters of the data-item
referenced by WHOLE-NAME to the data-item referenced by FIRST-NAME.
77 WHOLE-NAME PIC X(25).
77 FIRST-NAME PIC X(10).
77 START-P PIC 9(4) BINARY VALUE 1.
77 STR-LENGTH PIC 9(4) BINARY VALUE 10.
...
MOVE WHOLE-NAME(1:10) TO FIRST-NAME.
MOVE WHOLE-NAME(START-P:STR-LENGTH) TO FIRST-NAME.

The following statement transfers the last 15 characters of the data-item referenced
by WHOLE-NAME to the data-item referenced by LAST-NAME.
77 WHOLE-NAME PIC X(25).
77 LAST-NAME PIC X(15).
...
MOVE WHOLE-NAME(11:) TO LAST-NAME.

The following statement transfers the fourth and fifth characters of the third
occurrence of TAB to the variable SUFFIX.
01 TABLE-1.
02 TAB OCCURS 10 TIMES PICTURE X(5).
77 SUFFIX PICTURE X(2).
...
MOVE TAB OF TABLE-1 (3) (4:2) TO SUFFIX.

Function-identifier
A function-identifier is a sequence of character strings and separators that uniquely
references the data item that results from the evaluation of a function.

Format

►► FUNCTION function-name-1 ►

( ▼ argument-1 )

► ►◄
reference-modifier

argument-1
Must be an identifier, literal (other than a figurative constant), or arithmetic
expression.
For more information, see Chapter 21, “Intrinsic functions,” on page 509.
function-name-1
function-name-1 must be one of the intrinsic function names.
reference-modifier
Can be specified only for functions of the type alphanumeric or national.

Chapter 8. Referencing data names, copy libraries, and PROCEDURE DIVISION names 81
 A function-identifier that makes reference to an alphanumeric or national function
can be specified anywhere that a data item of category alphanumeric or category
national, respectively, can be referenced and where references to functions are not
specifically prohibited, except as follows:
v As a receiving operand of any statement
v Where a data item is required to have particular characteristics (such as class
and category, size, sign, and permissible values) and the evaluation of the
function according to its definition and the particular arguments specified would
not have these characteristics

A function-identifier that makes reference to an integer or numeric function can be

used wherever an arithmetic expression can be used.

Data attribute specification

Explicit data attributes are data attributes that you specify in COBOL coding. Implicit
data attributes are default values. If you do not explicitly code a data attribute, the
compiler assumes a default value.

For example, you need not specify the USAGE of a data item. If USAGE is omitted
and the symbol N is not specified in the PICTURE clause, the default is USAGE
DISPLAY, which is the implicit data attribute. When PICTURE symbol N is used,
USAGE DISPLAY-1 is the default when the NSYMBOL(DBCS) compiler option is
in effect; USAGE NATIONAL is the default when the NSYMBOL(NATIONAL)
compiler option is in effect. These are implicit data attributes.

82 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 9. Transfer of control
In the PROCEDURE DIVISION, unless there is an explicit control transfer or there
is no next executable statement, program flow transfers control from statement to
statement in the order in which the statements are written. This normal program
flow is an implicit transfer of control.

In addition to the implicit transfers of control between consecutive statements,

implicit transfer of control also occurs when the normal flow is altered without the
execution of a procedure branching statement. The following examples show
implicit transfers of control, overriding statement-to-statement transfer of control:
v After execution of the last statement of a procedure that is executed under
control of another COBOL statement, control implicitly transfers. (COBOL
statements that control procedure execution are, for example, MERGE,
PERFORM, SORT, and USE.) Further, if a paragraph is being executed under the
control of a PERFORM statement that causes iterative execution, and that
paragraph is the first paragraph in the range of that PERFORM statement, an
implicit transfer of control occurs between the control mechanism associated
with that PERFORM statement and the first statement in that paragraph for each
iterative execution of the paragraph.
v During SORT or MERGE statement execution, control is implicitly transferred to
an input or output procedure.
v During XML PARSE statement execution, control is implicitly transferred to a
processing procedure.
v During execution of any COBOL statement that causes execution of a declarative
procedure, control is implicitly transferred to that procedure.
v At the end of execution of any declarative procedure, control is implicitly
transferred back to the control mechanism associated with the statement that
caused its execution.

COBOL also provides explicit control transfers through the execution of any
procedure branching, program call, or conditional statement. (Lists of procedure
branching and conditional statements are contained in “Statement categories” on
page 284.)

Definition: The term next executable statement refers to the next COBOL statement
to which control is transferred, according to the rules given above. There is no next
executable statement under the following circumstances:
v When the program contains no PROCEDURE DIVISION
v Following the last statement in a declarative section when the paragraph in
which it appears is not being executed under the control of some other COBOL
statement
v Following the last statement in a program or method when the paragraph in
which it appears is not being executed under the control of some other COBOL
statement in that program
v Following the last statement in a declarative section when the statement is in the
range of an active PERFORM statement executed in a different section and this
last statement of the declarative section is not also the last statement of the
procedure that is the exit of the active PERFORM statement

© Copyright IBM Corp. 1991, 2017 83

 v Following a STOP RUN statement or EXIT PROGRAM statement that transfers
control outside the COBOL program
v Following a GOBACK statement that transfers control outside the COBOL
program
v Following an EXIT METHOD statement that transfers control outside the
COBOL method
v The end program or end method marker

When there is no next executable statement and control is not transferred outside
the COBOL program, the program flow of control is undefined unless the program
execution is in the nondeclarative procedures portion of a program under control
of a CALL statement, in which case an implicit EXIT PROGRAM statement is
executed.

Similarly, if control reaches the end of the PROCEDURE DIVISION of a method

and there is no next executable statement, an implicit EXIT METHOD statement is
executed.

84 Enterprise COBOL for z/OS, V6.1 Language Reference

Part 2. COBOL source unit structure

© Copyright IBM Corp. 1991, 2017 85

86 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 10. COBOL program structure
A COBOL source program is a syntactically correct set of COBOL statements.
Nested programs
A nested program is a program that is contained in another program.
Contained programs can reference some of the resources of the programs
that contain them. If program B is contained in program A, it is directly
contained if there is no program contained in program A that also contains
program B. Program B is indirectly contained in program A if there exists a
program contained in program A that also contains program B. For more
information about nested programs, see Nested programs in the Enterprise
COBOL Programming Guide.
Object program
An object program is a set or group of executable machine language
instructions and other material designed to interact with data to provide
problem solutions. An object program is generally the machine language
result of the operation of a COBOL compiler on a source program. The
term object program also refers to the methods that result from compiling
a class definition.
Run unit
A run unit is one or more object programs that interact with one another
and that function at run time as an entity to provide problem solutions.
Sibling program
Sibling programs are programs that are directly contained in the same
program.

With the exception of the COPY and REPLACE statements and the end program
marker, the statements, entries, paragraphs, and sections of a COBOL source
program are grouped into the following four divisions:
v IDENTIFICATION DIVISION
v ENVIRONMENT DIVISION
v DATA DIVISION
v PROCEDURE DIVISION

The end of a COBOL source program is indicated by the END PROGRAM marker.
If there are no nested programs, the absence of additional source program lines
also indicates the end of a COBOL program.

The following format is for the entries and statements that constitute a separately
compiled COBOL source program.

© Copyright IBM Corp. 1991, 2017 87

 Format: COBOL source program

►► IDENTIFICATION DIVISION. PROGRAM-ID program-name-1 ►

ID .

► ►
RECURSIVE . identification-division-content
IS INITIAL PROGRAM

► ►
ENVIRONMENT DIVISION. environment-division-content

► ►
DATA DIVISION. data-division-content PROCEDURE DIVISION. procedure-division-content

► ►◄
END PROGRAM program-name-1.

▼ Nested source program

nested source program:

IDENTIFICATION DIVISION. PROGRAM-ID program-name-2 ►

ID .

► ►
COMMON . identification-division-content
IS INITIAL PROGRAM
INITIAL
COMMON

► ►
ENVIRONMENT DIVISION. environment-division-content

► ►
DATA DIVISION. data-division-content PROCEDURE DIVISION. procedure-division-content

► END PROGRAM program-name-2.

▼ | nested source program |

A sequence of separate COBOL programs can also be input to the compiler. The
following format is for the entries and statements that constitute a sequence of
source programs (batch compile).

88 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format: sequence of COBOL source programs

►► ▼ COBOL-source-program ►◄

END PROGRAM program-name

An end program marker separates each program in the sequence of
programs. program-name must be identical to a program-name declared in a
preceding program-ID paragraph.
program-name can be specified either as a user-defined word or in an
alphanumeric literal. Either way, program-name must follow the rules for
forming program-names. program-name cannot be a figurative constant. Any
lowercase letters in the literal are folded to uppercase.
An end program marker is optional for the last program in the sequence
only if that program does not contain any nested source programs.

Nested programs
A COBOL program can contain other COBOL programs, which in turn can contain
still other COBOL programs. These contained programs are called nested programs.
Nested programs can be directly or indirectly contained in the containing program.

Nested programs are not supported for programs compiled with the THREAD
option.

In the following code fragment, program Outer-program directly contains program

Inner-1. Program Inner-1 directly contains program Inner-1a, and Outer-program
indirectly contains Inner-1a:
Id division.
Program-id. Outer-program.
Procedure division.
Call "Inner-1".
Stop run.
Id division.
Program-id. Inner-1
...
Call Inner-1a.
Stop run.
Id division.
Program-id. Inner-1a.
...
End Inner-1a.
End Inner-1.
End Outer-program.

The following figure describes a more complex nested program structure with
directly and indirectly contained programs.

Chapter 10. COBOL program structure 89

 Conventions for program-names
The program-name of a program is specified in the PROGRAM-ID paragraph of
the program's IDENTIFICATION DIVISION. A program-name can be referenced
only by the CALL statement, the CANCEL statement, the SET statement, or the
END PROGRAM marker.

Names of programs that constitute a run unit are not necessarily unique, but when
two programs in a run unit are identically named, at least one of the programs
must be directly or indirectly contained within another separately compiled
program that does not contain the other of those two programs.

A separately compiled program and all of its directly and indirectly contained
programs must have unique program-names within that separately compiled
program.

Rules for program-names

The following rules define the scope of a program-name:
v If the program-name is that of a program that does not possess the COMMON
attribute and that program is directly contained within another program, that
program-name can be referenced only by statements included in that containing
program.
v If the program-name is that of a program that does possess the COMMON
attribute and that program is directly contained within another program, that
program-name can be referenced only by statements included in the containing

90 Enterprise COBOL for z/OS, V6.1 Language Reference

 program and any programs directly or indirectly contained within that
containing program, except that program possessing the COMMON attribute
and any programs contained within it.
v If the program-name is that of a program that is separately compiled, that
program-name can be referenced by statements included in any other program
in the run unit, except programs it directly or indirectly contains.

The mechanism used to determine which program to call is as follows:

v If one of two programs that have the same name as that specified in the CALL
statement is directly contained within the program that includes the CALL
statement, that program is called.
v If one of two programs that have the same name as that specified in the CALL
statement possesses the COMMON attribute and is directly contained within
another program that directly or indirectly contains the program that includes
the CALL statement, that common program is called unless the calling program
is contained within that common program.
v Otherwise, the separately compiled program is called.

The following rules apply to referencing a program-name of a program that is

contained within another program. For this discussion, Program-A contains
Program-B and Program-C; Program-C contains Program-D and Program-F; and
Program-D contains Program-E.

If Program-D does not possess the COMMON attribute, then Program-D can be
referenced only by the program that directly contains Program-D, that is,
Program-C.

Chapter 10. COBOL program structure 91

 If Program-D does possess the COMMON attribute, then Program-D can be
referenced by Program-C (because Program-C contains Program-D) and by any
programs contained in Program-C except for programs contained in Program-D. In
other words, if Program-D possesses the COMMON attribute, Program-D can be
referenced in Program-C and Program-F but not by statements in Program-E,
Program-A, or Program-B.

92 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 11. COBOL class definition structure
Enterprise COBOL provides object-oriented syntax to facilitate interoperation of
COBOL and Java programs.

You can use object-oriented syntax to:

v Define classes, with methods and data implemented in COBOL
v Create instances of Java or COBOL classes
v Invoke methods on Java or COBOL objects
v Write classes that inherit from Java classes or from other COBOL classes
v Define and invoke overloaded methods

Basic Java-oriented object capabilities are accessed directly through COBOL

language features. Additional capabilities are available to the COBOL programmer
by calling services through the Java Native Interface (JNI), as described in
Accessing JNI services in the Enterprise COBOL Programming Guide.

Java programs can be multithreaded, and Java interoperation requires toleration of

asynchronous signals. Therefore, to mix COBOL with these Java programs, you
must use the thread enablement provided by the THREAD compiler option, as
described in THREAD in the Enterprise COBOL Programming Guide.

Java String data is represented at run time in Unicode. The Unicode support
provided in Enterprise COBOL with the national data type enables COBOL
programs to exchange String data with Java.

The following entities and concepts are used in object-oriented COBOL for Java
interoperability:
Class The entity that defines operations and state for zero, one, or more object
instances and defines operations and state for a common object (a factory
object) that is shared by multiple object instances.
You create object instances using the NEW operand of the COBOL
INVOKE statement or using a Java class instance creation expression.
Object instances are automatically freed by the Java runtime system's
garbage collection when they are no longer in use. You cannot explicitly
free individual objects.
Instance method
Procedural code that defines one of the operations supported for the object
instances of a class. Instance methods introduced by a COBOL class are
defined within the object paragraph of the class definition.
COBOL instance methods are equivalent to public nonstatic methods in
Java.
You execute instance methods on a particular object instance by using a
COBOL INVOKE statement or a Java method invocation expression.
Instance data
Data that defines the state of an individual object instance. Instance data in
a COBOL class is defined in the WORKING-STORAGE SECTION of the
DATA DIVISION within the object paragraph of a class definition.

© Copyright IBM Corp. 1991, 2017 93

 COBOL instance data is equivalent to private nonstatic member data in a
Java class.
The state of an object also includes the state of the instance data
introduced by inherited classes. Each instance object has its own copy of
the instance data defined within its class definition and its own copy of the
instance data defined in inherited classes.
You can access COBOL object instance data only from within COBOL
instance methods defined in the class definition that defines the data.
You can initialize object instance data with VALUE clauses or you can
write an instance method to perform custom initialization.
Factory method, static method
Procedural code that defines one of the operations supported for the
common factory object of the class. COBOL factory methods are defined
within the factory paragraph of a class definition. Factory methods are
associated with a class, not with any individual instance object of the class.
COBOL factory methods are equivalent to public static methods in Java.
You execute COBOL factory methods from COBOL using an INVOKE
statement that specifies the class-name as the first operand. You execute
them from a Java program using a static method invocation expression.
A factory method cannot operate directly on instance data of its class, even
though the data is described in the same class definition; a factory method
must invoke instance methods to act on instance data.
COBOL factory methods are typically used to define customized methods
that create object instances. For example, you can code a customized
factory method that accepts initial values as parameters, creates an instance
object using the NEW operand of the INVOKE statement, and then invokes
a customized instance method passing those initial values as arguments for
use in initializing the instance object.
Factory data, static data
Data associated with a class, rather than with an individual object instance.
COBOL factory data is defined in the WORKING-STORAGE SECTION of
the DATA DIVISION within the factory paragraph of a class definition.
COBOL factory data is equivalent to private static data in Java.
There is a single copy of factory data for a class. Factory data is associated
only with the class and is shared by all object instances of the class. It is
not associated with any particular instance object. A factory data item
might be used, for example, to keep a count of the number of instance
objects that have been created.
You can access COBOL factory data only within COBOL factory methods
defined in the same class definition.
Inheritance
Inheritance is a mechanism whereby a class definition (the inheriting class)
acquires the methods, data descriptions, and file descriptions written in
another class definition (the inherited class). When two classes in an
inheritance relationship are considered together, the inheriting class is the
subclass (or derived class or child class); the inherited class is the superclass
(or parent class). The inheriting class also indirectly acquires the methods,
data descriptions, and file descriptions that the parent class inherited from
its parent class.

94 Enterprise COBOL for z/OS, V6.1 Language Reference

 A COBOL class must inherit from exactly one parent class, which can be
implemented in COBOL or Java.
Every COBOL class must inherit directly or indirectly from the
java.lang.Object class.
Instance variable
An individual data item defined in the DATA DIVISION of an object
paragraph.
Java Native Interface (JNI)
A facility of Java designed for interoperation with non-Java programs.
Java Native Interface (JNI) environment pointer
A pointer used to obtain the address of the JNI environment structure used
for calling JNI services. The COBOL special register JNIENVPTR is
provided for referencing the JNI environment pointer.
Object reference
A data item that contains information used to identify and reference an
individual object. An object reference can refer to an object that is an
instance of a Java or COBOL class.
Subclass
A class that inherits from another class; also called a derived class or child
class of the inherited class.
Superclass
A class that is inherited by another class; also called a parent class of the
inheriting class.

With the exception of the COPY and REPLACE statements and the END CLASS
marker, the statements, entries, paragraphs, and sections of a COBOL class
definition are grouped into the following structure:
v IDENTIFICATION DIVISION
v ENVIRONMENT DIVISION (configuration section only)
v Factory definition
– IDENTIFICATION DIVISION
– DATA DIVISION
– PROCEDURE DIVISION (containing one or more method definitions)
v Object definition
– IDENTIFICATION DIVISION
– DATA DIVISION
– PROCEDURE DIVISION (containing one or more method definitions)

The end of a COBOL class definition is indicated by the END CLASS marker.

The following format is for a COBOL class definition.

Chapter 11. COBOL class definition structure 95

 Format: COBOL class definition

►► IDENTIFICATION DIVISION. CLASS-ID . class-name-1 INHERITS class-name-2 . ►

ID

► ►
other-identification-division-content

► ENVIRONMENT DIVISION. class-environment-division-content ►

Factory-definition

► ►◄
Object-definition END CLASS class-name-1.

Factory-definition:

IDENTIFICATION DIVISION. FACTORY. ►

ID DATA DIVISION. factory-data-division-content

► END FACTORY.
PROCEDURE DIVISION.

▼ method-definition

Object-definition:

IDENTIFICATION DIVISION. OBJECT. ►

ID DATA DIVISION. object-data-division-content

► END OBJECT.
PROCEDURE DIVISION.

▼ method-definition

END CLASS
Specifies the end of a class definition.
END FACTORY
Specifies the end of a factory definition.
END OBJECT
Specifies the end of an object definition.

96 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 12. COBOL method definition structure
A COBOL method definition describes a method. You can specify method
definitions only within the factory paragraph and the object paragraph of a class
definition.

With the exception of COPY and REPLACE statements and the END METHOD
marker, the statements, entries, paragraphs, and sections of a COBOL method
definition are grouped into the following four divisions:
v IDENTIFICATION DIVISION
v ENVIRONMENT DIVISION (input-output section only)
v DATA DIVISION
v PROCEDURE DIVISION

The end of a COBOL method definition is indicated by the END METHOD marker.

The following format is for a COBOL method definition.

Format: method definition

►► IDENTIFICATION DIVISION. METHOD-ID method-name-1 ►

ID . .

► ►
other-identification-division-content

► ►
ENVIRONMENT DIVISION. method-environment-division-content

► ►
DATA DIVISION. method-data-division-content

► ►
method-procedure-division-header.
method-procedure-division-content

► END METHOD method-name-1. ►◄

METHOD-ID
Identifies a method definition. See “METHOD-ID paragraph” on page 108
for details.
method-procedure-division-header
Indicates the start of the PROCEDURE DIVISION and identifies method
parameters and the returning item, if any. See “The PROCEDURE
DIVISION header” on page 255 for details.
END METHOD
Specifies the end of a method definition.

© Copyright IBM Corp. 1991, 2017 97

 Methods defined in an object definition are instance methods. An instance method in
a given class can access:
v Data defined in the DATA DIVISION of the object paragraph of that class
(instance data)
v Data defined in the DATA DIVISION of that instance method (method data)

An instance method cannot directly access instance data defined in a parent class,
factory data defined in its own class, or method data defined in another method of
its class. It must invoke a method to access such data.

Methods defined in a factory definition are factory methods. A factory method in a

given class can access:
v Data defined in the DATA DIVISION of the factory paragraph of that class
(factory data)
v Data defined in the DATA DIVISION of that factory method (method data)

A factory method cannot directly access factory data defined in a parent class,
instance data defined in its own class, or method data defined in another method
of its class. It must invoke a method to access such data.

Methods can be invoked from COBOL programs and methods, and they can be
invoked from Java programs. A method can execute an INVOKE statement that
directly or indirectly invokes itself. Therefore, COBOL methods are implicitly
recursive (unlike COBOL programs, which support recursion only if the
RECURSIVE attribute is specified in the program-ID paragraph.)

98 Enterprise COBOL for z/OS, V6.1 Language Reference

Part 3. Identification division

© Copyright IBM Corp. 1991, 2017 99

100 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 13. IDENTIFICATION DIVISION
The IDENTIFICATION DIVISION must be the first division in each COBOL source
program, factory definition, object definition, and method definition. The
identification division names the program, class, or method and identifies the
factory definition and object definition. The IDENTIFICATION DIVISION can
include the date a program, class, or method was written, the date of compilation,
and other such documentary information.
Program IDENTIFICATION DIVISION
For a program, the first paragraph of the IDENTIFICATION DIVISION
must be the PROGRAM-ID paragraph. The other paragraphs are optional
and can appear in any order.
Class IDENTIFICATION DIVISION
For a class, the first paragraph of the IDENTIFICATION DIVISION must
be the CLASS-ID paragraph. The other paragraphs are optional and can
appear in any order.
Factory IDENTIFICATION DIVISION
A factory IDENTIFICATION DIVISION contains only a factory paragraph
header.
Object IDENTIFICATION DIVISION
An object IDENTIFICATION DIVISION contains only an object paragraph
header.
Method IDENTIFICATION DIVISION
For a method, the first paragraph of the IDENTIFICATION DIVISION
must be the METHOD-ID paragraph. The other paragraphs are optional
and can appear in any order.

The following format is for a program IDENTIFICATION DIVISION.

© Copyright IBM Corp. 1991, 2017 101

 Format: program identification division

►► IDENTIFICATION DIVISION. PROGRAM-ID program-name ►

ID .

► ►
RECURSIVE .
IS COMMON PROGRAM
INITIAL
INITIAL
COMMON

► ►
AUTHOR
.

▼ comment-entry

► ►
INSTALLATION
.

▼ comment-entry

► ►
DATE-WRITTEN
.

▼ comment-entry

► ►
DATE-COMPILED.

▼ comment-entry

► ►◄
SECURITY
.

▼ comment-entry

The following format is for a class IDENTIFICATION DIVISION.

102 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format: class identification division

►► IDENTIFICATION DIVISION. CLASS-ID. class-name-1 ►

ID DIVISION.

► INHERITS class-name-2. ►
AUTHOR
.

▼ comment-entry

► ►
INSTALLATION
.

▼ comment-entry

► ►
DATE-WRITTEN
.

▼ comment-entry

► ►
DATE-COMPILED.

▼ comment-entry

► ►◄
SECURITY
.

▼ comment-entry

The following format is for a factory IDENTIFICATION DIVISION.

Format: factory identification division

►► IDENTIFICATION DIVISION. FACTORY. ►◄

ID

The following format is for an object IDENTIFICATION DIVISION.

Chapter 13. IDENTIFICATION DIVISION 103

 Format: object identification division

►► IDENTIFICATION DIVISION. OBJECT. ►◄

ID

The following format is for a method IDENTIFICATION DIVISION.

Format: method identification division

►► IDENTIFICATION DIVISION. METHOD-ID method-name-1 ►

ID . .

► ►
AUTHOR
.

▼ comment-entry

► ►
INSTALLATION
.

▼ comment-entry

► ►
DATE-WRITTEN
.

▼ comment-entry

► ►
DATE-COMPILED.

▼ comment-entry

► ►◄
SECURITY
.

▼ comment-entry

PROGRAM-ID paragraph
The PROGRAM-ID paragraph specifies the name by which the program is known
and assigns selected program attributes to that program. It is required and must be
the first paragraph in the IDENTIFICATION DIVISION.
program-name
A user-defined word or alphanumeric literal, but not a figurative constant,
that identifies your program. It must follow the following rules of
formation, depending on the setting of the PGMNAME compiler option:
104 Enterprise COBOL for z/OS, V6.1 Language Reference
 PGMNAME(COMPAT)
The name can be up to 30 characters in length.
Only the hyphen, underscore, digits 0-9, and alphabetic characters
are allowed in the name when it is specified as a user-defined
word.
At least one character must be alphabetic.
The hyphen cannot be the first or last character.
If program-name is an alphanumeric literal, the rules for the name
are the same except that the extension characters $, #, and @ can be
included in the name of the outermost program and the
underscore can be the first character.
PGMNAME (LONGUPPER)
If program-name is a user-defined word, it can be up to 30
characters in length.
If program-name is an alphanumeric literal, the literal can be up to
160 characters in length. The literal cannot be a figurative constant.
Only the hyphen, underscore, digits 0-9, and alphabetic characters
are allowed in the name when the name is specified as a
user-defined word.
At least one character must be alphabetic.
The hyphen cannot be the first or last character.
If program-name is an alphanumeric literal, the underscore character
can be the first character.
External program-names are processed with alphabetic characters
folded to uppercase.
PGMNAME (LONGMIXED)
program-name must be specified as an alphnumeric literal, which
can be up to 160 characters in length. The literal cannot be a
figurative constant.
program-name can consist of any character in the range X'41' to
X'FE'.

For information about the PGMNAME compiler option and how the compiler
processes the names, see PGMNAME in the Enterprise COBOL Programming Guide.
RECURSIVE
An optional clause that allows COBOL programs to be recursively
reentered.
You can specify the RECURSIVE clause only on the outermost program of
a compilation unit. Recursive programs cannot contain nested
subprograms.
If the RECURSIVE clause is specified, program-name can be recursively
reentered while a previous invocation is still active. If the RECURSIVE
clause is not specified, an active program cannot be recursively reentered.
The WORKING-STORAGE SECTION of a recursive program defines
storage that is statically allocated and initialized on the first entry to a
program and is available in a last-used state to any of the recursive
invocations.

Chapter 13. IDENTIFICATION DIVISION 105

 The LOCAL-STORAGE SECTION of a recursive program (as well as a
nonrecursive program) defines storage that is automatically allocated,
initialized, and deallocated on a per-invocation basis.
Internal file connectors that correspond to an FD in the FILE SECTION of a
recursive program are statically allocated. The status of internal file
connectors is part of the last-used state of a program that persists across
invocations.
The following language elements are not supported in a recursive
program:
v ALTER
v GO TO without a specified procedure-name
v RERUN
v SEGMENT-LIMIT
v USE FOR DEBUGGING
The RECURSIVE clause is required for programs compiled with the
THREAD option.
COMMON
Specifies that the program named by program-name is contained (that is,
nested) within another program and can be called from siblings of the
common program and programs contained within them. The COMMON
clause can be used only in nested programs. For more information about
conventions for program names, see “Conventions for program-names” on
page 90.
INITIAL
Specifies that when program-name is called, program-name and any programs
contained (nested) within it are placed in their initial state. The initial
attribute is not supported for programs compiled with the THREAD
option.
A program is in the initial state:
v The first time the program is called in a run unit
v Every time the program is called, if it possesses the initial attribute
v The first time the program is called after the execution of a CANCEL
statement that references the program or a CANCEL statement that
references a program that directly or indirectly contains the program
v The first time the program is called after the execution of a CALL
statement that references a program that possesses the initial attribute
and that directly or indirectly contains the program
When a program is in the initial state:
v The program's internal data contained in the WORKING-STORAGE
SECTION is initialized. If a VALUE clause is used in the description of
the data item, the data item is initialized to the defined value. If a
VALUE clause is not associated with a data item, the initial value of the
data item is undefined.
v Files with internal file connectors associated with the program are not in
the open mode.
v The control mechanisms for all PERFORM statements contained in the
program are set to their initial states.
v An altered GO TO statement contained in the program is set to its initial
state.

106 Enterprise COBOL for z/OS, V6.1 Language Reference

 For the rules governing nonunique program names, see “Rules for
program-names” on page 90.

CLASS-ID paragraph
The CLASS-ID paragraph specifies the name by which the class is known and
assigns selected attributes to that class. The CLASS-ID paragraph is required and
must be the first paragraph in a class IDENTIFICATION DIVISION.
class-name-1
A user-defined word that identifies the class. class-name-1 can optionally
have an entry in the REPOSITORY paragraph of the configuration section
of the class definition.
INHERITS
A clause that defines class-name-1 to be a subclass (or derived class) of
class-name-2 (the parent class). class-name-1 cannot directly or indirectly
inherit from class-name-1.
class-name-2
The name of a class inherited by class-name-1. You must specify class-name-2
in the REPOSITORY paragraph of the configuration section of the class
definition.

General rules
class-name-1 and class-name-2 must conform to the normal rules of formation for a
COBOL user-defined word, using single-byte characters.

See “REPOSITORY paragraph” on page 125 for details on specifying a class-name

that is part of a Java package or for using non-COBOL naming conventions for
class-names.

You cannot include a class definition in a sequence of programs or other class

definitions in a single compilation group. Each class must be specified as a
separate source file; that is, a class definition cannot be included in a batch
compile.

Inheritance
Every method available on instances of a class is also available on instances of any
subclass directly or indirectly derived from that class.

A subclass can introduce new methods that do not exist in the parent or ancestor
class and can override a method from the parent or ancestor class. When a
subclass overrides an existing method, it defines a new implementation for that
method, which replaces the inherited implementation.

The instance data of class-name-1 is the instance data declared in class-name-2

together with the data declared in the WORKING-STORAGE SECTION of
class-name-1. Note, however, that instance data is always private to the class that
introduces it.

The semantics of inheritance are as defined by Java. All classes must be derived
directly or directly from the java.lang.Object class.

Chapter 13. IDENTIFICATION DIVISION 107

 Java supports single inheritance; that is, no class can inherit directly from more
than one parent. Only one class-name can be specified in the INHERITS phrase of
a class definition.

FACTORY paragraph
The factory IDENTIFICATION DIVISION introduces the factory definition, which
is the portion of a class definition that defines the factory object of the class.

A factory object is the single common object that is shared by all object instances of
the class. The factory definition contains factory data and factory methods.

OBJECT paragraph
The object IDENTIFICATION DIVISION introduces the object definition, which is
the portion of a class definition that defines the instance objects of the class.

The object definition contains object data and object methods.

METHOD-ID paragraph
The METHOD-ID paragraph specifies the name by which a method is known and
assigns selected attributes to that method. The METHOD-ID paragraph is required
and must be the first paragraph in a method identification division.
method-name-1
An alphanumeric literal or national literal that contains the name of the
method. The name must conform to the rules of formation for a Java
method name. Method names are used directly, without translation. The
method name is processed in a case-sensitive manner.

Method signature

The signature of a method consists of the name of the method and the number and
types of the formal parameters to the method as specified in the PROCEDURE
DIVISION USING phrase.

Method overloading, overriding, and hiding

COBOL methods can be overloaded, overridden, or hidden, based on the rules of the
Java language.
Method overloading
Method names that are defined for a class are not required to be unique.
(The set of methods defined for a class includes the methods introduced by
the class definition and the methods inherited from parent classes.)
Method names defined for a class must have unique signatures. Two
methods defined for a class and that have the same name but different
signatures are said to be overloaded.
The type of the method return value, if any, is not included in the method
signature.
A class must not define two methods with the same signature but different
return value types, or with the same signature but where one method
specifies a return value and the other does not.

108 Enterprise COBOL for z/OS, V6.1 Language Reference

 The rules for overloaded method definitions and resolution of overloaded
method invocations are based on the corresponding rules for Java.
Method overriding (for instance methods)
An instance method in a subclass overrides an instance method with the
same name that is inherited from a parent class if the two methods have
the same signature.
When a method overrides an instance method defined in a parent class,
the presence or absence of a method return value (the PROCEDURE
DIVISION RETURNING data-name) must be consistent in the two
methods. Further, when method return values are specified, the return
values in the overridden method and the overriding method must have
identical data types.
An instance method must not override a factory method in a COBOL
parent class, or a static method in a Java parent class.
Method hiding (for factory methods)
A factory method is said to hide any and all methods with the same
signature in the superclasses of the method definition that would otherwise
be accessible. A factory method must not hide an instance method.

Optional paragraphs
Some optional paragraphs in the IDENTIFICATION DIVISION can be omitted.

The optional paragraphs are:

AUTHOR
Name of the author of the program.
INSTALLATION
Name of the company or location.
DATE-WRITTEN
Date the program was written.
DATE-COMPILED
The DATE-COMPILED paragraph provides the compilation date in the
source listing. If a comment-entry is specified, the entire entry is replaced
with the current date, even if the entry spans lines. If the comment entry is
omitted, the compiler adds the current date to the line on which
DATE-COMPILED is printed. For example:
DATE-COMPILED. 06/30/10.
SECURITY
Level of confidentiality of the program.

The comment-entry in any of the optional paragraphs can be any combination of

characters from the character set of the computer. The comment-entry is written in
Area B on one or more lines.

Comment-entries serve only as documentation; they do not affect the meaning of

the program. A hyphen in the indicator area (column 7) is not permitted in
comment-entries.

Chapter 13. IDENTIFICATION DIVISION 109

 You can include DBCS character strings as comment-entries in the
IDENTIFICATION DIVISION of your program. Multiple lines are allowed in a
comment-entry that contains DBCS character strings.

A DBCS character string must be preceded by a shift-out control character and

followed by a shift-in control character. For example:
AUTHOR. <.A.U.T.H.O.R.-.N.A.M.E>, XYZ CORPORATION
DATE-WRITTEN. <.D.A.T.E>

When a comment-entry that is contained on multiple lines uses DBCS characters,

shift-out and shift-in characters must be paired on a line.

110 Enterprise COBOL for z/OS, V6.1 Language Reference

Part 4. Environment division

© Copyright IBM Corp. 1991, 2017 111

112 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 14. Configuration section
The configuration section is an optional section for programs and classes, and can
describe the computer environment on which the program or class is compiled and
executed.
Program configuration section
The configuration section can be specified only in the ENVIRONMENT
DIVISION of the outermost program of a COBOL source program.
You should not specify the configuration section in a program that is
contained within another program. The entries specified in the
configuration section of a program apply to any program contained within
that program.
Class configuration section
Specify the configuration section in the ENVIRONMENT DIVISION of a
class definition. The repository paragraph can be specified in the
ENVIRONMENT DIVISION of a class definition.
Entries in a class configuration section apply to the entire class definition,
including all methods introduced by that class.
Method configuration section
The input-output section can be specified in a method configuration
section. The entries apply only to the method in which the configuration
section is specified.

Format:

►► CONFIGURATION SECTION. ►
source-computer-paragraph

► ►
object-computer-paragraph special-names-paragraph

► ►◄
repository-paragraph

The configuration section can:

v Relate IBM-defined environment-names to user-defined mnemonic names
v Specify the collating sequence
v Specify a currency sign value, and the currency symbol used in the PICTURE
clause to represent the currency sign value
v Exchange the functions of the comma and the period in PICTURE clauses and
numeric literals
v Relate alphabet-names to character sets or collating sequences
v Specify symbolic characters
v Relate class-names to sets of characters

© Copyright IBM Corp. 1991, 2017 113

 v Relate object-oriented class names to external class-names and identify
class-names that can be used in a class definition or program
v Relate xml-schema-names to ddnames or environment variable names
identifying files containing XML schemas

SOURCE-COMPUTER paragraph
The SOURCE-COMPUTER paragraph describes the computer on which the source
text is to be compiled.

Format

►► SOURCE-COMPUTER. ►◄
computer-name .
DEBUGGING MODE
WITH

computer-name
A system-name. For example:
IBM-system
WITH DEBUGGING MODE
Activates a compile-time switch for debugging lines written in the source
text.
A debugging line is a statement that is compiled only when the
compile-time switch is activated. Debugging lines allow you, for example,
to check the value of a data-name at certain points in a procedure.
To specify a debugging line in your program, code a D in column 7
(indicator area). You can include successive debugging lines, but each must
have a D in column 7, and you cannot break character strings across lines.
All your debugging lines must be written so that the program is
syntactically correct, whether the debugging lines are compiled or treated
as comments.
The presence or absence of the DEBUGGING MODE clause is logically
determined after all COPY and REPLACE statements have been processed.
You can code debugging lines in the ENVIRONMENT DIVISION (after the
OBJECT-COMPUTER paragraph), and in the data and procedure divisions.
If a debugging line contains only spaces in Area A and in Area B, the
debugging line is treated the same as a blank line.

All of the SOURCE-COMPUTER paragraph is syntax checked, but only the WITH
DEBUGGING MODE clause has an effect on the execution of the program.

OBJECT-COMPUTER paragraph
The OBJECT-COMPUTER paragraph specifies the system for which the object
program is designated.

114 Enterprise COBOL for z/OS, V6.1 Language Reference

Format

►► OBJECT-COMPUTER. ►

► ►◄
computer-name entry 1 .
MEMORY integer WORDS
SIZE CHARACTERS
MODULES

entry 1:

►
SEQUENCE alphabet-name
PROGRAM COLLATING IS

►
SEGMENT-LIMIT priority-number
IS

computer-name
A system-name. For example:
IBM-system
MEMORY SIZE integer
integer specifies the amount of main storage needed to run the object
program, in words, characters or modules. The MEMORY SIZE clause is
syntax checked but has no effect on the execution of the program.
PROGRAM COLLATING SEQUENCE IS alphabet-name
The collating sequence used in this program is the collating sequence
associated with the specified alphabet-name.
The collating sequence pertains to this program and to any programs that
this program might contain.
PROGRAM COLLATING SEQUENCE determines the truth value of the
following alphanumeric comparisons:
v Those explicitly specified in relation conditions
v Those explicitly specified in condition-name conditions
The PROGRAM COLLATING SEQUENCE clause also applies to any
merge or sort keys described with usage DISPLAY, unless the COLLATING
SEQUENCE phrase is specified in the MERGE or SORT statement.
The PROGRAM COLLATING SEQUENCE clause does not apply to DBCS
data items or data items of usage NATIONAL.
If the PROGRAM COLLATING SEQUENCE clause is omitted, the EBCDIC
collating sequence is used. (See Appendix C, “EBCDIC and ASCII collating
sequences,” on page 609.)
SEGMENT-LIMIT IS
The SEGMENT-LIMIT clause is syntax checked but has no effect on the
execution of the program.
priority-number
An integer ranging from 1 through 49. All sections with priority-numbers 0
Chapter 14. Configuration section 115
 through 49 are fixed permanent segments. See “Procedures” on page 260
for a description of priority-numbers and segmentation support.
Segmentation is not supported for programs compiled with the THREAD
option.

All of the OBJECT-COMPUTER paragraph is syntax checked, but only the

PROGRAM COLLATING SEQUENCE clause has an effect on the execution of the
program.

SPECIAL-NAMES paragraph
The SPECIAL-NAMES paragraph is the name of an ENVIRONMENT DIVISION
paragraph in which environment-names are related to user-specified
mnemonic-names.

The SPECIAL-NAMES paragraph:

v Relates IBM-specified environment-names to user-defined mnemonic-names
v Relates alphabet-names to character sets or collating sequences
v Specifies symbolic characters
v Relates class names to sets of characters
v Specifies one or more currency sign values and defines a picture symbol to
represent each currency sign value in PICTURE clauses
v Specifies that the functions of the comma and decimal point are to be
interchanged in PICTURE clauses and numeric literals
v Relates xml-schema-names to ddnames or environment variable names
identifying files containing XML schemas

The clauses in the SPECIAL-NAMES paragraph can appear in any order.

116 Enterprise COBOL for z/OS, V6.1 Language Reference

Format: SPECIAL-NAMES paragraph

►► SPECIAL-NAMES. ▼ ►
environment-name-1 mnemonic-name-1
IS
environment-name-2 mnemonic-name-2
IS entry 1
entry 1

► ►

▼ ALPHABET alphabet-name-1 STANDARD-1

IS STANDARD-2
NATIVE
EBCDIC

▼ literal-1 phrase 1

► ►

▼ SYMBOLIC symbolic
CHARACTERS IN alphabet-name-2

► ►

▼ CLASS class-name-1 ▼ literal-4

IS THROUGH literal-5
THRU

► ►

▼ CURRENCY literal-6
SIGN IS PICTURE SYMBOL literal-7
WITH

► ►
DECIMAL-POINT COMMA
IS

► ►◄
(1)
.
▼
XML-SCHEMA xml-schema-name-1 external-fileid-1
IS literal-8

Notes:
1 This separator period is optional when no clauses are selected. If you use
any clauses, you must code the period after the last clause.

Chapter 14. Configuration section 117

 Fragments

►► ►◄

entry 1:

ON condition-1
STATUS IS OFF condition-2
STATUS IS
OFF condition-2
STATUS IS ON condition-1
STATUS IS

phrase 1:

THROUGH literal-2
THRU

▼ ALSO literal-3

symbolic:

▼ ▼ symbolic-character-1 ▼ integer-1
ARE
IS

environment-name-1
System devices or standard system actions taken by the compiler.

Valid specifications for environment-name-1 are shown in the following table.

Table 5. Meanings of environment names
environment-
name-1 Meaning Allowed in
SYSIN System logical input unit ACCEPT
SYSIPT
SYSOUT System logical output unit DISPLAY
SYSLIST
SYSLST
SYSPUNCH System punch device DISPLAY
SYSPCH
CONSOLE Console ACCEPT and DISPLAY
C01 through C12 Skip to channel 1 through channel WRITE ADVANCING
12, respectively
CSP Suppress spacing WRITE ADVANCING
S01 through S05 Pocket select 1 through 5 on WRITE ADVANCING
punch devices

118 Enterprise COBOL for z/OS, V6.1 Language Reference

 Table 5. Meanings of environment names (continued)
environment-
name-1 Meaning Allowed in
AFP-5A Advanced Function Printing WRITE ADVANCING

environment-name-2
A 1-byte user-programmable status indicator (UPSI) switch. Valid
specifications for environment-name-2 are UPSI-0 through UPSI-7.
mnemonic-name-1 , mnemonic-name-2
mnemonic-name-1 and mnemonic-name-2 follow the rules of formation for
user-defined names. mnemonic-name-1 can be used in ACCEPT, DISPLAY,
and WRITE statements. mnemonic-name-2 can be referenced only in the SET
statement. mnemonic-name-2 can qualify condition-1 or condition-2 names.
Mnemonic-names and environment-names need not be unique. If you
choose a mnemonic-name that is also an environment-name, its definition
as a mnemonic-name will take precedence over its definition as an
environment-name.
ON STATUS IS, OFF STATUS IS
UPSI switches process special conditions within a program, such as
year-beginning or year-ending processing. For example, at the beginning of
the PROCEDURE DIVISION, an UPSI switch can be tested; if it is ON, the
special branch is taken. (See “Switch-status condition” on page 278.)
condition-1, condition-2
Condition-names follow the rules for user-defined names. At least one
character must be alphabetic. The value associated with the
condition-name is considered to be alphanumeric. A condition-name can be
associated with the on status or off status of each UPSI switch specified.
In the PROCEDURE DIVISION, the UPSI switch status is tested through
the associated condition-name. Each condition-name is the equivalent of a
level-88 item; the associated mnemonic-name, if specified, is considered the
conditional variable and can be used for qualification.
Condition-names specified in the SPECIAL-NAMES paragraph of a
containing program can be referenced in any contained program.

ALPHABET clause
The ALPHABET clause provides a means of relating an alphabet-name to a
specified character code set or collating sequence.

The related character code set or collating sequence can be used for alphanumeric
data, but not for DBCS or national data.
ALPHABET alphabet-name-1 IS
alphabet-name-1 specifies a collating sequence when used in:
v The PROGRAM COLLATING SEQUENCE clause of the object-computer
paragraph
v The COLLATING SEQUENCE phrase of the SORT or MERGE statement
alphabet-name-1 specifies a character code set when used in:
v The FD entry CODE-SET clause
v The SYMBOLIC CHARACTERS clause

Chapter 14. Configuration section 119

 STANDARD-1
Specifies the ASCII character set.
STANDARD-2
Specifies the International Reference Version of ISO/IEC 646, 7-bit
coded character set for information interchange.
NATIVE
Specifies the native character code set. If the ALPHABET clause is
omitted, EBCDIC is assumed.
EBCDIC
Specifies the EBCDIC character set.
literal-1 , literal-2 , literal-3
Specifies that the collating sequence for alphanumeric data is
determined by the program, according to the following rules:
v The order in which literals appear specifies the ordinal number,
in ascending sequence, of the characters in this collating
sequence.
v Each numeric literal specified must be an unsigned integer.
v Each numeric literal must have a value that corresponds to a
valid ordinal position within the collating sequence in effect.
See Appendix C, “EBCDIC and ASCII collating sequences,” on
page 609 for the ordinal numbers for characters in the
single-byte EBCDIC and ASCII collating sequences.
v Each character in an alphanumeric literal represents that actual
character in the character set. (If the alphanumeric literal
contains more than one character, each character, starting with
the leftmost, is assigned a successively ascending position within
this collating sequence.)
v Any characters that are not explicitly specified assume positions
in this collating sequence higher than any of the explicitly
specified characters.
v Within one alphabet-name clause, a given character must not be
specified more than once.
v Each alphanumeric literal associated with a THROUGH or ALSO
phrase must be one character in length.
v When the THROUGH phrase is specified, the contiguous
characters in the native character set beginning with the
character specified by literal-1 and ending with the character
specified by literal-2 are assigned successively ascending
positions in this collating sequence.
This sequence can be either ascending or descending within the
original native character set. That is, if "Z" THROUGH "A" is
specified, the ascending values, left-to-right, for the uppercase
letters are:
ZYXWVUTSRQPONMLKJIHGFEDCBA
v When the ALSO phrase is specified, the characters specified as
literal-1, literal-3, ... are assigned to the same position in this
collating sequence. For example, if you specify:
"D" ALSO "N" ALSO "%"
the characters D, N, and % are all considered to be in the same
position in the collating sequence.

120 Enterprise COBOL for z/OS, V6.1 Language Reference

 v When the ALSO phrase is specified and alphabet-name-1 is
referenced in a SYMBOLIC CHARACTERS clause, only literal-1
is used to represent the character in the character set.
v The character that has the highest ordinal position in this
collating sequence is associated with the figurative constant
HIGH-VALUE. If more than one character has the highest
position because of specification of the ALSO phrase, the last
character specified (or defaulted to when any characters are not
explicitly specified) is considered to be the HIGH-VALUE
character for procedural statements such as DISPLAY and as the
sending field in a MOVE statement. (If the ALSO phrase
example given above were specified as the high-order characters
of this collating sequence, the HIGH-VALUE character would be
%.)
v The character that has the lowest ordinal position in this
collating sequence is associated with the figurative constant
LOW-VALUE. If more than one character has the lowest position
because of specification of the ALSO phrase, the first character
specified is the LOW-VALUE character. (If the ALSO phrase
example given above were specified as the low-order characters
of the collating sequence, the LOW-VALUE character would be
D.)
When literal-1, literal-2, or literal-3 is specified, the alphabet-name
must not be referred to in a CODE-SET clause (see “CODE-SET
clause” on page 187).
literal-1, literal-2, and literal-3 must be alphanumeric or numeric
literals. All must have the same category. A floating-point literal, a
national literal, a DBCS literal, or a symbolic-character figurative
constant must not be specified.

SYMBOLIC CHARACTERS clause

The SYMBOLIC CHARACTERS clause is applicable only to single-byte character
sets. Each character represented is an alphanumeric character.
SYMBOLIC CHARACTERS symbolic-character-1
Provides a means of specifying one or more symbolic characters.
symbolic-character-1 is a user-defined word and must contain at least one
alphabetic character. The same symbolic-character can appear only once in
a SYMBOLIC CHARACTERS clause. The symbolic character can be a
DBCS user-defined word.
The internal representation of symbolic-character-1 is the internal
representation of the character that is represented in the specified character
set. The following rules apply:
v The relationship between each symbolic-character-1 and the corresponding
integer-1 is by their position in the SYMBOLIC CHARACTERS clause.
The first symbolic-character-1 is paired with the first integer-1; the second
symbolic-character-1 is paired with the second integer-1; and so forth.
v There must be a one-to-one correspondence between occurrences of
symbolic-character-1 and occurrences of integer-1 in a SYMBOLIC
CHARACTERS clause.
v If the IN phrase is specified, integer-1 specifies the ordinal position of the
character that is represented in the character set named by
alphabet-name-2. This ordinal position must exist.

Chapter 14. Configuration section 121

 v If the IN phrase is not specified, symbolic-character-1 represents the
character whose ordinal position in the native character set is specified
by integer-1.
Ordinal positions are numbered starting from 1.

CLASS clause
The CLASS clause provides a means for relating a name to the specified set of
characters listed in that clause.
CLASS class-name-1 IS
Provides a means for relating a name to the specified set of characters
listed in that clause. class-name-1 can be referenced only in a class
condition. The characters specified by the values of the literals in this
clause define the exclusive set of characters of which this class consists.
The class-name in the CLASS clause can be a DBCS user-defined word.
literal-4, literal-5
Must be category numeric or alphanumeric, and both must be of the same
category.
If numeric, literal-4 and literal-5 must be unsigned integers and must have
a value that is greater than or equal to 1 and less than or equal to the
number of characters in the alphabet specified. Each number corresponds
to the ordinal position of each character in the single-byte EBCDIC or
ASCII collating sequence.
If alphanumeric, literal-4 and literal-5 are an actual single-byte EBCDIC
character.
literal-4 and literal-5 must not specify a symbolic-character figurative
constant. If the value of the alphanumeric literal contains multiple
characters, each character in the literal is included in the set of characters
identified by class-name.
Floating-point literals cannot be used in the CLASS clause.
If the alphanumeric literal is associated with a THROUGH phrase, the
literal must be one character in length.
THROUGH, THRU
THROUGH and THRU are equivalent. If THROUGH is specified,
class-name includes those characters that begin with the value of
literal-4 and that end with the value of literal-5. In addition, the
characters specified by a THROUGH phrase can be in either
ascending or descending order.

CURRENCY SIGN clause

The CURRENCY SIGN clause affects numeric-edited data items whose PICTURE
character-strings contain a currency symbol.

A currency symbol represents a currency sign value that is:

v Inserted in such data items when they are used as receiving items
v Removed from such data items when they are used as sending items for a
numeric or numeric-edited receiver

Typically, currency sign values identify the monetary units stored in a data item.
For example: '$', 'EUR', 'CHF', 'JPY', 'HK$', 'HKD', or X'9F' (hexadecimal code point
122 Enterprise COBOL for z/OS, V6.1 Language Reference
in some EBCDIC code pages for €, the Euro currency sign). For details on
programming techniques for handling the Euro, see Using currency signs in the
Enterprise COBOL Programming Guide.

The CURRENCY SIGN clause specifies a currency sign value and the currency
symbol used to represent that currency sign value in a PICTURE clause.

The SPECIAL-NAMES paragraph can contain multiple CURRENCY SIGN clauses.

Each CURRENCY SIGN clause must specify a different currency symbol. Unlike all
other PICTURE clause symbols, currency symbols are case sensitive. For example,
'D' and 'd' specify different currency symbols.
CURRENCY SIGN IS literal-6
literal-6 must be an alphanumeric literal. literal-6 must not be a figurative
constant or a null-terminated literal. literal-6 must not contain a DBCS
character.
If the PICTURE SYMBOL phrase is not specified, literal-6:
v Specifies both a currency sign value and the currency symbol for this
currency sign value
v Must be a single character
v Must not contain any of the following digits or characters:
– Digits 0 through 9
– Alphabetic characters A, B, C, D, E, G, N, P, R, S, V, X, Z, their
lowercase equivalents, or the space
– Special characters + - , . * / ; ( ) " = ’ (plus sign, minus sign, comma,
period, asterisk, slash, semicolon, left parenthesis, right parenthesis,
quotation mark, equal sign, apostrophe)
v Can be one of the following lowercase alphabetic characters: f, h, i, j, k, l,
m, o, q, t, u, w, y
If the PICTURE SYMBOL phrase is specified, literal-6:
v Specifies a currency sign value. literal-7 in the PICTURE SYMBOL phrase
specifies the currency symbol for this currency sign value.
v Can consist of one or more characters.
v Must not contain any of the following digits or characters:
– Digits 0 through 9
– Special characters + - . ,
PICTURE SYMBOL literal-7
Specifies a currency symbol that can be used in a PICTURE clause to
represent the currency sign value specified by literal-6.
literal-7 must be an alphanumeric literal consisting of one single-byte
character. literal-7 must not contain any of the following digits or
characters:
v A figurative constant
v Digits 0 through 9
v Alphabetic characters A, B, C, D, E, G, N, P, R, S, V, X, Z, their lowercase
equivalents, or the space
v Special characters + - , . * / ; ( ) " = ’

If the CURRENCY SIGN clause is specified, the CURRENCY and NOCURRENCY

compiler options are ignored. If the CURRENCY SIGN clause is not specified and

Chapter 14. Configuration section 123

 the NOCURRENCY compiler option is in effect, the dollar sign ($) is used as the
default currency sign value and currency symbol. For more information about the
CURRENCY and NOCURRENCY compiler options, see CURRENCY in the
Enterprise COBOL Programming Guide.

DECIMAL-POINT IS COMMA clause

The DECIMAL-POINT IS COMMA clause exchanges the functions of the period
and the comma in PICTURE character-strings and in numeric literals.

XML-SCHEMA clause
The XML-SCHEMA clause provides the means of relating xml-schema-name-1 to an
external file identifier: a ddname or environment variable that identifies the actual
external file that contains the optimized XML schema.

The external file identifier can be specified as a user-defined word external-fileid-1

or as an alphanumeric literal literal-8, and identifies an existing external z/OSUNIX
file or MVS™ data set that contains the optimized XML schema.

The external file identifier must be either the name specified in the DD statement
for the file or the name of an environment variable that contains the file
identification information.

For details on specifying an environment variable, see “Environment variable

contents for an XML schema file.”
XML-SCHEMA xml-schema-name-1 IS
xml-schema-name-1 can be referenced only in an XML PARSE statement.
The xml-schema-name in the XML SCHEMA clause can be a DBCS
user-defined word.
external-fileid-1
Specifies a user-defined word that must conform to the following rules:
v The user-defined word can contain one to eight characters.
v The user-defined word can contain the characters, A-Z, a-z, 0-9.
v The leading character must be alphabetic.
literal-8
Specifies an alphanumeric literal that must conform to the following rules:
v The literal can contain one to eight characters.
v The literal can contain the characters, A-Z, a-z, 0-9, @, #, and $.
v The leading character must be alphabetic, @, #, and $.

The compiler folds external-fileid-1 or literal-8 to uppercase to form the ddname or

environment variable name for the file.

Environment variable contents for an XML schema file

The environment variable name must be defined using only uppercase because the
COBOL compiler automatically folds the external file identifier to uppercase.

For an XML schema in an MVS data set, the environment variable must contain a
DSN option in the format shown below.

124 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format: environment variable for XML schema in an MVS data set, DSN
option

►► DSN(data-set-name ) ►◄
(member-name)

data-set-name must be fully qualified. You must not code blanks within the
parentheses.

For an XML schema in a z/OS UNIX file, the environment variable must contain a
PATH option in the format shown below.

Format: environment variable for XML schema in a z/OS UNIX file, PATH
option

►► PATH(path-name) ►◄

path-name must be an absolute path name; that is, it must begin with a slash.
Special characters in the path name must be "escaped" by preceding them with a
backslash. For example, to include a backslash in the path name, code two
backslashes in sequence.

For more information about specifying path-name, see the description of the PATH
parameter in the z/OS MVS JCL Reference.

For both formats, blanks at the beginning and end of the environment variable
contents are ignored. You must not code blanks between a keyword and the left
parenthesis that immediately follows the keyword.

REPOSITORY paragraph
The REPOSITORY paragraph is used in a program or class definition to identify all
the object-oriented classes that are intended to be referenced in that program or
class definition. Optionally, the REPOSITORY paragraph defines associations
between class-names and external class-names.

Chapter 14. Configuration section 125

 Format: REPOSITORY paragraph

►► REPOSITORY. ►◄

▼ CLASS class-name-1
external-class-name-1
IS java-array-class-reference

class-name-1
A user-defined word that identifies the class.
external-class-name-1
An alphanumeric literal containing a name that enables a COBOL program
to define or access classes with class-names that are defined using Java
rules of formation.
The name must conform to the rules of formation for a fully qualified Java
class-name. If the class is part of a Java package, external-class-name-1 must
specify the fully qualified name of the package, followed by a period,
followed by the simple name of the Java class.
See Java Language Specification, Third Edition, by Gosling et al., for Java
class-name formation rules.
java-array-class-reference
A reference that enables a COBOL program to access a class that represents
an array object, where the elements of the array are themselves objects.
java-array-class-reference must be an alphanumeric literal with content in the
following format:

Format

►► jobjectArray ►◄
: external-class-name-2

jobjectArray
Specifies a Java object array class.
: A required separator when external-class-name-2 is specified. The
colon must not be preceded or followed by space characters.
external-class-name-2
The external class-name of the type of the elements of the array.
external-class-name-2 must follow the same rules of formation as
external-class-name-1.
When the repository entry specifies jobjectArray without the colon
separator and external-class-name-2, the elements of the object array are of
type java.lang.Object.

General rules
This topic lists the general rules of the REPOSITORY paragraph.

126 Enterprise COBOL for z/OS, V6.1 Language Reference

 1. All referenced class-names must have an entry in the repository paragraph of
the COBOL program or class definition that contains the reference. You can
specify a given class-name only once in a given repository paragraph.
2. In program definitions, the repository paragraph can be specified only in the
outermost program.
3. The repository paragraph of a COBOL class definition can optionally contain an
entry for the name of the class itself, but this entry is not required. Such an
entry can be used to specify an external class-name that uses non-COBOL
characters or that specifies a fully package-qualified class-name when a COBOL
class is to be part of a Java package.
4. Entries in a class repository paragraph apply to the entire class definition,
including all methods introduced by that class. Entries in a program repository
paragraph apply to the entire program, including its contained programs.

Identifying and referencing a class

An external-class-name is used to identify and reference a given class from outside
the class definition that defines the class.

The external class-name is determined by using the contents of

external-class-name-1, external-class-name-2, or class-name-1 (as specified in the
repository paragraph of a class), as described below:
1. external-class-name-1 and external-class-name-2 are used directly, without
translation. They are processed in a case-sensitive manner.
2. class-name-1 is used if external-class-name-1 or java-array-class-reference is not
specified. To create an external name that identifies the class and conforms to
Java rules of formation, class-name-1 is processed as follows:
v The name is converted to uppercase.
v Hyphens are translated to zero.
v Underscores are not translated.
v If the first character of the name is a digit, it is converted as follows:
– Digits 1 though 9 are changed to A through I.
– 0 is changed to J.

The class can be implemented in Java or COBOL.

When referencing a class that is part of a Java package, external-class-name-1 must

be specified and must give the fully qualified Java class-name.

For example, the repository entry

Repository.
Class JavaException is "java.lang.Exception"

defines local class-name JavaException for referring to the fully qualified

external-class-name "java.lang.Exception."

When defining a COBOL class that is to be part of a Java package, specify an entry
in the repository paragraph of that class itself, giving the full Java
package-qualified name as the external class-name.

Chapter 14. Configuration section 127

128 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 15. Input-Output section
The input-output section of the ENVIRONMENT DIVISION contains
FILE-CONTROL paragraph and I-O-CONTROL paragraph.

The exact contents of the input-output section depend on the file organization and
access methods used. See “ORGANIZATION clause” on page 139 and “ACCESS
MODE clause” on page 142.
Program input-output section
The same rules apply to program and method I-O sections.
Class input-output section
The input-output section is not valid for class definitions.
Method input-output section
The same rules apply to program and method I-O sections.

Format: input-output section

►► INPUT-OUTPUT SECTION. FILE-CONTROL. ▼ file-control-paragraph ►

► ►◄
I-O-CONTROL.

▼ i-o-control-paragraph .

FILE-CONTROL
The keyword FILE-CONTROL identifies the file-control paragraph. This
keyword can appear only once, at the beginning of the FILE-CONTROL
paragraph. It must begin in Area A and be followed by a separator period.
The keyword FILE-CONTROL and the period can be omitted if no
file-control-paragraph is specified and there are no files defined in the
program.
file-control-paragraph
Names the files and associates them with the external data sets.
Must begin in Area B with a SELECT clause. It must end with a separator
period. See “FILE-CONTROL paragraph” on page 130.
file-control-paragraph can be omitted if there are no files defined in the
program, even if the FILE-CONTROL keyword is specified.
I-O-CONTROL
The keyword I-O-CONTROL identifies the I-O-CONTROL paragraph.

© Copyright IBM Corp. 1991, 2017 129

 i-o-control-paragraph
Specifies information needed for efficient transmission of data between the
external data set and the COBOL program. The series of entries must end
with a separator period. See “I-O-CONTROL paragraph” on page 148.

FILE-CONTROL paragraph
The FILE-CONTROL paragraph associates each file in the COBOL program with
an external data set, and specifies file organization, access mode, and other
information.

The following formats are for the FILE-CONTROL paragraph:

v Sequential file entries
v Indexed file entries
v Relative file entries
v Line-sequential file entries

The table below lists the different type of files available to programs and methods.
Table 6. Types of files
File organization Access method
Sequential QSAM, VSAM1
Relative VSAM1
Indexed VSAM1
Line sequential2 Text stream I-O

1. VSAM does not support z/OS UNIX files.

2. Line-sequential support is limited to z/OS UNIX files.

The FILE-CONTROL paragraph begins with the word FILE-CONTROL followed

by a separator period. It must contain one and only one entry for each file
described in an FD or SD entry in the DATA DIVISION.

Within each entry, the SELECT clause must appear first. The other clauses can
appear in any order, except that the PASSWORD clause for indexed files, if
specified, must immediately follow the RECORD KEY or ALTERNATE RECORD
KEY data-name with which it is associated.

The name component of assignment-name-1 cannot contain an underscore.

130 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 1: sequential-file-control-entry

►► SELECT file-name-1 ASSIGN ▼ assignment-name-1 ►

OPTIONAL TO

► ►
RESERVE integer SEQUENTIAL
AREA ORGANIZATION
AREAS IS

► ►
PADDING data-name-5
CHARACTER IS literal-2

► ►
RECORD DELIMITER STANDARD-1 ACCESS SEQUENTIAL
IS assignment-name-2 MODE IS

► ►
PASSWORD data-name-6 STATUS data-name-1
IS FILE IS data-name-8

► . ►◄

Chapter 15. Input-Output section 131

 Format 2: indexed-file-control-entry

►► SELECT file-name-1 ASSIGN ▼ assignment-name-1 ►

OPTIONAL TO

► INDEXED ►
RESERVE integer ORGANIZATION
AREA IS
AREAS

► RECORD data-name-2 ►
ACCESS SEQUENTIAL KEY IS
MODE IS RANDOM
DYNAMIC

► ▼ ►
PASSWORD data-name-6 entry 1
IS

► . ►◄
STATUS data-name-1
FILE IS data-name-8

entry 1:

ALTERNATE data-name-3 ►
RECORD KEY IS DUPLICATES
WITH

►
PASSWORD data-name-7
IS

132 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 3: relative-file-control-entry

►► SELECT file-name-1 ASSIGN ▼ assignment-name-1 ►

OPTIONAL TO

► RELATIVE ►
RESERVE integer ORGANIZATION
AREA IS
AREAS

► ►
ACCESS SEQUENTIAL
MODE IS RELATIVE data-name-4
KEY IS
RANDOM RELATIVE data-name-4
DYNAMIC KEY IS

► ►
PASSWORD data-name-6 STATUS data-name-1
IS FILE IS data-name-8

► . ►◄

Format 4: line-sequential-file-control-entry

►► SELECT file-name-1 ASSIGN ▼ assignment-name-1 ►

OPTIONAL TO

► LINE SEQUENTIAL ►
ORGANIZATION ACCESS SEQUENTIAL
IS MODE IS

► . ►◄
STATUS data-name-1
FILE IS

Chapter 15. Input-Output section 133

SELECT clause
The SELECT clause identifies a file in the COBOL program to be associated with
an external data set.
SELECT OPTIONAL
Can be specified only for files opened in the input, I-O, or extend mode.
You must specify SELECT OPTIONAL for those input files that are not
necessarily available each time the object program is executed. For more
information, see “OPEN statement notes” on page 406.
file-name-1
Must be identified by an FD or SD entry in the DATA DIVISION. A
file-name must conform to the rules for a COBOL user-defined name, must
contain at least one alphabetic character, and must be unique within this
program.

When file-name-1 specifies a sort or a merge file, only the ASSIGN clause can
follow the SELECT clause.

If the file connector referenced by file-name-1 is an external file connector, all

file-control entries in the run unit that reference this file connector must have the
same specification for the OPTIONAL phrase.

ASSIGN clause
The ASSIGN clause associates the name of a file in a program with the actual
external name of the data file.
assignment-name-1
Identifies the external data file. It can be specified as a name or as an
alphanumeric literal.
assignment-name-1 is not the name of a data item, and assignment-name-1
cannot be contained in a data item. It is just a character string. It cannot
contain an underscore character.
Any assignment-name after the first is syntax checked, but has no effect on
the execution of the program.
assignment-name-1 has the following formats:

Format: assignment-name for QSAM files

►► name ►◄
label- S-

134 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format: assignment-name for VSAM sequential file

►► AS- name ►◄
label-

Format: assignment-name for line-sequential, VSAM indexed, or VSAM

relative file

►► name ►◄
label-

label- Documents (for the programmer) the device and device class to which a
file is assigned. It must end in a hyphen; the specified value is not
otherwise checked. It has no effect on the execution of the program. If
specified, it must end with a hyphen.
S- For QSAM files, the S- (organization) field can be omitted.
AS- For VSAM sequential files, the AS- (organization) field must be specified.
For VSAM indexed and relative files, the organization field must be
omitted.
name A required field that specifies the external name for this file.
It must be either the name specified in the DD statement for this file or the
name of an environment variable that contains file allocation information.
For details on specifying an environment variable, see “Assignment name
for environment variable” on page 136.
name must conform to the following rules of formation:
v If assignment-name-1 is a user-defined word:
– The name can contain from one to eight characters.
– The name can contain the characters A-Z, a-z, and 0-9.
– The leading character must be alphabetic.
– The name cannot contain an underscore.
v If assignment-name-1 is a literal:
– The name can contain from one to eight characters.
– The name can contain the characters A-Z, a-z, 0-9, @, #, and $.
– The leading character must be alphabetic.
– The name cannot contain an underscore.
For both user-defined words and literals, the compiler folds name to
uppercase to form the ddname for the file.
In a sort or merge file, name is treated as a comment.

If the file connector referenced by file-name-1 in the SELECT clause is an external

file connector, all file-control entries in the run unit that reference this file
connector must have a consistent specification for assignment-name-1 in the ASSIGN

Chapter 15. Input-Output section 135

 clause. For QSAM files and VSAM indexed and relative files, the name specified
on the first assignment-name-1 must be identical. For VSAM sequential files, it must
be specified as AS-name.

Assignment name for environment variable

The name component of assignment-name-1 is initially treated as a ddname. If no file

has been allocated using this ddname, then name is treated as an environment
variable.

The environment variable name must be defined using only uppercase because the
COBOL compiler automatically folds the external file-name to uppercase.

If this environment variable exists and contains a valid PATH or DSN option
(described below), then the file is dynamically allocated using the information
supplied by that option.

If the environment variable does not contain a valid PATH or DSN option or if the
dynamic allocation fails, then attempting to open the file results in file status 98.

The contents of the environment variable are checked at each OPEN statement. If a
file was dynamically allocated by a previous OPEN statement and the contents of
the environment variable have changed since the previous OPEN, then the
previous allocation is dynamically deallocated prior to dynamically reallocating the
file using the options currently set in the environment variable.

When the run unit terminates, the COBOL runtime system automatically
deallocates all automatically generated dynamic allocations.

Environment variable contents for a QSAM file

For a QSAM file, the environment variable must contain either a DSN or a PATH
option in the format shown below.

Format: environment variable for QSAM files, DSN option

►► DSN(data-set-name ) ►
(member-name) NEW TRACKS
OLD CYL
SHR
MOD

► ►
SPACE(nnn,mmmm) VOL(volume-serial) UNIT(type)

► ►
KEEP STORCLAS(storage-class)
DELETE
CATALOG
UNCATALOG

► ►◄
MGMTCLAS(management-class) DATACLAS(data-class)

136 Enterprise COBOL for z/OS, V6.1 Language Reference

data-set-name must be fully qualified. The data set must not be a temporary data
set; that is, it must not start with an ampersand.

After data-set-name or member-name, the data set attributes can follow in any order.

The options that follow DSN (such as NEW or TRACKS) must be separated by a
comma or by one or more blanks.

Blanks at the beginning and end of the environment variable contents are ignored.
You must not code blanks within the parentheses or between a keyword and the
left parenthesis that immediately follows the keyword.

COBOL does not provide a default for data set disposition (NEW, OLD, SHR, or
MOD); however, your operating system might provide one. To avoid unexpected
results when opening the file, you should always specify NEW, OLD, SHR, or
MOD with the DSN option when you use environment variables for dynamic
allocation of QSAM files.

For information about specifying the values of the data set attributes, see the
description of the DD statement in the z/OS MVS JCL Reference.

Format: environment variable for QSAM files, PATH option

►► PATH(path-name) ►◄

path-name must be an absolute path name; that is, it must begin with a slash. For
more information about specifying path-name, see the description of the PATH
parameter in z/OS MVS JCL Reference.

Blanks at the beginning and end of the environment variable contents are ignored.
You must not code blanks within the parentheses or between a keyword and the
left parenthesis that immediately follows the keyword.

Environment variable contents for a line-sequential file

For a line-sequential file, the environment variable must contain a PATH option in
the following format:

Format: environment variable for line-sequential files

►► PATH(path-name) ►◄

path-name must be an absolute path name; that is, it must begin with a slash. For
more information about specifying path-name, see the description of the PATH
parameter in z/OS MVS JCL Reference.

Chapter 15. Input-Output section 137

 Blanks at the beginning and end of the environment variable contents are ignored.
You must not code blanks within the parentheses or between a keyword and the
left parenthesis that immediately follows the keyword.

Environment variable contents for a VSAM file

For an indexed, relative, or sequential VSAM file, the environment variable must
contain a DSN option in the following format:

Format: environment variable for VSAM files, DSN option

►► DSN(data-set-name) ►◄
OLD
SHR

data-set-name specifies the data set name for the base cluster. data-set-name must be
fully qualified and must reference an existing predefined and cataloged VSAM
data set.

If an indexed file has alternate indexes, then additional environment variables

must be defined that contain DSN options (as above) for each of the alternate
index paths. The names of these environment variables must follow the same
naming convention as used for alternate index ddnames. That is:
v The environment variable name for each alternate index path is formed by
concatenating the base cluster environment variable name with an integer,
beginning with 1 for the path associated with the first alternate index and
incrementing by 1 for the path associated with each successive alternate index.
(For example, if the environment variable name for the base cluster is CUST,
then the environment variable names for the alternate indexes would be CUST1,
CUST2, ..., .)
v If the length of the base cluster environment variable name is already eight
characters, then the environment variable names for the alternate indexes are
formed by truncating the base cluster portion of the environment variable name
on the right to reduce the concatenated result to eight characters. (For example,
if the environment variable name for the base cluster is DATAFILE, then the
environment variable names for the alternate clusters would be DATAFIL1,
DATAFIL2, ..., .)

The options that follow DSN (such as SHR) must be separated by a comma or by
one or more blanks.

Blanks at the beginning and end of the environment variable contents are ignored.
You must not code blanks within the parentheses or between a keyword and the
left parenthesis that immediately follows the keyword.

COBOL does not provide a default for data set disposition (OLD or SHR);
however, your operating system might provide one. To avoid unexpected results
when opening the file, you should always specify OLD or SHR with the DSN
option when you use environment variables for dynamic allocation of VSAM files.

138 Enterprise COBOL for z/OS, V6.1 Language Reference

RESERVE clause
The RESERVE clause allows the user to specify the number of input/output
buffers to be allocated at run time for the files.

The RESERVE clause is not supported for line-sequential files.

If the RESERVE clause is omitted, the number of buffers at run time is taken from
the DD statement. If none is specified, the system default is taken.

If the file connector referenced by file-name-1 in the SELECT clause is an external

file connector, all file-control entries in the run unit that reference this file
connector must have the same value for the integer specified in the RESERVE
clause.

ORGANIZATION clause
The ORGANIZATION clause identifies the logical structure of the file. The logical
structure is established at the time the file is created and cannot subsequently be
changed.

You can find a discussion of the different ways in which data can be organized
and of the different access methods that you can use to retrieve the data under
“File organization and access modes” on page 143.
ORGANIZATION IS SEQUENTIAL (format 1)
A predecessor-successor relationship among the records in the file is
established by the order in which records are placed in the file when it is
created or extended.
ORGANIZATION IS INDEXED (format 2)
The position of each logical record in the file is determined by indexes
created with the file and maintained by the system. The indexes are based
on embedded keys within the file's records.
ORGANIZATION IS RELATIVE (format 3)
The position of each logical record in the file is determined by its relative
record number.
ORGANIZATION IS LINE SEQUENTIAL (format 4)
A predecessor-successor relationship among the records in the file is
established by the order in which records are placed in the file when it is
created or extended. A record in a LINE SEQUENTIAL file can consist only
of printable characters.

If you omit the ORGANIZATION clause, the compiler assumes ORGANIZATION

IS SEQUENTIAL.

If the file connector referenced by file-name-1 in the SELECT clause is an external

file connector, the same organization must be specified for all file-control entries in
the run unit that reference this file connector.

File organization
You establish the organization of the data when you create a file. Once the file has
been created, you can expand the file, but you cannot change the organization.

Chapter 15. Input-Output section 139

 Sequential organization

The physical order in which the records are placed in the file determines the
sequence of records. The relationships among records in the file do not change,
except that the file can be extended. Records can be fixed length or variable length;
there are no keys.

Each record in the file except the first has a unique predecessor record; and each
record except the last has a unique successor record.

Indexed organization
Each record in the file has one or more embedded keys (referred to as key data
items); each key is associated with an index. An index provides a logical path to
the data records according to the contents of the associated embedded record key
data items. Indexed files must be direct-access storage files. Records can be fixed
length or variable length.

Each record in an indexed file must have an embedded prime key data item. When
records are inserted, updated, or deleted, they are identified solely by the values of
their prime keys. Thus, the value in each prime key data item must be unique and
must not be changed when the record is updated. You tell COBOL the name of the
prime key data item in the RECORD KEY clause of the file-control paragraph.

In addition, each record in an indexed file can contain one or more embedded
alternate key data items. Each alternate key provides another means of identifying
which record to retrieve. You tell COBOL the name of any alternate key data items
on the ALTERNATE RECORD KEY clause of the file-control paragraph.

The key used for any specific input-output request is known as the key of reference.

Relative organization

Think of the file as a string of record areas, each of which contains a single record.
Each record area is identified by a relative record number; the access method stores
and retrieves a record based on its relative record number. For example, the first
record area is addressed by relative record number 1 and the 10th is addressed by
relative record number 10. The physical sequence in which the records were placed
in the file has no bearing on the record area in which they are stored, and thus no
effect on each record's relative record number. Relative files must be direct-access
files. Records can be fixed length or variable length.

Line-sequential organization

In a line-sequential file, each record contains a sequence of characters that ends

with a record delimiter. The delimiter is not counted in the length of the record.

When a record is written, any trailing blanks are removed prior to adding the
record delimiter. The characters in the record area from the first character up to
and including the added record delimiter constitute one record and are written to
the file.

When a record is read, characters are read one at a time into the record area until:
v The first record delimiter is encountered. The record delimiter is discarded and
the remainder of the record is filled with spaces.

140 Enterprise COBOL for z/OS, V6.1 Language Reference

 v The entire record area is filled with characters. If the first unread character is the
record delimiter, it is discarded. Otherwise, the first unread character becomes
the first character read by the next READ statement.
v End-of-file is encountered. The remainder of the record area is filled with spaces.

Records written to line-sequential files must consist of data items described as

USAGE DISPLAY or DISPLAY-1 or a combination of DISPLAY and DISPLAY-1
items. A zoned decimal data item either must be unsigned or, if signed, must be
declared with the SEPARATE CHARACTER phrase.

A line-sequential file can contain printable characters and control characters. Be

aware though that if your file contains a newline character (X'15'), the newline
character will function as a record delimiter.

The following clauses are not supported for line-sequential files:

v APPLY WRITE-ONLY clause
v CODE-SET clause
v DATA RECORDS clause
v LABEL RECORDS clause
v LINAGE clause
v I-O phrase of the OPEN statement
v PADDING CHARACTER clause
v RECORD CONTAINS 0 clause
v RECORD CONTAINS clause format 2 (for example: RECORD CONTAINS 100 to
200 CHARACTERS)
v RECORD DELIMITER clause
v RECORDING MODE clause
v RERUN clause
v RESERVE clause
v REVERSED phrase of the OPEN statement
v REWRITE statement
v VALUE OF clause of file description entry
v WRITE ... AFTER ADVANCING mnemonic-name
v WRITE ... AT END-OF-PAGE
v WRITE ... BEFORE ADVANCING

PADDING CHARACTER clause

The PADDING CHARACTER clause specifies a character to be used for block
padding on sequential files.
data-name-5
Must be defined in the DATA DIVISION as a one-character data item of
category alphabetic, alphanumeric, or national, and must not be defined in
the FILE SECTION. data-name-5 can be qualified.
literal-2
Must be a one-character alphanumeric literal or national literal.

For external files, data-name-5, if specified, must reference an external data item.

Chapter 15. Input-Output section 141

 The PADDING CHARACTER clause is syntax checked, but has no effect on the
execution of the program.

RECORD DELIMITER clause

The RECORD DELIMITER clause indicates the method of determining the length
of a variable-length record on an external medium. It can be specified only for
variable-length records.
STANDARD-1
If STANDARD-1 is specified, the external medium must be a magnetic tape
file.
assignment-name-2
Can be any COBOL word.

The RECORD DELIMITER clause is syntax checked, but has no effect on the
execution of the program.

ACCESS MODE clause

The ACCESS MODE clause defines the manner in which the records of the file are
made available for processing. If the ACCESS MODE clause is not specified,
sequential access is assumed.

For sequentially accessed relative files, the ACCESS MODE clause does not have to
precede the RELATIVE KEY clause.
ACCESS MODE IS SEQUENTIAL
Can be specified in all formats.
Format 1: sequential
Records in the file are accessed in the sequence established when
the file is created or extended. Format 1 supports only sequential
access.
Format 2: indexed
Records in the file are accessed in the sequence of ascending record
key values according to the collating sequence of the file.
Format 3: relative
Records in the file are accessed in the ascending sequence of
relative record numbers of existing records in the file.
Format 4: line-sequential
Records in the file are accessed in the sequence established when
the file is created or extended. Format 4 supports only sequential
access.
ACCESS MODE IS RANDOM
Can be specified in formats 2 and 3 only.
Format 2: indexed
The value placed in a record key data item specifies the record to
be accessed.
Format 3: relative
The value placed in a relative key data item specifies the record to
be accessed.

142 Enterprise COBOL for z/OS, V6.1 Language Reference

 ACCESS MODE IS DYNAMIC
Can be specified in formats 2 and 3 only.
Format 2: indexed
Records in the file can be accessed sequentially or randomly,
depending on the form of the specific input-output statement used.
Format 3: relative
Records in the file can be accessed sequentially or randomly,
depending on the form of the specific input-output request.

File organization and access modes

File organization is the permanent logical structure of the file. You tell the computer
how to retrieve records from the file by specifying the access mode (sequential,
random, or dynamic).

For details on the access methods and data organization, see Table 6 on page 130.

Sequentially organized data can be accessed only sequentially; however, data that
has indexed or relative organization can be accessed in any of the three access
modes.

Access modes
See the descriptions of the following types of access modes.
Sequential-access mode
Allows reading and writing records of a file in a serial manner; the order
of reference is implicitly determined by the position of a record in the file.
Random-access mode
Allows reading and writing records in a programmer-specified manner; the
control of successive references to the file is expressed by specifically
defined keys supplied by the user.
Dynamic-access mode
Allows the specific input-output statement to determine the access mode.
Therefore, records can be processed sequentially or randomly or both.

For external files, every file-control entry in the run unit that is associated with
that external file must specify the same access mode. In addition, for relative file
entries, data-name-4 must reference an external data item, and the RELATIVE KEY
phrase in each associated file-control entry must reference that same external data
item.

Relationship between data organizations and access modes

This section discusses which access modes are valid for each type of data
organization.
Sequential files
Files with sequential organization can be accessed only sequentially. The
sequence in which records are accessed is the order in which the records
were originally written.
Line-sequential files
Same as for sequential files (described above).
Indexed files
All three access modes are allowed.

Chapter 15. Input-Output section 143

 In the sequential access mode, the sequence in which records are accessed
is the ascending order of the record key value. The order of retrieval
within a set of records that have duplicate alternate record key values is
the order in which records were written into the set.
In the random access mode, you control the sequence in which records are
accessed. A specific record is accessed by placing the value of its key or
keys in the RECORD KEY data item (and the ALTERNATE RECORD KEY
data item). If a set of records has duplicate alternate record key values,
only the first record written is available.
In the dynamic access mode, you can change as needed from sequential
access to random access by using appropriate forms of input-output
statements.
Relative files
All three access modes are allowed.
In the sequential access mode, the sequence in which records are accessed
is the ascending order of the relative record numbers of all records that
exist within the file.
In the random access mode, you control the sequence in which records are
accessed. A specific record is accessed by placing its relative record number
in the RELATIVE KEY data item; the RELATIVE KEY must not be defined
within the record description entry for the file.
In the dynamic access mode, you can change as needed from sequential
access to random access by using appropriate forms of input-output
statements.

RECORD KEY clause

The RECORD KEY clause (format 2) specifies the data item within the record that
is the prime RECORD KEY for an indexed file. The values contained in the prime
RECORD KEY data item must be unique among records in the file.
data-name-2
The prime RECORD KEY data item.
data-name-2 must be described within a record description entry associated
with the file. The key can have any of the following data categories:
v Alphanumeric
v Numeric
v Numeric-edited (with usage DISPLAY or NATIONAL)
v Alphanumeric-edited
v Alphabetic
v External floating-point (with usage DISPLAY or NATIONAL)
v Internal floating-point
v DBCS
v National
v National-edited
Regardless of the category of the key data item, the key is treated as an
alphanumeric item. The collation order of the key is determined by the
item's binary value order when the key is used for locating a record or for
setting the file position indicator associated with the file.

144 Enterprise COBOL for z/OS, V6.1 Language Reference

 data-name-2 must not reference a variable-length data item. data-name-2 can
be qualified.
If the indexed file contains variable-length records, data-name-2 need not be
contained within the minimum record size specified for the file. That is,
data-name-2 can exceed the minimum record size, but this is not
recommended.
The data description of data-name-2 and its relative location within the
record must be the same as those used when the file was defined.
If the file has more than one record description entry, data-name-2 need be
described in only one of those record description entries. The identical
character positions referenced by data-name-2 in any one record description
entry are implicitly referenced as keys for all other record description
entries for that file.
For files defined with the EXTERNAL clause, all file description entries in
the run unit that are associated with the file must have data description
entries for data-name-2 that specify the same relative location in the record
and the same length.

ALTERNATE RECORD KEY clause

The ALTERNATE RECORD KEY clause (format 2) specifies a data item within the
record that provides an alternative path to the data in an indexed file.
data-name-3
An ALTERNATE RECORD KEY data item.
data-name-3 must be described within a record description entry associated
with the file. The key can have any of the following data categories:
v Alphanumeric
v Numeric
v Numeric-edited (with usage DISPLAY or NATIONAL)
v Alphanumeric-edited
v Alphabetic
v External floating-point (with usage DISPLAY or NATIONAL)
v Internal floating-point
v DBCS
v National
v National-edited
Regardless of the category of the key data item, the key is treated as an
alphanumeric item. The collation order of the key is determined by the
item's binary value order when the key is used for locating a record or for
setting the file position indicator associated with the file.
data-name-3 must not reference a group item that contains a
variable-occurrence data item. data-name-3 can be qualified.
If the indexed file contains variable-length records, data-name-3 need not be
contained within the minimum record size specified for the file. That is,
data-name-3 can exceed the minimum record size, but this is not
recommended.

Chapter 15. Input-Output section 145

 If the indexed file contains variable-length records, data-name-3 need not be
contained within the minimum record size specified for the file. That is,
data-name-3 can exceed the minimum record size, but this is not
recommended.
The data description of data-name-3 and its relative location within the
record must be the same as those used when the file was defined. The
number of alternate record keys for the file must also be the same as that
used when the file was created.
The leftmost character position of data-name-3 must not be the same as the
leftmost character position of the prime record key, or of another alternate
record key.

If the DUPLICATES phrase is not specified, the values contained in the

ALTERNATE RECORD KEY data item must be unique among records in the file.

If the DUPLICATES phrase is specified, the values contained in the ALTERNATE

RECORD KEY data item can be duplicated within any records in the file. In
sequential access, the records with duplicate keys are retrieved in the order in
which they were placed in the file. In random access, only the first record written
in a series of records with duplicate keys can be retrieved.

For files defined with the EXTERNAL clause, all file description entries in the run
unit that are associated with the file must have data description entries for
data-name-3 that specify the same relative location in the record and the same
length. The file description entries must specify the same number of alternate
record keys and the same DUPLICATES phrase.

RELATIVE KEY clause

The RELATIVE KEY clause (format 3) identifies a data-name that specifies the
relative record number for a specific logical record within a relative file.
data-name-4
Must be defined as an unsigned integer data item whose description does
not contain the PICTURE symbol P. data-name-4 must not be defined in a
record description entry associated with this relative file. That is, the
RELATIVE KEY is not part of the record. data-name-4 can be qualified.
data-name-4 is required for ACCESS IS SEQUENTIAL only when the START
statement is to be used. It is always required for ACCESS IS RANDOM
and ACCESS IS DYNAMIC. When the START statement is executed, the
system uses the contents of the RELATIVE KEY data item to determine the
record at which sequential processing is to begin.
If a value is placed in data-name-4, and a START statement is not executed,
the value is ignored and processing begins with the first record in the file.
If a relative file is to be referenced by a START statement, you must specify
the RELATIVE KEY clause for that file.
For external files, data-name-4 must reference an external data item, and the
RELATIVE KEY phrase in each associated file-control entry must reference
that same external data item in each case.
The ACCESS MODE IS RANDOM clause must not be specified for
file-names specified in the USING or GIVING phrase of a SORT or MERGE
statement.

146 Enterprise COBOL for z/OS, V6.1 Language Reference

PASSWORD clause
The PASSWORD clause controls access to files.
data-name-6 , data-name-7
Password data items. Each must be defined in the WORKING-STORAGE
SECTION of the DATA DIVISION as a data item of category alphabetic,
alphanumeric, or alphanumeric-edited. The first eight characters are used
as the password; a shorter field is padded with blanks to eight characters.
Each password data item must be equivalent to one that is externally
defined.

When the PASSWORD clause is specified, at object time the PASSWORD data item
must contain a valid password for this file before the file can be successfully
opened.

Format 1 considerations:

The PASSWORD clause is not valid for QSAM sequential files.

Format 2 and 3 considerations:

The PASSWORD clause, if specified, must immediately follow the RECORD KEY
or ALTERNATE RECORD KEY data-name with which it is associated.

For indexed files that have been completely predefined to VSAM, only the
PASSWORD data item for the RECORD KEY need contain the valid password
before the file can be successfully opened at file creation time.

For any other type of file processing (including the processing of dynamic calls at
file creation time through a COBOL runtime subroutine), every PASSWORD data
item for the file must contain a valid password before the file can be successfully
opened, regardless of whether all paths to the data are used in this object program.

For external files, data-name-6 and data-name-7 must reference external data items.
The PASSWORD clauses in each associated file-control entry must reference the
same external data items.

FILE STATUS clause

The FILE STATUS clause monitors the execution of each input-output operation for
the file.

When the FILE STATUS clause is specified, the system moves a value into the file
status key data item after each input-output operation that explicitly or implicitly
refers to this file. The value indicates the status of execution of the statement. (See
the file status key description under “Common processing facilities” on page 295.)
data-name-1
The file status key data item can be defined in the WORKING-STORAGE,
LOCAL-STORAGE, or LINKAGE SECTION as one of the following items:
v A two-character data item of category alphanumeric
v A two-character data item of category national
v A two-digit data item of category numeric with usage DISPLAY or
NATIONAL (an external decimal data item)
data-name-1 must not contain the PICTURE symbol 'P'.
Chapter 15. Input-Output section 147
 data-name-1 can be qualified.
The file status key data item must not be variably located; that is, the data
item cannot follow a data item that contains an OCCURS DEPENDING
ON clause.
data-name-8
Must be defined as an alphanumeric group item of 6 bytes in the
WORKING-STORAGE SECTION or LINKAGE SECTION of the DATA
DIVISION.
Specify data-name-8 only if the file is a VSAM file (that is, ESDS, KSDS,
RRDS).
data-name-8 holds the 6-byte VSAM return code, which is composed as
follows:
v The first 2 bytes of data-name-8 contain the VSAM return code in binary
format. The value for this code is defined (by VSAM) as 0, 8, or 12.
v The next 2 bytes of data-name-8 contain the VSAM function code in binary
format. The value for this code is defined (by VSAM) as 0, 1, 2, 3, 4, or
5.
v The last 2 bytes of data-name-8 contain the VSAM feedback code in binary
format. The code value is 0 through 255.
If VSAM returns a nonzero return code, data-name-8 is set.
If FILE STATUS is returned without having called VSAM, data-name-8 is
zero.
If data-name-1 is set to zero, the content of data-name-8 is undefined. VSAM
status return code information is available without transformation in the
currently defined COBOL FILE STATUS code. User identification and
handling of exception conditions are allowed at the same level as that
defined by VSAM.
Function code and feedback code are set if and only if the return code is set to
a nonzero value. If they are referenced when the return code is set to zero,
the contents of the fields are not dependable.
Values in the return code, function code, and feedback code fields are defined
by VSAM. There are no COBOL additions, deletions, or modifications to
the VSAM definitions.
For more information, see DFSMS Macro Instructions for Data Sets.

I-O-CONTROL paragraph
The I-O-CONTROL paragraph of the input-output section specifies when
checkpoints are to be taken and the storage areas to be shared by different files.
This paragraph is optional in a COBOL program.

The keyword I-O-CONTROL can appear only once, at the beginning of the
paragraph. The word I-O-CONTROL must begin in Area A and must be followed
by a separator period.

The order in which I-O-CONTROL paragraph clauses are written is not significant.
The I-O-CONTROL paragraph ends with a separator period.

148 Enterprise COBOL for z/OS, V6.1 Language Reference

Format: QSAM- i-o-control-entry

►► RERUN assignment-name-1 phrase 1 ►◄

ON file-name-1 EVERY
SAME file-name-3
RECORD AREA FOR

▼ file-name-4

(1)
MULTIPLE FILE ▼ file-name-5
TAPE CONTAINS POSITION integer-2

(1)
APPLY WRITE-ONLY ▼ file-name-2
ON

phrase 1:

integer-1 RECORDS file-name-1

END REEL OF
OF UNIT

Notes:
1 The MULTIPLE FILE clause and APPLY WRITE-ONLY clause are not supported for VSAM files.

Format: VSAM- i-o-control-entry

►► RERUN assignment-name-1 phrase 1 ►◄

ON file-name-1 EVERY
SAME file-name-3
RECORD AREA FOR

▼ file-name-4

phrase 1:

integer-1 RECORDS file-name-1

OF

Chapter 15. Input-Output section 149

 Format: line-sequential-i-o-control-entry

►► SAME file-name-3 ▼ file-name-4 ►◄

RECORD AREA FOR

Format: sort/merge-i-o-control-entry

►► ►
RERUN assignment-name-1
ON

► ▼ SAME RECORD phrase 1 ►◄

SORT AREA FOR
SORT-MERGE

phrase 1:

file-name-3

▼
file-name-4

RERUN clause
The RERUN clause specifies that checkpoint records are to be taken. Subject to the
restrictions given with each phrase, more than one RERUN clause can be specified.

For information regarding the checkpoint data set definition and the checkpoint
method required for complete compliance to the 85 COBOL Standard, see DD
statements for defining checkpoint data sets in the Enterprise COBOL Programming
Guide.

Do not use the RERUN clause:

v For files described with the EXTERNAL clause
v In programs with the RECURSIVE clause specified
v In programs compiled with the THREAD option
v In methods
file-name-1
Must be a sequentially organized file.
VSAM and QSAM considerations:

150 Enterprise COBOL for z/OS, V6.1 Language Reference

 The file named in the RERUN clause must be a file defined in the same
program as the I-O-CONTROL paragraph, even if the file is defined as
GLOBAL.
assignment-name-1
The external data set for the checkpoint file. It must not be the same
assignment-name as that specified in any ASSIGN clause throughout the
entire program, including contained and containing programs.
For QSAM files, assignment-name-1 has the format:

Format: assignment-name for QSAM files

►► name ►◄
label- S-

The QSAM file must reside on a tape or direct access device. See also
Appendix G, “ASCII considerations,” on page 639.
SORT/MERGE considerations:
When the RERUN clause is specified in the I-O-CONTROL paragraph,
checkpoint records are written at logical intervals determined by the
sort/merge program during execution of each SORT or MERGE statement
in the program. When the RERUN clause is omitted, checkpoint records
are not written.
There can be only one SORT/MERGE I-O-CONTROL paragraph in a
program, and it cannot be specified in contained programs. It will have a
global effect on all SORT and MERGE statements in the program unit.
EVERY integer-1 RECORDS
A checkpoint record is to be written for every integer-1 records in
file-name-1 that are processed.
When multiple integer-1 RECORDS phrases are specified, no two of them
can specify the same value for file-name-1.
If you specify the integer-1 RECORDS phrase, you must specify
assignment-name-1.
EVERY END OF REEL/UNIT
A checkpoint record is to be written whenever end-of-volume for
file-name-1 occurs. The terms REEL and UNIT are interchangeable.
When multiple END OF REEL/UNIT phrases are specified, no two of
them can specify the same value for file-name-1.
The END OF REEL/UNIT phrase can be specified only if file-name-1 is a
sequentially organized file.

SAME AREA clause

The SAME AREA clause is syntax checked, but has no effect on the execution of
the program.The SAME AREA clause specifies that two or more files that do not
represent sort or merge files are to use the same main storage area during
processing.

Chapter 15. Input-Output section 151

 The files named in a SAME AREA clause need not have the same organization or
access.
file-name-3 , file-name-4
Must be specified in the file-control paragraph of the same program.
file-name-3 and file-name-4 must not reference a file that is defined with the
EXTERNAL clause.
v For QSAM files, the SAME clause is treated as documentation.
v For VSAM files, the SAME clause is treated as if equivalent to the SAME
RECORD AREA clause.

More than one SAME AREA clause can be included in a program. However:
v A specific file-name must not appear in more than one SAME AREA clause.
v If one or more file-names of a SAME AREA clause appear in a SAME RECORD
AREA clause, all the file-names in that SAME AREA clause must appear in that
SAME RECORD AREA clause. However, the SAME RECORD AREA clause can
contain additional file-names that do not appear in the SAME AREA clause.
v The rule that in the SAME AREA clause only one file can be open at one time
takes precedence over the SAME RECORD AREA rule that all the files can be
open at the same time.

SAME RECORD AREA clause

The SAME RECORD AREA clause specifies that two or more files are to use the
same main storage area for processing the current logical record.

The files named in a SAME RECORD AREA clause need not have the same
organization or access.
file-name-3 , file-name-4
Must be specified in the file-control paragraph of the same program.
file-name-3 and file-name-4 must not reference a file that is defined with the
EXTERNAL clause.

All of the files can be opened at the same time. A logical record in the shared
storage area is considered to be both of the following ones:
v A logical record of each opened output file in the SAME RECORD AREA clause
v A logical record of the most recently read input file in the SAME RECORD
AREA clause

More than one SAME RECORD AREA clause can be included in a program.
However:
v A specific file-name must not appear in more than one SAME RECORD AREA
clause.
v If one or more file-names of a SAME AREA clause appear in a SAME RECORD
AREA clause, all the file-names in that SAME AREA clause must appear in that
SAME RECORD AREA clause. However, the SAME RECORD AREA clause can
contain additional file-names that do not appear in the SAME AREA clause.
v The rule that in the SAME AREA clause only one file can be open at one time
takes precedence over the SAME RECORD AREA rule that all the files can be
open at the same time.
v If the SAME RECORD AREA clause is specified for several files, the record
description entries or the file description entries for these files must not include
the GLOBAL clause.

152 Enterprise COBOL for z/OS, V6.1 Language Reference

 v The SAME RECORD AREA clause must not be specified when the RECORD
CONTAINS 0 CHARACTERS clause is specified.

The files named in the SAME RECORD AREA clause need not have the same
organization or access.

SAME SORT AREA clause

The SAME SORT AREA clause is syntax checked but has no effect on the execution
of the program.
file-name-3 , file-name-4
Must be specified in the file-control paragraph of the same program.
file-name-3 and file-name-4 must not reference a file that is defined with the
EXTERNAL clause.

When the SAME SORT AREA clause is specified, at least one file-name specified
must name a sort file. Files that are not sort files can also be specified. The
following rules apply:
v More than one SAME SORT AREA clause can be specified. However, a given
sort file must not be named in more than one such clause.
v If a file that is not a sort file is named in both a SAME AREA clause and in one
or more SAME SORT AREA clauses, all the files in the SAME AREA clause must
also appear in that SAME SORT AREA clause.
v Files named in a SAME SORT AREA clause need not have the same organization
or access.
v Files named in a SAME SORT AREA clause that are not sort files do not share
storage with each other unless they are named in a SAME AREA or SAME
RECORD AREA clause.
v During the execution of a SORT or MERGE statement that refers to a sort or
merge file named in this clause, any nonsort or nonmerge files associated with
file-names named in this clause must not be in the open mode.

SAME SORT-MERGE AREA clause

The SAME SORT-MERGE AREA clause is equivalent to the SAME SORT AREA
clause.

For more details, see “SAME SORT AREA clause.”

MULTIPLE FILE TAPE clause

The MULTIPLE FILE TAPE clause (format 1) specifies that two or more files share
the same physical reel of tape.

This clause is syntax checked, but has no effect on the execution of the program.
The function is performed by the system through the LABEL parameter of the DD
statement.

APPLY WRITE-ONLY clause

The APPLY WRITE-ONLY clause optimizes buffer and device space allocation for
files that have standard sequential organization, have variable-length records, and
are blocked.

Chapter 15. Input-Output section 153

 If you specify this phrase, the buffer is truncated only when the space available in
the buffer is smaller than the size of the next record. Otherwise, the buffer is
truncated when the space remaining in the buffer is smaller than the maximum
record size for the file.

APPLY WRITE-ONLY is effective only for QSAM files.

file-name-2
Each file must have standard sequential organization.

APPLY WRITE-ONLY clauses must agree among corresponding external file

description entries. For an alternate method of achieving the APPLY WRITE-ONLY
results, see the description of the compiler option, AWO in the Enterprise COBOL
Programming Guide.

154 Enterprise COBOL for z/OS, V6.1 Language Reference

Part 5. Data division

© Copyright IBM Corp. 1991, 2017 155

156 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 16. DATA DIVISION overview
This overview describes the structure of the DATA DIVISION for programs, object
definitions, factory definitions, and methods.

Each section in the DATA DIVISION has a specific logical function within a
COBOL program, object definition, factory definition, or method and can be
omitted when that logical function is not needed. If included, the sections must be
written in the order shown. The DATA DIVISION is optional.
Program data division
The DATA DIVISION of a COBOL source program describes, in a
structured manner, all the data to be processed by the program.
Object data division
The object data division contains data description entries for instance object
data (instance data). Instance data is defined in the WORKING-STORAGE
SECTION of the object paragraph of a class definition.
Factory data division
The factory data division contains data description entries for factory object
data (factory data). Factory data is defined in the WORKING-STORAGE
SECTION of the factory paragraph of a class definition.
Method data division
A method data division contains data description entries for data accessible
within the method. A method data division can contain a
LOCAL-STORAGE SECTION or a WORKING-STORAGE SECTION, or
both. The term method data applies to both. Method data in
LOCAL-STORAGE is dynamically allocated and initialized on each
invocation of the method; method data in WORKING-STORAGE is static
and persists across invocations of the method.

© Copyright IBM Corp. 1991, 2017 157

 Format: program and method data division

►► DATA DIVISION. ►

► ►

FILE SECTION. ▼

file-description-entry ▼ record-description-entry

► ►

WORKING-STORAGE SECTION. ▼
record-description-entry
data-item-description-entry

► ►

LOCAL-STORAGE SECTION. ▼
record-description-entry
data-item-description-entry

► ►◄

LINKAGE SECTION. ▼
record-description-entry
data-item-description-entry

Format: object and factory data division

►► DATA DIVISION. ►◄

WORKING-STORAGE SECTION. ▼
record-description-entry
data-item-description-entry

FILE SECTION
The FILE SECTION defines the structure of data files. The FILE SECTION must
begin with the header FILE SECTION, followed by a separator period.
file-description-entry
Represents the highest level of organization in the FILE SECTION. It
provides information about the physical structure and identification of a
file, and gives the record-names associated with that file. For the format

158 Enterprise COBOL for z/OS, V6.1 Language Reference

 and the clauses required in a file description entry, see Chapter 17, “DATA
DIVISION--file description entries,” on page 173.
record-description-entry
A set of data description entries (described in Chapter 18, “DATA
DIVISION--data description entry,” on page 189) that describe the
particular records contained within a particular file.
A record in the FILE SECTION must be described as an alphanumeric
group item, a national group item, or an elementary data item of class
alphabetic, alphanumeric, DBCS, national, or numeric.
More than one record description entry can be specified; each is an
alternative description of the same record storage area.

Data areas described in the FILE SECTION are not available for processing unless
the file that contains the data area is open.

A method FILE SECTION can define external files only. A single run-unit-level file
connector is shared by all programs and methods that contain a definition of a
given external file.

WORKING-STORAGE SECTION
The WORKING-STORAGE SECTION describes data records that are not part of
data files but are developed and processed by a program or method. The
WORKING-STORAGE SECTION also describes data items whose values are
assigned in the source program or method and do not change during execution of
the object program.

The WORKING-STORAGE SECTION must begin with the section header

WORKING-STORAGE SECTION, followed by a separator period.
Program WORKING-STORAGE
The WORKING-STORAGE SECTION for programs (and methods) can also
describe external data records, which are shared by programs and methods
throughout the run unit. All clauses that are used in record descriptions in
the FILE SECTION and also the VALUE and EXTERNAL clauses (which
might not be specified in record description entries in the FILE SECTION)
can be used in record descriptions in the WORKING-STORAGE SECTION.
Method WORKING-STORAGE
A single copy of the WORKING-STORAGE for a method is statically
allocated on the first invocation of the method and persists in a last-used
state for the duration of the run unit. The same copy is used whenever the
method is invoked regardless of which object instance the method is
invoked upon.
If a VALUE clause is specified on a method WORKING-STORAGE data
item, the data item is initialized to the VALUE clause value on the first
invocation.
If the EXTERNAL clause is specified on a data description entry in a
method WORKING-STORAGE SECTION, a single copy of the storage for
that data item is allocated once for the duration of the run unit. That
storage is shared by all programs and methods in the run unit that contain
a definition for the external data item.
Object WORKING-STORAGE
The data described in the WORKING-STORAGE SECTION of an object

Chapter 16. DATA DIVISION overview 159

 paragraph is object instance data, usually called instance data. A separate
copy of instance data is statically allocated for each object instance when
the object is instantiated. Instance data persists in a last-used state until the
object instance is freed by the Java runtime system.
Instance data can be initialized by VALUE clauses specified in data
declarations or by logic specified in an instance method.
Factory WORKING-STORAGE
The data described in the WORKING-STORAGE SECTION of a factory
paragraph is factory data. A single copy of factory data is statically
allocated when the factory object for the class is created. Factory data
persists in a last-used state for the duration of the run unit.
Factory data can be initialized by VALUE clauses specified in data
declarations or by logic specified in a factory method.

The WORKING-STORAGE SECTION contains record description entries and data

description entries for independent data items, called data item description entries.
record-description-entry
Data entries in the WORKING-STORAGE SECTION that bear a definite
hierarchic relationship to one another must be grouped into records
structured by level number. See Chapter 18, “DATA DIVISION--data
description entry,” on page 189 for more information.
data-item-description-entry
Independent items in the WORKING-STORAGE SECTION that bear no
hierarchic relationship to one another need not be grouped into records
provided that they do not need to be further subdivided. Instead, they are
classified and defined as independent elementary items. Each is defined in
a separate data-item description entry that begins with either the level
number 77 or 01. See Chapter 18, “DATA DIVISION--data description
entry,” on page 189 for more information.

LOCAL-STORAGE SECTION
The LOCAL-STORAGE SECTION defines storage that is allocated and freed on a
per-invocation basis.

On each invocation, data items defined in the LOCAL-STORAGE SECTION are

reallocated. Each data item that has a VALUE clause is initialized to the value
specified in that clause.

For nested programs, data items defined in the LOCAL-STORAGE SECTION are
allocated upon each invocation of the containing outermost program. However,
each data item is reinitialized to the value specified in its VALUE clause each time
the nested program is invoked.

For methods, a separate copy of the data defined in LOCAL-STORAGE is allocated

and initialized on each invocation of the method. The storage allocated for the data
is freed when the method returns.

Data items defined in the LOCAL-STORAGE SECTION cannot specify the

EXTERNAL clause.

The LOCAL-STORAGE SECTION must begin with the header LOCAL-STORAGE

SECTION, followed by a separator period.

160 Enterprise COBOL for z/OS, V6.1 Language Reference

 You can specify the LOCAL-STORAGE SECTION in recursive programs, in
nonrecursive programs, and in methods.

Method LOCAL-STORAGE content is the same as program LOCAL-STORAGE

content except that the GLOBAL clause has no effect (because methods cannot be
nested).

LINKAGE SECTION
The LINKAGE SECTION describes data made available from another program or
method.
record-description-entry
See “WORKING-STORAGE SECTION” on page 159 for a description.
data-item-description-entry
See “WORKING-STORAGE SECTION” on page 159 for a description.

Record description entries and data item description entries in the LINKAGE
SECTION provide names and descriptions, but storage within the program or
method is not reserved because the data area exists elsewhere.

| Any data description clause, except for the EXTERNAL clause, can be used to
| describe items in the LINKAGE SECTION.

You can specify the GLOBAL clause in the LINKAGE SECTION. The GLOBAL
clause has no effect for methods, however.

Data units
Data is grouped into the conceptual units as listed in the topic.
v File data
v Program data
v Method data
v Factory data
v Instance data

File data
File data is contained in files. A file is a collection of data records that exist on
some input-output device. A file can be considered as a group of physical records;
it can also be considered as a group of logical records. The DATA DIVISION
describes the relationship between physical and logical records.

For more information, see “FILE SECTION” on page 178.

A physical record is a unit of data that is treated as an entity when moved into or
out of storage. The size of a physical record is determined by the particular
input-output device on which it is stored. The size does not necessarily have a
direct relationship to the size or content of the logical information contained in the
file.

A logical record is a unit of data whose subdivisions have a logical relationship. A

logical record can itself be a physical record (that is, be contained completely

Chapter 16. DATA DIVISION overview 161

 within one physical unit of data); several logical records can be contained within
one physical record, or one logical record can extend across several physical
records.

File description entries specify the physical aspects of the data (such as the size
relationship between physical and logical records, the size and names of the logical
records, labeling information, and so forth).

Record description entries describe the logical records in the file (including the
category and format of data within each field of the logical record), different values
the data might be assigned, and so forth.

After the relationship between physical and logical records has been established,
only logical records are made available to you. For this reason, a reference in this
information to "records" means logical records, unless the term "physical records" is
used.

Program data
Program data is created by a program instead of being read from a file.

The concept of logical records applies to program data as well as to file data.
Program data can thus be grouped into logical records, and be defined by a series
of record description entries. Items that need not be so grouped can be defined in
independent data description entries (called data item description entries).

Method data
Method data is defined in the DATA DIVISION of a method and is processed by
the procedural code in that method. Method data is organized into logical records
and independent data description entries in the same manner as program data.

Factory data
Factory data is defined in the DATA DIVISION in the factory paragraph of a class
definition and is processed by procedural code in the factory methods of that class.
Factory data is organized into logical records and independent data description
entries in the same manner as program data.

There is one factory object for a given class in a run unit, and therefore only one
instance of factory data in a run unit for that class.

Instance data
Instance data is defined in the DATA DIVISION in the object paragraph of a class
definition and is processed by procedural code in the instance methods of that
class. Instance data is organized into logical records and independent data
description entries in the same manner as program data.

There is one copy of instance data in each object instance of a given class. There
can be many object instances for a given class. Each has its own separate copy of
instance data.

Data relationships
The relationships among all data to be used in a program are defined in the DATA
DIVISION through a system of level indicators and level-numbers.

162 Enterprise COBOL for z/OS, V6.1 Language Reference

 A level indicator, with its descriptive entry, identifies each file in a program. Level
indicators represent the highest level of any data hierarchy with which they are
associated. FD is the file description level indicator and SD is the sort-merge file
description level indicator.

A level-number, with its descriptive entry, indicates the properties of specific data.
Level-numbers can be used to describe a data hierarchy; they can indicate that this
data has a special purpose. Although they can be associated with (and subordinate
to) level indicators, they can also be used independently to describe internal data
or data common to two or more programs. (See “Level-numbers” on page 190 for
level-number rules.)

Levels of data
After a record has been defined, it can be subdivided to provide more detailed
data references.

For example, in a customer file for a department store, one complete record could
contain all data that pertains to one customer. Subdivisions within that record
could be, for example, customer name, customer address, account number,
department number of sale, unit amount of sale, dollar amount of sale, previous
balance, and other pertinent information.

The basic subdivisions of a record (that is, those fields not further subdivided) are
called elementary items. Thus a record can be made up of a series of elementary
items or can itself be an elementary item.

It might be necessary to refer to a set of elementary items; thus, elementary items

can be combined into group items. Groups can also be combined into a more
inclusive group that contains one or more subgroups. Thus within one hierarchy of
data items, an elementary item can belong to more than one group item.

A system of level-numbers specifies the organization of elementary and group

items into records. Special level-numbers are also used to identify data items used
for special purposes.

Levels of data in a record description entry

Each group and elementary item in a record requires a separate entry, and each
must be assigned a level-number.

A level-number is a one-digit or two-digit integer between 01 and 49, or one of

three special level-numbers: 66, 77, or 88. The following level-numbers are used to
structure records:
01 This level-number specifies the record itself, and is the most inclusive
level-number possible. A level-01 entry can be an alphanumeric group
item, a national group item, or an elementary item. The level number must
begin in Area A.
02 through 49
These level-numbers specify group and elementary items within a record.
They can begin in Area A or Area B. Less inclusive data items are assigned
higher (not necessarily consecutive) level-numbers in this series.

The relationship between level-numbers within a group item defines the hierarchy
of data within that group.

Chapter 16. DATA DIVISION overview 163

 A group item includes all group and elementary items that follow it until a
level-number less than or equal to the level-number of that group is encountered.

The following figure illustrates a group wherein all groups immediately

subordinate to the level-01 entry have the same level-number.

The COBOL record description

entry written as follows: is subdivided as indicated below:

01 RECORD-ENTRY. This entry includes

05 GROUP-1. This entry includes

10 SUBGROUP-1. This entry includes

15 ELEM-1 PIC... .
15 ELEM-2 PIC... .

10 SUBGROUP-2.
This entry includes
15 ELEM-3 PIC... .
15 ELEM-4 PIC... .

05 GROUP-2.
This entry includes
15 SUBGROUP-3.
This entry includes
25 ELEM-5 PIC... .
25 ELEM-6 PIC... .

15 SUBGROUP-4 PIC... .

05 ELEM-7 PIC... . This entry includes itself.

This entry includes itself.

The storage arrangement of the record description entry is illustrated below:

RECORD ENTRY
GROUP 1 GROUP 2
SUBGROUP-1 SUBGROUP-2 SUBGROUP-3

ELEM-1 ELEM-2 ELEM-3 ELEM-4 ELEM-5 ELEM-6 SUBGROUP-4 ELEM-7

You can also define groups with subordinate items that have different
level-numbers for the same level in the hierarchy. For example, 05 EMPLOYEE-NAME
and 04 EMPLOYEE-ADDRESS in EMPLOYEE-RECORD below define the same level in the
hierarchy. The compiler renumbers the levels in a relative fashion, as shown in
MAP output.
01 EMPLOYEE-RECORD.
05 EMPLOYEE-NAME.
10 FIRST-NAME PICTURE X(10).
10 LAST-NAME PICTURE X(10).
04 EMPLOYEE-ADDRESS.
08 STREET PICTURE X(10).
08 CITY PICTURE X(10).

The following record description entry defines the same data hierarchy as the
preceding record description entry:
01 EMPLOYEE-RECORD.
02 EMPLOYEE-NAME.
03 FIRST-NAME PICTURE X(10).

164 Enterprise COBOL for z/OS, V6.1 Language Reference

 03 LAST-NAME PICTURE X(10).
02 EMPLOYEE-ADDRESS.
03 STREET PICTURE X(10).
03 CITY PICTURE X(10).

Elementary items can be specified at any level within the hierarchy.

Special level-numbers
Special level-numbers identify items that do not structure a record.

The special level-numbers are:

66 Identifies items that must contain a RENAMES clause; such items regroup
previously defined data items. (For details, see “RENAMES clause” on
page 224.)
77 Identifies data item description entries that are independent
WORKING-STORAGE, LOCAL-STORAGE, or LINKAGE SECTION items;
they are not subdivisions of other items and are not subdivided
themselves. Level-77 items must begin in Area A.
88 Identifies any condition-name entry that is associated with a particular
value of a conditional variable. (For details, see “VALUE clause” on page
241.)

Level-77 and level-01 entries in the WORKING-STORAGE, LOCAL-STORAGE, or

LINKAGE SECTION that are referenced in a program or method must be given
unique data-names because level-77 and level-01 entries cannot be qualified.
Subordinate data-names that are referenced in the program or method must be
either uniquely defined, or made unique through qualification. Unreferenced
data-names need not be uniquely defined.

Indentation
Successive data description entries can begin in the same column as preceding
entries, or can be indented.

Indentation is useful for documentation but does not affect the action of the
compiler.

Classes and categories of group items

Enterprise COBOL has two types of groups: alphanumeric groups and national
groups.

Groups that do not specify a GROUP-USAGE clause are alphanumeric groups. An

alphanumeric group has class and category alphanumeric and is treated as though
its usage were DISPLAY, regardless of the representation of the elementary data
items that are contained within the group. In many operations, such as moves and
compares, alphanumeric groups are treated as though they were elementary items
of category alphanumeric, except that no editing or conversion of data
representation takes place. In other operations, such as MOVE CORRESPONDING
and ADD CORRESPONDING, the subordinate data items are processed as
separate elementary items.

National groups are defined by a GROUP-USAGE clause with the NATIONAL

phrase at the group level. All subordinate data items must be explicitly or
implicitly described with usage NATIONAL, and subordinate groups must be
explicitly or implicitly described with GROUP-USAGE NATIONAL.
Chapter 16. DATA DIVISION overview 165
 Unless stated otherwise, a national group item is processed exactly as though it
were an elementary data item of usage national, class and category national,
described with PICTURE N(m), where m is the length of the group in national
character positions. Because national groups contain only national characters, data
is converted as necessary for moves and compares. The compiler ensures proper
truncation and padding. In other operations, such as MOVE CORRESPONDING
and ADD CORRESPONDING, the subordinate data items are processed as
separate elementary items. See “GROUP-USAGE clause” on page 194 for details.

The table below summarizes the classes and categories of group items.
Table 7. Classes and categories of group items
USAGE of
elementary
Category of items within a USAGE of a
Group description Class of group group group group
Without a Alphanumeric Alphanumeric Any Treated as
GROUP-USAGE (even though the DISPLAY
clause elementary items when usage is
in the group can relevant
have any
category)
With explicit or National National NATIONAL NATIONAL
implicit
GROUP-USAGE
clause

Classes and categories of data

Most data and all literals used in a COBOL program are divided into classes and
categories. Data classes are groupings of data categories. Data categories are
determined by the attributes of data description entries or function definitions.

For more information about data categories, see “Category descriptions” on page
168.

The following elementary data items do not have a class and category:
v Index data items
v Items described with USAGE POINTER, USAGE FUNCTION-POINTER, USAGE
PROCEDURE-POINTER, or USAGE OBJECT REFERENCE

All other types of elementary data items have a class and category as shown in
Table 8 on page 167.

A function references an elementary data item and belongs to the data class and
category associated with the type of the function, as shown in Table 9 on page 167.

Literals have a class and category as shown in Table 10 on page 167. Figurative
constants (except NULL) have a class and category that depends on the literal or
value represented by the figurative constant in the context of its use. For details,
see “Figurative constants” on page 13.

166 Enterprise COBOL for z/OS, V6.1 Language Reference

All group items have a class and category, even if the subordinate elementary
items belong to another class and category. For the classification of group items,
see “Classes and categories of group items” on page 165.
Table 8. Class, category, and usage of elementary data items
Class Category Usage
Alphabetic Alphabetic DISPLAY
Alphanumeric Alphanumeric DISPLAY
Alphanumeric-edited DISPLAY
Numeric-edited DISPLAY
DBCS DBCS DISPLAY-1
National National NATIONAL
National-edited NATIONAL
Numeric-edited NATIONAL
Numeric Numeric DISPLAY (type zoned decimal)
NATIONAL (type national decimal)
PACKED-DECIMAL (type internal
decimal)
COMP-3 (type internal decimal)
BINARY
COMP
COMP-4
COMP-5
Internal floating-point COMP-1
COMP-2
External floating-point DISPLAY
NATIONAL

Table 9. Classes and categories of functions

Function type Class and category
Alphanumeric Alphanumeric
National National
Integer Numeric
Numeric Numeric

Table 10. Classes and categories of literals

Literal Class and category
Alphanumeric Alphanumeric
(including hexadecimal formats)
DBCS DBCS
National National
(including hexadecimal formats)
Numeric Numeric
(fixed-point and floating-point)

Chapter 16. DATA DIVISION overview 167

 Category descriptions
The category of a data item is established by the attributes of its data description
entry (such as its PICTURE character-string or USAGE clause) or by its function
definition.

The meaning of each category is given below.

Alphabetic

A data item is described as category alphabetic by its PICTURE character-string.

For PICTURE character-string details, see “Alphabetic items” on page 209.

A data item of category alphabetic is referred to as an alphabetic data item.

Alphanumeric

Each of the following data items is of category alphanumeric:

v An elementary data item described as alphanumeric by its PICTURE
character-string. For PICTURE character-string details, see “Alphanumeric items”
on page 211.
v An alphanumeric group item.
v An alphanumeric function.
v The following special registers:
– DEBUG-ITEM
– SHIFT-OUT
– SHIFT-IN
– SORT-CONTROL
– SORT-MESSAGE
– WHEN-COMPILED
– XML-EVENT
– XML-TEXT

Alphanumeric-edited
A data item is described as category alphanumeric-edited by its PICTURE
character-string. For PICTURE character-string details, see “Alphanumeric-edited
items” on page 212.

A data item of category alphanumeric-edited is referred to as an

alphanumeric-edited data item.

DBCS

A data item is described as category DBCS by its PICTURE character-string and

the NSYMBOL(DBCS) compiler option or by an explicit USAGE DISPLAY-1 clause.
For PICTURE character-string details, see “DBCS items” on page 212.

A data item of category DBCS is referred to as a DBCS data item.

168 Enterprise COBOL for z/OS, V6.1 Language Reference

External floating-point

A data item is described as category external floating-point by its PICTURE

character-string. For PICTURE character-string details, see “External floating-point
items” on page 214. An external floating-point data item can be described with
USAGE DISPLAY or USAGE NATIONAL.

When the usage is DISPLAY, the item is referred to as a display floating-point data
item.

When the usage is NATIONAL, the item is referred to as a national floating-point

data item.

An external floating-point data item is of class numeric and, unless specifically

excluded, is included in a reference to a numeric data item.

Internal floating-point

A data item is described as category internal floating-point by a USAGE clause

with the COMP-1 or COMP-2 phrase.

A data item of category internal floating-point is referred to as an internal

floating-point data item. An internal floating-point data item is of class numeric
and, unless specifically excluded, is included in a reference to a numeric data item.

National

Each of the following data items is of category national:

v A data item that is described as category national by its PICTURE
character-string and the NSYMBOL(NATIONAL) compiler option or by an
explicit USAGE NATIONAL clause. For PICTURE character-string details, see
“National items” on page 213.
v A group item explicitly or implicitly described with a GROUP-USAGE
NATIONAL clause.
v A national function.
v The special register XML-NTEXT.

National-edited
A data item is described as category national-edited by its PICTURE
character-string. For PICTURE character-string details, see “National-edited items”
on page 213.

A data item of category national-edited is referred to as a national-edited data

item.

Numeric

Each of the following data items is of category numeric:

v An elementary data item described as numeric by its PICTURE character-string
and not described with a BLANK WHEN ZERO clause. For PICTURE
character-string details, see “Numeric items” on page 210.
v An elementary data item described with one of the following usages:

Chapter 16. DATA DIVISION overview 169

 – BINARY, COMPUTATIONAL, COMPUTATIONAL-4, COMPUTATIONAL-5,
COMP, COMP-4, or COMP-5
– PACKED-DECIMAL, COMPUTATIONAL-3, or COMP-3
v A special register of numeric type:
| – JSON-CODE
– LENGTH OF
– LINAGE-COUNTER
– RETURN-CODE
– SORTCORE-SIZE
– SORT-FILE-SIZE
– SORT-MODE-SIZE
– SORT-RETURN
– TALLY
– XML-CODE
v A numeric function.
v An integer function.

A data item of category numeric is referred to as a numeric data item.

Numeric-edited

Each of the following data items is of category numeric-edited:

v A data item described as numeric-edited by its PICTURE character-string. For
PICTURE character-string details, see “Numeric-edited items” on page 211.
v A data item described as numeric by its PICTURE character-string and described
with a BLANK WHEN ZERO clause.

Alignment rules
The standard alignment rules for positioning data in an elementary item depend
on the category of a receiving item.

A receiving item is an item into which the data is moved. For more details about a
receiving item, see “Elementary moves” on page 394).
Numeric
For numeric receiving items, the following rules apply:
1. The data is aligned on the assumed decimal point and, if necessary,
truncated or padded with zeros. (An assumed decimal point is one that
has logical meaning but that does not exist as an actual character in the
data.)
2. If an assumed decimal point is not explicitly specified, the receiving
item is treated as though an assumed decimal point is specified
immediately to the right of the field. The data is then treated according
to the preceding rule.
Numeric-edited
The data is aligned on the decimal point, and (if necessary) truncated or
padded with zeros at either end except when editing causes replacement of
leading zeros.
Internal floating-point
A decimal point is assumed immediately to the left of the field. The data is

170 Enterprise COBOL for z/OS, V6.1 Language Reference

 then aligned on the leftmost digit position that follows the decimal point,
with the exponent adjusted accordingly.
External floating-point
The data is aligned on the leftmost digit position; the exponent is adjusted
accordingly.
Alphanumeric, alphanumeric-edited, alphabetic, DBCS
For these receiving items, the following rules apply:
1. The data is aligned at the leftmost character position, and (if necessary)
truncated or padded with spaces at the right.
2. If the JUSTIFIED clause is specified for this receiving item, the above
rule is modified as described in “JUSTIFIED clause” on page 193.
National, national-edited
For these receiving items, the following rules apply:
1. The data is aligned at the leftmost character position, and (if necessary)
truncated or padded with default Unicode spaces (NX'0020') at the
right. Truncation occurs at the boundary of a national character
position.
2. If the JUSTIFIED clause is specified for this receiving item, the above
rule is modified as described in “JUSTIFIED clause” on page 193.

Character-string and item size

For items described with a PICTURE clause, the size of an elementary item is
expressed in source code by the number of character positions described in the
PICTURE character-string and a SIGN clause (if applicable). Storage size, however,
is determined by the actual number of bytes the item occupies as determined by
the combination of its PICTURE character-string, SIGN IS SEPARATE clause (if
specified), and USAGE clause.

For items described with USAGE DISPLAY (categories alphabetic, alphanumeric,

alphanumeric-edited, numeric-edited, numeric, and external floating-point), 1 byte
of storage is reserved for each character position described by the item's PICTURE
character-string and SIGN IS SEPARATE clause (if applicable).

For items described with USAGE DISPLAY-1 (category DBCS), 2 bytes of storage
are reserved for each character position described by the item's PICTURE
character-string.

For items described with USAGE NATIONAL (categories national, national-edited,

numeric-edited, numeric, and external floating-point), 2 bytes of storage are
reserved for each character position described by the item's PICTURE
character-string and SIGN IS SEPARATE clause (if specified).

For internal floating-point items, the size of the item in storage is determined by its
USAGE clause. USAGE COMPUTATIONAL-1 reserves 4 bytes of storage for the
item; USAGE COMPUTATIONAL-2 reserves 8 bytes of storage.

Normally, when an arithmetic item is moved from a longer field into a shorter one,
the compiler truncates the data to the number of digits represented in the shorter
item's PICTURE character-string by truncating leading digits. For example, if a
sending field with PICTURE S99999 that contains the value +12345 is moved to a
BINARY receiving field with PICTURE S99, the data is truncated to +45. For
additional information, see “USAGE clause” on page 233.

Chapter 16. DATA DIVISION overview 171

 The TRUNC compiler option can affect the value of a binary numeric item. For
information about TRUNC, see TRUNC in the Enterprise COBOL Programming
Guide.

Signed data
There are two categories of algebraic signs used in COBOL: operational signs and
editing signs.

Operational signs
Operational signs are associated with signed numeric items, and indicate their
algebraic properties.

The internal representation of an algebraic sign depends on the item's USAGE

clause, its SIGN clause (if present), and the operating environment. (For further
details about the internal representation, see Examples: numeric data and internal
representation in the Enterprise COBOL Programming Guide.)

Editing signs
Editing signs are associated with numeric-edited items. Editing signs are PICTURE
symbols that identify the sign of the item in edited output.

172 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 17. DATA DIVISION--file description entries
In a COBOL program, the File Description (FD) Entry (or Sort File Description (SD)
Entry for sort/merge files) represents the highest level of organization in the FILE
SECTION. The order in which the optional clauses follow the FD or SD entry is
not important.

© Copyright IBM Corp. 1991, 2017 173

 Format 1: sequential file description entry

►► FD file-name-1 ►
EXTERNAL GLOBAL
IS IS

► ►
BLOCK integer-2 CHARACTERS
CONTAINS integer-1 TO RECORDS

► ►
RECORD integer-3
CONTAINS CHARACTERS
integer-4 TO integer-5
CONTAINS CHARACTERS
clause 1
DEPENDING data-name-1
ON

► ►
LABEL RECORD STANDARD
IS OMITTED
RECORDS
ARE
▼
data-name-2

► ►

VALUE OF ▼ system-name-1 data-name-3 DATA RECORD ▼ data-name-4

IS literal-1 IS
RECORDS
ARE

► ►
LINAGE data-name-5 clause 2 RECORDING mode
IS integer-8 LINES MODE IS

► . ►◄
CODE-SET alphabet-name
IS

clause 1:

VARYING
IS IN SIZE integer-6 TO integer-7 CHARACTERS
FROM

clause 2:

►
FOOTING data-name-6 TOP data-name-7
WITH AT integer-9 LINES AT integer-10

►
BOTTOM data-name-8
LINES AT integer-11

174 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 2: relative or indexed file description entry

►► FD file-name-1 ►
EXTERNAL GLOBAL
IS IS

► ►
BLOCK integer-2 CHARACTERS
CONTAINS integer-1 TO RECORDS

► ►
RECORD integer-3
CONTAINS CHARACTERS
integer-4 TO integer-5
CONTAINS CHARACTERS
clause 1
DEPENDING data-name-1
ON

► ►
LABEL RECORD STANDARD
IS OMITTED
RECORDS
ARE

► ►

VALUE OF ▼ system-name-1 data-name-3

IS literal-1

► . ►◄

DATA RECORD ▼ data-name-4

IS
RECORDS
ARE

clause 1:

VARYING
IS IN SIZE integer-6 TO integer-7 CHARACTERS
FROM

Chapter 17. DATA DIVISION--file description entries 175

 Format 3: line-sequential file description entry

►► FD file-name-1 ►
EXTERNAL GLOBAL
IS IS

► . ►◄
RECORD integer-3
CONTAINS CHARACTERS
clause 1
DEPENDING data-name-1
ON

clause 1:

VARYING
IS IN SIZE integer-6 TO integer-7 CHARACTERS
FROM

176 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 4: sort/merge file description entry

►► SD file-name-1 ►
RECORD integer-3
CONTAINS CHARACTERS
integer-4 TO integer-5
CONTAINS CHARACTERS
clause 1
DEPENDING data-name-1
ON

► ►

DATA RECORD ▼ data-name-4

IS
RECORDS
ARE

► ►
BLOCK integer-2 CHARACTERS
CONTAINS integer-1 TO RECORDS

► ►
LABEL RECORD STANDARD
IS OMITTED
RECORDS
ARE
▼ data-name-2

► ►

VALUE OF ▼ system-name-1 data-name-3

IS literal-1

► . ►◄
LINAGE data-name-5 clause 2 CODE-SET alphabet-name
IS integer-8 LINES IS

clause 1:

VARYING
IS IN SIZE integer-6 TO integer-7 CHARACTERS
FROM

clause 2:

►
FOOTING data-name-6 TOP data-name-7
WITH AT integer-9 LINES AT integer-10

►
BOTTOM data-name-8
LINES AT integer-11

Chapter 17. DATA DIVISION--file description entries 177

FILE SECTION
The FILE SECTION must contain a level-indicator for each input and output file.
For all files except sort or merge files, the FILE SECTION must contain an FD
entry. For each sort or merge file, the FILE SECTION must contain an SD entry.
file-name
Must follow the level indicator (FD or SD), and must be the same as that
specified in the associated SELECT clause. file-name must adhere to the
rules of formation for a user-defined word; at least one character must be
alphabetic. file-name must be unique within this program.
One or more record description entries must follow file-name. When more
than one record description entry is specified, each entry implies a
redefinition of the same storage area.
The clauses that follow file-name are optional, and they can appear in any
order.
FD (formats 1, 2, and 3)
The last clause in the FD entry must be immediately followed by a
separator period.
SD (format 4)
An SD entry must be written for each sort or merge file in the program.
The last clause in the SD entry must be immediately followed by a
separator period.
The following example illustrates the FILE SECTION entries needed for a
sort or merge file:
SD SORT-FILE.
01 SORT-RECORD PICTURE X(80).

A record in the FILE SECTION must be described as an alphanumeric group item,

a national group item, or an elementary item of class alphabetic, alphanumeric,
DBCS, national, or numeric.

EXTERNAL clause
The EXTERNAL clause specifies that a file connector is external, and permits
communication between two programs by the sharing of files.

A file connector is external if the storage associated with that file is associated with
the run unit rather than with any particular program within the run unit. An
external file can be referenced by any program in the run unit that describes the
file. References to an external file from different programs that use separate
descriptions of the file are always to the same file. In a run unit, there is only one
representative of an external file.

In the FILE SECTION, the EXTERNAL clause can be specified only in file
description entries.

The records appearing in the file description entry need not have the same name in
corresponding external file description entries. In addition, the number of such
records need not be the same in corresponding file description entries.

178 Enterprise COBOL for z/OS, V6.1 Language Reference

 Use of the EXTERNAL clause does not imply that the associated file-name is a
global name. See Sharing data by using the EXTERNAL clause in the Enterprise
COBOL Programming Guide for specific information about the use of the
EXTERNAL clause.

GLOBAL clause
The GLOBAL clause specifies that the file connector named by a file-name is a
global name. A global file-name is available to the program that declares it and to
every program that is contained directly or indirectly in that program.

A file-name is global if the GLOBAL clause is specified in the file description entry
for that file-name. A record-name is global if the GLOBAL clause is specified in the
record description entry by which the record-name is declared or, in the case of
record description entries in the FILE SECTION, if the GLOBAL clause is specified
in the file description entry for the file-name associated with the record description
entry. For details on using the GLOBAL clause, see Using data in input and output
operations and Scope of names in the Enterprise COBOL Programming Guide.

Two programs in a run unit can reference global file connectors in the following
circumstances:
v An external file connector can be referenced from any program that describes
that file connector.
v If a program is contained within another program, both programs can refer to a
global file connector by referring to an associated global file-name either in the
containing program or in any program that directly or indirectly contains the
containing program.

BLOCK CONTAINS clause

The BLOCK CONTAINS clause specifies the size of the physical records.

The CHARACTERS phrase indicates that the integer specified in the BLOCK
CONTAINS clause reflects the number of bytes in the record. For example, if you
have a block with 10 DBCS characters or 10 national characters, the BLOCK
CONTAINS clause should say BLOCK CONTAINS 20 CHARACTERS.

If the records in the file are not blocked, the BLOCK CONTAINS clause can be
omitted. When it is omitted, the compiler assumes that records are not blocked.
Even if each physical record contains only one complete logical record, coding
BLOCK CONTAINS 1 RECORD would result in fixed blocked records.

The BLOCK CONTAINS clause can be omitted when the associated file-control
entry specifies a VSAM file. The concept of blocking has no meaning for VSAM
files. The BLOCK CONTAINS clause is syntax checked but has no effect on the
execution of the program.

For external files, the value of all BLOCK CONTAINS clauses of corresponding
external files must match within the run unit. This conformance is in terms of
bytes and does not depend upon whether the value was specified as
CHARACTERS or as RECORDS.
integer-1 , integer-2
Must be unsigned integers. They specify:

Chapter 17. DATA DIVISION--file description entries 179

 CHARACTERS
Specifies the number of bytes required to store the physical record,
no matter what USAGE the data items have within the data record.
If only integer-2 is specified, it specifies the exact number of bytes
in the physical record. When integer-1 and integer-2 are both
specified, they represent the minimum and maximum number of
bytes in the physical record, respectively.
integer-1 and integer-2 must include any control bytes and padding
contained in the physical record. (Logical records do not include
padding.)
The CHARACTERS phrase is the default. CHARACTERS must be
specified when:
v The physical record contains padding.
v Logical records are grouped so that an inaccurate physical record
size could be implied. For example, suppose you describe a
variable-length record of 100 bytes, yet each time you write a
block of 4, one 50-byte record is written followed by three
100-byte records. If the RECORDS phrase were specified, the
compiler would calculate the block size as 420 bytes instead of
the actual size, 370 bytes. (This calculation includes block and
record descriptors.)
RECORDS
Specifies the number of logical records contained in each physical
record.
The compiler assumes that the block size must provide for integer-2
records of maximum size, and provides any additional space
needed for control bytes.

BLOCK CONTAINS 0 can be specified for QSAM files. If BLOCK CONTAINS 0 is

specified for a QSAM file, then:
v The block size is determined at run time from the DD parameters or the data set
label of the file. For output data sets, the DCB used by Language Environment
will have a zero block size value. When the DCB has a zero block size value, the
operating system might select a system-determined block size (SDB). See the
operating system specifications for further information about SDB.
BLOCK CONTAINS can be omitted for SYSIN files and for SYSOUT files. The
blocking is determined by the operating system.

For a way to apply BLOCK CONTAINS 0 to QSAM files that do not already have
a BLOCK CONTAINS clause, see the description of the compiler option, BLOCK0
in the Enterprise COBOL Programming Guide.

The BLOCK CONTAINS clause is syntax checked but has no effect on the
execution of the program when specified under an SD.

The BLOCK CONTAINS clause cannot be used with the RECORDING MODE U
clause.

180 Enterprise COBOL for z/OS, V6.1 Language Reference

RECORD clause
When the RECORD clause is used, the record size must be specified as the number
of bytes needed to store the record internally, regardless of the USAGE of the data
items contained within the record.

For example, if you have a record with 10 DBCS characters, the RECORD clause
should say RECORD CONTAINS 20 CHARACTERS. For a record with 10 national
characters, the RECORD clause should say the same, RECORD CONTAINS 20
CHARACTERS.

The size of a record is determined according to the rules for obtaining the size of a
group item. (See “USAGE clause” on page 233 and “SYNCHRONIZED clause”
on page 228.)

When the RECORD clause is omitted, the compiler determines the record lengths
from the record descriptions. When one of the entries within a record description
contains an OCCURS DEPENDING ON clause, the compiler uses the maximum
value of the variable-length item to calculate the number of bytes needed to store
the record internally.

If the associated file connector is an external file connector, all file description
entries in the run unit that are associated with that file connector must specify the
same maximum number of bytes.

The following sections describe the formats of the RECORD clause:

Format 1
Format 1 specifies the number of bytes for fixed-length records.

Format 1

►► RECORD integer-3 ►◄
CONTAINS CHARACTERS

integer-3
Must be an unsigned integer that specifies the number of bytes contained
in each record in the file.
The RECORD CONTAINS 0 CHARACTERS clause can be specified for
input QSAM files containing fixed-length records; the record size is
determined at run time from the DD statement parameters or the data set
label. If, at run time, the actual record is larger than the 01 record
description, then only the 01 record length is available. If the actual record
is shorter, then only the actual record length can be referred to. Otherwise,
uninitialized data or an addressing exception can be produced.
Usage note: If the RECORD CONTAINS 0 clause is specified, then the
SAME AREA, SAME RECORD AREA, or APPLY WRITE-ONLY clauses
cannot be specified.
Do not specify the RECORD CONTAINS 0 clause for an SD entry.

Chapter 17. DATA DIVISION--file description entries 181

 Format 2
Format 2 specifies the number of bytes for either fixed-length or variable-length
records.

Fixed-length records are obtained when all 01 record description entry lengths are
the same. The format-2 RECORD CONTAINS clause is never required, because the
minimum and maximum record lengths are determined from the record
description entries.

Format 2

►► RECORD integer-4 TO integer-5 ►◄

CONTAINS CHARACTERS

integer-4, integer-5
Must be unsigned integers. integer-4 specifies the size of the smallest data
record, and integer-5 specifies the size of the largest data record.

Format 3
Format 3 is used to specify variable-length records.

Format 3

►► RECORD VARYING ►
IS IN SIZE integer-6
FROM

► ►◄
TO integer-7 CHARACTERS DEPENDING data-name-1
ON

integer-6
Specifies the minimum number of bytes to be contained in any record of
the file. If integer-6 is not specified, the minimum number of bytes to be
contained in any record of the file is equal to the least number of bytes
described for a record in that file.
integer-7
Specifies the maximum number of bytes in any record of the file. If
integer-7 is not specified, the maximum number of bytes to be contained in
any record of the file is equal to the greatest number of bytes described for
a record in that file.

The number of bytes associated with a record description is determined by the

sum of the number of bytes in all elementary data items (excluding redefinitions
and renamings), plus any implicit FILLER due to synchronization. If a table is
specified:

182 Enterprise COBOL for z/OS, V6.1 Language Reference

 v The minimum number of table elements described in the record is used in the
summation above to determine the minimum number of bytes associated with
the record description.
v The maximum number of table elements described in the record is used in the
summation above to determine the maximum number of bytes associated with
the record description.

If data-name-1 is specified:
v data-name-1 must be an elementary unsigned integer.
v The number of bytes in the record must be placed into the data item referenced
by data-name-1 before any RELEASE, REWRITE, or WRITE statement is executed
for the file.
v The execution of a DELETE, RELEASE, REWRITE, START, or WRITE statement
or the unsuccessful execution of a READ or RETURN statement does not alter
the content of the data item referenced by data-name-1.
v After the successful execution of a READ or RETURN statement for the file, the
contents of the data item referenced by data-name-1 indicate the number of bytes
in the record just read.

During the execution of a RELEASE, REWRITE, or WRITE statement, the number

of bytes in the record is determined by the following conditions:
v If data-name-1 is specified, by the content of the data item referenced by
data-name-1
v If data-name-1 is not specified and the record does not contain a variable
occurrence data item, by the number of bytes positions in the record
v If data-name-1 is not specified and the record contains a variable occurrence data
item, by the sum of the fixed position and that portion of the table described by
the number of occurrences at the time of execution of the output statement

During the execution of a READ ... INTO or RETURN ... INTO statement, the
number of bytes in the current record that participate as the sending data items in
the implicit MOVE statement is determined by the following conditions:
v If data-name-1 is specified, by the content of the data item referenced by
data-name-1
v If data-name-1 is not specified, by the value that would have been moved into
the data item referenced by data-name-1 had data-name-1 been specified

LABEL RECORDS clause

For sequential, relative, or indexed files, and for sort/merge SDs, the LABEL
RECORDS clause is syntax checked, but has no effect on the execution of the
program.

The LABEL RECORDS clause documents the presence or absence of labels.

STANDARD
Labels conforming to system specifications exist for this file.
STANDARD is permitted for mass storage devices and tape devices.
OMITTED
No labels exist for this file.
OMITTED is permitted for tape devices.

Chapter 17. DATA DIVISION--file description entries 183

 data-name-2
User labels are present in addition to standard labels. data-name-2 specifies
the name of a user label record. data-name-2 must appear as the subject of a
record description entry associated with the file.

VALUE OF clause
The VALUE OF clause describes an item in the label records associated with the
file.
data-name-3
Should be qualified when necessary, but cannot be subscripted. It must be
described in the WORKING-STORAGE SECTION. It cannot be described
with the USAGE IS INDEX clause.
literal-1
Can be numeric or alphanumeric, or a figurative constant of category
numeric or alphanumeric. Cannot be a floating-point literal.

The VALUE OF clause is syntax checked, but has no effect on the execution of the
program.

DATA RECORDS clause

The DATA RECORDS clause is syntax checked but serves only as documentation
for the names of data records associated with the file.
data-name-4
The names of record description entries associated with the file.

The data-name need not have an associated 01 level number record description
with the same name.

LINAGE clause
The LINAGE clause specifies the depth of a logical page in number of lines.
Optionally, it also specifies the line number at which the footing area begins and
the top and bottom margins of the logical page. (The logical page and the physical
page cannot be the same size.)

The LINAGE clause is effective for sequential files opened as OUTPUT or

EXTEND.

All integers must be unsigned. All data-names must be described as unsigned

integer data items.
data-name-5 , integer-8
The number of lines that can be written or spaced on this logical page. The
area of the page that these lines represent is called the page body. The value
must be greater than zero.
WITH FOOTING AT
integer-9 or the value of the data item in data-name-6 specifies the first line
number of the footing area within the page body. The footing line number
must be greater than zero, and not greater than the last line of the page
body. The footing area extends between those two lines.

184 Enterprise COBOL for z/OS, V6.1 Language Reference

LINES AT TOP
integer-10 or the value of the data item in data-name-7 specifies the number
of lines in the top margin of the logical page. The value can be zero.
LINES AT BOTTOM
integer-11 or the value of the data item in data-name-8 specifies the number
of lines in the bottom margin of the logical page. The value can be zero.

The following figure illustrates the use of each phrase of the LINAGE clause.

The logical page size specified in the LINAGE clause is the sum of all values
specified in each phrase except the FOOTING phrase. If the LINES AT TOP phrase
is omitted, the assumed value for the top margin is zero. Similarly, if the LINES AT
BOTTOM phrase is omitted, the assumed value for the bottom margin is zero.
Each logical page immediately follows the preceding logical page, with no
additional spacing provided.

If the FOOTING phrase is omitted, its assumed value is equal to that of the page
body (integer-8 or data-name-5).

At the time an OPEN OUTPUT statement is executed, the values of integer-8,

integer-9, integer-10, and integer-11, if specified, are used to determine the page
body, first footing line, top margin, and bottom margin of the logical page for this
file. (See the figure above.) These values are then used for all logical pages printed
for this file during a given execution of the program.

At the time an OPEN statement with the OUTPUT phrase is executed for the file,
data-name-5, data-name-6, data-name-7, and data-name-8 determine the page body,
first footing line, top margin, and bottom margin for the first logical page only.

At the time a WRITE statement with the ADVANCING PAGE phrase is executed
or a page overflow condition occurs, the values of data-name-5, data-name-6,
data-name-7, and data-name-8 if specified, are used to determine the page body, first
footing line, top margin, and bottom margin for the next logical page.

If an external file connector is associated with this file description entry, all file
description entries in the run unit that are associated with this file connector must
have:

Chapter 17. DATA DIVISION--file description entries 185

 v A LINAGE clause, if any file description entry has a LINAGE clause
v The same corresponding values for integer-8, integer-9, integer-10, and integer-11,
if specified
v The same corresponding external data items referenced by data-name-5,
data-name-6, data-name-7, and data-name-8

See “ADVANCING phrase” on page 480 for the behavior of carriage control
characters in external files.

A LINAGE clause under an SD is syntax checked, but has no effect on the

execution of the program.

LINAGE-COUNTER special register

For information about the LINAGE-COUNTER special register, see
“LINAGE-COUNTER” on page 20.

RECORDING MODE clause

The RECORDING MODE clause specifies the format of the physical records in a
QSAM file. The clause is ignored for a VSAM file.

Permitted values for RECORDING MODE are:

Recording mode F (fixed)
All the records in a file are the same length and each is wholly contained
within one block. Blocks can contain more than one record, and there is
usually a fixed number of records for each block. In this mode, there are
no record-length or block-descriptor fields.
Recording mode V (variable)
The records can be either fixed-length or variable-length, and each must be
wholly contained within one block. Blocks can contain more than one
record. Each data record includes a record-length field and each block
includes a block-descriptor field. These fields are not described in the
DATA DIVISION. They are each 4 bytes long and provision is
automatically made for them. These fields are not available to you.
Recording mode U (fixed or variable)
The records can be either fixed-length or variable-length. However, there is
only one record for each block. There are no record-length or
block-descriptor fields.
You cannot use RECORDING MODE U if you are using the BLOCK
CONTAINS clause.
Recording mode S (spanned)
The records can be either fixed-length or variable-length, and can be larger
than a block. If a record is larger than the remaining space in a block, a
segment of the record is written to fill the block. The remainder of the
record is stored in the next block (or blocks, if required). Only complete
records are made available to you. Each segment of a record in a block,
even if it is the entire record, includes a segment-descriptor field, and each
block includes a block-descriptor field. These fields are not described in the
DATA DIVISION; provision is automatically made for them. These fields
are not available to you.

186 Enterprise COBOL for z/OS, V6.1 Language Reference

 When recording mode S is used, the BLOCK CONTAINS CHARACTERS clause
must be used. Recording mode S is not allowed for ASCII files.

If the RECORDING MODE clause is not specified for a QSAM file, the Enterprise
COBOL compiler determines the recording mode as follows:
F The compiler determines the recording mode to be F if the largest level-01
record associated with the file is not greater than the block size specified in
the BLOCK CONTAINS clause, and you do one of the following things:
v Use the RECORD CONTAINS integer clause. (For more information, see
the Enterprise COBOL Migration Guide.)
v Omit the RECORD clause and make sure that all level-01 records
associated with the file are the same size and none contains an OCCURS
DEPENDING ON clause.
V 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 specified in
the BLOCK CONTAINS clause, and you do one of the following things:
v Use the RECORD IS VARYING clause.
v Omit the RECORD clause and make sure that all level-01 records
associated with the file are not the same size or some contain an
OCCURS DEPENDING ON clause.
v Use the RECORD CONTAINS integer-1 TO integer-2 clause, with integer-1
the minimum length and integer-2 the maximum length of the level-01
records associated with the file. The two integers must be different, with
values matching minimum and maximum length of either different
length records or records with an OCCURS DEPENDING ON clause.
S The compiler determines the recording mode to be S if the maximum block
size is smaller than the largest record size.
U Recording mode U is never obtained by default. The RECORDING MODE
U clause must be explicitly specified to get recording mode U.

CODE-SET clause
The CODE-SET clause specifies the character code used to represent data on a
magnetic tape file. When the CODE-SET clause is specified, an alphabet-name
identifies the character code convention used to represent data on the input-output
device.

alphabet-name must be defined in the SPECIAL-NAMES paragraph as

STANDARD-1 (for ASCII-encoded files), STANDARD-2 (for ISO 7-bit encoded
files), EBCDIC (for EBCDIC-encoded files), or NATIVE. When NATIVE is specified,
the CODE-SET clause is syntax checked but has no effect on the execution of the
program.

The CODE-SET clause also specifies the algorithm for converting the character
codes on the input-output medium from and to the internal EBCDIC character set.

When the CODE-SET clause is specified for a file, all data in the file must have
USAGE DISPLAY; and if signed numeric data is present, it must be described with
the SIGN IS SEPARATE clause.

When the CODE-SET clause is omitted, the EBCDIC character set is assumed for
the file.

Chapter 17. DATA DIVISION--file description entries 187

 If the associated file connector is an external file connector, all CODE-SET clauses
in the run unit that are associated with the file connector must have the same
character set.

The CODE-SET clause is valid only for magnetic tape files.

The CODE-SET clause is syntax checked but has no effect on the execution of the
program when specified under an SD.

188 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 18. DATA DIVISION--data description entry
A data description entry specifies the characteristics of a data item. In the sections
that follow, sets of data description entries are called record description entries. The
term data description entry refers to data and record description entries.

Data description entries that define independent data items do not make up a
record. These entries are known as data item description entries.

Data description entries have three general formats, and all data description entries
must end with a separator period.

Format 1
Format 1 is used for data description entries in all DATA DIVISION sections.

Format 1: data description entry

►► level-number ►
data-name-1 redefines-clause blank-when-zero-clause
FILLER

► ►
external-clause global-clause group-usage-clause justified-clause

► ►
occurs-clause picture-clause sign-clause synchronized-clause

► ►◄
usage-clause value-clause volatile-clause

The clauses can be written in any order, with two exceptions:

v data-name-1 or FILLER, if specified, must immediately follow the level-number.
v When the REDEFINES clause is specified, it must immediately follow
data-name-1 or FILLER, if either is specified. If data-name-1 or FILLER is not
specified, the REDEFINES clause must immediately follow the level-number.

The level-number in format 1 can be any number in the range 01–49, or 77.

A space, a comma, or a semicolon must separate clauses.

Format 2
Format 2 regroups previously defined items.

© Copyright IBM Corp. 1991, 2017 189

 Format 2: renames

►► 66 data-name-1 renames-clause. ►◄

A level-66 entry cannot rename another level-66 entry, nor can it rename a level-01,
level-77, or level-88 entry.

All level-66 entries associated with one record must immediately follow the last
data description entry in that record.

See “RENAMES clause” on page 224 for further details.

Format 3
Format 3 describes condition-names.

Format 3: condition-name

►► 88 condition-name-1 value-clause. ►◄

condition-name-1
A user-specified name that associates a value, a set of values, or a range of
values with a conditional variable.
Level-88 entries must immediately follow the data description entry for the
conditional variable with which the condition-names are associated.

Format 3 can be used to describe elementary items, national group items, or

alphanumeric group items. Additional information about condition-name entries
can be found under “VALUE clause” on page 241 and “Condition-name condition”
on page 266.

Level-numbers
The level-number specifies the hierarchy of data within a record, and identifies
special-purpose data entries. A level-number begins a data description entry, a
renamed or redefined item, or a condition-name entry.

A level-number has an integer value between 1 and 49, inclusive, or one of the
special level-number values 66, 77, or 88.

190 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format

►► level-number ►◄
data-name-1
FILLER

level-number
01 and 77 must begin in Area A and be followed either by a separator
period or by a space followed by its associated data-name, FILLER, or
appropriate data description clause.
Level numbers 02 through 49 can begin in Areas A or B and must be
followed by a space or a separator period.
Level numbers 66 and 88 can begin in Areas A or B and must be followed
by a space.
Single-digit level-numbers 1 through 9 can be substituted for
level-numbers 01 through 09.
Successive data description entries can start in the same column as the first
entry or can be indented according to the level-number. Indentation does
not affect the magnitude of a level-number.
When level-numbers are indented, each new level-number can begin any
number of spaces to the right of Area A. The extent of indentation to the
right is limited only by the width of Area B.
For more information, see “Levels of data” on page 163.
data-name-1
Explicitly identifies the data being described.
data-name-1, if specified, identifies a data item used in the program.
data-name-1 must be the first word following the level-number.
The data item can be changed during program execution.
data-name-1 must be specified for level-66 and level-88 items. It must also
be specified for any entry containing the GLOBAL or EXTERNAL clause,
and for record description entries associated with file description entries
that have the GLOBAL or EXTERNAL clauses.
FILLER
A data item that is not explicitly referred to in a program. The keyword
FILLER is optional. If specified, FILLER must be the first word following
the level-number.
The keyword FILLER can be used with a conditional variable if explicit
reference is never made to the conditional variable but only to values that
it can assume. FILLER cannot be used with a condition-name.
In a MOVE CORRESPONDING statement or in an ADD
CORRESPONDING or SUBTRACT CORRESPONDING statement, FILLER
items are ignored.
| In an INITIALIZE statement:
| v When the FILLER phrase is not specified, elementary FILLER items are
| ignored.

Chapter 18. DATA DIVISION--data description entry 191

| v When the FILLER phrase is specified, the receiving elementary data
| items that have an explicit or implicit FILLER clause will be initialized.

If data-name-1 or the FILLER clause is omitted, the data item being described is
treated as though FILLER had been specified.

BLANK WHEN ZERO clause

The BLANK WHEN ZERO clause specifies that an item contains only spaces when
its value is zero.

Format

►► BLANK ZERO ►◄
WHEN ZEROS
ZEROES

The BLANK WHEN ZERO clause may be specified only for an elementary item
described by its picture character string as category numeric-edited or numeric,
without the picture symbol S or *. These items must be described, either implicitly
or explicitly, as USAGE DISPLAY or USAGE NATIONAL.

A BLANK WHEN ZERO clause that is specified for an item defined as numeric by
its picture character string defines the item as category numeric-edited.

EXTERNAL clause
The EXTERNAL clause specifies that the storage associated with a data item is
associated with the run unit rather than with any particular program or method
within the run unit.

An external data item can be referenced by any program or method in the run unit
that describes the data item. References to an external data item from different
programs or methods using separate descriptions of the data item are always to
the same data item. In a run unit, there is only one representative of an external
data item.

The EXTERNAL clause can be specified only on data description entries whose
level-number is 01. It can be specified only on data description entries that are in
the WORKING-STORAGE SECTION of a program or method. It cannot be
specified in LINKAGE SECTION or FILE SECTION data description entries. Any
data item described by a data description entry subordinate to an entry that
describes an external record also attains the external attribute. Indexes in an
external data record do not possess the external attribute.

The data contained in the record named by the data-name clause is external and
can be accessed and processed by any program or method in the run unit that
describes and, optionally, redefines it. This data is subject to the following rules:
v If two or more programs or methods within a run unit describe the same
external data record, each record-name of the associated record description
entries must be the same, and the records must define the same number of

192 Enterprise COBOL for z/OS, V6.1 Language Reference

 bytes. However, a program or method that describes an external record can
contain a data description entry including the REDEFINES clause that redefines
the complete external record, and this complete redefinition need not occur
identically in other programs or methods in the run unit.
v Use of the EXTERNAL clause does not imply that the associated data-name is a
global name.

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. All data-names subordinate to or
condition-names or indexes associated with a global name are global names.

A data-name is global if the GLOBAL clause is specified either in the data

description entry by which the data-name is defined or in another entry to which
that data description entry is subordinate. The GLOBAL clause can be specified in
the WORKING-STORAGE SECTION, the FILE SECTION, the LINKAGE SECTION,
and the LOCAL-STORAGE SECTION, but only in data description entries whose
level-number is 01.

In the same DATA DIVISION, the data description entries for any two data items
for which the same data-name is specified must not include the GLOBAL clause.

A statement in a program contained directly or indirectly within a program that

describes a global name can reference that name without describing it again.

Two programs in a run unit can reference common data in the following
circumstances:
v The data content of an external data record can be referenced from any program
that describes the data record as external.
v If a program is contained within another program, both programs can refer to
data that possesses the global attribute either in the containing program or in
any program that directly or indirectly contains the containing program.

JUSTIFIED clause
The JUSTIFIED clause overrides standard positioning rules for receiving items of
category alphabetic, alphanumeric, DBCS, or national.

Format

►► JUSTIFIED ►◄
JUST RIGHT

You can specify the JUSTIFIED clause only at the elementary level. JUST is an
abbreviation for JUSTIFIED, and has the same meaning.

You cannot specify the JUSTIFIED clause:

Chapter 18. DATA DIVISION--data description entry 193

 v For data items of category numeric, numeric-edited, alphanumeric-edited, or
national-edited
v For edited DBCS items
v For index data items
v For items described as USAGE FUNCTION-POINTER, USAGE POINTER,
USAGE PROCEDURE-POINTER, or USAGE OBJECT REFERENCE
v For external floating-point or internal floating-point items
v With level-66 (RENAMES) and level-88 (condition-name) entries

When the JUSTIFIED clause is specified for a receiving item, the data is aligned at
the rightmost character position in the receiving item. Also:
v If the sending item is larger than the receiving item, the leftmost character
positions are truncated.
v If the sending item is smaller than the receiving item, the unused character
positions at the left are filled with spaces. For a DBCS item, each unused
position is filled with a DBCS space (X'4040'); for an item described with usage
NATIONAL, each unused position is filled with the default Unicode space
(NX'0020'); otherwise, each unused position is filled with an alphanumeric space.

If you omit the JUSTIFIED clause, the rules for standard alignment are followed
(see “Alignment rules” on page 170).

The JUSTIFIED clause does not affect initial settings as determined by the VALUE
clause.

GROUP-USAGE clause
A GROUP-USAGE clause with the NATIONAL phrase specifies that the group
item defined by the entry is a national group item. A national group item contains
national characters in all subordinate data items and subordinate group items.

Format

►► GROUP-USAGE NATIONAL ►◄
IS

When GROUP-USAGE NATIONAL is specified:

v The subject of the entry is a national group item. The class and category of a
national group are national.
v A USAGE clause must not be specified for the subject of the entry. A USAGE
NATIONAL clause is implied.
v A USAGE NATIONAL clause is implied for any subordinate elementary data
items that are not described with a USAGE NATIONAL clause.
v All subordinate elementary data items must be explicitly or implicitly described
with USAGE NATIONAL.
v Any signed numeric data items must be described with the SIGN IS SEPARATE
clause.

194 Enterprise COBOL for z/OS, V6.1 Language Reference

 v A GROUP-USAGE NATIONAL clause is implied for any subordinate group
items that are not described with a GROUP-USAGE NATIONAL clause.
v All subordinate group items must be explicitly or implicitly described with a
GROUP-USAGE NATIONAL clause.
v The JUSTIFIED clause must not be specified.

Unless stated otherwise, a national group item is processed as though it were an

elementary data item of usage national, class and category national, described with
PICTURE N(m), where m is the length of the group in national character positions.

Usage note: When you use national groups, the compiler can ensure proper
truncation and padding of group items for statements such as MOVE and
INSPECT. Groups defined without a GROUP-USAGE NATIONAL clause are
alphanumeric groups. The content of alphanumeric groups, including any national
characters, is treated as alphanumeric data, possibly leading to invalid truncation
or mishandling of national character data.

The table below summarizes the cases where a national group item is processed as
a group item.
Table 11. Where national group items are processed as groups
Language feature Processing of national group items
Name qualification The name of a national group item can be used to qualify the names of
elementary data items and subordinate group items in the national group. The
rules of qualification for a national group are the same as the rules of
qualification for an alphanumeric group.
RENAMES clause The rules for a national group item specified in the THROUGH phrase are the
same as the rules for an alphanumeric group item specified in the THROUGH
phrase. The result is an alphanumeric group item.
CORRESPONDING phrase A national group item is processed as a group in accordance with the rules of
the CORRESPONDING phrase. Elementary data items within a national group
are processed the same as they would be if defined within an alphanumeric
group.
INITIALIZE statement A national group item is processed as a group in accordance with the rules of
the INITIALIZE statement. Elementary items within the national group are
initialized the same as they would be if defined within an alphanumeric
group.
XML GENERATE statement A national group item specified in the FROM phrase is processed as a group in
accordance with the rules of the XML GENERATE statement. Elementary items
within the national group are processed the same as they would be if defined
within an alphanumeric group.
| JSON GENERATE statement A national group item specified in the FROM phrase is processed as a group in
| accordance with the rules of the JSON GENERATE statement. Elementary
| items within the national group are processed the same as they would be if
| defined within an alphanumeric group.

OCCURS clause
The DATA DIVISION language elements used for table handling are the OCCURS
clause and the INDEXED BY phrase.

For the INDEXED BY phrase description, see “INDEXED BY phrase” on page 199.

Chapter 18. DATA DIVISION--data description entry 195

 The OCCURS clause specifies tables whose elements can be referred to by indexing
or subscripting. It also eliminates the need for separate entries for repeated data
items.

Formats for the OCCURS clause include fixed-length tables and variable-length
tables.

The subject of an OCCURS clause is the data-name of the data item that contains
the OCCURS clause. Except for the OCCURS clause itself, data description clauses
used with the subject apply to each occurrence of the item described.

Whenever the subject of an OCCURS clause or any data-item subordinate to it is

referenced, it must be subscripted or indexed, with the following exceptions:
v When the subject of the OCCURS clause is used as the subject of a SEARCH
statement.
v When the subject of the OCCURS clause is used as the subject of a format 2
SORT statement.
v When the subject or a subordinate data item is the object of the
ASCENDING/DESCENDING KEY phrase.
v When the subordinate data item is the object of the REDEFINES clause.
v When the subordinate data item is used as the subject of a LENGTH OF special
register. For details, see “LENGTH OF” on page 19.

When subscripted or indexed, the subject refers to one occurrence within the table,
unless the ALL subscript is used in an intrinsic function.

The OCCURS clause cannot be specified in a data description entry that:

v Has a level number of 01, 66, 77, or 88.
v Describes a redefined data item. (However, a redefined item can be subordinate
to an item that contains an OCCURS clause.) See “REDEFINES clause” on page
221.

Fixed-length tables
Fixed-length tables are specified using the OCCURS clause.

Because seven subscripts or indexes are allowed, six nested levels and one
outermost level of the format-1 OCCURS clause are allowed. The format-1
OCCURS clause can be specified as subordinate to the OCCURS DEPENDING ON
clause. In this way, a table of up to seven dimensions can be specified.

196 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 1: fixed-length tables

►► OCCURS integer-2 ►
TIMES

► ▼ ►

ASCENDING ▼ data-name-2
DESCENDING KEY IS

► ►◄

INDEXED ▼ index-name-1
BY

integer-2
The exact number of occurrences. integer-2 must be greater than zero.

ASCENDING KEY and DESCENDING KEY phrases

Data is arranged in ascending or descending order, depending on the keyword
specified, according to the values contained in data-name-2. The data-names are
listed in their descending order of significance.

The order is determined by the rules for comparison of operands (see “Relation
conditions” on page 267). The ASCENDING KEY and DESCENDING KEY data
items are used in OCCURS clauses, the SEARCH ALL statements for a binary
search of the table element, and the format 2 SORT statements. As an alternative,
keys can be specified with the format 2 SORT statements.
data-name-2
Must be the name of the subject entry or the name of an entry subordinate
to the subject entry. data-name-2 can be qualified.
If data-name-2 names the subject entry, that entire entry becomes the
ASCENDING KEY or DESCENDING KEY and is the only key that can be
specified for this table element.
If data-name-2 does not name the subject entry, then data-name-2:
v Must be subordinate to the subject of the table entry itself
v Must not be subordinate to, or follow, any other entry that contains an
OCCURS clause
v Must not contain an OCCURS clause
data-name-2 must not have subordinate items that contain OCCURS
DEPENDING ON clauses.

When the ASCENDING KEY or DESCENDING KEY phrase is specified, the

following rules apply:

Chapter 18. DATA DIVISION--data description entry 197

 v Keys must be listed in decreasing order of significance.
v The total number of keys for a given table element must not exceed 12.
v The data in the table must be arranged in ascending or descending sequence
according to the collating sequence in use.
v The key must be described with one of the following usages:
– BINARY
– DISPLAY
– DISPLAY-1
– NATIONAL
– PACKED-DECIMAL
– COMPUTATIONAL
– COMPUTATIONAL-1
– COMPUTATIONAL-2
– COMPUTATIONAL-3
– COMPUTATIONAL-4
– COMPUTATIONAL-5
v A key described with usage NATIONAL can have one of the following
categories: national, national-edited, numeric-edited, numeric, or external
floating-point.
v The sum of the lengths of all the keys associated with one table element must
not exceed 256.
v If a key is specified without qualifiers and it is not a unique name, the key will
be implicitly qualified with the subject of the OCCURS clause and all qualifiers
of the OCCURS clause subject.

The following example illustrates the specification of ASCENDING KEY data

items:
WORKING-STORAGE SECTION.
01 TABLE-RECORD.
05 EMPLOYEE-TABLE OCCURS 100 TIMES
ASCENDING KEY IS WAGE-RATE EMPLOYEE-NO
INDEXED BY A, B.
10 EMPLOYEE-NAME PIC X(20).
10 EMPLOYEE-NO PIC 9(6).
10 WAGE-RATE PIC 9999V99.
10 WEEK-RECORD OCCURS 52 TIMES
ASCENDING KEY IS WEEK-NO INDEXED BY C.
15 WEEK-NO PIC 99.
15 AUTHORIZED-ABSENCES PIC 9.
15 UNAUTHORIZED-ABSENCES PIC 9.
15 LATE-ARRIVALS PIC 9.

The keys for EMPLOYEE-TABLE are subordinate to that entry, and the key for
WEEK-RECORD is subordinate to that subordinate entry.

In the preceding example, records in EMPLOYEE-TABLE must be arranged in

ascending order of WAGE-RATE, and in ascending order of EMPLOYEE-NO
within WAGE-RATE. Records in WEEK-RECORD must be arranged in ascending
order of WEEK-NO. If they are not, results of any SEARCH ALL statement are
unpredictable.

198 Enterprise COBOL for z/OS, V6.1 Language Reference

INDEXED BY phrase
The INDEXED BY phrase specifies the indexes that can be used with a table. A
table without an INDEXED BY phrase can be referred to through indexing by
using an index-name associated with another table.

For more information about using indexing, see “Subscripting using index-names
(indexing)” on page 78.

Indexes normally are allocated in static memory associated with the program that
contains the table. Thus indexes are in the last-used state when a program is
reentered. However, in the following cases, indexes are allocated on a
per-invocation basis. Thus you must set the value of the index on every entry for
indexes on tables in the following sections:
v The LOCAL-STORAGE SECTION
v The WORKING-STORAGE SECTION of a class definition (object instance
variables)
v The LINKAGE SECTION of:
– Methods
– Programs compiled with the RECURSIVE clause
– Programs compiled with the THREAD option

Indexes specified in an external data record do not possess the external attribute.
index-name-1
Each index-name specifies an index to be created by the compiler for use
by the program. These index-names are not data-names and are not
identified elsewhere in the COBOL program; instead, they can be regarded
as private special registers for the use of this object program only. They are
not data and are not part of any data hierarchy.
Unreferenced index names need not be uniquely defined.
In one table entry, up to 12 index-names can be specified.
If a data item that possesses the global attribute includes a table accessed
with an index, that index also possesses the global attribute. Therefore, the
scope of an index-name is the same as that of the data-name that names
the table in which the index is defined.

Variable-length tables
You can specify variable-length tables by using the OCCURS DEPENDING ON
clause.

Chapter 18. DATA DIVISION--data description entry 199

 Format 2: variable-length tables

►► OCCURS integer-2 DEPENDING ►

integer-1 TO UNBOUNDED TIMES ON

► data-name-1 ▼ ►

ASCENDING ▼ data-name-2
DESCENDING KEY IS

► ►◄

INDEXED ▼ index-name-1
BY

integer-1
The minimum number of occurrences.
The value of integer-1 must be greater than or equal to zero, and it must
also be less than the value of integer-2.
If integer-1 is omitted, a value of 1 is assumed and the keyword TO must
also be omitted.
integer-2
The maximum number of occurrences.
integer-2 must be greater than integer-1.

The length of the subject item is fixed. Only the number of repetitions of the subject
item is variable.
UNBOUNDED
Unbounded maximum number of occurrences.
Unbounded table
A table with an OCCURS clause that specifies UNBOUNDED.
You can reference unbounded tables in COBOL syntax anywhere a
table can be referenced.
Unbounded group
A group that contains at least one unbounded table.
You can define unbounded groups only in the LINKAGE
SECTION. Either alphanumeric groups or national groups can be
unbounded.
You can reference unbounded groups in COBOL syntax anywhere
an alphanumeric or national group can be referenced, with the
following exceptions:

200 Enterprise COBOL for z/OS, V6.1 Language Reference

 v You cannot specify unbounded groups as a BY CONTENT argument
in a CALL statement.
v You cannot specify unbounded groups as data-name-2 on the
PROCEDURE DIVISION RETURNING phrase.
v You cannot specify unbounded groups as arguments to intrinsic
functions, except as an argument to the LENGTH intrinsic function.
The total size of an unbounded group at run time must be less
than 999,999,999 bytes.
For unbounded tables and groups, the effect of the SSRANGE
compiler option is limited. For more information, see SSRANGE in
the Enterprise COBOL Programming Guide.
For references about working with unbounded tables and groups,
see Working with unbounded tables and groups in the Enterprise
COBOL Programming Guide.

OCCURS DEPENDING ON clause

The OCCURS DEPENDING ON clause specifies variable-length tables.
data-name-1
Identifies the object of the OCCURS DEPENDING ON clause; that is, the
data item whose current value represents the current number of
occurrences of the subject item. The contents of items whose occurrence
numbers exceed the value of the object are undefined.
The object of the OCCURS DEPENDING ON clause (data-name-1) must
describe an integer data item.
The object of the OCCURS DEPENDING ON clause must not occupy any
storage position within the range of the table (that is, any storage position
from the first character position in the table through the last character
position in the table).
The object of the OCCURS DEPENDING ON clause cannot be variably
located; the object cannot follow an item that contains an OCCURS
DEPENDING ON clause.
If the OCCURS clause is specified in a data description entry included in a
record description entry that contains the EXTERNAL clause, data-name-1,
if specified, must reference a data item that possesses the external attribute.
data-name-1 must be described in the same DATA DIVISION as the subject
of the entry.
If the OCCURS clause is specified in a data description entry subordinate
to one that contains the GLOBAL clause, data-name-1, if specified, must be
a global name. data-name-1 must be described in the same DATA DIVISION
as the subject of the entry.

All data-names used in the OCCURS clause can be qualified; they cannot be
subscripted or indexed.

At the time that the group item, or any data item that contains a subordinate
OCCURS DEPENDING ON item or that follows but is not subordinate to the
OCCURS DEPENDING ON item, is referenced, the value of the object of the
OCCURS DEPENDING ON clause must fall within the range integer-1 through
integer-2, if integer-2 is specified (that is, if the table is not UNBOUNDED).

Chapter 18. DATA DIVISION--data description entry 201

 The behavior is undefined if the value of the object is outside of the range integer-1
through integer-2.

When a group item that contains a subordinate OCCURS DEPENDING ON item is

referred to, the part of the table area used in the operation is determined as
follows:
v If the object is outside the group, only that part of the table area that is specified
by the object at the start of the operation is used.
v If the object is included in the same group and the group data item is referenced
as a sending item, only that part of the table area that is specified by the value
of the object at the start of the operation is used in the operation.
v If the object is included in the same group and the group data item is referenced
as a receiving item, the maximum length of the group item is used in the
operation.

The following statements are affected by the maximum length rule:

v ACCEPT identifier (format 1 and 2)
v CALL ... USING BY REFERENCE identifier
v INVOKE ... USING BY REFERENCE identifier
v MOVE ... TO identifier
v READ ... INTO identifier
v RELEASE identifier FROM ...
v RETURN ... INTO identifier
v REWRITE identifier FROM ...
v STRING ... INTO identifier
v UNSTRING ... INTO identifier DELIMITER IN identifier
v WRITE identifier FROM ...

If a variable-length group item is not followed by a nonsubordinate item, the

maximum length of the group is used when it appears as the identifier in CALL ...
USING BY REFERENCE identifier. Therefore, the object of the OCCURS
DEPENDING ON clause does not need to be set unless the group is variably
located.

If the group item is followed by a nonsubordinate item, the actual length, rather
than the maximum length, is used. At the time the subject of entry is referenced, or
any data item subordinate or superordinate to the subject of entry is referenced,
the object of the OCCURS DEPENDING ON clause must fall within the range
integer-1 through integer-2, if integer-2 is specified.

Note:

The maximum length rule does not apply to unbounded groups. For unbounded
groups, based on the current run time value of the OCCURS DEPENDING ON
objects, the actual length of the group is used for all references to the group.
Consequently, before any COBOL statement that references an unbounded group
runs, you must set the OCCURS DEPENDING ON objects for that group.

Certain uses of the OCCURS DEPENDING ON clause result in complex OCCURS

DEPENDING ON (ODO) items. The following items constitute complex ODO
items:

202 Enterprise COBOL for z/OS, V6.1 Language Reference

 v A data item described with an OCCURS DEPENDING ON clause that is
followed by a nonsubordinate elementary data item, described with or without
an OCCURS clause
v A data item described with an OCCURS DEPENDING ON clause that is
followed by a nonsubordinate group item
v A group item that contains one or more subordinate items described with an
OCCURS DEPENDING ON clause
v A data item described with an OCCURS clause or an OCCURS DEPENDING
ON clause that contains a subordinate data item described with an OCCURS
DEPENDING ON clause (a table that contains variable-length elements)
v An index-name associated with a table that contains variable-length elements

The object of an OCCURS DEPENDING ON clause cannot be a nonsubordinate

item that follows a complex ODO item.

Any nonsubordinate item that follows an item described with an OCCURS

DEPENDING ON clause is a variably located item. That is, its location is affected by
the value of the OCCURS DEPENDING ON object.

When implicit redefinition is used in a File Description (FD) entry, subordinate

level items can contain OCCURS DEPENDING ON clauses.

The INDEXED BY phrase can be specified for a table that has a subordinate item
that contains an OCCURS DEPENDING ON clause.

For more information about complex OCCURS DEPENDING ON, see Complex
OCCURS DEPENDING ON in the Enterprise COBOL Programming Guide.

The ASCENDING KEY phrase, the DESCENDING KEY phrase, and the INDEXED
BY clause are described under “Fixed-length tables” on page 196.

PICTURE clause
The PICTURE clause specifies the general characteristics and editing requirements
of an elementary item.

Format

►► PICTURE character-string ►◄
PIC IS

PICTURE or PIC
The PICTURE clause must be specified for every elementary item except
the following ones:
v Index data items
v The subject of the RENAMES clause
v Items described with USAGE POINTER, USAGE FUNCTION-POINTER,
USAGE PROCEDURE-POINTER, or USAGE OBJECT REFERENCE
v Internal floating-point data items

Chapter 18. DATA DIVISION--data description entry 203

 In these cases, use of the PICTURE clause is prohibited.
The PICTURE clause can be specified only at the elementary level.
PIC is an abbreviation for PICTURE and has the same meaning.
character-string
character-string is made up of certain COBOL characters used as picture
symbols. The allowable combinations determine the category of the
elementary data item.
character-string can contain a maximum of 50 characters.

Symbols used in the PICTURE clause

Any punctuation character that appears within the PICTURE character-string is not
considered a punctuation character, but rather is a PICTURE character-string
symbol.

When specified in the SPECIAL-NAMES paragraph, DECIMAL-POINT IS

COMMA exchanges the functions of the period and the comma in PICTURE
character-strings and in numeric literals.

The lowercase letters that correspond to the uppercase letters that represent the
following PICTURE symbols are equivalent to their uppercase representations in a
PICTURE character-string:
A, B, E, G, N, P, S, V, X, Z, CR, DB

All other lowercase letters are not equivalent to their corresponding uppercase
representations.

Table 12 defines the meaning of each PICTURE clause symbol. The heading Size
indicates how the item is counted in determining the number of character positions
in the item. The type of the character positions depends on the USAGE clause
specified for the item, as follows:

Usage Type of character positions Number of bytes per character

DISPLAY Alphanumeric 1
DISPLAY-1 DBCS 2
NATIONAL National 2
All others Conceptual Not applicable

Table 12. PICTURE clause symbol meanings

Symbol Meaning Size
A A character position that can contain only a letter Each 'A' is counted as one character position in the
of the Latin alphabet or a space. size of the data item.
B For usage DISPLAY, a character position into Each 'B' is counted as one character position in the
which an alphanumeric space is inserted. size of the data item.

For usage DISPLAY-1, a character position into

which a DBCS space is inserted.

For usage NATIONAL, a character position into

which a national space is inserted.

204 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 12. PICTURE clause symbol meanings (continued)
Symbol Meaning Size
E Marks the start of the exponent in an external Each 'E' is counted as one character position in the
floating-point item. For additional details of size of the data item.
external floating-point items, see “Data categories
and PICTURE rules” on page 209.
G A DBCS character position. Each 'G' is counted as one character position in the
size of the data item.
N A DBCS character position when specified with Each 'N' is counted as one character position in the
usage DISPLAY-1 or when usage is unspecified size of the data item.
and the NSYMBOL(DBCS) compiler option is in
effect.

For category national, a national character position

when specified with usage NATIONAL or when
usage is unspecified and the
NSYMBOL(NATIONAL) compiler option is in
effect.

For category national-edited, a national character

position.
P An assumed decimal scaling position. Used to Not counted in the size of the data item. Scaling
specify the location of an assumed decimal point position characters are counted in determining the
when the point is not within the number that maximum number of digit positions in
appears in the data item. See “P symbol” on page numeric-edited items or in items that are used as
207 for further details. arithmetic operands.

The size of the value is the number of digit

positions represented by the PICTURE
character-string.
S An indicator of the presence (but not the Not counted in the size of the elementary item,
representation, and not necessarily the position) of unless an associated SIGN clause specifies the
an operational sign. An operational sign indicates SEPARATE CHARACTER phrase (which would be
whether the value of an item involved in an counted as one character position).
operation is positive or negative.
V An indicator of the location of the assumed Not counted in the size of the elementary item.
decimal point. Does not represent a character
position.

When the assumed decimal point is to the right of

the rightmost symbol in the string, the V is
redundant.
X A character position that can contain any Each 'X' is counted as one character position in the
allowable character from the alphanumeric size of the data item.
character set of the computer.
Z A leading numeric character position. When that Each 'Z' is counted as one character position in the
position contains a zero, a space character replaces size of the data item.
the zero.
9 A character position that contains a numeral. Each nine specifies one decimal digit in the value
of the item. For usages DISPLAY and NATIONAL,
each nine is counted as one character position in
the size of the data item.
0 A character position into which the numeral zero Each zero is counted as one character position in
is inserted. the size of the data item.
/ A character position into which the slash character Each slash character is counted as one character
is inserted. position in the size of the data item.

Chapter 18. DATA DIVISION--data description entry 205

Table 12. PICTURE clause symbol meanings (continued)
Symbol Meaning Size
, A character position into which a comma is Each comma is counted as one character position
inserted. in the size of the data item.
. An editing symbol that represents the decimal Each period is counted as one character position in
point for alignment purposes. In addition, it the size of the data item.
represents a character position into which a period
is inserted.
+ Editing sign control symbols. Each represents the Each character used in the editing sign symbol is
- character position into which the editing sign counted as one character position in the size of the
CR control symbol is placed. data item.
DB

* A check protect symbol: a leading numeric Each asterisk is counted as one character position
character position into which an asterisk is placed in the size of the item.
when that position contains a zero.
cs cs can be any valid currency symbol. A currency The first occurrence of a currency symbol adds the
symbol represents a character position into which number of characters in the currency sign value to
a currency sign value is placed. The default the size of the data item. Each subsequent
currency symbol is the character assigned the occurrence adds one character position to the size
value X'5B' in the code page in effect at compile of the data item.
time. In this document, the default currency
symbol is represented by the dollar sign ($) and cs
stands for any valid currency symbol. For details,
see “Currency symbol” on page 208.

The following figure shows the sequences in which picture symbols can be
specified to form picture character-strings. More detailed explanations of PICTURE
clause symbols follow the figure.

206 Enterprise COBOL for z/OS, V6.1 Language Reference

P symbol

The symbol P specifies a scaling position and implies an assumed decimal point
(to the left of the Ps if the Ps are leftmost PICTURE characters; to the right of the
Ps if the Ps are rightmost PICTURE characters).

The assumed decimal point symbol V is redundant as either the leftmost or

rightmost character within such a PICTURE description.

The symbol P can be specified only as a continuous string of Ps in the leftmost or

rightmost digit positions within a PICTURE character-string.

Chapter 18. DATA DIVISION--data description entry 207

 In certain operations that reference a data item whose PICTURE character-string
contains the symbol P, the algebraic value of the data item is used rather than the
actual character representation of the data item. This algebraic value assumes the
decimal point in the prescribed location and zero in place of the digit position
specified by the symbol P. The size of the value is the number of digit positions
represented by the PICTURE character-string. These operations are any of the
following ones:
v Any operation that requires a numeric sending operand
v A MOVE statement where the sending operand is numeric and its PICTURE
character-string contains the symbol P
v A MOVE statement where the sending operand is numeric-edited and its
PICTURE character-string contains the symbol P, and the receiving operand is
numeric or numeric-edited
v A comparison operation where both operands are numeric

In all other operations, the digit positions specified with the symbol P are ignored
and are not counted in the size of the operand.

Currency symbol

The currency symbol in a picture character-string is represented by the default

currency symbol $ or by a single character specified either in the CURRENCY
compiler option or in the CURRENCY SIGN clause in the SPECIAL-NAMES
paragraph of the ENVIRONMENT DIVISION.

Although the default currency symbol is represented by $ in this document, the

actual default currency symbol is the character with the value X'5B' in the EBCDIC
code page in effect at compile time.

If the CURRENCY SIGN clause is specified, the CURRENCY and NOCURRENCY

compiler options are ignored. If the CURRENCY SIGN clause is not specified and
the NOCURRENCY compiler option is in effect, the dollar sign ($) is used as the
default currency sign value and currency symbol. For more information about the
CURRENCY SIGN clause, see “CURRENCY SIGN clause” on page 122. For more
information about the CURRENCY and NOCURRENCY compiler options, see
CURRENCY in the Enterprise COBOL Programming Guide.

A currency symbol can be repeated within the PICTURE character-string to specify

floating insertion. Different currency symbols must not be used in the same
PICTURE character-string.

Unlike all other picture symbols, currency symbols are case sensitive. For example,
'D' and 'd' specify different currency symbols.

A currency symbol can be used only to define a numeric-edited item with USAGE
DISPLAY.

Character-string representation
The topic lists symbols that can appear once or more than once in the PICTURE
character-string.
Symbols that can appear more than once
The following symbols can appear more than once in one PICTURE
character-string:
A B G N P X Z 9 0 / , + – * cs

208 Enterprise COBOL for z/OS, V6.1 Language Reference

 At least one of the symbols A, G, N, X, Z, 9, or *, or at least two of the
symbols +, –, or cs must be present in a PICTURE string.
An unsigned nonzero integer enclosed in parentheses immediately
following any of these symbols specifies the number of consecutive
occurrences of that symbol.
Example: The following two PICTURE clause specifications are equivalent:
PICTURE IS $99999.99CR
PICTURE IS $9(5).9(2)CR
Symbols that can appear only once
The following symbols can appear only once in one PICTURE
character-string:
E S V . CR DB

Except for the PICTURE symbol V, each occurrence of any of the above
symbols in a given PICTURE character-string represents an occurrence of
that character or set of allowable characters in the data item.

Data categories and PICTURE rules

The allowable combinations of PICTURE symbols determine the data category of
the item.

The data categories are:

v Alphabetic
v Numeric
v Numeric-edited
v Alphanumeric
v Alphanumeric-edited
v DBCS
v External floating-point
v National
v National-edited

Note: Category internal floating point is defined by a USAGE clause that specifies
the COMP-1 or COMP-2 phrase.

Alphabetic items

The PICTURE character-string can contain only the symbol A.

The content of the item must consist only of letters of the Latin alphabet and the
space character.
Other clauses
USAGE DISPLAY must be specified or implied.
Any associated VALUE clause must specify an alphanumeric literal
containing only alphabetic characters, SPACE, or a symbolic-character as
the value of a figurative constant.
Do not include a single byte character in a DBCS data item.
When padding is required for a DBCS data item, the following rules apply:

Chapter 18. DATA DIVISION--data description entry 209

 v Padding is done using double-byte space characters until the data area is
filled (based on the number of double-byte character positions allocated
for the data item).
v Padding is done using single-byte space characters when the padding
needed is not an even number of bytes (for example, when an
alphanumeric group item is moved to a DBCS data item).

Numeric items
There are several types of numeric items.

The types are:

v Binary
v Packed decimal (internal decimal)
v Zoned decimal (external decimal)
v National decimal (external decimal)

The type of a numeric item is defined by the usage clause as shown in the table
below.
Table 13. Numeric types
Type USAGE clause
Binary BINARY, COMP, COMP-4, or COMP-5
Internal decimal PACKED-DECIMAL, COMP-3
Zoned decimal (external decimal) DISPLAY
National decimal (external decimal) NATIONAL

For all numeric fields, the PICTURE character-string can contain only the symbols
9, P, S, and V.

The symbol S can be written only as the leftmost character in the PICTURE
character-string.

The symbol V can be written only once in a given PICTURE character-string.

For binary items, the number of digit positions must range from 1 through 18
inclusive. For packed decimal and zoned decimal items the number of digit
positions must range from 1 through 18, inclusive, when the ARITH(COMPAT)
compiler option is in effect, or from 1 through 31, inclusive, when the
ARITH(EXTEND) compiler option is in effect.

If unsigned, the contents of the item in standard data format must contain a
combination of the Arabic numerals 0-9. If signed, it can also contain a +, -, or
other representation of the operational sign.
Examples of valid ranges
PICTURE Valid range of values
9999 0 through 9999
S99 -99 through +99
S999V9 -999.9 through +999.9
PPP999 0 through .000999
S999PPP -1000 through -999000 and
+1000 through +999000 or zero
Other clauses

210 Enterprise COBOL for z/OS, V6.1 Language Reference

 The USAGE of the item can be DISPLAY, NATIONAL, BINARY,
COMPUTATIONAL, PACKED-DECIMAL, COMPUTATIONAL-3,
COMPUTATIONAL-4, or COMPUTATIONAL-5.
For signed numeric items described with usage NATIONAL, the SIGN IS
SEPARATE clause must be specified or implied.
The NUMPROC and TRUNC compiler options can affect the use of
numeric data items. For details, see NUMPROC and TRUNC in the
Enterprise COBOL Programming Guide.

Numeric-edited items
The PICTURE character-string can contain certain symbols.

The symbols are:

B P V Z 9 0 / , . + - CR DB * cs

The combinations of symbols allowed are determined from the PICTURE clause
symbol order allowed (see the figure in “Symbols used in the PICTURE clause” on
page 204), and the editing rules (see “PICTURE clause editing” on page 215).

The following rules apply:

v Either the BLANK WHEN ZERO clause must be specified for the item, or the
string must contain at least one of the following symbols:
B / Z 0 , . * + - CR DB cs
v Only one of the following symbols can be written in a given PICTURE
character-string:
+ - CR DB
v If the ARITH(COMPAT) compiler option is in effect, then the number of digit
positions represented in the character-string must be in the range 1 through 18,
inclusive. If the ARITH(EXTEND) compiler option is in effect, then the number
of digit positions represented in the character-string must be in the range 1
through 31, inclusive.
v The total number of character positions in the string (including editing-character
positions) must not exceed 249.
v The contents of those character positions representing digits in standard data
format must be one of the 10 Arabic numerals.
Other clauses
USAGE DISPLAY or NATIONAL must be specified or implied.
If the usage of the item is DISPLAY, any associated VALUE clause must
specify an alphanumeric literal or a figurative constant. The value is
assigned without editing.
If the usage of the item is NATIONAL, any associated VALUE clause must
specify an alphanumeric literal, a national literal, or a figurative constant.
The value is assigned without editing.

Alphanumeric items

The PICTURE character-string must consist of certain symbols.

The symbols are:

v One or more occurrences of the symbol X.

Chapter 18. DATA DIVISION--data description entry 211

 v Combinations of the symbols A, X, and 9. (A character-string containing all As
or all 9s does not define an alphanumeric item.)

The item is treated as if the character-string contained only the symbol X.

The contents of the item in standard data format can be any allowable characters
from the character set of the computer.
Other clauses
USAGE DISPLAY must be specified or implied.
Any associated VALUE clause must specify an alphanumeric literal or one
of the following figurative constants:
v ZERO
v SPACE
v QUOTE
v HIGH-VALUE
v LOW-VALUE
v symbolic-character
v ALL alphanumeric-literal

Alphanumeric-edited items

The PICTURE character-string can contain the following symbols: A X 9 B 0 /.

The string must contain at least one A or X, and at least one B or 0 (zero) or /.

The contents of the item in standard data format must be two or more characters
from the character set of the computer.
Other clauses
USAGE DISPLAY must be specified or implied.
Any associated VALUE clause must specify an alphanumeric literal or or
one of the following figurative constants:
v ZERO
v SPACE
v QUOTE
v HIGH-VALUE
v LOW-VALUE
v symbolic-character
v ALL alphanumeric-literal
The literal is treated exactly as specified; no editing is done.

DBCS items

The PICTURE character-string can contain the symbols G, G and B, or N. Each G, B,

or N represents a single DBCS character position.

Any associated VALUE clause must contain a DBCS literal, the figurative constant
SPACE, or the figurative constant ALL DBCS-literal.
Other clauses

212 Enterprise COBOL for z/OS, V6.1 Language Reference

 When PICTURE symbol G is used, USAGE DISPLAY-1 must be specified.
When PICTURE symbol N is used and the NSYMBOL(DBCS) compiler
option is in effect, USAGE DISPLAY-1 is implied if the USAGE clause is
omitted.

National items

The PICTURE character-string can contain one or more occurrences of the picture
symbol N.

These rules apply when the NSYMBOL(NATIONAL) compiler option is in effect or

the USAGE NATIONAL clause is specified. In the absence of a USAGE
NATIONAL clause, if the NSYMBOL(DBCS) compiler option is in effect, picture
symbol N represents a DBCS character and the rules of the PICTURE clause for a
DBCS item apply.

Each N represents a single national character position.

Any associated VALUE clause must specify an alphanumeric literal, a national

literal, or one of the following figurative constants:
v ZERO
v SPACE
v QUOTE
v HIGH-VALUE
v LOW-VALUE
v symbolic-character
v ALL alphanumeric-literal
v ALL national-literal
Other clauses
Only the NATIONAL phrase can be specified in the USAGE clause. When
PICTURE symbol N is used and the NSYMBOL(NATIONAL) compiler
option is in effect, USAGE NATIONAL is implied if the usage clause is
omitted.
The following clauses can be used:
v JUSTIFIED
v EXTERNAL
v GLOBAL
v OCCURS
v REDEFINES
v RENAMES
v SYNCHRONIZED
The following clauses cannot be used:
v BLANK WHEN ZERO
v SIGN

National-edited items

The PICTURE character-string must contain at least one symbol N, and at least one
instance of one of these symbols: B 0 (zero) or / (slash).

Chapter 18. DATA DIVISION--data description entry 213

 Each symbol represents a single national character position.

Any associated VALUE clause must specify an alphanumeric literal, a national

literal, or one of the following figurative constants:
v ZERO
v SPACE
v QUOTE
v HIGH-VALUE
v LOW-VALUE
v symbolic-character
v ALL alphanumeric-literal
v ALL national-literal

The literal is treated exactly as specified; no editing is done.

The NSYMBOL(NATIONAL) compiler option has no effect on the definition of a

data item of category national-edited.
Other clauses
USAGE NATIONAL must be specified or implied.
The following clauses can be used:
v JUSTIFIED
v EXTERNAL
v GLOBAL
v OCCURS
v REDEFINES
v RENAMES
v SYNCHRONIZED
The following clauses cannot be used:
v BLANK WHEN ZERO
v SIGN

External floating-point items

A data item is described as category external floating-point by its PICTURE
character-string.

The PICTURE character-string details are described below.

Format

►► + mantissa E + exponent ►◄
- -

+ or - A sign character must immediately precede both the mantissa and the
exponent.

214 Enterprise COBOL for z/OS, V6.1 Language Reference

 A + sign indicates that a positive sign will be used in the output to
represent positive values and that a negative sign will represent negative
values.
A - sign indicates that a blank will be used in the output to represent
positive values and that a negative sign will represent negative values.
Each sign position occupies one byte of storage.
mantissa
The mantissa can contain the symbols:
9 . V

An actual decimal point can be represented with a period (.) while an

assumed decimal point is represented by a V.
Either an actual or an assumed decimal point must be present in the
mantissa; the decimal point can be leading, embedded, or trailing.
The mantissa can contain from 1 to 16 numeric characters.
E Indicates the exponent.
exponent
The exponent must consist of the symbol 99.

Example: Pic -9v9(9)E-99

The DISPLAY phrase of the USAGE clause and a floating-point picture

character-string define the item as a display floating-point data item.

The NATIONAL phrase of the USAGE clause and a floating-point picture

character-string define the item as a national floating-point data item.

For items defined with usage DISPLAY, each picture symbol except V defines one
alphanumeric character position in the item.

For items defined with usage NATIONAL, each picture symbol except V defines
one national character position in the item.
Other clauses
The DISPLAY phrase or the NATIONAL phrase of the USAGE clause must
be specified or implied.
The OCCURS, REDEFINES, and RENAMES clauses can be associated with
external floating-point items.
The SIGN clause is accepted as documentation and has no effect on the
representation of the sign.
The SYNCHRONIZED clause is treated as documentation.
The following clauses are invalid with external floating-point items:
v BLANK WHEN ZERO
v JUSTIFIED
v VALUE

PICTURE clause editing

There are two general methods of editing in a PICTURE clause, insertion editing,
and suppression and replacement editing.

Chapter 18. DATA DIVISION--data description entry 215

 Insertion editing includes the following types of editing:
v Simple insertion
v Special insertion
v Fixed insertion
v Floating insertion

Suppression and replacement editing includes the following types of editing:

v Zero suppression and replacement with asterisks
v Zero suppression and replacement with spaces

The type of editing allowed for an item depends on its data category. The type of
editing that is valid for each category is shown in the following table. cs indicates
any valid currency symbol.
Table 14. Data categories
Data category Type of editing Insertion symbol
Alphabetic None None
Numeric None None
Numeric-edited Simple insertion B0/,

Special insertion .

Fixed insertion cs + - CR DB

Floating insertion cs + -

Zero suppression Z*

Replacement Z * + - cs
Alphanumeric None None
Alphanumeric-edited Simple insertion B0/
DBCS Simple insertion B
External floating-point Special insertion .
National None None
National-edited Simple insertion B0/

Types of editing are described in the following sections:

v “Simple insertion editing”
v “Special insertion editing” on page 217
v “Fixed insertion editing” on page 217
v “Floating insertion editing” on page 218
v “Zero suppression and replacement editing” on page 219

Simple insertion editing

This type of editing is valid for alphanumeric-edited, numeric-edited, and DBCS
items.

Each insertion symbol is counted in the size of the item, and represents the
position within the item where the equivalent character is to be inserted. For
edited DBCS items, each insertion symbol (B) is counted in the size of the item and
represents the position within the item where the DBCS space is to be inserted.
216 Enterprise COBOL for z/OS, V6.1 Language Reference
 For example:

PICTURE Value of data Edited result

X(10)/XX ALPHANUMER01 ALPHANUMER/01
X(5)BX(7) ALPHANUMERIC ALPHA NUMERIC
99,B999,B000 1234 01,b234,b0001
99,999 12345 12,345
GGBBGG D1D2D3D4 D1D2bbbbD3D41

Notes:
1. The symbol b represents a space.

Special insertion editing

This type of editing is valid for either numeric-edited items or external
floating-point items.

The period (.) is the special insertion symbol; it also represents the actual decimal
point for alignment purposes.

The period insertion symbol is counted in the size of the item, and represents the
position within the item where the actual decimal point is inserted.

Either the actual decimal point or the symbol V as the assumed decimal point, but
not both, must be specified in one PICTURE character-string.

For example:

PICTURE Value of data Edited result

999.99 1.234 001.23
999.99 12.34 012.34
999.99 123.45 123.45
999.99 1234.5 234.50
+999.99E+99 12345 +123.45E+02

Fixed insertion editing

Fixed insertion editing is valid only for numeric-edited items.

The following insertion symbols are used:

v cs
v + - CR DB (editing-sign control symbols)

In fixed insertion editing, only one currency symbol and one editing-sign control
symbol can be specified in a PICTURE character-string.

Unless it is preceded by a + or - symbol, the currency symbol must be the first

character in the character-string.

When either + or - is used as a symbol, it must be the first or last character in the
character-string.

Chapter 18. DATA DIVISION--data description entry 217

 When CR or DB is used as a symbol, it must occupy the rightmost two character
positions in the character-string. If these two character positions contain the
symbols CR or DB, the uppercase letters are the insertion characters.

Editing sign control symbols produce results that depend on the value of the data
item, as shown below:

Editing symbol in PICTURE Result: data item positive or

character-string zero Result: data item negative
+ + -
- space -
CR 2 spaces CR
DB 2 spaces DB

For example:

PICTURE Value of data Edited result

999.99+ +6555.556 555.55+
+9999.99 -6555.555 -6555.55
9999.99 +1234.56 1234.56
$999.99 -123.45 $123.45
-$999.99 -123.456 -$123.45
-$999.99 +123.456 $123.45
$9999.99CR +123.45 $0123.45
$9999.99CR -123.45 $0123.45CR

Floating insertion editing

Floating insertion editing is valid only for numeric-edited items.

The following symbols are used:

cs + -

Within one PICTURE character-string, these symbols are mutually exclusive as

floating insertion characters.

Floating insertion editing is specified by using a string of at least two of the

allowable floating insertion symbols to represent leftmost character positions into
which the actual characters can be inserted.

The leftmost floating insertion symbol in the character-string represents the

leftmost limit at which the actual character can appear in the data item. The
rightmost floating insertion symbol represents the rightmost limit at which the
actual character can appear.

The second leftmost floating insertion symbol in the character-string represents the
leftmost limit at which numeric data can appear within the data item. Nonzero
numeric data can replace all characters at or to the right of this limit.

Any simple-insertion symbols (B 0 / ,) within or to the immediate right of the

string of floating insertion symbols are considered part of the floating

218 Enterprise COBOL for z/OS, V6.1 Language Reference

 character-string. If the period (.) special-insertion symbol is included within the
floating string, it is considered to be part of the character-string.

To avoid truncation, the minimum size of the PICTURE character-string must be:
v The number of character positions in the sending item, plus
v The number of nonfloating insertion symbols in the receiving item, plus
v One character position for the floating insertion symbol

Representing floating insertion editing

In a PICTURE character-string, there are two ways to represent floating insertion

editing and thus two ways in which editing is performed:
1. Any or all leading numeric character positions to the left of the decimal point
are represented by the floating insertion symbol. When editing is performed, a
single floating insertion character is placed to the immediate left of the first
nonzero digit in the data, or of the decimal point, whichever is farther to the
left. The character positions to the left of the inserted character are filled with
spaces.
If all numeric character positions in the PICTURE character-string are
represented by the insertion character, then at least one of the insertion
characters must be to the left of the decimal point.
2. All the numeric character positions are represented by the floating insertion
symbol. When editing is performed, then:
v If the value of the data is zero, the entire data item will contain spaces.
v If the value of the data is nonzero, the result is the same as in rule 1.

For example:

PICTURE Value of data Edited result

$$$$.99 .123 $.12

$$$9.99 .12 $0.12

$,$$$,999.99 -1234.56 $1,234.56

+,+++,999.99 -123456.789 -123,456.78

$$,$$$,$$$.99CR -1234567 $1,234,567.00CR

++,+++,+++.+++ 0000.00

Zero suppression and replacement editing

Zero suppression and replacement editing is valid only for numeric-edited items.

In zero suppression editing, the symbols Z and * are used. These symbols are
mutually exclusive in one PICTURE character-string.

The following symbols are mutually exclusive as floating replacement symbols in

one PICTURE character-string:

Z * + - cs

Chapter 18. DATA DIVISION--data description entry 219

 Specify zero suppression and replacement editing with a string of one or more of
the allowable symbols to represent leftmost character positions in which zero
suppression and replacement editing can be performed.

Any simple insertion symbols (B 0 / ,) within or to the immediate right of the

string of floating editing symbols are considered part of the string. If the period (.)
special insertion symbol is included within the floating editing string, it is
considered to be part of the character-string.

Representing zero suppression

In a PICTURE character-string, there are two ways to represent zero suppression,

and two ways in which editing is performed:
1. Any or all of the leading numeric character positions to the left of the decimal
point are represented by suppression symbols. When editing is performed, the
replacement character replaces any leading zero in the data that appears in the
same character position as a suppression symbol. Suppression stops at the
leftmost character:
v That does not correspond to a suppression symbol
v That contains nonzero data
v That is the decimal point
2. All the numeric character positions in the PICTURE character-string are
represented by the suppression symbols. When editing is performed and the
value of the data is nonzero, the result is the same as in the preceding rule. If
the value of the data is zero, then:
v If Z has been specified, the entire data item will contain spaces.
v If * has been specified, the entire data item except the actual decimal point
will contain asterisks.

For example:

PICTURE Value of data Edited result

****.** 0000.00 ****.**

ZZZZ.ZZ 0000.00

ZZZZ.99 0000.00 .00

****.99 0000.00 ****.00

ZZ99.99 0000.00 00.00

Z,ZZZ.ZZ+ +123.456 123.45+

*,***.**+ -123.45 **123.45-

**,***,***.**+ +12345678.9 12,345,678.90+

$Z,ZZZ,ZZZ.ZZCR +12345.67 $ 12,345.67

$B*,***,***.**BBDB -12345.67 $ ***12,345.67 DB

Do not specify both the asterisk (*) as a suppression symbol and the BLANK
WHEN ZERO clause for the same entry.

220 Enterprise COBOL for z/OS, V6.1 Language Reference

REDEFINES clause
The REDEFINES clause allows you to use different data description entries to
describe the same computer storage area.

Format

►► level-number REDEFINES data-name-2 ►◄

data-name-1
FILLER

(level-number, data-name-1, and FILLER are not part of the REDEFINES clause, and
are included in the format only for clarity.)

When specified, the REDEFINES clause must be the first entry following
data-name-1 or FILLER. If data-name-1 or FILLER is not specified, the REDEFINES
clause must be the first entry following the level-number.
data-name-1, FILLER
Identifies an alternate description for the data area identified by
data-name-2; data-name-1 is the redefining item or the REDEFINES subject.
Neither data-name-1 nor any of its subordinate entries can contain a VALUE
clause.
data-name-2
Identifies the redefined item or the REDEFINES object.
The data description entry for data-name-2 can contain a REDEFINES
clause.
The data description entry for data-name-2 cannot contain an OCCURS
clause. However, data-name-2 can be subordinate to an item whose data
description entry contains an OCCURS clause; in this case, the reference to
data-name-2 in the REDEFINES clause must not be subscripted.

Neither data-name-1 nor data-name-2 can contain an OCCURS DEPENDING ON

clause.

data-name-1 and data-name-2 must have the same level in the hierarchy; however,
the level numbers need not be the same. Neither data-name-1 nor data-name-2 can
be defined with level number 66 or 88.

data-name-1 and data-name-2 can each be described with any usage.

Redefinition begins at data-name-1 and ends when a level-number less than or

equal to that of data-name-1 is encountered. No entry that has a level-number
numerically lower than those of data-name-1 and data-name-2 can occur between
these entries. In the following example:
05 A PICTURE X(6).
05 B REDEFINES A.
10 B-1 PICTURE X(2).
10 B-2 PICTURE 9(4).
05 C PICTURE 99V99.

Chapter 18. DATA DIVISION--data description entry 221

 A is the redefined item, and B is the redefining item. Redefinition begins with B and
includes the two subordinate items B-1 and B-2. Redefinition ends when the
level-05 item C is encountered.

If the GLOBAL clause is used in the data description entry that contains the
REDEFINES clause, only data-name-1 (the redefining item) possesses the global
attribute. For example, in the following description, only item B possesses the
GLOBAL attribute:
05 A PICTURE X(6).
05 B REDEFINES A GLOBAL PICTURE X(4).

The EXTERNAL clause must not be specified in the same data description entry as
a REDEFINES clause.

If the redefined data item (data-name-2) is declared to be an external data record,

the size of the redefining data item (data-name-1) must not be greater than the size
of the redefined data item. If the redefined data item is not declared to be an
external data record, there is no such constraint.

The following example shows that the redefining item, B, can occupy more storage
than the redefined item, A. The size of storage for the REDEFINED clause is
determined in number of bytes. Item A occupies 6 bytes of storage and item B, a
data item of category national, occupies 8 bytes of storage.
05 A PICTURE X(6).
05 B REDEFINES A GLOBAL PICTURE N(4).

One or more redefinitions of the same storage area are permitted. The entries that
give the new descriptions of the storage area must immediately follow the
description of the redefined area without intervening entries that define new
character positions. Multiple redefinitions can, but need not, all use the data-name
of the original entry that defined this storage area. For example:
05 A PICTURE 9999.
05 B REDEFINES A PICTURE 9V999.
05 C REDEFINES A PICTURE 99V99.

Also, multiple redefinitions can use the name of the preceding definition as shown
in the following example:
05 A PICTURE 9999.
05 B REDEFINES A PICTURE 9V999.
05 C REDEFINES B PICTURE 99V99.

When more than one level-01 entry is written subordinate to an FD entry, a

condition known as implicit redefinition occurs. That is, the second level-01 entry
implicitly redefines the storage allotted for the first entry. In such level-01 entries,
the REDEFINES clause must not be specified.

When the data item implicitly redefines multiple 01-level records in a file
description (FD) entry, items subordinate to the redefining or redefined item can
contain an OCCURS DEPENDING ON clause.

REDEFINES clause considerations

The topic lists considerations of using the REDEFINES clause.

When an area is redefined, all descriptions of the area are always in effect; that is,
redefinition does not supersede a previous description. Thus, if B REDEFINES C has
been specified, either of the two procedural statements MOVE X TO B or MOVE Y TO C

222 Enterprise COBOL for z/OS, V6.1 Language Reference

 could be executed at any point in the program. In the first case, the area described
as B would receive the value and format of X. In the second case, the same physical
area (described now as C) would receive the value and format of Y. Note that if the
second statement is executed immediately after the first, the value of Y replaces the
value of X in the one storage area.

The usage of a redefining data item need not be the same as that of a redefined
item. This does not, however, cause any change in the format or content of existing
data. For example:
05 B PICTURE 99 USAGE DISPLAY VALUE 8.
05 C REDEFINES B PICTURE S99 USAGE COMPUTATIONAL-4.
05 A PICTURE S99 USAGE COMPUTATIONAL-4.

Redefining B does not change the bit configuration of the data in the storage area.
Therefore, the following two statements produce different results:
ADD B TO A
ADD C TO A

In the first case, the value 8 is added to A (because B has USAGE DISPLAY). In the
second statement, the value -3848 is added to A (because C has USAGE
COMPUTATIONAL-4), and the bit configuration of the storage area has the binary
value -3848. This example demonstrates how the improper use of redefinition can
give unexpected or incorrect results.

REDEFINES clause examples

The REDEFINES clause can be specified for an item within the scope of
(subordinate to) an area that is redefined.

In the following example, WEEKLY-PAY redefines SEMI-MONTHLY-PAY (which is within

the scope of REGULAR-EMPLOYEE, while REGULAR-EMPLOYEE is redefined by
TEMPORARY-EMPLOYEE).
05 REGULAR-EMPLOYEE.
10 LOCATION PICTURE A(8).
10 GRADE PICTURE X(4).
10 SEMI-MONTHLY-PAY PICTURE 9999V99.
10 WEEKLY-PAY REDEFINES SEMI-MONTHLY-PAY
PICTURE 999V999.
05 TEMPORARY-EMPLOYEE REDEFINES REGULAR-EMPLOYEE.
10 LOCATION PICTURE A(8).
10 FILLER PICTURE X(6).
10 HOURLY-PAY PICTURE 99V99.

The REDEFINES clause can also be specified for an item subordinate to a

redefining item, as shown for CODE-H REDEFINES HOURLY-PAY in the following
example:
05 REGULAR-EMPLOYEE.
10 LOCATION PICTURE A(8).
10 GRADE PICTURE X(4).
10 SEMI-MONTHLY-PAY PICTURE 999V999.
05 TEMPORARY-EMPLOYEE REDEFINES REGULAR-EMPLOYEE.
10 LOCATION PICTURE A(8).
10 FILLER PICTURE X(6).
10 HOURLY-PAY PICTURE 99V99.
10 CODE-H REDEFINES HOURLY-PAY PICTURE 9999.

Data items within an area can be redefined without changing their lengths. For
example:

Chapter 18. DATA DIVISION--data description entry 223

 05 NAME-2.
10 SALARY PICTURE XXX.
10 SO-SEC-NO PICTURE X(9).
10 MONTH PICTURE XX.
05 NAME-1 REDEFINES NAME-2.
10 WAGE PICTURE XXX.
10 EMP-NO PICTURE X(9).
10 YEAR PICTURE XX.

Data item lengths and types can also be respecified within an area. For example:
05 NAME-2.
10 SALARY PICTURE XXX.
10 SO-SEC-NO PICTURE X(9).
10 MONTH PICTURE XX.
05 NAME-1 REDEFINES NAME-2.
10 WAGE PICTURE 999V999.
10 EMP-NO PICTURE X(6).
10 YEAR PICTURE XX.

Data items can also be respecified with a length that is greater than the length of
the redefined item. For example:
05 NAME-2.
10 SALARY PICTURE XXX.
10 SO-SEC-NO PICTURE X(9).
10 MONTH PICTURE XX.
05 NAME-1 REDEFINES NAME-2.
10 WAGE PICTURE 999V999.
10 EMP-NO PICTURE X(6).
10 YEAR PICTURE X(4).

This does not change the length of the redefined item NAME-2.

Undefined results
Undefined results can occur in the conditions as listed in the topic.
v A redefining item is moved to a redefined item (that is, if B REDEFINES C and the
statement MOVE B TO C is executed).
v A redefined item is moved to a redefining item (that is, if B REDEFINES C and the
statement MOVE C TO B is executed).

RENAMES clause
The RENAMES clause specifies alternative and possibly overlapping groupings of
elementary data items.

Format

►► 66 data-name-1 RENAMES data-name-2 ►◄

THROUGH data-name-3
THRU

The special level-number 66 must be specified for data description entries that
contain the RENAMES clause. (Level-number 66 and data-name-1 are not part of
the RENAMES clause, and are included in the format only for clarity.)

224 Enterprise COBOL for z/OS, V6.1 Language Reference

One or more RENAMES entries can be written for a logical record. All RENAMES
entries associated with one logical record must immediately follow the last data
description entry of that record.
data-name-1
Identifies an alternative grouping of data items.
A level-66 entry cannot rename a level-01, level-77, level-88, or another
level-66 entry.
data-name-1 cannot be used as a qualifier; it can be qualified only by the
names of level indicator entries or level-01 entries.
data-name-2, data-name-3
Identify the original grouping of elementary data items; that is, they must
name elementary or group items within the associated level-01 entry and
must not be the same data-name. Both data-names can be qualified.
data-name-2 and data-name-3 can each reference any of the following items:
v An elementary data item
v An alphanumeric group item
v A national group item
When data-name-2 or data-name-3 references a national group item, the
referenced item is processed as a group (not as an elementary data item of
category national).
The OCCURS clause must not be specified in the data entries for
data-name-2 and data-name-3, or for any group entry to which they are
subordinate. In addition, the OCCURS DEPENDING clause must not be
specified for any item defined between data-name-2 and data-name-3.

The keywords THROUGH and THRU are equivalent.

When the THROUGH phrase is specified:

v data-name-1 defines an alphanumeric group item that includes all the elementary
items that:
– Start with data-name-2 if it is an elementary item, or the first elementary item
within data-name-2 if it is a group item
– End with data-name-3 if it is an elementary item, or the last elementary item
within data-name-3 if it is an alphanumeric group item or national group item
v The storage area occupied by the starting item through the ending item becomes
the storage area occupied by data-name-1.

Usage note: The group defined with the THROUGH phrase can include data items
of usage NATIONAL.

The leftmost character position in data-name-3 must not precede the leftmost
character position in data-name-2, and the rightmost character position in
data-name-3 must not precede the rightmost character position in data-name-2. This
means that data-name-3 cannot be totally subordinate to data-name-2.

When the THROUGH phrase is not specified:

v The storage area occupied by data-name-2 becomes the storage area occupied by
data-name-1.
v All of the data attributes of data-name-2 become the data attributes for
data-name-1. That is:

Chapter 18. DATA DIVISION--data description entry 225

 – When data-name-2 is an alphanumeric group item, data-name-1 is an
alphanumeric group item.
– When data-name-2 is a national group item, data-name-1 is a national group
item.
– When data-name-2 is an elementary item, data-name-1 is an elementary item.

The following figure illustrates valid and invalid RENAMES clause specifications.

COBOL Specifications Storage Layouts

Example 1 (Valid)
RECORD-I
01 RECORD-I.
05 DN-1... . DN-1 DN-2 DN-3 DN-4
05 DN-2... .
05 DN-3... .
05 DN-4... .
66 DN-6 RENAMES DN-1 THROUGH DN-3. DN-6

Example 2 (Valid) RECORD-II

01 RECORD-II. DN-1
05 DN-1.
10 DN-2... . DN-2 DN-2A DN-5
10 DN-2A... .
05 DN-1A REDEFINES DN-1. DN-1A
10 DN-3A... . DN-3A DN-3 DN-3B
10 DN-3... .
10 DN-3B... .
05 DN-5... .
66 DN-6 RENAMES DN-2 THROUGH DN-3. DN-6

Example 3 (Invalid)
RECORD-III
01 RECORD-III.
DN-2
05 DN-2.
10 DN-3... . DN-3 DN-4 DN-5
10 DN-4... .
05 DN-5... .
66 DN-6 RENAMES DN-2 THROUGH DN-3. DN-6 is indeterminate

Example 4 (Invalid) RECORD-IV

01 RECORD-IV. DN-1
05 DN-1.
10 DN-2A... . DN-2A DN-2B DN-3
10 DN-2B... .
DN-2C
10 DN-2C REDEFINES DN-2B.
15 DN-2CA... . DN-2CA DN-2D
15 DN-2D... .
05 DN-3... .
66 DN-4 RENAMES DN-1 THROUGH DN-2CA. DN-4 is indeterminate

SIGN clause
The SIGN clause specifies the position and mode of representation of the
operational sign for the signed numeric item to which it applies.

The SIGN clause is required only when an explicit description of the properties or
position of the operational sign is necessary.

226 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format

►► LEADING ►◄
SIGN TRAILING SEPARATE
IS CHARACTER

The SIGN clause can be specified only for the following items:
v An elementary numeric data item of usage DISPLAY or NATIONAL that is
described with an S in its picture character string, or
v A group item that contains at least one such elementary entry as a subordinate
item

When the SIGN clause is specified at the group level, that SIGN clause applies
only to subordinate signed numeric elementary data items of usage DISPLAY or
NATIONAL. Such a group can also contain items that are not affected by the SIGN
clause. If the SIGN clause is specified for a group or elementary entry that is
subordinate to a group item that has a SIGN clause, the SIGN clause for the
subordinate entry takes precedence for that subordinate entry.

The SIGN clause is treated as documentation for external floating-point items.

When the SIGN clause is specified without the SEPARATE phrase, USAGE
DISPLAY must be specified explicitly or implicitly. When SIGN IS SEPARATE is
specified, either USAGE DISPLAY or USAGE NATIONAL can be specified.

If you specify the CODE-SET clause in an FD entry, any signed numeric data
description entries associated with that file description entry must be described
with the SIGN IS SEPARATE clause.

If the SEPARATE CHARACTER phrase is not specified, then:

v The operational sign is presumed to be associated with the LEADING or
TRAILING digit position, whichever is specified, of the elementary numeric data
item. (In this instance, specification of SIGN IS TRAILING is the equivalent of
the standard action of the compiler.)
v The character S in the PICTURE character string is not counted in determining
the size of the item (in terms of standard data format characters).

If the SEPARATE CHARACTER phrase is specified, then:

v The operational sign is presumed to be the LEADING or TRAILING character
position, whichever is specified, of the elementary numeric data item. This
character position is not a digit position.
v The character S in the PICTURE character string is counted in determining the
size of the data item (in terms of standard data format characters).
v + is the character used for the positive operational sign.
v - is the character used for the negative operational sign.

Chapter 18. DATA DIVISION--data description entry 227

SYNCHRONIZED clause
The SYNCHRONIZED clause specifies the alignment of an elementary item on a
natural boundary in storage.

Format

►► SYNCHRONIZED ►◄
SYNC LEFT
RIGHT

SYNC is an abbreviation for SYNCHRONIZED and has the same meaning.

The SYNCHRONIZED clause is never required, but can improve performance on

some systems for binary items used in arithmetic.

The SYNCHRONIZED clause can be specified for elementary items and for
level-01 group items, in which case every elementary item within the group item is
synchronized.
LEFT Specifies that the elementary item is to be positioned so that it will begin
at the left character position of the natural boundary in which the
elementary item is placed.
RIGHT
Specifies that the elementary item is to be positioned such that it will
terminate on the right character position of the natural boundary in which
it has been placed.

When specified, the LEFT and the RIGHT phrases are syntax checked but have no
effect on the execution of the program.

The length of an elementary item is not affected by the SYNCHRONIZED clause.

The following table lists the effect of the SYNCHRONIZE clause on other language
elements.
Table 15. SYNCHRONIZE clause effect on other language elements
Language element Comments
OCCURS clause When specified for an item within the scope of an OCCURS clause,
each occurrence of the item is synchronized.
USAGE DISPLAY or Each item is syntax checked, but the SYNCHRONIZED clause has
PACKED-DECIMAL no effect on execution.
USAGE NATIONAL Each item is syntax checked, but the SYNCHRONIZED clause has
no effect on execution.

228 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 15. SYNCHRONIZE clause effect on other language elements (continued)
Language element Comments
USAGE BINARY or When the item is the first elementary item subordinate to an item
COMPUTATIONAL that contains a REDEFINES clause, the item must not require the
addition of unused character positions.

When the synchronized clause is not specified for a subordinate

data item (one with a level number of 02 through 49):
v The item is aligned at a displacement that is a multiple of 2
relative to the beginning of the record if its USAGE is BINARY
and its PICTURE is in the range of S9 through S9(4).
v The item is aligned at a displacement that is a multiple of 4
relative to the beginning of the record if its USAGE is BINARY
and its PICTURE is in the range of S9(5) through S9(18), or its
USAGE is INDEX.

When SYNCHRONIZED is not specified for binary items, no space

is reserved for slack bytes.
USAGE POINTER, The data is aligned on a fullword boundary.
PROCEDURE-
POINTER,
FUNCTION-
POINTER, OBJECT
REFERENCE
USAGE The data is aligned on a fullword boundary.
COMPUTATIONAL-1
USAGE The data is aligned on a doubleword boundary.
COMPUTATIONAL-2
USAGE The data is treated the same as the SYNCHRONIZED clause for a
COMPUTATIONAL-3 PACKED-DECIMAL item.
USAGE The data is treated the same as the SYNCHRONIZED clause for a
COMPUTATIONAL-4 COMPUTATIONAL item.
USAGE The data is treated the same as the SYNCHRONIZED clause for a
COMPUTATIONAL-5 COMPUTATIONAL item.
DBCS and external Each item is syntax checked, but the SYNCHRONIZED clause has
floating-point items no effect on execution.
REDEFINES clause For an item that contains a REDEFINES clause, the data item that
is redefined must have the proper boundary alignment for the data
item that redefines it. For example, if you write the following, be
sure that data item A begins on a fullword boundary:
02 A PICTURE X(4).
02 B REDEFINES A PICTURE S9(9) BINARY SYNC.

In the FILE SECTION, the compiler assumes that all level-01 records that contain
SYNCHRONIZED items are aligned on doubleword boundaries in the buffer. You
must provide the necessary slack bytes between records to ensure alignment when
there are multiple records in a block.

In the WORKING-STORAGE SECTION, the compiler aligns all level-01 entries on

a doubleword boundary.

Chapter 18. DATA DIVISION--data description entry 229

 For the purposes of aligning binary items in the LINKAGE SECTION, all level-01
items are assumed to begin on doubleword boundaries. Therefore, if you issue a
CALL statement, such operands of any USING phrase within it must be aligned
correspondingly.

Slack bytes
There are two types of slack bytes.
v Slack bytes within records: unused character positions that precede each
synchronized item in the record
v Slack bytes between records: unused character positions added between blocked
logical records

| If the RULES=(NOSLACKBYTES) option is in effect, warning messages are issued

| for any SYNCHONIZED data items that cause the compiler to add slack bytes,
| either slack bytes within records or slack bytes between records. For details about
| the RULES option, see RULES in the Enterprise COBOL Programming Guide.

Slack bytes within records

For any data description that has binary items that are not on their natural
boundaries, the compiler inserts slack bytes within a record to ensure that all
SYNCHRONIZED items are on their proper boundaries.

Because it is important that you know the length of the records in a file, you need
to determine whether slack bytes are required and, if so, how many bytes the
compiler will add. The algorithm that the compiler uses is as follows:
v The total number of bytes occupied by all elementary data items that precede
the binary item are added together, including any slack bytes that are previously
added.
v This sum is divided by m, where:
– m = 2 for binary items of four-digit length or less
– m = 4 for binary items of five-digit length or more and for
COMPUTATIONAL-1 data items
– m = 4 for data items described with USAGE INDEX, USAGE POINTER,
USAGE PROCEDURE-POINTER, USAGE OBJECT REFERENCE, or USAGE
FUNCTION-POINTER
– m = 8 for COMPUTATIONAL-2 data items
v If the remainder (r) of this division is equal to zero, no slack bytes are required.
If the remainder is not equal to zero, the number of slack bytes that must be
added is equal to m - r.

These slack bytes are added to each record immediately following the elementary
data item that precedes the binary item. They are defined as if they constitute an
item with a level-number equal to that of the elementary item that immediately
precedes the SYNCHRONIZED binary item, and are included in the size of the
group that contains them.

For example:
01 FIELD-A.
05 FIELD-B PICTURE X(5).
05 FIELD-C.
10 FIELD-D PICTURE XX.
[10 SLACK-BYTES PICTURE X. INSERTED BY COMPILER]
10 FIELD-E COMPUTATIONAL PICTURE S9(6) SYNC.
01 FIELD-L.

230 Enterprise COBOL for z/OS, V6.1 Language Reference

 05 FIELD-M PICTURE X(5).
05 FIELD-N PICTURE XX.
[05 SLACK-BYTES PICTURE X. INSERTED BY COMPILER]
05 FIELD-O.
10 FIELD-P COMPUTATIONAL PICTURE S9(6) SYNC.

Slack bytes can also be added by the compiler when a group item is defined with
an OCCURS clause and contains within it a SYNCHRONIZED binary data item. To
determine whether slack bytes are to be added, the following action is taken:
v The compiler calculates the size of the group, including all the necessary slack
bytes within a record.
v This sum is divided by the largest m required by any elementary item within the
group.
v If r is equal to zero, no slack bytes are required. If r is not equal to zero, m - r
slack bytes must be added.

The slack bytes are inserted at the end of each occurrence of the group item that
contains the OCCURS clause. For example, a record defined as follows appears in
storage, as shown, in the figure after the record:
01 WORK-RECORD.
05 WORK-CODE PICTURE X.
05 COMP-TABLE OCCURS 10 TIMES.
10 COMP-TYPE PICTURE X.
[10 SLACK-BYTES PIC XX. INSERTED BY COMPILER]
10 COMP-PAY PICTURE S9(4)V99 COMP SYNC.
10 COMP-HOURS PICTURE S9(3) COMP SYNC.
10 COMP-NAME PICTURE X(5).

In order to align COMP-PAY and COMP-HOURS on their proper boundaries, the

compiler added 2 slack bytes within the record.

In the previous example, without further adjustment, the second occurrence of

COMP-TABLE would begin 1 byte before a doubleword boundary, and the alignment
of COMP-PAY and COMP-HOURS would not be valid for any occurrence of the table
after the first. Therefore, the compiler must add slack bytes at the end of the
group, as though the record had been written as follows:
01 WORK-RECORD.
05 WORK-CODE PICTURE X.
05 COMP-TABLE OCCURS 10 TIMES.
10 COMP-TYPE PICTURE X.

Chapter 18. DATA DIVISION--data description entry 231

 [10 SLACK-BYTES PIC XX. INSERTED BY COMPILER]
10 COMP-PAY PICTURE S9(4)V99 COMP SYNC.
10 COMP-HOURS PICTURE S9(3) COMP SYNC.
10 COMP-NAME PICTURE X(5).
[10 SLACK-BYTES PIC XX. INSERTED BY COMPILER]

In this example, the second and each succeeding occurrence of COMP-TABLE begins 1
byte beyond a doubleword boundary. The storage layout for the first occurrence of
COMP-TABLE now appears as shown in the following figure:

Each succeeding occurrence within the table will now begin at the same relative
position as the first.

Slack bytes between records

If the file contains blocked logical records that are to be processed in a buffer, and
any of the records contain binary entries for which the SYNCHRONIZED clause is
specified, you can improve performance by adding any needed slack bytes
between records for proper alignment.

The lengths of all the elementary data items in the record, including all slack bytes,
are added. (For variable-length records, it is necessary to add an additional 4 bytes
for the count field.) The total is then divided by the highest value of m for any one
of the elementary items in the record.

If r (the remainder) is equal to zero, no slack bytes are required. If r is not equal to
zero, m - r slack bytes are required. These slack bytes can be specified by writing a
level-02 FILLER at the end of the record.

Consider the following record description:

01 COMP-RECORD.
05 A-1 PICTURE X(5).
05 A-2 PICTURE X(3).
05 A-3 PICTURE X(3).
05 B-1 PICTURE S9999 USAGE COMP SYNCHRONIZED.
05 B-2 PICTURE S99999 USAGE COMP SYNCHRONIZED.
05 B-3 PICTURE S9999 USAGE COMP SYNCHRONIZED.

The number of bytes in A-1, A-2, and A-3 totals 11. B-1 is a four-digit
COMPUTATIONAL item and 1 slack byte must therefore be added before B-1.
With this byte added, the number of bytes that precede B-2 totals 14. Because B-2

232 Enterprise COBOL for z/OS, V6.1 Language Reference

 is a COMPUTATIONAL item of five digits in length, 2 slack bytes must be added
before it. No slack bytes are needed before B-3.

The revised record description entry now appears as:

01 COMP-RECORD.
05 A-1 PICTURE X(5).
05 A-2 PICTURE X(3).
05 A-3 PICTURE X(3).
[05 SLACK-BYTE-1 PICTURE X. INSERTED BY COMPILER]
05 B-1 PICTURE S9999 USAGE COMP SYNCHRONIZED.
[05 SLACK-BYTE-2 PICTURE XX. INSERTED BY COMPILER]
05 B-2 PICTURE S99999 USAGE COMP SYNCHRONIZED.
05 B-3 PICTURE S9999 USAGE COMP SYNCHRONIZED.

There is a total of 22 bytes in COMP-RECORD, but from the rules above, it appears
that m = 4 and r = 2. Therefore, to attain proper alignment for blocked records, you
must add 2 slack bytes at the end of the record.

The final record description entry appears as:

01 COMP-RECORD.
05 A-1 PICTURE X(5).
05 A-2 PICTURE X(3).
05 A-3 PICTURE X(3).
[05 SLACK-BYTE-1 PICTURE X. INSERTED BY COMPILER]
05 B-1 PICTURE S9999 USAGE COMP SYNCHRONIZED.
[05 SLACK-BYTE-2 PICTURE XX. INSERTED BY COMPILER]
05 B-2 PICTURE S99999 USAGE COMP SYNCHRONIZED.
05 B-3 PICTURE S9999 USAGE COMP SYNCHRONIZED.
05 FILLER PICTURE XX. [SLACK BYTES YOU ADD]

USAGE clause
The USAGE clause specifies the format in which data is represented in storage.

Chapter 18. DATA DIVISION--data description entry 233

 Format 1

►► BINARY ►◄
USAGE NATIVE
IS COMP
NATIVE
COMP-1
NATIVE
COMP-2
NATIVE
COMP-3
NATIVE
COMP-4
NATIVE
COMP-5
NATIVE
COMPUTATIONAL
NATIVE
COMPUTATIONAL-1
NATIVE
COMPUTATIONAL-2
NATIVE
COMPUTATIONAL-3
NATIVE
COMPUTATIONAL-4
NATIVE
COMPUTATIONAL-5
NATIVE
DISPLAY
NATIVE
DISPLAY-1
NATIVE
INDEX
NATIONAL
NATIVE
objref phrase
PACKED-DECIMAL
NATIVE
POINTER
PROCEDURE-POINTER
FUNCTION-POINTER

objref phrase:

OBJECT REFERENCE
class-name-1

Note: NATIVE is treated as a comment in all phrases for which NATIVE is shown
in the USAGE clause.

The USAGE clause can be specified for a data description entry with any
level-number other than 66 or 88.

When specified at the group level, the USAGE clause applies to each elementary
item in the group. The usage of elementary items must not contradict the usage of
a group to which the elementary items belongs.

A USAGE clause must not be specified in a group level entry for which a
GROUP-USAGE NATIONAL clause is specified.

234 Enterprise COBOL for z/OS, V6.1 Language Reference

 When a GROUP-USAGE NATIONAL clause is specified or implied for a group
level entry, USAGE NATIONAL must be specified or implied for every elementary
item within the group. For details, see “GROUP-USAGE clause” on page 194.

When the USAGE clause is not specified at either the group or elementary level, a
usage clause is implied with:
v Usage DISPLAY when the PICTURE clause contains only symbols other than G
or N
v Usage NATIONAL when the PICTURE clause contains only one or more of the
symbol N and the NSYMBOL(NATIONAL) compiler option is in effect
v Usage DISPLAY-1 when the PICTURE clause contains one or more of the symbol
N and the NSYMBOL(DBCS) compiler option is in effect

Computational items
A computational item is a value used in arithmetic operations. It must be numeric.
If a group item is described with a computational usage, the elementary items
within the group have that usage.

The maximum length of a computational item is 18 decimal digits, except for a

PACKED-DECIMAL item. If the ARITH(COMPAT) compiler option is in effect,
then the maximum length of a PACKED-DECIMAL item is 18 decimal digits. If the
ARITH(EXTEND) compiler option is in effect, then the maximum length of a
PACKED-DECIMAL item is 31 decimal digits.

The PICTURE of a computational item can contain only:

9 One or more numeric character positions
S One operational sign
V One implied decimal point
P One or more decimal scaling positions

COMPUTATIONAL-1 and COMPUTATIONAL-2 items (internal floating-point)

cannot have PICTURE strings.
BINARY
Specified for binary data items. Such items have a decimal equivalent
consisting of the decimal digits 0 through 9, plus a sign. Negative numbers
are represented as the two's complement of the positive number with the
same absolute value.
The amount of storage occupied by a binary item depends on the number
of decimal digits defined in its PICTURE clause:

Digits in PICTURE clause Storage occupied

1 through 4 2 bytes (halfword)
5 through 9 4 bytes (fullword)
10 through 18 8 bytes (doubleword)

Binary data is big-endian: the operational sign is contained in the leftmost

bit.

Chapter 18. DATA DIVISION--data description entry 235

 BINARY, COMPUTATIONAL, and COMPUTATIONAL-4 data items can be
affected by the TRUNC compiler option. For information about the effect
of this compiler option, see TRUNC in the Enterprise COBOL Programming
Guide.
PACKED-DECIMAL
Specified for internal decimal items. Such an item appears in storage in
packed decimal format. There are two digits for each character position,
except for the trailing character position, which is occupied by the
low-order digit and the sign. Such an item can contain any of the digits 0
through 9, plus a sign, representing a value not exceeding 18 decimal
digits.
The sign representation uses the same bit configuration as the 4-bit sign
representation in zoned decimal fields. For details, see Sign representation of
zoned and packed-decimal data in the Enterprise COBOL Programming Guide.
COMPUTATIONAL or COMP (binary)
This is the equivalent of BINARY. The COMPUTATIONAL phrase is
synonymous with BINARY.
COMPUTATIONAL-1 or COMP-1 (floating-point)
Specified for internal floating-point items (single precision). COMP-1 items
are 4 bytes long.
COMPUTATIONAL-2 or COMP-2 (long floating-point)
Specified for internal floating-point items (double precision). COMP-2
items are 8 bytes long.
COMPUTATIONAL-3 or COMP-3 (internal decimal)
This is the equivalent of PACKED-DECIMAL.
COMPUTATIONAL-4 or COMP-4 (binary)
This is the equivalent of BINARY.
COMPUTATIONAL-5 or COMP-5 (native binary)
These data items are represented in storage as binary data. The data items
can contain values 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 nines in the picture for the item (as is the case for USAGE
BINARY data). When numeric data is moved or stored into a COMP-5
item, truncation occurs at the binary field size rather than at the COBOL
picture size limit. When a COMP-5 item is referenced, the full binary field
size is used in the operation.
The TRUNC(BIN) compiler option causes all binary data items (USAGE
BINARY, COMP, COMP-4) to be handled as if they were declared USAGE
COMP-5.
The following table shows several picture character strings, the resulting
storage representation, and the range of values for data items described
with USAGE COMP-5.

Picture Storage representation Numeric values

S9(1) through S9(4) Binary halfword (2 bytes) -32768 through +32767
S9(5) through S9(9) Binary fullword (4 bytes) -2,147,483,648 through
+2,147,483,647
S9(10) through S9(18) Binary doubleword (8 bytes) -9,223,372,036,854,775,808
through
+9,223,372,036,854,775,807

236 Enterprise COBOL for z/OS, V6.1 Language Reference

 Picture Storage representation Numeric values
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

The picture for a COMP-5 data item can specify a scaling factor (that is,
decimal positions or implied integer positions). In this case, the maximal
capacities listed in the table above must be scaled appropriately. For
example, a data item described with PICTURE S99V99 COMP-5 is
represented in storage as a binary halfword, and supports a range of
values from -327.68 to +327.67.
USAGE NOTE: When the ON SIZE ERROR phrase is used on an
arithmetic statement and a receiver is defined with USAGE COMP-5, the
maximum value that the receiver can contain is the value implied by the
item's decimal PICTURE character-string. Any attempt to store a value
larger than this maximum will result in a size error condition.

DISPLAY phrase
The data item is stored in character form, one character for each 8-bit byte. This
corresponds to the format used for printed output. DISPLAY can be explicit or
implicit.

USAGE IS DISPLAY is valid for the following types of items:

v Alphabetic
v Alphanumeric
v Alphanumeric-edited
v Numeric-edited
v External floating-point
v External decimal

Alphabetic, alphanumeric, alphanumeric-edited, and numeric-edited items are

discussed in “Data categories and PICTURE rules” on page 209.

External decimal items with USAGE DISPLAY are sometimes referred to as zoned
decimal items. Each digit of a number is represented by a single byte. The 4
high-order bits of each byte are zone bits; the 4 high-order bits of the low-order
byte represent the sign of the item. The 4 low-order bits of each byte contain the
value of the digit.

If the ARITH(COMPAT) compiler option is in effect, then the maximum length of

an external decimal item is 18 digits. If the ARITH(EXTEND) compiler option is in
effect, then the maximum length of an external decimal item is 31 digits.

The PICTURE character-string of an external decimal item can contain only:

v One or more of the symbol 9
v The operational-sign, S
v The assumed decimal point, V
v One or more of the symbol P

Chapter 18. DATA DIVISION--data description entry 237

 DISPLAY-1 phrase
The DISPLAY-1 phrase defines an item as DBCS. The data item is stored in
character form, with each character occupying 2 bytes of storage.

FUNCTION-POINTER phrase
The FUNCTION-POINTER phrase defines an item as a function-pointer data item. A
function-pointer data item can contain the address of a procedure entry point.

A function-pointer is a 4-byte elementary item . Function-pointers have the same

capabilities as procedure-pointers, but are 4 bytes in length instead of 8 bytes.
Function-pointers are thus more easily interoperable with C function pointers.

A function-pointer can contain one of the following addresses or can contain

NULL:
v The primary entry point of a COBOL program, defined by the PROGRAM-ID
paragraph of the outermost program
v An alternate entry point of a COBOL program, defined by a COBOL ENTRY
statement
v An entry point in a non-COBOL program

A VALUE clause for a function-pointer data item can contain only NULL or
NULLS.

A function-pointer can be used in the same contexts as a procedure-pointer, as

defined in “PROCEDURE-POINTER phrase” on page 240.

INDEX phrase
A data item defined with the INDEX phrase is an index data item.

An index data item is a 4-byte elementary item that can be used to save index-name
values for future reference. An index data item is not necessarily connected with any
specific table. Through a SET statement, an index data item can be assigned an
index-name value. Such a value corresponds to the occurrence number in a table.

Direct references to an index data item can be made only in a SEARCH statement,
a SET statement, a relation condition, the USING phrase of the PROCEDURE
DIVISION header, or the USING phrase of the CALL or ENTRY statement.

An index data item can be part of an alphanumeric group item that is referenced
in a MOVE statement or an input/output statement.

An index data item saves values that represent table occurrences, yet is not
necessarily defined as part of any table. There is no conversion of values when an
index data item is referenced in the following circumstances:
v directly in a SEARCH or SET statement
v indirectly in a MOVE statement
v indirectly in an input or output statement

An index data item cannot be a conditional variable.

The JUSTIFIED, PICTURE, BLANK WHEN ZERO, or VALUE clauses cannot be

used to describe a group item or elementary items described with the USAGE IS
INDEX clause.

238 Enterprise COBOL for z/OS, V6.1 Language Reference

 SYNCHRONIZED can be used with USAGE IS INDEX to obtain efficient use of the
index data item.

NATIONAL phrase
The NATIONAL phrase defines an item whose content is represented in storage in
UTF-16 (CCSID 1200). The class and category of the data item depend on the
picture symbols that are specified in the associated PICTURE clause.

OBJECT REFERENCE phrase

A data item defined with the OBJECT REFERENCE phrase is an object reference. An
object reference data item is a 4-byte elementary item.
class-name-1
An optional class name.
You must define class-name-1 in the REPOSITORY paragraph in the
configuration section of the containing class or outermost program.
If specified, class-name-1 indicates that data-name-1 always refers to an
object-instance of class class-name-1 or a class derived from class-name-1.
Important: The programmer must ensure that the referenced object meets
this requirement; violations are not diagnosed.
If class-name-1 is not specified, the object reference can refer to an object of
any class. In this case, data-name-1 is a universal object reference.
You can specify data-name-1 within an alphanumeric group item without
affecting the semantics of the group item. There is no conversion of values
or other special handling of the object references when statements are
executed that operate on the group. The group continues to behave as an
alphanumeric group item.

An object reference can be defined in any section of the DATA DIVISION of a

factory definition, object definition, method, or program. An object-reference data
item can be used in only:
v A SET statement (format 7 only)
v A relation condition
v An INVOKE statement
v The USING or RETURNING phrase of an INVOKE statement
v The USING or RETURNING phrase of a CALL statement
v A program procedure division or ENTRY statement USING or RETURNING
phrase
v A method procedure division USING or RETURNING phrase

Object-reference data items:

v Are ignored in CORRESPONDING operations
v Are unaffected by INITIALIZE statements
v Can be the subject or object of a REDEFINES clause
v Cannot be a conditional variable
v Can be written to a file (but upon subsequent reading of the record the content
of the object reference is undefined)

A VALUE clause for an object-reference data item can contain only NULL or
NULLS.

Chapter 18. DATA DIVISION--data description entry 239

 You can use the SYNCHRONIZED clause with the USAGE OBJECT REFERENCE
clause to obtain efficient alignment of the object-reference data item.

The JUSTIFIED, PICTURE, and BLANK WHEN ZERO clauses cannot be used to
describe group or elementary items defined with the USAGE OBJECT REFERENCE
clause.

POINTER phrase
| A data item defined with USAGE IS POINTER is a pointer data item, or data-pointer.
A pointer data item is a 4-byte elementary item.

You can use pointer data items to accomplish limited base addressing. Pointer data
items can be compared for equality or moved to other pointer items.

A pointer data item can be used only:

v In a SET statement (format 5 only)
v In a relation condition
v In the USING phrase of a CALL statement, an ENTRY statement, or the
PROCEDURE DIVISION header

Pointer data items can be part of an alphanumeric group that is referred to in a

MOVE statement or an input/output statement. However, if a pointer data item is
part of a group, there is no conversion of values when the statement is executed.

A pointer data item can be the subject or object of a REDEFINES clause.

SYNCHRONIZED can be used with USAGE IS POINTER to obtain efficient use of

the pointer data item.

A VALUE clause for a pointer data item can contain only NULL or NULLS.

A pointer data item cannot be a conditional variable.

A pointer data item does not belong to any class or category.

The JUSTIFIED, PICTURE, and BLANK WHEN ZERO clauses cannot be used to
describe group or elementary items defined with the USAGE IS POINTER clause.

Pointer data items are ignored in the processing of a CORRESPONDING phrase.

A pointer data item can be written to a data set, but upon subsequent reading of
the record that contains the pointer, the address contained might no longer
represent a valid pointer.

USAGE IS POINTER is implicitly specified for the ADDRESS OF special register.

For more information, see Using tables (arrays) and pointers in the Enterprise COBOL
Programming Guide.

PROCEDURE-POINTER phrase
The PROCEDURE-POINTER phrase defines an item as a procedure-pointer data item.

A procedure-pointer data item is an 8-byte elementary item.

240 Enterprise COBOL for z/OS, V6.1 Language Reference

 A procedure-pointer can contain one of the following addresses or can contain
NULL:
v The primary entry point of a COBOL program as defined by the program-ID
paragraph of the outermost program of a compilation unit
v An alternate entry point of a COBOL program as defined by a COBOL ENTRY
statement
v An entry point in a non-COBOL program

A procedure-pointer data item can be used only:

v In a SET statement (format 6 only)
v In a CALL statement
v In a relation condition
v In the USING phrase of an ENTRY statement or the PROCEDURE DIVISION
header

Procedure-pointer data items can be compared for equality or moved to other

procedure-pointer data items.

Procedure-pointer data items can be part of a group that is referred to in a MOVE

statement or an input/output statement. However, there is no conversion of values
when the statement is executed. If a procedure-pointer data item is written to a
data set, subsequent reading of the record that contains the procedure-pointer can
result in an invalid value in the procedure-pointer.

A procedure-pointer data item can be the subject or object of a REDEFINES clause.

SYNCHRONIZED can be used with USAGE IS PROCEDURE-POINTER to obtain

efficient alignment of the procedure-pointer data item.

The GLOBAL, EXTERNAL, and OCCURS clause can be used with USAGE IS
PROCEDURE-POINTER.

A VALUE clause for a procedure-pointer data item can contain only NULL or
NULLS.

The JUSTIFIED, PICTURE, and BLANK WHEN ZERO clauses cannot be used to
describe group or elementary items defined with the USAGE IS
PROCEDURE-POINTER clause.

A procedure-pointer data item cannot be a conditional variable.

A procedure-pointer data item does not belong to any class or category.

Procedure-pointer data items are ignored in CORRESPONDING operations.

NATIVE phrase
The NATIVE phrase is syntax checked, but has no effect on the execution of the
program.

VALUE clause
The VALUE clause specifies the initial contents of a data item or the values
associated with a condition-name. The use of the VALUE clause differs depending
on the DATA DIVISION section in which it is specified.

Chapter 18. DATA DIVISION--data description entry 241

 In the WORKING-STORAGE SECTION and the LOCAL-STORAGE SECTION, the
VALUE clause can be used in condition-name entries or in specifying the initial
value of any data item. The data item assumes the specified value at the beginning
of program execution. If the initial value is not explicitly specified, the value is
unpredictable.

Format 1
Format 1 specifies the initial value of a data item. Initialization is independent of
any BLANK WHEN ZERO or JUSTIFIED clause that is specified.

Format 1: literal value

►► VALUE literal ►◄
IS

A format-1 VALUE clause specified in a data description entry that contains or is

subordinate to an OCCURS clause causes every occurrence of the associated data
item to be assigned the specified value. Each structure that contains the
DEPENDING ON phrase of the OCCURS clause is assumed to contain the
maximum number of occurrences for the purposes of VALUE initialization.

The VALUE clause must not be specified for a data description entry that contains
or is subordinate to an entry that contains either an EXTERNAL or a REDEFINES
clause. This rule does not apply to condition-name entries.

A format-1 VALUE clause can be specified for an elementary data item or for a
group item. When the VALUE clause is specified at the group level, the group area
is initialized without consideration for the subordinate entries within the group. In
addition, a VALUE clause must not be specified for subordinate entries within the
group.

For group items, the VALUE clause must not be specified if any subordinate
entries contain a JUSTIFIED or SYNCHRONIZED clause.

If the VALUE clause is specified for an alphanumeric group, all subordinate items
must be explicitly or implicitly described with USAGE DISPLAY.

The VALUE clause must not conflict with other clauses in the data description
entry or in the data description of that entry's hierarchy.

The functions of the editing characters in a PICTURE clause are ignored in

determining the initial value of the item described. However, editing characters are
included in determining the size of the item. Therefore, any editing characters
must be included in the literal. For example, if the item is defined as PICTURE
+999.99 and the value is to be +12.34, then the VALUE clause should be specified
as VALUE "+012.34".

A VALUE clause cannot be specified for external floating-point items.

A data item cannot contain a VALUE clause if the prior data item contains an
OCCURS clause with the DEPENDING ON phrase.

242 Enterprise COBOL for z/OS, V6.1 Language Reference

Rules for literal values
v Wherever a literal is specified, a figurative constant can be substituted, in
accordance with the rules specified in “Figurative constants” on page 13.
v If the item is class numeric, the VALUE clause literal must be numeric. If the
literal defines the value of a WORKING-STORAGE item or LOCAL-STORAGE
item, the literal is aligned according to the rules for numeric moves, with one
additional restriction: The literal must not have a value that requires truncation
of nonzero digits. If the literal is signed, the associated PICTURE character-string
must contain a sign symbol.
v With some exceptions, numeric literals in a VALUE clause must have a value
within the range of values indicated by the PICTURE clause for the item. For
example, for PICTURE 99PPP, the literal must be zero or within the range 1000
through 99000. For PICTURE PPP99, the literal must be within the range 0.00000
through 0.00099.
The exceptions are the following ones:
– Data items described with usage COMP-5 that do not have a picture symbol
P in their PICTURE clause
– When the TRUNC(BIN) compiler option is in effect, data items described with
usage BINARY, COMP, or COMP-4 that do not have a picture symbol P in
their PICTURE clause
A VALUE clause for these items can have a value up to the capacity of the
native binary representation.
v If the VALUE clause is specified for an elementary alphabetic, alphanumeric,
alphanumeric-edited, or numeric-edited item described with usage DISPLAY, the
VALUE clause literal must be an alphanumeric literal or a figurative constant.
The literal is aligned according to the alphanumeric alignment rules, with one
additional restriction: the number of characters in the literal must not exceed the
size of the item.
v If the VALUE clause is specified for an elementary national, national-edited, or
numeric-edited item described with usage NATIONAL, the VALUE clause literal
must be a national or alphanumeric literal or a figurative constant as specified in
“Figurative constants” on page 13. The value of an alphanumeric literal is
converted from its source code representation to UTF-16 representation. The
literal is aligned according to the national alignment rules, with one additional
restriction: the number of characters in the literal must not exceed the size, in
character positions, of the item.
v If the VALUE clause is specified at the group level for an alphanumeric group,
the literal must be an alphanumeric literal or a figurative constant as specified in
“Figurative constants” on page 13, other than ALL national-literal. The size of the
literal must not exceed the size of the group item.
v If the VALUE clause is specified at the group level for a national group, the
literal can be an alphanumeric literal, a national literal, or one of the figurative
constants ZERO, SPACE, QUOTES, HIGH-VALUE, LOW-VALUE, symbolic
character, ALL national-literal, or ALL -literal. The value of an alphanumeric literal
is converted from its source code representation to UTF-16 representation. Each
figurative constant represents a national character value. The size of the literal
must not exceed the size of the group item.
v A VALUE clause associated with a DBCS item must contain a DBCS literal, the
figurative constant SPACE, or the figurative constant ALL DBCS-literal. The
length of the literal must not exceed the size indicated by the data item's
PICTURE clause.
v A VALUE clause that specifies a national literal can be associated only with a
data item of class national.

Chapter 18. DATA DIVISION--data description entry 243

 v A VALUE clause that specifies a DBCS literal can be associated only with a data
item of class DBCS.
v A VALUE clause associated with a COMPUTATIONAL-1 or
COMPUTATIONAL-2 (internal floating-point) item must specify a floating-point
literal. In addition, the figurative constant ZERO and both integer and decimal
forms of the zero literal can be specified in a floating-point VALUE clause.
You cannot specify a floating-point format numeric literal in the VALUE clause
of a fixed-point numeric item.
For information about floating-point literal values, see “Rules for floating-point
literal values” on page 42.

Format 2
This format associates a value, values, or ranges of values with a condition-name.
Each such condition-name requires a separate level-88 entry. Level-number 88 and
the condition-name are not part of the format-2 VALUE clause itself. They are
included in the format only for clarity.

Format 2: condition-name value

►► 88 condition-name-1 VALUE ►
IS
VALUES
ARE

► ▼ literal-1 . ►◄
THROUGH literal-2
THRU

condition-name-1
A user-specified name that associates a value with a conditional variable. If
the associated conditional variable requires subscripts or indexes, each
procedural reference to the condition-name must be subscripted or indexed
as required for the conditional variable.
Condition-names are tested procedurally in condition-name conditions (see
“Conditional expressions” on page 264).
literal-1
Associates the condition-name with a single value.
The class of literal-1 must be a valid class for assignment to the associated
conditional variable.
literal-1 THROUGH literal-2
Associates the condition-name with at least one range of values. When the
THROUGH phrase is used, literal-1 must be less than literal-2. For details,
see “Rules for condition-name entries” on page 245.

244 Enterprise COBOL for z/OS, V6.1 Language Reference

 literal-1 and literal-2 must be of the same class. The class of literal-1 and
literal-2 must be a valid class for assignment to the associated conditional
variable.
When literal-1 and literal-2 are DBCS literals, the range of DBCS values
specified by the THROUGH phrase is based on the binary collating
sequence of the hexadecimal values of the DBCS characters.
When literal-1 and literal-2 are national literals, the range of national
character values specified by the THROUGH phrase is based on the binary
collating sequence of the hexadecimal values of the national characters
represented by the literals.
If the associated conditional variable is of class DBCS, literal-1 and literal-2
must be DBCS literals. The figurative constant SPACE or the figurative
constant ALL DBCS-literal can be specified.
If the associated conditional variable is of class national, literal-1 and
literal-2 must be either both national literals or both alphanumeric literals
for a given condition-name. The figurative constants ZERO, SPACE,
QUOTE, HIGH-VALUE, LOW-VALUE, symbolic-character, ALL
national-literal, or ALL literal can be specified.

Rules for condition-name entries

There are certain rules for condition-name entries.

The rules are:

v The VALUE clause is required in a condition-name entry, and must be the only
clause in the entry. Each condition-name entry is associated with a preceding
conditional variable. Thus every level-88 entry must always be preceded either
by the entry for the conditional variable or by another level-88 entry when
several condition-names apply to one conditional variable. Each such level-88
entry implicitly has the PICTURE characteristics of the conditional variable.
v A space, a separator comma, or a separator semicolon must separate successive
operands.
Each entry must end with a separator period.
v The keywords THROUGH and THRU are equivalent.
v The condition-name entries associated with a particular conditional variable
must immediately follow the conditional variable entry. The conditional variable
can be any elementary data description entry except the following ones:
– Another condition-name
– A RENAMES clause (level-66 item)
– An item described with USAGE IS INDEX
– An item described with USAGE POINTER, USAGE PROCEDURE-POINTER,
USAGE FUNCTION-POINTER, or USAGE OBJECT REFERENCE
v Condition-names can be specified both at the group level and at subordinate
levels within an alphanumeric group or national group.
v When the condition-name is specified for an alphanumeric group data
description entry:
– The value of literal-1 (or literal-1 and literal-2) must be specified as an
alphanumeric literal or figurative constant.
– The group can contain items of any usage.

Chapter 18. DATA DIVISION--data description entry 245

 v When the condition-name is specified for a national group data description
entry:
– The value of literal-1 (or literal-1 and literal-2) must be specified as an
alphanumeric literal, a national literal, or a figurative constant.
– The group can contain only items of usage national, as specified for the
“GROUP-USAGE clause” on page 194.
v When the condition-name is associated with an alphanumeric group data
description entry or a national group data description entry:
– The size of each literal value must not exceed the sum of the sizes of all the
elementary items within the group.
– No element within the group can contain a JUSTIFIED or SYNCHRONIZED
clause.
v Relation tests implied by the definition of a condition-name are performed in
accordance with the rules referenced in the table below.
Table 16. Relation test references for condition-names
Type of conditional variable Relation condition rules
Alphanumeric group item “Group comparisons” on page 274
National group item (treated as elementary data “National comparisons” on page 273
item of class national)
Elementary data item of class alphanumeric “Alphanumeric comparisons” on page
271
Elementary data item of class national “National comparisons” on page 273
Elementary data item of class numeric “Numeric comparisons” on page 274
Elementary data item of class DBCS “DBCS comparisons” on page 273

v A VALUE clause that specifies a national literal can be associated with a

condition-name defined only for a data item of class national.
v A VALUE clause that specifies a DBCS literal can be associated with a
condition-name defined only for a data item of class DBCS.
v The literals in a condition-name entry for an elementary data item of class
national or a national group item must be either national literals or
alphanumeric literals, and literal-1 and literal-2 must be of the same class. For
alphanumeric groups or elementary data items of other classes, the type of
literal must be consistent with the data type of the conditional variable. In the
following example:
– CITY-COUNTY-INFO, COUNTY-NO, and CITY are conditional variables.
The PICTURE associated with COUNTY-NO limits the condition-name value
to a two-digit numeric literal.
The PICTURE associated with CITY limits the condition-name value to a
three-character alphanumeric literal.
– The associated condition-names are level-88 entries.
Any values for the condition-names associated with CITY-COUNTY-INFO
cannot exceed five characters.
Because this is an alphanumeric group item, the literal must be alphanumeric.
05 CITY-COUNTY-INFO.
88 BRONX VALUE "03NYC".
88 BROOKLYN VALUE "24NYC".
88 MANHATTAN VALUE "31NYC".
88 QUEENS VALUE "41NYC".
88 STATEN-ISLAND VALUE "43NYC".

246 Enterprise COBOL for z/OS, V6.1 Language Reference

 10 COUNTY-NO PICTURE 99.
88 DUTCHESS VALUE 14.
88 KINGS VALUE 24.
88 NEW-YORK VALUE 31.
88 RICHMOND VALUE 43.
10 CITY PICTURE X(3).
88 BUFFALO VALUE "BUF".
88 NEW-YORK-CITY VALUE "NYC".
88 POUGHKEEPSIE VALUE "POK".
05 POPULATION...

Format 3
This format assigns an invalid address as the initial value of an item defined as
USAGE POINTER, USAGE PROCEDURE POINTER, or USAGE
FUNCTION-POINTER. It also assigns an invalid object reference as the initial
value of an item defined as USAGE OBJECT REFERENCE.

Format 3: NULL value

►► VALUE NULL ►◄
IS NULLS

VALUE IS NULL can be specified only for elementary items described implicitly or
explicitly as USAGE POINTER, USAGE PROCEDURE-POINTER, USAGE
FUNCTION-POINTER, or USAGE OBJECT REFERENCE.

VOLATILE clause
The VOLATILE clause indicates that a data item's value can be modified or
referenced in ways that the compiler cannot detect, such as by a Language
Environment (LE) condition handler routine or by some other asynchronous
process or thread. Thus, optimization is restricted for the data item.

Format

►► VOLATILE ►◄

In particular, the compiler will enforce the following restrictions:

v A volatile data item is loaded from memory each time it is referenced and stored
to memory each time it is modified.
v Loads and stores to the data item are never reordered or eliminated.
v Storage is always allocated for the data item and initialized where necessary,
even when no references to the data item are in the compilation unit.

Note: The STGOPT option is ignored for data items that have the VOLATILE
clause.

Chapter 18. DATA DIVISION--data description entry 247

 The VOLATILE clause can be specified on data items that are defined in the FILE
SECTION, WORKING-STORAGE SECTION, LOCAL-STORAGE SECTION, and
LINKAGE SECTION. This clause can be specified together with any other clauses.
For example, VOLATILE can be specified on tables, group data items, elementary
data items, record descriptions and variably located data items.

There are additional considerations for groups:

v When a group item is explicitly defined with the VOLATILE clause, all items
subordinate to the group item are treated as volatile by the compiler.
v When a group item has one or more subordinate items that are explicitly
defined with the VOLATILE clause, the group item is treated as volatile by the
compiler.

The VOLATILE clause cannot be specified on level-66 or level-88 data items.

It is not possible to indicate that all memory associated with a class instance is
volatile. However, individual members of a class can be defined with the
VOLATILE clause.

Example of using VOLATILE with groups:

Consider the following group definition:

01 DATA-COLLECTION.
03 DATA-ITEMS-A VOLATILE.
05 DATA-A1 PIC S9(9) BINARY.
05 DATA-A2 PIC S9(9) BINARY.
03 DATA-ITEMS-B.
05 DATA-B1 PIC S9(9).
05 DATA-B2 PIC S9(9) VOLATILE.
03 DATA-ITEMS-C.
05 DATA-C1 PIC S9(9).
05 DATA-C2 PIC S9(9).

In this example:
v DATA-ITEMS-A and DATA-B2 are considered volatile because they are defined
with the VOLATILE clause.
v DATA-A1 and DATA-A2 are treated as volatile because they are both
subordinate to a group item (DATA-ITEMS-A) that has the VOLATILE clause.
v DATA-COLLECTION and DATA-ITEMS-B are treated as volatile because they
are group items that have subordinates that are defined with the VOLATILE
clause. For example:
MOVE DATA-ITEMS-B TO DATA-ITEMS-C.

In this case, by treating DATA-ITEMS-B as volatile, the compiler ensures that the
latest value of its subordinate member DATA-B2 is used in the memory copy
operation.

In the following LE condition handler scenario, it is necessary to specify the "STEP"

data item with the VOLATILE clause to achieve correct results. In particular, if the
VOLATILE clause is not used, the compiler might assume that "STEP" is never
referenced between the assignment of "2" to "STEP" and the assignment of "3" to
"STEP" and might therefore decide to eliminate the first assignment during
optimization. Unfortunately, this could result in a problem because if a
divide-by-zero condition occurs during execution of the subsequent line of code,
the condition handler will execute and reference the external variable "STEP",
which might have the incorrect value.

248 Enterprise COBOL for z/OS, V6.1 Language Reference

Main program:
IDENTIFICATION DIVISION.
PROGRAM-ID. MAIN.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 USER-HANDLER PROCEDURE-POINTER.
77 TOKEN PIC S9(9) COMP.
01 QTY PIC 9(8) BINARY.
01 DIVISOR PIC 9(8) BINARY VALUE 0.
01 ANSWER PIC 9(8) BINARY.
01 STEP PIC 9(8) BINARY VALUE 0 EXTERNAL VOLATILE.
:
SET USER-HANDLER TO ENTRY ’HANDLER’
CALL ’CEEHDLR’ USING USER-HANDLER, TOKEN, NULL
COMPUTE STEP = 2 *> Compiler thinks this store has no purpose and may remove it
COMPUTE ANSWER = NUMBER / DIVISOR *> Divide-by-zero exception occurs here, handler is invoked,
*> and reference to ’STEP’ is made but hidden from compiler
DISPLAY ’ANSWER = ’ ANSWER
COMPUTE STEP = 3
DISPLAY ’STEP = ’ STEP
COMPUTE ANSWER = QTY + 2
:
Condition handler program:
IDENTIFICATION DIVISION.
PROGRAM-ID. HANDLER.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 STEP PIC 9(8) BINARY EXTERNAL.
PROCEDURE DIVISION.
:
DISPLAY ’ERROR: A PROBLEM WAS ENCOUNTERED IN STEP ’ STEP.

Chapter 18. DATA DIVISION--data description entry 249

250 Enterprise COBOL for z/OS, V6.1 Language Reference
Part 6. Procedure division

© Copyright IBM Corp. 1991, 2017 251

252 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 19. Procedure division structure
The PROCEDURE DIVISION is an optional division.
Program procedure division
The program procedure division consists of optional declaratives, and
procedures that contain sections, paragraphs, sentences, and statements.
Factory procedure division
The factory procedure division contains only factory method definitions.
Object procedure division
The object procedure division contains only object method definitions.
Method procedure division
A method procedure division consists of optional declaratives, and
procedures that contain sections, paragraphs, sentences, and statements. A
method can INVOKE other methods, be recursively invoked, and issue a
CALL to a program. A method procedure division cannot contain nested
programs or methods.
For additional details on a method procedure division, see “Requirements
for a method procedure division” on page 254.

© Copyright IBM Corp. 1991, 2017 253

 Format: procedure division

►► procedure-division-header ►
factory-or-object-procedure-division-header
method-procedure-division-header

► ►

(1)
DECLARATIVES. ▼ sect . use-statement END DECLARATIVES.
para

(2)
► ▼ section-name SECTION . ►◄
(3) para
priority-number

sect:

section-name SECTION
(3)
priority-number

para:

▼ paragraph-name.

▼ sentence

Notes:
1 The USE statement is described under “USE statement” on page 582.
2 Section-name can be omitted. If you omit section-name, paragraph-name can be omitted.
3 Priority-numbers are not valid for methods, recursive programs, or programs compiled with the
THREAD option.

Requirements for a method procedure division

There are specific requirements when you code a method procedure division.

The requirements are:

v You can use the EXIT METHOD statement or the GOBACK statement to return
control to the invoking method or program. An implicit EXIT METHOD
statement is generated as the last statement of every method procedure division.

254 Enterprise COBOL for z/OS, V6.1 Language Reference

 For details on the EXIT METHOD statement, see “Format 3 (method)” on page
350.
v You can use the STOP RUN statement (which terminates the run unit) in a
method.
v You can use the RETURN-CODE special register within a method procedure
division to access return codes from subprograms that are called with the CALL
statement, but the RETURN-CODE value is not returned to the invoker of the
current method. Use the procedure division RETURNING data name to return a
value to the invoker of the current method. For details, see the discussion of
RETURNING data-name-2 under “The PROCEDURE DIVISION header.”

You cannot specify the following statements or clauses in a method procedure

division:
v ALTER
v ENTRY
v EXIT PROGRAM
v GO TO without a specified procedure name
v SEGMENT-LIMIT
v USE FOR DEBUGGING

The PROCEDURE DIVISION header

The PROCEDURE DIVISION, if specified, is identified by one of the following
headers, depending on whether you are specifying a program, a factory definition,
an object definition, or a method definition.

The following syntax diagram shows the format for a PROCEDURE DIVISION
header in a program.

Format: program procedure division header

►► PROCEDURE DIVISION ►

► ►

USING ▼ ▼ data-name-1
REFERENCE
BY
VALUE
BY

► . ►◄
RETURNING data-name-2

The following syntax diagram shows the format for a PROCEDURE DIVISION
header in a factory paragraph or object paragraph.

Chapter 19. Procedure division structure 255

 Format: factory and object procedure division header

►► PROCEDURE DIVISION. ►◄

The following syntax diagram shows the format for a PROCEDURE DIVISION
header in a method.

Format: method procedure division header

►► PROCEDURE DIVISION ►

USING ▼ VALUE ▼ data-name-1

BY

► ►◄
RETURNING data-name-2

The USING phrase

The USING phrase specifies the parameters that a program or method receives
when the program is called or the method is invoked.

The USING phrase is valid in the PROCEDURE DIVISION header of a called

subprogram or invoked method entered at the beginning of the nondeclaratives
portion. Each USING identifier must be defined as a level-01 or level-77 item in the
LINKAGE SECTION of the called subprogram or invoked method.

In a called subprogram entered at the first executable statement following an

ENTRY statement, the USING phrase is valid in the ENTRY statement. Each
USING identifier must be defined as a level-01 or level-77 item in the LINKAGE
SECTION of the called subprogram.

However, a data item specified in the USING phrase of the CALL statement can be
a data item of any level in the DATA DIVISION of the calling COBOL program or
method. A data item specified in the USING phrase of an INVOKE statement can
be a data item of any level in the DATA DIVISION of the invoking COBOL
program or method.

A data item in the USING phrase of the header can have a REDEFINES clause in
its data description entry.

It is possible to call COBOL programs from non-COBOL programs or to pass user

parameters from a system command to a COBOL main program. COBOL methods
can be invoked only from Java or COBOL.

256 Enterprise COBOL for z/OS, V6.1 Language Reference

The order of appearance of USING identifiers in both calling and called
subprograms, or invoking methods or programs and invoked methods, determines
the correspondence of single sets of data available to both. The correspondence is
positional and not by name. For calling and called subprograms, corresponding
identifiers must contain the same number of bytes although their data descriptions
need not be the same.

For index-names, no correspondence is established. Index-names in calling and

called programs, or invoking method or program and invoked methods, always
refer to separate indexes.

The identifiers specified in a CALL USING or INVOKE USING statement name the
data items available to the calling program or invoking method or program that
can be referred to in the called program or invoked method. These items can be
defined in any DATA DIVISION section.

A given identifier can appear more than once in a USING phrase. The last value
passed to it by a CALL or INVOKE statement is used.

The BY REFERENCE or BY VALUE phrase applies to all parameters that follow

until overridden by another BY REFERENCE or BY VALUE phrase.
BY REFERENCE (for programs only)
When an argument is passed BY CONTENT or BY REFERENCE, BY
REFERENCE must be specified or implied for the corresponding formal
parameter on the PROCEDURE or ENTRY USING phrase.
BY REFERENCE is the default if neither BY REFERENCE nor BY VALUE is
specified.
If the reference to the corresponding data item in the CALL statement
declares the parameter to be passed BY REFERENCE (explicit or implicit),
the program executes as if each reference to a USING identifier in the
called subprogram is replaced by a reference to the corresponding USING
identifier in the calling program.
If the reference to the corresponding data item in the CALL statement
declares the parameter to be passed BY CONTENT, the value of the item is
moved when the CALL statement is executed and placed into a
system-defined storage item that possesses the attributes declared in the
LINKAGE SECTION for data-name-1. The data description of each
parameter in the BY CONTENT phrase of the CALL statement must be the
same, meaning no conversion or extension or truncation, as the data
description of the corresponding parameter in the USING phrase of the
header.
BY VALUE
When an argument is passed BY VALUE, the value of the argument is
passed, not a reference to the sending data item. The receiving subprogram
or method has access only to a temporary copy of the sending data item.
Any modifications made to the formal parameters that correspond to an
argument passed BY VALUE do not affect the argument.
Parameters specified in the USING phrase of a method procedure division
header must be passed to the method BY VALUE. See Passing data in the
Enterprise COBOL Programming Guide for examples that illustrate these
concepts.

Chapter 19. Procedure division structure 257

 data-name-1
data-name-1 must be a level-01 or level-77 item in the LINKAGE SECTION.
When data-name-1 is an object reference in a method procedure division
header, an explicit class-name must be specified in the data description
entry for that object reference; that is, data-name-1 must not be a universal
object reference.
For methods, the parameter data types are restricted to the data types that
are interoperable between COBOL and Java, as listed in “Interoperable
data types for COBOL and Java” on page 377.

RETURNING phrase
The RETURNING phrase specifies a data item that is to receive the program or
method result.
data-name-2
data-name-2 is the RETURNING data item. data-name-2 must be a level-01
or level-77 item in the LINKAGE SECTION.

Note: An unbounded group cannot be specified as data-name-2.

In a method procedure division header, the data type of data-name-2 must
be one of the types supported for Java interoperation, as listed in
“Interoperable data types for COBOL and Java” on page 377.
The RETURNING data item is an output-only parameter. On entry to the
method, the initial state of the RETURNING data item has an undefined
and unpredictable value. You must initialize the PROCEDURE DIVISION
RETURNING data item before you reference its value. The value that is
returned to the invoking routine is the value that the data item has at the
point of exit from the method. See “RETURNING phrase” on page 375 for
further details on conformance requirements for the INVOKE RETURNING
identifier and the method RETURNING data item.
Do not use the PROCEDURE DIVISION RETURNING phrase in:
v Programs that contain the ENTRY statement.
v Nested programs.
v Main programs: Results of specifying PROCEDURE DIVISION
RETURNING on a main program are undefined. You should specify the
PROCEDURE DIVISION RETURNING phrase only on called
subprograms. For main programs, use the RETURN-CODE special
register to return a value to the operating environment.

References to items in the LINKAGE SECTION

Data items defined in the LINKAGE SECTION of the called program or invoked
method can be referenced within the PROCEDURE DIVISION of that program if
and only if they satisfy one of the conditions as listed in the topic.
v They are operands of the USING phrase of the PROCEDURE DIVISION header
or the ENTRY statement.
v They are operands of SET ADDRESS OF, CALL ... BY REFERENCE ADDRESS
OF, or INVOKE ... BY REFERENCE ADDRESS OF.
v They are defined with a REDEFINES or RENAMES clause, the object of which
satisfies the above conditions.
v They are items subordinate to any item that satisfies the condition in the rules
above.

258 Enterprise COBOL for z/OS, V6.1 Language Reference

 v They are condition-names or index-names associated with data items that satisfy
any of the above conditions.

Declaratives
Declaratives provide one or more special-purpose sections that are executed when
an exceptional condition occurs.

When declarative sections are specified, they must be grouped at the beginning of
the procedure division and the entire PROCEDURE DIVISION must be divided
into sections.

Each declarative section starts with a USE statement that identifies the section's
function. The series of procedures that follow specify the actions that are to be
taken when the exceptional condition occurs. Each declarative section ends with
another section-name followed by a USE statement, or with the keywords END
DECLARATIVES.

The entire group of declarative sections is preceded by the keyword

DECLARATIVES written on the line after the PROCEDURE DIVISION header. The
group is followed by the keywords END DECLARATIVES. The keywords
DECLARATIVES and END DECLARATIVES must each begin in Area A and be
followed by a separator period. No other text can appear on the same line.

In the declaratives part of the PROCEDURE DIVISION, each section header must
be followed by a separator period, and must be followed by a USE statement
followed by a separator period. No other text can appear on the same line.

| The USE statement has the following formats:

v “EXCEPTION/ERROR declarative” on page 582
v “DEBUGGING declarative” on page 584

The USE statement itself is never executed; instead, the USE statement defines the
conditions that execute the succeeding procedural paragraphs, which specify the
actions to be taken. After the procedure is executed, control is returned to the
routine that activated it.

A declarative procedure can be performed from a nondeclarative procedure.

A nondeclarative procedure can be performed from a declarative procedure.

A declarative procedure can be referenced in a GO TO statement in a declarative

procedure.

A nondeclarative procedure can be referenced in a GO TO statement in a

declarative procedure.

You can include a statement that executes a previously called USE procedure that
is still in control. However, to avoid an infinite loop, you must be sure there is an
eventual exit at the bottom.

The declarative procedure is exited when the last statement in the procedure is
executed.

Chapter 19. Procedure division structure 259

Procedures
Within the PROCEDURE DIVISION, a procedure consists of a section or a group of
sections, and a paragraph or group of paragraphs.

A procedure-name is a user-defined name that identifies a section or a paragraph.

Section
A section-header optionally followed by one or more paragraphs.
Section-header
A section-name followed by the keyword SECTION, optionally
followed by a priority-number, followed by a separator period.
Section-headers are optional after the keywords END
DECLARATIVES or if there are no declaratives.
Section-name
A user-defined word that identifies a section. A referenced
section-name, because it cannot be qualified, must be unique
within the program in which it is defined.
Priority-number
An integer or a positive signed numeric literal ranging in value
from 0 through 99. Priority-number identifies a fixed segment or an
independent segment that is to contain the section.
Sections in the declaratives portion must contain priority numbers in the
range of 0 through 49.
You cannot specify priority-numbers:
v In a method definition
v In a program that is declared with the RECURSIVE attribute
v In a program compiled with the THREAD compiler option
A section ends immediately before the next section header, or at the end of
the PROCEDURE DIVISION, or, in the declaratives portion, at the
keywords END DECLARATIVES.
Segments
A segment consists of all sections in a program that have the same
priority-number. Priority-number determines whether a section is stored in
a fixed segment or an independent segment at run time.
Segments with a priority-number of 0 through 49 are fixed segments.
Segments with a priority-number of 50 through 99 are independent
segments.
The type of segment (fixed or independent) controls the segmentation
feature.
In fixed segments, procedures are always in last-used state. In independent
segments, procedures are in initial state each time the segment receives
control from a segment with a different priority-number, except when the
transfer of control results from the execution of a GOBACK or EXIT
PROGRAM statement. Restrictions on the use of ALTER, SORT, and
MERGE statements in independent segments are described under those
statements.
Enterprise COBOL does not support the overlay feature of the 85 COBOL
Standard segmentation module.

260 Enterprise COBOL for z/OS, V6.1 Language Reference

 Paragraph
A paragraph-name followed by a separator period, optionally followed by
one or more sentences.
Paragraphs must be preceded by a period because paragraphs always
follow either the IDENTIFICATION DIVISION header, a section, or
another paragraph, all of which must end with a period.
Paragraph-name
A user-defined word that identifies a paragraph. A
paragraph-name, because it can be qualified, need not be unique.
If there are no declaratives (format 2), a paragraph-name is not
required in the PROCEDURE DIVISION.
A paragraph ends immediately before the next paragraph-name or section
header, or at the end of the PROCEDURE DIVISION, or, in the declaratives
portion, at the keywords END DECLARATIVES.
Paragraphs need not all be contained within sections, even if one or more
paragraphs are so contained.
Sentence
One or more statements terminated by a separator period.
Statement
A syntactically valid combination of identifiers and symbols (literals,
relational-operators, and so forth) beginning with a COBOL statement.
Identifier
The word or words necessary to make unique reference to a data item,
optionally including qualification, subscripting, indexing, and
reference-modification. In any PROCEDURE DIVISION reference (except
the class test), the contents of an identifier must be compatible with the
class specified through its PICTURE clause, otherwise results are
unpredictable.

Execution begins with the first statement in the PROCEDURE DIVISION,

excluding declaratives. Statements are executed in the order in which they are
presented for compilation, unless the statement rules dictate some other order of
execution.

The end of the PROCEDURE DIVISION is indicated by one of the following items:
v An IDENTIFICATION DIVISION header that indicates the start of a nested
source program
v An END PROGRAM, END METHOD, END FACTORY, or END OBJECT marker
v The physical end of a program; that is, the physical position in a source program
after which no further source program lines occur

Arithmetic expressions
Arithmetic expressions are used as operands of certain conditional and arithmetic
statements.

An arithmetic expression can consist of any of the following items:

1. An identifier described as a numeric elementary item (including numeric
functions)
2. A numeric literal

Chapter 19. Procedure division structure 261

 3. The figurative constant ZERO
4. Identifiers and literals, as defined in items 1, 2, and 3, separated by arithmetic
operators
5. Two arithmetic expressions, as defined in items 1, 2, 3, or 4, separated by an
arithmetic operator
6. An arithmetic expression, as defined in items 1, 2, 3, 4, or 5, enclosed in
parentheses

Any arithmetic expression can be preceded by a unary operator.

Identifiers and literals that appear in arithmetic expressions must represent either
numeric elementary items or numeric literals on which arithmetic can be
performed.

If an exponential expression is evaluated as both a positive and a negative number,

the result is always the positive number. For example, the square root of 4:
4 ** 0.5

is evaluated as +2 and -2. Enterprise COBOL always returns +2.

If the value of an expression to be raised to a power is zero, the exponent must

have a value greater than zero. Otherwise, the size error condition exists. In any
case where no real number exists as the result of an evaluation, the size error
condition exists.

Arithmetic operators
Five binary arithmetic operators and two unary arithmetic operators can be used in
arithmetic expressions. These operators are represented by specific characters that
must be preceded and followed by a space.

These binary and unary arithmetic operators are shown in Table 17.
Table 17. Binary and unary operators
Binary operator Meaning Unary operator Meaning
+ Addition + Multiplication by +1
- Subtraction - Multiplication by -1
* Multiplication
/ Division
** Exponentiation

Limitation: Exponents in fixed-point exponential expressions cannot contain more

than nine digits. The compiler will truncate any exponent with more than nine
digits. In the case of truncation, the compiler will issue a diagnostic message if the
exponent is a literal or constant; if the exponent is a variable or data-name, a
diagnostic message is issued at run time.

Parentheses can be used in arithmetic expressions to specify the order in which

elements are to be evaluated.

Expressions within parentheses are evaluated first. When expressions are contained
within nested parentheses, evaluation proceeds from the least inclusive to the most
inclusive set.

262 Enterprise COBOL for z/OS, V6.1 Language Reference

When parentheses are not used, or parenthesized expressions are at the same level
of inclusiveness, the following hierarchic order is implied:
1. Unary operator
2. Exponentiation
3. Multiplication and division
4. Addition and subtraction

Parentheses either eliminate ambiguities in logic where consecutive operations

appear at the same hierarchic level, or modify the normal hierarchic sequence of
execution when this is necessary. When the order of consecutive operations at the
same hierarchic level is not completely specified by parentheses, the order is from
left to right.

An arithmetic expression can begin only with a left parenthesis, a unary operator,
or an operand (that is, an identifier or a literal). It can end only with a right
parenthesis or an operand. An arithmetic expression must contain at least one
reference to an identifier or a literal.

There must be a one-to-one correspondence between left and right parentheses in

an arithmetic expression, with each left parenthesis placed to the left of its
corresponding right parenthesis.

If the first operator in an arithmetic expression is a unary operator, it must be

immediately preceded by a left parenthesis if that arithmetic expression
immediately follows an identifier or another arithmetic expression.

The following table shows permissible arithmetic symbol pairs. An arithmetic

symbol pair is the combination of two such symbols in sequence. In the table:
Yes Indicates a permissible pairing.
No Indicates that the pairing is not permitted.
Table 18. Valid arithmetic symbol pairs
Identifier or Unary + or
literal * / ** + - unary -
second second second ( second ) second
symbol symbol symbol symbol symbol
Identifier or No Yes No No Yes
literal first
symbol
* / ** + - Yes No Yes Yes No
first symbol
Unary + or Yes No No Yes No
unary - first
symbol
( Yes No Yes Yes No
first symbol
) No Yes No No Yes
first symbol

Chapter 19. Procedure division structure 263

Conditional expressions
A conditional expression causes the object program to select alternative paths of
control, depending on the truth value of a test. Conditional expressions are
specified in EVALUATE, IF, PERFORM, and SEARCH statements.

A conditional expression can be specified in either simple conditions or complex

conditions. Both simple and complex conditions can be enclosed within any
number of paired parentheses; the parentheses do not change whether the
condition is simple or complex.

Simple conditions
There are five simple conditions.

The simple conditions are:

v Class condition
v Condition-name condition
v Relation condition
v Sign condition
v Switch-status condition

A simple condition has a truth value of either true or false.

Class condition
The class condition determines whether the content of a data item is alphabetic,
alphabetic-lower, alphabetic-upper, numeric, DBCS, KANJI, or contains only the
characters in the set of characters specified by the CLASS clause as defined in the
SPECIAL-NAMES paragraph of the ENVIRONMENT DIVISION.

Format

►► identifier-1 NUMERIC ►◄
IS NOT ALPHABETIC
ALPHABETIC-LOWER
ALPHABETIC-UPPER
class-name
DBCS
KANJI

identifier-1
Must reference a data item described with one of the following usages:
v DISPLAY, NATIONAL, COMPUTATIONAL-3, or PACKED-DECIMAL
when NUMERIC is specified
v DISPLAY-1 when DBCS or KANJI is specified
v DISPLAY or NATIONAL when ALPHABETIC, ALPHABETIC-UPPER, or
ALPHABETIC-LOWER is specified
v DISPLAY when class-name is specified
Must not be of class alphabetic when NUMERIC is specified.

264 Enterprise COBOL for z/OS, V6.1 Language Reference

 Must not be of class numeric when ALPHABETIC, ALPHABETIC-UPPER,
or ALPHABETIC-LOWER is specified.
Table 19 on page 266 lists the forms of class condition that are valid for
each type of identifier.
If identifier-1 is a function-identifier, it must reference an alphanumeric or
national function.
An alphanumeric group item can be used in a class condition where an
elementary alphanumeric item can be used, except that the NUMERIC class
condition cannot be used if the group contains one or more signed
elementary items.
When identifier-1 is described with usage NATIONAL, the class-condition
tests for the national character representation of the characters associated
with the specified character class. For example, specifying a class condition
of the form IF national-item IS ALPHABETIC is a test for the lowercase
and uppercase letters Latin capital letter A through Latin capital letter Z
and the space, as represented in national characters. Specifying IF
national-item is NUMERIC is a test for the characters 0 through 9.
NOT When used, NOT and the next keyword define the class test to be executed
for truth value. For example, NOT NUMERIC is a truth test for
determining that the result of a NUMERIC class test is false (in other
words, the item contains data that is nonnumeric).
NUMERIC
identifier-1 consists entirely of the characters 0 through 9, with or without
an operational sign.
If its PICTURE does not contain an operational sign, the identifier being
tested is determined to be numeric only if the contents are numeric and an
operational sign is not present.
If its PICTURE does contain an operational sign, the identifier being tested
is determined to be numeric only if the item is an elementary item, the
contents are numeric, and a valid operational sign is present.
Usage note: Valid operational signs are determined from the setting of the
NUMCLS installation option and the NUMPROC compiler option. For
more information, see Checking for incompatible data (numeric class test) in the
Enterprise COBOL Programming Guide.
ALPHABETIC
identifier-1 consists entirely of any combination of the lowercase or
uppercase Latin alphabetic characters A through Z and the space.
ALPHABETIC-LOWER
identifier-1 consists entirely of any combination of the lowercase Latin
alphabetic characters a through z and the space.
ALPHABETIC-UPPER
identifier-1 consists entirely of any combination of the uppercase Latin
alphabetic characters A through Z and the space.
class-name
identifier-1 consists entirely of the characters listed in the definition of
class-name in the SPECIAL-NAMES paragraph.
DBCS
identifier-1 consists entirely of DBCS characters.

Chapter 19. Procedure division structure 265

 A range check is performed on the item for valid character representation.
The valid range is X'41' through X'FE' for both bytes of each DBCS
character and X'4040' for the DBCS blank.
KANJI
identifier-1 consists entirely of DBCS characters.
A range check is performed on the item for valid character representation.
The valid range is from X'41' through X'7E' for the first byte, from X'41'
through X'FE' for the second byte, and X'4040' for the DBCS blank.
Table 19. Valid forms of the class condition for different types of data items
Type of data item
referenced by identifier-1 Valid forms of the class condition
Alphabetic ALPHABETIC NOT ALPHABETIC
ALPHABETIC-LOWER NOT ALPHABETIC-LOWER
ALPHABETIC-UPPER NOT ALPHABETIC-UPPER
class-name NOT class-name
Alphanumeric, ALPHABETIC NOT ALPHABETIC
alphanumeric-edited, or ALPHABETIC-LOWER NOT ALPHABETIC-LOWER
numeric-edited ALPHABETIC-UPPER NOT ALPHABETIC-UPPER
NUMERIC NOT NUMERIC
class-name NOT class-name
External-decimal NUMERIC NOT NUMERIC
or internal-decimal
DBCS DBCS NOT DBCS
KANJI NOT KANJI
National NUMERIC NOT NUMERIC
ALPHABETIC NOT ALPHABETIC
ALPHABETIC-LOWER NOT ALPHABETIC-LOWER
ALPHABETIC-UPPER NOT ALPHABETIC-UPPER
Numeric NUMERIC NOT NUMERIC
class-name NOT class-name

Condition-name condition
A condition-name condition tests a conditional variable to determine whether its
value is equal to any values that are associated with the condition-name.

Format

►► condition-name-1 ►◄

A condition-name is used in conditions as an abbreviation for the relation

condition. The rules for comparing a conditional variable with a condition-name
value are the same as those specified for relation conditions.

If condition-name-1 has been associated with a range of values (or with several
ranges of values), the conditional variable is tested to determine whether its value

266 Enterprise COBOL for z/OS, V6.1 Language Reference

 falls within the ranges, including the end values. The result of the test is true if one
of the values that corresponds to the condition-name equals the value of its
associated conditional variable.

Condition-names are allowed for alphanumeric, DBCS, national, and floating-point

data items, as well as others, as defined for the condition-name format of the
VALUE clause.

The following example illustrates the use of conditional variables and

condition-names:
01 AGE-GROUP PIC 99.
88 INFANT VALUE 0.
88 BABY VALUE 1, 2.
88 CHILD VALUE 3 THRU 12.
88 TEENAGER VALUE 13 THRU 19.

AGE-GROUP is the conditional variable; INFANT, BABY, CHILD, and TEENAGER

are condition-names. For individual records in the file, only one of the values
specified in the condition-name entries can be present.

The following IF statements can be added to the above example to determine the
age group of a specific record:
IF INFANT... (Tests for value 0)
IF BABY... (Tests for values 1, 2)
IF CHILD... (Tests for values 3 through 12)
IF TEENAGER... (Tests for values 13 through 19)

Depending on the evaluation of the condition-name condition, alternative paths of

execution are taken by the object program.

Relation conditions
A relation condition specifies the comparison of two operands. The relational
operator that joins the two operands specifies the type of comparison. The relation
condition is true if the specified relation exists between the two operands; the
relation condition is false if the specified relation does not exist.

Comparisons are defined for the following cases:

v Two operands of class alphabetic
v Two operands of class alphanumeric
v Two operands of class DBCS
v Two operands of class national
v Two operands of class numeric
v Two operands of different classes where each operand is one of the classes
alphabetic, alphanumeric, or national
v Two operands where one is a numeric integer and the other is class
alphanumeric or national
v Two operands where one is class DBCS and the other is class national
v Comparisons involving indexes or index data items
v Two data pointer operands
v Two procedure pointer operands
v Two function pointer operands
v Two object reference operands

Chapter 19. Procedure division structure 267

 v An alphanumeric group and any operand that has usage DISPLAY, DISPLAY-1,
or NATIONAL

The following relation condition formats are defined:

v A general relation condition, for comparisons that involve only data items,
literals, index-names, or index data items. For details, see “General relation
conditions.”
v A data pointer relation condition. For details, see “Data pointer relation
conditions” on page 275.
v A program pointer relation condition, for comparison of procedure pointers or
function pointers. For details, see “Procedure-pointer and function-pointer
relation conditions” on page 276.
v An object-reference relation condition. For details, see “Object-reference relation
conditions” on page 277.

General relation conditions

A general relation condition compares two operands, either of which can be an
identifier, literal, arithmetic expression, or index-name.

Format 1: general relation condition

►► operand-1 GREATER operand-2 ►◄

IS NOT THAN
>
LESS
THAN
<
EQUAL
TO
=
GREATER OR EQUAL
THAN TO
>=
LESS OR EQUAL
THAN TO
<=

operand-1
The subject of the relation condition. Can be an identifier, literal,
function-identifier, arithmetic expression, or index-name.
operand-2
The object of the relation condition. Can be an identifier, literal,
function-identifier, arithmetic expression, or index-name.

An alphanumeric literal can be enclosed in parentheses within a relation condition.

The relation condition must contain at least one reference to an identifier.

268 Enterprise COBOL for z/OS, V6.1 Language Reference

The relational operators, shown in Table 20, specify the type of comparison to be
made. Each relational operator must be preceded and followed by a space. The
two characters of the relational operators >= and <= must not have a space between
them.
Table 20. Relational operators and their meanings
Relational operator Can be written Meaning
IS GREATER THAN IS > Greater than
IS NOT GREATER THAN IS NOT > Not greater than
IS LESS THAN IS < Less than
IS NOT LESS THAN IS NOT < Not less than
IS EQUAL TO IS = Equal to
IS NOT EQUAL TO IS NOT = Not equal to
IS GREATER THAN OR EQUAL IS >= Is greater than or equal to
TO
IS LESS THAN OR EQUAL TO IS <= Is less than or equal to

In a general relation condition, data items, literals, and figurative constants of class
alphabetic, alphanumeric, DBCS, national, and numeric are compared using the
following comparison types:

Comparison type Meaning

Alphanumeric Comparison of the alphanumeric character value of two
operands
DBCS Comparison of the DBCS character value of two operands
National Comparison of the national character value of two operands
Numeric Comparison of the algebraic value of two operands
Group Comparison of the alphanumeric character value of two
operands, where one or both operands is an alphanumeric
group item

Table 21 on page 270 and Table 22 on page 271 show the permissible pairs for
comparisons with different types of operands. The comparison type is indicated at
the row and column intersection for permitted comparisons, using the following
key:
Alph Comparison of alphanumeric characters (further described in
“Alphanumeric comparisons” on page 271)
DBCS Comparison of DBCS characters (further described in “DBCS comparisons”
on page 273)
Nat Comparison of national characters (further described in “National
comparisons” on page 273)
Num Comparison of algebraic value (further described in “Numeric
comparisons” on page 274)
Group Comparison of alphanumeric characters involving an alphanumeric group
(further described in “Group comparisons” on page 274)
(Int) Integer items only (combined with comparison type Alph, Nat, Num, or
Group)

Chapter 19. Procedure division structure 269

 Blank Comparison is not allowed

For rules and restrictions for comparisons involving index-names and index data
items, see “Comparison of index-names and index data items” on page 275.

Introduction to Table 21: This table is organized in the following manner:

v In the first column, under "Type of data item or literal", each row identifies a
type of operand. In some cases, the type of operand references a grouping of
operands that have common properties for comparison. For example, the row for
"Alphanumeric character items" references all the types of operands that are
listed in the cell, as follows:
– Data items of category:
- Alphanumeric
- Alphanumeric- edited
- Numeric-edited with usage DISPLAY
– Alphanumeric functions
v Subsequent column headings refer to the type of an operand or a grouping of
operands. For example, the column heading "Alphabetic and alphanumeric
character items" refers to the types of operands identified as "Alphabetic data
items" and all the types of operands that are grouped under the operand titled
"Alphanumeric character items".
v Literals are listed as a type of operand only in the first column. They do not
appear as column headings because literals cannot be used as both operands of
a relation condition.
Table 21. Comparisons involving data items and literals
Alpha-
betic and Alpha-
Alpha- alpha- numeric National
numeric numeric Zoned Native floating- National National floating-
group character decimal numeric point character decimal point DBCS
Type of data item or literal items items items items items items items items items
Alphanumeric group item Group Group Group Group Group Group Group Group
(Int) (Int)
Alphabetic data items Group Alph Alph Alph Nat Alph (Int) Nat
(Int)
Alphanumeric character Group Alph Alph Alph Nat Alph (Int) Nat
items: (Int)
v Data items of category:
– Alphanumeric
– Alphanumeric- edited
– Numeric-edited with
usage DISPLAY
v Alphanumeric functions
Alphanumeric literals Group Alph Alph Alph Nat Alph (Int) Nat
(Int)
Numeric literals Group Alph (Int) Num Num Num Nat (Int) Num Num
(Int)
Zoned decimal data items Group Alph (Int) Num Num Num Nat (Int) Num Num
(Int)

270 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 21. Comparisons involving data items and literals (continued)
Alpha-
betic and Alpha-
Alpha- alpha- numeric National
numeric numeric Zoned Native floating- National National floating-
group character decimal numeric point character decimal point DBCS
Type of data item or literal items items items items items items items items items
Native numeric items: Num Num Num Num Num
v Binary
v Arithmetic expression
v Internal decimal
v Internal floating point

Numeric and integer

intrinsic functions
Display floating-point Group Alph Num Num Num Nat Num Num
items
Floating-point literals Num Num Num Num Num
National character items: Group Nat Nat (Int) Nat Nat Nat (Int) Nat Nat
v Data items of category:
– National
– National- edited
– Numeric- edited with
usage NATIONAL
v National intrinsic
functions
v National groups (treated
as elementary item)
National literals Group Nat Nat (Int) Nat Nat Nat (Int) Nat Nat
National decimal items Group Alph (Int) Num Num Num Nat (Int) Num Num
(Int)
National floating-point Group Nat Num Num Num Nat Num Num
items
DBCS data items Group Nat DBCS
DBCS literals Group Nat DBCS

Table 22. Comparisons involving figurative constants

Alpha-
betic and
Alpha- alpha- Alpha-
numeric numeric Zoned Native numeric National National National
group character decimal numeric floating character decimal floating DBCS
Figurative constant items items items items point items items items point items items
ZERO Group Alph Num Num Num Nat Num Num
SPACE Group Alph Alph (Int) Alph Nat Nat (Int) Nat DBCS
HIGH-VALUE, Group Alph Alph (Int) Alph Nat Nat (Int) Nat
LOW-VALUE
QUOTE
Symbolic character Group Alph Alph (Int) Alph Nat Nat (Int) Nat
ALL alphanumeric literal Group Alph Alph (Int) Alph Nat Nat (Int) Nat
ALL national literal Group Nat Nat (Int) Nat Nat Nat (Int) Nat Nat
ALL DBCS literal Group Nat DBCS

Alphanumeric comparisons
An alphanumeric comparison is a comparison of the single-byte character values of
two operands.

Chapter 19. Procedure division structure 271

 When one of the operands is neither class alphanumeric nor class alphabetic, that
operand is processed as follows:
v A display floating-point data item is treated as though it were a data item of
category alphanumeric, rather than as a numeric value.
v A zoned decimal integer operand is treated as though it were moved to a
temporary elementary data item of category alphanumeric with a length the
same as the total number of digits in the number, according to the rules of the
MOVE statement.
When the ZWB compiler option is in effect, the unsigned value of the integer
operand is moved to the temporary data item. When the NOZWB compiler
option is specified, the signed value is moved to the temporary data item. See
ZWB in the Enterprise COBOL Programming Guide for more details about the
ZWB (NOZWB) compiler option.
Comparison then proceeds with the temporary data item of category
alphanumeric.

Comparison of two alphanumeric operands

Alphanumeric comparisons are made with respect to the collating sequence of the
character set in use as follows:
v For the EBCDIC character set, the EBCDIC collating sequence is used.
v For the ASCII character set, the ASCII collating sequence is used. (See
Appendix C, “EBCDIC and ASCII collating sequences,” on page 609.)
v When the PROGRAM COLLATING SEQUENCE clause is specified in the
object-computer paragraph, the collating sequence used is the one associated in
the special-names paragraph with the specified alphabet-name.

The size of each operand is the total number of character positions in that operand;
the size affects the result of the comparison. There are two cases to consider:
Operands of equal size
Characters in corresponding positions of the two operands are compared,
beginning with the leftmost character and continuing through the
rightmost character.
If all pairs of characters through the last pair evaluate as equal, the
operands are equal.
If a pair of unequal characters is encountered, the characters are tested to
determine their relative positions in the collating sequence. The operand
that contains the character higher in the sequence is considered the greater
operand.
Operands of unequal size
If the operands are of unequal size, the comparison is made as though the
shorter operand were extended to the right with enough spaces to make
the operands equal in size.

The higher collating value is determined using the hexadecimal value of

characters.
Standard comparison
A standard comparison is any comparison that is not based on a locale.
The standard comparison method depends on whether the operands to be
compared are of equal length or unequal length.

272 Enterprise COBOL for z/OS, V6.1 Language Reference

 If the operands are of unequal length, the comparison proceeds as though
the shorter operand were padded on the right with appropriate space
characters to make the operands of equal length. The comparison then
proceeds according to the rules for the comparison of operands of equal
length.
If the operands are of equal length, the comparison proceeds by comparing
corresponding character positions in the two operands, starting from the
leftmost position, until either unequal characters are encountered or the
rightmost character position is reached, whichever comes first. The
operands are determined to be equal if all corresponding characters are
equal.
The first-encountered unequal character in the operands is compared to
determine the relation of the operands. The operand that contains the
character with the higher collating value is the greater operand.

DBCS comparisons
A DBCS comparison is a comparison of two DBCS operands.

The following rules apply to a DBCS comparison:

v If the DBCS operands are not the same length, the comparison is made as
though the shorter operand were padded on the right with DBCS spaces to the
length of the longer operand.
v The comparison is based on the binary collating sequence of the hexadecimal
values of the DBCS characters.

National comparisons
A national comparison is a comparison of the national character value of two
operands of class national.

When the relation condition specifies an operand that is not class national, that
operand is converted to a data item of category national before the comparison.
The following list describes the conversion of operands to category national.
DBCS
A DBCS operand is treated as though it were moved to a temporary data
item of category national of the same length as the DBCS operand. DBCS
characters are converted to the corresponding national characters. The
source code page used for the conversion is the one in effect for the
CODEPAGE compiler option when the source code was compiled.
Alphabetic, alphanumeric, alphanumeric-edited, and numeric-edited with usage
DISPLAY
The operand is treated as though it were moved to a temporary data item
of category national of the length needed to represent the number of
character positions in that operand. Alphanumeric characters are converted
to the corresponding national characters. The source code page used for
the conversion is the one in effect for the CODEPAGE compiler option
when the source code was compiled.
Numeric integer
A numeric integer operand is treated as though it were moved to a
temporary data item of category alphanumeric of a length the same as the
number of digits in the integer. The unsigned value is used. The resulting
temporary data item is then converted as an alphanumeric operand.

Chapter 19. Procedure division structure 273

 External floating-point
A display floating-point item is treated as though it were a data item of
category alphanumeric, rather than as a numeric value, and then converted
as an alphanumeric operand.
A national floating-point item is treated as though it were a data item of
category national, rather than as a numeric value.

The implicit moves for the conversions are carried out in accordance with the rules
of the MOVE statement.

The resulting category national data item is used in the comparison of two national
operands.

Comparison of two national operands

If the operands are of unequal length, the comparison proceeds as though the
shorter operand were padded on the right with the default national space character
(NX'0020') to make the operands of equal length. The comparison then proceeds
according to the rules for the comparison of operands of equal length.

If the operands are of equal length, the comparison proceeds by comparing

corresponding national character positions in the two operands, starting from the
leftmost position, until either unequal national characters are encountered or the
rightmost national character position is reached, whichever comes first. The
operands are determined to be equal if all corresponding national characters are
equal.

The first-encountered unequal national character in the operands is compared to

determine the relation of the operands. The operand that contains the national
character with the higher collating value is the greater operand.

The higher collating value is determined using the hexadecimal value of

characters.

The PROGRAM COLLATING SEQUENCE clause has no effect on comparisons of

national operands.

Numeric comparisons
A numeric comparison is a comparison of the algebraic value of two operands of
class numeric.

When the algebraic values of numeric operands are compared:

v The length (number of digits) of the operands is not significant.
v The usage of the operands is not significant.
v Unsigned numeric operands are considered positive.
v All zero values compare equal; the presence or absence of a sign does not affect
the result.

The behavior of numeric comparisons depends on the settings of the NUMPROC

and ZONEDATA compiler options. For details, see NUMPROC and ZONEDATA in
the Enterprise COBOL Programming Guide.

Group comparisons
A group comparison is a comparison of the alphanumeric character values of two
operands.

274 Enterprise COBOL for z/OS, V6.1 Language Reference

 For the comparison operation, each operand is treated as though it were an
elementary data item of category alphanumeric of the same size as the operand, in
bytes. The comparison then proceeds as for two elementary operands of category
alphanumeric, as described in “Alphanumeric comparisons” on page 271.

Usage note: There is no conversion of data for group comparisons. The comparison
operates on bytes of data without regard to data representation. The result of
comparing an elementary item or literal operand to an alphanumeric group item is
predictable when that operand and the content of the group item have the same
data representation.

Comparison of index-names and index data items

Comparisons involving index-names, index data items, or both conform to rules.

The rules for comparisons are:

v The comparison of two index-names is actually the comparison of the
corresponding occurrence numbers.
v In the comparison of an index-name with a data item (other than an index data
item), or in the comparison of an index-name with a literal, the occurrence
number that corresponds to the value of the index-name is compared with the
data item or literal.
v In the comparison of an index-name with an arithmetic expression, the
occurrence number that corresponds to the value of the index-name is compared
with the arithmetic expression.
Because an integer function can be used wherever an arithmetic expression can
be used, you can compare an index-name to an integer or numeric function.
v In the comparison of an index data item with an index-name or another index
data item, the actual values are compared without conversion. Results of any
other comparison involving an index data item are undefined.

Valid comparisons for index-names and index data items are shown in the
following table.
Table 23. Comparisons for index-names and index data items
Data-name Literal
Operands Index data (numeric (numeric Arithmetic
compared Index-name item integer only) integer only) Expression
Index-name Compare Compare Compare Compare Compare
occurrence without occurrence occurrence occurrence
number conversion number with number with number with
content of literal arithmetic
referenced expression
data item
Index data Compare Compare Invalid Invalid Invalid
item without without
conversion conversion

Data pointer relation conditions

Only EQUAL and NOT EQUAL are allowed as relational operators when
specifying pointer data items.

Pointer data items are items defined explicitly as USAGE POINTER, or are
ADDRESS OF special registers, which are implicitly defined as USAGE POINTER.

Chapter 19. Procedure division structure 275

 The operands are equal if the two addresses used in the comparison would both
result in the same storage location.

This relation condition is allowed in IF, PERFORM, EVALUATE, and SEARCH

format-1 statements. It is not allowed in SEARCH format-2 (SEARCH ALL)
statements because there is no meaningful ordering that can be applied to pointer
data items.

Format 2: data-pointer relation condition

►► ADDRESS OF identifier-1 EQUAL ►

identifier-2 IS NOT TO
NULL =
NULLS

► ADDRESS OF identifier-3 ►◄
identifier-4
NULL
NULLS

identifier-1 , identifier-3
Can specify any level item defined in the LINKAGE SECTION, except 66
and 88.
identifier-2 , identifier-4
Must be described as USAGE POINTER.
NULL, NULLS
Can be used only if the other operand is defined as USAGE POINTER.
That is, NULL=NULL is not allowed.

The following table summarizes the permissible comparisons for USAGE

POINTER, NULL, and ADDRESS OF.
Table 24. Permissible comparisons for USAGE POINTER, NULL, and ADDRESS OF
Permissible USAGE POINTER ADDRESS OF NULL or NULLS
comparisons second operand second operand second operand
USAGE POINTER Yes Yes Yes
first operand
ADDRESS OF Yes Yes Yes
first operand
NULL/NULLS Yes Yes No
first operand

Yes Comparison allowed only for EQUAL, NOT EQUAL

No No comparison allowed

Procedure-pointer and function-pointer relation conditions

Only EQUAL and NOT EQUAL are allowed as relational operators when
specifying procedure-pointer or function-pointer data items in a relation condition.

276 Enterprise COBOL for z/OS, V6.1 Language Reference

 Procedure-pointer data items are defined explicitly as USAGE
PROCEDURE-POINTER. Function-pointer data items are defined explicitly as
USAGE FUNCTION-POINTER.

The operands are equal if the two addresses used in the comparison would both
result in the same storage location.

This relation condition is allowed in IF, PERFORM, EVALUATE, and SEARCH

format-1 statements. It is not allowed in SEARCH format-2 (SEARCH ALL)
statements, because there is no meaningful ordering that can be applied to
procedure-pointer data items.

Format 3: procedure-pointer and function-pointer relation condition

►► EQUAL ►◄
identifier-1 IS NOT TO identifier-2
NULL = NULL
NULLS NULLS

identifier-1 , identifier-2
Must be described as USAGE PROCEDURE-POINTER or USAGE
FUNCTION-POINTER. identifier-1 and identifier-2 need not be described the
same.
NULL, NULLS
Can be used only if the other operand is defined as USAGE
FUNCTION-POINTER or USAGE PROCEDURE-POINTER. That is,
NULL=NULL is not allowed.

Object-reference relation conditions

A data item of usage OBJECT REFERENCE can be compared for equality or
inequality with another data item of usage OBJECT REFERENCE or with NULL,
NULLS, or SELF.

Format 4: object-reference relation condition

►► object-reference-identifier-1 EQUAL ►
SELF IS NOT TO
NULL =
NULLS

► object-reference-identifier-2 ►◄
SELF
NULL
NULLS

A comparison with SELF is allowed only in a method.

Chapter 19. Procedure division structure 277

 Two object-references compare equal only if the data items identify the same
object.

Sign condition
The sign condition determines whether the algebraic value of a numeric operand is
greater than, less than, or equal to zero.

Format: sign condition

►► operand-1 POSITIVE ►◄
IS NOT NEGATIVE
ZERO

operand-1
Must be defined as a numeric identifier, or as an arithmetic expression that
contains at least one reference to a variable. operand-1 can be defined as a
floating-point identifier.
The operand is:
v POSITIVE if its value is greater than zero
v NEGATIVE if its value is less than zero
v ZERO if its value is equal to zero
An unsigned operand is either POSITIVE or ZERO.
NOT One algebraic test is executed for the truth value of the sign condition. For
example, NOT ZERO is regarded as true when the operand tested is
positive or negative in value.

The results of the sign condition test depend on the setting of the NUMPROC
compiler option. For details, see NUMPROC in the Enterprise COBOL Programming
Guide.

Switch-status condition
The switch-status condition determines the on or off status of a UPSI switch.

Format

►► condition-name ►◄

condition-name
Must be defined in the special-names paragraph as associated with the on
or off value of an UPSI switch. (See “SPECIAL-NAMES paragraph” on
page 116.)

The switch-status condition tests the value associated with condition-name. (The
value is considered to be alphanumeric.) The result of the test is true if the UPSI
switch is set to the value (0 or 1) corresponding to condition-name.

278 Enterprise COBOL for z/OS, V6.1 Language Reference

Complex conditions
A complex condition is formed by combining simple conditions, combined
conditions, or complex conditions with logical operators, or negating those
conditions with logical negation.

Each logical operator must be preceded and followed by a space. The following
table shows the logical operators and their meanings.
Table 25. Logical operators and their meanings
Logical
operator Name Meaning
AND Logical The truth value is true when both conditions are true.
conjunction
OR Logical The truth value is true when either or both conditions are
inclusive OR true.
NOT Logical Reversal of truth value (the truth value is true if the
negation condition is false).

Unless modified by parentheses, the following list is the order of precedence (from
highest to lowest):
1. Arithmetic operations
2. Simple conditions
3. NOT
4. AND
5. OR

The truth value of a complex condition (whether parenthesized or not) is the truth
value that results from the interaction of all the stated logical operators on either of
the following options:
v The individual truth values of simple conditions
v The intermediate truth values of conditions logically combined or logically
negated

A complex condition can be either of the following options:

v A negated simple condition
v A combined condition (which can be negated)

Negated simple conditions

A simple condition is negated through the use of the logical operator NOT.

Format

►► NOT condition-1 ►◄

The negated simple condition gives the opposite truth value of the simple
condition. That is, if the truth value of the simple condition is true, then the truth
value of that same negated simple condition is false, and vice versa.

Chapter 19. Procedure division structure 279

 Placing a negated simple condition within parentheses does not change its truth
value. That is, the following two statements are equivalent:
NOT A IS EQUAL TO B.
NOT (A IS EQUAL TO B).

Combined conditions
Two or more conditions can be logically connected to form a combined condition.

Format

►► condition-1 ▼ AND condition-2 ►◄

OR

The condition to be combined can be any of the following ones:

v A simple-condition
v A negated simple-condition
v A combined condition
v A negated combined condition (that is, the NOT logical operator followed by a
combined condition enclosed in parentheses)
v A combination of the preceding conditions that is specified according to the
rules in the following table
Table 26. Combined conditions—permissible element sequences
Combined When not leftmost, can When not rightmost, can
condition Left be immediately Right be immediately
element most preceded by: most followed by:
simple- Yes OR Yes OR
condition NOT AND
AND )
(
OR No simple-condition No simple-condition
AND ) NOT
(
NOT Yes OR No simple-condition
AND (
(
( Yes OR No simple-condition
NOT NOT
AND (
(
) No simple-condition Yes OR
) AND
)

280 Enterprise COBOL for z/OS, V6.1 Language Reference

Parentheses are never needed when either ANDs or ORs (but not both) are used
exclusively in one combined condition. However, parentheses might be needed to
modify the implicit precedence rules to maintain the correct logical relation of
operators and operands.

There must be a one-to-one correspondence between left and right parentheses,

with each left parenthesis to the left of its corresponding right parenthesis.

The following table illustrates the relationships between logical operators and
conditions C1 and C2.
Table 27. Logical operators and evaluation results of combined conditions
NOT NOT NOT
C1 (C1 C1 (C1
Value Value AND C1 OR AND AND OR NOT C1
for C1 for C2 C2 C2 C2) C2 C2) OR C2
True True True True False False False True
False True False True True True False True
True False False True True False False False
False False False False True False True True

Order of evaluation of conditions

Parentheses, both explicit and implicit, define the level of inclusiveness within a
complex condition. Two or more conditions connected by only the logical operators
AND or OR at the same level of inclusiveness establish a hierarchical level within
a complex condition. Therefore an entire complex condition is a nested structure of
hierarchical levels, with the entire complex condition being the most inclusive
hierarchical level.

Within this context, the evaluation of the conditions within an entire complex
condition begins at the left of the condition. The constituent connected conditions
within a hierarchical level are evaluated in order from left to right, and evaluation
of that hierarchical level terminates as soon as a truth value for it is determined,
regardless of whether all the constituent connected conditions within that
hierarchical level have been evaluated.

Values are established for arithmetic expressions and functions if and when the
conditions that contain them are evaluated. Similarly, negated conditions are
evaluated if and when it is necessary to evaluate the complex condition that they
represent. For example:
NOT A IS GREATER THAN B OR A + B IS EQUAL TO C AND D IS POSITIVE

is evaluated as if parenthesized as follows:

(NOT (A IS GREATER THAN B)) OR
(((A + B) IS EQUAL TO C) AND (D IS POSITIVE))

Order of evaluation:
1. (NOT (A IS GREATER THAN B)) is evaluated, giving some intermediate truth
value, t1. If t1 is true, the combined condition is true, and no further evaluation
takes place. If t1 is false, evaluation continues as follows.
2. (A + B) is evaluated, giving some intermediate result, x.

Chapter 19. Procedure division structure 281

 3. (x IS EQUAL TO C) is evaluated, giving some intermediate truth value, t2. If t2 is
false, the combined condition is false, and no further evaluation takes place. If
t2 is true, the evaluation continues as follows.
4. (D IS POSITIVE) is evaluated, giving some intermediate truth value, t3. If t3 is
false, the combined condition is false. If t3 is true, the combined condition is
true.

Abbreviated combined relation conditions

When relation-conditions are written consecutively, any relation-condition after the
first can be abbreviated by omission of the subject, or by omission of the subject
and relational operator.

Format

►► relation-condition ►

► ▼ AND object ►◄
OR NOT relational-operator

In any consecutive sequence of relation-conditions, both forms of abbreviation can

be specified. The abbreviated condition is evaluated as if:
1. The last stated subject is the missing subject.
2. The last stated relational operator is the missing relational operator.

The resulting combined condition must comply with the rules for element
sequences in combined conditions, as shown in “Combined conditions” on page
280.

If NOT is immediately followed by GREATER THAN, >, LESS THAN, <, EQUAL
TO, or =, then the NOT participates as part of the relational operator. NOT in any
other position is considered a logical operator (and thus results in a negated
relation condition).

Using parentheses
You can use parentheses in combined relation conditions to specify an intended
order of evaluation. Using parentheses can also help improve the readability of
conditional expressions.

The following rules govern the use of parentheses in abbreviated combined

relation conditions:
1. Parentheses can be used to change the order of evaluation of the logical
operators AND and OR.
2. The word NOT participates as part of the relational operator when it is
immediately followed by GREATER THAN, >, LESS THAN, <, EQUAL TO, or
=.

282 Enterprise COBOL for z/OS, V6.1 Language Reference

 3. NOT in any other position is considered a logical operator and thus results in
a negated relation condition. If you use NOT as a logical operator, only the
relation condition immediately following the NOT is negated; the negation is
not propagated through the abbreviated combined relation condition along
with the subject and relational operator.
4. The logical NOT operator can appear within a parenthetical expression that
immediately follows a relational operator.
5. When a left parenthesis appears immediately after the relational operator, the
relational operator is distributed to all objects enclosed in the parentheses. In
the case of a "distributed" relational operator, the subject and relational
operator remain current after the right parenthesis which ends the
distribution. The following three restrictions apply to cases where the
relational operator is distributed throughout the expression:
a. A simple condition cannot appear within the scope of the distribution.
b. Another relational operator cannot appear within the scope of the
distribution.
c. The logical operator NOT cannot appear immediately after the left
parenthesis, which defines the scope of the distribution.
6. Evaluation proceeds from the least to the most inclusive condition.
7. There must be a one-to-one correspondence between left and right
parentheses, with each left parenthesis to the left of its corresponding right
parenthesis. If the parentheses are unbalanced, the compiler inserts a
parenthesis and issues an E-level message. However, if the compiler-inserted
parenthesis results in the truncation of the expression, you will receive an
S-level diagnostic message.
8. The last stated subject is inserted in place of the missing subject.
9. The last stated relational operator is inserted in place of the missing relational
operator.
10. Insertion of the omitted subject or relational operator ends when:
a. Another simple condition is encountered.
b. A condition-name is encountered.
c. A right parenthesis is encountered that matches a left parenthesis that
appears to the left of the subject.
11. In any consecutive sequence of relation conditions, you can use both
abbreviated relation conditions that contain parentheses and those that do not.
12. Consecutive logical NOT operators cancel each other and result in an S-level
message. Note, however, that an abbreviated combined relation condition can
contain two consecutive NOT operators when the second NOT is part of a
relational operator. For example, you can abbreviate the first condition as the
second condition listed below.
A = B and not A not = C
A = B and not not = C

The following table summarizes the rules for forming an abbreviated combined
relation condition.
Table 28. Abbreviated combined conditions: permissible element sequences
Combined
condition When not leftmost, can be When not rightmost, can be
element Left- most immediately preceded by: Right- most immediately followed by:
Subject Yes NOT No Relational operator
(

Chapter 19. Procedure division structure 283

 Table 28. Abbreviated combined conditions: permissible element sequences (continued)
Combined
condition When not leftmost, can be When not rightmost, can be
element Left- most immediately preceded by: Right- most immediately followed by:
Object No Relational operator Yes AND
AND OR
OR )
NOT
(
Relational No Subject No Object
operator AND (
OR
NOT
AND No Object No Object
OR ) Relational operator
NOT
(
NOT Yes AND No Subject
OR Object
( Relational operator
(
( Yes Relational operator No Subject
AND Object
OR NOT
NOT (
(
) No Object Yes AND
) OR
)

The following table shows examples of abbreviated combined relation conditions,

with and without parentheses, and their unabbreviated equivalents.
Table 29. Abbreviated combined conditions: unabbreviated equivalents
Abbreviated combined relation condition Equivalent
A = B AND NOT < C OR D ((A = B) AND (A NOT < C)) OR (A NOT < D)
A NOT > B OR C (A NOT > B) OR (A NOT > C)
NOT A = B OR C (NOT (A = B)) OR (A = C)
NOT (A = B OR < C) NOT ((A = B) OR (A < C))
NOT (A NOT = B AND C AND NOT D) NOT ((((A NOT = B) AND (A NOT = C)) AND (NOT
(A NOT = D))))

Statement categories
There are four categories of COBOL statements: imperative statements, conditional
| statements, delimited scope statements, and compiler-directing statements. See the
| following topics for more details.

Imperative statements
An imperative statement either specifies an unconditional action to be taken by the
program, or is a conditional statement terminated by its explicit scope terminator.

284 Enterprise COBOL for z/OS, V6.1 Language Reference

 A series of imperative statements can be specified wherever an imperative
statement is allowed. A conditional statement that is terminated by its explicit
scope terminator is also classified as an imperative statement.

For more information about explicit scope terminator, see “Delimited scope
statements” on page 288.

The following lists contain the COBOL imperative statements.

Arithmetic
v ADD1
v COMPUTE1
v DIVIDE1
v MULTIPLY1
v SUBTRACT1

1. Without the ON SIZE ERROR or the NOT ON SIZE ERROR phrase.

Data movement
v ACCEPT (DATE, DAY, DAY-OF-WEEK, TIME)
v INITIALIZE
v INSPECT
| v JSON GENERATE3
v MOVE
v SET
v STRING2
v UNSTRING2
v XML GENERATE3
v XML PARSE3

2. Without the ON OVERFLOW or the NOT ON OVERFLOW phrase.

3. Without the ON EXCEPTION or NOT ON EXCEPTION phrase.

Ending
v STOP RUN
v EXIT PROGRAM
v EXIT METHOD
v GOBACK

Input-output
v ACCEPT identifier
v CLOSE
v DELETE4
v DISPLAY
v OPEN
v READ5
v REWRITE4
v START4

Chapter 19. Procedure division structure 285

 v STOP literal
v WRITE6

4. Without the INVALID KEY or the NOT INVALID KEY phrase.

5. Without the AT END or NOT AT END, and INVALID KEY or NOT INVALID
KEY phrases.

6. Without the INVALID KEY or NOT INVALID KEY, and END-OF-PAGE or NOT
END-OF-PAGE phrases.

Ordering
| v ALLOCATE
| v Format 1 SORT
| v FREE
v MERGE
v RELEASE
v RETURN7

7. Without the AT END or NOT AT END phrase.

Procedure-branching
v ALTER
v CONTINUE
v Format 1 EXIT
v GO TO
v PERFORM

Program or method linkage

v CALL8
v CANCEL
v INVOKE

8. Without the ON OVERFLOW phrase, and without the ON EXCEPTION or NOT

ON EXCEPTION phrase.

Table-handling
| v Format 2 SORT (table SORT)
v SET

Conditional statements
A conditional statement specifies that the truth value of a condition is to be
determined and that the subsequent action of the object program is dependent on
this truth value.

For more information about conditional expressions, see “Conditional expressions”

on page 264.)

The following lists contain COBOL statements that become conditional when a
condition (for example, ON SIZE ERROR or ON OVERFLOW) is included and
when the statement is not terminated by its explicit scope terminator.

286 Enterprise COBOL for z/OS, V6.1 Language Reference

 Arithmetic
v ADD ... ON SIZE ERROR
v ADD ... NOT ON SIZE ERROR
v COMPUTE ... ON SIZE ERROR
v COMPUTE ... NOT ON SIZE ERROR
v DIVIDE ... ON SIZE ERROR
v DIVIDE ... NOT ON SIZE ERROR
v MULTIPLY ... ON SIZE ERROR
v MULTIPLY ... NOT ON SIZE ERROR
v SUBTRACT ... ON SIZE ERROR
v SUBTRACT ... NOT ON SIZE ERROR

Data movement
| v JSON GENERATE ... ON EXCEPTION
| v JSON GENERATE ... NOT ON EXCEPTION
v STRING ... ON OVERFLOW
v STRING ... NOT ON OVERFLOW
v UNSTRING ... ON OVERFLOW
v UNSTRING ... NOT ON OVERFLOW
v XML GENERATE ... ON EXCEPTION
v XML GENERATE ... NOT ON EXCEPTION
v XML PARSE ... ON EXCEPTION
v XML PARSE ... NOT ON EXCEPTION

Decision
v IF
v EVALUATE

Input-output
v DELETE ... INVALID KEY
v DELETE ... NOT INVALID KEY
v READ ... AT END
v READ ... NOT AT END
v READ ... INVALID KEY
v READ ... NOT INVALID KEY
v REWRITE ... INVALID KEY
v REWRITE ... NOT INVALID KEY
v START ... INVALID KEY
v START ... NOT INVALID KEY
v WRITE ... AT END-OF-PAGE
v WRITE ... NOT AT END-OF-PAGE
v WRITE ... INVALID KEY
v WRITE ... NOT INVALID KEY

Chapter 19. Procedure division structure 287

 Ordering
v RETURN ... AT END
v RETURN ... NOT AT END

Program or method linkage

v CALL ... ON OVERFLOW
v CALL ... ON EXCEPTION
v CALL ... NOT ON EXCEPTION
v INVOKE ... ON EXCEPTION
v INVOKE ... NOT ON EXCEPTION

Table-handling
v SEARCH

Delimited scope statements

In general, a DELIMITED SCOPE statement uses an explicit scope terminator to
turn a conditional statement into an imperative statement.

The resulting imperative statement can then be nested. Explicit scope terminators
can also be used to terminate the scope of an imperative statement. Explicit scope
terminators are provided for all COBOL statements that can have conditional
phrases.

Unless explicitly specified otherwise, a delimited scope statement can be specified

wherever an imperative statement is allowed by the rules of the language.

Explicit scope terminators

An explicit scope terminator marks the end of certain PROCEDURE DIVISION
statements.

A conditional statement that is delimited by its explicit scope terminator is

considered an imperative statement and must follow the rules for imperative
statements.

These are the explicit scope terminators:

v END-ADD
v END-CALL
v END-COMPUTE
v END-DELETE
v END-DIVIDE
v END-EVALUATE
v END-IF
v END-INVOKE
| v END-JSON
v END-MULTIPLY
v END-PERFORM
v END-READ
v END-RETURN
v END-REWRITE

288 Enterprise COBOL for z/OS, V6.1 Language Reference

 v END-SEARCH
v END-START
v END-STRING
v END-SUBTRACT
v END-UNSTRING
v END-WRITE
v END-XML

Implicit scope terminators

At the end of any sentence, an implicit scope terminator is a separator period that
terminates the scope of all previous statements not yet terminated.

An unterminated conditional statement cannot be contained by another statement.

Except for nesting conditional statements within IF statements, nested statements

must be imperative statements and must follow the rules for imperative
statements. You should not nest conditional statements.

Compiler-directing statements
A compiler-directing statement is a statement that causes the compiler to take a
specific action during compilation.

For more information about statements that direct the compiler to take a specified
action, see Chapter 22, “Compiler-directing statements,” on page 559.

Statement operations
The topic shows types of operations performed by COBOL statements.

COBOL statements perform the following types of operations:

v Arithmetic
v Data manipulation
v Input/output
v Procedure branching

There are several phrases common to arithmetic and data manipulation statements,
such as:
v CORRESPONDING phrase
v GIVING phrase
v ROUNDED phrase
v SIZE ERROR phrases

CORRESPONDING phrase
The CORRESPONDING (CORR) phrase causes ADD, SUBTRACT, and MOVE
operations to be performed on elementary data items of the same name if the
alphanumeric group item or national group item to which they belong is specified.

A national group is processed as a group item when the CORRESPONDING

phrase is used.

Chapter 19. Procedure division structure 289

 Both identifiers that follow the keyword CORRESPONDING must name group
items. In this discussion, these identifiers are referred to as identifier-1 and
identifier-2. identifier-1 references the sending group item. identifier-2 references the
receiving group item.

Two subordinate data items, one from identifier-1 and one from identifier-2,
correspond if the following conditions are true:
v In an ADD or SUBTRACT statement, both of the data items are elementary
numeric data items. Other data items are ignored.
v In a MOVE statement, at least one of the data items is an elementary item, and
the move is permitted by the move rules.
v The two subordinate items have the same name and the same qualifiers up to
but not including identifier-1 and identifier-2.
v The subordinate items are not identified by the keyword FILLER.
v Neither identifier-1 nor identifier-2 is described as a level 66, 77, or 88 item, and
neither is described as an index data item. Neither identifier-1 nor identifier-2 can
be reference-modified.
v Neither identifier-1 nor identifier-2 is described with USAGE POINTER, USAGE
FUNCTION-POINTER, USAGE PROCEDURE-POINTER, or USAGE OBJECT
REFERENCE.
v The subordinate items do not include a REDEFINES, RENAMES, OCCURS,
USAGE INDEX, USAGE POINTER, USAGE PROCEDURE-POINTER, USAGE
FUNCTION-POINTER, or USAGE OBJECT REFERENCE clause in their
descriptions.
However, identifier-1 and identifier-2 themselves can contain or be subordinate to
items that contain a REDEFINES or OCCURS clause in their descriptions.
v The name of each subordinate data item that satisfies these conditions is unique
after application of implicit qualifiers.

identifier-1, identifier-2, or both can be subordinate to a FILLER item.

For example, consider two data hierarchies defined as follows:

05 ITEM-1 OCCURS 6.
10 ITEM-A PIC S9(3).
10 ITEM-B PIC +99.9.
10 ITEM-C PIC X(4).
10 ITEM-D REDEFINES ITEM-C PIC 9(4).
10 ITEM-E USAGE COMP-1.
10 ITEM-F USAGE INDEX.
05 ITEM-2.
10 ITEM-A PIC 99.
10 ITEM-B PIC +9V9.
10 ITEM-C PIC A(4).
10 ITEM-D PIC 9(4).
10 ITEM-E PIC 9(9) USAGE COMP.
10 ITEM-F USAGE INDEX.

If ADD CORR ITEM-2 TO ITEM-1(x) is specified, ITEM-A and ITEM-A(x), ITEM-B and
ITEM-B(x), and ITEM-E and ITEM-E(x) are considered to be corresponding and are
added together. ITEM-C and ITEM-C(x) are not included because they are not
numeric. ITEM-D and ITEM-D(x) are not included because ITEM-D(x) includes a
REDEFINES clause in its data description. ITEM-F and ITEM-F(x) are not included
because they are index data items. Note that ITEM-1 is valid as either identifier-1 or
identifier-2.

290 Enterprise COBOL for z/OS, V6.1 Language Reference

 If any of the individual operations in the ADD CORRESPONDING statement
produces a size error condition, imperative-statement-1 in the ON SIZE ERROR
phrase is not executed until all of the individual additions are completed.

GIVING phrase
The value of the identifier that follows the word GIVING is set equal to the
calculated result of the arithmetic operation. Because this identifier is not involved
in the computation, it can be a numeric-edited item.

ROUNDED phrase
After decimal point alignment, the number of places in the fraction of the result of
an arithmetic operation is compared with the number of places provided for the
fraction of the resultant identifier.

When the size of the fractional result exceeds the number of places provided for its
storage, truncation occurs unless ROUNDED is specified. When ROUNDED is
specified, the least significant digit of the resultant identifier is increased by 1
whenever the most significant digit of the excess is greater than or equal to 5.

When the resultant identifier is described by a PICTURE clause that contains

rightmost Ps and when the number of places in the calculated result exceeds the
number of integer positions specified, rounding or truncation occurs relative to the
rightmost integer position for which storage is allocated.

In a floating-point arithmetic operation, the ROUNDED phrase has no effect; the

result of a floating-point operation is always rounded. For more information on
floating-point arithmetic expressions, see Fixed-point contrasted with floating-point
arithmetic in the Enterprise COBOL Programming Guide.

When the ARITH(EXTEND) compiler option is in effect, the ROUNDED phrase is

not supported for arithmetic receivers with 31 digit positions to the right of the
decimal point. For example, neither X nor Y below is valid as a receiver with the
ROUNDED phrase:
01 X PIC V31.
01 Y PIC P(30)9(1).
. . .
COMPUTE X ROUNDED = A + B
COMPUTE Y ROUNDED = A - B

Otherwise, the ROUNDED phrase is fully supported for extended-precision

arithmetic statements.

SIZE ERROR phrases

A size error condition can occur in different ways.
v When the absolute value of the result of an arithmetic evaluation, after decimal
point alignment, exceeds the largest value that can be contained in the result
field.
v When division by zero occurs.
v In an exponential expression, as indicated in the following table:

Chapter 19. Procedure division structure 291

 Table 30. Exponentiation size error conditions
Action taken when a SIZE
Action taken when a SIZE ERROR clause is not
Size error ERROR clause is present present
Zero raised to zero power The SIZE ERROR imperative The value returned is 1, and
is executed. a message is issued.
Zero raised to a negative The SIZE ERROR imperative The program is terminated
number is executed. abnormally.
A negative number raised to The SIZE ERROR imperative The absolute value of the
a fractional power is executed. base is used, and a message
is issued.

The size error condition applies only to final results, not to any intermediate
results.

If the resultant identifier is defined with usage BINARY, COMPUTATIONAL,

COMPUTATIONAL-4, or COMPUTATIONAL-5, the largest value that the resultant
data item can contain is the value implied by the item's decimal PICTURE
character-string, regardless of the TRUNC compiler option in effect.

If the ROUNDED phrase is specified, rounding takes place before size error
checking.

When a size error occurs, the subsequent action of the program depends on
whether the ON SIZE ERROR phrase is specified.

If the ON SIZE ERROR phrase is not specified and a size error condition occurs,
truncation rules apply and the value of the affected resultant identifier is
computed.

If the ON SIZE ERROR phrase is specified and a size error condition occurs, the
value of the resultant identifier affected by the size error is not altered; that is, the
error results are not placed in the receiving identifier. After completion of the
execution of the arithmetic operation, the imperative statement in the ON SIZE
ERROR phrase is executed, control is transferred to the end of the arithmetic
statement, and the NOT ON SIZE ERROR phrase, if specified, is ignored.

For ADD CORRESPONDING and SUBTRACT CORRESPONDING statements, if

an individual arithmetic operation causes a size error condition, the ON SIZE
ERROR imperative statement is not executed until all the individual additions or
subtractions have been completed.

If the NOT ON SIZE ERROR phrase has been specified and, after execution of an
arithmetic operation, a size error condition does not exist, the NOT ON SIZE
ERROR phrase is executed.

When both the ON SIZE ERROR and NOT ON SIZE ERROR phrases are specified,
and the statement in the phrase that is executed does not contain any explicit
transfer of control, then if necessary an implicit transfer of control is made after
execution of the phrase to the end of the arithmetic statement.

292 Enterprise COBOL for z/OS, V6.1 Language Reference

Arithmetic statements
The arithmetic statements are used for computations. Individual operations are
specified by the ADD, SUBTRACT, MULTIPLY, and DIVIDE statements. These
individual operations can be combined symbolically in a formula that uses the
COMPUTE statement.

Arithmetic statement operands

The data descriptions of operands in an arithmetic statement need not be the same.
Throughout the calculation, the compiler performs any necessary data conversion
and decimal point alignment.

Size of operands

If the ARITH(COMPAT) compiler option is in effect, the maximum size of each

operand is 18 decimal digits. If the ARITH(EXTEND) compiler option is in effect,
the maximum size of each operand is 31 decimal digits.

The composite of operands is a hypothetical data item resulting from aligning the
operands at the decimal point and then superimposing them on one another.

If the ARITH(COMPAT) compiler option is in effect, the composite of operands can

be a maximum of 30 digits. If the ARITH(EXTEND) compiler option is in effect,
the composite of operands can be a maximum of 31 digits.

The following table shows how the composite of operands is determined for
arithmetic statements:
Table 31. How the composite of operands is determined
Statement Determination of the composite of operands
SUBTRACT Superimposing all operands in a given statement except those following the
ADD word GIVING
MULTIPLY Superimposing all receiving data items
DIVIDE Superimposing all receiving data items except the REMAINDER data item
COMPUTE Restriction does not apply

For example, assume that each item is defined as follows in the DATA DIVISION:
A PICTURE 9(7)V9(5).
B PICTURE 9(11)V99.
C PICTURE 9(12)V9(3).

If the following statement is executed, the composite of operands consists of 17

decimal digits:
ADD A B TO C

It has the following implicit description:

COMPOSITE-OF-OPERANDS PICTURE 9(12)V9(5).

In the ADD and SUBTRACT statements, if the composite of operands is 30 digits

or less with the ARITH(COMPAT) compiler option, or 31 digits or less with the
ARITH(EXTEND) compiler option, the compiler ensures that enough places are
carried so that no significant digits are lost during execution.

Chapter 19. Procedure division structure 293

 In all arithmetic statements, it is important to define data with enough digits and
decimal places to ensure the required accuracy in the final result. For more
information, see Appendix A. Intermediate results and arithmetic precision in the
Enterprise COBOL Programming Guide.

Overlapping operands

When operands in an arithmetic statement share part of their storage (that is, when
the operands overlap), the result of the execution of such a statement is
unpredictable.

Multiple results

When an arithmetic statement has multiple results, execution conceptually

proceeds as follows:
1. The statement performs all arithmetic operations to find the result to be placed
in the receiving items, and stores that result in a temporary location.
2. A sequence of statements transfers or combines the value of this temporary
result with each single receiving field. The statements are considered to be
written in the same left-to-right order in which the multiple results are listed.

For example, executing the following statement:

ADD A, B, C, TO C, D(C), E.

is equivalent to executing the following series of statements:

ADD A, B, C GIVING TEMP.
ADD TEMP TO C.
ADD TEMP TO D(C).
ADD TEMP TO E.

In the above example, TEMP is a compiler-supplied temporary result field. When

the addition operation for D(C) is performed, the subscript C contains the new
value of C.

Data manipulation statements

The following COBOL statements move and inspect data: ACCEPT, INITIALIZE,
| INSPECT, JSON GENERATE, MOVE, READ, RELEASE, RETURN, REWRITE, SET,
STRING, UNSTRING, WRITE, XML PARSE, and XML GENERATE.

Overlapping operands
When the sending and receiving fields of a data manipulation statement share a
part of their storage (that is, when the operands overlap), the result of the
execution of such a statement is unpredictable.

Input-output statements
COBOL input-output statements transfer data to and from files stored on external
media, and also control low-volume data that is obtained from or sent to an
input/output device.

In COBOL, the unit of file data made available to the program is a record. You
need only be concerned with such records. Provision is automatically made for
such operations as the movement of data into buffers, internal storage, validity
checking, error correction (where feasible), blocking and deblocking, and
volume-switching procedures.

294 Enterprise COBOL for z/OS, V6.1 Language Reference

 The description of the file in the ENVIRONMENT DIVISION and the DATA
DIVISION governs which input-output statements are allowed in the PROCEDURE
DIVISION. Permissible statements for sequential files are shown in Table 44 on
page 406, and permissible statements for indexed files and relative files are shown
in Table 45 on page 407. Permissible statements for line sequential files are shown
in Table 46 on page 407.

Common processing facilities

Several common processing facilities apply to more than one input-output
statement.

The common processing facilities provided are:

v “File status key”
v “Invalid key condition” on page 299
v “INTO and FROM phrases” on page 300
v “File position indicator” on page 301

Discussions in the following sections use the terms volume and reel. The term
volume refers to all non-unit-record input-output devices. The term reel applies only
to tape devices. Treatment of direct-access devices in the sequential access mode is
logically equivalent to the treatment of tape devices.

File status key

If the FILE STATUS clause is specified in the file-control entry, a value is placed in
the specified file status key (the two-character data item named in the FILE
STATUS clause) during execution of any request on that file; the value indicates
the status of that request.

The value is placed in the file status key before execution of any
EXCEPTION/ERROR declarative, INVALID KEY phrase, or AT END phrase
associated with the request.

There are two file status key data-names. One is described by data-name-1 in the
FILE STATUS clause of the file-control entry. This is a two-character data item with
the first character known as file status key 1 and the second character known as
file status key 2. The combinations of possible values and their meanings are
shown in Table 32 on page 296.

The other file status key is described by data-name-8 in the FILE STATUS clause of
the file-control entry. data-name-8 does not apply to QSAM files. For more
information about data-name-8, see “FILE STATUS clause” on page 147.

Chapter 19. Procedure division structure 295

 Table 32. File status key values and meanings
High- Low-order
order digit Meaning digit Meaning
0 Successful 0 No further information
completion
2 This file status value applies only to indexed files with alternate
keys that allow duplicates.

The input-output statement was successfully executed, but a

duplicate key was detected. For a READ statement, the key value
for the current key of reference was equal to the value of the same
key in the next record within the current key of reference. For a
REWRITE or WRITE statement, the record just written created a
duplicate key value for at least one alternate record key for which
duplicates are allowed.
4 A READ statement was successfully executed, but the number of
character positions that were read was less than the minimum size
or was greater than the maximum size specified by the record
description entries associated with the FD for the file.
| Note: If the VLR(COMPAT) option is in effect, you will get the
| status value of 00 when READ statements encounter a record length
| conflict. For details about the VLR option, see VLR in the Enterprise
| COBOL Programming Guide.
5 An OPEN statement was successfully executed, but the referenced
optional file was unavailable at the time the OPEN statement was
executed. The file had been created if the open mode was I-O or
EXTEND. This does not apply to VSAM sequential files.
7 For a CLOSE statement with the NO REWIND, REEL/UNIT, or
FOR REMOVAL phrase or for an OPEN statement with the NO
REWIND phrase, the referenced file was on a non-reel/unit
medium.
1 At-end condition 0 A sequential READ statement was attempted and no next logical
record existed in the file because the end of the file had been
reached. Or the first READ was attempted on an optional input file
that was unavailable.
4 A sequential READ statement was attempted for a relative file, and
the number of significant digits in the relative record number was
larger than the size of the relative key data item described for the
file.

296 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 32. File status key values and meanings (continued)
High- Low-order
order digit Meaning digit Meaning
2 Invalid key 1 A sequence error exists for a sequentially accessed indexed file. The
condition prime record key value was changed by the program between the
successful execution of a READ statement and the execution of the
next REWRITE statement for that file. Or the ascending
requirements for successive record key values were violated.
2 An attempt was made to write a record that would create a
duplicate key in a relative file. Or an attempt was made to write or
rewrite a record that would create a duplicate prime record key or a
duplicate alternate record key without the DUPLICATES phrase in
an indexed file.
3 An attempt was made to randomly access a record that does not
exist in the file. Or a START or random READ statement was
attempted on an optional input file that was unavailable.
4 An attempt was made to write beyond the externally defined
boundaries of a relative or indexed file. Or a sequential WRITE
statement was attempted for a relative file and the number of
significant digits in the relative record number was larger than the
size of the relative key data item described for the file.
3 Permanent error 0 No further information
condition
4 A permanent error exists because of a boundary violation; an
attempt was made to write beyond the externally defined
boundaries of a sequential file.
5 An OPEN statement with the INPUT, I-O, or EXTEND phrase was
attempted on a nonoptional file that was unavailable.
7 An OPEN statement was attempted on a file that would not
support the open mode specified in the OPEN statement. Possible
violations are:
v The EXTEND or OUTPUT phrase was specified but the file
would not support write operations.
v The I-O phrase was specified but the file would not support the
input and output operations permitted.
v The INPUT phrase was specified but the file would not support
read operations.
8 An OPEN statement was attempted on a file previously closed with
lock.
9 The OPEN statement was unsuccessful because a conflict was
detected between the fixed file attributes and the attributes specified
for that file in the program. These attributes include the
organization of the file (sequential, relative, or indexed), the prime
record key, the alternate record keys, the code set, the maximum
record size, the record type (fixed or variable), and the blocking
factor.

Chapter 19. Procedure division structure 297

Table 32. File status key values and meanings (continued)
High- Low-order
order digit Meaning digit Meaning
4 Logic error condition 1 An OPEN statement was attempted for a file in the open mode.
2 A CLOSE statement was attempted for a file not in the open mode.
3 For a mass storage file in the sequential access mode, the last
input-output statement executed for the associated file prior to the
execution of a REWRITE statement was not a successfully executed
READ statement.

For relative and indexed files in the sequential access mode, the last
input-output statement executed for the file prior to the execution
of a DELETE or REWRITE statement was not a successfully
executed READ statement.
4 A boundary violation exists because an attempt was made to
rewrite a record to a file and the record was not the same size as
the record being replaced. Or an attempt was made to write or
rewrite a record that was larger than the largest or smaller than the
smallest record allowed by the RECORD IS VARYING clause of the
associated file-name.
6 A sequential READ statement was attempted on a file open in the
input or I-O mode and no valid next record had been established
because:
v The preceding READ statement was unsuccessful but did not
cause an at-end condition.
v The preceding READ statement caused an at-end condition.
7 The execution of a READ statement was attempted on a file not
open in the input or I-O mode.
8 The execution of a WRITE statement was attempted on a file not
open in the I-O, output, or extend mode.
9 The execution of a DELETE or REWRITE statement was attempted
on a file not open in the I-O mode.

298 Enterprise COBOL for z/OS, V6.1 Language Reference

 Table 32. File status key values and meanings (continued)
High- Low-order
order digit Meaning digit Meaning
9 Implementor-defined 0 v For multithreading only: A CLOSE of a VSAM or QSAM file was
condition attempted on a thread that did not open the file.
v Without multithreading: For VSAM only: See the information
about VSAM return codes in Using VSAM status codes (VSAM files
only) in the Enterprise COBOL Programming Guide.
v QSAM files: No further information available. See the DFSMS
error message for more information.
1 For VSAM only: Password failure
2 Logic error
3 For all files, except QSAM: Resource unavailable
5 For all files except QSAM: Invalid or incomplete file information
6 For VSAM file: An OPEN statement with the OUTPUT phrase was
attempted, or an OPEN statement with the I-O or EXTEND phrase
was attempted for an optional file but no DD statement was
specified for the file.

For QSAM file: An OPEN statement with the OUTPUT phrase was
attempted, or an OPEN statement with the I-O or EXTEND phrase
was attempted for an optional file but no DD statement was
specified for the file and the CBLQDA(OFF) runtime option was
specified.
7 For VSAM only: OPEN statement execution successful: File integrity
verified
| Note: If the VSAMOPENFS(SUCC) option is in effect, you will get
| the status value of 00 when a VSAM OPEN statement is
| successfully verified. For details about the VSAMOPENFS option,
| see VSAMOPENFS in the Enterprise COBOL Programming Guide.
8 Open failed due to the invalid contents of an environment variable
specified in a SELECT ... ASSIGN clause or due to dynamic
allocation failure. For more information about the contents of
environment variables, see “ASSIGN clause” on page 134.

Invalid key condition

The invalid key condition can occur during execution of a START, READ, WRITE,
REWRITE, or DELETE statement. When an invalid key condition occurs, the
input-output statement that caused the condition is unsuccessful.

When the invalid key condition is recognized, actions are taken in the following
order:
1. If the FILE STATUS clause is specified in the file-control entry, a value is
placed into the file status key to indicate an invalid key condition, as shown in
Table 32 on page 296.
2. If the INVALID KEY phrase is specified in the statement that caused the
condition, control is transferred to the INVALID KEY imperative statement.
Any EXCEPTION/ERROR declarative procedure specified for this file is not
executed. Execution then continues according to the rules for each statement
specified in the imperative statement.

Chapter 19. Procedure division structure 299

 3. If the INVALID KEY phrase is not specified in the input-output statement for a
file and an applicable EXCEPTION/ERROR procedure exists, that procedure is
executed. The NOT INVALID KEY phrase, if specified, is ignored.

Both the INVALID KEY phrase and the EXCEPTION/ERROR procedure can be
omitted.

If the invalid key condition does not exist after execution of the input-output
operation, the INVALID KEY phrase is ignored, if specified, and the following
actions are taken:
v If an exception condition that is not an invalid key condition exists, control is
transferred according to the rules of the USE statement following the execution
of any USE AFTER EXCEPTION procedure.
v If no exception condition exists, control is transferred to the end of the
input-output statement or the imperative statement specified in the NOT
INVALID KEY phrase, if it is specified.

INTO and FROM phrases

The INTO and FROM phrases are valid for READ, RETURN, RELEASE, REWRITE,
and WRITE statements.

You must specify an identifier that is the name of an entry in the

WORKING-STORAGE SECTION or the LINKAGE SECTION, or of a record
description for another previously opened file.

Format: INTO and FROM phrases of input-output statements

►► READ file-name-1 ►◄
RETURN RECORD INTO identifier-1
RELEASE record-name-1
REWRITE FROM identifier-1
WRITE

v record-name-1 and identifier-1 must not refer to the same storage area.
v If record-name-1 or identifier-1 refers to a national group item, the item is
processed as an elementary data item of category national.
v The INTO phrase can be specified in a READ or RETURN statement.
The result of the execution of a READ or RETURN statement with the INTO
phrase is equivalent to the application of the following rules in the order
specified:
– The execution of the same READ or RETURN statement without the INTO
phrase.
– The current record is moved from the record area to the area specified by
identifier-1 according to the rules for the MOVE statement without the
CORRESPONDING phrase. The size of the current record is determined by
rules specified in the RECORD clause. If the file description entry contains a
RECORD IS VARYING clause, the implied move is a group move. The
implied MOVE statement does not occur if the execution of the READ or
RETURN statement was unsuccessful. Any subscripting or
reference-modification associated with identifier-1 is evaluated after the record

300 Enterprise COBOL for z/OS, V6.1 Language Reference

 has been read or returned and immediately before it is moved to the data
item. The record is available in both the record area and the data item
referenced by identifier-1.
v The FROM phrase can be specified in a RELEASE, REWRITE, or WRITE
statement.
The result of the execution of a RELEASE, REWRITE, or WRITE statement with
the FROM phrase is equivalent to the execution of the following statements in
the order specified:
1. MOVE identifier-1 TO record-name-1
2. The same RELEASE, REWRITE, or WRITE statement without the FROM
phrase
After the execution of the RELEASE, REWRITE or WRITE statement is complete,
the information in the area referenced by identifier-1 is available even though the
information in the area referenced by record-name-1 is unavailable, except as
specified by the SAME RECORD AREA clause.

File position indicator

The file position indicator is a conceptual entity used in this document to facilitate
exact specification of the next record to be accessed within a given file during
certain sequences of input-output operations.

The setting of the file position indicator is affected only by the OPEN, CLOSE,
READ and START statements. The concept of a file position indicator has no
meaning for a file opened in the output or extend mode.

Chapter 19. Procedure division structure 301

302 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 20. PROCEDURE DIVISION statements
Statements, sentences, and paragraphs in the PROCEDURE DIVISION are executed
sequentially except when a procedure branching statement such as EXIT, GO TO,
PERFORM, GOBACK, or STOP is used.

© Copyright IBM Corp. 1991, 2017 303

 ACCEPT statement
The ACCEPT statement transfers data or system date-related information into the
data area referenced by the specified identifier. There is no editing or error
checking of the incoming data.

Data transfer
Format 1 transfers data from an input source into the data item referenced by
identifier-1 (the receiving area). When the FROM phrase is omitted, the system
input device is assumed.

Format 1: data transfer

►► ACCEPT identifier-1 ►◄
FROM mnemonic-name-1
environment-name

Format 1 is useful for exceptional situations in a program when operator

intervention (to supply a given message, code, or exception indicator) is required.
The operator must of course be supplied with the appropriate messages with
which to reply.
identifier-1
The receiving area. Can be:
v An alphanumeric group item
v A national group item
v An elementary data item of usage DISPLAY, DISPLAY-1, or NATIONAL
| A national group item is processed as an elementary data item of category
| national.
mnemonic-name-1
Specifies the input device. mnemonic-name-1 must be associated in the
SPECIAL-NAMES paragraph with an environment-name. See
“SPECIAL-NAMES paragraph” on page 116.
v System input device
The length of a data transfer is the same as the length of the record on
the input device, with a maximum of 32,760 bytes.
The system input device is read until the receiving area is filled or EOF
is encountered. If the length of the receiving area is not an even multiple
of the system input device record length, the final record will be
truncated as required. If EOF is encountered after data has been moved
and before the receiving area has been filled, the receiving area is
padded with spaces of the appropriate representation for the receiving
area. If EOF is encountered before any data has been moved to the
receiving area, padding will not take place and the contents of the
receiving area are unchanged. Each input record is concatenated with the
previous input record.
If the input record is of a fixed-length format, the entire input record is
used. No editing is performed to remove trailing or leading blanks.

304 Enterprise COBOL for z/OS, V6.1 Language Reference

 If the input record is of the variable-length format, the actual record
length is used to determine the amount of data received. With
variable-format records, the Record Definition Word (RDW) is removed
from the beginning of the input record. Only the actual input data is
transferred to identifier-1.
If the data item referenced by identifier-1 is of usage national, data is
transferred without conversion and without checking for validity. The
input data is assumed to be in UTF-16 format.
v Console
1. A system-generated message code is automatically displayed,
followed by the literal AWAITING REPLY.
The maximum length of an input message is 114 characters.
2. Execution is suspended.
3. After the message code (the same code as in item 1) is entered from
the console and recognized by the system, ACCEPT statement
execution is resumed. The message is moved to the receiving area
and left-justified regardless of its PICTURE clause.
If identifier-1 references a data item of usage NATIONAL, the
message is converted from the native code page representation to
national character representation. The native code page is the one
that was specified by the CODEPAGE compiler option when the
source code was compiled.
The ACCEPT statement is terminated if any of the following
conditions occurs:
– No data is received from the console; for example, if the operator
hits the Enter key.
– The receiving data item is filled with data.
– Fewer than 114 characters of data are entered.
If 114 bytes of data are entered and the receiving area is still not
filled with data, more requests for data are issued to the console.
If more than 114 characters of data are entered, only the first 114
characters will be recognized by the system.
If the receiving area is longer than the incoming message, the
rightmost characters are padded with spaces of the appropriate
representation for the receiving area.
If the incoming message is longer than the receiving area, the
character positions beyond the length of the receiving area are
truncated.
For information about obtaining ACCEPT input from a z/OS UNIX file
or stdin, see Assigning input from a screen or file (ACCEPT) in the
Enterprise COBOL Programming Guide.
environment-name
Identifies the source of input data. An environment-name from the names
given in Table 5 on page 118 can be specified.

If the device is the same as that used for READ statements for a LINE
SEQUENTIAL file, results are unpredictable.

System date-related information transfer

System information contained in the specified conceptual data items DATE, DATE
YYYYMMDD, DAY, DAY YYYYDDD, DAY-OF-WEEK, or TIME, can be transferred

Chapter 20. PROCEDURE DIVISION statements 305

 into the data item referenced by identifier-2. The transfer must follow the rules for
the MOVE statement without the CORRESPONDING phrase.

For more information, see “MOVE statement” on page 393.

Format 2: system information transfer

►► ACCEPT identifier-2 FROM DATE ►◄

YYYYMMDD
DAY
YYYYDDD
DAY-OF-WEEK
TIME

identifier-2
The receiving area. Can be:
v An alphanumeric group item
v A national group item
v An elementary data item of one of the following categories:
– alphanumeric
– alphanumeric-edited
– numeric-edited (with usage DISPLAY or NATIONAL)
– national
– national-edited
– numeric
– internal floating-point
– external floating-point (with usage DISPLAY or NATIONAL)
| A national group item is processed as an elementary data item of category
| national.

Format 2 accesses the current date in two formats: the day of the week or the time
of day as carried by the system (which can be useful in identifying when a
particular run of an object program was executed). You can also use format 2 to
supply the date in headings and footings.

The current date and time can also be accessed with the intrinsic function
CURRENT-DATE, which also supports four-digit year values and provides
additional information (see “CURRENT-DATE” on page 522).

DATE, DATE YYYYMMDD, DAY, DAY YYYYDDD, DAY-OF-WEEK,

and TIME
The conceptual data items DATE, DATE YYYYMMDD, DAY, DAY YYYYDDD,
DAY-OF-WEEK, and TIME implicitly have USAGE DISPLAY. Because these are
conceptual data items, they cannot be described in the COBOL program.

The content of the conceptual data items is moved to the receiving area using the
rules of the MOVE statement. If the receiving area is of usage NATIONAL, the
data is converted to national character representation.

306 Enterprise COBOL for z/OS, V6.1 Language Reference

DATE
Has the implicit PICTURE 9(6).
The sequence of data elements (from left to right) is:
Two digits for the year
Two digits for the month
Two digits for the day

Thus 27 April 2003 is expressed as 030427.

DATE YYYYMMDD
Has the implicit PICTURE 9(8).
The sequence of data elements (from left to right) is:
Four digits for the year
Two digits for the month
Two digits for the day

Thus 27 April 2003 is expressed as 20030427.

DAY Has the implicit PICTURE 9(5).
The sequence of data elements (from left to right) is:
Two digits for the year
Three digits for the day

Thus 27 April 2003 is expressed as 03117.

DAY YYYYDDD
Has the implicit PICTURE 9(7).
The sequence of data elements (from left to right) is:
Four digits for the year
Three digits for the day

Thus 27 April 2003 is expressed as 2003117.

DAY-OF-WEEK
Has the implicit PICTURE 9(1).
The single data element represents the day of the week according to the
following values:
1 represents Monday 5 represents Friday
2 represents Tuesday 6 represents Saturday
3 represents Wednesday 7 represents Sunday
4 represents Thursday

Thus Wednesday is expressed as 3.

TIME Has the implicit PICTURE 9(8).
The sequence of data elements (from left to right) is:
Two digits for hour of day
Two digits for minute of hour
Two digits for second of minute
Two digits for hundredths of second

Thus 2:41 PM is expressed as 14410000.

Chapter 20. PROCEDURE DIVISION statements 307

ADD statement
The ADD statement sums two or more numeric operands and stores the result.

Format 1: ADD statement

►► ADD ▼ identifier-1 TO ▼ identifier-2 ►

literal-1 ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-ADD
ON

All identifiers or literals that precede the keyword TO are added together, and this
sum is added to and stored in identifier-2. This process is repeated for each
successive occurrence of identifier-2 in the left-to-right order in which identifier-2 is
specified.

308 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 2: ADD statement with GIVING phrase

►► ADD ▼ identifier-1 identifier-2 ►

literal-1 TO literal-2

► GIVING ▼ identifier-3 ►
ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-ADD
ON

The values of the operands that precede the word GIVING are added together, and
the sum is stored as the new value of each data item referenced by identifier-3.

Format 3: ADD statement with CORRESPONDING phrase

►► ADD CORRESPONDING identifier-1 TO identifier-2 ►

CORR ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-ADD
ON

Elementary data items within identifier-1 are added to and stored in the
corresponding elementary items within identifier-2.

For all formats:

identifier-1, identifier-2
In format 1, must name an elementary numeric item.
In format 2, must name an elementary numeric item except when
following the word GIVING. Each identifier that follows the word GIVING
must name an elementary numeric or numeric-edited item.

Chapter 20. PROCEDURE DIVISION statements 309

 In format 3, must name an alphanumeric group item or national group
item.
literal Must be a numeric literal.
Floating-point data items and literals can be used anywhere that a numeric
data item or literal can be specified.

When the ARITH(COMPAT) compiler option is in effect, the composite of operands

can contain a maximum of 30 digits. When the ARITH(EXTEND) compiler option
is in effect, the composite of operands can contain a maximum of 31 digits. For
more information, see “Arithmetic statement operands” on page 293 and the
details on arithmetic intermediate results in Appendix A. Intermediate results and
arithmetic precision in the Enterprise COBOL Programming Guide.

ROUNDED phrase

For formats 1, 2, and 3, see “ROUNDED phrase” on page 291.

SIZE ERROR phrases

For formats 1, 2, and 3, see “SIZE ERROR phrases” on page 291.

CORRESPONDING phrase (format 3)

See “CORRESPONDING phrase” on page 289.

END-ADD phrase

This explicit scope terminator serves to delimit the scope of the ADD statement.
END-ADD permits a conditional ADD statement to be nested in another
conditional statement. END-ADD can also be used with an imperative ADD
statement.

For more information, see “Delimited scope statements” on page 288.

| ALLOCATE statement
| The ALLOCATE statement obtains dynamic storage.

| Format

| ►► ALLOCATE arithmetic-expression-1 CHARACTERS ►

| data-name-1 INITIALIZED

| ► ►◄
| RETURNING data-name-2
|
||

| If data-name-1 is specified, the address of the data item is set to the address of the
| obtained storage, as if the "SET ADDRESS OF data-name-1 TO address" statement
| was used. If a RETURNING data item is also specified, the pointer data item will
| contain that address.

310 Enterprise COBOL for z/OS, V6.1 Language Reference

| If arithmetic-expression-1 CHARACTERS is specified, the RETURNING data-item-2
| will be set to the address of the obtained storage.
| data-name-1
| Must be a level-01 or level-77 item defined in the LINKAGE SECTION.
| If data-name-1 is specified, the RETURNING phrase can be omitted.
| Otherwise, the RETURNING phrase must be specified.
| Cannot be reference modified.
| Cannot be a group item that contains an unbounded table.
| data-name-2
| Must be defined as USAGE IS POINTER.
| Can be qualified or subscripted.
| arithmetic-expression-1
| Specifies a number of bytes of storage to be allocated:
| v If arithmetic-expression-1 does not evaluate to an integer, the result is
| rounded up to the next whole number.
| v If arithmetic-expression-1 evaluates to 0 or a negative value, the data item
| referenced by data-name-2 is set to the predefined address NULL.

| INITIALIZED phrase

| The INITIALIZED phrase initializes the allocated storage:

| v If the INITIALIZED phrase is not specified, the content of the allocated storage
| is undefined.
| v If both arithmetic-expression-1 and the INITIALIZED phrase are specified, all
| bytes of the allocated storage are initialized to binary zeros.
| v If both data-name-1 and the INITIALIZED phrase are specified, the allocated
| storage is initialized as if an INITIALIZE data-name-1 WITH FILLER ALL TO
| VALUE THEN TO DEFAULT statement were executed.

| If data-name-1 is specified, the amount of storage to be allocated is the number of

| bytes required to hold an item as described by data-name-1. If a data description
| entry that is subordinate to data-name-1 contains an OCCURS DEPENDING ON
| clause, the maximum length of the record is allocated.

| If the specified amount of storage is available for allocation:

| v If the RETURNING phrase is specified, the data item referenced by data-name-2
| is set to the address of that storage.
| v If data-name-1 is specified, the address of the 01 or 77 LINKAGE SECTION data
| item referenced by data-name-1 is set to the address of that storage, as if the "SET
| ADDRESS OF data-name-1 TO address-of-obtained-storage" statement was used.

| If the specified amount of storage is not available for allocation:

| v If the RETURNING phrase is specified, the data item referenced by data-name-2
| is set to the predefined address NULL.
| v If data-name-1 is specified, the address of the 01 or 77 LINKAGE SECTION data
| item referenced by data-name-1 is set to the predefined address NULL.

| The allocated storage persists until explicitly released with a FREE statement or the
| run unit is terminated, whichever occurs first.

Chapter 20. PROCEDURE DIVISION statements 311

| You can use ALLOCATE to dynamically increase the size of an UNBOUNDED
| table, see “Example: ALLOCATE and FREE storage for UNBOUNDED tables.”

| RELATED REFERENCES
| “FREE statement” on page 351
| “INITIALIZE statement” on page 358
| DATA (Enterprise COBOL Programming Guide)
| Storage and its addressability
| (Enterprise COBOL Programming Guide)

| Example: ALLOCATE and FREE storage for UNBOUNDED

| tables
| This example illustrates one way to manage an UNBOUNDED table that needs to
| be dynamically increased in size by using the ALLOCATE and FREE statements.
| ID DIVISION.
| PROGRAM-ID. ALLOC.
| ENVIRONMENT DIVISION.
| DATA DIVISION.
| WORKING-STORAGE SECTION.
| 77 X PIC 9(2) PACKED-DECIMAL.
| 77 NUM-ELEMENTS PIC 9(4) BINARY.
| 77 SIZE-NEEDED PIC 9(4) BINARY.
| 77 VPTR POINTER.
| 77 VPTR2 POINTER.
| 77 VPTR3 POINTER.
|
| LINKAGE SECTION.
|
| 01 VARGRP.
| 02 OBJ PIC 9(4) COMP.
| 02 TABGRP.
| 03 VARTAB OCCURS 1 TO UNBOUNDED DEPENDING ON OBJ.
| 04 T1 PIC 9(4).
| 04 T2 PIC X(8).
| 04 T3 PIC 9(4) COMP.
| 01 BUFFER PIC X(1000).
|
| PROCEDURE DIVISION.
|
| DISPLAY ’Starting testcase ALLOC’
|
| SET VPTR VPTR2 VPTR3 To NULL
|
| *************************************************************
| * Allocate a table with 20 elements
| *************************************************************
| COMPUTE NUM-ELEMENTS = 20
| PERFORM ALLOC-VARGRP
|
| *************************************************************
| * Set some ’test’ values to validate re-allocated table
| *************************************************************
| COMPUTE T1(12) = 9999
| MOVE ’HI MOM’ TO T2 (17)
| DISPLAY ’ ’
| DISPLAY ’VARTAB(12) = ’ VARTAB(12)
| DISPLAY ’VARTAB(17) = ’ VARTAB(17)
| DISPLAY ’ ’
|
| *************************************************************
| * Need a bigger table! Allocate a larger one and copy data
| *************************************************************

312 Enterprise COBOL for z/OS, V6.1 Language Reference

| COMPUTE NUM-ELEMENTS = 30
| PERFORM ALLOC-VARGRP
|
| *************************************************************
| * Ensure that new table has correct data from original
| *************************************************************
| DISPLAY ’VARTAB(12) = ’ VARTAB(12)
| DISPLAY ’VARTAB(17) = ’ VARTAB(17)
|
| GOBACK.
|
| *************************************************************
| * The first time allocate the original table. If the table
| * has already been allocated, assume that we are allocating
| * a larger one and want to copy the data over to it
| *************************************************************
| ALLOC-VARGRP.
|
| If VPTR = NULL Then *> If first time, allocate the table
| COMPUTE SIZE-NEEDED = LENGTH OF OBJ +
| LENGTH OF VARTAB * NUM-ELEMENTS
| ALLOCATE SIZE-NEEDED CHARACTERS INITIALIZED RETURNING VPTR
|
| SET ADDRESS OF VARGRP TO VPTR
| MOVE NUM-ELEMENTS TO OBJ
|
| Else *> If already have a table, doing re-size
| *********************************************************************
| * Re-size it!
| * First, allocate space for data save area and move data in
| *********************************************************************
|
| ALLOCATE SIZE-NEEDED CHARACTERS INITIALIZED RETURNING VPTR2
| SET ADDRESS OF BUFFER TO VPTR2
| MOVE VARGRP TO BUFFER(1:SIZE-NEEDED)
| DISPLAY ’BUFFER = ’ BUFFER(1:SIZE-NEEDED)
|
| *********************************************************************
| * Calculate new size from NUM-ElEMENTS
| *********************************************************************
| COMPUTE SIZE-NEEDED = LENGTH OF OBJ +
| LENGTH OF VARTAB * NUM-ELEMENTS
|
| ALLOCATE SIZE-NEEDED CHARACTERS INITIALIZED RETURNING VPTR3
|
| *************************************************************
| * Move data from data save area to new larger table
| *************************************************************
| SET ADDRESS OF VARGRP TO VPTR3
| MOVE NUM-ELEMENTS TO OBJ
| MOVE BUFFER(1:SIZE-NEEDED) TO VARGRP
| *************************************************************
| * Free the original table and temp copy
| *************************************************************
| FREE VPTR VPTR2
| SET VPTR TO VPTR2
| .

| RELATED REFERENCES
| “ALLOCATE statement” on page 310
| “FREE statement” on page 351
| “MOVE statement” on page 393
| Working with unbounded tables and groups
| (Enterprise COBOL Programming Guide)

Chapter 20. PROCEDURE DIVISION statements 313

|
ALTER statement
The ALTER statement changes the transfer point specified in a GO TO statement.

The ALTER statement encourages the use of unstructured programming practices;

the EVALUATE statement provides the same function as the ALTER statement but
helps to ensure that a program is well-structured.

Format

►► ALTER ▼ procedure-name-1 TO procedure-name-2 ►◄

PROCEED TO

The ALTER statement modifies the GO TO statement in the paragraph named by

procedure-name-1. Subsequent executions of the modified GO TO statement transfer
control to procedure-name-2.
procedure-name-1
Must name a PROCEDURE DIVISION paragraph that contains only one
sentence: a GO TO statement without the DEPENDING ON phrase.
procedure-name-2
Must name a PROCEDURE DIVISION section or paragraph.

Before the ALTER statement is executed, when control reaches the paragraph
specified in procedure-name-1, the GO TO statement transfers control to the
paragraph specified in the GO TO statement. After execution of the ALTER
statement however, the next time control reaches the paragraph specified in
procedure-name-1, the GO TO statement transfers control to the paragraph specified
in procedure-name-2.

The ALTER statement acts as a program switch, allowing, for example, one
sequence of execution during initialization and another sequence during the bulk
of file processing.

Altered GO TO statements in programs with the INITIAL attribute are returned to

their initial states each time the program is entered.

Do not use the ALTER statement in programs that have the RECURSIVE attribute,
in methods, or in programs compiled with the THREAD option.

Segmentation considerations
A GO TO statement that is coded in an independent segment must not be
referenced by an ALTER statement in a segment with a different priority-number.
All other uses of the ALTER statement are valid and are performed even if the GO
TO referenced by the ALTER statement is in a fixed segment.

314 Enterprise COBOL for z/OS, V6.1 Language Reference

Altered GO TO statements in independent segments are returned to their initial
state when control is transferred to the independent segment that contains the
ALTERED GO TO from another independent segment with a different
priority-number.

This transfer of control can take place because of:

v The effect of previous statements
v An explicit transfer of control with a PERFORM or GO TO statement
v A sort or merge statement with the INPUT or OUTPUT phrase specified

Chapter 20. PROCEDURE DIVISION statements 315

CALL statement
The CALL statement transfers control from one object program to another within
the run unit.

The program containing the CALL statement is the calling program; the program
identified in the CALL statement is the called subprogram. Called programs can
contain CALL statements; however, only programs defined with the RECURSIVE
clause can execute a CALL statement that directly or indirectly calls itself.

316 Enterprise COBOL for z/OS, V6.1 Language Reference

Format

►► CALL identifier-1 ►
literal-1
procedure-pointer-1
function-pointer-1

► ►

USING ▼ ▼ identifier-2
REFERENCE ADDRESS OF
BY file-name-1
OMITTED

CONTENT ▼ identifier-3
BY ADDRESS OF
LENGTH OF
literal-2
OMITTED

VALUE ▼ identifier-4
BY ADDRESS OF
LENGTH OF
literal-3

► ►◄
RETURNING identifier-5 exception-phrases END-CALL

exception-phrases:

EXCEPTION imperative-statement-1 not-exception-phrase

ON
OVERFLOW imperative-statement-3
ON

not-exception-phrase:

NOT EXCEPTION imperative-statement-2

ON

identifier-1, literal-1
literal-1 must be an alphanumeric literal. identifier-1 must be an
alphanumeric, alphabetic, or numeric data item described with USAGE
DISPLAY such that its value can be a program-name.
The rules of formation for program-names are dependent on the
PGMNAME compiler option. For details, see the discussion of

Chapter 20. PROCEDURE DIVISION statements 317

 program-names in “PROGRAM-ID paragraph” on page 104 and also the
description of PGMNAME in the Enterprise COBOL Programming Guide.
Usage note: Do not specify the name of a class or method in the CALL
statement.
procedure-pointer-1
Must be defined with USAGE IS PROCEDURE-POINTER and must be set
to a valid program entry point; otherwise, the results of the CALL
statement are undefined.
After a program has been canceled by COBOL, released by PL/I or C, or
deleted by assembler, any procedure-pointers that had been set to that
program's entry point are no longer valid.
function-pointer-1
Must be defined with USAGE IS FUNCTION-POINTER and must be set to
a valid function or program entry point; otherwise, the results of the CALL
statement are undefined.
After a program has been canceled by COBOL, released by PL/I or C, or
deleted by the assembler, any function-pointers that had been set to that
function or program's entry point are no longer valid.

When the called subprogram is to be entered at the beginning of the PROCEDURE

DIVISION, literal-1 or the contents of identifier-1 must specify the program-name of
the called subprogram.

When the called subprogram is entered through an ENTRY statement, literal-1 or

the contents of identifier-1 must be the same as the name specified in the called
subprogram's ENTRY statement.

For information about how the compiler resolves calls to program-names found in
multiple programs, see “Conventions for program-names” on page 90.

USING phrase

The USING phrase specifies arguments that are passed to the target program.

Include the USING phrase in the CALL statement only if there is a USING phrase
in the PROCEDURE DIVISION header or the ENTRY statement through which the
called program is run. The number of operands in each USING phrase must be
identical.

For more information about the USING phrase, see “The PROCEDURE DIVISION
header” on page 255.

The sequence of the operands in the USING phrase of the CALL statement and in
the corresponding USING phrase in the called subprogram's PROCEDURE
DIVISION header or ENTRY statement determines the correspondence between the
operands used by the calling and called programs. This correspondence is
positional.

The values of the parameters referenced in the USING phrase of the CALL
statement are made available to the called subprogram at the time the CALL
statement is executed. The description of the data items in the called program must
describe the same number of character positions as the description of the
corresponding data items in the calling program.

318 Enterprise COBOL for z/OS, V6.1 Language Reference

The BY CONTENT, BY REFERENCE, and BY VALUE phrases apply to parameters
that follow them until another BY CONTENT, BY REFERENCE, or BY VALUE
phrase is encountered. BY REFERENCE is assumed if you do not specify a BY
CONTENT, BY REFERENCE, or BY VALUE phrase prior to the first parameter.

BY REFERENCE phrase

If the BY REFERENCE phrase is either specified or implied for a parameter, the

corresponding data item in the calling program occupies the same storage area as
the data item in the called program.
identifier-2
Can be any data item of any level in the DATA DIVISION. identifier-2
cannot be a function-identifier.
If it is defined in the LINKAGE SECTION or FILE SECTION, you must
have already provided addressability for identifier-2 prior to invocation of
the CALL statement. You can do this by coding either one of the following:
SET ADDRESS OF identifier-2 TO pointer or PROCEDURE/ENTRY USING.
file-name-1
A file-name for a QSAM file. See Passing data in the Enterprise COBOL
Programming Guide for details on using file-name with the CALL statement.
ADDRESS OF identifier-2
identifier-2 must be a level-01 or level-77 item defined in the LINKAGE
SECTION.
OMITTED
Indicates that no argument is passed.

BY CONTENT phrase

If the BY CONTENT phrase is specified or implied for a parameter, the called

program cannot change the value of this parameter as referenced in the CALL
statement's USING phrase, though the called program can change the value of the
data item referenced by the corresponding data-name in the called program's
PROCEDURE DIVISION header. Changes to the parameter in the called program
do not affect the corresponding argument in the calling program.
identifier-3
Can be any data item of any level in the DATA DIVISION. identifier-3
cannot be a function identifier or an unbounded group.
If defined in the LINKAGE SECTION or FILE SECTION, you must have
already provided addressability for identifier-3 prior to invocation of the
CALL statement. You can do this by coding one of the following phrases:
v SET ADDRESS OF identifier-3 TO pointer
v PROCEDURE DIVISION USING
v ENTRY USING
literal-2
Can be:
v An alphanumeric literal
v A figurative constant (except ALL literal or NULL/NULLS)
v A DBCS literal
v A national literal

Chapter 20. PROCEDURE DIVISION statements 319

 LENGTH OF special register
For information about the LENGTH OF special register, see “LENGTH OF”
on page 19.
ADDRESS OF identifier-3
identifier-3 must be a data item of any level except 66 or 88 defined in the
LINKAGE SECTION, the WORKING-STORAGE SECTION, or the
LOCAL-STORAGE SECTION.
OMITTED
Indicates that no argument is passed.

For alphanumeric literals, the called subprogram should describe the parameter as
PIC X(n) USAGE DISPLAY, where n is the number of characters in the literal.

For DBCS literals, the called subprogram should describe the parameter as PIC
G(n) USAGE DISPLAY-1, or PIC N(n) with implicit or explicit USAGE DISPLAY-1,
where n is the length of the literal.

For national literals, the called subprogram should describe the parameter as PIC
N(n) with implicit or explicit USAGE NATIONAL, where n is the length of the
literal.

BY VALUE phrase

The BY VALUE phrase applies to all arguments that follow until overridden by
another BY REFERENCE or BY CONTENT phrase.

If the BY VALUE phrase is specified or implied for an argument, the value of the
argument is passed, not a reference to the sending data item. The called program
can modify the formal parameter that corresponds to the BY VALUE argument, but
any such changes do not affect the argument because the called program has
access to a temporary copy of the sending data item.

Although BY VALUE arguments are primarily intended for communication with

non-COBOL programs (such as C), they can also be used for COBOL-to-COBOL
invocations. In this case, BY VALUE must be specified or implied for both the
argument in the CALL USING phrase and the corresponding formal parameter in
the PROCEDURE DIVISION USING phrase.
identifier-4
Must be an elementary data item in the DATA DIVISION. It must be one
of the following items:
v Binary (USAGE BINARY, COMP, COMP-4, or COMP-5)
v Floating point (USAGE COMP-1 or COMP-2)
v Function-pointer (USAGE FUNCTION-POINTER)
v Pointer (USAGE POINTER)
v Procedure-pointer (USAGE PROCEDURE-POINTER)
v Object reference (USAGE OBJECT REFERENCE)
v One single-byte alphanumeric character (such as PIC X or PIC A)
v One national character (PIC N), described as an elementary data item of
category national.
The following items can also be passed BY VALUE:
v Reference-modified item of USAGE DISPLAY and length 1

320 Enterprise COBOL for z/OS, V6.1 Language Reference

 v Reference-modified item of USAGE NATIONAL and length 1
v SHIFT-IN and SHIFT-OUT special registers
v LINAGE-COUNTER special register when it is USAGE BINARY
ADDRESS OF identifier-4
identifier-4 must be a data item of any level except 66 or 88 defined in the
LINKAGE SECTION, the WORKING-STORAGE SECTION, or the
LOCAL-STORAGE SECTION.
LENGTH OF special register
A LENGTH OF special register passed BY VALUE is treated as a PIC 9(9)
binary. For information about the LENGTH OF special register, see
“LENGTH OF” on page 19.
literal-3
Must be of one of the following types:
v A numeric literal
v A figurative constant ZERO
v A one-character alphanumeric literal
v A one-character national literal
v A symbolic character
v A single-byte figurative constant
– SPACE
– QUOTE
– HIGH-VALUE
– LOW-VALUE
ZERO is treated as a numeric value; a fullword binary zero is passed.
If literal-3 is a fixed-point numeric literal, it must have a precision of nine
or fewer digits. In this case, a fullword binary representation of the literal
value is passed.
If literal-3 is a floating-point numeric literal, an 8-byte internal
floating-point (COMP-2) representation of the value is passed.
literal-3 must not be a DBCS literal.

RETURNING phrase
identifier-5
The RETURNING data item, which can be any data item defined in the
DATA DIVISION. The return value of the called program is implicitly
stored into identifier-5.

You can specify the RETURNING phrase for calls to functions written in COBOL,
C, or in other programming languages that use C linkage conventions. If you
specify the RETURNING phrase on a CALL to a COBOL subprogram:
v The called subprogram must specify the RETURNING phrase on its
PROCEDURE DIVISION header.
v identifier-5 and the corresponding PROCEDURE DIVISION RETURNING
identifier in the target program must have the same PICTURE, USAGE, SIGN,
SYNCHRONIZE, JUSTIFIED, and BLANK WHEN ZERO clauses (except that
PICTURE clause currency symbols can differ, and periods and commas can be
interchanged due to the DECIMAL POINT IS COMMA clause).

Chapter 20. PROCEDURE DIVISION statements 321

 When the target returns, its return value is assigned to identifier-5 using the rules
for the SET statement if identifier-6 is of usage INDEX, POINTER,
FUNCTION-POINTER, PROCEDURE-POINTER, or OBJECT REFERENCE.
When identifier-5 is of any other usage, the rules for the MOVE statement are
used.

The CALL ... RETURNING data item is an output-only parameter. On entry to the
called program, the initial state of the PROCEDURE DIVISION RETURNING data
item has an undefined and unpredictable value. You must initialize the
PROCEDURE DIVISION RETURNING data item in the called program before you
reference its value. The value that is passed back to the calling program is the final
value of the PROCEDURE DIVISION RETURNING data item when the called
program returns.

Note: If a COBOL program returns a doubleword binary item via a PROCEDURE

DIVISION RETURNING header to a calling COBOL program with a CALL ...
RETURNING statement, an issue occurs if only one of the programs is recompiled
with Enterprise COBOL V6. Both the called and calling programs must be
recompiled with Enterprise COBOL V6 together, so that the linkage convention for
the RETURNING item is consistent.

If an EXCEPTION or OVERFLOW occurs, identifier-5 is not changed. identifier-5

must not be reference-modified.

The RETURN-CODE special register is not set by execution of CALL statements

that include the RETURNING phrase.

ON EXCEPTION phrase

An exception condition occurs when the called subprogram cannot be made

available. At that time, one of the following two actions will occur:
1. If the ON EXCEPTION phrase is specified, control is transferred to
imperative-statement-1. Execution then continues according to the rules for each
statement specified in imperative-statement-1. If a procedure branching or
conditional statement that causes explicit transfer of control is executed, control
is transferred in accordance with the rules for that statement. Otherwise, upon
completion of the execution of imperative-statement-1, control is transferred to
the end of the CALL statement and the NOT ON EXCEPTION phrase, if
specified, is ignored.
2. If the ON EXCEPTION phrase is not specified in the CALL statement, the NOT
ON EXCEPTION phrase, if specified, is ignored.

NOT ON EXCEPTION phrase

If an exception condition does not occur (that is, the called subprogram can be
made available), control is transferred to the called program. After control is
returned from the called program, control is transferred to:
v imperative-statement-2, if the NOT ON EXCEPTION phrase is specified.
v The end of the CALL statement in any other case. (If the ON EXCEPTION
phrase is specified, it is ignored.)

If control is transferred to imperative-statement-2, execution continues according to

the rules for each statement specified in imperative-statement-2. If a procedure
branching or conditional statement that causes explicit transfer of control is
executed, control is transferred in accordance with the rules for that statement.

322 Enterprise COBOL for z/OS, V6.1 Language Reference

 Otherwise, upon completion of the execution of imperative-statement-2, control is
transferred to the end of the CALL statement.

ON OVERFLOW phrase

The ON OVERFLOW phrase has the same effect as the ON EXCEPTION phrase.

END-CALL phrase

This explicit scope terminator serves to delimit the scope of the CALL statement.
END-CALL permits a conditional CALL statement to be nested in another
conditional statement. END-CALL can also be used with an imperative CALL
statement.

For more information, see “Delimited scope statements” on page 288.

| RELATED REFERENCES
| PARMCHECK (Enterprise COBOL Programming Guide)

Chapter 20. PROCEDURE DIVISION statements 323

CANCEL statement
The CANCEL statement ensures that the referenced subprogram is entered in
initial state the next time that it is called.

Format

►► CANCEL ▼ identifier-1 ►◄
literal-1

identifier-1, literal-1
literal-1 must be an alphanumeric literal. identifier-1 must be an
alphanumeric, alphabetic, or zoned decimal data item such that its value
can be a program-name. The rules of formation for program-names are
dependent on the PGMNAME compiler option. For details, see the
discussion of program-names in “PROGRAM-ID paragraph” on page 104
and the description of PGMNAME in the Enterprise COBOL Programming
Guide.
literal-1 or the contents of identifier-1 must be the same as a literal or the
contents of an identifier specified in an associated CALL statement.

Do not specify the name of a class or a method in the CANCEL statement.

After a CANCEL statement for a called subprogram has been executed, that
subprogram no longer has a logical connection to the program. The contents of
data items in external data records described by the subprogram are not changed
when that subprogram is canceled. If a CALL statement is executed later by any
program in the run unit naming the same subprogram, that subprogram is entered
in its initial state.

When a CANCEL statement is executed, all programs contained within the

program referenced in the CANCEL statement are also canceled. The result is the
same as if a valid CANCEL were executed for each contained program in the
reverse order in which the programs appear in the separately compiled program.

A CANCEL statement closes all open files that are associated with an internal file
connector in the program named in an explicit CANCEL statement. USE
procedures associated with those files are not executed.

You can cancel a called subprogram in any of the following ways:

v By referencing it as the operand of a CANCEL statement
v By terminating the run unit of which the subprogram is a member
v By executing an EXIT PROGRAM statement or a GOBACK statement in the
called subprogram if that subprogram possesses the initial attribute

No action is taken when a CANCEL statement is executed if the specified program:

v Has not been dynamically called in this run unit by another COBOL program
v Has been called and subsequently canceled

324 Enterprise COBOL for z/OS, V6.1 Language Reference

In a multithreaded environment, a program cannot execute a CANCEL statement
naming a program that is active on any thread. The named program must be
completely inactive.

Called subprograms can contain CANCEL statements. However, a called

subprogram must not execute a CANCEL statement that directly or indirectly
cancels the calling program itself or that cancels any program higher than itself in
the calling hierarchy. In such a case, the run unit is terminated.

A program named in a CANCEL statement must be a program that has been called
and has executed an EXIT PROGRAM statement or a GOBACK statement.

A program can cancel a program that it did not call, provided that, in the calling
hierarchy, the program that executes the CANCEL statement is higher than or
equal to the program it is canceling. For example:
A calls B and B calls C (When A receives control, it can cancel C.)
A calls B and A calls C (When C receives control, it can cancel B.)

Chapter 20. PROCEDURE DIVISION statements 325

CLOSE statement
The CLOSE statement terminates the processing of volumes and files.

Format 1: CLOSE statement for sequential files

►► CLOSE ▼ file-name-1 ►◄
(1)
REEL
(1) REMOVAL
UNIT FOR
WITH NO REWIND
(1)
NO REWIND
WITH LOCK

Notes:
1 The REEL, UNIT, and NO REWIND phrases are not valid for VSAM files.

Format 2: CLOSE statement for indexed and relative files

►► CLOSE ▼ file-name-1 ►◄
LOCK
WITH

Format 3: CLOSE statement for line-sequential files

►► CLOSE ▼ file-name-1 ►◄
REEL
UNIT REMOVAL
FOR
WITH NO REWIND
NO REWIND
WITH LOCK

file-name-1
Designates the file upon which the CLOSE statement is to operate. If more

326 Enterprise COBOL for z/OS, V6.1 Language Reference

 than one file-name is specified, the files need not have the same
organization or access. file-name-1 must not be a sort or merge file.
REEL and UNIT
You can specify these phrases only for QSAM multivolume or single
volume files. The terms REEL and UNIT are interchangeable.
WITH NO REWIND and FOR REMOVAL
These phrases apply only to QSAM tape files. If they are specified for
storage devices to which they do not apply, the close operation is
successful and a status key value is set to indicate the file was on a
non-reel medium.

A CLOSE statement can be executed only for a file in an open mode. After
successful execution of a CLOSE statement (without the REEL/UNIT phrase if
using format 1):
v The record area associated with the file-name is no longer available.
Unsuccessful execution of a CLOSE statement leaves availability of the record
data undefined.
v An OPEN statement for the file must be executed before any other input/output
statement can be executed for the file and before data is moved to a record
description entry associated with the file.

If the FILE STATUS clause is specified in the file-control entry, the associated file
status key is updated when the CLOSE statement is executed.

If the file is in an open status and the execution of a CLOSE statement is

unsuccessful, the EXCEPTION/ERROR procedure (if specified) for this file is
executed.

Effect of CLOSE statement on file types

If the SELECT OPTIONAL clause is specified in the file-control entry for a file, and
the file is not available at run time, standard end-of-file processing is not
performed. For QSAM files, the file position indicator and current volume pointer
are unchanged.

Files are divided into the following types:

Non-reel/unit
A file whose input or output medium is such that rewinding, reels, and
units have no meaning. All VSAM files are of non-reel/unit file types.
QSAM files can be of non-reel/unit file types.
Sequential single volume
A sequential file that is contained entirely on one volume. More than one
file can be contained on this volume. All VSAM files are single volume.
QSAM files can be single volume.
Sequential multivolume
A sequential file that is contained on more than one volume. QSAM files
are the only files that can be multivolume. The concept of volume has no
meaning for VSAM files.

The permissible combinations of CLOSE statement phrases are shown in the

following tables:
v For sequential files: Sequential files and CLOSE statement phrases
v For indexed and relative files: Table 34 on page 328

Chapter 20. PROCEDURE DIVISION statements 327

 v For line-sequential files: Table 35

The meaning of each key letter is shown in Table 36.

Table 33. Sequential files and CLOSE statement phrases
Sequential Sequential
CLOSE statement phrases Non-reel/ unit single-volume multivolume
CLOSE C C, G A, C, G
CLOSE REEL/UNIT F F, G F, G
CLOSE REEL/UNIT WITH NO F B, F B, F
REWIND
CLOSE REEL/UNIT FOR D D D
REMOVAL
CLOSE WITH NO REWIND C, H B, C A, B, C
CLOSE WITH LOCK C, E C, E, G A, C, E, G

Table 34. Indexed and relative file types and CLOSE statement phrases
CLOSE statement phrases Action
CLOSE C
CLOSE WITH LOCK C,E

Table 35. Line-sequential file types and CLOSE statement phrases

CLOSE statement phrases Action
CLOSE C
CLOSE WITH LOCK C,E

Table 36. Meanings of key letters for sequential file types

Key Actions taken
A Previous volumes unaffected

Input and input-output files: Standard volume-switch processing is performed

for all previous volumes (except those controlled by a previous CLOSE
REEL/UNIT statement). Any subsequent volumes are not processed.

Output files: Standard volume-switch processing is performed for all previous

volumes (except those controlled by a previous CLOSE REEL/UNIT statement).
B No rewinding of current reel: The current volume is left in its current position.
C Close file

Standard system closing procedures are performed.

D Volume removal: Treated as a comment.
E File lock: The compiler ensures that this file cannot be opened again during this
execution of the object program. If the file is a tape unit, it will be rewound and
unloaded.

328 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 36. Meanings of key letters for sequential file types (continued)
Key Actions taken
F Close volume

Input and input-output files: If the current reel/unit is the last or only reel/unit
for the file or if the reel is on a non-reel/unit medium, no volume switching is
performed. If another reel/unit exists for the file, the following operations are
performed: a volume switch, and the first record on the new volume is made
available for reading. If no data records exist for the current volume, another
volume switch occurs.

Output (reel/unit media) files: The following operations are performed: a

volume switch. The next executed WRITE statement places the next logical
record on the next direct access volume available. A close statement with the
REEL phrase does not close the output file; only an end-of-volume condition
occurs.

Output (non-reel/unit media) files: Execution of the CLOSE statement is

considered successful. The file remains in the open mode and no action takes
place except that the value of the I-O status associated with the file is updated.
G Rewind: The current volume is positioned at its physical beginning.
H Optional phrases ignored: The CLOSE statement is executed as if none of the
optional phrases were present.

Chapter 20. PROCEDURE DIVISION statements 329

COMPUTE statement
The COMPUTE statement assigns the value of an arithmetic expression to one or
more data items.

With the COMPUTE statement, arithmetic operations can be combined without the
restrictions on receiving data items imposed by the rules for the ADD, SUBTRACT,
MULTIPLY, and DIVIDE statements.

When arithmetic operations are combined, the COMPUTE statement can be more
efficient than the separate arithmetic statements written in a series.

Format

►► COMPUTE ▼ identifier-1 = ►
ROUNDED EQUAL

► arithmetic-expression ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-COMPUTE
ON

identifier-1
Must name an elementary numeric item or an elementary numeric-edited
item.
Can name an elementary floating-point data item.
arithmetic-expression
Can be any arithmetic expression, as defined in “Arithmetic expressions”
on page 261.
When the COMPUTE statement is executed, the value of arithmetic
expression is calculated and stored as the new value of each data item
referenced by identifier-1.
An arithmetic expression consisting of a single identifier, numeric function,
or literal allows the user to set the value of the data items that are
referenced by identifier-1 equal to the value of that identifier, function, or
literal.

ROUNDED phrase

For a discussion of the ROUNDED phrase, see “ROUNDED phrase” on page 291.

330 Enterprise COBOL for z/OS, V6.1 Language Reference

SIZE ERROR phrases

For a discussion of the SIZE ERROR phrases, see “SIZE ERROR phrases” on page
291.

END-COMPUTE phrase

This explicit scope terminator serves to delimit the scope of the COMPUTE
statement. END-COMPUTE permits a conditional COMPUTE statement to be
nested in another conditional statement. END-COMPUTE can also be used with an
imperative COMPUTE statement.

For more information, see “Delimited scope statements” on page 288.

Chapter 20. PROCEDURE DIVISION statements 331

CONTINUE statement
The CONTINUE statement is a no operation statement. CONTINUE indicates that
no executable instruction is present.

Format

►► CONTINUE ►◄

332 Enterprise COBOL for z/OS, V6.1 Language Reference

DELETE statement
The DELETE statement removes a record from an indexed or relative file. For
indexed files, the key can then be reused for record addition. For relative files, the
space is then available for a new record with the same RELATIVE KEY value.

When the DELETE statement is executed, the associated file must be open in I-O
mode.

Format

►► DELETE file-name-1 ►
RECORD

► ►
INVALID imperative-statement-1
KEY

► ►◄
NOT INVALID imperative-statement-2 END-DELETE
KEY

file-name-1
Must be defined in an FD entry in the DATA DIVISION and must be the
name of an indexed or relative file.

After successful execution of a DELETE statement, the record is removed from the
file and can no longer be accessed.

Execution of the DELETE statement does not affect the contents of the record area
associated with file-name-1 or the content of the data item referenced by the
data-name specified in the DEPENDING ON phrase of the RECORD clause
associated with file-name-1.

If the FILE STATUS clause is specified in the file-control entry, the associated file
status key is updated when the DELETE statement is executed.

The file position indicator is not affected by execution of the DELETE statement.

Sequential access mode

For a file in sequential access mode, the previous input/output statement must be
a successfully executed READ statement. When the DELETE statement is executed,
the system removes the record that was retrieved by that READ statement.

For a file in sequential access mode, the INVALID KEY and NOT INVALID KEY
phrases must not be specified. An EXCEPTION/ERROR procedure can be
specified.

Chapter 20. PROCEDURE DIVISION statements 333

 Random or dynamic access mode

In random or dynamic access mode, DELETE statement execution results depend

on the file organization: indexed or relative.

When the DELETE statement is executed, the system removes the record identified
by the contents of the prime RECORD KEY data item for indexed files, or the
RELATIVE KEY data item for relative files. If the file does not contain such a
record, an INVALID KEY condition exists. (See “Invalid key condition” on page
299.)

Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure

can be omitted.

Transfer of control after the successful execution of a DELETE statement, with the
NOT INVALID KEY phrase specified, is to the imperative statement associated
with the phrase.

END-DELETE phrase

This explicit scope terminator serves to delimit the scope of the DELETE statement.
END-DELETE permits a conditional DELETE statement to be nested in another
conditional statement. END-DELETE can also be used with an imperative DELETE
statement.

For more information, see “Delimited scope statements” on page 288.

334 Enterprise COBOL for z/OS, V6.1 Language Reference

DISPLAY statement
The DISPLAY statement transfers the contents of each operand to the output
device. The contents are displayed on the output device in the order, left to right,
in which the operands are listed.

Format

►► DISPLAY ▼ identifier-1 ►
literal-1 UPON mnemonic-name-1
environment-name-1

► ►◄
NO ADVANCING
WITH

identifier-1
Identifier-1 references the data that is to be displayed. Identifier-1 can
reference any data item except an item of usage PROCEDURE-POINTER,
FUNCTION-POINTER, OBJECT REFERENCE, or INDEX. Identifier-1
cannot be an index-name.
If identifier-1 is a binary, internal decimal, or internal floating-point data
item, identifier-1 is converted automatically to external format as follows:
v Binary and internal decimal items are converted to zoned decimal.
Negative signed values cause a low-order sign overpunch.
v Internal floating-point numbers are converted to external floating-point
numbers for display such that:
– A COMP-1 item will display as if it had an external floating-point
PICTURE clause of -.9(8)E-99.
– A COMP-2 item will display as if it had an external floating-point
PICTURE clause of -.9(17)E-99.
Data items defined with USAGE POINTER are converted to a zoned
decimal number that has an implicit PICTURE clause of PIC 9(10).
If the output is directed to CONSOLE, data items described with usage
NATIONAL are converted from national character representation to
EBCDIC. The conversion uses the EBCDIC code page that was specified in
the CODEPAGE compiler option when the source code was compiled.
National characters without EBCDIC counterparts are converted to default
substitution characters; no exception condition is indicated or raised.
If the output is not directed to CONSOLE, data items described with usage
NATIONAL are written without conversion and without data validation.
No other categories of data require conversion.

Chapter 20. PROCEDURE DIVISION statements 335

 DBCS data items, explicitly or implicitly defined as USAGE DISPLAY-1, are
transferred to the sending field of the output device. For proper results, the
output device must have the capability to recognize DBCS shift-out and
shift-in control characters.
Both DBCS and non-DBCS operands can be specified in a single DISPLAY
statement.
literal-1
Can be any literal or any figurative constant as specified in “Figurative
constants” on page 13. When a figurative constant is specified, only a
single occurrence of that figurative constant is displayed.
UPON
environment-name-1 or the environment name associated with
mnemonic-name-1 must be associated with an output device. See
“SPECIAL-NAMES paragraph” on page 116.
A default logical record size is assumed for each device, as follows:
The system logical output device
120 characters
The system punch device
80 characters
The console
100 characters
A maximum logical record size is allowed for each device, as follows:
The system logical output device
255 characters
The system punch device
255 characters
The console
100 characters
On the system punch device, the last eight characters are used for
PROGRAM-ID name.
When the UPON phrase is omitted, the system's logical output device is
assumed. The list of valid environment-names in a DISPLAY statement is
shown in Table 5 on page 118.
For details on routing DISPLAY output to stdout, see Displaying values on a
screen or in a file (DISPLAY) in the Enterprise COBOL Programming Guide.
WITH NO ADVANCING
When specified, the positioning of the output device will not be changed
in any way following the display of the last operand.
If the WITH NO ADVANCING phrase is not specified, after the last
operand has been transferred to the output device, the positioning of the
output device will be reset to the leftmost position of the next line of the
device.
Enterprise COBOL does not support output devices that are capable of
positioning to a specific character position. See Displaying values on a screen
or in a file (DISPLAY) in the Enterprise COBOL Programming Guide for more
information about the DISPLAY statement.

336 Enterprise COBOL for z/OS, V6.1 Language Reference

The DISPLAY statement transfers the data in the sending field to the output
device. The size of the sending field is the total byte count of all operands listed. If
the output device is capable of receiving data of the same size as the data item
being transferred, then the data item is transferred. If the output device is not
capable of receiving data of the same size as the data item being transferred, then
one of the following applies:
v If the total count is less than the device maximum, the remaining rightmost
positions are padded with spaces.
v If the total count exceeds the maximum, as many records are written as are
needed to display all operands. Any operand being printed or displayed when
the end of a record is reached is continued in the next record.

If a DBCS operand must be split across multiple records, it will be split only on a
double-byte boundary.

Shift code insertion is required for splitting DBCS items. That is, when a DBCS
operand is split across multiple records, the shift-in character is inserted at the end
of the current record, and the shift-out character is inserted at the beginning of the
next record. A space is padded after the shift-in character, if necessary. These
inserted shift codes and spaces are included in the total byte count of the sending
data items.

After the last operand has been transferred to the output device, the device is reset
to the leftmost position of the next line of the device.

If a DBCS data item or literal is specified in a DISPLAY statement, the size of the
sending field is the total byte count of all operands listed, with each DBCS
character counted as two bytes, plus the necessary shift codes and spaces for
DBCS.

Chapter 20. PROCEDURE DIVISION statements 337

DIVIDE statement
The DIVIDE statement divides one numeric data item into or by others and sets
the values of data items equal to the quotient and remainder.

Format 1: DIVIDE statement

►► DIVIDE identifier-1 INTO ▼ identifier-2 ►

literal-1 ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-DIVIDE
ON

In format 1, the value of identifier-1 or literal-1 is divided into the value of

identifier-2, and the quotient is then stored in identifier-2. For each successive
occurrence of identifier-2, the division takes place in the left-to-right order in which
identifier-2 is specified.

338 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 2: DIVIDE statement with INTO and GIVING phrases

►► DIVIDE identifier-1 INTO identifier-2 ►

literal-1 literal-2

► GIVING ▼ identifier-3 ►
ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-DIVIDE
ON

In format 2, the value of identifier-1 or literal-1 is divided into the value of

identifier-2 or literal-2. The value of the quotient is stored in each data item
referenced by identifier-3.

Format 3: DIVIDE statement with BY and GIVING phrases

►► DIVIDE identifier-1 BY identifier-2 ►

literal-1 literal-2

► GIVING ▼ identifier-3 ►
ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-DIVIDE
ON

Chapter 20. PROCEDURE DIVISION statements 339

 In format 3, the value of identifier-1 or literal-1 is divided by the value of identifier-2
or literal-2. The value of the quotient is stored in each data item referenced by
identifier-3.

Format 4: DIVIDE statement with INTO and REMAINDER phrases

►► DIVIDE identifier-1 INTO identifier-2 ►

literal-1 literal-2

► GIVING identifier-3 REMAINDER identifier-4 ►

ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-DIVIDE
ON

In format 4, the value of identifier-1 or literal-1 is divided into identifier-2 or literal-2.

The value of the quotient is stored in identifier-3, and the value of the remainder is
stored in identifier-4.

Format 5: DIVIDE statement with BY and REMAINDER phrases

►► DIVIDE identifier-1 BY identifier-2 ►

literal-1 literal-2

► GIVING identifier-3 REMAINDER identifier-4 ►

ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-DIVIDE
ON

In format 5, the value of identifier-1 or literal-1 is divided by identifier-2 or literal-2.

The value of the quotient is stored in identifier-3, and the value of the remainder is
stored in identifier-4.

For all formats:

identifier-1, identifier-2
Must name an elementary numeric data item.

340 Enterprise COBOL for z/OS, V6.1 Language Reference

identifier-3, identifier-4
Must name an elementary numeric or numeric-edited item.
literal-1, literal-2
Must be a numeric literal.

In formats 1, 2, and 3, floating-point data items and literals can be used anywhere
that a numeric data item or literal can be specified.

In formats 4 and 5, floating-point data items or literals cannot be used.

ROUNDED phrase

For formats 1, 2, and 3, see “ROUNDED phrase” on page 291.

For formats 4 and 5, the quotient used to calculate the remainder is in an

intermediate field. The value of the intermediate field is truncated rather than
rounded.

REMAINDER phrase

The result of subtracting the product of the quotient and the divisor from the
dividend is stored in identifier-4. If identifier-3, the quotient, is a numeric-edited
item, the quotient used to calculate the remainder is an intermediate field that
contains the unedited quotient.

The REMAINDER phrase is invalid if the receiver or any of the operands is a

floating-point item.

Any subscripts for identifier-4 in the REMAINDER phrase are evaluated after the
result of the divide operation is stored in identifier-3 of the GIVING phrase.

SIZE ERROR phrases

For formats 1, 2, and 3, see “SIZE ERROR phrases” on page 291.

For formats 4 and 5, if a size error occurs in the quotient, no remainder calculation
is meaningful. Therefore, the contents of the quotient field (identifier-3) and the
remainder field (identifier-4) are unchanged.

If size error occurs in the remainder, the contents of the remainder field
(identifier-4) are unchanged.

In either of these cases, you must analyze the results to determine which situation
has actually occurred.

For information about the NOT ON SIZE ERROR phrase, see “SIZE ERROR
phrases” on page 291.

END-DIVIDE phrase
This explicit scope terminator serves to delimit the scope of the DIVIDE statement.
END-DIVIDE turns a conditional DIVIDE statement into an imperative statement
that can be nested in another conditional statement. END-DIVIDE can also be used
with an imperative DIVIDE statement.

Chapter 20. PROCEDURE DIVISION statements 341

 For more information, see “Delimited scope statements” on page 288.

342 Enterprise COBOL for z/OS, V6.1 Language Reference

ENTRY statement
The ENTRY statement establishes an alternate entry point into a COBOL called
subprogram.

The ENTRY statement cannot be used in:

v Programs that specify a return value using the PROCEDURE DIVISION
RETURNING phrase. For details, see the discussion of the RETURNING phrase
under “The PROCEDURE DIVISION header” on page 255.
v Nested program. See “Nested programs” on page 89 for a description of nested
programs.

When a CALL statement that specifies the alternate entry point is executed in a
calling program, control is transferred to the next executable statement following
the ENTRY statement.

Format

►► ENTRY literal-1 ►

► . ►◄

USING ▼ ▼ identifier-1
REFERENCE
BY
VALUE
BY

literal-1
Must be an alphanumeric literal that conform to the rules for the formation
of a program-name in an outermost program (see “PROGRAM-ID
paragraph” on page 104).
Must not match the program-ID or any other ENTRY literal in this
program.
Must not be a figurative constant.

Execution of the called program begins at the first executable statement following
the ENTRY statement whose literal corresponds to the literal or identifier specified
in the CALL statement.

The entry point name on the ENTRY statement can be affected by the PGMNAME
compiler option. For details, see PGMNAME in the Enterprise COBOL Programming
Guide.

USING phrase

For a discussion of the USING phrase, see “The PROCEDURE DIVISION header”
on page 255.

Chapter 20. PROCEDURE DIVISION statements 343

EVALUATE statement
The EVALUATE statement provides a shorthand notation for a series of nested IF
statements. The EVALUATE statement can evaluate multiple conditions. The
subsequent action depends on the results of these evaluations.

Format

►► EVALUATE identifier-1 ►
literal-1
expression-1
TRUE ▼ ALSO identifier-2
FALSE literal-2
expression-2
TRUE
FALSE

► ▼ ▼ WHEN phrase 1 imperative-statement-1 ►

▼ ALSO phrase 2

► ►◄
WHEN OTHER imperative-statement-2 END-EVALUATE

phrase 1:

ANY
condition-1
TRUE
FALSE
identifier-3
NOT literal-3 THROUGH identifier-4
arithmetic-expression-1 THRU literal-4
arithmetic-expression-2

phrase 2:

ANY
condition-2
TRUE
FALSE
identifier-5
NOT literal-5 THROUGH identifier-6
arithmetic-expression-3 THRU literal-6
arithmetic-expression-4

344 Enterprise COBOL for z/OS, V6.1 Language Reference

 Operands before the WHEN phrase
Are interpreted in one of two ways, depending on how they are specified:
v Individually, they are called selection subjects.
v Collectively, they are called a set of selection subjects.
Operands in the WHEN phrase
Are interpreted in one of two ways, depending on how they are specified:
v Individually, they are called selection objects
v Collectively, they are called a set of selection objects.
ALSO
Separates selection subjects within a set of selection subjects; separates
selection objects within a set of selection objects.
THROUGH and THRU
Are equivalent.

Two operands connected by a THRU phrase must be of the same class. The two
operands thus connected constitute a single selection object.

The number of selection objects within each set of selection objects must be equal
to the number of selection subjects.

Each selection object within a set of selection objects must correspond to the
selection subject having the same ordinal position within the set of selection
subjects, according to the following rules:
v Identifiers, literals, or arithmetic expressions appearing within a selection object
must be valid operands for comparison to the corresponding operand in the set
of selection subjects.
v condition-1, condition-2, or the word TRUE or FALSE appearing as a selection
object must correspond to a conditional expression or the word TRUE or FALSE
in the set of selection subjects.
v The word ANY can correspond to a selection subject of any type.

END-EVALUATE phrase

This explicit scope terminator serves to delimit the scope of the EVALUATE
statement. END-EVALUATE permits a conditional EVALUATE statement to be
nested in another conditional statement.

For more information, see “Delimited scope statements” on page 288.

Determining values
The execution of the EVALUATE statement operates as if each selection subject and
selection object were evaluated and assigned a numeric, alphanumeric, DBCS, or
national character value; a range of numeric, alphanumeric, DBCS, or national
character values; or a truth value.

These values are determined as follows:

v Any selection subject specified by identifier-1, identifier-2, ... and any selection
object specified by identifier-3 or identifier-5 without the NOT or THRU phrase
are assigned the value and class of the data item that they reference.
v Any selection subject specified by literal-1, literal-2, ... and any selection object
specified by literal-3 or literal-5 without the NOT or THRU phrase are assigned

Chapter 20. PROCEDURE DIVISION statements 345

 the value and class of the specified literal. If literal-3 or literal-5 is the figurative
constant ZERO, QUOTE, or SPACE, the figurative constant is assigned the class
of the corresponding selection subject.
v Any selection subject in which expression-1, expression-2, ... is specified as an
arithmetic expression, and any selection object without the NOT or THRU phrase
in which arithmetic-expression-1 or arithmetic-expression-3 is specified, are assigned
numeric values according to the rules for evaluating an arithmetic expression.
(See “Arithmetic expressions” on page 261.)
v Any selection subject in which expression-1, expression-2, ... is specified as a
conditional expression, and any selection object in which condition-1 or condition-2
is specified, are assigned a truth value according to the rules for evaluating
conditional expressions. (See “Conditional expressions” on page 264.)
v Any selection subject or any selection object specified by the words TRUE or
FALSE is assigned a truth value. The truth value "true" is assigned to those
items specified with the word TRUE, and the truth value "false" is assigned to
those items specified with the word FALSE.
v Any selection object specified by the word ANY is not further evaluated.
v If the THRU phrase is specified for a selection object without the NOT phrase,
the range of values includes all values that, when compared to the selection
subject, are greater than or equal to the first operand and less than or equal to
the second operand according to the rules for comparison. If the first operand is
greater than the second operand, there are no values in the range.
v If the NOT phrase is specified for a selection object, the values assigned to that
item are all values not equal to the value, or range of values, that would have
been assigned to the item had the NOT phrase been omitted.

Comparing selection subjects and objects

The execution of the EVALUATE statement then proceeds as if the values assigned
to the selection subjects and selection objects were compared to determine whether
any WHEN phrase satisfies the set of selection subjects.

This comparison proceeds as follows:

1. Each selection object within the set of selection objects for the first WHEN
phrase is compared to the selection subject having the same ordinal position
within the set of selection subjects. One of the following conditions must be
satisfied if the comparison is to be satisfied:
a. If the items being compared are assigned numeric, alphanumeric, DBCS, or
national character values, or a range of numeric, alphanumeric, DBCS, or
national character values, the comparison is satisfied if the value, or one
value in the range of values, assigned to the selection object is equal to the
value assigned to the selection subject according to the rules for
comparison.
b. If the items being compared are assigned truth values, the comparison is
satisfied if the items are assigned identical truth values.
c. If the selection object being compared is specified by the word ANY, the
comparison is always satisfied, regardless of the value of the selection
subject.
2. If the above comparison is satisfied for every selection object within the set of
selection objects being compared, the WHEN phrase containing that set of
selection objects is selected as the one satisfying the set of selection subjects.

346 Enterprise COBOL for z/OS, V6.1 Language Reference

 3. If the above comparison is not satisfied for every selection object within the set
of selection objects being compared, that set of selection objects does not satisfy
the set of selection subjects.
4. This procedure is repeated for subsequent sets of selection objects in the order
of their appearance in the source text, until either a WHEN phrase satisfying
the set of selection subjects is selected or until all sets of selection objects are
exhausted.

Executing the EVALUATE statement

After the comparison operation is completed, execution of the EVALUATE
statement proceeds.
v If a WHEN phrase is selected, execution continues with the first
imperative-statement-1 following the selected WHEN phrase. Note that multiple
WHEN statements are allowed for a single imperative-statement-1.
v If no WHEN phrase is selected and a WHEN OTHER phrase is specified,
execution continues with imperative-statement-2.
v If no WHEN phrase is selected and no WHEN OTHER phrase is specified,
execution continues with the next executable statement following the scope
delimiter.
v The scope of execution of the EVALUATE statement is terminated when
execution reaches the end of the scope of the selected WHEN phrase or WHEN
OTHER phrase, or when no WHEN phrase is selected and no WHEN OTHER
phrase is specified.

Chapter 20. PROCEDURE DIVISION statements 347

EXIT statement
The EXIT statement provides a common end point for a series of procedures. It
also provides a way to exit from a section, a paragraph, or an inline PERFORM
statement.

Note: Enterprise COBOL does not yet support the format 4 EXIT statement, EXIT
FUNCTION.

Format 1 (simple)
The format 1 EXIT statement provides a common end point for a series of
procedures.

Format 1

►► paragraph-name . EXIT ►◄

The format 1 EXIT statement enables you to assign a procedure-name to a given

point in a program.

The format 1 EXIT statement is treated as a CONTINUE statement. Any statements

following the EXIT statement are executed.

348 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 2 (program)
The EXIT PROGRAM statement specifies the end of a called program and returns
control to the calling program.

You can specify EXIT PROGRAM only in the PROCEDURE DIVISION of a

program. EXIT PROGRAM must not be used in a declarative procedure in which
the GLOBAL phrase is specified.

Format 2

►► EXIT PROGRAM ►◄

If control reaches an EXIT PROGRAM statement in a program that does not

possess the INITIAL attribute while operating under the control of a CALL
statement (that is, the CALL statement is active), control returns to the point in the
calling routine (program or method) immediately following the CALL statement.
The state of the calling routine is identical to that which existed at the time it
executed the CALL statement. The contents of data items and the contents of data
files shared between the calling and called routine could have been changed. The
state of the called program or method is not altered except that the ends of the
ranges of all executed PERFORM statements are considered to have been reached.

The execution of an EXIT PROGRAM statement in a called program that possesses

the INITIAL attribute is equivalent also to executing a CANCEL statement
referencing that program.

If control reaches an EXIT PROGRAM statement, and no CALL statement is active,

control passes through the exit point to the next executable statement.

If a subprogram specifies the PROCEDURE DIVISION RETURNING phrase, the

value in the data item referred to by the RETURNING phrase becomes the result
of the subprogram invocation.

The EXIT PROGRAM statement should be the last statement in a sequence of

imperative statements. When it is not, statements following the EXIT PROGRAM
will not be executed if a CALL statement is active.

When there is no next executable statement in a called program, an implicit EXIT

PROGRAM statement is executed.

Chapter 20. PROCEDURE DIVISION statements 349

 Format 3 (method)
The EXIT METHOD statement specifies the end of an invoked method.

Format 3

►► EXIT METHOD ►◄

You can specify EXIT METHOD only in the PROCEDURE DIVISION of a method.
EXIT METHOD causes the executing method to terminate, and control returns to
the invoking statement. If the containing method specifies the PROCEDURE
DIVISION RETURNING phrase, the value in the data item referred to by the
RETURNING phrase becomes the result of the method invocation.

If you need method-specific data to be in the last-used state on each invocation,

define it in method WORKING-STORAGE. If you need method-specific data to be
in the initial state on each invocation, define it in method LOCAL-STORAGE.

If control reaches an EXIT METHOD statement in a method definition, control

returns to the point that immediately follows the INVOKE statement in the
invoking program or method. The state of the invoking program or method is
identical to that which existed at the time it executed the INVOKE statement.

The contents of data items and the contents of data files shared between the
invoking program or method and the invoked method could have changed. The
state of the invoked method is not altered except that the end of the ranges of all
PERFORM statements executed by the method are considered to have been
reached.

The EXIT METHOD statement does not have to be the last statement in a sequence
of imperative statements, but the statements following the EXIT METHOD will not
be executed.

When there is no next executable statement in an invoked method, an implicit

EXIT METHOD statement is executed.

Format 5 (inline-perform)
The EXIT PERFORM statement controls the exit from an inline PERFORM without
using a GO TO statement or a PERFORM ... THROUGH statement.

Format 5

►► EXIT PERFORM ►◄
CYCLE

If you specify an EXIT PERFORM statement outside of an inline PERFORM

statement, the EXIT PERFORM is ignored.

350 Enterprise COBOL for z/OS, V6.1 Language Reference

 When an EXIT PERFORM statement without the CYCLE phrase is executed,
control is passed to an implicit CONTINUE statement. This implicit CONTINUE
statement immediately follows the END-PERFORM phrase that matches the most
closely preceding and unterminated inline PERFORM statement.

When an EXIT PERFORM statement with the CYCLE phrase is executed, control is
passed to an implicit CONTINUE statement. This implicit CONTINUE statement
immediately precedes the END-PERFORM phrase that matches the most closely
preceding and unterminated inline PERFORM statement.

Format 6 (procedure)
The EXIT PARAGRAPH statement controls the exit from the middle of a
paragraph without executing any following statements within the paragraph. The
EXIT SECTION statement controls the exit from a section without executing any
following statements within the section.

Format 6

►► EXIT PARAGRAPH ►◄
SECTION

EXIT PARAGRAPH

When an EXIT PARAGRAPH statement is executed, control is passed to an implicit

CONTINUE statement that immediately follows the last explicit statement of the
current paragraph. This return mechanism supersedes any other return
mechanisms that are associated with language elements, such as PERFORM, SORT,
and USE for that paragraph.

EXIT SECTION

The EXIT SECTION statement can be specified only in a section.

When an EXIT SECTION statement is executed, control is passed to an unnamed

empty paragraph that immediately follows the last paragraph of the current
section. This return mechanism supersedes any other return mechanisms that are
associated with language elements, such as PERFORM, SORT, and USE for that
section.

| FREE statement
| The FREE statement releases dynamic storage that was previously obtained with
| an ALLOCATE statement.

Chapter 20. PROCEDURE DIVISION statements 351

| Format

►► FREE ▼ data-name-1 ►◄
|
||

| data-name-1
| Must be defined as USAGE IS POINTER.
| Can be qualified or subscripted.

| The FREE statement is processed as follows:

| v If the pointer referenced by data-name-1 identifies the start of storage that is
| currently allocated by an ALLOCATE statement, that storage is released and the
| pointer referenced by data-name-1 is set to NULL, the length of the released
| storage is the length of the storage obtained by the ALLOCATE statement, and
| the contents of any data items located within the released storage area become
| undefined.
| v If the pointer referenced by data-name-1 contains the predefined address NULL
| or the address of storage that is not acquired by the ALLOCATE statement, no
| storage will be freed. The pointer data-name-1 will be kept unchanged and the
| behavior is undefined.

| If more than one data-name-1 is specified in a FREE statement, the result of

| executing this FREE statement is the same as if a separate FREE statement had
| been written for each data-name-1 in the same order as specified in the FREE
| statement.

| RELATED REFERENCES
| “ALLOCATE statement” on page 310
| “Example: ALLOCATE and FREE storage for UNBOUNDED tables” on page 312

352 Enterprise COBOL for z/OS, V6.1 Language Reference

GOBACK statement
The GOBACK statement functions like the EXIT PROGRAM statement when it is
coded as part of a called program (or the EXIT METHOD statement when
GOBACK is coded as part of an invoked method) and like the STOP RUN
statement when coded in a main program.

The GOBACK statement specifies the logical end of a called program or invoked
method.

Format

►► GOBACK ►◄

A GOBACK statement should appear as the only statement or as the last of a

series of imperative statements in a sentence because any statements following the
GOBACK are not executed. GOBACK must not be used in a declarative procedure
in which the GLOBAL phrase is specified.

If control reaches a GOBACK statement while a CALL statement is active, control

returns to the point in the calling program or method immediately following the
CALL statement, as in the EXIT PROGRAM statement.

If control reaches a GOBACK statement while an INVOKE statement is active,

control returns to the point in the invoking program or method immediately
following the INVOKE statement, as in the EXIT METHOD statement.

In addition, the execution of a GOBACK statement in a called program that

possesses the INITIAL attribute is equivalent to executing a CANCEL statement
referencing that program.

The table below shows the action taken for the GOBACK statement in both a main
program and a subprogram.

Termination
statement Main program Subprogram
GOBACK Returns to the calling program. Returns to the calling program.
(Can be the system, which causes
the application to end.)

Chapter 20. PROCEDURE DIVISION statements 353

GO TO statement
The GO TO statement transfers control from one part of the PROCEDURE
DIVISION to another.

The types of GO TO statements are:

v Unconditional
v Conditional
v Altered

Unconditional GO TO
The unconditional GO TO statement transfers control to the first statement in the
paragraph or section identified by procedure-name, unless the GO TO statement
has been modified by an ALTER statement.

For more information, see “ALTER statement” on page 314.

Format 1: unconditional GO TO statement

►► GO procedure-name-1 ►◄
TO

procedure-name-1
Must name a procedure or a section in the same PROCEDURE DIVISION
as the GO TO statement.

When the unconditional GO TO statement is not the last statement in a sequence

of imperative statements, the statements following the GO TO are not executed.

When a paragraph is referred to by an ALTER statement, the paragraph must

consist of a paragraph-name followed by an unconditional or altered GO TO
statement.

Conditional GO TO
The conditional GO TO statement transfers control to one of a series of procedures,
depending on the value of the data item referenced by identifier-1.

Format 2: conditional GO TO statement

►► GO ▼ procedure-name-1 DEPENDING identifier-1 ►◄

TO ON

354 Enterprise COBOL for z/OS, V6.1 Language Reference

 procedure-name-1
Must be a procedure or a section in the same PROCEDURE DIVISION as
the GO TO statement. The number of procedure-names must not exceed
255.
identifier-1
Must be a numeric elementary data item that is an integer.
If 1, control is transferred to the first statement in the procedure named by
the first occurrence of procedure-name-1.
If 2, control is transferred to the first statement in the procedure named by
the second occurrence of procedure-name-1, and so forth.
If the value of identifier is anything other than a value within the range of
1 through n (where n is the number of procedure-names specified in this
GO TO statement), no control transfer occurs. Instead, control passes to the
next statement in the normal sequence of execution.

Altered GO TO
The altered GO TO statement transfers control to the first statement of the
paragraph named in the ALTER statement.

You cannot specify the altered GO TO statement in the following cases:

v A program or method that has the RECURSIVE attribute
v A program compiled with the THREAD compiler option

An ALTER statement referring to the paragraph that contains the altered GO TO

statement should be executed before the GO TO statement is executed. Otherwise,
the GO TO statement acts like a CONTINUE statement.

Format 3: altered GO TO statement

►► paragraph-name . GO . ►◄
TO

When an ALTER statement refers to a paragraph, the paragraph can consist only of
the paragraph-name followed by an unconditional or altered GO TO statement.

Chapter 20. PROCEDURE DIVISION statements 355

IF statement
The IF statement evaluates a condition and provides for alternative actions in the
object program, depending on the evaluation.

Format

►► IF condition-1 ▼ statement-1 ►
THEN NEXT SENTENCE

► ►◄
(1)
END-IF
ELSE ▼ statement-2
NEXT SENTENCE

Notes:
1 END-IF can be specified with statement-2 or NEXT SENTENCE.

condition-1
Can be any simple or complex condition, as described in “Conditional
expressions” on page 264.
statement-1, statement-2
Can be any one of the following options:
v An imperative statement
v A conditional statement
v An imperative statement followed by a conditional statement
NEXT SENTENCE
The NEXT SENTENCE phrase transfers control to an implicit CONTINUE
statement immediately following the next separator period.
When NEXT SENTENCE is specified with END-IF, control does not pass to
the statement following the END-IF. Instead, control passes to the
statement after the closest following period.

END-IF phrase

This explicit scope terminator serves to delimit the scope of the IF statement.
END-IF permits a conditional IF statement to be nested in another conditional
statement. For more information about explicit scope terminators, see “Delimited
scope statements” on page 288.

The scope of an IF statement can be terminated by any of the following options:

v An END-IF phrase at the same level of nesting
v A separator period
v If nested, by an ELSE phrase associated with an IF statement at a higher level of
nesting
356 Enterprise COBOL for z/OS, V6.1 Language Reference
 Transferring control
The topic describes the actions to take when conditions tested is true or false.

If the condition tested is true, one of the following actions takes place:
v If statement-1 is specified, statement-1 is executed. If statement-1 contains a
procedure branching or conditional statement, control is transferred according to
the rules for that statement. If statement-1 does not contain a
procedure-branching statement, the ELSE phrase, if specified, is ignored, and
control passes to the next executable statement after the corresponding END-IF
or separator period.
v If NEXT SENTENCE is specified, control passes to an implicit CONTINUE
| statement immediately following the next separator period.

If the condition tested is false, one of the following actions takes place:
v If ELSE statement-2 is specified, statement-2 is executed. If statement-2 contains a
procedure-branching or conditional statement, control is transferred, according
to the rules for that statement. If statement-2 does not contain a
procedure-branching or conditional statement, control is passed to the next
executable statement after the corresponding END-IF or separator period.
v If ELSE NEXT SENTENCE is specified, control passes to an implicit CONTINUE
STATEMENT immediately preceding the next separator period.
v If neither ELSE statement-2 nor ELSE NEXT SENTENCE is specified, control
passes to the next executable statement after the corresponding END-IF or
separator period.

When the ELSE phrase is omitted, all statements following the condition and
preceding the corresponding END-IF or the separator period for the sentence are
considered to be part of statement-1.

Nested IF statements
When an IF statement appears as statement-1 or statement-2, or as part of statement-1
or statement-2, that IF statement is nested.

When an IF statement appears as statement-1 or statement-2, or as part of statement-1

or statement-2, that IF statement is nested.

Nested IF statements are considered to be matched IF, ELSE, and END-IF

combinations proceeding from left to right. Thus, any ELSE encountered is
matched with the nearest preceding IF that either has not been already matched
with an ELSE or has not been implicitly or explicitly terminated. Any END-IF
encountered is matched with the nearest preceding IF that has not been implicitly
or explicitly terminated.

Chapter 20. PROCEDURE DIVISION statements 357

 INITIALIZE statement
The INITIALIZE statement sets selected categories of data fields to predetermined
values. The INITIALIZE statement is functionally equivalent to one or more MOVE
statements.

| Format

|
|
►► INITIALIZE ▼ identifier-1 ►
FILLER
WITH

| ► ►
| ALL VALUE
category-name TO

| ► ►
|
REPLACING ▼ category-name BY identifier-2
THEN DATA literal-1

| ► ►◄
| DEFAULT
THEN TO

| Where category-name is:

| v ALPHABETIC
| v ALPHANUMERIC
| v ALPHANUMERIC-EDITED
| v DBCS
| v EGCS
| v NATIONAL
| v NATIONAL-EDITED
| v NUMERIC
| v NUMERIC-EDITED
identifier-1
Receiving areas.
identifier-1 must reference one of the following items:
v An alphanumeric group item
v A national group item
v An elementary data item of one of the following categories:
– Alphabetic
– Alphanumeric

358 Enterprise COBOL for z/OS, V6.1 Language Reference

 – Alphanumeric-edited
– DBCS
– External floating-point
– Internal floating-point
– National
– National-edited
– Numeric
– Numeric-edited
v A special register that is valid as a receiving operand in a MOVE
statement with identifer-2 or literal-1 as the sending operand.
| identifier-1 references an elementary item or a group item. The effect of the
| execution of an INITIALIZE statement is as if a series of implicit MOVE
| statements, each of which has an elementary data item as its receiving
| operand, were executed.
When identifier-1 references a national group item, identifier-1 is processed
as a group item.
identifier-2, literal-1
Sending areas.
When identifier-2 references a national group item, identifier-2 is processed
as an elementary data item of category national.
identifier-2 must reference an elementary data item (or a national group
item treated as elementary) that is valid as a sending operand in a MOVE
statement with identifier-1 as the receiving operand.
literal-1 must be a literal that is valid as a sending operand in a MOVE
statement with identifier-1 as the receiving operand.

A subscripted item can be specified for identifier-1. A complete table can be

initialized only by specifying identifier-1 as a group that contains the complete
table.

Usage note: The data description entry for identifier-1 can contain the DEPENDING
phrase of the OCCURS clause. However, you cannot use the INITIALIZE statement
to initialize a variably-located item or a variable-length item.

The data description entry for identifier-1 must not contain a RENAMES clause.

Special registers can be specified for identifier-1 and identifier-2 only if they are
valid receiving fields or sending fields, respectively, for the implied MOVE
statements.

| FILLER phrase

| When the FILLER phrase is specified, the receiving elementary data items that
| have an explicit or implicit FILLER clause will be initialized.

| VALUE phrase
| When the VALUE phrase is specified:
| v If ALL is specified in the VALUE phrase, it is as if all of the categories listed in
| category-name were specified.

Chapter 20. PROCEDURE DIVISION statements 359

| v The same category cannot be repeated in a VALUE phrase.

REPLACING phrase

When the REPLACING phrase is specified:

v identifier-2 must reference an item of a category that is valid as a sending
operand in a MOVE statement to an item of the corresponding category
specified in the REPLACING phrase.
v literal-1 must be of a category that is valid as a sending operand in a MOVE
statement to an item of the corresponding category specified in the REPLACING
phrase.
v A floating-point literal, a data item of category internal floating-point, or a data
item of category external floating point is treated as if it were in the NUMERIC
category.
v The same category cannot be repeated in a REPLACING phrase.

With the exception of EGCS, the keyword after the word REPLACING corresponds
to a category of data shown in “Classes and categories of data” on page 166.

EGCS in the REPLACING phrase is synonymous with DBCS.

RELATED REFERENCES
“ALLOCATE statement” on page 310

INITIALIZE statement rules

| The effect of the execution of an INITIALIZE statement is as if a series of implicit
| MOVE statements, each of which has an elementary data item as its receiving
| operand, were executed. The receiving operands of these implicit statements are
| defined in rule 1 and the sending operands are defined in rule 2.
| 1. The receiving operand in each implicit MOVE statement is determined by
| applying the following steps in order:
| a. First, the following data items are excluded as receiving operands:
| v Any identifiers that are not valid receiving operands of a MOVE
| statement.
| v Elementary data items that have an explicit or implicit FILLER clause if
| the FILLER phrase is not specified.
| v Any elementary data item subordinate to identifier-1 whose data
| description entry contains a REDEFINES or RENAMES clause or is
| subordinate to a data item whose data description entry contains a
| REDEFINES clause. However, identifier-1 might itself have a REDEFINES
| clause or be subordinate to a data item with a REDEFINES clause.
| b. Second, an elementary data item is a possible receiving item in either of the
| following cases:
| v It is explicitly referenced by identifier-1.
| v It is contained within the group data item referenced by identifier-1. If the
| elementary data item is a table element, each occurrence of the
| elementary data item is a possible receiving operand.
| c. Finally, each possible receiving operand is a receiving operand if at least one
| of the following conditions is true:
| v The VALUE phrase is specified, the category of the elementary data item
| is one of the categories specified or implied in the VALUE phrase, and
| either of the following conditions is true:

360 Enterprise COBOL for z/OS, V6.1 Language Reference

| – A data-item format VALUE clause is specified in the data description
| entry of the elementary data item.
| – A table format VALUE clause is specified in the data description entry
| of the elementary item and that VALUE clause specifies a value for the
| particular occurrence of the elementary data item.
| v The REPLACING phrase is specified and the category of the elementary
| data item is one of the categories specified in the REPLACING phrase.
| v The DEFAULT phrase is specified.
| v Neither the REPLACING phrase nor the VALUE phrase is specified.
| 2. The sending operand in each implicit MOVE statement is determined as
| follows:
| v If the data item qualifies as a receiving operand because of the VALUE
| phrase, the sending operand is determined by the literal in the VALUE
| clause specified in the data description entry of the data item. If the data
| item is a table element, the literal in the VALUE clause that corresponds to
| the occurrence being initialized determines the sending operand. The actual
| sending operand is a literal that, when moved to the receiving operand with
| a MOVE statement, produces the same result as the initial value of the data
| item as produced by the application of the VALUE clause.
| v If the data item does not qualify as a receiving operand because of the
| VALUE phrase, but does qualify because of the REPLACING phrase, the
| sending operand is the literal-1 or identifier-2 associated with the category
| specified in the REPLACING phrase.
| v If the data item does not qualify in accordance with the preceding two rules,
| the sending operand used depends on the category of the receiving operand
| as follows:
| – SPACE is the implied sending item for receiving items of category
| alphabetic, alphanumeric, alphanumeric-edited, DBCS, EGCS, national, or
| national-edited.
| – ZERO is the implied sending item for receiving items of category numeric
| or numeric-edited.

Chapter 20. PROCEDURE DIVISION statements 361

INSPECT statement
The INSPECT statement examines characters or groups of characters in a data
item.

The INSPECT statement does the following tasks:

v Counts the occurrences of a specific character (alphanumeric, DBCS, or national)
in a data item (formats 1 and 3).
v Counts the occurrences of specific characters and fills all or portions of a data
item with specified characters, such as spaces or zeros (formats 2 and 3).
v Converts all occurrences of specific characters in a data item to user-supplied
replacement characters (format 4).

Format 1: INSPECT statement with TALLYING phrase

►► INSPECT identifier-1 TALLYING ►

► ▼ identifier-2 FOR ▼ CHARACTERS ▼ ►◄

phrase 1

ALL ▼ identifier-3 ▼
LEADING literal-1 phrase 1

phrase 1:

BEFORE identifier-4
AFTER INITIAL literal-2

362 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 2: INSPECT statement with REPLACING phrase

►► INSPECT identifier-1 REPLACING ►

► ▼ CHARACTERS BY identifier-5 ▼ ►◄
literal-3 phrase 1

ALL ▼ identifier-3 BY identifier-5 ▼

LEADING literal-1 literal-3 phrase 1
FIRST

phrase 1:

BEFORE identifier-4
AFTER INITIAL literal-2

Chapter 20. PROCEDURE DIVISION statements 363

 Format 3: INSPECT statement with TALLYING and REPLACING phrases

►► INSPECT identifier-1 TALLYING ►

► ▼ identifier-2 FOR ▼ CHARACTERS ▼ ►

phrase 1

ALL ▼ identifier-3 ▼
LEADING literal-1 phrase 1

► REPLACING ►

► ▼ CHARACTERS BY identifier-5 ▼ ►◄
literal-3 phrase 1

ALL ▼ identifier-3 BY identifier-5 ▼

LEADING literal-1 literal-3 phrase 1
FIRST

phrase 1:

BEFORE identifier-4
AFTER INITIAL literal-2

364 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 4: INSPECT statement with CONVERTING phrase

►► INSPECT identifier-1 CONVERTING identifier-6 TO identifier-7 ►

literal-4 literal-5

► ▼ BEFORE identifier-4 ►◄
AFTER INITIAL literal-2

identifier-1
Is the inspected item and can be any of the following items:
v An alphanumeric group item or a national group item
v An elementary data item described explicitly or implicitly with usage
DISPLAY, DISPLAY-1, or NATIONAL. The item can have any category
that is valid for the selected usage.
identifier-3 , identifier-4 , identifier-5 , identifier-6 , identifier-7
Must reference an elementary data item described explicitly or implicitly
with usage DISPLAY, DISPLAY-1, or NATIONAL.
literal-1 , literal-2 , literal-3 , literal-4
Must be of category alphanumeric, DBCS, or national.
When identifier-1 is of usage NATIONAL, literals must be of category
national.
When identifier-1 is of usage DISPLAY-1, literals must be of category DBCS.
When identifier-1 is of usage DISPLAY, literals must be of category
alphanumeric.
When identifier-1 is of usage DISPLAY-1 (DBCS) literals may be the
figurative constant SPACE.
When identifier-1 is of usage DISPLAY or NATIONAL, literals can be any
figurative constant that does not begin with the word ALL, as specified in
“Figurative constants” on page 13. The figurative constant is treated as a
one-character alphanumeric literal when identifier-1 is of usage DISPLAY,
and as a one-character national literal when identifier-1 is of usage
NATIONAL.

All identifiers (except identifier-2) must have the same usage as identifier-1. All
literals must have category alphanumeric, DBCS, or national when identifier-1 has
usage DISPLAY, DISPLAY-1, or NATIONAL, respectively.

TALLYING phrase (formats 1 and 3)

This phrase counts the occurrences of a specific character or special character in a

data item.

When identifier-1 is a DBCS data item, DBCS characters are counted; when
identifier-1 is a data item of usage national, national characters (encoding units) are
counted; otherwise, alphanumeric characters (bytes) are counted.

Chapter 20. PROCEDURE DIVISION statements 365

 identifier-2
Is the count field, and must be an elementary integer item defined without
the symbol P in its PICTURE character-string.
identifier-2 cannot be of category external floating-point.
You must initialize identifier-2 before execution of the INSPECT statement
begins.
Usage note: The count field can be an integer data item defined with usage
NATIONAL.
identifier-3 or literal-1
Is the tallying field (the item whose occurrences will be tallied).
CHARACTERS
When CHARACTERS is specified and neither the BEFORE nor AFTER
phrase is specified, the count field (identifier-2) is increased by 1 for each
character (including the space character) in the inspected item (identifier-1).
Thus, execution of an INSPECT statement with the TALLYING phrase
increases the value in the count field by the number of character positions
in the inspected item.
ALL When ALL is specified and neither the BEFORE nor AFTER phrase is
specified, the count field (identifier-2) is increased by 1 for each
nonoverlapping occurrence of the tallying comparand (identifier-3 or
literal-1) in the inspected item (identifier-1), beginning at the leftmost
character position and continuing to the rightmost.
LEADING
When LEADING is specified and neither the BEFORE nor AFTER phrase is
specified, the count field (identifier-2) is increased by 1 for each contiguous
nonoverlapping occurrence of the tallying comparand in the inspected item
(identifier-1), provided that the leftmost such occurrence is at the point
where comparison began in the first comparison cycle for which the
tallying comparand is eligible to participate.
FIRST (format 3 only)
When FIRST is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces the leftmost occurrence of the
subject field in the inspected item (identifier-1).

REPLACING phrase (formats 2 and 3)

This phrase fills all or portions of a data item with specified characters, such as
spaces or zeros.
identifier-3 or literal-1
Is the subject field, which identifies the characters to be replaced.
identifier-5 or literal-3
Is the substitution field (the item that replaces the subject field).
The subject field and the substitution field must be the same length.
CHARACTERS BY
When the CHARACTERS BY phrase is used, the substitution field must be
one character position in length.

366 Enterprise COBOL for z/OS, V6.1 Language Reference

 When CHARACTERS BY is specified and neither the BEFORE nor AFTER
phrase is specified, the substitution field replaces each character in the
inspected item (identifier-1), beginning at the leftmost character position
and continuing to the rightmost.
ALL When ALL is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces each nonoverlapping occurrence of
the subject field in the inspected item (identifier-1), beginning at the
leftmost character position and continuing to the rightmost.
LEADING
When LEADING is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces each contiguous nonoverlapping
occurrence of the subject field in the inspected item (identifier-1), provided
that the leftmost such occurrence is at the point where comparison began
in the first comparison cycle for which this substitution field is eligible to
participate.
FIRST
When FIRST is specified and neither the BEFORE nor AFTER phrase is
specified, the substitution field replaces the leftmost occurrence of the
subject field in the inspected item (identifier-1).

When both the TALLYING and REPLACING phrases are specified (format 3), the
INSPECT statement is executed as if an INSPECT TALLYING statement (format 1)
were specified, immediately followed by an INSPECT REPLACING statement
(format 2).

The following replacement rules apply:

v When the subject field is a figurative constant, the one-character substitution
field replaces each character in the inspected item that is equivalent to the
figurative constant.
v When the substitution field is a figurative constant, the substitution field
replaces each nonoverlapping occurrence of the subject field in the inspected
item.
v When the subject and substitution fields are character-strings, the
character-string specified in the substitution field replaces each nonoverlapping
occurrence of the subject field in the inspected item.
v After replacement has occurred in a given character position in the inspected
item, no further replacement for that character position is made in this execution
of the INSPECT statement.

BEFORE and AFTER phrases (all formats)

This phrase narrows the set of items being tallied or replaced.

No more than one BEFORE phrase and one AFTER phrase can be specified for any
one ALL, LEADING, CHARACTERS, FIRST or CONVERTING phrase.
identifier-4 or literal-2
Is the delimiter.
Delimiters are not counted or replaced.
INITIAL
The first occurrence of a specified item.

The BEFORE and AFTER phrases change how counting and replacing are done:

Chapter 20. PROCEDURE DIVISION statements 367

 v When BEFORE is specified, counting or replacing of the inspected item
(identifier-1) begins at the leftmost character position and continues until the first
occurrence of the delimiter is encountered. If no delimiter is present in the
inspected item, counting or replacing continues toward the rightmost character
position.
v When AFTER is specified, counting or replacing of the inspected item
(identifier-1) begins with the first character position to the right of the delimiter
and continues toward the rightmost character position in the inspected item. If
no delimiter is present in the inspected item, no counting or replacement takes
place.

CONVERTING phrase (format 4)

This phrase converts all occurrences of a specific character or string of characters in

a data item (identifier-1) to user-supplied replacement characters.
identifier-6 or literal-4
Specifies the character string to be replaced.
The same character must not appear more than once in either literal-4 or
identifier-6.
identifier-7 or literal-5
Specifies the replacing character string.
The replacing character string (identifier-7 or literal-5) must be the same size
as the replaced character string (identifier-6 or literal-4).

A format-4 INSPECT statement is interpreted and executed as if a format-2

INSPECT statement had been written with a series of ALL phrases (one for each
character of literal-4), specifying the same identifier-1. The effect is as if each single
character of literal-4 were referenced as literal-1, and the corresponding single
character of literal-5 referenced as literal-3. Correspondence between the characters
of literal-4 and the characters of literal-5 is by ordinal position within the data item.

If identifier-4, identifier-6, or identifier-7 occupies the same storage area as identifier-1,

the result of the execution of this statement is undefined, even if they are defined
by the same data description entry.

The following table describes the treatment of data items that can be used as an
operand in the INSPECT statement:
Table 37. Treatment of the content of data items
When referenced by any identifier except
identifier-2, the content of each item of
category ... Is treated ...
Alphanumeric or alphabetic As an alphanumeric character string
DBCS As a DBCS character string
National As a national character string
Alphanumeric-edited, numeric-edited with As if redefined as category alphanumeric,
usage DISPLAY, or numeric with usage with the INSPECT statement referring to an
DISPLAY (unsigned, external decimal) alphanumeric character string
National-edited, numeric-edited with usage As if redefined as category national, with
NATIONAL or numeric with usage the INSPECT statement referring to a
NATIONAL (unsigned, external decimal) national character string

368 Enterprise COBOL for z/OS, V6.1 Language Reference

 Table 37. Treatment of the content of data items (continued)
When referenced by any identifier except
identifier-2, the content of each item of
category ... Is treated ...
Numeric with usage DISPLAY (signed, As if moved to an unsigned external decimal
external decimal) item of usage DISPLAY with the same
length as the identifier and then redefined as
category alphanumeric, with the INSPECT
statement referring to an alphanumeric
character string

If the sign is a separate character, the byte

containing the sign is not examined and,
therefore, not replaced.

If the referenced item is identifier-1, the

string that results from any replacing or
converting action is copied back to
identifier-1.
Numeric with usage NATIONAL (signed, As if moved to an unsigned external decimal
external decimal) item of usage NATIONAL with the same
length as the identifier and then redefined as
category national, with the INSPECT
statement referring to a national character
string

If the sign is a separate character, the byte

containing the sign is not examined and,
therefore, not replaced.

If the referenced item is identifier-1, the

string that results from any replacing or
converting action is copied back to
identifier-1.
External floating-point with usage DISPLAY As if redefined as category alphanumeric,
with the INSPECT statement referring to an
alphanumeric character-string
External floating-point with usage As if redefined as category national, with
NATIONAL the INSPECT statement referring to a
national character-string

Data flow
Except when the BEFORE or AFTER phrase is specified, inspection begins at the
leftmost character position of the inspected item (identifier-1) and proceeds
character-by-character to the rightmost position.

The comparands of the following phrases are compared in the left-to-right order in
which they are specified in the INSPECT statement:
v TALLYING (literal-1 or identifier-3, ... )
v REPLACING (literal-3 or identifier-5, ... )

If any identifier is subscripted or reference modified, or is a function-identifier, the

subscript, reference-modifier, or function is evaluated only once as the first
operation in the execution of the INSPECT statement.

Chapter 20. PROCEDURE DIVISION statements 369

 For examples of TALLYING and REPLACING, see Tallying and replacing data items
(INSPECT) in the Enterprise COBOL Programming Guide.

Comparison cycle
The comparison cycle consists of the actions as described in this topic.
1. The first comparand is compared with an equal number of leftmost contiguous
character positions in the inspected item. The comparand matches the inspected
characters only if both are equal, character-for-character.
If the CHARACTERS phrase is specified, an implied one-character comparand
is used. The implied character is always considered to match the inspected
character in the inspected item.
2. If no match occurs for the first comparand and there are more comparands, the
comparison is repeated for each successive comparand until either a match is
found or all comparands have been acted upon.
3. Depending on whether a match is found, these actions are taken:
v If a match is found, tallying or replacing takes place as described in the
TALLYING and REPLACING phrase descriptions.
If there are more character positions in the inspected item, the first character
position following the rightmost matching character is now considered to be
in the leftmost character position. The process described in actions 1 and 2 is
then repeated.
v If no match is found and there are more character positions in the inspected
item, the first character position following the leftmost inspected character is
now considered to be in the leftmost character position. The process
described in actions 1 and 2 is then repeated.
4. Actions 1 through 3 are repeated until the rightmost character position in the
inspected item either has been matched or has been considered as being in the
leftmost character position.

When the BEFORE or AFTER phrase is specified, the comparison cycle is modified,
as described in “BEFORE and AFTER phrases (all formats)” on page 367.

Example of the INSPECT statement

The topic shows an example of INSPECT statement results.

370 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 20. PROCEDURE DIVISION statements 371
INVOKE statement
The INVOKE statement can create object instances of a COBOL or Java class and
can invoke a method defined in a COBOL or Java class.

Format

►► INVOKE identifier-1 literal-1 ►

class-name-1 identifier-2
SELF NEW
SUPER

► ►

USING ▼ VALUE ▼ identifier-3

BY LENGTH OF
literal-2

► ►
RETURNING identifier-4

► ►
EXCEPTION imperative-statement-1
ON

► ►◄
NOT EXCEPTION imperative-statement-2 END-INVOKE
ON

identifier-1
Must be defined as USAGE OBJECT REFERENCE. The contents of
identifier-1 specify the object on which a method is invoked.
When identifier-1 is specified, either literal-1 or identifier-2 must be specified,
identifying the name of the method to be invoked.
The results of the INVOKE statement are undefined if either:
v identifier-1 does not contain a valid reference to an object.
v identifier-1 contains NULL.
class-name-1
When class-name-1 is specified together with literal-1 or identifier-2, the
INVOKE statement invokes a static or factory method of the class
referenced by class-name-1. literal-1 or identifier-2 specifies the name of the
method that is to be invoked. The method must be a static method if
class-name-1 is a Java class; the method must be a factory method if
class-name-1 is a COBOL class.
When class-name-1 is specified together with NEW, the INVOKE statement
creates a new object that is an instance of class class-name-1.
You must specify class-name-1 in the REPOSITORY paragraph of the
configuration section of the class or program that contains the INVOKE
statement.
372 Enterprise COBOL for z/OS, V6.1 Language Reference
SELF An implicit reference to the object used to invoke the currently executing
method. When SELF is specified, the INVOKE statement must appear
within the PROCEDURE DIVISION of a method.
SUPER
An implicit reference to the object that was used to invoke the currently
executing method. The resolution of the method to be invoked will ignore
any methods declared in the class definition of the currently executing
method and methods defined in any class derived from that class; thus the
method invoked will be one that is inherited from an ancestor class.
literal-1
The value of literal-1 is the name of the method to be invoked. The
referenced object must support the method identified by literal-1.
literal-1 must be an alphanumeric literal or a national literal.
literal-1 is interpreted in a case-sensitive manner. The method name, the
number of arguments, and the data types of the arguments in the USING
phrase of the INVOKE statement are used to select the method with
matching signature that is supported by the object. The method can be
overloaded.
identifier-2
A data item of category alphabetic, alphanumeric, or national that at run
time contains the name of the method to be invoked. The referenced object
must support the method identified by identifier-2.
If identifier-2 is specified, identifier-1 must be defined as USAGE OBJECT
REFERENCE without any optional phrases; that is, identifier-1 must be a
universal object reference.
The content of identifier-2 is interpreted in a case-sensitive manner. The
method name, the number of arguments, and the data types of the
arguments in the USING phrase of the INVOKE statement are used to
select the method with matching signature that is supported by the object.
The method can be overloaded.
NEW The NEW operand specifies that the INVOKE statement is to create a new
object instance of the class class-name-1. class-name-1 must be specified.
When class-name-1 is implemented in Java, the USING phrase of the
INVOKE statement can be specified. The number of arguments and the
data types of the arguments in the USING phrase of the INVOKE
statement are used to select the Java constructor with matching signature
that is supported by the class. An object instance of class class-name-1 is
allocated, the selected constructor (or the default constructor) is executed,
and a reference to the created object is returned.
When class-name-1 is implemented in COBOL, the USING phrase of the
INVOKE statement must not be specified. An object instance of class
class-name-1 is allocated, instance data items are initialized to the values
specified in associated VALUE clauses, and a reference to the created object
is returned.
When NEW is specified, you must also specify a RETURNING phrase as
described in “RETURNING phrase” on page 375.

Chapter 20. PROCEDURE DIVISION statements 373

 USING phrase

The USING phrase specifies arguments that are passed to the target method. The
argument data types and argument linkage conventions are restricted to those
supported by Java. See “BY VALUE phrase” for details.

BY VALUE phrase
Arguments specified in an INVOKE statement must be passed BY VALUE.

The BY VALUE phrase specifies that the value of the argument is passed, not a
reference to the sending data item. The invoked method can modify the formal
parameter that corresponds to an argument passed by value, but changes do not
affect the argument because the invoked method has access only to a temporary
copy of the sending data item.
identifier-3
Must be an elementary data item in the DATA DIVISION. The data type of
identifier-3 must be one of the types supported for Java interoperation, as
listed in “Interoperable data types for COBOL and Java” on page 377.
Miscellaneous cases that are also supported as identifier-3 are listed in
“Miscellaneous argument types for COBOL and Java” on page 378, with
their corresponding Java type.
See Conformance requirements for arguments for additional requirements
that apply to identifier-3.
literal-2
Must be of a type suitable for Java interoperation and must exactly match
the type of the corresponding parameter in the target method. Supported
literal forms are listed in “Miscellaneous argument types for COBOL and
Java” on page 378, with their corresponding Java type.
literal-2 must not be a DBCS literal.
LENGTH OF identifier-3
Specifies that the length of identifier-3 is passed as an argument in the
LENGTH OF special register. A LENGTH OF special register passed BY
VALUE is treated as a PIC 9(9) binary value. For information about the
LENGTH OF special register, see “LENGTH OF” on page 19.

Conformance requirements for arguments

When identifier-3 is an object reference, certain rules apply.

The rules are:

v A class-name must be specified in the data description entry for that object
reference. That is, identifier-3 must not be a universal object reference.
v The specified class-name must reference a class that is exactly the class of the
corresponding parameter in the invoked method. That is, the class of identifier-3
must not be a subclass or a superclass of the corresponding parameter's class.

When identifier-3 is not an object reference, the following rules apply:

v If the target method is implemented in COBOL, the description of identifier-3
must exactly match the description of the corresponding formal parameter in the
target method.

374 Enterprise COBOL for z/OS, V6.1 Language Reference

v If the target method is implemented in Java, the description of identifier-3 must
correspond to the Java type of the formal parameter in the target method, as
specified in “Interoperable data types for COBOL and Java” on page 377.

Usage note: Adherence to conformance requirements for arguments is the

responsibility of the programmer. Conformance requirements are not verified by
the compiler.

RETURNING phrase

The RETURNING phrase specifies a data item that will contain the value returned
from the invoked method. You can specify the RETURNING phrase on the
INVOKE statement when invoking methods that are written in COBOL or Java.
identifier-4
The RETURNING data item. identifier-4:
v Must be defined in the DATA DIVISION
v Must not be reference-modified
v Is not changed if an EXCEPTION occurs
The data type of identifier-4 must be one of the types supported for Java
interoperation, as listed in “Interoperable data types for COBOL and Java”
on page 377.
See Conformance requirements for the RETURNING item for additional
requirements that apply to identifier-4.
If identifier-4 is specified and the target method is written in COBOL, the
target method must have a RETURNING phrase in its PROCEDURE
DIVISION header. When the target method returns, its return value is
assigned to identifier-4 using the rules for the SET statement if identifier-4 is
described with USAGE OBJECT REFERENCE; otherwise, the rules for the
MOVE statement are used.

The RETURNING data item is an output-only parameter. On entry to the called

method, the initial state of the PROCEDURE DIVISION RETURNING data item
has an undefined and unpredictable value. You must initialize the PROCEDURE
DIVISION RETURNING data item in the invoked method before you reference its
value. The value that is passed back to the invoker is the final value of the
PROCEDURE DIVISION RETURNING data item when the invoked method
returns.

See Managing local and global references in the Enterprise COBOL Programming Guide
for discussion of local and global object references as defined in Java. These
attributes affect the life-time of object references.

Usage note: The RETURN-CODE special register is not set by execution of

INVOKE statements.

Conformance requirements for the RETURNING item

For INVOKE statements that specify class-name-1 NEW, the RETURNING phrase is
required.

The returning item must be one of the following ones:

v A universal object reference
v An object reference specifying class-name-1

Chapter 20. PROCEDURE DIVISION statements 375

 v An object reference specifying a superclass of class-name-1

For INVOKE statements without the NEW phrase, the RETURNING item specified
in the method invocation and in the corresponding target method must satisfy the
following requirements:
v The presence or absence of a return value must be the same on the INVOKE
statement and in the target method.
v If the RETURNING item is not an object reference, the following rules apply:
– If the target method is implemented in COBOL, the returning item in the
INVOKE statement and the RETURNING item in the target method must
have an identical data description entry.
– If the target method is implemented in Java, the returning item in the
INVOKE statement must correspond to the Java type of the method result, as
described in “Interoperable data types for COBOL and Java” on page 377.
v If the RETURNING item is an object reference, the RETURNING item specified
in the INVOKE statement must be an object reference typed exactly to the class
of the returning item specified in the target method. That is, the class of
identifier-4 must not be a subclass or a superclass of the class of the returning
item in the target method.

Usage note: Adherence to conformance requirements for returning items is the

responsibility of the programmer. Conformance requirements are not verified by
the compiler.

ON EXCEPTION phrase

An exception condition occurs when the identified object or class does not support
a method with a signature that matches the signature of the method specified in
the INVOKE statement. When an exception condition occurs, one of the following
actions occurs:
v If the ON EXCEPTION phrase is specified, control is transferred to
imperative-statement-1.
v If the ON EXCEPTION phrase is not specified, a severity-3 Language
Environment condition is raised at run time.

NOT ON EXCEPTION phrase

If an exception condition does not occur (that is, the identified method is
supported by the specified object), control is transferred to the invoked method.
After control is returned from the invoked method, control is then transferred:
1. To imperative-statement-2, if the NOT ON EXCEPTION phrase is specified.
2. To the end of the INVOKE statement if the NOT ON EXCEPTION phrase is not
specified.

END-INVOKE phrase

This explicit scope terminator serves to delimit the scope of the INVOKE
statement. An INVOKE statement that is terminated by END-INVOKE, along with
its contained statements, becomes a unit that is treated as though it were an
imperative statement. It can be specified as an imperative statement in a
conditional statement; for example, in the exception phrase of another statement.

376 Enterprise COBOL for z/OS, V6.1 Language Reference

Interoperable data types for COBOL and Java
A subset of COBOL data types can be used for interoperation between COBOL and
Java.

You can specify the interoperable data types as arguments in COBOL INVOKE
statements and as the RETURNING item in COBOL INVOKE statements. Similarly,
you can pass these types as arguments from a Java method invocation expression
and receive them as parameters in the USING phrase or as the RETURNING item
in the PROCEDURE DIVISION header of a COBOL method.

The following table lists the primitive Java types and the COBOL data types that
are supported for interoperation and the correspondence between them.
Table 38. Interoperable Java and COBOL data types
Java data type COBOL data type
1
boolean Conditional variable and two condition-names of the form:
level-number data-name PIC X.
88 data-name-false VALUE X’00’.
88 data-name-true VALUE X’01’ THROUGH X’FF’.
byte Single-byte alphanumeric, PIC X or PIC A
short USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE
clause of the form S9(n), where 1 <= n <= 4
int USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE
clause of the form S9(n), where 5 <= n <= 9
long USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE
clause of the form S9(n), where 10 <= n <= 18
float2 USAGE COMP-1
2
double USAGE COMP-2
char Single-character national: PIC N USAGE NATIONAL
(an elementary data item of category national)
class types USAGE OBJECT REFERENCE class-name
(object references)

1. Enterprise COBOL interprets a PIC X argument or parameter as the Java boolean type
only when the PIC X data item is followed by exactly two condition-names of the form
shown. In all other cases, a PIC X argument or parameter is interpreted as the Java byte
type.
2. Java floating-point data is represented in IEEE binary floating-point, while Enterprise
COBOL uses the IBM hexadecimal floating-point representation. The representations are
automatically converted as necessary when Java methods are invoked from COBOL and
when COBOL methods are invoked from Java.

In addition to the primitive types, Java Strings and arrays of Java primitive types
can interoperate with COBOL. This requires specialized mechanisms provided by
the COBOL runtime system and the Java Native Interface (JNI).

In a Java program, to pass array data to COBOL or to receive array data from
COBOL, you declare the array types using the usual Java syntax. In the COBOL
program, you declare the array as an object reference that contains an instance of
one of the special classes provided for array support. Conversion between the Java
and COBOL types is automatic at the time of method invocation.

Chapter 20. PROCEDURE DIVISION statements 377

 In a Java program, to pass String data to COBOL or to receive String data from
COBOL, you declare the array types using the usual Java syntax. In the COBOL
program, you declare the String as an object reference that contains an instance of
the special jstring class. Conversion between the Java and COBOL types is
automatic at the time of method invocation. The following table lists the Java array
and String data types and the corresponding special COBOL data types.
Table 39. Interoperable COBOL and Java array and String data types
Java data type COBOL data type
boolean[ ] object reference jboooleanArray
byte[ ] object reference jbyteArray
short[ ] object reference jshortArray
int[ ] object reference jintArray
long[ ] object reference jlongArray
char[ ] object reference jcharArray
Object[ ] object reference jobjectArray
String object reference jstring

The following java array types are not currently supported:

Java data type COBOL data type

float[ ] object reference jfloatArray
double[ ] object reference jdoubleArray

You must code an entry in the repository paragraph for each special class that you
want to use, just as you do for other classes. For example, to use jstring, code the
following entry:
Configuration Section.
Repository.
Class jstring is "jstring".

Alternatively, for the String type, the COBOL repository entry can specify an
external class name of java.lang.String:
Repository.
Class jstring is "java.lang.String".

Callable services are provided by the Java Native Interface (JNI) for manipulating
the COBOL objects of these types in COBOL. For example, callable services can be
used to set COBOL alphanumeric or national data into a jstring object or to extract
data from a jstring object. For details on use of JNI callable services for these and
other purposes, see Accessing JNI services in the Enterprise COBOL Programming
Guide.

For details on repository entries for class definitions, see “REPOSITORY

paragraph” on page 125. For examples, see Example: external class-names and Java
packages in the Enterprise COBOL Programming Guide.

Miscellaneous argument types for COBOL and Java

There are miscellaneous cases of COBOL items that can be used as arguments in
an INVOKE statement.

378 Enterprise COBOL for z/OS, V6.1 Language Reference

The COBOL miscellaneous argument types and the corresponding Jave types are
listed in the following table.
Table 40. COBOL miscellaneous argument types and corresponding Java types
Corresponding Java
COBOL argument data type
Reference-modified item of usage display with length one byte
Reference-modified item of usage national with length one (either char
an elementary data item of usage national or a national group
item)
SHIFT-IN and SHIFT-OUT special registers byte
LINAGE-COUNTER special register when its usage is binary int
LENGTH OF special register int

The following table lists COBOL literal types that can be used as arguments in an
INVOKE statement, with the corresponding Java type.
Table 41. COBOL literal argument types and corresponding Java types
Corresponding Java
COBOL literal argument data type
Fixed-point numeric literal with no decimal positions and with int
nine digits or less
Floating-point numeric literal double
Figurative constant ZERO int
One-character alphanumeric literal byte
One-character national literal char
Symbolic character byte
Figurative constants SPACE, QUOTE, HIGH-VALUE, or byte
LOW-VALUE

Chapter 20. PROCEDURE DIVISION statements 379

| JSON GENERATE statement
| The JSON GENERATE statement converts data to JSON format.

| Format

| ►► JSON GENERATE identifier-1 FROM identifier-2 ►

| COUNT identifier-3
IN

| ► ►
|

NAME ▼ identifier-4 literal-1 SUPPRESS ▼ identifier-5

OF IS

| ► ►
| EXCEPTION imperative-statement-1
ON

| ► ►◄
| NOT EXCEPTION imperative-statement-2 END-JSON
ON
|
||

| identifier-1
| The receiving area for the generated JSON text. identifier-1 must reference
| one of the following items:
| v An elementary data item of category alphanumeric
| v An alphanumeric group item
| v An elementary data item of category national
| v A national group item
| When identifier-1 references a national group item, identifier-1 is processed
| as an elementary data item of category national. When identifier-1
| references an alphanumeric group item, identifier-1 is treated as though it
| were an elementary data item of category alphanumeric.
| identifier-1 must not be defined with the JUSTIFIED clause, and cannot be a
| function identifier. identifier-1 can be subscripted or reference modified.
| identifier-1 must not overlap identifier-2 or identifier-3.
| The generated JSON text is encoded in UTF-8 (CCSID 1208) unless
| identifier-1 is of category national, in which case it is encoded in UTF-16
| big-Endian (CCSID 1200). Conversion of the data values and NAME
| phrase literals is done according to the compiler CODEPAGE option in
| effect for the compilation. Conversion of original data names is always
| done using CCSID 1140.
| identifier-1 must be large enough to contain the generated JSON text.
| Typically, it should be from 2 to 3 times the size of identifier-2, depending
| on the lengths of the data-names within identifier-2. If identifier-1 is not
| large enough, an exception condition exists at the end of the JSON

380 Enterprise COBOL for z/OS, V6.1 Language Reference

| GENERATE statement. If the COUNT phrase is specified, identifier-3
| contains the number of character encoding units that were actually
| generated.
| identifier-2
| The group or elementary data item to be converted to JSON format.
| identifier-2 cannot be a function identifier or be reference modified, but it
| can be subscripted.
| identifier-2 must not overlap identifier-1 or identifier-3.
| The data description entry for identifier-2 must not contain a RENAMES
| clause.
| The following data items that are specified by identifier-2 are ignored by
| the JSON GENERATE statement:
| v Any subordinate unnamed elementary data items or elementary FILLER
| data items
| v Any slack bytes inserted for SYNCHRONIZED items
| v Any data item subordinate to identifier-2 that is defined with the
| REDEFINES clause or that is subordinate to such a redefining item
| v Any data item subordinate to identifier-2 that is defined with the
| RENAMES clause
| v Any group data item whose subordinate data items are all ignored
| All data items specified by identifier-2 that are not ignored according to the
| previous rules must satisfy the following conditions:
| v Each elementary data item must have a USAGE other than POINTER,
| FUNCTION-POINTER, PROCEDURE-POINTER, or OBJECT
| REFERENCE.
| v There must be at least one such elementary data item.
| v Each non-FILLER data-name must have a unique identifier within
| identifier-2.
| For example, consider the following data declaration:
| 01 STRUCT.
| 02 STAT PIC X(4).
| 02 IN-AREA PIC X(100).
| 02 OK-AREA REDEFINES IN-AREA.
| 03 FLAGS PIC X.
| 03 PIC X(3).
| 03 COUNTER USAGE COMP-5 PIC S9(9).
| 03 ASFNPTR REDEFINES COUNTER USAGE FUNCTION-POINTER.
| 03 UNREFERENCED PIC X(92).
| 02 NG-AREA1 REDEFINES IN-AREA.
| 03 FLAGS PIC X. 03 PIC X(3).
| 03 PTR USAGE POINTER.
| 03 ASNUM REDEFINES PTR USAGE COMP-5 PIC S9(9).
| 03 PIC X(92).
| 02 NG-AREA2 REDEFINES IN-AREA.
| 03 FN-CODE PIC X.
| 03 UNREFERENCED PIC X(3).
| 03 QTYONHAND USAGE BINARY PIC 9(5).
| 03 DESC USAGE NATIONAL PIC N(40).
| 03 UNREFERENCED PIC X(12).

| The following data items from the example can be specified as identifier-2:

Chapter 20. PROCEDURE DIVISION statements 381

| v STRUCT, of which subordinate data items STAT and IN-AREA would be
| converted to JSON format. (OK-AREA, NG-AREA1, and NG-AREA2 are ignored
| because they specify the REDEFINES clause.)
| v OK-AREA, of which subordinate data items FLAGS, COUNTER, and
| UNREFERENCED would be converted. (The item whose data description
| entry specifies 03 PIC X(3) is ignored because it is an elementary
| FILLER data item. ASFNPTR is ignored because it specifies the
| REDEFINES clause.)
| v Any of the elementary data items that are subordinate to STRUCT except:
| – ASFNPTR or PTR (disallowed usage)
| – UNREFERENCED OF NG-AREA2 (nonunique names for data items that are
| otherwise eligible)
| – Any FILLER data items
| The following data items cannot be specified as identifier-2:
| v NG-AREA1, because subordinate data item PTR specifies USAGE POINTER
| but does not specify the REDEFINES clause. (PTR would be ignored if it
| is defined with the REDEFINES clause.)
| v NG-AREA2, because subordinate elementary data items have the
| nonunique name UNREFERENCED.
| COUNT phrase
| If the COUNT phrase is specified, identifier-3 contains (after successful
| execution of the JSON GENERATE statement) the count of generated JSON
| character encoding units. If identifier-1 (the receiver) is of category national,
| the count is in double-bytes. Otherwise, the count is in bytes.
| identifier-3
| The data count field. Must be an integer data item defined without
| the symbol P in its picture string.
| identifier-3 must not overlap identifier-1, identifier-2, identifier-4, or
| identifier-5.
| NAME phrase
| Allows you to override the default JSON names derived from identifier-2 or
| its subordinate data items.
| identifier-4 must reference identifier-2 or one of its subordinate data items.
| It cannot be a function identifier and cannot be reference modified or
| subscripted. It must not specify any data item which is ignored by the
| JSON GENERATE statement. For more information about identifier-2, see
| the description of identifier-2. If identifier-4 is specified more than once in
| the NAME phrase, the last specification is used.
| literal-1 must be an alphanumeric or national literal containing the name
| to be generated in the JSON text corresponding to identifier-4.
| SUPPRESS phrase
| Allows you to identify and unconditionally exclude items that are
| subordinate to identifier-2, and thus selectively generate output for the
| JSON GENERATE statement. If the SUPPRESS phrase is specified,
| identifier-1 must be large enough to contain the generated JSON document
| before any suppression.
| identifier-5 must reference a data item that is subordinate to identifier-2 and
| that is not otherwise ignored by the operation of the JSON GENERATE
| statement. identifier-5 cannot be a function identifier and cannot be
| reference modified or subscripted. If identifier-5 specifies a group data item,

382 Enterprise COBOL for z/OS, V6.1 Language Reference

| that group data item and all data items that are subordinate to the group
| item are excluded. Duplicate specifications of identifier-5 are permitted.
| When the SUPPRESS phrase is specified, a group item subordinate to
| identifier-2 is excluded from the generated JSON text if all the eligible items
| subordinate to the group item are excluded. The outermost object that
| corresponds to identifier-2 itself is always generated, even if all the items
| subordinate to identifier-2 are excluded. In this case, the value generated for
| identifier-2 is an empty object, as follows:
| {"identifier-2":{}}
| For example, consider the following data declaration:
| 1 a.
| 2 b.
| 3 c occurs 0 to 2 depending j.
| 4 d pic x.
| 2 e pic x.

| If the ODO object j contains the value 2 and group a is populated with all
| ‘_’, the statement JSON GENERATE x FROM a (without the SUPPRESS phrase)
| produces the following JSON text:
| {"a":{"b":{"c":[{"d":"_"},{"d":"_"}]},"e":"_"}}

| Group item b is eliminated from the output if a SUPPRESS phrase specifies

| any one of data items b, c or d, resulting in the following JSON text:
| {"a":{"e":"_"}}

| As an example of complete recursive suppression, the statement JSON

| GENERATE x FROM a SUPPRESS b e produces:
| {"a":{}}

| JSON has an explicit representation of a table with no elements:

| {"table-name":[]}

| which is thus retained in the generated JSON text unless explicitly

| suppressed.
| For example if ODO object j contains the value 0 and thus table d has no
| occurrences, and group a is populated with all '_', the statement JSON
| GENERATE x FROM a produces the following JSON text:
| {"a":{"b":{"c":[]},"e":"_"}}

| Components of a zero-occurrence group table do not contribute any JSON

| text to the output. As a result, a SUPPRESS phrase that specified only d
| would have no effect on this generated output.
| Suppressing data items b or c, and e, which do contribute JSON text, has
| the same result as for non-zero occurrences of table c, illustrated above.
| ON EXCEPTION phrase
| An exception condition exists when an error occurs during generation of
| the JSON document, for example if identifier-1 is not large enough to
| contain the generated JSON document. In this case, JSON generation stops
| and the content of the receiver, identifier-1, is undefined. If the COUNT
| phrase is specified, identifier-3 contains the number of character positions
| that were actually generated.
| If the ON EXCEPTION phrase is specified, control is transferred to
| imperative-statement-1. If the ON EXCEPTION phrase is not specified, the

Chapter 20. PROCEDURE DIVISION statements 383

| NOT ON EXCEPTION phrase, if any, is ignored, and control is transferred
| to the end of the JSON GENERATE statement. Special register JSON-CODE
| contains an exception code, as detailed in JSON GENERATE exceptions in
| the Enterprise COBOL Programming Guide.
| NOT ON EXCEPTION phrase
| If an exception condition does not occur during generation of the JSON
| document, control is passed to imperative-statement-2, if specified, otherwise
| to the end of the JSON GENERATE statement. The ON EXCEPTION
| phrase, if specified, is ignored. Special register JSON-CODE contains zero
| after execution of the JSON GENERATE statement.
| END-JSON phrase
| This explicit scope terminator delimits the scope of the JSON GENERATE
| statement. END-JSON permits a conditional JSON GENERATE statement
| (that is, a JSON GENERATE statement that specifies the ON EXCEPTION
| or NOT ON EXCEPTION phrase) to be nested in another conditional
| statement.
| The scope of a conditional JSON GENERATE statement can be terminated
| by:
| v An END-JSON phrase at the same level of nesting
| v A separator period
| END-JSON can also be used with a JSON GENERATE statement that does
| not specify either the ON EXCEPTION or the NOT ON EXCEPTION
| phrase.
| For more information about explicit scope terminators, see “Delimited
| scope statements” on page 288.

| Nested JSON GENERATE statements

| When a given JSON GENERATE statement appears in imperative-statement-1 or
| imperative-statement-2 of another JSON GENERATE statement, that given JSON
| GENERATE statement is a nested JSON GENERATE statement.

| Nested JSON GENERATE statements are considered to be matched JSON

| GENERATE and END-JSON combinations, proceeding from left to right. Thus, any
| END-JSON phrase that is encountered is matched with the nearest preceding JSON
| GENERATE statement that has not been implicitly or explicitly terminated.

| Operation of JSON GENERATE

| The content of each eligible elementary data item within identifier-2 that has not
| been excluded from JSON generation according to a SUPPRESS phrase, is
| converted to character format in the resulting JSON text.

| Only the first definition of each storage area is processed. Redefinitions of data
| items are not included. Data items that are effectively defined by the RENAMES
| clause are also not included.

| A table item that has zero element occurrences is included in the JSON text as an
| empty array, such as {"name":[]}.

| Note: if the zero-occurrence table is a group item, its subordinate items do not
| appear in the JSON text and thus specifying them in the SUPPRESS phrase has no
| effect. See the description of the SUPPRESS phrase for more information.

384 Enterprise COBOL for z/OS, V6.1 Language Reference

| For information about the format conversion of elementary data, see “Format
| conversion of elementary data” and “Trimming of generated JSON data” on page
| 387.

| The JSON names are obtained from the NAME phrase if specified; otherwise by
| default they are derived from the data-names within identifier-2 as described in
| “JSON name formation” on page 387. The names of group items that contain the
| selected elementary items are retained as the names of parent JSON objects.

| No extra white space (new lines, indentation, and so forth) is inserted to make the
| generated JSON text more readable.

| If the receiving area specified by identifier-1 is not large enough to contain the
| resulting JSON text, an exception condition exists. See the description of the ON
| EXCEPTION phrase above for details.

| If identifier-1 is longer than the generated JSON text, only that part of identifier-1 in
| which JSON is generated is changed. The rest of identifier-1 contains the data that
| was present before this execution of the JSON GENERATE statement.

| To avoid referring to that data, either initialize identifier-1 to spaces before the
| JSON GENERATE statement or specify the COUNT phrase.

| If the COUNT phrase is specified, identifier-3 contains (after successful execution of

| the JSON GENERATE statement) the total number of character positions (UTF-16
| encoding units or bytes) that were generated. You can use identifier-3 as a reference
| modification length field to refer to the part of identifier-2 that contains the
| generated JSON text.

| After execution of the JSON GENERATE statement, special register JSON-CODE

| contains either zero, which indicates successful completion, or a nonzero exception
| code. For details, see JSON GENERATE exceptions in the Enterprise COBOL
| Programming Guide.

| A byte order mark is not generated for JSON texts.

| Format conversion of elementary data

| Elementary data items within identifier-2 are converted in the sequence of the
| following steps. Some of these steps are optional.

| Conversion to character format:

| Elementary data items are converted to character format depending on the type of
| the data item:
| v Data items of category alphabetic, alphanumeric, alphanumeric-edited, DBCS,
| external floating-point, national, national-edited, and numeric-edited are not
| converted, except as required to the correct Unicode encoding form.
| v Fixed-point numeric data items other than COMPUTATIONAL-5 (COMP-5)
| binary data items or binary data items compiled with the TRUNC(BIN) compiler
| option are converted as if they were moved to a numeric-edited item that has:
| – As many integer positions as the numeric item has, but with at least one
| integer position, possibly zero (0)

Chapter 20. PROCEDURE DIVISION statements 385

| – An explicit decimal point, if the numeric item has at least one decimal
| position; the decimal point is represented by a period regardless of whether
| the DECIMAL-POINT IS COMMA clause is specified in the
| SPECIAL-NAMES paragraph
| – The same number of decimal positions as the numeric item has
| – A leading '-' picture symbol if the data item is signed (has an S in its
| PICTURE clause)
| v COMPUTATIONAL-5 (COMP-5) binary data items or binary data items
| compiled with the TRUNC(BIN) compiler option are converted in the same way
| as the other fixed-point numeric items, except for the number of integer
| positions. The number of integer positions is computed depending on the
| number of '9' symbols in the picture character string as follows:
| – 5 minus the number of decimal places, if the data item has 1 to 4 '9' picture
| symbols
| – 10 minus the number of decimal places, if the data item has 5 to 9 '9' picture
| symbols
| – 20 minus the number of decimal places, if the data item has 10 to 18 '9'
| picture symbols
| v Internal floating-point data items are converted as if they were moved to a data
| item as follows:
| – For COMP-1: an external floating-point data item with PICTURE -9.9(8)E+99
| – For COMP-2: an external floating-point data item with PICTURE -9.9(17)E+99
| (illegal because of the number of digit positions)
| v External floating-point data items are converted as if they were moved to
| another external floating-point data item with the same precision and scale, and
| with:
| – A - sign for the mantissa.
| – An actual decimal point, indicated by a . PICTURE symbol.
| – A + sign for the exponent.
| For example, an external floating-point item defined with PICTURE
| -9(3)V9(5)E-99 would be converted as if it were moved to an external
| floating-point item defined with PICTURE -9(3).9(5)E+99.
| v Index data items are converted as if they were declared USAGE COMP-5
| PICTURE S9(9).

| Trimming:

| After any conversion to character format, leading and trailing spaces and leading
| zeroes are eliminated, as described under “Trimming of generated JSON data” on
| page 387.

| Conversion to the target encoding:

| If identifier-1 is a data item of category national, any nonnational values are

| converted to national format. Otherwise, all values are represented in UTF-8. The
| conversion is done according to the compiler CODEPAGE option in effect for the
| compilation.

| Escaping characters:

| The characters NX'0022' (") and NX'005C' (\) are escaped as \" and \\,
| respectively.

386 Enterprise COBOL for z/OS, V6.1 Language Reference

| For compactness and appearance, other common characters are represented by a
| two-character escape sequence as follows:
| NX’0008’ \b - backspace
| NX’0009’ \t - tab
| NX’000A’ \n - line feed
| NX’000C’ \f - form feed
| NX’000D’ \r - carriage return
| NX’0085’ \x - next line

| The remaining characters in the range NX'0000' through NX'001F' are escaped as
| \uhhhh, where "h" represents a hexadecimal digit 0 through F.

| Representation of out-of-range Unicode characters:

| Any remaining Unicode character that has a Unicode scalar value greater than
| NX'FFFF' is represented by a surrogate pair for national output, or a four-byte
| sequence for UTF-8 output. For example, the musical symbol G clef (U+1D11E) is
| represented in UTF-16 by the surrogate pair NX'D834' NX'DD1E', and in UTF-8 by
| the byte sequence x'F09D849E'.

| Trimming of generated JSON data

| Trimming is performed on data values after any conversion to character format.

| For more information about the conversion, see “Format conversion of elementary
| data” on page 385.

| For values converted from signed numeric values, the leading space is removed if
| the value is positive.

| For values converted from numeric items, leading zeroes (after any initial minus
| sign) up to but not including the digit immediately before the actual or implied
| decimal point are eliminated. Trailing zeroes after a decimal point are retained. For
| example:
| v -012.340 becomes -12.340
| v 0000.45 becomes 0.45
| v 0013 becomes 13
| v 0000 becomes 0

| Character values from data items of class alphabetic, alphanumeric, DBCS, and
| national have either trailing or leading spaces removed, depending on whether the
| corresponding data items have left (default) or right justification, respectively. That
| is, trailing spaces are removed from values whose corresponding data items do not
| specify the JUSTIFIED clause. Leading spaces are removed from values whose data
| items do specify the JUSTIFIED clause. If a character value consists solely of
| spaces, one space remains as the value after trimming is finished.

| JSON name formation

| In the JSON text that is generated from identifier-2, the names are obtained from
| the NAME phrase if specified; otherwise they are derived from the name of the
| data item specified by identifier-2 and from any eligible data-names that are
| subordinate to identifier-2. The exact mixed-case spelling of data-names from the
| data description entry is retained. The spellings from any references to data items
| (for example, in an OCCURS DEPENDING ON clause) are not used.

Chapter 20. PROCEDURE DIVISION statements 387

MERGE statement
The MERGE statement combines two or more identically sequenced files (that is,
files that have already been sorted according to an identical set of ascending or
descending keys) on one or more keys and makes records available in merged
order to an output procedure or output file.

A MERGE statement can appear anywhere in the PROCEDURE DIVISION except

in a declarative section.

The MERGE statement is not supported for programs compiled with the THREAD
compiler option.

Format

►► MERGE file-name-1 ▼ ASCENDING ▼ data-name-1 ►

ON DESCENDING KEY

► USING file-name-2 ▼ file-name-3 ►

SEQUENCE alphabet-name-1
COLLATING IS

► OUTPUT PROCEDURE procedure-name-1 ►◄

IS THROUGH procedure-name-2
THRU

GIVING ▼ file-name-4

file-name-1
The name given in the SD entry that describes the records to be merged.
No file-name can be repeated in the MERGE statement.
No pair of file-names in a MERGE statement can be specified in the same
SAME AREA, SAME SORT AREA, or SAME SORT-MERGE AREA clause.
However, any file-names in the MERGE statement can be specified in the
same SAME RECORD AREA clause.

When the MERGE statement is executed, all records contained in file-name-2,

file-name-3, ... , are accepted by the merge program and then merged according to
the keys specified.

388 Enterprise COBOL for z/OS, V6.1 Language Reference

ASCENDING/DESCENDING KEY phrase

This phrase specifies that records are to be processed in an ascending or

descending sequence (depending on the phrase specified), based on the specified
merge keys.
data-name-1
Specifies a KEY data item on which the merge will be based. Each such
data-name must identify a data item in a record associated with file-name-1.
The data-names following the word KEY are listed from left to right in the
MERGE statement in order of decreasing significance without regard to
how they are divided into KEY phrases. The leftmost data-name is the
major key, the next data-name is the next most significant key, and so
forth.
The following rules apply:
v A specific key data item must be physically located in the same position
and have the same data format in each input file. However, it need not
have the same data-name.
v If file-name-1 has more than one record description, the KEY data items
need be described in only one of the record descriptions.
v If file-name-1 contains variable-length records, all of the KEY data-items
must be contained within the first n character positions of the record,
where n equals the minimum records size specified for file-name-1.
v KEY data items must not contain an OCCURS clause or be subordinate
to an item that contains an OCCURS clause.
v KEY data items cannot be:
– Variably located
– Group items that contain variable-occurrence data items
– Category numeric described with usage NATIONAL (national decimal
type)
– Category external floating-point described with usage NATIONAL
(national floating-point)
– Category DBCS
v KEY data items can be qualified.
v KEY data items can be any of the following data categories:
– Alphabetic, alphanumeric, alphanumeric-edited
– Numeric (except numeric with usage NATIONAL)
– Numeric-edited (with usage DISPLAY or NATIONAL)
– Internal floating-point or display floating-point
– National or national-edited

The direction of the merge operation depends on the specification of the

ASCENDING or DESCENDING keywords as follows:
v When ASCENDING is specified, the sequence is from the lowest key value to
the highest key value.
v When DESCENDING is specified, the sequence is from the highest key value to
the lowest key value.

If the KEY data item is described with usage NATIONAL, the sequence of the KEY
values is based on the binary values of the national characters.

Chapter 20. PROCEDURE DIVISION statements 389

 When the COLLATING SEQUENCE phrase is not specified, the key comparisons
are performed according to the rules for comparison of operands in a relation
condition. For details, see “General relation conditions” on page 268.

When the COLLATING SEQUENCE phrase is specified, the indicated collating

sequence is used for key data items of alphabetic, alphanumeric,
alphanumeric-edited, external floating-point, and numeric-edited categories. For all
other key data items, the comparisons are performed according to the rules for
comparison of operands in a relation condition.

COLLATING SEQUENCE phrase

This phrase specifies the collating sequence to be used in alphanumeric
comparisons for the KEY data items in this merge operation.

The COLLATING SEQUENCE phrase has no effect for keys that are not alphabetic
or alphanumeric.
alphabet-name-1
Must be specified in the ALPHABET clause of the SPECIAL-NAMES
paragraph. Any one of the alphabet-name clause phrases can be specified,
with the following results:
STANDARD-1
The ASCII collating sequence is used for all alphanumeric
comparisons. (The ASCII collating sequence is shown in “US
English ASCII code page” on page 612.)
STANDARD-2
The 7-bit code defined in the International Reference Version of
ISO/IEC 646, 7-bit coded character set for information interchange is
used for all alphanumeric comparisons.
NATIVE
The EBCDIC collating sequence is used for all alphanumeric
comparisons. (The EBCDIC collating sequence is shown in
“EBCDIC collating sequence” on page 609.)
EBCDIC
The EBCDIC collating sequence is used for all alphanumeric
comparisons. (The EBCDIC collating sequence is shown in
“EBCDIC collating sequence” on page 609.)
literal
The collating sequence established by the specification of literals in
the ALPHABET-NAME clause is used for all alphanumeric
comparisons.

When the COLLATING SEQUENCE phrase is omitted, the PROGRAM

COLLATING SEQUENCE clause (if specified) in the OBJECT-COMPUTER
paragraph identifies the collating sequence to be used. When both the
COLLATING SEQUENCE phrase of the MERGE statement and the PROGRAM
COLLATING SEQUENCE clause of the OBJECT-COMPUTER paragraph are
omitted, the EBCDIC collating sequence is used.

USING phrase
file-name-2 , file-name-3 , ...
Specifies the input files.

390 Enterprise COBOL for z/OS, V6.1 Language Reference

During the MERGE operation, all the records on file-name-2, file-name-3, ... (that is,
the input files) are transferred to file-name-1. At the time the MERGE statement is
executed, these files must not be open. The input files are automatically opened,
read, and closed. If DECLARATIVE procedures are specified for these files for
input operations, the declaratives will be driven for errors if errors occur.

All input files must specify sequential or dynamic access mode and be described in
FD entries in the DATA DIVISION.

If file-name-1 contains variable-length records, the size of the records contained in

the input files (file-name-2, file-name-3, ...) must be neither less than the smallest
record nor greater than the largest record described for file-name-1. If file-name-1
contains fixed-length records, the size of the records contained in the input files
must not be greater than the largest record described for file-name-1. For more
information, see Sorting and merging files in the Enterprise COBOL Programming
Guide.

GIVING phrase
file-name-4 , ...
Specifies the output files.

When the GIVING phrase is specified, all the merged records in file-name-1 are
automatically transferred to the output files (file-name-4, ...).

All output files must specify sequential or dynamic access mode and be described
in FD entries in the DATA DIVISION.

If the output files (file-name-4, ...) contain variable-length records, the size of the
records contained in file-name-1 must be neither less than the smallest record nor
greater than the largest record described for the output files. If the output files
contain fixed-length records, the size of the records contained in file-name-1 must
not be greater than the largest record described for the output files. For more
information, see Sorting and merging files in the Enterprise COBOL Programming
Guide.

At the time the MERGE statement is executed, the output files (file-name-4, ...) must
not be open. The output files are automatically opened, read, and closed. If
DECLARATIVE procedures are specified for these files for output operations, the
declaratives will be driven for errors if errors occur.

OUTPUT PROCEDURE phrase

This phrase specifies the name of a procedure that is to select or modify output
records from the merge operation.
procedure-name-1
Specifies the first (or only) section or paragraph in the OUTPUT
PROCEDURE.
procedure-name-2
Identifies the last section or paragraph of the OUTPUT PROCEDURE.

The OUTPUT PROCEDURE can consist of any procedure needed to select, modify,
or copy the records that are made available one at time by the RETURN statement
in merged order from the file referenced by file-name-1. The range includes all
statements that are executed as the result of a transfer of control by CALL, EXIT,

Chapter 20. PROCEDURE DIVISION statements 391

 GO TO, PERFORM, and XML PARSE statements in the range of the output
procedure. The range also includes all statements in declarative procedures that are
executed as a result of the execution of statements in the range of the output
procedure. The range of the output procedure must not cause the execution of any
MERGE, RELEASE, or format 1 SORT statement.

If an output procedure is specified, control passes to it after the file referenced by

file-name-1 has been sequenced by the MERGE statement. The compiler inserts a
return mechanism at the end of the last statement in the output procedure and
when control passes the last statement in the output procedure, the return
mechanism provides the termination of the merge and then passes control to the
next executable statement after the MERGE statement. Before entering the output
procedure, the merge procedure reaches a point at which it can select the next
record in merged order when requested. The RETURN statements in the output
procedure are the requests for the next record.

The OUTPUT PROCEDURE phrase is similar to a basic PERFORM statement. For

example, if you name a procedure in an OUTPUT PROCEDURE, that procedure is
executed during the merging operation just as if it were named in a PERFORM
statement. As with the PERFORM statement, execution of the procedure is
terminated after the last statement completes execution. The last statement in an
OUTPUT PROCEDURE can be the EXIT statement (see “EXIT statement” on page
348).

MERGE special registers

The topic describes special registers of the MERGE statement.
SORT-CONTROL special register
You identify the sort control file (through which you can specify additional
options to the sort/merge function) with the SORT-CONTROL special
register.
If you use a sort control file to specify control statements, the values
specified in the sort control file take precedence over those in the other
SORT special registers.
For information, see “SORT-CONTROL” on page 22.
SORT-MESSAGE special register
For information, see “SORT-MESSAGE” on page 24. The special register
SORT-MESSAGE is equivalent to an option control statement keyword in
the sort control file.
SORT-RETURN special register
For information, see “SORT-RETURN” on page 24.

Segmentation considerations
If a MERGE statement is coded in a fixed segment, any output procedure
referenced by that MERGE statement must be either totally within a fixed segment
or wholly contained in a single independent segment.

If a MERGE statement is coded in an independent segment, any output procedure

referenced by that MERGE statement must be either totally within a fixed segment
or wholly contained within the same independent segment as that MERGE
statement.

392 Enterprise COBOL for z/OS, V6.1 Language Reference

MOVE statement
The MOVE statement transfers data from one area of storage to one or more other
areas.

Format 1: MOVE statement

►► MOVE identifier-1 TO ▼ identifier-2 ►◄

literal-1

Format 2: MOVE statement with CORRESPONDING phrase

►► MOVE CORRESPONDING identifier-1 TO identifier-2 ►◄

CORR

CORR is an abbreviation for, and is equivalent to, CORRESPONDING.

identifier-1 , literal-1
The sending area.
identifier-2
The receiving areas. identifier-2 must not reference an intrinsic function.

When format 1 is specified:

v All identifiers can reference alphanumeric group items, national group items, or
elementary items.
v When one of identifier-1 or identifier-2 references a national group item and the
other operand references an alphanumeric group item, the national group is
processed as a group item; in all other cases, the national group item is
processed as an elementary data item of category national.
v The data in the sending area is moved into the data item referenced by each
identifier-2 in the order in which the identifier-2 data items are specified in the
MOVE statement. See “Elementary moves” on page 394 and “Group moves” on
page 398 below.

When format 2 is specified:

v Both identifiers must be group items.
v A national group item is processed as a group item (and not as an elementary
data item of category national).
v Selected items in identifier-1 are moved to identifier-2 according to the rules for
the “CORRESPONDING phrase” on page 289. The results are the same as if
each pair of CORRESPONDING identifiers were referenced in a separate MOVE
statement.

Chapter 20. PROCEDURE DIVISION statements 393

 Data items described with the following types of usage cannot be specified in a
MOVE statement:
v INDEX
v POINTER
v FUNCTION-POINTER
v PROCEDURE-POINTER
v OBJECT REFERENCE

A data item defined with a usage of INDEX, POINTER, FUNCTION-POINTER,

PROCEDURE-POINTER, or OBJECT REFERENCE can be part of an alphanumeric
group item that is referenced in a MOVE CORRESPONDING statement; however,
no movement of data from those data items takes place.

The evaluation of the length of the sending or receiving area can be affected by the
DEPENDING ON phrase of the OCCURS clause (see “OCCURS clause” on page
195).

If the sending field (identifier-1) is reference-modified or subscripted, or is an

alphanumeric or national function-identifier, the reference-modifier, subscript, or
function is evaluated only once, immediately before data is moved to the first of
the receiving operands.

Any length evaluation, subscripting, or reference-modification associated with a

receiving field (identifier-2) is evaluated immediately before the data is moved into
that receiving field.

For example, the result of the statement:

MOVE A(B) TO B, C(B).

is equivalent to:
MOVE A(B) TO TEMP.
MOVE TEMP TO B.
MOVE TEMP TO C(B).

where TEMP is defined as an intermediate result item. The subscript B has changed
in value between the time that the first move took place and the time that the final
move to C(B) is executed.

For further information about intermediate results, see Appendix A. Intermediate

results and arithmetic precision in the Enterprise COBOL Programming Guide.

After execution of a MOVE statement, the sending fields contain the same data as
before execution.

Usage note: Overlapping operands in a MOVE statement can cause unpredictable

results.

Elementary moves
An elementary move is one in which the receiving item is an elementary data item
and the sending item is an elementary data item or a literal.

Valid operands belong to one of the following categories:

v Alphabetic: includes data items of category alphabetic and the figurative
constant SPACE

394 Enterprise COBOL for z/OS, V6.1 Language Reference

v Alphanumeric: includes the following items:
– Data items of category alphanumeric
– Alphanumeric functions
– Alphanumeric literals
– The figurative constant ALL alphanumeric-literal and all other figurative
constants (except NULL) when used in a context that requires an
alphanumeric sending item
v Alphanumeric-edited: includes data items of category alphanumeric-edited
v DBCS: includes data items of category DBCS, DBCS literals, and the figurative
constant ALL DBCS-literal.
v External floating-point: includes data items of category external floating point
(described with USAGE DISPLAY or USAGE NATIONAL) and floating-point
literals.
v Internal floating-point: includes data items of category internal floating-point
(defined as USAGE COMP-1 or USAGE COMP-2)
v National: includes the following items:
– National group items (treated as elementary item of category national)
– Data items of category national
– National literals
– National functions
– Figurative constants ZERO, SPACE, QUOTE, and ALL national-literal when
used in a context that requires a national sending item
v National-edited: includes data items of category national-edited
v Numeric: includes the following items:
– Data items of category numeric
– Numeric literals
– The figurative constant ZERO (when ZERO is moved to a numeric or
numeric-edited item).
v Numeric-edited: includes data items of category numeric-edited.

Elementary move rules

Any necessary conversion of data from one form of internal representation to
another takes place during the move, along with any specified editing in, or
de-editing implied by, the receiving item. The code page used for conversion to or
from alphanumeric characters is the one in effect for the CODEPAGE compiler
option when the source code was compiled.

The following rules outline the execution of valid elementary moves. When the
receiving field is:

Alphabetic:
v Alignment and any necessary space filling or truncation occur as described
under “Alignment rules” on page 170.
v If the size of the sending item is greater than the size of the receiving item,
excess characters on the right are truncated after the receiving item is filled.

Alphanumeric or alphanumeric-edited:
v If the sending item is a national decimal integer item, the sending data is
converted to usage DISPLAY and treated as though it were moved to a

Chapter 20. PROCEDURE DIVISION statements 395

 temporary data item of category alphanumeric with the same number of
character positions as the sending item. The resulting alphanumeric data item is
treated as the sending item.
v Alignment and any necessary space filling or truncation take place, as described
under “Alignment rules” on page 170.
v If the size of the sending item is greater than the size of the receiving item,
excess characters on the right are truncated after the receiving item is filled.
v If the initial sending item has an operational sign, the unsigned value is used. If
the operational sign occupies a separate character, that character is not moved,
and the size of the sending item is considered to be one less character than the
actual size.

DBCS:
v If the sending and receiving items are not the same size, the sending data is
either truncated on the right or padded with DBCS spaces on the right.

External floating-point:
v For a floating-point sending item, the floating-point value is converted to the
usage of the receiving external floating-point item (if different from the sending
item's representation).
v For other sending items, the numeric value is treated as though that value were
converted to internal floating-point and then converted to the usage of the
receiving external floating-point item.

Internal floating-point:
v When the category of the sending operand is not internal floating-point, the
numeric value of the sending item is converted to internal floating-point format.

National or national-edited:
v If the representation of the sending item is not national characters, the sending
data is converted to national characters and treated as though it were moved to
a temporary data item of category national of a length not to cause truncation or
padding. The resulting category national data item is treated as the sending data
item.
v If the representation of the sending item is national characters, the sending data
is used without conversion.
v Alignment and any necessary space filling or truncation take place as described
under “Alignment rules” on page 170. The programmer is responsible for
ensuring that multiple encoding units that together form a graphic character are
not split by truncation.
v If the sending item has an operational sign, the unsigned value is used. If the
operational sign occupies a separate character, that character is not moved, and
the size of the sending item is considered to be one less character than the actual
size.

Numeric or numeric-edited:
v Except when zeros are replaced because of editing requirements, alignment by
decimal point and any necessary zero filling take place, as described under
“Alignment rules” on page 170.
v If the receiving item is signed, the sign of the sending item is placed in the
receiving item, with any necessary sign conversion. If the sending item is
unsigned, a positive operational sign is generated for the receiving item.

396 Enterprise COBOL for z/OS, V6.1 Language Reference

 v If the receiving item is unsigned, no operational sign is generated for the
receiving item and the absolute value of the sending item is used in the move.
v When the category of the sending item is alphanumeric, alphanumeric-edited,
national, or national-edited, the data is moved as if the sending item were
described as an unsigned integer.
v When the sending item is floating-point, the data is first converted to either a
binary or internal decimal representation and is then moved.
v When the receiving item is numeric-edited, editing takes place as defined by the
picture character string or BLANK WHEN ZERO clause associated with the
receiving item.
v When the sending item is numeric-edited, the compiler de-edits the sending data
to establish the unedited value of the numeric-edited item (this value can be
signed). The unedited numeric value is used in the move to the receiving
numeric or numeric-edited data item.

Usage notes:
1. If the receiving item is of category alphanumeric, alphanumeric-edited,
numeric-edited, national, or national-edited and the sending field is numeric,
any digit positions described with picture symbol P in the sending item are
considered to have the value zero. Each P is counted in the size of the sending
item.
2. If the receiving item is numeric and the sending field is an alphanumeric literal,
a national literal, or an ALL literal, all characters of the literal must be numeric
characters.

Valid and invalid elementary moves

The table shows valid and invalid elementary moves for each category.

In the table:
v YES = Move is valid.
v NO = Move is invalid.
v Column headings indicate receiving item categories; row headings indicate
sending item categories.
Table 42. Valid and invalid elementary moves
Valid and
invalid Alpha- External Internal National,
elementary Alpha- Alpha- numeric Numeric- floating- floating- national-
moves betic numeric edited Numeric edited point point DBCS1 edited
Alphabetic and Yes Yes Yes No No No No No Yes
SPACE sending
item
Alphanumeric Yes Yes Yes Yes3 Yes3 Yes8 Yes8 No Yes
sending item2
Alphanumeric- Yes Yes Yes No No No No No Yes
edited sending
item
Numeric integer No Yes Yes Yes Yes Yes Yes No Yes
and ZERO
sending item4
Numeric No No No Yes Yes Yes Yes No No
noninteger
sending item5

Chapter 20. PROCEDURE DIVISION statements 397

Table 42. Valid and invalid elementary moves (continued)
Valid and
invalid Alpha- External Internal National,
elementary Alpha- Alpha- numeric Numeric- floating- floating- national-
moves betic numeric edited Numeric edited point point DBCS1 edited
Numeric-edited No Yes Yes Yes Yes Yes Yes No Yes
sending item
Floating-point No No No Yes Yes Yes Yes No No
sending item6
DBCS sending No No No No No No No Yes Yes
item7
National sending No No No Yes Yes Yes Yes No Yes
item9
National-edited No No No No No No No No Yes
sending item

1. Includes DBCS data items.

2. Includes alphanumeric literals.
3. Figurative constants and alphanumeric literals must consist only of numeric characters and will be treated as
numeric integer fields.
4. Includes integer numeric literals.
5. Includes noninteger numeric literals.
6. Includes floating-point literals, external floating-point data items (USAGE DISPLAY or USAGE NATIONAL),
and internal floating-point data items (USAGE COMP-1 or USAGE COMP-2).
7. Includes DBCS data-items, DBCS literals, and figurative constant SPACE.
8. Figurative constants and alphanumeric literals must consist only of numeric characters and will be treated as
numeric integer fields. The ALL literal cannot be used as a sending item.
9. Includes national data items, national literals, national functions, and figurative constants ZERO, SPACE,
QUOTE, and ALL national literal.

Moves involving file record areas

The successful execution of an OPEN statement for a given file makes the record
area for that file available. You can move data to or from the record description
entries associated with a file only when the file is in the open status.

Execution of an implicit or explicit CLOSE statement removes a file from open

status and makes the record area unavailable.

Group moves
A group move is any move in which an alphanumeric group item is a sending
item or a receiving item, or both.

The group moves are:

v A move to an alphanumeric group item from one of the following items:
– any elementary data item that is valid as a sending item in the MOVE
statement
– a national group item
– a literal
– a figurative constant
v A move from an alphanumeric group item to the following items:

398 Enterprise COBOL for z/OS, V6.1 Language Reference

 – any elementary data item that is valid as a receiving item in the MOVE
statement
– a national group item
– an alphanumeric group item

A group move is treated as though it were an alphanumeric-to-alphanumeric

elementary move, except that there is no conversion of data from one form of
internal representation to another. In a group move, the receiving area is filled
without consideration for the individual elementary items contained within either
the sending area or the receiving area, except as noted in the OCCURS clause. (See
“OCCURS clause” on page 195.)

Chapter 20. PROCEDURE DIVISION statements 399

MULTIPLY statement
The MULTIPLY statement multiplies numeric items and sets the values of data
items equal to the results.

Format 1: MULTIPLY statement

►► MULTIPLY identifier-1 BY ▼ identifier-2 ►

literal-1 ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-MULTIPLY
ON

In format 1, the value of identifier-1 or literal-1 is multiplied by the value of

identifier-2; the product is then placed in identifier-2. For each successive occurrence
of identifier-2, the multiplication takes place in the left-to-right order in which
identifier-2 is specified.

400 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 2: MULTIPLY statement with GIVING phrase

►► MULTIPLY identifier-1 BY identifier-2 ►

literal-1 literal-2

► GIVING ▼ identifier-3 ►
ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-MULTIPLY
ON

In format 2, the value of identifier-1 or literal-1 is multiplied by the value of

identifier-2 or literal-2. The product is then stored in the data items referenced by
identifier-3.

For all formats:

identifier-1 , identifier-2
Must name an elementary numeric item.
literal-1 , literal-2
Must be a numeric literal.

For format-2:
identifier-3
Must name an elementary numeric or numeric-edited item.

Floating-point data items and literals can be used anywhere a numeric data item or
literal can be specified.

When the ARITH(COMPAT) compiler option is in effect, the composite of operands

can contain a maximum of 30 digits. When the ARITH(EXTEND) compiler option
is in effect, the composite of operands can contain a maximum of 31 digits. For
more information, see “Arithmetic statement operands” on page 293 and the
details on arithmetic intermediate results, Appendix A. Intermediate results and
arithmetic precision in the Enterprise COBOL Programming Guide.

ROUNDED phrase

For formats 1 and 2, see “ROUNDED phrase” on page 291.

Chapter 20. PROCEDURE DIVISION statements 401

 SIZE ERROR phrases

For formats 1 and 2, see “SIZE ERROR phrases” on page 291.

END-MULTIPLY phrase

This explicit scope terminator serves to delimit the scope of the MULTIPLY
statement. END-MULTIPLY permits a conditional MULTIPLY statement to be
nested in another conditional statement. END-MULTIPLY can also be used with an
imperative MULTIPLY statement.

For more information, see “Delimited scope statements” on page 288.

402 Enterprise COBOL for z/OS, V6.1 Language Reference

OPEN statement
The OPEN statement initiates the processing of files. It also checks or writes labels,
or both.

Format 1: OPEN statement for sequential files

►► OPEN ▼ INPUT ▼ file-name-1 ►◄

(1)
REVERSED
(1)
NO REWIND
WITH

OUTPUT ▼ file-name-2
NO REWIND
WITH

I-O ▼ file-name-3

EXTEND ▼ file-name-4

Notes:
1 The REVERSED and WITH NO REWIND phrases are not valid for VSAM
files.

Format 2: OPEN statement for indexed and relative files

►► OPEN ▼ INPUT ▼ file-name-1 ►◄

OUTPUT ▼ file-name-2

I-O ▼ file-name-3

EXTEND ▼ file-name-4

Chapter 20. PROCEDURE DIVISION statements 403

 Format 3: OPEN statement for line-sequential files

►► OPEN ▼ INPUT ▼ file-name-1 ►◄

OUTPUT ▼ file-name-2

EXTEND ▼ file-name-4

The phrases INPUT, OUTPUT, I-O, and EXTEND specify the mode to be used for
opening the file. At least one of the phrases INPUT, OUTPUT, I-O, or EXTEND
must be specified with the OPEN keyword. The INPUT, OUTPUT, I-O, and
EXTEND phrases can appear in any order.
INPUT
Permits input operations.
OUTPUT
Permits output operations. This phrase can be specified when the file is
being created.
Do not specify OUTPUT for files that:
v Contain records. The file will be replaced by new data.
If the OUTPUT phrase is specified for a file that already contains
records, the data set must be defined as reusable and cannot have an
alternate index. The records in the file will be replaced by the new data
and any ALTERNATE RECORD KEY clause in the SELECT statement
will be ignored.
v Are defined with a DD dummy card. Unpredictable results can occur.
I-O Permits both input and output operations. The I-O phrase can be specified
only for files assigned to direct access devices.
The I-O phrase is not valid for line-sequential files.
EXTEND
Permits output operations that append to or create a file.
The EXTEND phrase is allowed for sequential access files only if the new
data is written in ascending sequence. The EXTEND phrase is allowed for
files that specify the LINAGE clause.
For QSAM files, do not specify the EXTEND phrase for a multiple file reel.
If you want to append to a file, but are unsure if the file exists, use the
SELECT OPTIONAL clause before opening the file in EXTEND mode. The
file will be created or appended to, depending on whether the file exists.
file-name-1, file-name-2, file-name-3, file-name-4
Designate a file upon which the OPEN statement is to operate. If more
than one file is specified, the files need not have the same organization or
access mode. Each file-name must be defined in an FD entry in the DATA
DIVISION and must not name a sort or merge file. The FD entry must be
equivalent to the information supplied when the file was defined.

404 Enterprise COBOL for z/OS, V6.1 Language Reference

 REVERSED
Valid only for sequential single-reel files. REVERSED is not valid for
VSAM files.
If the concept of reels has no meaning for the storage medium (for
example, a direct access device), the REVERSED and NO REWIND phrases
do not apply.
NO REWIND
Valid only for sequential single-reel files. It is not valid for VSAM files.

For information on file sizes, see Appendix B, “Compiler limits,” on page 605.

General rules
The topic shows general rules of the OPEN statement.
v If a file opened with the INPUT phrase is an optional file that is not available,
the OPEN statement sets the file position indicator to indicate that an optional
input file is not available.
v Execution of an OPEN INPUT or OPEN I-O statement sets the file position
indicator:
– For indexed files, to the characters with the lowest ordinal position in the
collating sequence associated with the file.
– For sequential and relative files, to 1.
v When the EXTEND phrase is specified, the OPEN statement positions the file
immediately after the last record written in the file. (The record with the highest
prime record key value for indexed files or relative key value for relative files is
considered the last record.) Subsequent WRITE statements add records as if the
file were opened OUTPUT. The EXTEND phrase can be specified when a file is
being created; it can also be specified for a file that contains records, or that has
contained records that have been deleted. For more information, see note 1 in
the “OPEN statement notes” on page 406 and SELECT OPTIONAL in the
“SELECT clause” on page 134.
v For VSAM files, if no records exist in the file, the file position indicator is set so
that the first format 1 READ statement executed results in an AT END condition.
v When NO REWIND is specified, the OPEN statement execution does not
reposition the file; prior to OPEN statement execution, the file must be
positioned at its beginning. When the NO REWIND phrase is specified (or when
both the NO REWIND and REVERSE phrases are omitted), file positioning is
specified with the LABEL parameter of the DD statement.
v When REVERSED is specified, OPEN statement execution positions the QSAM
file at its end. Subsequent READ statements make the data records available in
reversed order, starting with the last record.
When OPEN REVERSED is specified, the record format must be fixed.
v When the REVERSED, NO REWIND, or EXTEND phrases are not specified,
OPEN statement execution positions the file at its beginning.

If the PASSWORD clause is specified in the file-control entry, the password data
item must contain a valid password before the OPEN statement is executed. If a
valid password is not present, OPEN statement execution is unsuccessful.

Chapter 20. PROCEDURE DIVISION statements 405

 OPEN statement notes
The topic provides notes for the OPEN statement.

The notes are:

1. The successful execution of an OPEN statement determines the availability of
the file and results in that file being in open mode. A QSAM file is available if it
has a DD allocation and is physically present. A VSAM file is available if it has a
DD allocation, has been defined using VSAM access method services, and
contains records or has previously contained records. For more information
regarding file availability, see Opening a file (ESDS, KSDS, or RRDS) in the
Enterprise COBOL Programming Guide. The following table shows the results of
opening available and unavailable files.
Table 43. Availability of a file
Opened as File is available File is unavailable
INPUT Normal open Open is unsuccessful. (file status 35)
INPUT (optional Normal open Normal open; the first read causes the at end
file) condition or the invalid key condition. (file
status 05)
I-O Normal open Open is unsuccessful. (file status 35)
I-O (optional file) Normal open Open causes the file to be created. (file status
05)
OUTPUT Normal open; the Open causes the file to be created.
file contains no
records
EXTEND Normal open Open is unsuccessful. (file status 35)
EXTEND (optional Normal open Open causes the file to be created. (file status
file) 05)

2. The successful execution of the OPEN statement places the file in open status
and makes the associated record area available to the program.
3. The OPEN statement does not obtain or release the first data record.
4. You can move data to or from the record area only when the file is in open
status.
5. An OPEN statement must be successfully executed prior to the execution of
any of the permissible input-output statements, except a SORT or MERGE
statement with the USING or GIVING phrase. In the following table, an 'X'
indicates that the specified statement can be used with the open mode given at
the top of the column.
| 6. The VSAMOPENFS option affects the user file status reported from successful
| OPEN statements on VSAM files.
Table 44. Permissible statements for sequential files
Input open Output open Extend open
Statement mode mode I-O open mode mode
READ X X
WRITE X X
REWRITE X

406 Enterprise COBOL for z/OS, V6.1 Language Reference

In the following table, an 'X' indicates that the specified statement, used in the
access mode given for that row, can be used with the open mode given at the top
of the column.
Table 45. Permissible statements for indexed and relative files
File access Input open Output open I-O open Extend open
mode Statement mode mode mode mode
Sequential READ X X
WRITE X X
REWRITE X
START X X
DELETE X
Random READ X X
WRITE X X
REWRITE X
START
DELETE X
Dynamic READ X X
WRITE X X
REWRITE X
START X X
DELETE X

In the following table, an 'X' indicates that the specified statement can be used
with the open mode given at the top of the column.
Table 46. Permissible statements for line-sequential files
Input open Output open Extend open
Statement mode mode I-O open mode mode
READ X
WRITE X X
REWRITE

1. A file can be opened for INPUT, OUTPUT, I-O, or EXTEND (sequential and
line-sequential files only) in the same program. After the first OPEN statement
execution for a given file, each subsequent OPEN statement execution must be
preceded by a successful CLOSE file statement execution without the REEL or
UNIT phrase (for QSAM files only), or the LOCK phrase.
2. If the FILE STATUS clause is specified in the file-control entry, the associated
file status key is updated when the OPEN statement is executed.
3. If an OPEN statement is executed for a file that is already open, the
EXCEPTION/ERROR procedure (if specified) for this file is run.

Chapter 20. PROCEDURE DIVISION statements 407

 PERFORM statement
The PERFORM statement transfers control explicitly to one or more procedures
and implicitly returns control to the next executable statement after execution of
the specified procedures is completed.

Format 1: Basic PERFORM statement

►► PERFORM procedure-name-1 ►◄
THROUGH procedure-name-2
THRU
END-PERFORM
imperative-statement-1

procedure-name-1 , procedure-name-2
Must name a section or paragraph in the procedure division.
When both procedure-name-1 and procedure-name-2 are specified, if either is a
procedure-name in a declarative procedure, both must be procedure-names
in the same declarative procedure.
If procedure-name-1 is specified, imperative-statement-1 and the
END-PERFORM phrase must not be specified.
If procedure-name-1 is omitted, imperative-statement-1 and the
END-PERFORM phrase must be specified.
imperative-statement-1
The statements to be executed for an in-line PERFORM

Inline and out-of-line PERFORM statements

The PERFORM statement is an inline PERFORM statement, when procedure-name-1

is omitted.

The PERFORM statement is an out-of-line PERFORM statement, when

procedure-name-1 is specified.

An inline PERFORM must be delimited by the END-PERFORM phrase.

The inline and out-of-line formats cannot be combined. For example, if

procedure-name-1 is specified, imperative statements and the END-PERFORM
phrase must not be specified.

You can use the EXIT PERFORM statement to exit from an inline PERFORM
without using a GO TO statement or a PERFORM ... THROUGH statement. For
details, see “Format 5 (inline-perform)” on page 350.

| You can use the INLINE directive to decide whether a procedure referenced by
| PERFORM statements is eligible for inlining. For details, see “INLINE” on page
| 588.

408 Enterprise COBOL for z/OS, V6.1 Language Reference

END-PERFORM

Delimits the scope of the in-line PERFORM statement. Execution of an in-line

PERFORM is completed after the last statement contained within it has been
executed.

Chapter 20. PROCEDURE DIVISION statements 409

 Basic PERFORM statement
The procedures referenced in the basic PERFORM statement are executed once,
and control then passes to the next executable statement following the PERFORM
statement.

Note: A PERFORM statement must not cause itself to be executed. A recursive

PERFORM statement can cause unpredictable results.

An in-line PERFORM statement functions according to the same general rules as

an otherwise identical out-of-line PERFORM statement, except that statements
contained within the in-line PERFORM are executed in place of the statements
contained within the range of procedure-name-1 (through procedure-name-2, if
specified). Unless specifically qualified by the word in-line or the word out-of-line,
all the rules that apply to the out-of-line PERFORM statement also apply to the
in-line PERFORM.

Whenever an out-of-line PERFORM statement is executed, control is transferred to

the first statement of the procedure named procedure-name-1. Control is always
returned to the statement following the PERFORM statement. The point from
which this control is returned is determined as follows:
v If procedure-name-1 is a paragraph name and procedure-name-2 is not specified, the
return is made after the execution of the last statement of the procedure-name-1
paragraph.
v If procedure-name-1 is a section name and procedure-name-2 is not specified, the
return is made after the execution of the last statement of the last paragraph in
the procedure-name-1 section.
v If procedure-name-2 is specified and it is a paragraph name, the return is made
after the execution of the last statement of the procedure-name-2 paragraph.
v If procedure-name-2 is specified and it is a section name, the return is made after
the execution of the last statement of the last paragraph in the procedure-name-2
section.

The only necessary relationship between procedure-name-1 and procedure-name-2 is

that a consecutive sequence of operations is executed, beginning at the procedure
named by procedure-name-1 and ending with the execution of the procedure named
by procedure-name-2.

PERFORM statements can be specified within the performed procedure. If there

are two or more logical paths to the return point, then procedure-name-2 can name a
paragraph that consists only of an EXIT statement; all the paths to the return point
must then lead to this paragraph.

When the performed procedures include another PERFORM statement, the

sequence of procedures associated with the embedded PERFORM statement must
be totally included in or totally excluded from the performed procedures of the
first PERFORM statement. That is, an active PERFORM statement whose execution
point begins within the range of performed procedures of another active
PERFORM statement must not allow control to pass through the exit point of the
other active PERFORM statement. However, two or more active PERFORM
statements can have a common exit.

When control passes to the sequence of procedures by means other than a

PERFORM statement, control passes through the exit point to the next executable
statement, as if no PERFORM statement referred to these procedures.

410 Enterprise COBOL for z/OS, V6.1 Language Reference

 The following figure illustrates valid sequences of execution for PERFORM
statements.

This figure illustrates valid PERFORM statement execution sequences. Letters of

the alphabet are used to represent procedures. The following examples are shown:
1. PERFORM a THRU m. The sequence of procedures is a, d, f, j, and m. Procedure d
contains PERFORM f THRU j. In this sequence, procedures f THRU j are nested
within the range of procedures a THRU m.
2. PERFORM a THRU m. The sequence of procedures is a, d, h, m, f, and j. Procedure
d contains PERFORM f THRU j. In this sequence, procedures f THRU j are wholly
outside the range of procedures a THRU m.
3. PERFORM a THRU m. The sequence of procedures is a, f, m, j, and d. Procedure d
contains PERFORM f THRU j. In this sequence, the two PERFORM statements
have overlapping range; f thru j overlaps a thru m.
4. PERFORM a THRU m. The sequence of procedures is a, d, f, j, and m. Procedure m
terminates with an EXIT statement. Procedure d contains PERFORM d THRU m. In
this sequence, both PERFORM statements share the same exit point.

PERFORM with TIMES phrase

The procedures referred to in the TIMES phrase of the PERFORM statement are
executed the number of times specified by the value in identifier-1 or integer-1, up
to a maximum of 999,999,999 times. Control then passes to the next executable
statement following the PERFORM statement.

Chapter 20. PROCEDURE DIVISION statements 411

 Format 2: PERFORM statement with TIMES phrase

►► PERFORM ►

► procedure-name-1 identifier-1 TIMES ►◄

THROUGH procedure-name-2 integer-1
THRU
identifier-1 TIMES END-PERFORM
integer-1 imperative-statement-1

If procedure-name-1 is specified, imperative-statement-1 and the END-PERFORM

phrase must not be specified.
identifier-1
Must name an integer item.
If identifier-1 is zero or a negative number at the time the PERFORM
statement is initiated, control passes to the statement following the
PERFORM statement.
After the PERFORM statement has been initiated, any change to identifier-1
has no effect in varying the number of times the procedures are initiated.
integer-1
Can be a positive signed integer.

PERFORM with UNTIL phrase

In the UNTIL phrase format, the procedures referred to are performed until the
condition specified by the UNTIL phrase is true. Control is then passed to the next
executable statement following the PERFORM statement.

Format 3: PERFORM statement with UNTIL phrase

►► PERFORM ►

► procedure-name-1 THROUGH procedure-name-2 phrase 1 ►◄

THRU
phrase 1 END-PERFORM
imperative-statement-1

phrase 1:

UNTIL condition-1
TEST BEFORE
WITH AFTER

If procedure-name-1 is specified, imperative-statement-1 and the END-PERFORM

phrase must not be specified.
condition-1
Can be any condition described under “Conditional expressions” on page
264

412 Enterprise COBOL for z/OS, V6.1 Language Reference

 264. If the condition is true at the time the PERFORM statement is
initiated, the specified procedures are not executed.
Any subscripting associated with the operands specified in condition-1 is
evaluated each time the condition is tested.

If the TEST BEFORE phrase is specified or assumed, the condition is tested before
any statements are executed (corresponds to DO WHILE).

If the TEST AFTER phrase is specified, the statements to be performed are

executed at least once before the condition is tested (corresponds to DO UNTIL).

In either case, if the condition is true, control is transferred to the next executable
statement following the end of the PERFORM statement. If neither the TEST
BEFORE nor the TEST AFTER phrase is specified, the TEST BEFORE phrase is
assumed.

PERFORM with VARYING phrase

The VARYING phrase increases or decreases the value of one or more identifiers or
index-names, according to certain rules.

For more information, see “Varying phrase rules” on page 419.

The format-4 VARYING phrase PERFORM statement can serially search an entire
seven-dimensional table.

Chapter 20. PROCEDURE DIVISION statements 413

 Format 4: PERFORM statement with VARYING phrase

►► PERFORM procedure-name-1 phrase 1 phrase 2 ►◄

THROUGH procedure-name-2
THRU
phrase 1 END-PERFORM
imperative-statement-1

phrase 1:

VARYING identifier-2 FROM identifier-3 BY ►

TEST BEFORE index-name-1 index-name-2
WITH AFTER literal-1

► identifier-4 UNTIL condition-1

literal-2

phrase 2:

▼ AFTER identifier-5 FROM identifier-6 phrase 3

index-name-3 index-name-4
literal-3

phrase 3:

BY identifier-7 UNTIL condition-2

literal-4

If procedure-name-1 is specified, imperative-statement-1 and the END-PERFORM

phrase must not be specified. If procedure-name-1 is omitted, the AFTER phrase
must not be specified.
identifier-2 through identifier-7
Must name a numeric elementary item.
literal-1 through literal-4
Must represent a numeric literal.
condition-1, condition-2
Can be any condition described under “Conditional expressions” on page
264. If the condition is true at the time the PERFORM statement is
initiated, the specified procedures are not executed.
After the conditions specified in the UNTIL phrase are satisfied, control is
passed to the next executable statement following the PERFORM
statement.
If any of the operands specified in condition-1 or condition-2 is subscripted,
reference modified, or is a function-identifier, the subscript,
reference-modifier, or function is evaluated each time the condition is
tested.

414 Enterprise COBOL for z/OS, V6.1 Language Reference

Floating-point data items and literals can be used anywhere a numeric data item or
literal can be specified.

When TEST BEFORE is indicated, all specified conditions are tested before the first
execution, and the statements to be performed are executed, if at all, only when all
specified tests fail. When TEST AFTER is indicated, the statements to be performed
are executed at least once, before any condition is tested.

If neither the TEST BEFORE nor the TEST AFTER phrase is specified, the TEST
BEFORE phrase is assumed.

Varying identifiers
The way in which operands are increased or decreased depends on the number of
variables specified. In the discussion, every reference to identifier-n refers equally to
index-name-n (except when identifier-n is the object of the BY phrase).

If identifier-2 or identifier-5 is subscripted, the subscripts are evaluated each time the
content of the data item referenced by the identifier is set or augmented. If
identifier-3, identifier-4, identifier-6, or identifier-7 is subscripted, the subscripts are
evaluated each time the content of the data item referenced by the identifier is
used in a setting or an augmenting operation.

The following figure illustrates the logic of the PERFORM statement when an
identifier is varied with TEST BEFORE.

The following figure illustrates the logic of the PERFORM statement when an
identifier is varied with TEST AFTER.

Chapter 20. PROCEDURE DIVISION statements 415

 Varying two identifiers:

The topic lists steps of varying two identifiers.

PERFORM PROCEDURE-NAME-1 THROUGH PROCEDURE-NAME-2
VARYING IDENTIFIER-2 FROM IDENTIFIER-3
BY IDENTIFIER-4 UNTIL CONDITION-1
AFTER IDENTIFIER-5 FROM IDENTIFIER-6
BY IDENTIFIER-7 UNTIL CONDITION-2
1. identifier-2 and identifier-5 are set to their initial values, identifier-3 and
identifier-6, respectively.
2. condition-1 is evaluated as follows:
a. If it is false, steps 3 through 7 are executed.
b. If it is true, control passes directly to the statement following the PERFORM
statement.
3. condition-2 is evaluated as follows:
a. If it is false, steps 4 through 6 are executed.
b. If it is true, identifier-2 is augmented by identifier-4, identifier-5 is set to the
current value of identifier-6, and step 2 is repeated.
4. procedure-name-1 and procedure-name-2 are executed once (if specified).
5. identifier-5 is augmented by identifier-7.
6. Steps 3 through 5 are repeated until condition-2 is true.
7. Steps 2 through 6 are repeated until condition-1 is true.

At the end of PERFORM statement execution:

v identifier-5 contains the current value of identifier-6.
v identifier-2 has a value that exceeds the last-used setting by the increment or
decrement value (unless condition-1 was true at the beginning of PERFORM
statement execution, in which case, identifier-2 contains the current value of
identifier-3).

The following figure illustrates the logic of the PERFORM statement when two
identifiers are varied with TEST BEFORE.

416 Enterprise COBOL for z/OS, V6.1 Language Reference

The following figure illustrates the logic of the PERFORM statement when two
identifiers are varied with TEST AFTER.

Chapter 20. PROCEDURE DIVISION statements 417

 Varying three identifiers:

The topic lists steps of varying three identifiers.

PERFORM PROCEDURE-NAME-1 THROUGH PROCEDURE-NAME-2
VARYING IDENTIFIER-2 FROM IDENTIFIER-3
BY IDENTIFIER-4 UNTIL CONDITION-1
AFTER IDENTIFIER-5 FROM IDENTIFIER-6
BY IDENTIFIER-7 UNTIL CONDITION-2
AFTER IDENTIFIER-8 FROM IDENTIFIER-9
BY IDENTIFIER-10 UNTIL CONDITION-3

The actions are the same as those for two identifiers, except that identifier-8 goes
through the complete cycle each time that identifier-5 is augmented by identifier-7,
which, in turn, goes through a complete cycle each time that identifier-2 is varied.

At the end of PERFORM statement execution:

v identifier-5 and identifier-8 contain the current values of identifier-6 and identifier-9,
respectively.
v identifier-2 has a value exceeding its last-used setting by one
increment/decrement value (unless condition-1 was true at the beginning of
PERFORM statement execution, in which case identifier-2 contains the current
value of identifier-3).

Varying more than three identifiers:

You can produce analogous PERFORM statement actions to the previous example
with the addition of up to four AFTER phrases.

418 Enterprise COBOL for z/OS, V6.1 Language Reference

Varying phrase rules:

There are certain rules that apply to this phrase, no matter how many variables are
specified.

The rules are:

v In the VARYING or AFTER phrases, when an index-name is specified:
– The index-name is initialized and incremented or decremented according to
the rules under “INDEX phrase” on page 238. (See also “SET statement” on
page 441.)
– In the associated FROM phrase, an identifier must be described as an integer
and have a positive value; a literal must be a positive integer.
– In the associated BY phrase, an identifier must be described as an integer; a
literal must be a nonzero integer.
v In the FROM phrase, when an index-name is specified:
– In the associated VARYING or AFTER phrase, an identifier must be described
as an integer. It is initialized as described in the SET statement.
– In the associated BY phrase, an identifier must be described as an integer and
have a nonzero value; a literal must be a nonzero integer.
v In the BY phrase, identifiers and literals must have nonzero values.
v Changing the values of identifiers or index-names in the VARYING, FROM, and
BY phrases during execution changes the number of times the procedures are
executed.

Chapter 20. PROCEDURE DIVISION statements 419

READ statement
For sequential access, the READ statement makes the next logical record from a file
available to the object program. For random access, the READ statement makes a
specified record from a direct-access file available to the object program.

When the READ statement is executed, the associated file must be open in INPUT
or I-O mode.

Format 1: READ statement for sequential retrieval

►► READ file-name-1 ►
NEXT RECORD INTO identifier-1

► ►
END imperative-statement-1
AT

► ►◄
NOT END imperative-statement-2 END-READ
AT

Format 2: READ statement for random retrieval

►► READ file-name-1 ►
RECORD INTO identifier-1

► ►
KEY data-name-1
IS

► ►
INVALID imperative-statement-3
KEY

► ►◄
NOT INVALID imperative-statement-4 END-READ
KEY

file-name-1
Must be defined in a DATA DIVISION FD entry.
NEXT RECORD
Reads the next record in the logical sequence of records. NEXT is optional
when the access mode is sequential, and has no effect on READ statement
execution.
You must specify the NEXT RECORD phrase to retrieve records
sequentially from files in dynamic access mode.

420 Enterprise COBOL for z/OS, V6.1 Language Reference

INTO identifier-1
identifier-1 is the receiving field.
identifier-1 must be a valid receiving field for the selected sending record
description entry in accordance with the rules of the MOVE statement.
The record areas associated with file-name-1 and identifier-1 must not be the
same storage area.
When there is only one record description associated with file-name-1 or all
the records and the data item referenced by identifier-1 describe an
elementary alphanumeric item or an alphanumeric group item, the result
of the execution of a READ statement with the INTO phrase is equivalent
to the application of the following rules in the order specified:
v The execution of the same READ statement without the INTO phrase.
v The current record is moved from the record area to the area specified
by identifier-1 according to the rules for the MOVE statement without the
CORRESPONDING phrase. The size of the current record is determined
by rules specified for the RECORD clause. If the file description entry
contains a RECORD IS VARYING clause, the implied move is a group
move. The implied MOVE statement does not occur if the execution of
the READ statement was unsuccessful. Any subscripting or reference
modification associated with identifier-1 is evaluated after the record has
been read and immediately before it is moved to the data item. The
record is available in both the record area and the data item referenced
by identifier-1.
When there are multiple record descriptions associated with file-name-1 and
they do not all describe an alphanumeric group item or elementary
alphanumeric item, the following rules apply:
1. If the file referenced by file-name-1 is described as containing
variable-length records, or as a QSAM file with RECORDING MODE 'S'
or 'U', a group move will take place.
2. If the file referenced by file-name-1 is described as containing
fixed-length records, a move will take place according to the rules for a
MOVE statement using, as a sending field description, the record that
specifies the largest number of character positions. If more than one
such record exists, the sending field record selected will be the one
among those records that appears first under the description of
file-name-1.

KEY IS phrase

The KEY IS phrase can be specified only for indexed files. data-name-1 must
identify a record key associated with file-name-1. data-name-1 can be qualified; it
cannot be subscripted.

AT END phrases

For sequential access, both the AT END phrase and an applicable

EXCEPTION/ERROR procedure can be omitted.

For information about at-end condition processing, see AT END condition.

Chapter 20. PROCEDURE DIVISION statements 421

 INVALID KEY phrases

Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure

can be omitted.

For information about INVALID KEY phrase processing, see “Invalid key
condition” on page 299.

END-READ phrase

This explicit scope terminator serves to delimit the scope of the READ statement.
END-READ permits a conditional READ statement to be nested in another
conditional statement. END-READ can also be used with an imperative READ
statement. For more information, see “Delimited scope statements” on page 288.

Processing files with variable-length records or multiple

record descriptions
If more than one record description entry is associated with file-name-1, those
records automatically share the same storage area; that is, they are implicitly
redefined. After a READ statement is executed, only those data items within the
range of the current record are replaced; data items stored beyond that range are
undefined. The following example illustrates this concept.

If the length of the current record that is read is less than the minimum size
specified by the record description entries for file-name-1, the portion of the record
area which is to the right of the last valid character read is undefined. If the length
of the current record exceeds the record description entries for file-name-1, the
record is truncated on the right to the maximum record definition size.

In either of the previous cases, the READ statement is successful, and the I-O
status is set to either 00 (hiding the record length conflict condition) or 04
(indicating that a record length conflict has occurred), depending on the VLR
compiler option setting. If compiler option VLR(COMPAT) is in effect, the I-O
status would be set to 00.

For more information about the VLR compiler option, see VLR in the Enterprise
COBOL Programming Guide.

The following example shows two record areas of different sizes in an FD. When a
shorter record is read, the content of the remaining record area is undefined.
FD INPUT-FILE LABEL RECORD OMITTED.
01 RECORD-1 PICTURE X(30).
01 RECORD-2 PICTURE X(20).

Content of input area when READ statement is executed:

ABCDEFGHIJKLMNOPQRSTUVWXYZ1234

Content of record being read in (RECORD-2):

01234567890123456789

Content of input area after READ statement is executed:

01234567890123456789??????????

The "?" characters are undefined characters in input area.

422 Enterprise COBOL for z/OS, V6.1 Language Reference

Sequential access mode
Format 1 must be used for all files in sequential access mode.

Execution of a format-1 READ statement retrieves the next logical record from the
file. The next record accessed is determined by the file organization.

Sequential files
The NEXT RECORD is the next record in a logical sequence of records. The NEXT
phrase need not be specified; it has no effect on READ statement execution.

If SELECT OPTIONAL is specified in the file-control entry for this file, and the file
is unavailable during this execution of the object program, execution of the first
READ statement causes an at-end condition; however, since no file is available, the
system-defined end-of-file processing is not performed.
AT END condition
If the file position indicator indicates that no next logical record exists, or
that an optional input file is not available, at-end condition processing
occurs in a specific order.
The order is:
1. A value derived from the setting of the file position indicator is placed
into the I-O status associated with file-name-1 to indicate the at-end
condition.
2. If the AT END phrase is specified in the statement causing the
condition, control is transferred to imperative-statement-1 in the AT END
phrase. Any USE AFTER STANDARD EXCEPTION procedure
associated with file-name-1 is not executed.
3. If the AT END phrase is not specified and an applicable USE AFTER
STANDARD EXCEPTION procedure exists, the procedure is executed.
Return from that procedure is to the next executable statement
following the end of the READ statement.
Both the AT END phrase and an applicable EXCEPTION/ERROR
procedure can be omitted.
When the at-end condition occurs, execution of the READ statement is
unsuccessful. The contents of the associated record area are undefined
and the file position indicator is set to indicate that no valid next record
has been established.
For QSAM files, attempts to access or move data into the record area
after an unsuccessful read can result in a protection exception.
If an at-end condition does not occur during the execution of a READ
statement, the AT END phrase is ignored, if specified, and the following
actions occur:
1. The file position indicator is set and the I-O status associated with
file-name-1 is updated.
2. If an exception condition that is not an at-end condition exists, control
is transferred to the end of the READ statement after the execution of
any USE AFTER STANDARD EXCEPTION procedure applicable to
file-name-1.
If no USE AFTER STANDARD EXCEPTION procedure is specified,
control is transferred to the end of the READ statement or to
imperative-statement-2, if specified.

Chapter 20. PROCEDURE DIVISION statements 423

 3. If no exception condition exists, the record is made available in the
record area and any implicit move resulting from the presence of an
INTO phrase is executed. Control is transferred to the end of the READ
statement or to imperative-statement-2, if specified. In the latter case,
execution continues according to the rules for each statement specified
in imperative-statement-2. If a procedure branching or conditional
statement which causes explicit transfer of control is executed, control
is transferred in accordance with the rules for that statement; otherwise,
upon completion of the execution of imperative-statement-2, control is
transferred to the end of the READ statement.
After the unsuccessful execution of a READ statement, the contents of the
associated record area are undefined and the file position indicator is set to
indicate that no valid next record has been established. Attempts to access
or move data into the record area after an unsuccessful read can result in a
protection exception.

Indexed or relative files

The NEXT RECORD is the next logical record in the key sequence.

For indexed files, the key sequence is the sequence of ascending values of the
current key of reference. For relative files, the key sequence is the sequence of
ascending values of relative record numbers for records that exist in the file.

Before the READ statement is executed, the file position indicator must have been
set by a successful OPEN, START, or READ statement. When the READ statement
is executed, the record indicated by the file position indicator is made available if it
is still accessible through the path indicated by the file position indicator.

If the record is no longer accessible (because it has been deleted, for example), the
file position indicator is updated to point to the next existing record in the file, and
that record is made available.

For files in sequential access mode, the NEXT phrase need not be specified.

For files in dynamic access mode, the NEXT phrase must be specified for
sequential record retrieval.
AT END condition
This condition exists when the file position indicator indicates that no next
logical record exists or that an optional input file is not available. The same
procedure occurs as for sequential files (see AT END condition).
If neither an at-end nor an invalid key condition occurs during the
execution of a READ statement, the AT END or the INVALID KEY phrase
is ignored, if specified. The same actions occur as when the at-end
condition does not occur with sequential files (see AT END condition).
Sequentially accessed indexed files
When an ALTERNATE RECORD KEY with DUPLICATES is the key of
reference, file records with duplicate key values are made available in the
order in which they were placed in the file.
Sequentially accessed relative files

424 Enterprise COBOL for z/OS, V6.1 Language Reference

 If the RELATIVE KEY clause is specified for this file, READ statement
execution updates the RELATIVE KEY data item to indicate the relative
record number of the record being made available.

Random access mode

Format 2 must be specified for indexed and relative files in random access mode,
and also for files in the dynamic access mode when record retrieval is random.

Execution of the READ statement depends on the file organization, as explained in

the following sections.

Indexed files

Execution of a format-2 READ statement causes the value of the key of reference to
be compared with the value of the corresponding key data item in the file records,
until the first record having an equal value is found. The file position indicator is
positioned to this record, which is then made available. If no record can be so
identified, an INVALID KEY condition exists, and READ statement execution is
unsuccessful. (See “Invalid key condition” on page 299 for details of the invalid
key condition.)

If the KEY phrase is not specified, the prime RECORD KEY becomes the key of
reference for this request. When dynamic access is specified, the prime RECORD
KEY is also used as the key of reference for subsequent executions of sequential
READ statements, until a different key of reference is established.

When the KEY phrase is specified, data-name-1 becomes the key of reference for
this request. When dynamic access is specified, this key of reference is used for
subsequent executions of sequential READ statements, until a different key of
reference is established.

Relative files

Execution of a format-2 READ statement sets the file position indicator pointer to
the record whose relative record number is contained in the RELATIVE KEY data
item, and makes that record available.

If the file does not contain such a record, the INVALID KEY condition exists, and
READ statement execution is unsuccessful. (See “Invalid key condition” on page
299 for details of the invalid key condition).

The KEY phrase must not be specified for relative files.

Dynamic access mode

For files with indexed or relative organization, dynamic access mode can be
specified in the file-control entry. In dynamic access mode, either sequential or
random record retrieval can be used, depending on the format used.

Format 1 with the NEXT phrase must be specified for sequential retrieval. All other
rules for sequential access apply.

READ statement notes

This topic provides notes on the READ statement.

Chapter 20. PROCEDURE DIVISION statements 425

 v If the FILE-STATUS clause is specified in the file-control entry, the associated file
status key is updated when the READ statement is executed.
v After unsuccessful READ statement execution, the contents of the associated
record area and the value of the file position indicator are undefined. Attempts
to access or move data into the record area after an unsuccessful read can result
in a protection exception.
v If the number of character positions in a record is less than the minimum size
specified by the record description entries for file-name-1, after a READ statement
is executed, the portion of the record area that is to the right of the last valid
character read is undefined. If the number of character positions in a record
exceed the maximum size specified by the record description entries for
file-name-1, after a READ statement is executed, the record is truncated on the
right to the maximum size.
In either of these cases, the READ statement is successful and the I-O status is
set to either 00 (hiding the record length conflict condition) or 04 (indicating that
a record length conflict has occurred), depending on the VLR compiler option
setting.
– When the VLR(COMPAT) compiler option is in effect, the status value of 00 is
set.
– When the VLR(STANDARD) compiler option is in effect, the status value of
04 is set.
For more information about the VLR compiler option, see VLR in the Enterprise
COBOL Programming Guide.

426 Enterprise COBOL for z/OS, V6.1 Language Reference

RELEASE statement
The RELEASE statement transfers records from an input/output area to the initial
phase of a sorting operation.

The RELEASE statement can be used only within the range of an INPUT
PROCEDURE associated with a SORT statement.

Format: RELEASE

►► RELEASE record-name-1 ►◄
FROM identifier-1

Within an INPUT PROCEDURE, at least one RELEASE statement must be

specified.

When the RELEASE statement is executed, the current contents of record-name-1 are
placed in the sort file. This makes the record available to the initial phase of the
sorting operation.
record-name-1
Must specify the name of a logical record in a sort-merge file description
entry (SD). record-name-1 can be qualified.
FROM phrase
The result of the execution of the RELEASE statement with the FROM
identifier-1 phrase is equivalent to the execution of the following statements
in the order specified.
MOVE identifier-1 to record-name-1.
RELEASE record-name-1.

The MOVE is performed according to the rules for the MOVE statement
without the CORRESPONDING phrase.
identifier-1
identifier-1 must reference one of the following items:
v An entry in the WORKING-STORAGE SECTION, the LOCAL-STORAGE
SECTION, or the LINKAGE SECTION
v A record description for another previously opened file
v An alphanumeric or national function.
identifier-1 must be a valid sending item with record-name-1 as the receiving
item in accordance with the rules of the MOVE statement.
identifier-1 and record-name-1 must not refer to the same storage area.
After the RELEASE statement is executed, the information is still available
in identifier-1. (See “INTO and FROM phrases” on page 300 under
"Common processing facilities".)

If the RELEASE statement is executed without specifying the SD entry for

file-name-1 in a SAME RECORD AREA clause, the information in record-name-1 is
no longer available.

Chapter 20. PROCEDURE DIVISION statements 427

 If the SD entry is specified in a SAME RECORD AREA clause, record-name-1 is still
available as a record of the other files named in that clause.

When FROM identifier-1 is specified, the information is still available in identifier-1.

When control passes from the INPUT PROCEDURE, the sort file consists of all
those records placed in it by execution of RELEASE statements.

428 Enterprise COBOL for z/OS, V6.1 Language Reference

RETURN statement
The RETURN statement transfers records from the final phase of a sorting or
merging operation to an OUTPUT PROCEDURE.

The RETURN statement can be used only within the range of an OUTPUT
PROCEDURE associated with a SORT or MERGE statement.

Format: RETURN statement

►► RETURN file-name-1 ►
RECORD INTO identifier-1

► ►
END imperative-statement-1
AT

► ►◄
NOT END imperative-statement-2 END-RETURN
AT

Within an OUTPUT PROCEDURE, at least one RETURN statement must be

specified.

When the RETURN statement is executed, the next record from file-name-1 is made
available for processing by the OUTPUT PROCEDURE.
file-name-1
Must be described in a DATA DIVISION SD entry.
If more than one record description is associated with file-name-1, those
records automatically share the same storage; that is, the area is implicitly
redefined. After RETURN statement execution, only the contents of the
current record are available. If any data items lie beyond the length of the
current record, their contents are undefined.
INTO phrase
When there is only one record description associated with file-name-1 or all
the records and the data item referenced by identifier-1 describe an
elementary alphanumeric item or an alphanumeric group item, the result
of the execution of a RETURN statement with the INTO phrase is
equivalent to the application of the following rules in the order specified:
v The execution of the same RETURN statement without the INTO phrase.
v The current record is moved from the record area to the area specified
by identifier-1 according to the rules for the MOVE statement without the
CORRESPONDING phrase. The size of the current record is determined
by rules specified for the RECORD clause. If the file description entry
contains a RECORD IS VARYING clause, the implied move is a group
move. The implied MOVE statement does not occur if the execution of
the RETURN statement was unsuccessful. Any subscripting or reference
modification associated with identifier-1 is evaluated after the record has

Chapter 20. PROCEDURE DIVISION statements 429

 been read and immediately before it is moved to the data item. The
record is available in both the record area and the data item referenced
by identifier-1.
When there are multiple record descriptions associated with file-name-1 and
they do not all describe an alphanumeric group item or elementary
alphanumeric item, the following rules apply:
1. If the file referenced by file-name-1 contains variable-length records, a
group move takes place.
2. If the file referenced by file-name-1 contains fixed-length records, a
move takes place according to the rules for a MOVE statement using,
as a sending field description, the record that specifies the largest
number of character positions. If more than one such record exists, the
sending field record selected will be the one among those records that
appears first under the description of file-name-1.

identifier-1 must be a valid receiving field for the selected sending record
description entry in accordance with the rules of the MOVE statement.

The record areas associated with file-name-1 and identifier-1 must not be the same
storage area.

AT END phrases

The imperative-statement specified on the AT END phrase executes after all

records have been returned from file-name-1. No more RETURN statements can be
executed as part of the current output procedure.

If an at-end condition does not occur during the execution of a RETURN

statement, then after the record is made available and after executing any implicit
move resulting from the presence of an INTO phrase, control is transferred to the
imperative statement specified by the NOT AT END phrase. If an at-end condition
does occur, control is transferred to the end of the RETURN statement.

END-RETURN phrase

This explicit scope terminator serves to delimit the scope of the RETURN
statement. END-RETURN permits a conditional RETURN statement to be nested in
another conditional statement. END-RETURN can also be used with an imperative
RETURN statement.

For more information, see “Delimited scope statements” on page 288.

430 Enterprise COBOL for z/OS, V6.1 Language Reference

REWRITE statement
The REWRITE statement logically replaces an existing record in a direct-access file.
When the REWRITE statement is executed, the associated direct-access file must be
open in I-O mode.

The REWRITE statement is not supported for line-sequential files.

Format: REWRITE statement

►► REWRITE record-name-1 ►
FROM identifier-1

► ►
INVALID imperative-statement-1
KEY

► ►◄
NOT INVALID imperative-statement-2 END-REWRITE
KEY

record-name-1
Must be the name of a logical record in a DATA DIVISION FD entry. The
record-name can be qualified.
FROM phrase
The result of the execution of the REWRITE statement with the FROM
identifier-1 phrase is equivalent to the execution of the following statements
in the order specified.
MOVE identifier-1 TO record-name-1.
REWRITE record-name-1

The MOVE is performed according to the rules for the MOVE statement
without the CORRESPONDING phrase.
identifier-1
identifier-1 can reference one of the following items:
v A record description for another previously opened file
v An alphanumeric or national function
v A data item defined in the WORKING-STORAGE SECTION, the
LOCAL-STORAGE SECTION, or the LINKAGE SECTION
identifier-1 must be a valid sending item with record-name-1 as the receiving
item in accordance with the rules of the MOVE statement.
identifier-1 and record-name-1 must not refer to the same storage area.
After the REWRITE statement is executed, the information is still available
in identifier-1 (“INTO and FROM phrases” on page 300 under "Common
processing facilities").

INVALID KEY phrases

An INVALID KEY condition exists when:

Chapter 20. PROCEDURE DIVISION statements 431

 v The access mode is sequential, and the value contained in the prime RECORD
KEY of the record to be replaced does not equal the value of the prime RECORD
KEY data item of the last-retrieved record from the file
v The value contained in the prime RECORD KEY does not equal that of any
record in the file
v The value of an ALTERNATE RECORD KEY data item for which DUPLICATES
is not specified is equal to that of a record already in the file

For details of invalid key processing, see Invalid key condition.

END-REWRITE phrase

This explicit scope terminator serves to delimit the scope of the REWRITE
statement. END-REWRITE permits a conditional REWRITE statement to be nested
in another conditional statement. END-REWRITE can also be used with an
imperative REWRITE statement.

For more information, see “Delimited scope statements” on page 288.

Reusing a logical record

After successful execution of a REWRITE statement, the logical record is no longer
available in record-name-1 unless the associated file is named in a SAME RECORD
AREA clause (in which case, the record is also available as a record of the other
files named in the SAME RECORD AREA clause).

The file position indicator is not affected by execution of the REWRITE statement.

If the FILE STATUS clause is specified in the file-control entry, the associated file
status key is updated when the REWRITE statement is executed.

Sequential files
For files in the sequential access mode, the last prior input/output statement
executed for this file must be a successfully executed READ statement. When the
REWRITE statement is executed, the record retrieved by that READ statement is
logically replaced.

The number of character positions in record-name-1 must equal the number of

character positions in the record being replaced.

The INVALID KEY phrase must not be specified for a file with sequential
organization. An EXCEPTION/ERROR procedure can be specified.

Indexed files
The number of character positions in record-name-1 can be different from the
number of character positions in the record being replaced.

When the access mode is sequential, the record to be replaced is specified by the
value contained in the prime RECORD KEY. When the REWRITE statement is
executed, this value must equal the value of the prime record key data item in the
last record read from this file.

Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure

can be omitted.

432 Enterprise COBOL for z/OS, V6.1 Language Reference

 When the access mode is random or dynamic, the record to be replaced is specified
by the value contained in the prime RECORD KEY.

Values of ALTERNATE RECORD KEY data items in the rewritten record can differ
from those in the record being replaced. The system ensures that later access to the
record can be based upon any of the record keys.

If an invalid key condition exists, the execution of the REWRITE statement is

unsuccessful, the updating operation does not take place, and the data in
record-name-1 is unaffected. (See Invalid key condition under "Common processing
facilities".)

Relative files
The number of character positions in record-name-1 can be different from the
number of character positions in the record being replaced.

For relative files in sequential access mode, the INVALID KEY phrase must not be
specified. An EXCEPTION/ERROR procedure can be specified.

For relative files in random or dynamic access mode, the INVALID KEY phrase or
an applicable EXCEPTION/ERROR procedure can be specified. Both can be
omitted.

When the access mode is random or dynamic, the record to be replaced is specified
in the RELATIVE KEY data item. If the file does not contain the record specified,
an invalid key condition exists, and, if specified, the INVALID KEY
imperative-statement is executed. (See Invalid key condition under "Common
processing facilities".) The updating operation does not take place, and the data in
record-name is unaffected.

Chapter 20. PROCEDURE DIVISION statements 433

SEARCH statement
The SEARCH statement searches a table for an element that satisfies the specified
condition and adjusts the associated index to indicate that element.

Format 1: SEARCH statement for serial search

►► SEARCH identifier-1 ►
VARYING identifier-2 END imperative-statement-1
index-name-1 AT

► ▼ WHEN condition-1 imperative-statement-2 ►◄

NEXT-SENTENCE END-SEARCH

Format 2: SEARCH statement for binary search

►► SEARCH ALL identifier-1 ►

END imperative-statement-1
AT

► WHEN data-name-1 EQUAL identifier-3 ►

IS TO literal-1
= arithmetic-expression-1
condition-name-1

► ▼ ►
AND data-name-2 EQUAL identifier-4
IS TO literal-2
= arithmetic-expression-2
condition-name-2

► imperative-statement-2 ►◄
NEXT SENTENCE END-SEARCH

Use format 1 (serial search) when the table that you want to search has not been
sorted. Use format 1 to search a sorted table when you want to search serially
through the table or you want to control subscripts or indexes.

434 Enterprise COBOL for z/OS, V6.1 Language Reference

 Use format 2 (binary search) when you want to efficiently search across all
occurrences in a table. The table must previously have been sorted, and you can
sort the table with the format 2 SORT statement.

AT END and WHEN phrases

After imperative-statement-1 or imperative-statement-2 is executed, control passes to

the end of the SEARCH statement, unless imperative-statement-1 or
imperative-statement-2 ends with a GO TO statement.

The function of the AT END phrase is the same for a serial search and a binary
search.

NEXT SENTENCE
NEXT SENTENCE transfers control to the first statement following the closest
separator period.

When NEXT SENTENCE is specified with END-SEARCH, control does not pass to
the statement following the END-SEARCH. Instead, control passes to the statement
after the closest following period.

For the format-2 SEARCH ALL statement, neither imperative-statement-2 nor NEXT
SENTENCE is required. Without them, the SEARCH statement sets the index to
the value in the table that matched the condition.

The function of the NEXT SENTENCE phrase is the same for a serial search and a
binary search.

END-SEARCH phrase

This explicit scope terminator delimits the scope of the SEARCH statement.
END-SEARCH permits a conditional SEARCH statement to be nested in another
conditional statement.

For more information, see “Delimited scope statements” on page 288.

The function of END-SEARCH is the same for a serial search and a binary search.

Serial search
The topic provides information of using the SEARCH statement for serial search.
identifier-1 (serial search)
identifier-1 identifies the table that is to be searched. identifier-1 references
all occurrences within that table.
The data description entry for identifier-1 must contain an OCCURS clause.
The data description entry for identifier-1 should contain an OCCURS
clause with the INDEXED BY phrase, but a table can be searched using an
index defined for an appropriately described different table.
identifier-1 can reference a data item that is subordinate to a data item that
is described with an OCCURS clause (that is, identifier-1 can be a
subordinate table within a multidimensional table). In this case, the data
description entries must specify an INDEXED BY phrase for each
dimension of the table.

Chapter 20. PROCEDURE DIVISION statements 435

 identifier-1 must not be subscripted or reference-modified.
AT END
The condition that exists when the search operation terminates without
satisfying the condition specified in any of the associated WHEN phrases.

Before executing a serial search, you must set the value of the first (or only) index
associated with identifier-1 (the search index) to indicate the starting occurrence for
the search.

Before using a serial search on a multidimensional table, you must also set the
value of the index for each superordinate dimension.

The SEARCH statement modifies only the value in the search index, and, if the
VARYING phrase is specified, the value in index-name-1 or identifier-2. Therefore, to
search an entire two-dimensional to seven-dimensional table, you must execute a
SEARCH statement for each dimension. In the WHEN phrases, you must specify
the indexes for all dimensions. Before the execution of each SEARCH statement,
you must initialize the associated indexes with SET statements.

The SEARCH statement executes a serial search beginning at the current setting of
the search index.

When the search begins, if the value of the index associated with identifier-1 is not
greater than the highest possible occurrence number, the following actions take
place:
v The conditions in the WHEN phrase are evaluated in the order in which they
are written.
v If none of the conditions is satisfied, the index for identifier-1 is increased to
correspond to the next table element, and step 1 is repeated.
v If upon evaluation one of the WHEN conditions is satisfied, the search is
terminated immediately, and the imperative-statement-2 associated with that
condition is executed. The index points to the table element that satisfied the
condition. If NEXT SENTENCE is specified, control passes to the statement
following the closest period.
v If the end of the table is reached (that is, the value of the incremented index is
greater than the highest possible occurrence number) without the WHEN
condition being satisfied, the search is terminated.

If, when the search begins, the value of the index-name associated with identifier-1
is greater than the highest possible occurrence number, the search terminates
immediately.

When the search terminates, if the AT END phrase is specified,

imperative-statement-1 is executed. If the AT END phrase is omitted, control passes
to the next statement after the SEARCH statement.

Example: multidimensional serial search

The following code fragment shows a search of the inner dimension (table C) in the
third occurrence within the superordinate table (table R):
. . .
Working-storage section.
1 G.
2 R occurs 10 indexed by Rindex.
3 C occurs 10 ascending key X indexed by Cindex.

436 Enterprise COBOL for z/OS, V6.1 Language Reference

 4 X pic 99.
1 Arg pic 99 value 34.
Procedure division.
. . .
* To search within occurrence 3 of table R, set its index to 3
* To search table C beginning at occurrence 1, set its index to 1
Set Rindex to 3
Set Cindex to 1
* In the SEARCH statement, specify C without indexes
Search C
* Specify indexes for both dimensions in the WHEN phrase
when X(Rindex Cindex) = Arg
display "Found " X(Rindex Cindex)
End-search
. . .

VARYING phrase
index-name-1
One of the following actions applies:
v If index-name-1 is an index for identifier-1, this index is used for the
search. Otherwise, the first (or only) index-name is used.
v If index-name-1 is an index for another table element, then the first (or
only) index-name for identifier-1 is used for the search; the occurrence
number represented by index-name-1 is increased by the same amount as
the search index-name and at the same time.
When the VARYING index-name-1 phrase is omitted, the first (or only)
index-name for identifier-1 is used for the search.
If indexing is used to search a table without an INDEXED BY phrase,
correct results are ensured only if both the table defined with the index
and the table defined without the index have table elements of the same
length and with the same number of occurrences.
When the object of the VARYING phrase is an index-name for another
table element, one serial SEARCH statement steps through two table
elements at once.
identifier-2
Must be either an index data item or an elementary integer item. identifier-2
cannot be subscripted by the first (or only) index-name specified for
identifier-1. During the search, one of the following actions applies:
v If identifier-2 is an index data item, then, whenever the search index is
increased, the specified index data item is simultaneously increased by
the same amount.
v If identifier-2 is an integer data item, then, whenever the search index is
increased, the specified data item is simultaneously increased by 1.

WHEN phrase (serial search)

condition-1
Can be any condition described under “Conditional expressions” on page
264.

The following figure illustrates a format-1 SEARCH operation containing two

WHEN phrases.

Chapter 20. PROCEDURE DIVISION statements 437

 Entrance

Index
setting: >AT END imperative-
highest statement-1
permissible
occurrence
number

True imperative-
Condition-1 statement-2

False

Condition-2 True imperative-

statement-3

False

Increment
index-name
for identifier-1

Increment
index-name-1
or identifier-2

These operations are included only when called for in the statement.
Control transfers to the next sentence, unless the imperative statement
ends with a GO TO statement.

Binary search
The topic provides information of using the SEARCH statement for binary search.
identifier-1 (binary search)
identifier-1 identifies the table that is to be searched. identifier-1 references
all occurrences within that table.
The data description entry for identifier-1 must contain an OCCURS clause
with the INDEXED BY and KEY IS phrases.
identifier-1 can reference a data item that is subordinate to a data item that
contains an OCCURS clause (that is, identifier-1 can be a subordinate table
within a multidimensional table). In this case, the data description entry
must specify an INDEXED BY phrase for each dimension of the table.
identifier-1 must not be subscripted or reference-modified.
AT END
The condition that exists when the search operation terminates without
satisfying the conditions specified in the WHEN phrase.

The SEARCH ALL statement executes a binary search. The index associated with
identifier-1 (the search index) need not be initialized by SET statements. The search
index is varied during the search operation so that its value is at no time less than

438 Enterprise COBOL for z/OS, V6.1 Language Reference

the value of the first table element, nor ever greater than the value of the last table
element. The index used is always that associated with the first index-name
specified in the OCCURS clause.

Before using a binary search on a multidimensional table, you must execute SET
statements to set the value of the index for each superordinate dimension.

The SEARCH statement modifies only the value in the search index. Therefore, to
search an entire two-dimensional to seven-dimensional table, you must execute a
SEARCH statement for each dimension. In the WHEN phrases, you must specify
the indexes for all dimensions.

If the search ends without the WHEN condition being satisfied and the AT END
phrase is specified, imperative-statement-1 is executed. If the AT END phrase is
omitted, control passes to the next statement after the SEARCH statement.

The results of a SEARCH ALL operation are predictable only when:

v The data in the table is ordered in ASCENDING KEY or DESCENDING KEY
order
v The contents of the ASCENDING or DESCENDING keys specified in the WHEN
clause provide a unique table reference.

WHEN phrase (binary search)

If a relation condition is specified in the WHEN phrase, the evaluation of the

relation is based on the USAGE of the data item referenced by data-name-1. The
search argument is moved to a temporary data item with the same USAGE as
data-name-1, and this temporary data item is used for the compare operations
associated with the SEARCH.

If the WHEN phrase cannot be satisfied for any setting of the index within this
range, the search is unsuccessful. Control is passed to imperative-statement-1 of the
AT END phrase, when specified, or to the next statement after the SEARCH
statement. In either case, the final setting of the index is not predictable.

If the WHEN phrase can be satisfied, control passes to imperative-statement-2, if

specified, or to the next executable sentence if the NEXT SENTENCE phrase is
specified. The index contains the value indicating the occurrence that allowed the
WHEN conditions to be satisfied.

After imperative-statement-2 is executed, control passes to the end of the SEARCH

statement, unless imperative-statement-2 ends with a GO TO statement.
condition-name-1 , condition-name-2
Each condition-name specified must have only a single value, and each
must be associated with an ASCENDING KEY or DESCENDING KEY data
item for this table element.
data-name-1 , data-name-2
Must specify an ASCENDING KEY or DESCENDING KEY data item in the
table element referenced by identifier-1 and must be subscripted by the first
index-name associated with identifier-1. Each data-name can be qualified.
data-name-1 must be a valid operand for comparison with identifier-3,
literal-1, or arithmetic-expression-1 according to the rules of comparison.

Chapter 20. PROCEDURE DIVISION statements 439

 data-name-2 must be a valid operand for comparison with identifier-4,
literal-2, or arithmetic-expression-2 according to the rules of comparison.
data-name-1 and data-name-2 cannot reference:
v Floating-point data items
v Group items containing variable-occurrence data items
identifier-3 , identifier-4
Must not be an ASCENDING KEY or DESCENDING KEY data item for
identifier-1 or an item that is subscripted by the first index-name for
identifier-1.
identifier-3 and identifier-4 cannot be data items defined with any of the
usages POINTER, FUNCTION-POINTER, PROCEDURE-POINTER, or
OBJECT REFERENCE.
If identifier-3 or literal-1 is of class national, data-name-1 must be of class
national.
If identifier-4 or literal-2 is of class national, data-name-2 must be of class
national.
literal-1 , literal-2
literal-1 or literal-2 must be a valid operand for comparison with
data-name-1 or data-name-2, respectively.
arithmetic-expression
Can be any of the expressions defined under “Arithmetic expressions” on
page 261, with the following restriction: Any identifier in
arithmetic-expression must not be an ASCENDING KEY or DESCENDING
KEY data item for identifier-1 or an item that is subscripted by the first
index-name for identifier-1.

When an ASCENDING KEY or DESCENDING KEY data item is specified,

explicitly or implicitly, in the WHEN phrase, all preceding ASCENDING KEY or
DESCENDING KEY data-names for identifier-1 must also be specified.

Search statement considerations

The topic lists considerations of using the SEARCH statement.

Index data items cannot be used as subscripts, because of the restrictions on direct
reference to them.

To ensure correct execution of a SEARCH statement for a variable-length table,

make sure the object of the OCCURS DEPENDING ON clause (data-name-1)
contains a value that specifies the current length of the table.

The scope of a SEARCH statement can be terminated by any of the following

items:
v An END-SEARCH phrase at the same level of nesting
v A separator period
v An ELSE or END-IF phrase associated with a previous IF statement

440 Enterprise COBOL for z/OS, V6.1 Language Reference

SET statement
The SET statement is used to perform an operation as described in this topic.

The operations are:

v Placing values associated with table elements into indexes associated with
index-names
v Incrementing or decrementing an occurrence number
v Setting the status of an external switch to ON or OFF
v Moving data to condition names to make conditions true
v Setting USAGE POINTER data items to a data address
v Setting USAGE PROCEDURE-POINTER data items to an entry address
v Setting USAGE FUNCTION-POINTER data items to an entry address
v Setting USAGE OBJECT REFERENCE data items to refer to an object instance

Index-names are related to a given table through the INDEXED BY phrase of the
OCCURS clause; they are not further defined in the program.

When the sending and receiving fields in a SET statement share part of their
storage (that is, the operands overlap), the result of the execution of that SET
statement is undefined.

Format 1: SET for basic table handling

When this form of the SET statement is executed, the current value of the receiving
field is replaced by the value of the sending field (with conversion).

Format 1: SET statement for basic table handling

►► SET ▼ index-name-1 TO index-name-2 ►◄

identifier-1 identifier-2
integer-1

index-name-1
Receiving field.
Must name an index that is specified in the INDEXED BY phrase of an
OCCURS clause.
identifier-1
Receiving field.
Must name either an index data item or an elementary numeric integer
item.
index-name-2
Sending field.
Must name an index that is specified in the INDEXED BY phrase of an
OCCURS clause. The value of the index before the SET statement is
executed must correspond to an occurrence number of its associated table.

Chapter 20. PROCEDURE DIVISION statements 441

 identifier-2
Sending field.
Must name either an index data item or an elementary numeric integer
item.
integer-1
Sending field.
Must be a positive integer.

The following table shows valid combinations of sending and receiving fields in a
format-1 SET statement.
Table 47. Sending and receiving fields for format-1 SET statement
Integer data
Index-name Index data item item receiving
Sending field receiving field receiving field field
Index-name* Valid Valid** Valid
** **
Index data item* Valid Valid Invalid
Integer data item Valid Invalid Invalid
Integer literal Valid Invalid Invalid
*An index-name refers to an index named in the INDEXED BY phrase of an OCCURS
clause. An index data item is defined with the USAGE IS INDEX clause.
**
No conversion takes place.

Receiving fields are acted upon in the left-to-right order in which they are
specified. Any subscripting or indexing associated with identifier-1 is evaluated
immediately before that receiving field is acted upon.

The value used for the sending field is the value at the beginning of SET statement
execution.

The value of an index after execution of a SEARCH or PERFORM statement can be

undefined; therefore, use a format-1 SET statement to reinitialize such indexes
before you attempt other table-handling operations.

If index-name-2 is for a table that has a subordinate item that contains an OCCURS
DEPENDING ON clause, then undefined values can be received into identifier-1.

For more information about complex OCCURS DEPENDING ON, see Complex
OCCURS DEPENDING ON in the Enterprise COBOL Programming Guide.

Format 2: SET for adjusting indexes

When this form of the SET statement is executed, the value of the receiving index
is increased (UP BY) or decreased (DOWN BY) by a value that corresponds to the
value in the sending field.

442 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 2: SET statement for adjusting indexes

►► SET ▼ index-name-3 UP BY identifier-3 ►◄

DOWN BY integer-2

The receiving field is an index specified by index-name-3. The index value both
before and after the SET statement execution must correspond to an occurrence
number in an associated table.

The sending field can be specified as identifier-3, which must be an elementary

integer data item, or as integer-2, which must be a nonzero integer.

When the format-2 SET statement is executed, the contents of the receiving field
are increased (UP BY) or decreased (DOWN BY) by a value that corresponds to the
number of occurrences represented by the value of identifier-3 or integer-2.
Receiving fields are acted upon in the left-to-right order in which they are
specified. The value of the incrementing or decrementing field at the beginning of
SET statement execution is used for all receiving fields.

If index-name-3 is for a table that has a subordinate item that contains an OCCURS
DEPENDING ON clause, and if the ODO object is changed before executing a
format-2 SET Statement, then index-name-3 cannot contain a value that corresponds
to an occurrence number of its associated table.

For more information about complex OCCURS DEPENDING ON, see Complex
OCCURS DEPENDING ON in the Enterprise COBOL Programming Guide.

Format 3: SET for external switches

When this form of the SET statement is executed, the status of each external switch
associated with the specified mnemonic-name is turned ON or OFF.

Format 3: SET statement for external switches

►► SET ▼ ▼ mnemonic-name-1 TO ON ►◄
OFF

mnemonic-name-1
Must be associated with an external switch, the status of which can be
altered.

Format 4: SET for condition-names

When this form of the SET statement is executed, the value associated with a
condition-name is placed in its conditional variable according to the rules of the
VALUE clause.
Chapter 20. PROCEDURE DIVISION statements 443
 Format 4: SET statement for condition-names

►► SET ▼ condition-name-1 TO TRUE ►◄

condition-name-1
Must be associated with a conditional variable.

If more than one literal is specified in the VALUE clause of condition-name-1, its
associated conditional variable is set equal to the first literal.

If multiple condition-names are specified, the results are the same as if a separate
SET statement had been written for each condition-name in the same order in
which they are specified in the SET statement.

Format 5: SET for USAGE IS POINTER data items

When this form of the SET statement is executed, the current value of the receiving
field is replaced by the address value contained in the sending field.

Format 5: SET statement for USAGE IS POINTER data items

►► SET ▼ identifier-4 TO identifier-6 ►◄

ADDRESS OF identifier-5 ADDRESS OF identifier-7
NULL
NULLS

identifier-4
Receiving field(s).
Must be defined as USAGE IS POINTER.
ADDRESS OF identifier-5
Receiving field(s).
identifier-5 must be level-01 or level-77 items defined in the LINKAGE
SECTION. The addresses of these items are set to the value of the operand
specified in the TO phrase.
identifier-5 must not be reference-modified.
identifier-6
Sending field.
Must be defined as USAGE IS POINTER.
ADDRESS OF identifier-7
Sending field. identifier-7 must name an item of any level except 66 or 88 in
the LINKAGE SECTION, the WORKING-STORAGE SECTION, or the

444 Enterprise COBOL for z/OS, V6.1 Language Reference

 LOCAL-STORAGE SECTION. ADDRESS OF identifier-7 contains the
address of the identifier, and not the content of the identifier.
NULL, NULLS
Sending field.
Sets the receiving field to contain the value of an invalid address.

The following table shows valid combinations of sending and receiving fields in a
format-5 SET statement.
Table 48. Sending and receiving fields for format-5 SET statement
USAGE IS
POINTER receiving ADDRESS OF NULL/NULLS
Sending field field receiving field receiving field
USAGE IS POINTER Valid Valid Invalid
ADDRESS OF Valid Valid Invalid
NULL/NULLS Valid Valid Invalid

Format 6: SET for procedure-pointer and function-pointer data

items
When this format of the SET statement is executed, the current value of the
receiving field is replaced by the address value specified by the sending field.

At run time, function-pointers and procedure-pointers can reference the address of

the primary entry point of a COBOL program, an alternate entry point in a
COBOL program, or an entry point in a non-COBOL program; or they can be
NULL.

COBOL function-pointers are more easily used than procedure-pointers for

interoperation with C functions.

Format 6: SET statement for procedure-pointers and function-pointers

►► SET ▼ procedure-pointer-data-item-1 ►
function-pointer-data-item-1

► TO procedure-pointer-data-item-2 ►◄
function-pointer-data-item-2
ENTRY identifier-8
literal-1
NULL
NULLS
pointer-data-item-3

Chapter 20. PROCEDURE DIVISION statements 445

 procedure-pointer-data-item-1 , procedure-pointer-data-item-2
Must be described as USAGE IS PROCEDURE-POINTER.
procedure-pointer-data-item-1 is a receiving field; procedure-pointer-data-item-2
is a sending field.
function-pointer-data-item-1 , function-pointer-data-item-2
Must be described as USAGE IS FUNCTION-POINTER.
function-pointer-data-item-1 is a receiving field; function-pointer-data-item-2 is
a sending field.
identifier-8
Must be defined as an alphabetic or alphanumeric item such that the value
can be a program name. For more information, see “PROGRAM-ID
paragraph” on page 104. For entry points in non-COBOL programs,
identifier-8 can contain the characters @, #, and, $.
literal-1
Must be alphanumeric and must conform to the rules for formation of
program-names. For details on formation rules, see the discussion of
program-name under “PROGRAM-ID paragraph” on page 104.
identifier-8 or literal-1 must refer to one of the following types of entry
points:
v The primary entry point of a COBOL program as defined by the
PROGRAM-ID paragraph. The PROGRAM-ID must reference the
outermost program of a compilation unit; it must not reference a nested
program.
v An alternate entry point of a COBOL program as defined by a COBOL
ENTRY statement.
v An entry point in a non-COBOL program.
The program-name referenced by the SET ... TO ENTRY statement can be
affected by the PGMNAME compiler option. For details, see PGMNAME in
the Enterprise COBOL Programming Guide.
NULL, NULLS
Sets the receiving field to contain the value of an invalid address.
pointer-data-item-3
Must be defined with USAGE POINTER. You must set pointer-data-item-3 in
a non-COBOL program to point to a valid program entry point.

Example of COBOL/C interoperability

The following example demonstrates a COBOL CALL to a C function that returns

a function-pointer to a service, followed by a COBOL CALL to the service:
IDENTIFICATION DIVISION.
PROGRAM-ID DEMO.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FP USAGE FUNCTION-POINTER.
PROCEDURE DIVISION.
CALL "c-function" RETURNING FP.
CALL FP.

Format 7: SET for USAGE OBJECT REFERENCE data items

When this format of the SET statement is executed the value in the receiving item
is replaced by the value in the sending item.

446 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 7: SET statement for object references

►► SET object-reference-id-1 TO object-reference-id-2 ►◄

NULL
SELF

object-reference-id-1 and object-reference-id-2 must be defined as USAGE OBJECT

REFERENCE. object-reference-id-1 is the receiving item and object-reference-id-2 is the
sending item. If object-reference-id-1 is defined as an object reference of a certain
class (defined as "USAGE OBJECT REFERENCE class-name"), object-reference-id-2
must be an object reference of the same class or a class derived from that class.

If the figurative constant NULL is specified, the receiving object-reference-id-1 is set

to the NULL value.

If SELF is specified, the SET statement must appear in the PROCEDURE DIVISION
of a method. object-reference-id-1 is set to reference the object upon which the
currently executing method was invoked.

Chapter 20. PROCEDURE DIVISION statements 447

SORT statement
The SORT statement causes a set of records or table elements to be arranged in a
user-specified sequence.

For sorting files, the SORT statement accepts records from one or more files, sorts
them according to the specified keys, and makes the sorted records available either
through an output procedure or in an output file.

For sorting tables, the SORT statement sorts table elements according to specified
table keys.

Format 1: SORT statement

►► SORT file-name-1 ▼ ASCENDING ▼ data-name-1 ►

ON DESCENDING KEY

► ►
DUPLICATES
WITH IN ORDER

► ►
SEQUENCE alphabet-name-1
COLLATING IS

► USING ▼ file-name-2 ►
INPUT PROCEDURE procedure-name-1
IS THROUGH procedure-name-2
THRU

► GIVING ▼ file-name-3 ►◄
OUTPUT PROCEDURE procedure-name-3
IS THROUGH procedure-name-4
THRU

Format 1 SORT statements can appear anywhere in the PROCEDURE DIVISION

except in the declarative portion. This format of the SORT statement is not
supported for programs that are compiled with the THREAD option. See also
“MERGE statement” on page 388.

448 Enterprise COBOL for z/OS, V6.1 Language Reference

Format 2: Table SORT statement

►► SORT data-name-2 ►

▼ ASCENDING ▼
ON DESCENDING KEY data-name-1

► ►
DUPLICATES
WITH IN ORDER

► ►◄
SEQUENCE alphabet-name-1
COLLATING IS

Format 2 SORT statements can appear anywhere in the PROCEDURE DIVISION.

This format of the SORT statement can be used with programs that are compiled
with the THREAD option.
file-name-1
The name given in the SD entry that describes the records to be sorted.

No pair of file-names in a SORT statement can be specified in the same SAME

SORT AREA clause or the SAME SORT-MERGE AREA clause. File-names
associated with the GIVING clause (file-name-3, ...) cannot be specified in the SAME
AREA clause; however, they can be associated with the SAME RECORD AREA
clause.
data-name-2
Specifies a table data-name that is subject to the following rules:
v data-name-2 must have an OCCURS clause in the data description entry.
v data-name-2 can be qualified.
v data-name-2 can be subscripted. The rightmost or only subscript of the
table must be omitted or replaced with the word ALL.
The number of occurrences of table elements that are referenced by
data-name-2 is determined by the rules in the OCCURS clause. The sorted
table elements are placed in the same table that is referenced by
data-name-2.

ASCENDING KEY and DESCENDING KEY phrases (format 1)

This phrase specifies that records are to be processed in ascending or descending
sequence (depending on the phrase specified), based on the specified sort keys.
data-name-1
Specifies a KEY data item on which the SORT statement will be based.
Each such data-name must identify a data item in a record associated with
file-name-1. The data-names following the word KEY are listed from left to
right in the SORT statement in order of decreasing significance without

Chapter 20. PROCEDURE DIVISION statements 449

 regard to how they are divided into KEY phrases. The leftmost data-name
is the major key, the next data-name is the next most significant key, and
so forth. The following rules apply:
v A specific KEY data item must be physically located in the same position
and have the same data format in each input file. However, it need not
have the same data-name.
v If file-name-1 has more than one record description, the KEY data items
need be described in only one of the record descriptions.
v If file-name-1 contains variable-length records, all of the KEY data-items
must be contained within the first n character positions of the record,
where n equals the minimum records size specified for file-name-1.
v KEY data items must not contain an OCCURS clause or be subordinate
to an item that contains an OCCURS clause.
v KEY data items cannot be:
– Variably located
– Group items that contain variable-occurrence data items
– Category numeric described with usage NATIONAL (national decimal
item)
– Category external floating-point described with usage NATIONAL
(national floating-point item)
– Category DBCS
v KEY data items can be qualified.
v KEY data items can belong to any of the following data categories:
– Alphabetic, alphanumeric, alphanumeric-edited
– Numeric (except numeric with usage NATIONAL)
– Numeric-edited (with usage DISPLAY or NATIONAL)
– Internal floating-point or display floating-point
– National or national-edited

If file-name-3 references an indexed file , the first specification of data-name-1 must

be associated with an ASCENDING phrase and the data item referenced by that
data-name-1 must occupy the same character positions in this record as the data
item associated with the prime record key for that file.

The direction of the sorting operation depends on the specification of the

ASCENDING or DESCENDING keywords as follows:
v When ASCENDING is specified, the sequence is from the lowest key value to
the highest key value.
v When DESCENDING is specified, the sequence is from the highest key value to
the lowest.
v If the KEY data item is described with usage NATIONAL, the sequence of the
KEY values is based on the binary values of the national characters.
v If the KEY data item is internal floating point, the sequence of key values will be
in numeric order.
v When the COLLATING SEQUENCE phrase is not specified, the key
comparisons are performed according to the rules for comparison of operands in
a relation condition. See “General relation conditions” on page 268.
v When the COLLATING SEQUENCE phrase is specified, the indicated collating
sequence is used for key data items of alphabetic, alphanumeric,
alphanumeric-edited, external floating-point, and numeric-edited categories. For

450 Enterprise COBOL for z/OS, V6.1 Language Reference

 all other key data items, the comparisons are performed according to the rules
for comparison of operands in a relation condition.

ASCENDING KEY and DESCENDING KEY phrases (format 2)

This phrase specifies that table elements are to be processed in ascending or

descending sequence, based on the specified phrase and sort keys.
data-name-1
Specifies a KEY data name that is subject to the following rules:
v The data item that is identified by a key data-name must be the same as,
or subordinate to, the data item that is referenced by data-name-2.
v KEY data items can be qualified.
v KEY data items can belong to any of the following data categories:
– Alphabetic, alphanumeric, alphanumeric-edited
– Numeric (except numeric with usage NATIONAL)
– Numeric-edited (with usage DISPLAY or NATIONAL)
– Internal floating-point or display floating-point
– National or national-edited
v KEY data items cannot be:
– Variably located
– Group items that contain variable-occurrence data items
– Category numeric that is described with usage NATIONAL (national
decimal item)
– Category external floating-point that is described with usage
NATIONAL (national floating-point item)
– Category DBCS
– Class object or pointer
– Subscripted
v If the data item that is identified by a KEY data-name is subordinate to
data-name-2, the following rules apply:
– The data item cannot be described with an OCCURS clause.
– The data item cannot be subordinate to an entry that is also
subordinate to data-name-2 and that contains an OCCURS clause.

The KEY phrase can be omitted only if the description of the table that is
referenced by data-name-2 contains a KEY phrase.

The words ASCENDING and DESCENDING are transitive across all occurrences of
data-name-1 until another word ASCENDING or DESCENDING is encountered.

The data items that are referenced by data-name-1 are key data items, and these
data items determine the order in which the sorted table elements are stored. The
order of significance of the keys is the order in which data items are specified in
the SORT statement, without regard to the association with ASCENDING or
DESCENDING phrases.

The SORT statement sorts the table that is referenced by data-name-2 and presents
the sorted table in data-name-2. The sorting order is determined by either the
ASCENDING and DESCENDING phrases (if specified), or by the KEY phrase that
is associated with data-name-2.

Chapter 20. PROCEDURE DIVISION statements 451

 The direction of the sorting operation depends on the specification of the
ASCENDING or DESCENDING keywords:
v When ASCENDING is specified, the sequence is from the lowest key value to
the highest one.
v When DESCENDING is specified, the sequence is from the highest key value to
the lowest one.
v If the KEY data item is described with usage NATIONAL, the sequence of the
KEY values is based on the binary values of the national characters.
v If the KEY data item is internal floating-point, the sequence of key values is in
the numeric order.
v When the COLLATING SEQUENCE phrase is not specified, the EBCDIC
sequence is used for key data items of alphabetic, alphanumeric,
alphanumeric-edited, external floating-point, and numeric-edited categories. For
all the other key data items, the comparisons are performed according to the
rules for comparison of operands in a relation condition.
v When the COLLATING SEQUENCE phrase is specified, the indicated collating
sequence is used for key data items of alphabetic, alphanumeric,
alphanumeric-edited, external floating-point, and numeric-edited categories. For
all the other key data items, the comparisons are performed according to the
rules for comparison of operands in a relation condition.

To determine the relative order in which table elements are stored, the contents of
corresponding key data items are compared according to the rules for comparison
of operands in a relation condition. The sorting starts with the most significant key
data item with the following rules:
v If the contents of the corresponding key data items are not equal and the key is
associated with the ASCENDING phrase, the table element that contains the key
data item with the lower value has the lower occurrence number.
v If the contents of the corresponding key data items are not equal and the key is
associated with the DESCENDING phrase, the table element that contains the
key data item with the higher value has the lower occurrence number.
v If the contents of the corresponding key data items are equal, the determination
is based on the contents of the next most significant key data item.

If the KEY phrase is not specified, the sequence is determined by the KEY phrase
in the data description entry of the table that is referenced by data-name-2.

If the KEY phrase is specified, it overrides any KEY phrase specified in the data
description entry of the table that is referenced by data-name-2.

If data-name-1 is omitted, the data item that is referenced by data-name-2 is the key
data item.

DUPLICATES phrase (format 1)

If the DUPLICATES phrase is specified, and the contents of all the key elements
associated with one record are equal to the corresponding key elements in one or
more other records, the order of return of these records is as follows:
v The order of the associated input files as specified in the SORT statement.
Within a given file the order is that in which the records are accessed from that
file.
v The order in which these records are released by an input procedure, when an
input procedure is specified.

452 Enterprise COBOL for z/OS, V6.1 Language Reference

If the DUPLICATES phrase is not specified, the order of these records is undefined.

DUPLICATES phrase (format 2)

When both of the following conditions are met, the contents of table elements are
in the relative order that is the same as the order before sorting operation:
v The DUPLICATES phrase is specified.
v The contents of all the key data items that are associated with one table element
are equal to the contents of corresponding key data items that are associated
with one or more other table elements.

If the DUPLICATES phrase is not specified and the second condition exists, the
relative order of the contents of these table elements is undefined.

COLLATING SEQUENCE phrase (both formats)

This phrase specifies the collating sequence to be used in alphanumeric

comparisons for the KEY data items in this sorting operation.

The COLLATING SEQUENCE phrase has no effect for keys that are not alphabetic
or alphanumeric.
alphabet-name-1
Must be specified in the ALPHABET clause of the SPECIAL-NAMES
paragraph. alphabet-name-1 can be associated with any one of the
ALPHABET clause phrases, with the following results:
STANDARD-1
The ASCII collating sequence is used for all alphanumeric
comparisons. (The ASCII collating sequence is shown in
Appendix C, “EBCDIC and ASCII collating sequences,” on page
609.)
STANDARD-2
The International Reference Version of ISO/IEC 646, 7-bit coded
character set for information processing interchange is used for all
alphanumeric comparisons.
NATIVE
The EBCDIC collating sequence is used for all alphanumeric
comparisons. (The EBCDIC collating sequence is shown in
Appendix C, “EBCDIC and ASCII collating sequences,” on page
609.)
EBCDIC
The EBCDIC collating sequence is used for all alphanumeric
comparisons. (The EBCDIC collating sequence is shown in
Appendix C, “EBCDIC and ASCII collating sequences,” on page
609.)
literal
The collating sequence established by the specification of literals in
the alphabet-name clause is used for all alphanumeric
comparisons.

When the COLLATING SEQUENCE phrase is omitted, the PROGRAM

COLLATING SEQUENCE clause (if specified) in the OBJECT-COMPUTER
paragraph specifies the collating sequence to be used. When both the COLLATING

Chapter 20. PROCEDURE DIVISION statements 453

 SEQUENCE phrase and the PROGRAM COLLATING SEQUENCE clause are
omitted, the EBCDIC collating sequence is used.

USING phrase
file-name-2 , ...
The input files.
When the USING phrase is specified, all the records in file-name-2, ..., (that
is, the input files) are transferred automatically to file-name-1. At the time
the SORT statement is executed, these files must not be open. The compiler
opens, reads, makes records available, and closes these files automatically.
If EXCEPTION/ERROR procedures are specified for these files, the
compiler makes the necessary linkage to these procedures.
All input files must be described in FD entries in the DATA DIVISION.
If the USING phrase is specified and if file-name-1 contains variable-length
records, the size of the records contained in the input files (file-name-2, ...)
must be neither less than the smallest record nor greater than the largest
record described for file-name-1. If file-name-1 contains fixed-length records,
the size of the records contained in the input files must not be greater than
the largest record described for file-name-1. For more information, see
Describing the input to sorting or merging in the Enterprise COBOL
Programming Guide.

INPUT PROCEDURE phrase

This phrase specifies the name of a procedure that is to select or modify input
records before the sorting operation begins.
procedure-name-1
Specifies the first (or only) section or paragraph in the input procedure.
procedure-name-2
Identifies the last section or paragraph of the input procedure.
The input procedure can consist of any procedure needed to select, modify,
or copy the records that are made available one at a time by the RELEASE
statement to the file referenced by file-name-1. The range includes all
statements that are executed as the result of a transfer of control by CALL,
EXIT, GO TO, PERFORM, and XML PARSE statements in the range of the
input procedure, as well as all statements in declarative procedures that are
executed as a result of the execution of statements in the range of the input
procedure. The range of the input procedure must not cause the execution
of any MERGE, RETURN, or format 1 SORT statement.
If an input procedure is specified, control is passed to the input procedure
before the file referenced by file-name-1 is sequenced by the SORT
statement. The compiler inserts a return mechanism at the end of the last
statement in the input procedure. When control passes the last statement in
the input procedure, the records that have been released to the file
referenced by file-name-1 are sorted.

GIVING phrase
file-name-3 , ...
The output files.
When the GIVING phrase is specified, all the sorted records in file-name-1
are automatically transferred to the output files (file-name-3, ...).

454 Enterprise COBOL for z/OS, V6.1 Language Reference

 All output files must be described in FD entries in the DATA DIVISION.
If the output files (file-name-3, ...) contain variable-length records, the size
of the records contained in file-name-1 must be neither less than the
smallest record nor greater than the largest record described for the output
files. If the output files contain fixed-length records, the size of the records
contained in file-name-1 must not be greater than the largest record
described for the output files. For more information, see Describing the
output from sorting or merging in the Enterprise COBOL Programming Guide.
At the time the SORT statement is executed, the output files (file-name-3, ...)
must not be open. For each of the output files, the execution of the SORT
statement causes the following actions to be taken:
v The processing of the file is initiated. The initiation is performed as if an
OPEN statement with the OUTPUT phrase had been executed.
v The sorted logical records are returned and written onto the file. Each
record is written as if a WRITE statement without any optional phrases
had been executed.
For a relative file, the relative key data item for the first record returned
contains the value '1'; for the second record returned, the value '2'. After
execution of the SORT statement, the content of the relative key data
item indicates the last record returned to the file.
v The processing of the file is terminated. The termination is performed as
if a CLOSE statement without optional phrases had been executed.
These implicit functions are performed such that any associated USE
AFTER EXCEPTION/ERROR procedures are executed; however, the
execution of such a USE procedure must not cause the execution of any
statement manipulating the file referenced by, or accessing the record area
associated with, file-name-3. On the first attempt to write beyond the
externally defined boundaries of the file, any USE AFTER STANDARD
EXCEPTION/ERROR procedure specified for the file is executed. If control
is returned from that USE procedure or if no such USE procedure is
specified, the processing of the file is terminated.

OUTPUT PROCEDURE phrase

This phrase specifies the name of a procedure that is to select or modify output
records from the sorting operation.
procedure-name-3
Specifies the first (or only) section or paragraph in the output procedure.
procedure-name-4
Identifies the last section or paragraph of the output procedure.
The output procedure can consist of any procedure needed to select,
modify, or copy the records that are made available one at a time by the
RETURN statement in sorted order from the file referenced by file-name-1.
The range includes all statements that are executed as the result of a
transfer of control by CALL, EXIT, GO TO, PERFORM, and XML PARSE
statements in the range of the output procedure. The range also includes
all statements in declarative procedures that are executed as a result of the
execution of statements in the range of the output procedure. The range of
the output procedure must not cause the execution of any MERGE,
RELEASE, or format 1 SORT statement.

Chapter 20. PROCEDURE DIVISION statements 455

 If an output procedure is specified, control passes to it after the file
referenced by file-name-1 has been sequenced by the SORT statement. The
compiler inserts a return mechanism at the end of the last statement in the
output procedure and when control passes the last statement in the output
procedure, the return mechanism provides the termination of the sort and
then passes control to the next executable statement after the SORT
statement. Before entering the output procedure, the sort procedure reaches
a point at which it can select the next record in sorted order when
requested. The RETURN statements in the output procedure are the
requests for the next record.
The INPUT PROCEDURE and OUTPUT PROCEDURE phrases are similar
to those for a basic PERFORM statement. For example, if you name a
procedure in an output procedure, that procedure is executed during the
sorting operation just as if it were named in a PERFORM statement. As
with the PERFORM statement, execution of the procedure is terminated
after the last statement completes execution. The last statement in an input
or output procedure can be the EXIT statement (see “EXIT statement” on
page 348).

SORT special registers

The special registers, SORT-CORE-SIZE, SORT-MESSAGE, and SORT-MODE-SIZE,
are equivalent to option control statement keywords in the sort control file. You
define the sort control data set with the SORT-CONTROL special register.

Usage notes:
v The SORT special registers are not applicable to sorting a table by using the
format 2 SORT statement.
v If you use a sort control file to specify control statements, the values specified in
the sort control file take precedence over those in the special register.
SORT-MESSAGE special register
See “SORT-MESSAGE” on page 24.
SORT-CORE-SIZE special register
See “SORT-CORE-SIZE” on page 23.
SORT-FILE-SIZE special register
See “SORT-FILE-SIZE” on page 23.
SORT-MODE-SIZE special register
See “SORT-MODE-SIZE” on page 24.
SORT-CONTROL special register
See “SORT-CONTROL” on page 22.
SORT-RETURN special register
See “SORT-RETURN” on page 24.

Segmentation considerations
The topic lists considerations of using the SORT statement.

If a SORT statement is coded in a fixed segment, any input or output procedure

referenced by that SORT statement must be either totally within a fixed segment or
wholly contained in a single independent segment.

If a SORT statement is coded in an independent segment, any input or output

procedure referenced by that SORT statement must be either totally within a fixed

456 Enterprise COBOL for z/OS, V6.1 Language Reference

segment or wholly contained within the same independent segment as that SORT
statement.

Chapter 20. PROCEDURE DIVISION statements 457

START statement
The START statement provides a means of positioning within an indexed or
relative file for subsequent sequential record retrieval.

When the START statement is executed, the associated indexed or relative file must
be open in either INPUT or I-O mode.

Format

►► START file-name-1 ►

► ►
KEY EQUAL data-name-1
IS TO
=
GREATER
THAN
>
NOT LESS
THAN
NOT <
GREATER OR EQUAL
THAN TO
>=

► ►
INVALID imperative-statement-1
KEY

► ►◄
NOT INVALID imperative-statement-2 END-START
KEY

file-name-1
Must name a file with sequential or dynamic access. file-name-1 must be
defined in an FD entry in the DATA DIVISION and must not name a sort
file.

KEY phrase

When the KEY phrase is specified, the file position indicator is positioned at the
logical record in the file whose key field satisfies the comparison.

When the KEY phrase is not specified, KEY IS EQUAL (to the prime record key) is
implied.
data-name-1
Can be qualified; it cannot be subscripted.

When the START statement is executed, a comparison is made between the current
value in the key data-name and the corresponding key field in the file's index.

If the FILE STATUS clause is specified in the file-control entry, the associated file
status key is updated when the START statement is executed (See “File status key”
on page 295).

458 Enterprise COBOL for z/OS, V6.1 Language Reference

 INVALID KEY phrases

If the comparison is not satisfied by any record in the file, an invalid key condition
exists; the position of the file position indicator is undefined, and (if specified) the
INVALID KEY imperative-statement is executed. (See “INTO and FROM phrases”
on page 300 under "Common processing facilities".)

Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure

can be omitted.

END-START phrase
This explicit scope terminator serves to delimit the scope of the START statement.
END-START permits a conditional START statement to be nested in another
conditional statement. END-START can also be used with an imperative START
statement.

For more information, see “Delimited scope statements” on page 288.

Indexed files
When the KEY phrase is specified, the key data item used for the comparison is
data-name-1.

When the KEY phrase is not specified, the key data item used for the EQUAL TO
comparison is the prime record key.

When START statement execution is successful, the RECORD KEY or ALTERNATE

RECORD KEY with which data-name-1 is associated becomes the key of reference
for subsequent READ statements.
data-name-1
Can be any of the following items:
v The prime RECORD KEY.
v Any ALTERNATE RECORD KEY.
v A data item within a record description for a file whose leftmost
character position corresponds to the leftmost character position of that
record key; it can be qualified. The size of the data item must be less
than or equal to the length of the record key for the file.

Regardless of its category, data-name-1 is treated as an alphanumeric item for

purposes of the comparison operation.

Note: If your key is numeric, you must specify the EQUAL TO condition,
otherwise, unexpected results can happen.

The file position indicator points to the first record in the file whose key field
satisfies the comparison. If the operands in the comparison are of unequal lengths,
the comparison proceeds as if the longer field were truncated on the right to the
length of the shorter field. All other numeric and alphanumeric comparison rules
apply, except that the PROGRAM COLLATING SEQUENCE clause, if specified,
has no effect.

When START statement execution is successful, the RECORD KEY with which
data-name-1 is associated becomes the key of reference for subsequent READ
statements.

Chapter 20. PROCEDURE DIVISION statements 459

 When START statement execution is unsuccessful, the key of reference is
undefined.

Relative files
When the KEY phrase is specified, data-name-1 must specify the RELATIVE KEY.

Whether or not the KEY phrase is specified, the key data item used in the
comparison is the RELATIVE KEY data item. Numeric comparison rules apply.

The file position indicator points to the logical record in the file whose key satisfies
the specified comparison.

460 Enterprise COBOL for z/OS, V6.1 Language Reference

STOP statement
The STOP statement halts execution of the object program either permanently or
temporarily.

Format

►► STOP RUN ►◄
literal

literal
Can be a fixed-point numeric literal (signed or unsigned) or an
alphanumeric literal. It can be any figurative constant except ALL literal.

When STOP literal is specified, the literal is communicated to the operator, and
object program execution is suspended. Program execution is resumed only after
operator intervention, and continues at the next executable statement in sequence.

The STOP literal statement is useful for special situations when operator
intervention is needed during program execution; for example, when a special tape
or disk must be mounted or a specific daily code must be entered. However, the
ACCEPT and DISPLAY statements are preferred when operator intervention is
needed.

Do not use the STOP literal statement in programs compiled with the THREAD
compiler option.

When STOP RUN is specified, execution is terminated and control is returned to

the system. When STOP RUN is not the last or only statement in a sequence of
imperative statements within a sentence, the statements following STOP RUN are
not executed.

The STOP RUN statement closes all files defined in any of the programs in the run
unit.

For use of the STOP RUN statement in calling and called programs, see the
following table.

Termination
statement Main program Subprogram
STOP RUN Returns to the calling program. (Can be Returns directly to the program that
the system, which causes the called the main program. (Can be
application to end.) the system, which causes the
application to end.)

Chapter 20. PROCEDURE DIVISION statements 461

STRING statement
The STRING statement strings together the partial or complete contents of two or
more data items or literals into one single data item.

One STRING statement can be written instead of a series of MOVE statements.

Format

►► STRING ▼ ▼ identifier-1 DELIMITED identifier-2 ►

literal-1 BY literal-2
SIZE

► INTO identifier-3 ►
POINTER identifier-4
WITH

► ►
OVERFLOW imperative-statement-1
ON

► ►◄
NOT OVERFLOW imperative-statement-2 END-STRING
ON

identifier-1, literal-1
Represents the sending fields.
DELIMITED BY phrase
Sets the limits of the string.
identifier-2, literal-2
Are delimiters; that is, characters that delimit the data to be
transferred.
SIZE Transfers the complete sending area.
INTO phrase
Identifies the receiving field.
identifier-3
Represents the receiving field.
POINTER phrase
Points to a character position in the receiving field. The pointer field

462 Enterprise COBOL for z/OS, V6.1 Language Reference

 indicates a relative alphanumeric character position, DBCS character
position, or national character position when the receiving field is of usage
DISPLAY, DISPLAY-1, or NATIONAL, respectively.
identifier-4
Represents the pointer field. identifier-4 must be large enough to
contain a value equal to the length of the receiving field plus 1.
You must initialize identifier-4 to a nonzero value before execution
of the STRING statement begins.

The following rules apply:

v All identifiers except identifier-4 must reference data items described explicitly
or implicitly as usage DISPLAY, DISPLAY-1, or NATIONAL.
v literal-1 or literal-2 must be of category alphanumeric, DBCS, or national and can
be any figurative constant that does not begin with the word ALL (except
NULL).
v If identifier-1 or identifer-2 references a data item of category numeric, each
numeric item must be described as an integer without the symbol 'P' in its
PICTURE character-string.
v identifier-3 must not reference a data item of category numeric-edited,
alphanumeric-edited, or national-edited; an external floating-point data item of
usage DISPLAY, or an external floating-point data item of usage NATIONAL.
v identifier-3 must not described with the JUSTIFIED clause.
v If identifier-3 is of usage DISPLAY, identifier-1 and identifier-2 must be of usage
DISPLAY and all literals must be alphanumeric literals. Any figurative constant
can be specified except one that begins with the word ALL. Each figurative
constant represents a 1-character alphanumeric literal.
v If identifier-3 is of usage DISPLAY-1, identifier-1 and identifier-2 must be of usage
DISPLAY-1 and all literals must be DBCS literals. The only figurative constant
that can be specified is SPACE, which represents a 1-character DBCS literal. ALL
DBCS-literal must not be specified.
v If identifier-3 is of usage NATIONAL, identifier-1 and identifier-2 must be of usage
NATIONAL and all literals must be national literals. Any figurative constant can
be specified except symbolic-character and one that begins with the word ALL.
Each figurative constant represents a 1-character national literal.
v If identifier-1 or identifier-2 references an elementary data item of usage DISPLAY
that is described as category numeric, numeric-edited, or alphanumeric-edited,
the item is treated as if it were redefined as category alphanumeric.
v If identifier-1 or identifier-2 references an elementary data item of usage
NATIONAL that is described as category numeric, numeric-edited, or
national-edited item, the item is treated as if it were redefined as category
national.
v identifier-4 must not be described with the symbol P in its PICTURE
character-string.

Evaluation of subscripts, reference modification, variable-lengths, variable

locations, and function-identifiers is performed only once, at the beginning of the
execution of the STRING statement. Therefore, if identifier-3 or identifier-4 is used as
a subscript, reference-modifier, or function argument in the STRING statement, or
affects the length or location of any of the identifiers in the STRING statement, the
values calculated for those subscripts, reference-modifiers, variable lengths,
variable locations, and functions are not affected by any results of the STRING
statement.

Chapter 20. PROCEDURE DIVISION statements 463

 If identifier-3 and identifier-4 occupy the same storage area, undefined results will
occur, even if the identifiers are defined by the same data description entry.

If identifier-1 or identifier-2 occupies the same storage area as identifier-3 or

identifier-4, undefined results will occur, even if the identifiers are defined by the
same data description entry.

See “Data flow” for details of STRING statement processing.

ON OVERFLOW phrases
imperative-statement-1
Executed when the pointer value (explicit or implicit):
v Is less than 1
v Exceeds a value equal to the length of the receiving field
When either of the above conditions occurs, an overflow condition exists,
and no more data is transferred. Then the STRING operation is terminated,
the NOT ON OVERFLOW phrase, if specified, is ignored, and control is
transferred to the end of the STRING statement or, if the ON OVERFLOW
phrase is specified, to imperative-statement-1.
If control is transferred to imperative-statement-1, execution continues
according to the rules for each statement specified in imperative-statement-1.
If a procedure branching or conditional statement that causes explicit
transfer of control is executed, control is transferred according to the rules
for that statement; otherwise, upon completion of the execution of
imperative-statement-1, control is transferred to the end of the STRING
statement.
If at the time of execution of a STRING statement, conditions that would
cause an overflow condition are not encountered, then after completion of
the transfer of data, the ON OVERFLOW phrase, if specified, is ignored.
Control is then transferred to the end of the STRING statement, or if the
NOT ON OVERFLOW phrase is specified, to imperative-statement-2.
If control is transferred to imperative-statement-2, execution continues
according to the rules for each statement specified in imperative-statement-2.
If a procedure branching or conditional statement that causes explicit
transfer of control is executed, control is transferred according to the rules
for that statement. Otherwise, upon completion of the execution of
imperative-statement-2, control is transferred to the end of the STRING
statement.

END-STRING phrase

This explicit scope terminator serves to delimit the scope of the STRING statement.
END-STRING permits a conditional STRING statement to be nested in another
conditional statement. END-STRING can also be used with an imperative STRING
statement.

For more information, see “Delimited scope statements” on page 288.

Data flow
When the STRING statement is executed, characters are transferred from the
sending fields to the receiving field. The order in which sending fields are
processed is the order in which they are specified.

464 Enterprise COBOL for z/OS, V6.1 Language Reference

 The following rules apply:
v Characters from the sending fields are transferred to the receiving fields in the
following manner:
– For national sending fields, data is transferred using the rules of the MOVE
statement for elementary national-to-national moves, except that no space
filling takes place.
– For DBCS sending fields, data is transferred using the rules of the MOVE
statement for elementary DBCS-to-DBCS moves, except that no space filling
takes place.
– Otherwise, data is transferred to the receiving fields using the rules of the
MOVE statement for elementary alphanumeric-to-alphanumeric moves, except
that no space filling takes place (see “MOVE statement” on page 393).
v When DELIMITED BY identifier-2 or literal-2 is specified, the contents of each
sending item are transferred, character-by-character, beginning with the leftmost
character position and continuing until either:
– A delimiter for this sending field is reached (the delimiter itself is not
transferred).
– The rightmost character of this sending field has been transferred.
v When DELIMITED BY SIZE is specified, each entire sending field is transferred
to the receiving field.
v When the receiving field is filled, or when all the sending fields have been
processed, the operation is ended.
v When the POINTER phrase is specified, an explicit pointer field is available to
the COBOL user to control placement of data in the receiving field. The user
must set the explicit pointer's initial value, which must not be less than 1 and
not more than the character position count of the receiving field.
Usage note: The pointer field must be defined as a field large enough to contain
a value equal to the length of the receiving field plus 1; this precludes arithmetic
overflow when the system updates the pointer at the end of the transfer.
v When the POINTER phrase is not specified, no pointer is available to the user.
However, a conceptual implicit pointer with an initial value of 1 is used by the
system.
v Conceptually, when the STRING statement is executed, the initial pointer value
(explicit or implicit) is the first character position within the receiving field into
which data is to be transferred. Beginning at that position, data is then
positioned, character-by-character, from left to right. After each character is
positioned, the explicit or implicit pointer is increased by 1. The value in the
pointer field is changed only in this manner. At the end of processing, the
pointer value always indicates a value equal to one character position beyond
the last character transferred into the receiving field.

After STRING statement execution is completed, only that part of the receiving
field into which data was transferred is changed. The rest of the receiving field
contains the data that was present before this execution of the STRING statement.

Example of the STRING statement

This topic lists an example for the STRING statement.

When the following STRING statement is executed, the results obtained will be
like those illustrated in the figure after the statement.

Chapter 20. PROCEDURE DIVISION statements 465

 STRING ID-1 ID-2 DELIMITED BY ID-3
ID-4 ID-5 DELIMITED BY SIZE
INTO ID-7 WITH POINTER ID-8
END-STRING

466 Enterprise COBOL for z/OS, V6.1 Language Reference

SUBTRACT statement
The SUBTRACT statement subtracts one numeric item, or the sum of two or more
numeric items, from one or more numeric items, and stores the result.

Format 1: SUBTRACT statement

►► SUBTRACT ▼ identifier-1 FROM ▼ identifier-2 ►

literal-1 ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-SUBTRACT
ON

All identifiers or literals preceding the keyword FROM are added together and
their sum is subtracted from and stored immediately in identifier-2. This process is
repeated for each successive occurrence of identifier-2, in the left-to-right order in
which identifier-2 is specified.

Chapter 20. PROCEDURE DIVISION statements 467

 Format 2: SUBTRACT statement with GIVING phrase

►► SUBTRACT ▼ identifier-1 FROM identifier-2 ►

literal-1 literal-2

► GIVING ▼ identifier-3 ►
ROUNDED

► ►
SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-SUBTRACT
ON

All identifiers or literals preceding the keyword FROM are added together and
their sum is subtracted from identifier-2 or literal-2. The result of the subtraction is
stored as the new value of each data item referenced by identifier-3.

Format 3: SUBTRACT statement with CORRESPONDING phrase

►► SUBTRACT CORRESPONDING identifier-1 FROM ►

CORR

► identifier-2 ►
ROUNDED SIZE ERROR imperative-statement-1
ON

► ►◄
NOT SIZE ERROR imperative-statement-2 END-SUBTRACT
ON

Elementary data items within identifier-1 are subtracted from, and the results are
stored in, the corresponding elementary data items within identifier-2.

When the ARITH(COMPAT) compiler option is in effect, the composite of operands

can contain a maximum of 30 digits. When the ARITH(EXTEND) compiler option
is in effect, the composite of operands can contain a maximum of 31 digits. For
more information about arithmetic intermediate results, see Appendix A.
Intermediate results and arithmetic precision in the Enterprise COBOL Programming
Guide.

468 Enterprise COBOL for z/OS, V6.1 Language Reference

For all formats:
identifier
In format 1, must name an elementary numeric data item.
In format 2, must name an elementary numeric data item, unless the
identifier follows the word GIVING. Each identifier following the word
GIVING must name a numeric or numeric-edited elementary data item.
In format 3, must name an alphanumeric group item or a national group
item.
literal
Must be a numeric literal.

Floating-point data items and literals can be used anywhere numeric data items
and literals can be specified.

ROUNDED phrase

For information about the ROUNDED phrase, and for operand considerations, see
“ROUNDED phrase” on page 291.

SIZE ERROR phrases

For information about the SIZE ERROR phrases, and for operand considerations,
see “SIZE ERROR phrases” on page 291.

CORRESPONDING phrase (format 3)

See “CORRESPONDING phrase” on page 289.

END-SUBTRACT phrase

This explicit scope terminator serves to delimit the scope of the SUBTRACT
statement. END-SUBTRACT permits a conditional SUBTRACT statement to be
nested in another conditional statement. END-SUBTRACT can also be used with
an imperative SUBTRACT statement.

For more information, see “Delimited scope statements” on page 288.

Chapter 20. PROCEDURE DIVISION statements 469

UNSTRING statement
The UNSTRING statement causes contiguous data in a sending field to be
separated and placed into multiple receiving fields.

Format

►► UNSTRING identifier-1 ►

► INTO ►
DELIMITED identifier-2
BY ALL literal-1

▼ OR identifier-3
ALL literal-2

► ▼ identifier-4 ►
DELIMITER identifier-5 COUNT identifier-6
IN IN

► ►
POINTER identifier-7 TALLYING identifier-8
WITH IN

► ►
OVERFLOW imperative-statement-1 NOT OVERFLOW imperative-statement-2
ON ON

► ►◄
END-UNSTRING

identifier-1
Represents the sending field. Data is transferred from this field to the data
receiving fields (identifier-4).
identifier-1 must reference a data item of category alphabetic, alphanumeric,
alphanumeric-edited, DBCS, national, or national-edited.
identifier-2, literal-1, identifier-3, literal-2
Specifies one or more delimiters.
identifier-2 and identifier-3 must reference data items of category alphabetic,
alphanumeric, alphanumeric-edited, DBCS, national, or national-edited.

470 Enterprise COBOL for z/OS, V6.1 Language Reference

 literal-1 or literal-2 must be of category alphanumeric, DBCS, or national
and must not be a figurative constant that begins with the word ALL.
identifier-4
Specifies one or more receiving fields.
identifier-4 must reference a data item of category alphabetic, alphanumeric,
numeric, DBCS, or national. If the referenced data item is of category
numeric, its picture character-string must not contain the picture symbol P,
and its usage must be DISPLAY or NATIONAL.
identifier-5
Specifies a field to receive the delimiter associated with identifier-4.
Identifier-5 must reference a data item of category alphabetic,
alphanumeric, DBCS, or national.
identifier-6
Specifies a field to hold the count of characters that are transferred to
identifier-4.
identifier-6 must be an integer data item defined without the symbol P in
its PICTURE character-string.
identifier-7
Specifies a field to hold a relative character position during UNSTRING
processing.
identifier-7 must be an integer data item defined without the symbol P in
the PICTURE string.identifier-7 must be described as a data item of
sufficient size to contain a value equal to 1 plus the number of character
positions in the data item referenced by identifier-1.
identifier-8
Specifies a field that is incremented by the number of delimited fields
processed.
identifier-8 must be an integer data item defined without the symbol P in
its PICTURE character-string.

The following rules apply

v If identifier-4 references a data item of usage DISPLAY, identifier-1, identifier-2,
identifier-3, and identifier-5 must also reference data items of usage DISPLAY and
all literals must be alphanumeric literals. Any figurative constant can be
specified except NULL or one that begins with the word ALL. Each figurative
constant represents a 1-character alphanumeric literal.
v If identifier-4 references a data item of usage DISPLAY-1, identifier-1, identifier-2,
identifier-3, and identifier-5 must also reference data items of usage DISPLAY-1
and all literals must be DBCS literals. Figurative constant SPACE is the only
figurative constant that can be specified. Each figurative constant represents a
1-character DBCS literal.
v If identifier-4 references a data item of usage NATIONAL, identifier-1, identifier-2,
identifier-3, and identifier-5 must also reference data items of usage NATIONAL
and all literals must be national literals. Any figurative constant can be specified
except NULL or one that begins with the word ALL. Each figurative constant
represents a 1-character national literal.

Count fields (identifier-6) and pointer fields (identifier-7) are incremented by number
of character positions (alphanumeric, DBCS, or national), not by number of bytes.

Chapter 20. PROCEDURE DIVISION statements 471

 One UNSTRING statement can take the place of a series of MOVE statements,
except that evaluation or calculation of certain elements is performed only once, at
the beginning of the execution of the UNSTRING statement. For more information,
see “Values at the end of execution of the UNSTRING statement” on page 476.

The rules for moving are the same as those for a MOVE statement for an
elementary sending item of the category of identifier-1, with the appropriate
identifier-4 as the receiving item (see “MOVE statement” on page 393). For example,
rules for moving a DBCS item are used when identifier-1 is a DBCS item.

DELIMITED BY phrase
This phrase specifies delimiters within the data that control the data transfer.

Each identifier-2, identifier-3, literal-1, or literal-2 represents one delimiter.

If the DELIMITED BY phrase is not specified, the DELIMITER IN and COUNT IN

phrases must not be specified.
ALL Multiple contiguous occurrences of any delimiters are treated as if there
were only one occurrence; this one occurrence is moved to the delimiter
receiving field (identifier-5), if specified. The delimiting characters in the
sending field are treated as an elementary item of the same usage and
category as identifier-1 and are moved into the current delimiter receiving
field according to the rules of the MOVE statement.
When DELIMITED BY ALL is not specified, and two or more contiguous
occurrences of any delimiter are encountered, the current data receiving
field (identifier-4) is filled with spaces or zeros, according to the description
of the data receiving field.

Delimiter with two or more characters

A delimiter that contains two or more characters is recognized as a delimiter only

if the delimiting characters are in both of the following cases:
v Contiguous
v In the sequence specified in the sending field

Two or more delimiters

When two or more delimiters are specified, an OR condition exists, and each
nonoverlapping occurrence of any one of the delimiters is recognized in the
sending field in the sequence specified.

For example:
DELIMITED BY "AB" or "BC"

An occurrence of either AB or BC in the sending field is considered a delimiter. An

occurrence of ABC is considered an occurrence of AB.

INTO phrase

This phrase specifies the fields where the data is to be moved.

identifier-4 represents the data receiving fields.

472 Enterprise COBOL for z/OS, V6.1 Language Reference

DELIMITER IN
This phrase specifies the fields where the delimiters are to be moved.
identifier-5 represents the delimiter receiving fields.
The DELIMITER IN phrase must not be specified if the DELIMITED BY
phrase is not specified.
COUNT IN
This phrase specifies the field where the count of examined character
positions is held.
identifier-6 is the data count field for each data transfer. Each field holds the
count of examined character positions in the sending field, terminated by
the delimiters or the end of the sending field, for the move to this
receiving field. The delimiters are not included in this count.
The COUNT IN phrase must not be specified if the DELIMITED BY phrase
is not specified.

POINTER phrase

When the POINTER phrase is specified, the value of the pointer field, identifier-7,
behaves as if it were increased by 1 for each examined character position in the
sending field. When execution of the UNSTRING statement is completed, the
pointer field contains a value equal to its initial value plus the number of character
positions examined in the sending field.

When this phrase is specified, the user must initialize the pointer field before
execution of the UNSTRING statement begins.

TALLYING IN phrase

When the TALLYING phrase is specified, the area count field, identifier-8, contains
(at the end of execution of the UNSTRING statement) a value equal to the initial
value plus the number of data receiving areas acted upon.

When this phrase is specified, the user must initialize the area count field before
execution of the UNSTRING statement begins.

ON OVERFLOW phrases

An overflow condition exists when:

v The pointer value (explicit or implicit) is less than 1.
v The pointer value (explicit or implicit) exceeds a value equal to the length of the
sending field.
v All data receiving fields have been acted upon and the sending field still
contains unexamined character positions.

When an overflow condition occurs

An overflow condition results in the following actions:

1. No more data is transferred.
2. The UNSTRING operation is terminated.
3. The NOT ON OVERFLOW phrase, if specified, is ignored.
4. Control is transferred to the end of the UNSTRING statement or, if the ON
OVERFLOW phrase is specified, to imperative-statement-1.

Chapter 20. PROCEDURE DIVISION statements 473

 imperative-statement-1
Statement or statements for dealing with an overflow condition.
If control is transferred to imperative-statement-1, execution continues
according to the rules for each statement specified in imperative-
statement-1. If a procedure branching or conditional statement that causes
explicit transfer of control is executed, control is transferred according to
the rules for that statement. Otherwise, upon completion of the execution
of imperative-statement-1, control is transferred to the end of the UNSTRING
statement.

When an overflow condition does not occur

When, during execution of an UNSTRING statement, conditions that would cause

an overflow condition are not encountered, then:
1. The transfer of data is completed.
2. The ON OVERFLOW phrase, if specified, is ignored.
3. Control is transferred to the end of the UNSTRING statement or, if the NOT
ON OVERFLOW phrase is specified, to imperative-statement-2.
imperative-statement-2
Statement or statements for dealing with an overflow condition that does
not occur.
If control is transferred to imperative-statement-2, execution continues
according to the rules for each statement specified in imperative-
statement-2. If a procedure branching or conditional statement that causes
explicit transfer of control is executed, control is transferred according to
the rules for that statement. Otherwise, upon completion of the execution
of imperative-statement-2, control is transferred to the end of the UNSTRING
statement.

END-UNSTRING phrase

This explicit scope terminator serves to delimit the scope of the UNSTRING
statement. END-UNSTRING permits a conditional UNSTRING statement to be
nested in another conditional statement. END-UNSTRING can also be used with
an imperative UNSTRING statement.

For more information, see “Delimited scope statements” on page 288.

Data flow
The data flow for the UNSTRING statement is based on certain rules.

When the UNSTRING statement is initiated, data is transferred from the sending
field to the current data receiving field, according to the following rules:

Stage 1: Examine
1. If the POINTER phrase is specified, the field is examined, beginning at the
relative character position specified by the value in the pointer field.
If the POINTER phrase is not specified, the sending field character-string is
examined, beginning with the leftmost character position.
2. If the DELIMITED BY phrase is specified, the examination proceeds from left to
right, examining character positions one-by-one until a delimiter is
encountered. If the end of the sending field is reached before a delimiter is

474 Enterprise COBOL for z/OS, V6.1 Language Reference

 found, the examination ends with the last character position in the sending
field. If there are more receiving fields, the next one is selected; otherwise, an
overflow condition occurs.
If the DELIMITED BY phrase is not specified, the number of character positions
examined is equal to the size of the current data receiving field, as described in
the table below. The size depends on the category treatment of the receiving
field, as shown in Table 37 on page 368.
Table 49. Character positions examined when DELIMITED BY is not specified
The number of character positions
If the receiving field is ... examined is ...
Alphanumeric or alphabetic Equal to the number of alphanumeric
character positions in the current receiving
field
DBCS Equal to the number of DBCS character
positions in the current receiving field
National Equal to the number of national character
positions in the current receiving field
Numeric Equal to the number of character positions
in the integer portion of the current
receiving field
Described with the SIGN IS SEPARATE 1 less than the size of the current receiving
clause field
Described as a variable-length data item Determined by the size of the current
receiving field at the beginning of the
UNSTRING operation

Stage 2: Move
3. The examined character positions (excluding any delimiter characters) are
treated as an elementary data item of the same data category as the sending
field except for the cases shown in the table below.

Category of identifier-1 (sending-field) Category of elementary data item

Alphanumeric-edited Alphanumeric
National-edited National

That elementary data item is moved to the current data receiving field
according to the rules for the MOVE statement for the categories of the sending
and receiving fields as described in “MOVE statement” on page 393.
4. If the DELIMITER IN phrase is specified, the delimiting characters in the
sending field are treated as an elementary alphanumeric item and are moved to
the current delimiter receiving field, according to the rules for the MOVE
statement. If the delimiting condition is the end of the sending field, the current
delimiter receiving field is filled with spaces.
5. If the COUNT IN phrase is specified, a value equal to the number of examined
character positions (excluding any delimiters) is moved into the data count
field, according to the rules for an elementary move.
Stage 3: Successive iterations
6. If the DELIMITED BY phrase is specified, the sending field is further examined,
beginning with the first character position to the right of the delimiter.
If the DELIMITED BY phrase is not specified, the sending field is further
examined, beginning with the first character position to the right of the last
character position examined.

Chapter 20. PROCEDURE DIVISION statements 475

 7. For each succeeding data receiving field, this process of examining and moving
is repeated until either of the following conditions occurs:
v All the characters in the sending field have been transferred.
v There are no more unfilled data receiving fields.

Values at the end of execution of the UNSTRING statement

At the beginning of the execution of the UNSTRING statement, certain operations
are performed only once.

The operations are:

v Calculations of subscripts, reference modifications, variable-lengths, variable
locations
v Evaluations of functions

Therefore, if identifier-4, identifier-5, identifier-6, identifier-7, or identifier-8 is used as a

subscript, reference-modifier, or function argument in the UNSTRING statement, or
affects the length or location of any of the identifiers in the UNSTRING statement,
these values are determined at the beginning of the UNSTRING statement, and are
not affected by any results of the UNSTRING statement.

Example of the UNSTRING statement

This topic lists an example for the UNSTRING statement.

The following figure shows the execution results for an example of the UNSTRING
statement.

476 Enterprise COBOL for z/OS, V6.1 Language Reference

Chapter 20. PROCEDURE DIVISION statements 477
WRITE statement
The WRITE statement releases a logical record to an output or input/output file.

When the WRITE statement is executed:

v The associated sequential file must be open in OUTPUT or EXTEND mode.
v The associated indexed or relative file must be open in OUTPUT, I-O, or
EXTEND mode.

Format 1: WRITE statement for sequential files

►► WRITE record-name-1 ►
FROM identifier-1

► phrase 1 ►◄
BEFORE identifier-2 END-WRITE
AFTER ADVANCING integer-1 LINE
LINES
mnemonic-name-1
PAGE
invalid_key not_invalid_key

phrase 1:

►
END-OF-PAGE imperative-statement-3
AT EOP

►
NOT END-OF-PAGE imperative-statement-4
AT EOP

invalid_key:

INVALID imperative-statement-1
KEY

not_invalid_key:

NOT INVALID imperative-statement-2

KEY

478 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 2: WRITE statement for indexed and relative files

►► WRITE record-name-1 ►
FROM identifier-1

► ►
INVALID imperative-statement-1
KEY

► ►◄
NOT INVALID imperative-statement-2 END-WRITE
KEY

Format 3: WRITE statement for line-sequential files

►► WRITE record-name-1 ►
FROM identifier-1

► ►
AFTER identifier-2
ADVANCING integer-1 LINE
LINES
PAGE

► ►◄
END-WRITE

record-name-1
Must be defined in a DATA DIVISION FD entry. record-name-1 can be
qualified. It must not be associated with a sort or merge file.
For relative files, the number of character positions in the record being
written can be different from the number of character positions in the
record being replaced.
FROM phrase
The result of the execution of the WRITE statement with the FROM
identifier-1 phrase is equivalent to the execution of the following statements
in the order specified:
MOVE identifier-1 TO record-name-1.
WRITE record-name-1.

The MOVE is performed according to the rules for a MOVE statement

without the CORRESPONDING phrase.
identifier-1
identifier-1 can reference any of the following items:
v A data item defined in the WORKING-STORAGE SECTION, the
LOCAL-STORAGE SECTION, or the LINKAGE SECTION
v A record description for another previously opened file
v An alphanumeric function

Chapter 20. PROCEDURE DIVISION statements 479

 v A national function
identifier-1 must be a valid sending item for a MOVE statement with
record-name-1 as the receiving item.
identifier-1 and record-name-1 must not refer to the same storage area.
After the WRITE statement is executed, the information is still available in
identifier-1. (See “INTO and FROM phrases” on page 300 under "Common
processing facilities".)
identifier-2
Must be an integer data item.

ADVANCING phrase

The ADVANCING phrase controls positioning of the output record on the page.

The BEFORE and AFTER phrases are not supported for VSAM files. QSAM files
are sequentially organized. The ADVANCING and END-OF-PAGE phrases control
the vertical positioning of each line on a printed page.

You can specify the ADVANCING PAGE and END-OF-PAGE phrases in a single
WRITE statement.

If the printed page is held on an intermediate device (a disk, for example), the
format can appear different from the expected format when the output is edited or
browsed.

ADVANCING phrase rules

When the ADVANCING phrase is specified, the following rules apply:

1. When BEFORE ADVANCING is specified, the line is printed before the page is
advanced.
2. When AFTER ADVANCING is specified, the page is advanced before the line is
printed.
3. When identifier-2 is specified, the page is advanced the number of lines equal to
the current value in identifier-2. identifier-2 must name an elementary integer
data item.
4. When integer is specified, the page is advanced the number of lines equal to
the value of integer.
5. Integer or the value in identifier-2 can be zero.
6. When PAGE is specified, the record is printed on the logical page BEFORE or
AFTER (depending on the phrase used) the device is positioned to the next
logical page. If PAGE has no meaning for the device used, then BEFORE or
AFTER (depending on the phrase specified) ADVANCING 1 LINE is provided.
If the FD entry contains a LINAGE clause, the repositioning is to the first
printable line of the next page, as specified in that clause. If the LINAGE clause
is omitted, the repositioning is to line 1 of the next succeeding page.
7. When mnemonic-name is specified, a skip to channels 1 through 12, or space
suppression, takes place. mnemonic-name must be equated with
environment-name-1 in the SPECIAL-NAMES paragraph.
The mnemonic-name phrase can also be specified for stacker selection with a
card punch file. When using stacker selection, WRITE AFTER ADVANCING
must be used.

480 Enterprise COBOL for z/OS, V6.1 Language Reference

The ADVANCING phrase of the WRITE statement, or the presence of a LINAGE
clause on the file, causes a carriage control character to be generated in the record
that is written. If the corresponding file is described with the EXTERNAL clause,
all file connectors within the run unit must be defined such that carriage control
characters will be generated for records that are written. That is, if all the files have
a LINAGE clause, some of the programs can use the WRITE statement with the
ADVANCING phrase and other programs can use the WRITE statement without
the ADVANCING phrase. However, if none of the files has a LINAGE clause, then
if any of the programs use the WRITE statement with the ADVANCING phrase, all
of the programs in the run unit that have a WRITE statement must use the WRITE
statement with the ADVANCING phrase.

When the ADVANCING phrase is omitted, automatic line advancing is provided,

as if AFTER ADVANCING 1 LINE had been specified.

LINAGE-COUNTER rules

If the LINAGE clause is specified for this file, the associated LINAGE-COUNTER
special register is modified during the execution of the WRITE statement,
according to the following rules:
1. If ADVANCING PAGE is specified, LINAGE-COUNTER is reset to 1.
2. If ADVANCING identifier-2 or integer is specified, LINAGE-COUNTER is
increased by the value in identifier-2 or integer.
3. If the ADVANCING phrase is omitted, LINAGE-COUNTER is increased by 1.
4. When the device is repositioned to the first available line of a new page,
LINAGE-COUNTER is reset to 1.

Usage note: If you use the ADV compiler option, the compiler adds 1 byte to the
record length in order to allow for the control character. If in your record definition
you already reserve the first byte for the control character, you should use the
NOADV option. For files defined with the LINAGE clause, the NOADV option has
no effect. The compiler processes these files as if the ADV option were specified.

END-OF-PAGE phrases

The AT END-OF-PAGE phrase is not supported for VSAM files.

When END-OF-PAGE is specified, and the logical end of the printed page is
reached during execution of the WRITE statement, the END-OF-PAGE
imperative-statement is executed. When the END-OF-PAGE phrase is specified, the
FD entry for this file must contain a LINAGE clause.

The logical end of the printed page is specified in the associated LINAGE clause.

An END-OF-PAGE condition is reached when execution of a WRITE

END-OF-PAGE statement causes printing or spacing within the footing area of a
page body. This occurs when execution of such a WRITE statement causes the
value in the LINAGE-COUNTER special register to equal or exceed the value
specified in the WITH FOOTING phrase of the LINAGE clause. The WRITE
statement is executed, and then the END-OF-PAGE imperative-statement is
executed.

An automatic page overflow condition is reached whenever the execution of any

given WRITE statement (with or without the END-OF-PAGE phrase) cannot be
completely executed within the current page body. This occurs when a WRITE

Chapter 20. PROCEDURE DIVISION statements 481

 statement, if executed, would cause the value in the LINAGE-COUNTER to exceed
the number of lines for the page body specified in the LINAGE clause. In this case,
the line is printed BEFORE or AFTER (depending on the option specified) the
device is repositioned to the first printable line on the next logical page, as
specified in the LINAGE clause. If the END-OF-PAGE phrase is specified, the
END-OF-PAGE imperative-statement is then executed.

If the WITH FOOTING phrase of the LINAGE clause is not specified, the
automatic page overflow condition exists because no end-of-page condition (as
distinct from the page overflow condition) can be detected.

If the WITH FOOTING phrase is specified, but the execution of a given WRITE
statement would cause the LINAGE-COUNTER to exceed both the footing value
and the page body value specified in the LINAGE clause, then both the
end-of-page condition and the automatic page overflow condition occur
simultaneously.

The keywords END-OF-PAGE and EOP are equivalent.

You can specify both the ADVANCING PAGE phrase and the END-OF-PAGE
phrase in a single WRITE statement.

INVALID KEY phrases

The INVALID KEY phrase is not supported for VSAM sequential files.

An invalid key condition is caused by the following cases:

v For sequential files, an attempt is made to write beyond the externally defined
boundary of the file.
v For indexed files:
– An attempt is made to write beyond the externally defined boundary of the
file.
– ACCESS SEQUENTIAL is specified and the file is opened OUTPUT, and the
value of the prime record key is not greater than that of the previous record.
– The file is opened OUTPUT or I-O and the value of the prime record key
equals that of an already existing record.
v For relative files:
– An attempt is made to write beyond the externally defined boundary of the
file.
– When the access mode is random or dynamic and the RELATIVE KEY data
item specifies a record that already exists in the file.
– The number of significant digits in the relative record number is larger than
the size of the relative key data item for the file.

When an invalid key condition occurs:

v If the INVALID KEY phrase is specified, imperative-statement-1 is executed. For
details of invalid key processing, see Invalid key condition.
v Otherwise, the WRITE statement is unsuccessful and the contents of record-name
are unaffected (except for QSAM files) and the following case occurs:
– For sequential files, the file status key, if specified, is updated and an
EXCEPTION/ERROR condition exists.

482 Enterprise COBOL for z/OS, V6.1 Language Reference

 If an explicit or implicit EXCEPTION/ERROR procedure is specified for the
file, the procedure is executed. If no such procedure is specified, the results
are unpredictable.
– For relative and indexed files, program execution proceeds according to the
rules described by Invalid key condition under "Common processing
facilities".
The INVALID KEY conditions that apply to a relative file in OPEN OUTPUT
mode also apply to one in OPEN EXTEND mode.
v If the NOT INVALID KEY phrase is specified and a valid key condition exists at
the end of the execution of the WRITE statement, control is passed to
imperative-statement-4.

Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure

can be omitted.

END-WRITE phrase

This explicit scope terminator serves to delimit the scope of the WRITE statement.
END-WRITE permits a conditional WRITE statement to be nested in another
conditional statement. END-WRITE can also be used with an imperative WRITE
statement.

For more information, see “Delimited scope statements” on page 288.

WRITE for sequential files

The maximum record size for sequential files is established at the time the file is
created and cannot subsequently be changed.

After the WRITE statement is executed, the logical record is no longer available in
record-name-1 unless either:
v The associated file is named in a SAME RECORD AREA clause (in which case,
the record is also available as a record of the other files named in the SAME
RECORD AREA clause)
v The WRITE statement is unsuccessful because of a boundary violation.

In either of these two cases, the logical record is still available in record-name-1.

The file position indicator is not affected by execution of the WRITE statement.

The number of character positions required to store the record in a file might or
might not be the same as the number of character positions defined by the logical
description of that record in the COBOL program. (See “PICTURE clause editing”
on page 215 and “USAGE clause” on page 233.)

If the FILE STATUS clause is specified in the file-control entry, the associated file
status key is updated when the WRITE statement is executed, whether or not
execution is successful.

The WRITE statement can only be executed for a sequential file opened in
OUTPUT or EXTEND mode for QSAM files.

Chapter 20. PROCEDURE DIVISION statements 483

 Punch function files with the IBM 3525

When the punch function is used, the next I-O operation after the READ statement
must be a WRITE statement for the punch function file.

If you want to punch additional data into some of the cards and not into others, a
dummy WRITE statement must be executed for the null cards, first filling the
output area with SPACES.

If stacker selection for the punch function file is required, you can specify the
appropriate stacker function-names in the SPECIAL-NAMES paragraph, and then
code WRITE ADVANCING statements using the associated mnemonic-names.

Print function files

After the punch function operations (if specified) are completed, you can issue
WRITE statements for the print function file.

If you wish to print additional data on some of the data cards and not on others,
the WRITE statement for the null cards can be omitted. Any attempt to write
beyond the limits of the card results in abnormal termination of the application,
thus, the END-OF-PAGE phrase cannot be specified.

Depending on the capabilities of the specific IBM 3525 model in use, the print file
can be either a two-line print file or a multiline print file. Up to 64 characters can
be printed on each line.
v For a two-line print file, the lines are printed on line 1 (top edge of card) and
line 3 (between rows 11 and 12). Line control cannot be specified. Automatic
spacing is provided.
v For a multiline print file, up to 25 lines of characters can be printed. Line control
can be specified. If line control is not specified, automatic spacing is provided.

Line control is specified by issuing WRITE AFTER ADVANCING statements for

the print function file. If line control is used for one such statement, it must be
used for all other WRITE statements for the file. The maximum number of
printable characters, including any space characters, is 64. Such WRITE statements
must not specify space suppression.

Identifier and integer have the same meanings they have for other WRITE AFTER
ADVANCING statements. However, such WRITE statements must not increase the
line position on the card beyond the card limit, or abnormal termination results.

The mnemonic-name option of the WRITE AFTER ADVANCING statement can

also be specified. In the SPECIAL-NAMES paragraph, the environment-names can
be associated with the mnemonic-names, as shown in the following table:
Table 50. Meanings of environment-names in SPECIAL NAMES paragraph
environment-name Meaning
C02 Line 3
C03 Line 5
C04 Line 7
C05 Line 9
... ...

484 Enterprise COBOL for z/OS, V6.1 Language Reference

 Table 50. Meanings of environment-names in SPECIAL NAMES paragraph (continued)
environment-name Meaning
C22 Line 21
C12 Line 23

Advanced Function Printing

When you use the WRITE ADVANCING phrase with a mnemonic-name associated
with environment-name AFP-5A, a Print Services Facility (PSF) control character is
placed in the control character position of the output record. This control character
(X'5A') allows Advanced Function Printing (AFP) services to be used. For more
information, refer to the documentation for the Print Services Facility™ product:
PSF for OS/390® & z/OS (5655-B17).

WRITE for indexed files

Before the WRITE statement is executed for indexed files, you must set the prime
record key (the RECORD KEY data item, as defined in the file-control entry) to the
required value. Note that RECORD KEY values must be unique within a file.

If the ALTERNATE RECORD KEY clause is also specified in the file-control entry,
each alternate record key must be unique, unless the DUPLICATES phrase is
specified. If the DUPLICATES phrase is specified, alternate record key values
might not be unique. In this case, the system stores the records so that later
sequential access to the records allows retrieval in the same order in which they
were stored.

When ACCESS IS SEQUENTIAL is specified in the file-control entry, records must

be released in ascending order of RECORD KEY values.

When ACCESS IS RANDOM or ACCESS IS DYNAMIC is specified in the

file-control entry, records can be released in any programmer-specified order.

WRITE for relative files

For relative record OUTPUT files, the WRITE statement causes actions as described
in the topic.
v If ACCESS IS SEQUENTIAL is specified:
The first record released has relative record number 1, the second record
released has relative record number 2, the third number 3, and so on.
If the RELATIVE KEY is specified in the file-control entry, the relative record
number of the record just released is placed in the RELATIVE KEY during
execution of the WRITE statement.
v If ACCESS IS RANDOM or ACCESS IS DYNAMIC is specified, the RELATIVE
KEY must contain the required relative record number for this record before the
WRITE statement is executed. When the WRITE statement is executed, this
record is placed at the specified relative record number position in the file.

For I-O files, either ACCESS IS RANDOM or ACCESS IS DYNAMIC must be

specified; the WRITE statement inserts new records into the file. The RELATIVE
KEY must contain the required relative record number for this record before the
WRITE statement is executed. When the WRITE statement is executed, this record
is placed at the specified relative record number position in the file.

Chapter 20. PROCEDURE DIVISION statements 485

XML GENERATE statement
The XML GENERATE statement converts data to XML format.

Format

►► XML GENERATE identifier-1 FROM identifier-2 ►

COUNT identifier-3
IN

► ►
ENCODING codepage XML-DECLARATION ATTRIBUTES
WITH WITH WITH

► ►
NAMESPACE identifier-4
IS literal-4 NAMESPACE-PREFIX identifier-5
IS literal-5

► ►

NAME ▼ identifier-6 literal-6

OF IS

► ►

TYPE ▼ identifier-7 ATTRIBUTE

OF IS ELEMENT
CONTENT

► ►

SUPPRESS ▼ identifier-8
when-phrase
generic-suppression-phrase

► ►
EXCEPTION imperative-statement-1
ON

► ►◄
NOT EXCEPTION imperative-statement-2 END-XML
ON

486 Enterprise COBOL for z/OS, V6.1 Language Reference

 when-phrase Format

►► WHEN ZERO ▼ ►◄
ZEROES ZERO
ZEROS OR ZEROES
SPACE ZEROS
SPACES SPACE
LOW-VALUE SPACES
LOW-VALUES LOW-VALUE
HIGH-VALUE LOW-VALUES
HIGH-VALUES HIGH-VALUE
HIGH-VALUES

generic-suppression-phrase Format

►► when-phrase ►◄
EVERY NUMERIC
ATTRIBUTE
CONTENT
ELEMENT
NONNUMERIC
ATTRIBUTE
CONTENT
ELEMENT
ATTRIBUTE
CONTENT
ELEMENT

identifier-1
The receiving area for a generated XML document. identifier-1 must
reference one of the following items:
v An elementary data item of category alphanumeric
v An alphanumeric group item
v An elementary data item of category national
v A national group item
When identifier-1 references a national group item, identifier-1 is processed
as an elementary data item of category national. When identifier-1
references an alphanumeric group item, identifier-1 is treated as though it
were an elementary data item of category alphanumeric.
identifier-1 must not be described with the JUSTIFIED clause, and cannot be
a function identifier. identifier-1 can be subscripted or reference modified.
identifier-1 must not overlap identifier-2, identifier-3, codepage (if an
identifier), identifier-4, or identifier-5.
The generated XML output is encoded as described in the documentation
of the ENCODING phrase.

Chapter 20. PROCEDURE DIVISION statements 487

 identifier-1 must reference a data item of category national, or the
ENCODING phrase must specify 1208, if any of the following statements
are true:
v The CODEPAGE compiler option specifies an EBCDIC DBCS code page.
v identifier-4 or identifier-5 references a data item of category national.
v literal-4, literal-5, or literal-6 is of category national.
v The generated XML includes data from identifier-2 for:
– Any data item of class national or class DBCS
– Any data item with a DBCS name (that is, a data item whose name
consists of DBCS characters)
– Any data item of class alphanumeric that contains DBCS characters
identifier-1 must be large enough to contain the generated XML document.
Typically, it must be from 5 to 10 times the size of identifier-2, depending
on the length of the data-name or data-names within identifier-2. If
identifier-1 is not large enough, an error condition exists at the end of the
XML GENERATE statement.
identifier-2
The group or elementary data item to be converted to XML format.
If identifier-2 references a national group item, identifier-2 is processed as a
group item. When identifier-2 includes a subordinate national group item,
that subordinate item is processed as a group item.
identifier-2 cannot be a function identifier or be reference modified, but it
can be subscripted.
identifier-2 must not overlap identifier-1 or identifier-3.
identifier-2 must not specify the RENAMES clause.
The following data items that are specified by identifier-2 are ignored by
the XML GENERATE statement:
v Any subordinate unnamed elementary data items or elementary FILLER
data items
v Any slack bytes inserted for SYNCHRONIZED items
v Any data item subordinate to identifier-2 that is described with the
REDEFINES clause or that is subordinate to such a redefining item
v Any data item subordinate to identifier-2 that is described with the
RENAMES clause
v Any group data item all of whose subordinate data items are ignored
All data items specified by identifier-2 that are not ignored according to the
previous rules must satisfy the following conditions:
v Each elementary data item must either have class alphabetic,
alphanumeric, numeric, or national, or be an index data item. (That is,
no elementary data item can be described with the USAGE POINTER,
USAGE FUNCTION-POINTER, USAGE PROCEDURE-POINTER, or
USAGE OBJECT REFERENCE phrase.)
v There must be at least one such elementary data item.
v Each non-FILLER data-name must be unique within any immediately
superordinate group data item.
v Any DBCS data-names, when converted to Unicode, must be legal as
names in the XML specification, version 1.0. For details about the XML
specification, see XML specification.

488 Enterprise COBOL for z/OS, V6.1 Language Reference

 For example, consider the following data declaration:
01 STRUCT.
02 STAT PIC X(4).
02 IN-AREA PIC X(100).
02 OK-AREA REDEFINES IN-AREA.
03 FLAGS PIC X.
03 PIC X(3).
03 COUNTER USAGE COMP-5 PIC S9(9).
03 ASFNPTR REDEFINES COUNTER USAGE FUNCTION-POINTER.
03 UNREFERENCED PIC X(92).
02 NG-AREA1 REDEFINES IN-AREA.
03 FLAGS PIC X.
03 PIC X(3).
03 PTR USAGE POINTER.
03 ASNUM REDEFINES PTR USAGE COMP-5 PIC S9(9).
03 PIC X(92).
02 NG-AREA2 REDEFINES IN-AREA.
03 FN-CODE PIC X.
03 UNREFERENCED PIC X(3).
03 QTYONHAND USAGE BINARY PIC 9(5).
03 DESC USAGE NATIONAL PIC N(40).
03 UNREFERENCED PIC X(12).

The following data items from the previous example can be specified as
identifier-2:
v STRUCT, of which subordinate data items STAT and IN-AREA would be
converted to XML format. (OK-AREA, NG-AREA1, and NG-AREA2 are ignored
because they specify the REDEFINES clause.)
v OK-AREA, of which subordinate data items FLAGS, COUNTER, and
UNREFERENCED would be converted. (The item whose data description
entry specifies 03 PIC X(3) is ignored because it is an elementary
FILLER data item. ASFNPTR is ignored because it specifies the
REDEFINES clause.)
v Any of the elementary data items that are subordinate to STRUCT except:
– ASFNPTR or PTR (disallowed usage)
– UNREFERENCED OF NG-AREA2 (nonunique names for data items that are
otherwise eligible)
– Any FILLER data items
The following data items cannot be specified as identifier-2:
v NG-AREA1, because subordinate data item PTR specifies USAGE POINTER
but does not specify the REDEFINES clause. (PTR would be ignored if it
specified the REDEFINES clause.)
v NG-AREA2, because subordinate elementary data items have the
nonunique name UNREFERENCED.
COUNT IN phrase
If the COUNT IN phrase is specified, identifier-3 contains (after execution
of the XML GENERATE statement) the count of generated XML character
encoding units. If identifier-1 (the receiver) has category national, the count
is in UTF-16 character encoding units. For all other encodings (including
UTF-8), the count is in bytes.
identifier-3
The data count field. Must be an integer data item defined without
the symbol P in its picture string.
identifier-3 must not overlap identifier-1, identifier-2, codepage (if an
identifier), identifier-4, or identifier-5.

Chapter 20. PROCEDURE DIVISION statements 489

 ENCODING phrase
The ENCODING phrase, if specified, determines the encoding of the
generated XML document.
codepage
Must be an unsigned integer data item or unsigned integer literal
and must represent a valid coded character set identifier (CCSID).
Must identify one of the code pages supported for COBOL XML
processing as described in The encoding of XML documents in the
Enterprise COBOL Programming Guide.
If identifier-1 references a data item of category national, codepage
must specify 1200, the CCSID for Unicode UTF-16.
If identifier-1 references a data item of category alphanumeric,
codepage must specify 1208 or the CCSID of a supported EBCDIC
code page as listed in The encoding of XML documents in the
Enterprise COBOL Programming Guide.
If codepage is an identifier, it must not overlap identifier-1 or
identifier-3.
If the ENCODING phrase is omitted and identifier-1 is of category national,
the document encoding is Unicode UTF-16, CCSID 1200.
If the ENCODING phrase is omitted and identifier-1 is of category
alphanumeric, the XML document is encoded using the code page
specified by the CODEPAGE compiler option in effect when the source
code was compiled.
XML-DECLARATION phrase
If the XML-DECLARATION phrase is specified, the generated XML
document starts with an XML declaration that includes the XML version
information and an encoding declaration.
If identifier-1 is of category national, the encoding declaration has the value
UTF-16 (encoding="UTF-16").
If identifier-1 is of category alphanumeric, the encoding declaration is
derived from the ENCODING phrase, if specified, or from the CODEPAGE
compiler option in effect for the program if the ENCODING phrase is not
specified. See the description of the ENCODING phrase for further details.
For an example of the effect of coding the XML-DECLARATION phrase,
see Generating XML output in the Enterprise COBOL Programming Guide.
If the XML-DECLARATION phrase is omitted, the generated XML
document does not include an XML declaration.
ATTRIBUTES phrase
If the ATTRIBUTES phrase is specified, each eligible item included in the
generated XML document is expressed as an attribute of the XML element
that corresponds to the data item immediately superordinate to that
eligible item, rather than as a child element of the XML element. To be
eligible, a data item must be elementary, must have a name other than
FILLER, and must not specify an OCCURS clause in its data description
entry.
If the TYPE phrase is specified for particular identifiers, the TYPE phrase
takes precedence for those identifiers over the WITH ATTRIBUTES phrase.
For an example of the effect of the ATTRIBUTES phrase, see Generating
XML output in the Enterprise COBOL Programming Guide.

490 Enterprise COBOL for z/OS, V6.1 Language Reference

NAMESPACE and NAMESPACE-PREFIX phrases
Use the NAMESPACE phrase to identify a namespace for the generated
XML document. If the NAMESPACE phrase is not specified, or if
identifier-4 has length zero or contains all spaces, the element names of
XML documents produced by the XML GENERATE statement are not in
any namespace.
Use the NAMESPACE-PREFIX phrase to qualify the start and end tag of
each element in the generated XML document with a prefix.
If the NAMESPACE-PREFIX phrase is not specified, or if identifier-5 is of
length zero or contains all spaces, the namespace specified by the
NAMESPACE phrase specifies the default namespace for the document. In
this case, the namespace declared on the root element applies by default to
each element name in the document, including that of the root element.
(Default namespace declarations do not apply directly to attribute names.)
If the NAMESPACE-PREFIX phrase is specified, and identifier-5 is not of
length zero and does not contain all spaces, then the start and end tag of
each element in the generated document is qualified with the specified
prefix. The prefix should therefore preferably be short. When the XML
GENERATE statement is executed, the prefix must be a valid XML name,
but without the colon (:), as defined in Namespaces in XML 1.0. The prefix
can have trailing spaces, which are removed before use.
identifier-4, literal-4; identifier-5, literal-5
identifier-4, literal-4: The namespace identifier, which must be a
valid Uniform Resource Identifier (URI) as defined in Uniform
Resource Identifier (URI): Generic Syntax.
identifier-5, literal-5: The namespace prefix, which serves as an alias
for the namespace identifier.
identifier-4 and identifier-5 must reference data items of category
alphanumeric or national.
identifier-4 and identifier-5 must not overlap identifier-1 or
identifier-3.
literal-4 and literal-5 must be of category alphanumeric or national,
and must not be figurative constants.
For full details about namespaces, see Namespaces in XML 1.0.
For examples that show the use of the NAMESPACE and
NAMESPACE-PREFIX phrases, see Generating XML output in the Enterprise
COBOL Programming Guide.
NAME phrase
Allows you to supply element and attribute names.
identifier-6 must reference identifier-2 or one of its subordinate data items.
It cannot be a function identifier and cannot be reference modified or
subscripted. It must not specify any data item which is ignored by the
XML GENERATE statement. For more information about identifier-2, see
the description of identifier-2. If identifier-6 is specified more than once in
the NAME phrase, the last specification is used.
literal-6 must be an alphanumeric or national literal containing the
attribute or element name to be generated in the XML document
corresponding to identifier-6. It must be a valid XML local name. If literal-6

Chapter 20. PROCEDURE DIVISION statements 491

 is a national literal, identifier-1 must reference a data item of category
national or the encoding phrase must specify 1208.
TYPE phrase
Allows you to control attribute and element generation.
identifier-7 must reference an elementary data item that is subordinate to
identifier-2. It cannot be a function identifier and cannot be reference
modified or subscripted. It must not specify any data item which is
ignored by the XML GENERATE statement. For more information about
identifier-2, see the description of identifier-2. If identifier-7 is specified more
than once in the TYPE phrase, the last specification is used.
v If the XML GENERATE statement also includes a WITH ATTRIBUTES
phrase, the TYPE phrase has precedence for identifier-7.
v When ATTRIBUTE is specified, identifier-7 must be eligible to be an XML
attribute. identifier-7 is expressed in the generated XML as an attribute of
the XML element immediately superordinate to identifier-7 rather than as
a child element.
v When ELEMENT is specified, identifier-7 is expressed in the generated
XML as an element. The XML element name is derived from identifier-7
and the element character content is derived from the converted content
of identifier-7 as described in “Operation of XML GENERATE” on page
494.
v When CONTENT is specified, identifier-7 is expressed in the generated
XML as element character content of the XML element that corresponds
to the data item immediately superordinate to identifier-7. The value of
the element character content is derived from the converted content of
identifier-7 as described in “Operation of XML GENERATE” on page 494.
When CONTENT is specified for multiple identifiers all corresponding
to the same superordinate identifier, the multiple contributions to the
element character content are concatenated.
SUPPRESS phrase
Allows you to identify and unconditionally suppress items that are
subordinate to identifier-2 and selectively generate output for the XML
GENERATE statement. If the SUPPRESS phrase is specified, identifier-1
must be large enough to contain the generated XML document before any
suppression.
With the generic-suppression-phrase, elementary items subordinate to
identifier-2 that are not otherwise ignored by XML GENERATE operations
are identified generically for potential suppression. Either items of class
numeric, if the NUMERIC keyword is specified, or items that are not of
class numeric, if the NONNUMERIC keyword is specified, or both, might
be suppressed. If the ATTRIBUTE keyword is specified, only items that
would be expressed in the generated XML document as an XML attribute
are identified for potential suppression. If the ELEMENT keyword is
specified, only items that would be expressed in the generated XML
document as an XML element are identified for potential suppression. If
the CONTENT keyword is specified, only items that would be expressed
in the generated XML document as element character content of the XML
element corresponding to the data item superordinate to the CONTENT
data item are identified for potential suppression.
If multiple generic-suppression-phrase are specified, the effect is cumulative.
identifier-8 explicitly identifies items for potential suppression. If the
WHEN phrase is specified, identifier-8 must reference an elementary data

492 Enterprise COBOL for z/OS, V6.1 Language Reference

 item that is subordinate to identifier-2 and that is not otherwise ignored by
the XML GENERATE operations. identifier-8 cannot be a function identifier
and cannot be reference modified or subscripted.If the WHEN phrase is
omitted, identifier-8 can reference not only an elementary data item but also
a group data item. That group data item and all data items that are
subordinate to the group item are suppressed. If identifier-8 is specified
more than once in the SUPPRESS phrase, the last specification is used. The
explicit suppression specification for identifier-8 overrides the suppression
specification that is implied by any generic-suppression-phrase, if identifier-8
is also one of the identifiers generically identified.
If identifier-8 is specified, the following rules apply to it:
v If ZERO, ZEROES, or ZEROS is specified in the WHEN phrase,
identifier-8 must not be of USAGE DISPLAY-1.
v If SPACE or SPACES is specified in the WHEN phrase, identifier-8 must
be of USAGE DISPLAY, DISPLAY-1, or NATIONAL. If identifier-8 is a
zoned or national decimal item, it must be an integer.
v If LOW-VALUE, LOW-VALUES, HIGH-VALUE, or HIGH-VALUES is
specified in the WHEN phrase, identifier-8 must be of USAGE DISPLAY
or NATIONAL. If identifier-8 is a zoned or national decimal item, it must
be an integer.
If the generic-suppression-phrase is specified, data items are selected for
potential suppression according to the following rules:
v If ZERO, ZEROES, or ZEROS is specified in the WHEN phrase, all data
items except those that are defined with USAGE DISPLAY-1 are selected.
v If SPACE or SPACES is specified in the WHEN phrase, data items of
USAGE DISPLAY, DISPLAY-1, or NATIONAL are selected. For zoned or
national decimal items, only integers are selected.
v If LOW-VALUE, LOW-VALUES, HIGH-VALUE, or HIGH-VALUES is
specified in the WHEN phrase, data items of USAGE DISPLAY or
NATIONAL are selected. For zoned or national decimal items, only
integers are selected.
The comparison operation that determines whether an item will be
suppressed is a relation condition as shown in the table of Comparisons
involving figurative constants. That is, the comparison is a numeric
comparison if the value specified is ZERO, ZEROS, or ZEROES, and the
item is of class numeric. For all other cases, the comparison operation is an
alphanumeric, DBCS, or national comparison, depending on whether the
item is of usage DISPLAY, DISPLAY-1 or NATIONAL, respectively.
When the SUPPRESS phrase is specified, a group item subordinate to
identifier-2 is suppressed in the generated XML document if all the eligible
| items subordinate to the group item are suppressed or if, after suppressing
| any subordinate items, the XML corresponding to the group item would be
| an empty element with no attributes. The root element is always
generated, even if all the items subordinate to identifier-2 are suppressed.
ON EXCEPTION phrase
An exception condition exists when an error occurs during generation of
the XML document, for example if identifier-1 is not large enough to
contain the generated XML document. In this case, XML generation stops
and the content of the receiver, identifier-1, is undefined. If the COUNT IN
phrase is specified, identifier-3 contains the number of character positions
that were generated, which can range from 0 to the length of identifier-1.

Chapter 20. PROCEDURE DIVISION statements 493

 If the ON EXCEPTION phrase is specified, control is transferred to
imperative-statement-1. If the ON EXCEPTION phrase is not specified, the
NOT ON EXCEPTION phrase, if any, is ignored, and control is transferred
to the end of the XML GENERATE statement. Special register XML-CODE
contains an exception code, as detailed in Handling XML GENERATE
exceptions in the Enterprise COBOL Programming Guide.
NOT ON EXCEPTION phrase
If an exception condition does not occur during generation of the XML
document, control is passed to imperative-statement-2, if specified, otherwise
to the end of the XML GENERATE statement. The ON EXCEPTION
phrase, if specified, is ignored. Special register XML-CODE contains zero
after execution of the XML GENERATE statement.
END-XML phrase
This explicit scope terminator delimits the scope of XML GENERATE or
XML PARSE statements. END-XML permits a conditional XML GENERATE
or XML PARSE statement (that is, an XML GENERATE or XML PARSE
statement that specifies the ON EXCEPTION or NOT ON EXCEPTION
phrase) to be nested in another conditional statement.
The scope of a conditional XML GENERATE or XML PARSE statement can
be terminated by:
v An END-XML phrase at the same level of nesting
v A separator period
END-XML can also be used with an XML GENERATE or XML PARSE
statement that does not specify either the ON EXCEPTION or the NOT ON
EXCEPTION phrase.
For more information about explicit scope terminators, see “Delimited
scope statements” on page 288.

Nested XML GENERATE or XML PARSE statements

When a given XML GENERATE or XML PARSE statement appears as
imperative-statement-1 or imperative-statement-2, or as part of imperative-statement-1 or
imperative-statement-2 of another XML GENERATE or XML PARSE statement, that
given XML GENERATE or XML PARSE statement is a nested XML GENERATE or
XML PARSE statement.

Nested XML GENERATE or XML PARSE statements are considered to be matched

XML GENERATE and END-XML combinations, or XML PARSE and END-XML
combinations, proceeding from left to right. Thus, any END-XML phrase that is
encountered is matched with the nearest preceding XML GENERATE or XML
PARSE statement that has not been implicitly or explicitly terminated.

Operation of XML GENERATE

The content of each eligible elementary data item within identifier-2 that has not
been suppressed from XML generation according to a SUPPRESS phrase, is
converted to character format.

Only the first definition of each storage area is processed. Redefinitions of data
items are not included. Data items that are effectively defined by the RENAMES
clause are also not included.

494 Enterprise COBOL for z/OS, V6.1 Language Reference

 For information about the format conversion of elementary data, see “Format
conversion of elementary data” on page 496 and “Trimming of generated XML
data” on page 497.

If the TYPE OF phrase is specified, the converted content is then processed as

element character content or attribute value, according to the specifications on that
phrase. If the TYPE OF phrase is not specified, by default the converted content is
inserted as element character content, or, if the WITH ATTRIBUTES phrase is
specified and the data item is eligible to be expressed as an attribute, as the value
of the attribute, in the generated XML document.

The XML element names and attribute names are obtained from the NAME phrase
if specified; otherwise by default they are derived from the data-names within
identifier-2 as described in “XML element name and attribute name formation” on
page 497. The names of group items that contain the selected elementary items are
retained as parent elements. If the NAMESPACE-PREFIX phrase is specified, the
prefix value, minus any trailing spaces, is used to qualify the start and end tag of
each element.

No extra white space (new lines, indentation, and so forth) is inserted to make the
generated XML more readable. An XML declaration is generated if the
XML-DECLARATION phrase is specified.

If the receiving area specified by identifier-1 is not large enough to contain the
resulting XML document, an error condition exists. See the description of the ON
EXCEPTION phrase above for details.

If identifier-1 is longer than the generated XML document, only that part of
identifier-1 in which XML is generated is changed. The rest of identifier-1 contains
the data that was present before this execution of the XML GENERATE statement.
To avoid referring to that data, either initialize identifier-1 to spaces before the XML
GENERATE statement or specify the COUNT IN phrase.

If the COUNT IN phrase is specified, identifier-3 contains (after execution of the

XML GENERATE statement) the total number of character positions (UTF-16
encoding units or bytes) that were generated. You can use identifier-3 as a reference
| modification length field to refer to the part of identifier-1 that contains the
generated XML document.

After execution of the XML GENERATE statement, special register XML-CODE

contains either zero, which indicates successful completion, or a nonzero exception
code. For details, see Handling XML GENERATE exceptions in the Enterprise COBOL
Programming Guide.

The XML PARSE statement also uses special register XML-CODE. Therefore if you
code an XML GENERATE statement in the processing procedure of an XML
PARSE statement, save the value of XML-CODE before that XML GENERATE
statement executes and restore the saved value after the XML GENERATE
statement terminates.

A byte order mark is not generated for XML documents that have Unicode
encoding.

Chapter 20. PROCEDURE DIVISION statements 495

 Format conversion of elementary data
Elementary data items within identifier-2 are converted in a sequence of several
steps, some of them are optional as described below.

Conversion to character format:

Elementary data items are converted to character format depending on the type of
the data item:
v Data items of category alphabetic, alphanumeric, alphanumeric-edited, DBCS,
external floating-point, national, national-edited, and numeric-edited are not
converted.
v Fixed-point numeric data items other than COMPUTATIONAL-5 (COMP-5)
binary data items or binary data items compiled with the TRUNC(BIN) compiler
option are converted as if they were moved to a numeric-edited item that has:
– As many integer positions as the numeric item has, but with at least one
integer position
– An explicit decimal point, if the numeric item has at least one decimal
position
– The same number of decimal positions as the numeric item has
– A leading '-' picture symbol if the data item is signed (has an S in its
PICTURE clause)
v COMPUTATIONAL-5 (COMP-5) binary data items or binary data items
compiled with the TRUNC(BIN) compiler option are converted in the same way
as the other fixed-point numeric items, except for the number of integer
positions. The number of integer positions is computed depending on the
number of '9' symbols in the picture character string as follows:
– 5 minus the number of decimal places, if the data item has 1 to 4 '9' picture
symbols
– 10 minus the number of decimal places, if the data item has 5 to 9 '9' picture
symbols
– 20 minus the number of decimal places, if the data item has 10 to 18 '9'
picture symbols
v Internal floating-point data items are converted as if they were moved to a data
item as follows:
– For COMP-1: an external floating-point data item with PICTURE -9.9(8)E+99
– For COMP-2: an external floating-point data item with PICTURE -9.9(17)E+99
(illegal because of the number of digit positions)
v Index data items are converted as if they were declared USAGE COMP-5
PICTURE S9(9).

Trimming:

After any conversion to character format, leading and trailing spaces and leading
zeroes are eliminated, as described under “Trimming of generated XML data” on
page 497.

Conversion to the document encoding:

If identifier-1 is a data item of category national, any nonnational values are

converted to national format.

Conversion of special characters to XML references:

496 Enterprise COBOL for z/OS, V6.1 Language Reference

 Any remaining instances of the five characters & (ampersand), ’ (apostrophe), >
(greater-than sign), < (less-than sign), and " (quotation mark) are converted into
the equivalent XML references '&amp;', '&apos;', '&gt;', '<', and '&quot;',
respectively.

Replacement of out-of-range Unicode characters:

Any remaining Unicode character that has a Unicode scalar value greater than
x'FFFF' is replaced by an XML character reference. For example, if the document
contains a character with Unicode scalar value x'10813', in UTF-16, that value is
represented by the surrogate pair (NX'D802', NX'DC13'), which is replaced by the
reference '&#x10813;'. For a document encoding of UTF-8, the byte sequence that is
equivalent to character reference '&#x10813;' is X'F090A093'.

Trimming of generated XML data

Trimming is performed on data values after their conversion to character format.

For more information about the conversion, see “Format conversion of elementary
data” on page 496.

For values converted from signed numeric values, the leading space is removed if
the value is positive.

For values converted from numeric items, leading zeroes (after any initial minus
sign) up to but not including the digit immediately before the actual or implied
decimal point are eliminated. Trailing zeroes after a decimal point are retained. For
example:
v -012.340 becomes -12.340.
v 0000.45 becomes 0.45.
v 0013 becomes 13.
v 0000 becomes 0.

Character values from data items of class alphabetic, alphanumeric, DBCS, and
national have either trailing or leading spaces removed, depending on whether the
corresponding data items have left (default) or right justification, respectively. That
is, trailing spaces are removed from values whose corresponding data items do not
specify the JUSTIFIED clause. Leading spaces are removed from values whose data
items do specify the JUSTIFIED clause. If a character value consists solely of
spaces, one space remains as the value after trimming is finished.

XML element name and attribute name formation

In the XML documents that are generated from identifier-2, the XML element names
and attribute names are obtained from the NAME phrase if specified; otherwise
they are derived from the names of the data item specified by identifier-2 and from
any eligible data-names that are subordinate to identifier-2.

The formation of XML element name and attribute name is as follows:

v The exact mixed-case spelling of data-names from the data description entry is
retained. The spellings from any references to data items (for example, in an
OCCURS DEPENDING ON clause) are not used.
v Data-names that start with a digit are prefixed by an underscore. For example,
the data-name '3D' becomes XML tag or attribute name '_3D'.

Chapter 20. PROCEDURE DIVISION statements 497

 v Data-names that start with the characters 'xml', in any combination of uppercase
and lowercase, are prefixed by an underscore. For example, the data-name 'Xml'
becomes XML tag or attribute name '_Xml'.

DBCS data-names, when translated to Unicode, must be legal as names in the XML
specification, version 1.0. For details about the XML specification, see XML
specification.

498 Enterprise COBOL for z/OS, V6.1 Language Reference

XML PARSE statement
The XML PARSE statement is the COBOL language interface to either of two
high-speed XML parsers, depending on the setting of the XMLPARSE compiler
option.

The two high-speed XML parsers are:

v The z/OS XML System Services parser, for enhanced parsing capabilities. This
parser is selected by the XMLPARSE(XMLSS) compiler option.
v The XML parser that is provided in the COBOL run time, for compatibility with
Enterprise COBOL for z/OS Version 3. The compatible parser is selected by the
XMLPARSE(COMPAT) compiler option.

The XML PARSE statement parses an XML document into its individual pieces and
passes each piece, one at a time, to a user-written processing procedure.

Format

►► XML PARSE identifier-1 ►

ENCODING codepage RETURNING NATIONAL
WITH

► ►
VALIDATING identifier-2
WITH FILE xml-schema-name-1

► PROCESSING PROCEDURE procedure-name-1 ►

IS THROUGH procedure-name-2
THRU

► ►
EXCEPTION imperative-statement-1
ON

► ►◄
NOT EXCEPTION imperative-statement-2 END-XML
ON

identifier-1
identifier-1 must be an elementary data item of category national, a national
group, an elementary data item of category alphanumeric, or an
alphanumeric group item. identifier-1 cannot be a function-identifier.
identifier-1 contains the XML document character stream.
If identifier-1 is a national group item, identifier-1 is processed as an
elementary data item of category national.
If identifier-1 is of category national, its content must be encoded using
Unicode UTF-16BE (CCSID 1200). If the XMLPARSE(COMPAT) compiler
option is in effect, identifier-1 must not contain any character entities that
are represented using multiple encoding units. Use a character reference to
represent any such characters, for example:
v "&#x67603;" or

Chapter 20. PROCEDURE DIVISION statements 499

 v "&#x10813;"
The letter x must be lowercase.
If identifier-1 is of category alphanumeric, its content must be encoded
using one of the character sets listed in Coded character sets for XML
documents in the Enterprise COBOL Programming Guide. If the
XMLPARSE(COMPAT) compiler option is in effect, and identifier-1 is
alphanumeric and contains an XML document that does not specify an
encoding declaration, the XML document is parsed with the code page
specified by the CODEPAGE compiler option.
If the XMLPARSE(XMLSS) compiler option is in effect, the XML document
is parsed with the code page specified in the ENCODING phrase; if the
ENCODING phrase is not used, the document is parsed with the code
page specified by the CODEPAGE compiler option. Any encoding
declaration in the XML document is ignored.
RETURNING NATIONAL phrase
The RETURNING NATIONAL phrase can be specified only when the
XMLPARSE(XMLSS) compiler option is in effect.
When identifier-1 references a data item of category alphanumeric and the
RETURNING NATIONAL phrase is specified, XML document fragments
are automatically converted to Unicode UTF-16 representation and
returned to the processing procedure in the national special registers
XML-NTEXT, XML-NNAMESPACE, and XML-NNAMESPACE-PREFIX.
When the RETURNING NATIONAL phrase is not specified and identifier-1
references a data item of category alphanumeric, the XML document
fragments are returned to the processing procedure in the alphanumeric
special registers XML-TEXT, XML-NAMESPACE, and XML-NAMESPACE-
PREFIX except that when XMLPARSE(COMPAT) is in effect, text for the
ATTRIBUTE-NATIONAL-CHARACTER and CONTENT-NATIONAL-
CHARACTER XML events is always returned in special register
XML-NTEXT.
When identifier-1 references a national data item, XML document fragments
are always returned in Unicode UTF-16 representation in the national
special registers XML-NTEXT, XML-NNAMESPACE, and
XML-NNAMESPACE-PREFIX.
VALIDATING phrase
The VALIDATING phrase specifies that the parser should validate the
XML document against an XML schema while parsing it. In Enterprise
COBOL, the schema used for XML validation is in a preprocessed format
known as Optimized Schema Representation or OSR. The VALIDATING
phrase can be specified only when the XMLPARSE(XMLSS) compiler
option is in effect.
See Parsing XML documents with validation in the Enterprise COBOL
Programming Guide for details.
If the FILE keyword is not specified, identifier-2 must reference a data item
that contains the optimized XML schema. identifier-2 must be of category
alphanumeric and cannot be a function-identifier.
If the FILE keyword is specified, xml-schema-name-1 identifies an existing
z/OS UNIX file or MVS data set that contains the optimized XML schema.
xml-schema-name-1 must be associated with the external file name of the

500 Enterprise COBOL for z/OS, V6.1 Language Reference

 schema by using the XML-SCHEMA clause. For more information about
the XML-SCHEMA clause, see “SPECIAL-NAMES paragraph” on page 116.

Restriction: XML validation using the FILE keyword is not supported

under CICS®.
During parsing with validation, normal XML events are returned as for
nonvalidating parsing until an exception occurs due to a validation error
or other error in the document.
When an XML document is not valid, the parser signals an XML exception
and passes control to the processing procedure with special register
XML-EVENT containing 'EXCEPTION' and special-register XML-CODE
containing return code 24 in the high-order halfword and a reason code in
the low-order halfword.
For information about the return code and reason code for exceptions that
might occur when parsing XML documents with validation, see XML
PARSE exceptions with XMLPARSE(XMLSS) in effect in the Enterprise COBOL
Programming Guide.
ENCODING phrase
The ENCODING phrase can be specified only when the
XMLPARSE(XMLSS) compiler option is in effect.
The ENCODING phrase specifies an encoding that is assumed for the
source XML document in identifier-1. codepage must be an unsigned integer
data item or an unsigned integer literal that represents a valid coded
character set identifier (CCSID). The ENCODING phrase specification
overrides the encoding specified by the CODEPAGE compiler option. The
encoding specified in any XML declaration is always ignored.
If identifier-1 references a data item of category national, codepage must
specify CCSID 1200, for Unicode UTF-16.
If identifier-1 references a data item of category alphanumeric, codepage
must specify CCSID 1208 for UTF-8 or a CCSID for a supported EBCDIC
or ASCII codepage. See Coded character sets for XML documents in the
Enterprise COBOL Programming Guide for details.
PROCESSING PROCEDURE phrase
Specifies the name of a procedure to handle the various events that the
XML parser generates.
procedure-name-1, procedure-name-2
Must name a section or paragraph in the PROCEDURE DIVISION.
When both procedure-name-1 and procedure-name-2 are specified, if
either is a procedure name in a declarative procedure, both must
be procedure names in the same declarative procedure.
procedure-name-1
Specifies the first (or only) section or paragraph in the processing
procedure.
procedure-name-2
Specifies the last section or paragraph in the processing procedure.

For each XML event, the parser transfers control to the first statement of
the procedure named procedure-name-1. Control is always returned from the
processing procedure to the XML parser. The point from which control is
returned is determined as follows:

Chapter 20. PROCEDURE DIVISION statements 501

 v If procedure-name-1 is a paragraph name and procedure-name-2 is not
specified, the return is made after the execution of the last statement of
the procedure-name-1 paragraph.
v If procedure-name-1 is a section name and procedure-name-2 is not
specified, the return is made after the execution of the last statement of
the last paragraph in the procedure-name-1 section.
v If procedure-name-2 is specified and it is a paragraph name, the return is
made after the execution of the last statement of the procedure-name-2
paragraph.
v If procedure-name-2 is specified and it is a section name, the return is
made after the execution of the last statement of the last paragraph in
the procedure-name-2 section.
The only necessary relationship between procedure-name-1 and
procedure-name-2 is that they define a consecutive sequence of operations to
execute, beginning at the procedure named by procedure-name-1 and ending
with the execution of the procedure named by procedure-name-2.
If there are two or more logical paths to the return point, then
procedure-name-2 can name a paragraph that consists of only an EXIT
statement; all the paths to the return point must then lead to this
paragraph.
The processing procedure consists of all the statements at which XML
events are handled. The range of the processing procedure includes all
statements executed by CALL, EXIT, GO TO, GOBACK, INVOKE, MERGE,
PERFORM, and SORT statements that are in the range of the processing
procedure, as well as all statements in declarative procedures that are
executed as a result of the execution of statements in the range of the
processing procedure.
The range of the processing procedure must not cause the execution of any
GOBACK or EXIT PROGRAM statement, except to return control from a
method or program to which control was passed by an INVOKE or CALL
statement, respectively, that is executed in the range of the processing
procedure.
The range of the processing procedure must not cause the execution of an
XML PARSE statement, unless the XML PARSE statement is executed in a
method or outermost program to which control was passed by an INVOKE
or CALL statement that is executed in the range of the processing
procedure.
A program executing on multiple threads can execute the same XML
statement or different XML statements simultaneously.
The processing procedure can terminate the run unit with a STOP RUN
statement.
For more details about the processing procedure, see “Control flow” on
page 504.
ON EXCEPTION
The ON EXCEPTION phrase specifies imperative statements that are
executed when the XML PARSE statement raises an exception condition.
An exception condition exists when the XML parser detects an error in
processing the XML document. The parser first signals an XML exception
by passing control to the processing procedure with special register
XML-EVENT containing 'EXCEPTION'. The parser also provides a numeric

502 Enterprise COBOL for z/OS, V6.1 Language Reference

 error code in special register XML-CODE, as detailed in Handling XML
PARSE exceptions in the Enterprise COBOL Programming Guide.
An exception condition also exists if the processing procedure sets
XML-CODE to -1 before returning to the parser for any normal XML event.
In this case, the parser does not signal an EXCEPTION XML event and
parsing is terminated.
If the ON EXCEPTION phrase is specified, the parser transfers control to
imperative-statement-1. If the ON EXCEPTION phrase is not specified, the
NOT ON EXCEPTION phrase, if any, is ignored and control is transferred
to the end of the XML PARSE statement.
Special register XML-CODE contains the numeric error code for the XML
exception or -1 after execution of the XML PARSE statement.
If the processing procedure handles the XML exception event and sets
XML-CODE to zero before returning control to the parser, the exception
condition no longer exists. If no other unhandled exceptions occur before
termination of the parser, control is transferred to imperative-statement-2 of
the NOT ON EXCEPTION phrase, if specified.
NOT ON EXCEPTION
The NOT ON EXCEPTION phrase specifies imperative statements that are
executed when no exception condition exists at the termination of XML
PARSE processing.
If an exception condition does not exist at termination of XML PARSE
processing, control is transferred to imperative-statement-2 of the NOT ON
EXCEPTION phrase, if specified. If the NOT ON EXCEPTION phrase is
not specified, control is transferred to the end of the XML PARSE
statement. The ON EXCEPTION phrase, if specified, is ignored.
Special register XML-CODE contains zero after execution of the XML
PARSE statement.
END-XML phrase
This explicit scope terminator delimits the scope of XML GENERATE or
XML PARSE statements. END-XML permits a conditional XML GENERATE
or XML PARSE statement (that is, an XML GENERATE or XML PARSE
statement that specifies the ON EXCEPTION or NOT ON EXCEPTION
phrase) to be nested in another conditional statement.
The scope of a conditional XML GENERATE or XML PARSE statement can
be terminated by:
v An END-XML phrase at the same level of nesting
v A separator period
END-XML can also be used with an XML GENERATE or XML PARSE
statement that does not specify either the ON EXCEPTION or NOT ON
EXCEPTION phrase.
For more information about explicit scope terminators, see “Delimited
scope statements” on page 288.

Nested XML GENERATE or XML PARSE statements

When a given XML GENERATE or XML PARSE statement appears as
imperative-statement-1 or imperative-statement-2, or as part of imperative-statement-1 or

Chapter 20. PROCEDURE DIVISION statements 503

 imperative-statement-2 of another XML GENERATE or XML PARSE statement, that
given XML GENERATE or XML PARSE statement is a nested XML GENERATE or
XML PARSE statement.

Nested XML GENERATE or XML PARSE statements are considered to be matched

XML GENERATE and END-XML, or XML PARSE and END-XML combinations
proceeding from left to right. Thus, any END-XML phrase that is encountered is
matched with the nearest preceding XML GENERATE or XML PARSE statement
that has not been implicitly or explicitly terminated.

Control flow
When the XML parser receives control from an XML PARSE statement, the parser
analyzes the XML document and transfers control at specific points in the process.

The points are:

v The start of the parsing process
v When a document fragment is found
v When the parser detects an error in parsing the XML document
v The end of processing the XML document

Control returns to the XML parser when the end of the processing procedure is
reached.

The exchange of control between the parser and the processing procedure
continues until either:
v The entire XML document has been parsed, ending with the
END-OF-DOCUMENT event.
v The processing procedure terminates parsing deliberately by setting XML-CODE
to -1 before returning to the parser.
v When the XMLPARSE(XMLSS) compiler option is in effect: The parser detects an
exception of any kind.
v When the XMLPARSE(COMPAT) compiler option is in effect: The parser detects
an exception (other than an encoding conflict) and the processing procedure
does not reset special register XML-CODE to zero before to returning to the
parser.
v When the XMLPARSE(COMPAT) compiler option is in effect: The parser detects
an encoding conflict exception and the processing procedure does not reset
special register XML-CODE to zero or to the CCSID of the document encoding.

In each case, the processing procedure returns control to the parser. Then, the
parser terminates and returns control to the XML PARSE statement with the
XML-CODE special register containing the most recent value set by the parser or -1
(which might have been set by the parser or by the processing procedure).

For each XML event passed to the processing procedure, the XML-CODE and
XML-EVENT special registers contain information about the particular event.
Special register XML-EVENT is set to the event name, such as
'START-OF-DOCUMENT'. For most events, the XML-TEXT or XML-NTEXT special
register contains document text. Additionally, when the XMLPARSE(XMLSS)
compiler option is in effect, the XML-NAMESPACE and XML-NAMESPACE-
PREFIX or the XML-NNAMESPACE and XML-NNAMESPACE-PREFIX special
registers contain a namespace identifier and namespace prefix when applicable. See
“XML-EVENT” on page 26 for details.

504 Enterprise COBOL for z/OS, V6.1 Language Reference

The content of the XML-CODE special register is defined during and after
execution of an XML PARSE statement. The contents of all other XML special
registers are undefined outside the range of the processing procedure.

For normal XML events, special register XML-CODE contains zero when the
processing procedure receives control. For XML exception events, XML-CODE
contains an XML exception code as described in XML PARSE exceptions in the
Enterprise COBOL Programming Guide.

For more information about the XML special registers, see:

v “XML-CODE” on page 25
v “XML-EVENT” on page 26
v “XML-INFORMATION” on page 32
v “XML-NAMESPACE” on page 33
v “XML-NAMESPACE-PREFIX” on page 34
v “XML-NNAMESPACE” on page 34
v “XML-NNAMESPACE-PREFIX” on page 35
v “XML-NTEXT” on page 36
v “XML-TEXT” on page 37

For an introduction to special registers, see “Special registers” on page 16

For more information about the EXCEPTION event and exception processing, see
Handling XML PARSE exceptions in the Enterprise COBOL Programming Guide.

Chapter 20. PROCEDURE DIVISION statements 505

506 Enterprise COBOL for z/OS, V6.1 Language Reference
Part 7. Intrinsic functions

© Copyright IBM Corp. 1991, 2017 507

508 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 21. Intrinsic functions
An intrinsic function is a function that performs a mathematical, character, or logical
operation. You can use intrinsic functions to make reference to a data item whose
value is derived automatically during execution.

Data processing problems often require the use of values that are not directly
accessible in the data storage associated with the object program, but instead must
be derived through performing operations on other data. An intrinsic function is a
function that performs a mathematical, character, or logical operation, and thereby
allows you to make reference to a data item whose value is derived automatically
during execution.

The intrinsic functions can be grouped into six categories, based on the type of
service performed:
v Mathematical
v Statistical
v Date/time
v Financial
v Character-handling
v General

You can reference a function by specifying its name, along with any required
arguments, in a PROCEDURE DIVISION statement.

Functions are elementary data items, and return alphanumeric character, national
character, numeric, or integer values. Functions cannot serve as receiving operands.

Specifying a function
This topic describes the general format of a function-identifier.

Format: Function-identifier

►► FUNCTION function-name-1 ►

( ▼ argument-1 )

► ►◄
reference-modifier

function-name-1
function-name-1 must be one of the intrinsic function names.

© Copyright IBM Corp. 1991, 2017 509

 argument-1
argument-1 must be an identifier, a literal (other than a figurative constant),
or an arithmetic expression that satisfies the argument requirements for the
specified function.
reference-modifier
Can be specified only for functions of type alphanumeric or national.

A function-identifier can be specified wherever a data item of the type of the

function is allowed. The argument to a function can be any function or an
expression containing a function, including another evaluation of the same
function, whose result meets the requirements for the argument.

Within a PROCEDURE DIVISION statement, each function-identifier is evaluated

at the same time as any reference modification or subscripting associated with an
identifier in that same position would be evaluated.

Function definition and evaluation

The class and characteristics of a function, and the number and types of arguments
it requires, are determined by its function definition.

These characteristics include:

v For functions of type alphanumeric and national, the size of the returned value
v For functions of type numeric and integer, the sign of the returned value and
whether the function is integer
v The actual value returned by the function

For some functions, the class and characteristics are determined by the arguments
to the function.

The evaluation of any intrinsic function is not affected by the context in which it
appears; in other words, function evaluation is not affected by operations or
operands outside the function. However, evaluation of a function can be affected
by the attributes of its arguments.

Within a PROCEDURE DIVISION statement, each function-identifier is evaluated

at the same time as any reference modification or subscripting associated with an
identifier in that same position would be evaluated.

Types of functions
The topic introduces types of functions in COBOL.

COBOL has the following types of functions:

v Alphanumeric
v National
v Numeric
v Integer

Alphanumeric functions are of class and category alphanumeric. The value returned
has an implicit usage of DISPLAY. The number of character positions in the value
returned is determined by the function definition.

510 Enterprise COBOL for z/OS, V6.1 Language Reference

 National functions are of class and category national. The value returned has an
implicit usage of NATIONAL and is represented in national characters (UTF-16).
The number of character positions in the value returned is determined by the
function definition.

Numeric functions are of class and category numeric. The returned value is always
considered to have an operational sign and is a numeric intermediate result. For
more information, see Using numeric intrinsic functions in the Enterprise COBOL
Programming Guide.

Integer functions are of class and category numeric. The returned value is always
considered to have an operational sign and is an integer intermediate result. The
number of digit positions in the value returned is determined by the function
definition. For more information, see Using numeric intrinsic functions in the
Enterprise COBOL Programming Guide.

Rules for usage

The topic describes rules of using different types of functions.
Alphanumeric functions
An alphanumeric function can be specified anywhere in the general
formats that a data item of class and category alphanumeric is permitted
and where the rules associated with the general formats do not specifically
prohibit reference to functions, except as noted below.
An alphanumeric function can be used as an argument for any function
that allows an alphanumeric argument.
Reference modification of an alphanumeric function is allowed. If reference
modification is specified for a function, the evaluation of the reference
modification takes place immediately after the evaluation of the function;
that is, the function's returned value is reference-modified.
An alphanumeric function cannot be used:
v As a receiving operand of any statement
v Where the rules associated with the general formats require the data
item being referenced to have particular characteristics (such as class and
category, usage, size, and permissible values) and the evaluation of the
function according to its definition and the particular arguments
specified would not have those characteristics
National functions
A national function can be specified anywhere in the general formats that a
data item of class and category national is permitted and where the rules
associated with the general formats do not specifically prohibit reference to
functions, except as noted below.
A national function can be used as an argument for any function that
allows a national argument.
Reference modification of a national function is allowed. If reference
modification is specified for a function, the evaluation of the reference
modification takes place immediately after the evaluation of the function;
that is, the function's returned value is reference-modified.
A national function cannot be used:
v As a receiving operand of any statement

Chapter 21. Intrinsic functions 511

 v Where the rules associated with the general formats require the data
item being referenced to have particular characteristics (such as class and
category, usage, size, and permissible values) and the evaluation of the
function according to its definition and the particular arguments
specified would not have those characteristics
Numeric functions
A numeric function can be used only where an arithmetic expression can
be specified.
A numeric function can be referenced as an argument for a function that
allows a numeric argument.
A numeric function cannot be used where an integer operand is required,
even if the particular reference would yield an integer value. The
INTEGER or INTEGER-PART functions can be used to force the type of a
numeric argument to be an integer.
Integer functions
An integer function can be used only where an arithmetic expression can
be specified.
An integer function can be referenced as an argument for a function that
allows a numeric argument.

Usage notes:
v A function-identifier cannot be used in the BY REFERENCE phrase of a CALL
statement (that is, identifier-2 of the CALL statement must not be a
function-identifier).
v The COPY statement accepts function-identifiers of all types in the REPLACING
phrase.

Arguments
The value returned by some functions is determined by the arguments specified in
the function-identifier when the functions are evaluated. Some functions require no
arguments; others require a fixed number of arguments, and still others accept a
variable number of arguments.

An argument must be one of the following items:

v A data item identifier
v An arithmetic expression
v A function-identifier
v A literal other than a figurative constant
v A special-register

See “Function definitions” on page 516 for function-specific argument

specifications.

The types of arguments are:

Alphabetic
An elementary data item of the class alphabetic or an alphanumeric literal
containing only alphabetic characters. The content of the argument is used
to determine the value of the function. The length of the argument can be
used to determine the value of the function.

512 Enterprise COBOL for z/OS, V6.1 Language Reference

Alphanumeric
A data item of the class alphabetic or alphanumeric or an alphanumeric
literal. The content of the argument is used to determine the value of the
function. The length of the argument can be used to determine the value of
the function.
DBCS An elementary data item of class DBCS or a DBCS literal. The content of
the argument is used to determine the value of the function. The length of
the argument can be used to determine the value of the function. (A DBCS
data item or literal can be used as an argument only for the
NATIONAL-OF function.)
National
A data item of class national (category national, national-edited, or
numeric-edited). The content of the argument is used to determine the
value of the function. The length of the argument can be used to determine
the value of the function.
Integer
An arithmetic expression that always results in an integer value. The value
of the expression, including its sign, is used to determine the value of the
function.
Numeric
An arithmetic expression. The expression can include numeric literals and
data items of categories numeric, internal floating-point, and external
floating-point. The numeric data items can have any usage permitted for
the category of the data item (including NATIONAL). The value of the
expression, including its sign, is used to determine the value of the
function.

Some functions place constraints on their arguments, such as the acceptable range
of values. If the values assigned as arguments for a function do not comply with
specified constraints, the returned value is undefined.

If a nested function is used as an argument, the evaluation of its arguments is not

affected by the arguments in the outer function.

Only those arguments at the same function level interact with each other. This
interaction occurs in two areas:
v The computation of an arithmetic expression that appears as a function
argument is affected by other arguments for that function.
v The evaluation of the function takes into consideration the attributes of all of its
arguments.

When a function is evaluated, its arguments are evaluated individually in the order
specified in the list of arguments, from left to right. The argument being evaluated
can be a function-identifier or an expression that includes function-identifiers.

If an arithmetic expression is specified as an argument and if the first operator in

the expression is a unary plus or a unary minus, the expression must be
immediately preceded by a left parenthesis.

Floating-point literals are allowed wherever a numeric argument is allowed and in

arithmetic expressions used in functions that allow a numeric argument.

Chapter 21. Intrinsic functions 513

 Internal floating-point items and external floating-point items (both display
floating-point and national floating-point) can be used wherever a numeric
argument is allowed and in arithmetic expressions as arguments to a function that
allows a numeric argument.

Floating-point items and floating-point literals cannot be used where an integer

argument is required or where an argument of class alphanumeric or national is
required (such as in the LOWER-CASE, REVERSE, UPPER-CASE, NUMVAL, and
NUMVAL-C functions).

Where a function allows an alphanumeric or national argument to be specified, an

alphanumeric group or national group, respectively, can also be specified.
However, an unbounded group cannot be specified as a function argument, except
when it is used in the LENGTH intrinsic function.

Examples
See examples of using different types of intrinsic functions.

The following statement illustrates the use of intrinsic function UPPER-CASE to

replace each lowercase letter in an alphanumeric argument with the corresponding
uppercase letter.
MOVE FUNCTION UPPER-CASE(’hello’) TO DATA-NAME.

This statement moves HELLO into DATA-NAME.

The following statement illustrates the use of intrinsic function LOWER-CASE to

replace each uppercase letter in a national argument with the corresponding
lowercase letter.
MOVE FUNCTION LOWER-CASE(N’HELLO’) TO N-DATA-NAME.

This statement moves national characters hello into N-DATA-NAME.

The following statement illustrates the use of a numeric intrinsic function:

COMPUTE NUM-ITEM = FUNCTION SUM(A B C)

This statement uses the numeric function SUM to add the values of A, B, and C
and places the result in NUM-ITEM.

ALL subscripting
When a function allows an argument to be repeated a variable number of times,
you can refer to a table by specifying the data-name and any qualifiers that
identify the table. This can be followed immediately by subscripting where one or
more of the subscripts is the word ALL.

Tip: The evaluation of an ALL subscript must result in at least one argument or the
value returned by the function will be undefined; however, the situation can be
diagnosed at run time by specifying the SSRANGE compiler option.

Specifying ALL as a subscript is equivalent to specifying all table elements possible

using every valid subscript in that subscript position.

For a table argument specified as Table-name(ALL), the order of the implicit

specification of each table element as an argument is from left to right, where the
first (or leftmost) argument is Table-name(1) and ALL has been replaced by 1. The

514 Enterprise COBOL for z/OS, V6.1 Language Reference

next argument is Table-name(2), where the subscript has been incremented by 1.
This process continues, with the subscript being incremented by 1 to produce an
implicit argument, until the ALL subscript has been incremented through its range
of values.

For example,
FUNCTION MAX(Table(ALL))

is equivalent to
FUNCTION MAX(Table(1) Table(2) Table(3) ... Table(n))

where n is the number of elements in Table.

If there are multiple ALL subscripts, Table-name(ALL, ALL, ALL), the first implicit
argument is Table-name(1, 1, 1), where each ALL has been replaced by 1. The
next argument is Table-name(1, 1, 2), where the rightmost subscript has been
incremented by 1. The subscript represented by the rightmost ALL is incremented
through its range of values to produce an implicit argument for each value.

Once a subscript specified as ALL has been incremented through its range of
values, the next subscript to the left that is specified as ALL is incremented by 1.
Each subscript specified as ALL to the right of the newly incremented subscript is
set to 1 to produce an implicit argument. Once again, the subscript represented by
the rightmost ALL is incremented through its range of values to produce an
implicit argument for each value. This process is repeated until each subscript
specified as ALL has been incremented through its range of values.

For example,
FUNCTION MAX(Table(ALL, ALL))

is equivalent to
FUNCTION MAX(Table(1, 1) Table(1, 2) Table(1, 3) ... Table(1, n)
Table(2, 1) Table(2, 2) Table(2, 3) ... Table(2, n)
Table(3, 1) Table(3, 2) Table(3, 3) ... Table(3, n)
...
Table(m, 1) Table(m, 2) Table(m, 3) ... Table(m, n))

where n is the number of elements in the column dimension of Table, and m is the
number of elements in the row dimension of Table.

ALL subscripts can be combined with literal, data-name, or index-name subscripts

to reference multidimensional tables.

For example,
FUNCTION MAX(Table(ALL, 2))

is equivalent to
FUNCTION MAX(Table(1, 2)
Table(2, 2)
Table(3, 2)
...
Table(m, 2))

where m is the number of elements in the row dimension of Table.

Chapter 21. Intrinsic functions 515

 If an ALL subscript is specified for an argument and the argument is
reference-modified, then the reference-modifier is applied to each of the implicitly
specified elements of the table.

If an ALL subscript is specified for an operand that is reference-modified, the

reference-modifier is applied to each of the implicitly specified elements of the
table.

If the ALL subscript is associated with an OCCURS DEPENDING ON clause, the

range of values is determined by the object of the OCCURS DEPENDING ON
clause.

For example, given a payroll record definition such as:

01 PAYROLL.
02 PAYROLL-WEEK PIC 99.
02 PAYROLL-HOURS PIC 999 OCCURS 1 TO 52
DEPENDING ON PAYROLL-WEEK.

The following COMPUTE statements could be used to identify total year-to-date

hours, the maximum hours worked in any week, and the specific week
corresponding to the maximum hours:
COMPUTE YTD-HOURS = FUNCTION SUM (PAYROLL-HOURS(ALL))
COMPUTE MAX-HOURS = FUNCTION MAX (PAYROLL-HOURS(ALL))
COMPUTE MAX-WEEK = FUNCTION ORD-MAX (PAYROLL-HOURS(ALL))

In these function invocations, the subscript ALL is used to reference all elements of
the PAYROLL-HOURS array (depending on the execution time value of the
PAYROLL-WEEK field).

Function definitions
This section provides an overview of the argument type, function type, and value
returned for each of the intrinsic functions.

For more information about the intrinsic functions, see Table 51 on page 517.

Argument types and function types are abbreviated as follows:

Abbreviation Meaning
A Alphabetic
D DBCS
I Integer
N Numeric
X Alphanumeric
U National
O Other, as specified in the function definition (pointer,
function-pointer, procedure-pointer, or object reference)

Each intrinsic function is described in detail in the topics that follow the table
below.

516 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 51. Table of functions
Function
Function name Arguments type Value returned
ACOS N1 N Arccosine of N1
ANNUITY N1, I2 N Ratio of annuity paid for I2 periods at interest
of N1 to initial investment of one
ASIN N1 N Arcsine of N1
ATAN N1 N Arctangent of N1
CHAR I1 X Character in position I1 of program collating
sequence
COS N1 N Cosine of N1
CURRENT-DATE None X Current date and time and difference from
Greenwich mean time
DATE-OF-INTEGER I1 I Standard date equivalent (YYYYMMDD) of
integer date
DATE-TO-YYYYMMDD I1, I2 I Standard date equivalent (YYYYMMDD) of I1
(standard date with a windowed year,
YYMMDD), according to the 100-year interval
whose ending year is specified by the sum of I2
and the year at execution time
DAY-OF-INTEGER I1 I Julian date equivalent (YYYYDDD) of integer
date
DAY-TO-YYYYDDD I1, I2 I Julian date equivalent (YYYYDDD) of I1 (Julian
date with a windowed year, YYDDD),
according to the 100-year interval whose ending
year is specified by the sum of I2 and the year
at execution time
DISPLAY-OF U1 or X Each character in U1 converted to a
U1, I2 corresponding character representation using a
code page identified by I2, if specified, or a
default code page selected at compile time if I2
is unspecified
FACTORIAL I1 I Factorial of I1
INTEGER N1 I The greatest integer not greater than N1
INTEGER-OF-DATE I1 I Integer date equivalent of standard date
(YYYYMMDD)
INTEGER-OF-DAY I1 I Integer date equivalent of Julian date
(YYYYDDD)
INTEGER-PART N1 I Integer part of N1
LENGTH A1, N1, O1, I Length of argument in national character
X1, or U1 positions or in alphanumeric character positions
or bytes, depending on the argument type
LOG N1 N Natural logarithm of N1
LOG10 N1 N Logarithm to base 10 of N1
LOWER-CASE A1 or X1 X All letters in the argument set to lowercase
U1 U All letters in the argument set to lowercase

Chapter 21. Intrinsic functions 517

Table 51. Table of functions (continued)
Function
Function name Arguments type Value returned
MAX A1... X Value of maximum argument; note that the
type of function depends on the arguments
I1... I Value of maximum argument; note that the
type of function depends on the arguments
N1... N Value of maximum argument; note that the
type of function depends on the arguments
X1... X Value of maximum argument; note that the
type of function depends on the arguments
U1... U Value of maximum argument; note that the
type of function depends on the arguments
MEAN N1... N Arithmetic mean of arguments
MEDIAN N1... N Median of arguments
MIDRANGE N1... N Mean of minimum and maximum arguments
MIN A1... X Value of minimum argument; note that the type
of function depends on the arguments
I1... I Value of minimum argument; note that the type
of function depends on the arguments
N1... N Value of minimum argument; note that the type
of function depends on the arguments
X1... X Value of minimum argument; note that the type
of function depends on the arguments
U1... U Value of minimum argument; note that the type
of function depends on the arguments
MOD I1, I2 I I1 modulo I2
NATIONAL-OF A1, X1, or D1 U The characters in the argument converted to
national characters, using the code page
identified by I2, if specified, or a default code
page selected at compile time if I2 is
unspecified
A1, X1, or D1; U The characters in the argument converted to
I2 national characters, using the code page
identified by I2, if specified, or a default code
page selected at compile time if I2 is
unspecified
NUMVAL X1 N Numeric value of simple numeric string
NUMVAL-C X1 or N Numeric value of numeric string with optional
X1, X2 commas and currency sign
ORD A1 or X1 I Ordinal position of the argument in collating
sequence
ORD-MAX A1..., N1..., I Ordinal position of maximum argument
X1..., or U1...
ORD-MIN A1..., N1..., I Ordinal position of minimum argument
X1..., or U1...
PRESENT-VALUE N1, N2... N Present value of a series of future period-end
amounts, N2, at a discount rate of N1
RANDOM I1, none N Random number

518 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 51. Table of functions (continued)
Function
Function name Arguments type Value returned
RANGE I1... I Value of maximum argument minus value of
minimum argument; note that the type of
function depends on the arguments.
N1... N Value of maximum argument minus value of
minimum argument; note that the type of
function depends on the arguments.
REM N1, N2 N Remainder of N1/N2
REVERSE A1 or X1 X Reverse order of the characters of the argument
U1 U Reverse order of the characters of the argument
SIN N1 N Sine of N1
SQRT N1 N Square root of N1
STANDARD-DEVIATION N1... N Standard deviation of arguments
SUM I1... I Sum of arguments; note that the type of
function depends on the arguments.
N1... N Sum of arguments; note that the type of
function depends on the arguments.
TAN N1 N Tangent of N1
ULENGTH A1 or X1 I Length of A1 or X1, in UTF-8 characters
UPOS A1 or X1, I2 I Index of the I2th UTF-8 character of A1 or X1
UPPER-CASE A1 or X1 X All letters in the argument set to uppercase
U1 U All letters in the argument set to uppercase
USUBSTR A1 or X1, I2, X Alphanumeric character string that contains the
I3 I3 UTF-8 characters of A1 or X1, starting at the
I2th character position
USUPPLEMENTARY A1, X1 or U1 I Index of the first Unicode supplementary
character of A1, X1 or U1
UVALID A1, X1 or U1 I 0 if A1, X1 or U1 contains valid Unicode UTF-8
or UTF-16 data, or the index of the first invalid
element of A1, X1 or U1
UWIDTH A1 or X1, I2 I Width in bytes of the I2th UTF-8 character of
A1 or X1
VARIANCE N1... N Variance of arguments
WHEN-COMPILED None X Date and time when program was compiled
YEAR-TO-YYYY I1, I2 I Expanded year equivalent (YYYY) of I1
(windowed year, YY), according to the 100-year
interval whose ending year is specified by the
sum of I2 and the year at execution time

ACOS
The ACOS function returns a numeric value in radians that approximates the
arccosine of the argument specified.

The function type is numeric.

Chapter 21. Intrinsic functions 519

 Format

►► FUNCTION ACOS ( argument-1 ) ►◄

argument-1
Must be class numeric. The value of argument-1 must be greater than or
equal to -1 and less than or equal to +1.

The returned value is the approximation of the arccosine of the argument and is
greater than or equal to zero and less than or equal to Pi.

ANNUITY
The ANNUITY function returns a numeric value that approximates the ratio of an
annuity paid at the end of each period, for a given number of periods, at a given
interest rate, to an initial value of one.

The number of periods is specified by argument-2; the rate of interest is specified

by argument-1. For example, if argument-1 is zero and argument-2 is four, the value
returned is the approximation of the ratio 1 / 4.

The function type is numeric.

Format

►► FUNCTION ANNUITY ( argument-1 argument-2 ) ►◄

argument-1
Must be class numeric. The value of argument-1 must be greater than or
equal to zero.
argument-2
Must be a positive integer.

When the value of argument-1 is zero, the value returned by the function is the
approximation of:

1 / argument-2

When the value of argument-1 is not zero, the value of the function is the
approximation of:

argument-1 / (1 - (1 + argument-1) ** (- argument-2))

520 Enterprise COBOL for z/OS, V6.1 Language Reference

ASIN
The ASIN function returns a numeric value in radians that approximates the
arcsine of the argument specified.

The function type is numeric.

Format

►► FUNCTION ASIN ( argument-1 ) ►◄

argument-1
Must be class numeric. The value of argument-1 must be greater than or
equal to -1 and less than or equal to +1.

The returned value is the approximation of the arcsine of argument-1 and is greater
than or equal to -Pi/2 and less than or equal to +Pi/2.

ATAN
The ATAN function returns a numeric value in radians that approximates the
arctangent of the argument specified.

The function type is numeric.

Format

►► FUNCTION ATAN ( argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the approximation of the arctangent of argument-1 and is

greater than -Pi/2 and less than +Pi/2.

CHAR
The CHAR function returns a one-character alphanumeric value that is a character
in the program collating sequence having the ordinal position equal to the value of
the argument specified.

The function type is alphanumeric.

Chapter 21. Intrinsic functions 521

 Format

►► FUNCTION CHAR ( argument-1 ) ►◄

argument-1
Must be an integer. The value must be greater than zero and less than or
equal to the number of positions in the collating sequence associated with
alphanumeric data items (a maximum of 256).

If more than one character has the same position in the program collating
sequence, the character returned as the function value is that of the first literal
specified for that character position in the ALPHABET clause.

If the current program collating sequence was not specified by an ALPHABET

clause, the single-byte EBCDIC collating sequence is used. (See “Conditional
expressions” on page 264.)

COS
The COS function returns a numeric value that approximates the cosine of the
angle or arc specified by the argument in radians.

The function type is numeric.

Format

►► FUNCTION COS ( argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the approximation of the cosine of the argument and is
greater than or equal to -1 and less than or equal to +1.

CURRENT-DATE
The CURRENT-DATE function returns a 21-character alphanumeric value that
represents the calendar date, time of day, and time differential from Greenwich
mean time provided by the system on which the function is evaluated.

The function type is alphanumeric.

Format

►► FUNCTION CURRENT-DATE ►◄

522 Enterprise COBOL for z/OS, V6.1 Language Reference

 Reading from left to right, the 21 character positions of the returned value are as
follows:

Character
positions Contents
1-4 Four numeric digits of the year in the Gregorian calendar
5-6 Two numeric digits of the month of the year, in the range 01 through
12
7-8 Two numeric digits of the day of the month, in the range 01 through 31
9-10 Two numeric digits of the hours past midnight, in the range 00 through
23
11-12 Two numeric digits of the minutes past the hour, in the range 00
through 59
13-14 Two numeric digits of the seconds past the minute, in the range 00
through 59
15-16 Two numeric digits of the hundredths of a second past the second, in
the range 00 through 99. The value 00 is returned if the system on
which the function is evaluated does not have the facility to provide
the fractional part of a second.
17 Either the character '-' or the character '+'. The character '-' is returned if
the local time indicated in the previous character positions is behind
Greenwich mean time. The character '+' is returned if the local time
indicated is the same as or ahead of Greenwich mean time. The
character '0' is returned if the system on which this function is
evaluated does not have the facility to provide the local time
differential factor.
18-19 If character position 17 is '-', two numeric digits are returned in the
range 00 through 12 indicating the number of hours that the reported
time is behind Greenwich mean time. If character position 17 is '+', two
numeric digits are returned in the range 00 through 13 indicating the
number of hours that the reported time is ahead of Greenwich mean
time. If character position 17 is '0', the value 00 is returned.
20-21 Two numeric digits are returned in the range 00 through 59 indicating
the number of additional minutes that the reported time is ahead of or
behind Greenwich mean time, depending on whether character position
17 is '+' or '-', respectively. If character position 17 is '0', the value 00 is
returned.

For more information, see Examples: numeric intrinsic functions in the Enterprise
COBOL Programming Guide.

DATE-OF-INTEGER
The DATE-OF-INTEGER function converts a date in the Gregorian calendar from
integer date form to standard date form (YYYYMMDD).

The function type is integer.

The function result is an eight-digit integer.

Chapter 21. Intrinsic functions 523

 Format

►► FUNCTION DATE-OF-INTEGER ( argument-1 ) ►◄

argument-1
A positive integer that represents a number of days succeeding December
31, 1600, in the Gregorian calendar. The valid range is 1 to 3,067,671, which
corresponds to dates ranging from January 1, 1601 thru December 31, 9999.
The INTDATE compiler option affects the starting date for the integer date
functions. For details, see INTDATE in the Enterprise COBOL Programming
Guide.

The returned value represents the International Standards Organization (ISO)

standard date equivalent to the integer specified as argument-1.

The returned value is an integer of the form YYYYMMDD where YYYY represents
a year in the Gregorian calendar; MM represents the month of that year; and DD
represents the day of that month.

DATE-TO-YYYYMMDD
The DATE-TO-YYYYMMDD function converts argument-1 from a date with a
two-digit year (YYnnnn) to a date with a four-digit year (YYYYnnnn). argument-2,
when added to the year at the time of execution, defines the ending year of a
100-year interval, or sliding century window, into which the year of argument-1
falls.

The function type is integer.

Format

►► FUNCTION DATE-TO-YYYYMMDD ( argument-1 ) ►◄

argument-2

argument-1
Must be zero or a positive integer less than 991232.
Note: The COBOL run time does not verify that the value is a valid date.
argument-2
Must be an integer. If argument-2 is omitted, the function is evaluated
assuming the value 50 was specified.

The sum of the year at the time of execution and the value of argument-2 must be
less than 10,000 and greater than 1,699.

See the following examples with returned values from the DATE-TO-YYYYMMDD
function:

524 Enterprise COBOL for z/OS, V6.1 Language Reference

 Current year argument-1 value argument-2 value Returned value
2002 851003 120 20851003
2002 851003 -20 18851003
2002 851003 10 19851003
1994 981002 -10 18981002

DAY-OF-INTEGER
The DAY-OF-INTEGER function converts a date in the Gregorian calendar from
integer date form to Julian date form (YYYYDDD).

The function type is integer.

The function result is a seven-digit integer.

Format

►► FUNCTION DAY-OF-INTEGER ( argument-1 ) ►◄

argument-1
A positive integer that represents a number of days succeeding December
31, 1600, in the Gregorian calendar. The valid range is 1 to 3,067,671, which
corresponds to dates ranging from January 1, 1601 thru December 31, 9999.
The INTDATE compiler option affects the starting date for the integer date
functions. For details, see INTDATE in the Enterprise COBOL Programming
Guide.

The returned value represents the Julian equivalent of the integer specified as
argument-1. The returned value is an integer of the form YYYYDDD where YYYY
represents a year in the Gregorian calendar and DDD represents the day of that
year.

DAY-TO-YYYYDDD
The DAY-TO-YYYYDDD function converts argument-1 from a date with a two-digit
year (YYnnn) to a date with a four-digit year (YYYYnnn). argument-2, when added
to the year at the time of execution, defines the ending year of a 100-year interval,
or sliding century window, into which the year of argument-1 falls.

The function type is integer.

Chapter 21. Intrinsic functions 525

 Format

►► FUNCTION DAY-TO-YYYYDDD ( argument-1 ) ►◄

argument-2

argument-1
Must be zero or a positive integer less than 99367.
The COBOL run time does not verify that the value is a valid date.
argument-2
Must be an integer. If argument-2 is omitted, the function is evaluated
assuming the value 50 was specified.

The sum of the year at the time of execution and the value of argument-2 must be
less than 10,000 and greater than 1,699.

Some examples of returned values from the DAY-TO-YYYYDDD function follow:

Current year argument-1 value argument-2 value Returned value

2002 10004 -20 1910004
2002 10004 -120 1810004
2002 10004 20 2010004
2013 95005 -10 1995005

DISPLAY-OF
The DISPLAY-OF function returns an alphanumeric character string consisting of
the content of argument-1 converted to a specific code page representation.

The type of the function is alphanumeric.

Format

►► FUNCTION DISPLAY-OF ( argument-1 ) ►◄

argument-2

argument-1
Must be of class national (categories national, national-edited, and
numeric-edited described with usage NATIONAL). argument-1 identifies
the source string for the conversion.
argument-2
Must be an integer. argument-2 identifies the output code page for the
conversion.
argument-2 must be a valid CCSID number and must identify an EBCDIC,
ASCII, UTF-8, or EUC code page. An EBCDIC or ASCII code page can
contain both single-byte and double-byte characters.

526 Enterprise COBOL for z/OS, V6.1 Language Reference

 If argument-2 is omitted, the output code page is the one that was in effect
for the CODEPAGE compiler option when the source code was compiled.

The returned value is an alphanumeric character string consisting of the characters

of argument-1 converted to the output code page representation. When a source
character cannot be converted to a character in the output code page, the source
character is replaced with a substitution character. The following table shows
substitution characters for some widely-used code pages:

Output code page Substitution character

SBCS ASCII X'7F'
PC Windows SBCS
EBCDIC SBCS X'3F'
ASCII DBCS X'FCFC'
EBCDIC DBCS (except for Thai) X'FEFE'
EBCDIC DBCS (Thai) X'41B8'
PC DBCS (Japanese or Chinese) X'FCFC'
PC DBCS (Korean) X'BFFC'
EUC (Korean) X'AFFE'
EUC (Japanese) X'747E'
UTF-8 From SBCS: X'1A'
From MBCS: X'EFBFBD'
UTF-16 From SBCS: X'001A'
From MBCS: X'FFFD'

No exception condition is raised.

The length of the returned value depends on the content of argument-1 and the
characteristics of the output code page.

Usage notes
v The CCSID for UTF-8 is 1208.
v If the output code page includes DBCS characters, the returned value can be a
mixed SBCS and DBCS string.
v The DISPLAY-OF function, with argument-2 specified, can be used to generate
character data represented in a code page that differs from that specified in the
CODEPAGE compiler option. Subsequent COBOL operations on that data can
involve implicit conversions that assume the data is represented in the EBCDIC
code page specified in the CODEPAGE compiler option. See Converting to or from
national (Unicode) representation in the Enterprise COBOL Programming Guide for
examples and programming techniques for processing data represented using
more than one code page within a single program.

Exception: If the conversion fails, a severe runtime error occurs. Verify that the
z/OS Unicode conversion services are installed and are configured to include the
table for converting from CCSID 1200 to the output code page. See the
Customization Guide for installation requirements to support the conversion.

Chapter 21. Intrinsic functions 527

FACTORIAL
The FACTORIAL function returns an integer that is the factorial of the argument
specified.

The function type is integer.

Format

►► FUNCTION FACTORIAL ( argument-1 ) ►◄

argument-1
If the ARITH(COMPAT) compiler option is in effect, argument-1 must be an
integer greater than or equal to zero and less than or equal to 28. If the
ARITH(EXTEND) compiler option is in effect, argument-1 must be an
integer greater than or equal to zero and less than or equal to 29.

If the value of argument-1 is zero, the value 1 is returned; otherwise, the factorial of
argument-1 is returned.

INTEGER
The INTEGER function returns the greatest integer value that is less than or equal
to the argument specified.

The function type is integer.

Format

►► FUNCTION INTEGER ( argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the greatest integer less than or equal to the value of
argument-1. For example, FUNCTION INTEGER (2.5) returns a value of 2 and
FUNCTION INTEGER (-2.5) returns a value of -3.

INTEGER-OF-DATE
The INTEGER-OF-DATE function converts a date in the Gregorian calendar from
standard date form (YYYYMMDD) to integer date form.

The function type is integer.

The function result is a seven-digit integer with a range from 1 to 3,067,671.

528 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format

►► FUNCTION INTEGER-OF-DATE ( argument-1 ) ►◄

argument-1
Must be an integer of the form YYYYMMDD, whose value is obtained
from the calculation (YYYY * 10,000) + (MM * 100) + DD, where:
v YYYY represents the year in the Gregorian calendar. It must be an
integer greater than 1600, but not greater than 9999.
v MM represents a month and must be a positive integer less than 13.
v DD represents a day and must be a positive integer less than 32,
provided that it is valid for the specified month and year combination.

The returned value is an integer that is the number of days that the date
represented by argument-1 succeeds December 31, 1600 in the Gregorian calendar.

The INTDATE compiler option affects the starting date for the integer date
functions. For details, see INTDATE in the Enterprise COBOL Programming Guide.

INTEGER-OF-DAY
The INTEGER-OF-DAY function converts a date in the Gregorian calendar from
Julian date form (YYYYDDD) to integer date form.

The function type is integer.

The function result is a seven-digit integer.

Format

►► FUNCTION INTEGER-OF-DAY ( argument-1 ) ►◄

argument-1
Must be an integer of the form YYYYDDD whose value is obtained from
the calculation (YYYY * 1000) + DDD, where:
v YYYY represents the year in the Gregorian calendar. It must be an
integer greater than 1600, but not greater than 9999.
v DDD represents the day of the year. It must be a positive integer less
than 367, provided that it is valid for the year specified.

The returned value is an integer that is the number of days that the date
represented by argument-1 succeeds December 31, 1600 in the Gregorian calendar.

The INTDATE compiler option affects the starting date for the integer date
functions. For details, see INTDATE in the Enterprise COBOL Programming Guide.

Chapter 21. Intrinsic functions 529

INTEGER-PART
The INTEGER-PART function returns an integer that is the integer portion of the
argument specified.

The function type is integer.

Format

►► FUNCTION INTEGER-PART ( argument-1 ) ►◄

argument-1
Must be class numeric.

If the value of argument-1 is zero, the returned value is zero. If the value of
argument-1 is positive, the returned value is the greatest integer less than or equal
to the value of argument-1. If the value of argument-1 is negative, the returned value
is the least integer greater than or equal to the value of argument-1.

LENGTH
The LENGTH function returns an integer equal to the length of the argument in
national character positions for arguments of usage NATIONAL and in
alphanumeric character positions or bytes for all other arguments. An
alphanumeric character position and a byte are equivalent.

The type of the function is integer.

Format

►► FUNCTION LENGTH ( argument-1 ) ►◄

argument-1
Can be:
v An alphanumeric literal or a national literal
v A group item (including unbounded groups) or an elementary data item
of any class except DBCS
v A data item described with usage POINTER, PROCEDURE-POINTER,
FUNCTION-POINTER, or OBJECT REFERENCE
v The ADDRESS OF special register
v The LENGTH OF special register
v The XML-NTEXT special register
v The XML-TEXT special register

The returned value is a nine-digit integer determined as follows:

530 Enterprise COBOL for z/OS, V6.1 Language Reference

 v If argument-1 is an alphanumeric literal or an elementary data item of class
alphabetic or alphanumeric, the value returned is equal to the number of
alphanumeric character positions in the argument.
If argument-1 is a null-terminated alphanumeric literal, the returned value is
equal to the number of alphanumeric character positions in the literal excluding
the null character at the end of the literal.
The length of an alphanumeric data item or literal containing a mix of
single-byte and double-byte characters is counted as though each byte were a
single-byte character.
v If argument-1 is an alphanumeric group item, the value returned is equal to the
length of argument-1 in alphanumeric character positions regardless of the
content of the group. If any data item subordinate to argument-1 is described
with the DEPENDING phrase of the OCCURS clause, the length of argument-1 is
determined using the contents of the data item specified in the DEPENDING
phrase. This evaluation is accomplished according to the rules of the OCCURS
clause for a sending data item. For more information, see the discussions of the
“OCCURS clause” on page 195 and the “USAGE clause” on page 233.
The returned value includes implicit FILLER positions, if any.
v If argument-1 is a national literal or an elementary data item described with
usage NATIONAL, the value returned is equal to the length of argument-1 in
national character positions.
For example, if argument-1 is defined as PIC 9(3) with usage NATIONAL, the
returned value is 3, although the storage size of the argument is 6 bytes.
v If argument-1 is a national group item, the value returned is equal to the length
of argument-1 in national character positions. If any data item subordinate to
argument-1 is described with the DEPENDING phrase of the OCCURS clause,
the length of argument-1 is determined using the contents of the data item
specified in the DEPENDING phrase. This evaluation is accomplished according
to the rules of the OCCURS clause for a sending data item. For more
information, see the discussions of the “OCCURS clause” on page 195 and the
“USAGE clause” on page 233.
The returned value includes implicit FILLER positions, if any.
v Otherwise, the returned value is the number of bytes of storage occupied by
argument-1.

LOG
The LOG function returns a numeric value that approximates the logarithm to the
base e (natural log) of the argument specified.

The function type is numeric.

Format

►► FUNCTION LOG ( argument-1 ) ►◄

argument-1
Must be class numeric. The value of argument-1 must be greater than zero.

Chapter 21. Intrinsic functions 531

 The returned value is the approximation of the logarithm to the base e of
argument-1.

LOG10
The LOG10 function returns a numeric value that approximates the logarithm to
the base 10 of the argument specified.

The function type is numeric.

Format

►► FUNCTION LOG10 ( argument-1 ) ►◄

argument-1
Must be class numeric. The value of argument-1 must be greater than zero.

The returned value is the approximation of the logarithm to the base 10 of

argument-1.

LOWER-CASE
The LOWER-CASE function returns a character string that contains the characters
in the argument with each uppercase letter replaced by the corresponding
lowercase letter.

The function type depends on the type of the argument, as follows:

Argument type Function type

Alphabetic Alphanumeric
Alphanumeric Alphanumeric
National National

Format

►► FUNCTION LOWER-CASE ( argument-1 ) ►◄

argument-1
Must be class alphabetic, alphanumeric, or national and must be at least
one character position in length.

Note: If argument-1 is of the alphanumeric class, it must not contain UTF-8

encoded data.

The same character string as argument-1 is returned, except that each uppercase
letter is replaced by the corresponding lowercase letter.

532 Enterprise COBOL for z/OS, V6.1 Language Reference

 If argument-1 is of class alphabetic or alphanumeric, the uppercase letters 'A'
through 'Z' are replaced by the corresponding lowercase letters 'a' through 'z',
where the range of 'A' through 'Z' and the range of 'a' through 'z' are as shown in
“EBCDIC collating sequence” on page 609, regardless of the code page in effect.

If argument-1 is of class national, each uppercase letter is replaced by its

corresponding lowercase letter based on the specification given in the Unicode
database UnicodeData.txt, available from the Unicode Consortium at
http://www.unicode.org/.

The character string returned has the same length as argument-1.

MAX
The MAX function returns the content of the argument that contains the maximum
value.

The function type depends on the argument type, as follows:

Argument type Function type

Alphabetic Alphanumeric
Alphanumeric Alphanumeric
National National
All arguments integer Integer
(includes integer arguments of usage NATIONAL)
Numeric (some arguments can be integer) Numeric
(includes numeric arguments of usage NATIONAL)

Format

►► FUNCTION MAX ( ▼ argument-1 ) ►◄

argument-1
Must be class alphabetic, alphanumeric, national, or numeric.

All arguments must be of the same class, except that a combination of alphabetic
and alphanumeric arguments is allowed.

The returned value is the content of argument-1 having the greatest value. The
comparisons used to determine the greatest value are made according to the rules
for simple conditions. For more information, see “Conditional expressions” on
page 264.

If more than one argument-1 has the same greatest value, the leftmost argument-1
having that value is returned.

If the type of the function is alphanumeric or national, the size of the returned
value is the size of the selected argument-1.

Chapter 21. Intrinsic functions 533

MEAN
The MEAN function returns a numeric value that approximates the arithmetic
average of its arguments.

The function type is numeric.

Format

►► FUNCTION MEAN ( ▼ argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the arithmetic mean of the argument-1 series. The returned
value is defined as the sum of the argument-1 series divided by the number of
occurrences referenced by argument-1.

MEDIAN
The MEDIAN function returns the content of the argument whose value is the
middle value in the list formed by arranging the arguments in sorted order.

The function type is numeric.

Format

►► FUNCTION MEDIAN ( ▼ argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the content of argument-1 having the middle value in the list
formed by arranging all argument-1 values in sorted order.

If the number of occurrences referenced by argument-1 is odd, the returned value is

such that at least half of the occurrences referenced by argument-1 are greater than
or equal to the returned value and at least half are less than or equal. If the
number of occurrences referenced by argument-1 is even, the returned value is the
arithmetic mean of the values referenced by the two middle occurrences.

The comparisons used to arrange the argument values in sorted order are made
according to the rules for simple conditions. For more information, see
“Conditional expressions” on page 264.

534 Enterprise COBOL for z/OS, V6.1 Language Reference

MIDRANGE
The MIDRANGE function returns a numeric value that approximates the
arithmetic average of the values of the minimum argument and the maximum
argument.

The function type is numeric.

Format

►► FUNCTION MIDRANGE ( ▼ argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the arithmetic mean of the value of the greatest argument-1
and the value of the least argument-1. The comparisons used to determine the
greatest and least values are made according to the rules for simple conditions. For
more information, see “Conditional expressions” on page 264.

MIN
The MIN function returns the content of the argument that contains the minimum
value.

The function type depends on the argument type, as follows:

Argument type Function type

Alphabetic Alphanumeric
Alphanumeric Alphanumeric
National National
All arguments integer Integer
(includes integer arguments of usage NATIONAL)
Numeric (some arguments can be integer) Numeric
(includes numeric arguments of usage NATIONAL)

Format

►► FUNCTION MIN ( ▼ argument-1 ) ►◄

argument-1
Must be class alphabetic, alphanumeric, national, or numeric.

Chapter 21. Intrinsic functions 535

 All arguments must be of the same class, except that a combination of alphabetic
and alphanumeric arguments is allowed.

The returned value is the content of argument-1 having the least value. The
comparisons used to determine the least value are made according to the rules for
simple conditions. For more information, see “Conditional expressions” on page
264.

If more than one argument-1 has the same least value, the leftmost argument-1
having that value is returned.

If the type of the function is alphanumeric or national, the size of the returned
value is the size of the selected argument-1.

MOD
The MOD function returns an integer value that is argument-1 modulo argument-2.

The function type is integer.

The function result is an integer with as many digits as the shorter of argument-1
and argument-2.

Format

►► FUNCTION MOD ( argument-1 argument-2 ) ►◄

argument-1
Must be an integer.
argument-2
Must be an integer. Must not be zero.

The returned value is argument-1 modulo argument-2. The returned value is defined
as:

argument-1 - (argument-2 * FUNCTION INTEGER (argument-1 / argument-2))

The following table lists expected results for some values of argument-1 and
argument-2.

argument-1 argument-2 Returned value

11 5 1
-11 5 4
11 -5 -4
-11 -5 -1

536 Enterprise COBOL for z/OS, V6.1 Language Reference

NATIONAL-OF
The NATIONAL-OF function returns a national character string consisting of the
national character representation of the characters in argument-1.

The type of the function is national.

Format

►► FUNCTION NATIONAL-OF ( argument-1 ) ►◄

argument-2

argument-1
Must be of class alphabetic, alphanumeric, or DBCS. argument-1 specifies
the source string for the conversion.
argument-2
Must be an integer. argument-2 identifies the source code page for the
conversion.
argument-2 must be a valid CCSID number and must identify an EBCDIC,
ASCII, UTF-8, or EUC code page. An EBCDIC or ASCII code page can
contain both single-byte and double-byte characters.
If argument-2 is omitted, the source code page is the one that was in effect
for the CODEPAGE compiler option when the source code was compiled.

The returned value is a national character string consisting of the characters of

argument-1 converted to national character representation. When a source character
cannot be converted to a national character, the source character is converted to a
substitution character. The substitution character is:
v X'001A' if converting a single-byte character
v X'FFFD' if converting a multi-byte character

No exception condition is raised.

The length of the returned value depends on the content of argument-1 and the
characteristics of the source code page.

Usage note: The CCSID for UTF-8 is 1208.

Exception: If the conversion fails, a severe runtime error occurs. Verify that the
z/OS Unicode conversion services are installed and are configured to include the
table for converting from the source code page to CCSID 1200. See the
Customization Guide for installation requirements to support the conversion.

NUMVAL
The NUMVAL function returns the numeric value represented by the alphanumeric
character string or national character string specified as the argument. The function
removes any leading or trailing spaces in the string to produce a numeric value.

The function type is numeric.

Chapter 21. Intrinsic functions 537

 Format

►► FUNCTION NUMVAL ( argument-1 ) ►◄

argument-1
Must be an alphanumeric literal, a national literal, or a data item of class
national or class alphanumeric that contains a character string in either of
the following formats:

Format 1: argument-1

►► digit ►◄
space + space . space
- digit
. digit

Format 2: argument-1, monetary format

►► digit ►◄
space . space + space
digit -
. digit CR
DB

space A string of one or more spaces.

digit A string of one or more digits. If the ARITH(COMPAT) compiler option is
in effect, the total number of digits must not exceed 18. If the
ARITH(EXTEND) compiler option is in effect, the total number of digits
must not exceed 31.

If the DECIMAL-POINT IS COMMA clause is specified in the SPECIAL-NAMES

paragraph, a comma must be used in argument-1 rather than a decimal point.

The returned value is a floating-point approximation of the numeric value

represented by argument-1. The precision of the returned value depends on the
setting of the ARITH compiler option. For details, see Converting to numbers
(NUMVAL, NUMVAL-C) in the Enterprise COBOL Programming Guide.

538 Enterprise COBOL for z/OS, V6.1 Language Reference

NUMVAL-C
The NUMVAL-C function returns the numeric value represented by the
alphanumeric character string or national character string specified as argument-1.
The function removes the currency string, if any, and any grouping separators
(commas or periods) to produce a numeric value.

The function type is numeric.

Format

►► FUNCTION NUMVAL-C ( argument-1 ) ►◄

argument-2

argument-1
Must be an alphanumeric literal, a national literal, or a data item of class
alphanumeric or class national that contains a character string in either of
the following formats:

Format 1: argument-1

►► ►
space + space cs space
-

► digit ►◄
. space
digit
▼ , digit
. digit

Format 2: argument-1, monetary format

►► ►
space cs space

► digit ►
. space +
digit -
▼ , digit CR
. digit DB

► ►◄
space

space A string of one or more spaces.

Chapter 21. Intrinsic functions 539
 cs The string of one or more characters that form the currency sign.
At most one copy of the characters specified by cs can occur in
argument-1.
digit A string of one or more digits. If the ARITH(COMPAT) compiler
option is in effect, the total number of digits must not exceed 18. If
the ARITH(EXTEND) compiler option is in effect, the total number
of digits must not exceed 31.
If the DECIMAL-POINT IS COMMA clause is specified in the
SPECIAL-NAMES paragraph, the functions of the comma and decimal
point in argument-1 are reversed.
argument-2
Specifies the currency string value.
The following rules apply:
v argument-2 must be specified if the program contains more than one
CURRENCY SIGN clause.
v argument-2, if specified, must be of the same class as argument-1.
v argument-2 must not contain any of the digits 0 through 9, any leading
or trailing spaces, or any of the special characters '+', '-', '.', or ','.
v argument-2 can be of any length valid for an elementary or group data
item of the class of argument-2, including zero.
v Matching of argument-2 is case sensitive. For example, if you specify
argument-2 as 'CHF', it will not match 'ChF', 'chf' or 'chF'.
If argument-2 is not specified, the character used for cs is the currency
symbol specified for the program.

The returned value is a floating-point approximation of the numeric value

represented by argument-1. The precision of the returned value depends on the
setting of the ARITH compiler option. For details, see Converting to numbers
(NUMVAL, NUMVAL-C) in the Enterprise COBOL Programming Guide.

ORD
The ORD function returns an integer value that is the ordinal position of its
argument in the collating sequence for the program. The lowest ordinal position is
1.

The function type is integer.

The function result is a three-digit integer.

Format

►► FUNCTION ORD ( argument-1 ) ►◄

argument-1
Must be one character in length and must be class alphabetic or
alphanumeric.

540 Enterprise COBOL for z/OS, V6.1 Language Reference

 The returned value is the ordinal position of argument-1 in the collating sequence
for the program; it ranges from 1 to 256 depending on the collating sequence.

ORD-MAX
The ORD-MAX function returns a value that is the ordinal position in the
argument list of the argument that contains the maximum value.

The function type is integer.

Format

►► FUNCTION ORD-MAX ( ▼ argument-1 ) ►◄

argument-1
Must be class alphabetic, alphanumeric, national, or numeric.

All arguments must be of the same class, except that a combination of alphabetic
and alphanumeric arguments is allowed.

The returned value is the ordinal number that corresponds to the position of the
argument-1 having the greatest value in the argument-1 series.

The comparisons used to determine the greatest-valued argument-1 are made

according to the rules for simple conditions. For more information, see
“Conditional expressions” on page 264.

If more than one argument-1 has the same greatest value, the number returned
corresponds to the position of the leftmost argument-1 having that value.

ORD-MIN
The ORD-MIN function returns a value that is the ordinal position in the argument
list of the argument that contains the minimum value.

The function type is integer.

Format

►► FUNCTION ORD-MIN ( ▼ argument-1 ) ►◄

argument-1
Must be class alphabetic, alphanumeric, national, or numeric.

Chapter 21. Intrinsic functions 541

 All arguments must be of the same class, except that a combination of alphabetic
and alphanumeric arguments is allowed.

The returned value is the ordinal number that corresponds to the position of the
argument-1 having the least value in the argument-1 series.

The comparisons used to determine the least-valued argument-1 are made

according to the rules for simple conditions. For more information, see
“Conditional expressions” on page 264.

If more than one argument-1 has the same least value, the number returned
corresponds to the position of the leftmost argument-1 having that value.

PRESENT-VALUE
The PRESENT-VALUE function returns a value that approximates the present
value of a series of future period-end amounts specified by argument-2 at a
discount rate specified by argument-1.

The function type is numeric.

Format

►► FUNCTION PRESENT-VALUE ( argument-1 ▼ argument-2 ) ►◄

argument-1
Must be class numeric. Must be greater than -1.
argument-2
Must be class numeric.

The returned value is an approximation of the summation of a series of

calculations with each term in the following form:

argument-2 / (1 + argument-1) ** n

There is one term for each occurrence of argument-2. The exponent n is

incremented from 1 by 1 for each term in the series.

RANDOM
The RANDOM function returns a numeric value that is a pseudorandom number
from a rectangular distribution.

The function type is numeric.

542 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format

►► FUNCTION RANDOM ►◄
( argument-1 )

argument-1
If argument-1 is specified, it must be zero or a positive integer. However,
only values in the range from zero up to and including 2,147,483,645 yield
a distinct sequence of pseudorandom numbers.

If a subsequent reference specifies argument-1, a new sequence of pseudorandom

numbers is started.

If the first reference to this function in the run unit does not specify argument-1, the
seed value used will be zero.

In each case, subsequent references without specifying argument-1 return the next
number in the current sequence.

The returned value is exclusively between zero and one.

For a given seed value, the sequence of pseudorandom numbers is always the
same.

The RANDOM function can be used in threaded programs. For an initial seed, a
single sequence of pseudorandom numbers is returned, regardless of the thread
that is running when RANDOM is invoked.

RANGE
The RANGE function returns a value that is equal to the value of the maximum
argument minus the value of the minimum argument.

The function type depends on the argument types, as follows:

Argument type Function type

All arguments integer Integer
Numeric (some arguments can be integer) Numeric

Format

►► FUNCTION RANGE ( ▼ argument-1 ) ►◄

argument-1
Must be class numeric.

Chapter 21. Intrinsic functions 543

 The returned value is equal to argument-1 with the greatest value minus the
argument-1 with the least value. The comparisons used to determine the greatest
and least values are made according to the rules for simple conditions. For more
information, see “Conditional expressions” on page 264.

REM
The REM function returns a numeric value that is the remainder of argument-1
divided by argument-2.

The function type is numeric.

Format

►► FUNCTION REM ( argument-1 argument-2 ) ►◄

argument-1
Must be class numeric.
argument-2
Must be class numeric. Must not be zero.

The returned value is the remainder of argument-1 divided by argument-2. It is

defined as the expression:

argument-1 - (argument-2 * FUNCTION INTEGER-PART (argument-1 / argument-2))

REVERSE
The REVERSE function returns a character string of exactly the same length as the
argument, whose characters are exactly the same as those specified in the
argument except that they are in reverse order. For arguments of type national,
character positions are reversed.

The function type depends on the type of the argument, as follows:

Argument type Function type

Alphabetic Alphanumeric
Alphanumeric Alphanumeric
National National

Format

►► FUNCTION REVERSE ( argument-1 ) ►◄

544 Enterprise COBOL for z/OS, V6.1 Language Reference

 argument-1
Must be class alphabetic, alphanumeric, or national and must be at least
one character in length.

The returned value is a character string of the same length as argument-1, with the
characters of argument-1 in reversed order. For example, if argument-1 contains ABC,
the returned value is CBA.

SIN
The SIN function returns a numeric value that approximates the sine of the angle
or arc specified by the argument in radians.

The function type is numeric.

Format

►► FUNCTION SIN ( argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the approximation of the sine of argument-1 and is greater
than or equal to -1 and less than or equal to +1.

SQRT
The SQRT function returns a numeric value that approximates the square root of
the argument specified.

The function type is numeric.

Format

►► FUNCTION SQRT ( argument-1 ) ►◄

argument-1
Must be class numeric. The value of argument-1 must be zero or positive.

The returned value is the absolute value of the approximation of the square root of
argument-1.

Chapter 21. Intrinsic functions 545

STANDARD-DEVIATION
The STANDARD-DEVIATION function returns a numeric value that approximates
the standard deviation of its arguments.

The function type is numeric.

Format

►► FUNCTION STANDARD-DEVIATION ( ▼ argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the approximation of the standard deviation of the

argument-1 series. The returned value is calculated as follows:
1. The difference between each argument-1 and the arithmetic mean of the
argument-1 series is calculated and squared.
2. The values obtained are then added together. This quantity is divided by the
number of values in the argument-1 series.
3. The square root of the quotient obtained is then calculated. The returned value
is the absolute value of this square root.

If the argument-1 series consists of only one value, or if the argument-1 series
consists of all variable-occurrence data items and the total number of occurrences
for all of them is one, the returned value is zero.

SUM
The SUM function returns a value that is the sum of the arguments.

The function type depends on the argument types, as follows:

Argument type Function type

All arguments integer Integer
Numeric (some arguments can be integer) Numeric

Format

►► FUNCTION SUM ( ▼ argument-1 ) ►◄

546 Enterprise COBOL for z/OS, V6.1 Language Reference

 argument-1
Must be class numeric.

The returned value is the sum of the arguments. If the argument-1 series are all
integers, the value returned is an integer. If the argument-1 series are not all
integers, a numeric value is returned.

TAN
The TAN function returns a numeric value that approximates the tangent of the
angle or arc that is specified by the argument in radians.

The function type is numeric.

Format

►► FUNCTION TAN ( argument-1 ) ►◄

argument-1
Must be class numeric.

The returned value is the approximation of the tangent of argument-1.

ULENGTH
The ULENGTH function returns an integer value that is equal to the number of
UTF-8 characters in a character string argument that is encoded in UTF-8.

The function type is integer.

Format

►► FUNCTION ULENGTH ( argument-1 ) ►◄

argument-1
Must be of class alphabetic or alphanumeric. argument-1 must contain valid
UTF-8 encoded characters.

The returned value is the number of UTF-8 characters in argument-1.

If the UTF-8 argument contains composed characters, the combining characters are
counted individually in determining the length. For example, when encoded in
UTF-8, the Unicode character ä can be x'C3A4' or x'61CC88'. With either of the
UTF-8 characters as argument-1, the returned values of the ULENGTH function are
different. See the following table for details.

Chapter 21. Intrinsic functions 547

Table 52. ULENGTH function of character ä
Returned value of the ULENGTH
Character Unicode encoding UTF-8 encoding function
ä U+00E4 x'C3A4' 1
(precomposed form,
latin small letter a with diaeresis)
U+0061 + U+0308 x'61CC88' 2
(canonical decomposition,
latin small letter a + combining diaeresis)

UPOS
The UPOS function returns an integer value that is equal to the index of the nth
UTF-8 character in a character string argument that is encoded in UTF-8.

The function type is integer.

Format

►► FUNCTION UPOS ( argument-1 argument-2 ) ►◄

argument-1
Must be of class alphabetic or alphanumeric. argument-1 must contain valid
UTF-8 encoded characters.
argument-2
Must be an integer.

Suppose argument-2=n, the returned value is the byte position of the nth UTF-8
character in argument-1.

If argument-2 is not positive or if argument-2 is larger than ULENGTH(argument-1),

zero is returned. Otherwise, if argument-2=n, the returned value is the byte position
in argument-1 where the nth UTF-8 character starts.

For example, if A is an alphanumeric item that contains the UTF-8 value

x'4BC3A4666572' ('Käfer'), the returned values are as follows:
v UPOS(A 1) returns 1
v UPOS(A 2) returns 2
v UPOS(A 3) returns 4
v UPOS(A 4) returns 5
v UPOS(A 5) returns 6

UPPER-CASE
The UPPER-CASE function returns a character string that contains the characters in
the argument with each lowercase letter replaced by the corresponding uppercase
letter.

The function type depends on the type of the argument, as follows:

548 Enterprise COBOL for z/OS, V6.1 Language Reference

 Argument type Function type
Alphabetic Alphanumeric
Alphanumeric Alphanumeric
National National

Format

►► FUNCTION UPPER-CASE ( argument-1 ) ►◄

argument-1
Must be of class alphabetic, alphanumeric, or national and must be at least
one character position in length.

Note: If argument-1 is of the alphanumeric class, it must not contain UTF-8

encoded data.

The same character string as argument-1 is returned, except that each lowercase
letter is replaced by the corresponding uppercase letter.

If argument-1 is alphabetic or alphanumeric, the lowercase letters 'a' through 'z' are
replaced by the corresponding uppercase letters 'A' through 'Z', where the range of
'a' through 'z' and the range of 'A' through 'Z' are as shown in “EBCDIC collating
sequence” on page 609, regardless of the code page in effect.

If argument-1 is national, each lowercase letter is replaced by its corresponding

uppercase letter based on the specification given in the Unicode database
UnicodeData.txt, available from the Unicode Consortium at www.unicode.org/.

The returned character string has the same length as argument-1.

USUBSTR
The USUBSTR function returns a substring of a character string argument that is
encoded in UTF-8.

The function type is alphanumeric.

Format

►► FUNCTION USUBSTR ( argument-1 argument-2 argument-3 ) ►◄

argument-1
Must be of class alphabetic or alphanumeric. argument-1 must contain valid
UTF-8 encoded characters.

Chapter 21. Intrinsic functions 549

 argument-2
Must be an integer that is greater than zero. It represents the starting
position of a substring in argument-1.
argument-3
Must be an integer that is greater than or equal to zero. It represents the
length of a substring in argument-1.

Note: The sum of argument-2 and argument-3 minus one must be less than or equal
to ULENGTH(argument-1).

Suppose argument-2 = n and argument-3 = m, the returned value is an alphanumeric

character string that contains m UTF-8 characters in argument-1, starting with the
nth character.

For example, if A is an alphanumeric item that contains the UTF-8 value

x'4BC3A4666572' ('Käfer'), the returned values are as follows:
v USUBSTR(A 1 2) returns x'4BC3A4' ('Kä')
v USUBSTR(A 2 1) returns x'C3A4' ('ä')
v USUBSTR(A 2 2) returns x'C3A466' ('äf')
v USUBSTR(A 3 2) returns x'6665' ('fe')

USUPPLEMENTARY
The USUPPLEMENTARY function returns an integer value that is equal to the
index of the first Unicode supplementary character in a character string argument
that is encoded in UTF-8 or UTF-16.

A Unicode supplementary character is a character above U+FFFF, that is, a

character outside of the Basic Multilingual Plane (BMP). These characters are
encoded in UTF-16 with a surrogate pair (two 16-bit code units), or are encoded in
UTF-8 with a 4-byte representation.

The function type is integer.

Format

►► FUNCTION USUPPLEMENTARY ( argument-1 ) ►◄

argument-1
Must be of class alphabetic, alphanumeric, or national. argument-1 must
contain valid UTF-8 or UTF-16 data based on its class:
v If argument-1 is of class alphabetic or alphanumeric, it must contain valid
UTF-8 data.
v If argument-1 is of class national, it must contain valid UTF-16 data.

The returned value is an integer, which differs based on the argument-1 value:
v If the contents of argument-1 are not valid Unicode (UTF-8 or UTF-16, depending
on class), the returned result is unpredictable.
v If argument-1 contains no supplementary characters, the returned value is zero.

550 Enterprise COBOL for z/OS, V6.1 Language Reference

 v If argument-1 is of class alphabetic or alphanumeric, the returned value is the
byte position of the first UTF-8 supplementary character in argument-1.
v If argument-1 is of class national, the returned value is the index, in UTF-16
encoding units, of the first UTF-16 supplementary character in argument-1.

For example, the musical G-clef symbol is represented in UTF-16 Unicode by the
surrogate pair nx'D834DD1E', or in UTF-8 Unicode by x'F09D849E'. Thus, for the
following COBOL program fragment, the output of both DISPLAY statements is
value 3.
01 N pic N(4) value nx’00200020D834DD1E’.
01 X pic X(6) value x’2020F09D849E’.
01 I pic 9.
...
Compute I = function Usupplementary(N)
Display I
Compute I = function Usupplementary(X)
Display I

UVALID
If a character string consists of valid Unicode UTF-8 or UTF-16 data, the UVALID
function returns the value zero. If a character string contains invalid Unicode data,
the UVALID function returns the index of the first invalid element.

The function type is integer.

Format

►► FUNCTION UVALID ( argument-1 ) ►◄

argument-1
Must be of class alphabetic, alphanumeric, or national.

The returned value is an integer, which differs based on argument-1:

v If argument-1 is of class alphabetic or alphanumeric, and it consists of valid
UTF-8 encoded Unicode data, the returned value is zero.
v If argument-1 is of class alphabetic or alphanumeric, and it contains invalid
UTF-8 encoded Unicode data, the returned value is the position of the first byte
where the invalid UTF-8 data starts.
v If argument-1 is of class national, and it consists of valid UTF-16 encoded
Unicode data, the returned value is zero.
v If argument-1 is of class national, and it contains invalid UTF-16 encoded
Unicode data, the returned value is the position of the first UTF-16 encoding
unit where the invalid UTF-16 data starts. This position is one plus the number
of well-formed UTF-16 encoding units that precede the invalid data.

Note: The UVALID function indicates whether the character string contains
well-formed Unicode UTF-8 or UTF-16 data. It does not indicate whether any or all
of the Unicode code points represented by the character string are assigned to
characters.

Chapter 21. Intrinsic functions 551

 For UTF-8 data, the validity of a byte varies according to its range as listed in the
table:
Table 53. Byte validity for UTF-8 data
Value Range Dependency Validity
x'00' - x'7F' None Valid
x'80' - x'C1' None Invalid
x'C2' - x'DF' Followed by another byte that is in the range x'80' to x'BF' Valid
x'E0' - x'EF' If the first byte is x'E0', followed by two more bytes that meet the following Valid
requirements:
v The second byte is in the range x'A0' to x'BF'
v The third byte is in the range x'80' to x'BF'
If the first byte is in the range x'E1' to x'EC', both the second and third bytes Valid
are in the range x'80' to x'BF'
If the first byte is x'ED', followed by two more bytes that meet the following Valid
requirements:
v The second byte is in the range x'80' to x'9F'
v The third byte is in the range x'80' to x'BF'
If the first byte is in the range x'EE' to x'EF', both the second and third bytes Valid
are in the range x'80' to x'BF'
x'F0' - x'F4' If the first byte is x'F0', followed by three more bytes that meet the following Valid
requirements:
v The second byte is in the range x'90' to x'BF'
v The third byte is in the range x'80' to x'BF'
v The fourth byte is in the range x'80' to x'BF'
If the first byte is in the range x'F1' to x'F3', all the second, third, and fourth bytes Valid
are in the range x'80' to x'BF'
If the first byte is x'F4', followed by three more bytes that meet the following Valid
requirements:
v The second byte is in the range x'80' to x'8f'
v The third byte is in the range x'80' to x'BF'
v The fourth byte is in the range x'80' to x'BF'
x'F5' - x'FF' None Invalid

For UTF-16 data, the validity of an encoding unit varies according to its range as
listed in the table:
Table 54. Encoding unit validity for UTF-16 data
Number of bytes if converted
Value Range Dependency Validity to UTF-8
nx'0000' - nx'007F' None Valid 1
nx'0080' - nx'07FF' None Valid 2
nx'0800' - nx'D7FF' None Valid 3
nx'D800' - nx'DBFF' Must be followed by a second Valid 4
encoding unit with a value in (A Unicode surrogate pair)
the range nx'DC00' to nx'DFFF'
Other cases Invalid Not applicable
nx'E000' - nx'FFFF' None Valid 3

552 Enterprise COBOL for z/OS, V6.1 Language Reference

UWIDTH
The UWIDTH function returns an integer value that is equal to the width in bytes
of the nth UTF-8 character in a character string argument that is encoded in UTF-8.

The function type is integer.

Format

►► FUNCTION UWIDTH ( argument-1 argument-2 ) ►◄

argument-1
Must be of class alphabetic or alphanumeric, and it must contain valid
UTF-8 data.
argument-2
Must be an integer.

The returned value is an integer.

If argument-2 is not positive or if argument-2 is larger than ULENGTH(argument-1),

zero is returned. Otherwise, if argument-2=n, the returned value is the width in
bytes of the nth UTF-8 character in argument-1.

If A is an alphanumeric item that contains the UTF-8 value x'4BC3A4666572'

('Käfer'), the returned values are as follows:
v UWIDTH(A 1) returns 1
v UWIDTH(A 2) returns 2
v UWIDTH(A 3) returns 1
v UWIDTH(A 4) returns 1
v UWIDTH(A 5) returns 1

VARIANCE
The VARIANCE function returns a numeric value that approximates the variance
of its arguments.

The function type is numeric.

Format

►► FUNCTION VARIANCE ( ▼ argument-1 ) ►◄

argument-1
Must be class numeric.

Chapter 21. Intrinsic functions 553

 The returned value is the approximation of the variance of the argument-1 series.

The returned value is defined as the square of the standard deviation of the
argument-1 series. This value is calculated as follows:
1. The difference between each argument-1 value and the arithmetic mean of the
argument-1 series is calculated and squared.
2. The values obtained are then added together. This quantity is divided by the
number of values in the argument series.

If the argument-1 series consists of only one value, or if the argument-1 series
consists of all variable-occurrence data items and the total number of occurrences
for all of them is one, the returned value is zero.

WHEN-COMPILED
The WHEN-COMPILED function returns the date and time that the program was
compiled as provided by the system on which the program was compiled.

The function type is alphanumeric.

Format

►► FUNCTION WHEN-COMPILED ►◄

Reading from left to right, the 21 character positions of the returned value are as
follows:

Character
positions Contents
1-4 Four numeric digits of the year in the Gregorian calendar
5-6 Two numeric digits of the month of the year, in the range 01 through
12
7-8 Two numeric digits of the day of the month, in the range 01 through 31
9-10 Two numeric digits of the hours past midnight, in the range 00 through
23
11-12 Two numeric digits of the minutes past the hour, in the range 00
through 59
13-14 Two numeric digits of the seconds past the minute, in the range 00
through 59
15-16 Two numeric digits of the hundredths of a second past the second, in
the range 00 through 99. The value 00 is returned if the system on
which the function is evaluated does not have the facility to provide
the fractional part of a second.

554 Enterprise COBOL for z/OS, V6.1 Language Reference

 Character
positions Contents
17 Either the character '-' or the character '+'. The character '-' is returned if
the local time indicated in the previous character positions is behind
Greenwich mean time. The character '+' is returned if the local time
indicated is the same as or ahead of Greenwich mean time. The
character '0' is returned if the system on which this function is
evaluated does not have the facility to provide the local time
differential factor.
18-19 If character position 17 is '-', two numeric digits are returned in the
range 00 through 12 indicating the number of hours that the reported
time is behind Greenwich mean time. If character position 17 is '+', two
numeric digits are returned in the range 00 through 13 indicating the
number of hours that the reported time is ahead of Greenwich mean
time. If character position 17 is '0', the value 00 is returned.
20-21 Two numeric digits are returned in the range 00 through 59 indicating
the number of additional minutes that the reported time is ahead of or
behind Greenwich mean time, depending on whether character position
17 is '+' or '-', respectively. If character position 17 is '0', the value 00 is
returned.

The returned value is the date and time of compilation of the source unit that
contains this function. If a program is a contained program, the returned value is
the compilation date and time associated with the containing program.

YEAR-TO-YYYY
The YEAR-TO-YYYY function converts argument-1, a two-digit year, to a four-digit
year. argument-2, when added to the year at the time of execution, defines the
ending year of a 100-year interval, or sliding century window, into which the year
of argument-1 falls.

The function type is integer.

Format

►► FUNCTION YEAR-TO-YYYY ( argument-1 ) ►◄

argument-2

argument-1
Must be a non-negative integer that is less than 100.
argument-2
Must be an integer. If argument-2 is omitted, the function is evaluated
assuming the value 50 was specified.

The sum of the year at the time of execution and the value of argument-2 must be
less than 10,000 and greater than 1,699.

Examples of return values from the YEAR-TO-YYYY function are shown in the
following table.

Chapter 21. Intrinsic functions 555

 Current year argument-1 value argument-2 value Returned value
1995 4 23 2004
1995 4 -15 1904
2008 98 23 1998
2008 98 -15 1898

556 Enterprise COBOL for z/OS, V6.1 Language Reference

Part 8. Compiler-directing statements and compiler directives

© Copyright IBM Corp. 1991, 2017 557

558 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 22. Compiler-directing statements
A compiler-directing statement is a statement that causes the compiler to take a
specific action during compilation.

You can use compiler-directing statements for the following purposes:

v Extended source library control (BASIS, DELETE, and INSERT statements)
v Source text manipulation (COPY and REPLACE statements)
v Exception handling (USE statement)
v Controlling compiler listings (*CONTROL, *CBL, EJECT, TITLE, SKIP1, SKIP2,
and SKIP3 statements)
v Specifying compiler options (CBL and PROCESS statements)
v Specifying COBOL exception handling procedures (USE statements)

The SERVICE LABEL statement is used with Language Environment condition

handling. It is also generated by the CICS integrated translator (and the separate
CICS translator).

The following compiler directing statements have no effect: ENTER, READY or

RESET TRACE, and SERVICE RELOAD.

BASIS statement
The BASIS statement is an extended source text library statement. It provides a
complete COBOL program as the source for a compilation.

A complete program can be stored as an entry in a user-defined library and can be

used as the source for a compilation. Compiler input is a BASIS statement,
optionally followed by any number of INSERT and DELETE statements.

Format

►► BASIS basis-name ►◄
sequence-number literal-1

sequence-number
Can optionally appear in columns 1 through 6, followed by a space. The
content of this field is ignored.
BASIS
Can appear anywhere in columns 1 through 72, followed by basis-name.
There must be no other text in the statement.
basis-name, literal-1
Is the name by which the library entry is known to the system
environment.
For rules of formation and processing rules, see the description under
literal-1 and text-name of the “COPY statement” on page 562.

© Copyright IBM Corp. 1991, 2017 559

 The source file remains unchanged after execution of the BASIS statement.

Usage note: If INSERT or DELETE statements are used to modify the COBOL
source text provided by a BASIS statement, the sequence field of the COBOL
source text must contain numeric sequence numbers in ascending order.

CBL (PROCESS) statement

With the CBL (PROCESS) statement, you can specify compiler options to be used
in the compilation of the program. The CBL (PROCESS) statement is placed before
the IDENTIFICATION DIVISION header of an outermost program.

Format

►► CBL ►◄
PROCESS options-list

options-list
A series of one or more compiler options, each one separated by a comma
or a space.
For more information about compiler options, see Compiler options in the
Enterprise COBOL Programming Guide.

The CBL (PROCESS) statement can be preceded by a sequence number in columns

1 through 6. The first character of the sequence number must be numeric, and CBL
or PROCESS can begin in column 8 or after; if a sequence number is not specified,
CBL or PROCESS can begin in column 1 or after.

The CBL (PROCESS) statement must end before or at column 72, and options
cannot be continued across multiple CBL (PROCESS) statements. However, you
can use more than one CBL (PROCESS) statement. Multiple CBL (PROCESS)
statements must follow one another with no intervening statements of any other
type.

The CBL (PROCESS) statement must be placed before any comment lines or other
compiler-directing statements.

*CONTROL (*CBL) statement

With the *CONTROL (or *CBL) statement, you can selectively display or suppress
the listing of source code, object code, and storage maps throughout the source
text.

560 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format

►► *CONTROL ▼ SOURCE ►◄
*CBL NOSOURCE .
LIST
NOLIST
MAP
NOMAP

For a complete discussion of the output produced by these options, see Getting
listings in the Enterprise COBOL Programming Guide.

The *CONTROL and *CBL statements are synonymous. *CONTROL is accepted

anywhere that *CBL is accepted.

The characters *CONTROL or *CBL can start in any column beginning with
column 7, followed by at least one space or comma and one or more option
keywords. The option keywords must be separated by one or more spaces or
commas. This statement must be the only statement on the line, and continuation
is not allowed. The statement can be terminated with a period.

The *CONTROL and *CBL statements must be embedded in a program source. For
example, in the case of batch applications, the *CONTROL and *CBL statements
must be placed between the PROCESS (CBL) statement and the end of the
program (or END PROGRAM marker, if specified).

The source line containing the *CONTROL (*CBL) statement will not appear in the
source listing.

If an option is defined at installation as a fixed option, that fixed option takes

precedence over all of the following parameter and statements:
v PARM (if available)
v CBL statement
v *CONTROL (*CBL) statement

The requested options are handled in the following manner:

1. If an option or its negation appears more than once in a *CONTROL statement,
the last occurrence of the option word is used.
2. If the corresponding option has been requested as a parameter to the compiler,
then a *CONTROL statement with the negation of the option word must
precede the portions of the source text for which listing output is to be
inhibited. Listing output then resumes when a *CONTROL statement with the
affirmative option word is encountered.
3. If the negation of the corresponding option has been requested as a parameter
to the compiler, then that listing is always inhibited.
4. The *CONTROL statement is in effect only within the source program in which
it is written, including any contained programs. It does not remain in effect
across batch compiles of two or more COBOL source programs.

Chapter 22. Compiler-directing statements 561

 Source code listing
The topic lists statements that control the listing of the input source text lines.

The statement can be any of the following one:

*CONTROL SOURCE [*CBL SOURCE]
*CONTROL NOSOURCE [*CBL NOSOURCE]

If a *CONTROL NOSOURCE statement is encountered and SOURCE has been

requested as a compilation option, printing of the source listing is suppressed from
this point on. An informational (I-level) message is issued stating that printing of
the source has been suppressed.

Object code listing

The topic lists statements that control the listing of generated object code in the
PROCEDURE DIVISION.

The statement can be any of the following one:

*CONTROL LIST [*CBL LIST]
*CONTROL NOLIST [*CBL NOLIST]

If a *CONTROL NOLIST statement is encountered, and LIST has been requested as

a compilation option, listing of generated object code is suppressed from this point
on.

Storage map listing

The topic lists statements that control the listing of storage map entries occurring
in the DATA DIVISION.

The statement can be any of the following one:

*CONTROL MAP [*CBL MAP]
*CONTROL NOMAP [*CBL NOMAP]

If a *CONTROL NOMAP statement is encountered, and MAP has been requested

as a compilation option, listing of storage map entries is suppressed from this
point on.

For example, either of the following sets of statements produces a storage map
listing in which A and B will not appear:
*CONTROL NOMAP *CBL NOMAP
01 A 01 A
02 B 02 B
*CONTROL MAP *CBL MAP

COPY statement
The COPY statement is a library statement that places prewritten text in a COBOL
compilation unit.

Prewritten source code entries can be included in a compilation unit at compile

time. Thus, an installation can use standard file descriptions, record descriptions,
or procedures without recoding them. These entries and procedures can then be
saved in user-created libraries; they can then be included in programs and class
definitions by means of the COPY statement.

562 Enterprise COBOL for z/OS, V6.1 Language Reference

Compilation of the source code containing COPY statements is logically equivalent
to processing all COPY statements before processing the resulting source text.

The effect of processing a COPY statement is that the library text associated with
text-name is copied into the compilation unit, logically replacing the entire COPY
statement, beginning with the word COPY and ending with the period, inclusive.
When the REPLACING phrase is not specified, the library text is copied
unchanged.

Format

►► COPY text-name ►
literal-1 OF library-name SUPPRESS
IN literal-2

► . ►◄

REPLACING ▼ operand-1 BY operand-2

LEADING == partial-word-1 == BY == partial-word-2 ==
TRAILNG

text-name, library-name
text-name identifies the copy text. library-name identifies where the copy text
exists.
v Can be from 1-30 characters in length
v Can contain the following characters: Latin uppercase letters A-Z, Latin
lowercase letters a-z, digits 0-9, and hyphen
v The first or last character must not be a hyphen
v Cannot contain an underscore
Neither text-name nor library-name need to be unique within a program.
They can be identical to other user-defined words in the program.
text-name need not be qualified. If text-name is not qualified, a library-name
of SYSLIB is assumed.
When compiling from JCL or TSO, only the first eight characters are used
as the identifying name. When compiling with the cob2 command and
processing COPY text residing in the z/OS UNIX file system, all characters
are significant.
literal-1 , literal-2
Must be alphanumeric literals. literal-1 identifies the copy text. literal-2
identifies where the copy text exists.
When compiling from JCL or TSO:
v Literals can be from 1-30 characters in length.
v Literals can contain characters: A-Z, a-z, 0-9, hyphen, @, #, or $.
v The first or last character must not be a hyphen.
v Literals cannot contain an underscore.
v Only the first eight characters are used as the identifying name.
When compiling with the cob2 command and processing COPY text
residing in the z/OS UNIX file system, the literal can be from 1 to 160
characters in length.

Chapter 22. Compiler-directing statements 563

 The uniqueness of text-name and library-name is determined after the formation and
conversion rules for a system-dependent name have been applied.

For information about the mapping of characters in the text-name, library-name, and
literals, see Compiler-directing statements in the Enterprise COBOL Programming
Guide.
operand-1, operand-2
Can be pseudo-text, an identifier, a function-identifier, a literal, or a
COBOL word (except the word COPY). For details, see “REPLACING
phrase” on page 565.

Format

►► == pseudo-text == ►◄
identifier
function-identifier
literal
word

partial-word-1, partial-word-2
Can be a partial-word. For details, see “REPLACING phrase” on page 565.

Each COPY statement must be preceded by a space and ended with a separator
period.

A COPY statement can appear in the source text anywhere a character string or a
separator can appear.

COPY statements can be nested, and any COPY statement in a chain of nested
COPY statements can have the REPLACING phrase, provided there is only one
such COPY statement in the chain. When the REPLACING phrase is specified for a
COPY statement that appears in a chain of nested COPY statements, the
REPLACING phrase applies to all library text that is included by COPY statements
nested under the COPY statement that has the REPLACING phrase.

A nested COPY statement cannot cause recursion. That is, a COPY member can be
named only once in a set of nested COPY statements until the end-of-file for that
COPY member is reached. For example, assume that the source text contains the
statement: COPY X. and library text X contains the statement: COPY Y..

In this case, library text contained in Y must not have a COPY X or a COPY Y
statement.

For details, see “Comparison and replacement rules” on page 566.

Library text copied from the library is placed into the same area of the resultant
program as it is in the library. Library text must conform to the rules for the 85
COBOL Standard format. Library text can consist of or include any words,
identifiers, or literals that can be written in the source text. This includes DBCS
user-defined words, DBCS literals, and national literals.

564 Enterprise COBOL for z/OS, V6.1 Language Reference

Note: Characters outside those defined for COBOL words and separators must not
appear in library text or pseudo-text except in comment lines, inline comments,
comment-entries, alphanumeric literals, DBCS literals, or national literals.

SUPPRESS phrase

The SUPPRESS phrase specifies that the library text is not to be printed on the
source listing.

REPLACING phrase

When the REPLACING phrase is specified, the library text is copied, and each
properly matched occurrence of operand-1 or partial-word-1 within the library text is
replaced by the associated operand-2 or partial-word-2.

In the discussion that follows, when the LEADING or TRAILING keyword of the
REPLACING phrase is specified, each operand of the REPLACING phrase must be
a partial-word. Otherwise, each operand can consist of one of the following items:
v Pseudo-text
v An identifier
v A literal
v A COBOL word (except the word COPY)
v A function-identifier
pseudo-text
A sequence of text words that are bounded by, but not including,
pseudo-text delimiters (==). Both characters of each pseudo-text delimiter
must appear on one line.
Individual text words within pseudo-text can be up to 322 characters long.
They can be continued subject to the normal continuation rules for source
code format.
A text word must be delimited by separators. For more information, see
Chapter 1, “Characters,” on page 3.
pseudo-text-1 refers to pseudo-text when used for operand-1, and
pseudo-text-2 refers to pseudo-text when used for operand-2.
pseudo-text-1 can be one or more text words. It can consist solely of the
separator comma or separator semicolon. pseudo-text-2 can be zero or more
text words. It can consist solely of space characters, comment lines, or
inline comments.
Each text word in pseudo-text-2 that is to be copied into the program is
placed in the same area of the resultant program as the area in which it
appears in pseudo-text-2.
Pseudo-text can consist of or include any words (except COPY), identifiers,
or literals that can be written in the source text. This includes DBCS
user-defined words, DBCS literals, and national literals.
DBCS user-defined words must be wholly formed; that is, there is no
partial-word replacement for DBCS words.
Words or literals containing DBCS characters cannot be continued across
lines.

Chapter 22. Compiler-directing statements 565

 Use pseudo-text when you replace a PICTURE character-string. To avoid
ambiguities, the entire PICTURE clause, including the keyword PICTURE
or PIC, should be specified in pseudo-text-1.
identifier
Can be defined in any section of the DATA DIVISION.
literal
Can be numeric, alphanumeric, DBCS, or national.
word Can be any single COBOL word (except COPY), including DBCS
user-defined words. DBCS user-defined words must be wholly formed.
You cannot replace part of a DBCS word.
You can include the nonseparator COBOL characters (for example, + * / $
< > =) as part of a COBOL word when used as REPLACING operands. In
addition, a hyphen or underscore can be at the beginning of the word or a
hyphen can be at the end of the word.
function-identifier
A sequence of character strings and separators that uniquely references the
data item that results from the evaluation of a function. For more
information, see “Function-identifier” on page 81.
partial-word
A single text word that is bounded by, but not including, pseudo-text
delimiters (==). Both characters of each pseudo-text delimiter must appear
on one line. However, the text word within a partial-word can be
continued.
The following rules apply to partial-word-1 and partial-word-2:
v partial-word-1 consists of one text word.
v partial-word-2 consists of zero or one text word.
v partial-word-1 and partial-word-2 cannot be an alphanumeric literal,
national literal, DBCS literal, or DBCS word.

For purposes of matching, each identifier, literal, word, or function-identifier is

treated as pseudo-text that contains only that identifier, literal, word, or
function-identifier, respectively.

Comparison and replacement rules

This topic introduces detailed rules for comparison and replacement.
v Arithmetic and logical operators are considered text words and can be replaced
only through a pseudo-text operand.
v Beginning and ending blanks are not included in the text comparison process.
Embedded blanks are used in the text comparison process to separate multiple
text words.
v When operand-1 is a figurative constant, operand-1 matches only the same exact
figurative constant. For example, if ALL "AB" is specified in operand-1, "ABAB" in
the library text is not considered a match; only ALL "AB" is considered a match.
v Any separator comma, semicolon, or space that precedes the leftmost word in
the library text is copied into the source text. Beginning with the leftmost library
text word and the first operand-1 or partial-word-1 specified in the REPLACING
phrase, the entire REPLACING operand that precedes the keyword BY is
compared to an equivalent number of contiguous library text words.
v operand-1 matches the library text only if the ordered sequence of text words that
forms operand-1 is equal, character for character, to the ordered sequence of

566 Enterprise COBOL for z/OS, V6.1 Language Reference

 library words. For national characters, the sequence of national characters must
be equal, national character for national character, to the ordered sequence of
library words.
v When the LEADING phrase is specified, partial-word-1 matches the library text
only if the contiguous sequence of characters that forms partial-word-1 is equal,
character for character, to an equal number of contiguous characters that start
with the leftmost character position of a library text word.
When the TRAILING phrase is specified, partial-word-1 matches the library text
only if the contiguous sequence of characters that forms partial-word-1 is equal,
character for character, to an equal number of contiguous characters that end
with the rightmost character position of a library text word.
v For matching purposes, each occurrence of a separator comma, a separator
semicolon, or a sequence of one or more separator spaces is considered to be a
single space.
However, when operand-1 or partial-word-1 consists solely of a separator comma
or separator semicolon, the operand-1 or partial-word-1 participates in the match
as a text word. In this case, the space that follows the comma or semicolon
separator can be omitted.
When the library text contains a closing quotation mark that is not immediately
followed by a separator space, a separator comma, a separator semicolon, or a
separator period, the closing quotation mark is considered a separator quotation
mark.
v If no match occurs, the comparison is repeated with each successive operand-1 or
partial-word-1 if specified, until either a match is found or no further
REPLACING operands exist.
v Whenever a match occurs between operand-1 and the library text, the
corresponding operand-2 is copied into the source text. Whenever a match occurs
between partial-word-1 and the library text word, the matched characters of that
library text word are either replaced by partial-word-2 or deleted when
partial-word-2 consists of zero text words.
v When all operands are compared and no match occurs, the leftmost library text
word is copied into the source text.
v Once a library text word is finished being processed and is either copied into the
source text unchanged or replaced because of a match, the next successive
uncopied library text word is then considered to be the leftmost text word, and
the comparison cycle starts again, beginning with the first occurrence of
operand-1 or partial-word-1. The process continues until the rightmost library text
word is compared.
v The sequence of text words in the library text, pseudo-text-1, and partial-word-1 is
determined by the rules for reference format. For more information, see
Chapter 6, “Reference format,” on page 55.
v When text words are placed in the source text, additional spaces are introduced
only between text words where there already exists a space, including the
assumed space between source lines.
v The following rules apply to comment lines, inline comments, and blank lines:
– Comment lines, inline comments, or blank lines in the library text,
pseudo-text-1, or partial-word-1 are ignored for purposes of matching.
– Comment lines, inline comments, or blank lines in the library text are copied
into the resultant source text unchanged with the following exception: a
comment line, an inline comment, or a blank line in the library text is not
copied if that comment line, inline comment, or blank line appears in the
sequence of text words that match pseudo-text-1 or partial-word-1.

Chapter 22. Compiler-directing statements 567

 – Comment lines, inline comments, or blank lines in pseudo-text-2 or
partial-word-2 are copied into the resultant program unchanged whenever
pseudo-text-2 or partial-word-2 is placed into the source text as a result of text
replacement.
– If the word COPY appears in a comment-entry, or in the place where a
comment-entry can appear, it is considered part of the comment-entry.
v COPY REPLACING does not affect the EJECT, SKIP1, SKIP2, SKIP3, or TITLE
compiler-directing statements.
v Lines that contain *CONTROL (*CBL), EJECT, SKIP1, SKIP2, SKIP3, or TITLE
statements can appear in the library text. Such lines are copied into the resultant
source text unchanged.
v The following rules apply to debugging lines:
– Debugging lines are permitted in library text and pseudo-text. Text words
within a debugging line participate in the matching rules as if the letter "D"
did not appear in the indicator area. A debugging line is specified within
pseudo-text if the debugging line begins in the source text after the opening
pseudo-text delimiter but before the matching closing pseudo-text delimiter.
– If more lines are introduced into the source text as a result of a COPY
statement, each text word that is introduced appears on a debugging line if
the COPY statement begins on a debugging line or if the text word that is
introduced appears on a debugging line in library text. When a text word
specified in the BY phrase is introduced, it appears on a debugging line if the
first library text word that is being replaced is specified on a debugging line.
– When a COPY statement is specified on a debugging line, the copied text is
treated as though it appeared on a debugging line, except that comment lines
in the text appear as comment lines in the resulting source text.
– After all COPY and REPLACE statements are processed, a debugging line will
be considered to have all the characteristics of a comment line, if the WITH
DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER
paragraph.
v The syntactic correctness of the entire COBOL source text cannot be determined
until all COPY and REPLACE statements have been completely processed,
because the syntactic correctness of the library text cannot be independently
determined.
v (This rule applies to pseudo-text only.) If the source text has occurrences of a
dummy operand :TAG: that is delimited by colons in the program text, the
compiler replaces the dummy operand with the required text. Example 3 shows
how it is used with the dummy operand :TAG:. The colons serve as separators
and make TAG a stand-alone operand.
v The COPY statement with REPLACING phrase can be used to replace parts of
words, either by using the LEADING|TRAILING partial-word-1 BY partial-word-2
phrase, or by using the pseudo-text :TAG: method.
v After replacement, text words are placed in the source text according to the 85
COBOL Standard format rules.

Comparison and replacement examples

This topic shows examples of comparison and replacement.

Sequences of code (such as file and data descriptions, error, and exception
routines) that are common to a number of programs can be saved in a library, and
then used with the COPY statement. If naming conventions are established for
such common code, the REPLACING phrase need not be specified. If the names

568 Enterprise COBOL for z/OS, V6.1 Language Reference

change from one program to another, the REPLACING phrase can be used to
supply meaningful names for this program.

Example 1

In this example, the library text PAYLIB consists of the following DATA DIVISION
entries:
01 A.
02 B PIC S99.
02 C PIC S9(5)V99.
02 D PIC S9999 OCCURS 1 TO 52 TIMES
DEPENDING ON B OF A.

You can use the COPY statement in the DATA DIVISION of a program as follows:
COPY PAYLIB.

In this program, the library text is copied. The resulting text is treated as if it were
written as follows:
01 A.
02 B PIC S99.
02 C PIC S9(5)V99.
02 D PIC S9999 OCCURS 1 TO 52 TIMES
DEPENDING ON B OF A.

Example 2

To change some or all of the names within the library text, you can use the
REPLACING phrase:
COPY PAYLIB REPLACING A BY PAYROLL
B BY PAY-CODE
C BY GROSS-PAY
D BY HOURS.

In this program, the library text is copied. The resulting text is treated as if it were
written as follows:
01 PAYROLL.
02 PAY-CODE PIC S99.
02 GROSS-PAY PIC S9(5)V99.
02 HOURS PIC S9999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAY-CODE OF PAYROLL.

The changes that are shown are made only for this program. The text remains
unchanged as it appears in the library.

Example 3

If the following conventions are followed in the library text, parts of names (for
example, the prefix portion of data names) can be changed with the REPLACING
phrase.

In this example, the library text PAYLIB consists of the following DATA DIVISION
entries:
01 :TAG:.
02 :TAG:-WEEK PIC S99.
02 :TAG:-GROSS-PAY PIC S9(5)V99.
02 :TAG:-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON :TAG:-WEEK OF :TAG:.

Chapter 22. Compiler-directing statements 569

 You can use the COPY statement in the DATA DIVISION of a program as follows:
COPY PAYLIB REPLACING ==:TAG:== BY ==Payroll==.

Usage Note: In this example, the required use of colons or parentheses as

delimiters in the library text. Colons are recommended for clarity because
parentheses can be used for a subscript, for instance in referencing a table element.

In this program, the library text is copied. The resulting text is treated as if it were
written as follows:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 PAYROLL-GROSS-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.

The changes that are shown are made only for this program. The text remains
unchanged as it appears in the library.

Example 4

This example shows how to selectively replace level numbers without replacing the
numbers in the PICTURE clause:
COPY xxx REPLACING ==(01)== BY ==(01)==
== 01 == BY == 05 ==.

Example 5

This example demonstrates use of the LEADING keyword of the REPLACING

phrase in the COPY statement. The library text PAYLIB consists of the following
DATA DIVISION entries:
01 DEPT.
02 DEPT-WEEK PIC S99.
02 DEPT-GROSS-PAY PIC S9(5)V99.
02 DEPT-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON DEPT-WEEK OF DEPT.

You can use the COPY statement in the DATA DIVISION of a program as follows:
COPY PAYLIB REPLACING LEADING == DEPT == BY == PAYROLL ==.

In this program, the library text is copied. The resulting text is treated as if it were
written as follows:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 PAYROLL-GROSS-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.

The changes that are shown are made only for this program. The text remains
unchanged as it appears in the library.

Example 6

This example demonstrates use of the TRAILING keyword of the REPLACING

phrase in the COPY statement. The library text PAYLIB consists of the following
DATA DIVISION entries:

570 Enterprise COBOL for z/OS, V6.1 Language Reference

01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 PAYROLL-GROSS-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.

You can use the COPY statement in the DATA DIVISION of a program as follows:
COPY PAYLIB REPLACING TRAILING == GROSS-PAY == BY == NET-PAY ==.

In this program, the library text is copied. The resulting text is treated as if it were
written as follows:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 PAYROLL-NET-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.

The changes that are shown are made only for this program. The text remains
unchanged as it appears in the library.

Example 7

This example demonstrates a scenario where two types of partial-word

replacement are specified in a single REPLACING phrase. The library text PAYLIB
consists of the following DATA DIVISION entries:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 :TAG:-GROSS-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.

You can use the COPY statement in the DATA DIVISION of a program as follows:
COPY PAYLIB REPLACING == :TAG: == BY == PAYROLL ==
TRAILING == GROSS-PAY == BY == NET-PAY ==.

In this program, the library text is copied. The resulting text is treated as if it were
written as follows:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 PAYROLL-GROSS-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.

Two types of partial-word replacement are specified in the same REPLACING

operation, but as usual, one replacement is done on a single library text word.
Therefore, even though :TAG:-GROSS-PAY is considered a match with the first
operand of both replacement operations, after the first match and replacement is
performed, no more replacement is performed on that word.

The changes that are shown are made only for this program. The text remains
unchanged as it appears in the library.

Example 8

This example demonstrates support for the REPLACING phrase in a chain of

nested COPY statements. In this example, it is the outermost COPY statement that
has the REPLACING phrase, but note that the REPLACING phrase can be

Chapter 22. Compiler-directing statements 571

 specified on any of the nested COPY statements in the chain, provided it is
specified on only one of them. The library text PAYLIB consists of the following
DATA DIVISION entries:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 :TAG:-GROSS-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.
COPY PAYLIB2

The library text PAYLIB2 consists of the following DATA DIVISION entries:
01 PAYROLL2.
02 PAYROLL2-WEEK PIC S99.
02 :TAG:2-GROSS-PAY PIC S9(5)V99.
02 PAYROLL2-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL2-WEEK OF PAYROLL2.

You can use the COPY statement in the DATA DIVISION of a program as follows:
COPY PAYLIB REPLACING == :TAG: == BY == PAYROLL ==
TRAILING == GROSS-PAY == BY == NET-PAY ==.

In this program, the library text is copied. The resulting text is treated as if it were
written as follows:
01 PAYROLL.
02 PAYROLL-WEEK PIC S99.
02 PAYROLL-NET-PAY PIC S9(5)V99.
02 PAYROLL-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL-WEEK OF PAYROLL.

01 PAYROLL2.
02 PAYROLL2-WEEK PIC S99.
02 PAYROLL2-NET-PAY PIC S9(5)V99.
02 PAYROLL2-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON PAYROLL2-WEEK OF PAYROLL2.

The REPLACING phrase in the outermost COPY statement applies not only to the
library text in PAYLIB but also to the text in PAYLIB2.

The changes that are shown are made only for this program. The text remains
unchanged as it appears in the library.

DELETE statement
The DELETE statement is an extended source library statement. It removes COBOL
statements from a source program that was included by a BASIS statement.

Format

►► DELETE sequence-number-field ►◄
sequence-number

sequence-number
Can optionally appear in columns 1 through 6, followed by a space. The
content of this field is ignored.

572 Enterprise COBOL for z/OS, V6.1 Language Reference

 DELETE
Can appear anywhere within columns 1 through 72. The keyword DELETE
must be followed by a space and the sequence-number-field. There must be
no other text in the statement.
sequence-number-field
Each number must be equal to a sequence-number in the BASIS source
program. This sequence-number is the six-digit number the programmer
assigns in columns 1 through 6 of the COBOL coding form. The numbers
referenced in the sequence-number-field of INSERT or DELETE statements
must always be specified in ascending numeric order.
The sequence-number-field must be one of the following options:
v A single number
v A series of single numbers
v A range of numbers (indicated by separating the two bounding numbers
of the range by a hyphen)
v A series of ranges of numbers
v Any combination of one or more single numbers and one or more
ranges of numbers
Each entry in the sequence-number-field must be separated from the
preceding entry by a comma followed by a space. For example:
000250 DELETE 000010-000050, 000400, 000450

Source program statements can follow a DELETE statement. These source program
statements are then inserted into the BASIS source program before the statement
following the last statement deleted (that is, in the example above, before the next
statement following deleted statement 000450).

If a DELETE statement begins in column 12 or higher and a valid

sequence-number-field does not follow the keyword DELETE, the compiler assumes
that this DELETE statement is a COBOL DELETE statement.

Usage note: If INSERT or DELETE statements are used to modify the COBOL
source program provided by a BASIS statement, the sequence field of the COBOL
source program must contain numeric sequence numbers in ascending order. The
source file remains unchanged. Any INSERT or DELETE statements referring to
these sequence numbers must occur in ascending order.

EJECT statement
The EJECT statement specifies that the next source statement is to be printed at the
top of the next page.

Format

►► EJECT ►◄
.

Chapter 22. Compiler-directing statements 573

 The EJECT statement must be the only statement on the line. It can be written in
either Area A or Area B, and can be terminated with a separator period.

The EJECT statement must be embedded in a program source. For example, in the
case of batch applications, the EJECT statement must be placed between the CBL
(PROCESS) statement and the end of the program (or the END PROGRAM marker,
if specified).

The EJECT statement has no effect on the compilation of the source unit itself.

ENTER statement
The ENTER statement is designed to facilitate the use of more than one source
language in the same source program. However, only COBOL is allowed in the
source program.

The ENTER statement is syntax checked but has no effect on the execution of the
program.

Format

►► ENTER language-name-1 . ►◄
routine-name-1

language-name-1
A system name that has no defined meaning. It must be either a correctly
formed user-defined word or the word "COBOL." At least one character
must be alphabetic.
routine-name-1
Must follow the rules for formation of a user-defined word. At least one
character must be alphabetic.

INSERT statement
The INSERT statement is a library statement that adds COBOL statements to a
source program that was included by a BASIS statement.

Format

►► INSERT sequence-number-field ►◄
sequence-number

sequence-number
Can optionally appear in columns 1 through 6, followed by a space. The
content of this field is ignored.

574 Enterprise COBOL for z/OS, V6.1 Language Reference

 INSERT
Can appear anywhere within columns 1 through 72, followed by a space
and the sequence-number-field. There must be no other text in the statement.
sequence-number-field
A number that must be equal to a sequence-number in the BASIS source
program. This sequence-number is a six-digit number that the programmer
assigns in columns 1 through 6 of the COBOL source line.
The numbers referenced in the sequence-number-field of INSERT or DELETE
statements must always be specified in ascending numeric order.
The sequence-number-field must be a single number (for example, 000130). At
least one new source program statement must follow the INSERT
statement for insertion after the statement number specified by the
sequence-number-field.

New source program statements following the INSERT statement can include any
COBOL syntax.

Usage note: If INSERT or DELETE statements are used to modify the COBOL
source program provided by a BASIS statement, the sequence field of the COBOL
source program must contain numeric sequence numbers in ascending order. The
source file remains unchanged. Any INSERT or DELETE statements referring to
these sequence numbers must occur in ascending order.

READY or RESET TRACE statement

The READY or RESET TRACE statement was designed to trace the execution of
procedures. The READY or RESET TRACE statement can appear only in the
PROCEDURE DIVISION, but has no effect on your program.

Format

►► READY TRACE . ►◄
RESET

You can trace the execution of procedures by using the USE FOR DEBUGGING
declarative as described in Example: USE FOR DEBUGGING in the Enterprise
COBOL Programming Guide.

REPLACE statement
The REPLACE statement is used to replace source text.

A REPLACE statement can occur anywhere in the source text that a

character-string can occur. It must be preceded by a separator period except when
it is the first statement in a separately compiled program. It must ends with a
separator period.

The REPLACE statement provides a means of applying a change to an entire

COBOL compilation group, or part of a compilation group, without manually
having to find and modify all places that need to be changed. It is an easy method

Chapter 22. Compiler-directing statements 575

 of doing simple string substitutions. It is similar in action to the REPLACING
phrase of the COPY statement, except that it acts on the entire source text, not just
on the text in COPY libraries.

If the word REPLACE appears in a comment-entry or in the place where a

comment-entry can appear, it is considered part of the comment-entry.

Format 1

►► REPLACE ►

► ▼ == pseudo-text-1 == BY == pseudo-text-2 == . ►◄
LEADING == partial-word-1 == BY == partial-word-2 ==
TRAILING

Each matched occurrence of pseudo-text-1 in the source text is replaced by the

corresponding pseudo-text-2.

Format 2

►► REPLACE OFF. ►◄

Any text replacement currently in effect is discontinued with the format-2 form of
REPLACE. If format 2 is not specified, a specific occurrence of the REPLACE
statement is in effect from the point at which it is specified until the next
occurrence of a REPLACE statement or the end of the separately compiled
program.
pseudo-text-1, pseudo-text-2
A sequence of text words that are bounded by, but not including,
pseudo-text delimiters (==). Both characters of each pseudo-text delimiter
must appear on one line.
Individual text words within pseudo-text can be up to 322 characters long.
They can be continued subject to the normal continuation rules for source
code format.
A text word must be delimited by separators. For more information, see
Chapter 1, “Characters,” on page 3.
pseudo-text-1 can be one or more text words. It can consist solely of the
separator comma or separator semicolon. pseudo-text-2 can be zero or more
text words. It can consist solely of space characters, comment lines, or
inline comments.
Each text word in pseudo-text-2 that is to be copied into the program is
placed in the same area of the resultant program as the area in which it
appears in pseudo-text-2.
576 Enterprise COBOL for z/OS, V6.1 Language Reference
 Pseudo-text can consist of or include any words (except COPY), identifiers,
or literals that can be written in the source text. This includes DBCS
user-defined words, DBCS literals, and national literals.
DBCS user-defined words must be wholly formed; that is, there is no
partial-word replacement for DBCS words.
Words or literals containing DBCS characters cannot be continued across
lines.
partial-word-1, partial-word-2
A single text word that is bounded by, but not including, pseudo-text
delimiters (==). Both characters of each pseudo-text delimiter must appear
on one line. However, the text word within a partial-word can be
continued.
The following rules apply to partial-word-1 and partial-word-2:
v partial-word-1 consists of one text word.
v partial-word-2 consists of zero or one text word.
v partial-word-1 and partial-word-2 cannot be an alphanumeric literal,
national literal, DBCS literal, or DBCS word.

The compiler processes REPLACE statements in source text after the processing of
any COPY statements. COPY must be processed first to assemble complete source
text. Then, REPLACE can be used to modify that source text, performing simple
string substitution. REPLACE statements cannot themselves contain COPY
statements.

The text that is produced as a result of the processing of a REPLACE statement

must not contain a REPLACE statement.

Continuation rules for pseudo-text and partial-word

The character-strings and separators that comprise pseudo-text and partial-words

can start in either Area A or Area B. However, if a hyphen is in the indicator area
of a line, and that hyphen follows the opening pseudo-text or partial-word
delimiter, Area A of the line must be blank, and the normal rules for continuation
of lines apply to the formation of text words. See “Continuation lines” on page 58.

Comparison rules
The comparison operation that determines text replacement starts with the leftmost
source text word that follows the REPLACE statement, and with the first word of
pseudo-text-1 or partial-word-1.
v pseudo-text-1 is compared to an equivalent number of contiguous source text
words. pseudo-text-1 matches the source text only if the ordered sequence of text
words that forms pseudo-text-1 is equal, character for character, to the ordered
sequence of source text words. For national characters, the sequence of national
characters must be equal, national character for national character, to the ordered
sequence of library words.
v When the LEADING phrase is specified, partial-word-1 matches the source text
only if the contiguous sequence of characters that forms partial-word-1 is equal,
character for character, to an equal number of contiguous characters that start
with the leftmost character position of a source text word.
When the TRAILING phrase is specified, partial-word-1 matches the source text
only if the contiguous sequence of characters that forms partial-word-1 is equal,

Chapter 22. Compiler-directing statements 577

 character for character, to an equal number of contiguous characters that end
with the rightmost character position of a source text word.
v For matching purposes, each occurrence of a separator comma, a separator
semicolon, or a sequence of one or more separator spaces is considered to be a
single space.
However, when pseudo-text-1 or partial-word-1 consists solely of a separator
comma or separator semicolon, the comma or semicolon participates in the
match as a text word. In this case, the space that follows the comma or
semicolon separator can be omitted.
When the source text contains a closing quotation mark that is not immediately
followed by a separator space, a separator comma, a separator semicolon, or a
separator period, the closing quotation mark is considered a separator quotation
mark.
v If no match occurs, the comparison is repeated with each successive occurrence
of pseudo-text-1 or partial-word-1 if specified, until either a match is found or no
further REPLACING operands exist.
v When all occurrences of pseudo-text-1 or partial-word-1 are compared and no
match occurs, the next successive source text word is then considered to be the
leftmost source text word, and the comparison cycle starts again, beginning with
the first occurrence of pseudo-text-1 or partial-word-1.
v Whenever a match occurs between pseudo-text-1 and the source text, the
corresponding pseudo-text-2 replaces the matched text in the source text.
Whenever a match occurs between partial-word-1 and the source text word, the
matched characters of that source text word are either replaced by partial-word-2
or deleted if partial-word-2 consists of zero text words.The source text word that
immediately follows the rightmost text word that participated in the match is
then considered as the leftmost source text word. The comparison cycle starts
again, beginning with the first occurrence of pseudo-text-1 or partial-word-1.
v The comparison operation continues until the rightmost text word in the source
text that is within the scope of the REPLACE statement has either participated in
a match, or been considered as a leftmost source text word and participated in a
complete comparison cycle.

Replacement rules
This topic introduces detailed rules for replacement.
v The sequence of text words in the source text, pseudo-text-1, and partial-word-1 is
determined by the rules for reference format. For more information, see
Chapter 6, “Reference format,” on page 55.
v Text words that are inserted into the source text as a result of processing a
REPLACE statement are placed in the source text according to the rules for
reference format. When inserting text words of pseudo-text-2 or partial-word-2 into
the source text, additional spaces are introduced only between text words where
there already exists a space, including the assumed space between source lines.
v If more lines are introduced into the source text as a result of the processing of
REPLACE statements, the indicator area of the introduced lines contains the
same character as the line on which the text being replaced begins, unless that
line contains a hyphen, in which case the introduced line contains a space.
v If any literal within pseudo-text-2 or partial-word-2 is of a length too great to be
accommodated on a single line without continuation to another line in the
resultant program, and the literal is not being placed on a debugging line, more
continuation lines are introduced that contain the remainder of the literal. If
replacement requires the continued literal to be continued on a debugging line,
the program is in error.

578 Enterprise COBOL for z/OS, V6.1 Language Reference

v Each word in pseudo-text-2 or partial-word-2 that is to be placed into the resultant
program begins in the same area of the resultant program as it appears in
pseudo-text-2 or partial-word-2.
v The following rules apply to comment lines, inline comments, and blank lines:
– Comment lines, inline comments, or blank lines in the source text,
pseudo-text-1, or partial-word-1 are ignored for purposes of matching.
– Comment lines, inline comments, or blank lines in the source text are copied
into the resultant source text unchanged with the following exception: a
comment line, an inline comment, or a blank line in the source text is not
copied if that comment line, inline comment, or blank line appears in the
sequence of text words that match pseudo-text-1 or partial-word-1.
– Comment lines, inline comments, or blank lines in pseudo-text-2 or
partial-word-2 are copied into the resultant program unchanged whenever
pseudo-text-2 or partial-word-2 is placed into the source text as a result of text
replacement.
v Lines that contain *CONTROL (*CBL), EJECT, SKIP1, SKIP2, SKIP3, or TITLE
statements can appear in the source text. Such lines are copied into the resultant
source text unchanged.
v The following rules apply to debugging lines:
– Debugging lines are permitted in pseudo-text or partial-words. Text words
within a debugging line participate in the matching rules as if the letter "D"
did not appear in the indicator area.
– When a REPLACE statement is specified on a debugging line, the statement is
treated as if the letter "D" did not appear in the indicator area.
– After all COPY and REPLACE statements are processed, a debugging line is
considered to have all the characteristics of a comment line if the WITH
DEBUGGING MODE clause is not specified in the SOURCE-COMPUTER
paragraph.
v Except for COPY and REPLACE statements, the syntactic correctness of the
source text cannot be determined until all COPY and REPLACE statements are
completely processed.
v (This rule only applies to pseudo-text.) If the source text has occurrences of a
dummy operand :TAG: that is delimited by colons in the program text, the
compiler replaces the dummy operand with the required text. The colons serve
as separators and make TAG a stand-alone operand.
For example, you can use the REPLACE statement in the DATA DIVISION of a
program as follows:
REPLACE ==:TAG:== BY ==Payroll==.

01 :TAG:.
02 :TAG:-WEEK PIC S99.
02 :TAG:-GROSS-PAY PIC S9(5)V99.
02 :TAG:-HOURS PIC S999 OCCURS 1 TO 52 TIMES
DEPENDING ON :TAG:-WEEK OF :TAG:.
v The REPLACE statement can be used to replace parts of words, either by using
the LEADING|TRAILING partial-word-1 BY partial-word-2 phrase, or by using
the pseudo-text :TAG: method.

Chapter 22. Compiler-directing statements 579

SERVICE LABEL statement
This statement is generated by the CICS integrated language translator (and the
separate CICS translator) to indicate control flow. It is also used after calls to
CEE3SRP when using Language Environment condition handling. For more
information about CEE3SRP, see the Language Environment Programming Guide.

Format

►► SERVICE LABEL ►◄

The SERVICE LABEL statement can appear only in the PROCEDURE DIVISION,
but not in the declaratives section.

SERVICE RELOAD statement

The SERVICE RELOAD statement is syntax checked, but has no effect on the
execution of the program.

Format

►► SERVICE RELOAD identifier-1 ►◄

SKIP statements
The SKIP1, SKIP2, and SKIP3 statements specify blank lines that the compiler
should add when printing the source listing. SKIP statements have no effect on the
compilation of the source text itself.

Format

►► SKIP1 ►◄
SKIP2 .
SKIP3

SKIP1
Specifies a single blank line to be inserted in the source listing.
SKIP2
Specifies two blank lines to be inserted in the source listing.
SKIP3
Specifies three blank lines to be inserted in the source listing.

580 Enterprise COBOL for z/OS, V6.1 Language Reference

 SKIP1, SKIP2, or SKIP3 can be written anywhere in either Area A or Area B, and
can be terminated with a separator period. It must be the only statement on the
line.

The SKIP statements must be embedded in a program source. For example, in the
case of batch applications, a SKIP1, SKIP2, or SKIP3 statement must be placed
between the CBL (PROCESS) statement and the end of the program or class (or the
END CLASS marker or END PROGRAM marker, if specified).

TITLE statement
The TITLE statement specifies a title to be printed at the top of each page of the
source listing produced during compilation.

If no TITLE statement is found, a title containing the identification of the compiler

and the current release level is generated. The title is left-justified on the title line.

Format

►► TITLE literal ►◄
.

literal
Must be an alphanumeric literal, DBCS literal, or national literal and can
be followed by a separator period.
Must not be a figurative constant.

In addition to the default or chosen title, the right side of the title line contains the
following items:
v For programs, the name of the program from the PROGRAM-ID paragraph for
the outermost program. (This space is blank on pages preceding the
PROGRAM-ID paragraph for the outermost program.)
v For classes, the name of the class from the CLASS-ID paragraph.
v Current page number.
v Date and time of compilation.

The TITLE statement:

v Forces a new page immediately, if the SOURCE compiler option is in effect
v Is not itself printed on the source listing
v Has no other effect on compilation
v Has no effect on program execution
v Cannot be continued on another line
v Can appear anywhere in any of the divisions

A title line is produced for each page in the listing produced by the LIST option.
This title line uses the last TITLE statement found in the source statements or the
default.

The word TITLE can begin in either Area A or Area B.

Chapter 22. Compiler-directing statements 581

 The TITLE statement must be embedded in a class or program source. For
example, in the case of batch applications, the TITLE statement must be placed
between the CBL (PROCESS) statement and the end of the class or program (or the
END CLASS marker or END PROGRAM marker, if specified).

No other statement can appear on the same line as the TITLE statement.

USE statement
The USE statement defines the conditions under which the procedures that follow
the statement will be executed.

The formats for the USE statement are:

v EXCEPTION/ERROR declarative
v DEBUGGING declarative

For general information about declaratives, see “Declaratives” on page 259.

EXCEPTION/ERROR declarative
The EXCEPTION/ERROR declarative specifies procedures for input/output
exception or error handling that are to be executed in addition to the standard
system procedures.

The words EXCEPTION and ERROR are synonymous and can be used
interchangeably.

Format 1: USE statement for EXCEPTION/ERROR declarative

►► USE AFTER EXCEPTION PROCEDURE ►

GLOBAL STANDARD ERROR ON

► ▼ file-name-1 ►◄
INPUT
OUTPUT
I-O
EXTEND

file-name-1
Valid for all files. When this option is specified, the procedure is executed
only for the files named. No file-name can refer to a sort or merge file. For
any given file, only one EXCEPTION/ERROR procedure can be specified;
thus, file-name specification must not cause simultaneous requests for
execution of more than one EXCEPTION/ERROR procedure.
A USE AFTER EXCEPTION/ERROR declarative statement specifying the
name of a file takes precedence over a declarative statement specifying the
open mode of the file.

582 Enterprise COBOL for z/OS, V6.1 Language Reference

INPUT
Valid for all files. When this option is specified, the procedure is executed
for all files opened in INPUT mode or in the process of being opened in
INPUT mode that get an error.
OUTPUT
Valid for all files. When this option is specified, the procedure is executed
for all files opened in OUTPUT mode or in the process of being opened in
OUTPUT mode that get an error.
I-O Valid for all direct-access files. When this option is specified, the procedure
is executed for all files opened in I-O mode or in the process of being
opened in I-O mode that get an error.
EXTEND
Valid for all files. When this option is specified, the procedure is executed
for all files opened in EXTEND mode or in the process of being opened in
EXTEND mode that get an error.

The EXCEPTION/ERROR procedure is executed:

v Either after completing the system-defined input/output error routine, or
v Upon recognition of an INVALID KEY or AT END condition when an INVALID
KEY or AT END phrase has not been specified in the input/output statement, or
v Upon recognition of an IBM-defined condition that causes file status key 1 to be
set to 9. (See “File status key” on page 295.)

After execution of the EXCEPTION/ERROR procedure, control is returned to the

invoking routine in the input/output control system. If the input/output status
value does not indicate a critical input/output error, the input/output control
system returns control to the next executable statement following the input/output
statement whose execution caused the exception.

An applicable EXCEPTION/ERROR procedure is activated when an input/output

error occurs during execution of a READ, WRITE, REWRITE, START, OPEN,
CLOSE, or DELETE statement. To determine what conditions are errors, see
“Common processing facilities” on page 295.

The following rules apply to declarative procedures:

v A declarative procedure can be performed from a nondeclarative procedure.
v A nondeclarative procedure can be performed from a declarative procedure.
v A declarative procedure can be referenced in a GO TO statement in a declarative
procedure.
v A nondeclarative procedure can be referenced in a GO TO statement in a
declarative procedure.

You can include a statement that executes a previously called USE procedure that
is still in control. However, to avoid an infinite loop, you must be sure that there is
an eventual exit at the bottom.

You cannot use a GOBACK statement or a STOP RUN statement when an

EXCEPTION/ERROR declarative is active due to a QSAM abend for a READ,
WRITE, or REWRITE statement. You cannot use an EXIT PROGRAM statement in
a non-nested subprogram when an EXCEPTION/ERROR declarative is active due
to a QSAM abend for a READ, WRITE, or REWRITE statement. When a QSAM
abend occurs during a READ, WRITE, or REWRITE statement, the file status code
can be "34" or "90".

Chapter 22. Compiler-directing statements 583

 You cannot use a GOBACK statement or an EXIT PROGRAM statement while a
declarative is active in a nested program. You cannot use a GOBACK statement or
an EXIT METHOD statement while a declarative is active in a method.

EXCEPTION/ERROR procedures can be used to check the file status key values
whenever an input/output error occurs.

Precedence rules for nested programs

Special precedence rules are followed when programs are contained within other
programs.

In applying these rules, only the first qualifying declarative is selected for
execution. The order of precedence for selecting a declarative is:
1. A file-specific declarative (that is, a declarative of the form USE AFTER ERROR
ON file-name-1) within the program that contains the statement that caused the
qualifying condition.
2. A mode-specific declarative (that is, a declarative of the form USE AFTER
ERROR ON INPUT) within the program that contains the statement that
caused the qualifying condition.
3. A file-specific declarative that specifies the GLOBAL phrase and is within the
program directly containing the program that was last examined for a
qualifying declarative.
4. A mode-specific declarative that specifies the GLOBAL phrase and is within the
program directly containing the program that was last examined for a
qualifying condition.

Steps 3 and 4 are repeated until the last examined program is the outermost
program, or until a qualifying declarative has been found.

DEBUGGING declarative
Debugging sections are permitted only in the outermost program; they are not
valid in nested programs. Debugging sections are never triggered by procedures
contained in nested programs.

Debugging sections are not permitted in:

v A method
v A program defined with the recursive attribute
v A program compiled with the THREAD compiler option

The WITH DEBUGGING MODE clause of the SOURCE-COMPUTER paragraph

activates all debugging sections and lines that have been compiled into the object
code. See Appendix D, “Source language debugging,” on page 617 for additional
details.

When the debugging mode is suppressed by not specifying the WITH

DEBUGGING MODE clause, all USE FOR DEBUGGING declarative procedures
and all debugging lines are inhibited.

Automatic execution of a debugging section is not caused by a statement that

appears in a debugging section.

584 Enterprise COBOL for z/OS, V6.1 Language Reference

 Format 2: USE statement for DEBUGGING declarative

►► USE DEBUGGING ▼ procedure-name-1 ►◄

FOR ON ALL PROCEDURES

USE FOR DEBUGGING

All debugging statements must be written together in a section
immediately after the DECLARATIVES header.
Except for the USE FOR DEBUGGING sentence itself, within the
debugging procedure there must be no reference to any nondeclarative
procedures.
procedure-name-1
Must not be defined in a debugging session.
Table 55 shows, for each valid option, the points during execution when
the USE FOR DEBUGGING procedures are executed.
Any given procedure-name can appear in only one USE FOR
DEBUGGING sentence, and only once in that sentence. All procedures
must appear in the outermost program.
ALL PROCEDURES
procedure-name-1 must not be specified in any USE FOR DEBUGGING
sentences. The ALL PROCEDURES phrase can be specified only once in a
program. Only the procedures contained in the outermost program will
trigger execution of the debugging section.
Table 55. Execution of debugging declaratives
USE FOR
DEBUGGING Upon execution of the following, the USE FOR DEBUGGING
operand procedures are executed immediately
procedure-name-1 Before each execution of the named procedure

After the execution of an ALTER statement referring to the named

procedure
ALL PROCEDURES Before each execution of each nondebugging procedure in the
outermost program

After the execution of each ALTER statement in the outermost

program (except ALTER statements in declarative procedures)

Chapter 22. Compiler-directing statements 585

586 Enterprise COBOL for z/OS, V6.1 Language Reference
Chapter 23. Compiler directives
A compiler directive is a statement that causes the compiler to take a specific action
during compilation.

CALLINTERFACE
The CALLINTERFACE directive specifies the interface convention for CALL and
SET statements. The convention specified stays in effect until another
CALLINTERFACE directive is encountered in the source.

Format

►► >>CALLINTERFACE ►◄
>>CALLINT DLL
DYNAMIC
STATIC

DLL Specifies that the interface convention for subsequent CALL statements is a
call to a DLL, and that subsequent SET function-pointer and
procedure-pointer statements are treated as if the DLL compiler option was
in effect.
DYNAMIC
Specifies that the interface convention for subsequent CALL literal
statements and subsequent SET function-pointer and procedure-pointer
statements is dynamic (as if the DYNAM compiler option was in effect).
STATIC
Specifies that the interface convention for subsequent CALL statements and
subsequent SET function pointer and procedure pointer statements is static
(as if the NODLL and NODYNAM compiler options were in effect).

If the >>CALLINTERFACE directive has no suboptions, the interface convention

for subsequent CALL and SET statements is determined by the setting of the DLL
and DYNAM compiler options.

The >>CALLINTERFACE directive has no effect on the CANCEL statement.

The >>CALLINTERFACE directive can only appear in the procedure division.

The positions of CALL statements relative to the CALLINTERFACE directive are

determined following any processing of COPY and REPLACE statements. For
example, CALL statements and CALLINTERFACE directives in COPY text are
processed by the rules specified for the CALLINTERFACE directive.

© Copyright IBM Corp. 1991, 2017 587

 Syntax and general rules

You must specify >>CALLINTERFACE on a line by itself, in Area B.

You cannot specify >>CALLINTERFACE in the following cases:

v Within a COPY or REPLACE statement
v Between the lines of a continued character string
v In the middle of a COBOL statement

The >>CALLINTERFACE specification is limited to the current compilation unit.

The REPLACE statement and REPLACING phrase of the COPY statement do not
affect the CALLINTERFACE directive.

Precedence of CALLINTERFACE directive versus DLL and

DYNAM compiler options

If you specify both the CALLINTERFACE directive (with suboptions) and the DLL
or the DYNAM compiler option, the directive overrides the compiler option in
effect and determines the interface to be used for subsequent CALL and SET
statements.

If you specify the CALLINTERFACE directive without any suboptions, the DLL or
the DYNAM compiler option will determine the interface to use for subsequent
CALL and SET statements.

| INLINE
| The INLINE directive lets you selectively prevent the compiler from considering
| procedures eligible for inlining. Specifying >>INLINE OFF prevents the compiler
| from inlining procedures referenced by PERFORM statements. If the NOINLINE
| compiler option is in effect, all INLINE directives are ignored. The relative location
| of an INLINE directive to the definition of a procedure name is important for
| determining the inlining behavior for that procedure.

| Format

| ►► >>INLINE ON ►◄
OFF
|
||

| ON Specifies that the compiler determines if the procedures within the scope of
| the directive are inlined in a specific PERFORM statement when
| OPTIMIZE(1) or OPTIMIZE(2) is in effect.
| OFF Specifies that procedures within the scope of the directive will not be
| inlined when referenced by PERFORM statements, no matter which
| optimization level setting is in effect.

| Note: The word inlining here implies that the compiler might choose to replace the
| PERFORM of a procedure (paragraph or section) with a copy of that procedure's
| code. By inserting the procedure code at the location of the PERFORM, the
| compiler saves the overhead of branching logic to and from the procedure.
588 Enterprise COBOL for z/OS, V6.1 Language Reference
| Syntax and general rules

| You must specify >>INLINE ON or >>INLINE OFF on a line by itself, in either

| Area A or Area B.

| You cannot specify >>INLINE ON or >>INLINE OFF in the following cases:

| v Within a COPY or REPLACE statement
| v Between the lines of a continued character string
| v In the middle of a COBOL statement

| The >>INLINE ON or >>INLINE OFF specification is limited to the current

| compilation unit.

| Note: The INLINE directive can appear multiple times in the program.

| Inlining eligibility of procedures for PERFORM statements

| A procedure is "in the scope of" a particular INLINE directive when:

| v This INLINE directive appears before the definition of the procedure name
| and
| v There are no other intervening INLINE directives between the definition of the
| procedure name and this particular INLINE directive

| A procedure is eligible for inlining for statements of the form "PERFORM

| procedure-name-1 [THROUGH procedure-name-2]", if and only if:
| v The procedure is in the scope of an INLINE ON directive
| or
| v The INLINE compiler option is in effect and the procedure is not in the scope
| of an INLINE OFF directive

| For a section that contains paragraphs, it is possible that this section is under the
| scope of one INLINE directive while some of its paragraphs are under the scope of
| another INLINE directive.

| Example
| Following is an example of the effect of the inlining directive on a section that is
| comprised of one or more paragraphs:
| >>INLINE ON
|
| MY-SUBROUTINE SECTION.
|
| MY-PARAGRAPH-ONE.
| .
| .
|
| >>INLINE OFF
|
| MY-PARAGRAPH-TWO.
| .
| .
|
| MY-PARAGRAPH-THREE.
| .
| .
|
| EXIT.

Chapter 23. Compiler directives 589

| Notes:
| 1. Procedure MY-SUBROUTINE will be eligible for inlining in any statements that
| PERFORM it.
| 2. Procedure MY-PARAGRAPH-ONE will be eligible for inlining in any
| statements that PERFORM it.
| 3. Procedure MY-PARAGRAPH-TWO will not be eligible for inlining in any
| statements that PERFORM it.
| 4. Procedure MY-PARAGRAPH-THREE will not be eligible for inlining in any
| statements that PERFORM it.
| 5. Procedures MY-PARAGRAPH-ONE through MY-PARAGRAPH-THREE will be
| eligible for inlining in any statements that PERFORM "MY-PARAGRAPH-ONE
| THRU MY-PARAGRAPH-THREE", because MY-PARAGRAPH-ONE is eligible
| for inlining in a PERFORM statement.
|

590 Enterprise COBOL for z/OS, V6.1 Language Reference

Part 9. Appendixes

© Copyright IBM Corp. 1991, 2017 591

592 Enterprise COBOL for z/OS, V6.1 Language Reference
Appendix A. IBM extensions
IBM extensions are features, syntax rules, or behaviors defined by IBM rather than
by the COBOL standards.

The COBOL standards are listed in Appendix H, “Industry specifications,” on page

643.

Table 56 lists IBM extensions with a brief description. Standard behavior is shown
in brackets, [ ], when the standard behavior is not obvious. Extensions are
described in more detail throughout this document, but they are not further
identified as extensions.

Many IBM extensions are distinguished from standard language by their syntax.
For others, you use compiler options to choose between standard and extension
behavior. Generally, the related compiler options are noted in the detailed rules.
For information about compiler options, see Option settings for 85 COBOL Standard
conformance in the Enterprise COBOL Programming Guide.

If an item is listed as an extension, all related rules are also extensions. For
example, USAGE DISPLAY-1 for DBCS characters is listed as an extension; its
many uses in statements and clauses are also extensions, but are not listed
separately.
Table 56. IBM extension language elements
Language area Extension elements
COBOL words User-defined words written in DBCS characters

Computer-name written in DBCS characters

Class-names (for object orientation)

Method-names

User-defined words can include an underscore, but not as the first character.
National character support Support for UTF-16 with USAGE NATIONAL
(Unicode support)
Allowance of UTF-8 with USAGE DISPLAY

Usage NATIONAL for data categories national, national-edited, numeric,

numeric-edited, external decimal, and external floating-point

GROUP-USAGE clause with the NATIONAL phrase

National literals (basic and hexadecimal)

National character value for figurative constants SPACE, ZERO, QUOTE,

HIGH-VALUES, LOW-VALUES, ALL literal

Intrinsic functions for data conversion:

v DISPLAY-OF
v NATIONAL-OF

Extended case mapping with UPPER-CASE and LOWER-CASE functions

© Copyright IBM Corp. 1991, 2017 593

Table 56. IBM extension language elements (continued)
Language area Extension elements
Implicit items Special object references:
v SELF
v SUPER

Special registers:
v ADDRESS OF
v JNIENVPTR
v JSON-CODE
v LENGTH OF
v RETURN-CODE
v SHIFT-IN
v SHIFT-OUT
v SORT-CONTROL
v SORT-CORE-SIZE
v SORT-FILE-SIZE
v SORT-MESSAGE
v SORT-MODE-SIZE
v SORT-RETURN
v TALLY
v WHEN-COMPILED
v XML-CODE
v XML-EVENT
v XML-INFORMATION
v XML-NAMESPACE
v XML-NAMESPACE-PREFIX
v XML-NNAMESPACE
v XML-NNAMESPACE-PREFIX
v XML-NTEXT
v XML-TEXT
Figurative constants Selection of apostrophe (’) as the value of the figurative constant QUOTE

NULL and NULLS for pointers and object references

594 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 56. IBM extension language elements (continued)
Language area Extension elements
Literals Use of apostrophe (’) as an alternative to the quotation mark (") in opening and
closing delimiters

Mixed single-byte and double-byte characters in alphanumeric literals (mixed literals)

Hexadecimal notation for alphanumeric literals, defined by opening delimiters X" and
X’

Null-terminated alphanumeric literals, defined by opening delimiters Z" and Z’

DBCS literals, defined by opening delimiters N", N’, G", and G’. N" and N’ are defined
as DBCS when the NSYMBOL(DBCS) compiler option is in effect.

Consecutive alphanumeric literals (coding two consecutive alphanumeric literals by

ending the first literal in column 72 of a continued line and starting the next literal
with a single quotation mark in the continuation line)

National literals N", N’, NX", NX’ for storing literal content as national characters. N"
and N’ are defined as national when the NSYMBOL(NATIONAL) compiler option is
in effect.

19- to 31-digit fixed-point numeric literals. [The 85 COBOL Standard specifies a

maximum of 18 digits.]

Floating-point numeric literals

Comments Comment lines before the IDENTIFICATION DIVISION header

Comment lines and comment entries containing multibyte characters

Inline comments
End markers The following end markers:
v END CLASS
v END FACTORY
v END METHOD
v END OBJECT
Indexing and subscripting Referencing a table with an index-name defined for a different table

Specifying a positive signed integer literal following the operator + or - in relative

subscripting
IDENTIFICATION Abbreviation ID for IDENTIFICATION
DIVISION for programs
RECURSIVE clause

An optional separator period following PROGRAM-ID, AUTHOR, INSTALLATION,

DATE-WRITTEN, and SECURITY paragraph headers. [The 85 COBOL Standard
requires a period following each of these paragraph headers.]

An optional separator period following program-name in the PROGRAM-ID

paragraph. [The 85 COBOL Standard requires a period following program-name.]

An alphanumeric literal for program-name in the PROGRAM-ID paragraph;

characters $, #, and @ in the name of the outermost program, and the underscore can
be the first character; program-name up to 160 characters in length. [The 85 COBOL
Standard requires that program-name be specified as a user-defined word.]
End markers Program-name in a literal. [The 85 COBOL Standard requires that program-name be
specified as a user-defined word.]

Appendix A. IBM extensions 595

Table 56. IBM extension language elements (continued)
Language area Extension elements
Object-oriented structure In a class definition:
v CLASS-ID paragraph
v INHERITS clause
v END CLASS marker

In a method definition:
v METHOD-ID paragraph
v EXIT METHOD statement
v END METHOD marker
Configuration section Repository paragraph
SPECIAL-NAMES The optional order of clauses. [The 85 COBOL Standard requires that the clauses be
paragraph coded in the order presented in the syntax diagram.]

Optionality of a period after the last clause when no clauses are coded. [The 85
COBOL Standard requires a period, even when no clauses are coded.]

Multiple CURRENCY SIGN clauses. [The 85 COBOL Standard allows a single

CURRENCY SIGN clause.]

WITH PICTURE SYMBOL phrase in the CURRENCY SIGN clause

Multiple-character and mixed-case currency signs in the CURRENCY SIGN clause

(when the WITH PICTURE SYMBOL phrase is specified). [The 85 COBOL Standard
allows only one character, and it is both the currency sign and the currency picture
symbol. The standard currency sign must not be:
v The same character as any standard picture symbol
v A digit 0-9
v One of the special characters * + - , ; ( ) " = /
v A space ]

Use of lower-case alphabetic characters as a currency sign. [The 85 COBOL Standard

allows only uppercase characters.]

596 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 56. IBM extension language elements (continued)
Language area Extension elements
INPUT-OUTPUT SECTION, Optionality of "FILE-CONTROL." when the INPUT-OUTPUT SECTION is specified,
FILE-CONTROL paragraph no file-control-paragraph is specified, and there are no files defined in the compilation
unit. [The 85 COBOL Standard requires that "FILE-CONTROL." be coded if
"INPUT-OUTPUT SECTION." is coded.]

Optionality of the file-control-paragraph when the "FILE CONTROL." syntax is

specified and there are no files defined in the compilation unit. [The 85 COBOL
Standard requires that a file-control-paragraph be coded if "INPUT-OUTPUT
SECTION." is coded.]

PASSWORD clause

The second data-name in the FILE STATUS clause

Optionality of RECORD in the ALTERNATE RECORD KEY clause. [The 85 COBOL

Standard requires the word RECORD.]

A numeric, numeric-edited, alphanumeric-edited, alphabetic, internal floating-point,

external floating-point, national, national-edited, or DBCS primary or alternate record
key data item. [The 85 COBOL Standard requires that the key be alphanumeric.]

A primary or alternate record key defined outside the minimum record size for
indexed files containing variable-length records. [The 85 COBOL Standard requires
that the primary and alternate record keys be within the minimum record size.]

A numeric data item of usage DISPLAY or NATIONAL in the FILE STATUS clause.
[The 85 COBOL Standard requires an alphanumeric file status data item.]

The ORGANIZATION IS LINE SEQUENTIAL clause and line-sequential file control

format

National literal in the PADDING CHARACTER clause

INPUT-OUTPUT SECTION, APPLY WRITE-ONLY clause
I-O-CONTROL paragraph
Specifying only one file-name in the SAME clause in the sequential, indexed, and
sort-merge formats of the I-O-control entry. [The 85 COBOL Standard requires at least
two file-names.]

Optionality of the keyword ON in the RERUN clause. [The 85 COBOL Standard

requires that ON be coded.]

The line-sequential format I-O-control entry

The RERUN clause in the sort-merge I-O-control entry

DATA DIVISION LOCAL-STORAGE SECTION

The GLOBAL clause in the LINKAGE SECTION

Specifying level numbers that are lower than other level numbers at the same
hierarchical level in a data description entry. [The 85 COBOL Standard requires that
all elementary or group items at the same level in the hierarchy be assigned identical
level numbers.]

Data categories internal floating-point, external floating-point, DBCS, national, and

national-edited.

Data category numeric with usage NATIONAL.

Data category numeric-edited with usage NATIONAL.

Appendix A. IBM extensions 597

Table 56. IBM extension language elements (continued)
Language area Extension elements
FILE SECTION data-name in the LABEL RECORDS clause, for specifying user labels

RECORDING MODE clause

Line-sequential format file description entry

Sort/merge file description The following clauses:
entry v BLOCK CONTAINS
v LABEL RECORDS
v VALUE OF
v LINAGE
v CODE-SET
v WITH FOOTING
v LINES AT
BLOCK CONTAINS clause BLOCK CONTAINS 0 for QSAM files. [The 85 COBOL Standard requires that at least
1 CHARACTER or RECORD be specified in the BLOCK CONTAINS clause.]
VALUE OF clause The lack of VALUE clause effect on execution when specified under an SD
DATA RECORDS clause Optionality of an 01 record description entry for a specified data-name. [The 85
COBOL Standard requires that an 01 record with the same data-name be specified.]
LINAGE clause Specifying LINAGE for files opened in EXTEND mode
BLANK WHEN ZERO Alternative spellings ZEROS and ZEROES for ZERO
clause
GLOBAL clause Specifying GLOBAL in the LINKAGE SECTION
INDEXED BY phrase Nonunique unreferenced index names
OCCURS clause Omission of "integer-1 TO" for variable-length tables

Complex OCCURS DEPENDING ON. [The 85 COBOL Standard requires that an

entry containing OCCURS DEPENDING ON be followed only by subordinate entries,
and that no entry containing OCCURS DEPENDING ON be subordinate to an entry
containing OCCURS DEPENDING ON.]

Implicit qualification of a key specified without qualifiers when the key name is not
unique

Reference to a table through indexing when no INDEXED BY phrase is specified

Keys of usages COMPUTATIONAL-1, COMPUTATIONAL-2, COMPUTATIONAL-3,

COMPUTATIONAL-4, and COMPUTATIONAL-5 in the ASCENDING/DESCENDING
KEY phrase

Acceptance of nonunique index-names that are not referenced

Unbounded tables and groups

598 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 56. IBM extension language elements (continued)
Language area Extension elements
PICTURE clause A picture character-string containing 31 to 50 characters. [The 85 COBOL Standard
allows a maximum of 30 characters.]

Picture symbols G and N

Picture symbol E and the external floating-point picture format

Coding a trailing comma insertion character or trailing period insertion character

immediately followed by a separator comma or separator semicolon in a PICTURE
clause that is not the last clause of a data description entry. [The 85 COBOL Standard
requires that a PICTURE clause containing a picture ending with a comma or period
be the last clause in the entry and that it be followed immediately by a separator
period.]

Selecting a currency sign and currency symbol with the CURRENCY compiler option

Case-sensitive currency symbols

The maximum of 31 digits for numeric items of usages DISPLAY and

PACKED-DECIMAL and for numeric-edited items of USAGE DISPLAY

The effect of the TRUNC compiler option on the value of data items described with a
usage of BINARY, COMPUTATIONAL, or COMPUTATIONAL-4
REDEFINES clause Specifying REDEFINES of a redefined data item

At a subordinate level, specifying a redefining data item that has a size greater than
the size of the redefined data item
SYNCHRONIZED clause Specifying SYNCHRONIZED for a level 01 entry
USAGE clause The following phrases:
v NATIVE
v COMP-1 and COMPUTATIONAL-1
v COMP-2 and COMPUTATIONAL-2
v COMP-3 and COMPUTATIONAL-3
v COMP-4 and COMPUTATIONAL-4
v COMP-5 and COMPUTATIONAL-5
v DISPLAY-1
v OBJECT REFERENCE
v NATIONAL
v POINTER
v PROCEDURE-POINTER
v FUNCTION-POINTER

Use of the SYNCHRONIZED clause for items of usage INDEX

VALUE clause for A VALUE clause in file and LINKAGE SECTION other than in condition-name entries
condition-name entries
A VALUE clause for a condition-name entry on a group that has usages other than
DISPLAY

VALUE IS NULL and VALUE IS NULLS

VOLATILE clause A VOLATILE clause in a format 1 data description entry

Appendix A. IBM extensions 599

 Table 56. IBM extension language elements (continued)
Language area Extension elements
PROCEDURE DIVISION Omission of a section-name

Omission of a paragraph-name when a section-name is omitted

A method, factory, or object procedure division

Referencing data items in the LINKAGE SECTION without a USING phrase in the
PROCEDURE DIVISION header (when those data-names are the operand of an
ADDRESS OF phrase or ADDRESS OF special register)

The following statements:

v ENTRY
v EXIT METHOD
v GOBACK
v INVOKE
| v JSON GENERATE
v XML PARSE
v XML GENERATE
PROCEDURE DIVISION The BY VALUE phrase
header
The RETURNING phrase

Specifying a data item in the USING phrase when the data item has a REDEFINES
clause in its description

Specifying multiple instances of a given data item in the USING phrase

The formats for method, factory, and object definitions

Declarative Procedures Performing a nondeclarative procedure from a declarative procedure

Referencing a declarative procedure or nondeclarative procedure in a GO TO

statement from a declarative procedure. [The 85 COBOL Standard specifies that a
declarative procedure must not reference a nondeclarative procedure. A reference to a
declarative procedure from either another declarative procedure or a nondeclarative
procedure is allowed only with a PERFORM statement.]

Executing an active declarative

600 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 56. IBM extension language elements (continued)
Language area Extension elements
Procedures Specifying priority-number as a positive signed numeric literal. [The 85 COBOL
Standard requires an unsigned integer.]

Omitting the section-header after the declaratives or when there are no declaratives.
[The 85 COBOL Standard requires a section-header following the "DECLARATIVES."
syntax and following the "END DECLARATIVES." syntax.]

Omitting an initial paragraph-name if there are no declaratives. [The 85 COBOL

Standard requires a paragraph-name in the following circumstances:
v After the USE statement if there are statements in the declarative procedure
v Following a section header outside declarative procedures
v Before any procedural statement if there are no declaratives

and the 85 COBOL Standard requires that procedural statements be within a

paragraph.]

Specifying paragraphs that are not contained within a section, even if some
paragraphs are so contained. [The 85 COBOL Standard requires that paragraphs be
within a section except when there are no declaratives. The 85 COBOL Standard
requires that either all paragraphs be in sections or that none be.]
Conditional expressions DBCS and KANJI class conditions

Specifying data items of usage COMPUTATIONAL-3 or usage PACKED-DECIMAL in

a NUMERIC class test
Relation condition Enclosing an alphanumeric, DBCS, or national literal in parentheses

The data-pointer format, the procedure-pointer and function-pointer format, and the
object-reference format

Comparison of an index-name with an arithmetic expression

Use of parentheses within abbreviated combined relation conditions

CORRESPONDING phrase Specifying an identifier that is subordinate to a filler item
INVALID KEY phrase Omission of both the INVALID KEY phrase and an applicable EXCEPTION/ERROR
procedure. [The 85 COBOL Standard requires at least one of them.]
ACCEPT statement The environment-name operand of the FROM phrase

The DATE YYYYMMDD phrase

The DAY YYYYDDD phrase

ADD statement A composite of operands greater than 18 digits

Appendix A. IBM extensions 601

Table 56. IBM extension language elements (continued)
Language area Extension elements
CALL statement The procedure-pointer and function-pointer operands for identifying the program to
be called

The following phrases and parameters:

v ADDRESS OF
v LENGTH OF
v OMITTED
v BY VALUE
v RETURNING

Specifying a file-name as an argument

Specifying the called program-name in an alphabetic or zoned-decimal data item

Specifying an argument defined as a subordinate group item. [The 85 COBOL

Standard requires that arguments be an elementary data item or a group item defined
with level 01.]
CANCEL statement Specifying the name of the program to be canceled in an alphabetic or zoned-decimal
data item

The effect of the PGMNAME compiler option on the name of the program to be
canceled
CLOSE statement WITH NO REWIND phrase

The line-sequential format

COMPUTE statement The use of the word EQUAL in place of the equal sign (=)
DISPLAY statement The environment-name operand of the UPON phrase

Displaying signed numeric literals and noninteger numeric literals

DIVIDE statement A composite of operands greater than 18 digits
EXIT statement Specifying the EXIT statement in a sentence that has statements before or after the
EXIT statement or in a paragraph that has other sentences. [The 85 COBOL Standard
requires that the EXIT statement be specified in a sentence by itself and that the
sentence be the only sentence in the paragraph.]
EXIT PROGRAM statement Specifying EXIT PROGRAM before the last statement in a sequence of imperative
statements. [The 85 COBOL Standard requires that the EXIT PROGRAM statement be
specified as the last statement in a sequence of imperative statements.]
GO TO statement Coding the unconditional format before the last statement in a sequence of imperative
statements. [The 85 COBOL Standard requires that an unconditional GO TO be coded:
v Only in a single-statement paragraph if no procedure-name is specified
v Otherwise, as the last statement of a sentence.]
IF statement The use of END-IF with the NEXT SENTENCE phrase. [The 85 COBOL Standard
disallows use of END-IF with NEXT SENTENCE.]
INITIALIZE statement DBCS, EGCS, NATIONAL, and NATIONAL-EDITED in the REPLACING phrase

Initializing a data item that contains the DEPENDING phrase of the OCCURS clause
MERGE statement Specifying file-names in a SAME clause
MULTIPLY statement A composite of operands greater than 18 digits
OPEN statement The line-sequential format

Specifying the EXTEND phrase for files that have a LINAGE clause

602 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 56. IBM extension language elements (continued)
Language area Extension elements
PERFORM statement An empty in-line PERFORM statement

A common exit for two or more active PERFORMS

READ statement Omission of both the AT END phrase and an applicable declarative procedure

Omission of both the INVALID KEY phrase and an applicable declarative procedure

Read into an item that is neither an alphanumeric group item nor an elementary
alphanumeric item
RETURN statement Return into an item that is neither an alphanumeric group item nor an elementary
alphanumeric item
REWRITE statement Omission of both the INVALID KEY phrase and an applicable declarative procedure

Rewriting a record with a different number of character positions than the number of
character positions in the record being rewritten
SEARCH statement Specifying END SEARCH with NEXT SENTENCE

Omission of both the NEXT SENTENCE phrase and imperative statements in the
binary search format
SET statement The data-pointer format

The procedure-pointer and function-pointer format

The object reference format

SORT statement Specifying GIVING file-names in the SAME clause
START statement Omission of both the INVALID KEY phrase and an applicable exception procedure

Use of a key of a category other than alphanumeric

STOP statement Specifying a noninteger fixed-point literal or a signed numeric integer or noninteger
fixed-point literal

Coding STOP as other than the last statement in a sentence

STRING statement Reference modification of the data item specified in the INTO phrase
SUBTRACT statement A composite of operands greater than 18 digits
UNSTRING statement Reference modification of the sending field
WRITE statement INVALID KEY and NOT ON INVALID KEY phrases

The line-sequential format

For a relative file, writing a different number of character positions than the number
of character positions in the record being replaced

Specifying both the ADVANCING PAGE and END-OF-PAGE phrases in a single

WRITE statement

The effect of the ADV compiler option on the length of the record written to a file

Using WRITE ADVANCING with stacker selection for a card punch file

For a relative or indexed file, omission of both the INVALID KEY phrase and an
applicable exception procedure

Appendix A. IBM extensions 603

Table 56. IBM extension language elements (continued)
Language area Extension elements
Intrinsic functions The effect of the INTDATE compiler options on the INTEGER-OF-DATE and
INTEGER-OF-DAY functions

The following functions:

v DATE-TO-YYYYMMDD
v DAY-TO-YYYYDDD
v DISPLAY-OF
v NATIONAL-OF
v ULENGTH
v UPOS
v USUBSTR
v USUPPLEMENTARY
v UVALID
v UWIDTH
v YEAR-TO-YYYY
FACTORIAL function The effect of the ARITH(EXTEND) compiler option on the range of values permitted
in the argument
LENGTH function Specifying a pointer, the ADDRESS OF special register, or the LENGTH OF special
register as an argument to the function
NUMVAL function The effect of the ARITH(EXTEND) compiler option on the maximum number of digits
allowed in the argument
NUMVAL-C function The effect of the ARITH(EXTEND) compiler option on the maximum number of digits
allowed in the argument
Compiler-directing The following statements:
statements v BASIS
v CBL(PROCESS)
v *CONTROL and *CBL
v DELETE
v EJECT
v INSERT
v READY or RESET TRACE
v SERVICE LABEL
v SERVICE RELOAD
v SKIP1, SKIP2, and SKIP3
v TITLE
Compiler directives CALLINTERFACE directive
COPY statement The optionality of the syntax "OF library-name" for specifying a text-name qualifier

Literals for specifying text-name and library-name

SUPPRESS phrase

Nested COPY statements

Hyphen as the first or last character in the word form of REPLACING operands

The use of any character (other than a COBOL separator) in the word form of
REPLACING operands. [The 85 COBOL Standard accepts only the characters used in
formation of user-defined words.]

604 Enterprise COBOL for z/OS, V6.1 Language Reference

Appendix B. Compiler limits
Enterprise COBOL supports various compiler limits for programs and class
definitions.
Table 57. Compiler limits
Language element Compiler limit
Maximum length of user-defined words (for example, 30 bytes
data-name, file-name, class-name)
Size of program 999,999 lines
Number of literals 4,194,303(Note 1)
Total length of literals 4,194,303 bytes(Note 1)
Reserved word table entries 1536
COPY REPLACING . . . BY . . . (items per COPY No limit
statement)
Number of COPY libraries No limit
Block size of COPY library 32,760 bytes
IDENTIFICATION DIVISION
ENVIRONMENT DIVISION
Configuration section
Special-names paragraph
mnemonic-name IS 18
UPSI-n . . . (switches) 0-7
alphabet-name IS . . . No limit
Literal THRU . . . or ALSO . . . 256
Input-Output section
File-control paragraph
SELECT file-name . . . A maximum of 65,535 file names can be assigned
external names
ASSIGN system-name . . . No limit
ALTERNATE RECORD KEY data-name . . . 253
RECORD KEY length No limit(Note 3)
RESERVE integer (buffers) 255(Note 4)
I-O-control paragraph
RERUN ON system-name . . . 32,767
RERUN integer RECORDS 16,777,215
SAME RECORD AREA 255
SAME RECORD AREA FOR file-name . . . 255
SAME SORT/MERGE AREA No limit(Note 2)
MULTIPLE FILE file-name . . . No limit(Note 2)
DATA DIVISION
77 data item size 999,999,999 bytes

© Copyright IBM Corp. 1991, 2017 605

 Table 57. Compiler limits (continued)
Language element Compiler limit
01-49 data item size 999,999,999 bytes
Total 01 + 77 (data items) No limit
88 condition-names . . . No limit
| 88 level VALUE clause . . . No limit
66 RENAMES . . . No limit
PICTURE clause, number of characters in character-string 50
PICTURE clause, numeric item digit positions With ARITH(COMPAT): 18

With ARITH(EXTEND): 31
PICTURE clause, numeric-edited character positions 249
Picture symbol replication ( ) 999,999,999 bytes
Picture symbol replication (editing) 32,767
Picture symbol replication ( ), class DBCS items 499,999,999 bytes
Picture symbol replication ( ), class national items 499,999,999 bytes
Elementary item size 134,217,727 bytes
OCCURS integer 999,999,999
Total number of ODOs 4,194,303(Note 1)
Table size 999,999,999 bytes
Table element size 999,999,999 bytes
ASCENDING or DESCENDING KEY . . . (per OCCURS 12 KEYS
clause)
Total length of keys (per OCCURS clause) 256 bytes
INDEXED BY . . . (index names per OCCURS clause) 12
Total number of indexes (index names) per class or 65,535
program
Size of relative index 32,765
FILE SECTION
FD record description entry 1,048,575 bytes
FD file-name . . . 65,535
LABEL data-name . . . (if no optional clauses) 255
Label record length 80 bytes
BLOCK CONTAINS integer 2,147,483,647(Note 8)
RECORD CONTAINS integer 1,048,575(Note 5)
LINAGE clause values 99,999,999
SD file-name . . . 65,535
DATA RECORD data-name . . . No limit(Note 2)
LINKAGE SECTION
Total size No limit
LOCAL-STORAGE SECTION
Total size 2,147,483,646 bytes
WORKING-STORAGE SECTION

606 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 57. Compiler limits (continued)
Language element Compiler limit
Total size of items without the external attribute 2,147,483,646 bytes
Total size of items with the external attribute 2,147,483,646 bytes
PROCEDURE DIVISION
Procedure and constant area 4,194,303 bytes(Note 1)
PROCEDURE DIVISION USING identifier . . . 32,767
Procedure-names 1,048,575(Note 1)
Subscripted data-names per statement 32,767
Statements per line (TEST) 7
ACCEPT statement, record length on input device 32,760
ADD identifier . . . No limit
ALTER procedure-name-1 TO procedure-name-2 . . . 4,194,303(Note 1)
CALL . . . BY CONTENT identifier 2,147,483,647 bytes
CALL identifier or literal USING identifier or literal . . . 16,380
CALL literal . . . 4,194,303(Note 1)
Active programs in a run unit 32,767
Number of names called (DYN option) No limit
CANCEL identifier or literal . . . No limit
CLOSE file-name . . . No limit
COMPUTE identifier . . . No limit
DISPLAY identifier or literal . . . No limit
DIVIDE identifier . . . No limit
ENTRY USING identifier or literal . . . No limit
EVALUATE . . . subjects 64
EVALUATE . . . WHEN clauses 256
GO procedure-name . . . DEPENDING 255
INSPECT TALLYING and REPLACING clauses No limit
MERGE file-name ASC or DES KEY . . . No limit
Total merge key length 4,092 bytes(Note 6)
MERGE USING file-name . . . 16(Note 7)
MOVE identifier or literal TO identifier . . . No limit
MULTIPLY identifier . . . No limit
OPEN file-name . . . No limit
PERFORM 4,194,303
PERFORM . . . TIMES identifier or literal 999,999,999
SEARCH ALL . . . maximum key length No limit
SEARCH ALL . . . total length of keys No limit
SEARCH . . . WHEN . . . No limit
SET index or identifier . . . TO No limit
SET index . . . UP/DOWN No limit
SORT file-name ASC or DES KEY No limit

Appendix B. Compiler limits 607

Table 57. Compiler limits (continued)
Language element Compiler limit
Total sort key length 4,092 bytes(Note 6)
SORT USING file-name . . . 16(Note 7)
STRING identifier . . . No limit
STRING DELIMITED identifier or literal . . . No limit
UNSTRING DELIMITED identifier or literal . . . No limit
UNSTRING INTO identifier or literal . . . No limit
USE . . . ON file-name . . . No limit
XML PARSE statement, maximum size of identifier 999,999,999 bytes
Notes:
1. Items included in 4,194,303 byte limit for procedure plus constant area.
2. Syntax checked, but has no effect on the execution of the program; there is no limit.
3. No compiler limit, but VSAM limits it to 255 bytes.
4. QSAM.
5. Compiler limit shown, but QSAM limits it to 32,760 bytes.
6. For QSAM and VSAM, the limit is 4088 bytes if EQUALS is coded on the OPTION control statement.
7. SORT limit for QSAM and VSAM.
8. Requires large block interface (LBI) support provided by OS/390 DFSMS Version 2 Release 10.0 or later. On
OS/390 systems with earlier releases of DFSMS, the limit is 32,760 bytes. For more information about using large
block sizes, see Setting block sizes in the Enterprise COBOL Programming Guide.

608 Enterprise COBOL for z/OS, V6.1 Language Reference

Appendix C. EBCDIC and ASCII collating sequences
A collating sequence defines the order of characters within a coded character set or
COBOL alphabet for purposes of sorting, merging, and comparing data and for
processing files with indexed organization.

The ascending collating sequences for both the single-byte EBCDIC (Extended
Binary Coded Decimal Interchange Code) and single-byte ASCII (American
National Standard Code for Information Interchange) character sets are shown in
this appendix. The collating sequence is defined by the ordinal number of
characters in the character set, relative to 1.

The symbols and associated meanings shown for the EBCDIC collating sequence
are those defined in the EBCDIC code page defined with CCSID 1140. Symbols and
meanings can vary for other EBCDIC code pages, but the collating sequence is
unchanged.

EBCDIC collating sequence

The EBCDIC collating sequence is the order in which characters are defined in
EBCDIC.

The following table presents the collating sequence for single-byte EBCDIC code
page 1140.

Ellipsis (...) indicates omission of a range of ordinal numbers between predecessor

and successor ordinal numbers.
Table 58. EBCDIC collating sequence
Ordinal Decimal Hex
number Symbol Meaning representation representation
...
65 Space 64 40
...
75 ¢ Cent sign 74 4A
76 . Period, decimal point 75 4B
77 < Less than sign 76 4C
78 ( Left parenthesis 77 4D
79 + Plus sign 78 4E
80 | Vertical bar, logical OR 79 4F
81 & Ampersand 80 50
...
91 ! Exclamation point 90 5A
92 $ Dollar sign 91 5B
93 * Asterisk 92 5C
94 ) Right parenthesis 93 5D
95 ; Semicolon 94 5E

© Copyright IBM Corp. 1991, 2017 609

 Table 58. EBCDIC collating sequence (continued)
Ordinal Decimal Hex
number Symbol Meaning representation representation
96 ¬ Logical NOT 95 5F
97 - Minus, hyphen 96 60
98 / Slash 97 61
...
108 , Comma 107 6B
109 % Percent sign 108 6C
110 _ Underscore 109 6D
111 > Greater than sign 110 6E
112 ? Question mark 111 6F
...
122 ` Grave accent 121 79
123 : Colon 122 7A
124 # Number sign, pound sign 123 7B
125 @ At sign 124 7C
126 ’ Apostrophe, prime sign 125 7D
127 = Equal sign 126 7E
128 " Quotation marks 127 7F
...
130 a 129 81
131 b 130 82
132 c 131 83
133 d 132 84
134 e 133 85
135 f 134 86
136 g 135 87
137 h 136 88
138 i 137 89
...
146 j 145 91
147 k 146 92
148 l 147 93
149 m 148 94
150 n 149 95
151 o 150 96
152 p 151 97
153 q 152 98
154 r 153 99
...
160 € Euro currency sign 159 9F

610 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 58. EBCDIC collating sequence (continued)
Ordinal Decimal Hex
number Symbol Meaning representation representation
...
162 ~ Tilde 161 A1
163 s 162 A2
164 t 163 A3
165 u 164 A4
166 v 165 A5
167 w 166 A6
168 x 167 A7
169 y 168 A8
170 z 169 A9
...
177 ^ Caret 176 B0
...
188 [ Opening square bracket 187 BA
189 ] Closing square bracket 188 BB
...
193 { Opening brace 192 C0
194 A 193 C1
195 B 194 C2
196 C 195 C3
197 D 196 C4
198 E 197 C5
199 F 198 C6
200 G 199 C7
201 H 200 C8
202 I 201 C9
...
209 } Closing brace 208 D0
210 J 209 D1
211 K 210 D2
212 L 211 D3
213 M 212 D4
214 N 213 D5
215 O 214 D6
216 P 215 D7
217 Q 216 D8
218 R 217 D9
...
225 \ Backslash 224 E0

Appendix C. EBCDIC and ASCII collating sequences 611

 Table 58. EBCDIC collating sequence (continued)
Ordinal Decimal Hex
number Symbol Meaning representation representation
...
227 S 226 E2
228 T 227 E3
229 U 228 E4
230 V 229 E5
231 W 230 E6
232 X 231 E7
233 Y 232 E8
234 Z 233 E9
...
241 0 240 F0
242 1 241 F1
243 2 242 F2
244 3 243 F3
245 4 244 F4
246 5 245 F5
247 6 246 F6
248 7 247 F7
249 8 248 F8
250 9 249 F9
...

US English ASCII code page

The ASCII collating sequence is the order in which characters are defined in ASCII.

The following table presents the collating sequence for the US English ASCII code
page. The collating sequence is the order in which characters are defined in ANSI
INCITS 4, the 7-Bit American National Standard Code for Information Interchange
(7-Bit ASCII), and in the International Reference Version of ISO/IEC 646, 7-Bit Coded
Character Set for Information Interchange.

Ellipsis (. . .) indicates omission of a range of ordinal numbers between predecessor

and successor ordinal numbers.
Table 59. ASCII collating sequence
Ordinal Decimal Hex
number Symbol Meaning representation representation
1 Null 0 0
...
33 Space 32 20
34 ! Exclamation point 33 21
35 " Quotation mark 34 22

612 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 59. ASCII collating sequence (continued)
Ordinal Decimal Hex
number Symbol Meaning representation representation
36 # Number sign 35 23
37 $ Dollar sign 36 24
38 % Percent sign 37 25
39 & Ampersand 38 26
40 ’ Apostrophe, prime sign 39 27
41 ( Opening parenthesis 40 28
42 ) Closing parenthesis 41 29
43 * Asterisk 42 2A
44 + Plus sign 43 2B
45 , Comma 44 2C
46 - Hyphen, minus 45 2D
47 . Period, decimal point 46 2E
48 / Slash, solidus 47 2F
49 0 48 30
50 1 49 31
51 2 50 32
52 3 51 33
53 4 52 34
54 5 53 35
55 6 54 36
56 7 55 37
57 8 56 38
58 9 57 39
59 : Colon 58 3A
60 ; Semicolon 59 3B
61 < Less than sign 60 3C
62 = Equal sign 61 3D
63 > Greater than sign 62 3E
64 ? Question mark 63 3F
65 @ Commercial At sign 64 40
66 A 65 41
67 B 66 42
68 C 67 43
69 D 68 44
70 E 69 45
71 F 70 46
72 G 71 47
73 H 72 48
74 I 73 49

Appendix C. EBCDIC and ASCII collating sequences 613

 Table 59. ASCII collating sequence (continued)
Ordinal Decimal Hex
number Symbol Meaning representation representation
75 J 74 4A
76 K 75 4B
77 L 76 4C
78 M 77 4D
79 N 78 4E
80 O 79 4F
81 P 80 50
82 Q 81 51
83 R 82 52
84 S 83 53
85 T 84 54
86 U 85 55
87 V 86 56
88 W 87 57
89 X 88 58
90 Y 89 59
91 Z 90 5A
92 [ Opening bracket 91 5B
93 \ Backslash, reverse solidus 92 5C
94 ] Closing bracket 93 5D
95 ^ Caret 94 5E
96 _ Underscore 95 5F
97 ` Grave accent 96 60
98 a 97 61
99 b 98 62
100 c 99 63
101 d 100 64
102 e 101 65
103 f 102 66
104 g 103 67
105 h 104 68
106 i 105 69
107 j 106 6A
108 k 107 6B
109 l 108 6C
110 m 109 6D
111 n 110 6E
112 o 111 6F
113 p 112 70

614 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 59. ASCII collating sequence (continued)
Ordinal Decimal Hex
number Symbol Meaning representation representation
114 q 113 71
115 r 114 72
116 s 115 73
117 t 116 74
118 u 117 75
119 v 118 76
120 w 119 77
121 x 120 78
122 y 121 79
123 z 122 7A
124 { Opening brace 123 7B
125 | Vertical bar 124 7C
126 } Closing brace 125 7D
127 ~ Tilde 126 7E

Appendix C. EBCDIC and ASCII collating sequences 615

616 Enterprise COBOL for z/OS, V6.1 Language Reference
Appendix D. Source language debugging
Several COBOL language elements implement the debugging feature.

COBOL language elements are:

v Debugging lines
v Debugging sections
v DEBUG-ITEM special register
v Compile-time switch (WITH DEBUGGING MODE clause)
v Object-time switch

Debugging lines
A debugging line is a statement that is compiled only when the compile-time switch
is activated. Debugging lines allow you, for example, to check the value of a data
item at certain points in a procedure.

To specify a debugging line in your program, code a D in column 7 (the indicator

area). You can include successive debugging lines, but each must have a D in
column 7. You cannot break character-strings across two lines.

All your debugging lines must be written so that the program is syntactically
correct, whether the debugging lines are compiled or treated as comments.

You can code debugging lines anywhere in your program after the
OBJECT-COMPUTER paragraph.

A debugging line that contains only spaces in Area A and in Area B is treated as a
blank line.

Debugging sections
Debugging sections are permitted only in the outermost program; they are not
valid in nested programs. Debugging sections are never triggered by procedures
contained in nested programs.

Debugging sections are declarative procedures. Declarative procedures are

described under “USE statement” on page 582. A debugging section can be called,
for example, by a PERFORM statement that causes repeated execution of a
procedure. Any associated procedure-name debugging declarative section is executed
once for each repetition.

A debugging section executes only if both the compile-time switch and the
object-time switch are activated.

The debug feature recognizes each separate occurrence of an imperative statement

within an imperative statement as the beginning of a separate statement.

You cannot refer to a procedure defined within a debugging section from a

statement outside of the debugging section.

© Copyright IBM Corp. 1991, 2017 617

 References to the DEBUG-ITEM special register can be made only from within a
debugging declarative procedure.

DEBUG-ITEM special register

The DEBUG-ITEM special register provides information for a debugging
declarative procedure about the conditions that cause debugging section execution.

For details of the DEBUG-ITEM special register, see “DEBUG-ITEM” on page 17.

Activate compile-time switch

The compile-time switch activates the debugging lines and sections. To place the
compile-time switch in effect, specify WITH DEBUGGING MODE in the SOURCE
COMPUTER paragraph of the configuration section.

Format

►► SOURCE-COMPUTER. ►◄
computer-name .
DEBUGGING MODE
WITH

WITH DEBUGGING MODE

When WITH DEBUGGING MODE is specified, all debugging sections and
debugging lines are compiled.
When WITH DEBUGGING MODE is omitted, all debugging sections and
debugging lines are treated as comments.

Usage note: If you include a COPY statement as a debugging line, the letter "D"
must appear on the first line of the COPY statement. The compiler treats the
copied text as the debugging line or lines. The COPY statement is executed,
regardless of whether WITH DEBUGGING MODE is specified or not.

Activate object-time switch

The object-time switch is set when the runtime option DEBUG or NODEBUG is
specified. (NODEBUG is the default supplied by IBM.)

For details on the format, see the Language Environment Programming Guide.

The USE FOR DEBUGGING declarative procedures are activated when DEBUG is
in effect and inhibited when NODEBUG is in effect.

The debugging lines (lines with "D" or "d" in column 7) are not affected by the
DEBUG or NODEBUG option; they are always active if they have been compiled.

When WITH DEBUGGING MODE is not specified in the SOURCE-COMPUTER

paragraph, the object-time switch has no effect on execution of the object program.

618 Enterprise COBOL for z/OS, V6.1 Language Reference

You do not have to recompile the source unit to activate or deactivate the
object-time switch.

Appendix D. Source language debugging 619

620 Enterprise COBOL for z/OS, V6.1 Language Reference
Appendix E. Reserved words
A reserved word is a character-string with a predefined meaning in a COBOL source
unit.

The following table identifies words that are reserved in Enterprise COBOL and
words that you should avoid because they might be reserved in a future release of
Enterprise COBOL.
v Words marked X under Reserved are reserved for function implemented in
Enterprise COBOL. If used as user-defined names, these words are flagged with
an S-level message.
v Words marked X under Standard only are 85 COBOL Standard reserved words
for function not implemented in Enterprise COBOL. (Some of the function is
implemented in the Report Writer Precompiler.) Use of these words as
user-defined names is flagged with an S-level message.
v Words marked X under Potential reserved words are words that might be reserved
in a future release of Enterprise COBOL. IBM recommends that you not use
these words as user-defined names. Use of these words as user-defined names is
flagged with an I-level message.
This column includes words reserved in the 2002 COBOL Standard.

The default reserved word table is shown below. You can select a different reserved
word table by using the WORD compiler option. For details, see WORD in the
Enterprise COBOL Programming Guide.
Table 60. Reserved words
Potential
Word Reserved Standard only reserved words
+ Arithmetic operator - unary plus or X
addition
- Arithmetic operator - unary minus or X
subtraction
* Arithmetic operator - multiplication X
/ Arithmetic operator - division X
** Arithmetic operator - exponentiation X
> Relational operator - greater than X
< Relational operator - less than X
= Relational operator - equal and X
assignment operator in COMPUTE
== Pseudo-text delimiter in COPY and X
REPLACE statements
>= Relational operator - greater than or X
equal
<= Relational operator - less than or X
equal
<> Relational operator - not equal X
*> Comment indicator X

© Copyright IBM Corp. 1991, 2017 621

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
>> Compiler directive indicator X
ACCEPT X
ACCESS X
ACTIVE-CLASS X
ADD X
ADDRESS X
ADVANCING X
AFTER X
ALIGNED X
ALL X
| ALLOCATE X
ALPHABET X
ALPHABETIC X
ALPHABETIC-LOWER X
ALPHABETIC-UPPER X
ALPHANUMERIC X
ALPHANUMERIC-EDITED X
ALSO X
ALTER X
ALTERNATE X
AND X
ANY X
ANYCASE X
APPLY X
ARE X
AREA X
AREAS X
ASCENDING X
ASSIGN X
AT X
AUTHOR X
B-AND X
B-NOT X
B-OR X
B-XOR X
BASED X
BASIS X
BEFORE X
BEGINNING X

622 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
BINARY X
BINARY-CHAR X
BINARY-DOUBLE X
BINARY-LONG X
BINARY-SHORT X
BIT X
BLANK X
BLOCK X
BOOLEAN X
BOTTOM X
BY X
CALL X
CANCEL X
CBL X
CD X
CF X
CH X
CHARACTER X
CHARACTERS X
CLASS X
CLASS-ID X
CLOCK-UNITS X
CLOSE X
COBOL X
CODE X
CODE-SET X
COL X
COLLATING X
COLS X
COLUMN X
COLUMNS X
COM-REG X
COMMA X
COMMON X
COMMUNICATION X
COMP X
COMP-1 X
COMP-2 X
COMP-3 X

Appendix E. Reserved words 623

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
COMP-4 X
COMP-5 X
COMPUTATIONAL X
COMPUTATIONAL-1 X
COMPUTATIONAL-2 X
COMPUTATIONAL-3 X
COMPUTATIONAL-4 X
COMPUTATIONAL-5 X
COMPUTE X
CONDITION X
CONFIGURATION X
CONSTANT X
CONTAINS X
CONTENT X
CONTINUE X
CONTROL X
CONTROLS X
CONVERTING X
COPY X
CORR X
CORRESPONDING X
COUNT X
CRT X
CURRENCY X
CURSOR X
DATA X
DATA-POINTER X
DATE X
DATE-COMPILED X
DATE-WRITTEN X
DAY X
DAY-OF-WEEK X
DBCS X
DE X
DEBUG-CONTENTS X
DEBUG-ITEM X
DEBUG-LINE X
DEBUG-NAME X
DEBUG-SUB-1 X

624 Enterprise COBOL for z/OS, V6.1 Language Reference

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
DEBUG-SUB-2 X
DEBUG-SUB-3 X
DEBUGGING X
DECIMAL-POINT X
DECLARATIVES X
| DEFAULT X
DELETE X
DELIMITED X
DELIMITER X
DEPENDING X
DESCENDING X
DESTINATION X
DETAIL X
DISABLE X
DISPLAY X
DISPLAY-1 X
DIVIDE X
DIVISION X
DOWN X
DUPLICATES X
DYNAMIC X
EC X
EGCS X
EGI X
EJECT X
ELSE X
EMI X
ENABLE X
END X
END-ACCEPT X
END-ADD X
END-CALL X
END-COMPUTE X
END-DELETE X
END-DISPLAY X
END-DIVIDE X
END-EVALUATE X
END-EXEC X
END-IF X

Appendix E. Reserved words 625

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
END-INVOKE X
| END-JSON X
END-MULTIPLY X
END-OF-PAGE X
END-PERFORM X
END-READ X
END-RECEIVE X
END-RETURN X
END-REWRITE X
END-SEARCH X
END-START X
END-STRING X
END-SUBTRACT X
END-UNSTRING X
END-WRITE X
END-XML X
ENDING X
ENTER X
ENTRY X
ENVIRONMENT X
EO X
EOP X
EQUAL X
ERROR X
ESI X
EVALUATE X
EVERY X
EXCEPTION X
EXCEPTION-OBJECT X
EXEC X
EXECUTE X
EXIT X
EXTEND X
EXTERNAL X
FACTORY X
FALSE X
FD X
FILE X
FILE-CONTROL X

626 Enterprise COBOL for z/OS, V6.1 Language Reference

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
FILLER X
FINAL X
FIRST X
FLOAT-EXTENDED X
FLOAT-LONG X
FLOAT-SHORT X
FOOTING X
FOR X
FORMAT X
| FREE X
FROM X
FUNCTION X
FUNCTION-ID X
FUNCTION-POINTER X
GENERATE X
GET X
GIVING X
GLOBAL X
GO X
GOBACK X
GREATER X
GROUP X
GROUP-USAGE X
HEADING X
HIGH-VALUE X
HIGH-VALUES X
I-O X
I-O-CONTROL X
ID X
IDENTIFICATION X
IF X
IN X
INDEX X
INDEXED X
INDICATE X
INHERITS X
INITIAL X
INITIALIZE X
INITIATE X

Appendix E. Reserved words 627

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
INPUT X
INPUT-OUTPUT X
INSERT X
INSPECT X
INSTALLATION X
INTERFACE X
INTERFACE-ID X
INTO X
INVALID X
INVOKE X
IS X
JNIENVPTR X
| JSON X
| JSON-CODE X
JUST X
JUSTIFIED X
KANJI X
KEY X
LABEL X
LAST X
LEADING X
LEFT X
LENGTH X
LESS X
LIMIT X
LIMITS X
LINAGE X
LINAGE-COUNTER X
LINE X
LINE-COUNTER X
LINES X
LINKAGE X
LOCAL-STORAGE X
LOCALE X
LOCK X
LOW-VALUE X
LOW-VALUES X
MEMORY X
MERGE X

628 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
MESSAGE X
METHOD X
METHOD-ID X
MINUS X
MODE X
MODULES X
MORE-LABELS X
MOVE X
MULTIPLE X
MULTIPLY X
NATIONAL X
NATIONAL-EDITED X
NATIVE X
NEGATIVE X
NESTED X
NEXT X
NO X
NOT X
NULL X
NULLS X
NUMBER X
NUMERIC X
NUMERIC-EDITED X
OBJECT X
OBJECT-COMPUTER X
OBJECT-REFERENCE X
OCCURS X
OF X
OFF X
OMITTED X
ON X
OPEN X
OPTIONAL X
OPTIONS X
OR X
ORDER X
ORGANIZATION X
OTHER X
OUTPUT X

Appendix E. Reserved words 629

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
OVERFLOW X
OVERRIDE X
PACKED-DECIMAL X
PADDING X
PAGE X
PAGE-COUNTER X
PASSWORD X
PERFORM X
PF X
PH X
PIC X
PICTURE X
PLUS X
POINTER X
POSITION X
POSITIVE X
PRESENT X
PRINTING X
PROCEDURE X
PROCEDURE-POINTER X
PROCEDURES X
PROCEED X
PROCESSING X
PROGRAM X
PROGRAM-ID X
PROGRAM-POINTER X
PROPERTY X
PROTOTYPE X
PURGE X
QUEUE X
QUOTE X
QUOTES X
RAISE X
RAISING X
RANDOM X
RD X
READ X
READY X
RECEIVE X

630 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
RECORD X
RECORDING X
RECORDS X
RECURSIVE X
REDEFINES X
REEL X
REFERENCE X
REFERENCES X
RELATIVE X
RELEASE X
RELOAD X
REMAINDER X
REMOVAL X
RENAMES X
REPLACE X
REPLACING X
REPORT X
REPORTING X
REPORTS X
REPOSITORY X
RERUN X
RESERVE X
RESET X
RESUME X
RETRY X
RETURN X
RETURN-CODE X
RETURNING X
REVERSED X
REWIND X
REWRITE X
RF X
RH X
RIGHT X
ROUNDED X
RUN X
SAME X
SCREEN X
SD X

Appendix E. Reserved words 631

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
SEARCH X
SECTION X
SECURITY X
SEGMENT X
SEGMENT-LIMIT X
SELECT X
SELF X
SEND X
SENTENCE X
SEPARATE X
SEQUENCE X
SEQUENTIAL X
SERVICE X
SET X
SHARING X
SHIFT-IN X
SHIFT-OUT X
SIGN X
SIZE X
SKIP1 X
SKIP2 X
SKIP3 X
SORT X
SORT-CONTROL X
SORT-CORE-SIZE X
SORT-FILE-SIZE X
SORT-MERGE X
SORT-MESSAGE X
SORT-MODE-SIZE X
SORT-RETURN X
SOURCE X
SOURCE-COMPUTER X
SOURCES X
SPACE X
SPACES X
SPECIAL-NAMES X
SQL X
SQLIMS X
STANDARD X

632 Enterprise COBOL for z/OS, V6.1 Language Reference

Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
STANDARD-1 X
STANDARD-2 X
START X
STATUS X
STOP X
STRING X
SUB-QUEUE-1 X
SUB-QUEUE-2 X
SUB-QUEUE-3 X
SUBTRACT X
SUM X
SUPER X
SUPPRESS X
SYMBOLIC X
SYNC X
SYNCHRONIZED X
SYSTEM-DEFAULT X
TABLE X
TALLY X
TALLYING X
TAPE X
TERMINAL X
TERMINATE X
TEST X
TEXT X
THAN X
THEN X
THROUGH X
THRU X
TIME X
TIMES X
TITLE X
TO X
TOP X
TRACE X
TRAILING X
TRUE X
TYPE X
TYPEDEF X

Appendix E. Reserved words 633

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
UNIT X
UNIVERSAL X
UNLOCK X
UNSTRING X
UNTIL X
UP X
UPON X
USAGE X
USE X
USER-DEFAULT X
USING X
VAL-STATUS X
VALID X
VALIDATE X
VALIDATE-STATUS X
VALUE X
VALUES X
VARYING X
VOLATILE X
WHEN X
WHEN-COMPILED X
WITH X
WORDS X
WORKING-STORAGE X
WRITE X
WRITE-ONLY X
XML X
XML-CODE X
XML-EVENT X
XML-INFORMATION X
XML-NAMESPACE X
XML-NAMESPACE-PREFIX X
XML-NNAMESPACE X
XML-NNAMESPACE-PREFIX X
XML-NTEXT X
XML-SCHEMA X
XML-TEXT X
ZERO X
ZEROES X

634 Enterprise COBOL for z/OS, V6.1 Language Reference

 Table 60. Reserved words (continued)
Potential
Word Reserved Standard only reserved words
ZEROS X

| RELATED REFERENCES
| Appendix F, “Context-sensitive words,” on page 637

Appendix E. Reserved words 635

636 Enterprise COBOL for z/OS, V6.1 Language Reference
|

| Appendix F. Context-sensitive words

| A context-sensitive word is a COBOL word that is reserved only in the general
| formats in which it is specified. If a context-sensitive word is used where the
| context-sensitive word is permitted in the general format, the word is treated as a
| keyword; otherwise it is treated as a user-defined word.
| Table 61. Context-sensitive words
| Context-sensitive word Language construct or context
| CYCLE EXIT statement
| INITIALIZED ALLOCATE statement
| PARAGRAPH EXIT statement
| RECURSIVE PROGRAM-ID paragraph
| YYYYDDD ACCEPT statement
| YYYYMMDD ACCEPT statement
|

| RELATED REFERENCES
| “User-defined words” on page 10
| Appendix E, “Reserved words,” on page 621

© Copyright IBM Corp. 1991, 2017 637

638 Enterprise COBOL for z/OS, V6.1 Language Reference
Appendix G. ASCII considerations
The compiler supports the American National Standard Code for Information
Interchange (ASCII) for magnetic tape files. Thus, the programmer can create and
process tape files recorded in accordance with several standards.

The standards are:

v American National Standard Code for Information Interchange, X3.4-1977
v American National Standard Magnetic Tape Labels for Information Interchange,
X3.27-1978
v American National Standard Recorded Magnetic Tape for Information
Interchange (800 CPI, NRZI), X3.22-1967

Single-byte ASCII-encoded tape files, when read into the system, are automatically
translated in the buffers into single-byte EBCDIC. Internal manipulation of data is
performed exactly as if the ASCII files were single-byte EBCDIC-encoded files. For
an output file, the system translates the EBCDIC characters into single-byte ASCII
in the buffers before writing the file on tape. Therefore, there are special
considerations concerning ASCII-encoded files when they are processed in COBOL.

This appendix also applies (with appropriate modifications) to the International

Reference Version of the ISO 7-bit code defined in International Standard 646, 7-Bit
Coded Character Set for Information Processing Interchange (ISCII). The ISCII code set
differs from ASCII only in the graphic representation of two code points:
v Ordinal number 37, which is a dollar sign in ASCII, but a lozenge in ISCII
v Ordinal number 127, which is a tilde (~) in ASCII, but an overline (or optionally
a tilde) in ISCII.

The following paragraphs discuss the special considerations concerning

ASCII-encoded (or ISCII-encoded) files. The information given for STANDARD-1
also applies to STANDARD-2 except where otherwise specified.

ENVIRONMENT DIVISION
In the ENVIRONMENT DIVISION, the OBJECT-COMPUTER, SPECIAL-NAMES,
and FILE-CONTROL paragraphs are affected by the use of ASCII-encoded files.

OBJECT-COMPUTER and SPECIAL-NAMES paragraphs

When at least one file in the program is an ASCII-encoded file, the alphabet-name
clause of the SPECIAL-NAMES paragraph must be specified; the alphabet-name
must be associated with STANDARD-1 or STANDARD-2 (for ASCII or ISCII
collating sequence or CODE SET, respectively).

When alphanumeric comparisons within the object program are to use the ASCII
collating sequence, the PROGRAM COLLATING SEQUENCE clause of the
OBJECT-COMPUTER paragraph must be specified; the alphabet-name used must
also be specified as an alphabet-name in the SPECIAL-NAMES paragraph, and
associated with STANDARD-1. For example:
Object-computer. IBM-system
Program collating sequence is ASCII-sequence.
Special-names. Alphabet ASCII-sequence is standard-1.

© Copyright IBM Corp. 1991, 2017 639

 When both clauses are specified, the ASCII collating sequence is used in this
program to determine the truth value of the following alphanumeric comparisons:
v Those explicitly specified in relation conditions
v Those explicitly specified in condition-name conditions
v Any alphanumeric sort or merge keys (unless the COLLATING SEQUENCE
phrase is specified in the MERGE or SORT statement).

When the PROGRAM COLLATING SEQUENCE clause is omitted, the EBCDIC

collating sequence is used for such comparisons.

The PROGRAM COLLATING SEQUENCE clause, in conjunction with the

alphabet-name clause, can be used to specify EBCDIC alphanumeric comparisons
for an ASCII-encoded tape file or ASCII alphanumeric comparisons for an
EBCDIC-encoded tape file.

The literal option of the alphabet-name clause can be used to process internal data
in a collating sequence other than NATIVE or STANDARD-1.

FILE-CONTROL paragraph
For ASCII files, the ASSIGN clause assignment-name has the following format:

Format: assignment-name for QSAM files

►► name ►◄
label- S-

The file must be a QSAM file assigned to a magnetic tape device.

label- Documents the device and device class to which a file is assigned. If
specified, it must end with a hyphen.
S- The organization field. Optional for QSAM files, which always have
sequential organization.
name A required one-character to eight-character field that specifies the external
name for this file.

I-O-CONTROL paragraph
The assignment-name in a RERUN clause must not specify an ASCII-encoded file.

ASCII-encoded files that contain checkpoint records cannot be processed.

DATA DIVISION
In the DATA DIVISION, there are special considerations for the FD entry and for
data description entries.

For each logical file defined in the ENVIRONMENT DIVISION, there must be a
corresponding FD entry and level-01 record description entry in the FILE
SECTION of the DATA DIVISION.

640 Enterprise COBOL for z/OS, V6.1 Language Reference

 FD Entry: CODE-SET clause
The FD Entry for an ASCII-encoded file must contain a CODE-SET clause; the
alphabet-name must be associated with STANDARD-1 (for the ASCII code set) in
the SPECIAL-NAMES paragraph.

For example:
Special-names. Alphabet ASCII-sequence is standard-1.
...
FD ASCII-file label records standard
Recording mode is f
Code-set is ASCII-sequence.

Data description entries

For ASCII files, the data description considerations listed in the topic apply.
v PICTURE clause specifications are valid for the following categories of data:
– Alphabetic
– Alphanumeric
– Alphanumeric-edited
– Numeric
– Numeric-edited
v For signed numeric items, the SIGN clause with the SEPARATE CHARACTER
phrase must be specified.
v For the USAGE clause, only the DISPLAY phrase is valid.

PROCEDURE DIVISION
An ASCII-collated sort or merge operation can be specified in two ways as
described in the topic.
v Through the PROGRAM COLLATING SEQUENCE clause in the
OBJECT-COMPUTER paragraph. In this case, the ASCII collating sequence is
used for alphanumeric comparisons explicitly specified in relation conditions
and condition-name conditions.
v Through the COLLATING SEQUENCE phrase of the SORT or MERGE
statement. In this case, only this sort or merge operation uses the ASCII collating
sequence.

In either case, alphabet-name must be associated with STANDARD-1 (for ASCII

collating sequence) in the SPECIAL-NAMES paragraph.

For this sort or merge operation, the COLLATING SEQUENCE phrase of the SORT
or MERGE statement takes precedence over the PROGRAM COLLATING
SEQUENCE clause in the OBJECT-COMPUTER paragraph.

If both the PROGRAM COLLATING SEQUENCE clause and the COLLATING

SEQUENCE phrase are omitted (or if the one in effect specifies an EBCDIC
collating sequence), the sort or merge is performed using the EBCDIC collating
sequence.

Appendix G. ASCII considerations 641

642 Enterprise COBOL for z/OS, V6.1 Language Reference
Appendix H. Industry specifications
Enterprise COBOL supports various industry standards.
v ISO COBOL standards
– ISO 1989:1985, Programming languages - COBOL
ISO 1989:1985 is identical to ANSI INCITS 23-1985 (R2001), Programming
Languages - COBOL
– ISO/IEC 1989/AMD1:1992, Programming languages - COBOL: Intrinsic function
module
ISO/IEC 1989/AMD1:1992 is identical to ANSI INCITS 23a-1989 (R2001),
Programming Languages - Intrinsic Function Module for COBOL
– ISO/IEC 1989/AMD2:1994, Programming languages - Correction and clarification
amendment for COBOL
ISO/IEC 1989/AMD2:1994 is identical to ANSI INCITS 23b-1993 (R2001),
Programming Language - Correction Amendment for COBOL
All required modules are supported at the highest level defined by the
standard.
The following optional modules of the standard are supported:
- Intrinsic Functions (1 ITR 0,1)
- Debug (1 DEB 0,2)
- Segmentation (2 SEG 0,2)
The Report Writer optional module of the standard is supported with the
optional IBM COBOL Report Writer Precompiler and Libraries (5798-DYR).
The following optional modules of the standard are not supported:
- Communications
- Debug (2 DEB 0,2)
– ISO/IEC 1989:2002, Information technology - Programming languages - COBOL
(partial support)
ISO/IEC 1989:2002 is identical to ANSI INCITS 1989-2002 (R2013), Information
technology - Programming languages COBOL
For a list of 2002 COBOL Standard features that are implemented since
Enterprise COBOL Version 3, see Appendix I, “2002 COBOL Standard features
implemented in Enterprise COBOL Version 3 or later versions,” on page 645.
v ANSI COBOL standards
– ANSI INCITS 23-1985 (R2001), Programming Languages - COBOL
– ANSI INCITS 23a-1989 (R2001), Programming Languages - Intrinsic Function
Module for COBOL
– ANSI INCITS 23b-1993 (R2001), Programming Language - Correction Amendment
for COBOL
All required modules are supported at the highest level defined by the
standard.
The following optional modules of the standard are supported:
- Intrinsic Functions (1 ITR 0,1)
- Debug (1 DEB 0,2)
- Segmentation (2 SEG 0,2)
The following optional modules of the standard are not supported:
© Copyright IBM Corp. 1991, 2017 643
 - Communications
- Debug (2 DEB 0,2)
– ANSI INCITS 1989-2002 (R2013), Information technology - Programming
languages COBOL (partial support)
v International Reference Version of ISO/IEC 646, 7-Bit Coded Character Set for
Information Interchange
v The 7-bit coded character set defined in American National Standard X3.4-1977,
Code for Information Interchange

Enterprise COBOL has the following restrictions related to COBOL standards:

v OPEN EXTEND is not supported for ASCII-encoded tapes (CODE-SET
STANDARD-1 or STANDARD-2).
v File status 97 is an informational file status value that represents successful
completion of an OPEN statement, rather than an unsuccessful completion as is
normally the case for 9x file status values in the 85 COBOL Standard.

See Option settings for 85 COBOL Standard conformance in the Enterprise COBOL
Programming Guide for specification of the compiler options and Language
Environment runtime options that are required to support the above standards.

644 Enterprise COBOL for z/OS, V6.1 Language Reference

 Appendix I. 2002 COBOL Standard features implemented in
Enterprise COBOL Version 3 or later versions
| Beginning with Enterprise COBOL Version 3, substantive changes are implemented
according to the 2002 COBOL Standard. This topic lists those changes that will
potentially affect existing COBOL programs and those changes that will not affect
existing COBOL programs.
| Table 62. 2002 COBOL Standard features implemented in V3 or later versions that will potentially affect existing
programs
Features Notes
SPECIAL-NAMES paragraph, CURRENCY SIGN clause The letters 'N', 'n', 'E' and 'e' are now used as picture
symbols. The letter 'N' or 'E' can no longer be specified
as a currency sign in the CURRENCY SIGN clause.
SAME clause File-names referenced in a SAME clause shall be
described in the FILE-CONTROL paragraph of the source
element that contains the SAME clause.
Executable code production The implementor is not required to produce an
executable object program if a fatal exception condition
for which checking is not enabled is detected by the
compiler.
Exponentiation If the value of an expression to be raised to a power is
less than zero, the following condition shall be true for
the exponent: (FUNCTION FRACTION-PART (exponent)
= 0). Otherwise, the EC-SIZE-EXPONENTIATION
exception exists and the size error condition is raised.
CORRESPONDING order The order of execution of the implied statements created
for corresponding operands for ADD, MOVE, and
SUBTRACT with the CORRESPONDING phrase is
defined to be the order of the specification of the
operands in the group following the word
CORRESPONDING. The previous COBOL standard did
not specify an order. In addition, the evaluation of
subscripts for the implied statements is done only once,
at the start of the execution of the actual ADD, MOVE,
or SUBTRACT statement. The previous COBOL standard
implied this, but was not specific.
Sending and receiving operands The terms sending operand and receiving operand have
been defined.
Incompatible data clarification The conditions that cause the incompatible data
condition are specified explicitly. They are limited to
boolean, numeric, and numeric-edited sending operands.
EVALUATE statement, sequence of execution The sequence of evaluation of selection subjects and
objects is now defined to be from left to right and
selection objects are evaluated as each WHEN phrase is
processed. When a WHEN phrase is selected, no more
selection objects are evaluated.
SIZE ERROR phrase for intermediate results If the SIZE ERROR phrase is specified for a statement
containing an arithmetic expression and a size error is
detected during evaluation of an intermediate result of
that arithmetic expression, the size error condition is set
to exist.

© Copyright IBM Corp. 1991, 2017 645

| Table 63. 2002 COBOL Standard features implemented in V3 or later versions that will not affect existing programs
Features Notes
ACCEPT statement four-digit year The capability to access the four-digit year of the
Gregorian calendar is added to the ACCEPT statement.
Apostrophe as quotation mark The apostrophe character and the quotation mark can be
used in the opening and closing delimiters of
alphanumeric, boolean, and national literals. A given
literal can use either the apostrophe or the quotation
mark, but both the starting and ending characters are
required to be the same. Whichever character is used, it
is necessary to double that character to represent one
occurrence of the character within the literal. Both
formats can be used in a single source element.
Arithmetic operators. No space is required between a left parenthesis and
unary operator or between a unary operator and a left
parenthesis.
AT END phrase The AT END phrase of the READ statement does not
have to be specified if there is no applicable USE
statement.
BINARY and floating point data Two new representations of numeric data type are
introduced, a binary representation that holds data in a
machine-specific way and is not restricted to decimal
ranges of values, and a floating-point representation. The
floating-point type exists both in a numeric form, with a
machine-specific representation, and in a numeric-edited
form.
CALL argument level numbers (any) CALL arguments can be elementary or groups with any
level number. Formerly, they had to be elementary or
have a level number of 1 or 77.
CALL BY CONTENT parameter difference A parameter passed by content does not have to have
the same description as the matching parameter in the
called program.
CALL parameter length difference The size of an argument in the USING phrase of the
CALL statement can be greater than the size of the
matching formal parameter if either the argument or the
formal parameter is a group item. Formerly, the sizes
were required to be the same.
CALL recursively The capability of calling an active COBOL program has
been added to COBOL.
| COBOL words reserved in context Certain words added to the COBOL standard are
| reserved only in the contexts in which they are specified
| and were not added to the reserved word list. See
| Appendix F, “Context-sensitive words,” on page 637 for
| details.
CODE clause (Report Writer) The identifier phrase is provided in the CODE clause in
the report description entry.
COLUMN clause A relative form is provided using PLUS integer, by
analogy with LINE; COLUMN RIGHT and COLUMN
CENTER are provided, allowing alignment of a printable
item at the right or center; and COL, COLS, and
COLUMNS are allowed as synonyms for COLUMN.
COLUMN, LINE, SOURCE, and VALUE clauses These clauses can have more than one operand in a
report group description entry.

646 Enterprise COBOL for z/OS, V6.1 Language Reference

| Table 63. 2002 COBOL Standard features implemented in V3 or later versions that will not affect existing
programs (continued)
Features Notes
Comment lines anywhere in a compilation group Comment lines can be written as any line in a
compilation group, including before the identification
division header.
Compiler directive The CALLINTERFACE compiler directive is provided,
which specifies the interface convention for CALL and
SET statements.
Control data name This is allowed to be omitted on TYPE CH/CF if only
one control is defined.
Conversion from two-digit year to four-digit year There are three functions for converting from a two-digit
year to a four-digit year. DATE-TO-YYYYMMDD,
DAY-TO-YYYYDDD, and YEAR-TO-YYYY convert from
YYnnnn to YYYYnnnn, YYnnn to YYYYnnn, and YY to
YYYY, respectively.
COPY statement An alphanumeric literal can be specified in place of
text-name-1 or library-name-1.

When more than one COBOL library is referenced,

text-name need not be qualified when the library text
resides in the default library.

The ability to nest COPY statements is provided. Library

text incorporated as a result of processing a COPY
statement without a REPLACING phrase can contain a
COPY statement without a REPLACING phrase.

A SUPPRESS PRINTING phrase is added to the COPY

statement to suppress listing of library text incorporated
as a result of COPY statement processing.
COPY and REPLACE statement partial word LEADING and TRAILING phrases of the REPLACE
replacement statement and the REPLACING phrase of the COPY
statement allow replacement of partial words in source
text and library text. This is useful for prefixing and
postfixing names.
Currency sign extensions The CURRENCY SIGN clause has been extended to
allow for national characters and for multiple distinct
currency signs, which can have any length.
DISPLAY statement If the literal in a DISPLAY statement is numeric, it can be
signed.
| DIVIDE BY zero DIVIDE BY zero conforms to the 2002 COBOL Standard.
| Nothing has changed in IBM COBOL, but the Standard
| is changed so that now Enterprise COBOL is conforming.
| (Enterprise COBOL was not conforming to the 85
| COBOL Standard for DIVIDE BY zero.)
| Dynamic storage allocation ALLOCATE and FREE statements are provided for
| obtaining storage dynamically. This storage is addressed
| by pointer data items.
EXIT statement The ability to immediately exit an inline PERFORM
statement, a paragraph, or a section has been added.
EXIT PROGRAM allowed as other than last statement EXIT PROGRAM is allowed to appear as other than the
last statement in a consecutive sequence of imperative
statements.
FILLER FILLER is allowed in the report section.

Appendix I. 2002 COBOL Standard features implemented in Enterprise COBOL Version 3 or later versions 647
| Table 63. 2002 COBOL Standard features implemented in V3 or later versions that will not affect existing
programs (continued)
Features Notes
|| Floating indicators v The floating comment indicator (*>) indicates a
| comment line if it is the first character string in the
| program-text area (Area A plus Area B), or indicates
| an inline comment if it is after one or more character
| strings in the program-text area.
| v The compiler directive indicator (>>) indicates a
| compiler directive line when followed by a compiler
| directive word - with or without an intervening space.
GOBACK statement A GOBACK statement has been added that always
returns control, either to the operating system or to the
calling runtime element.
Hexadecimal literals The ability was added to specify alphanumeric, boolean,
and national literals using hexadecimal (radix 16)
notation.
Inline comment A comment can be written on a line following any
character-strings of the source text or library text that are
written on that line. An inline comment is introduced by
the two contiguous characters '*>'.
Index data item The definition of an index data item can include the
SYNCHRONIZED clause.
| INITIALIZE statement, FILLER phrase FILLER data items can be initialized with the
| INITIALIZE statement.
| INITIALIZE statement, VALUE phrase A VALUE phrase can be specified in the INITIALIZE
| statement to cause initialization of elementary data items
| to the literal specified in the VALUE clause of the
| associated data description entry.
Intrinsic function facility Previously, the intrinsic function facility was a separate
module and its implementation was optional. The
intrinsic function facility is integrated into the
specification and it shall be implemented by a
conforming implementation
New intrinsic functions New intrinsic functions are added:
v DATE-TO-YYYYMMDD
v DAY-TO-YYYYDDD
v DISPLAY-OF
v NATIONAL-OF
v YEAR-TO-YYYY
INVALID KEY phrase The INVALID KEY phrase does not have to be specified
if there is no applicable USE statement.
LOCAL-STORAGE SECTION A facility was added to define data that is set to its initial
values each time a function, method, or program is
activated. Each instance of this source element has its
own copy of this data.

648 Enterprise COBOL for z/OS, V6.1 Language Reference

| Table 63. 2002 COBOL Standard features implemented in V3 or later versions that will not affect existing
programs (continued)
Features Notes
National character handling The capability is added for using large character sets,
such as ISO/IEC 10646-1, in source text and library text
and in data at execution time. Class national and
categories national and national-edited are specified by
picture character-strings containing the symbol 'N';
national literals are identified by a separator N", N', NX",
or NX'. Usage national specifies representation of data in
a national character set. User-defined words can contain
extended letters. Processing of data of class national is
comparable to processing data of class alphanumeric,
though there are some minor differences. Conversions
between data of classes alphanumeric and national are
provided by intrinsic functions.
Object orientation Support for object-oriented programming has been
added.
OCCURS clause Repetition vertically or horizontally and a STEP phrase
are added for Report Writer.
Optional word OF Allowed after SUM.
Optional word FOR and ON Allowed after TYPE CH or CF.
OR PAGE phrase of the CONTROL HEADING phrase This enables the control heading group to be printed at
the top of each page and after a control break.
PAGE FOOTING report group Such a group is allowed to have all relative LINE
clauses.
PAGE LIMIT clause New COLUMNS phrase is provided to define maximum
number of horizontal print positions in each report line
and a LAST CONTROL HEADING phrase was added.
Paragraph-name A paragraph-name is not required at the beginning of the
procedure division or a section.
PERFORM statement A common exit for multiple active PERFORM statements
is allowed.
PICTURE clause The maximum number of characters that can be specified
in a picture character-string is increased from 30 to 50.

The symbol 'E' can be used in a PICTURE

character-string to specify a floating-point numeric-edited
data item.

The symbol 'N' can be used in a PICTURE

character-string to specify a national or a national-edited
data item.

When the last symbol of a PICTURE character-string is a

period or a comma, one or more spaces can precede the
following separator period. It was unclear in the
previous standard whether a space could precede the
separator period in this context.
PLUS and MINUS The symbol + or - is synonymous with PLUS or MINUS,
respectively, in the COLUMN and LINE clauses.
Pointer data A new class of data is introduced, a pointer type that
holds data and program addresses in a machine-specific
or system-specific way.

Appendix I. 2002 COBOL Standard features implemented in Enterprise COBOL Version 3 or later versions 649
| Table 63. 2002 COBOL Standard features implemented in V3 or later versions that will not affect existing
programs (continued)
Features Notes
PRESENT WHEN clause The PRESENT WHEN clauses allows lines and printable
items, or groups of them, to be printed or not, depending
on the truth value of a condition.
Program-names as literals The option to specify a literal as the program-name to be
externalized was added for names that are not valid
COBOL words or need to be case-sensitive.
RECORD KEY and ALTERNATE RECORD KEY Keys for indexed files can be made up from more than
one component.
Report Writer Previously, the Report Writer was a separate module and
its implementation was optional. The Report Writer
facility is integrated into the specification and it shall be
implemented by a conforming implementation.
Report Writer national character support The capability of printing national characters and
alphanumeric characters in a report is provided.
SIGN clause in a report description entry The SEPARATE phrase is no longer required in a report
description entry and the SIGN clause can be specified at
the group level.
SORT statement A SORT statement can be used to sort a table. This sort
can be done using the fields specified in the KEY phrase
defining the table, by using the entire table element as
the key, or by using specified key data items.

GIVING files in a SORT statement can now be specified

in the same SAME RECORD AREA clause.
SOURCE clause in a report description entry The sending operand can be a function-identifier.

An arithmetic-expression is allowed as an operand and a

ROUNDED phrase was added.
SUM clause in a report description entry The SUM clause was extended in the following ways:
v Extension to total a repeating entry.
v Now allowed in any TYPE of report group, not only
control footing.
v SUM of arithmetic-expression format.
v Checks for overflow of a sum counter during totalling.
v Any numeric report section item can be totalled, not
just another sum counter.
v ROUNDED phrase.
Underscore (_) character The basic special characters of the COBOL character
repertoire have been expanded to include the underscore
(_) character, which can be used in the formation of
COBOL words.
UNSTRING statement The sending operand can be reference modified.
USE BEFORE REPORTING The effect of GLOBAL in a report description and a USE
declarative is further elucidated.
VARYING clause A VARYING clause is provided in the validate and
Report Writer facilities to be used with an OCCURS
clause.
WITH RESET phrase This was added to the NEXT PAGE phrase of the NEXT
GROUP clause to reset PAGE-COUNTER back to 1.

650 Enterprise COBOL for z/OS, V6.1 Language Reference

|

| Appendix J. Accessibility features for Enterprise COBOL for

| z/OS
| Accessibility features assist users who have a disability, such as restricted mobility
| or limited vision, to use information technology content successfully. The
| accessibility features in z/OS provide accessibility for Enterprise COBOL for z/OS.

| Accessibility features

| z/OS includes the following major accessibility features:

| v Interfaces that are commonly used by screen readers and screen-magnifier
| software
| v Keyboard-only navigation
| v Ability to customize display attributes such as color, contrast, and font size

| z/OS uses the latest W3C Standard, WAI-ARIA 1.0 (http://www.w3.org/TR/wai-

| aria/), to ensure compliance to US Section 508 (http://www.access-board.gov/
| guidelines-and-standards/communications-and-it/about-the-section-508-standards/
| section-508-standards) and Web Content Accessibility Guidelines (WCAG) 2.0
| (http://www.w3.org/TR/WCAG20/). To take advantage of accessibility features,
| use the latest release of your screen reader in combination with the latest web
| browser that is supported by this product.

| The Enterprise COBOL for z/OS online product documentation in IBM Knowledge
| Center is enabled for accessibility. The accessibility features of IBM Knowledge
| Center are described at http://www.ibm.com/support/knowledgecenter/en/
| about/releasenotes.html.

| Keyboard navigation
| Users can access z/OS user interfaces by using TSO/E or ISPF.

| Users can also access z/OS services by using IBM Rational® Developer for System
| z® .

| For information about accessing these interfaces, see the following publications:
| v z/OS TSO/E Primer (http://publib.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/
| ikj4p120)
| v z/OS TSO/E User's Guide (http://publib.boulder.ibm.com/cgi-bin/bookmgr/
| BOOKS/ikj4c240/APPENDIX1.3)
| v z/OS ISPF User's Guide Volume I (http://publib.boulder.ibm.com/cgi-bin/
| bookmgr/BOOKS/ispzug70)
| v IBM Rational Developer for System z Knowledge Center (http://www.ibm.com/
| support/knowledgecenter/SSQ2R2/rdz_welcome.html?lang=en)

| These guides describe how to use TSO/E and ISPF, including the use of keyboard
| shortcuts or function keys (PF keys). Each guide includes the default settings for
| the PF keys and explains how to modify their functions.

© Copyright IBM Corp. 1991, 2017 651

| Interface information

| The Enterprise COBOL for z/OS online product documentation is available in IBM
| Knowledge Center, which is viewable from a standard web browser.

| PDF files have limited accessibility support. With PDF documentation, you can use
| optional font enlargement, high-contrast display settings, and can navigate by
| keyboard alone.

| To enable your screen reader to accurately read syntax diagrams, source code
| examples, and text that contains period or comma PICTURE symbols, you must set
| the screen reader to speak all punctuation.

| Assistive technology products work with the user interfaces that are found in
| z/OS. For specific guidance information, see the documentation for the assistive
| technology product that you use to access z/OS interfaces.

| Related accessibility information

| In addition to standard IBM help desk and support websites, IBM has established
| a TTY telephone service for use by deaf or hard of hearing customers to access
| sales and support services:

| TTY service
| 800-IBM-3383 (800-426-3383)
| (within North America)

| IBM and accessibility

| For more information about the commitment that IBM has to accessibility, see IBM
| Accessibility (www.ibm.com/able).

652 Enterprise COBOL for z/OS, V6.1 Language Reference

Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive, MD-NC119
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM websites are provided for

convenience only and do not in any manner serve as an endorsement of those
websites. The materials at those websites are not part of the materials for this IBM
product and use of those websites is at your own risk.

© Copyright IBM Corp. 1991, 2017 653

 IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

Licensees of this program who want to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:

Intellectual Property Dept. for Rational Software

IBM Corporation
5 Technology Park Drive
Westford, MA 01886
U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrates programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample

654 Enterprise COBOL for z/OS, V6.1 Language Reference

 programs are provided “AS IS”, without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. 1991, 2017.

PRIVACY POLICY CONSIDERATIONS:

IBM Software products, including software as a service solutions, (“Software

Offerings”) may use cookies or other technologies to collect product usage
information, to help improve the end user experience, or to tailor interactions with
the end user, or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings
can help enable you to collect personally identifiable information. If this Software
Offering uses cookies to collect personally identifiable information, specific
information about this offering's use of cookies is set forth below.

This Software Offering does not use cookies or other technologies to collect
personally identifiable information.

If the configurations deployed for this Software Offering provide you as customer
the ability to collect personally identifiable information from end users via cookies
and other technologies, you should seek your own legal advice about any laws
applicable to such data collection, including any requirements for notice and
consent.

For more information about the use of various technologies, including cookies, for
these purposes, see IBM's Privacy Policy at http://www.ibm.com/privacy and
IBM's Online Privacy Statement at http://www.ibm.com/privacy/details in the
section entitled “Cookies, Web Beacons and Other Technologies,” and the “IBM
Software Products and Software-as-a-Service Privacy Statement” at
http://www.ibm.com/software/info/product-privacy.

Programming interface information

This Language Reference documents intended Programming Interfaces that allow
the customer to write programs to obtain the services of Enterprise COBOL.

Trademarks
IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at “Copyright and
trademark information” at www.ibm.com/legal/copytrade.html.

Intel is a registered trademark of Intel Corporation in the United States and other
countries.

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.

Notices 655
 Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

Other product and service names might be trademarks of IBM or other companies.

656 Enterprise COBOL for z/OS, V6.1 Language Reference

Glossary
The terms in this glossary are defined in character-string that contains only the
accordance with their meaning in COBOL. These symbol A. An alphabetic data item has
terms might or might not have the same meaning usage DISPLAY.
in other languages.
alphanumeric character
Any character in the computer's
This glossary includes terms and definitions from
single-byte character set.
the following publications:
v ANSI INCITS 23-1985, Programming Languages - alphanumeric character position
COBOL as amended by: See character position.
– ANSI INCITS 23a-1989, Programming alphanumeric data item
Languages - Intrinsic Function Module for A general reference to a data item
COBOL, described implicitly or explicitly with
– ANSI INCITS 23b-1993, Programming usage DISPLAY and category
Language - Correction Amendment for COBOL alphanumeric, alphanumeric-edited, or
numeric-edited, possibly limited to
v ANSI INCITS 172-2002 American National
specific data categories or specific data
Standard Dictionary of Information Technology.
descriptions by detailed specifications.
American National Standard definitions are alphanumeric-edited data item
preceded by an asterisk (*). A data item described by a PICTURE
character-string that contains at least one
A symbol A or X and at least one of the
simple insertion symbols B, 0, or /. An
* abbreviated combined relation condition
alphanumeric-edited data item has usage
The combined condition that results from
DISPLAY.
the explicit omission of a common subject
or a common subject and common * alphanumeric function
relational operator in a consecutive A function that returns a value that is
sequence of relation conditions. composed of a string of one or more
characters from the computer's
abend Abnormal termination of program.
alphanumeric character set.
* access mode
alphanumeric group item
The manner in which records are to be
A group item that is defined without a
operated upon within a file.
GROUP-USAGE NATIONAL clause. For
* actual decimal point operations such as INSPECT, STRING,
The physical representation, using the and UNSTRING, an alphanumeric group
decimal point characters period (.) or item is processed as though all its content
comma (,), of the decimal point position were described with usage DISPLAY,
in a data item. regardless of the actual content of the
group. For operations that require
* alphabet-name
processing of the elementary items within
A user-defined word, defined in the
a group, such as MOVE
SPECIAL-NAMES paragraph of the
CORRESPONDING, ADD
ENVIRONMENT DIVISION, that names a
CORRESPONDING, and INITIALIZE
specific character set or collating
identifier, an alphanumeric group item is
sequence, or both.
processed using group semantics.
* alphabetic character
alphanumeric literal
A letter or a space character.
A literal that has an opening delimiter
alphabetic data item from the following set:
A data item described with a PICTURE

© Copyright IBM Corp. 1991, 2017 657

 ’ Character Meaning
"
* Multiplication
X’
X" / Division
Z’ ** Exponentiation
Z"

The literal content can include any * arithmetic statement

character in the character set of the A statement that causes an arithmetic
computer. operation to be executed. The arithmetic
statements are the ADD, COMPUTE,
* alternate record key DIVIDE, MULTIPLY, and SUBTRACT
A key, other than the prime record key, statements.
whose contents identify a record within
an indexed file. * ascending key
A key, upon the values of which data is
ANSI (American National Standards Institute) ordered starting with the lowest value of
An organization consisting of producers, the key up to the highest value of the key,
consumers, and general interest groups, in accordance with the rules for
that establishes the procedures by which comparing data items.
accredited organizations create and
maintain voluntary industry standards in ASCII
the United States. American National Standard Code for
Information Interchange. A standard code,
argument using a coded character set consisting of
(1) An identifier, a literal, an arithmetic 7-bit coded characters (8 bits including
expression, or a function-identifier that parity check), used for information
specifies a value to be used in the interchange between data processing
evaluation of a function. (2) An operand systems, data communication systems,
of the USING phrase of a CALL or and associated equipment. The ASCII set
INVOKE statement, used for passing consists of control characters and graphic
values to a called program or an invoked characters.
method.
IBM has defined an extension to ASCII
* arithmetic expression (characters 128-255).
An identifier of a numeric elementary
item, a numeric literal, such identifiers ASCII DBCS
and literals separated by arithmetic See double-byte ASCII.
operators, two arithmetic expressions assignment-name
separated by an arithmetic operator, or an A name that identifies the organization of
arithmetic expression enclosed in a COBOL file and the name by which it is
parentheses. known to the system.
* arithmetic operation * assumed decimal point
The process caused by the execution of an A decimal point position that does not
arithmetic statement, or the evaluation of involve the existence of an actual
an arithmetic expression, that results in a character in a data item. The assumed
mathematically correct solution to the decimal point has logical meaning with
arguments presented. no physical representation.
* arithmetic operator * AT END condition
A single character, or a fixed A condition that exists in the following
two-character combination that belongs to circumstances:
the following set: v During the execution of a READ
Character Meaning statement for a sequentially accessed
file, when no next logical record exists
+ Addition in the file, or when the number of
- Subtraction significant digits in the relative record
number is larger than the size of the
658 Enterprise COBOL for z/OS, V6.1 Language Reference
 relative key data item, or when an the block or that overlap the block. The
optional input file is not available. term is synonymous with physical record.
v During the execution of a RETURN buffer
statement, when no next logical record A portion of storage used to hold input or
exists for the associated sort or merge output data temporarily.
file.
byte A string consisting of a certain number of
v During the execution of a SEARCH
bits, usually eight, treated as a unit.
statement, when the search operation
terminates without satisfying the byte order mark (BOM)
condition specified in any of the A Unicode character that can be used at
associated WHEN phrases. the start of UTF-16 or UTF-32 text to
indicate the byte order of subsequent text;
B the byte order can be either big endian or
little endian.
basic character set
The basic set of characters used in writing
C
words, character-strings, and separators of
the language. The basic character set is cataloged procedure
implemented in single-byte EBCDIC. The A set of job control statements placed in a
extended character set includes DBCS partitioned data set called the procedure
characters, which can be used in library (SYS1.PROCLIB). You can use
comments, literals, and user-defined cataloged procedures to save time and
words. reduce errors coding JCL.
Synonymous with COBOL character set in CCSID
the 85 COBOL Standard. See coded character set identifier.
big-endian century window
The default format used by the A 100-year interval within which any
mainframe to store binary data. In this two-digit year is unique. For windowing
format, the least significant digit is on the intrinsic functions DATE-TO-
highest address. See also little-endian. YYYYMMDD, DAY-TO-YYYYDDD, and
YEAR-TO-YYYY, it is specified by
binary item
argument-2.
A numeric data item represented in
binary notation (on the base 2 numbering * character
system). Binary items have a decimal The basic indivisible unit of the language.
equivalent consisting of the decimal digits
character encoding unit
0 through 9, plus an operational sign. The
A unit of data that corresponds to one
leftmost bit of the item is the operational
code point in a coded character set. One
sign.
or more character encoding units are used
binary search to represent a character in a coded
A dichotomizing search in which, at each character set. Also known as encoding unit.
step of the search, the set of data elements
For usage NATIONAL, a character
is divided by two; some appropriate
encoding unit corresponds to one 2-byte
action is taken in the case of an odd
code point of UTF-16.
number.
For usage DISPLAY, a character encoding
* block
unit corresponds to a byte.
A physical unit of data that is normally
composed of one or more logical records. For usage DISPLAY-1, a character
For mass storage files, a block can contain encoding unit corresponds to a 2-byte
a portion of a logical record. The size of a code point in the DBCS character set.
block has no direct relationship to the size
character position
of the file within which the block is
The amount of physical storage or
contained or to the size of the logical
presentation space required for holding or
records that are either contained within
presenting one character. The term applies

Glossary 659
 to any class of character. For specific to the proposition for which a truth value
classes of characters, the following terms can be defined, that the content of a data
apply: item consists exclusively of those
v Alphanumeric character position, for characters listed in the definition of the
characters represented in usage class-name.
DISPLAY * clause
v DBCS character position, for DBCS An ordered set of consecutive COBOL
characters represented in usage character-strings whose purpose is to
DISPLAY-1 specify an attribute of an entry.
v National character position, for characters COBOL character set
represented in usage NATIONAL; See basic character set.
synonymous with character encoding
unit for UTF-16 * COBOL word
See word.
character set
See basic character set and coded character code page
set. An assignment of graphic characters and
control character meanings to the code
* character-string points in a coded character set; for
A sequence of contiguous characters that example, assignment of characters and
forms a COBOL word, a literal, a meanings to the 256 code points in
PICTURE character-string, or a single-byte EBCDIC or ASCII. The terms
comment-entry. Must be delimited by coded character set and code page can be
separators. used interchangeably.
checkpoint code point
A point at which information about the A unique bit pattern defined in a code
status of a job and the system can be page. Graphic symbols and control
recorded so that the job step can be characters are assigned to code points.
restarted later.
coded character set
class (object-oriented) A set of graphic characters and control
The entity that defines common behavior characters along with their unambiguous
and implementation for zero, one, or assignment to specific code points (their
more objects. The objects that share the encodings). EBCDIC is an example of a
same implementation are considered to be coded character set. A specific instance of
objects of the same class. encodings is called a code page. A code
* class condition page specified by IBM is identified by a
The proposition (for which a truth value CCSID.
can be determined) that the content of an coded character set identifier (CCSID)
item is wholly alphabetic, is wholly An IBM-defined number in the range 1 to
numeric, is wholly DBCS, is wholly Kanji, 65,535 that identifies a specific code page.
or consists exclusively of the characters
that are listed in the definition of a * collating sequence
class-name. The sequence in which the characters that
are acceptable to a computer are ordered
class definition for purposes of sorting, merging,
The COBOL source unit that defines a comparing, and for processing indexed
class. files sequentially.
class-name (object-oriented) column
The name of an object-oriented class A byte position within a print line or
definition. Class-name can refer to a within a reference format line. The
COBOL class-name or a Java class-name. columns are numbered from 1, by 1,
* class-name (of data) starting at the leftmost position of the line
A user-defined word, defined in the
SPECIAL-NAMES paragraph, that refers

660 Enterprise COBOL for z/OS, V6.1 Language Reference

 and extending to the rightmost position of conditions. See also negated simple
the line. A column holds one single-byte condition, combined condition, and negated
character. combined condition.
* combined condition complex ODO
A condition that is the result of Certain forms of the OCCURS
connecting two or more conditions with DEPENDING ON clause:
the AND or the OR logical operator. v A variably located item or group: A
* comment-entry data item described with an OCCURS
An entry in the IDENTIFICATION clause with the DEPENDING ON
DIVISION that is used for documentation phrase, followed by a nonsubordinate
and has no effect on execution. data item or group. The group can be
an alphanumeric group or a national
comment line group.
A source program line represented by an
v A variably located table: A data item
asterisk (*) in the indicator area of the line
described with an OCCURS clause with
or by an asterisk followed by greater-than
the DEPENDING ON phrase, followed
sign (*>) as the first character string in the
by a nonsubordinate data item
program text area (Area A plus Area B),
described with an OCCURS clause.
and any characters from the character set
of the computer that follow in Area A and v A table with variable-length elements:
Area B of that line. A comment line serves A data item described with an
only for documentation. A special form of OCCURS clause, where a subordinate
comment line represented by a slant (/) data item is described with an
in the indicator area of the line and any OCCURS clause with the DEPENDING
characters from the character set of the ON phrase.
computer in Area A and Area B of that v An index name for a table with
line causes page ejection before the variable-length elements.
comment is printed. v An element of a table with
* common program variable-length elements.
A program that, despite being directly condition (exception)
contained within another program, is An exception that has been enabled, or
permitted to be called from any program recognized, by Language Environment
directly or indirectly contained in that and thus is eligible to activate user and
other program. language condition handlers. Any
compilation group alteration to the normal programmed flow
A sequence of source units submitted for of an application. Conditions can be
compilation together. detected by the hardware or operating
system and result in an interrupt. They
compilation unit can also be detected by language-specific
See source unit generated code or language library code.
* compile time * condition (expression)
The time at which COBOL source code is A status of data at run time for which a
translated by a COBOL compiler to a truth value can be determined. Where the
COBOL object program. term 'condition' (condition-1, condition-2,...)
compiler-directing statement appears in these language specifications
A statement that causes the compiler to in or in reference to 'condition'
take a specific action during compilation. (condition-1, condition-2,...) of a general
The standard compiler-directing format, it is a conditional expression
statements are COPY, REPLACE, and consisting of either a simple condition
USE. optionally parenthesized, or a combined
condition consisting of the syntactically
* complex condition correct combination of simple conditions,
A condition in which one or more logical logical operators, and parentheses, for
operators act upon one or more which a truth value can be determined.

Glossary 661
* conditional expression number representations in a manner that
A simple condition or a complex permits these numbers to be increased or
condition specified in an EVALUATE, IF, decreased by the value of another
PERFORM, or SEARCH statement. See number, or to be changed or reset to zero
also simple condition and complex condition. or to an arbitrary positive or negative
value.
* conditional phrase
A conditional phrase specifies the action cs See currency symbol.
to be taken upon determination of the
currency sign value
truth value of a condition resulting from
A character-string that identifies the
the execution of a conditional statement.
monetary units stored in a numeric-edited
* conditional statement item. Some examples are '$', 'USD', 'JPY',
A statement specifying that the truth and 'EUR'. A currency sign value can be
value of a condition is to be determined defined by either the CURRENCY
and that the subsequent action of the compiler option or the CURRENCY SIGN
object program is dependent on this truth clause in the SPECIAL-NAMES paragraph
value. of the ENVIRONMENT DIVISION. If the
CURRENCY SIGN clause is not specified
* conditional variable
and the NOCURRENCY compiler option
A data item one or more values of which
is in effect, the dollar sign ($) is used as
has a condition-name assigned to it.
the default currency sign value. See also
* condition-name currency symbol.
A user-defined word that assigns a name
currency symbol
to a subset of values that a conditional
A character used in a PICTURE clause to
variable is permitted to assume; or a
indicate the position of a currency sign
user-defined word assigned to a status of
value in a numeric-edited item. A currency
an implementor defined switch or device.
symbol can be defined by either the
* condition-name condition CURRENCY compiler option or by the
The proposition, for which a truth value CURRENCY SIGN clause in the
can be determined, that the value of a SPECIAL-NAMES paragraph of the
conditional variable is a member of the PROCEDURE DIVISION. If the
set of values attributed to a CURRENCY SIGN clause is not specified
condition-name associated with the and the NOCURRENCY compiler option
conditional variable. is in effect, the dollar sign ($) is used as
the default currency sign value and
* configuration section
currency symbol. Multiple currency
A section of the ENVIRONMENT
symbols and currency sign values can be
DIVISION that describes overall
defined. See also currency sign value.
specifications of source and object
programs, method definitions, and class * current record
definitions. In file processing, the record that is
available in the record area associated
CONSOLE
with a file.
A COBOL environment-name associated
with the operator console. * current volume pointer
A conceptual entity that points to the
* contiguous items
current volume of a sequential file.
Items that are described by consecutive
entries in the DATA DIVISION, and that
D
bear a definite hierarchic relationship to
each other. * data description entry
An entry in the DATA DIVISION
contained program
composed of a level-number followed by
A COBOL program that is nested within
a data-name, if required, and then
another COBOL program.
followed by a set of clauses that describe
* counter the attributes of a data item or record.
A data item used for storing numbers or

662 Enterprise COBOL for z/OS, V6.1 Language Reference

* DATA DIVISION item in order to determine that item's
A COBOL division that describes data unedited numeric value.
and files to be processed at run time.
* delimited scope statement
* data item Any statement that includes its explicit
A unit of data (excluding literals) defined scope terminator.
by a COBOL program or by the rules for
* delimiter
function evaluation.
A character or a sequence of contiguous
* data-name characters that identify the end of a string
A user-defined word that names a data of characters and separate that string of
item described in a data description entry. characters from the following string of
The maximum length of a data-name is 30 characters. A delimiter is not part of the
bytes. When used in the general formats, string of characters that it delimits.
'data-name' represents a word that must
* descending key
not be reference-modified, subscripted or
A key upon the values of which data is
qualified unless specifically permitted by
ordered starting with the highest value of
the rules for the format.
key down to the lowest value of key, in
DBCS accordance with the rules for comparing
See Double-Byte Character Set (DBCS). data items.
DBCS character digit Any of the numerals from 0 through 9. In
Any character defined in an IBM COBOL, the term is not used in reference
double-byte character set. to any other symbol.
DBCS character position * digit position
See character position. The amount of physical storage required
to store a single digit. This amount can
DBCS data item
vary depending on the usage specified in
A data item described by a PICTURE
the data description entry that defines the
character-string that contains at least one
data item.
symbol G or, when the NSYMBOL(DBCS)
compiler option is in effect, at least one * direct access
symbol N. A DBCS data item has usage The facility to obtain data from storage
DISPLAY-1. devices or to enter data into a storage
device in such a way that the process
* debugging line
depends only on the location of that data
A debugging line is any line with a 'D' in
and not on a reference to data previously
the indicator area of the line.
accessed.
* debugging section
display floating-point data item
A section that contains a USE FOR
A data item described with usage
DEBUGGING statement.
DISPLAY and a picture character-string
* declaratives that describes an external floating-point
A set of one or more special purpose data item. See floating-point.
sections, written at the beginning of the
* division
PROCEDURE DIVISION, the first of
There are four divisions in a COBOL
which is preceded by the keyword
program: identification, environment,
DECLARATIVES and the last of which is
data, and procedure.
followed by the keyword END
DECLARATIVES. A declarative is * division header
composed of a section header, followed A combination of words followed by a
by a USE compiler-directing sentence, separator period that indicates the
followed by a set of zero, one, or more beginning of a division. The division
associated paragraphs. headers are:
* de-edit v IDENTIFICATION DIVISION.
The logical removal of all editing v ENVIRONMENT DIVISION.
characters from a numeric-edited data v DATA DIVISION.

Glossary 663
 v PROCEDURE DIVISION. EBCDIC DBCS
See double-byte EBCDIC.
do-until
In structured programming, a do-until edited data item
loop will be executed at least once, and A data item that has been modified by
until a given condition is true. In COBOL, suppressing zeroes or inserting editing
a TEST AFTER phrase used with the characters.
PERFORM statement functions in the
* editing character
same way.
A single character or a fixed two-character
do-while combination belonging to the following
In structured programming, a do-while set:
loop will be executed if, and while, a
given condition is true. In COBOL, a Character Meaning
TEST BEFORE phrase used with the Space
PERFORM statement functions in the 0 Zero
same way.
+ Plus
double-byte ASCII
- Minus
An IBM character set that includes DBCS
and single-byte ASCII characters. (Also CR Credit
known as ASCII DBCS.) DB Debit
double-byte EBCDIC Z Zero suppress
An IBM character set that includes DBCS * Check protect
and single-byte EBCDIC characters. (Also
known as EBCDIC DBCS.) $ Currency sign
, Comma (decimal point)
Double-Byte Character Set (DBCS)
An IBM coded character set in which each . Period (decimal point)
character is represented by two bytes. / Forward slash
Languages such as Japanese, Chinese, and
Korean, which contain more symbols than
can be represented by 256 code points, * elementary item
require double-byte character sets. A data item that is described as not being
Because each character requires two bytes, further logically subdivided.
entering, displaying, and printing DBCS encoding unit
characters requires hardware and See character encoding unit.
supporting software that are
DBCS-capable. end class marker
A combination of words, followed by a
* dynamic access separator period, that indicates the end of
An access mode in which specific logical a COBOL class definition. The end class
records can be obtained from or placed marker is:
into a mass storage file in a nonsequential END CLASS class-name.
manner and obtained from a file in a
sequential manner during the scope of the end method marker
same OPEN statement. A combination of words, followed by a
separator period, that indicates the end of
E a COBOL method definition. The end
method marker is:
EBCDIC (Extended Binary-Coded Decimal
END METHOD method-name.
Interchange Code)
A coded character set consisting of 8-bit * end of PROCEDURE DIVISION
coded characters. The physical position of a COBOL
PROCEDURE DIVISION after which no
EBCDIC character
further procedures appear.
Any one of the graphic characters or
control characters encoded in EBCDIC. end program marker
A combination of words, followed by a

664 Enterprise COBOL for z/OS, V6.1 Language Reference

 separator period, that indicates the end of expression is indicated with the symbol
a COBOL source program. The end '**' followed by the exponent.
program marker is:
* expression
END PROGRAM program-name. An arithmetic or conditional expression.
* entry * extend mode
Any descriptive set of consecutive clauses The state of a file after execution of an
written in the IDENTIFICATION OPEN statement, with the EXTEND
DIVISION, PROCEDURE DIVISION, or phrase specified for that file, and before
DATA DIVISION of a COBOL program. the execution of a CLOSE statement,
* ENVIRONMENT DIVISION without the REEL or UNIT phrase for that
A division of a COBOL source unit that file.
describes the computers upon which the Extensible Markup Language
source code is compiled and those on See XML.
which the object code is run. It provides a
linkage between the logical concept of * external data
files and their records and the physical The data described in a program as
aspects of the devices on which files are external data items and external file
stored. connectors.

environment-name * external data item

A name, specified by IBM, that identifies A data item that is described as part of an
system logical units, printer and card external record in one or more programs
punch control characters, report codes, or of a run unit and that itself is permitted
program switches. When an to be referenced from any program in
environment-name is associated with a which it is described.
mnemonic-name in the ENVIRONMENT * external data record
DIVISION, the mnemonic-name can then A logical record which is described in one
be substituted in any format in which or more programs of a run unit and
such substitution is valid. whose constituent data items are
environment variable permitted to be referenced from any
Any of a number of variables that define program in which they are described.
some aspect of the computing external decimal data item
environment, and are accessible to A zoned decimal data item or a national
programs that operate in that decimal data item. A zoned decimal data
environment. Environment variables can item has usage DISPLAY. A national
affect the behavior of programs that are decimal data item has usage NATIONAL.
sensitive to the environment in which See zoned decimal data item and national
they operate. decimal data item.
execution time * external file connector
See run time. A file connector which is accessible to one
execution-time environment or more object programs in the run unit.
See runtime environment. external floating-point data item
* explicit scope terminator A display floating-point data item or a
A reserved word that terminates the scope national floating-point data item. A
of a particular PROCEDURE DIVISION display floating-point data item has usage
statement. For example, END-READ. DISPLAY. A national floating-point data
item has usage NATIONAL. See display
exponent floating-point data item and national
A number, indicating the power to which floating-point data item.
another number (the base) is to be raised.
Positive exponents denote multiplication, * external switch
negative exponents denote division, A hardware or software device, defined
fractional exponents denote a root of a
quantity. In COBOL, an exponential

Glossary 665
 and named by the implementor, which is file-name, and then followed by a set of
used to indicate that one of two alternate clauses that include the attributes of the
states exists. file.
* file-name
F
A user-defined word that names a file
factory data connector described in a file description
Data of a factory object. Factory data is entry or a sort-merge file description
allocated once for a class and shared by entry within the FILE SECTION of the
all instances of the class. Factory data is DATA DIVISION.
declared in the WORKING-STORAGE
* file organization
SECTION in the factory paragraph of a
The permanent logical file structure
class definition. Factory data is equivalent
established at the time that a file is
to private static data in Java.
created.
factory method
*file position indicator
A method that is supported by a class
A conceptual entity that contains the
independently of any object instance.
value of the current key within the key of
Factory methods are defined in the
reference for an indexed file, or the record
factory paragraph of the class definition,
number of the current record for a
and are equivalent to public static
sequential file, or the relative record
methods in Java. They are typically used
number of the current record for a
to customize the creation of objects.
relative file, or indicates that no next
* figurative constant logical record exists, or that an optional
A compiler-generated value referenced input file is not available, or that the at
through the use of certain reserved end condition already exists, or that no
words. valid next record has been established.
* file A collection of logical records. * FILE SECTION
The section of the DATA DIVISION that
* file attribute conflict condition
contains file description entries and
An unsuccessful attempt has been made
sort-merge file description entries together
to execute an input-output operation on a
with their associated record descriptions.
file and the file attributes, as specified for
that file in the program, do not match the file system
fixed attributes for that file. The collection of files and file
management structures on a physical or
* file connector
logical mass storage device, such as a
A storage area which contains information
diskette or minidisk.
about a file and is used as the linkage
between a file-name and a physical file * fixed file attributes
and between a file-name and its Information about a file which is
associated record area. established when a file is created and
cannot subsequently be changed during
* file control entry
the existence of the file. These attributes
A SELECT clause and all its subordinate
include the organization of the file
clauses which declare the relevant
(sequential, relative, or indexed), the
physical attributes of a file.
prime record key, the alternate record
* file-control paragraph keys, the code set, the minimum and
A paragraph in the ENVIRONMENT maximum record size, the record type
DIVISION in which the data files for a (fixed or variable), the collating sequence
given source unit are declared. of the keys for indexed files, the blocking
factor, the padding character, and the
* file description entry
record delimiter.
An entry in the FILE SECTION of the
DATA DIVISION that is composed of the * fixed-length record
level indicator FD, followed by a A record associated with a file whose file
description or sort-merge description

666 Enterprise COBOL for z/OS, V6.1 Language Reference

 entry requires that all records contain the the general formats that an arithmetic
same number of bytes. expression can be specified.
fixed-point item function-name
A numeric data item defined with a A word that names the mechanism whose
PICTURE clause that specifies the location invocation, along with required
of an optional sign, the number of digits arguments, determines the value of a
it contains, and the location of an optional function.
decimal point. The format can be either
function-pointer
binary, packed decimal, or external
A data item that can contain the address
decimal.
of a procedure or function, described with
floating-point a usage of FUNCTION-POINTER.
A format for representing numbers in
which a real number is represented by a G
pair of distinct numerals. In floating-point
garbage collection
representation, the real number is the
The automatic freeing by the Java runtime
product of the fixed-point part (the first
system of the memory for objects that are
numeral), and a value obtained by raising
no longer referenced.
the implicit floating-point base to a power
denoted by the exponent (the second * global name
numeral). A name that is declared in only one
program but which can be referenced
For example, a floating-point
from that program and from any program
representation of the number 0.0001234 is:
contained within that program.
0.1234 -3, where 0.1234 is the mantissa
Condition-names, data-names, file-names,
and -3 is the exponent.
record-names, report-names, and some
floating-point item special registers can be global names.
A numeric data item containing a fraction
group item
and an exponent. Its value is obtained by
(1) A data item that is composed of
multiplying the fraction by the base of the
subordinate data items. A group item that
numeric data item raised to the power
is described with an explicit or implicit
specified by the exponent.
GROUP-USAGE NATIONAL clause is a
* format national group item. A group that is
A specific arrangement of a set of data. described without a GROUP-USAGE
NATIONAL clause is an alphanumeric
* function
group item. See alphanumeric group item
A temporary data item whose value is
and national group item. (2) When not
determined at the time the function is
qualified explicitly or by context as a
referenced during the execution of a
national group or an alphanumeric group,
statement.
the term refers to groups in general.
* function-identifier
grouping separator
A syntactically correct combination of
A character used to separate units of
character-strings and separators that
digits in numbers for ease of reading. The
references a function. The data item
default is the character comma.
represented by a function is uniquely
identified by a function-name with its
H
arguments, if any. A function-identifier
can include a reference-modifier. A header label
function-identifier that references an (1) A file label or data set label that
alphanumeric function can be specified precedes the data records on a unit of
anywhere in the general formats that an recording media. (2) Synonym for
identifier can be specified, subject to beginning-of-file label.
certain restrictions. A function-identifier
hide (a method)
that references an integer or numeric
To redefine (in a subclass) a factory or
function can be referenced anywhere in
static method defined with the same

Glossary 667
 method-name in a parent class. Thus, the indexed data-name
method in the subclass hides the method An identifier that is composed of a
in the parent class. data-name, followed by one or more
index-names enclosed in parentheses.
* high order end
The leftmost character of a string of * indexed file
characters. A file with indexed organization.
* indexed organization
I
The permanent logical file structure in
IBM extensions which each record is identified by the
COBOL syntax and semantics specified by value of one or more keys within that
IBM, rather than by the 85 COBOL record.
Standard.
indexing
IDENTIFICATION DIVISION Subscripting using index-names.
One of the four main component parts of
* index-name
a COBOL program, class definition, or
A user-defined word that names an index
method definition. The IDENTIFICATION
associated with a specific table.
DIVISION identifies the program, class, or
method. The IDENTIFICATION inheritance
DIVISION can include the following A mechanism for using the
documentation: author name, installation, implementation of a class (the superclass)
or date. as the basis for a new class (a subclass).
Each subclass inherits from exactly one
* identifier
class. The inherited class can itself be a
Syntax that references a resource, such as
subclass that inherits from another class.
a data item. An identifier that refers to
data item includes the data-name and Enterprise COBOL does not support
optionally includes qualifiers, multiple inheritance. It supports the Java
subscripting, and reference modification. object model, which provides single
inheritance.
* imperative statement
A statement that specifies an * initial program
unconditional action to be taken or a A program that is placed into an initial
conditional statement that is delimited by state every time the program is called in a
its explicit scope terminator (a delimited run unit.
scope statement). An imperative statement
* initial state
can consist of a sequence of imperative
The state of a program when it is first
statements.
called in a run unit.
* implicit scope terminator
inline
A separator period that terminates the
In a program, instructions that are
scope of any preceding unterminated
executed sequentially, without branching
statement, or a phrase of a statement that
to routines, subroutines, or other
by its occurrence indicates the end of the
programs.
scope of any statement contained within
the preceding phrase. * input file
A file that is opened in the INPUT mode.
* index
A computer storage area or register, the * input mode
content of which represents the The state of a file after execution of an
identification of a particular element in a OPEN statement, with the INPUT phrase
table. specified, for that file and before the
execution of a CLOSE statement, without
* index data item
the REEL or UNIT phrase for that file.
A data item in which the values
associated with an index-name can be * input-output file
stored in a form specified by the A file that is opened in the I-O mode.
implementor.

668 Enterprise COBOL for z/OS, V6.1 Language Reference

* input-output section interlanguage communication (ILC)
The section of the ENVIRONMENT The ability of routines written in different
DIVISION that names the files and the programming languages to communicate.
external media required by a program or ILC support allows the application writer
method and that provides information to readily build applications from
required for transmission and handling of component routines written in a variety
data at run time. of languages.
* input-output statement intermediate result
A statement that causes files to be An intermediate field containing the
processed by performing operations upon results of a succession of arithmetic
individual records or upon the file as a operations.
unit. The input-output statements are:
* internal data
ACCEPT (with the identifier phrase),
The data described in a program
CLOSE, DELETE, DISPLAY, OPEN,
excluding all external data items and
READ, REWRITE, SET (with the TO ON
external file connectors. Items described
or TO OFF phrase), START, and WRITE.
in the LINKAGE SECTION of a program
* input procedure are treated as internal data.
A set of statements, to which control is
* internal data item
given during the execution of a format 1
A data item which is described in one
SORT statement, for the purpose of
program in a run unit. An internal data
controlling the release of specified records
item can have a global name.
to be sorted.
internal decimal data item
instance data
A data item that is described with usage
Data defining the state of an object
PACKED-DECIMAL or COMP-3 and a
instance. Instance data is declared in the
PICTURE character-string that defines the
WORKING-STORAGE SECTION of the
item as numeric (a valid combination of
object paragraph of a class definition.
symbols 9, S, P, or V). Synonymous with
Also called object instance data. Each object
packed decimal item.
instance has its own copy of instance
data. Instance data is equivalent to * internal file connector
private nonstatic member data in a Java A file connector that is accessible to only
class. one object program in the run unit.
instance method internal floating-point data item
A method defined in the object paragraph A data item that is described with usage
of a class definition. Instance methods are COMP-1 or COMP-2. COMP-1 defines a
equivalent to public nonstatic methods in single-precision floating-point data item.
Java. COMP-2 defines a double-precision
floating-point data item. There is no
* integer
PICTURE clause associated with an
(1) A numeric literal that does not include
internal floating-point data item.
any digit positions to the right of the
decimal point. (2) A numeric data item intrinsic function
defined in the DATA DIVISION that does A function defined as part of the COBOL
not include any digit positions to the language. In some programming
right of the decimal point. (3) A numeric languages, this is called a built-in
function whose definition provides that function.
all digits to the right of the decimal point
* invalid key condition
are zero in the returned value for any
A condition, at run time, caused when a
possible evaluation of the function.
specific value of the key associated with
* integer function an indexed or relative file is determined
A function whose category is numeric and to be invalid.
whose definition does not include any
* I-O mode
digit positions to the right of the decimal
The state of a file after execution of an
point.

Glossary 669
 OPEN statement, with the I-O phrase v Uppercase letters: A, B, C, D, E, F, G,
specified, for that file and before the H, I, J, K, L, M, N, O, P, Q, R, S, T, U,
execution of a CLOSE statement without V, W, X, Y, Z
the REEL or UNIT phase for that file. v Lowercase letters: a, b, c, d, e, f, g, h, i,
* I-O status j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z
A conceptual entity which contains the * level indicator
two-character value indicating the Two alphabetic characters that identify a
resulting status of an input-output specific type of file or a position in a
operation. This value is made available to hierarchy. The level indicators in the
the program through the use of the FILE DATA DIVISION are: CD, FD, and SD.
STATUS clause in the file control entry for
the file. * level-number
A user-defined word, expressed as a
J two-digit number, which indicates the
hierarchical position of a data item or the
Java Native Interface (JNI) special properties of a data description
A programming interface that allows Java entry. Level-numbers in the range from 1
code running inside a Java virtual through 49 indicate the position of a data
machine (JVM) to interoperate with item in the hierarchical structure of a
applications and libraries written in other logical record. Level-numbers in the range
programming languages. 1 through 9 can be written either as a
single digit or as a zero followed by a
K significant digit. Level-numbers 66, 77,
K When referring to storage capacity, two to and 88 identify special properties of a
the tenth power; 1024 in decimal notation. data description entry.

* key A data item that identifies the location of * library-name

a record, or a set of data items which A user-defined word that names a
serve to identify the ordering of data. COBOL library that is to be used by the
compiler for a given compilation.
* key of reference
The key, either prime or alternate, * library text
currently being used to access records A sequence of text words, comment lines,
within an indexed file. inline comments, the separator space, or
the separator pseudo-text delimiter in a
| * keyword COBOL library.
| A context-sensitive word or a reserved
| word whose presence is required when Lilian date
| the format in which the word appears is The number of days since the beginning
| used in a source unit. of the Gregorian calendar. Day one is
Friday, October 15, 1582. The Lilian date
kilobyte (KB) format is named in honor of Luigi Lilio,
One kilobyte equals 1024 bytes. the creator of the Gregorian calendar.

L * LINAGE-COUNTER
A special register whose value points to
* language-name the current position within the page body.
A system-name that specifies a particular
programming language. LINKAGE SECTION
The section in the DATA DIVISION of an
last-used state activated unit (a called program or an
The state of storage in which internal invoked method) that describes data
values remain the same as when the items available from the activating unit (a
program or method was exited (are not program or a method). These data items
reset to their initial values on reentry). can be referred to by both the activated
* letter unit and the activating unit.
A character belonging to one of the literal
following two sets: A character-string whose value is

670 Enterprise COBOL for z/OS, V6.1 Language Reference

 specified either by the ordered set of MERGE statement. The merge file is
characters comprising the string, or by the created and can be used only by the
use of a figurative constant. merge function.
little-endian method
The default format that Intel processors Procedural code that defines one of the
use to store binary data. In this format, operations supported by an object.
the most significant digit is at the highest Method procedural code is executed by a
address. See also big-endian. COBOL INVOKE statement on a specific
object instance. A method can be invoked
LOCAL-STORAGE SECTION
by a Java invocation expression. A
The section of the DATA DIVISION that
method can be a factory method or an
defines storage that is allocated and freed
instance method.
on a per-invocation basis, depending on
the value assigned in their VALUE method identification entry
clauses. An entry in the METHOD-ID paragraph
of the IDENTIFICATION DIVISION that
* logical operator
contains clauses that specify the
One of the reserved words AND, OR, or
method-name and assign selected
NOT. In the formation of a condition,
attributes to the method definition.
either AND or OR, or both, can be used
as logical connectives. NOT can be used method invocation
for logical negation. (1) The act of invoking a method. (2) The
programming language syntax used to
* logical record
invoke a method (the INVOKE statement
The most inclusive data item. The
in COBOL, a method invocation
level-number for a record is 01. A record
expression in Java).
can be either an elementary item or a
group of items. The term is synonymous method-name
with record. A name that identifies a method, specified
as the content of an alphanumeric or
* low order end
national literal in the METHOD-ID
The rightmost character of a string of
paragraph, and as the content of an
characters.
alphanumeric literal, national literal,
alphanumeric data item, or data item of
M
category national in the INVOKE
main program statement.
In a hierarchy of programs and
method hiding
subroutines, the first program to receive
See hide.
control when the programs are run.
method overloading
* mass storage
See overload.
A storage medium in which data can be
organized and maintained in both a method overriding
sequential and nonsequential manner. See override.
* mass storage device * mnemonic-name
A device having a large storage capacity; A user-defined word that is associated in
for example, magnetic disk, magnetic the ENVIRONMENT DIVISION with a
drum. specified implementor-name.
* mass storage file
N
A collection of records that is assigned to
a mass storage medium. namespace
See XML namespace.
* megabyte (M)
One megabyte equals 1,048,576 bytes. national character
Any character represented in UTF-16.
* merge file
A collection of records to be merged by a

Glossary 671
national character data associated with the computer specified in
A general reference to data represented in the OBJECT-COMPUTER paragraph.
UTF-16.
* native collating sequence
national character position The implementor-defined collating
See character position. sequence associated with the computer
specified in the OBJECT-COMPUTER
national data
paragraph.
See national character data.
* negated combined condition
national data item
The 'NOT' logical operator immediately
A data item of class national. Class
followed by a parenthesized combined
national includes categories national,
condition.
national-edited, and numeric-edited with
USAGE NATIONAL. * negated simple condition
The 'NOT' logical operator immediately
national decimal data item
followed by a simple condition.
A data item described by a PICTURE
character-string that contains valid nested program
combinations of picture symbols 9, S, P, A program that is directly contained
and V. A national decimal data item is an within another program.
external decimal data item that has usage
* next executable sentence
NATIONAL.
The next sentence to which control will be
national-edited data item transferred after execution of the current
A data item described by a PICTURE statement is complete.
character-string that contains the symbol
* next executable statement
N and at least one of the simple insertion
The next statement to which control will
symbols B, 0, and /. A national-edited
be transferred after execution of the
data item has usage NATIONAL.
current statement is complete.
national floating-point data item
* next record
A data item described with usage
The record that logically follows the
NATIONAL and a picture character-string
current record of a file.
that describes a floating-point data item.
See floating-point. * noncontiguous items
Elementary data items in the
national group item
WORKING-STORAGE or LINKAGE
A group item that is explicitly or
SECTION that bear no hierarchic
implicitly described with a
relationship to other data items.
GROUP-USAGE clause with the
NATIONAL phrase. A national group is null A figurative constant that represents a
processed as though it were defined as an value used to indicate that a pointer data
elementary data item of category national item does not contain a valid address or
for operations such as INSPECT, STRING, that an object reference does not reference
and UNSTRING. This ensures correct an object. NULLS can be used wherever
padding and truncation of national NULL can be used.
characters, as opposed to defining data
* numeric character
items described with USAGE NATIONAL
A character that belongs to the following
within an alphanumeric group item. For
set of digits: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9.
operations that require processing of the
elementary items within a group, such as numeric data item
MOVE CORRESPONDING, ADD (1) A data item whose description restricts
CORRESPONDING, and INITIALIZE its content to a value represented by
identifier, a national group is processed characters chosen from the digits from '0'
using group semantics. through '9'; if signed, the item can also
contain a '+', '-', or other representation of
* native character set
an operational sign. (2) A data item of
The implementor-defined character set
class numeric and category numeric,

672 Enterprise COBOL for z/OS, V6.1 Language Reference

 internal floating-point, or external object instance
floating-point, possibly limited to specific A single object, of possibly many,
data categories or specific data instantiated from the specifications in the
descriptions by detailed specifications. A object paragraph of a COBOL class
numeric data item can have usage definition. An object instance has a copy
DISPLAY, NATIONAL, of all the data described in its class
PACKED-DECIMAL, BINARY, COMP, definition and all inherited data. The
COMP-1, COMP-2, COMP-3, COMP-4, or methods associated with an object
COMP-5. instance includes the methods defined in
its class definition and all inherited
numeric-edited data item
methods.
A data item that contains numeric data in
a form suitable for use in printed output. An object instance can be an instance of a
It can consist of external decimal digits Java class.
from 0 through 9, the decimal separator,
object module
commas, the currency sign, sign control
Synonym for object deck or text deck.
characters, and other editing characters. A
numeric-edited data item can be * object of entry
represented in usage DISPLAY or usage A set of operands and reserved words,
NATIONAL. within a DATA DIVISION entry of a
COBOL program, that immediately
* numeric function
follows the subject of the entry.
A function whose class and category are
numeric but which for some possible * object program
evaluation does not satisfy the A set or group of executable machine
requirements of integer functions. language instructions and other material
designed to interact with data to provide
* numeric literal
problem solutions. In this context, an
A literal composed of one or more
object program is generally the machine
numeric characters. It can contain either a
language result of the operation of a
decimal point, or an algebraic sign, or
COBOL compiler on a source program or
both. The decimal point must not be the
on the methods of an object-oriented class
rightmost character. The algebraic sign, if
definition. Where there is no danger of
present, must be the leftmost character.
ambiguity, the word 'program' alone can
be used in place of the phrase 'object
O
program'.
object
object reference
An entity that has state (its data values)
A data item that can contain the
and operations (its methods). An object is
information needed to invoke or refer to
a way to encapsulate state and behavior.
an object. An object reference is defined in
object code COBOL with the OBJECT REFERENCE
Output from a compiler or assembler that phrase in the USAGE clause of a data
is itself executable machine code or is description entry. See also typed object
suitable for processing to produce reference and universal object reference.
executable machine code.
* object time
* object-computer The time at which an object program is
The name of an ENVIRONMENT executed. The term is synonymous with
DIVISION paragraph in which the the terms execution time and run time.
computer environment, within which the
* obsolete element
program is executed, is described.
A COBOL language element in the 85
object deck COBOL Standard that was deleted from
A portion of an object program suitable as the 2002 COBOL Standard.
input to a linkage editor. The term is
ODO object
synonymous with object module and text
In the example below,
deck.

Glossary 673
 WORKING-STORAGE SECTION. OPEN statement, with the OUTPUT or
01 TABLE-1. EXTEND phrase specified, for that file
05 X PIC S9.
and before the execution of a CLOSE
05 Y OCCURS 3 TIMES
DEPENDING ON X PIC X. statement without the REEL or UNIT
phrase for that file.
X is the object of the OCCURS * output procedure
DEPENDING ON clause (ODO object). A set of statements to which control is
The value of the ODO object determines given during execution of a format 1
how many of the ODO subject appear in SORT statement after the sort function is
the table. completed, or during execution of a
ODO subject MERGE statement after the merge
In the example above, Y is the subject of function reaches a point at which it can
the OCCURS DEPENDING ON clause select the next record in merged order
(ODO subject). The number of Y ODO when requested.
subjects that appear in the table depends overflow condition
on the value of X. A condition that occurs when a portion of
* open mode the result of an operation exceeds the
The state of a file after execution of an capacity of the intended unit of storage.
OPEN statement for that file and before overload
the execution of a CLOSE statement To define a method with the same name
without the REEL or UNIT phrase for that as another method available in the same
file. The particular open mode is specified class, but with a different signature. See
in the OPEN statement as either INPUT, also signature.
OUTPUT, I-O, or EXTEND.
override
operand To redefine (in a subclass) an instance
Data that is operated upon. In this method inherited from a parent class.
document, any lowercase word (or words)
that appears in a statement or entry P
format is an operand in that it is a
reference to the data identified by that package
word (or words). In Java, a group of related classes that can
be imported individually or as a whole.
* operational sign
An algebraic sign, associated with a packed decimal item
numeric data item or a numeric literal, to See internal decimal item.
indicate whether its value is positive or padding character
negative. An alphanumeric or national character or
optional file literal used to fill the unused character
A file that is declared as being not positions in a physical record.
necessarily available each time the object page A vertical division of output data
program is executed. representing a physical separation of such
* optional word data, the separation being based on
A reserved word that is included in a internal logical requirements or external
specific format only to improve the characteristics of the output medium.
readability of the language and whose * page body
presence is optional to the user when the That part of the logical page in which
format in which the word appears is used lines can be written or spaced.
in a source unit.
* paragraph
* output file In the PROCEDURE DIVISION, a
A file that is opened in either the paragraph-name followed by a separator
OUTPUT mode or EXTEND mode. period and by zero, one, or more
* output mode sentences. In the identification and
The state of a file after execution of an

674 Enterprise COBOL for z/OS, V6.1 Language Reference

 ENVIRONMENT DIVISION, a paragraph methods. Thus, instance data is private to
header followed by zero, one, or more instance methods defined in the same
entries. class definition; factory data is private to
factory methods defined in the same class
* paragraph header
definition.
A reserved word, followed by the
separator period, that indicates the * procedure
beginning of a paragraph. A paragraph or group of logically
successive paragraphs, or a section or
* paragraph-name
group of logically successive sections,
A user-defined word that identifies and
within the PROCEDURE DIVISION.
begins a paragraph in the PROCEDURE
DIVISION. * procedure branching statement
A statement that causes the explicit
password
transfer of control to a statement other
A unique string of characters that a
than the next executable statement in the
program, computer operator, or user must
sequence in which the statements are
supply to meet security requirements
written in the source unit. The procedure
before gaining access to data.
branching statements are: ALTER, CALL,
* phrase EXIT, EXIT PROGRAM, GO TO, MERGE
An ordered set of one or more (with the OUTPUT PROCEDURE phrase),
consecutive COBOL character-strings that PERFORM, SORT (with the INPUT
form a portion of a COBOL procedural PROCEDURE or OUTPUT PROCEDURE
statement or of a COBOL clause. phrase), and XML PARSE.
* physical record PROCEDURE DIVISION
See block. The division of a program or method that
contains procedural statements for
pointer data item
performing operations at run time.
A data item in which address values can
be stored. Data items are explicitly * procedure-name
defined as pointers with the USAGE IS A user-defined word that is used to name
POINTER clause. ADDRESS OF special a paragraph or section in the
registers are implicitly defined as pointer PROCEDURE DIVISION. It consists of a
data items. Pointer data items can be paragraph-name (which can be qualified)
compared for equality or moved to other or a section-name.
pointer data items.
procedure pointer
portability A data item in which a pointer to an
The ability to transfer an application from entry point can be stored. A data item
one application platform to another with defined with the USAGE IS
relatively few changes to the source code. PROCEDURE-POINTER clause contains
the address of a procedure entry point.
* prime record key
A key whose contents uniquely identify a program-name
record within an indexed file. In the IDENTIFICATION DIVISION and
the end program marker, a user-defined
* priority-number
word or an alphanumeric literal that
A user-defined word that classifies
identifies a COBOL source program.
sections in the PROCEDURE DIVISION
for purposes of segmentation. * pseudo-text
Priority-numbers can contain only the A sequence of text words, comment lines,
characters '0','1', . . ., '9'. inline comments, or the separator space in
a source unit or COBOL library bounded
private
by, but not including, pseudo-text
In object orientation, data that is
delimiters.
accessible only by methods of the class
that defines the data. Instance data is * pseudo-text delimiter
accessible only by instance methods; Two contiguous equal sign characters (==)
factory data is accessible only by factory used to delimit pseudo-text.

Glossary 675
* punctuation character * record
A character that belongs to the following See logical record.
set:
* record area
Character Meaning A storage area allocated for the purpose
of processing the record described in a
, Comma
record description entry in the FILE
; Semicolon SECTION of the DATA DIVISION. In the
: Colon FILE SECTION, the current number of
character positions in the record area is
. Period (full stop)
determined by the explicit or implicit
" Quotation mark RECORD clause.
( Left parenthesis * record description
) Right parenthesis See record description entry.
Space * record description entry
= Equal sign The total set of data description entries
associated with a particular record. The
term is synonymous with record
Q description.
QSAM (Queued Sequential Access Method) record key
An extended version of the basic A key whose contents identify a record
sequential access method (BSAM). When within an indexed file.
this method is used, a queue is formed of * record-name
input data blocks that are awaiting A user-defined word that names a record
processing or of output data blocks that described in a record description entry in
have been processed and are awaiting the DATA DIVISION of a COBOL
transfer to auxiliary storage or to an program.
output device.
* record number
* qualified data-name The ordinal number of a record in the file
An identifier that is composed of a whose organization is sequential.
data-name followed by one or more sets
of either of the connectives OF and IN recording mode
followed by a data-name qualifier. The format of the logical records in a file.
Recording mode can be F (fixed-length), V
* qualifier (variable-length), S (spanned), or U
(1) A data-name or a name associated (undefined).
with a level indicator which is used in a
reference either together with another recursion
data-name which is the name of an item A program calling itself or being directly
that is subordinate to the qualifier or or indirectly called by a one of its called
together with a condition-name. (2) A programs.
section-name that is used in a reference recursively capable
together with a paragraph-name specified A program is recursively capable (can be
in that section. (3) A library-name that is called recursively) if the RECURSIVE
used in a reference together with a clause is on the PROGRAM-ID statement.
text-name associated with that library.
reel A discrete portion of a storage medium
R that contains part of a file, all of a file, or
any number of files. The term is
* random access synonymous with unit and volume.
An access mode in which the
program-specified value of a key data reentrant
item identifies the logical record that is The attribute of a program or routine that
obtained from, deleted from, or placed allows more than one user to share a
into a relative or indexed file. single copy of a program object.

676 Enterprise COBOL for z/OS, V6.1 Language Reference

* reference format Character Meaning
A format that provides a standard method
IS LESS THAN Less than
for writing COBOL source code.
IS < Less than
reference modification
A method of defining a new data item by IS NOT LESS THAN Not less than
specifying the leftmost character position IS NOT < Not less than
and length relative to the leftmost IS EQUAL TO Equal to
character position of another data item.
IS = Equal to
* reference-modifier
IS NOT EQUAL TO Not equal to
A syntactically correct combination of
character-strings and separators that IS NOT = Not equal to
defines a unique data item. It includes a IS GREATER THAN OR EQUAL Greater than or equal to
delimiting left parenthesis separator, the TO
leftmost character position, a colon
IS >= Greater than or equal to
separator, optionally a length, and a
delimiting right parenthesis separator. IS LESS THAN OR EQUAL TO Less than or equal to

* relation IS <= Less than or equal to

See relational operator or relation condition.
* relative file
* relation character
A file with relative organization.
A character that belongs to the following
set: * relative key
A key whose contents identify a logical
Character Meaning record in a relative file.
> Greater than
* relative organization
< Less than The permanent logical file structure in
= Equal to which each record is uniquely identified
by an integer value greater than zero,
which specifies the record's logical ordinal
* relation condition position in the file.
The proposition, for which a truth value
can be determined, that the value of an * relative record number
arithmetic expression, data item, The ordinal number of a record in a file
alphanumeric literal, or index-name has a whose organization is relative. This
specific relationship to the value of number is treated as a numeric literal that
another arithmetic expression, data item, is an integer.
alphanumeric literal, or index name. See * reserved word
also relational operator. A COBOL word specified in the list of
* relational operator words that can be used in a COBOL
A reserved word, a relation character, a source unit, but that must not appear in
group of consecutive reserved words, or a the program as user-defined words or
group of consecutive reserved words and system-names.
relation characters used in the * resource
construction of a relation condition. The A facility or service, controlled by the
permissible operators and their meanings operating system, that can be used by an
are: executing program.
Character Meaning * resultant identifier
IS GREATER THAN Greater than A user-defined data item that is to contain
the result of an arithmetic operation.
IS > Greater than
IS NOT GREATER THAN Not greater than routine
A set of statements in a COBOL program
IS NOT > Not greater than that causes the computer to perform an
operation or series of related operations.

Glossary 677
* routine-name * sentence
A user-defined word that identifies a A sequence of one or more statements, the
procedure written in a language other last of which is terminated by a separator
than COBOL. period.
* run time * separately compiled program
The time at which an object program is A program that, together with its
executed. The term is synonymous with contained programs, is compiled
object time. separately from all other programs.
runtime environment * separator
The environment in which a COBOL A character or two or more contiguous
program executes. characters used to delimit
character-strings.
* run unit
A stand-alone object program, or several * separator comma
object programs, that interact via COBOL A comma (,) followed by a space used to
CALL or INVOKE statements and delimit character-strings.
function at run time as an entity.
* separator period
A period (.) followed by a space used to
S
delimit character-strings.
SBCS (Single Byte Character Set)
* separator semicolon
See Single Byte Character Set (SBCS).
A semicolon (;) followed by a space used
scope terminator to delimit character-strings.
A COBOL reserved word that marks the
* sequential access
end of certain PROCEDURE DIVISION
An access mode in which logical records
statements. It can be either explicit
are obtained from or placed into a file in
(END-ADD, for example) or implicit (a
a consecutive predecessor-to-successor
separator period, for example).
logical record sequence determined by the
* section order of records in the file.
A set of zero, one or more paragraphs or
* sequential file
entities, called a section body, the first of
A file with sequential organization.
which is preceded by a section header.
Each section consists of the section header * sequential organization
and the related section body. The permanent logical file structure in
which a record is identified by a
* section header
predecessor-successor relationship
A combination of words followed by a
established when the record is placed into
separator period that indicates the
the file.
beginning of a section. For example,
WORKING-STORAGE SECTION. serial search
A search in which the members of a set
* section-name
are consecutively examined, beginning
A user-defined word that names a section
with the first member and ending with
in the PROCEDURE DIVISION.
the last.
segmentation
* 77-level-description-entry
A feature of Enterprise COBOL that is
A data description entry that describes a
based on the 85 COBOL Standard
noncontiguous data item with the
segmentation module. The segmentation
level-number 77.
feature uses priority-numbers in section
headers to assign sections to fixed * sign condition
segments or independent segments. The proposition, for which a truth value
Segment classification affects whether can be determined, that the algebraic
procedures contained in a segment receive value of a data item or an arithmetic
control in initial state or last-used state. expression is either less than, greater than,
or equal to zero.

678 Enterprise COBOL for z/OS, V6.1 Language Reference

signature Character Meaning
The name of a method and the number
+ Plus sign
and types of its formal parameters.
- Minus sign (hyphen)
* simple condition
Any single condition chosen from the set: * Asterisk

v Relation condition / Slant (forward slash)

v Class condition = Equal sign
v Condition-name condition $ Currency sign
v Switch-status condition , Comma (decimal point)
v Sign condition ; Semicolon
Single Byte Character Set (SBCS) . Period (decimal point, full stop)
A set of characters in which each " Quotation mark
character is represented by a single byte.
See also EBCDIC (Extended Binary-Coded ’ Apostrophe
Decimal Interchange Code). ( Left parenthesis

slack bytes (within records) ) Right parenthesis

Bytes inserted by the compiler between > Greater than
data items to ensure correct alignment of
< Less than
some elementary data items. Slack bytes
contain no meaningful data. The : Colon
SYNCHRONIZED clause instructs the _ Underscore
compiler to insert slack bytes when they
are needed for proper alignment.
SPECIAL-NAMES
slack bytes (between records) The name of an ENVIRONMENT
Bytes inserted by the programmer DIVISION paragraph in which
between blocked logical records of a file, environment-names are related to
to ensure correct alignment of some user-specified mnemonic-names.
elementary data items. In some cases,
* special registers
slack bytes between records improve
Certain compiler-generated storage areas
performance for records processed in a
whose primary use is to store information
buffer.
produced in conjunction with the use of a
* sort file specific COBOL feature.
A collection of records to be sorted by a
* statement
format 1 SORT statement. The sort file is
A COBOL language construct that
created and can be used by the sort
specifies one or more actions to be
function only.
performed. Statements can be procedural
* sort-merge file description entry statements or compiler-directing
An entry in the FILE SECTION of the statements. An example of a procedural
DATA DIVISION that is composed of the statement is the ADD statement; an
level indicator SD, followed by a example of a compiler-directing statement
file-name, and then followed clauses that is the USE statement.
describe the attributes of the sort-merge
structured programming
file.
A technique for organizing and coding a
source unit computer program in which the program
A unit of COBOL source code that can be comprises a hierarchy of segments, each
separately compiled: a program or a class segment having a single entry point and a
definition. Also known as compilation unit. single exit point. Control is passed
downward through the structure without
special character
unconditional branches to higher levels of
A character that belongs to the following
the hierarchy.
set:

Glossary 679
subclass switch-status condition
A class that inherits from another class. The proposition, for which a truth value
When two classes in an inheritance can be determined, that an UPSI switch,
relationship are considered together, the capable of being set to an 'on' or 'off'
subclass is the inheriting class; the status, has been set to a specific status.
superclass is the inherited class.
* symbolic-character
A subclass is also referred to as a child A user-defined word that specifies a
class or derived class. user-defined figurative constant.
* subject of entry syntax
An operand or reserved word that (1) The relationship among characters or
appears immediately following the level groups of characters, independent of their
indicator or the level-number in a DATA meanings or the manner of their
DIVISION entry. interpretation and use. (2) The structure
of expressions in a language. (3) The rules
* subprogram
governing the structure of a language. (4)
Any called program.
The relationship among symbols. (5) The
* subscript rules for the construction of a statement.
An occurrence number represented by
* system-name
either an integer, a data-name optionally
A COBOL word that is used to
followed by an integer with the operator
communicate with the operating
+ or -, or an index-name optionally
environment.
followed by an integer with the operator
+ or -, that identifies a particular element
T
in a table. A subscript can be the word
ALL when the subscripted identifier is * table
used as a function argument for a A set of logically consecutive items of
function allowing a variable number of data that are defined in the DATA
arguments. DIVISION by means of the OCCURS
clause.
* subscripted data-name
An identifier that is composed of a * table element
data-name followed by one or more A data item that belongs to the set of
subscripts enclosed in parentheses. repeated items comprising a table.
superclass text deck
A class that is inherited by another class. Synonym for object deck or object module.
When two classes in an inheritance
* text-name
relationship are considered together, the
A user-defined word that identifies library
subclass is the inheriting class; the
text.
superclass is the inherited class.
* text word
The superclass is also referred to as the
A character or a sequence of contiguous
parent class.
characters between margin A and margin
surrogate pair R in COBOL source code. A text word can
In the UTF-16 format of Unicode, a pair be:
of encoding units that together represents v A separator, except for: space; a
a single Unicode graphic character. The pseudo-text delimiter; and the opening
first unit of the pair is called a high and closing delimiters for alphanumeric
surrogate and the second a low surrogate. literals. The right parenthesis and left
The code value of a high surrogate is in parenthesis characters, regardless of
the range X'D800' through X'DBFF'. The context within the library, source unit,
code value of a low surrogate is in the or pseudo-text, are always considered
range X'DC00' through X'DFFF'. Surrogate text words.
pairs provide for more characters than the
v A literal including, in the case of
65,536 characters that fit in the Unicode
alphanumeric literals, the opening
16-bit coded character set.

680 Enterprise COBOL for z/OS, V6.1 Language Reference

 quotation mark and the closing that does not result in the execution of all
quotation mark that bound the literal. the operations specified by that statement.
v Any other sequence of contiguous UPSI switch
COBOL characters except comment A program switch that performs the
lines and the word 'COPY', bounded by functions of a hardware switch. Eight are
separators, that are neither a separator provided: UPSI-0 through UPSI-7.
nor a literal.
* user-defined word
trailer-label A COBOL word that must be supplied by
(1) A file or data set label that follows the the user to satisfy the format of a clause
data records on a unit of recording or statement. The maximum length of a
medium. (2) Synonym for end-of-file user-defined word is 30 bytes.
label.
* truth value V
The representation of the result of the * variable
evaluation of a condition in terms of one A data item whose value can be changed
of two values: true or false. by the application at run time.
typed object reference variable-length item
An object reference data item that can A group item that contains a table
reference only an object of a specified described with the DEPENDING phrase
class or one of its subclasses. of the OCCURS clause.

U * variable-length record
A record associated with a file whose file
* unary operator description or sort-merge description
A plus (+) or a minus (-) sign that entry permits records to contain a varying
precedes a variable or a left parenthesis in number of character positions.
an arithmetic expression and that has the
effect of multiplying the expression by +1 * variable-occurrence data item
or -1, respectively. A variable-occurrence data item is a table
element which is repeated a variable
unbounded table number of times. Such an item must
A table with OCCURS integer-1 to contain an OCCURS DEPENDING ON
UNBOUNDED instead of specifying integer-2 clause in its data description entry, or be
as the upper bound. subordinate to such an item.
Unicode variably located group
A coded character set that encodes all the A group item following, and not
characters required for the written subordinate to, a variable-length table in
expression of any of the languages of the the same level-01 record. A variably
modern world. There are multiple formats located group can be an alphanumeric
for representing Unicode, including group or a national group.
UTF-8, UTF-16, and UTF-32. Enterprise
COBOL supports Unicode using UTF-16 variably located item
big-endian format as the representation A data item following, and not
for the national data type. subordinate to, a variable-length table in
the same level-01 record.
unit A module of direct access, the dimensions
of which are determined by IBM. volume
A module of external storage. For tape
universal object reference devices it is a reel; for direct-access
An object reference data item that can devices it is a unit.
contain a reference to an object of any
class. volume switch procedures
System procedures executed automatically
* unsuccessful execution when the end of a unit or reel has been
The attempted execution of a statement reached before end-of-file has been
reached.

Glossary 681
W XML document
A data object that is well formed as
white space characters
defined by the W3C XML specification.
Characters that introduce space into a
document. They are: XML namespace
v Space A mechanism, defined by the W3C XML
Namespace specifications, that limits the
v Horizontal tabulation
scope of a collection of element names
v Carriage return and attribute names. A uniquely chosen
v Line feed XML namespace ensures the unique
v Next line identity of an element name or attribute
name across multiple XML documents or
as named in the Unicode Standard. multiple contexts within an XML
* word document.
A character-string that forms a XML schema
user-defined word, a system-name, a A mechanism, defined by the W3C, for
reserved word, or a function-name. describing and constraining the structure
* WORKING-STORAGE SECTION and content of XML documents. An XML
The section of the DATA DIVISION that schema, which is itself expressed in XML,
describes WORKING-STORAGE data effectively defines a class of XML
items, composed either of noncontiguous documents of a given type, for example,
items or WORKING-STORAGE records, purchase orders.
or both.
Z
X zoned decimal data item
XML Extensible Markup Language. A A data item described by a PICTURE
metalanguage for defining markup character-string that contains valid
languages that was derived from and is a combinations of picture symbols 9, S, P,
subset of SGML. XML omits the more and V. A zoned decimal data item is an
complex and less-used parts of SGML and external decimal data item that has usage
makes it much easier to: DISPLAY. See external decimal data item
and national decimal data item.
v Write applications to handle document
types
#
v Author and manage structured
information 85 COBOL Standard
The COBOL language defined by the
v Transmit and share structured
ANSI and ISO standards identified in
information across diverse computing
Appendix H, “Industry specifications,” on
systems
page 643.
XML is being developed under the
2002 COBOL Standard
auspices of the World Wide Web
The COBOL language defined by the
Consortium (W3C).
following standards:
XML data v INCITS/ISO/IEC 1989-2002,
Data that is organized into a hierarchical Information Technology - Programming
structure with XML elements. The data Languages - COBOL
definitions are defined in XML element
v ISO/IEC 1989:2002, Information
type declarations.
technology -- Programming languages
XML declaration -- COBOL
XML text that specifies characteristics of
the XML document such as the version of
XML being used and the encoding of the
document.

682 Enterprise COBOL for z/OS, V6.1 Language Reference

 List of resources
v Checkpoint/Restart
Enterprise COBOL for z/OS
v Macro Instructions for Data Sets
COBOL for z/OS publications v Using Data Sets
You can find the following publications in the v Utilities
Enterprise COBOL for z/OS library:
z/OS ISPF
| v Customization Guide, SC27-8712
v Dialog Developer's Guide and Reference
| v Language Reference, SC27-8713
v User's Guide Vol I
| v Programming Guide, SC27-8714
v User's Guide Vol II
| v Migration Guide, GC27-8715
| v Program Directory, GI13-4526 z/OS Language Environment
| v Licensed Program Specifications, GI13-4532 v Concepts Guide
v Customization
Softcopy publications
v Debugging Guide
The following collection kits contain Enterprise v Programming Guide
COBOL and other product publications. You can v Programming Reference
find them at http://www.ibm.com/e-business/
v Run-Time Messages
linkweb/publications/servlet/pbi.wss.
v Run-Time Application Migration Guide
v z/OS Software Products Collection
v Writing Interlanguage Communication Applications
v z/OS and Software Products DVD Collection
z/OS MVS
Support
v JCL Reference
If you have a problem using Enterprise COBOL v JCL User's Guide
for z/OS, see the following site that provides v Program Management: User's Guide and Reference
up-to-date support information:
v System Commands
https://www.ibm.com/support/home/product/
B984385H82239E03/Enterprise_COBOL_for_z/OS. v z/OS Unicode Services User's Guide and Reference
v z/OS XML System Services User's Guide and
Reference
Related publications
z/OS library publications z/OS TSO/E
v Command Reference
You can find the following publications in the v Primer
z/OS Internet Library.
v User's Guide
Run-Time Library Extensions
z/OS UNIX System Services
v Common Debug Architecture Library Reference
v Command Reference
v Common Debug Architecture User’s Guide
v Programming: Assembler Callable Services
v DWARF/ELF Extensions Library Reference Reference
v User's Guide
z/Architecture®
v Principles of Operation CICS Transaction Server for z/OS
z/OS DFSMS You can find the following publications in the
v Access Method Services for Catalogs CICS Library:

© Copyright IBM Corp. 1991, 2017 683

v Application Programming Guide v Namespaces in XML 1.0, www.w3.org/TR/xml-
v Application Programming Reference names/
v Customization Guide v Namespaces in XML 1.1, www.w3.org/TR/xml-
names11/
v External Interfaces Guide
v XML specification, www.w3.org/TR/xml/
Debug Tool

You can find the following publications in the

Debug Tool Library:
v Reference and Messages
v User's Guide

You can find the following publications by

searching their publication numbers in the IBM
Publications Center.

COBOL Report Writer Precompiler

v Programmer's Manual, SC26-4301

Softcopy publications for z/OS

The following collection kit contains z/OS and

related product publications:
v z/OS CD Collection Kit, SK3T-4269

Java
v IBM SDK for Java - Tools Documentation,
publib.boulder.ibm.com/infocenter/javasdk/
tools/index.jsp
v The Java 2 Enterprise Edition Developer's Guide,
download.oracle.com/javaee/1.2.1/devguide/
html/DevGuideTOC.html
v Java 2 SDK, Standard Edition Documentation,
download.oracle.com/javase/1.4.2/docs/
v Java 2 on z/OS, www.ibm.com/servers/eserver/
zseries/software/java/
v The Java EE 5 Tutorial, download.oracle.com/
javaee/5/tutorial/doc/
v The Java Language Specification, Third Edition, by
Gosling et al., java.sun.com/docs/books/jls/
v The Java Native Interface, download.oracle.com/
javase/1.5.0/docs/guide/jni/

Unicode and character representation

v Unicode, www.unicode.org/
v Character Data Representation Architecture
Reference and Registry, SC09-2190

XML
v Extensible Markup Language (XML),
www.w3.org/XML/

684 Enterprise COBOL for z/OS, V6.1 Language Reference

Index
Special characters A ALL literal
figurative constant 15
- (minus) A symbol in PICTURE clause 204 STOP statement 461
insertion character 217, 218 abbreviated combined relation STRING statement 463
SIGN clause 227 condition 657 ALL phrase
symbol in PICTURE clause 208 examples 284 INSPECT statement 365, 366
, (comma) using parentheses in 282 SEARCH statement 438
insertion character 216 abend, definition 657 UNSTRING statement 472
symbol in PICTURE clause 206, 208 ACCEPT statement ALL subscripting 75, 514
: (colon) description and format 304 ALLOCATE statement 310
description 50 FROM phrase 304 description and format 310
required use of 570 mnemonic-name in 304 UNBOUNDED tables 312
/ (slash) overlapping operands, unpredictable ALPHABET clause 119
insertion character 216 results 294 alphabet-name 11, 65
symbol in PICTURE clause 208 system information transfer 306 description 119
(/ or *>) comment line 61 access mode MERGE statement 390
(period) symbol in PICTURE clause 206 description 142 PROGRAM COLLATING SEQUENCE
$ (default currency symbol) dynamic clause 115
in PICTURE clause 208 DELETE statement 334 SORT statement 453
insertion character 217, 218 description 143 alphabetic category 168
symbol in PICTURE clause 206 READ statement 425 alphabetic character in ACCEPT 304
* symbol in PICTURE clause 206 DYNAMIC 143 ALPHABETIC class test 265
*> (floating comment indicator) 61 random alphabetic function arguments 512
*CBL (*CONTROL) statement 560 DELETE statement 334 alphabetic items
*CONTROL (*CBL) statement 560 description 143 alignment rules 170
> (greater than) 269 READ statement 425 elementary move rules 395
>> (compiler directive indicator) 13 RANDOM 142 how to define 209
CALLINTERFACE directive 587 sequential PICTURE clause 209
compiler directive 587 DELETE statement 333 ALPHABETIC-LOWER class test 265
INLINE directive 588 description 143 ALPHABETIC-UPPER class test 265
>= (greater than or equal to) 269 READ statement 423 alphanumeric category 168
< (less than) 269 SEQUENTIAL 142 alphanumeric comparisons 272
<= (less than or equal to) 269 ACCESS MODE clause 142 alphanumeric function arguments 513
+ (plus) accessibility alphanumeric functions 510, 511
insertion character 217, 218, 219 keyboard navigation 651 alphanumeric group items 165
SIGN clause 227 of Enterprise COBOL for z/OS 651 alphanumeric items
symbol in PICTURE clause 208 of this information 652 alignment rules 170
= (equal) 269 using z/OS 651 elementary move rules 396
accessibility features for this how to define 211
product 651 PICTURE clause 211
Numerics ACOS function 519
ADD statement
alphanumeric literals 37, 40
0 in hexadecimal notation 40
common phrases 289 with DBCS characters 38
insertion character 216
CORRESPONDING phrase 310 alphanumeric operands, comparing 272
symbol in PICTURE clause 208
description and format 308 alphanumeric-edited category 168
0 symbol in PICTURE clause 205
END-ADD phrase 310 alphanumeric-edited items
2002 COBOL Standard features 645
GIVING phrase 309 alignment rules 170
66, RENAMES data description
NOT ON SIZE ERROR phrase 310 elementary move rules 396
entry 224
ON SIZE ERROR phrase 310 how to define 212
66, renames level-number 165
ROUNDED phrase 310 PICTURE clause 212
77, elementary item level-number 165
ADDRESS OF special register 17 ALSO phrase
88, condition-name data description
ADV compiler option 481 ALPHABET clause 119
entry 190
advanced function printing 485 EVALUATE statement 345
88, conditional variable level
ADVANCING phrase 480 ALTER statement
number 165
AFTER phrase description and format 314
9 symbol in PICTURE clause 205
INSPECT statement 369 GO TO statement and 355
9, symbol in PICTURE clause 208
PERFORM statement 412 segmentation considerations 315
with REPLACING 366 altered GO TO statement 355
with TALLYING 365 alternate key data item 145
WRITE statement 480 ALTERNATE RECORD KEY clause 145
alignment rules 170 DUPLICATES phrase 146

© Copyright IBM Corp. 1991, 2017 685

AND logical operator 279
ANNUITY function 520
asterisk (*) (continued)
insertion character 219
C
ANSI COBOL standards 643 AT END phrase call convention 587, 588
ANSI X3.22 639 READ statement 421 CALL statement
ANSI X3.27 639 RETURN statement 430 CANCEL statement and 324
ANSI X3.4 639 SEARCH statement 435 description and format 316
APPLY WRITE-ONLY clause 154 SEARCH statement (binary LINKAGE SECTION 258
Area A (cols. 8-11) 56 search) 438 ON OVERFLOW phrase 316
Area B (cols. 12-72) 58 SEARCH statement (serial PROCEDURE DIVISION header 255,
arguments 512 search) 435 258
arithmetic expression AT END-OF-PAGE phrases 481 program termination 316
COMPUTE statement 330 at-end condition subprogram linkage 316
description 261 READ statement 424 transfer of control 84
EVALUATE statement 345 RETURN statement 430 USING phrase 258
relation condition 268 ATAN function 521 called and calling programs,
arithmetic operators 13 ATTRIBUTE-CHARACTER XML description 316
description 262 event 26 CALLINTERFACE directive 587
permissible symbol pairs 263 ATTRIBUTE-CHARACTERS XML CANCEL statement 324
arithmetic statements event 26 carriage control character 481
ADD 308 ATTRIBUTE-NAME XML event 26 category
common phrases 289 ATTRIBUTE-NATIONAL-CHARACTER of group items 165
COMPUTE 330 XML event 26 relationship to classes of data 166
DIVIDE 338 ATTRIBUTES phrase 490 relationship to usages of data 166
list of 293 AUTHOR paragraph category descriptions 168
multiple results 294 description 109 category of data 166
MULTIPLY 400 format 101 alphabetic 168, 209
operands 293 alphanumeric 168, 211
programming notes 294 alphanumeric-edited 168, 212
DBCS 168, 212
SUBTRACT 467
ASCENDING KEY phrase
B external floating-point 169
B internal floating-point 169
collating sequence 198
insertion character 216 national 169, 213
description 389
symbol in PICTURE clause 204 national-edited 169, 213
MERGE statement 389
basic character set 3 numeric 169, 210
OCCURS clause 197
basic PERFORM statement numeric-edited 170, 211
SORT statement 449, 451
format and description 410 category of functions 167
ASCII
BASIS statement 559 category of literals 167
collating sequence 612
basis-name 64 CBL (PROCESS) statement 560
specifying in SPECIAL-NAMES
batch compile 88 CCSID 5
paragraph 119
BEFORE phrase CHAR function 521
ASCII considerations 639
INSPECT statement 369 character code set, specifying 119
ASSIGN clause 640
PERFORM statement 412 character encoding unit 5
CODE-SET clause 641
with REPLACING 366 character sets 5
data description entries 641
with TALLYING 365 character-strings 9
DATA DIVISION 640
WRITE statement 480 COBOL words 9
ENVIRONMENT DIVISION 639
big-endian 5 representation in PICTURE
I-O-CONTROL paragraph 640
binary arithmetic operators 262 clause 208
OBJECT-COMPUTER paragraph 639
binary data item, DISPLAY size determination 171
PROCEDURE DIVISION 641
statement 335 CHARACTERS BY phrase 366
PROGRAM COLLATING SEQUENCE
BINARY phrase in USAGE clause 235 CHARACTERS phrase
clause 639
binary search 438 BLOCK CONTAINS clause 179
SPECIAL-NAMES paragraph 639
blank lines 63 INSPECT statement 365
ASCII standard 643
BLANK WHEN ZERO clause MEMORY SIZE clause 115
ASIN function 521
description and format 192 USAGE clause and 179
ASSIGN clause
INDEX phrase in USAGE clause 238 characters, valid in COBOL program 3
ASCII considerations 640
BLOCK CONTAINS clause checkpoint processing, RERUN
description 134
description 179 clause 150
format 130
format 173 CICS
SELECT clause and 134
branching restrictions
assigning index values 441
GO TO statement 354 parsing with validation using
assignment-name 12, 134
out-of-line PERFORM statement 410 FILE 501
ASSIGN clause 134
BY CONTENT phrase class (object-oriented) 93
environment variable 134
CALL statement 319 class (of data)
RECORD DELIMITER clause 142
BY REFERENCE phrase of data items 166
RERUN clause 150
CALL statement 319 of figurative constants 166
assistive technologies 652
BY VALUE phrase of functions 166
asterisk (*)
CALL statement 320 of group items 165
comment line 61
INVOKE statement 374 of literals 166

686 Enterprise COBOL for z/OS, V6.1 Language Reference

CLASS clause 122 combined condition (continued) compiler-directing statements (continued)
class condition 264 logical operators and evaluation USE 582
class definition results 281 complex conditions
class procedure division 253 order of evaluation 281 abbreviated combined relation 282
CLASS-ID paragraph 107 permissible element sequences 280 combined condition 280
configuration section 113 comma (,) description 279
description 93 DECIMAL-POINT IS COMMA negated simple 279
effect of SELF and SUPER 372 clause 124 complex OCCURS DEPENDING ON
factory procedure division 253 insertion character 216 (CODO) 203
IDENTIFICATION DIVISION 102 comment lines composite of operands 293
object procedure division 253 description 60 COMPUTATIONAL data items 235
requirements for indexed tables 199 in IDENTIFICATION DIVISION 109 COMPUTATIONAL phrases in USAGE
class identification division 101 in library text 567 clause 236
class IDENTIFICATION DIVISION 107 in source text 579 COMPUTE statement
class procedure division 253 COMMENT XML event 26 common phrases 291
CLASS-ID paragraph 107 comments 46 description and format 330
class-name 11, 12, 65 COMMON clause 105 computer-name 12, 114, 115
class-name class test 265 common processing facilities 295 condition
class-name, OO 65 COMP-1 through COMP-5 data abbreviated combined relation 282
clauses 55 items 236 class 264
definition 54 comparison tables 269 combined 280
syntactical hierarchy 53 comparison types 269 complex 279
CLOSE statement comparisons condition-name 266
format and description 326 alphanumeric operands 272 EVALUATE statement 345
COBOL cycle, INSPECT statement 370 IF statement 356
class definition 93 DBCS operands 273 negated simple 279
language structure 3 function pointer operands 277 PERFORM UNTIL statement 412
method definition 97 group operands 275 relation 268
program structure 87 in EVALUATE statement 346 SEARCH statement (binary
reference format 55 index data items 275 search) 438
COBOL classes 93 index-names 275 SEARCH statement (serial
COBOL objects 93 national operands 273 search) 437
COBOL standards 643 numeric operands 274 sign 278
COBOL words 9 object reference operands 277 simple 264
with DBCS characters 9 procedure pointer operands 277 switch-status 278
with single-byte characters 9 rules for COPY statement 566 condition-name 11, 64, 74
code page names 5 compiler directive 587 and conditional variable 190
code pages 5 compiler limits 605 description and format 266
CODE-SET clause compiler options 560 rules for values 245
ALPHABET clause and 119 ADV 481 SEARCH statement 439
ASCII considerations 641 CODEPAGE 5 SET statement 444
description 187 controlling listing output 560 SPECIAL-NAMES paragraph 119
format 173 NUMPROC 278 switch status condition 119
NATIVE phrase and 187 PGMNAME 324 conditional expressions
CODEPAGE compiler option 5 specifying 560 DBCS operands 273
collating sequence THREAD 199 description 264
ASCENDING/DESCENDING KEY TRUNC 172 index-names and index data
phrase and 198 compiler-directing statements 61, 559 items 275
ASCII 612 *CBL (*CONTROL) 560 order of evaluation of operands 281
EBCDIC 609 *CONTROL (*CBL) 560 parentheses in abbreviated combined
specified in OBJECT-COMPUTER BASIS 559 relation conditions 282
paragraph 115 CBL (PROCESS) 560 conditional statements
specified in SPECIAL-NAMES COPY 562 description 286
paragraph 119 DELETE 572 GO TO statement 354
COLLATING SEQUENCE phrase 115 EJECT 573 IF statement 356
ALPHABET clause 119 ENTER 574 list of 286
MERGE statement 390 INSERT 574 PERFORM statement 412
SORT statement 453 PROCESS (CBL) 560 conditional variable 190
colon character READY TRACE 575 configuration section
description 50 REPLACE 575 description (programs, classes,
required use of 570 RESET TRACE 575 methods) 113
column 7 SERVICE LABEL 580 REPOSITORY paragraph 125
indicator area 58 SERVICE RELOAD 580 SOURCE-COMPUTER
specifying comments 60 SKIP1 580 paragraph 114
combined condition SKIP2 580 SPECIAL-NAMES paragraph 116
description 280 SKIP3 580
evaluation rules 281 TITLE 581

Index 687
conformance rules data category (continued) data manipulation statements
SET...USAGE OBJECT alphanumeric 211 ACCEPT 304
REFERENCE 447 alphanumeric-edited 212 INITIALIZE 358
contained programs 87 DBCS 212 list of 294
CONTENT-CHARACTER XML event 26 national 213 MOVE 393
CONTENT-CHARACTERS XML national-edited 213 overlapping operands 294
event 26 numeric 210 READ 420
CONTENT-NATIONAL-CHARACTER numeric-edited 211 RELEASE 427
XML event 26 data category descriptions 168 RETURN 429
context-sensitive word 637 data conversion, DISPLAY REWRITE 431
continuation statement 335 SET 441
area 55 data description entries STRING 462
lines 58, 60 ASCII considerations 641 UNSTRING 470
CONTINUE statement 332 data description entry 189 WRITE 478
CONTROL statement (*CONTROL) 560 BLANK WHEN ZERO clause 192 data organization
conversion of data, DISPLAY data-name 191 access modes and 143
statement 335 FILLER phrase 191 indexed 140
CONVERTING phrase 368 GLOBAL clause 193 line-sequential 140
COPY libraries 70 indentation and 165 relative 140
COPY statement JUSTIFIED clause 193 sequential 140
comparison rules 566 level-66 format (previously defined DATA RECORDS clause
description and format 562 items) 189 description 184
example 569 level-88 format (condition- format 173
replacement rules 566 names) 190 data relationships
REPLACING phrase 565 level-number description 190 DATA DIVISION 163
SUPPRESS option 565 OCCURS clause 195 data transfer 304
CORRESPONDING (CORR) phrase OCCURS DEPENDING ON (ODO) data units
ADD statement 310 clause 199 factory data 162
description 310 format 199 file data 161
MOVE statement 393 PICTURE clause 203 instance data 162
SUBTRACT statement 468 REDEFINES clause 221 method data 162
with ON SIZE ERROR phrase 292 RENAMES clause 224 overview 161
COS function 522 SIGN clause 226 program data 162
COUNT IN phrase SYNCHRONIZED clause 228 data-item-description-entry
UNSTRING statement 473 USAGE clause 233 LINKAGE SECTION 161
XML GENERATE statement 489 USAGE IS NATIONAL clause data-name
COUNT phrase and 193 data description entry 191
JSON GENERATE statement 382 VALUE clause 242 definition 64
CR (credit) VOLATILE clause 247 data-pointer
insertion character 217 data division USAGE clause 240
symbol in PICTURE clause 206 file description (FD) entry 178 DATE 307
cs (currency symbol) levels of data 163 DATE YYYYMMDD 307
in PICTURE clause 204 LINKAGE SECTION 161 DATE-COMPILED paragraph
CURRENCY SIGN clause LOCAL-STORAGE SECTION 160 description 109
description 122 sort description (SD) entry 178 format 101
Euro currency sign 122 WORKING-STORAGE SECTION 159 DATE-OF-INTEGER function 523
currency sign value 122 DATA DIVISION DATE-TO-YYYYMMDD function 524
currency symbol 208 ASCII considerations 640 DATE-WRITTEN paragraph
in PICTURE clause 206 data description entry 189 description 109
specifying in CURRENCY SIGN data relationships 163 format 101
clause 122 in factory definition 157 DAY 307
currency symbol, default ($) 217 in method definition 157 DAY YYYYDDD 307
CURRENT-DATE function 522 in object definition 157 DAY-OF-INTEGER function 525
customer support 683 in program definition 157 DAY-OF-WEEK 307
DATA DIVISION names 71 DAY-TO-YYYYDDD function 525
data flow DB (debit)
D STRING statement 465
UNSTRING statement 474
insertion character 217
symbol in PICTURE clause 206
data
data item DBCS (Double-Byte Character Set)
alignment 170
characteristics 189 elementary move rules 396
categories 166, 209
description entry definition 159 using in comments 110
classes 166
EXTERNAL clause 192 DBCS category 168
hierarchies used in qualification 163
data item description entry 160 DBCS character set 3
organization 140
data items DBCS characters
signed 172
categories 167 in COBOL words 10
truncation of 171, 194
classes 167 in literals 39
data category
DBCS class condition 265
alphabetic 209

688 Enterprise COBOL for z/OS, V6.1 Language Reference

DBCS comparisons 273 disability 651 encoding units 5
DBCS function arguments 513 display floating-point 215 ENCODING-DECLARATION XML
DBCS items DISPLAY phrase in USAGE clause 237 event 26
alignment rules 170 DISPLAY statement end class marker 57
how to define 212 description and format 335 END DECLARATIVES key word 259
in ACCEPT 304 DISPLAY-OF function 526 end markers 57
PICTURE clause 212 DIVIDE statement end method marker 57
DBCS literals 42 common phrases 291 END PROGRAM 88
in ACCEPT 304 description and format 338 end program marker 57
DBCS notation xv REMAINDER phrase 341 END-ADD phrase 310
de-editing 397 division header END-CALL phrase 323
DEBUG-CONTENTS 18 format, ENVIRONMENT END-IF phrase 356
DEBUG-ITEM special register 17, 618 DIVISION 113 END-INVOKE phrase 376
DEBUG-LINE 18 format, IDENTIFICATION END-JSON phrase
DEBUG-NAME 18 DIVISION 101 JSON GENERATE statement 384
debugging 617 format, PROCEDURE DIVISION 255 END-OF-CDATA-SECTION XML
DEBUGGING declarative 582, 584 specification of 56 event 26
debugging lines 62, 114, 617 DO-UNTIL structure, PERFORM END-OF-DOCUMENT XML event 26
debugging mode statement 412 END-OF-ELEMENT XML event 26
compile-time switch 618 DO-WHILE structure, PERFORM end-of-file processing 326
object-time switch 618 statement 412 END-OF-INPUT XML event 26
DEBUGGING MODE clause 114, 584, DOCUMENT-TYPE-DECLARATION END-OF-PAGE phrases 481
617, 618 XML event 26 END-PERFORM phrase 409
debugging sections 617 Double-Byte Character Set (DBCS) END-SUBSTRACT phrase 469
decimal point (.) 291 PICTURE clause and 212 END-WRITE phrase 483
DECIMAL-POINT IS COMMA clause using in comments 110 END-XML phrase
description 124 DOWN BY phrase, SET statement 442 XML GENERATE statement 494
NUMVAL function 538 DUPLICATES phrase 146 XML PARSE statement 503
NUMVAL-C function 539 SORT statement 452, 453 entries
declarative procedures dynamic access mode definition 54
description and format 259 data organization and 143 syntactical hierarchy 53
PERFORM statement 410 DELETE statement 334 ENTRY statement
USE statement 259 description 143 description and format 343
declaratives READ statement 425 subprogram linkage 343
DEBUGGING 584 environment division
EXCEPTION/ERROR 582 configuration section
precedence rules for nested
programs 584
E ALPHABET clause 119
CURRENCY SIGN clause 122
E symbol in PICTURE clause 205
DECLARATIVES key word OBJECT-COMPUTER
EBCDIC
begin in Area A 57 paragraph 114
code page 1140 609
description 259 REPOSITORY paragraph 125
CODE-SET clause and 187
declaratives section 259 SPECIAL-NAMES paragraph 122
collating sequence 609
DELETE statement SYMBOLIC CHARACTERS
specifying in SPECIAL-NAMES
description and format 572 clause 121
paragraph 119
dynamic access 334 XML-SCHEMA clause 124
editing
format and description 333 REPOSITORY paragraph 125
fixed insertion 217
INVALID KEY phrase 334 ENVIRONMENT DIVISION
floating insertion 218
random access 334 ASCII considerations 639
replacement 219
sequential access 333 configuration section
signs 173
DELIMITED BY phrase SOURCE-COMPUTER
simple insertion 216
STRING 462 paragraph 114
special insertion 217
UNSTRING statement 472 SPECIAL-NAMES paragraph 116
suppression 219
delimited scope statement 288 input-output section
editing sign control symbol 206
delimiter FILE-CONTROL paragraph 130
editing signs 172, 173
INSPECT statement 367 environment variable
eject page 61
UNSTRING statement 472 assignment-name 134
EJECT statement 573
DELIMITER IN phrase, UNSTRING DSN option 124, 134
elementary items 163
statement 473 for a line sequential file 134
alignment rules 170
DEPENDING phrase for a QSAM file 134
basic subdivisions of a record 163
GO TO statement 354 for a VSAM file 134
MOVE statement 394
OCCURS clause 199 for an XML schema file 124
size determination in program 171
derived class 93 PATH option 124, 134
size determination in storage 171
DESCENDING KEY phrase 197 XML schema file 124
elementary move rules 394
collating sequence 198 environment-name 12, 305, 484
ELSE NEXT SENTENCE phrase 356
description 389 SPECIAL-NAMES paragraph 118,
ENCODING phrase
MERGE statement 389 119
XML GENERATE statement 490
SORT statement 449, 451 EOP phrases 481
ENCODING phrase, in XML PARSE 501

Index 689
equal sign (=) 268 factory data unit 162 FILE-CONTROL paragraph (continued)
EQUAL TO relational operator 268 factory definition ORGANIZATION clause 139
EUC 5 FACTORY paragraph 108 PADDING CHARACTER clause 141
Euro currency sign 610 format and description 95 RECORD KEY clause 144
specifying in CURRENCY SIGN factory identification division 101, 108 RELATIVE KEY clause 146
clause 122 factory method 93, 98 RESERVE clause 139
EVALUATE statement FACTORY paragraph 108 SELECT clause 134
comparing operands 346 factory procedure division 253 file-description-entry 158
determining truth value 345 factory procedure division header 255 file-name 64
format and description 344 factory WORKING-STORAGE 159 file-name, specifying on SELECT
evaluation rules FALSE phrase 345 clause 134
combined conditions 281 FD (file description) entry FILLER phrase 189
EVALUATE statement 346 BLOCK CONTAINS clause 179 CORRESPONDING phrase 191
nested IF statement 357 DATA RECORDS clause 184 data description entry 191
EXCEPTION XML event 26 description 178 fixed insertion editing 217
EXCEPTION/ERROR declarative 582 format 173 fixed segments 260
CLOSE statement 327 GLOBAL clause 179 fixed-length
DELETE statement 333 level indicator 163 records 179
description and format 582 VALUE OF clause 184 floating comment indicator (*>)
execution flow figurative constant comment lines 60
ALTER statement 314 DISPLAY statement 335 description 61
basic PERFORM statement 410 STOP statement 461 inline comment 61
PERFORM statement 408 STRING statement 463 floating comment indicators 13
EXIT METHOD statement figurative constants 14 floating insertion editing 218
format and description 350 ALL literal 15 floating-point
EXIT PARAGRAPH statement HIGH-VALUE 14 DISPLAY statement 335
format and description 351 HIGH-VALUES 14 floating-point literals 42
EXIT PERFORM statement LOW-VALUE 14 FOOTING phrase of LINAGE
format and description 350 LOW-VALUES 14 clause 184
EXIT PROGRAM statement NULL 15 FOR REMOVAL phrase 326, 327
format and description 349 NULLS 15 format notation, rules for xi
EXIT SECTION statement QUOTE 14 FREE statement 351
format and description 351 QUOTES 14 description and format 351
EXIT statement SPACE 14 UNBOUNDED tables 312
format and description 348 SPACES 14 FROM phrase
PERFORM statement 410 symbolic-character 15 ACCEPT statement 304
explicit attributes, of data 82 ZERO 14 REWRITE statement 431
explicit scope terminators 288 ZEROES 14 SUBTRACT statement 467
exponentiation ZEROS 14 with identifier 300
exponential expression 262 file WRITE statement 479
expression, arithmetic 261 definition 161 function arguments 512
EXTEND phrase file organization function definitions 516
OPEN statement 404 and access modes 143 function pointer
extended character set 3 definition 143 in SET statement 441
extension language elements 593 LINAGE clause 184 function pointer data items 238
EXTERNAL clause line-sequential 140 relation condition 277
with data item 192 types of 140 function type 510
with file name 178 file position indicator function-identifier 81
external decimal item description 301 function-names 12
DISPLAY statement 335 READ statement 424 function-pointer data items
external floating-point file section SET statement 445
DISPLAY statement 335 RECORD clause 181 FUNCTION-POINTER phrase in USAGE
external floating-point category 169 FILE SECTION 158, 178 clause 238
external floating-point in ACCEPT 304 EXTERNAL clause 178 functions
external floating-point items FILE STATUS clause arguments 512
alignment rules 170 DELETE statement and 333 categories 167
how to define 214 description 147 class and category of 166
PICTURE clause 214 file status key 295 classes 167
external-class-name 12, 127 format 130 description 509
external-fileid 12 INVALID KEY phrase and 299 rules for usage 511
file status key types of functions 510
common processing facility 295
F value and meaning 295
FACTORIAL function 528
FILE-CONTROL paragraph
ASSIGN clause 134
G
factory data 93 G symbol in PICTURE clause 205
description and format 130
factory data division 157 garbage collection 93
FILE STATUS clause 147
format 158

690 Enterprise COBOL for z/OS, V6.1 Language Reference

GIVING phrase I-O-CONTROL paragraph (continued) INHERITS clause 107
ADD statement 309 SAME RECORD AREA clause 152 INITIAL clause 105
arithmetic 291 SAME SORT AREA clause 153 initial state of program 105
DIVIDE statement 341 SAME SORT-MERGE AREA INITIALIZE statement
MERGE statement 391 clause 153 format and description 358
MULTIPLY statement 401 IBM extensions xiv, 593 overlapping operands, unpredictable
SORT statement 454 identification division results 294
SUBTRACT statement 469 FACTORY paragraph 108 inline comments 46
GLOBAL clause METHOD-ID paragraph 108 INLINE directive 588
with data item 193 OBJECT paragraph 108 INPUT phrase
with file name 179 IDENTIFICATION DIVISION OPEN statement 404
glossary 657 CLASS-ID paragraph 107 USE statement 582
GO TO statement 314 format 101 INPUT PROCEDURE phrase
altered 355 format (program, class, method) 101 RELEASE statement 427
conditional 354 optional paragraphs 109 SORT statement 454
format and description 354 PROGRAM-ID paragraph 104 Input-Output section
SEARCH statement 435, 439 identifier 261 description 129
unconditional 354 identifiers 71, 261 file control paragraph 129
GO TO, DEPENDING ON phrase 314 IF statement 356 FILE-CONTROL keyword 129
GOBACK statement 353 imperative statement 285 FILE-CONTROL paragraph 130
graphic character 5 implementor-name 12 format 129
GREATER THAN OR EQUAL TO symbol implicit I-O-CONTROL paragraph 148
(>=) 268 redefinition of storage area 178, 222 input-output statements
GREATER THAN symbol (>) 268 scope terminators 289 ACCEPT 304
group comparisons 275 implicit attributes, of data 82 CLOSE 326
group items 163 indentation 58, 165 common processing facilities 295
alphanumeric 165 independent segments 260 DELETE 333
class and category of 165 index DISPLAY 335
description 163 data item 275, 394 EXCEPTION/ERROR
MOVE statement 398 relative indexing 78 procedures 583
national 165, 194 SET statement 78 general description 294
usage of 165 index data item 75 OPEN 403
group move rules 398 INDEX phrase in USAGE clause 238 READ 420
GROUP-USAGE clause 194 index-name 65, 75 REWRITE 431
description 194 assigning values 441 START 458
format 194 comparisons 275 WRITE 478
GROUP-USAGE NATIONAL clause 194 OCCURS clause 199 INSERT statement 574
groups PERFORM statement 419 insertion editing
categories 167 SET statement 441 fixed (numeric-edited items) 217
classes 167 INDEXED BY phrase 199 floating (numeric-edited items) 218
indexed files simple 216
CLOSE statement 327 special (numeric-edited items) 217
H DELETE statement 334
FILE-CONTROL paragraph
INSPECT statement
AFTER phrase 367
halting execution 461
format 130 BEFORE phrase 367
hexadecimal notation
I-O-CONTROL paragraph comparison cycle 370
for alphanumeric literals 40
format 148 CONVERTING phrase 368
for national literals 45
organization 140 overlapping operands, unpredictable
hiding 109
permissible statements for 407 results 294
hierarchy of data 163
READ statement 424 REPLACING phrase 365
HIGH-VALUE figurative constant 14,
REWRITE statement 432 INSTALLATION paragraph
119
START statement 459 description 109
HIGH-VALUES figurative constant 14,
indexed organization format 101
119
description 140 instance data 93, 97, 162
hyphen (-), in indicator area 58
FILE-CONTROL paragraph instance definition
format 130 format and description 95
I-O-CONTROL paragraph instance method 93, 98
I format 148 instance variable 93
I-O-CONTROL paragraph indexing integer arguments 512
APPLY WRITE-ONLY clause 154 description 75 INTEGER function 528
ASCII considerations 640 MOVE statement evaluation 394 integer function arguments 513
checkpoint processing in 150 OCCURS clause 75, 195 integer functions 511
description 129, 148 relative 78 INTEGER-OF-DATE function 528
MULTIPLE FILE TAPE clause 153 SET statement and 78 INTEGER-OF-DAY function 529
order of entries 148 indicator area 55 INTEGER-PART function 530
RERUN clause 150 industry specifications 643 internal floating-point
SAME AREA clause 152 inheritance 93, 107 DISPLAY statement 335

Index 691
internal floating-point (continued) intrinsic functions (continued) JUSTIFIED clause
size of items 171 UPPER-CASE 548 description and format 193
internal floating-point category 169 USUBSTR 549 effect on initial settings 194
internal floating-point items USUPPLEMENTARY 550 STRING statement 463
alignment rules 170 UVALID 551 truncation of data 194
how to define 209 UWIDTH 553 USAGE IS INDEX clause and 193
INTO phrase VARIANCE 553 VALUE clause and 242
DIVIDE statement 338 WHEN-COMPILED 554
READ statement 420 YEAR-TO-YYYY 555
RETURN statement 429
STRING statement 462
invalid key condition 299
INVALID KEY phrase
K
Kanji 266
UNSTRING statement 472 DELETE statement 334
key of reference 140
with identifier 300 READ statement 422
KEY phrase
intrinsic functions 509 REWRITE statement 431
OCCURS clause 197
ACOS 519 START statement 459
READ statement 421
alphanumeric functions 510 WRITE statement 482
SEARCH statement 438
ANNUITY 520 INVOKE statement
SORT statement 449, 451
ASIN 521 BY VALUE phrase 374
START statement 458
ATAN 521 format and description 372
keyboard navigation 651
categories 167 LENGTH OF special register 374
keyword 670
CHAR 521 NEW phrase 373
classes 167 NOT ON EXCEPTION phrase 376
COS 522 ON EXCEPTION phrase 376
CURRENT-DATE 522 RETURNING phrase 375 L
DATE-OF-INTEGER 523 SELF special object identifier 373 LABEL RECORDS clause
DATE-TO-YYYYMMDD 524 SUPER special object identifier 373 format 173
DAY-OF-INTEGER 525 USING phrase 374 language-name 12
DAY-TO-YYYYDDD 525 ISCII considerations 639 LEADING phrase
DISPLAY-OF 526 ISCII standard 643 INSPECT statement 365, 366
FACTORIAL 528 ISO 646 639 SIGN clause 227
floating-point literals 513 ISO COBOL standards 643 LENGTH function 530
INTEGER 528 LENGTH OF special register 19
integer functions 510 INVOKE statement 374
INTEGER-OF-DATE 528
INTEGER-OF-DAY 529
J LESS THAN OR EQUAL TO symbol
(<=) 268
Java
INTEGER-PART 530 LESS THAN symbol (<) 268
class-name 127
LENGTH 530 level
package 127
LOG 531 01 item 163
Java classes 93
LOG10 532 02-49 item 163
Java interoperability 93
LOWER-CASE 532 level indicator
data types 374, 377, 379
MAX 533 (FD and SD) 57
literal types 374
MEAN 534 definition 163
Java interoperation 93
MEDIAN 534 level-number 60, 163, 189
Java Native Interface (JNI) 19, 93, 670
MIDRANGE 535 (01 and 77) 57
Java objects 93
MIN 535 66, renames 165
Java String data 93
MOD 536 77, elementary item 165
java.lang.Object 93
national functions 510 88, conditional variable 165
JNI environment pointer 93
NATIONAL-OF 537 definition 163
JNIENVPTR special register 19, 93
numeric functions 510 description and format 190
JSON GENERATE statement
NUMVAL 537 FILLER phrase 191
COUNT phrase 382
NUMVAL-C 539 levels of data 163
description 380
ORD 540 library-name 11, 64
END-JSON phrase 384
ORD-MAX 541 COPY statement 563
exception event 383
ORD-MIN 541 limits of the compiler 605
format 380
PRESENT-VALUE 542 LINAGE clause 481
format conversion 385
RANDOM 542 description 184
JSON name formation 387
RANGE 543 diagram of phrases 185
NAME phrase 382
REM 544 format 173
NOT ON EXCEPTION phrase 384
REVERSE 544 LINAGE-COUNTER special register
ON EXCEPTION phrase 383
SIN 545 description 20
operation 384
SQRT 545 WRITE statement 481
SUPPRESS phrase 382
STANDARD-DEVIATION 546 LINE
trimming 387
SUM 546 WRITE statement 480
JSON processing
summary of 516 line advancing 480
JSON-CODE special register 19
TAN 547 line-sequential file organization 140
JSON-CODE special register 19
ULENGTH 547 LINES
use in JSON GENERATE 383
UPOS 548 WRITE statement 480

692 Enterprise COBOL for z/OS, V6.1 Language Reference

LINES AT BOTTOM phrase 185 method data division (continued) national comparisons 273
LINES AT TOP phrase 185 format 157 national data items 239
linkage section method definition elementary move rules 396
requirement for indexed items 199 effect of SELF and SUPER 372 in a class condition 264
VALUE clause 242 format and description 97 in ACCEPT 304
LINKAGE SECTION IDENTIFICATION DIVISION 104 in UNSTRING statement 470
called subprogram 258 method procedure division 253 SEARCH statement 438
description 161 METHOD-ID paragraph 108 national floating-point 215
literals method FILE SECTION 159 national function arguments 513
and arithmetic expressions 261 method hiding 109 national functions 510, 511
ASSIGN clause 134 method identification division 101, 108 national groups 194
categories 167 method LOCAL-STORAGE 160, 161 CORRESPONDING phrase 195
classes 167 method overloading 108 description 195
CODE-SET clause and ALPHABET method overriding 109 INITIALIZE statement 195
clause 119 method procedure division 253, 254 qualification of data-names 195
CURRENCY SIGN clause 122 method procedure division header 256 RENAMES clause 195
DBCS 42 method WORKING-STORAGE 159 where processed as group 195
description 37 METHOD-ID paragraph 108 XML GENERATE statement 195
null-terminated alphanumeric 40 method-name 64 national items
STOP statement 461 methods alignment rules 170
VALUE clause 242 available to subclasses 107 how to define 213
Z literals 40 exiting 350 PICTURE clause 213
literals, class and category of 166 invoking 372 national literals 3, 43, 44
local-storage method definition in ACCEPT 304
requirement for indexed items 199 inheritance rules 107 national literals in hexadecimal
LOCAL-STORAGE 160 recursively reentering 105 notation 45
defining with RECURSIVE reusing 107 NATIONAL phrase in USAGE
clause 105 MIDRANGE function 535 clause 239
LOG function 531 MIN function 535 national-edited category 169
LOG10 function 532 minus sign (-) national-edited items 213
logical operator COBOL character 3 alignment rules 170
complex condition 279 fixed insertion symbol 217 how to define 213
in evaluation of combined floating insertion symbol 218, 219 NATIONAL-OF function 537
conditions 281 SIGN clause 227 native binary data item 236
list of 279 mnemonic-name 11, 65, 304 native character set 119
logical record ACCEPT statement 304 native collating sequence 119
definition 161 DISPLAY statement 335 negated combined condition 280
file data 161 SET statement 443 negated simple condition 279
program data 162 SPECIAL-NAMES paragraph 119 NEGATIVE in sign condition 278
record description entry and 162 WRITE statement 480 nested IF structure
RECORDS phrase 180 MOD function 536 description 357
LOW-VALUE figurative constant 14, 119 MOVE statement EVALUATE statement 344
LOW-VALUES figurative constant 14, CORRESPONDING phrase 393 nested programs
119 elementary moves 394 description 87
LOWER-CASE function 532 format and description 393 precedence rules for 584
lowercase letters group moves 398 NEW phrase
in PICTURE clause 204 record area 398 INVOKE statement 373
MULTIPLE FILE TAPE clause 153 next executable statement 83
multiple record processing, READ NEXT RECORD phrase, READ
M statement 422
multiple results, arithmetic
statement 420
NEXT SENTENCE phrase
MAX function 533
statements 294 IF statement 356
maximum index value 78
MULTIPLY statement SEARCH statement 435
MEAN function 534
common phrases 291 SEARCH statement (binary
MEDIAN function 534
format and description 400 search) 439
MEMORY SIZE clause 115
SEARCH statement (serial
MERGE statement
search) 436
ASCENDING/DESCENDING KEY
phrase 389 N NO ADVANCING phrase, DISPLAY
statement 336
COLLATING SEQUENCE N symbol in PICTURE clause 205
NO REWIND phrase 326
phrase 390 NAME phrase
OPEN statement 404
format and description 388 JSON GENERATE statement 382
nonreel file, definition 327
GIVING phrase 391 XML GENERATE statement 491
NOT AT END phrase
OUTPUT PROCEDURE phrase 391 NAMESPACE phrase 491
READ statement 421
segmentation considerations 392 NAMESPACE-DECLARATION XML
RETURN statement 430
USING phrase 390 event 26
NOT END-OF-PAGE phrase 481
method data 162 NAMESPACE-PREFIX phrase 491
method data division 157 national category 169

Index 693
NOT INVALID KEY phrase object program 87 ON SIZE ERROR phrase
DELETE statement 334 object reference 93 ADD statement 310
READ statement 422 in SET statement 441 arithmetic statements 291
REWRITE statement 431 OBJECT REFERENCE phrase 239 COMPUTE statement 331
START statement 459 object WORKING-STORAGE 159 DIVIDE statement 341
NOT ON EXCEPTION phrase OBJECT-COMPUTER paragraph 114 MULTIPLY statement 402
CALL statement 322 ASCII considerations 639 SUBTRACT statement 469
INVOKE statement 376 object-oriented class-name 65 OPEN statement
JSON GENERATE statement 384 object-oriented COBOL for new/existing files 404
XML GENERATE statement 494 class definition 93 format and description 403
XML PARSE statement 503 comparison rules 277 I-O phrase 404
NOT ON OVERFLOW phrase conformance rules phrases 403
STRING statement 464 SET...USAGE OBJECT programming notes 406
UNSTRING statement 473 REFERENCE 447 system dependencies 407
NOT ON SIZE ERROR phrase effect of VALUE clause 159 operands
ADD statement 310 factory definition 95 comparison of alphanumeric 272
DIVIDE statement 341 IDENTIFICATION DIVISION (class comparison of DBCS 273
general description 291 and method) 101 comparison of group 275
MULTIPLY statement 402 INHERITS clause 107 comparison of national 273
SUBTRACT statement 469 INVOKE statement 372 comparison of numeric 274
NSYMBOL compiler option 3 method definition 97 composite of 293
NULL method-name 64 overlapping 294
figurative constant 15 object definition 95 operation of JSON GENERATE
null block branch, CONTINUE OBJECT REFERENCE phrase in statement 384
statement 332 USAGE clause 239 operation of XML GENERATE
null-terminated alphanumeric literals 40 OO class name 65 statement 494
NULL/NULLS procedure division (classes and operational sign
data pointer 276, 444 methods) 253 algebraic, description of 172
figurative constant 247 REPOSITORY paragraph 125 SIGN clause and 172
function-pointer 277, 446 SELF and SUPER special object USAGE clause and 172
object reference 277, 447 identifiers 13 operational signs 172
procedure-pointer 277, 446 specifying configuration section 113 optional words, syntax notation xi
NULLS subclasses and methods 107 ORD function 540
figurative constant 15 objects in EVALUATE statement 345 ORD-MAX function 541
numeric arguments 512, 513 obsolete language elements xiv ORD-MIN function 541
numeric category 169 OCCURS clause order of entries
NUMERIC class test 265 ASCENDING/DESCENDING KEY clauses in FILE-CONTROL
numeric comparisons 274 phrase 197 paragraph 130
numeric function arguments 513 description 195 I-O-CONTROL paragraph 148
numeric functions 510, 511 INDEXED BY phrase 199 order of evaluation in combined
numeric items 210 restrictions 196 conditions 281
alignment rules 170 UNBOUNDED 199 ORGANIZATION clause
how to define 210 variable-length tables format 199 description 139
millennium dates 210 OCCURS DEPENDING ON (ODO) format 130
PICTURE clause 210 clause INDEXED phrase 139
numeric literals 41 complex 203 LINE SEQUENTIAL phrase 139
numeric-edited category 170 description 201 RELATIVE phrase 139
numeric-edited item object of 201 SEQUENTIAL phrase 139
editing signs 173 RECORD clause 181 out-of-line PERFORM statement 410
elementary move rules 396 REDEFINES clause and 196 outermost programs, debugging 584
numeric-edited items SEARCH statement and 196 OUTPUT phrase 404
alignment rules 170 subject and object of 201 OUTPUT PROCEDURE phrase
how to define 211 subject of 196, 201 MERGE statement 391
PICTURE clause 211 subscripting 75 RETURN statement 429
NUMVAL function 537 OFF phrase, SET statement 443 SORT statement 455
NUMVAL-C function 539 OMITTED phrase 319, 320 OVERFLOW phrase
ON EXCEPTION phrase CALL statement 323
CALL statement 322 STRING statement 464, 474
O INVOKE statement 376
JSON GENERATE statement 383
overlapping operands invalid in
arithmetic statements 294
object data division 157
XML GENERATE statement 493 data manipulation statements 294
format 158
XML PARSE statement 502 overloading 108
object definition
ON OVERFLOW phrase overriding 109
OBJECT paragraph 108
CALL statement 323
object identification division 101, 108
STRING statement 464, 474
object instance data 162
ON phrase, SET statement 443
OBJECT paragraph 108
object procedure division 253

694 Enterprise COBOL for z/OS, V6.1 Language Reference

P picture symbols (continued)
- 206
procedure-name
GO TO statement 354
P symbol in PICTURE clause 205, 207 , 206 MERGE statement 391
PACKED-DECIMAL phrase in USAGE / 205 PERFORM statement 410
clause 236 . 206 SORT statement 454
PADDING CHARACTER clause 141 $ (currency symbol) 206 procedure-pointer data items
PAGE * 206 SET statement 445
WRITE statement 480 + 206 USAGE clause 240
page eject 61 0 205 PROCEDURE-POINTER phrase in
paragraph 9 205 USAGE clause 240
header, specification of 56 A 204 procedures, description 260
termination, EXIT statement 348 asterisk 206 PROCESS (CBL) statement 560
paragraph-name 11, 64 B 204 PROCESSING PROCEDURE phrase, in
description 261 comma 206 XML PARSE 501
specification of 56 CR 206 PROCESSING-INSTRUCTION-DATA
paragraphs currency symbol (cs) 206, 208 XML event 26
description 53, 261 DB 206 PROCESSING-INSTRUCTION-TARGET
syntactical hierarchy 53 E 205 XML event 26
parent class 93 G 205 product support 683
parentheses minus 206 PROGRAM COLLATING SEQUENCE
combined conditions, use 281 N 205 clause
in arithmetic expressions 262 P 205, 207 ALPHABET clause 119
parsing XML documents period 206 ASCII considerations 639
with validation plus 206 SPECIAL-NAMES paragraph
restrictions 501 S 205 and 115
partial listings 560 sequence of 206 program data 162
PASSWORD clause slash 205 program data division 157
description 147 V 205 format 157
system dependencies 147 X 205 program definition
PERFORM statement Z 205 program procedure division 253
branching 410 plus (+) program identification division 101
conditional 412 fixed insertion symbol 217 program LOCAL-STORAGE 160
END-PERFORM phrase 409 floating insertion symbol 218, 219 program procedure division 253
EVALUATE statement 344 insertion character 219 program procedure division header 255
execution sequences 411 SIGN clause 227 program termination
EXIT statement 348 pointer data items GOBACK statement 353
format and description 408 relation condition 276 STOP statement 461
in-line 410 SET statement 444 program WORKING-STORAGE 159
out-of-line 410 USAGE clause 240 PROGRAM-ID paragraph
TIMES phrase 411 POINTER phrase description 104
VARYING phrase 413, 416 STRING statement 462 format 101
period (.) UNSTRING statement 473 program-name 64
actual decimal point 217 POINTER phrase in USAGE clause 240 program-name, rules for referencing 90
PGMNAME compiler option POSITIVE in sign condition 278 program, separately compiled 87
CANCEL statement 324 PRESENT-VALUE function 542 Programming interface information 655
phrases print files, WRITE statement 484 programming notes
definition 55 priority-number 115, 260 ACCEPT statement 304
syntactical hierarchy 53 procedure branching altered GO TO statement 314
physical record GO TO statement 354 arithmetic statements 294
BLOCK CONTAINS clause 179 statements, executed sequentially 303 data manipulation statements 462,
definition 161 procedure branching statements 303 470
file data 161 procedure division DELETE statement 333
file description entry and 162 description 253 EXCEPTION/ERROR
RECORDS phrase 180 format (programs, methods, procedures 584
PICTURE character-strings 46 classes) 253 OPEN statement 406
PICTURE clause PROCEDURE DIVISION PERFORM statement 410
and class condition 264 ASCII considerations 641 RECORD clause 181
computational items and 235 declarative procedures 259 STRING statement 462
CURRENCY SIGN clause 122 header 255 UNSTRING statement 470
data categories 209 statements 303 programming structures 412
DECIMAL-POINT IS COMMA PROCEDURE DIVISION header programs, recursive 105
clause 124, 204 RETURNING phrase 258 pseudo-text
description 203 USING phrase 256 COPY statement operand 565
editing 216 PROCEDURE DIVISION names 71 description 62
format 203 procedure pointer data items pseudo-text and partial-word
symbols used in 204 relation condition 277 continuation rules 577
PICTURE SYMBOL phrase 123 pseudo-text delimiters 51
picture symbols 204

Index 695
punch files, WRITE statement 484 RECORDS phrase relative organization
BLOCK CONTAINS clause 179 access modes allowed 144
RERUN clause 151 description 140
Q RECURSIVE clause 105
recursive methods 372
FILE-CONTROL paragraph
format 130
qualification 69
recursive programs 105 I-O-CONTROL paragraph
quotation mark character 59
requirement for indexed items 199 format 148
QUOTE figurative constant 14
REDEFINES clause RELEASE statement 294, 427
QUOTES figurative constant 14
description 221 REM function 544
examples of 223 REMAINDER phrase of DIVIDE
format 221 statement 341
R general considerations 222 RENAMES clause 165
railroad track format, how to read xi OCCURS clause restriction 221 description and format 224
random access mode undefined results 224 INITIALIZE statement 359
data organization and 143 VALUE clause and 221 level 66 item 165, 224
DELETE statement 334 redefinition, implicit 178 PICTURE clause 203
description 143 REEL phrase 326, 327 repeated words, syntax notation xii
READ statement 425 reference format 55 REPLACE statement
RANDOM function 542 reference-modification comparison operation 577
RANGE function 543 description 79 continuation rules for pseudo-text and
READ statement MOVE statement evaluation 394 partial-word 577
AT END phrases 421 reference, methods of description and format 575
dynamic access mode 425 simple data 71 special notes 578
format and description 420 relation character replacement editing 219
INTO identifier phrase 300, 421 COPY statement 565 replacement rules for COPY
INVALID KEY phrase 299, 422 INITIALIZE statement 358 statement 566
KEY phrase 421 INSPECT statement 365 REPLACING phrase
multiple record processing 422 relation conditions COPY statement 565
NEXT RECORD phrase 420 abbreviated combined 282 INITIALIZE statement 358, 360
overlapping operands, unpredictable alphanumeric comparisons 269, 272 REPOSITORY paragraph 125, 127
results 294 comparison operations 269 required words, syntax notation xi
programming notes 426 data pointer 275 RERUN clause
random access mode 425 DBCS comparisons 269, 273 checkpoint processing 150
READY TRACE statement 575 description 267 description 150
receiving field function-pointer operands 277 format 148
COMPUTE statement 330 general relation 268 RECORDS phrase 150
MOVE statement 393 group comparisons 269 sort/merge 151
multiple results rules 294 national comparisons 269 RESERVE clause
SET statement 441 numeric comparisons 269 description 139
STRING statement 462 object reference 277 format 130
UNSTRING statement 472 operands of equal size 272 reserved words 12, 621
record operands of unequal size 272 RESET TRACE statement 575
area description 181 procedure pointer operands 277 resolution of names 66
elementary items 163 relational operator restrictions
fixed-length 179 in abbreviated combined relation CICS
logical, definition of 161 condition 282 parsing with validation using
physical, definition of 161 meaning of each 269 FILE 501
record area relation condition use 268 result field
MOVE statement 398 relational operators 13 GIVING phrase 291
RECORD clause relative files NOT ON SIZE ERROR phrase 291
description and format 181 access modes allowed 144 ON SIZE ERROR phrase 291
omission of 181 CLOSE statement 327 ROUNDED phrase 291
RECORD CONTAINS 0 DELETE statement 334 RETURN statement
CHARACTERS 181 FILE-CONTROL paragraph AT END phrase 430
RECORD DELIMITER clause 142 format 130 description and format 429
record description entry 160, 189 I-O-CONTROL paragraph overlapping operands, unpredictable
levels of data 163 format 148 results 294
logical record 162 organization 140 RETURN-CODE special register 21
RECORD KEY clause permissible statements for 407 RETURNING NATIONAL phrase, in
description 144 READ statement 423 XML PARSE 500
format 130 RELATIVE KEY clause 144, 146 RETURNING phrase
record key in indexed file 334 REWRITE statement 433 CALL statement 321
record-description entry START statement 460 INVOKE statement 375
LINKAGE SECTION 161 RELATIVE KEY clause PROCEDURE DIVISION header 258
record-description-entry 159 description 146 reusing logical records 432
record-name 64 format 130 REVERSE function 544
RECORDING MODE clause 186

696 Enterprise COBOL for z/OS, V6.1 Language Reference

REWRITE statement SECURITY paragraph SET statement (continued)
description and format 431 description 109 object reference data items 447
FROM identifier phrase 300 format 101 OFF phrase 443
INVALID KEY phrase 431 SEGMENT-LIMIT clause 115 ON phrase 443
ROUNDED phrase segmentation 260 overlapping operands, unpredictable
ADD statement 310 segmentation considerations 315, 392, results 294
COMPUTE statement 330 456 pointer data items 444
description 291 SELECT clause procedure-pointer data items 445
DIVIDE statement 341 ASSIGN clause and 134 requirement for indexed items 199
MULTIPLY statement 401 format 130 SEARCH statement 442
size error checking and 292 specifying a file name 134 TO phrase 441
SUBTRACT statement 469 SELECT OPTIONAL clause TO TRUE phrase 444
RSD file CLOSE statement 327 UP BY phrase 442
WRITE statement 480 description 134 sharing data 193
rules for condition-name entries 245 format 130 sharing files 179
rules for syntax notation xi specification for sequential I-O SHIFT-IN special register 22
run unit files 134 SHIFT-OUT special register 22
description 87 selection objects in EVALUATE sibling program 87
termination with CANCEL statement 345 SIGN clause 226
statement 325 selection subjects in EVALUATE sign condition 278
runtime options statement 345 SIGN IS SEPARATE clause 227
DEBUG 618 SELF 277 signed
NODEBUG 618 SELF special object identifier 13, 373 numeric item, definition 210
sending field operational signs 172
MOVE statement 393 simple condition
S SET statement 441
STRING statement 462
combined 280
description and types 264
S symbol in PICTURE clause 205
UNSTRING statement 470 negated 279
SAME clause 152
sentences simple data reference 71
SAME RECORD AREA clause
definition 54 simple insertion editing 216
description 152
description 261 SIN function 545
format 148
syntactical hierarchy 53 single-byte ASCII 5
SAME SORT AREA clause
SEPARATE CHARACTER phrase of single-byte EBCDIC 5
description 153
SIGN clause 227 size-error condition 291
format 148
separately compiled program 87 skip to next page 61
SAME SORT-MERGE AREA clause
separators 49, 245 SKIP1 statement 580
description 153
separators, rules for 49 SKIP2 statement 580
format 148
sequence number area (cols. 1-6) 55 SKIP3 statement 580
scope of names 63
sequential access mode slack bytes
scope terminator
data organization and 143 between 232
explicit 288
DELETE statement 333 within 230
implicit 289
description 143 slash (/)
SD (sort file description) entry
READ statement 423 comment lines 60
data division 178
REWRITE statement 432 insertion character 216
DATA RECORDS clause 184
sequential files symbol in PICTURE clause 205
description 178
access mode allowed 143 SORT statement
level indicator 163
CLOSE statement 326, 327 ASCENDING KEY phrase 449, 451
SD (Sort File Description) entry
description 140 COLLATING SEQUENCE
description 173
file description entry 173 phrase 453
SEARCH statement
FILE-CONTROL paragraph DESCENDING KEY phrase 449, 451
AT END phrase 435
format 130 description and format 448
binary search 438
LINAGE clause 184 DUPLICATES phrase 452, 453
description and format 434
OPEN statement 403 GIVING phrase 454
serial search 435
PASSWORD clause valid with 147 INPUT PROCEDURE phrase 454
SET statement 436
permissible statements for 406 OUTPUT PROCEDURE phrase 455
VARYING phrase 437
READ statement 423 segmentation considerations 456
WHEN phrase 439
REWRITE statement 432 USING phrase 454
SEARCH STATEMENT
SELECT OPTIONAL clause 134 SORT-CONTROL special register 22, 456
NEXT SENTENCE phrase 435
serial search 435 SORT-CORE-SIZE special register 23,
section header
PERFORM statement 413 456
description 260
SERVICE LABEL statement 580 SORT-FILE-SIZE special register 23, 456
specification of 56
SERVICE RELOAD statement 580 SORT-MESSAGE special register 24, 456
section-name 11, 64
SET statement SORT-MODE-SIZE special register 24,
description 260
description and format 441 456
in EXCEPTION/ERROR
DOWN BY phrase 442 SORT-RETURN special register 24, 456
declarative 582
function-pointer data items 238, 445
sections 53, 260
index data item 238

Index 697
Sort/Merge feature SPECIAL-NAMES paragraph (continued) subclass 93
I-O-CONTROL paragraph DECIMAL-POINT IS COMMA subclasses and methods 107
format 148 clause 124 subjects in EVALUATE statement 345
MERGE statement 388 description 116 subprogram linkage
RELEASE statement 427 format 116 CALL statement 316
RERUN clause 151 mnemonic-name 119 CANCEL statement 324
RETURN statement 429 XML-SCHEMA clause 124 ENTRY statement 343
SAME SORT AREA clause 153 SQRT function 545 subprogram termination
SAME SORT-MERGE AREA STANDALONE-DECLARATION XML CANCEL statement 324
clause 153 event 26 EXIT PROGRAM statement 349
SORT statement 448 standard alignment GOBACK statement 353
Sort/Merge file statement phrases JUSTIFIED clause 194 subscripting
ASCENDING/DESCENDING KEY standard alignment rules 170 definition and format 75
phrase 389 STANDARD-1 INDEXED BY phrase of OCCURS
COLLATING SEQUENCE RECORD DELIMITER clause 142 clause 199
phrase 390 STANDARD-1 phrase 120 MOVE statement evaluation 394
GIVING phrase 391 STANDARD-2 phrase 120 OCCURS clause specification 195
OUTPUT PROCEDURE phrase 391 STANDARD-DEVIATION function 546 table references 75
USING phrase 390 standards 643 using data-names 77
source code START statement using index-names (indexing) 75
library, programming notes 568 description and format 458 using integers 77
listing 562 indexed file 459 substitution characters
source code format 55 INVALID KEY phrase 299, 459 DISPLAY-OF 527
source language debugging 617 relative files 460 NATIONAL-OF 537
source program status key considerations 458 substitution field of INSPECT
standard COBOL reference format 55 START-OF-CDATA-SECTION XML REPLACING 365
SOURCE-COMPUTER paragraph 114 event 26 substrings, specifying
SPACE figurative constant 14 START-OF-DOCUMENT XML event 26 (reference-modification) 79
SPACES figurative constant 14 START-OF-ELEMENT XML event 26 SUBTRACT statement
special insertion editing 217 statement operations common phrases 289
special object identifiers common phrases 289 description and format 467
SELF 13 file position indicator 301 SUM function 546
SUPER 13 INTO and FROM phrases 300 SUPER special object identifier 13, 373
special registers 16 statements superclass 93
ADDRESS OF 17 categories of 284 support 683
DEBUG-ITEM 17 conditional 286 SUPPRESS option, COPY 565
JNIENVPTR 19 data manipulation 294 suppress output 560
JSON-CODE 19 definition 54 SUPPRESS phrase
LENGTH OF 19 delimited scope 288 JSON GENERATE statement 382
LINAGE-COUNTER 20 description 261 XML GENERATE statement 492
RETURN-CODE 21 imperative 285 suppression editing 219
SHIFT-OUT, SHIFT-IN 22 input-output 294 switch-status condition 278
SORT-CONTROL 22 procedure branching 303 SYMBOLIC CHARACTERS clause 121
SORT-CORE-SIZE 23 syntactical hierarchy 53 symbolic-character 11, 65
SORT-FILE-SIZE 23 types of 54 symbolic-character figurative
SORT-MESSAGE 24 static data 93 constant 15
SORT-MODE-SIZE 24 static method 93 symbols in PICTURE clause 204
SORT-RETURN 24 status key SYNCHRONIZED clause 228
TALLY 25 common processing facility 295 effect on other language
WHEN-COMPILED 25 file processing 583 elements 228
XML-CODE 26 STOP RUN statement 461 VALUE clause and 242
XML-EVENT 26 STOP statement 461 syntax notation, rules for xi
XML-INFORMATION 32 storage system considerations, subprogram
XML-NAMESPACE 26, 33 map listing 562 linkage
XML-NAMESPACE-PREFIX 26, 35 MEMORY SIZE clause 115 CALL statement 316
XML-NNAMESPACE 26, 34 REDEFINES clause 221 CANCEL statement 324
XML-NNAMESPACE-PREFIX 26, 35 storage manipulation statements system information transfer, ACCEPT
XML-NTEXT 26, 36 ALLOCATE 310 statement 306
XML-TEXT 26, 37 FREE 351 system input device, ACCEPT
SPECIAL-NAMES paragraph STRING statement statement 304
ACCEPT statement 304 description and format 462 system-names 12, 114
ALPHABET clause 119 execution of 464 computer-name 114
ASCII considerations 639 overlapping operands, unpredictable SOURCE-COMPUTER
ASCII-encoded file specification 187 results 294 paragraph 114
CLASS clause 122 structure of the COBOL language 3
CODE-SET clause and 187 structured programming
CURRENCY SIGN clause 122 DO-WHILE and DO-UNTIL 412

698 Enterprise COBOL for z/OS, V6.1 Language Reference

T type conformance
SET...USAGE OBJECT
USAGE NATIONAL
size of items 171
table references REFERENCE 447 STRING statement and 463
indexing 75 TYPE phrase USAGE OBJECT REFERENCE
subscripting 75 XML GENERATE statement 492 phrase 372
TALLY special register 25 types of functions 510 USE FOR DEBUGGING declarative 618
TALLYING phrase USE statement
INSPECT statement 365 format and description 582
UNSTRING statement 473
TAN function 547 U user labels
DEBUGGING declarative 584
termination of execution ULENGTH function 547
user-defined words 10
EXIT METHOD statement 350 unary operator 262
USING phrase
EXIT PARAGRAPH statement 351 unconditional GO TO statement 354
ASSIGN clause 134
EXIT PERFORM statement 350 Unicode 3, 5
CALL statement 318
EXIT PROGRAM statement 349 unique names 165
in PROCEDURE DIVISION
EXIT SECTION statement 351 uniqueness of reference 69
header 255
GOBACK statement 353 unit file, definition 327
INVOKE statement 374
STOP RUN statement 461 UNIT phrase 326
MERGE statement 390
terminators, scope 288 universal object reference 239
PROCEDURE DIVISION header 256
text words 564 UNKNOWN-REFERENCE-IN-
SORT statement 454
text-name 11, 65 ATTRIBUTE XML event 26
subprogram linkage 258
literal-1 563 UNKNOWN-REFERENCE-IN-CONTENT
USUBSTR function 549
THREAD compiler option 199 XML event 26
USUPPLEMENTARY function 550
requirement for indexed items 199 UNRESOLVED-REFERENCE XML
UTF-16 3, 5
THROUGH (THRU) phrase event 26
UTF-8 5
ALPHABET clause 119 unsigned numeric item, definition 210
UVALID function 551
CLASS clause 122 UNSTRING statement
UWIDTH function 553
EVALUATE statement 345 description and format 470
PERFORM statement 410 execution 474
RENAMES clause 224 overlapping operands, unpredictable
VALUE clause 244 results 294 V
TIME 307 receiving field 472 V symbol in PICTURE clause 205
TIMES phrase of PERFORM sending field 470 VALIDATING phrase, in XML
statement 411 UP BY phrase, SET statement 442 PARSE 500
TITLE statement 581 UPON phrase, DISPLAY 335 validating XML documents
TO phrase, SET statement 441 UPOS function 548 restrictions 501
TO TRUE phrase, SET statement 444 UPPER-CASE function 548 VALUE clause
transfer of control UPSI-0 through UPSI-7, program switches condition-name 244
ALTER statement 314, 315 and switch-status condition 278 effect on object-oriented
basic PERFORM statement 410 condition-name 119 programs 159
explicit 83 processing special conditions 119 format 242, 244
GO TO statement 354 SPECIAL-NAMES paragraph 119 level 88 item 165
IF statement 357 USAGE clause NULL/NULLS figurative
implicit 83 BINARY phrase 235 constant 238, 247
PERFORM statement 408 CODE-SET clause and 187 rules for condition-name entries 245
XML PARSE statement 499 COMPUTATIONAL phrases 236 rules for literal values 242
transfer of data description 233 VALUE OF clause
ACCEPT statement 304 DISPLAY phrase 237 description 184
MOVE statement 393 DISPLAY-1 phrase 238 format 173
STRING statement 462 format 233 variable-length tables 199, 201
UNSTRING statement 470 FUNCTION-POINTER phrase 238 VARIANCE function 553
trimming of generated JSON data 387 INDEX phrase 238 VARYING phrase
trimming of generated XML data 497 NATIONAL phrase 194, 239 PERFORM statement 413
TRUNC compiler option 172 operational signs and 172 SEARCH statement 437
truncation of data PACKED-DECIMAL phrase 236 VERSION-INFORMATION XML
arithmetic item 171 POINTER phrase 240 event 26
JUSTIFIED clause 194 PROCEDURE-POINTER phrase 240 VOLATILE clause
ROUNDED phrase 291 VALUE clause and 242 format 247
TRUNC compiler option 172 USAGE COMP-1
truth value size of items 171
complex conditions 279 USAGE COMP-2
size of items 171
W
EVALUATE statement 345 WHEN phrase
IF statement 356 USAGE DISPLAY
EVALUATE statement 345
of complex condition 279 size of items 171
SEARCH statement (binary
sign condition 278 STRING statement and 463
search) 439
with conditional statement 286 USAGE DISPLAY-1
SEARCH statement (serial
size of items 171
search) 437
STRING statement and 463

Index 699
WHEN-COMPILED function 554 XML GENERATE statement XML-INFORMATION special register 32
WHEN-COMPILED special register 25 ATTRIBUTES phrase 490 XML-NAMESPACE special register 26,
WITH DEBUGGING MODE clause 114, COUNT IN phrase 489 33
584, 617 description 487 XML-NAMESPACE special register, in
WITH DUPLICATES phrase, SORT element name formation 497 XML PARSE 504
statement 452, 453 ENCODING phrase 490 XML-NAMESPACE-PREFIX special
WITH FOOTING phrase 184 END-XML phrase 494 register 26, 35
WITH NO ADVANCING phrase 336 exception event 493 XML-NNAMESPACE special register 26,
WITH NO REWIND phrase, CLOSE format 487 34
statement 327 format conversion 496 XML-NNAMESPACE-PREFIX special
WITH POINTER phrase NAME phrase 491 register 26, 35
STRING statement 462 NAMESPACE phrase 491 XML-NTEXT special register 26, 36, 505
UNSTRING statement 473 NAMESPACE-PREFIX phrase 491 XML-SCHEMA clause 124
WORKING-STORAGE SECTION 159 NOT ON EXCEPTION phrase 494 specified in SPECIAL-NAMES
WRITE statement ON EXCEPTION phrase 493 paragraph 124
AFTER ADVANCING 480, 484 operation 494 xml-schema-name 65, 124
ALTERNATE RECORD KEY 485 SUPPRESS phrase 492 description 124
BEFORE ADVANCING 480, 484 trimming 497 specifying in SPECIAL-NAMES
description 478 TYPE phrase 492 paragraph 124
END-OF-PAGE phrase 481 XML-DECLARATION phrase 490 XML-SCHEMA clause 124
format 478 XML PARSE statement XML-TEXT special register 26, 37, 505
FROM identifier phrase 300 control flow 504 XML, definition 682
indexed files 485 description 499
NOT END-OF-PAGE phrase 481 exception event 502
relative files 485
sequential files 483
format 499
nested XML GENERATE 504
Y
YEAR-TO-YYYY function 555
nested XML PARSE 504
ON EXCEPTION phrase 502
X PROCESSING PROCEDURE
phrase 501 Z
X symbol in PICTURE clause 205
XML parsing Z
XML document
with validation insertion character 219
parsing with validation
restrictions 501 null-terminated literals 40
restrictions 501
XML processing symbol in PICTURE clause 205
XML event
ENCODING phrase, in XML Z literals 40
ATTRIBUTE-CHARACTER 26
GENERATE 490 zero
ATTRIBUTE-CHARACTERS 26
ENCODING phrase, in XML filling, elementary moves 394
ATTRIBUTE-NAME 26
PARSE 501 suppression and replacement
ATTRIBUTE-NATIONAL-
PROCESSING PROCEDURE phrase, editing 219
CHARACTER 26
in XML PARSE 501 ZERO figurative constant 14
COMMENT 26
RETURNING NATIONAL phrase, in ZERO in sign condition 278
CONTENT-CHARACTER 26
XML PARSE 500 ZEROES figurative constant 14
CONTENT-CHARACTERS 26
VALIDATING phrase, in XML ZEROS figurative constant 14
CONTENT-NATIONAL-
PARSE 500
CHARACTER 26
XML-CODE special register 26, 499
DOCUMENT-TYPE-
XML-EVENT special register 26, 499
DECLARATION 26
XML-INFORMATION special
ENCODING-DECLARATION 26
register 32
END-OF-CDATA-SECTION 26
XML-NAMESPACE special
END-OF-DOCUMENT 26
register 26, 33, 499
END-OF-ELEMENT 26
XML-NAMESPACE-PREFIX special
END-OF-INPUT 26
register 26, 35, 499
EXCEPTION 26
XML-NNAMESPACE special
NAMESPACE-DECLARATION 26
register 26, 34, 499
PROCESSING-INSTRUCTION-
XML-NNAMESPACE-PREFIX special
DATA 26
register 26, 35, 499
PROCESSING-INSTRUCTION-
XML-NTEXT special register 26, 36,
TARGET 26
499
STANDALONE-DECLARATION 26
XML-TEXT special register 26, 37,
START-OF-CDATA-SECTION 26
499
START-OF-DOCUMENT 26
XML schema file
START-OF-ELEMENT 26
environment variable 124
UNKNOWN-REFERENCE-IN-
XML-CODE special register 26
ATTRIBUTE 26
use in XML GENERATE 494
UNKNOWN-REFERENCE-IN-
use in XML PARSE 502
CONTENT 26
XML-DECLARATION phrase 490
UNRESOLVED-REFERENCE 26
XML-EVENT special register 26, 504
VERSION-INFORMATION 26

700 Enterprise COBOL for z/OS, V6.1 Language Reference

IBM®

Product Number: 5655-EC6

Printed in USA

SC27-8713-00