Cobol Programming Guide - Igy5pg20
Uploaded by
viriathvsCobol Programming Guide - Igy5pg20
Uploaded by
viriathvsEnterprise COBOL for z/OS
Programming Guide
Version 5.2
SC14-7382-03
Enterprise COBOL for z/OS
Programming Guide
Version 5.2
SC14-7382-03
Note
Before using this information and the product it supports, be sure to read the general information under Notices on page
815.
First edition
| This edition applies to Version 5 Release 2 of IBM Enterprise COBOL for z/OS (program number 5655-W32) and to
| all subsequent releases and modifications until otherwise indicated in new editions. Make sure that you are using
| the correct edition for the level of the product.
You can view or download softcopy publications free of charge at www.ibm.com/shop/publications/order/.
Copyright IBM Corporation 1991, 2015.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . xiii Examples: initializing data items . . . . . . 28
Initializing a structure (INITIALIZE) . . . . . 30
Preface . . . . . . . . . . . . . . xv Assigning values to elementary data items
(MOVE) . . . . . . . . . . . . . . 32
About this information . . . . . . . . . . xv
Assigning values to group data items (MOVE) . 33
How this information will help you . . . . . xv
Assigning arithmetic results (MOVE or
Abbreviated terms . . . . . . . . . . . xv
COMPUTE) . . . . . . . . . . . . . 34
Comparison of commonly used terms . . . . xvi
Assigning input from a screen or file (ACCEPT) 34
How to read syntax diagrams . . . . . . . xvi
Displaying values on a screen or in a file (DISPLAY) 35
How examples are shown . . . . . . . . xviii
Displaying data on the system logical output
Additional documentation and support . . . . xviii
device . . . . . . . . . . . . . . . 36
Summary of changes . . . . . . . . . . xviii
Using WITH NO ADVANCING . . . . . . 37
| Version 5 Release 2 . . . . . . . . . . xix
Using intrinsic functions (built-in functions) . . . 38
Version 5 Release 1 Modification 1 . . . . . xix
Using tables (arrays) and pointers . . . . . . . 39
Version 5 Release 1 . . . . . . . . . . . xx
Storage and its addressability . . . . . . . . 39
How to send your comments . . . . . . . . xxii
Restrictions for AMODE . . . . . . . . . . 40
Accessibility. . . . . . . . . . . . . . xxii
Settings for RMODE . . . . . . . . . . . 41
Interface information . . . . . . . . . . xxii
Storage restrictions for passing data . . . . . 41
Keyboard navigation . . . . . . . . . . xxii
Location of data areas . . . . . . . . . . 42
Accessibility of this information . . . . . . xxiii
Storage for LOCAL-STORAGE data . . . . . 42
IBM and accessibility . . . . . . . . . xxiii
Storage for external data . . . . . . . . . 42
Storage for QSAM input-output buffers . . . . 42
Part 1. Coding your program . . . . 1
Chapter 3. Working with numbers and
Chapter 1. Structuring your program . . 3 arithmetic . . . . . . . . . . . . . 43
Identifying a program . . . . . . . . . . . 3 Defining numeric data. . . . . . . . . . . 43
Identifying a program as recursive . . . . . . 4 Displaying numeric data . . . . . . . . . . 45
Marking a program as callable by containing Controlling how numeric data is stored . . . . . 46
programs . . . . . . . . . . . . . 4. Formats for numeric data. . . . . . . . . . 47
Setting a program to an initial state. . . . . 5. External decimal (DISPLAY and NATIONAL)
Changing the header of a source listing . . . 5. items . . . . . . . . . . . . . . . 47
Describing the computing environment . . . . 5. External floating-point (DISPLAY and
Example: FILE-CONTROL entries . . . . . 6. NATIONAL) items . . . . . . . . . . . 48
Specifying the collating sequence . . . . . 6. Binary (COMP) items . . . . . . . . . . 48
Defining symbolic characters . . . . . . . 8. Native binary (COMP-5) items . . . . . . . 49
Defining a user-defined class . . . . . . . 8. Packed-decimal (COMP-3) items . . . . . . 50
Defining files to the operating system . . . . 8. Internal floating-point (COMP-1 and COMP-2)
Describing the data . . . . . . . . . . . . 11 items . . . . . . . . . . . . . . . 50
Using data in input and output operations . . . 11 Examples: numeric data and internal
Comparison of WORKING-STORAGE and representation . . . . . . . . . . . . 51
LOCAL-STORAGE . . . . . . . . . . . 14 Data format conversions . . . . . . . . . . 52
Using data from another program . . . . . . 16 Conversions and precision . . . . . . . . 52
Processing the data . . . . . . . . . . . . 17 Sign representation of zoned and packed-decimal
How logic is divided in the PROCEDURE data . . . . . . . . . . . . . . . . . 53
DIVISION . . . . . . . . . . . . . . 18 Checking for incompatible data (numeric class test) 54
Declaratives . . . . . . . . . . . . . 21 Performing arithmetic . . . . . . . . . . . 55
Using COMPUTE and other arithmetic
Chapter 2. Using data . . . . . . . . 23 statements . . . . . . . . . . . . . . 56
Using variables, structures, literals, and constants . 23 Using arithmetic expressions . . . . . . . 57
Using variables . . . . . . . . . . . . 23 Using numeric intrinsic functions . . . . . . 57
Using data items and group items . . . . . . 24 Using math-oriented callable services . . . . . 58
Using literals . . . . . . . . . . . . . 25 Using date callable services . . . . . . . . 60
Using constants . . . . . . . . . . . . 26 Examples: numeric intrinsic functions . . . . 60
Using figurative constants . . . . . . . . 26 Fixed-point contrasted with floating-point arithmetic 62
Assigning values to data items . . . . . . . . 27 Floating-point evaluations . . . . . . . . 63
Copyright IBM Corp. 1991, 2015 iii
Fixed-point evaluations . . . . . . . . . 63 Example: arithmetic expressions as reference
Arithmetic comparisons (relation conditions) . . 63 modifiers . . . . . . . . . . . . . . 114
Examples: fixed-point and floating-point Example: intrinsic functions as reference
evaluations . . . . . . . . . . . . . 64 modifiers . . . . . . . . . . . . . . 114
Using currency signs . . . . . . . . . . . 65 Tallying and replacing data items (INSPECT) . . . 115
Example: multiple currency signs . . . . . . 66 Examples: INSPECT statement. . . . . . . 115
Converting data items (intrinsic functions). . . . 116
Chapter 4. Handling tables . . . . . . 67 Changing case (UPPER-CASE, LOWER-CASE) 117
Defining a table (OCCURS) . . . . . . . . . 67 Transforming to reverse order (REVERSE) . . . 117
Nesting tables . . . . . . . . . . . . . 69 Converting to numbers (NUMVAL,
Example: subscripting . . . . . . . . . . 70 NUMVAL-C) . . . . . . . . . . . . 117
Example: indexing . . . . . . . . . . . 70 Converting from one code page to another . . 118
Referring to an item in a table . . . . . . . . 70 Evaluating data items (intrinsic functions) . . . . 119
Subscripting . . . . . . . . . . . . . 71 Evaluating single characters for collating
Indexing . . . . . . . . . . . . . . 72 sequence . . . . . . . . . . . . . . 119
Putting values into a table . . . . . . . . . 73 Finding the largest or smallest data item . . . 120
Loading a table dynamically. . . . . . . . 73 Finding the length of data items . . . . . . 122
Initializing a table (INITIALIZE) . . . . . . 73 Finding the date of compilation . . . . . . 123
Assigning values when you define a table
(VALUE) . . . . . . . . . . . . . . 75 Chapter 7. Processing data in an
Example: PERFORM and subscripting . . . . 76 international environment . . . . . . 125
Example: PERFORM and indexing. . . . . . 77 COBOL statements and national data . . . . . 126
Creating variable-length tables (DEPENDING ON) 78 Intrinsic functions and national data. . . . . . 128
Loading a variable-length table . . . . . . . 80 Unicode and the encoding of language characters 129
Assigning values to a variable-length table . . . 81 Using national data (Unicode) in COBOL . . . . 130
Complex OCCURS DEPENDING ON . . . . . 81 Defining national data items . . . . . . . 130
Example: complex ODO . . . . . . . . . 82 Using national literals . . . . . . . . . 131
Effects of change in ODO object value . . . . 83 Using national-character figurative constants 132
Searching a table . . . . . . . . . . . . 85 Defining national numeric data items . . . . 133
Doing a serial search (SEARCH) . . . . . . 86 National groups . . . . . . . . . . . 133
Doing a binary search (SEARCH ALL) . . . . 87 Using national groups . . . . . . . . . 134
| Sorting a table . . . . . . . . . . . . . 88 Storage of character data . . . . . . . . 137
Processing table items using intrinsic functions . . 89 Converting to or from national (Unicode)
Example: processing tables using intrinsic representation . . . . . . . . . . . . . 137
functions . . . . . . . . . . . . . . 89 Converting alphanumeric, DBCS, and integer to
Working with unbounded tables and groups . . . 90 national (MOVE) . . . . . . . . . . . 138
Example: Using unbounded tables for parsing Converting alphanumeric or DBCS to national
XML documents . . . . . . . . . . . . 90 (NATIONAL-OF) . . . . . . . . . . . 139
Converting national to alphanumeric
Chapter 5. Selecting and repeating (DISPLAY-OF) . . . . . . . . . . . . 139
program actions . . . . . . . . . . 93 Overriding the default code page. . . . . . 140
Selecting program actions . . . . . . . . . 93 Conversion exceptions . . . . . . . . . 140
Coding a choice of actions . . . . . . . . 93 Example: converting to and from national data 140
Coding conditional expressions . . . . . . . 98 Processing UTF-8 data . . . . . . . . . . 141
Repeating program actions . . . . . . . . . 101 Using intrinsic functions to process UTF-8
Choosing inline or out-of-line PERFORM . . . 102 encoded data . . . . . . . . . . . . 142
Coding a loop . . . . . . . . . . . . 103 Processing Chinese GB 18030 data . . . . . . 146
Looping through a table . . . . . . . . . 103 Comparing national (UTF-16) data . . . . . . 147
Executing multiple paragraphs or sections. . . 104 Comparing two class national operands . . . 148
Comparing class national and class numeric
operands . . . . . . . . . . . . . . 148
Chapter 6. Handling strings . . . . . 105
Comparing national numeric and other numeric
Joining data items (STRING) . . . . . . . . 105
operands . . . . . . . . . . . . . . 149
Example: STRING statement . . . . . . . 106
Comparing national and other character-string
Splitting data items (UNSTRING) . . . . . . 107
operands . . . . . . . . . . . . . . 149
Example: UNSTRING statement . . . . . . 108
Comparing national data and
Manipulating null-terminated strings . . . . . 110
alphanumeric-group operands . . . . . . . 149
Example: null-terminated strings . . . . . . 111
Coding for use of DBCS support . . . . . . . 150
Referring to substrings of data items. . . . . . 111
| Defining DBCS data . . . . . . . . . . 150
Reference modifiers . . . . . . . . . . 113
Using DBCS literals . . . . . . . . . . 150
Testing for valid DBCS characters . . . . . 151
iv Enterprise COBOL for z/OS, V5.2 Programming Guide
Processing alphanumeric data items that contain Creating alternate indexes . . . . . . . . 204
DBCS data . . . . . . . . . . . . . 152 Allocating VSAM files . . . . . . . . . 206
Sharing VSAM files through RLS . . . . . . 207
Chapter 8. Processing files . . . . . 153 Allocation of record areas for VSAM files . . . . 209
File organization and input-output devices . . . 153 Improving VSAM performance . . . . . . . 209
Choosing file organization and access mode . . . 155 | Extended addressability support . . . . . . . 211
Format for coding input and output . . . . . 156
Allocating files . . . . . . . . . . . . . 157 Chapter 11. Processing line-sequential
Checking for input or output errors . . . . . . 158 files . . . . . . . . . . . . . . . 213
Defining line-sequential files and records in
Chapter 9. Processing QSAM files . . 159 COBOL . . . . . . . . . . . . . . . 213
Defining QSAM files and records in COBOL . . . 159 Describing the structure of a line-sequential file 214
Establishing record formats. . . . . . . . 160 Control characters in line-sequential files . . . 214
Setting block sizes . . . . . . . . . . . 167 Allocating line-sequential files . . . . . . . . 214
Coding input and output statements for QSAM Coding input-output statements for line-sequential
files . . . . . . . . . . . . . . . . 170 files . . . . . . . . . . . . . . . . 215
Opening QSAM files . . . . . . . . . . 170 Opening line-sequential files . . . . . . . 216
Dynamically creating QSAM files. . . . . . 171 Reading records from line-sequential files . . . 216
Adding records to QSAM files. . . . . . . 172 Adding records to line-sequential files . . . . 217
Updating QSAM files . . . . . . . . . 172 Closing line-sequential files. . . . . . . . 217
Writing QSAM files to a printer or spooled data Handling errors in line-sequential files . . . . . 218
set . . . . . . . . . . . . . . . . 172
Closing QSAM files . . . . . . . . . . 173 Chapter 12. Sorting and merging files 219
Handling errors in QSAM files . . . . . . . 174 Sort and merge process . . . . . . . . . . 220
Working with QSAM files . . . . . . . . . 174 Describing the sort or merge file . . . . . . . 220
Defining and allocating QSAM files . . . . . 174 Describing the input to sorting or merging . . . 221
Retrieving QSAM files . . . . . . . . . 177 Example: describing sort and input files for
Ensuring that file attributes match your SORT . . . . . . . . . . . . . . . 221
program . . . . . . . . . . . . . . 178 Coding the input procedure . . . . . . . . 222
Using striped extended-format QSAM data sets 180 Describing the output from sorting or merging . . 223
Allocation of buffers for QSAM files. . . . . 181 Coding the output procedure . . . . . . . . 224
Accessing z/OS UNIX files using QSAM . . . . 181 Example: coding the output procedure when
Processing QSAM ASCII files on tape . . . . . 182 using DFSORT . . . . . . . . . . . . 224
Restrictions on input and output procedures . . . 225
Chapter 10. Processing VSAM files 185 Defining sort and merge data sets . . . . . . 225
VSAM files . . . . . . . . . . . . . . 186 Sorting variable-length records . . . . . . . 226
Defining VSAM file organization and records . . 187 Requesting the sort or merge . . . . . . . . 226
Specifying sequential organization for VSAM Setting sort or merge criteria . . . . . . . 227
files . . . . . . . . . . . . . . . 188 Example: sorting with input and output
Specifying indexed organization for VSAM files 188 procedures . . . . . . . . . . . . . 228
Specifying relative organization for VSAM files 190 Choosing alternate collating sequences . . . . 229
Specifying access modes for VSAM files . . . 191 Preserving the original sequence of records with
Defining record lengths for VSAM files. . . . 191 equal keys . . . . . . . . . . . . . 230
Coding input and output statements for VSAM Determining whether the sort or merge was
files . . . . . . . . . . . . . . . . 193 successful . . . . . . . . . . . . . . 230
File position indicator . . . . . . . . . 195 Stopping a sort or merge operation prematurely 231
Opening a file (ESDS, KSDS, or RRDS) . . . . 195 Improving sort performance with FASTSRT . . . 231
Reading records from a VSAM file . . . . . 198 FASTSRT requirements for JCL . . . . . . 231
Updating records in a VSAM file . . . . . . 199 FASTSRT requirements for sort input and
Adding records to a VSAM file . . . . . . 199 output files . . . . . . . . . . . . . 231
Replacing records in a VSAM file. . . . . . 200 Checking for sort errors with NOFASTSRT . . . 233
Deleting records from a VSAM file . . . . . 200 Controlling sort behavior . . . . . . . . . 234
Closing VSAM files . . . . . . . . . . 200 Changing DFSORT defaults with control
Handling errors in VSAM files . . . . . . . 201 statements . . . . . . . . . . . . . 235
Protecting VSAM files with a password . . . . 202 Allocating storage for sort or merge operations 235
Example: password protection for a VSAM Allocating space for sort files . . . . . . . 236
indexed file . . . . . . . . . . . . . 202 Using checkpoint/restart with DFSORT . . . . 236
Working with VSAM data sets under z/OS and Sorting under CICS . . . . . . . . . . . 237
z/OS UNIX . . . . . . . . . . . . . . 202 CICS SORT application restrictions . . . . . 237
Defining VSAM files . . . . . . . . . . 203
Contents v
Chapter 13. Handling errors . . . . . 239 Messages and listings for compiler-detected
Requesting dumps . . . . . . . . . . . 239 errors . . . . . . . . . . . . . . . 280
Handling errors in joining and splitting strings . . 240 Format of compiler diagnostic messages . . . 281
Handling errors in arithmetic operations . . . . 240 Severity codes for compiler diagnostic messages 282
Example: checking for division by zero . . . . 241
Handling errors in input and output operations 241 Chapter 15. Compiling under z/OS
Using the end-of-file condition (AT END) . . . 243 UNIX . . . . . . . . . . . . . . . 283
Coding ERROR declaratives . . . . . . . 244 Setting environment variables under z/OS UNIX 283
Using file status keys . . . . . . . . . . 245 Specifying compiler options under z/OS UNIX . . 284
Example: file status key . . . . . . . . . 246 Compiling and linking with the cob2 command 285
Using VSAM status codes (VSAM files only) 246 Creating a DLL under z/OS UNIX . . . . . 286
Example: checking VSAM status codes . . . . 247 Example: using cob2 to compile and link under
Coding INVALID KEY phrases . . . . . . 249 z/OS UNIX . . . . . . . . . . . . . 286
Example: FILE STATUS and INVALID KEY . . 249 cob2 syntax and options . . . . . . . . . 287
Handling errors when calling programs . . . . 250 cob2 input and output files . . . . . . . . 288
Writing routines for handling errors . . . . . . 250 Compiling using scripts . . . . . . . . . . 290
Part 2. Compiling and debugging Chapter 16. Compiling, linking, and
your program . . . . . . . . . . 253 running OO applications . . . . . . 291
Compiling, linking, and running OO applications
Chapter 14. Compiling under z/OS 255 under z/OS UNIX. . . . . . . . . . . . 291
Compiling with JCL . . . . . . . . . . . 255 Compiling OO applications under z/OS UNIX 291
Using a cataloged procedure . . . . . . . 256 Preparing OO applications under z/OS UNIX 292
Writing JCL to compile programs. . . . . . 260 Example: compiling and linking a COBOL class
Compiling under TSO . . . . . . . . . . 262 definition under z/OS UNIX . . . . . . . 293
Example: ALLOCATE and CALL for compiling Running OO applications under z/OS UNIX 293
under TSO . . . . . . . . . . . . . 263 Compiling, linking, and running OO applications
Example: CLIST for compiling under TSO . . . 264 in JCL or TSO/E . . . . . . . . . . . . 295
Starting the compiler from an assembler program 265 Compiling OO applications in JCL or TSO/E 295
Defining compiler input and output . . . . . . 266 Preparing and running OO applications in JCL
Data sets used by the compiler under z/OS . . 267 or TSO/E. . . . . . . . . . . . . . 296
Defining the source code data set (SYSIN) . . . 269 Example: compiling, linking, and running an
Defining a compiler-option data set (SYSOPTF) 269 OO application using JCL . . . . . . . . 298
Specifying source libraries (SYSLIB) . . . . . 270 Using Java SDKs for z/OS . . . . . . . . . 299
Defining the output data set (SYSPRINT) . . . 270 | Object-oriented syntax, and Java 6, Java 7, or
Directing compiler messages to your terminal | Java 8 . . . . . . . . . . . . . . . 300
(SYSTERM) . . . . . . . . . . . . . 271
Creating object code (SYSLIN or SYSPUNCH) 271 Chapter 17. Compiler options . . . . 301
Defining an associated-data file (SYSADATA) 271 | Option settings for 85 COBOL Standard
Defining the Java-source output file (SYSJAVA) 272 conformance. . . . . . . . . . . . . . 304
Defining the library-processing output file Conflicting compiler options . . . . . . . . 304
(SYSMDECK) . . . . . . . . . . . . 272 ADATA . . . . . . . . . . . . . . . 305
Specifying compiler options under z/OS . . . . 272 ADV . . . . . . . . . . . . . . . . 306
Specifying compiler options in the PROCESS AFP . . . . . . . . . . . . . . . . 306
(CBL) statement . . . . . . . . . . . 273 ARCH. . . . . . . . . . . . . . . . 307
Example: specifying compiler options using JCL 274 ARITH . . . . . . . . . . . . . . . 309
Example: specifying compiler options under AWO . . . . . . . . . . . . . . . . 310
TSO . . . . . . . . . . . . . . . 274 BLOCK0 . . . . . . . . . . . . . . . 310
Compiler options and compiler output under BUFSIZE . . . . . . . . . . . . . . . 311
z/OS . . . . . . . . . . . . . . . 274 CICS . . . . . . . . . . . . . . . . 312
Compiling multiple programs (batch compilation) 275 CODEPAGE . . . . . . . . . . . . . . 313
Example: batch compilation . . . . . . . 276 COMPILE . . . . . . . . . . . . . . 316
Specifying compiler options in a batch | COPYRIGHT . . . . . . . . . . . . . 316
compilation . . . . . . . . . . . . . 277 CURRENCY . . . . . . . . . . . . . . 317
Example: precedence of options in a batch DATA . . . . . . . . . . . . . . . . 318
compilation . . . . . . . . . . . . . 278 DBCS . . . . . . . . . . . . . . . . 318
Example: LANGUAGE option in a batch DECK . . . . . . . . . . . . . . . . 319
compilation . . . . . . . . . . . . . 278 DIAGTRUNC . . . . . . . . . . . . . 319
Correcting errors in your source program . . . . 279 DISPSIGN . . . . . . . . . . . . . . 320
Generating a list of compiler messages . . . . 280 DLL . . . . . . . . . . . . . . . . 321
vi Enterprise COBOL for z/OS, V5.2 Programming Guide
DUMP . . . . . . . . . . . . . . . 322 Chapter 18. Compiler-directing
DYNAM . . . . . . . . . . . . . . . 323 statements . . . . . . . . . . . . 373
EXIT . . . . . . . . . . . . . . . . 324
EXPORTALL . . . . . . . . . . . . . 326
FASTSRT . . . . . . . . . . . . . . . 327
Chapter 19. Debugging . . . . . . . 377
FLAG . . . . . . . . . . . . . . . . 327 Debugging with source language . . . . . . . 377
FLAGSTD . . . . . . . . . . . . . . 328 Tracing program logic . . . . . . . . . 378
HGPR . . . . . . . . . . . . . . . . 330 Finding and handling input-output errors . . . 379
INTDATE . . . . . . . . . . . . . . 331 Validating data . . . . . . . . . . . . 379
LANGUAGE . . . . . . . . . . . . . 331 Moving, initializing or setting uninitialized data 380
LINECOUNT . . . . . . . . . . . . . 332 Generating information about procedures . . . 380
LIST . . . . . . . . . . . . . . . . 333 Debugging using compiler options . . . . . . 382
MAP . . . . . . . . . . . . . . . . 333 Finding coding errors . . . . . . . . . 382
MAXPCF . . . . . . . . . . . . . . . 335 Finding line sequence problems . . . . . . 383
MDECK . . . . . . . . . . . . . . . 336 Checking for valid ranges . . . . . . . . 383
NAME . . . . . . . . . . . . . . . 337 Selecting the level of error to be diagnosed . . 384
NSYMBOL . . . . . . . . . . . . . . 338 Finding program entity definitions and
NUMBER . . . . . . . . . . . . . . 339 references . . . . . . . . . . . . . 386
NUMPROC . . . . . . . . . . . . . . 339 Listing data items . . . . . . . . . . . 386
OBJECT . . . . . . . . . . . . . . . 340 Using the debugger . . . . . . . . . . . 387
OFFSET . . . . . . . . . . . . . . . 341 Getting listings . . . . . . . . . . . . . 387
OPTFILE . . . . . . . . . . . . . . . 342 Example: short listing . . . . . . . . . 389
OPTIMIZE . . . . . . . . . . . . . . 343 Example: SOURCE and NUMBER output . . . 391
OUTDD . . . . . . . . . . . . . . . 344 Example: MAP output . . . . . . . . . 392
PGMNAME . . . . . . . . . . . . . . 345 Reading LIST output . . . . . . . . . . 397
PGMNAME(COMPAT) . . . . . . . . . 345 Example: XREF output: data-name
PGMNAME(LONGUPPER). . . . . . . . 346 cross-references . . . . . . . . . . . . 411
PGMNAME(LONGMIXED) . . . . . . . 346 Example: OFFSET compiler output . . . . . 415
Usage notes . . . . . . . . . . . . . 347 Example: VBREF compiler output . . . . . 415
| QUALIFY . . . . . . . . . . . . . . 347
QUOTE/APOST . . . . . . . . . . . . 348 Part 3. Targeting COBOL programs
RENT . . . . . . . . . . . . . . . . 348 for certain environments . . . . . 417
RMODE . . . . . . . . . . . . . . . 349
| RULES . . . . . . . . . . . . . . . 350
SEQUENCE . . . . . . . . . . . . . . 352 Chapter 20. Developing COBOL
| SERVICE . . . . . . . . . . . . . . . 353 programs for CICS . . . . . . . . . 419
SOURCE . . . . . . . . . . . . . . . 353 Coding COBOL programs to run under CICS . . 419
SPACE . . . . . . . . . . . . . . . 354 Getting the system date under CICS. . . . . 421
SQL . . . . . . . . . . . . . . . . 354 Calling to or from COBOL programs . . . . 421
SQLCCSID . . . . . . . . . . . . . . 355 Determining the success of ECI calls. . . . . 423
SQLIMS . . . . . . . . . . . . . . . 356 Compiling with the CICS option . . . . . . . 423
SSRANGE . . . . . . . . . . . . . . 357 Separating CICS suboptions . . . . . . . 425
STGOPT . . . . . . . . . . . . . . . 358 Integrated CICS translator . . . . . . . . 425
TERMINAL . . . . . . . . . . . . . . 359 Using the separate CICS translator . . . . . . 426
TEST . . . . . . . . . . . . . . . . 359 CICS reserved-word table . . . . . . . . . 427
THREAD . . . . . . . . . . . . . . . 362 Handling errors by using CICS HANDLE . . . . 428
TRUNC . . . . . . . . . . . . . . . 363 Example: handling errors by using CICS
TRUNC example 1 . . . . . . . . . . 364 HANDLE . . . . . . . . . . . . . 429
TRUNC example 2 . . . . . . . . . . 365
VBREF . . . . . . . . . . . . . . . 366 Chapter 21. Programming for a DB2
| VLR . . . . . . . . . . . . . . . . 366 environment . . . . . . . . . . . . 431
WORD . . . . . . . . . . . . . . . 367 DB2 coprocessor . . . . . . . . . . . . 431
| XMLPARSE . . . . . . . . . . . . . . 368 Coding SQL statements . . . . . . . . . . 432
XREF . . . . . . . . . . . . . . . . 369 Using SQL INCLUDE with the DB2 coprocessor 432
| ZONEDATA. . . . . . . . . . . . . . 370 Using character data in SQL statements . . . 433
ZWB . . . . . . . . . . . . . . . . 372 Using national decimal data in SQL statements 434
Using national group items in SQL statements 434
Using binary items in SQL statements . . . . 435
Determining the success of SQL statements . . 435
Compiling with the SQL option . . . . . . . 435
Separating DB2 suboptions . . . . . . . . 436
Contents vii
COBOL and DB2 CCSID determination. . . . . 437 Chapter 24. Using subprograms . . . 463
Code-page determination for string host Main programs, subprograms, and calls . . . . 463
variables in SQL statements . . . . . . . 437 Ending and reentering main programs or
Programming with the SQLCCSID or subprograms . . . . . . . . . . . . . 464
NOSQLCCSID option . . . . . . . . . 438 Transferring control to another program . . . . 465
Differences in how the DB2 precompiler and Making static calls. . . . . . . . . . . 466
coprocessor behave . . . . . . . . . . . 439 Making dynamic calls . . . . . . . . . 467
Period at the end of EXEC SQL INCLUDE AMODE switching . . . . . . . . . . 469
statements . . . . . . . . . . . . . 439 Performance considerations of static and
EXEC SQL INCLUDE and nested COPY dynamic calls . . . . . . . . . . . . 471
REPLACING . . . . . . . . . . . . 439 Making both static and dynamic calls . . . . 471
EXEC SQL and REPLACE or COPY Examples: static and dynamic CALL statements 472
REPLACING . . . . . . . . . . . . 439 Calling nested COBOL programs . . . . . . 473
Source code after an END-EXEC statement . . 440 Making recursive calls . . . . . . . . . . 477
Multiple definitions of host variables . . . . 440 Calling to and from object-oriented programs . . 477
EXEC SQL statement continuation lines . . . 440 Using procedure and function pointers . . . . . 477
Bit-data host variables . . . . . . . . . 440 Deciding which type of pointer to use . . . . 479
SQL-INIT-FLAG . . . . . . . . . . . 440 Calling alternate entry points . . . . . . . 479
Choosing the DYNAM or NODYNAM compiler Making programs reentrant . . . . . . . . 480
option . . . . . . . . . . . . . . . . 441
Chapter 25. Sharing data . . . . . . 481
Chapter 22. Developing COBOL Passing data . . . . . . . . . . . . . . 481
programs for IMS. . . . . . . . . . 443 Describing arguments in the calling program 483
IMS SQL coprocessor . . . . . . . . . . . 443 Describing parameters in the called program 484
Coding SQLIMS statements . . . . . . . . 444 Testing for OMITTED arguments . . . . . . 485
Using SQLIMS INCLUDE with the IMS SQL Coding the LINKAGE SECTION . . . . . . . 485
coprocessor . . . . . . . . . . . . . 444 Coding the PROCEDURE DIVISION for passing
Using character data in SQLIMS statements . . 445 arguments . . . . . . . . . . . . . . 486
Using binary items in SQLIMS statements . . . 445 Grouping data to be passed . . . . . . . 486
Determining the success of SQLIMS statements 445 Handling null-terminated strings . . . . . . 486
Compiling with the SQLIMS option . . . . . . 445 Using pointers to process a chained list . . . 487
Separating IMS suboptions . . . . . . . . 446 Passing return-code information . . . . . . . 490
Compiling and linking COBOL programs for Using the RETURN-CODE special register. . . 490
running under IMS . . . . . . . . . . . 447 Using PROCEDURE DIVISION RETURNING . .
Using object-oriented COBOL and Java under IMS 448 .. . . . . . . . . . . . . . . . . 490
Calling a COBOL method from a Java Specifying CALL . . . RETURNING . . . . . 491
application under IMS . . . . . . . . . 448 Sharing data by using the EXTERNAL clause. . . 491
Building a mixed COBOL-Java application that Sharing files between programs (external files) . . 491
starts with COBOL . . . . . . . . . . 449 Example: using external files . . . . . . . 492
Writing mixed-language IMS applications . . . 449 Accessing main program parameters under z/OS 495
Example: accessing main program parameters
Chapter 23. Running COBOL under z/OS . . . . . . . . . . . . . 495
programs under z/OS UNIX . . . . . 453
Running in z/OS UNIX environments . . . . . 453 Chapter 26. Creating a DLL or a DLL
Setting and accessing environment variables . . . 454 application . . . . . . . . . . . . 497
Setting environment variables that affect Dynamic link libraries (DLLs) . . . . . . . . 497
execution . . . . . . . . . . . . . . 455 Compiling programs to create DLLs . . . . . . 498
Runtime environment variables . . . . . . 455 Linking DLLs . . . . . . . . . . . . . 499
Example: setting and accessing environment Example: sample JCL for a procedural DLL
variables . . . . . . . . . . . . . . 456 application . . . . . . . . . . . . . . 500
Calling UNIX/POSIX APIs . . . . . . . . . 456 Using CALL identifier with DLLs . . . . . . 500
Accessing main program parameters under z/OS Search order for DLLs in the z/OS UNIX file
UNIX . . . . . . . . . . . . . . . . 458 system . . . . . . . . . . . . . . 501
Example: accessing main program parameters Using DLL linkage and dynamic calls together . . 502
under z/OS UNIX. . . . . . . . . . . 459 Using procedure or function pointers with DLLs 503
Calling DLLs from non-DLLs . . . . . . . 503
Example: calling DLLs from non-DLLs . . . . 504
Part 4. Structuring complex
Using COBOL DLLs with C/C++ programs . . . 505
applications . . . . . . . . . . . 461 Using DLLs in OO COBOL applications . . . . 506
viii Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 27. Preparing COBOL Chapter 30. Writing object-oriented
programs for multithreading . . . . . 507 programs . . . . . . . . . . . . . 579
Multithreading . . . . . . . . . . . . . 508 Example: accounts. . . . . . . . . . . . 580
Choosing THREAD to support multithreading . . 509 Subclasses . . . . . . . . . . . . . 581
Transferring control to multithreaded programs 509 Defining a class . . . . . . . . . . . . 582
Ending multithreaded programs . . . . . . . 510 CLASS-ID paragraph for defining a class . . . 584
Processing files with multithreading . . . . . . 510 REPOSITORY paragraph for defining a class 584
File-definition (FD) storage . . . . . . . . 511 WORKING-STORAGE SECTION for defining
Serializing file access with multithreading . . . 511 class instance data . . . . . . . . . . . 586
Example: usage patterns of file input and Example: defining a class . . . . . . . . 587
output with multithreading. . . . . . . . 512 Defining a class instance method . . . . . . . 587
Handling COBOL limitations with multithreading 512 METHOD-ID paragraph for defining a class
instance method . . . . . . . . . . . 588
INPUT-OUTPUT SECTION for defining a class
Part 5. Using XML and COBOL instance method . . . . . . . . . . . 589
together . . . . . . . . . . . . . 515 DATA DIVISION for defining a class instance
method . . . . . . . . . . . . . . 589
Chapter 28. Processing XML input 517 PROCEDURE DIVISION for defining a class
XML parser in COBOL . . . . . . . . . . 518 instance method . . . . . . . . . . . 590
Accessing XML documents . . . . . . . . . 520 Overriding an instance method . . . . . . 591
Parsing XML documents . . . . . . . . . 520 Overloading an instance method . . . . . . 592
Writing procedures to process XML . . . . . 522 Coding attribute (get and set) methods . . . . 593
XML events . . . . . . . . . . . . . 524 Example: defining a method . . . . . . . 594
Transforming XML text to COBOL data items 529 Defining a client . . . . . . . . . . . . 596
Parsing XML documents with validation . . . 530 REPOSITORY paragraph for defining a client 597
Parsing XML documents one segment at a time 533 DATA DIVISION for defining a client . . . . 598
Handling splits using the XML-INFORMATION Comparing and setting object references . . . 599
special register . . . . . . . . . . . . 535 Invoking methods (INVOKE) . . . . . . . 600
The encoding of XML documents. . . . . . . 536 Creating and initializing instances of classes . . 604
XML input document encoding . . . . . . 537 Freeing instances of classes . . . . . . . . 606
Parsing XML documents encoded in UTF-8 . . 541 Example: defining a client . . . . . . . . 606
Handling XML PARSE exceptions . . . . . . 542 Defining a subclass . . . . . . . . . . . 607
How the XML parser handles errors. . . . . 544 CLASS-ID paragraph for defining a subclass 608
| Handling encoding conflicts . . . . . . . 545 REPOSITORY paragraph for defining a subclass 608
Terminating XML parsing . . . . . . . . . 546 WORKING-STORAGE SECTION for defining
XML PARSE examples . . . . . . . . . . 547 subclass instance data . . . . . . . . . 609
Example: parsing a simple document . . . . 547 Defining a subclass instance method . . . . 609
Example: program for processing XML . . . . 548 Example: defining a subclass (with methods) 610
Example: parsing an XML document that uses Defining a factory section . . . . . . . . . 611
namespaces . . . . . . . . . . . . . 553 WORKING-STORAGE SECTION for defining
Example: parsing an XML document one factory data . . . . . . . . . . . . . 612
segment at a time . . . . . . . . . . . 556 Defining a factory method . . . . . . . . 612
Example: parsing XML documents with Example: defining a factory (with methods) . . 615
validation . . . . . . . . . . . . . 558 Wrapping procedure-oriented COBOL programs 620
Structuring OO applications . . . . . . . . 620
Chapter 29. Producing XML output 561 Examples: COBOL applications that run using
Generating XML output . . . . . . . . . . 561 the java command . . . . . . . . . . . 621
Controlling the encoding of generated XML output 566
Handling XML GENERATE exceptions . . . . . 567 Chapter 31. Communicating with Java
Example: generating XML . . . . . . . . . 568 methods . . . . . . . . . . . . . 623
Program XGFX . . . . . . . . . . . . 568 Accessing JNI services . . . . . . . . . . 623
Program Pretty . . . . . . . . . . . . 570 Handling Java exceptions . . . . . . . . 624
Output from program XGFX . . . . . . . 572 Managing local and global references . . . . 626
Enhancing XML output . . . . . . . . . . 573 Java access controls . . . . . . . . . . 627
Example: enhancing XML output . . . . . . 573 Sharing data with Java . . . . . . . . . . 627
Coding interoperable data types in COBOL and
Part 6. Developing object-oriented Java . . . . . . . . . . . . . . . 628
Declaring arrays and strings for Java . . . . 629
programs . . . . . . . . . . . . 577 Manipulating Java arrays . . . . . . . . 630
Manipulating Java strings . . . . . . . . 632
Contents ix
Example: J2EE client written in COBOL . . . . 634 | Using the format 2 SORT statement to sort a table 671
COBOL client (ConverterClient.cbl) . . . . . 635
Java client (ConverterClient.java) . . . . . . 637
Part 9. Appendixes . . . . . . . . 673
Part 7. Specialized processing . . 639 Appendix A. Intermediate results and
arithmetic precision . . . . . . . . 675
Chapter 32. Interrupts and Terminology used for intermediate results . . . . 676
checkpoint/restart . . . . . . . . . 641 Example: calculation of intermediate results . . . 677
Setting checkpoints . . . . . . . . . . . 641 Fixed-point data and intermediate results . . . . 677
Designing checkpoints . . . . . . . . . 642 Addition, subtraction, multiplication, and
Testing for a successful checkpoint . . . . . 642 division . . . . . . . . . . . . . . 677
DD statements for defining checkpoint data sets 643 Exponentiation . . . . . . . . . . . . 678
Messages generated during checkpoint . . . . 644 Example: exponentiation in fixed-point
Restarting programs . . . . . . . . . . . 644 arithmetic . . . . . . . . . . . . . 679
Requesting automatic restart . . . . . . . 645 Truncated intermediate results. . . . . . . 680
Requesting deferred restart . . . . . . . . 645 Binary data and intermediate results . . . . 680
Formats for requesting deferred restart . . . . 646 Intrinsic functions evaluated in fixed-point
Resubmitting jobs for restart . . . . . . . 647 arithmetic . . . . . . . . . . . . . . 680
Example: restarting a job at a specific Integer functions . . . . . . . . . . . 680
checkpoint step. . . . . . . . . . . . 647 Mixed functions . . . . . . . . . . . 681
Example: requesting a step restart . . . . . 647 Floating-point data and intermediate results . . . 682
Example: resubmitting a job for a step restart 647 Exponentiations evaluated in floating-point
Example: resubmitting a job for a checkpoint arithmetic . . . . . . . . . . . . . 683
restart . . . . . . . . . . . . . . . 648 Intrinsic functions evaluated in floating-point
arithmetic . . . . . . . . . . . . . 683
Arithmetic expressions in nonarithmetic statements 683
Part 8. Improving performance and
productivity . . . . . . . . . . . 649 Appendix B. Converting double-byte
character set (DBCS) data . . . . . . 685
Chapter 33. Tuning your program . . . 651 DBCS notation . . . . . . . . . . . . . 685
Using an optimal programming style . . . . . 651 Alphanumeric to DBCS data conversion
Using structured programming . . . . . . 652 (IGZCA2D) . . . . . . . . . . . . . . 685
Factoring expressions. . . . . . . . . . 652 IGZCA2D syntax . . . . . . . . . . . 685
Using symbolic constants . . . . . . . . 652 IGZCA2D return codes . . . . . . . . . 686
Choosing efficient data types . . . . . . . . 652 Example: IGZCA2D . . . . . . . . . . 687
Choosing efficient computational data items . . 653 DBCS to alphanumeric data conversion (IGZCD2A) 688
Using consistent data types. . . . . . . . 653 IGZCD2A syntax . . . . . . . . . . . 688
Making arithmetic expressions efficient . . . . 654 IGZCD2A return codes . . . . . . . . . 689
Making exponentiations efficient . . . . . . 654 Example: IGZCD2A . . . . . . . . . . 689
| Using VOLATILE clauses efficiently . . . . . 654
Handling tables efficiently . . . . . . . . . 654
Optimization of table references . . . . . . 656
Appendix C. XML reference material 691
Optimizing your code . . . . . . . . . . 657 | XML PARSE exceptions with XMLPARSE(XMLSS)
Optimization . . . . . . . . . . . . 657 | in effect . . . . . . . . . . . . . . . 691
Choosing compiler features to enhance | XML PARSE exceptions with
performance . . . . . . . . . . . . . . 658 | XMLPARSE(COMPAT) in effect . . . . . . . 693
Performance-related compiler options . . . . 659 | XML PARSE exceptions that allow continuation 693
Evaluating performance . . . . . . . . . 662 | XML PARSE exceptions that do not allow
Running efficiently with CICS, IMS, or VSAM . . 662 | continuation . . . . . . . . . . . . . 697
Choosing static or dynamic calls . . . . . . . 663 XML GENERATE exceptions . . . . . . . . 700
Chapter 34. Simplifying coding . . . . 665 Appendix D. EXIT compiler option . . 701
Eliminating repetitive coding . . . . . . . . 665 Using the user-exit work area . . . . . . . . 701
Example: using the COPY statement. . . . . 666 Calling from exit modules . . . . . . . . . 702
Using Language Environment callable services . . 667 Processing of INEXIT. . . . . . . . . . . 702
Sample list of Language Environment callable INEXIT parameters . . . . . . . . . . 702
services . . . . . . . . . . . . . . 668 Processing of LIBEXIT . . . . . . . . . . 703
Calling Language Environment services . . . 669 Processing of LIBEXIT with nested COPY
Example: Language Environment callable statements . . . . . . . . . . . . . 704
services . . . . . . . . . . . . . . 670 LIBEXIT parameters . . . . . . . . . . 705
x Enterprise COBOL for z/OS, V5.2 Programming Guide
Processing of PRTEXIT . . . . . . . . . . 706 Symbol cross-reference record: X'0044' . . . . . 787
PRTEXIT parameters . . . . . . . . . . 707 Nested program record: X'0046' . . . . . . . 788
Processing of ADEXIT . . . . . . . . . . 707 Library record: X'0060' . . . . . . . . . . 789
ADEXIT parameters . . . . . . . . . . 708 Statistics record: X'0090' . . . . . . . . . . 789
Processing of MSGEXIT . . . . . . . . . . 709 EVENTS record: X'0120' . . . . . . . . . . 790
MSGEXIT parameters . . . . . . . . . 709
Customizing compiler-message severities . . . 710 Appendix G. Using sample programs 795
Example: MSGEXIT user exit . . . . . . . 713 IGYTCARA: batch application . . . . . . . . 795
Error handling for exit modules . . . . . . . 717 Input data for IGYTCARA . . . . . . . . 796
Using the EXIT compiler option with CICS, SQL Report produced by IGYTCARA . . . . . . 797
and SQLIMS statements . . . . . . . . . . 718 Preparing to run IGYTCARA . . . . . . . 798
IGYTCARB: interactive program . . . . . . . 799
Appendix E. JNI.cpy copybook . . . . 721 Preparing to run IGYTCARB . . . . . . . 800
IGYTSALE: nested program application . . . . 802
Appendix F. COBOL SYSADATA file Input data for IGYTSALE . . . . . . . . 803
contents . . . . . . . . . . . . . 727 Reports produced by IGYTSALE . . . . . . 805
Preparing to run IGYTSALE . . . . . . . 808
Compiler options that affect the SYSADATA file 727
Language elements and concepts that are
SYSADATA record types . . . . . . . . . 728
illustrated . . . . . . . . . . . . . . 809
Example: SYSADATA . . . . . . . . . . 729
SYSADATA record descriptions . . . . . . . 730
Common header section . . . . . . . . . . 731 Notices . . . . . . . . . . . . . . 815
Job identification record: X'0000' . . . . . . . 733 Trademarks . . . . . . . . . . . . . . 817
ADATA identification record: X'0001' . . . . . 734
Compilation unit start | end record: X'0002' . . . 734 Glossary . . . . . . . . . . . . . 819
Options record: X'0010' . . . . . . . . . . 735
External symbol record: X'0020' . . . . . . . 744 List of resources . . . . . . . . . . 853
Parse tree record: X'0024' . . . . . . . . . 745 Enterprise COBOL for z/OS . . . . . . . . 853
Token record: X'0030' . . . . . . . . . . . 760 Related publications . . . . . . . . . . . 853
Source error record: X'0032'. . . . . . . . . 774
Source record: X'0038' . . . . . . . . . . 774
COPY REPLACING record: X'0039' . . . . . . 775
Index . . . . . . . . . . . . . . . 855
Symbol record: X'0042' . . . . . . . . . . 776
Contents xi
xii Enterprise COBOL for z/OS, V5.2 Programming Guide
Tables
1. FILE-CONTROL entries . . . . . . . . 6 41. Commands for compiling and linking a
2. FILE SECTION entries . . . . . . . . 12 class definition . . . . . . . . . . . 292
3. Assignment to data items in a program 27 42. java command options for customizing the
4. Effect of RMODE and RENT compiler JVM . . . . . . . . . . . . . . 294
options on the RMODE attribute . . . . . 41 43. Compiler options . . . . . . . . . . 301
5. Ranges in value of COMP-5 data items 49 44. Mutually exclusive compiler options 305
6. Internal representation of numeric items 51 45. EBCDIC multibyte coded character set
7. NUMCLS(PRIM) and valid signs . . . . . 55 identifiers . . . . . . . . . . . . 315
8. NUMCLS(ALT) and valid signs . . . . . 55 46. DISPLAY output with the DISPSIGN(COMPAT)
9. Order of evaluation of arithmetic operators 57 option or the DISPSIGN(SEP) option specified: . 321
10. Numeric intrinsic functions . . . . . . . 58 47. Values of the LANGUAGE compiler option 332
11. Compatibility of math intrinsic functions and | 48. Mapping of removed options to new options 344
callable services . . . . . . . . . . . 59 49. Severity levels of compiler messages 384
12. INTDATE(LILIAN) and compatibility of date 50. Using compiler options to get listings 388
intrinsic functions and callable services. . . 60 51. Terms used in MAP output . . . . . . 395
13. INTDATE(ANSI) and compatibility of date 52. Symbols used in LIST and MAP output 396
intrinsic functions and callable services. . . 60 53. Compiler options in the INFO BYTE section 399
14. Hexadecimal values of the euro sign . . . . 65 54. Signature information bytes . . . . . . 399
15. COBOL statements and national data 126 55. Calls between COBOL and assembler under
16. Intrinsic functions and national character CICS . . . . . . . . . . . . . . 422
data. . . . . . . . . . . . . . . 128 56. Compiler options required for the integrated
17. National group items that are processed CICS translator . . . . . . . . . . . 424
with group semantics . . . . . . . . 136 57. Compiler options required for the separate
18. Encoding and size of alphanumeric, DBCS, CICS translator . . . . . . . . . . . 426
and national data . . . . . . . . . . 137 58. TRUNC compiler options recommended for
19. Summary of file organizations, access the separate CICS translator . . . . . . 427
modes, and record formats of COBOL files . 155 59. Samples with POSIX function calls . . . . 457
20. QSAM file allocation. . . . . . . . . 175 60. Effects of termination statements. . . . . 464
21. Maximum record length of QSAM files 179 61. Methods for passing data in the CALL
22. Comparison of VSAM, COBOL, and statement . . . . . . . . . . . . . 482
non-VSAM terminology. . . . . . . . 185 62. Compiler options for DLL applications 498
23. Comparison of VSAM data-set types 187 63. Binder options for DLL applications 499
24. VSAM file organization, access mode, and 64. Special registers used by the XML parser 522
record format . . . . . . . . . . . 188 | 65. Results of processing-procedure changes to
25. Definition of VSAM fixed-length records 192 | XML-CODE with XMLPARSE(XMLSS) in effect . . 525
26. Definition of VSAM variable-length records 192 | 66. Results of processing-procedure changes to
27. I/O statements for VSAM sequential files 194 | XML-CODE with XMLPARSE(COMPAT) in effect . . 526
28. I/O statements for VSAM relative and 67. Coded character sets for XML documents 537
indexed files . . . . . . . . . . . 194 68. Hexadecimal values of white-space
29. Statements to load records into a VSAM file 197 characters. . . . . . . . . . . . . 538
30. Statements to update records in a VSAM 69. Aliases for XML encoding declarations 540
file . . . . . . . . . . . . . . . 199 70. Hexadecimal values of special characters for
31. Methods for improving VSAM performance 209 various EBCDIC CCSIDs . . . . . . . 540
32. Methods for checking for sort errors with 71. XML events and special registers . . . . 547
NOFASTSRT . . . . . . . . . . . 233 72. XML events and special registers . . . . 553
33. Methods for controlling sort behavior 234 73. XML events and special registers from
34. Compiler data sets . . . . . . . . . 267 parsing XML document with an undeclared
35. Block size of fixed-length compiler data sets 269 namespace prefix . . . . . . . . . . 555
36. Block size of variable-length compiler data 74. Encoding of generated XML if the
sets . . . . . . . . . . . . . . . 269 ENCODING phrase is omitted . . . . . 567
37. Types of compiler output under z/OS 274 75. Structure of class definitions . . . . . . 582
38. Severity codes for compiler diagnostic 76. Structure of instance method definitions 588
messages . . . . . . . . . . . . . 282 77. Structure of COBOL clients . . . . . . 596
39. Input files to the cob2 command . . . . . 288 78. Conformance of arguments in a COBOL
40. Output files from the cob2 command 289 client . . . . . . . . . . . . . . 601
Copyright IBM Corp. 1991, 2015 xiii
79. Conformance of the returned data item in a 106. PRTEXIT processing . . . . . . . . . 706
COBOL client . . . . . . . . . . . 603 107. PRTEXIT parameters . . . . . . . . . 707
80. Structure of factory definitions . . . . . 611 108. ADEXIT processing . . . . . . . . . 708
81. Structure of factory method definitions 613 109. ADEXIT parameters . . . . . . . . . 708
82. JNI services for local and global references 627 110. MSGEXIT processing . . . . . . . . 709
83. Interoperable data types in COBOL and Java 628 111. MSGEXIT parameters . . . . . . . . 710
84. Interoperable arrays and strings in COBOL 112. FIPS (FLAGSTD) message categories . . . . 712
and Java . . . . . . . . . . . . . 629 113. Actions possible in exit modules for CICS,
85. Noninteroperable array types in COBOL SQL and SQLIMS statements . . . . . . 719
and Java . . . . . . . . . . . . . 630 114. SYSADATA record types . . . . . . . 728
86. JNI array services . . . . . . . . . . 630 115. SYSADATA common header section 731
87. Services that convert between jstring 116. SYSADATA job identification record 733
references and national data . . . . . . 632 117. ADATA identification record . . . . . . 734
88. Services that convert between jstring 118. SYSADATA compilation unit start | end
references and alphanumeric data . . . . 633 record . . . . . . . . . . . . . . 734
89. Performance-related compiler options 659 119. SYSADATA options record . . . . . . . 735
90. Performance-tuning worksheet . . . . . 662 120. SYSADATA external symbol record 744
91. Language Environment callable services 668 121. SYSADATA parse tree record . . . . . . 745
| 92. Comparison of format 1 and format 2 SORT 122. SYSADATA token record . . . . . . . 760
| statements . . . . . . . . . . . . 671 123. SYSADATA source error record . . . . . 774
93. IGZCA2D return codes . . . . . . . . 686 124. SYSADATA source record . . . . . . . 774
94. IGZCD2A return codes . . . . . . . . 689 125. SYSADATA COPY REPLACING record 775
95. Reason codes for XML PARSE exceptions 126. SYSADATA symbol record . . . . . . . 776
that are unique to Enterprise COBOL . . . 692 127. SYSADATA symbol cross-reference record 787
| 96. XML PARSE exceptions that allow 128. SYSADATA nested program record . . . . 788
| continuation . . . . . . . . . . . . 693 129. SYSADATA library record . . . . . . . 789
| 97. XML PARSE exceptions that do not allow 130. SYSADATA statistics record . . . . . . 789
| continuation (for XMLPARSE(COMPAT)) . . . . 697 131. SYSADATA EVENTS TIMESTAMP record
98. XML GENERATE exceptions . . . . . . 700 layout . . . . . . . . . . . . . . 790
99. Layout of the user-exit work area . . . . 701 132. SYSADATA EVENTS PROCESSOR record
100. INEXIT processing . . . . . . . . . 702 layout . . . . . . . . . . . . . . 790
101. INEXIT parameters . . . . . . . . . 703 133. SYSADATA EVENTS FILE END record
102. LIBEXIT processing . . . . . . . . . 703 layout . . . . . . . . . . . . . . 791
103. LIBEXIT processing with nonnested COPY 134. SYSADATA EVENTS PROGRAM record
statements . . . . . . . . . . . . 704 layout . . . . . . . . . . . . . . 791
104. LIBEXIT processing with nested COPY 135. SYSADATA EVENTS FILE ID record layout 791
statements . . . . . . . . . . . . 705 136. SYSADATA EVENTS ERROR record layout 792
105. LIBEXIT parameters . . . . . . . . . 705
xiv Enterprise COBOL for z/OS, V5.2 Programming Guide
Preface
About this information
This information is for COBOL programmers and system programmers. It helps
you understand how to use Enterprise COBOL for z/OS to compile COBOL
programs. It also describes the operating system features that you might need to
optimize program performance or handle errors.
For information about COBOL language, and for references needed to write a
program for an IBM COBOL compiler, see the Enterprise COBOL Language
Reference.
Important: Enterprise COBOL for z/OS is referred to as Enterprise COBOL
throughout this information.
How this information will help you
This information will help you write and compile Enterprise COBOL programs. It
will also help you define object-oriented classes and methods, invoke methods, and
refer to objects in your programs.
This information assumes experience in developing application programs and
some knowledge of COBOL. It focuses on using Enterprise COBOL to meet your
programming objectives and not on the definition of the COBOL language. For
complete information about COBOL syntax, see the IBM Enterprise COBOL
Language Reference.
For information about migrating programs to Enterprise COBOL, see the IBM
Enterprise COBOL Migration Guide.
IBM z/OS Language Environment provides the runtime environment and runtime
services that are required to run Enterprise COBOL programs. You can find
information about link-editing and running programs in the IBM z/OS Language
Environment Programming Guide and IBM z/OS Language Environment Programming
Reference.
For a comparison of commonly used Enterprise COBOL and Language
Environment terms, see Comparison of commonly used terms on page xvi.
Abbreviated terms
Certain terms are used in a shortened form in this information. Abbreviations for
the product names used most frequently are listed alphabetically in the following
table.
Term used Long form
CICS CICS Transaction Server
Enterprise COBOL IBM Enterprise COBOL for z/OS
Language Environment IBM z/OS Language Environment
MVS MVS/ESA
z/OS UNIX z/OS UNIX System Services
Copyright IBM Corp. 1991, 2015 xv
| In addition to these abbreviated terms, the term "85 COBOL Standard" is used to
refer to the combination of the following standards:
v ISO 1989:1985, Programming languages - COBOL
v ISO/IEC 1989/AMD1:1992, Programming languages - COBOL: Intrinsic function
module
v ISO/IEC 1989/AMD2:1994, Programming languages - Correction and
clarification amendment for COBOL
v ANSI INCITS 23-1985, Programming Languages - COBOL
v ANSI INCITS 23a-1989, Programming Languages - Intrinsic Function Module for
COBOL
v ANSI INCITS 23b-1993, Programming Language - Correction Amendment for
COBOL
The ISO standards are identical to the American National standards.
Other terms, if not commonly understood, are shown in italics the first time that
they appear, and are listed in the glossary.
Comparison of commonly used terms
To better understand the terms used throughout the IBM z/OS Language
Environment and IBM Enterprise COBOL for z/OS information, and to understand
which terms are meant to be equivalent, see the following table.
Language Environment term Enterprise COBOL equivalent
Aggregate Group item
Array A table created using the OCCURS clause
Array element Table element
Enclave Run unit
External data WORKING-STORAGE data defined using the EXTERNAL
clause
Local data Any non-EXTERNAL data item
Pass parameters directly, by value BY VALUE
Pass parameters indirectly, by BY REFERENCE
reference
Pass parameters indirectly, by value BY CONTENT
Routine Program
Scalar Elementary item
How to read syntax diagrams
Use the following description to read the syntax diagrams in this information.
v Read the syntax diagrams from left to right, from top to bottom, following the
path of the line.
The >>--- symbol indicates the beginning of a syntax diagram.
The ---> symbol indicates that the syntax diagram is continued on the next line.
The >--- symbol indicates that the syntax diagram is continued from the
previous line.
The --->< symbol indicates the end of a syntax diagram.
xvi Enterprise COBOL for z/OS, V5.2 Programming Guide
Diagrams of syntactical units other than complete statements start with the >---
symbol and end with the ---> symbol.
v Required items appear on the horizontal line (the main path):
required_item
v Optional items appear below the main path:
required_item
optional_item
v If you can choose from two or more items, they appear vertically, in a stack. If
you must choose one of the items, one item of the stack appears on the main
path:
required_item required_choice1
required_choice2
If choosing one of the items is optional, the entire stack appears below the main
path:
required_item
optional_choice1
optional_choice2
If one of the items is the default, it appears above the main path and the
remaining choices are shown below:
default_choice
required_item
optional_choice
optional_choice
v An arrow returning to the left, above the main line, indicates an item that can be
repeated:
Preface xvii
required_item repeatable_item
If the repeat arrow contains a comma, you must separate repeated items with a
comma:
required_item repeatable_item
v Keywords appear in uppercase (for example, FROM). They must be spelled exactly
as shown. Variables appear in lowercase italics (for example, column-name). They
represent user-supplied names or values.
v If punctuation marks, parentheses, arithmetic operators, or other such symbols
are shown, you must enter them as part of the syntax.
How examples are shown
This information shows numerous examples of sample COBOL statements,
program fragments, and small programs to illustrate the coding techniques being
described. The examples of program code are written in lowercase, uppercase, or
mixed case to demonstrate that you can write your programs in any of these ways.
To more clearly separate some examples from the explanatory text, they are
presented in a monospace font.
COBOL keywords and compiler options that appear in text are generally shown in
SMALL UPPERCASE. Other terms such as program variable names are sometimes
shown in an italic font for clarity.
Additional documentation and support
IBM Enterprise COBOL for z/OS provides Portable Document Format (PDF)
versions of the entire library for this version and for previous versions on the
product site at www.ibm.com/software/awdtools/cobol/zos/library/.
Support information is also available on the product site at http://www.ibm.com/
support/entry/portal/Overview/Software/Rational/Enterprise_COBOL_for_z~OS
.
Summary of changes
This section lists the major changes that have been made to this document for
| Enterprise COBOL in Version 5. The changes that are described in this information
have an associated cross-reference for your convenience. The latest technical
changes are marked by a vertical bar (|) in the left margin in the PDF version.
xviii Enterprise COBOL for z/OS, V5.2 Programming Guide
| Version 5 Release 2
| v Several changes are made to compiler options:
| The following compiler options are new:
| - COPYRIGHT | NOCOPYRIGHT (COPYRIGHT on page 316)
| - QUALIFY(COMPAT|EXTEND) (QUALIFY on page 347)
| - RULES | NORULES (RULES on page 350)
| - SERVICE | NOSERVICE (SERVICE on page 353)
| - SQLIMS | NOSQLIMS (SQLIMS on page 356)
| - VLR(COMPAT | STANDARD) (VLR on page 366)
| - XMLPARSE(XMLSS | COMPAT) (XMLPARSE on page 368)
| - ZONEDATA(PFD | MIG) (ZONEDATA on page 370)
| The following compiler options are modified:
| - ARCH: ARCH(6) is no longer accepted. A new higher level of ARCH(11) is
| accepted, and ARCH(7) is the default (ARCH on page 307).
| - MAP: New suboptions of HEX and DEC are added to the MAP compiler option
| to control whether hexadecimal or decimal offsets are shown for MAP output
| in the compiler listing (MAP on page 333).
| The following compiler option is removed:
| - SIZE
| 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 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.
| v A new section is added to describe accessing VSAM data sets with the extended
| addressability attribute (Extended addressability support on page 211).
| 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.
| v Enhancements are made to the XML GENERATE statement:
| 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.
Version 5 Release 1 Modification 1
v New fatal and warning exception codes are added for XML PARSE exceptions.
(XML-CODE on page 525)
v The LIST option output in the compiler listing contains a new special register
table that provides the location information for all the COBOL special register
variables. (Example: special register table on page 410)
v A new compiler option, SQLIMS, enables the new IMS SQL coprocessor (called
SQL statement coprocessor by IMS). The new coprocessor handles your source
programs that contain embedded SQLIMS statements.
Preface xix
v Except for a few exception cases, AMODE 24 execution of COBOL programs is
supported. Many programs compiled by Enterprise COBOL V5.1.1 will execute
in AMODE 31 or AMODE 24.
| With current service applied, COBOL V5.1.0 appears to be V5.1.1 and has the
| following new compiler options:
| v SQLIMS | NOSQLIMS (SQLIMS on page 356)
| v VLR(COMPAT | STANDARD) (VLR on page 366)
| v XMLPARSE(XMLSS | COMPAT) (XMLPARSE on page 368)
| v New suboptions of HEX and DEC are added to the MAP compiler option to control
| whether hexadecimal or decimal offsets are shown for MAP output in the
| compiler listing (MAP on page 333).
Version 5 Release 1
v Several changes are made to compiler options:
The following compiler options are new:
- AFP(VOLATILE | NOVOLATILE) (AFP on page 306)
- ARCH(n) (ARCH on page 307)
- DISPSIGN(SEP | COMPAT) (DISPSIGN on page 320)
- HGPR(PRESERVE | NOPRESERVE) (HGPR on page 330)
- MAXPCF(n) (MAXPCF on page 335)
- STGOPT | NOSTGOPT(STGOPT on page 358)
The following compiler options are modified:
- The MDECK option no longer has a dependency on the LIB option.
(MDECK on page 336)
- The MIG suboption of the NUMPROC compiler option is no longer supported.
(NUMPROC on page 339)
- The compiled-in range checks cannot be disabled at run time using the
runtime option NOCHECK. (SSRANGE on page 357)
- Execution of NORENT programs above the 16 MB line is not supported.
(RENT on page 348 and RMODE on page 349)
- The HOOK | NOHOOK and SEPARATE | NOSEPARATE suboptions of the TEST
compiler option are no longer supported, but continue to be tolerated to
ease migration. New suboptions SOURCE and NOSOURCE are added to the TEST
compiler option. (TEST on page 359)
- The NOTEST option is enhanced to include the suboptions DWARF and
NODWARF. (TEST on page 359)
- The EXIT compiler option is no longer mutually exclusive with the DUMP
compiler option, and the compiler exits rules are updated. (EXIT on page
324)
- The OPTIMIZE option is modified to allow several level of optimization.
(OPTIMIZE on page 343)
| The following compiler options have been removed, but continue to be
tolerated to ease migration. Informational or warning diagnostics will be
displayed if you specify any of these options.
- DATEPROC - Year 2000 support is no longer provided.
- LIB - Library processing is always done.
- SIZE(MAX) - This choice has become meaningless.
- YEARWINDOW - Year 2000 support is no longer provided.
xx Enterprise COBOL for z/OS, V5.2 Programming Guide
- XMLPARSE - The XML System Services parser is always used.
v New intrinsic functions are added to provide additional Unicode capability:
ULENGTH
UPOS
USUBSTR
USUPPLEMENTARY
UVALID
UWIDTH
v AMODE 24 execution of programs is no longer supported. Enterprise COBOL
V5.1.0 executable modules must be AMODE 31.
v The IGZERRE and ILBOSTP0 interfaces for managing a reusable COBOL
environment are not supported for applications containing programs compiled
with Enterprise COBOL V5.
v A new special register, XML-INFORMATION, provides a mechanism to easily
determine whether the XML content delivered for an XML event is complete, or
will be continued on the next event. (XML-INFORMATION on page 526)
v The compatibility-mode COBOL XML parser from the COBOL library is no
longer supported. XML PARSE statements in V5 programs always use the z/OS
XML System Services parser.
| v New phrases, NAME, TYPE and SUPPRESS are added to the XML GENERATE
| statement. 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.
v Numerous changes are added to compiler listings. (Reading LIST output on
page 397)
v JCL catalogue procedure changes:
The COBOL compiler now requires 15 utility data sets (SYSUT1 - SYSUT15) and
the SYSMDECK data set when compiling under z/OS TSO or batch. The
following JCL catalogued procedures are modified:
- IGYWC (Compile procedure (IGYWC) on page 257)
- IGYWCL (Compile and link-edit procedure (IGYWCL) on page 258)
- IGYWCLG (Compile, link-edit, and run procedure (IGYWCLG) on page 259)
The following JCL catalogued procedures are no longer supported. Because
they all use the Language Environment Prelinker or the DFSMS Loader,
which are no longer supported.
- IGYWCG
- IGYWCPG
- IGYWCPL
- IGYWCPLG
- IGYWPL
v A new keyword UNBOUNDED is added to the OCCURS clause, which enables you to
work with unbounded tables and groups. (Working with unbounded tables and
groups on page 90)
v For reentrant COBOL programs, VSAM record areas are allocated above 16 MB
by default. (Allocation of record areas for VSAM files on page 209)
v Debugging enhancements:
Preface xxi
With NOLOAD debug segments in the program object, Enterprise COBOL V5
debug data always matches the executable file, and is always available
without giving lists of data sets to search, and does not increase the size of
the loaded program.
For other improvements about Debug Tool with Enterprise COBOL V5, see
Debug Tool changes with IBM Enterprise COBOL, Version 5 in the Enterprise
COBOL Migration Guide.
v Restrictions are added in the interoperability of Enterprise COBOL Version 5
Release 1 with earlier versions of COBOL. For details, see Interoperation with
older levels of Enterprise COBOL programs in the Enterprise COBOL Migration
Guide.
How to send your comments
Your feedback is important in helping us to provide accurate, high-quality
information. If you have comments about this information or any other Enterprise
COBOL documentation, contact us in one of these ways:
v Use the Online Readers' Comments Form at www.ibm.com/software/awdtools/
rcf/.
v Send your comments to the following address: [email protected].
Be sure to include the name of the document, the publication number, the version
of Enterprise COBOL, and, if applicable, the specific location (for example, the
page number or section heading) of the text that you are commenting on.
When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any way that IBM believes appropriate without
incurring any obligation to you.
Accessibility
Accessibility features help users who have a disability, such as restricted mobility
or limited vision, to use information technology products successfully. The
accessibility features in z/OS provide accessibility for Enterprise COBOL.
The major accessibility features in z/OS are:
v Interfaces that are commonly used by screen readers and screen-magnifier
software
v Keyboard-only navigation
v Ability to customize display attributes such as color, contrast, and font size
Interface information
Assistive technology products work with the user interfaces that are found in
z/OS. For specific guidance information, see the documentation for the assistive
technology product that you use to access z/OS interfaces.
Keyboard navigation
Users can access z/OS user interfaces by using TSO/E or ISPF. For information
about accessing TSO/E or ISPF interfaces, see the following publications:
v z/OS TSO/E Primer
v z/OS TSO/E User's Guide
v z/OS ISPF User's Guide Volume I
xxii Enterprise COBOL for z/OS, V5.2 Programming Guide
These guides describe how to use TSO/E and ISPF, including the use of keyboard
shortcuts or function keys (PF keys). Each guide includes the default settings for
the PF keys and explains how to modify their functions.
Accessibility of this information
The English-language XHTML format of this information that will be provided in
the IBM System z Enterprise Development Tools & Compilers Information Center
at publib.boulder.ibm.com/infocenter/pdthelp/index.jsp is accessible to visually
impaired individuals who use a screen reader.
To enable your screen reader to accurately read syntax diagrams, source code
examples, and text that contains the period or comma PICTURE symbols, you must
set the screen reader to speak all punctuation.
IBM and accessibility
See the IBM Human Ability and Accessibility Center at www.ibm.com/able for
more information about the commitment that IBM has to accessibility.
Preface xxiii
xxiv Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 1. Coding your program
Copyright IBM Corp. 1991, 2015 1
2 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 1. Structuring your program
COBOL programs consist of four divisions: IDENTIFICATION DIVISION, ENVIRONMENT
DIVISION, DATA DIVISION, and PROCEDURE DIVISION. Each division has a specific
logical function.
To define a program, only the IDENTIFICATION DIVISION is required.
To define a COBOL class or method, you need to define some divisions differently
than you do for a program.
RELATED TASKS
Identifying a program
Describing the computing environment on page 5
Describing the data on page 11
Processing the data on page 17
Defining a class on page 582
Defining a class instance method on page 587
Structuring OO applications on page 620
Identifying a program
Use the IDENTIFICATION DIVISION to name a program and optionally provide other
identifying information.
You can use the optional AUTHOR, INSTALLATION, DATE-WRITTEN, and DATE-COMPILED
paragraphs for descriptive information about a program. The data you enter in the
DATE-COMPILED paragraph is replaced with the latest compilation date.
IDENTIFICATION DIVISION.
Program-ID. Helloprog.
Author. A. Programmer.
Installation. Computing Laboratories.
Date-Written. 07/30/2009.
Date-Compiled. 03/30/2013.
Use the PROGRAM-ID paragraph to name your program. The program-name that you
assign is used in these ways:
v Other programs use that name to call your program.
v The name appears in the header on each page, except the first, of the program
listing that is generated when you compile the program.
| v If you use the NAME compiler option, the name is placed on the NAME binder
| (linkage-editor) control statement to identify the object module that the
compilation creates.
Tip: Do not use program-names that start with prefixes used by IBM products.
If you use program-names that start with any of the following prefixes, your
CALL statements might resolve to IBM library or compiler routines rather than to
your intended program:
AFB
AFH
CBC
CEE
Copyright IBM Corp. 1991, 2015 3
CEH
CEL
CEQ
CEU
DFH
DSN
EDC
FOR
IBM
IFY
IGY
IGZ
ILB
Tip: If a program-name is case sensitive, avoid mismatches with the name that the
compiler is looking for. Verify that the appropriate setting of the PGMNAME compiler
option is in effect.
RELATED TASKS
Changing the header of a source listing on page 5
Identifying a program as recursive
Marking a program as callable by containing programs
Setting a program to an initial state on page 5
RELATED REFERENCES
Compiler limits (Enterprise COBOL Language Reference)
Conventions for program-names (Enterprise COBOL Language Reference)
Identifying a program as recursive
Code the RECURSIVE attribute on the PROGRAM-ID clause to specify that a program
can be recursively reentered while a previous invocation is still active.
You can code RECURSIVE only on the outermost program of a compilation unit.
Neither nested subprograms nor programs that contain nested subprograms can be
recursive. You must code RECURSIVE for programs that you compile with the THREAD
option.
RELATED TASKS
Sharing data in recursive or multithreaded programs on page 17
Making recursive calls on page 477
Marking a program as callable by containing programs
Use the COMMON attribute in the PROGRAM-ID paragraph to specify that a program can
be called by the containing program or by any program in the containing program.
The COMMON program cannot be called by any program contained in itself.
Only contained programs can have the COMMON attribute.
RELATED CONCEPTS
Nested programs on page 474
4 Enterprise COBOL for z/OS, V5.2 Programming Guide
Setting a program to an initial state
Use the INITIAL clause in the PROGRAM-ID paragraph to specify that whenever a
program is called, that program and any nested programs that it contains are to be
placed in their initial state.
When a program is set to its initial state:
v Data items that have VALUE clauses are set to the specified values.
v Changed GO TO statements and PERFORM statements are in their initial states.
v Non-EXTERNAL files are closed.
RELATED TASKS
Ending and reentering main programs or subprograms on page 464
Making static calls on page 466
Making dynamic calls on page 467
Changing the header of a source listing
The header on the first page of a source listing contains the identification of the
compiler and the current release level, the date and time of compilation, and the
page number.
The following example shows these five elements:
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.0 Date 03/30/2013 Time 15:05:19 Page 1
The header indicates the compilation platform. You can customize the header on
succeeding pages of the listing by using the compiler-directing TITLE statement.
RELATED REFERENCES
TITLE statement (Enterprise COBOL Language Reference)
Describing the computing environment
In the ENVIRONMENT DIVISION of a program, you describe the aspects of the
program that depend on the computing environment.
Use the CONFIGURATION SECTION to specify the following items:
v Computer for compiling the program (in the SOURCE-COMPUTER paragraph)
v Computer for running the program (in the OBJECT-COMPUTER paragraph)
v Special items such as the currency sign and symbolic characters (in the
SPECIAL-NAMES paragraph)
v User-defined classes (in the REPOSITORY paragraph)
Use the FILE-CONTROL and I-O-CONTROL paragraphs of the INPUT-OUTPUT SECTION to:
v Identify and describe the characteristics of the files in the program.
v Associate your files with the external QSAM, VSAM, or z/OS UNIX file system
data sets where they physically reside.
The terms file in COBOL terminology and data set in operating-system
terminology have essentially the same meaning and are used interchangeably in
this information.
For Customer Information Control System (CICS) and online Information
Management System (IMS) message processing programs (MPP), code only the
ENVIRONMENT DIVISION header and, optionally, the CONFIGURATION SECTION. Do
Chapter 1. Structuring your program 5
not code file definitions in your COBOL programs that will run under CICS.
IMS allows COBOL definition of files only for batch programs.
v Provide information to control efficient transmission of the data records between
your program and the external medium.
Example: FILE-CONTROL entries
RELATED TASKS
Specifying the collating sequence
Defining symbolic characters on page 8
Defining a user-defined class on page 8
Defining files to the operating system on page 8
RELATED REFERENCES
Sections and paragraphs (Enterprise COBOL Language Reference)
Example: FILE-CONTROL entries
The following table shows example FILE-CONTROL entries for a QSAM sequential
file, a VSAM indexed file, and a line-sequential file.
Table 1. FILE-CONTROL entries
QSAM file VSAM file Line-sequential file
1 1
SELECT PRINTFILE SELECT COMMUTER-FILE SELECT PRINTFILE1
ASSIGN TO UPDPRINT2 ASSIGN TO COMMUTER2 ASSIGN TO UPDPRINT2
ORGANIZATION IS SEQUENTIAL3 ORGANIZATION IS INDEXED3 ORGANIZATION IS LINE SEQUENTIAL3
ACCESS IS SEQUENTIAL.4 ACCESS IS RANDOM4 ACCESS IS SEQUENTIAL.4
RECORD KEY IS COMMUTER-KEY5
FILE STATUS IS5
COMMUTER-FILE-STATUS
COMMUTER-VSAM-STATUS.
1. The SELECT clause chooses a file in the COBOL program to be associated with an external data set.
2. The ASSIGN clause associates the program's name for the file with the external name for the actual data file. You
can define the external name with a DD statement or an environment variable.
3. The ORGANIZATION clause describes the file's organization. For QSAM files, the ORGANIZATION clause is optional.
4. The ACCESS MODE clause defines the manner in which the records are made available for processing: sequential,
random, or dynamic. For QSAM and line-sequential files, the ACCESS MODE clause is optional. These files always
have sequential organization.
5. For VSAM files, you might have additional statements in the FILE-CONTROL paragraph depending on the type of
VSAM file you use.
RELATED TASKS
Chapter 9, Processing QSAM files, on page 159
Chapter 10, Processing VSAM files, on page 185
Chapter 11, Processing line-sequential files, on page 213
Describing the computing environment on page 5
Specifying the collating sequence
You can use the PROGRAM COLLATING SEQUENCE clause and the ALPHABET clause of the
SPECIAL-NAMES paragraph to establish the collating sequence that is used in several
operations on alphanumeric items.
These clauses specify the collating sequence for the following operations on
alphanumeric items:
6 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Comparisons explicitly specified in relation conditions and condition-name
conditions
v HIGH-VALUE and LOW-VALUE settings
v SEARCH ALL
v SORT and MERGE unless overridden by a COLLATING SEQUENCE phrase in the SORT
or MERGE statement
Example: specifying the collating sequence
The sequence that you use can be based on one of these alphabets:
v EBCDIC: references the collating sequence associated with the EBCDIC
character set
v NATIVE: references the same collating sequence as EBCDIC
v STANDARD-1: references the collating sequence associated with the ASCII
character set defined by ANSI INCITS X3.4, Coded Character Sets - 7-bit American
National Standard Code for Information Interchange (7-bit ASCII)
v STANDARD-2: references the collating sequence associated with the character
set defined by ISO/IEC 646 -- Information technology -- ISO 7-bit coded character set
for information interchange, International Reference Version
v An alteration of the EBCDIC sequence that you define in the SPECIAL-NAMES
paragraph
The PROGRAM COLLATING SEQUENCE clause does not affect comparisons that involve
national or DBCS operands.
RELATED TASKS
Choosing alternate collating sequences on page 229
Comparing national (UTF-16) data on page 147
Example: specifying the collating sequence
The following example shows the ENVIRONMENT DIVISION coding that you can use
to specify a collating sequence in which uppercase and lowercase letters are
similarly handled in comparisons and in sorting and merging.
When you change the EBCDIC sequence in the SPECIAL-NAMES paragraph, the
overall collating sequence is affected, not just the collating sequence of the
characters that are included in the SPECIAL-NAMES paragraph.
IDENTIFICATION DIVISION.
. . .
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
Source-Computer. IBM-390.
Object-Computer. IBM-390.
Program Collating Sequence Special-Sequence.
Special-Names.
Alphabet Special-Sequence Is
"A" Also "a"
"B" Also "b"
"C" Also "c"
"D" Also "d"
"E" Also "e"
"F" Also "f"
"G" Also "g"
"H" Also "h"
"I" Also "i"
"J" Also "j"
"K" Also "k"
Chapter 1. Structuring your program 7
"L" Also "l"
"M" Also "m"
"N" Also "n"
"O" Also "o"
"P" Also "p"
"Q" Also "q"
"R" Also "r"
"S" Also "s"
"T" Also "t"
"U" Also "u"
"V" Also "v"
"W" Also "w"
"X" Also "x"
"Y" Also "y"
"Z" Also "z".
RELATED TASKS
Specifying the collating sequence on page 6
Defining symbolic characters
Use the SYMBOLIC CHARACTERS clause to give symbolic names to any character of the
specified alphabet. Use ordinal position to identify the character, where position 1
corresponds to character X'00'.
For example, to give a name to the backspace character (X'16' in the EBCDIC
alphabet), code:
SYMBOLIC CHARACTERS BACKSPACE IS 23
Defining a user-defined class
Use the CLASS clause to give a name to a set of characters that you list in the
clause.
For example, name the set of digits by coding the following clause:
CLASS DIGIT IS "0" THROUGH "9"
You can reference the class-name only in a class condition. (This user-defined class
is not the same as an object-oriented class.)
Defining files to the operating system
For all files that you process in your COBOL program, you need to define the files
to the operating system with an appropriate system data definition.
Depending on the operating system, this system data definition can take any of the
following forms:
v DD statement for MVS JCL.
v ALLOCATE command under TSO.
v Environment variable for z/OS or z/OS UNIX. The contents can define either an
MVS data set or a file in the z/OS UNIX file system.
The following examples show the relationship of a FILE-CONTROL entry to the
system data definition and to the FD entry in the FILE SECTION:
v JCL DD statement:
(1)
//OUTFILE DD DSNAME=MY.OUT171,UNIT=SYSDA,SPACE=(TRK,(50,5))
/*
8 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Environment variable (export command):
(1)
export OUTFILE=DSN(MY.OUT171),UNIT(SYSDA),SPACE(TRK,(50,5))
v COBOL code:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT CARPOOL
ASSIGN TO OUTFILE (1)
ORGANIZATION IS SEQUENTIAL.
. . .
DATA DIVISION.
FILE SECTION.
FD CARPOOL (2)
LABEL RECORD STANDARD
BLOCK CONTAINS 0 CHARACTERS
RECORD CONTAINS 80 CHARACTERS
(1) The assignment-name in the ASSIGN clause points to the ddname OUTFILE in
the DD statement or the environment variable OUTFILE in the export
command:
v //OUTFILE DD DSNAME=OUT171 . . ., or
v export OUTFILE= . . .
(2) When you specify a file file-name in a FILE-CONTROL entry, you must
describe the file in an FD entry:
SELECT CARPOOL
. . .
FD CARPOOL
RELATED TASKS
Optimizing buffer and device space on page 10
RELATED REFERENCES
FILE SECTION entries on page 12
FILE SECTION (Enterprise COBOL Language Reference)
Varying the input or output file at run time
The file-name that you code in a SELECT clause is used as a constant throughout
your COBOL program, but you can associate the name of that file with a different
system file at run time.
Changing a file-name within a COBOL program would require changing the input
statements and output statements and recompiling the program. Alternatively, you
can change the DSNAME value in the DD statement or the DSN or PATH value in the
export command to use a different file at run time.
Environment variable values that are in effect at the time of the OPEN statement are
used for associating COBOL file-names to the system file-names (including any
path specifications).
The name that you use in the assignment-name of the ASSIGN clause must be the
same as the ddname in the DD statement or the environment variable in the export
command.
The file-name that you use in the SELECT clause (such as SELECT MASTER) must be the
same as in the FD file-name entry.
Chapter 1. Structuring your program 9
Two files should not use the same ddname or environment variable name in their
SELECT clauses; otherwise, results could be unpredictable. For example, if DISPLAY
output is directed to SYSOUT, do not use SYSOUT as the ddname or environment
variable name in the SELECT clause for a file.
Example: using different input files:
This example shows that you use the same COBOL program to access different
files by coding a DD statement or an export command before the programs runs.
Consider a COBOL program that contains the following SELECT clause:
SELECT MASTER ASSIGN TO DA-3330-S-MASTERA
Assume the three possible input files are MASTER1, MASTER2, and MASTER3. Before
running the program, code one of the following DD statements in the job step that
calls for program execution, or issue one of the following export commands from
the same shell from which you run the program:
//MASTERA DD DSNAME=MY.MASTER1,. . .
export MASTERA=DSN(MY.MASTER1),. . .
//MASTERA DD DSNAME=MY.MASTER2,. . .
export MASTERA=DSN(MY.MASTER2),. . .
//MASTERA DD DSNAME=MY.MASTER3,. . .
export MASTERA=DSN(MY.MASTER3),. . .
Any reference in the program to MASTER will therefore be a reference to the file that
is currently assigned to the ddname or environment-variable name MASTERA.
Notice that in this example, you cannot use the PATH(path) form of the export
command to reference a line-sequential file in the z/OS UNIX file system, because
you cannot specify an organization field (S- or AS-) with a line-sequential file.
Optimizing buffer and device space
Use the APPLY WRITE-ONLY clause to make optimum use of buffer and device space
when you create a sequential file with blocked variable-length records.
With APPLY WRITE-ONLY specified, a buffer is truncated only when the next record
does not fit in the unused portion of the buffer. Without APPLY WRITE-ONLY
specified, a buffer is truncated when it does not have enough space for a
maximum-size record.
The APPLY WRITE-ONLY clause has meaning only for sequential files that have
variable-length records and are blocked.
The AWO compiler option applies an implicit APPLY WRITE-ONLY clause to all eligible
files. The NOAWO compiler option has no effect on files that have the APPLY
WRITE-ONLY clause specified. The APPLY WRITE-ONLY clause takes precedence over
the NOAWO compiler option.
The APPLY-WRITE ONLY clause can cause input files to use a record area rather than
process the data in the buffer. This use might affect the processing of both input
files and output files.
RELATED REFERENCES
AWO on page 310
10 Enterprise COBOL for z/OS, V5.2 Programming Guide
Describing the data
Define the characteristics of your data, and group your data definitions into one or
more of the sections in the DATA DIVISION.
You can use these sections for defining the following types of data:
v Data used in input-output operations: FILE SECTION
v Data developed for internal processing:
To have storage be statically allocated and exist for the life of the run unit:
WORKING-STORAGE SECTION
To have storage be allocated each time a program is entered, and deallocated
on return from the program: LOCAL-STORAGE SECTION
v Data from another program: LINKAGE SECTION
The Enterprise COBOL compiler limits the maximum size of DATA DIVISION
elements. For details, see the related reference about compiler limits below.
RELATED CONCEPTS
Comparison of WORKING-STORAGE and LOCAL-STORAGE on page 14
RELATED TASKS
Using data in input and output operations
Using data from another program on page 16
RELATED REFERENCES
Compiler limits (Enterprise COBOL Language Reference)
Using data in input and output operations
Define the data that you use in input and output operations in the FILE SECTION.
Provide the following information about the data:
v Name the input and output files that the program will use. Use the FD entry to
give names to the files that the input-output statements in the PROCEDURE
DIVISION can refer to.
Data items defined in the FILE SECTION are not available to PROCEDURE DIVISION
statements until the file has been successfully opened.
v In the record description that follows the FD entry, describe the fields of the
records in the file:
You can code a level-01 description of the entire record, and then in the
WORKING-STORAGE SECTION code a working copy that describes the fields of the
record in more detail. Use the READ INTO statement to bring the records into
WORKING-STORAGE. Processing occurs on the copy of data in WORKING-STORAGE.
A WRITE FROM statement writes processed data into the record area defined in
the FILE SECTION.
The record-name established is the object of WRITE and REWRITE statements.
For QSAM files only, you can set the record format in the RECORDING MODE
clause. If you omit the RECORDING MODE clause, the compiler determines the
record format based on the RECORD clause and on the level-01 record
descriptions.
For QSAM files, you can set a blocking factor for the file in the BLOCK
CONTAINS clause. If you omit the BLOCK CONTAINS clause, the file defaults to
Chapter 1. Structuring your program 11
unblocked. However, you can override this with z/OS data management
facilities (including a DD file job-control statement).
For line-sequential files, you can set a blocking factor for the file in the BLOCK
CONTAINS clause. When you code BLOCK CONTAINS 1 RECORDS, or BLOCK
CONTAINS n CHARACTERS, where n is the length of one logical record in bytes,
WRITE statements result in the record being transferred immediately to the file
rather than being buffered. This technique is useful when you want each
record written immediately, such as to an error log.
Programs in the same run unit can share, or have access to, common files. The
method for doing this depends on whether the programs are part of a nested
(contained) structure or are separately compiled (including programs compiled as
part of a batch sequence).
You can use the EXTERNAL clause for separately compiled programs. A file that is
defined as EXTERNAL can be referenced by any program in the run unit that
describes the file.
You can use the GLOBAL clause for programs in a nested, or contained, structure. If
a program contains another program (directly or indirectly), both programs can
access a common file by referencing a GLOBAL file-name.
RELATED CONCEPTS
Nested programs on page 474
RELATED TASKS
Sharing files between programs (external files) on page 491
RELATED REFERENCES
FILE SECTION entries
FILE SECTION entries
The entries that you can use in the FILE SECTION are summarized in the table
below.
Table 2. FILE SECTION entries
Clause To define Notes
FD The file-name to be Must match file-name in the SELECT clause.
referred to in PROCEDURE file-name is associated with a ddname
DIVISION input-output through the assignment-name.
statements (OPEN, CLOSE,
READ, also START and
DELETE for VSAM)
12 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 2. FILE SECTION entries (continued)
Clause To define Notes
BLOCK CONTAINS Size of physical records If the CHARACTERS phrase is specified, size
indicates the number of bytes in a record
regardless of the USAGE of the data items in
the record.
QSAM: If provided, must match
information on JCL or data-set label. If
specified as BLOCK CONTAINS 0, or not
provided, the system determines the
optimal block size for you.
Line sequential: Can be specified to control
buffering for WRITE statements.
VSAM: Syntax-checked, but has no effect on
execution.
RECORD CONTAINS Size of logical records Integer size indicates the number of bytes
n (fixed length) in a record regardless of the USAGE of the
data items in the record. If the clause is
provided, it must match information on JCL
or data-set label. If n is equal to 0, LRECL
must be coded on JCL or data-set label.
RECORD IS Size of logical records Integer size or sizes, if specified, indicate
VARYING (variable length) the number of bytes in a record regardless
of the USAGE of the data items in the record.
If the clause is provided, it must match
information on JCL or data-set label;
compiler checks that record descriptions
match.
RECORD CONTAINS Size of logical records The integer sizes indicate the number of
n TO m (variable length) bytes in a record regardless of the USAGE of
the data items in the record. If the clause is
provided, it must match information on JCL
or data-set label; compiler checks that
record descriptions match.
LABEL RECORDS Labels for QSAM files VSAM: Handled as comments
STANDARD Labels exist QSAM: Handled as comments
OMITTED Labels do not exist QSAM: Handled as comments
data-name Labels defined by the user QSAM: Allowed for (optional) tape or disk
VALUE OF An item in the label Comments only
records associated with
file
DATA RECORDS Names of records Comments only
associated with file
LINAGE Depth of logical page QSAM only
Chapter 1. Structuring your program 13
Table 2. FILE SECTION entries (continued)
Clause To define Notes
CODE-SET ASCII or EBCDIC files QSAM only.
When an ASCII file is identified with the
CODE-SET clause, the corresponding DD
statement might need to have
DCB=(OPTCD=Q. . .) or DCB=(RECFM=D. . .)
coded if the file was not created using VS
COBOL II, COBOL for OS/390 & VM, or
IBM Enterprise COBOL for z/OS.
RECORDING MODE Physical record QSAM only
description
RELATED REFERENCES
FILE SECTION (Enterprise COBOL Language Reference)
Comparison of WORKING-STORAGE and LOCAL-STORAGE
How data items are allocated and initialized varies depending on whether the
items are in the WORKING-STORAGE SECTION or LOCAL-STORAGE SECTION.
WORKING-STORAGE for programs is allocated when the run unit is started.
Any data items that have VALUE clauses are initialized to the appropriate value at
that time. For the duration of the run unit, WORKING-STORAGE items persist in their
last-used state. Exceptions are:
v A program with INITIAL specified in the PROGRAM-ID paragraph
In this case, WORKING-STORAGE data items are reinitialized each time that the
program is entered.
v A subprogram that is dynamically called and then canceled
In this case, WORKING-STORAGE data items are reinitialized on the first reentry into
the program following the CANCEL.
WORKING-STORAGE is deallocated at the termination of the run unit.
See the related tasks for information about WORKING-STORAGE in COBOL class
definitions.
A separate copy of LOCAL-STORAGE data is allocated for each call of a program or
invocation of a method, and is freed on return from the program or method. If you
specify a VALUE clause for a LOCAL-STORAGE item, the item is initialized to that value
on each call or invocation. If a VALUE clause is not specified, the initial value of the
item is undefined.
Threading: Each invocation of a program that runs simultaneously on multiple
threads shares access to a single copy of WORKING-STORAGE data. Each invocation
has a separate copy of LOCAL-STORAGE data.
Example: storage sections on page 15
RELATED TASKS
Ending and reentering main programs or subprograms on page 464
14 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 27, Preparing COBOL programs for multithreading, on page 507
WORKING-STORAGE SECTION for defining class instance data on page 586
RELATED REFERENCES
WORKING-STORAGE SECTION (Enterprise COBOL Language Reference)
LOCAL-STORAGE SECTION (Enterprise COBOL Language Reference)
Example: storage sections
The following example is a recursive program that uses both WORKING-STORAGE and
LOCAL-STORAGE.
CBL pgmn(lu)
*********************************
* Recursive Program - Factorials
*********************************
IDENTIFICATION DIVISION.
Program-Id. factorial recursive.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 numb pic 9(4) value 5.
01 fact pic 9(8) value 0.
LOCAL-STORAGE SECTION.
01 num pic 9(4).
PROCEDURE DIVISION.
move numb to num.
if numb = 0
move 1 to fact
else
subtract 1 from numb
call factorial
multiply num by fact
end-if.
display num ! = fact.
goback.
End Program factorial.
The program produces the following output:
0000! = 00000001
0001! = 00000001
0002! = 00000002
0003! = 00000006
0004! = 00000024
0005! = 00000120
The following tables show the changing values of the data items in LOCAL-STORAGE
and WORKING-STORAGE in the successive recursive calls of the program, and in the
ensuing gobacks. During the gobacks, fact progressively accumulates the value of
5! (five factorial).
Value for num in Value for numb in Value for fact in
Recursive calls LOCAL-STORAGE WORKING-STORAGE WORKING-STORAGE
Main 5 5 0
1 4 4 0
2 3 3 0
3 2 2 0
4 1 1 0
5 0 0 0
Chapter 1. Structuring your program 15
Value for num in Value for numb in Value for fact in
Gobacks LOCAL-STORAGE WORKING-STORAGE WORKING-STORAGE
5 0 0 1
4 1 0 1
3 2 0 2
2 3 0 6
1 4 0 24
Main 5 0 120
RELATED CONCEPTS
Comparison of WORKING-STORAGE and LOCAL-STORAGE on page 14
Using data from another program
How you share data depends on the type of program. You share data differently in
programs that are separately compiled than you do for programs that are nested or
for programs that are recursive or multithreaded.
RELATED TASKS
Sharing data in separately compiled programs
Sharing data in nested programs
Sharing data in recursive or multithreaded programs on page 17
Passing data on page 481
Sharing data in separately compiled programs
Many applications consist of separately compiled programs that call and pass data
to one another. Use the LINKAGE SECTION in the called program to describe the data
passed from another program.
In the calling program, code a CALL . . . USING or INVOKE . . . USING statement
to pass the data.
RELATED TASKS
Passing data on page 481
Coding the LINKAGE SECTION on page 485
Sharing data in nested programs
Some applications consist of nested programs, that is, programs that are contained
in other programs. Level-01 data items can include the GLOBAL attribute. This
attribute allows any nested program that includes the declarations to access these
data items.
A nested program can also access data items in a sibling program (one at the same
nesting level in the same containing program) that is declared with the COMMON
attribute.
RELATED CONCEPTS
Nested programs on page 474
16 Enterprise COBOL for z/OS, V5.2 Programming Guide
Sharing data in recursive or multithreaded programs
If your program has the RECURSIVE attribute or is compiled with the THREAD
compiler option, data that is defined in the LINKAGE SECTION is not accessible on
subsequent invocations of the program.
To address a record in the LINKAGE SECTION, use either of these techniques:
v Pass an argument to the program and specify the record in an appropriate
position in the USING phrase in the program.
v Use the format-5 SET statement.
If your program has the RECURSIVE attribute or is compiled with the THREAD
compiler option, the address of the record is valid for a particular instance of the
program invocation. The address of the record in another execution instance of the
same program must be reestablished for that execution instance. Unpredictable
results will occur if you refer to a data item for which the address has not been
established.
RELATED CONCEPTS
Multithreading on page 508
RELATED TASKS
Making recursive calls on page 477
Processing files with multithreading on page 510
RELATED REFERENCES
THREAD on page 362
SET statement (Enterprise COBOL Language Reference)
Processing the data
In the PROCEDURE DIVISION of a program, you code the executable statements that
process the data that you defined in the other divisions. The PROCEDURE DIVISION
contains one or two headers and the logic of your program.
The PROCEDURE DIVISION begins with the division header and a procedure-name
header. The division header for a program can simply be:
PROCEDURE DIVISION.
You can code the division header to receive parameters by using the USING phrase,
or to return a value by using the RETURNING phrase.
To receive an argument that was passed by reference (the default) or by content,
code the division header for a program in either of these ways:
PROCEDURE DIVISION USING dataname
PROCEDURE DIVISION USING BY REFERENCE dataname
Be sure to define dataname in the LINKAGE SECTION of the DATA DIVISION.
To receive a parameter that was passed by value, code the division header for a
program as follows:
PROCEDURE DIVISION USING BY VALUE dataname
To return a value as a result, code the division header as follows:
PROCEDURE DIVISION RETURNING dataname2
Chapter 1. Structuring your program 17
You can also combine USING and RETURNING in a PROCEDURE DIVISION header:
PROCEDURE DIVISION USING dataname RETURNING dataname2
Be sure to define dataname and dataname2 in the LINKAGE SECTION.
RELATED CONCEPTS
How logic is divided in the PROCEDURE DIVISION
RELATED TASKS
Coding the LINKAGE SECTION on page 485
Coding the PROCEDURE DIVISION for passing arguments on page 486
Using PROCEDURE DIVISION RETURNING . . . on page 490
Eliminating repetitive coding on page 665
RELATED REFERENCES
The procedure division header (Enterprise COBOL Language Reference)
The USING phrase (Enterprise COBOL Language Reference)
CALL statement (Enterprise COBOL Language Reference)
How logic is divided in the PROCEDURE DIVISION
The PROCEDURE DIVISION of a program is divided into sections and paragraphs,
which contain sentences, statements, and phrases.
Section
Logical subdivision of your processing logic.
A section has a section header and is optionally followed by one or more
paragraphs.
A section can be the subject of a PERFORM statement. One type of section is
for declaratives.
Paragraph
Subdivision of a section, procedure, or program.
A paragraph has a name followed by a period and zero or more sentences.
A paragraph can be the subject of a statement.
Sentence
Series of one or more COBOL statements that ends with a period.
Statement
Performs a defined step of COBOL processing, such as adding two
numbers.
A statement is a valid combination of words, and begins with a COBOL
verb. Statements are imperative (indicating unconditional action),
conditional, or compiler-directing. Using explicit scope terminators instead
of periods to show the logical end of a statement is preferred.
Phrase
A subdivision of a statement.
RELATED CONCEPTS
Compiler-directing statements on page 20
Scope terminators on page 20
Imperative statements on page 19
Conditional statements on page 19
Declaratives on page 21
18 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
PROCEDURE DIVISION structure (Enterprise COBOL Language Reference)
Imperative statements
An imperative statement (such as ADD, MOVE, INVOKE, or CLOSE) indicates an
unconditional action to be taken.
You can end an imperative statement with an implicit or explicit scope terminator.
A conditional statement that ends with an explicit scope terminator becomes an
imperative statement called a delimited scope statement. Only imperative statements
(or delimited scope statements) can be nested.
RELATED CONCEPTS
Conditional statements
Scope terminators on page 20
Conditional statements
A conditional statement is either a simple conditional statement (IF, EVALUATE,
SEARCH) or a conditional statement made up of an imperative statement that
includes a conditional phrase or option.
You can end a conditional statement with an implicit or explicit scope terminator.
If you end a conditional statement explicitly, it becomes a delimited scope
statement (which is an imperative statement).
You can use a delimited scope statement in these ways:
v To delimit the range of operation for a COBOL conditional statement and to
explicitly show the levels of nesting
For example, use an END-IF phrase instead of a period to end the scope of an IF
statement within a nested IF.
v To code a conditional statement where the COBOL syntax calls for an imperative
statement
For example, code a conditional statement as the object of an inline PERFORM:
PERFORM UNTIL TRANSACTION-EOF
PERFORM 200-EDIT-UPDATE-TRANSACTION
IF NO-ERRORS
PERFORM 300-UPDATE-COMMUTER-RECORD
ELSE
PERFORM 400-PRINT-TRANSACTION-ERRORS
END-IF
READ UPDATE-TRANSACTION-FILE INTO WS-TRANSACTION-RECORD
AT END
SET TRANSACTION-EOF TO TRUE
END-READ
END-PERFORM
An explicit scope terminator is required for the inline PERFORM statement, but it is
not valid for the out-of-line PERFORM statement.
For additional program control, you can use the NOT phrase with conditional
statements. For example, you can provide instructions to be performed when a
particular exception does not occur, such as NOT ON SIZE ERROR. The NOT phrase
cannot be used with the ON OVERFLOW phrase of the CALL statement, but it can be
used with the ON EXCEPTION phrase.
Chapter 1. Structuring your program 19
Do not nest conditional statements. Nested statements must be imperative
statements (or delimited scope statements) and must follow the rules for
imperative statements.
The following statements are examples of conditional statements if they are coded
without scope terminators:
v Arithmetic statement with ON SIZE ERROR
v Data-manipulation statements with ON OVERFLOW
v CALL statements with ON OVERFLOW
v I/O statements with INVALID KEY, AT END, or AT END-OF-PAGE
v RETURN with AT END
RELATED CONCEPTS
Imperative statements on page 19
Scope terminators
RELATED TASKS
Selecting program actions on page 93
RELATED REFERENCES
Conditional statements (Enterprise COBOL Language Reference)
Compiler-directing statements
A compiler-directing statement causes the compiler to take specific action about the
program structure, COPY processing, listing control, or control flow.
A compiler-directing statement is not part of the program logic.
RELATED REFERENCES
Chapter 18, Compiler-directing statements, on page 373
Compiler-directing statements (Enterprise COBOL Language Reference)
Scope terminators
A scope terminator ends a verb or statement. Scope terminators can be explicit or
implicit.
Explicit scope terminators end a verb without ending a sentence. They consist of
END followed by a hyphen and the name of the verb being terminated, such as
END-IF. An implicit scope terminator is a period (.) that ends the scope of all
previous statements not yet ended.
Each of the two periods in the following program fragment ends an IF statement,
making the code equivalent to the code after it that instead uses explicit scope
terminators:
IF ITEM = "A"
DISPLAY "THE VALUE OF ITEM IS " ITEM
ADD 1 TO TOTAL
MOVE "C" TO ITEM
DISPLAY "THE VALUE OF ITEM IS NOW " ITEM.
IF ITEM = "B"
ADD 2 TO TOTAL.
IF ITEM = "A"
DISPLAY "THE VALUE OF ITEM IS " ITEM
ADD 1 TO TOTAL
MOVE "C" TO ITEM
DISPLAY "THE VALUE OF ITEM IS NOW " ITEM
20 Enterprise COBOL for z/OS, V5.2 Programming Guide
END-IF
IF ITEM = "B"
ADD 2 TO TOTAL
END-IF
If you use implicit terminators, the end of statements can be unclear. As a result,
you might end statements unintentionally, changing your program's logic. Explicit
scope terminators make a program easier to understand and prevent unintentional
ending of statements. For example, in the program fragment below, changing the
location of the first period in the first implicit scope example changes the meaning
of the code:
IF ITEM = "A"
DISPLAY "VALUE OF ITEM IS " ITEM
ADD 1 TO TOTAL.
MOVE "C" TO ITEM
DISPLAY " VALUE OF ITEM IS NOW " ITEM
IF ITEM = "B"
ADD 2 TO TOTAL.
The MOVE statement and the DISPLAY statement after it are performed regardless of
the value of ITEM, despite what the indentation indicates, because the first period
terminates the IF statement.
For improved program clarity and to avoid unintentional ending of statements, use
explicit scope terminators, especially within paragraphs. Use implicit scope
terminators only at the end of a paragraph or the end of a program.
Be careful when coding an explicit scope terminator for an imperative statement
that is nested within a conditional statement. Ensure that the scope terminator is
paired with the statement for which it was intended. In the following example, the
scope terminator will be paired with the second READ statement, though the
programmer intended it to be paired with the first.
READ FILE1
AT END
MOVE A TO B
READ FILE2
END-READ
To ensure that the explicit scope terminator is paired with the intended statement,
the preceding example can be recoded in this way:
READ FILE1
AT END
MOVE A TO B
READ FILE2
END-READ
END-READ
RELATED CONCEPTS
Conditional statements on page 19
Imperative statements on page 19
Declaratives
Declaratives provide one or more special-purpose sections that are executed when
an exception condition occurs.
Start each declarative section with a USE statement that identifies the function of
the section. In the procedures, specify the actions to be taken when the condition
occurs.
Chapter 1. Structuring your program 21
RELATED TASKS
Finding and handling input-output errors on page 379
RELATED REFERENCES
Declaratives (Enterprise COBOL Language Reference)
22 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 2. Using data
This information is intended to help non-COBOL programmers relate terms for
data used in other programming languages to COBOL terms. It introduces COBOL
fundamentals for variables, structures, literals, and constants; assigning and
displaying values; intrinsic (built-in) functions, and tables (arrays) and pointers.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Using variables, structures, literals, and constants
Assigning values to data items on page 27
Displaying values on a screen or in a file (DISPLAY) on page 35
Using intrinsic functions (built-in functions) on page 38
Using tables (arrays) and pointers on page 39
Chapter 7, Processing data in an international environment, on page 125
Using variables, structures, literals, and constants
Most high-level programming languages share the concept of data being
represented as variables, structures (group items), literals, or constants.
The data in a COBOL program can be alphabetic, alphanumeric, double-byte
character set (DBCS), national, or numeric. You can also define index-names and
data items described as USAGE POINTER, USAGE FUNCTION-POINTER, USAGE
PROCEDURE-POINTER, or USAGE OBJECT REFERENCE. You place all data definitions in
the DATA DIVISION of your program.
RELATED TASKS
Using variables
Using data items and group items on page 24
Using literals on page 25
Using constants on page 26
Using figurative constants on page 26
RELATED REFERENCES
Classes and categories of data (Enterprise COBOL Language Reference)
Using variables
A variable is a data item whose value can change during a program. The value is
restricted, however, to the data type that you define when you specify a name and
a length for the data item.
For example, if a customer name is an alphanumeric data item in your program,
you could define and use the customer name as shown below:
Data Division.
01 Customer-Name Pic X(20).
01 Original-Customer-Name Pic X(20).
. . .
Procedure Division.
Move Customer-Name to Original-Customer-Name
. . .
Copyright IBM Corp. 1991, 2015 23
| You could instead define the customer names above as national data items by
specifying their PICTURE clauses as Pic N(20) and specifying the USAGE NATIONAL
clause for the items. National data items are represented in Unicode UTF-16, in
which most characters are represented in 2 bytes of storage.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Using national data (Unicode) in COBOL on page 130
RELATED REFERENCES
NSYMBOL on page 338
Storage of character data on page 137
PICTURE clause (Enterprise COBOL Language Reference)
Using data items and group items
Related data items can be parts of a hierarchical data structure. A data item that
does not have subordinate data items is called an elementary item. A data item that
is composed of one or more subordinate data items is called a group item.
A record can be either an elementary item or a group item. A group item can be
either an alphanumeric group item or a national group item.
For example, Customer-Record below is an alphanumeric group item that is
composed of two subordinate alphanumeric group items (Customer-Name and
Part-Order), each of which contains elementary data items. These groups items
implicitly have USAGE DISPLAY. You can refer to an entire group item or to parts of
a group item in MOVE statements in the PROCEDURE DIVISION as shown below:
Data Division.
File Section.
FD Customer-File
Record Contains 45 Characters.
01 Customer-Record.
05 Customer-Name.
10 Last-Name Pic x(17).
10 Filler Pic x.
10 Initials Pic xx.
05 Part-Order.
10 Part-Name Pic x(15).
10 Part-Color Pic x(10).
Working-Storage Section.
01 Orig-Customer-Name.
05 Surname Pic x(17).
05 Initials Pic x(3).
01 Inventory-Part-Name Pic x(15).
. . .
Procedure Division.
Move Customer-Name to Orig-Customer-Name
Move Part-Name to Inventory-Part-Name
. . .
You could instead define Customer-Record as a national group item that is
composed of two subordinate national group items by changing the declarations in
the DATA DIVISION as shown below. National group items behave in the same way
as elementary category national data items in most operations. The GROUP-USAGE
NATIONAL clause indicates that a group item and any group items subordinate to it
are national groups. Subordinate elementary items in a national group must be
explicitly or implicitly described as USAGE NATIONAL.
24 Enterprise COBOL for z/OS, V5.2 Programming Guide
Data Division.
File Section.
FD Customer-File
Record Contains 90 Characters.
01 Customer-Record Group-Usage National.
05 Customer-Name.
10 Last-Name Pic n(17).
10 Filler Pic n.
10 Initials Pic nn.
05 Part-Order.
10 Part-Name Pic n(15).
10 Part-Color Pic n(10).
Working-Storage Section.
01 Orig-Customer-Name Group-Usage National.
05 Surname Pic n(17).
05 Initials Pic n(3).
01 Inventory-Part-Name Pic n(15) Usage National.
. . .
Procedure Division.
Move Customer-Name to Orig-Customer-Name
Move Part-Name to Inventory-Part-Name
. . .
In the example above, the group items could instead specify the USAGE NATIONAL
clause at the group level. A USAGE clause at the group level applies to each
elementary data item in a group (and thus serves as a convenient shorthand
notation). However, a group that specifies the USAGE NATIONAL clause is not a
national group despite the representation of the elementary items within the group.
Groups that specify the USAGE clause are alphanumeric groups and behave in many
operations, such as moves and compares, like elementary data items of USAGE
DISPLAY (except that no editing or conversion of data occurs).
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
National groups on page 133
RELATED TASKS
Using national data (Unicode) in COBOL on page 130
Using national groups on page 134
RELATED REFERENCES
FILE SECTION entries on page 12
Storage of character data on page 137
Classes and categories of group items (Enterprise COBOL Language Reference)
PICTURE clause (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
USAGE clause (Enterprise COBOL Language Reference)
Using literals
A literal is a character string whose value is given by the characters themselves. If
you know the value you want a data item to have, you can use a literal
representation of the data value in the PROCEDURE DIVISION.
| You do not need to define a data item for the value nor refer to it by using a
data-name. For example, you can prepare an error message for an output file by
moving an alphanumeric literal:
Move "Name is not valid" To Customer-Name
Chapter 2. Using data 25
You can compare a data item to a specific integer value by using a numeric literal.
In the example below, "Name is not valid" is an alphanumeric literal, and 03519 is
a numeric literal:
01 Part-number Pic 9(5).
. . .
If Part-number = 03519 then display "Part number was found"
You can use the opening delimiter N" or N to designate a national literal if the
NSYMBOL(NATIONAL) compiler option is in effect, or to designate a DBCS literal if the
NSYMBOL(DBCS) compiler option is in effect.
You can use the opening delimiter NX" or NX to designate national literals in
hexadecimal notation (regardless of the setting of the NSYMBOL compiler option).
Each group of four hexadecimal digits designates a single national character.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Using national literals on page 131
Using DBCS literals on page 150
RELATED REFERENCES
NSYMBOL on page 338
Literals (Enterprise COBOL Language Reference)
Using constants
A constant is a data item that has only one value. COBOL does not define a
construct for constants. However, you can define a data item with an initial value
by coding a VALUE clause in the data description (instead of coding an INITIALIZE
statement).
Data Division.
01 Report-Header pic x(50) value "Company Sales Report".
. . .
01 Interest pic 9v9999 value 1.0265.
The example above initializes an alphanumeric and a numeric data item. You can
likewise use a VALUE clause in defining a national or DBCS constant.
RELATED TASKS
Using national data (Unicode) in COBOL on page 130
Coding for use of DBCS support on page 150
Using figurative constants
Certain commonly used constants and literals are available as reserved words
called figurative constants: ZERO, SPACE, HIGH-VALUE, LOW-VALUE, QUOTE, NULL, and ALL
literal. Because they represent fixed values, figurative constants do not require a
data definition.
For example:
Move Spaces To Report-Header
RELATED TASKS
Using national-character figurative constants on page 132
Coding for use of DBCS support on page 150
26 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
Figurative constants (Enterprise COBOL Language Reference)
Assigning values to data items
After you have defined a data item, you can assign a value to it at any time.
Assignment takes many forms in COBOL, depending on what you want to do.
Table 3. Assignment to data items in a program
What you want to do How to do it
Assign values to a data item or large data area. Use one of these ways:
v INITIALIZE statement
v MOVE statement
v STRING or UNSTRING statement
v VALUE clause (to set data items to the values you
want them to have when the program is in
initial state)
Assign the results of arithmetic. Use COMPUTE, ADD, SUBTRACT, MULTIPLY, or DIVIDE
statements.
Examine or replace characters or groups of characters in a data Use the INSPECT statement.
item.
Receive values from a file. Use the READ (or READ INTO) statement.
Receive values from a system input device or a file. Use the ACCEPT statement.
Establish a constant. Use the VALUE clause in the definition of the data
item, and do not use the data item as a receiver.
Such an item is in effect a constant even though the
compiler does not enforce read-only constants.
One of these actions: Use the SET statement.
v Place a value associated with a table element in an index.
v Set the status of an external switch to ON or OFF.
v Move data to a condition-name to make the condition true.
v Set a POINTER, PROCEDURE-POINTER, or FUNCTION-POINTER data
item to an address.
v Associate an OBJECT REFERENCE data item with an object
instance.
Examples: initializing data items on page 28
RELATED TASKS
Initializing a structure (INITIALIZE) on page 30
Assigning values to elementary data items (MOVE) on page 32
Assigning values to group data items (MOVE) on page 33
Assigning input from a screen or file (ACCEPT) on page 34
Joining data items (STRING) on page 105
Splitting data items (UNSTRING) on page 107
Assigning arithmetic results (MOVE or COMPUTE) on page 34
Tallying and replacing data items (INSPECT) on page 115
Chapter 7, Processing data in an international environment, on page 125
Chapter 2. Using data 27
Examples: initializing data items
The following examples show how you can initialize many kinds of data items,
including alphanumeric, national-edited, and numeric-edited data items, by using
INITIALIZE statements.
An INITIALIZE statement is functionally equivalent to one or more MOVE statements.
The related tasks about initializing show how you can use an INITIALIZE statement
on a group item to conveniently initialize all the subordinate data items that are in
a given data category.
Initializing a data item to blanks or zeros:
INITIALIZE identifier-1
identifier-1 PICTURE identifier-1 before identifier-1 after
9(5) 12345 00000
X(5) AB123 bbbbb1
N(3) 0041004200312 0020002000203
99XX9 12AB3 bbbbb1
XXBX/XX ABbC/DE bbbb/bb1
**99.9CR 1234.5CR **00.0bb1
A(5) ABCDE bbbbb1
+99.99E+99 +12.34E+02 +00.00E+00
1. The symbol b represents a blank space.
2. Hexadecimal representation of the national (UTF-16) characters 'AB1'. The example
assumes that identifier-1 has Usage National.
3. Hexadecimal representation of the national (UTF-16) characters ' ' (three blank
spaces). Note that if identifier-1 were not defined as Usage National, and if
NSYMBOL(DBCS) were in effect, INITIALIZE would instead store DBCS spaces ('4040') into
identifier-1.
Initializing an alphanumeric data item:
01 ALPHANUMERIC-1 PIC X VALUE "y".
01 ALPHANUMERIC-3 PIC X(1) VALUE "A".
. . .
INITIALIZE ALPHANUMERIC-1
REPLACING ALPHANUMERIC DATA BY ALPHANUMERIC-3
ALPHANUMERIC-3 ALPHANUMERIC-1 before ALPHANUMERIC-1 after
A y A
Initializing an alphanumeric right-justified data item:
01 ANJUST PIC X(8) VALUE SPACES JUSTIFIED RIGHT.
01 ALPHABETIC-1 PIC A(4) VALUE "ABCD".
. . .
INITIALIZE ANJUST
REPLACING ALPHANUMERIC DATA BY ALPHABETIC-1
ALPHABETIC-1 ANJUST before ANJUST after
1
ABCD bbbbbbbb bbbbABCD1
1. The symbol b represents a blank space.
28 Enterprise COBOL for z/OS, V5.2 Programming Guide
Initializing an alphanumeric-edited data item:
01 ALPHANUM-EDIT-1 PIC XXBX/XXX VALUE "ABbC/DEF".
01 ALPHANUM-EDIT-3 PIC X/BB VALUE "M/bb".
. . .
INITIALIZE ALPHANUM-EDIT-1
REPLACING ALPHANUMERIC-EDITED DATA BY ALPHANUM-EDIT-3
ALPHANUM-EDIT-3 ALPHANUM-EDIT-1 before ALPHANUM-EDIT-1 after
1 1
M/bb ABbC/DEF M/bb/bbb1
1. The symbol b represents a blank space.
Initializing a national data item:
01 NATIONAL-1 PIC NN USAGE NATIONAL VALUE N"AB".
01 NATIONAL-3 PIC NN USAGE NATIONAL VALUE N"CD".
. . .
INITIALIZE NATIONAL-1
REPLACING NATIONAL DATA BY NATIONAL-3
NATIONAL-3 NATIONAL-1 before NATIONAL-1 after
1 2
00430044 00410042 004300441
1. Hexadecimal representation of the national characters 'CD'
2. Hexadecimal representation of the national characters 'AB'
Initializing a national-edited data item:
01 NATL-EDIT-1 PIC 0NN USAGE NATIONAL VALUE N"123".
01 NATL-3 PIC NNN USAGE NATIONAL VALUE N"456".
. . .
INITIALIZE NATL-EDIT-1
REPLACING NATIONAL-EDITED DATA BY NATL-3
NATL-3 NATL-EDIT-1 before NATL-EDIT-1 after
1 2
003400350036 003100320033 0030003400353
1. Hexadecimal representation of the national characters '456'
2. Hexadecimal representation of the national characters '123'
3. Hexadecimal representation of the national characters '045'
Initializing a numeric (zoned decimal) data item:
01 NUMERIC-1 PIC 9(8) VALUE 98765432.
01 NUM-INT-CMPT-3 PIC 9(7) COMP VALUE 1234567.
. . .
INITIALIZE NUMERIC-1
REPLACING NUMERIC DATA BY NUM-INT-CMPT-3
NUM-INT-CMPT-3 NUMERIC-1 before NUMERIC-1 after
1234567 98765432 01234567
Initializing a numeric (national decimal) data item:
01 NAT-DEC-1 PIC 9(3) USAGE NATIONAL VALUE 987.
01 NUM-INT-BIN-3 PIC 9(2) BINARY VALUE 12.
. . .
INITIALIZE NAT-DEC-1
REPLACING NUMERIC DATA BY NUM-INT-BIN-3
Chapter 2. Using data 29
NUM-INT-BIN-3 NAT-DEC-1 before NAT-DEC-1 after
1
12 003900380037 0030003100322
1. Hexadecimal representation of the national characters '987'
2. Hexadecimal representation of the national characters '012'
Initializing a numeric-edited (USAGE DISPLAY) data item:
01 NUM-EDIT-DISP-1 PIC $ZZ9V VALUE "$127".
01 NUM-DISP-3 PIC 999V VALUE 12.
. . .
INITIALIZE NUM-EDIT-DISP-1
REPLACING NUMERIC DATA BY NUM-DISP-3
NUM-DISP-3 NUM-EDIT-DISP-1 before NUM-EDIT-DISP-1 after
012 $127 $ 12
Initializing a numeric-edited (USAGE NATIONAL) data item:
01 NUM-EDIT-NATL-1 PIC $ZZ9V NATIONAL VALUE N"$127".
01 NUM-NATL-3 PIC 999V NATIONAL VALUE 12.
. . .
INITIALIZE NUM-EDIT-NATL-1
REPLACING NUMERIC DATA BY NUM-NATL-3
NUM-NATL-3 NUM-EDIT-NATL-1 before NUM-EDIT-NATL-1 after
1 2
003000310032 0024003100320037 00240020003100323
1. Hexadecimal representation of the national characters '012'
2. Hexadecimal representation of the national characters '$127'
3. Hexadecimal representation of the national characters '$ 12'
RELATED TASKS
Initializing a structure (INITIALIZE)
Initializing a table (INITIALIZE) on page 73
Defining numeric data on page 43
RELATED REFERENCES
NSYMBOL on page 338
Initializing a structure (INITIALIZE)
You can reset the values of all subordinate data items in a group item by applying
the INITIALIZE statement to that group item. However, it is inefficient to initialize
an entire group unless you really need all the items in the group to be initialized.
The following example shows how you can reset fields to spaces and zeros in
transaction records that a program produces. The values of the fields are not
identical in each record that is produced. (The transaction record is defined as an
alphanumeric group item, TRANSACTION-OUT.)
01 TRANSACTION-OUT.
05 TRANSACTION-CODE PIC X.
05 PART-NUMBER PIC 9(6).
05 TRANSACTION-QUANTITY PIC 9(5).
05 PRICE-FIELDS.
10 UNIT-PRICE PIC 9(5)V9(2).
30 Enterprise COBOL for z/OS, V5.2 Programming Guide
10 DISCOUNT PIC V9(2).
10 SALES-PRICE PIC 9(5)V9(2).
. . .
INITIALIZE TRANSACTION-OUT
Record TRANSACTION-OUT before TRANSACTION-OUT after
1 R001383000240000000000000000 b0000000000000000000000000001
2 R001390000480000000000000000 b0000000000000000000000000001
3 S001410000120000000000000000 b0000000000000000000000000001
4 C001383000000000425000000000 b0000000000000000000000000001
5 C002010000000000000100000000 b0000000000000000000000000001
1. The symbol b represents a blank space.
You can likewise reset the values of all the subordinate data items in a national
group item by applying the INITIALIZE statement to that group item. The
following structure is similar to the preceding structure, but instead uses Unicode
UTF-16 data:
01 TRANSACTION-OUT GROUP-USAGE NATIONAL.
05 TRANSACTION-CODE PIC N.
05 PART-NUMBER PIC 9(6).
05 TRANSACTION-QUANTITY PIC 9(5).
05 PRICE-FIELDS.
10 UNIT-PRICE PIC 9(5)V9(2).
10 DISCOUNT PIC V9(2).
10 SALES-PRICE PIC 9(5)V9(2).
. . .
INITIALIZE TRANSACTION-OUT
Regardless of the previous contents of the transaction record, after the INITIALIZE
statement above is executed:
v TRANSACTION-CODE contains NX"0020" (a national space).
v Each of the remaining 27 national character positions of TRANSACTION-OUT
contains NX"0030" (a national-decimal zero).
When you use an INITIALIZE statement to initialize an alphanumeric or national
group data item, the data item is processed as a group item, that is, with group
semantics. The elementary data items within the group are recognized and
processed, as shown in the examples above. If you do not code the REPLACING
phrase of the INITIALIZE statement:
v SPACE is the implied sending item for alphabetic, alphanumeric,
alphanumeric-edited, DBCS, category national, and national-edited receiving
items.
v ZERO is the implied sending item for numeric and numeric-edited receiving
items.
RELATED CONCEPTS
National groups on page 133
RELATED TASKS
Initializing a table (INITIALIZE) on page 73
Using national groups on page 134
RELATED REFERENCES
INITIALIZE statement (Enterprise COBOL Language Reference)
Chapter 2. Using data 31
Assigning values to elementary data items (MOVE)
Use a MOVE statement to assign a value to an elementary data item.
The following statement assigns the contents of an elementary data item,
Customer-Name, to the elementary data item Orig-Customer-Name:
Move Customer-Name to Orig-Customer-Name
If Customer-Name is longer than Orig-Customer-Name, truncation occurs on the right.
If Customer-Name is shorter, the extra character positions on the right in
Orig-Customer-Name are filled with spaces.
For data items that contain numbers, moves can be more complicated than with
character data items because there are several ways in which numbers can be
represented. In general, the algebraic values of numbers are moved if possible, as
opposed to the digit-by-digit moves that are performed with character data. For
example, after the MOVE statement below, Item-x contains the value 3.0, represented
as 0030:
01 Item-x Pic 999v9.
. . .
Move 3.06 to Item-x
You can move an alphabetic, alphanumeric, alphanumeric-edited, DBCS, integer, or
numeric-edited data item to a category national or national-edited data item; the
sending item is converted. You can move a national data item to a category
national or national-edited data item. If the content of a category national data
item has a numeric value, you can move that item to a numeric, numeric-edited,
external floating-point, or internal floating-point data item. You can move a
national-edited data item only to a category national data item or another
national-edited data item. Padding or truncation might occur.
For complete details about elementary moves, see the related reference below
about the MOVE statement.
The following example shows an alphanumeric data item in the Greek language
that is moved to a national data item:
CBL CODEPAGE(00875)
. . .
01 Data-in-Unicode Pic N(100) usage national.
01 Data-in-Greek Pic X(100).
. . .
Read Greek-file into Data-in-Greek
Move Data-in-Greek to Data-in-Unicode
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Assigning values to group data items (MOVE) on page 33
Converting to or from national (Unicode) representation on page 137
RELATED REFERENCES
CODEPAGE on page 313
Classes and categories of data (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
32 Enterprise COBOL for z/OS, V5.2 Programming Guide
Assigning values to group data items (MOVE)
Use the MOVE statement to assign values to group data items.
You can move a national group item (a data item that is described with the
GROUP-USAGE NATIONAL clause) to another national group item. The compiler
processes the move as though each national group item were an elementary item
of category national, that is, as if each item were described as PIC N(m), where m
is the length of that item in national character positions.
You can move an alphanumeric group item to an alphanumeric group item or to a
national group item. You can also move a national group item to an alphanumeric
group item. The compiler performs such moves as group moves, that is, without
consideration of the individual elementary items in the sending or receiving group,
and without conversion of the sending data item. Be sure that the subordinate data
descriptions in the sending and receiving group items are compatible. The moves
occur even if a destructive overlap could occur at run time.
You can code the CORRESPONDING phrase in a MOVE statement to move subordinate
elementary items from one group item to the identically named corresponding
subordinate elementary items in another group item:
01 Group-X.
02 T-Code Pic X Value "A".
02 Month Pic 99 Value 04.
02 State Pic XX Value "CA".
02 Filler PIC X.
01 Group-N Group-Usage National.
02 State Pic NN.
02 Month Pic 99.
02 Filler Pic N.
02 Total Pic 999.
. . .
MOVE CORR Group-X TO Group-N
In the example above, State and Month within Group-N receive the values in
national representation of State and Month, respectively, from Group-X. The other
data items in Group-N are unchanged. (Filler items in a receiving group item are
unchanged by a MOVE CORRESPONDING statement.)
In a MOVE CORRESPONDING statement, sending and receiving group items are treated
as group items, not as elementary data items; group semantics apply. That is, the
elementary data items within each group are recognized, and the results are the
same as if each pair of corresponding data items were referenced in a separate
MOVE statement. Data conversions are performed according to the rules for the MOVE
statement as specified in the related reference below. For details about which types
of elementary data items correspond, see the related reference about the
CORRESPONDING phrase.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
National groups on page 133
RELATED TASKS
Assigning values to elementary data items (MOVE) on page 32
Using national groups on page 134
Converting to or from national (Unicode) representation on page 137
Chapter 2. Using data 33
RELATED REFERENCES
Classes and categories of group items (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
CORRESPONDING phrase (Enterprise COBOL Language Reference)
Assigning arithmetic results (MOVE or COMPUTE)
When assigning a number to a data item, consider using the COMPUTE statement
instead of the MOVE statement.
Move w to z
Compute z = w
In the example above, the two statements in most cases have the same effect. The
MOVE statement however carries out the assignment with truncation. You can use
the DIAGTRUNC compiler option to request that the compiler issue a warning for
MOVE statements that might truncate numeric receivers.
When significant left-order digits would be lost in execution, the COMPUTE statement
can detect the condition and allow you to handle it. If you use the ON SIZE ERROR
phrase of the COMPUTE statement, the compiler generates code to detect a
size-overflow condition. If the condition occurs, the code in the ON SIZE ERROR
phrase is performed, and the content of z remains unchanged. If you do not
specify the ON SIZE ERROR phrase, the assignment is carried out with truncation.
There is no ON SIZE ERROR support for the MOVE statement.
You can also use the COMPUTE statement to assign the result of an arithmetic
expression or intrinsic function to a data item. For example:
Compute z = y + (x ** 3)
Compute x = Function Max(x y z)
You can assign the results of date, time, mathematical, and other calculations to
data items by using Language Environment callable services. Language
Environment services are available through a standard COBOL CALL statement, and
the values they return are passed in the parameters of the CALL statement. For
example, you can call the Language Environment service CEESIABS to find the
absolute value of a data item by coding the following statement:
Call CEESIABS Using Arg, Feedback-code, Result.
As a result of this call, data item Result is assigned the absolute value of the value
in data item Arg; data item Feedback-code contains the return code that indicates
whether the service completed successfully. You have to define all the data items in
the DATA DIVISION using the correct descriptions according to the requirements of
the particular callable service. For the example above, the data items could be
defined as follows:
77 Arg Pic s9(9) Binary.
77 Feedback-code Pic x(12) Display.
77 Result Pic s9(9) Binary.
RELATED REFERENCES
DIAGTRUNC on page 319
Intrinsic functions (Enterprise COBOL Language Reference)
Language Environment Programming Reference (Callable services)
Assigning input from a screen or file (ACCEPT)
One way to assign a value to a data item is to read the value from a screen or a
file.
34 Enterprise COBOL for z/OS, V5.2 Programming Guide
To enter data from the screen, first associate the monitor with a mnemonic-name in
the SPECIAL-NAMES paragraph. Then use ACCEPT to assign the line of input entered
at the screen to a data item. For example:
Environment Division.
Configuration Section.
Special-Names.
Console is Names-Input.
. . .
Accept Customer-Name From Names-Input
To read from a file instead of the screen, make the following change:
v Change Console to device, where device is any valid system device (for example,
SYSIN). For example:
SYSIN is Names-Input
device can be a ddname that references a z/OS UNIX file system path. If this
ddname is not defined and your program is running in the z/OS UNIX
environment, stdin is the input source. If this ddname is not defined and your
program is not running in the z/OS UNIX environment, the ACCEPT statement
fails.
When you use the ACCEPT statement, you can assign a value to an alphanumeric or
national group item, or to an elementary data item that has USAGE DISPLAY, USAGE
DISPLAY-1, or USAGE NATIONAL.
When you assign a value to a USAGE NATIONAL data item, input data from the
console is converted from the EBCDIC code page specified in the CODEPAGE
compiler option to national (Unicode UTF-16) representation. This is the only case
where conversion of national data is done when you use the ACCEPT statement.
Conversion is done in this case because the input is known to be coming from a
screen.
To have conversion done when the input data is from any other device, use the
NATIONAL-OF intrinsic function.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Converting alphanumeric or DBCS to national (NATIONAL-OF) on page 139
RELATED REFERENCES
CODEPAGE on page 313
ACCEPT statement (Enterprise COBOL Language Reference)
SPECIAL-NAMES paragraph (Enterprise COBOL Language Reference)
Displaying values on a screen or in a file (DISPLAY)
You can display the value of a data item on a screen or write it to a file by using
the DISPLAY statement.
Display "No entry for surname " Customer-Name " found in the file.".
In the example above, if the content of data item Customer-Name is JOHNSON,
then the statement displays the following message on the system logical output
device:
No entry for surname JOHNSON found in the file.
Chapter 2. Using data 35
To write data to a destination other than the system logical output device, use the
UPON phrase with a destination other than SYSOUT. For example, the following
statement writes to the file that is specified in the SYSPUNCH DD statement:
Display "Hello" upon syspunch.
You can specify a file in the z/OS UNIX file system by using the SYSPUNCH DD
statement. For example, the following definition causes DISPLAY output to be
written to the file /u/userid/cobol/demo.lst:
//SYSPUNCH DD PATH=/u/userid/cobol/demo.lst,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU,
// FILEDATA=TEXT
The following statement writes to the job log or console and to the TSO screen if
you are running under TSO:
Display "Hello" upon console.
When you display the value of a USAGE NATIONAL data item to the console, the data
item is converted from Unicode (UTF-16) representation to EBCDIC based on the
value of the CODEPAGE option. This is the only case in which conversion of national
data is done when you use the DISPLAY statement. Conversion is done in this case
because the output is known to be directed to a screen.
To have a national data item be converted when you direct output to a different
device, use the DISPLAY-OF intrinsic function, as in the following example:
01 Data-in-Unicode pic N(10) usage national.
. . .
Display function Display-of(Data-in-Unicode, 00037)
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Displaying data on the system logical output device
Using WITH NO ADVANCING on page 37
Converting national to alphanumeric (DISPLAY-OF) on page 139
Coding COBOL programs to run under CICS on page 419
RELATED REFERENCES
CODEPAGE on page 313
DISPLAY statement (Enterprise COBOL Language Reference)
Displaying data on the system logical output device
To write data to the system logical output device, either omit the UPON clause or
use the UPON clause with destination SYSOUT.
Display "Hello" upon sysout.
The output is directed to the ddname that you specify in the OUTDD compiler
option. You can specify a file in the z/OS UNIX file system with this ddname.
If the OUTDD ddname is not allocated and you are not running in the z/OS UNIX
environment, a default DD of SYSOUT=* is allocated. If the OUTDD ddname is not
allocated and you are running in the z/OS UNIX environment, the _IGZ_SYSOUT
environment variable is used as follows:
Undefined or set to stdout
Output is routed to stdout (file descriptor 1).
36 Enterprise COBOL for z/OS, V5.2 Programming Guide
Set to stderr
Output is routed to stderr (file descriptor 2).
Otherwise (set to something other than stdout or stderr)
The DISPLAY statement fails; a severity-3 Language Environment condition
is raised.
When DISPLAY output is routed to stdout or stderr, the output is not subdivided
into records. The output is written as a single stream of characters without line
breaks.
If OUTDD and the Language Environment runtime option MSGFILE specify the same
ddname, both DISPLAY output and Language Environment runtime diagnostics are
routed to the Language Environment message file.
RELATED TASKS
Setting and accessing environment variables on page 454
RELATED REFERENCES
OUTDD on page 344
DISPLAY statement (Enterprise COBOL Language Reference)
Using WITH NO ADVANCING
If you specify the WITH NO ADVANCING phrase, and output is going to a ddname, the
printer control character + (plus) is placed into the first output position from the
next DISPLAY statement. + is the ANSI-defined printer control character that
suppresses line spacing before a record is printed.
If you specify the WITH NO ADVANCING phrase and the output is going to stdout or
stderr, a newline character is not appended to the end of the stream. A subsequent
DISPLAY statement might add additional characters to the end of the stream.
If you do not specify WITH NO ADVANCING, and the output is going to a ddname, the
printer control character ' ' (space) is placed into the first output position from the
next DISPLAY statement, indicating single-spaced output.
DISPLAY "ABC"
DISPLAY "CDEF" WITH NO ADVANCING
DISPLAY "GHIJK" WITH NO ADVANCING
DISPLAY "LMNOPQ"
DISPLAY "RSTUVWX"
If you code the statements above, the result sent to the output device is:
ABC
CDEF
+GHIJK
+LMNOPQ
RSTUVMX
The output that is printed depends on how the output device interprets printer
control characters.
If you do not specify the WITH NO ADVANCING phrase and the output is going to
stdout or stderr, a newline character is appended to the end of the stream.
RELATED REFERENCES
DISPLAY statement (Enterprise COBOL Language Reference)
Chapter 2. Using data 37
Using intrinsic functions (built-in functions)
Some high-level programming languages have built-in functions that you can
reference in your program as if they were variables that have defined attributes
and a predetermined value. In COBOL, these functions are called intrinsic functions.
They provide capabilities for manipulating strings and numbers.
Because the value of an intrinsic function is derived automatically at the time of
reference, you do not need to define functions in the DATA DIVISION. Define only
the nonliteral data items that you use as arguments. Figurative constants are not
allowed as arguments.
A function-identifier is the combination of the COBOL reserved word FUNCTION
followed by a function name (such as Max), followed by any arguments to be used
in the evaluation of the function (such as x, y, z). For example, the groups of
highlighted words below are function-identifiers:
Unstring Function Upper-case(Name) Delimited By Space
Into Fname Lname
Compute A = 1 + Function Log10(x)
Compute M = Function Max(x y z)
A function-identifier represents both the invocation of the function and the data
value returned by the function. Because it actually represents a data item, you can
use a function-identifier in most places in the PROCEDURE DIVISION where a data
item that has the attributes of the returned value can be used.
The COBOL word function is a reserved word, but the function-names are not
reserved. You can use them in other contexts, such as for the name of a data item.
For example, you could use Sqrt to invoke an intrinsic function and to name a
data item in your program:
Working-Storage Section.
01 x Pic 99 value 2.
01 y Pic 99 value 4.
01 z Pic 99 value 0.
01 Sqrt Pic 99 value 0.
. . .
Compute Sqrt = 16 ** .5
Compute z = x + Function Sqrt(y)
. . .
A function-identifier represents a value that is of one of these types: alphanumeric,
national, numeric, or integer. You can include a substring specification (reference
modifier) in a function-identifier for alphanumeric or national functions. Numeric
intrinsic functions are further classified according to the type of numbers they
return.
The functions MAX and MIN can return either type of value depending on the type of
arguments you supply.
Functions can reference other functions as arguments provided that the results of
the nested functions meet the requirements for the arguments of the outer function.
For example, Function Sqrt(5) returns a numeric value. Thus, the three arguments
to the MAX function below are all numeric, which is an allowable argument type for
this function:
Compute x = Function Max((Function Sqrt(5)) 2.5 3.5)
38 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Processing table items using intrinsic functions on page 89
Converting data items (intrinsic functions) on page 116
Evaluating data items (intrinsic functions) on page 119
Using tables (arrays) and pointers
In COBOL, arrays are called tables. A table is a set of logically consecutive data
items that you define in the DATA DIVISION by using the OCCURS clause.
Pointers are data items that contain virtual storage addresses. You define them
either explicitly with the USAGE IS POINTER clause in the DATA DIVISION or
implicitly as ADDRESS OF special registers.
You can perform the following operations with pointer data items:
v Pass them between programs by using the CALL . . . BY REFERENCE statement.
v Move them to other pointers by using the SET statement.
v Compare them to other pointers for equality by using a relation condition.
v Initialize them to contain an invalid address by using VALUE IS NULL.
Use pointer data items to:
v Accomplish limited base addressing, particularly if you want to pass and receive
addresses of a record area that is defined with OCCURS DEPENDING ON and is
therefore variably located.
v Handle a chained list.
RELATED TASKS
Defining a table (OCCURS) on page 67
Using procedure and function pointers on page 477
Storage and its addressability
When you run COBOL programs, the programs and the data that they use reside
in virtual storage. Storage that you use with COBOL can be either below the 16
MB line or above the 16 MB line but below the 2 GB bar. Two modes of addressing
are available to address this storage: 24-bit and 31-bit.
You can address storage below (but not above) the 16 MB line with 24-bit
addressing. You can address storage either above or below the 16 MB line with
31-bit addressing. Unrestricted storage is addressable by 31-bit addressing and
therefore encompasses all the storage available to your program, both above and
below the 16 MB line.
Enterprise COBOL does not directly exploit the 64-bit virtual addressing capability
of z/OS; however, COBOL applications running in 31-bit or 24-bit addressing
mode are fully supported on 64-bit z/OS systems.
Addressing mode (AMODE) is the attribute that tells which hardware addressing mode
is supported by your program: 24-bit addressing, 31-bit addressing, or either 24-bit
or 31-bit addressing. These attributes are AMODE 24, AMODE 31, and AMODE ANY,
| respectively. The program object and the executing program each have an AMODE
attribute. Enterprise COBOL V5.1.1 object programs are either AMODE MIN for
cases where AMODE 24 is possible, or AMODE 31 in all other cases. See
Restrictions for AMODE on page 40.
Chapter 2. Using data 39
Residency mode (RMODE) is the attribute of a program object that identifies where in
virtual storage the program will reside: below the 16 MB line, or either below or
above. This attribute is RMODE 24 or RMODE ANY.
Enterprise COBOL uses Language Environment services to control the storage used
at run time. Thus COBOL compiler options and Language Environment runtime
options influence the AMODE and RMODE attributes of your program and data, alone
and in combination:
DATA Compiler option that influences the location of storage for WORKING-STORAGE
data, I-O buffers, and parameter lists for programs compiled with RENT.
RMODE Compiler option that influences the residency mode.
RENT Compiler option to generate a reentrant program.
HEAP Runtime option that controls storage for the runtime heap. For example,
COBOL WORKING-STORAGE is allocated from heap storage when the COBOL
program is compiled with the RENT option and is in one of the following
cases:
v Compiled with Enterprise COBOL V4.2 or earlier releases
v Compiled with the DATA(24) compiler option
v Running in CICS
v A COBOL V5.1.1 in a program object that contains only COBOL
programs (V5.1.1, V4.2 or earlier) and assembly programs. There are no
Language Environment interlanguage calls within the program object
and no COBOL V5.1.0 programs.
v A COBOL V5 program in a program object where the main entry point
is COBOL V5. In this case, the program object can contain Language
Environment interlanguage calls, with COBOL statically linking with C,
C++ or PL/I. All COBOL V5 programs within such program objects
(even if they are not the main entry point) have their WORKING-STORAGE
allocated from heap storage.
STACK Runtime option that controls storage for the runtime stack. For example,
COBOL LOCAL-STORAGE is allocated from stack storage.
ALL31 Runtime option that specifies whether an application can run entirely in
AMODE 31.
Restrictions for AMODE
AMODE 24 execution is not supported in the following cases, and the applications
must run in AMODE 31:
v Programs containing XML PARSE statements
v Programs containing XML GENERATE statements
v Program objects containing COBOL bound together with C, C++, or PL/I
programs, and communicating via static CALL
v Programs containing object-oriented language syntax, such as INVOKE statements,
or object-oriented class definitions
v Programs compiled with any of the following compiler options:
DLL
PGMNAME(LONGUPPER)
PGMNAME(LONGMIXED)
v Multithreaded applications
40 Enterprise COBOL for z/OS, V5.2 Programming Guide
Note: A program compiled with the THREAD option can run in AMODE 24, but only
in an application that does not have multiple threads or PL/I tasks.
v Programs run from the z/OS UNIX file system
Note: An AMODE 31 driver program resident in the z/OS UNIX file system can
contain a dynamic call to an AMODE 24 program module resident in an MVS PDS
or PDSE.
v Programs used as COBOL compiler exit modules that are specified on the EXIT
compiler option
v Language Environment enclaves that use XPLINK, including either the enclaves
that contain non-COBOL programs compiled with the XPLINK compiler option, or
run with the XPLINK runtime option
Note: To run COBOL programs with addressing mode 24, you must compile all
COBOL programs with Enterprise COBOL V5.1.1, or later versions; or Enterprise
COBOL V4.2 or earlier versions. If any component of a program object is compiled
with Enterprise COBOL V5.1.0, the program object must run in addressing mode
31. COBOL programs that run with addressing mode 24 must be linked with the
binder option RMODE(24).
Settings for RMODE
The RMODE and RENT options determine the RMODE attribute of your program.
Table 4. Effect of RMODE and RENT compiler options on the RMODE attribute
RMODE compiler option RENT compiler option RMODE attribute
RMODE(AUTO) RENT RMODE ANY
RMODE(AUTO) NORENT RMODE 24
RMODE(24) RENT or NORENT RMODE 24
RMODE(ANY) RENT RMODE ANY
RMODE(ANY) NORENT Compiler option conflict.
If the NORENT option is
specified, the RMODE(24)
or RMODE(AUTO) compiler
option must be specified.
Link-edit considerations: When the object code that COBOL generates has an
attribute of RMODE 24, you must link-edit it with RMODE 24. When the object code
that COBOL generates has an attribute of RMODE ANY, you can link-edit it with
RMODE ANY or RMODE 24.
Storage restrictions for passing data
Do not pass parameters that are allocated in storage above the 16 MB line to AMODE
24 subprograms. Force the WORKING-STORAGE data and parameter lists below the line
for programs that run in 31-bit addressing mode and pass data to programs that
run in AMODE 24:
v Compile with the RENT and DATA(24) compiler options, or if the WORKING-STORAGE
is on the HEAP (see previous description of the HEAP option), run them with the
HEAP(,,BELOW) runtime option.
v Compile with the NORENT compiler option.
Chapter 2. Using data 41
Location of data areas
For reentrant programs, the DATA compiler option, and the HEAP runtime option
control whether storage for data areas such as WORKING-STORAGE SECTION and FD
record areas is obtained from below the 16 MB line or from unrestricted storage.
Compile programs with RENT and RMODE(ANY) or RMODE(AUTO) if they will be run
with 31-bit addressing in virtual storage addresses above the 16 MB line. The DATA
option does not affect programs that are compiled with NORENT.
Storage for LOCAL-STORAGE data
The location of LOCAL-STORAGE data items is controlled by the STACK runtime option
and the AMODE of the program. LOCAL-STORAGE data items are acquired in
unrestricted storage when the STACK(,,ANYWHERE) runtime option is in effect and
the program is running in AMODE 31. Otherwise LOCAL-STORAGE is acquired below
the 16 MB line. The DATA compiler option does not influence the location of
LOCAL-STORAGE data.
Storage for external data
In addition to affecting how storage is obtained for dynamic data areas
(WORKING-STORAGE, FD record areas, and parameter lists), the DATA compiler option
can also influence where storage for EXTERNAL data is obtained. Storage required for
EXTERNAL data is obtained from unrestricted storage if the following conditions are
met:
v The program is compiled with the DATA(31) and RENT compiler options.
v The HEAP(,,ANYWHERE) runtime option is in effect.
v The ALL31(ON) runtime option is in effect.
In all other cases, the storage for EXTERNAL data is obtained from below the 16 MB
line. If you specify the ALL31(ON) runtime option, all the programs in the run unit
must be capable of running in 31-bit addressing mode.
Storage for QSAM input-output buffers
The DATA compiler option can also influence where input-output buffers for QSAM
files are obtained. See the related references below for information about allocation
of buffers for QSAM files and the DATA compiler option.
RELATED CONCEPTS
AMODE switching on page 469
Language Environment Programming Guide (AMODE considerations for heap
storage)
RELATED TASKS
Chapter 24, Using subprograms, on page 463
Chapter 25, Sharing data, on page 481
RELATED REFERENCES
Allocation of buffers for QSAM files on page 181
Allocation of record areas for VSAM files on page 209
DATA on page 318
RENT on page 348
RMODE on page 349
Performance-related compiler options on page 659
Language Environment Programming Reference (HEAP, STACK, ALL31)
MVS Program Management: User's Guide and Reference
42 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 3. Working with numbers and arithmetic
In general, you can view COBOL numeric data as a series of decimal digit
positions. However, numeric items can also have special properties such as an
arithmetic sign or a currency sign.
To define, display, and store numeric data so that you can perform arithmetic
operations efficiently:
v Use the PICTURE clause and the characters 9, +, -, P, S, and V to define numeric
data.
v Use the PICTURE clause and editing characters (such as Z, comma, and period)
along with MOVE and DISPLAY statements to display numeric data.
v Use the USAGE clause with various formats to control how numeric data is stored.
v Use the numeric class test to validate that data values are appropriate.
v Use ADD, SUBTRACT, MULTIPLY, DIVIDE, and COMPUTE statements to perform
arithmetic.
v Use the CURRENCY SIGN clause and appropriate PICTURE characters to designate
the currency you want.
RELATED TASKS
Defining numeric data
Displaying numeric data on page 45
Controlling how numeric data is stored on page 46
Checking for incompatible data (numeric class test) on page 54
Performing arithmetic on page 55
Using currency signs on page 65
Defining numeric data
Define numeric items by using the PICTURE clause with the character 9 in the data
description to represent the decimal digits of the number. Do not use an X, which
is for alphanumeric data items.
For example, Count-y below is a numeric data item, an external decimal item that
has USAGE DISPLAY (a zoned decimal item):
05 Count-y Pic 9(4) Value 25.
05 Customer-name Pic X(20) Value "Johnson".
You can similarly define numeric data items to hold national characters (UTF-16).
For example, Count-n below is an external decimal data item that has USAGE
NATIONAL (a national decimal item):
05 Count-n Pic 9(4) Value 25 Usage National.
You can code up to 18 digits in the PICTURE clause when you compile using the
default compiler option ARITH(COMPAT) (referred to as compatibility mode). When
you compile using ARITH(EXTEND) (referred to as extended mode), you can code up
to 31 digits in the PICTURE clause.
Other characters of special significance that you can code are:
P Indicates leading or trailing zeros
Copyright IBM Corp. 1991, 2015 43
S Indicates a sign, positive or negative
V Implies a decimal point
The s in the following example means that the value is signed:
05 Price Pic s99v99.
The field can therefore hold a positive or a negative value. The v indicates the
position of an implied decimal point, but does not contribute to the size of the
item because it does not require a storage position. An s usually does not
contribute to the size of a numeric item, because by default s does not require a
storage position.
However, if you plan to port your program or data to a different machine, you
might want to code the sign for a zoned decimal data item as a separate position
in storage. In the following case, the sign takes 1 byte:
05 Price Pic s99V99 Sign Is Leading, Separate.
This coding ensures that the convention your machine uses for storing a
nonseparate sign will not cause unexpected results on a machine that uses a
different convention.
Separate signs are also preferable for zoned decimal data items that will be printed
or displayed.
Separate signs are required for national decimal data items that are signed. The
sign takes 2 bytes of storage, as in the following example:
05 Price Pic s99V99 Usage National Sign Is Leading, Separate.
You cannot use the PICTURE clause with internal floating-point data (COMP-1 or
COMP-2). However, you can use the VALUE clause to provide an initial value for an
internal floating-point literal:
05 Compute-result Usage Comp-2 Value 06.23E-24.
For information about external floating-point data, see the examples referenced
below and the related concept about formats for numeric data.
Examples: numeric data and internal representation on page 51
RELATED CONCEPTS
Formats for numeric data on page 47
Appendix A, Intermediate results and arithmetic precision, on page 675
RELATED TASKS
Displaying numeric data on page 45
Controlling how numeric data is stored on page 46
Performing arithmetic on page 55
Defining national numeric data items on page 133
RELATED REFERENCES
Sign representation of zoned and packed-decimal data on page 53
Storage of character data on page 137
ARITH on page 309
NUMPROC on page 339
SIGN clause (Enterprise COBOL Language Reference)
44 Enterprise COBOL for z/OS, V5.2 Programming Guide
Displaying numeric data
You can define numeric items with certain editing symbols (such as decimal points,
commas, dollar signs, and debit or credit signs) to make the items easier to read
and understand when you display or print them.
For example, in the code below, Edited-price is a numeric-edited item that has
USAGE DISPLAY. (You can specify the clause USAGE IS DISPLAY for numeric-edited
items; however, it is implied. It means that the items are stored in character
format.)
05 Price Pic 9(5)v99.
05 Edited-price Pic $zz,zz9.99.
. . .
Move Price To Edited-price
Display Edited-price
If the contents of Price are 0150099 (representing the value 1,500.99), $ 1,500.99 is
displayed when you run the code. The z in the PICTURE clause of Edited-price
indicates the suppression of leading zeros.
You can define numeric-edited data items to hold national (UTF-16) characters
| instead of alphanumeric characters. To do so, define the numeric-edited items as
USAGE NATIONAL. The effect of the editing symbols is the same for numeric-edited
items that have USAGE NATIONAL as it is for numeric-edited items that have USAGE
DISPLAY, except that the editing is done with national characters. For example, if
Edited-price is declared as USAGE NATIONAL in the code above, the item is edited
and displayed using national characters.
To display numeric or numeric-edited data items that have USAGE NATIONAL in
EBCDIC, direct them to CONSOLE. For example, if Edited-price in the code above
has USAGE NATIONAL, $ 1,500.99 is displayed when you run the program if the last
statement above is:
Display Edited-price Upon Console
You can cause an elementary numeric or numeric-edited item to be filled with
spaces when a value of zero is stored into it by coding the BLANK WHEN ZERO clause
for the item. For example, each of the DISPLAY statements below causes blanks to
be displayed instead of zeros:
05 Price Pic 9(5)v99.
05 Edited-price-D Pic $99,999.99
Blank When Zero.
05 Edited-price-N Pic $99,999.99 Usage National
Blank When Zero.
. . .
Move 0 to Price
Move Price to Edited-price-D
Move Price to Edited-price-N
Display Edited-price-D
Display Edited-price-N upon console
You cannot use numeric-edited items as sending operands in arithmetic
expressions or in ADD, SUBTRACT, MULTIPLY, DIVIDE, or COMPUTE statements. (Numeric
editing takes place when a numeric-edited item is the receiving field for one of
these statements, or when a MOVE statement has a numeric-edited receiving field
and a numeric-edited or numeric sending field.) You use numeric-edited items
primarily for displaying or printing numeric data.
Chapter 3. Working with numbers and arithmetic 45
You can move numeric-edited items to numeric or numeric-edited items. In the
following example, the value of the numeric-edited item (whether it has USAGE
DISPLAY or USAGE NATIONAL) is moved to the numeric item:
Move Edited-price to Price
Display Price
If these two statements immediately followed the statements in the first example
above, then Price would be displayed as 0150099, representing the value 1,500.99.
Price would also be displayed as 0150099 if Edited-price had USAGE NATIONAL.
You can also move numeric-edited items to alphanumeric, alphanumeric-edited,
floating-point, and national data items. For a complete list of the valid receiving
items for numeric-edited data, see the related reference about the MOVE statement.
Examples: numeric data and internal representation on page 51
RELATED TASKS
Displaying values on a screen or in a file (DISPLAY) on page 35
Controlling how numeric data is stored
Defining numeric data on page 43
Performing arithmetic on page 55
Defining national numeric data items on page 133
Converting to or from national (Unicode) representation on page 137
RELATED REFERENCES
MOVE statement (Enterprise COBOL Language Reference)
BLANK WHEN ZERO clause (Enterprise COBOL Language Reference)
Controlling how numeric data is stored
You can control how the computer stores numeric data items by coding the USAGE
clause in your data description entries.
You might want to control the format for any of several reasons such as these:
v Arithmetic performed with computational data types is more efficient than with
USAGE DISPLAY or USAGE NATIONAL data types.
v Packed-decimal format requires less storage per digit than USAGE DISPLAY or
USAGE NATIONAL data types.
v Packed-decimal format converts to and from DISPLAY or NATIONAL format more
efficiently than binary format does.
v Floating-point format is well suited for arithmetic operands and results with
widely varying scale, while maintaining the maximal number of significant
digits.
v You might need to preserve data formats when you move data from one
machine to another.
The numeric data you use in your program will have one of the following formats
available with COBOL:
v External decimal (USAGE DISPLAY or USAGE NATIONAL)
v External floating point (USAGE DISPLAY or USAGE NATIONAL)
v Internal decimal (USAGE PACKED-DECIMAL)
v Binary (USAGE BINARY)
v Native binary (USAGE COMP-5)
46 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Internal floating point (USAGE COMP-1 or USAGE COMP-2)
COMP and COMP-4 are synonymous with BINARY, and COMP-3 is synonymous with
PACKED-DECIMAL.
The compiler converts displayable numbers to the internal representation of their
numeric values before using them in arithmetic operations. Therefore it is often
more efficient if you define data items as BINARY or PACKED-DECIMAL than as
DISPLAY or NATIONAL. For example:
05 Initial-count Pic S9(4) Usage Binary Value 1000.
Regardless of which USAGE clause you use to control the internal representation of a
value, you use the same PICTURE clause conventions and decimal value in the
VALUE clause (except for internal floating-point data, for which you cannot use a
PICTURE clause).
Examples: numeric data and internal representation on page 51
RELATED CONCEPTS
Formats for numeric data
Data format conversions on page 52
Appendix A, Intermediate results and arithmetic precision, on page 675
RELATED TASKS
Defining numeric data on page 43
Displaying numeric data on page 45
Performing arithmetic on page 55
RELATED REFERENCES
Conversions and precision on page 52
Sign representation of zoned and packed-decimal data on page 53
Formats for numeric data
Several formats are available for numeric data.
External decimal (DISPLAY and NATIONAL) items
When USAGE DISPLAY is in effect for a category numeric data item (either because
you have coded it, or by default), each position (byte) of storage contains one
decimal digit. The items are stored in displayable form. External decimal items that
have USAGE DISPLAY are referred to as zoned decimal data items.
When USAGE NATIONAL is in effect for a category numeric data item, 2 bytes of
storage are required for each decimal digit. The items are stored in UTF-16 format.
| External decimal items that have USAGE NATIONAL must only contain valid
| UTF-16 digits. If they do not, the data is illegal and the behaviour of the generated
| code is undefined. External decimal items that have USAGE NATIONAL are referred to
as national decimal data items.
National decimal data items, if signed, must have the SIGN SEPARATE clause in
effect. All other rules for zoned decimal items apply to national decimal items. You
can use national decimal items anywhere that other category numeric data items
can be used.
Chapter 3. Working with numbers and arithmetic 47
External decimal (both zoned decimal and national decimal) data items are
primarily intended for receiving and sending numbers between your program and
files, terminals, or printers. You can also use external decimal items as operands
and receivers in arithmetic processing. However, if your program performs a lot of
intensive arithmetic, and efficiency is a high priority, COBOL's computational
numeric types might be a better choice for the data items used in the arithmetic.
External floating-point (DISPLAY and NATIONAL) items
When USAGE DISPLAY is in effect for a floating-point data item (either because you
have coded it, or by default), each PICTURE character position (except for v, an
implied decimal point, if used) takes 1 byte of storage. The items are stored in
displayable form. External floating-point items that have USAGE DISPLAY are
referred to as display floating-point data items in this information when necessary to
distinguish them from external floating-point items that have USAGE NATIONAL.
In the following example, Compute-Result is implicitly defined as a display
floating-point item:
05 Compute-Result Pic -9v9(9)E-99.
The minus signs (-) do not mean that the mantissa and exponent must necessarily
be negative numbers. Instead, they mean that when the number is displayed, the
sign appears as a blank for positive numbers or a minus sign for negative
numbers. If you instead code a plus sign (+), the sign appears as a plus sign for
positive numbers or a minus sign for negative numbers.
When USAGE NATIONAL is in effect for a floating-point data item, each PICTURE
character position (except for v, if used) takes 2 bytes of storage. The items are
stored as national characters (UTF-16). External floating-point items that have
USAGE NATIONAL are referred to as national floating-point data items.
The existing rules for display floating-point items apply to national floating-point
items.
In the following example, Compute-Result-N is a national floating-point item:
05 Compute-Result-N Pic -9v9(9)E-99 Usage National.
If Compute-Result-N is displayed, the signs appear as described above for
Compute-Result, but in national characters. To instead display Compute-Result-N in
EBCDIC characters, direct it to the console:
Display Compute-Result-N Upon Console
You cannot use the VALUE clause for external floating-point items.
As with external decimal numbers, external floating-point numbers have to be
converted (by the compiler) to an internal representation of their numeric value
before they can be used in arithmetic operations. If you compile with the default
option ARITH (COMPAT), external floating-point numbers are converted to long
(64-bit) floating-point format. If you compile with ARITH (EXTEND), they are instead
converted to extended-precision (128-bit) floating-point format.
Binary (COMP) items
BINARY, COMP, and COMP-4 are synonyms. Binary-format numbers occupy 2, 4, or 8
bytes of storage. If the PICTURE clause specifies that an item is signed, the leftmost
bit is used as the operational sign.
48 Enterprise COBOL for z/OS, V5.2 Programming Guide
A binary number with a PICTURE description of four or fewer decimal digits
occupies 2 bytes; five to nine decimal digits, 4 bytes; and 10 to 18 decimal digits, 8
bytes. Binary items with nine or more digits require more handling by the
compiler. Testing them for the SIZE ERROR condition and rounding is more
cumbersome than with other types.
You can use binary items, for example, for indexes, subscripts, switches, and
arithmetic operands or results.
Use the TRUNC(STD|OPT|BIN) compiler option to indicate how binary data (BINARY,
COMP, or COMP-4) is to be truncated.
Native binary (COMP-5) items
| Data items that you define as USAGE COMP-5 are represented in storage as binary
data. However, unlike USAGE COMP items, they can contain values of magnitude up
to the capacity of the native binary representation (2, 4, or 8 bytes) rather than
being limited to the value implied by the number of 9s in the PICTURE clause.
When you move or store numeric data into a COMP-5 item, truncation occurs at the
binary field size rather than at the COBOL PICTURE size limit. When you reference
a COMP-5 item, the full binary field size is used in the operation.
COMP-5 is thus particularly useful for binary data items that originate in
non-COBOL programs where the data might not conform to a COBOL PICTURE
clause.
The table below shows the ranges of possible values for COMP-5 data items.
Table 5. Ranges in value of COMP-5 data items
PICTURE Storage representation Numeric values
S9(1) through S9(4) Binary halfword (2 bytes) -32768 through +32767
S9(5) through S9(9) Binary fullword (4 bytes) -2,147,483,648 through +2,147,483,647
S9(10) through Binary doubleword (8 -9,223,372,036,854,775,808 through
S9(18) bytes) +9,223,372,036,854,775,807
9(1) through 9(4) Binary halfword (2 bytes) 0 through 65535
9(5) through 9(9) Binary fullword (4 bytes) 0 through 4,294,967,295
9(10) through 9(18) Binary doubleword (8 0 through 18,446,744,073,709,551,615
bytes)
You can specify scaling (that is, decimal positions or implied integer positions) in
the PICTURE clause of COMP-5 items. If you do so, you must appropriately scale the
maximal capacities listed above. For example, a data item you describe as PICTURE
S99V99 COMP-5 is represented in storage as a binary halfword, and supports a range
of values from -327.68 through +327.67.
Large literals in VALUE clauses: Literals specified in VALUE clauses for COMP-5 items
can, with a few exceptions, contain values of magnitude up to the capacity of the
native binary representation. See Enterprise COBOL Language Reference for the
exceptions.
Regardless of the setting of the TRUNC compiler option, COMP-5 data items behave
like binary data does in programs compiled with TRUNC(BIN).
Chapter 3. Working with numbers and arithmetic 49
Packed-decimal (COMP-3) items
PACKED-DECIMAL and COMP-3 are synonyms. Packed-decimal items occupy 1 byte of
storage for every two decimal digits you code in the PICTURE description, except
that the rightmost byte contains only one digit and the sign. This format is most
efficient when you code an odd number of digits in the PICTURE description, so
that the leftmost byte is fully used. Packed-decimal items are handled as
fixed-point numbers for arithmetic purposes.
Internal floating-point (COMP-1 and COMP-2) items
COMP-1 refers to short floating-point format and COMP-2 refers to long floating-point
format, which occupy 4 and 8 bytes of storage, respectively. The leftmost bit
contains the sign and the next 7 bits contain the exponent; the remaining 3 or 7
bytes contain the mantissa.
COMP-1 and COMP-2 data items are stored in System z hexadecimal format.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
Appendix A, Intermediate results and arithmetic precision, on page 675
RELATED TASKS
Defining numeric data on page 43
Defining national numeric data items on page 133
RELATED REFERENCES
Storage of character data on page 137
TRUNC on page 363
Classes and categories of data (Enterprise COBOL Language Reference)
SIGN clause (Enterprise COBOL Language Reference)
VALUE clause (Enterprise COBOL Language Reference)
50 Enterprise COBOL for z/OS, V5.2 Programming Guide
Examples: numeric data and internal representation
The following table shows the internal representation of numeric items.
Table 6. Internal representation of numeric items
PICTURE and USAGE and
Numeric type optional SIGN clause Value Internal representation
External decimal PIC S9999 DISPLAY + 1234 F1 F2 F3 C4
- 1234 F1 F2 F3 D4
1234 F1 F2 F3 C4
PIC 9999 DISPLAY 1234 F1 F2 F3 F4
PIC 9999 NATIONAL 1234 00 31 00 32 00 33 00 34
PIC S9999 DISPLAY + 1234 C1 F2 F3 F4
SIGN LEADING
- 1234 D1 F2 F3 F4
PIC S9999 DISPLAY + 1234 4E F1 F2 F3 F4
SIGN LEADING SEPARATE
- 1234 60 F1 F2 F3 F4
PIC S9999 DISPLAY + 1234 F1 F2 F3 F4 4E
SIGN TRAILING SEPARATE
- 1234 F1 F2 F3 F4 60
PIC S9999 NATIONAL + 1234 00 2B 00 31 00 32 00 33 00 34
SIGN LEADING SEPARATE
- 1234 00 2D 00 31 00 32 00 33 00 34
PIC S9999 NATIONAL + 1234 00 31 00 32 00 33 00 34 00 2B
SIGN TRAILING SEPARATE
- 1234 00 31 00 32 00 33 00 34 00 2D
Binary PIC S9999 BINARY + 1234 04 D2
PIC S9999 COMP
- 1234 FB 2E
PIC S9999 COMP-4
PIC S9999 COMP-5 + 123451 30 39
1
- 12345 CF C7
PIC 9999 BINARY 1234 04 D2
PIC 9999 COMP
PIC 9999 COMP-4
PIC 9999 COMP-5 600001 EA 60
Internal decimal PIC S9999 PACKED-DECIMAL + 1234 01 23 4C
PIC S9999 COMP-3
- 1234 01 23 4D
PIC 9999 PACKED-DECIMAL 1234 01 23 4F
PIC 9999 COMP-3
Internal floating COMP-1 + 1234 43 4D 20 00
point
- 1234 C3 4D 20 00
COMP-2 + 1234 43 4D 20 00 00 00 00 00
- 1234 C3 4D 20 00 00 00 00 00
External floating PIC +9(2).9(2)E+99 DISPLAY + 12.34E+02 4E F1 F2 4B F3 F4 C5 4E F0 F2
point
- 12.34E+02 60 F1 F2 4B F3 F4 C5 4E F0 F2
PIC +9(2).9(2)E+99 NATIONAL + 12.34E+02 00 2B 00 31 00 32 00 2E 00 33
00 34 00 45 00 2B 00 30 00 32
- 12.34E+02 00 2D 00 31 00 32 00 2E 00 33
00 34 00 45 00 2B 00 30 00 32
Chapter 3. Working with numbers and arithmetic 51
Table 6. Internal representation of numeric items (continued)
PICTURE and USAGE and
Numeric type optional SIGN clause Value Internal representation
1. The example demonstrates that COMP-5 data items can contain values of magnitude up to the capacity of the
native binary representation (2, 4, or 8 bytes), rather than being limited to the value implied by the number of 9s
in the PICTURE clause.
Data format conversions
When the code in your program involves the interaction of items that have
different data formats, the compiler converts those items either temporarily, for
comparisons and arithmetic operations, or permanently, for assignment to the
receiver in a MOVE or COMPUTE statement.
A conversion is actually a move of a value from one data item to another. The
compiler performs any conversions that are required during the execution of
arithmetic or comparisons by using the same rules that are used for MOVE and
COMPUTE statements.
When possible, the compiler performs a move to preserve numeric value instead of
a direct digit-for-digit move.
Conversion generally requires additional storage and processing time because data
is moved to an internal work area and converted before the operation is
performed. The results might also have to be moved back into a work area and
converted again.
Conversions between fixed-point data formats (external decimal, packed decimal,
or binary) are without loss of precision provided that the target field can contain
all the digits of the source operand.
A loss of precision is possible in conversions between fixed-point data formats and
floating-point data formats (short floating point, long floating point, or external
floating point). These conversions happen during arithmetic evaluations that have
a mixture of both fixed-point and floating-point operands.
RELATED REFERENCES
Conversions and precision
Sign representation of zoned and packed-decimal data on page 53
Conversions and precision
In some numeric conversions, a loss of precision is possible; other conversions
preserve precision or result in rounding.
Because both fixed-point and external floating-point items have decimal
characteristics, references to fixed-point items in the following examples include
external floating-point items unless stated otherwise.
When the compiler converts from fixed-point to internal floating-point format,
fixed-point numbers in base 10 are converted to the numbering system used
internally.
When the compiler converts short form to long form for comparisons, zeros are
used for padding the shorter number.
52 Enterprise COBOL for z/OS, V5.2 Programming Guide
Conversions that lose precision
When a USAGE COMP-1 data item is moved to a fixed-point data item that has more
than nine digits, the fixed-point data item will receive only nine significant digits,
and the remaining digits will be zero.
When a USAGE COMP-2 data item is moved to a fixed-point data item that has more
than 18 digits, the fixed-point data item will receive only 18 significant digits, and
the remaining digits will be zero.
Conversions that preserve precision
If a fixed-point data item that has six or fewer digits is moved to a USAGE COMP-1
data item and then returned to the fixed-point data item, the original value is
recovered.
If a USAGE COMP-1 data item is moved to a fixed-point data item of nine or more
digits and then returned to the USAGE COMP-1 data item, the original value is
recovered.
If a fixed-point data item that has 15 or fewer digits is moved to a USAGE COMP-2
data item and then returned to the fixed-point data item, the original value is
recovered.
If a USAGE COMP-2 data item is moved to a fixed-point (not external floating-point)
data item of 18 or more digits and then returned to the USAGE COMP-2 data item,
the original value is recovered.
Conversions that result in rounding
If a USAGE COMP-1 data item, a USAGE COMP-2 data item, an external floating-point
data item, or a floating-point literal is moved to a fixed-point data item, rounding
occurs in the low-order position of the target data item.
If a USAGE COMP-2 data item is moved to a USAGE COMP-1 data item, rounding occurs
in the low-order position of the target data item.
If a fixed-point data item is moved to an external floating-point data item and the
PICTURE of the fixed-point data item contains more digit positions than the PICTURE
of the external floating-point data item, rounding occurs in the low-order position
of the target data item.
RELATED CONCEPTS
Appendix A, Intermediate results and arithmetic precision, on page 675
Sign representation of zoned and packed-decimal data
Sign representation affects the processing and interaction of zoned decimal and
internal decimal data.
Given Xsd, where s is the sign representation and d represents the digit, the valid
sign representations for zoned decimal (USAGE DISPLAY) data without the SIGN IS
SEPARATE clause are:
Positive:
C, A, E, and F
Negative:
D and B
Chapter 3. Working with numbers and arithmetic 53
The COBOL NUMPROC compiler option affects sign processing for zoned decimal and
internal decimal data. NUMPROC has no effect on binary data, national decimal data,
or floating-point data.
NUMPROC(PFD)
Given Xsd, where s is the sign representation and d represents the digit,
when you use NUMPROC(PFD), the compiler assumes that the sign in your
data is one of three preferred signs:
Signed positive or 0:
XC
Signed negative:
XD
Unsigned or alphanumeric:
XF
Based on this assumption, the compiler uses whatever sign it is given to
process data. The preferred sign is generated only where necessary (for
example, when unsigned data is moved to signed data). Using the
NUMPROC(PFD) option can save processing time, but you must use preferred
signs with your data for correct processing.
NUMPROC(NOPFD)
When the NUMPROC(NOPFD) compiler option is in effect, the compiler accepts
any valid sign configuration. The preferred sign is always generated in the
receiver. NUMPROC(NOPFD) is less efficient than NUMPROC(PFD), but you should
use it whenever data that does not use preferred signs might exist.
If an unsigned, zoned-decimal sender is moved to an alphanumeric
receiver, the sign is unchanged (even with NUMPROC(NOPFD) in effect).
RELATED REFERENCES
NUMPROC on page 339
ZWB on page 372
Checking for incompatible data (numeric class test)
The compiler assumes that values you supply for a data item are valid for the
PICTURE and USAGE clauses, and does not check their validity. Ensure that the
contents of a data item conform to the PICTURE and USAGE clauses before using the
item in additional processing.
It can happen that values are passed into your program and assigned to items that
have incompatible data descriptions for those values. For example, nonnumeric
data might be moved or passed into a field that is defined as numeric, or a signed
number might be passed into a field that is defined as unsigned. In either case, the
receiving fields contain invalid data. When you give an item a value that is
incompatible with its data description, references to that item in the PROCEDURE
DIVISION are undefined and your results are unpredictable.
You can use the numeric class test to perform data validation. For example:
Linkage Section.
01 Count-x Pic 999.
. . .
Procedure Division Using Count-x.
If Count-x is numeric then display "Data is good"
54 Enterprise COBOL for z/OS, V5.2 Programming Guide
The numeric class test checks the contents of a data item against a set of values
that are valid for the PICTURE and USAGE of the data item. For example, a
packed-decimal item is checked for hexadecimal values X'0' through X'9' in the
digit positions and for a valid sign value in the sign position (whether separate or
| nonseparate). An external decimal data item that has USAGE DISPLAY is checked for
| hexadecimal values X'0' through X'9' in the digit positions (the lower 4 bits of each
| byte), for a valid zone code in the upper 4 bits of each byte and for a valid sign
| value in the sign position (whether separate or nonseparate). The sign code is in
| the upper 4 bits of the sign byte or in a separate byte if SIGN IS SEPARATE was
| specified. If the SIGN IS SEPARATE clause is used, the upper four bits of all bytes
| must be x'F'.
| Note: Although the ZONEDATA(MIG) compiler option allows toleration of invalid
| zone codes in USAGE DISPLAY numeric (zoned decimal) data items in numeric
| comparisons, invalid zone codes in zoned decimal data items will be treated as
| nonnumeric by the numeric class test.
For zoned decimal and packed-decimal items, the numeric class test is affected by
the NUMPROC compiler option and the NUMCLS option (which is set at installation
time). To determine the NUMCLS setting used at your installation, consult your
system programmer.
If NUMCLS(PRIM) is in effect at your installation, use the following table to find the
values that the compiler considers valid for the sign.
Table 7. NUMCLS(PRIM) and valid signs
NUMPROC(NOPFD) NUMPROC(PFD)
Signed C, D, F C, D, +0 (positive zero)
Unsigned F F
Separate sign +, - +, -, +0 (positive zero)
If NUMCLS(ALT) is in effect at your installation, use the following table to find the
values that the compiler considers valid for the sign.
Table 8. NUMCLS(ALT) and valid signs
NUMPROC(NOPFD) NUMPROC(PFD)
Signed A to F C, D, +0 (positive zero)
Unsigned F F
Separate sign +, - +, -, +0 (positive zero)
RELATED REFERENCES
NUMPROC on page 339
Performing arithmetic
You can use any of several COBOL language features (including COMPUTE,
arithmetic expressions, numeric intrinsic functions, and math and date callable
services) to perform arithmetic. Your choice depends on whether a feature meets
your particular needs.
For most common arithmetic evaluations, the COMPUTE statement is appropriate. If
you need to use numeric literals, numeric data, or arithmetic operators, you might
Chapter 3. Working with numbers and arithmetic 55
want to use arithmetic expressions. In places where numeric expressions are
allowed, you can save time by using numeric intrinsic functions. Language
Environment callable services for mathematical functions and for date and time
operations also provide a means of assigning arithmetic results to data items.
RELATED TASKS
Using COMPUTE and other arithmetic statements
Using arithmetic expressions on page 57
Using numeric intrinsic functions on page 57
Using math-oriented callable services on page 58
Using date callable services on page 60
Using COMPUTE and other arithmetic statements
Use the COMPUTE statement for most arithmetic evaluations rather than ADD,
SUBTRACT, MULTIPLY, and DIVIDE statements. Often you can code only one COMPUTE
statement instead of several individual arithmetic statements.
The COMPUTE statement assigns the result of an arithmetic expression to one or
more data items:
Compute z = a + b / c ** d - e
Compute x y z = a + b / c ** d - e
Some arithmetic calculations might be more intuitive using arithmetic statements
other than COMPUTE. For example:
COMPUTE Equivalent arithmetic statements
Compute Increment = Increment + 1 Add 1 to Increment
Compute Balance = Subtract Overdraft from Balance
Balance - Overdraft
Compute IncrementOne = Add 1 to IncrementOne,
IncrementOne + 1 IncrementTwo,
Compute IncrementTwo = IncrementThree
IncrementTwo + 1
Compute IncrementThree =
IncrementThree + 1
You might also prefer to use the DIVIDE statement (with its REMAINDER phrase) for
division in which you want to process a remainder. The REM intrinsic function also
provides the ability to process a remainder.
When you perform arithmetic calculations, you can use national decimal data
items as operands just as you use zoned decimal data items. You can also use
national floating-point data items as operands just as you use display
floating-point operands.
RELATED CONCEPTS
Fixed-point contrasted with floating-point arithmetic on page 62
Appendix A, Intermediate results and arithmetic precision, on page 675
RELATED TASKS
Defining numeric data on page 43
56 Enterprise COBOL for z/OS, V5.2 Programming Guide
Using arithmetic expressions
You can use arithmetic expressions in many (but not all) places in statements
where numeric data items are allowed.
For example, you can use arithmetic expressions as comparands in relation
conditions:
If (a + b) > (c - d + 5) Then. . .
Arithmetic expressions can consist of a single numeric literal, a single numeric data
item, or a single intrinsic function reference. They can also consist of several of
these items connected by arithmetic operators.
Arithmetic operators are evaluated in the following order of precedence:
Table 9. Order of evaluation of arithmetic operators
Operator Meaning Order of evaluation
Unary + or - Algebraic sign First
** Exponentiation Second
/ or * Division or multiplication Third
Binary + or - Addition or subtraction Last
Operators at the same level of precedence are evaluated from left to right;
however, you can use parentheses to change the order of evaluation. Expressions
in parentheses are evaluated before the individual operators are evaluated.
Parentheses, whether necessary or not, make your program easier to read.
RELATED CONCEPTS
Fixed-point contrasted with floating-point arithmetic on page 62
Appendix A, Intermediate results and arithmetic precision, on page 675
Using numeric intrinsic functions
You can use numeric intrinsic functions only in places where numeric expressions
are allowed. These functions can save you time because you don't have to code the
many common types of calculations that they provide.
Numeric intrinsic functions return a signed numeric value, and are treated as
temporary numeric data items.
Numeric functions are classified into the following categories:
Integer
Those that return an integer
Floating point
Those that return a long (64-bit) or extended-precision (128-bit)
floating-point value (depending on whether you compile using the default
option ARITH(COMPAT) or using ARITH(EXTEND))
Mixed
Those that return an integer, a floating-point value, or a fixed-point
number with decimal places, depending on the arguments
You can use intrinsic functions to perform several different arithmetic operations,
as outlined in the following table.
Chapter 3. Working with numbers and arithmetic 57
Table 10. Numeric intrinsic functions
Number
handling Date and time Finance Mathematics Statistics
LENGTH CURRENT-DATE ANNUITY ACOS MEAN
MAX DATE-OF-INTEGER PRESENT-VALUE ASIN MEDIAN
MIN DATE-TO-YYYYMMDD ATAN MIDRANGE
NUMVAL DAY-OF-INTEGER COS RANDOM
NUMVAL-C DAY-TO-YYYYDDD FACTORIAL RANGE
ORD-MAX INTEGER-OF-DATE INTEGER STANDARD-DEVIATION
ORD-MIN INTEGER-OF-DAY INTEGER-PART VARIANCE
WHEN-COMPILED LOG
YEAR-TO-YYYY LOG10
MOD
REM
SIN
SQRT
SUM
TAN
Examples: numeric intrinsic functions on page 60
You can reference one function as the argument of another. A nested function is
evaluated independently of the outer function (except when the compiler
determines whether a mixed function should be evaluated using fixed-point or
floating-point instructions).
You can also nest an arithmetic expression as an argument to a numeric function.
For example, in the statement below, there are three function arguments (a, b, and
the arithmetic expression (c / d)):
Compute x = Function Sum(a b (c / d))
You can reference all the elements of a table (or array) as function arguments by
using the ALL subscript.
You can also use the integer special registers as arguments wherever integer
arguments are allowed.
Many of the capabilities of numeric intrinsic functions are also provided by
Language Environment callable services.
RELATED CONCEPTS
Fixed-point contrasted with floating-point arithmetic on page 62
Appendix A, Intermediate results and arithmetic precision, on page 675
RELATED REFERENCES
ARITH on page 309
Using math-oriented callable services
Most COBOL intrinsic functions have corresponding math-oriented callable
services that you can use to produce the same results.
When you compile with the default option ARITH(COMPAT), COBOL floating-point
intrinsic functions return long (64-bit) results. When you compile with option
58 Enterprise COBOL for z/OS, V5.2 Programming Guide
ARITH(EXTEND), COBOL floating-point intrinsic functions (with the exception of
RANDOM) return extended-precision (128-bit) results.
For example (considering the first row of the table below), if you compile using
ARITH(COMPAT), CEESDACS returns the same result as ACOS. If you compile using
ARITH(EXTEND), CEESQACS returns the same result as ACOS.
Table 11. Compatibility of math intrinsic functions and callable services
Corresponding Corresponding Results same for intrinsic
COBOL intrinsic long-precision Language extended-precision Language function and callable
function Environment callable service Environment callable service service?
ACOS CEESDACS CEESQACS Yes
ASIN CEESDASN CEESQASN Yes
ATAN CEESDATN CEESQATN Yes
COS CEESDCOS CEESQCOS Yes
LOG CEESDLOG CEESQLOG Yes
LOG10 CEESDLG1 CEESQLG1 Yes
1
RANDOM CEERAN0 none No
REM CEESDMOD CEESQMOD Yes
SIN CEESDSIN CEESQSIN Yes
SQRT CEESDSQT CEESQSQT Yes
TAN CEESDTAN CEESQTAN Yes
1. RANDOM returns a long (64-bit) floating-point result even if you pass it a 31-digit argument and compile with
ARITH(EXTEND).
Both the RANDOM intrinsic function and CEERAN0 service generate random
numbers between zero and one. However, because each uses its own algorithm,
RANDOM and CEERAN0 produce different random numbers from the same seed.
Even for functions that produce the same results, how you use intrinsic functions
and Language Environment callable services differs. The rules for the data types
required for intrinsic function arguments are less restrictive. For numeric intrinsic
functions, you can use arguments that are of any numeric data type. When you
invoke a Language Environment callable service with a CALL statement, however,
you must ensure that the parameters match the numeric data types (generally
COMP-1 or COMP-2) required by that service.
The error handling of intrinsic functions and Language Environment callable
services sometimes differs. If you pass an explicit feedback token when calling the
Language Environment math services, you must check the feedback code after
each call and take explicit action to deal with errors. However, if you call with the
feedback token explicitly OMITTED, you do not need to check the token; Language
Environment automatically signals any errors.
RELATED CONCEPTS
Fixed-point contrasted with floating-point arithmetic on page 62
Appendix A, Intermediate results and arithmetic precision, on page 675
RELATED TASKS
Using Language Environment callable services on page 667
Chapter 3. Working with numbers and arithmetic 59
RELATED REFERENCES
ARITH on page 309
Using date callable services
Both the COBOL date intrinsic functions and the Language Environment date
callable services are based on the Gregorian calendar. However, the starting dates
can differ depending on the setting of the INTDATE compiler option.
When INTDATE(LILIAN) is in effect, COBOL uses October 15, 1582 as day 1.
Language Environment always uses October 15, 1582 as day 1. If you use
INTDATE(LILIAN), you get equivalent results from COBOL intrinsic functions and
Language Environment date callable services. The following table compares the
results when INTDATE(LILIAN) is in effect.
Table 12. INTDATE(LILIAN) and compatibility of date intrinsic functions and callable
services
Language Environment callable
COBOL intrinsic function service Results
DATE-OF-INTEGER CEEDATE with picture string YYYYMMDD Compatible
DAY-OF-INTEGER CEEDATE with picture string YYYYDDD Compatible
INTEGER-OF-DATE CEEDAYS Compatible
INTEGER-OF-DATE CEECBLDY Incompatible
When the default setting of INTDATE(ANSI) is in effect, COBOL uses January 1, 1601
as day 1. The following table compares the results when INTDATE(ANSI) is in effect.
Table 13. INTDATE(ANSI) and compatibility of date intrinsic functions and callable
services
Language Environment callable
COBOL intrinsic function service Results
INTEGER-OF-DATE CEECBLDY Compatible
DATE-OF-INTEGER CEEDATE with picture string YYYYMMDD Incompatible
DAY-OF-INTEGER CEEDATE with picture string YYYYDDD Incompatible
INTEGER-OF-DATE CEEDAYS Incompatible
RELATED TASKS
Using Language Environment callable services on page 667
RELATED REFERENCES
INTDATE on page 331
Examples: numeric intrinsic functions
The following examples and accompanying explanations show intrinsic functions
in each of several categories.
Where the examples below show zoned decimal data items, national decimal items
could instead be used. (Signed national decimal items, however, require that the
SIGN SEPARATE clause be in effect.)
60 Enterprise COBOL for z/OS, V5.2 Programming Guide
General number handling
Suppose you want to find the maximum value of two prices (represented below as
alphanumeric items with dollar signs), put this value into a numeric field in an
output record, and determine the length of the output record. You can use
NUMVAL-C (a function that returns the numeric value of an alphanumeric or national
literal, or an alphanumeric or national data item) and the MAX and LENGTH functions
to do so:
01 X Pic 9(2).
01 Price1 Pic x(8) Value "$8000".
01 Price2 Pic x(8) Value "$2000".
01 Output-Record.
05 Product-Name Pic x(20).
05 Product-Number Pic 9(9).
05 Product-Price Pic 9(6).
. . .
Procedure Division.
Compute Product-Price =
Function Max (Function Numval-C(Price1) Function Numval-C(Price2))
Compute X = Function Length(Output-Record)
Additionally, to ensure that the contents in Product-Name are in uppercase letters,
you can use the following statement:
Move Function Upper-case (Product-Name) to Product-Name
Date and time
The following example shows how to calculate a due date that is 90 days from
today. The first eight characters returned by the CURRENT-DATE function represent
the date in a four-digit year, two-digit month, and two-digit day format (YYYYMMDD).
The date is converted to its integer value; then 90 is added to this value and the
integer is converted back to the YYYYMMDD format.
01 YYYYMMDD Pic 9(8).
01 Integer-Form Pic S9(9).
. . .
Move Function Current-Date(1:8) to YYYYMMDD
Compute Integer-Form = Function Integer-of-Date(YYYYMMDD)
Add 90 to Integer-Form
Compute YYYYMMDD = Function Date-of-Integer(Integer-Form)
Display Due Date: YYYYMMDD
Finance
Business investment decisions frequently require computing the present value of
expected future cash inflows to evaluate the profitability of a planned investment.
The present value of an amount that you expect to receive at a given time in the
future is that amount, which, if invested today at a given interest rate, would
accumulate to that future amount.
For example, assume that a proposed investment of $1,000 produces a payment
stream of $100, $200, and $300 over the next three years, one payment per year
respectively. The following COBOL statements calculate the present value of those
cash inflows at a 10% interest rate:
01 Series-Amt1 Pic 9(9)V99 Value 100.
01 Series-Amt2 Pic 9(9)V99 Value 200.
01 Series-Amt3 Pic 9(9)V99 Value 300.
01 Discount-Rate Pic S9(2)V9(6) Value .10.
01 Todays-Value Pic 9(9)V99.
. . .
Compute Todays-Value =
Function
Present-Value(Discount-Rate Series-Amt1 Series-Amt2 Series-Amt3)
Chapter 3. Working with numbers and arithmetic 61
You can use the ANNUITY function in business problems that require you to
determine the amount of an installment payment (annuity) necessary to repay the
principal and interest of a loan. The series of payments is characterized by an
equal amount each period, periods of equal length, and an equal interest rate each
period. The following example shows how you can calculate the monthly payment
required to repay a $15,000 loan in three years at a 12% annual interest rate (36
monthly payments, interest per month = .12/12):
01 Loan Pic 9(9)V99.
01 Payment Pic 9(9)V99.
01 Interest Pic 9(9)V99.
01 Number-Periods Pic 99.
. . .
Compute Loan = 15000
Compute Interest = .12
Compute Number-Periods = 36
Compute Payment =
Loan * Function Annuity((Interest / 12) Number-Periods)
Mathematics
The following COBOL statement demonstrates that you can nest intrinsic
functions, use arithmetic expressions as arguments, and perform previously
complex calculations simply:
Compute Z = Function Log(Function Sqrt (2 * X + 1)) + Function Rem(X 2)
Here in the addend the intrinsic function REM (instead of a DIVIDE statement with a
REMAINDER clause) returns the remainder of dividing X by 2.
Statistics
Intrinsic functions make calculating statistical information easier. Assume you are
analyzing various city taxes and want to calculate the mean, median, and range
(the difference between the maximum and minimum taxes):
01 Tax-S Pic 99v999 value .045.
01 Tax-T Pic 99v999 value .02.
01 Tax-W Pic 99v999 value .035.
01 Tax-B Pic 99v999 value .03.
01 Ave-Tax Pic 99v999.
01 Median-Tax Pic 99v999.
01 Tax-Range Pic 99v999.
. . .
Compute Ave-Tax = Function Mean (Tax-S Tax-T Tax-W Tax-B)
Compute Median-Tax = Function Median (Tax-S Tax-T Tax-W Tax-B)
Compute Tax-Range = Function Range (Tax-S Tax-T Tax-W Tax-B)
RELATED TASKS
Converting to numbers (NUMVAL, NUMVAL-C) on page 117
Fixed-point contrasted with floating-point arithmetic
How you code arithmetic in a program (whether an arithmetic statement, an
intrinsic function, an expression, or some combination of these nested within each
other) determines whether the evaluation is done with floating-point or fixed-point
arithmetic.
Many statements in a program could involve arithmetic. For example, each of the
following types of COBOL statements requires some arithmetic evaluation:
v General arithmetic
compute report-matrix-col = (emp-count ** .5) + 1
add report-matrix-min to report-matrix-max giving report-matrix-tot
62 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Expressions and functions
compute report-matrix-col = function sqrt(emp-count) + 1
compute whole-hours = function integer-part((average-hours) + 1)
v Arithmetic comparisons
if report-matrix-col < function sqrt(emp-count) + 1
if whole-hours not = function integer-part((average-hours) + 1)
Floating-point evaluations
In general, if your arithmetic coding has either of the characteristics listed below, it
is evaluated in floating-point arithmetic:
v An operand or result field is floating point.
An operand is floating point if you code it as a floating-point literal or if you
code it as a data item that is defined as USAGE COMP-1, USAGE COMP-2, or external
floating point (USAGE DISPLAY or USAGE NATIONAL with a floating-point PICTURE).
An operand that is a nested arithmetic expression or a reference to a numeric
intrinsic function results in floating-point arithmetic when any of the following
conditions is true:
An argument in an arithmetic expression results in floating point.
The function is a floating-point function.
The function is a mixed function with one or more floating-point arguments.
v An exponent contains decimal places.
An exponent contains decimal places if you use a literal that contains decimal
places, give the item a PICTURE that contains decimal places, or use an arithmetic
expression or function whose result has decimal places.
An arithmetic expression or numeric function yields a result that has decimal
places if any operand or argument (excluding divisors and exponents) has decimal
places.
Fixed-point evaluations
In general, if an arithmetic operation contains neither of the characteristics listed
above for floating point, the compiler causes it to be evaluated in fixed-point
arithmetic. In other words, arithmetic evaluations are handled as fixed point only if
all the operands are fixed point, the result field is defined to be fixed point, and
none of the exponents represent values with decimal places. Nested arithmetic
expressions and function references must also represent fixed-point values.
Arithmetic comparisons (relation conditions)
When you compare numeric expressions using a relational operator, the numeric
expressions (whether they are data items, arithmetic expressions, function
references, or some combination of these) are comparands in the context of the
entire evaluation. That is, the attributes of each can influence the evaluation of the
other: both expressions are evaluated in fixed point, or both are evaluated in
floating point. This is also true of abbreviated comparisons even though one
comparand does not explicitly appear in the comparison. For example:
if (a + d) = (b + e) and c
This statement has two comparisons: (a + d) = (b + e), and (a + d) = c.
Although (a + d) does not explicitly appear in the second comparison, it is a
comparand in that comparison. Therefore, the attributes of c can influence the
evaluation of (a + d).
Chapter 3. Working with numbers and arithmetic 63
The compiler handles comparisons (and the evaluation of any arithmetic
expressions nested in comparisons) in floating-point arithmetic if either comparand
is a floating-point value or resolves to a floating-point value.
The compiler handles comparisons (and the evaluation of any arithmetic
expressions nested in comparisons) in fixed-point arithmetic if both comparands
are fixed-point values or resolve to fixed-point values.
Implicit comparisons (no relational operator used) are not handled as a unit,
however; the two comparands are treated separately as to their evaluation in
floating-point or fixed-point arithmetic. In the following example, five arithmetic
expressions are evaluated independently of one another's attributes, and then are
compared to each other.
evaluate (a + d)
when (b + e) thru c
when (f / g) thru (h * i)
. . .
end-evaluate
Examples: fixed-point and floating-point evaluations
RELATED REFERENCES
Arithmetic expressions in nonarithmetic statements on page 683
Examples: fixed-point and floating-point evaluations
The following example shows statements that are evaluated using fixed-point
arithmetic and using floating-point arithmetic.
Assume that you define the data items for an employee table in the following
manner:
01 employee-table.
05 emp-count pic 9(4).
05 employee-record occurs 1 to 1000 times
depending on emp-count.
10 hours pic +9(5)e+99.
. . .
01 report-matrix-col pic 9(3).
01 report-matrix-min pic 9(3).
01 report-matrix-max pic 9(3).
01 report-matrix-tot pic 9(3).
01 average-hours pic 9(3)v9.
01 whole-hours pic 9(4).
These statements are evaluated using floating-point arithmetic:
compute report-matrix-col = (emp-count ** .5) + 1
compute report-matrix-col = function sqrt(emp-count) + 1
if report-matrix-tot < function sqrt(emp-count) + 1
These statements are evaluated using fixed-point arithmetic:
add report-matrix-min to report-matrix-max giving report-matrix-tot
compute report-matrix-max =
function max(report-matrix-max report-matrix-tot)
if whole-hours not = function integer-part((average-hours) + 1)
64 Enterprise COBOL for z/OS, V5.2 Programming Guide
Using currency signs
Many programs need to process financial information and present that information
using the appropriate currency signs. With COBOL currency support (and the
appropriate code page for your printer or display unit), you can use several
currency signs in a program.
You can use one or more of the following signs:
v Symbols such as the dollar sign ($)
v Currency signs of more than one character (such as USD or EUR)
v Euro sign, established by the Economic and Monetary Union (EMU)
To specify the symbols for displaying financial information, use the CURRENCY SIGN
clause (in the SPECIAL-NAMES paragraph in the CONFIGURATION SECTION) with the
PICTURE characters that relate to those symbols. In the following example, the
PICTURE character $ indicates that the currency sign $US is to be used:
Currency Sign is "$US" with Picture Symbol "$".
. . .
77 Invoice-Amount Pic $$,$$9.99.
. . .
Display "Invoice amount is " Invoice-Amount.
In this example, if Invoice-Amount contained 1500.00, the display output would be:
Invoice amount is $US1,500.00
By using more than one CURRENCY SIGN clause in your program, you can allow for
multiple currency signs to be displayed.
You can use a hexadecimal literal to indicate the currency sign value. Using a
hexadecimal literal could be useful if the data-entry method for the source
program does not allow the entry of the intended characters easily. The following
example shows the hexadecimal value X9F used as the currency sign:
Currency Sign X9F with Picture Symbol U.
. . .
01 Deposit-Amount Pic UUUUU9.99.
If there is no corresponding character for the euro sign on your keyboard, you
need to specify it as a hexadecimal value in the CURRENCY SIGN clause. The
hexadecimal value for the euro sign is either X9F or X5A depending on the code
page in use, as shown in the following table.
Table 14. Hexadecimal values of the euro sign
Code page Modified
CCSID Applicable countries from Euro sign
1140 USA, Canada, Netherlands, Portugal, Australia, 037 X'9F'
New Zealand
1141 Austria, Germany 273 X'9F'
1142 Denmark, Norway 277 X'5A'
1143 Finland, Sweden 278 X'5A'
1144 Italy 280 X'9F'
1145 Spain, Latin America - Spanish 284 X'9F'
1146 UK 285 X'9F'
1147 France 297 X'9F'
Chapter 3. Working with numbers and arithmetic 65
Table 14. Hexadecimal values of the euro sign (continued)
Code page Modified
CCSID Applicable countries from Euro sign
1148 Belgium, Canada, Switzerland 500 X'9F'
1149 Iceland 871 X'9F'
RELATED REFERENCES
CURRENCY on page 317
CURRENCY SIGN clause (Enterprise COBOL Language Reference)
Example: multiple currency signs
The following example shows how you can display values in both euro currency
(as EUR) and Swiss francs (as CHF).
IDENTIFICATION DIVISION.
PROGRAM-ID. EuroSamp.
Environment Division.
Configuration Section.
Special-Names.
Currency Sign is "CHF " with Picture Symbol "F"
Currency Sign is "EUR " with Picture Symbol "U".
Data Division.
WORKING-STORAGE SECTION.
01 Deposit-in-Euro Pic S9999V99 Value 8000.00.
01 Deposit-in-CHF Pic S99999V99.
01 Deposit-Report.
02 Report-in-Franc Pic -FFFFF9.99.
02 Report-in-Euro Pic -UUUUU9.99.
01 EUR-to-CHF-Conv-Rate Pic 9V99999 Value 1.53893.
. . .
PROCEDURE DIVISION.
Report-Deposit-in-CHF-and-EUR.
Move Deposit-in-Euro to Report-in-Euro
Compute Deposit-in-CHF Rounded
= Deposit-in-Euro * EUR-to-CHF-Conv-Rate
On Size Error
Perform Conversion-Error
Not On Size Error
Move Deposit-in-CHF to Report-in-Franc
Display "Deposit in euro = " Report-in-Euro
Display "Deposit in franc = " Report-in-Franc
End-Compute
Goback.
Conversion-Error.
Display "Conversion error from EUR to CHF"
Display "Euro value: " Report-in-Euro.
The above example produces the following display output:
Deposit in euro = EUR 8000.00
Deposit in franc = CHF 12311.44
The exchange rate used in this example is for illustrative purposes only.
66 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 4. Handling tables
A table is a collection of data items that have the same description, such as account
totals or monthly averages. A table consists of a table name and subordinate items
called table elements. A table is the COBOL equivalent of an array.
In the example above, SAMPLE-TABLE-ONE is the group item that contains the table.
TABLE-COLUMN names the table element of a one-dimensional table that occurs three
times.
Rather than defining repetitious items as separate, consecutive entries in the DATA
DIVISION, you use the OCCURS clause in the DATA DIVISION entry to define a table.
This practice has these advantages:
v The code clearly shows the unity of the items (the table elements).
v You can use subscripts and indexes to refer to the table elements.
v You can easily repeat data items.
Tables are important for increasing the speed of a program, especially a program
that looks up records.
RELATED CONCEPTS
Complex OCCURS DEPENDING ON on page 81
RELATED TASKS
Defining a table (OCCURS)
Nesting tables on page 69
Referring to an item in a table on page 70
Putting values into a table on page 73
Creating variable-length tables (DEPENDING ON) on page 78
| Searching a table on page 85
| Sorting a table on page 88
Processing table items using intrinsic functions on page 89
Working with unbounded tables and groups on page 90
Handling tables efficiently on page 654
Defining a table (OCCURS)
To code a table, give the table a group name and define a subordinate item (the
table element) to be repeated n times.
01 table-name.
05 element-name OCCURS n TIMES.
. . . (subordinate items of the table element)
Copyright IBM Corp. 1991, 2015 67
In the example above, table-name is the name of an alphanumeric group item. The
table element definition (which includes the OCCURS clause) is subordinate to the
group item that contains the table. The OCCURS clause cannot be used in a level-01
description.
If a table is to contain only Unicode (UTF-16) data, and you want the group item
that contains the table to behave like an elementary category national item in most
operations, code the GROUP-USAGE NATIONAL clause for the group item:
01 table-nameN Group-Usage National.
05 element-nameN OCCURS m TIMES.
10 elementN1 Pic nn.
10 elementN2 Pic S99 Sign Is Leading, Separate.
. . .
Any elementary item that is subordinate to a national group must be explicitly or
implicitly described as USAGE NATIONAL, and any subordinate numeric data item
that is signed must be implicitly or explicitly described with the SIGN IS SEPARATE
clause.
To create tables of two to seven dimensions, use nested OCCURS clauses.
To create a variable-length table, code the DEPENDING ON phrase of the OCCURS
clause.
To specify that table elements will be arranged in ascending or descending order
based on the values in one or more key fields of the table, code the ASCENDING or
DESCENDING KEY phrases of the OCCURS clause, or both. Specify the names of the
keys in decreasing order of significance. Keys can be of class alphabetic,
alphanumeric, DBCS, national, or numeric. (If it has USAGE NATIONAL, a key can be
of category national, or can be a national-edited, numeric-edited, national decimal,
or national floating-point item.)
You must code the ASCENDING or DESCENDING KEY phrase of the OCCURS clause to do
| a binary search (SEARCH ALL) of a table. You can use a format 2 SORT statement to
| order the table according to its defined keys, thereby making the table searchable
| by the SEARCH ALL statement. Note that SEARCH ALL will return unpredictable
| results if the table has not been ordered according to the keys.
Example: binary search on page 87
RELATED CONCEPTS
National groups on page 133
RELATED TASKS
Nesting tables on page 69
Referring to an item in a table on page 70
Putting values into a table on page 73
Creating variable-length tables (DEPENDING ON) on page 78
Using national groups on page 134
Doing a binary search (SEARCH ALL) on page 87
Defining numeric data on page 43
RELATED REFERENCES
OCCURS clause (Enterprise COBOL Language Reference)
SIGN clause (Enterprise COBOL Language Reference)
ASCENDING KEY and DESCENDING KEY phrases
68 Enterprise COBOL for z/OS, V5.2 Programming Guide
(Enterprise COBOL Language Reference)
SORT statement (Enterprise COBOL Language Reference)
Nesting tables
To create a two-dimensional table, define a one-dimensional table in each
occurrence of another one-dimensional table.
For example, in SAMPLE-TABLE-TWO above, TABLE-ROW is an element of a
one-dimensional table that occurs two times. TABLE-COLUMN is an element of a
two-dimensional table that occurs three times in each occurrence of TABLE-ROW.
To create a three-dimensional table, define a one-dimensional table in each
occurrence of another one-dimensional table, which is itself contained in each
occurrence of another one-dimensional table. For example:
In SAMPLE-TABLE-THREE, TABLE-DEPTH is an element of a one-dimensional table that
occurs two times. TABLE-ROW is an element of a two-dimensional table that occurs
two times within each occurrence of TABLE-DEPTH. TABLE-COLUMN is an element of a
three-dimensional table that occurs three times within each occurrence of
TABLE-ROW.
In a two-dimensional table, the two subscripts correspond to the row and column
numbers. In a three-dimensional table, the three subscripts correspond to the
depth, row, and column numbers.
Example: subscripting on page 70
Example: indexing on page 70
RELATED TASKS
Defining a table (OCCURS) on page 67
Referring to an item in a table on page 70
Putting values into a table on page 73
Creating variable-length tables (DEPENDING ON) on page 78
Searching a table on page 85
Processing table items using intrinsic functions on page 89
Handling tables efficiently on page 654
Chapter 4. Handling tables 69
RELATED REFERENCES
OCCURS clause (Enterprise COBOL Language Reference)
Example: subscripting
The following example shows valid references to SAMPLE-TABLE-THREE that use
literal subscripts. The spaces are required in the second example.
TABLE-COLUMN (2, 2, 1)
TABLE-COLUMN (2 2 1)
In either table reference, the first value (2) refers to the second occurrence within
TABLE-DEPTH, the second value (2) refers to the second occurrence within TABLE-ROW,
and the third value (1) refers to the first occurrence within TABLE-COLUMN.
The following reference to SAMPLE-TABLE-TWO uses variable subscripts. The reference
is valid if SUB1 and SUB2 are data-names that contain positive integer values within
the range of the table.
TABLE-COLUMN (SUB1 SUB2)
RELATED TASKS
Subscripting on page 71
Example: indexing
The following example shows how displacements to elements that are referenced
with indexes are calculated.
Consider the following three-dimensional table, SAMPLE-TABLE-FOUR:
01 SAMPLE-TABLE-FOUR
05 TABLE-DEPTH OCCURS 3 TIMES INDEXED BY INX-A.
10 TABLE-ROW OCCURS 4 TIMES INDEXED BY INX-B.
15 TABLE-COLUMN OCCURS 8 TIMES INDEXED BY INX-C PIC X(8).
Suppose you code the following relative indexing reference to SAMPLE-TABLE-FOUR:
TABLE-COLUMN (INX-A + 1, INX-B + 2, INX-C - 1)
This reference causes the following computation of the displacement to the
TABLE-COLUMN element:
(contents of INX-A) + (256 * 1)
+ (contents of INX-B) + (64 * 2)
+ (contents of INX-C) - (8 * 1)
This calculation is based on the following element lengths:
v Each occurrence of TABLE-DEPTH is 256 bytes in length (4 * 8 * 8).
v Each occurrence of TABLE-ROW is 64 bytes in length (8 * 8).
v Each occurrence of TABLE-COLUMN is 8 bytes in length.
RELATED TASKS
Indexing on page 72
Referring to an item in a table
A table element has a collective name, but the individual items within it do not
have unique data-names.
To refer to an item, you have a choice of three techniques:
70 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Use the data-name of the table element, along with its occurrence number
(called a subscript) in parentheses. This technique is called subscripting.
v Use the data-name of the table element, along with a value (called an index) that
is added to the address of the table to locate an item (as a displacement from the
beginning of the table). This technique is called indexing, or subscripting using
index-names.
v Use both subscripts and indexes together.
RELATED TASKS
Subscripting
Indexing on page 72
Subscripting
The lowest possible subscript value is 1, which references the first occurrence of a
table element. In a one-dimensional table, the subscript corresponds to the row
number.
You can use a literal or a data-name as a subscript. If a data item that has a literal
subscript is of fixed length, the compiler resolves the location of the data item.
When you use a data-name as a variable subscript, you must describe the
data-name as an elementary numeric integer. The most efficient format is
COMPUTATIONAL (COMP) with a PICTURE size that is smaller than five digits. You
cannot use a subscript with a data-name that is used as a subscript. The code
generated for the application resolves the location of a variable subscript at run
time.
You can increment or decrement a literal or variable subscript by a specified
integer amount. For example:
TABLE-COLUMN (SUB1 - 1, SUB2 + 3)
You can change part of a table element rather than the whole element. To do so,
refer to the character position and length of the substring to be changed. For
example:
01 ANY-TABLE.
05 TABLE-ELEMENT PIC X(10)
OCCURS 3 TIMES VALUE "ABCDEFGHIJ".
. . .
MOVE "??" TO TABLE-ELEMENT (1) (3 : 2).
The MOVE statement in the example above moves the string '??' into table element
number 1, beginning at character position 3, for a length of 2 characters.
Example: subscripting on page 70
RELATED TASKS
Indexing on page 72
Chapter 4. Handling tables 71
Putting values into a table on page 73
Searching a table on page 85
Handling tables efficiently on page 654
Indexing
You create an index by using the INDEXED BY phrase of the OCCURS clause to
identify an index-name.
For example, INX-A in the following code is an index-name:
05 TABLE-ITEM PIC X(8)
OCCURS 10 INDEXED BY INX-A.
The compiler calculates the value contained in the index as the occurrence number
(subscript) minus 1, multiplied by the length of the table element. Therefore, for
the fifth occurrence of TABLE-ITEM, the binary value contained in INX-A is (5 - 1) * 8,
or 32.
You can use an index-name to reference another table only if both table
descriptions have the same number of table elements, and the table elements are of
the same length.
You can use the USAGE IS INDEX clause to create an index data item, and can use
an index data item with any table. For example, INX-B in the following code is an
index data item:
77 INX-B USAGE IS INDEX.
. . .
SET INX-A TO 10
SET INX-B TO INX-A.
PERFORM VARYING INX-A FROM 1 BY 1 UNTIL INX-A > INX-B
DISPLAY TABLE-ITEM (INX-A)
. . .
END-PERFORM.
The index-name INX-A is used to traverse table TABLE-ITEM above. The index data
item INX-B is used to hold the index of the last element of the table. The advantage
of this type of coding is that calculation of offsets of table elements is minimized,
and no conversion is necessary for the UNTIL condition.
You can use the SET statement to assign to an index data item the value that you
stored in an index-name, as in the statement SET INX-B TO INX-A above. For
example, when you load records into a variable-length table, you can store the
index value of the last record into a data item defined as USAGE IS INDEX. Then
you can test for the end of the table by comparing the current index value with the
index value of the last record. This technique is useful when you look through or
process a table.
You can increment or decrement an index-name by an elementary integer data
item or a nonzero integer literal, for example:
SET INX-A DOWN BY 3
The integer represents a number of occurrences. It is converted to an index value
before being added to or subtracted from the index.
Initialize the index-name by using a SET, PERFORM VARYING, or SEARCH ALL
statement. You can then use the index-name in SEARCH or relational condition
statements. To change the value, use a PERFORM, SEARCH, or SET statement.
72 Enterprise COBOL for z/OS, V5.2 Programming Guide
Because you are comparing a physical displacement, you can directly use index
data items only in SEARCH and SET statements or in comparisons with indexes or
other index data items. You cannot use index data items as subscripts or indexes.
Example: indexing on page 70
RELATED TASKS
Subscripting on page 71
Putting values into a table
Searching a table on page 85
Processing table items using intrinsic functions on page 89
Handling tables efficiently on page 654
RELATED REFERENCES
INDEXED BY phrase (Enterprise COBOL Language Reference)
INDEX phrase (Enterprise COBOL Language Reference)
SET statement (Enterprise COBOL Language Reference)
Putting values into a table
You can put values into a table by loading the table dynamically, initializing the
table with the INITIALIZE statement, or assigning values with the VALUE clause
when you define the table.
RELATED TASKS
Loading a table dynamically
Loading a variable-length table on page 80
Initializing a table (INITIALIZE)
Assigning values when you define a table (VALUE) on page 75
Assigning values to a variable-length table on page 81
Loading a table dynamically
If the initial values of a table are different with each execution of your program,
you can define the table without initial values. You can instead read the changed
values into the table dynamically before the program refers to the table.
To load a table, use the PERFORM statement and either subscripting or indexing.
When reading data to load your table, test to make sure that the data does not
exceed the space allocated for the table. Use a named value (rather than a literal)
for the maximum item count. Then, if you make the table bigger, you need to
change only one value instead of all references to a literal.
Example: PERFORM and subscripting on page 76
Example: PERFORM and indexing on page 77
RELATED REFERENCES
PERFORM statement (Enterprise COBOL Language Reference)
Initializing a table (INITIALIZE)
You can load a table by coding one or more INITIALIZE statements.
For example, to move the value 3 into each of the elementary numeric data items
in a table called TABLE-ONE, shown below, you can code the following statement:
INITIALIZE TABLE-ONE REPLACING NUMERIC DATA BY 3.
Chapter 4. Handling tables 73
To move the character 'X' into each of the elementary alphanumeric data items in
TABLE-ONE, you can code the following statement:
INITIALIZE TABLE-ONE REPLACING ALPHANUMERIC DATA BY "X".
When you use the INITIALIZE statement to initialize a table, the table is processed
as a group item (that is, with group semantics); elementary data items within the
group are recognized and processed. For example, suppose that TABLE-ONE is an
alphanumeric group that is defined like this:
01 TABLE-ONE.
02 Trans-out Occurs 20.
05 Trans-code Pic X Value "R".
05 Part-number Pic XX Value "13".
05 Trans-quan Pic 99 Value 10.
05 Price-fields.
10 Unit-price Pic 99V Value 50.
10 Discount Pic 99V Value 25.
10 Sales-Price Pic 999 Value 375.
. . .
Initialize TABLE-ONE Replacing Numeric Data By 3
Alphanumeric Data By "X"
The table below shows the content that each of the twenty 12-byte elements
Trans-out(n) has before execution and after execution of the INITIALIZE statement
shown above:
Trans-out(n) before Trans-out(n) after
R13105025375 XXb0303030031
1. The symbol b represents a blank space.
You can similarly use an INITIALIZE statement to load a table that is defined as a
national group. For example, if TABLE-ONE shown above specified the GROUP-USAGE
NATIONAL clause, and Trans-code and Part-number had N instead of X in their
PICTURE clauses, the following statement would have the same effect as the
INITIALIZE statement above, except that the data in TABLE-ONE would instead be
encoded in UTF-16:
Initialize TABLE-ONE Replacing Numeric Data By 3
National Data By N"X"
The REPLACING NUMERIC phrase initializes floating-point data items also.
You can use the REPLACING phrase of the INITIALIZE statement similarly to
initialize all of the elementary ALPHABETIC, DBCS, ALPHANUMERIC-EDITED,
NATIONAL-EDITED, and NUMERIC-EDITED data items in a table.
The INITIALIZE statement cannot assign values to a variable-length table (that is, a
table that was defined using the OCCURS DEPENDING ON clause).
Examples: initializing data items on page 28
RELATED TASKS
Initializing a structure (INITIALIZE) on page 30
Assigning values when you define a table (VALUE) on page 75
Assigning values to a variable-length table on page 81
Looping through a table on page 103
Using data items and group items on page 24
Using national groups on page 134
74 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
INITIALIZE statement (Enterprise COBOL Language Reference)
Assigning values when you define a table (VALUE)
If a table is to contain stable values (such as days and months), you can set the
specific values when you define the table.
Set static values in tables in one of these ways:
v Initialize each table item individually.
v Initialize an entire table at the group level.
v Initialize all occurrences of a given table element to the same value.
RELATED TASKS
Initializing each table item individually
Initializing a table at the group level on page 76
Initializing all occurrences of a given table element on page 76
Initializing a structure (INITIALIZE) on page 30
Initializing each table item individually
If a table is small, you can set the value of each item individually by using a VALUE
clause.
Use the following technique, which is shown in the example code below:
| 1. Define a record (such as Error-Flag-Table below) that contains the items that
are to be in the table.
2. Set the initial value of each item in a VALUE clause.
3. Code a REDEFINES entry to make the record into a table.
***********************************************************
*** E R R O R F L A G T A B L E ***
***********************************************************
01 Error-Flag-Table Value Spaces.
88 No-Errors Value Spaces.
05 Type-Error Pic X.
05 Shift-Error Pic X.
05 Home-Code-Error Pic X.
05 Work-Code-Error Pic X.
05 Name-Error Pic X.
05 Initials-Error Pic X.
05 Duplicate-Error Pic X.
05 Not-Found-Error Pic X.
01 Filler Redefines Error-Flag-Table.
05 Error-Flag Occurs 8 Times
Indexed By Flag-Index Pic X.
In the example above, the VALUE clause at the 01 level initializes each of the table
items to the same value. Each table item could instead be described with its own
VALUE clause to initialize that item to a distinct value.
To initialize larger tables, use MOVE, PERFORM, or INITIALIZE statements.
RELATED TASKS
Initializing a structure (INITIALIZE) on page 30
Assigning values to a variable-length table on page 81
Chapter 4. Handling tables 75
RELATED REFERENCES
REDEFINES clause (Enterprise COBOL Language Reference)
OCCURS clause (Enterprise COBOL Language Reference)
Initializing a table at the group level
Code an alphanumeric or national group data item and assign to it, through the
VALUE clause, the contents of the whole table. Then, in a subordinate data item, use
an OCCURS clause to define the individual table items.
In the following example, the alphanumeric group data item TABLE-ONE uses a
VALUE clause that initializes each of the four elements of TABLE-TWO:
01 TABLE-ONE VALUE "1234".
05 TABLE-TWO OCCURS 4 TIMES PIC X.
In the following example, the national group data item Table-OneN uses a VALUE
clause that initializes each of the three elements of the subordinate data item
Table-TwoN (each of which is implicitly USAGE NATIONAL). Note that you can
initialize a national group data item with a VALUE clause that uses an alphanumeric
literal, as shown below, or a national literal.
01 Table-OneN Group-Usage National Value "AB12CD34EF56".
05 Table-TwoN Occurs 3 Times Indexed By MyI.
10 ElementOneN Pic nn.
10 ElementTwoN Pic 99.
After Table-OneN is initialized, ElementOneN(1) contains NX"00410042" (the UTF-16
representation of 'AB'), the national decimal item ElementTwoN(1) contains
NX"00310032" (the UTF-16 representation of '12'), and so forth.
RELATED REFERENCES
OCCURS clause (Enterprise COBOL Language Reference)
GROUP-USAGE clause (Enterprise COBOL Language Reference)
Initializing all occurrences of a given table element
You can use the VALUE clause in the data description of a table element to initialize
all instances of that element to the specified value.
01 T2.
05 T-OBJ PIC 9 VALUE 3.
05 T OCCURS 5 TIMES
DEPENDING ON T-OBJ.
10 X PIC XX VALUE "AA".
10 Y PIC 99 VALUE 19.
10 Z PIC XX VALUE "BB".
For example, the code above causes all the X elements (1 through 5) to be
initialized to AA, all the Y elements (1 through 5) to be initialized to 19, and all the
Z elements (1 through 5) to be initialized to BB. T-OBJ is then set to 3.
RELATED TASKS
Assigning values to a variable-length table on page 81
RELATED REFERENCES
OCCURS clause (Enterprise COBOL Language Reference)
Example: PERFORM and subscripting
This example traverses an error-flag table using subscripting until an error code
that has been set is found. If an error code is found, the corresponding error
message is moved to a print report field.
76 Enterprise COBOL for z/OS, V5.2 Programming Guide
***********************************************************
*** E R R O R F L A G T A B L E ***
***********************************************************
01 Error-Flag-Table Value Spaces.
88 No-Errors Value Spaces.
05 Type-Error Pic X.
05 Shift-Error Pic X.
05 Home-Code-Error Pic X.
05 Work-Code-Error Pic X.
05 Name-Error Pic X.
05 Initials-Error Pic X.
05 Duplicate-Error Pic X.
05 Not-Found-Error Pic X.
01 Filler Redefines Error-Flag-Table.
05 Error-Flag Occurs 8 Times
Indexed By Flag-Index Pic X.
77 Error-on Pic X Value "E".
***********************************************************
*** E R R O R M E S S A G E T A B L E ***
***********************************************************
01 Error-Message-Table.
05 Filler Pic X(25) Value
"Transaction Type Invalid".
05 Filler Pic X(25) Value
"Shift Code Invalid".
05 Filler Pic X(25) Value
"Home Location Code Inval.".
05 Filler Pic X(25) Value
"Work Location Code Inval.".
05 Filler Pic X(25) Value
"Last Name - Blanks".
05 Filler Pic X(25) Value
"Initials - Blanks".
05 Filler Pic X(25) Value
"Duplicate Record Found".
05 Filler Pic X(25) Value
"Commuter Record Not Found".
01 Filler Redefines Error-Message-Table.
05 Error-Message Occurs 8 Times
Indexed By Message-Index Pic X(25).
. . .
PROCEDURE DIVISION.
. . .
Perform
Varying Sub From 1 By 1
Until No-Errors
If Error-Flag (Sub) = Error-On
Move Space To Error-Flag (Sub)
Move Error-Message (Sub) To Print-Message
Perform 260-Print-Report
End-If
End-Perform
. . .
Example: PERFORM and indexing
This example traverses an error-flag table using indexing until an error code that
has been set is found. If an error code is found, the corresponding error message is
moved to a print report field.
***********************************************************
*** E R R O R F L A G T A B L E ***
***********************************************************
01 Error-Flag-Table Value Spaces.
88 No-Errors Value Spaces.
05 Type-Error Pic X.
05 Shift-Error Pic X.
Chapter 4. Handling tables 77
05 Home-Code-Error Pic X.
05 Work-Code-Error Pic X.
05 Name-Error Pic X.
05 Initials-Error Pic X.
05 Duplicate-Error Pic X.
05 Not-Found-Error Pic X.
01 Filler Redefines Error-Flag-Table.
05 Error-Flag Occurs 8 Times
Indexed By Flag-Index Pic X.
77 Error-on Pic X Value "E".
***********************************************************
*** E R R O R M E S S A G E T A B L E ***
***********************************************************
01 Error-Message-Table.
05 Filler Pic X(25) Value
"Transaction Type Invalid".
05 Filler Pic X(25) Value
"Shift Code Invalid".
05 Filler Pic X(25) Value
"Home Location Code Inval.".
05 Filler Pic X(25) Value
"Work Location Code Inval.".
05 Filler Pic X(25) Value
"Last Name - Blanks".
05 Filler Pic X(25) Value
"Initials - Blanks".
05 Filler Pic X(25) Value
"Duplicate Record Found".
05 Filler Pic X(25) Value
"Commuter Record Not Found".
01 Filler Redefines Error-Message-Table.
05 Error-Message Occurs 8 Times
Indexed By Message-Index Pic X(25).
. . .
PROCEDURE DIVISION.
. . .
Set Flag-Index To 1
Perform Until No-Errors
Search Error-Flag
When Error-Flag (Flag-Index) = Error-On
Move Space To Error-Flag (Flag-Index)
Set Message-Index To Flag-Index
Move Error-Message (Message-Index) To
Print-Message
Perform 260-Print-Report
End-Search
End-Perform
. . .
Creating variable-length tables (DEPENDING ON)
If you do not know before run time how many times a table element occurs, define
a variable-length table. To do so, use the OCCURS DEPENDING ON (ODO) clause.
X OCCURS 1 TO 10 TIMES DEPENDING ON Y
In the example above, X is called the ODO subject, and Y is called the ODO object.
You can also specify unbounded tables and groups, see Variable-length tables in
the Enterprise COBOL Language Reference for details.
Two factors affect the successful manipulation of variable-length records:
v Correct calculation of record lengths
78 Enterprise COBOL for z/OS, V5.2 Programming Guide
The length of the variable portions of a group item is the product of the object
of the DEPENDING ON phrase and the length of the subject of the OCCURS clause.
v Conformance of the data in the object of the OCCURS DEPENDING ON clause to its
PICTURE clause
If the content of the ODO object does not match its PICTURE clause, the program
could terminate abnormally. You must ensure that the ODO object correctly
specifies the current number of occurrences of table elements.
The following example shows a group item (REC-1) that contains both the subject
and object of the OCCURS DEPENDING ON clause. The way the length of the group
item is determined depends on whether it is sending or receiving data.
WORKING-STORAGE SECTION.
01 MAIN-AREA.
03 REC-1.
05 FIELD-1 PIC 9.
05 FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-1 PIC X(05).
01 REC-2.
03 REC-2-DATA PIC X(50).
If you want to move REC-1 (the sending item in this case) to REC-2, the length of
REC-1 is determined immediately before the move, using the current value in
FIELD-1. If the content of FIELD-1 conforms to its PICTURE clause (that is, if FIELD-1
contains a zoned decimal item), the move can proceed based on the actual length
of REC-1. Otherwise, the result is unpredictable. You must ensure that the ODO
object has the correct value before you initiate the move.
When you do a move to REC-1 (the receiving item in this case), the length of REC-1
is determined using the maximum number of occurrences. In this example, five
occurrences of FIELD-2, plus FIELD-1, yields a length of 26 bytes. In this case, you
do not need to set the ODO object (FIELD-1) before referencing REC-1 as a receiving
item. However, the sending field's ODO object (not shown) must be set to a valid
numeric value between 1 and 5 for the ODO object of the receiving field to be
validly set by the move.
However, if you do a move to REC-1 (again the receiving item) where REC-1 is
followed by a variably located group (a type of complex ODO), the actual length of
REC-1 is calculated immediately before the move, using the current value of the
ODO object (FIELD-1). In the following example, REC-1 and REC-2 are in the same
record, but REC-2 is not subordinate to REC-1 and is therefore variably located:
01 MAIN-AREA
03 REC-1.
05 FIELD-1 PIC 9.
05 FIELD-3 PIC 9.
05 FIELD-2 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-1 PIC X(05).
03 REC-2.
05 FIELD-4 OCCURS 1 TO 5 TIMES
DEPENDING ON FIELD-3 PIC X(05).
The compiler issues a message that lets you know that the actual length was used.
This case requires that you set the value of the ODO object before using the group
item as a receiving field.
The following example shows how to define a variable-length table when the ODO
object (LOCATION-TABLE-LENGTH below) is outside the group:
Chapter 4. Handling tables 79
DATA DIVISION.
FILE SECTION.
FD LOCATION-FILE
RECORDING MODE F
BLOCK 0 RECORDS
RECORD 80 CHARACTERS
LABEL RECORD STANDARD.
01 LOCATION-RECORD.
05 LOC-CODE PIC XX.
05 LOC-DESCRIPTION PIC X(20).
05 FILLER PIC X(58).
WORKING-STORAGE SECTION.
01 FLAGS.
05 LOCATION-EOF-FLAG PIC X(5) VALUE SPACE.
88 LOCATION-EOF VALUE "FALSE".
01 MISC-VALUES.
05 LOCATION-TABLE-LENGTH PIC 9(3) VALUE ZERO.
05 LOCATION-TABLE-MAX PIC 9(3) VALUE 100.
*****************************************************************
*** L O C A T I O N T A B L E ***
*** FILE CONTAINS LOCATION CODES. ***
*****************************************************************
01 LOCATION-TABLE.
05 LOCATION-CODE OCCURS 1 TO 100 TIMES
DEPENDING ON LOCATION-TABLE-LENGTH PIC X(80).
RELATED CONCEPTS
Complex OCCURS DEPENDING ON on page 81
RELATED TASKS
Assigning values to a variable-length table on page 81
Loading a variable-length table
Preventing overlay when adding elements to a variable table on page 84
Finding the length of data items on page 122
RELATED REFERENCES
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Variable-length tables (Enterprise COBOL Language Reference)
Loading a variable-length table
You can use a do-until structure (a TEST AFTER loop) to control the loading of a
variable-length table. For example, after the following code runs,
LOCATION-TABLE-LENGTH contains the subscript of the last item in the table.
DATA DIVISION.
FILE SECTION.
FD LOCATION-FILE
RECORDING MODE F
BLOCK 0 RECORDS
RECORD 80 CHARACTERS
LABEL RECORD STANDARD.
01 LOCATION-RECORD.
05 LOC-CODE PIC XX.
05 LOC-DESCRIPTION PIC X(20).
05 FILLER PIC X(58).
. . .
WORKING-STORAGE SECTION.
01 FLAGS.
05 LOCATION-EOF-FLAG PIC X(5) VALUE SPACE.
88 LOCATION-EOF VALUE "YES".
01 MISC-VALUES.
05 LOCATION-TABLE-LENGTH PIC 9(3) VALUE ZERO.
05 LOCATION-TABLE-MAX PIC 9(3) VALUE 100.
*****************************************************************
80 Enterprise COBOL for z/OS, V5.2 Programming Guide
*** L O C A T I O N T A B L E ***
*** FILE CONTAINS LOCATION CODES. ***
*****************************************************************
01 LOCATION-TABLE.
05 LOCATION-CODE OCCURS 1 TO 100 TIMES
DEPENDING ON LOCATION-TABLE-LENGTH PIC X(80).
. . .
PROCEDURE DIVISION.
. . .
Perform Test After
Varying Location-Table-Length From 1 By 1
Until Location-EOF
Or Location-Table-Length = Location-Table-Max
Move Location-Record To
Location-Code (Location-Table-Length)
Read Location-File
At End Set Location-EOF To True
End-Read
End-Perform
Assigning values to a variable-length table
You can code a VALUE clause for an alphanumeric or national group item that has a
subordinate data item that contains the OCCURS clause with the DEPENDING ON
phrase. Each subordinate structure that contains the DEPENDING ON phrase is
initialized using the maximum number of occurrences.
If you define the entire table by using the DEPENDING ON phrase, all the elements
are initialized using the maximum defined value of the ODO (OCCURS DEPENDING
ON) object.
If the ODO object is initialized by a VALUE clause, it is logically initialized after the
ODO subject has been initialized.
01 TABLE-THREE VALUE "3ABCDE".
05 X PIC 9.
05 Y OCCURS 5 TIMES
DEPENDING ON X PIC X.
For example, in the code above, the ODO subject Y(1) is initialized to 'A', Y(2) to
'B', . . ., Y(5) to 'E', and finally the ODO object X is initialized to 3. Any subsequent
reference to TABLE-THREE (such as in a DISPLAY statement) refers to X and the first
three elements, Y(1) through Y(3), of the table.
RELATED TASKS
Assigning values when you define a table (VALUE) on page 75
RELATED REFERENCES
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Complex OCCURS DEPENDING ON
Several types of complex OCCURS DEPENDING ON (complex ODO) are possible.
| Complex ODO is supported as an extension to the 85 COBOL Standard.
The basic forms of complex ODO permitted by the compiler are as follows:
v Variably located item or group: A data item described by an OCCURS clause with
the DEPENDING ON phrase is followed by a nonsubordinate elementary or group
data item.
Chapter 4. Handling tables 81
v Variably located table: A data item described by an OCCURS clause with the
DEPENDING ON phrase is followed by a nonsubordinate data item described by an
OCCURS clause.
v Table that has variable-length elements: A data item described by an OCCURS
clause contains a subordinate data item described by an OCCURS clause with the
DEPENDING ON phrase.
v Index name for a table that has variable-length elements.
v Element of a table that has variable-length elements.
Example: complex ODO
RELATED TASKS
Preventing index errors when changing ODO object value on page 83
Preventing overlay when adding elements to a variable table on page 84
RELATED REFERENCES
Effects of change in ODO object value on page 83
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Example: complex ODO
The following example illustrates the possible types of occurrence of complex
ODO.
01 FIELD-A.
02 COUNTER-1 PIC S99.
02 COUNTER-2 PIC S99.
02 TABLE-1.
03 RECORD-1 OCCURS 1 TO 5 TIMES
DEPENDING ON COUNTER-1 PIC X(3).
02 EMPLOYEE-NUMBER PIC X(5). (1)
02 TABLE-2 OCCURS 5 TIMES (2)(3)
INDEXED BY INDX. (4)
03 TABLE-ITEM PIC 99. (5)
03 RECORD-2 OCCURS 1 TO 3 TIMES
DEPENDING ON COUNTER-2.
04 DATA-NUM PIC S99.
Definition: In the example, COUNTER-1 is an ODO object, that is, it is the object of
the DEPENDING ON clause of RECORD-1. RECORD-1 is said to be an ODO subject.
Similarly, COUNTER-2 is the ODO object of the corresponding ODO subject,
RECORD-2.
The types of complex ODO occurrences shown in the example above are as
follows:
(1) A variably located item: EMPLOYEE-NUMBER is a data item that follows, but is
not subordinate to, a variable-length table in the same level-01 record.
(2) A variably located table: TABLE-2 is a table that follows, but is not
subordinate to, a variable-length table in the same level-01 record.
(3) A table with variable-length elements: TABLE-2 is a table that contains a
subordinate data item, RECORD-2, whose number of occurrences varies
depending on the content of its ODO object.
(4) An index-name, INDX, for a table that has variable-length elements.
(5) An element, TABLE-ITEM, of a table that has variable-length elements.
82 Enterprise COBOL for z/OS, V5.2 Programming Guide
How length is calculated
The length of the variable portion of each record is the product of its ODO object
and the length of its ODO subject. For example, whenever a reference is made to
one of the complex ODO items shown above, the actual length, if used, is
computed as follows:
v The length of TABLE-1 is calculated by multiplying the contents of COUNTER-1 (the
number of occurrences of RECORD-1) by 3 (the length of RECORD-1).
v The length of TABLE-2 is calculated by multiplying the contents of COUNTER-2 (the
number of occurrences of RECORD-2) by 2 (the length of RECORD-2), and adding
the length of TABLE-ITEM.
v The length of FIELD-A is calculated by adding the lengths of COUNTER-1,
COUNTER-2, TABLE-1, EMPLOYEE-NUMBER, and TABLE-2 times 5.
Setting values of ODO objects
You must set every ODO object in a group item before you reference any complex
ODO item in the group. For example, before you refer to EMPLOYEE-NUMBER in the
code above, you must set COUNTER-1 and COUNTER-2 even though EMPLOYEE-NUMBER
does not directly depend on either ODO object for its value.
Restriction: An ODO object cannot be variably located.
Effects of change in ODO object value
If a data item that is described by an OCCURS clause with the DEPENDING ON phrase
is followed in the same group by one or more nonsubordinate data items (a form
of complex ODO), any change in value of the ODO object affects subsequent
references to complex ODO items in the record.
For example:
v The size of any group that contains the relevant ODO clause reflects the new
value of the ODO object.
v A MOVE to a group that contains the ODO subject is made based on the new
value of the ODO object.
v The location of any nonsubordinate items that follow the item described with
the ODO clause is affected by the new value of the ODO object. (To preserve the
contents of the nonsubordinate items, move them to a work area before the
value of the ODO object changes, then move them back.)
The value of an ODO object can change when you move data to the ODO object or
to the group in which it is contained. The value can also change if the ODO object
is contained in a record that is the target of a READ statement.
RELATED TASKS
Preventing index errors when changing ODO object value
Preventing overlay when adding elements to a variable table on page 84
Preventing index errors when changing ODO object value
Be careful if you reference a complex-ODO index-name, that is, an index-name for
a table that has variable-length elements, after having changed the value of the
ODO object for a subordinate data item in the table.
When you change the value of an ODO object, the byte offset in an associated
complex-ODO index is no longer valid because the table length has changed.
Unless you take precautions, you will have unexpected results if you then code a
reference to the index-name such as:
Chapter 4. Handling tables 83
v A reference to an element of the table
v A SET statement of the form SET integer-data-item TO index-name (format 1)
v A SET statement of the form SET index-name UP|DOWN BY integer (format 2)
To avoid this type of error, do these steps:
1. Save the index in an integer data item. (Doing so causes an implicit conversion:
the integer item receives the table element occurrence number that corresponds
to the offset in the index.)
2. Change the value of the ODO object.
3. Immediately restore the index from the integer data item. (Doing so causes an
implicit conversion: the index-name receives the offset that corresponds to the
table element occurrence number in the integer item. The offset is computed
according to the table length then in effect.)
The following code shows how to save and restore the index-name (shown in
Example: complex ODO on page 82) when the ODO object COUNTER-2 changes.
77 INTEGER-DATA-ITEM-1 PIC 99.
. . .
SET INDX TO 5.
* INDX is valid at this point.
SET INTEGER-DATA-ITEM-1 TO INDX.
* INTEGER-DATA-ITEM-1 now has the
* occurrence number that corresponds to INDX.
MOVE NEW-VALUE TO COUNTER-2.
* INDX is not valid at this point.
SET INDX TO INTEGER-DATA-ITEM-1.
* INDX is now valid, containing the offset
* that corresponds to INTEGER-DATA-ITEM-1, and
* can be used with the expected results.
RELATED REFERENCES
SET statement (Enterprise COBOL Language Reference)
Preventing overlay when adding elements to a variable table
Be careful if you increase the number of elements in a variable-occurrence table
that is followed by one or more nonsubordinate data items in the same group.
When you increment the value of the ODO object and add an element to a table,
you can inadvertently overlay the variably located data items that follow the table.
To avoid this type of error, do these steps:
1. Save the variably located data items that follow the table in another data area.
2. Increment the value of the ODO object.
3. Move data into the new table element (if needed).
4. Restore the variably located data items from the data area where you saved
them.
In the following example, suppose you want to add an element to the table
VARY-FIELD-1, whose number of elements depends on the ODO object CONTROL-1.
VARY-FIELD-1 is followed by the nonsubordinate variably located data item
GROUP-ITEM-1, whose elements could potentially be overlaid.
WORKING-STORAGE SECTION.
01 VARIABLE-REC.
05 FIELD-1 PIC X(10).
05 CONTROL-1 PIC S99.
05 CONTROL-2 PIC S99.
05 VARY-FIELD-1 OCCURS 1 TO 10 TIMES
84 Enterprise COBOL for z/OS, V5.2 Programming Guide
DEPENDING ON CONTROL-1 PIC X(5).
05 GROUP-ITEM-1.
10 VARY-FIELD-2
OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-2 PIC X(9).
01 STORE-VARY-FIELD-2.
05 GROUP-ITEM-2.
10 VARY-FLD-2
OCCURS 1 TO 10 TIMES
DEPENDING ON CONTROL-2 PIC X(9).
Each element of VARY-FIELD-1 has 5 bytes, and each element of VARY-FIELD-2 has 9
bytes. If CONTROL-1 and CONTROL-2 both contain the value 3, you can picture storage
for VARY-FIELD-1 and VARY-FIELD-2 as follows:
VARY-FIELD-1(1)
VARY-FIELD-1(2)
VARY-FIELD-1(3)
VARY-FIELD-2(1)
VARY-FIELD-2(2)
VARY-FIELD-2(3)
To add a fourth element to VARY-FIELD-1, code as follows to prevent overlaying the
first 5 bytes of VARY-FIELD-2. (GROUP-ITEM-2 serves as temporary storage for the
variably located GROUP-ITEM-1.)
MOVE GROUP-ITEM-1 TO GROUP-ITEM-2.
ADD 1 TO CONTROL-1.
MOVE five-byte-field TO
VARY-FIELD-1 (CONTROL-1).
MOVE GROUP-ITEM-2 TO GROUP-ITEM-1.
You can picture the updated storage for VARY-FIELD-1 and VARY-FIELD-2 as follows:
VARY-FIELD-1(1)
VARY-FIELD-1(2)
VARY-FIELD-1(3)
VARY-FIELD-1(4)
VARY-FIELD-2(1)
VARY-FIELD-2(2)
VARY-FIELD-2(3)
Note that the fourth element of VARY-FIELD-1 did not overlay the first element of
VARY-FIELD-2.
Searching a table
COBOL provides two search techniques for tables: serial and binary.
To do serial searches, use SEARCH and indexing. For variable-length tables, you can
use PERFORM with subscripting or indexing.
To do binary searches, use SEARCH ALL and indexing.
A binary search can be considerably more efficient than a serial search. For a serial
search, the number of comparisons is of the order of n, the number of entries in
Chapter 4. Handling tables 85
the table. For a binary search, the number of comparisons is of the order of only
the logarithm (base 2) of n. A binary search, however, requires that the table items
already be sorted.
RELATED TASKS
Doing a serial search (SEARCH)
Doing a binary search (SEARCH ALL) on page 87
Doing a serial search (SEARCH)
Use the SEARCH statement to do a serial (sequential) search beginning at the current
index setting. To modify the index setting, use the SET statement.
The conditions in the WHEN phrase are evaluated in the order in which they appear:
v If none of the conditions is satisfied, the index is increased to correspond to the
next table element, and the WHEN conditions are evaluated again.
v If one of the WHEN conditions is satisfied, the search ends. The index remains
pointing to the table element that satisfied the condition.
v If the entire table has been searched and no conditions were met, the AT END
imperative statement is executed if there is one. If you did not code AT END,
control passes to the next statement in the program.
You can reference only one level of a table (a table element) with each SEARCH
statement. To search multiple levels of a table, use nested SEARCH statements.
Delimit each nested SEARCH statement with END-SEARCH.
Performance: If the found condition comes after some intermediate point in the
table, you can speed up the search by using the SET statement to set the index to
begin the search after that point. Arranging the table so that the data used most
often is at the beginning of the table also enables more efficient serial searching. If
the table is large and is presorted, a binary search is more efficient.
Example: serial search
RELATED REFERENCES
SEARCH statement (Enterprise COBOL Language Reference)
Example: serial search
The following example shows how you might find a particular string in the
innermost table of a three-dimensional table.
Each dimension of the table has its own index (set to 1, 4, and 1, respectively). The
innermost table (TABLE-ENTRY3) has an ascending key.
01 TABLE-ONE.
05 TABLE-ENTRY1 OCCURS 10 TIMES
INDEXED BY TE1-INDEX.
10 TABLE-ENTRY2 OCCURS 10 TIMES
INDEXED BY TE2-INDEX.
15 TABLE-ENTRY3 OCCURS 5 TIMES
ASCENDING KEY IS KEY1
INDEXED BY TE3-INDEX.
20 KEY1 PIC X(5).
20 KEY2 PIC X(10).
. . .
PROCEDURE DIVISION.
. . .
SET TE1-INDEX TO 1
SET TE2-INDEX TO 4
86 Enterprise COBOL for z/OS, V5.2 Programming Guide
SET TE3-INDEX TO 1
MOVE "A1234" TO KEY1 (TE1-INDEX, TE2-INDEX, TE3-INDEX + 2)
MOVE "AAAAAAAA00" TO KEY2 (TE1-INDEX, TE2-INDEX, TE3-INDEX + 2)
. . .
SEARCH TABLE-ENTRY3
AT END
MOVE 4 TO RETURN-CODE
WHEN TABLE-ENTRY3(TE1-INDEX, TE2-INDEX, TE3-INDEX)
= "A1234AAAAAAAA00"
MOVE 0 TO RETURN-CODE
END-SEARCH
Values after execution:
TE1-INDEX = 1
TE2-INDEX = 4
TE3-INDEX points to the TABLE-ENTRY3 item
that equals "A1234AAAAAAAA00"
RETURN-CODE = 0
Doing a binary search (SEARCH ALL)
If you use SEARCH ALL to do a binary search, you do not need to set the index
before you begin. The index is always the one that is associated with the first
index-name in the OCCURS clause. The index varies during execution to maximize
the search efficiency.
To use the SEARCH ALL statement to search a table, the table must specify the
ASCENDING or DESCENDING KEY phrases of the OCCURS clause, or both, and must
already be ordered on the key or keys that are specified in the ASCENDING and
| DESCENDING KEY phrases. You can use a format 2 SORT statement to order the table
| according to its defined keys, thereby making the table searchable by the SEARCH
| ALL statement. Note that SEARCH ALL will return unpredictable results if the table
| has not been ordered according to the keys.
In the WHEN phrase of the SEARCH ALL statement, you can test any key that is named
in the ASCENDING or DESCENDING KEY phrases for the table, but you must test all
preceding keys, if any. The test must be an equal-to condition, and the WHEN phrase
must specify either a key (subscripted by the first index-name associated with the
table) or a condition-name that is associated with the key. The WHEN condition can
be a compound condition that is formed from simple conditions that use AND as the
only logical connective.
Each key and its object of comparison must be compatible according to the rules
for comparison of data items. Note though that if a key is compared to a national
literal or identifier, the key must be a national data item.
Example: binary search
RELATED TASKS
Defining a table (OCCURS) on page 67
RELATED REFERENCES
SEARCH statement (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
Example: binary search
The following example shows how you can code a binary search of a table.
Chapter 4. Handling tables 87
Suppose you define a table that contains 90 elements of 40 bytes each, and three
keys. The primary and secondary keys (KEY-1 and KEY-2) are in ascending order,
but the least significant key (KEY-3) is in descending order:
01 TABLE-A.
05 TABLE-ENTRY OCCURS 90 TIMES
ASCENDING KEY-1, KEY-2
DESCENDING KEY-3
INDEXED BY INDX-1.
10 PART-1 PIC 99.
10 KEY-1 PIC 9(5).
10 PART-2 PIC 9(6).
10 KEY-2 PIC 9(4).
10 PART-3 PIC 9(18).
10 KEY-3 PIC 9(5).
You can search this table by using the following statements:
SEARCH ALL TABLE-ENTRY
AT END
PERFORM NOENTRY
WHEN KEY-1 (INDX-1) = VALUE-1 AND
KEY-2 (INDX-1) = VALUE-2 AND
KEY-3 (INDX-1) = VALUE-3
MOVE PART-1 (INDX-1) TO OUTPUT-AREA
END-SEARCH
If an entry is found in which each of the three keys is equal to the value to which
it is compared (VALUE-1, VALUE-2, and VALUE-3, respectively), PART-1 of that entry is
moved to OUTPUT-AREA. If no matching key is found in the entries in TABLE-A, the
NOENTRY routine is performed.
| Sorting a table
| You can sort a table by using the format 2 SORT statement. It is part of the 2002
| COBOL Standard.
| The format 2 SORT statement sorts table elements according to the specified table
| keys, and it is especially useful for tables used with SEARCH ALL. You can specify
| the keys for sorting as part of the table definition, which can also be used in the
| SEARCH ALL statement. Alternatively, you can also specify the keys for sorting as
| part of the SORT statement, either if you want to sort the table using different keys
| than those specified in the table definition, or if the table has no keys specified.
| With the format 2 SORT statement, you don't need to use the input and output
| procedures as you do with the format 1 SORT statement.
| See the following example in which the table is sorted based on specified keys:
| WORKING-STORAGE SECTION.
| 01 GROUP-ITEM.
| 05 TABL OCCURS 10 TIMES
| 10 ELEM-ITEM1 PIC X.
| 10 ELEM-ITEM2 PIC X.
| 10 ELEM-ITEM3 PIC X.
| ...
| PROCEDURE DIVISION.
| ...
| SORT TABL DESCENDING ELEM-ITEM2 ELEM-ITEM3.
| IF TABL (1)...
88 Enterprise COBOL for z/OS, V5.2 Programming Guide
| RELATED REFERENCES
| SORT statement (Enterprise COBOL Language Reference)
| Using the format 2 SORT statement to sort a table on page 671
|
Processing table items using intrinsic functions
You can use intrinsic functions to process alphabetic, alphanumeric, national, or
numeric table items. (You can process DBCS data items only with the NATIONAL-OF
intrinsic function.) The data descriptions of the table items must be compatible
with the requirements for the function arguments.
Use a subscript or index to reference an individual data item as a function
argument. For example, assuming that Table-One is a 3 x 3 array of numeric items,
you can find the square root of the middle element by using this statement:
Compute X = Function Sqrt(Table-One(2,2))
You might often need to iteratively process the data in tables. For intrinsic
functions that accept multiple arguments, you can use the subscript ALL to
reference all the items in the table or in a single dimension of the table. The
iteration is handled automatically, which can make your code shorter and simpler.
You can mix scalars and array arguments for functions that accept multiple
arguments:
Compute Table-Median = Function Median(Arg1 Table-One(ALL))
Example: processing tables using intrinsic functions
RELATED TASKS
Using intrinsic functions (built-in functions) on page 38
Converting data items (intrinsic functions) on page 116
Evaluating data items (intrinsic functions) on page 119
RELATED REFERENCES
Intrinsic functions (Enterprise COBOL Language Reference)
Example: processing tables using intrinsic functions
These examples show how you can apply an intrinsic function to some or all of the
elements in a table by using the ALL subscript.
Assuming that Table-Two is a 2 x 3 x 2 array, the following statement adds the
values in elements Table-Two(1,3,1), Table-Two(1,3,2), Table-Two(2,3,1), and
Table-Two(2,3,2):
Compute Table-Sum = FUNCTION SUM (Table-Two(ALL, 3, ALL))
The following example computes various salary values for all the employees
whose salaries are encoded in Employee-Table:
01 Employee-Table.
05 Emp-Count Pic s9(4) usage binary.
05 Emp-Record Occurs 1 to 500 times
depending on Emp-Count.
10 Emp-Name Pic x(20).
10 Emp-Idme Pic 9(9).
10 Emp-Salary Pic 9(7)v99.
. . .
Procedure Division.
Compute Max-Salary = Function Max(Emp-Salary(ALL))
Chapter 4. Handling tables 89
Compute I = Function Ord-Max(Emp-Salary(ALL))
Compute Avg-Salary = Function Mean(Emp-Salary(ALL))
Compute Salary-Range = Function Range(Emp-Salary(ALL))
Compute Total-Payroll = Function Sum(Emp-Salary(ALL))
Working with unbounded tables and groups
You can process an unbounded group as the input parameter to a called program.
The memory for the unbounded group is provided by the calling program.
Alternatively, you can define, initialize, and process unbounded groups in a single
program.
To work with unbounded tables and groups in a single program, do these steps:
1. In the LINKAGE SECTION, define an unbounded table (with the syntax of OCCURS
n TO UNBOUNDED), which will be part of an unbounded group.
2. In the WORKING-STORAGE SECTION or LOCAL-STORAGE SECTION, define the OCCURS
DEPENDING ON objects.
3. In the PROCEDURE DIVISION, do these steps to process unbounded groups:
a. Set the OCCURS DEPENDING ON objects.
b. Use the LENGTH special register or the LENGTH intrinsic function to compute
the total size of the group.
c. Use the CALL statement to call a storage allocation service, such as the
Language Environment service CEEGTST. Allocate enough memory for the
total length of the group. You will need a pointer to this memory (the
CEEGTST service returns a pointer).
d. Use the SET statement to establish addressability. For example, SET ADDRESS
OF group TO pointer.
4. Use the unbounded table and its containing unbounded group according to the
following rules:
v You can reference unbounded tables in COBOL syntax anywhere a table can
be referenced.
v You can reference unbounded groups in COBOL syntax anywhere an
alphanumeric or national group can be referenced, with the following
exceptions:
You cannot specify unbounded groups as a BY CONTENT argument in a CALL
statement.
You cannot specify unbounded groups as data-name-2 on the PROCEDURE
DIVISION RETURNING phrase.
You cannot specify unbounded groups as arguments to intrinsic functions,
except as an argument to the LENGTH intrinsic function.
RELATED REFERENCES
Example: Using unbounded tables for parsing XML documents
Variable-length tables (Enterprise COBOL Language Reference)
OCCURS DEPENDING ON clause (Enterprise COBOL Language Reference)
Example: Using unbounded tables for parsing XML
documents
Consider using unbounded tables when parsing an XML document with an
unknown number of repetitive elements.
You can use any of the following methods:
90 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Predetermine the number of elements to expect. One method to determine the
number of elements is to parse the XML document twice. During the first parse,
count the number of occurrences of each unbounded element in the
corresponding OCCURS UNBOUNDED DEPENDING ON object. Then, allocate storage for
the data items using these computed values, and parse the XML document a
second time to process its payload.
v Pick initial sizes and allow for expansion of the tables. It might be more efficient
to set arbitrary limits in the OCCURS UNBOUNDED DEPENDING ON objects based on
previous experience, and parse the document directly to process its content. For
each unbounded element, check if the current limit is about to be exceeded. If
so, allocate more storage for the corresponding array, copy the data from the old
array to the expanded array, then free the storage for the old array.
The following examples illustrate the first method. See the XML schema example,
and note that elements B and C have a maxOccurs value of unbounded, and thus can
occur an unlimited number of times in the sequence within element G. In the XML
document example, element B in fact occurs three times, and element C occurs five
times.
In the XML processing program example, the processing procedure for the first XML
PARSE statement simply computes the number of occurrences of elements B and C.
After allocating the required storage, the program executes a second XML PARSE
statement to process the XML payload.
XML schema
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://example.org"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="G">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="A" type="xsd:string" maxOccurs="1" />
<xsd:element name="B" type="xsd:int" maxOccurs="unbounded" />
<xsd:element name="C" type="xsd:int" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
XML document
<?xml version="1.0" encoding="UTF-8"?>
<p:G xmlns:p="http://example.org" >
<A>Hello</A>
<B>1</B>
<B>2</B>
<B>3</B>
<C>1</C>
<C>2</C>
<C>3</C>
<C>4</C>
<C>5</C>
</p:G>
XML processing program
Identification division.
Program-id. XMLProc.
Data division.
Working-storage section.
01 NB pic S9(9) binary value zero.
01 NC pic S9(9) binary value zero.
Chapter 4. Handling tables 91
01 Gptr pointer.
01 Gsize pic 9(9) binary.
01 Heap0 pic 9(9) binary value zero.
Linkage section.
01 XML-Doc pic X(500000).
01 G.
02 A pic x(5).
02 B pic s9(9) occurs 1 to unbounded depending on NB.
02 C pic s9(9) occurs 1 to unbounded depending on NC.
Procedure division using XML-Doc.
XML parse XML-Doc processing procedure CountElements
Move length of G to Gsize
Call "CEEGTST" using Heap0 Gsize Gptr omitted
Set address of G to Gptr
XML parse XML-doc processing procedure acquireContent
...
Goback.
CountElements.
If xml-event = START-OF-ELEMENT
Evaluate xml-text
When B
Add 1 to NB
When C
Add 1 to NC
When other
Continue
End-evaluate
End-if.
End program XMLProc.
RELATED TASKS
Working with unbounded tables and groups on page 90
92 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 5. Selecting and repeating program actions
Use COBOL control language to choose program actions based on the outcome of
logical tests, to iterate over selected parts of your program and data, and to
identify statements to be performed as a group.
These controls include the IF, EVALUATE, and PERFORM statements, and the use of
switches and flags.
RELATED TASKS
Selecting program actions
Repeating program actions on page 101
Selecting program actions
You can provide for different program actions depending on the tested value of
one or more data items.
The IF and EVALUATE statements in COBOL test one or more data items by means
of a conditional expression.
RELATED TASKS
Coding a choice of actions
Coding conditional expressions on page 98
RELATED REFERENCES
IF statement (Enterprise COBOL Language Reference)
EVALUATE statement (Enterprise COBOL Language Reference)
Coding a choice of actions
Use IF . . . ELSE to code a choice between two processing actions. (The word
THEN is optional.) Use the EVALUATE statement to code a choice among three or
more possible actions.
IF condition-p
statement-1
ELSE
statement-2
END-IF
When one of two processing choices is no action, code the IF statement with or
without ELSE. Because the ELSE clause is optional, you can code the IF statement as
follows:
IF condition-q
statement-1
END-IF
Such coding is suitable for simple cases. For complex logic, you probably need to
use the ELSE clause. For example, suppose you have nested IF statements in which
there is an action for only one of the processing choices. You could use the ELSE
clause and code the null branch of the IF statement with the CONTINUE statement:
Copyright IBM Corp. 1991, 2015 93
IF condition-q
statement-1
ELSE
CONTINUE
END-IF
The EVALUATE statement is an expanded form of the IF statement that allows you to
avoid nesting IF statements, a common source of logic errors and debugging
problems.
RELATED TASKS
Using nested IF statements
Using the EVALUATE statement on page 95
Coding conditional expressions on page 98
Using nested IF statements
If an IF statement contains an IF statement as one of its possible branches, the IF
statements are said to be nested. Theoretically, there is no limit to the depth of
nested IF statements.
However, use nested IF statements sparingly. The logic can be difficult to follow,
although explicit scope terminators and indentation can help. If a program has to
test a variable for more than two values, EVALUATE is probably a better choice.
The following pseudocode depicts a nested IF statement:
IF condition-p
IF condition-q
statement-1
ELSE
statement-2
END-IF
statement-3
ELSE
statement-4
END-IF
In the pseudocode above, an IF statement and a sequential structure are nested in
one branch of the outer IF. In this structure, the END-IF that closes the nested IF is
very important. Use END-IF instead of a period, because a period would end the
outer IF structure also.
The following figure shows the logic structure of the pseudocode above.
94 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Coding a choice of actions on page 93
RELATED REFERENCES
Explicit scope terminators (Enterprise COBOL Language Reference)
Using the EVALUATE statement
You can use the EVALUATE statement instead of a series of nested IF statements to
test several conditions and specify a different action for each. Thus you can use the
EVALUATE statement to implement a case structure or decision table.
You can also use the EVALUATE statement to cause multiple conditions to lead to the
same processing, as shown in these examples:
Example: EVALUATE using THRU phrase on page 96
Example: EVALUATE using multiple WHEN phrases on page 97
In an EVALUATE statement, the operands before the WHEN phrase are referred to as
selection subjects, and the operands in the WHEN phrase are called the selection objects.
Selection subjects can be identifiers, literals, conditional expressions, or the word
TRUE or FALSE. Selection objects can be identifiers, literals, conditional or arithmetic
expressions, or the word TRUE, FALSE, or ANY.
You can separate multiple selection subjects with the ALSO phrase. You can separate
multiple selection objects with the ALSO phrase. The number of selection objects
within each set of selection objects must be equal to the number of selection
subjects, as shown in this example:
Example: EVALUATE testing several conditions on page 97
Identifiers, literals, or arithmetic expressions that appear within a selection object
must be valid operands for comparison to the corresponding operand in the set of
selection subjects. Conditions or the word TRUE or FALSE that appear in a selection
object must correspond to a conditional expression or the word TRUE or FALSE in
Chapter 5. Selecting and repeating program actions 95
the set of selection subjects. (You can use the word ANY as a selection object to
correspond to any type of selection subject.)
The execution of the EVALUATE statement ends when one of the following
conditions occurs:
v The statements associated with the selected WHEN phrase are performed.
v The statements associated with the WHEN OTHER phrase are performed.
v No WHEN conditions are satisfied.
WHEN phrases are tested in the order that they appear in the source program.
Therefore, you should order these phrases for the best performance. First code the
WHEN phrase that contains selection objects that are most likely to be satisfied, then
the next most likely, and so on. An exception is the WHEN OTHER phrase, which must
come last.
RELATED TASKS
Coding a choice of actions on page 93
RELATED REFERENCES
EVALUATE statement (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
Example: EVALUATE using THRU phrase:
This example shows how you can code several conditions in a range of values to
lead to the same processing action by coding the THRU phrase. Operands in a THRU
phrase must be of the same class.
In this example, CARPOOL-SIZE is the selection subject; 1, 2, and 3 THRU 6 are the
selection objects:
EVALUATE CARPOOL-SIZE
WHEN 1
MOVE "SINGLE" TO PRINT-CARPOOL-STATUS
WHEN 2
MOVE "COUPLE" TO PRINT-CARPOOL-STATUS
WHEN 3 THRU 6
MOVE "SMALL GROUP" TO PRINT-CARPOOL STATUS
WHEN OTHER
MOVE "BIG GROUP" TO PRINT-CARPOOL STATUS
END-EVALUATE
The following nested IF statements represent the same logic:
IF CARPOOL-SIZE = 1 THEN
MOVE "SINGLE" TO PRINT-CARPOOL-STATUS
ELSE
IF CARPOOL-SIZE = 2 THEN
MOVE "COUPLE" TO PRINT-CARPOOL-STATUS
ELSE
IF CARPOOL-SIZE >= 3 and CARPOOL-SIZE <= 6 THEN
MOVE "SMALL GROUP" TO PRINT-CARPOOL-STATUS
ELSE
MOVE "BIG GROUP" TO PRINT-CARPOOL-STATUS
END-IF
END-IF
END-IF
96 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: EVALUATE using multiple WHEN phrases:
The following example shows that you can code multiple WHEN phrases if several
conditions should lead to the same action. Doing so gives you more flexibility than
using only the THRU phrase, because the conditions do not have to evaluate to
values in a range nor have the same class.
EVALUATE MARITAL-CODE
WHEN "M"
ADD 2 TO PEOPLE-COUNT
WHEN "S"
WHEN "D"
WHEN "W"
ADD 1 TO PEOPLE-COUNT
END-EVALUATE
The following nested IF statements represent the same logic:
IF MARITAL-CODE = "M" THEN
ADD 2 TO PEOPLE-COUNT
ELSE
IF MARITAL-CODE = "S" OR
MARITAL-CODE = "D" OR
MARITAL-CODE = "W" THEN
ADD 1 TO PEOPLE-COUNT
END-IF
END-IF
Example: EVALUATE testing several conditions:
This example shows the use of the ALSO phrase to separate two selection subjects
(True ALSO True) and to separate the two corresponding selection objects within
each set of selection objects (for example, When A + B < 10 Also C = 10).
Both selection objects in a WHEN phrase must satisfy the TRUE, TRUE condition before
the associated action is performed. If both objects do not evaluate to TRUE, the next
WHEN phrase is processed.
Identification Division.
Program-ID. MiniEval.
Environment Division.
Configuration Section.
Source-Computer. IBM-390.
Data Division.
Working-Storage Section.
01 Age Pic 999.
01 Sex Pic X.
01 Description Pic X(15).
01 A Pic 999.
01 B Pic 9999.
01 C Pic 9999.
01 D Pic 9999.
01 E Pic 99999.
01 F Pic 999999.
Procedure Division.
PN01.
Evaluate True Also True
When Age < 13 Also Sex = "M"
Move "Young Boy" To Description
When Age < 13 Also Sex = "F"
Move "Young Girl" To Description
When Age > 12 And Age < 20 Also Sex = "M"
Move "Teenage Boy" To Description
When Age > 12 And Age < 20 Also Sex = "F"
Move "Teenage Girl" To Description
When Age > 19 Also Sex = "M"
Chapter 5. Selecting and repeating program actions 97
Move "Adult Man" To Description
When Age > 19 Also Sex = "F"
Move "Adult Woman" To Description
When Other
Move "Invalid Data" To Description
End-Evaluate
Evaluate True Also True
When A + B < 10 Also C = 10
Move "Case 1" To Description
When A + B > 50 Also C = ( D + E ) / F
Move "Case 2" To Description
When Other
Move "Case Other" To Description
End-Evaluate
Stop Run.
Coding conditional expressions
Using the IF and EVALUATE statements, you can code program actions that will be
performed depending on the truth value of a conditional expression.
You can specify the following conditions:
v Relation conditions, such as:
Numeric comparisons
Alphanumeric comparisons
DBCS comparisons
National comparisons
v Class conditions; for example, to test whether a data item:
IS NUMERIC
IS ALPHABETIC
IS DBCS
IS KANJI
IS NOT KANJI
v Condition-name conditions, to test the value of a conditional variable that you
define
v Sign conditions, to test whether a numeric operand IS POSITIVE, NEGATIVE, or
ZERO
v Switch-status conditions, to test the status of UPSI switches that you name in the
SPECIAL-NAMES paragraph
v Complex conditions, such as:
Negated conditions; for example, NOT (A IS EQUAL TO B)
Combined conditions (conditions combined with logical operators AND or OR)
RELATED CONCEPTS
Switches and flags on page 99
RELATED TASKS
Defining switches and flags on page 99
Resetting switches and flags on page 100
Checking for incompatible data (numeric class test) on page 54
Comparing national (UTF-16) data on page 147
Testing for valid DBCS characters on page 151
RELATED REFERENCES
General relation conditions (Enterprise COBOL Language Reference)
98 Enterprise COBOL for z/OS, V5.2 Programming Guide
Class condition (Enterprise COBOL Language Reference)
Rules for condition-name entries (Enterprise COBOL Language Reference)
Sign condition (Enterprise COBOL Language Reference)
Combined conditions (Enterprise COBOL Language Reference)
Switches and flags
Some program decisions are based on whether the value of a data item is true or
false, on or off, yes or no. Control these two-way decisions by using level-88 items
with meaningful names (condition-names) to act as switches.
Other program decisions depend on the particular value or range of values of a
data item. When you use condition-names to give more than just on or off values
to a field, the field is generally referred to as a flag.
Flags and switches make your code easier to change. If you need to change the
values for a condition, you have to change only the value of that level-88
condition-name.
For example, suppose a program uses a condition-name to test a field for a given
salary range. If the program must be changed to check for a different salary range,
you need to change only the value of the condition-name in the DATA DIVISION.
You do not need to make changes in the PROCEDURE DIVISION.
RELATED TASKS
Defining switches and flags
Resetting switches and flags on page 100
Defining switches and flags
In the DATA DIVISION, define level-88 items that will act as switches or flags, and
give them meaningful names.
To test for more than two values with flags, assign more than one condition-name
to a field by using multiple level-88 items.
The reader can easily follow your code if you choose meaningful condition-names
and if the values assigned to them have some association with logical values.
Example: switches
Example: flags on page 100
Example: switches
The following examples show how you can use level-88 items to test for various
binary-valued (on-off) conditions in your program.
For example, to test for the end-of-file condition for an input file named
Transaction-File, you can use the following data definitions:
WORKING-STORAGE SECTION.
01 Switches.
05 Transaction-EOF-Switch Pic X value space.
88 Transaction-EOF value "y".
The level-88 description says that a condition named Transaction-EOF is turned on
when Transaction-EOF-Switch has value 'y'. Referencing Transaction-EOF in the
PROCEDURE DIVISION expresses the same condition as testing Transaction-EOF-
Switch = "y". For example, the following statement causes a report to be printed
only if Transaction-EOF-Switch has been set to 'y':
Chapter 5. Selecting and repeating program actions 99
If Transaction-EOF Then
Perform Print-Report-Summary-Lines
Example: flags
The following examples show how you can use several level-88 items together
with an EVALUATE statement to determine which of several conditions in a program
is true.
Consider for example a program that updates a master file. The updates are read
from a transaction file. The records in the file contain a field that indicates which
of the three functions is to be performed: add, change, or delete. In the record
description of the input file, code a field for the function code using level-88 items:
01 Transaction-Input Record
05 Transaction-Type Pic X.
88 Add-Transaction Value "A".
88 Change-Transaction Value "C".
88 Delete-Transaction Value "D".
The code in the PROCEDURE DIVISION for testing these condition-names to determine
which function is to be performed might look like this:
Evaluate True
When Add-Transaction
Perform Add-Master-Record-Paragraph
When Change-Transaction
Perform Update-Existing-Record-Paragraph
When Delete-Transaction
Perform Delete-Master-Record-Paragraph
End-Evaluate
Resetting switches and flags
Throughout your program, you might need to reset switches or flags to the
original values they had in their data descriptions. To do so, either use a SET
statement or define a data item to move to the switch or flag.
When you use the SET condition-name TO TRUE statement, the switch or flag is set to
the original value that it was assigned in its data description. For a level-88 item
that has multiple values, SET condition-name TO TRUE assigns the first value (A in the
example below):
88 Record-is-Active Value "A" "O" "S"
Using the SET statement and meaningful condition-names makes it easier for
readers to follow your code.
Example: set switch on
Example: set switch off on page 101
Example: set switch on
The following examples show how you can set a switch on by coding a SET
statement that moves the value TRUE to a level-88 item.
For example, the SET statement in the following example has the same effect as
coding the statement Move "y" to Transaction-EOF-Switch:
01 Switches
05 Transaction-EOF-Switch Pic X Value space.
88 Transaction-EOF Value "y".
. . .
Procedure Division.
000-Do-Main-Logic.
100 Enterprise COBOL for z/OS, V5.2 Programming Guide
Perform 100-Initialize-Paragraph
Read Update-Transaction-File
At End Set Transaction-EOF to True
End-Read
The following example shows how to assign a value to a field in an output record
based on the transaction code of an input record:
01 Input-Record.
05 Transaction-Type Pic X(9).
01 Data-Record-Out.
05 Data-Record-Type Pic X.
88 Record-Is-Active Value "A".
88 Record-Is-Suspended Value "S".
88 Record-Is-Deleted Value "D".
05 Key-Field Pic X(5).
. . .
Procedure Division.
Evaluate Transaction-Type of Input-Record
When "ACTIVE"
Set Record-Is-Active to TRUE
When "SUSPENDED"
Set Record-Is-Suspended to TRUE
When "DELETED"
Set Record-Is-Deleted to TRUE
End-Evaluate
Example: set switch off
The following example shows how you can set a switch off by coding a MOVE
statement that moves a value to a level-88 item.
For example, you can use a data item called SWITCH-OFF to set an on-off switch to
off, as in the following code, which resets a switch to indicate that end-of-file has
not been reached:
01 Switches
05 Transaction-EOF-Switch Pic X Value space.
88 Transaction-EOF Value "y".
01 SWITCH-OFF Pic X Value "n".
. . .
Procedure Division.
. . .
Move SWITCH-OFF to Transaction-EOF-Switch
Repeating program actions
Use a PERFORM statement to repeat the same code (that is, loop) either a specified
number of times or based on the outcome of a decision.
You can also use a PERFORM statement to execute a paragraph and then implicitly
return control to the next executable statement. In effect, this PERFORM statement is
a way of coding a closed subroutine that you can enter from many different parts
of the program.
PERFORM statements can be inline or out-of-line.
RELATED TASKS
Choosing inline or out-of-line PERFORM on page 102
Coding a loop on page 103
Looping through a table on page 103
Executing multiple paragraphs or sections on page 104
Chapter 5. Selecting and repeating program actions 101
RELATED REFERENCES
PERFORM statement (Enterprise COBOL Language Reference)
Choosing inline or out-of-line PERFORM
An inline PERFORM is an imperative statement that is executed in the normal flow of
a program; an out-of-line PERFORM entails a branch to a named paragraph and an
implicit return from that paragraph.
To determine whether to code an inline or out-of-line PERFORM statement, answer
the following questions:
v Is the PERFORM statement used in several places?
Use an out-of-line PERFORM when you want to use the same portion of code in
several places in your program.
v Which placement of the statement will be easier to read?
If the code to be performed is short, an inline PERFORM can be easier to read. But
if the code extends over several screens, the logical flow of the program might
be clearer if you use an out-of-line PERFORM. (Each paragraph in structured
programming should perform one logical function, however.)
v What are the efficiency tradeoffs?
An inline PERFORM avoids the overhead of branching that occurs with an
out-of-line PERFORM. But even out-of-line PERFORM coding can improve code
optimization, so efficiency gains should not be overemphasized.
In the 1974 COBOL standard, the PERFORM statement is out-of-line and thus requires
a branch to a separate paragraph and an implicit return. If the performed
paragraph is in the subsequent sequential flow of your program, it is also executed
in that logic flow. To avoid this additional execution, place the paragraph outside
the normal sequential flow (for example, after the GOBACK) or code a branch around
it.
The subject of an inline PERFORM is an imperative statement. Therefore, you must
code statements (other than imperative statements) within an inline PERFORM with
explicit scope terminators.
Example: inline PERFORM statement
Example: inline PERFORM statement
This example shows the structure of an inline PERFORM statement that has the
required scope terminators and the required END-PERFORM phrase.
Perform 100-Initialize-Paragraph
* The following statement is an inline PERFORM:
Perform Until Transaction-EOF
Read Update-Transaction-File Into WS-Transaction-Record
At End
Set Transaction-EOF To True
Not At End
Perform 200-Edit-Update-Transaction
If No-Errors
Perform 300-Update-Commuter-Record
Else
Perform 400-Print-Transaction-Errors
* End-If is a required scope terminator
End-If
Perform 410-Re-Initialize-Fields
* End-Read is a required scope terminator
End-Read
End-Perform
102 Enterprise COBOL for z/OS, V5.2 Programming Guide
Coding a loop
Use the PERFORM . . . TIMES statement to execute a paragraph a specified number
of times.
PERFORM 010-PROCESS-ONE-MONTH 12 TIMES
INSPECT . . .
In the example above, when control reaches the PERFORM statement, the code for the
paragraph 010-PROCESS-ONE-MONTH is executed 12 times before control is transferred
to the INSPECT statement.
Use the PERFORM . . . UNTIL statement to execute a paragraph until a condition
you choose is satisfied. You can use either of the following forms:
PERFORM . . . WITH TEST AFTER . . . . UNTIL . . .
PERFORM . . . [WITH TEST BEFORE] . . . UNTIL . . .
Use the PERFORM . . . WITH TEST AFTER . . . UNTIL statement if you want to
execute the paragraph at least once, and test before any subsequent execution. This
statement is equivalent to a do-until structure:
In the following example, the implicit WITH TEST BEFORE phrase provides a
do-while structure:
PERFORM 010-PROCESS-ONE-MONTH
UNTIL MONTH GREATER THAN 12
INSPECT . . .
When control reaches the PERFORM statement, the condition MONTH GREATER THAN 12
is tested. If the condition is satisfied, control is transferred to the INSPECT
statement. If the condition is not satisfied, 010-PROCESS-ONE-MONTH is executed, and
the condition is tested again. This cycle continues until the condition tests as true.
(To make your program easier to read, you might want to code the WITH TEST
BEFORE clause.)
Looping through a table
You can use the PERFORM . . . VARYING statement to initialize a table. In this form
of the PERFORM statement, a variable is increased or decreased and tested until a
condition is satisfied.
Thus you use the PERFORM statement to control looping through a table. You can
use either of these forms:
PERFORM . . . WITH TEST AFTER . . . . VARYING . . . UNTIL . . .
PERFORM . . . [WITH TEST BEFORE] . . . VARYING . . . UNTIL . . .
Chapter 5. Selecting and repeating program actions 103
The following section of code shows an example of looping through a table to
check for invalid data:
PERFORM TEST AFTER VARYING WS-DATA-IX
FROM 1 BY 1 UNTIL WS-DATA-IX = 12
IF WS-DATA (WS-DATA-IX) EQUALS SPACES
SET SERIOUS-ERROR TO TRUE
DISPLAY ELEMENT-NUM-MSG5
END-IF
END-PERFORM
INSPECT . . .
When control reaches the PERFORM statement above, WS-DATA-IX is set equal to 1
and the PERFORM statement is executed. Then the condition WS-DATA-IX = 12 is
tested. If the condition is true, control drops through to the INSPECT statement. If
the condition is false, WS-DATA-IX is increased by 1, the PERFORM statement is
executed, and the condition is tested again. This cycle of execution and testing
continues until WS-DATA-IX is equal to 12.
The loop above controls input-checking for the 12 fields of item WS-DATA. Empty
fields are not allowed in the application, so the section of code loops and issues
error messages as appropriate.
Executing multiple paragraphs or sections
In structured programming, you usually execute a single paragraph. However, you
can execute a group of paragraphs, or a single section or group of sections, by
coding the PERFORM . . . THRU statement.
When you use the PERFORM . . . THRU statement, code a paragraph-EXIT statement
to clearly indicate the end point of a series of paragraphs.
RELATED TASKS
Processing table items using intrinsic functions on page 89
104 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 6. Handling strings
COBOL provides language constructs for performing many different operations on
string data items.
For example, you can:
v Join or split data items.
v Manipulate null-terminated strings, such as count or move characters.
v Refer to substrings by their ordinal position and, if needed, length.
v Tally and replace data items, such as count the number of times a specific
character occurs in a data item.
v Convert data items, such as change to uppercase or lowercase.
v Evaluate data items, such as determine the length of a data item.
RELATED TASKS
Joining data items (STRING)
Splitting data items (UNSTRING) on page 107
Manipulating null-terminated strings on page 110
Referring to substrings of data items on page 111
Tallying and replacing data items (INSPECT) on page 115
Converting data items (intrinsic functions) on page 116
Evaluating data items (intrinsic functions) on page 119
Chapter 7, Processing data in an international environment, on page 125
Joining data items (STRING)
Use the STRING statement to join all or parts of several data items or literals into
one data item. One STRING statement can take the place of several MOVE statements.
The STRING statement transfers data into a receiving data item in the order that you
indicate. In the STRING statement you also specify:
v A delimiter for each set of sending fields that, if encountered, causes those
sending fields to stop being transferred (DELIMITED BY phrase)
v (Optional) Action to be taken if the receiving field is filled before all of the
sending data has been processed (ON OVERFLOW phrase)
v (Optional) An integer data item that indicates the leftmost character position
within the receiving field into which data should be transferred (WITH POINTER
phrase)
The receiving data item must not be an edited item, or a display or national
floating-point item. If the receiving data item has:
v USAGE DISPLAY, each identifier in the statement except the POINTER identifier
must have USAGE DISPLAY, and each literal in the statement must be
alphanumeric
v USAGE NATIONAL, each identifier in the statement except the POINTER identifier
must have USAGE NATIONAL, and each literal in the statement must be national
v USAGE DISPLAY-1, each identifier in the statement except the POINTER identifier
must have USAGE DISPLAY-1, and each literal in the statement must be DBCS
Copyright IBM Corp. 1991, 2015 105
Only that portion of the receiving field into which data is written by the STRING
statement is changed.
Example: STRING statement
RELATED TASKS
Handling errors in joining and splitting strings on page 240
RELATED REFERENCES
STRING statement (Enterprise COBOL Language Reference)
Example: STRING statement
The following example shows the STRING statement selecting and formatting
information from a record into an output line.
The FILE SECTION defines the following record:
01 RCD-01.
05 CUST-INFO.
10 CUST-NAME PIC X(15).
10 CUST-ADDR PIC X(35).
05 BILL-INFO.
10 INV-NO PIC X(6).
10 INV-AMT PIC $$,$$$.99.
10 AMT-PAID PIC $$,$$$.99.
10 DATE-PAID PIC X(8).
10 BAL-DUE PIC $$,$$$.99.
10 DATE-DUE PIC X(8).
The WORKING-STORAGE SECTION defines the following fields:
77 RPT-LINE PIC X(120).
77 LINE-POS PIC S9(3).
77 LINE-NO PIC 9(5) VALUE 1.
77 DEC-POINT PIC X VALUE ".".
The record RCD-01 contains the following information (the symbol b indicates a
blank space):
J.B.bSMITHbbbbb
444bSPRINGbST.,bCHICAGO,bILL.bbbbbb
A14275
$4,736.85
$2,400.00
09/22/76
$2,336.85
10/22/76
In the PROCEDURE DIVISION, these settings occur before the STRING statement:
v RPT-LINE is set to SPACES.
v LINE-POS, the data item to be used as the POINTER field, is set to 4.
Here is the STRING statement:
STRING
LINE-NO SPACE CUST-INFO INV-NO SPACE DATE-DUE SPACE
DELIMITED BY SIZE
BAL-DUE
DELIMITED BY DEC-POINT
INTO RPT-LINE
WITH POINTER LINE-POS.
106 Enterprise COBOL for z/OS, V5.2 Programming Guide
Because the POINTER field LINE-POS has value 4 before the STRING statement is
performed, data is moved into the receiving field RPT-LINE beginning at character
position 4. Characters in positions 1 through 3 are unchanged.
The sending items that specify DELIMITED BY SIZE are moved in their entirety to
the receiving field. Because BAL-DUE is delimited by DEC-POINT, the moving of
BAL-DUE to the receiving field stops when a decimal point (the value of DEC-POINT)
is encountered.
STRING results
When the STRING statement is performed, items are moved into RPT-LINE as shown
in the table below.
Item Positions
LINE-NO 4-8
Space 9
CUST-INFO 10 - 59
INV-NO 60 - 65
Space 66
DATE-DUE 67 - 74
Space 75
Portion of BAL-DUE that precedes the decimal point 76 - 81
After the STRING statement is performed, the value of LINE-POS is 82, and RPT-LINE
has the values shown below.
Splitting data items (UNSTRING)
Use the UNSTRING statement to split a sending field into several receiving fields.
One UNSTRING statement can take the place of several MOVE statements.
In the UNSTRING statement you can specify:
v Delimiters that, when one of them is encountered in the sending field, cause the
current receiving field to stop receiving and the next, if any, to begin receiving
(DELIMITED BY phrase)
v A field for the delimiter that, when encountered in the sending field, causes the
current receiving field to stop receiving (DELIMITER IN phrase)
v An integer data item that stores the number of characters placed in the current
receiving field (COUNT IN phrase)
v An integer data item that indicates the leftmost character position within the
sending field at which UNSTRING processing should begin (WITH POINTER phrase)
v An integer data item that stores a tally of the number of receiving fields that are
acted on (TALLYING IN phrase)
Chapter 6. Handling strings 107
v Action to be taken if all of the receiving fields are filled before the end of the
sending data item is reached (ON OVERFLOW phrase)
The sending data item and the delimiters in the DELIMITED BY phrase must be of
category alphabetic, alphanumeric, alphanumeric-edited, DBCS, national, or
national-edited.
Receiving data items can be of category alphabetic, alphanumeric, numeric, DBCS,
or national. If numeric, a receiving data item must be zoned decimal or national
decimal. If a receiving data item has:
v USAGE DISPLAY, the sending item and each delimiter item in the statement must
have USAGE DISPLAY, and each literal in the statement must be alphanumeric
v USAGE NATIONAL, the sending item and each delimiter item in the statement must
have USAGE NATIONAL, and each literal in the statement must be national
v USAGE DISPLAY-1, the sending item and each delimiter item in the statement
must have USAGE DISPLAY-1, and each literal in the statement must be DBCS
Example: UNSTRING statement
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Handling errors in joining and splitting strings on page 240
RELATED REFERENCES
UNSTRING statement (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Example: UNSTRING statement
The following example shows the UNSTRING statement transferring selected
information from an input record. Some information is organized for printing and
some for further processing.
The FILE SECTION defines the following records:
* Record to be acted on by the UNSTRING statement:
01 INV-RCD.
05 CONTROL-CHARS PIC XX.
05 ITEM-INDENT PIC X(20).
05 FILLER PIC X.
05 INV-CODE PIC X(10).
05 FILLER PIC X.
05 NO-UNITS PIC 9(6).
05 FILLER PIC X.
05 PRICE-PER-M PIC 99999.
05 FILLER PIC X.
05 RTL-AMT PIC 9(6).99.
*
* UNSTRING receiving field for printed output:
01 DISPLAY-REC.
05 INV-NO PIC X(6).
05 FILLER PIC X VALUE SPACE.
05 ITEM-NAME PIC X(20).
05 FILLER PIC X VALUE SPACE.
05 DISPLAY-DOLS PIC 9(6).
*
* UNSTRING receiving field for further processing:
01 WORK-REC.
108 Enterprise COBOL for z/OS, V5.2 Programming Guide
05 M-UNITS PIC 9(6).
05 FIELD-A PIC 9(6).
05 WK-PRICE REDEFINES FIELD-A PIC 9999V99.
05 INV-CLASS PIC X(3).
*
* UNSTRING statement control fields:
77 DBY-1 PIC X.
77 CTR-1 PIC S9(3).
77 CTR-2 PIC S9(3).
77 CTR-3 PIC S9(3).
77 CTR-4 PIC S9(3).
77 DLTR-1 PIC X.
77 DLTR-2 PIC X.
77 CHAR-CT PIC S9(3).
77 FLDS-FILLED PIC S9(3).
In the PROCEDURE DIVISION, these settings occur before the UNSTRING statement:
v A period (.) is placed in DBY-1 for use as a delimiter.
v CHAR-CT (the POINTER field) is set to 3.
v The value zero (0) is placed in FLDS-FILLED (the TALLYING field).
v Data is read into record INV-RCD, whose format is as shown below.
Here is the UNSTRING statement:
* Move subfields of INV-RCD to the subfields of DISPLAY-REC
* and WORK-REC:
UNSTRING INV-RCD
DELIMITED BY ALL SPACES OR "/" OR DBY-1
INTO ITEM-NAME COUNT IN CTR-1
INV-NO DELIMITER IN DLTR-1 COUNT IN CTR-2
INV-CLASS
M-UNITS COUNT IN CTR-3
FIELD-A
DISPLAY-DOLS DELIMITER IN DLTR-2 COUNT IN CTR-4
WITH POINTER CHAR-CT
TALLYING IN FLDS-FILLED
ON OVERFLOW GO TO UNSTRING-COMPLETE.
Because the POINTER field CHAR-CT has value 3 before the UNSTRING statement is
performed, the two character positions of the CONTROL-CHARS field in INV-RCD are
ignored.
UNSTRING results
When the UNSTRING statement is performed, the following steps take place:
1. Positions 3 through 18 (FOUR-PENNY-NAILS) of INV-RCD are placed in ITEM-NAME,
left justified in the area, and the four unused character positions are padded
with spaces. The value 16 is placed in CTR-1.
2. Because ALL SPACES is coded as a delimiter, the five contiguous space characters
in positions 19 through 23 are considered to be one occurrence of the delimiter.
3. Positions 24 through 29 (707890) are placed in INV-NO. The delimiter character
slash (/) is placed in DLTR-1, and the value 6 is placed in CTR-2.
Chapter 6. Handling strings 109
4. Positions 31 through 33 (BBA) are placed in INV-CLASS. The delimiter is SPACE,
but because no field has been defined as a receiving area for delimiters, the
space in position 34 is bypassed.
5. Positions 35 through 40 (475120) are placed in M-UNITS. The value 6 is placed in
CTR-3. The delimiter is SPACE, but because no field has been defined as a
receiving area for delimiters, the space in position 41 is bypassed.
6. Positions 42 through 46 (00122) are placed in FIELD-A and right justified in the
area. The high-order digit position is filled with a zero (0). The delimiter is
SPACE, but because no field was defined as a receiving area for delimiters, the
space in position 47 is bypassed.
7. Positions 48 through 53 (000379) are placed in DISPLAY-DOLS. The period (.)
delimiter in DBY-1 is placed in DLTR-2, and the value 6 is placed in CTR-4.
8. Because all receiving fields have been acted on and two characters in INV-RCD
have not been examined, the ON OVERFLOW statement is executed. Execution of
the UNSTRING statement is completed.
After the UNSTRING statement is performed, the fields contain the values shown
below.
Field Value
DISPLAY-REC 707890 FOUR-PENNY-NAILS 000379
WORK-REC 475120000122BBA
CHAR-CT (the POINTER field) 55
FLDS-FILLED (the TALLYING field) 6
Manipulating null-terminated strings
You can construct and manipulate null-terminated strings (for example, strings that
are passed to or from a C program) by various mechanisms.
For example, you can:
v Use null-terminated literal constants (Z". . . ").
v Use an INSPECT statement to count the number of characters in a null-terminated
string:
MOVE 0 TO char-count
INSPECT source-field TALLYING char-count
FOR CHARACTERS
BEFORE X"00"
v Use an UNSTRING statement to move characters in a null-terminated string to a
target field, and get the character count:
WORKING-STORAGE SECTION.
01 source-field PIC X(1001).
01 char-count COMP-5 PIC 9(4).
01 target-area.
02 individual-char OCCURS 1 TO 1000 TIMES DEPENDING ON char-count
PIC X.
. . .
PROCEDURE DIVISION.
UNSTRING source-field DELIMITED BY X"00"
INTO target-area
COUNT IN char-count
ON OVERFLOW
DISPLAY "source not null terminated or target too short"
END-UNSTRING
110 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Use a SEARCH statement to locate trailing null or space characters. Define the
string being examined as a table of single characters.
v Check each character in a field in a loop (PERFORM). You can examine each
character in a field by using a reference modifier such as source-field (I:1).
Example: null-terminated strings
RELATED TASKS
Handling null-terminated strings on page 486
RELATED REFERENCES
Alphanumeric literals (Enterprise COBOL Language Reference)
Example: null-terminated strings
The following example shows several ways in which you can process
null-terminated strings.
01 L pic X(20) value zab.
01 M pic X(20) value zcd.
01 N pic X(20).
01 N-Length pic 99 value zero.
01 Y pic X(13) value Hello, World!.
. . .
* Display null-terminated string:
Inspect N tallying N-length
for characters before initial x00
Display N: N(1:N-Length) Length: N-Length
. . .
* Move null-terminated string to alphanumeric, strip null:
Unstring N delimited by X00 into X
. . .
* Create null-terminated string:
String Y delimited by size
X00 delimited by size
into N.
. . .
* Concatenate two null-terminated strings to produce another:
String L delimited by x00
M delimited by x00
X00 delimited by size
into N.
Referring to substrings of data items
Refer to a substring of a data item that has USAGE DISPLAY, DISPLAY-1, or NATIONAL
by using a reference modifier. You can also refer to a substring of an alphanumeric
or national character string that is returned by an intrinsic function by using a
reference modifier.
Note: To get a substring of a character string argument that is encoded in UTF-8,
use the USUBSTR function as described in Using intrinsic functions to process
UTF-8 encoded data on page 142.
The following example shows how to use a reference modifier to refer to a
twenty-character substring of a data item called Customer-Record:
Move Customer-Record(1:20) to Orig-Customer-Name
You code a reference modifier in parentheses immediately after the data item. As
the example shows, a reference modifier can contain two values that are separated
by a colon, in this order:
Chapter 6. Handling strings 111
1. Ordinal position (from the left) of the character that you want the substring to
start with
2. (Optional) Length of the required substring in character positions
The reference-modifier position and length for an item that has USAGE DISPLAY are
expressed in terms of single-byte characters. The reference-modifier position and
length for items that have USAGE DISPLAY-1 or NATIONAL are expressed in terms of
DBCS character positions and national character positions, respectively.
If you omit the length in a reference modifier (coding only the ordinal position of
the first character, followed by a colon), the substring extends to the end of the
item. Omit the length where possible as a simpler and less error-prone coding
technique.
You can refer to substrings of USAGE DISPLAY data items, including alphanumeric
groups, alphanumeric-edited data items, numeric-edited data items, display
floating-point data items, and zoned decimal data items, by using reference
modifiers. When you reference-modify any of these data items, the result is of
category alphanumeric. When you reference-modify an alphabetic data item, the
result is of category alphabetic.
You can refer to substrings of USAGE NATIONAL data items, including national
groups, national-edited data items, numeric-edited data items, national
floating-point data items, and national decimal data items, by using reference
modifiers. When you reference-modify any of these data items, the result is of
category national. For example, suppose that you define a national decimal data
item as follows:
01 NATL-DEC-ITEM Usage National Pic 999 Value 123.
You can use NATL-DEC-ITEM in an arithmetic expression because NATL-DEC-ITEM is of
category numeric. But you cannot use NATL-DEC-ITEM(2:1) (the national character
2, which in hexadecimal notation is NX"0032") in an arithmetic expression, because
it is of category national.
You can refer to substrings of table entries, including variable-length entries, by
using reference modifiers. To refer to a substring of a table entry, code the
subscript expression before the reference modifier. For example, assume that
PRODUCT-TABLE is a properly coded table of character strings. To move D to the
fourth character in the second string in the table, you can code this statement:
MOVE D to PRODUCT-TABLE (2), (4:1)
You can code either or both of the two values in a reference modifier as a variable
or as an arithmetic expression.
Example: arithmetic expressions as reference modifiers on page 114
Because numeric function identifiers can be used anywhere that arithmetic
expressions can be used, you can code a numeric function identifier in a reference
modifier as the leftmost character position or as the length, or both.
Example: intrinsic functions as reference modifiers on page 114
Each number in the reference modifier must have a value of at least 1. The sum of
the two numbers must not exceed the total length of the data item by more than 1
character position so that you do not reference beyond the end of the substring.
112 Enterprise COBOL for z/OS, V5.2 Programming Guide
If the leftmost character position or the length value is a fixed-point noninteger,
truncation occurs to create an integer. If either is a floating-point noninteger,
rounding occurs to create an integer.
The SSRANGE compiler option detects out-of-range reference modifiers, and flags
violations with a runtime message.
RELATED CONCEPTS
Reference modifiers
Unicode and the encoding of language characters on page 129
RELATED TASKS
Referring to an item in a table on page 70
RELATED REFERENCES
SSRANGE on page 357
Reference modification (Enterprise COBOL Language Reference)
Function definitions (Enterprise COBOL Language Reference)
Reference modifiers
Reference modifiers let you easily refer to a substring of a data item.
For example, assume that you want to retrieve the current time from the system
and display its value in an expanded format. You can retrieve the current time
with the ACCEPT statement, which returns the hours, minutes, seconds, and
hundredths of seconds in this format:
HHMMSSss
However, you might prefer to view the current time in this format:
HH:MM:SS
Without reference modifiers, you would have to define data items for both formats.
You would also have to write code to convert from one format to the other.
With reference modifiers, you do not need to provide names for the subfields that
describe the TIME elements. The only data definition you need is for the time as
returned by the system. For example:
01 REFMOD-TIME-ITEM PIC X(8).
The following code retrieves and expands the time value:
ACCEPT REFMOD-TIME-ITEM FROM TIME.
DISPLAY "CURRENT TIME IS: "
* Retrieve the portion of the time value that corresponds to
* the number of hours:
REFMOD-TIME-ITEM (1:2)
":"
* Retrieve the portion of the time value that corresponds to
* the number of minutes:
REFMOD-TIME-ITEM (3:2)
":"
* Retrieve the portion of the time value that corresponds to
* the number of seconds:
REFMOD-TIME-ITEM (5:2)
Example: arithmetic expressions as reference modifiers on page 114
Example: intrinsic functions as reference modifiers on page 114
Chapter 6. Handling strings 113
RELATED TASKS
Assigning input from a screen or file (ACCEPT) on page 34
Referring to substrings of data items on page 111
Using national data (Unicode) in COBOL on page 130
RELATED REFERENCES
Reference modification (Enterprise COBOL Language Reference)
Example: arithmetic expressions as reference modifiers
Suppose that a field contains some right-justified characters, and you want to
move those characters to another field where they will be left justified. You can do
so by using reference modifiers and an INSPECT statement.
Suppose a program has the following data:
01 LEFTY PIC X(30).
01 RIGHTY PIC X(30) JUSTIFIED RIGHT.
01 I PIC 9(9) USAGE BINARY.
The program counts the number of leading spaces and, using arithmetic
expressions in a reference modifier, moves the right-justified characters into
another field, justified to the left:
MOVE SPACES TO LEFTY
MOVE ZERO TO I
INSPECT RIGHTY
TALLYING I FOR LEADING SPACE.
IF I IS LESS THAN LENGTH OF RIGHTY THEN
MOVE RIGHTY ( I + 1 : LENGTH OF RIGHTY - I ) TO LEFTY
END-IF
The MOVE statement transfers characters from RIGHTY, beginning at the position
computed as I + 1 for a length that is computed as LENGTH OF RIGHTY - I, into the
field LEFTY.
Example: intrinsic functions as reference modifiers
You can use intrinsic functions in reference modifiers if you do not know the
leftmost position or length of a substring at compile time.
For example, the following code fragment causes a substring of Customer-Record to
be moved into the data item WS-name. The substring is determined at run time.
05 WS-name Pic x(20).
05 Left-posn Pic 99.
05 I Pic 99.
. . .
Move Customer-Record(Function Min(Left-posn I):Function Length(WS-name)) to WS-name
If you want to use a noninteger function in a position that requires an integer
function, you can use the INTEGER or INTEGER-PART function to convert the result to
an integer. For example:
Move Customer-Record(Function Integer(Function Sqrt(I)): ) to WS-name
RELATED REFERENCES
INTEGER (Enterprise COBOL Language Reference)
INTEGER-PART (Enterprise COBOL Language Reference)
114 Enterprise COBOL for z/OS, V5.2 Programming Guide
Tallying and replacing data items (INSPECT)
Use the INSPECT statement to inspect characters or groups of characters in a data
item and to optionally replace them.
Use the INSPECT statement to do the following tasks:
v Count the number of times a specific character occurs in a data item (TALLYING
phrase).
v Fill a data item or selected portions of a data item with specified characters such
as spaces, asterisks, or zeros (REPLACING phrase).
v Convert all occurrences of a specific character or string of characters in a data
item to replacement characters that you specify (CONVERTING phrase).
You can specify one of the following data items as the item to be inspected:
v An elementary item described explicitly or implicitly as USAGE DISPLAY, USAGE
DISPLAY-1, or USAGE NATIONAL
v An alphanumeric group item or national group item
If the inspected item has:
v USAGE DISPLAY, each identifier in the statement (except the TALLYING count field)
must have USAGE DISPLAY, and each literal in the statement must be
alphanumeric
v USAGE NATIONAL, each identifier in the statement (except the TALLYING count field)
must have USAGE NATIONAL, and each literal in the statement must be national
v USAGE DISPLAY-1, each identifier in the statement (except the TALLYING count
field) must have USAGE DISPLAY-1, and each literal in the statement must be a
DBCS literal
Examples: INSPECT statement
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED REFERENCES
INSPECT statement (Enterprise COBOL Language Reference)
Examples: INSPECT statement
The following examples show some uses of the INSPECT statement to examine and
replace characters.
In the following example, the INSPECT statement examines and replaces characters
in data item DATA-2. The number of times a leading zero (0) occurs in the data item
is accumulated in COUNTR. The first instance of the character A that follows the first
instance of the character C is replaced by the character 2.
77 COUNTR PIC 9 VALUE ZERO.
01 DATA-2 PIC X(11).
. . .
INSPECT DATA-2
TALLYING COUNTR FOR LEADING "0"
REPLACING FIRST "A" BY "2" AFTER INITIAL "C"
DATA-2 before COUNTR after DATA-2 after
00ACADEMY00 2 00AC2DEMY00
Chapter 6. Handling strings 115
DATA-2 before COUNTR after DATA-2 after
0000ALABAMA 4 0000ALABAMA
CHATHAM0000 0 CH2THAM0000
In the following example, the INSPECT statement examines and replaces characters
in data item DATA-3. Each character that precedes the first instance of a quotation
mark (") is replaced by the character 0.
77 COUNTR PIC 9 VALUE ZERO.
01 DATA-3 PIC X(8).
. . .
INSPECT DATA-3
REPLACING CHARACTERS BY ZEROS BEFORE INITIAL QUOTE
DATA-3 before COUNTR after DATA-3 after
456"ABEL 0 000"ABEL
ANDES"12 0 00000"12
"TWAS BR 0 "TWAS BR
The following example shows the use of INSPECT CONVERTING with AFTER and
BEFORE phrases to examine and replace characters in data item DATA-4. All
characters that follow the first instance of the character / but that precede the first
instance of the character ? (if any) are translated from lowercase to uppercase.
01 DATA-4 PIC X(11).
. . .
INSPECT DATA-4
CONVERTING
"abcdefghijklmnopqrstuvwxyz" TO
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
AFTER INITIAL "/"
BEFORE INITIAL"?"
DATA-4 before DATA-4 after
a/five/?six a/FIVE/?six
r/Rexx/RRRr r/REXX/RRRR
zfour?inspe zfour?inspe
Converting data items (intrinsic functions)
You can use intrinsic functions to convert character-string data items to several
other formats, for example, to uppercase or lowercase, to reverse order, to
numbers, or to one code page from another.
You can use the NATIONAL-OF and DISPLAY-OF intrinsic functions to convert to and
from national (Unicode) strings.
You can also use the INSPECT statement to convert characters.
Examples: INSPECT statement on page 115
RELATED TASKS
Changing case (UPPER-CASE, LOWER-CASE) on page 117
Transforming to reverse order (REVERSE) on page 117
116 Enterprise COBOL for z/OS, V5.2 Programming Guide
Converting to numbers (NUMVAL, NUMVAL-C)
Converting from one code page to another on page 118
Changing case (UPPER-CASE, LOWER-CASE)
You can use the UPPER-CASE and LOWER-CASE intrinsic functions to easily change the
case of alphanumeric, alphabetic, or national strings.
01 Item-1 Pic x(30) Value "Hello World!".
01 Item-2 Pic x(30).
. . .
Display Item-1
Display Function Upper-case(Item-1)
Display Function Lower-case(Item-1)
Move Function Upper-case(Item-1) to Item-2
Display Item-2
The code above displays the following messages on the system logical output
device:
Hello World!
HELLO WORLD!
hello world!
HELLO WORLD!
The DISPLAY statements do not change the actual contents of Item-1, but affect only
how the letters are displayed. However, the MOVE statement causes uppercase
letters to replace the contents of Item-2.
Note: The UPPER-CASE and LOWER-CASE intrinsic functions do not support
alphanumeric arguments that contain UTF-8 encoded data.
RELATED TASKS
Assigning input from a screen or file (ACCEPT) on page 34
Displaying values on a screen or in a file (DISPLAY) on page 35
Transforming to reverse order (REVERSE)
You can reverse the order of the characters in a string by using the REVERSE
intrinsic function.
Move Function Reverse(Orig-cust-name) To Orig-cust-name
For example, the statement above reverses the order of the characters in
Orig-cust-name. If the starting value is JOHNSONbbb, the value after the statement is
performed is bbbNOSNHOJ, where b represents a blank space.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
Converting to numbers (NUMVAL, NUMVAL-C)
The NUMVAL and NUMVAL-C functions convert character strings (alphanumeric or
national literals, or class alphanumeric or class national data items) to numbers.
Use these functions to convert free-format character-representation numbers to
numeric form so that you can process them numerically.
01 R Pic x(20) Value "- 1234.5678".
01 S Pic x(20) Value " $12,345.67CR".
01 Total Usage is Comp-1.
. . .
Compute Total = Function Numval(R) + Function Numval-C(S)
Chapter 6. Handling strings 117
Use NUMVAL-C when the argument includes a currency symbol or comma or both,
as shown in the example above. You can also place an algebraic sign before or after
the character string, and the sign will be processed. The arguments must not
exceed 18 digits when you compile with the default option ARITH(COMPAT)
(compatibility mode) nor 31 digits when you compile with ARITH(EXTEND) (extended
mode), not including the editing symbols.
NUMVAL and NUMVAL-C return long (64-bit) floating-point values in compatibility
mode, and return extended-precision (128-bit) floating-point values in extended
mode. A reference to either of these functions represents a reference to a numeric
data item.
At most 15 decimal digits can be converted accurately to long-precision floating
point (as described in the related reference below about conversions and precision).
If the argument to NUMVAL or NUMVAL-C has more than 15 digits, it is recommended
that you specify the ARITH(EXTEND) compiler option so that an extended-precision
function result that can accurately represent the value of the argument is returned.
| When you use NUMVAL or NUMVAL-C, you do not need to statically define numeric
data in a fixed format nor input data in a precise manner. For example, suppose
you define numbers to be entered as follows:
01 X Pic S999V99 leading sign is separate.
. . .
Accept X from Console
The user of the application must enter the numbers exactly as defined by the
PICTURE clause. For example:
+001.23
-300.00
However, using the NUMVAL function, you could code:
01 A Pic x(10).
01 B Pic S999V99.
. . .
Accept A from Console
Compute B = Function Numval(A)
The input could then be:
1.23
-300
RELATED CONCEPTS
Formats for numeric data on page 47
Data format conversions on page 52
Unicode and the encoding of language characters on page 129
RELATED TASKS
Converting to or from national (Unicode) representation on page 137
RELATED REFERENCES
Conversions and precision on page 52
ARITH on page 309
Converting from one code page to another
You can nest the DISPLAY-OF and NATIONAL-OF intrinsic functions to easily convert
from any code page to any other code page.
118 Enterprise COBOL for z/OS, V5.2 Programming Guide
For example, the following code converts an EBCDIC string to an ASCII string:
77 EBCDIC-CCSID PIC 9(4) BINARY VALUE 1140.
77 ASCII-CCSID PIC 9(4) BINARY VALUE 819.
77 Input-EBCDIC PIC X(80).
77 ASCII-Output PIC X(80).
. . .
* Convert EBCDIC to ASCII
Move Function Display-of
(Function National-of (Input-EBCDIC EBCDIC-CCSID),
ASCII-CCSID)
to ASCII-output
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Converting to or from national (Unicode) representation on page 137
Evaluating data items (intrinsic functions)
You can use intrinsic functions to determine the ordinal position of a character in
the collating sequence, to find the largest or smallest item in a series, to find the
length of data item, or to determine when a program was compiled.
Use these intrinsic functions:
v CHAR and ORD to evaluate integers and single alphabetic or alphanumeric
characters with respect to the collating sequence used in a program
v MAX, MIN, ORD-MAX, and ORD-MIN to find the largest and smallest items in a series
of data items, including USAGE NATIONAL data items
v LENGTH to find the length of data items, including USAGE NATIONAL data items
v WHEN-COMPILED to find the date and time when a program was compiled
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
RELATED TASKS
Evaluating single characters for collating sequence
Finding the largest or smallest data item on page 120
Finding the length of data items on page 122
Finding the date of compilation on page 123
Evaluating single characters for collating sequence
To find out the ordinal position of a given alphabetic or alphanumeric character in
the collating sequence, use the ORD function with the character as the argument. ORD
returns an integer that represents that ordinal position.
You can use a one-character substring of a data item as the argument to ORD:
IF Function Ord(Customer-record(1:1)) IS > 194 THEN . . .
If you know the ordinal position in the collating sequence of a character, and want
to find the character that it corresponds to, use the CHAR function with the integer
ordinal position as the argument. CHAR returns the required character. For example:
INITIALIZE Customer-Name REPLACING ALPHABETIC BY Function Char(65)
Chapter 6. Handling strings 119
RELATED REFERENCES
CHAR (Enterprise COBOL Language Reference)
ORD (Enterprise COBOL Language Reference)
Finding the largest or smallest data item
To determine which of two or more alphanumeric, alphabetic, or national data
items has the largest value, use the MAX or ORD-MAX intrinsic function. To determine
which item has the smallest value, use MIN or ORD-MIN. These functions evaluate
according to the collating sequence.
To compare numeric items, including those that have USAGE NATIONAL, you can use
MAX, ORD-MAX, MIN, or ORD-MIN. With these intrinsic functions, the algebraic values of
the arguments are compared.
The MAX and MIN functions return the content of one of the arguments that you
supply. For example, suppose that your program has the following data
definitions:
05 Arg1 Pic x(10) Value "THOMASSON ".
05 Arg2 Pic x(10) Value "THOMAS ".
05 Arg3 Pic x(10) Value "VALLEJO ".
The following statement assigns VALLEJObbb to the first 10 character positions of
Customer-record, where b represents a blank space:
Move Function Max(Arg1 Arg2 Arg3) To Customer-record(1:10)
If you used MIN instead, then THOMASbbbb would be assigned.
The functions ORD-MAX and ORD-MIN return an integer that represents the ordinal
position (counting from the left) of the argument that has the largest or smallest
value in the list of arguments that you supply. If you used the ORD-MAX function in
the example above, the compiler would issue an error message because the
reference to a numeric function is not in a valid place. The following statement is a
valid use of ORD-MAX:
Compute x = Function Ord-max(Arg1 Arg2 Arg3)
The statement above assigns the integer 3 to x if the same arguments are used as
in the previous example. If you used ORD-MIN instead, the integer 2 would be
returned. The examples above might be more realistic if Arg1, Arg2, and Arg3 were
successive elements of an array (table).
If you specify a national item for any argument, you must specify all arguments as
class national.
RELATED TASKS
Performing arithmetic on page 55
Processing table items using intrinsic functions on page 89
Returning variable results with alphanumeric or national functions on page 121
RELATED REFERENCES
MAX (Enterprise COBOL Language Reference)
MIN (Enterprise COBOL Language Reference)
ORD-MAX (Enterprise COBOL Language Reference)
ORD-MIN (Enterprise COBOL Language Reference)
120 Enterprise COBOL for z/OS, V5.2 Programming Guide
Returning variable results with alphanumeric or national
functions
The results of alphanumeric or national functions could be of varying lengths and
values depending on the function arguments.
In the following example, the amount of data moved to R3 and the results of the
COMPUTE statement depend on the values and sizes of R1 and R2:
01 R1 Pic x(10) value "e".
01 R2 Pic x(05) value "f".
01 R3 Pic x(20) value spaces.
01 L Pic 99.
. . .
Move Function Max(R1 R2) to R3
Compute L = Function Length(Function Max(R1 R2))
This code has the following results:
v R2 is evaluated to be larger than R1.
v The string 'fbbbb' is moved to R3, where b represents a blank space. (The unfilled
character positions in R3 are padded with spaces.)
v L evaluates to the value 5.
If R1 contained 'g' instead of 'e', the code would have the following results:
v R1 would evaluate as larger than R2.
v The string 'gbbbbbbbbb' would be moved to R3. (The unfilled character positions
in R3 would be padded with spaces.)
v The value 10 would be assigned to L.
If a program uses national data for function arguments, the lengths and values of
the function results could likewise vary. For example, the following code is
identical to the fragment above, but uses national data instead of alphanumeric
data.
01 R1 Pic n(10) national value "e".
01 R2 Pic n(05) national value "f".
01 R3 Pic n(20) national value spaces.
01 L Pic 99 national.
. . .
Move Function Max(R1 R2) to R3
Compute L = Function Length(Function Max(R1 R2))
This code has the following results, which are similar to the first set of results
except that these are for national characters:
v R2 is evaluated to be larger than R1.
v The string NX"0066 0020 0020 0020 0020" (the equivalent in national characters
of 'fbbbb', where b represents a blank space), shown here in hexadecimal notation
with added spaces for readability, is moved to R3. The unfilled character
positions in R3 are padded with national spaces.
v L evaluates to the value 5, the length in national character positions of R2.
You might be dealing with variable-length output from alphanumeric or national
functions. Plan your program accordingly. For example, you might need to think
about using variable-length files when the records that you are writing could be of
different lengths:
File Section.
FD Output-File Recording Mode V.
01 Short-Customer-Record Pic X(50).
01 Long-Customer-Record Pic X(70).
Chapter 6. Handling strings 121
Working-Storage Section.
01 R1 Pic x(50).
01 R2 Pic x(70).
. . .
If R1 > R2
Write Short-Customer-Record from R1
Else
Write Long-Customer-Record from R2
End-if
RELATED TASKS
Finding the largest or smallest data item on page 120
Performing arithmetic on page 55
RELATED REFERENCES
MAX (Enterprise COBOL Language Reference)
Finding the length of data items
You can use the LENGTH function in many contexts (including tables and numeric
data) to determine the length of an item. For example, you can use the LENGTH
function to determine the length of an alphanumeric or national literal, or a data
item of any type except DBCS.
The LENGTH function returns the length of a national item (a literal, or any item that
has USAGE NATIONAL, including national group items) as an integer equal to the
length of the argument in national character positions. It returns the length of any
other data item as an integer equal to the length of the argument in alphanumeric
character positions.
The following COBOL statement demonstrates moving a data item into the field in
a record that holds customer names:
Move Customer-name To Customer-record(1:Function Length(Customer-name))
You can also use the LENGTH OF special register, which returns the length in bytes
even for national data. Coding either Function Length(Customer-name) or LENGTH
OF Customer-name returns the same result for alphanumeric items: the length of
Customer-name in bytes.
You can use the LENGTH function only where arithmetic expressions are allowed.
However, you can use the LENGTH OF special register in a greater variety of
contexts. For example, you can use the LENGTH OF special register as an argument
to an intrinsic function that accepts integer arguments. (You cannot use an intrinsic
function as an operand to the LENGTH OF special register.) You can also use the
LENGTH OF special register as a parameter in a CALL statement.
RELATED TASKS
Performing arithmetic on page 55
Creating variable-length tables (DEPENDING ON) on page 78
Processing table items using intrinsic functions on page 89
RELATED REFERENCES
LENGTH (Enterprise COBOL Language Reference)
LENGTH OF (Enterprise COBOL Language Reference)
122 Enterprise COBOL for z/OS, V5.2 Programming Guide
Finding the date of compilation
You can use the WHEN-COMPILED intrinsic function to determine when a program
was compiled. The 21-character result indicates the four-digit year, month, day, and
time (in hours, minutes, seconds, and hundredths of seconds) of compilation, and
the difference in hours and minutes from Greenwich mean time.
The first 16 positions are in the following format:
YYYYMMDDhhmmsshh
You can instead use the WHEN-COMPILED special register to determine the date and
time of compilation in the following format:
MM/DD/YYhh.mm.ss
The WHEN-COMPILED special register supports only a two-digit year, and does not
carry fractions of a second. You can use this special register only as the sending
field in a MOVE statement.
RELATED REFERENCES
WHEN-COMPILED (Enterprise COBOL Language Reference)
Chapter 6. Handling strings 123
124 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 7. Processing data in an international environment
Enterprise COBOL supports Unicode UTF-16 as national character data at run
time. UTF-16 provides a consistent and efficient way to encode plain text. Using
UTF-16, you can develop software that will work with various national languages.
Use these COBOL facilities to code and compile programs that process national
data:
v Data types and literals:
Character data types, defined with the USAGE NATIONAL clause and a PICTURE
clause that defines data of category national, national-edited, or
numeric-edited
Numeric data types, defined with the USAGE NATIONAL clause and a PICTURE
clause that defines a numeric data item (a national decimal item) or an external
floating-point data item (a national floating-point item)
National literals, specified with literal prefix N or NX
Figurative constant ALL national-literal
Figurative constants QUOTE, SPACE, HIGH-VALUE, LOW-VALUE, or ZERO, which have
national character (UTF-16) values when used in national-character contexts
v The COBOL statements shown in the related reference below about COBOL
statements and national data
v Intrinsic functions:
NATIONAL-OF to convert an alphanumeric or double-byte character set (DBCS)
character string to USAGE NATIONAL (UTF-16)
DISPLAY-OF to convert a national character string to USAGE DISPLAY in a
selected code page (EBCDIC, ASCII, EUC, or UTF-8)
The other intrinsic functions shown in the related reference below about
intrinsic functions and national data
v The GROUP-USAGE NATIONAL clause to define groups that contain only USAGE
NATIONAL data items and that behave like elementary category national items in
most operations
v Compiler options:
CODEPAGE to specify the code page to use for alphanumeric and DBCS data in
your program
NSYMBOL to control whether national or DBCS processing is used for the N
symbol in literals and PICTURE clauses
You can also take advantage of implicit conversions of alphanumeric or DBCS data
items to national representation. The compiler performs such conversions (in most
cases) when you move these items to national data items, or compare these items
with national data items.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
National groups on page 133
RELATED TASKS
Using national data (Unicode) in COBOL on page 130
Converting to or from national (Unicode) representation on page 137
Copyright IBM Corp. 1991, 2015 125
Processing UTF-8 data on page 141
Processing Chinese GB 18030 data on page 146
Comparing national (UTF-16) data on page 147
Coding for use of DBCS support on page 150
Appendix B, Converting double-byte character set (DBCS) data, on page 685
RELATED REFERENCES
COBOL statements and national data
Intrinsic functions and national data on page 128
CODEPAGE on page 313
NSYMBOL on page 338
Classes and categories of data (Enterprise COBOL Language Reference)
Data categories and PICTURE rules (Enterprise COBOL Language Reference)
MOVE statement (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
COBOL statements and national data
You can use national data with the PROCEDURE DIVISION and compiler-directing
statements shown in the table below.
Table 15. COBOL statements and national data
COBOL
statement Can be national Comment For more information
ACCEPT identifier-1, identifier-2 identifier-1 is converted Assigning input from a screen or file
from the native code page (ACCEPT) on page 34
specified in the CODEPAGE
compiler option only if
input is from CONSOLE.
ADD All identifiers can be Using COMPUTE and other
numeric items that have arithmetic statements on page 56
USAGE NATIONAL. identifier-3
(GIVING) can be
numeric-edited with USAGE
NATIONAL.
CALL identifier-2, identifier-3, Passing data on page 481
identifier-4, identifier-5;
literal-2, literal-3
COMPUTE identifier-1 can be numeric Using COMPUTE and other
or numeric-edited with arithmetic statements on page 56
USAGE NATIONAL.
arithmetic-expression can
contain numeric items that
have USAGE NATIONAL.
COPY . . . operand-1, operand-2 of the Chapter 18, Compiler-directing
REPLACING REPLACING phrase statements, on page 373
DISPLAY identifier-1 identifier-1 is converted to Displaying values on a screen or in a
EBCDIC only if the CONSOLE file (DISPLAY) on page 35
mnemonic-name is
specified directly or
indirectly.
126 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 15. COBOL statements and national data (continued)
COBOL
statement Can be national Comment For more information
DIVIDE All identifiers can be Using COMPUTE and other
numeric items that have arithmetic statements on page 56
USAGE NATIONAL. identifier-3
(GIVING) and identifier-4
(REMAINDER) can be
numeric-edited with USAGE
NATIONAL.
INITIALIZE identifier-1; identifier-2 or If you specify REPLACING Examples: initializing data items on
literal-1 of the REPLACING NATIONAL or REPLACING page 28
phrase NATIONAL-EDITED, identifier-2
or literal-1 must be valid as
a sending operand in a
move to identifier-1.
INSPECT All identifiers and literals. If any of these (other than Tallying and replacing data items
(identifier-2, the TALLYING identifier-2, the TALLYING (INSPECT) on page 115
integer data item, can have identifier) have USAGE
USAGE NATIONAL.) NATIONAL, all must be
national.
INVOKE Method-name as identifier-2 Invoking methods (INVOKE) on
or literal-1; identifier-3 or page 600
literal-2 in the BY VALUE
phrase
MERGE Merge keys The COLLATING SEQUENCE Setting sort or merge criteria on
phrase does not apply. page 227
MOVE Both the sender and Implicit conversions are Assigning values to elementary data
receiver, or only the performed for valid MOVE items (MOVE) on page 32
receiver operands.
Assigning values to group data items
(MOVE) on page 33
MULTIPLY All identifiers can be Using COMPUTE and other
numeric items that have arithmetic statements on page 56
USAGE NATIONAL. identifier-3
(GIVING) can be
numeric-edited with USAGE
NATIONAL.
SEARCH ALL Both the key data item and The key data item and its Doing a binary search (SEARCH
(binary search) its object of comparison object of comparison must ALL) on page 87
be compatible according to
the rules of comparison. If
the object of comparison is
of class national, the key
must be also.
SORT Sort keys The COLLATING SEQUENCE Setting sort or merge criteria on
phrase does not apply. page 227
STRING All identifiers and literals. If identifier-3, the receiving Joining data items (STRING) on
(identifier-4, the POINTER data item, is national, all page 105
integer data item, can have identifiers and literals
USAGE NATIONAL.) (other than identifier-4, the
POINTER identifier) must be
national.
Chapter 7. Processing data in an international environment 127
Table 15. COBOL statements and national data (continued)
COBOL
statement Can be national Comment For more information
SUBTRACT All identifiers can be Using COMPUTE and other
numeric items that have arithmetic statements on page 56
USAGE NATIONAL. identifier-3
(GIVING) can be
numeric-edited with USAGE
NATIONAL.
UNSTRING All identifiers and literals. If identifier-4, a receiving Splitting data items (UNSTRING) on
(identifier-6 and identifier-7, data item, has USAGE page 107
the COUNT and TALLYING NATIONAL, the sending data
integer data items, item and each delimiter
respectively, can have USAGE must have USAGE NATIONAL,
NATIONAL.) and each literal must be
national.
XML GENERATE identifier-1 (the generated Chapter 29, Producing XML output,
XML document); identifier-2 on page 561
(the source field or fields);
identifier-4 or literal-4 (the
namespace identifier);
identifier-5 or literal-5 (the
namespace prefix)
XML PARSE identifier-1 (the XML The XML-NTEXT special Chapter 28, Processing XML input,
document) register contains national on page 517
character document
fragments during parsing.
XML-NNAMESPACE and
XML-NNAMESPACE-PREFIX
special registers contain the
associated namespace
identifier and namespace
prefix, if any, in national
characters.
RELATED TASKS
Defining numeric data on page 43
Displaying numeric data on page 45
Using national data (Unicode) in COBOL on page 130
Comparing national (UTF-16) data on page 147
RELATED REFERENCES
CODEPAGE on page 313
Classes and categories of data (Enterprise COBOL Language Reference)
Intrinsic functions and national data
You can use arguments of class national with the intrinsic functions shown in the
table below.
Table 16. Intrinsic functions and national character data
Intrinsic function Function type For more information
DISPLAY-OF Alphanumeric Converting national to alphanumeric (DISPLAY-OF) on
page 139
LENGTH Integer Finding the length of data items on page 122
128 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 16. Intrinsic functions and national character data (continued)
Intrinsic function Function type For more information
LOWER-CASE, UPPER-CASE National Changing case (UPPER-CASE, LOWER-CASE) on page 117
NUMVAL, NUMVAL-C Numeric Converting to numbers (NUMVAL, NUMVAL-C) on page
117
MAX, MIN National Finding the largest or smallest data item on page 120
ORD-MAX, ORD-MIN Integer Finding the largest or smallest data item on page 120
REVERSE National Transforming to reverse order (REVERSE) on page 117
You can use national decimal arguments wherever zoned decimal arguments are
allowed. You can use national floating-point arguments wherever display
floating-point arguments are allowed. (See the related reference below about
arguments for a complete list of intrinsic functions that can take integer or numeric
arguments.)
RELATED TASKS
Defining numeric data on page 43
Using national data (Unicode) in COBOL on page 130
RELATED REFERENCES
Arguments (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Unicode and the encoding of language characters
Enterprise COBOL provides basic runtime support for Unicode, which can handle
tens of thousands of characters that cover all commonly used characters and
symbols in the world.
A character set is a defined set of characters, but is not associated with a coded
representation. A coded character set (also referred to in this documentation as a code
page) is a set of unambiguous rules that relate the characters of the set to their
coded representation. Each code page has a name and is like a table that sets up
the symbols for representing a character set; each symbol is associated with a
unique bit pattern, or code point. Each code page also has a coded character set
identifier (CCSID), which is a value from 1 to 65,536.
Unicode has several encoding schemes, called Unicode Transformation Format (UTF),
such as UTF-8, UTF-16, and UTF-32. Enterprise COBOL uses UTF-16 (CCSID 1200)
in big-endian format as the representation for national literals and data items that
have USAGE NATIONAL.
UTF-8 represents ASCII invariant characters a-z, A-Z, 0-9, and certain special
characters such as ' @ , . + - = / * ( ) the same way that they are represented in
ASCII. UTF-16 represents these characters as NX00nn, where Xnn is the
representation of the character in ASCII.
For example, the string ABC is represented in UTF-16 as NX004100420043. In
UTF-8, ABC is represented as X414243.
One or more encoding units are used to represent a character from a coded
character set. For UTF-16, an encoding unit takes 2 bytes of storage. Any character
Chapter 7. Processing data in an international environment 129
defined in any EBCDIC, ASCII, or EUC code page is represented in one UTF-16
encoding unit when the character is converted to the national data representation.
Cross-platform considerations: Enterprise COBOL and COBOL for AIX support
UTF-16 in big-endian format in national data. COBOL for Windows supports
UTF-16 in little-endian format (UTF-16LE) in national data. If you are porting
Unicode data that is encoded in UTF-16LE representation to Enterprise COBOL
from another platform, you must convert that data to UTF-16 in big-endian format
to process the data as national data.
RELATED TASKS
Converting to or from national (Unicode) representation on page 137
RELATED REFERENCES
Storage of character data on page 137
Character sets and code pages (Enterprise COBOL Language Reference)
Using national data (Unicode) in COBOL
In Enterprise COBOL, you can specify national (UTF-16) data in any of several
ways.
These types of national data are available:
v National data items (categories national, national-edited, and numeric-edited)
v National literals
v Figurative constants as national characters
v Numeric data items (national decimal and national floating-point)
In addition, you can define national groups that contain only data items that
explicitly or implicitly have USAGE NATIONAL, and that behave in the same way as
elementary category national data items in most operations.
These declarations affect the amount of storage that is needed.
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
National groups on page 133
RELATED TASKS
Defining national data items
Using national literals on page 131
Using national-character figurative constants on page 132
Defining national numeric data items on page 133
Using national groups on page 134
Converting to or from national (Unicode) representation on page 137
Comparing national (UTF-16) data on page 147
RELATED REFERENCES
Storage of character data on page 137
Classes and categories of data (Enterprise COBOL Language Reference)
Defining national data items
Define national data items with the USAGE NATIONAL clause to hold national
(UTF-16) character strings.
130 Enterprise COBOL for z/OS, V5.2 Programming Guide
You can define national data items of the following categories:
v National
v National-edited
v Numeric-edited
To define a category national data item, code a PICTURE clause that contains only
one or more PICTURE symbols N.
To define a national-edited data item, code a PICTURE clause that contains at least
one of each of the following symbols:
v Symbol N
v Simple insertion editing symbol B, 0, or /
To define a numeric-edited data item of class national, code a PICTURE clause that
defines a numeric-edited item (for example, -$999.99) and code a USAGE NATIONAL
clause. You can use a numeric-edited data item that has USAGE NATIONAL in the
same way that you use a numeric-edited item that has USAGE DISPLAY.
You can also define a data item as numeric-edited by coding the BLANK WHEN ZERO
clause for an elementary item that is defined as numeric by its PICTURE clause.
If you code a PICTURE clause but do not code a USAGE clause for data items that
contain only one or more PICTURE symbols N, you can use the compiler option
NSYMBOL(NATIONAL) to ensure that such items are treated as national data items
instead of as DBCS items.
RELATED TASKS
Displaying numeric data on page 45
RELATED REFERENCES
NSYMBOL on page 338
BLANK WHEN ZERO clause (Enterprise COBOL Language Reference)
Using national literals
To specify national literals, use the prefix character N and compile with the option
NSYMBOL(NATIONAL).
You can use either of these notations:
v N"character-data"
v Ncharacter-data
If you compile with the option NSYMBOL(DBCS), the literal prefix character N
specifies a DBCS literal, not a national literal.
To specify a national literal as a hexadecimal value, use the prefix NX. You can use
either of these notations:
v NX"hexadecimal-digits"
v NXhexadecimal-digits
Each of the following MOVE statements sets the national data item Y to the UTF-16
value of the characters 'AB':
Chapter 7. Processing data in an international environment 131
01 Y pic NN usage national.
. . .
Move NX"00410042" to Y
Move N"AB" to Y
Move "AB" to Y
Do not use alphanumeric hexadecimal literals in contexts that call for national
literals, because such usage is easily misunderstood. For example, the following
statement also results in moving the UTF-16 characters 'AB' (not the hexadecimal bit
pattern C1C2) to Y, where Y is defined as USAGE NATIONAL:
Move X"C1C2" to Y
You cannot use national literals in the SPECIAL-NAMES paragraph or as
program-names. You can use a national literal to name an object-oriented method
in the METHOD-ID paragraph or to specify a method-name in an INVOKE statement.
RELATED TASKS
Using literals on page 25
RELATED REFERENCES
NSYMBOL on page 338
National literals (Enterprise COBOL Language Reference)
Using national-character figurative constants
You can use the figurative constant ALL national-literal in a context that requires
national characters. ALL national-literal represents all or part of the string that is
generated by successive concatenations of the encoding units that make up the
national literal.
You can use the figurative constants QUOTE, SPACE, HIGH-VALUE, LOW-VALUE, or ZERO
in a context that requires national characters, such as a MOVE statement, an implicit
move, or a relation condition that has national operands. In these contexts, the
figurative constant represents a national-character (UTF-16) value.
When you use the figurative constant HIGH-VALUE in a context that requires
national characters, its value is NXFFFF. When you use LOW-VALUE in a context
that requires national characters, its value is NX0000.
Restrictions: You must not use HIGH-VALUE or the value assigned from HIGH-VALUE
in a way that results in conversion of the value from one data representation to
another (for example, between USAGE DISPLAY and USAGE NATIONAL). XFF (the
value of HIGH-VALUE in an alphanumeric context when the EBCDIC collating
sequence is being used) does not represent a valid EBCDIC character, and NXFFFF
does not represent a valid national character. Conversion of such a value to
another representation results in a substitution character being used (not XFF or
NXFFFF). Consider the following example:
01 natl-data PIC NN Usage National.
01 alph-data PIC XX.
. . .
MOVE HIGH-VALUE TO natl-data, alph-data
IF natl-data = alph-data. . .
The IF statement above evaluates as false even though each of its operands was set
to HIGH-VALUE. Before an elementary alphanumeric operand is compared to a
national operand, the alphanumeric operand is treated as though it were moved to
a temporary national data item, and the alphanumeric characters are converted to
132 Enterprise COBOL for z/OS, V5.2 Programming Guide
the corresponding national characters. When XFF is converted to UTF-16,
however, the UTF-16 item gets a substitution character value and so does not
compare equally to NXFFFF.
RELATED TASKS
Converting to or from national (Unicode) representation on page 137
Comparing national (UTF-16) data on page 147
RELATED REFERENCES
Figurative constants (Enterprise COBOL Language Reference)
DISPLAY-OF (Enterprise COBOL Language Reference)
Support for Unicode: Using Unicode Services
Defining national numeric data items
Define data items with the USAGE NATIONAL clause to hold numeric data that is
represented in national characters (UTF-16). You can define national decimal items
and national floating-point items.
To define a national decimal item, code a PICTURE clause that contains only the
symbols 9, P, S, and V. If the PICTURE clause contains S, the SIGN IS SEPARATE
clause must be in effect for that item.
To define a national floating-point item, code a PICTURE clause that defines a
floating-point item (for example, +99999.9E-99).
You can use national decimal items in the same way that you use zoned decimal
items. You can use national floating-point items in the same way that you use
display floating-point items.
RELATED TASKS
Defining numeric data on page 43
Displaying numeric data on page 45
RELATED REFERENCES
SIGN clause (Enterprise COBOL Language Reference)
National groups
National groups, which are specified either explicitly or implicitly with the
GROUP-USAGE NATIONAL clause, contain only data items that have USAGE NATIONAL. In
most cases, a national group item is processed as though it were redefined as an
elementary category national item described as PIC N(m), where m is the number
of national (UTF-16) characters in the group.
For some operations on national groups, however (just as for some operations on
alphanumeric groups), group semantics apply. Such operations (for example, MOVE
CORRESPONDING and INITIALIZE) recognize or process the elementary items within
the national group.
Where possible, use national groups instead of alphanumeric groups that contain
USAGE NATIONAL items. National groups provide several advantages for the
processing of national data compared to the processing of national data within
alphanumeric groups:
v When you move a national group to a longer data item that has USAGE NATIONAL,
the receiving item is padded with national characters. By contrast, if you move
an alphanumeric group that contains national characters to a longer
Chapter 7. Processing data in an international environment 133
alphanumeric group that contains national characters, alphanumeric spaces are
used for padding. As a result, mishandling of data items could occur.
v When you move a national group to a shorter data item that has USAGE
NATIONAL, the national group is truncated at national-character boundaries. By
contrast, if you move an alphanumeric group that contains national characters to
a shorter alphanumeric group that contains national characters, truncation might
occur between the 2 bytes of a national character.
v When you move a national group to a national-edited or numeric-edited item,
the content of the group is edited. By contrast, if you move an alphanumeric
group to an edited item, no editing takes place.
v When you use a national group as an operand in a STRING, UNSTRING, or INSPECT
statement:
The group content is processed as national characters rather than as
single-byte characters.
TALLYING and POINTER operands operate at the logical level of national
characters.
The national group operand is supported with a mixture of other national
operand types.
By contrast, if you use an alphanumeric group that contains national characters
in these contexts, the characters are processed byte by byte. As a result, invalid
handling or corruption of data could occur.
USAGE NATIONAL groups: A group item can specify the USAGE NATIONAL clause at the
group level as a convenient shorthand for the USAGE of each of the elementary data
items within the group. Such a group is not a national group, however, but an
alphanumeric group, and behaves in many operations, such as moves and
compares, like an elementary data item of USAGE DISPLAY (except that no editing or
conversion of data occurs).
RELATED TASKS
Assigning values to group data items (MOVE) on page 33
Joining data items (STRING) on page 105
Splitting data items (UNSTRING) on page 107
Tallying and replacing data items (INSPECT) on page 115
Using national groups
RELATED REFERENCES
GROUP-USAGE clause (Enterprise COBOL Language Reference)
Using national groups
To define a group data item as a national group, code a GROUP-USAGE NATIONAL
clause at the group level for the item. The group can contain only data items that
explicitly or implicitly have USAGE NATIONAL.
The following data description entry specifies that a level-01 group and its
subordinate groups are national group items:
01 Nat-Group-1 GROUP-USAGE NATIONAL.
02 Group-1.
04 Month PIC 99.
04 DayOf PIC 99.
04 Year PIC 9999.
02 Group-2 GROUP-USAGE NATIONAL.
04 Amount PIC 9(4).99 USAGE NATIONAL.
134 Enterprise COBOL for z/OS, V5.2 Programming Guide
In the example above, Nat-Group-1 is a national group, and its subordinate groups
Group-1 and Group-2 are also national groups. A GROUP-USAGE NATIONAL clause is
implied for Group-1, and USAGE NATIONAL is implied for the subordinate items in
Group-1. Month, DayOf, and Year are national decimal items, and Amount is a
numeric-edited item that has USAGE NATIONAL.
You can subordinate national groups within alphanumeric groups as in the
following example:
01 Alpha-Group-1.
02 Group-1.
04 Month PIC 99.
04 DayOf PIC 99.
04 Year PIC 9999.
02 Group-2 GROUP-USAGE NATIONAL.
04 Amount PIC 9(4).99.
In the example above, Alpha-Group-1 and Group-1 are alphanumeric groups; USAGE
DISPLAY is implied for the subordinate items in Group-1. (If Alpha-Group-1 specified
USAGE NATIONAL at the group level, USAGE NATIONAL would be implied for each of
the subordinate items in Group-1. However, Alpha-Group-1 and Group-1 would be
alphanumeric groups, not national groups, and would behave like alphanumeric
groups during operations such as moves and compares.) Group-2 is a national
group, and USAGE NATIONAL is implied for the numeric-edited item Amount.
You cannot subordinate alphanumeric groups within national groups. All
elementary items within a national group must be explicitly or implicitly described
as USAGE NATIONAL, and all group items within a national group must be explicitly
or implicitly described as GROUP-USAGE NATIONAL.
RELATED CONCEPTS
National groups on page 133
RELATED TASKS
Using national groups as elementary items
Using national groups as group items on page 136
RELATED REFERENCES
GROUP-USAGE clause (Enterprise COBOL Language Reference)
Using national groups as elementary items
In most cases, you can use a national group as though it were an elementary data
item.
In the following example, a national group item, Group-1, is moved to a
national-edited item, Edited-date. Because Group-1 is treated as an elementary
data item during the move, editing takes place in the receiving data item. The
value in Edited-date after the move is 06/23/2010 in national characters.
01 Edited-date PIC NN/NN/NNNN USAGE NATIONAL.
01 Group-1 GROUP-USAGE NATIONAL.
02 Month PIC 99 VALUE 06.
02 DayOf PIC 99 VALUE 23.
02 Year PIC 9999 VALUE 2010.
. . .
MOVE Group-1 to Edited-date.
If Group-1 were instead an alphanumeric group in which each of its subordinate
items had USAGE NATIONAL (specified either explicitly with a USAGE NATIONAL clause
on each elementary item, or implicitly with a USAGE NATIONAL clause at the group
Chapter 7. Processing data in an international environment 135
level), a group move, rather than an elementary move, would occur. Neither
editing nor conversion would take place during the move. The value in the first
eight character positions of Edited-date after the move would be 06232010 in
national characters, and the value in the remaining two character positions would
be 4 bytes of alphanumeric spaces.
RELATED TASKS
Assigning values to group data items (MOVE) on page 33
Comparing national data and alphanumeric-group operands on page 149
Using national groups as group items
RELATED REFERENCES
MOVE statement (Enterprise COBOL Language Reference)
Using national groups as group items
In some cases when you use a national group, it is handled with group semantics;
that is, the elementary items in the group are recognized or processed.
In the following example, an INITIALIZE statement that acts upon national group
item Group-OneN causes the value 15 in national characters to be moved to only the
numeric items in the group:
01 Group-OneN Group-Usage National.
05 Trans-codeN Pic N Value "A".
05 Part-numberN Pic NN Value "XX".
05 Trans-quanN Pic 99 Value 10.
. . .
Initialize Group-OneN Replacing Numeric Data By 15
Because only Trans-quanN in Group-OneN above is numeric, only Trans-quanN
receives the value 15. The other subordinate items are unchanged.
The table below summarizes the cases where national groups are processed with
group semantics.
Table 17. National group items that are processed with group semantics
Language feature Uses of national group items Comment
CORRESPONDING phrase Specify a national group item for Elementary items within the
of the ADD, SUBTRACT, processing as a group in national group are processed
or MOVE statement accordance with the rules of the like elementary items that
CORRESPONDING phrase. have USAGE NATIONAL within
an alphanumeric group.
Host variable in EXEC Specify a national group item as a The national group item is in
SQL statement host variable. effect shorthand for the set of
host variables that are
subordinate to the group item.
INITIALIZE statement Specify a national group for Elementary items within the
processing as a group in national group are initialized
accordance with the rules of the like elementary items that
INITIALIZE statement. have USAGE NATIONAL within
an alphanumeric group.
Name qualification Use the name of a national group Follow the same rules for
item to qualify the names of qualification as for an
elementary data items and of alphanumeric group.
subordinate group items in the
national group.
136 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 17. National group items that are processed with group semantics (continued)
Language feature Uses of national group items Comment
THROUGH phrase of the To specify a national group item in The result is an alphanumeric
RENAMES clause the THROUGH phrase, use the same group item.
rules as for an alphanumeric group
item.
FROM phrase of the Specify a national group item in Elementary items within the
XML GENERATE the FROM phrase for processing as a national group are processed
statement group in accordance with the rules like elementary items that
of the XML GENERATE statement. have USAGE NATIONAL within
an alphanumeric group.
RELATED TASKS
Initializing a structure (INITIALIZE) on page 30
Initializing a table (INITIALIZE) on page 73
Assigning values to elementary data items (MOVE) on page 32
Assigning values to group data items (MOVE) on page 33
Finding the length of data items on page 122
Generating XML output on page 561
Using national group items in SQL statements on page 434
RELATED REFERENCES
Qualification (Enterprise COBOL Language Reference)
RENAMES clause (Enterprise COBOL Language Reference)
Storage of character data
Use the table below to compare alphanumeric (DISPLAY), DBCS (DISPLAY-1), and
Unicode (NATIONAL) encoding and to plan storage usage.
Table 18. Encoding and size of alphanumeric, DBCS, and national data
Characteristic DISPLAY DISPLAY-1 NATIONAL
Character encoding unit 1 byte 2 bytes 2 bytes
Code page EBCDIC EBCDIC DBCS UTF-16BE1
Encoding units per graphic 1 1 1 or 22
character
Bytes per graphic character 1 byte 2 bytes 2 or 4 bytes
1. Use the CODEPAGE compiler option to specify the EBCDIC code page that is applicable to
alphanumeric or DBCS data.
2. Most characters are represented in UTF-16 using one encoding unit. In particular, the
following characters are represented using a single UTF-16 encoding unit per character:
v COBOL characters A-Z, a-z, 0-9, space, + - * / = $ , ; . " ( ) > < :'
v All characters that are converted from an EBCDIC or ASCII code page
RELATED CONCEPTS
Unicode and the encoding of language characters on page 129
Converting to or from national (Unicode) representation
You can implicitly or explicitly convert data items to national (UTF-16)
representation.
Chapter 7. Processing data in an international environment 137
You can implicitly convert alphabetic, alphanumeric, DBCS, or integer data to
national data by using the MOVE statement. Implicit conversions also take place in
other COBOL statements, such as IF statements that compare an alphanumeric
data item with a data item that has USAGE NATIONAL.
You can explicitly convert to and from national data items by using the intrinsic
functions NATIONAL-OF and DISPLAY-OF, respectively. By using these intrinsic
functions, you can specify a code page for the conversion that is different from the
code page that is in effect with the CODEPAGE compiler option.
RELATED TASKS
Converting alphanumeric, DBCS, and integer to national (MOVE)
Converting alphanumeric or DBCS to national (NATIONAL-OF) on page 139
Converting national to alphanumeric (DISPLAY-OF) on page 139
Overriding the default code page on page 140
Comparing national (UTF-16) data on page 147
RELATED REFERENCES
CODEPAGE on page 313
Conversion exceptions on page 140
Converting alphanumeric, DBCS, and integer to national
(MOVE)
You can use a MOVE statement to implicitly convert data to national representation.
You can move the following kinds of data to category national or national-edited
data items, and thus convert the data to national representation:
v Alphabetic
v Alphanumeric
v Alphanumeric-edited
v DBCS
v Integer of USAGE DISPLAY
v Numeric-edited of USAGE DISPLAY
You can likewise move the following kinds of data to numeric-edited data items
that have USAGE NATIONAL:
v Alphanumeric
v Display floating-point (floating-point of USAGE DISPLAY)
v Numeric-edited of USAGE DISPLAY
v Integer of USAGE DISPLAY
For complete rules about moves to national data, see the related reference about
the MOVE statement.
For example, the MOVE statement below moves the alphanumeric literal "AB" to the
national data item UTF16-Data:
01 UTF16-Data Pic N(2) Usage National.
. . .
Move "AB" to UTF16-Data
After the MOVE statement above, UTF16-Data contains NX00410042, the national
representation of the alphanumeric characters 'AB'.
138 Enterprise COBOL for z/OS, V5.2 Programming Guide
If padding is required in a receiving data item that has USAGE NATIONAL, the default
UTF-16 space character (NX0020) is used. If truncation is required, it occurs at the
boundary of a national-character position.
RELATED TASKS
Assigning values to elementary data items (MOVE) on page 32
Assigning values to group data items (MOVE) on page 33
Displaying numeric data on page 45
Coding for use of DBCS support on page 150
RELATED REFERENCES
MOVE statement (Enterprise COBOL Language Reference)
Converting alphanumeric or DBCS to national (NATIONAL-OF)
Use the NATIONAL-OF intrinsic function to convert alphabetic, alphanumeric, or
DBCS data to a national data item. Specify the source code page as the second
argument if the source is encoded in a different code page than is in effect with the
CODEPAGE compiler option.
Example: converting to and from national data on page 140
RELATED TASKS
Processing UTF-8 data on page 141
Processing Chinese GB 18030 data on page 146
Processing alphanumeric data items that contain DBCS data on page 152
RELATED REFERENCES
CODEPAGE on page 313
NATIONAL-OF (Enterprise COBOL Language Reference)
Converting national to alphanumeric (DISPLAY-OF)
Use the DISPLAY-OF intrinsic function to convert national data to an alphanumeric
(USAGE DISPLAY) character string that is represented in a code page that you specify
as the second argument.
If you omit the second argument, the output code page is the one that was in
effect with the CODEPAGE compiler option when the source was compiled.
If you specify an EBCDIC or ASCII code page that combines single-byte character
set (SBCS) and DBCS characters, the returned string might contain a mixture of
SBCS and DBCS characters. The DBCS substrings are delimited by shift-in and
shift-out characters if the code page in effect for the function is an EBCDIC code
page.
Example: converting to and from national data on page 140
RELATED TASKS
Processing UTF-8 data on page 141
Processing Chinese GB 18030 data on page 146
RELATED REFERENCES
DISPLAY-OF (Enterprise COBOL Language Reference)
Chapter 7. Processing data in an international environment 139
Overriding the default code page
In some cases, you might need to convert data to or from a code page that differs
from the CCSID that is specified as the CODEPAGE option value. To do so, convert
the item by using a conversion function in which you explicitly specify the code
page.
If you specify a code page as an argument to the DISPLAY-OF intrinsic function, and
the code page differs from the code page that is in effect with the CODEPAGE
compiler option, do not use the function result in any operations that involve
implicit conversion (such as an assignment to, or comparison with, a national data
item). Such operations assume the EBCDIC code page that is specified with the
CODEPAGE compiler option.
RELATED REFERENCES
CODEPAGE on page 313
Conversion exceptions
Implicit or explicit conversion between national data and alphanumeric data can
fail and generate a severity-3 Language Environment condition.
Failure can occur if the code page that you specified implicitly or explicitly is not a
valid code page.
A character that does not have a counterpart in the target CCSID does not result in
a conversion exception. Such a character is converted to a substitution character in
the target code page.
RELATED REFERENCES
CODEPAGE on page 313
Example: converting to and from national data
The following example shows the NATIONAL-OF and DISPLAY-OF intrinsic functions
and the MOVE statement for converting to and from national (UTF-16) data items. It
also demonstrates the need for explicit conversions when you operate on strings
that are encoded in multiple code pages.
CBL CODEPAGE(00037)
* . . .
01 Data-in-Unicode pic N(100) usage national.
01 Data-in-Greek pic X(100).
01 other-data-in-US-English pic X(12) value "PRICE in $ =".
* . . .
Read Greek-file into Data-in-Greek
Move function National-of(Data-in-Greek, 00875)
to Data-in-Unicode
* . . . process Data-in-Unicode here . . .
Move function Display-of(Data-in-Unicode, 00875)
to Data-in-Greek
Write Greek-record from Data-in-Greek
The example above works correctly because the input code page is specified.
Data-in-Greek is converted as data represented in CCSID 00875 (Greek). However,
the following statement results in an incorrect conversion unless all the characters
in the item happen to be among those that have a common representation in both
the Greek and the English code pages:
Move Data-in-Greek to Data-in-Unicode
140 Enterprise COBOL for z/OS, V5.2 Programming Guide
The MOVE statement above converts Data-in-Greek to Unicode representation based
on the CCSID 00037 (U.S. English) to UTF-16 conversion. This conversion does not
produce the expected results because Data-in-Greek is encoded in CCSID 00875.
If you can correctly set the CODEPAGE compiler option to CCSID 00875 (that is, the
rest of your program also handles EBCDIC data in Greek), you can code the same
example correctly as follows:
CBL CODEPAGE(00875)
* . . .
01 Data-in-Unicode pic N(100) usage national.
01 Data-in-Greek pic X(100).
* . . .
Read Greek-file into Data-in-Greek
* . . . process Data-in-Greek here ...
* . . . or do the following (if need to process data in Unicode):
Move Data-in-Greek to Data-in-Unicode
* . . . process Data-in-Unicode
Move function Display-of(Data-in-Unicode) to Data-in-Greek
Write Greek-record from Data-in-Greek
Processing UTF-8 data
To process UTF-8 data, first convert the UTF-8 data to UTF-16 in a national data
item. After processing the national data, convert it back to UTF-8 for output. For
the conversions, use the intrinsic functions NATIONAL-OF and DISPLAY-OF,
respectively. Use code page 1208 for UTF-8 data.
National data is encoded in UTF-16, which uses one encoding unit for almost all
commonly encountered characters. With this property, you can use string
operations such as reference modification on the national data. If it is more
convenient to retain the UTF-8 encoding, use the Unicode intrinsic functions to
assist with processing the data. For details, see Using intrinsic functions to
process UTF-8 encoded data on page 142.
Take the following steps to convert ASCII or EBCDIC data to UTF-8:
1. Use the function NATIONAL-OF to convert the ASCII or EBCDIC string to a
national (UTF-16) string.
2. Use the function DISPLAY-OF to convert the national string to UTF-8.
The following example converts Greek EBCDIC data to UTF-8:
Usage note: Use care if you use reference modification to refer to data encoded in
UTF-8. UTF-8 characters are encoded with a varying number of bytes per
character. Avoid operations that might split a multibyte character.
RELATED TASKS
Referring to substrings of data items on page 111
Converting to or from national (Unicode) representation on page 137
Parsing XML documents encoded in UTF-8 on page 541
Using intrinsic functions to process UTF-8 encoded data on page 142
Chapter 7. Processing data in an international environment 141
Using intrinsic functions to process UTF-8 encoded data
If it is more convenient to keep your data encoded in UTF-8, use the Unicode
intrinsic functions to facilitate testing and processing the UTF-8 data.
You can use the following intrinsic functions:
UVALID To verify that the UTF-8 character data is well-formed
USUPPLEMENTARY
If the data is to be converted to national, and it is important that every
character can be represented by a single 16-bit encoding unit, use the
USUPPLEMENTARY function to determine whether a valid UTF-8 character
string contains a Unicode supplementary code point; that is, a code point
with a Unicode scalar value above U+FFFF, requiring a 4-byte
representation in UTF-8.
USUBSTR
It provides a convenient alternative to reference modification for referring
to substrings of the UTF-8 character string. USUBSTR expects character
position and length arguments versus the computed byte locations and
counts required by reference modification.
Auxiliary functions can provide additional information about a valid UTF-8
character string:
ULENGTH
To determine the total number of Unicode code points in the string
UPOS To determine the byte position in the string of the nth Unicode code point
UWIDTH To determine the width in bytes of the nth Unicode code point in the
string
The following code fragment illustrates UTF-8 validity checking, and the use of the
auxiliary functions:
checkUTF-8-validity.
Compute u = function UVALID(UTF-8-testStr)
If u not = 0
Display checkUTF-8-validity failure:
Display The UTF-8 representation is not valid,
starting at byte u .
Compute v = function ULENGTH(UTF-8-testStr(1:u - 1))
Compute u = function UPOS(UTF-8-testStr v)
Compute w = function UWIDTH(UTF-8-testStr v)
Display The v th and last valid code point starts
at byte u for w bytes.
End-if.
In the following string, the sequence that starts with x'F5' is not valid UTF-8
because no byte can have a value in the range x'F5' to x'FF':
x6162D0B0E4BA8CF5646364
The output from checkUTF-8-validity for this string is as follows:
checkUTF-8-validity failure:
The UTF-8 representation is not valid, starting at byte 08.
The 04th and last valid code point starts at byte 05 for 03 bytes.
The following code fragment illustrates checking for the presence of a Unicode
supplementary code point, requiring a 4-byte representation in UTF-8:
142 Enterprise COBOL for z/OS, V5.2 Programming Guide
checkUTF-8-supp.
Compute u = function USUPPLEMENTARY(UTF-8-testStr)
If u not = 0
Display checkUTF-8-supp hit:
Compute v = function ULENGTH(UTF-8-testStr(1:u - 1))
Compute w = function UWIDTH(UTF-8-testStr v + 1)
Display The v th code point of the string
, starting at byte u ,
Display is a Unicode supplementary code point,
width w bytes.
End-if.
In the following string, the sequence x'F0908C82' is a supplementary character (as
is any valid UTF-8 sequence beginning with a byte in the range x'F0' to x'F4'):
x6162D0B0E4BA8CF0908C826364
The output from checkUTF-8-supp for this string is as follows:
checkUTF-8-supp hit:
The 04th code point of the string, starting at byte 08,
is a Unicode supplementary code point, width 04 bytes.
RELATED REFERENCES
CODEPAGE on page 313
Example: deriving initials from UTF-8 names
The following program uses the Unicode functions to derive composers initials
from a table of names in Czech. It is intended to illustrate these functions, and is
not necessarily the most efficient way of doing the task. Although the program
processes the composer names in UTF-8, the data begins and ends in EBCDIC in
order to permit a meaningful display of the program source and output. The
compiler option CODEPAGE(1153) ensures that the names are interpreted correctly
when translated to and from Unicode.
Chapter 7. Processing data in an international environment 143
Program initials
144 Enterprise COBOL for z/OS, V5.2 Programming Guide
Program initials, continued
Output from program initials
Compute composer initials...
#1: ALD (x414C44)
#2: LJ (x4C4A)
#3: RJK (x524A4B)
#4: PK (x504B)
#5: JVHV (x4A564856)
Chapter 7. Processing data in an international environment 145
Program toHex
Identification division.
Program-id. toHex.
Data division.
Working-storage section.
1 hexv.
2 pic x(32) value 000102030405060708090A0B0C0D0E0F.
2 pic x(32) value 101112131415161718191A1B1C1D1E1F.
2 pic x(32) value 202122232425262728292A2B2C2D2E2F.
2 pic x(32) value 303132333435363738393A3B3C3D3E3F.
2 pic x(32) value 404142434445464748494A4B4C4D4E4F.
2 pic x(32) value 505152535455565758595A5B5C5D5E5F.
2 pic x(32) value 606162636465666768696A6B6C6D6E6F.
2 pic x(32) value 707172737475767778797A7B7C7D7E7F.
2 pic x(32) value 808182838485868788898A8B8C8D8E8F.
2 pic x(32) value 909192939495969798999A9B9C9D9E9F.
2 pic x(32) value A0A1A2A3A4A5A6A7A8A9AAABACADAEAF.
2 pic x(32) value B0B1B2B3B4B5B6B7B8B9BABBBCBDBEBF.
2 pic x(32) value C0C1C2C3C4C5C6C7C8C9CACBCCCDCECF.
2 pic x(32) value D0D1D2D3D4D5D6D7D8D9DADBDCDDDEDF.
2 pic x(32) value E0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF.
2 pic x(32) value F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF.
1 redefines hexv.
2 hex pic xx occurs 256 times.
Local-storage section.
1 i pic 9(4) binary.
1 j pic 9(4) binary value 0.
1 jx redefines j.
2 pic x.
2 jxd pic x.
Linkage section.
1 ostr.
2 ostrv pic xx occurs 1024 times.
1 istr.
2 istrv pic x occurs 1024 times.
1 len pic 9(9) binary.
Procedure division using ostr istr value len.
If len > 1024
Display >> Error: length len greater than toHex
supported maximum of 1024.
Stop run
End-if
Perform with test before varying i from 1 by 1 until i > len
Move 0 to j
Move istrv(i) to jxd
Add 1 to j
Move hex(j) to ostrv(i)
End-perform
Goback
.
End program toHex.
Processing Chinese GB 18030 data
GB 18030 is a national-character standard specified by the government of the
People's Republic of China.
GB 18030 characters can be encoded in either UTF-16 or in code page CCSID 1392.
Code page 1392 is an ASCII multibyte code page that uses 1, 2, or 4 bytes per
character. A subset of the GB 18030 characters can be encoded in the Chinese ASCII
code page, CCSID 1386, or in the Chinese EBCDIC code page, CCSID 1388.
Enterprise COBOL does not have explicit support for GB 18030, but does support
the processing of GB 18030 characters in several ways. You can:
146 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Use DBCS data items to process GB 18030 characters that are represented in
CCSID 1388.
v Use national data items to define and process GB 18030 characters that are
represented in UTF-16, CCSID 01200.
v Process data in any code page (including CCSID 1388 or 1392) by converting the
data to UTF-16, processing the UTF-16 data, and then converting the data back
to the original code-page representation.
When you need to process Chinese GB 18030 data that requires conversion, first
convert the input data to UTF-16 in a national data item. After you process the
national data item, convert it back to Chinese GB 18030 for output. For the
conversions, use the intrinsic functions NATIONAL-OF and DISPLAY-OF, respectively,
and specify code page 1388 or 1392 as the second argument of each function.
The following example illustrates these conversions:
RELATED TASKS
Converting to or from national (Unicode) representation on page 137
Coding for use of DBCS support on page 150
RELATED REFERENCES
Storage of character data on page 137
Comparing national (UTF-16) data
You can compare national (UTF-16) data, that is, national literals and data items
that have USAGE NATIONAL (whether of class national or class numeric), explicitly or
implicitly with other kinds of data in relation conditions.
You can code conditional expressions that use national data in the following
statements:
v EVALUATE
v IF
v INSPECT
v PERFORM
v SEARCH
v STRING
v UNSTRING
For full details about comparing national data items to other data items, see the
related references.
RELATED TASKS
Comparing two class national operands on page 148
Comparing class national and class numeric operands on page 148
Comparing national numeric and other numeric operands on page 149
Chapter 7. Processing data in an international environment 147
Comparing national and other character-string operands on page 149
Comparing national data and alphanumeric-group operands on page 149
RELATED REFERENCES
Relation conditions (Enterprise COBOL Language Reference)
General relation conditions (Enterprise COBOL Language Reference)
National comparisons (Enterprise COBOL Language Reference)
Group comparisons (Enterprise COBOL Language Reference)
Comparing two class national operands
You can compare the character values of two operands of class national.
Either operand (or both) can be any of the following types of items:
v A national group
v An elementary category national or national-edited data item
v A numeric-edited data item that has USAGE NATIONAL
One of the operands can instead be a national literal or a national intrinsic
function.
When you compare two class national operands that have the same length, they
are determined to be equal if all pairs of the corresponding characters are equal.
Otherwise, comparison of the binary values of the first pair of unequal characters
determines the operand with the larger binary value.
When you compare operands that have unequal lengths, the shorter operand is
treated as if it were padded on the right with default UTF-16 space characters
(NX0020) to the length of the longer operand.
The PROGRAM COLLATING SEQUENCE clause does not affect the comparison of two
class national operands.
RELATED CONCEPTS
National groups on page 133
RELATED TASKS
Using national groups on page 134
RELATED REFERENCES
National comparisons (Enterprise COBOL Language Reference)
Comparing class national and class numeric operands
You can compare national literals or class national data items to integer literals or
numeric data items that are defined as integer (that is, national decimal items or
zoned decimal items). At most one of the operands can be a literal.
You can also compare national literals or class national data items to floating-point
data items (that is, display floating-point or national floating-point items).
Numeric operands are converted to national (UTF-16) representation if they are not
already in national representation. A comparison is made of the national character
values of the operands.
148 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
General relation conditions (Enterprise COBOL Language Reference)
Comparing national numeric and other numeric operands
National numeric operands (national decimal and national floating-point operands)
are data items of class numeric that have USAGE NATIONAL.
You can compare the algebraic values of numeric operands regardless of their
USAGE. Thus you can compare a national decimal item or a national floating-point
item with a binary item, an internal-decimal item, a zoned decimal item, a display
floating-point item, or any other numeric item.
RELATED TASKS
Defining national numeric data items on page 133
RELATED REFERENCES
General relation conditions (Enterprise COBOL Language Reference)
Comparing national and other character-string operands
You can compare the character value of a national literal or class national data item
with the character value of any of the following other character-string operands:
alphabetic, alphanumeric, alphanumeric-edited, DBCS, or numeric-edited of USAGE
DISPLAY.
These operands are treated as if they were moved to an elementary national data
item. The characters are converted to national (UTF-16) representation, and the
comparison proceeds with two national character operands.
RELATED TASKS
Using national-character figurative constants on page 132
RELATED REFERENCES
National comparisons (Enterprise COBOL Language Reference)
Comparing national data and alphanumeric-group operands
You can compare a national literal, a national group item, or any elementary data
item that has USAGE NATIONAL to an alphanumeric group.
Neither operand is converted. The national operand is treated as if it were moved
to an alphanumeric group item of the same size in bytes as the national operand,
and the two groups are compared. An alphanumeric comparison is done regardless
of the representation of the subordinate items in the alphanumeric group operand.
For example, Group-XN is an alphanumeric group that consists of two subordinate
items that have USAGE NATIONAL:
01 Group-XN.
02 TransCode PIC NN Value "AB" Usage National.
02 Quantity PIC 999 Value 123 Usage National.
. . .
If N"AB123" = Group-XN Then Display "EQUAL"
Else Display "NOT EQUAL".
When the IF statement above is executed, the 10 bytes of the national literal
N"AB123" are compared byte by byte to the content of Group-XN. The items compare
equally, and "EQUAL" is displayed.
Chapter 7. Processing data in an international environment 149
RELATED REFERENCES
Group comparisons (Enterprise COBOL Language Reference)
Coding for use of DBCS support
IBM Enterprise COBOL for z/OS supports using applications in any of many
national languages, including languages that use double-byte character sets
(DBCS).
The following list summarizes the support for DBCS:
v DBCS characters in user-defined words (DBCS names)
v DBCS characters in comments
v DBCS data items (defined with PICTURE N, G, or G and B)
v DBCS literals
v DBCS compiler option
RELATED TASKS
| Defining DBCS data
Using DBCS literals
Testing for valid DBCS characters on page 151
Processing alphanumeric data items that contain DBCS data on page 152
Appendix B, Converting double-byte character set (DBCS) data, on page 685
RELATED REFERENCES
DBCS on page 318
| Defining DBCS data
| Use the PICTURE and USAGE clauses to define DBCS data items. DBCS data items
can use PICTURE symbols G, G and B, or N. Each DBCS character position is 2 bytes
in length.
You can specify a DBCS data item by using the USAGE DISPLAY-1 clause. When you
use PICTURE symbol G, you must specify USAGE DISPLAY-1. When you use PICTURE
symbol N but omit the USAGE clause, USAGE DISPLAY-1 or USAGE NATIONAL is implied
depending on the setting of the NSYMBOL compiler option.
| If you use a VALUE clause with the USAGE clause in the definition of a DBCS item,
you must specify a DBCS literal or the figurative constant SPACE or SPACES.
For the purpose of handling reference modifications, each character in a DBCS data
item is considered to occupy the number of bytes that corresponds to the
code-page width (that is, 2).
RELATED REFERENCES
NSYMBOL on page 338
Using DBCS literals
You can use the prefix N or G to represent a DBCS literal.
That is, you can specify a DBCS literal in either of these ways:
v Ndbcs characters (provided that the compiler option NSYMBOL(DBCS) is in effect)
v Gdbcs characters
150 Enterprise COBOL for z/OS, V5.2 Programming Guide
You can use quotation marks (") or single quotation marks () as the delimiters of
a DBCS literal irrespective of the setting of the APOST or QUOTE compiler option. You
must code the same opening and closing delimiter for a DBCS literal.
The shift-out (SO) control character X0E must immediately follow the opening
delimiter, and the shift-in (SI) control character X0F must immediately precede
the closing delimiter.
In addition to DBCS literals, you can use alphanumeric literals to specify any
character in one of the supported code pages. However, any string of DBCS
characters that is within an alphanumeric literal must be delimited by the SO and
SI characters, and the DBCS compiler option must be in effect for the SO and SI
characters to be recognized as shift codes.
You cannot continue an alphanumeric literal that contains DBCS characters. The
length of a DBCS literal is likewise limited by the available space in Area B on a
single source line. The maximum length of a DBCS literal is thus 28 double-byte
characters.
An alphanumeric literal that contains DBCS characters is processed byte by byte,
that is, with semantics appropriate for single-byte characters, except when it is
converted explicitly or implicitly to national data representation, as for example in
an assignment to or comparison with a national data item.
RELATED TASKS
Using figurative constants on page 26
RELATED REFERENCES
DBCS on page 318
NSYMBOL on page 338
QUOTE/APOST on page 348
DBCS literals (Enterprise COBOL Language Reference)
Testing for valid DBCS characters
The Kanji class test tests for valid Japanese graphic characters. This testing includes
Katakana, Hiragana, Roman, and Kanji character sets.
The Kanji class test is done by checking characters for the range X41 through
X7E in the first byte and X41 through XFE in the second byte, plus the space
character X4040.
The DBCS class test tests for valid graphic characters for the code page.
The DBCS class test is done by checking characters for the range X41 through
XFE in both the first and second byte of each character, plus the space character
X4040.
RELATED TASKS
Coding conditional expressions on page 98
RELATED REFERENCES
Class condition (Enterprise COBOL Language Reference)
Chapter 7. Processing data in an international environment 151
Processing alphanumeric data items that contain DBCS data
If you use byte-oriented operations (for example, STRING, UNSTRING, or reference
modification) on an alphanumeric data item that contains DBCS characters, results
are unpredictable. You should instead convert the item to a national data item
before you process it.
That is, do these steps:
1. Convert the item to UTF-16 in a national data item by using a MOVE statement
or the NATIONAL-OF intrinsic function.
2. Process the national data item as needed.
3. Convert the result back to an alphanumeric data item by using the DISPLAY-OF
intrinsic function.
RELATED TASKS
Joining data items (STRING) on page 105
Splitting data items (UNSTRING) on page 107
Referring to substrings of data items on page 111
Converting to or from national (Unicode) representation on page 137
152 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 8. Processing files
Reading and writing data is an essential part of every program. Your program
retrieves information, processes it as you request, and then produces the results.
The source of the information and the target for the results can be one or more of
the following items:
v Another program
v Direct-access storage device
v Magnetic tape
v Printer
v Terminal
v Card reader or punch
The information as it exists on an external device is in a physical record or block, a
collection of information that is handled as a unit by the system during input or
output operations.
Your COBOL program does not directly handle physical records. It processes
logical records. A logical record can correspond to a complete physical record, part
of a physical record, or to parts or all of one or more physical records. Your
COBOL program handles logical records exactly as you have defined them.
In COBOL, a collection of logical records is a file, a sequence of pieces of
information that your program can process.
RELATED CONCEPTS
File organization and input-output devices
RELATED TASKS
Choosing file organization and access mode on page 155
Allocating files on page 157
Checking for input or output errors on page 158
File organization and input-output devices
Depending on the input-output devices, your file organization can be sequential,
line sequential, indexed, or relative. Decide on the file types and devices to be used
when you design your program.
You have the following choices of file organization:
Sequential file organization
The chronological order in which records are entered when a file is created
establishes the arrangement of the records. Each record except the first has
a unique predecessor record, and each record except the last has a unique
successor record. Once established, these relationships do not change.
The access (record transmission) mode allowed for sequential files is
sequential only.
Copyright IBM Corp. 1991, 2015 153
Line-sequential file organization
Line-sequential files are sequential files that reside in the z/OS UNIX file
system and that contain only characters as data. Each record ends with a
newline character.
The only access (record transmission) mode allowed for line-sequential files
is sequential.
Indexed file organization
Each record in the file contains a special field whose contents form the
record key. The position of the key is the same in each record. The index
component of the file establishes the logical arrangement of the file, an
ordering by record key. The actual physical arrangement of the records in
the file is not significant to your COBOL program.
An indexed file can also use alternate indexes in addition to the record key.
These keys let you access the file using a different logical ordering of the
records.
The access (record transmission) modes allowed for indexed files are
sequential, random, or dynamic. When you read or write indexed files
sequentially, the sequence is that of the key values.
Relative file organization
Records in the file are identified by their location relative to the beginning
of the file. The first record in the file has a relative record number of 1, the
tenth record has a relative record number of 10, and so on.
The access (record transmission) modes allowed for relative files are
sequential, random, or dynamic. When relative files are read or written
sequentially, the sequence is that of the relative record number.
With IBM Enterprise COBOL for z/OS, requests to the operating system for the
storage and retrieval of records from input-output devices are handled by the two
access methods QSAM and VSAM, and the z/OS UNIX file system.
The device type upon which you elect to store your data could affect the choices of
file organization available to you. Direct-access storage devices provide greater
flexibility in the file organization options. Sequential-only devices limit
organization options but have other characteristics, such as the portability of tapes,
that might be useful.
Sequential-only devices
Terminals, printers, card readers, and punches are called unit-record devices
because they process one line at a time. Therefore, you must also process
records one at a time sequentially in your program when it reads from or
writes to unit-record devices.
On tape, records are ordered sequentially, so your program must process
them sequentially. Use QSAM physical sequential files when processing
tape files. The records on tape can be fixed length or variable length.
Direct-access storage devices
Direct-access storage devices hold many records. The record arrangement
of files stored on these devices determines the ways that your program can
process the data. When using direct-access devices, you have greater
flexibility within your program, because your can use several types of file
organization:
v Sequential (VSAM or QSAM)
v Line sequential (z/OS UNIX)
154 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Indexed (VSAM)
v Relative (VSAM)
RELATED TASKS
Allocating files on page 157
Chapter 9, Processing QSAM files, on page 159
Chapter 10, Processing VSAM files, on page 185
Chapter 11, Processing line-sequential files, on page 213
Choosing file organization and access mode
Choosing file organization and access mode
There are several guidelines you can use to determine which file organization and
access mode to use in an application.
Consider the following guidelines when choosing file organization:
v If an application accesses records (whether fixed-length or variable-length) only
sequentially and does not insert records between existing records, a QSAM or
VSAM sequential file is the simplest type.
v If you are developing an application for z/OS UNIX file system that sequentially
accesses records that contain only printable characters and certain control
characters, line-sequential files work best.
v If an application requires both sequential and random access (whether records
are fixed length or variable length), a VSAM indexed file is the most flexible
type.
v If an application inserts and deletes records randomly, a relative file works well.
Consider the following guidelines when choosing access mode:
v If a large percentage of a file is referenced or updated in an application,
sequential access is faster than random or dynamic access.
v If a small percentage of records is processed during each run of an application,
use random or dynamic access.
Table 19. Summary of file organizations, access modes, and record formats of COBOL
files
Sequential Random Dynamic Fixed Variable
File organization access access access length length
QSAM (physical X X X
sequential)
Line sequential X X1 X
VSAM sequential (ESDS) X X X
VSAM indexed (KSDS) X X X X X
VSAM relative (RRDS) X X X X X
1. The data itself is in variable format but can be read into and written from COBOL
fixed-length records.
RELATED REFERENCES
Format for coding input and output on page 156
Control characters in line-sequential files on page 214
Chapter 8. Processing files 155
Format for coding input and output
The following example shows the general format of input-output coding.
Explanations of the user-supplied information are shown after the code.
IDENTIFICATION DIVISION.
. . .
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT filename ASSIGN TO assignment-name (1) (2)
ORGANIZATION IS org ACCESS MODE IS access (3) (4)
FILE STATUS IS file-status (5)
. . .
DATA DIVISION.
FILE SECTION.
FD filename
01 recordname (6)
nn . . . fieldlength & type (7) (8)
nn . . . fieldlength & type
. . .
WORKING-STORAGE SECTION
01 file-status PICTURE 99.
. . .
PROCEDURE DIVISION.
. . .
OPEN iomode filename (9)
. . .
READ filename
. . .
WRITE recordname
. . .
CLOSE filename
. . .
STOP RUN.
The user-supplied information in the code above is described below:
(1) filename
Any legal COBOL name. You must use the same file-name in the SELECT
clause and in the FD entry, and in the READ, OPEN, and CLOSE statements. In
addition, the file-name is required if you use the START or DELETE
statements. This name is not necessarily the actual name of the data set as
known to the system. Each file requires its own SELECT clause, FD entry,
and input-output statements.
(2) assignment-name
Any name you choose, provided that it follows COBOL and system
naming rules. The name can be 1 - 30 characters long if it is a user-defined
word, or 1 - 160 characters long if it is a literal. You code the name part of
the assignment-name in a DD statement, in an ALLOCATE command (TSO), or
as an environment variable (for example, in an export command) (z/OS
UNIX).
(3) org The organization can be SEQUENTIAL, LINE SEQUENTIAL, INDEXED, or
RELATIVE. This clause is optional for QSAM files.
(4) access
The access mode can be SEQUENTIAL, RANDOM, or DYNAMIC. For sequential file
processing, including line-sequential, you can omit this clause.
(5) file-status
The COBOL file status key. You can specify the file status key as a
156 Enterprise COBOL for z/OS, V5.2 Programming Guide
two-character category alphanumeric or category national item, or as a
two-digit zoned decimal (USAGE DISPLAY) or national decimal (USAGE
NATIONAL) item.
(6) recordname
The name of the record used in the WRITE or REWRITE statements.
(7) fieldlength
The logical length of the field.
(8) type
The record format of the file. If you break the record entry beyond the
level-01 description, map each element accurately against the fields in the
record.
(9) iomode
The INPUT or OUTPUT mode. If you are only reading from a file, code INPUT.
If you are only writing to a file, code OUTPUT or EXTEND. If you are both
reading and writing, code I-O, except for organization LINE SEQUENTIAL.
RELATED TASKS
Chapter 9, Processing QSAM files, on page 159
Chapter 10, Processing VSAM files, on page 185
Chapter 11, Processing line-sequential files, on page 213
Allocating files
For any type of file (sequential, line sequential, indexed, or relative) in your z/OS
or z/OS UNIX applications, you can define the external name with either a
ddname or an environment-variable name. The external name is the name in the
assignment-name of the ASSIGN clause.
If the file is in the z/OS UNIX file system, you can use either a DD definition or an
environment variable to define the file by specifying its path name with the PATH
keyword.
The environment-variable name must be uppercase. The allowable attributes for its
value depend on the organization of the file being defined.
Because you can define the external name in either of two ways, the COBOL run
time goes through the following steps to find the definition of the file:
1. If the ddname is explicitly allocated, it is used. The definition can be from a DD
statement in JCL, an ALLOCATE command from TSO/E, or a user-initiated
dynamic allocation.
2. If the ddname is not explicitly allocated and an environment variable of the
same name is set, the value of the environment variable is used.
The file is dynamically allocated using the attributes specified by the
environment variable. At a minimum, you must specify either the PATH() or
DSN() option. All options and attributes must be in uppercase, except for the
path-name suboption of the PATH option, which is case sensitive. You cannot
specify a temporary data-set name in the DSN() option.
File status code 98 results from any of the following cases:
v The contents (including a value of null or all blanks) of the environment
variable are not valid.
v The dynamic allocation of the file fails.
v The dynamic deallocation of the file fails.
Chapter 8. Processing files 157
The COBOL run time checks the contents of the environment variable at each
OPEN statement. If a file with the same external name was dynamically allocated
by a previous OPEN statement, and the contents of the environment variable
have changed since that OPEN, the run time dynamically deallocates the
previous allocation and reallocates the file using the options currently set in the
environment variable. If the contents of the environment variable have not
changed, the run time uses the current allocation.
3. If neither a ddname nor an environment variable is defined, the following steps
occur:
a. If the allocation is for a QSAM file and the CBLQDA runtime option is in
effect, CBLQDA dynamic allocation processing takes place for those eligible
files. This type of "implicit" dynamic allocation persists for the life of the
run unit and cannot be reallocated.
b. Otherwise, the allocation fails.
The COBOL run time deallocates all dynamic allocations at run unit termination,
except for implicit CBLQDA allocations.
RELATED TASKS
Setting and accessing environment variables on page 454
Defining and allocating QSAM files on page 174
Dynamically creating QSAM files on page 171
Allocating VSAM files on page 206
Checking for input or output errors
After each input or output statement is performed, the file status key is updated
with a value that indicates the success or failure of the operation.
Using a FILE STATUS clause, test the file status key after each input or output
statement, and call an error-handling procedure if a nonzero file status code is
returned. With VSAM files, you can use a second data item in the FILE STATUS
clause to get additional VSAM status code information.
Another way of handling errors in input and output operations is to code ERROR
(synonymous with EXCEPTION) declaratives.
RELATED TASKS
Handling errors in input and output operations on page 241
Coding ERROR declaratives on page 244
Using file status keys on page 245
158 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 9. Processing QSAM files
Queued sequential access method (QSAM) files are unkeyed files in which the
records are placed one after another, according to entry order.
Your program can process these files only sequentially, retrieving (with the READ
statement) records in the same order as they are in the file. Each record is placed
after the preceding record. To process QSAM files in your program, use COBOL
language statements that:
v Identify and describe the QSAM files in the ENVIRONMENT DIVISION and the DATA
DIVISION.
v Process the records in these files in the PROCEDURE DIVISION.
After you have created a record, you cannot change its length or its position in the
file, and you cannot delete it. You can, however, update QSAM files on
direct-access storage devices (using REWRITE), though not in the z/OS UNIX file
system.
QSAM files can be on tape, direct-access storage devices (DASDs), unit-record
devices, and terminals. QSAM processing is best for tables and intermediate
storage.
You can also access byte-stream files in the z/OS UNIX file system using QSAM.
These files are binary byte-oriented sequential files with no record structure. The
record definitions that you code in your COBOL program and the length of the
variables that you read into and write from determine the amount of data
transferred.
RELATED CONCEPTS
z/OS DFSMS: Using Data Sets (Access methods)
RELATED TASKS
Defining QSAM files and records in COBOL
Coding input and output statements for QSAM files on page 170
Handling errors in QSAM files on page 174
Working with QSAM files on page 174
Accessing z/OS UNIX files using QSAM on page 181
Processing QSAM ASCII files on tape on page 182
Defining QSAM files and records in COBOL
Use the FILE-CONTROL entry to define the files in a COBOL program as QSAM files,
and to associate the files with their external file-names.
An external file-name (a ddname or environment variable name) is the name by
which a file is known to the operating system. In the following example,
COMMUTER-FILE-MST is your program's name for the file; COMMUTR is the external
name:
FILE-CONTROL.
SELECT COMMUTER-FILE-MST
ASSIGN TO S-COMMUTR
ORGANIZATION IS SEQUENTIAL
ACCESS MODE IS SEQUENTIAL.
Copyright IBM Corp. 1991, 2015 159
The ASSIGN clause name can include an S- before the external name to document
that the file is a QSAM file. Both the ORGANIZATION and ACCESS MODE clauses are
optional.
RELATED TASKS
Establishing record formats
Setting block sizes on page 167
Establishing record formats
In the FD entry in the DATA DIVISION, code the record format and indication of
whether the records are blocked. In the associated record description entry or
entries, specify the record-name and record length.
You can code a record format of F, V, S, or U in the RECORDING MODE clause. COBOL
determines the record format from the RECORD clause or from the record
descriptions associated with the FD entry for the file. If you want the records to be
blocked, code the BLOCK CONTAINS clause in the FD entry.
The following example shows how the FD entry might look for a file that has
fixed-length records:
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS F
BLOCK CONTAINS 0 RECORDS
RECORD CONTAINS 80 CHARACTERS.
01 COMMUTER-RECORD-MST.
05 COMMUTER-NUMBER PIC X(16).
05 COMMUTER-DESCRIPTION PIC X(64).
A recording mode of S is not supported for files in the z/OS UNIX file system. The
above example is appropriate for such a file.
RELATED CONCEPTS
Logical records
RELATED TASKS
Requesting fixed-length format on page 161
Requesting variable-length format on page 162
Requesting spanned format on page 164
Requesting undefined format on page 166
Defining QSAM files and records in COBOL on page 159
RELATED REFERENCES
FILE SECTION entries on page 12
Logical records
COBOL uses the term logical record in a slightly different way than z/OS QSAM.
For format-V and format-S files, a QSAM logical record includes a 4-byte prefix in
front of the user data portion of the record that is not included in the definition of
a COBOL logical record.
For format-F and format-U files, and for byte-stream files in the z/OS UNIX file
system, the definitions of QSAM logical record and COBOL logical record are
identical.
160 Enterprise COBOL for z/OS, V5.2 Programming Guide
In this information, QSAM logical record refers to the QSAM definition, and logical
record refers to the COBOL definition.
RELATED REFERENCES
Layout of format-F records on page 162
Layout of format-V records on page 163
Layout of format-S records on page 166
Layout of format-U records on page 167
Requesting fixed-length format
Fixed-length records are in format F. Use RECORDING MODE F to explicitly request
this format.
You can omit the RECORDING MODE clause. The compiler determines the recording
mode to be F if the length of the largest level-01 record associated with the file is
not greater than the block size coded in the BLOCK CONTAINS clause, and you take
one of the following actions:
v Use the RECORD CONTAINS integer clause (format-1 RECORD clause) to indicate the
length of the record in bytes.
When you use this clause, the file is always fixed format with record length
integer even if there are multiple level-01 record description entries with different
lengths associated with the file.
v Omit the RECORD CONTAINS integer clause, but code the same fixed size and no
OCCURS DEPENDING ON clause for all level-01 record description entries associated
with the file. This fixed size is the record length.
In an unblocked format-F file, the logical record is the same as the block.
In a blocked format-F file, the number of logical records in a block (the blocking
factor) is constant for every block in the file except the last block, which might be
shorter.
Files in the z/OS UNIX file system are never blocked.
RELATED CONCEPTS
Logical records on page 160
RELATED TASKS
Requesting variable-length format on page 162
Requesting spanned format on page 164
Requesting undefined format on page 166
Establishing record formats on page 160
RELATED REFERENCES
Layout of format-F records on page 162
Chapter 9. Processing QSAM files 161
Layout of format-F records:
The layout of format-F QSAM records is shown below.
RELATED CONCEPTS
Logical records on page 160
RELATED TASKS
Requesting fixed-length format on page 161
z/OS DFSMS: Using Data Sets (Fixed-length record formats)
RELATED REFERENCES
Layout of format-V records on page 163
Layout of format-S records on page 166
Layout of format-U records on page 167
Requesting variable-length format
Variable-length records can be in format V or format D. Format-D records are
variable-length records on ASCII tape files. Format-D records are processed in the
same way as format-V records.
Use RECORDING MODE V for both. You can omit the RECORDING MODE clause. The
compiler determines the recording mode to be V if the largest level-01 record
associated with the file is not greater than the block size set in the BLOCK CONTAINS
clause, and you take one of the following actions:
v Use the RECORD IS VARYING clause (format-3 RECORD clause).
If you provide values for integer-1 and integer-2 (RECORD IS VARYING FROM
integer-1 TO integer-2), the maximum record length is the value coded for integer-2
regardless of the lengths coded in the level-01 record description entries
associated with the file. The integer sizes indicate the minimum and maximum
record lengths in numbers of bytes regardless of the USAGE of the data items in
the record.
If you omit integer-1 and integer-2, the maximum record length is determined to
be the size of the largest level-01 record description entry associated with the
file.
v Use the RECORD CONTAINS integer-1 TO integer-2 clause (format-2 RECORD clause).
Make integer-1 and integer-2 match the minimum length and the maximum
length in bytes of the level-01 record description entries associated with the file.
The maximum record length is the integer-2 value.
v Omit the RECORD clause, but code multiple level-01 records (associated with the
file) that are of different sizes or contain an OCCURS DEPENDING ON clause.
The maximum record length is determined to be the size of the largest level-01
record description entry associated with the file.
162 Enterprise COBOL for z/OS, V5.2 Programming Guide
When you specify a READ INTO statement for a format-V file, the record size read
for that file is used in the MOVE statement generated by the compiler. Consequently,
you might not get the result you expect if the record just read does not correspond
to the level-01 record description. All other rules of the MOVE statement apply. For
example, when you specify a MOVE statement for a format-V record read in by the
READ statement, the size of the record moved corresponds to its level-01 record
description.
When you specify a READ statement for a format-V file followed by a MOVE of the
level-01 record, the actual record length is not used. The program will attempt to
move the number of bytes described by the level-01 record description. If this
number exceeds the actual record length and extends outside the area addressable
by the program, results are unpredictable. If the number of bytes described by the
level-01 record description is shorter than the physical record read, truncation of
bytes beyond the level-01 description occurs. To find the actual length of a
variable-length record, specify data-name-1 in format 3 of the RECORD clause of the
File Definition (FD).
RELATED TASKS
Requesting fixed-length format on page 161
Requesting spanned format on page 164
Requesting undefined format on page 166
Establishing record formats on page 160
RELATED REFERENCES
FILE SECTION entries on page 12
Layout of format-V records
Enterprise COBOL Migration Guide (Moving from the
VS COBOL II run time)
Layout of format-V records:
Format-V QSAM records have control fields that precede the data. The QSAM
logical record length is determined by adding 4 bytes (for the control fields) to the
record length defined in your program. However, you must not include these 4
bytes in the description of the record and record length.
Block Size
QSAM Logical Record
Data Record
(Level -01 Record)
4 4 Variable 4 Variable
bytes bytes bytes bytes bytes
LL BB ll bb Data ll bb Data
'CC' 'cc' 'cc'
CC The first 4 bytes of each block contain control information.
LL Represents 2 bytes designating the length of the block (including the CC
field).
BB Represents 2 bytes reserved for system use.
cc The first 4 bytes of each logical record contain control information.
ll Represents 2 bytes designating the logical record length (including the
cc field).
bb Represents 2 bytes reserved for system use.
Chapter 9. Processing QSAM files 163
The block length is determined as follows:
v Unblocked format-V records: CC + cc + the data portion
v Blocked format-V records: CC + the cc of each record + the data portion of each
record
The operating system provides the control bytes when the file is written; the
control byte fields do not appear in the description of the logical record in the DATA
DIVISION of your program. COBOL allocates input and output buffers that are
large enough to accommodate the control bytes. These control fields in the buffer
are not available for you to use in your program. When variable-length records are
written on unit record devices, control bytes are neither printed nor punched. They
appear however on other external storage devices, as well as in buffer areas of
storage. If you move V-mode records from an input buffer to a WORKING-STORAGE
area, the records will be moved without the control bytes.
Files in the z/OS UNIX file system are never blocked.
RELATED CONCEPTS
Logical records on page 160
RELATED TASKS
Requesting variable-length format on page 162
RELATED REFERENCES
Layout of format-F records on page 162
Layout of format-S records on page 166
Layout of format-U records on page 167
Requesting spanned format
Spanned records are in format S. A spanned record is a QSAM logical record that
can be contained in one or more physical blocks.
You can code RECORDING MODE S for spanned records in QSAM files that are
assigned to magnetic tape or to direct access devices. Do not request spanned
records for files in the z/OS UNIX file system. You can omit the RECORDING MODE
clause. The compiler determines the recording mode to be S if the maximum
record length (in bytes) plus 4 is greater than the block size set in the BLOCK
CONTAINS clause.
For files with format S in your program, the compiler determines the maximum
record length with the same rules as are used for format V. The length is based on
your usage of the RECORD clause.
When creating files that contain format-S records and a record is larger than the
remaining space in a block, COBOL writes a segment of the record to fill the block.
The rest of the record is stored in the next block or blocks depending on its length.
COBOL supports QSAM spanned records up to 32,760 bytes in length.
When retrieving files that have format-S records, a program can retrieve only
complete records.
Benefits of format-S files: You can efficiently use external storage and still
organize your files with logical record lengths by defining files with format-S
records:
164 Enterprise COBOL for z/OS, V5.2 Programming Guide
v You can set block lengths to efficiently use track capacities on direct access
devices.
v You are not required to adjust the logical record lengths to device-dependent
physical block lengths. One logical record can span two or more physical blocks.
v You have greater flexibility when you want to transfer logical records between
direct access storage types.
You will, however, have additional overhead in processing format-S files.
Format-S files and READ INTO: When you specify a READ INTO statement for a
format-S file, the compiler generates a MOVE statement that uses the size of the
record that it just read for that file. If the record just read does not correspond to
the level-01 record description, you might not get the result that you expect. All
other rules of the MOVE statement apply.
RELATED CONCEPTS
Logical records on page 160
Spanned blocked and unblocked files
RELATED TASKS
Requesting fixed-length format on page 161
Requesting variable-length format on page 162
Requesting undefined format on page 166
Establishing record formats on page 160
RELATED REFERENCES
FILE SECTION entries on page 12
Layout of format-S records on page 166
Spanned blocked and unblocked files:
A spanned blocked QSAM file is made up of blocks, each containing one or more
logical records or segments of logical records. A spanned unblocked file is made
up of physical blocks, each containing one logical record or one segment of a
logical record.
In a spanned blocked file, a logical record can be either fixed or variable in length,
and its size can be smaller than, equal to, or larger than the physical block size.
There are no required relationships between logical records and physical block
sizes.
In a spanned unblocked file, the logical records can be either fixed or variable in
length. When the physical block contains one logical record, the block length is
determined by the logical record size. When a logical record has to be segmented,
the system always writes the largest physical block possible. The system segments
the logical record when the entire logical record cannot fit on a track.
RELATED CONCEPTS
Logical records on page 160
RELATED TASKS
Requesting spanned format on page 164
Chapter 9. Processing QSAM files 165
Layout of format-S records:
Spanned records are preceded by control fields, as explained below.
4 bytes 4 bytes Variable bytes
LL BB ll bb Data Record or Segment
BDF SDF
Each block is preceded by a 4-byte block descriptor field ('BDF' in the image
above). There is only one block descriptor field at the beginning of each physical
block.
Each segment of a record in a block is preceded by a 4-byte segment descriptor
field ('SDF' in the image) even if the segment is the entire record. There is one
segment descriptor field for each record segment in the block. The segment
descriptor field also indicates whether the segment is the first, the last, or an
intermediate segment.
You do not describe these fields in the DATA DIVISION, and the fields are not
available for you to use in your COBOL program.
RELATED TASKS
Requesting spanned format on page 164
RELATED REFERENCES
Layout of format-F records on page 162
Layout of format-V records on page 163
Layout of format-U records on page 167
Requesting undefined format
Format-U records have undefined or unspecified characteristics. With format U,
you can process blocks that do not meet format-F or format-V specifications.
When you use format-U files, each block of storage is one logical record. A read of
a format-U file returns the entire block as a record. A write to a format-U file
writes a record out as a block. The compiler determines the recording mode to be
U only if you code RECORDING MODE U.
It is recommended that you not use format U to update or extend a file that was
written with a different record format. If you use format U to update a file that
was written with a different format, the RECFM value in the data-set label could be
changed or the data set could contain records written in different formats.
The record length is determined in your program based on how you use the
RECORD clause:
v If you use the RECORD CONTAINS integer clause (format-1 RECORD clause), the record
length is the integer value regardless of the lengths of the level-01 record
description entries associated with the file. The integer size indicates the number
of bytes in a record regardless of the USAGE of its data items.
v If you use the RECORD IS VARYING clause (format-3 RECORD clause), the record
length is determined based on whether you code integer-1 and integer-2.
If you code integer-1 and integer-2 (RECORD IS VARYING FROM integer-1 TO
integer-2), the maximum record length is the integer-2 value regardless of the
lengths of the level-01 record description entries associated with the file. The
166 Enterprise COBOL for z/OS, V5.2 Programming Guide
integer sizes indicate the minimum and maximum record lengths in numbers of
bytes regardless of the USAGE of the data items in the record.
If you omit integer-1 and integer-2, the maximum record length is determined to
be the size of the largest level-01 record description entry associated with the
file.
v If you use the RECORD CONTAINS integer-1 TO integer-2 clause (format-2 RECORD
clause), with integer-1 and integer-2 matching the minimum length and the
maximum length in bytes of the level-01 record description entries associated
with the file, the maximum record length is the integer-2 value.
v If you omit the RECORD clause, the maximum record length is determined to be
the size of the largest level-01 record description entry associated with the file.
Format-U files and READ INTO: When you specify a READ INTO statement for a
format-U file, the compiler generates a MOVE statement that uses the size of the
record that it just read for that file. If the record just read does not correspond to
the level-01 record description, you might not get the result that you expect. All
other rules of the MOVE statement apply.
RELATED TASKS
Requesting fixed-length format on page 161
Requesting variable-length format on page 162
Requesting spanned format on page 164
Establishing record formats on page 160
RELATED REFERENCES
FILE SECTION entries on page 12
Layout of format-U records
Layout of format-U records:
With format-U, each block of external storage is handled as a logical record. There
are no record-length or block-length fields.
RELATED CONCEPTS
Logical records on page 160
RELATED TASKS
Requesting undefined format on page 166
RELATED REFERENCES
Layout of format-F records on page 162
Layout of format-V records on page 163
Layout of format-S records on page 166
Setting block sizes
In COBOL, you establish the size of a physical record by using the BLOCK CONTAINS
clause. If you omit this clause, the compiler assumes that the records are not
blocked.
Chapter 9. Processing QSAM files 167
Blocking QSAM files on tape and disk can enhance processing speed and minimize
storage requirements. You can block files in the z/OS UNIX file system, PDSE
members, and spooled data sets, but doing so has no effect on how the system
stores the data.
If you set the block size explicitly in the BLOCK CONTAINS clause, the size must not
be greater than the maximum block size for the device. If you specify the
CHARACTERS phrase of the BLOCK CONTAINS clause, size must indicate the number of
bytes in a record regardless of the USAGE of the data items in the record. The block
size that is set for a format-F file must be an integral multiple of the record length.
If your program uses QSAM files on tape, use a physical block size of at least 12 to
18 bytes. Otherwise, the block will be skipped over when a parity check occurs
during one of the following actions:
v Reading a block of records of fewer than 12 bytes
v Writing a block of records of fewer than 18 bytes
Larger blocks generally give you better performance. Blocks of only a few kilobytes
are particularly inefficient; you should choose a block size of at least tens of
kilobytes. If you specify record blocking and omit the block size, the system will
pick a block size that is optimal for device utilization and for data transfer speed.
Letting z/OS determine block size: To maximize performance, do not explicitly set
the block size for a blocked file in your COBOL source program. For new blocked
data sets, it is simpler to allow z/OS to supply a system-determined block size. To
use this feature, follow these guidelines:
v Code BLOCK CONTAINS 0 in your source program or compile with the BLOCK0
option. For details about BLOCK0, see BLOCK0 on page 310.
v Do not code RECORD CONTAINS 0 in your source program.
v Do not code a BLKSIZE value in the JCL DD statement.
Setting block size explicitly: If you prefer to set a block size explicitly, your
program will be most flexible if you follow these guidelines:
v Code BLOCK CONTAINS 0 in your source program.
v Code a BLKSIZE value in the ddname definition (the JCL DD statement).
For extended-format data sets on z/OS, z/OS DFSMS adds a 32-byte block suffix
to the physical record. If you specify a block size explicitly (using JCL or ISPF), do
not include the size of this block suffix in the block size. This block suffix is not
available for you to use in your program. z/OS DFSMS allocates the space used to
read in the block suffix. However, when you calculate how many blocks of an
extended-format data set will fit on a track of a direct-access device, you need to
include the size of the block suffix in the block size.
If you specify a block size that is larger than 32760 directly in the BLOCK CONTAINS
clause or indirectly with the use of BLOCK CONTAINS n RECORDS, the OPEN of the data
set fails with file status code 90 unless you define the data set to be on tape.
For existing blocked data sets, it is simplest to:
v Code BLOCK CONTAINS 0 in your source program.
v Not code a BLKSIZE value in the ddname definition.
When you omit the BLKSIZE from the ddname definition, the block size is
automatically obtained by the system from the data-set label.
168 Enterprise COBOL for z/OS, V5.2 Programming Guide
Taking advantage of LBI: You can improve the performance of tape data sets by
using the large block interface (LBI) for large block sizes. When the LBI is
available, the COBOL run time automatically uses this facility for those tape files
for which you use system-determined block size. LBI is also used for those files for
which you explicitly define a block size in JCL or a BLOCK CONTAINS clause. Use of
the LBI allows block sizes to exceed 32760 if the tape device supports it.
The LBI is not used in all cases. An attempt to use a block size greater than 32760
in the following cases is diagnosed at compile time or results in a failure at OPEN:
v Spanned records
v OPEN I-O
Using a block size that exceeds 32760 might result in your not being able to read
the tape on another system. A tape that you create with a block size greater than
32760 can be read only on a system that has a tape device that supports block sizes
greater than 32760. If you specify a block size that is too large for the file, the
device, or the operating system level, a runtime message is issued.
To limit a system-determined block size to 32760, do not specify BLKSIZE anywhere,
and set one of the following items to 32760:
v The BLKSZLIM keyword on the DD statement for the data set
v BLKSZLIM for the data class by using the BLKSZLIM keyword (must be set by your
systems programmer)
v A block-size limit for the system in the DEVSUPxx member of SYS1.PARMLIB
by using the keyword TAPEBLKSZLIM (must be set by your systems programmer)
The block-size limit is the first nonzero value that the compiler finds by checking
these items.
If no BLKSIZE or BLKSZLIM value is available from any source, the system limits
BLKSIZE to 32760. You can then enable block sizes larger than 32760 in one of two
ways:
v Specify a BLKSZLIM value greater than 32760 in the DD statement for the file and
use BLOCK CONTAINS 0 in your COBOL source.
v Specify a value greater than 32760 for the BLKSIZE in the DD statement or in the
BLOCK CONTAINS clause in your COBOL source.
BLKSZLIM is device-independent.
Block size and the DCB RECFM subparameter: Under z/OS, you can code the S
or T option in the DCB RECFM subparameter:
v Use the S (standard) option in the DCB RECFM subparameter for a format-F record
with only standard blocks (ones that have no truncated blocks or unfilled tracks
in the file, except for the last block of the file). S is also supported for records on
tape. It is ignored if the records are not on DASD or tape.
Using this standard block option might improve input-output performance,
especially for direct-access devices.
v The T (track overflow) option for QSAM files is no longer useful.
RELATED TASKS
Defining QSAM files and records in COBOL on page 159
z/OS DFSMS: Using Data Sets
Chapter 9. Processing QSAM files 169
RELATED REFERENCES
FILE SECTION entries on page 12
BLOCK0 on page 310
BLOCK CONTAINS clause (Enterprise COBOL Language Reference)
Coding input and output statements for QSAM files
You can code the following input and output statements to process a QSAM file or
a byte-stream file in the z/OS UNIX file system using QSAM: OPEN, READ, WRITE,
REWRITE, and CLOSE.
OPEN Initiates the processing of files. You can open all QSAM files as INPUT,
OUTPUT, or EXTEND (depending on device capabilities).
You can also open QSAM files on direct access storage devices as I-O. You
cannot open z/OS UNIX files as I-O; a file status of 37 results if you
attempt to do so.
READ Reads a record from the file. With sequential processing, your program
reads one record after another in the same order in which they were
entered when the file was created.
WRITE Creates a record in the file. Your program writes new records to the end of
the file.
REWRITE
Updates a record. You cannot update a file in the z/OS UNIX file system
using REWRITE.
CLOSE Releases the connection between the file and your program.
RELATED TASKS
Opening QSAM files
Dynamically creating QSAM files on page 171
Adding records to QSAM files on page 172
Updating QSAM files on page 172
Writing QSAM files to a printer or spooled data set on page 172
Closing QSAM files on page 173
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
READ statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise COBOL Language Reference)
REWRITE statement (Enterprise COBOL Language Reference)
CLOSE statement (Enterprise COBOL Language Reference)
File status key (Enterprise COBOL Language Reference)
Opening QSAM files
Before a program can use any READ, WRITE, or REWRITE statements to process records
in a file, it must first open the file by using an OPEN statement.
An OPEN statement works if both of the following conditions are true:
v The file is available or has been dynamically allocated.
v The fixed file attributes coded in the ddname definition or the data-set label for
the file match the attributes coded for that file in the SELECT clause and FD entry.
Mismatches in the file-organization attributes, code set, maximum record size, or
record format (fixed or variable) result in file status code 39, and the failure of
170 Enterprise COBOL for z/OS, V5.2 Programming Guide
the OPEN statement. Mismatches in maximum record size and record format are
not errors when opening files in the z/OS UNIX file system.
For fixed-length QSAM files, if you code RECORD CONTAINS 0 in the FD entry, the
record size attributes are not in conflict. The record size is taken from the DD
statement or the data-set label, and the OPEN statement is successful.
Code CLOSE WITH LOCK so that the file cannot be opened again while the program
is running.
Use the REVERSED option of the OPEN statement to process tape files in reverse order.
The file is positioned at the end, and READ statements read the data records in
reverse order, starting with the last record. The REVERSED option is supported only
for files that have fixed-length records.
RELATED TASKS
Dynamically creating QSAM files
Ensuring that file attributes match your program on page 178
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
Dynamically creating QSAM files
Sometimes a QSAM file is unavailable on the operating system, but a COBOL
program specifies that the file be created. Under certain circumstances, the file is
created for you dynamically.
A QSAM file is considered to be available on z/OS when it has been identified to
the operating system using a valid DD statement, an export command for an
environment variable, or a TSO ALLOCATE command. Otherwise the file is
unavailable.
Note that a DD statement with a misspelled ddname is equivalent to a missing DD
statement, and an environment variable with a value that is not valid is equivalent
to an unset variable.
The QSAM file is implicitly created if you use the runtime option CBLQDA and one
of the following circumstances exists:
v An optional file is being opened as EXTEND or I-O.
Optional files are files that are not necessarily available each time the program is
run. You define a file that is being opened in INPUT, I-O, or EXTEND mode as
optional by coding the SELECT OPTIONAL clause in the FILE-CONTROL paragraph.
v The file is being opened for OUTPUT, regardless of the OPTIONAL phrase.
The file is allocated with the system default attributes established at your
installation and the attributes coded in the SELECT clause and FD entry in your
program.
Do not confuse this implicit allocation mechanism with the explicit dynamic
allocation of files by means of environment variables. Explicit dynamic allocation
requires that a valid environment variable be set. CBLQDA support is used only
when the QSAM file is unavailable as defined above, which includes no valid
environment variable being set.
Chapter 9. Processing QSAM files 171
Under z/OS, files created using the CBLQDA option are temporary data sets and do
not exist after the program has run.
RELATED TASKS
Opening QSAM files on page 170
Adding records to QSAM files
To add to a QSAM file, open the file as EXTEND and use the WRITE statement to add
records immediately after the last record in the file.
To add records to a file opened as I-O, you must first close the file and open it as
EXTEND.
RELATED REFERENCES
READ statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise COBOL Language Reference)
Updating QSAM files
You can update QSAM files only if they reside on direct access storage devices.
You cannot update files in the z/OS UNIX file system.
Replace an existing record with another record of the same length by doing these
steps:
1. Open the file as I-O.
2. Use REWRITE to update an existing record. (The last file processing statement
before REWRITE must have been a successful READ statement.)
You cannot open as I-O an extended format data set that you allocate in
compressed format.
RELATED REFERENCES
REWRITE statement (Enterprise COBOL Language Reference)
Writing QSAM files to a printer or spooled data set
COBOL provides language statements to control the size of a printed page and
control the vertical positioning of records.
Controlling the page size: Use the LINAGE clause of the FD entry to control the size
of your printed page: the number of lines in the top and bottom margins and in
the footing area of the page. When you use the LINAGE clause, COBOL handles the
file as if you had also requested the ADV compiler option.
If you use the LINAGE clause in combination with WRITE BEFORE|AFTER ADVANCING
nn LINES, be careful about the values you set. With the ADVANCING nn LINES phrase,
COBOL first calculates the sum of LINAGE-COUNTER plus nn. Subsequent actions
depend on the size of nn. The END-OF-PAGE imperative phrase is performed after
the LINAGE-COUNTER is increased. Consequently, the LINAGE-COUNTER could be
pointing to the next logical page instead of to the current footing area when the
END-OF-PAGE phrase is performed.
AT END-OF-PAGE or NOT AT END-OF-PAGE imperative phrases are performed only if
the write operation completes successfully. If the write operation is unsuccessful,
control is passed to the end of the WRITE statement, and all conditional phrases are
omitted.
172 Enterprise COBOL for z/OS, V5.2 Programming Guide
Controlling the vertical positioning of records: Use the WRITE ADVANCING
statement to control the vertical positioning of each record you write on a printed
page.
BEFORE ADVANCING prints the record before the page is advanced. AFTER ADVANCING
prints the record after the page is advanced.
Specify the number of lines the page is advanced with an integer (or an identifier
with a mnemonic-name) following ADVANCING. If you omit the ADVANCING phrase from
a WRITE statement, the effect is as if you had coded:
AFTER ADVANCING 1 LINE
RELATED REFERENCES
WRITE statement (Enterprise COBOL Language Reference)
Closing QSAM files
Use the CLOSE statement to disconnect your program from a QSAM file. If you try
to close a file that is already closed, you will get a logic error.
If you do not close a QSAM file, the file is automatically closed for you under the
following conditions:
v When the run unit ends normally, the run time closes all open files that are
defined in any COBOL programs in the run unit.
v If the run unit ends abnormally and the TRAP(ON) runtime option is in effect, the
run time closes all open files that are defined in any COBOL programs in the
run unit.
v When Language Environment condition handling has completed and the
application resumes in a routine other than where the condition occurred, the
run time closes all open files that are defined in any COBOL programs in the
run unit that might be called again and reentered.
You can change the location where the program resumes running (after a
condition is handled) by moving the resume cursor with the Language
Environment CEEMRCR callable service or by using language constructs such as
a C longjmp.
v When you use CANCEL for a COBOL subprogram, the run time closes any open
nonexternal files that are defined in that program.
v When a COBOL subprogram with the INITIAL attribute returns control, the run
time closes any open nonexternal files that are defined in that program.
v When a thread of a multithreaded application ends, both external and
nonexternal files that you opened from within that same thread are closed.
File status key data items in the DATA DIVISION are set when these implicit CLOSE
operations are performed, but your EXCEPTION/ERROR declarative is not invoked.
Errors: If you open a QSAM file in a multithreaded application, you must close it
from the same thread of execution from which the file was opened. Attempting to
close the file from a different thread results in a close failure with file-status
condition 90.
RELATED REFERENCES
CLOSE statement (Enterprise COBOL Language Reference)
Chapter 9. Processing QSAM files 173
Handling errors in QSAM files
When an input statement or output statement fails, COBOL does not take
corrective action for you. You choose whether your program should continue
running after a less-than-severe input or output error occurs.
COBOL provides these ways for you to intercept and handle certain QSAM input
and output errors:
v End-of-file phrase (AT END)
v EXCEPTION/ERROR declarative
v FILE STATUS clause
v INVALID KEY phrase
If you do not code a FILE STATUS key or a declarative, serious QSAM processing
errors will cause a message to be issued and a Language Environment condition to
be signaled, which will cause an abend if you specify the runtime option
ABTERMENC(ABEND).
If you use the FILE STATUS clause or the EXCEPTION/ERROR declarative, code
EROPT=ACC in the DCB of the DD statement for that file. Otherwise, your COBOL
program will not be able to continue processing after some error conditions.
If you use the FILE STATUS clause, be sure to check the key and take appropriate
action based on its value. If you do not check the key, your program might
continue, but the results will probably not be what you expected.
RELATED TASKS
Handling errors in input and output operations on page 241
Working with QSAM files
To work with QSAM files in a COBOL program, you define and allocate the files,
retrieve them, and ensure that their file attributes match those in the program. You
can also use striped extended-format QSAM data sets to help improve
performance.
RELATED TASKS
Defining and allocating QSAM files
Retrieving QSAM files on page 177
Ensuring that file attributes match your program on page 178
Using striped extended-format QSAM data sets on page 180
RELATED REFERENCES
Allocation of buffers for QSAM files on page 181
Defining and allocating QSAM files
You can define a QSAM file or a byte-stream file in the z/OS UNIX file system by
using either a DD statement or an environment variable. Allocation of these files
follows the general rules for the allocation of COBOL files.
When you use an environment variable, the name must be in uppercase. Specify
the MVS data set in one of these ways:
v DSN(data-set-name)
v DSN(data-set-name(member-name))
174 Enterprise COBOL for z/OS, V5.2 Programming Guide
data-set-name must be fully qualified and cannot be a temporary data set (that is, it
must not start with &).
Restriction: You cannot create a PDS or PDSE by using an environment variable.
You can optionally specify the following attributes in any order after DSN:
v A disposition value, one of: NEW, OLD, SHR, or MOD
v TRACKS or CYL
v SPACE(nnn,mmm)
v VOL(volume-serial)
v UNIT(type)
v KEEP, DELETE, CATALOG, or UNCATALOG
v STORCLAS(storage-class)
v MGMTCLAS(management-class)
v DATACLAS(data-class)
You can use either an environment variable or a DD definition to define a file in the
z/OS UNIX file system. To do so, define one of the following items with a name
that matches the external name in the ASSIGN clause:
v A DD allocation that uses PATH=absolute-path-name and FILEDATA=BINARY
v An environment variable with a value PATH(pathname), where pathname is an
absolute path name (starting with /)
For compatibility with releases of COBOL before COBOL for OS/390 & VM
Version 2 Release 2, you can also specify FILEDATA=TEXT when using a DD allocation
for z/OS UNIX files, but this use is not recommended. To process text files in the
z/OS UNIX file system, use LINE SEQUENTIAL organization. If you do use QSAM to
process text files in the z/OS UNIX file system, you cannot use environment
variables to define the files.
When you define a QSAM file, use the parameters as shown below.
Table 20. QSAM file allocation
What you want to do DD parameter to use EV keyword to use
Name the file. DSNAME (data-set name) DSN
Select the type and quantity of UNIT UNIT for type only
input-output devices to be
allocated for the file.
Give instructions for the volume in VOLUME (or let the system VOL
which the file will reside and for choose an output volume)
volume mounting.
Allocate the type and amount of SPACE SPACE for the amount of
space the file needs. (Only for space (primary and
direct-access storage devices.) secondary only); TRACKS or
CYL for the type of space
Specify the type and some of the LABEL n/a
contents of the label associated
with the file.
Indicate whether you want to DISP NEW, OLD, SHR, MOD plus
catalog, pass, or keep the file after KEEP, DELETE, CATALOG, or
the job step is completed. UNCATALOG
Chapter 9. Processing QSAM files 175
Table 20. QSAM file allocation (continued)
What you want to do DD parameter to use EV keyword to use
Complete any data control block DCB subparameters n/a
information that you want to add.
Some of the information about the QSAM file must always be coded in the
FILE-CONTROL paragraph, the FD entry, and other COBOL clauses. Other
information must be coded in the DD statement or environment variable for output
files. For input files, the system can obtain information from the file label (for
standard label files). If DCB information is provided in the DD statement for input
files, it overrides information on the data-set label. For example, the amount of
space allocated for a new direct-access device file can be set in the DD statement by
the SPACE parameter.
You cannot express certain characteristics of QSAM files in the COBOL language,
but you can code them in the DD statement for the file by using the DCB parameter.
Use the subparameters of the DCB parameter to provide information that the system
needs for completing the data set definition, including the following items:
v Block size (BLKSIZE=), if BLOCK CONTAINS 0 RECORDS was coded at compile time
(recommended)
v Options to be executed if an error occurs in reading or writing a record
v TRACK OVERFLOW or standard blocks
v Mode of operation for a card reader or punch
DCB attributes coded for a DD DUMMY do not override those coded in the FD entry of
your COBOL program.
Example: setting and accessing environment variables on page 456
RELATED TASKS
Setting block sizes on page 167
Defining QSAM files and records in COBOL on page 159
Allocating files on page 157
RELATED REFERENCES
Parameters for creating QSAM files on page 177
MVS Program Management: User's Guide and Reference
176 Enterprise COBOL for z/OS, V5.2 Programming Guide
Parameters for creating QSAM files
The following DD statement parameters are frequently used to create QSAM files.
dataset-name
DSNAME=
dataset-name(member-name)
DSN= &&name
&&name(member-name)
UNIT= ( name[,unitcount] )
VOLUME= ( [PRIVATE] [,RETAIN] [,vol-sequence-num] [,volume-count] ...
VOL=
... ,SER=(volume-serial[,volume-serial]...)
(
,REF= dsname
*.ddname
*.stepname.ddname
*.stepname.procstep.ddname
SPACE= ( TRK ,(primary-quantity[,secondary-quantity][,directory-quantity]))
CYL
average-record-length
LABEL= ( [Data-set-sequence-number,] NL ,EXPDT= yyddd (
SL yyyy/ddd
SUL ,RETPD=xxxx
DISP= ( NEW ,DELETE ,DELETE )
MOD ,KEEP ,KEEP
,PASS ,CATLG
,CATLG
DCB= ( subparameter-list )
RELATED TASKS
Defining and allocating QSAM files on page 174
Retrieving QSAM files
You retrieve QSAM files, cataloged or not, by using job control statements or
environment variables.
Cataloged files
All data set information, such as volume and space, is stored in the catalog
and file label. All you have to code are the data set name and a
disposition. When you use a DD statement, this is the DSNAME parameter and
the DISP parameter. When you use an environment variable, this is the DSN
parameter and one of the parameters OLD, SHR, or MOD.
Noncataloged files
Some information is stored in the file label, but you must code the unit
and volume information, and the dsname and disposition.
If you are using JCL, and you created the file in the current job step or in a
previous job step in the current job, you can refer to the previous DD statement for
most of the data set information. You do, however, need to code DSNAME and DISP.
RELATED REFERENCES
Parameters for retrieving QSAM files on page 178
Chapter 9. Processing QSAM files 177
Parameters for retrieving QSAM files
The following DD statement parameters are used to retrieve previously created files.
RELATED TASKS
Retrieving QSAM files on page 177
Ensuring that file attributes match your program
When the fixed file attributes in the DD statement or the data-set label and the
attributes that are coded for that file in the SELECT clause and FD entry are not
consistent, an OPEN statement in your program might not work.
Mismatches in the attributes for file organization, record format (fixed or variable),
record length, or the code set result in file status code 39 and the failure of the
OPEN statement. An exception exists for files in the z/OS UNIX file system:
mismatches in record format and record length do not cause an error.
To prevent common file status 39 problems, follow the guidelines for processing
existing or new files.
If you have not made a file available with a DD statement or a TSO ALLOCATE
command, and your COBOL program specifies that the file be created, Enterprise
COBOL dynamically allocates the file. When the file is opened, the file attributes
that are coded in your program are used. You do not have to worry about file
attribute conflicts.
Remember that information in the JCL or environment variable overrides
information in the data-set label.
RELATED TASKS
Processing existing files on page 179
Processing new files on page 180
Opening QSAM files on page 170
178 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
FILE SECTION entries on page 12
Processing existing files
When your program processes an existing file, code the description of the file in
your COBOL program to be consistent with the file attributes of the data set. Use
the guidelines below to define the maximum record length.
Table 21. Maximum record length of QSAM files
For this format: Specify this:
V or S Exactly 4 bytes less than the length attribute of the data set
F Same value as the length attribute of the data set
U Same value as the length attribute of the data set
The easiest way to define variable-length (format-V) records in a program is to use
the RECORD IS VARYING FROM integer-1 TO integer-2 clause in the FD entry and set an
appropriate value for integer-2. Express the integer sizes in bytes regardless of the
underlying USAGE of the data items in the record. For example, assume that you
determine that the length attribute of the data set is 104 bytes (LRECL=104).
Remembering that the maximum record length is determined from the RECORD IS
VARYING clause and not from the level-01 record descriptions, you could define a
format-V file in your program with this code:
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS V
RECORD IS VARYING FROM 4 TO 100 CHARACTERS.
01 COMMUTER-RECORD-A PIC X(4).
01 COMMUTER-RECORD-B PIC X(75).
Assume that the existing file in the previous example was format-U instead of
format-V. If the 104 bytes are all user data, you could define the file in your
program with this code:
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS U
RECORD IS VARYING FROM 4 TO 104 CHARACTERS.
01 COMMUTER-RECORD-A PIC X(4).
01 COMMUTER-RECORD-B PIC X(75).
To define fixed-length records in your program, either code the RECORD CONTAINS
integer clause, or omit this clause and code all level-01 record descriptions to be the
same fixed size. In either case, use a value that equals the value of the length
attribute of the data set. If you intend to use the same program to process different
files at run time, and those files have differing fixed lengths, avoid record-length
conflicts by coding RECORD CONTAINS 0.
If the existing file is an ASCII data set (DCB=(OPTCD=Q)), you must use the CODE-SET
clause in the FD entry for the file.
RELATED TASKS
Processing new files on page 180
Requesting fixed-length format on page 161
Requesting variable-length format on page 162
Requesting undefined format on page 166
Opening QSAM files on page 170
Chapter 9. Processing QSAM files 179
RELATED REFERENCES
FILE SECTION entries on page 12
Processing new files
If your COBOL program writes records to a new file that will be made available
before the program runs, ensure that the file attributes in the DD statement, the
environment variable, or the allocation do not conflict with the attributes in the
program.
Usually you need to code only a minimum of parameters when predefining files.
But if you need to explicitly set a length attribute for the data set (for example, you
are using an ISPF allocation panel, or your DD statement is for a batch job in which
the program uses RECORD CONTAINS 0), follow these guidelines:
v For format-V and format-S files, set a length attribute that is 4 bytes larger than
that defined in the program.
v For format-F and format-U files, set a length attribute that is the same as that
defined in the program.
v If you open the file as OUTPUT and write it to a printer, the compiler might add 1
byte to the record length to account for the carriage-control character, depending
on the ADV compiler option and the language used in your program. In such a
case, take the added byte into account when coding the LRECL value.
For example, if your program contains the following code for a file that has
variable-length records, the LRECL value in the DD statement or allocation should be
54.
FILE SECTION.
FD COMMUTER-FILE-MST
RECORDING MODE IS V
RECORD CONTAINS 10 TO 50 CHARACTERS.
01 COMMUTER-RECORD-A PIC X(10).
01 COMMUTER-RECORD-B PIC X(50).
RELATED TASKS
Processing existing files on page 179
Requesting fixed-length format on page 161
Requesting variable-length format on page 162
Requesting undefined format on page 166
Opening QSAM files on page 170
Dynamically creating QSAM files on page 171
RELATED REFERENCES
FILE SECTION entries on page 12
Using striped extended-format QSAM data sets
Striped extended-format QSAM data sets can benefit applications that process files
that have large amounts of data or in which the time needed for I/O operations
significantly affects overall performance.
A striped extended-format QSAM data set is an extended-format QSAM data set that
is spread over multiple volumes, thus allowing parallel data access.
For you to gain the maximum benefit from using QSAM striped data sets, z/OS
DFSMS needs to be able to allocate the required number of buffers above the 16
MB line. When you develop applications that contain files allocated to QSAM
striped data sets, follow these guidelines:
180 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Avoid using a QSAM striped data set for a file that cannot have buffers
allocated above the 16 MB line.
v Omit the RESERVE clause in the FILE-CONTROL entry for the file. Doing so lets
z/OS DFSMS determine the optimum number of buffers for the data set.
v Compile your program with the DATA(31) and RENT compiler options, and make
| the program object AMODE 31.
v Specify the ALL31(ON) runtime option if the file is an EXTERNAL file with format-F,
format-V, or format-U records.
Note that all striped data sets are extended-format data sets, but not all
extended-format data sets are striped.
RELATED TASKS
z/OS DFSMS: Using Data Sets
Allocation of buffers for QSAM files
z/OS DFSMS automatically allocates buffers for storing input and output for a
QSAM file above or below the 16 MB line as appropriate for the file.
Most QSAM files have buffers allocated above the 16 MB line. Exceptions are:
v Programs running in AMODE 24.
v Programs compiled with the DATA(24) and RENT options.
v Programs compiled with the NORENT option.
v EXTERNAL files when the ALL31(OFF) runtime option is specified. To specify the
ALL31(ON) runtime option, all programs in the run unit must be capable of
running in 31-bit addressing mode.
v Files allocated to the TSO terminal.
v A file with format-S (spanned) records, if the file is any of the following ones:
An EXTERNAL file (even if ALL31(ON) is specified)
A file specified in a SAME RECORD AREA clause of the I-O-CONTROL paragraph
A blocked file that is opened I-O and updated using the REWRITE statement
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Using striped extended-format QSAM data sets on page 180
Accessing z/OS UNIX files using QSAM
You can process byte-stream files in the z/OS UNIX file system as ORGANIZATION
SEQUENTIAL files using QSAM. To do this, specify as the assignment-name in the
ASSIGN clause either a ddname or an environment-variable name.
ddname
A DD allocation that identifies the file with the keywords PATH= and
FILEDATA=BINARY
Environment-variable name
An environment variable that holds the runtime value of the z/OS UNIX
file system path for the file
Observe the following restrictions:
Chapter 9. Processing QSAM files 181
v Spanned record format is not supported.
v OPEN I-O and REWRITE are not supported. If you attempt one of these operations,
one of the following file-status conditions results:
37 from OPEN I-O
47 from REWRITE (because you could not have successfully opened the file as
I-O)
Usage notes
v File status 39 (fixed file attribute conflict) is not enforced for either of the
following types of conflicts:
Record-length conflict
Record-type conflict (fixed as opposed to variable)
v A READ returns the number of bytes of the maximum logical record size for the
file except for the last record, which might be shorter.
For example, suppose that a file definition has level-01 record descriptions of 3,
5, and 10 bytes long, and you write the following three records: 'abc', 'defgh',
and 'ijklmnopqr', in that order. The first READ of this file returns 'abcdefghij', the
second READ returns 'klmnopqr ', and the third READ results in the AT END
condition.
For compatibility with releases of IBM COBOL before COBOL for OS/390 & VM
Version 2 Release 2, you can also specify FILEDATA=TEXT when using a DD allocation
for z/OS UNIX files, but this use is not recommended. To process text files in the
z/OS UNIX file system, use LINE SEQUENTIAL organization. If you use QSAM to
process text files in the z/OS UNIX file system, you cannot use environment
variables to define the files.
RELATED TASKS
Allocating files on page 157
Defining and allocating QSAM files on page 174
z/OS DFSMS: Using Data Sets (Using HFS data sets)
Processing QSAM ASCII files on tape
If your program processes a QSAM ASCII file, you must request the ASCII
alphabet, define the record formats, and define the ddname (with JCL).
In addition, if your program processes signed numeric data items from ASCII files,
define the numeric data as zoned decimal items with separate signs, that is, as
USAGE DISPLAY and with the SEPARATE phrase of the SIGN clause.
The CODEPAGE compiler option has no effect on the code page used for conversions
between ASCII and EBCDIC for ASCII tape support. For information about how
CCSIDs used for the ASCII tape support are selected and what the default CCSIDs
are, see the z/OS DFSMS documentation.
Requesting the ASCII alphabet: In the SPECIAL-NAMES paragraph, code STANDARD-1
for ASCII:
ALPHABET-NAME IS STANDARD-1
In the FD entry for the file, code:
CODE-SET IS ALPHABET-NAME
182 Enterprise COBOL for z/OS, V5.2 Programming Guide
Defining the record formats: Process QSAM ASCII tape files with any of these
record formats:
v Fixed length (format F)
v Undefined (format U)
v Variable length (format V)
If you use variable-length records, you cannot explicitly code format D; instead,
code RECORDING MODE V. The format information is internally converted to D mode.
D-mode records have a 4-byte record descriptor for each record.
Defining the ddname: Under z/OS, processing ASCII files requires special JCL
coding. Code these subparameters of the DCB parameter in the DD statement:
BUFOFF=[L|n]
L A 4-byte block prefix that contains the block length (including the
block prefix)
n The length of the block prefix:
v For input, from 0 through 99
v For output, either 0 or 4
Use this value if you coded BLOCK CONTAINS 0.
BLKSIZE=n
n The size of the block, including the length of the block prefix
LABEL=[AL|AUL|NL]
AL American National Standard (ANS) labels
AUL ANS and user labels
NL No labels
OPTCD=Q
Q This value is required for ASCII files and is the default if the file is
created using Enterprise COBOL.
RELATED REFERENCES
z/OS DFSMS: Using Data Sets (Character data conversion)
Chapter 9. Processing QSAM files 183
184 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 10. Processing VSAM files
Virtual storage access method (VSAM) is an access method for files on
direct-access storage devices. With VSAM you can load files, retrieve records from
files, update files, and add, replace, and delete records in files.
VSAM processing has these advantages over QSAM:
v Protection of data against unauthorized access
v Compatibility across systems
v Independence of devices (no need to be concerned with block size and other
control information)
v Simpler JCL (information needed by the system is provided in integrated
catalogs)
v Ability to use indexed file organization or relative file organization
The following table shows how VSAM terms differ from COBOL terms and other
terms that you might be familiar with.
Table 22. Comparison of VSAM, COBOL, and non-VSAM terminology
VSAM term COBOL term Similar non-VSAM term
Data set File Data set
Entry-sequenced data set (ESDS) Sequential file QSAM data set
Key-sequenced data set (KSDS) Indexed file ISAM data set
Relative-record data set (RRDS) Relative file BDAM data set
Control interval Block
Control interval size (CISZ) Block size
Buffers (BUFNI/BUFND) BUFNO
Access method control block (ACB) Data control block (DCB)
Cluster (CL) Data set
Cluster definition Data-set allocation
AMP parameter of JCL DD statement DCB parameter of JCL DD statement
Record size Record length
The term file in this VSAM documentation refers to either a COBOL file or a
VSAM data set.
If you have complex requirements or frequently use VSAM, se the VSAM
publications for your operating system.
RELATED CONCEPTS
VSAM files on page 186
RELATED TASKS
Defining VSAM file organization and records on page 187
Coding input and output statements for VSAM files on page 193
Handling errors in VSAM files on page 201
Protecting VSAM files with a password on page 202
Copyright IBM Corp. 1991, 2015 185
Working with VSAM data sets under z/OS and z/OS UNIX on page 202
Improving VSAM performance on page 209
RELATED REFERENCES
z/OS DFSMS: Using Data Sets
z/OS DFSMS Macro Instructions for Data Sets
z/OS DFSMS: Access Method Services for Catalogs
| Allocation of record areas for VSAM files on page 209
| Extended addressability support on page 211
VSAM files
The physical organization of VSAM data sets differs considerably from the
organizations used by other access methods.
VSAM data sets are held in control intervals (CI) and control areas (CA). The size
of the CI and CA is normally determined by the access method; and the way in
which they are used is not visible to you.
You can use three types of file organization with VSAM:
VSAM sequential file organization
(Also referred to as VSAM ESDS (entry-sequenced data set) organization.) In
VSAM sequential file organization, the records are stored in the order in
which they were entered.
VSAM entry-sequenced data sets are equivalent to QSAM sequential files.
The order of the records is fixed.
VSAM indexed file organization
(Also referred to as VSAM KSDS (key-sequenced data set) organization.) In a
VSAM indexed file (KSDS), the records are ordered according to the
collating sequence of an embedded prime key field, which you define. The
prime key consists of one or more consecutive characters in the records.
The prime key uniquely identifies the record and determines the sequence
in which it is accessed with respect to other records. A prime key for a
record might be, for example, an employee number or an invoice number.
VSAM relative file organization
(Also referred to as VSAM fixed-length or variable-length RRDS
(relative-record data set) organization.) A VSAM relative-record data set
(RRDS) contains records ordered by their relative key. The relative key is the
relative record number, which represents the location of the record relative
to where the file begins. The relative record number identifies the fixed- or
variable-length record.
In a VSAM fixed-length RRDS, records are placed in a series of
fixed-length slots in storage. Each slot is associated with a relative record
number. For example, in a fixed-length RRDS that contains 10 slots, the
first slot has a relative record number of 1, and the tenth slot has a relative
record number of 10.
In a VSAM variable-length RRDS, the records are ordered according to
their relative record number. Records are stored and retrieved according to
the relative record number that you set.
186 Enterprise COBOL for z/OS, V5.2 Programming Guide
Throughout this information, the term VSAM relative-record data set (or
RRDS) is used to mean both relative-record data sets with fixed-length
records and with variable-length records, unless they need to be
differentiated.
The following table compares the characteristics of the different types of VSAM
data sets.
Table 23. Comparison of VSAM data-set types
Entry-sequenced data set Key-sequenced data set Relative-record data set
Characteristic (ESDS) (KSDS) (RRDS)
Order of records Order in which they are Collating sequence by key Order of relative record
written field number
Access Sequential By key through an index By relative record number,
which is handled like a key
Alternate indexes Can have one or more Can have one or more Cannot have alternate indexes
alternate indexes, although alternate indexes
not supported in COBOL
Relative byte address RBA cannot change. RBA can change. RRN cannot change.
(RBA) and relative
record number (RRN)
of a record
Space for adding Uses space at the end of Uses distributed free space For fixed-length RRDS, uses
records the data set for inserting records and empty slots in the data set
changing their lengths in
place For variable-length RRDS, uses
distributed free space and
changes the lengths of added
records in place
Space from deleting You cannot delete a record, Space from a deleted or Space from a deleted record
records but you can reuse its space shortened record is can be reused.
for a record of the same automatically reclaimed in a
length. control interval.
Spanned records Can have spanned records Can have spanned records Cannot have spanned records
Reuse as work file Can be reused unless it has Can be reused unless it has Can be reused
an alternate index, is an alternate index, is
associated with key ranges, associated with key ranges, or
or exceeds 123 extents per exceeds 123 extents per
volume volume
RELATED TASKS
Specifying sequential organization for VSAM files on page 188
Specifying indexed organization for VSAM files on page 188
Specifying relative organization for VSAM files on page 190
Defining VSAM files on page 203
Defining VSAM file organization and records
Use an entry in the FILE-CONTROL paragraph in the ENVIRONMENT DIVISION to define
the file organization and access modes for the VSAM files in your COBOL
program.
Chapter 10. Processing VSAM files 187
In the FILE SECTION of the DATA DIVISION, code a file description (FD) entry for the
file. In the associated record description entry or entries, define the record-name and
record length. Code the logical size of the records by using the RECORD clause.
Important: You can process VSAM data sets in Enterprise COBOL programs only
after you define them by using access method services.
Table 24. VSAM file organization, access mode, and record format
Sequential Random Dynamic Fixed Variable
File organization access access access length length
VSAM sequential Yes No No Yes Yes
(ESDS)
VSAM indexed Yes Yes Yes Yes Yes
(KSDS)
VSAM relative Yes Yes Yes Yes Yes
(RRDS)
RELATED TASKS
Specifying sequential organization for VSAM files
Specifying indexed organization for VSAM files
Specifying relative organization for VSAM files on page 190
Specifying access modes for VSAM files on page 191
Defining record lengths for VSAM files on page 191
Using file status keys on page 245
Using VSAM status codes (VSAM files only) on page 246
Defining VSAM files on page 203
Specifying sequential organization for VSAM files
Identify VSAM ESDS files in a COBOL program with the ORGANIZATION IS
SEQUENTIAL clause. You can access (read or write) records in sequential files only
sequentially.
After you place a record in the file, you cannot shorten, lengthen, or delete it.
However, you can update (REWRITE) a record if the length does not change. New
records are added at the end of the file.
The following example shows typical FILE-CONTROL entries for a VSAM sequential
file (ESDS):
SELECT S-FILE
ASSIGN TO SEQUENTIAL-AS-FILE
ORGANIZATION IS SEQUENTIAL
ACCESS IS SEQUENTIAL
FILE STATUS IS FSTAT-CODE VSAM-CODE.
RELATED CONCEPTS
VSAM files on page 186
Specifying indexed organization for VSAM files
Identify a VSAM KSDS file in a COBOL program by using the ORGANIZATION IS
INDEXED clause. Code a prime key for the record by using the RECORD KEY clause.
You can also use alternate keys and an alternate index.
RECORD KEY IS data-name
188 Enterprise COBOL for z/OS, V5.2 Programming Guide
In the example above, data-name is the name of the prime key field as you define it
in the record description entry in the DATA DIVISION. The prime key data item can
be class alphabetic, alphanumeric, DBCS, numeric, or national. If it has USAGE
NATIONAL, the prime key can be category national, or can be a national-edited,
numeric-edited, national decimal, or national floating-point data item. The collation
of record keys is based on the binary value of the keys regardless of the class or
category of the keys.
The following example shows the statements for a VSAM indexed file (KSDS) that
is accessed dynamically. In addition to the primary key, COMMUTER-NO, an alternate
key, LOCATION-NO, is specified:
SELECT I-FILE
ASSIGN TO INDEXED-FILE
ORGANIZATION IS INDEXED
ACCESS IS DYNAMIC
RECORD KEY IS IFILE-RECORD-KEY
ALTERNATE RECORD KEY IS IFILE-ALTREC-KEY
FILE STATUS IS FSTAT-CODE VSAM-CODE.
RELATED CONCEPTS
VSAM files on page 186
RELATED TASKS
Using alternate keys
Using an alternate index
RELATED REFERENCES
RECORD KEY clause (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Using alternate keys
In addition to the primary key, you can code one or more alternate keys for a
VSAM KSDS file. By using alternate keys, you can access an indexed file to read
records in some sequence other than the prime-key sequence.
Alternate keys do not need to be unique. More than one record could be accessed
if alternate keys are coded to allow duplicates. For example, you could access the
file through employee department rather than through employee number.
You define the alternate key in your COBOL program with the ALTERNATE RECORD
KEY clause:
ALTERNATE RECORD KEY IS data-name
In the example above, data-name is the name of the alternate key field as you
define it in the record description entry in the DATA DIVISION. Alternate key data
items, like prime key data items, can be class alphabetic, alphanumeric, DBCS,
numeric, or national. The collation of alternate keys is based on the binary value of
the keys regardless of the class or category of the keys.
Using an alternate index
To use an alternate index for a VSAM KSDS file, you need to define a data set
called the alternate index (AIX) by using access method services.
The AIX contains one record for each value of a given alternate key. The records
are in sequential order by alternate-key value. Each record contains the
corresponding primary keys of all records in the associated indexed files that
contain the alternate-key value.
Chapter 10. Processing VSAM files 189
RELATED TASKS
Creating alternate indexes on page 204
Specifying relative organization for VSAM files
Identify VSAM RRDS files in a COBOL program by using the ORGANIZATION IS
RELATIVE clause. Use the RELATIVE KEY IS clause to associate each logical record
with its relative record number.
The following example shows a relative-record data set (RRDS) that is accessed
randomly by the value in the relative key:
SELECT R-FILE
ASSIGN TO RELATIVE-FILE
ORGANIZATION IS RELATIVE
ACCESS IS RANDOM
RELATIVE KEY IS RFILE-RELATIVE-KEY
FILE STATUS IS FSTAT-CODE VSAM-CODE.
You can use a randomizing routine to associate a key value in each record with the
relative record number for that record. Although there are many techniques to
convert a record key to a relative record number, the most commonly used is the
division/remainder technique. With this technique, you divide the key by a value
equal to the number of slots in the data set to produce a quotient and remainder.
When you add one to the remainder, the result is a valid relative record number.
Alternate indexes are not supported for VSAM RRDS.
RELATED CONCEPTS
VSAM files on page 186
Fixed-length and variable-length RRDS
RELATED TASKS
Using variable-length RRDS
Defining VSAM files on page 203
Fixed-length and variable-length RRDS
In an RRDS that has fixed-length records, each record occupies one slot. You store
and retrieve records according to the relative record number of the slot. A
variable-length RRDS does not have slots; instead, the free space that you define
allows for more efficient record insertions.
When you load an RRDS that has fixed-length records, you have the option of
skipping over slots and leaving them empty. When you load an RRDS that has
variable-length records, you can skip over relative record numbers.
Using variable-length RRDS
To use relative-record data sets (RRDS) that have variable-length records, you must
use VSAM variable-length RRDS support.
Do these steps:
1. Define the file with the ORGANIZATION IS RELATIVE clause.
2. Use FD entries to describe the records with variable-length sizes.
3. Use the NOSIMVRD runtime option.
4. Define the VSAM file through access-method services as an RRDS.
190 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Defining VSAM files on page 203
RELATED REFERENCES
z/OS DFSMS: Access Method Services for Catalogs
Specifying access modes for VSAM files
You can access records in VSAM sequential files only sequentially. You can access
records in VSAM indexed and relative files in three ways: sequentially, randomly,
or dynamically.
For sequential access, code ACCESS IS SEQUENTIAL in the FILE-CONTROL entry.
Records in indexed files are then accessed in the order of the key field selected
(either primary or alternate). Records in relative files are accessed in the order of
the relative record numbers.
For random access, code ACCESS IS RANDOM in the FILE-CONTROL entry. Records in
indexed files are then accessed according to the value you place in a key field.
Records in relative files are accessed according to the value you place in the
relative key.
For dynamic access, code ACCESS IS DYNAMIC in the FILE-CONTROL entry. Dynamic
access is a mixed sequential-random access in the same program. Using dynamic
access, you can write one program to perform both sequential and random
processing, accessing some records in sequential order and others by their keys.
Example: using dynamic access with VSAM files
RELATED TASKS
Reading records from a VSAM file on page 198
Example: using dynamic access with VSAM files
Suppose that you have an indexed file of employee records, and the employee's
hourly wage forms the record key.
If your program processes those employees who earn between $15.00 and $20.00
per hour and those who earn $25.00 per hour and above, using dynamic access of
VSAM files, the program would:
1. Retrieve the first record randomly (with a random-retrieval READ) based on the
key of 1500.
2. Read sequentially (using READ NEXT) until the salary field exceeds 2000.
3. Retrieve the next record randomly, based on a key of 2500.
4. Read sequentially until the end of the file.
RELATED TASKS
Reading records from a VSAM file on page 198
Defining record lengths for VSAM files
You can define VSAM records to be fixed or variable in length. COBOL determines
the record format from the RECORD clause and the record descriptions that are
associated with the FD entry for a file.
Chapter 10. Processing VSAM files 191
Because the concept of blocking has no meaning for VSAM files, you can omit the
BLOCK CONTAINS clause. The clause is syntax-checked, but it has no effect on how
the program runs.
RELATED TASKS
Defining fixed-length records
Defining variable-length records
Enterprise COBOL Migration Guide
RELATED REFERENCES
FILE SECTION entries on page 12
Defining fixed-length records
To define VSAM records as fixed length, use one of these coding options.
Table 25. Definition of VSAM fixed-length records
Clause
RECORD clause format Record length Comments
Code RECORD CONTAINS 1 Fixed in size with a The lengths of the
integer. length of integer-3 bytes level-01 record
description entries
associated with the file
do not matter.
Omit the RECORD clause, The fixed size that you
but code all level-01 coded
records that are
associated with the file as
the same size; and code
none with an OCCURS
DEPENDING ON clause.
RELATED REFERENCES
RECORD clause (Enterprise COBOL Language Reference)
Defining variable-length records
To define VSAM records as variable length, use one of these coding options.
Table 26. Definition of VSAM variable-length records
Clause
RECORD clause format Maximum record length Comments
Code RECORD IS VARYING 3 integer-7 bytes The lengths of the
FROM integer-6 TO integer-7. level-01 record
description entries
associated with the file
do not matter.
Code RECORD IS VARYING. 3 Size of the largest level-01 The compiler determines
record description entry the maximum record
associated with the file length.
Code RECORD CONTAINS 2 integer-5 bytes The minimum record
integer-4 TO integer-5. length is integer-4 bytes.
192 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 26. Definition of VSAM variable-length records (continued)
Clause
RECORD clause format Maximum record length Comments
Omit the RECORD clause, Size of the largest level-01 The compiler determines
but code multiple level-01 record description entry the maximum record
records that are associated with the file length.
associated with the file
and are of different sizes
or contain an OCCURS
DEPENDING ON clause.
When you specify a READ INTO statement for a format-V file, the record size that is
read for that file is used in the MOVE statement generated by the compiler.
Consequently, you might not get the result you expect if the record read in does
not correspond to the level-01 record description. All other rules of the MOVE
statement apply. For example, when you specify a MOVE statement for a format-V
record read in by the READ statement, the size of the record corresponds to its
level-01 record description.
RELATED REFERENCES
RECORD clause (Enterprise COBOL Language Reference)
Coding input and output statements for VSAM files
Use the COBOL statements shown below to process VSAM files.
OPEN To connect the VSAM data set to your COBOL program for processing.
WRITE To add records to a file or load a file.
START To establish the current location in the cluster for a READ NEXT statement.
START does not retrieve a record; it only sets the current record pointer.
READ and READ NEXT
To retrieve records from a file.
REWRITE
To update records.
DELETE To logically remove records from indexed and relative files only.
CLOSE To disconnect the VSAM data set from your program.
All of the following factors determine which input and output statements you can
use for a given VSAM data set:
v Access mode (sequential, random, or dynamic)
v File organization (ESDS, KSDS, or RRDS)
v Mode of OPEN statement (INPUT, OUTPUT, I-O, or EXTEND)
The following table shows the possible combinations of statements and open
modes for sequential files (ESDS). The X indicates that you can use a statement
with the open mode shown at the top of the column.
Chapter 10. Processing VSAM files 193
Table 27. I/O statements for VSAM sequential files
COBOL
Access mode statement OPEN INPUT OPEN OUTPUT OPEN I-O OPEN EXTEND
Sequential OPEN X X X X
WRITE X X
START
READ X X
REWRITE X
DELETE
CLOSE X X X X
The following table shows the possible combinations of statements and open
modes that you can use with indexed (KSDS) files and relative (RRDS) files. The X
indicates that you can use the statement with the open mode shown at the top of
the column.
Table 28. I/O statements for VSAM relative and indexed files
COBOL
Access mode statement OPEN INPUT OPEN OUTPUT OPEN I-O OPEN EXTEND
Sequential OPEN X X X X
WRITE X X
START X X
READ X X
REWRITE X
DELETE X
CLOSE X X X X
Random OPEN X X X
WRITE X X
START
READ X X
REWRITE X
DELETE X
CLOSE X X X
Dynamic OPEN X X X
WRITE X X
START X X
READ X X
REWRITE X
DELETE X
CLOSE X X X
The fields that you code in the FILE STATUS clause are updated by VSAM after
each input-output statement to indicate the success or failure of the operation.
194 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED CONCEPTS
File position indicator
RELATED TASKS
Opening a file (ESDS, KSDS, or RRDS)
Reading records from a VSAM file on page 198
Updating records in a VSAM file on page 199
Adding records to a VSAM file on page 199
Replacing records in a VSAM file on page 200
Deleting records from a VSAM file on page 200
Closing VSAM files on page 200
RELATED REFERENCES
File status key (Enterprise COBOL Language Reference)
File position indicator
The file position indicator marks the next record to be accessed for sequential
COBOL requests. You do not set the file position indicator in your program. It is
set by successful OPEN, START, READ, and READ NEXT statements.
Subsequent READ or READ NEXT requests use the established file position indicator
location and update it.
The file position indicator is not used or affected by the output statements WRITE,
REWRITE, or DELETE. The file position indicator has no meaning for random
processing.
RELATED TASKS
Reading records from a VSAM file on page 198
Opening a file (ESDS, KSDS, or RRDS)
Before you can use WRITE, START, READ, REWRITE, or DELETE statements to process
records in a file, you must first open the file with an OPEN statement.
Whether a file is available or optional affects OPEN processing, file creation, and the
resulting file status key. For example, if you open in EXTEND, I-O, or INPUT mode a
nonexistent non-OPTIONAL file, the result is an OPEN error, and file status 35 is
returned. If the file is OPTIONAL, however, the same OPEN statement returns file
status 05, and, for open modes EXTEND and I-O, creates the file.
An OPEN operation works successfully only if you set fixed file attributes in the DD
statement or data-set label for a file, and specify consistent attributes for the file in
the SELECT clause and FD entries of your COBOL program. Mismatches in the
following items result in a file status key 39 and the failure of the OPEN statement:
v Attributes for file organization (sequential, relative, or indexed)
v Prime record key
v Alternate record keys
v Maximum record size
v Record type (fixed or variable)
How you code the OPEN statement for a VSAM file depends on whether the file is
empty (a file that has never contained records) or loaded. For either type of file,
your program should check the file status key after each OPEN statement.
Chapter 10. Processing VSAM files 195
RELATED TASKS
Opening an empty file
Opening a loaded file (a file with records) on page 197
RELATED REFERENCES
Statements to load records into a VSAM file on page 197
Opening an empty file
To open a file that has never contained records (an empty file), use a form of the
OPEN statement.
Depending on the type of file that you are opening, use one of the following
statements:
v OPEN OUTPUT for ESDS files.
v OPEN OUTPUT or OPEN EXTEND for KSDS and RRDS files. (Either coding has the
same effect.) If you coded the file for random or dynamic access and the file is
optional, you can use OPEN I-O.
Optional files are files that are not necessarily available each time a program is run.
You can define files opened in INPUT, I-O, or OUTPUT mode as optional by defining
them with the SELECT OPTIONAL clause in the FILE-CONTROL paragraph.
Initially loading a file sequentially: Initially loading a file means writing records
into the file for the first time. Doing so is not the same as writing records into a
file from which all previous records have been deleted. To initially load a VSAM
file:
1. Open the file.
2. Use sequential processing (ACCESS IS SEQUENTIAL). (Sequential processing is
faster than random or dynamic processing.)
3. Use WRITE to add a record to the file.
Using OPEN OUTPUT to load a VSAM file significantly improves the performance of
your program. Using OPEN I-O or OPEN EXTEND has a negative effect on the
performance of your program.
When you load VSAM indexed files sequentially, you optimize both loading
performance and subsequent processing performance, because sequential
processing maintains user-defined free space. Future insertions will be more
efficient.
With ACCESS IS SEQUENTIAL, you must write the records in ascending RECORD KEY
order.
When you load VSAM relative files sequentially, the records are placed in the file
in the ascending order of relative record numbers.
Initially loading a file randomly or dynamically: You can use random or dynamic
processing to load a file, but they are not as efficient as sequential processing.
Because VSAM does not support random or dynamic processing, COBOL has to
perform some extra processing to enable you to use ACCESS IS RANDOM or ACCESS
IS DYNAMIC with OPEN OUTPUT or OPEN I-O. These steps prepare the file for use and
give it the status of a loaded file because it has been used at least once.
196 Enterprise COBOL for z/OS, V5.2 Programming Guide
In addition to extra overhead for preparing files for use, random processing does
not consider any user-defined free space. As a result, any future insertions might
be inefficient. Sequential processing maintains user-defined free space.
When you are loading an extended-format VSAM data set, file status 30 will occur
for the OPEN if z/OS DFSMS system-managed buffering sets the buffering to local
shared resources (LSR). To successfully load the VSAM data set in this case, specify
ACCBIAS=USER in the DD AMP parameter for the VSAM data set to bypass
system-managed buffering.
Loading a VSAM data set with access method services: You can load or update a
VSAM data set by using the access method services REPRO command. Use REPRO
whenever possible.
RELATED TASKS
Opening a loaded file (a file with records)
RELATED REFERENCES
Statements to load records into a VSAM file
z/OS DFSMS: Access Method Services for Catalogs (REPRO)
Statements to load records into a VSAM file
Use the statements shown below to load records into a VSAM file.
Table 29. Statements to load records into a VSAM file
Division ESDS KSDS RRDS
ENVIRONMENT SELECT SELECT SELECT
DIVISION ASSIGN ASSIGN ASSIGN
FILE STATUS ORGANIZATION IS INDEXED ORGANIZATION IS RELATIVE
PASSWORD RECORD KEY RELATIVE KEY
ACCESS MODE ALTERNATE RECORD KEY FILE STATUS
FILE STATUS PASSWORD
PASSWORD ACCESS MODE
ACCESS MODE
DATA DIVISION FD entry FD entry FD entry
PROCEDURE OPEN OUTPUT OPEN OUTPUT OPEN OUTPUT
DIVISION OPEN EXTEND OPEN EXTEND OPEN EXTEND
WRITE WRITE WRITE
CLOSE CLOSE CLOSE
RELATED TASKS
Opening an empty file on page 196
Updating records in a VSAM file on page 199
Opening a loaded file (a file with records)
To open a file that already contains records, use OPEN INPUT, OPEN I-O, or OPEN
EXTEND.
If you open a VSAM entry-sequenced or relative-record file as EXTEND, the added
records are placed after the last existing records in the file.
If you open a VSAM key-sequenced file as EXTEND, each record you add must have
a record key higher than the highest record in the file.
Chapter 10. Processing VSAM files 197
RELATED TASKS
Opening an empty file on page 196
Working with VSAM data sets under z/OS and z/OS UNIX on page 202
RELATED REFERENCES
Statements to load records into a VSAM file on page 197
z/OS DFSMS: Access Method Services for Catalogs
Reading records from a VSAM file
Use the READ statement to retrieve (READ) records from a file. To read a record, you
must have opened the file INPUT or I-O. Your program should check the file status
key after each READ.
You can retrieve records in VSAM sequential files only in the sequence in which
they were written.
You can retrieve records in VSAM indexed and relative record files in any of the
following ways:
Sequentially
According to the ascending order of the key you are using, the RECORD KEY
or the ALTERNATE RECORD KEY, beginning at the current position of the file
position indicator for indexed files, or according to ascending relative
record locations for relative files
Randomly
In any order, depending on how you set the RECORD KEY or ALTERNATE
RECORD KEY or the RELATIVE KEY before your READ request
Dynamically
Mixed sequential and random
With dynamic access, you can switch between reading a specific record directly
and reading records sequentially, by using READ NEXT for sequential retrieval and
READ for random retrieval (by key).
When you want to read sequentially, beginning at a specific record, use START
before the READ NEXT statement to set the file position indicator to point to a
particular record. When you code START followed by READ NEXT, the next record is
read and the file position indicator is reset to the next record. You can move the
file position indicator randomly by using START, but all reading is done
sequentially from that point.
START file-name KEY IS EQUAL TO ALTERNATE-RECORD-KEY
When a direct READ is performed for a VSAM indexed file, based on an alternate
index for which duplicates exist, only the first record in the data set (base cluster)
with that alternate key value is retrieved. You need a series of READ NEXT
statements to retrieve each of the data set records with the same alternate key. A
file status code of 02 is returned if there are more records with the same alternate
key value to be read; a code of 00 is returned when the last record with that key
value has been read.
RELATED CONCEPTS
File position indicator on page 195
RELATED TASKS
Specifying access modes for VSAM files on page 191
198 Enterprise COBOL for z/OS, V5.2 Programming Guide
Updating records in a VSAM file
To update a VSAM file, use these PROCEDURE DIVISION statements.
Table 30. Statements to update records in a VSAM file
Access
method ESDS KSDS RRDS
ACCESS IS OPEN EXTEND OPEN EXTEND OPEN EXTEND
SEQUENTIAL WRITE WRITE WRITE
CLOSE CLOSE CLOSE
or or or
OPEN I-O OPEN I-O OPEN I-O
READ READ READ
REWRITE REWRITE REWRITE
CLOSE DELETE DELETE
CLOSE CLOSE
ACCESS IS Not applicable OPEN I-O OPEN I-O
RANDOM READ READ
WRITE WRITE
REWRITE REWRITE
DELETE DELETE
CLOSE CLOSE
ACCESS IS Not applicable OPEN I-O OPEN I-O
DYNAMIC READ NEXT READ NEXT
(sequential WRITE WRITE
processing) REWRITE REWRITE
START START
DELETE DELETE
CLOSE CLOSE
ACCESS IS Not applicable OPEN I-O OPEN I-O
DYNAMIC READ READ
(random WRITE WRITE
processing) REWRITE REWRITE
DELETE DELETE
CLOSE CLOSE
RELATED REFERENCES
Statements to load records into a VSAM file on page 197
Adding records to a VSAM file
Use the COBOL WRITE statement to add a record to a file without replacing any
existing records. The record to be added must not be larger than the maximum
record size that you set when you defined the file. Your program should check the
file status key after each WRITE statement.
Adding records sequentially: Use ACCESS IS SEQUENTIAL and code the WRITE
statement to add records sequentially to the end of a VSAM file that has been
opened with either OUTPUT or EXTEND.
Sequential files are always written sequentially.
For indexed files, you must write new records in ascending key sequence. If you
open the file EXTEND, the record keys of the records to be added must be higher
than the highest primary record key on the file when you opened the file.
Chapter 10. Processing VSAM files 199
For relative files, the records must be in sequence. If you include a RELATIVE KEY
data item in the SELECT clause, the relative record number of the record to be
written is placed in that data item.
Adding records randomly or dynamically: When you write records to an indexed
data set and ACCESS IS RANDOM or ACCESS IS DYNAMIC, you can write the records in
any order.
Replacing records in a VSAM file
To replace a record in a VSAM file, use REWRITE on a file that you opened as I-O. If
the file was not opened as I-O, the record is not rewritten and the status key is set
to 49. Check the file status key after each REWRITE statement.
For sequential files, the length of the replacement record must be the same as the
length of the original record. For indexed files or variable-length relative files, you
can change the length of the record you replace.
To replace a record randomly or dynamically, you do not have to first READ the
record. Instead, locate the record you want to replace as follows:
v For indexed files, move the record key to the RECORD KEY data item, and then
issue the REWRITE.
v For relative files, move the relative record number to the RELATIVE KEY data
item, and then issue the REWRITE.
Deleting records from a VSAM file
To remove an existing record from an indexed or relative file, open the file I-O and
use the DELETE statement. You cannot use DELETE on a sequential file.
When you use ACCESS IS SEQUENTIAL or the file contains spanned records, your
program must first read the record to be deleted. The DELETE then removes the
record that was read. If the DELETE is not preceded by a successful READ, the
deletion is not done and the status key value is set to 92.
When you use ACCESS IS RANDOM or ACCESS IS DYNAMIC, your program does not
have to first read the record to be deleted. To delete a record, move the key of the
record to be deleted to the RECORD KEY data item, and then issue the DELETE. Your
program should check the file status key after each DELETE statement.
Closing VSAM files
Use the CLOSE statement to disconnect your program from a VSAM file. If you try
to close a file that is already closed, you will get a logic error. Check the file status
key after each CLOSE statement.
If you do not close a VSAM file, the file is automatically closed for you under the
following conditions:
v When the run unit ends normally, all open files defined in any COBOL
programs in the run unit are closed.
v When the run unit ends abnormally, if the TRAP(ON) runtime option has been set,
all open files defined in any COBOL programs in the run unit are closed.
v When Language Environment condition handling has completed and the
application resumes in a routine other than where the condition occurred, open
files defined in any COBOL programs in the run unit that might be called again
and reentered are closed.
200 Enterprise COBOL for z/OS, V5.2 Programming Guide
You can change the location where a program resumes after a condition is
handled. To make this change, you can, for example, move the resume cursor
with the CEEMRCR callable service or use language constructs such as a C
longjmp statement.
v When you issue CANCEL for a COBOL subprogram, any open nonexternal files
defined in that program are closed.
v When a COBOL subprogram with the INITIAL attribute returns control, any
open nonexternal files defined in that program are closed.
v When a thread of a multithreaded application ends, both external and
nonexternal files that were opened from within that same thread are closed.
File status key data items in the DATA DIVISION are set when these implicit CLOSE
operations are performed, but your EXCEPTION/ERROR declarative is not invoked.
Errors: If you open a VSAM file in a multithreaded application, you must close it
from the same thread of execution. Attempting to close the file from a different
thread results in a close failure with file-status condition 90.
Handling errors in VSAM files
When an input or output statement operation fails, COBOL does not perform
corrective action for you.
All OPEN and CLOSE errors with a VSAM file, whether logical errors in your
program or input/output errors on the external storage media, return control to
your COBOL program even if you coded no DECLARATIVE and no FILE STATUS
clause.
If any other input or output statement operation fails, you choose whether your
program will continue running after a less-than-severe error.
COBOL provides these ways for you to intercept and handle certain VSAM input
and output errors:
v End-of-file phrase (AT END)
v EXCEPTION/ERROR declarative
v FILE STATUS clause (file status key and VSAM status code)
v INVALID KEY phrase
You should define a status key for each VSAM file that you define in your
program. Check the status key value after each input or output request, especially
OPEN and CLOSE.
If you do not code a file status key or a declarative, serious VSAM processing
errors will cause a message to be issued and a Language Environment condition to
be signaled, which will cause an abend if you specify the runtime option
ABTERMENC(ABEND).
RELATED TASKS
Handling errors in input and output operations on page 241
Using VSAM status codes (VSAM files only) on page 246
RELATED REFERENCES
z/OS DFSMS Macro Instructions for Data Sets (VSAM macro return and
reason codes)
Chapter 10. Processing VSAM files 201
Protecting VSAM files with a password
Although the preferred security mechanism on a z/OS system is RACF,
Enterprise COBOL also supports using explicit passwords on VSAM files to
prevent unauthorized access and update.
To use explicit passwords, code the PASSWORD clause in the FILE-CONTROL
paragraph. Use this clause only if the catalog entry for the files includes a read or
an update password:
v If the catalog entry includes a read password, you cannot open and access the
file in a COBOL program unless you use the PASSWORD clause in the
FILE-CONTROL paragraph and describe it in the DATA DIVISION. The data-name
referred to must contain a valid password when the file is opened.
v If the catalog entry includes an update password, you can open and access it,
but not update it, unless you code the PASSWORD clause in the FILE-CONTROL
paragraph and describe it in the DATA DIVISION.
v If the catalog entry includes both a read password and an update password,
specify the update password to both read and update the file in your program.
If your program only retrieves records and does not update them, you need only
the read password. If your program loads files or updates them, you need to
specify the update password that was cataloged.
For indexed files, the PASSWORD data item for the RECORD KEY must contain the valid
password before the file can be successfully opened.
If you password-protect a VSAM indexed file, you must also password-protect
each alternate index in order to be fully password protected. Where you place the
PASSWORD clause is important because each alternate index has its own password.
The PASSWORD clause must directly follow the key clause to which it applies.
Example: password protection for a VSAM indexed file
The following example shows the COBOL code used for a VSAM indexed file that
has password protection.
. . .
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT LIBFILE
ASSIGN TO PAYMAST
ORGANIZATION IS INDEXED
RECORD KEY IS EMPL-NUM
PASSWORD IS BASE-PASS
ALTERNATE RECORD KEY IS EMPL-PHONE
PASSWORD IS PATH1-PASS
. . .
WORKING-STORAGE SECTION.
01 BASE-PASS PIC X(8) VALUE "25BSREAD".
01 PATH1-PASS PIC X(8) VALUE "25ATREAD".
Working with VSAM data sets under z/OS and z/OS UNIX
Be aware of special coding considerations for VSAM files under z/OS and z/OS
UNIX for access method services (IDCAMS) commands, environment variables,
and JCL.
A VSAM file is available if all of the following conditions are true:
202 Enterprise COBOL for z/OS, V5.2 Programming Guide
v You define it using access method services.
v You define it for your program by providing a DD statement, an environment
variable, or an ALLOCATE command.
v It has previously contained a record.
A VSAM file is unavailable if it has never contained a record, even if you have
defined the file.
You always get a return code of zero on completion of the OPEN statement for a
VSAM sequential file.
Use the access method services REPRO command to empty a file. Deleting records in
this manner resets the high-use relative byte address (RBA) of the file to zero. The
file is effectively empty and appears to COBOL as if it never contained a record.
RELATED TASKS
Defining files to the operating system on page 8
Defining VSAM files
Creating alternate indexes on page 204
Allocating VSAM files on page 206
Sharing VSAM files through RLS on page 207
Defining VSAM files
You can process VSAM entry-sequenced, key-sequenced, and relative-record data
sets in Enterprise COBOL only after you define them through access method
services (IDCAMS).
A VSAM cluster is a logical definition for a VSAM data set and has one or two
components:
v The data component of a VSAM cluster contains the data records.
v The index component of a VSAM key-sequenced cluster consists of the index
records.
Use the DEFINE CLUSTER access-method services command to define VSAM data
sets (clusters). This process includes creating an entry in an integrated catalog
without any data transfer. Define the following information about the cluster:
v Name of the entry
v Name of the catalog to contain this definition and its password (can use default
name)
v Organization (sequential, indexed, or relative)
v Device and volumes that the data set will occupy
v Space required for the data set
v Record size and control interval sizes (CISIZE)
v Passwords (if any) required for future access
Depending on what kind of data set is in the cluster, also define the following
information for each cluster:
v For VSAM indexed data sets (KSDS), specify length and position of the prime
key in the records.
v For VSAM fixed-length relative-record data sets (RRDS), specify the record size
as greater than or equal to the maximum size COBOL record:
Chapter 10. Processing VSAM files 203
DEFINE CLUSTER NUMBERED
RECORDSIZE(n,n)
If you define a data set in this way, all records are padded to the fixed slot size
n. If you use the RECORD IS VARYING ON data-name form of the RECORD clause, a
WRITE or REWRITE uses the length specified in DEPENDING ON data-name as the
length of the record to be transferred by VSAM. This data is then padded to the
fixed slot size. READ statements always return the fixed slot size in the DEPENDING
ON data-name.
v For VSAM variable-length relative-record data sets (RRDS), specify the average
size COBOL record expected and the maximum size COBOL record expected:
DEFINE CLUSTER NUMBERED
RECORDSIZE(avg,m)
The average size COBOL record expected must be less than the maximum size
COBOL record expected.
RELATED TASKS
Creating alternate indexes
Allocating VSAM files on page 206
Specifying relative organization for VSAM files on page 190
RELATED REFERENCES
z/OS DFSMS: Access Method Services for Catalogs
Creating alternate indexes
An alternate index provides access to the records in a data set that uses more than
one key. It accesses records in the same way as the prime index key of an indexed
data set (KSDS).
When planning to use an alternate index, you must know:
v The type of data set (base cluster) with which the index will be associated
v Whether the keys will be unique or not unique
v Whether the index is to be password protected
v Some of the performance aspects of using alternate indexes
Because an alternate index is, in practice, a VSAM data set that contains pointers to
the keys of a VSAM data set, you must define the alternate index and the alternate
index path (the entity that establishes the relationship between the alternate index
and the prime index). After you define an alternate index, make a catalog entry to
establish the relationship (or path) between the alternate index and its base cluster.
This path allows you to access the records of the base cluster through the alternate
keys.
To use an alternate index, do these steps:
1. Define the alternate index by using the DEFINE ALTERNATEINDEX command. In it,
specify these items:
v Name of the alternate index
v Name of its related VSAM indexed data set
v Location in the record of any alternate indexes and whether they are unique
v Whether alternate indexes are to be updated when the data set is changed
v Name of the catalog to contain this definition and its password (can use
default name)
204 Enterprise COBOL for z/OS, V5.2 Programming Guide
In your COBOL program, the alternate index is identified solely by the
ALTERNATE RECORD KEY clause in the FILE-CONTROL paragraph. The ALTERNATE
RECORD KEY definitions must match the definitions in the catalog entry. Any
password entries that you cataloged should be coded directly after the
ALTERNATE RECORD KEY phrase.
2. Relate the alternate index to the base cluster (the data set to which the alternate
index gives you access) by using the DEFINE PATH command. In it, specify these
items:
v Name of the path
v Alternate index to which the path is related
v Name of the catalog that contains the alternate index
The base cluster and alternate index are described by entries in the same
catalog.
3. Load the VSAM indexed data set.
4. Build the alternate index by using (typically) the BLDINDEX command. Identify
the input file as the indexed data set (base cluster) and the output file as the
alternate index or its path. BLDINDEX reads all the records in the VSAM indexed
data set (or base cluster) and extracts the data needed to build the alternate
index.
Alternatively, you can use the runtime option AIXBLD to build the alternate
index at run time. However, this option might adversely affect performance.
Example: entries for alternate indexes
RELATED TASKS
Using an alternate index on page 189
RELATED REFERENCES
Language Environment Programming Reference (AIXBLD (COBOL only))
Example: entries for alternate indexes
The following example maps the relationships between the COBOL FILE-CONTROL
entry and the DD statements or environment variables for a VSAM indexed file that
has two alternate indexes.
Using JCL:
//MASTERA DD DSNAME=clustername,DISP=OLD (1)
//MASTERA1 DD DSNAME=path1,DISP=OLD (2)
//MASTERA2 DD DSNAME=path2,DISP=OLD (3)
Using environment variables:
export MASTERA=DSN(clustername),OLD (1)
export MASTERA=DSN(path1),OLD (2)
export MASTERA=DSN(path2),OLD (3)
. . .
FILE-CONTROL.
SELECT MASTER-FILE ASSIGN TO MASTERA (4)
RECORD KEY IS EM-NAME
PASSWORD IS PW-BASE (5)
ALTERNATE RECORD KEY IS EM-PHONE (6)
PASSWORD IS PW-PATH1
ALTERNATE RECORD KEY IS EM-CITY (7)
PASSWORD IS PW-PATH2.
(1) The base cluster name is clustername.
(2) The name of the first alternate index path is path1.
Chapter 10. Processing VSAM files 205
(3) The name of the second alternate index path is path2.
(4) The ddname or environment variable name for the base cluster is specified
with the ASSIGN clause.
(5) Passwords immediately follow their indexes.
(6) The key EM-PHONE relates to the first alternate index.
(7) The key EM-CITY relates to the second alternate index.
RELATED TASKS
Creating alternate indexes on page 204
Allocating VSAM files
You must predefine and catalog all VSAM data sets through the access method
services DEFINE command. Most of the information about a VSAM data set is in the
catalog, so you need to specify only minimal DD or environment variable
information.
Allocation of VSAM files (indexed, relative, and sequential) follows the general
rules for the allocation of COBOL files.
When you use an environment variable to allocate a VSAM file, the variable name
must be in uppercase. Usually the input and data buffers are the only variables
that you are concerned about. You must specify these options in the order shown,
but no others:
1. DSN(dsname), where dsname is the name of the base cluster
2. OLD or SHR
The basic DD statement that you need for VSAM files and the corresponding export
command are these:
//ddname DD DSN=dsname,DISP=SHR,AMP=AMORG
export evname="DSN(dsname),SHR"
In either case, dsname must be the same as the name used in the access method
services DEFINE CLUSTER or DEFINE PATH command. DISP must be OLD or SHR
because the data set is already cataloged. If you specify MOD when using JCL, the
data set is treated as OLD.
AMP is a VSAM JCL parameter that supplements the information that the program
supplies about the data set. AMP takes effect when your program opens the VSAM
file. Any information that you set through the AMP parameter takes precedence over
the information that is in the catalog or that the program supplies. The AMP
parameter is required only under the following circumstances:
v You use a dummy VSAM data set. For example,
//ddname DD DUMMY,AMP=AMORG
v You request additional index or data buffers. For example,
//ddname DD DSN=VSAM.dsname,DISP=SHR,
// AMP=(BUFNI=4,BUFND=8)
You cannot specify AMP if you allocate a VSAM data set with an environment
variable.
For a VSAM base cluster, specify the same system-name (ddname or environment
variable name) that you specify in the ASSIGN clause after the SELECT clause.
206 Enterprise COBOL for z/OS, V5.2 Programming Guide
When you use alternate indexes in your COBOL program, you must specify not
only a system-name (using a DD statement or environment variable) for the base
cluster, but also a system-name for each alternate index path. No language
mechanism exists to explicitly declare system-names for alternate index paths
within the program. Therefore, you must adhere to the following guidelines for
forming the system-name (ddname or environment variable name) for each
alternate index path:
v Concatenate the base cluster name with an integer.
v Begin with 1 for the path associated with the first alternate record defined for
the file in your program (ALTERNATE RECORD KEY clause of the FILE-CONTROL
paragraph).
v Increment by 1 for the path associated with each successive alternate record
definition for that file.
For example, if the system-name of a base cluster is ABCD, the system-name for the
first alternate index path defined for the file in your program is ABCD1, the
system-name for the second alternate index path is ABCD2, and so on.
If the length of the base cluster system-name together with the sequence number
exceeds eight characters, the base cluster portion of the system-name is truncated
on the right to reduce the concatenated result to eight characters. For example, if
the system-name of a base cluster is ABCDEFGH, the system name of the first
alternate index path is ABCDEFG1, the tenth is ABCDEF10, and so on.
RELATED TASKS
Allocating files on page 157
RELATED REFERENCES
MVS Program Management: User's Guide and Reference
Sharing VSAM files through RLS
By using the VSAM JCL parameter RLS, you can specify record-level sharing with
VSAM. Specifying RLS is the only way to request the RLS mode when running
COBOL programs.
Use RLS=CR when consistent read protocols are required, and RLS=NRI when no read
integrity protocols are required. You cannot specify RLS if you allocate your VSAM
data set with an environment variable
RELATED TASKS
Preventing update problems with VSAM files in RLS mode
Handling errors in VSAM files in RLS mode on page 208
RELATED REFERENCES
Restrictions when using RLS on page 208
Preventing update problems with VSAM files in RLS mode
When you open a VSAM data set in RLS mode for I-O (updates), the first READ
causes an exclusive lock of the record regardless of the value of RLS (RLS=CR or
RLS=NRI) that you specify.
If the COBOL file is defined as ACCESS RANDOM, VSAM releases the exclusive lock
on the record after a WRITE or REWRITE statement is executed or a READ statement is
executed for another record. When a WRITE or REWRITE is done, VSAM writes the
record immediately.
Chapter 10. Processing VSAM files 207
However, if the COBOL file is defined as ACCESS DYNAMIC, VSAM does not release
the exclusive lock on the record after a WRITE or REWRITE statement, nor after a READ
statement, unless the I-O statement causes VSAM to move to another control
interval (CI). As a result, if a WRITE or REWRITE was done, VSAM does not write the
record until processing is moved to another CI and the lock is released. When you
use ACCESS DYNAMIC, one way to cause the record to be written immediately, to
release the exclusive lock immediately, or both, is to define the VSAM data set to
allow only one record per CI.
Specifying RLS=CR locks a record and prevents an update to it until another READ is
requested for another record. While a lock on the record being read is in effect,
other users can request a READ for the same record, but they cannot update the
record until the read lock is released. When you specify RLS=NRI, no lock will be in
effect when a READ for input is executed. Another user might update the record.
The locking rules for RLS=CR can cause the application to wait for availability of a
record lock. This wait might slow down the READ for input. You might need to
modify your application logic to use RLS=CR. Do not use the RLS parameter for
batch jobs that update nonrecoverable spheres until you are sure that the
application functions correctly in a multiple-updater environment.
When you open a VSAM data set in RLS mode for INPUT or I-O processing, it is
good to issue an OPEN or START immediately before a READ. If there is a delay
between the OPEN or START and the READ, another user might add records before the
record on which the application is positioned after the OPEN or START. The COBOL
run time points explicitly to the beginning of the VSAM data set at the time when
OPEN was requested, but another user might add records that would alter the true
beginning of the VSAM data set if the READ is delayed.
Restrictions when using RLS
When you use RLS mode, several restrictions apply to VSAM cluster attributes and
to runtime options.
Be aware of these restrictions:
v The VSAM cluster attributes KEYRANGE and IMBED are not supported when you
open a VSAM file.
v The VSAM cluster attribute REPLICATE is not recommended because the benefits
are negated by the system-wide buffer pool and potentially large CF cache
structure in the storage hierarchy.
v The AIXBLD runtime option is not supported when you open a VSAM file
because VSAM does not allow an empty path to be opened. If you need the
AIXBLD runtime option to build the alternate index data set, open the VSAM data
set in non-RLS mode.
v The SIMVRD runtime option is not supported for VSAM files.
v Temporary data sets are not allowed.
Handling errors in VSAM files in RLS mode
If your application accesses a VSAM data set in RLS mode, be sure to check the file
status and VSAM feedback codes after each request.
If your application encounters "SMSVSAM server not available" while processing
input or output, explicitly close the VSAM file before you try to open it again.
VSAM generates return code 16 for such failures, and there is no feedback code.
You can have COBOL programs check the first 2 bytes of the second file status
208 Enterprise COBOL for z/OS, V5.2 Programming Guide
area for VSAM return code 16. The COBOL run time generates message IGZ0205W
and automatically closes the file if the error occurs during OPEN processing.
All other RLS mode errors return a VSAM return code of 4, 8, or 12.
RELATED TASKS
Using VSAM status codes (VSAM files only) on page 246
Allocation of record areas for VSAM files
For reentrant COBOL programs, the record areas for VSAM files are allocated
above the 16 MB line by default.
If you specify the DATA(24) compiler option, the VSAM record areas and other
dynamic storage areas are allocated in storage below 16 MB.
Programs that pass data in VSAM file records as CALL...USING parameters to AMODE
24 subprograms are impacted. You can recompile such programs with the DATA(24)
compiler option, or use the Language Environment HEAP runtime option, to ensure
that the records are addressable by the AMODE 24 programs.
Improving VSAM performance
Your system programmer is most likely responsible for tuning the performance of
COBOL and VSAM. As an application programmer, you can control the aspects of
VSAM that are listed in the following table.
Table 31. Methods for improving VSAM performance
Aspect of VSAM What you can do Rationale and comments
Invoking access Build your alternate indexes in
methods service advance, using IDCAMS.
Buffering For sequential access, request The default is one index (BUFNI) and
more data buffers; for random two data buffers (BUFND).
access, request more index
buffers. Specify both BUFND
and BUFNI if ACCESS IS
DYNAMIC.
Avoid coding additional
buffers unless your application
will run interactively; then
code buffers only when
response-time problems arise
that might be caused by
delays in input and output.
Chapter 10. Processing VSAM files 209
Table 31. Methods for improving VSAM performance (continued)
Aspect of VSAM What you can do Rationale and comments
Loading records, Use the access methods service The REPRO command can update an
using access REPRO command when: indexed data set as fast or faster than
methods services v The target indexed data set any COBOL program under these
already contains records. conditions.
v The input sequential data
set contains records to be
updated or inserted into the
indexed data set.
If you use a COBOL program
to load the file, use OPEN
OUTPUT and ACCESS
SEQUENTIAL.
File access modes For best performance, access Dynamic access is less efficient than
records sequentially. sequential access, but more efficient
than random access. Random access
results in increased EXCPs because
VSAM must access the index for each
request.
Key design Design the key in the records This method compresses the key best.
so that the high-order portion
is relatively constant and the
low-order portion changes
often.
Multiple Avoid using multiple alternate Updates must be applied through the
alternate indexes indexes. primary paths and are reflected
through multiple alternate paths,
perhaps slowing performance.
Relative file Use VSAM fixed-length Although not as space efficient, VSAM
organization relative data sets rather than fixed-length relative data sets are more
VSAM variable-length relative run time efficient than VSAM
data sets. variable-length relative data sets.
Control interval Provide your system VSAM calculates CISZ to best fit the
sizes (CISZ) programmer with information direct-access storage device (DASD)
about the data access and usage algorithm, which might not,
future growth of your VSAM however, be efficient for your
data sets. From this application.
information, your system
programmer can determine An average CISZ of 4K is suitable for
the best control interval size most applications. A smaller CISZ
(CISZ) and FREESPACE size means faster retrieval for random
(FSPC). processing at the expense of inserts
(that is, more CISZ splits and therefore
Choose proper values for CISZ more space in the data set). A larger
and FSPC to minimize control CISZ results in the transfer of more data
area (CA) splits. You can across the channel for each READ. This is
diagnose the current number more efficient for sequential processing,
of CA splits by issuing the similar to a large OS BLKSIZE.
LISTCAT ALL command on the
cluster, and then compress Many control area (CA) splits are
(using EXPORT, IMPORT, or unfavorable for VSAM performance.
REPRO) the cluster to omit all The FREESPACE value can affect CA
CA splits periodically. splits, depending on how the file is
used.
210 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Specifying access modes for VSAM files on page 191
z/OS DFSMS: Using Data Sets (Building a resource pool, Selecting the optimal
percentage of free space)
RELATED REFERENCES
z/OS DFSMS: Access Method Services for Catalogs
| Extended addressability support
| You can access VSAM data sets that are defined with the extended addressability
| attribute, use those VSAM data sets in COBOL programs without COBOL source
| changes, and maintain compatibility with previous versions of COBOL.
| With extended addressability support, you can define larger VSAM data sets
| outside of COBOL. The 4 GB VSAM architectural limit for data set size imposed
| by using the 4-byte field for the relative byte address (RBA) is eliminated.
| To use the extended addressability, the VSAM data set must be Storage
| Management Subsystem (SMS)-managed and be defined as extended format. The
| size limit for a VSAM data set is determined in either of the following ways:
| v Control Interval (CI) size multiplied by 4 GB
| v Volume size multiplied by 59
| For example, a 4 KB CI size yields a maximum data set size of 16 TB, and a 32 KB
| CI size yields a maximum data set size of 128 TB. A 4 KB CI size is preferred by
| many applications for performance reasons. For extended-format data sets that
| grow beyond 4 GB, the processing time does not increase.
| Extended addressability is also supported for programs compiled with earlier
| versions: VS COBOL II programs compiled with RES and any later compilers.
| Extended addressability and extended format are not the same concept. Extended
| format is a prerequisite for extended addressability. Extended format is a technique
| that affects the way of storing count key data (CKD) in a 3390/3380 logical track.
| Extended format implements data striping and increases the performance and the
| reliability of an I/O operation. If a data set is allocated as an extended-format data
| set, 32 bytes are added to each physical block.
| Restriction: Extended addressability was introduced for KSDS data sets in
| DFSMS/MVS V1.3. Since DFSMS/MVS V1.4, extended addressability is supported
| in record level sharing (RLS). With DFSMS/MVS V1.5, support for extended
| addressability is extended to all other VSAM record organizations.
| RELATED TASKS
| z/OS DFSMS: Using Data Sets
Chapter 10. Processing VSAM files 211
212 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 11. Processing line-sequential files
Line-sequential files reside in the z/OS UNIX file system and can contain both
printable characters and control characters as data. Each record ends with an
EBCDIC newline character (X15), which is not included in the record length.
Because line-sequential files are sequential, records are placed one after another
according to entry order. Your program can process these files only sequentially,
retrieving (with the READ statement) records in the same order as they are in the
file. A new record is placed after the preceding record.
To process line-sequential files in a program, code COBOL language statements
that:
v Identify and describe the files in the ENVIRONMENT DIVISION and the DATA
DIVISION
v Process the records in the files in the PROCEDURE DIVISION
After you have created a record, you cannot change its length or its position in the
file, and you cannot delete it.
RELATED TASKS
Defining line-sequential files and records in COBOL
Allocating line-sequential files on page 214
Coding input-output statements for line-sequential files on page 215
Handling errors in line-sequential files on page 218
UNIX System Services User's Guide
Defining line-sequential files and records in COBOL
Use the FILE-CONTROL paragraph in the ENVIRONMENT DIVISION to define the files in
a COBOL program as line-sequential files, and to associate the files with the
corresponding external file-names (ddnames or environment variable names).
An external file-name is the name by which a file is known to the operating
system. In the following example, COMMUTER-FILE is the name that your program
uses for the file; COMMUTR is the external name:
FILE-CONTROL.
SELECT COMMUTER-FILE
ASSIGN TO COMMUTR
ORGANIZATION IS LINE SEQUENTIAL
ACCESS MODE IS SEQUENTIAL
FILE STATUS IS ECODE.
The ASSIGN assignment-name clause must not include an organization field (S- or
AS-) before the external name. The ACCESS phrase and the FILE STATUS clause are
optional.
RELATED TASKS
Describing the structure of a line-sequential file on page 214
Allocating line-sequential files on page 214
Coding input-output statements for line-sequential files on page 215
Copyright IBM Corp. 1991, 2015 213
RELATED REFERENCES
Control characters in line-sequential files
Describing the structure of a line-sequential file
In the FILE SECTION, code a file description (FD) entry for the file. In the associated
record description entry or entries, define the record-name and record length.
Code the logical size in bytes of the records by using the RECORD clause.
Line-sequential files are stream files. Because of their character-oriented nature, the
physical records are of variable length.
The following examples show how the FD entry might look for a line-sequential
file:
With fixed-length records:
FILE SECTION.
FD COMMUTER-FILE
RECORD CONTAINS 80 CHARACTERS.
01 COMMUTER-RECORD.
05 COMMUTER-NUMBER PIC X(16).
05 COMMUTER-DESCRIPTION PIC X(64).
With variable-length records:
FILE SECTION.
FD COMMUTER-FILE
RECORD VARYING FROM 16 TO 80 CHARACTERS.
01 COMMUTER-RECORD.
05 COMMUTER-NUMBER PIC X(16).
05 COMMUTER-DESCRIPTION PIC X(64).
If you code the same fixed size and no OCCURS DEPENDING ON clause for any level-01
record description entries associated with the file, that fixed size is the logical
record length. However, because blanks at the end of a record are not written to
the file, the physical records might be of varying lengths.
RELATED TASKS
Allocating line-sequential files
Coding input-output statements for line-sequential files on page 215
RELATED REFERENCES
Data division--file description entries (Enterprise COBOL Language Reference)
Control characters in line-sequential files
A line-sequential file can contain control characters. Be aware though that if a
line-sequential file contains a newline character (X15), the newline character will
function as a record delimiter.
Control characters other than newline are treated as data and are part of the
record.
Allocating line-sequential files
You can allocate a line-sequential file in the z/OS UNIX file system by using either
a DD statement or an environment variable. Allocation of line-sequential files
follows the general rules for allocating COBOL files.
214 Enterprise COBOL for z/OS, V5.2 Programming Guide
To allocate a line-sequential file, code a DD allocation or an environment variable
that has a name that matches the external name in the ASSIGN clause:
v A DD allocation:
A DD statement that specifies PATH=absolute-path-name
A TSO allocation that specifies PATH(absolute-path-name)
You can optionally also specify these options:
PATHOPTS
PATHMODE
PATHDISP
v An environment variable that has a value of PATH(absolute-path-name). No other
values can be specified.
For example, to have your program use z/OS UNIX file /u/myfiles/
commuterfile for a COBOL file that has an assignment-name of COMMUTR, you can
use the following command:
export COMMUTR="PATH(/u/myfiles/commuterfile)"
RELATED TASKS
Allocating files on page 157
Defining line-sequential files and records in COBOL on page 213
RELATED REFERENCES
MVS Program Management: User's Guide and Reference
Coding input-output statements for line-sequential files
Code the input and output statements shown below to process a line-sequential
file.
OPEN To initiate the processing of a file.
You can open a line-sequential file as INPUT, OUTPUT, or EXTEND. You cannot
open a line-sequential file as I-O.
READ To read a record from a file.
With sequential processing, a program reads one record after another in
the same order in which the records were entered when the file was
created.
WRITE To create a record in a file.
A program writes new records to the end of the file.
CLOSE To release the connection between a file and the program.
RELATED TASKS
Defining line-sequential files and records in COBOL on page 213
Describing the structure of a line-sequential file on page 214
Opening line-sequential files on page 216
Reading records from line-sequential files on page 216
Adding records to line-sequential files on page 217
Closing line-sequential files on page 217
Handling errors in line-sequential files on page 218
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
READ statement (Enterprise COBOL Language Reference)
Chapter 11. Processing line-sequential files 215
WRITE statement (Enterprise COBOL Language Reference)
CLOSE statement (Enterprise COBOL Language Reference)
Opening line-sequential files
Before your program can use any READ or WRITE statements to process records in a
file, it must first open the file with an OPEN statement. An OPEN statement works if
the file is available or has been dynamically allocated.
Code CLOSE WITH LOCK so that the file cannot be opened again while the program
is running.
RELATED TASKS
Reading records from line-sequential files
Adding records to line-sequential files on page 217
Closing line-sequential files on page 217
Allocating line-sequential files on page 214
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
CLOSE statement (Enterprise COBOL Language Reference)
Reading records from line-sequential files
To read from a line-sequential file, open the file and use the READ statement. Your
program reads one record after another in the same order in which the records
were entered when the file was created.
Characters in the file record are read one at a time into the record area until one of
the following conditions occurs:
v The record delimiter (the EBCDIC newline character) is encountered.
The delimiter is discarded and the remainder of the record area is filled with
spaces. (Record area is longer than the file record.)
v The entire record area is filled with characters.
If the next unread character is the record delimiter, it is discarded. The next READ
reads from the first character of the next record. (Record area is the same length
as the file record.)
Otherwise the next unread character is the first character to be read by the next
READ. (Record area is shorter than the file record.)
v End-of-file is encountered.
The remainder of the record area is filled with spaces. (Record area is longer
than the file record.)
RELATED TASKS
Opening line-sequential files
Adding records to line-sequential files on page 217
Closing line-sequential files on page 217
Allocating line-sequential files on page 214
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise COBOL Language Reference)
216 Enterprise COBOL for z/OS, V5.2 Programming Guide
Adding records to line-sequential files
To add to a line-sequential file, open the file as EXTEND and use the WRITE statement
to add records immediately after the last record in the file.
Blanks at the end of the record area are removed, and the record delimiter is
added. The characters in the record area from the first character up to and
including the added record delimiter are written to the file as one record.
Records written to line-sequential files must contain only USAGE DISPLAY and
DISPLAY-1 items. Zoned decimal data items must be unsigned or declared with the
SEPARATE phrase of the SIGN clause if signed.
RELATED TASKS
Opening line-sequential files on page 216
Reading records from line-sequential files on page 216
Closing line-sequential files
Allocating line-sequential files on page 214
RELATED REFERENCES
OPEN statement (Enterprise COBOL Language Reference)
WRITE statement (Enterprise COBOL Language Reference)
Closing line-sequential files
Use the CLOSE statement to disconnect your program from a line-sequential file. If
you try to close a file that is already closed, you will get a logic error.
If you do not close a line-sequential file, the file is automatically closed for you
under the following conditions:
v When the run unit ends normally.
v When the run unit ends abnormally, if the TRAP(ON) runtime option is set.
v When Language Environment condition handling is completed and the
application resumes in a routine other than where the condition occurred, open
files defined in any COBOL programs in the run unit that might be called again
and reentered are closed.
You can change the location where the program resumes (after a condition is
handled) by moving the resume cursor with the Language Environment
CEEMRCR callable service or using HLL language constructs such as a C
longjmp call.
File status codes are set when these implicit CLOSE operations are performed, but
EXCEPTION/ERROR declaratives are not invoked.
RELATED TASKS
Opening line-sequential files on page 216
Reading records from line-sequential files on page 216
Adding records to line-sequential files
Allocating line-sequential files on page 214
RELATED REFERENCES
CLOSE statement (Enterprise COBOL Language Reference)
Chapter 11. Processing line-sequential files 217
Handling errors in line-sequential files
When an input or output statement fails, COBOL does not take corrective action
for you. You choose whether your program should continue running after an input
or output statement fails.
COBOL provides these language elements for intercepting and handling certain
line-sequential input and output errors:
v End-of-file phrase (AT END)
v EXCEPTION/ERROR declarative
v FILE STATUS clause
If you do not use one of these techniques, an error in processing input or output
raises a Language Environment condition.
If you use the FILE STATUS clause, be sure to check the key and take appropriate
action based on its value. If you do not check the key, your program might
continue, but the results will probably not be what you expected.
RELATED TASKS
Coding input-output statements for line-sequential files on page 215
Handling errors in input and output operations on page 241
218 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 12. Sorting and merging files
You can arrange records in a particular sequence by using a SORT or MERGE
statement. You can mix SORT and MERGE statements in the same COBOL program.
| Note: The SORT statement, sort processes, and sort restrictions that are described in
| this topic relate to the format 1 SORT statement only. For more information about
| sorting a table by using the format 2 SORT statement, see Sorting a table on page
| 88.
SORT statement
Accepts input (from a file or an internal procedure) that is not in sequence,
and produces output (to a file or an internal procedure) in a requested
sequence. You can add, delete, or change records before or after they are
sorted.
MERGE statement
Compares records from two or more sequenced files and combines them in
order. You can add, delete, or change records after they are merged.
A program can contain any number of sort and merge operations. They can be the
same operation performed many times or different operations. However, one
operation must finish before another begins.
With Enterprise COBOL, your IBM licensed program for sorting and merging must
be DFSORT or an equivalent. Where DFSORT is mentioned, you can use any
equivalent sort or merge product.
COBOL programs that contain SORT or MERGE statements can reside above or below
the 16 MB line.
The steps you take to sort or merge are generally as follows:
1. Describe the sort or merge file to be used for sorting or merging.
2. Describe the input to be sorted or merged. If you want to process the records
before you sort them, code an input procedure.
3. Describe the output from sorting or merging. If you want to process the records
after you sort or merge them, code an output procedure.
4. Request the sort or merge.
5. Determine whether the sort or merge operation was successful.
Restrictions:
v You cannot run a COBOL program that contains SORT or MERGE statements under
z/OS UNIX. This restriction includes BPXBATCH.
v You cannot use SORT or MERGE statements in programs compiled with the THREAD
option. This includes programs that use object-oriented syntax and
multithreaded applications, both of which require the THREAD option.
RELATED CONCEPTS
Sort and merge process on page 220
RELATED TASKS
| Sorting a table on page 88
Copyright IBM Corp. 1991, 2015 219
| Describing the sort or merge file
Describing the input to sorting or merging on page 221
Describing the output from sorting or merging on page 223
Requesting the sort or merge on page 226
Determining whether the sort or merge was successful on page 230
Stopping a sort or merge operation prematurely on page 231
Improving sort performance with FASTSRT on page 231
Controlling sort behavior on page 234
DFSORT Application Programming Guide
RELATED REFERENCES
CICS SORT application restrictions on page 237
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise COBOL Language Reference)
Sort and merge process
During the sorting of a file, all of the records in the file are ordered according to
the contents of one or more fields (keys) in each record. You can sort the records in
either ascending or descending order of each key.
If there are multiple keys, the records are first sorted according to the content of
the first (or primary) key, then according to the content of the second key, and so
on.
| To sort a file, use the format 1 SORT statement.
During the merging of two or more files (which must already be sorted), the
records are combined and ordered according to the contents of one or more keys in
each record. You can order the records in either ascending or descending order of
each key. As with sorting, the records are first ordered according to the content of
the primary key, then according to the content of the second key, and so on.
Use MERGE . . . USING to name the files that you want to combine into one
sequenced file. The merge operation compares keys in the records of the input
files, and passes the sequenced records one by one to the RETURN statement of an
output procedure or to the file that you name in the GIVING phrase.
RELATED TASKS
Setting sort or merge criteria on page 227
RELATED REFERENCES
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise COBOL Language Reference)
Describing the sort or merge file
Describe the sort file to be used for sorting or merging. You need SELECT clauses
and SD entries even if you are sorting or merging data items only from
WORKING-STORAGE or LOCAL-STORAGE.
Code as follows:
1. Write one or more SELECT clauses in the FILE-CONTROL paragraph of the
ENVIRONMENT DIVISION to name a sort file. For example:
220 Enterprise COBOL for z/OS, V5.2 Programming Guide
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Sort-Work-1 ASSIGN TO SortFile.
Sort-Work-1 is the name of the file in your program. Use this name to refer to
the file.
2. Describe the sort file in an SD entry in the FILE SECTION of the DATA DIVISION.
Every SD entry must contain a record description. For example:
DATA DIVISION.
FILE SECTION.
SD Sort-Work-1
RECORD CONTAINS 100 CHARACTERS.
01 SORT-WORK-1-AREA.
05 SORT-KEY-1 PIC X(10).
05 SORT-KEY-2 PIC X(10).
05 FILLER PIC X(80).
The file described in an SD entry is the working file used for a sort or merge
operation. You cannot perform any input or output operations on this file and you
do not need to provide a ddname definition for it.
RELATED REFERENCES
FILE SECTION entries on page 12
Describing the input to sorting or merging
Describe the input file or files for sorting or merging by following the procedure
below.
1. Write one or more SELECT clauses in the FILE-CONTROL paragraph of the
ENVIRONMENT DIVISION to name the input files. For example:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Input-File ASSIGN TO InFile.
Input-File is the name of the file in your program. Use this name to refer to the
file.
2. Describe the input file (or files when merging) in an FD entry in the FILE
SECTION of the DATA DIVISION. For example:
DATA DIVISION.
FILE SECTION.
FD Input-File
LABEL RECORDS ARE STANDARD
BLOCK CONTAINS 0 CHARACTERS
RECORDING MODE IS F
RECORD CONTAINS 100 CHARACTERS.
01 Input-Record PIC X(100).
RELATED TASKS
Coding the input procedure on page 222
Requesting the sort or merge on page 226
RELATED REFERENCES
FILE SECTION entries on page 12
Example: describing sort and input files for SORT
The following example shows the ENVIRONMENT DIVISION and DATA DIVISION entries
needed to describe sort work files and an input file.
Chapter 12. Sorting and merging files 221
ID Division.
Program-ID. SmplSort.
Environment Division.
Input-Output Section.
File-Control.
*
* Assign name for a working file is treated as documentation.
*
Select Sort-Work-1 Assign To SortFile.
Select Sort-Work-2 Assign To SortFile.
Select Input-File Assign To InFile.
. . .
Data Division.
File Section.
SD Sort-Work-1
Record Contains 100 Characters.
01 Sort-Work-1-Area.
05 Sort-Key-1 Pic X(10).
05 Sort-Key-2 Pic X(10).
05 Filler Pic X(80).
SD Sort-Work-2
Record Contains 30 Characters.
01 Sort-Work-2-Area.
05 Sort-Key Pic X(5).
05 Filler Pic X(25).
FD Input-File
Label Records Are Standard
Block Contains 0 Characters
Recording Mode is F
Record Contains 100 Characters.
01 Input-Record Pic X(100).
. . .
Working-Storage Section.
01 EOS-Sw Pic X.
01 Filler.
05 Table-Entry Occurs 100 Times
Indexed By X1 Pic X(30).
. . .
RELATED TASKS
Requesting the sort or merge on page 226
Coding the input procedure
To process the records in an input file before they are released to the sort program,
| use the INPUT PROCEDURE phrase of the format 1 SORT statement.
You can use an input procedure to:
v Release data items to the sort file from WORKING-STORAGE or LOCAL-STORAGE.
v Release records that have already been read elsewhere in the program.
v Read records from an input file, select or process them, and release them to the
sort file.
Each input procedure must be contained in either paragraphs or sections. For
example, to release records from a table in WORKING-STORAGE or LOCAL-STORAGE to
the sort file SORT-WORK-2, you could code as follows:
SORT SORT-WORK-2
ON ASCENDING KEY SORT-KEY
INPUT PROCEDURE 600-SORT3-INPUT-PROC
. . .
600-SORT3-INPUT-PROC SECTION.
222 Enterprise COBOL for z/OS, V5.2 Programming Guide
PERFORM WITH TEST AFTER
VARYING X1 FROM 1 BY 1 UNTIL X1 = 100
RELEASE SORT-WORK-2-AREA FROM TABLE-ENTRY (X1)
END-PERFORM.
To transfer records to the sort program, all input procedures must contain at least
one RELEASE or RELEASE FROM statement. To release A from X, for example, you can
code:
MOVE X TO A.
RELEASE A.
Alternatively, you can code:
RELEASE A FROM X.
The following table compares the RELEASE and RELEASE FROM statements.
RELEASE RELEASE FROM
MOVE EXT-RECORD PERFORM RELEASE-SORT-RECORD
TO SORT-EXT-RECORD . . .
PERFORM RELEASE-SORT-RECORD RELEASE-SORT-RECORD.
. . . RELEASE SORT-RECORD
RELEASE-SORT-RECORD. FROM SORT-EXT-RECORD
RELEASE SORT-RECORD
RELATED REFERENCES
Restrictions on input and output procedures on page 225
RELEASE statement (Enterprise COBOL Language Reference)
Describing the output from sorting or merging
If the output from sorting or merging is a file, describe the file by following the
procedure below.
1. Write a SELECT clause in the FILE-CONTROL paragraph of the ENVIRONMENT
DIVISION to name the output file. For example:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT Output-File ASSIGN TO OutFile.
Output-File is the name of the file in your program. Use this name to refer to
the file.
2. Describe the output file (or files when merging) in an FD entry in the FILE
SECTION of the DATA DIVISION. For example:
DATA DIVISION.
FILE SECTION.
FD Output-File
LABEL RECORDS ARE STANDARD
BLOCK CONTAINS 0 CHARACTERS
RECORDING MODE IS F
RECORD CONTAINS 100 CHARACTERS.
01 Output-Record PIC X(100).
RELATED TASKS
Coding the output procedure on page 224
Requesting the sort or merge on page 226
Chapter 12. Sorting and merging files 223
RELATED REFERENCES
FILE SECTION entries on page 12
Coding the output procedure
To select, edit, or otherwise change sorted records before writing them from the
| sort work file into another file, use the OUTPUT PROCEDURE phrase of the format 1
| SORT statement.
Each output procedure must be contained in either a section or a paragraph. An
output procedure must include both of the following elements:
v At least one RETURN statement or one RETURN statement with the INTO phrase
v Any statements necessary to process the records that are made available, one at
a time, by the RETURN statement
The RETURN statement makes each sorted record available to the output procedure.
(The RETURN statement for a sort file is similar to a READ statement for an input file.)
You can use the AT END and END-RETURN phrases with the RETURN statement. The
imperative statements in the AT END phrase are performed after all the records have
been returned from the sort file. The END-RETURN explicit scope terminator delimits
the scope of the RETURN statement.
If you use RETURN INTO instead of RETURN, the records will be returned to
WORKING-STORAGE, LOCAL-STORAGE, or to an output area.
DFSORT coding: If you use DFSORT and a RETURN statement does not encounter
| an AT END condition before a COBOL program finishes running, the format 1 SORT
statement could end abnormally with DFSORT message IEC025A. To avoid this
situation, be sure to code the RETURN statement with the AT END phrase. In addition,
ensure that the RETURN statement is executed until the AT END condition is
encountered. The AT END condition occurs after the last record is returned to the
program from the sort work file and a subsequent RETURN statement is executed.
Example: coding the output procedure when using DFSORT
RELATED REFERENCES
Restrictions on input and output procedures on page 225
RETURN statement (Enterprise COBOL Language Reference)
Example: coding the output procedure when using DFSORT
The following example shows a coding technique that ensures that the RETURN
statement encounters the AT END condition before the program finishes running.
The RETURN statement, coded with the AT END phrase, is executed until the AT END
condition occurs.
IDENTIFICATION DIVISION.
DATA DIVISION.
FILE SECTION.
SD OUR-FILE.
01 OUR-SORT-REC.
03 SORT-KEY PIC X(10).
03 FILLER PIC X(70).
. . .
WORKING-STORAGE SECTION.
01 WS-SORT-REC PIC X(80).
01 END-OF-SORT-FILE-INDICATOR PIC X VALUE N.
88 NO-MORE-SORT-RECORDS VALUE Y.
224 Enterprise COBOL for z/OS, V5.2 Programming Guide
. . .
PROCEDURE DIVISION.
A-CONTROL SECTION.
SORT OUR-FILE ON ASCENDING KEY SORT-KEY
INPUT PROCEDURE IS B-INPUT
OUTPUT PROCEDURE IS C-OUTPUT.
. . .
B-INPUT SECTION.
MOVE . . .. . .. TO WS-SORT-REC.
RELEASE OUR-SORT-REC FROM WS-SORT-REC.
. . .
C-OUTPUT SECTION.
DISPLAY STARTING READS OF SORTED RECORDS: .
RETURN OUR-FILE
AT END
SET NO-MORE-SORT-RECORDS TO TRUE.
PERFORM WITH TEST BEFORE UNTIL NO-MORE-SORT-RECORDS
IF SORT-RETURN = 0 THEN
DISPLAY OUR-SORT-REC = OUR-SORT-REC
RETURN OUR-FILE
AT END
SET NO-MORE-SORT-RECORDS TO TRUE
END-IF
END-PERFORM.
Restrictions on input and output procedures
Several restrictions apply to each input or output procedure called by SORT and to
each output procedure called by MERGE.
Observe these restrictions:
v The procedure must not contain any SORT or MERGE statements.
v You can use ALTER, GO TO, and PERFORM statements in the procedure to refer to
procedure-names outside the input or output procedure. However, control must
return to the input or output procedure after a GO TO or PERFORM statement.
v The remainder of the PROCEDURE DIVISION must not contain any transfers of
control to points inside the input or output procedure (with the exception of the
return of control from a declarative section).
v In an input or output procedure, you can call a program that follows standard
linkage conventions. However, the called program cannot issue a SORT or MERGE
statement.
v During a SORT or MERGE operation, the SD data item is used. You must not use it
in the output procedure before the first RETURN executes. If you move data into
this record area before the first RETURN statement, the first record to be returned
will be overwritten.
v Language Environment condition handling does not let user-written condition
handlers be established in an input or output procedure.
RELATED TASKS
Coding the input procedure on page 222
Coding the output procedure on page 224
Language Environment Programming Guide (Preparing to link-edit and run)
Defining sort and merge data sets
To use DFSORT under z/OS, code DD statements in the runtime JCL to describe the
necessary data sets that are listed below.
Chapter 12. Sorting and merging files 225
Sort or merge work
Define a minimum of three data sets: SORTWK01, SORTWK02, SORTWK03, . . .,
SORTWKnn (where nn is 99 or less). These data sets cannot be in the z/OS
UNIX file system.
SYSOUT Define for sort diagnostic messages, unless you change the data-set name.
(Change the name using either the MSGDDN keyword of the OPTION control
statement in the SORT-CONTROL data set, or using the SORT-MESSAGE special
register.)
SORTCKPT
Define if the sort or merge is to take checkpoints.
Input and output
Define input and output data sets, if any.
SORTLIB (DFSORT library)
Define the library that contains the sort modules, for example,
SYS1.SORTLIB.
RELATED TASKS
Controlling sort behavior on page 234
Using checkpoint/restart with DFSORT on page 236
Sorting variable-length records
Your sort work file will be variable length only if you define it to be variable
length, even if the input file to the sort contains variable-length records.
The compiler determines that the sort work file is variable length if you code one
of the following elements in the SD entry:
v A RECORD IS VARYING clause
v Two or more record descriptions that define records that have different sizes, or
records that contain an OCCURS DEPENDING ON clause
You cannot use RECORDING MODE V for the sort work file because the SD entry does
not allow the RECORDING MODE clause.
Performance consideration: To improve sort performance of variable-length files,
specify the most frequently occurring record length of the input file (the modal
length) on the SMS= control card or in the SORT-MODE-SIZE special register.
RELATED TASKS
Changing DFSORT defaults with control statements on page 235
Controlling sort behavior on page 234
Requesting the sort or merge
To read records from an input file (files for MERGE) without preliminary processing,
use SORT . . . USING or MERGE . . . USING and the name of the input file (files)
that you declared in a SELECT clause.
To transfer sorted or merged records from the sort or merge program to another
file without any further processing, use SORT . . . GIVING or MERGE . . . GIVING
and the name of the output file that you declared in a SELECT clause. For example:
226 Enterprise COBOL for z/OS, V5.2 Programming Guide
SORT Sort-Work-1
ON ASCENDING KEY Sort-Key-1
USING Input-File
GIVING Output-File.
For SORT . . . USING or MERGE . . . USING, the compiler generates an input
procedure to open the file (files), read the records, release the records to the sort or
merge program, and close the file (files). The file (files) must not be open when the
SORT or MERGE statement begins execution. For SORT . . . GIVING or MERGE . . .
GIVING, the compiler generates an output procedure to open the file, return the
records, write the records, and close the file. The file must not be open when the
SORT or MERGE statement begins execution.
The USING or GIVING files in a SORT or MERGE statement can be sequential files
residing in the z/OS UNIX file system.
Example: describing sort and input files for SORT on page 221
If you want an input procedure to be performed on the sort records before they are
sorted, use SORT . . . INPUT PROCEDURE. If you want an output procedure to be
performed on the sorted records, use SORT . . . OUTPUT PROCEDURE. For example:
SORT Sort-Work-1
ON ASCENDING KEY Sort-Key-1
INPUT PROCEDURE EditInputRecords
OUTPUT PROCEDURE FormatData.
Example: sorting with input and output procedures on page 228
Restriction: You cannot use an input procedure with the MERGE statement. The
source of input to the merge operation must be a collection of already sorted files.
However, if you want an output procedure to be performed on the merged
records, use MERGE . . . OUTPUT PROCEDURE. For example:
MERGE Merge-Work
ON ASCENDING KEY Merge-Key
USING Input-File-1 Input-File-2 Input-File-3
OUTPUT PROCEDURE ProcessOutput.
In the FILE SECTION, you must define Merge-Work in an SD entry, and the input files
in FD entries.
RELATED TASKS
Defining sort and merge data sets on page 225
RELATED REFERENCES
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise COBOL Language Reference)
Setting sort or merge criteria
To set sort or merge criteria, define the keys on which the operation is to be
performed.
| Note: The process of setting sort criteria that is described in this topic relates to
| the format 1 SORT statement only. For more information about sorting a table by
| using the format 2 SORT statement, see Sorting a table on page 88.
Do these steps:
Chapter 12. Sorting and merging files 227
1. In the record description of the files to be sorted or merged, define the key or
keys.
There is no maximum number of keys, but the keys must be located in the first
4092 bytes of the record description. The total length of the keys cannot exceed
4092 bytes unless the EQUALS keyword is coded in the DFSORT OPTION control
statement, in which case the total length of the keys must not exceed 4088
bytes.
Restriction: A key cannot be variably located.
2. In the SORT or MERGE statement, specify the key fields to be used for sequencing
by coding the ASCENDING or DESCENDING KEY phrase, or both. When you code
more than one key, some can be ascending, and some descending.
Specify the names of the keys in decreasing order of significance. The leftmost
key is the primary key. The next key is the secondary key, and so on.
SORT and MERGE keys can be of class alphabetic, alphanumeric, national, or numeric
(but not numeric of USAGE NATIONAL). If it has USAGE NATIONAL, a key can be of
category national or can be a national-edited or numeric-edited data item. A key
cannot be a national decimal data item or a national floating-point data item.
The collation order for national keys is determined by the binary order of the keys.
If you specify a national data item as a key, any COLLATING SEQUENCE phrase in the
SORT or MERGE statement does not apply to that key.
You can mix SORT and MERGE statements in the same COBOL program. A program
can perform any number of sort or merge operations. However, one operation
must end before another can begin.
RELATED TASKS
| Sorting a table on page 88
RELATED REFERENCES
DFSORT Application Programming Guide (SORT control statement)
SORT statement (Enterprise COBOL Language Reference)
MERGE statement (Enterprise COBOL Language Reference)
Example: sorting with input and output procedures
The following example shows the use of an input and an output procedure in a
| format 1 SORT statement. The example also shows how you can define a primary
key (SORT-GRID-LOCATION) and a secondary key (SORT-SHIFT) before using them in
| the format 1 SORT statement.
DATA DIVISION.
. . .
SD SORT-FILE
RECORD CONTAINS 115 CHARACTERS
DATA RECORD SORT-RECORD.
01 SORT-RECORD.
05 SORT-KEY.
10 SORT-SHIFT PIC X(1).
10 SORT-GRID-LOCATION PIC X(2).
10 SORT-REPORT PIC X(3).
05 SORT-EXT-RECORD.
10 SORT-EXT-EMPLOYEE-NUM PIC X(6).
10 SORT-EXT-NAME PIC X(30).
10 FILLER PIC X(73).
. . .
WORKING-STORAGE SECTION.
01 TAB1.
228 Enterprise COBOL for z/OS, V5.2 Programming Guide
05 TAB-ENTRY OCCURS 10 TIMES
INDEXED BY TAB-INDX.
10 WS-SHIFT PIC X(1).
10 WS-GRID-LOCATION PIC X(2).
10 WS-REPORT PIC X(3).
10 WS-EXT-EMPLOYEE-NUM PIC X(6).
10 WS-EXT-NAME PIC X(30).
10 FILLER PIC X(73).
. . .
PROCEDURE DIVISION.
. . .
SORT SORT-FILE
ON ASCENDING KEY SORT-GRID-LOCATION SORT-SHIFT
INPUT PROCEDURE 600-SORT3-INPUT
OUTPUT PROCEDURE 700-SORT3-OUTPUT.
. . .
600-SORT3-INPUT.
PERFORM VARYING TAB-INDX FROM 1 BY 1 UNTIL TAB-INDX > 10
RELEASE SORT-RECORD FROM TAB-ENTRY(TAB-INDX)
END-PERFORM.
. . .
700-SORT3-OUTPUT.
PERFORM VARYING TAB-INDX FROM 1 BY 1 UNTIL TAB-INDX > 10
RETURN SORT-FILE INTO TAB-ENTRY(TAB-INDX)
AT END DISPLAY Out Of Records In SORT File
END-RETURN
END-PERFORM.
RELATED TASKS
Requesting the sort or merge on page 226
Choosing alternate collating sequences
You can sort or merge records on the EBCDIC or ASCII collating sequence, or on
another collating sequence. The default collating sequence is EBCDIC unless you
code the PROGRAM COLLATING SEQUENCE clause in the OBJECT-COMPUTER paragraph.
To override the default sequence, use the COLLATING SEQUENCE phrase of the SORT or
MERGE statement. You can use different collating sequences for each SORT or MERGE
statement in your program.
The PROGRAM COLLATING SEQUENCE clause and the COLLATING SEQUENCE phrase apply
only to keys of class alphabetic or alphanumeric.
When you sort or merge an ASCII file, you have to request the ASCII collating
sequence. To do so, code the COLLATING SEQUENCE phrase of the SORT or MERGE
statement, and define the alphabet-name as STANDARD-1 in the SPECIAL-NAMES
paragraph.
RELATED TASKS
Specifying the collating sequence on page 6
Setting sort or merge criteria on page 227
RELATED REFERENCES
OBJECT-COMPUTER paragraph (Enterprise COBOL Language Reference)
SORT statement (Enterprise COBOL Language Reference)
Classes and categories of data (Enterprise COBOL Language Reference)
Chapter 12. Sorting and merging files 229
Preserving the original sequence of records with equal keys
You can preserve the order of identical collating records from input to output.
Use one of these techniques:
v Install DFSORT with the EQUALS option as the default.
v Provide, at run time, an OPTION card that has the EQUALS keyword in the
IGZSRTCD data set.
v Use the WITH DUPLICATES IN ORDER phrase in the SORT statement. Doing so adds
the EQUALS keyword to the OPTION card in the IGZSRTCD data set.
Do not use both the NOEQUALS keyword on the OPTION card and the DUPLICATES
phrase, or the run unit will end.
RELATED REFERENCES
DFSORT Application Programming Guide (OPTION control statement)
Determining whether the sort or merge was successful
The DFSORT program returns a completion code of either 0 (successful
completion) or 16 (unsuccessful completion) after each sort or merge has finished.
The completion code is stored in the SORT-RETURN special register.
You should test for successful completion after each SORT or MERGE statement. For
example:
SORT SORT-WORK-2
ON ASCENDING KEY SORT-KEY
INPUT PROCEDURE IS 600-SORT3-INPUT-PROC
OUTPUT PROCEDURE IS 700-SORT3-OUTPUT-PROC.
IF SORT-RETURN NOT=0
DISPLAY "SORT ENDED ABNORMALLY. SORT-RETURN = " SORT-RETURN.
. . .
600-SORT3-INPUT-PROC SECTION.
. . .
700-SORT3-OUTPUT-PROC SECTION.
. . .
If you do not reference SORT-RETURN anywhere in your program, the COBOL run
time tests the completion code. If it is 16, COBOL issues a runtime diagnostic
message.
By default, DFSORT diagnostic messages are sent to the SYSOUT data set. If you
want to change this default, use the MSGDDN parameter of the DFSORT OPTION
control card or use the SORT-MESSAGE special register.
If you test SORT-RETURN for one or more (but not necessarily all) SORT or MERGE
statements, the COBOL run time does not check the completion code.
RELATED TASKS
Checking for sort errors with NOFASTSRT on page 233
Controlling sort behavior on page 234
RELATED REFERENCES
DFSORT Application Programming Guide (DFSORT messages and return codes)
230 Enterprise COBOL for z/OS, V5.2 Programming Guide
Stopping a sort or merge operation prematurely
To stop a sort or merge operation, move the integer 16 into the SORT-RETURN special
register.
Move 16 into the register in either of the following ways:
v Use MOVE in an input or output procedure.
Sort or merge processing will be stopped immediately after the next RELEASE or
RETURN statement is performed.
v Reset the register in a declarative section entered during processing of a USING or
GIVING file.
Sort or merge processing will be stopped immediately after the next implicit
RELEASE or RETURN is performed, which will occur after a record has been read
from or written to the USING or GIVING file.
Control then returns to the statement following the SORT or MERGE statement.
Improving sort performance with FASTSRT
Using the FASTSRT compiler option improves the performance of most sort
operations. With FASTSRT, the DFSORT product (instead of Enterprise COBOL)
performs the I/O on the input and output files you name in the SORT . . . USING
and SORT . . . GIVING statements.
The compiler issues informational messages to point out statements in which
FASTSRT can improve performance.
Usage notes
v You cannot use the DFSORT options SORTIN or SORTOUT if you use FASTSRT. The
FASTSRT compiler option does not apply to line-sequential files you use as USING
or GIVING files.
v If you specify file status and use FASTSRT, file status is ignored during the sort.
RELATED REFERENCES
FASTSRT on page 327
FASTSRT requirements for JCL
FASTSRT requirements for sort input and output files
FASTSRT requirements for JCL
In the runtime JCL, you must assign the sort work files (SORTWKnn) to a
direct-access device, not to tape data sets.
For the input and output files, the DCB parameter of the DD statement must match
the FD description.
FASTSRT requirements for sort input and output files
If you specify FASTSRT but your code does not meet FASTSRT requirements, the
compiler issues a message and the COBOL run time performs the I/O instead.
Your program will not experience the performance improvements that are
otherwise possible.
| Note: The sort input and output files that is described in this topic relates to the
| format 1 SORT statement only.
Chapter 12. Sorting and merging files 231
To use FASTSRT, you must describe and process the input files to the sort and the
output files from the sort in these ways:
v You can name only one input file in the USING phrase. You can name only one
output file in the GIVING phrase.
v You cannot use an input procedure on an input file nor an output procedure on
an output file.
Instead of using input or output procedures, you might be able to use these
DFSORT control statements:
INREC
OUTFILE
OUTREC
INCLUDE
OMIT
STOPAFT
SKIPREC
SUM
Many DFSORT functions perform the same operations that are common in input
or output procedures. Code the appropriate DFSORT control statements instead,
and place them either in the IGZSRTCD or SORTCNTL data set.
v Do not code the LINAGE clause for the output FD entry.
v Do not code any INPUT declarative (for input files), OUTPUT declarative (for
output files), or file-specific declaratives (for either input or output files) to
apply to any FDs used in the sort.
v Do not use a variable relative file as the input or output file.
v Do not use a line-sequential file as the input or output file.
v For either an input or an output file, the record descriptions of the SD and FD
entry must define the same format (fixed or variable), and the largest records of
the SD and FD entry must define the same record length.
If you code a RELATIVE KEY clause for an output file, it will not be set by the sort.
Performance tip: If you block your input and output records, the sort performance
could be significantly improved.
QSAM requirements
v QSAM files must have a record format of fixed, variable, or spanned.
v A QSAM input file can be empty.
v To use the same QSAM file for both input and output, you must describe the file
using two different DD statements. For example, in the FILE-CONTROL SECTION
you might code this:
SELECT FILE-IN ASSIGN INPUTF.
SELECT FILE-OUT ASSIGN OUTPUTF.
In the DATA DIVISION, you would have an FD entry for both FILE-IN and
FILE-OUT, where FILE-IN and FILE-OUT are identical except for their names.
In the PROCEDURE DIVISION, your SORT statement could look like this:
SORT file-name
ASCENDING KEY data-name-1
USING FILE-IN GIVING FILE-OUT
Then in your JCL, assuming that data set INOUT has been cataloged, you would
code:
232 Enterprise COBOL for z/OS, V5.2 Programming Guide
//INPUTF DD DSN=INOUT,DISP=SHR
//OUTPUTF DD DSN=INOUT,DISP=SHR
On the other hand, if you code the same file-name in the USING and GIVING
phrases, or assign the input and output files the same ddname, then the file can
be accepted for FASTSRT either for input or output, but not both. If no other
conditions disqualify the file from being eligible for FASTSRT on input, then the
file will be accepted for FASTSRT on input, but not on output. If the file was
found to be ineligible for FASTSRT on input, it might be eligible for FASTSRT on
output.
A QSAM file that qualifies for FASTSRT can be accessed by the COBOL program
| while the format 1 SORT statement is being performed. For example, if the file is
used for FASTSRT on input, you can access it in an output procedure; if it is used
for FASTSRT on output, you can access it in an input procedure.
VSAM requirements
v A VSAM input file must not be empty.
v VSAM files cannot be password-protected.
v You cannot name the same VSAM file in both the USING and GIVING phrases.
v A VSAM file that qualifies for FASTSRT cannot be accessed by the COBOL
| program until the format 1 SORT statement processing is completed. For example,
if the file qualifies for FASTSRT on input, you cannot access it in an output
procedure and vice versa. (If you do so, OPEN fails.)
RELATED TASKS
DFSORT Application Programming Guide
Checking for sort errors with NOFASTSRT
When you compile with the NOFASTSRT option, the sort process does not check for
errors in open, close, or input or output operations for files that you reference in
| the USING or GIVING phrase of the format 1 SORT statement. Therefore, you might
need to check whether SORT completed successfully.
| Note: This topic relates to the format 1 SORT statement only.
The code required depends on whether you code a FILE STATUS clause or an ERROR
declarative for the files referenced in the USING and GIVING phrases, as shown in
the table below.
Table 32. Methods for checking for sort errors with NOFASTSRT
FILE STATUS ERROR
clause? declarative? Then do:
No No No special coding. Any failure during the sort process
causes the program to end abnormally.
| Yes No Test the SORT-RETURN special register after the format 1
| SORT statement, and test the file status key. (Not
recommended if you want complete file-status checking,
because the file status code is set but COBOL cannot
check it.)
Maybe Yes In the ERROR declarative, set the SORT-RETURN special
register to 16 to stop the sort process and indicate that it
was not successful. Test the SORT-RETURN special register
| after the format 1 SORT statement.
Chapter 12. Sorting and merging files 233
RELATED TASKS
Determining whether the sort or merge was successful on page 230
Using file status keys on page 245
Coding ERROR declaratives on page 244
Stopping a sort or merge operation prematurely on page 231
Controlling sort behavior
You can control several aspects of sort behavior by inserting values in special
registers before the sort or by using compiler options. You might also have a choice
of control statements and keywords.
You can verify sort behavior by examining the contents of special registers after the
sort.
The table below lists those aspects of sort behavior that you can affect by using
special registers or compiler options, and the equivalent sort control statement
keywords if any are available.
Table 33. Methods for controlling sort behavior
Or this control statement
Use this special register or (and keyword if
To set or test compiler option applicable)
Amount of main storage to be SORT-CORE-SIZE special register OPTION (keyword RESINV)
reserved
Amount of main storage to be SORT-CORE-SIZE special register OPTION (keywords
used MAINSIZE or MAINSIZE=MAX)
Modal length of records in a SORT-MODE-SIZE special register SMS=nnnnn
file with variable-length
records
Name of sort control statement SORT-CONTROL special register None
data set (default IGZSRTCD)
Name of sort message file SORT-MESSAGE special register OPTION (keyword MSGDDN)
(default SYSOUT)
Number of sort records SORT-FILE-SIZE special register OPTION (keyword FILSZ)
Sort completion code SORT-RETURN special register None
Sort special registers: SORT-CONTROL is an eight-character COBOL special register
that contains the ddname of the sort control statement file. If you do not want to
use the default ddname IGZSRTCD, assign to SORT-CONTROL the ddname of the
data set that contains your sort control statements.
The SORT-CORE-SIZE, SORT-FILE-SIZE, SORT-MESSAGE, and SORT-MODE-SIZE special
registers are used in the SORT interface if you assign them nondefault values. At
run time, however, any parameters in control statements in the sort control
statement data set override corresponding settings in the special registers, and a
message to that effect is issued.
You can use the SORT-RETURN special register to determine whether the sort or
merge was successful and to stop a sort or merge operation prematurely.
A compiler warning message (W-level) is issued for each sort special register that
you set in a program.
234 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Determining whether the sort or merge was successful on page 230
Stopping a sort or merge operation prematurely on page 231
Changing DFSORT defaults with control statements
Allocating space for sort files on page 236
DFSORT Application Programming Guide (Using DFSORT program
control statements)
RELATED REFERENCES
Default characteristics of the IGZSRTCD data set
Changing DFSORT defaults with control statements
If you want to change DFSORT system defaults to improve sort performance, pass
information to DFSORT through control statements in the runtime data set
IGZSRTCD.
The control statements that you can include in IGZSRTCD (in the order listed) are:
1. SMS=nnnnn, where nnnnn is the length in bytes of the most frequently occurring
record size. (Use only if the SD file is variable length.)
2. OPTION (except keywords SORTIN or SORTOUT).
3. Other DFSORT control statements (except SORT, MERGE, RECORD, or END).
Code control statements between columns 2 and 71. You can continue a control
statement record by ending the line with a comma and starting the next line with a
new keyword. You cannot use labels or comments on a record, and a record itself
cannot be a DFSORT comment statement.
RELATED TASKS
Controlling sort behavior on page 234
DFSORT Application Programming Guide (Using DFSORT program
control statements)
RELATED REFERENCES
Default characteristics of the IGZSRTCD data set
Default characteristics of the IGZSRTCD data set
The IGZSRTCD data set is optional. Its defaults are LRECL=80, BLKSIZE=400, and
ddname IGZSRTCD.
You can use a different ddname by coding it in the SORT-CONTROL special register. If
you defined a ddname for the SORT-CONTROL data set and you receive the message
IGZ0027W, an OPEN failure occurred that you should investigate.
RELATED TASKS
Controlling sort behavior on page 234
Allocating storage for sort or merge operations
Certain parameters set during the installation of DFSORT determine the amount of
storage that DFSORT uses. In general, the more storage DFSORT has available, the
faster the sort or merge operations in your program will be.
DFSORT installation should not allocate all the free space in the region for its
COBOL operation, however. When your program is running, storage must be
available for:
Chapter 12. Sorting and merging files 235
v COBOL programs that are dynamically called from an input or output procedure
v Language Environment runtime library modules
v Data management modules that can be loaded into the region for use by an
input or output procedure
v Any storage obtained by these modules
For a specific sort or merge operation, you can override the DFSORT storage
values set at installation. To do so, code the MAINSIZE and RESINV keywords on the
OPTION control statement in the sort control statement data set, or use the
SORT-CORE-SIZE special register.
Be careful not to override the storage allocation to the extent that all the free space
in the region is used for sort operations for your COBOL program.
RELATED TASKS
Controlling sort behavior on page 234
DFSORT Installation and Customization
RELATED REFERENCES
DFSORT Application Programming Guide (OPTION control statement)
Allocating space for sort files
If you use NOFASTSRT or an input procedure, DFSORT does not know the size of
the file that you are sorting. This can lead to an out-of-space condition when you
sort large files or to overallocation of resources when you sort small files.
If this occurs, you can use the SORT-FILE-SIZE special register to help DFSORT
determine the amount of resource (for example, workspace or hiperspace) needed
for the sort. Set SORT-FILE-SIZE to a reasonable estimate of the number of input
records. This value is passed to DFSORT as its FILSZ=En value.
RELATED TASKS
Controlling sort behavior on page 234
Coding the input procedure on page 222
DFSORT Application Programming Guide
Using checkpoint/restart with DFSORT
You cannot use checkpoints taken while DFSORT is running under z/OS to restart,
unless the checkpoints are taken by DFSORT.
Checkpoints taken by a COBOL program while SORT or MERGE statements execute
are invalid; such restarts are detected and canceled.
To take a checkpoint during a sort or merge operation, do these steps:
1. Add a DD statement for SORTCKPT in the JCL.
2. Code the RERUN clause in the I-O-CONTROL paragraph:
RERUN ON assignment-name
3. Code the CKPT (or CHKPT) keyword on an OPTION control statement in the sort
control statement data set (default ddname IGZSRTCD).
RELATED CONCEPTS
Chapter 32, Interrupts and checkpoint/restart, on page 641
236 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Changing DFSORT defaults with control statements on page 235
Setting checkpoints on page 641
Sorting under CICS
There is no IBM sort product that is supported under CICS. However, you can use
the SORT statement with a sort program you write that runs under CICS to sort
small amounts of data.
You must have both an input and an output procedure for the SORT statement. In
the input procedure, use the RELEASE statement to transfer records from the
COBOL program to the sort program before the sort is performed. In the output
procedure, use the RETURN statement to transfer records from the sort program to
the COBOL program after the sort is performed.
RELATED TASKS
Coding the input procedure on page 222
Coding the output procedure on page 224
Coding COBOL programs to run under CICS on page 419
RELATED REFERENCES
CICS SORT application restrictions
CICS reserved-word table on page 427
CICS SORT application restrictions
Several restrictions apply to COBOL applications that run under CICS and use the
SORT statement.
The restrictions are:
v SORT statements that include the USING or GIVING phrase are not supported.
v Sort control data sets are not supported. Data in the SORT-CONTROL special
register is ignored.
v These CICS commands in the input or output procedures can cause
unpredictable results:
CICS LINK
CICS XCTL
CICS RETURN
CICS HANDLE
CICS IGNORE
CICS PUSH
CICS POP
You can use CICS commands other than these if you use the NOHANDLE or RESP
option. Unpredictable results can occur if you do not use NOHANDLE or RESP.
RELATED REFERENCES
CICS reserved-word table on page 427
Chapter 12. Sorting and merging files 237
238 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 13. Handling errors
Put code in your programs that anticipates possible system or runtime problems. If
you do not include such code, output data or files could be corrupted, and the
user might not even be aware that there is a problem.
The error-handling code can take actions such as handling the situation, issuing a
message, or halting the program. You might for example create error-detection
routines for data-entry errors or for errors as your installation defines them. In any
event, coding a warning message is a good idea.
Enterprise COBOL contains special elements to help you anticipate and correct
error conditions:
v User-requested dumps
v ON OVERFLOW in STRING and UNSTRING operations
v ON SIZE ERROR in arithmetic operations
v Elements for handling input or output errors
v ON EXCEPTION or ON OVERFLOW in CALL statements
v User-written routines for handling errors
RELATED TASKS
Handling errors in joining and splitting strings on page 240
Handling errors in arithmetic operations on page 240
Handling errors in input and output operations on page 241
Handling errors when calling programs on page 250
Writing routines for handling errors on page 250
Requesting dumps
You can cause a formatted dump of the Language Environment runtime
environment and the member language libraries at any prespecified point in your
program by coding a call to the Language Environment callable service CEE3DMP.
77 Title-1 Pic x(80) Display.
77 Options Pic x(255) Display.
01 Feedback-code Pic x(12) Display.
. . .
Call "CEE3DMP" Using Title-1, Options, Feedback-code
To have symbolic variables included in the formatted dump, compile with the TEST
compiler option and use the VARIABLES subparameter of CEE3DMP. You can also
request, through runtime options, that a dump be produced for error conditions of
your choosing.
You can cause a system dump at any prespecified point in your program. Request
an abend without cleanup by calling the Language Environment service CEE3ABD
with a cleanup value of zero. This callable service stops the run unit immediately,
and a system dump is requested when the abend is issued.
RELATED REFERENCES
TEST on page 359
Copyright IBM Corp. 1991, 2015 239
Language Environment Debugging Guide
Language Environment Programming Reference (CEE3DMP--generate dump)
Handling errors in joining and splitting strings
During the joining or splitting of strings, the pointer used by STRING or UNSTRING
might fall outside the range of the receiving field. A potential overflow condition
exists, but COBOL does not let the overflow happen.
Instead, the STRING or UNSTRING operation is not completed, the receiving field
remains unchanged, and control passes to the next sequential statement. If you do
not code the ON OVERFLOW phrase of the STRING or UNSTRING statement, you are not
notified of the incomplete operation.
Consider the following statement:
String Item-1 space Item-2 delimited by Item-3
into Item-4
with pointer String-ptr
on overflow
Display "A string overflow occurred"
End-String
These are the data values before and after the statement is performed:
Data item PICTURE Value before Value after
Item-1 X(5) AAAAA AAAAA
Item-2 X(5) EEEAA EEEAA
Item-3 X(2) EA EA
1
Item-4 X(8) bbbbbbbb bbbbbbbb1
String-ptr 9(2) 0 0
1. The symbol b represents a blank space.
Because String-ptr has a value (0) that falls short of the receiving field, an
overflow condition occurs and the STRING operation is not completed. (Overflow
would also occur if String-ptr were greater than 9.) If ON OVERFLOW had not been
specified, you would not be notified that the contents of Item-4 remained
unchanged.
Handling errors in arithmetic operations
The results of arithmetic operations might be larger than the fixed-point field that
is to hold them, or you might have tried dividing by zero. In either case, the ON
SIZE ERROR clause after the ADD, SUBTRACT, MULTIPLY, DIVIDE, or COMPUTE statement
can handle the situation.
For ON SIZE ERROR to work correctly for fixed-point overflow and decimal
overflow, you must specify the TRAP(ON) runtime option.
The imperative statement of the ON SIZE ERROR clause will be performed and the
result field will not change in these cases:
v Fixed-point overflow
v Division by zero
v Zero raised to the zero power
240 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Zero raised to a negative number
v Negative number raised to a fractional power
Floating-point exponent overflow occurs when the value of a floating-point
computation cannot be represented in the System z floating-point operand format.
This type of overflow does not cause SIZE ERROR; an abend occurs instead. You
could code a user-written condition handler to intercept the abend and provide
your own error recovery logic.
Example: checking for division by zero
The following example shows how you can code an ON SIZE ERROR imperative
statement so that the program issues an informative message if division by zero
occurs.
DIVIDE-TOTAL-COST.
DIVIDE TOTAL-COST BY NUMBER-PURCHASED
GIVING ANSWER
ON SIZE ERROR
DISPLAY "ERROR IN DIVIDE-TOTAL-COST PARAGRAPH"
DISPLAY "SPENT " TOTAL-COST, " FOR " NUMBER-PURCHASED
PERFORM FINISH
END-DIVIDE
. . .
FINISH.
STOP RUN.
If division by zero occurs, the program writes a message and halts program
execution.
Handling errors in input and output operations
When an input or output operation fails, COBOL does not automatically take
corrective action. You choose whether your program will continue running after a
less-than-severe input or output error.
You can use any of the following techniques for intercepting and handling certain
input or output conditions or errors:
v End-of-file condition (AT END)
v ERROR declaratives
v FILE STATUS clause and file status key
v File system status code
v Imperative-statement phrases in READ or WRITE statements
For VSAM files, if you specify a FILE STATUS clause, you can also test the VSAM
status code to direct your program to error-handling logic.
v INVALID KEY phrase
To have your program continue, you must code the appropriate error-recovery
procedure. You might code, for example, a procedure to check the value of the file
status key. If you do not handle an input or output error in any of these ways, a
severity-3 Language Environment condition is signaled, which causes the run unit
to end if the condition is not handled.
The following figure shows the flow of logic after a VSAM input or output error:
Chapter 13. Handling errors 241
The following figure shows the flow of logic after an input or output error with
QSAM or line-sequential files. The error can be from a READ statement, a WRITE
statement, or a CLOSE statement with a REEL/UNIT clause (QSAM only).
242 Enterprise COBOL for z/OS, V5.2 Programming Guide
Set status key
(if present)
Applicable*
Yes Execute
imperative
imperative
phrase?
statement
No
Associated Execute
Yes
ERROR ERROR
declarative? declarative
No
File-status
Yes Test file**
clause
status key
specified ?
No
Terminate the run Return to COBOL***
unit with a message at the end of I/O
statement
*Possible phrases for QSAM are AT END, AT END-OF-PAGE, and INVALID KEY; for line
sequential, AT END.
**You need to write the code to test the file status key.
***Execution of your COBOL program continues after the input or output
statement that caused the error.
RELATED TASKS
Using the end-of-file condition (AT END)
Coding ERROR declaratives on page 244
Using file status keys on page 245
Handling errors in QSAM files on page 174
Using VSAM status codes (VSAM files only) on page 246
Handling errors in line-sequential files on page 218
Coding INVALID KEY phrases on page 249
RELATED REFERENCES
File status key (Enterprise COBOL Language Reference)
Using the end-of-file condition (AT END)
You code the AT END phrase of the READ statement to handle errors or normal
conditions, according to your program design. At end-of-file, the AT END phrase is
performed. If you do not code an AT END phrase, the associated ERROR declarative is
performed.
Chapter 13. Handling errors 243
In many designs, reading sequentially to the end of a file is done intentionally, and
the AT END condition is expected. For example, suppose you are processing a file
that contains transactions in order to update a master file:
PERFORM UNTIL TRANSACTION-EOF = "TRUE"
READ UPDATE-TRANSACTION-FILE INTO WS-TRANSACTION-RECORD
AT END
DISPLAY "END OF TRANSACTION UPDATE FILE REACHED"
MOVE "TRUE" TO TRANSACTION-EOF
END READ
. . .
END-PERFORM
Any NOT AT END phrase is performed only if the READ statement completes
successfully. If the READ operation fails because of a condition other than
end-of-file, neither the AT END nor the NOT AT END phrase is performed. Instead,
control passes to the end of the READ statement after any associated declarative
procedure is performed.
You might choose not to code either an AT END phrase or an EXCEPTION declarative
procedure, but to code a status key clause for the file instead. In that case, control
passes to the next sequential instruction after the input or output statement that
detected the end-of-file condition. At that place, have some code that takes
appropriate action.
RELATED REFERENCES
AT END phrases (Enterprise COBOL Language Reference)
Coding ERROR declaratives
You can code one or more ERROR declarative procedures that will be given control
if an input or output error occurs during the execution of your program. If you do
not code such procedures, your job could be canceled or abnormally terminated
after an input or output error occurs.
Place each such procedure in the declaratives section of the PROCEDURE DIVISION.
You can code:
v A single, common procedure for the entire program
v Procedures for each file open mode (whether INPUT, OUTPUT, I-O, or EXTEND)
v Individual procedures for each file
In an ERROR declarative procedure, you can code corrective action, retry the
operation, continue, or end execution. (If you continue processing a blocked file,
though, you might lose the remaining records in a block after the record that
caused the error.) You can use the ERROR declaratives procedure in combination
with the file status key if you want a further analysis of the error.
Multithreading: Avoid deadlocks when coding I/O declaratives in multithreaded
applications. When an I/O operation results in a transfer of control to an I/O
declarative, the automatic serialization lock associated with the file is held during
the execution of the statements within the declarative. If you code I/O operations
within your declaratives, your logic might result in a deadlock as illustrated by the
following sample:
Declaratives.
D1 section.
Use after standard error procedure on F1
Read F2.
. . .
244 Enterprise COBOL for z/OS, V5.2 Programming Guide
D2 section.
Use after standard error procedure on F2
Read F1.
. . .
End declaratives.
. . .
Rewrite R1.
Rewrite R2.
When this program is running on two threads, the following sequence of events
could occur:
1. Thread 1: Rewrite R1 acquires lock on F1 and encounters I/O error.
2. Thread 1: Enter declarative D1, holding lock on F1.
3. Thread 2: Rewrite R2 acquires lock on F2 and encounters I/O error.
4. Thread 2: Enter declarative D2.
5. Thread 1: Read F2 from declarative D1; wait on F2 lock held by thread 2.
6. Thread 2: Read F1 from declarative D2; wait on F1 lock held by thread 1.
7. Deadlock.
RELATED REFERENCES
EXCEPTION/ERROR declarative (Enterprise COBOL Language Reference)
Using file status keys
After each input or output statement is performed on a file, the system updates
values in the two digit positions of the file status key. In general, a zero in the first
position indicates a successful operation, and a zero in both positions means that
nothing abnormal occurred.
Establish a file status key by coding:
v The FILE STATUS clause in the FILE-CONTROL paragraph:
FILE STATUS IS data-name-1
v Data definitions in the DATA DIVISION (WORKING-STORAGE, LOCAL-STORAGE, or
LINKAGE SECTION), for example:
WORKING-STORAGE SECTION.
01 data-name-1 PIC 9(2) USAGE NATIONAL.
Specify the file status key data-name-1 as a two-character category alphanumeric or
category national item, or as a two-digit zoned decimal or national decimal item.
This data-name-1 cannot be variably located.
Your program can check the file status key to discover whether an error occurred,
and, if so, what type of error occurred. For example, suppose that a FILE STATUS
clause is coded like this:
FILE STATUS IS FS-CODE
FS-CODE is used by COBOL to hold status information like this:
Chapter 13. Handling errors 245
Follow these rules for each file:
v Define a different file status key for each file.
Doing so means that you can determine the cause of a file input or output
exception, such as an application logic error or a disk error.
v Check the file status key after each input or output request.
If the file status key contains a value other than 0, your program can issue an
error message or can take action based on that value.
You do not have to reset the file status key code, because it is set after each
input or output attempt.
For VSAM files, you can additionally code a second identifier in the FILE STATUS
clause to get more detailed information about VSAM input or output requests.
You can use the file status key alone or in conjunction with the INVALID KEY
phrase, or to supplement the EXCEPTION or ERROR declarative. Using the file status
key in this way gives you precise information about the results of each input or
output operation.
Example: file status key
RELATED TASKS
Using VSAM status codes (VSAM files only)
Coding INVALID KEY phrases on page 249
Finding and handling input-output errors on page 379
RELATED REFERENCES
FILE STATUS clause (Enterprise COBOL Language Reference)
File status key (Enterprise COBOL Language Reference)
Example: file status key
The following example shows how you can perform a simple check of the file
status key after opening a file.
IDENTIFICATION DIVISION.
PROGRAM-ID. SIMCHK.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT MASTERFILE ASSIGN TO AS-MASTERA
FILE STATUS IS MASTER-CHECK-KEY
. . .
DATA DIVISION.
. . .
WORKING-STORAGE SECTION.
01 MASTER-CHECK-KEY PIC X(2).
. . .
PROCEDURE DIVISION.
OPEN INPUT MASTERFILE
IF MASTER-CHECK-KEY NOT = "00"
DISPLAY "Nonzero file status returned from OPEN " MASTER-CHECK-KEY
. . .
Using VSAM status codes (VSAM files only)
Often the COBOL file status code is too general to pinpoint the disposition of a
request. You can get more detailed information about VSAM input or output
requests by coding a second data item in the FILE STATUS clause.
FILE STATUS IS data-name-1 data-name-8
246 Enterprise COBOL for z/OS, V5.2 Programming Guide
The data item data-name-1 shown above specifies the COBOL file status key, which
you define as a two-character alphanumeric or national data item, or as a two-digit
zoned decimal or national decimal item.
The data item data-name-8 specifies the VSAM status code, which you define as a
6-byte alphanumeric group data item that has three subordinate 2-byte binary
fields. The VSAM status code contains meaningful values when the COBOL file
status key is not 0.
You can define data-name-8 in the WORKING-STORAGE SECTION, as in VSAM-CODE below.
01 RETURN-STATUS.
05 FS-CODE PIC X(2).
05 VSAM-CODE.
10 VSAM-R15-RETURN PIC S9(4) Usage Comp-5.
10 VSAM-FUNCTION PIC S9(4) Usage Comp-5.
10 VSAM-FEEDBACK PIC S9(4) Usage Comp-5.
Enterprise COBOL uses data-name-8 to pass information supplied by VSAM. In the
following example, FS-CODE corresponds to data-name-1 and VSAM-CODE corresponds
to data-name-8:
Example: checking VSAM status codes
RELATED REFERENCES
FILE STATUS clause (Enterprise COBOL Language Reference)
File status key (Enterprise COBOL Language Reference)
z/OS DFSMS Macro Instructions for Data Sets (VSAM macro return and
reason codes)
Example: checking VSAM status codes
The following example reads an indexed file (starting at the fifth record), checks
the file status key after each input or output request, and displays the VSAM
status codes when the file status key is not zero.
This example also illustrates how output from this program might look if the file
being processed contained six records.
IDENTIFICATION DIVISION
PROGRAM-ID. EXAMPLE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT VSAMFILE ASSIGN TO VSAMFILE
ORGANIZATION IS INDEXED
Chapter 13. Handling errors 247
ACCESS DYNAMIC
RECORD KEY IS VSAMFILE-KEY
FILE STATUS IS FS-CODE VSAM-CODE.
DATA DIVISION.
FILE SECTION.
FD VSAMFILE
RECORD 30.
01 VSAMFILE-REC.
10 VSAMFILE-KEY PIC X(6).
10 FILLER PIC X(24).
WORKING-STORAGE SECTION.
01 RETURN-STATUS.
05 FS-CODE PIC XX.
05 VSAM-CODE.
10 VSAM-RETURN-CODE PIC S9(2) Usage Binary.
10 VSAM-COMPONENT-CODE PIC S9(1) Usage Binary.
10 VSAM-REASON-CODE PIC S9(3) Usage Binary.
PROCEDURE DIVISION.
OPEN INPUT VSAMFILE.
DISPLAY "OPEN INPUT VSAMFILE FS-CODE: " FS-CODE.
IF FS-CODE NOT = "00"
PERFORM VSAM-CODE-DISPLAY
STOP RUN
END-IF.
MOVE "000005" TO VSAMFILE-KEY.
START VSAMFILE KEY IS EQUAL TO VSAMFILE-KEY.
DISPLAY "START VSAMFILE KEY=" VSAMFILE-KEY
" FS-CODE: " FS-CODE.
IF FS-CODE NOT = "00"
PERFORM VSAM-CODE-DISPLAY
END-IF.
IF FS-CODE = "00"
PERFORM READ-NEXT UNTIL FS-CODE NOT = "00"
END-IF.
CLOSE VSAMFILE.
STOP RUN.
READ-NEXT.
READ VSAMFILE NEXT.
DISPLAY "READ NEXT VSAMFILE FS-CODE: " FS-CODE.
IF FS-CODE NOT = "00"
PERFORM VSAM-CODE-DISPLAY
END-IF.
DISPLAY VSAMFILE-REC.
VSAM-CODE-DISPLAY.
DISPLAY "VSAM-CODE ==>"
" RETURN: " VSAM-RETURN-CODE,
" COMPONENT: " VSAM-COMPONENT-CODE,
" REASON: " VSAM-REASON-CODE.
Below is a sample of the output from the example program that checks VSAM
status-code information:
OPEN INPUT VSAMFILE FS-CODE: 00
START VSAMFILE KEY=000005 FS-CODE: 00
READ NEXT VSAMFILE FS-CODE: 00
000005 THIS IS RECORD NUMBER 5
READ NEXT VSAMFILE FS-CODE: 00
000006 THIS IS RECORD NUMBER 6
READ NEXT VSAMFILE FS-CODE: 10
VSAM-CODE ==> RETURN: 08 COMPONENT: 2 REASON: 004
248 Enterprise COBOL for z/OS, V5.2 Programming Guide
Coding INVALID KEY phrases
You can include an INVALID KEY phrase in READ, START, WRITE, REWRITE, and DELETE
statements for VSAM indexed and relative files. The INVALID KEY phrase is given
control if an input or output error occurs due to a faulty index key.
You can also include the INVALID KEY phrase in WRITE requests for QSAM files, but
the phrase has limited meaning for QSAM files. It is used only if you try to write
to a disk that is full.
Use the FILE STATUS clause with the INVALID KEY phrase to evaluate the status key
and determine the specific INVALID KEY condition.
INVALID KEY phrases differ from ERROR declaratives in several ways. INVALID KEY
phrases:
v Operate for only limited types of errors. ERROR declaratives encompass all forms.
v Are coded directly with the input or output statement. ERROR declaratives are
coded separately.
v Are specific for a single input or output operation. ERROR declaratives are more
general.
If you code INVALID KEY in a statement that causes an INVALID KEY condition,
control is transferred to the INVALID KEY imperative statement. Any ERROR
declaratives that you coded are not performed.
If you code a NOT INVALID KEY phrase, it is performed only if the statement
completes successfully. If the operation fails because of a condition other than
INVALID KEY, neither the INVALID KEY nor the NOT INVALID KEY phrase is
performed. Instead, after the program performs any associated ERROR declaratives,
control passes to the end of the statement.
Example: FILE STATUS and INVALID KEY
Example: FILE STATUS and INVALID KEY
The following example shows how you can use the file status code and the
INVALID KEY phrase to determine more specifically why an input or output
statement failed.
Assume that you have a file that contains master customer records and you need
to update some of these records with information from a transaction update file.
The program reads each transaction record, finds the corresponding record in the
master file, and makes the necessary updates. The records in both files contain a
field for a customer number, and each record in the master file has a unique
customer number.
The FILE-CONTROL entry for the master file of customer records includes statements
that define indexed organization, random access, MASTER-CUSTOMER-NUMBER as the
prime record key, and CUSTOMER-FILE-STATUS as the file status key.
.
. (read the update transaction record)
.
MOVE "TRUE" TO TRANSACTION-MATCH
MOVE UPDATE-CUSTOMER-NUMBER TO MASTER-CUSTOMER-NUMBER
READ MASTER-CUSTOMER-FILE INTO WS-CUSTOMER-RECORD
INVALID KEY
Chapter 13. Handling errors 249
DISPLAY "MASTER CUSTOMER RECORD NOT FOUND"
DISPLAY "FILE STATUS CODE IS: " CUSTOMER-FILE-STATUS
MOVE "FALSE" TO TRANSACTION-MATCH
END-READ
Handling errors when calling programs
When a program dynamically calls a separately compiled program, the called
program might be unavailable. For example, the system might be out of storage or
| unable to locate the program object. If the CALL statement does not have an ON
EXCEPTION or ON OVERFLOW phrase, your application might abend.
Use the ON EXCEPTION phrase to perform a series of statements and to perform your
own error handling. For example, in the code fragment below, if program REPORTA
is unavailable, control passes to the ON EXCEPTION phrase.
MOVE "REPORTA" TO REPORT-PROG
CALL REPORT-PROG
ON EXCEPTION
DISPLAY "Program REPORTA not available, using REPORTB."
MOVE "REPORTB" TO REPORT-PROG
CALL REPORT-PROG
END-CALL
END-CALL
The ON EXCEPTION phrase applies only to the availability of the called program on
its initial load. If the called program is loaded but fails for any other reason (such
as initialization), the ON EXCEPTION phrase is not performed.
RELATED TASKS
Enterprise COBOL Migration Guide
Writing routines for handling errors
You can handle most error conditions that might occur while your program is
running by using the ON EXCEPTION phrase, ON SIZE ERROR phrase, or other
language constructs. But if an extraordinary condition such as a machine check
occurs, usually your application is abnormally terminated.
Enterprise COBOL and Language Environment provide a way for a user-written
program to gain control when such conditions occur. Using Language Environment
condition handling, you can write your own error-handling routines in COBOL.
They can report, analyze, or even fix up a program and enable it to resume
running.
When you write your own error-handling routines for an application, the COBOL
programs must be compiled with appropriate compiler options. For more
information, see OPTIMIZE on page 343.
To have Language Environment pass control to a user-written error program, you
must first identify and register its entry point to Language Environment.
PROCEDURE-POINTER data items enable you to pass the entry address of procedure
entry points to Language Environment services.
RELATED TASKS
Using procedure and function pointers on page 477
250 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
OPTIMIZE on page 343
Chapter 13. Handling errors 251
252 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 2. Compiling and debugging your program
Copyright IBM Corp. 1991, 2015 253
254 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 14. Compiling under z/OS
You can compile Enterprise COBOL programs under z/OS using job control
language (JCL), TSO commands, CLISTs, or ISPF panels.
For compiling with JCL, IBM provides a set of cataloged procedures, which can
reduce the amount of JCL coding that you need to write. If the cataloged
procedures do not meet your needs, you can write your own JCL. Using JCL, you
can compile a single program or compile several programs as part of a batch job.
When compiling under TSO, you can use TSO commands, CLISTs, or ISPF panels.
You can also compile in a z/OS UNIX shell by using the cob2 command.
You might instead want to start the Enterprise COBOL compiler from an assembler
program, for example, if your shop has developed a tool or interface that calls the
Enterprise COBOL compiler.
As part of the compilation step, you need to define the data sets needed for the
compilation and specify any compiler options necessary for your program and the
required output.
The compiler translates your COBOL program into language that the computer can
process (object code). The compiler also lists errors in your source statements and
provides supplementary information to help you debug and tune your program.
Use compiler-directing statements and compiler options to control your
compilation.
After compiling your program, you need to review the results of the compilation
and correct any compiler-detected errors.
RELATED TASKS
Compiling with JCL
Compiling under TSO on page 262
Chapter 15, Compiling under z/OS UNIX, on page 283
Starting the compiler from an assembler program on page 265
Defining compiler input and output on page 266
Specifying compiler options under z/OS on page 272
Compiling multiple programs (batch compilation) on page 275
Correcting errors in your source program on page 279
RELATED REFERENCES
Chapter 18, Compiler-directing statements, on page 373
Data sets used by the compiler under z/OS on page 267
Compiler options and compiler output under z/OS on page 274
Compiling with JCL
Include the following information in the JCL for compilation: job description,
statement to invoke the compiler, and definitions of the needed data sets
(including the directory paths of z/OS UNIX files, if any).
Copyright IBM Corp. 1991, 2015 255
The simplest way to compile your program under z/OS is to code JCL that uses a
cataloged procedure. A cataloged procedure is a set of job control statements in a
partitioned data set called the procedure library (SYS1.PROCLIB).
The following JCL shows the general format for a cataloged procedure.
//jobname JOB parameters
//stepname EXEC [PROC=]procname[,{PARM=|PARM.stepname=}options]
//SYSIN DD data-set parameters
. . . (source program to be compiled)
/*
//
Additional considerations apply when you use cataloged procedures to compile
object-oriented programs.
Example: sample JCL for a procedural DLL application on page 500
RELATED TASKS
Using a cataloged procedure
Writing JCL to compile programs on page 260
Specifying compiler options under z/OS on page 272
Specifying compiler options in a batch compilation on page 277
Compiling programs to create DLLs on page 498
RELATED REFERENCES
Data sets used by the compiler under z/OS on page 267
Using a cataloged procedure
Specify a cataloged procedure in an EXEC statement in your JCL.
For example, the following JCL calls the IBM-supplied cataloged procedure
IGYWC for compiling an Enterprise COBOL program and defining the required
data sets:
//JOB1 JOB1
//STEPA EXEC PROC=IGYWC
//COBOL.SYSIN DD *
000100 IDENTIFICATION DIVISION
* (the source code)
. . .
/*
You can omit /* after the source code. If your source code is stored in a data set,
replace SYSIN DD * with appropriate parameters that describe the data set.
You can use these procedures with any of the job schedulers that are part of z/OS.
When a scheduler encounters parameters that it does not require, the scheduler
either ignores them or substitutes alternative parameters.
If the compiler options are not explicitly supplied with the procedure, default
options established at the installation apply. You can override these default options
by using an EXEC statement that includes the required options.
You can specify data sets to be in the z/OS UNIX file system by overriding the
corresponding DD statement. However, the compiler utility files (SYSUTx) and copy
libraries (SYSLIB) you specify must be MVS data sets.
256 Enterprise COBOL for z/OS, V5.2 Programming Guide
Additional details about invoking cataloged procedures, overriding and adding to
EXEC statements, and overriding and adding to DD statements are in the Language
Environment information.
RELATED TASKS
Language Environment Programming Guide
RELATED REFERENCES
Compile procedure (IGYWC)
Compile and link-edit procedure (IGYWCL) on page 258
Compile, link-edit, and run procedure (IGYWCLG) on page 259
MVS Program Management: User's Guide and Reference
Compile procedure (IGYWC)
IGYWC is a single-step cataloged procedure for compiling a program. It produces an
object module. The compile steps in all other cataloged procedures that invoke the
compiler are similar.
You must supply the following DD statement, indicating the location of the source
program, in the input stream:
//COBOL.SYSIN DD * (or appropriate parameters)
If you use copybooks in the program that you are compiling, you must also supply
a DD statement for SYSLIB or other libraries that you specify in COPY statements. For
example:
//COBOL.SYSLIB DD DISP=SHR,DSN=DEPT88.BOBS.COBLIB
//IGYWC PROC LNGPRFX=IGY.V5R1M0,
// LIBPREFIX=CEE
//*
//* COMPILE A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE USAGE
//* LNGPRFX IGY.V5R1M0 PREFIX FOR LANGUAGE DATA SET NAMES
//* LIBPRFX CEE PREFIX FOR LIBRARY DATA SET NAMES
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//* CALLER MUST ALSO SUPPLY //COBOL.SYSLIB DD . . . for COPY statements
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=0M
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,DISP=SHR (1)
// DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
// DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSNAME=&&LOADSET,UNIT=SYSALLDA,
// DISP=(MOD,PASS),SPACE=(CYL,(1,1)),
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT8 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
(1) STEPLIB can be installation-dependent.
Example: JCL for compiling in the z/OS UNIX file system on page 258
Chapter 14. Compiling under z/OS 257
Example: JCL for compiling in the z/OS UNIX file system:
The following job uses procedure IGYWC to compile a COBOL program, demo.cbl,
that is located in the z/OS UNIX file system. The job writes the generated
compiler listing demo.lst, object file demo.o, and SYSADATA file demo.adt in the
z/OS UNIX file system.
//UNIXDEMO JOB ,
// TIME=(1),MSGLEVEL=(1,1),MSGCLASS=H,CLASS=A,REGION=50M,
// NOTIFY=&SYSUID,USER=&SYSUID
//COMPILE EXEC IGYWC,
// PARM.COBOL=LIST,MAP,RENT,FLAG(I,I),XREF,ADATA
//SYSPRINT DD PATH=/u/userid/cobol/demo.lst, (1)
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC), (2)
// PATHMODE=SIRWXU, (3)
// FILEDATA=TEXT (4)
//SYSLIN DD PATH=/u/userid/cobol/demo.o,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//SYSADATA DD PATH=/u/userid/cobol/demo.adt,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//SYSIN DD PATH=/u/userid/cobol/demo.cbl,
// PATHOPTS=ORDONLY,
// FILEDATA=TEXT,
// RECFM=F
(1) PATH specifies the path name of a file in the z/OS UNIX file system.
(2) PATHOPTS indicates the access for the file (such as read or read-write) and
sets the status for the file (such as append, create, or truncate).
(3) PATHMODE indicates the permissions, or file access attributes, to be set when
a file is created.
(4) FILEDATA specifies whether the data is to be treated as text or as binary.
You can use a mixture of files in the z/OS UNIX file system (PATH=unix-directory-
path) and traditional MVS data sets (DSN=mvs-data-set-name) in the compilation DD
statements (shown in this example as overrides). However, the compiler utility files
(DD statements SYSUTx) and COPY libraries (DD statements SYSLIB) must be MVS data
sets.
RELATED REFERENCES
Data sets used by the compiler under z/OS on page 267
UNIX System Services Command Reference
MVS JCL Reference
Compile and link-edit procedure (IGYWCL)
IGYWCL is a two-step cataloged procedure to compile and link-edit a program.
| The COBOL job step produces an object module that is input to the binder
| (linkage-editor). You can add other object modules. You must supply the following
DD statement, indicating the location of the source program, in the input stream:
//COBOL.SYSIN DD * (or appropriate parameters)
If the program uses copybooks, you must also supply a DD statement for SYSLIB or
other libraries that you specify in COPY statements. For example:
//COBOL.SYSLIB DD DISP=SHR,DSN=DEPT88.BOBS.COBLIB
//IGYWCL PROC LNGPRFX=IGY.V5R1M0,
// LIBPRFX=CEE,
// PGMLIB=&&GOSET,GOPGM=GO
258 Enterprise COBOL for z/OS, V5.2 Programming Guide
//*
//* COMPILE AND LINK EDIT A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE USAGE
//* LNGPRFX IGY.V5R1M0 PREFIX FOR LANGUAGE DATA SET NAMES
//* SYSLBLK 3200 BLOCK SIZE FOR OBJECT DATA SET
//* LIBPRFX CEE PREFIX FOR LIBRARY DATA SET NAMES
//* PGMLIB &&GOSET DATA SET NAME FOR LOAD MODULE
//* GOPGM GO MEMBER NAME FOR LOAD MODULE
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//* CALLER MUST ALSO SUPPLY //COBOL.SYSLIB DD . . . for COPY statements
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=0M
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,DISP=SHR (1)
// DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
// DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSNAME=&&LOADSET,UNIT=SYSALLDA,
// DISP=(MOD,PASS),SPACE=(CYL,(1,1)),
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT8 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//LKED EXEC PGM=IEWBLINK,COND=(8,LT,COBOL),REGION=0M
//SYSLIB DD DSNAME=&LIBPRFX..SCEELKED,DISP=SHR (2)
// DD DSNAME=&LIBPRFX..SCEELKEX,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&PGMLIB(&GOPGM),
// SPACE=(CYL,(3,1,1)),
// UNIT=SYSALLDA,DISP=(MOD,PASS),DSNTYPE=LIBRARY
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
(1) STEPLIB can be installation-dependent.
(2) SYSLIB can be installation-dependent.
Compile, link-edit, and run procedure (IGYWCLG)
IGYWCLG is a three-step cataloged procedure to compile, link-edit, and run a
program.
| The COBOL job step produces an object module that is input to the binder
| (linkage-editor). You can add other object modules. If the COBOL program refers
to any data sets, you must also supply DD statements that define these data sets.
You must supply the following DD statement, indicating the location of the source
program, in the input stream:
//COBOL.SYSIN DD * (or appropriate parameters)
If the program uses copybooks, you must also supply a DD statement for SYSLIB or
other libraries that you specify in COPY statements. For example:
Chapter 14. Compiling under z/OS 259
//COBOL.SYSLIB DD DISP=SHR,DSN=DEPT88.BOBS.COBLIB
//IGYWCLG PROC LNGPRFX=IGY.V5R1M0,
// LIBPRFX=CEE,GOPGM=GO
//*
//* COMPILE, LINK EDIT AND RUN A COBOL PROGRAM
//*
//* PARAMETER DEFAULT VALUE USAGE
//* LNGPRFX IGY.V5R1M0 PREFIX FOR LANGUAGE DATA SET NAMES
//* LIBPRFX CEE PREFIX FOR LIBRARY DATA SET NAMES
//* GOPGM GO MEMBER NAME FOR LOAD MODULE
//*
//* CALLER MUST SUPPLY //COBOL.SYSIN DD . . .
//*
//* CALLER MUST ALSO SUPPLY //COBOL.SYSLIB DD . . . for COPY statements
//*
//COBOL EXEC PGM=IGYCRCTL,REGION=0M
//STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP,DISP=SHR (1)
// DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR
// DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSNAME=&&LOADSET,UNIT=SYSALLDA,
// DISP=(MOD,PASS),SPACE=(CYL,(1,1)),
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT2 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT4 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT5 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT6 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT7 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT8 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//LKED EXEC PGM=IEWBLINK,COND=(8,LT,COBOL),REGION=0M
//SYSLIB DD DSNAME=&LIBPRFX..SCEELKED,DISP=SHR (2)
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,DELETE)
// DD DDNAME=SYSIN
//SYSLMOD DD DSNAME=&&GOSET(&GOPGM),SPACE=(CYL,(1,1,1)),
// UNIT=SYSALLDA,DISP=(MOD,PASS),DSNTYPPE=LIBRARY
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//GO EXEC PGM=*.LKED.SYSLMOD,COND=((8,LT,COBOL),(4,LT,LKED)),
// REGION=0M
//STEPLIB DD DSNAME=&LIBPRFX..SCEERUN,DISP=SHR (1)
// DD DSNAME=&LIBPRFX..SCEERUN2,DISP=SHR
//SYSPRINT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
(1) STEPLIB can be installation-dependent.
(2) SYSLIB can be installation-dependent.
Writing JCL to compile programs
If the cataloged procedures do not provide you with the flexibility that you need
for more complex programs, write your own job control statements. The following
example shows the general format of JCL used to compile a program.
//jobname JOB acctno,name,MSGCLASS=1 (1)
//stepname EXEC PGM=IGYCRCTL,PARM=(options) (2)
//STEPLIB DD DSNAME=IGY.V5R1M0.SIGYCOMP,DISP=SHR (3)
260 Enterprise COBOL for z/OS, V5.2 Programming Guide
// DD DSNAME=SYS1.SCEERUN,DISP=SHR
// DD DSNAME=SYS1.SCEERUN2,DISP=SHR
//SYSUT1 DD UNIT=SYSALLDA,SPACE=(subparms) (4)
//SYSUT2 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT3 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT4 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT5 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT6 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT7 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT8 DD UNIT=SYSALLDA,SPACE)=(subparms)
//SYSUT9 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(subparms)
//SYSPRINT DD SYSOUT=A (5)
//SYSLIN DD DSNAME=MYPROG,UNIT=SYSALLDA, (6)
// DISP=(MOD,PASS),SPACE=(subparms)
//SYSIN DD DSNAME=dsname,UNIT=device, (7)
VOLUME=(subparms),DISP=SHR
(1) The JOB statement indicates the beginning of a job.
(2) The EXEC statement specifies that the Enterprise COBOL compiler
(IGYCRCTL) is to be invoked.
(3) This DD statement defines the data set where the Enterprise COBOL
compiler resides.
The Language Environment SCEERUN and SCEERUN2 data sets must be
included in the concatenation (together with the compiler SIGYCOMP data
set), unless the Language Environment data sets are available in the
LNKLST.
(4) The SYSUT DD statements define the utility data sets that the compiler will
use to process the source program. All SYSUT files must be on direct-access
storage devices.
(5) The SYSPRINT DD statement defines the data set that receives output from
compiler options such as LIST and MAP. SYSOUT=A is the standard
designation for data sets whose destination is the system output device.
(6) The SYSLIN DD statement defines the data set (the object module) that
receives output from the OBJECT compiler option.
(7) The SYSIN DD statement defines the data set (source code) to be used as
input to the job step.
You can use a mixture of files in the z/OS UNIX file system (PATH=unix-directory-
path) and traditional MVS data sets (DSN=mvs-data-set-name) in the compilation DD
statements for the following data sets:
v Sources files
v Object files
v Listings
v ADATA files
v Debug files
v Executable modules
Chapter 14. Compiling under z/OS 261
However, the compiler utility files (DD statements SYSUTx) and COPY libraries (DD
statement SYSLIB) must be MVS data sets.
Example: user-written JCL for compiling
Example: sample JCL for a procedural DLL application on page 500
RELATED REFERENCES
MVS Program Management: User's Guide and Reference
Example: user-written JCL for compiling
The following example shows a few possibilities for adapting the basic JCL.
//JOB1 JOB (1)
//STEP1 EXEC PGM=IGYCRCTL,PARM=OBJECT (2)
//STEPLIB DD DSNAME=IGY.V5R1M0.SIGYCOMP,DISP=SHR
// DD DSNAME=SYS1.SCEERUN,DISP=SHR
// DD DSNAME=SYS1.SCEERUN2,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT5 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT6 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT7 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT8 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT9 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
//SYSPRINT DD SYSOUT=A
//SYSLIN DD DSNAME=MYPROG,UNIT=SYSDA,
// DISP=(MOD,PASS),SPACE=(TRK,(3,3))
//SYSIN DD * (3)
000100 IDENTIFICATION DIVISION.
. . .
/* (4)
(1) JOB1 is the name of the job.
(2) STEP1 is the name of the sole job step in the job. The EXEC statement also
specifies that the generated object code should be placed on disk or tape
(to be used as input to the link step).
(3) The asterisk indicates that the input data set follows in the input stream.
(4) The delimiter statement /* separates data from subsequent control
statements in the input stream.
Compiling under TSO
Under TSO, you can use TSO commands, command lists (CLISTs), REXX execs, or
ISPF to compile programs using traditional MVS data sets. You can use TSO
commands or REXX execs to compile programs using z/OS UNIX files.
With each method, you need to allocate the data sets and request the compilation:
1. Use the ALLOCATE command to allocate data sets.
For any compilation, allocate the work data sets (SYSUTn) and the SYSIN and
SYSPRINT data sets.
262 Enterprise COBOL for z/OS, V5.2 Programming Guide
If you specify certain compiler options, you must allocate other data sets. For
example, if you specify the TERMINAL compiler option, you must allocate the
SYSTERM data set to receive compiler messages at your terminal.
You can allocate data sets in any order. However, you must allocate all needed
data sets before you start to compile.
2. Use the CALL command at the READY prompt to request compilation:
CALL IGY.V5R1M0.SIGYCOMP(IGYCRCTL)
You can specify the ALLOCATE and CALL commands on the TSO command line, or, if
you are not using z/OS UNIX files, you can include them in a CLIST.
You can allocate z/OS UNIX files for all the compiler data sets except the SYSUTx
utility data sets and the SYSLIB libraries. ALLOCATE statements have the following
form:
Allocate File(SYSIN) Path(/u/myu/myap/std/prog2.cbl)
Pathopts(ORDONLY) Filedata(TEXT)
Example: ALLOCATE and CALL for compiling under TSO
Example: CLIST for compiling under TSO on page 264
RELATED REFERENCES
Data sets used by the compiler under z/OS on page 267
Example: ALLOCATE and CALL for compiling under TSO
The following example shows how to specify ALLOCATE and CALL commands when
you are compiling under TSO.
[READY]
ALLOCATE FILE(SYSUT1) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT2) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT3) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT4) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT5) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT6) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT7) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT8) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT9) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT10) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT11) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT12) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT13) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT14) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSUT15) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSMDECK) CYLINDERS SPACE(1 1)
[READY]
ALLOCATE FILE(SYSPRINT) SYSOUT
[READY]
ALLOCATE FILE(SYSTERM) DATASET(*)
[READY]
ALLOCATE FILE(SYSLIN) DATASET(PROG2.OBJ) NEW TRACKS SPACE(3,3)
[READY]
ALLOCATE FILE(SYSIN) DATASET(PROG2.COBOL) SHR
[READY]
Chapter 14. Compiling under z/OS 263
CALL IGY.V5R1M0.SIGYCOMP(IGYCRCTL) LIST,NOCOMPILE(S),OBJECT,FLAG(E,E),TERMINAL
.
(COBOL listings and messages)
.
[READY]
FREE FILE(SYSUT1,SYSUT2,SYSUT3,SYSUT4,SYSUT5,SYSUT6,SYSUT7,SYSUT8,SYSUT9,SYSUT10,SYSUT11,SYSUT12,
SYSUT13,SYSUT14,SYSUT15,SYSMDECK,SYSPRINT,SYSTERM,+
SYSIN,SYSLIN)
[READY]
Example: CLIST for compiling under TSO
The following example shows a CLIST for compiling under TSO. The FREE
commands are not required. However, good programming practice dictates that
you free files before you allocate them.
PROC 1 MEM
CONTROL LIST
FREE F(SYSUT1)
FREE F(SYSUT2)
FREE F(SYSUT3)
FREE F(SYSUT4)
FREE F(SYSUT5)
FREE F(SYSUT6)
FREE F(SYSUT7)
FREE F(SYSUT8)
FREE F(SYSUT9)
FREE F(SYSUT10)
FREE F(SYSUT11)
FREE F(SYSUT12)
FREE F(SYSUT13)
FREE F(SYSUT14)
FREE F(SYSUT15)
FREE F(SYSMDECK)
FREE F(SYSPRINT)
FREE F(SYSIN)
FREE F(SYSLIN)
ALLOC F(SYSPRINT) SYSOUT
ALLOC F(SYSIN) DA(COBOL.SOURCE(&MEM)) SHR REUSE
ALLOC F(SYSLIN) DA(COBOL.OBJECT(&MEM)) OLD REUSE
ALLOC F(SYSUT1) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT2) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT3) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT4) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT5) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT6) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT7) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT8) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT9) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT10) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT11) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT12) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT13) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT14) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSUT15) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
ALLOC F(SYSMDECK) NEW SPACE(1,1) CYL UNIT(SYSALLDA)
CALL IGY.V5R1M0.SIGYCOMP(IGYCRCTL)
RELATED REFERENCES
TSO/E Command Reference
264 Enterprise COBOL for z/OS, V5.2 Programming Guide
Starting the compiler from an assembler program
You can start the Enterprise COBOL compiler from within an assembler program
by using the ATTACH or the LINK macro by dynamic invocation. You must identify
the compiler options and the ddnames of the data sets to be used during
processing.
For example:
symbol {LINK|ATTACH} EP=IGYCRCTL,PARAM=(optionlist[,ddnamelist]),VL=1
EP Specifies the symbolic name of the compiler. The control program (from
the library directory entry) determines the entry point at which the
program should begin running.
PARAM Specifies, as a sublist, address parameters to be passed from the assembler
program to the compiler.
The first fullword in the address parameter list contains the address of the
COBOL optionlist. The second fullword contains the address of the
ddnamelist.
optionlist
Specifies the address of a variable-length list that contains the COBOL
options specified for compilation. This address must be written even if no
list is provided.
The optionlist must begin on a halfword boundary. The 2 high-order bytes
contain a count of the number of bytes in the remainder of the list. If no
options are specified, the count must be zero. The optionlist is freeform,
with each field separated from the next by a comma. No blanks or zeros
should appear. The compiler recognizes only the first 100 characters.
ddnamelist
Specifies the address of a variable-length list that contains alternative
ddnames for the data sets used during compiler processing. If standard
ddnames are used, the ddnamelist can be omitted.
The ddnamelist must begin on a halfword boundary. The 2 high-order bytes
contain a count of the number of bytes in the remainder of the list. Each
name of less than 8 bytes must be left justified and padded with blanks. If
an alternate ddname is omitted from the list, the standard name is
assumed. If the name is omitted, the 8-byte entry must contain binary
zeros. You can omit names from the end by shortening the list.
All SYSUTn data sets specified must be on direct-access storage devices
and have physical sequential organization. They must not reside in the
z/OS UNIX file system.
The following table shows the sequence of the 8-byte entries in the
ddnamelist.
Alternative ddname 8-byte entry Name for which alternative ddname is substituted
1 SYSLIN
2 Not applicable
3 Not applicable
4 SYSLIB
5 SYSIN
6 SYSPRINT
Chapter 14. Compiling under z/OS 265
Alternative ddname 8-byte entry Name for which alternative ddname is substituted
7 SYSPUNCH
8 SYSUT1
9 SYSUT2
10 SYSUT3
11 SYSUT4
12 SYSTERM
13 SYSUT5
14 SYSUT6
15 SYSUT7
16 SYSADATA
17 SYSJAVA
18 Not applicable
19 SYSMDECK
20 DBRMLIB
21 SYSOPTF
22 SYSUT8
23 SYSUT9
24 SYSUT10
25 SYSUT11
26 SYSUT12
27 SYSUT13
28 SYSUT14
29 SYSUT15
VL Specifies that the sign bit is to be set to 1 in the last fullword of the
address parameter list.
When the compiler completes processing, it puts a return code in register 15.
RELATED TASKS
Defining compiler input and output
RELATED REFERENCES
Data sets used by the compiler under z/OS on page 267
Compiler options and compiler output under z/OS on page 274
Defining compiler input and output
You need to define several kinds of data sets that the compiler uses to do its work.
The compiler takes input data sets and libraries and produces various types of
output, including object code, listings, and messages. The compiler also uses utility
data sets during compilation.
RELATED TASKS
Defining the source code data set (SYSIN) on page 269
Defining a compiler-option data set (SYSOPTF) on page 269
Specifying source libraries (SYSLIB) on page 270
266 Enterprise COBOL for z/OS, V5.2 Programming Guide
Defining the output data set (SYSPRINT) on page 270
Directing compiler messages to your terminal (SYSTERM) on page 271
Creating object code (SYSLIN or SYSPUNCH) on page 271
Defining an associated-data file (SYSADATA) on page 271
Defining the Java-source output file (SYSJAVA) on page 272
Defining the library-processing output file (SYSMDECK) on page 272
RELATED REFERENCES
Data sets used by the compiler under z/OS
Compiler options and compiler output under z/OS on page 274
Data sets used by the compiler under z/OS
The following table lists the function, device requirements, and allowable device
classes for each data set that the compiler uses.
Table 34. Compiler data sets
Can be in
Allowable z/OS UNIX
Device device file
Type ddname Function Required? requirements classes system?
1
Input SYSIN Reading source Yes Card reader; Any Yes
program intermediate
storage
SYSOPTF Reading compiler If OPTFILE is in effect Card reader; Any Yes
options intermediate
storage; direct
access
SYSLIB or Reading user source If program has COPY or Direct access SYSDA No
other copy libraries (PDSs or BASIS statements
libraries1 PDSEs)
| Utility3 SYSUT1, Work data set used Yes Direct access SYSALLDA No
SYSUT2, by compiler during
SYSUT3, compilation
SYSUT4,
SYSUT62
SYSUT52 Work data set used If program has COPY, Direct access SYSALLDA No
by compiler during REPLACE, or BASIS
compilation statements
SYSUT72 Work data set used Yes Direct access SYSALLDA No
by compiler to create
listing
SYSUT8, Work data set used Yes Direct access SYSALLDA No
SYSUT9, by compiler during
SYSUT10, compilation
SYSUT11,
SYSUT12,
SYSUT13,
SYSUT14,
2
SYSUT15,
Chapter 14. Compiling under z/OS 267
Table 34. Compiler data sets (continued)
Can be in
Allowable z/OS UNIX
Device device file
Type ddname Function Required? requirements classes system?
1
Output SYSPRINT Writing storage map, Yes Printer; SYSSQ, SYSDA, Yes
listings, and intermediate standard
messages storage output class
A
SYSTERM Writing progress and If TERM is in effect Output Yes
diagnostic messages device; TSO
terminal
SYSPUNCH Creating object code If DECK is in effect Card punch; SYSSQ, SYSDA Yes
direct access
SYSLIN Creating object If OBJECT is in effect Direct access SYSSQ, SYSDA Yes
module data set as
output from compiler
| and input to binder
| (linkage-editor)
SYSADATA1 Writing associated If ADATA is in effect Output Yes
data file records device
SYSJAVA Creating generated If compiling a class (Must be a Yes
Java source file for definition z/OS UNIX
a class definition file)
SYSUDUMP, Writing dump If DUMP is in effect Direct access SYSDA Yes
SYSABEND, or (should be rarely used)
SYSMDUMP
SYSMDECK Processing for the Yes Direct access SYSALLDA Yes
MDECK option, or a
work data set if
NOMDECK is specified.
1. You can use the EXIT option to provide user exits from these data sets.
2. These data sets must be single volume.
| 3. Do not use DSNTYPE=LARGE for utility data sets (SYSUT1 - SYSUT15).
RELATED REFERENCES
Logical record length and block size
EXIT on page 324
Logical record length and block size
For compiler data sets other than the work data sets (SYSUTn) and z/OS UNIX
files, you can set the block size by using the BLKSIZE subparameter of the DCB
parameter. The value must be permissible for the device on which the data set
resides. The values you set depend on whether the data sets are fixed length or
variable length.
For fixed-length records (RECFM=F or RECFM=FB), LRECL is the logical record length;
and BLKSIZE equals LRECL multiplied by n where n is equal to the blocking factor.
The following table shows the defined values for the fixed-length data sets. In
general, you should not change these values, but you can change the value for
theSYSPRINT data set. You can specify BLKSIZE=0, which results in a
system-determined block size.
268 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 35. Block size of fixed-length compiler data sets
Data set RECFM LRECL (bytes) BLKSIZE1
SYSIN F or FB 80 80 x n
SYSLIB or other copy libraries F or FB 80 80 x n
SYSLIN F or FB 80 80 x n
SYSMDECK F or FB 80 80 x n
SYSOPTF F or FB 80 80 x n
2
SYSPRINT F or FB 133 133 x n
SYSPUNCH F or FB 80 80 x n
SYSTERM F or FB 80 80 x n
1. n = blocking factor
2. If you specify BLKSIZE=0, the system determines the block size.
For variable-length records (RECFM=V), LRECL is the logical record length, and
BLKSIZE equals LRECL plus 4.
Table 36. Block size of variable-length compiler data sets
LRECL BLKSIZE (bytes) minimum
Data set RECFM (bytes) acceptable value
SYSADATA VB 1020 1024
Defining the source code data set (SYSIN)
Define the data set that contains your source code by using the SYSIN DD statement
as shown below.
//SYSIN DD DSNAME=dsname,UNIT=SYSSQ,VOLUME=(subparms),DISP=SHR
You can place your source code or BASIS statement directly in the input stream. To
do so, use this SYSIN DD statement:
//SYSIN DD *
The source code or BASIS statement must follow theDD * statement. If another job
step follows the compilation, the EXEC statement for that step must follow the /*
statement or the last source statement.
Defining a compiler-option data set (SYSOPTF)
Define a data set that contains the compiler options for your COBOL program by
coding the SYSOPTF DD statement as shown below.
//SYSOPTF DD DSNAME=dsname,UNIT=SYSDA,VOLUME=(subparms),DISP=SHR
To use a compiler-option data set, specify OPTFILE either as a compiler invocation
option or in a PROCESS or CBL statement in your source program.
Within the SYSOPTF data set:
v Specify compiler options in free form between columns 2 and 72, using the same
syntax as you use for invocation options or for compiler options in a PROCESS or
CBL statement.
v Code an asterisk (*) in column 1 to cause a line to be treated as a comment.
Chapter 14. Compiling under z/OS 269
v Optionally code sequence numbers in columns 73 through 80; those columns are
ignored.
You can optionally place the compiler options directly in the input stream after the
SYSOPTF DD statement if you compile using the OPTFILE option:
//COB EXEC PGM=IGYCRCTL,PARM=OPTFILE
//SYSOPTF DD DATA,DLM=@@
SSRANGE ARITH(COMPAT)
OPTIMIZE
. . .
@@
//SYSIN DD . . .
You can concatenate multiple SYSOPTF DD statements if you have multiple
compiler-option data sets:
//SYSOPTF DD DSNAME=dsname1, . . .
// DD DSNAME=dsname2, . . .
Compiler options that are in later data sets in the concatenation take precedence
over options in earlier data sets in the concatenation.
RELATED REFERENCES
Logical record length and block size on page 268
OPTFILE on page 342
Specifying source libraries (SYSLIB)
Use SYSLIB DD statements if your program contains COPY or BASIS statements.
These DD statements define the libraries (partitioned data sets) that contain the data
requested by COPY statements in the source code or by BASIS statements in the
input stream.
//SYSLIB DD DSNAME=copylibname,DISP=SHR
Concatenate multiple DD statements if you have multiple copy or basis libraries:
//SYSLIB DD DSNAME=PROJECT.USERLIB,DISP=SHR
// DD DSNAME=SYSTEM.COPYX,DISP=SHR
Libraries are on direct-access storage devices. They cannot be in the z/OS UNIX
file system when you compile with JCL or under TSO.
You do not need the SYSLIB DD statement if the NOLIB option is in effect.
Defining the output data set (SYSPRINT)
You can use ddname SYSPRINT to produce a listing. The listing includes the results
of the default or requested options of the PARM parameter (that is, diagnostic
messages and the object-code listing).
You can direct the output to a SYSOUT data set, a printer, a direct-access storage
device, or a magnetic-tape device. For example:
//SYSPRINT DD SYSOUT=A
The SYSPRINT data set can be a sequential data set, a PDS or PDSE member, or a
z/OS UNIX file. For details about how to specify the record format, record length,
and block size of the SYSPRINT data set, see the related reference below.
270 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
Logical record length and block size on page 268
Directing compiler messages to your terminal (SYSTERM)
If you are compiling under TSO, you can define the SYSTERM data set to send
compiler messages to your terminal.
ALLOC F(SYSTERM) DA(*)
You can define SYSTERM in various other ways, for example to a SYSOUT data set,
a data set on disk, a file in the z/OS UNIX file system, or to another print class.
Creating object code (SYSLIN or SYSPUNCH)
When using the OBJECT compiler option, you can store the object code on disk as a
traditional MVS data set or a z/OS UNIX file, or on tape. The compiler uses the
file that you define in the SYSLIN or SYSPUNCH DD statement.
//SYSLIN DD DSNAME=dsname,UNIT=SYSDA,
// SPACE=(subparms),DISP=(MOD,PASS)
Use the DISP parameter of the SYSLIN DD statement to indicate whether the object
code data set is to be:
| v Passed to the binder (linkage-editor)
v Cataloged
v Kept
v Added to an existing cataloged library
In the example above, the data is created and passed to another job step, the
| binder (linkage-editor) job step.
Your installation might use the DECK option and the SYSPUNCH DD statement. B is the
standard output class for punch data sets:
//SYSPUNCH DD SYSOUT=B
You do not need the SYSLIN DD statement if the NOOBJECT option is in effect. You do
not need the SYSPUNCH DD statement if the NODECK option is in effect.
RELATED REFERENCES
OBJECT on page 340
DECK on page 319
Defining an associated-data file (SYSADATA)
Define a SYSADATA file if you use the ADATA compiler option.
//SYSADATA DD DSNAME=dsname,UNIT=SYSDA
The SYSADATA file will be a sequential file that contains specific record types that
have information about the program that is collected during compilation. The file
can be a traditional MVS data set or a z/OS UNIX file.
RELATED REFERENCES
ADATA on page 305
Chapter 14. Compiling under z/OS 271
Defining the Java-source output file (SYSJAVA)
Add the SYSJAVA DD statement if you are compiling an OO program. The generated
Java source file is written to the SYSJAVA ddname.
//SYSJAVA DD PATH=/u/userid/java/Classname.java,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU,
// FILEDATA=TEXT
The SYSJAVA file must be in the z/OS UNIX file system.
RELATED TASKS
Compiling OO applications in JCL or TSO/E on page 295
Defining the library-processing output file (SYSMDECK)
The SYSMDECK data set is required for all compilations. If you specify the MDECK
compiler option, the SYSMDECK DD allocation must specify a permanent data set.
However, if you use the NOMDECK option, SYSMDECK can be specified as a utility
(temporary) data set.
//SYSMDECK DD DSNAME=dsname,UNIT=SYSDA
The SYSMDECK file will contain a copy of the updated input source after library
processing, that is, the result of COPY, BASIS, REPLACE, EXEC SQL INCLUDE, and EXEC
SQLIMS INCLUDE statements. The file can be a traditional MVS data set or a z/OS
UNIX file.
RELATED REFERENCES
MDECK on page 336
Specifying compiler options under z/OS
The compiler is installed with default compiler options. While installing the
compiler, the system programmer can fix compiler option settings to, for example,
ensure better performance or maintain certain standards. You cannot override any
compiler options that are fixed.
For options that are not fixed, you can override the default settings by specifying
compiler options in any of these ways:
v Code them on the PROCESS or CBL statement in COBOL source.
v Include them when you start the compiler, either on the PARM parameter on the
EXEC statement in the JCL or on the command line under TSO.
v Include them in a SYSOPTF data set, and specify the OPTFILE compiler option in
either of the above ways.
The compiler recognizes the options in the following order of precedence from
highest to lowest:
1. Installation defaults that are fixed by your site
2. Values of the BUFSIZE, OUTDD, SQL, and SQLIMS compiler options in effect for the
first program in a batch
3. Options specified on PROCESS (or CBL) statements, preceding the IDENTIFICATION
DIVISION
4. Options specified on the compiler invocation (JCL PARM parameter or the TSO
CALL command)
5. Installation defaults that are not fixed
272 Enterprise COBOL for z/OS, V5.2 Programming Guide
This order of precedence also determines which options are in effect when
conflicting or mutually exclusive options are specified.
The precedence of options in a SYSOPTF data set depends on where you specify the
OPTFILE compiler option. For example, if you specify OPTFILE in a PROCESS
statement, the SYSOPTF options supersede the options that you specify in the
compiler invocation. For further details, see the related reference below about the
OPTFILE option.
Most of the options come in pairs; you select one or the other. For example, the
option pair for a cross-reference listing is XREF|NOXREF. If you want a
cross-reference listing, specify XREF; if you do not, specify NOXREF.
Some options have subparameters. For example, if you want 44 lines per page on
your listings, specify LINECOUNT(44).
Example: specifying compiler options using JCL on page 274
Example: specifying compiler options under TSO on page 274
RELATED TASKS
Defining a compiler-option data set (SYSOPTF) on page 269
Specifying compiler options in the PROCESS (CBL) statement
Specifying compiler options in a batch compilation on page 277
RELATED REFERENCES
Compiler options and compiler output under z/OS on page 274
Chapter 17, Compiler options, on page 301
Conflicting compiler options on page 304
OPTFILE on page 342
Specifying compiler options in the PROCESS (CBL) statement
Within a COBOL program, you can code most compiler options in PROCESS (CBL)
statements. Code the statements before the IDENTIFICATION DIVISION header and
before any comment lines or compiler-directing statements.
CBL/PROCESS statement syntax
CBL
PROCESS options-list
If you do not use a sequence field, you can start a PROCESS statement in column 1
or after. If you use a sequence field, the sequence number must start in column 1
and must contain six characters; the first character must be numeric. If used with a
sequence field, PROCESS can start in column 8 or after.
You can use CBL as a synonym for PROCESS. CBL can likewise start in column 1 or
after if you do not use a sequence field. If used with a sequence field, CBL can start
in column 8 or after.
You must end PROCESS and CBL statements at or before column 72.
Chapter 14. Compiling under z/OS 273
Use one or more blanks to separate a PROCESS or CBL statement from the first
option in options-list. Separate options with a comma or a blank. Do not insert
spaces between individual options and their suboptions.
You can code more than one PROCESS or CBL statement. If you do so, the statements
must follow one another with no intervening statements. You cannot continue
options across multiple PROCESS or CBL statements.
Your programming organization can inhibit the use of PROCESS (CBL) statements by
using the default options module of the COBOL compiler. If PROCESS or CBL
statements that are not allowed by the organization are found in a COBOL
program, the COBOL compiler generates error diagnostics.
RELATED REFERENCES
Reference format (Enterprise COBOL Language Reference)
CBL (PROCESS) statement (Enterprise COBOL Language Reference)
Example: specifying compiler options using JCL
The following example shows how to specify compiler options under z/OS using
JCL.
. . .
//STEP1 EXEC PGM=IGYCRCTL,
// PARM=LIST,NOCOMPILE(S),OBJECT,FLAG(E,E)
Example: specifying compiler options under TSO
The following example shows how to specify compiler options under TSO.
. . .
[READY]
CALL SYS1.LINKLIB(IGYCRCTL) LIST,NOCOMPILE(S),OBJECT,FLAG(E,E)
Compiler options and compiler output under z/OS
When the compiler finishes processing your source program, it will have produced
one or more outputs, depending on the compiler options that were in effect.
Table 37. Types of compiler output under z/OS
Compiler option Compiler output Type of output
ADATA Information about the program being compiled Associated-data file
DLL Object module that is enabled for DLL support Object
DUMP System dump, if compilation ended with abnormal Listing
termination (requires SYSUDUMP, SYSABEND, or SYSMDUMP
DD statement); should be used rarely
EXPORTALL Exported symbols for a DLL Object
FLAG List of errors that the compiler found in your program Listing
LIST Listing of object code in machine and assembler Listing
language
| MAP(HEX) or MAP(DEC) Map of the data items in your program Listing
MDECK Expansion of library-processing statements in your Library-processing side file
program
NUMBER User-supplied line numbers shown in listing Listing
OBJECT or DECK with COMPILE Your object code Object
OFFSET Map of the relative addresses in your object code Listing
274 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 37. Types of compiler output under z/OS (continued)
Compiler option Compiler output Type of output
OPTIMIZE(1) or OPTIMIZE(2) Optimized object code Object
RENT Reentrant object code Object
SOURCE Listing of your source program Listing
SQL SQL statements and host variable information for DB2 Database request module
bind process (DBRM)
SSRANGE Extra code for checking references within tables In object
TERMINAL Progress and diagnostic messages sent to terminal Terminal
TEST DWARF format debugging information in the object Object
module, to enable interactive debugging
NOTEST(DWARF) Basic DWARF format diagnostic information, to enable Object
application failure analysis tools
VBREF Cross-reference listing of verbs in your source program Listing
XREF Sorted cross-reference listing of names of procedures, Listing
programs, and data
Listing output from compilation will be in the data set defined by SYSPRINT; object
output will be in SYSLIN or SYSPUNCH. Progress and diagnostic messages can be
directed to the SYSTERM data set and included in the SYSPRINT data set. The
database request module (DBRM) is the data set defined in DBRMLIB.
Save the listings you produced during compilation. You can use them during the
testing of your work if you need to debug or tune. You might also use the listings
for diagnosis and debugging after the application is in production.
After compilation, fix any errors that the compiler found in your program. If no
| errors were detected, you can go to the next step in the process: binding
| (link-editing) your program. (If you used compiler options to suppress object code
generation, you must recompile to obtain object code.)
RELATED TASKS
Language Environment Programming Guide (Preparing to link-edit and run)
RELATED REFERENCES
Messages and listings for compiler-detected errors on page 280
Chapter 17, Compiler options, on page 301
Compiling multiple programs (batch compilation)
You can compile a sequence of separate COBOL programs by using a single
invocation of the compiler. You can link the object program produced from this
| compilation into one program object or separate program objects, controlled by the
NAME compiler option.
When you compile several programs as part of a batch job, you need to:
| v Determine whether you want to create one or more program objects.
v Terminate each program in the sequence.
v Specify compiler options, with an awareness of the effect of compiler options
specified in programs within the batch job.
Chapter 14. Compiling under z/OS 275
| To create separate program objects, precede each set of objects with the NAME
compiler option. When the compiler encounters the NAME option, the first program
in the sequence and all subsequent programs until the next NAME compiler option is
| encountered are link-edited into a single program object. Then each successive
| program that is compiled with the NAME option is included in a separate program
| object.
Use the END PROGRAM marker to terminate each program in the sequence except the
last program in the batch (for which the END PROGRAM marker is optional).
Alternatively, you can precede each program in the sequence with a CBL or PROCESS
statement.
If you omit the END PROGRAM marker from a program (other than the last program
in a sequence of separate programs), the next program in the sequence will be
nested in the preceding program. An error can occur in either of the following
situations:
v A PROCESS statement is in a program that is now nested.
v A CBL statement is not coded entirely in the sequence number area (columns 1
through 6).
If a CBL statement is coded entirely in the sequence number area (columns 1
through 6), no error message is issued for the CBL statement because it is
considered a label for the source statement line.
Example: batch compilation
RELATED TASKS
Specifying compiler options in a batch compilation on page 277
RELATED REFERENCES
NAME on page 337
Example: batch compilation
The following example shows a batch compilation for three programs (PROG1,
| PROG2, and PROG3) and the creation of two program objects using one invocation of
the IGYWCL cataloged procedure.
The following steps occur:
| v PROG1 and PROG2 are link-edited together to form one program object that has the
| name PROG2. The entry point of this program object defaults to the first program
| in the program object, PROG1.
| v PROG3 is link-edited by itself into a program object that has the name PROG3.
| Because it is the only program in the program object, the entry point is also
PROG3.
//jobname JOB acctno,name,MSGLEVEL=1
//stepname EXEC IGYWCL
//COBOL.SYSIN DD *
010100 IDENTIFICATION DIVISION.
010200 PROGRAM-ID PROG1.
. . .
019000 END PROGRAM PROG1.
020100 IDENTIFICATION DIVISION.
020200 PROGRAM-ID PROG2.
. . .
029000 END PROGRAM PROG2.
CBL NAME
030100 IDENTIFICATION DIVISION.
276 Enterprise COBOL for z/OS, V5.2 Programming Guide
030200 PROGRAM-ID PROG3.
. . .
039000 END PROGRAM PROG3.
/*
//LKED.SYSLMOD DD DSN=&&GOSET (1)
/*
//P2 EXEC PGM=PROG2
//STEPLIB DD DSN=&&GOSET,DISP=(SHR,PASS) (2)
. . . (3)
/*
//P3 EXEC PGM=PROG3
//STEPLIB DD DSN=&&GOSET,DISP=(SHR,PASS) (2)
. . . (4)
/*
//
(1) The data-set name for the LKED step SYSLMOD is changed to the temporary
name &&GOSET, without any member name.
(2) The temporary data set &&GOSET is used as the STEPLIB for steps P2 and P3
to run the compiled programs. If the Language Environment library does
not reside in shared storage, you must also add the library data set as a DD
statement for STEPLIB.
(3) Other DD statements and input that are required to run PROG1 and PROG2
must be added.
(4) Other DD statements and input that are required to run PROG3 must be
added.
RELATED REFERENCES
Language Environment Programming Guide (IBM-supplied cataloged procedures)
Specifying compiler options in a batch compilation
You can specify compiler options for each program in the batch sequence either
with a CBL or PROCESS statement that precedes the program, or upon invocation of
the compiler.
If a CBL or PROCESS statement is specified in the current program, the compiler
resolves the CBL or PROCESS statements together with the options in effect before
the first program. If the current program does not contain CBL or PROCESS
statements, the compiler uses the settings of options in effect for the previous
program.
You should be aware of the effect of certain compiler options on the precedence of
compiler option settings for each program in the batch sequence. Compiler options
are recognized in the following order of precedence, from highest to lowest:
1. Installation defaults that are fixed at your site
2. Values of the BUFSIZE, OUTDD, SIZE, SQL, and SQLIMS compiler options in effect
for the first program in the batch
3. Options on CBL or PROCESS statements, if any, for the current program
4. Options specified in the compiler invocation (JCL PARM or TSO CALL)
5. Installation defaults that are not fixed
If any program in the batch sequence requires the BUF, OUTDD, SIZE, SQL or SQLIMS
option, that option must be in effect for the first program in the batch sequence.
(When processing BASIS, COPY, or REPLACE statements, the compiler handles all
programs in the batch as a single input file.)
Chapter 14. Compiling under z/OS 277
If you specify the option for the batch, you cannot change the NUMBER and SEQUENCE
options during the batch compilation. The compiler treats all programs in the batch
as a single input file during NUMBER and SEQUENCE processing under the option;
therefore, the sequence numbers of the entire input file must be in ascending order.
If the compiler diagnoses the LANGUAGE option on the CBL or PROCESS statement as
an error, the language selection reverts to what was in effect before the compiler
encountered the first CBL or PROCESS statement. The language in effect during a
batch compilation conforms to the rules of processing CBL or PROCESS statements in
that environment.
Example: precedence of options in a batch compilation
Example: LANGUAGE option in a batch compilation
Example: precedence of options in a batch compilation
The following example listing shows the precedence of compiler options for batch
compilation.
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.0 Date 03/30/2013. . .
Invocation parameters:
NOTERM
PROCESS(CBL) statements:
CBL CURRENCY,FLAG(I,I)
Options in effect: All options are installation defaults unless otherwise noted:
NOADATA
ADV
QUOTE
ARITH(COMPAT)
NOAWO
NOBLOCK0
BUFSIZE(4096)
. . .
CURRENCY Process option PROGRAM 1
. . .
FLAG(I,I) Process option PROGRAM 1
. . .
NOTERM INVOCATION option
. . .
End of compilation for program 1
. . .
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.0 Date 03/30/2013. . .
PROCESS(CBL) statements:
CBL APOST
Options in effect:
NOADATA
ADV
APOST Process option PROGRAM 2
ARITH(COMPAT)
NOAWO
NOBLOCK0
BUFSIZE(4096)
. . .
NOCURRENCY Installation default option for PROGRAM 2
. . .
FLAG(I) Installation default option
. . .
NOTERM INVOCATION option remains in effect
. . .
End of compilation for program 2
Example: LANGUAGE option in a batch compilation
The following example shows the behavior of the LANGUAGE compiler option in a
batch environment. The default installation option is ENGLISH (abbreviated EN), and
the invocation option is XX, a nonexistent language.
278 Enterprise COBOL for z/OS, V5.2 Programming Guide
CBL LANG(JP),FLAG(I,I),APOST (1)
IDENTIFICATION DIVISION. (2)
PROGRAM-ID. COMPILE1.
. . .
END PROGRAM COMPILE1.
CBL LANGUAGE(YY) (3)
CBL LANGUAGE(JP),LANG(!!) (4)
IDENTIFICATION DIVISION. (2)
PROGRAM-ID. COMPILE2.
. . .
END PROGRAM COMPILE2.
IDENTIFICATION DIVISION.
PROGRAM-ID. COMPILE3.
. . .
END PROGRAM COMPILE3.
CBL LANGUAGE(JP),LANGUAGE(YY) (5)
. . .
(1) The installation default is EN. The invocation option was XX, a nonexistent
language. EN is the language in effect.
(2) After the CBL statement is scanned, JP is the language in effect.
(3) CBL resets the language to EN. YY is ignored because it is superseded by JP.
(4) !! is not alphanumeric and is discarded.
(5) CBL resets the language to EN. YY supersedes JP but is nonexistent.
For the program COMPILE1, the default language English (EN) is in effect when the
compiler scans the invocation options. A diagnostic message is issued in
mixed-case English because XX is a nonexistent language identifier. The default EN
remains in effect when the compiler scans the CBL statement. The unrecognized
option APOST in the CBL statement is diagnosed in mixed-case English because the
CBL statement has not completed processing and EN was the last valid language
option. After the compiler processes the CBL options, the language in effect
becomes Japanese (JP).
In the program COMPILE2, the compiler diagnoses CBL statement errors in
mixed-case English because English is the language in effect before the first
program is used. If more than one LANGUAGE option is specified, only the last valid
language specified is used. In this example, the last valid language is Japanese (JP).
Therefore Japanese becomes the language in effect when the compiler finishes
processing the CBL options. If you want diagnostics in Japanese for the options in
the CBL and PROCESS statements, the language in effect before COMPILE1 must be
Japanese.
The program COMPILE3 has no CBL statement. It inherits the language in effect,
Japanese (JP), from the previous compilation.
After compiling COMPILE3, the compiler resets the language in effect to English (EN)
because of the CBL statement. The language option in the CBL statement resolves
the last-specified two-character alphanumeric language identifier, YY. Because YY is
nonexistent, the language in effect remains English.
Correcting errors in your source program
Messages about source-code errors indicate where the error occurred (LINEID). The
text of a message tells you what the problem is. With this information, you can
correct the source program.
Chapter 14. Compiling under z/OS 279
Although you should try to correct errors, it is not always necessary to correct
source code for every diagnostic message. You can leave a warning-level or
informational-level message in a program without much risk, and you might
decide that the recoding and compilation that are needed to remove the message
are not worth the effort. Severe-level and error-level errors, however, indicate
probable program failure and should be corrected.
In contrast with the four lower levels of severities, an unrecoverable (U-level) error
might not result from a mistake in your source program. It could come from a flaw
in the compiler itself or in the operating system. In such cases, the problem must
be resolved, because the compiler is forced to end early and does not produce
complete object code or a complete listing. If the message occurs for a program
that has many S-level syntax errors, correct those errors and compile the program
again. You can also resolve job set-up problems (such as missing data-set
definitions or insufficient storage for compiler processing) by making changes to
the compile job. If your compile job setup is correct and you have corrected the
S-level syntax errors, you need to contact IBM to investigate other U-level errors.
After correcting the errors in your source program, recompile the program. If this
second compilation is successful, proceed to the link-editing step. If the compiler
still finds problems, repeat the above procedure until only informational messages
are returned.
RELATED TASKS
Generating a list of compiler messages
RELATED REFERENCES
Messages and listings for compiler-detected errors
Generating a list of compiler messages
You can generate a complete listing of compiler diagnostic messages with their
message numbers, severities, and text by compiling a program that has
program-name ERRMSG.
You can code just the PROGRAM-ID paragraph, as shown below, and omit the rest of
the program.
Identification Division.
Program-ID. ErrMsg.
RELATED TASKS
Customizing compiler-message severities on page 710
RELATED REFERENCES
Messages and listings for compiler-detected errors
Format of compiler diagnostic messages on page 281
Messages and listings for compiler-detected errors
As the compiler processes your source program, it checks for COBOL language
errors, and issues diagnostic messages. These messages are collated in the compiler
listing (subject to the FLAG option).
Each message in the listing provides information about the nature of the problem,
its severity, and the compiler phase that detected it. Wherever possible, the
message provides specific instructions for correcting an error.
280 Enterprise COBOL for z/OS, V5.2 Programming Guide
The messages for errors found during processing of compiler options, CBL and
PROCESS statements, and BASIS, COPY, or REPLACE statements are displayed near the
top of the listing.
The messages for compilation errors (ordered by line number) are displayed near
the end of the listing for each program.
A summary of all problems found during compilation is displayed near the bottom
of the listing.
RELATED TASKS
Correcting errors in your source program on page 279
Generating a list of compiler messages on page 280
RELATED REFERENCES
Format of compiler diagnostic messages
Severity codes for compiler diagnostic messages on page 282
FLAG on page 327
Format of compiler diagnostic messages
Each message issued by the compiler has a source line number, a message
identifier, and message text.
Each message has the following form:
nnnnnn IGYppxxxx-l message-text
nnnnnn
The number of the source statement of the last line that the compiler was
processing. Source statement numbers are listed on the source printout of
your program. If you specified the NUMBER option at compile time, the
numbers are the original source program numbers. If you specified
NONUMBER, the numbers are those generated by the compiler.
IGY A prefix that identifies that the message was issued by the COBOL
compiler.
pp Two characters that identify which phase or subphase of the compiler
detected the condition that resulted in a message. As an application
programmer, you can ignore this information. If you are diagnosing a
suspected compiler error, contact IBM for support.
xxxx A four-digit number that identifies the message.
l A character that indicates the severity level of the message: I, W, E, S, or U.
message-text
The message text; for an error message, a short explanation of the
condition that caused the error.
Tip: If you used the FLAG option to suppress messages, there might be additional
errors in your program.
RELATED REFERENCES
Severity codes for compiler diagnostic messages on page 282
FLAG on page 327
Chapter 14. Compiling under z/OS 281
Severity codes for compiler diagnostic messages
Conditions that the compiler can detect fall into five levels or categories of severity.
Table 38. Severity codes for compiler diagnostic messages
Level or category Return
of message code Purpose
Informational (I) 0 To inform you. No action is required, and the program
runs correctly.
Warning (W) 4 To indicate a possible error. The program probably runs
correctly as written.
Error (E) 8 To indicate a condition that is definitely an error. The
compiler attempted to correct the error, but the results of
program execution might not be what you expect. You
should correct the error.
Severe (S) 12 To indicate a condition that is a serious error. The
compiler was unable to correct the error. The program
does not run correctly, and execution should not be
attempted. Object code might not be created.
Unrecoverable (U) 16 To indicate an error condition of such magnitude that the
compilation was terminated.
The final return code at the end of compilation is generally the highest return code
that occurred for any message during the compilation.
You can suppress compiler diagnostic messages or change their severities, however,
which can have an effect upon the final compilation return code. For details, see
the related information.
RELATED TASKS
Customizing compiler-message severities on page 710
RELATED REFERENCES
Processing of MSGEXIT on page 709
282 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 15. Compiling under z/OS UNIX
Compile Enterprise COBOL programs under z/OS UNIX by using the cob2
command. Under z/OS UNIX, you can compile any COBOL program that you can
compile under z/OS. The object code generated by the COBOL compiler can run
under z/OS.
As part of the compilation step, you define the files needed for the compilation,
and specify any compiler options or compiler-directing statements that are
necessary for your program and for the output that you want.
The main job of the compiler is to translate COBOL programs into language that
the computer can process (object code). The compiler also lists errors in source
statements and provides supplementary information to help you debug and tune
programs.
RELATED TASKS
Setting environment variables under z/OS UNIX
Specifying compiler options under z/OS UNIX on page 284
Compiling and linking with the cob2 command on page 285
Compiling using scripts on page 290
Compiling, linking, and running OO applications under z/OS UNIX on page 291
RELATED REFERENCES
Data sets used by the compiler under z/OS on page 267
Compiler options and compiler output under z/OS on page 274
Setting environment variables under z/OS UNIX
An environment variable is a name that is associated with a string of characters and
that defines some variable aspect of the program environment. You use
environment variables to set values that programs, including the compiler, need.
Set the environment variables for the compiler by using the export command. For
example, to set the SYSLIB variable, issue the export command from the shell or
from a script file:
export SYSLIB=/u/mystuff/copybooks
The value that you assign to an environment variable can include other
environment variables or the variable itself. The values of these variables apply
only when you compile from the shell where you issue the export command. If
you do not set an environment variable, either a default value is applied or the
variable is not defined. The environment-variable names must be uppercase.
The environment variables that you can set for use by the compiler are as follows:
COBOPT
Specify compiler options separated by blanks or commas. Separate
suboptions with commas. Blanks at the beginning or the end of the
variable value are ignored. Delimit the list of options with quotation marks
if it contains blanks or characters that are significant to the z/OS UNIX
shell. For example:
export COBOPT="TRUNC(OPT) XREF"
Copyright IBM Corp. 1991, 2015 283
SYSLIB
Specify paths to directories to be used in searching for COBOL copybooks
if you do not specify an explicit library-name in the COPY statement.
Separate multiple paths with a colon. Paths are evaluated in order from the
first path to the last in the export command. If you set the variable with
multiple files of the same name, the first located copy of the file is used.
For COPY statements in which you have not coded an explicit library-name,
the compiler searches for copybooks in this order:
1. In the current directory
2. In the paths you specify with the -I cob2 option
3. In the paths you specify in the SYSLIB environment variable
library-name
Specify the directory path from which to copy when you specify an explicit
library-name in the COPY statement. The environment-variable name is
identical to the library-name in your program. You must set an environment
variable for each library; an error will occur otherwise. The
environment-variable name library-name must be uppercase.
text-name
Specify the name of the file from which to copy text. The
environment-variable name is identical to the text-name in your program.
The environment-variable name text-name must be uppercase.
RELATED TASKS
Specifying compiler options under z/OS UNIX
Compiling and linking with the cob2 command on page 285
Setting and accessing environment variables on page 454
RELATED REFERENCES
Chapter 18, Compiler-directing statements, on page 373
Chapter 17, Compiler options, on page 301
COPY statement (Enterprise COBOL Language Reference)
Specifying compiler options under z/OS UNIX
The compiler is installed and set up with default compiler options. While installing
the compiler, a system programmer can fix compiler option settings to ensure
better performance or maintain certain standards. You cannot override any
compiler options that your site has fixed.
For options that are not fixed, you can override the default settings by specifying
compiler options in any of three ways:
v Code them on the PROCESS or CBL statement in your COBOL source.
v Specify the -q option of the cob2 command.
v Set the COBOPT environment variable.
The compiler recognizes the options in the above order of precedence, from highest
to lowest. The order of precedence also determines which options are in effect
when conflicting or mutually exclusive options are specified. When you compile
using the cob2 command, compiler options are recognized in the following order
of precedence, from highest to lowest:
1. Installation defaults fixed as nonoverridable
284 Enterprise COBOL for z/OS, V5.2 Programming Guide
2. The values of BUFSIZE, SQL, SQLIMS, and OUTDD options in effect for the first
program in a batch compilation
3. The values that you specify on PROCESS or CBL statements in COBOL source
programs
4. The values that you specify in the cob2 command's -q option string
5. The values that you specify in the COBOPT environment variable
6. Installation defaults that are not fixed
Restrictions:
v Do not use the SQL compiler option under z/OS UNIX.
Neither the separate SQL precompiler nor the integrated SQL coprocessor runs
under z/OS UNIX.
v Do not use the SQLIMS compiler option under z/OS UNIX.
v The OPTFILE option is ignored when you compile using the cob2 command
under z/OS UNIX.
You can use the COBOPT environment variable, which provides a capability that
is comparable to OPTFILE, instead.
RELATED TASKS
Specifying compiler options in the PROCESS (CBL) statement on page 273
Setting environment variables under z/OS UNIX on page 283
Compiling and linking with the cob2 command
RELATED REFERENCES
Conflicting compiler options on page 304
Chapter 17, Compiler options, on page 301
Compiling and linking with the cob2 command
Use the cob2 command to compile and link COBOL programs from the z/OS
UNIX shell. You can specify the options and input file-names in any order, using
spaces to separate options and names. Any options that you specify apply to all
files on the command line.
To compile multiple files (batch compilation), specify multiple source-file names.
When you compile COBOL programs for z/OS UNIX, the RENT option is required.
The cob2 command automatically includes the COBOL compiler options RENT and
TERM.
The cob2 command invokes the COBOL compiler that is found through the
standard MVS search order. If the COBOL compiler is not installed in the LNKLST,
or if more than one level of IBM COBOL compiler is installed on your system, you
can specify in the STEPLIB environment variable the compiler PDS that you want
to use. For example, the following statement specifies IGY.V5R1M0 as the compiler
PDS:
export STEPLIB=IGY.V5R1M0.SIGYCOMP
The cob2 command implicitly uses the z/OS UNIX shell command c89 for the link
step. c89 is the shell interface to the linker (the z/OS program management
binder).
The default location for compiler input and output is the current directory.
Chapter 15. Compiling under z/OS UNIX 285
Only files with the suffix .cbl are passed to the compiler; cob2 passes all other files
to the linker.
The listing output that you request from the compilation of a COBOL source
program file.cbl is written to file.lst. The listing output that you request from the
linker is written to stdout.
The linker causes execution to begin at the first main program.
RELATED TASKS
Creating a DLL under z/OS UNIX
Preparing OO applications under z/OS UNIX on page 292
UNIX System Services User's Guide
RELATED REFERENCES
cob2 syntax and options on page 287
cob2 input and output files on page 288
UNIX System Services Command Reference
Creating a DLL under z/OS UNIX
To create a DLL from the z/OS UNIX shell, you must specify the cob2 option
-bdll.
cob2 -o mydll -bdll mysub.cbl
When you specify cob2 -bdll:
v The COBOL compiler uses the compiler options DLL, EXPORTALL, and RENT, which
are required for DLLs.
v The link step produces a DLL definition side file that contains IMPORT control
statements for each of the names exported by the DLL.
The name of the DLL definition side file is based on the output file-name. If the
output name has a suffix, that suffix is replaced with x to form the side-file name.
For example, if the output file-name is foo.dll, the side-file name is foo.x.
To use the DLL definition side file later when you create a module that calls that
DLL, specify the side file with any other object files (file.o) that you need to link.
For example, the following command compiles myappl.cbl, uses the DLL option to
enable myappl.o to reference DLLs, and links to produce the module myappl:
cob2 -o myappl -qdll myappl.cbl mydll.x
Example: using cob2 to compile and link under z/OS UNIX
RELATED TASKS
Chapter 26, Creating a DLL or a DLL application, on page 497
Compiling programs to create DLLs on page 498
RELATED REFERENCES
cob2 syntax and options on page 287
cob2 input and output files on page 288
Example: using cob2 to compile and link under z/OS UNIX
The following examples illustrate the use of cob2.
v To compile one file called alpha.cbl, enter:
cob2 -c alpha.cbl
286 Enterprise COBOL for z/OS, V5.2 Programming Guide
The compiled file is named alpha.o.
v To compile two files called alpha.cbl and beta.cbl, enter:
cob2 -c alpha.cbl beta.cbl
The compiled files are named alpha.o and beta.o.
v To link two files, compile them without the -c option. For example, to compile
and link alpha.cbl and beta.cbl and generate gamma, enter:
cob2 alpha.cbl beta.cbl -o gamma
This command creates alpha.o and beta.o, then links alpha.o, beta.o, and the
COBOL libraries. If the link step is successful, it produces an executable program
named gamma.
v To compile alpha.cbl with the LIST and NODATA options, enter:
cob2 -qlist,noadata alpha.cbl
cob2 syntax and options
You can use the options listed below with the cob2 command. (Do not capitalize
cob2.)
cob2 command syntax
cob2 filenames
options
-bxxx Passes the string xxx to the linker as parameters. xxx is a list of linker
options in name=value format, separated by commas. You must spell out
both the name and the value in full (except for the special cases noted
below). The name and value are case insensitive. Do not use any spaces
between -b and xxx.
If you do not specify a value for an option, a default value of YES is used
except for the following options, which have the indicated default values:
v LIST=NOIMPORT
v ALIASES=ALL
v COMPAT=CURRENT
v DYNAM=DLL
One special value for xxx is dll, which specifies that the executable
module is to be a DLL. This string is not passed to the linker.
-c Compiles programs but does not link them.
-comprc_ok=n
Controls cob2 behavior on the return code from the compiler. If the return
code is less than or equal to n, cob2 continues to the link step or, in the
compile-only case, exits with a zero return code. If the return code
returned by the compiler is greater than n, cob2 exits with the same return
code. When the c89 command is implicitly invoked by cob2 for the link
step, the exit value from the c89 command is used as the return code from
the cob2 command.
The default is -comprc_ok=4.
-e xxx Specifies the name of a program to be used as the entry point of the
Chapter 15. Compiling under z/OS UNIX 287
module. If you do not specify -e, the default entry point is the first
program (file.cbl) or object file (file.o) that you specify as a file name on the
cob2 command invocation.
-g Prepares the program for debugging. Equivalent to specifying the TEST
option with no suboptions.
-Ixxx Adds a path xxx to the directories to be searched for copybooks for which
you do not specify a library-name.
To specify multiple paths, either use multiple -I options, or use a colon to
separate multiple path names within a single -I option value.
For COPY statements in which you have not coded an explicit library-name,
the compiler searches for copybooks in the following order:
1. In the current directory
2. In the paths you specify with the -I cob2 option
3. In the paths you specify in the SYSLIB environment variable
-L xxx Specifies the directory paths to be used to search for archive libraries
specified by the -l operand.
-l xxx Specifies the name of an archive library for the linker. The cob2 command
searches for the name libxxx.a in the directories specified in the -L option,
then in the usual search order. (This option is lowercase l, not uppercase I.)
-o xxx Names the object module xxx. If the -o option is not used, the name of the
object module is a.out.
-qxxx Passes xxx to the compiler, where xxx is a list of compiler options
separated by blanks or commas.
Enclose xxx in quotation marks if a parenthesis is part of the option or
suboption, or if you use blanks to separate options. Do not insert spaces
between -q and xxx.
-v Displays the generated commands that are issued by cob2 for the compile
and link steps, including the options being passed, and executes them.
Here is sample output:
cob2 -v -o mini -qssrange mini.cbl
compiler: ATTCRCTL PARM=RENT,TERM,SSRANGE /u/userid/cobol/mini.cbl
PP 5655-W32 IBM Enterprise COBOL for z/OS 5.1.0 in progress ...
End of compilation 1, program mini, no statements flagged.
linker: /bin/c89 -o mini -e // mini.o
-# Displays compile and link steps, but does not execute them.
RELATED TASKS
Compiling and linking with the cob2 command on page 285
Creating a DLL under z/OS UNIX on page 286
Setting environment variables under z/OS UNIX on page 283
cob2 input and output files
You can specify the following files as input file-names when you use the cob2
command.
Table 39. Input files to the cob2 command
File name Description Comments
file.cbl COBOL source file to be compiled Will not be linked if you specify the
and linked cob2 option -c
288 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 39. Input files to the cob2 command (continued)
File name Description Comments
file.a Archive file Produced by the ar command, to be
used during the link-edit phase
file.o Object file to be link-edited Can be produced by the COBOL
compiler, the C/C++ compiler, or the
assembler
file.x DLL definition side file Used during the link-edit phase of an
application that references the dynamic
link library (DLL)
If you use the cob2 command, the following files are created in the current
directory.
Table 40. Output files from the cob2 command
File name Description Comments
file Executable module or DLL Created by the linker if you specify the
cob2 option -o file
a.out Executable module or DLL Created by the linker if you do not
specify the cob2 option -o
file.adt Associated data (ADATA) file Created by the compiler if you specify
corresponding to input COBOL compiler option ADATA
source program file.cbl
file.dbg Symbolic information tables for Created by the compiler if you specify
Debug Tool corresponding to input compiler option TEST(. . .,SEP,. . .)
COBOL source program file.cbl
file.dek Extended COBOL source output Created by the compiler if you specify
from library processing compiler option MDECK
file.lst Listing file corresponding to input Created by the compiler
COBOL source program file.cbl
file.o Object file corresponding to input Created by the compiler
COBOL source program file.cbl
file.x DLL definition side file Created during the cob2 linking phase
when creating file.dll
class.java Java class definition (source) Created when you compile a class
definition
RELATED TASKS
Compiling and linking with the cob2 command on page 285
RELATED REFERENCES
ADATA on page 305
MDECK on page 336
TEST on page 359
UNIX System Services Command Reference
Chapter 15. Compiling under z/OS UNIX 289
Compiling using scripts
If you use a shell script to automate cob2 tasks, you must code option syntax
carefully to prevent the shell from passing invalid strings to cob2.
Code option strings in scripts as follows:
v Use an equal sign and colon rather than a left and right parenthesis, respectively,
| to specify compiler suboptions. For example, code -qOPTIMIZE=1:,XREF instead
| of -qOPTIMIZE(1),XREF.
v Use an underscore rather than a single quotation mark where a compiler option
requires single quotation marks for delimiting a suboption.
v Do not use blanks in the option string.
290 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 16. Compiling, linking, and running OO applications
It is recommended that you compile, link, and run object-oriented (OO)
applications in the z/OS UNIX environment. However, with certain limitations
explained in the related tasks, it is possible to compile, link, and run OO COBOL
applications by using standard batch JCL or TSO/E commands.
RELATED TASKS
Compiling, linking, and running OO applications under z/OS UNIX
Compiling, linking, and running OO applications in JCL or TSO/E on page 295
Using Java SDKs for z/OS on page 299
Compiling, linking, and running OO applications under z/OS UNIX
When you compile, link, and run object-oriented applications in a z/OS UNIX
environment, application components reside in the z/OS UNIX file system. You
compile and link them by using shell commands, and run them at a shell
command prompt or with the BPXBATCH utility from JCL or TSO/E.
RELATED TASKS
Compiling OO applications under z/OS UNIX
Preparing OO applications under z/OS UNIX on page 292
Running OO applications under z/OS UNIX on page 293
Compiling OO applications under z/OS UNIX
When you compile OO applications in a z/OS UNIX shell, use the cob2 command
to compile COBOL client programs and class definitions, and the javac command
to compile Java class definitions to produce bytecode (suffix .class).
To compile COBOL source code that contains OO syntax such as INVOKE statements
or class definitions, or that uses Java services, you must use these compiler
options: RENT, DLL, THREAD, and DBCS. (The RENT and DBCS options are defaults.)
A COBOL source file that contains a class definition must not contain any other
class or program definitions.
When you compile a COBOL class definition, two output files are generated:
v The object file (.o) for the class definition.
v A Java source program (.java) that contains a class definition that corresponds to
the COBOL class definition. Do not edit this generated Java class definition in
any way. If you change the COBOL class definition, you must regenerate both
the object file and the Java class definition by recompiling the updated COBOL
class definition.
If a COBOL client program or class definition includes the file JNI.cpy by using a
COPY statement, specify the include subdirectory of the COBOL install directory
(typically /usr/lpp/cobol/include) in the search order for copybooks. You can
specify the include subdirectory by using the -I option of the cob2 command or
by setting the SYSLIB environment variable.
RELATED TASKS
Chapter 15, Compiling under z/OS UNIX, on page 283
Copyright IBM Corp. 1991, 2015 291
Preparing OO applications under z/OS UNIX
Running OO applications under z/OS UNIX on page 293
Setting and accessing environment variables on page 454
Accessing JNI services on page 623
RELATED REFERENCES
cob2 syntax and options on page 287
DBCS on page 318
DLL on page 321
RENT on page 348
THREAD on page 362
Preparing OO applications under z/OS UNIX
Use the cob2 command to link OO COBOL applications.
To prepare an OO COBOL client program for execution, link the object file with
the following two DLL side files to create an executable module:
v libjvm.x, which is provided with your IBM Java Software Development Kit.
v igzcjava.x, which is provided in the lib subdirectory of the cobol directory in
the z/OS UNIX file system. The typical complete path is /usr/lpp/cobol/lib/
igzcjava.x. This DLL side file is also available as the member IGZCJAVA in the
SCEELIB PDS (part of Language Environment).
To prepare a COBOL class definition for execution:
1. Link the object file using the two DLL side files mentioned above to create an
executable DLL module.
You must name the resulting DLL module libClassname.so, where Classname is
the external class-name. If the class is part of a package and thus there are
periods in the external class-name, you must change the periods to underscores
in the DLL module name. For example, if class Account is part of the com.acme
package, the external class-name (as defined in the REPOSITORY paragraph entry
for the class) must be com.acme.Account, and the DLL module for the class
must be libcom_acme_Account.so.
2. Compile the generated Java source with the Java compiler to create a class file
(.class).
For a COBOL source file Classname.cbl that contains the class definition for
Classname, you would use the following commands to compile and link the
components of the application:
Table 41. Commands for compiling and linking a class definition
Command Input Output
cob2 -c -qdll,thread Classname.cbl Classname.cbl Classname.o,
Classname.java
cob2 -bdll -o libClassname.so Classname.o Classname.o libClassname.so
/usr/lpp/java/J5.0/bin/j9vm/libjvm.x
/usr/lpp/cobol/lib/igzcjava.x
javac Classname.java Classname.java Classname.class
After you issue the cob2 and javac commands successfully, you have the
executable components for the program: the executable DLL module
libClassname.so and the class file Classname.class. All files from these commands
are generated in the current working directory.
292 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: compiling and linking a COBOL class definition under z/OS UNIX
RELATED TASKS
Chapter 15, Compiling under z/OS UNIX, on page 283
REPOSITORY paragraph for defining a class on page 584
RELATED REFERENCES
cob2 syntax and options on page 287
| Object-oriented syntax, and Java 6, Java 7, or Java 8 on page 300
Example: compiling and linking a COBOL class definition
under z/OS UNIX
This example illustrates the commands that you use and the files that are produced
when you compile and link a COBOL class definition, Manager.cbl, using z/OS
UNIX shell commands.
Manager.cbl
Identification division.
Class-id Manager inherits Employee.
Environment division.
Configuration section.
Repository.
Class Manager is "Manager"
...
End class Manager.
cob2 -c -qdll,thread Manager.cbl
Manager.java Manager.o
javac Manager.java cob2 -bdll -o libManager.so Manager.o
/usr/lpp/java/J5.0/bin/j9vm/libjvm.x
/usr/lpp/cobol/lib/igzcjava.x
Manager.class libManager.so
The class file Manager.class and the DLL module libManager.so are the executable
components of the application, and are generated in the current working directory.
Running OO applications under z/OS UNIX
It is recommended that you run object-oriented COBOL applications as z/OS
UNIX applications. You must do so if an application begins with a Java program or
the main factory method of a COBOL class.
Specify the directory that contains the DLLs for the COBOL classes in the LIBPATH
environment variable. Specify the directory paths for the Java class files that are
associated with the COBOL classes in the CLASSPATH environment variable as
follows:
v For classes that are not part of a package, end the class path with the directory
that contains the .class files.
Chapter 16. Compiling, linking, and running OO applications 293
v For classes that are part of a package, end the class path with the directory that
contains the "root" package (the first package in the full package name).
v For a .jar file that contains .class files, end the class path with the name of the
.jar file.
Separate multiple path entries with colons.
RELATED TASKS
Running OO applications that start with a main method
Running OO applications that start with a COBOL program
Running J2EE COBOL clients on page 295
Chapter 23, Running COBOL programs under z/OS UNIX, on page 453
Setting and accessing environment variables on page 454
Chapter 30, Writing object-oriented programs, on page 579
Structuring OO applications on page 620
Running OO applications that start with a main method
If the first routine of a mixed COBOL and Java application is the main method of a
Java class or the main factory method of a COBOL class, run the application by
using the java command and by specifying the name of the class that contains the
main method.
The java command initializes the Java virtual machine (JVM). To customize the
initialization of the JVM, specify options on the java command as in the following
examples:
Table 42. java command options for customizing the JVM
Purpose Option
To set a system property -Dname=value
To request that the JVM generate verbose messages about -verbose:gc
garbage collection
To request that the JVM generate verbose messages about class -verbose:class
loading
To request that the JVM generate verbose messages about -verbose:jni
native methods and other Java Native Interface activity
To set the initial Java heap size to value bytes -Xmsvalue
To set the maximum Java heap size to value bytes -Xmxvalue
For details about the options that the JVM supports, see the output from the java
-h command, or see the related references.
RELATED REFERENCES
IBM SDK for Java - Tools Documentation
WebSphere for z/OS: Applications (Java Naming and Directory Interface (JNDI))
Running OO applications that start with a COBOL program
If the first routine of a mixed COBOL and Java application is a COBOL program,
run the application by specifying the program name at the command prompt. If a
JVM is not already running in the process of the COBOL program, the COBOL run
time automatically initializes a JVM.
294 Enterprise COBOL for z/OS, V5.2 Programming Guide
To customize the initialization of the JVM, specify options by setting the
COBJVMINITOPTIONS environment variable. Use blanks to separate options. For
example:
export COBJVMINITOPTIONS="-Xms10000000 -Xmx20000000 -verbose:gc"
RELATED TASKS
Using Java SDKs for z/OS on page 299
Chapter 23, Running COBOL programs under z/OS UNIX, on page 453
Setting and accessing environment variables on page 454
RELATED REFERENCES
IBM SDK for Java - Tools Documentation
WebSphere for z/OS: Applications (Java Naming and Directory Interface (JNDI))
Running J2EE COBOL clients:
You can use OO syntax in a COBOL program to implement a Java 2 Platform,
Enterprise Edition (J2EE) client. You can, for example, invoke methods on
enterprise beans that run in the WebSphere for z/OS environment.
Before you run a COBOL J2EE client, you must set the Java system property
java.naming.factory.initial to access WebSphere naming services. For example:
export COBJVMINITOPTIONS
="-Djava.naming.factory.initial=com.ibm.websphere.naming.WsnInitialContextFactory"
Example: J2EE client written in COBOL on page 634
Compiling, linking, and running OO applications in JCL or TSO/E
It is recommended that you compile, link, and run applications that use OO syntax
in the z/OS UNIX environment.
However, in limited circumstances it is possible to compile, prepare, and run OO
applications by using standard batch JCL or TSO/E commands. To do so, you
must follow the guidelines that are in the related tasks. For example, you might
follow this approach for applications that consist of a COBOL main program and
subprograms that:
v Access objects that are all implemented in Java
v Access enterprise beans that run in a WebSphere server
RELATED TASKS
Compiling OO applications in JCL or TSO/E
Preparing and running OO applications in JCL or TSO/E on page 296
Compiling, linking, and running OO applications under z/OS UNIX on page 291
Compiling OO applications in JCL or TSO/E
If you use batch JCL or TSO/E to compile an OO COBOL program or class
definition, the generated object file is written, as usual, to the data set that has
ddname SYSLIN or SYSPUNCH. You must use compiler options RENT, DLL, THREAD, and
DBCS. (RENT and DBCS are defaults.)
If the COBOL program or class definition uses the JNI environment structure to
access JNI callable services, copy the file JNI.cpy from the z/OS UNIX file system
to a PDS or PDSE member called JNI, identify that library with a SYSLIB DD
statement, and use a COPY statement of the form COPY JNI in the COBOL source.
Chapter 16. Compiling, linking, and running OO applications 295
A COBOL source file that contains a class definition must not contain any other
class or program definitions.
When you compile a COBOL class definition, a Java source program that contains
a class definition that corresponds to the COBOL class definition is generated in
addition to the object file. Use the SYSJAVA ddname to write the generated Java
source file to a file in the z/OS UNIX file system. For example:
//SYSJAVA DD PATH=/u/userid/java/Classname.java,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU,
// FILEDATA=TEXT
Do not edit this generated Java class definition in any way. If you change the
COBOL class definition, you must regenerate both the object file and the Java class
definition by recompiling the updated COBOL class definition.
Compile Java class definitions by using the javac command from a z/OS UNIX
shell command prompt, or by using the BPXBATCH utility.
Example: compiling, linking, and running an OO application using JCL on page
298
RELATED TASKS
Compiling with JCL on page 255
Compiling under TSO on page 262
Specifying source libraries (SYSLIB) on page 270
Defining the Java-source output file (SYSJAVA) on page 272
Accessing JNI services on page 623
Compiling OO applications under z/OS UNIX on page 291
Preparing OO applications under z/OS UNIX on page 292
RELATED REFERENCES
DBCS on page 318
DLL on page 321
RENT on page 348
THREAD on page 362
Appendix E, JNI.cpy copybook, on page 721
UNIX System Services User's Guide (The BPXBATCH utility)
Preparing and running OO applications in JCL or TSO/E
It is recommended that you run OO applications in a z/OS UNIX environment. To
run OO applications from batch JCL or TSO/E, you should therefore use the
BPXBATCH utility.
In limited circumstances, however, you can run an OO application by using
standard batch JCL (EXEC PGM=COBPROG) or the TSO/E CALL command. To do so,
follow these requirements when preparing the application:
v Structure the application to start with a COBOL program. (If an application
starts with a Java program or with the main factory method of a COBOL class,
you must run the application under z/OS UNIX, and the application
components must reside in the z/OS UNIX file system.)
| v Link-edit considerations: Link the program object for the COBOL program into
a PDSE. COBOL programs that contain object-oriented syntax must be
link-edited with AMODE 31.
296 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Ensure that the class files and DLLs associated with the COBOL or Java classes
that are used by the application reside in the z/OS UNIX file system. You must
name the class files and DLLs as described in the related task about preparing
OO applications.
v Specify INCLUDE control statements for the DLL side files libjvm.x and
igzcjava.x when you bind the object deck for the main program. For example:
INCLUDE /usr/lpp/java/J5.0/bin/j9vm/libjvm.x
INCLUDE /usr/lpp/cobol/lib/igzcjava.x
v Create a file that contains the environment variable settings that are required for
Java. For example, a file /u/userid/javaenv might contain the three lines shown
below to set the PATH, LIBPATH, and CLASSPATH environment variables.
| PATH=/bin:/usr/lpp/java/IBM/J7.1/bin
| LIBPATH=/lib:/usr/lib:/usr/lpp/java/J5.0/bin:/usr/lpp/java/IBM/J7.1/bin/j9vm
| CLASSPATH=.:/u/userid/applications
To customize the initialization of the JVM that will be used by the application,
you can set the COBJVMINITOPTIONS environment variable in the same file.
For example, to access enterprise beans that run in a WebSphere server, you
must set the Java system property java.naming.factory.initial. For details, see the
related task about running OO applications.
When you run an OO application that starts with a COBOL program by using
standard batch JCL or the TSO/E CALL command, follow these guidelines:
v Use the _CEE_ENVFILE environment variable to indicate the location of the file
that contains the environment variable settings required by Java. Set
_CEE_ENVFILE by using the ENVAR runtime option.
v Specify the POSIX(ON) and XPLINK(ON) runtime option.
v Use DD statements to specify files in the z/OS UNIX file system for the standard
input, output, and error streams for Java:
JAVAIN DD for the input from statements such as c=System.in.read();
JAVAOUT DD for the output from statements such as
System.out.println(string);
JAVAERR DD for the output from statements such as
System.err.println(string);
v Ensure that the SCEERUN2 and SCEERUN load libraries are available in the
system library search order, for example, by using a STEPLIB DD statement.
Example: compiling, linking, and running an OO application using JCL on page
298
RELATED TASKS
Preparing OO applications under z/OS UNIX on page 292
Running OO applications under z/OS UNIX on page 293
Structuring OO applications on page 620
UNIX System Services User's Guide (The BPXBATCH utility)
Language Environment Programming Guide (Running an application under batch)
RELATED REFERENCES
XL C/C++ Programming Guide (_CEE_ENVFILE)
Language Environment Programming Reference (ENVAR)
Chapter 16. Compiling, linking, and running OO applications 297
Example: compiling, linking, and running an OO application
using JCL
This example shows sample JCL that you could use to compile, link, and run a
COBOL client that invokes a Java method.
The example shows:
v JCL to compile, link, and run an OO COBOL program, TSTHELLO
v A Java class definition, HelloJ, that contains a method that the COBOL program
invokes
v A z/OS UNIX file, ENV, that contains the environment variable settings that
Java requires
JCL for program TSTHELLO
| //TSTHELLO JOB ,
| // TIME=(1),MSGLEVEL=(1,1),MSGCLASS=H,CLASS=A,REGION=200M,
| // NOTIFY=&SYSUID,USER=&SYSUID
| //*
| // SET COBPRFX=IGY.V5R1M0
| // SET LIBPRFX=CEE
| //*
| //COMPILE EXEC PGM=IGYCRCTL,
| //SYSLIN DD DSNAME=&&OBJECT(TSTHELLO),UNIT=VIO,DISP=(NEW,PASS),
| // SPACE=(CYL,(1,1,1))
| //SYSPRINT DD SYSOUT=*
| //STEPLIB DD DSN=&COBPRFX..SIGYCOMP,DISP=SHR
| // DD DSN=&LIBPRFX..SCEERUN,DISP=SHR
| // DD DSN=&LIBPRFX..SCEERUN2,DISP=SHR
| //SYSUT1 DD UNIT=VIO,SPACE=(CYL,(1,1))
| //SYSUT2 DD UNIT=VIO,SPACE=(CYL,(1,1))
| //SYSUT3 DD UNIT=VIO,SPACE=(CYL,(1,1))
| //SYSUT4 DD UNIT=VIO,SPACE=(CYL,(1,1))
| //SYSUT5 DD UNIT=VIO,SPACE=(CYL,(1,1))
| //SYSUT6 DD UNIT=VIO,SPACE=(CYL,(1,1))
| //SYSUT7 DD UNIT=VIO,SPACE=(CYL,(1,1))
| //SYSUT8 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSUT9 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSUT10 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSUT11 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSUT12 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSUT13 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSUT14 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSUT15 DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSMDECK DD UNIT=SYSALLDA,SPACE=(CYL,(1,1))
| //SYSIN DD *
| cbl dll,thread
| Identification division.
| Program-id. "TSTHELLO" recursive.
| Environment division.
| Configuration section.
| Repository.
| Class HelloJ is "HelloJ".
| Data Division.
| Procedure division.
| Display "COBOL program TSTHELLO entered"
| Invoke HelloJ "sayHello"
| Display "Returned from java sayHello to TSTHELLO"
| Goback.
| End program "TSTHELLO".
| /*
| //LKED EXEC PGM=IEWL,PARM=RENT,LIST,LET,DYNAM(DLL),CASE(MIXED)
| //SYSLIB DD DSN=&LIBPRFX..SCEELKED,DISP=SHR
| // DD DSN=&LIBPRFX..SCEELKEX,DISP=SHR
| //SYSPRINT DD SYSOUT=*
298 Enterprise COBOL for z/OS, V5.2 Programming Guide
| //SYSTERM DD SYSOUT=*
| //SYSLMOD DD DSN=&&GOSET(TSTHELLO),DISP=(MOD,PASS),UNIT=VIO,
| // SPACE=(CYL,(1,1,1)),DSNTYPE=LIBRARY
| //SYSDEFSD DD DUMMY
| //OBJMOD DD DSN=&&OBJECT,DISP=(OLD,DELETE)
| //SYSLIN DD *
| INCLUDE OBJMOD(TSTHELLO)
| INCLUDE /usr/lpp/java/J5.0/bin/j9vm/libjvm.x
| INCLUDE /usr/lpp/cobol/lib/igzcjava.x
| /*
| //GO EXEC PGM=TSTHELLO,COND=(4,LT,LKED),
| // PARM=/ENVAR("_CEE_ENVFILE=/u/userid/ootest/tsthello/ENV")
| // POSIX(ON) XPLINK(ON)
| //STEPLIB DD DSN=*.LKED.SYSLMOD,DISP=PASS
| // DD DSN=&LIBPRFX..SCEERUN2,DISP=SHR
| // DD DSN=&LIBPRFX..SCEERUN,DISP=SHR
| //SYSOUT DD SYSOUT=*
| //CEEDUMP DD SYSOUT=*
| //SYSUDUMP DD DUMMY
| //JAVAOUT DD PATH=/u/userid/ootest/tsthello/javaout,
| // PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
| // PATHMODE=(SIRUSR,SIWUSR,SIRGRP)
| //JAVAERR DD PATH=/u/userid/ootest/tsthello/javaerr,
| // PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
| // PATHMODE=(SIRUSR,SIWUSR,SIRGRP)
Definition of class HelloJ
class HelloJ {
public static void sayHello() {
System.out.println("Hello World, from Java!");
}
}
HelloJ.java is compiled with the javac command. The resulting .class file resides in
the z/OS UNIX file system directory u/userid/ootest/tsthello, which is specified
in the CLASSPATH environment variable in the environment variable settings file.
Environment variable settings file, ENV
| PATH=/bin:/usr/lpp/java/IBM/J7.1/bin.
| LIBPATH=/lib:/usr/lib:/usr/lpp/java/J5.0/bin:/usr/lpp/java/IBM/J7.1/bin/j9vm
| CLASSPATH=.:/u/userid/ootest/tsthello
The environment variable settings file also resides in directory
u/userid/ootest/tsthello, as specified in the _CEE_ENVFILE environment variable
in the JCL.
Using Java SDKs for z/OS
The Java SDKs for z/OS are based on the XPLINK linkage convention defined by
Language Environment.
If the application starts with a Java program or the main factory method of a
COBOL class, the XPLINK environment is automatically started by the java
command that starts the JVM and runs the application.
If an application starts with a COBOL program that invokes methods on COBOL
or Java classes, you must specify the XPLINK(ON) runtime option so that the
XPLINK environment is initialized. XPLINK(ON) is not recommended as a default
setting, however; you should use XPLINK(ON) only for applications that specifically
require it.
Chapter 16. Compiling, linking, and running OO applications 299
When you are running an application under z/OS UNIX, you can set the
XPLINK(ON) option by using the _CEE_RUNOPTS environment variable as follows:
_CEE_RUNOPTS="XPLINK(ON)"
Exporting _CEE_RUNOPTS="XPLINK(ON)" so that it is in effect for the entire z/OS
UNIX shell session is not recommended, however. Suppose for example that an
OO COBOL application starts with a COBOL program called App1Driver. One way
to limit the effect of the XPLINK option to the execution of the App1Driver
application is to set the _CEE_RUNOPTS variable on the command-line invocation
of App1Driver as follows:
_CEE_RUNOPTS="XPLINK(ON)" App1Driver
RELATED TASKS
Running OO applications under z/OS UNIX on page 293
Setting and accessing environment variables on page 454
RELATED REFERENCES
| Object-oriented syntax, and Java 6, Java 7, or Java 8
Runtime environment variables on page 455
Language Environment Programming Reference (XPLINK)
XL C/C++ Programming Guide (_CEE_RUNOPTS)
| Object-oriented syntax, and Java 6, Java 7, or Java 8
| Enterprise COBOL Version 5.2 applications that use object-oriented syntax for Java
| interoperability are supported with Java 6 or Java 7.
| Earlier versions of Enterprise COBOL applications that use object-oriented syntax
| for Java interoperability were supported with Java SDK 1.4.2 and Java 5. To run
| these applications with Java 6, Java 7, or Java 8, , do these steps:
| 1. Recompile and relink the applications using Enterprise COBOL V5.2.
2. Recompile the generated Java class that is associated with each object-oriented
| COBOL class using the javac command from Java 6, Java 7, or Java 8.
RELATED TASKS
Preparing OO applications under z/OS UNIX on page 292
300 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 17. Compiler options
You can direct and control your compilation by using compiler options or by using
compiler-directing statements (compiler directives).
Compiler options affect the aspects of your program that are listed in the table
below. The linked-to information for each option provides the syntax for specifying
the option and describes the option, its parameters, and its interaction with other
parameters.
Table 43. Compiler options
Aspect of your
program Compiler option Default Option abbreviations
Source language ARITH on page 309 ARITH(COMPAT) AR(C|E)
CICS on page 312 NOCICS None
CODEPAGE on page 313 CODEPAGE(1140) CP(ccsid)
CURRENCY on page 317 NOCURRENCY CURR|NOCURR
DBCS on page 318 DBCS None
NSYMBOL on page 338 NSYMBOL(NATIONAL) NS(DBCS|NAT)
NUMBER on page 339 NONUMBER NUM|NONUM
| QUALIFY on page 347 QUALIFY(COMPAT) QUA(C|E)
QUOTE/APOST on page 348 QUOTE Q|APOST
SEQUENCE on page 352 SEQUENCE SEQ|NOSEQ
SQL on page 354 NOSQL None
SQLCCSID on page 355 SQLCCSID SQLC|NOSQLC
SQLIMS on page 356 NOSQLIMS None
WORD on page 367 NOWORD WD|NOWD
| XMLPARSE on page 368 XMLPARSE(XMLSS) XP(X)|XP(C)
Date processing INTDATE on page 331 INTDATE(ANSI) None
Maps and listings LANGUAGE on page 331 LANGUAGE(ENGLISH) LANG(EN|UE|JA|JP)
LINECOUNT on page 332 LINECOUNT(60) LC
LIST on page 333 NOLIST None
MAP on page 333 NOMAP None
OFFSET on page 341 NOOFFSET OFF|NOOFF
SOURCE on page 353 SOURCE S|NOS
SPACE on page 354 SPACE(1) None
TERMINAL on page 359 NOTERMINAL TERM|NOTERM
VBREF on page 366 NOVBREF None
XREF on page 369 XREF(FULL) X|NOX
Copyright IBM Corp. 1991, 2015 301
Table 43. Compiler options (continued)
Aspect of your
program Compiler option Default Option abbreviations
Object deck COMPILE on page 316 NOCOMPILE(S) C|NOC
generation
| COPYRIGHT on page 316 NOCOPYRIGHT CPYR|NOCPYR
DECK on page 319 NODECK D|NOD
NAME on page 337 NONAME, or NAME(NOALIAS) None
if only NAME is specified
OBJECT on page 340 OBJECT OBJ|NOOBJ
PGMNAME on page 345 PGMNAME(COMPAT) PGMN(CO|LU|LM)
| SERVICE on page 353 NOSERVICE SERV|NOSERV
Object code control ADV on page 306 ADV None
AFP on page 306 AFP(VOLATILE) None
| ARCH on page 307 ARCH(7) None
AWO on page 310 NOAWO None
BLOCK0 on page 310 NOBLOCK0 None
DISPSIGN on page 320 DISPSIGN(COMPAT) DS(S|C)
DLL on page 321 NODLL None
EXPORTALL on page 326 NOEXPORTALL EXP|NOEXP
FASTSRT on page 327 NOFASTSRT FSRT|NOFSRT
MAXPCF on page 335 MAXPCF(60000) None
HGPR on page 330 HGPR(PRESERVE) None
NUMPROC on page 339 NUMPROC(NOPFD) None
OPTIMIZE on page 343 OPTIMIZE(0) OPT(n)
OUTDD on page 344 OUTDD(SYSOUT) OUT
TRUNC on page 363 TRUNC(STD) None
| VLR on page 366 VLR(STD) VLR(C|S)
| ZONEDATA on page 370 ZONEDATA(PFD) ZD(PFD)|ZD(MIG)
ZWB on page 372 ZWB None
Virtual storage BUFSIZE on page 311 4096 BUF
usage
DATA on page 318 DATA(31) None
DYNAM on page 323 NODYNAM DYN|NODYN
RENT on page 348 RENT None
RMODE on page 349 AUTO None
STGOPT on page 358 NOSTGOPT SO|NOSO
302 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 43. Compiler options (continued)
Aspect of your
program Compiler option Default Option abbreviations
Debugging and DIAGTRUNC on page 319 NODIAGTRUNC DTR|NODTR
diagnostics
DUMP on page 322 NODUMP DU|NODU
FLAG on page 327 FLAG(I,I) F|NOF
FLAGSTD on page 328 NOFLAGSTD None
| RULES on page 350 NORULES RULES(ENDP, EVENP, LXPRF,
| SLCKB)|RULES(NOENDP,
| NOEVENP, NOLXPRF, NOSLCKB)
SSRANGE on page 357 NOSSRANGE SSR|NOSSR
TEST on page 359 NOTEST None
Other ADATA on page 305 NOADATA None
EXIT on page 324 NOEXIT NOEX|EX(INX|NOINX,
LIBX|NOLIBX, PRTX|NOPRTX,
ADX|NOADX, MSGX|NOMSGX)
MDECK on page 336 NOMDECK NOMD|MD|MD(C|NOC)
OPTFILE on page 342 None None
THREAD on page 362 NOTHREAD None
Installation defaults: The default compiler options that were set up when your
compiler was installed are in effect for your program unless you override those
options. (In some installations, certain compiler options are fixed so that you
cannot override them. If you have problems with the default options, contact your
system administrator.) To determine which are the default options, run a test
compilation without specifying any compiler options. The output listing lists the
default options in effect at your site.
Nonoverridable options: In some installations, certain compiler options are fixed
so that you cannot override them. If you have problems with those options, contact
your system administrator.
Option specification: Compiler options and suboptions are not case sensitive.
Performance considerations: The AFP, ARCH, ARITH, AWO, BLOCK0, DYNAM, FASTSRT,
HGPR, MAXPCF, NUMPROC, OPTIMIZE, RENT, SQLCCSID, SSRANGE, STGOPT, TEST, THREAD, and
TRUNC compiler options can affect runtime performance.
RELATED TASKS
Chapter 14, Compiling under z/OS, on page 255
Compiling under TSO on page 262
Chapter 15, Compiling under z/OS UNIX, on page 283
Chapter 33, Tuning your program, on page 651
RELATED REFERENCES
Conflicting compiler options on page 304
Chapter 18, Compiler-directing statements, on page 373
| Option settings for 85 COBOL Standard conformance on page 304
Performance-related compiler options on page 659
Chapter 17. Compiler options 303
| Option settings for 85 COBOL Standard conformance
| Compiler options and runtime options are required for conformance with the 85
| COBOL Standard.
The following compiler options are required:
v ADV
v DYNAM
v NAME(ALIAS) or NAME(NOALIAS)
v NOBLOCK0
v NOCICS
v NODLL
v NOEXPORTALL
v NOFASTSRT
v NOTHREAD
v NOWORD
v NUMPROC(NOPFD)
v PGMNAME(COMPAT) or PGMNAME(LONGUPPER)
| v QUALIFY(COMPAT)
v QUOTE
v TRUNC(STD)
| v VLR(STANDARD)
| v ZONEDATA(PFD)
v ZWB
You can use the FLAGSTD compiler option to flag nonconforming elements such as
IBM extensions.
The following runtime options are required:
v AIXBLD
v CBLQDA(ON)
v TRAP(ON)
RELATED REFERENCES
Language Environment Programming Reference
Conflicting compiler options
The Enterprise COBOL compiler can encounter conflicting compiler options in
either of two ways: both the positive and negative form of an option are specified
at the same level in the hierarchy of precedence, or mutually exclusive options are
specified at the same level in the hierarchy.
When conflicting options are specified at the same level in the hierarchy (such as
specifying both DECK and NODECK in a PROCESS or CBL statement), the option
specified last takes effect.
If you specify mutually exclusive compiler options at the same level, the compiler
generates an error message and forces one of the options to a nonconflicting value.
For example, if you specify both OFFSET and LIST in a PROCESS statement in any
order, OFFSET takes effect and LIST is ignored.
304 Enterprise COBOL for z/OS, V5.2 Programming Guide
However, options coded at a higher level of precedence override any options
specified at a lower level of precedence. For example, if you code OFFSET in a JCL
statement but LIST in a PROCESS statement, LIST takes effect because the options
coded in the PROCESS statement and any options forced on by an option coded in
the PROCESS statement have higher precedence.
Table 44. Mutually exclusive compiler options
Specified Ignored1 Forced on1
CICS DYNAM NODYNAM
NORENT RENT
DLL DYNAM NODYNAM
NORENT RENT
EXPORTALL NODLL DLL
DYNAM NODYNAM
NORENT RENT
NORENT RMODE(ANY) RMODE(24)
NSYMBOL(NATIONAL) NODBCS DBCS
OBJECT DECK NODECK
OFFSET LIST NOLIST
PGMNAME(LM|LU) NAME NONAME
TEST NOOBJECT and NODECK OBJECT and NODECK
THREAD NORENT RENT
WORD FLAGSTD NOFLAGSTD
1. Unless in conflict with a fixed installation default option.
RELATED TASKS
Specifying compiler options under z/OS on page 272
Specifying compiler options in a batch compilation on page 277
Specifying compiler options under z/OS UNIX on page 284
RELATED REFERENCES
OPTFILE on page 342
ADATA
Use ADATA when you want the compiler to create a SYSADATA file that contains
records of additional compilation information.
ADATA option syntax
NOADATA
ADATA
Default is: NOADATA
Chapter 17. Compiler options 305
Abbreviations are: None
ADATA is required for remote compilation using an IBM Windows COBOL compiler.
On z/OS, the SYSADATA file is written to ddname SYSADATA.
The size of the SYSADATA file generally grows with the size of the associated
program.
Option specification: You cannot specify the ADATA option in a PROCESS (or CBL)
statement. You can specify it only in one of the following ways:
v In the PARM parameter of JCL
v As a cob2 command option
v As an installation default
v In the COBOPT environment variable
RELATED REFERENCES
Setting environment variables under z/OS UNIX on page 283
cob2 syntax and options on page 287
Appendix F, COBOL SYSADATA file contents, on page 727
ADV
ADV has meaning only if you use WRITE . . . ADVANCING in your source code. With
ADV in effect, the compiler adds 1 byte to the record length to account for the
printer control character.
ADV option syntax
ADV
NOADV
Default is: ADV
Abbreviations are: None
Use NOADV if you already adjusted record length to include 1 byte for the printer
control character.
AFP
The AFP option controls the compiler usage of the Additional Floating Point (AFP)
registers that are provided by z/Architecture processors.
306 Enterprise COBOL for z/OS, V5.2 Programming Guide
AFP option syntax
VOLATILE
AFP( NOVOLATILE )
Default is: AFP(VOLATILE)
Abbreviations are: None
The Enterprise COBOL compiler generates code that uses the full complement of
16 floating point registers (FPR) provided by a z/Architecture processor. These
FPRs are as follows:
v Original FPRs, which are numbered 0, 2, 4, and 6
v AFP registers, which are numbered 1, 3, 5, 7, and 8-15
Note: If your code runs on a version of CICS Transaction Server that is earlier than
V4.1, you must specify AFP(VOLATILE).
AFP(VOLATILE)
If you specify AFP(VOLATILE), the AFP registers 8-15 are considered volatile,
which means that they might be changed by a called subprogram.
Therefore, the COBOL compiler generates extra code to protect the values
in these registers.
AFP(NOVOLATILE)
If you specify AFP(NOVOLATILE), the AFP registers 8-15 are considered
nonvolatile, which means that they are known to be unchanged or
preserved by every called subprogram. Therefore, the compiler can
generate more efficient code sequences for programs with floating point
operations. It is the normal z/OS architecture convention.
ARCH
The ARCH option specifies the machine architecture for which the executable
program instructions are to be generated.
ARCH option syntax
7
ARCH( 8 )
9
10
11
| Default is: ARCH(7)
Abbreviations are: None
Chapter 17. Compiler options 307
If you specify a higher ARCH level, the compiler generates code that uses newer and
faster instructions. Your application might abend if it runs on a processor with an
architecture level lower than what you specified with the ARCH option. Use the ARCH
level that matches the lowest machine architecture where your application runs.
Current supported architecture levels and groups of models are as follows:
7 Produces code that uses instructions available on the 2096-xxx (IBM System
z9 BC) and 2094-xxx (IBM System z9 EC) models in z/Architecture mode.
Specifically, these ARCH(7) machines and their follow-ons add instructions
supported by the following facilities:
v Extended-immediate facility
v Decimal floating point facility. These instructions might be generated if
decimal data is used in numeric operations.
8 Produces code that uses instructions available on the 2097-xxx (IBM System
z10 EC) models in z/Architecture mode.
Specifically, these ARCH(8) machines and their follow-ons add instructions
supported by the general instruction extensions facility.
9 Produces code that uses instructions available on 2817-xxx (IBM
zEnterprise 196) and 2818-xxx (IBM zEnterprise 114) models in
z/Architecture mode.
Specifically, these ARCH(9) machines and their follow-ons add instructions
supported by the following facilities:
v High-word facility
v Interlocked access facility
v Load/store-on-condition facility
v Distinct-operands facility
v Population-count facility
10 Produces code that uses instructions available on the 2827-xxxx (IBM
zEnterprise EC12) models in z/Architecture mode.
Specifically, these ARCH(10) machines and their follow-ons add instructions
supported by the following facilities:
v Execution-hint facility
v Load-and-trap facility
v Miscellaneous-instructions-extension facility
v Transactional-execution facility
| v Enhanced decimal floating point facility that enables more efficient
| conversions between zoned decimal data items and decimal floating
| point data items. Instead of converting zoned decimal data items to
| packed decimal data items to perform arithmetic, the compiler converts
| zoned decimal data items directly to decimal floating point data items,
| and then back again to zoned decimal data items after the computations
| are complete.
| 11 Produces code that uses instructions available on the 2964-xxxx (IBM z13)
| models in z/Architecture mode.
| Specifically, these ARCH(11) machines and their follow-ons add instructions
| with support of the following facilities:
308 Enterprise COBOL for z/OS, V5.2 Programming Guide
| v Enhanced decimal floating point facility that enables more efficient
| conversions between packed-decimal data items and decimal floating
| point intermediate result data items
| v Exploitation of the new vector extension facility (SIMD) instructions for
| some INSPECT REPLACING and INSPECT TALLYING statements
Note: A higher ARCH level includes the facilities of the lower ARCH level. For
| example, ARCH(11) includes all the facilities of the lower ARCH levels.
For more information about these facilities, see z/Architecture Principles of Operation.
ARITH
ARITH affects the maximum number of digits that you can code for integers, and
the number of digits used in fixed-point intermediate results.
ARITH option syntax
COMPAT
ARITH( EXTEND )
Default is: ARITH(COMPAT)
Abbreviations are: AR(C|E)
When you specify ARITH(EXTEND):
v The maximum number of digit positions that you can specify in the PICTURE
clause for packed-decimal, external-decimal, and numeric-edited data items is
raised from 18 to 31.
v The maximum number of digits that you can specify in a fixed-point numeric
literal is raised from 18 to 31. You can use numeric literals with large precision
anywhere that numeric literals are currently allowed, including:
Operands of PROCEDURE DIVISION statements
VALUE clauses (for numeric data items with large-precision PICTURE)
Condition-name values (on numeric data items with large-precision PICTURE)
v The maximum number of digits that you can specify in the arguments to NUMVAL
and NUMVAL-C is raised from 18 to 31.
v The maximum value of the integer argument to the FACTORIAL function is 29.
v Intermediate results in arithmetic statements use extended mode.
When you specify ARITH(COMPAT):
v The maximum number of digit positions in the PICTURE clause for
packed-decimal, external-decimal, and numeric-edited data items is 18.
v The maximum number of digits in a fixed-point numeric literal is 18.
v The maximum number of digits in the arguments to NUMVAL and NUMVAL-C is 18.
v The maximum value of the integer argument to the FACTORIAL function is 28.
v Intermediate results in arithmetic statements use compatibility mode.
Chapter 17. Compiler options 309
RELATED CONCEPTS
Appendix A, Intermediate results and arithmetic precision, on page 675
AWO
If you specify AWO, an implicit APPLY WRITE-ONLY clause is activated for all QSAM
files in the program that have blocked variable-length records.
AWO option syntax
NOAWO
AWO
Default is: NOAWO
Abbreviations are: None
RELATED TASKS
Optimizing buffer and device space on page 10
RELATED REFERENCES
BLOCK0
APPLY WRITE-ONLY clause (Enterprise COBOL Language Reference)
BLOCK0
Use BLOCK0 to change the compiler default for QSAM files from unblocked to
blocked (as if BLOCK CONTAINS 0 were specified) and thus gain the benefit of
system-determined blocking for output files.
BLOCK0 option syntax
NOBLOCK0
BLOCK0
Default is: NOBLOCK0
Abbreviations are: None
Specifying BLOCK0 activates an implicit BLOCK CONTAINS 0 clause for each file in the
program that meets the following three criteria:
v The FILE-CONTROL paragraph either specifies ORGANIZATION SEQUENTIAL or omits
the ORGANIZATION clause.
v The FD entry does not specify RECORDING MODE U.
310 Enterprise COBOL for z/OS, V5.2 Programming Guide
v The FD entry does not specify a BLOCK CONTAINS clause.
Files for which the resulting BLOCK CONTAINS 0 clause is in effect have a blocking
factor that is determined at run time from the data definition or from the data-set
characteristics.
Interaction of the APPLY WRITE-ONLY clause and the AWO compiler option with
BLOCK0:
v If NOBLOCK0 is in effect, and the file description of a file that meets the three
criteria listed above specifies APPLY WRITE-ONLY, the compiler issues an error
message because APPLY WRITE-ONLY applies only to blocked files. But if BLOCK0 is
in effect, the result is that the file is blocked, and the APPLY WRITE-ONLY clause is
therefore accepted.
v AWO applies to any QSAM files that have blocked variable-length records. If
BLOCK0 is in effect, the result is that more files might be blocked than if NOBLOCK0
were in effect; thus AWO might apply to more files than it otherwise would.
Specifying BLOCK0 for existing programs might result in a change of behavior, and
in some cases produce undesirable results for files opened as INPUT. For example:
v The OPEN INPUT statement fails for files for which no block size can be
determined.
v Programs that continue after handling nonzero FILE STATUS codes for files
opened as INPUT might abnormally terminate when executing subsequent I/O
statements on those files.
For these reasons, after compiling with BLOCK0 you should investigate and test the
effects on your program.
For recommendations about blocking, see the related reference from the Enterprise
COBOL Migration Guide (in the information about migrating from CMPR2 to
NOCMPR2).
RELATED TASKS
Optimizing buffer and device space on page 10
Setting block sizes on page 167
RELATED REFERENCES
AWO on page 310
APPLY WRITE-ONLY clause (Enterprise COBOL Language Reference)
BLOCK CONTAINS clause (Enterprise COBOL Language Reference)
Enterprise COBOL Migration Guide
(Recommendation for DCB= parameters of JCL)
BUFSIZE
Use BUFSIZE to allocate an amount of main storage to the buffer for each compiler
work data set. Usually, a large buffer size improves the performance of the
compiler.
Chapter 17. Compiler options 311
BUFSIZE option syntax
nnnnn
BUFSIZE( nnnK )
Default is: 4096
Abbreviations are: BUF
nnnnn specifies a decimal number that must be at least 256.
nnnK specifies a decimal number in 1 KB increments, where 1 KB = 1024 bytes.
BUFSIZE cannot exceed the track capacity for the device used, nor can it exceed the
maximum allowed by data management services.
CICS
The CICS compiler option enables the integrated CICS translator and lets you
specify CICS suboptions. You must use the CICS option if your COBOL source
program contains EXEC CICS or EXEC DLI statements and the program has not been
processed by the separate CICS translator.
CICS option syntax
NOCICS
CICS
("CICS-suboption-string")
Default is: NOCICS
Abbreviations are: None
Use the CICS option only to compile CICS programs. Programs compiled with the
CICS option will not run in a non-CICS environment.
If you specify the NOCICS option, any CICS statements found in the source program
are diagnosed and discarded.
Use either quotation marks or single quotation marks to delimit the string of CICS
suboptions.
You can partition a long CICS suboption string into multiple suboption strings in
multiple CBL or PROCESS statements. The CICS suboptions are concatenated in the
order of their appearance. For example:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL=CICS("string1")
//COBOL.SYSIN DD *
312 Enterprise COBOL for z/OS, V5.2 Programming Guide
CBL CICS(string2)
CBL CICS("string3")
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
. . .
The compiler passes the following suboption string to the integrated CICS
translator:
"string1 string2 string3"
The concatenated strings are delimited with single spaces as shown. If multiple
instances of the same CICS suboption are found, the last specification of that
suboption in the concatenated string prevails. The compiler limits the size of the
concatenated suboption string to 4 KB.
RELATED CONCEPTS
Integrated CICS translator on page 425
RELATED TASKS
Compiling with the CICS option on page 423
Separating CICS suboptions on page 425
CICS Application Programming Guide (Specifying CICS translator options)
RELATED REFERENCES
Conflicting compiler options on page 304
CODEPAGE
Use CODEPAGE to specify the coded character set identifier (CCSID) for an EBCDIC
code page for processing compile-time and runtime COBOL operations that are
sensitive to character encoding.
CODEPAGE option syntax
CODEPAGE(ccsid)
Default is: CODEPAGE(1140)
Abbreviations are: CP(ccsid)
ccsid must be an integer that represents a valid CCSID for an EBCDIC code page.
The default CCSID 1140 is the equivalent of CCSID 37 (COM EUROPE EBCDIC),
but additionally includes the euro symbol.
ccsid specifies these encodings:
v The encoding for alphanumeric, national, and DBCS literals in a COBOL source
program
v The default encoding of the content of alphanumeric and DBCS data items at
run time
Chapter 17. Compiler options 313
v The encoding for DBCS user-defined words when processed by an XML GENERATE
statement to create XML element and attribute names
v The default encoding of an XML document created by an XML GENERATE
statement if the receiving data item for the document is alphanumeric
v The default encoding assumed for an XML document in an alphanumeric data
item when the document is processed by an XML PARSE statement
The CODEPAGE ccsid is used when code-page-sensitive operations are performed at
compile time or run time, and an explicit CCSID that overrides the default code
page is not specified. Such operations include:
v Conversion of literal values to Unicode
v Conversion of alphanumeric data to and from national (Unicode) data as part of
move operations, comparison, or the intrinsic functions DISPLAY-OF and
NATIONAL-OF
v Object-oriented language such as INVOKE statements or class definitions and
method definitions
v XML parsing
v XML generation
v Processing of DBCS names as part of XML generation at run time
v Processing of SQL string host variables if the SQLCCSID option is in effect
v Processing of source code for EXEC SQL statements
v Processing of source code for EXEC SQLIMS statements
However, the encoding of the following items in a COBOL source program is not
affected by the CODEPAGE compiler option:
v Data items that have USAGE NATIONAL
These items are always encoded in UTF-16 in big-endian format, CCSID 1200.
v Characters from the basic COBOL character set (see the table of these characters
in the related reference below about characters)
Though the encoding of the basic COBOL characters default currency sign ($),
quotation mark ("), and the lowercase Latin letters varies in different EBCDIC
code pages, the compiler always interprets these characters using the EBCDIC
code page 1140 encoding. In particular, the default currency sign is always the
character with value X5B (unless changed by the CURRENCY compiler option or
the CURRENCY SIGN clause in the SPECIAL-NAMES paragraph), and the quotation
mark is always the character with value X7F.
Some COBOL operations can override the CODEPAGE ccsid by using an explicit
encoding specification, for example:
v DISPLAY-OF and NATIONAL-OF intrinsic functions that specify a code page as the
second argument
v XML PARSE statements that specify the WITH ENCODING phrase
v XML GENERATE statements that specify the WITH ENCODING phrase
Additionally, you can use the CURRENCY compiler option or the CURRENCY SIGN
clause in the SPECIAL-NAMES paragraph to override:
v The default currency symbol used in the PICTURE character-strings for
numeric-edited data items in your source program
v The currency sign value used in the content of numeric-edited data items at run
time
314 Enterprise COBOL for z/OS, V5.2 Programming Guide
DBCS code pages:
Compile your COBOL program using the CODEPAGE option with the ccsid set to one
of the EBCDIC multibyte character set (MBCS) CCSIDs shown in the table below if
the program contains any of the following items:
v User-defined words formed with DBCS characters
v DBCS (USAGE DISPLAY-1) data items
v DBCS literals
All of the CCSIDs in the table below identify mixed code pages that refer to a
combination of SBCS and DBCS coded character sets. These are also the CCSIDs
that are supported for mixed data by DB2.
Table 45. EBCDIC multibyte coded character set identifiers
SBCS CCSID DBCS CCSID
National language MBCS CCSID component component
Japanese (Katakana-Kanji) 930 290 300
Japanese (Katakana-Kanji with euro) 1390 8482 16684
Japanese (Katakana-Kanji) 5026 290 4396
Japanese (Latin-Kanji) 939 1027 300
Japanese (Latin-Kanji with euro) 1399 5123 16684
Japanese (Latin-Kanji) 5035 1027 4396
Korean 933 833 834
Korean 1364 13121 4930
Simplified Chinese 935 836 837
Simplified Chinese 1388 13124 4933
Traditional Chinese 937 28709 835
Note: If you specify the TEST option, you must set the CODEPAGE option to the
CCSID that is used for the COBOL source program. In particular, programs that
use Japanese characters in DBCS literals or DBCS user-defined words must be
compiled with the CODEPAGE option set to a Japanese codepage CCSID.
RELATED CONCEPTS
COBOL and DB2 CCSID determination on page 437
RELATED TASKS
Using currency signs on page 65
Chapter 28, Processing XML input, on page 517
Chapter 29, Producing XML output, on page 561
RELATED REFERENCES
CURRENCY on page 317
SQLCCSID on page 355
TEST on page 359
The encoding of XML documents on page 536
Characters (Enterprise COBOL Language Reference)
Chapter 17. Compiler options 315
COMPILE
Use the COMPILE option only if you want to force full compilation even in the
presence of serious errors. All diagnostics and object code will be generated. Do
not try to run the object code if the compilation resulted in serious errors: the
results could be unpredictable or an abnormal termination could occur.
COMPILE option syntax
S
NOCOMPILE( E )
W
COMPILE
NOCOMPILE
Default is: NOCOMPILE(S)
Abbreviations are: C|NOC
Use NOCOMPILE without any suboption to request a syntax check (only diagnostics
produced, no object code). If you use NOCOMPILE without any suboption, several
compiler options will have no effect because no object code will be produced, for
example: DECK, LIST, OBJECT, OFFSET, OPTIMIZE, SSRANGE, and TEST.
Use NOCOMPILE with suboption W, E, or S for conditional full compilation. Full
compilation (diagnosis and object code) will stop when the compiler finds an error
of the level you specify (or higher), and only syntax checking will continue.
RELATED TASKS
Finding coding errors on page 382
RELATED REFERENCES
Messages and listings for compiler-detected errors on page 280
| COPYRIGHT
| Use COPYRIGHT to place a string in the object module if the object module is
| generated. If the object is linked into a program object, the string is loaded into
| memory with that program object.
| COPYRIGHT option syntax
| NOCOPYRIGHT
COPYRIGHT('copyright string')
|
||
316 Enterprise COBOL for z/OS, V5.2 Programming Guide
| Default is: NOCOPYRIGHT
| Abbreviations are: CPYR|NOCPYR
| The copyright string is limited to 64 characters in length.
CURRENCY
You can use the CURRENCY option to provide an alternate default currency symbol
to be used for a COBOL program. (The default currency symbol is the dollar sign
($).)
CURRENCY option syntax
NOCURRENCY
CURRENCY(literal)
Default is: NOCURRENCY
Abbreviations are: CURR|NOCURR
NOCURRENCY specifies that no alternate default currency symbol will be used.
To change the default currency symbol, specify CURRENCY(literal), where literal is a
valid COBOL alphanumeric literal (optionally a hexadecimal literal) that represents
a single character. The literal must not be from the following list:
v Digits zero (0) through nine (9)
v Uppercase alphabetic characters A B C D E G N P R S V X Z or their lowercase
equivalents
v The space
v Special characters * + - / , . ; ( ) " =
v A figurative constant
v A null-terminated literal
v A DBCS literal
v A national literal
If your program processes only one currency type, you can use the CURRENCY
option as an alternative to the CURRENCY SIGN clause for indicating the currency
symbol you will use in the PICTURE clause of your program. If your program
processes more than one currency type, you should use the CURRENCY SIGN clause
with the WITH PICTURE SYMBOL phrase to specify the different currency sign types.
If you use both the CURRENCY option and the CURRENCY SIGN clause in a program,
the CURRENCY option is ignored. Currency symbols specified in the CURRENCY SIGN
clause or clauses can be used in PICTURE clauses.
When the NOCURRENCY option is in effect and you omit the CURRENCY SIGN clause,
the dollar sign ($) is used as the PICTURE symbol for the currency sign.
Chapter 17. Compiler options 317
Delimiter: You can delimit the CURRENCY option literal with either quotation marks
or single quotation marks, regardless of the QUOTE|APOST compiler option setting.
RELATED TASKS
Using currency signs on page 65
DATA
The DATA option affects whether storage for dynamic data areas and other dynamic
runtime storage is obtained from above or below the 16 MB line.
DATA option syntax
31
DATA( 24 )
Default is: DATA(31)
Abbreviations are: None
For reentrant programs, the DATA compiler option and the HEAP runtime option
control whether storage for dynamic data areas (such as WORKING-STORAGE and FD
record areas) is obtained from below the 16 MB line (DATA(24)) or from
unrestricted storage (DATA(31)). (DATA does not affect the location of LOCAL-STORAGE
data; the STACK runtime option controls that location instead, along with the AMODE
of the program.)
Specify DATA(24) for programs that run in 31-bit addressing mode and that pass
data arguments to programs in 24-bit addressing mode. Doing so ensures that the
data will be addressable by the called program.
External data and QSAM buffers: The DATA option interacts with other compiler
options and runtime options that affect storage and its addressability. See the
related information for details.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Language Environment Programming Guide (Using runtime options)
RELATED REFERENCES
Allocation of buffers for QSAM files on page 181
DBCS
Using DBCS causes the compiler to recognize X0E (SO) and X0F (SI) as shift
codes for the double-byte portion of an alphanumeric literal.
318 Enterprise COBOL for z/OS, V5.2 Programming Guide
DBCS option syntax
DBCS
NODBCS
Default is: DBCS
Abbreviations are: None
With DBCS in effect, the double-byte portion of the literal is syntax-checked and the
literal remains category alphanumeric.
RELATED REFERENCES
Conflicting compiler options on page 304
DECK
Use DECK to produce object code in the form of 80-column records. If you use the
DECK option, be certain that SYSPUNCH is defined in your JCL for compilation.
DECK option syntax
NODECK
DECK
Default is: NODECK
Abbreviations are: D|NOD
RELATED TASKS
Creating object code (SYSLIN or SYSPUNCH) on page 271
DIAGTRUNC
DIAGTRUNC causes the compiler to issue a severity-4 (Warning) diagnostic message
for MOVE statements that have numeric receivers when the receiving data item has
fewer integer positions than the sending data item or literal. In statements that
have multiple receivers, the message is issued separately for each receiver that
could be truncated.
Chapter 17. Compiler options 319
DIAGTRUNC option syntax
NODIAGTRUNC
DIAGTRUNC
Default is: NODIAGTRUNC
Abbreviations are: DTR|NODTR
The diagnostic message is also issued for implicit moves associated with
statements such as these:
v INITIALIZE
v READ . . . INTO
v RELEASE . . . FROM
v RETURN . . . INTO
v REWRITE . . . FROM
v WRITE . . . FROM
The diagnostic message is also issued for moves to numeric receivers from
alphanumeric data-names or literal senders, except when the sending field is
reference modified.
There is no diagnostic message for COMP-5 receivers, nor for binary receivers when
you specify the TRUNC(BIN) option.
RELATED CONCEPTS
Formats for numeric data on page 47
Reference modifiers on page 113
RELATED REFERENCES
TRUNC on page 363
DISPSIGN
The DISPSIGN option controls output formatting for DISPLAY of signed numeric
items.
DISPSIGN option syntax
COMPAT
DISPSIGN( SEP )
Default is: DISPSIGN(COMPAT)
Abbreviations are: DS(C | S)
320 Enterprise COBOL for z/OS, V5.2 Programming Guide
DISPSIGN(COMPAT)
If you specify DISPSIGN(COMPAT), formatting for displayed values of signed
numeric items is compatible with prior versions of Enterprise COBOL.
Overpunch signs are generated in some cases.
DISPSIGN(SEP)
If you specify DISPSIGN(SEP), the displayed values for signed binary,
signed packed-decimal, or overpunch signed zoned-decimal items are
always formatted with a leading separate sign.
The following example shows the DISPLAY output with the DISPSIGN(COMPAT)
option or the DISPSIGN(SEP) option specified:
Table 46. DISPLAY output with the DISPSIGN(COMPAT) option or the DISPSIGN(SEP) option
specified:
DISPLAY output with the DISPLAY output with the
DISPSIGN(COMPAT) option DISPSIGN(SEP) option
Data items specified specified
Unsigned binary 111 111
Positive binary 111 +111
Negative binary 11J -111
Unsigned packed-decimal 222 222
Positive packed-decimal 222 +222
Negative packed-decimal 22K -222
Zoned-decimal unsigned 333 333
Zoned-decimal trailing 33C +333
positive
Zoned-decimal trailing 33L -333
negative
Zoned-decimal leading C33 +333
positive
Zoned-decimal leading L33 -333
negative
DLL
Use DLL to instruct the compiler to generate an object module that is enabled for
dynamic link library (DLL) support. DLL enablement is required if the program
will be part of a DLL, will reference DLLs, or if the program contains
object-oriented COBOL syntax such as INVOKE statements or class definitions.
| Note: The DLL option can be overridden for particular CALL statements by using
| the CALLINTERFACE directive.
DLL option syntax
NODLL
DLL
Chapter 17. Compiler options 321
Default is: NODLL
Abbreviations are: None
Link-edit considerations: COBOL programs that are compiled with the DLL option
must be link-edited with the RENT and AMODE 31 link-edit options.
NODLL instructs the compiler to generate an object module that is not enabled for
DLL usage.
RELATED TASKS
Making dynamic calls on page 467
RELATED REFERENCES
Conflicting compiler options on page 304
| CALLINTERFACE (Enterprise COBOL Language Reference)
DUMP
Use DUMP to produce a system dump at compile time for an internal compiler error.
DUMP option syntax
NODUMP
DUMP
Default is: NODUMP
Abbreviations are: DU|NODU
Not for general use: The DUMP option should be used only at the request of an IBM
representative.
The dump, which consists of a listing of the compiler's registers and a storage
dump, is intended primarily for diagnostic personnel for determining errors in the
compiler.
If you use the DUMP option, include a DD statement at compile time to define
SYSABEND, SYSUDUMP, or SYSMDUMP.
With DUMP, the compiler will not issue a diagnostic message before abnormal
termination processing. Instead, a user abend will be issued with an IGYppnnnn
message. In general, a message IGYppnnnn corresponds to a compile-time user
abend nnnn. However, both IGYpp5nnn and IGYpp1nnn messages produce a user
abend of 1nnn. You can usually distinguish whether the message is really a 5nnn or
a 1nnn by recompiling with the NODUMP option.
Use NODUMP if you want normal termination processing, including:
v Diagnostic messages produced so far in compilation.
v A description of the error.
322 Enterprise COBOL for z/OS, V5.2 Programming Guide
v The name of the compiler phase currently executing.
v The line number of the COBOL statement being processed when the error was
found. (If you compiled with OPTIMIZE(1|2), the line number might not always
be correct; for some errors, it will be the last line in the program.)
v The contents of the general purpose registers.
Using the DUMP and OPTIMIZE(1|2) compiler options together could cause the
compiler to produce a system dump instead of the following optimizer message:
"IGYOP3124-W This statement may cause a program exception at
execution time."
This situation does not represent a compiler error. Using the NODUMP option will
allow the compiler to issue message IGYOP3124-W and continue processing.
RELATED TASKS
Language Environment Debugging Guide (Understanding abend codes)
RELATED REFERENCES
Conflicting compiler options on page 304
DYNAM
Use DYNAM to cause nonnested, separately compiled programs invoked through the
CALL literal statement to be loaded for CALL, and deleted for CANCEL, dynamically at
run time.
| Note: The DYNAM option can be overridden for particular CALL statements by using
| the CALLINTERFACE directive.
CALL identifier statements always result in a runtime load of the target program and
are not affected by this option.
DYNAM option syntax
NODYNAM
DYNAM
Default is: NODYNAM
Abbreviations are: DYN|NODYN
Restriction: The DYNAM compiler option must not be used in the following cases:
v COBOL programs that are processed by the CICS translator or the CICS compiler
option
v COBOL programs that have EXEC SQL statements and are run under CICS or
DB2 call attach facility (CAF)
If your COBOL program calls programs that have been linked as dynamic link
libraries (DLLs), you must not use the DYNAM option. You must instead compile the
program with the NODYNAM and DLL options.
Chapter 17. Compiler options 323
RELATED TASKS
Making both static and dynamic calls on page 471
Choosing the DYNAM or NODYNAM compiler option on page 441
RELATED REFERENCES
Conflicting compiler options on page 304
| CALLINTERFACE (Enterprise COBOL Language Reference)
EXIT
Use the EXIT option to provide user-supplied modules in place of various compiler
functions.
For compiler input, use the INEXIT and LIBEXIT suboptions to provide modules in
place of SYSIN and SYSLIB (or copy library), respectively. For compiler output, use
the PRTEXIT suboption to provide a module in place of SYSPRINT.
To provide a module that will be called for each SYSADATA record immediately
after the record has been written out to the file, use the ADEXIT suboption.
To customize compiler messages (change their severity or suppress them, including
converting FIPS (FLAGSTD) messages to diagnostic messages to which you assign a
severity), use the MSGEXIT suboption. The module that you provide to customize
the messages will be called each time the compiler issues a diagnostic message or a
FIPS message.
EXIT option syntax
NOEXIT
EXIT( )
INEXIT( mod1)
str1,
NOINEXIT
LIBEXIT( mod2)
str2,
NOLIBEXIT
PRTEXIT( mod3)
str3,
NOPRTEXIT
ADEXIT( mod4)
str4,
NOADEXIT
MSGEXIT( mod5)
str5,
NOMSGEXIT
Default is: NOEXIT
Abbreviations are: NOEX|EX(INX|NOINX, LIBX|NOLIBX, PRTX|NOPRTX, ADX|NOADX,
MSGX|NOMSGX)
324 Enterprise COBOL for z/OS, V5.2 Programming Guide
You can specify the suboptions in any order, and can separate them by either
commas or spaces. If you specify both the positive and negative form of a
suboption, the form specified last takes effect. If you specify the same suboption
more than once, the last one specified takes effect.
If you specify the EXIT option without specifying at least one suboption, NOEXIT
will be in effect.
You can specify the EXIT option only at invocation in the JCL PARM field (under
TSO/E, in a command argument) or at installation time. Do not specify the EXIT
option in a PROCESS (CBL) statement.
INEXIT([str1,]mod1)
| The compiler reads source code from a user-supplied program object
(where mod1 is the module name) instead of SYSIN.
LIBEXIT([str2,]mod2)
| The compiler obtains copybooks from a user-supplied program object
(where mod2 is the module name) instead of library-name or SYSLIB. For
use with either COPY or BASIS statements.
PRTEXIT([str3,]mod3)
| The compiler passes printer-destined output to the user-supplied program
| object (where mod3 is the module name) instead of SYSPRINT.
ADEXIT([str4,]mod4)
| The compiler passes the SYSADATA output to the user-supplied program
| object (where mod4 is the module name).
MSGEXIT([str5,]mod5)
The compiler passes the message number, and passes the default severity
of a compiler diagnostic message, or the category (as a numeric code) of a
| FIPS compiler message, to the user-supplied program object (where mod5 is
the module name).
The names mod1, mod2, mod3, mod4, and mod5 can refer to the same module.
The suboptions str1, str2, str3, str4, and str5 are character strings that are passed to
| the program object. These strings are optional. They can be up to 64 characters in
length, and you must enclose them in single quotation marks. You can use any
character in the strings, but any included single quotation marks must be doubled.
Lowercase characters are folded to uppercase.
If one of str1, str2, str3, str4, or str5 is specified, that string is passed to the
appropriate user-exit module in the following format, where LL is a halfword (on a
halfword boundary) that contains the length of the string.
LL string
Example: MSGEXIT user exit on page 713
Compiler exit modules that are specified on the EXIT option can be implemented
either in an assembler language or in a high-level programming language such as
COBOL. However, when exits are written in a Language Environment conforming
programming language or Language Environment conforming assembler language,
the exit must be reentrant.
Chapter 17. Compiler options 325
The Enterprise COBOL compiler automatically manages a preinitialized Language
Environment at compile time, and calls compiler exits within this environment.
Therefore, the following rules apply:
v Compiler exits are run as subprograms instead of main programs.
v Compiler exits must not include logic for explicitly initializing or terminating
Language Environment. In particular, exits must not use the RTEREUS runtime
option, the IGZERRE callable service, or the CEEPIPI callable service for
environment management.
v Compiler exits must not use the STOP RUN statement.
RELATED REFERENCES
Conflicting compiler options on page 304
FLAGSTD on page 328
Appendix D, EXIT compiler option, on page 701
EXPORTALL
Use EXPORTALL to instruct the compiler to automatically export the PROGRAM-ID
name and each alternate entry-point name from each program definition when the
object deck is link-edited to form a DLL.
EXPORTALL option syntax
NOEXPORTALL
EXPORTALL
Default is: NOEXPORTALL
Abbreviations are: EXP|NOEXP
With these symbols exported from the DLL, the exported program and entry-point
| names can be called from programs in the root program object, in other DLL
| program objects in the application, and from programs that are linked into that
DLL.
Specification of the EXPORTALL option requires that the RENT linker option also be
used.
NOEXPORTALL instructs the compiler to not export any symbols. In this case the
programs are accessible only from other routines that are link-edited into the same
| program object as the COBOL program definition.
RELATED REFERENCES
Conflicting compiler options on page 304
326 Enterprise COBOL for z/OS, V5.2 Programming Guide
FASTSRT
Use FASTSRT to let IBM DFSORT, or an equivalent product, perform sort input and
| output instead of Enterprise COBOL. It applies only to sorting files by using the
| format 1 SORT (that is, file SORT) statement.
FASTSRT option syntax
NOFASTSRT
FASTSRT
Default is: NOFASTSRT
Abbreviations are: FSRT|NOFSRT
RELATED TASKS
Improving sort performance with FASTSRT on page 231
FLAG
Use FLAG(x) to produce diagnostic messages at the end of the source listing for
errors of a severity level x or above.
FLAG option syntax
FLAG(x )
,y
NOFLAG
Default is: FLAG(I,I)
Abbreviations are: F|NOF
x and y can be either I, W, E, S, or U.
Use FLAG(x,y) to produce diagnostic messages for errors of severity level x or
above at the end of the source listing, with error messages of severity y and above
to be embedded directly in the source listing. The severity coded for y must not be
lower than the severity coded for x. To use FLAG(x,y), you must also specify the
SOURCE compiler option.
Error messages in the source listing are set off by the embedding of the statement
number in an arrow that points to the message code. The message code is followed
by the message text. For example:
Chapter 17. Compiler options 327
000413 MOVE CORR WS-DATE TO HEADER-DATE
==000413==> IGYPS2121-S " WS-DATE " was not defined as a data-name. . . .
When FLAG(x,y) is in effect, messages of severity y and above are embedded in the
listing after the line that caused the message. (See the related reference below for
information about messages for exceptions.)
Use NOFLAG to suppress error flagging. NOFLAG does not suppress error messages for
compiler options.
Embedded messages
v Embedding level-U messages is not recommended. The specification of
embedded level-U messages is accepted, but does not produce any messages in
the source.
v The FLAG option does not affect diagnostic messages that are produced before
the compiler options are processed.
v Diagnostic messages that are produced during processing of compiler options,
CBL or PROCESS statements, or BASIS, COPY, or REPLACE statements are not
embedded in the source listing. All such messages appear at the beginning of
the compiler output.
v Messages that are produced during processing of the *CONTROL or *CBL statement
are not embedded in the source listing.
RELATED REFERENCES
Messages and listings for compiler-detected errors on page 280
FLAGSTD
| Use FLAGSTD to specify the level or subset of the 85 COBOL Standard to be
| regarded as conforming, and to get informational messages about the 85 COBOL
| Standard elements that are included in your program.
You can specify any of the following items for flagging:
v A selected Federal Information Processing Standard (FIPS) COBOL subset
v Any of the optional modules
v Obsolete language elements
v Any combination of subset and optional modules
v Any combination of subset and obsolete elements
v IBM extensions (these are flagged any time that FLAGSTD is specified, and
identified as "nonconforming nonstandard")
FLAGSTD option syntax
NOFLAGSTD
FLAGSTD(x )
yy ,O
328 Enterprise COBOL for z/OS, V5.2 Programming Guide
Default is: NOFLAGSTD
Abbreviations are: None
| x specifies the subset of the 85 COBOL Standard to be regarded as conforming:
M Language elements that are not from the minimum subset are to be
flagged as "nonconforming standard."
I Language elements that are not from the minimum or the intermediate
subset are to be flagged as "nonconforming standard."
H The high subset is being used and elements will not be flagged by subset.
Elements that are IBM extensions will be flagged as "nonconforming
Standard, IBM extension."
yy specifies, by a single character or combination of any two, the optional modules
to be included in the subset:
D Elements from debug module level 1 are not flagged as "nonconforming
standard."
N Elements from segmentation module level 1 are not flagged as
"nonconforming standard."
S Elements from segmentation module level 2 are not flagged as
"nonconforming standard."
If S is specified, N is included (N is a subset of S).
O (the letter) specifies that obsolete language elements are flagged as "obsolete."
The informational messages appear in the source program listing, and identify:
v The element as "obsolete," "nonconforming standard," or "nonconforming
nonstandard" (a language element that is both obsolete and nonconforming is
flagged as obsolete only)
v The clause, statement, or header that contains the element
v The source program line and beginning location of the clause, statement, or
header that contains the element
v The subset or optional module to which the element belongs
FLAGSTD requires the standard set of reserved words.
In the following example, the line number and column where a flagged clause,
statement, or header occurred are shown with the associated message code and
text. After that is a summary of the total number of flagged items and their type.
Chapter 17. Compiler options 329
LINE.COL CODE FIPS MESSAGE TEXT
IGYDS8211 Comment lines before "IDENTIFICATION DIVISION":
nonconforming nonstandard, IBM extension to
ANS/ISO 1985.
11.14 IGYDS8111 "GLOBAL clause": nonconforming standard, ANS/ISO
1985 high subset.
59.12 IGYPS8169 "USE FOR DEBUGGING statement": obsolete element
in ANS/ISO 1985.
FIPS MESSAGES TOTAL STANDARD NONSTANDARD OBSOLETE
3 1 1 1
You can convert FIPS informational messages into diagnostic messages, and can
suppress FIPS messages, by using the MSGEXIT suboption of the EXIT compiler
option. For details, see the related reference about the processing of MSGEXIT, and
see the related task.
RELATED TASKS
Customizing compiler-message severities on page 710
RELATED REFERENCES
Conflicting compiler options on page 304
Processing of MSGEXIT on page 709
HGPR
The HGPR option controls the compiler usage of the 64-bit registers provided by
z/Architecture processors.
HGPR option syntax
PRESERVE
HGPR( NOPRESERVE )
Default is: HGPR(PRESERVE)
Abbreviations are: None
The Enterprise COBOL compiler uses the 64-bit width of the z/Architecture
General Purpose Registers (GPRs). HGPR stands for "High-halves of 64-bit GPRs",
which means the use of native 64-bit instructions.
HGPR(PRESERVE)
If you specify HGPR(PRESERVE), the compiler preserves the high halves of
the 64-bit GPRs that a program is using, by saving them in the prolog for
the function and restoring them in the epilog. The PRESERVE suboption is
necessary only if the caller of the program is not Enterprise COBOL,
Enterprise PL/I, or z/OS XL C/C++ compiler-generated code.
330 Enterprise COBOL for z/OS, V5.2 Programming Guide
HGPR(NOPRESERVE)
If you specify HGPR(NOPRESERVE), the compiler omits preserving the
high-halves of the 64-bit GPRs that a program is using, which improves
performance.
INTDATE
| INTDATE(ANSI) instructs the compiler to use the 85 COBOL Standard starting date
for integer dates used with date intrinsic functions. Day 1 is Jan 1, 1601.
INTDATE(LILIAN) instructs the compiler to use the Language Environment Lilian
starting date for integer dates used with date intrinsic functions. Day 1 is Oct 15,
1582.
INTDATE option syntax
ANSI
INTDATE( LILIAN )
Default is: INTDATE(ANSI)
Abbreviations are: None
With INTDATE(LILIAN), the date intrinsic functions return results that are
compatible with the Language Environment date callable services.
Usage note: When INTDATE(LILIAN) is in effect, CEECBLDY is not usable because
you have no way to turn an ANSI integer into a meaningful date by using either
intrinsic functions or callable services. If you code a CALL literal statement with
CEECBLDY as the target of the call when INTDATE(LILIAN) in effect, the compiler
diagnoses this and converts the call target to CEEDAYS.
RELATED TASKS
Using date callable services on page 60
LANGUAGE
Use the LANGUAGE option to select the language in which compiler output will be
printed. The information that will be printed in the selected language includes
diagnostic messages, source listing page and scale headers, FIPS message headers,
message summary headers, compilation summary, and headers and notations that
result from the selection of certain compiler options (MAP, XREF, VBREF, and
FLAGSTD).
LANGUAGE option syntax
LANGUAGE(name)
Chapter 17. Compiler options 331
Default is: LANGUAGE(ENGLISH)
Abbreviations are: LANG(EN|UE|JA|JP)
name specifies the language for compiler output messages. Possible values for the
LANGUAGE option are shown in the table below.
Table 47. Values of the LANGUAGE compiler option
Name Abbreviation1 Output language
ENGLISH EN Mixed-case English (the default)
JAPANESE JA, JP Japanese, using the Japanese character set
2
UENGLISH UE Uppercase English
1. If your installation's system programmer has provided a language other than those
described, you must specify at least the first two characters of this other language's
name.
2. To specify a language other than UENGLISH, the appropriate language feature must be
installed.
If the LANGUAGE option is changed at compile time (using CBL or PROCESS
statements), some initial text will be printed using the language that was in effect
at the time the compiler was started.
NATLANG: The NATLANG runtime option allows you to control the national language
to be used for the runtime environment, including error messages, month names,
and day-of-the-week names. The LANGUAGE compiler option and the NATLANG
runtime option act independently of each other. You can use them together with
neither taking precedence over the other.
LINECOUNT
Use LINECOUNT(nnn) to specify the number of lines to be printed on each page of
the compilation listing, or use LINECOUNT(0) to suppress pagination.
LINECOUNT option syntax
LINECOUNT(nnn)
Default is: LINECOUNT(60)
Abbreviations are: LC
nnn must be an integer between 10 and 255, or 0.
If you specify LINECOUNT(0), no page ejects are generated in the compilation listing.
The compiler uses three lines of nnn for titles. For example, if you specify
LINECOUNT(60), 57 lines of source code are printed on each page of the output
listing.
332 Enterprise COBOL for z/OS, V5.2 Programming Guide
LIST
Use the LIST compiler option to produce a listing of the assembler-language
expansion of your source code.
LIST option syntax
NOLIST
LIST
Default is: NOLIST
Abbreviations are: None
These items will also be written to the output listing:
v Constant area
v Program prolog areas (PPA1, PPA2, PPA3, PPA4)
v Time stamp and compiler version information
v Compiler options and program information
v Base locator table
v External symbols dictionary
v Static maps
v Automatic maps
The output is generated if:
v You specify the COMPILE option, or the NOCOMPILE(x) option is in effect and an
error of level x or higher does not occur.
v You do not specify the OFFSET option.
If you want to limit the assembler listing output, use *CONTROL (or *CBL) LIST or
NOLIST statements in the PROCEDURE DIVISION. Source statements that follow a
*CONTROL NOLIST statement are not included in the listing until a subsequent
*CONTROL LIST statement switches the output back to normal LIST format.
RELATED TASKS
Getting listings on page 387
RELATED REFERENCES
Conflicting compiler options on page 304
*CONTROL (*CBL) statement (Enterprise COBOL Language Reference)
MAP
| Use the MAP option to create a listing of the DATA DIVISION items and all implicitly
| declared items. You can also specify whether hexadecimal or decimal offsets are
| shown for MAP output in the listing.
Chapter 17. Compiler options 333
| MAP option syntax
| NOMAP
MAP
HEX
( DEC )
|
||
| Default is: NOMAP
| Suboption default is: MAP(HEX) if MAP is specified with no suboption
Abbreviations are: None
| HEX If you specify MAP(HEX), data item offsets within groups will be in
| hexadecimal notation.
| DEC If you specify MAP(DEC), data item offsets within groups will be in decimal
| notation.
The output includes the following items:
v DATA DIVISION map
v Global tables
v Literal pools
v Nested program structure map, and program attributes
v Size of the program's WORKING-STORAGE and LOCAL-STORAGE and its location in the
object code if the program is compiled with the NORENT option
If you want to limit the MAP output, use *CONTROL MAP or NOMAP statements in the
DATA DIVISION. Source statements that follow *CONTROL NOMAP are not included in
the listing until a *CONTROL MAP statement switches the output back to normal MAP
format. For example:
*CONTROL NOMAP *CBL NOMAP
01 A 01 A
02 B 02 B
*CONTROL MAP *CBL MAP
| When the MAP(HEX|DEC) option is in effect, you also get an embedded MAP report in
the source code listing. The condensed MAP information is shown to the right of
data-name definitions in the WORKING-STORAGE SECTION, FILE SECTION,
LOCAL-STORAGE SECTION, and LINKAGE SECTION of the DATA DIVISION. When both
XREF data and an embedded MAP summary are on the same line, the embedded MAP
| summary is listed first.
Example: MAP output on page 392
RELATED CONCEPTS
Chapter 19, Debugging, on page 377
RELATED TASKS
Getting listings on page 387
334 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
*CONTROL (*CBL) statement (Enterprise COBOL Language Reference)
MAXPCF
Use the MAXPCF option to specify a maximum program complexity factor value. The
program complexity factor (PCF) is computed by the compiler and the computed
value is in the listing file. If the PCF of your program exceeds the maximum value,
the compiler will automatically reduce the optimization level to speed up the
compilation and use less storage. Therefore, when you compile a suite of
programs, you do not have to specify an OPTIMIZE option value for each program.
MAXPCF option syntax
MAXPCF(n)
Default is: MAXPCF(60000)
Abbreviations are: None
n must be an integer of 0 - 999999.
The aspects of the program taken into consideration when computing the
complexity factor include:
v The number of COBOL statements in the PROCEDURE DIVISION, including
generated statements from the CICS, SQL or SQLIMS options, and the expansion of
COPY and REPLACE statements
v Initialization operations for WORKING-STORAGE or LOCAL-STORAGE data items with
value clauses
v Operations for variable-length groups or subgroups in the DATA DIVISION, which
compute their size at run time
For large and complex programs, you can use the MAXPCF option to set a threshold
on the program complexity that the compiler attempts optimize. Lower the
MAXPCF value to reduce the optimization level, hence the compiler needs less
memory and compilation time. Raise the MAXPCF value to attempt to optimize
the programs at the cost of longer compilation time.
If you specify MAXPCF(0), no limit is enforced on the complexity of the program,
and the MAXPCF option has no effect.
If you specify MAXPCF(n) and n is not zero, when the program complexity factor
exceeds n, any specification of OPTIMIZE(1) or OPTIMIZE(2) is reset to OPTIMIZE(0),
and a warning message is generated.
If the COBOL source file contains a sequence of source programs (a batch compile),
the MAXPCF limit is applied on a per program basis.
Notes:
Chapter 17. Compiler options 335
v If the OPTIMIZE(1) or OPTIMIZE(2) option is set at installation time as a fixed,
nonoverridable option, then MAXPCF(n) with a nonzero n is an option conflict. In
this case, the OPTIMIZE option takes precedence and the MAXPCF(0) option is
forced on.
v If you attempt to optimize a program larger than the default threshold by
raising the value of MAXPCF to n where n is greater than the default, or by
specifying MAXPCF(0), the compiler might take excessive time to compile or fail
to compile because of insufficient memory.
RELATED REFERENCES
OPTIMIZE on page 343
MDECK
The MDECK compiler option specifies that a copy of the updated input source after
library processing (that is, the result of COPY, BASIS, REPLACE, EXEC SQL INCLUDE,
and EXEC SQLIMS INCLUDE statements) is written to a file.
If Enterprise COBOL is running under z/OS UNIX, the MDECK output is written in
the current directory to a file that has the same name as the COBOL source file and
a suffix of .dek. For Enterprise COBOL running under TSO or batch, the MDECK
output is written to the data set defined by the SYSMDECK DD allocation, which must
specify an MVS data set that has RECFM F or FB and an LRECL of 80 bytes.
Note: When compiling under z/OS TSO or batch, the COBOL compiler requires
the SYSMDECK data set allocation for all compilations, no matter if you specify the
MDECK or NOMDECK option:
v If you specify the MDECK option, the SYSMDECK DD allocation must specify a
permanent data set.
v If you specify the NOMDECK option, the SYSMDECK DD allocation can specify either
a temporary utility data set or a permanent data set.
MDECK option syntax
NOMDECK
MDECK
COMPILE
( NOCOMPILE )
Default is: NOMDECK
Abbreviations are: NOMD|MD|MD(C|NOC)
Option specification:
You cannot specify the MDECK option in a PROCESS (or CBL) statement. You can
specify it only in one of the following ways:
v In the PARM parameter of JCL
v As a cob2 command option
336 Enterprise COBOL for z/OS, V5.2 Programming Guide
v As an installation default
v In the COBOPT environment variable
Suboptions:
v When MDECK(COMPILE) is in effect, compilation continues normally after library
processing and generation of the MDECK output file have completed, subject to the
settings of the COMPILE|NOCOMPILE, DECK|NODECK, and OBJECT|NOOBJECT compiler
options.
v When MDECK(NOCOMPILE) is in effect, compilation is terminated after library
processing has completed and the expanded source program file has been
written. The compiler does no further syntax checking or code generation
regardless of the settings of the COMPILE, DECK, and OBJECT compiler options.
If you specify MDECK with no suboption, MDECK(COMPILE) is implied.
Contents of the MDECK output file:
If you use the MDECK option with programs that contain EXEC CICS, EXEC SQL, or
EXEC SQLIMS statements, these EXEC statements are included in the MDECK output as
is. However, if you compile using the SQL or SQLIMS option, the corresponding EXEC
SQL INCLUDE or EXEC SQLIMS INCLUDE statements are expanded in the MDECK output.
CBL, PROCESS, *CONTROL, and *CBL card images are passed to the MDECK output file in
the proper locations.
For a batch compilation (multiple COBOL source programs in a single input file), a
single MDECK output file that contains the complete expanded source is created.
Any SEQUENCE compiler-option processing is reflected in the MDECK file.
COPY statements are included in the MDECK file as comments.
RELATED TASKS
Starting the compiler from an assembler program on page 265
Defining the library-processing output file (SYSMDECK) on page 272
RELATED REFERENCES
Conflicting compiler options on page 304
Chapter 18, Compiler-directing statements, on page 373
NAME
Use NAME to generate a link-edit NAME card for each object module. You can also use
| NAME to generate names for each program object when you are doing batch
compilations.
When NAME is specified, a NAME card is appended to each object module that is
| created. Program object names are formed using the rules for forming module
names from PROGRAM-ID statements.
Chapter 17. Compiler options 337
NAME option syntax
NONAME
NAME
NOALIAS
( ALIAS )
Default is: NONAME, or NAME(NOALIAS) if only NAME is specified
Abbreviations are: None
If you specify NAME(ALIAS), and your program contains ENTRY statements, a
link-edit ALIAS card is generated for each ENTRY statement.
RELATED REFERENCES
PROGRAM-ID paragraph (Enterprise COBOL Language Reference)
NSYMBOL
The NSYMBOL option controls the interpretation of the N symbol used in literals and
PICTURE clauses, indicating whether national or DBCS processing is assumed.
NSYMBOL option syntax
NATIONAL
NSYMBOL( DBCS )
Default is: NSYMBOL(NATIONAL)
Abbreviations are: NS(NAT|DBCS)
With NSYMBOL(NATIONAL):
v Data items defined with a PICTURE clause that consists only of the symbol N
without the USAGE clause are treated as if the USAGE NATIONAL clause is specified.
v Literals of the form N". . ." or N. . . are treated as national literals.
With NSYMBOL(DBCS):
v Data items defined with a PICTURE clause that consists only of the symbol N
without the USAGE clause are treated as if the USAGE DISPLAY-1 clause is specified.
v Literals of the form N". . ." or N. . . are treated as DBCS literals.
The NSYMBOL(DBCS) option provides compatibility with previous releases of IBM
COBOL, and the NSYMBOL(NATIONAL) option makes the handling of the above
| language elements consistent with the 2002 COBOL Standard in this regard.
NSYMBOL(NATIONAL) is recommended for applications that use Unicode data or
object-oriented syntax for Java interoperability.
338 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
Conflicting compiler options on page 304
NUMBER
Use the NUMBER compiler option if you have line numbers in your source code and
want those numbers to be used in error messages and SOURCE, MAP, LIST, and XREF
listings.
NUMBER option syntax
NONUMBER
NUMBER
Default is: NONUMBER
Abbreviations are: NUM|NONUM
If you request NUMBER, the compiler checks columns 1 through 6 to make sure that
they contain only numbers and that the numbers are in numeric collating
sequence. (In contrast, SEQUENCE checks the characters in these columns according
to EBCDIC collating sequence.) When a line number is found to be out of
sequence, the compiler assigns to it a line number with a value one higher than the
line number of the preceding statement. The compiler flags the new value with
two asterisks and includes in the listing a message indicating an out-of-sequence
error. Sequence-checking continues with the next statement, based on the newly
assigned value of the previous line.
If you use COPY statements and NUMBER is in effect, be sure that your source
program line numbers and the copybook line numbers are coordinated.
If you are doing a batch compilation and NUMBER is in effect, all programs in the
batch compile will be treated as a single input file. The sequence numbers of the
entire input file must be in ascending order.
Use NONUMBER if you do not have line numbers in your source code, or if you want
the compiler to ignore the line numbers you do have in your source code. With
NONUMBER in effect, the compiler generates line numbers for your source statements
and uses those numbers as references in listings.
NUMPROC
Use NUMPROC(NOPFD) if your internal decimal and zoned decimal data might use
nonpreferred signs.
Chapter 17. Compiler options 339
NUMPROC option syntax
NOPFD
NUMPROC( PFD )
Default is: NUMPROC(NOPFD)
Abbreviations are: None
The compiler accepts any valid sign configuration: X'A', X'B', X'C', X'D', X'E', or
X'F'. NUMPROC(NOPFD) is the recommended option in most cases.
Performance considerations: NUMPROC(PFD) improves the performance of
processing internal decimal and zoned decimal data. Use this option however only
if your numeric data agrees exactly with the following IBM system standards:
v Zoned decimal, unsigned: High-order 4 bits of the sign byte contain X'F'.
v Zoned decimal, signed overpunch: High-order 4 bits of the sign byte contain
X'C' if a number is positive or 0, and X'D' if it is not.
v Zoned decimal, separate sign: Separate sign contains the character '+' if a
number is positive or 0, and '-' if it is not.
v Internal decimal, unsigned: Low-order 4 bits of the low-order byte contain X'F'.
v Internal decimal, signed: Low-order 4 bits of the low-order byte contain X'C' if
a number is positive or 0, and X'D' if it is not.
Data produced by COBOL arithmetic statements conforms to the IBM system
standards described above. However, using REDEFINES and group moves could
change data so that it no longer conforms. If you use NUMPROC(PFD), use the
INITIALIZE statement to initialize data fields, rather than using group moves.
Using NUMPROC(PFD) can affect class tests for numeric data. Use NUMPROC(NOPFD) if a
COBOL program calls programs written in PL/I or FORTRAN.
Sign representation is affected not only by the NUMPROC option, but also by the
NUMCLS installation option.
RELATED TASKS
Checking for incompatible data (numeric class test) on page 54
RELATED REFERENCES
Sign representation of zoned and packed-decimal data on page 53
OBJECT
Use OBJECT to write the generated object code to a file to be used as input for the
binder.
340 Enterprise COBOL for z/OS, V5.2 Programming Guide
OBJECT option syntax
OBJECT
NOOBJECT
Default is: OBJECT
Abbreviations are: OBJ|NOOBJ
If you specify OBJECT, include a SYSLIN DD statement in your JCL for compilation.
The only difference between DECK and OBJECT is in the routing of output to the data
sets:
v DECK output goes to the data set associated with ddname SYSPUNCH.
v OBJECT output goes to the data set associated with ddname SYSLIN.
Use the option that your installation guidelines recommend.
RELATED REFERENCES
Conflicting compiler options on page 304
OFFSET
Use OFFSET to produce a condensed PROCEDURE DIVISION listing.
OFFSET option syntax
NOOFFSET
OFFSET
Default is: NOOFFSET
Abbreviations are: OFF|NOOFF
With OFFSET, the condensed PROCEDURE DIVISION listing will contain line numbers,
statement references, and the location of the first instruction generated for each
statement. In addition, the listing also shows:
v Global tables
v Literal pools
v Size of the program's WORKING-STORAGE, and its location in the object code if the
program is compiled with the NORENT option
RELATED REFERENCES
Conflicting compiler options on page 304
Chapter 17. Compiler options 341
OPTFILE
Use OPTFILE to enable the specifying of COBOL compiler options in a data set.
Using a compiler-option data set circumvents the 100-character limit on options
specified in a JCL PARM string.
OPTFILE option syntax
OPTFILE
Default is: None
Abbreviations are: None
You can specify OPTFILE as a compiler invocation option or in the PROCESS or CBL
statement in your COBOL source program. OPTFILE cannot be specified as an
installation default.
OPTFILE is ignored if you compile using the cob2 command in the z/OS UNIX
environment. (In that environment, the COBOPT environment variable provides a
capability that is comparable to OPTFILE.)
If OPTFILE is in effect, compiler options are read from the data set that you identify
in a SYSOPTF DD statement. A SYSOPTF data set must have RECFM F or FB and an
LRECL of 80 bytes. For further details about the format of a SYSOPTF data set, see the
related task below about defining a compiler-option data set.
The precedence of options in the SYSOPTF data set is determined by where you
specify the OPTFILE option. For example, if you specify OPTFILE in the invocation
PARM string, an option specified later in the PARM string supersedes any option
specified in the SYSOPTF data set that conflicts with it.
(Conceptually, OPTFILE in an options specification is replaced with the options that
are in the SYSOPTF data set; then the usual rules about precedence of compiler
options and conflicting compiler options apply.)
If you start the COBOL compiler from within an assembler program, you can use
the alternate ddname list to specify a ddname to be used instead of SYSOPTF to
identify the compiler-option data set.
RELATED TASKS
Starting the compiler from an assembler program on page 265
Defining a compiler-option data set (SYSOPTF) on page 269
Specifying compiler options under z/OS on page 272
Chapter 15, Compiling under z/OS UNIX, on page 283
RELATED REFERENCES
Conflicting compiler options on page 304
342 Enterprise COBOL for z/OS, V5.2 Programming Guide
OPTIMIZE
Use OPTIMIZE to reduce the run time of your object program. Optimization might
also reduce the amount of storage your object program uses.
OPTIMIZE option syntax
0
OPTIMIZE ( 1 )
2
Default is: OPTIMIZE(0)
Abbreviations are: OPT(0), OPT(1), or OPT(2)
| Optimizations are performed under the assumption that the program and data are
| valid, given the compiler options. For example, external decimal data that has
| USAGE DISPLAY must be valid unless ZONEDATA(MIG) is used to allow invalid zone
| bits for comparisons. If the program or data is invalid, programs might behave
| differently at different levels of optimization or between different versions of
| Enterprise COBOL.
v OPTIMIZE(0) specifies limited optimizations, which result in the shortest
compilation time. When the TEST option is specified, full debug capabilities are
available.
v OPTIMIZE(1) specifies optimizations that improve application runtime
performance. Optimizations at this level include basic inlining, strength
reduction, simplification of complex operations into equivalent simpler
operations, removal of some unreachable code and block rearrangement. Also,
OPTIMIZE(1) includes some intrablock optimizations such as common
subexpression elimination and value propagation. When the TEST option is
specified, most debug capabilities are available.
v OPTIMIZE(2) specifies further optimizations, which include more aggressive
simplifications and instruction scheduling. Also, some interblock optimizations
such as global value propagation and loop invariant code motion are included.
When the TEST option is specified, some debug capabilities are available.
| When OPTIMIZE(1) or OPTIMIZE(2) is used without the TEST compiler option, care
| must be taken with user-written condition handlers registered via the Language
| Environment service CEEHDLR. In particular, if a condition handler accesses data
| items that are not defined local to the condition handler program themselves (for
| example, data items defined in the application as EXTERNAL), such data items must
| be defined with the VOLATILE clause to ensure that the handler uses the latest value
| of the data item, or the condition handler program can be compiled with the TEST
| compiler option. The use of the VOLATILE clause is preferred over the use of the
| TEST option because the use of the TEST option can reduce optimization for the
| entire program, while VOLATILE localizes the reduced optimization.
| For more information about the VOLATILE clause, see VOLATILE clause in the
| Enterprise COBOL Language Reference.
Chapter 17. Compiler options 343
Note: In Enterprise COBOL V5, the NOOPTIMIZE, OPTIMIZE, OPTIMIZE(STD), and
| OPTIMIZE(FULL) options are removed but are tolerated for compatibility. If one of
| those options is specified, it is mapped to the new option or options as follows:
| Table 48. Mapping of removed options to new options
| Removed options New options
NOOPTIMIZE OPTIMIZE(0)
OPTIMIZE OPTIMIZE(1)
OPTIMIZE(STD) OPTIMIZE(1)
OPTIMIZE(FULL) OPTIMIZE(1) and STGOPT
RELATED CONCEPTS
Optimization on page 657
RELATED TASKS
Writing routines for handling errors on page 250
RELATED REFERENCES
Conflicting compiler options on page 304
MAXPCF on page 335
TEST on page 359
| STGOPT on page 358
| VOLATILE clause (Enterprise COBOL Language Reference)
OUTDD
Use OUTDD to specify that you want DISPLAY output that is directed to the system
logical output device to go to a specific ddname.
You can specify a file in the z/OS UNIX file system with the ddname named in
OUTDD. To understand where output is directed when this ddname is not allocated,
see the related task about displaying data.
OUTDD option syntax
OUTDD(ddname)
Default is: OUTDD(SYSOUT)
Abbreviations are: OUT
The MSGFILE runtime option lets you specify the ddname of the file to which all
runtime diagnostics and reports generated by the RPTOPTS and RPTSTG runtime
options are to be written. The IBM-supplied default is MSGFILE(SYSOUT). If the
OUTDD compiler option and the MSGFILE runtime option both specify the same
ddname, the error message information and DISPLAY output directed to the system
logical output device are routed to the same destination.
Restriction: The OUTDD option has no effect under CICS.
344 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Displaying data on the system logical output device on page 36
Coding COBOL programs to run under CICS on page 419
RELATED REFERENCES
Language Environment Programming Reference (MSGFILE)
PGMNAME
The PGMNAME option controls the handling of program-names and entry-point
names.
PGMNAME option syntax
COMPAT
PGMNAME( LONGMIXED )
LONGUPPER
Default is: PGMNAME(COMPAT)
Abbreviations are: PGMN(LM|LU|CO)
LONGUPPER can be abbreviated as UPPER, LU, or U. LONGMIXED can be abbreviated as
MIXED, LM, or M.
PGMNAME controls the handling of names used in the following contexts:
v Program-names defined in the PROGRAM-ID paragraph
v Program entry-point names in the ENTRY statement
v Program-name references in:
CALL statements that reference nested programs, statically linked programs, or
DLLs
SET procedure-pointer or function-pointer statements that reference statically
linked programs or DLLs
CANCEL statements that reference nested programs
PGMNAME(COMPAT)
With PGMNAME(COMPAT), program-names are handled in a manner compatible with
older versions of COBOL compilers:
v The program-name can be up to 30 characters in length.
v All the characters used in the name must be alphabetic, digits, the hyphen, or
the underscore, except that if the program-name is a literal and is in the
outermost program, then the literal can also contain the extension characters @,
#, and $, and the first character can be an underscore.
v At least one character must be alphabetic.
v The hyphen cannot be used as the first or last character.
External program-names are processed by the compiler as follows:
v They are folded to uppercase.
Chapter 17. Compiler options 345
v They are truncated to eight characters.
v Hyphens are translated to zero (0).
v If the first character is not alphabetic, and is not an underscore, it is converted as
follows:
1-9 are translated to A-I.
Anything else is translated to J.
PGMNAME(LONGUPPER)
With PGMNAME(LONGUPPER), program-names that are specified in the PROGRAM-ID
paragraph as COBOL user-defined words must follow the normal COBOL rules for
forming a user-defined word:
v The program-name can be up to 30 characters in length.
v All the characters used in the name must be alphabetic, digits, the hyphen, or
the underscore.
v At least one character must be alphabetic.
v The hyphen cannot be used as the first or last character.
v The underscore cannot be used as the first character.
When a program-name is specified as a literal, in either a definition or a reference,
then:
v The program-name can be up to 160 characters in length.
v All the characters used in the name must be alphabetic, digits, the hyphen, or
the underscore.
v At least one character must be alphabetic.
v The hyphen cannot be used as the first or last character.
v The underscore can be used in any position.
External program-names are processed by the compiler as follows:
v They are folded to uppercase.
v Hyphens are translated to zero (0).
v If the first character is not alphabetic, and is not an underscore, it is converted as
follows:
1-9 are translated to A-I.
Anything else is translated to J.
Names of nested programs are folded to uppercase by the compiler but otherwise
are processed as is, without truncation or translation.
PGMNAME(LONGMIXED)
With PGMNAME(LONGMIXED), program-names are processed as is, without truncation,
translation, or folding to uppercase.
With PGMNAME(LONGMIXED), all program-name definitions must be specified using
the literal format of the program-name in the PROGRAM-ID paragraph or ENTRY
statement. The literal user for a program-name can contain any character in the
range X41-XFE.
346 Enterprise COBOL for z/OS, V5.2 Programming Guide
Usage notes
v The following elements are not affected by the PGMNAME option:
Class-names and method-names.
System-names (assignment-names in SELECT . . . ASSIGN, and text-names or
library-names in COPY statements).
Dynamic calls.
Dynamic calls are resolved with truncation of the program-name to eight
characters, folding to uppercase, and translation of embedded hyphens or a
leading digit.
CANCEL of nonnested programs. Name resolution uses the same mechanism as
for a dynamic call.
v Link-edit considerations: COBOL programs that are compiled with the
PGMNAME(LONGUPPER) or PGMNAME(LONGMIXED) option must be link-edited in AMODE
31.
v Dynamic calls are not permitted to COBOL programs compiled with the
PGMNAME(LONGMIXED) or PGMNAME(LONGUPPER) options unless the program-name is
less than or equal to 8 bytes, and all uppercase. In addition, the name of the
program must be identical to the name of the module that contains it.
v When using the extended character set supported by PGMNAME(LONGMIXED), be
| sure to use names that conform to the binder (linkage-editor) or system
conventions that apply, depending on the mechanism used to resolve the names.
Using characters such as commas or parentheses is not recommended, because
| these characters are used in the syntax of binder (linkage-editor) control
statements.
RELATED REFERENCES
PROGRAM-ID paragraph (Enterprise COBOL Language Reference)
| QUALIFY
| QUALIFY affects qualification rules and controls whether to extend qualification
| rules so that some data items that cannot be referenced under COBOL Standard
| rules can be referenced.
| QUALIFY option syntax
| COMPAT
QUALIFY( EXTEND )
|
||
| Default is: QUALIFY(COMPAT)
| Abbreviations are: QUA(C|E)
| QUALIFY(COMPAT)
| If QUALIFY(COMPAT) is in effect, references to data items must be unique.
| QUALIFY(EXTEND)
| If QUALIFY(EXTEND) is in effect, qualification rules are extended so that
| some references that are not unique by COBOL standard rules can be
Chapter 17. Compiler options 347
| unique. If every level in the containing hierarchy of names is specified, the
| set of qualifiers is called a complete set of qualifiers. If there is only one data
| item with a specific complete set of qualifiers, the reference resolves to that
| data item, even if the same set of qualifiers can match with another
| reference as an incomplete set of qualifiers.
| Example
| 01 A.
| 02 B.
| 03 C PIC X.
| 03 A PIC X.
| 02 C PIC X.
| .
| .
| .
| Move space to C of A *> Refers to 02 level C (unique only with QUALIFY(EXTEND))
| Move space to A *> Refers to 01 level A (unique only with QUALIFY(EXTEND))
| Move space to C of B of A *> Refers to 03 level C (unique by COBOL standard rules)
| Move space to C of B *> Refers to 03 level C (unique by COBOL standard rules)
|
QUOTE/APOST
Use QUOTE if you want the figurative constant [ALL] QUOTE or [ALL] QUOTES to
represent one or more quotation mark (") characters. Use APOST if you want the
figurative constant [ALL] QUOTE or [ALL] QUOTES to represent one or more single
quotation mark (') characters.
QUOTE/APOST option syntax
QUOTE
APOST
Default is: QUOTE
Abbreviations are: Q|APOST
Delimiters: You can use either quotation marks or single quotation marks as literal
delimiters regardless of whether the APOST or QUOTE option is in effect. The
delimiter character used as the opening delimiter for a literal must be used as the
closing delimiter for that literal.
RENT
A program compiled as RENT is generated as a reentrant object program. A program
compiled as NORENT is generated as a nonreentrant object program.
Either a reentrant or a nonreentrant program can be invoked as a main program or
as a subprogram.
348 Enterprise COBOL for z/OS, V5.2 Programming Guide
RENT option syntax
RENT
NORENT
Default is: RENT
Abbreviations are: None
DATA and RMODE settings: The RENT option interacts with other compiler options that
affect storage and its addressability. Use the DATA(24|31) option for reentrant
programs to control whether dynamic data areas are allocated in unrestricted
storage or in storage obtained from below 16 MB. Compile programs with RENT if
they will be run in virtual storage addresses above 16 MB.
Execution of nonreentrant programs above 16 MB is not supported. Programs
compiled with NORENT must be RMODE 24.
The setting of the DATA option does not affect programs compiled with NORENT.
For information about which Enterprise COBOL programs need to be reentrant, see
the related task about making programs reentrant.
| Link-edit considerations: If all programs in a program object are compiled with
| RENT, it is recommended that the program object be link-edited with the RENT
| binder (linkage-editor) option. Use the REUS binder (linkage-editor) option instead
| if the program object will also contain any non-COBOL programs that are only
serially reusable.
| If any program in a program object is not reentrant, the program object must not
| be link-edited with the RENT or REUS link-edit attributes. The NOREUS binder
| (linkage-editor) option is needed to ensure that the CANCEL statement will guarantee
a fresh copy of the program on a subsequent CALL.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Making programs reentrant on page 480
DB2 Application Programming and SQL Guide (Using reentrant code)
RELATED REFERENCES
Conflicting compiler options on page 304
RMODE
RMODE
The RMODE setting influences the RMODE (residency mode) of your generated object
program.
Chapter 17. Compiler options 349
RMODE option syntax
AUTO
RMODE( 24 )
ANY
Default is: AUTO
Abbreviations are: None
A program compiled with the RMODE(AUTO) option will have RMODE 24 if NORENT is
specified, or RMODE ANY if RENT is specified. RMODE AUTO is compatible with older
compilers such as VS COBOL II, which produced RMODE 24 for programs compiled
with NORENT, and RMODE ANY for programs compiled with RENT.
A program compiled with the RMODE(24) option will have RMODE 24 whether NORENT
or RENT is specified.
A program compiled with the RMODE(ANY) option must also be compiled with the
RENT option. The program will have the RMODE ANY attribute.
If the NORENT option is specified, the RMODE(24) or RMODE(AUTO) compiler option
must be specified. Overriding the module RMODE with a binder option or control
statement is not supported.
DATA and RENT: The RMODE option interacts with other compiler options and runtime
options that affect storage and its addressability. For information about passing
data between programs with different modes, see the related concept about storage
and its addressability.
Link-edit considerations: If the object code that COBOL generates has an attribute
of RMODE 24, you must link-edit the code with RMODE 24. If the object code that
COBOL generates has an attribute of RMODE ANY, you can link-edit the code with
either RMODE ANY or RMODE 24.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED REFERENCES
Allocation of buffers for QSAM files on page 181
Conflicting compiler options on page 304
| RULES
| You can use the RULES option to request information about your program from the
| compiler to improve the program by flagging certain types of source code at
| compile time.
350 Enterprise COBOL for z/OS, V5.2 Programming Guide
| RULES option syntax
| NORULES
ENDPERIOD
RULES ( NOENDPERIOD )
EVENPACK
NOEVENPACK
LAXPERF
NOLAXPERF
SLACKBYTES
NOSLACKBYTES
|
||
| Default is: NORULES
| Abbreviations are:
| v ENDP = ENDPERIOD
| v EVENP = EVENPACK
| v LXPRF = LAXPERF
| v SLCKB = SLACKBYTES
| You can specify the following suboptions for RULES:
| ENDPERIOD | NOENDPERIOD
| The default is ENDPERIOD. Specifying NOENDPERIOD causes the compiler to
| issue warning messages when the scope of a conditional statement is
| terminated by a period instead of an explicit scope terminator END-*.
| EVENPACK | NOEVENPACK
| The default is EVENPACK. Specifying NOEVENPACK causes the compiler to issue
| warning messages for any USAGE PACKED-DECIMAL (COMP-3) data
| items that have an even number of digits.
| LAXPERF | NOLAXPERF
| The default is LAXPERF. Specifying NOLAXPERF suboption causes the compiler
| to issue warning messages for usage of inefficient COBOL features. These
| features might include USAGE DISPLAY numeric data items in arithmetic
| statements, large amounts of space padding in MOVE statements, inefficient
| compiler options, and other cases.
| SLACKBYTES | NOSLACKBYTES
| The default is SLACKBYTES. Specifying NOSLACKBYTES causes the compiler to
| issue warning messages for any SYNCHONIZED data items that cause the
| compiler to add slack bytes, either slack bytes within records or slack bytes
| between records. Each data item that causes slack bytes to be added gets a
| compiler diagnostic.
| If the RULES option is specified with no suboptions, the default is
| RULES(ENDPERIOD,EVENPACK,LAXPERF,SLACKBYTES).
| Notes:
| v It is not necessary to specify all of the suboptions for RULES. If a suboption is not
| specified, the default takes effect.
Chapter 17. Compiler options 351
| v You can optionally use the RULES option with the MSGEXIT suboption of the EXIT
| compiler option to enforce local coding standards. For example, if you want to
| ensure that no programmers use periods instead of explicit scope delimiters to
| delimit conditional statements, you can change the severity of the ENDPERIOD
| message from Warning level (RC=4) to Severe level (RC-12). For a sample of
| how to modify the severity of this and other RULES messages, see the sample
| MSGEXIT in SIGYSAMP called IGYMSGXT.
| RELATED REFERENCES
| SYNCHRONIZED clause (Enterprise COBOL Language Reference)
|
SEQUENCE
When you use SEQUENCE, the compiler examines columns 1 through 6 to check that
the source statements are arranged in ascending order according to their EBCDIC
collating sequence. The compiler issues a diagnostic message if any statements are
not in ascending order.
Source statements with blanks in columns 1 through 6 do not participate in this
sequence check and do not result in messages.
SEQUENCE option syntax
SEQUENCE
NOSEQUENCE
Default is: SEQUENCE
Abbreviations are: SEQ|NOSEQ
If you use COPY statements with the SEQUENCE option in effect, be sure that your
source program's sequence fields and the copybook sequence fields are
coordinated.
If you use NUMBER and SEQUENCE, the sequence is checked according to numeric,
rather than EBCDIC, collating sequence.
If you are doing a batch compilation and SEQUENCE is in effect, all programs in the
batch compilation are treated as a single input file. The sequence numbers of the
entire input file must be in ascending order.
Use NOSEQUENCE to suppress this checking and the diagnostic messages.
RELATED TASKS
Finding line sequence problems on page 383
352 Enterprise COBOL for z/OS, V5.2 Programming Guide
| SERVICE
| Use SERVICE to place a string in the object module if the object module is
| generated. If the object module is linked into a program object, the string is loaded
| into memory with this program object. If the Language Environment dump
| includes a traceback, this string is included in that traceback.
| SERVICE option syntax
| NOSERVICE
SERVICE('service string')
|
||
| Default is: NOSERVICE
| Abbreviations are: SERV|NOSERV
| The service string is limited to 64 characters in length.
SOURCE
Use SOURCE to get a listing of your source program. This listing will include any
statements embedded by PROCESS or COPY statements.
SOURCE option syntax
SOURCE
NOSOURCE
Default is: SOURCE
Abbreviations are: S|NOS
You must specify SOURCE if you want embedded messages in the source listing.
Use NOSOURCE to suppress the source code from the compiler output listing.
If you want to limit the SOURCE output, use *CONTROL SOURCE or NOSOURCE
statements in your PROCEDURE DIVISION. Source statements that follow a *CONTROL
NOSOURCE statement are not included in the listing until a subsequent *CONTROL
SOURCE statement switches the output back to normal SOURCE format.
Example: MAP output on page 392
RELATED REFERENCES
*CONTROL (*CBL) statement (Enterprise COBOL Language Reference)
Chapter 17. Compiler options 353
SPACE
Use SPACE to select single-, double-, or triple-spacing in your source code listing.
SPACE option syntax
1
SPACE( 2 )
3
Default is: SPACE(1)
Abbreviations are: None
SPACE has meaning only when the SOURCE compiler option is in effect.
RELATED REFERENCES
SOURCE on page 353
SQL
Use the SQL compiler option to enable the DB2 coprocessor and to specify DB2
suboptions. You must specify the SQL option if a COBOL source program contains
SQL statements (EXEC SQL statements) and the program has not been processed
by the DB2 precompiler.
SQL option syntax
NOSQL
SQL
("DB2-suboption-string")
Default is: NOSQL
Abbreviations are: None
When you use the SQL option, the DB2 coprocessor writes the database request
module (DBRM) to ddname DBRMLIB. DB2 must be available on the machine on
which you compile.
If you specify the NOSQL option, any SQL statements found in the source program
are diagnosed and discarded.
Use either quotation marks or single quotation marks to delimit the string of DB2
suboptions.
354 Enterprise COBOL for z/OS, V5.2 Programming Guide
You can partition a long suboption string into multiple suboption strings in
multiple CBL statements. For example:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL=SQL("string1")
//COBOL.SYSIN DD *
CBL SQL("string2")
CBL SQL(string3)
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
. . .
The DB2 suboptions are concatenated in the order of their appearance. Thus in the
example above, the compiler passes the following suboption string to the DB2
coprocessor:
"string1 string2 string3"
The concatenated strings are delimited with single spaces as shown. If multiple
instances of the same DB2 option are found, the last specification of each option
prevails. The compiler limits the length of the concatenated DB2 suboption string
to 4 KB.
RELATED CONCEPTS
DB2 coprocessor on page 431
COBOL and DB2 CCSID determination on page 437
RELATED TASKS
Compiling with the SQL option on page 435
Separating DB2 suboptions on page 436
RELATED REFERENCES
Conflicting compiler options on page 304
SQLCCSID
Use the SQLCCSID compiler option to control whether the CODEPAGE compiler option
will influence the processing of SQL statements in your COBOL programs.
SQLCCSID option syntax
SQLCCSID
NOSQLCCSID
Default is: SQLCCSID
Abbreviations are: SQLC|NOSQLC
The SQLCCSID option has an effect only if you use the integrated DB2 coprocessor
(SQL compiler option).
If SQLCCSID is in effect, the setting of the CODEPAGE compiler option will influence
the processing of SQL statements within your COBOL programs when you use the
Chapter 17. Compiler options 355
integrated DB2 coprocessor. If NOSQLCCSID is in effect, the CODEPAGE setting will not
influence the processing of SQL statements when you use the integrated DB2
coprocessor; only COBOL statements will be sensitive to the CCSID specified in the
CODEPAGE option.
For further information about this option, see the related task.
RELATED CONCEPTS
DB2 coprocessor on page 431
COBOL and DB2 CCSID determination on page 437
RELATED TASKS
Programming with the SQLCCSID or NOSQLCCSID option on page 438
RELATED REFERENCES
Code-page determination for string host variables in SQL statements on page 437
CODEPAGE on page 313
SQL on page 354
SQLIMS
Use the SQLIMS compiler option to enable the IMS SQL coprocessor and to specify
Information Management System (IMS) suboptions. You must specify the SQLIMS
option if a COBOL source program contains SQLIMS statements (EXEC SQLIMS
statements).
SQLIMS option syntax
NOSQLIMS
SQLIMS
("IMS-suboption-string")
Default: NOSQLIMS
Abbreviation: None
If you specify the NOSQLIMS option, any SQLIMS statements that are found in the
source program are diagnosed and discarded.
Use either double quotation marks or single quotation marks to delimit the string
of IMS suboptions.
You can partition a long suboption string into multiple suboption strings in
multiple CBL statements. For example:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL='SQLIMS("string1")'
//COBOL.SYSIN DD *
CBL SQLIMS("string2")
356 Enterprise COBOL for z/OS, V5.2 Programming Guide
CBL SQLIMS('string3')
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
. . .
The IMS suboptions are concatenated in the order of their appearance. Thus in the
proceeding example, the compiler passes the following suboption strings to the
IMS SQL coprocessor:
"string1 string2 string3"
The concatenated strings are delimited with single spaces as shown. If multiple
instances of the same IMS suboption are found, the last specification of each
suboption takes effect. The compiler limits the length of the concatenated IMS
suboption string to 4 KB.
RELATED CONCEPTS
IMS SQL coprocessor on page 443
RELATED TASKS
Compiling with the SQLIMS option on page 445
Separating IMS suboptions on page 446
RELATED REFERENCES
Conflicting compiler options on page 304
SSRANGE
Use SSRANGE to generate code that checks for out-of-range storage references.
SSRANGE option syntax
NOSSRANGE
SSRANGE
Default is: NOSSRANGE
Abbreviations are: SSR|NOSSR
SSRANGE generates code that checks whether subscripts, including ALL subscripts, or
indexes try to reference areas outside the region of their associated tables. Each
subscript or index is not individually checked for validity. Instead, the effective
address is checked to ensure that it does not reference outside the table.
Note: If you specify the SSRANGE option, range checks are generated by the
compiler and the checks are always conducted at run time. You cannot disable the
compiled-in range checks at run time by specifying the runtime option CHECK(OFF).
Variable-length items are also checked to ensure that references are within their
maximum defined length.
Reference modification expressions are checked to ensure that:
Chapter 17. Compiler options 357
v The starting position is greater than or equal to 1.
v The starting position is not greater than the current length of the subject data
item.
v The length value (if specified) is greater than or equal to 1.
v The starting position and length value (if specified) do not reference an area
beyond the end of the subject data item.
If SSRANGE is in effect and an out-of-range condition is detected, an error message is
generated, and the program is terminated.
For unbounded groups or their subordinate items, checking is done only for
reference modification expressions. Subscripted or indexed references to tables
subordinate to an unbounded group are not checked.
RELATED CONCEPTS
Reference modifiers on page 113
RELATED TASKS
Checking for valid ranges on page 383
STGOPT
The STGOPT option controls storage optimization.
STGOPT option syntax
NOSTGOPT
STGOPT
Default is: NOSTGOPT
Abbreviations are: SO, NOSO
If you specify STGOPT, the compiler might discard any or all of the following data
items, and does not allocate storage for them.
v Unreferenced LOCAL-STORAGE and non-external WORKING-STORAGE level-77 and
level-01 elementary data items
v Non-external level-01 group items if none of their subordinate items are
referenced
v Unreferenced special registers
| Note: The STGOPT option is ignored for data items that have the VOLATILE
| clause. For details, see VOLATILE clause in the Enterprise COBOL Language
| Reference.
| The compiler will not generate code to initialize discarded data items to the values
in their VALUE clauses.
In addition, with STGOPT, data items in the LOCAL-STORAGE SECTION can be
reordered in memory to optimize performance.
358 Enterprise COBOL for z/OS, V5.2 Programming Guide
TERMINAL
Use TERMINAL to send progress and diagnostic messages to the SYSTERM ddname.
TERMINAL option syntax
NOTERMINAL
TERMINAL
Default is: NOTERMINAL
Abbreviations are: TERM|NOTERM
Use NOTERMINAL if you do not want this additional output.
TEST
Use TEST to produce object code that enables debugging and problem
determination tools such as Debug Tool and Fault Analyzer. With TEST, you can
also enable the inclusion of symbolic variables in the formatted dumps that are
produced by Language Environment.
TEST option syntax
NODWARF
NOTEST
DWARF
NOEJPD SOURCE
TEST
EJPD NOSOURCE
Option default is: NOTEST(NODWARF)
Suboption defaults are:
v NODWARF if only NOTEST is specified
v NOEJPD,SOURCE if only TEST is specified
Abbreviations are: None
Suboption abbreviation is: NOS | S
NOTEST suboptions
DWARF If you specify NOTEST(DWARF), basic DWARF diagnostic information is
included in the application module. This option enables the best usability
for application failure analysis tools, such as CEEDUMP and IBM Fault
Chapter 17. Compiler options 359
Analyzer. With NOTEST(DWARF), the debugging information is a subset of
the DWARF information that is available with TEST.
Debugging information generated by the compiler is in the
industry-standard DWARF format. For more information about DWARF,
see About Common Debug Architecture in the DWARF/ELF Extensions Library
Reference.
NODWARF
If you specify NOTEST(NODWARF), DWARF diagnostic information is not
included in the application module.
TEST suboptions
When the TEST option is specified, DWARF debugging information is included in the
application module.
The EJPD and NOEJPD suboptions control enablement of the Debug Tool commands
JUMPTO and GOTO in production debugging sessions. These suboptions take effect
only if you specify the TEST option and a non-zero OPTIMIZE level (OPTIMIZE(1) or
OPTIMIZE(2)).
EJPD If you specify TEST(EJPD) and a non-zero OPTIMIZE level:
v The JUMPTO and GOTO commands are enabled.
v The amount of program optimization is reduced. Optimization is done
within statements, but most optimizations do not cross statement
boundaries.
NOEJPD If you specify TEST(NOEJPD) and a non-zero OPTIMIZE level:
v The JUMPTO and GOTO commands are not enabled. However, you can still
use JUMPTO and GOTO if you use the SET WARNING OFF Debug Tool
command. In this scenario, JUMPTO and GOTO will have unpredictable
results.
v The normal amount of program optimization is done.
SOURCE If you specify TEST(SOURCE), the generated DWARF debug information
generated by the compiler includes the expanded source code, and the
compiler listing is not needed by IBM Debug Tool.
NOSOURCE
If you specify TEST(NOSOURCE), the generated DWARF debugging information
does not include the expanded source code, and you will need access to
the compiler listing to use IBM Debug Tool.
Note: If you specify the TEST option, you must set the CODEPAGE option to the
CCSID that is used for the COBOL source program. In particular, programs that
use Japanese characters in DBCS literals or DBCS user-defined words must be
compiled with the CODEPAGE option set to a Japanese codepage CCSID. For more
information, see CODEPAGE on page 313.
Performance versus debugging capability:
You can control the amount of debugging capability that you get and so also the
program performance, as follows:
v For the best performance, but with some restrictions on debugging, compile
using a non-zero OPTIMIZE level, STGOPT and TEST(NOEJPD).
360 Enterprise COBOL for z/OS, V5.2 Programming Guide
The Debug Tool commands JUMPTO and GOTO are not supported. However, you
can still use JUMPTO and GOTO if you use the SET WARNING OFF Debug Tool
command. In this scenario, JUMPTO and GOTO will have unpredictable results.
Except for the DESCRIBE ATTRIBUTES command, Debug Tool commands cannot
refer to any data item that was discarded from a program by the STGOPT
option.
The Debug Tool command AT CALL entry-name is not supported.
v For some reduction in program performance from the production-debugging
scenario above, but to enable predictable behavior for the Debug Tool commands
JUMPTO and GOTO, specify a non-zero OPTIMIZE level and TEST(EJPD).
The restrictions above about referring to items discarded by the STGOPT option,
and about the AT CALL command also apply when you use a non-zero OPTIMIZE
level and TEST(EJPD).
v For slowest performance but maximum debugging capability, specify
OPTIMIZE(0), NOSTGOPT and TEST.
The OPTIMIZE(0) option causes the compiler to generate slower code, but all
Debug Tool commands are supported.
Language Environment:
The TEST option specified with any of its suboptions can improve your formatted
dumps from Language Environment by adding these two features to the dumps:
v A line number that indicates the failing statement, rather than just an offset
v The values of the program variables
With NOTEST(DWARF), the dump will have program variables but will not have the
line number of the failing statement. With NOTEST(NODWARF), the dump will not
have program variables nor the line number of the failing statement.
Enterprise COBOL uses the Language Environment-provided dump services to
produce dumps that are consistent in content and format with those that are
produced by other Language Environment-conforming member languages.
Whether Language Environment produces a dump for unhandled conditions
depends on the setting of the runtime option TERMTHDACT. If you specify
TERMTHDACT(DUMP), a dump is generated when a condition of severity 2 or greater
goes unhandled.
RELATED CONCEPTS
DWARF/ELF Extensions Library Reference (About Common Debug
Architecture)
RELATED TASKS
Using the debugger on page 387
Language Environment Debugging Guide (Generating a
Language Environment dump with TERMTHDACT)
Debug Tool User's Guide (Special considerations while using the TEST
runtime option)
RELATED REFERENCES
Logical record length and block size on page 268
cob2 input and output files on page 288
Conflicting compiler options on page 304
Chapter 17. Compiler options 361
OPTIMIZE on page 343
Language Environment Programming Reference (TEST | NOTEST)
THREAD
THREAD indicates that a COBOL program is to be enabled for execution in a
Language Environment enclave that has multiple POSIX threads or PL/I tasks.
THREAD option syntax
NOTHREAD
THREAD
Default is: NOTHREAD
Abbreviations are: None
A program that has been compiled using the THREAD option can also be used in a
nonthreaded application. However, if a COBOL program is to be run in a threaded
application, all the COBOL programs in the Language Environment enclave must
be compiled using the THREAD option.
NOTHREAD indicates that the COBOL program is not to be enabled for execution in
an enclave that has multiple POSIX threads or PL/I tasks.
Programs that are compiled using compilers earlier than Enterprise COBOL are
treated as if compiled using NOTHREAD.
If the THREAD option is in effect, the following elements are not supported. If
encountered, they are diagnosed as errors:
v ALTER statement
v DEBUG-ITEM special register
v GO TO statement without procedure-name
v INITIAL phrase in PROGRAM-ID clause
v Nested programs
v RERUN
v Segmentation module
v SORT or MERGE statements
v STOP literal statement
v USE FOR DEBUGGING statement
Additionally, some language constructs have different semantics than in the
nonthreaded case.
Although threaded applications are subject to a number of programming and
environment restrictions, the use of a program in nonthreaded applications is not
so restricted. For example, a program compiled using the THREAD option can run in
the CICS and IMS environments, can run AMODE 24, and can call and be called by
362 Enterprise COBOL for z/OS, V5.2 Programming Guide
other programs that are not enabled for multithreading, provided that the
application does not contain multiple POSIX threads or PL/I tasks at run time.
Programs compiled using the THREAD option are supported in the reusable
environment that is created by calling the Language Environment preinitialization
routine CEEPIPI. But a reusable environment created by using the RTEREUS runtime
option is not supported for programs compiled using the THREAD option.
Performance consideration: If you use the THREAD option, you can expect some
runtime performance degradation due to the overhead of serialization logic that is
automatically generated.
RELATED TASKS
Chapter 27, Preparing COBOL programs for multithreading, on page 507
RELATED REFERENCES
Conflicting compiler options on page 304
TRUNC
TRUNC affects the way that binary data is truncated during moves and arithmetic
operations.
TRUNC option syntax
STD
TRUNC( OPT )
BIN
Default is: TRUNC(STD)
Abbreviations are: None
TRUNC has no effect on COMP-5 data items; COMP-5 items are handled as if
TRUNC(BIN) is in effect regardless of the TRUNC suboption specified.
TRUNC(STD)
TRUNC(STD) applies only to USAGE BINARY receiving fields in MOVE statements
and arithmetic expressions. When TRUNC(STD) is in effect, the final result of
an arithmetic expression, or the sending field in the MOVE statement, is
truncated to the number of digits in the PICTURE clause of the BINARY
receiving field.
TRUNC(OPT)
TRUNC(OPT) is a performance option. When TRUNC(OPT) is in effect, the
compiler assumes that data conforms to PICTURE specifications in USAGE
BINARY receiving fields in MOVE statements and arithmetic expressions. The
results are manipulated in the most optimal way, either truncating to the
number of digits in the PICTURE clause, or to the size of the binary field in
storage (halfword, fullword, or doubleword).
Tips:
Chapter 17. Compiler options 363
v Use the TRUNC(OPT) option only if you are sure that the data being
moved into the binary areas will not have a value with larger precision
than that defined by the PICTURE clause for the binary item. Otherwise,
unpredictable results could occur. This truncation is performed in the
most efficient manner possible; therefore, the results are dependent on
the particular code sequence generated. It is not possible to predict the
truncation without seeing the code sequence generated for a particular
statement.
TRUNC(BIN)
The TRUNC(BIN) option applies to all COBOL language that processes USAGE
BINARY data. When TRUNC(BIN) is in effect, all binary items (USAGE COMP,
COMP-4, or BINARY) are handled as native hardware binary items, that is, as
if they were each individually declared USAGE COMP-5:
v BINARY receiving fields are truncated only at halfword, fullword, or
doubleword boundaries.
v BINARY sending fields are handled as halfwords, fullwords, or
doublewords when the receiver is numeric; TRUNC(BIN) has no effect
when the receiver is not numeric.
v The full binary content of fields is significant.
v DISPLAY will convert the entire content of binary fields with no
truncation.
Recommendations: TRUNC(BIN) is the recommended option for programs
that use binary values set by other products. Other products, such as IMS,
DB2, C/C++, FORTRAN, and PL/I, might place values in COBOL binary
data items that do not conform to the PICTURE clause of the data items. You
can use TRUNC(OPT) with CICS programs provided that your data conforms
to the PICTURE clause for your BINARY data items.
USAGE COMP-5 has the effect of applying TRUNC(BIN) behavior to individual
data items. Therefore, you can avoid the performance overhead of using
TRUNC(BIN) for every binary data item by specifying COMP-5 on only some
of the binary data items, such as those data items that are passed to
non-COBOL programs or other products and subsystems. The use of
COMP-5 is not affected by the TRUNC suboption in effect.
Large literals in VALUE clauses: When you use the compiler option
TRUNC(BIN), numeric literals specified in VALUE clauses for binary data
items (COMP, COMP-4, or BINARY) can generally contain a value of magnitude
up to the capacity of the native binary representation (2, 4, or 8 bytes)
rather than being limited to the value implied by the number of 9s in the
PICTURE clause.
TRUNC example 1
01 BIN-VAR PIC S99 USAGE BINARY.
. . .
MOVE 123451 to BIN-VAR
The following table shows values of the data items after the MOVE statement.
Data item Decimal Hex Display
Sender 123451 00|01|E2|3B 123451
Receiver TRUNC(STD) 51 00|33 51
Receiver TRUNC(OPT) -7621 E2|3B 2J
364 Enterprise COBOL for z/OS, V5.2 Programming Guide
Data item Decimal Hex Display
Receiver TRUNC(BIN) -7621 E2|3B 762J
A halfword of storage is allocated for BIN-VAR. The result of this MOVE statement if
the program is compiled with the TRUNC(STD) option is 51; the field is truncated to
conform to the PICTURE clause.
If you compile the program with TRUNC(BIN), the result of the MOVE statement is
-7621. The reason for the unusual result is that nonzero high-order digits are
truncated. Here, the generated code sequence would merely move the lower
halfword quantity X'E23B' to the receiver. Because the new truncated value
overflows into the sign bit of the binary halfword, the value becomes a negative
number.
It is better not to compile this MOVE statement with TRUNC(OPT), because 123451 has
greater precision than the PICTURE clause for BIN-VAR. With TRUNC(OPT), the results
are again -7621. This is because the best performance was obtained by not doing a
decimal truncation.
TRUNC example 2
01 BIN-VAR PIC 9(6) USAGE BINARY
. . .
MOVE 1234567891 to BIN-VAR
The following table shows values of the data items after the MOVE statement.
Data item Decimal Hex Display
Sender 1234567891 49|96|02|D3 1234567891
Receiver TRUNC(STD) 567891 00|08|AA|53 567891
Receiver TRUNC(OPT) 567891 53|AA|08|00 567891
Receiver TRUNC(BIN) 1234567891 49|96|02|D3 1234567891
When you specify TRUNC(STD), the sending data is truncated to six integer digits to
conform to the PICTURE clause of the BINARY receiver.
When you specify TRUNC(OPT), the compiler assumes the sending data is not larger
than the PICTURE clause precision of the BINARY receiver. The most efficient code
sequence in this case is truncation as if TRUNC(STD) were in effect.
When you specify TRUNC(BIN), no truncation occurs because all of the sending data
fits into the binary fullword allocated for BIN-VAR.
RELATED CONCEPTS
Formats for numeric data on page 47
RELATED TASKS
Compiling with the CICS option on page 423
RELATED REFERENCES
VALUE clause (Enterprise COBOL Language Reference)
Chapter 17. Compiler options 365
VBREF
Use VBREF to get a cross-reference between all verbs used in the source program
and the line numbers in which they are used. VBREF also produces a summary of
the number of times each verb was used in the program.
VBREF option syntax
NOVBREF
VBREF
Default is: NOVBREF
Abbreviations are: None
Use NOVBREF for more efficient compilation.
| VLR
| The VLR option affects the file status returned from READ statements for
| variable-length records when the length of record returned is inconsistent with the
| record descriptions. It eases your migration from earlier versions to Enterprise
| COBOL V5, if your programs have READ statements that result in a record length
| conflict.
| VLR option syntax
| STANDARD
VLR( COMPAT )
|
||
| Default is: VLR(STANDARD)
| Abbreviations are: VLR(C|S)
| After the execution of a READ statement:
| v If the number of character positions in the record that is read is less than the
| minimum size specified by the record description entries for the file, the portion
| of the record area that is to the right of the last valid character read is
| undefined.
| v If the number of character positions in the record that is read is greater than the
| maximum size specified by the record description entries for the file, the record
| is truncated on the right to the maximum size.
366 Enterprise COBOL for z/OS, V5.2 Programming Guide
| In either of these cases, the READ statement is successful, and the file 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.
| VLR(COMPAT)
| If you specify VLR(COMPAT), you get the status value of 00 when READ
| statements encounter a record length conflict.
| Note: This setting can hide I/O problems that can arise with the wrong
| length read situation. Use the VLR(COMPAT) option with caution, and check
| for correct READ statements.
| VLR(STANDARD)
| If you specify VLR(STANDARD), you get the status value of 04 when READ
| statements encounter a record length conflict.
| You can add code to test for FS=04 to avoid accessing undefined data in a
| record and also avoid getting protection exceptions for attempting to
| reference a part of the record that was truncated.
| Using VLR(STANDARD) can result in more reliable code and fewer I/O problems
| because the file status will tell you when a wrong length READ might occur. A
| new compiler message, MSGIGYP3178, can also help you avoid I/O problems by
| telling you if a program has a possibility of a wrong length READ. This message
| can be used to assist with migration from VLR(COMPAT) to VLR(STANDARD) by
| indicating the possible wrong length READ that you can solve by correcting the
| File Definition (FD). You can also raise the severity of the message so that the
| program must be corrected in order to run. To do this, use the MSGEXIT suboption
| of the EXIT compiler option to change the severity of message MSGIGYP3178 from
| I (RC=0) to S (RC=12), E (RC=8), or W (RC=4). If you are not interested in seeing
| this message, you can suppress the message completely.
| RELATED REFERENCES
| EXIT on page 324
| Compatible READ results of variable length records - wrong length READ
| (Enterprise COBOL Migration Guide)
|
WORD
Use WORD(xxxx) to specify that an alternate reserved-word table is to be used during
compilation.
WORD option syntax
NOWORD
WORD(xxxx)
Default is: NOWORD
Abbreviations are: WD|NOWD
Chapter 17. Compiler options 367
xxxx specifies the ending characters of the name of the reserved-word table
(IGYCxxxx) to be used in your compilation. IGYC are the first four standard
characters of the name, and xxxx can be one to four characters in length.
Alternate reserved-word tables provide changes to the IBM-supplied default
reserved-word table. Your systems programmer might have created one or more
alternate reserved-word tables for your site. See your systems programmer for the
names of alternate reserved-word tables.
Enterprise COBOL provides an alternate reserved-word table (IGYCCICS)
specifically for CICS applications. It is set up to flag COBOL words not supported
under CICS with an error message. If you want to use this CICS reserved-word
table during your compilation, specify the compiler option WORD(CICS).
RELATED TASKS
Compiling with the CICS option on page 423
RELATED REFERENCES
Conflicting compiler options on page 304
CICS reserved-word table on page 427
| XMLPARSE
| Use XMLPARSE to select the parser to be used for processing XML input, and,
| therefore, the XML processing capabilities that are available to your program.
| XMLPARSE option syntax
| XMLSS
XMLPARSE( COMPAT )
|
||
| Default is: XMLSS
| Abbreviations are: XP(X|C)
| If you specify the XMLPARSE(XMLSS) option, XML PARSE statements are processed
| using the z/OS XML System Services parser. The following XML parsing
| capabilities are available only if you specify XMLPARSE(XMLSS):
| v Validation of XML input documents against an XML schema (by using the
| VALIDATING phrase of the XML PARSE statement)
| v Enhanced namespace processing (special registers XML-NAMESPACE,
| XML-NNAMESPACE, XML-NAMESPACE-PREFIX, and XML-NNAMESPACE-PREFIX)
| v Automatic conversion of document fragments to Unicode UTF-16 (by using the
| RETURNING NATIONAL phrase of the XML PARSE statement)
| v Specification of the encoding of the input document (by using the ENCODING
| phrase of the XML PARSE statement)
| v Direct parsing of XML documents encoded in UTF-8
| v Parsing of XML documents, a buffer of XML at a time
| v Offloading of XML parsing to System z Application Assist Processors (zAAPs)
368 Enterprise COBOL for z/OS, V5.2 Programming Guide
| If you specify the XMLPARSE(COMPAT) option, XML PARSE statements are processed
| using the XML parser that is a built-in component of the COBOL library. The XML
| PARSE statement results and operational behaviors are then compatible with those
| obtained with Enterprise COBOL Version 3, and also with Version 4 when
| XMLPARSE(COMPAT) was used, and the advanced features described above for
| XMLPARSE(XMLSS) are not available.
| RELATED TASKS
| Chapter 28, Processing XML input, on page 517
| RELATED REFERENCES
| XML PARSE statement (Enterprise COBOL Language Reference)
| z/OS XML System Services User's Guide and Reference
|
XREF
Use XREF to produce a sorted cross-reference listing.
XREF option syntax
XREF
FULL
( SHORT )
NOXREF
Default is: XREF(FULL)
Abbreviations are: X|NOX
You can choose XREF, XREF(FULL), or XREF(SHORT). If you specify XREF without any
suboptions, XREF(FULL) will be in effect.
A section of the listing shows all the program-names, data-names, and
procedure-names that are referenced in your program, and the line numbers where
those names are defined. External program-names are identified.
Example: XREF output: data-name cross-references on page 411
Example: XREF output: program-name cross-references on page 412
A section is also included that cross-references COPY or BASIS statements in the
program with the data sets or files from which associated copybooks were
obtained.
Example: XREF output: COPY/BASIS cross-references on page 413
EBCDIC data-names and procedure-names are listed in alphanumeric order. DBCS
data-names and procedure-names are listed based on their physical order in the
program; they are shown before the EBCDIC data-names and procedure-names
unless the DBCSXREF installation option is selected with a DBCS ordering program.
In that case, DBCS data-names and procedure-names are in the order specified by
the DBCS ordering program.
Chapter 17. Compiler options 369
If you use XREF and SOURCE, data-name and procedure-name cross-reference
information is printed on the same line as the original source. Line-number
references or other information appears on the right-hand side of the listing page.
On the right of source lines that reference an intrinsic function, the letters IFN are
printed with the line number of the locations where the function arguments are
defined. Information included in the embedded references lets you know if an
identifier is undefined (UND) or defined more than once (DUP), if items are implicitly
defined (IMP) (such as special registers or figurative constants), or if a
program-name is external (EXT).
If you use XREF and NOSOURCE, you get only the sorted cross-reference listing.
XREF(SHORT) prints only the explicitly referenced data items in the cross-reference
listing. XREF(SHORT) applies to DBCS data-names and procedure-names as well as
to single-byte names.
NOXREF suppresses this listing.
Usage notes
v Group names used in a MOVE CORRESPONDING statement are in the XREF listing.
The elementary names in those groups are also listed.
v In the data-name XREF listing, line numbers that are preceded by the letter M
indicate that the data item is explicitly modified by a statement on that line.
v XREF listings take additional storage.
v If there is more than one data set in your SYSLIB concatenation, in some cases
the COPY/BASIS cross-reference might be incomplete or missing. This loss can
occur if XREF is set only in a CBL or PROCESS statement, and XREFOPT=NO is set as
an installation default or NOXREF is coded in your JCL PARM parameter.
To ensure that the COPY/BASIS cross-reference is complete, either verify with your
system programmer that XREFOPT=FULL or XREFOPT=SHORT is your installation
default, or code the XREF option in your JCL PARM parameter.
RELATED CONCEPTS
Chapter 19, Debugging, on page 377
RELATED TASKS
Getting listings on page 387
RELATED REFERENCES
Language Environment Debugging Guide (COBOL compiler options)
| ZONEDATA
| The ZONEDATA option tells the compiler whether USAGE DISPLAY numeric data items
| (zoned decimal) contain data with valid zone bits for numeric comparisons.
| ZONEDATA option syntax
| PFD
ZONEDATA( MIG )
|
||
370 Enterprise COBOL for z/OS, V5.2 Programming Guide
| Default is: ZONEDATA(PFD)
| Abbreviations are: ZD(PFD)|ZD(MIG)
| Each digit of a valid zoned decimal number is represented by a single byte from
| XF0 through XF9. The 4 high-order bits of each byte are zone bits, and the 4
| low-order bits of each byte contain the value of the digit. The 4 high-order bits of
| the low-order byte for SIGN TRAILING represent the sign of the item. The sign is in
| the high-order byte with SIGN LEADING, or in a separate byte for SIGN IS SEPARATE.
| When ZONEDATA(MIG) is in effect, the compiler generates instructions to do numeric
| comparisons that ignore the zone bits of each digit in zoned decimal data items.
| For example, the zoned decimal value is converted to packed-decimal with a pack
| instruction before the comparison.
| Note: The sign zone must be a valid sign according to the NUMPROC compiler option
| setting. In addition, the low-order byte must have a valid zone (xF) for unsigned
| and signed with either SIGN IS LEADING or SIGN IS SEPARATE.
| When ZONEDATA(PFD) is in effect, the compiler assumes that the zone bits in zoned
| decimal data items are valid, and generates the most efficient code possible to
| make numeric comparisons. For example, the compiler might generate a string
| comparison to avoid numeric conversion.
| In the following example, you can see a data item with an invalid zone code 4 in
| the zone bits in the middle of data item VALUE1, forced in by REDEFINES:
| 77 VALUE0 PIC X(4) VALUE 00 0. <* xF0F040F0
| 77 VALUE1 REDEFINES VALUE0 PIC 9(4).
| PROCEDURE DIVISION.
| IF VALUE1 = ZERO
| DISPLAY ZONEDATA(MIG) is in effect VALUE1
| ELSE
| DISPLAY ZONEDATA(PFD) is in effect VALUE1
| END-IF
| In this example, the test is true in COBOL V4 and earlier if the NUMPROC(MIG)
| option is used, and false for other NUMPROC settings. With COBOL V5.1 (and with
| COBOL V5.2 and ZONEDATA(PFD), the test is true at OPT(0) and false at OPT(1|2).
| With COBOL V5.2 and ZONEDATA(MIG), the test is true at any OPT setting.
| If you were compiling with NUMPROC(MIG) with your previous COBOL compiler,
| and have USAGE DISPLAY numeric data items that contain invalid zone codes for
| numeric comparisons, specify ZONEDATA(MIG) to help migration to COBOL V5. In
| such cases, ZONEDATA(PFD) might give different results for comparisons that use
| USAGE DISPLAY numeric data items from the previous compiler. You can either
| correct data or use ZONEDATA(MIG).
| ZONEDATA(PFD) gives better runtime performance than ZONEDATA(MIG) does.
| ZONEDATA(MIG) disables some of the optimizations that NUMPROC(PFD) can give.
| RELATED REFERENCES
| NUMPROC on page 339
Chapter 17. Compiler options 371
|
ZWB
If you compile using ZWB, the compiler removes the sign from a signed zoned
decimal (DISPLAY) field before comparing this field to an alphanumeric elementary
field during execution.
ZWB option syntax
ZWB
NOZWB
Default is: ZWB
Abbreviations are: None
If the zoned decimal item is a scaled item (that is, it contains the symbol P in its
PICTURE string), comparisons that use the decimal item are not affected by ZWB.
Such items always have their sign removed before the comparison is made to an
alphanumeric field.
ZWB affects how a program runs. The same COBOL program can produce different
results depending on the setting of this option.
Use NOZWB if you want to test input numeric fields for SPACES.
372 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 18. Compiler-directing statements
Several statements help you to direct the compilation of your program.
These are the compiler-directing statements:
BASIS statement
This extended source program library statement provides a complete
COBOL program as the source for a compilation. For rules of formation
and processing, see the description of text-name for the COPY statement.
| CALLINTERFACE directive
| 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.
| The CALLINTERFACE directive can be used only in the procedure
| division and its effect is limited to the current compilation unit.
*CONTROL (*CBL) statement
This compiler-directing statement selectively suppresses or allows output
to be produced. The names *CONTROL and *CBL are synonymous.
COPY statement
COPY statement syntax
COPY text-name
literal-1 OF library-name SUPPRESS
IN literal-2
| .
REPLACING operand-1 BY operand-2
LEADING == partial-word-1 == BY == partial-word-2 ==
TRAILNG
This library statement places prewritten text into a COBOL program.
Neither text-name nor library-name need to be unique within a program.
They can be identical to other user-defined words in the program, except
that they cannot contain the underscore.
The uniqueness of text-name and library-name is determined after the
formation and conversion rules for a system-dependent name have been
applied. If library-name is omitted, SYSLIB is assumed.
Compiling with JCL:
text-name, library-name, and literal-1 and literal-2 are processed as follows:
v The name (which can be from one to 30 characters long) is truncated to
eight characters. Only the first eight characters of text-name and
library-name are used as the identifying name. These eight characters
must be unique within any COBOL library.
v The name is folded to uppercase.
v Hyphens that are not the first or last character are translated to zero (0),
and a warning message is issued.
Copyright IBM Corp. 1991, 2015 373
v If the first character is numeric, then the characters 1-9 are translated to
A-I, zero (0) is converted to J, and a warning message is issued.
For example:
COPY INVOICES1Q
COPY "Company-#Employees" IN Personellib
In the IN/OF phrase, library-name is the ddname that identifies the
partitioned data set to be copied from. Use a DD statement such as in the
following example to define library-name:
//COPYLIB DD DSNAME=ABC.COB,VOLUME=SER=111111,
// DISP=SHR,UNIT=3380
To specify more than one copy library, use either JCL or a combination of
JCL and the IN/OF phrase. Using just JCL, concatenate data sets in your DD
statement for SYSLIB. Alternatively, define multiple DD statements and
include the IN/OF phrase in your COPY statements.
The maximum block size for the copy library depends on the device on
which your data set resides.
Compiling in the z/OS UNIX shell:
When you compile using the cob2 command, copybooks are included from
the z/OS UNIX file system. text-name, library-name, and literal-1 and literal-2
are processed as follows:
v User-defined words are folded to uppercase. Literals are not folded.
Because UNIX is case sensitive, if your file-name is lowercase or mixed
case, you must specify it as a literal.
v If text-name is a literal and library-name is omitted, text-name is used
directly: as a file-name, a relative path name, or an absolute path name
(if the first character is /). For example:
COPY "MyInc"
COPY "x/MyInc"
COPY "/u/user1/MyInc"
v If text-name is a user-defined word, and an environment variable of that
name is defined, the value of the environment variable is used as the
name of the file that contains the copybook.
If an environment variable of that name is not defined, the copybook is
searched for under the following names, in this order:
1. text-name.cpy
2. text-name.CPY
3. text-name.cbl
4. text-name.CBL
5. text-name.cob
6. text-name.COB
7. text-name
v If library-name is a literal, it is treated as the actual path, relative or
absolute, from which to copy file text-name.
v If library-name is a user-defined word, it is treated as an environment
variable. The value of the environment variable is used as the path. If
the environment variable is not set, an error occurs.
v If both library-name and text-name are specified, the compiler forms the
path name for the copybook by concatenating library-name and text-name
374 Enterprise COBOL for z/OS, V5.2 Programming Guide
with a path separator (/) inserted between the two values. For example,
suppose you have the following setting for COPY MYCOPY OF MYLIB:
export MYCOPY=mystuff/today.cpy
export MYLIB=/u/user1
These settings result in:
/u/user1/mystuff/today.cpy
If library-name is an environment variable that identifies the path from
which copybooks are to be copied, use an export command to define
library-name, as in this example:
export COPYLIB=/u/mystuff/copybooks
The name of the environment variable must be uppercase. To specify more
than one copy library, set the environment variable to multiple path names
delimited by colon (:).
If library-name is omitted and text-name is not an absolute path name, the
copybook is searched for in this order:
1. In the current directory
2. In the paths specified on the -I cob2 option
3. In the paths specified in the SYSLIB environment variable
For additional information about the COPY statement, for example, the rules
for text replacement, see the related reference.
DELETE statement
This extended source library statement removes COBOL statements from
the BASIS source program.
EJECT statement
This compiler-directing statement specifies that the next source statement is
to be printed at the top of the next page.
ENTER statement
The statement is treated as a comment.
INSERT statement
This library statement adds COBOL statements to the BASIS source
program.
PROCESS (CBL) statement
This statement, which you place before the IDENTIFICATION DIVISION
header of an outermost program, indicates which compiler options are to
be used during compilation of the program.
REPLACE statement
This statement is used to replace source program text.
SERVICE LABEL statement
This statement is generated by the CICS translator to indicate control flow,
and should be used at the resume point for a call to CEE3SRP. It is not
intended for general use.
SKIP1/2/3 statement
These statements indicate lines to be skipped in the source listing.
TITLE statement
This statement specifies that a title (header) should be printed at the top of
each page of the source listing.
Chapter 18. Compiler-directing statements 375
USE statement
The USE statement provides declaratives to specify these elements:
v Error-handling procedures: EXCEPTION/ERROR
v Debugging lines and sections: DEBUGGING
RELATED TASKS
Changing the header of a source listing on page 5
Specifying compiler options under z/OS on page 272
Specifying compiler options under z/OS UNIX on page 284
Setting environment variables under z/OS UNIX on page 283
Eliminating repetitive coding on page 665
RELATED REFERENCES
cob2 syntax and options on page 287
CALLINTERFACE (Enterprise COBOL Language Reference)
COPY statement (Enterprise COBOL Language Reference)
376 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 19. Debugging
You can choose between two different approaches to determine the cause of
problems in the behavior of your application: source-language debugging or
interactive debugging.
For source-language debugging, COBOL provides several language elements,
compiler options, and listing outputs that make debugging easier.
If the problem with your program is not easily detected and you do not have a
debugger available, you might need to analyze a storage dump of your program.
For interactive debugging, you can use Debug Tool. Debug Tool offers these
productivity enhancements:
v Interactive debugging (in full-screen or line mode), or debugging in batch mode
During an interactive full-screen mode session, you can use Debug Tool's
full-screen services and session panel windows on a 3270 device to debug your
program while it is running.
v COBOL-like commands
For each high-level language supported, commands for coding actions to be
taken at breakpoints are provided in a syntax similar to that programming
language.
v Mixed-language debugging
You can debug an application that contains programs written in a different
language. Debug Tool automatically determines the language of the program or
subprogram being run.
v COBOL-CICS debugging
Debug Tool supports the debugging of CICS applications in both interactive and
batch mode.
v Support for remote debugging
Workstation users can use the IBM Debug Tool Plug-in for Eclipse or the IBM
Problem Determination Tools with Rational Developer for System z for
debugging programs that run on z/OS.
RELATED TASKS
Debugging with source language
Debugging using compiler options on page 382
Using the debugger on page 387
Getting listings on page 387
Debug Tool User's Guide
RELATED REFERENCES
Debug Tool Reference and Messages
Language Environment Debugging Guide (Formatting and analyzing system
dumps, Debugging example COBOL programs)
Debugging with source language
You can use several COBOL language features to pinpoint the cause of a failure in
a program.
Copyright IBM Corp. 1991, 2015 377
If a failing program is part of a large application that is already in production
(precluding source updates), write a small test case to simulate the failing part of
the program. Code debugging features in the test case to help detect these
problems:
v Errors in program logic
v Input-output errors
v Mismatches of data types
v Uninitialized data
v Problems with procedures
RELATED TASKS
Tracing program logic
Finding and handling input-output errors on page 379
Validating data on page 379
Moving, initializing or setting uninitialized data on page 380
Generating information about procedures on page 380
RELATED REFERENCES
Source language debugging (Enterprise COBOL Language Reference)
Tracing program logic
Trace the logic of your program by adding DISPLAY statements.
For example, if you determine that the problem is in an EVALUATE statement or in a
set of nested IF statements, use DISPLAY statements in each path to see the logic
flow. If you determine that the calculation of a numeric value is causing the
problem, use DISPLAY statements to check the value of some interim results.
If you use explicit scope terminators to end statements in your program, the logic
is more apparent and therefore easier to trace.
To determine whether a particular routine started and finished, you might insert
code like this into your program:
DISPLAY "ENTER CHECK PROCEDURE"
.
. (checking procedure routine)
.
DISPLAY "FINISHED CHECK PROCEDURE"
After you are sure that the routine works correctly, disable the DISPLAY statements
in one of two ways:
v Put an asterisk in column 7 of each DISPLAY statement line to convert it to a
comment line.
v Put a D in column 7 of each DISPLAY statement to convert it to a comment line.
When you want to reactivate these statements, include a WITH DEBUGGING MODE
clause in the ENVIRONMENT DIVISION; the D in column 7 is ignored and the
DISPLAY statements are implemented.
Before you put the program into production, delete or disable the debugging aids
you used and recompile the program. The program will run more efficiently and
use less storage.
RELATED CONCEPTS
Scope terminators on page 20
378 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
DISPLAY statement (Enterprise COBOL Language Reference)
Finding and handling input-output errors
File status keys can help you determine whether your program errors are due to
input-output errors occurring on the storage media.
To use file status keys in debugging, check for a nonzero value in the status key
after each input-output statement. If the value is nonzero (as reported in an error
message), look at the coding of the input-output procedures in the program. You
can also include procedures to correct the error based on the value of the status
key.
If you determine that a problem lies in an input-output procedure, include the USE
EXCEPTION/ERROR declarative to help debug the problem. Then, when a file fails to
open, the appropriate EXCEPTION/ERROR declarative is performed. The appropriate
declarative might be a specific one for the file or one provided for the open
attributes INPUT, OUTPUT, I-O, or EXTEND.
Code each USE AFTER STANDARD ERROR statement in a section that follows the
DECLARATIVES keyword in the PROCEDURE DIVISION.
RELATED TASKS
Coding ERROR declaratives on page 244
Using file status keys on page 245
RELATED REFERENCES
File status key (Enterprise COBOL Language Reference)
Validating data
If you suspect that your program is trying to perform arithmetic on nonnumeric
data or is receiving the wrong type of data on an input record, use the class test
(the class condition) to validate the type of data.
You can use the class test to check whether the content of a data item is
ALPHABETIC, ALPHABETIC-LOWER, ALPHABETIC-UPPER, DBCS, KANJI, or NUMERIC. If the
data item is described implicitly or explicitly as USAGE NATIONAL, the class test
checks the national character representation of the characters associated with the
specified character class.
You can use the UVALID intrinsic function to check whether a national data item
contains valid UTF-16 encoded data, or whether an alphanumeric or alphabetic
item contains valid UTF-8 encoded data.
RELATED TASKS
Coding conditional expressions on page 98
Testing for valid DBCS characters on page 151
RELATED REFERENCES
Class condition (Enterprise COBOL Language Reference)
UVALID (Enterprise COBOL Language Reference)
Chapter 19. Debugging 379
Moving, initializing or setting uninitialized data
Use an INITIALIZE or SET statement to initialize a table or data item when you
suspect that a problem might be caused by residual data in those fields.
If the problem happens intermittently and not always with the same data, it could
be that a switch was not initialized but is generally set to the right value (0 or 1)
by chance. By using a SET statement to ensure that the switch is initialized, you
can determine that the uninitialized switch is the cause of the problem or remove
it as a possible cause.
RELATED REFERENCES
INITIALIZE statement (Enterprise COBOL Language Reference)
SET statement (Enterprise COBOL Language Reference)
Generating information about procedures
Generate information about your program or test case and how it is running by
coding the USE FOR DEBUGGING declarative. This declarative lets you include
statements in the program and indicate when they should be performed when you
run your program.
For example, to determine how many times a procedure is run, you could include
a debugging procedure in the USE FOR DEBUGGING declarative and use a counter to
keep track of the number of times that control passes to that procedure. You can
use the counter technique to check items such as these:
v How many times a PERFORM statement runs, and thus whether a particular
routine is being used and whether the control structure is correct
v How many times a loop runs, and thus whether the loop is executing and
whether the number for the loop is accurate
You can use debugging lines or debugging statements or both in your program.
Debugging lines are statements that are identified by a D in column 7. To make
debugging lines in your program active, code the WITH DEBUGGING MODE clause on
the SOURCE-COMPUTER line in the ENVIRONMENT DIVISION. Otherwise debugging lines
are treated as comments.
Debugging statements are the statements that are coded in the DECLARATIVES section
of the PROCEDURE DIVISION. Code each USE FOR DEBUGGING declarative in a separate
section. Code the debugging statements as follows:
v Only in a DECLARATIVES section.
v Following the header USE FOR DEBUGGING.
v Only in the outermost program; they are not valid in nested programs.
Debugging statements are also never triggered by procedures that are contained
in nested programs.
To use debugging statements in your program, you must include the WITH
DEBUGGING MODE clause and use the DEBUG runtime option.
Options restrictions:
v You cannot use the USE FOR DEBUGGING declarative in a program that you
compile with the THREAD option.
Example: USE FOR DEBUGGING on page 381
380 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
SOURCE-COMPUTER paragraph (Enterprise COBOL Language Reference)
Debugging lines (Enterprise COBOL Language Reference)
Debugging sections (Enterprise COBOL Language Reference)
DEBUGGING declarative (Enterprise COBOL Language Reference)
Example: USE FOR DEBUGGING
This example shows the kind of statements that are needed to use a DISPLAY
statement and a USE FOR DEBUGGING declarative to test a program.
The DISPLAY statement writes information to the terminal or to an output data set.
The USE FOR DEBUGGING declarative is used with a counter to show how many
times a routine runs.
Environment Division.
. . .
Data Division.
. . .
Working-Storage Section.
. . . (other entries your program needs)
01 Trace-Msg PIC X(30) Value " Trace for Procedure-Name : ".
01 Total PIC 9(9) Value 1.
. . .
Procedure Division.
Declaratives.
Debug-Declaratives Section.
Use For Debugging On Some-Routine.
Debug-Declaratives-Paragraph.
Display Trace-Msg, Debug-Name, Total.
End Declaratives.
Main-Program Section.
. . . (source program statements)
Perform Some-Routine.
. . . (source program statements)
Stop Run.
Some-Routine.
. . . (whatever statements you need in this paragraph)
Add 1 To Total.
Some-Routine-End.
The DISPLAY statement in the DECLARATIVES SECTION issues this message every time
the procedure Some-Routine runs:
Trace For Procedure-Name : Some-Routine 22
The number at the end of the message, 22, is the value accumulated in the data
item Total; it indicates the number of times Some-Routine has run. The statements
in the debugging declarative are performed before the named procedure runs.
You can also use the DISPLAY statement to trace program execution and show the
flow through the program. You do this by dropping Total from the DISPLAY
statement and changing the USE FOR DEBUGGING declarative in the DECLARATIVES
SECTION to:
USE FOR DEBUGGING ON ALL PROCEDURES.
As a result, a message is displayed before each nondebugging procedure in the
outermost program runs.
Chapter 19. Debugging 381
Debugging using compiler options
You can use certain compiler options to help you find errors in your program, find
various elements in your program, obtain listings, and prepare your program for
debugging.
You can find the following errors by using compiler options (the options are
shown in parentheses):
v Syntax errors such as duplicate data-names (NOCOMPILE)
v Missing sections (SEQUENCE)
v Invalid subscript values (SSRANGE)
You can find the following elements in your program by using compiler options:
v Error messages and locations of the associated errors (FLAG)
v Program entity definitions and references; text-names and library-names from
COPY or BASIS statements, and the associated data sets or files from which
copybooks are obtained (XREF)
v Data items in the DATA DIVISION (MAP)
v Verb references (VBREF)
You can get a copy of your source (SOURCE) or a listing of generated code (LIST).
You prepare your program for debugging by using the TEST compiler option.
RELATED TASKS
Finding coding errors
Finding line sequence problems on page 383
Checking for valid ranges on page 383
Selecting the level of error to be diagnosed on page 384
Finding program entity definitions and references on page 386
Listing data items on page 386
Getting listings on page 387
RELATED REFERENCES
Chapter 17, Compiler options, on page 301
Finding coding errors
Use the NOCOMPILE option to compile conditionally or to only check syntax. When
used with the SOURCE option, NOCOMPILE produces a listing that will help you find
coding mistakes such as missing definitions, improperly defined data items, and
duplicate data-names.
If you are compiling in the TSO foreground, you can send the messages to your
screen by using the TERM compiler option and defining your data set as the
SYSTERM data set.
Checking syntax only: To only check the syntax of your program, and not produce
object code, use NOCOMPILE without a suboption. If you also specify the SOURCE
option, the compiler produces a listing.
When you specify NOCOMPILE, several compiler options are suppressed. See the
related reference below about the COMPILE option for details.
382 Enterprise COBOL for z/OS, V5.2 Programming Guide
Compiling conditionally: To compile conditionally, use NOCOMPILE(x), where x is
one of the severity levels of errors. Your program is compiled if all the errors are of
a lower severity than x. The severity levels that you can use, from highest to
lowest, are S (severe), E (error), and W (warning).
If an error of level x or higher occurs, the compilation stops and your program is
only checked for syntax.
RELATED REFERENCES
COMPILE on page 316
Finding line sequence problems
Use the SEQUENCE compiler option to find statements that are out of sequence.
Breaks in sequence indicate that a section of a source program was moved or
deleted.
When you use SEQUENCE, the compiler checks the source statement numbers to
determine whether they are in ascending sequence. Two asterisks are placed beside
statement numbers that are out of sequence. The total number of these statements
is printed as the first line in the diagnostics after the source listing.
RELATED REFERENCES
SEQUENCE on page 352
Checking for valid ranges
Use the SSRANGE compiler option to check whether addresses fall within proper
ranges.
SSRANGE causes the following addresses to be checked:
v Subscripted or indexed data references: Is the effective address of the specified
table element within the maximum boundary of the containing group? (This
checking is not done for UNBOUNDED tables and groups.)
v Variable-length data references (a reference to a data item that contains an
OCCURS DEPENDING ON clause): Is the actual length greater than or equal to zero,
and within the maximum defined length for the group data item? (This checking
is not done for UNBOUNDED groups.)
v Reference-modified data references: Are the offset and length positive? Is the
sum of the offset and length within the maximum length for the data item?
If the SSRANGE option is in effect, checking is performed at run time if the COBOL
statement that contains the indexed, subscripted, variable-length, or
reference-modified data item is executed.
If an effective address is outside the range of the data item that contains the
referenced data, an error message is generated and the program stops. The
message identifies the table or identifier that was referenced and the line number
where the error occurred. Additional information is provided depending on the
type of reference that caused the error.
If all subscripts, indices, and reference modifiers in a given data reference are
literals and they result in a reference outside the data item, the error is diagnosed
at compile time regardless of the setting of the SSRANGE option.
Chapter 19. Debugging 383
Performance consideration: SSRANGE can somewhat degrade performance because
of the extra overhead to check each subscripted or indexed item.
RELATED REFERENCES
SSRANGE on page 357
Performance-related compiler options on page 659
Selecting the level of error to be diagnosed
Use the FLAG compiler option to specify the level of error to be diagnosed during
compilation and to indicate whether error messages are to be embedded in the
listing. Use FLAG(I) or FLAG(I,I) to be notified of all errors.
Specify as the first parameter the lowest severity level of the syntax-error messages
to be issued. Optionally specify the second parameter as the lowest level of the
syntax-error messages to be embedded in the source listing. This severity level
must be the same or higher than the level for the first parameter. If you specify
both parameters, you must also specify the SOURCE compiler option.
Table 49. Severity levels of compiler messages
Severity level Resulting messages
U (unrecoverable) U messages only
S (severe) All S and U messages
E (error) All E, S, and U messages
W (warning) All W, E, S, and U messages
I (informational) All messages
When you specify the second parameter, each syntax-error message (except a
U-level message) is embedded in the source listing at the point where the compiler
had enough information to detect that error. All embedded messages (except those
issued by the library compiler phase) directly follow the statement to which they
refer. The number of the statement that had the error is also included with the
message. Embedded messages are repeated with the rest of the diagnostic
messages at the end of the source listing.
Note: You can suppress some error messages and change the severity of others
with the MSGEXIT suboption of the EXIT option.
When you specify the NOSOURCE compiler option, the syntax-error messages are
included only at the end of the listing. Messages for unrecoverable errors are not
embedded in the source listing, because an error of this severity terminates the
compilation.
Example: embedded messages on page 385
RELATED TASKS
Generating a list of compiler messages on page 280
RELATED REFERENCES
Severity codes for compiler diagnostic messages on page 282
Messages and listings for compiler-detected errors on page 280
FLAG on page 327
384 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: embedded messages
The following example shows the embedded messages generated by specifying a
second parameter to the FLAG option. Some messages in the summary apply to
more than one COBOL statement.
LineID PL SL ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|--+----8 Map and Cross Reference
...
090671** /
090672** *****************************************************************
090673** *** I N I T I A L I Z E P A R A G R A P H **
090674** *** Open files. Accept date, time and format header lines. **
090675** *** Load location-table. **
090676** *****************************************************************
090677** 100-initialize-paragraph.
090678** move spaces to ws-transaction-record IMP 331
090679** move spaces to ws-commuter-record IMP 307
090680** move zeroes to commuter-zipcode IMP 318
090681** move zeroes to commuter-home-phone IMP 319
090682** move zeroes to commuter-work-phone IMP 320
090683** move zeroes to commuter-update-date IMP 324
090684** open input update-transaction-file 204
==090684==> IGYPS2052-S An error was found in the definition of file "LOCATION-FILE". The
reference to this file was discarded.
090685** location-file 193
090686** i-o commuter-file 181
090687** output print-file 217
090688** if commuter-file-status not = "00" and not = "97" 241
090689** 1 display "100-OPEN"
090690** 1 move 100 to comp-code 231
090691** 1 perform 500-vsam-error 91069
090692** 1 perform 900-abnormal-termination 91114
090693** end-if
090694** accept ws-date from date UND
==090694==> IGYPS2121-S "WS-DATE" was not defined as a data-name. The statement was discarded.
090695** move corr ws-date to header-date UND 455
==090695==> IGYPS2121-S "WS-DATE" was not defined as a data-name. The statement was discarded.
090696** accept ws-time from time UND
==090696==> IGYPS2121-S "WS-TIME" was not defined as a data-name. The statement was discarded.
090697** move corr ws-time to header-time UND 449
==090697==> IGYPS2121-S "WS-TIME" was not defined as a data-name. The statement was discarded.
090698** read location-file 193
==090698==> IGYPS2053-S An error was found in the definition of file "LOCATION-FILE". This
input/output statement was discarded.
090699** at end
090700** 1 set location-eof to true 256
090701** end-read
...
LineID Message code Message text
IGYSC0090-W 1700 sequence errors were found in this program.
IGYSC3002-I A severe error was found in the program. The "OPTIMIZE" compiler option was cancelled.
160 IGYDS1089-S "ASSIGNN" was invalid. Scanning was resumed at the next area "A" item, level-number, or
the start of the next clause.
193 IGYGR1207-S The "ASSIGN" clause was missing or invalid in the "SELECT" entry for file "LOCATION-FILE".
The file definition was discarded.
269 IGYDS1066-S "REDEFINES" object "WS-DATE" was not the immediately preceding level-1 data item.
The "REDEFINES" clause was discarded.
90602 IGYPS2052-S An error was found in the definition of file "LOCATION-FILE". The reference to this file
was discarded. Same message on line: 90684
90694 IGYPS2121-S "WS-DATE" was not defined as a data-name. The statement was discarded.
Same message on line: 90695
90696 IGYPS2121-S "WS-TIME" was not defined as a data-name. The statement was discarded.
Same message on line: 90697
90698 IGYPS2053-S An error was found in the definition of file "LOCATION-FILE". This input/output statement
was discarded. Same message on line: 90709
Messages Total Informational Warning Error Severe Terminating
Printed: 13 1 1 11
* Statistics for COBOL program IGYTCARA:
* Source records = 1755
* Data Division statements = 295
* Procedure Division statements = 479
* Generated COBOL statements = 0
* Program complexity factor = 486
End of compilation 1, program IGYTCARA, highest severity 12.
Return code 12
Chapter 19. Debugging 385
Finding program entity definitions and references
Use the XREF(FULL) compiler option to find out where a data-name,
procedure-name, or program-name is defined and referenced. Use it also to
produce a cross-reference of COPY or BASIS statements to the data sets or files from
which copybooks were obtained.
A sorted cross-reference includes the line number where the data-name,
procedure-name, or program-name was defined and the line numbers of all
references to it.
To include only the explicitly referenced data items, use the XREF(SHORT) option.
Use both the XREF (either FULL or SHORT) and the SOURCE options to print a modified
cross-reference to the right of the source listing. This embedded cross-reference
shows the line number where the data-name or procedure-name was defined.
For further details, see the related reference about the XREF compiler option.
Example: XREF output: data-name cross-references on page 411
Example: XREF output: program-name cross-references on page 412
Example: XREF output: COPY/BASIS cross-references on page 413
Example: XREF output: embedded cross-reference on page 414
RELATED TASKS
Getting listings on page 387
RELATED REFERENCES
XREF on page 369
Listing data items
| Use the MAP(HEX|DEC) compiler option to create a listing of the DATA DIVISION items
and all implicitly declared items. Use the MAP output to locate the contents of a
data item in a system dump.
| When you specify the MAP(HEX|DEC) option, an embedded MAP summary that
contains condensed MAP information is generated to the right of the COBOL source
| data definition.
| v If you specify MAP(HEX) or MAP with no suboption, data item offsets within
| groups will be in hexadecimal notation.
| v If you specify MAP(DEC), data item offsets within groups will be in decimal
| notation.
When both XREF data and an embedded MAP summary are on the same line, the
embedded summary is printed first.
You can select or inhibit parts of the MAP listing and embedded MAP summary by
using *CONTROL MAP|NOMAP (or *CBL MAP|NOMAP) statements throughout the source.
For example:
*CONTROL NOMAP
01 A
02 B
*CONTROL MAP
Example: MAP output on page 392
386 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Getting listings
RELATED REFERENCES
MAP on page 333
Using the debugger
You can use Debug Tool to debug your Enterprise COBOL programs. Use the TEST
compiler option to prepare your COBOL program so that you can step through the
executable program with the debugger.
For remote debugging, there is an Eclipse plugin that provides a client graphical
user interface to the debugging information provided by the Debug Tool engine
running under z/OS or z/OS UNIX. The IBM Debug Tool Plug-in for Eclipse is
included with Rational Developer for System z and also with the IBM Problem
Determination Tools Studio.
You can specify the TEST suboption NOSOURCE to have smaller object programs
stored on disk. The loaded size does not change, the debug information is never
loaded unless requested, for example, by a debugger such as Debug Tool or by LE
(for CEEDUMP). With the NOSOURCE suboption, the compiler listing will be required
at debug time for the Debug Tool source window.
Specify the OPTIMIZE(0), NOSTGOPT and TEST compiler options to get the most
debugging function.
Specify a non-zero OPTIMIZE level, NOSTGOPT and TEST(EJPD) compiler options to
get better performance with a few restrictions on debugging function.
Specify a non-zero OPTIMIZE level, STGOPT and TEST(NOEJPD) compiler options to
get the best performance but still be able to use Debug Tool, with some restrictions
on debugging function.
For details about which compiler options to use for maximum debugging
capability versus best performance, see the related reference about the TEST
compiler option.
RELATED TASKS
Debug Tool User's Guide (Preparing your program for debugging)
RELATED REFERENCES
TEST on page 359
Getting listings
Get the information that you need for debugging by requesting the appropriate
compiler listing with the use of compiler options.
Attention: The listings produced by the compiler are not a programming interface
and are subject to change.
Chapter 19. Debugging 387
Table 50. Using compiler options to get listings
Use Listing Contents Compiler option
To check a list of the Short listing v List of options in effect NOSOURCE, NOXREF, NOVBREF,
options in effect for the for the program NOMAP, NOOFFSET, NOLIST
program, statistics about
v Statistics about the
the content of the program,
content of the program
and diagnostic messages
about the compilation v Diagnostic messages
about the compilation1
To aid in testing and Source listing Copy of your source SOURCE on page 353
debugging your program;
to have a record after the
program has been
debugged
To find certain data items Map of DATA DIVISION All DATA DIVISION items MAP on page 3332
in a storage dump; to see items and all implicitly declared
the final storage allocation items
after reentrancy or
optimization has been Embedded map summary
accounted for; to see where (in the right margin of the
programs are defined and listing for lines in the DATA
check their attributes DIVISION that contain data
declarations)
Nested program map (if the
program contains nested
programs)
To find where a name is Sorted cross-reference Data-names, XREF on page 3692,3
defined, referenced, or listing of names; sorted procedure-names, and
modified; to determine the cross-reference listing of program-names; references
context (such as whether a COPY/BASIS statements and to these names
verb was used in a PERFORM copybook data sets or files
block) in which a procedure COPY/BASIS text-names and
is referenced; to determine library names, and the data
the data set or file from sets or files from which
which a copybook was associated copybooks were
obtained obtained
Embedded modified
cross-reference provides
line numbers where
data-names and
procedure-names were
defined
To find the failing verb in a PROCEDURE DIVISION code Generated code LIST on page 3332,4
program or the address in and assembler code
storage of a data item that produced by the compiler3
is moved while the
program is running
To verify you still have a Condensed PROCEDURE Condensed verb listing, OFFSET on page 341
valid logic path after you DIVISION listing global tables,
move or add PROCEDURE WORKING-STORAGE
DIVISION sections information, and literals
To find an instance of a Alphabetic listing of verbs Each verb used, number of VBREF on page 366
certain verb times each verb was used,
line numbers where each
verb was used
388 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 50. Using compiler options to get listings (continued)
Use Listing Contents Compiler option
1. To eliminate messages, turn off the options (such as FLAG) that govern the level of compile diagnostic
information. You can also selectively suppress messages by using the MSGEXIT suboption of the EXIT compiler
option.
2. To use your line numbers in the compiled program, use the NUMBER compiler option. The compiler checks the
sequence of your source statement line numbers in columns 1 through 6 as the statements are read in. When it
finds a line number out of sequence, the compiler assigns to it a number with a value one higher than the line
number of the preceding statement. The new value is flagged with two asterisks. A diagnostic message
indicating an out-of-sequence error is included in the compilation listing.
3. The context of the procedure reference is indicated by the characters preceding the line number.
4. You can control the listing of generated object code by selectively placing *CONTROL LIST and *CONTROL NOLIST
(or equivalently, *CBL LIST and *CBL NOLIST) statements in your source. Note that the *CONTROL statement is
different than the PROCESS (or CBL) statement.
The output is generated if:
v You specify the COMPILE option (or the NOCOMPILE(x) option is in effect and an error level x or higher does not
occur).
v You do not specify the OFFSET option. OFFSET and LIST are mutually exclusive options with OFFSET taking
precedence.
Example: short listing
Example: SOURCE and NUMBER output on page 391
Example: MAP output on page 392
Example: embedded map summary on page 394
Example: nested program map on page 397
Example: XREF output: data-name cross-references on page 411
Example: XREF output: program-name cross-references on page 412
Example: XREF output: COPY/BASIS cross-references on page 413
Example: XREF output: embedded cross-reference on page 414
Example: OFFSET compiler output on page 415
Example: VBREF compiler output on page 415
RELATED TASKS
Generating a list of compiler messages on page 280
Reading LIST output on page 397
Language Environment Debugging Guide (Debugging COBOL programs)
RELATED REFERENCES
Messages and listings for compiler-detected errors on page 280
Example: short listing
The parenthetical numbers shown in the listing below correspond to numbered
explanations that follow the listing. For illustrative purposes, some errors that
cause diagnostic messages were deliberately introduced.
Invocation parameters: (1)
OPTFILE
PROCESS(CBL) statements: (2)
CBL NODECK
CBL NOADV,NODYN,NONAME,NONUMBER,QUOTE,SEQ,DUMP
CBL NOSOURCE, NOXREF, NOVBREF, NOMAP, NOOFFSET, NOLIST
Options from SYSOPTF: (3)
C,NODU,FLAG(I),X,MAP,NOLIST,RENT,OPT(1),SSR
TEST TRUNC(OPT)
Options in effect: (4)
NOADATA
NOADV
AFP(VOLATILE)
Chapter 19. Debugging 389
QUOTE
| ARCH(7)
ARITH(COMPAT)
NOAWO
NOBLOCK0
BUFSIZE(4096)
NOCICS
CODEPAGE(1140)
COMPILE
| NOCOPYRIGHT
NOCURRENCY
DATA(31)
DBCS
NODECK
NODIAGTRUNC
DISPSIGN(COMPAT)
NODLL
DUMP
NODYNAM
NOEXIT
NOEXPORTALL
NOFASTSRT
FLAG(I)
NOFLAGSTD
HGPR(PRESERVE)
INTDATE(ANSI)
LANGUAGE(EN)
LINECOUNT(60)
NOLIST
NOMAP
MAXPCF(60000)
NOMDECK
NONAME
NSYMBOL(NATIONAL)
NONUMBER
NUMPROC(NOPFD)
OBJECT
NOOFFSET
OPTIMIZE(1)
OUTDD(SYSOUT)
PGMNAME(COMPAT)
| QUALIFY(COMPAT)
RENT
RMODE(AUTO)
| NORULES
| NOSERVICE
SEQUENCE
NOSOURCE
SPACE(1)
NOSQL
SQLCCSID
NOSQLIMS
SSRANGE
NOSTGOPT
NOTERM
TEST(NOEJPD,SOURCE)
NOTHREAD
TRUNC(OPT)
NOVBREF
| VLR(COMPAT)
NOWORD
| XMLPARSE(XMLSS)
NOXREF
| ZONEDATA(PFD)
ZWB
LineID Message code Message text (5)
IGYSC3002-I A severe error was found in the program. The "OPTIMIZE" and the "STGOPT" compiler
options were cancelled.
160 IGYDS1089-S "ASSIGNN" was invalid. Scanning was resumed at the next area "A" item, level-number,
or the start of the next clause.
192 IGYDS1050-E File "LOCATION-FILE" contained no data record descriptions. The file definition was
discarded.
192 IGYGR1207-S The "ASSIGN" clause was missing or invalid in the "SELECT" entry for file "LOCATION-FILE".
The file definition was discarded.
888 IGYPS2052-S An error was found in the definition of file "LOCATION-FILE". The reference to this file
was discarded.
390 Enterprise COBOL for z/OS, V5.2 Programming Guide
Same message on line: 979
1000 IGYPS2121-S "WS-DATE" was not defined as a data-name. The statement was discarded.
Same message on line: 1001
1004 IGYPS2053-S An error was found in the definition of file "LOCATION-FILE". This input/output statement
was discarded.
Same message on line: 1016
1015 IGYPS2121-S "LOC-CODE" was not defined as a data-name. The statement was discarded.
1212 IGYPS2121-S "WS-NUMERIC-DATE" was not defined as a data-name. The statement was discarded.
1655 IGYPG3113-W Truncation of high-order digit positions may occur due to precision of intermediate results
exceeding 30 digits.
Messages Total Informational Warning Error Severe Terminating (6)
Printed: 13 1 1 1 10
* Statistics for COBOL program IGYTCARA: (7)
* Source records = 1755
* Data Division statements = 295
* Procedure Division statements = 479
* Generated COBOL statements = 0
* Program complexity factor = 486
End of compilation 1, program IGYTCARA, highest severity 12. (8)
Return code 12
(1) Message about options passed to the compiler at compiler invocation. This
message does not appear if no options were passed.
OPTFILE
Requests options from a SYSOPTF data set.
(2) Options coded in the PROCESS (or CBL) statement.
NOOFFSET
Suppresses a condensed listing of the PROCEDURE DIVISION.
NOMAP Suppresses a map report of the items defined in the DATA DIVISION.
(3) Options obtained from the SYSOPTF data set (because the OPTFILE
compiler option was specified).
NOLIST Suppresses an assembler-language expansion of the source code.
TEST The program was compiled for use with debugging and problem
determination tools (such as Debug Tool and Fault Analyzer) and
to get local variables listed in CEEDUMP.
(4) Status of options at the start of this compilation.
(5) Program diagnostics. The first message refers you to any library phase
diagnostics. Diagnostics for the library phase are presented at the
beginning of the listing.
(6) Count of diagnostic messages in this program, grouped by severity level.
(7) Program statistics for the program IGYTCARA.
(8) Program statistics for the compilation unit. When you perform a batch
compilation, the return code is the highest message severity level for the
entire compilation.
Example: SOURCE and NUMBER output
In the portion of the listing shown below, the programmer numbered two of the
statements out of sequence. The note numbers in the listing correspond to
numbered explanations that follow the listing.
(1)
LineID PL SL ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|--+----8 Map and Cross Reference
(2) (3) (4)
000870 /****************************************************************
000871 *** D O M A I N L O G I C **
000872 *** **
Chapter 19. Debugging 391
000873 *** Initialization. Read and process update transactions until **
000874 *** EOE. Close files and stop run. **
000875 *****************************************************************
000876 procedure division.
000877 000-do-main-logic.
000878 display "PROGRAM IGYTCARA - Beginning".
000879 perform 050-create-vsam-master-file. 930
000880 perform 100-initialize-paragraph. 982
000881 read update-transaction-file into ws-transaction-record 203 338
000882 at end
000883 1 IA4390 set transaction-eof to true 253
000884 end-read.
000885 IA4410 perform until transaction-eof 253
000886 1 perform 200-edit-update-transaction 1050
000887 1 IA4430 if no-errors 372
000888 2 perform 300-update-commuter-record 1159
000889 1 else
000890 2 perform 400-print-transaction-errors 1312
000891 1 end-if
000892 1 perform 410-re-initialize-fields 1373
000893 1 IA4480 read update-transaction-file into ws-transaction-record 203 338
000894 1 at end
000895 2 IA4500 set transaction-eof to true 253
000896 1 IA4510 end-read
000897 IA4520 end-perform.
000898 close commuter-file update-transaction-file location-file 180 203 192
000899 print-file. 216
000900
000901 *----------------------------------------------------*
000902 * File status checked after I/O operation. *
000903 *----------------------------------------------------*
000904
000905 IA4600 if not i-o-okay 241
000906 1 display "000-close"
000907 1 move 0000 to comp-code 230
000908 1 IA4620 perform 500-vsam-error 1386
000909 1 perform 900-abnormal-termination 1432
000910 IA4630 end-if.
000911 *********************************************************
000912 * Paragraphs 1100 and 1200 illustrates the intrinsic *
000913 * function computations. *
000914 *********************************************************
000915 perform 1100-print-i-f-headings. 1441
000916 perform 1200-print-i-f-data. 1481
000917 display " ".
000918 display " ".
000919 display "PROGRAM IGYTCARA - Normal end".
000920 stop run.
(1) Scale line, which labels Area A, Area B, and source-code column numbers
(2) Source-code line number assigned by the compiler
(3) Program (PL) and statement (SL) nesting level
(4) Columns 1 through 6 of program (the sequence number area)
Example: MAP output
The following example shows output from the MAP option. The numbers used in
the explanation below correspond to the numbers that annotate the output.
Data Division Map
(1)
Data Definition Attribute codes (rightmost column) have the following meanings:
D = Object of OCCURS DEPENDING G = GLOBAL S = Spanned file
E = EXTERNAL O = Has OCCURS clause U = Undefined format file
F = Fixed-length file OG= Group has own length definition V = Variable-length file
FB= Fixed-length blocked file R = REDEFINES VB= Variable-length blocked file
X = Unallocated
(2) (3) (4) (5) (6) (7) (8) (9)
Source Hierarchy and Base Displacement Asmblr Data Data Def
LineID Data Name Locator Structure Definition Data Type Attributes
4 PROGRAM-ID IGYTCARA----------------------------------------------------------------------------------------------------*
58 FD COMMUTER-FILE . . . . . . . . . . . . . . . . BLF=00001 VSAM F
60 1 COMMUTER-RECORD . . . . . . . . . . . . . . . BLF=00001 DS 0CL80 Group
61 2 COMMUTER-KEY. . . . . . . . . . . . . . . . BLF=00001 000000000 DS 16C Display
62 2 FILLER. . . . . . . . . . . . . . . . . . . BLF=00001 000000016 DS 64C Display
64 FD COMMUTER-FILE-MST . . . . . . . . . . . . . . BLF=00002 VSAM F
66 1 COMMUTER-RECORD-MST . . . . . . . . . . . . . BLF=00002 DS 0CL80 Group
67 2 COMMUTER-KEY-MST. . . . . . . . . . . . . . BLF=00002 000000000 DS 16C Display
68 2 FILLER. . . . . . . . . . . . . . . . . . . BLF=00002 000000016 DS 64C Display
140 1 STATUS-AREA . . . . . . . . . . . . . . . . . DS 0CL8 Group
141 2 COMMUTER-FILE-STATUS. . . . . . . . . . . . 000000000 DS 2C Display
142 88 I-O-OKAY. . . . . . . . . . . . . . . . . .
143 2 COMMUTER-VSAM-STATUS. . . . . . . . . . . . 000000002 DS 0CL6 Group
144 3 VSAM-R15-RETURN-CODE. . . . . . . . . . . 000000002 DS 2C Binary
145 3 VSAM-FUNCTION-CODE. . . . . . . . . . . . 000000004 DS 2C Binary
146 3 VSAM-FEEDBACK-CODE. . . . . . . . . . . . 000000006 DS 2C Binary
148 77 UPDATE-FILE-STATUS. . . . . . . . . . . . . . DS 2C Display
149 77 LOCCODE-FILE-STATUS . . . . . . . . . . . . . DS 2C Display
150 77 UPDPRINT-FILE-STATUS. . . . . . . . . . . . . DS 2C Display
152 1 FLAGS . . . . . . . . . . . . . . . . . . . . DS 0CL3 Group
153 2 TRANSACTION-EOF-FLAG. . . . . . . . . . . . 000000000 DS 1C Display
154 88 TRANSACTION-EOF . . . . . . . . . . . . . .
155 2 LOCATION-EOF-FLAG . . . . . . . . . . . . . 000000001 DS 1C Display
156 88 LOCATION-EOF. . . . . . . . . . . . . . . .
157 2 TRANSACTION-MATCH-FLAG. . . . . . . . . . . 000000002 DS 1C Display
158 88 TRANSACTION-MATCH . . . . . . . . . . . . .
392 Enterprise COBOL for z/OS, V5.2 Programming Guide
159 88 TRANSACTION-MATCH-OFF . . . . . . . . . . .
216 1 WS-COMMUTER-RECORD. . . . . . . . . . . . . . BLX=00001 DS 0CL81 Group E
217 2 WS-COMMUTER-KEY . . . . . . . . . . . . . . BLX=00001 000000000 DS 0CL16 Group E
218 3 WS-COMMUTER-GENERIC-KEY . . . . . . . . . BLX=00001 000000000 DS 0CL5 Group E
219 4 COMMUTER-SHIFT. . . . . . . . . . . . . BLX=00001 000000000 DS 1C Display E
220 4 COMMUTER-HOME-CODE. . . . . . . . . . . BLX=00001 000000001 DS 2C Display E
221 4 COMMUTER-WORK-CODE. . . . . . . . . . . BLX=00001 000000003 DS 2C Display E
222 3 COMMUTER-NAME . . . . . . . . . . . . . . BLX=00001 000000005 DS 9C Display E
223 3 COMMUTER-INITIALS . . . . . . . . . . . . BLX=00001 000000014 DS 2C Display E
224 2 COMMUTER-ADDRESS. . . . . . . . . . . . . . BLX=00001 000000016 DS 18C Display E
225 2 COMMUTER-CITY . . . . . . . . . . . . . . . BLX=00001 000000034 DS 13C Display E
226 2 COMMUTER-STATE. . . . . . . . . . . . . . . BLX=00001 000000047 DS 2C Display E
227 2 COMMUTER-ZIPCODE. . . . . . . . . . . . . . BLX=00001 000000049 DS 3P Packed-Dec E
396 1 DETAIL1-LINE. . . . . . . . . . . . . . . . . BLL=00001 DS 0CL121 Group
397 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000000 DS 2C Display
398 2 PRINT-TRANSACTION-CODE. . . . . . . . . . . BLL=00001 000000002 DS 1C Display
399 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000003 DS 4C Display
400 2 PRINT-RECORD-TYPE . . . . . . . . . . . . . BLL=00001 000000007 DS 3C Display
401 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000010 DS 3C Display
402 2 PRINT-SHIFT . . . . . . . . . . . . . . . . BLL=00001 000000013 DS 1C Display
403 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000014 DS 1C Display
404 2 PRINT-HOME-CODE . . . . . . . . . . . . . . BLL=00001 000000015 DS 2C Display
405 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000017 DS 1C Display
406 2 PRINT-WORK-CODE . . . . . . . . . . . . . . BLL=00001 000000018 DS 2C Display
407 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00001 000000020 DS 2C Display
408 2 PRINT-NAME. . . . . . . . . . . . . . . . . BLL=00001 000000022 DS 9C Display
454 1 DETAILX-LINE. . . . . . . . . . . . . . . . . BLL=XXXXX DS 0CL121 Group X
455 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX DS 36C Display X
456 2 PRINT-CITY. . . . . . . . . . . . . . . . . BLL=XXXXX DS 13C Display X
457 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX DS 3C Display X
458 2 PRINT-STATE . . . . . . . . . . . . . . . . BLL=XXXXX DS 2C Display X
459 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX DS 1C Display X
460 2 PRINT-ZIPCODE . . . . . . . . . . . . . . . BLL=XXXXX DS 5C Display X
461 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX DS 1C Display X
462 2 PRINT-WORK-PHONE. . . . . . . . . . . . . . BLL=XXXXX DS 14C Display X
463 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX DS 1C Display X
464 2 PRINT-WORK-JUNCTION . . . . . . . . . . . . BLL=XXXXX DS 25C Display X
465 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=XXXXX DS 20C Display X (10)
467 1 DETAIL2-LINE. . . . . . . . . . . . . . . . . BLL=00002 DS 0CL121 Group
468 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000000 DS 36C Display
469 2 PRINT-CITY. . . . . . . . . . . . . . . . . BLL=00002 000000036 DS 13C Display
470 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000049 DS 3C Display
471 2 PRINT-STATE . . . . . . . . . . . . . . . . BLL=00002 000000052 DS 2C Display
472 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000054 DS 1C Display
473 2 PRINT-ZIPCODE . . . . . . . . . . . . . . . BLL=00002 000000055 DS 5C Display
474 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000060 DS 1C Display
475 2 PRINT-WORK-PHONE. . . . . . . . . . . . . . BLL=00002 000000061 DS 14C Display
476 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000075 DS 1C Display
477 2 PRINT-WORK-JUNCTION . . . . . . . . . . . . BLL=00002 000000076 DS 25C Display
478 2 FILLER. . . . . . . . . . . . . . . . . . . BLL=00002 000000101 DS 20C Display
(1) Explanations of the data definition attribute codes.
(2) Source line number where the data item was defined.
(3) Level definition or number. The compiler generates this number in the
following way:
v First level of any hierarchy is always 01. Increase 1 for each level (any
item you coded as level 02 through 49).
v Level-numbers 66, 77, and 88, and the indicators FD and SD, are not
changed.
(4) Data-name that is used in the source module in source order.
(5) Base locator used for this data item.
(6) Hexadecimal displacement from the beginning of the containing structure
| if the MAP(HEX) option is in effect. If the MAP(DEC) option is in effect,
| decimal displacement is shown.
(7) Pseudoassembler code showing how the data is defined. When a structure
contains variable-length fields, the maximum length of the structure is
shown.
(8) Data type and usage.
(9) Data definition attribute codes. The definitions are explained at the top of
the DATA DIVISION map.
(10) DETAILX-LINE was not referenced in the PROCEDURE DIVISION. Because
STGOPT was specified, DETAILX-LINE was deleted, resulting in the base
locator being set to XXXXX.
Chapter 19. Debugging 393
Example: embedded map summary
Example: nested program map on page 397
RELATED REFERENCES
Terms used in MAP output on page 395
Symbols used in LIST and MAP output on page 396
Example: embedded map summary
The following example shows an embedded map summary from specifying the MAP
option. The summary appears in the right margin of the listing for lines in the DATA
DIVISION that contain data declarations.
000002 Identification Division.
000003
000004 Program-id. IGYTCARA.
. . .
000054 Data division.
000055 File section.
000056
000058 FD COMMUTER-FILE
000059 record 80 characters.
. . . (1) (2) (3)
000060 01 commuter-record. BLF=00001 0CL80
000061 05 commuter-key PIC x(16). BLF=00001,000000000 16C
000062 05 filler PIC x(64). BLF=00001,000000016 64C
. . .
000105 Working-storage section.
000106 01 Working-storage-for-IGYCARA pic x. 1C
000107
000108 77 comp-code pic S9999 comp. 2C
000109 77 ws-type pic x(3) value spaces. 3C
000135 01 i-f-status-area. 0CL2
000136 05 i-f-file-status pic x(2). 000000000 2C
000137 88 i-o-successful value zeroes.
000138
000139
000140 01 status-area. 0CL8
000141 05 commuter-file-status pic x(2). 000000000 2C
000142 88 i-o-okay value zeroes.
000143 05 commuter-vsam-status. 000000002 0CL6
000144 10 vsam-r15-return-code pic 9(2) comp. 000000002 2C
000145 10 vsam-function-code pic 9(1) comp. 000000004 2C
000146 10 vsam-feedback-code pic 9(3) comp. 000000006 2C
000147
000148 77 update-file-status pic xx. 2C
000149 77 loccode-file-status pic xx. 2C
000150 77 updprint-file-status pic xx. 2C
000151
000216 01 ws-commuter-record EXTERNAL. BLX=00001 0CL81
000217 05 ws-commuter-key. BLX=00001,000000000 0CL16
000218 10 ws-commuter-generic-key. BLX=00001,000000000 0CL5
000219 15 commuter-shift pic x. BLX=00001,000000000 1C
000220 15 commuter-home-code pic xx. BLX=00001,000000001 2C
000221 15 commuter-work-code pic xx. BLX=00001,000000003 2C
000222 10 commuter-name pic x(9). BLX=00001,000000005 9C
000223 10 commuter-initials pic xx. BLX=00001,000000014 2C
000224 05 commuter-address pic x(18). BLX=00001,000000016 18C
000225 05 commuter-city pic x(13). BLX=00001,000000034 13C
000226 05 commuter-state pic xx. BLX=00001,000000047 2C
000227 05 commuter-zipcode pic 9(5) comp-3. BLX=00001,000000049 3P
. . .
000395 Linkage Section.
000396 01 detail1-line. BLL=00001 0CL121
000397 05 filler pic xx. BLL=00001,000000000 2C
000398 05 print-transaction-code pic x. BLL=00001,000000002 1C
000399 05 filler pic x(4). BLL=00001,000000003 4C
000400 05 print-record-type pic x(3). BLL=00001,000000007 3C
000401 05 filler pic xxx. BLL=00001,000000010 3C
000402 05 print-shift pic x. BLL=00001,000000013 1C
000403 05 filler pic x. BLL=00001,000000014 1C
000404 05 print-home-code pic xx. BLL=00001,000000015 2C
000405 05 filler pic x. BLL=00001,000000017 1C
000406 05 print-work-code pic xx. BLL=00001,000000018 2C
000407 05 filler pic xx. BLL=00001,000000020 2C
000408 05 print-name pic x(9). BLL=00001,000000022 9C
000409 05 filler pic xx. BLL=00001,000000031 2C
000410 05 print-initials pic xx. BLL=00001,000000033 2C
. . .
000487 procedure division.
000488 000-do-main-logic.
000489 display "PROGRAM IGYTCARA - Beginning".
(1) Base locator used for this data item
394 Enterprise COBOL for z/OS, V5.2 Programming Guide
| (2) Decimal displacement from the beginning of the containing structure. It
| indicates that the MAP(DEC) option is in effect. If you specified the MAP(HEX)
| option or MAP with no suboption, hexadecimal displacement is shown.
(3) Pseudoassembler code showing how the data is defined
RELATED REFERENCES
Symbols used in LIST and MAP output on page 396
Terms used in MAP output
The following table describes the terms used in the listings produced by the MAP
compiler option.
Table 51. Terms used in MAP output
Term Definition Description
ALPHABETIC DS nC Alphabetic data item (PICTURE A)
ALPHA-EDIT DS nC Alphabetic-edited data item
AN-EDIT DS nC Alphanumeric-edited data item
2 2 2
BINARY DS 1H , 1F , 2F , 2C, Binary data item (USAGE BINARY, COMPUTATIONAL, or
4C, or 8C COMPUTATIONAL-5)
COMP-1 DS 4C Single-precision internal floating-point data item (USAGE
COMPUTATIONAL-1)
COMP-2 DS 8C Double-precision internal floating-point data item (USAGE
COMPUTATIONAL-2)
DBCS DS nC DBCS data item (USAGE DISPLAY-1)
DBCS-EDIT DS nC DBCS-edited data item (USAGE DISPLAY-1)
DISP-FLOAT DS nC Display floating-point data item (USAGE DISPLAY)
DISPLAY DS nC Alphanumeric data item (PICTURE X)
DISP-NUM DS nC Zoned decimal data item (USAGE DISPLAY)
DISP-NUM-EDIT DS nC Numeric-edited data item (USAGE DISPLAY)
FD File definition
FUNCTION-PTR DS nC Function pointer (USAGE FUNCTION-POINTER)
1
GROUP DS 0CLn Fixed-length alphanumeric group data item
1
GRP-VARLEN DS 0CLn Variable-length alphanumeric group data item
INDEX DS nC Index data item (USAGE INDEX)
INDEX-NAME DS nC Index name
NATIONAL DS nC Category national data item (USAGE NATIONAL)
NAT-EDIT DS nC National-edited data item (USAGE NATIONAL)
NAT-FLOAT DS nC National floating-point data item (USAGE NATIONAL)
1
NAT-GROUP DS 0CLn National group (GROUP-USAGE NATIONAL)
1
NAT-GRP-VARLEN DS 0CLn National variable-length group (GROUP-USAGE NATIONAL)
NAT-NUM DS nC National decimal data item (USAGE NATIONAL)
NAT-NUM-EDIT DS nC National numeric-edited data item (USAGE NATIONAL)
OBJECT-REF DS nC Object-reference data item (USAGE OBJECT REFERENCE)
PACKED-DEC DS nP Internal decimal data item (USAGE PACKED-DECIMAL or
COMPUTATIONAL-3)
POINTER DS nC Pointer data item (USAGE POINTER)
Chapter 19. Debugging 395
Table 51. Terms used in MAP output (continued)
Term Definition Description
PROCEDURE-PTR DS nC Procedure pointer (USAGE PROCEDURE-POINTER)
SD Sort file definition
VSAM, QSAM, File processing method
LINESEQ
1-49, 77 Level-numbers for data descriptions
66 Level-number for RENAMES
88 Level-number for condition-names
1. n is the size in bytes for fixed-length groups and the maximum size in bytes for variable-length groups.
2. If the SYNCHRONIZED clause appears, these fields are used.
Symbols used in LIST and MAP output
The following table describes the symbols used in the listings produced by the
LIST or MAP option.
Table 52. Symbols used in LIST and MAP output
Symbol Definition
1
BLF_n Base locator for files
1
BLL_n Base locator for LINKAGE SECTION
1
BLO_n Base locator for object instance data
1
BLT_n Base locator for XML-TEXT and XML-NTEXT
1
BLV_n Base locator for variably located data
1
BLX_n Base locator for external data
ODOsv_cell ODO save cell number
Pfm_cell PERFORM cell number
Pfmsv_cell Perform save cell number
TSN=N Temporary created by the compiler
VLC_cell Variable-length cell (ODO)
VN_cell Variable name cell for PERFORM statement
VNGO_cell Variable name cell for ALTER statement
VNI_cell Variable name initialization
#Calc00000000n Code to compute addresses of data that is present after an OCCURS DEPENDING
ON clause
#WSVal0000000n Code to initialize the WORKING-STORAGE area for a procedure
_ArgumentList Outgoing arguments to a procedure
_ACON Address of a symbol
_BEtempNNN Temporary created by the optimizer
_CAA Address of the start of the Language Environment Common Anchor Area
_CACHED_$STATIC Copy of the start address of the static area (for this procedure)
_CONSTANT_AREA+n Offset in the Constant Area
_CRENT Address of the writeable static area (for this module), from the CAA
_incomingArgumentList Incoming parameters to the procedure
_parentDSA For a nested procedure, it is the address of its parent's stack
396 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 52. Symbols used in LIST and MAP output (continued)
Symbol Definition
_QCON Offset to a symbol
_returnValue Return value of the procedure
_VTS_n Temporary created by the optimizer
1. n is the number of the entry. For base locators, it can also be XXXXX, indicating a data item that was deleted by
STGOPT processing.
Example: nested program map
This example shows a map of nested procedures produced by specifying the MAP
compiler option. Numbers in parentheses refer to notes that follow the example.
Nested Program Map
Program Attribute codes (rightmost column) have the following meanings:
C = COMMON
I = INITIAL (1)
U = PROCEDURE DIVISION USING... (5)
Source Nesting Program
LineID Level Program Name from PROGRAM-ID paragraph Attributes
2 0 NESTMAIN. . . . . . . . . . . . . . . . . . . U
120 1 (4) SUBPRO1 . . . . . . . . . . . . . . . . . . I,C,U
(2)199 2 NESTED1 . . . . . . . . . . . . . . . . . I,C,U
253 1 SUBPRO2 . . . . . . . . . . . . . . . . . . U
335 2 NESTED2 . . . . . . . . . . . . . . . . . C,U
(3)
(1) Explanations of the program attribute codes
(2) Source line number where the program was defined
(3) Depth of program nesting
(4) Program-name
(5) Program attribute codes
Reading LIST output
Parts of the LIST compiler output might be useful to you for debugging a program.
The LIST compiler option produces several pieces of output:
v An assembler listing of the initialization code for the program (program
signature information bytes) from which you can verify program characteristics
such as:
Compiler options in effect
Types of data items present
Verbs used in the PROCEDURE DIVISION
v An assembler listing of the source code for the program
From the address in storage of the instruction that was executing when an abend
occurred, you can find the COBOL verb that corresponds to that instruction.
After you find the address of the failing instruction, go to the assembler listing
and find the verb for which that instruction was generated. The line number is
in the 3rd column of the assembler listing for your program. Using the line
number, you can locate the VERB by looking at the corresponding line in the
Source Output section of the listing.
v Information about WORKING-STORAGE. This information is contained in the Data
Division Map and in the Static Map.
Chapter 19. Debugging 397
v A description of the writeable static area (WSA) is found in the Static Map or
WSA24 Map sections of the listing. The symbols in WORKING-STORAGE area of the
source are mapped into the writable static area that is shown in the Static Map.
You can use the Data Division Map along with the Static Map section to find the
location of data items defined in WORKING-STORAGE. These data items reside in the
Writeable Static Area (WSA or WSA24). The Static Map gives the offset of each
level-1 data item relative to the beginning of the writable static area. The Data
Division Map section gives the offset of the level-n data items relative to their
respective level-1 member. By using both pieces of information, you can
determine the offset of any data member within the writable static area.
If you compile with the DATA24 option, data items mapped below the line will
appear in the WSA24 Map. You can follow the same process to determine their
locations.
v Information about the constants and the literals used in the program. The
Constant Area contains information about the constants and literals in the
program, as well as those created by the compiler. This section contains the
offset of each constant or literal within the Constant Area.
v Program prolog areas (PPA1, PPA2, PPA3, PPA4) contain information about the
characteristics of the compiled program.
v Externals symbols dictionary contains the list of external symbols defined by or
referred to, in your program.
v Map of the dynamic save area (DSA)
The map of the DSA (also known as the stack frame) contains information about
the contents of the storage acquired each time a separately compiled procedure
is entered.
You do not need to be able to program in assembler language to understand the
LIST output. The comments that accompany most of the assembler code provide
you with a conceptual understanding of the functions performed by the code.
Example: program initialization code on page 405
Example: Timestamp and version information on page 405
Example: Compiler options and program information on page 405
Example: assembler code generated from source code on page 406
Example: Program prolog areas on page 406
Example: Static map on page 408
Example: Constant area on page 409
Example: Base locator table on page 409
Example: External symbols on page 410
Example: DSA memory map (Automatic map) on page 411
RELATED REFERENCES
Signature information bytes
Example: MAP output on page 392
Language Environment Programming Guide (Stack storage overview)
Signature information bytes
The tables in this topic show program signature information that is part of the
listing of program initialization code provided when you use the LIST compiler
option.
398 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 53. Compiler options in the INFO BYTE section
Offset in
decimal Option Value
00 CODEPAGE CCSID value specified for EBCDIC code page
02 ARCH 7
8
9
10
| 11
03 OPTIMIZE 0
1
2
The INFO BYTE section of the listing also provides the following values:
v The number of DATA DIVISION statements
v The number of PROCEDURE DIVISION statements
In the following table, different signature bytes represent different information:
| v Signature bytes 1-5, and 26-30 refer to compiler options
v Signature bytes 6-7 refer to DATA DIVISION items
v Signature byte 8 refers to ENVIRONMENT DIVISION items
v Signature bytes 9-25 refer to PROCEDURE DIVISION verbs and items
Table 54. Signature information bytes
Offset
Item
in Signature
decimal byte Bit On Off
04 28 0 SQL NOSQL
1 CICS NOCICS
2 MDECK NOMDECK
3 SQLCCSID NOSQLCCSID
4 OPTFILE NOOPTFILE
| 5 XMLPARSE(XMLSS) XMLPARSE(COMPAT)
6 BLOCK0 NOBLOCK0
7 DISPSIGN(SEP) DISPSIGN(COMPAT)
05 29 0 Program uses Java-based OO syntax
1 Program uses RANDOM function
2 Program uses NATIONAL data (Unicode)
3 XML PARSE with schema validation
4 STGOPT NOSTGOPT
5 AFP(VOLATILE) AFP(NOVOLATILE)
6 HGPR(PRESERVE) HGPR(NOPRESERVE)
7 NOTEST(DWARF) Not NOTEST(DWARF)
Chapter 19. Debugging 399
Table 54. Signature information bytes (continued)
Offset
Item
in Signature
decimal byte Bit On Off
| 06 30 0 QUALIFY(EXTEND) QUALIFY(COMPAT)
| 1 VLR(COMPAT) VLR(STANDARD)
| 2 COPYRIGHT string specified COPYRIGHT string unspecified
| 3 SERVICE string specified SERVICE string unspecified
| 4 ZONEDATA(MIG) ZONEDATA(PFD)
| 5-7 Reserved
08 1 0 ADV NOADV
1 APOST QUOTE
2 DATA(31) DATA(24)
3 DECK NODECK
4 DUMP NODUMP
5 DYNAM NODYNAM
6 FASTSRT NOFASTSRT
7 SQLIMS NOSQLIMS
09 2 0 LIB (always on)
1 LIST NOLIST
| 2 MAP(HEX), MAP(DEC) NOMAP
3 NUM NONUM
4 OBJECT NOOBJECT
5 OFFSET NOOFFSET
6 OPT(1), OPT(2) NOOPT, OPT(0)
7 OUTDD NOOUTDD
10 3 0 NUMPROC(PFD) NUMPROC(NOPFD)
1 RENT NORENT
2 RESIDENT (always on)
3 SEQUENCE NOSEQUENCE
4 Reserved
5 SOURCE NOSOURCE
6 SSRANGE NOSSRANGE
7 TERM NOTERM
11 4 0 TEST NOTEST
1 TRUNC(STD) Not TRUNC(STD)
2 WORD NOWORD
3 VBREF NOVBREF
4 XREF NOXREF
5 ZWB NOZWB
6 NAME NONAME
7 NOCMPR2 (always off)
400 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 54. Signature information bytes (continued)
Offset
Item
in Signature
decimal byte Bit On Off
12 5 0 Reserved NONUMPROC
1 NUMCLS=ALT NUMCLS=PRIM
2 DBCS NODBCS
3 AWO NOAWO
4 TRUNC(BIN) Not TRUNC(BIN)
5 ADATA NOADATA
6 CURRENCY NOCURRENCY
7 Compilation unit is a class Compilation unit is a program
13 6 0 QSAM file descriptor
1 VSAM sequential file descriptor
2 VSAM indexed file descriptor
3 VSAM relative file descriptor
4 CODE-SET clause (ASCII files) in file descriptor
5 Spanned records
6 PIC G or PIC N (DBCS data item)
7 OCCURS DEPENDING ON clause in data description entry
14 7 0 SYNCHRONIZED clause in data description entry
1 JUSTIFIED clause in data description entry
2 USAGE IS POINTER item
3 Complex OCCURS DEPENDING ON clause
4 External floating-point items in the DATA DIVISION
5 Internal floating-point items in the DATA DIVISION
6 Line-sequential file
7 USAGE IS PROCEDURE-POINTER or FUNCTION-POINTER item
15 8 0 FILE STATUS clause in FILE-CONTROL paragraph
1 RERUN clause in I-O-CONTROL paragraph of INPUT-OUTPUT SECTION
2 UPSI switch defined in SPECIAL-NAMES paragraph
16 9 0 ACCEPT
1 ADD
2 ALTER
3 CALL
4 CANCEL
6 CLOSE
17 10 0 COMPUTE
2 DELETE
4 DISPLAY
5 DIVIDE
Chapter 19. Debugging 401
Table 54. Signature information bytes (continued)
Offset
Item
in Signature
decimal byte Bit On Off
18 11 1 END-PERFORM
2 ENTER
3 ENTRY
4 EXIT
5 EXEC
6 GO TO
7 IF
19 12 0 INITIALIZE
1 INVOKE
2 INSPECT
3 MERGE
4 MOVE
5 MULTIPLY
6 OPEN
7 PERFORM
20 13 0 READ
2 RELEASE
3 RETURN
4 REWRITE
5 SEARCH
7 SET
21 14 0 SORT
1 START
2 STOP
3 STRING
4 SUBTRACT
7 UNSTRING
22 15 0 USE
1 WRITE
2 CONTINUE
3 END-ADD
4 END-CALL
5 END-COMPUTE
6 END-DELETE
7 END-DIVIDE
402 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 54. Signature information bytes (continued)
Offset
Item
in Signature
decimal byte Bit On Off
23 16 0 END-EVALUATE
1 END-IF
2 END-MULTIPLY
3 END-READ
4 END-RETURN
5 END-REWRITE
6 END-SEARCH
7 END-START
24 17 0 END-STRING
1 END-SUBTRACT
2 END-UNSTRING
3 END-WRITE
4 GOBACK
5 EVALUATE
7 SERVICE
25 18 0 END-INVOKE
1 END-EXEC
2 XML
3 END-XML
26 19 0-7 Reserved
27 20 0-7 Reserved
28 21 0 Hexadecimal literal
1 Altered GO TO
2 I-O ERROR declarative
3 LABEL declarative
4 DEBUGGING declarative
5 Program segmentation
6 OPEN . . . EXTEND
7 EXIT PROGRAM
29 22 0 CALL literal
1 CALL identifier
2 CALL . . . ON OVERFLOW
3 CALL . . . LENGTH OF
4 CALL . . . ADDRESS OF
5 CLOSE . . . REEL/UNIT
6 Exponentiation used
7 Floating-point items used
Chapter 19. Debugging 403
Table 54. Signature information bytes (continued)
Offset
Item
in Signature
decimal byte Bit On Off
30 23 0 COPY
1 BASIS
2 DBCS name in program
3 Shift-out and Shift-in in program
| 4-7 Reserved
40 24 0 DBCS literal
1 REPLACE
2 Reference modification was used.
3 Nested program
4 INITIAL
5 COMMON
6 SELECT . . . OPTIONAL
7 EXTERNAL
41 25 0 GLOBAL
1 RECORD IS VARYING
| 2 VOLATILE
5 Intrinsic function was used
6 Z-literal found
7 RECURSIVE
42 26 0 RMODE(ANY) Not RMODE(ANY)
1-3 Reserved
4 Reserved
5 INTDATE(LILIAN) INTDATE(ANSI)
6 Reserved
7 Reserved
43 27 0 PGMNAME(LONGUPPER) Not PGMNAME(LONGUPPER)
1 PGMNAME(LONGMIXED) Not PGMNAME(LONGMIXED)
2 DLL NODLL
3 EXPORTALL NOEXPORTALL
4 TEST(SOURCE) Not TEST(SOURCE)
5 ARITH(EXTEND) ARITH(COMPAT)
6 THREAD NOTHREAD
7 TEST(EJPD) TEST(NOEJPD)
Check return code: A return code greater than 4 from the compiler could mean
that some of the verbs shown in the information bytes might have been discarded
from the program.
RELATED REFERENCES
LIST on page 333
404 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: program initialization code
A listing of the program initialization code gives you information about the
characteristics of the COBOL source program. Interpret the program signature
information bytes to verify characteristics of your program.
(1) (2) (3) (4) (5)
000000 000003 PROC IGYTCARA
000000 47F0 F014 000003 BC R15,20(,R15) # Skip over constant area
000004 01C3 C5C5 000003 DC X01C3C5C5 # Eyecatcher: CEE
000008 0000 0978 000003 DC X00000978 # Stack Size
00000C 0000 8910 000003 DC X00008910 # Offset to PPA1
000010 47F0 F001 000003 BC R15,1(,R15) # Wrong Entry Point: cause exception
000014 000003 L3282: EQU *
000014 90EC D00C 000003 STM R14,R12,12(,R13) # Save GPRs Used
000018 4110 F024 000003 LA R1,36(,R15) # Args for boot strap routine
00001C 98EF F034 000003 LM R14,R15,52(,R15) #
000020 07FF 000003 BR R15 # Branch to boot strap routine
000022 0000 000003 DC X0000 # Available half-word
000024 000003 L3284: EQU * # Boot Strap Info Block
000024 0000 0000 000003 DC X00000000 # address of entry label
000028 0000 0000 000003 DC X00000000 # WSA24 allocation size
00002C 0000 8A0C 000003 DC X00008A0C # address of Saved Option String
000030 0000 8948 000003 DC X00008948 # address of entry point name
000034 0000 0054 000003 DC X00000054 # A(Label L3283)
000038 0000 0000 000003 DC X00000000 # address of boot strap routine(IGZXBST)
00003C 000003 L3285: EQU * # CEE Parameter Block
00003C 0000 0024 000003 DC X00000024 # address of infoBlockLabel
000040 0000 8A1C 000003 DC X00008A1C # A(PARMCEE-CEEEPARMBlock)
000044 000003 L3280: EQU * # Handle growing stack
000044 58F0 C31C 000003 L R15,796(,R12) # Load CEECAAOGETS
000048 184E 000003 LR R4,R14 # Required NAB
00004A 05EF 000003 BALR R14,R15 # Extend Stack
00004C 0000 0000 000003 DC X00000000 # Argument list size = 0
000050 A7F4 0009 000003 J L3281 # Branch back
000054 000003 @MAINENT DS 0H # PRIMARY ENTRY POINT ADDRESS
000054 000003 L3283: EQU * # User Code Entry Point
000054 18EF 000003 LR R14,R15 # Load NAB
000056 4100 E978 000003 LA R0,2424(,R14) # New NAB Address
00005A 5500 C314 000003 CL R0,788(,R12) # Exceed current storage segment?
00005E A724 FFF3 000003 JH L3280 # Yes: branch to recovery code
000062 000003 L3281: EQU * # Stack now has sufficient room
000062 5000 E04C 000003 ST R0,76(,R14) # Update NAB
000066 A708 0010 000003 LHI R0,16 # COBOL Language Word upper half
00006A 8900 0010 000003 SLL R0,16 # shift to upper half of register
00006E A70A 0301 000003 AHI R0,769 # add COBOL Language Word lower half
000072 5000 E000 000003 ST R0,0(,R14) # Save Language Word
000076 50D0 E004 000003 ST R13,4(,R14) # Save Back Chain
00007A 18DE 000003 LR R13,R14 # Set new DSA
00007C 4100 D6D0 000003 LA R0,1744(,R13) # Address of COBDSACB
000080 5000 D074 000003 ST R0,116(,R13) # Saved in member slot1
000084 4100 0000 000003 LA R0,0(,R0) #
000088 5000 D070 000003 ST R0,112(,R13) # zero member slot0
(1) Offset from the start of the COBOL program
(2) Hexadecimal representation of assembler instructions
(3) Source line number
(4) Pseudo-assembler representation of the code generated for the COBOL
program
(5) Comments that explain the pseudo-assembler code
RELATED REFERENCES
Signature information bytes on page 398
Example: Timestamp and version information
The following example shows LIST output about the version of the compiler and
the data and time of compilation.
Timestamp and Version Information
0029C8 F2F0 F1F3 =C2013 Compiled Year
0029CC F0F3 F2F7 =C0327 Compiled Date MMDD
0029D0 F1F2 F3F1 F2F2 =C123122 Compiled Time HHMMSS
0029D6 F0F5 F0F1 F0F0 =C050100 VERSION/RELEASE/MOD LEVEL OF PROD
Timestamp and Version End
Example: Compiler options and program information
The following example shows LIST output for the compiler options and program
information.
DATA VALIDATION AND UPDATE PROGRAM IGYTCARA Date 03/30/2013 Time 10:48:16
Compiler Options and Program Information Section
(1) (2) (3) (4) (5)
Chapter 19. Debugging 405
0029DC 0030 =X0030 Size of Compiler Options and Prog Info Section
0029DE (+00) 0474 =X0474 UNSIGNED BINARY CODE PAGE CCSID VALUE
0029E0 (+02) 06 =X06 ARCHITECTURE LEVEL
0029E1 (+03) 00 =X00 OPTIMIZATION LEVEL
0029E2 (+04) 1406 =X1406 INFO. BYTES 28-29
0029E4 (+06) 0000 =X0000 RESERVED
0029E6 (+08) A04875CC2001 =XA04875CC2001 INFO. BYTES 1-6
0029EC (+14) 100010884909 =X100010884909 INFO. BYTES 7-12
0029F2 (+20) 002008800C00 =X002008800C00 INFO. BYTES 13-18
0029F8 (+26) 000001A000 =X000001A000 INFO. BYTES 19-23
0029FD (+31) 00 =X00 COBOL SIGNATURE LEVEL
0029FE (+32) 0000002F =X0000002F # DATA DIVISION STATEMENTS
002A02 (+36) 0000005B =X0000005B # PROCEDURE DIVISION STATEMENTS
002A06 (+40) 18808008 =X18808008 INFO. BYTES 24-27
002A0A (+44) 40404040 =C USER LEVEL INFO (LVLINFO)
Compiler Options and Program Information Section End
| (1) Offset in the program object
(2) Offset in decimal
(3) Contents of the bytes in hexadecimal format
(4) Assembler representation of the bytes
(5) Explanation of the bytes in the section
Example: assembler code generated from source code
The following example shows a listing of the assembler code that is generated
from source code when you use the LIST compiler option. You can use this listing
to find the COBOL verb that corresponds to the instruction that failed.
000964: display "PROGRAM IGYTCARA - Beginning". (1)
(2) (3) (4) (5) (6)
0001EA E320 3394 0171 000964 LAY R2,5012(,R3) #
0001F0 D203 D5E8 2000 000964 MVC 1512(4,R13),0(R2) # _$CONSTANT_AREA+5012
0001F6 E320 3398 0171 000964 LAY R2,5016(,R3) #
0001FC D203 D5EC 2000 000964 MVC 1516(4,R13),0(R2) # _$CONSTANT_AREA+5016
000202 4120 39C8 000964 LA R2,2504(,R3) #
000206 5020 D5F0 000964 ST R2,1520(,R13) #
00020A E320 338C 0171 000964 LAY R2,5004(,R3) #
000210 D203 D5F4 2000 000964 MVC 1524(4,R13),0(R2) # _$CONSTANT_AREA+5004
000216 E320 339C 0171 000964 LAY R2,5020(,R3) #
00021C D203 D5F8 2000 000964 MVC 1528(4,R13),0(R2) # _$CONSTANT_AREA+5020
000222 D703 D5FC D5FC 000964 XC 1532(4,R13),1532(R13) #
000228 4110 D5E8 000964 LA R1,1512(,R13) # _ArgumentList
00022C E3F0 31D4 0158 000964 LY R15,4564(,R3) # _ACON
000232 58C0 D080 000964 L R12,128(,R13) # _@CAA
000236 0DEF 000964 BASR R14,R15 # Call "IGZXDSP"
000965: perform 050-create-vsam-master-file.
000238 5820 D670 000965 L R2,1648(,R13) # VN_cell
00023C 5020 D544 000965 ST R2,1348(,R13) # PfmSv_Cell
000240 C020 0000 0007 000965 LARL R2
000246 5020 D670 000965 ST R2,1648(,R13) # VN_cell
00024A A7F4 02F4 000965 J 050-CREATE-VSAM-MASTER-FILE
00024E 5820 D544 000965 L R2,1348(,R13) # PfmSv_Cell
000252 5020 D670 000965 ST R2,1648(,R13) # VN_cell
(1) Source code interspersed with the pseudo-assembler instructions
(2) Relative location of the object code instruction in the module, in
hexadecimal notation
(3) Object code instructions, in hexadecimal notation
The first two or four hexadecimal digits are the instruction, and the
remaining digits are the instruction operands. Some instructions have two
operands.
(4) Source line number associated with this assembler code
(5) Object code instructions, in compiler-generated pseudo assembler
(6) Explanation of the instruction and the operands used by the instructions
RELATED REFERENCES
Symbols used in LIST and MAP output on page 396
Example: Program prolog areas
The following example shows LIST output for the program prolog area. The
Program Prologue Area (PPA) is comprised of several sections that contain
information about the compiled program.
406 Enterprise COBOL for z/OS, V5.2 Programming Guide
There is a PPA1 for every procedure in your program, including procedures
generated by the compiler. The offset to its corresponding PPA1 is recorded at offset
12 (X'C') from the start of each procedure. The PPA1 contains information about the
procedure as well as offsets to the PPA2 and PPA3 sections.
For details on how to use the program prolog areas to locate information in the
listing file, see z/OS Language Environment Vendor Interfaces.
DATA VALIDATION AND UPDATE PROGRAM IGYTCARA Date 03/30/2013 Time 10:48:16
1 2 3 4
PPA1: Entry Point Constants
0081E0 1CCEA506 =F483304710 Flags
0081E4 00008310 =A(PPA2-IGYTCARA)
0081E8 00008378 =A(PPA3-IGYTCARA)
0081EC 00000000 =F0 No EPD
0081F0 FFFE0000 =F-131072 Register Save Mask
0081F4 40000000 =F1073741824 Member Flags
0081F8 90 =AL1(144) Flags
0081F9 000978 =AL3(2424) Callees DSA use/8
0081FC 0000 =AL1(0) Flags
0081FE 0012 =H18 Offset/2 to CDL
008200 D00006D0 =F-805304624 State variable location
008204 00000000 =F0 CDL function length/2
008208 00000000 =F0 CDL function EP offset
00820C 00000000 =F0 CDL prolog
008210 00000000 =F0 CDL epilog
008214 00000000 =F0 CDL end
008218 0008 **** AL2(8),CIGYTCARA
PPA1 End
There is one PPA2 for each program. The offset to the PPA2 is recorded in each PPA1.
The PPA2 contains offsets to the Time Stamp and Version Information section of
the listing as well as to the PPA4 section.
PPA2: Entry Point Constants
008310 04002203 =F67117571 Flags
008314 FFFF7CF0 =A(CEESTART-PPA2)
008318 00000030 =F48 A(PPA4-PPA2)
00831C FFFFFFB8 =A(TIMESTMP-PPA2)
008320 FFFF7CF0 =A(PrimaryEntryPoint-PPA2)
008324 02200000 =F35651584 Flags
PPA2 End
There is one PPA3 for each program (including each nested program) in a COBOL
source file. Each entry contains offsets, relative to the PPA3 itself, to the base locator
table and to the special register table. The PPA3 also contains an offset from the
start of the program to the first COBOL statement.
PPA3: Entry Point Constants
0014D8 00000000 =F0 Flags
0014DC 000000C0 =F192 A(Base_Locator_Table-PPA3)
0014E0 000000D8 =F216 A(Special_Register_Table-PPA3)
0014E0 00000184 =X184 A(User_Entry-CUEntry)
PPA3 End
There is one PPA4 for each program. It has offsets to various compiler generated
tables, such as the writable static area ( the Static Map and WSA24 sections). The
offset to the PPA4 is recorded in a field of the PPA2.
PPA4: Entry Point Constants
008340 08000000 =F134217728 Flags 1
008344 00020100 =F131328 Flags 2
008348 00000000 =F0 A(NORENTstatic)
00834C 00000000 =F0 Q(RENTstatic)
008350 00000000 =F0 A(DATA24_address_cell-RENTstatic)
008354 FFFF7CC0 =F-33600 A(Code-PPA4)
008358 00008398 =F33688 Code Length
00835C 00000000 =F0 Length NORENTstatic
008360 00002204 =F8708 Length RENTstatic
008364 00000000 =F0 Length DATA24
008368 002A =X2A A(CUName-PPA4)
PPA4 End
1 Relative location, in hexadecimal format, of the PPA field in the object
module
2 The contents of the field, in hexadecimal
3 An assembler-like syntax defining the field
4 A description of the contents of the field.
Chapter 19. Debugging 407
RELATED REFERENCES
z/OS Language Environment Vendor Interfaces
Example: Static map
The following example shows LIST output about the writable static area.
The STATIC MAP contains the level-1 symbols defined in the WORKING-STORAGE part
of the program. If compiled with the RENT option, the first column contains the
offset of the level-1 symbol from the start of the Working Storage Area (WSA) for
the program. For NORENT compilations, the offset is the start of the level-1 from a
block of storage allocated by the compiler. The starting address of this block
resides in the Constant Area. The second column is the size of the symbol,
including all of its sub-level members. The third column is the name.
* * * * * S T A T I C M A P * * * * *
OFFSET (HEX) LENGTH (HEX) NAME
0 14 BLF_Ptrs
14 C BLT_Ptrs
20 4 JNIENVPTR
28 2 RETURN-CODE
30 2 SORT-RETURN
38 8 SORT-CONTROL
40 4 SORT-CORE-SIZE
48 4 SORT-FILE-SIZE
50 4 SORT-MODE-SIZE
58 8 SORT-MESSAGE
60 4 TALLY
68 1 SHIFT-OUT
70 1 SHIFT-IN
78 4 XML-CODE
80 1E XML-EVENT
A0 4 XML-INFORMATION
A8 50 COMMUTER-FILE
F8 50 COMMUTER-FILE-MST
148 7A PRINT-FILE
1C8 1 WORKING-STORAGE-FOR-IGYCARA
1D0 2 COMP-CODE
1D8 3 WS-TYPE
1E0 2 I-F-STATUS-AREA
1E8 8 STATUS-AREA
1F0 2 UPDATE-FILE-STATUS
1F8 2 LOCCODE-FILE-STATUS
200 2 UPDPRINT-FILE-STATUS
208 3 FLAGS
If you compile with the compiler option DATA(24), a WSA 24 Map is generated. It
shows the names of the symbols that are mapped below the 16 MB line. The
symbols in the WORKING-STORAGE area in the source are mapped into the writable
static area which is shown in the Static Map.
* * * * * W S A 2 4 M A P * * * * *
OFFSET (HEX) LENGTH (HEX) NAME
0 4 JNIENVPTR
8 2 RETURN-CODE
10 2 SORT-RETURN
18 8 SORT-CONTROL
20 4 SORT-CORE-SIZE
28 4 SORT-FILE-SIZE
30 4 SORT-MODE-SIZE
38 8 SORT-MESSAGE
40 4 TALLY
408 Enterprise COBOL for z/OS, V5.2 Programming Guide
48 1 SHIFT-OUT
50 1 SHIFT-IN
58 4 XML-CODE
60 1E XML-EVENT
80 4 XML-INFORMATION
88 50 COMMUTER-FILE
D8 50 COMMUTER-FILE-MST
128 7A PRINT-FILE
1A8 1 WORKING-STORAGE-FOR-IGYCARA
1B0 2 COMP-CODE
1B8 3 WS-TYPE
1C0 2 I-F-STATUS-AREA
1C8 8 STATUS-AREA
1D0 2 UPDATE-FILE-STATUS
Example: Constant area
The following example shows LIST output about strings and other literals from the
COBOL source as well as those generated by the compiler.
The compiler generates loads from (and stores to) the Constant Area by loading
the starting address of Constant Area and adding the fixed offsets to the respective
constants or literals.
CONSTANT AREA:
(1) (2) (3) (4)
006A98 (+0) 00CCDDFF 00000000 C9C7E8E3 C3C1D9C1 00000000 00000000 C9C7E9E2 D9E3C3C4 |........IGYTCARA........IGZSRTCD|
006AB8 (+32) 40000A00 40000000 00000008 00000000 E2E8E2D6 E4E34040 00100000 00000000 | ... ...........SYSOUT ........|
006AD8 (+64) 0E000000 00000001 0F000000 0000001E 00000000 40000000 00000003 0064003C |.................... ...........|
006AF8 (+96) 000FE800 9F0F0000 00000011 00000000 E3D9C1D5 E2C1C3E3 4B40C3D6 C4C50000 |..Y.............TRANSACT. CODE..|
006B18 (+128) 0000000E 00000000 E2C8C9C6 E340C3D6 C4C54040 40400000 C8D6D4C5 40D3D6C3 |........SHIFT CODE ..HOME LOC|
006B38 (+160) 4B40C3D6 C4C50000 E6D6D9D2 40D3D6C3 4B40C3D6 C4C50000 D3C1E2E3 40D5C1D4 |. CODE..WORK LOC. CODE..LAST NAM|
006B58 (+192) C5404040 40400000 C9D5C9E3 C9C1D3E2 40404040 40400000 C4E4D7D3 C9C3C1E3 |E ..INITIALS ..DUPLICAT|
006B78 (+224) C540D9C5 C34B0000 D9C5C34B 40D5D6E3 40C6D6E4 D5C40000 C1C4C4D9 C5E2E240 |E REC...REC. NOT FOUND..ADDRESS |
006B98 (+256) 40404040 40400000 C3C9E3E8 40404040 40404040 40400000 E2E3C1E3 C540C3D6 | ..CITY ..STATE CO|
006BB8 (+288) C4C54040 40400000 E9C9D7C3 D6C4C540 40404040 40400000 C8D6D4C5 40D7C8D6 |DE ..ZIPCODE ..HOME PHO|
006BD8 (+320) D5C54040 40400000 E6D6D9D2 40D7C8D6 D5C54040 40400000 C8D6D4C5 40D1E4D5 |NE ..WORK PHONE ..HOME JUN|
006BF8 (+352) C3E3C9D6 D5400000 E6D6D9D2 40D1E4D5 C3E3C9D6 D5400000 C4D9C9E5 C9D5C740 |CTION ..WORK JUNCTION ..DRIVING |
006C18 (+384) E2E3C1E3 E4E20000 40D9C5D7 D6D9E340 407B7A40 C9C7E8E3 C3C1D9C1 40404040 |STATUS.. REPORT #: IGYTCARA |
006C38 (+416) 40404040 40404040 40404040 40404040 40404040 40404040 40404000 00000033 | .....|
006C58 (+448) C3D6D4D4 E4E3C5D9 40C6C9D3 C540E4D7 C4C1E3C5 40D3C9E2 E3404040 40404040 |COMMUTER FILE UPDATE LIST |
006C78 (+480) 40404040 40404040 40404040 40404040 40400000 00000032 40404040 40404040 | ...... |
006C98 (+512) D7C1C7C5 407B7A40 00000000 00000010 40D7D9D6 C7D9C1D4 407B7A40 C9C7E8E3 |PAGE #: ........ PROGRAM #: IGYT|
006CB8 (+544) C3C1D9C1 40404040 404040D9 E4D540E3 C9D4C57A 40000000 00000025 7A000000 |CARA RUN TIME: .......:...|
006CD8 (+576) 00000030 00000000 D9E4D540 C4C1E3C5 7A400000 0000000A 61000000 0000000B |........RUN DATE: ....../.......|
(1) Offset in csect.
(2) Offset in base 10.
(3) 8 columns containing the bytes in the Constant Area
(4) Character representation. A dot (.) is used for non-printable characters.
Example: Base locator table
The following example shows LIST output for the base locator table.
Base Locator Table
008AB0 01 =X1 Table Version
008AB1 00 =X0 Reserved
008AB2 0008 =H8 Header length
008AB4 00000010 =F16 Array byte length
008AB8 2A00 =X2A00 Flags & info (element 1)
008ABA 00000014 =X14 Offset to cells
008ABE 03 =X3 Cell count
008ABF 0A00 =XA00 Flags & info (element 2)
008AC1 00000000 =X0 Offset to cells
008AC5 05 =X5 Cell count
008AC6 0000 =X0 Flags & info (end of array)
Base Locator Table End
For more information about the base locator table, see z/OS Language Environment
Vendor Interfaces.
RELATED REFERENCES
z/OS Language Environment Vendor Interfaces (Base locator table)
Chapter 19. Debugging 409
Example: special register table
The following example shows LIST output for the special register table. The special
register table has a similar format to the base locator table.
Special Register Table
0015B0 01 =X1 Table Version
0015B1 00 =X0 Reserved
0015B2 0008 =H8 Header length
0015B4 00000006 =F6 Array byte length
0015B8 12 =X12 Flags & info (element 1)
0015B9 00000018 =X18 Offset to cells
0015BD 00 =X0 Flags & info (end of array)
Special Register Table End
Each entry in the special register table consists of the following items:
v A byte which represents the following information:
Special register ID number (bits 0 - 4). ID = 1 represents the RETURN-CODE
register
Access mode (bits 5 - 8)
- MODE = 0; Base Address = Top of Stack
- MODE = 1; Base Addr = NORENT Static
- MODE = 2; Base Addr = 32-bit RENT static
- MODE = 3; 24-bit NORENT static
v An offset to the special register
The end of the special register table is indicated by a null byte.
Example: External symbols
The following example shows LIST output for external symbols defined by, or
referred to in your program. The external symbol dictionary contains one entry per
external symbol defined by or referred to in the program.
Each entry contains the address, length and symbol type. Symbol types are:
ED External Definition
SD Section Definition
LD Label Definition
ER External Reference
PR Pseudo Register
E X T E R N A L S Y M B O L D I C T I O N A R Y
TYPE ID ADDR LENGTH NAME
SD 1 000000 000000 IGYTCARA
ED 2 000000 000000 C_CEESG003
ED 3 000000 008AC8 C_CODE
LD 4 000000 000000 IGYTCARA#C
ER 5 000000 000000 CEESTART
ER 6 000000 000000 CEEBETBL
ED 7 000000 000000 C_WSA
PR 8 000000 002204 IGYTCARA#S
ED 9 000000 000022 B_IDRL
ER 10 000000 000000 IGZXBST
ER 11 000000 000000 IGYTCARA
ER 12 000000 000000 IGZXPRS
ER 13 000000 000000 IGZXCMSG
ER 14 000000 000000 IGZXDSP
ER 15 000000 000000 IGZXVCLS
410 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: DSA memory map (Automatic map)
The following example shows LIST output for the dynamic save area (DSA). The
DSA contains information about the contents of the storage acquired when a
separately compiled procedure is entered.
* * * * * A U T O M A T I C M A P * * * * *
1 2 3
OFFSET (HEX) LENGTH (HEX) NAME
Block name: IGYTCARA
80 4 _@CAA
C8 3 _BEtemp200
CC 3 _BEtemp204
D0 3 _BEtemp208
D4 3 _BEtemp212
D8 3 _BEtemp216
DC 3 _BEtemp220
E0 3 _BEtemp224
E4 3 _BEtemp228
E8 10 _BEtemp232
F8 20 _BEtemp248
118 20 _BEtemp280
138 4 _BEtemp312
13C 4 _BEtemp316
140 4 _BEtemp320
144 4 _BEtemp324
148 4 _BEtemp328
14C 4 _BEtemp332
150 4 _BEtemp336
154 4 _BEtemp340
158 4 _BEtemp344
15C 4 _BEtemp348
160 4 _BEtemp352
164 4 _BEtemp356
168 4 _BEtemp360
16C 4 _BEtemp364
170 4 _BEtemp368
174 4 _BEtemp372
178 4 _BEtemp376
(1) Hexadecimal offset of the DSA field from the start of the DSA
(2) Length (in hexidecimal) of the DSA field
(3) Symbol name
Example: XREF output: data-name cross-references
The following example shows a sorted cross-reference of data-names that is
produced by the XREF compiler option. Numbers in parentheses refer to notes after
the example.
An "M" preceding a data-name reference indicates that the
data-name is modified by this reference.
(1) (2) (3)
Defined Cross-reference of data-names References
265 ABEND-ITEM1
266 ABEND-ITEM2
347 ADD-CODE . . . . . . . . . . . 1102 1162
381 ADDRESS-ERROR. . . . . . . . . M1126
280 AREA-CODE. . . . . . . . . . . 1236 1261 1324 1345
382 CITY-ERROR . . . . . . . . . . M1129
Chapter 19. Debugging 411
(4)
Context usage is indicated by the letter preceding a procedure-name
reference. These letters and their meanings are:
A = ALTER (procedure-name)
D = GO TO (procedure-name) DEPENDING ON
E = End of range of (PERFORM) through (procedure-name)
G = GO TO (procedure-name)
P = PERFORM (procedure-name)
T = (ALTER) TO PROCEED TO (procedure-name)
U = USE FOR DEBUGGING (procedure-name)
(5) (6) (7)
Defined Cross-reference of procedures References
877 000-DO-MAIN-LOGIC
930 050-CREATE-STL-MASTER-FILE . . P879
982 100-INITIALIZE-PARAGRAPH . . . P880
1441 1100-PRINT-I-F-HEADINGS. . . . P915
1481 1200-PRINT-I-F-DATA. . . . . . P916
1543 1210-GET-MILES-TIME. . . . . . P1510
1636 1220-STORE-MILES-TIME. . . . . P1511
1652 1230-PRINT-SUB-I-F-DATA. . . . P1532
1676 1240-COMPUTE-SUMMARY . . . . . P1533
1050 200-EDIT-UPDATE-TRANSACTION. . P886
1124 210-EDIT-THE-REST. . . . . . . P1116
1159 300-UPDATE-COMMUTER-RECORD . . P888
1207 310-FORMAT-COMMUTER-RECORD . . P1164 P1179
1258 320-PRINT-COMMUTER-RECORD. . . P1165 P1176 P1182 P1192
1288 330-PRINT-REPORT . . . . . . . P1178 P1202 P1256 P1280 P1340 P1365 P1369
1312 400-PRINT-TRANSACTION-ERRORS . P890
Cross-reference of data-names:
(1) Line number where the name was defined.
(2) Data-name.
(3) Line numbers where the name was used. If M precedes the line number, the
data item was explicitly modified at the location.
Cross-reference of procedure references:
(4) Explanations of the context usage codes for procedure references.
(5) Line number where the procedure-name is defined.
(6) Procedure-name.
(7) Line numbers where the procedure is referenced, and the context usage
code for the procedure.
Example: XREF output: program-name cross-references
Example: XREF output: COPY/BASIS cross-references on page 413
Example: XREF output: embedded cross-reference on page 414
Example: XREF output: program-name cross-references
The following example shows a sorted cross-reference of program-names produced
by the XREF compiler option. Numbers in parentheses refer to notes that follow the
example.
(1) (2) (3)
Defined Cross-reference of programs References
EXTERNAL EXTERNAL1. . . . . . . . . . . 25
2 X. . . . . . . . . . . . . . . 41
12 X1 . . . . . . . . . . . . . . 33 7
20 X11. . . . . . . . . . . . . . 25 16
27 X12. . . . . . . . . . . . . . 32 17
35 X2 . . . . . . . . . . . . . . 40 8
412 Enterprise COBOL for z/OS, V5.2 Programming Guide
(1) Line number where the program-name was defined. If the program is
external, the word EXTERNAL is displayed instead of a definition line
number.
(2) Program-name.
(3) Line numbers where the program is referenced.
Example: XREF output: COPY/BASIS cross-references
The following example shows a sorted cross-reference of copybooks to the
library-names and data-set names of the associated copybooks, produced by the
XREF compiler option under z/OS. Numbers in parentheses refer to notes after the
example.
COPY/BASIS cross-reference of text-names, library names
(1) (1) (2) (3) (4)
Text-name Library File name Concat ISPF
(Member) (DDNAME) (Data set name) Level Created
ACTIONS OTHERLIB USERID.COBOL.COPY 0 1992/07/11
ACTIONS SYSLIB USERID.COBOL.COPY 0 1992/07/11
CUSTOMER ALTDDXXY USERID.COBOL.LIB3 0 2007/06/01
CUSTOMER SYSLIB USERID.COBOL.LIB2PDSE 1 2007/06/07
HOUSE ALTDDXXY USERID.COBOL.LIB2 1 2007/06/07
HOUSE SYSLIB USERID.COBOL.LIB2PDSE 1
IMOTOR SYSLIB USERID.COBOL.LIB4X 3 2007/06/07
ISOVERFY SYSLIB USERID.COBOL.COPY 0
NSMAP SYSLIB USERID.COBOL.LIB3 2
(1) Text-name and library (an abbreviation for library-name) are from the
statement COPY text-name OF library-name in the source, for example,
Copy ACTIONS Of OTHERLIB.
(2) The name of the data set from which the COPY member was copied.
(3) Abbreviation for concatenation level. Indicates how many levels deep a
given data set is from the first data set in the concatenation for a given
ddname.
For example, four data sets in the example above are concatenated to
ddname SYSLIB:
DDNAME DSNAME (concatenation level)
SYSLIB DD DSN=USERID.COBOL.COPY, 0
DD DSN=USERID.COBOL.LIB2PDSE, 1
DD DSN=USERID.COBOL.LIB3, 2
DD DSN=USERID.COBOL.LIB4X 3
Thus for example member NSMAP shown in the listing above was found
in data set USERID.COBOL.LIB3, which is two levels down from the first
data set in the SYSLIB concatenation.
(4) Creation date is shown if the PDS or PDSE was edited with STATS ON in
ISPF.
Tip: Under z/OS, if there is more than one data set in your SYSLIB concatenation,
the COPY/BASIS cross-reference might in some cases be incomplete or missing. For
details, see the related reference about the XREF compiler option.
If you compile in the z/OS UNIX shell, the cross-reference looks like the excerpt
shown below.
Chapter 19. Debugging 413
COPY/BASIS cross-reference of text-names, library names, and file names
(5) (5) (6)
Text-name Library-name File name
/copydir/copyM.cbl SYSLIB /u/JSMITH/cobol//copydir/copyM.cbl
/copyA.cpy SYSLIB /u/JSMITH/cobol//copyA.cpy
cobol/copyA.cpy ALTDD2 /u/JSMITH/cobol/copyA.cpy
copy/stuff.cpy ALTDD2 /u/JSMITH/copy/stuff.cpy
copydir/copyM.cbl SYSLIB /u/JSMITH/cobol/copydir/copyM.cbl
copydir/copyM.cbl SYSLIB (default) /u/JSMITH/cobol/copydir/copyM.cbl
stuff.cpy ALTDD /u/JSMITH/copy/stuff.cpy
"copyA.cpy" (7) SYSLIB (default) /u/JSMITH/cobol/copyA.cpy
"reallyXXVeryLongLon> SYSLIB (default) (8)<JSMITH/cobol/reallyXXVeryLongLongName.cpy
OTHERDD ALTDD2 /u/JSMITH//copy/other.cob
. . .
Note: Some names were truncated. > = truncated on right < = truncated on left
(5) From the COPY statement in the source; for example the COPY statement
corresponding to the third item in the cross-reference above would be:
COPY cobol/copyA.cpy Of ALTDD2
(6) The fully qualified path of the file from which the COPY member was
copied
(7) Truncation of a long text-name or library-name on the right is marked by a
greater-than sign (>).
(8) Truncation of a long file name on the left is marked by a less-than sign (<).
RELATED REFERENCES
XREF on page 369
Example: XREF output: embedded cross-reference
The following example shows a modified cross-reference that is embedded in the
source listing. The cross-reference is produced by the XREF compiler option.
LineID PL SL ----+-*A-1-B--+----2----+----3----+----4----+----5----+----6----+----7-|--+----8 Map and Cross Reference
. . .
000878 procedure division.
000879 000-do-main-logic.
000880 display "PROGRAM IGYTCARA - Beginning".
000881 perform 050-create-vsam-master-file. 932 (1)
000882 perform 100-initialize-paragraph. 984
000883 read update-transaction-file into ws-transaction-record 204 340
000884 at end
000885 1 set transaction-eof to true 254
000886 end-read.
. . .
000984 100-initialize-paragraph.
000985 move spaces to ws-transaction-record IMP 340 (2)
000986 move spaces to ws-commuter-record IMP 316
000987 move zeroes to commuter-zipcode IMP 327
000988 move zeroes to commuter-home-phone IMP 328
000989 move zeroes to commuter-work-phone IMP 329
000990 move zeroes to commuter-update-date IMP 333
000991 open input update-transaction-file 204
000992 location-file 193
000993 i-o commuter-file 181
000994 output print-file 217
. . .
001442 1100-print-i-f-headings.
001443
001444 open output print-file. 217
001445
001446 move function when-compiled to when-comp. IFN 698 (2)
001447 move when-comp (5:2) to compile-month. 698 640
001448 move when-comp (7:2) to compile-day. 698 642
001449 move when-comp (3:2) to compile-year. 698 644
001450
001451 move function current-date (5:2) to current-month. IFN 649
001452 move function current-date (7:2) to current-day. IFN 651
001453 move function current-date (3:2) to current-year. IFN 653
001454
001455 write print-record from i-f-header-line-1 222 635
001456 after new-page. 138
. . .
(1) Line number of the definition of the data-name or procedure-name in the
program
414 Enterprise COBOL for z/OS, V5.2 Programming Guide
(2) Special definition symbols:
UND The user name is undefined.
DUP The user name is defined more than once.
IMP Implicitly defined name, such as special registers and figurative
constants.
IFN Intrinsic function reference.
EXT External reference.
* The program-name is unresolved because the NOCOMPILE option is
in effect.
Example: OFFSET compiler output
The following example shows a compiler listing that has a condensed verb listing,
global tables, WORKING-STORAGE information, and literals. The listing is output from
the OFFSET compiler option.
DATA VALIDATION AND UPDATE PROGRAM IGYTCARA Date 03/30/2013 Time 10:48:16
. . .
(1) (2) (3)
LINE # HEXLOC VERB LINE # HEXLOC VERB LINE # HEXLOC VERB
000880 0026F0 DISPLAY 000881 002702 PERFORM 000933 002702 OPEN
000934 002722 IF 000935 00272C DISPLAY 000936 002736 PERFORM
001389 002736 DISPLAY 001390 002740 DISPLAY 001391 00274A DISPLAY
001392 002754 DISPLAY 001393 00275E DISPLAY 001394 002768 DISPLAY
001395 002772 DISPLAY 000937 00277C PERFORM 001434 00277C DISPLAY
001435 002786 STOP 000939 0027A2 MOVE 000940 0027AC WRITE
000941 0027D6 IF 000942 0027E0 DISPLAY 000943 0027EA PERFORM
001389 0027EA DISPLAY 001390 0027F4 DISPLAY 001391 0027FE DISPLAY
001392 002808 DISPLAY 001393 002812 DISPLAY 001394 00281C DISPLAY
001395 002826 DISPLAY 000944 002830 DISPLAY 000945 00283A PERFORM
001403 00283A DISPLAY 001404 002844 DISPLAY 001405 00284E DISPLAY
001406 002858 DISPLAY 001407 002862 CALL 000947 002888 CLOSE
(1) Line number. Your line numbers or compiler-generated line numbers are
listed.
(2) Offset, from the start of the program, of the code generated for this verb
(in hexadecimal notation).
The verbs are listed in the order in which they occur and are listed once
for each time they are used.
(3) Verb used.
RELATED REFERENCES
OFFSET on page 341
Example: VBREF compiler output
The following example shows an alphabetic listing of all the verbs in a program,
and shows where each is referenced. The listing is produced by the VBREF compiler
option.
(1) (2) (3)
2 ACCEPT . . . . . . . . . . . . 1010 1012
2 ADD. . . . . . . . . . . . . . 1290 1306
1 CALL . . . . . . . . . . . . . 1406
5 CLOSE. . . . . . . . . . . . . 898 945 970 1526 1535
20 COMPUTE. . . . . . . . . . . . 1506 1640 1644 1657 1660 1663 1664 1665 1678 1682 1686 1691 1696 1701 1709 1713
1718 1723 1728 1733
2 CONTINUE . . . . . . . . . . . 1062 1069
2 DELETE . . . . . . . . . . . . 964 1193
48 DISPLAY. . . . . . . . . . . . 878 906 917 918 919 933 940 942 947 953 960 966 972 996 997 998 999 1003 1006 1037
1090 1168 1171 1185 1195 1387 1388 1389 1390 1391 1392 1393 1401 1402 1403 1404
1405 1433 1485 1486 1492 1497 1498 1520 1521 1528 1529 1624
2 EVALUATE . . . . . . . . . . . 1161 1557
47 IF . . . . . . . . . . . . . . 887 905 932 939 946 952 959 965 971 993 1002 1036 1051 1054 1071 1074 1077 1089
1102 1111 1115 1125 1128 1131 1134 1137 1141 1145 1148 1151 1167 1184 1194 1240
Chapter 19. Debugging 415
1247 1265 1272 1289 1321 1330 1339 1351 1361 1484 1496 1519 1527
183 MOVE . . . . . . . . . . . . . 907 937 957 983 984 985 986 987 988 1004 1011 1013 1025 1038 1052 1055 1060 1067
1072 1075 1078 1079 1080 1081 1082 1083 1091 1103 1112 1126 1129 1132 1135 1139
1143 1146 1149 1152 1160 1163 1169 1175 1177 1180 1181 1186 1191 1196 1201 1208
1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1229 1230
1231 1232 1233 1234 1235 1239 1241 1244 1248 1250 1251 1253 1254 1255 1257 1258
1259 1260 1264 1266 1269 1273 1275 1276 1278 1279 1291 1294 1299 1301 1303 1307
1313 1314 1315 1316 1317 1318 1319 1320 1322 1323 1327 1328 1331 1333 1334 1336
1338 1341 1342 1343 1344 1348 1349 1352 1354 1355 1357 1362 1364 1368 1374 1375
1376 1377 1378 1379 1380 1381 1414 1417 1422 1425 1445 1446 1447 1448 1450 1451
1452 1457 1464 1489 1502 1507 1508 1509 1517 1551 1561 1566 1571 1576 1581 1586
1591 1596 1601 1606 1611 1616 1621 1626 1627 1679 1683 1688 1693 1698 1703 1710
1715 1720 1725 1730 1735
5 OPEN . . . . . . . . . . . . . 931 951 989 1443 1483
62 PERFORM. . . . . . . . . . . . 879 880 885 886 888 890 892 908 909 915 916 934 935 941 943 948 949 954 955 961
962 967 968 973 974 1000 1005 1008 1023 1039 1092 1093 1116 1164 1165 1170 1172
1176 1178 1179 1182 1187 1188 1192 1197 1198 1202 1246 1256 1271 1280 1329 1340
1350 1359 1365 1369 1504 1510 1511 1532 1533
8 READ . . . . . . . . . . . . . 881 893 958 1014 1026 1085 1490 1514
1 REWRITE. . . . . . . . . . . . 1183
4 SEARCH . . . . . . . . . . . . 1058 1065 1413 1421
46 SET. . . . . . . . . . . . . . 883 895 1016 1028 1041 1057 1064 1084 1087 1363 1412 1420 1493 1499 1516 1522 1548
1550 1559 1560 1564 1565 1569 1570 1574 1575 1579 1580 1584 1585 1589 1590 1594
1595 1599 1600 1604 1605 1609 1610 1614 1615 1619 1620 1639 1643
2 STOP . . . . . . . . . . . . . 920 1434
4 STRING . . . . . . . . . . . . 1236 1261 1324 1345
33 WRITE. . . . . . . . . . . . . 938 1166 1292 1293 1295 1296 1297 1298 1300 1302 1305 1454 1459 1462 1465 1467 1469
1471 1512 1654 1655 1667 1668 1669 1740 1742 1744 1745 1746 1747 1748 1749 1750
(1) Number of times the verb is used in the program
(2) Verb
(3) Line numbers where the verb is used
416 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 3. Targeting COBOL programs for certain environments
Copyright IBM Corp. 1991, 2015 417
418 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 20. Developing COBOL programs for CICS
COBOL programs that are written for CICS can run under CICS Transaction Server.
CICS COBOL application programs that use CICS services must use the CICS
command-level interface.
When you use the CICS compiler option, the Enterprise COBOL compiler handles
both native COBOL statements and embedded CICS statements in the source
program. You can still use the separate CICS translator to translate CICS
statements to COBOL code, but use of the integrated CICS translator is
recommended instead.
| After you compile and bind your program, you need to do some other steps such
as updating CICS tables before you can run the COBOL program under CICS.
However, these CICS topics are beyond the scope of COBOL information. For
further information, see the related tasks.
You can determine how runtime errors are handled by setting the CBLPSHPOP
runtime option. For information about CICS HANDLE and CBLPSHPOP, see the related
tasks.
RELATED CONCEPTS
Integrated CICS translator on page 425
RELATED TASKS
Coding COBOL programs to run under CICS
Compiling with the CICS option on page 423
Using the separate CICS translator on page 426
Handling errors by using CICS HANDLE on page 428
Language Environment Programming Guide (Condition handling under CICS:
using the CBLPSHPOP runtime option)
CICS Application Programming Guide
RELATED REFERENCES
CICS on page 312
Coding COBOL programs to run under CICS
To code a program to run under CICS, code CICS commands in the PROCEDURE
DIVISION by using the EXEC CICS command format.
EXEC CICS command-name command-options
END-EXEC
CICS commands have the basic format shown above. Within EXEC commands, use
the space as a word separator; do not use a comma or a semicolon. Do not code
COBOL statements within EXEC CICS commands.
Restriction: You cannot run COBOL programs that have object-oriented syntax for
Java interoperability in CICS. In addition, if you write programs to run under
CICS, do not use the following code:
v FILE-CONTROL entry in the ENVIRONMENT DIVISION, unless the FILE-CONTROL entry
is used for a SORT statement
Copyright IBM Corp. 1991, 2015 419
v FILE SECTION of the DATA DIVISION, unless the FILE SECTION is used for a SORT
statement
v User-specified parameters to the main program
v USE declaratives (except USE FOR DEBUGGING)
v These COBOL language statements:
ACCEPT format 1: data transfer (you can use format-2 ACCEPT to retrieve the
system date and time)
CLOSE
DELETE
DISPLAY UPON CONSOLE
DISPLAY UPON SYSPUNCH
MERGE
OPEN
READ
RERUN
REWRITE
START
STOP literal
WRITE
If you plan to use the separate CICS translator, you must put any REPLACE
statements that contain EXEC commands after the PROCEDURE DIVISION header for
the program, otherwise the commands will not be translated.
Coding file input and output: You must use CICS commands for most input and
output processing. Therefore, do not describe files or code any OPEN, CLOSE, READ,
START, REWRITE, WRITE, or DELETE statements. Instead, use CICS commands to
retrieve, update, insert, and delete data.
Coding a COBOL program to run above the 16 MB line: Under Enterprise
COBOL, the following restrictions apply when you code a COBOL program to run
above the 16 MB line:
v If you use IMS/ESA without DBCTL, DL/I CALL statements are supported only if
all the data passed in the call resides below the 16 MB line. Therefore, you must
specify the DATA(24) compiler option. However, if you use IMS/ESA with DBCTL,
you can use the DATA(31) compiler option instead and pass data that resides
above the 16 MB line.
If you use EXEC DLI instead of DL/I CALL statements, you can specify DATA(31)
regardless of the level of the IMS product.
v If the receiving program is link-edited with AMODE 31, addresses that are passed
must be 31 bits long, or 24 bits long with the leftmost byte set to zeros.
v If the receiving program is link-edited with AMODE 24, addresses that are passed
must be 24 bits long.
Displaying the contents of data items: DISPLAY to the system logical output device
(SYSOUT, SYSLIST, SYSLST) is supported under CICS. The DISPLAY output is
written to the Language Environment message file (transient data queue CESE).
DISPLAY . . . UPON CONSOLE and DISPLAY . . . UPON SYSPUNCH, however, are not
| allowed. You can specify the DISPSIGN option to control output formatting for
| DISPLAY of signed numeric items.
420 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED CONCEPTS
Integrated CICS translator on page 425
RELATED TASKS
Sorting under CICS on page 237
Getting the system date under CICS
Calling to or from COBOL programs
Determining the success of ECI calls on page 423
Using the separate CICS translator on page 426
RELATED REFERENCES
CICS SORT application restrictions on page 237
DISPSIGN on page 320
Getting the system date under CICS
To retrieve the system date in a CICS program, use a format-2 ACCEPT statement or
the CURRENT-DATE intrinsic function.
You can use any of these format-2 ACCEPT statements in CICS to get the system
date:
v ACCEPT identifier-2 FROM DATE (two-digit year)
v ACCEPT identifier-2 FROM DATE YYYYMMDD
v ACCEPT identifier-2 FROM DAY (two-digit year)
v ACCEPT identifier-2 FROM DAY YYYYDDD
v ACCEPT identifier-2 FROM DAY-OF-WEEK (one-digit integer, where 1 represents
Monday)
You can use this format-2 ACCEPT statement in CICS to get the system time:
v ACCEPT identifier-2 FROM TIME
Alternatively, you can use the CURRENT-DATE intrinsic function, which can also
provide the time.
These methods work in both CICS and non-CICS environments.
Do not use a format-1 ACCEPT statement in a CICS program.
RELATED TASKS
Assigning input from a screen or file (ACCEPT) on page 34
RELATED REFERENCES
CURRENT-DATE (Enterprise COBOL Language Reference)
Calling to or from COBOL programs
You can make calls to or from VS COBOL II, COBOL for MVS & VM, COBOL for
OS/390 & VM, and Enterprise COBOL programs by using the CALL statement.
If you are calling a separately compiled COBOL program that was processed with
either the separate CICS translator or the integrated CICS translator, you must pass
DFHEIBLK and DFHCOMMAREA as the first two parameters in the CALL statement.
Chapter 20. Developing COBOL programs for CICS 421
Called programs that are processed by the separate CICS translator or the
integrated CICS translator can contain any function that is supported by CICS for
the language.
Dynamic calls:
You can use COBOL dynamic calls when running under CICS. If a COBOL
program contains EXEC CICS statements or contains EXEC SQL statements, the
NODYNAM compiler option is required. To dynamically call a program in this case,
you can use CALL identifier with the NODYNAM compiler option.
If a COBOL program contains no EXEC CICS statements and contains no EXEC SQL
statements, there is no requirement to compile with NODYNAM. To dynamically call a
program in this case, you can use either CALL literal with the DYNAM compiler option,
or CALL identifier.
| Note: END-EXEC cannot be followed by a period when it is associated with EXEC
| CICS statements even though it is required for EXEC SQL statements.
You must define dynamically called programs in the CICS program processing
table (PPT) if you are not using CICS autoinstall. Under CICS, COBOL programs
do not support dynamic calls to subprograms that have the RELOAD=YES option
coded in their CICS PROGRAM definition. Dynamic calls to programs that are defined
with RELOAD=YES can cause a storage shortage. Use the RELOAD=NO option for
programs that are to be dynamically called by COBOL.
Interlanguage communication (ILC):
Support for ILC with other high-level languages is available. Where ILC is not
supported, you can use CICS LINK, XCTL, and RETURN instead.
The following table shows the calling relationship between COBOL and assembler
programs. In the table, assembler programs that conform to the interface that is
described in the Language Environment Programming Guide are called Language
Environment-conforming assembler programs. Those that do not conform to the
interface are non-Language Environment-conforming assembler programs.
Table 55. Calls between COBOL and assembler under CICS
Language Non-Language
Calls between COBOL and Environment-conforming Environment-conforming
assembler programs assembler program assembler program
From an Enterprise COBOL Yes Yes
program to the assembler
program?
From the assembler program to Yes No
an Enterprise COBOL program?
Nested programs:
When you compile with the integrated CICS translator, the translator generates the
DFHEIBLK and DFHCOMMAREA control blocks with the GLOBAL clause in the outermost
program. Therefore if you code nested programs, you do not have to pass these
control blocks as arguments on calls to the nested programs.
422 Enterprise COBOL for z/OS, V5.2 Programming Guide
If you code nested programs and you plan to use the separate CICS translator,
pass DFHEIBLK and DFHCOMMAREA as parameters to the nested programs that contain
EXEC commands or references to the EXEC interface block (EIB). You must pass the
same parameters also to any program that forms part of the control hierarchy
between such a program and its top-level program.
RELATED CONCEPTS
Integrated CICS translator on page 425
RELATED TASKS
Using the separate CICS translator on page 426
Choosing the DYNAM or NODYNAM compiler option on page 441
Handling errors when calling programs on page 250
Language Environment Writing ILC Communication Applications (ILC under CICS)
CICS External Interfaces Guide
Language Environment Programming Guide
RELATED REFERENCES
DYNAM on page 323
Determining the success of ECI calls
After calls to the external CICS interface (ECI), the content of the RETURN-CODE
special register is set to an unpredictable value. Therefore, even if your COBOL
program terminates normally after successfully using the external CICS interface,
the job step could end with an undefined return code.
To ensure that a meaningful return code occurs at termination, set the RETURN-CODE
special register before you terminate your program. To make the job return code
reflect the status of the last call to CICS, set the RETURN-CODE special register based
on the response codes from the last call to the external CICS interface.
RELATED TASKS
CICS External Interfaces Guide
Compiling with the CICS option
Use the CICS compiler option to enable the integrated CICS translator and to
specify CICS suboptions.
If you specify the NOCICS option, the compiler diagnoses and discards any CICS
statements that it finds in your source program. If you have already used the
separate CICS translator, you must use NOCICS.
You can specify the CICS option in any of the compiler option sources: compiler
invocation, PROCESS or CBL statements, or installation default. If the CICS option is
the COBOL installation default, you cannot specify CICS suboptions. However,
making the CICS option the installation default is not recommended, because the
changes that are made by the integrated CICS translator are not appropriate for
non-CICS applications.
All CBL or PROCESS statements must precede any comment lines, in accordance with
the rules for Enterprise COBOL.
Chapter 20. Developing COBOL programs for CICS 423
The COBOL compiler passes to the integrated CICS translator the CICS suboption
string that you provide in the CICS compiler option. The compiler does not analyze
the suboption string.
When you use the integrated CICS translator, you must compile with the following
options:
Table 56. Compiler options required for the integrated CICS translator
Compiler option Comment
| AFP If your code runs on a version of CICS Transaction Server that
| is earlier than V4.1, you must specify AFP(VOLATILE).
CICS If you specify NOLIB, DYNAM, or NORENT, the compiler forces
NODYNAM, and RENT on.
NODYNAM Must be in effect with CICS
RENT Must be in effect with CICS
In addition, IBM recommends that you use the compiler option WORD(CICS) to
cause the compiler to flag language elements that are not supported under CICS.
To compile your program with the integrated CICS translator, you can use the
standard JCL procedural statements that are supplied with COBOL. In addition to
specifying the above compiler options, you must change your JCL in two ways:
v Specify the STEPLIB override for the COBOL step.
v Add the data set that contains the integrated CICS translator services, unless
these services are in the linklist.
| The default name of the data set for CICS Transaction Server V5R1 is
| CICSTS51.CICS.SDFHLOAD, but your installation might have changed the name.
For example, you might have the following line in your JCL:
//STEPLIB DD DSN=CICSTS41.CICS.SDFHLOAD,DISP=SHR
The COBOL compiler listing includes the error diagnostics (such as syntax errors
in the CICS statements) that the integrated CICS translator generates. The listing
reflects the input source; it does not include the COBOL statements that the
integrated CICS translator generates.
Compiling a sequence of programs: When you use the CICS option to compile a
source file that contains a sequence of COBOL programs, the order of precedence
of the options from highest to lowest is:
v Options that are specified in the CBL or PROCESS card that initiates the unit of
compilation
v Options that are specified when the compiler is started
v CICS default options
RELATED CONCEPTS
Integrated CICS translator on page 425
RELATED TASKS
Coding COBOL programs to run under CICS on page 419
Separating CICS suboptions on page 425
CICS Application Programming Guide
424 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
CICS on page 312
Conflicting compiler options on page 304
Separating CICS suboptions
You can partition the specification of CICS suboptions into multiple CBL statements.
CICS suboptions are cumulative. The compiler concatenates them from multiple
sources in the order that they are specified.
For example, suppose that a JCL file has the following code:
//STEP1 EXEC IGYWC, . . .
//PARM.COBOL="CICS("FLAG(I)")"
//COBOL.SYSIN DD *
CBL CICS("DEBUG")
CBL CICS("LINKAGE")
IDENTIFICATION DIVISION.
PROGRAM-ID. COBOL1.
During compilation, the compiler passes the following CICS suboption string to
the integrated CICS translator:
"FLAG(I) DEBUG LINKAGE"
The concatenated strings are delimited with single spaces and with a quotation
mark or single quotation mark around the group. When the compiler finds
multiple instances of the same CICS suboption, the last specification of the
suboption in the concatenated string takes effect. The compiler limits the length of
the concatenated CICS suboption string to 4 KB.
RELATED REFERENCES
CICS on page 312
Integrated CICS translator
When you compile a COBOL program using the CICS compiler option, the COBOL
compiler works with the integrated CICS translator to handle both native COBOL
and embedded CICS statements in the source program.
When the compiler encounters CICS statements, and at other significant points in
the source program, the compiler interfaces with the integrated CICS translator. All
text between EXEC CICS and END-EXEC statements is passed to the translator. The
translator takes appropriate actions and then returns to the compiler, typically
indicating which native language statements to generate.
Although you can still translate embedded CICS statements separately, it is
recommended that you use the integrated CICS translator instead. Certain
restrictions that apply when you use the separate translator do not apply when
you use the integrated translator, and using the integrated translator provides
several advantages:
v You can use Debug Tool to debug the original source instead of the expanded
source that the separate CICS translator generates.
v You do not need to separately translate the EXEC CICS or EXEC DLI statements
that are in copybooks.
v There is no intermediate data set for a translated but not compiled version of the
source program.
v Only one output listing instead of two is produced.
Chapter 20. Developing COBOL programs for CICS 425
v Using nested programs that contain EXEC CICS statements is simpler.
DFHCOMMAREA and DFHEIBLK are generated with the GLOBAL attribute in the
outermost program. You do not need to pass them as arguments on calls to
nested programs or specify them in the USING phrase of the PROCEDURE DIVISION
header of nested programs.
v You can keep nested programs that contain EXEC CICS statements in separate
files, and include those nested programs by using COPY statements.
v REPLACE statements can affect EXEC CICS statements.
v You can compile programs that contain CICS statements in a batch compilation
(compilation of a sequence of programs).
v Because the compiler generates binary fields in CICS control blocks with format
COMP-5 instead of BINARY, there is no dependency on the setting of the TRUNC
compiler option. You can use any setting of the TRUNC option in CICS programs,
subject only to the requirements of the application logic and use of user-defined
binary fields.
Note: The CICS documentation states that the EXCI translator option is not
supported for programs compiled with the integrated CICS translator, but CICS
has reversed this position. You can now compile with the EXCI translator option
and ignore the warning message DFH7006I.
RELATED CONCEPTS
CICS Application Programming Guide (The integrated CICS translator)
RELATED TASKS
Coding COBOL programs to run under CICS on page 419
Compiling with the CICS option on page 423
RELATED REFERENCES
CICS on page 312
TRUNC on page 363
Using the separate CICS translator
To run a COBOL program under CICS, you can use the separate CICS translator to
convert the CICS commands to COBOL statements, and then compile and link the
program to create the executable module. However, using the CICS translator that
is integrated with Enterprise COBOL is recommended.
To translate CICS statements separately, use the COBOL3 translator option. This
option causes the following line to be inserted:
CBL RENT,NODYNAM,
You can suppress the insertion of a CBL statement by using the CICS translator
option NOCBLCARD.
After you use the separate CICS translator, use the following compiler options
when you compile the program:
Table 57. Compiler options required for the separate CICS translator
Required compiler option Condition
RENT
NODYNAM The program is translated by the CICS translator.
426 Enterprise COBOL for z/OS, V5.2 Programming Guide
In addition, IBM recommends that you use the compiler option WORD(CICS) to
cause the compiler to flag language elements that are not supported under CICS.
The following TRUNC compiler option recommendations are based on expected
values for binary data items:
Table 58. TRUNC compiler options recommended for the separate CICS translator
Recommended compiler
option Condition
TRUNC(OPT) All binary data items conform to the PICTURE and USAGE clause
for those data items.
TRUNC(BIN) Not all binary data items conform to the PICTURE and USAGE
clause for those data items.
For example, if you use the separate CICS translator and have a data item defined
as PIC S9(8) BINARY that might receive a value greater than eight digits, use the
TRUNC(BIN) compiler option, change the item to USAGE COMP-5, or change the
PICTURE clause.
You might also want to avoid using these options, which have no effect:
v ADV
v FASTSRT
v OUTDD
The input data set for the compiler is the data set that you received as a result of
translation, which is SYSPUNCH by default.
RELATED CONCEPTS
Integrated CICS translator on page 425
RELATED TASKS
Compiling with the CICS option on page 423
CICS reserved-word table
COBOL provides an alternate reserved-word table (IGYCCICS) for CICS
application programs. If you use the compiler option WORD(CICS), COBOL words
that are not supported under CICS are flagged with an error message.
In addition to the COBOL words restricted by the IBM-supplied default
reserved-word table, the IBM-supplied CICS reserved-word table restricts the
following COBOL words:
v CLOSE
v DELETE
v FD
v FILE
v FILE-CONTROL
v INPUT-OUTPUT
v I-O-CONTROL
v MERGE
v OPEN
Chapter 20. Developing COBOL programs for CICS 427
v READ
v RERUN
v REWRITE
v SD
v SORT
v START
v WRITE
If you intend to use the SORT statement under CICS (COBOL supports an interface
for the SORT statement under CICS), you must change the CICS reserved-word
table to remove the words in bold above from the list of words marked as
restricted.
RELATED TASKS
Compiling with the CICS option on page 423
Sorting under CICS on page 237
RELATED REFERENCES
WORD on page 367
Handling errors by using CICS HANDLE
The setting of the CBLPSHPOP runtime option affects the state of the HANDLE
specifications when a program calls COBOL subprograms using a CALL statement.
When CBLPSHPOP is ON and a COBOL subprogram (not a nested program) is called
with a CALL statement, the following actions occur:
1. As part of program initialization, the run time suspends the HANDLE
specifications of the calling program (using EXEC CICS PUSH HANDLE).
2. The default actions for HANDLE apply until the called program issues its own
HANDLE commands.
3. As part of program termination, the run time reinstates the HANDLE
specifications of the calling program (using EXEC CICS POP HANDLE).
If you use the CICS HANDLE CONDITION or CICS HANDLE AID commands, the LABEL
specified for the CICS HANDLE command must be in the same PROCEDURE DIVISION
as the CICS command that causes branching to the CICS HANDLE label. You cannot
use the CICS HANDLE commands with the LABEL option to handle conditions, aids,
or abends that were caused by another program invoked with the COBOL CALL
statement. Attempts to perform cross-program branching by using the CICS HANDLE
command with the LABEL option result in a transaction abend.
If a condition, aid, or abend occurs in a nested program, the LABEL for the
condition, aid, or abend must be in the same nested program; otherwise
unpredictable results occur.
Performance considerations: When CBLPSHPOP is OFF, the run time does not
perform CICS PUSH or POP on a CALL to any COBOL subprogram. If the
subprograms do not use any of the EXEC CICS condition-handling commands, you
can run with CBLPSHPOP(OFF), thus eliminating the overhead of the PUSH HANDLE
and POP HANDLE commands. As a result, performance can be improved compared to
running with CBLPSHPOP(ON).
428 Enterprise COBOL for z/OS, V5.2 Programming Guide
If you are migrating an application from the VS COBOL II run time to the
Language Environment run time, see the related reference for information about
the CBLPSHPOP option for additional considerations.
Example: handling errors by using CICS HANDLE
RELATED TASKS
Running efficiently with CICS, IMS, or VSAM on page 662
RELATED REFERENCES
Enterprise COBOL Migration Guide (CICS HANDLE
commands and the CBLPSHPOP runtime option)
Enterprise COBOL Version 4 Performance Tuning
Example: handling errors by using CICS HANDLE
The following example shows the use of CICS HANDLE in COBOL programs.
Program A has a CICS HANDLE CONDITION command and program B has no CICS
HANDLE commands. Program A calls program B; program A also calls nested
program A1. A condition is handled in one of three scenarios.
(1) CBLPSHPOP(ON): If the CICS READ command in program B causes a
condition, the condition is not handled by program A (the HANDLE
specifications are suspended because the run time performs a CICS PUSH
HANDLE). The condition turns into a transaction abend.
(2) CBLPSHPOP(OFF): If the CICS READ command in program B causes a
condition, the condition is not handled by program A (the run time
diagnoses the attempt to perform cross-program branching by using a CICS
HANDLE command with the LABEL option). The condition turns into a
transaction abend.
(3) If the CICS READ command in nested program A1 causes a condition, the
flow of control goes to label ERR-1, and unpredictable results occur.
***********************************************************
* Program A *
***********************************************************
ID DIVISION.
PROGRAM-ID. A.
. . .
PROCEDURE DIVISION.
EXEC CICS HANDLE CONDITION
ERROR(ERR-1)
END-EXEC.
CALL B USING DFHEIBLK DFHCOMMAREA.
CALL A1.
. . .
THE-END.
EXEC CICS RETURN END-EXEC.
ERR-1.
. . .
* Nested program A1.
ID DIVISION.
PROGRAM-ID. A1.
PROCEDURE DIVISION.
EXEC CICS READ (3)
FILE(LEDGER)
INTO(RECORD)
RIDFLD(ACCTNO)
END-EXEC.
END PROGRAM A1.
Chapter 20. Developing COBOL programs for CICS 429
END PROGRAM A.
*
***********************************************************
* Program B *
***********************************************************
ID DIVISION.
PROGRAM-ID. B.
. . .
PROCEDURE DIVISION.
EXEC CICS READ (1) (2)
FILE(MASTER)
INTO(RECORD)
RIDFLD(ACCTNO)
END-EXEC.
. . .
END PROGRAM B.
430 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 21. Programming for a DB2 environment
In general, the coding for a COBOL program will be the same if you want the
program to access a DB2 database. However, to retrieve, update, insert, and delete
DB2 data and use other DB2 services, you must use SQL statements.
To communicate with DB2, do these steps:
v Code any SQL statements that you need, delimiting them with EXEC SQL and
END-EXEC statements.
v Either use the DB2 stand-alone precompiler, or compile with the SQL compiler
option and use the DB2 coprocessor.
RELATED CONCEPTS
DB2 coprocessor
COBOL and DB2 CCSID determination on page 437
RELATED TASKS
Coding SQL statements on page 432
Compiling with the SQL option on page 435
Choosing the DYNAM or NODYNAM compiler option on page 441
RELATED REFERENCES
Differences in how the DB2 precompiler and coprocessor behave on page 439
DB2 coprocessor
When you use the DB2 coprocessor (called SQL statement coprocessor by DB2), the
compiler handles your source programs that contain embedded SQL statements
without your having to use a separate precompile step.
To use the DB2 coprocessor, specify the SQL compiler option.
When the compiler encounters SQL statements in the source program, it interfaces
with the DB2 coprocessor. All text between EXEC SQL and END-EXEC statements is
passed to the coprocessor. The coprocessor takes appropriate actions for the SQL
statements and indicates to the compiler which native COBOL statements to
generate for them.
Although the use of a separate precompile step continues to be supported, it is
recommended that you use the coprocessor instead:
v Interactive debugging with Debug Tool is enhanced when you use the
coprocessor because you see the SQL statements (not the generated COBOL
source) in the listing.
v The COBOL compiler listing includes the error diagnostics (such as syntax errors
in the SQL statements) that the DB2 coprocessor generates.
v Certain restrictions on the use of COBOL language that apply when you use the
precompile step do not apply when you use the DB2 coprocessor. With the
coprocessor:
You can use SQL statements in any nested program. (With the precompiler,
SQL statements are restricted to the outermost program.)
You can use SQL statements in copybooks.
Copyright IBM Corp. 1991, 2015 431
REPLACE statements work in SQL statements.
Compiling with the DB2 coprocessor generates a DB2 database request module
(DBRM) along with the usual COBOL compiler outputs such as object module and
listing. The DBRM writes to the data set that you specified in the DBRMLIB DD
statement in the JCL for the COBOL compile step. As input to the DB2 bind
process, the DBRM data set contains information about the SQL statements and
host variables in the program.
RELATED CONCEPTS
COBOL and DB2 CCSID determination on page 437
RELATED TASKS
Compiling with the SQL option on page 435
RELATED REFERENCES
Differences in how the DB2 precompiler and coprocessor behave on page 439
SQL on page 354
Coding SQL statements
Delimit SQL statements with EXEC SQL and END-EXEC. The EXEC SQL and END-EXEC
delimiters must each be complete on one line. You cannot continue them across
multiple lines. Do not code COBOL statements within EXEC SQL statements.
You also need to do these special steps:
v Code an EXEC SQL INCLUDE statement to include an SQL communication area
(SQLCA) in the WORKING-STORAGE SECTION or LOCAL-STORAGE SECTION of the
outermost program. LOCAL-STORAGE is recommended for recursive programs and
programs that use the THREAD compiler option.
| v Define all host variables that you use in SQL statements in the WORKING-STORAGE
SECTION, LOCAL-STORAGE SECTION, or LINKAGE SECTION. However, you do not need
to identify them with EXEC SQL BEGIN DECLARE SECTION and EXEC SQL END
DECLARE SECTION.
Restriction: You cannot use SQL statements in object-oriented classes or methods.
RELATED TASKS
Using SQL INCLUDE with the DB2 coprocessor
Using character data in SQL statements on page 433
Using national decimal data in SQL statements on page 434
Using national group items in SQL statements on page 434
Using binary items in SQL statements on page 435
Determining the success of SQL statements on page 435
DB2 Application Programming and SQL Guide (Coding SQL statements in a
COBOL application)
RELATED REFERENCES
Code-page determination for string host variables in SQL statements on page 437
DB2 SQL Reference
Using SQL INCLUDE with the DB2 coprocessor
An SQL INCLUDE statement is treated identically to a native COBOL COPY statement
when you use the SQL compiler option.
432 Enterprise COBOL for z/OS, V5.2 Programming Guide
The following two lines are therefore treated the same way. (The period that ends
the EXEC SQL INCLUDE statement is required.)
EXEC SQL INCLUDE name END-EXEC.
COPY "name".
The processing of the name in an SQL INCLUDE statement follows the same rules as
those of the literal in a COPY literal-1 statement that does not have a REPLACING
phrase.
The library search order for SQL INCLUDE statements is the same SYSLIB
concatenation as the compiler uses to resolve COBOL COPY statements that do not
specify a library-name.
RELATED REFERENCES
Chapter 18, Compiler-directing statements, on page 373
Differences in how the DB2 precompiler and coprocessor behave on page 439
COPY statement (Enterprise COBOL Language Reference)
Using character data in SQL statements
You can code any of the following USAGE clauses to describe host variables for
character data that you use in EXEC SQL statements: USAGE DISPLAY for single-byte
or UTF-8 data, USAGE DISPLAY-1 for DBCS data, or USAGE NATIONAL for UTF-16
data.
When you use the stand-alone DB2 precompiler, you must specify the code page
(CCSID) in EXEC SQL DECLARE statements for host variables that are declared with
USAGE NATIONAL. You must specify the code page for host variables that are
declared with USAGE DISPLAY or DISPLAY-1 only if the CCSID that is in effect for
the COBOL CODEPAGE compiler option does not match the CCSIDs that are used by
DB2 for character and graphic data.
Consider the following code. The two highlighted statements are unnecessary
when you use the integrated DB2 coprocessor (with the SQLCCSID compiler option,
as detailed in the related concept below), because the code-page information is
handled implicitly.
CBL CODEPAGE(1140) NSYMBOL(NATIONAL)
. . .
WORKING-STORAGE SECTION.
EXEC SQL INCLUDE SQLCA END-EXEC.
01 INT1 PIC S9(4) USAGE COMP.
01 C1140.
49 C1140-LEN PIC S9(4) USAGE COMP.
49 C1140-TEXT PIC X(50).
EXEC SQL DECLARE :C1140 VARIABLE CCSID 1140 END-EXEC.
01 G1200.
49 G1200-LEN PIC S9(4) USAGE COMP.
49 G1200-TEXT PIC N(50) USAGE NATIONAL.
EXEC SQL DECLARE :G1200 VARIABLE CCSID 1200 END-EXEC.
. . .
EXEC SQL FETCH C1 INTO :INT1, :C1140, :G1200 END-EXEC.
If you specify EXEC SQL DECLARE variable-name VARIABLE CCSID nnnn END-EXEC, that
specification overrides the implied CCSID. For example, the following code would
cause DB2 to treat C1208-TEXT as encoded in UTF-8 (CCSID 1208) rather than as
encoded in the CCSID in effect for the COBOL CODEPAGE compiler option:
Chapter 21. Programming for a DB2 environment 433
01 C1208.
49 C1208-LEN PIC S9(4) USAGE COMP.
49 C1208-TEXT PIC X(50).
EXEC SQL DECLARE :C1208 VARIABLE CCSID 1208 END-EXEC.
The NSYMBOL compiler option has no effect on a character literal inside an EXEC SQL
statement. Character literals in an EXEC SQL statement follow the SQL rules for
character constants.
RELATED CONCEPTS
COBOL and DB2 CCSID determination on page 437
RELATED TASKS
DB2 Application Programming and SQL Guide (Coding SQL statements in a
COBOL application)
RELATED REFERENCES
Differences in how the DB2 precompiler and coprocessor behave on page 439
CODEPAGE on page 313
DB2 SQL Reference
Using national decimal data in SQL statements
You can use national decimal host variables in EXEC SQL statements when you use
either the integrated DB2 coprocessor or the DB2 precompiler. You do not need to
specify the CCSID in EXEC SQL DECLARE statements in either case. CCSID 1200 is
used automatically.
Any national decimal host variable that you specify in an EXEC SQL statement must
have the following characteristics:
v It must be signed.
v It must be specified with the SIGN LEADING SEPARATE clause.
v USAGE NATIONAL must be in effect implicitly or explicitly.
RELATED CONCEPTS
Formats for numeric data on page 47
RELATED TASKS
Defining national numeric data items on page 133
RELATED REFERENCES
Differences in how the DB2 precompiler and coprocessor behave on page 439
Using national group items in SQL statements
You can use a national group item as a host variable in an EXEC SQL statement. The
national group item is treated with group semantics (that is, as shorthand for the
set of host variables that are subordinate to the group item) rather than as an
elementary item.
Because all subordinate items in a national group must have USAGE NATIONAL, a
national group item cannot describe a variable-length string.
RELATED TASKS
Using national groups on page 134
434 Enterprise COBOL for z/OS, V5.2 Programming Guide
Using binary items in SQL statements
| For binary data items that you specify in an EXEC SQL statement, you can define
the data items as either USAGE COMP-5 or as USAGE BINARY, COMP, or COMP-4.
| If you define the binary data items as USAGE BINARY, COMP, or COMP-4, use the
TRUNC(BIN) option. (This technique might have a larger effect on performance than
using USAGE COMP-5 on individual data items.) If instead TRUNC(OPT) or TRUNC(STD)
is in effect, the compiler accepts the items but the data might not be valid because
of the decimal truncation rules. You need to ensure that truncation does not affect
the validity of the data.
RELATED CONCEPTS
Formats for numeric data on page 47
RELATED REFERENCES
TRUNC on page 363
Determining the success of SQL statements
When DB2 finishes executing an SQL statement, DB2 sends a return code in the
SQLCA structure, with one exception, to indicate whether the operation succeeded
or failed. In your program, test the return code and take any necessary action.
The exception occurs when a program runs under DSN from one of the alternate
entry points of the TSO batch mode module IKJEFT01 (IKJEFT1A or IKJEFT1B). In
this case, the return code is passed in register 15.
After execution of SQL statements, the content of the RETURN-CODE special register
might not be valid. Therefore, even if your COBOL program terminates normally
after successfully using SQL statements, the job step could end with an undefined
return code. To ensure that a meaningful return code is given at termination, set
the RETURN-CODE special register before terminating your program.
RELATED TASKS
DB2 Application Programming and SQL Guide (Coding SQL statements in a
COBOL application)
Compiling with the SQL option
You use the SQL compiler option to enable the DB2 coprocessor and to specify DB2
suboptions.
You can specify the SQL option in any of the compiler option sources: compiler
invocation, PROCESS or CBL statements, or installation default. You cannot specify
DB2 suboptions when the SQL option is the COBOL installation default, but you
can specify default DB2 suboptions by customizing the DB2 product installation
defaults.
The DB2 suboption string that you provide in the SQL compiler option is made
available to the DB2 coprocessor. Only the DB2 coprocessor views the contents of
the string.
You can use standard JCL procedural statements to compile your program with the
DB2 coprocessor. In addition to specifying the above compiler options, specify the
following items in your JCL:
Chapter 21. Programming for a DB2 environment 435
v DBRMLIB DD statement with the location for the generated database request
module (DBRM).
v STEPLIB override for the COBOL step, adding the data set that contains the DB2
coprocessor services, unless these services are in the LNKLST. Typically, this data
set is this data set is xxxxxx.SDSNLOAD. For example, for DB2 9 it might be
DSN910.SDSNLOAD, but your installation might have changed the name.
For example, you might have the following lines in your JCL:
//DBRMLIB DD DSN=PAYROLL.MONTHLY.DBRMLIB.DATA(MASTER),DISP=SHR
//STEPLIB DD DSN=DSN910.SDSNLOAD,DISP=SHR
Compiling a batch of programs: If you use the SQL option when compiling a
source file that contains a sequence of COBOL programs (a batch compile
sequence), SQL must be in effect for only the first program of the sequence.
Although you can specify SQL upon compiler invocation, the option will be in
effect for only the first program. If you specify SQL in a CBL or PROCESS statement
for a program other than the first program in the batch, you will receive a
compiler diagnostic message.
RELATED CONCEPTS
DB2 coprocessor on page 431
COBOL and DB2 CCSID determination on page 437
RELATED TASKS
Separating DB2 suboptions
Choosing the DYNAM or NODYNAM compiler option on page 441
RELATED REFERENCES
DYNAM on page 323
SQL on page 354
DB2 Command Reference
Separating DB2 suboptions
Because of the concatenation of multiple SQL option specifications, you can
separate DB2 suboptions (which might not fit in one CBL statement) into multiple
CBL statements.
The options that you include in the suboption string are cumulative. The compiler
concatenates these suboptions from multiple sources in the order that they are
specified. For example, suppose that your source file has the following code:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL=SQL("string1")
//COBOL.SYSIN DD *
CBL SQL("string2")
CBL SQL("string3")
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
During compilation, the compiler passes the following suboption string to the DB2
coprocessor:
"string1 string2 string3"
The concatenated strings are delimited with single spaces. If the compiler finds
multiple instances of the same SQL suboption, the last specification of that
suboption in the concatenated string takes effect. The compiler limits the length of
the concatenated DB2 suboption string to 4 KB.
436 Enterprise COBOL for z/OS, V5.2 Programming Guide
COBOL and DB2 CCSID determination
All DB2 string data other than BLOB, BINARY, and VARBINARY data has an
associated encoding scheme and a coded character set ID (CCSID). This is true for
fixed-length and variable-length character strings, fixed-length and variable-length
graphic character strings, CLOB host variables, and DBCLOB host variables.
When you use the integrated DB2 coprocessor, the determination of the code page
CCSID that will be associated with the string host variables used in SQL statement
processing depends on the setting of the COBOL SQLCCSID option, on the
programming techniques used, and on various DB2 configuration options.
When you use the SQL and SQLCCSID COBOL compiler options, the CCSID value
nnnnn that is specified in the CODEPAGE compiler option, or that is determined from
the COBOL data type of a host variable, is communicated automatically from
COBOL to DB2. DB2 associates the COBOL CCSID with host variables, overriding
the CCSID that would otherwise be implied by DB2 external mechanisms and
defaults. This associated CCSID is used for the processing of the SQL statements
that reference host variables.
When you use the SQL and NOSQLCCSID compiler options, the CCSID value nnnnn
that is specified in the CODEPAGE compiler option is used only for processing
COBOL statements within the COBOL program; that CCSID is not used for the
processing of SQL statements. Instead, DB2 assumes in processing SQL statements
that host variable data values are encoded according to the CCSID or CCSIDs that
are specified through DB2 external mechanisms and defaults.
RELATED CONCEPTS
DB2 coprocessor on page 431
RELATED TASKS
Programming with the SQLCCSID or NOSQLCCSID option on page 438
RELATED REFERENCES
Code-page determination for string host variables in SQL statements
CODEPAGE on page 313
SQL on page 354
SQLCCSID on page 355
Code-page determination for string host variables in SQL
statements
When you use the integrated DB2 coprocessor (SQL compiler option), the code page
for processing string host variables in SQL statements is determined as shown
below, in descending order of precedence.
v A host variable that has USAGE NATIONAL is always processed by DB2 using
CCSID 1200 (Unicode UTF-16). For example:
01 hostvariable pic n(10) usage national.
v An alphanumeric host variable that has an explicit FOR BIT DATA declaration is
set by DB2 to CCSID 66535, which indicates that the variable does not represent
encoded characters. For example:
EXEC SQL DECLARE hostvariable VARIABLE FOR BIT DATA END-EXEC
v A BLOB, BINARY, or VARBINARY host variable has no CCSID association.
These string types do not represent encoded characters.
Chapter 21. Programming for a DB2 environment 437
v A host variable for which you specify an explicit CCSID override in the SQLDA
is processed with that CCSID.
v A host variable that you specify in a declaration with an explicit CCSID is
processed with that CCSID. For example:
EXEC SQL DECLARE hostvariable VARIABLE CCSID nnnnn END-EXEC
v An alphanumeric host variable, if the SQLCCSID compiler option is in effect, is
processed with the CCSID nnnnn from the CODEPAGE compiler option.
v A DBCS host variable, if the SQLCCSID option is in effect, is processed with the
mapped value mmmmm, which is the pure DBCS CCSID component of the
mixed (MBCS) CCSID nnnnn from the CODEPAGE(nnnnn) compiler option.
v An alphanumeric or DBCS host variable, if the NOSQLCCSID option is in effect, is
processed with the CCSID from the DB2 ENCODING bind option, if specified,
or from the APPLICATION ENCODING set in DSNHDECP through the DB2
installation panel DSNTIPF.
RELATED REFERENCES
CODEPAGE on page 313
SQLCCSID on page 355
Programming with the SQLCCSID or NOSQLCCSID option
In general, the SQLCCSID option is recommended for new applications that use the
integrated DB2 coprocessor, and as a long-term direction for existing applications.
The NOSQLCCSID option is recommended as a mechanism for migrating existing
precompiler-based applications to use the integrated DB2 coprocessor.
The SQLCCSID option is recommended for COBOL-DB2 applications that have any
of these characteristics:
v Use COBOL Unicode support
v Use other COBOL syntax that is indirectly sensitive to CCSID encoding, such as
XML support or object-oriented syntax for Java interoperability
v Process character data that is encoded in a CCSID that is different from the
default CCSID assumed by DB2
The NOSQLCCSID option is recommended for applications that require the highest
compatibility with the behavior of the DB2 precompiler.
For applications that use COBOL alphanumeric data items as host variables
interacting with DB2 string data that is defined with the FOR BIT DATA subtype,
you must either:
v Use the NOSQLCCSID compiler option
v Specify explicit FOR BIT DATA declarations for those host variables, for example:
EXEC SQL DECLARE hostvariable VARIABLE FOR BIT DATA END-EXEC
Usage notes
v If you use the DB2 DCLGEN command to generate COBOL declarations for a table,
you can optionally create FOR BIT DATA declarations automatically. To do so,
specify the DCLBIT(YES) option of the DCLGEN command.
v Performance consideration: Using the SQLCCSID compiler option could result in
some performance overhead in SQL processing, because with SQLCCSID in effect
the default DB2 CCSID association mechanism is overridden with a mechanism
that works on a per-host-variable basis.
438 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED CONCEPTS
DB2 coprocessor on page 431
RELATED REFERENCES
SQLCCSID on page 355
Differences in how the DB2 precompiler and coprocessor behave
The sections that follow enumerate the differences in behavior between the
stand-alone COBOL DB2 precompiler and the integrated COBOL DB2 coprocessor.
| For details about the CCSID determination under the DB2 precompiler and
| coprocessor, see COBOL and DB2 CCSID determination on page 437.
Period at the end of EXEC SQL INCLUDE statements
Precompiler: The DB2 precompiler does not require that a period end each EXEC
SQL INCLUDE statement. If a period is specified, the precompiler processes it as part
of the statement. If a period is not specified, the precompiler accepts the statement
as if a period had been specified.
Coprocessor: The DB2 coprocessor treats each EXEC SQL INCLUDE statement like a
COPY statement, and requires that a period end the statement. For example:
IF A = B THEN
EXEC SQL INCLUDE some_code_here END-EXEC.
ELSE
. . .
END-IF
Note that the period does not terminate the IF statement.
EXEC SQL INCLUDE and nested COPY REPLACING
Precompiler: With the DB2 precompiler, an EXEC SQL INCLUDE statement can
reference a copybook that contains a COPY statement that uses the REPLACING
phrase.
Coprocessor: With the DB2 coprocessor, an EXEC SQL INCLUDE statement cannot
reference a copybook that contains a COPY statement that uses the REPLACING
phrase. The coprocessor processes each EXEC SQL INCLUDE statement identically to a
COPY statement, and nested COPY statements cannot have the REPLACING phrase.
EXEC SQL and REPLACE or COPY REPLACING
Precompiler: With the DB2 precompiler, COBOL REPLACE statements and the
REPLACING phrase of the COPY statement act on the expanded source created from
the EXEC SQL statement. COBOL rules for REPLACE and REPLACING are used.
Coprocessor: With the DB2 coprocessor, REPLACE and COPY . . . REPLACING
statements act on the original source program, including EXEC SQL statements.
Different behavior can result, as in the following example:
REPLACE == ABC == By == XYZ ==.
01 G.
02 ABC PIC X(10).
. . .
EXEC SQL SELECT * INTO :G.ABC FROM TABLE1 END-EXEC
Chapter 21. Programming for a DB2 environment 439
With the precompiler, the reference to G.ABC will appear as ABC of G in the
expanded source and will be replaced with XYZ of G. With the coprocessor,
replacement will not occur, because ABC is not delimited by separators in the
original source string G.ABC.
Source code after an END-EXEC statement
Precompiler: The DB2 precompiler ignores any code that follows END-EXEC
statements on the same line.
Coprocessor: The DB2 coprocessor processes code that follows END-EXEC statements
on the same line.
Multiple definitions of host variables
Precompiler: The DB2 precompiler does not require that host variable references be
unique. The first definition that maps to a valid DB2 data type is used.
Coprocessor: The DB2 coprocessor requires that each host variable reference be
unique. The coprocessor diagnoses nonunique references to host variables. You
must fully qualify host variable references to make them unique.
EXEC SQL statement continuation lines
Precompiler: The DB2 precompiler requires that EXEC SQL statements start in
columns 12 through 72. Continuation lines of the statements can start anywhere in
columns 8 through 72.
Coprocessor: The DB2 coprocessor requires that all lines of an EXEC SQL statement,
including continuation lines, be coded in columns 12 through 72.
Bit-data host variables
Precompiler: With the DB2 precompiler, a COBOL alphanumeric data item can be
used as a host variable to hold DB2 character data that has subtype FOR BIT DATA.
An explicit EXEC SQL DECLARE VARIABLE statement that declares that host variable
as FOR BIT DATA is not required.
Coprocessor: With the DB2 coprocessor, a COBOL alphanumeric data item can be
used as a host variable to hold DB2 character data that has subtype FOR BIT DATA
if an explicit EXEC SQL DECLARE VARIABLE statement for that host variable is
specified in the COBOL program. For example:
EXEC SQL DECLARE :HV1 VARIABLE FOR BIT DATA END-EXEC.
As an alternative to adding EXEC SQL DECLARE . . . FOR BIT DATA statements, you
can use the NOSQLCCSID compiler option. For details, see the related reference about
code-page determination below.
SQL-INIT-FLAG
Precompiler: With the DB2 precompiler, if you pass host variables that might be
located at different addresses when the program is called more than once, the
called program must reset SQL-INIT-FLAG. Resetting this flag indicates to DB2 that
storage must be initialized when the next SQL statement runs. To reset the flag,
insert the statement MOVE ZERO TO SQL-INIT-FLAG in the PROCEDURE DIVISION of the
called program ahead of any executable SQL statements that use those host
variables.
440 Enterprise COBOL for z/OS, V5.2 Programming Guide
Coprocessor: With the DB2 coprocessor, the called program does not need to reset
SQL-INIT-FLAG. An SQL-INIT-FLAG is automatically defined in the program to aid
program portability. However, statements that modify SQL-INIT-FLAG, such as MOVE
ZERO TO SQL-INIT-FLAG, have no effect on the SQL processing in the program.
RELATED CONCEPTS
DB2 coprocessor on page 431
COBOL and DB2 CCSID determination on page 437
RELATED REFERENCES
Code-page determination for string host variables in SQL statements on page 437
SQLCCSID on page 355
Choosing the DYNAM or NODYNAM compiler option
For COBOL programs that have EXEC SQL statements, your choice of the compiler
option DYNAM or NODYNAM depends on the operating environment.
When you run under:
v TSO or IMS: You can use either the DYNAM or NODYNAM compiler option.
Note that IMS and DB2 share a common alias name, DSNHLI, for the language
interface module. You must concatenate your libraries as follows:
If you use IMS with the DYNAM option, concatenate the IMS library first.
If you run your application only under DB2, concatenate the DB2 library first.
v CICS or the DB2 call attach facility (CAF): You must use the NODYNAM compiler
option.
Because stored procedures use CAF, you must also compile COBOL stored
procedures with the NODYNAM option.
RELATED TASKS
Compiling with the SQL option on page 435
DB2 Application Programming and SQL Guide (Programming for the call
attachment facility)
RELATED REFERENCES
DYNAM on page 323
Chapter 21. Programming for a DB2 environment 441
442 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 22. Developing COBOL programs for IMS
Although much of the coding of a COBOL program will be the same when
running under IMS, be aware of the following recommendations and restrictions.
In COBOL, IMS message processing programs (MPPs) do not use non-IMS input or
output statements such as READ, WRITE, REWRITE, OPEN, and CLOSE.
With Enterprise COBOL, you can invoke IMS facilities using the following
interfaces:
v CBLTDLI call
v Language Environment callable service CEETDLI
v EXEC SQLIMS statements
CEETDLI behaves essentially the same way as CBLTDLI, except that CEETDLI
enables LE condition handling to be used. There are some instances when you
cannot use Language Environment condition handling when using CBLTDLI under
IMS.
You can also run object-oriented COBOL programs in a Java dependent region. You
can mix the object-oriented COBOL and Java languages in a single application.
RELATED CONCEPTS
IMS SQL coprocessor
RELATED TASKS
Coding SQLIMS statements on page 444
Compiling with the SQLIMS option on page 445
Compiling and linking COBOL programs for running under IMS on page 447
Using object-oriented COBOL and Java under IMS on page 448
Calling a COBOL method from a Java application under IMS on page 448
Building a mixed COBOL-Java application that starts with COBOL on page 449
Writing mixed-language IMS applications on page 449
IMS SQL coprocessor
When you use the IMS SQL coprocessor (called SQL statement coprocessor by IMS),
the compiler handles your source programs that contain embedded SQL
statements.
When the compiler encounters SQLIMS statements in the source program, it
interfaces with the IMS SQL coprocessor. All text between EXEC SQLIMS and
END-EXEC statements is passed to the coprocessor. The coprocessor takes
appropriate actions for the SQLIMS statements and indicates to the compiler what
native COBOL statements to generate for them.
Notes:
v The IMS SQL coprocessor processes embedded SQLIMS statements, not embedded
SQL statements.
Copyright IBM Corp. 1991, 2015 443
v IMS program might contain EXEC SQL statements for accessing a DB2 SQL
database, EXEC SQLIMS statements for accessing an IMS DLI databases, or both.
The SQL option enables EXEC SQL statements while the SQLIMS option enables
EXEC SQLIMS statements.
With the IMS SQL coprocessor, you can use statements in the following ways:
v Use EXEC SQLIMS statements in any nested program.
v Use EXEC SQLIMS statements in COPYBOOKS.
v REPLACE statements work in SQLIMS statements.
RELATED TASKS
Coding SQLIMS statements
Compiling with the SQLIMS option on page 445
Compiling and linking COBOL programs for running under IMS on page 447
RELATED REFERENCES
SQLIMS on page 356
Coding SQLIMS statements
Delimit SQLIMS statements with EXEC SQLIMS and END-EXEC. The EXEC SQLIMS and
END-EXEC delimiters must each be complete on one line. Do not code COBOL
statements within EXEC SQLIMS statements.
Code an EXEC SQLIMS INCLUDE statement to include an SQLIMS communication
area (SQLCA) in the WORKING-STORAGE SECTION or LOCAL-STORAGE SECTION of the
outermost program. The LOCAL-STORAGE SECTION is recommended for recursive
programs and programs that use the THREAD compiler option.
Restriction: You cannot use SQLIMS statements in object-oriented classes or
methods.
RELATED TASKS
Using SQLIMS INCLUDE with the IMS SQL coprocessor
Using character data in SQLIMS statements on page 445
Using binary items in SQLIMS statements on page 445
Determining the success of SQLIMS statements on page 445
Using SQLIMS INCLUDE with the IMS SQL coprocessor
An SQLIMS INCLUDE statement is treated identically to a native COBOL COPY
statement when you use the SQLIMS compiler option.
The following two lines are therefore treated the same way. The period that ends
the EXEC SQLIMS INCLUDE statement is required.
EXEC SQLIMS INCLUDE name END-EXEC.
COPY "name".
The processing of the name in an SQLIMS INCLUDE statement follows the same rules
as the literal in a COPY literal-1 statement that does not have a REPLACING phrase.
The library search order for SQLIMS INCLUDE statements is the same SYSLIB
concatenation as the compiler uses to resolve COBOL COPY statements that do not
specify a library-name.
444 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
Chapter 18, Compiler-directing statements, on page 373
COPY statement (Enterprise COBOL Language Reference)
Using character data in SQLIMS statements
Alphanumeric host data items for use in EXEC SQLIMS statements (host variables)
must be defined as USAGE DISPLAY.
Note: Do not use character data items that are defined with USAGE DISPLAY-1 or
USAGE NATIONAL as SQLIMS host variables.
RELATED CONCEPTS
IMS SQL coprocessor on page 443
RELATED REFERENCES
CODEPAGE on page 313
Using binary items in SQLIMS statements
| For binary data items that you specify in an EXEC SQLIMS statement, you can define
the data items as either USAGE COMP-5 or as USAGE BINARY, COMP, or COMP-4.
| If you define the binary data items as USAGE BINARY, COMP, or COMP-4, use the
TRUNC(BIN) compiler option. Using this option might have a larger effect on
performance than using USAGE COMP-5 on individual data items. If instead you use
the TRUNC(OPT) or TRUNC(STD) compiler options, the compiler accepts the items but
the data might not be valid because of the decimal truncation rules. You must
ensure that truncation does not affect the validity of the data.
RELATED CONCEPTS
Formats for numeric data on page 47
RELATED REFERENCES
TRUNC on page 363
Determining the success of SQLIMS statements
When IMS finishes running an SQLIMS statement, IMS sends a return code in the
SQLIMSCA structure to indicate whether the operation succeeded or failed. In
your program, test the return code and take any necessary action.
After execution of SQLIMS statements, the content of the RETURN-CODE special
register might not be valid. Therefore, even if a program terminates normally after
successfully using SQLIMS statements, the job step might end with an undefined
return code. To ensure that a meaningful return code is given at termination, set
the RETURN-CODE special register before you end the program.
RELATED TASKS
IMS Application Programming Guide
Compiling with the SQLIMS option
Use the SQLIMS compiler option to enable the IMS SQL coprocessor and to specify
IMS suboptions.
Chapter 22. Developing COBOL programs for IMS 445
You can specify the SQLIMS option in any of the compiler option sources: compiler
invocation, PROCESS or CBL statements, or installation default. However, you cannot
specify IMS suboptions when the SQLIMS option is the COBOL installation default.
The IMS suboption string in the SQLIMS compiler option is only available to the
IMS SQL coprocessor.
To use the IMS SQL coprocessor, you must compile with the SQLIMS option and
IMS must be available on the system on which you compile.
You can use standard JCL procedural statements to compile your program with the
IMS SQL coprocessor. In addition to specifying the above compiler options, specify
the following item in your JCL:
STEPLIB override for the COBOL step, adding the data set that contains the IMS
SQL coprocessor services, unless these services are in the LNKLST. Typically, the
data set is IMS.SDFSRESL but your installation might have changed the name.
For example, you might have the following lines in your JCL:
//STEPLIB DD DSN=IMS.SDFSRESL,DISP=SHR
Compiling a batch of programs:
If you use the SQLIMS option when you compile a source file that contains a
sequence of COBOL programs (a batch compile sequence), SQLIMS is in effect for
only the first program of the sequence. Although you can specify SQLIMS upon
compiler invocation, the option is in effect for only the first program. If you specify
SQLIMS in a CBL or PROCESS statement for a program other than the first program in
the batch, a compiler diagnostic message is issued.
RELATED CONCEPTS
IMS SQL coprocessor on page 443
RELATED TASKS
Separating IMS suboptions
RELATED REFERENCES
SQL on page 354
Separating IMS suboptions
Because of the concatenation of multiple SQLIMS option specifications, you can
separate IMS suboptions (which might not fit in one CBL statement) into multiple
CBL statements.
The options that you include in the suboption string are cumulative. The compiler
concatenates these suboptions from multiple sources in the order that they are
specified. For example, suppose that your source file contains the following code:
//STEP1 EXEC IGYWC, . . .
// PARM.COBOL=SQLIMS("string1")
//COBOL.SYSIN DD *
CBL SQLIMS("string2")
CBL SQLIMS("string3")
IDENTIFICATION DIVISION.
PROGRAM-ID. DRIVER1.
During compilation, the compiler passes the following suboption string to the IMS
SQL coprocessor:
446 Enterprise COBOL for z/OS, V5.2 Programming Guide
"string1 string2 string3"
The concatenated strings are delimited with single spaces. If the compiler finds
multiple instances of the same SQLIMS suboption, the last specification of that
suboption in the concatenated string takes effect. The compiler limits the length of
the concatenated IMS suboption string to 4 KB.
RELATED CONCEPTS
IMS SQL coprocessor on page 443
RELATED TASKS
Compiling with the SQLIMS option on page 445
Compiling and linking COBOL programs for running under IMS
For best performance in the IMS environment, use the RENT compiler option. RENT
causes COBOL to generate reentrant code. You can then run your application
programs in either preloaded mode (the programs are always resident in storage) or
nonpreload mode without having to recompile using different options.
Preloading can boost performance because subsequent requests for a program can
be handled faster when the program is already in storage (rather than being
fetched from a library each time it is needed).
For IMS programs, using the RENT compiler option is recommended. You must use
the RENT compiler option for a program that is to be run preloaded or both
| preloaded and nonpreloaded. When you preload a program object that contains
| COBOL programs, all of the COBOL programs in that program object must be
compiled using the RENT option.
You can place programs compiled with the RENT option in the z/OS link pack area.
There they can be shared among the IMS dependent regions.
To run above the 16 MB line, an application program must be compiled with RENT.
The data for IMS application programs can reside above the 16 MB line, and you
can use DATA(31) RENT for programs that use IMS services.
For proper execution of COBOL programs under IMS, observe the following
guidelines for the link-edit attributes:
| v To link program objects that contain only COBOL programs compiled with the
RENT compiler option, link as RENT.
| v To link program objects that contain a mixture of COBOL RENT programs and
other programs, use the link-edit attributes recommended for the other
programs.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Choosing the DYNAM or NODYNAM compiler option on page 441
Language Environment Programming Guide (Condition handling under IMS)
RELATED REFERENCES
DATA on page 318
Chapter 22. Developing COBOL programs for IMS 447
RENT on page 348
Enterprise COBOL Migration Guide (IMS considerations)
Using object-oriented COBOL and Java under IMS
You can mix object-oriented COBOL and Java in an application that runs in a Java
dependent region.
For example, you can:
v Call a COBOL method from a Java application. You can build the messaging
portion of your application in Java and call COBOL methods to access IMS
databases.
v Build a mixed COBOL and Java application that starts with the main method of
a COBOL class and that invokes Java routines.
You must run these applications in either a Java message processing (JMP)
dependent region or a Java batch processing (JBP) dependent region. A program
that reads from the message queue (regardless of the language) must run in a JMP
dependent region.
RELATED TASKS
Defining a factory section on page 611
Chapter 30, Writing object-oriented programs, on page 579
Chapter 31, Communicating with Java methods, on page 623
Chapter 16, Compiling, linking, and running OO applications, on page 291
IMS Application Programming Guide
Calling a COBOL method from a Java application under IMS
You can use the object-oriented language support in Enterprise COBOL to write
COBOL methods that a Java program can call under IMS.
When you define a COBOL class and compile it using Enterprise COBOL, the
compiler generates a Java class definition with native methods and the object code
that implements those native methods. You can then create an instance and invoke
the methods of this class from a Java program that runs in a Java dependent
region, just as you would use any other class.
For example, you can define a COBOL class that uses the appropriate DL/I calls to
access an IMS database. To make the implementation of this class available to a
Java program, do the following steps:
1. Compile the COBOL class using Enterprise COBOL. The compiler generates a
Java source file (.java) that contains the class definition, and an object module
(.o) that contains the implementation of the native methods.
2. Compile the generated Java source file using the Java compiler. The Java
compiler creates a class file (.class).
3. Link the object code into a dynamic link library (DLL) in the z/OS UNIX file
system (.so). The directory that contains the COBOL DLLs must be listed in the
LIBPATH, as specified in the IMS.PROCLIB member that is indicated by the
ENVIRON= parameter of the IMS region procedure.
4. Update the sharable application class path in the master JVM options member
(ibm.jvm.sharable.application.class.path in the IMS.PROCLIB member that is
specified by the JVMOPMAS= parameter of the IMS region procedure) to
enable the JVM to access the Java class file.
448 Enterprise COBOL for z/OS, V5.2 Programming Guide
A Java program cannot call procedural COBOL programs directly. To reuse existing
COBOL IMS code, use one of the following techniques:
v Restructure the COBOL code as a method in a COBOL class.
v Write a COBOL class definition and method that serves as a wrapper for the
existing procedural code. The wrapper code can use COBOL CALL statements to
access procedural COBOL programs.
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Structuring OO applications on page 620
Wrapping procedure-oriented COBOL programs on page 620
IMS Application Programming Guide
Building a mixed COBOL-Java application that starts with
COBOL
An application that runs in a Java dependent region must start with the main
method of a class.
A COBOL class definition that has a main factory method meets this requirement;
therefore, you can use a main factory method as the first routine of a mixed
COBOL and Java application under IMS.
Enterprise COBOL generates a Java class with a main method, which the Java
dependent region can find, instantiate, and invoke. Although you can code the
entire application in COBOL, you would probably build this type of application to
call a Java routine. When the COBOL run time runs within the JVM of a Java
dependent region, it automatically finds and uses this JVM to invoke methods on
Java classes.
The COBOL application should use DL/I calls for processing messages (GU and GN)
and synchronizing transactions (CHKP).
RELATED TASKS
Structuring OO applications on page 620
IMS Application Programming Guide
IBM SDK for Java - Tools Documentation
Writing mixed-language IMS applications
When you write mixed-language IMS applications, you need to be aware of the
effects of the STOP RUN statement. You also need to understand how to process
messages and synchronize transactions, access databases, and use the application
interface block (AIB).
RELATED TASKS
Using the STOP RUN statement
Processing messages and synchronizing transactions on page 450
Accessing databases on page 450
Using the application interface block on page 450
Using the STOP RUN statement
If you use the STOP RUN statement in the COBOL portion of your application, the
statement terminates all COBOL and Java routines (including the JVM).
Chapter 22. Developing COBOL programs for IMS 449
Control is returned immediately to IMS. The program and the transaction are left
in a stopped state.
Processing messages and synchronizing transactions
IMS message-processing applications must do all message processing and
transaction synchronization either in COBOL or Java, rather than distributing this
logic between application components written in both languages.
COBOL components use CALL statements to DL/I services to process messages (GU
and GN) and synchronize transactions (CHKP). Java components use Java classes for
IMS to do these functions. You can use object instances of classes derived from
IMSFieldMessage to communicate entire IMS messages between the COBOL and
Java components of the application.
RELATED TASKS
IMS Application Programming Guide
RELATED REFERENCES
IMS Application Programming API Reference
Accessing databases
You can use either Java, COBOL, or a mixture of the two languages to access IMS
databases.
Limitation: EXEC SQL statements for DB2 database access are not supported in
COBOL routines that run in a Java dependent region.
Recommendation: Do not access the same database program communication block
(PCB) from both Java and COBOL. The Java and COBOL parts of the application
share the same database position. Changes in database position from calls in one
part of the application affect the database position in another part of the
application. (This problem occurs whether the affected parts of an application are
written in the same language or in different languages.)
Suppose that a Java component of a mixed application builds an SQL SELECT clause
and uses Java Database Connectivity (JDBC) to query and retrieve results from an
IMS database. The Java class libraries for IMS construct the appropriate request to
IMS to establish the correct position in the database. If you then invoke a COBOL
method that builds a segment search argument (SSA) and issues a GU (Get Unique)
request to IMS against the same database PCB, the request probably altered the
position in the database for that PCB. If so, subsequent JDBC requests to retrieve
more records by using the initial SQL SELECT clause are incorrect because the
database position changed. If you must access the same PCB from multiple
languages, reestablish the database position after an interlanguage call before you
access more records in the database.
RELATED TASKS
IMS Application Programming Guide
Using the application interface block
COBOL applications that run in a Java dependent region normally must use the
AIB interface because the Java dependent region does not provide PCB addresses
to its application.
To use the AIB interface, specify the PCB requested for the call by placing the PCB
name (which must be defined as part of the PSBGEN) in the resource name field of
450 Enterprise COBOL for z/OS, V5.2 Programming Guide
the AIB. (The AIB requires that all PCBs in a program specification block (PSB)
definition have a name.) You do not specify the PCB address directly, and your
application does not need to know the relative PCB position in the PCB list. Upon
the completion of the call, the AIB returns the PCB address that corresponds to the
PCB name that the application passed.
Alternatively, you can obtain PCB addresses by making an IMS INQY call using
subfunction FIND, and the PCB name as the resource name. The call returns the
address of the PCB, which you can then pass to a COBOL program. (This approach
still requires that the PCB name be defined as part of the PSBGEN, but the
application does not have to use the AIB interface.)
Example: using the application interface block
RELATED TASKS
IMS Application Programming Guide
Example: using the application interface block:
The following example shows how you can use the AIB interface in a COBOL
application.
Local-storage section.
copy AIB.
. . .
Linkage section.
01 IOPCB.
05 logtterm pic x(08).
05 pic x(02).
05 tpstat pic x(02).
05 iodate pic s9(7) comp-3.
05 iotime pic s9(7) comp-3.
05 pic x(02).
05 seqnum pic x(02).
05 mod pic x(08).
Procedure division.
Move spaces to input-area
Move spaces to AIB
Move "DFSAIB" to AIBRID
Move length of AIB to AIBRLEN
Move "IOPCB" to AIBRSNM1
Move length of input-area to AIBOALEN
Call "CEETDLI" using GU, AIB, input-area
Set address of IOPCB to AIBRESA1
If tpstat = spaces
* . . process input message
Chapter 22. Developing COBOL programs for IMS 451
452 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 23. Running COBOL programs under z/OS UNIX
To run COBOL programs in the z/OS UNIX environment, compile them using
Enterprise COBOL or COBOL for OS/390 & VM. The programs must be reentrant,
so use the compiler and linker option RENT.
If you are going to run the programs from the z/OS UNIX file system, use the
linker option AMODE 31. Any AMODE 24 program that you call from within a z/OS
UNIX application must reside in an MVS PDS or PDSE.
Restrictions: The following restrictions apply to running under z/OS UNIX:
v SORT and MERGE statements are not supported.
v You cannot use the old COBOL interfaces for preinitialization (runtime option
RTEREUS) to establish a reusable environment.
v You cannot run a COBOL program compiled with the NOTHREAD option in more
than one thread. If you start a COBOL application in a second thread, you get a
software condition from the COBOL run time. You can run NOTHREAD COBOL
programs in the initial process thread (IPT) or in one non-IPT that you create
from a C or PL/I routine.
You can run a COBOL program in more than one thread if you compile all the
COBOL programs in the application with the THREAD option.
You can use Debug Tool to debug z/OS UNIX programs in remote debug mode,
for example, by using the Debug Perspective of Rational Developer for System z,
or in full-screen mode (MFI) using a VTAM terminal.
RELATED TASKS
Chapter 15, Compiling under z/OS UNIX, on page 283
Running OO applications under z/OS UNIX on page 293
Running in z/OS UNIX environments
Setting and accessing environment variables on page 454
Calling UNIX/POSIX APIs on page 456
Accessing main program parameters under z/OS UNIX on page 458
Language Environment Programming Guide
RELATED REFERENCES
RENT on page 348
Running in z/OS UNIX environments
You can run COBOL programs in any of the z/OS UNIX execution environments,
either from within a z/OS UNIX shell or from outside a shell.
v You can run programs in either the OMVS shell (OMVS) or the ISPF shell
(ISHELL).
Enter the program-name at the shell prompt. The program must be in the
current directory or in your search path.
You can specify runtime options only by setting the environment variable
_CEE_RUNOPTS before starting the program.
You can run programs that reside in a cataloged MVS data set from a shell by
using the tso utility. For example:
tso "call my.loadlib(myprog)"
Copyright IBM Corp. 1991, 2015 453
The ISPF shell can direct stdout and stderr only to a z/OS UNIX file, not to
your terminal.
v From outside a shell, you can run programs either under TSO/E or in batch.
To call a COBOL program that resides in a z/OS UNIX file from the TSO/E
prompt, use the BPXBATCH utility or a spawn() syscall in a REXX exec.
To call a COBOL program that resides in a z/OS UNIX file with the EXEC JCL
statement, use the BPXBATCH utility.
RELATED TASKS
Running OO applications under z/OS UNIX on page 293
Setting and accessing environment variables
Calling UNIX/POSIX APIs on page 456
Accessing main program parameters under z/OS UNIX on page 458
Defining and allocating QSAM files on page 174
Allocating line-sequential files on page 214
Allocating VSAM files on page 206
Displaying values on a screen or in a file (DISPLAY) on page 35
Language Environment Programming Guide (Running POSIX-enabled programs)
RELATED REFERENCES
TEST on page 359
UNIX System Services User's Guide (The BPXBATCH utility)
Language Environment Programming Reference
Setting and accessing environment variables
You can set environment variables for z/OS UNIX COBOL programs either from
the shell with commands export and set, or from the program.
Although setting and resetting environment variables from the shell before you
begin to run a program is a typical procedure, you can set, reset, and access
environment variables from the program while it is running.
If you are running a program with BPXBATCH, you can set environment variables
by using an STDENV DD statement.
To reset an environment variable as if it had not been set, use the z/OS UNIX shell
command unset. To reset an environment variable from a COBOL program, call
the setenv() function.
To see the values of all environment variables, use the export command with no
parameters. To access the value of an environment variable from a COBOL
program, call the getenv() function.
Example: setting and accessing environment variables on page 456
RELATED TASKS
Running in z/OS UNIX environments on page 453
Setting environment variables that affect execution on page 455
Accessing main program parameters under z/OS UNIX on page 458
Running OO applications under z/OS UNIX on page 293
Setting environment variables under z/OS UNIX on page 283
RELATED REFERENCES
Runtime environment variables on page 455
454 Enterprise COBOL for z/OS, V5.2 Programming Guide
Language Environment Programming Reference
MVS Program Management: User's Guide and Reference
Setting environment variables that affect execution
To set environment variables for z/OS UNIX COBOL programs from a shell, use
the export or set command. To set environment variables from within the
program, call POSIX functions setenv() or putenv().
For example, to set the environment variable MYFILE:
export MYFILE=/usr/mystuff/notes.txt
Example: setting and accessing environment variables on page 456
RELATED TASKS
Calling UNIX/POSIX APIs on page 456
Setting environment variables under z/OS UNIX on page 283
RELATED REFERENCES
Runtime environment variables
Runtime environment variables
Several runtime variables are of interest for COBOL programs.
These are the runtime environment variables:
_CEE_ENVFILE
Specifies a file from which to read environment variables.
_CEE_RUNOPTS
Specifies runtime options.
CLASSPATH
Specifies directory paths of Java .class files required for an OO application.
COBJVMINITOPTIONS
Specifies Java virtual machine (JVM) options to be used when COBOL
initializes a JVM.
_IGZ_SYSOUT
Specifies where to direct DISPLAY output. stdout and stderr are the only
allowable values.
LIBPATH
Specifies directory paths of dynamic link libraries.
PATH Specifies directory paths of executable programs.
STEPLIB
Specifies location of programs that are not in the LNKLST.
RELATED TASKS
Displaying data on the system logical output device on page 36
RELATED REFERENCES
XL C/C++ Programming Guide (_CEE_ENVFILE)
Language Environment Programming Reference
Chapter 23. Running COBOL programs under z/OS UNIX 455
Example: setting and accessing environment variables
The following example shows how you can access and set environment variables
from a COBOL program by calling the standard POSIX functions getenv() and
putenv().
Because getenv() and putenv() are C functions, you must pass arguments BY VALUE.
Pass character strings as BY VALUE pointers that point to null-terminated strings.
Compile programs that call these functions with the NODYNAM and
PGMNAME(LONGMIXED) options.
CBL pgmname(longmixed),nodynam
Identification division.
Program-id. "envdemo".
Data division.
Working-storage section.
01 P pointer.
01 PATH pic x(5) value Z"PATH".
01 var-ptr pointer.
01 var-len pic 9(4) binary.
01 putenv-arg pic x(14) value Z"MYVAR=ABCDEFG".
01 rc pic 9(9) binary.
Linkage section.
01 var pic x(5000).
Procedure division.
* Retrieve and display the PATH environment variable
Set P to address of PATH
Call "getenv" using by value P returning var-ptr
If var-ptr = null then
Display "PATH not set"
Else
Set address of var to var-ptr
Move 0 to var-len
Inspect var tallying var-len
for characters before initial X"00"
Display "PATH = " var(1:var-len)
End-if
* Set environment variable MYVAR to ABCDEFG
Set P to address of putenv-arg
Call "putenv" using by value P returning rc
If rc not = 0 then
Display "putenv failed"
Stop run
End-if
Goback.
Calling UNIX/POSIX APIs
You can call standard UNIX/POSIX functions from z/OS UNIX COBOL programs
and from traditional z/OS COBOL programs by using the CALL literal statement.
These functions are part of Language Environment.
Because these are C functions, you must pass arguments BY VALUE. Pass character
strings as BY VALUE pointers that point to null-terminated strings. You must use the
compiler options NODYNAM and PGMNAME(LONGMIXED) when you compile programs
that call these functions.
You can call the fork(), exec(), and spawn() functions from a COBOL program or
from a non-COBOL program in the same process as COBOL programs. However,
be aware of these restrictions:
v From a forked process you cannot access any COBOL sequential, indexed, or
relative files that were open when you issued the fork. File status code 92 is
456 Enterprise COBOL for z/OS, V5.2 Programming Guide
returned if you attempt such access (CLOSE, READ, WRITE, REWRITE, DELETE, or
START). You can access line-sequential files that were open at the time of a fork.
v You cannot use the fork() function in a process in which any of the following
conditions are true:
A COBOL SORT or MERGE is running.
A declarative is running.
The process has more than one Language Environment enclave (COBOL run
unit).
The process has used any of the COBOL reusable environment interfaces.
The process has ever run a VS COBOL II program.
v With one exception, DD allocations are not inherited from a parent process to a
child process. The exception is the local spawn, which creates a child process in
the same address space as the parent process. You request a local spawn by
setting the environment variable _BPX_ SHAREAS=YES before you invoke the
spawn() function.
The exec() and spawn() functions start a new Language Environment enclave in
the new UNIX process. Therefore the target program of the exec() or spawn()
function is a main program, and all COBOL programs in the process start in initial
state with all files closed.
Sample code for calling some of the POSIX routines is provided in the SIGYSAMP
data set.
Table 59. Samples with POSIX function calls
Purpose Sample Functions used
Shows how to use some IGYTFL1 v getcwd()
of the file and directory
v mkdir()
routines
v rmdir()
v access()
Shows how to use the IGYTCNV v iconv_open()
iconv routines to convert
v iconv()
data
v iconv_close()
Shows the use of the IGYTEXC, IGYTEXC1 v fork()
exec() routine to run a
v getpid()
new program along with
other process-related v getppid()
routines v execl()
v perror()
v wait()
Shows how to get the IGYTERNO, IGYTGETE v perror()
errno value
v fopen()
Chapter 23. Running COBOL programs under z/OS UNIX 457
Table 59. Samples with POSIX function calls (continued)
Purpose Sample Functions used
Shows the use of the IGYTMSQ, IGYTMSQ2 v ftok()
interprocess
v msgget()
communication message
routines v msgsnd()
v perror()
v fopen()
v fclose()
v msgrcv()
v msgctl()
v perror()
RELATED TASKS
Running in z/OS UNIX environments on page 453
Setting and accessing environment variables on page 454
Accessing main program parameters under z/OS UNIX
Language Environment Programming Guide
RELATED REFERENCES
XL C/C++ Run-Time Library Reference
UNIX System Services Programming: Assembler Callable Services Reference
Accessing main program parameters under z/OS UNIX
When you run a COBOL program from the z/OS UNIX shell command line or
with an exec() or spawn() function, the parameter list consists of three parameters
passed by reference. You can access these parameters with standard COBOL
coding.
argument count
A binary fullword integer that contains the number of elements in each of
the arrays that are passed in the second and third parameters.
argument length list
An array of pointers. The nth entry in the array is the address of a
fullword binary integer that contains the length of the nth entry in the
argument list.
argument list
An array of pointers. The nth entry in the array is the address of the nth
character string passed as an argument in the spawn() or exec() function or
in the command invocation. Each character string is null-terminated.
This array is never empty. The first argument is the character string that
represents the name of the file associated with the process being started.
Example: accessing main program parameters under z/OS UNIX on page 459
RELATED TASKS
Running in z/OS UNIX environments on page 453
Setting and accessing environment variables on page 454
Calling UNIX/POSIX APIs on page 456
Accessing main program parameters under z/OS on page 495
458 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: accessing main program parameters under z/OS
UNIX
The following example shows the three parameters that are passed by reference,
and shows the coding that you can use to access them.
Identification division.
Program-id. "EXECED".
****************************************************************
* This sample program displays arguments received via exec() *
* function of z/OS UNIX *
****************************************************************
Data division.
Working-storage section.
01 curr-arg-count pic 9(9) binary value zero.
Linkage section.
01 arg-count pic 9(9) binary. (1)
01 arg-length-list. (2)
05 arg-length-addr pointer occurs 1 to 99999
depending on curr-arg-count.
01 arg-list. (3)
05 arg-addr pointer occurs 1 to 99999
depending on curr-arg-count.
01 arg-length pic 9(9) binary.
01 arg pic X(65536).
Procedure division using arg-count arg-length-list arg-list.
*****************************************************************
* Display number of arguments received *
*****************************************************************
Display "Number of arguments received: " arg-count
*****************************************************************
* Display each argument passed to this program *
*****************************************************************
Perform arg-count times
Add 1 to curr-arg-count
* *******************************************************
* * Set address of arg-length to address of current *
* * argument length and display *
* *******************************************************
Set Address of arg-length
to arg-length-addr(curr-arg-count)
Display
"Length of Arg " curr-arg-count " = " arg-length
* *******************************************************
* * Set address of arg to address of current argument *
* * and display *
* *******************************************************
Set Address of arg to arg-addr(curr-arg-count)
Display "Arg " curr-arg-count " = " arg (1:arg-length)
End-Perform
Display "Display of arguments complete."
Goback.
(1) This count contains the number of elements in the arrays that are passed in
the second and third parameters.
(2) This array contains a pointer to the length of the nth entry in the argument
list.
(3) This array contains a pointer to the nth character string passed as an
argument in the spawn() or exec() function or in the command invocation.
Chapter 23. Running COBOL programs under z/OS UNIX 459
460 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 4. Structuring complex applications
Copyright IBM Corp. 1991, 2015 461
462 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 24. Using subprograms
Many applications consist of several separately compiled programs linked together.
A run unit (the COBOL term that is synonymous with the Language Environment
term enclave) includes one or more object programs and can include object
programs written in other Language Environment member languages.
Language Environment provides interlanguage support that lets your Enterprise
COBOL programs call and be called by programs that meet the requirements of
Language Environment.
Name prefix alert: Do not use program-names that start with prefixes used by IBM
products. If you use programs whose names start with such prefixes, CALL
statements might resolve to IBM library or compiler routines rather than to the
intended program. For a list of prefixes to avoid, see the related task about
identifying a program.
RELATED CONCEPTS
Main programs, subprograms, and calls
RELATED TASKS
Identifying a program on page 3
Ending and reentering main programs or subprograms on page 464
Transferring control to another program on page 465
Making recursive calls on page 477
Calling to and from object-oriented programs on page 477
Using procedure and function pointers on page 477
Making programs reentrant on page 480
Handling COBOL limitations with multithreading on page 512
Language Environment Writing ILC Communication Applications
RELATED REFERENCES
Language Environment Programming Guide (Register conventions)
Main programs, subprograms, and calls
If a COBOL program is the first program in a run unit, that COBOL program is the
main program. Otherwise, it and all other COBOL programs in the run unit are
subprograms. No specific source-code statements or options identify a COBOL
program as a main program or subprogram.
Whether a COBOL program is a main program or subprogram can be significant
for either of two reasons:
v Effect of program termination statements
v State of the program when it is reentered after returning
In the PROCEDURE DIVISION, a program can call another program (generally called a
subprogram), and this called program can itself call other programs. The program
that calls another program is referred to as the calling program, and the program it
calls is referred to as the called program. When the processing of the called
program is completed, the called program can either transfer control back to the
calling program or end the run unit.
Copyright IBM Corp. 1991, 2015 463
The called COBOL program starts running at the top of the PROCEDURE DIVISION.
RELATED TASKS
Ending and reentering main programs or subprograms
Transferring control to another program on page 465
Making recursive calls on page 477
RELATED REFERENCES
Language Environment Programming Guide
Ending and reentering main programs or subprograms
Whether a program is left in its last-used state or its initial state, and to which
caller it returns, can depend on the termination statements that you use.
You can use any of three termination statements in a program, but they have
different effects as shown in the following table.
Table 60. Effects of termination statements
Termination
statement Main program Subprogram
EXIT PROGRAM No action taken Return to calling program without
ending the run unit. An implicit EXIT
PROGRAM statement is generated if the
called program has no next executable
statement.
In a threaded environment, the thread
is not terminated unless the program is
the first (oldest) one in the thread.
STOP RUN Return to calling program.1 (Might Return directly to the program that
be the operating system, and called the main program.1 (Might be
application will end.) the operating system, and application
will end.)
STOP RUN terminates the run unit,
and deletes all dynamically called STOP RUN terminates the run unit, and
programs in the run unit and all deletes all dynamically called programs
programs link-edited with them. (It in the run unit and all programs
does not delete the main program.) link-edited with them. (It does not
delete the main program.)
In a threaded environment, the
entire Language Environment In a threaded environment, the entire
enclave is terminated, including all Language Environment enclave is
threads running within the terminated, including all threads
enclave. running within the enclave.
GOBACK Return to calling program.1 (Might Return to calling program.
be the operating system, and
application will end.) In a threaded environment, if the
program is the first program in a
GOBACK terminates the run unit, thread, the thread is terminated.2
and deletes all dynamically called
programs in the run unit and all
programs link-edited with them. (It
does not delete the main program.)
In a threaded environment, the
thread is terminated.2
464 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 60. Effects of termination statements (continued)
Termination
statement Main program Subprogram
1. If the main program is called by a program written in another language that does not
follow Language Environment linkage conventions, return is to this calling program.
2. If the thread is the initial thread of execution in an enclave, the enclave is terminated.
A subprogram is usually left in its last-used state when it terminates with EXIT
PROGRAM or GOBACK. The next time the subprogram is called in the run unit, its
internal values are as they were left, except that return values for PERFORM
statements are reset to their initial values. (In contrast, a main program is
initialized each time it is called.)
There are some cases in which programs will be in their initial state:
v A subprogram that is dynamically called and then canceled will be in the initial
state the next time it is called.
v A program that has the INITIAL clause in the PROGRAM-ID paragraph will be in
the initial state each time it is called.
v Data items defined in the LOCAL-STORAGE SECTION will be reset to the initial state
specified by their VALUE clauses each time the program is called.
RELATED CONCEPTS
Comparison of WORKING-STORAGE and LOCAL-STORAGE on page 14
Language Environment Programming Guide (What happens during termination:
thread termination)
RELATED TASKS
Calling nested COBOL programs on page 473
Making recursive calls on page 477
Transferring control to another program
You can use several different methods to transfer control to another program: static
calls, dynamic calls, calls to nested programs, and calls to dynamic link libraries
(DLLs).
In addition to making calls between Enterprise COBOL programs, you can also
make static and dynamic calls between Enterprise COBOL and programs compiled
with older compilers in all environments including CICS.
For restrictions about making calls with older levels of programs, see
Interoperability with older levels of IBM COBOL programs in the Enterprise COBOL
Migration Guide.
Calling nested programs lets you create applications using structured
programming techniques. You can use nested programs in place of PERFORM
procedures to prevent unintentional modification of data items. Call nested
programs using either the CALL literal or CALL identifier statement.
Calls to dynamic link libraries (DLLs) are an alternative to COBOL dynamic CALL,
and are well suited to object-oriented COBOL applications, z/OS UNIX programs,
and applications that interoperate with C/C++.
Chapter 24. Using subprograms 465
| Under z/OS, linking two program objects together results logically in a single
program with a primary entry point and an alternate entry point, each with its
own name. Each name by which a subprogram is to be dynamically called must be
| known to the system. You must specify each such name in binder (linkage-editor)
| control statements as either a NAME or an ALIAS of the program object that contains
the subprogram.
RELATED CONCEPTS
AMODE switching on page 469
Performance considerations of static and dynamic calls on page 471
Nested programs on page 474
RELATED TASKS
Making static calls
Making dynamic calls on page 467
Making both static and dynamic calls on page 471
Calling nested COBOL programs on page 473
RELATED REFERENCES
Enterprise COBOL Migration Guide
(Interoperability with older levels of IBM COBOL programs)
Making static calls
When you use the CALL literal statement in a program that is compiled using the
NODYNAM and NODLL compiler options, a static call occurs. With these options, all
CALL literal calls are handled as static calls.
With static calls statement, the COBOL program and all called programs are part of
| the same program object. When control is transferred, the called program already
resides in storage, and a branch to it takes place. Subsequent executions of the CALL
statement make the called program available in its last-used state unless the called
program has the INITIAL attribute. In that case, the called program and each
program directly or indirectly contained within it are placed into their initial state
each time the called program is called within a run unit.
If you specify alternate entry points, a static CALL statement can use any alternate
entry point to enter the called subprogram.
Examples: static and dynamic CALL statements on page 472
RELATED CONCEPTS
Performance considerations of static and dynamic calls on page 471
RELATED TASKS
Making dynamic calls on page 467
Making both static and dynamic calls on page 471
Calling to and from object-oriented programs on page 477
RELATED REFERENCES
DLL on page 321
DYNAM on page 323
CALL statement (Enterprise COBOL Language Reference)
466 Enterprise COBOL for z/OS, V5.2 Programming Guide
Making dynamic calls
When you use a CALL literal statement in a program that is compiled using the
DYNAM and the NODLL compiler options, or when you use the CALL identifier
statement in a program that is compiled using the NODLL compiler option, a
dynamic call occurs.
In these forms of the CALL statement, the called COBOL subprogram is not
link-edited with the main program. Instead, it is link-edited into a separate
| program object, and is loaded at run time only when it is required (that is, when
called). The program-name in the PROGRAM-ID paragraph or ENTRY statement must
| be identical to the corresponding program object name or program object alias of
| the program object that contains the program.
Each subprogram that you call with a dynamic CALL statement can be part of a
| different program object that is a member of either the system link library or a
private library that you supply. In either case it must be in an MVS load library; it
cannot reside in the z/OS UNIX file system. When a dynamic CALL statement calls
a subprogram that is not resident in storage, the subprogram is loaded from
secondary storage into the region or partition that contains the main program, and
a branch to the subprogram is performed.
The first dynamic call to a subprogram within a run unit obtains a fresh copy of
the subprogram. Subsequent calls to the same subprogram (by either the original
caller or any other subprogram within the same run unit) result in a branch to the
same copy of the subprogram in its last-used state, provided the subprogram does
not possess the INITIAL attribute. Therefore, the reinitialization of either of the
following items is your responsibility:
v GO TO statements that have been altered
v Data items
If you call the same COBOL program in different run units, a separate copy of
WORKING-STORAGE is allocated for each run unit.
Restrictions: You cannot make dynamic calls to:
v COBOL DLL programs
v COBOL programs compiled with the PGMNAME(LONGMIXED) option, unless the
program-name is less than or equal to eight characters in length and is all
uppercase
v COBOL programs compiled with the PGMNAME(LONGUPPER) option, unless the
program-name is less than or equal to eight characters in length
v More than one entry point in the same COBOL program (unless an intervening
CANCEL statement was executed)
Examples: static and dynamic CALL statements on page 472
RELATED CONCEPTS
When to use a dynamic call with subprograms on page 468
Performance considerations of static and dynamic calls on page 471
RELATED TASKS
Canceling a subprogram on page 468
Making static calls on page 466
Making both static and dynamic calls on page 471
Chapter 24. Using subprograms 467
RELATED REFERENCES
DLL on page 321
DYNAM on page 323
ENTRY statement (Enterprise COBOL Language Reference)
CALL statement (Enterprise COBOL Language Reference)
Language Environment Programming Reference
Canceling a subprogram
When you issue a CANCEL statement for a subprogram, the storage that is occupied
by the subprogram is freed. A subsequent call to the subprogram functions as
though it were the first call. You can cancel a subprogram from a program other
than the original caller.
If the called subprogram has more than one entry point, ensure that an intervening
CANCEL statement is executed before you specify different entry points in a dynamic
CALL statement to that subprogram.
After a CANCEL statement is processed for a dynamically called contained program,
the program will be in its first-used state. However, the program is not loaded
with the initial call, and storage is not freed after the program is canceled.
Examples: static and dynamic CALL statements on page 472
RELATED CONCEPTS
Performance considerations of static and dynamic calls on page 471
When to use a dynamic call with subprograms
Your decision to use dynamic calls with subprograms depends on factors such as
| location of the program object, frequency of calls to the subprograms, size of the
subprograms, ease of maintenance, the need to call subprograms in their unused
state, the need for AMODE switching, and when the program-names are known.
| The program object that you want to dynamically call must be in an MVS load
library rather than in the z/OS UNIX file system.
If subprograms are called in only a few conditions, you can use dynamic calls to
bring in the subprograms only when needed.
If the subprograms are very large or there are many of them, using static calls
might require too much main storage. Less total storage might be required to call
and cancel one, then call and cancel another, than to statically call both.
If you are concerned about ease of maintenance, dynamic calls can help.
Applications do not have to be link-edited again when dynamically called
subprograms are changed.
When you cannot use the INITIAL attribute to ensure that a subprogram is placed
in its unused state each time that it is called, you can set the unused state by using
a combination of dynamic CALL and CANCEL statements. When you cancel a
subprogram that was first called by a COBOL program, the next call causes the
subprogram to be reinitialized to its unused state.
Using the CANCEL statement to explicitly cancel a subprogram that was dynamically
loaded and branched to by a non-COBOL program does not result in any action
being taken to release the subprogram's storage or to delete the subprogram.
468 Enterprise COBOL for z/OS, V5.2 Programming Guide
Suppose you have an AMODE 24 program in the same run unit with Enterprise
COBOL programs that you want to run in 31-bit addressing mode. COBOL
dynamic call processing includes AMODE switching for AMODE 24 programs that call
AMODE 31 programs, and vice versa. To have this implicit AMODE switching done, the
Language Environment runtime options ALL31(OFF) and STACK(,,BELOW) must be
in effect.
When dynamic call is performed, control is passed from the caller to a Language
Environment library routine. After the switching is performed, control passes to
the called program; the save area for the library routine will be positioned between
the save area for the caller program and the save area for the called program.
If you do not know the program-name to be called until run time, use the format
CALL identifier, where identifier is a data item that will contain the name of the
called program at run time. For example, you could use CALL identifier when the
program to be called varies depending on conditional processing in your program.
CALL identifier is always dynamic, even if you use the NODYNAM compiler option.
Examples: static and dynamic CALL statements on page 472
RELATED CONCEPTS
AMODE switching
Performance considerations of static and dynamic calls on page 471
RELATED TASKS
Making dynamic calls on page 467
RELATED REFERENCES
DYNAM on page 323
CALL statement (Enterprise COBOL Language Reference)
Language Environment Programming Reference
AMODE switching
When you have an application that has COBOL subprograms, some of the COBOL
subprograms can be AMODE 31 and some can be AMODE 24. To have this mixed AMODE
support, the calls must be dynamic and the Language Environment runtime
options ALL31(OFF) and STACK(,,BELOW) must be in effect.
If your application consists of only COBOL programs, and you are using dynamic
calls, each COBOL subprogram will always be entered in the proper AMODE. For
example, if you are using a dynamic call from an AMODE 31 COBOL program to an
AMODE 24 COBOL program, the AMODE is automatically switched.
However, if you are using procedure pointers, function pointers, or other
languages that call COBOL subprograms, you must ensure that when a COBOL
program is called more than once in an enclave, it is entered in the same AMODE
each time that it is called. The AMODE is not automatically switched in this case.
The following scenario shows that AMODE problems can arise when procedure
pointers are used to call COBOL subprograms. This scenario is not supported
because the COBOL program COBOLY is not entered in the same AMODE each time
that it is called.
Chapter 24. Using subprograms 469
1. COBOLX is AMODE 31. It uses the SET statement to set a procedure pointer to
| COBOLZ. COBOLZ is a reentrant program object and is AMODE 31 and RMODE
24. COBOLX calls COBOLZ using the procedure pointer. COBOLZ is entered in
AMODE 31.
2. COBOLZ returns to COBOLX.
3. COBOLX dynamically calls COBOLY, passing the procedure pointer for
| COBOLZ. COBOLY is a reentrant program object, and is AMODE 24 and RMODE
24. COBOLY is entered in AMODE 24.
4. COBOLY calls COBOLZ using the procedure pointer. This call causes COBOLZ
to be entered in AMODE 24, which is not the same AMODE in which COBOLZ was
entered when it was called the first time.
The following scenario uses a mix of COBOL and assembler language. This
scenario is not supported because the COBOL program COBOLB is not entered in
the same AMODE each time that it is called.
1. COBOLA is AMODE 31. COBOLA dynamically calls COBOLB. COBOLB is a
| reentrant program object and is AMODE 31 and RMODE 24. COBOLB is entered in
AMODE 31.
2. COBOLB returns to COBOLA.
470 Enterprise COBOL for z/OS, V5.2 Programming Guide
3. COBOLA dynamically calls ASSEM10, which is in assembler language.
| ASSEM10 is a reentrant program object, and is AMODE 24 and RMODE 24.
ASSEM10 is entered in AMODE 24.
4. ASSEM10 loads COBOLB. ASSEM10 does a BALR instruction to COBOLB.
COBOLB is entered in AMODE 24, which is not the same AMODE in which
COBOLB was entered when it was called the first time.
RELATED CONCEPTS
Storage and its addressability on page 39
When to use a dynamic call with subprograms on page 468
RELATED TASKS
Making dynamic calls on page 467
RELATED REFERENCES
Language Environment Programming Reference (ALL31)
Performance considerations of static and dynamic calls
| Because a statically called program is link-edited into the same program object as
the calling program, a static call is faster than a dynamic call. A static call is the
preferred method if your application does not require the services of the dynamic
call.
Statically called programs cannot be deleted using CANCEL, so static calls might take
more main storage. If storage is a concern, think about using dynamic calls.
Storage usage of calls depends on whether:
v The subprogram is called only a few times. Regardless of whether it is called, a
statically called program is loaded into storage; a dynamically called program is
loaded only when it is called.
v You subsequently delete the dynamically called subprogram with a CANCEL
statement.
You cannot delete a statically called program, but you can delete a dynamically
called program. Using a dynamic call and then a CANCEL statement to delete the
dynamically called program after it is no longer needed in the application (and
not after each call to it) might require less storage than using a static call.
RELATED CONCEPTS
When to use a dynamic call with subprograms on page 468
RELATED TASKS
Making static calls on page 466
Making dynamic calls on page 467
Making both static and dynamic calls
You can use both static and dynamic CALL statements in the same program if you
compile the program with the NODYNAM compiler option.
In this case, with the CALL literal statement, the called subprogram will be
| link-edited with the main program into one program object. The CALL identifier
| statement results in the dynamic invocation of a separate program object.
When a dynamic CALL statement and a static CALL statement to the same
subprogram are issued within one program, a second copy of the subprogram is
Chapter 24. Using subprograms 471
loaded into storage. Because this arrangement does not guarantee that the
subprogram will be left in its last-used state, results can be unpredictable.
RELATED REFERENCES
DYNAM on page 323
Examples: static and dynamic CALL statements
This example shows how you can code static and dynamic calls.
The example has three parts:
v Code that uses a static call to call a subprogram
v Code that uses a dynamic call to call the same subprogram
v The subprogram that is called by the two types of calls
The following example shows how you would code static calls:
PROCESS NODYNAM NODLL
IDENTIFICATION DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 RECORD-2 PIC X. (6)
01 RECORD-1. (2)
05 PAY PICTURE S9(5)V99.
05 HOURLY-RATE PICTURE S9V99.
05 HOURS PICTURE S99V9.
. . .
PROCEDURE DIVISION.
CALL "SUBPROG" USING RECORD-1. (1)
CALL "PAYMASTR" USING RECORD-1 RECORD-2. (5)
STOP RUN.
The following example shows how you would code dynamic calls:
DATA DIVISION.
WORKING-STORAGE SECTION.
77 PGM-NAME PICTURE X(8).
01 RECORD-2 PIC x. (6)
01 RECORD-1. (2)
05 PAY PICTURE S9(5)V99.
05 HOURLY-RATE PICTURE S9V99.
05 HOURS PICTURE S99V9.
. . .
PROCEDURE DIVISION.
. . .
MOVE "SUBPROG" TO PGM-NAME.
CALL PGM-NAME USING RECORD-1. (1)
CANCEL PGM-NAME.
MOVE "PAYMASTR" TO PGM-NAME. (4)
CALL PGM-NAME USING RECORD-1 RECORD-2. (5)
STOP RUN.
The following example shows a called subprogram that is called by each of the
two preceding calling programs:
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBPROG.
DATA DIVISION.
LINKAGE SECTION.
01 PAYREC. (2)
10 PAY PICTURE S9(5)V99.
10 HOURLY-RATE PICTURE S9V99.
10 HOURS PICTURE S99V9.
77 PAY-CODE PICTURE 9. (6)
PROCEDURE DIVISION USING PAYREC. (1)
472 Enterprise COBOL for z/OS, V5.2 Programming Guide
. . .
EXIT PROGRAM. (3)
ENTRY "PAYMASTR" USING PAYREC PAY-CODE. (5)
. . .
GOBACK. (7)
(1) Processing begins in the calling program. When the first CALL statement is
executed, control is transferred to the first statement of the PROCEDURE
DIVISION in SUBPROG, which is the called program.
In each of the CALL statements, the operand of the first USING option is
identified as RECORD-1.
(2) When SUBPROG receives control, the values within RECORD-1 are made
available to SUBPROG; however, in SUBPROG they are referred to as PAYREC.
The PICTURE character-strings within PAYREC and PAY-CODE contain the same
number of characters as RECORD-1 and RECORD-2, although the descriptions
are not identical.
(3) When processing within SUBPROG reaches the EXIT PROGRAM statement,
control is returned to the calling program. Processing continues in that
program until the second CALL statement is executed.
(4) In the example of a dynamically called program, because the second CALL
statement refers to another entry point within SUBPROG, a CANCEL statement
is executed before the second CALL statement.
(5) With the second CALL statement in the calling program, control is again
transferred to SUBPROG, but this time processing begins at the statement
following the ENTRY statement in SUBPROG.
(6) The values within RECORD-1 are again made available to PAYREC. In
addition, the value in RECORD-2 is now made available to SUBPROG through
the corresponding USING operand, PAY-CODE.
When control is transferred the second time from the statically linked
program, SUBPROG is made available in its last-used state (that is, if any
values in SUBPROG storage were changed during the first execution, those
changed values are still in effect). When control is transferred from the
dynamically linked program, however, SUBPROG is made available in its
initial state, because of the CANCEL statement that has been executed.
(7) When processing reaches the GOBACK statement, control is returned to the
calling program at the statement immediately after the second CALL
statement.
In any given execution of the called program and either of the two calling
programs, if the values within RECORD-1 are changed between the time of the first
CALL and the second, the values passed at the time of the second CALL statement
will be the changed, not the original, values. If you want to use the original values,
you must save them.
Calling nested COBOL programs
By calling nested programs, you can create applications that use structured
programming techniques. You can also call nested programs instead of PERFORM
procedures to prevent unintentional modification of data items.
Use either CALL literal or CALL identifier statements to make calls to nested
programs.
Chapter 24. Using subprograms 473
You can call a contained program only from its directly containing program unless
you identify the contained program as COMMON in its PROGRAM-ID paragraph. In that
case, you can call the common program from any program that is contained (directly
or indirectly) in the same program as the common program. Only contained
programs can be identified as COMMON. Recursive calls are not allowed.
Follow these guidelines when using nested program structures:
v Code an IDENTIFICATION DIVISION in each program. All other divisions are
optional.
v Optionally make the name of each contained program unique. Although the
names of contained programs are not required to be unique (as described in the
related reference about scope of names), making the names unique could help
make your application more maintainable. You can use any valid user-defined
word or an alphanumeric literal as the name of a contained program.
v In the outermost program, code any CONFIGURATION SECTION entries that might
be required. Contained programs cannot have a CONFIGURATION SECTION.
v Include each contained program in the containing program immediately before
the END PROGRAM marker of the containing program.
v Use an END PROGRAM marker to terminate contained and containing programs.
You cannot use the THREAD option when compiling programs that contain nested
programs.
RELATED CONCEPTS
Nested programs
RELATED REFERENCES
Scope of names on page 476
Nested programs
A COBOL program can nest, or contain, other COBOL programs. The nested
programs can themselves contain other programs. A nested program can be
directly or indirectly contained in a program.
There are four main advantages to nesting called programs:
v Nested programs provide a method for creating modular functions and
maintaining structured programming techniques. They can be used analogously
to perform procedures (using the PERFORM statement), but with more structured
control flow and with the ability to protect local data items.
v Nested programs let you debug a program before including it in an application.
v Nested programs enable you to compile an application with a single invocation
of the compiler.
v Calls to nested programs have the best performance of all the forms of COBOL
CALL statements.
The following example describes a nested structure that has directly and indirectly
contained programs:
474 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: structure of nested programs
RELATED TASKS
Calling nested COBOL programs on page 473
RELATED REFERENCES
Scope of names on page 476
Example: structure of nested programs
The following example shows a nested structure with some contained programs
that are identified as COMMON.
Chapter 24. Using subprograms 475
The following table describes the calling hierarchy for the structure that is shown
in the example above. Programs A12, A2, and A3 are identified as COMMON, and the
calls associated with them differ.
And can be called by these
This program Can call these programs programs
A A1, A2, A3 None
A1 A11, A12, A2, A3 A
A11 A111, A12, A2, A3 A1
A111 A12, A2, A3 A11
A12 A2, A3 A1, A11, A111
A2 A3 A, A1, A11, A111, A12, A3
A3 A2 A, A1, A11, A111, A12, A2
In this example, note that:
v A2 cannot call A1 because A1 is not common and is not contained in A2.
v A1 can call A2 because A2 is common.
Scope of names
Names in nested structures are divided into two classes: local and global. The class
determines whether a name is known beyond the scope of the program that
declares it. A specific search sequence locates the declaration of a name after it is
referenced in a program.
Local names:
Names (except the program-name) are local unless declared to be otherwise. Local
names are visible or accessible only within the program in which they are declared.
They are not visible or accessible to contained and containing programs.
Global names:
A name that is global (indicated by using the GLOBAL clause) is visible and
accessible to the program in which it is declared and to all the programs that are
directly and indirectly contained in that program. Therefore, the contained
programs can share common data and files from the containing program simply by
referencing the names of the items.
Any item that is subordinate to a global item (including condition-names and
indexes) is automatically global.
You can declare the same name with the GLOBAL clause more than one time,
provided that each declaration occurs in a different program. Be aware that you
can mask, or hide, a name in a nested structure by having the same name occur in
different programs in the same containing structure. However, such masking could
cause problems during a search for a name declaration.
Searches for name declarations:
When a name is referenced in a program, a search is made to locate the declaration
for that name. The search begins in the program that contains the reference and
continues outward to the containing programs until a match is found. The search
follows this process:
1. Declarations in the program are searched.
476 Enterprise COBOL for z/OS, V5.2 Programming Guide
2. If no match is found, only global declarations are searched in successive outer
containing programs.
3. The search ends when the first matching name is found. If no match is found,
an error exists.
The search is for a global name, not for a particular type of object associated with
the name such as a data item or file connector. The search stops when any match is
found, regardless of the type of object. If the object declared is of a different type
than that expected, an error condition exists.
Making recursive calls
A called program can directly or indirectly execute its caller. For example, program
X calls program Y, program Y calls program Z, and program Z then calls program
X. This type of call is recursive.
To make a recursive call, you must code the RECURSIVE clause in the PROGRAM-ID
paragraph of the recursively called program. If you try to recursively call a
COBOL program that does not have the RECURSIVE clause in the PROGRAM-ID
paragraph, a condition is signaled. If the condition remains unhandled, the run
unit will end.
RELATED TASKS
Identifying a program as recursive on page 4
RELATED REFERENCES
PROGRAM-ID paragraph (Enterprise COBOL Language Reference)
Calling to and from object-oriented programs
When you create applications that contain object-oriented (OO) programs, the OO
COBOL programs are DLL programs and can be in one or more dynamic link
libraries (DLLs). Each class definition must be in a separate DLL, however.
Calls to or from COBOL DLL programs must either use DLL linkage or be static
calls. COBOL dynamic calls to or from COBOL DLL programs are not supported.
If you must call a COBOL DLL program from a COBOL non-DLL program, other
means to ensure that the DLL linkage mechanism is followed are available.
Using procedure and function pointers
You can set procedure-pointer and function-pointer data items only by using
format 6 of the SET statement.
Procedure pointers are data items defined with the USAGE IS PROCEDURE-POINTER
clause. Function pointers are data items defined with the USAGE IS
FUNCTION-POINTER clause. In this information, pointer refers to either a
procedure-pointer data item or a function-pointer data item. You can set either of
these data items to contain entry addresses of, or pointers to, these entry points:
v Another COBOL program that is not nested. For example, to have a user-written
error-handling routine take control when an exception condition occurs, you
must first pass the entry address of the routine to CEEHDLR, a
condition-management Language Environment callable service, so that the
routine is registered.
Chapter 24. Using subprograms 477
v A program written in another language. For example, to receive the entry
address of a C function, call the function with the CALL RETURNING statement. It
will return a pointer that you can either use as a function pointer or convert to a
procedure pointer by using a form of the SET statement.
v An alternate entry point in another COBOL program (as defined in an ENTRY
statement).
The SET statement sets the pointer to refer either to an entry point in the same
| program object as your program, to a separate program object, or to an entry point
that is exported from a DLL, depending on the DYNAM|NODYNAM and DLL|NODLL
compiler options. Therefore, consider these factors when using these pointer data
items:
v If you compile a program with the NODYNAM and NODLL options and set a pointer
item to a literal value (to an actual name of an entry point), the value must refer
| to an entry point in the same program object. Otherwise the reference cannot be
resolved.
v If you compile a program with the NODLL option and either set a pointer item to
an identifier that will contain the name of the entry point at run time or set the
pointer item to a literal and compile with the DYNAM option, then the pointer
item, whether a literal or variable, must point to an entry point in a separate
| program objectlink. The entry point can be either the primary entry point or an
| alternate entry point named in an ALIAS binder (linkage-editor) statement.
v If you compile with the NODYNAM and DLL options and set a pointer item to a
literal value (the actual name of an entry point), the value must refer to an entry
| point in the same program object or to an entry-point name that is exported
from a DLL module. In the latter case you must include the DLL side file for the
| target DLL module in the link-edit of your program object.
v If you compile with the NODYNAM and DLL options and set a pointer item to an
identifier (a data item that contains the entry point name at run time), the
identifier value must refer to the entry-point name that is exported from a DLL
module. In this case the DLL module name must match the name of the
exported entry point.
| If you set a pointer item to an entry address in a dynamically called program
| object, and your program subsequently cancels that dynamically called module,
then that pointer item becomes undefined. Reference to it thereafter is not reliable.
Procedure pointer and function pointer calls are supported for AMODE 24
applications. However, the addressing mode cannot be switched for these calls, so
the called and calling programs must have the same addressing mode at execution
time.
COBOL entry points with the AMODE ANY attribute can be entered in either AMODE 31
or AMODE 24. However, the AMODE value that is in effect when the program is
entered for the first time must also be in effect for all subsequent reentries of the
program during the current Language Environment enclave.
RELATED TASKS
Deciding which type of pointer to use on page 479
Calling alternate entry points on page 479
Using procedure or function pointers with DLLs on page 503
RELATED REFERENCES
DLL on page 321
DYNAM on page 323
478 Enterprise COBOL for z/OS, V5.2 Programming Guide
CANCEL statement (Enterprise COBOL Language Reference)
Format 6: SET for procedure-pointer and function-pointer data items
(Enterprise COBOL Language Reference)
ENTRY statement (Enterprise COBOL Language Reference)
MVS Program Management: User's Guide and Reference
Deciding which type of pointer to use
Use procedure pointers to call other COBOL programs and to call Language
Environment callable services. Use function pointers to communicate with C/C++
programs or with services provided by the Java Native Interface.
Procedure pointers are more efficient than function pointers for COBOL-to-COBOL
calls, and are required for calls to Language Environment condition-handling
services.
Many callable services written in C return function pointers. You can call such a C
function pointer from your COBOL program by using COBOL function pointers as
shown below.
IDENTIFICATION DIVISION.
PROGRAM-ID. DEMO.
ENVIRONMENT DIVISION.
DATA DIVISION.
*
WORKING-STORAGE SECTION.
01 FP USAGE FUNCTION-POINTER.
*
PROCEDURE DIVISION.
CALL "c-function" RETURNING FP.
CALL FP.
RELATED TASKS
Using procedure or function pointers with DLLs on page 503
Accessing JNI services on page 623
Calling alternate entry points
Static calls to alternate entry points work without restriction.
Dynamic calls to alternate entry points require the following elements:
| v Either explicitly specified NAME or ALIAS binder (linkage-editor) control
statements, or use of the NAME compiler option which generates them
automatically.
v An intervening CANCEL for any dynamic call to the same module at a different
entry point. CANCEL causes the program to be invoked in initial state when it is
called at a new entry point.
You can specify another entry point at which a program will begin running by
using the ENTRY label in the called program. However, this method is not
recommended in a structured program.
Examples: static and dynamic CALL statements on page 472
RELATED REFERENCES
NAME on page 337
CANCEL statement (Enterprise COBOL Language Reference)
ENTRY statement (Enterprise COBOL Language Reference)
MVS Program Management: User's Guide and Reference
Chapter 24. Using subprograms 479
Making programs reentrant
If more than one user will run an application program at the same time (for
example, users in different address spaces accessing a program that resides in the
link pack area), you must make the program reentrant by compiling with the RENT
option.
You do not need to worry about multiple copies of variables. The compiler creates
the necessary reentrancy controls in the object module.
The following Enterprise COBOL programs must be reentrant:
v Programs to be used with CICS
v Programs to be preloaded with IMS
v Programs to be used as DB2 stored procedures
v Programs to be run in the z/OS UNIX environment
v Programs that are enabled for DLL support
v Programs that use object-oriented syntax
For reentrant programs, use the DATA compiler option and the HEAP and ALL31
runtime options to control whether dynamic data areas, such as WORKING-STORAGE,
are obtained from storage below or above the 16 MB line.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Compiling programs to create DLLs on page 498
Chapter 16, Compiling, linking, and running OO applications, on page 291
RELATED REFERENCES
RENT on page 348
DATA on page 318
Language Environment Programming Reference (ALL31, HEAP)
480 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 25. Sharing data
If a run unit consists of several separately compiled programs that call each other,
the programs must be able to communicate with each other. They also usually
need access to common data.
This information describes how you can write programs that share data with other
programs. In this information, a subprogram is any program that is called by
another program.
RELATED TASKS
Using data from another program on page 16
Sharing data with Java on page 627
Passing data
Coding the LINKAGE SECTION on page 485
Coding the PROCEDURE DIVISION for passing arguments on page 486
Passing return-code information on page 490
Sharing data by using the EXTERNAL clause on page 491
Sharing files between programs (external files) on page 491
Accessing main program parameters under z/OS on page 495
Passing data
You can choose among three ways of passing data between programs: BY
REFERENCE, BY CONTENT, or BY VALUE.
BY REFERENCE
The subprogram refers to and processes the data items in the storage of the
calling program rather than working on a copy of the data. BY REFERENCE is
the assumed passing mechanism for a parameter if none of the three ways
is specified or implied for the parameter.
BY CONTENT
The calling program passes only the contents of the literal or identifier. The
called program cannot change the value of the literal or identifier in the
calling program, even if it modifies the data item in which it received the
literal or identifier.
BY VALUE
The calling program or method passes the value of the literal or identifier,
not a reference to the sending data item. The called program or invoked
method can change the parameter. However, because the subprogram or
method has access only to a temporary copy of the sending data item, any
change does not affect the argument in the calling program.
The following figure shows the differences in values passed BY REFERENCE, BY
CONTENT, and BY VALUE:
Copyright IBM Corp. 1991, 2015 481
Determine which of these data-passing methods to use based on what you want
your program to do with the data.
Table 61. Methods for passing data in the CALL statement
Code Purpose Comments
CALL . . . BY REFERENCE To have the definition of the argument Any changes made by the subprogram
identifier of the CALL statement in the calling to the parameter affect the argument in
program and the definition of the the calling program.
parameter in the called program share
the same memory
CALL . . . BY REFERENCE To pass the address of identifier to a Any changes made by the subprogram
ADDRESS OF identifier called program, where identifier is an to the address affect the address in the
item in the LINKAGE SECTION calling program.
CALL . . . BY REFERENCE To pass a data control block (DCB) to The file-name must reference a QSAM
file-name assembler programs sequential file.1
CALL . . . BY CONTENT ADDRESS To pass a copy of the address of Any changes to the copy of the address
OF identifier identifier to a called program will not affect the address of identifier,
but changes to identifier using the copy
of the address will cause changes to
identifier.
CALL . . . BY CONTENT identifier To pass a copy of the identifier to the Changes to the parameter by the
subprogram subprogram will not affect the caller's
identifier.
CALL . . . BY CONTENT literal To pass a copy of a literal value to a
called program
CALL . . . BY CONTENT LENGTH To pass a copy of the length of a data The calling program passes the length
OF identifier item of the identifier from its LENGTH special
register.
A combination of BY REFERENCE To pass both a data item and a copy of
and BY CONTENT such as: its length to a subprogram
CALL ERRPROC
USING BY REFERENCE A
BY CONTENT LENGTH OF A.
CALL . . . BY VALUE identifier To pass data to a program, such as a A copy of the identifier is passed
C/C++ program, that uses BY VALUE directly in the parameter list.
parameter linkage conventions
482 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 61. Methods for passing data in the CALL statement (continued)
Code Purpose Comments
CALL . . . BY VALUE literal To pass data to a program, such as a A copy of the literal is passed directly
C/C++ program, that uses BY VALUE in the parameter list.
parameter linkage conventions
CALL . . . BY VALUE ADDRESS OF To pass the address of identifier to a Any changes to the copy of the address
identifier called program. This is the will not affect the address of identifier,
recommended way to pass data to a but changes to identifier using the copy
C/C++ program that expects a pointer of the address will cause changes to
to the data. identifier.
CALL . . . RETURNING To call a C/C++ function with a
function return value
1. File-names as CALL operands are allowed as an IBM extension to COBOL. Any use of the extension generally
depends on the specific internal implementation of the compiler. Control block field settings might change in
future releases. Any changes made to the control block are the user's responsibility and are not supported by
IBM.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Describing arguments in the calling program
Describing parameters in the called program on page 484
Testing for OMITTED arguments on page 485
Specifying CALL . . . RETURNING on page 491
Sharing data by using the EXTERNAL clause on page 491
Sharing files between programs (external files) on page 491
Sharing data with Java on page 627
RELATED REFERENCES
CALL statement (Enterprise COBOL Language Reference)
The USING phrase (Enterprise COBOL Language Reference)
INVOKE statement (Enterprise COBOL Language Reference)
Describing arguments in the calling program
In the calling program, describe arguments in the DATA DIVISION in the same
manner as other data items in the DATA DIVISION.
Storage for arguments is allocated only in the outermost program. For example,
program A calls program B, which calls program C. Data items are allocated in
program A. They are described in the LINKAGE SECTION of programs B and C,
making the one set of data available to all three programs.
If you reference data in a file, the file must be open when the data is referenced.
Code the USING phrase of the CALL statement to pass the arguments. If you pass a
data item BY VALUE, it must be an elementary item.
To pass CALL arguments from AMODE 31 programs to AMODE 24 programs, you must
ensure that the arguments are in storage below the 16 MB line to be addressed by
the AMODE 24 subprogram.
v For reentrant AMODE 31 programs, compile the program with the DATA(24)
option, or specify the Language Environment runtime option HEAP(,,BELOW) if
Chapter 25. Sharing data 483
WORKING-STORAGE is allocated from HEAP storage. For more information
about when WORKING-STORAGE is allocated from HEAP storage, see Storage
and its addressability on page 39.
v For nonreentrant programs that are compiled with the NORENT option, compile
with the RMODE(24) or RMODE(AUTO) option. Consequently, the following items are
allocated below the 16 MB line, and can be passed as arguments to AMODE 24
programs:
WORKING-STORAGE data items without the EXTERNAL clause
FD record areas
QSAM buffers
v For mixed AMODE applications, the Language Environment runtime options
ALL31(OFF) and STACK(,,BELOW) are required. Consequently, the LOCAL-STORAGE
SECTION data items and data items with the EXTERNAL attributes will be allocated
below the 16 MB line, and can be passed as arguments to AMODE 24 programs.
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Coding the LINKAGE SECTION on page 485
Coding the PROCEDURE DIVISION for passing arguments on page 486
RELATED REFERENCES
The USING phrase (Enterprise COBOL Language Reference)
Describing parameters in the called program
You must know what data is being passed from the calling program and describe
it in the LINKAGE SECTION of each program that is called directly or indirectly by
the calling program.
Code the USING phrase after the PROCEDURE DIVISION header to name the
parameters that receive the data that is passed from the calling program.
When arguments are passed to the subprogram BY REFERENCE, it is invalid for the
subprogram to specify any relationship between its parameters and any fields
other than those that are passed and defined in the main program. The
subprogram must not:
v Define a parameter to be larger in total number of bytes than the corresponding
argument.
v Use subscript references to refer to elements beyond the limits of tables that are
passed as arguments by the calling program.
v Use reference modification to access data beyond the length of defined
parameters.
v Manipulate the address of a parameter in order to access other data items that
are defined in the calling program.
If any of the rules above are violated, unexpected results might occur.
RELATED TASKS
Coding the LINKAGE SECTION on page 485
RELATED REFERENCES
The USING phrase (Enterprise COBOL Language Reference)
484 Enterprise COBOL for z/OS, V5.2 Programming Guide
Testing for OMITTED arguments
You can specify that one or more BY REFERENCE arguments are not to be passed to a
called program by coding the OMITTED keyword in place of those arguments in the
CALL statement.
For example, to omit the second argument when calling program sub1, code this
statement:
Call sub1 Using PARM1, OMITTED, PARM3
The arguments in the USING phrase of the CALL statement must match the
parameters of the called program in number and position.
In a called program, you can test whether an argument was passed as OMITTED by
comparing the address of the corresponding parameter to NULL. For example:
Program-ID. sub1.
. . .
Procedure Division Using RPARM1, RPARM2, RPARM3.
If Address Of RPARM2 = Null Then
Display No 2nd argument was passed this time
Else
Perform Process-Parm-2
End-If
RELATED REFERENCES
CALL statement (Enterprise COBOL Language Reference)
The USING phrase (Enterprise COBOL Language Reference)
Coding the LINKAGE SECTION
Code the same number of data-names in the identifier list of the called program as
the number of arguments in the calling program. Synchronize by position, because
the compiler passes the first argument from the calling program to the first
identifier of the called program, and so on.
You will introduce errors if the number of data-names in the identifier list of a
called program is greater than the number of arguments passed from the calling
program. The compiler does not try to match arguments and parameters.
The following figure shows a data item being passed from one program to another
(implicitly BY REFERENCE):
Chapter 25. Sharing data 485
In the calling program, the code for parts (PARTCODE) and the part number (PARTNO)
are distinct data items. In the called program, by contrast, the code for parts and
the part number are combined into one data item (PART-ID). In the called program,
a reference to PART-ID is the only valid reference to these items.
RELATED TASKS
Accessing main program parameters under z/OS on page 495
Coding the PROCEDURE DIVISION for passing arguments
If you pass an argument BY VALUE, code the USING BY VALUE clause in the
PROCEDURE DIVISION header of the subprogram. If you pass an argument BY
REFERENCE or BY CONTENT, you do not need to indicate in the header how the
argument was passed.
PROCEDURE DIVISION USING BY VALUE. . .
PROCEDURE DIVISION USING. . .
PROCEDURE DIVISION USING BY REFERENCE. . .
The first header above indicates that the data items are passed BY VALUE; the
second or third headers indicate that the items are passed BY REFERENCE or BY
CONTENT.
RELATED REFERENCES
The procedure division header (Enterprise COBOL Language Reference)
The USING phrase (Enterprise COBOL Language Reference)
CALL statement (Enterprise COBOL Language Reference)
Grouping data to be passed
Consider grouping all the data items that you need to pass between programs and
putting them under one level-01 item. If you do so, you can pass a single level-01
record.
Note that if you pass a data item BY VALUE, it must be an elementary item.
To lessen the possibility of mismatched records, put the level-01 record into a copy
library and copy it into both programs. That is, copy it in the WORKING-STORAGE
SECTION of the calling program and in the LINKAGE SECTION of the called program.
RELATED TASKS
Coding the LINKAGE SECTION on page 485
RELATED REFERENCES
CALL statement (Enterprise COBOL Language Reference)
Handling null-terminated strings
COBOL supports null-terminated strings when you use string-handling verbs
together with null-terminated literals and the hexadecimal literal X00.
You can manipulate null-terminated strings (passed from a C program, for
example) by using string-handling mechanisms such as those in the following
code:
01 L pic X(20) value zab.
01 M pic X(20) value zcd.
01 N pic X(20).
01 N-Length pic 99 value zero.
01 Y pic X(13) value Hello, World!.
486 Enterprise COBOL for z/OS, V5.2 Programming Guide
To determine the length of a null-terminated string, and display the value of the
string and its length, code:
Inspect N tallying N-length for characters before initial X00
Display N: N(1:N-length) Length: N-length
To move a null-terminated string to an alphanumeric string, but delete the null,
code:
Unstring N delimited by X00 into X
To create a null-terminated string, code:
String Y delimited by size
X00 delimited by size
into N.
To concatenate two null-terminated strings, code:
String L delimited by x00
M delimited by x00
X00 delimited by size
into N.
RELATED TASKS
Manipulating null-terminated strings on page 110
RELATED REFERENCES
Null-terminated alphanumeric literals (Enterprise COBOL Language Reference)
Using pointers to process a chained list
When you need to pass and receive addresses of record areas, you can use pointer
data items, which are either data items that are defined with the USAGE IS POINTER
clause or are ADDRESS OF special registers.
A typical application for using pointer data items is in processing a chained list, a
series of records in which each record points to the next.
When you pass addresses between programs in a chained list, you can use NULL to
assign the value of an address that is not valid (nonnumeric 0) to a pointer item in
either of two ways:
v Use a VALUE IS NULL clause in its data definition.
v Use NULL as the sending field in a SET statement.
In the case of a chained list in which the pointer data item in the last record
contains a null value, you can use this code to check for the end of the list:
IF PTR-NEXT-REC = NULL
. . .
(logic for end of chain)
If the program has not reached the end of the list, the program can process the
record and move on to the next record.
The data passed from a calling program might contain header information that you
want to ignore. Because pointer data items are not numeric, you cannot directly
perform arithmetic on them. However, to bypass header information, you can use
the SET statement to increment the passed address.
Example: using pointers to process a chained list on page 488
Chapter 25. Sharing data 487
RELATED TASKS
Coding the LINKAGE SECTION on page 485
Coding the PROCEDURE DIVISION for passing arguments on page 486
RELATED REFERENCES
SET statement (Enterprise COBOL Language Reference)
Example: using pointers to process a chained list
The following example shows how you might process a linked list, that is, a
chained list of data items.
For this example, picture a chained list of data that consists of individual salary
records. The following figure shows one way to visualize how the records are
linked in storage. The first item in each record except the last points to the next
record. The first item in the last record contains a null value (instead of a valid
address) to indicate that it is the last record.
The high-level pseudocode for an application that processes these records might
be:
Obtain address of first record in chained list from routine
Check for end of the list
Do until end of the list
Process record
Traverse to the next record
End
The following code contains an outline of the calling program, LISTS, used in this
example of processing a chained list.
IDENTIFICATION DIVISION.
PROGRAM-ID. LISTS.
ENVIRONMENT DIVISION.
DATA DIVISION.
******
WORKING-STORAGE SECTION.
77 PTR-FIRST POINTER VALUE IS NULL. (1)
77 DEPT-TOTAL PIC 9(4) VALUE IS 0.
******
LINKAGE SECTION.
01 SALARY-REC.
02 PTR-NEXT-REC POINTER. (2)
02 NAME PIC X(20).
02 DEPT PIC 9(4).
02 SALARY PIC 9(6).
01 DEPT-X PIC 9(4).
******
PROCEDURE DIVISION USING DEPT-X.
******
* FOR EVERYONE IN THE DEPARTMENT RECEIVED AS DEPT-X,
* GO THROUGH ALL THE RECORDS IN THE CHAINED LIST BASED ON THE
* ADDRESS OBTAINED FROM THE PROGRAM CHAIN-ANCH
* AND ACCUMULATE THE SALARIES.
* IN EACH RECORD, PTR-NEXT-REC IS A POINTER TO THE NEXT RECORD
488 Enterprise COBOL for z/OS, V5.2 Programming Guide
* IN THE LIST; IN THE LAST RECORD, PTR-NEXT-REC IS NULL.
* DISPLAY THE TOTAL.
******
CALL "CHAIN-ANCH" USING PTR-FIRST (3)
SET ADDRESS OF SALARY-REC TO PTR-FIRST (4)
******
PERFORM WITH TEST BEFORE UNTIL ADDRESS OF SALARY-REC = NULL (5)
IF DEPT = DEPT-X
THEN ADD SALARY TO DEPT-TOTAL
ELSE CONTINUE
END-IF
SET ADDRESS OF SALARY-REC TO PTR-NEXT-REC (6)
END-PERFORM
******
DISPLAY DEPT-TOTAL
GOBACK.
(1) PTR-FIRST is defined as a pointer data item with an initial value of NULL.
On a successful return from the call to CHAIN-ANCH, PTR-FIRST contains the
address of the first record in the chained list. If something goes wrong
with the call, and PTR-FIRST never receives the value of the address of the
first record in the chain, a null value remains in PTR-FIRST and, according
to the logic of the program, the records will not be processed.
(2) The LINKAGE SECTION of the calling program contains the description of the
records in the chained list. It also contains the description of the
department code that is passed in the USING clause of the CALL statement.
(3) To obtain the address of the first SALARY-REC record area, the LISTS
program calls the program CHAIN-ANCH.
(4) The SET statement bases the record description SALARY-REC on the address
contained in PTR-FIRST.
(5) The chained list in this example is set up so that the last record contains an
address that is not valid. This check for the end of the chained list is
accomplished with a do-while structure where the value NULL is assigned
to the pointer data item in the last record.
(6) The address of the record in the LINKAGE-SECTION is set equal to the
address of the next record by means of the pointer data item sent as the
first field in SALARY-REC. The record-processing routine repeats, processing
the next record in the chained list.
To increment addresses received from another program, you could set up the
LINKAGE SECTION and PROCEDURE DIVISION like this:
LINKAGE SECTION.
01 RECORD-A.
02 HEADER PIC X(12).
02 REAL-SALARY-REC PIC X(30).
. . .
01 SALARY-REC.
02 PTR-NEXT-REC POINTER.
02 NAME PIC X(20).
02 DEPT PIC 9(4).
02 SALARY PIC 9(6).
. . .
PROCEDURE DIVISION USING DEPT-X.
. . .
SET ADDRESS OF SALARY-REC TO ADDRESS OF REAL-SALARY-REC
Chapter 25. Sharing data 489
The address of SALARY-REC is now based on the address of REAL-SALARY-REC, or
RECORD-A + 12.
RELATED TASKS
Using pointers to process a chained list on page 487
Passing return-code information
Use the RETURN-CODE special register to pass return codes between programs.
(Methods do not return information in the RETURN-CODE special register, but they
can check the register after a call to a program.)
You can also use the RETURNING phrase in the PROCEDURE DIVISION header of a
method to return information to an invoking program or method. If you use
PROCEDURE DIVISION . . . RETURNING with CALL . . . RETURNING, the RETURN-CODE
register will not be set.
Using the RETURN-CODE special register
When a COBOL program returns to its caller, the contents of the RETURN-CODE
special register are stored into register 15.
When control is returned to a COBOL program or method from a call, the contents
of register 15 are stored into the RETURN-CODE special register of the calling program
or method. When control is returned from a COBOL program to the operating
system, the special register contents are returned as a user return code.
You might need to think about this handling of the RETURN-CODE special register
when control is returned to a COBOL program from a non-COBOL program. If the
non-COBOL program does not use register 15 to pass back the return code, the
RETURN-CODE special register of the COBOL program might be updated with an
invalid value. Unless you set this special register to a meaningful value before
your Enterprise COBOL program returns to the operating system, a return code
that is invalid will be passed to the system.
For equivalent function between COBOL and C programs, have your COBOL
program call the C program with the RETURNING phrase. If the C program
(function) correctly declares a function value, the RETURNING value of the calling
COBOL program will be set.
You cannot set the RETURN-CODE special register by using the INVOKE statement.
Using PROCEDURE DIVISION RETURNING . . .
Use the RETURNING phrase in the PROCEDURE DIVISION header of a program to return
information to the calling program.
PROCEDURE DIVISION RETURNING dataname2
When the called program in the example above successfully returns to its caller,
the value in dataname2 is stored into the identifier that was specified in the
RETURNING phrase of the CALL statement:
CALL . . . RETURNING dataname2
CEEPIPI: The results of specifying PROCEDURE DIVISION RETURNING in programs that
are called with the Language Environment preinitialization service (CEEPIPI) are
undefined.
490 Enterprise COBOL for z/OS, V5.2 Programming Guide
Specifying CALL . . . RETURNING
You can specify the RETURNING phrase of the CALL statement for calls to C/C++
functions or to COBOL subroutines.
The RETURNING phrase has the following format.
CALL . . . RETURNING dataname2
The return value of the called program is stored into dataname2. You must define
dataname2 in the DATA DIVISION of the calling program. The data type of the return
value that is declared in the target function must be identical to the data type of
dataname2.
Sharing data by using the EXTERNAL clause
Use the EXTERNAL clause to enable separately compiled programs and methods
(including programs in a batch sequence) to share data items. Code EXTERNAL in the
level-01 data description in the WORKING-STORAGE SECTION.
The following rules apply:
v Items that are subordinate to an EXTERNAL group item are themselves EXTERNAL.
v You cannot use the name of an EXTERNAL data item as the name for another
EXTERNAL item in the same program.
v You cannot code the VALUE clause for any group item or subordinate item that is
EXTERNAL.
In the run unit, any COBOL program or method that has the same data description
for the item as the program that contains the item can access and process that item.
For example, suppose program A has the following data description:
01 EXT-ITEM1 EXTERNAL PIC 99.
Program B can access that data item if B has the identical data description in its
WORKING-STORAGE SECTION.
Any program that has access to an EXTERNAL data item can change the value of that
item. Therefore do not use this clause for data items that you need to protect.
Sharing files between programs (external files)
To enable separately compiled programs or methods in a run unit to access a file
as a common file, use the EXTERNAL clause for the file.
It is recommended that you follow these guidelines:
v Use the same data-name in the FILE STATUS clause of all the programs that
check the file status code.
v For each program that checks the same file status field, code the EXTERNAL clause
in the level-01 data definition for the file status field.
Using an external file has these benefits:
v Even if the main program does not contain any input or output statements, it
can reference the record area of the file.
v Each subprogram can control a single input or output function, such as OPEN or
READ.
v Each program has access to the file.
Chapter 25. Sharing data 491
Example: using external files
RELATED TASKS
Using data in input and output operations on page 11
RELATED REFERENCES
EXTERNAL clause (Enterprise COBOL Language Reference)
Example: using external files
The following example shows the use of an external file in several programs. COPY
statements ensure that each subprogram contains an identical description of the
file.
The following table describes the main program and subprograms.
Name Function
ef1 The main program, which calls all the subprograms and then verifies the
contents of a record area
ef1openo Opens the external file for output and checks the file status code
ef1write Writes a record to the external file and checks the file status code
ef1openi Opens the external file for input and checks the file status code
ef1read Reads a record from the external file and checks the file status code
ef1close Closes the external file and checks the file status code
Each program uses three copybooks:
v efselect is placed in the FILE-CONTROL paragraph:
Select ef1
Assign To ef1
File Status Is efs1
Organization Is Sequential.
v effile is placed in the FILE SECTION:
Fd ef1 Is External
Record Contains 80 Characters
Recording Mode F.
01 ef-record-1.
02 ef-item-1 Pic X(80).
v efwrkstg is placed in the WORKING-STORAGE SECTION:
01 efs1 Pic 99 External.
Input/output using external files
IDENTIFICATION DIVISION.
Program-Id.
ef1.
*
* This main program controls external file processing.
*
ENVIRONMENT DIVISION.
Input-Output Section.
File-Control.
Copy efselect.
DATA DIVISION.
FILE SECTION.
Copy effile.
WORKING-STORAGE SECTION.
Copy efwrkstg.
492 Enterprise COBOL for z/OS, V5.2 Programming Guide
PROCEDURE DIVISION.
Call "ef1openo"
Call "ef1write"
Call "ef1close"
Call "ef1openi"
Call "ef1read"
If ef-record-1 = "First record" Then
Display "First record correct"
Else
Display "First record incorrect"
Display "Expected: " "First record"
Display "Found : " ef-record-1
End-If
Call "ef1close"
Goback.
End Program ef1.
IDENTIFICATION DIVISION.
Program-Id.
ef1openo.
*
* This program opens the external file for output.
*
ENVIRONMENT DIVISION.
Input-Output Section.
File-Control.
Copy efselect.
DATA DIVISION.
FILE SECTION.
Copy effile.
WORKING-STORAGE SECTION.
Copy efwrkstg.
PROCEDURE DIVISION.
Open Output ef1
If efs1 Not = 0
Display "file status " efs1 " on open output"
Stop Run
End-If
Goback.
End Program ef1openo.
IDENTIFICATION DIVISION.
Program-Id.
ef1write.
*
* This program writes a record to the external file.
*
ENVIRONMENT DIVISION.
Input-Output Section.
File-Control.
Copy efselect.
DATA DIVISION.
FILE SECTION.
Copy effile.
WORKING-STORAGE SECTION.
Copy efwrkstg.
PROCEDURE DIVISION.
Move "First record" to ef-record-1
Write ef-record-1
If efs1 Not = 0
Display "file status " efs1 " on write"
Stop Run
End-If
Goback.
End Program ef1write.
Identification Division.
Program-Id.
ef1openi.
*
Chapter 25. Sharing data 493
* This program opens the external file for input.
*
ENVIRONMENT DIVISION.
Input-Output Section.
File-Control.
Copy efselect.
DATA DIVISION.
FILE SECTION.
Copy effile.
WORKING-STORAGE SECTION.
Copy efwrkstg.
PROCEDURE DIVISION.
Open Input ef1
If efs1 Not = 0
Display "file status " efs1 " on open input"
Stop Run
End-If
Goback.
End Program ef1openi.
Identification Division.
Program-Id.
ef1read.
*
* This program reads a record from the external file.
*
ENVIRONMENT DIVISION.
Input-Output Section.
File-Control.
Copy efselect.
DATA DIVISION.
FILE SECTION.
Copy effile.
WORKING-STORAGE SECTION.
Copy efwrkstg.
PROCEDURE DIVISION.
Read ef1
If efs1 Not = 0
Display "file status " efs1 " on read"
Stop Run
End-If
Goback.
End Program ef1read.
Identification Division.
Program-Id.
ef1close.
*
* This program closes the external file.
*
ENVIRONMENT DIVISION.
Input-Output Section.
File-Control.
Copy efselect.
DATA DIVISION.
FILE SECTION.
Copy effile.
WORKING-STORAGE SECTION.
Copy efwrkstg.
PROCEDURE DIVISION.
Close ef1
If efs1 Not = 0
Display "file status " efs1 " on close"
Stop Run
End-If
Goback.
End Program ef1close.
494 Enterprise COBOL for z/OS, V5.2 Programming Guide
Accessing main program parameters under z/OS
When you run an Enterprise COBOL program under z/OS and pass the program a
parameter string, for example, by using JCL or a TSO command, the parameter list
consists of a character string that has a halfword prefix that contains the string
length.
You can access the parameter string by using a LINKAGE SECTION and standard
COBOL coding as shown in the example referenced below:
Example: accessing main program parameters under z/OS
Alternatively, you can obtain the parameter string by calling either of the following
Language Environment callable services, which are described in the related
references below:
v CEE3PRM (query parameter string): obtain the parameter string (if not longer
than 80 characters)
v CEE3PR2 (query parameter string long): obtain the parameter string and its
length
In either case, the parameter string might contain program arguments, runtime
options, or both. The setting of the CBLOPTS runtime option determines the relative
order in which program arguments and runtime options are expected. If
CBLOPTS(ON) (the default) is in effect, and program arguments and runtime options
are both passed in the parameter string, they must appear in the following order,
separated by a forward slash:
program_arguments/runtime_options
For further details, see the related information referenced below.
RELATED TASKS
Coding the LINKAGE SECTION on page 485
Accessing main program parameters under z/OS UNIX on page 458
Language Environment Programming Guide (Specifying runtime options and
program arguments, Preparing your main routine to receive parameters)
RELATED REFERENCES
Language Environment Customization (CBLOPTS (COBOL only))
Language Environment Programming Reference (CEE3PRM, CEE3PR2)
Example: accessing main program parameters under z/OS
The following example shows how to receive a parameter string that is passed to a
COBOL program that runs under z/OS, and shows the coding that you can use to
access the parameter string.
IDENTIFICATION DIVISION.
PROGRAM-ID. "testarg".
*
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
*
DATA DIVISION.
WORKING-STORAGE SECTION.
*
linkage section.
01 os-parm.
05 parm-len pic s999 comp.
05 parm-string.
Chapter 25. Sharing data 495
10 parm-char pic x occurs 0 to 100 times
depending on parm-len.
*
PROCEDURE DIVISION using os-parm.
display "parm-len=" parm-len
display "parm-string=" parm-string ""
evaluate parm-string
when "01" display "case one"
when "02" display "case two"
when "95" display "case ninety-five"
when other display "case unknown"
end-evaluate
GOBACK.
Suppose that the CBLOPTS(ON) runtime option is in effect, and that you pass the
following argument in the JCL or TSO command that you use to run the program:
95/
Then the resulting output is:
parm-len=002
parm-string=95
case ninety-five
496 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 26. Creating a DLL or a DLL application
Creating a dynamic link library (DLL) or a DLL application is similar to creating a
regular COBOL application. It involves writing, compiling, and linking your source
code.
Special considerations when writing a DLL or a DLL application include:
| v Determining how the parts of the program object or the application relate to
each other or to other DLLs
v Deciding what linking or calling mechanisms to use
| Depending on whether you want to create a DLL program object or a program
| object that references a separate DLL, you need to use slightly different compiler
| and binder (linkage-editor) options.
RELATED CONCEPTS
Dynamic link libraries (DLLs)
RELATED TASKS
Creating a DLL under z/OS UNIX on page 286
Compiling programs to create DLLs on page 498
Linking DLLs on page 499
Using CALL identifier with DLLs on page 500
Using DLL linkage and dynamic calls together on page 502
Using COBOL DLLs with C/C++ programs on page 505
Using DLLs in OO COBOL applications on page 506
Using procedure or function pointers with DLLs on page 503
Dynamic link libraries (DLLs)
| A DLL is a program object that can be accessed from other separate program
| objects.
| A DLL differs from a traditional program object in that it exports definitions of
programs, functions, or variables to DLLs, DLL applications, or non-DLLs.
| Therefore, you do not need to link the target routines into the same program object
as the referencing routine. When an application references a separate DLL for the
first time, the system automatically loads the DLL into memory. In other words,
| calling a program in a DLL is similar to calling a program object with a dynamic
CALL.
Copyright IBM Corp. 1991, 2015 497
A DLL application is an application that references imported definitions of
programs, functions, or variables.
Although some functions of z/OS DLLs overlap the functions provided by COBOL
dynamic CALL statements, DLLs have several advantages over regular z/OS
| program objects and dynamic calls:
v DLLs are common across COBOL and C/C++, thus providing better
interoperation for applications that use multiple programming languages.
Reentrant COBOL and C/C++ DLLs can also interoperate smoothly.
v You can make calls to programs in separate DLL modules that have long
program-names. (Dynamic call resolution truncates program-names to eight
characters.) Using the COBOL option PGMNAME(LONGUPPER) or PGMNAME(LONGMIXED)
| and the COBOL DLL support, you can make calls between program objects with
names of up to 160 characters.
DLLs are supported by IBM z/OS Language Environment, based on function
provided by the z/OS program management binder. DLL support is available for
applications running under z/OS in batch or in TSO, CICS, z/OS UNIX, or IMS
environments.
RELATED REFERENCES
PGMNAME on page 345
MVS Program Management: User's Guide and Reference (Binder support for DLLs)
Compiling programs to create DLLs
When you compile a COBOL program with the DLL option, it becomes enabled for
DLL support. Applications that use DLL support must be reentrant. Therefore, you
must compile them with the RENT compiler option and link them with the RENT
binder option.
In an application with DLL support, use the following compiler options depending
on where the programs or classes are:
Table 62. Compiler options for DLL applications
Programs or classes in: Compile with:
| Root program object DLL, RENT, NOEXPORTALL
| DLL program objects used by other program DLL, RENT, EXPORTALL
| objects
498 Enterprise COBOL for z/OS, V5.2 Programming Guide
| If a DLL program object includes some programs that are used only from within
the DLL module, you can hide these routines by compiling them with NOEXPORTALL.
Example: sample JCL for a procedural DLL application on page 500
RELATED TASKS
Creating a DLL under z/OS UNIX on page 286
Linking DLLs
Chapter 26, Creating a DLL or a DLL application, on page 497
RELATED REFERENCES
DLL on page 321
EXPORTALL on page 326
RENT on page 348
Linking DLLs
| You can link DLL-enabled object modules into separate DLL program objects, or
you can link them together statically. You can decide whether to package the
application as one module or as several DLL modules at link time.
The DLL support in the z/OS binder is recommended for linking DLL
applications. The binder can directly receive the output of COBOL compilers.
A binder-based DLL must reside in a PDSE or in a z/OS UNIX file rather than in a
PDS.
When using the binder to link a DLL application, use the following options:
Table 63. Binder options for DLL applications
Type of code Link using binder parameters:
DLL applications DYNAM(DLL), RENT
Applications that use mixed-case exported CASE(MIXED)
program-names
Class definitions or INVOKE statements
You must specify a SYSDEFSD DD statement to indicate the data set in which the
binder should create a DLL definition side file. This side file contains IMPORT
control statements for each symbol exported by a DLL. The binder SYSLIN input
(the binding code that references the DLL code) must include the DLL definition
side files for DLLs that are to be referenced from the module being linked.
If there are programs in the module that you do not want to make available with
DLL linkage, you can edit the definition side file to remove these programs.
Example: sample JCL for a procedural DLL application on page 500
RELATED TASKS
Creating a DLL under z/OS UNIX on page 286
Chapter 26, Creating a DLL or a DLL application, on page 497
Compiling programs to create DLLs on page 498
RELATED REFERENCES
MVS Program Management: User's Guide and Reference (Binder support for DLLs)
Chapter 26. Creating a DLL or a DLL application 499
Example: sample JCL for a procedural DLL application
The following example shows how to create an application that consists of a main
program that calls a DLL subprogram.
| The first step creates the DLL program object that contains the subprogram
| DemoDLLSubprogram. The second step creates the main program object that contains
the program MainProgram. The third step runs the application.
//DLLSAMP JOB ,
// TIME=(1),MSGLEVEL=(1,1),MSGCLASS=H,CLASS=A,
// NOTIFY=&SYSUID,USER=&SYSUID
// SET LEPFX=SYS1
//*---------------------------------------------------------------------
//* Compile COBOL subprogram, bind to form a DLL.
//*---------------------------------------------------------------------
//STEP1 EXEC IGYWCL,REGION=80M,GOPGM=DEMODLL,
// PARM.COBOL=RENT,PGMN(LM),DLL,EXPORTALL,
// PARM.LKED=RENT,LIST,XREF,LET,MAP,DYNAM(DLL),CASE(MIXED)
//COBOL.SYSIN DD *
Identification division.
Program-id. "DemoDLLSubprogram".
Procedure division.
Display "Hello from DemoDLLSubprogram!".
End program "DemoDLLSubprogram".
/*
//LKED.SYSDEFSD DD DSN=&&SIDEDECK,UNIT=SYSDA,DISP=(NEW,PASS),
// SPACE=(TRK,(1,1))
//LKED.SYSLMOD DD DSN=&&GOSET(&GOPGM),DSNTYPE=LIBRARY,DISP=(MOD,PASS)
//LKED.SYSIN DD DUMMY
//*---------------------------------------------------------------------
//* Compile and bind COBOL main program
//*---------------------------------------------------------------------
//STEP2 EXEC IGYWCL,REGION=80M,GOPGM=MAINPGM,
// PARM.COBOL=RENT,PGMNAME(LM),DLL,
// PARM.LKED=RENT,LIST,XREF,LET,MAP,DYNAM(DLL),CASE(MIXED)
//COBOL.SYSIN DD *
Identification division.
Program-id. "MainProgram".
Procedure division.
Call "DemoDLLSubprogram"
Stop Run.
End program "MainProgram".
/*
//LKED.SYSIN DD DSN=&&SIDEDECK,DISP=(OLD,DELETE)
//*---------------------------------------------------------------------
//* Execute the main program, calling the subprogram DLL.
//*---------------------------------------------------------------------
//STEP3 EXEC PGM=MAINPGM,REGION=80M
//STEPLIB DD DSN=&&GOSET,DISP=(OLD,DELETE)
// DD DSN=&LEPFX..SCEERUN,DISP=SHR
// DD DSN=&LEPFX..SCEERUN2,DISP=SHR
//SYSOUT DD SYSOUT=*
//CEEDUMP DD SYSOUT=*
Using CALL identifier with DLLs
In a COBOL program that has been compiled with the DLL option, you can use
CALL identifier and CALL literal statements to make calls to DLLs. However, there are
a few additional considerations for the CALL identifier case.
For the content of the identifier or for the literal, use the name of either of the
following programs:
500 Enterprise COBOL for z/OS, V5.2 Programming Guide
v A nested program in the same compilation unit that is eligible to be called from
the program that contains the CALL identifier statement.
v A program in a separately bound DLL module. The target program-name must
be exported from the DLL, and the DLL module name must match the exported
name of the target program.
In the nonnested case, the runtime environment interprets the program-name in
the identifier according to the setting of the PGMNAME compiler option of the program
that contains the CALL statement, and interprets the program-name that is exported
from the target DLL according to the setting of the PGMNAME option used when the
target program was compiled.
The search for the target DLL in the z/OS UNIX file system is case sensitive. If the
target DLL is a PDS or PDSE member, the DLL member name must be eight
characters or less. For the purpose of the search for the DLL as a PDS or PDSE
member, the run time automatically converts the name to uppercase.
If the runtime environment cannot resolve the CALL statement in either of these
cases, control is transferred to the ON EXCEPTION or ON OVERFLOW phrase of the CALL
statement. If the CALL statement does not specify one of these phrases in this
situation, Language Environment raises a severity-3 condition.
RELATED TASKS
Using DLL linkage and dynamic calls together on page 502
Compiling programs to create DLLs on page 498
Linking DLLs on page 499
RELATED REFERENCES
DLL on page 321
PGMNAME on page 345
CALL statement (Enterprise COBOL Language Reference)
Search order for DLLs in the z/OS UNIX file system
Search order for DLLs in the z/OS UNIX file system
When you use the z/OS UNIX file system, the search order for resolving a DLL
reference in a CALL statement depends on the setting of the Language Environment
POSIX runtime option.
If the POSIX runtime option is ON, the search order is as follows:
1. The runtime environment looks for the DLL in the z/OS UNIX file system. If
the LIBPATH environment variable is set, the run time searches each directory
listed. Otherwise, it searches just the current directory. The search for the DLL
in the z/OS UNIX file system is case sensitive.
2. If the runtime environment does not find the DLL in the z/OS UNIX file
system, it tries to load the DLL from the MVS load library search order of the
caller. In this case, the DLL name must be eight characters or less. The run time
automatically converts the DLL name to uppercase for this search.
If the POSIX runtime option is set to OFF, the search order is reversed:
1. The runtime environment tries to load the DLL from the search order for the
load library of the caller.
2. If the runtime environment cannot load the DLL from this load library, it tries
to load the DLL from the z/OS UNIX file system.
Chapter 26. Creating a DLL or a DLL application 501
RELATED TASKS
Using CALL identifier with DLLs on page 500
RELATED REFERENCES
Language Environment Programming Reference (POSIX)
Using DLL linkage and dynamic calls together
For applications (that is, Language Environment enclaves) that are structured as
| multiple separately bound modules, each module can be invoked by using
| dynamic call linkage or DLL linkage. For a certain module, use exclusively one
| form of linkage to enter it. However, the caller can contain CALL statements with
| both linkage types, calling out to different modules.
| DLL linkage refers to a call in a program that is compiled with the DLL and NODYNAM
| options, or a call with the CALLINTERFACE compiler directive that specifies DLL. In
| such calls, the called subprogram is resolved to an exported name in a separate
| module. DLL linkage can also refer to an invocation of a method that is defined in
| a separate module.
| Within a compilation unit you can call a specific program with only one of the
| calling conventions: Dynamic, DLL or Static. If a program is called by using
| different calling conventions, the compiler diagnoses this case and force all the
| calls to have the same convention as the first call statement that is encountered for
| that program.
| A program can contain CALL statements with both dynamic call linkage and DLL
| linkage. It can do so by using the CALL INTERFACE compiler directive to specify
| the linkage type of a particular call. All components of a DLL application must
| have the same AMODE. The automatic AMODE switching normally provided by
| COBOL dynamic calls is not available for DLL linkages. You cannot cancel
| programs that are called by using DLL linkage.
All components of a DLL application must have the same AMODE. The automatic
AMODE switching normally provided by COBOL dynamic calls is not available
for DLL linkages.
You cannot cancel programs that are called using DLL linkage.
RELATED CONCEPTS
Dynamic link libraries (DLLs) on page 497
RELATED TASKS
Compiling programs to create DLLs on page 498
Linking DLLs on page 499
Using procedure or function pointers with DLLs on page 503
Calling DLLs from non-DLLs on page 503
RELATED REFERENCES
DLL on page 321
EXPORTALL on page 326
| CALLINTERFACE (Enterprise COBOL Language Reference)
502 Enterprise COBOL for z/OS, V5.2 Programming Guide
Using procedure or function pointers with DLLs
In run units that contain both DLLs and non-DLLs, use procedure- and
function-pointer data items with care.
| The SET procedure-pointer-1 TO ENTRY entry-name statement, SET function-pointer-1 TO
| ENTRY entry-name statement, and the CALL statement have a call linkage type that
| associates with them. The call linkage type is determined by the compiler options
| and the CALLINTERFACE directive that are in effect on that statement. In a program
| that is compiled with the DLL option, the default call linkage type is DLL.
| Otherwise, the linkage type is non-DLL. This default can be overridden by the
| CALLINTERFACE directive.
| For a procedure-pointer or function-pointer data item that is set by a SET statement
| with linkage type non-DLL, it must not be used by a CALL statement with linkage
| type DLL. For a SET statement with linkage type DLL and the entry-name is an
| identifier, and if the NODYNAM option is in effect, the entry-name identifier value must
| refer to the entry-point name that is exported from a DLL module. The DLL
| module name must match the name of the exported entry point. In this case, note
| also that:
v The program-name that is contained in the identifier is interpreted according to
the setting of the PGMNAME(COMPAT|LONGUPPER|LONGMIXED) compiler option of the
program that contains the CALL statement.
v The program-name that is exported from the target DLL is interpreted according
to the setting of the PGMNAME option used when compiling the target program.
v The search for the target DLL in the z/OS UNIX file system is case sensitive.
v If the target DLL is a PDS or PDSE member, the DLL member name must have
eight characters or less. For the purpose of the search for the DLL as a PDS or
PDSE member, the name is automatically converted to uppercase.
RELATED TASKS
Using CALL identifier with DLLs on page 500
Using procedure and function pointers on page 477
Compiling programs to create DLLs on page 498
Linking DLLs on page 499
RELATED REFERENCES
DLL on page 321
EXPORTALL on page 326
| CALLINTERFACE (Enterprise COBOL Language Reference)
Calling DLLs from non-DLLs
It is possible to call a DLL from a COBOL program that is compiled with the NODLL
option, but there are restrictions.
You can use the following methods to ensure that the DLL linkage is followed:
v Put the COBOL DLL programs that you want to call from the COBOL non-DLL
| programs in the program object that contains the main program. Use static calls
from the COBOL non-DLL programs to call the COBOL DLL programs.
| The COBOL DLL programs in the program object that contains the main
program can call COBOL DLL programs in other DLLs.
v Put the COBOL DLL programs in DLLs and call them from COBOL non-DLL
programs with CALL function-pointer, where function-pointer is set to a function
Chapter 26. Creating a DLL or a DLL application 503
descriptor of the target program. You can obtain the address of the function
descriptor for the program in the DLL by calling a C routine that uses dllload
and dllqueryfn.
Example: calling DLLs from non-DLLs
RELATED TASKS
Using procedure and function pointers on page 477
Example: calling DLLs from non-DLLs
The following example shows how a COBOL program that is not in a DLL
(COBOL1) can call a COBOL program that is in a DLL (program ooc05R in DLL
OOC05R).
CBL NODYNAM
IDENTIFICATION DIVISION.
PROGRAM-ID. COBOL1.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
DATA DIVISION.
FILE SECTION.
WORKING-STORAGE SECTION.
01 DLL-INFO.
03 DLL-LOADMOD-NAME PIC X(12).
03 DLL-PROGRAM-NAME PIC X(160).
03 DLL-PROGRAM-HANDLE FUNCTION-POINTER.
77 DLL-RC PIC S9(9) BINARY.
77 DLL-STATUS PIC X(1) VALUE N.
88 DLL-LOADED VALUE Y.
88 DLL-NOT-LOADED VALUE N.
PROCEDURE DIVISION.
IF DLL-NOT-LOADED
THEN
* Move the names in. They must be null terminated.
MOVE ZOOC05R TO DLL-LOADMOD-NAME
MOVE Zooc05r TO DLL-PROGRAM-NAME
* Call the C routine to load the DLL and to get the
* function descriptor address.
CALL A1CCDLGT USING BY REFERENCE DLL-INFO
BY REFERENCE DLL-RC
IF DLL-RC = 0
THEN
SET DLL-LOADED TO TRUE
ELSE
DISPLAY A1CCLDGT failed with rc =
DLL-RC
MOVE 16 TO RETURN-CODE
STOP RUN
END-IF
END-IF
* Use the function pointer on the call statement to call the
* program in the DLL.
* Call the program in the DLL.
CALL DLL-PROGRAM-HANDLE
GOBACK.
#include <stdio.h>
504 Enterprise COBOL for z/OS, V5.2 Programming Guide
#include <dll.h>
#pragma linkage (A1CCDLGT,COBOL)
typedef struct dll_lm {
char dll_loadmod_name[(12]);
char dll_func_name[(160]);
void (*fptr) (void); /* function pointer */
} dll_lm;
void A1CCDLGT (dll_lm *dll, int *rc)
{
dllhandle *handle;
void (*fptr1)(void);
*rc = 0;
/* Load the DLL */
handle = dllload(dll->dll_loadmod_name);
if (handle == NULL) {
perror("A1CCDLGT failed on call to load DLL./n");
*rc = 1;
return;
}
/* Get the address of the function */
fptr1 = (void (*)(void))
dllqueryfn(handle,dll->dll_func_name);
if (fptr1 == NULL) {
perror("A1CCDLGT failed on retrieving function./n");
*rc = 2;
return;
}
/* Return the function pointer */
dll->fptr = fptr1;
return;
}
Using COBOL DLLs with C/C++ programs
COBOL support for DLLs interoperates with the DLL support in the z/OS C/C++
products, except for COBOL EXTERNAL data. In particular, COBOL applications can
call functions that are exported from C/C++ DLLs, and C/C++ applications can
call COBOL programs that are exported from COBOL DLLs.
COBOL data items that are declared with the EXTERNAL attribute are independent of
DLL support. These data items are accessible by name from any COBOL program
in the run unit that declares them, regardless of whether the programs are in DLLs.
The COBOL options DLL, RENT, and EXPORTALL work much the same way as the
C/C++ DLL, RENT, and EXPORTALL options. (The DLL option applies only to C.)
However, the C/C++ compiler produces DLL-enabled code by default.
You can pass a C/C++ DLL function pointer to COBOL and use it within COBOL,
receiving the C/C++ function pointer as a function-pointer data item. The
following example shows 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.
Chapter 26. Creating a DLL or a DLL application 505
RELATED TASKS
Compiling programs to create DLLs on page 498
Linking DLLs on page 499
RELATED REFERENCES
DLL on page 321
EXPORTALL on page 326
RENT on page 348
EXTERNAL clause (Enterprise COBOL Language Reference)
| CALLINTERFACE (Enterprise COBOL Language Reference)
Using DLLs in OO COBOL applications
You must compile each COBOL class definition using the DLL, THREAD, RENT, and
DBCS compiler options, and link-edit it into a separate DLL module using the RENT
binder option.
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Compiling programs to create DLLs on page 498
Linking DLLs on page 499
RELATED REFERENCES
DLL on page 321
THREAD on page 362
RENT on page 348
DBCS on page 318
506 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 27. Preparing COBOL programs for multithreading
You can run COBOL programs in multiple threads within a process under batch,
TSO, IMS, or z/OS UNIX.
There is no explicit COBOL language to use for multithreaded execution; rather,
you compile with the THREAD compiler option.
COBOL does not directly support managing program threads. However, you can
run COBOL programs that you compile with the THREAD compiler option in
multithreaded application servers, in applications that use a C/C++ driver
program to create the threads, in programs that interoperate with Java and use
Java threads, and in applications that use PL/I tasking. In other words, other
programs can call COBOL programs in such a way that the COBOL programs run
in multiple threads within a process or as multiple program invocation instances
within a thread. Your threaded application must run within a single Language
Environment enclave.
Choosing LOCAL-STORAGE or WORKING-STORAGE: Because you must code your
multithreaded programs as recursive, the persistence of data is that of any
recursive program:
v Data items in the LOCAL-STORAGE SECTION are automatically allocated for each
instance of a program invocation. When a program runs in multiple threads
simultaneously, each invocation has a separate copy of LOCAL-STORAGE data.
v Data items in the WORKING-STORAGE SECTION are allocated once for each program
and are thus available in their last-used state to all invocations of the program.
For the data that you want to isolate to an individual program invocation instance,
define the data in the LOCAL-STORAGE SECTION. In general, this choice is appropriate
| for working data in threaded programs. If you define data in WORKING-STORAGE and
your program changes the contents of the data, you must take one of the following
actions:
v Structure your application so that you do not access data in WORKING-STORAGE
simultaneously from multiple threads.
v If you do access data simultaneously from separate threads, write appropriate
serialization code.
RELATED CONCEPTS
Multithreading on page 508
RELATED TASKS
Choosing THREAD to support multithreading on page 509
Transferring control to multithreaded programs on page 509
Ending multithreaded programs on page 510
Processing files with multithreading on page 510
Handling COBOL limitations with multithreading on page 512
RELATED REFERENCES
THREAD on page 362
PROGRAM-ID paragraph (Enterprise COBOL Language Reference)
Copyright IBM Corp. 1991, 2015 507
Multithreading
To use COBOL support for multithreading, you need to understand how processes,
threads, run units, and program invocation instances relate to each other.
The operating system and multithreaded applications can handle execution flow
within a process, which is the course of events when all or part of a program runs.
Programs that run within a process can share resources. Processes can be
manipulated. For example, they can have a high or low priority in terms of the
amount of time that the system devotes to running the process.
Within a process, an application can initiate one or more threads, each of which is a
stream of computer instructions that controls that thread. A multithreaded process
begins with one stream of instructions (one thread) and can later create other
instruction streams to perform tasks. These multiple threads can run concurrently.
Within a thread, control is transferred between executing programs.
In a multithreaded environment, a COBOL run unit is the portion of the process
that includes threads that have actively executing COBOL programs. The COBOL
run unit continues until no COBOL program is active in the execution stack for
any of the threads. For example, a called COBOL program contains a GOBACK
statement and returns control to a C program. Within the run unit, COBOL
programs can call non-COBOL programs, and vice versa.
Within a thread, control is transferred between separate COBOL and non-COBOL
programs. For example, a COBOL program can call another COBOL program or a
C program. Each separately called program is a program invocation instance.
Program invocation instances of a particular program can exist in multiple threads
within a given process.
The following illustration shows these relationships between processes, threads,
run units, and program invocation instances.
RELATED CONCEPTS
Language Environment Programming Guide (Program management model,
Understanding the basics: threads)
508 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Choosing THREAD to support multithreading
Transferring control to multithreaded programs
Ending multithreaded programs on page 510
Processing files with multithreading on page 510
Handling COBOL limitations with multithreading on page 512
RELATED REFERENCES
THREAD on page 362
Choosing THREAD to support multithreading
Use the THREAD compiler option for multithreading support. Use THREAD if your
program will be called in more than one thread in a single process by an
application. However, THREAD might adversely affect performance because of the
serialization logic that is automatically generated.
In order to run COBOL programs in more than one thread, you must compile all
of the COBOL programs in the application using the THREAD compiler option. You
must also compile them with the RENT compiler option and link them with the
| RENT option of the binder (linkage-editor).
Use the THREAD option when you compile object-oriented (OO) clients and classes.
Language restrictions: When you use the THREAD option, you cannot use certain
language elements. For details, see the related reference below.
Recursion: Before you compile a program using the THREAD compiler option, you
must specify the RECURSIVE phrase in the PROGRAM-ID paragraph. If you do not do
so, an error will occur.
RELATED TASKS
Sharing data in recursive or multithreaded programs on page 17
Compiling OO applications under z/OS UNIX on page 291
RELATED REFERENCES
THREAD on page 362
Transferring control to multithreaded programs
When you write COBOL programs for a multithreaded environment, choose
appropriate program linkage statements.
As in single-threaded environments, a called program is in its initial state when it
is first called within a run unit and when it is first called after a CANCEL to the
called program. Ensure that the program that you name on a CANCEL statement is
not active on any thread. If you try to cancel an active program, a severity-3
Language Environment condition occurs.
If your threaded application requires preinitialization, use the Language
Environment services (CEEPIPI interface). You cannot use the COBOL-specific
interfaces for preinitialization (runtime option RTEREUS) to establish a reusable
environment from any program that has been compiled with the THREAD option.
Chapter 27. Preparing COBOL programs for multithreading 509
RELATED CONCEPTS
Language Environment Programming Guide (What happens during termination:
enclave termination)
RELATED TASKS
Ending multithreaded programs
Ending and reentering main programs or subprograms on page 464
Ending multithreaded programs
You can end a multithreaded program by using GOBACK, EXIT PROGRAM, or STOP RUN.
Use GOBACK to return to the caller of the program. When you use GOBACK from the
first program in a thread, the thread is terminated. If that thread is the initial
thread in an enclave, the entire enclave is terminated.
Use EXIT PROGRAM as you would GOBACK, except from a main program where it has
no effect.
Use STOP RUN to terminate the entire Language Environment enclave and to return
control to the caller of the main program (which might be the operating system).
All threads that are executing within the enclave are terminated.
RELATED CONCEPTS
Language Environment Programming Guide (What happens during termination:
enclave termination)
RELATED TASKS
Ending and reentering main programs or subprograms on page 464
Processing files with multithreading
In threaded applications, you can code COBOL statements for input and output in
QSAM, VSAM, and line-sequential files.
Each file definition (FD) has an implicit serialization lock. This lock is used with
automatic serialization logic during the input or output operation that is associated
with the execution of the following statements:
v OPEN
v CLOSE
v READ
v WRITE
v REWRITE
v START
v DELETE
Automatic serialization also occurs for the implicit MOVE that is associated with the
following statements:
WRITE record-name FROM identifier
READ file-name INTO identifier
Automatic serialization is not applied to any statements specified within the
following conditional phrases:
v AT END
510 Enterprise COBOL for z/OS, V5.2 Programming Guide
v NOT AT END
v INVALID KEY
v NOT INVALID KEY
v AT END-OF-PAGE
v NOT AT END-OF-PAGE
RELATED CONCEPTS
File-definition (FD) storage
RELATED TASKS
Closing QSAM files on page 173
Closing VSAM files on page 200
Coding ERROR declaratives on page 244
Serializing file access with multithreading
File-definition (FD) storage
On all program invocations, the storage that is associated with a file definition
(such as FD records and the record area that is associated with the SAME RECORD
AREA clause) is allocated and available in its last-used state.
All threads of execution share this storage. You can depend on automatic
serialization for this storage during the execution of the OPEN, CLOSE, READ, WRITE,
REWRITE, START, and DELETE statements, but not between uses of these statements.
RELATED TASKS
Serializing file access with multithreading
Serializing file access with multithreading
To take full advantage of automatic serialization and to avoid explicitly writing
your own serialization logic, use one of the recommended file organizations and
usage patterns when you access files in threaded programs.
Use one of the following file organizations:
v Sequential organization
v Line-sequential organization
v Relative organization with sequential access
v Indexed organization with sequential access
Use the following pattern for input:
OPEN INPUT fn
. . .
READ fn INTO local-storage-item
. . .
* Process the record from the local-storage item
. . .
CLOSE fn
Use the following pattern for output:
OPEN OUTPUT fn
. . .
* Construct output record in local-storage item
. . .
WRITE rec FROM local-storage-item
. . .
CLOSE fn
Chapter 27. Preparing COBOL programs for multithreading 511
With other usage patterns, you must take one of the following actions:
v Verify the safety of your application logic. Ensure that two instances of the
program are never simultaneously active on different threads.
v Code explicit serialization logic by using calls to POSIX services.
To avoid serialization problems when you access a file from multiple threads,
define the data items that are associated with the file (such as file-status data items
and key arguments) in the LOCAL-STORAGE SECTION.
Example: usage patterns of file input and output with multithreading
RELATED TASKS
Calling UNIX/POSIX APIs on page 456
Example: usage patterns of file input and output with
multithreading
The following examples show the need for explicit serialization logic when you
deviate from the recommended usage pattern for file input and output in your
multithreaded applications. These examples also explain the unexpected behavior
that might result if you fail to handle serialization properly.
In each example, two instances of a program that contains the sample operations
are running within one run unit on two different threads.
READ F1
. . .
REWRITE R1
In the example above, the second thread might execute the READ statement after the
READ statement is executed on the first thread but before the REWRITE statement is
executed on the first thread. The REWRITE statement might not update the record
that you intended. To ensure the results that you want, write explicit serialization
logic.
READ F1
. . .
* Process the data in the FD record description entry for F1
. . .
In the example above, the second thread might execute the READ statement while
the first thread is still processing a record in the FD record description entry. The
second READ statement would overlay the record that the first thread is processing.
To avoid this problem, use the recommended technique:
READ F1 INTO LOCAL-STORAGE-item
Other cases: You must give similar consideration to other usage patterns that
involve a sequence of related input and output operations, such as START followed
by READ NEXT, or READ followed by DELETE. Take appropriate steps to ensure the
correct processing of file input and output.
Handling COBOL limitations with multithreading
Some COBOL applications depend on subsystems or other applications. In a
multithreaded environment, these dependencies and others result in some
limitations on COBOL programs.
512 Enterprise COBOL for z/OS, V5.2 Programming Guide
In general, you must synchronize access to resources that are visible to the
application within a run unit. Exceptions to this requirement are DISPLAY and
ACCEPT, which you can use from multiple threads, and supported COBOL file I/O
statements that have the recommended usage pattern; all synchronization is
provided for these by the runtime environment.
CICS: You cannot run multithreaded applications in CICS. In CICS, you can run a
COBOL program that has been compiled with the THREAD option and that is part of
an application that has no multiple threads or PL/I tasks.
Recursive: Because you must code the programs in a multithreaded application as
recursive, you must adhere to all the restrictions and programming considerations
that apply to recursive programs, such as not coding nested programs.
Reentrancy: You must compile your multithreading programs with the RENT
| compiler option and link them with the RENT option of the binder (linkage-editor).
POSIX and PL/I: If you use POSIX threads in your multithreaded application, you
must specify the Language Environment runtime option POSIX(ON). If the
application uses PL/I tasking, you must specify POSIX(OFF). You cannot mix
POSIX threads and PL/I tasks in the same application.
PL/I tasking: To include COBOL programs in applications that contain multiple
PL/I tasks, follow these guidelines:
v Compile all COBOL programs that you run in multiple PL/I tasks with the
THREAD option. If you compile any COBOL program with the NOTHREAD option, all
of the COBOL programs must run in one PL/I task.
v You can call COBOL programs compiled with the THREAD option from one or
more PL/I tasks. However, calls from PL/I programs to COBOL programs
cannot include the TASK or EVENT option. The PL/I tasking call must first call a
PL/I program or function that in turn calls the COBOL program. This
indirection is required because you cannot specify the COBOL program directly
as the target of a PL/I CALL statement that includes the TASK or EVENT option.
v Be aware that issuing a STOP RUN statement from a COBOL program or a STOP
statement from a PL/I program terminates the entire Language Environment
enclave, including all the tasks of execution.
v Do not code explicit POSIX threading (calls to pthread_create()) in any run unit
that includes PL/I tasking.
C and Language Environment conforming assembler: You can combine your
multithreaded COBOL programs with C programs and Language Environment
conforming assembler programs in the same run unit when those programs are
also appropriately coded for multithreaded execution.
AMODE: You must run your multithreaded applications with AMODE 31. You can
run a COBOL program that has been compiled with the THREAD option with AMODE
24 as part of an application that does not have multiple threads or PL/I tasks.
Asynchronous signals: In a threaded application your COBOL program might be
interrupted by an asynchronous signal or interrupt. If your program contains logic
that cannot tolerate such an interrupt, you must disable the interrupts for the
duration of that logic. Call a C/C++ function to set the signal mask appropriately.
Chapter 27. Preparing COBOL programs for multithreading 513
Older COBOL programs: To run your COBOL programs on multiple threads of a
multithreaded application, you must compile them with Enterprise COBOL and
use the THREAD option. Run applications that contain programs compiled by older
compilers only on one thread.
IGZETUN and IGZEOPT: Do not use the modules IGZETUN (for storage tuning)
or IGZEOPT (for runtime options) for applications in which the main program has
been compiled with the THREAD option; these CSECTs are ignored.
UPSI switches: All programs and all threads in an application share a single copy
of UPSI switches. If you modify switches in a threaded application, you must code
appropriate serialization logic.
RELATED TASKS
Making recursive calls on page 477
Serializing file access with multithreading on page 511
XL C/C++ Programming Guide (Using threads in z/OS UNIX System Services
applications)
Language Environment Writing ILC Communication Applications
514 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 5. Using XML and COBOL together
Copyright IBM Corp. 1991, 2015 515
516 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 28. Processing XML input
You can process XML input in a COBOL program by using the XML PARSE
statement.
| The XML PARSE statement is the COBOL language interface to either of two
| high-speed XML parsers. You use the XMLPARSE compiler option to select the
| appropriate parser for your application:
| v XMLPARSE(XMLSS) selects the z/OS XML System Services parser.
| This option provides enhanced features such as namespace processing,
| validation of XML documents with respect to an XML schema, and conversion
| of text fragments to national character representation (Unicode UTF-16).
| v XMLPARSE(COMPAT) selects the XML parser that is built into the COBOL library.
| This option provides compatibility with XML parsing in Enterprise COBOL
| Version 3 and Version 4.
Processing XML input involves passing control between the XML parser and a
processing procedure in which you handle parser events.
Use the following COBOL facilities to process XML input:
v The XML PARSE statement to begin XML parsing and to identify the source XML
document and the processing procedure.
You can also use the following optional phrases of the XML PARSE statement:
ENCODING to specify the encoding of the XML document
VALIDATING to identify an XML schema against which the XML document is to
be validated
v The processing procedure to control the parsing, that is, receive and process
XML events and associated document fragments, and return to the parser for
continued processing
v Special registers to exchange information between the parser and the processing
procedure:
XML-CODE to receive the status of XML parsing and, in some cases, to return
information to the parser
XML-EVENT to receive the name of each XML event from the parser
XML-INFORMATION provides a mechanism to easily determine whether an XML
event is complete
XML-NTEXT to receive XML document fragments that are returned as national
character data
XML-TEXT to receive document fragments that are returned as alphanumeric
data
XML-NAMESPACE or XML-NNAMESPACE to receive a namespace identifier for a
NAMESPACE-DECLARATION XML event, or for an element name or attribute name
that is in a namespace
XML-NAMESPACE-PREFIX or XML-NNAMESPACE-PREFIX to receive a namespace
prefix for a NAMESPACE-DECLARATION XML event, or for an element name or
attribute name that is prefixed
v The optional RETURNING NATIONAL phrase of the XML PARSE statement to indicate
that the fragments of an XML document in an alphanumeric data item are to be
Copyright IBM Corp. 1991, 2015 517
converted to UTF-16 and returned to the processing procedure in the national
special registers XML-NTEXT, XML-NNAMESPACE, and XML-NNAMESPACE-PREFIX
You can use the ENCODING, VALIDATING, and RETURNING NATIONAL phrases of the XML
| PARSE statement only if XMLPARSE(XMLSS) is in effect.
Link-edit consideration: COBOL programs that contain the XML PARSE statement
must be link-edited with AMODE 31.
RELATED CONCEPTS
XML parser in COBOL
RELATED TASKS
Accessing XML documents on page 520
Parsing XML documents on page 520
Handling XML PARSE exceptions on page 542
Terminating XML parsing on page 546
RELATED REFERENCES
XMLPARSE on page 368 (compiler option)
The encoding of XML documents on page 536
Appendix C, XML reference material, on page 691
Extensible Markup Language (XML)
XML parser in COBOL
Enterprise COBOL provides an event-based interface that lets you parse XML
documents and transform them to COBOL data structures.
The XML parser finds fragments within the source XML document, and your
processing procedure acts on those fragments. The fragments are associated with
XML events; you code the processing procedure to handle each XML event.
Execution of the XML PARSE statement begins the parsing and establishes the
processing procedure with the parser. The parser transfers control to the processing
procedure for each XML event that it detects while processing the document. After
processing the event, the processing procedure automatically returns control to the
parser. Each normal return from the processing procedure causes the parser to
continue analyzing the XML document to report the next event. Throughout this
operation, control passes back and forth between the parser and the processing
procedure.
In the XML PARSE statement, you can also specify two imperative statements to
which you want control to be passed at the end of the parsing: one if a normal end
occurs, and the other if an exception condition exists.
The following figure shows a high-level overview of the basic exchange of control
between the parser and your COBOL program:
518 Enterprise COBOL for z/OS, V5.2 Programming Guide
Normally, parsing continues until the entire XML document has been parsed.
The XML parser checks XML documents for most aspects of well formedness. A
document is well formed if it adheres to the XML syntax in the XML specification
and follows some additional rules such as proper use of end tags and uniqueness
of attribute names.
When you parse an XML document with validation against an XML schema, the
z/OS XML System Services parser additionally verifies that the XML document
adheres to the content and structure prescribed in the schema. For example, the
parser checks that there are no unexpected elements or attributes, that no required
elements or attributes are missing, and that any values of elements or attributes are
legal.
RELATED CONCEPTS
XML schemas on page 532
XML input document encoding on page 537
RELATED TASKS
Parsing XML documents on page 520
Parsing XML documents with validation on page 530
Handling XML PARSE exceptions on page 542
Terminating XML parsing on page 546
RELATED REFERENCES
The encoding of XML documents on page 536
XML specification
Chapter 28. Processing XML input 519
Accessing XML documents
Before you can parse an XML document using an XML PARSE statement, you must
make the document available to your program. Common methods of acquiring an
XML document are by retrieval from a WebSphere MQ message, a CICS transient
queue or communication area, or an IMS message processing queue; or by reading
the document from a file.
If the XML document that you want to parse is held in a file, use ordinary COBOL
facilities to place the document into a data item in your program:
v A FILE-CONTROL entry to define the file to your program.
v An OPEN statement to open the file.
v READ statements to read all the records from the file into a data item (either an
elementary item of category alphanumeric or national, or an alphanumeric or
national group). You can define the data item in the WORKING-STORAGE SECTION or
the LOCAL-STORAGE SECTION.
v Optionally, the STRING statement to string all of the separate records together
into one continuous stream, to remove extraneous blanks, and to handle
variable-length records.
| If the XMLPARSE(XMLSS) option is in effect, you can parse an XML document that is
| in a file by passing the parser one record (or segment) of text from the file at a
| time. This capability is useful for parsing very large XML documents.
RELATED TASKS
Coding COBOL programs to run under CICS on page 419
Chapter 22, Developing COBOL programs for IMS, on page 443
Parsing XML documents one segment at a time on page 533
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
Parsing XML documents
To parse XML documents, use the XML PARSE statement, specifying the XML
document that is to be parsed and the processing procedure for handling XML
events that occur during parsing, as shown in the following code fragment.
XML PARSE xml-document
PROCESSING PROCEDURE xml-event-handler
ON EXCEPTION
DISPLAY XML document error XML-CODE
STOP RUN
NOT ON EXCEPTION
DISPLAY XML document was successfully parsed.
END-XML
In the XML PARSE statement, you first identify the parse data item (xml-document in
the example above) that contains the XML document character stream. In the DATA
DIVISION, define the parse data item as an elementary data item of category
national or as a national group item if the encoding of the document is Unicode
UTF-16; otherwise, define the parse data item as an elementary alphanumeric data
item or an alphanumeric group item:
v If the parse data item is national, the XML document must be encoded in
UTF-16, CCSID 1200.
520 Enterprise COBOL for z/OS, V5.2 Programming Guide
v If the parse data item is alphanumeric, its content must be encoded in one of the
supported code pages described in the related reference about the encoding of
XML documents.
Next, specify the name of the processing procedure (xml-event-handler in the
example above) that is to handle the XML events that occur during parsing of the
document.
| If the XMLPARSE(XMLSS) compiler option is in effect, you can also use any of these
| optional phrases of the XML PARSE statement:
| v ENCODING, to specify the CCSID of the document
| v RETURNING NATIONAL, to cause the parser to automatically convert UTF-8 or
| single-byte characters to national characters for return to the processing
| procedure
| v VALIDATING, to cause the parser to validate the document against an XML
| schema
In addition, you can specify either or both of the following optional phrases (as
shown in the fragment above) to indicate the action to be taken after parsing
finishes:
v ON EXCEPTION, to receive control if an unhandled exception occurs during
parsing
v NOT ON EXCEPTION, to receive control otherwise
You can end the XML PARSE statement with the explicit scope terminator END-XML.
Use END-XML to nest an XML PARSE statement that uses the ON EXCEPTION or NOT ON
EXCEPTION phrase in a conditional statement.
The parser passes control to the processing procedure for each XML event. Control
returns to the parser at the end of the processing procedure. This exchange of
control between the XML parser and the processing procedure continues until one
of the following events occurs:
v The entire XML document was parsed, as indicated by the END-OF-DOCUMENT
event.
| v If XMLPARSE(XMLSS) is in effect, either:
| The parser detects an error in the document and signals an EXCEPTION event
| (regardless of the kind of exception).
| The parser signals an END-OF-INPUT event, and the processing procedure
| returns to the parser with special register XML-CODE still set to zero, which
| indicates that no further XML data will be provided to the parser.
| v If XMLPARSE(COMPAT) is in effect, either:
| The parser signals an encoding conflict EXCEPTION event, and the processing
| procedure does not reset special register XML-CODE to zero or to the correct
| CCSID before returning to the parser.
| The parser detects an error in the document and signals an EXCEPTION event
| (other than an encoding conflict), and the processing procedure does not reset
| special register XML-CODE to zero before returning to the parser.
v The parsing process is terminated deliberately by the user's code in the
processing procedure that sets the XML-CODE special register to -1 before it
returns to the parser.
RELATED CONCEPTS
XML events on page 524
Chapter 28. Processing XML input 521
XML-CODE on page 525
XML schemas on page 532
XML-INFORMATION on page 526
RELATED TASKS
Writing procedures to process XML
Parsing XML documents with validation on page 530
Parsing XML documents one segment at a time on page 533
Parsing XML documents encoded in UTF-8 on page 541
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
The encoding of XML documents on page 536
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect on page 693
XML PARSE statement (Enterprise COBOL Language Reference)
Writing procedures to process XML
In your processing procedure, code statements to handle XML events.
For each event that the parser encounters, the parser passes information to the
processing procedure in several special registers. Use the content of those special
registers to populate COBOL data structures and to control the processing.
Examine the XML-EVENT special register to determine which event the parser passed
to the processing procedure. XML-EVENT contains an event name, such as
'START-OF-ELEMENT'. Obtain the text associated with the event from the XML-TEXT or
XML-NTEXT special register.
| If the XMLPARSE(XMLSS) option is in effect, you can use special register
| XML-NAMESPACE or XML-NNAMESPACE to determine the namespace identifier, if any,
| that is associated with the XML event, and examine the XML-NAMESPACE-PREFIX or
| XML-NNAMESPACE-PREFIX special register to determine the associated prefix, if any.
When used in nested programs, the XML special registers are implicitly defined as
GLOBAL in the outermost program.
For additional details about the XML special registers, see the following table.
Table 64. Special registers used by the XML parser
Special register Implicit definition and usage Content
XML-EVENT1 PICTURE X(30) USAGE DISPLAY VALUE SPACE The name of the XML event
2
XML-CODE PICTURE S9(9) USAGE BINARY VALUE ZERO An exception code or zero for each XML event
XML-INFORMATION1 PICTURE S9(9) USAGE BINARY VALUE 0 A mechanism to easily determine whether an XML
EVENT is complete
XML-TEXT1 Variable-length elementary category Text (corresponding to the event that the parser
alphanumeric item encountered) from the XML document if you specify
an alphanumeric item for the XML PARSE identifier3
XML-NTEXT1 Variable-length elementary category national Text (corresponding to the event that the parser
item encountered) from the XML document if you specify a
national item for the XML PARSE identifier3
XML-NAMESPACE1, 4 Variable-length elementary category The namespace identifier for a NAMESPACE-DECLARATION
alphanumeric item XML event or for an element or attribute name that is
in a namespace, if the XML document is in an
alphanumeric data item3
522 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 64. Special registers used by the XML parser (continued)
Special register Implicit definition and usage Content
XML-NNAMESPACE1, 4 Variable-length elementary category national The namespace identifier for a NAMESPACE-DECLARATION
item XML event or for an element or attribute name that is
in a namespace, if the XML document is in a national
data item or the RETURNING NATIONAL phrase is
specified in the XML PARSE statement
XML-NAMESPACE-PREFIX1, 4 Variable-length elementary category national The prefix, if any, for a NAMESPACE-DECLARATION XML
item event or for an element or attribute name that is in a
nondefault namespace, if the XML document is in an
alphanumeric data item3
XML-NNAMESPACE-PREFIX1, 4 Variable-length elementary category national The prefix, if any, for a NAMESPACE-DECLARATION XML
item event or for an element or attribute name that is in a
nondefault namespace, if the XML document is in a
national data item or the RETURNING NATIONAL phrase is
specified in the XML PARSE statement
1. You cannot use this special register as a receiving data item.
2. The XML GENERATE statement also uses XML-CODE. Therefore, if you have an XML GENERATE statement in the processing procedure,
save the value of XML-CODE before the XML GENERATE statement, and restore the saved value after the XML GENERATE statement.
| 3. If you specify the RETURNING NATIONAL phrase in the XML PARSE statement for an alphanumeric data item, text is returned in the
| corresponding national special register. You can specify the RETURNING NATIONAL phrase only if the XMLPARSE(XMLSS) option is in
| effect.
| 4. The parser sets the namespace special registers only if the XMLPARSE(XMLSS) option is in effect.
Restrictions:
v A processing procedure must not directly execute an XML PARSE statement.
However, if a processing procedure passes control to a method or outermost
program by using an INVOKE or CALL statement, the target method or program
can execute the same or a different XML PARSE statement. You can also execute
the same XML statement or different XML statements simultaneously from a
program that is running on multiple threads.
v 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.
You can code a STOP RUN statement in a processing procedure to end the run
unit.
The compiler inserts a return mechanism after the last statement in each processing
procedure.
Example: program for processing XML on page 548
RELATED CONCEPTS
XML events on page 524
XML-CODE on page 525
XML-TEXT and XML-NTEXT on page 527
XML-NAMESPACE and XML-NNAMESPACE on page 527
XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX on page 528
RELATED TASKS
Parsing XML documents one segment at a time on page 533
Parsing XML documents with validation on page 530
Terminating XML parsing on page 546
Chapter 28. Processing XML input 523
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
XML-EVENT (Enterprise COBOL Language Reference)
XML events
An XML event results when the XML parser detects various conditions (such as
END-OF-INPUT or EXCEPTION) or encounters document fragments (such as
CONTENT-CHARACTERS or START-OF-CDATA-SECTION) while processing an XML
document.
For each event that occurs during XML parsing, the parser sets the associated
event name in the XML-EVENT special register, and passes the XML-EVENT special
register to the processing procedure. Depending on the event, the parser sets other
special registers to contain additional information about the event.
In most cases, the parser sets the XML-TEXT or XML-NTEXT special register to the XML
fragment that caused the event:
| v If the XMLPARSE(COMPAT) compiler option is in effect, the parser sets XML-NTEXT if
| the XML document is in a national data item, or if the parser finds a character
| reference; otherwise, the parser sets XML-TEXT.
| v If XMLPARSE(XMLSS) is in effect, the parser sets XML-NTEXT if the RETURNING
| NATIONAL phrase is specified in the XML PARSE statement, or if the XML document
| is in a national data item; otherwise, the parser sets XML-TEXT.
| If XMLPARSE(XMLSS) is in effect, the parser sets the namespace special registers for a
| NAMESPACE-DECLARATION event, or if it encounters a name that is in a namespace.
When the parser detects an encoding conflict or a well-formedness or validation
error in the document, it sets XML-EVENT to EXCEPTION and provides additional
| information about the exception in the XML-CODE special register. You can parse
| with validation only if XMLPARSE(XMLSS) is in effect. For further details, see the
| related task about parsing with validation.
For a detailed description of the set of XML events, see the related reference about
XML-EVENT.
Example: parsing a simple document on page 547
RELATED CONCEPTS
XML parser in COBOL on page 518
XML-CODE on page 525
XML-INFORMATION on page 526
XML-TEXT and XML-NTEXT on page 527
XML-NAMESPACE and XML-NNAMESPACE on page 527
XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX on page 528
RELATED TASKS
Writing procedures to process XML on page 522
Parsing XML documents with validation on page 530
RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect on page 693
XML-EVENT (Enterprise COBOL Language Reference)
524 Enterprise COBOL for z/OS, V5.2 Programming Guide
XML-CODE
For each XML event except an EXCEPTION event, the parser sets the value of the
XML-CODE special register to zero. For an EXCEPTION event, the parser sets XML-CODE
to a value that identifies the specific exception.
For information about the possible exception codes, see the related references.
When the parser returns control to the XML PARSE statement from your processing
procedure, XML-CODE generally contains the most recent value that was set by the
parser. However, for any event other than EXCEPTION, if you set XML-CODE to -1 in
your processing procedure, parsing terminates with a user-initiated exception
condition when control returns to the parser, and XML-CODE retains the value -1.
| For an EXCEPTION XML event when XMLPARSE(COMPAT) is in effect, your processing
| procedure can, in some cases, set XML-CODE to a meaningful value before control
| returns to the parser. (For details, see the related tasks about handling XML PARSE
| exceptions and handling encoding conflicts.) If you set XML-CODE to any other
| nonzero value or set it for any other exception, the parser resets XML-CODE to the
| original exception code.
| For a START-OF-DOCUMENT XML event when compiler option XMLPARSE(COMPAT) is in
| effect, your processing procedure can set XML-CODE to 1 before control returns to the
| parser. This action instructs the parser to release (at the end of parsing) any
| Language Environment resources acquired during parsing.
The following table shows the results of setting XML-CODE to various values. The
leftmost column shows the type of XML event passed to the processing procedure;
the other column headings show the XML-CODE value set by the processing
procedure. The cell at the intersection of each row and column shows the action
that the parser takes upon return from the processing procedure for a given
combination of XML event and XML-CODE value.
| Table 65. Results of processing-procedure changes to XML-CODE with XMLPARSE(XMLSS) in effect
| XML-CODE set to
| XML event type XML-CODE set to -1 XML-CODE set to 0 XML-CODE set to 1 other nonzero values
| Fatal EXCEPTION Ignores setting; keeps Ignores setting; keeps Ignores setting; keeps Ignores setting; keeps
| original XML-CODE original XML-CODE original XML-CODE original XML-CODE
| value value value value
| Warning EXCEPTION Ignores setting; keeps Next event is Ignores setting; keeps Ignores setting; keeps
| (Reason code 800 or original XML-CODE ATTRIBUTE-NAME or original XML-CODE original XML-CODE
| 801) value START-OF-ELEMENT value value
| END-OF-INPUT Ends immediately; Next event is Next event depends Fatal runtime error
| XML-CODE = -11 END-OF-DOCUMENT2 on input2 (message 230S)
| Normal event Ends immediately; XML-CODE already 0, Fatal runtime error Fatal runtime error
| XML-CODE = -11 no change (message 230S) (message 230S)
| 1. See the related task about terminating XML parsing.
| 2. See the related task about parsing documents one segment at a time.
|
Chapter 28. Processing XML input 525
| Table 66. Results of processing-procedure changes to XML-CODE with XMLPARSE(COMPAT) in effect
| XML event type -1 0 XML-CODE-100,000 Other nonzero value
| Encoding-conflict Ignores setting; keeps Chooses encoding Ignores setting; keeps Ignores setting; keeps
| exception (exception original XML-CODE depending on the original XML-CODE original XML-CODE
| codes 50 - 99) value specific exception value value
| code1
| Encoding-choice Ignores setting; keeps Parses using the Parses using the Ignores setting; keeps
| exception (exception original XML-CODE CODEPAGE value2 difference (shown original XML-CODE
| codes > 100,000) value above) as the value
| encoding value2
| Other exception Ignores setting; keeps Limited continuation Ignores setting; keeps Ignores setting; keeps
| original XML-CODE only for exception original XML-CODE original XML-CODE
| value codes 1 - 493 value value
| Normal event (except Ends immediately; [No apparent change Ends immediately; Ends immediately;
| START-OF-DOCUMENT) XML-CODE = -14 to XML-CODE] XML-CODE = -1 XML-CODE = -1
|| START-OF-DOCUMENT Ends immediately; [No apparent change Ends immediately; v XML-CODE = 1
| XML-CODE = -14 to XML-CODE] XML-CODE = -1
| v Else ends
| immediately;
| XML-CODE = -1
| 1. See the exception codes in the related reference about XML PARSE exceptions with XMLPARSE(COMPAT) in effect.
| 2. See the related task about handling encoding conflicts.
| 3. See the related task about handling XML PARSE exceptions.
| 4. See the related task about terminating XML parsing.
|
XML generation also uses the XML-CODE special register. For details, see the related
task about handling XML GENERATE exceptions.
RELATED CONCEPTS
How the XML parser handles errors on page 544
RELATED TASKS
Writing procedures to process XML on page 522
Parsing XML documents one segment at a time on page 533
Handling XML PARSE exceptions on page 542
Terminating XML parsing on page 546
Handling XML GENERATE exceptions on page 567
RELATED REFERENCES
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect on page 693
XML GENERATE exceptions on page 700
XML-CODE (Enterprise COBOL Language Reference)
XML-EVENT (Enterprise COBOL Language Reference)
XML-INFORMATION
For most XML events, the parser sets XML-INFORMATION to indicate whether an XML
EVENT is complete or whether the XML content spans multiple events.
The application program logic can use the XML-INFORMATION special register to
concatenate pieces of parsed XML content together.
526 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED CONCEPTS
XML events on page 524
XML-CODE on page 525
RELATED TASKS
Writing procedures to process XML on page 522
RELATED REFERENCES
XML-TEXT (Enterprise COBOL Language Reference)
XML-NTEXT (Enterprise COBOL Language Reference)
XML-TEXT and XML-NTEXT
For most XML events, the parser sets XML-TEXT or XML-NTEXT to an associated
document fragment.
Typically, the parser sets XML-TEXT if the XML document is in an alphanumeric data
item. The parser sets XML-NTEXT if:
v The XML document is in a national data item.
| v The XMLPARSE(XMLSS) option is in effect and the RETURNING NATIONAL phrase is
| specified in the XML PARSE statement.
v The ATTRIBUTE-NATIONAL-CHARACTER or CONTENT-NATIONAL-CHARACTER event
occurs.
The special registers XML-TEXT and XML-NTEXT are mutually exclusive. When the
parser sets XML-TEXT, XML-NTEXT is empty with length zero. When the parser sets
XML-NTEXT, XML-TEXT is empty with length zero.
To determine the number of character encoding units in XML-NTEXT, use the LENGTH
intrinsic function; for example FUNCTION LENGTH(XML-NTEXT). To determine the
number of bytes in XML-NTEXT, use special register LENGTH OF XML-NTEXT. The
number of character encoding units differs from the number of bytes.
To determine the number of bytes in XML-TEXT, use either special register LENGTH OF
XML-TEXT or the LENGTH intrinsic function; each returns the number of bytes.
The XML-TEXT and XML-NTEXT special registers are undefined outside the processing
procedure.
RELATED CONCEPTS
XML events on page 524
XML-CODE on page 525
RELATED TASKS
Writing procedures to process XML on page 522
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
XML-TEXT (Enterprise COBOL Language Reference)
XML-NTEXT (Enterprise COBOL Language Reference)
XML-NAMESPACE and XML-NNAMESPACE
| If the XMLPARSE(XMLSS) option is in effect, the XML parser sets the XML-NAMESPACE
| or XML-NNAMESPACE special register to the namespace identifier for a
| NAMESPACE-DECLARATION XML event, or if it encounters an element name or
| attribute name that is in a namespace.
Chapter 28. Processing XML input 527
The parser sets XML-NNAMESPACE if the XML document is in a national data item, or
if the RETURNING NATIONAL phrase is specified in the XML PARSE statement.
Otherwise, the parser sets XML-NAMESPACE.
The special registers XML-NAMESPACE and XML-NNAMESPACE are mutually exclusive: If
the parser sets XML-NAMESPACE, XML-NNAMESPACE is empty with length zero. If the
parser sets XML-NNAMESPACE, XML-NAMESPACE is empty with length zero.
To determine the number of character encoding units in XML-NNAMESPACE, use the
LENGTH intrinsic function; for example: FUNCTION LENGTH(XML-NNAMESPACE). To
determine the number of bytes in XML-NNAMESPACE, use special register LENGTH OF
XML-NNAMESPACE. The number of character encoding units differs from the number
of bytes.
To determine the number of bytes in XML-NAMESPACE, use either special register
LENGTH OF XML-NAMESPACE or the LENGTH intrinsic function; each returns the number
of bytes.
The XML namespace special registers are undefined outside the processing
procedure.
RELATED CONCEPTS
XML events on page 524
XML-CODE on page 525
XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX
XML-TEXT and XML-NTEXT on page 527
RELATED TASKS
Writing procedures to process XML on page 522
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX
If the XMLPARSE(XMLSS) option is in effect, the XML parser sets the
XML-NAMESPACE-PREFIX special register or the XML-NNAMESPACE-PREFIX special
register for a NAMESPACE-DECLARATION XML event that also defines a namespace
prefix, or if an element name or attribute name in a namespace is prefixed.
The parser sets XML-NNAMESPACE-PREFIX if the XML document is in a national data
item, or the RETURNING NATIONAL phrase is specified in the XML PARSE statement.
Otherwise, the parser sets XML-NAMESPACE-PREFIX.
The special registers XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX are
mutually exclusive: If the parser sets XML-NAMESPACE-PREFIX, XML-NNAMESPACE-
PREFIX is empty with length zero. If the parser sets XML-NNAMESPACE-PREFIX,
XML-NAMESPACE-PREFIX is empty with length zero.
To determine the number of character encoding units in XML-NNAMESPACE-PREFIX,
use the LENGTH intrinsic function; for example: FUNCTION LENGTH(XML-NNAMESPACE-
PREFIX). To determine the number of bytes in XML-NNAMESPACE-PREFIX, use special
register LENGTH OF XML-NNAMESPACE-PREFIX. The number of character encoding
units differs from the number of bytes.
528 Enterprise COBOL for z/OS, V5.2 Programming Guide
To determine the number of bytes in XML-NAMESPACE-PREFIX, use either special
register LENGTH OF XML-NAMESPACE-PREFIX or the LENGTH intrinsic function; each
returns the number of bytes.
The XML namespace-prefix special registers are undefined outside the processing
procedure.
RELATED CONCEPTS
XML events on page 524
XML-NAMESPACE and XML-NNAMESPACE on page 527
RELATED TASKS
Writing procedures to process XML on page 522
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| Transforming XML text to COBOL data items
Because XML data is neither fixed length nor fixed format, you need to use special
techniques when you move XML data to a COBOL data item.
For alphanumeric items, decide whether the XML data should go at the left
(default) end, or at the right end, of the COBOL data item. If the data should go at
| the right end, specify the JUSTIFIED RIGHT clause in the definition of the item.
Give special consideration to numeric XML values, particularly decorated
monetary values such as '$1,234.00' or '$1234'. These two strings might mean the
| same thing in XML, but need quite different definitions if used as COBOL sending
fields.
Use one of the following techniques when you move XML data to COBOL data
items:
v If the format is reasonably regular, code a MOVE to an alphanumeric item that you
redefine appropriately as a numeric-edited item. Then do the final move to a
numeric (operational) item by moving from, and thus de-editing, the
numeric-edited item. (A regular format would have the same number of digits
after the decimal point, a comma separator for values greater than 999, and so
on.)
v For simplicity and vastly increased flexibility, use the following intrinsic
functions for alphanumeric XML data:
NUMVAL to extract and decode simple numeric values from XML data that
represents plain numbers
NUMVAL-C to extract and decode numeric values from XML data that represents
monetary quantities
However, using these functions is at the expense of performance.
RELATED TASKS
Converting to numbers (NUMVAL, NUMVAL-C) on page 117
Using national data (Unicode) in COBOL on page 130
Writing procedures to process XML on page 522
Chapter 28. Processing XML input 529
Parsing XML documents with validation
Validating an XML document determines whether the structure and content of the
document conform to a set of rules. In Enterprise COBOL, the rules are expressed
in an XML schema, which is essentially a blueprint for a class of documents.
To validate XML documents while parsing, use the VALIDATING phrase of the XML
| PARSE statement. To do so, you must compile your program using the
| XMLPARSE(XMLSS) compiler option.
You can validate XML documents only against an XML schema.
In Enterprise COBOL, a schema used for XML validation must be in a
preprocessed format known as Optimized Schema Representation, or OSR. To
generate a schema in OSR format from a text-form schema, use the z/OS UNIX
command xsdosrg, which invokes the OSR generator provided by z/OS System
Services. (Alternatively, you can call the OSR generator programmatically. For
details, see the related reference about z/OS XML System Services.)
For example, to convert the text-form schema in file item.xsd to a schema in
preprocessed format in file item.osr, you can use the following z/OS UNIX
command:
xsdosrg -v -o /u/HLQ/xml/item.osr /u/HLQ/xml/item.xsd
Use one of two forms of the VALIDATING phrase, depending on the location of the
preprocessed schema:
v In one form, you use the FILE keyword and specify an XML schema name. In
this case, the schema must be in an MVS data set or a z/OS UNIX file.
v In the other form, you specify the identifier of a data item that contains the
schema.
If you use the FILE keyword and specify an XML schema name, the COBOL
runtime library automatically retrieves the schema during execution of the XML
PARSE statement. The following code fragment shows this method of specifying
validation:
XML PARSE document-item
VALIDATING WITH FILE schema-name
PROCESSING PROCEDURE xml-event-handler
ON EXCEPTION
DISPLAY Document has an error.
GOBACK
NOT ON EXCEPTION
DISPLAY Document is valid.
END-XML
To associate an XML schema name with the external file that contains the schema,
code the XML-SCHEMA clause in the SPECIAL-NAMES paragraph, specifying either a
literal or a user-defined word to identify the file.
For example, you can associate the XML schema name schema-name shown in the
fragment above with the ddname DDSCHEMA by coding the ddname as a literal in
the XML-SCHEMA clause as follows:
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
XML-SCHEMA schema-name IS DDSCHEMA.
530 Enterprise COBOL for z/OS, V5.2 Programming Guide
For running the program, you can associate ddname DDSCHEMA with the z/OS
UNIX file item.osr by coding a DD statement as follows:
//GO.DDSCHEMA DD PATH=/u/HLQ/xml/item.osr
Or you can use an analogous TSO ALLOCATE command.
Alternatively, DDSCHEMA in the example above could be the name of an environment
variable that identifies the external file by means of a DSN option that specifies an
MVS data set or a PATH option that specifies a z/OS UNIX file.
If your schema is in an MVS data set, the data set can be any sequential data set
(for example, QSAM fixed blocked or variable blocked, or VSAM ESDS).
For further details about how to associate an XML schema name with the external
file that contains the schema, see the related reference about the XML-SCHEMA clause.
Restriction: XML validation using the FILE keyword is not supported under
CICS.
The automatic retrieval that occurs when you use the FILE keyword is convenient.
But if you have several XML documents of the same type to validate, reading the
schema into memory once and then reusing the schema for each of the documents
provides better performance than automatic retrieval. In this case, you use the
other form of the VALIDATING phrase, in which you specify an identifier that
references an alphanumeric data item that contains the XML schema. For example:
XML PARSE document-item
VALIDATING WITH xmlschema
PROCESSING PROCEDURE xml-event-handler
ON EXCEPTION
DISPLAY Document has an error.
GOBACK
NOT ON EXCEPTION
DISPLAY Document is valid.
END-XML
Read the preprocessed schema into the data item, for example by using normal
COBOL statements.
For more information about this form of the VALIDATING phrase, see the related
reference about the XML PARSE statement.
During parsing with validation, normal XML events are returned until an
exception occurs due to a validation error or well-formedness error. If 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 specific validation 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 the related reference
| about exceptions with XMLPARSE(XMLSS) in effect.
Example: parsing XML documents with validation on page 558
RELATED CONCEPTS
XML-CODE on page 525
XML schemas on page 532
Chapter 28. Processing XML input 531
RELATED TASKS
Handling XML PARSE exceptions on page 542
RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
XML PARSE statement (Enterprise COBOL Language Reference)
XML-SCHEMA clause (Enterprise COBOL Language Reference)
z/OS XML System Services User's Guide and Reference
XML schemas
An XML schema is a mechanism, defined by the W3C, for describing and
constraining the structure and content of XML documents. An XML schema, which
is itself expressed in XML, effectively defines a class of XML documents of a given
type, for example, purchase orders.
For Enterprise COBOL, XML schemas used for validating XML documents must be
in a preprocessed format known as Optimized Schema Representation (OSR). For
information about this format, see the related reference about z/OS XML System
Services.
Consider an XML document that describes an item for stock-keeping purposes:
<stockItem itemNumber="453-SR">
<itemName>Stainless steel rope thimbles</itemName>
<quantityOnHand>23</quantityOnHand>
</stockItem>
The example document above is both well formed and valid according to the
following schema. (The numbers that precede each line are not part of the schema,
but are used in the explanations after the schema.)
1. <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
2.
3. <xsd:element name="stockItem" type="stockItemType"/>
4.
5. <xsd:complexType name="stockItemType">
6. <xsd:sequence>
7. <xsd:element name="itemName" type="xsd:string" minOccurs="0"/>
8. <xsd:element name="quantityOnHand">
9. <xsd:simpleType>
10. <xsd:restriction base="xsd:nonNegativeInteger">
11. <xsd:maxExclusive value="100"/>
12. </xsd:restriction>
13. </xsd:simpleType>
14. </xsd:element>
15. </xsd:sequence>
16. <xsd:attribute name="itemNumber" type="SKU" use="required"/>
17. </xsd:complexType>
18.
19. <xsd:simpleType name="SKU">
20. <xsd:restriction base="xsd:string">
21. <xsd:pattern value="\d{3}-[A-Z]{2}"/>
22. </xsd:restriction>
23. </xsd:simpleType>
24.
25. </xsd:schema>
The schema declares (line 3) that the root element is stockItem, which has a
mandatory itemNumber attribute (line 16) of type SKU, and includes a sequence
(lines 6 - 15) of other elements:
v An optional itemName element of type string (line 7)
532 Enterprise COBOL for z/OS, V5.2 Programming Guide
v A required quantityOnHand element that has a constrained range of 1 - 99 based
on the type nonNegativeInteger (lines 8 - 14)
Type declarations can be inline and unnamed, as in lines 9 - 13, which include the
maxExclusive facet to specify the legal values for the quantityOnHand element.
For the itemNumber attribute, by contrast, the named type SKU is declared separately
in lines 19 - 23, which include a pattern facet that uses regular expression syntax to
specify that the legal values for that type consist of (in order): 3 digits, a
hyphen-minus, then two uppercase letters.
The example referenced below shows a program that parses documents against
this schema.
Example: parsing XML documents with validation on page 558
RELATED TASKS
Parsing XML documents with validation on page 530
RELATED REFERENCES
z/OS XML System Services User's Guide and Reference
Parsing XML documents one segment at a time
You can parse XML documents by passing the parser one segment (or record) of
XML text at a time. Processing very large documents, or processing XML
documents that reside in a data set, are two possible major applications of this
technique.
| To use this feature, compile your program with the XMLPARSE(XMLSS) compiler
| option in effect.
You parse an XML document a segment at a time by initializing the parse data
item to the first segment of the XML document, and then executing the XML PARSE
statement. The parser processes the XML text and returns XML events to your
processing procedure as usual.
At the end of the text segment, the parser signals an END-OF-INPUT XML event,
with XML-CODE set to zero. If there is another segment of the document to process,
in your processing procedure move the next segment of XML data to the parse
data item, set XML-CODE to one, and return to the parser. To signal the end of XML
segments to the parser, return to the parser with XML-CODE still set to zero.
The length of the parse data item is evaluated for each segment, and determines
the segment length.
Variable-length segments: If the XML document segments are variable length,
specify a variable-length item for the parse data item. For example, for
variable-length XML segments, you can define the parse data item as one of the
following items:
v A variable-length group item that contains an OCCURS DEPENDING ON clause
v A reference-modified item
v An FD record that specifies the RECORD IS VARYING DEPENDING ON clause, where
the depending-on data item is used as the length in a reference modifier or ODO
object for the FD record
Chapter 28. Processing XML input 533
When you send an XML document to the parser in multiple segments, document
content is in some cases returned to the processing procedure in multiple
fragments by means of multiple events, rather than as one large fragment in a
single event.
For example, if the document is split into two segments with the split point in the
middle of a string of content characters, the parser returns the content in two
separate CONTENT-CHARACTERS events. In the processing procedure, you must
reassemble the string of content as needed by the application.
Starting element tags, attribute names, namespace declarations, and ending
element tags are always delivered to the processing procedure in a single event,
even if those items are split between two segments of a document.
If a segment split occurs between the bytes of a multibyte character, the parser
detects the split and reassembles the character for delivery in a single event.
If you are parsing an XML document with an unknown number of repetitive
elements to be processed, use unbounded tables. For more information on
unbounded tables, see Working with unbounded tables and groups on page 90.
For each such element in a given document, manage the table size using one of the
following methods:
v Calculating number of elements:
1. Count the number of elements in the document during an initial parse.
2. Set the OCCURS DEPENDING ON object for the table to that size
3. Allocate storage for the table
4. Parse the document a second time to process the XML
v Incremental expansion:
1. Set an initial size in the OCCURS DEPENDING ON object for the unbounded table
2. Parse the document normally. For each element
a. Check the limit and expand the unbounded table if necessary.
3. Allocate a new, larger storage area:
4. Copy the data from the smaller area
5. Free the smaller area
6. Set the table pointer to the address of the larger storage area.
QSAM and VSAM files: You can process XML documents stored in a QSAM or
VSAM file as follows:
1. Open the file and read the first record of the XML document.
2. Execute the XML PARSE statement with the FD record as the parse data item.
3. In the processing-procedure logic for handling the END-OF-INPUT event, read the
next record of the XML document into the parse data item. If not end-of-file
(file status code 10), set XML-CODE to one and return to the parser. If end-of-file,
return to the parser with XML-CODE still set to zero.
4. In your processing procedure logic for the END-OF-DOCUMENT event, close the file.
Miscellaneous information after the root element:
The root element of an XML document might be followed by zero or more
occurrences of a comment or processing instruction, in any order. If you parse the
document one segment at a time, the parser signals an END-OF-INPUT XML event
534 Enterprise COBOL for z/OS, V5.2 Programming Guide
after processing the end tag of the root element only if the last item in the segment
is incomplete. If the segment ends with a complete XML item (such as the root
element end tag, or after that tag, a complete comment or processing instruction),
the next XML event after the event for the item itself is the END-OF-DOCUMENT XML
event.
Tip: To provide successive segments of XML data after the end of the root element,
include at least the first nonspace character of an XML item at the end of each
segment. Include a complete item only on the last segment that you want the
parser to process.
For instance, in the following example, in which each line represents a segment of
an XML document, the segment that includes the text This comment ends this
segment is the last segment to be parsed:
<Tagline>
COBOL is the language of the future!
</Tagline> <
!--First comment--
> <?pi data?> <!-
-This comment ends this segment-->
<!-- This segment is not included in the parse-->
Example: parsing an XML document one segment at a time on page 556
RELATED CONCEPTS
XML events on page 524
XML-CODE on page 525
RELATED TASKS
Parsing XML documents one segment at a time on page 533
XML-CODE on page 525
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| Handling splits using the XML-INFORMATION special register
You can parse large XML documents by using the XML-INFORMATION special register.
To use this feature, compile your program with the XMLPARSE(XMLSS) compiler
option in effect.
Splits in character content might occur at arbitrary points in the XML data stream,
even with unsegmented input. The XML-INFORMATION special register simplifies the
reassembly of content. This register may be required for any and all attribute
values and element character content.
The length of the parse data item is evaluated for each segment, and determines
the segment length.
The example, Example: program for processing XML on page 548, demonstrates
various ways of assigning values obtained from the XML document to program
data items for later processing.
The XML data is provided to the parser in 40-byte records, imitating the way an
XML document might be acquired from an external source such as a data file. The
Chapter 28. Processing XML input 535
record boundaries are designed so that all data splits but one are accommodated
by the parser. For example, the sample treats as an error a split in any content
except the content of the "filling" element.
In the example, the XML-INFORMATION special register is only used to simplify the
reassembly of content for the "filling" element. This register could be used for
any attribute values and element character content. An XML-INFORMATION value of 2
indicates that the character data for an ATTRIBUTE-CHARACTERS or
CONTENT-CHARACTERS XML event is continued in a subsequent XML event, and
should thus be buffered in order to accumulate the complete character string. A
subsequent XML event of the same type with an XML-INFORMATION value of 1
indicates that XML-TEXT or XML-NTEXT contains the final piece of the character
content, and that the complete string can be moved to the appropriate data item.
In the example, the STRING ... WITH POINTER statement accumulates and
describes properly the complete character value for assignment to the "filling"
identifier.
String xml-text delimited by size into
content-buffer with pointer tally
On overflow
Display content buffer (
length of content-buffer
bytes) is too small
Move -1 to xml-code
End-string
RELATED CONCEPTS
XML events on page 524
XML-CODE on page 525
RELATED REFERENCES
XMLPARSE on page 368 (compiler option)
Example: program for processing XML on page 548
The encoding of XML documents
XML documents must be encoded in a supported code page.
XML documents generated in or parsed from national data items must be encoded
in Unicode UTF-16 in big-endian format, CCSID 1200.
For XML GENERATE statements, documents generated in alphanumeric data items
must be encoded in Unicode UTF-8 (CCSID 1208) or one of the single-byte
EBCDIC encodings listed in the table below. You can use any CCSID from that
table in the ENCODING phrase of the XML GENERATE statement.
For XML PARSE statements, documents in alphanumeric data items must be encoded
as follows:
| v If XMLPARSE(XMLSS) is in effect:
| If the RETURNING NATIONAL phrase is specified in the XML PARSE statement, in
| any EBCDIC or ASCII encoding that is supported by z/OS Unicode Services
| for conversion to UTF-16
| If the RETURNING NATIONAL phrase is not specified in the XML PARSE statement,
| in UTF-8 (CCSID 1208) or one of the single-byte EBCDIC encodings listed in
| the table below
536 Enterprise COBOL for z/OS, V5.2 Programming Guide
| v If XMLPARSE(COMPAT) is in effect: in one of the single-byte EBCDIC encodings
| listed in the table below
If XMLPARSE(XMLSS) is in effect, you can use any supported CCSID (as described
above for XML PARSE) in the ENCODING phrase of the XML PARSE statement.
Table 67. Coded character sets for XML documents
CCSID Description
1208 UTF-81
1047 Latin 1 / Open Systems
1140, 37 USA, Canada, . . . Euro Country Extended Code Page (ECECP),
Country Extended Code Page (CECP)
1141, 273 Austria, Germany ECECP, CECP
1142, 277 Denmark, Norway ECECP, CECP
1143, 278 Finland, Sweden ECECP, CECP
1144, 280 Italy ECECP, CECP
1145, 284 Spain, Latin America (Spanish) ECECP, CECP
1146, 285 UK ECECP, CECP
1147, 297 France ECECP, CECP
1148, 500 International ECECP, CECP
1149, 871 Iceland ECECP, CECP
1. Supported for the XML PARSE statement in the ENCODING phrase if XMLPARSE(XMLSS) is in
effect
RELATED CONCEPTS
XML input document encoding
RELATED TASKS
Specifying the encoding on page 539
Parsing XML documents encoded in UTF-8 on page 541
Chapter 29, Producing XML output, on page 561
RELATED REFERENCES
CODEPAGE on page 313
| XMLPARSE on page 368 (compiler option)
XML input document encoding
To parse an XML document using the XML PARSE statement, the document must be
encoded in a supported encoding.
The supported encodings for a given parse operation depend on:
v The category of the data item that contains the XML document
| v The setting of the XMLPARSE compiler option
v The optional phrases that are specified in the XML PARSE statement
For XML documents that are contained in a national data item, the supported
encoding is Unicode UTF-16 in big-endian format, CCSID 1200.
Chapter 28. Processing XML input 537
| For XML documents that are contained in an alphanumeric data item, the
| supported encodings if the XMLPARSE(XMLSS) compiler option is in effect are as
| follows:
v If the RETURNING NATIONAL phrase is specified in the XML PARSE statement: UTF-8
or any EBCDIC or ASCII encoding that is supported by the z/OS Unicode
Services for conversion to UTF-16
v If the RETURNING NATIONAL phrase is not specified: UTF-8 or any of the
single-byte EBCDIC CCSIDs listed in the related reference about the encoding of
XML documents
| For XML documents that are contained in an alphanumeric data item, the
| supported CCSIDs if XMLPARSE(COMPAT) is in effect are those specified in the related
| reference about the encoding of XML documents.
To parse an XML document that is encoded in an unsupported code page, first
convert the document to national character data (UTF-16) by using the NATIONAL-OF
intrinsic function. You can convert the individual pieces of document text that are
passed to the processing procedure in special register XML-NTEXT back to the
original code page by using the DISPLAY-OF intrinsic function.
XML declaration and white space:
XML documents can begin with white space only if they do not have an XML
declaration:
v If an XML document begins with an XML declaration, the first angle bracket (<)
in the document must be the first character in the document.
v If an XML document does not begin with an XML declaration, the first angle
bracket in the document can be preceded only by white space.
White-space characters have the hexadecimal values shown in the following table.
Table 68. Hexadecimal values of white-space characters
White-space character EBCDIC Unicode
Space X'40' X'0020'
Horizontal tabulation X'05' X'0009'
Carriage return X'0D' X'000D'
Line feed X'25' X'000A'
New line / next line X'15' X'0085'
Determining the encoding of an input XML document
The parser must know the encoding of an XML document in order to process the
document correctly.
If the specified encoding is not one of the supported coded character sets, the
parser signals an XML exception event before beginning the parse operation. If the
actual document encoding does not match the specified encoding, the parser signals
an appropriate XML exception after beginning the parse operation.
Several sources are used in determining the encoding of an XML document:
| v If the XMLPARSE(XMLSS) option is in effect:
| The data type of the data item that contains the XML document
| The ENCODING phrase (if used) of the XML PARSE statement
538 Enterprise COBOL for z/OS, V5.2 Programming Guide
| The CCSID specified in the CODEPAGE compiler option
| v Ifthe XMLPARSE(COMPAT) option is in effect:
| The data type of the data item that contains the XML document
| The actual encoding determined when the parser examines the first few bytes
| of the document
| The encoding declaration specified within the XML document
| The CCSID specified in the CODEPAGE compiler option
| If XMLPARSE(XMLSS) is in effect:
v Any encoding declaration specified within the XML document is ignored.
v For XML documents that are contained in a national data item, the ENCODING
phrase of the XML PARSE statement must be omitted or must specify CCSID 1200.
The CCSID specified in the CODEPAGE compiler option is ignored. The parser
signals an XML exception event if the actual document encoding is not UTF-16
in big-endian format.
v For XML documents that are contained in an alphanumeric data item, the
CCSID specified in the ENCODING phrase overrides the CODEPAGE compiler option.
The parser raises an XML exception event at the beginning of the parse
operation if the actual document encoding is not consistent with the specified
CCSID.
RELATED TASKS
Converting to or from national (Unicode) representation on page 137
Specifying the encoding
Parsing XML documents encoded in UTF-8 on page 541
Handling XML PARSE exceptions on page 542
RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
The encoding of XML documents on page 536
EBCDIC code-page-sensitive characters in XML markup on page 540
Specifying the encoding
You can choose how to specify the encoding for parsing an XML document that is
in an alphanumeric data item.
The preferred way is to omit the encoding declaration from the document and to
| specify the encoding using one of the following means:
| v If XMLPARSE(XMLSS) is in effect: the ENCODING phrase of the XML PARSE statement,
| or the CODEPAGE compiler option
| v If XMLPARSE(COMPAT) is in effect: the CODEPAGE compiler option
Omitting the encoding declaration makes it possible to more easily transmit an
XML document between heterogeneous systems. (If you included an encoding
declaration, you would need to update it to reflect any code-page translation
imposed by the transmission process.)
| For XMLPARSE(COMPAT):
| You can instead specify an encoding declaration in the XML declaration with
| which most XML documents begin. For example:
| <?xml version="1.0" encoding="ibm-1140"?>
Chapter 28. Processing XML input 539
| Note that the XML parser generates an exception if it encounters an XML
| declaration that does not begin in the first byte of an XML document.
If you specify an encoding declaration, do so in one of the following ways:
v Specify the CCSID number (with or without any number of leading zeros)
prefixed by one of the following strings in any mixture of uppercase and
lowercase letters:
IBM-
IBM_
CCSID-
CCSID_
v Use one of the aliases listed in the following table. You can code the aliases in
any mixture of uppercase and lowercase letters.
Table 69. Aliases for XML encoding declarations
CCSID Supported aliases
037 EBCDIC-CP-US, EBCDIC-CP-CA, EBCDIC-CP-WT, EBCDIC-CP-NL
500 EBCDIC-CP-BE, EBCDIC-CP-CH
1200 UTF-16
1208 UTF-8
For more information about the CCSIDs that are supported for XML parsing, see
the related reference about the encoding of XML documents.
RELATED CONCEPTS
XML input document encoding on page 537
RELATED TASKS
Parsing XML documents encoded in UTF-8 on page 541
| Handling encoding conflicts on page 545
RELATED REFERENCES
The encoding of XML documents on page 536
EBCDIC code-page-sensitive characters in XML markup
Several special characters that are used in XML markup have different hexadecimal
representations in different EBCDIC code pages.
The following table shows those special characters and their hexadecimal values
for various EBCDIC CCSIDs.
Table 70. Hexadecimal values of special characters for various EBCDIC CCSIDs
Character 1047 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149
[ X'AD' X'BA' X'63' X'9E' X'B5' X'90' X'4A' X'B1' X'90' X'4A' X'AE'
] X'BD' X'BB' X'FC' X'9F' X'9F' X'51' X'5A' X'BB' X'B5' X'5A' X'9E'
! X'5A' X'5A' X'4F' X'4F' X'4F' X'4F' X'BB' X'5A' X'4F' X'4F' X'4F'
| X'4F' X'4F' X'BB' X'BB' X'BB' X'BB' X'4F' X'4F' X'BB' X'BB' X'BB'
# X'7B' X'7B' X'7B' X'4A' X'63' X'B1' X'69' X'7B' X'B1' X'7B' X'7B'
540 Enterprise COBOL for z/OS, V5.2 Programming Guide
Parsing XML documents encoded in UTF-8
| If the XMLPARSE(XMLSS) compiler option is in effect, you can parse XML documents
that are encoded in Unicode UTF-8 in a manner similar to parsing other XML
documents. However, some additional requirements apply.
To parse a UTF-8 XML document, you must specify CCSID 1208 in the ENCODING
phrase of the XML PARSE statement, as shown in the following code fragment:
XML PARSE xml-document
WITH ENCODING 1208
PROCESSING PROCEDURE xml-event-handler
. . .
END-XML
You define xml-document as an alphanumeric data item or alphanumeric group
item in WORKING-STORAGE or LOCAL-STORAGE.
If you do not code the RETURNING NATIONAL phrase in the XML PARSE statement, the
parser returns the XML document fragments in the alphanumeric special registers
XML-TEXT, XML-NAMESPACE, and XML-NAMESPACE-PREFIX.
UTF-8 characters are encoded using a variable number of bytes per character. Most
COBOL operations on alphanumeric data assume a single-byte encoding, in which
each character is encoded in 1 byte. When you operate on UTF-8 characters as
alphanumeric data, you must ensure that the data is processed correctly. Avoid
operations (such as reference modification and moves that involve truncation) that
can split a multibyte character between bytes. You cannot reliably use statements
such as INSPECT to process multibyte characters in alphanumeric data.
You can more reliably process UTF-8 document fragments by specifying the
RETURNING NATIONAL phrase in the XML PARSE statement. If you use the RETURNING
NATIONAL phrase, XML document fragments are efficiently converted to UTF-16
encoding and are returned to the application in the national special registers
XML-NTEXT, XML-NNAMESPACE, and XMLNNAMESPACE-PREFIX. Then you can process the
XML text fragments in national data items. (The UTF-16 encoding in national data
items greatly facilitates Unicode processing in COBOL.)
The following code fragment illustrates the use of both the ENCODING phrase and
the RETURNING NATIONAL phrase for parsing a UTF-8 XML document:
XML PARSE xml-document
WITH ENCODING 1208 RETURNING NATIONAL
PROCESSING PROCEDURE xml-event-handler
ON EXCEPTION
DISPLAY XML document error XML-CODE
STOP RUN
NOT ON EXCEPTION
DISPLAY XML document was successfully parsed.
END-XML
RELATED CONCEPTS
XML-TEXT and XML-NTEXT on page 527
XML-NAMESPACE and XML-NNAMESPACE on page 527
XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX on page 528
RELATED TASKS
Processing UTF-8 data on page 141
Parsing XML documents on page 520
Specifying the encoding on page 539
Chapter 28. Processing XML input 541
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
The encoding of XML documents on page 536
XML PARSE statement (Enterprise COBOL Language Reference)
Handling XML PARSE exceptions
If the XML parser encounters an anomaly or error during parsing, it sets an
exception code in the XML-CODE special register and signals an XML exception
| event. The specific exception codes that can occur and the subsequent actions that
| you can take differ depending on the setting of the XMLPARSE compiler option.
| For XMLPARSE(XMLSS):
Return code and reason code: The exception code is formed from the return code
and the reason code that the parser generates. The return code and the reason code
are each a halfword binary value. The value in XML-CODE is a concatenation of these
two values.
As an example, the following XML document is not well formed because the
element end tag mmsg does not match the element start tag msg:
<msg>Hello</mmsg>
The return code is hexadecimal 000C (XRC_NOT_WELL_FORMED), and the reason code
is hexadecimal 3035 (XRSN_ENDTAG_NAME_MISMATCH), if you parse the document
without validation. The concatenation of these two values, hexadecimal 000C3035,
is returned to the processing procedure in the XML-CODE special register.
If you parse a document with validation, the values returned in XML-CODE for any
well-formedness errors differ from the values returned for the same errors when
you parse without validation. The return code generated by the z/OS XML System
Services parser for any validation error is 24 (hexadecimal 0018).
For more information about the return codes and reason codes that can be
generated, see the related reference about exceptions with XMLPARSE(XMLSS) in
effect.
| If XMLPARSE(XMLSS) is in effect, processing procedures cannot handle exception
| events and cannot cause parsing to resume. When a processing procedure returns
to the parser from an exception event, the parser does not signal any further
events. The parser transfers control to the statement that is specified in the ON
EXCEPTION phrase of the XML PARSE statement. If you did not code an ON EXCEPTION
phrase, control is passed to the end of the XML PARSE statement. XML-CODE contains
the original exception code set by the parser.
If no exception occurs during parsing, control is passed to the statement specified
in the NOT ON EXCEPTION phrase. If you did not code a NOT ON EXCEPTION phrase,
control is passed to the end of the XML PARSE statement. XML-CODE contains zero.
| For XMLPARSE(COMPAT):
| If the exception code is within a certain range, you might be able to handle the
| exception event within your processing procedure, and resume parsing.
| To handle an exception in the processing procedure, follow these steps:
542 Enterprise COBOL for z/OS, V5.2 Programming Guide
| 1. Check the contents of XML-CODE.
| 2. Handle the exception appropriately.
| 3. Set XML-CODE to zero to indicate that you handled the exception.
| 4. Return control to the parser.
| The exception condition no longer exists.
| You can handle exceptions in this way only if the exception code that is passed in
| XML-CODE is within one of the following ranges, which indicates that an encoding
| conflict was detected:
| v 50 - 99
| v 100,001 - 165,535
| Exception codes 1 - 49: In the processing procedure, you can do limited handling
| of exceptions for which the exception code is within the range 1 - 49. After an
| exception in this range occurs, the parser does not signal any further normal
| events, except the END-OF-DOCUMENT event, even if you set XML-CODE to zero before
| returning. If you set XML-CODE to zero, the parser continues parsing the document
| and signals any exceptions that it finds. (Doing so can provide a useful way to
| discover multiple errors in the document.)
| Restriction: The compatibility-mode COBOL XML parser might not signal all
| additional exception events. The number of exceptions is limited to the remaining
| space in the XML PARSE event token array, probably 8192 events.
| At the end of parsing after an exception that has an exception code in the range 1 -
| 49, control is passed to the statement specified in the ON EXCEPTION phrase. If you
| did not code an ON EXCEPTION phrase, control is passed to the end of the XML PARSE
| statement. XML-CODE contains the code set by the parser for the most recent
| exception.
| For all exceptions other than those having an exception code within one of the
| ranges described above, the parser does not signal any further events, but passes
| control to the statement specified in the ON EXCEPTION phrase. XML-CODE contains
| the original exception code even if you set XML-CODE in the processing procedure
| before returning control to the parser.
| If you do not want to handle an exception, return control to the parser without
| changing the value of XML-CODE. The parser transfers control to the statement
| specified in the ON EXCEPTION phrase. If you did not code an ON EXCEPTION phrase,
| control is transferred to the end of the XML PARSE statement.
| If no unhandled exceptions occur before the end of parsing, control is passed to
| the statement specified in the NOT ON EXCEPTION phrase. If you did not code a NOT
| ON EXCEPTION phrase, control is transferred to the end of the XML PARSE statement.
| XML-CODE contains zero.
| RELATED CONCEPTS
| XML-CODE on page 525
| XML input document encoding on page 537
| How the XML parser handles errors on page 544
| RELATED TASKS
| Writing procedures to process XML on page 522
Chapter 28. Processing XML input 543
| Parsing XML documents with validation on page 530
| Handling encoding conflicts on page 545
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| The encoding of XML documents on page 536
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect on page 693
| z/OS XML System Services User's Guide and Reference
| How the XML parser handles errors
When the XML parser detects an error in an XML document, it generates an XML
exception event and passes control to your processing procedure.
The parser passes the following information in special registers to the processing
procedure:
v XML-EVENT contains 'EXCEPTION'.
v XML-CODE contains a numeric exception code.
The exception codes are described in the related references about XML PARSE
exceptions.
v For fatal exceptions, XML-TEXT or XML-NTEXT contains the document text up to
and including the point where the exception was detected.
v For the warning exceptions issued for using an undeclared prefix, XML-TEXT or
XML-NTEXT contains the fully qualified attribute name or element name. That is,
the name includes the undeclared prefix and the separator colon (:).
| v If XMLPARSE(COMPAT) is in effect, XML-TEXT or XML-NTEXT contains the document
| text up to and including the point where the exception was detected.
| v If XMLPARSE(XMLSS) is in effect, XML-TEXT or XML-NTEXT contains the document text
| up to the point where the error or anomaly was detected. If you process the
| XML document one segment at a time, the applicable special register contains
| only the current segment.
All other XML special registers are empty with length zero.
| For XMLPARSE(XMLSS):
Parsing cannot continue after a fatal exception even if you set XML-CODE to zero in
the processing procedure. Upon return to the parser from the processing
procedure, the parser transfers control to the ON EXCEPTION phrase, if specified;
otherwise the parser transfers control to the end of the XML PARSE statement.
XML-CODE contains the original exception code set by the parser.
| For XMLPARSE(COMPAT):
| The processing procedure might be able to handle an exception so that parsing
| continues if the exception code is within one of the following ranges:
| v 1 - 99
| v 100,001 - 165,535
| If the exception code has any other nonzero value, parsing cannot continue.
544 Enterprise COBOL for z/OS, V5.2 Programming Guide
| Encoding conflicts: The exceptions for encoding conflicts (50 - 99 and 300 - 399)
| are signaled before the parsing of the document begins. For these exceptions,
| XML-TEXT or XML-NTEXT is either length zero or contains only the encoding
| declaration value from the document.
| Exception codes 1 - 49: An exception for which the exception code is in the range
| 1 - 49 is a fatal error according to the XML specification. Therefore, the parser does
| not continue normal parsing even if the processing procedure handles the
| exception. However, the parser does continue scanning for further errors until it
| reaches the end of the document, or until the existing XML EVENT token array is
| exhausted. For these exceptions, the parser does not signal any further normal
| events except the END-OF-DOCUMENT event.
RELATED CONCEPTS
XML events on page 524
XML-CODE on page 525
XML input document encoding on page 537
RELATED TASKS
Parsing XML documents one segment at a time on page 533
Handling XML PARSE exceptions on page 542
| Handling encoding conflicts
Terminating XML parsing on page 546
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
The encoding of XML documents on page 536
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect on page 693
z/OS XML System Services User's Guide and Reference
XML specification
| Handling encoding conflicts
| The way that you handle encoding-conflict exceptions depends on the setting of
| the XMLPARSE compiler option.
| For XMLPARSE(XMLSS):
| The parser does not continue after an encoding-conflict exception or after any
| other type of exception. Any changes that you make in the processing procedure to
| the value of XML-CODE are ignored. The value in XML-CODE when the parser returns
| to the XML PARSE statement is the original exception code that the parser set.
| For XMLPARSE(COMPAT):
| Your processing procedure might be able to handle exceptions for document
| encoding conflicts. Exception events in which the parse data item is alphanumeric
| and the exception code in XML-CODE is within the range 100,001 - 165,535 indicate
| that the code page of the document (as specified by its encoding declaration)
| conflicts with the external code-page information.
| In this special case, you can choose to parse using the code page of the document
| by subtracting 100,000 from the value in XML-CODE. For instance, if XML-CODE
Chapter 28. Processing XML input 545
| contains 101,140, the code page of the document is 1140. Alternatively, you can
| choose to parse using the external code page by setting XML-CODE to zero before
| returning to the parser.
| The parser takes one of three actions after returning from a processing procedure
| for an encoding-conflict exception event:
| v If you set XML-CODE to zero, the parser uses the external code page: the value of
| the CODEPAGE compiler option.
| v If you set XML-CODE to the code page of the document (that is, the original
| XML-CODE value minus 100,000), the parser uses the code page of the document.
| This is the only case in which the parser continues when XML-CODE has a nonzero
| value upon returning from a processing procedure.
| v Otherwise, the parser stops processing the document and returns control to the
| XML PARSE statement with an exception condition. XML-CODE contains the
| exception code that was originally passed with the exception event.
| RELATED CONCEPTS
| XML-CODE on page 525
| XML input document encoding on page 537
| How the XML parser handles errors on page 544
| RELATED TASKS
| Handling XML PARSE exceptions on page 542
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| The encoding of XML documents on page 536
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect on page 693
| z/OS XML System Services User's Guide and Reference
|
Terminating XML parsing
You can terminate parsing immediately, without processing any remaining XML
text, by setting XML-CODE to -1 in your processing procedure before the procedure
returns to the parser from any normal XML event (that is, any event other than
EXCEPTION).
You can use this technique when the processing procedure has examined enough
of the document or has detected some irregularity in the document that precludes
further meaningful processing.
If you terminate parsing in this way, the parser does not signal any further XML
events, including the exception event. Control transfers to the ON EXCEPTION phrase
of the XML PARSE statement, if that phrase was specified.
In the imperative statement of the ON EXCEPTION phrase, you can determine
whether parsing was deliberately terminated by testing whether XML-CODE contains
-1. If you do not specify the ON EXCEPTION phrase, control transfers to the end of
the XML PARSE statement.
| If the XMLPARSE(COMPAT) compiler option is in effect, you can also terminate parsing
| after any XML EXCEPTION event by returning to the parser from the processing
| procedure without changing the value in XML-CODE. The result is similar to the
546 Enterprise COBOL for z/OS, V5.2 Programming Guide
| result of deliberate termination, except that the parser returns to the XML PARSE
| statement with XML-CODE containing the original exception code.
| If the XMLPARSE(XMLSS) option is in effect, parsing always terminates after any
| exception event.
RELATED CONCEPTS
XML-CODE on page 525
How the XML parser handles errors on page 544
RELATED TASKS
Writing procedures to process XML on page 522
Handling XML PARSE exceptions on page 542
XML PARSE examples
The examples that are referenced below illustrate various uses of the XML PARSE
statement.
| Use these examples to understand the basic use of XML PARSE and for
| XMLPARSE(XMLSS), specialized uses such as parsing documents that include
| namespaces, parsing documents one segment at a time, and parsing documents
| with validation against a schema.
Example: parsing a simple document
Example: program for processing XML on page 548
Example: parsing an XML document that uses namespaces on page 553
Example: parsing an XML document one segment at a time on page 556
Example: parsing XML documents with validation on page 558
Example: parsing a simple document
This example shows the flow of events and the contents of special register
XML-TEXT that result from the parsing of a simple XML document.
Assume that the COBOL program contains the following XML document in data
item Doc:
<?xml version="1.0"?><msg type="short">Hello, World!</msg>
The following code fragment shows an XML PARSE statement for parsing Doc, and a
processing procedure, P, for handling the XML events:
XML Parse Doc
Processing procedure P
. . .
P. Display XML-Event XML-Text.
The processing procedure displays the content of XML-EVENT and XML-TEXT for each
event that the parser signals during parsing. The following table shows the events
and the text.
Table 71. XML events and special registers
XML-EVENT XML-TEXT
START-OF-DOCUMENT
VERSION-INFORMATION 1.0
START-OF-ELEMENT msg
Chapter 28. Processing XML input 547
Table 71. XML events and special registers (continued)
XML-EVENT XML-TEXT
ATTRIBUTE-NAME type
ATTRIBUTE-CHARACTERS short
CONTENT-CHARACTERS Hello, World!
END-OF-ELEMENT msg
END-OF-DOCUMENT
RELATED CONCEPTS
XML events on page 524
XML-TEXT and XML-NTEXT on page 527
Example: program for processing XML
This example shows the parsing of an XML document, and a processing procedure
that reports the various XML events and their associated text fragments.
The XML document is shown in the program source to make it easier to follow the
| flow of the parsing. The output of the program with XMLPARSE(XMLSS) and with
| XMLPARSE(COMPAT) in effect is shown after the example.
To understand the interaction of the parser and the processing procedure, and to
match events to document fragments, compare the XML document to the output of
the program.
Process codepage(1047)
Identification division.
Program-id. XMLSAMPL.
Data division.
Working-storage section.
******************************************************************
* XML document data, encoded as initial values of data items. *
******************************************************************
1 xml-document-data.
2 pic x(39) value <?xml version="1.0" encoding="IBM-1047".
2 pic x(19) value standalone="yes"?>.
2 pic x(39) value <!--This document is just an example-->.
2 pic x(10) value <sandwich>.
2 pic x(33) value <bread type="baker's best"/>.
2 pic x(36) value <?spread Well use real mayonnaise?>.
2 pic x(29) value <meat>Ham & turkey</meat>.
2 pic x(34) value <filling>Cheese, lettuce, tomato, .
2 pic x(32) value and thats all, Folks!</filling>.
2 pic x(25) value <![CDATA[We should add a .
2 pic x(20) value <relish> element!]]>.
2 pic x(28) value <listprice>$4.99</listprice>.
2 pic x(25) value <discount>0.10</discount>.
2 pic x(31) value </sandwich>.
******************************************************************
* XML document, represented as fixed-length records. *
******************************************************************
1 xml-document redefines xml-document-data.
2 xml-segment pic x(40) occurs 10 times.
1 xml-segment-no comp pic s9(4).
1 content-buffer pic x(100).
1 current-element-stack.
2 current-element pic x(30) occurs 10 times.
******************************************************************
* Sample data definitions for processing numeric XML content. *
******************************************************************
548 Enterprise COBOL for z/OS, V5.2 Programming Guide
1 element-depth comp pic s9(4).
1 discount computational pic 9v99 value 0.
1 display-price pic $$9.99.
1 filling pic x(4095).
1 list-price computational pic 9v99 value 0.
1 ofr-ed pic x(9) justified.
1 ofr-ed-1 redefines ofr-ed pic 999999.99.
Procedure division.
Mainline section.
Move 1 to xml-segment-no
Display Initial segment { xml-segment(xml-segment-no) }
Display
XML parse xml-segment(xml-segment-no)
processing procedure XML-handler
On exception
Display XML processing error, XML-Code= XML-Code .
Move 16 to return-code
Goback
Not on exception
Display XML document successfully parsed.
End-XML
******************************************************************
* Process the transformed content and calculate promo price. *
******************************************************************
Display
Display -----+++++***** Using information from XML
*****+++++-----
Display
Move list-price to Display-price
Display Sandwich list price: Display-price
Compute Display-price = list-price * (1 - discount)
Display Promotional price: Display-price
Display Get one today!
Goback.
XML-handler section.
Evaluate XML-Event
* ==> Order XML events most frequent first
When START-OF-ELEMENT
Display Start element tag: { XML-Text }
Add 1 to element-depth
Move XML-Text to current-element(element-depth)
When CONTENT-CHARACTERS
Display Content characters: { XML-Text }
* ==> In general, a split can occur for any element or attribute
* ==> data, but in this sample, it only occurs for "filling"...
If xml-information = 2 and
current-element(element-depth) not = filling
Display Unexpected split in content for element
current-element(element-depth)
Move -1 to xml-code
End-if
* ==> Transform XML content to operational COBOL data item...
Evaluate current-element(element-depth)
When filling
* ==> After reassembling separate pieces of character content...
String xml-text delimited by size into
content-buffer with pointer tally
On overflow
Display content buffer (
length of content-buffer
bytes) is too small
Move -1 to xml-code
End-string
Evaluate xml-information
When 2
Display Character data for element "filling"
is incomplete.
Chapter 28. Processing XML input 549
Display The partial data was buffered for
content assembly.
When 1
subtract 1 from tally
move content-buffer(1:tally) to filling
Display Element "filling" data ( tally
bytes) is now complete:
Display { filling(1:tally) }
End-evaluate
When listprice
* ==> Using function NUMVAL-C...
Move XML-Text to content-buffer
Compute list-price =
function numval-c(content-buffer)
When discount
* ==> Using de-editing of a numeric edited item...
Move XML-Text to ofr-ed
Move ofr-ed-1 to discount
End-evaluate
When END-OF-ELEMENT
Display End element tag: { XML-Text }
Subtract 1 from element-depth
When END-OF-INPUT
Display End of input
Add 1 to xml-segment-no
Display Next segment: { xml-segment(xml-segment-no)
}
Display
Move 1 to xml-code
When START-OF-DOCUMENT
Display Start of document
Move 0 to element-depth
Move 1 to tally
When END-OF-DOCUMENT
Display End of document.
When VERSION-INFORMATION
Display Version: { XML-Text }
When ENCODING-DECLARATION
Display Encoding: { XML-Text }
When STANDALONE-DECLARATION
Display Standalone: { XML-Text }
When ATTRIBUTE-NAME
Display Attribute name: { XML-Text }
When ATTRIBUTE-CHARACTERS
Display Attribute value characters: { XML-Text }
When ATTRIBUTE-CHARACTER
Display Attribute value character: { XML-Text }
When START-OF-CDATA-SECTION
Display Start of CData section
When END-OF-CDATA-SECTION
Display End of CData section
When CONTENT-CHARACTER
Display Content character: { XML-Text }
When PROCESSING-INSTRUCTION-TARGET
Display PI target: { XML-Text }
When PROCESSING-INSTRUCTION-DATA
Display PI data: { XML-Text }
When COMMENT
Display Comment: { XML-Text }
When EXCEPTION
Compute tally = function length (XML-Text)
Display Exception XML-Code at offset tally .
When other
Display Unexpected XML event: XML-Event .
End-evaluate
.
End program XMLSAMPL.
550 Enterprise COBOL for z/OS, V5.2 Programming Guide
| Output from parsing with XMLPARSE(XMLSS)
From the following output you can see which fragments of the document were
associated with the events that occurred during parsing:
Initial segment {<?xml version="1.0" encoding="ibm-1047" }
Start of document
End of input
Next segment: {standalone="yes"?><!--This document is j}
Version: {1.0}
Encoding: {ibm-1047}
Standalone: {yes}
Comment: {This document is j}
End of input
Next segment: {ust an example--><sandwich><bread type="}
Comment: {ust an example}
Start element tag: {sandwich}
End of input
Next segment: {baker's best"/><?spread Well use r}
Start element tag: {bread}
Attribute name: {type}
Attribute value characters: {bakers best}
End element tag: {bread}
PI target: {spread}
PI data: {Well use r}
End of input
Next segment: {eal mayonnaise?><meat>Ham & turkey</}
PI target: {spread}
PI data: {eal mayonnaise}
Start element tag: {meat}
Content characters: {Ham & turkey}
End of input
Next segment: {meat><filling>Cheese, lettuce, tomato, a}
End element tag: {meat}
Start element tag: {filling}
Content characters: {Cheese, lettuce, tomato, a}
Character data for element "filling" is incomplete.
The partial data was buffered for content assembly.
End of input
Next segment: {nd thats all, Folks!</filling><![CDATA[}
Content characters: {nd thats all, Folks!}
Element "filling" data (00047 bytes) is now complete:
{Cheese, lettuce, tomato, and thats all, Folks!}
End element tag: {filling}
End of input
Next segment: {We should add a <relish> element!]]><lis}
Start of CData section
Content characters: {We should add a <relish> element!}
End of CData section
End of input
Next segment: {tprice>$4.99</listprice><discount>0.10</}
Start element tag: {listprice}
Content characters: {$4.99}
End element tag: {listprice}
Start element tag: {discount}
Content characters: {0.10}
End of input
Next segment: {discount></sandwich> }
Chapter 28. Processing XML input 551
End element tag: {discount}
End element tag: {sandwich}
End of document.
XML document successfully parsed.
-----+++++***** Using information from XML *****+++++-----
Sandwich list price: $4.99
Promotional price: $4.49
Get one today!
| Output from parsing with XMLPARSE(COMPAT)
From the following output you can see which fragments of the document were
associated with the events that occurred during parsing:
Start of document
Version: {1.0}
Encoding: {IBM-1047}
Standalone: {yes}
Comment: {This document is just an example}
Start element tag: {sandwich}
Content characters: { }
Start element tag: {bread}
Attribute name: {type}
Attribute value characters: {baker}
Attribute value character: {}
Attribute value characters: {s best}
End element tag: {bread}
Content characters: { }
PI target: {spread}
PI data: {please use real mayonnaise }
Content characters: { }
Start element tag: {meat}
Content characters: {Ham }
Content character: {&}
Content characters: { turkey}
End element tag: {meat}
Content characters: { }
Start element tag: {filling}
Content characters: {Cheese, lettuce, tomato, etc.}
End element tag: {filling}
Content characters: { }
Start of CData: {<![CDATA[}
Content characters: {We should add a <relish> element in future!}
End of CData: {]]>}
Content characters: { }
Start element tag: {listprice}
Content characters: {$4.99 }
End element tag: {listprice}
Content characters: { }
Start element tag: {discount}
Content characters: {0.10}
End element tag: {discount}
End element tag: {sandwich}
End of document.
XML document successfully parsed
-----+++++***** Using information from XML *****+++++-----
Sandwich list price: $4.99
Promotional price: $4.49
Get one today!
RELATED CONCEPTS
XML events on page 524
552 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Handling splits using the XML-INFORMATION special register on page 535
RELATED REFERENCES
XMLPARSE on page 368 (compiler option)
XML-EVENT (Enterprise COBOL Language Reference)
| Example: parsing an XML document that uses namespaces
| This example shows the parsing of a document that uses namespaces and
| namespace prefixes. The program must be compiled using the XMLPARSE(XMLSS)
| compiler option.
Namespace identifiers and namespace prefixes are used in the program to qualify
element names and attribute names. This qualification makes it possible to use the
same name in more than one context: title is used both as an author's title (Mr)
and as a book title (Writing COBOL for Fun and Profit).
Sample XML document
The following XML document contains several namespace declarations: a default
namespace; then three namespace identifiers with prefixes (bk, pi, and isbn).
Notice that the default namespace is set to the empty string for the element
comment (xmlns=). This setting undeclares the default namespace, with the
result that there is no default namespace.
<section
xmlns="http://www.ibm.com/events"
xmlns:bk="urn:loc.gov:books"
xmlns:pi="urn:personalInformation"
xmlns:isbn=urn:ISBN:0-395-36341-6>
<title>Book-Signing Event</title>
<signing>
<bk:author pi:title="Mr" pi:name="Jim Ross"/>
<book bk:title="Writing COBOL for Fun and Profit" isbn:number="0426070806"/>
<comment xmlns=>What a great issue!</comment>
</signing>
</section>
Results from parsing
The following table shows the sequence of events that the processing procedure
receives from the parser, and shows the content of the associated XML special
registers.
Table 72. XML events and special registers
XML-EVENT XML-TEXT XML-NAMESPACE-PREFIX XML-NAMESPACE
START-OF-DOCUMENT
START-OF-ELEMENT section http://www.ibm.com/events
NAMESPACE-DECLARATION http://www.ibm.com/events
NAMESPACE-DECLARATION bk urn:loc.gov:books
NAMESPACE-DECLARATION pi urn:personalInformation
NAMESPACE-DECLARATION isbn urn:ISBN:0-395-36341-6
START-OF-ELEMENT title http://www.ibm.com/events
CONTENT-CHARACTERS Book-Signing Event
END-OF-ELEMENT title http://www.ibm.com/events
START-OF-ELEMENT signing http://www.ibm.com/events
Chapter 28. Processing XML input 553
Table 72. XML events and special registers (continued)
XML-EVENT XML-TEXT XML-NAMESPACE-PREFIX XML-NAMESPACE
START-OF-ELEMENT author bk urn:loc.gov:books
ATTRIBUTE-NAME title pi urn:personalInformation
ATTRIBUTE-CHARACTERS Mr
ATTRIBUTE-NAME name pi urn:personalInformation
ATTRIBUTE-CHARACTERS Jim Ross
END-OF-ELEMENT author bk urn:loc.gov:books
START-OF-ELEMENT book http://www.ibm.com/events
ATTRIBUTE-NAME title bk urn:loc.gov:books
ATTRIBUTE-CHARACTERS Writing COBOL for
Fun and Profit
ATTRIBUTE-NAME number isbn urn:ISBN:0-395-36341-6
ATTRIBUTE-CHARACTERS 0426070806
END-OF-ELEMENT book http://www.ibm.com/events
START-OF-ELEMENT comment
NAMESPACE-DECLARATION
CONTENT-CHARACTERS What a great issue!
END-OF-ELEMENT comment
END-OF-ELEMENT signing http://www.ibm.com/events
END-OF-ELEMENT section http://www.ibm.com/events
END-OF-DOCUMENT
XML PARSE example with an undeclared namespace prefix
The following XML document contains undeclared namespace prefixes:
Identification division.
Program-id. XMLup.
Data division.
Working-storage section.
1 d.
2 pic x(40) value <pfx0:root xmlns:pfx1="http://whatever">.
2 pic x(19) value <pfx1:localElName1>.
2 pic x(20) value <pfx2:localElName2/>.
2 pic x(40) value <pfx3:localElName3 pfx4:localAtName4="">.
2 pic x(02) value c1.
2 pic x(41) value <pfx5:localElName5 pfx6:localAtName6=""/>.
2 pic x(24) value c2</pfx3:localElName3>c3.
2 pic x(32) value </pfx1:localElName1></pfx0:root>.
Procedure division.
main.
display XML document: d
display
xml parse d processing procedure h
goback.
h.
if xml-event = EXCEPTION
display
end-if
display xml-event xml-code | xml-text |
xml-namespace-prefix |
xml-namespace |
if xml-event = EXCEPTION and xml-code = 264192 or 264193
554 Enterprise COBOL for z/OS, V5.2 Programming Guide
move 0 to xml-code
end-if
.
End program XMLup.
Results from parsing XML document with an undeclared namespace
prefix
The following table lists the sequence of events that the processing procedure
receives from the parser, and shows the content of the associated XML special
registers.
Table 73. XML events and special registers from parsing XML document with an undeclared namespace prefix
XML-NAMESPACE-
XML-EVENT XML-CODE XML-TEXT PREFIX XML-NAMESPACE
START-OF-DOCUMENT 000000000
EXCEPTION 000264193 pfx0:root
START-OF-ELEMENT 000000000 root pfx0
NAMESPACE- 000000000 pfx1 http://whatever
DECLARATION
START-OF-ELEMENT 000000000 localElName1 pfx1 http://whatever
EXCEPTION 000264193 pfx2:localElName2
START-OF-ELEMENT 000000000 localElName2 pfx2
END-OF-ELEMENT 000000000 localElName2 pfx2
EXCEPTION 000264193 pfx3:localElName3
START-OF-ELEMENT 000000000 localElName3 pfx3
EXCEPTION 000264192 pfx4:localAtName4
ATTRIBUTE-NAME 000000000 localAtName4 pfx4
ATTRIBUTE- 000000000
CHARACTERS
CONTENT-CHARACTERS 000000000 c1
EXCEPTION 000264193 pfx5:localElName5
START-OF-ELEMENT 000000000 localElName5 pfx5
EXCEPTION 000264192 pfx6:localAtName6
ATTRIBUTE-NAME 000000000 localAtName6 pfx6
ATTRIBUTE- 000000000
CHARACTERS
END-OF-ELEMENT 000000000 localElName5 pfx5
CONTENT-CHARACTERS 000000000 c2
END-OF-ELEMENT 000000000 localElName3 pfx3
CONTENT-CHARACTERS 000000000 c3
END-OF-ELEMENT 000000000 localElName1 pfx1 http://whatever
END-OF-ELEMENT 000000000 root pfx0
END-OF-DOCUMENT 000000000
For a detailed description of the set of XML events, see the related reference about
XML-EVENT.
Chapter 28. Processing XML input 555
RELATED CONCEPTS
XML events on page 524
XML-TEXT and XML-NTEXT on page 527
XML-NAMESPACE and XML-NNAMESPACE on page 527
XML-NAMESPACE-PREFIX and XML-NNAMESPACE-PREFIX on page 528
RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
XML-EVENT (Enterprise COBOL Language Reference)
Example: parsing an XML document one segment at a time
This example shows the parsing of a document one segment at a time. The
program must be compiled using the XMLPARSE(XMLSS) compiler option.
The example shows the XML content of a file, the program that reads and submits
XML text to the parser, and the sequence of events that results from parsing the
input records.
Content of infile
The XML document that will be parsed a segment at a time is contained in file
infile, shown below.
<?xml version=1.0?>
<Tagline>
COBOL is the language of the future!
</Tagline>
Program PARSESEG
Program PARSESEG reads a segment (a record) of the XML document from file
infile, then passes the record to the parser using the XML PARSE statement. The
parser processes the XML text and transfers control to the processing procedure for
each XML event. The processing procedure handles each event and returns to the
parser.
At the end of the segment, the parser sets XML-EVENT to END-OF-INPUT, sets
XML-CODE to zero, and transfers control to the processing procedure. The processing
procedure reads the next XML record into the parse data item, sets XML-CODE to
one, and returns to the parser.
The exchange between the processing procedure and the parser continues until the
READ statement returns the end-of-file status code. The processing procedure
returns to the parser with XML-CODE still set to zero to indicate the end of segment
processing.
Identification division.
Program-id. PARSESEG.
Environment division.
Input-output section.
File-control.
Select Input-XML
Assign to infile
File status is Input-XML-status.
Data division.
File section.
FD Input-XML
Record is varying from 1 to 255 depending on Rec-length
Recording mode V.
1 fdrec.
2 pic X occurs 1 to 255 depending on Rec-length .
Working-storage section.
556 Enterprise COBOL for z/OS, V5.2 Programming Guide
1 Event-number comp pic 99.
1 Rec-length comp-5 pic 9(4).
1 Input-XML-status pic 99.
Procedure division.
Open input Input-XML
If Input-XML-status not = 0
Display Open failed, file status: Input-XML-status
Goback
End-if
Read Input-XML
If Input-XML-status not = 0
Display Read failed, file status: Input-XML-status
Goback
End-if
Move 0 to Event-number
Display Starting with: fdrec
Display Event number and name Content of XML-text
XML parse fdrec processing procedure Handle-parse-events
Close Input-XML
Goback
.
Handle-parse-events.
Add 1 to Event-number
Display Event-number : XML-event { XML-text }
Evaluate XML-event
When END-OF-INPUT
Read Input-XML
Evaluate Input-XML-status
When 0
Move 1 to XML-code
Display Continuing with: fdrec
When 10
Display At EOF; no more input.
When other
Display Read failed, file status: Input-XML-status
Goback
End-evaluate
When other
Continue
End-evaluate
.
End program PARSESEG.
Results from parsing
To show parsing results, the processing procedure displayed each record of input,
followed by the sequence of XML events and any associated text fragments in
XML-TEXT. The content of XML-TEXT is displayed in braces ({}); empty braces signify
that XML-TEXT is empty.
Notice the extra zero-length CONTENT-CHARACTERS XML event at event number 08.
(Such anomalies are typical when supplying XML text piecemeal.)
Starting with: <?xml version=1.0?>
Event number and name Content of XML-TEXT
01: START-OF-DOCUMENT {}
02: VERSION-INFORMATION {1.0}
03: END-OF-INPUT {}
Continuing with: <Tagline>
04: START-OF-ELEMENT {Tagline}
05: END-OF-INPUT {}
Continuing with: COBOL is the language of the future!
06: CONTENT-CHARACTERS {COBOL is the language of the future!}
07: END-OF-INPUT {}
Chapter 28. Processing XML input 557
Continuing with: </Tagline>
08: CONTENT-CHARACTERS {}
09: END-OF-ELEMENT {Tagline}
10: END-OF-DOCUMENT {}
For a detailed description of the XML events that were detected, see the related
reference about XML-EVENT.
RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
XML-EVENT (Enterprise COBOL Language Reference)
Example: parsing XML documents with validation
This example shows the parsing of several XML documents with validation against
a schema, and a processing procedure that captures the return code and reason
code that the parser generates after parsing each document. All of the XML
documents are well formed but not necessarily valid.
| The program must be compiled using the XMLPARSE(XMLSS) compiler option.
The example uses the schema that was described in the related concept about XML
schemas.
Assume that file item.xsd contains the schema in text format, and that the
preprocessed schema was generated in file item.osr by means of the following
z/OS UNIX command:
xsdosrg -v -o /u/HLQ/xml/item.osr /u/HLQ/xml/item.xsd
The example uses the XML-SCHEMA clause to associate the XML schema name schema
with the ddname ddschema. The following DD statement associates the ddname with
the external z/OS UNIX file that contains the schema:
//GO.DDSCHEMA DD PATH=/u/HLQ/xml/item.osr
Program ValidCk
Identification division.
Program-id. ValidCk.
Environment division.
Configuration section.
Special-names.
xml-schema schema is ddschema.
Data division.
Working-storage section.
1 xml-decode.
2 rtn comp Pic 9(2).
2 rsn comp-5 Pic 9(4).
1 hv pic x(16) value 0123456789ABCDEF.
1 T Pic 999 COMP.
1 xml-document-1.
2 pic x(52) value
<!--Valid: the "itemName" element can be omitted-->.
2 pic x(31) value <stockItem itemNumber="123-AB">.
2 pic x(36) value <quantityOnHand>1</quantityOnHand>.
2 pic x(12) value </stockItem>.
1 xml-document-2.
2 pic x(44)
value <!--Invalid: missing attribute itemNumber-->.
2 pic x(11) value <stockItem>.
2 pic x(30) value <itemName>No name</itemName>.
2 pic x(36) value <quantityOnHand>1</quantityOnHand>.
2 pic x(12) value </stockItem>.
558 Enterprise COBOL for z/OS, V5.2 Programming Guide
1 xml-document-3.
2 pic x(47)
value <!--Invalid: unexpected attribute warehouse-->.
2 pic x(46) value
<stockItem itemNumber="074-UN" warehouse="NJ">.
2 pic x(37) value <quantityOnHand>10</quantityOnHand>.
2 pic x(32) value <itemName>Not here!</itemName>.
2 pic x(12) value </stockItem>.
1 xml-document-4.
2 pic x(46)
value <!--Invalid: illegal attribute value 123-Ab-->.
2 pic x(31) value <stockItem itemNumber="123-Ab">.
2 pic x(33) value <itemName>Paintbrush</itemName>.
2 pic x(37) value <quantityOnHand>10</quantityOnHand>.
2 pic x(12) value </stockItem>.
1 xml-document-5.
2 pic x(46)
value <!--Invalid: missing element quantityOnHand-->.
2 pic x(31) value <stockItem itemNumber="074-UN">.
2 pic x(32) value <itemName>Not here!</itemName>.
2 pic x(12) value </stockItem>.
1 xml-document-6.
2 pic x(42)
value <!--Invalid: unexpected element comment-->.
2 pic x(31) value <stockItem itemNumber="123-AB">.
2 pic x(33) value <itemName>Paintbrush</itemName>.
2 pic x(36) value <quantityOnHand>1</quantityOnHand>.
2 pic x(35) value <comment>Nylon bristles</comment>.
2 pic x(12) value </stockItem>.
1 xml-document-7.
2 pic x(46) value
<!--Invalid: out-of-range element value 100-->.
2 pic x(31) value <stockItem itemNumber="123-AB">.
2 pic x(33) value <itemName>Paintbrush</itemName>.
2 pic x(38) value <quantityOnHand>100</quantityOnHand>.
2 pic x(12) value </stockItem>.
Procedure division.
m.
xml parse xml-document-1 validating with file schema
processing procedure p
xml parse xml-document-2 validating with file schema
processing procedure p
xml parse xml-document-3 validating with file schema
processing procedure p
xml parse xml-document-4 validating with file schema
processing procedure p
xml parse xml-document-5 validating with file schema
processing procedure p
xml parse xml-document-6 validating with file schema
processing procedure p
xml parse xml-document-7 validating with file schema
processing procedure p
goback
.
p.
evaluate xml-event
when COMMENT
display
display xml-text
when END-OF-DOCUMENT
display Document successfully parsed.
when EXCEPTION
move xml-code to xml-decode
Divide rsn by 16 giving tally remainder T
display RC= rtn , reason=x
hv(function mod(rsn / 4096 16) + 1:1)
hv(function mod(rsn / 256 16) + 1:1)
Chapter 28. Processing XML input 559
hv(function mod(rsn / 16 16) + 1:1)
hv(T + 1:1)
end-evaluate
.
End program ValidCk.
Output from program ValidCk
In the following output, you can see which XML documents in the source program
failed validation against the schema.
For those documents that were not valid, the parser signaled an XML exception
and passed control to the processing procedure with special register XML-EVENT
containing 'EXCEPTION' and special-register XML-CODE containing the return code and
a specific reason code.
Valid: the "itemName" element can be omitted
Document successfully parsed.
Invalid: missing attribute itemNumber
RC=24, reason=x8613
Invalid: unexpected attribute warehouse
RC=24, reason=x8612
Invalid: illegal attribute value 123-Ab
RC=24, reason=x8809
Invalid: missing element quantityOnHand
RC=24, reason=x8611
Invalid: unexpected element comment
RC=24, reason=x8607
Invalid: out-of-range element value 100
RC=24, reason=x8803
RELATED CONCEPTS
XML-CODE on page 525
XML schemas on page 532
RELATED TASKS
Parsing XML documents with validation on page 530
Handling XML PARSE exceptions on page 542
RELATED REFERENCES
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect on page 691
560 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 29. Producing XML output
You can produce XML output from a COBOL program by using the XML GENERATE
statement.
In the XML GENERATE statement, you identify the source and the output data items.
You can optionally also identify:
v A field to receive a count of the XML characters generated
v A code page in which the generated XML document is to be encoded
v A namespace for the generated document
v A namespace prefix to qualify the start and end tag of each element, if you
specify a namespace
v A user-defined element or attribute name in the generated XML document
v Attributes or elements to be suppressed according to some specified conditions
v Particular items to be specified as attributes, elements or content in the
generated XML output.
v A statement to receive control if an exception occurs
Optionally, you can generate an XML declaration for the document, and can cause
eligible source data items to be expressed as attributes in the output rather than as
elements.
You can use the XML-CODE special register to determine the status of XML
generation.
After you transform COBOL data items to XML, you can use the resulting XML
output in various ways, such as deploying it in a web service, passing it as a
message to WebSphere MQ, or transmitting it for subsequent conversion to a CICS
communication area.
Link-edit considerations: COBOL programs that contain the XML GENERATE
statement must be link-edited with AMODE 31.
RELATED TASKS
Generating XML output
Controlling the encoding of generated XML output on page 566
Handling XML GENERATE exceptions on page 567
Enhancing XML output on page 573
RELATED REFERENCES
Extensible Markup Language (XML)
XML GENERATE statement (Enterprise COBOL Language Reference)
Generating XML output
To transform COBOL data to XML, use the XML GENERATE statement as in the
example below.
XML GENERATE XML-OUTPUT FROM SOURCE-REC
COUNT IN XML-CHAR-COUNT
ON EXCEPTION
DISPLAY XML generation error XML-CODE
Copyright IBM Corp. 1991, 2015 561
STOP RUN
NOT ON EXCEPTION
DISPLAY XML document was successfully generated.
END-XML
In the XML GENERATE statement, you first identify the data item (XML-OUTPUT in the
example above) that is to receive the XML output. Define the data item to be large
enough to contain the generated XML output, typically five to 10 times the size of
the COBOL source data depending on the length of its data-name or data-names.
| In the DATA DIVISION, you can define the receiving identifier as alphanumeric
(either an alphanumeric group item or an elementary item of category
alphanumeric) or as national (either a national group item or an elementary item
of category national).
Next you identify the source data item that is to be transformed to XML format
(SOURCE-REC in the example). The source data item can be an alphanumeric group
item, national group item, or elementary data item of class alphanumeric or
national.
Some COBOL data items are not transformed to XML, but are ignored. Subordinate
data items of an alphanumeric group item or national group item that you
transform to XML are ignored if they:
v Specify the REDEFINES clause, or are subordinate to such a redefining item
v Specify the RENAMES clause
These items in the source data item are also ignored when you generate XML:
v Elementary FILLER (or unnamed) data items
v Slack bytes inserted for SYNCHRONIZED data items
No extra white space (for example, new lines or indentation) is inserted to make
the generated XML more readable.
Optionally, you can code the COUNT IN phrase to obtain the number of XML
character encoding units that are filled during generation of the XML output. If the
receiving identifier has category national, the count is in UTF-16 character
encoding units. For all other encodings (including UTF-8), the count is in bytes.
You can use the count field as a reference modification length to obtain only that
portion of the receiving data item that contains the generated XML output. For
example, XML-OUTPUT(1:XML-CHAR-COUNT) references the first XML-CHAR-COUNT
character positions of XML-OUTPUT.
Consider the following program excerpt:
01 doc pic x(512).
01 docSize pic 9(9) binary.
01 G.
05 A pic x(3) value "aaa".
05 B.
10 C pic x(3) value "ccc".
10 D pic x(3) value "ddd".
05 E pic x(3) value "eee".
. . .
XML Generate Doc from G
562 Enterprise COBOL for z/OS, V5.2 Programming Guide
The code above generates the following XML document, in which A, B, and E are
expressed as child elements of element G, and C and D become child elements of
element B:
<G><A>aaa</A><B><C>ccc</C><D>ddd</D></B><E>eee</E></G>
Alternatively, you can specify the ATTRIBUTES phrase of the XML GENERATE
| statement. The ATTRIBUTES phrase causes every eligible data item included in the
| generated XML document to be expressed as an attribute of the containing XML
| element, rather than as a child element of the containing XML element. To be
| eligible, the data item must be elementary, must have a name other than FILLER,
| and must not have an OCCURS clause in its data description entry. The containing
| XML element corresponds to the group data item that is immediately
| superordinate to the elementary data item. Optionally, you can specify more
| precise control of which data items should be expressed as attributes or elements
| by using the TYPE OF phrase.
For example, suppose that the XML GENERATE statement in the program excerpt
above had instead been coded as follows:
XML Generate Doc from G with attributes
The code would then generate the following XML document, in which A and E are
expressed as attributes of element G, and C and D become attributes of element B:
<G A="aaa" E="eee"><B C="ccc" D="ddd"></B></G>
Optionally, you can code the ENCODING phrase of the XML GENERATE statement to
specify the CCSID of the generated XML document. If you do not use the ENCODING
phrase, the document encoding is determined by the category of the receiving data
item and by the CODEPAGE compiler option. For further details, see the related task
below about controlling the encoding of generated XML output.
Optionally, you can code the XML-DECLARATION phrase to cause the generated XML
document to have an XML declaration that includes version information and an
encoding declaration. If the receiving data item is of category:
v National: The encoding declaration has the value UTF-16 (encoding="UTF-16").
v 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.
For example, the program excerpt below specifies the XML-DECLARATION phrase of
XML GENERATE, and specifies encoding with CCSID 1208 (UTF-8):
01 Greeting.
05 msg pic x(80) value Hello, world!.
. . .
XML Generate Doc from Greeting
with Encoding 1208
with XML-declaration
End-XML
The code above generates the following XML document:
<?xml version="1.0" encoding="UTF-8"?><Greeting><msg>Hello, world!</msg></Greeting>
If you do not code the XML-DECLARATION phrase, an XML declaration is not
generated.
Optionally, you can code the NAMESPACE phrase to specify a namespace for the
generated XML document. The namespace value must be a valid Uniform Resource
Chapter 29. Producing XML output 563
Identifier (URI), for example, a URL (Uniform Resource Locator); for further details,
see the related concept about URI syntax below.
Specify the namespace in an identifier or literal of either category national or
alphanumeric.
If you specify a namespace, but do not specify a namespace prefix (described
below), the namespace becomes the default namespace for the document. That is, the
| namespace define on the root element applies by default to each element name in
the document, including the root element.
For example, consider the following data definitions and XML GENERATE statement:
01 Greeting.
05 msg pic x(80) value Hello, world!.
01 NS pic x(20) value http://example.
. . .
XML Generate Doc from Greeting
namespace is NS
The resulting XML document has a default namespace (http://example), as
follows:
<Greeting xmlns="http://example"><msg>Hello, world!</msg></Greeting>
If you do not specify a namespace, the element names in the generated XML
document are not in any namespace.
Optionally, you can code the NAMESPACE-PREFIX phrase to specify a prefix to be
applied to the start and end tag of each element in the generated document. You
can specify a prefix only if you have specified a namespace as described above.
When the XML GENERATE statement is executed, the prefix value must be a valid
XML name, but without the colon (:); see the related reference below about
namespaces for details. The value can have trailing spaces, which are removed
before the prefix is used.
Specify the namespace prefix in an identifier or literal of either category national or
alphanumeric.
It is recommended that the prefix be short, because it qualifies the start and end
tag of each element.
For example, consider the following data definitions and XML GENERATE statement:
01 Greeting.
05 msg pic x(80) value Hello, world!.
01 NS pic x(20) value http://example.
01 NP pic x(5) value pre.
. . .
XML Generate Doc from Greeting
namespace is NS
namespace-prefix is NP
The resulting XML document has an explicit namespace (http://example), and the
prefix pre is applied to the start and end tag of the elements Greeting and msg, as
follows:
<pre:Greeting xmlns:pre="http://example"><pre:msg>Hello, world!</pre:msg></pre:Greeting>
564 Enterprise COBOL for z/OS, V5.2 Programming Guide
Optionally, you can code the NAME phrase to specify attribute and element names in
the generated XML document. The attribute and element names must be
alphanumeric or national literals and must be legal names according to the XML
1.0 standard.
For example, consider the following data structure and XML GENERATE statement:
| 01 Msg.
02 Msg-Severity pic 9 value 1.
02 Msg-Date pic 9999/99/99 value "2012/04/12".
02 Msg-Text pic X(50) value "Sell everything!".
| 01 Doc pic X(500).
XML Generate Doc from Msg
With attributes
Name of Msg is "Message"
Msg-Severity is "Severity"
Msg-Date is "Date"
Msg-Text is "Text"
| End-XML
The resulting XML document is as follows:
<Message Severity="1" Date="2012/04/12" Text="Sell everything!"></Message>
Optionally, you can code the SUPPRESS phrase to specify whether individual data
items are generated based on whether or not they meet certain criteria.
For example, consider the following data structure and XML GENERATE statement to
suppress spaces and zeros:
| 01 G.
| 02 SensitiveInfo.
| 03 SSN pic x(11) value 123-45-6789.
| 03 HomeAddress pic x(50) value 123 Main St, Anytown, USA.
| 02 Aarray value spaces.
| 03 A pic AAA occurs 5.
| 02 Barray value spaces.
| 03 B pic XXX occurs 5.
| 02 Carray value zeros.
| 03 C pic 999 occurs 5.
| Move abc to A(1)
| Move 123 to C(3)
| XML Generate Doc from G
| Suppress SensitiveInfo
| every nonnumeric element when space
| every numeric element when zero
| End-XML
The resulting XML document is as follows:
<G>
<Aarray><A>abc</A></Aarray>
<Carray><C>123</C></Carray>
</G>
| Optionally, you can use the TYPE OF phrase to specify whether individual data
items are expressed as attributes, elements or content.
For example, consider the following data structure and XML GENERATE statement:
| 01 Msg.
02 Msg-Severity pic 9 value 1.
02 Msg-Date pic 9999/99/99 value "2012/04/12".
02 Msg-Text pic X(50) value "Sell everything!".
| 01 Doc pic X(500).
XML Generate Doc from Msg
With attributes
Chapter 29. Producing XML output 565
Type of Msg-Severity is attribute
Msg-Date is attribute
Msg-Text is element
| End-XML
The resulting XML document is as follows:
<Msg Msg-Severity="1" Msg-Date="2012/04/12">
<Msg-Text>Sell everything!</Msg-Text></Msg>
In addition, you can specify either or both of the following phrases to receive
control after generation of the XML document:
v ON EXCEPTION, to receive control if an error occurs during XML generation
v NOT ON EXCEPTION, to receive control if no error occurs
You can end the XML GENERATE statement with the explicit scope terminator
END-XML. Code END-XML to nest an XML GENERATE statement that has the ON
EXCEPTION or NOT ON EXCEPTION phrase in a conditional statement.
XML generation continues until either the COBOL source record has been
transformed to XML or an error occurs. If an error occurs, the results are as
follows:
v The XML-CODE special register contains a nonzero exception code.
v Control is passed to the ON EXCEPTION phrase, if specified, otherwise to the end
of the XML GENERATE statement.
If no error occurs during XML generation, the XML-CODE special register contains
zero, and control is passed to the NOT ON EXCEPTION phrase if specified or to the
end of the XML GENERATE statement otherwise.
Example: generating XML on page 568
RELATED CONCEPTS
Uniform Resource Identifier (URI): Generic Syntax
RELATED TASKS
Controlling the encoding of generated XML output
Handling XML GENERATE exceptions on page 567
Processing UTF-8 data on page 141
RELATED REFERENCES
XML GENERATE statement (Enterprise COBOL Language Reference)
Extensible Markup Language (XML)
Namespaces in XML 1.0
Controlling the encoding of generated XML output
When you generate XML output by using the XML GENERATE statement, you can
control the encoding of the output by the category of the data item that receives
the output, and by identifying the code page using the WITH ENCODING phrase of
the XML GENERATE statement.
If you specify the WITH ENCODING codepage phrase to designate the coded character
set identifier (CCSID) of the output document, codepage must specify an unsigned
integer data item or unsigned integer literal that identifies one of the code pages
supported for COBOL XML processing as described in the related reference below
about the encoding of XML documents:
566 Enterprise COBOL for z/OS, V5.2 Programming Guide
v If the data item that receives the generated XML is of category national, the WITH
ENCODING phrase must specify 1200, the CCSID for Unicode UTF-16.
v If the receiving identifier is of category alphanumeric, the WITH ENCODING phrase
must specify CCSID 1208 or the CCSID of a supported EBCDIC code page.
If you do not code the WITH ENCODING phrase, the generated XML output is
encoded as shown in the table below.
Table 74. Encoding of generated XML if the ENCODING phrase is omitted
If you define the receiving XML
identifier as: The generated XML output is encoded in:
Alphanumeric The code page specified by the CODEPAGE
compiler option in effect when the source was
compiled
National UTF-16 big-endian (UTF-16BE, CCSID 1200)
A byte order mark is not generated.
For details about how data items are converted to XML and how the XML element
names and attributes names are formed from the COBOL data-names, see the
related reference below about the operation of the XML GENERATE statement.
RELATED REFERENCES
CODEPAGE on page 313
The encoding of XML documents on page 536
XML GENERATE statement (Enterprise COBOL Language Reference)
Operation of XML GENERATE (Enterprise COBOL Language Reference)
Handling XML GENERATE exceptions
When an error is detected during generation of XML output, an exception
condition exists. You can write code to check the XML-CODE special register, which
contains a numeric exception code that indicates the error type.
To handle errors, use either or both of the following phrases of the XML GENERATE
statement:
v ON EXCEPTION
v COUNT IN
If you code the ON EXCEPTION phrase in the XML GENERATE statement, control is
transferred to the imperative statement that you specify. You might code an
imperative statement, for example, to display the XML-CODE value. If you do not
code an ON EXCEPTION phrase, control is transferred to the end of the XML GENERATE
statement.
When an error occurs, one problem might be that the data item that receives the
XML output is not large enough. In that case, the XML output is not complete, and
the XML-CODE special register contains error code 400.
You can examine the generated XML output by doing these steps:
1. Code the COUNT IN phrase in the XML GENERATE statement.
The count field that you specify holds a count of the XML character encoding
units that are filled during XML generation. If you define the XML output as
Chapter 29. Producing XML output 567
national, the count is in UTF-16 character encoding units; for all other
encodings (including for UTF-8), the count is in bytes.
2. Use the count field as a reference modification length to refer to the substring
of the receiving data item that contains the XML characters that were generated
until the point when the error occurred.
For example, if XML-OUTPUT is the data item that receives the XML output, and
XML-CHAR-COUNT is the count field, then XML-OUTPUT(1:XML-CHAR-COUNT)
references the XML output.
Use the contents of XML-CODE to determine what corrective action to take. For a list
of the exceptions that can occur during XML generation, see the related reference
below.
RELATED TASKS
Referring to substrings of data items on page 111
RELATED REFERENCES
XML GENERATE exceptions on page 700
XML-CODE (Enterprise COBOL Language Reference)
Example: generating XML
The following example simulates the building of a purchase order in a group data
item, and generates an XML version of that purchase order.
Program XGFX uses XML GENERATE to produce XML output in elementary data item
xmlPO from the source record, group data item purchaseOrder. Elementary data
items in the source record are converted to character format as necessary, and the
characters are inserted as the values of XML attributes whose names are derived
from the data-names in the source record.
XGFX calls program Pretty, which uses the XML PARSE statement with processing
procedure p to format the XML output with new lines and indentation so that the
XML content can more easily be verified.
Program XGFX
Identification division.
Program-id. XGFX.
Data division.
Working-storage section.
01 numItems pic 99 global.
01 purchaseOrder global.
05 orderDate pic x(10).
05 shipTo.
10 country pic xx value US.
10 name pic x(30).
10 street pic x(30).
10 city pic x(30).
10 state pic xx.
10 zip pic x(10).
05 billTo.
10 country pic xx value US.
10 name pic x(30).
10 street pic x(30).
10 city pic x(30).
10 state pic xx.
10 zip pic x(10).
05 orderComment pic x(80).
05 items occurs 0 to 20 times depending on numItems.
568 Enterprise COBOL for z/OS, V5.2 Programming Guide
10 item.
15 partNum pic x(6).
15 productName pic x(50).
15 quantity pic 99.
15 USPrice pic 999v99.
15 shipDate pic x(10).
15 itemComment pic x(40).
01 numChars comp pic 999.
01 xmlPO pic x(999).
Procedure division.
m.
Move 20 to numItems
Move spaces to purchaseOrder
Move 1999-10-20 to orderDate
Move US to country of shipTo
Move Alice Smith to name of shipTo
Move 123 Maple Street to street of shipTo
Move Mill Valley to city of shipTo
Move CA to state of shipTo
Move 90952 to zip of shipTo
Move US to country of billTo
Move Robert Smith to name of billTo
Move 8 Oak Avenue to street of billTo
Move Old Town to city of billTo
Move PA to state of billTo
Move 95819 to zip of billTo
Move Hurry, my lawn is going wild! to orderComment
Move 0 to numItems
Call addFirstItem
Call addSecondItem
Move space to xmlPO
Xml generate xmlPO from purchaseOrder count in numChars
with xml-declaration with attributes
namespace http://www.example.com namespace-prefix po
Call pretty using xmlPO value numChars
Goback
.
Identification division.
Program-id. addFirstItem.
Procedure division.
Add 1 to numItems
Move 872-AA to partNum(numItems)
Move Lawnmower to productName(numItems)
Move 1 to quantity(numItems)
Move 148.95 to USPrice(numItems)
Move Confirm this is electric to itemComment(numItems)
Goback.
End program addFirstItem.
Identification division.
Program-id. addSecondItem.
Procedure division.
Add 1 to numItems
Move 926-AA to partNum(numItems)
Move Baby Monitor to productName(numItems)
Move 1 to quantity(numItems)
Move 39.98 to USPrice(numItems)
Move 1999-05-21 to shipDate(numItems)
Goback.
End program addSecondItem.
End program XGFX.
Chapter 29. Producing XML output 569
Program Pretty
| Process xmlparse(xmlss), codepage(37)
Identification division.
Program-id. Pretty.
Data division.
Working-storage section.
01 prettyPrint.
05 pose pic 999.
05 posd pic 999.
05 depth pic 99.
05 inx pic 999.
05 elementName pic x(30).
05 indent pic x(40).
05 buffer pic x(998).
05 lastitem pic 9.
88 unknown value 0.
88 xml-declaration value 1.
88 element value 2.
88 attribute value 3.
88 charcontent value 4.
Linkage section.
1 doc.
2 pic x occurs 16384 times depending on len.
1 len comp-5 pic 9(9).
Procedure division using doc value len.
m.
Move space to prettyPrint
Move 0 to depth
Move 1 to posd pose
Xml parse doc processing procedure p
Goback
.
p.
Evaluate xml-event
When VERSION-INFORMATION
String <?xml version=" xml-text " delimited by size
into buffer with pointer posd
Set xml-declaration to true
When ENCODING-DECLARATION
String encoding=" xml-text " delimited by size
into buffer with pointer posd
When STANDALONE-DECLARATION
String standalone=" xml-text " delimited by size
into buffer with pointer posd
When START-OF-ELEMENT
Evaluate true
When xml-declaration
String ?> delimited by size into buffer
with pointer posd
Set unknown to true
Perform printline
Move 1 to posd
When element
String > delimited by size into buffer
with pointer posd
When attribute
String "> delimited by size into buffer
with pointer posd
End-evaluate
If elementName not = space
Perform printline
End-if
Move xml-text to elementName
Add 1 to depth
Move 1 to pose
Set element to true
570 Enterprise COBOL for z/OS, V5.2 Programming Guide
If xml-namespace-prefix = space
String < xml-text delimited by size
into buffer with pointer pose
Else
String < xml-namespace-prefix : xml-text
delimited by size into buffer with pointer pose
End-if
Move pose to posd
When ATTRIBUTE-NAME
If element
String delimited by size into buffer
with pointer posd
Else
String " delimited by size into buffer
with pointer posd
End-if
If xml-namespace-prefix = space
String xml-text =" delimited by size into buffer
with pointer posd
Else
String xml-namespace-prefix : xml-text ="
delimited by size into buffer with pointer posd
End-if
Set attribute to true
When NAMESPACE-DECLARATION
If element
String delimited by size into buffer
with pointer posd
Else
String " delimited by size into buffer
with pointer posd
End-if
If xml-namespace-prefix = space
String xmlns=" xml-namespace delimited by size
into buffer with pointer posd
Else
String xmlns: xml-namespace-prefix =" xml-namespace
delimited by size into buffer with pointer posd
End-if
Set attribute to true
When ATTRIBUTE-CHARACTERS
String xml-text delimited by size into buffer
with pointer posd
When ATTRIBUTE-CHARACTER
String xml-text delimited by size into buffer
with pointer posd
When CONTENT-CHARACTERS
Evaluate true
When element
String > delimited by size into buffer
with pointer posd
When attribute
String "> delimited by size into buffer
with pointer posd
End-evaluate
String xml-text delimited by size into buffer
with pointer posd
Set charcontent to true
When CONTENT-CHARACTER
Evaluate true
When element
String > delimited by size into buffer
with pointer posd
When attribute
String "> delimited by size into buffer
with pointer posd
End-evaluate
Chapter 29. Producing XML output 571
String xml-text delimited by size into buffer
with pointer posd
Set charcontent to true
When END-OF-ELEMENT
Move space to elementName
Evaluate true
When element
String /> delimited by size into buffer
with pointer posd
When attribute
String "/> delimited by size into buffer
with pointer posd
When other
If xml-namespace-prefix = space
String </ xml-text > delimited by size
into buffer with pointer posd
Else
String </ xml-namespace-prefix : xml-text >
delimited by size into buffer with pointer posd
End-if
End-evaluate
Set unknown to true
Perform printline
Subtract 1 from depth
Move 1 to posd
When other
Continue
End-evaluate
.
printline.
Compute inx = function max(0 2 * depth - 2) + posd - 1
If inx > 120
compute inx = 117 - function max(0 2 * depth - 2)
If depth > 1
Display indent(1:2 * depth - 2) buffer(1:inx) ...
Else
Display buffer(1:inx) ...
End-if
Else
If depth > 1
Display indent(1:2 * depth - 2) buffer(1:posd - 1)
Else
Display buffer(1:posd - 1)
End-if
End-if
.
End program Pretty.
Output from program XGFX
<?xml version="1.0" encoding="IBM-037"?>
<po:purchaseOrder xmlns:po="http://www.example.com" orderDate="1999-10-20" orderComment="Hurry, my lawn is going wild!">
<po:shipTo country="US" name="Alice Smith" street="123 Maple Street" city="Mill Valley" state="CA" zip="90952"/>
<po:billTo country="US" name="Robert Smith" street="8 Oak Avenue" city="Old Town" state="PA" zip="95819"/>
<po:items>
<po:item partNum="872-AA" productName="Lawnmower" quantity="1" USPrice="148.95" shipDate=" " itemComment="Confirm...
</po:items>
<po:items>
<po:item partNum="926-AA" productName="Baby Monitor" quantity="1" USPrice="39.98" shipDate="1999-05-21" itemComme...
</po:items>
</po:purchaseOrder>
RELATED TASKS
Chapter 28, Processing XML input, on page 517
572 Enterprise COBOL for z/OS, V5.2 Programming Guide
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
Operation of XML GENERATE (Enterprise COBOL Language Reference)
Enhancing XML output
It might happen that the information that you want to express in XML format
already exists in a group item in the DATA DIVISION, but you are unable to use that
item directly to generate an XML document because of one or more factors.
For example:
v In addition to the required data, the item has subordinate data items that
contain values that are irrelevant to the XML output document.
v The names of the required data items are unsuitable for external presentation,
and are possibly meaningful only to programmers.
v The required data items are broken up into too many components, and should
be output as the content of the containing group.
There are various ways that you can deal with such situations. One possible
technique is to define a new data item that has the appropriate characteristics, and
move the required data to the appropriate fields of this new data item. However,
this approach is somewhat laborious and requires careful maintenance to keep the
original and new data items synchronized.
A superior approach that addresses most such problems is to use the new optional
phrases of the XML GENERATE statement in order to:
v Provide more meaningful and appropriate names for the selected elementary
items and for the group items that contain them.
v Exclude irrelevant data items from the generated XML by suppressing them
based on their values.
The example that is referenced below shows a way to do so.
Example: enhancing XML output
RELATED REFERENCES
Operation of XML GENERATE (Enterprise COBOL Language Reference)
Example: enhancing XML output
The following example shows how you can modify XML output.
Consider the following data structure. The XML that is generated from the
structure suffers from several problems that can be corrected.
01 CDR-LIFE-BASE-VALUES-BOX.
15 CDR-LIFE-BASE-VAL-DATE PIC X(08).
15 CDR-LIFE-BASE-VALUE-LINE OCCURS 2 TIMES.
20 CDR-LIFE-BASE-DESC.
25 CDR-LIFE-BASE-DESC1 PIC X(15).
25 FILLER PIC X(01).
25 CDR-LIFE-BASE-LIT PIC X(08).
25 CDR-LIFE-BASE-DTE PIC X(08).
20 CDR-LIFE-BASE-PRICE.
25 CDR-LIFE-BP-SPACE PIC 9(08).
25 CDR-LIFE-BP-DASH PIC X.
25 CDR-LIFE-BP-SPACE1 PIC X(02).
20 CDR-LIFE-BASE-PRICE-ED REDEFINES
Chapter 29. Producing XML output 573
CDR-LIFE-BASE-PRICE PIC $$$.$$.
20 CDR-LIFE-BASE-QTY.
25 CDR-LIFE-QTY-SPACE PIC X(08).
25 CDR-LIFE-QTY-DASH PIC X.
25 CDR-LIFE-QTY-SPACE1 PIC X(03).
25 FILLER PIC X(02).
20 CDR-LIFE-BASE-VALUE PIC $$$9.99
BLANK WHEN ZERO.
15 CDR-LIFE-BASE-TOT-VALUE PIC X(15)
When this data structure is populated with some sample values, and XML is
generated directly from it and then formatted using program Pretty (shown in
Example: generating XML on page 568), the result is as follows:
<CDR-LIFE-BASE-VALUES-BOX>
<CDR-LIFE-BASE-VAL-DATE>01/02/03</CDR-LIFE-BASE-VAL-DATE>
<CDR-LIFE-BASE-VALUE-LINE>
<CDR-LIFE-BASE-DESC>
<CDR-LIFE-BASE-DESC1>First</CDR-LIFE-BASE-DESC1>
<CDR-LIFE-BASE-LIT> </CDR-LIFE-BASE-LIT>
<CDR-LIFE-BASE-DTE>01/01/01</CDR-LIFE-BASE-DTE>
</CDR-LIFE-BASE-DESC>
<CDR-LIFE-BASE-PRICE>
<CDR-LIFE-BP-SPACE>23</CDR-LIFE-BP-SPACE>
<CDR-LIFE-BP-DASH>.</CDR-LIFE-BP-DASH>
<CDR-LIFE-BP-SPACE1>000</CDR-LIFE-BP-SPACE1>
</CDR-LIFE-BASE-PRICE>
<CDR-LIFE-BASE-QTY>
<CDR-LIFE-QTY-SPACE>123</CDR-LIFE-QTY-SPACE>
<CDR-LIFE-QTY-DASH>.</CDR-LIFE-QTY-DASH>
<CDR-LIFE-QTY-SPACE1>000</CDR-LIFE-QTY-SPACE1>
</CDR-LIFE-BASE-QTY>
<CDR-LIFE-BASE-VALUE>$765.00</CDR-LIFE-BASE-VALUE>
</CDR-LIFE-BASE-VALUE-LINE>
<CDR-LIFE-BASE-VALUE-LINE>
<CDR-LIFE-BASE-DESC1>Second</CDR-LIFE-BASE-DESC1>
<CDR-LIFE-BASE-LIT> </CDR-LIFE-BASE-LIT>
<CDR-LIFE-BASE-DTE>02/02/02</CDR-LIFE-BASE-DTE>
<CDR-LIFE-BASE-PRICE>
<CDR-LIFE-BP-SPACE>34</CDR-LIFE-BP-SPACE>
<CDR-LIFE-BP-DASH>.</CDR-LIFE-BP-DASH>
<CDR-LIFE-BP-SPACE1>00</CDR-LIFE-BP-SPACE1>
</CDR-LIFE-BASE-PRICE>
<CDR-LIFE-BASE-QTY>
<CDR-LIFE-QTY-SPACE>234</CDR-LIFE-QTY-SPACE>
<CDR-LIFE-QTY-DASH>.</CDR-LIFE-QTY-DASH>
<CDR-LIFE-QTY-SPACE1>000</CDR-LIFE-QTY-SPACE1>
</CDR-LIFE-BASE-QTY>
<CDR-LIFE-BASE-VALUE>$654.00</CDR-LIFE-BASE-VALUE>
</CDR-LIFE-BASE-VALUE-LINE>
<CDR-LIFE-BASE-TOT-VALUE>Very high!</CDR-LIFE-BASE-TOT-VALUE>
</CDR-LIFE-BASE-TOT-VALUE-LINE>
</CDR-LIFE-BASE-VALUES-BOX>
This generated XML suffers from several problems:
v The element names are long and not very meaningful. There may also be an
XML schema that specifies required tag names.
v The XML schema may require some tag names that are COBOL reserved words
such as DATE/TIME
v Some fields that are elements should be attributes such as, CDR-LIFE-BASE-VAL-
DATE and CDR-LIFE-BASE-DESC1.
v There is unwanted data, for example, CDR-LIFE-BASE-LIT and
CDR-LIFE-BASE-DTE.
574 Enterprise COBOL for z/OS, V5.2 Programming Guide
v Other required fields are split into too many subcomponents. For example,
CDR-LIFE-BASE-PRICE has three subcomponents for one amount.
These and other characteristics of the XML output can be remedied by using
additional phrases of the XML GENERATE statement as follows:
v Use the NAME OF phrase to provide appropriate tag or attribute names.
v Use the TYPE OF ... IS ATTRIBUTE phrase to select the fields which should be
XML attributes rather than elements.
v Use the TYPE OF ... IS CONTENT phrase to suppress tags for excessive
subcomponents.
v Use the SUPPRESS ... WHEN phrase to exclude fields that contain uninteresting
values.
Here is an example of the XML GENERATE statement to address those problems:
XML generate Doc from CDR-LIFE-BASE-VALUES-BOX
Count in tally
Name of
CDR-LIFE-BASE-VALUES-BOX
is Base_Values
CDR-LIFE-BASE-VAL-DATE
is Date
CDR-LIFE-BASE-DTE
is Date
CDR-LIFE-BASE-VALUE-LINE
is BaseValueLine
CDR-LIFE-BASE-DESC1
is Description
CDR-LIFE-BASE-PRICE
is BasePrice
CDR-LIFE-BASE-QTY
is BaseQuantity
CDR-LIFE-BASE-VALUE
is BaseValue
CDR-LIFE-BASE-TOT-VALUE
is TotalValue
Type of
CDR-LIFE-BASE-VAL-DATE is attribute
CDR-LIFE-BASE-DESC1 is attribute
CDR-LIFE-BP-SPACE is content
CDR-LIFE-BP-DASH is content
CDR-LIFE-BP-SPACE1 is content
CDR-LIFE-QTY-SPACE is content
CDR-LIFE-QTY-DASH is content
CDR-LIFE-QTY-SPACE1 is content
Suppress every nonnumeric when space
every numeric when zero
The result of generating and formatting XML from the statement shown above is
more usable:
<Base_Values Date="01/02/03">
<BaseValueLine Description="First">
<Date>01/01/01</Date>
<BasePrice>23.00</BasePrice>
<BaseQuantity>123.000</BaseQuantity>
<BaseValue>$765.00</BaseValue>
</BaseValueLine>
<BaseValueLine Description="Second">
<Date>02/02/02</Date>
<BasePrice>34.00</BasePrice>
<BaseQuantity>234.000</BaseQuantity>
Chapter 29. Producing XML output 575
<BaseValue>$654.00</BaseValue>
</BaseValueLine>
<TotalValue>Very high!</TotalValue>
</Base_Values>
Note that the COBOL reserved word DATE can now be used as an XML tag name in
the output. Characters such as accented letters and period . that are illegal in
single-byte data names can also be used.
RELATED REFERENCES
Operation of XML GENERATE (Enterprise COBOL Language Reference)
REPLACE statement (Enterprise COBOL Language Reference)
576 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 6. Developing object-oriented programs
Copyright IBM Corp. 1991, 2015 577
578 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 30. Writing object-oriented programs
When you write an object-oriented (OO) program, you have to determine what
classes you need and the methods and data that the classes need to do their work.
OO programs are based on objects (entities that encapsulate state and behavior) and
their classes, methods, and data. A class is a template that defines the state and the
capabilities of an object. Usually a program creates and works with multiple object
instances (or simply, instances) of a class, that is, multiple objects that are members
of that class. The state of each instance is stored in data known as instance data,
and the capabilities of each instance are called instance methods. A class can define
data that is shared by all instances of the class, known as factory or static data, and
methods that are supported independently of any object instance, known as factory
or static methods.
Using Enterprise COBOL, you can:
v Define classes, with methods and data implemented in COBOL.
v Create instances of Java and COBOL classes.
v Invoke methods on Java and COBOL objects.
v Write classes that inherit from Java classes or other COBOL classes.
v Define and invoke overloaded methods.
In Enterprise COBOL programs, you can call the services provided by the Java
Native Interface (JNI) to obtain Java-oriented capabilities in addition to the basic
OO capabilities available directly in the COBOL language.
In Enterprise COBOL classes, you can code CALL statements to interface with
procedural COBOL programs. Thus COBOL class definition syntax can be
especially useful for writing wrapper classes for procedural COBOL logic, enabling
existing COBOL code to be accessed from Java.
Java code can create instances of COBOL classes, invoke methods of these classes,
and can extend COBOL classes.
It is recommended that you develop and run OO COBOL programs and Java
programs in the z/OS UNIX environment.
Restrictions:
v COBOL class definitions and methods cannot contain EXEC SQL statements and
cannot be compiled using the SQL compiler option.
v COBOL class definitions and methods cannot contain EXEC SQLIMS statements
and cannot be compiled using the SQLIMS compiler option.
v COBOL programs that use object-oriented syntax for Java interoperability cannot
contain EXEC CICS statements, and cannot be run in CICS. They cannot be
compiled using the CICS compiler option.
Example: accounts on page 580
RELATED TASKS
Defining a class on page 582
Defining a class instance method on page 587
Copyright IBM Corp. 1991, 2015 579
Defining a client on page 596
Defining a subclass on page 607
Defining a factory section on page 611
Chapter 16, Compiling, linking, and running OO applications, on page 291
Upgrading IBM COBOL source programs
(Enterprise COBOL Migration Guide)
RELATED REFERENCES
The Java Language Specification
Example: accounts
Consider the example of a bank in which customers can open accounts and make
deposits to and withdrawals from their accounts. You could represent an account
by a general-purpose class, called Account. Because there are many customers,
multiple instances of the Account class could exist simultaneously.
After you determine the classes that you need, the next step is to determine the
methods that the classes need to do their work. An Account class must provide the
following services:
v Open the account.
v Get the current balance.
v Deposit to the account.
v Withdraw from the account.
v Report account status.
The following methods for an Account class meet those needs:
init Open an account and assign it an account number.
getBalance
Return the current balance of the account.
credit Deposit a given sum to the account.
debit Withdraw a given sum from the account.
print Display account number and account balance.
As you design an Account class and its methods, you discover the need for the
class to keep some instance data. Typically, an Account object needs the following
instance data:
v Account number
v Account balance
v Customer information: name, address, home phone, work phone, social security
number, and so forth
To keep the example simple, however, it is assumed that the account number and
account balance are the only instance data that the Account class needs.
Diagrams are helpful when you design classes and methods. The following
diagram depicts a first attempt at a design of the Account class:
580 Enterprise COBOL for z/OS, V5.2 Programming Guide
The words in parentheses in the diagrams are the names of the instance data, and
the words that follow a number and colon are the names of the instance methods.
The structure below shows how the classes relate to each other, and is known as
the inheritance hierarchy. The Account class inherits directly from the class
java.lang.Object.
Subclasses
In the account example, Account is a general-purpose class. However, a bank could
have many different types of accounts: checking accounts, savings accounts,
mortgage loans, and so forth, all of which have all the general characteristics of
accounts but could have additional characteristics not shared by all types of
accounts.
For example, a CheckingAccount class could have, in addition to the account
number and account balance that all accounts have, a check fee that applies to each
check written on the account. A CheckingAccount class also needs a method to
process checks (that is, to read the amount, debit the payer, credit the payee, and
so forth). So it makes sense to define CheckingAccount as a subclass of Account,
and to define in the subclass the additional instance data and instance methods
that the subclass needs.
As you design the CheckingAccount class, you discover the need for a class that
models checks. An instance of class Check needs, at a minimum, instance data for
payer, payee, and the check amount.
Many additional classes (and database and transaction-processing logic) would
need to be designed in a real-world OO account system, but have been omitted to
keep the example simple. The updated inheritance diagram is shown below.
Chapter 30. Writing object-oriented programs 581
A number and colon with no method-name following them indicate that the
method with that number is inherited from the superclass.
Multiple inheritance: You cannot use multiple inheritance in OO COBOL
applications. All classes that you define must have exactly one parent, and
java.lang.Object must be at the root of every inheritance hierarchy. The class
structure of any object-oriented system defined in an OO COBOL application is
thus a tree.
Example: defining a method on page 594
RELATED TASKS
Defining a class
Defining a class instance method on page 587
Defining a subclass on page 607
Defining a class
A COBOL class definition consists of an IDENTIFICATION DIVISION and ENVIRONMENT
DIVISION, followed by an optional factory definition and optional object definition,
followed by an END CLASS marker.
Table 75. Structure of class definitions
Section Purpose Syntax
IDENTIFICATION Name the class. Provide CLASS-ID paragraph for defining a class
DIVISION inheritance information on page 584 (required)
(required) for it. AUTHOR paragraph (optional)
INSTALLATION paragraph (optional)
DATE-WRITTEN paragraph (optional)
DATE-COMPILED paragraph (optional)
582 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 75. Structure of class definitions (continued)
Section Purpose Syntax
ENVIRONMENT Describe the computing CONFIGURATION SECTION (required)
DIVISION environment. Relate REPOSITORY paragraph for defining a
(required) class-names used within class on page 584 (required)
the class definition to the SOURCE-COMPUTER paragraph (optional)
corresponding external OBJECT-COMPUTER paragraph (optional)
class-names known SPECIAL-NAMES paragraph (optional)
outside the compilation
unit.
Factory definition Define data to be shared IDENTIFICATION DIVISION.
(optional) by all instances of the FACTORY.
class, and methods DATA DIVISION.
supported independently WORKING-STORAGE SECTION.
of any object instance. * (Factory data here)
PROCEDURE DIVISION.
* (Factory methods here)
END FACTORY.
Object definition Define instance data and IDENTIFICATION DIVISION.
(optional) instance methods. OBJECT.
DATA DIVISION.
WORKING-STORAGE SECTION.
* (Instance data here)
PROCEDURE DIVISION.
* (Instance methods here)
END OBJECT.
If you specify the SOURCE-COMPUTER, OBJECT-COMPUTER, or SPECIAL-NAMES paragraphs
in a class CONFIGURATION SECTION, they apply to the entire class definition
including all methods that the class introduces.
A class CONFIGURATION SECTION can consist of the same entries as a program
CONFIGURATION SECTION, except that a class CONFIGURATION SECTION cannot contain
an INPUT-OUTPUT SECTION. You define an INPUT-OUTPUT SECTION only in the
individual methods that require it rather than defining it at the class level.
As shown above, you define instance data and methods in the DATA DIVISION and
PROCEDURE DIVISION, respectively, within the OBJECT paragraph of the class
definition. In classes that require data and methods that are to be associated with
the class itself rather than with individual object instances, define a separate DATA
DIVISION and PROCEDURE DIVISION within the FACTORY paragraph of the class
definition.
Each COBOL class definition must be in a separate source file.
Example: defining a class on page 587
RELATED TASKS
WORKING-STORAGE SECTION for defining class instance data on page 586
Defining a class instance method on page 587
Defining a subclass on page 607
Defining a factory section on page 611
Describing the computing environment on page 5
Chapter 16, Compiling, linking, and running OO applications, on page 291
Chapter 30. Writing object-oriented programs 583
RELATED REFERENCES
COBOL class definition structure (Enterprise COBOL Language Reference)
CLASS-ID paragraph for defining a class
Use the CLASS-ID paragraph in the IDENTIFICATION DIVISION to name a class and
provide inheritance information for it.
Identification Division. Required
Class-id. Account inherits Base. Required
Use the CLASS-ID paragraph to identify these classes:
v The class that you are defining (Account in the example above).
v The immediate superclass from which the class that you are defining inherits its
characteristics. The superclass can be implemented in Java or COBOL.
In the example above, inherits Base indicates that the Account class inherits
methods and data from the class known within the class definition as Base. It is
recommended that you use the name Base in your OO COBOL programs to refer
to java.lang.Object.
A class-name must use single-byte characters and must conform to the normal
rules of formation for a COBOL user-defined word.
Use the REPOSITORY paragraph in the CONFIGURATION SECTION of the ENVIRONMENT
DIVISION to associate the superclass name (Base in the example) with the name of
the superclass as it is known externally (java.lang.Object for Base). You can
optionally also specify the name of the class that you are defining (Account in the
example) in the REPOSITORY paragraph and associate it with its corresponding
external class-name.
You must derive all classes directly or indirectly from the java.lang.Object class.
RELATED TASKS
REPOSITORY paragraph for defining a class
RELATED REFERENCES
CLASS-ID paragraph (Enterprise COBOL Language Reference)
User-defined words (Enterprise COBOL Language Reference)
REPOSITORY paragraph for defining a class
Use the REPOSITORY paragraph to declare to the compiler that the specified words
are class-names when you use them within a class definition, and to optionally
relate the class-names to the corresponding external class-names (the class-names
as they are known outside the compilation unit).
External class-names are case sensitive and must conform to Java rules of
formation. For example, in the Account class definition you might code this:
Environment Division. Required
Configuration Section. Required
Repository. Required
Class Base is "java.lang.Object" Required
Class Account is "Account". Optional
The REPOSITORY paragraph entries indicate that the external class-names of the
classes referred to as Base and Account within the class definition are
java.lang.Object and Account, respectively.
584 Enterprise COBOL for z/OS, V5.2 Programming Guide
In the REPOSITORY paragraph, you must code an entry for each class-name that you
explicitly reference in the class definition. For example:
v Base
v A superclass from which the class that you are defining inherits
v The classes that you reference in methods within the class definition
In a REPOSITORY paragraph entry, you must specify the external class-name if the
name contains non-COBOL characters. You must also specify the external
class-name for any referenced class that is part of a Java package. For such a class,
specify the external class-name as the fully qualified name of the package,
followed by period (.), followed by the simple name of the Java class. For
example, the Object class is part of the java.lang package, so specify its external
name as java.lang.Object as shown above.
An external class-name that you specify in the REPOSITORY paragraph must be an
alphanumeric literal that conforms to the rules of formation for a fully qualified
Java class-name.
If you do not include the external class-name in a REPOSITORY paragraph entry, the
external class-name is formed from the class-name in the following manner:
v The class-name is converted to uppercase.
v Each hyphen is changed to zero.
v The first character, if a digit, is changed:
1-9 are changed to A-I.
0 is changed to J.
v Underscores are not changed.
In the example above, class Account is known externally as Account (in mixed
case) because the external name is spelled using mixed case.
You can optionally include in the REPOSITORY paragraph an entry for the class that
you are defining (Account in this example). You must include an entry for the class
that you are defining if the external class-name contains non-COBOL characters, or
to specify a fully package-qualified class-name if the class is to be part of a Java
package.
Example: external class-names and Java packages
RELATED TASKS
Declaring arrays and strings for Java on page 629
RELATED REFERENCES
REPOSITORY paragraph (Enterprise COBOL Language Reference)
The Java Language Specification (Identifiers)
The Java Language Specification (Packages)
Example: external class-names and Java packages
The following example shows how external class-names are determined from
entries in a REPOSITORY paragraph.
Chapter 30. Writing object-oriented programs 585
Environment division.
Configuration section.
Repository.
Class Employee is "com.acme.Employee"
Class JavaException is "java.lang.Exception"
Class Orders.
The local class-names (the class-names as used within the class definition), the Java
packages that contain the classes, and the associated external class-names are as
shown in the table below.
Local class-name Java package External class-name
Employee com.acme com.acme.Employee
JavaException java.lang java.lang.Exception
Orders (unnamed) ORDERS
The external class-name (the name after the class-name and optional IS in the
REPOSITORY paragraph entry) is composed of the fully qualified name of the
package (if any) followed by a period, followed by the simple name of the class.
RELATED TASKS
REPOSITORY paragraph for defining a class on page 584
RELATED REFERENCES
REPOSITORY paragraph (Enterprise COBOL Language Reference)
WORKING-STORAGE SECTION for defining class instance
data
Use the WORKING-STORAGE SECTION in the DATA DIVISION of the OBJECT paragraph to
describe the instance data that a COBOL class needs, that is, the data to be allocated
for each instance of the class.
The OBJECT keyword, which you must immediately precede with an
IDENTIFICATION DIVISION declaration, indicates the beginning of the definitions of
the instance data and instance methods for the class. For example, the definition of
the instance data for the Account class might look like this:
IDENTIFICATION DIVISION.
Object.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 AccountNumber pic 9(6).
01 AccountBalance pic S9(9) value zero.
. . .
End Object.
The instance data is allocated when an object instance is created, and exists until
garbage collection of the instance by the Java run time.
You can initialize simple instance data by using VALUE clauses as shown above. You
can initialize more complex instance data by coding customized methods to create
and initialize instances of classes.
COBOL instance data is equivalent to Java private nonstatic member data. No
other class or subclass (nor factory method in the same class, if any) can reference
COBOL instance data directly. Instance data is global to all instance methods that
586 Enterprise COBOL for z/OS, V5.2 Programming Guide
the OBJECT paragraph defines. If you want to make instance data accessible from
outside the OBJECT paragraph, define attribute (get or set) instance methods for
doing so.
| The syntax of the WORKING-STORAGE SECTION for instance data definition is generally
the same as in a program, with these exceptions:
v You cannot use the EXTERNAL attribute.
v You can use the GLOBAL attribute, but it has no effect.
RELATED TASKS
Creating and initializing instances of classes on page 604
Freeing instances of classes on page 606
Defining a factory method on page 612
Coding attribute (get and set) methods on page 593
Example: defining a class
The following example shows a first attempt at the definition of the Account class,
excluding method definitions.
cbl dll,thread,pgmname(longmixed)
IDENTIFICATION DIVISION.
Class-id. Account inherits Base.
ENVIRONMENT DIVISION.
Configuration section.
Repository.
Class Base is "java.lang.Object"
Class Account is "Account".
*
IDENTIFICATION DIVISION.
Object.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 AccountNumber pic 9(6).
01 AccountBalance pic S9(9) value zero.
*
PROCEDURE DIVISION.
*
* (Instance method definitions here)
*
End Object.
*
End class Account.
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Defining a client on page 596
Defining a class instance method
Define COBOL instance methods in the PROCEDURE DIVISION of the OBJECT paragraph
of a class definition. An instance method defines an operation that is supported for
each object instance of a class.
A COBOL instance method definition consists of four divisions (like a COBOL
program), followed by an END METHOD marker.
Chapter 30. Writing object-oriented programs 587
Table 76. Structure of instance method definitions
Division Purpose Syntax
IDENTIFICATION Name a method.
(required) METHOD-ID paragraph for defining a
class instance method (required)
AUTHOR paragraph (optional)
INSTALLATION paragraph (optional)
DATE-WRITTEN paragraph (optional)
DATE-COMPILED paragraph (optional)
ENVIRONMENT Relate the file-names used INPUT-OUTPUT SECTION for defining a
(optional) in a method to the class instance method on page 589
corresponding file-names (optional)
known to the operating
system.
DATA (optional) Define external files. DATA DIVISION for defining a class
Allocate a copy of the instance method on page 589 (optional)
data.
PROCEDURE Code the executable PROCEDURE DIVISION for defining a
(optional) statements to complete class instance method on page 590
the service provided by (optional)
the method.
Definition: The signature of a method consists of the name of the method and the
number and type of its formal parameters. (You define the formal parameters of a
COBOL method in the USING phrase of the method's PROCEDURE DIVISION header.)
Within a class definition, you do not need to make each method-name unique, but
you do need to give each method a unique signature. (You overload methods by
giving them the same name but a different signature.)
COBOL instance methods are equivalent to Java public nonstatic methods.
Example: defining a method on page 594
RELATED TASKS
PROCEDURE DIVISION for defining a class instance method on page 590
Overloading an instance method on page 592
Overriding an instance method on page 591
Invoking methods (INVOKE) on page 600
Defining a subclass instance method on page 609
Defining a factory method on page 612
METHOD-ID paragraph for defining a class instance method
Use the METHOD-ID paragraph to name an instance method. Immediately precede
the METHOD-ID paragraph with an IDENTIFICATION DIVISION declaration to indicate
the beginning of the method definition.
For example, the definition of the credit method in the Account class begins like
this:
Identification Division.
Method-id. "credit".
588 Enterprise COBOL for z/OS, V5.2 Programming Guide
Code the method-name as an alphanumeric or national literal. The method-name is
processed in a case-sensitive manner and must conform to the rules of formation
for a Java method-name.
Other Java or COBOL methods or programs (that is, clients) use the method-name
to invoke a method.
RELATED TASKS
Invoking methods (INVOKE) on page 600
Using national data (Unicode) in COBOL on page 130
RELATED REFERENCES
The Java Language Specification (Meaning of method names)
The Java Language Specification (Identifiers)
METHOD-ID paragraph (Enterprise COBOL Language Reference)
INPUT-OUTPUT SECTION for defining a class instance method
The ENVIRONMENT DIVISION of an instance method can have only one section, the
INPUT-OUTPUT SECTION. This section relates the file-names used in a method
definition to the corresponding file-names as they are known to the operating
system.
For example, if the Account class defined a method that read information from a
file, the Account class might have an INPUT-OUTPUT SECTION that is coded like this:
Environment Division.
Input-Output Section.
File-Control.
Select account-file Assign AcctFile.
The syntax for the INPUT-OUTPUT SECTION of a method is the same as the syntax for
the INPUT-OUTPUT SECTION of a program.
RELATED TASKS
Describing the computing environment on page 5
RELATED REFERENCES
INPUT-OUTPUT section (Enterprise COBOL Language Reference)
DATA DIVISION for defining a class instance method
The DATA DIVISION of an instance method consists of any of the following four
sections: FILE SECTION, LOCAL-STORAGE SECTION, WORKING-STORAGE SECTION, and
LINKAGE SECTION.
FILE SECTION
The same as a program FILE SECTION, except that a method FILE SECTION
can define EXTERNAL files only.
LOCAL-STORAGE SECTION
A separate copy of the LOCAL-STORAGE data is allocated for each invocation
of the method, and is freed on return from the method. The method
LOCAL-STORAGE SECTION is similar to a program LOCAL-STORAGE SECTION.
If you specify the VALUE clause on a data item, the item is initialized to that
value on each invocation of the method.
WORKING-STORAGE SECTION
A single copy of the WORKING-STORAGE data is allocated. The data persists in
Chapter 30. Writing object-oriented programs 589
its last-used state until the run unit ends. The same copy of the data is
used whenever the method is invoked, regardless of the invoking object or
thread. The method WORKING-STORAGE SECTION is similar to a program
WORKING-STORAGE SECTION.
If you specify the VALUE clause on a data item, the item is initialized to that
value on the first invocation of the method. You can specify the EXTERNAL
clause for the data items.
LINKAGE SECTION
The same as a program LINKAGE SECTION.
If you define a data item with the same name in both the DATA DIVISION of an
instance method and the DATA DIVISION of the OBJECT paragraph, a reference in the
method to that data-name refers only to the method data item. The method DATA
DIVISION takes precedence.
RELATED TASKS
Describing the data on page 11
Sharing data by using the EXTERNAL clause on page 491
RELATED REFERENCES
DATA DIVISION overview (Enterprise COBOL Language Reference)
PROCEDURE DIVISION for defining a class instance method
Code the executable statements to implement the service that an instance method
provides in the PROCEDURE DIVISION of the instance method.
You can code most COBOL statements in the PROCEDURE DIVISION of a method that
you can code in the PROCEDURE DIVISION of a program. You cannot, however, code
the following statements in a method:
v ENTRY
v EXIT PROGRAM
| v The following obsolete elements of the 85 COBOL Standard:
ALTER
GOTO without a specified procedure-name
SEGMENT-LIMIT
USE FOR DEBUGGING
Additionally, because you must compile all COBOL class definitions with the
THREAD compiler option, you cannot use SORT or MERGE statements in a COBOL
method.
You can code the EXIT METHOD or GOBACK statement in an instance method to return
control to the invoking client. Both statements have the same effect. If you specify
the RETURNING phrase upon invocation of the method, the EXIT METHOD or GOBACK
statement returns the value of the data item to the invoking client.
An implicit EXIT METHOD is generated as the last statement in the PROCEDURE
DIVISION of each method.
You can specify STOP RUN in a method; doing so terminates the entire run unit
including all threads executing within it.
590 Enterprise COBOL for z/OS, V5.2 Programming Guide
You must terminate a method definition with an END METHOD marker. For example,
the following statement marks the end of the credit method:
End method "credit".
USING phrase for obtaining passed arguments: Specify the formal parameters to
a method, if any, in the USING phrase of the method's PROCEDURE DIVISION header.
You must specify that the arguments are passed BY VALUE. Define each parameter
as a level-01 or level-77 item in the method's LINKAGE SECTION. The data type of
each parameter must be one of the types that are interoperable with Java.
RETURNING phrase for returning a value: Specify the data item to be returned
as the method result, if any, in the RETURNING phrase of the method's PROCEDURE
DIVISION header. Define the data item as a level-01 or level-77 item in the method's
LINKAGE SECTION. The data type of the return value must be one of the types that
are interoperable with Java.
RELATED TASKS
Coding interoperable data types in COBOL and Java on page 628
Overriding an instance method
Overloading an instance method on page 592
Comparing and setting object references on page 599
Invoking methods (INVOKE) on page 600
Chapter 16, Compiling, linking, and running OO applications, on page 291
RELATED REFERENCES
THREAD on page 362
The procedure division header (Enterprise COBOL Language Reference)
Overriding an instance method
An instance method that is defined in a subclass is said to override an inherited
instance method that would otherwise be accessible in the subclass if the two
methods have the same signature.
To override a superclass instance method m1 in a COBOL subclass, define an
instance method m1 in the subclass that has the same name and whose PROCEDURE
DIVISION USING phrase (if any) has the same number and type of formal
parameters as the superclass method has. (If the superclass method is implemented
in Java, you must code formal parameters that are interoperable with the data
types of the corresponding Java parameters.) When a client invokes m1 on an
instance of the subclass, the subclass method rather than the superclass method is
invoked.
For example, the Account class defines a method debit whose LINKAGE SECTION
and PROCEDURE DIVISION header look like this:
Linkage section.
01 inDebit pic S9(9) binary.
Procedure Division using by value inDebit.
If you define a CheckingAccount subclass and want it to have a debit method that
overrides the debit method defined in the Account superclass, define the subclass
method with exactly one input parameter also specified as pic S9(9) binary. If a
client invokes debit using an object reference to a CheckingAccount instance, the
CheckingAccount debit method (rather than the debit method in the Account
superclass) is invoked.
Chapter 30. Writing object-oriented programs 591
The presence or absence of a method return value and the data type of the return
value used in the PROCEDURE DIVISION RETURNING phrase (if any) must be identical
in the subclass instance method and the overridden superclass instance method.
An instance method must not override a factory method in a COBOL superclass
nor a static method in a Java superclass.
Example: defining a method on page 594
RELATED TASKS
PROCEDURE DIVISION for defining a class instance method on page 590
Coding interoperable data types in COBOL and Java on page 628
Invoking methods (INVOKE) on page 600
Invoking overridden superclass methods on page 604
Defining a subclass on page 607
Hiding a factory or static method on page 613
RELATED REFERENCES
The Java Language Specification (Inheritance, overriding, and hiding)
Overloading an instance method
Two methods that are supported in a class (whether defined in the class or
inherited from a superclass) are said to be overloaded if they have the same name
but different signatures.
You overload methods when you want to enable clients to invoke different
versions of a method, for example, to initialize data using different sets of
parameters.
To overload a method, define a method whose PROCEDURE DIVISION USING phrase
(if any) has a different number or type of formal parameters than an identically
named method that is supported in the same class. For example, the Account class
defines an instance method init that has exactly one formal parameter. The
LINKAGE SECTION and PROCEDURE DIVISION header of the init method look like this:
Linkage section.
01 inAccountNumber pic S9(9) binary.
Procedure Division using by value inAccountNumber.
Clients invoke this method to initialize an Account instance with a given account
number (and a default account balance of zero) by passing exactly one argument
that matches the data type of inAccountNumber.
But the Account class could define, for example, a second instance method init
that has an additional formal parameter that allows the opening account balance to
also be specified. The LINKAGE SECTION and PROCEDURE DIVISION header of this init
method could look like this:
Linkage section.
01 inAccountNumber pic S9(9) binary.
01 inBalance pic S9(9) binary.
Procedure Division using by value inAccountNumber
inBalance.
Clients could invoke either init method by passing arguments that match the
signature of the required method.
592 Enterprise COBOL for z/OS, V5.2 Programming Guide
The presence or absence of a method return value does not have to be consistent in
overloaded methods, and the data type of the return value given in the PROCEDURE
DIVISION RETURNING phrase (if any) does not have to be identical in overloaded
methods.
You can overload factory methods in exactly the same way that you overload
instance methods.
The rules for overloaded method definition and resolution of overloaded method
invocations are based on the corresponding rules for Java.
RELATED TASKS
Invoking methods (INVOKE) on page 600
Defining a factory method on page 612
RELATED REFERENCES
The Java Language Specification (Overloading)
Coding attribute (get and set) methods
You can provide access to an instance variable X from outside the class in which X
is defined by coding accessor (get) and mutator (set) methods for X.
Instance variables in COBOL are private: the class that defines instance variables
fully encapsulates them, and only the instance methods defined in the same OBJECT
paragraph can access them directly. Normally a well-designed object-oriented
application does not need to access instance variables from outside the class.
COBOL does not directly support the concept of a public instance variable as
defined in Java and other object-oriented languages, nor the concept of a class
attribute as defined by CORBA. (A CORBA attribute is an instance variable that has
an automatically generated get method for accessing the value of the variable, and
an automatically generated set method for modifying the value of the variable if
the variable is not read-only.)
Example: coding a get method
RELATED TASKS
WORKING-STORAGE SECTION for defining class instance data on page 586
Processing the data on page 17
Example: coding a get method
The following example shows the definition in the Account class of an instance
method, getBalance, to return the value of the instance variable AccountBalance to
a client. getBalance and AccountBalance are defined in the OBJECT paragraph of the
Account class definition.
Identification Division.
Class-id. Account inherits Base.
* (ENVIRONMENT DIVISION not shown)
* (FACTORY paragraph not shown)
*
Identification division.
Object.
Data division.
WORKING-STORAGE SECTION.
01 AccountBalance pic S9(9) value zero.
* (Other instance data not shown)
*
Chapter 30. Writing object-oriented programs 593
Procedure Division.
*
Identification Division.
Method-id. "getBalance".
Data division.
Linkage section.
01 outBalance pic S9(9) binary.
*
Procedure Division returning outBalance.
Move AccountBalance to outBalance.
End method "getBalance".
*
* (Other instance methods not shown)
End Object.
*
End class Account.
Example: defining a method
The following example adds to the previous example the instance method
definitions of the Account class, and shows the definition of the Java Check class.
(The previous example was Example: defining a class on page 587.)
Account class
cbl dll,thread,pgmname(longmixed)
Identification Division.
Class-id. Account inherits Base.
Environment Division.
Configuration section.
Repository.
Class Base is "java.lang.Object"
Class Account is "Account".
*
* (FACTORY paragraph not shown)
*
Identification division.
Object.
Data division.
Working-storage section.
01 AccountNumber pic 9(6).
01 AccountBalance pic S9(9) value zero.
*
Procedure Division.
*
* init method to initialize the account:
Identification Division.
Method-id. "init".
Data division.
Linkage section.
01 inAccountNumber pic S9(9) binary.
Procedure Division using by value inAccountNumber.
Move inAccountNumber to AccountNumber.
End method "init".
*
* getBalance method to return the account balance:
Identification Division.
Method-id. "getBalance".
Data division.
Linkage section.
01 outBalance pic S9(9) binary.
Procedure Division returning outBalance.
Move AccountBalance to outBalance.
End method "getBalance".
*
* credit method to deposit to the account:
594 Enterprise COBOL for z/OS, V5.2 Programming Guide
Identification Division.
Method-id. "credit".
Data division.
Linkage section.
01 inCredit pic S9(9) binary.
Procedure Division using by value inCredit.
Add inCredit to AccountBalance.
End method "credit".
*
* debit method to withdraw from the account:
Identification Division.
Method-id. "debit".
Data division.
Linkage section.
01 inDebit pic S9(9) binary.
Procedure Division using by value inDebit.
Subtract inDebit from AccountBalance.
End method "debit".
*
* print method to display formatted account number and balance:
Identification Division.
Method-id. "print".
Data division.
Local-storage section.
01 PrintableAccountNumber pic ZZZZZZ999999.
01 PrintableAccountBalance pic $$$$,$$$,$$9CR.
Procedure Division.
Move AccountNumber to PrintableAccountNumber
Move AccountBalance to PrintableAccountBalance
Display " Account: " PrintableAccountNumber
Display " Balance: " PrintableAccountBalance.
End method "print".
*
End Object.
*
End class Account.
Check class
/**
* A Java class for check information
*/
public class Check {
private CheckingAccount payer;
private Account payee;
private int amount;
public Check(CheckingAccount inPayer, Account inPayee, int inAmount) {
payer=inPayer;
payee=inPayee;
amount=inAmount;
}
public int getAmount() {
return amount;
}
public Account getPayee() {
return payee;
}
}
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Chapter 30. Writing object-oriented programs 595
Defining a client
A program or method that requests services from one or more methods in a class
is called a client of that class.
In a COBOL or Java client, you can:
v Create object instances of Java and COBOL classes.
v Invoke instance methods on Java and COBOL objects.
v Invoke COBOL factory methods and Java static methods.
In a COBOL client, you can also call services provided by the Java Native Interface
(JNI).
A COBOL client program consists of the usual four divisions:
Table 77. Structure of COBOL clients
Division Purpose Syntax
IDENTIFICATION Name a client. Code as usual, except that a client program
(required) must be:
v Recursive (declared RECURSIVE in the
PROGRAM-ID paragraph)
v Thread-enabled (compiled with the
THREAD option, and conforming to the
coding guidelines for threaded
applications)
ENVIRONMENT Describe the computing CONFIGURATION SECTION (required)
(required) environment. Relate REPOSITORY paragraph for defining a
class-names used in the client on page 597 (required)
client to the
corresponding external
class-names known
outside the compilation
unit.
DATA (optional) Describe the data that the DATA DIVISION for defining a client on
client needs. page 598 (optional)
PROCEDURE Create instances of classes, Code using INVOKE, IF, and SET statements.
(optional) manipulate object
reference data items, and
invoke methods.
Because you must compile all COBOL programs that contain object-oriented syntax
or that interoperate with Java with the THREAD compiler option, you cannot use the
following language elements in a COBOL client:
v SORT or MERGE statements
v Nested programs
Any programs that you compile with the THREAD compiler option must be
recursive. You must specify the RECURSIVE clause in the PROGRAM-ID paragraph of
each OO COBOL client program.
Example: defining a client on page 606
596 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Chapter 27, Preparing COBOL programs for multithreading, on page 507
Chapter 31, Communicating with Java methods, on page 623
Coding interoperable data types in COBOL and Java on page 628
Creating and initializing instances of classes on page 604
Comparing and setting object references on page 599
Invoking methods (INVOKE) on page 600
Invoking factory or static methods on page 614
RELATED REFERENCES
THREAD on page 362
REPOSITORY paragraph for defining a client
Use the REPOSITORY paragraph to declare to the compiler that the specified words
are class-names when you use them in a COBOL client, and to optionally relate the
class-names to the corresponding external class-names (the class-names as they are
known outside the compilation unit).
External class-names are case sensitive, and must conform to Java rules of
formation. For example, in a client program that uses the Account and Check
classes you might code this:
Environment division. Required
Configuration section. Required
Source-Computer. IBM-390.
Object-Computer. IBM-390.
Repository. Required
Class Account is "Account"
Class Check is "Check".
The REPOSITORY paragraph entries indicate that the external class-names of the
classes referred to as Account and Check within the client are Account and Check,
respectively.
In the REPOSITORY paragraph, you must code an entry for each class-name that you
explicitly reference in the client. In a REPOSITORY paragraph entry, you must specify
the external class-name if the name contains non-COBOL characters.
You must specify the external class-name for any referenced class that is part of a
Java package. For such a class, specify the external class-name as the fully qualified
name of the package, followed by period (.), followed by the simple name of the
Java class.
An external class-name that you specify in the REPOSITORY paragraph must be an
alphanumeric literal that conforms to the rules of formation for a fully qualified
Java class-name.
If you do not include the external class-name in a REPOSITORY paragraph entry, the
external class-name is formed from the class-name in the same manner as it is
when an external class-name is not included in a REPOSITORY paragraph entry in a
class definition. In the example above, class Account and class Check are known
externally as Account and Check (in mixed case), respectively, because the external
names are spelled using mixed case.
The SOURCE-COMPUTER, OBJECT-COMPUTER, and SPECIAL-NAMES paragraphs of the
CONFIGURATION SECTION are optional.
Chapter 30. Writing object-oriented programs 597
RELATED TASKS
REPOSITORY paragraph for defining a class on page 584
RELATED REFERENCES
REPOSITORY paragraph (Enterprise COBOL Language Reference)
The Java Language Specification (Identifiers)
The Java Language Specification (Packages)
DATA DIVISION for defining a client
You can use any of the sections of the DATA DIVISION to describe the data that the
client needs.
Data Division.
Local-storage section.
01 anAccount usage object reference Account.
01 aCheckingAccount usage object reference CheckingAccount.
01 aCheck usage object reference Check.
01 payee usage object reference Account.
. . .
Because a client references classes, it needs one or more special data items called
object references, that is, references to instances of those classes. All requests to
instance methods require an object reference to an instance of a class in which the
method is supported (that is, either defined or available by inheritance). You code
object references to refer to instances of Java classes using the same syntax as you
use to refer to instances of COBOL classes. In the example above, the phrase usage
object reference indicates an object reference data item.
All four object references in the code above are called typed object references
because a class-name appears after the OBJECT REFERENCE phrase. A typed object
reference can refer only to an instance of the class named in the OBJECT REFERENCE
phrase or to one of its subclasses. Thus anAccount can refer to instances of the
Account class or one of its subclasses, but cannot refer to instances of any other
class. Similarly, aCheck can refer only to instances of the Check class or any
subclasses that it might have.
Another type of object reference, not shown above, does not have a class-name
after the OBJECT REFERENCE phrase. Such a reference is called a universal object
reference, which means that it can refer to instances of any class. Avoid coding
universal object references, because they are interoperable with Java in only very
limited circumstances (when used in the RETURNING phrase of the INVOKE
class-name NEW . . . statement).
You must define, in the REPOSITORY paragraph of the CONFIGURATION SECTION,
class-names that you use in the OBJECT REFERENCE phrase.
RELATED TASKS
Choosing LOCAL-STORAGE or WORKING-STORAGE on page 599
Coding interoperable data types in COBOL and Java on page 628
Invoking methods (INVOKE) on page 600
REPOSITORY paragraph for defining a client on page 597
RELATED REFERENCES
RETURNING phrase (Enterprise COBOL Language Reference)
598 Enterprise COBOL for z/OS, V5.2 Programming Guide
Choosing LOCAL-STORAGE or WORKING-STORAGE
You can in general use the WORKING-STORAGE SECTION to define working data that a
client program needs. However, if the program could simultaneously run on
multiple threads, you might instead want to define the data in the LOCAL-STORAGE
SECTION.
Each thread has access to a separate copy of LOCAL-STORAGE data but shares access
to a single copy of WORKING-STORAGE data. If you define the data in the
WORKING-STORAGE SECTION, you need to synchronize access to the data or ensure
that no two threads can access it simultaneously.
RELATED TASKS
Chapter 27, Preparing COBOL programs for multithreading, on page 507
Comparing and setting object references
You can compare object references by coding conditional statements or a call to the
JNI service IsSameObject, and you can set object references by using the SET
statement.
For example, code either IF statement below to check whether the object reference
anAccount refers to no object instance:
If anAccount = Null . . .
If anAccount = Nulls . . .
You can code a call to IsSameObject to check whether two object references, object1
and object2, refer to the same object instance or whether each refers to no object
instance. To ensure that the arguments and return value are interoperable with
Java and to establish addressability to the callable service, code the following data
definitions and statements before the call to IsSameObject:
Local-storage Section.
. . .
01 is-same Pic X.
88 is-same-false Value X00.
88 is-same-true Value X01 Through XFF.
Linkage Section.
Copy JNI.
Procedure Division.
Set Address Of JNIEnv To JNIEnvPtr
Set Address Of JNINativeInterface To JNIEnv
Call IsSameObject Using By Value JNIEnvPtr object1 object2
Returning is-same
If is-same-true . . .
Within a method you can check whether an object reference refers to the object
instance on which the method was invoked by coding a call to IsSameObject that
compares the object reference and SELF.
You can instead invoke the Java equals method (inherited from java.lang.Object) to
determine whether two object references refer to the same object instance.
You can make an object reference refer to no object instance by using the SET
statement. For example:
Set anAccount To Null.
You can also make one object reference refer to the same instance as another object
reference does by using the SET statement. For example:
Set anotherAccount To anAccount.
Chapter 30. Writing object-oriented programs 599
This SET statement causes anotherAccount to refer to the same object instance as
anAccount does. If the receiver (anotherAccount) is a universal object reference, the
sender (anAccount) can be either a universal or a typed object reference. If the
receiver is a typed object reference, the sender must be a typed object reference
bound to the same class as the receiver or to one of its subclasses.
Within a method you can make an object reference refer to the object instance on
which the method was invoked by setting it to SELF. For example:
Set anAccount To Self.
RELATED TASKS
Coding interoperable data types in COBOL and Java on page 628
Accessing JNI services on page 623
RELATED REFERENCES
The Java Native Interface (IsSameObject)
Invoking methods (INVOKE)
In a Java client, you can create object instances of classes that were implemented in
COBOL and invoke methods on those objects using standard Java syntax. In a
COBOL client, you can invoke methods that are defined in Java or COBOL classes
by coding the INVOKE statement.
Invoke Account "createAccount"
using by value 123456
returning anAccount
Invoke anAccount "credit" using by value 500.
The first example INVOKE statement above uses the class-name Account to invoke a
method called createAccount. This method must be either defined or inherited in
the Account class, and must be one of the following types:
v A Java static method
v A COBOL factory method
The phrase using by value 123456 indicates that 123456 is an input argument to
the method, and is passed by value. The input argument 123456 and the returned
data item anAccount must conform to the definition of the formal parameters and
return type, respectively, of the (possibly overloaded) createAccount method.
The second INVOKE statement uses the returned object reference anAccount to
invoke the instance method credit, which is defined in the Account class. The
input argument 500 must conform to the definition of the formal parameters of the
(possibly overloaded) credit method.
Code the name of the method to be invoked either as a literal or as an identifier
whose value at run time matches the method-name in the signature of the target
method. The method-name must be an alphanumeric or national literal or a
category alphabetic, alphanumeric, or national data item, and is interpreted in a
case-sensitive manner.
When you code an INVOKE statement using an object reference (as in the second
example statement above), the statement begins with one of the following two
forms:
Invoke objRef "literal-name" . . .
Invoke objRef identifier-name . . .
600 Enterprise COBOL for z/OS, V5.2 Programming Guide
When the method-name is an identifier, you must define the object reference
(objRef) as USAGE OBJECT REFERENCE with no specified type, that is, as a universal
object reference.
If an invoked method is not supported in the class to which the object reference
refers, a severity-3 Language Environment condition is raised at run time unless
you code the ON EXCEPTION phrase in the INVOKE statement.
You can use the optional scope terminator END-INVOKE with the INVOKE statement.
The INVOKE statement does not set the RETURN-CODE special register.
RELATED TASKS
USING phrase for passing arguments
RETURNING phrase for obtaining a returned value on page 603
PROCEDURE DIVISION for defining a class instance method on page 590
Coding interoperable data types in COBOL and Java on page 628
Invoking overridden superclass methods on page 604
Invoking factory or static methods on page 614
RELATED REFERENCES
INVOKE statement (Enterprise COBOL Language Reference)
USING phrase for passing arguments
If you pass arguments to a method, specify the arguments in the USING phrase of
the INVOKE statement. Code the data type of each argument so that it conforms to
the type of the corresponding formal parameter in the intended target method.
Table 78. Conformance of arguments in a COBOL client
Programming Is the argument Then code the DATA
language of the an object DIVISION definition of
target method reference? the argument as: Restriction
COBOL No The same as the
definition of the
corresponding formal
parameter
Java No Interoperable with the
corresponding Java
parameter
COBOL or Java Yes An object reference that is In a COBOL client (unlike
typed to the same class as in a Java client), the class
the corresponding of an argument cannot be
parameter in the target a subclass of the class of
method the corresponding
parameter.
See the example referenced below for a way to make an object-reference argument
conform to the type of a corresponding formal parameter by using the SET
statement or the REDEFINES clause.
Example: passing conforming object-reference arguments from a COBOL client
on page 602
If the target method is overloaded, the data types of the arguments are used to
select from among the methods that have the same name.
Chapter 30. Writing object-oriented programs 601
You must specify that the arguments are passed BY VALUE. In other words, the
arguments are not affected by any change to the corresponding formal parameters
in the invoked method.
The data type of each argument must be one of the types that are interoperable
with Java.
RELATED TASKS
PROCEDURE DIVISION for defining a class instance method on page 590
Overloading an instance method on page 592
Coding interoperable data types in COBOL and Java on page 628
Passing data on page 481
RELATED REFERENCES
INVOKE statement (Enterprise COBOL Language Reference)
SET statement (Enterprise COBOL Language Reference)
REDEFINES clause (Enterprise COBOL Language Reference)
Example: passing conforming object-reference arguments from a
COBOL client
The following example shows a way to make an object-reference argument in a
COBOL client conform to the expected class of the corresponding formal parameter
in an invoked method.
Class C defines a method M that has one parameter, a reference to an object of
class java.lang.Object:
. . .
Class-id. C inherits Base.
. . .
Repository.
Class Base is "java.lang.Object"
Class JavaObject is "java.lang.Object".
Identification division.
Factory.
. . .
Procedure Division.
Identification Division.
Method-id. "M".
Data division.
Linkage section.
01 obj object reference JavaObject.
Procedure Division using by value obj.
. . .
To invoke method M, a COBOL client must pass an argument that is a reference to
an object of class java.lang.Object. The client below defines a data item aString,
which cannot be passed as an argument to M because aString is a reference to an
object of class java.lang.String. The client first uses a SET statement to assign
aString to a data item, anObj, that is a reference to an object of class
java.lang.Object. (This SET statement is legal because java.lang.String is a subclass
of java.lang.Object.) The client then passes anObj as the argument to M.
. . .
Repository.
Class jstring is "java.lang.String"
Class JavaObject is "java.lang.Object".
Data division.
Local-storage section.
01 aString object reference jstring.
01 anObj object reference JavaObject.
*
602 Enterprise COBOL for z/OS, V5.2 Programming Guide
Procedure division.
. . . (statements here assign a value to aString)
Set anObj to aString
Invoke C "M"
using by value anObj
Instead of using a SET statement to obtain anObj as a reference to an object of class
java.lang.Object, the client could define aString and anObj with the REDEFINES
clause as follows:
. . .
01 aString object reference jstring.
01 anObj redefines aString object reference JavaObject.
After the client assigns a value to data item aString (that is, a valid reference to an
object of class java.lang.String), anObj can be passed as the argument to M. For an
example of the use of the REDEFINES clause to obtain argument conformance, see
the example referenced below.
Example: J2EE client written in COBOL on page 634
RELATED TASKS
Coding interoperable data types in COBOL and Java on page 628
PROCEDURE DIVISION for defining a class instance method on page 590
RELATED REFERENCES
INVOKE statement (Enterprise COBOL Language Reference)
SET statement (Enterprise COBOL Language Reference)
REDEFINES clause (Enterprise COBOL Language Reference)
RETURNING phrase for obtaining a returned value
If a data item is to be returned as the method result, specify the item in the
RETURNING phrase of the INVOKE statement. Define the returned item in the DATA
DIVISION of the client.
The item that you specify in the RETURNING phrase of the INVOKE statement must
conform to the type returned by the target method, as shown in the table below.
Table 79. Conformance of the returned data item in a COBOL client
Programming
language of the Is the returned item Then code the DATA DIVISION definition of
target method an object reference? the returned item as:
COBOL No The same as the definition of the RETURNING
item in the target method
Java No Interoperable with the returned Java data
item
COBOL or Java Yes An object reference that is typed to the
same class as the object reference that is
returned by the target method
In all cases, the data type of the returned value must be one of the types that are
interoperable with Java.
RELATED TASKS
Coding interoperable data types in COBOL and Java on page 628
Chapter 30. Writing object-oriented programs 603
RELATED REFERENCES
INVOKE statement (Enterprise COBOL Language Reference)
Invoking overridden superclass methods
Sometimes within a class you need to invoke an overridden superclass method
instead of invoking a method that has the same signature and is defined in the
current class.
For example, suppose that the CheckingAccount class overrides the debit instance
method defined in its immediate superclass, Account. You could invoke the
Account debit method within a method in the CheckingAccount class by coding
this statement:
Invoke Super "debit" Using By Value amount.
You would define amount as PIC S9(9) BINARY to match the signature of the debit
methods.
The CheckingAccount class overrides the print method that is defined in the
Account class. Because the print method has no formal parameters, a method in
the CheckingAccount class could invoke the superclass print method with this
statement:
Invoke Super "print".
The keyword SUPER indicates that you want to invoke a superclass method rather
than a method in the current class. (SUPER is an implicit reference to the object used
in the invocation of the currently executing method.)
Example: accounts on page 580
RELATED TASKS
Overriding an instance method on page 591
RELATED REFERENCES
INVOKE statement (Enterprise COBOL Language Reference)
Creating and initializing instances of classes
Before you can use the instance methods that are defined in a Java or COBOL
class, you must first create an instance of the class.
To create a new instance of class class-name and to obtain a reference object-reference
to the created object, code a statement of the following form, where object-reference
is defined in the DATA DIVISION of the client:
INVOKE class-name NEW . . . RETURNING object-reference
When you code the INVOKE . . . NEW statement within a method, and the use of
the returned object reference is not limited to the duration of the method
invocation, you must convert the returned object reference to a global reference by
calling the JNI service NewGlobalRef:
Call NewGlobalRef using by value JNIEnvPtr object-reference
returning object-reference
If you do not call NewGlobalRef, the returned object reference is only a local
reference, which means that it is automatically freed after the method returns.
604 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Instantiating Java classes
Instantiating COBOL classes
Accessing JNI services on page 623
Managing local and global references on page 626
DATA DIVISION for defining a client on page 598
Invoking methods (INVOKE) on page 600
Coding interoperable data types in COBOL and Java on page 628
RELATED REFERENCES
INVOKE statement (Enterprise COBOL Language Reference)
Instantiating Java classes
To instantiate a Java class, invoke any parameterized constructor that the class
supports by coding the USING phrase in the INVOKE . . . NEW statement
immediately before the RETURNING phrase, passing BY VALUE the number and types
of arguments that match the signature of the constructor.
The data type of each argument must be one of the types that are interoperable
with Java. To invoke the default (parameterless) constructor, omit the USING phrase.
For example, to create an instance of the Check class, initialize its instance data,
and obtain reference aCheck to the Check instance created, you could code this
statement in a COBOL client:
Invoke Check New
using by value aCheckingAccount, payee, 125
returning aCheck
RELATED TASKS
Invoking methods (INVOKE) on page 600
Coding interoperable data types in COBOL and Java on page 628
RELATED REFERENCES
VALUE clause (Enterprise COBOL Language Reference)
INVOKE statement (Enterprise COBOL Language Reference)
Instantiating COBOL classes
To instantiate a COBOL class, you can specify either a typed or universal object
reference in the RETURNING phrase of the INVOKE . . . NEW statement. However,
you cannot code the USING phrase: the instance data is initialized as specified in the
VALUE clauses in the class definition.
Thus the INVOKE . . . NEW statement is useful for instantiating COBOL classes that
have only simple instance data. For example, the following statement creates an
instance of the Account class, initializes the instance data as specified in VALUE
clauses in the WORKING-STORAGE SECTION of the OBJECT paragraph of the Account
class definition, and provides reference outAccount to the new instance:
Invoke Account New returning outAccount
To make it possible to initialize COBOL instance data that cannot be initialized
using VALUE clauses alone, when designing a COBOL class you must define a
parameterized creation method in the FACTORY paragraph and a parameterized
initialization method in the OBJECT paragraph:
1. In the parameterized factory creation method, do these steps:
Chapter 30. Writing object-oriented programs 605
a. Code INVOKE class-name NEW RETURNING objectRef to create an instance of
class-name and to give initial values to the instance data items that have
VALUE clauses.
b. Invoke the parameterized initialization method on the instance (objectRef),
passing BY VALUE the arguments that were supplied to the factory method.
2. In the initialization method, code logic to complete the instance data
initialization using the values supplied through the formal parameters.
To create an instance of the COBOL class and properly initialize it, the client
invokes the parameterized factory method, passing BY VALUE the required
arguments. The object reference returned to the client is a local reference. If the
client code is within a method, and the use of the returned object reference is not
limited to the duration of that method, the client code must convert the returned
object reference to a global reference by calling the JNI service NewGlobalRef.
Example: defining a factory (with methods) on page 615
RELATED TASKS
Accessing JNI services on page 623
Managing local and global references on page 626
Invoking methods (INVOKE) on page 600
Defining a factory section on page 611
RELATED REFERENCES
VALUE clause (Enterprise COBOL Language Reference)
INVOKE statement (Enterprise COBOL Language Reference)
Freeing instances of classes
You do not need to take any action to free individual object instances of any class.
No syntax is available for doing so. The Java runtime system automatically
performs garbage collection, that is, it reclaims the memory for objects that are no
longer in use.
There could be times, however, when you need to explicitly free local or global
references to objects within a native COBOL client in order to permit garbage
collection of the referenced objects to occur.
RELATED TASKS
Managing local and global references on page 626
Example: defining a client
The following example shows a small client program of the Account class.
The program does this:
v Invokes a factory method createAccount to create an Account instance with a
default balance of zero
v Invokes the instance method credit to deposit $500 to the new account
v Invokes the instance method print to display the account status
(The Account class was shown in Example: defining a method on page 594.)
cbl dll,thread,pgmname(longmixed)
Identification division.
Program-id. "TestAccounts" recursive.
Environment division.
606 Enterprise COBOL for z/OS, V5.2 Programming Guide
Configuration section.
Repository.
Class Account is "Account".
Data Division.
* Working data is declared in LOCAL-STORAGE instead of
* WORKING-STORAGE so that each thread has its own copy:
Local-storage section.
01 anAccount usage object reference Account.
*
Procedure division.
Test-Account-section.
Display "Test Account class"
* Create account 123456 with 0 balance:
Invoke Account "createAccount"
using by value 123456
returning anAccount
* Deposit 500 to the account:
Invoke anAccount "credit" using by value 500
Invoke anAccount "print"
Display space
*
Stop Run.
End program "TestAccounts".
Example: defining a factory (with methods) on page 615
RELATED TASKS
Defining a factory method on page 612
Invoking factory or static methods on page 614
Chapter 16, Compiling, linking, and running OO applications, on page 291
Defining a subclass
You can make a class (called a subclass, derived class, or child class) a
specialization of another class (called a superclass, base class, or parent class).
A subclass inherits the methods and instance data of its superclasses, and is related
to its superclasses by an is-a relationship. For example, if subclass P inherits from
superclass Q, and subclass Q inherits from superclass S, then an instance of P is an
instance of Q and also (by transitivity) an instance of S. An instance of P inherits
the methods and data of Q and S.
Using subclasses has several advantages:
v Reuse of code: Through inheritance, a subclass can reuse methods that already
exist in a superclass.
v Specialization: In a subclass you can add new methods to handle cases that the
superclass does not handle. You can also add new data items that the superclass
does not need.
v Change in action: A subclass can override a method that it inherits from a
superclass by defining a method of the same signature as that in the superclass.
When you override a method, you might make only a few minor changes or
completely change what the method does.
Restriction: You cannot use multiple inheritance in your COBOL programs. Each
COBOL class that you define must have exactly one immediate superclass that is
implemented in Java or COBOL, and each class must be derived directly or
indirectly from java.lang.Object. The semantics of inheritance are as defined by
Java.
Chapter 30. Writing object-oriented programs 607
The structure and syntax of a subclass definition are identical to those of a class
definition: Define instance data and methods in the DATA DIVISION and PROCEDURE
DIVISION, respectively, within the OBJECT paragraph of the subclass definition. In
subclasses that require data and methods that are to be associated with the
subclass itself rather than with individual object instances, define a separate DATA
DIVISION and PROCEDURE DIVISION within the FACTORY paragraph of the subclass
definition.
COBOL instance data is private. A subclass can access the instance data of a
COBOL superclass only if the superclass defines attribute (get or set) instance
methods for doing so.
Example: accounts on page 580
Example: defining a subclass (with methods) on page 610
RELATED TASKS
Defining a class on page 582
Overriding an instance method on page 591
Coding attribute (get and set) methods on page 593
Defining a subclass instance method on page 609
Defining a factory section on page 611
RELATED REFERENCES
The Java Language Specification (Inheritance, overriding, and hiding)
COBOL class definition structure (Enterprise COBOL Language Reference)
CLASS-ID paragraph for defining a subclass
Use the CLASS-ID paragraph to name the subclass and indicate from which
immediate Java or COBOL superclass it inherits its characteristics.
Identification Division. Required
Class-id. CheckingAccount inherits Account. Required
In the example above, CheckingAccount is the subclass being defined.
CheckingAccount inherits all the methods of the class known within the subclass
definition as Account. CheckingAccount methods can access Account instance data
only if the Account class provides attribute (get or set) methods for doing so.
You must specify the name of the immediate superclass in the REPOSITORY
paragraph in the CONFIGURATION SECTION of the ENVIRONMENT DIVISION. You can
optionally associate the superclass name with the name of the class as it is known
externally. You can also specify the name of the subclass that you are defining
(here, CheckingAccount) in the REPOSITORY paragraph and associate it with its
corresponding external class-name.
RELATED TASKS
CLASS-ID paragraph for defining a class on page 584
Coding attribute (get and set) methods on page 593
REPOSITORY paragraph for defining a subclass
REPOSITORY paragraph for defining a subclass
Use the REPOSITORY paragraph to declare to the compiler that the specified words
are class-names when you use them within a subclass definition, and to optionally
relate the class-names to the corresponding external class-names (the class-names
as they are known outside the compilation unit).
608 Enterprise COBOL for z/OS, V5.2 Programming Guide
For example, in the CheckingAccount subclass definition, these REPOSITORY
paragraph entries indicate that the external class-names of the classes referred to as
CheckingAccount, Check, and Account within the subclass definition are
CheckingAccount, Check, and Account, respectively.
Environment Division. Required
Configuration Section. Required
Repository. Required
Class CheckingAccount is "CheckingAccount" Optional
Class Check is "Check" Required
Class Account is "Account". Required
In the REPOSITORY paragraph, you must code an entry for each class-name that you
explicitly reference in the subclass definition. For example:
v A user-defined superclass from which the subclass that you are defining inherits
v The classes that you reference in methods within the subclass definition
The rules for coding REPOSITORY paragraph entries in a subclass are identical to
those for coding REPOSITORY paragraph entries in a class.
RELATED TASKS
REPOSITORY paragraph for defining a class on page 584
RELATED REFERENCES
REPOSITORY paragraph (Enterprise COBOL Language Reference)
WORKING-STORAGE SECTION for defining subclass instance
data
Use the WORKING-STORAGE SECTION in the DATA DIVISION of the subclass OBJECT
paragraph to describe any instance data that the subclass needs in addition to the
instance data defined in its superclasses. Use the same syntax that you use to
define instance data in a class.
For example, the definition of the instance data for the CheckingAccount subclass
of the Account class might look like this:
IDENTIFICATION DIVISION.
Object.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CheckFee pic S9(9) value 1.
. . .
End Object.
RELATED TASKS
WORKING-STORAGE SECTION for defining class instance data on page 586
Defining a subclass instance method
A subclass inherits the methods of its superclasses. In a subclass definition, you
can override any instance method that the subclass inherits by defining an instance
method with the same signature as the inherited method. You can also define new
methods that the subclass needs.
The structure and syntax of a subclass instance method are identical to those of a
class instance method. Define subclass instance methods in the PROCEDURE DIVISION
of the OBJECT paragraph of the subclass definition.
Example: defining a subclass (with methods) on page 610
Chapter 30. Writing object-oriented programs 609
RELATED TASKS
Defining a class instance method on page 587
Overriding an instance method on page 591
Overloading an instance method on page 592
Example: defining a subclass (with methods)
The following example shows the instance method definitions for the
CheckingAccount subclass of the Account class.
The processCheck method invokes the Java instance methods getAmount and
getPayee of the Check class to get the check data. It invokes the credit and debit
instance methods inherited from the Account class to credit the payee and debit
the payer of the check.
The print method overrides the print instance method defined in the Account
class. It invokes the overridden print method to display account status, and also
displays the check fee. CheckFee is an instance data item defined in the subclass.
(The Account class was shown in Example: defining a method on page 594.)
CheckingAccount class (subclass of Account)
cbl dll,thread,pgmname(longmixed)
Identification Division.
Class-id. CheckingAccount inherits Account.
Environment Division.
Configuration section.
Repository.
Class CheckingAccount is "CheckingAccount"
Class Check is "Check"
Class Account is "Account".
*
* (FACTORY paragraph not shown)
*
Identification division.
Object.
Data division.
Working-storage section.
01 CheckFee pic S9(9) value 1.
Procedure Division.
*
* processCheck method to get the check amount and payee,
* add the check fee, and invoke inherited methods debit
* to debit the payer and credit to credit the payee:
Identification Division.
Method-id. "processCheck".
Data division.
Local-storage section.
01 amount pic S9(9) binary.
01 payee usage object reference Account.
Linkage section.
01 aCheck usage object reference Check.
*
Procedure Division using by value aCheck.
Invoke aCheck "getAmount" returning amount
Invoke aCheck "getPayee" returning payee
Invoke payee "credit" using by value amount
Add checkFee to amount
Invoke self "debit" using by value amount.
End method "processCheck".
*
* print method override to display account status:
Identification Division.
610 Enterprise COBOL for z/OS, V5.2 Programming Guide
Method-id. "print".
Data division.
Local-storage section.
01 printableFee pic $$,$$$,$$9.
Procedure Division.
Invoke super "print"
Move CheckFee to printableFee
Display " Check fee: " printableFee.
End method "print".
*
End Object.
*
End class CheckingAccount.
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Invoking methods (INVOKE) on page 600
Overriding an instance method on page 591
Invoking overridden superclass methods on page 604
Defining a factory section
Use the FACTORY paragraph in a class definition to define data and methods that
are to be associated with the class itself rather than with individual object
instances.
COBOL factory data is equivalent to Java private static data. A single copy of the
data is instantiated for the class and is shared by all object instances of the class.
You most commonly use factory data when you want to gather data from all the
instances of a class. For example, you could define a factory data item to keep a
running total of the number of instances of the class that are created.
COBOL factory methods are equivalent to Java public static methods. The methods
are supported by the class independently of any object instance. You most
commonly use factory methods to customize object creation when you cannot use
VALUE clauses alone to initialize instance data.
By contrast, you use the OBJECT paragraph in a class definition to define data that
is created for each object instance of the class, and methods that are supported for
each object instance of the class.
A factory definition consists of three divisions, followed by an END FACTORY
statement:
Table 80. Structure of factory definitions
Division Purpose Syntax
IDENTIFICATION Identify the start of the IDENTIFICATION DIVISION.
(required) factory definition. FACTORY.
DATA (optional) Describe data that is WORKING-STORAGE SECTION for
allocated once for the defining factory data on page 612
class (as opposed to data (optional)
allocated for each instance
of a class).
PROCEDURE Define factory methods. Factory method definitions: Defining a
(optional) factory method on page 612
Chapter 30. Writing object-oriented programs 611
Example: defining a factory (with methods) on page 615
RELATED TASKS
Defining a class on page 582
Instantiating COBOL classes on page 605
Wrapping procedure-oriented COBOL programs on page 620
Structuring OO applications on page 620
WORKING-STORAGE SECTION for defining factory data
Use the WORKING-STORAGE SECTION in the DATA DIVISION of the FACTORY paragraph
to describe the factory data that a COBOL class needs, that is, statically allocated
data to be shared by all object instances of the class.
The FACTORY keyword, which you must immediately precede with an
IDENTIFICATION DIVISION declaration, indicates the beginning of the definitions of
the factory data and factory methods for the class. For example, the definition of
the factory data for the Account class might look like this:
IDENTIFICATION DIVISION.
Factory.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 NumberOfAccounts pic 9(6) value zero.
. . .
End Factory.
You can initialize simple factory data by using VALUE clauses as shown above.
COBOL factory data is equivalent to Java private static data. No other class or
subclass (nor instance method in the same class, if any) can reference COBOL
factory data directly. Factory data is global to all factory methods that the FACTORY
paragraph defines. If you want to make factory data accessible from outside the
FACTORY paragraph, define factory attribute (get or set) methods for doing so.
RELATED TASKS
Coding attribute (get and set) methods on page 593
Instantiating COBOL classes on page 605
Defining a factory method
Define COBOL factory methods in the PROCEDURE DIVISION of the FACTORY paragraph
of a class definition. A factory method defines an operation that is supported by a
class independently of any object instance of the class. COBOL factory methods are
equivalent to Java public static methods.
You typically define factory methods for classes whose instances require complex
initialization, that is, to values that you cannot assign by using VALUE clauses alone.
Within a factory method you can invoke instance methods to initialize the instance
data. A factory method cannot directly access instance data.
You can code factory attribute (get and set) methods to make factory data
accessible from outside the FACTORY paragraph, for example, to make the data
accessible from instance methods in the same class or from a client program. For
example, the Account class could define a factory method getNumberOfAccounts
to return the current tally of the number of accounts.
You can use factory methods to wrap procedure-oriented COBOL programs so that
they are accessible from Java programs. You can code a factory method called main
612 Enterprise COBOL for z/OS, V5.2 Programming Guide
to enable you to run an OO application by using the java command, and to
structure your applications in keeping with standard Java practice. See the related
tasks for details.
In defining factory methods, you use the same syntax that you use to define
instance methods. A COBOL factory method definition consists of four divisions
(like a COBOL program), followed by an END METHOD marker:
Table 81. Structure of factory method definitions
Division Purpose Syntax
IDENTIFICATION Same as for a class Same as for a class instance method
(required) instance method (required)
ENVIRONMENT Same as for a class Same as for a class instance method
(optional) instance method
DATA (optional) Same as for a class Same as for a class instance method
instance method
PROCEDURE Same as for a class Same as for a class instance method
(optional) instance method
Within a class definition, you do not need to make each factory method-name
unique, but you do need to give each factory method a unique signature. You can
overload factory methods in exactly the same way that you overload instance
methods. For example, the CheckingAccount subclass provides two versions of the
factory method createCheckingAccount: one that initializes the account to have a
default balance of zero, and one that allows the opening balance to be passed in.
Clients can invoke either createCheckingAccount method by passing arguments
that match the signature of the intended method.
If you define a data item with the same name in both the DATA DIVISION of a
factory method and the DATA DIVISION of the FACTORY paragraph, a reference in the
method to that data-name refers only to the method data item. The method DATA
DIVISION takes precedence.
Example: defining a factory (with methods) on page 615
RELATED TASKS
Structuring OO applications on page 620
Wrapping procedure-oriented COBOL programs on page 620
Instantiating COBOL classes on page 605
Defining a class instance method on page 587
Coding attribute (get and set) methods on page 593
Overloading an instance method on page 592
Hiding a factory or static method
Invoking factory or static methods on page 614
Using object-oriented COBOL and Java under IMS on page 448
Hiding a factory or static method
A factory method defined in a subclass is said to hide an inherited COBOL or Java
method that would otherwise be accessible in the subclass if the two methods have
the same signature.
To hide a superclass factory method f1 in a COBOL subclass, define a factory
method f1 in the subclass that has the same name and whose PROCEDURE DIVISION
USING phrase (if any) has the same number and type of formal parameters as the
Chapter 30. Writing object-oriented programs 613
superclass method has. (If the superclass method is implemented in Java, you must
code formal parameters that are interoperable with the data types of the
corresponding Java parameters.) When a client invokes f1 using the subclass name,
the subclass method rather than the superclass method is invoked.
The presence or absence of a method return value and the data type of the return
value used in the PROCEDURE DIVISION RETURNING phrase (if any) must be identical
in the subclass factory method and the hidden superclass method.
A factory method must not hide an instance method in a Java or COBOL
superclass.
Example: defining a factory (with methods) on page 615
RELATED TASKS
Coding interoperable data types in COBOL and Java on page 628
Overriding an instance method on page 591
Invoking methods (INVOKE) on page 600
RELATED REFERENCES
The Java Language Specification (Inheritance, overriding, and hiding)
The procedure division header (Enterprise COBOL Language Reference)
Invoking factory or static methods
To invoke a COBOL factory method or Java static method in a COBOL method or
client program, code the class-name as the first operand of the INVOKE statement.
For example, a client program could invoke one of the overloaded
CheckingAccount factory methods called createCheckingAccount to create a
checking account with account number 777777 and an opening balance of $300 by
coding this statement:
Invoke CheckingAccount "createCheckingAccount"
using by value 777777 300
returning aCheckingAccount
To invoke a factory method from within the same class in which you define the
factory method, you also use the class-name as the first operand in the INVOKE
statement.
Code the name of the method to be invoked either as a literal or as an identifier
whose value at run time is the method-name. The method-name must be an
alphanumeric or national literal or a category alphabetic, alphanumeric, or national
data item, and is interpreted in a case-sensitive manner.
If an invoked method is not supported in the class that you name in the INVOKE
statement, a severity-3 Language Environment condition is raised at run time
unless you code the ON EXCEPTION phrase in the INVOKE statement.
The conformance requirements for passing arguments to a COBOL factory method
or Java static method in the USING phrase, and receiving a return value in the
RETURNING phrase, are the same as those for invoking instance methods.
Example: defining a factory (with methods) on page 615
RELATED TASKS
Invoking methods (INVOKE) on page 600
614 Enterprise COBOL for z/OS, V5.2 Programming Guide
Using national data (Unicode) in COBOL on page 130
Coding interoperable data types in COBOL and Java on page 628
RELATED REFERENCES
INVOKE statement (Enterprise COBOL Language Reference)
Example: defining a factory (with methods)
The following example updates the previous examples to show the definition of
factory data and methods.
These updates are shown:
v The Account class adds factory data and a parameterized factory method,
createAccount, which allows an Account instance to be created using an account
number that is passed in.
v The CheckingAccount subclass adds factory data and an overloaded
parameterized factory method, createCheckingAccount. One implementation of
createCheckingAccount initializes the account with a default balance of zero, and
the other allows the opening balance to be passed in. Clients can invoke either
method by passing arguments that match the signature of the required method.
v The TestAccounts client invokes the services provided by the factory methods of
the Account and CheckingAccount classes, and instantiates the Java Check class.
v The output from the TestAccounts client program is shown.
(The previous examples were Example: defining a method on page 594,
Example: defining a client on page 606, and Example: defining a subclass (with
methods) on page 610.)
You can also find the complete source code for this example in the
cobol/demo/oosample subdirectory in the z/OS UNIX file system. Typically the
complete path for the source is /usr/lpp/cobol/demo/oosample. You can use the
makefile there to compile and link the code.
Account class
cbl dll,thread,pgmname(longmixed)
Identification Division.
Class-id. Account inherits Base.
Environment Division.
Configuration section.
Repository.
Class Base is "java.lang.Object"
Class Account is "Account".
*
Identification division.
Factory.
Data division.
Working-storage section.
01 NumberOfAccounts pic 9(6) value zero.
*
Procedure Division.
*
* createAccount method to create a new Account
* instance, then invoke the OBJECT paragraphs init
* method on the instance to initialize its instance data:
Identification Division.
Method-id. "createAccount".
Data division.
Linkage section.
01 inAccountNumber pic S9(6) binary.
01 outAccount object reference Account.
Chapter 30. Writing object-oriented programs 615
* Facilitate access to JNI services:
Copy JNI.
Procedure Division using by value inAccountNumber
returning outAccount.
* Establish addressability to JNI environment structure:
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
Invoke Account New returning outAccount
Invoke outAccount "init" using by value inAccountNumber
Add 1 to NumberOfAccounts.
End method "createAccount".
*
End Factory.
*
Identification division.
Object.
Data division.
Working-storage section.
01 AccountNumber pic 9(6).
01 AccountBalance pic S9(9) value zero.
*
Procedure Division.
*
* init method to initialize the account:
Identification Division.
Method-id. "init".
Data division.
Linkage section.
01 inAccountNumber pic S9(9) binary.
Procedure Division using by value inAccountNumber.
Move inAccountNumber to AccountNumber.
End method "init".
*
* getBalance method to return the account balance:
Identification Division.
Method-id. "getBalance".
Data division.
Linkage section.
01 outBalance pic S9(9) binary.
Procedure Division returning outBalance.
Move AccountBalance to outBalance.
End method "getBalance".
*
* credit method to deposit to the account:
Identification Division.
Method-id. "credit".
Data division.
Linkage section.
01 inCredit pic S9(9) binary.
Procedure Division using by value inCredit.
Add inCredit to AccountBalance.
End method "credit".
*
* debit method to withdraw from the account:
Identification Division.
Method-id. "debit".
Data division.
Linkage section.
01 inDebit pic S9(9) binary.
Procedure Division using by value inDebit.
Subtract inDebit from AccountBalance.
End method "debit".
*
* print method to display formatted account number and balance:
Identification Division.
Method-id. "print".
Data division.
616 Enterprise COBOL for z/OS, V5.2 Programming Guide
Local-storage section.
01 PrintableAccountNumber pic ZZZZZZ999999.
01 PrintableAccountBalance pic $$$$,$$$,$$9CR.
Procedure Division.
Move AccountNumber to PrintableAccountNumber
Move AccountBalance to PrintableAccountBalance
Display " Account: " PrintableAccountNumber
Display " Balance: " PrintableAccountBalance.
End method "print".
*
End Object.
*
End class Account.
CheckingAccount class (subclass of Account)
cbl dll,thread,pgmname(longmixed)
Identification Division.
Class-id. CheckingAccount inherits Account.
Environment Division.
Configuration section.
Repository.
Class CheckingAccount is "CheckingAccount"
Class Check is "Check"
Class Account is "Account".
*
Identification division.
Factory.
Data division.
Working-storage section.
01 NumberOfCheckingAccounts pic 9(6) value zero.
*
Procedure Division.
*
* createCheckingAccount overloaded method to create a new
* CheckingAccount instance with a default balance, invoke
* inherited instance method init to initialize the account
* number, and increment factory data tally of checking accounts:
Identification Division.
Method-id. "createCheckingAccount".
Data division.
Linkage section.
01 inAccountNumber pic S9(6) binary.
01 outCheckingAccount object reference CheckingAccount.
* Facilitate access to JNI services:
Copy JNI.
Procedure Division using by value inAccountNumber
returning outCheckingAccount.
* Establish addressability to JNI environment structure:
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
Invoke CheckingAccount New returning outCheckingAccount
Invoke outCheckingAccount "init"
using by value inAccountNumber
Add 1 to NumberOfCheckingAccounts.
End method "createCheckingAccount".
*
* createCheckingAccount overloaded method to create a new
* CheckingAccount instance, invoke inherited instance methods
* init to initialize the account number and credit to set the
* balance, and increment factory data tally of checking accounts:
Identification Division.
Method-id. "createCheckingAccount".
Data division.
Linkage section.
01 inAccountNumber pic S9(6) binary.
01 inInitialBalance pic S9(9) binary.
01 outCheckingAccount object reference CheckingAccount.
Chapter 30. Writing object-oriented programs 617
Copy JNI.
Procedure Division using by value inAccountNumber
inInitialBalance
returning outCheckingAccount.
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
Invoke CheckingAccount New returning outCheckingAccount
Invoke outCheckingAccount "init"
using by value inAccountNumber
Invoke outCheckingAccount "credit"
using by value inInitialBalance
Add 1 to NumberOfCheckingAccounts.
End method "createCheckingAccount".
*
End Factory.
*
Identification division.
Object.
Data division.
Working-storage section.
01 CheckFee pic S9(9) value 1.
Procedure Division.
*
* processCheck method to get the check amount and payee,
* add the check fee, and invoke inherited methods debit
* to debit the payer and credit to credit the payee:
Identification Division.
Method-id. "processCheck".
Data division.
Local-storage section.
01 amount pic S9(9) binary.
01 payee usage object reference Account.
Linkage section.
01 aCheck usage object reference Check.
Procedure Division using by value aCheck.
Invoke aCheck "getAmount" returning amount
Invoke aCheck "getPayee" returning payee
Invoke payee "credit" using by value amount
Add checkFee to amount
Invoke self "debit" using by value amount.
End method "processCheck".
*
* print method override to display account status:
Identification Division.
Method-id. "print".
Data division.
Local-storage section.
01 printableFee pic $$,$$$,$$9.
Procedure Division.
Invoke super "print"
Move CheckFee to printableFee
Display " Check fee: " printableFee.
End method "print".
*
End Object.
*
End class CheckingAccount.
Check class
/**
* A Java class for check information
*/
public class Check {
private CheckingAccount payer;
private Account payee;
private int amount;
618 Enterprise COBOL for z/OS, V5.2 Programming Guide
public Check(CheckingAccount inPayer, Account inPayee, int inAmount) {
payer=inPayer;
payee=inPayee;
amount=inAmount;
}
public int getAmount() {
return amount;
}
public Account getPayee() {
return payee;
}
}
TestAccounts client program
cbl dll,thread,pgmname(longmixed)
Identification division.
Program-id. "TestAccounts" recursive.
Environment division.
Configuration section.
Repository.
Class Account is "Account"
Class CheckingAccount is "CheckingAccount"
Class Check is "Check".
Data Division.
* Working data is declared in Local-storage
* so that each thread has its own copy:
Local-storage section.
01 anAccount usage object reference Account.
01 aCheckingAccount usage object reference CheckingAccount.
01 aCheck usage object reference Check.
01 payee usage object reference Account.
*
Procedure division.
Test-Account-section.
Display "Test Account class"
* Create account 123456 with 0 balance:
Invoke Account "createAccount"
using by value 123456
returning anAccount
* Deposit 500 to the account:
Invoke anAccount "credit" using by value 500
Invoke anAccount "print"
Display space
*
Display "Test CheckingAccount class"
* Create checking account 777777 with balance of 300:
Invoke CheckingAccount "createCheckingAccount"
using by value 777777 300
returning aCheckingAccount
* Set account 123456 as the payee:
Set payee to anAccount
* Initialize check for 125 to be paid by account 777777 to payee:
Invoke Check New
using by value aCheckingAccount, payee, 125
returning aCheck
* Debit the payer, and credit the payee:
Invoke aCheckingAccount "processCheck"
using by value aCheck
Invoke aCheckingAccount "print"
Invoke anAccount "print"
*
Stop Run.
End program "TestAccounts".
Chapter 30. Writing object-oriented programs 619
Output produced by the TestAccounts client program
Test Account class
Account: 123456
Balance: $500
Test CheckingAccount class
Account: 777777
Balance: $174
Check fee: $1
Account: 123456
Balance: $625
RELATED TASKS
Creating and initializing instances of classes on page 604
Defining a factory method on page 612
Invoking factory or static methods on page 614
Chapter 16, Compiling, linking, and running OO applications, on page 291
Wrapping procedure-oriented COBOL programs
A wrapper is a class that provides an interface between object-oriented code and
procedure-oriented code. Factory methods provide a convenient means for writing
wrappers for existing procedural COBOL code to make it accessible from Java
programs.
To wrap COBOL code, do these steps:
1. Create a simple COBOL class that contains a FACTORY paragraph.
2. In the FACTORY paragraph, code a factory method that uses a CALL statement to
call the procedural program.
A Java program can invoke the factory method by using a static method invocation
expression, thus invoking the COBOL procedural program.
RELATED TASKS
Defining a class on page 582
Defining a factory section on page 611
Defining a factory method on page 612
Structuring OO applications
You can structure applications that use object-oriented COBOL syntax in one of
three ways.
An OO application can begin with:
v A COBOL program, which can have any name.
Under z/OS UNIX, you can run the application by specifying the name of the
linked module (which should match the program name) at the command
prompt. You can also bind the program as a module in a PDSE and run it in JCL
using the EXEC PGM statement.
v A Java class definition that contains a method called main. Declare main as
public, static, and void, with a single parameter of type String[].
You can run the application with the java command, specifying the name of the
class that contains main, and zero or more strings as command-line arguments.
v A COBOL class definition that contains a factory method called main. Declare
main with no RETURNING phrase and a single USING parameter, an object reference
620 Enterprise COBOL for z/OS, V5.2 Programming Guide
to a class that is an array with elements of type java.lang.String. (Thus main is in
effect public, static, and void, with a single parameter of type String[].)
You can run the application with the java command, specifying the name of the
class that contains main, and zero or more strings as command-line arguments.
Structure an OO application this way if you want to:
Run the application by using the java command.
Run the application in an environment where applications must start with the
main method of a Java class (such as a Java dependent region).
Follow standard Java programming practice.
Examples: COBOL applications that run using the java command
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Defining a factory method on page 612
Declaring arrays and strings for Java on page 629
Chapter 22, Developing COBOL programs for IMS, on page 443
Examples: COBOL applications that run using the java
command
The following examples show COBOL class definitions that contain a factory
method called main.
In each case, main has no RETURNING phrase and has a single USING parameter, an
object reference to a class that is an array with elements of type java.lang.String.
You can run these applications by using the java command.
Displaying a message
cbl dll,thread
Identification Division.
Class-id. CBLmain inherits Base.
Environment Division.
Configuration section.
Repository.
Class Base is "java.lang.Object"
Class stringArray is "jobjectArray:java.lang.String"
Class CBLmain is "CBLmain".
*
Identification Division.
Factory.
Procedure division.
*
Identification Division.
Method-id. "main".
Data division.
Linkage section.
01 SA usage object reference stringArray.
Procedure division using by value SA.
Display " >> COBOL main method entered"
.
End method "main".
End factory.
End class CBLmain.
Echoing the input strings
cbl dll,thread,pgmname(longmixed),ssrange
Identification Division.
Class-id. Echo inherits Base.
Environment Division.
Chapter 30. Writing object-oriented programs 621
Configuration section.
Repository.
Class Base is "java.lang.Object"
Class stringArray is "jobjectArray:java.lang.String"
Class jstring is "java.lang.String"
Class Echo is "Echo".
*
Identification Division.
Factory.
Procedure division.
*
Identification Division.
Method-id. "main".
Data division.
Local-storage section.
01 SAlen pic s9(9) binary.
01 I pic s9(9) binary.
01 SAelement object reference jstring.
01 SAelementlen pic s9(9) binary.
01 Sbuffer pic X(65535).
01 P pointer.
Linkage section.
01 SA object reference stringArray.
Copy "JNI.cpy" suppress.
Procedure division using by value SA.
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
Call GetArrayLength using by value JNIEnvPtr SA
returning SAlen
Display "Input string array length: " SAlen
Display "Input strings:"
Perform varying I from 0 by 1 until I = SAlen
Call GetObjectArrayElement
using by value JNIEnvPtr SA I
returning SAelement
Call "GetStringPlatformLength"
using by value JNIEnvPtr
SAelement
address of SAelementlen
0
Call "GetStringPlatform"
using by value JNIEnvPtr
SAelement
address of Sbuffer
length of Sbuffer
0
Display Sbuffer(1:SAelementlen)
End-perform
.
End method "main".
End factory.
End class Echo.
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Defining a factory method on page 612
Chapter 31, Communicating with Java methods, on page 623
622 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 31. Communicating with Java methods
To achieve interlanguage interoperability with Java, you need to follow certain
rules and guidelines for using services in the Java Native Interface (JNI), coding
data types, and compiling COBOL programs.
You can invoke methods that are written in Java from COBOL programs, and you
can invoke methods that are written in COBOL from Java programs. You need to
code COBOL object-oriented language for basic Java object capabilities. For
additional Java capabilities, you can call JNI services.
Because Java programs might be multithreaded and use asynchronous signals,
compile COBOL programs with the THREAD option.
Example: J2EE client written in COBOL on page 634
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
Accessing JNI services
Sharing data with Java on page 627
Chapter 30, Writing object-oriented programs, on page 579
Chapter 27, Preparing COBOL programs for multithreading, on page 507
RELATED REFERENCES
JDK 5.0 Documentation
Accessing JNI services
The Java Native Interface (JNI) provides many callable services that you can use
when you develop applications that mix COBOL and Java. To facilitate access to
these services, copy JNI.cpy into the LINKAGE SECTION of your COBOL program.
The JNI.cpy copybook contains these definitions:
v COBOL data definitions that correspond to the Java JNI types
v JNINativeInterface, the JNI environment structure that contains function pointers
for accessing the callable service functions
You obtain the JNI environment structure by two levels of indirection from the JNI
environment pointer, as the following illustration shows:
JNIEnvPtr
pointer pointer JNI function
Private per- pointer
thread data JNI function
pointer
...
JNI function
Use the special register JNIEnvPtr to reference the JNI environment pointer to
obtain the address for the JNI environment structure. JNIEnvPtr is implicitly
Copyright IBM Corp. 1991, 2015 623
defined as USAGE POINTER; do not use it as a receiving data item. Before you
reference the contents of the JNI environment structure, you must code the
following statements to establish its addressability:
Linkage section.
COPY JNI
. . .
Procedure division.
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
. . .
The code above sets the addresses of the following items:
v JNIEnv, a pointer data item that JNI.cpy provides. JNIEnvPtr is the COBOL
special register that contains the environment pointer.
v JNINativeInterface, the COBOL group structure that JNI.cpy contains. This
structure maps the JNI environment structure, which contains an array of
function pointers for the JNI callable services.
After you code the statements above, you can access the JNI callable services with
CALL statements that reference the function pointers. You can pass the JNIEnvPtr
special register as the first argument to the services that require the environment
pointer, as shown in the following example:
01 InputArrayObj usage object reference jlongArray.
01 ArrayLen pic S9(9) comp-5.
. . .
Call GetArrayLength using by value JNIEnvPtr InputArrayObj
returning ArrayLen
Important: Pass all arguments to the JNI callable services by value.
Some JNI callable services require a Java class-object reference as an argument. To
obtain a reference to the class object that is associated with a class, use one of the
following JNI callable services:
v GetObjectClass
v FindClass
Restriction: The JNI environment pointer is thread specific. Do not pass it from
one thread to another.
RELATED TASKS
Managing local and global references on page 626
Handling Java exceptions
Coding interoperable data types in COBOL and Java on page 628
Defining a client on page 596
RELATED REFERENCES
Appendix E, JNI.cpy copybook, on page 721
The Java Native Interface
Handling Java exceptions
Use JNI services to throw and catch Java exceptions.
Throwing an exception: Use one of the following services to throw a Java
exception from a COBOL method:
v Throw
624 Enterprise COBOL for z/OS, V5.2 Programming Guide
v ThrowNew
You must make the thrown object an instance of a subclass of java.lang.Throwable.
The Java virtual machine (JVM) does not recognize and process the thrown
exception until the method that contains the call has completed and returned to
the JVM.
Catching an exception: After you invoke a method that might have thrown a Java
exception, you can do these steps:
1. Test whether an exception occurred.
2. If an exception occurred, process the exception.
3. Clear the exception, if clearing is appropriate.
Use the following JNI services:
v ExceptionOccurred
v ExceptionCheck
v ExceptionDescribe
v ExceptionClear
To do error analysis, use the methods supported by the exception object that is
returned. This object is an instance of the java.lang.Throwable class.
Example: handling Java exceptions
Example: handling Java exceptions
The following example shows the use of JNI services for catching an exception
from Java and the use of the printStackTrace method of java.lang.Throwable for
error analysis.
Repository.
Class JavaException is "java.lang.Exception".
. . .
Local-storage section.
01 ex usage object reference JavaException.
Linkage section.
COPY "JNI.cpy".
. . .
Procedure division.
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
. . .
Invoke anObj "someMethod"
Perform ErrorCheck
. . .
ErrorCheck.
Call ExceptionOccurred
using by value JNIEnvPtr
returning ex
If ex not = null then
Call ExceptionClear using by value JNIEnvPtr
Display "Caught an unexpected exception"
Invoke ex "printStackTrace"
Stop run
End-if
Chapter 31. Communicating with Java methods 625
Managing local and global references
The Java virtual machine tracks the object references that you use in native
methods, such as COBOL methods. This tracking ensures that the objects are not
prematurely released during garbage collection.
There are two classes of such references:
Local references
Local references are valid only while the method that you invoke runs.
Automatic freeing of the local references occurs after the native method
returns.
Global references
Global references remain valid until you explicitly delete them. You can
create global references from local references by using the JNI service
NewGlobalRef.
The following object references are always local:
v Object references that are received as method parameters
v Object references that are returned as the method RETURNING value from a
method invocation
v Object references that are returned by a call to a JNI function
v Object references that you create by using the INVOKE . . . NEW statement
You can pass either a local reference or a global reference as an object reference
argument to a JNI service.
You can code methods to return either local or global references as RETURNING
values. However, in either case, the reference that is received by the invoking
program is a local reference.
You can pass either local or global references as USING arguments in a method
invocation. However, in either case, the reference that is received by the invoked
method is a local reference.
Local references are valid only in the thread in which you create them. Do not pass
them from one thread to another.
RELATED TASKS
Accessing JNI services on page 623
Deleting, saving, and freeing local references
Deleting, saving, and freeing local references
You can manually delete local references at any point within a method. Save local
references only in object references that you define in the LOCAL-STORAGE SECTION
of a method.
Use a SET statement to convert a local reference to a global reference if you want to
save a reference in any of these data items:
v An object instance variable
v A factory variable
v A data item in the WORKING-STORAGE SECTION of a method
Otherwise, an error occurs. These storage areas persist when a method returns;
therefore a local reference is no longer valid.
626 Enterprise COBOL for z/OS, V5.2 Programming Guide
In most cases you can rely on the automatic freeing of local references that occurs
when a method returns. However, in some cases you should explicitly free a local
reference within a method by using the JNI service DeleteLocalRef. Here are two
situations where explicit freeing is appropriate:
v In a method you access a large object, thereby creating a local reference to the
object. After extensive computations, the method returns. Free the large object if
you do not need it for the additional computations, because the local reference
prevents the object from being released during garbage collection.
v You create a large number of local references in a method, but do not use all of
them at the same time. Because the Java virtual machine requires space to keep
track of each local reference, you should free those that you no longer need.
Freeing the local references helps prevent the system from running out of
memory.
For example, in a COBOL method you loop through a large array of objects,
retrieve the elements as local references, and operate on one element at each
iteration. You can free the local reference to the array element after each
iteration.
Use the following callable services to manage local references and global
references.
Table 82. JNI services for local and global references
Service Input arguments Return value Purpose
NewGlobalRef v The JNI environment The global reference, or To create a new global
pointer NULL if the system is out of reference to the object that
memory the input object reference
v A local or global object
refers to
reference
DeleteGlobalRef v The JNI environment None To delete a global reference
pointer to the object that the input
object reference refers to
v A global object reference
DeleteLocalRef v The JNI environment None To delete a local reference
pointer to the object that the input
object reference refers to
v A local object reference
RELATED TASKS
Accessing JNI services on page 623
Java access controls
The Java access modifiers protected and private are not enforced when you use
the Java Native Interface. Therefore a COBOL program could invoke a protected or
private Java method that is not invocable from a Java client. This usage is not
recommended.
Sharing data with Java
You can share the COBOL data types that have Java equivalents. (Some COBOL
data types have Java equivalents, but others do not.)
Share data items with Java in these ways:
v Pass them as arguments in the USING phrase of an INVOKE statement.
v Receive them as parameters in the USING phrase from a Java method.
Chapter 31. Communicating with Java methods 627
v Receive them as the RETURNING value in an INVOKE statement.
v Return them as the value in the RETURNING phrase of the PROCEDURE DIVISION
header in a COBOL method.
To pass or receive arrays and strings, declare them as object references:
v Declare an array as an object reference that contains an instance of one of the
special array classes.
v Declare a string as an object reference that contains an instance of the jstring
class.
RELATED TASKS
Coding interoperable data types in COBOL and Java
Declaring arrays and strings for Java on page 629
Manipulating Java arrays on page 630
Manipulating Java strings on page 632
Invoking methods (INVOKE) on page 600
Chapter 25, Sharing data, on page 481
Coding interoperable data types in COBOL and Java
Your COBOL program can use only certain data types when communicating with
Java.
Table 83. Interoperable data types in COBOL and Java
Primitive Java data
type Corresponding COBOL data type
1
boolean PIC X followed by exactly two condition-names of this form:
level-number data-name PIC X.
88 data-name-false value X00.
88 data-name-true value X01 through XFF.
byte1 Single-byte alphanumeric: PIC X or PIC A
short USAGE BINARY, COMP, COMP-4, or COMP-5, with PICTURE clause of the
form S9(n), where 1<=n<=4
int USAGE BINARY, COMP, COMP-4, or COMP-5, with PICTURE clause of the
form S9(n), where 5<=n<=9
long USAGE BINARY, COMP, COMP-4, or COMP-5, with PICTURE clause of the
form S9(n), where 10<=n<=18
float2 USAGE COMP-1
2
double USAGE COMP-2
char Single-character elementary national: PIC N USAGE NATIONAL.
(Cannot be a national group.)
class types (object USAGE OBJECT REFERENCE class-name
references)
1. You must distinguish boolean from byte, because they each correspond to PIC X. PIC X
is interpreted as boolean only if you define an argument or a parameter with the two
condition-names as shown. Otherwise, a PIC X data item is interpreted as the Java byte
type.
2. Java floating-point data is formatted according to the IEEE Standard for Binary Floating
Point Arithmetic. Enterprise COBOL, however, uses hexadecimal floating-point
representation. When you pass floating-point arguments by using an INVOKE statement,
or you receive floating-point data from a Java method, the arguments and data are
automatically converted as needed.
628 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Using national data (Unicode) in COBOL on page 130
Declaring arrays and strings for Java
When you communicate with Java, declare arrays by using the special array
classes, and declare strings by using jstring. Code the COBOL data types shown in
the table below.
Table 84. Interoperable arrays and strings in COBOL and Java
Java data type Corresponding COBOL data type
boolean[ ] object reference jbooleanArray
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
To use one of these classes for interoperability with Java, you must code an entry
in the REPOSITORY paragraph. For example:
Configuration section.
Repository.
Class jbooleanArray is "jbooleanArray".
The REPOSITORY paragraph entry for an object array type must specify an external
class-name in one of these forms:
"jobjectArray"
"jobjectArray:external-classname-2"
In the first case, the REPOSITORY entry specifies an array class in which the elements
of the array are objects of type java.lang.Object. In the second case, the REPOSITORY
entry specifies an array class in which the elements of the array are objects of type
external-classname-2. Code a colon as the separator between the specification of the
jobjectArray type and the external class-name of the array elements.
The following example shows both cases. In the example, oa defines an array of
elements that are objects of type java.lang.Object. aDepartment defines an array of
elements that are objects of type com.acme.Employee.
Environment Division.
Configuration Section.
Repository.
Class jobjectArray is "jobjectArray"
Class Employee is "com.acme.Employee"
Class Department is "jobjectArray:com.acme.Employee".
. . .
Linkage section.
01 oa usage object reference jobjectArray.
01 aDepartment usage object reference Department.
. . .
Procedure division using by value aDepartment.
. . .
Examples: COBOL applications that run using the java command on page 621
Chapter 31. Communicating with Java methods 629
The following Java array types are currently not supported for interoperation with
COBOL programs.
Table 85. Noninteroperable array types in COBOL and Java
Java data type Corresponding COBOL data type
float[ ] object reference jfloatArray
double[ ] object reference jdoubleArray
RELATED TASKS
REPOSITORY paragraph for defining a class on page 584
Manipulating Java arrays
To represent an array in a COBOL program, code a group item that contains a
single elementary item that is of the data type that corresponds to the Java type of
the array. Specify an OCCURS or OCCURS DEPENDING ON clause that is appropriate for
the array.
For example, the following code specifies a structure to receive 500 or fewer
integer values from a jlongArray object:
01 longArray.
02 X pic S9(10) comp-5 occurs 1 to 500 times depending on N.
To operate on objects of the special Java-array classes, call the services that the JNI
provides. You can use services to access and set individual elements of an array
and for the following purposes, using the services cited:
Table 86. JNI array services
Service Input arguments Return value Purpose
GetArrayLength v The JNI environment pointer The array length as To get the number of
a binary fullword elements in a Java
v The array object reference
integer array object
NewBooleanArray, v The JNI environment pointer The array object To create a new Java
NewByteArray, NewCharArray, reference, or NULL if array object
v The number of elements in the
NewShortArray, NewIntArray, the array cannot be
array, as a binary fullword
NewLongArray constructed
integer
GetBooleanArrayElements, v The JNI environment pointer A pointer to the To extract the array
GetByteArrayElements, storage buffer elements from a Java
v The array object reference
GetCharArrayElements, array into a storage
GetShortArrayElements, v A pointer to a boolean item. If buffer. The services
GetIntArrayElements, the pointer is not null, the return a pointer to the
GetLongArrayElements boolean item is set to true if a storage buffer, which
copy of the array elements was you can use as the
made. If a copy was made, the address of a COBOL
corresponding group data item
ReleasexxxArrayElements service defined in the LINKAGE
must be called if changes are to SECTION.
be written back to the array
object.
630 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 86. JNI array services (continued)
Service Input arguments Return value Purpose
ReleaseBooleanArrayElements, v The JNI environment pointer None; the storage To release the storage
ReleaseByteArrayElements, for the array is buffer that contains
v The array object reference
ReleaseCharArrayElements, released. elements that have
ReleaseShortArrayElements, v A pointer to the storage buffer been extracted from a
ReleaseIntArrayElements, v The release mode, as a binary Java array, and
ReleaseLongArrayElements fullword integer. See Java JNI conditionally map the
documentation for details. updated array values
(Recommendation: Specify 0 to back into the array
copy back the array content and object
free the storage buffer.)
NewObjectArray v The JNI environment pointer The array object To create a new Java
reference, or NULL if object array
v The number of elements in the
the array cannot be
array, as a binary fullword
constructed1
integer
v An object reference for the array
element class
v An object reference for the initial
element value. All array elements
are set to this value.
GetObjectArrayElement v The JNI environment pointer An object reference2 To return the element
at a given index within
v The array object reference
an object array
v An array element index, as a
binary fullword integer using
origin zero
SetObjectArrayElement v The JNI environment pointer None3 To set an element
within an object array
v The array object reference
v The array element index, as a
binary fullword integer using
origin zero
v The object reference for the new
value
1. NewObjectArray throws an exception if the system runs out of memory.
2. GetObjectArrayElement throws an exception if the index is not valid.
3. SetObjectArrayElement throws an exception if the index is not valid or if the new value is not a subclass of the
element class of the array.
Examples: COBOL applications that run using the java command on page 621
Example: processing a Java integer array
RELATED TASKS
Coding interoperable data types in COBOL and Java on page 628
Declaring arrays and strings for Java on page 629
Accessing JNI services on page 623
Example: processing a Java integer array
The following example shows the use of the Java-array classes and JNI services to
process a Java integer array in COBOL.
cbl thread,dll
Identification division.
Class-id. OOARRAY inherits Base.
Chapter 31. Communicating with Java methods 631
Environment division.
Configuration section.
Repository.
Class Base is "java.lang.Object"
Class jintArray is "jintArray".
Identification division.
Object.
Procedure division.
Identification division.
Method-id. "ProcessArray".
Data Division.
Local-storage section.
01 intArrayPtr pointer.
01 intArrayLen pic S9(9) comp-5.
Linkage section.
COPY JNI.
01 inIntArrayObj usage object reference jintArray.
01 intArrayGroup.
02 X pic S9(9) comp-5
occurs 1 to 1000 times depending on intArrayLen.
Procedure division using by value inIntArrayObj.
Set address of JNIEnv to JNIEnvPtr
Set address of JNINativeInterface to JNIEnv
Call GetArrayLength
using by value JNIEnvPtr inIntArrayObj
returning intArrayLen
Call GetIntArrayElements
using by value JNIEnvPtr inIntArrayObj 0
returning IntArrayPtr
Set address of intArrayGroup to intArrayPtr
* . . . process the array elements X(I) . . .
Call ReleaseIntArrayElements
using by value JNIEnvPtr inIntArrayObj intArrayPtr 0.
End method "ProcessArray".
End Object.
End class OOARRAY.
Manipulating Java strings
COBOL represents Java String data in Unicode. To represent a Java String in a
COBOL program, declare the string as an object reference of the jstring class. Then
use JNI services to set or extract COBOL alphanumeric or national (Unicode) data
from the object.
Services for Unicode: Use the following standard services to convert between
jstring object references and COBOL USAGE NATIONAL data items. Use these services
for applications that you intend to be portable between the workstation and the
mainframe. Access these services by using function pointers in the
JNINativeInterface environment structure.
Table 87. Services that convert between jstring references and national data
Service Input arguments Return value
1
NewString v The JNI environment pointer jstring object reference
v A pointer to a Unicode string, such
as a COBOL national data item
v The number of characters in the
string; binary fullword
632 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 87. Services that convert between jstring references and national data (continued)
Service Input arguments Return value
GetStringLength v The JNI environment pointer The number of Unicode characters in the jstring
object reference; binary fullword
v A jstring object reference
1
GetStringChars v The JNI environment pointer v A pointer to the array of Unicode characters
v A jstring object reference extracted from the jstring object, or NULL if the
operation fails. The pointer is valid until it is
v A pointer to a boolean data item, or
released with ReleaseStringChars.
NULL
v If the pointer to the boolean data item is not
null, the boolean value is set to true if a copy is
made of the string and to false if no copy is
made.
ReleaseStringChars v The JNI environment pointer None; the storage for the array is released.
v A jstring object reference
v A pointer to the array of Unicode
characters that was returned from
GetStringChars
1. This service throws an exception if the system runs out of memory.
Services for EBCDIC: Use the following z/OS services, an extension of the JNI, to
convert between jstring object references and COBOL alphanumeric data (PIC
X(n)).
Table 88. Services that convert between jstring references and alphanumeric data
Service Input arguments Return value
NewStringPlatform v The JNI environment pointer Return code as a binary fullword
integer:
v Pointer to the null-terminated EBCDIC
character string that you want to convert 0 Success.
to a jstring object
-1 Malformed input or illegal
v Pointer to the jstring object reference in input character.
which you want the result
-2 Unsupported encoding; the
v Pointer to the Java encoding name for the
jstring object reference pointer
string, represented as a null-terminated
is set to NULL.
EBCDIC character string1
GetStringPlatformLength v The JNI environment pointer Return code as a binary fullword
integer:
v jstring object reference for which you want
the length 0 Success.
v Pointer to a binary fullword integer for the -1 Malformed input or illegal
result input character.
v Pointer to the Java encoding name for the
-2 Unsupported encoding; the
string, represented as a null-terminated
jstring object reference pointer
EBCDIC character string1
is set to NULL.
Returns, in the third argument, the
needed length in bytes of the output
buffer to hold the converted Java
string, including the terminating null
byte referenced by the second
argument.
Chapter 31. Communicating with Java methods 633
Table 88. Services that convert between jstring references and alphanumeric data (continued)
Service Input arguments Return value
GetStringPlatform v The JNI environment pointer Return code as a binary fullword
integer:
v jstring object reference that you want to
convert to a null-terminated string 0 Success.
v Pointer to the output buffer in which you -1 Malformed input or illegal
want the converted string input character.
v Length of the output buffer as a binary
-2 Unsupported encoding; the
fullword integer
output string is set to a null
v Pointer to the Java encoding name for the string.
string, represented as a null-terminated
EBCDIC character string1 -3 Conversion buffer is full.
1. If the pointer is NULL, the encoding from the Java file.encoding property is used.
These EBCDIC services are packaged as a DLL that is part of your IBM Java
Software Development Kit. For details about the services, see jni_convert.h in the
IBM Java Software Development Kit.
Use CALL literal statements to call the services. The calls are resolved through the
libjvm.x DLL side file, which you must include in the link step of any COBOL
program that uses object-oriented language.
For example, the following code creates a Java String object from the EBCDIC
string 'MyConverter'. (This code fragment is from the J2EE client program, which
is shown in full in Example: J2EE client written in COBOL.)
Move z"MyConverter" to stringBuf
Call "NewStringPlatform"
using by value JNIEnvPtr
address of stringBuf
address of jstring1
0
returning rc
If the EBCDIC services are the only JNI services that you call from a COBOL
program, you do not need to copy the JNI.cpy copybook. You also do not need to
establish addressability with the JNI environment pointer.
Services for UTF-8: The Java Native Interface also provides services for conversion
between jstring object references and UTF-8 strings. These services are not
recommended for use in COBOL programs due to the difficulty in handling UTF-8
character strings on the z/OS platform.
RELATED TASKS
Accessing JNI services on page 623
Coding interoperable data types in COBOL and Java on page 628
Declaring arrays and strings for Java on page 629
Using national data (Unicode) in COBOL on page 130
Chapter 16, Compiling, linking, and running OO applications, on page 291
Example: J2EE client written in COBOL
The following example shows a COBOL client program that can access enterprise
beans that run on a J2EE-compliant EJB server.
634 Enterprise COBOL for z/OS, V5.2 Programming Guide
The COBOL client is equivalent to the J2EE client program in the Getting Started
section of the Java 2 Enterprise Edition Developer's Guide. For your convenience in
comparing implementations, the second example shows the equivalent Java client
from the guide. (The enterprise bean is the Java implementation of the simple
currency-converter enterprise bean, and is in the same guide.)
You can find an alternate version of the Java enterprise bean and client code in The
Java EE 5 Tutorial, referenced below.
COBOL client (ConverterClient.cbl)
Process pgmname(longmixed),dll,thread
*****************************************************************
* Demo J2EE client written in COBOL. *
* *
* Based on the sample J2EE client written in Java, which is *
* given in the "Getting Started" chapter of "The Java(TM) 2 *
* Enterprise Edition Developers Guide." *
* *
* The client: *
* - Locates the home interface of a session enterprise bean *
* (a simple currency converter bean) *
* - Creates an enterprise bean instance *
* - Invokes a business method (currency conversion) *
*****************************************************************
Identification division.
Program-id. "ConverterClient" is recursive.
Environment Division.
Configuration section.
Repository.
Class InitialContext is "javax.naming.InitialContext"
Class PortableRemoteObject
is "javax.rmi.PortableRemoteObject"
Class JavaObject is "java.lang.Object"
Class JavaClass is "java.lang.Class"
Class JavaException is "java.lang.Exception"
Class jstring is "jstring"
Class Converter is "Converter"
Class ConverterHome is "ConverterHome".
Data division.
Working-storage section.
01 initialCtx object reference InitialContext.
01 obj object reference JavaObject.
01 classObj object reference JavaClass.
01 ex object reference JavaException.
01 currencyConverter object reference Converter.
01 home object reference ConverterHome.
01 homeObject redefines home object reference JavaObject.
01 jstring1 object reference jstring.
01 stringBuf pic X(500) usage display.
01 len pic s9(9) comp-5.
01 rc pic s9(9) comp-5.
01 amount comp-2.
Linkage section.
Copy JNI.
Procedure division.
Set address of JNIenv to JNIEnvPtr
Set address of JNINativeInterface to JNIenv
*****************************************************************
* Create JNDI naming context. *
*****************************************************************
Invoke InitialContext New returning initialCtx
Perform JavaExceptionCheck
Chapter 31. Communicating with Java methods 635
*****************************************************************
* Create a jstring object for the string "MyConverter" for use *
* as argument to the lookup method. *
*****************************************************************
Move z"MyConverter" to stringBuf
Call "NewStringPlatform"
using by value JNIEnvPtr
address of stringBuf
address of jstring1
0
returning rc
If rc not = zero then
Display "Error occurred creating jstring object"
Stop run
End-if
*****************************************************************
* Use the lookup method to obtain a reference to the home *
* object bound to the name "MyConverter". (This is the JNDI *
* name specified when deploying the J2EE application.) *
*****************************************************************
Invoke initialCtx "lookup" using by value jstring1
returning obj
Perform JavaExceptionCheck
*****************************************************************
* Narrow the home object to be of type ConverterHome. *
* First obtain class object for the ConverterHome class, by *
* passing the null-terminated ASCII string "ConverterHome" to *
* the FindClass API. Then use this class object as the *
* argument to the static method "narrow". *
*****************************************************************
Move z"ConverterHome" to stringBuf
Call "__etoa"
using by value address of stringBuf
returning len
If len = -1 then
Display "Error occurred on ASCII conversion"
Stop run
End-if
Call FindClass
using by value JNIEnvPtr
address of stringBuf
returning classObj
If classObj = null
Display "Error occurred locating ConverterHome class"
Stop run
End-if
Invoke PortableRemoteObject "narrow"
using by value obj
classObj
returning homeObject
Perform JavaExceptionCheck
*****************************************************************
* Create the ConverterEJB instance and obtain local object *
* reference for its remote interface *
*****************************************************************
Invoke home "create" returning currencyConverter
Perform JavaExceptionCheck
*****************************************************************
* Invoke business methods *
*****************************************************************
Invoke currencyConverter "dollarToYen"
using by value +100.00E+0
returning amount
636 Enterprise COBOL for z/OS, V5.2 Programming Guide
Perform JavaExceptionCheck
Display amount
Invoke currencyConverter "yenToEuro"
using by value +100.00E+0
returning amount
Perform JavaExceptionCheck
Display amount
*****************************************************************
* Remove the object and return. *
*****************************************************************
Invoke currencyConverter "remove"
Perform JavaExceptionCheck
Goback
.
*****************************************************************
* Check for thrown Java exceptions *
*****************************************************************
JavaExceptionCheck.
Call ExceptionOccurred using by value JNIEnvPtr
returning ex
If ex not = null then
Call ExceptionClear using by value JNIEnvPtr
Display "Caught an unexpected exception"
Invoke ex "printStackTrace"
Stop run
End-if
.
End program "ConverterClient".
Java client (ConverterClient.java)
/*
*
* Copyright 2000 Sun Microsystems, Inc. All Rights Reserved.
*
* This software is the proprietary information of Sun Microsystems, Inc.
* Use is subject to license terms.
*
*/
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.rmi.PortableRemoteObject;
import Converter;
import ConverterHome;
public class ConverterClient {
public static void main(String[] args) {
try {
Context initial = new InitialContext();
Object objref = initial.lookup("MyConverter");
ConverterHome home =
(ConverterHome)PortableRemoteObject.narrow(objref,
ConverterHome.class);
Converter currencyConverter = home.create();
double amount = currencyConverter.dollarToYen(100.00);
Chapter 31. Communicating with Java methods 637
System.out.println(String.valueOf(amount));
amount = currencyConverter.yenToEuro(100.00);
System.out.println(String.valueOf(amount));
currencyConverter.remove();
} catch (Exception ex) {
System.err.println("Caught an unexpected exception!");
ex.printStackTrace();
}
}
}
RELATED TASKS
Chapter 16, Compiling, linking, and running OO applications, on page 291
WebSphere for z/OS: Applications
Java 2 Enterprise Edition Developer's Guide (Getting Started)
The Java EE 5 Tutorial (Getting Started with Enterprise Beans)
638 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 7. Specialized processing
Copyright IBM Corp. 1991, 2015 639
640 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 32. Interrupts and checkpoint/restart
When programs run for an extended period of time, interruptions might halt
processing before the end of a job. The checkpoint/restart functions of z/OS let an
interrupted program be restarted at the beginning of a job step or at a checkpoint
that you have set.
Because the checkpoint/restart functions cause a lot of extra processing, use them
only when you anticipate interruptions caused by machine malfunctions, input or
output errors, or intentional operator intervention.
| The checkpoint routine starts from the COBOL program object that contains your
program. While your program is running, the checkpoint routine creates records at
points that you have designated using the COBOL RERUN clause. A checkpoint
record contains a snapshot of the information in the registers and main storage
when the program reached the checkpoint.
The restart routine restarts an interrupted program. You can perform a restart at
any time after the program was interrupted: either immediately (automatic restart),
or later (deferred restart).
RELATED TASKS
Setting checkpoints
Restarting programs on page 644
Resubmitting jobs for restart on page 647
z/OS DFSMS: Checkpoint/Restart
RELATED REFERENCES
DD statements for defining checkpoint data sets on page 643
Messages generated during checkpoint on page 644
Formats for requesting deferred restart on page 646
Setting checkpoints
To set checkpoints, use job control statements and use the RERUN clause in the
ENVIRONMENT DIVISION. Associate each RERUN clause with a particular COBOL file.
The RERUN clause indicates that a checkpoint record is to be written to a checkpoint
data set whenever a specified number of records in the COBOL file have been
processed or when END OF VOLUME is reached. You cannot use the RERUN clause with
files that are defined with the EXTERNAL attribute.
You can write checkpoint records from several COBOL files to one checkpoint data
set, but you must use a separate data set exclusively for checkpoint records. You
cannot embed checkpoint records in one of your program data sets.
Restrictions: A checkpoint data set must have sequential organization. You cannot
write checkpoints in VSAM data sets or in data sets that are allocated to
extended-format QSAM data sets. Also, a checkpoint cannot be taken if any
program in the run unit has an extended-format QSAM data set that is open.
Checkpoint records are written in the checkpoint data set defined by a DD
statement. In the DD statement, you also choose the checkpoint method:
Copyright IBM Corp. 1991, 2015 641
Single (store single checkpoints)
Only one checkpoint record exists at any given time. After the first
checkpoint record is written, any succeeding checkpoint record overlays
the previous one.
This method is acceptable for most programs. You save space in the
checkpoint data set, and you can restart your program at the latest
checkpoint.
Multiple (store multiple contiguous checkpoints)
Checkpoints are recorded and numbered sequentially. Each checkpoint is
saved.
Use this method if you want to restart a program at a checkpoint other
than the latest one taken.
| You must use the multiple checkpoint method for complete compliance with the 85
| COBOL Standard.
Checkpoints during sort operations have the following requirements:
v If checkpoints are to be taken during a sort operation, add a DD statement for
SORTCKPT in the job control procedure for execution.
v You can take checkpoint records on ASCII-collated sorts, but the system-name that
indicates the checkpoint data set must not specify an ASCII file.
RELATED TASKS
Using checkpoint/restart with DFSORT on page 236
Designing checkpoints
Testing for a successful checkpoint
RELATED REFERENCES
DD statements for defining checkpoint data sets on page 643
Designing checkpoints
Design your checkpoints at critical points in your program so that data can be
easily reconstructed. Do not change the contents of files between the time of a
checkpoint and the time of the restart.
In a program that uses disk files, design the program so that you can identify
previously processed records. For example, consider a disk file that contains loan
records that are periodically updated for interest due. If a checkpoint is taken,
records are updated, and then the program is interrupted, you would want to test
that the records that are updated after the last checkpoint are not updated again
when the program is restarted. To do this, set up a date field in each record, and
update the field each time the record is processed. Then, after the restart, test the
field to determine whether the record was already processed.
For efficient repositioning of a print file, take checkpoints on the file only after
printing the last line of a page.
Testing for a successful checkpoint
After each input or output statement that issues a checkpoint, the RETURN-CODE
special register is updated with the return code from the checkpoint routine.
Therefore, you can test whether the checkpoint was successful and decide whether
conditions are right to allow a restart.
642 Enterprise COBOL for z/OS, V5.2 Programming Guide
If the return code is greater than 4, an error has occurred in the checkpoint. Check
the return code to prevent a restart that could cause incorrect output.
RELATED REFERENCES
z/OS DFSMS: Checkpoint/Restart (Return codes)
DD statements for defining checkpoint data sets
To define checkpoint data sets, use DD statements.
For tape:
//ddname DD DSNAME=data-set-name,
// [VOLUME=SER=volser,]UNIT=device-type,
// DISP=({NEW|MOD},PASS)
For direct-access devices:
//ddname DD DSNAME=data-set-name,
// [VOLUME=(PRIVATE,RETAIN,SER=volser),]
// UNIT=device-type,SPACE=(subparms),
// DISP=({NEW|MOD},PASS,KEEP)
ddname
Provides a link to the DD statement. The same as the ddname portion of the
assignment-name used in the COBOL RERUN clause.
data-set-name
Identifies the checkpoint data set to the restart procedure. The name given
to the data set used to record checkpoint records.
volser
Identifies the volume by serial number.
device-type
Identifies the device.
subparms
Specifies the amount of track space needed for the data set.
MOD Specifies the multiple contiguous checkpoint method.
NEW Specifies the single checkpoint method.
PASS Prevents deletion of the data set at successful completion of the job step,
unless the job step is the last in the job. If it is the last step, the data set is
deleted.
KEEP Keeps the data set if the job step abnormally ends.
Examples: defining checkpoint data sets
Examples: defining checkpoint data sets
The following examples show the JCL and COBOL coding you can use to define
checkpoint data sets.
Writing single checkpoint records, using tape:
//CHECKPT DD DSNAME=CHECK1,VOLUME=SER=ND0003,
// UNIT=TAPE,DISP=(NEW,KEEP),LABEL=(,NL)
. . .
ENVIRONMENT DIVISION.
. . .
RERUN ON CHECKPT EVERY
5000 RECORDS OF ACCT-FILE.
Chapter 32. Interrupts and checkpoint/restart 643
Writing single checkpoint records, using disk:
//CHEK DD DSNAME=CHECK2,
// VOLUME=(PRIVATE,RETAIN,SER=DB0030),
// UNIT=3380,DISP=(NEW,KEEP),SPACE=(CYL,5)
. . .
ENVIRONMENT DIVISION.
. . .
RERUN ON CHEK EVERY
20000 RECORDS OF PAYCODE.
RERUN ON CHEK EVERY
30000 RECORDS OF IN-FILE.
Writing multiple contiguous checkpoint records, using tape:
//CHEKPT DD DSNAME=CHECK3,VOLUME=SER=111111,
// UNIT=TAPE,DISP=(MOD,PASS),LABEL=(,NL)
. . .
ENVIRONMENT DIVISION.
. . .
RERUN ON CHEKPT EVERY
10000 RECORDS OF PAY-FILE.
Messages generated during checkpoint
The system checkpoint routine advises the operator of the status of the checkpoints
taken by displaying informative messages on the console.
Each time a checkpoint is successfully completed, a message is displayed that
associates the jobname (ddname, unit, volser) with the checkpoint taken (checkid).
The control program assigns checkid as an eight-character string. The first character
is the letter C, followed by a decimal number that indicates the checkpoint. For
example, the following message indicates the fourth checkpoint taken in the job
step:
checkid C0000004
Restarting programs
The system restart routine retrieves the information recorded in a checkpoint
record, restores the contents of main storage and all registers, and restarts the
program.
You can begin the restart routine in one of two ways:
v Automatically at the time an interruption stopped the program
v At a later time as a deferred restart
The RD parameter of the job control language determines the type of restart. You
can use the RD parameter on either the JOB or the EXEC statement. If coded on the
JOB statement, the parameter overrides any RD parameters on the EXEC statement.
To suppress both restart and writing checkpoints, code RD=NC.
Restriction: If you try to restart at a checkpoint taken by a COBOL program
during a SORT or MERGE operation, an error message is issued and the restart is
canceled. Only checkpoints taken by DFSORT are valid.
Data sets that have the SYSOUT parameter coded in their DD statements are handled
in various ways depending on the type of restart.
644 Enterprise COBOL for z/OS, V5.2 Programming Guide
If the checkpoint data set is multivolume, include in the VOLUME parameter the
sequence number of the volume on which the checkpoint entry was written. If the
checkpoint data set is on a 7-track tape with nonstandard labels or no labels, the
SYSCHK DD statement must contain DCB=(TRTCH=C,. . .).
RELATED TASKS
Using checkpoint/restart with DFSORT on page 236
Requesting automatic restart
Requesting deferred restart
Requesting automatic restart
Automatic restart occurs only at the latest checkpoint taken. If no checkpoint was
taken before interruption, automatic restart occurs at the beginning of the job step.
Whenever automatic restart is to occur, the system repositions all devices except
unit-record devices.
If you want automatic restart, code RD=R or RD=RNC:
v RD=R indicates that restart is to occur at the latest checkpoint. Code the RERUN
clause for at least one data set in the program in order to record checkpoints. If
no checkpoint is taken before interruption, restart occurs at the beginning of the
job step.
v RD=RNC indicates that no checkpoint is to be written, and that any restart is to
occur at the beginning of the job step. In this case, RERUN clauses are
unnecessary; if any are present, they are ignored.
If you omit the RD parameter, the CHKPT macro instruction remains active, and
checkpoints can be taken during processing. If an interrupt occurs after the first
checkpoint, automatic restart will occur.
To restart automatically, a program must satisfy the following conditions:
v In the program you must request restart by using the RD parameter or by taking
a checkpoint.
v An abend that terminated the job must return a code that allows restart.
v The operator must authorize the restart.
Example: requesting a step restart on page 647
Requesting deferred restart
Deferred restart can occur at any checkpoint, not necessarily the latest one taken.
You can restart your program at a checkpoint other than at the beginning of the job
step.
When a deferred restart has been successfully completed, the system displays a
message on the console stating that the job has been restarted. Control is then
given to your program.
If you want deferred restart, code the RD parameter as RD=NR. This form of the
parameter suppresses automatic restart but allows a checkpoint record to be
written provided that a RERUN clause was coded.
Request a deferred restart by using the RESTART parameter on the JOB card and a
SYSCHK DD statement to identify the checkpoint data set. If a SYSCHK DD statement is
present in a job and the JOB statement does not contain the RESTART parameter, the
Chapter 32. Interrupts and checkpoint/restart 645
SYSCHK DD statement is ignored. If a RESTART parameter without the CHECKID
subparameter is included in a job, a SYSCHK DD statement must not appear before
the first EXEC statement for the job.
Example: restarting a job at a specific checkpoint step on page 647
RELATED REFERENCES
Formats for requesting deferred restart
Formats for requesting deferred restart
The formats for the RESTART parameter of the JOB statement and the SYSCHK DD
statements are as shown below.
//jobname JOB MSGLEVEL=1,RESTART=(request[,checkid])
//SYSCHK DD DSNAME=data-set-name,
// DISP=OLD[,UNIT=device-type,
// VOLUME=SER=volser]
MSGLEVEL=1 (or MSGLEVEL=(1,y))
MSGLEVEL is required.
RESTART=(request,[checkid])
Identifies the particular checkpoint at which restart is to occur.
request
Takes one of the following forms:
* Indicates restart at the beginning of the job.
stepname
Indicates restart at the beginning of a job step.
stepname.procstep
Indicates restart at a procedure step within the job step.
checkid
Identifies the checkpoint where restart is to occur.
SYSCHK
The ddname used to identify a checkpoint data set to the control program.
The SYSCHK DD statement must immediately precede the first EXEC
statement of the resubmitted job, and must follow any JOBLIB statement.
data-set-name
Identifies the checkpoint data set. It must be the same name that
was used when the checkpoint was taken.
device-type and volser
Identify the device type and the serial number of the volume that
contains the checkpoint data set.
Example: requesting a deferred restart
Example: requesting a deferred restart
This example shows JCL to restart the GO step of an IGYWCLG procedure at
checkpoint identifier (CHECKID) C0000003.
//jobname JOB MSGLEVEL=1,RESTART=(stepname.GO,C0000003)
//SYSCHK DD DSNAME=CHEKPT,
// DISP=OLD[,UNIT=3380,VOLUME=SER=111111]
. . .
646 Enterprise COBOL for z/OS, V5.2 Programming Guide
Resubmitting jobs for restart
When you resubmit a job for restart, be careful with any DD statements that might
affect the execution of the restarted job step. The restart routine uses information
from DD statements in the resubmitted job to reset files for use after restart.
If you want a data set to be deleted at the end of a job step, give it a conditional
disposition of PASS or KEEP (rather than DELETE). This disposition allows the data
set to be available if an interruption forces a restart. If you want to restart a job at
the beginning of a step, you must first discard any data set created (defined as NEW
in a DD statement) in the previous run, or change the DD statement to mark the data
set as OLD.
The system automatically repositions input data sets that are on tape or disk.
Example: resubmitting a job for a step restart
Example: resubmitting a job for a checkpoint restart on page 648
Example: restarting a job at a specific checkpoint step
This example shows a sequence of job control statements for restarting a job at a
specific step.
//PAYROLL JOB MSGLEVEL=1,REGION=80K,
// RESTART=(STEP1,CHECKPT4)
//JOBLIB DD DSNAME=PRIV.LIB3,DISP=OLD
//SYSCHK DD DSNAME=CHKPTLIB,
// [UNIT=TAPE,VOL=SER=456789,]
// DISP=(OLD,KEEP)
//STEP1 EXEC PGM=PROG4,TIME=5
Example: requesting a step restart
This example shows the use of the RD parameter, which requests step restart for
any abnormally terminated job step.
//J1234 JOB 386,SMITH,MSGLEVEL=1,RD=R
//S1 EXEC PGM=MYPROG
//INDATA DD DSNAME=INVENT[,UNIT=TAPE],DISP=OLD,
// [VOLUME=SER=91468,]
// LABEL=RETPD=14
//REPORT DD SYSOUT=A
//WORK DD DSNAME=T91468,DISP=(,,KEEP),
// UNIT=SYSDA,SPACE=(3000,(5000,500)),
// VOLUME=(PRIVATE,RETAIN,,6)
//DDCKPNT DD UNIT=TAPE,DISP=(MOD,PASS,CATLG),
// DSNAME=C91468,LABEL=(,NL)
The DDCKPNT DD statement defines a checkpoint data set. For this step, after a RERUN
clause is performed, only automatic checkpoint restart can occur unless a CHKPT
cancel is issued.
Example: resubmitting a job for a step restart
This example shows the changes that you might make to the JCL before you
resubmit a job for step restart.
//J3412 JOB 386,SMITH,MSGLEVEL=1,RD=R,RESTART=*
//S1 EXEC PGM=MYPROG
//INDATA DD DSNAME=INVENT[,UNIT=TAPE],DISP=OLD,
// [VOLUME=SER=91468,]LABEL=RETPD=14
//REPORT DD SYSOUT=A
//WORK DD DSNAME=S91468,
// DISP=(,,KEEP),UNIT=SYSDA,
Chapter 32. Interrupts and checkpoint/restart 647
// SPACE=(3000,(5000,500)),
// VOLUME=(PRIVATE,RETAIN,,6)
//DDCHKPNT DD UNIT=TAPE,DISP=(MOD,PASS,CATLG),
// DSNAME=R91468,LABEL=(,NL)
The following changes were made in the example above:
v The job name has been changed (from J1234 to J3412) to distinguish the original
job from the restarted job.
v The RESTART parameter has been added to the JOB statement, and indicates that
restart is to begin with the first job step.
v The WORK DD statement was originally assigned a conditional disposition of KEEP
for this data set:
If the step terminated normally in the previous run of the job, the data set
was deleted, and no changes need to be made to this statement.
If the step abnormally terminated, the data set was kept. In that case, define a
new data set (S91468 instead of T91468, as shown), or change the status of the
data set to OLD before resubmitting the job.
v A new data set (R91468 instead of C91468) has also been defined as the
checkpoint data set.
Example: requesting a step restart on page 647
Example: resubmitting a job for a checkpoint restart
This example shows the changes that you might make to JCL before you resubmit
a job for checkpoint restart.
//J3412 JOB 386,SMITH,MSGLEVEL=1,RD=R,
// RESTART=(*,C0000002)
//SYSCHK DD DSNAME=C91468,DISP=OLD
//S1 EXEC PGM=MYPROG
//INDATA DD DSNAME=INVENT,UNIT=TAPE,DISP=OLD,
// VOLUME=SER=91468,LABEL=RETPD=14
//REPORT DD SYSOUT=A
//WORK DD DSNAME=T91468,DISP=(,,KEEP),
// UNIT=SYSDA,SPACE=(3000,(5000,500)),
// VOLUME=(PRIVATE,RETAIN,,6)
//DDCKPNT DD UNIT=TAPE,DISP=(MOD,KEEP,CATLG),
// DSNAME=C91468,LABEL=(,NL)
The following changes were made in the example above:
v The job name has been changed (from J1234 to J3412) to distinguish the original
job from the restarted job.
v The RESTART parameter has been added to the JOB statement, and indicates that
restart is to begin with the first step at the checkpoint entry named C0000002.
v The DD statement DDCKPNT was originally assigned a conditional disposition of
CATLG for the checkpoint data set:
If the step terminated normally in the previous run of the job, the data set
was kept. In that case, the SYSCHK DD statement must contain all of the
information necessary for retrieving the checkpoint data set.
If the job abnormally terminated, the data set was cataloged. In that case, the
only parameters required on the SYSCHK DD statement are DSNAME and DISP as
shown.
If a checkpoint is taken in a job that is running when V=R is specified, the job
cannot be restarted until adequate nonpageable dynamic storage becomes
available.
648 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 8. Improving performance and productivity
Copyright IBM Corp. 1991, 2015 649
650 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 33. Tuning your program
When a program is comprehensible, you can assess its performance. A tangled
control flow makes a program difficult to understand and maintain, and inhibits
the optimization of its code.
To improve the performance of your program, examine at least these aspects:
v Underlying algorithms: For best performance, using sound algorithms is
essential. For example:
A sophisticated algorithm for sorting a million items might be hundreds of
thousands of times faster than a simple algorithm.
If the program frequently accesses data, reduce the number of steps to access
the data.
v Data structures: Using data structures that are appropriate for the algorithms is
essential.
You can write programs that result in better generated code sequences and use
system services more efficiently. These additional aspects can affect performance:
v Coding techniques: Use a programming style that enables the optimizer to
choose efficient data types and handle tables efficiently.
v Optimization: You can optimize code by using the OPTIMIZE compiler option.
v Compiler options and USE FOR DEBUGGING ON ALL PROCEDURES: Some compiler
options and language affect program efficiency.
v Runtime environment: Consider your choice of runtime options.
v Running under CICS, IMS, or VSAM: Heeding various tips can help make these
programs run more efficiently.
RELATED CONCEPTS
Optimization on page 657
Enterprise COBOL Version 4 Performance Tuning
RELATED TASKS
Using an optimal programming style
Choosing efficient data types on page 652
Handling tables efficiently on page 654
Optimizing your code on page 657
Choosing compiler features to enhance performance on page 658
Running efficiently with CICS, IMS, or VSAM on page 662
Language Environment Programming Guide (Specifying runtime options)
RELATED REFERENCES
Performance-related compiler options on page 659
Language Environment Programming Guide (Storage performance considerations)
Using an optimal programming style
The coding style you use can affect how the optimizer handles your code. You can
improve optimization by using structured programming techniques, factoring
expressions, using symbolic constants, and grouping constant and duplicate
computations.
Copyright IBM Corp. 1991, 2015 651
RELATED TASKS
Using structured programming
Factoring expressions
Using symbolic constants
Using structured programming
Using structured programming statements, such as EVALUATE and inline PERFORM,
makes your program more comprehensible and generates a more linear control
flow. As a result, the optimizer can operate over larger regions of the program,
which gives you more efficient code.
Use top-down programming constructs. Out-of-line PERFORM statements are a
natural means of doing top-down programming. Out-of-line PERFORM statements
can often be as efficient as inline PERFORM statements, because the optimizer can
simplify or remove the linkage code.
Avoid using the following constructs:
v ALTER statements
v Explicit GO TO statements
v PERFORM procedures that involve irregular control flow (such as preventing
control from passing to the end of the procedure and returning to the PERFORM
statement)
Factoring expressions
By factoring expressions in your programs, you can potentially eliminate a lot of
unnecessary computation.
For example, the first block of code below is more efficient than the second block
of code:
MOVE ZERO TO TOTAL
PERFORM VARYING I FROM 1 BY 1 UNTIL I = 10
COMPUTE TOTAL = TOTAL + ITEM(I)
END-PERFORM
COMPUTE TOTAL = TOTAL * DISCOUNT
MOVE ZERO TO TOTAL
PERFORM VARYING I FROM 1 BY 1 UNTIL I = 10
COMPUTE TOTAL = TOTAL + ITEM(I) * DISCOUNT
END-PERFORM
The optimizer does not factor expressions.
Using symbolic constants
To have the optimizer recognize a data item as a constant throughout the program,
initialize it with a VALUE clause and do not change it anywhere in the program.
If you pass a data item to a subprogram BY REFERENCE, the optimizer treats it as an
external data item and assumes that it is changed at every subprogram call.
Choosing efficient data types
Using the SYNCHRONIZED clause can produce more efficient code.
652 Enterprise COBOL for z/OS, V5.2 Programming Guide
Consistent data types can reduce the need for conversions during operations on
data items. You can also improve program performance by carefully determining
when to use fixed-point and floating-point data types.
RELATED CONCEPTS
Formats for numeric data on page 47
RELATED TASKS
Choosing efficient computational data items
Using consistent data types
Making arithmetic expressions efficient on page 654
Making exponentiations efficient on page 654
Choosing efficient computational data items
When you use a data item mainly for arithmetic or as a subscript, code USAGE
BINARY on the data description entry for the item. The operations for manipulating
binary data are faster than those for manipulating decimal data.
However, if a fixed-point arithmetic statement has intermediate results with a large
precision (number of significant digits), the compiler uses decimal arithmetic
anyway, after converting the operands to packed-decimal form. For fixed-point
arithmetic statements, the compiler normally uses binary arithmetic for simple
computations with binary operands if the precision is eight or fewer digits. Above
18 digits, the compiler always uses decimal arithmetic. With a precision of nine to
18 digits, the compiler uses either form.
To produce the most efficient code for a BINARY data item, ensure that it has:
v A sign (an S in its PICTURE clause)
v Eight or fewer digits
For a data item that is larger than eight digits or is used with DISPLAY or NATIONAL
data items, use PACKED-DECIMAL. The code generated for PACKED-DECIMAL data items
can be as fast as that for BINARY data items in some cases, especially if the
statement is complicated or specifies rounding.
To produce the most efficient code for a PACKED-DECIMAL data item, ensure that it
has:
v A sign (an S in its PICTURE clause)
v An odd number of digits (9s in the PICTURE clause), so that it occupies an exact
number of bytes without a half byte left over
v 15 or fewer digits in the PICTURE specification on ARCH(7) machines. If a
PACKED-DECIMAL data item has more than 31 digits, library routines are used. For
a PACKED-DECIMAL data item with 16-31 digits on ARCH (8) or higher level
machines, the compiler uses instructions that are more efficient than library calls,
but not as fast as if the data item has 15 or fewer digits.
Using consistent data types
In operations on operands of different types, one of the operands must be
converted to the same type as the other. Each conversion requires several
instructions. For example, one of the operands might need to be scaled to give it
the appropriate number of decimal places.
You can largely avoid conversions by using consistent data types and by giving
both operands the same usage and also appropriate PICTURE specifications. That is,
Chapter 33. Tuning your program 653
you should ensure that two numbers to be compared, added, or subtracted not
only have the same usage but also the same number of decimal places (9s after the
V in the PICTURE clause).
Making arithmetic expressions efficient
Computation of arithmetic expressions that are evaluated in floating point is most
efficient when the operands need little or no conversion. Use operands that are
COMP-1 or COMP-2 to produce the most efficient code.
| Define integer items as BINARY or PACKED-DECIMAL with nine or fewer digits to
afford quick conversion to floating-point data. Also, conversion from a COMP-1 or
COMP-2 item to a fixed-point integer with nine or fewer digits, without SIZE ERROR
in effect, is efficient when the value of the COMP-1 or COMP-2 item is less than
1,000,000,000.
Making exponentiations efficient
Use floating point for exponentiations for large exponents to achieve faster
evaluation and more accurate results.
For example, the first statement below is computed more quickly and accurately
than the second statement:
COMPUTE fixed-point1 = fixed-point2 ** 100000.E+00
COMPUTE fixed-point1 = fixed-point2 ** 100000
A floating-point exponent causes floating-point arithmetic to be used to compute
the exponentiation.
| Using VOLATILE clauses efficiently
| Optimization of data items that are defined with the VOLATILE clause is
| significantly restricted. Therefore, use the VOLATILE clause only when appropriate.
| In particular, it is important to understand that when the VOLATILE clause is used
| on a group item, the compiler treats all data items subordinate to the group item
| as volatile, and all higher-level group items that contain the volatile group item are
| treated as volatile, too. If a particular member of a group needs to be treated as
| volatile, specify the VOLATILE clause on the data description entry for that item
| only, where possible.
| At present, the primary reason to use the VOLATILE clause is for data items that are
| set or referenced inside an LE condition handler but are defined outside the LE
| condition handler program. The VOLATILE clause guarantees that such items are
| handled correctly by the optimizer. For more information on when to use VOLATILE,
| see VOLATILE clause in the Enterprise COBOL Language Reference.
Handling tables efficiently
You can use several techniques to improve the efficiency of table-handling
operations, and to influence the optimizer. The return for your efforts can be
significant, particularly when table-handling operations are a major part of an
application.
The following two guidelines affect your choice of how to refer to table elements:
v Use indexing rather than subscripting.
654 Enterprise COBOL for z/OS, V5.2 Programming Guide
Although the compiler can eliminate duplicate indexes and subscripts, the
original reference to a table element is more efficient with indexes (even if the
subscripts were BINARY). The value of an index has the element size factored into
it, whereas the value of a subscript must be multiplied by the element size when
the subscript is used. The index already contains the displacement from the start
of the table, and this value does not have to be calculated at run time. However,
subscripting might be easier to understand and maintain.
v Use relative indexing.
Relative index references (that is, references in which an unsigned numeric
literal is added to or subtracted from the index-name) are executed at least as
fast as direct index references, and sometimes faster. There is no merit in
keeping alternative indexes with the offset factored in.
Whether you use indexes or subscripts, the following coding guidelines can help
you get better performance:
v Specify the element length so that it matches that of related tables.
When you index or subscript tables, it is most efficient if all the tables have the
same element length. That way, the stride for the last dimension of the tables is
the same, and the optimizer can reuse the rightmost index or subscript
computed for one table. If both the element lengths and the number of
occurrences in each dimension are equal, then the strides for dimensions other
than the last are also equal, resulting in greater commonality between their
subscript computations. The optimizer can then reuse indexes or subscripts other
than the rightmost.
v Avoid errors in references by coding index and subscript checks into your
program.
If you need to validate indexes and subscripts, it might be faster to code your
own checks than to use the SSRANGE compiler option.
You can also improve the efficiency of tables by using these guidelines:
v Use binary data items for all subscripts.
When you use subscripts to address a table, use a BINARY signed data item with
eight or fewer digits. In some cases, using four or fewer digits for the data item
might also improve processing time.
v Use binary data items for variable-length table items.
For tables with variable-length items, you can improve the code for OCCURS
DEPENDING ON (ODO). To avoid unnecessary conversions each time the
variable-length items are referenced, specify BINARY for OCCURS . . . DEPENDING
ON objects.
v Use fixed-length data items whenever possible.
Copying variable-length data items into a fixed-length data item before a period
of high-frequency use can reduce some of the overhead associated with using
variable-length data items.
v Organize tables according to the type of search method used.
If the table is searched sequentially, put the data values most likely to satisfy the
search criteria at the beginning of the table. If the table is searched using a
binary search algorithm, put the data values in the table sorted alphabetically on
the search key field.
RELATED CONCEPTS
Optimization of table references on page 656
Chapter 33. Tuning your program 655
RELATED TASKS
Referring to an item in a table on page 70
Choosing efficient data types on page 652
RELATED REFERENCES
SSRANGE on page 357
Optimization of table references
The COBOL compiler optimizes table references in several ways.
For the table element reference ELEMENT(S1 S2 S3), where S1, S2, and S3 are
subscripts, the compiler evaluates the following expression:
comp_s1 * d1 + comp_s2 * d2 + comp_s3 * d3 + base_address
Here comp_s1 is the value of S1 after conversion to binary, comp-s2 is the value of
S2 after conversion to binary, and so on. The strides for each dimension are d1, d2,
and d3. The stride of a given dimension is the distance in bytes between table
elements whose occurrence numbers in that dimension differ by 1 and whose other
occurrence numbers are equal. For example, the stride d2 of the second dimension
in the above example is the distance in bytes between ELEMENT(S1 1 S3) and
ELEMENT(S1 2 S3).
Index computations are similar to subscript computations, except that no
multiplication needs to be done. Index values have the stride factored into them.
They involve loading the indexes into registers, and these data transfers can be
optimized, much as the individual subscript computation terms are optimized.
Optimization of variable-length items
A group item that contains a subordinate OCCURS DEPENDING ON data item has a
variable length. The program must perform special code every time a
variable-length data item is referenced.
Because this code is out-of-line, it might interrupt optimization. Furthermore, the
code to manipulate variable-length data items is much less efficient than that for
fixed-size data items and can significantly increase processing time. For instance,
the code to compare or move a variable-length data item might involve calling a
library routine and is much slower than the same code for fixed-length data items.
Comparison of direct and relative indexing
Relative index references are as fast as or faster than direct index references.
The direct indexing in ELEMENT (I5, J3, K2) requires this preprocessing:
SET I5 TO I
SET I5 UP BY 5
SET J3 TO J
SET J3 DOWN BY 3
SET K2 TO K
SET K2 UP BY 2
This processing makes the direct indexing less efficient than the relative indexing
in ELEMENT (I + 5, J - 3, K + 2).
RELATED CONCEPTS
Optimization on page 657
656 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Handling tables efficiently on page 654
Optimizing your code
When your program is ready for final testing, specify the OPTIMIZE(1|2) compiler
option so that the tested code and the production code are identical.
If you frequently run a program without recompiling it during development, you
might also want to use OPTIMIZE(1|2). However, if you recompile frequently, the
overhead for OPTIMIZE(1|2) might outweigh its benefits unless you are using the
assembler language expansion (LIST compiler option) to fine-tune the program.
For unit-testing a program, you will probably find it easier to debug code that has
not been optimized.
To see how the optimizer works on a program, compile it with different levels of
optimization and compare the generated code. (Use the LIST compiler option to
request the assembler listing of the generated code.)
RELATED CONCEPTS
Optimization
RELATED REFERENCES
LIST on page 333
OPTIMIZE on page 343
Optimization
To improve the efficiency of the generated code, you can use the OPTIMIZE(1) or
OPTIMIZE(2) compiler option.
OPTIMIZE(1) causes the COBOL optimizer to do the following optimizations:
v Eliminate unnecessary transfers of control and inefficient branches, including
those generated by the compiler that are not evident from looking at the source
program.
v Simplify the compiled code for a PERFORM statement. The compiler replicates the
PERFORM a number of times to avoid linkage code.
v Eliminate duplicate computations (such as subscript computations and repeated
statements) that have no effect on the results of the program.
v Eliminate constant computations by performing them when the program is
compiled.
v Eliminate constant conditional expressions.
v Aggregate moves of contiguous items (such as those that often occur with the
use of MOVE CORRESPONDING) into a single move. Both the source and target must
be contiguous for the moves to be aggregated.
v Delete from the program, and identify with a warning message, code that can
never be performed (unreachable code elimination).
v Discard unreferenced data items from the DATA DIVISION, and suppress
generation of code to initialize these data items to their VALUE clauses. (The
optimizer takes this action only when you use the STGOPT option.)
OPTIMIZE(2) causes the COBOL optimizer to do further optimizations:
v Simplify operations more aggressively and schedule instructions.
Chapter 33. Tuning your program 657
v Do interblock optimizations such as global value propagation and loop invariant
code motion.
Contained program procedure integration
In contained program procedure integration, the contained program code replaces
a CALL to a contained program. The resulting program runs faster without the
overhead of CALL linkage and with more linear control flow.
Program size: If several CALL statements call contained programs and these
programs replace each such statement, the containing program can become large.
The optimizer then chooses the next best optimization for the CALL statement.
RELATED CONCEPTS
Optimization of table references on page 656
PERFORM procedure integration
RELATED REFERENCES
OPTIMIZE on page 343
PERFORM procedure integration
PERFORM procedure integration is the process whereby a PERFORM statement is
replaced by its performed procedures. The advantage is that the resulting program
runs faster without the overhead of PERFORM linkage and with more orderly control
flow.
Program size: If the performed procedures are invoked by several PERFORM
statements and replace each such statement, the program could become large. The
optimizer limits this increase, after which it no longer integrates these procedures.
Choosing compiler features to enhance performance
Your choice of performance-related compiler options and your use of the USE FOR
DEBUGGING ON ALL PROCEDURES statement can affect how well your program is
optimized.
You might have a customized system that requires certain options for optimum
performance. Do these steps:
1. To see what your system defaults are, get a short listing for any program and
review the listed option settings.
2. Determine which options are fixed as nonoverridable at your installation by
checking with your system programmer.
3. For the options not fixed at installation, select performance-related options for
compiling your programs.
Important: Confer with your system programmer about how to tune COBOL
programs. Doing so will ensure that the options you choose are appropriate for
programs at your site.
Another compiler feature to consider is the USE FOR DEBUGGING ON ALL PROCEDURES
statement. It can greatly affect the compiler optimizer. The ON ALL PROCEDURES
option generates extra code at each transfer to a procedure name. Although very
useful for debugging, it can make the program significantly larger and inhibit
optimization substantially.
Although COBOL allows segmentation language, you will not improve storage
allocation by using it, because COBOL does not perform overlay.
658 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED CONCEPTS
Optimization on page 657
RELATED TASKS
Optimizing your code on page 657
Getting listings on page 387
RELATED REFERENCES
Performance-related compiler options
Performance-related compiler options
In the table below you can see a description of the purpose of each option, its
performance advantages and disadvantages, and usage notes where applicable.
Table 89. Performance-related compiler options
Performance Performance
Compiler option Purpose advantages disadvantages Usage notes
AFP(NOVOLATILE) To control the AFP(NOVOLATILE) lets the None Poorly behaved assembler code
compiler usage of the compiler generate more might not adhere to the standard
(see AFP on Additional Floating efficient code sequences calling convention and might fail to
page 306) Point (AFP) registers for programs with correctly preserve values in Floating
that are provided by floating point Point registers. With
z/Architecture operations. AFP(NOVOLATILE), COBOL programs
processors can safely call such routines.
ARCH To specify the If you specify a higher None Your application might abend if it
machine architecture ARCH level, the machine runs on a processor with an
(see ARCH on for which the generates code that uses architecture level lower than that
page 307) executable program newer and faster specified for the ARCH option.
instructions are to be instructions instead of
generated the sequences of
common instructions.
ARITH(EXTEND) To increase the None ARITH(EXTEND) causes The amount of degradation that you
maximum number of some degradation in experience depends directly on the
(see ARITH on digits allowed for performance for all amount of decimal data that you use.
page 309) decimal numbers decimal data types
because of larger
intermediate results.
AWO To get optimum use Can result in None If you use AWO, the APPLY WRITE-ONLY
of buffer and device performance savings, clause is in effect for all QSAM files
(see AWO on space for QSAM files because this option in the program that have V-mode
page 310) results in fewer calls to records.
data management
services to handle input
and output
BLOCK0 To take advantage of Can result in enhanced None If you use BLOCK0, a BLOCK CONTAINS
system-determined processing speed and 0 clause is activated for all QSAM
(see BLOCK0 block size for QSAM minimized storage files in the program that specify
on page 310) output files requirements for QSAM neither BLOCK CONTAINS nor
output files RECORDING MODE U in the file
description entry.
DATA(31) To have DFSMS Because None On a z/OS system with DFSMS, if
allocate QSAM extended-format QSAM your application processes striped
(see DATA on buffers above the 16 data sets can require extended-format QSAM data sets,
page 318) MB line (by using the many buffers, allocating use the RENT and DATA(31) compiler
RENT and DATA(31) the buffers in options to have the input-output
compiler options) unrestricted storage buffers for your QSAM files allocated
avoids virtual storage from storage above the 16 MB line.
constraint problems.
Chapter 33. Tuning your program 659
Table 89. Performance-related compiler options (continued)
Performance Performance
Compiler option Purpose advantages disadvantages Usage notes
DYNAM To have subprograms Subprograms are easier There is a slight To free virtual storage that is no
(called through the to maintain, because the performance penalty, longer needed, issue the CANCEL
(see DYNAM CALL statement) application does not because the call must statement.
on page 323) dynamically loaded have to be link-edited go through a
at run time again if a subprogram is Language
changed. Environment routine.
FASTSRT To specify that the Eliminates the overhead None FASTSRT is recommended if direct
IBM DFSORT product of returning to work files are used for the sort work
(see FASTSRT (or equivalent) will Enterprise COBOL after files. Not all sorts are eligible for this
on page 327) handle all of the each record is processed option.
input and output
HGPR To control the If you specify None If your program modifies and does
compiler usage of the HGPR(NOPRESERVE), the not save the high-halves of the
(see HGPR on 64-bit registers compiler omits registers, but calling programs
page 330) provided by preserving the depend on the unchanged values, the
z/Architecture high-halves of the 64-bit application might give incorrect
processors. GPRs that a program is results.
using, which improves Exception: It does not apply if the
performance. caller of this program is Enterprise
COBOL, Enterprise PL/I or z/OS XL
C/C++ programs.
MAXPCF To reduce None If you specify None
optimization in MAXPCF(n) and n is not
(see MAXPCF programs that require zero, when the
on page 335) excessive compilation program complexity
time or excessive factor exceeds n, any
storage requirements specification of
because of large sizes OPTIMIZE(1) or
or complexity. OPTIMIZE(2) is reset
to OPTIMIZE(0), and a
warning message is
generated.
NUMPROC(PFD) To have invalid sign Generates significantly For most references If you use NUMPROC(PFD), the
processing bypassed more efficient code for to COMP-3 and compiler assumes and requires that
(see for numeric numeric comparisons DISPLAY numeric data all decimal items contain the
NUMPROC on operations items, NUMPROC(PFD) preferred sign values and bypasses
page 339) inhibits extra code the sign "fix-up" process. However,
from being generated because not all external data files
to "fix up" signs. This contain the proper signs for COMP-3
extra code might also or DISPLAY numeric data, and
inhibit some other programs might use REDEFINES,
types of group moves, or parameter passing
optimizations. The in ways that do not ensure preferred
extra code is signs, the NUMPROC(PFD) might not be
generated with appropriate for many programs.
NUMPROC(NOPFD).
OPTIMIZE(0|1|2) To optimize Generally results in Longer compile time: OPTIMIZE(0) is generally used during
generated code for more efficient runtime OPTIMIZE(1|2) program development when frequent
(see OPTIMIZE better performance code requires more compiles are needed; it also allows
on page 343) processing time for for symbolic debugging. For
compiles than production runs, OPTIMIZE(1|2) is
OPTIMIZE(0). recommended.
STGOPT To optimize storage Generally results in less None STGOPT deletes unused data items,
allocation in DATA storage usage which might be undesirable in the
(see STGOPT DIVISION case of time stamps or data items
on page 358) that are used only as markers for
dump reading.
RENT To generate a Enables the program to Generates additional None
reentrant program be placed in shared code to ensure that
(see RENT on storage (LPA/ELPA) for the program is
page 348) faster execution reentrant
660 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 89. Performance-related compiler options (continued)
Performance Performance
Compiler option Purpose advantages disadvantages Usage notes
RMODE(ANY) To let the program be None None None
loaded anywhere
(see RMODE
on page 349)
SSRANGE To verify that all table SSRANGE generates With SSRANGE In general, if you need to verify the
references and additional code for specified, checks for table references only a few times
(see SSRANGE reference verifying table valid ranges do affect instead of at every reference, coding
on page 357) modification references. Using compiler your own checks might be faster
expressions are in NOSSRANGE causes that performance. than using SSRANGE. For
proper bounds code not to be performance-sensitive applications,
generated. NOSSRANGE is recommended.
TEST To get full debugging None Some reduction in For production runs, using NOTEST or
capability when using optimization occurs TEST(NOEJPD) is recommended.
(see TEST on Debug Tool and to when the TEST option
page 359) get a symbolic dump is used. More If during a production run, you want
of the data items in reduction in a symbolic dump of the data items in
CEEDUMP. You can also optimization occurs a formatted dump if the program
get a symbolic dump when the EJPD abends, compile using TEST or with
of the data items in suboption of TEST is NOTEST(DWARF).
CEEDUMP with used.
NOTEST(DWARF).
THREAD To enable programs None There is a slight A slight performance penalty occurs
for execution in a performance penalty in either a threaded or nonthreaded
(see THREAD Language because of the environment.
on page 362) Environment enclave overhead of
that has multiple serialization logic.
POSIX threads or
PL/I tasks
| TRUNC(OPT) To avoid having code Does not generate extra Both TRUNC(BIN) and TRUNC(STD) conforms to the 85
| generated to truncate code and generally TRUNC(STD) generate COBOL Standard, but TRUNC(BIN)
(see TRUNC on the receiving fields of improves performance extra code whenever and TRUNC(OPT) do not. With
page 363) arithmetic operations a BINARY data item is TRUNC(OPT), the compiler assumes
changed. TRUNC(BIN) that the data conforms to the PICTURE
is usually the slowest and USAGE specifications. TRUNC(OPT)
of these options. is recommended where possible.
RELATED CONCEPTS
Optimization on page 657
Storage and its addressability on page 39
RELATED TASKS
Generating a list of compiler messages on page 280
Evaluating performance on page 662
Optimizing buffer and device space on page 10
Choosing compiler features to enhance performance on page 658
Improving sort performance with FASTSRT on page 231
Using striped extended-format QSAM data sets on page 180
Handling tables efficiently on page 654
RELATED REFERENCES
Sign representation of zoned and packed-decimal data on page 53
Allocation of buffers for QSAM files on page 181
Chapter 17, Compiler options, on page 301
Conflicting compiler options on page 304
Chapter 33. Tuning your program 661
Evaluating performance
Fill in the following worksheet to help you evaluate the performance of your
program. If you answer yes to each question, you are probably improving the
performance.
In thinking about the performance tradeoff, be sure you understand the function of
each option as well as the performance advantages and disadvantages. You might
prefer function over increased performance in many instances.
Table 90. Performance-tuning worksheet
Compiler option Consideration Yes?
ARCH Do you use the highest architecture level possible for all
environments in which your programs will run? For
example, if the lowest level architecture you have
including your disaster recovery machines is z10, are
you using ARCH(8)?
AWO Do you use the AWO option when possible?
BLOCK0 Do you use BLOCK0 for QSAM files?
DATA When you use QSAM striped data sets, do you use the
| RENT and DATA(31) options? Is the program object AMODE
31? Are you running with ALL31(ON)?
DYNAM Can you use NODYNAM? Consider the performance
tradeoffs.
FASTSRT When you use direct work files for the sort work files,
did you use the FASTSRT option?
NUMPROC Do you use NUMPROC(PFD) when possible?
OPTIMIZE Do you use a non-zero OPTIMIZE level for production
runs?
SSRANGE Do you use NOSSRANGE for production runs?
TEST Do you use NOTEST or TEST(NOEJPD) for production runs?
TRUNC Do you use TRUNC(OPT) when possible?
| ZONEDATA Do you use ZONEDATA(PFD) when possible?
RELATED CONCEPTS
Storage and its addressability on page 39
RELATED TASKS
Choosing compiler features to enhance performance on page 658
RELATED REFERENCES
Performance-related compiler options on page 659
Running efficiently with CICS, IMS, or VSAM
You can improve performance for online programs running under CICS or IMS, or
programs that use VSAM, by following these tips.
CICS: If your application runs under CICS, convert EXEC CICS LINK commands to
COBOL CALL statements to improve transaction response time.
662 Enterprise COBOL for z/OS, V5.2 Programming Guide
IMS: If your application runs under IMS, preloading the application program and
the library routines can help reduce the overhead of loading and searching. It can
also reduce the input-output activity.
For better system performance, use the RENT compiler option and preload the
applications and library routines when possible. You can also use the Language
Environment library routine retention (LRR) function to improve performance in
IMS/TM regions.
VSAM: When you use VSAM files, increase the number of data buffers for
sequential access or index buffers for random access. Also, select a control interval
size (CISZ) that is appropriate for the application. A smaller CISZ results in faster
retrieval for random processing at the expense of inserts. A larger CISZ is more
efficient for sequential processing.
For better performance, access the records sequentially and avoid using multiple
alternate indexes when possible. If you use alternate indexes, access method
services builds them more efficiently than the AIXBLD runtime option.
RELATED TASKS
Coding COBOL programs to run under CICS on page 419
Chapter 22, Developing COBOL programs for IMS, on page 443
Improving VSAM performance on page 209
Language Environment Customization
RELATED REFERENCES
Language Environment Programming Guide (Specifying runtime options)
Choosing static or dynamic calls
If you can arrange your modules, and the programs that frequently call each other
are in one module, static calls are faster than dynamic calls.
For more information, see Performance considerations of static and dynamic calls
on page 471.
RELATED CONCEPTS
Performance considerations of static and dynamic calls on page 471
Chapter 33. Tuning your program 663
664 Enterprise COBOL for z/OS, V5.2 Programming Guide
Chapter 34. Simplifying coding
You can use coding techniques to improve your productivity. By using the COPY
| statement, the format 2 SORT statement, COBOL intrinsic functions, and Language
Environment callable services, you can avoid repetitive coding and having to code
many arithmetic calculations or other complex tasks.
If your program contains frequently used code sequences (such as blocks of
common data items, input-output routines, error routines, or even entire COBOL
programs), write the code sequences once and put them in a COBOL copy library.
You can use the COPY statement to retrieve these code sequences and have them
included in your program at compile time. Using copybooks in this manner
eliminates repetitive coding.
| To sort a table, you can use the format 2 SORT statement to simplify coding. It
| provides a much simpler way compared to the format 1 SORT statement.
COBOL provides various capabilities for manipulating strings and numbers. These
capabilities can help you simplify your coding.
The Language Environment date and time callable services store dates as fullword
binary integers and store time stamps as long (64-bit) floating-point values. These
formats let you do arithmetic calculations on date and time values simply and
efficiently. You do not need to write special subroutines that use services outside
the language library to perform such calculations.
RELATED TASKS
Using numeric intrinsic functions on page 57
Using math-oriented callable services on page 58
Using date callable services on page 60
Eliminating repetitive coding
Converting data items (intrinsic functions) on page 116
Evaluating data items (intrinsic functions) on page 119
Using Language Environment callable services on page 667
| RELATED REFERENCES
| Using the format 2 SORT statement to sort a table on page 671
|
Eliminating repetitive coding
To include stored source statements in a program, use the COPY statement in any
program division and at any code sequence level. You can nest COPY statements to
any depth.
To specify more than one copy library, use either multiple system definitions or a
combination of multiple definitions and the IN/OF phrase (IN/OF library-name):
MVS batch
Use JCL to concatenate data sets in your SYSLIB DD statement.
Alternatively, define multiple DD statements and use the IN/OF phrase of
the COPY statement.
Copyright IBM Corp. 1991, 2015 665
TSO Use the ALLOCATE command to concatenate data sets for SYSLIB.
Alternatively, issue multiple ALLOCATE statements and use the IN/OF phrase
of the COPY statement.
z/OS UNIX
Use the SYSLIB environment variable to define multiple paths to your
copybooks. Alternatively, use multiple environment variables and use the
IN/OF phrase of the COPY statement.
For example:
COPY MEMBER1 OF COPYLIB
If you omit this qualifying phrase, the default is SYSLIB.
COPY and debugging line: In order for the text copied to be treated as debug lines,
for example, as if there were a D inserted in column 7, put the D on the first line of
the COPY statement. A COPY statement cannot itself be a debugging line; if it
contains a D, and WITH DEBUGGING mode is not specified, the COPY statement is
nevertheless processed.
Example: using the COPY statement
RELATED REFERENCES
Chapter 18, Compiler-directing statements, on page 373
Example: using the COPY statement
These examples show how you can use the COPY statement to include library text
in a program.
Suppose the library entry CFILEA consists of the following FD entries:
BLOCK CONTAINS 20 RECORDS
RECORD CONTAINS 120 CHARACTERS
LABEL RECORDS ARE STANDARD
DATA RECORD IS FILE-OUT.
01 FILE-OUT PIC X(120).
You can retrieve the text-name CFILEA by using the COPY statement in a source
program as follows:
FD FILEA
COPY CFILEA.
The library entry is copied into your program, and the resulting program listing
looks like this:
FD FILEA
COPY CFILEA.
C BLOCK CONTAINS 20 RECORDS
C RECORD CONTAINS 120 CHARACTERS
C LABEL RECORDS ARE STANDARD
C DATA RECORD IS FILE-OUT.
C 01 FILE-OUT PIC X(120).
In the compiler source listing, the COPY statement prints on a separate line. C
precedes copied lines.
Assume that a copybook with the text-name DOWORK is stored by using the
following statements:
666 Enterprise COBOL for z/OS, V5.2 Programming Guide
COMPUTE QTY-ON-HAND = TOTAL-USED-NUMBER-ON-HAND
MOVE QTY-ON-HAND to PRINT-AREA
To retrieve the copybook identified as DOWORK, code:
paragraph-name.
COPY DOWORK.
The statements that are in the DOWORK procedure will follow paragraph-name.
If you use the EXIT compiler option to provide a LIBEXIT module, your results
might differ from those shown here.
Note: To save compile time, you might group related items in a copybook, but not
necessarily have a single large copybook with unrelated items in it.
RELATED TASKS
Eliminating repetitive coding on page 665
RELATED REFERENCES
Chapter 18, Compiler-directing statements, on page 373
Using Language Environment callable services
Language Environment callable services make many types of programming tasks
easier. You call them by using the CALL statement.
Language Environment services help you with the following tasks:
v Handling conditions
The Language Environment condition-handling facilities enable COBOL
applications to react to unexpected errors. You can use language constructs or
runtime options to select the level at which to handle each condition. For
example, you can handle a particular error in your COBOL program, let
Language Environment take care of it, or have the operating system handle it.
In support of Language Environment condition handling, COBOL provides
procedure-pointer data items.
v Managing dynamic storage
These services enable you to get, free, and reallocate storage. You can also create
your own storage pools.
v Calculating dates and times
If you use the date and time services, you can get the current local time and
date in several formats, and perform date and time conversions. Two callable
services, CEEQCEN and CEESCEN, provide a predictable way to handle
two-digit years, such as 91 for 1991 or 09 for 2009.
v Making math calculations
Calculations that are easy to perform with mathematical callable services include
logarithmic, exponential, trigonometric, square root, and integer functions.
COBOL also supports a set of intrinsic functions that include some of the same
mathematical and date functions as those provided by the callable services. The
Language Environment callable services and intrinsic functions provide
equivalent results, with a few exceptions. You should be familiar with these
differences before deciding which to use.
v Handling messages
Chapter 34. Simplifying coding 667
Message-handling services include services for getting, dispatching, and
formatting messages. Messages for non-CICS applications can be directed to files
or printers. CICS messages are directed to a CICS transient data queue.
Language Environment splits messages to accommodate the record length of the
destination, and presents messages in the correct national language such as
Japanese or English.
v Supporting national languages
These services make it easy for your applications to support the language that
application users want. You can set the language and country, and obtain default
date, time, number, and currency formats. For example, you might want dates to
appear as 23 June 09 or as 6,23,09.
v General services such as starting Debug Tool and obtaining a Language
Environment formatted dump
Debug Tool provides advanced debugging functions for COBOL applications,
including both batch and interactive debugging of CICS programs. Debug Tool
enables you to debug a COBOL application from the host or, in conjunction with
the Debug Perspective of Rational Developer for System z, from a
Windows-based workstation.
Depending on the options that you select, the Language Environment formatted
dump might contain the names and values of data items, and information about
conditions, program tracebacks, control blocks, storage, and files. All Language
Environment dumps have a common, well-labeled, easy-to-read format.
Example: Language Environment callable services on page 670
RELATED CONCEPTS
Sample list of Language Environment callable services
RELATED TASKS
Using numeric intrinsic functions on page 57
Using math-oriented callable services on page 58
Using date callable services on page 60
Calling Language Environment services on page 669
Using procedure and function pointers on page 477
Sample list of Language Environment callable services
The following table shows some examples of the callable services that are available
with Language Environment. Many more services are available than those listed.
Table 91. Language Environment callable services
Function type Service Purpose
Condition CEEHDLR To register a user condition handler
handling
CEESGL To raise or signal a condition
CEEMRCR To indicate where the program will resume running after
the condition handler has finished
Dynamic storage CEEGTST To get storage
CEECZST To change the size of a previously allocated storage block
CEEFRST To free storage
668 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 91. Language Environment callable services (continued)
Function type Service Purpose
Date and time CEECBLDY To convert a string that represents a date into COBOL
integer date format, which represents a date as the
number of days since 31 December 1600
CEEQCEN, To query and set the Language Environment century
CEESCEN window, which is valuable when a program uses two
digits to express a year
CEEGMTO To calculate the difference between the local system time
and Greenwich Mean Time
CEELOCT To get the current local time in your choice of three
formats
Math CEESIABS To calculate the absolute value of an integer
CEESSNWN To calculate the nearest whole number for a
single-precision floating-point number
CEESSCOS To calculate the cosine of an angle
Message CEEMOUT To dispatch a message
handling
CEEMGET To retrieve a message
National CEE3LNG To change or query the current national language
language support
CEE3CTY To change or query the current national country
CEE3MCS To obtain the default currency symbol for a given
country
General CEE3DMP To obtain a Language Environment formatted dump
CEETEST To start a debugging tool, such as Debug Tool
RELATED REFERENCES
Language Environment Programming Reference
Calling Language Environment services
To invoke a Language Environment service, use a CALL statement with the correct
parameters for that service. Define the variables for the CALL statement in the DATA
DIVISION with the definitions that are required by that service.
77 argument comp-1.
77 feedback-code pic x(12) display.
77 result comp-1.
. . .
CALL "CEESSSQT" using argument, feedback-code, result
In the example above, Language Environment service CEESSSQT calculates the
value of the square root of the variable argument and returns this value in the
variable result.
You can choose whether to specify the feedback code parameter. If you specify it,
the value returned in feedback-code indicates whether the service completed
successfully. If you specify OMITTED instead of the feedback code, and the service is
not successful, a Language Environment condition is automatically signaled to the
Language Environment condition manager. You can handle such a condition by
recovery logic implemented in a user-written condition handler, or let the default
Language Environment processing for unhandled conditions occur. In either case,
you avoid having to write logic to check the feedback code explicitly after each
call.
Chapter 34. Simplifying coding 669
If you call a Language Environment callable service and specify OMITTED for the
feedback code, the RETURN-CODE special register is set to 0 if the service is
successful. It is not altered if the service is unsuccessful. If you do not specify
OMITTED for the feedback code, the RETURN-CODE special register is always set to 0
regardless of whether the service completed successfully.
Example: Language Environment callable services
RELATED CONCEPTS
Language Environment Programming Guide (General callable services)
RELATED REFERENCES
Language Environment Programming Reference (General callable services)
CALL statement (Enterprise COBOL Language Reference)
Example: Language Environment callable services
This example shows a COBOL program that uses the Language Environment
services CEEDAYS and CEEDATE to format and display a date from the results of
a COBOL ACCEPT statement.
Using CEEDAYS and CEEDATE reduces the coding that would be required
without Language Environment.
ID DIVISION.
PROGRAM-ID. HOHOHO.
************************************************************
* FUNCTION: DISPLAY TODAYS DATE IN THE FOLLOWING FORMAT: *
* WWWWWWWWW, MMMMMMMM DD, YYYY *
* *
* For example: TUESDAY, SEPTEMBER 15, 2009 *
* *
************************************************************
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CHRDATE.
05 CHRDATE-LENGTH PIC S9(4) COMP VALUE 10.
05 CHRDATE-STRING PIC X(10).
01 PICSTR.
05 PICSTR-LENGTH PIC S9(4) COMP.
05 PICSTR-STRING PIC X(80).
*
77 LILIAN PIC S9(9) COMP.
77 FORMATTED-DATE PIC X(80).
*
PROCEDURE DIVISION.
***************************************************************
* USE LANGUAGE ENVIRONMENT CALLABLE SERVICES TO PRINT OUT *
* TODAYS DATE FROM COBOL ACCEPT STATEMENT. *
***************************************************************
ACCEPT CHRDATE-STRING FROM DATE.
*
MOVE "YYMMDD" TO PICSTR-STRING.
MOVE 6 TO PICSTR-LENGTH.
CALL "CEEDAYS" USING CHRDATE , PICSTR , LILIAN , OMITTED.
*
MOVE " WWWWWWWWWZ, MMMMMMMMMZ DD, YYYY " TO PICSTR-STRING.
MOVE 50 TO PICSTR-LENGTH.
CALL "CEEDATE" USING LILIAN , PICSTR , FORMATTED-DATE ,
OMITTED.
*
DISPLAY "******************************".
670 Enterprise COBOL for z/OS, V5.2 Programming Guide
DISPLAY FORMATTED-DATE.
DISPLAY "******************************".
*
STOP RUN.
| Using the format 2 SORT statement to sort a table
| It is recommended to use the format 2 SORT statement to sort a table. It provides
| the following benefits when compared to the format 1 SORT statement.
| Table 92. Comparison of format 1 and format 2 SORT statements
| Characteristics Format 1 SORT statements Format 2 SORT statements
| Can be used to sort a file or Yes No, it is for tables only
| a table
| Requires DFSORT or Yes No
| equivalent sorting program
| Supported in CICS Limited Yes
| Supported in UNIX System No Yes
| Services
| Supported in programs that No Yes
| are compiled with the THREAD
| option
| Table can be sorted by using No, it requires the SELECT Yes
| a single SORT statement, clauses, SD entries with
| which simplifies coding record descriptions, and
| input and output procedures
| Keys for sorting can be No, keys must be specified Yes, and it also supports
| specified as part of the table in the SORT statement. If the specifying keys in the SORT
| definition, which can also be table is to be searched by statement if needed
| used in the SEARCH ALL using SEARCH ALL as well, the
| statement keys must also be
| redundantly specified as part
| of the table definition.
| Can filter or preprocess table Yes, using input and output No, all of the table elements
| elements during the sorting procedures are passed to SORT as-is
| process
| Uses special registers that Yes No
| include SORT-CONTROL,
| SORT-CORE-SIZE,
| SORT-FILE-SIZE,
| SORT-MESSAGE,
| SORT-MODE-SIZE, and
| SORT-RETURN
|
|
Chapter 34. Simplifying coding 671
672 Enterprise COBOL for z/OS, V5.2 Programming Guide
Part 9. Appendixes
Copyright IBM Corp. 1991, 2015 673
674 Enterprise COBOL for z/OS, V5.2 Programming Guide
Appendix A. Intermediate results and arithmetic precision
The compiler handles arithmetic statements as a succession of operations
performed according to operator precedence, and sets up intermediate fields to
contain the results of those operations. The compiler uses algorithms to determine
the number of integer and decimal places to reserve.
Intermediate results are possible in the following cases:
v In an ADD or SUBTRACT statement that contains more than one operand
immediately after the verb
v In a COMPUTE statement that specifies a series of arithmetic operations or multiple
result fields
v In an arithmetic expression contained in a conditional statement or in a
reference-modification specification
v In an ADD, SUBTRACT, MULTIPLY, or DIVIDE statement that uses the GIVING option
and multiple result fields
v In a statement that uses an intrinsic function as an operand
Example: calculation of intermediate results on page 677
The precision of intermediate results depends on whether you compile using the
default option ARITH(COMPAT) (referred to as compatibility mode) or using
ARITH(EXTEND) (referred to as extended mode).
In compatibility mode, evaluation of arithmetic operations is unchanged from that
in releases of IBM COBOL before COBOL for OS/390 & VM Version 2 Release 2:
v A maximum of 30 digits is used for fixed-point intermediate results.
v Floating-point intrinsic functions return long-precision (64-bit) floating-point
results.
v Expressions that contain floating-point operands, fractional exponents, or
floating-point intrinsic functions are evaluated as if all operands that are not in
floating point are converted to long-precision floating point and floating-point
operations are used to evaluate the expression.
v Floating-point literals and external floating-point data items are converted to
long-precision floating point for processing.
In extended mode, evaluation of arithmetic operations has the following
characteristics:
v A maximum of 31 digits is used for fixed-point intermediate results.
v Floating-point intrinsic functions return extended-precision (128-bit)
floating-point results.
v Expressions that contain floating-point operands, fractional exponents, or
floating-point intrinsic functions are evaluated as if all operands that are not in
floating point are converted to extended-precision floating point and
floating-point operations are used to evaluate the expression.
v Floating-point literals and external floating-point data items are converted to
extended-precision floating point for processing.
Copyright IBM Corp. 1991, 2015 675
RELATED CONCEPTS
Formats for numeric data on page 47
Fixed-point contrasted with floating-point arithmetic on page 62
RELATED REFERENCES
Fixed-point data and intermediate results on page 677
Floating-point data and intermediate results on page 682
Arithmetic expressions in nonarithmetic statements on page 683
ARITH on page 309
Terminology used for intermediate results
To understand this information about intermediate results, you need to understand
the following terminology.
i The number of integer places carried for an intermediate result. (If you use
the ROUNDED phrase, one more integer place might be carried for accuracy if
necessary.)
d The number of decimal places carried for an intermediate result. (If you
use the ROUNDED phrase, one more decimal place might be carried for
accuracy if necessary.)
dmax In a particular statement, the largest of the following items:
v The number of decimal places needed for the final result field or fields
v The maximum number of decimal places defined for any operand,
except divisors or exponents
v The outer-dmax for any function operand
inner-dmax
In reference to a function, the largest of the following items:
v The number of decimal places defined for any of its elementary
arguments
v The dmax for any of its arithmetic expression arguments
v The outer-dmax for any of its embedded functions
outer-dmax
The number of decimal places that a function result contributes to
operations outside of its own evaluation (for example, if the function is an
operand in an arithmetic expression, or an argument to another function).
op1 The first operand in a generated arithmetic statement (in division, the
divisor).
op2 The second operand in a generated arithmetic statement (in division, the
dividend).
i1 , i2 The number of integer places in op1 and op2, respectively.
d1 , d2
The number of decimal places in op1 and op2, respectively.
ir The intermediate result when a generated arithmetic statement or
operation is performed. (Intermediate results are generated either in
registers or storage locations.)
ir1 , ir2
Successive intermediate results. (Successive intermediate results might have
the same storage location.)
676 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
ROUNDED phrase (Enterprise COBOL Language Reference)
Example: calculation of intermediate results
The following example shows how the compiler performs an arithmetic statement
as a succession of operations, storing intermediate results as needed.
COMPUTE Y = A + B * C - D / E + F ** G
The result is calculated in the following order:
1. Exponentiate F by G yielding ir1.
2. Multiply B by C yielding ir2.
3. Divide E into D yielding ir3.
4. Add A to ir2 yielding ir4.
5. Subtract ir3 from ir4 yielding ir5.
6. Add ir5 to ir1 yielding Y.
RELATED TASKS
Using arithmetic expressions on page 57
RELATED REFERENCES
Terminology used for intermediate results on page 676
Fixed-point data and intermediate results
The compiler determines the number of integer and decimal places in an
intermediate result.
Addition, subtraction, multiplication, and division
The following table shows the precision theoretically possible as the result of
addition, subtraction, multiplication, or division.
Operation Integer places Decimal places
+ or - (i1 or i2) + 1, whichever is greater d1 or d2, whichever is greater
* i1 + i2 d1 + d2
/ i2 + d1 (d2 - d1) or dmax, whichever is
greater
You must define the operands of any arithmetic statements with enough decimal
places to obtain the accuracy you want in the final result.
The following table shows the number of places the compiler carries for
fixed-point intermediate results of arithmetic operations that involve addition,
subtraction, multiplication, or division in compatibility mode (that is, when the
default compiler option ARITH(COMPAT) is in effect):
Value of i +
Value of i + d Value of d dmax Number of places carried for ir
<30 or =30 Any value Any value i integer and d decimal places
Appendix A. Intermediate results and arithmetic precision 677
Value of i +
Value of i + d Value of d dmax Number of places carried for ir
>30 <dmax or =dmax Any value 30-d integer and d decimal places
>dmax <30 or =30 i integer and 30-i decimal places
>30 30-dmax integer and dmax decimal
places
The following table shows the number of places the compiler carries for
fixed-point intermediate results of arithmetic operations that involve addition,
subtraction, multiplication, or division in extended mode (that is, when the compiler
option ARITH(EXTEND) is in effect):
Value of i +
Value of i + d Value of d dmax Number of places carried for ir
<31 or =31 Any value Any value i integer and d decimal places
>31 <dmax or =dmax Any value 31-d integer and d decimal places
>dmax <31 or =31 i integer and 31-i decimal places
>31 31-dmax integer and dmax decimal
places
Exponentiation
Exponentiation is represented by the expression op1 ** op2. Based on the
characteristics of op2, the compiler handles exponentiation of fixed-point numbers
in one of three ways:
v When op2 is expressed with decimals, floating-point instructions are used.
v When op2 is an integral literal or constant, the value d is computed as
d = d1 * |op2|
and the value i is computed based on the characteristics of op1:
When op1 is a data-name or variable,
i = i1 * |op2|
When op1 is a literal or constant, i is set equal to the number of integers in
the value of op1 ** |op2|.
In compatibility mode (compilation using ARITH(COMPAT)), the compiler having
calculated i and d takes the action indicated in the table below to handle the
intermediate results ir of the exponentiation.
Value of i + d Other conditions Action taken
<30 Any i integer and d decimal places are carried for ir.
=30 op1 has an odd i integer and d decimal places are carried for ir.
number of digits.
op1 has an even Same action as when op2 is an integral data-name or
number of digits. variable (shown below). Exception: for a 30-digit
integer raised to the power of literal 1, i integer and
d decimal places are carried for ir.
>30 Any Same action as when op2 is an integral data-name or
variable (shown below)
678 Enterprise COBOL for z/OS, V5.2 Programming Guide
In extended mode (compilation using ARITH(EXTEND)), the compiler having
calculated i and d takes the action indicated in the table below to handle the
intermediate results ir of the exponentiation.
Value of i + d Other conditions Action taken
<31 Any i integer and d decimal places are carried for ir.
=31 or >31 Any Same action as when op2 is an integral data-name or
variable (shown below). Exception: for a 31-digit
integer raised to the power of literal 1, i integer and
d decimal places are carried for ir.
If op2 is negative, the value of 1 is then divided by the result produced by the
preliminary computation. The values of i and d that are used are calculated
following the division rules for fixed-point data already shown above.
v When op2 is an integral data-name or variable, dmax decimal places and 30-dmax
(compatibility mode) or 31-dmax (extended mode) integer places are used. op1 is
multiplied by itself (|op2| - 1) times for nonzero op2.
If op2 is equal to 0, the result is 1. Division-by-0 and exponentiation SIZE ERROR
conditions apply.
Fixed-point exponents with more than nine significant digits are always truncated
to nine digits. If the exponent is a literal or constant, an E-level compiler diagnostic
message is issued; otherwise, an informational message is issued at run time.
Example: exponentiation in fixed-point arithmetic
RELATED REFERENCES
Terminology used for intermediate results on page 676
Truncated intermediate results on page 680
Binary data and intermediate results on page 680
Floating-point data and intermediate results on page 682
Intrinsic functions evaluated in fixed-point arithmetic on page 680
ARITH on page 309
SIZE ERROR phrases (Enterprise COBOL Language Reference)
Example: exponentiation in fixed-point arithmetic
The following example shows how the compiler performs an exponentiation to a
nonzero integer power as a succession of multiplications, storing intermediate
results as needed.
COMPUTE Y = A ** B
If B is equal to 4, the result is computed as shown below. The values of i and d that
are used are calculated according to the multiplication rules for fixed-point data
and intermediate results (referred to below).
1. Multiply A by A yielding ir1.
2. Multiply ir1 by A yielding ir2.
3. Multiply ir2 by A yielding ir3.
4. Move ir3 to ir4.
ir4 has dmax decimal places. Because B is positive, ir4 is moved to Y. If B were
equal to -4, however, an additional fifth step would be performed:
5. Divide ir4 into 1 yielding ir5.
ir5 has dmax decimal places, and would then be moved to Y.
Appendix A. Intermediate results and arithmetic precision 679
RELATED REFERENCES
Terminology used for intermediate results on page 676
Fixed-point data and intermediate results on page 677
Truncated intermediate results
Whenever the number of digits in an intermediate result exceeds 30 in
compatibility mode or 31 in extended mode, the compiler truncates to 30
(compatibility mode) or 31 (extended mode) digits and issues a warning. If
truncation occurs at run time, a message is issued and the program continues
running.
If you want to avoid the truncation of intermediate results that can occur in
fixed-point calculations, use floating-point operands (COMP-1 or COMP-2) instead.
RELATED CONCEPTS
Formats for numeric data on page 47
RELATED REFERENCES
Fixed-point data and intermediate results on page 677
ARITH on page 309
Binary data and intermediate results
If an operation that involves binary operands requires intermediate results longer
than 18 digits, the compiler converts the operands to internal decimal before
performing the operation. If the result field is binary, the compiler converts the
result from internal decimal to binary.
Binary operands are most efficient when intermediate results will not exceed nine
digits.
RELATED REFERENCES
Fixed-point data and intermediate results on page 677
ARITH on page 309
Intrinsic functions evaluated in fixed-point arithmetic
The compiler determines the inner-dmax and outer-dmax values for an intrinsic
function from the characteristics of the function.
Integer functions
Integer intrinsic functions return an integer; thus their outer-dmax is always zero.
For those integer functions whose arguments must all be integers, the inner-dmax is
thus also always zero.
The following table summarizes the inner-dmax and the precision of the function
result.
Function Inner-dmax Digit precision of function result
DATE-OF-INTEGER 0 8
DATE-TO-YYYYMMDD 0 8
DAY-OF-INTEGER 0 7
DAY-TO-YYYYDDD 0 7
FACTORIAL 0 30 in compatibility mode, 31 in extended mode
680 Enterprise COBOL for z/OS, V5.2 Programming Guide
Function Inner-dmax Digit precision of function result
INTEGER-OF-DATE 0 7
INTEGER-OF-DAY 0 7
LENGTH n/a 9
MOD 0 min(i1 i2)
ORD n/a 3
ORD-MAX 9
ORD-MIN 9
YEAR-TO-YYYY 0 4
INTEGER For a fixed-point argument: one more digit than in
the argument. For a floating-point argument: 30 in
compatibility mode, 31 in extended mode.
INTEGER-PART For a fixed-point argument: same number of digits
as in the argument. For a floating-point argument: 30
in compatibility mode, 31 in extended mode.
Mixed functions
A mixed intrinsic function is a function whose result type depends on the type of
its arguments. A mixed function is fixed point if all of its arguments are numeric
and none of its arguments is floating point. (If any argument of a mixed function is
floating point, the function is evaluated with floating-point instructions and returns
a floating-point result.) When a mixed function is evaluated with fixed-point
arithmetic, the result is integer if all of the arguments are integer; otherwise, the
result is fixed point.
For the mixed functions MAX, MIN, RANGE, REM, and SUM, the outer-dmax is always
equal to the inner-dmax (and both are thus zero if all the arguments are integer). To
determine the precision of the result returned for these functions, apply the rules
for fixed-point arithmetic and intermediate results (as referred to below) to each
step in the algorithm.
MAX
1. Assign the first argument to the function result.
2. For each remaining argument, do the following steps:
a. Compare the algebraic value of the function result with the
argument.
b. Assign the greater of the two to the function result.
MIN
1. Assign the first argument to the function result.
2. For each remaining argument, do the following steps:
a. Compare the algebraic value of the function result with the
argument.
b. Assign the lesser of the two to the function result.
RANGE
1. Use the steps for MAX to select the maximum argument.
2. Use the steps for MIN to select the minimum argument.
3. Subtract the minimum argument from the maximum.
4. Assign the difference to the function result.
Appendix A. Intermediate results and arithmetic precision 681
REM
1. Divide argument one by argument two.
2. Remove all noninteger digits from the result of step 1.
3. Multiply the result of step 2 by argument two.
4. Subtract the result of step 3 from argument one.
5. Assign the difference to the function result.
SUM
1. Assign the value 0 to the function result.
2. For each argument, do the following steps:
a. Add the argument to the function result.
b. Assign the sum to the function result.
RELATED REFERENCES
Terminology used for intermediate results on page 676
Fixed-point data and intermediate results on page 677
Floating-point data and intermediate results
ARITH on page 309
Floating-point data and intermediate results
If any operation in an arithmetic expression is computed in floating-point
arithmetic, the entire expression is computed as if all operands were converted to
floating point and the operations were performed using floating-point instructions.
Floating-point instructions are used to compute an arithmetic expression if any of
the following conditions is true of the expression:
v A receiver or operand is COMP-1, COMP-2, external floating point, or a
floating-point literal.
v An exponent contains decimal places.
v An exponent is an expression that contains an exponentiation or division
operator, and dmax is greater than zero.
v An intrinsic function is a floating-point function.
In compatibility mode, if an expression is computed in floating-point arithmetic,
the precision used to evaluate the arithmetic operations is determined as follows:
v Single precision is used if all receivers and operands are COMP-1 data items and
the expression contains no multiplication or exponentiation operations.
v In all other cases, long precision is used.
Whenever long-precision floating point is used for one operation in an arithmetic
expression, all operations in the expression are computed as if long floating-point
instructions were used.
In extended mode, if an expression is computed in floating-point arithmetic, the
precision used to evaluate the arithmetic operations is determined as follows:
v Single precision is used if all receivers and operands are COMP-1 data items and
the expression contains no multiplication or exponentiation operations.
v Long precision is used if all receivers and operands are COMP-1 or COMP-2 data
items, at least one receiver or operand is a COMP-2 data item, and the expression
contains no multiplication or exponentiation operations.
v In all other cases, extended precision is used.
682 Enterprise COBOL for z/OS, V5.2 Programming Guide
Whenever extended-precision floating point is used for one operation in an
arithmetic expression, all operations in the expression are computed as if
extended-precision floating-point instructions were used.
Alert: If a floating-point operation has an intermediate result field in which
exponent overflow occurs, the job is abnormally terminated.
Exponentiations evaluated in floating-point arithmetic
In compatibility mode, floating-point exponentiations are always evaluated using
long floating-point arithmetic. In extended mode, floating-point exponentiations
are always evaluated using extended-precision floating-point arithmetic.
The value of a negative number raised to a fractional power is undefined in
COBOL. For example, (-2) ** 3 is equal to -8, but (-2) ** (3.000001) is undefined.
When an exponentiation is evaluated in floating point and there is a possibility
that the result is undefined, the exponent is evaluated at run time to determine if it
has an integral value. If not, a diagnostic message is issued.
Intrinsic functions evaluated in floating-point arithmetic
In compatibility mode, floating-point intrinsic functions always return a long
(64-bit) floating-point value. In extended mode, floating-point intrinsic functions
always return an extended-precision (128-bit) floating-point value.
Mixed functions that have at least one floating-point argument are evaluated using
floating-point arithmetic.
RELATED REFERENCES
Terminology used for intermediate results on page 676
ARITH on page 309
Arithmetic expressions in nonarithmetic statements
Arithmetic expressions can appear in contexts other than arithmetic statements. For
example, you can use an arithmetic expression with the IF or EVALUATE statement.
In such statements, the rules for intermediate results with fixed-point data and for
intermediate results with floating-point data apply, with the following changes:
v Abbreviated IF statements are handled as though the statements were not
abbreviated.
v In an explicit relation condition where at least one of the comparands is an
arithmetic expression, dmax is the maximum number of decimal places for any
operand of either comparand, excluding divisors and exponents. The rules for
floating-point arithmetic apply if any of the following conditions is true:
Any operand in either comparand is COMP-1, COMP-2, external floating point,
or a floating-point literal.
An exponent contains decimal places.
An exponent is an expression that contains an exponentiation or division
operator, and dmax is greater than zero.
For example:
IF operand-1 = expression-1 THEN . . .
If operand-1 is a data-name defined to be COMP-2, the rules for floating-point
arithmetic apply to expression-1 even if it contains only fixed-point operands,
because it is being compared to a floating-point operand.
Appendix A. Intermediate results and arithmetic precision 683
v When the comparison between an arithmetic expression and another data item
or arithmetic expression does not use a relational operator (that is, there is no
explicit relation condition), the arithmetic expression is evaluated without regard
to the attributes of its comparand. For example:
EVALUATE expression-1
WHEN expression-2 THRU expression-3
WHEN expression-4
. . .
END-EVALUATE
In the statement above, each arithmetic expression is evaluated in fixed-point or
floating-point arithmetic based on its own characteristics.
RELATED CONCEPTS
Fixed-point contrasted with floating-point arithmetic on page 62
RELATED REFERENCES
Terminology used for intermediate results on page 676
Fixed-point data and intermediate results on page 677
Floating-point data and intermediate results on page 682
IF statement (Enterprise COBOL Language Reference)
EVALUATE statement (Enterprise COBOL Language Reference)
Conditional expressions (Enterprise COBOL Language Reference)
684 Enterprise COBOL for z/OS, V5.2 Programming Guide
Appendix B. Converting double-byte character set (DBCS)
data
The Language Environment service routines IGZCA2D and IGZCD2A were
intended for converting alphanumeric data items that contain DBCS data to and
from pure DBCS data items in order to reliably perform operations such as STRING,
UNSTRING, and reference modification.
These service routines continue to be provided for compatibility; however, using
national data items and the national conversion operations is now recommended
instead for this purpose.
The service routines do not support a code-page argument and are not sensitive to
the code page specified by the CODEPAGE compiler option. The DBCS compiler option
does not affect their operation.
RELATED TASKS
Converting to or from national (Unicode) representation on page 137
Processing alphanumeric data items that contain DBCS data on page 152
RELATED REFERENCES
DBCS notation
Alphanumeric to DBCS data conversion (IGZCA2D)
DBCS to alphanumeric data conversion (IGZCD2A) on page 688
CODEPAGE on page 313
DBCS notation
The symbols shown below are used in the DBCS data conversion examples to
describe DBCS items.
Symbols Meaning
< and > Shift-out (SO) and shift-in (SI), respectively
D0, D1, D2, . . ., Dn Any DBCS character except for double-byte EBCDIC
characters that correspond to single-byte EBCDIC
characters
.A, .B, .C, . . . Any double-byte EBCDIC character that corresponds
to a single-byte EBCDIC character. The period (.)
represents the value X'42'.
A single letter, such as A, B, or s Any single-byte EBCDIC character
Alphanumeric to DBCS data conversion (IGZCA2D)
The Language Environment IGZCA2D service routine converts alphanumeric data
that contains double-byte characters to pure DBCS data.
IGZCA2D syntax
To use the IGZCA2D service routine, pass the following four parameters to the
routine by using the CALL statement:
Copyright IBM Corp. 1991, 2015 685
parameter-1
The sending field for the conversion, handled as an alphanumeric data
item.
parameter-2
The receiving field for the conversion, handled as a DBCS data item.
You cannot use reference modification with parameter-2.
parameter-3
The number of bytes in parameter-1 to be converted.
It can be the LENGTH OF special register of parameter-1, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-1 to be
converted. Shift codes count as 1 byte each.
parameter-4
The number of bytes in parameter-2 that will receive the converted data.
It can be the LENGTH OF special register of parameter-2, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-2 to receive
the converted data.
Usage notes
v You can pass parameter-1, parameter-3, and parameter-4 to the routine BY
REFERENCE or BY CONTENT, but you must pass parameter-2 BY REFERENCE.
v The compiler does not perform syntax checking on these parameters. Ensure that
the parameters are correctly set and passed in the CALL statement to the
conversion routine. Otherwise, results are unpredictable.
v When creating parameter-2 from parameter-1, IGZCA2D makes these changes:
Removes the shift codes, leaving the DBCS data unchanged
Converts the single-byte (nonspace) EBCDIC character X'nn' to a character
represented by X'42nn'
Converts the single-byte space (X'40') to DBCS space (X'4040'), instead of
X'4240'
v IGZCA2D does not change the contents of parameter-1, parameter-3, or
parameter-4.
v The valid range for the contents of parameter-3 and for the contents of
parameter-4 is 1 to 134,217,727.
Example: IGZCA2D on page 687
RELATED REFERENCES
IGZCA2D return codes
IGZCA2D return codes
IGZCA2D sets the RETURN-CODE special register to reflect the status of the conversion.
Table 93. IGZCA2D return codes
Return code Explanation
0 parameter-1 was converted and the results were placed in parameter-2.
2 parameter-1 was converted and the results were placed in parameter-2.
parameter-2 was padded on the right with DBCS spaces.
4 parameter-1 was converted and the results were placed in parameter-2. The
DBCS data placed in parameter-2 was truncated on the right.
686 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 93. IGZCA2D return codes (continued)
Return code Explanation
6 parameter-1 was converted and the results were placed in parameter-2. A
single-byte character in the range X'00' to X'3F' or X'FF' was encountered.
The valid single-byte character was converted into an out-of-range DBCS
character.
8 parameter-1 was converted and the results were placed in parameter-2. A
single-byte character in the range X'00' to X'3F' or X'FF' was encountered.
The valid single-byte character was converted into an out-of-range DBCS
character.
parameter-2 was padded on the right with DBCS spaces.
10 parameter-1 was converted and the results were placed in parameter-2. A
single-byte character in the range X'00' to X'3F' or X'FF' was encountered.
The valid single-byte character was converted into an out-of-range DBCS
character.
The DBCS data in parameter-2 was truncated on the right.
12 An odd number of bytes was found between paired shift codes in
parameter-1. No conversion occurred.
13 Unpaired or nested shift codes were found in parameter-1. No conversion
occurred.
14 parameter-1 and parameter-2 were overlapping. No conversion occurred.
15 The value provided for parameter-3 or parameter-4 was out of range. No
conversion occurred.
16 An odd number of bytes was coded in parameter-4. No conversion
occurred.
Example: IGZCA2D
This example CALL statement converts the alphanumeric data in alpha-item to
DBCS data. The results of the conversion are placed in dbcs-item.
CALL "IGZCA2D" USING BY REFERENCE alpha-item dbcs-item
BY CONTENT LENGTH OF alpha-item LENGTH OF dbcs-item
Suppose the contents of alpha-item and dbcs-item and the lengths before the
conversion are:
alpha-item = AB<D1D2D3>CD
dbcs-item = D4D5D6D7D8D9D0
LENGTH OF alpha-item = 12
LENGTH OF dbcs-item = 14
Then after the conversion, alpha-item and dbcs-item will contain:
alpha-item = AB<D1D2D3>CD
dbcs-item = .A.BD1D2D3.C.D
The content of the RETURN-CODE register is 0.
RELATED REFERENCES
DBCS notation on page 685
Appendix B. Converting double-byte character set (DBCS) data 687
DBCS to alphanumeric data conversion (IGZCD2A)
The Language Environment IGZCD2A routine converts pure DBCS data to
alphanumeric data that can contain double-byte characters.
IGZCD2A syntax
To use the IGZCD2A service routine, pass the following four parameters to the
routine using the CALL statement:
parameter-1
The sending field for the conversion, handled as a DBCS data item.
parameter-2
The receiving field for the conversion, handled as an alphanumeric data
item.
parameter-3
The number of bytes in parameter-1 to be converted.
It can be the LENGTH OF special register of parameter-1, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-1 to be
converted.
parameter-4
The number of bytes in parameter-2 that will receive the converted data.
It can be the LENGTH OF special register of parameter-2, or a 4-byte USAGE IS
BINARY data item containing the number of bytes of parameter-2 to receive
the converted data. Shift codes count as 1 byte each.
Usage notes
v You can pass parameter-1, parameter-3, and parameter-4 to the routine BY
REFERENCE or BY CONTENT, but you must pass parameter-2 BY REFERENCE.
v The compiler does not perform syntax checking on these parameters. Ensure that
the parameters are correctly set and passed to the conversion routine. Otherwise,
results are unpredictable.
v When creating parameter-2 from parameter-1, IGZCD2A makes these changes:
Inserts shift codes around DBCS characters that do not correspond to
single-byte EBCDIC characters
Converts DBCS characters to single-byte characters when the DBCS characters
correspond to single-byte EBCDIC characters
Converts the DBCS space (X'4040') to a single-byte space (X'40')
v IGZCD2A does not change the contents of parameter-1, parameter-3, or
parameter-4.
v If the converted data contains double-byte characters, shift codes are counted in
the length of parameter-2.
v The valid range for the contents of parameter-3 and for the contents of
parameter-4 is 1 to 134,217,727.
Example: IGZCD2A on page 689
RELATED REFERENCES
IGZCD2A return codes on page 689
688 Enterprise COBOL for z/OS, V5.2 Programming Guide
IGZCD2A return codes
IGZCD2A sets the RETURN-CODE special register to reflect the status of the conversion.
Table 94. IGZCD2A return codes
Return code Explanation
0 parameter-1 was converted and the results were placed in parameter-2.
2 parameter-1 was converted and the results were placed in parameter-2.
parameter-2 was padded on the right with single-byte spaces.
4 parameter-1 was converted and the results were placed in parameter-2.
parameter-2 was truncated on the right.1
14 parameter-1 and parameter-2 were overlapping. No conversion occurred.
15 The value of parameter-3 or parameter-4 was out of range. No conversion
occurred.
16 An odd number of bytes was coded in parameter-3. No conversion
occurred.
1. If a truncation occurs within the DBCS characters, the truncation is on an even-byte
boundary and a shift-in (SI) is inserted. If necessary, the alphanumeric data is padded
with a single-byte space after the shift-in.
Example: IGZCD2A
This example CALL statement converts the DBCS data in dbcs-item to alphanumeric
data with double-byte characters. The results of the conversion are placed in
alpha-item.
CALL "IGZCD2A" USING BY REFERENCE dbcs-item alpha-item
BY CONTENT LENGTH OF dbcs-item LENGTH OF alpha-item
Suppose the contents of dbcs-item and alpha-item and the lengths before the
conversion are:
dbcs-item = .A.BD1D2D3.C.D
alpha-item = ssssssssssss
LENGTH OF dbcs-item = 14
LENGTH OF alpha-item = 12
Then after the conversion, dbcs-item and alpha-item will contain:
dbcs-item = .A.BD1D2D3.C.D
alpha-item = AB<D1D2D3>CD
The content of the RETURN-CODE register is 0.
RELATED REFERENCES
DBCS notation on page 685
Appendix B. Converting double-byte character set (DBCS) data 689
690 Enterprise COBOL for z/OS, V5.2 Programming Guide
Appendix C. XML reference material
The following information describes the XML exception codes that might be
returned during XML parsing or XML generation.
RELATED REFERENCES
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect on page 693
XML GENERATE exceptions on page 700
XML specification
| XML PARSE exceptions with XMLPARSE(XMLSS) in effect
| When the z/OS XML System Services parser passes control to your processing
procedure for an exception event, the XML-CODE special register contains the
exception code, which is formed from a return code and a reason code.
The return code and reason code are each a halfword binary value. The exception
code is the concatenation of those two values: the return code in the high-order
halfword, and the reason code in the low-order halfword.
The return codes and reason codes are documented as hexadecimal values in the
z/OS XML System Services User's Guide and Reference, referenced below, and in
Table 95 on page 692 below.
After most exception events, the parser does not continue processing; the value in
XML-CODE at the end of the XML PARSE statement is the original exception code set
by the parser.
When the processing procedure returns to the parser after the exception event,
control transfers to the statement specified in the ON EXCEPTION phrase, or to the
end of the XML PARSE statement if you did not code an ON EXCEPTION phrase.
Validation exceptions:
If you code an XML PARSE statement that contains the VALIDATING phrase, and the
z/OS XML System Services parser determines that the document is not valid, the
parser generates return code 24 (hexadecimal 18, XRC_NOT_VALID).
Exceptions that are unique to Enterprise COBOL:
Some exceptions are unique to Enterprise COBOL and thus are not documented in
the z/OS XML System Services User's Guide and Reference, for example, errors that
occur during XML schema retrieval. The return code for exceptions with reason
codes in the hexadecimal range 800 to 899 is 4 (hexadecimal 0004, XRC_WARNING).
For other exceptions, the return code is 16 (hexadecimal 0010, XRC_FATAL). The
exception code (the value in special register XML-CODE), is formed from this return
code concatenated with one of the reason codes shown in the following table.
Copyright IBM Corp. 1991, 2015 691
Table 95. Reason codes for XML PARSE exceptions that are unique to Enterprise
COBOL
Reason code
(hexadecimal) Description
700 VALIDATING WITH FILE is not supported under CICS.
701 The optimized XML schema that was read in was too short, or the file
was empty.
702 The file identifier for the schema was not a ddname or
environment-variable name.
703 The DSN value contained a space character in a position where a space is
not allowed.
704 The DSN value specified a temporary data set.
705 The PATH value contained an unescaped space character.
706 The PATH value contained a path name that was not an absolute path.
707 Memory allocation for the XML schema buffer failed.
708 The environment variable was null or contained only spaces.
709 The environment variable contained an invalid keyword.
710 The DSN value contained an invalid character after the member name.
711 The DSN value did not specify a member name.
712 The DSN value did not specify a data set name, or parentheses were not
specified correctly.
713 The PATH value did not specify a path name, or parentheses were not
specified correctly.
714 The DSN value contained an extra parenthesis.
715 The PATH value contained an extra parenthesis.
716 The DSN value was missing the closing parenthesis.
717 The PATH value was missing the closing parenthesis.
718 The DSN value contained an escape character.
720 A character reference for an unrepresentable character was not resolved.
721 An unrepresentable character reference in the document type declaration
is not supported.
800 The attribute name used an undeclared prefix.
801 The START-OF-ELEMENT name used an undeclared prefix. (The
END-OF-ELEMENT name must match, so using the same undeclared prefix
does not cause another exception.)
900 Internal error. Report the error to your service representative.
For any of the reason codes except 900, correct the error and then retry your
program.
RELATED CONCEPTS
XML-CODE on page 525
XML events on page 524
RELATED TASKS
Handling XML PARSE exceptions on page 542
692 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
XML PARSE statement (Enterprise COBOL Language Reference)
z/OS XML System Services User's Guide and Reference
| XML PARSE exceptions with XMLPARSE(COMPAT) in effect
| When an exception event occurs, the XML parser that is provided with the
| Enterprise COBOL library sets special register XML-CODE to a value that identifies
| the exception. Depending on the value in XML-CODE, the parser might or might not
| be able to continue processing after the exception, as detailed in the information
| referenced below.
| RELATED REFERENCES
| XML PARSE exceptions that allow continuation
| XML PARSE exceptions that do not allow continuation on page 697
| XML PARSE exceptions that allow continuation
| If the XMLPARSE(COMPAT) compiler option is in effect, whether the XML parser can
| continue processing after an exception event depends upon the value of the
| exception code.
| The parser can continue processing if the exception code, which is in special
| register XML-CODE, is within one of the following ranges:
| v 1 - 99
| v 100,001 - 165,535
| The following table describes each exception, and identifies the actions that the
| parser takes if you request that it continue after the exception. Some of the
| descriptions use the following terms:
| v Actual document encoding
| v Document encoding declaration
| For definitions of the terms, see the related concept about XML input document
| encoding.
| Table 96. XML PARSE exceptions that allow continuation
| Exception
| code
| (decimal) Description Parser action on continuation
| 1 The parser found an invalid The parser continues detecting errors until
| character while scanning white it reaches the end of the document or
| space outside element content. encounters an error that does not allow
| continuation. The parser does not signal
| For further information about any further normal events, except for the
| white space, see the related END-OF-DOCUMENT event.
| concept about XML input
| document encoding.
| 2 The parser found an invalid The parser continues detecting errors until
| start of a processing it reaches the end of the document or
| instruction, element, comment, encounters an error that does not allow
| or document type declaration continuation. The parser does not signal
| outside element content. any further normal events, except for the
| END-OF-DOCUMENT event.
Appendix C. XML reference material 693
| Table 96. XML PARSE exceptions that allow continuation (continued)
| Exception
| code
| (decimal) Description Parser action on continuation
| 3 The parser found a duplicate The parser continues detecting errors until
| attribute name. it reaches the end of the document or
| encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 4 The parser found the markup The parser continues detecting errors until
| character '<' in an attribute it reaches the end of the document or
| value. encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 5 The start and end tag names of The parser continues detecting errors until
| an element did not match. it reaches the end of the document or
| encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 6 The parser found an invalid The parser continues detecting errors until
| character in element content. it reaches the end of the document or
| encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 7 The parser found an invalid The parser continues detecting errors until
| start of an element, comment, it reaches the end of the document or
| processing instruction, or encounters an error that does not allow
| CDATA section in element continuation. The parser does not signal
| content. any further normal events, except for the
| END-OF-DOCUMENT event.
| 8 The parser found in element The parser continues detecting errors until
| content the CDATA closing it reaches the end of the document or
| character sequence ']]>' without encounters an error that does not allow
| the matching opening character continuation. The parser does not signal
| sequence '<![CDATA['. any further normal events, except for the
| END-OF-DOCUMENT event.
| 9 The parser found an invalid The parser continues detecting errors until
| character in a comment. it reaches the end of the document or
| encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 10 The parser found in a comment The parser continues detecting errors until
| the character sequence '--' (two it reaches the end of the document or
| hyphens) not followed by '>'. encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
694 Enterprise COBOL for z/OS, V5.2 Programming Guide
| Table 96. XML PARSE exceptions that allow continuation (continued)
| Exception
| code
| (decimal) Description Parser action on continuation
| 11 The parser found an invalid The parser continues detecting errors until
| character in a processing it reaches the end of the document or
| instruction data segment. encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 12 The XML declaration was not The parser continues detecting errors until
| at the beginning of the it reaches the end of the document or
| document. encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 13 The parser found an invalid The parser continues detecting errors until
| digit in a hexadecimal character it reaches the end of the document or
| reference (of the form encounters an error that does not allow
| �). continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 14 The parser found an invalid The parser continues detecting errors until
| digit in a decimal character it reaches the end of the document or
| reference (of the form &#dddd;). encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 15 The encoding declaration value The parser continues detecting errors until
| in the XML declaration did not it reaches the end of the document or
| begin with lowercase or encounters an error that does not allow
| uppercase A through Z. continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 16 A character reference did not The parser continues detecting errors until
| refer to a legal XML character. it reaches the end of the document or
| encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 17 The parser found an invalid The parser continues detecting errors until
| character in an entity reference it reaches the end of the document or
| name. encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
| 18 The parser found an invalid The parser continues detecting errors until
| character in an attribute value. it reaches the end of the document or
| encounters an error that does not allow
| continuation. The parser does not signal
| any further normal events, except for the
| END-OF-DOCUMENT event.
Appendix C. XML reference material 695
| Table 96. XML PARSE exceptions that allow continuation (continued)
| Exception
| code
| (decimal) Description Parser action on continuation
| 70 The actual document encoding The parser uses the encoding specified by
| was EBCDIC, and the CODEPAGE theCODEPAGE compiler option.
| compiler option specified a
| supported EBCDIC code page,
| but the document encoding
| declaration did not specify a
| supported EBCDIC code page.
| 71 The actual document encoding The parser uses the encoding specified by
| was EBCDIC, and the the document encoding declaration.
| document encoding declaration
| specified a supported EBCDIC
| encoding, but the CODEPAGE
| compiler option did not specify
| a supported EBCDIC code
| page.
| 72 The actual document encoding The parser uses EBCDIC code page 1140
| was EBCDIC, the CODEPAGE (USA, Canada, . . . Euro Country Extended
| compiler option did not specify Code Page).
| a supported EBCDIC code
| page, and the document did
| not contain an encoding
| declaration.
| 73 The actual document encoding The parser uses EBCDIC code page 1140
| was EBCDIC, but neither the (USA, Canada, . . . Euro Country Extended
| CODEPAGE compiler option nor Code Page).
| the document encoding
| declaration specified a
| supported EBCDIC code page.
| 82 The actual document encoding The parser uses ASCII code page 819
| was ASCII, but the document (ISO-8859-1 Latin 1/Open Systems).
| did not contain an encoding
| declaration.
| 83 The actual document encoding The parser uses ASCII code page 819
| was ASCII, but the document (ISO-8859-1 Latin 1/Open Systems).
| encoding declaration did not
| specify code page 813, 819, or
| 920.
| 92 The document data item was The parser uses code page 1200 (Unicode
| alphanumeric, but the actual UTF-16).
| document encoding was
| Unicode UTF-16.
| 100,001 - The CODEPAGE compiler option If you set XML-CODE to zero before
| 165,535 and the document encoding returning from the EXCEPTION event, the
| declaration specified different parser uses the encoding specified by the
| supported EBCDIC code pages. CODEPAGE compiler option. If you set
| XML-CODE contains the code XML-CODE to the CCSID for the document
| page CCSID for the encoding encoding declaration (by subtracting
| declaration plus 100,000. 100,000), the parser uses this encoding.
|
696 Enterprise COBOL for z/OS, V5.2 Programming Guide
| RELATED CONCEPTS
| XML-CODE on page 525
| XML input document encoding on page 537
| RELATED TASKS
| Handling XML PARSE exceptions on page 542
| RELATED REFERENCES
| XMLPARSE on page 368 (compiler option)
| XML PARSE exceptions that do not allow continuation
| If the XMLPARSE(COMPAT) compiler option is in effect, the XML parser cannot
| continue processing if any of the exceptions described below occurs.
| No further events are returned from the parser for any of these exceptions even if
| the processing procedure sets XML-CODE to zero before passing control back to the
| parser. The parser transfers control to the statement in the ON EXCEPTION phrase, if
| specified, otherwise to the end of the XML PARSE statement.
| Table 97. XML PARSE exceptions that do not allow continuation (for XMLPARSE(COMPAT))
| Exception
| code (decimal) Description
| 100 The parser reached the end of the document while scanning the start of
| the XML declaration.
| 101 The parser reached the end of the document while looking for the end of
| the XML declaration.
| 102 The parser reached the end of the document while looking for the root
| element.
| 103 The parser reached the end of the document while looking for the version
| information in the XML declaration.
| 104 The parser reached the end of the document while looking for the version
| information value in the XML declaration.
| 106 The parser reached the end of the document while looking for the
| encoding declaration value in the XML declaration.
| 108 The parser reached the end of the document while looking for the
| standalone declaration value in the XML declaration.
| 109 The parser reached the end of the document while scanning an attribute
| name.
| 110 The parser reached the end of the document while scanning an attribute
| value.
| 111 The parser reached the end of the document while scanning a character
| reference or entity reference in an attribute value.
| 112 The parser reached the end of the document while scanning an empty
| element tag.
| 113 The parser reached the end of the document while scanning the root
| element name.
| 114 The parser reached the end of the document while scanning an element
| name.
| 115 The parser reached the end of the document while scanning character data
| in element content.
Appendix C. XML reference material 697
| Table 97. XML PARSE exceptions that do not allow continuation (for
| XMLPARSE(COMPAT)) (continued)
| Exception
| code (decimal) Description
| 116 The parser reached the end of the document while scanning a processing
| instruction in element content.
| 117 The parser reached the end of the document while scanning a comment or
| CDATA section in element content.
| 118 The parser reached the end of the document while scanning a comment in
| element content.
| 119 The parser reached the end of the document while scanning a CDATA
| section in element content.
| 120 The parser reached the end of the document while scanning a character
| reference or entity reference in element content.
| 121 The parser reached the end of the document while scanning after the close
| of the root element.
| 122 The parser found a possible invalid start of a document type declaration.
| 123 The parser found a second document type declaration.
| 124 The first character of the root element name was not a letter, '_', or ':'.
| 125 The first character of the first attribute name of an element was not a
| letter, '_', or ':'.
| 126 The parser found an invalid character either in or following an element
| name.
| 127 The parser found a character other than '=' following an attribute name.
| 128 The parser found an invalid attribute value delimiter.
| 130 The first character of an attribute name was not a letter, '_', or ':'.
| 131 The parser found an invalid character either in or following an attribute
| name.
| 132 An empty element tag was not terminated by a '>' following the '/'.
| 133 The first character of an element end tag name was not a letter, '_', or ':'.
| 134 An element end tag name was not terminated by a '>'.
| 135 The first character of an element name was not a letter, '_', or ':'.
| 136 The parser found an invalid start of a comment or CDATA section in
| element content.
| 137 The parser found an invalid start of a comment.
| 138 The first character of a processing instruction target name was not a letter,
| '_', or ':'.
| 139 The parser found an invalid character in or following a processing
| instruction target name.
| 140 A processing instruction was not terminated by the closing character
| sequence '?>'.
| 141 The parser found an invalid character following '&' in a character
| reference or entity reference.
| 142 The version information was not present in the XML declaration.
| 143 'version' in the XML declaration was not followed by '='.
| 144 The version declaration value in the XML declaration is either missing or
| improperly delimited.
698 Enterprise COBOL for z/OS, V5.2 Programming Guide
| Table 97. XML PARSE exceptions that do not allow continuation (for
| XMLPARSE(COMPAT)) (continued)
| Exception
| code (decimal) Description
| 145 The version information value in the XML declaration specified a bad
| character, or the start and end delimiters did not match.
| 146 The parser found an invalid character following the version information
| value closing delimiter in the XML declaration.
| 147 The parser found an invalid attribute instead of the optional encoding
| declaration in the XML declaration.
| 148 'encoding' in the XML declaration was not followed by '='.
| 149 The encoding declaration value in the XML declaration is either missing
| or improperly delimited.
| 150 The encoding declaration value in the XML declaration specified a bad
| character, or the start and end delimiters did not match.
| 151 The parser found an invalid character following the encoding declaration
| value closing delimiter in the XML declaration.
| 152 The parser found an invalid attribute instead of the optional standalone
| declaration in the XML declaration.
| 153 standalone in the XML declaration was not followed by =.
| 154 The standalone declaration value in the XML declaration is either missing
| or improperly delimited.
| 155 The standalone declaration value was neither 'yes' nor 'no' only.
| 156 The standalone declaration value in the XML declaration specified a bad
| character, or the start and end delimiters did not match.
| 157 The parser found an invalid character following the standalone
| declaration value closing delimiter in the XML declaration.
| 158 The XML declaration was not terminated by the proper character sequence
| '?>', or contained an invalid attribute.
| 159 The parser found the start of a document type declaration after the end of
| the root element.
| 160 The parser found the start of an element after the end of the root element.
| 315 The actual document encoding was UTF-16 little-endian, which the parser
| does not support on this platform.
| 316 The actual document encoding was UCS4, which the parser does not
| support.
| 317 The parser cannot determine the document encoding. The document
| might be damaged.
| 318 The actual document encoding was UTF-8, which the parser does not
| support.
| 320 The document data item was national, but the actual document encoding
| was EBCDIC.
| 321 The document data item was national, but the actual document encoding
| was ASCII.
| 500 - 599 Internal error. Report the error to your service representative.
|
| RELATED CONCEPTS
| XML-CODE on page 525
Appendix C. XML reference material 699
| RELATED TASKS
| Handling XML PARSE exceptions on page 542
|
XML GENERATE exceptions
One of several exception codes might be returned in the XML-CODE special register
during XML generation. If one of these exceptions occurs, control is passed to the
statement in the ON EXCEPTION phrase, or to the end of the XML GENERATE statement
if you did not code an ON EXCEPTION phrase.
Table 98. XML GENERATE exceptions
Exception
code (decimal) Description
400 The receiver was too small to contain the generated XML document. The
COUNT IN data item, if specified, contains the count of character positions
that were actually generated.
401 A DBCS data-name contained a character that, when converted to
Unicode, was not valid in an XML element or attribute name.
402 The first character of a DBCS data-name, when converted to Unicode, was
not valid as the first character of an XML element or attribute name.
403 The value of an OCCURS DEPENDING ON variable exceeded 16,777,215.
410 The CCSID page specified by the CODEPAGE compiler option is not
supported for conversion to Unicode.
411 The CCSID specified by the CODEPAGE compiler option is not a supported
single-byte EBCDIC CCSID.
414 The CCSID specified for the XML document was invalid or was not
supported.
415 The receiver was national, but the encoding specified for the document
was not UTF-16.
416 The XML namespace identifier contained invalid XML characters.
417 Element character content or an attribute value contained characters that
are illegal in XML content. XML generation has continued, with the
element tag name or the attribute name prefixed with 'hex.' and the
original data value represented in the document in hexadecimal.
| Any TYPE IS CONTENT specification is ignored, and the item is treated
| as an element.
418 Substitution characters were generated by encoding conversion.
419 The XML namespace prefix was invalid.
| 420 The receiver was alphanumeric and the input included national or DBCS
| data or names, but the encoding specified for the document was not 1208.
600-699 Internal error. Report the error to your service representative.
RELATED TASKS
Handling XML GENERATE exceptions on page 567
700 Enterprise COBOL for z/OS, V5.2 Programming Guide
Appendix D. EXIT compiler option
You can use the EXIT compiler option to provide user-supplied modules in place of
various compiler functions. For details about processing of each exit module, error
handling for exit modules, or using the EXIT option with CICS, SQL and SQLIMS
statements, see the following topics.
RELATED TASKS
Using the user-exit work area
Calling from exit modules on page 702
Using the EXIT compiler option with CICS, SQL and
SQLIMS statements
RELATED REFERENCES
EXIT on page 324
Processing of INEXIT on page 702
Processing of LIBEXIT on page 703
Processing of PRTEXIT on page 706
Processing of ADEXIT on page 707
Processing of MSGEXIT on page 709
Error handling for exit modules on page 717
Using the user-exit work area
When you use one of the user exits, the compiler provides a work area in which
you can save the address of GETMAIN storage obtained by the exit module. Having
such a work area lets the module be reentrant.
The user-exit work area consists of 6 fullwords that reside on a fullword boundary.
These fullwords are initialized to binary zeros before the first exit routine is
invoked. The address of the work area is passed to the exit module in a parameter
list. After initialization, the compiler makes no further reference to the work area.
The words in the user-exit work area are used by the individual exit modules as
shown in the following table.
Table 99. Layout of the user-exit work area
Word number Used by module:
1 INEXIT
2 LIBEXIT
3 PRTEXIT
4 ADEXIT
5 (Reserved)
6 MSGEXIT
RELATED REFERENCES
Processing of INEXIT on page 702
Processing of LIBEXIT on page 703
Copyright IBM Corp. 1991, 2015 701
Processing of PRTEXIT on page 706
Processing of ADEXIT on page 707
Processing of MSGEXIT on page 709
Calling from exit modules
To call COBOL programs or library routines within your exit modules, use
standard COBOL linkage. You need to be aware of the register conventions in
order to trace the call chain correctly.
When a call is made to a program or to a routine in an exit module, the registers
are set up as follows:
R1 Points to the parameter list passed to the called program or library routine
R13 Points to the register save area provided by the calling program or routine
R14 Holds the return address of the calling program or routine
R15 Holds the address of the called program or routine
Exit modules must have RMODE attribute 24 and AMODE attribute ANY.
RELATED CONCEPTS
Storage and its addressability on page 39
Processing of INEXIT
| The INEXIT exit module is used to read source code from a user-supplied program
| object in place of SYSIN.
Table 100. INEXIT processing
Action by compiler Action by exit module
Loads the exit module (mod1) during
initialization
Calls the exit module with an OPEN Prepares its source for processing. Passes the
operation code (op code) status of the OPEN request back to the
compiler.
Calls the exit module with a GET op code Returns either the address and length of the
when a source statement is needed next statement or the end-of-data indication
(if no more source statements exist)
Calls the exit module with a CLOSE op code Releases any resources that are related to its
when the end-of-data is presented output
INEXIT parameters
The compiler uses 10 parameters, passed by reference, to communicate with the
exit module. The return code, data length, and data parameters are set by the exit
module for return to the compiler; the other items are passed from the compiler to
the exit module.
702 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 101. INEXIT parameters
Parameter
number Parameter item Description of item
1 User-exit type Halfword that identifies which user exit is to perform
the operation.
1=INEXIT
2 Operation code Halfword that indicates the type of operation:
v 0=OPEN
v 1=CLOSE
v 2=GET
3 Return code Fullword, set by the exit module, that indicates the
success of the requested operation:
v 0=Operation was successful
v 4=End-of-data
v 12=Operation failed
4 User-exit work area Six-fullword work area provided by the compiler for
use by the user-exit module.
First word: for use by INEXIT
5 Data length Fullword, set by the exit module, that specifies the
length of the record being returned by the GET
operation (must be 80)
6 Data or str1 Fullword, set by the exit module, that contains the
address of the record in a user-owned buffer, for the
GET operation.
str1 applies only to OPEN. The first halfword (on a
halfword boundary) contains the length of the string,
followed by the string.
7 Not used (Used only by LIBEXIT and MSGEXIT)
8 Not used (Used only by LIBEXIT)
9 Not used (Used only by LIBEXIT)
10 Not used (Used only by LIBEXIT)
RELATED TASKS
Using the user-exit work area on page 701
Calling from exit modules on page 702
Using the EXIT compiler option with CICS, SQL and
SQLIMS statements
Processing of LIBEXIT
The LIBEXIT exit module is used in place of the SYSLIB, or library-name, data set.
Calls are made to the module by the compiler to obtain copybooks whenever COPY
or BASIS statements are encountered.
Table 102. LIBEXIT processing
Action by compiler Action by exit module
Loads the exit module (mod2)
during initialization
Appendix D. EXIT compiler option 703
Table 102. LIBEXIT processing (continued)
Action by compiler Action by exit module
Calls the exit module with an Prepares the specified library-name for processing.
OPEN operation code (op code) Passes the status of the OPEN request to the
compiler.
Calls the exit module with a FIND Establishes positioning at the requested text-name (or
op code if the library-name was basis-name) in the specified library-name; this place
successfully opened becomes the active copybook. Passes an appropriate
return code to the compiler when positioning is
complete.
Calls the exit module with a GET Passes the compiler either the length and address of
op code the record to be copied from the active copybook or
the end-of-data indicator
Calls the exit module with a Releases any resources that are related to its input
CLOSE op code when the
end-of-data is presented
Processing of LIBEXIT with nested COPY statements
Any record from the active copybook can contain a COPY statement. (However,
nested COPY statements cannot contain the REPLACING phrase, and a COPY statement
with the REPLACING phrase cannot contain nested COPY statements.)
You cannot make recursive calls to text-name. That is, a copybook can be named
only once in a set of nested COPY statements until the end-of-data for that
copybook is reached.
The following table shows how the processing of LIBEXIT changes when there are
one or more valid COPY statements that are not nested.
Table 103. LIBEXIT processing with nonnested COPY statements
Action by compiler Action by exit module
Loads the exit module (mod2)
during initialization
Calls the exit module with an Prepares the specified library-name for processing. Passes
OPEN operation code (op the status of the OPEN request to the compiler.
code)
Calls the exit module with a Establishes positioning at the requested text-name (or
FIND op code if the basis-name) in the specified library-name; this place
library-name was successfully becomes the active copybook. Passes an appropriate
opened return code to the compiler when positioning is complete.
Calls the exit module with a Reestablishes positioning at the previous active copybook.
FIND op code if the Passes an appropriate return code to the compiler when
library-name was successfully positioning is complete.
opened
Calls the exit module with a Passes the compiler the same record as was passed
GET op code. Verifies that the previously from this copybook. After verification, passes
same record was passed. either the length and address of the record to be copied
from the active copybook or the end-of-data indicator.
Calls the exit module with a Releases any resources that are related to its input
CLOSE op code when the
end-of-data is presented
704 Enterprise COBOL for z/OS, V5.2 Programming Guide
The following table shows how the processing of LIBEXIT changes when the
compiler encounters a valid nested COPY statement.
Table 104. LIBEXIT processing with nested COPY statements
Action by compiler Action by exit module
If the requested library-name Pushes its control information about the active copybook
from the nested COPY statement onto a stack. Completes the requested action (OPEN). The
was not previously opened, newly requested text-name (or basis-name) becomes the
calls the exit module with an active copybook.
OPEN op code
Calls the exit module with a Pushes its control information about the active copybook
FIND op code for the onto a stack. Completes the requested action (FIND). The
requested new text-name newly requested text-name (or basis-name) becomes the
active copybook.
Calls the exit module with a Passes the compiler either the length and address of the
GET op code record to be copied from the active copybook or the
end-of-data indicator. At end-of-data, pops its control
information from the stack.
LIBEXIT parameters
The compiler uses 10 parameters, passed by reference, to communicate with the
exit module. The return code, data length, and data parameters are set by the exit
module for return to the compiler; the other items are passed from the compiler to
the exit module.
Table 105. LIBEXIT parameters
Parameter
number Parameter item Description of item
1 User-exit type Halfword that identifies which user exit is to perform
the operation.
2=LIBEXIT
2 Operation code Halfword that indicates the type of operation:
v 0=OPEN
v 1=CLOSE
v 2=GET
v 4=FIND
3 Return code Fullword, set by the exit module, that indicates the
success of the requested operation:
v 0=Operation was successful
v 4=End-of-data
v 12=Operation failed
4 User-exit work area Six-fullword work area provided by the compiler for
use by the user-exit module.
Second word: for use by LIBEXIT
5 Data length Fullword, set by the exit module, that specifies the
length of the record being returned by the GET
operation (must be 80)
Appendix D. EXIT compiler option 705
Table 105. LIBEXIT parameters (continued)
Parameter
number Parameter item Description of item
6 Data or str2 Fullword, set by the exit module, that contains the
address of the record in a user-owned buffer, for the
GET operation.
str2 applies only to OPEN. The first halfword (on a
halfword boundary) contains the length of the string,
followed by the string.
7 System library-name Eight-character area that contains the library-name from
the COPY statement. Processing and conversion rules
for a program-name are applied. Padded with blanks
if required. Applies to OPEN, CLOSE, and FIND.
8 System text-name Eight-character area that contains the text-name from
the COPY statement (basis-name from BASIS statement).
Processing and conversion rules for a program-name are
applied. Padded with blanks if required. Applies only
to FIND.
9 Library-name Thirty-character area that contains the full library-name
from the COPY statement. Padded with blanks if
required, and used as is (not folded to uppercase).
Applies to OPEN, CLOSE, and FIND.
10 Text-name Thirty-character area that contains the full text-name
from the COPY statement. Padded with blanks if
required, and used as is (not folded to uppercase).
Applies only to FIND.
RELATED TASKS
Using the user-exit work area on page 701
Calling from exit modules on page 702
Using the EXIT compiler option with CICS, SQL and
SQLIMS statements
Processing of PRTEXIT
The PRTEXIT exit module is used in place of the SYSPRINT data set.
Table 106. PRTEXIT processing
Action by compiler Action by exit module
Loads the exit module (mod3) during
initialization
Calls the exit module with an OPEN Prepares its output destination for
operation code (op code) processing. Passes the status of the OPEN
request to the compiler.
Calls the exit modules with a PUT op code Passes the status of the PUT request to the
when a line is to be printed, supplying the compiler by a return code. The first byte of
address and length of the record that is to be the record to be printed contains an ANSI
printed printer control character.
Calls the exit module with a CLOSE op code Releases any resources that are related to its
when the end-of-data is presented output destination
706 Enterprise COBOL for z/OS, V5.2 Programming Guide
PRTEXIT parameters
The compiler uses 10 parameters, passed by reference, to communicate with the
exit module. The return code, data length, and data buffer parameters are set by
the exit module for return to the compiler; the other items are passed from the
compiler to the exit module.
Table 107. PRTEXIT parameters
Parameter
number Parameter item Description of item
1 User-exit type Halfword that identifies which user exit is to perform
the operation.
3=PRTEXIT
2 Operation code Halfword that indicates the type of operation:
v 0=OPEN
v 1=CLOSE
v 3=PUT
3 Return code Fullword, set by the exit module, that indicates the
success of the requested operation:
v 0=Operation was successful
v 12=Operation failed
4 User-exit work area Six-fullword work area provided by the compiler for
use by the user-exit module.
Third word: for use by PRTEXIT
5 Data length Fullword that specifies the length of the record being
supplied by the PUT operation (the compiler sets this
value to 133)
6 Data buffer or str3 Data buffer where the compiler has placed the record
to be printed by the PUT operation.
str3 applies only to OPEN. The first halfword (on a
halfword boundary) contains the length of the string,
followed by the string.
7 Not used (Used only by LIBEXIT and MSGEXIT)
8 Not used (Used only by LIBEXIT)
9 Not used (Used only by LIBEXIT)
10 Not used (Used only by LIBEXIT)
RELATED TASKS
Using the user-exit work area on page 701
Calling from exit modules on page 702
Using the EXIT compiler option with CICS, SQL and
SQLIMS statements
Processing of ADEXIT
The ADEXIT module is called for each SYSADATA record immediately after the
record has been written out to the file.
To use an ADEXIT module, you must compile using the ADATA option to produce
SYSADATA output, and code the SYSADATA DD statement.
Appendix D. EXIT compiler option 707
Table 108. ADEXIT processing
Action by compiler Action by exit module
Loads the exit module (mod4) during
initialization
Calls the exit module with an OPEN Prepares its output destination for
operation code (op code) processing. Passes the status of the OPEN
request to the compiler.
Calls the exit module with a PUT op code Passes the status of the PUT request to the
when the compiler has written a SYSADATA compiler by a return code
record, supplying the address and length of
the SYSADATA record
Calls the exit module with a CLOSE op code Releases any resources
when the end-of-data is presented
ADEXIT parameters
The compiler uses 10 parameters, passed by reference, to communicate with the
exit module. The return code, data length, and data buffer parameters are set by
the exit module for return to the compiler; the other items are passed from the
compiler to the exit module.
Table 109. ADEXIT parameters
Parameter
number Parameter item Description of item
1 User-exit type Halfword that identifies which user exit is to perform
the operation.
4=ADEXIT
2 Operation code Halfword that indicates the type of operation:
v 0=OPEN
v 1=CLOSE
v 3=PUT
3 Return code Fullword, set by the exit module, that indicates the
success of the requested operation:
v 0=Operation was successful
v 12=Operation failed
4 User-exit work area Six-fullword work area provided by the compiler for
use by the user-exit module.
Fourth word: for use by ADEXIT
5 Data length Fullword that specifies the length of the record being
supplied by the PUT operation
6 Data buffer or str4 Fullword that contains the address of the data buffer
where the compiler has placed the record to be
printed by the PUT operation.
str4 applies only to OPEN. The first halfword (on a
halfword boundary) contains the length of the string,
followed by the string.
7 Not used (Used only by LIBEXIT and MSGEXIT)
8 Not used (Used only by LIBEXIT)
9 Not used (Used only by LIBEXIT)
708 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 109. ADEXIT parameters (continued)
Parameter
number Parameter item Description of item
10 Not used (Used only by LIBEXIT)
RELATED TASKS
Using the user-exit work area on page 701
Calling from exit modules on page 702
Using the EXIT compiler option with CICS, SQL and
SQLIMS statements
RELATED REFERENCES
ADATA on page 305
Processing of MSGEXIT
The MSGEXIT module is used to customize compiler diagnostic messages and FIPS
messages. The module can customize a message either by changing its severity or
suppressing it.
If the MSGEXIT module assigns a severity to a FIPS message, the message is
converted into a diagnostic message. (The message is shown in the summary of
diagnostic messages in the listing.)
A MSGEXIT summary at the end of the compiler listing shows how many
messages were changed in severity and how many messages were suppressed.
Table 110. MSGEXIT processing
Action by compiler Action by exit module
Loads the exit module (mod5)
during initialization
Calls the exit module with an Optionally processes str5 and passes the status of the
OPEN operation code (op code) OPEN request to the compiler
Calls the exit module with a One of the following actions:
MSGSEV operation code (op code) v Indicates no customization of the message (by
when the compiler is about to issue setting return code to 0)
a diagnostic message or FIPS
v Specifies a new severity for (or suppression of) the
message
message, and sets return code to 4
v Indicates that the operation failed (by setting
return code to 12)
Calls the exit module with a Optionally frees storage and passes the status of the
CLOSE op code CLOSE request to the compiler
Deletes the exit module (mod5)
during compiler termination
MSGEXIT parameters
The compiler uses 10 parameters, passed by reference, to communicate with the
exit module. The return code and user-requested severity parameters are set by the
exit module for return to the compiler; the other items are passed from the
compiler to the exit module.
Appendix D. EXIT compiler option 709
Table 111. MSGEXIT parameters
Parameter
number Parameter item Description of item
1 User-exit type Halfword that identifies which user exit is to perform
the operation.
6=MSGEXIT
2 Operation code Halfword that indicates the type of operation:
v 0=OPEN
v 1=CLOSE
v 5=MSGSEV: customize message severity
3 Return code Fullword, set by the exit module, that indicates the
success of the requested operation.
For op code MSGSEV:
v 0=Message not customized
v 4=Message found and customized
v 12=Operation failed
4 User-exit work area Six-fullword work area provided by the compiler for
use by the user-exit module.
Sixth word: for use by MSGEXIT
5 Not used (Used by the other exits)
6 Message exit data Three-halfword area (on a halfword boundary).
v First halfword: the message number of the message
to be customized
v Second halfword: for a diagnostic message, the
default severity; for a FIPS message, the FIPS
category as a numeric code
v Third halfword: the user-requested severity for the
message (-1 to indicate suppression)
7 str5 First halfword (on a halfword boundary): the length of
the string, followed by the string
8 Not used (Used only by LIBEXIT)
9 Not used (Used only by LIBEXIT)
10 Not used (Used only by LIBEXIT)
Example: MSGEXIT user exit on page 713
RELATED TASKS
Using the user-exit work area on page 701
Calling from exit modules on page 702
Customizing compiler-message severities
Using the EXIT compiler option with CICS, SQL and
SQLIMS statements
Customizing compiler-message severities
To change the severities of compiler messages or suppress compiler messages
(including FIPS messages), do the steps described below.
1. Code and compile a COBOL program named ERRMSG. The program needs only
a PROGRAM-ID paragraph, as described in the related task.
710 Enterprise COBOL for z/OS, V5.2 Programming Guide
2. Review the ERRMSG listing, which contains a complete list of compiler messages
with their message numbers, severities, and message text.
3. Decide which messages you want to customize.
To understand the customizations that are possible, see the related reference
about customizable compiler-message severities.
4. Code a MSGEXIT module to implement the customizations:
a. Verify that the operation-code parameter indicates message-severity
customization.
b. Check the two input values in the message-exit-data parameter: the message
number; and the default severity for a diagnostic message or the FIPS
category for a FIPS message.
The FIPS category is expressed as numeric code. For details, see the related
reference about customizable compiler-message severities.
c. For a message that you want to customize, set the user-requested severity in
the message-exit-data parameter to indicate either:
v A new message severity, by coding severity 0, 4, 8, or 12
v Message suppression, by coding severity -1
d. Set the return code to one of the following values:
v 0, to indicate that the message was not customized
v 4, to indicate that the message was found and customized
v 12, to indicate that the operation failed and that compilation should be
terminated
5. Compile and link your MSGEXIT module.
6. Add the data set that contains your MSGEXIT module to the compiler
concatenation by using a STEPLIB or JOBLIB DD statement.
7. Recompile program ERRMSG, but use compiler option EXIT(MSGEXIT(msgmod)),
where msgmod is the name of your MSGEXIT module.
8. Review the listing and check for:
v Updated message severities
v Suppressed messages (indicated by XX in place of the severity)
v Unsupported severity changes or unsupported message suppression
(indicated by a severity-U diagnostic message, and compiler termination with
return code 16)
RELATED TASKS
Generating a list of compiler messages on page 280
RELATED REFERENCES
Severity codes for compiler diagnostic messages on page 282
Customizable compiler-message severities
Effect of message customization on compilation return code on page 712
Error handling for exit modules on page 717
Customizable compiler-message severities
To customize compiler-message severities, you need to understand the possible
severities of compiler diagnostic messages, the levels or categories of FIPS
messages, and the permitted customizations of message severities.
The possible severity codes for compiler diagnostic messages are described in the
related reference about severity codes.
Appendix D. EXIT compiler option 711
The eight categories of FIPS (FLAGSTD) messages are shown in the following table.
The category of any given FIPS message is passed as a numeric code to the
MSGEXIT module. Those numeric codes are shown in the second column.
Table 112. FIPS (FLAGSTD) message categories
FIPS level or category Numeric code Description
D 81 Debug module level 1
E 82 Extension (IBM)
H 83 High level
I 84 Intermediate level
N 85 Segmentation module level 1
O 86 Obsolete elements
Q 87 High-level and obsolete elements
S 88 Segmentation module level 2
FIPS messages have an implied severity of zero (severity I).
Permitted message-severity customizations:
You can change the severity of a compiler message in the following ways:
v Severity-I and severity-W compiler diagnostic messages, and FIPS messages, can
be changed to have any severity from I through S.
Assigning a severity to a FIPS message converts the FIPS message to a
diagnostic message of the assigned severity.
As examples, you can:
Lower an optimizer warning to severity I.
Disallow REDEFINING a smaller item with a larger item by raising the severity
of message 1154.
Disallow complex OCCURS DEPENDING ON by changing FIPS message 8235 from
a category-E FIPS message to a severity-S compiler diagnostic message.
v Severity-E messages can be raised to severity S, but not lowered to severity I or
W, because an error condition has occurred in the program.
v Severity-S and severity-U messages cannot be changed to have a different
severity.
You can request suppression of compiler messages as follows:
v I, W, and FIPS messages can be suppressed.
v E and S messages cannot be suppressed.
RELATED REFERENCES
Severity codes for compiler diagnostic messages on page 282
FLAGSTD on page 328
Effect of message customization on compilation return code
Effect of message customization on compilation return code
If you use a MSGEXIT module, the final return code from the compilation of a
program could be affected as described below.
If you change the severity of a message, the return code from the compilation
might also be changed. For example, if a compilation produces one diagnostic
712 Enterprise COBOL for z/OS, V5.2 Programming Guide
message, and it is a severity-E message, the compilation return code would
normally be 8. But if the MSGEXIT module changes the severity of that message to
severity S, then the return code from compilation would be 12.
If you suppress a message, the return code from the compilation is no longer
affected by the severity of that message. For example, if a compilation produces
one diagnostic message, and it is a severity-W message, the compilation return
code would normally be 4. But if the MSGEXIT module suppresses that message,
then the return code from compilation would be 0.
RELATED TASKS
Customizing compiler-message severities on page 710
RELATED REFERENCES
Severity codes for compiler diagnostic messages on page 282
Example: MSGEXIT user exit
The following example shows a MSGEXIT user-exit module that changes message
severities and suppresses messages.
For helpful tips about using a message-exit module, see the comments within the
code.
*****************************************************************
* IGYMSGXT - Sample COBOL program for MSGEXIT *
*****************************************************************
* Function: This is a SAMPLE user exit for the MSGEXIT *
* suboption of the EXIT compiler option. This exit *
* can be used to customize the severity of or *
* suppress compiler diagnostic messages and FIPS *
* messages. This example program includes several *
* sample customizations to show how customizations *
* are done. If you do not want the sample *
* customizations then either delete the unwanted *
* lines of code or comment them out with a comment *
* indicator in column 7 (*). *
* *
*---------------------------------------------------------------*
* *
* USAGE NOTE: To use this user exit program, make the *
| * link-edited program object available to your *
* compiles that will use the MSGEXIT suboption of *
* the EXIT compiler option. Also, the name should *
* be changed, since IBM recommends that you avoid *
* having programs with names that start with IGY. *
* Sample steps to take: *
* 1) Make your customizations *
* 2) Change program name (E.G. MSGEXT) *
* 3) Compile and link into a data set *
* 4) Include that data set in your compile *
* JCL concatenation for the compile step. *
* If you link into USER.COBOLLIB: *
* *
* //COBOL.STEPLIB DD DSNAME=SYS1.SIGYCOMP,DISP=SHR *
* // DD DSNAME=USER.COBOLLIB,DISP=SHR *
* *
*****************************************************************
Id Division.
Program-Id. IGYMSGXT.
Data Division.
Working-Storage Section.
Appendix D. EXIT compiler option 713
*****************************************************************
* *
* Local variables. *
* *
*****************************************************************
77 EXIT-TYPEN PIC 9(4).
77 EXIT-DEFAULT-SEV-FIPS PIC X.
*****************************************************************
* *
* Definition of the User-Exit Parameter List, which is *
* passed from the COBOL compiler to the user-exit module. *
* *
*****************************************************************
Linkage Section.
01 EXIT-TYPE PIC 9(4) COMP.
01 EXIT-OPERATION PIC 9(4) COMP.
01 EXIT-RETURNCODE PIC 9(9) COMP.
01 EXIT-WORK-AREA.
02 EXIT-WORK-AREA-PTR OCCURS 6 POINTER.
01 EXIT-DUMMY POINTER.
01 EXIT-MESSAGE-PARMS.
02 EXIT-MESSAGE-NUM PIC 9(4) COMP.
02 EXIT-DEFAULT-SEV PIC 9(4) COMP.
02 EXIT-USER-SEV PIC S9(4) COMP.
01 EXIT-STRING.
02 EXIT-STR-LEN PIC 9(4) COMP.
02 EXIT-STR-TXT PIC X(64).
*****************************************************************
*****************************************************************
* *
* Begin PROCEDURE DIVISION *
* *
* Check parameters and perform the operation requested. *
* *
*****************************************************************
*****************************************************************
Procedure Division Using EXIT-TYPE EXIT-OPERATION
EXIT-RETURNCODE EXIT-WORK-AREA
EXIT-DUMMY EXIT-MESSAGE-PARMS
EXIT-STRING EXIT-DUMMY
EXIT-DUMMY EXIT-DUMMY.
Compute EXIT-RETURNCODE = 0
Evaluate TRUE
*****************************************************************
* Handle a bad invocation of this exit by the compiler. *
* This could happen if this routine was used for one of the *
* other EXITs, such as INEXIT, PRTEXIT or LIBEXIT. *
*****************************************************************
When EXIT-TYPE Not = 6
Move EXIT-TYPE to EXIT-TYPEN
Display **** Invalid exit routine identifier
Display **** EXIT TYPE = EXIT-TYPE
Compute EXIT-RETURNCODE = 16
*****************************************************************
* Handle the OPEN call to this exit by the compiler *
* Display the exit string (str5 in syntax diagram) from *
* the EXIT(MSGEXIT(str5,mod5)) option specification. *
*****************************************************************
714 Enterprise COBOL for z/OS, V5.2 Programming Guide
When EXIT-OPERATION = 0
* Display Opening MSGEXIT
* If EXIT-STR-LEN Not Zero Then
* Display str5 len = EXIT-STR-LEN
* Display str5 = EXIT-STR-TXT(1:EXIT-STR-LEN)
* End-If
Continue
*****************************************************************
* Handle the CLOSE call to this exit by the compiler *
*****************************************************************
When EXIT-OPERATION = 1
* Display Closing MSGEXIT
GOBACK
*****************************************************************
* Handle the customize message severity call to this exit *
* Display information about every customized severity. *
*****************************************************************
When EXIT-OPERATION = 5
* Display MSGEXIT called with MSGSEV
If EXIT-MESSAGE-NUM < 8000 Then
Perform Error-Messages-Severity
Else
Perform FIPS-Messages-Severity
End-If
* If EXIT-RETURNCODE = 4 Then
* Display >>>> Customizing message EXIT=MESSAGE-NUM
* with new severity EXIT-USER-SEV <<<<
* If EXIT-MESSAGE-NUM > 8000 Then
* Display FIPS sev = EXIT-DEFAULT-SEV-FIPS <<<<
* End-If
* End-If
*****************************************************************
* Handle a bad invocation of this exit by the compiler *
* The compiler should not invoke this exit with EXIT-TYPE = 6 *
* and an opcode other than 0, 1, or 5. This should not happen *
* and IBM service should be contacted if it does. *
*****************************************************************
When Other
Display **** Invalid MSGEXIT routine operation
Display **** EXIT OPCODE = EXIT-OPERATION
Compute EXIT-RETURNCODE = 16
End-Evaluate
Goback.
*****************************************************************
* ERROR MESSAGE PROCESSOR *
*****************************************************************
Error-Messages-Severity.
* Assume message severity will be customized...
Compute EXIT-RETURNCODE = 4
Evaluate EXIT-MESSAGE-NUM
*****************************************************************
* Change severity of message 1154(W) to 12 (S)
* This is the case of redefining a large item
* with a smaller item, IBM Req # MR0904063236
*****************************************************************
When(1154)
Compute EXIT-USER-SEV = 12
Appendix D. EXIT compiler option 715
*****************************************************************
* Change severity of messages 3188(W) and 3189(W)
* to 12 (S). This is to force a fix for all
* SEARCH ALL cases that might behave differently
* between COBOL compilers previous to Enterprise
* COBOL release V3R4 and later compilers such as
* Enterprise COBOL Version 4 Release 2.
* Another way to handle this migration is to analyze all of
* the warnings you get and then change them to I-level when
* the analysis is complete.
*****************************************************************
When(3188) When(3189)
Compute EXIT-USER-SEV = 12
*****************************************************************
* Message severity Not customized
*****************************************************************
When Other
Compute EXIT-RETURNCODE = 0
End-Evaluate
.
*****************************************************************
* FIPS MESSAGE PROCESSOR *
*****************************************************************
Fips-Messages-Severity.
* Assume message severity will be customized...
Compute EXIT-RETURNCODE = 4
* Convert numeric FIPS(FLAGSTD) category to character
* See the Programming Guide for decription of FIPS category
EVALUATE EXIT-DEFAULT-SEV
When 81
MOVE D To EXIT-DEFAULT-SEV-FIPS
When 82
MOVE E To EXIT-DEFAULT-SEV-FIPS
When 83
MOVE H To EXIT-DEFAULT-SEV-FIPS
When 84
MOVE I To EXIT-DEFAULT-SEV-FIPS
When 85
MOVE N To EXIT-DEFAULT-SEV-FIPS
When 86
MOVE O To EXIT-DEFAULT-SEV-FIPS
When 87
MOVE Q To EXIT-DEFAULT-SEV-FIPS
When 88
MOVE S To EXIT-DEFAULT-SEV-FIPS
When Other
Continue
End-Evaluate
*****************************************************************
* Example of using FIPS category to force coding
* restrictions. This is not a recommendation!
* Change severity of all OBSOLETE item FIPS
* messages to S
*****************************************************************
* If EXIT-DEFAULT-SEV-FIPS = O Then
* Display >>>> Default customizing FIPS category
* EXIT-DEFAULT-SEV-FIPS msg EXIT-MESSAGE-NUM <<<<
* Compute EXIT-USER-SEV = 12
* End-If
716 Enterprise COBOL for z/OS, V5.2 Programming Guide
Evaluate EXIT-MESSAGE-NUM
*****************************************************************
* Change severity of message 8062(O) to 8 (E)
* 8062 = GO TO without proc name
*****************************************************************
When(8062)
Compute EXIT-USER-SEV = 8
*****************************************************************
* Change severity of message 8193(E) to 0(I)
* 8193 = GOBACK
*****************************************************************
When(8193)
Compute EXIT-USER-SEV = 0
*****************************************************************
* Change severity of message 8235(E) to 8 (Error)
* to disallow Complex Occurs Depending On
* 8235 = Complex Occurs Depending On
*****************************************************************
When(8235)
Compute EXIT-USER-SEV = 08
*****************************************************************
* Change severity of message 8270(O) to -1 (Suppress)
* 8270 = SERVICE LABEL
*****************************************************************
When(8270)
Compute EXIT-USER-SEV = -1
*****************************************************************
* Message severity Not customized
*****************************************************************
When Other
* For the default set O to S case...
* If EXIT-USER-SEV = 12 Then
* Compute EXIT-RETURNCODE = 4
* Else
Compute EXIT-RETURNCODE = 0
* End-If
End-Evaluate
.
END PROGRAM IGYMSGXT.
Error handling for exit modules
The conditions described below can occur during processing of the user exits.
Exit load failure:
Message IGYSI5207-U is written to the operator if a LOAD request for any of the
user exits fails:
An error occurred while attempting to load user exit exit-name.
Exit open failure:
Message IGYSI5208-U is written to the operator if an OPEN request for any of the
user exits fails:
An error occurred while attempting to open user exit exit-name.
PRTEXIT PUT failure:
v Message IGYSI5203-U is written to the listing:
Appendix D. EXIT compiler option 717
A PUT request to the PRTEXIT user exit failed with return code nn.
v Message IGYSI5217-U is written to the operator:
An error occurred in PRTEXIT user exit exit-name. Compiler terminated.
SYSIN GET failures:
The following messages might be written to the listing:
v IGYSI5204-U:
The record address was not set by the exit-name user exit.
v IGYSI5205-U:
A GET request from the INEXIT user exit failed with return code nn.
v IGYSI5206-U:
The record length was not set by the exit-name user exit.
ADEXIT PUT failure:
v Message IGYSI5225-U is written to the operator:
An error occurred in ADEXIT user exit exit-name. Compiler terminated.
v Message IGYSI5226-U is written to the listing:
A PUT request to the ADEXIT user exit failed with return code nn.
MSGEXIT failures:
Customization failure: Message IGYPP5293-U is written to the listing if an
unsupported severity change or unsupported message suppression is attempted:
MSGEXIT user exit exit-name specified a message severity customization that is
not supported. The message number, default severity, and user-specified severity
were: mm, ds, us. Change MSGEXIT user exit exit-name to correct this error.
General failure: Message IGYPP5064-U is written to the listing if the MSGEXIT
module sets the return code to a nonzero value other than 4:
A call to the MSGEXIT user exit routine exit-name failed with return code nn.
In the MSGEXIT messages, the two characters PP indicate the phase of the
compiler that issued the message that resulted in a call to the MSGEXIT module.
RELATED TASKS
Customizing compiler-message severities on page 710
Using the EXIT compiler option with CICS, SQL and SQLIMS
statements
When you compile using suboptions of the EXIT compiler option, and your
program contains EXEC CICS, EXEC SQL, or EXEC SQLIMS statements, the actions that
you can take in the exit modules depend on whether you use the separate CICS
translator and DB2 precompiler, or the integrated CICS translator and DB2
coprocessor.
If the program contains EXEC SQLIMS statements, the actions that you can take in
the exit modules are the actions that are listed for the integrated translator.
The following table shows which actions you can take in the exit modules
depending on whether you use the integrated or separate translators.
718 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 113. Actions possible in exit modules for CICS, SQL and SQLIMS statements
Translated with
Compile integrated or separate
with CICS and DB2
suboption translators? Possible actions Comments
INEXIT Integrated Can process EXEC CICS, EXEC SQL, and The INEXIT module does not get
EXEC SQLIMS statements in the INEXIT control of the COBOL statements that
module are generated for the EXEC statements.
Separate Can process the COBOL statements You can change the generated
that are generated for the EXEC statements in the INEXIT module, but
statements in the INEXIT module doing so is not supported by IBM.
LIBEXIT Integrated Can process in the LIBEXIT module EXEC SQL INCLUDE and EXEC SQLIMS
the statements that are brought in by INCLUDE statements are processed like
the EXEC SQL INCLUDE and EXEC COBOL COPY statements.
SQLIMS INCLUDE statements. Can
process EXEC CICS source statements
in the LIBEXIT module.
Separate Can process the COBOL statements You can process the input statements
that are generated for the EXEC CICS that are brought in by the EXEC SQL
statements in the LIBEXIT module INCLUDE and SQLIMS INCLUDE
statements only by using the INEXIT
suboption.
PRTEXIT Integrated Can process the EXEC CICS , EXEC SQL, The PRTEXIT module does not have
and EXEC SQLIMS source statements access to the COBOL statements that
from the SOURCE listing in the are generated.
PRTEXIT module
Separate Can process the COBOL SOURCE
listing statements that are generated
for the EXEC statements in the
PRTEXIT module
ADEXIT Integrated Can process the EXEC CICS, EXEC SQL, The ADEXIT module does not have
and EXEC SQLIMS source statements in access to the COBOL statements that
the ADEXIT module are generated.
Separate Can process the COBOL SYSADATA
statements that are generated for the
EXEC statements in the ADEXIT
module
MSGEXIT Integrated Can process CICS and DB2 messages
in the MSGEXIT module
Separate Cannot process CICS and DB2 Messages from CICS are shown in the
messages in the MSGEXIT module separate CICS translator listing;
messages from DB2 are shown in the
DB2 precompiler listing.
RELATED CONCEPTS
Integrated CICS translator on page 425
DB2 coprocessor on page 431
RELATED TASKS
Compiling with the CICS option on page 423
Compiling with the SQL option on page 435
RELATED REFERENCES
Processing of INEXIT on page 702
Appendix D. EXIT compiler option 719
Processing of LIBEXIT on page 703
Processing of PRTEXIT on page 706
Processing of ADEXIT on page 707
Processing of MSGEXIT on page 709
720 Enterprise COBOL for z/OS, V5.2 Programming Guide
Appendix E. JNI.cpy copybook
This listing shows the JNI.cpy copybook, which you can use to access the Java
Native Interface (JNI) services from your COBOL programs.
JNI.cpy contains sample COBOL data definitions that correspond to the Java JNI
types, and contains JNINativeInterface, the JNI environment structure that contains
function pointers for accessing the JNI callable services.
JNI.cpy is in the z/OS UNIX file system in the include subdirectory of the COBOL
install directory (typically /usr/lpp/cobol/include). JNI.cpy is analogous to the
header file jni.h that C programmers use to access the JNI.
*****************************************************************
* COBOL declarations for Java native method interoperation *
* *
* To use the Java Native Interface callable services from a *
* COBOL program: *
* 1) Use a COPY statement to include this file into the *
* the Linkage Section of the program, e.g. *
* Linkage Section. *
* Copy JNI *
* 2) Code the following statements at the beginning of the *
* Procedure Division: *
* Set address of JNIEnv to JNIEnvPtr *
* Set address of JNINativeInterface to JNIEnv *
*****************************************************************
*
* Sample JNI type definitions in COBOL
*
*01 jboolean1 pic X.
* 88 jboolean1-true value X01 through XFF.
* 88 jboolean1-false value X00.
*
*01 jbyte1 pic X.
*
*01 jchar1 pic N usage national.
*
*01 jshort1 pic s9(4) comp-5.
*01 jint1 pic s9(9) comp-5.
*01 jlong1 pic s9(18) comp-5.
*
*01 jfloat1 comp-1.
*01 jdouble1 comp-2.
*
*01 jobject1 object reference.
*01 jclass1 object reference.
*01 jstring1 object reference jstring.
*01 jarray1 object reference jarray.
*
*01 jbooleanArray1 object reference jbooleanArray.
*01 jbyteArray1 object reference jbyteArray.
*01 jcharArray1 object reference jcharArray.
*01 jshortArray1 object reference jshortArray.
*01 jintArray1 object reference jintArray.
*01 jlongArray1 object reference jlongArray.
*01 floatArray1 object reference floatArray.
*01 jdoubleArray1 object reference jdoubleArray.
*01 jobjectArray1 object reference jobjectArray.
* Possible return values for JNI functions.
Copyright IBM Corp. 1991, 2015 721
01 JNI-RC pic S9(9) comp-5.
* success
88 JNI-OK value 0.
* unknown error
88 JNI-ERR value -1.
* thread detached from the VM
88 JNI-EDETACHED value -2.
* JNI version error
88 JNI-EVERSION value -3.
* not enough memory
88 JNI-ENOMEM value -4.
* VM already created
88 JNI-EEXIST value -5.
* invalid arguments
88 JNI-EINVAL value -6.
* Used in ReleaseScalarArrayElements
01 releaseMode pic s9(9) comp-5.
88 JNI-COMMIT value 1.
88 JNI-ABORT value 2.
01 JNIenv pointer.
* JNI Native Method Interface - environment structure.
01 JNINativeInterface.
02 pointer.
02 pointer.
02 pointer.
02 pointer.
02 GetVersion function-pointer.
02 DefineClass function-pointer.
02 FindClass function-pointer.
02 FromReflectedMethod function-pointer.
02 FromReflectedField function-pointer.
02 ToReflectedMethod function-pointer.
02 GetSuperclass function-pointer.
02 IsAssignableFrom function-pointer.
02 ToReflectedField function-pointer.
02 Throw function-pointer.
02 ThrowNew function-pointer.
02 ExceptionOccurred function-pointer.
02 ExceptionDescribe function-pointer.
02 ExceptionClear function-pointer.
02 FatalError function-pointer.
02 PushLocalFrame function-pointer.
02 PopLocalFrame function-pointer.
02 NewGlobalRef function-pointer.
02 DeleteGlobalRef function-pointer.
02 DeleteLocalRef function-pointer.
02 IsSameObject function-pointer.
02 NewLocalRef function-pointer.
02 EnsureLocalCapacity function-pointer.
02 AllocObject function-pointer.
02 NewObject function-pointer.
02 NewObjectV function-pointer.
02 NewObjectA function-pointer.
02 GetObjectClass function-pointer.
02 IsInstanceOf function-pointer.
02 GetMethodID function-pointer.
02 CallObjectMethod function-pointer.
02 CallObjectMethodV function-pointer.
02 CallObjectMethodA function-pointer.
02 CallBooleanMethod function-pointer.
02 CallBooleanMethodV function-pointer.
02 CallBooleanMethodA function-pointer.
02 CallByteMethod function-pointer.
02 CallByteMethodV function-pointer.
722 Enterprise COBOL for z/OS, V5.2 Programming Guide
02 CallByteMethodA function-pointer.
02 CallCharMethod function-pointer.
02 CallCharMethodV function-pointer.
02 CallCharMethodA function-pointer.
02 CallShortMethod function-pointer.
02 CallShortMethodV function-pointer.
02 CallShortMethodA function-pointer.
02 CallIntMethod function-pointer.
02 CallIntMethodV function-pointer.
02 CallIntMethodA function-pointer.
02 CallLongMethod function-pointer.
02 CallLongMethodV function-pointer.
02 CallLongMethodA function-pointer.
02 CallFloatMethod function-pointer.
02 CallFloatMethodV function-pointer.
02 CallFloatMethodA function-pointer.
02 CallDoubleMethod function-pointer.
02 CallDoubleMethodV function-pointer.
02 CallDoubleMethodA function-pointer.
02 CallVoidMethod function-pointer.
02 CallVoidMethodV function-pointer.
02 CallVoidMethodA function-pointer.
02 CallNonvirtualObjectMethod function-pointer.
02 CallNonvirtualObjectMethodV function-pointer.
02 CallNonvirtualObjectMethodA function-pointer.
02 CallNonvirtualBooleanMethod function-pointer.
02 CallNonvirtualBooleanMethodV function-pointer.
02 CallNonvirtualBooleanMethodA function-pointer.
02 CallNonvirtualByteMethod function-pointer.
02 CallNonvirtualByteMethodV function-pointer.
02 CallNonvirtualByteMethodA function-pointer.
02 CallNonvirtualCharMethod function-pointer.
02 CallNonvirtualCharMethodV function-pointer.
02 CallNonvirtualCharMethodA function-pointer.
02 CallNonvirtualShortMethod function-pointer.
02 CallNonvirtualShortMethodV function-pointer.
02 CallNonvirtualShortMethodA function-pointer.
02 CallNonvirtualIntMethod function-pointer.
02 CallNonvirtualIntMethodV function-pointer.
02 CallNonvirtualIntMethodA function-pointer.
02 CallNonvirtualLongMethod function-pointer.
02 CallNonvirtualLongMethodV function-pointer.
02 CallNonvirtualLongMethodA function-pointer.
02 CallNonvirtualFloatMethod function-pointer.
02 CallNonvirtualFloatMethodV function-pointer.
02 CallNonvirtualFloatMethodA function-pointer.
02 CallNonvirtualDoubleMethod function-pointer.
02 CallNonvirtualDoubleMethodV function-pointer.
02 CallNonvirtualDoubleMethodA function-pointer.
02 CallNonvirtualVoidMethod function-pointer.
02 CallNonvirtualVoidMethodV function-pointer.
02 CallNonvirtualVoidMethodA function-pointer.
02 GetFieldID function-pointer.
02 GetObjectField function-pointer.
02 GetBooleanField function-pointer.
02 GetByteField function-pointer.
02 GetCharField function-pointer.
02 GetShortField function-pointer.
02 GetIntField function-pointer.
02 GetLongField function-pointer.
02 GetFloatField function-pointer.
02 GetDoubleField function-pointer.
02 SetObjectField function-pointer.
02 SetBooleanField function-pointer.
02 SetByteField function-pointer.
02 SetCharField function-pointer.
02 SetShortField function-pointer.
Appendix E. JNI.cpy copybook 723
02 SetIntField function-pointer.
02 SetLongField function-pointer.
02 SetFloatField function-pointer.
02 SetDoubleField function-pointer.
02 GetStaticMethodID function-pointer.
02 CallStaticObjectMethod function-pointer.
02 CallStaticObjectMethodV function-pointer.
02 CallStaticObjectMethodA function-pointer.
02 CallStaticBooleanMethod function-pointer.
02 CallStaticBooleanMethodV function-pointer.
02 CallStaticBooleanMethodA function-pointer.
02 CallStaticByteMethod function-pointer.
02 CallStaticByteMethodV function-pointer.
02 CallStaticByteMethodA function-pointer.
02 CallStaticCharMethod function-pointer.
02 CallStaticCharMethodV function-pointer.
02 CallStaticCharMethodA function-pointer.
02 CallStaticShortMethod function-pointer.
02 CallStaticShortMethodV function-pointer.
02 CallStaticShortMethodA function-pointer.
02 CallStaticIntMethod function-pointer.
02 CallStaticIntMethodV function-pointer.
02 CallStaticIntMethodA function-pointer.
02 CallStaticLongMethod function-pointer.
02 CallStaticLongMethodV function-pointer.
02 CallStaticLongMethodA function-pointer.
02 CallStaticFloatMethod function-pointer.
02 CallStaticFloatMethodV function-pointer.
02 CallStaticFloatMethodA function-pointer.
02 CallStaticDoubleMethod function-pointer.
02 CallStaticDoubleMethodV function-pointer.
02 CallStaticDoubleMethodA function-pointer.
02 CallStaticVoidMethod function-pointer.
02 CallStaticVoidMethodV function-pointer.
02 CallStaticVoidMethodA function-pointer.
02 GetStaticFieldID function-pointer.
02 GetStaticObjectField function-pointer.
02 GetStaticBooleanField function-pointer.
02 GetStaticByteField function-pointer.
02 GetStaticCharField function-pointer.
02 GetStaticShortField function-pointer.
02 GetStaticIntField function-pointer.
02 GetStaticLongField function-pointer.
02 GetStaticFloatField function-pointer.
02 GetStaticDoubleField function-pointer.
02 SetStaticObjectField function-pointer.
02 SetStaticBooleanField function-pointer.
02 SetStaticByteField function-pointer.
02 SetStaticCharField function-pointer.
02 SetStaticShortField function-pointer.
02 SetStaticIntField function-pointer.
02 SetStaticLongField function-pointer.
02 SetStaticFloatField function-pointer.
02 SetStaticDoubleField function-pointer.
02 NewString function-pointer.
02 GetStringLength function-pointer.
02 GetStringChars function-pointer.
02 ReleaseStringChars function-pointer.
02 NewStringUTF function-pointer.
02 GetStringUTFLength function-pointer.
02 GetStringUTFChars function-pointer.
02 ReleaseStringUTFChars function-pointer.
02 GetArrayLength function-pointer.
02 NewObjectArray function-pointer.
02 GetObjectArrayElement function-pointer.
02 SetObjectArrayElement function-pointer.
02 NewBooleanArray function-pointer.
724 Enterprise COBOL for z/OS, V5.2 Programming Guide
02 NewByteArray function-pointer.
02 NewCharArray function-pointer.
02 NewShortArray function-pointer.
02 NewIntArray function-pointer.
02 NewLongArray function-pointer.
02 NewFloatArray function-pointer.
02 NewDoubleArray function-pointer.
02 GetBooleanArrayElements function-pointer.
02 GetByteArrayElements function-pointer.
02 GetCharArrayElements function-pointer.
02 GetShortArrayElements function-pointer.
02 GetIntArrayElements function-pointer.
02 GetLongArrayElements function-pointer.
02 GetFloatArrayElements function-pointer.
02 GetDoubleArrayElements function-pointer.
02 ReleaseBooleanArrayElements function-pointer.
02 ReleaseByteArrayElements function-pointer.
02 ReleaseCharArrayElements function-pointer.
02 ReleaseShortArrayElements function-pointer.
02 ReleaseIntArrayElements function-pointer.
02 ReleaseLongArrayElements function-pointer.
02 ReleaseFloatArrayElements function-pointer.
02 ReleaseDoubleArrayElements function-pointer.
02 GetBooleanArrayRegion function-pointer.
02 GetByteArrayRegion function-pointer.
02 GetCharArrayRegion function-pointer.
02 GetShortArrayRegion function-pointer.
02 GetIntArrayRegion function-pointer.
02 GetLongArrayRegion function-pointer.
02 GetFloatArrayRegion function-pointer.
02 GetDoubleArrayRegion function-pointer.
02 SetBooleanArrayRegion function-pointer.
02 SetByteArrayRegion function-pointer.
02 SetCharArrayRegion function-pointer.
02 SetShortArrayRegion function-pointer.
02 SetIntArrayRegion function-pointer.
02 SetLongArrayRegion function-pointer.
02 SetFloatArrayRegion function-pointer.
02 SetDoubleArrayRegion function-pointer.
02 RegisterNatives function-pointer.
02 UnregisterNatives function-pointer.
02 MonitorEnter function-pointer.
02 MonitorExit function-pointer.
02 GetJavaVM function-pointer.
02 GetStringRegion function-pointer.
02 GetStringUTFRegion function-pointer.
02 GetPrimitiveArrayCritical function-pointer.
02 ReleasePrimitiveArrayCritical function-pointer.
02 GetStringCritical function-pointer.
02 ReleaseStringCritical function-pointer.
02 NewWeakGlobalRef function-pointer.
02 DeleteWeakGlobalRef function-pointer.
02 ExceptionCheck function-pointer.
RELATED TASKS
Compiling OO applications under z/OS UNIX on page 291
Accessing JNI services on page 623
Appendix E. JNI.cpy copybook 725
726 Enterprise COBOL for z/OS, V5.2 Programming Guide
Appendix F. COBOL SYSADATA file contents
When you use the ADATA compiler option, the compiler produces a file, the
SYSADATA file, that contains additional program data. You can use this file
instead of the compiler listing to extract information about the program. For
example, you can extract information about the program for symbolic debugging
tools or cross-reference tools.
Example: SYSADATA on page 729
RELATED REFERENCES
ADATA on page 305
Compiler options that affect the SYSADATA file
SYSADATA record types on page 728
SYSADATA record descriptions on page 730
Compiler options that affect the SYSADATA file
Several compiler options could affect the contents of the SYSADATA file.
COMPILE
NOCOMPILE(W|E|S) might stop compilation prematurely, resulting in the loss
of specific messages.
EXIT INEXIT prohibits identification of the compilation source file.
LANGUAGE
LANGUAGE controls the message text (Uppercase English, Mixed-Case
English, or Japanese). Selection of Japanese could result in DBCS characters
written to Error Identification records.
NUM NUM causes the compiler to use the contents of columns 1-6 in the source
records for line numbering, rather than using generated sequence numbers.
Any invalid (nonnumeric) or out-of-sequence numbers are replaced with a
number one higher than that of the previous record.
TEST TEST causes additional object text records to be created that also affect the
contents of the SYSADATA file.
The SYSADATA fields shown in the following table contain line numbers whose
contents differ depending on the NUM|NONUM setting.
Type Field Record
0020 AE_LINE External Symbol record
0030 ATOK_LINE Token record
0032 AF_STMT Source Error record
0038 AS_STMT Source record
0039 AS_REP_EXP_SLIN COPY REPLACING record
0039 AS_REP_EXP_ELIN COPY REPLACING record
0042 ASY_STMT Symbol record
0044 AX_DEFN Symbol Cross Reference record
0044 AX_STMT Symbol Cross Reference record
Copyright IBM Corp. 1991, 2015 727
Type Field Record
0046 AN_STMT Nested Program record
The Type 0038 Source record contains two fields that relate to line numbers and
record numbers:
v AS_STMT contains the compiler line number in both the NUM and NONUM cases.
v AS_CUR_REC# contains the physical source record number.
These two fields can always be used to correlate the compiler line numbers, used
in all the above fields, with physical source record numbers.
The remaining compiler options have no direct effect on the SYSADATA file, but
might trigger generation of additional error messages associated with the specific
option, such as FLAGSTD or SSRANGE.
Example: SYSADATA on page 729
RELATED REFERENCES
SYSADATA record types
COMPILE on page 316
EXIT on page 324
LANGUAGE on page 331
NUMBER on page 339
TEST on page 359
SYSADATA record types
The SYSADATA file contains records classified into different record types. Each
type of record provides information about the COBOL program being compiled.
Each record consists of two parts:
v A 12-byte header section, which has the same structure for all record types, and
contains the record code that identifies the type of record
v A variable-length data section, which varies by record type
Table 114. SYSADATA record types
Record type What it does
Job identification record: X'0000' on page Provides information about the environment
733 used to process the source data
ADATA identification record: X'0001' on Provides common information about the
page 734 records in the SYSADATA file
Compilation unit start | end record: Marks the beginning and ending of
X'0002' on page 734 compilation units in a source file
Options record: X'0010' on page 735 Describes the compiler options used for the
compilation
External symbol record: X'0020' on page Describes all external names in the program,
744 definitions, and references
Parse tree record: X'0024' on page 745 Defines a node in the parse tree of the
program
Token record: X'0030' on page 760 Defines a source token
Source error record: X'0032' on page 774 Describes errors in source program statements
728 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 114. SYSADATA record types (continued)
Record type What it does
Source record: X'0038' on page 774 Describes a single source line
COPY REPLACING record: X'0039' on Describes an instance of text replacement as a
page 775 result of a match of COPY. . .REPLACING
operand-1 with text in the copybook
Symbol record: X'0042' on page 776 Describes a single symbol defined in the
program. There is one symbol record for each
symbol defined in the program.
Symbol cross-reference record: X'0044' on Describes references to a single symbol
page 787
Nested program record: X'0046' on page Describes the name and nesting level of a
788 program
Library record: X'0060' on page 789 Describes the library files and members used
from each library
Statistics record: X'0090' on page 789 Describes the statistics about the compilation
EVENTS record: X'0120' on page 790 EVENTS records provide compatibility with
COBOL/370. The record format is identical
with that in COBOL/370, with the addition of
the standard ADATA header at the beginning
of the record and a field indicating the length
of the EVENTS record data.
Example: SYSADATA
The following sample shows part of the listing of a COBOL program. If this
COBOL program were compiled with the ADATA option, the records produced in
the associated data file would be in the sequence shown in the table below.
000001 IDENTIFICATION DIVISION. AD000020
000002 PROGRAM-ID. AD04202. AD000030
000003 ENVIRONMENT DIVISION. AD000040
000004 DATA DIVISION. AD000050
000005 WORKING-STORAGE SECTION. AD000060
000006 77 COMP3-FLD2 pic S9(3)v9. AD000070
000007 PROCEDURE DIVISION. AD000080
000008 STOP RUN.
Type Description
X'0120' EVENTS Timestamp record
X'0120' EVENTS Processor record
X'0120' EVENTS File-ID record
X'0120' EVENTS Program record
X'0001' ADATA Identification record
X'0000' Job Identification record
X'0010' Options record
X'0038' Source record for statement 1
X'0038' Source record for statement 2
X'0038' Source record for statement 3
X'0038' Source record for statement 4
X'0038' Source record for statement 5
Appendix F. COBOL SYSADATA file contents 729
Type Description
X'0038' Source record for statement 6
X'0038' Source record for statement 7
X'0038' Source record for statement 8
X'0020' External Symbol record for AD04202
X'0044' Symbol Cross Reference record for STOP
X'0044' Symbol Cross Reference record for COMP3-FLD2
X'0044' Symbol Cross Reference record for AD04202
X'0042' Symbol record for AD04202
X'0042' Symbol record for COMP3-FLD2
X'0090' Statistics record
X'0120' EVENTS FileEnd record
RELATED REFERENCES
SYSADATA record descriptions
SYSADATA record descriptions
The formats of the records written to the associated data file are shown in the
related references below.
In the fields described in each of the record types, these symbols occur:
C Indicates character (EBCDIC or ASCII) data
H Indicates 2-byte binary integer data
F Indicates 4-byte binary integer data
A Indicates 4-byte binary integer address and offset data
X Indicates hexadecimal (bit) data or 1-byte binary integer data
No boundary alignments are implied by any data type, and the implied lengths
above might be changed by the presence of a length indicator (Ln). All integer data
is in big-endian or little-endian format depending on the indicator bit in the header
flag byte. Big-endian format means that bit 0 is always the most significant bit and
bit n is the least significant bit. Little-endian refers to byte-reversed integers as
seen on Intel processors.
All undefined fields and unused values are reserved.
RELATED REFERENCES
Common header section on page 731
Job identification record: X'0000' on page 733
ADATA identification record: X'0001' on page 734
Compilation unit start | end record: X'0002' on page 734
Options record: X'0010' on page 735
External symbol record: X'0020' on page 744
Parse tree record: X'0024' on page 745
Token record: X'0030' on page 760
Source error record: X'0032' on page 774
Source record: X'0038' on page 774
COPY REPLACING record: X'0039' on page 775
730 Enterprise COBOL for z/OS, V5.2 Programming Guide
Symbol record: X'0042' on page 776
Symbol cross-reference record: X'0044' on page 787
Nested program record: X'0046' on page 788
Library record: X'0060' on page 789
Statistics record: X'0090' on page 789
EVENTS record: X'0120' on page 790
Common header section
The table below shows the format of the header section that is common for all
record types. For MVS and VSE, each record is preceded by a 4-byte RDW
(record-descriptor word) that is normally used only by access methods and
stripped off by download utilities.
Table 115. SYSADATA common header section
Field Size Description
Language code XL1
16 High Level Assembler
17 COBOL on all platforms
40 PL/I on supported platforms
Appendix F. COBOL SYSADATA file contents 731
Table 115. SYSADATA common header section (continued)
Field Size Description
Record type HL2 The record type, which can be any of the following ones:
X'0000'
Job Identification record1
X'0001'
ADATA Identification record
X'0002'
Compilation unit start/end record
X'0010'
Options record1
X'0020'
External Symbol record
X'0024'
Parse Tree record
X'0030'
Token record
X'0032'
Source Error record
X'0038'
Source record
X'0039'
COPY REPLACING record
X'0042'
Symbol record
X'0044'
Symbol Cross-Reference record
X'0046'
Nested Program record
X'0060'
Library record
X'0090'
Statistics record1
X'0120'
EVENTS record
Associated data XL1
3 Definition level for the header structure
architecture level
Flag XL1
.... ..1.
ADATA record integers are in little-endian
(Intel) format
.... ...1
This record is continued in the next record
1111 11..
Reserved for future use
Associated data XL1 Used to indicate a new format for a specific record type,
record edition level usually 0
Reserved CL4 Reserved for future use
732 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 115. SYSADATA common header section (continued)
Field Size Description
Associated data field HL2 The length in bytes of the data following the header
length
1. When a batch compilation (sequence of programs) is run with the ADATA option, there
will be multiple Job Identification, Options, and Statistics records for each compilation.
The mapping of the 12-byte header does not include the area used for the
variable-length record-descriptor word required by the access method on MVS and
VSE.
Job identification record: X'0000'
The following table shows the contents of the job identification record.
Table 116. SYSADATA job identification record
Field Size Description
Date CL8 The date of the compilation in the format YYYYMMDD
Time CL4 The time of the compilation in the format HHMM
Product number CL8 The product number of the compiler that produced the
associated data file
Product version CL8 The version number of the product that produced the
associated data file, in the form V.R.M
PTF level CL8 The PTF level number of the product that produced the
associated data file. (This field is blank if the PTF
number is not available.)
System ID CL24 The system identification of the system on which the
compilation was run
Job name CL8 The MVS job name of the compilation job
Step name CL8 The MVS step name of the compilation step
Proc step CL8 The MVS procedure step name of the compilation
procedure
Number of input HL2 The number of input files recorded in this record.
files1
The following group of seven fields will occur n times
depending on the value in this field.
...Input file number HL2 The assigned sequence number of the file
...Input file name HL2 The length of the following input file name
length
...Volume serial HL2 The length of the volume serial number
number length
...Member name HL2 The length of the member name
length
...Input file name CL(n) The name of the input file for the compilation
...Volume serial CL(n) The volume serial number of the (first) volume on which
number the input file resides
...Member name CL(n) Where applicable, the name of the member in the input
file
Appendix F. COBOL SYSADATA file contents 733
Table 116. SYSADATA job identification record (continued)
Field Size Description
1. Where the number of input files would exceed the record size for the associated data
file, the record is continued on the next record. The current number of input files (for
that record) is stored in the record, and the record is written to the associated data file.
The next record contains the rest of the input files. The count of the number of input
files is a count for the current record.
ADATA identification record: X'0001'
The following table shows the contents of the ADATA identification record.
Table 117. ADATA identification record
Field Size Description
Time (binary) XL8 Universal Time (UT) as a binary number of microseconds
since midnight Greenwich Mean Time, with the
low-order bit representing 1 microsecond. This time can
be used as a time-zone-independent time stamp.
On Windows and AIX systems, only bytes 5-8 of the field
are used as a fullword binary field that contains the time.
CCSID1 XL2 Coded Character Set Identifier
Character-set flags XL1
X'80' EBCDIC (IBM-037)
X'40' ASCII (IBM-1252)
Code-page name XL2 Length of the code-page name that follows
length
Code-page name CL(n) Name of the code page
1. The appropriate CCS flag will always be set. If the CCSID is set to nonzero, the
code-page name length will be zero. If the CCSID is set to zero, the code-page name
length will be nonzero and the code-page name will be present.
Compilation unit start | end record: X'0002'
The following table shows the contents of the compilation unit start|end record.
Table 118. SYSADATA compilation unit start | end record
Field Size Description
Type HL2 Compilation unit type, which is one of the following
options:
X'0000' Start compilation unit
X'0001' End compilation unit
Reserved CL2 Reserved for future use
Reserved FL4 Reserved for future use
734 Enterprise COBOL for z/OS, V5.2 Programming Guide
Options record: X'0010'
The following table shows the contents of the options record.
Table 119. SYSADATA options record
Field Size Description
Option byte 0 XL1
1111 1111
Reserved for future use
Option byte 1 XL1
1... ....
Bit 1 = DECK, Bit 0 = NODECK
.1.. ....
Bit 1 = ADATA, Bit 0 = NOADATA
..1. ....
Bit 1 = COLLSEQ(EBCDIC), Bit 0 =
COLLSEQ(LOCALE|BINARY) (Windows and AIX
only)
...1 ....
Bit 1 = SEPOBJ, Bit 0 = NOSEPOBJ (Windows and
AIX only)
.... 1...
Bit 1 = NAME, Bit 0 = NONAME
.... .1..
Bit 1 = OBJECT, Bit 0 = NOOBJECT
.... ..1.
Bit 1 = SQL, Bit 0 = NOSQL
.... ...1
Bit 1 = CICS, Bit 0 = NOCICS
Option byte 2 XL1
1... ....
Bit 1 = OFFSET, Bit 0 = NOOFFSET
.1.. ....
Bit 1 = MAP, Bit 0 = NOMAP
..1. ....
Bit 1 = LIST, Bit 0 = NOLIST
...1 ....
Bit 1 = DBCSXREF, Bit 0 = NODBCSXREF
.... 1...
Bit 1 = XREF(SHORT), Bit 0 = not XREF(SHORT).
This flag should be used in combination with
the flag at bit 7. XREF(FULL) is indicated by this
flag being off and the flag at bit 7 being on.
.... .1..
Bit 1 = SOURCE, Bit 0 = NOSOURCE
.... ..1.
Bit 1 = VBREF, Bit 0 = NOVBREF
.... ...1
Bit 1 = XREF, Bit 0 = not XREF. See also flag at bit
4 above.
Appendix F. COBOL SYSADATA file contents 735
Table 119. SYSADATA options record (continued)
Field Size Description
Option byte 3 XL1
1... ....
Bit 1 = FLAG imbedded diagnostics level
specified (a value y is specified as in FLAG(x,y))
.1.. ....
Bit 1 = FLAGSTD, Bit 0 = NOFLAGSTD
..1. ....
Bit 1 = NUM, Bit 0 = NONUM
...1 ....
Bit 1 = SEQUENCE, Bit 0 = NOSEQUENCE
.... 1...
Bit 1 = SOSI, Bit 0 = NOSOSI (Windows and AIX
only)
.... .1..
Bit 1 = NSYMBOL(NATIONAL), Bit 0 =
NSYMBOL(DBCS)
.... ..1.
Bit 1 = PROFILE, Bit 0 = NOPROFILE (AIX only)
.... ...1
Bit 1 = WORD, Bit 0 = NOWORD
Option byte 4 XL1
1... ....
Bit 1 = ADV, Bit 0 = NOADV
.1.. ....
Bit 1 = APOST, Bit 0 = QUOTE
..1. ....
Bit 1 = DYNAM, Bit 0 = NODYNAM
...1 ....
Bit 1 = AWO, Bit 0 = NOAWO
.... 1...
Bit 1 = RMODE specified, Bit 0 = RMODE(AUTO)
.... .1..
Bit 1 = RENT, Bit 0 = NORENT
.... ..1.
Bit 1 = RES: this flag will always be set on for
COBOL.
.... ...1
Bit 1 = RMODE(24), Bit 0 = RMODE(ANY)
736 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 119. SYSADATA options record (continued)
Field Size Description
Option byte 5 XL1
1... ....
Bit 1 = SQLCCSID, Bit 0 = NOSQLCCSID
.1.. ....
Bit 1 = OPT(1|2), Bit 0 = OPT(0)
..1. ....
Bit 1 = SQLIMS, Bit 0 = NOSQLIMS
...1 ....
Bit 1 = DBCS, Bit 0 = NODBCS
.... 1...
Bit 1 = AFP(VOLATILE), Bit 0 = AFP(NOVOLATILE)
.... .1..
Bit 1 = SSRANGE, Bit 0 = NOSSRANGE
.... ..1.
Bit 1 = TEST, Bit 0 = NOTEST
.... ...1
Bit 1 = PROBE, Bit 0 = NOPROBE (Windows only)
Option byte 6 XL1
1... ....
Bit 1 = SRCFORMAT(EXTEND), Bit 0 =
SRCFORMAT(COMPAT)
..1. ....
Bit 1 = NUMPROC(PFD), Bit 0 = NUMPROC(NOPFD)
...1 ....
Bit 1 = NUMCLS(ALT), Bit 0 = NUMCLS(PRIM)
.... .1..
Bit 1 = BINARY(S390), Bit 0 = BINARY(NATIVE)
(Windows and AIX only)
.... ..1.
Bit 1 = TRUNC(STD), Bit 0 = TRUNC(OPT)
.... ...1
Bit 1 = ZWB, Bit 0 = NOZWB
.1.. 1...
Reserved for future use
Option byte 7 XL1
1... ....
Bit 1 = ALOWCBL, Bit 0 = NOALOWCBL
.1.. ....
Bit 1 = TERM, Bit 0 = NOTERM
..1. ....
Bit 1 = DUMP, Bit 0 = NODUMP
.... ..1.
Bit 1 = CURRENCY, Bit 0 = NOCURRENCY
...1 11.1
Reserved for future use
Appendix F. COBOL SYSADATA file contents 737
Table 119. SYSADATA options record (continued)
Field Size Description
Option byte 8 XL1
| 1... ....
| Bit 1 = RULES, Bit 0 = NORULES
.1.. ....
Bit 1 = OPTFILE, Bit 0 = not OPTFILE
..1. ....
Bit 1 = ADDR(64), Bit 0 = ADDR(32) (AIX only)
.... 1...
Bit 1 = BLOCK0, Bit 0 = NOBLOCK0
.... ..1.
Bit 1 = DISPSIGN(SEP), Bit 0 = DISPSIGN(COMPAT)
.... ...1
Bit 1 = STGOPT, Bit 0 = NOSTGOPT
1..1 .1..
Reserved for future use
Option byte 9 XL1
1... ....
Bit 1 = DATA(24), Bit 0 = DATA(31)
.1.. ....
Bit 1 = FASTSRT, Bit 0 = NOFASTSRT
.... .1..
Bit 1 = THREAD, Bit 0 = NOTHREAD
| ..11 1.11
Reserved for future use
Option byte A XL1
1... ....
Bit 1 = HGPR(PRESERVE), Bit 0 =
HGPR(NOPRESERVE)
| .1.. ....
| Bit 1 = XMLPARSE(XMLSS), Bit 0 =
| XMLPARSE(COMPAT)
| ..1. ....
| Bit 1 = MAP(DEC), Bit 0 = MAP(HEX)
| ...1 1111
| Reserved for future use
Option byte B XL1
1111 1111
Reserved for future use
738 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 119. SYSADATA options record (continued)
Field Size Description
Option byte C XL1
1... ....
Bit 1 = NCOLLSEQ(LOCALE) (Windows and AIX
only)
.1.. ....
Reserved for future use
..1. ....
Bit 1 = INTDATE(LILIAN), Bit 0 = INTDATE(ANSI)
...1 ....
Bit 1 = NCOLLSEQ(BINARY) (Windows and AIX
only)
.... 1...
Bit 1 = CHAR(EBCDIC), Bit 0 = CHAR(NATIVE)
(Windows and AIX only)
.... .1..
Bit 1 = FLOAT(HEX), Bit 0 = FLOAT(NATIVE)
(Windows and AIX only)
.... ..1.
Bit 1 = COLLSEQ(BINARY) (Windows and AIX
only)
.... ...1
Bit 1 = COLLSEQ(LOCALE) (Windows and AIX
only)
Option byte D XL1
1... ....
Bit 1 = DLL, Bit 0 = NODLL
.1.. ....
Bit 1 = EXPORTALL, Bit 0 = NOEXPORTALL
..1. ....
Bit 1 = CODEPAGE
| ...1 ....
| Bit 1 = SOURCEFORMAT(EXTEND), Bit 0 =
| SOURCEFORMAT(COMPAT) (Windows and AIX only)
.... ..1.
Bit 1 = WSCLEAR, Bit 0 = NOWSCLEAR (Windows
and AIX only)
.... ...1
Bit 1 = BEOPT, Bit 0 = NOBEOPT (Windows and
AIX only)
| .... 11..
| Reserved for future use
Appendix F. COBOL SYSADATA file contents 739
Table 119. SYSADATA options record (continued)
Field Size Description
Option byte E XL1
.1.. ....
Bit 1 = DIAGTRUNC, Bit 0 = NODIAGTRUNC
.... .1..
Bit 1 = LSTFILE(UTF-8), Bit 0 = LSTFILE(LOCALE)
(Windows and AIX only)
.... ..1.
Bit 1 = MDECK, Bit 0 = NOMDECK
.... ...1
Bit 1 = MDECK(NOCOMPILE)
..11 1...
Reserved for future use
Option byte F XL1
| 1... ....
| Bit 1 = DIVIDE(S390), Bit 0 = DIVIDE(NATIVE)
| (AIX Only)
| .1.. ....
| Bit 1 = COPYRIGHT, Bit 0 = NOCOPYRIGHT
| ..1. ....
| Bit 1 = QUALIFY(EXTEND), Bit 0 =
| QUALIFY(COMPAT)
| ...1 ....
| Bit 1 = SERVICE, Bit 0 = NOSERVICE
| .... 1...
| Bit 1 = VLR(COMPAT), Bit 0 = VLR(STANDARD)
| .... .111
| Reserved for future use
Flag level XL1
X'00' Flag(I)
X'04' Flag(W)
X'08' Flag(E)
X'0C' Flag(S)
X'10' Flag(U)
X'FF' Noflag
Imbedded diagnostic XL1
X'00' Flag(I)
level
X'04' Flag(W)
X'08' Flag(E)
X'0C' Flag(S)
X'10' Flag(U)
X'FF' Noflag
740 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 119. SYSADATA options record (continued)
Field Size Description
FLAGSTD (FIPS) XL1
1... ....
specification
Minimum
.1.. ....
Intermediate
..1. ....
High
...1 ....
IBM extensions
.... 1...
Level-1 segmentation
.... .1..
Level-2 segmentation
.... ..1.
Debugging
.... ...1
Obsolete
Reserved for flagging XL1
1111 1111
Reserved for future use
Compiler mode XL1
X'00' Unconditional Nocompile, Nocompile(I)
X'04' Nocompile(W)
X'08' Nocompile(E)
X'0C' Nocompile(S)
X'FF' Compile
Space value CL1
Data for 3-valued XL1
1... ....
options
NAME(ALIAS) specified
.1.. ....
Reserved for future use
..1. ....
TRUNC(BIN) specified
...1 1111
Reserved for future use
TEST suboptions XL1
..1. ....
TEST(EJPD)
...1 ....
TEST(SOURCE)
11.. 1111
Reserved for TEST suboptions
OUTDD name length HL2 Length of OUTDD name
RWT ID Length HL2 Length of Reserved Word Table identifier
LVLINFO CL4 User-specified LVLINFO data
Appendix F. COBOL SYSADATA file contents 741
Table 119. SYSADATA options record (continued)
Field Size Description
PGMNAME suboptions XL1
1... ....
Bit 1 = PGMNAME(COMPAT)
.1.. ....
Bit 1 = PGMNAME(LONGUPPER)
..1. ....
Bit 1 = PGMNAME(LONGMIXED)
...1 1111
Reserved for future use
Entry interface XL1
1... ....
suboptions
Bit 1 = EntryInterface(System) (Windows only)
.1.. ....
Bit 1 = EntryInterface(OptLink) (Windows only)
..11 1111
Reserved for future use
CALLINTERFACE XL1
| suboptions
1... ....
| Bit 1 = CALLINTERFACE(DLL)
| .1.. ....
| Bit 1 = CALLINTERFACE(DYNAMIC)
| ..11 1111
| Reserved for future use
ARITH suboption XL1
1... ....
Bit 1 = ARITH(COMPAT)
.1.. ....
Bit 1 = ARITH(EXTEND)
11 1111
Reserved for future use
DBCS Req FL4 DBCS XREF storage requirement
DBCS ORDPGM HL2 Length of name of DBCS Ordering Program
length
DBCS ENCTBL HL2 Length of name of DBCS Encode Table
length
DBCS ORD TYPE CL2 DBCS Ordering type
Reserved CL5 Reserved for future use
Optimize level XL1 Optimization level 0 <= n <= 2
Converted SO CL1 Converted SO hexadecimal value
Converted SI CL1 Converted SI hexadecimal value
Language ID CL2 This field holds the two-character abbreviation (one of
EN, UE, JA, or JP) from the LANGUAGE option.
Reserved CL8 Reserved for future use
INEXIT name length HL2 Length of SYSIN user-exit name
PRTEXIT name length HL2 Length of SYSPRINT user-exit name
LIBEXIT name length HL2 Length of Libraryuser-exit name
ADEXIT name length HL2 Length of ADATA user-exit name
742 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 119. SYSADATA options record (continued)
Field Size Description
CURROPT CL5 CURRENCY option value
ARCH XL1 ARCH level number
Reserved CL2 Reserved for future use
CODEPAGE HL2 CODEPAGE CCSID option value
Reserved CL50 Reserved for future use
LINECNT HL2 LINECOUNT value
Reserved CL2 Reserved for future use
BUFSIZE FL4 BUFSIZE option value
Reserved FL4 Reserved for future use
Phase residence bits XL1
1... ....
byte 1
Bit 1 = IGYCLIBR in user region
.1.. ....
Bit 1 = IGYCSCAN in user region
..1. ....
Bit 1 = IGYCDSCN in user region
...1 ....
Bit 1 = IGYCGROU in user region
.... 1...
Bit 1 = IGYCPSCN in user region
.... .1..
Bit 1 = IGYCPANA in user region
.... ..1.
Bit 1 = IGYCFGEN in user region
.... ...1
Bit 1 = IGYCPGEN in user region
Phase residence bits XL1
.1.. ....
byte 2
Bit 1 = IGYCLSTR in user region
..1. ....
Bit 1 = IGYCXREF in user region
...1 ....
Bit 1 = IGYCDMAP in user region
.... ..1.
Bit 1 = IGYCDIAG in user region
.... ...1
Bit 1 = IGYCDGEN in user region
1... 11..
Reserved for future use
Phase residence bits XL2 Reserved
bytes 3 and 4
Reserved CL8 Reserved for future use
OUTDD name CL(n) OUTDD name
RWT CL(n) Reserved word table identifier
DBCS ORDPGM CL(n) DBCS Ordering program name
Appendix F. COBOL SYSADATA file contents 743
Table 119. SYSADATA options record (continued)
Field Size Description
DBCS ENCTBL CL(n) DBCS Encode table name
INEXIT name CL(n) SYSIN user-exit name
PRTEXIT name CL(n) SYSPRINT user-exit name
LIBEXIT name CL(n) Library user-exit name
ADEXIT name CL(n) ADATA user-exit name
External symbol record: X'0020'
The following table shows the contents of the external symbol record.
Table 120. SYSADATA external symbol record
Field Size Description
Section type XL1
X00 PROGRAM-ID name (main entry point name)
X01 ENTRY name (secondary entry point name)
X02 External reference (referenced external entry
point)
X04 Not applicable for COBOL
X05 Not applicable for COBOL
X06 Not applicable for COBOL
X0A Not applicable for COBOL
X12 Internal reference (referenced internal
subprogram)
XC0 External class-name (OO COBOL class
definition)
XC1 METHOD-ID name (OO COBOL method definition)
XC6 Method reference (OO COBOL method
reference)
XFF Not applicable for COBOL
Types X'12', X'C0', X'C1' and X'C6' are for COBOL only.
Flags XL1 Not applicable for COBOL
Reserved HL2 Reserved for future use
Symbol-ID FL4 Symbol-ID of program that contains the reference (only
for types x'02' and x'12')
Line number FL4 Line number of statement that contains the reference
(only for types x'02' and x'12')
Section length FL4 Not applicable for COBOL
LD ID FL4 Not applicable for COBOL
Reserved CL8 Reserved for future use
External name length HL2 Number of characters in the external name
Alias name length HL2 Not applicable for COBOL
External name CL(n) The external name
744 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 120. SYSADATA external symbol record (continued)
Field Size Description
Alias section name CL(n) Not applicable for COBOL
Parse tree record: X'0024'
The following table shows the contents of the parse tree record.
Table 121. SYSADATA parse tree record
Field Size Description
Node number FL4 The node number generated by the compiler, starting at
1
Node type HL2 The type of the node:
001 Program
002 Class
003 Method
101 IDENTIFICATION DIVISION
102 ENVIRONMENT DIVISION
103 DATA DIVISION
104 PROCEDURE DIVISION
105 End Program/Method/Class
201 Declaratives body
202 Nondeclaratives body
301 Section
302 Procedure section
401 Paragraph
402 Procedure paragraph
501 Sentence
502 File definition
503 Sort file definition
504 Program-name
505 Program attribute
508 ENVIRONMENT DIVISION clause
509 CLASS attribute
510 METHOD attribute
511 USE statement
Appendix F. COBOL SYSADATA file contents 745
Table 121. SYSADATA parse tree record (continued)
Field Size Description
601 Statement
602 Data description clause
603 Data entry
604 File description clause
605 Data entry name
606 Data entry level
607 EXEC entry
701 EVALUATE subject phrase
702 EVALUATE WHEN phrase
703 EVALUATE WHEN OTHER phrase
704 SEARCH WHEN phrase
705 INSPECT CONVERTING phrase
706 INSPECT REPLACING phrase
707 INSPECT TALLYING phrase
708 PERFORM UNTIL phrase
709 PERFORM VARYING phrase
710 PERFORM AFTER phrase
711 Statement block
712 Scope terminator
713 INITIALIZE REPLACING phrase
714 EXEC CICS Command
720 DATA DIVISION phrase
801 Phrase
802 ON phrase
803 NOT phrase
804 THEN phrase
805 ELSE phrase
806 Condition
807 Expression
808 Relative indexing
809 EXEC CICS Option
810 Reserved word
811 INITIALIZE REPLACING category
746 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 121. SYSADATA parse tree record (continued)
Field Size Description
901 Section or paragraph name
902 Identifier
903 Alphabet-name
904 Class-name
905 Condition-name
906 File-name
907 Index-name
908 Mnemonic-name
910 Symbolic-character
911 Literal
912 Function identifier
913 Data-name
914 Special register
915 Procedure reference
916 Arithmetic operator
917 All procedures
918 INITIALIZE literal (no tokens)
919 ALL literal or figcon
920 Keyword class test name
921 Reserved word at identifier level
922 Unary operator
923 Relational operator
1001 Subscript
1002 Reference modification
Node subtype HL2 The subtype of the node.
For Section type:
0001 CONFIGURATION Section
0002 INPUT-OUTPUT Section
0003 FILE SECTION
0004 WORKING-STORAGE SECTION
0005 LINKAGE SECTION
0006 LOCAL-STORAGE SECTION
0007 REPOSITORY Section
Appendix F. COBOL SYSADATA file contents 747
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For Paragraph type:
0001 PROGRAM-ID paragraph
0002 AUTHOR paragraph
0003 INSTALLATION paragraph
0004 DATE-WRITTEN paragraph
0005 SECURITY paragraph
0006 SOURCE-COMPUTER paragraph
0007 OBJECT-COMPUTER paragraph
0008 SPECIAL-NAMES paragraph
0009 FILE-CONTROL paragraph
0010 I-O-CONTROL paragraph
0011 DATE-COMPILED paragraph
0012 CLASS-ID paragraph
0013 METHOD-ID paragraph
0014 REPOSITORY paragraph
For ENVIRONMENT DIVISION clause type:
0001 WITH DEBUGGING MODE
0002 MEMORY-SIZE
0003 SEGMENT-LIMIT
0004 CURRENCY-SIGN
0005 DECIMAL POINT
0006 PROGRAM COLLATING SEQUENCE
0007 ALPHABET
0008 SYMBOLIC-CHARACTER
0009 CLASS
0010 ENVIRONMENT NAME
0011 SELECT
0012 XML-SCHEMA
748 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For data description clause type:
0001 BLANK WHEN ZERO
0002 DATA-NAME OR FILLER
0003 JUSTIFIED
0004 OCCURS
0005 PICTURE
0006 REDEFINES
0007 RENAMES
0008 SIGN
0009 SYNCHRONIZED
0010 USAGE
0011 VALUE
| 0012 VOLATILE
0023 GLOBAL
0024 EXTERNAL
Appendix F. COBOL SYSADATA file contents 749
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For file description clause type:
0001 FILE STATUS
0002 ORGANIZATION
0003 ACCESS MODE
0004 RECORD KEY
0005 ASSIGN
0006 RELATIVE KEY
0007 PASSWORD
0008 PROCESSING MODE
0009 RECORD DELIMITER
0010 PADDING CHARACTER
0011 BLOCK CONTAINS
0012 RECORD CONTAINS
0013 LABEL RECORDS
0014 VALUE OF
0015 DATA RECORDS
0016 LINAGE
0017 ALTERNATE KEY
0018 LINES AT TOP
0019 LINES AT BOTTOM
0020 CODE-SET
0021 RECORDING MODE
0022 RESERVE
0023 GLOBAL
0024 EXTERNAL
0025 LOCK
750 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For Statement type:
0002 NEXT SENTENCE
0003 ACCEPT
0004 ADD
0005 ALTER
0006 CALL
0007 CANCEL
0008 CLOSE
0009 COMPUTE
0010 CONTINUE
0011 DELETE
0012 DISPLAY
0013 DIVIDE (INTO)
0113 DIVIDE (BY)
0014 ENTER
0015 ENTRY
0016 EVALUATE
0017 EXIT
0018 GO
0019 GOBACK
0020 IF
0021 INITIALIZE
0022 INSPECT
Appendix F. COBOL SYSADATA file contents 751
Table 121. SYSADATA parse tree record (continued)
Field Size Description
0023 INVOKE
0024 MERGE
0025 MOVE
0026 MULTIPLY
0027 OPEN
0028 PERFORM
0029 READ
0030 READY
0031 RELEASE
0032 RESET
0033 RETURN
0034 REWRITE
0035 SEARCH
0036 SERVICE
0037 SET
0038 SORT
0039 START
0040 STOP
0041 STRING
0042 SUBTRACT
0043 UNSTRING
0044 EXEC SQL
0144 EXEC CICS
0045 WRITE
0046 XML
752 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For Phrase type:
0001 INTO
0002 DELIMITED
0003 INITIALIZE. . .REPLACING
0004 INSPECT. . .ALL
0005 INSPECT. . .LEADING
0006 SET. . .TO
0007 SET. . .UP
0008 SET. . .DOWN
0009 PERFORM. . .TIMES
0010 DIVIDE. . .REMAINDER
0011 INSPECT. . .FIRST
0012 SEARCH. . .VARYING
0013 MORE-LABELS
0014 SEARCH ALL
0015 SEARCH. . .AT END
0016 SEARCH. . .TEST INDEX
0017 GLOBAL
0018 LABEL
0019 DEBUGGING
0020 SEQUENCE
0021 Reserved for future use
0022 Reserved for future use
0023 Reserved for future use
0024 TALLYING
0025 Reserved for future use
0026 ON SIZE ERROR
0027 ON OVERFLOW
0028 ON ERROR
0029 AT END
0030 INVALID KEY
0031 END-OF-PAGE
0032 USING
Appendix F. COBOL SYSADATA file contents 753
Table 121. SYSADATA parse tree record (continued)
Field Size Description
0033 BEFORE
0034 AFTER
0035 EXCEPTION
0036 CORRESPONDING
0037 Reserved for future use
0038 RETURNING
0039 GIVING
0040 THROUGH
0041 KEY
0042 DELIMITER
0043 POINTER
0044 COUNT
0045 METHOD
0046 PROGRAM
0047 INPUT
0048 OUTPUT
0049 I-O
0050 EXTEND
0051 RELOAD
0052 ASCENDING
0053 DESCENDING
0054 DUPLICATES
0055 NATIVE (USAGE)
0056 INDEXED
0057 FROM
0058 FOOTING
0059 LINES AT BOTTOM
0060 LINES AT TOP
0061 XML ENCODING
0062 XML GENERATE XML-DECLARATION
0063 XML GENERATE ATTRIBUTES
0064 XML GENERATE NAMESPACE
0065 XML PARSE PROCESSING
0066 XML PARSE VALIDATING
0067 XML GENERATE NAME
0068 XML GENERATE TYPE
0069 XML GENERATE SUPPRESS
754 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For Function identifier type:
0001 COS
0002 LOG
0003 MAX
0004 MIN
0005 MOD
0006 ORD
0007 REM
0008 SIN
0009 SUM
0010 TAN
0011 ACOS
0012 ASIN
0013 ATAN
0014 CHAR
0015 MEAN
0016 SQRT
0017 LOG10
0018 RANGE
0019 LENGTH
0020 MEDIAN
0021 NUMVAL
0022 RANDOM
0023 ANNUITY
0024 INTEGER
0025 ORD-MAX
0026 ORD-MIN
0027 REVERSE
0028 MIDRANGE
0029 NUMVAL-C
0030 VARIANCE
0031 FACTORIAL
0032 LOWER-CASE
Appendix F. COBOL SYSADATA file contents 755
Table 121. SYSADATA parse tree record (continued)
Field Size Description
0033 UPPER-CASE
0034 CURRENT-DATE
0035 INTEGER-PART
0036 PRESENT-VALUE
0037 WHEN-COMPILED
0038 DAY-OF-INTEGER
0039 INTEGER-OF-DAY
0040 DATE-OF-INTEGER
0041 INTEGER-OF-DATE
0042 STANDARD-DEVIATION
0043 YEAR-TO-YYYY
0044 DAY-TO-YYYYDDD
0045 DATE-TO-YYYYMMDD
0049 DISPLAY-OF
0050 NATIONAL-OF
0051 UPOS
0052 UVALID
0053 UWIDTH
0054 ULENGTH
0055 USUBSTR
0056 USUPPLEMENTARY
For Special Register type:
0001 ADDRESS OF
0002 LENGTH OF
For Keyword Class Test Name type:
0001 ALPHABETIC
0002 ALPHABETIC-LOWER
0003 ALPHABETIC-UPPER
0004 DBCS
0005 KANJI
0006 NUMERIC
0007 NEGATIVE
0008 POSITIVE
0009 ZERO
756 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For Reserved Word type:
0001 TRUE
0002 FALSE
0003 ANY
0004 THRU
For Identifier, Data-name, Index-name, Condition-name
or Mnemonic-name type:
0001 REFERENCED
0002 CHANGED
0003 REFERENCED & CHANGED
For Initialize literal type:
0001 ALPHABETIC
0002 ALPHANUMERIC
0003 NUMERIC
0004 ALPHANUMERIC-EDITED
0005 NUMERIC-EDITED
0006 DBCS/EGCS
0007 NATIONAL
0008 NATIONAL-EDITED
For Procedure-name type:
0001 SECTION
0002 PARAGRAPH
Appendix F. COBOL SYSADATA file contents 757
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For Reserved word at identifier level type:
0001 ROUNDED
0002 TRUE
0003 ON
0004 OFF
0005 SIZE
0006 DATE
0007 DAY
0008 DAY-OF-WEEK
0009 TIME
0010 WHEN-COMPILED
0011 PAGE
0012 DATE YYYYMMDD
0013 DAY YYYYDDD
0014 Attribute
0015 Element
0016 Content
0017 Numeric
0018 Nonnumeric
0019 Every
0020 When
For Arithmetic Operator type:
0001 PLUS
0002 MINUS
0003 TIMES
0004 DIVIDE
0005 DIVIDE REMAINDER
0006 EXPONENTIATE
0007 NEGATE
758 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 121. SYSADATA parse tree record (continued)
Field Size Description
For Relational Operator type:
0008 LESS
0009 LESS OR EQUAL
0010 EQUAL
0011 NOT EQUAL
0012 GREATER
0013 GREATER OR EQUAL
0014 AND
0015 OR
0016 CLASS CONDITION
0017 NOT CLASS CONDITION
Parent node number FL4 The node number of the parent of the node
Left sibling node FL4 The node number of the left sibling of the node, if any. If
number none, the value is zero.
Symbol ID FL4 The Symbol ID of the node, if it is a user-name of one of
the following types:
v Data entry
v Identifier
v File-name
v Index-name
v Procedure-name
v Condition-name
v Mnemonic-name
This value corresponds to the Symbol ID in a Symbol
(Type 42) record, except for procedure-names where it
corresponds to the Paragraph ID.
For all other node types this value is zero.
Section Symbol ID FL4 The Symbol ID of the section containing the node, if it is
a qualified paragraph-name reference. This value
corresponds to the Section ID in a Symbol (Type 42)
record.
For all other node types this value is zero.
First token number FL4 The number of the first token associated with the node
Last token number FL4 The number of the last token associated with the node
Reserved FL4 Reserved for future use
Flags CL1 Information about the node:
X'80' Reserved
X'40' Generated node, no tokens
Reserved CL3 Reserved for future use
Appendix F. COBOL SYSADATA file contents 759
Token record: X'0030'
The compiler does not generate token records for any lines that are treated as
comment lines, which include, but are not limited to, items in the following list.
v Comment lines, which are source lines that have an asterisk (*) or a slash (/) in
column 7
v The following compiler-directing statements:
*CBL (*CONTROL)
BASIS
COPY
DELETE
EJECT
INSERT
REPLACE
SKIP1
SKIP2
SKIP3
TITLE
v Debugging lines, which are source lines that have a D in column 7, if WITH
DEBUGGING MODE is not specified
Table 122. SYSADATA token record
Field Size Description
Token number FL4 The token number within the source file generated by
the compiler, starting at 1. Any copybooks have already
been included in the source.
760 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 122. SYSADATA token record (continued)
Field Size Description
Token code HL2 The type of token (user-name, literal, reserved word, and
so forth).
For reserved words, the compiler reserved-word table
values are used.
For PICTURE strings, the special code 0000 is used.
For each piece (other than the last) of a continued token,
the special code 3333 is used.
Otherwise, the following codes are used:
0001 ACCEPT
0002 ADD
0003 ALTER
0004 CALL
0005 CANCEL
0007 CLOSE
0009 COMPUTE
0011 DELETE
0013 DISPLAY
0014 DIVIDE
0017 READY
0018 END-PERFORM
0019 ENTER
0020 ENTRY
0021 EXIT
0022 EXEC
EXECUTE
0023 GO
0024 IF
0025 INITIALIZE
0026 INVOKE
0027 INSPECT
0028 MERGE
0029 MOVE
Appendix F. COBOL SYSADATA file contents 761
Table 122. SYSADATA token record (continued)
Field Size Description
0030 MULTIPLY
0031 OPEN
0032 PERFORM
0033 READ
0035 RELEASE
0036 RETURN
0037 REWRITE
0038 SEARCH
0040 SET
0041 SORT
0042 START
0043 STOP
0044 STRING
0045 SUBTRACT
0048 UNSTRING
0049 USE
0050 WRITE
0051 CONTINUE
0052 END-ADD
0053 END-CALL
0054 END-COMPUTE
0055 END-DELETE
0056 END-DIVIDE
0057 END-EVALUATE
0058 END-IF
0059 END-MULTIPLY
0060 END-READ
0061 END-RETURN
0062 END-REWRITE
0063 END-SEARCH
0064 END-START
0065 END-STRING
0066 END-SUBTRACT
0067 END-UNSTRING
0068 END-WRITE
0069 GOBACK
762 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 122. SYSADATA token record (continued)
Field Size Description
0070 EVALUATE
0071 RESET
0072 SERVICE
0073 END-INVOKE
0074 END-EXEC
0075 XML
0076 END-XML
0099 FOREIGN-VERB
0101 DATA-NAME
0105 DASHED-NUM
0106 DECIMAL
0107 DIV-SIGN
0108 EQ
0109 EXPONENTIATION
0110 GT
0111 INTEGER
0112 LT
0113 LPAREN
0114 MINUS-SIGN
0115 MULT-SIGN
0116 NONUMLIT
0117 PERIOD
0118 PLUS-SIGN
0121 RPAREN
0122 SIGNED-INTEGER
0123 QUID
0124 COLON
0125 IEOF
0126 EGCS-LIT
0127 COMMA-SPACE
0128 SEMICOLON-SPACE
0129 PROCEDURE-NAME
0130 FLT-POINT-LIT
0131 Language Environment
Appendix F. COBOL SYSADATA file contents 763
Table 122. SYSADATA token record (continued)
Field Size Description
0132 GE
0133 IDREF
0134 EXPREF
0136 CICS
0137 NEW
0138 NATIONAL-LIT
0200 ADDRESS
0201 ADVANCING
0202 AFTER
0203 ALL
0204 ALPHABETIC
0205 ALPHANUMERIC
0206 ANY
0207 AND
0208 ALPHANUMERIC-EDITED
0209 BEFORE
0210 BEGINNING
0211 FUNCTION
0212 CONTENT
0213 CORR
CORRESPONDING
0214 DAY
0215 DATE
0216 DEBUG-CONTENTS
0217 DEBUG-ITEM
0218 DEBUG-LINE
0219 DEBUG-NAME
0220 DEBUG-SUB-1
0221 DEBUG-SUB-2
0222 DEBUG-SUB-3
0223 DELIMITED
0224 DELIMITER
0225 DOWN
764 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 122. SYSADATA token record (continued)
Field Size Description
0226 NUMERIC-EDITED
0227 XML-EVENT
0228 END-OF-PAGE
EOP
0229 EQUAL
0230 ERROR
0231 XML-NTEXT
0232 EXCEPTION
0233 EXTEND
0234 FIRST
0235 FROM
0236 GIVING
0237 GREATER
0238 I-O
0239 IN
0240 INITIAL
0241 INTO
0242 INVALID
0243 SQL
0244 LESS
0245 LINAGE-COUNTER
0246 XML-TEXT
0247 LOCK
0248 GENERATE
0249 NEGATIVE
0250 NEXT
0251 NO
0252 NOT
0253 NUMERIC
0254 KANJI
0255 OR
0256 OTHER
0257 OVERFLOW
0258 PAGE
0259 CONVERTING
Appendix F. COBOL SYSADATA file contents 765
Table 122. SYSADATA token record (continued)
Field Size Description
0260 POINTER
0261 POSITIVE
0262 DBCS
0263 PROCEDURES
0264 PROCEED
0265 REFERENCES
0266 DAY-OF-WEEK
0267 REMAINDER
0268 REMOVAL
0269 REPLACING
0270 REVERSED
0271 REWIND
0272 ROUNDED
0273 RUN
0274 SENTENCE
0275 STANDARD
0276 RETURN-CODE
SORT-CORE-SIZE
SORT-FILE-SIZE
SORT-MESSAGE
SORT-MODE-SIZE
SORT-RETURN
TALLY
XML-CODE
0277 TALLYING
0278 SUM
0279 TEST
0280 THAN
0281 UNTIL
0282 UP
0283 UPON
0284 VARYING
0285 RELOAD
0286 TRUE
766 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 122. SYSADATA token record (continued)
Field Size Description
0287 THEN
0288 RETURNING
0289 ELSE
0290 SELF
0291 SUPER
0292 WHEN-COMPILED
0293 ENDING
0294 FALSE
0295 REFERENCE
0296 NATIONAL-EDITED
0297 COM-REG
0298 ALPHABETIC-LOWER
0299 ALPHABETIC-UPPER
0301 REDEFINES
0302 OCCURS
0303 SYNC
SYNCHRONIZED
0304 MORE-LABELS
0305 JUST
JUSTIFIED
0306 SHIFT-IN
0307 BLANK
0308 VALUE
0309 COMP
COMPUTATIONAL
0310 COMP-1
COMPUTATIONAL-1
0311 COMP-3
COMPUTATIONAL-3
0312 COMP-2
COMPUTATIONAL-2
0313 COMP-4
COMPUTATIONAL-4
0314 DISPLAY-1
0315 SHIFT-OUT
Appendix F. COBOL SYSADATA file contents 767
Table 122. SYSADATA token record (continued)
Field Size Description
0316 INDEX
0317 USAGE
0318 SIGN
0319 LEADING
0320 SEPARATE
0321 INDEXED
0322 LEFT
0323 RIGHT
0324 PIC
PICTURE
0325 VALUES
0326 GLOBAL
0327 EXTERNAL
0328 BINARY
0329 PACKED-DECIMAL
0330 EGCS
0331 PROCEDURE-POINTER
0332 COMP-5
COMPUTATIONAL-5
0333 FUNCTION-POINTER
0334 TYPE
0335 JNIENVPTR
0336 NATIONAL
0337 GROUP-USAGE
| 0342 VOLATILE
0401 HIGH-VALUE
HIGH-VALUES
0402 LOW-VALUE
LOW-VALUES
0403 QUOTE
QUOTES
0404 SPACE
SPACES
0405 ZERO
768 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 122. SYSADATA token record (continued)
Field Size Description
0406 ZEROES
ZEROS
0407 NULL
NULLS
0501 BLOCK
0502 BOTTOM
0505 CHARACTER
0506 CODE
0507 CODE-SET
0514 FILLER
0516 FOOTING
0520 LABEL
0521 LENGTH
0524 LINAGE
0526 OMITTED
0531 RENAMES
0543 TOP
0545 TRAILING
0549 RECORDING
0601 INHERITS
0603 RECURSIVE
0701 ACCESS
0702 ALSO
0703 ALTERNATE
0704 AREA
AREAS
0705 ASSIGN
0707 COLLATING
0708 COMMA
0709 CURRENCY
0710 CLASS
0711 DECIMAL-POINT
0712 DUPLICATES
0713 DYNAMIC
0714 EVERY
Appendix F. COBOL SYSADATA file contents 769
Table 122. SYSADATA token record (continued)
Field Size Description
0716 MEMORY
0717 MODE
0718 MODULES
0719 MULTIPLE
0720 NATIVE
0721 OFF
0722 OPTIONAL
0723 ORGANIZATION
0724 POSITION
0725 PROGRAM
0726 RANDOM
0727 RELATIVE
0728 RERUN
0729 RESERVE
0730 SAME
0731 SEGMENT-LIMIT
0732 SELECT
0733 SEQUENCE
0734 SEQUENTIAL
0736 SORT-MERGE
0737 STANDARD-1
0738 TAPE
0739 WORDS
0740 PROCESSING
0741 APPLY
0742 WRITE-ONLY
0743 COMMON
0744 ALPHABET
0745 PADDING
0746 SYMBOLIC
0747 STANDARD-2
0748 OVERRIDE
0750 PASSWORD
0751 XML-SCHEMA
770 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 122. SYSADATA token record (continued)
Field Size Description
0801 ARE
IS
0802 ASCENDING
0803 AT
0804 BY
0805 CHARACTERS
0806 CONTAINS
0808 COUNT
0809 DEBUGGING
0810 DEPENDING
0811 DESCENDING
0812 DIVISION
0814 FOR
0815 ORDER
0816 INPUT
0817 REPLACE
0818 KEY
0819 LINE
LINES
0820 XML-INFORMATION
0821 OF
0822 ON
0823 OUTPUT
0825 RECORD
0826 RECORDS
0827 REEL
0828 SECTION
0829 SIZE
0830 STATUS
0831 THROUGH
THRU
0832 TIME
0833 TIMES
0834 TO
0836 UNIT
| 840 SQLIMS
Appendix F. COBOL SYSADATA file contents 771
Table 122. SYSADATA token record (continued)
Field Size Description
0837 USING
0838 WHEN
0839 WITH
0840 SQLIMS
0901 PROCEDURE
0902 DECLARATIVES
0903 END
1001 DATA
1002 FILE
1003 FD
1004 SD
1005 WORKING-STORAGE
1006 LOCAL-STORAGE
1007 LINKAGE
1101 ENVIRONMENT
1102 CONFIGURATION
1103 SOURCE-COMPUTER
1104 OBJECT-COMPUTER
1105 SPECIAL-NAMES
1106 REPOSITORY
1107 INPUT-OUTPUT
1108 FILE-CONTROL
1109 I-O-CONTROL
1201 ID
IDENTIFICATION
1202 PROGRAM-ID
1203 AUTHOR
1204 INSTALLATION
1205 DATE-WRITTEN
1206 DATE-COMPILED
1207 SECURITY
1208 CLASS-ID
1209 METHOD-ID
1210 METHOD
1211 FACTORY
772 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 122. SYSADATA token record (continued)
Field Size Description
1212 OBJECT
2020 TRACE
| 2046 SUPPRESS
3000 DATADEF
3001 F-NAME
3002 UPSI-SWITCH
3003 CONDNAME
3004 CONDVAR
3005 BLOB
3006 CLOB
3007 DBCLOB
3008 BLOB-LOCATOR
3009 CLOB-LOCATOR
3010 DBCLOB-LOCATOR
3011 BLOB-FILE
3012 CLOB-FILE
3013 DBCLOB-FILE
3014 DFHRESP
5001 PARSE
5002 AUTOMATIC
5003 PREVIOUS
5004 ENCODING
5005 NAMESPACE
5006 NAMESPACE-PREFIX
5007 XML-DECLARATION
5008 ATTRIBUTES
5009 VALIDATING
5010 UNBOUNDED
5011 ATTRIBUTE
5012 ELEMENT
5013 NONNUMERIC
5014 NAME
| 5015 CYCLE
| 5016 PARAGRAPH
9999 COBOL
Token length HL2 The length of the token
Token column FL4 The starting column number of the token in the source
listing
Appendix F. COBOL SYSADATA file contents 773
Table 122. SYSADATA token record (continued)
Field Size Description
Token line FL4 The line number of the token in the source listing
Flags CL1 Information about the token:
X'80' Token is continued
X'40' Last piece of continued token
Note that for PICTURE strings, even if the source token is
continued, there will be only one Token record
generated. It will have a token code of 0000, the token
column and line of the first piece, the length of the
complete string, no continuation flags set, and the token
text of the complete string.
Reserved CL7 Reserved for future use
Token text CL(n) The actual token string
Source error record: X'0032'
The following table shows the contents of the source error record.
Table 123. SYSADATA source error record
Field Size Description
Statement number FL4 The statement number of the statement in error
Error identifier CL16 The error message identifier (left-justified and padded
with blanks)
Error severity HL2 The severity of the error
Error message length HL2 The length of the error message text
Line position XL1 The line position indicator provided in FIPS messages
Reserved CL7 Reserved for future use
Error message CL(n) The error message text
Source record: X'0038'
The following table shows the contents of the source record.
Table 124. SYSADATA source record
Field Size Description
Line number FL4 The listing line number of the source record
Input record number FL4 The input source record number in the current input file
Primary file number HL2 The input file's assigned sequence number if this record
is from the primary input file. (Refer to the Input file n
field in the Job identification record).
Library file number HL2 The library input file's assigned sequence number if this
record is from a COPY|BASIS input file. (Refer to the
Member File ID n field in the Library record.)
Reserved CL8 Reserved for future use
Parent record number FL4 The parent source record number. This will be the record
number of the COPY|BASIS statement.
774 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 124. SYSADATA source record (continued)
Field Size Description
Parent primary file HL2 The parent file's assigned sequence number if the parent
number of this record is from the primary input file. (Refer to the
Input file n field in the Job Identification Record.)
Parent library HL2 The parent library file's assigned sequence number if this
assigned file number record's parent is from a COPY|BASIS input file. (Refer to
the COPY/BASIS Member File ID n field in the Library
record.)
Reserved CL8 Reserved for future use
Length of source HL2 The length of the actual source record following
record
Reserved CL10 Reserved for future use
Source record CL(n)
COPY REPLACING record: X'0039'
One COPY REPLACING type record will be emitted each time a REPLACING action takes
place. That is, whenever operand-1 of the REPLACING phrase is matched with text in
the copybook, a COPY REPLACING TEXT record will be written.
The following table shows the contents of the COPY REPLACING record.
Table 125. SYSADATA COPY REPLACING record
Field Size Description
Starting line number FL4 The listing line number of the start of the text that
of replaced string resulted from REPLACING
Starting column FL4 The listing column number of the start of the text that
number of replaced resulted from REPLACING
string
Ending line number FL4 The listing line number of the end of the text that
of replaced string resulted from REPLACING
Ending column FL4 The listing column number of the end of the text that
number of replaced resulted from REPLACING
string
Starting line number FL4 The source file line number of the start of the text that
of original string was changed by REPLACING
Starting column FL4 The source file column number of the start of the text
number of original that was changed by REPLACING
string
Ending line number FL4 The source file line number of the end of the text that
of original string was changed by REPLACING
Ending column FL4 The source file column number of the end of the text that
number of original was changed by REPLACING
string
Appendix F. COBOL SYSADATA file contents 775
Symbol record: X'0042'
The following table shows the contents of the symbol record.
Table 126. SYSADATA symbol record
Field Size Description
Symbol ID FL4 Unique ID of symbol
Line number FL4 The listing line number of the source record in which the
symbol is defined or declared
Level XL1 True level-number of symbol (or relative level-number of
a data item within a structure). For COBOL, this can be
in the range 01-49, 66 (for RENAMES items), 77, or 88 (for
condition items).
Qualification XL1
X00 Unique name; no qualification needed.
indicator
X01 This data item needs qualification. The name is
not unique within the program. This field
applies only when this data item is not the
level-01 name.
Symbol type XL1
X68 Class-name (Class-ID)
X58 Method-name
X40 Data-name
X20 Procedure-name
X10 Mnemonic-name
X08 Program-name
X81 Reserved
The following ORed are into the above types, when
applicable:
X04 External
X02 Global
776 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 126. SYSADATA symbol record (continued)
Field Size Description
Symbol attribute XL1
X01 Numeric
X02 Elementary character of one of these classes:
v Alphabetic
v Alphanumeric
v DBCS
v National
X03 Group
X04 Pointer
X05 Index data item
X06 Index-name
X07 Condition
X0F File
X10 Sort file
X17 Class-name (repository)
X18 Object reference
X19 Currency-sign symbol
X1A XML schema name
Appendix F. COBOL SYSADATA file contents 777
Table 126. SYSADATA symbol record (continued)
Field Size Description
Clauses XL1 Clauses specified in symbol definition.
For symbols that have a symbol attribute of Numeric
(X01), Elementary character (X02), Group (X03),
Pointer (X04), Index data item (X05), or Object
reference (X18):
1... ....
Value
.1.. ....
Indexed
..1. ....
Redefines
...1 ....
Renames
.... 1...
Occurs
.... .1..
Has Occurs keys
.... ..1.
Occurs Depending On
.... ...1
Occurs in parent
For file types:
1... ....
Select
.1.. ....
Assign
..1. ....
Rerun
...1 ....
Same area
.... 1...
Same record area
.... .1..
Recording mode
.... ..1.
Reserved
.... ...1
Record
778 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 126. SYSADATA symbol record (continued)
Field Size Description
For mnemonic-name symbols:
01 CSP
02 C01
03 C02
04 C03
05 C04
06 C05
07 C06
08 C07
09 C08
10 C09
11 C10
12 C11
13 C12
14 S01
15 S02
16 S03
17 S04
18 S05
19 CONSOLE
20 SYSIN|SYSIPT
22 SYSOUT|SYSLST|SYSLIST
24 SYSPUNCH|SYSPCH
26 UPSI-0
27 UPSI-1
28 UPSI-2
29 UPSI-3
30 UPSI-4
31 UPSI-5
32 UPSI-6
33 UPSI-7
34 AFP-5A
Appendix F. COBOL SYSADATA file contents 779
Table 126. SYSADATA symbol record (continued)
Field Size Description
Data flags 1 XL1 For file types, and for symbols that have a symbol
attribute of Numeric (X01), Elementary character
(X02), Group (X03), Pointer (X04), Index data item
(X05), or Object reference (X18):
1... ....
Redefined
.1.. ....
Renamed
..1. ....
Synchronized
...1 ....
Implicitly redefined
.... 1...
| Volatile
.... .1..
Implicit redefines
.... ..1.
FILLER
.... ...1
Level 77
780 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 126. SYSADATA symbol record (continued)
Field Size Description
Data flags 2 XL1 For symbols that have a symbol attribute of Numeric
(X01):
1... ....
Binary
.1.. ....
External floating point (of USAGE DISPLAY or
USAGE NATIONAL)
..1. ....
Internal floating point
...1 ....
Packed
.... 1...
External decimal (of USAGE DISPLAY or USAGE
NATIONAL)
.... .1..
Scaled negative
.... ..1.
Numeric edited (of USAGE DISPLAY or USAGE
NATIONAL)
.... ...1
Reserved for future use
For symbols that have a symbol attribute of Elementary
character (X02) or Group (X03):
1... ....
Alphabetic
.1.. ....
Alphanumeric
..1. ....
Alphanumeric edited
...1 ....
Group contains its own ODO object
.... 1...
DBCS item
.... .1..
Group variable length
.... ..1.
EGCS item
.... ...1
EGCS edited
Appendix F. COBOL SYSADATA file contents 781
Table 126. SYSADATA symbol record (continued)
Field Size Description
For file types:
1... ....
Object of ODO in record
.1.. ....
Subject of ODO in record
..1. ....
Sequential access
...1 ....
Random access
.... 1...
Dynamic access
.... .1..
Locate mode
.... ..1.
Record area
.... ...1
Reserved for future use
Data flags 3 XL1
1... ....
All records are the same length
.1.. ....
Fixed length
..1. ....
Variable length
...1 ....
Undefined
.... 1...
Spanned
.... .1..
Blocked
.... ..1.
Apply write only
.... ...1
Same sort merge area
782 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 126. SYSADATA symbol record (continued)
Field Size Description
File organization and XL1
1... ....
attributes
Physical sequential (on host, QSAM)
.1.. ....
ASCII
..1. ....
Standard label
...1 ....
User label
.... 1...
Sequential organization
.... .1..
Indexed organization
.... ..1.
Relative organization
.... ...1
Line sequential
USAGE clause FL1
X00 USAGE IS DISPLAY
X01 USAGE IS COMP-1
X02 USAGE IS COMP-2
X03 USAGE IS PACKED-DECIMAL or USAGE IS COMP-3
X04 USAGE IS BINARY, USAGE IS COMP, USAGE IS
COMP-4, or USAGE IS COMP-5
X05 USAGE IS DISPLAY-1
X06 USAGE IS POINTER
X07 USAGE IS INDEX
X08 USAGE IS PROCEDURE-POINTER
X09 USAGE IS OBJECT-REFERENCE
X0A FUNCTION-POINTER
X0B NATIONAL
Sign clause FL1
X00 No SIGN clause
X01 SIGN IS LEADING
X02 SIGN IS LEADING SEPARATE CHARACTER
X03 SIGN IS TRAILING
X04 SIGN IS TRAILING SEPARATE CHARACTER
Indicators FL1
X01 Has JUSTIFIED clause. Right-justified attribute is
in effect.
X02 Has BLANK WHEN ZERO clause.
Appendix F. COBOL SYSADATA file contents 783
Table 126. SYSADATA symbol record (continued)
Field Size Description
Size FL4 The size of this data item. The actual number of bytes
this item occupies in storage. If a DBCS item, the number
is in bytes, not characters. For variable-length items, this
field will reflect the maximum size of storage reserved
for this item by the compiler. Also known as the "Length
attribute."
Precision FL1 The precision of a fixed or float data item
Scale FL1 The scale factor of a fixed data item. This is the number
of digits to the right of the decimal point.
| Storage type FL1
| 00 Not applicable
| 01 Files
| 02 Working-Storage
| 03 Linkage Section
| 05 Special registers
| 07 Indexed by variable
| 10 UPSI switch
| 13 Variably located items
| 14 External data
| 15 Alphanumeric FUNC
| 16 Alphanumeric EVAL
| 17 Object data
| 19 Local-Storage
| 20 Factory data
| 21 XML-TEXT and XML-NTEXT
| Date format FL1 Reserved for future use
Data flags 4 XL1 For symbols that have a symbol attribute of Numeric
(X01):
1... ....
Numeric national
For symbols that have a symbol attribute of Elementary
character (X02):
1... ....
National
.1.. ....
National edited
For symbols that have a symbol attribute of Group
(X03):
1... ....
Group-Usage National
.1.. ....
Unbounded length group
784 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 126. SYSADATA symbol record (continued)
Field Size Description
Data flags 5 XL1 OCCURS flags:
1... ....
UNBOUNDED
| Base locator Cell FL2 Base locator cell number
| Symbol Identifier FL4 Number identifying the symbol
Structure AL4 Offset of symbol within structure. This offset is set to 0
displacement for variably located items.
Parent displacement AL4 Byte offset from immediate parent of the item being
defined.
Parent ID FL4 The symbol ID of the immediate parent of the item being
defined.
Redefined ID FL4 The symbol ID of the data item that this item redefines,
if applicable.
Start-renamed ID FL4 If this item is a level-66 item, the symbol ID of the
starting COBOL data item that this item renames. If not a
level-66 item, this field is set to 0.
End-renamed ID FL4 If this item is a level-66 item, the symbol ID of the
ending COBOL data item that this item renames. If not a
level-66 item, this field is set to 0.
Program-name FL4 ID of the program-name of the program or the
symbol ID class-name of the class where this symbol is defined.
OCCURS minimum FL4 Minimum value for OCCURS
Paragraph ID Proc-name ID for a paragraph-name
OCCURS maximum FL4 Maximum value for OCCURS
Section ID Proc-name ID for a section-name
Dimensions FL4 Number of dimensions
Case bit vector XL4 The case of the characters in the symbol name is
represented with one bit per character. Each bit has the
following meaning:
0 Uppercase
1 Lowercase
Bit 0 represents the case of the first character, bit 1
represents the case of the second character, and so forth.
Reserved CL8 Reserved for future use
Value pairs count HL2 Count of value pairs
Symbol name length HL2 Number of characters in the symbol name
Appendix F. COBOL SYSADATA file contents 785
Table 126. SYSADATA symbol record (continued)
Field Size Description
Picture data length HL2 Number of characters in the picture data; zero if symbol
for data-name has no associated PICTURE clause. (Length of the PICTURE
field.) Length represents the field as it is found in the
or source input. This length does not represent the
expanded field for PICTURE items that contain a
Assignment-name replication factor. The maximum COBOL length for a
length for file-name PICTURE string is 50 bytes. Zero in this field indicates no
PICTURE specified.
Number of characters in the external file-name if this is a
file-name. This is the DD name part of the
assignment-name. Zero if file-name and ASSIGN USING
specified.
Initial Value length HL2 Number of characters in the symbol value; zero if
for data-name symbol has no initial value
External class-name Number of characters in the external class-name for
length for CLASS-ID CLASS-ID
ODO symbol name FL4 If data-name, ID of the ODO symbol name; zero if ODO
ID for data-name not specified
ID of ASSIGN If file-name, Symbol-ID for ASSIGN USING data-name; zero
data-name if if ASSIGN TO specified
file-name
Keys count HL2 The number of keys defined
Index count HL2 Count of Index symbol IDs; zero if none specified
Symbol name CL(n)
Picture data string for CL(n) The PICTURE character string exactly as the user types it
data-name in. The character string includes all symbols, parentheses,
and replication factor.
or
The external file-name if this is a file-name. This is the DD
Assignment-name for name part of the assignment-name.
file-name
Index ID list (n)FL4 ID of each index symbol name
Keys (n)XL8 This field contains data describing keys specified for an
array. The following three fields are repeated as many
times as specified in the 'Keys count' field.
...Key Sequence FL1 Ascending or descending indicator.
X00 DESCENDING
X01 ASCENDING
...Filler CL3 Reserved
...Key ID FL4 The symbol ID of the data item that is the key field in
the array
Initial Value data for CL(n) This field contains the data specified in the INITIAL
data-name VALUE clause for this symbol. The following four
subfields are repeated according to the count in the
'Value pairs count' field. The total length of the data in
this field is contained in the 'Initial value length' field.
External class-name
for CLASS-ID The external class-name for CLASS-ID.
...1st value length HL2 Length of first value
786 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 126. SYSADATA symbol record (continued)
Field Size Description
...1st value data CL(n) 1st value.
This field contains the literal (or figurative constant) as it
is specified in the VALUE clause in the source file. It
includes any beginning and ending delimiters, embedded
quotation marks, and SHIFT IN and SHIFT OUT
characters. If the literal spans multiple lines, the lines are
concatenated into one long string. If a figurative constant
is specified, this field contains the actual reserved word,
not the value associated with that word.
...2nd value length HL2 Length of second value, zero if not a THRU value pair
...2nd value data CL(n) 2nd value.
This field contains the literal (or figurative constant) as it
is specified in the VALUE clause in the source file. It
includes any beginning and ending delimiters, embedded
quotation marks, and SHIFT IN and SHIFT OUT
characters. If the literal spans multiple lines, the lines are
concatenated into one long string. If a figurative constant
is specified, this field contains the actual reserved word,
not the value associated with that word.
Symbol cross-reference record: X'0044'
The following table shows the contents of the symbol cross-reference record.
Table 127. SYSADATA symbol cross-reference record
Field Size Description
Symbol length HL2 The length of the symbol
Statement definition FL4 The statement number where the symbol is defined or
declared
For VERB XREF only:
Verb count - total number of references to this verb.
Number of HL2 The number of references in this record to the symbol
references1 following
Cross-reference type XL1
X'01' Program
X'02' Procedure
X'03' Verb
X'04' Symbol or data-name
X'05' Method
X'06' Class
Reserved CL7 Reserved for future use
Symbol name CL(n) The symbol. Variable length.
Appendix F. COBOL SYSADATA file contents 787
Table 127. SYSADATA symbol cross-reference record (continued)
Field Size Description
...Reference flag CL1 For symbol or data-name references:
C' ' Blank means reference only
C'M' Modification reference flag
For Procedure type symbol references:
C'A' ALTER (procedure-name)
C'D' GO TO (procedure-name) DEPENDING ON
C'E' End of range of (PERFORM) through
(procedure-name)
C'G' GO TO (procedure-name)
C'P' PERFORM (procedure-name)
C'T' (ALTER) TO PROCEED TO (procedure-name)
C'U' Use for debugging (procedure-name)
...Statement number XL4 The statement number on which the symbol or verb is
referenced
1. The reference flag field and the statement number field occur as many times as the
number of references field dictates. For example, if there is a value of 10 in the number
of references field, there will be 10 occurrences of the reference flag and statement
number pair for data-name, procedure, or program symbols, or 10 occurrences of the
statement number for verbs.
Where the number of references would exceed the record size for the SYSADATA file,
the record is continued on the next record. The continuation flag is set in the common
header section of the record.
Nested program record: X'0046'
The following table shows the contents of the nested program record.
Table 128. SYSADATA nested program record
Field Size Description
Statement definition FL4 The statement number where the symbol is defined or
declared
Nesting level XL1 Program nesting level
Program attributes XL1
1... ....
Initial
.1.. ....
Common
..1. ....
PROCEDURE DIVISION using
...1 1111
Reserved for future use
Reserved XL1 Reserved for future use
Program-name length XL1 Length of the following field
Program-name CL(n) The program-name
788 Enterprise COBOL for z/OS, V5.2 Programming Guide
Library record: X'0060'
The following table shows the contents of the SYSADATA library record.
Table 129. SYSADATA library record
Field Size Description
1
Number of members HL2 Count of the number of COPY/INCLUDE code members
described in this record
Library name length HL2 The length of the library name
Library volume HL2 The length of the library volume ID
length
Concatenation XL2 Concatenation number of the library
number
Library ddname HL2 The length of the library ddname
length
Reserved CL4 Reserved for future use
Library name CL(n) The name of the library from which the COPY/INCLUDE
member was retrieved
Library volume CL(n) The volume identification of the volume where the
library resides
Library ddname CL(n) The ddname (or equivalent) used for this library
...COPY/BASIS member HL2 The library file ID of the name following
file ID2
...COPY/BASIS name HL2 The length of the name following
length
...COPY/BASIS name CL(n) The name of the COPY/BASIS member that has been used
1. If 10 COPY members are retrieved from a library, the "Number of members" field will
contain 10 and there will be 10 occurrences of the "COPY/BASIS member file ID" field,
the "COPY/BASIS name length" field, and the "COPY/BASIS name" field.
2. If COPY/BASIS members are retrieved from different libraries, a library record is written
to the SYSADATA file for each unique library.
Statistics record: X'0090'
The following table shows the contents of the statistics record.
Table 130. SYSADATA statistics record
Field Size Description
Source records FL4 The number of source records processed
DATA DIVISION FL4 The number of DATA DIVISION statements processed
statements
PROCEDURE DIVISION FL4 The number of PROCEDURE DIVISION statements processed
statements
Compilation number HL2 Batch compilation number
Error severity XL1 The highest error message severity
Appendix F. COBOL SYSADATA file contents 789
Table 130. SYSADATA statistics record (continued)
Field Size Description
Flags XL1
1... ....
End of Job indicator
.1.. ....
Class definition indicator
..11 1111
Reserved for future use
EOJ severity XL1 The maximum return code for the compile job
Program-name length XL1 The length of the program-name
Program-name CL(n) Program-name
EVENTS record: X'0120'
Events records are included in the ADATA file to provide compatibility with
previous levels of the compiler.
Events records are of the following types:
v Time stamp
v Processor
v File end
v Program
v File ID
v Error
Table 131. SYSADATA EVENTS TIMESTAMP record layout
Field Size Description
Header CL12 Standard ADATA record header
Record length HL2 Length of following EVENTS record data (excluding this
halfword)
EVENTS record type CL12 C'TIMESTAMP'
TIMESTAMP record
Blank separator CL1
Revision level XL1
Blank separator CL1
Date XL8 YYYYMMDD
Hour XL2 HH
Minutes XL2 MI
Seconds XL2 SS
Table 132. SYSADATA EVENTS PROCESSOR record layout
Field Size Description
Header CL12 Standard ADATA record header
Record length HL2 Length of following EVENTS record data (excluding this
halfword)
790 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 132. SYSADATA EVENTS PROCESSOR record layout (continued)
Field Size Description
EVENTS record type CL9 C'PROCESSOR'
PROCESSOR record
Blank separator CL1
Revision level XL1
Blank separator CL1
Output file ID XL1
Blank separator CL1
Line-class indicator XL1
Table 133. SYSADATA EVENTS FILE END record layout
Field Size Description
Header CL12 Standard ADATA record header
Record length HL2 Length of following EVENTS record data (excluding this
halfword)
EVENTS record type CL7 C'FILEEND'
FILE END record
Blank separator CL1
Revision level XL1
Blank separator CL1
Input file ID XL1
Blank separator CL1
Expansion indicator XL1
Table 134. SYSADATA EVENTS PROGRAM record layout
Field Size Description
Header CL12 Standard ADATA record header
Record length HL2 Length of following EVENTS record data (excluding this
halfword)
EVENTS record type CL7 C'PROGRAM'
PROGRAM record
Blank separator CL1
Revision level XL1
Blank separator CL1
Output file ID XL1
Blank separator CL1
Program input record XL1
number
Table 135. SYSADATA EVENTS FILE ID record layout
Field Size Description
Header CL12 Standard ADATA record header
Appendix F. COBOL SYSADATA file contents 791
Table 135. SYSADATA EVENTS FILE ID record layout (continued)
Field Size Description
Record length HL2 Length of following EVENTS record data (excluding this
halfword)
EVENTS record type CL7 C'FILEID'
FILE ID record
Blank separator CL1
Revision level XL1
Blank separator CL1
Input source file ID XL1 File ID of source file
Blank separator CL1
Reference indicator XL1
Blank separator CL1
Source file name H2
length
Blank separator CL1
Source file name CL(n)
Table 136. SYSADATA EVENTS ERROR record layout
Field Size Description
Header CL12 Standard ADATA record header
Record length HL2 Length of following EVENTS record data (excluding this
halfword)
EVENTS record type CL5 C'ERROR'
ERROR record
Blank separator CL1
Revision level XL1
Blank separator CL1
Input source file ID XL1 File ID of source file
Blank separator CL1
Annot class XL1 Annot-class message placement
Blank separator CL1
Error input record XL10
number
Blank separator CL1
Error start line XL10
number
Blank separator CL1
Error token start XL1 Column number of error token start
number
Blank separator CL1
Error end line XL10
number
Blank separator CL1
792 Enterprise COBOL for z/OS, V5.2 Programming Guide
Table 136. SYSADATA EVENTS ERROR record layout (continued)
Field Size Description
Error token end XL1 Column number of error token end
number
Blank separator CL1
Error message ID XL9
number
Blank separator CL1
Error message XL1
severity code
Blank separator CL1
Error message XL2
severity level number
Blank separator CL1
Error message length HL3
Blank separator CL1
Error message text CL(n)
Appendix F. COBOL SYSADATA file contents 793
794 Enterprise COBOL for z/OS, V5.2 Programming Guide
Appendix G. Using sample programs
The sample programs, which are included on your product tape, demonstrate
many language elements and concepts of COBOL.
This information contains the following items:
v Overview of the programs, including program charts for two of the samples
v Format and sample of the input data
v Sample of reports produced
v Information about how to run the programs
v List of the language elements and concepts that are illustrated
Pseudocode and other comments about the programs are included in the program
prolog, which you can obtain in a program listing.
There are three sample programs:
v IGYTCARA is an example of using QSAM files and VSAM indexed files, and
shows how to use many COBOL intrinsic functions.
v IGYTCARB is an example of using IBM Interactive System Product Facility
(ISPF).
v IGYTSALE is an example of using several of the features of the Language
Environment callable services.
RELATED CONCEPTS
IGYTCARA: batch application
IGYTCARB: interactive program on page 799
IGYTSALE: nested program application on page 802
IGYTCARA: batch application
A company that has several local offices wants to establish employee carpools.
Application IGYTCARA validates the transaction-file entries (QSAM sequential file
processing) and updates a master file (VSAM indexed file processing).
This batch application does two tasks:
v Produces reports of employees who can share rides from the same home
location to the same work location
v Updates the carpool data:
Adds data for new employees
Changes information for participating employees
Deletes employee records
Lists update requests that are not valid
The following diagram shows the parts of the application and how they are
organized:
Copyright IBM Corp. 1991, 2015 795
RELATED TASKS
Preparing to run IGYTCARA on page 798
RELATED REFERENCES
Input data for IGYTCARA
Report produced by IGYTCARA on page 797
Language elements and concepts that are illustrated on page 809
Input data for IGYTCARA
As input to the program, the company collected information from interested
employees, coded the information, and produced an input file. Here is an example
of the format of the input file (spaces between fields are left out, as they would be
in your input file) with an explanation of each item.
1. Transaction code
2. Shift
3. Home code
796 Enterprise COBOL for z/OS, V5.2 Programming Guide
4. Work code
5. Commuter name
6. Home address
7. Home phone
8. Work phone
9. Home location code
10. Work location code
11. Driving status code
This sample below shows a section of the input file:
A10111ROBERTS AB1021 CRYSTAL COURTSAN FRANCISCOCA9990141555501904155551387H1W1D
A20212KAHN DE789 EMILY LANE SAN FRANCISCOCA9992141555518904155552589H2W2D
P48899 99ASDFG0005557890123ASDFGHJ T
R10111ROBERTS AB1221 CRYSTAL COURTSAN FRANCISCOCA9990141555501904155551387H1W1D
A20212KAHN DE789 EMILY LANE SAN FRANCISCOCA9992141555518904155552589H2W2D
D20212KAHN DE
D20212KAHN DE
A20212KAHN DE789 EMILY LANE SAN FRANCISCOCA9992141555518904155552589H2W2D
A10111BONNICK FD1025 FIFTH AVENUE SAN FRANCISCOCA9990541555595904155557895H8W3
A10111PETERSON SW435 THIRD AVENUE SAN FRANCISCOCA9990541555546904155553717H3W4
. . .
Report produced by IGYTCARA
The following sample shows the first page of the output report produced by
IGYTCARA. Your actual output might vary slightly in appearance, depending on
your system.
1REPORT #: IGYTCAR1 COMMUTER FILE UPDATE LIST PAGE #: 1
-PROGRAM #: IGYTCAR1 RUN TIME: 01:40 RUN DATE: 11/24/2003
-========================================================================================================================
| RE-| SHIFT | | | | |STA-|
TRANS|CORD|HOME CODE| COMMUTER | HOME | HOME PHONE | HOME LOCATION JUNCTION |TUS | TRANS. ERROR
CODE |TYPE|WORK CODE| NAME | ADDRESS | WORK PHONE | WORK LOCATION JUNCTION |CODE|
========================================================================================================================
A NEW 1 01 11 ROBERTS AB 1021 CRYSTAL COURT (415) 555-0190 RODNEY/CRYSTAL D
SAN FRANCISCO CA 99901 (415) 555-1387 BAYFAIR PLAZA
------------------------------------------------------------------------------------------------------------------------
A NEW 2 02 12 KAHN DE 789 EMILY LANE (415) 555-1890 COYOTE D
SAN FRANCISCO CA 99921 (415) 555-2589 14TH STREET/166TH AVENUE
------------------------------------------------------------------------------------------------------------------------
P 4 88 99 (000) 555-7890 HOME CODE NOT FOUND. T
99 ASDFG (123) ASD-FGHJ WORK CODE NOT FOUND. TRANSACT. CODE
SHIFT CODE
HOME LOC. CODE
WORK LOC. CODE
LAST NAME
INITIALS
ADDRESS
CITY
STATE CODE
ZIPCODE
HOME PHONE
WORK PHONE
HOME JUNCTION
WORK JUNCTION
DRIVING STATUS
------------------------------------------------------------------------------------------------------------------------
R OLD 1 01 11 ROBERTS AB 1021 CRYSTAL COURT (415) 555-0190 RODNEY/CRYSTAL D
SAN FRANCISCO CA 99901 (415) 555-1387 BAYFAIR PLAZA
NEW 1 01 11 ROBERTS AB 1221 CRYSTAL COURT (415) 555-0190 RODNEY/CRYSTAL D
SAN FRANCISCO CA 99901 (415) 555-1387 BAYFAIR PLAZA
------------------------------------------------------------------------------------------------------------------------
A 2 02 12 KAHN DE 789 EMILY LANE (415) 555-1890 COYOTE D
SAN FRANCISCO CA 99921 (415) 555-2589 14TH STREET/166TH AVENUE DUPLICATE REC.
------------------------------------------------------------------------------------------------------------------------
D OLD 2 02 12 KAHN DE 789 EMILY LANE (415) 555-1890 COYOTE D
SAN FRANCISCO CA 99921 (415) 555-2589 14TH STREET/166TH AVENUE
------------------------------------------------------------------------------------------------------------------------
D 2 02 12 KAHN DE REC. NOT FOUND
------------------------------------------------------------------------------------------------------------------------
A NEW 2 02 12 KAHN DE 789 EMILY LANE (415) 555-1890 COYOTE D
SAN FRANCISCO CA 99921 (415) 555-2589 14TH STREET/166TH AVENUE
------------------------------------------------------------------------------------------------------------------------
A NEW 1 01 11 BONNICK FD 1025 FIFTH AVENUE (415) 555-9590 RODNEY
SAN FRANCISCO CA 99905 (415) 555-7895 17TH FREEWAY SAN LEANDRO
------------------------------------------------------------------------------------------------------------------------
A NEW 1 01 11 PETERSON SW 435 THIRD AVENUE (415) 555-4690 RODNEY/THIRD AVENUE
Appendix G. Using sample programs 797
Preparing to run IGYTCARA
All files required by the IGYTCARA program (IGYTCARA, IGYTCODE, and
IGYTRANX) are supplied on the product installation tape. These files are located
in the IGY.V5R1M0.SIGYSAMP data set.
Data-set and procedure names might be changed at installation time. Check with
your system programmer to verify these names.
Do not change these options on the CBL statement in the source file for
IGYTCARA:
v NOADV
v NODYNAM
v NONAME
v NONUMBER
v QUOTE
v SEQUENCE
With these options in effect, the program will not cause any diagnostic messages to
be issued. You can use the sequence number string in the source file to search for
the language elements used.
RELATED CONCEPTS
IGYTCARA: batch application on page 795
RELATED TASKS
Running IGYTCARA
RELATED REFERENCES
Input data for IGYTCARA on page 796
Report produced by IGYTCARA on page 797
Language elements and concepts that are illustrated on page 809
Running IGYTCARA
The following procedure compiles, link-edits, and runs the IGYTCARA program. If
you want only to compile or only to compile and link-edit the program, you must
change the IGYWCLG cataloged procedure.
To run IGYTCARA under z/OS, use JCL to define a VSAM cluster and compile the
program. Insert the information specific to your system and installation
(accounting information, volume serial number, unit name, cluster prefix) in the
fields that are shown in lowercase letters. These examples use the name
IGYTCAR.MASTFILE; you can use another name if you want to.
1. Use this JCL to create the required VSAM cluster:
//CREATE JOB (acct-info),IGYTCAR CREATE VSAM,MSGLEVEL=(1,1),
// TIME=(0,29)
//CREATE EXEC PGM=IDCAMS
//VOL1 DD VOL=SER=your-volume-serial,UNIT=your-unit,DISP=SHR
//SYSPRINT DD SYSOUT=A
//SYSIN DD *
DELETE your-prefix.IGYTCAR.MASTFILE -
FILE(VOL1) -
PURGE
DEFINE CLUSTER -
(NAME(your-prefix.IGYTCAR.MASTFILE) -
VOLUME(your-volume-serial) -
FILE(VOL1) -
798 Enterprise COBOL for z/OS, V5.2 Programming Guide
INDEXED -
RECSZ(80 80) -
KEYS(16 0) -
CYLINDERS(2))
/*
To remove any existing cluster, a DELETE is issued before the VSAM cluster is
created.
2. Use the following JCL to compile, link-edit, and run the IGYTCARA program:
//IGYTCARA JOB (acct-info),IGYTCAR,MSGLEVEL=(1,1),TIME=(0,29)
//TEST EXEC IGYWCLG
//COBOL.SYSLIB DD DSN=IGY.V5R1M0.SIGYSAMP,DISP=SHR
//COBOL.SYSIN DD DSN=IGY.V5R1M0.SIGYSAMP(IGYTCARA),DISP=SHR
//GO.SYSOUT DD SYSOUT=A
//GO.COMMUTR DD DSN=your-prefix.IGYTCAR.MASTFILE,DISP=SHR
//GO.LOCCODE DD DSN=IGY.V5R1M0.SIGYSAMP(IGYTCODE),DISP=SHR
//GO.UPDTRANS DD DSN=IGY.V5R1M0.SIGYSAMP(IGYTRANX),DISP=SHR
//GO.UPDPRINT DD SYSOUT=A,DCB=BLKSIZE=133
//
RELATED TASKS
Chapter 10, Processing VSAM files, on page 185
RELATED REFERENCES
Compile, link-edit, and run procedure (IGYWCLG) on page 259
IGYTCARB: interactive program
IGYTCARB contains an interactive program for entering carpool data by using IBM
Interactive System Productivity Facility (ISPF) to invoke Dialog Manager and
Enterprise COBOL. IGYTCARB creates a file that can be used as input for a
carpool listing or matching program such as IGYTCARA.
The input data for IGYTCARB is the same as that for IGYTCARA. IGYTCARB lets
you append to the information in your input file by using an ISPF panel. An
example of the panel used by IGYTCARB is shown below:
--------------------------- CARPOOL DATA ENTRY -------------------------------
New Data Entry Previous Entry
Type =======> - A, R, or D A
Shift ======> - 1, 2, or 3 1
Home Code ==> -- 2 Chars 01
Work Code ==> -- 2 Chars 11
Name =======> --------- 9 Chars POPOWICH
Initials ===> -- 2 Chars AD
Address ====> ------------------ 18 Chars 134 SIXTH AVENUE
City =======> ------------- 13 Chars SAN FRANCISCO
State ======> -- 2 Chars CA
Zip Code ===> ----- 5 Chars 99903
Home Phone => ---------- 10 Chars 4155553390
Work Phone => ---------- 10 Chars 4155557855
Home Jnc code > -- 2 Chars H3
Work Jnc Code > -- 2 Chars W7
Commuter Stat > - D, R or blank
RELATED TASKS
Preparing to run IGYTCARB on page 800
Appendix G. Using sample programs 799
Preparing to run IGYTCARB
Run the IGYTCARB program under Interactive System Productivity Facility (ISPF).
All files required by IGYTCARB (IGYTCARB, IGYTRANB, and IGYTPNL) are
supplied on the product installation tape in the IGY.V5R1M0.SIGYSAMP data set.
Data-set names and procedure-names might be changed at installation time. Check
with your system programmer to verify the names.
Do not change the following options in the CBL statement in the source file for
IGYTCARB:
v NONUMBER
v QUOTE
v SEQUENCE
With these options in effect, the program will not cause any diagnostic messages to
be issued. You can use the sequence number string in the source file to search for
language elements.
RELATED CONCEPTS
IGYTCARB: interactive program on page 799
RELATED TASKS
Running IGYTCARB
RELATED REFERENCES
Language elements and concepts that are illustrated on page 809
Running IGYTCARB
The following procedure compiles, link-edits, and runs the IGYTCARB program. If
you want only to compile or only to compile and link-edit the program, you must
change the procedure.
To run IGYTCARB under z/OS, do the following steps:
1. Using the ISPF editor, change the ISPF/PDF Primary Option Panel (ISR@PRIM)
or some other panel to include the IGYTCARB invocation. Panel ISR@PRIM is
in your site's PDF panel data set (normally ISRPLIB).
The following example shows an ISR@PRIM panel modified, in two identified
locations, to include the IGYTCARB invocation. If you add or change an option
in the upper portion of the panel definition, you must also add or change the
corresponding line on the lower portion of the panel.
%---------------------- ISPF/PDF PRIMARY OPTION PANEL ------------------------
%OPTION ===>_ZCMD +
% +USERID - &ZUSER
% 0 +ISPF PARMS - Specify terminal and user parameters +TIME - &ZTIME
% 1 +BROWSE - Display source data or output listings +TERMINAL - &ZTERM
% 2 +EDIT - Create or change source data +PF KEYS - &ZKEYS
% 3 +UTILITIES - Perform utility functions
% 4 +FOREGROUND - Invoke language processors in foreground
% 5 +BATCH - Submit to batch for language processing
% 6 +COMMAND - Enter TSO or Workstation commands
% 7 +DIALOG TEST - Perform dialog testing
% 8 +LM UTILITIES- Perform library management utility functions
% C +IGYTCARB - Run IGYTCARB UPDATE TRANSACTION PROGRAM (1)
% T +TUTORIAL - Display information about ISPF/PDF
% X +EXIT - Terminate using console, log, and list defaults
%
%
800 Enterprise COBOL for z/OS, V5.2 Programming Guide
+Enter%END+command to terminate ISPF.
%
)INIT
.HELP = ISR00003
&ZPRIM = YES /* ALWAYS A PRIMARY OPTION MENU */
&ZHTOP = ISR00003 /* TUTORIAL TABLE OF CONTENTS */
&ZHINDEX = ISR91000 /* TUTORIAL INDEX - 1ST PAGE */
VPUT (ZHTOP,ZHINDEX) PROFILE
)PROC
&Z1 = TRUNC(&ZCMD,1)
IF (&Z1 ¬sym.= .)
&ZSEL = TRANS( TRUNC (&ZCMD,.)
0,PANEL(ISPOPTA)
1,PGM(ISRBRO) PARM(ISRBRO01)
2,PGM(ISREDIT) PARM(P,ISREDM01)
3,PANEL(ISRUTIL)
4,PANEL(ISRFPA)
5,PGM(ISRJB1) PARM(ISRJPA) NOCHECK
6,PGM(ISRPCC)
7,PGM(ISRYXDR) NOCHECK
8,PANEL(ISRLPRIM)
C,PGM(IGYTCARB) (2)
T,PGM(ISPTUTOR) PARM(ISR00000)
,
X,EXIT
*,? )
&ZTRAIL = .TRAIL
IF (&Z1 = .) .msg = ISPD141
)END
As indicated by (1) in this example, you add IGYTCARB to the upper portion
of the panel by entering:
% C +IGYTCARB - Run IGYTCARB UPDATE TRANSACTION PROGRAM
You add the corresponding line on the lower portion of the panel, indicated by
(2), by entering:
C,PGM(IGYTCARB)
2. Place ISR@PRIM (or your other modified panel) and IGYTPNL in a library and
make this library the first library in the ISPPLIB concatenation.
3. Comment sequence line IB2200 and uncomment sequence line IB2210 in
IGYTCARB. (The OPEN EXTEND verb is supported under z/OS.)
| 4. Compile and link-edit IGYTCARB and place the resulting program object in
your LOADLIB.
5. Allocate ISPLLIB by using the following command:
ALLOCATE FILE(ISPLLIB) DATASET(DSN1, SYS1.COBLIB, DSN2) SHR REUSE
Here DSN1 is the library name of the LOADLIB from step 4. DSN2 is your
installed ISPLLIB.
6. Allocate the input and output data sets by using the following command:
ALLOCATE FILE(UPDTRANS) DA(IGY.V5R1M0.SIGYSAMP(IGYTRANB)) SHR REUSE
7. Allocate ISPPLIB by using the following command:
ALLOCATE FILE(ISPPLIB) DATASET(DSN3, DSN4) SHR REUSE
Here DSN3 is the library containing the modified panels. DSN4 is the ISPF panel
library.
8. Invoke IGYTCARB by using your modified panel.
RELATED REFERENCES
ISPF Dialog Developer's Guide and Reference
Appendix G. Using sample programs 801
IGYTSALE: nested program application
Application IGYTSALE tracks product sales and sales commissions for a
sporting-goods distributor.
This nested program application does the following tasks:
1. Keeps a record of the product line, customers, and number of salespeople. This
data is stored in a file called IGYTABLE.
2. Maintains a file that records valid transactions and transaction errors. All
transactions that are not valid are flagged, and the results are printed in a
report. Transactions to be processed are in a file called IGYTRANA.
3. Processes transactions and report sales by location.
4. Records an individual's sales performance and commission, and prints the
results in a report.
5. Reports the sale and shipment dates in local time and UTC (Universal Time
Coordinate), and calculates the response time.
The following diagram shows the parts of the application as a hierarchy:
The following diagram shows how the parts are nested:
802 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED TASKS
Preparing to run IGYTSALE on page 808
RELATED REFERENCES
Input data for IGYTSALE
Reports produced by IGYTSALE on page 805
Language elements and concepts that are illustrated on page 809
Input data for IGYTSALE
As input to our program, the distributor collected information about its customers,
salespeople, and products, coded the information, and produced an input file.
This input file, called IGYTABLE, is loaded into three separate tables for use
during transaction processing. The format of the file is as follows, with an
explanation of the items below:
1. Record type
2. Customer code
3. Customer name
4. Product code
Appendix G. Using sample programs 803
5. Product description
6. Product unit price
7. Salesperson number
8. Salesperson name
9. Date of hire
10. Commission rate
The value of field 1 (C, P, or S) determines the format of the input record. The
following sample shows a section of IGYTABLE:
S1111Edyth Phillips 062484042327
S1122Chuck Morgan 052780084425
S1133Art Tung 022882061728
S1144Billy Jim Bob 010272121150
S1155Chris Preston 122083053377
S1166Al Willie Roz 111276100000
P01Footballs 0000620
P02Football Equipment 0032080
P03Football Uniform 0004910
P04Basketballs 0002220
P05Basketball Rim/Board0008830
P06Basketball Uniform 0004220
C01L. A. Sports
C02Gear Up
C03Play Outdoors
C04Sports 4 You
C05Sports R US
C06Stay Active
C07Sport Shop
C08Stay Sporty
C09Hot Sports
C10The Sportsman
C11Playing Ball
C12Sports Play
. . .
In addition, the distributor collected information about sales transactions. Each
transaction represents an individual salesperson's sales to a particular customer.
The customer can purchase from one to five items during each transaction. The
transaction information is coded and put into an input file, called IGYTRANA. The
format of this file is as follows, with an explanation of the items below:
1. Sales order number
2. Invoiced items (number of different items ordered)
3. Date of sale (year month day hour minutes seconds)
4. Sales area
5. Salesperson number
6. Customer code
7. Date of shipment (year month day hour minutes seconds)
8. Product code
9. Quantity sold
804 Enterprise COBOL for z/OS, V5.2 Programming Guide
Fields 8 and 9 occur one to eight times depending on the number of different items
ordered (field 2). The following sample shows a section of IGYTRANA:
A00001119900227010101CNTRL VALLEY11442019900228259999
A00004119900310100530CNTRL VALLEY11441019900403150099
A00005119900418222409CNTRL VALLEY11441219900419059900
A00006119900523151010CNTRL VALLEY11442019900623250004
419990324591515SAN DIEGO 11615 60200132200110522045100
B11114419901111003301SAN DIEGO 11661519901114260200132200110522041100
A00007119901115003205CNTRL VALLEY11332019901117120023
C00125419900118101527SF BAY AREA 11331519900120160200112200250522145111
B11116419901201132013SF BAY AREA 11331519901203060200102200110522045102
B11117319901201070833SAN Diego 1165661990120333020o132200120522041100
B11118419901221191544SAN DIEGO 11661419901223160200142200130522040300
B11119419901210211544SAN DIEGO 11221219901214060200152200160522050500
B11120419901212000816SAN DIEGO 11220419901213150200052200160522040100
B11121419901201131544SAN DIEGO 11330219901203120200112200140522250100
B11122419901112073312SAN DIEGO 11221019901113100200162200260522250100
B11123919901110123314SAN DIEGO 11660919901114260200270500110522250100140010
B11124219901313510000SAN DIEGO 116611 1 0200042200120a22141100
B11125419901215012510SAN DIEGO 11661519901216110200162200130522141111
B11126119901111000034SAN DIEGO 11331619901113260022
B11127119901110154100SAN DIEGO 11221219901113122000
B11128419901110175001SAN DIEGO 11661519901113260200132200160521041104
. . .
Reports produced by IGYTSALE
The figures referenced below are samples of IGYTSALE output.
The program records the following data in reports:
v Transaction errors
v Sales by product and area
v Individual sales performance and commissions
v Response time between the sale date and the date the sold products are shipped
Your output might vary slightly in appearance, depending on your system.
Example: IGYTSALE transaction errors
Example: IGYTSALE sales analysis by product by area on page 806
Example: IGYTSALE sales and commissions on page 807
Example: IGYTSALE response time from sale to ship on page 807
Example: IGYTSALE transaction errors
The following sample of IGYTSALE output shows transaction errors in the last
column.
Day of Report: Tuesday C O B O L S P O R T S 11/24/2003 03:12 Page: 1
Invalid Edited Transactions
Sales Inv. Sales Sales Sales Cust. Product And Quantity Sold Ship
Order Items Time Stamp Area Pers Code Date Stamp
----- ----- -------------- ----------- ----- ----- ------------------------- ------------
4 19990324591515 SAN DIEGO 116 15 60200132200110522045100 Error Descriptions
-Sales order number is missing
-Date of sale time stamp is invalid
-Salesperson number not numeric
-Product code not in product-table
-Date of ship time stamp is invalid
B11117 3 19901201070833 SAN Diego 1165 66 33020o132200120522041100 19901203 Error Descriptions
-Sales area not in area-table
-Salesperson not in sales-per-table
-Customer code not in customer-table
-Product code not in product-table
-Quantity sold not numeric
B11123 9 19901110123314 SAN DIEGO 1166 09 260200270500110522250100140010 19901114 Error Descriptions
-Invoiced items is invalid
-Product and quantity not checked
-Date of ship time stamp is invalid
B11124 2 19901313510000 SAN DIEGO 1166 11 1 0200042200120a22141100 Error Descriptions
-Date of sale time stamp is invalid
-Product code is invalid
-Date of ship time stamp is invalid
133 81119110000 LOS ANGELES 1166 10 040112110210160321251104 Error Descriptions
Appendix G. Using sample programs 805
-Sales order number is invalid
-Invoiced items is invalid
-Date of sale time stamp is invalid
-Product and quantity not checked
-Date of ship time stamp is invalid
C11133 4 1990111944 1166 10 040112110210160321251104 Error Descriptions
-Date of sale time stamp is invalid
-Sales area is missing
-Date of ship time stamp is invalid
C11138 4 19901117091530 LOS ANGELES 1155 113200102010260321250004 19901119 Error Descriptions
-Customer code is invalid
D00009 9 19901201222222 CNTRL COAST 115 19 141 1131221 19901202 Error Descriptions
-Invoiced items is invalid
Example: IGYTSALE sales analysis by product by area
The following sample of IGYTSALE output shows sales by product and area.
Day of Report: Tuesday C O B O L S P O R T S 11/24/2003 03:12 Page: 1
Sales Analysis By Product By Area
Areas of Sale
| | CNTRL COAST | CNTRL VALLEY | LOS ANGELES | NORTH COAST | SAN DIEGO | SF BAY AREA | |
| Product Codes | | | | | | | Product Totals |
==================================================================================================================================
|Product Number 04 | | | | | | | |
|Basketballs | | | | | | | |
| Units Sold | | | 433 | | 2604 | 5102 | 8139 |
| Unit Price | | | 22.20 | | 22.20 | 22.20 | |
| Amount of Sale | | | $9,612.60 | | $57,808.80 | $113,264.40 | $180,685.80 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 05 | | | | | | | |
|Basketball Rim/Board| | | | | | | |
| Units Sold | | 9900 | 2120 | 11 | 2700 | | 14731 |
| Unit Price | | 88.30 | 88.30 | 88.30 | 88.30 | | |
| Amount of Sale | | $874,170.00 | $187,196.00 | $971.30 | $238,410.00 | | $1,300,747.30 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 06 | | | | | | | |
|Basketball Uniform | | | | | | | |
| Units Sold | | | | 990 | 200 | 200 | 1390 |
| Unit Price | | | | 42.20 | 42.20 | 42.20 | |
| Amount of Sale | | | | $41,778.00 | $8,440.00 | $8,440.00 | $58,658.00 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 10 | | | | | | | |
|Baseball Cage | | | | | | | |
| Units Sold | 45 | | 3450 | 16 | 200 | 3320 | 7031 |
| Unit Price | 890.00 | | 890.00 | 890.00 | 890.00 | 890.00 | |
| Amount of Sale | $40,050.00 | |$3,070,500.00 | $14,240.00 | $178,000.00 |$2,954,800.00 | $6,257,590.00 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 11 | | | | | | | |
|Baseball Uniform | | | | | | | |
| Units Sold | 10003 | | 3578 | | 2922 | 2746 | 19249 |
| Unit Price | 45.70 | | 45.70 | | 45.70 | 45.70 | |
| Amount of Sale | $457,137.10 | | $163,514.60 | | $133,535.40 | $125,492.20 | $879,679.30 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 12 | | | | | | | |
|Softballs | | | | | | | |
| Units Sold | 10 | 137 | 2564 | 13 | 2200 | 22 | 4946 |
| Unit Price | 1.40 | 1.40 | 1.40 | 1.40 | 1.40 | 1.40 | |
| Amount of Sale | $14.00 | $191.80 | $3,589.60 | $18.20 | $3,080.00 | $30.80 | $6,924.40 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 13 | | | | | | | |
|Softball Bats | | | | | | | |
| Units Sold | 3227 | | 3300 | 1998 | 5444 | 99 | 14068 |
| Unit Price | 12.60 | | 12.60 | 12.60 | 12.60 | 12.60 | |
| Amount of Sale | $40,660.20 | | $41,580.00 | $25,174.80 | $68,594.40 | $1,247.40 | $177,256.80 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 14 | | | | | | | |
|Softball Gloves | | | | | | | |
| Units Sold | 1155 | | 136 | 3119 | 3833 | 5152 | 13395 |
| Unit Price | 12.00 | | 12.00 | 12.00 | 12.00 | 12.00 | |
| Amount of Sale | $13,860.00 | | $1,632.00 | $37,428.00 | $45,996.00 | $61,824.00 | $160,740.00 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 15 | | | | | | | |
|Softball Cage | | | | | | | |
| Units Sold | 997 | 99 | 2000 | | 2400 | | 5496 |
| Unit Price | 890.00 | 890.00 | 890.00 | | 890.00 | | |
| Amount of Sale | $887,330.00 | $88,110.00 |$1,780,000.00 | |$2,136,000.00 | | $4,891,440.00 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 16 | | | | | | | |
|Softball Uniform | | | | | | | |
| Units Sold | 44 | | 465 | 16 | 6165 | 200 | 6890 |
| Unit Price | 45.70 | | 45.70 | 45.70 | 45.70 | 45.70 | |
| Amount of Sale | $2,010.80 | | $21,250.50 | $731.20 | $281,740.50 | $9,140.00 | $314,873.00 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 25 | | | | | | | |
|RacketBalls | | | | | | | |
| Units Sold | 1001 | 10003 | 1108 | 8989 | 200 | 522 | 21823 |
| Unit Price | 0.60 | 0.60 | 0.60 | 0.60 | 0.60 | 0.60 | |
| Amount of Sale | $600.60 | $6,001.80 | $664.80 | $5,393.40 | $120.00 | $313.20 | $13,093.80 |
----------------------------------------------------------------------------------------------------------------------------------
|Product Number 26 | | | | | | | |
|Racketball Rackets | | | | | | | |
| Units Sold | 21 | | 862 | 194 | 944 | 31 | 2052 |
| Unit Price | 12.70 | | 12.70 | 12.70 | 12.70 | 12.70 | |
| Amount of Sale | $266.70 | | $10,947.40 | $2,463.80 | $11,988.80 | $393.70 | $26,060.40 |
----------------------------------------------------------------------------------------------------------------------------------
==================================================================================================================================
| Total Units Sold | 16503 | 20139 | 20016 | 15346 | 29812 | 17394 * 119210 *
| Total Sales |$1,441,929.40 | $968,473.60 |$5,290,487.50 | $128,198.70 |$3,163,713.90 |$3,274,945.70 * $14,267,748.80 *
806 Enterprise COBOL for z/OS, V5.2 Programming Guide
Example: IGYTSALE sales and commissions
The following sample of IGYTSALE output shows sales performance and
commissions by salesperson.
Day of Report: Tuesday C O B O L S P O R T S 11/24/2003 03:12 Page: 1
Sales and Commission Report
Salesperson: Billy Jim Bob
Customers: Number of Products Total for Discount Discount Commission
Orders Ordered Order (if any) Amount Earned
-------------------- --------- -------- -------------- -------- ----------- -----------
Sports Stop 3 10117 $6,161.40 2.25% $138.63 $746.45
The Sportsman 1 99 $88,110.00 5.06% $4,458.36 $10,674.52
Sports Play 1 9900 $874,170.00 7.59% $66,349.50 $105,905.69
--------- -------- -------------- ----------- -----------
Totals: 5 20116 $968,441.40 $70,946.49 $117,326.66
Salesperson: Willie Al Roz
Customers: Number of Products Total for Discount Discount Commission
Orders Ordered Order (if any) Amount Earned
-------------------- --------- -------- -------------- -------- ----------- -----------
Winners Club 4 13998 $1,572,775.90 7.59% $119,373.69 $157,277.59
Winning Sports 1 3222 $48,777.20 3.38% $1,648.66 $4,877.72
The Sportsman 1 1747 $27,415.50 3.38% $926.64 $2,741.55
Play Outdoors 1 2510 $18,579.60 3.38% $627.99 $1,857.96
--------- -------- -------------- ----------- -----------
Totals: 7 21477 $1,667,548.20 $122,576.98 $166,754.82
Salesperson: Art Tung
Customers: Number of Products Total for Discount Discount Commission
Orders Ordered Order (if any) Amount Earned
-------------------- --------- -------- -------------- -------- ----------- -----------
Sports Stop 1 23 $32.20 2.25% $.72 $1.98
Winners Club 2 16057 $2,274,885.00 7.59% $172,663.77 $140,424.10
Gear Up 1 3022 $107,144.00 7.59% $8,132.22 $6,613.78
Sports Club 1 22 $279.40 2.25% $6.28 $17.24
Sports Fans Shop 1 1044 $20,447.30 3.38% $691.11 $1,262.17
L. A. Sports 1 1163 $979,198.10 7.59% $74,321.13 $60,443.94
--------- -------- -------------- ----------- -----------
Totals: 7 21331 $3,381,986.00 $255,815.23 $208,763.21
Salesperson: Chuck Morgan
Customers: Number of Products Total for Discount Discount Commission
Orders Ordered Order (if any) Amount Earned
-------------------- --------- -------- -------------- -------- ----------- -----------
Sports Play 3 7422 $3,817,245.40 7.59% $289,728.92 $322,270.94
Sports 4 You 1 3022 $398,335.40 7.59% $30,233.65 $33,629.46
The Sportsman 1 3022 $285,229.40 7.59% $21,648.91 $24,080.49
Sports 4 Winners 1 1100 $68,509.40 5.06% $3,466.57 $5,783.90
Sports Club 1 12027 $1,324,256.10 7.59% $100,511.03 $111,800.32
--------- -------- -------------- ----------- -----------
Totals: 7 26593 $5,893,575.70 $445,589.08 $497,565.11
Salesperson: Chris Preston
Customers: Number of Products Total for Discount Discount Commission
Orders Ordered Order (if any) Amount Earned
-------------------- --------- -------- -------------- -------- ----------- -----------
Playing Ball 1 5535 $1,939,219.10 7.59% $147,186.72 $103,509.69
Play Sports 1 5675 $225,130.80 7.59% $17,087.42 $12,016.80
Winners Club 1 631 $14,069.70 2.25% $316.56 $750.99
The Jock Shop 1 2332 $28,716.60 3.38% $970.62 $1,532.80
--------- -------- -------------- ----------- -----------
Totals: 4 14173 $2,207,136.20 $165,561.32 $117,810.28
Salesperson: Edyth Phillips
Customers: Number of Products Total for Discount Discount Commission
Orders Ordered Order (if any) Amount Earned
-------------------- --------- -------- -------------- -------- ----------- -----------
Sports Play 2 3575 $92,409.90 5.06% $4,675.94 $3,911.43
Winning Sports 1 11945 $56,651.40 5.06% $2,866.56 $2,397.88
--------- -------- -------------- ----------- -----------
Totals: 3 15520 $149,061.30 $7,542.50 $6,309.31
Grand Totals: 33 119210 $14,267,748.80 $1,068,031.60 $1,114,529.39
Example: IGYTSALE response time from sale to ship
The following sample of IGYTSALE output shows response time between the sale
date in the United States and the date the sold products are shipped to Europe.
Day of Report: Monday COBOL SPORTS 11/24/2003 03:12 Page: 1
Response Time from USA Sale to European Ship
Prod Units Sale Date/Time(PST) Ship Date Ship Response Time
Code Sold YYYYMMDD HHMMSS YYYYMMDD Day Days
---- ----- -------- ------ -------- ---- -------------
25 9999 19900226 010101 19900228 WED .95
15 99 19900310 100530 19900403 TUE 23.57
05 9900 19900418 222409 19900419 THU .06
25 4 19900523 151010 19900623 SAT 30.36
04 1100 19901110 003301 19901114 WED 2.97
12 23 19901114 003205 19901117 SAT 1.97
Appendix G. Using sample programs 807
14 5111 19900118 101527 19900120 SAT 1.57
04 5102 19901201 132013 19901203 MON 1.44
04 300 19901221 191544 19901223 SUN 1.19
05 500 19901210 211544 19901214 FRI 3.11
04 100 19901211 000816 19901213 THU .99
25 100 19901201 131544 19901203 MON 1.44
25 100 19901112 073312 19901113 TUE .68
14 1111 19901214 012510 19901216 SUN .94
26 22 19901110 000034 19901113 TUE 1.99
12 2000 19901110 154100 19901113 TUE 2.34
04 1104 19901110 175001 19901113 TUE 2.25
12 114 19901229 115522 19901230 SUN .50
15 2000 19901110 190113 19901114 WED 3.20
10 1440 19901112 001500 19901115 THU 1.98
25 1104 19901118 120101 19901119 MON .49
25 4 19901118 110030 19901119 MON .54
12 144 19901114 010510 19901119 MON 3.95
14 112 19901119 010101 19901122 THU 1.95
26 321 19901117 173945 19901119 MON 1.26
13 1221 19901101 135133 19901102 FRI .42
10 22 19901029 210000 19901030 TUE .12
14 35 19901130 160500 19901201 SAT .32
11 9005 19901211 050505 19901212 WED .78
06 990 19900511 214409 19900515 TUE 3.09
13 1998 19900712 150100 19900716 MON 3.37
26 31 19901010 185559 19901011 THU .21
14 30 19901210 195500 19901212 WED 1.17
Preparing to run IGYTSALE
All files required by the IGYTSALE program (IGYTSALE, IGYTCRC, IGYTPRC,
IGYTSRC, IGYTABLE, and IGYTRANA) are on the product installation tape in the
IGY.V5R1M0.SIGYSAMP data set.
You can change data-set names and procedure-names at installation time. Check
with your system programmer to verify these names.
Do not change these options in the CBL statement in the source file for IGYTSALE:
v NONUMBER
v SEQUENCE
v NONUMBER
v QUOTE
With these options in effect, the program might not cause any diagnostic messages
to be issued. You can use the sequence number string in the source file to search
for the language elements used.
When you run IGYTSALE, the following messages are printed to the SYSOUT data
set:
Program IGYTSALE Begins
There were 00041 records processed in this program
Program IGYTSALE Normal End
RELATED CONCEPTS
IGYTSALE: nested program application on page 802
RELATED TASKS
Running IGYTSALE on page 809
808 Enterprise COBOL for z/OS, V5.2 Programming Guide
RELATED REFERENCES
Input data for IGYTSALE on page 803
Reports produced by IGYTSALE on page 805
Language elements and concepts that are illustrated
Running IGYTSALE
Use the following JCL to compile, link-edit, and run the IGYTSALE program. If
you want only to compile or only to compile and link-edit the program, change the
IGYWCLG cataloged procedure.
Insert the accounting information for your system or installation in the fields that
are shown in lowercase letters.
//IGYTSALE JOB (acct-info),IGYTSALE,MSGLEVEL=(1,1),TIME=(0,29)
//TEST EXEC IGYWCLG
//COBOL.SYSLIB DD DSN=IGY.V5R1M0.SIGYSAMP,DISP=SHR
//COBOL.SYSIN DD DSN=IGY.V5R1M0.SIGYSAMP(IGYTSALE),DISP=SHR
//GO.SYSOUT DD SYSOUT=A
//GO.IGYTABLE DD DSN=IGY.V5R1M0.SIGYSAMP(IGYTABLE),DISP=SHR
//GO.IGYTRANS DD DSN=IGY.V5R1M0.SIGYSAMP(IGYTRANA),DISP=SHR
//GO.IGYPRINT DD SYSOUT=A,DCB=BLKSIZE=133
//GO.IGYPRT2 DD SYSOUT=A,DCB=BLKSIZE=133
//
Language elements and concepts that are illustrated
The sample programs illustrate several COBOL language elements and concepts.
To find the applicable language element for a sample program, locate the
abbreviation for that program in the sequence string:
Sample program Abbreviation
IGYTCARA IA
IGYTCARB IB
IGYTSALE IS
The following table lists the language elements and programming concepts that the
sample programs illustrate. The language element or concept is described, and the
sequence string is shown. The sequence string is the special character string that
appears in the sequence field of the source file. You can use this string as a search
argument for locating the elements in the listing.
Language element or concept Sequence string
ACCEPT . . . FROM DAY-OF-WEEK IS0900
ACCEPT . . . FROM DATE IS0901
ACCEPT . . . FROM TIME IS0902
ADD . . . TO IS4550
AFTER ADVANCING IS2700
AFTER PAGE IS2600
ALL IS4200
ASSIGN IS1101
AUTHOR IA0040
CALL IS0800
Appendix G. Using sample programs 809
Language element or concept Sequence string
Callable services (Language Environment):
1. CEEDATM: format date or time output 1. IS0875, IS2575
2. CEEDCOD: feedback code check 2. IS0905
3. CEEGMTO: UTC offset from local time 3. IS0904
4. CEELOCT: local date and time 4. IS0850
5. CEESECS: convert time stamp to seconds 5. IS2350, IS2550
CLOSE files IS1900
Comma, semicolon, and space interchangeable IS3500, IS3600
COMMON statement for nested programs IS4600
Complex OCCURS DEPENDING ON IS0700, IS3700
COMPUTE IS4501
COMPUTE ROUNDED IS4500
CONFIGURATION SECTION IA0970
CONFIGURATION SECTION (optional) IS0200
CONTINUE statement IA5310, IA5380
COPY statement IS0500
DATA DIVISION (optional) IS5100
Data validation IA5130-6190
Do-until (PERFORM . . . TEST AFTER) IA4900-5010, IA7690-7770
Do-while (PERFORM . . . TEST BEFORE) IS1660
END-ADD IS2900
END-COMPUTE IS4510
END-EVALUATE IA6590, IS2450
END-IF IS1680
END-MULTIPLY IS3100
END-PERFORM IS1700
END PROGRAM IA9990
END-READ IS1800
END-SEARCH IS3400
ENVIRONMENT DIVISION (optional) IS0200
Error handling, termination of program IA4620, IA5080, IA7800-7980
EVALUATE statement IA6270-6590
EVALUATE . . . ALSO IS2400
EXIT PROGRAM not only statement in paragraph IS2000
Exponentiation IS4500
EXTERNAL clause IS1200
FILE-CONTROL entry for sequential file IA1190-1300
FILE-CONTROL entry for VSAM indexed file IA1070-1180
FILE SECTION (optional) IS0200
FILE STATUS code check IA4600-4630, IA4760-4790
FILLER (optional) IS0400
810 Enterprise COBOL for z/OS, V5.2 Programming Guide
Language element or concept Sequence string
Flags, level-88, definition IA1730-1800, IA2440-2480, IA2710
Flags, level-88, testing IA4430, IA5200-5250
FLOATING POINT IS4400
GLOBAL statement IS0300
INITIAL statement for nested programs IS2300
INITIALIZE IS2500
Initializing a table in the DATA DIVISION IA2920-4260
Inline PERFORM statement IA4410-4520
I-O-CONTROL paragraphs (optional) IS0200
INPUT-OUTPUT SECTION (optional) IS0200
Intrinsic functions:
1. CURRENT-DATE 1. IA9005
2. MAX 2. IA9235
3. MEAN 3. IA9215
4. MEDIAN 4. IA9220
5. MIN 5. IA9240
6. STANDARD-DEVIATION 6. IA9230
7. UPPER-CASE 7. IA9015
8. VARIANCE 8. IA9225
9. WHEN-COMPILED 9. IA9000
IS (optional in all clauses) IS0700
LABEL RECORDS (optional) IS1150
LINKAGE SECTION IS4900
Mixing of indexes and subscripts IS3500
Mnemonic names IA1000
MOVE IS0903
MOVE CORRESPONDING statement IA4810, IA4830
MULTIPLY . . . GIVING IS3000
Nested IF statement, using END-IF IA5460-5830
Nested program IS1000
NEXT SENTENCE IS4300
NOT AT END IS1600
NULL IS4800
OBJECT-COMPUTER (optional) IS0200
OCCURS DEPENDING ON IS0710
ODO uses maximum length for receiving item IS1550
OPEN EXTEND IB2210
OPEN INPUT IS1400
OPEN OUTPUT IS1500
ORGANIZATION (optional) IS1100
Page eject IA7180-7210
Parenthesis in abbreviated conditions IS4850
Appendix G. Using sample programs 811
Language element or concept Sequence string
PERFORM . . . WITH TEST AFTER (Do-until) IA4900-5010, IA7690-7770
PERFORM . . . WITH TEST BEFORE (Do-while) IS1660
PERFORM . . . UNTIL IS5000
PERFORM . . . VARYING statement IA7690-7770
POINTER function IS4700
Print file FD entry IA1570-1620
Print report IA7100-7360
PROCEDURE DIVISION . . . USING IB1320-IB1650
PROGRAM-ID (30 characters allowed) IS0120
READ . . . INTO . . . AT END IS1550
REDEFINES statement IA1940, IA2060, IA2890, IA3320
Reference modification IS2425
Relational operator <= (less than or equal) IS4400
Relational operator >= (greater than or equal) IS2425
Relative subscripting IS4000
REPLACE IS4100
SEARCH statement IS3300
SELECT IS1100
Sequence number can contain any character IA, IB, IS
Sequential file processing IA4480-4510, IA4840-4870
Sequential table search, using PERFORM IA7690-7770
Sequential table search, using SEARCH IA5270-5320, IA5340-5390
SET INDEX IS3200
SET . . . TO TRUE statement IA4390, IA4500, IA4860, IA4980
SOURCE-COMPUTER (optional) IS0200
SPECIAL-NAMES paragraph (optional) IS0200
STRING statement IA6950, IA7050
Support for lowercase letters IS0100
TALLY IS1650
TITLE statement for nested programs IS0100
Update commuter record IA6200-6610
Update transaction work value spaces IB0790-IB1000
USAGE BINARY IS1300
USAGE PACKED-DECIMAL IS1301
Validate elements IB0810, IB0860, IB1000
VALUE with OCCURS IS0600
VALUE SPACE (S) IS0601
VALUE ZERO (S) (ES) IS0600
Variable-length table control variable IA5100
Variable-length table definition IA2090-2210
Variable-length table loading IA4840-4990
812 Enterprise COBOL for z/OS, V5.2 Programming Guide
Language element or concept Sequence string
VSAM indexed file key definition IA1170
VSAM return-code display IA7800-7900
WORKING-STORAGE SECTION IS0250
Appendix G. Using sample programs 813
814 Enterprise COBOL for z/OS, V5.2 Programming Guide
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 grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
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.
3-2-12, Roppongi, Minato-ku, Tokyo 106-8711
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 Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
Copyright IBM Corp. 1991, 2015 815
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 wish 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:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
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
illustrate 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
816 Enterprise COBOL for z/OS, V5.2 Programming Guide
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. _enter the year or years_. All rights
reserved.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
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.shtml.
Intel is a registered trademark of Intel Corporation or its subsidiaries 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.
Microsoft and Windows 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.
Notices 817
818 Enterprise COBOL for z/OS, V5.2 Programming Guide
Glossary
The terms in this glossary are defined in decimal point characters period (.) or
accordance with their meaning in COBOL. These comma (,), of the decimal point position
terms might or might not have the same meaning in a data item.
in other languages.
actual document encoding
For an XML document, one of the
This glossary includes terms and definitions from
following encoding categories that the
the following publications:
XML parser determines by examining the
v ANSI INCITS 23-1985, Programming languages - first few bytes of the document:
COBOL, as amended by ANSI INCITS 23a-1989,
v ASCII
Programming Languages - COBOL - Intrinsic
Function Module for COBOL, and ANSI INCITS v EBCDIC
23b-1993, Programming Languages - Correction v UTF-8
Amendment for COBOL v UTF-16, either big-endian or
v ANSI X3.172-2002, American National Standard little-endian
Dictionary for Information Systems v Other unsupported encoding
v No recognizable encoding
American National Standard definitions are
preceded by an asterisk (*). * alphabet-name
A user-defined word, in the
A SPECIAL-NAMES paragraph of the
ENVIRONMENT DIVISION, that assigns a
* abbreviated combined relation condition
name to a specific character set or
The combined condition that results from
collating sequence or both.
the explicit omission of a common subject
or a common subject and common * alphabetic character
relational operator in a consecutive A letter or a space character.
sequence of relation conditions.
alphabetic data item
abend Abnormal termination of a program. A data item that is described with a
PICTURE character string that contains
above the 16 MB line
only the symbol A. An alphabetic data
Storage above the so-called 16 MB line (or
item has USAGE DISPLAY.
boundary) but below the 2 GB bar. This
storage is addressable only in 31-bit * alphanumeric character
mode. Before IBM introduced the Any character in the single-byte character
MVS/XA architecture in the 1980s, the set of the computer.
virtual storage for a program was limited
alphanumeric data item
to 16 MB. Programs that have been
A general reference to a data item that is
compiled with a 24-bit mode can address
described implicitly or explicitly as USAGE
only 16 MB of space, as though they were
DISPLAY, and that has category
kept under an imaginary storage line.
alphanumeric, alphanumeric-edited, or
Since VS COBOL II, a program that has
numeric-edited.
been compiled with a 31-bit mode can be
above the 16 MB line. alphanumeric-edited data item
A data item that is described by a PICTURE
* access mode
character string that contains at least one
The manner in which records are to be
instance of the symbol A or X and at least
operated upon within a file.
one of the simple insertion symbols B, 0,
* actual decimal point or /. An alphanumeric-edited data item
The physical representation, using the has USAGE DISPLAY.
* alphanumeric function
A function whose value is composed of a
Copyright IBM Corp. 1991, 2015 819
string of one or more characters from the arithmetic statement, or the evaluation of
alphanumeric character set of the an arithmetic expression, that results in a
computer. mathematically correct solution to the
arguments presented.
alphanumeric group item
A group item that is defined without a * arithmetic operator
GROUP-USAGE NATIONAL clause. For A single character, or a fixed
operations such as INSPECT, STRING, and two-character combination that belongs to
UNSTRING, an alphanumeric group item is the following set:
processed as though all its content were
described as USAGE DISPLAY regardless of Character Meaning
the actual content of the group. For + Addition
operations that require processing of the - Subtraction
elementary items within a group, such as * Multiplication
MOVE CORRESPONDING, ADD CORRESPONDING, / Division
or INITIALIZE, an alphanumeric group ** Exponentiation
item is processed using group semantics.
* arithmetic statement
alphanumeric literal
A statement that causes an arithmetic
A literal that has an opening delimiter
operation to be executed. The arithmetic
from the following set: , ", X, X", Z, or
statements are ADD, COMPUTE, DIVIDE,
Z". The string of characters can include
MULTIPLY, and SUBTRACT.
any character in the character set of the
computer. array An aggregate that consists of data objects,
each of which can be uniquely referenced
* alternate record key
by subscripting. An array is roughly
A key, other than the prime record key,
analogous to a COBOL table.
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 that consists of
the key up to the highest value of the key,
producers, consumers, and
in accordance with the rules for
general-interest groups and establishes the
comparing data items.
procedures by which accredited
organizations create and maintain ASCII
voluntary industry standards in the American National Standard Code for
United States. Information Interchange. The standard
code uses a coded character set that is
argument
based on 7-bit coded characters (8 bits
(1) An identifier, a literal, an arithmetic
including parity check). The standard is
expression, or a function-identifier that
used for information interchange between
specifies a value to be used in the
data processing systems, data
evaluation of a function. (2) An operand
communication systems, and associated
of the USING phrase of a CALL or INVOKE
equipment. The ASCII set consists of
statement, used for passing values to a
control characters and graphic characters.
called program or an invoked 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 assignment-name
and literals separated by arithmetic A name that identifies the organization of
operators, two arithmetic expressions a COBOL file and the name by which it is
separated by an arithmetic operator, or an known to the system.
arithmetic expression enclosed in
* assumed decimal point
parentheses.
A decimal point position that does not
* arithmetic operation involve the existence of an actual
The process caused by the execution of an character in a data item. The assumed
820 Enterprise COBOL for z/OS, V5.2 Programming Guide
decimal point has logical meaning but no records that are either contained within
physical representation. the block or that overlap the block.
Synonymous with physical record.
AT END condition
A condition that is caused during the breakpoint
execution of a READ, RETURN, or SEARCH A place in a computer program, usually
statement under certain conditions: specified by an instruction, where external
v A READ statement runs on a sequentially intervention or a monitor program can
accessed file when no next logical interrupt the program as it runs.
record exists in the file, or when the buffer
number of significant digits in the A portion of storage that is used to hold
relative record number is larger than input or output data temporarily.
the size of the relative key data item, or
when an optional input file is not built-in function
available. See intrinsic function.
v A RETURN statement runs when no next business method
logical record exists for the associated A method of an enterprise bean that
sort or merge file. implements the business logic or rules of
v A SEARCH statement runs when the an application. (Oracle)
search operation terminates without byte A string that consists of a certain number
satisfying the condition specified in any of bits, usually eight, treated as a unit,
of the associated WHEN phrases. and representing a character or a control
function.
B
byte order mark (BOM)
big-endian A Unicode character that can be used at
The default format that the mainframe the start of UTF-16 or UTF-32 text to
and the AIX workstation use to store indicate the byte order of subsequent text;
binary data and UTF-16 characters. In this the byte order can be either big-endian or
format, the least significant byte of a little-endian.
binary data item is at the highest address
and the least significant byte of a UTF-16 bytecode
character is at the highest address. Machine-independent code that is
Compare with little-endian. generated by the Java compiler and
executed by the Java interpreter. (Oracle)
binary item
A numeric data item that is represented in C
binary notation (on the base 2 numbering
system). The decimal equivalent consists callable services
of the decimal digits 0 through 9, plus an In Language Environment, a set of
operational sign. The leftmost bit of the services that a COBOL program can
item is the operational sign. invoke by using the conventional
Language Environment-defined call
binary search interface. All programs that share the
A dichotomizing search in which, at each Language Environment conventions can
step of the search, the set of data elements use these services.
is divided by two; some appropriate
action is taken in the case of an odd called program
number. A program that is the object of a CALL
statement. At run time the called program
* block and calling program are combined to
A physical unit of data that is normally produce a run unit.
composed of one or more logical records.
For mass storage files, a block can contain * calling program
a portion of a logical record. The size of a A program that executes a CALL to another
block has no direct relationship to the size program.
of the file within which the block is
contained or to the size of the logical
Glossary 821
case structure v DBCS character position, for DBCS
A program-processing logic in which a characters represented in USAGE
series of conditions is tested in order to DISPLAY-1
choose between a number of resulting v National character position, for characters
actions. represented in USAGE NATIONAL;
cataloged procedure synonymous with character encoding unit
A set of job control statements that are for UTF-16
placed in a partitioned data set called the character set
procedure library (SYS1.PROCLIB). You A collection of elements that are used to
can use cataloged procedures to save time represent textual information, but for
and reduce errors in coding JCL. which no coded representation is
CCSID assumed. See also coded character set.
See coded character set identifier. character string
century window A sequence of contiguous characters that
A 100-year interval within which any form a COBOL word, a literal, a PICTURE
two-digit year is unique. Several types of character string, or a comment-entry. A
century window are available to COBOL character string must be delimited by
programmers: separators.
v For the windowing intrinsic functions checkpoint
DATE-TO-YYYYMMDD, DAY-TO-YYYYDDD, and A point at which information about the
YEAR-TO-YYYY, you specify the century status of a job and the system can be
window with argument-2. recorded so that the job step can be
v For Language Environment callable restarted later.
services, you specify the century * class
window in CEESCEN. The entity that defines common behavior
* character and implementation for zero, one, or
The basic indivisible unit of the language. more objects. The objects that share the
same implementation are considered to be
character encoding unit objects of the same class. Classes can be
A unit of data that corresponds to one defined hierarchically, allowing one class
code point in a coded character set. One to inherit from another.
or more character encoding units are used
to represent a character in a coded * class condition
character set. Also known as encoding unit. The proposition (for which a truth value
can be determined) that the content of an
For USAGE NATIONAL, a character encoding item is wholly alphabetic, is wholly
unit corresponds to one 2-byte code point numeric, is wholly DBCS, is wholly Kanji,
of UTF-16. or consists exclusively of the characters
For USAGE DISPLAY, a character encoding that are listed in the definition of a
unit corresponds to a byte. class-name.
For USAGE DISPLAY-1, a character * class definition
encoding unit corresponds to a 2-byte The COBOL source unit that defines a
code point in the DBCS character set. class.
character position class hierarchy
The amount of physical storage or A tree-like structure that shows
presentation space required to hold or relationships among object classes. It
present one character. The term applies to places one class at the top and one or
any class of character. For specific classes more layers of classes below it.
of characters, the following terms apply: Synonymous with inheritance hierarchy.
v Alphanumeric character position, for * class identification entry
characters represented in USAGE DISPLAY An entry in the CLASS-ID paragraph of the
IDENTIFICATION DIVISION; this entry
contains clauses that specify the
822 Enterprise COBOL for z/OS, V5.2 Programming Guide
class-name and assign selected attributes code page
to the class definition. An assignment of graphic characters and
control function meanings to all code
class-name (object-oriented)
points. For example, one code page could
The name of an object-oriented COBOL
assign characters and meanings to 256
class definition.
code points for 8-bit code, and another
* class-name (of data) code page could assign characters and
A user-defined word that is defined in the meanings to 128 code points for 7-bit
SPECIAL-NAMES paragraph of the code. For example, one of the IBM code
ENVIRONMENT DIVISION; this word assigns pages for English on the workstation is
a name to the proposition (for which a IBM-1252 and on the host is IBM-1047. A
truth value can be defined) that the coded character set.
content of a data item consists exclusively
code point
of the characters that are listed in the
A unique bit pattern that is defined in a
definition of the class-name.
coded character set (code page). Graphic
class object symbols and control characters are
The runtime object that represents a class. assigned to code points.
* clause coded character set
An ordered set of consecutive COBOL A set of unambiguous rules that establish
character strings whose purpose is to a character set and the relationship
specify an attribute of an entry. between the characters of the set and their
coded representation. Examples of coded
client In object-oriented programming, a
character sets are the character sets as
program or method that requests services
represented by ASCII or EBCDIC code
from one or more methods in a class.
pages or by the UTF-16 encoding scheme
COBOL character set for Unicode.
The set of characters used in writing
coded character set identifier (CCSID)
COBOL syntax. The complete COBOL
An IBM-defined number in the range 1 to
character set consists of these characters:
65,535 that identifies a specific code page.
Character Meaning * collating sequence
0,1, . . . ,9 Digit The sequence in which the characters that
A,B, . . . ,Z Uppercase letter are acceptable to a computer are ordered
a,b, . . . ,z Lowercase letter for purposes of sorting, merging,
Space comparing, and for processing indexed
+ Plus sign files sequentially.
- Minus sign (hyphen)
* Asterisk * column
/ Slant (forward slash) A byte position within a print line or
= Equal sign within a reference format line. The
$ Currency sign columns are numbered from 1, by 1,
, Comma starting at the leftmost position of the line
; Semicolon and extending to the rightmost position of
. Period (decimal point, full stop) the line. A column holds one single-byte
" Quotation mark character.
' Apostrophe * combined condition
( Left parenthesis A condition that is the result of
) Right parenthesis connecting two or more conditions with
> Greater than the AND or the OR logical operator. See also
< Less than condition and negated combined condition.
: Colon
_ Underscore * comment-entry
An entry in the IDENTIFICATION DIVISION
that can be any combination of characters
* COBOL word
from the character set of the computer.
See word.
Glossary 823
comment line complex ODO
A source program line represented by an Certain forms of the OCCURS DEPENDING ON
asterisk (*) in the indicator area of the clause:
line and any characters from the character v Variably located item or group: A data
set of the computer that follow in Area A item described by an OCCURS clause
and Area B of that line. A comment line with the DEPENDING ON option is
serves only for documentation. A special followed by a nonsubordinate data
form of comment line represented by a item or group. The group can be an
slant (/) in the indicator area of the line alphanumeric group or a national
and any characters from the character set group.
of the computer in Area A and Area B of
v Variably located table: A data item
that line causes page ejection before the
described by an OCCURS clause with the
comment is printed.
DEPENDING ON option is followed by a
* common program nonsubordinate data item described by
A program that, despite being directly an OCCURS clause.
contained within another program, can be v Table with variable-length elements: A
called from any program directly or data item described by an OCCURS
indirectly contained in that other clause contains a subordinate data item
program. described by an OCCURS clause with the
* compile DEPENDING ON option.
(1) To translate a program expressed in a v Index name for a table with
high-level language into a program variable-length elements.
expressed in an intermediate language, v Element of a table with variable-length
assembly language, or a computer elements.
language. (2) To prepare a
machine-language program from a component
computer program written in another (1) A functional grouping of related files.
programming language by making use of (2) In object-oriented programming, a
the overall logic structure of the program, reusable object or program that performs
or generating more than one computer a specific function and is designed to
instruction for each symbolic statement, work with other components and
or both, as well as performing the applications. JavaBeans is Oracle's
function of an assembler. architecture for creating components.
* compile time * computer-name
The time at which COBOL source code is A system-name that identifies the
translated, by a COBOL compiler, to a computer where the program is to be
COBOL object program. compiled or run.
compiler condition (exception)
A program that translates source code An exception that has been enabled, or
written in a higher-level language into recognized, by Language Environment
machine-language object code. and thus is eligible to activate user and
language condition handlers. Any
compiler-directing statement alteration to the normal programmed flow
A statement that causes the compiler to of an application. Conditions can be
take a specific action during compilation. detected by the hardware or the operating
The standard compiler-directing system and result in an interrupt. They
statements are COPY, REPLACE, and USE. can also be detected by language-specific
* complex condition generated code or language library code.
A condition in which one or more logical condition (expression)
operators act upon one or more A status of data at run time for which a
conditions. See also condition, negated truth value can be determined. Where
simple condition, and negated combined used in this information in or in reference
condition. to condition (condition-1, condition-2,. . .)
of a general format, the term refers to a
824 Enterprise COBOL for z/OS, V5.2 Programming Guide
conditional expression that consists of contained program
either a simple condition optionally A COBOL program that is nested within
parenthesized or a combined condition another COBOL program.
(consisting of the syntactically correct
* contiguous items
combination of simple conditions, logical
Items that are described by consecutive
operators, and parentheses) for which a
entries in the DATA DIVISION, and that
truth value can be determined. See also
bear a definite hierarchic relationship to
simple condition, complex condition, negated
each other.
simple condition, combined condition, and
negated combined condition. copybook
A file or library member that contains a
* conditional expression
sequence of code that is included in the
A simple condition or a complex
source program at compile time using the
condition specified in an EVALUATE, IF,
COPY statement. The file can be created by
PERFORM, or SEARCH statement. See also
the user, supplied by COBOL, or supplied
simple condition and complex condition.
by another product. Synonymous with
* conditional phrase copy file.
A phrase that specifies the action to be
* counter
taken upon determination of the truth
A data item used for storing numbers or
value of a condition that results from the
number representations in a manner that
execution of a conditional statement.
permits these numbers to be increased or
* conditional statement decreased by the value of another
A statement that specifies that the truth number, or to be changed or reset to zero
value of a condition is to be determined or to an arbitrary positive or negative
and that the subsequent action of the value.
object program depends on this truth
cross-reference listing
value.
The portion of the compiler listing that
* conditional variable contains information on where files,
A data item one or more values of which fields, and indicators are defined,
has a condition-name assigned to it. referenced, and modified in a program.
* condition-name currency-sign value
A user-defined word that assigns a name A character string that identifies the
to a subset of values that a conditional monetary units stored in a numeric-edited
variable can assume; or a user-defined item. Typical examples are $, USD, and
word assigned to a status of an EUR. A currency-sign value can be
implementor-defined switch or device. defined by either the CURRENCY compiler
option or the CURRENCY SIGN clause in the
* condition-name condition
SPECIAL-NAMES paragraph of the
The proposition (for which a truth value
ENVIRONMENT DIVISION. If the CURRENCY
can be determined) that the value of a
SIGN clause is not specified and the
conditional variable is a member of the
NOCURRENCY compiler option is in effect,
set of values attributed to a
the dollar sign ($) is used as the default
condition-name associated with the
currency-sign value. See also currency
conditional variable.
symbol.
* CONFIGURATION SECTION
currency symbol
A section of the ENVIRONMENT DIVISION
A character used in a PICTURE clause to
that describes overall specifications of
indicate the position of a currency sign
source and object programs and class
value in a numeric-edited item. A
definitions.
currency symbol can be defined by either
CONSOLE the CURRENCY compiler option or the
A COBOL environment-name associated CURRENCY SIGN clause in the
with the operator console. SPECIAL-NAMES paragraph of the
ENVIRONMENT DIVISION. If the CURRENCY
SIGN clause is not specified and the
Glossary 825
NOCURRENCY compiler option is in effect, DBCS character
the dollar sign ($) is used as the default Any character defined in IBM's
currency sign value and currency symbol. double-byte character set.
Multiple currency symbols and currency
DBCS character position
sign values can be defined. See also
See character position.
currency sign value.
DBCS data item
* current record
A data item that is described by a PICTURE
In file processing, the record that is
character string that contains at least one
available in the record area associated
symbol G, or, when the NSYMBOL(DBCS)
with a file.
compiler option is in effect, at least one
* current volume pointer symbol N. A DBCS data item has USAGE
A conceptual entity that points to the DISPLAY-1.
current volume of a sequential file.
* debugging line
Any line with a D in the indicator area of
D
the line.
* data clause
* debugging section
A clause, appearing in a data description
A section that contains a USE FOR
entry in the DATA DIVISION of a COBOL
DEBUGGING statement.
program, that provides information
describing a particular attribute of a data * declarative sentence
item. A compiler-directing sentence that
consists of a single USE statement
* data description entry
terminated by the separator period.
An entry in the DATA DIVISION of a
COBOL program that is composed of a * declaratives
level-number followed by a data-name, if A set of one or more special-purpose
required, and then followed by a set of sections, written at the beginning of the
data clauses, as required. PROCEDURE DIVISION, the first of which is
preceded by the key word DECLARATIVE
DATA DIVISION
and the last of which is followed by the
The division of a COBOL program or
key words END DECLARATIVES. A
method that describes the data to be
declarative is composed of a section
processed by the program or method: the
header, followed by a USE
files to be used and the records contained
compiler-directing sentence, followed by a
within them; internal WORKING-STORAGE
set of zero, one, or more associated
records that will be needed; data to be
paragraphs.
made available in more than one program
in the COBOL run unit. * de-edit
The logical removal of all editing
* data item
characters from a numeric-edited data
A unit of data (excluding literals) defined
item in order to determine the unedited
by a COBOL program or by the rules for
numeric value of the item.
function evaluation.
* delimited scope statement
data set
Any statement that includes its explicit
Synonym for file.
scope terminator.
* data-name
* delimiter
A user-defined word that names a data
A character or a sequence of contiguous
item described in a data description entry.
characters that identify the end of a string
When used in the general formats,
of characters and separate that string of
data-name represents a word that must
characters from the following string of
not be reference-modified, subscripted, or
characters. A delimiter is not part of the
qualified unless specifically permitted by
string of characters that it delimits.
the rules for the format.
dependent region
DBCS See double-byte character set (DBCS).
In IMS, the MVS virtual storage region
826 Enterprise COBOL for z/OS, V5.2 Programming Guide
that contains message-driven programs, DLL linkage
batch programs, or online utilities. A CALL in a program that has been
compiled with the DLL and NODYNAM
* descending key
options; the CALL resolves to an exported
A key upon the values of which data is
name in a separate module, or to an
ordered starting with the highest value of
INVOKE of a method that is defined in a
key down to the lowest value of key, in
separate module.
accordance with the rules for comparing
data items. do construct
In structured programming, a DO
digit Any of the numerals from 0 through 9. In
statement is used to group a number of
COBOL, the term is not used to refer to
statements in a procedure. In COBOL, an
any other symbol.
inline PERFORM statement functions in the
* digit position same way.
The amount of physical storage required
do-until
to store a single digit. This amount can
In structured programming, a do-until
vary depending on the usage specified in
loop will be executed at least once, and
the data description entry that defines the
until a given condition is true. In COBOL,
data item.
a TEST AFTER phrase used with the
* direct access PERFORM statement functions in the same
The facility to obtain data from storage way.
devices or to enter data into a storage
do-while
device in such a way that the process
In structured programming, a do-while
depends only on the location of that data
loop will be executed if, and while, a
and not on a reference to data previously
given condition is true. In COBOL, a TEST
accessed.
BEFORE phrase used with the PERFORM
display floating-point data item statement functions in the same way.
A data item that is described implicitly or
document type declaration
explicitly as USAGE DISPLAY and that has a
An XML element that contains or points
PICTURE character string that describes an
to markup declarations that provide a
external floating-point data item.
grammar for a class of documents. This
* division grammar is known as a document type
A collection of zero, one, or more sections definition, or DTD.
or paragraphs, called the division body,
document type definition (DTD)
that are formed and combined in
The grammar for a class of XML
accordance with a specific set of rules.
documents. See document type declaration.
Each division consists of the division
header and the related division body. double-byte character set (DBCS)
There are four divisions in a COBOL A set of characters in which each
program: Identification, Environment, character is represented by 2 bytes.
Data, and Procedure. Languages such as Japanese, Chinese, and
Korean, which contain more symbols than
* division header
can be represented by 256 code points,
A combination of words followed by a
require double-byte character sets.
separator period that indicates the
Because each character requires 2 bytes,
beginning of a division. The division
entering, displaying, and printing DBCS
headers are:
characters requires hardware and
IDENTIFICATION DIVISION. supporting software that are
ENVIRONMENT DIVISION.
DATA DIVISION. DBCS-capable.
PROCEDURE DIVISION. DWARF
DLL See dynamic link library (DLL). DWARF was developed by the UNIX
International Programming Languages
DLL application Special Interest Group (SIG). It is
An application that references imported designed to meet the symbolic,
programs, functions, or variables.
Glossary 827
source-level debugging needs of different edited data item
languages in a unified fashion by A data item that has been modified by
supplying language-independent suppressing zeros or inserting editing
debugging information. A DWARF file characters or both.
contains debugging data organized into
* editing character
different elements. For more information,
A single character or a fixed two-character
see DWARF program information in the
combination belonging to the following
DWARF/ELF Extensions Library Reference.
set:
* dynamic access
An access mode in which specific logical Character Meaning
records can be obtained from or placed Space
into a mass storage file in a nonsequential 0 Zero
manner and obtained from a file in a + Plus
sequential manner during the scope of the - Minus
same OPEN statement. CR Credit
DB Debit
dynamic CALL Z Zero suppress
A CALL literal statement in a program that * Check protect
has been compiled with the DYNAM option $ Currency sign
and the NODLL option, or a CALL identifier , Comma (decimal point)
statement in a program that has been . Period (decimal point)
compiled with the NODLL option. / Slant (forward slash)
dynamic link library (DLL)
A file that contains executable code and EJB See Enterprise JavaBeans.
data that are bound to a program at load
EJB container
time or run time, rather than during
A container that implements the EJB
linking. Several applications can share the
component contract of the J2EE
code and data in a DLL simultaneously.
architecture. This contract specifies a
Although a DLL is not part of the
runtime environment for enterprise beans
executable file for a program, it can be
that includes security, concurrency, life
required for an executable file to run
cycle management, transaction,
properly.
deployment, and other services. An EJB
dynamic storage area (DSA) container is provided by an EJB or J2EE
Dynamically acquired storage composed server. (Oracle)
of a register save area and an area
EJB server
available for dynamic storage allocation
Software that provides services to an EJB
(such as program variables). A DSA is
container. An EJB server can host one or
allocated upon invocation of a program or
more EJB containers. (Oracle)
function and persists for the duration of
the invocation instance. DSAs are element (text element)
generally allocated within stack segments One logical unit of a string of text, such
managed by Language Environment. as the description of a single data item or
verb, preceded by a unique code
* EBCDIC (Extended Binary-Coded Decimal
identifying the element type.
Interchange Code)
A coded character set based on 8-bit * elementary item
coded characters. A data item that is described as not being
further logically subdivided.
EBCDIC character
Any one of the symbols included in the encapsulation
EBCDIC (Extended Binary-Coded-Decimal In object-oriented programming, the
Interchange Code) set. technique that is used to hide the inherent
details of an object. The object provides
an interface that queries and manipulates
828 Enterprise COBOL for z/OS, V5.2 Programming Guide
the data without exposing its underlying * environment clause
structure. Synonymous with information A clause that appears as part of an
hiding. ENVIRONMENT DIVISION entry.
enclave ENVIRONMENT DIVISION
When running under Language One of the four main component parts of
Environment, an enclave is analogous to a a COBOL program, class definition, or
run unit. An enclave can create other method definition. The ENVIRONMENT
enclaves by using LINK and by using the DIVISION describes the computers where
system() function in C. the source program is compiled and those
where the object program is run. It
encoding unit
provides a linkage between the logical
See character encoding unit.
concept of files and their records, and the
end class marker physical aspects of the devices on which
A combination of words, followed by a files are stored.
separator period, that indicates the end of
environment-name
a COBOL class definition. The end class
A name, specified by IBM, that identifies
marker is:
system logical units, printer and card
END CLASS class-name. punch control characters, report codes,
end method marker program switches or all of these. When an
A combination of words, followed by a environment-name is associated with a
separator period, that indicates the end of mnemonic-name in the ENVIRONMENT
a COBOL method definition. The end DIVISION, the mnemonic-name can be
method marker is: substituted in any format in which such
END METHOD method-name. substitution is valid.
* end of PROCEDURE DIVISION environment variable
The physical position of a COBOL source Any of a number of variables that define
program after which no further some aspect of the computing
procedures appear. environment, and are accessible to
programs that operate in that
* end program marker environment. Environment variables can
A combination of words, followed by a affect the behavior of programs that are
separator period, that indicates the end of sensitive to the environment in which
a COBOL source program. The end they operate.
program marker is:
execution time
END PROGRAM program-name.
See run time.
enterprise bean
execution-time environment
A component that implements a business
See runtime environment.
task and resides in an EJB container.
(Oracle) * explicit scope terminator
A reserved word that terminates the scope
Enterprise JavaBeans
of a particular PROCEDURE DIVISION
A component architecture defined by
statement.
Oracle for the development and
deployment of object-oriented, exponent
distributed, enterprise-level applications. A number that indicates the power to
which another number (the base) is to be
* entry
raised. Positive exponents denote
Any descriptive set of consecutive clauses
multiplication; negative exponents denote
terminated by a separator period and
division; and fractional exponents denote
written in the IDENTIFICATION DIVISION,
a root of a quantity. In COBOL, an
ENVIRONMENT DIVISION, or DATA DIVISION
exponential expression is indicated with
of a COBOL program.
the symbol ** followed by the exponent.
* expression
An arithmetic or conditional expression.
Glossary 829
* extend mode factory data
The state of a file after execution of an Data that is allocated once for a class and
OPEN statement, with the EXTEND phrase shared by all instances of the class.
specified for that file, and before the Factory data is declared in the
execution of a CLOSE statement, without WORKING-STORAGE SECTION of the DATA
the REEL or UNIT phrase for that file. DIVISION in the FACTORY paragraph of the
class definition, and is equivalent to Java
Extensible Markup Language
private static data.
See XML.
factory method
extensions
A method that is supported by a class
COBOL syntax and semantics supported
independently of an object instance.
by IBM compilers in addition to those
Factory methods are declared in the
| described in the 85 COBOL Standard.
FACTORY paragraph of the class definition,
external code page and are equivalent to Java public static
For XML documents, the value specified methods. They are typically used to
by the CODEPAGE compiler option. customize the creation of objects.
* external data * figurative constant
The data that is described in a program as A compiler-generated value referenced
external data items and external file through the use of certain reserved
connectors. words.
* external data item * file A collection of logical records.
A data item that is described as part of an
* file attribute conflict condition
external record in one or more programs
An unsuccessful attempt has been made
of a run unit and that can be referenced
to execute an input-output operation on a
from any program in which it is
file and the file attributes, as specified for
described.
that file in the program, do not match the
* external data record fixed attributes for that file.
A logical record that is described in one
* file clause
or more programs of a run unit and
A clause that appears as part of any of
whose constituent data items can be
the following DATA DIVISION entries: file
referenced from any program in which
description entry (FD entry) and
they are described.
sort-merge file description entry (SD
external decimal data item entry).
See zoned decimal data item and national
* file connector
decimal data item.
A storage area that contains information
* external file connector about a file and is used as the linkage
A file connector that is accessible to one between a file-name and a physical file
or more object programs in the run unit. and between a file-name and its
associated record area.
external floating-point data item
See display floating-point data item and * file control entry
national floating-point data item. A SELECT clause and all its subordinate
clauses that declare the relevant physical
external program
attributes of a file.
The outermost program. A program that
is not nested. FILE-CONTROL paragraph
A paragraph in the ENVIRONMENT DIVISION
* external switch
in which the data files for a given source
A hardware or software device, defined
unit are declared.
and named by the implementor, which is
used to indicate that one of two alternate * file description entry
states exists. An entry in the FILE SECTION of the DATA
DIVISION that is composed of the level
F
830 Enterprise COBOL for z/OS, V5.2 Programming Guide
indicator FD, followed by a file-name, and entry requires that all records contain the
then followed by a set of file clauses as same number of bytes.
required.
fixed-point item
* file-name A numeric data item defined with a
A user-defined word that names a file PICTURE clause that specifies the location
connector described in a file description of an optional sign, the number of digits
entry or a sort-merge file description it contains, and the location of an optional
entry within the FILE SECTION of the DATA decimal point. The format can be either
DIVISION. binary, packed decimal, or external
decimal.
* file organization
The permanent logical file structure floating point
established at the time that a file is A format for representing numbers in
created. which a real number is represented by a
pair of distinct numerals. In a
file position indicator
floating-point representation, the real
A conceptual entity that contains the
number is the product of the fixed-point
value of the current key within the key of
part (the first numeral) and a value
reference for an indexed file, or the record
obtained by raising the implicit
number of the current record for a
floating-point base to a power denoted by
sequential file, or the relative record
the exponent (the second numeral). For
number of the current record for a
example, a floating-point representation of
relative file, or indicates that no next
the number 0.0001234 is 0.1234 -3, where
logical record exists, or that an optional
0.1234 is the mantissa and -3 is the
input file is not available, or that the AT
exponent.
END condition already exists, or that no
valid next record has been established. floating-point data item
A numeric data item that contains a
* FILE SECTION
fraction and an exponent. Its value is
The section of the DATA DIVISION that
obtained by multiplying the fraction by
contains file description entries and
the base of the numeric data item raised
sort-merge file description entries together
to the power that the exponent specifies.
with their associated record descriptions.
* format
file system
A specific arrangement of a set of data.
The collection of files that conform to a
specific set of data-record and * function
file-description protocols, and a set of A temporary data item whose value is
programs that manage these files. determined at the time the function is
referenced during the execution of a
* fixed file attributes
statement.
Information about a file that is established
when a file is created and that cannot * function-identifier
subsequently be changed during the A syntactically correct combination of
existence of the file. These attributes character strings and separators that
include the organization of the file references a function. The data item
(sequential, relative, or indexed), the represented by a function is uniquely
prime record key, the alternate record identified by a function-name with its
keys, the code set, the minimum and arguments, if any. A function-identifier
maximum record size, the record type can include a reference-modifier. A
(fixed or variable), the collating sequence function-identifier that references an
of the keys for indexed files, the blocking alphanumeric function can be specified
factor, the padding character, and the anywhere in the general formats that an
record delimiter. identifier can be specified, subject to
certain restrictions. A function-identifier
* fixed-length record
that references an integer or numeric
A record associated with a file whose file
function can be referenced anywhere in
description or sort-merge description
Glossary 831
the general formats that an arithmetic hide To redefine a factory or static method
expression can be specified. (inherited from a parent class) in a
subclass.
function-name
A word that names the mechanism whose * high-order end
invocation, along with required The leftmost character of a string of
arguments, determines the value of a characters.
function.
hiperspace
function-pointer data item In a z/OS environment, a range of up to
A data item in which a pointer to an 2 GB of contiguous virtual storage
entry point can be stored. A data item addresses that a program can use as a
defined with the USAGE IS buffer.
FUNCTION-POINTER clause contains the
address of a function entry point. I
Typically used to communicate with C
IBM COBOL extension
and Java programs.
COBOL syntax and semantics supported
by IBM compilers in addition to those
G
| described in the 85 COBOL Standard.
garbage collection
IDENTIFICATION DIVISION
The automatic freeing by the Java runtime
One of the four main component parts of
system of the memory for objects that are
a COBOL program, class definition, or
no longer referenced.
method definition. The IDENTIFICATION
* global name DIVISION identifies the program, class, or
A name that is declared in only one method. The IDENTIFICATION DIVISION
program but that can be referenced from can include the following documentation:
the program and from any program author name, installation, or date.
contained within the program.
* identifier
Condition-names, data-names, file-names,
A syntactically correct combination of
record-names, report-names, and some
character strings and separators that
special registers can be global names.
names a data item. When referencing a
global reference data item that is not a function, an
A reference to an object that is outside the identifier consists of a data-name,
scope of a method. together with its qualifiers, subscripts,
and reference-modifier, as required for
group item
uniqueness of reference. When referencing
(1) A data item that is composed of
a data item that is a function, a
subordinate data items. See alphanumeric
function-identifier is used.
group item and national group item. (2)
When not qualified explicitly or by * imperative statement
context as a national group or an A statement that either begins with an
alphanumeric group, the term refers to imperative verb and specifies an
groups in general. unconditional action to be taken or is a
conditional statement that is delimited by
grouping separator
its explicit scope terminator (delimited
A character used to separate units of
scope statement). An imperative statement
digits in numbers for ease of reading. The
can consist of a sequence of imperative
default is the character comma.
statements.
H * implicit scope terminator
A separator period that terminates the
header label
scope of any preceding unterminated
(1) A data-set label that precedes the data
statement, or a phrase of a statement that
records in a unit of recording media. (2)
by its occurrence indicates the end of the
Synonym for beginning-of-file label.
scope of any statement contained within
the preceding phrase.
832 Enterprise COBOL for z/OS, V5.2 Programming Guide
* index * input file
A computer storage area or register, the A file that is opened in the input mode.
content of which represents the
* input mode
identification of a particular element in a
The state of a file after execution of an
table.
OPEN statement, with the INPUT phrase
* index data item specified, for that file and before the
A data item in which the values execution of a CLOSE statement, without
associated with an index-name can be the REEL or UNIT phrase for that file.
stored in a form specified by the
* input-output file
implementor.
A file that is opened in the I-O mode.
indexed data-name
* INPUT-OUTPUT SECTION
An identifier that is composed of a
The section of the ENVIRONMENT DIVISION
data-name, followed by one or more
that names the files and the external
index-names enclosed in parentheses.
media required by an object program or
* indexed file method and that provides information
A file with indexed organization. required for transmission and handling of
data at run time.
* indexed organization
The permanent logical file structure in * input-output statement
which each record is identified by the A statement that causes files to be
value of one or more keys within that processed by performing operations on
record. individual records or on the file as a unit.
The input-output statements are ACCEPT
indexing
(with the identifier phrase), CLOSE, DELETE,
Synonymous with subscripting using
DISPLAY, OPEN, READ, REWRITE, SET (with
index-names.
the TO ON or TO OFF phrase), START, and
* index-name WRITE.
A user-defined word that names an index
* input procedure
associated with a specific table.
A set of statements, to which control is
inheritance | given during the execution of a format 1
A mechanism for using the | SORT statement, for the purpose of
implementation of a class as the basis for controlling the release of specified records
another class. By definition, the inheriting to be sorted.
class conforms to the inherited classes.
instance data
Enterprise COBOL does not support
Data that defines the state of an object.
multiple inheritance; a subclass has exactly
The instance data introduced by a class is
one immediate superclass.
defined in the WORKING-STORAGE SECTION
inheritance hierarchy of the DATA DIVISION in the OBJECT
See class hierarchy. paragraph of the class definition. The
state of an object also includes the state of
* initial program
the instance variables introduced by
A program that is placed into an initial
classes that are inherited by the current
state every time the program is called in a
class. A separate copy of the instance data
run unit.
is created for each object instance.
* initial state
* integer
The state of a program when it is first
(1) A numeric literal that does not include
called in a run unit.
any digit positions to the right of the
inline decimal point. (2) A numeric data item
In a program, instructions that are defined in the DATA DIVISION that does
executed sequentially, without branching not include any digit positions to the
to routines, subroutines, or other right of the decimal point. (3) A numeric
programs. function whose definition provides that
all digits to the right of the decimal point
Glossary 833
are zero in the returned value for any * intrarecord data structure
possible evaluation of the function. The entire collection of groups and
elementary data items from a logical
integer function
record that a contiguous subset of the
A function whose category is numeric and
data description entries defines. These
whose definition does not include any
data description entries include all entries
digit positions to the right of the decimal
whose level-number is greater than the
point.
level-number of the first data description
Interactive System Productivity Facility (ISPF) entry describing the intra-record data
An IBM software product that provides a structure.
menu-driven interface for the TSO or VM
intrinsic function
user. ISPF includes library utilities, a
A predefined function, such as a
powerful editor, and dialog management.
commonly used arithmetic function,
interlanguage communication (ILC) called by a built-in function reference.
The ability of routines written in different
* invalid key condition
programming languages to communicate.
A condition, at run time, caused when a
ILC support lets you readily build
specific value of the key associated with
applications from component routines
an indexed or relative file is determined
written in a variety of languages.
to be not valid.
intermediate result
* I-O-CONTROL
An intermediate field that contains the
The name of an ENVIRONMENT DIVISION
results of a succession of arithmetic
paragraph in which object program
operations.
requirements for rerun points, sharing of
* internal data same areas by several data files, and
The data that is described in a program multiple file storage on a single
and excludes all external data items and input-output device are specified.
external file connectors. Items described
* I-O-CONTROL entry
in the LINKAGE SECTION of a program are
An entry in the I-O-CONTROL paragraph of
treated as internal data.
the ENVIRONMENT DIVISION; this entry
* internal data item contains clauses that provide information
A data item that is described in one required for the transmission and
program in a run unit. An internal data handling of data on named files during
item can have a global name. the execution of a program.
internal decimal data item * I-O mode
A data item that is described as USAGE The state of a file after execution of an
PACKED-DECIMAL or USAGE COMP-3, and that OPEN statement, with the I-O phrase
has a PICTURE character string that defines specified, for that file and before the
the item as numeric (a valid combination execution of a CLOSE statement without
of symbols 9, S, P, or V). Synonymous the REEL or UNIT phase for that file.
with packed-decimal data item.
* I-O status
* internal file connector A conceptual entity that contains the
A file connector that is accessible to only two-character value indicating the
one object program in the run unit. resulting status of an input-output
operation. This value is made available to
internal floating-point data item
the program through the use of the FILE
A data item that is described as USAGE
STATUS clause in the file control entry for
COMP-1 or USAGE COMP-2. COMP-1 defines a
the file.
single-precision floating-point data item.
COMP-2 defines a double-precision is-a A relationship that characterizes classes
floating-point data item. There is no and subclasses in an inheritance hierarchy.
PICTURE clause associated with an internal Subclasses that have an is-a relationship
floating-point data item. to a class inherit from that class.
834 Enterprise COBOL for z/OS, V5.2 Programming Guide
ISPF See Interactive System Productivity Facility Java virtual machine (JVM)
(ISPF). A software implementation of a central
processing unit that runs compiled Java
iteration structure
programs.
A program processing logic in which a
series of statements is repeated while a JavaBeans
condition is true or until a condition is A portable, platform-independent,
true. reusable component model. (Oracle)
JBP See Java batch-processing program (JBP).
J
JDBC See Java Database Connectivity (JDBC).
J2EE See Java 2 Platform, Enterprise Edition
(J2EE). JMP See Java message-processing program (JMP).
Java 2 Platform, Enterprise Edition (J2EE) job control language (JCL)
An environment for developing and A control language used to identify a job
deploying enterprise applications, defined to an operating system and to describe
by Oracle. The J2EE platform consists of a the job's requirements.
set of services, application programming
JVM See Java virtual machine (JVM).
interfaces (APIs), and protocols that
provide the functionality for developing
K
multitiered, Web-based applications.
(Oracle) K When referring to storage capacity, two to
the tenth power; 1024 in decimal notation.
Java batch-processing program (JBP)
An IMS batch-processing program that * key A data item that identifies the location of
has access to online databases and output a record, or a set of data items that serve
message queues. JBPs run online, but like to identify the ordering of data.
programs in a batch environment, they
* key of reference
are started with JCL or in a TSO session.
The key, either prime or alternate,
Java batch-processing region currently being used to access records
An IMS dependent region in which only within an indexed file.
Java batch-processing programs are
* keyword
scheduled.
A reserved word or function-name whose
Java Database Connectivity (JDBC) presence is required when the format in
A specification from Oracle that defines which the word appears is used in a
an API that enables Java programs to source program.
access databases.
kilobyte (KB)
Java message-processing program (JMP) One kilobyte equals 1024 bytes.
A Java application program that is driven
by transactions and has access to online L
IMS databases and message queues.
* language-name
Java message-processing region A system-name that specifies a particular
An IMS dependent region in which only programming language.
Java message-processing programs are
Language Environment-conforming
scheduled.
A characteristic of compiler products
Java Native Interface (JNI) (such as Enterprise COBOL, COBOL for
A programming interface that lets Java OS/390 & VM, COBOL for MVS & VM,
code that runs inside a Java virtual C/C++ for MVS & VM, PL/I for MVS &
machine (JVM) interoperate with VM) that produce object code conforming
applications and libraries written in other to the Language Environment
programming languages. conventions.
last-used state
A state that a program is in if its internal
values remain the same as when the
Glossary 835
program was exited (the values are not multiple links in a multipoint or
reset to their initial values). token-ring configuration. (2) To
interconnect items of data or portions of
* letter
one or more computer programs; for
A character belonging to one of the
example, linking object programs by a
following two sets:
linkage-editor to produce an executable
1. Uppercase letters: A, B, C, D, E, F, G, file.
H, I, J, K, L, M, N, O, P, Q, R, S, T, U,
V, W, X, Y, Z LINKAGE SECTION
The section in the DATA DIVISION of the
2. Lowercase letters: a, b, c, d, e, f, g, h, i,
called program or invoked method that
j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y,
describes data items available from the
z
calling program or invoking method. Both
* level indicator the calling program or invoking method
Two alphabetic characters that identify a and the called program or invoked
specific type of file or a position in a method can refer to these data items.
hierarchy. The level indicators in the DATA
linker A term that refers to either the z/OS
DIVISION are: CD, FD, and SD.
| binder (linkage-editor).
* level-number
literal
A user-defined word (expressed as a
A character string whose value is
two-digit number) that indicates the
specified either by the ordered set of
hierarchical position of a data item or the
characters comprising the string or by the
special properties of a data description
use of a figurative constant.
entry. Level-numbers in the range from 1
through 49 indicate the position of a data little-endian
item in the hierarchical structure of a The default format that Intel processors
logical record. Level-numbers in the range use to store binary data and UTF-16
1 through 9 can be written either as a characters. In this format, the most
single digit or as a zero followed by a significant byte of a binary data item is at
significant digit. Level-numbers 66, 77, the highest address and the most
and 88 identify special properties of a significant byte of a UTF-16 character is at
data description entry. the highest address. Compare with
big-endian.
* library-name
A user-defined word that names a local reference
COBOL library that the compiler is to use A reference to an object that is within the
for compiling a given source program. scope of your method.
* library text locale A set of attributes for a program
A sequence of text words, comment lines, execution environment that indicates
the separator space, or the separator culturally sensitive considerations, such as
pseudo-text delimiter in a COBOL library. character code page, collating sequence,
date and time format, monetary value
Lilian date
representation, numeric value
The number of days since the beginning
representation, or language.
of the Gregorian calendar. Day one is
Friday, October 15, 1582. The Lilian date * LOCAL-STORAGE SECTION
format is named in honor of Luigi Lilio, The section of the DATA DIVISION that
the creator of the Gregorian calendar. defines storage that is allocated and freed
on a per-invocation basis, depending on
* linage-counter
the value assigned in the VALUE clauses.
A special register whose value points to
the current position within the page body. * logical operator
One of the reserved words AND, OR, or
link (1) The combination of the link connection
NOT. In the formation of a condition,
(the transmission medium) and two link
either AND, or OR, or both can be used
stations, one at each end of the link
as logical connectives. NOT can be used
connection. A link can be shared among
for logical negation.
836 Enterprise COBOL for z/OS, V5.2 Programming Guide
* logical record supported by an object and that is
The most inclusive data item. The executed by an INVOKE statement on that
level-number for a record is 01. A record object.
can be either an elementary item or a
* method definition
group of items. Synonymous with record.
The COBOL source code that defines a
* low-order end method.
The rightmost character of a string of
* method identification entry
characters.
An entry in the METHOD-ID paragraph of
the IDENTIFICATION DIVISION; this entry
M
contains a clause that specifies the
main program method-name.
In a hierarchy of programs and
method invocation
subroutines, the first program that
A communication from one object to
receives control when the programs are
another that requests the receiving object
run within a process.
to execute a method.
makefile
method-name
A text file that contains a list of the files
The name of an object-oriented operation.
for your application. The make utility
When used to invoke the method, the
uses this file to update the target files
name can be an alphanumeric or national
with the latest changes.
literal or a category alphanumeric or
* mass storage category national data item. When used
A storage medium in which data can be in the METHOD-ID paragraph to define the
organized and maintained in both a method, the name must be an
sequential manner and a nonsequential alphanumeric or national literal.
manner.
* mnemonic-name
* mass storage device A user-defined word that is associated in
A device that has a large storage capacity, the ENVIRONMENT DIVISION with a
such as a magnetic disk. specified implementor-name.
* mass storage file module definition file
A collection of records that is stored in a A file that describes the code segments
mass storage medium. | within a program object.
* megabyte (MB) MPP See message-processing program (MPP).
One megabyte equals 1,048,576 bytes.
multitasking
* merge file A mode of operation that provides for the
A collection of records to be merged by a concurrent, or interleaved, execution of
MERGE statement. The merge file is created two or more tasks.
and can be used only by the merge
multithreading
function.
Concurrent operation of more than one
message-processing program (MPP) path of execution within a computer.
An IMS application program that is Synonymous with multiprocessing.
driven by transactions and has access to
online IMS databases and message N
queues.
name A word (composed of not more than 30
message queue characters) that defines a COBOL
The data set on which messages are operand.
queued before being processed by an
namespace
application program or sent to a terminal.
See XML namespace.
method
national character
Procedural code that defines an operation
(1) A UTF-16 character in a USAGE
Glossary 837
NATIONAL data item or national literal. (2) sequence associated with the computer
Any character represented in UTF-16. specified in the OBJECT-COMPUTER
paragraph.
national character position
See character position. native method
A Java method with an implementation
national data item
that is written in another programming
A data item of category national,
language, such as COBOL.
national-edited, or numeric-edited of
USAGE NATIONAL. * negated combined condition
The NOT logical operator immediately
national decimal data item
followed by a parenthesized combined
An external decimal data item that is
condition. See also condition and combined
described implicitly or explicitly as USAGE
condition.
NATIONAL and that contains a valid
combination of PICTURE symbols 9, S, P, * negated simple condition
and V. The NOT logical operator immediately
followed by a simple condition. See also
national-edited data item
condition and simple condition.
A data item that is described by a PICTURE
character string that contains at least one nested program
instance of the symbol N and at least one A program that is directly contained
of the simple insertion symbols B, 0, or /. within another program.
A national-edited data item has USAGE
* next executable sentence
NATIONAL.
The next sentence to which control will be
national floating-point data item transferred after execution of the current
An external floating-point data item that statement is complete.
is described implicitly or explicitly as
* next executable statement
USAGE NATIONAL and that has a PICTURE
The next statement to which control will
character string that describes a
be transferred after execution of the
floating-point data item.
current statement is complete.
national group item
* next record
A group item that is explicitly or
The record that logically follows the
implicitly described with a GROUP-USAGE
current record of a file.
NATIONAL clause. A national group item is
processed as though it were defined as an * noncontiguous items
elementary data item of category national Elementary data items in the
for operations such as INSPECT, STRING, WORKING-STORAGE SECTION and LINKAGE
and UNSTRING. This processing ensures SECTION that bear no hierarchic
correct padding and truncation of relationship to other data items.
national characters, as contrasted with
null A figurative constant that is used to
defining USAGE NATIONAL data items
assign, to pointer data items, the value of
within an alphanumeric group item. For
an address that is not valid. NULLS can be
operations that require processing of the
used wherever NULL can be used.
elementary items within a group, such as
MOVE CORRESPONDING, ADD CORRESPONDING, * numeric character
and INITIALIZE, a national group is A character that belongs to the following
processed using group semantics. set of digits: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9.
* native character set numeric data item
The implementor-defined character set (1) A data item whose description restricts
associated with the computer specified in its content to a value represented by
the OBJECT-COMPUTER paragraph. characters chosen from the digits 0
through 9. If signed, the item can also
* native collating sequence
contain a +, -, or other representation of
The implementor-defined collating
an operational sign. (2) A data item of
category numeric, internal floating-point,
838 Enterprise COBOL for z/OS, V5.2 Programming Guide
or external floating-point. A numeric data input to a linkage-editor. Synonymous
item can have USAGE DISPLAY, NATIONAL, with object module and text deck.
PACKED-DECIMAL, BINARY, COMP, COMP-1,
object instance
COMP-2, COMP-3, COMP-4, or COMP-5.
See object.
numeric-edited data item
object module
A data item that contains numeric data in
Synonym for object deck or text deck.
a form suitable for use in printed output.
The data item can consist of external * object of entry
decimal digits from 0 through 9, the A set of operands and reserved words,
decimal separator, commas, the currency within a DATA DIVISION entry of a COBOL
sign, sign control characters, and other program, that immediately follows the
editing characters. A numeric-edited item subject of the entry.
can be represented in either USAGE
object-oriented programming
DISPLAY or USAGE NATIONAL.
A programming approach based on the
* numeric function concepts of encapsulation and inheritance.
A function whose class and category are Unlike procedural programming
numeric but that for some possible techniques, object-oriented programming
evaluation does not satisfy the concentrates on the data objects that
requirements of integer functions. comprise the problem and how they are
manipulated, not on how something is
* numeric literal
accomplished.
A literal composed of one or more
numeric characters that can contain a object program
decimal point or an algebraic sign, or A set or group of executable
both. The decimal point must not be the machine-language instructions and other
rightmost character. The algebraic sign, if material designed to interact with data to
present, must be the leftmost character. provide problem solutions. In this context,
an object program is generally the
O machine language result of the operation
of a COBOL compiler on a source
object
program or class definition. Where there
An entity that has state (its data values)
is no danger of ambiguity, the word
and operations (its methods). An object is
program can be used in place of object
a way to encapsulate state and behavior.
program.
Each object in the class is said to be an
instance of the class. object reference
A value that identifies an instance of a
object code
class. If the class is not specified, the
Output from a compiler or assembler that
object reference is universal and can
is itself executable machine code or is
apply to instances of any class.
suitable for processing to produce
executable machine code. * object time
The time at which an object program is
* OBJECT-COMPUTER
executed. Synonymous with run time.
The name of an ENVIRONMENT DIVISION
paragraph in which the computer * obsolete element
environment, where the object program is | A COBOL language element in the 85
run, is described. | COBOL Standard that was deleted from
| the 2002 COBOL Standard.
* object computer entry
An entry in the OBJECT-COMPUTER ODO object
paragraph of the ENVIRONMENT DIVISION; In the example below, X is the object of
this entry contains clauses that describe the OCCURS DEPENDING ON clause (ODO
the computer environment in which the object).
object program is to be executed.
object deck
A portion of an object program suitable as
Glossary 839
WORKING-STORAGE SECTION * output file
01 TABLE-1. A file that is opened in either output
05 X PICS9.
mode or extend mode.
05 Y OCCURS 3 TIMES
DEPENDING ON X PIC X. * output mode
The state of a file after execution of an
The value of the ODO object determines OPEN statement, with the OUTPUT or EXTEND
how many of the ODO subject appear in phrase specified, for that file and before
the table. the execution of a CLOSE statement
ODO subject without the REEL or UNIT phrase for that
In the example above, Y is the subject of file.
the OCCURS DEPENDING ON clause (ODO * output procedure
subject). The number of Y ODO subjects A set of statements to which control is
that appear in the table depends on the | given during execution of a format 1 SORT
value of X. statement after the sort function is
* open mode completed, or during execution of a MERGE
The state of a file after execution of an statement after the merge function reaches
OPEN statement for that file and before the a point at which it can select the next
execution of a CLOSE statement without record in merged order when requested.
the REEL or UNIT phrase for that file. The overflow condition
particular open mode is specified in the A condition that occurs when a portion of
OPEN statement as either INPUT, OUTPUT, the result of an operation exceeds the
I-O, or EXTEND. capacity of the intended unit of storage.
* operand overload
(1) The general definition of operand is To define a method with the same name
the component that is operated upon. as another method that is available in the
(2) For the purposes of this document, same class, but with a different signature.
any lowercase word (or words) that See also signature.
appears in a statement or entry format
can be considered to be an operand and, override
as such, is an implied reference to the To redefine an instance method (inherited
data indicated by the operand. from a parent class) in a subclass.
operation P
A service that can be requested of an
object. package
A group of related Java classes, which can
* operational sign be imported individually or as a whole.
An algebraic sign that is associated with a
numeric data item or a numeric literal, to packed-decimal data item
indicate whether its value is positive or See internal decimal data item.
negative. padding character
optional file An alphanumeric or national character
A file that is declared as being not that is used to fill the unused character
necessarily available each time the object positions in a physical record.
program is run. page A vertical division of output data that
* optional word represents a physical separation of the
A reserved word that is included in a data. The separation is based on internal
specific format only to improve the logical requirements or external
readability of the language. Its presence is characteristics of the output medium or
optional to the user when the format in both.
which the word appears is used in a * page body
source unit. That part of the logical page in which
lines can be written or spaced or both.
840 Enterprise COBOL for z/OS, V5.2 Programming Guide
* paragraph form a portion of a COBOL procedural
In the PROCEDURE DIVISION, a statement or of a COBOL clause.
paragraph-name followed by a separator
* physical record
period and by zero, one, or more
See block.
sentences. In the IDENTIFICATION
DIVISION and ENVIRONMENT DIVISION, a pointer data item
paragraph header followed by zero, one, A data item in which address values can
or more entries. be stored. Data items are explicitly
defined as pointers with the USAGE IS
* paragraph header
POINTER clause. ADDRESS OF special
A reserved word, followed by the
registers are implicitly defined as pointer
separator period, that indicates the
data items. Pointer data items can be
beginning of a paragraph in the
compared for equality or moved to other
IDENTIFICATION DIVISION and
pointer data items.
ENVIRONMENT DIVISION. The permissible
paragraph headers in the IDENTIFICATION port (1) To modify a computer program to
DIVISION are: enable it to run on a different platform.
PROGRAM-ID. (Program IDENTIFICATION (2) In the Internet suite of protocols, a
DIVISION) specific logical connector between the
CLASS-ID. (Class IDENTIFICATION DIVISION) Transmission Control Protocol (TCP) or
METHOD-ID. (Method IDENTIFICATION the User Datagram Protocol (UDP) and a
DIVISION)
AUTHOR. higher-level protocol or application. A
INSTALLATION. port is identified by a port number.
DATE-WRITTEN.
DATE-COMPILED. portability
SECURITY. The ability to transfer an application
program from one application platform to
The permissible paragraph headers in the another with relatively few changes to the
ENVIRONMENT DIVISION are: source program.
SOURCE-COMPUTER. preinitialization
OBJECT-COMPUTER. The initialization of the COBOL runtime
SPECIAL-NAMES.
REPOSITORY. (Program or Class environment in preparation for multiple
CONFIGURATION SECTION) calls from programs, especially
FILE-CONTROL. non-COBOL programs. The environment
I-O-CONTROL. is not terminated until an explicit
* paragraph-name termination.
A user-defined word that identifies and * prime record key
begins a paragraph in the PROCEDURE A key whose contents uniquely identify a
DIVISION. record within an indexed file.
parameter * priority-number
(1) Data passed between a calling A user-defined word that classifies
program and a called program. (2) A data sections in the PROCEDURE DIVISION for
element in the USING phrase of a method purposes of segmentation. Segment
invocation. Arguments provide additional numbers can contain only the characters 0
information that the invoked method can through 9. A segment number can be
use to perform the requested operation. expressed as either one or two digits.
Persistent Reusable JVM private
A JVM that can be serially reused for As applied to factory data or instance
transaction processing by resetting the data, accessible only by methods of the
JVM between transactions. The reset class that defines the data.
phase restores the JVM to a known
initialization state. * procedure
A paragraph or group of logically
* phrase successive paragraphs, or a section or
An ordered set of one or more
consecutive COBOL character strings that
Glossary 841
group of logically successive sections, runtime environment to execute it. (2) A
within the PROCEDURE DIVISION. logical assembly of one or more
interrelated modules. Multiple copies of
* procedure branching statement
the same program can be run in different
A statement that causes the explicit
processes.
transfer of control to a statement other
than the next executable statement in the * program identification entry
sequence in which the statements are In the PROGRAM-ID paragraph of the
written in the source code. The procedure IDENTIFICATION DIVISION, an entry that
branching statements are: ALTER, CALL, contains clauses that specify the
EXIT, EXIT PROGRAM, GO TO, MERGE (with the program-name and assign selected
OUTPUT PROCEDURE phrase), PERFORM and program attributes to the program.
SORT (with the INPUT PROCEDURE or OUTPUT
program-name
PROCEDURE phrase), XML PARSE.
In the IDENTIFICATION DIVISION and the
PROCEDURE DIVISION end program marker, a user-defined word
The COBOL division that contains or alphanumeric literal that identifies a
instructions for solving a problem. COBOL source program.
procedure integration project
One of the functions of the COBOL The complete set of data and actions that
optimizer is to simplify calls to performed are required to build a target, such as a
procedures or contained programs. dynamic link library (DLL) or other
executable (EXE).
PERFORM procedure integration is the
process whereby a PERFORM statement is * pseudo-text
replaced by its performed procedures. A sequence of text words, comment lines,
Contained program procedure integration or the separator space in a source
is the process where a call to a contained program or COBOL library bounded by,
program is replaced by the program code. but not including, pseudo-text delimiters.
* procedure-name * pseudo-text delimiter
A user-defined word that is used to name Two contiguous equal sign characters (==)
a paragraph or section in the PROCEDURE used to delimit pseudo-text.
DIVISION. It consists of a paragraph-name
* punctuation character
(which can be qualified) or a
A character that belongs to the following
section-name.
set:
procedure-pointer data item
A data item in which a pointer to an Character Meaning
entry point can be stored. A data item , Comma
defined with the USAGE IS ; Semicolon
PROCEDURE-POINTER clause contains the : Colon
address of a procedure entry point. . Period (full stop)
Typically used to communicate with " Quotation mark
COBOL and Language Environment ( Left parenthesis
programs. ) Right parenthesis
Space
process = Equal sign
The course of events that occurs during
the execution of all or part of a program.
Multiple processes can run concurrently, Q
and programs that run within a process
QSAM (Queued Sequential Access Method)
can share resources.
An extended version of the basic
program sequential access method (BSAM). When
(1) A sequence of instructions suitable for this method is used, a queue is formed of
processing by a computer. Processing may input data blocks that are awaiting
include the use of a compiler to prepare processing or of output data blocks that
the program for execution, as well as a
842 Enterprise COBOL for z/OS, V5.2 Programming Guide
have been processed and are awaiting * record number
transfer to auxiliary storage or to an The ordinal number of a record in the file
output device. whose organization is sequential.
* qualified data-name recording mode
An identifier that is composed of a The format of the logical records in a file.
data-name followed by one or more sets Recording mode can be F (fixed length), V
of either of the connectives OF and IN (variable length), S (spanned), or U
followed by a data-name qualifier. (undefined).
* qualifier recursion
(1) A data-name or a name associated A program calling itself or being directly
with a level indicator that is used in a or indirectly called by one of its called
reference either together with another programs.
data-name (which is the name of an item
recursively capable
that is subordinate to the qualifier) or
A program is recursively capable (can be
together with a condition-name. (2) A
called recursively) if the RECURSIVE
section-name that is used in a reference
attribute is on the PROGRAM-ID statement.
together with a paragraph-name specified
in that section. (3) A library-name that is reel A discrete portion of a storage medium,
used in a reference together with a the dimensions of which are determined
text-name associated with that library. by each implementor that contains part of
a file, all of a file, or any number of files.
R Synonymous with unit and volume.
* random access reentrant
An access mode in which the The attribute of a program or routine that
program-specified value of a key data lets more than one user share a single
item identifies the logical record that is | copy of a program object.
obtained from, deleted from, or placed
* reference format
into a relative or indexed file.
A format that provides a standard method
* record for describing COBOL source programs.
See logical record.
reference modification
* record area A method of defining a new category
A storage area allocated for the purpose alphanumeric, category DBCS, or category
of processing the record described in a national data item by specifying the
record description entry in the FILE leftmost character and length relative to
SECTION of the DATA DIVISION. In the FILE the leftmost character position of a USAGE
SECTION, the current number of character DISPLAY, DISPLAY-1, or NATIONAL data
positions in the record area is determined item.
by the explicit or implicit RECORD clause.
* reference-modifier
* record description A syntactically correct combination of
See record description entry. character strings and separators that
defines a unique data item. It includes a
* record description entry
delimiting left parenthesis separator, the
The total set of data description entries
leftmost character position, a colon
associated with a particular record.
separator, optionally a length, and a
Synonymous with record description.
delimiting right parenthesis separator.
record key
* relation
A key whose contents identify a record
See relational operator or relation condition.
within an indexed file.
* relation character
* record-name
A character that belongs to the following
A user-defined word that names a record
set:
described in a record description entry in
the DATA DIVISION of a COBOL program.
Glossary 843
Character Meaning by an integer value greater than zero,
> Greater than which specifies the logical ordinal
< Less than position of the record in the file.
= Equal to * relative record number
The ordinal number of a record in a file
* relation condition whose organization is relative. This
The proposition (for which a truth value number is treated as a numeric literal that
can be determined) that the value of an is an integer.
arithmetic expression, data item, * reserved word
alphanumeric literal, or index-name has a A COBOL word that is specified in the
specific relationship to the value of list of words that can be used in a
another arithmetic expression, data item, COBOL source program, but that must
alphanumeric literal, or index name. See not appear in the program as a
also relational operator. user-defined word or system-name.
* relational operator * resource
A reserved word, a relation character, a A facility or service, controlled by the
group of consecutive reserved words, or a operating system, that an executing
group of consecutive reserved words and program can use.
relation characters used in the
construction of a relation condition. The * resultant identifier
permissible operators and their meanings A user-defined data item that is to contain
are: the result of an arithmetic operation.
Character Meaning reusable environment
IS GREATER THAN Greater than A reusable environment is created when
IS > Greater than you establish an assembler program as
IS NOT GREATER THAN Not greater than the main program by using either the old
IS NOT > Not greater than COBOL interfaces for preinitialization
(RTEREUS runtime option), or the
IS LESS THAN Less than Language Environment interface,
IS < Less than CEEPIPI.
IS NOT LESS THAN Not less than routine
IS NOT < Not less than A set of statements in a COBOL program
that causes the computer to perform an
IS EQUAL TO Equal to operation or series of related operations.
IS = Equal to In Language Environment, refers to either
IS NOT EQUAL TO Not equal to a procedure, function, or subroutine.
IS NOT = Not equal to
* routine-name
A user-defined word that identifies a
IS GREATER THAN OR EQUAL Greater than or equal to
procedure written in a language other
TO
than COBOL.
IS >= Greater than or equal to
* run time
IS LESS THAN OR EQUAL TO Less than or equal to The time at which an object program is
IS <= Less than or equal to executed. Synonymous with object time.
runtime environment
* relative file The environment in which a COBOL
A file with relative organization. program executes.
* relative key * run unit
A key whose contents identify a logical A stand-alone object program, or several
record in a relative file. object programs, that interact by means of
* relative organization COBOL CALL or INVOKE statements and
The permanent logical file structure in function at run time as an entity.
which each record is uniquely identified
844 Enterprise COBOL for z/OS, V5.2 Programming Guide
S * separately compiled program
A program that, together with its
SBCS See single-byte character set (SBCS).
contained programs, is compiled
scope terminator separately from all other programs.
A COBOL reserved word that marks the
* separator
end of certain PROCEDURE DIVISION
A character or two or more contiguous
statements.It can be either explicit
characters used to delimit character
(END-ADD, for example) or implicit
strings.
(separator period).
* separator comma
* section
A comma (,) followed by a space used to
A set of zero, one, or more paragraphs or
delimit character strings.
entities, called a section body, the first of
which is preceded by a section header. * separator period
Each section consists of the section header A period (.) followed by a space used to
and the related section body. delimit character strings.
* section header * separator semicolon
A combination of words followed by a A semicolon (;) followed by a space used
separator period that indicates the to delimit character strings.
beginning of a section in any of these
sequence structure
divisions: ENVIRONMENT, DATA, or
A program processing logic in which a
PROCEDURE. In the ENVIRONMENT DIVISION
series of statements is executed in
and DATA DIVISION, a section header is
sequential order.
composed of reserved words followed by
a separator period. The permissible * sequential access
section headers in the ENVIRONMENT An access mode in which logical records
DIVISION are: are obtained from or placed into a file in
CONFIGURATION SECTION. a consecutive predecessor-to-successor
INPUT-OUTPUT SECTION. logical record sequence determined by the
order of records in the file.
The permissible section headers in the
* sequential file
DATA DIVISION are:
A file with sequential organization.
FILE SECTION.
WORKING-STORAGE SECTION. * sequential organization
LOCAL-STORAGE SECTION. The permanent logical file structure in
LINKAGE SECTION. which a record is identified by a
predecessor-successor relationship
In the PROCEDURE DIVISION, a section established when the record is placed into
header is composed of a section-name, the file.
followed by the reserved word SECTION,
followed by a separator period. 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.
selection structure session bean
A program processing logic in which one In EJB, an enterprise bean that is created
or another series of statements is by a client and that usually exists only for
executed, depending on whether a the duration of a single client/server
condition is true or false. session. (Oracle)
* sentence 77-level-description-entry
A sequence of one or more statements, the A data description entry that describes a
last of which is terminated by a separator noncontiguous data item that has
period. level-number 77.
Glossary 845
* sign condition environment, where the source program is
The proposition (for which a truth value compiled, is described.
can be determined) that the algebraic
* source computer entry
value of a data item or an arithmetic
An entry in the SOURCE-COMPUTER
expression is either less than, greater than,
paragraph of the ENVIRONMENT DIVISION;
or equal to zero.
this entry contains clauses that describe
signature the computer environment in which the
(1) The name of an operation and its source program is to be compiled.
parameters. (2) The name of a method
* source item
and the number and types of its formal
An identifier designated by a SOURCE
parameters.
clause that provides the value of a
* simple condition printable item.
Any single condition chosen from this set:
source program
v Relation condition Although a source program can be
v Class condition represented by other forms and symbols,
v Condition-name condition in this document the term always refers
to a syntactically correct set of COBOL
v Switch-status condition
statements. A COBOL source program
v Sign condition commences with the IDENTIFICATION
See also condition and negated simple DIVISION or a COPY statement and
condition. terminates with the end program marker,
if specified, or with the absence of
single-byte character set (SBCS) additional source program lines.
A set of characters in which each
character is represented by a single byte. source unit
See also ASCII and EBCDIC (Extended A unit of COBOL source code that can be
Binary-Coded Decimal Interchange Code). separately compiled: a program or a class
definition. Also known as a compilation
slack bytes unit.
Bytes inserted between data items or
records to ensure correct alignment of special character
some numeric items. Slack bytes contain A character that belongs to the following
no meaningful data. In some cases, they set:
are inserted by the compiler; in others, it
Character Meaning
is the responsibility of the programmer to
+ Plus sign
insert them. The SYNCHRONIZED clause
- Minus sign (hyphen)
instructs the compiler to insert slack bytes
* Asterisk
when they are needed for proper
/ Slant (forward slash)
alignment. Slack bytes between records
= Equal sign
are inserted by the programmer.
$ Currency sign
* sort file , Comma
A collection of records to be sorted by a ; Semicolon
| format 1 SORT statement. The sort file is . Period (decimal point, full stop)
created and can be used by the sort " Quotation mark
function only. ' Apostrophe
( Left parenthesis
* sort-merge file description entry
) Right parenthesis
An entry in the FILE SECTION of the DATA
> Greater than
DIVISION that is composed of the level
< Less than
indicator SD, followed by a file-name, and
: Colon
then followed by a set of file clauses as
_ Underscore
required.
* SOURCE-COMPUTER SPECIAL-NAMES
The name of an ENVIRONMENT DIVISION The name of an ENVIRONMENT DIVISION
paragraph in which the computer
846 Enterprise COBOL for z/OS, V5.2 Programming Guide
paragraph in which environment-names optionally followed by an integer with the
are related to user-specified operator + or -, that identifies a particular
mnemonic-names. element in a table. A subscript can be the
word ALL when the subscripted identifier
* special names entry
is used as a function argument for a
An entry in the SPECIAL-NAMES paragraph
function allowing a variable number of
of the ENVIRONMENT DIVISION; this entry
arguments.
provides means for specifying the
currency sign; choosing the decimal point; * subscripted data-name
specifying symbolic characters; relating An identifier that is composed of a
implementor-names to user-specified data-name followed by one or more
mnemonic-names; relating subscripts enclosed in parentheses.
alphabet-names to character sets or
substitution character
collating sequences; and relating
A character that is used in a conversion
class-names to sets of characters.
from a source code page to a target code
* special registers page to represent a character that is not
Certain compiler-generated storage areas defined in the target code page.
whose primary use is to store information
* superclass
produced in conjunction with the use of a
A class that is inherited by another class.
specific COBOL feature.
See also subclass.
* statement
surrogate pair
A syntactically valid combination of
In the UTF-16 format of Unicode, a pair
words, literals, and separators, beginning
of encoding units that together represents
with a verb, written in a COBOL source
a single Unicode graphic character. The
program.
first unit of the pair is called a high
structured programming surrogate and the second a low surrogate.
A technique for organizing and coding a The code value of a high surrogate is in
computer program in which the program the range X'D800' through X'DBFF'. The
comprises a hierarchy of segments, each code value of a low surrogate is in the
segment having a single entry point and a range X'DC00' through X'DFFF'. Surrogate
single exit point. Control is passed pairs provide for more characters than the
downward through the structure without 65,536 characters that fit in the Unicode
unconditional branches to higher levels of 16-bit coded character set.
the hierarchy.
switch-status condition
* subclass The proposition (for which a truth value
A class that inherits from another class. can be determined) that an UPSI switch,
When two classes in an inheritance capable of being set to an on or off status,
relationship are considered together, the has been set to a specific status.
subclass is the inheritor or inheriting
* symbolic-character
class; the superclass is the inheritee or
A user-defined word that specifies a
inherited class.
user-defined figurative constant.
* subject of entry
syntax (1) The relationship among characters or
An operand or reserved word that
groups of characters, independent of their
appears immediately following the level
meanings or the manner of their
indicator or the level-number in a DATA
interpretation and use. (2) The structure
DIVISION entry.
of expressions in a language. (3) The rules
* subprogram governing the structure of a language. (4)
See called program. The relationship among symbols. (5) The
rules for the construction of a statement.
* subscript
An occurrence number that is represented * system-name
by either an integer, a data-name A COBOL word that is used to
optionally followed by an integer with the communicate with the operating
operator + or -, or an index-name environment.
Glossary 847
T trailer-label
(1) A data-set label that follows the data
* table
records on a unit of recording medium.
A set of logically consecutive items of
(2) Synonym for end-of-file label.
data that are defined in the DATA DIVISION
by means of the OCCURS clause. troubleshoot
To detect, locate, and eliminate problems
* table element
in using computer software.
A data item that belongs to the set of
repeated items comprising a table. * truth value
The representation of the result of the
text deck
evaluation of a condition in terms of one
Synonym for object deck or object module.
of two values: true or false.
* text-name
typed object reference
A user-defined word that identifies library
A data-name that can refer only to an
text.
object of a specified class or any of its
* text word subclasses.
A character or a sequence of contiguous
characters between margin A and margin U
R in a COBOL library, source program, or
* unary operator
pseudo-text that is any of the following
A plus (+) or a minus (-) sign that
characters:
precedes a variable or a left parenthesis in
v A separator, except for space; a an arithmetic expression and that has the
pseudo-text delimiter; and the opening effect of multiplying the expression by +1
and closing delimiters for alphanumeric or -1, respectively.
literals. The right parenthesis and left
parenthesis characters, regardless of Unicode
context within the library, source A universal character encoding standard
program, or pseudo-text, are always that supports the interchange, processing,
considered text words. and display of text that is written in any
of the languages of the modern world.
v A literal including, in the case of
There are multiple encoding schemes to
alphanumeric literals, the opening
represent Unicode, including UTF-8,
quotation mark and the closing
UTF-16, and UTF-32. Enterprise COBOL
quotation mark that bound the literal.
supports Unicode using UTF-16 in
v Any other sequence of contiguous big-endian format as the representation
COBOL characters except comment for the national data type.
lines and the word COPY bounded by
separators that are neither a separator Uniform Resource Identifier (URI)
nor a literal. A sequence of characters that uniquely
names a resource; in Enterprise COBOL,
thread the identifier of a namespace. URI syntax
A stream of computer instructions is defined by the document Uniform
(initiated by an application within a Resource Identifier (URI): Generic Syntax.
process) that is in control of a process.
unit A module of direct access, the dimensions
token In the COBOL editor, a unit of meaning in of which are determined by IBM.
a program. A token can contain data, a
language keyword, an identifier, or other universal object reference
part of the language syntax. A data-name that can refer to an object of
any class.
top-down design
The design of a computer program using unrestricted storage
a hierarchic structure in which related Storage below the 2 GB bar. It can be
functions are performed at each level of above or below the 16 MB line. If it is
the structure. above the 16 MB line, it is addressable
only in 31-bit mode.
top-down development
See structured programming.
848 Enterprise COBOL for z/OS, V5.2 Programming Guide
* unsuccessful execution * verb
The attempted execution of a statement A word that expresses an action to be
that does not result in the execution of all taken by a COBOL compiler or object
the operations specified by that statement. program.
The unsuccessful execution of a statement
volume
does not affect any data referenced by
A module of external storage. For tape
that statement, but can affect status
devices it is a reel; for direct-access
indicators.
devices it is a unit.
UPSI switch
volume switch procedures
A program switch that performs the
System-specific procedures that are
functions of a hardware switch. Eight are
executed automatically when the end of a
provided: UPSI-0 through UPSI-7.
unit or reel has been reached before
URI See Uniform Resource Identifier (URI). end-of-file has been reached.
* user-defined word VSAM file system
A COBOL word that must be supplied by A file system that supports COBOL
the user to satisfy the format of a clause sequential, relative, and indexed
or statement. organizations.
V W
* variable web service
A data item whose value can be changed A modular application that performs
by execution of the object program. A specific tasks and is accessible through
variable used in an arithmetic expression open protocols like HTTP and SOAP.
must be a numeric elementary item.
white space
variable-length item Characters that introduce space into a
A group item that contains a table document. They are:
described with the DEPENDING phrase of v Space
the OCCURS clause.
v Horizontal tabulation
* variable-length record v Carriage return
A record associated with a file whose file
v Line feed
description or sort-merge description
entry permits records to contain a varying v Next line
number of character positions. as named in the Unicode Standard.
* variable-occurrence data item * word
A variable-occurrence data item is a table A character string of not more than 30
element that is repeated a variable characters that forms a user-defined word,
number of times. Such an item must a system-name, a reserved word, or a
contain an OCCURS DEPENDING ON clause in function-name.
its data description entry or be
subordinate to such an item. * WORKING-STORAGE SECTION
The section of the DATA DIVISION that
* variably located group describes WORKING-STORAGE data items,
A group item following, and not composed either of noncontiguous items
subordinate to, a variable-length table in or WORKING-STORAGE records or of both.
the same record. The group item can be
an alphanumeric group or a national workstation
group. A generic term for computers, including
personal computers, 3270 terminals,
* variably located item intelligent workstations, and UNIX
A data item following, and not terminals. Often a workstation is
subordinate to, a variable-length table in connected to a mainframe or to a
the same record. network.
Glossary 849
wrapper and content of XML documents. An XML
An object that provides an interface schema, which is itself expressed in XML,
between object-oriented code and effectively defines a class of XML
procedure-oriented code. Using wrappers documents of a given type, for example,
lets programs be reused and accessed by purchase orders.
other systems.
Z
X
z/OS UNIX file system
x The symbol in a PICTURE clause that can A collection of files and directories that
hold any character in the character set of are organized in a hierarchical structure
the computer. and can be accessed by using z/OS
UNIX.
XML Extensible Markup Language. A standard
metalanguage for defining markup zoned decimal data item
languages that was derived from and is a An external decimal data item that is
subset of SGML. XML omits the more described implicitly or explicitly as USAGE
complex and less-used parts of SGML and DISPLAY and that contains a valid
makes it much easier to write applications combination of PICTURE symbols 9, S, P,
to handle document types, author and and V. The content of a zoned decimal
manage structured information, and data item is represented in characters 0
transmit and share structured information through 9, optionally with a sign. If the
across diverse computing systems. The PICTURE string specifies a sign and the
use of XML does not require the robust SIGN IS SEPARATE clause is specified, the
applications and processing that is sign is represented as characters + or -. If
necessary for SGML. XML is developed SIGN IS SEPARATE is not specified, the
under the auspices of the World Wide sign is one hexadecimal digit that
Web Consortium (W3C). overlays the first 4 bits of the sign
position (leading or trailing).
XML data
Data that is organized into a hierarchical
#
structure with XML elements. The data
definitions are defined in XML element | 85 COBOL Standard
type declarations. The COBOL language defined by the
following standards:
XML declaration
XML text that specifies characteristics of v ANSI INCITS 23-1985, Programming
the XML document such as the version of languages - COBOL, as amended by
XML being used and the encoding of the ANSI INCITS 23a-1989, Programming
document. Languages - COBOL - Intrinsic Function
Module for COBOL and ANSI INCITS
XML document 23b-1993, Programming Languages -
A data object that is well formed as Correction Amendment for COBOL
defined by the W3C XML specification.
v ISO 1989:1985, Programming languages -
XML namespace COBOL, as amended by ISO/IEC
A mechanism, defined by the W3C XML 1989/AMD1:1992, Programming languages
Namespace specifications, that limits the - COBOL: Intrinsic function module and
scope of a collection of element names ISO/IEC 1989/AMD2:1994, Programming
and attribute names. A uniquely chosen languages - Correction and clarification
XML namespace ensures the unique amendment for COBOL
identity of an element name or attribute
| 2002 COBOL Standard
name across multiple XML documents or
The COBOL language defined by the
multiple contexts within an XML
following standards:
document.
v INCITS/ISO/IEC 1989-2002,
XML schema Information Technology - Programming
A mechanism, defined by the W3C, for Languages - COBOL
describing and constraining the structure
850 Enterprise COBOL for z/OS, V5.2 Programming Guide
v ISO/IEC 1989:2002, Information
technology -- Programming languages
-- COBOL
Glossary 851
852 Enterprise COBOL for z/OS, V5.2 Programming Guide
List of resources
z/OS DFSMS
Enterprise COBOL for z/OS
v Access Method Services for Catalogs
COBOL for z/OS publications v Checkpoint/Restart
You can find the following publications in the v Macro Instructions for Data Sets
Enterprise COBOL for z/OS library: v Using Data Sets
v Customization Guide, SC14-7380 v Utilities
v Language Reference, SC14-7381
z/OS DFSORT
v Programming Guide, SC14-7382
v Application Programming Guide
v Migration Guide, GC14-7383
v Installation and Customization
v Program Directory, GI11-9180
v Licensed Program Specifications, GI11-9181 z/OS ISPF
v Dialog Developer's Guide and Reference
Softcopy publications
v User's Guide Vol I
The following collection kits contain Enterprise v User's Guide Vol II
COBOL and other product publications. You can
find them at http://www-05.ibm.com/e- z/OS Language Environment
business/linkweb/publications/servlet/pbi.wss. v Concepts Guide
v z/OS Software Products Collection v Customization
v z/OS and Software Products DVD Collection v Debugging Guide
v Programming Guide
Support
v Programming Reference
Performance Tuning, www.ibm.com/support/ v Run-Time Messages
docview.wss?uid=swg27018287 v Run-Time Application Migration Guide
v Language Environment Vendor Interfaces
If you have a problem using Enterprise COBOL
for z/OS, see the following site, which provides v Writing Interlanguage Communication Applications
up-to-date support information:
www.ibm.com/software/awdtools/cobol/zos/ z/OS MVS
support. v JCL Reference
v JCL User's Guide
Related publications v Program Management: User's Guide and Reference
v System Commands
z/OS library publications
v z/OS Unicode Services User's Guide and Reference
You can find the following publications in the v z/OS XML System Services User's Guide and
z/OS Internet Library. Reference
Run-Time Library Extensions z/OS TSO/E
v DWARF/ELF Extensions Library Reference v Command Reference
v Common Debug Architecture Library Reference v Primer
v Common Debug Architecture Users Guide v User's Guide
z/Architecture z/OS UNIX System Services
v Principles of Operation v Command Reference
Copyright IBM Corp. 1991, 2015 853
v Programming: Assembler Callable Services Java
Reference v IBM SDK for Java - Tools Documentation,
v User's Guide publib.boulder.ibm.com/infocenter/javasdk/
tools/index.jsp
z/OS XL C/C++ v The Java 2 Enterprise Edition Developer's Guide,
v Programming Guide download.oracle.com/javaee/1.2.1/devguide/
v Run-Time Library Reference html/DevGuideTOC.html
v Java 2 on z/OS, www.ibm.com/servers/eserver/
CICS Transaction Server for z/OS zseries/software/java/
v The Java EE 5 Tutorial, download.oracle.com/
You can find the following publications in the javaee/5/tutorial/doc/
CICS Library:
v The Java Language Specification, Third Edition, by
v Application Programming Guide Gosling et al., java.sun.com/docs/books/jls/
v Application Programming Reference v The Java Native Interface, download.oracle.com/
v Customization Guide javase/1.5.0/docs/guide/jni/
v External Interfaces Guide v JDK 5.0 Documentation, download.oracle.com/
javase/1.5.0/docs/
DB2 for z/OS
Unicode and character representation
You can find the following publications in the v Unicode, www.unicode.org/
DB2 Library:
v Character Data Representation Architecture
v Application Programming and SQL Guide Reference and Registry, SC09-2190
v Command Reference
v SQL Reference XML
v Extensible Markup Language (XML),
Debug Tool www.w3.org/XML/
v Namespaces in XML 1.0, www.w3.org/TR/xml-
You can find the following publications in the names/
Debug Tool Library:
v Namespaces in XML 1.1, www.w3.org/TR/xml-
v Reference and Messages names11/
v User's Guide v XML specification, www.w3.org/TR/xml/
You can find the following publications by
searching their publication numbers in the IBM
Publications Center.
IMS
v Application Programming API Reference,
SC18-9699
v Application Programming Guide, SC18-9698
WebSphere Application Server for z/OS
v Applications, SA22-7959
Softcopy publications for z/OS
The following collection kit contains z/OS and
related product publications:
v z/OS CD Collection Kit, SK3T-4269
854 Enterprise COBOL for z/OS, V5.2 Programming Guide
Index
Special characters Numerics ALL31 runtime option
multioption interaction 40
_BPX_SHAREAS environment 16 MB line OFF for AMODE switching 469
variable 457 CICS programs 420 ALLOCATE command (TSO)
_CEE_ENVFILE environment variable IMS programs 420 compiler data sets 262
description 455 performance options 659 with z/OS UNIX files 263
indicating Java settings 297 24-bit addressing mode 39 allocation of files
_CEE_RUNOPTS environment variable 31-bit addressing mode 39 description 157
description 455 dynamic call 469 line-sequential 215
setting XPLINK 299 64-bit addressing QSAM 174
specifying runtime options 453 no support 39 under TSO 262
_IGZ_SYSOUT environment variable VSAM 206
setting 455 ALPHABET clause, establishing collating
writing to stdout or stderr 36
-# cob2 option for displaying compile and
A sequence with 6
a suffix with cob2 289 alphabetic data
link steps 288 comparing to national 149
a.out file from cob2 289
-b cob2 option MOVE statement with 32
abends, compile-time 322
for creating DLLs 286 alphanumeric comparison 98
ACCEPT statement
for passing information to the alphanumeric data
assigning input 35
linker 287 comparing
reading from stdin 35
-c cob2 option for compiling but not effect of ZWB 372
under CICS 421
linking 287 to national 149
access method services
-comprc_ok cob2 option for controlling converting
build alternate indexes in
compiler based on return code 287 to DBCS with IGZCA2D 685
advance 209
-e cob2 option for specifying entry to national with MOVE 138
defining VSAM data sets to
point 287 to national with
z/OS 203
-g cob2 option equivalent to specifying NATIONAL-OF 139
loading a VSAM data set 197
TEST 288 MOVE statement with 32
accessibility
-I cob2 option for searching with double-byte characters 685
of Enterprise COBOL xxii
copybooks 288 alphanumeric group item
of this information xxiii
-l cob2 option for specifying archive a group without GROUP-USAGE
using z/OS xxii
library name 288 NATIONAL 25
ADATA compiler option 305
-L cob2 option for specifying archive definition 24
adding records
library path 288 alphanumeric literals
to line-sequential files 217
-o cob2 option for specifying output conversion of mixed
to QSAM files 172
file 288 DBCS/EBCDIC 685
to VSAM files 199
-q cob2 option for specifying compiler description 25
ADDRESS OF special register
options 288 with DBCS content 151
use in CALL statement 482
-v cob2 option for displaying and with double-byte characters 685
addresses
executing compile and link steps 288 alphanumeric-edited data
incrementing 487
! character, hexadecimal values 540 initializing
NULL value 487
.a suffix with cob2 289 example 29
passing between programs 487
.adt file 305 using INITIALIZE 74
passing entry-point addresses 477
.adt suffix with cob2 289 MOVE statement with 32
addressing mode, definition 39
.cbl suffix with cob2 288 alternate collating sequence
ADEXIT suboption of EXIT option
.dbg suffix with cob2 289 choosing 229
processing of 707
.dek suffix with cob2 289 example 7
syntax 325
.lst suffix with cob2 289 alternate entry point, calling 479
ADMODE attribute
.o suffix with cob2 289 alternate index
with multithreading 513
.x suffix with cob2 289 creating 204
adt suffix with cob2 289
*CBL statement 373 example of 205
ADV compiler option 306
*CONTROL statement 373 password for 202
AFP compiler option 306
[ character, hexadecimal values 540 path 204, 205
performance considerations 659
] character, hexadecimal values 540 performance considerations 210
AIXBLD runtime option
| character, hexadecimal values 540 using 189
effect on performance 663
# character, hexadecimal values 540 ALTERNATE RECORD KEY clause
ALL subscript
| 85 COBOL Standard identify alternate indexes 205
examples 89
checkpoints 642 identifying alternate keys in KSDS
processing table elements
required compiler options 304 files 189
iteratively 89
required runtime options 304 alternate reserved-word table
table elements as function
arguments 58 CICS 427
Copyright IBM Corp. 1991, 2015 855
alternate reserved-word table (continued) assembler BLANK WHEN ZERO clause (continued)
specifying 367 expansion of PROCEDURE example with numeric-edited
AMODE DIVISION 397 data 45
and DLLs 502 programs BLOCK CONTAINS clause
description 39 calls from (in CICS) 421 FILE SECTION entry 13
of EXIT modules 702 compiling from 265 no meaning for VSAM files 192
switching listing of 333, 657 QSAM files 161, 168, 310
ALL31(OFF) 469 with multithreading 513 block size
examples 469 ASSIGN clause ASCII files 183
overview 469 corresponds to ddname 8 compiler data sets 268
AMP parameter 206 QSAM files 160 QSAM files 168, 310
ANNUITY intrinsic function 62 assigning values 27 fixed-length 161
APIs, UNIX and POSIX assistive technologies xxii record layout 163
calling 456 associated-data file, creating 271 using DCB 176
APOST compiler option 348 asynchronous signals with variable-length 162
APPLY WRITE-ONLY clause 10 multithreading 513 system-determined
ARCH compiler option 307 AT END (end-of-file) phrase 244 compiler data sets 268
performance considerations 659 ATTACH macro 265 QSAM files 168, 310
arguments attribute methods 593 BLOCK0 compiler option
describing in calling program 483 automatic restart 645 description 310
from main program available files performance considerations 659
accessing in z/OS 495 QSAM 171 blocking factor, definition 161
accessing in z/OS UNIX 458 VSAM 202 blocking QSAM files
passing BY VALUE 483 AWO compiler option using BLOCK CONTAINS clause 168
specifying OMITTED 485 APPLY-WRITE ONLY clause using BLOCK0 310
testing for OMITTED arguments 485 performance 10 blocking records 168
ARITH compiler option description 310 BPXBATCH utility
description 309 performance considerations 659 calling z/OS UNIX programs 454
performance considerations 659 running OO applications 296
arithmetic branch, implicit 102
COMPUTE statement simpler to
code 56
B buffers
best use of 10
Base class
error handling 240 obtaining for QSAM 181
equating to java.lang.Object 585
with intrinsic functions 57 BUFSIZE compiler option 311
using for java.lang.Object 584
arithmetic comparisons 63 BY CONTENT 481
base cluster name 205
arithmetic evaluation BY REFERENCE 481
base locator 393, 394
conversions and precision 52 BY VALUE
base locator table 409
data format conversion 52 description 481
basis libraries 270
examples 62, 64 restrictions 483
BASIS statement 373
fixed-point contrasted with valid data types 483
batch compilation
floating-point 62 byte order mark not generated 567
description 275
intermediate results 675 byte-stream files
LANGUAGE option
performance tips 653 processing with QSAM 181
example 279
precedence 57, 677
precedence of options
precision 675
example 278
arithmetic expression
as reference modifier 114
overview 277 C
Bibliography 853 C/C++ programs
description of 57
big-endian, converting to with COBOL DLLs 505
in nonarithmetic statement 683
little-endian 130 with multithreading 513
in parentheses 57
binary data item c89 command for link step 285
arrays
general description 48 CALL command (TSO) 262
COBOL 39
intermediate results 680 CALL identifier
Java
synonyms 47 always dynamic 469
declaring 629
using efficiently 48, 653 dynamic calls 467
manipulating 630
binary search making from DLLs 500
ASCII
description 87 with NODLL 467
alphabet, QSAM 182
example 88 with NODYNAM 471
code pages supported in XML
binder CALL literal
documents 536
c89 command 285 dynamic calls 467
converting to EBCDIC 119
options needed for DLLs 499 static calls 466
job control language (JCL) 183
recommended for DLLs 499 with DYNAM 467
record formats, QSAM 183
binding OO applications with NODLL 466, 467
tape files, QSAM 182
example 298 with NODYNAM 466, 471
ASCII files
using JCL or TSO/E 296 CALL statement
CODE-SET clause 14
BLANK WHEN ZERO clause AMODE processing 469
OPTCD= parameter in DCB 14
coded for numeric data 131 BY CONTENT 481
BY REFERENCE 481
856 Enterprise COBOL for z/OS, V5.2 Programming Guide
CALL statement (continued) CBL statement CICS (continued)
BY VALUE overview 373 DFHCOMMAREA parameter
description 481 specifying compiler options 273 calling nested programs 422
restrictions 483 cbl suffix with cob2 288 calling separately compiled
CICS restrictions 421 CBLPSHPOP runtime option 428 programs 421
effect of EXIT option on registers 702 CBLQDA runtime option 171 DFHEIBLK parameter
exception condition 250 CCSID calling nested programs 422
for error handling 250 conflict in XML documents 545 calling separately compiled
function-pointer 479 definition 129 programs 421
handling of program-name in 345 EBCDIC multibyte CCSIDs 315 ECI calls and RETURN-CODE special
Language Environment callable in PARSE statement 520 register 423
services 669 of DB2 string data 437 EXIT compiler option and 718
overflow condition 250 of XML documents 536 in a multithreaded environment 513
RETURNING 491 of XML documents to be parsed 520 integrated translator
to alternate entry points 479 specifying with CODEPAGE advantages 425
USING 483 option 313 calling nested programs 422
with CANCEL 468 chained-list processing compiler options for 424
with DYNAM 323 example 488 overview 425
with ON EXCEPTION 250 overview 487 interlanguage communication
with ON OVERFLOW 20, 250 changing under 422
calls characters to numbers 117 macro-level interface 419
31-bit addressing mode 469 file-name 9 NODYNAM compiler option 422
AMODE switching for 24-bit title on source listing 5 performance
programs 469 CHAR intrinsic function, example 119 overview 651
between COBOL and non-COBOL character set, definition 129 performance considerations 428, 662
programs 463 CHECK runtime option restrictions
between COBOL programs 463, 465 performance considerations 661 16 MB line 420
CICS restrictions 421 checking for valid data files 5
dynamic conditional expressions 98 OO programs 419, 579
example 472 checkpoint OUTDD compiler option 344
| making 467 85 COBOL Standard 642 parsing with validation using
performance 471 designing 642 FILE 531
restrictions 467 example of JCL for restart 647 separate translator 425
with static calls 471 messages generated during 644 sorting 237
exception condition 250 methods 641 separate translator
interlanguage 463 multiple 642, 644 calling nested programs 423
LINKAGE SECTION 485 overview 641 compiler options for 426
OMITTED arguments 485 record data set 643 restrictions 425
overflow condition 250 restart during DFSORT 236 using 426
passing arguments 483 restrictions during sort 642 sorting under
passing data 481 setting 641 change reserved-word table 428
receiving parameters 484 single 642 overview 237
recursive 477 disk 644 restrictions 237
static tape 643 system date, getting 421
example 472 testing 643 CICS compiler option
making 466 Chinese GB 18030 data description 312
performance 471 processing 146 enables integrated translator 425
with dynamic calls 471 CHKPT keyword 236 multioption interaction 305
to and from object-oriented CICS specifying suboptions 312, 425
programs 477 alternate reserved-word table 427 using 423
to JNI services 623 calling nested programs 422 CISZ (control interval size), performance
to Language Environment callable CICS HANDLE 428 considerations 210, 663
services 669 example 429 CKPT keyword 236
CANCEL statement LABEL value 428 class
cannot use with DLL linkage 502 coding programs to run under defining 582
for subprograms 468 calls 421 definition of 579
handling of program-name in 345 DISPLAY statement 420 factory data 612
with dynamic CALL 468 I/O 420 instance data 586
case structure, EVALUATE statement overview 419 instantiating
for 95 restrictions 419 COBOL 605
cataloged procedure SORT statement 428 Java 605
JCL for compiling 256 command-level interface 419 name
to compile (IGYWC) 257 commands and the PROCEDURE external 585, 597
to compile and link-edit DIVISION 419 in a program 584
(IGYWCL) 258 compiling with CICS option 423 object, obtaining reference with
to compile, link-edit, run developing programs for 419 JNI 624
(IGYWCLG) 259 user-defined 8
Index 857
class condition COBOL (continued) coding (continued)
testing object-oriented (continued) OO programs
for DBCS 151 compiling using JCL or must be reentrant 480
for Kanji 151 TSO/E 295 overview 579
for numeric 54 linking 292 PROCEDURE DIVISION 17
overview 98 running 293 programs to run under CICS
validating data 379 under IMS 448 calls 421
CLASSPATH environment variable COBOL client DISPLAY statement 420
description 455 example 615 I/O 420
example of setting 297 example of passing object must be reentrant 480
specifying location of Java references 602 overview 419
classes 293 COBOL DLL programs, calling 503 restrictions 419
client COBOL terms 23 SORT statement 428
defining 596 COBOL3 translator option 426 system date, getting 421
definition of 596 COBOPT environment variable 283 programs to run under DB2
CLIST for compiling under TSO 264 code CCSID of string data 437
CLOSE statement copy 665 overview 431
line-sequential files 215 optimized 657 stored procedures must be
QSAM 170 code page reentrant 480
VSAM 193 conflict in XML documents 545 programs to run under IMS
closing files DBCS 315 must be reentrant 480
line-sequential 217 definition 129 overview 443
multithreading serialization 510 euro currency support 65 restrictions 443
QSAM hexadecimal values of special simplifying 665
overview 173 characters 540 SQL statements
with multithreading 173 of DB2 string data 437 overview 432
VSAM overriding 140 restriction 432
overview 200 specifying 313 SQLIMS statements
with multithreading 201 specifying for alphanumeric XML overview 444
closing files, automatic document 539 subclasses
line-sequential 217 code point, definition 129 example 610
QSAM 173 CODE-SET clause 14 overview 607
VSAM 200 coded character set tables 67
cluster, VSAM 203 definition 129 techniques 11, 651
cob2 command in XML documents 536 test conditions 99
compiling with CODEPAGE compiler option collating sequence
examples 286 DBCS code pages 315 alternate
overview 285 description 313 choosing 229
description 287 for national literals 137 example 7
for compiling OO applications 291 items that are not affected 314 ASCII 7
for creating DLLs 286 operations that override 314 binary for national keys 228
for linking OO applications 292 coding EBCDIC 7
input and output 288 class definition 582 HIGH-VALUE 7
linking with clients 596 ISO 7-bit code 7
examples 286 condition tests 99 LOW-VALUE 7
overview 285 constructor methods 612 MERGE 7, 229
options and syntax 287 DATA DIVISION 11 NATIVE 7
COBJVMINITOPTIONS environment decisions 93 nonnumeric comparisons 6
variable efficiently 651 ordinal position of a character 119
description 455 ENVIRONMENT DIVISION 5 SEARCH ALL 7
specifying JVM options 295 errors, avoiding 651 SORT 7, 229
COBOL EVALUATE statement 95 specifying 6
and Java factory definition 611 STANDARD-1 7
binding 296 factory methods 612 STANDARD-2 7
communicating between 623 file input/output (overview) 153 symbolic characters in the 8
compatibility 300 IDENTIFICATION DIVISION 3 COLLATING SEQUENCE phrase
compiling under z/OS UNIX 291 IF statement 93 does not apply to national keys 228
compiling using JCL or input/output overview 156 overrides PROGRAM COLLATING
TSO/E 295 input/output statements SEQUENCE clause 6, 229
linking 292 for line-sequential files 215 use in SORT or MERGE 229
running 293, 296 for QSAM files 170 columns in tables 67
structuring applications 620 for VSAM files 193 COMMON attribute 4, 474
under IMS 448 instance methods 587, 609 COMP (COMPUTATIONAL) 48
object-oriented interoperable data types with COMP-1 (COMPUTATIONAL-1)
binding 296 Java 628 format 50
compiling under z/OS UNIX 291 loops 101 performance tips 654
858 Enterprise COBOL for z/OS, V5.2 Programming Guide
COMP-2 (COMPUTATIONAL-2) compiler data sets compiler options (continued)
format 50 in the z/OS UNIX file system 256, IMS, recommended for 447
performance tips 654 261 in effect 399
COMP-3 (COMPUTATIONAL-3) 50 input and output 267 INTDATE 331
COMP-4 (COMPUTATIONAL-4) 48 required for compilation 267 LANGUAGE
COMP-5 (COMPUTATIONAL-5) 49 SYSADATA (ADATA records) 271 description 331
comparing data items 370 SYSIN 269 example in batch compilation 279
national SYSJAVA 272 LINECOUNT 332
overview 147 SYSLIB (libraries) 270 LIST 333, 387
to alphabetic, alphanumeric, or SYSLIN (object code) 271 MAP 333, 386, 387
DBCS 149 SYSMDECK (library processing) 272 MAXPCF 335
to alphanumeric groups 149 SYSOPTF 269 MAXPCF(nnn)
to numeric 148 SYSOUT (listing) 270 performance considerations 660
two operands 148 SYSPUNCH (object code) 271 MDECK 336
object references 599 SYSTERM (messages) 271 NAME 337
zoned decimal and alphanumeric, with cob2 288 NOCOMPILE 382
effect of ZWB 372 compiler listings NOFASTSRT 233
compatibility getting 387 NSYMBOL 338
Java and COBOL 300 compiler options NUMBER 339, 389
| object-oriented syntax 300 85 COBOL Standard NUMPROC 339
compatibility mode 43, 675 conformance 304 NUMPROC(PFD)
compilation abbreviations 301 performance considerations 660
| conformance to 85 COBOL ADATA 305 NUMPROC(PFD|NOPFD) 54
| Standard 304 ADV 306 OBJECT 340
results 274 AFP 306 OFFSET 341
with z/OS UNIX files 258 performance considerations 659 on compiler invocation 391
compilation statistics 391 APOST 348 OPTFILE 342
COMPILE compiler option ARCH 307 OPTIMIZE
description 316 performance considerations 659 description 343
use NOCOMPILE to find syntax ARITH performance considerations 657,
errors 382 description 309 660
compile-time considerations performance considerations 659 OUTDD 344
compiler-directed errors 280 AWO performance considerations 659
display compile and link steps 288 description 310 PGMNAME 345
dump, generating a 322 performance considerations 659 precedence of
error messages BLOCK0 example 278
determining what severity level to description 310 in batch 277
produce 327 performance considerations 659 in SYSOPTF data sets 270, 342
severity levels 282 BUFSIZE 311 under z/OS 272
executing compile and link steps after CICS 312 under z/OS UNIX 284
display 288 CODEPAGE 313 QUALIFY 347
compiler COMPILE 316 QUOTE 348
calculation of intermediate conflicting 304 RENT
results 676 COPYRIGHT 316 description 348
environment variables under z/OS CURRENCY 317 performance considerations 660
UNIX 283 DATA 318 RMODE
generating list of error messages 280 DBCS 318 description 349
invoking in the z/OS UNIX shell DECK 319 performance considerations 661
examples 286 DIAGTRUNC 319 RULES 350
overview 285 DISPSIGN 320 SEQUENCE 352
limits DLL 321 SERVICE 353
DATA DIVISION 11 DUMP 322 signature information bytes 399
messages DYNAM 323, 660 SOURCE 353, 387
choosing severity to be EXIT 324 SPACE 354
flagged 384 EXPORTALL 326 specifying 272
customizing 710 FASTSRT 231, 327 using PROCESS (CBL) 273
determining what severity level to performance considerations 660 specifying under TSO 274
produce 327 FLAG 327, 384 specifying under z/OS 274
embedding in source listing 384 FLAGSTD 328 specifying under z/OS UNIX 284
from exit modules 717 for CICS integrated translator 424 specifying with SYSOPTF data
sending to terminal 271 for CICS separate translator 423, 426 set 269
severity levels 282, 711 for debugging SQL
return code overview 382 description 354
depends on highest severity 282 TEST restriction 380 using with DB2 435
effect of message THREAD restriction 380 SQLCCSID
customization 712 HGPR 330 description 355
overview 282 performance considerations 660
Index 859
compiler options (continued) compiling and linking in the z/OS UNIX continuation
SQLCCSID (continued) shell (continued) entry 235
effect on CCSID of string examples 286 of program 241
data 437 OO applications syntax checking 316
performance considerations 438 cob2 command 292 CONTINUE statement 93
recommended with DB2 example 293 control
coprocessor 438 overview 285 in nested programs 474
SQLIMS 356 completion code program flow 93
SSRANGE 357, 383 merge 230 transfer 463
performance considerations 661 sort 230 control interval size (CISZ), performance
status 391 complex OCCURS DEPENDING ON considerations 210, 663
STGOPT 358 basic forms of 81 CONTROL statement 373
table of 301 complex ODO item 82 converting data items
TERMINAL 359 variably located data item 82 between code pages 119
TEST variably located group 82 between data formats 52
description 359 computation exceptions with national data 140
performance considerations 661 arithmetic data items 653 precision 52
use for debugging 387 of indexes 72 reversing order of characters 117
THREAD of subscripts 656 to alphanumeric
debugging restriction 380 COMPUTATIONAL (COMP) 48 with DISPLAY 36
description 362 COMPUTATIONAL-1 (COMP-1) with DISPLAY-OF 139
performance considerations 661 format 50 to Chinese GB 18030 from
TRUNC performance tips 654 national 146
description 363 COMPUTATIONAL-2 (COMP-2) to integers with INTEGER,
performance considerations 661 format 50 INTEGER-PART 114
under IMS and CICS 420 performance tips 654 to national
VBREF 366, 387 COMPUTATIONAL-3 (COMP-3) from Chinese GB 18030 146
VLR description 50 from UTF-8 141
description 366 COMPUTATIONAL-4 (COMP-4) 48 with ACCEPT 35
WORD 367 COMPUTATIONAL-5 (COMP-5) 49 with MOVE 138
XMLPARSE 368 COMPUTE statement with NATIONAL-OF 139
XREF 369, 386 assigning arithmetic results 34 to numbers with NUMVAL,
ZONEDATA 370 simpler to code 56 NUMVAL-C 117
ZWB 372 computer, describing 5 to uppercase or lowercase
Compiler options concatenating data items (STRING) 105 with INSPECT 116
listing example 405 condition handling with intrinsic functions 117
compiler-directing statements closing QSAM files 173 to UTF-8 from national 141
description 373 closing VSAM files 200 with INSPECT 115
overview 20 in input or output procedures 225 with intrinsic functions 116
compiling using Language Environment 667 CONVERTING phrase (INSPECT),
batch 275 condition testing 99 example 116
control of 272 conditional expression coprocessor, DB2
data sets for 267 EVALUATE statement 93 CCSID determination of string
DLLs 286 IF statement 93 data 437
from an assembler program 265 PERFORM statement 103 differences from the precompiler 439
OO applications conditional statement enable with SQL compiler option 435
cob2 command 291 overview 19 overview 431
example 293, 298 with NOT phrase 19 recommended compiler option
under z/OS UNIX 291 with object references 599 SQLCCSID 438
using JCL or TSO/E 295 CONFIGURATION SECTION 5 using SQL INCLUDE with 433
under TSO conflicting compiler options 304 coprocessor, IMS
example CLIST 264 conformance requirements enable with SQLIMS compiler
| overview 262 85 COBOL Standard 304 option 446
under z/OS 255 example of passing object references overview 443
under z/OS UNIX 283 in INVOKE 602 copy libraries
using shell script 290 RETURNING phrase of INVOKE 603 COPY statement 373
using the cob2 command USING phrase of INVOKE 601 data set 267
examples 286 Constant area 409 example 666
overview 285 constants search order 374
with cataloged procedures 256 data items 652 specifying 270
compile 257 definition 26 SYSLIB 270
compile and link-edit 258 figurative, definition 26 z/OS UNIX search order 284, 288
compile, link-edit, run 259 contained program integration 658 COPY statement
with JCL (job control language) 256 CONTENT-CHARACTERS XML event DB2 considerations 439
compiling and linking in the z/OS UNIX example 557 description 373
shell when parsing segments 534 example 666
DLLs 286 nested 665, 704
860 Enterprise COBOL for z/OS, V5.2 Programming Guide
COPY statement (continued) data (continued) data item (continued)
z/OS considerations 270 incompatible 54 evaluating with intrinsic
z/OS UNIX considerations 374 naming 12 functions 119
copybook numeric 43 finding the smallest or largest
description 373 passing 481 item 120
obtaining from user-supplied record size 13 group, definition 24
module 325 splitting (UNSTRING) 107 index, referring to table elements
searching for 288, 374 validating 54 with 70
copybook cross-reference, data and procedure-name cross-reference, initializing, examples of 28
description 386 description 386 map 274
copybooks data areas, dynamic 323 numeric 43
cross-reference 413 DATA compiler option reference modification 111
using 665 description 318 referring to a substring 111
COPYRIGHT compiler option 316 influencing data location 42 replacing characters (INSPECT) 115
COUNT IN phrase multioption interaction 40 reversing characters 117
UNSTRING 107 performance considerations 659 splitting (UNSTRING) 107
XML GENERATE 567 when passing data 41 unused 343, 393
counting data definition 393 variably located 82
characters (INSPECT) 115 data description entry 11 data manipulation
generated XML characters 562 DATA DIVISION character data 105
creating client 598 DBCS data 685
associated-data file 271 coding 11 DATA RECORDS clause 13
library-processing output file 272 description 11 data set
line-sequential files in z/OS 215 entries for line-sequential files 214 alternate data-set names 265
object code 271 entries for QSAM files 160 checkpoint record 643
objects 604 entries for VSAM files 192 compiler-option 269
QSAM files, z/OS 174, 177 factory data 612 defining with environment
SYSJAVA file 272 factory method 613 variable 157
variable-length tables 78 FD entry 11 example of checkpoint/restart 647
cross-reference FILE SECTION 11 file, same meaning as 5
COPY/BASIS 413 GROUP-USAGE NATIONAL JAVAERR 297
COPY/BASIS statements 387 clause 68 JAVAIN 297
copybooks 387 instance data 586, 609 JAVAOUT 297
data and procedure-names 386 instance method 589 names, alternate 265
embedded 387 items present in 399 output 270
list 369 limits 11 source code 269
program-name 412 LINKAGE SECTION 11, 16 SYSADATA 271
special definition symbols 414 listing 387 SYSIN 269
text-names and data sets 386 LOCAL-STORAGE SECTION 11 SYSJAVA 272
verb list 366 mapping of items 333, 387 SYSLIB 270
verbs 387 OCCURS clause 67 SYSLIN 271
CRP (file position indicator) 195, 198 OCCURS DEPENDING ON (ODO) SYSMDECK 272
CURRENCY compiler option 317 clause 78 SYSOPTF 269
currency signs REDEFINES clause 75 SYSPRINT 270
euro 65 restrictions 11 SYSPUNCH 271
hexadecimal literals 65 signature information bytes 399 SYSTERM 271
multiple-character 65 USAGE clause at the group level 25 data sets used for compiling 267
using 65 USAGE IS INDEX clause 72 data-definition attribute codes 393
CURRENT-DATE intrinsic function USAGE NATIONAL clause at the data-name
example 61 group level 134 cross-reference 411
under CICS 421 WORKING-STORAGE SECTION 11 cross-reference list 275
customer support xviii, 853 data item in MAP listing 393
alphanumeric with double-byte OMITTED 13
characters 685 password for VSAM files 202
D coding Java types 627
common, in subprogram linkage 484
date and time operations
Language Environment callable
D-format record
concatenating (STRING) 105 services 667
layout 163
converting characters (INSPECT) 115 date operations
requesting 162
converting characters to numbers 117 finding date of compilation 123
DASD (direct-access storage device) 210
converting to uppercase or DATE-COMPILED paragraph 3
data
lowercase 117 DATE-OF-INTEGER intrinsic
concatenating (STRING) 105
converting with intrinsic function 61
converting between alphanumeric and
functions 116 DB2
DBCS 685
counting characters (INSPECT) 115 coding considerations 431
efficient execution 651
DBCS 685 coprocessor
format conversion of 52
elementary, definition 24 CCSID determination of string
format, numeric types 46
data 437
grouping 486
Index 861
DB2 (continued) DD control statement (continued) DELETE statement (continued)
coprocessor (continued) ASCII tape files 183 VSAM, coding 193
database request module creating QSAM files 174, 177 deleting records from VSAM file 200
(DBRM) 432, 436 DBRMLIB 436 delimited scope statement
differences from the DCB overrides data-set label 176 description of 19
precompiler 439 define file 8 nested 21
enable with SQL compiler defining merge data sets 226 DEPENDING ON clause 162, 192
option 435 defining sort data sets 226 depth in tables 69
overview 431 JAVAERR 297 device
recommended compiler option JAVAIN 297 classes 267
SQLCCSID 438 JAVAOUT 297 requirements 267
using SQL INCLUDE with 433 RLS parameter 207 DFHCOMMAREA parameter
DYNAM compiler option with TSO or SYSADATA 271 calling nested CICS programs 422
IMS 441 SYSIN 269 calling separately compiled CICS
NODYNAM compiler option with SYSJAVA 272 programs 421
CICS or CAF 441 SYSLIB 270 DFHEIBLK parameter
precompiler SYSLIN 271 calling nested CICS programs 422
differences from the SYSMDECK 272 calling separately compiled CICS
coprocessor 439 SYSOPTF 269 programs 421
recommended compiler option SYSPRINT 270 DFSORT
NOSQLCCSID 438 SYSPUNCH 271 defining data sets for 226
specifying code page for host ddname definition 8 error message for RETURN
variables 433 deadlock in I/O error declarative 244 statement 224
SQL compiler option 435 Debug Tool diagnostics, program 391
SQL statements compiler options for 387 DIAGTRUNC compiler option 319
CCSID determination 437 description 377 direct-access
coding 432 debugging direct indexing 72
overview 431 and performance 360 file organization 154
return codes 435 compiler options for storage device (DASD) 210
SQL DECLARE 433 overview 382 directories
SQL INCLUDE 433 TEST restriction 380 adding a path to 288
using binary data in 435 THREAD restriction 380 disability xxii
using character data in 433 overview 377 DISPLAY (USAGE IS)
using national decimal data 434 runtime options for 380 encoding and storage 137
SQLCCSID compiler option 437 using COBOL language features 378 external decimal 47
DBCS comparison 98 using the debugger 387 floating point 48
DBCS compiler option debugging, language features display floating-point data (USAGE
description 318 class test 379 DISPLAY) 48
for Java interoperability 291, 295 debugging lines 380 DISPLAY statement
for OO COBOL 291, 295 debugging statements 380 directing output 344
multioption interaction 305 declaratives 380 displaying data values 35
DBCS data DISPLAY statements 378 displaying on the system logical
comparing file status keys 379 output device 36
to national 149 INITIALIZE statements 380 interaction with OUTDD 36
converting scope terminators 378 suppressing line spacing 37
to alphanumeric with SET statements 380 under CICS 420
IGZCD2A 688 WITH DEBUGGING MODE using in debugging 378
to and from alphanumeric 685 clause 380 writing to stdout or stderr 36
to national, overview 152 DECK compiler option 319 DISPLAY-1 (USAGE IS)
declaring 150 declarative procedures encoding and storage 137
encoding and storage 137 EXCEPTION/ERROR 244 DISPLAY-OF intrinsic function
literals with multithreading 244 example with Chinese data 147
description 26 USE FOR DEBUGGING 380 example with Greek data 140
maximum length 151 deferred restart 645 example with UTF-8 data 141
using 150 defining using 139
MOVE statement with 32 files, overview 8, 153 with XML documents 538
notation for 685 libraries 270 DISPSIGN compiler option 320
testing for 151 line-sequential files to z/OS 215 DLL compiler option
dbg suffix with cob2 289 QSAM files description 321
DBRM data set to z/OS 174, 177 for Java interoperability 291, 295
defining 436 sort or merge files under z/OS 226 for OO COBOL 291, 295
description 432 VSAM files multioption interaction 305
DBRMLIB DD statement 432, 436 to z/OS 203 DLL igzcjava.x
DCB 169 dek suffix with cob2 289 binding with
DD control statement DELETE statement example 298
allocating line-sequential files 215 compiler-directing 375 preparing OO applications 297
AMP parameter 206 multithreading serialization 510
862 Enterprise COBOL for z/OS, V5.2 Programming Guide
DLL igzcjava.x (continued) dynamic link libraries (continued) ENVIRONMENT DIVISION (continued)
linking with using with OO 293 instance method 589
example 293 items present in, program
preparing OO applications 292 initialization code 399
DLL libjvm.x
binding with
E signature information bytes 399
subclass 609
E-level error message 282, 384
example 298 environment variables
EBCDIC
preparing OO applications 297 _BPX_SHAREAS 457
code pages supported in XML
linking with _CEE_ENVFILE
documents 536
example 293 description 455
converting to ASCII 119
preparing OO applications 292 indicating Java settings 297
JNI services 633
with EBCDIC services 634 _CEE_RUNOPTS
multibyte CCSIDs supported for
DLLs (see dynamic link libraries) 497 description 455
DBCS 315
do loop 103 setting XPLINK 299
ECI calls and RETURN-CODE special
do-until 103 specifying runtime options 453
register 423
do-while 103 _IGZ_SYSOUT 455
efficiency of coding 651
documentation of program 5 allocating line-sequential files 215
EJECT statement 375
DSA memory map 397 and copybooks 373
embedded cross-reference
dump CLASSPATH
description 387
requesting 239 description 455
example 414
with DUMP compiler option 274 example of setting 297
embedded error messages 384
DUMP compiler option specifying location of Java
embedded MAP summary 386, 394
description 322 classes 293
enclave 463
output 274 COBJVMINITOPTIONS
encoding
DYNAM compiler option description 455
conflicts in XML documents 545
description 323 specifying JVM options 295
controlling in generated XML
multioption interaction 305 COBOPT 283
output 566
performance considerations 660 compiler 283
description 137
under DB2 with TSO or IMS 441 defining files, example 8
language characters 129
with dynamic calls 467 defining QSAM files 174
of XML documents 536, 537
dynamic calls example of setting and accessing 456
of XML documents to be parsed 520
example 472 LIBPATH
specifying for alphanumeric XML
making 467 description 455
document 539
performance 471 example of setting 297
specifying with CODEPAGE
restrictions 467 specifying location for COBOL
option 313
using with DLL linkage 502 classes 293
encoding declaration
when to use 468 library-name 284, 373
preferable to omit 539
with static calls 471 PATH
specifying 539
dynamic data areas, allocating description 455
end-of-file (AT END phrase) 244
storage 42 example of setting 297
END-OF-INPUT XML event
dynamic file allocation runtime 455
example 557
order of allocation 157 setting and accessing 454
when parsing segments 533
using CBLQDA 171 STEPLIB
enhancing XML output
using environment variables description 455
example of modifying data
line-sequential files 215 example 285
definitions 573
QSAM files 174 SYSLIB
rationale and techniques 573
VSAM files 206 description 284
ENTER statement 375
dynamic link libraries specifying location of JNI.cpy 291
entry point
about 497 text-name 284, 373
alternate 479
binder options for DLLs 499 using to allocate files 157
alternate in ENTRY statement 478
compiler options required 286 environment-name 5
ENTRY label 479
compiling 498 ERRMSG, for generating list of error
passing entry addresses of 477
creating messages 280
procedure-pointer data item 477
from the z/OS UNIX shell 286 error
ENTRY statement
overview 497 arithmetic 240
for alternate entry points 478
creating for OO 292 compiler options, conflicting 304
handling of program-name in 345
for Java interoperability 292 handling 239
ENVAR runtime option 297
in OO COBOL applications 506 handling for I/O 158
ENVIRONMENT DIVISION
linking 499 listing 274
class 584
programs with DLL support must be message table
client 597
reentrant 480 example using indexing 77
collating sequence coding 6
search order for in z/OS UNIX file example using subscripting 77
CONFIGURATION SECTION 5
system 501 processing
description 5
using CALL identifier with 500 line-sequential files 218
entries for line-sequential files 213
using with C/C++ programs 505 QSAM files 174
entries for QSAM files 159
using with dynamic calls 502 VSAM files 201
entries for VSAM files 188
using with Java interoperability 293 XML GENERATE 567
INPUT-OUTPUT SECTION 5
Index 863
error (continued) EXIT compiler option (continued) FASTSRT compiler option
processing (continued) user-exit work area 701 description 327
XML PARSE 544 using 324 improving sort performance 231, 660
routines for handling 250 exit modules information message 231
error messages called for SYSADATA data set 707 requirements
compiler calling COBOL programs 702 JCL 231
choosing severity to be error messages generated 717 QSAM 232
flagged 384 message severity customization 709 sort input and output files 231
correcting source 280 used in place of library-name 703 VSAM 233
customizing 710 used in place of SYSLIB 703 FD (file description) entry 12
determining what severity level to used in place of SYSPRINT 706 figurative constants
produce 327 EXIT PROGRAM statement definition 26
embedding in source listing 384 in subprogram 464 HIGH-VALUE restriction 132
format 281 with multithreading 464 national-character 132
from exit modules 717 explicit scope terminator 20 file access mode
generating a list of 280 exponentiation choosing 155
location in listing 281 evaluated in fixed-point dynamic 191
sending to terminal 271 arithmetic 678 example 191
severity levels 282, 711 evaluated in floating-point for indexed files (KSDS) 191
compiler-directed 280 arithmetic 683 for relative files (RRDS) 191
ESDS (entry-sequenced data sets) performance tips 654 for sequential files (ESDS) 191
file access mode 191 EXPORTALL compiler option performance considerations 210
organization 188 description 326 random 191
euro currency sign 65 DLL considerations 498 sequential 191
EVALUATE statement multioption interaction 305 summary table of 188
case structure 95 extended mode 43, 675 file allocation 157
coding 95 external class-name 585, 597 file availability
contrasted with nested IFs 96, 97 EXTERNAL clause QSAM files under z/OS 171
example that tests several example for files 492 VSAM files under z/OS 202
conditions 97 for data items 491 file description (FD) entry 12
example with multiple WHEN for sharing files 12, 491 file organization
phrases 97 external data choosing 155
example with THRU phrase 96 obtaining storage for 42 comparison of ESDS, KSDS,
performance 96 sharing 491 RRDS 187
structured programming 652 storage location of 42 indexed 154, 188
testing multiple values, example 100, external decimal data line-sequential 213
101 national 47 overview 153
use to test multiple conditions 93 zoned 47 QSAM 159
evaluating data item contents external file 491 relative 154
class test external floating-point data relative-record 190
for numeric 54 display 48 sequential 153, 188
overview 98 national 48 VSAM 186
INSPECT statement 115 External symbols 410 file position indicator (CRP) 195, 198
intrinsic functions 119 FILE SECTION
exception condition BLOCK CONTAINS clause 13
CALL 250
XML GENERATE 567
F CODE-SET clause 14
DATA RECORDS clause 13
F-format record
XML PARSE 544 description 11
layout 162
exception handling EXTERNAL clause 12
requesting 161
with Java 624 FD entry 12
factoring expressions 652
with XML GENERATE 567 GLOBAL clause 12
factory data
with XML PARSE 542 LABEL RECORDS clause 13
defining 612
EXCEPTION XML event 544 LINAGE clause 13
definition of 579
EXCEPTION/ERROR declarative OMITTED 13
making it accessible 612
description 244 RECORD CONTAINS clause 13
private 612
file status key 246 record description 11
factory definition, coding 611
line-sequential error processing 218 RECORD IS VARYING 13
factory methods
QSAM error processing 174 RECORDING MODE clause 14
defining 612
VSAM error processing 201 VALUE OF 13
definition of 579
EXEC control statement, RD parameter FILE STATUS clause
hiding 613
of 644 description 158
invoking 614
EXIT compiler option example 249
using to wrap procedural
considerations for SQL and CICS line-sequential error processing 218
programs 620
statements 718 NOFASTSRT error processing 233
FACTORY paragraph
description 324 QSAM error processing 174
factory data 612
MSGEXIT suboption 709 using 245
factory methods 612
register usage 702 VSAM error processing 201
factory section, defining 611
864 Enterprise COBOL for z/OS, V5.2 Programming Guide
FILE STATUS clause (continued) files (continued) format of record (continued)
with VSAM status code 246 unavailable (continued) layout 167
file status code VSAM 203 requesting 166
02 198 usage explanation 9 format V 183
30 197 FIPS messages layout 163
37 170 categories 711 requesting 162
39 170, 178, 182 FLAGSTD compiler option 328 spanned
49 200 fixed-length records layout 166
90 168, 173, 201 QSAM overview 165
92 200, 456 layout 162 requesting 164
file status key requesting 161 undefined
05 195 VSAM layout 167
35 195 defining 192 requesting 166
39 195 RRDS 186 variable-length
checking for I/O errors 245 fixed-point arithmetic defining for VSAM 192
checking for successful OPEN 245, comparisons 63 layout of QSAM 163
246 evaluation 62 requesting for QSAM 162
error handling 379 example evaluations 64 formatted dump 239
set for error handling 158 exponentiation 678 freeing object instances 606
used with VSAM status code 246 fixed-point data function-pointer data item
VSAM, importance of in 201 binary 48 addressing JNI services 721
FILE-CONTROL paragraph conversions and precision 52 CALL statement 479
example of entries 6 conversions between fixed- and calling COBOL 479
relation to FD entries 8 floating-point 52 calling DLL program
files external decimal 47 example 504
associating program files to external intermediate results 677 calling Language Environment
files 5 packed-decimal 50 services 479
attributes 178 planning use of 653 definition 477
available FLAG compiler option SET function-pointer 477
QSAM 171 compiler output 385 with DLLs 503
VSAM 202 description 327
changing name 9 using 384
CICS, restrictions under 5
COBOL coding
flags and switches 99
FLAGSTD compiler option 328
G
garbage collection 606
DATA DIVISION entries 160, 192, multioption interaction 305
GB 18030 data
214 floating-point arithmetic
converting to or from national 146
ENVIRONMENT DIVISION comparisons 63
processing 146
entries 159, 188, 213 evaluation 62
generating XML output
input/output statements 170, 193, example evaluations 64
example 568
215 exponentiation 683
overview 561
overview 156 floating-point data
get and set methods 593
data sets, same meaning as 5 conversions and precision 52
GETMAIN, saving address of 701
defining to operating system 8 conversions between fixed- and
GLOBAL clause for files 12, 16
describing 11 floating-point 52
global names 476
external 491 external 48
Glossary 819
identifying to z/OS 174, 177, 203 intermediate results 682
GOBACK statement
line-sequential, allocating 215 internal
in main program 464
multithreaded processing format 50
in subprogram 464
example 512 performance tips 654
with multithreading 464
recommended organization 511 planning use of 653
group item
recommended usage patterns 511 format of record
cannot subordinate alphanumeric
serialization 510 fixed-length
group within national group 135
optional defining for VSAM 192
comparing to national data 149
QSAM 171 layout of QSAM 162
definition 24
VSAM 196 requesting for QSAM 161
for defining tables 67
overview 154 for QSAM ASCII tape 183
group move contrasted with
processing format D 183
elementary move 33, 135
line-sequential 213 layout 163
initializing
QSAM 159 requesting 162
using a VALUE clause 76
VSAM 185 format F 183
using INITIALIZE 30, 73
with multithreading 510 layout 162
MOVE statement with 33
sort performance requesting 161
passing as an argument 486
FASTSRT 231 format S
treated as a group item
variable-length files 226 layout 166
example with INITIALIZE 74
storage of file-definition records 511 overview 165
in INITIALIZE 31
unavailable requesting 164
variably located 82
QSAM 171 format U 183
Index 865
group move contrasted with elementary IGZETUN module INITIAL clause
move 33, 135 with multithreading 514 effect on main program 465
GROUP-USAGE NATIONAL clause IGZSRTCD data set 235 effect on nested programs 5
communicating with Java 628 imperative statement, list 19 setting programs to initial state 5
defining a national group 134 implicit scope terminator 20 INITIALIZE statement
defining tables 68 IMS examples 28
example of declaring a national COBOL-Java interoperability loading group values 30
group 24 accessing databases 450 loading national group values 31
initializing a national group 31 calling COBOL method from loading table values 73
grouping data to pass as an Java 448 REPLACING phrase 73
argument 486 calling Java method from using for debugging 380
COBOL 449 initializing
messages 450 a group item
H restriction on EXEC SQL 450
STOP RUN 450
using a VALUE clause 76
using INITIALIZE 30, 73
header on listing 5
synchronizing transactions 450 a national group item
HEAP runtime option
using the AIB 450 using a VALUE clause 76
influencing data location 42
coding programs under using INITIALIZE 31, 74
multioption interaction 40
overview 443 a structure using INITIALIZE 30
hexadecimal literals
restrictions 5, 443 a table
as currency sign 65
compiling and linking for 447 all occurrences of an element 76
national
coprocessor at the group level 76
description 26
overview 443 each item individually 75
using 131
performance considerations 663 using INITIALIZE 73
HGPR compiler option 330
SQLIMS compiler option 446 using PERFORM VARYING 103
performance considerations 660
SQLIMS statements 445 examples 28
hiding factory methods 613
return codes 445 instance data 604
hierarchy of compiler options
SQLIMS INCLUDE 444 variable-length group 81
in batch 277
using character data in 445 inline PERFORM
in SYSOPTF data sets 342
using EXEC SQL under IMS 450 example 102
under z/OS 272
IMS SQL overview 102
under z/OS UNIX 284
coprocessor 444 input
incrementing addresses 487 coding for CICS 420
index coding for line-sequential files 215
I assigning a value to 72 coding for QSAM files 170
I-level message 282, 384 computation of element displacement, coding for VSAM files 193
IDENTIFICATION DIVISION example 70 from files 153
class 584 creating with OCCURS INDEXED BY to compiler, under z/OS 267
CLASS-ID paragraph 584, 608 clause 72 input procedure
client 596 definition 70 coding 222
coding 3 incrementing or decrementing 72 example 228
DATE-COMPILED paragraph 3 initializing 72 FASTSRT option not effective 232
errors 3 key, detecting faulty 249 requires RELEASE or RELEASE
listing header example 5 range checking 383 FROM 223
method 588 referencing other tables with 72 restrictions 225
PROGRAM-ID paragraph 3 index data item INPUT-OUTPUT SECTION 5
required paragraphs 3 cannot use as subscript or index 73 input/output
subclass 608 creating with USAGE IS INDEX checking for errors 245
TITLE statement 5 clause 72 coding overview 156
IF statement indexed file organization controlling with FASTSRT option 327
coding 93 description 154 logic flow after error 241
nested 94 specifying 188 overview 153
use EVALUATE instead for multiple indexing processing errors
conditions 94 computation of element displacement, line-sequential files 218
with null branch 93 example 70 QSAM files 174, 241
IGZCA2D service routine 685 definition 70 VSAM files 201, 241
IGZCD2A service routine 688 example 77 input/output coding
igzcjava.x preferred to subscripting 654 AT END (end-of-file) phrase 244
binding with tables 72 checking for successful operation 245
example 298 INEXIT suboption of EXIT option checking VSAM status codes 246
preparing OO applications 297 processing of 702 detecting faulty index key 249
linking with syntax 325 error handling techniques 241
example 293 inheritance hierarchy, definition of 581 EXCEPTION/ERROR
preparing OO applications 292 INITIAL attribute declaratives 244
IGZEOPT module effect on subprograms 466, 467 INSERT statement 375
with multithreading 514 use of dynamic call and CANCEL INSPECT statement
instead 468 avoid with UTF-8 data 541
866 Enterprise COBOL for z/OS, V5.2 Programming Guide
INSPECT statement (continued) intrinsic functions (continued) Java
examples 115 example of (continued) and COBOL
using 115 MIN 114 binding 296
inspecting data (INSPECT) 115 NATIONAL-OF 140 communicating between 623
instance NUMVAL 117 compatibility 300
creating 604 NUMVAL-C 61, 117 compiling under z/OS UNIX 291
definition of 579 ORD 119 compiling using JCL or
deleting 606 ORD-MAX 89, 120 TSO/E 295
instance data PRESENT-VALUE 61 linking 292
defining 586, 609 RANGE 62, 89 running 293, 296
definition of 579 REM 62 structuring applications 620
initializing 604 REVERSE 117 array classes 628
making it accessible 593 SQRT 62 arrays
private 586 SUM 89 declaring 629
instance methods UPPER-CASE 117 example 631
defining 587, 609 WHEN-COMPILED 123 manipulating 630
definition of 579 example of Unicode functions 144 boolean array 629
invoking overridden 604 finding date of compilation 123 boolean type 628
overloading 592 finding largest or smallest item 120 byte array 629
overriding 591 finding length of data items 122 byte type 628
INTDATE compiler option intermediate results 680, 683 char array 629
description 331 introduction to 38 char type 628
effect on calendar starting date 60 nesting 38 class types 628
INTEGER intrinsic function, numeric functions double array 630
example 114 differences from Language double type 628
INTEGER-OF-DATE intrinsic Environment callable example
function 61 services 59 exception handling 625
INTEGER-PART intrinsic function 114 equivalent Language Environment J2EE client 635
integrated CICS translator callable services 58 processing an integer array 631
advantages 425 examples of 57 exception
compiler options for 424 integer, floating-point, mixed 57 catching 625
overview 425 nested 58 example 625
interactive program, example 799 special registers as arguments 58 handling 624
Interactive System Productivity Facility table elements as arguments 58 throwing 624
(ISPF) 799 uses for 57 float array 630
interlanguage communication processing table elements 89 float type 628
and PL/I tasking 513 UTF-8 142 global references
between COBOL and Java 623 INVALID KEY phrase JNI services for 627
IMS applications 449 description 249 managing 626
subprograms 463 example 249 object 626
under CICS 422 INVOKE statement passing 626
with multithreading 513 RETURNING phrase 603 int array 629
intermediate results 675 USING phrase 601 int type 628
internal floating-point data (COMP-1, using to create objects 604 interoperability 623
COMP-2) 50 using to invoke methods 600 interoperable data types, coding 628
interoperable data types with Java 628 with ON EXCEPTION 601, 614 jstring class 628
interrupts 641 with PROCEDURE DIVISION local references
intrinsic functions RETURNING 490 deleting 626
as reference modifiers 114 invoking freeing 627
converting alphanumeric data items COBOL programs under z/OS 495 JNI services for 627
with 116 COBOL programs under z/OS managing 626
converting national data items UNIX 453 object 626
with 116 factory or static methods 614 passing 626
evaluating data items 119 instance methods 600 per multithreading 626
example of Language Environment callable saving 626
ANNUITY 62 services 669 long array 629
CHAR 119 ISAM data set, analogous to VSAM KSDS long type 628
CURRENT-DATE 61 data set 185 methods
DISPLAY-OF 140 ISPF (Interactive System Productivity access control 627
INTEGER 114 Facility) 799 object array 629
INTEGER-OF-DATE 61 running with COBOL
LENGTH 61, 121, 122 under z/OS UNIX 293
LOG 62
LOWER-CASE 117
J using JCL or TSO/E 296
XPLINK linkage 299
J2EE client
MAX 61, 89, 120, 121 sharing data with 627
example 635
MEAN 62 short array 629
running 295
MEDIAN 62, 89 short type 628
Index 867
Java (continued) keys level-88 item
string array 629 alternate in KSDS file 189 conditional expressions 98
strings for binary search 87 setting switches off, example 101
declaring 629 for merging setting switches on, example 100
manipulating 632 defining 227 switches and flags 99
Java virtual machine overview 220 testing multiple values, example 100
exceptions 625 for sorting testing single values, example 99
initializing 294 defining 227 level-number 393
object references 626 overview 220 LIBEXIT suboption of EXIT option
java.lang.Object permissible data types processing of 703
referring to as Base 584 in MERGE statement 228 syntax 325
javac command in OCCURS clause 68 libjvm.x
compiling Java class definitions 291 in SORT statement 228 binding with
recompile for Java 5 or Java 6 300 prime in KSDS file 188 example 298
JAVAERR data set 297 relative-record 190 preparing OO applications 297
JAVAIN data set 297 to specify order of table elements 68 linking with
JAVAOUT data set 297 KSDS (key-sequenced data sets) example 293
JCL file access mode 191 preparing OO applications 292
ASCII tape files 183 organization 188 with EBCDIC services 634
cataloged procedures 256 LIBPATH environment variable
example of checkpoint/restart 647 description 455
FASTSRT requirement 231
for compiling 256
L example of setting 297
specifying location for COBOL
LABEL RECORDS clause
for compiling in the z/OS UNIX file classes 293
FILE SECTION entry 13
system 258 library
LANGUAGE compiler option
for line-sequential files 215 BASIS 270
description 331
for merge 226 COPY 270
Language Environment callable services
for OO applications 295 defining 270
condition handling 667
example 298 directory entry 265
corresponding math intrinsic
for QSAM files 176 specifying path for 373
functions 58
for sort 226 library-name
date and time computations 667
for VSAM data sets 206 alternative if not specified 288
differences from intrinsic
JNI cross-reference to data-set names 413
functions 59
accessing services 623 when not used 703
dynamic storage services 667
comparing object references 599 library-name environment variable 284
example of using 670
converting local references to limits of the compiler
feedback code 669
global 604 DATA DIVISION 11
for date and time 60
EBCDIC services 633 user data 11
for mathematics 58
environment structure 623 line number 392
invoking with CALL 669
addressability for 623 line-sequential files
mathematics 667
exception handling services 624 adding records to 217
message handling 668
Java array services 630 blocking 12
national language support 668
Java string services 632 closing 217
omitted feedback code 669
obtaining class object reference 624 closing to prevent reopening 216
overview 667
restrictions when using 624 control characters in 214
return code 670
Unicode services 632 DATA DIVISION entries 214
RETURN-CODE special register 670
UTF-8 services 634 ENVIRONMENT DIVISION
sample list of 668
JNI.cpy entries 213
types of 667
for compiling 291 input/output error processing 218
large block interface (LBI) 169
for JNINativeInterface 623 input/output statements for 215
largest or smallest item, finding 120
listing 721 national data not supported 217
last-used state
JNIEnvPtr special register opening 216
subprograms with EXIT PROGRAM
use for JNI callable services 623 organization 213
or GOBACK 465
JNINativeInterface processing 213
subprograms without INITIAL
environment structure 623 reading from 215
attribute 466, 467
JNI.cpy 623 reading records from 216
LBI (large block interface) 169
JOB control statement, RD parameter under z/OS
LENGTH intrinsic function
of 644 allocating 215
compared with LENGTH OF special
job resubmission 647 creating 215
register 122
job stream 463 job control language (JCL) 215
example 61, 122
jstring Java class 628 writing to 215
using 119
LINECOUNT compiler option 332
variable-length results 121
LINK macro 265
with national data 122
K length of data items, finding 122
LINKAGE SECTION
coding 485
Kanji comparison 98 LENGTH OF special register
for describing parameters 484
Kanji data, testing for 151 passing 482
with recursive calls 17
keyboard navigation xxii using 122
868 Enterprise COBOL for z/OS, V5.2 Programming Guide
LINKAGE SECTION (continued) little-endian, converting to MAXPCF compiler option 335
with the THREAD option 17 big-endian 130 MDECK compiler option
linked-list processing, example 488 loading a table dynamically 73 description 336
linking in the z/OS UNIX shell local names 476 MEAN intrinsic function
c89 command 285 local references, converting to global 604 example statistics calculation 62
passing information to cob2 287 LOCAL-STORAGE SECTION example table calculation 89
using the cob2 command client 598, 599 MEDIAN intrinsic function
DLLs 286 comparison with example statistics calculation 62
examples 286 WORKING-STORAGE example table calculation 89
overview 285 example 15 memory map
linking OO applications OO client 599 DSA 397
cob2 command 292 overview 14 merge
under z/OS UNIX determining location 42 alternate collating sequence 229
example 293 LOG intrinsic function 62 completion code 230
overview 292 logical record criteria 227
using JCL or TSO/E description 153 data sets needed under z/OS 226
example 298 fixed-length format DD statements for defining z/OS data
overview 296 defining for VSAM 192 sets 226
LIST compiler option requesting for QSAM 161 description 219
assembler code for source QSAM, definition 160 determining success 230
program 397 variable-length format diagnostic message 230
base locator table 409 defining for VSAM 192 files, describing 221
compiler output 399, 405 layout for QSAM 163 keys
conflict with OFFSET option 387 requesting for QSAM 162 defining 227
Constant area section 409 loops overview 220
description 333 coding 101 pass control statements to 235
DSA memory map 397, 411 conditional 103 process 220
External symbols section 410 do 103 restrictions 219
getting output 387 in a table 103 storage use 235
multioption interaction 305 performed an explicit number of terminating 231
reading output 397 times 103 work files
special register table 410 LOWER-CASE intrinsic function 117 describing 220
Static map section 408 lowercase, converting to 117 MERGE statement
symbols used in output 396 lst suffix with cob2 289 ASCENDING|DESCENDING KEY
Timestamp and version information phrase 228
example 405 COLLATING SEQUENCE phrase 7,
List of resources 853
listings
M 229
description 226
main program
assembler expansion of PROCEDURE GIVING phrase 226
accessing parameter list in z/OS
DIVISION 397 overview 219
example 495
data and procedure-name restrictions 219
overview 495
cross-reference 386 USING phrase 226
accessing parameter list in z/OS
embedded error messages 384 message handling, Language
UNIX
generating a short listing 388 Environment callable services 668
example 459
line numbers, user-supplied 389 messages
overview 458
sorted cross-reference of compiler
and subprograms 463
program-names 412 choosing severity to be
dynamic calls 467
sorted cross-reference of flagged 384
main storage, allocating to buffers 311
text-names 413 customizing 710
MAP compiler option
terms used in MAP output 395 determining what severity level to
data items and relative addresses 274
text-name cross-reference 386 produce 327
description 333
literals embedding in source listing 384
embedded MAP summary 387
alphanumeric generating a list of 280
example 392, 397
description 25 sending to terminal 271
nested program map 387
with DBCS content 151 severity levels 282, 711
example 397
DBCS compiler-directed 280
symbols used in output 396
description 26 from exit modules 717
terms used in output 395
maximum length 151 sending to SYSTERM 359
using 386, 387
using 150 METHOD-ID paragraph 588
mapping of DATA DIVISION items 387
definition 25 methods
mathematics
hexadecimal constructor 612
intrinsic functions 57, 62
using 131 factory 612
Language Environment callable
national hiding factory 613
services 59, 667
description 26 instance 587, 609
MAX intrinsic function
using 131 invoking 600, 614
example table calculation 89
numeric 26 invoking superclass 604
example with functions 61
using 25 Java access control 627
using 120
Index 869
methods (continued) multithreading (continued) national data (continued)
obtaining passed arguments 591 overview 507 encoding in XML documents 537
overloading 592 preinitializing 509 evaluating with intrinsic
overriding 591, 613 preparing COBOL programs for 507 functions 119
returning a value from 591 recursion 509 external decimal 47
signature 588 recursive requirement 513 external floating-point 48
migration considerations reentrancy 513 figurative constants 132
Java and COBOL 300 reentrancy requirement 513 finding the smallest or largest
MIN intrinsic function runtime restrictions 514 item 120
example 114 sort and merge restriction 219 in conditional expressions 147, 148
using 120 STOP RUN statement 464 in generated XML documents 562
mixed DBCS/EBCDIC literal synchronizing access to in keys
alphanumeric to DBCS resources 513 in MERGE statement 228
conversion 685 terminology 508 in OCCURS clause 68
DBCS to alphanumeric THREAD compiler option in SORT statement 228
conversion 688 restrictions with 362 initializing, example of 29
mnemonic-name when to choose 509 input with ACCEPT 35
SPECIAL-NAMES paragraph 5 UPSI switches 514 inspecting (INSPECT) 115
MOVE statement with PL/I tasks 513 LENGTH intrinsic function and 122
assigning arithmetic results 34 LENGTH OF special register 122
converting to national data 138 literals
CORRESPONDING 33
effect of ODO on lengths of sending
N using 131
MOVE statement with 32, 138
N delimiter for national or DBCS
and receiving items 79 NSYMBOL compiler option if no
literals 26
group move contrasted with USAGE clause 131
NAME compiler option
elementary move 33, 135 reference modification of 112
description 337
with elementary receiving items 32 reversing characters 117
using 3
with group receiving items 33 specifying 130
name declaration
with national items 32 splitting (UNSTRING) 108
searching for 476
MSGEXIT suboption of EXIT option VALUE clause with alphanumeric
NAMESPACE-DECLARATION XML
effect on compilation return code 712 literal, example 121
event 528
example user exit 713 national decimal data (USAGE
naming
message severity levels 711 NATIONAL)
files 8
processing of 709 defining 133
programs 3
syntax 325 example 43
NATIONAL (USAGE IS)
MSGFILE runtime option 344 format 47
external decimal 47
multiple currency signs initializing, example of 29
floating point 48
example 66 national floating-point data (USAGE
national comparison 98
using 65 NATIONAL)
national data
multiple inheritance, not permitted 582, defining 133
communicating with Java 628
607 definition 48
comparing
multiple thread environment, running national group item
overview 147
in 362 advantages over alphanumeric
to alphabetic, alphanumeric, or
multithreading groups 133
DBCS 149
AMODE setting 513 can contain only national data 24,
to alphanumeric groups 149
asynchronous signals 513 135
to numeric 148
choosing data section 507 communicating with Java 628
two operands 148
in an OO client 599 contrasted with USAGE NATIONAL
concatenating (STRING) 105
closing QSAM files 173 group 25
converting
closing VSAM files 201 defining 134
exceptions 140
COBOL programs 507 example 24
from alphanumeric or DBCS with
coding file I/O for defining tables 68
NATIONAL-OF 139
example 512 in generated XML documents 562
from alphanumeric, DBCS, or
recommended organization 511 initializing
integer with MOVE 138
recommended usage patterns 511 using a VALUE clause 76
overview 138
serialization 510 using INITIALIZE 31, 74
to alphanumeric with
control transfer 509 LENGTH intrinsic function and 122
DISPLAY-OF 139
ending programs 510 MOVE statement with 33
to numbers with NUMVAL,
EXIT PROGRAM statement 464 overview 133
NUMVAL-C 117
GOBACK statement 464 passing as an argument 486
to or from Chinese GB 18030 146
I/O error declaratives 244 treated as a group item
to or from Greek alphanumeric,
IGZEOPT 514 example with INITIALIZE 136
example 140
IGZETUN 514 in INITIALIZE 31
to or from UTF-8 141
interlanguage communication 513 in MOVE CORRESPONDING 33
to uppercase or lowercase 117
limitations 513 summary 136
with INSPECT 115
nested programs 513 treated as an elementary item
defining 131
older compilers 514 example with MOVE 33
displaying on output 36
870 Enterprise COBOL for z/OS, V5.2 Programming Guide
national group item (continued) NORENT compiler option numeric data (continued)
treated as an elementary item multioption interaction 305 packed-decimal (continued)
(continued) NOSIMVRD runtime option 190 USAGE COMPUTATIONAL-3
in most cases 24, 133 NOSQLCCSID compiler option (COMP-3) 50
using recommended for compatibility with USAGE PACKED-DECIMAL 50
as an elementary item 135 DB2 precompiler 438 PICTURE clause 43, 45
overview 134 Notices 815 storage formats 46
VALUE clause with alphanumeric NSYMBOL compiler option USAGE DISPLAY 43
literal, example 76 description 338 USAGE NATIONAL 43
national language support (NLS) effect on N literals 26 zoned decimal (USAGE DISPLAY)
DBCS 150 for DBCS literals 131 format 48
LANGUAGE compiler option 331 for national data items 131 sign representation 53
processing data 125 for national literals 131 numeric intrinsic functions
national literals multioption interaction 305 differences from Language
description 26 null branch 93 Environment callable services 59
using 131 null-terminated strings equivalent Language Environment
national-edited data example 111 callable services 58
defining 131 handling 486 example of
editing symbols 131 manipulating 110 ANNUITY 62
initializing NUMBER compiler option CURRENT-DATE 61
example 29 description 339 INTEGER 114
using INITIALIZE 74 for debugging 389 INTEGER-OF-DATE 61
MOVE statement with 32 NUMCLS installation option, effect on LENGTH 61, 121
PICTURE clause 131 numeric class test 55 LOG 62
NATIONAL-OF intrinsic function numeric class test MAX 61, 89, 120, 121
example with Chinese data 147 checking for valid data 54 MEAN 62
example with Greek data 140 effect of NUMPROC, NUMCLS 55 MEDIAN 62, 89
example with UTF-8 data 141 numeric comparison 98 MIN 114
using 139 numeric data NUMVAL 117
with XML documents 538 binary NUMVAL-C 61, 117
nested COPY statement 665, 704 USAGE BINARY 48 ORD 119
nested delimited scope statements 21 USAGE COMPUTATIONAL ORD-MAX 89
nested IF statement (COMP) 48 PRESENT-VALUE 61
coding 94 USAGE COMPUTATIONAL-4 RANGE 62, 89
CONTINUE statement 93 (COMP-4) 48 REM 62
EVALUATE statement preferred 94 USAGE COMPUTATIONAL-5 SQRT 62
with null branches 93 (COMP-5) 49 SUM 89
nested intrinsic functions 58 can compare algebraic values integer, floating-point, mixed 57
nested program integration 658 regardless of USAGE 149 nested 58
nested program map comparing to national 148 special registers as arguments 58
description 387 converting table elements as arguments 58
example 397 between fixed- and uses for 57
nested programs floating-point 52 numeric literals, description 26
calling 474 precision 52 numeric-edited data
description 474 to national with MOVE 138 BLANK WHEN ZERO clause
effect of INITIAL clause 5 defining 43 coding with numeric data 131
guidelines 474 display floating-point (USAGE example 45
map 387, 397 DISPLAY) 48 defining 131
scope of names 476 editing symbols 45 editing symbols 45
transfer of control 474 external decimal initializing
nesting level USAGE DISPLAY 47 examples 30
program 392, 397 USAGE NATIONAL 47 using INITIALIZE 74
statement 392 external floating-point PICTURE clause 45
NOCBLCARD translator option 426 USAGE DISPLAY 48 USAGE DISPLAY
NOCOMPILE compiler option USAGE NATIONAL 48 displaying 45
use to find syntax errors 382 internal floating-point initializing, example of 30
NODLL compiler option USAGE COMPUTATIONAL-1 USAGE NATIONAL
with dynamic calls 467 (COMP-1) 50 displaying 45
with static calls 466 USAGE COMPUTATIONAL-2 initializing, example of 30
NODYNAM compiler option (COMP-2) 50 NUMPROC compiler option
under CICS 422 national decimal (USAGE affected by NUMCLS 55
under DB2 with CICS or CAF 441 NATIONAL) 48 description 339
with static and dynamic calls 471 national floating-point (USAGE effect on sign processing 54
with static calls 466 NATIONAL) 48 performance considerations 660
with stored procedures 441 packed-decimal NUMVAL intrinsic function
NOFASTSRT compiler option 233, 236 sign representation 53 description 117
Index 871
NUMVAL-C intrinsic function object-oriented COBOL (continued) optimization (continued)
description 117 running (continued) factor expressions 652
example 61 XPLINK linkage 299 index computations 656
NX delimiter for national literals 26 writing OO programs 579 indexing 654
OCCURS clause nested program integration 658
ASCENDING|DESCENDING KEY OCCURS DEPENDING ON 655
O phrase
example 88
out-of-line PERFORM 652
packed-decimal data items 653
o suffix with cob2 289
needed for binary search 87 performance implications 655
object
specify order of table elements 68 procedure integration 658
creating 604
cannot use in a level-01 item 68 structured programming 652
definition of 579
defining tables 67 subscript computations 656
deleting 606
for defining table elements 68 subscripting 654
object code
INDEXED BY phrase for creating table elements 654
compilation and listing 274
indexes 72 top-down programming 652
creating 271
nested for creating multidimensional unreachable code 657
generating 316
tables 68 unused data items 343, 393
producing in 80-column record 319
OCCURS DEPENDING ON (ODO) OPTIMIZE compiler option
OBJECT compiler option
clause description 343
description 340
complex 81 effect on parameter passing 484
multioption interaction 305
for creating variable-length tables 78 performance considerations 657, 660
object instances, definition of 579
initializing ODO elements 81 optimizer
OBJECT paragraph
ODO object 78 overview 657
instance data 586, 609
ODO subject 78 optional files
instance methods 587
optimization 655 QSAM 171
object references
simple 78 VSAM 196
comparing 599
variable-length records ORD intrinsic function, example 119
converting from local to global 604
QSAM 162 ORD-MAX intrinsic function
example of passing 602
VSAM 192 example table calculation 89
setting 599
OCCURS INDEXED BY clause, creating using 120
typed 598
indexes with 72 ORD-MIN intrinsic function 120
universal 598
ODO object 78 order of evaluation
OBJECT-COMPUTER paragraph 5
ODO subject 78 arithmetic operators 57, 677
object-oriented COBOL
OFFSET compiler option compiler options 305
binding
description 341 out-of-line PERFORM 102
example 298
multioption interaction 305 OUTDD compiler option
overview 296
output 415 DD not allocated 36
calls to and from OO programs 477
OMITTED clause, FILE SECTION 13 description 344
communicating with Java 628
OMITTED parameters 669 interaction with DISPLAY 36
compatibility 300
OMITTED phrase for omitting output
compiling
arguments 485 coding for CICS 420
under z/OS UNIX 291
ON EXCEPTION phrase coding for line-sequential files 215
using JCL or TSO/E 295
INVOKE statement 601, 614 coding for QSAM files 170
DLLs in 506
OPEN statement coding for VSAM files 193
IMS
file availability 170, 195, 216 data set 270
accessing databases 450
file status key 245 from compiler, under z/OS 268
calling COBOL method from
line-sequential files 215 to files 153
Java 448
multithreading serialization 510 output files with cob2 289
calling Java method from
QSAM files 170 output procedure
COBOL 449
VSAM files 193 coding 224
linking
opening files example 224, 228
example 293
line-sequential 216 FASTSRT option not effective 232
overview 292
multithreading serialization 510 requires RETURN or RETURN
preparing applications
QSAM 170 INTO 224
under z/OS UNIX 292
VSAM restrictions 225
using JCL or TSO/E 296
empty 196 overflow condition
programs must be reentrant 480
overview 195 CALL 250
restrictions
OPTFILE compiler option 342 joining and splitting strings 240
cannot run under CICS 419
optimization UNSTRING 107
CICS 579
avoid ALTER statement 652 overloading instance methods 592
EXEC CICS statements 579
BINARY data items 653 overriding
EXEC SQL statements 579
consistent data 653 factory methods 613
sort and merge 219
constant data items 652 instance methods 591
SQL compiler option 579
contained program integration 658
SQL statements 432
effect of compiler options on 658
running
effect on parameter passing 484
under z/OS UNIX 293
effect on performance 652
using JCL or TSO/E 296
872 Enterprise COBOL for z/OS, V5.2 Programming Guide
P PERFORM statement
coding loops 101
performance (continued)
parsing XML documents with
packed-decimal data item for a table validation 531
description 50 example using indexing 77 programming style 652
sign representation 53 example using subscripting 77 sorting with FASTSRT 231
synonym 47 for changing an index 72 striped extended-format QSAM data
using efficiently 50, 653 inline 102 sets 180
page out-of-line 102 table handling 656
control 172 performed an explicit number of table searching
depth 13 times 103 binary compared with serial 85
paragraph TEST AFTER 103 improving serial search 86
definition 18 TEST BEFORE 103 tape, QSAM 169
grouping 104 THRU 104 tuning 651
parameters TIMES 103 variable subscript data format 71
accessing from main program in z/OS UNTIL 103 VSAM files 209, 663
example 495 VARYING 103 worksheet 662
overview 495 VARYING WITH TEST AFTER 103 period as scope terminator 20
accessing from main program in z/OS WITH TEST AFTER . . . UNTIL 103 PGMNAME compiler option
UNIX WITH TEST BEFORE . . . UNTIL 103 COMPAT suboption 345
example 459 performance description 345
overview 458 AIXBLD runtime option 663 LONGMIXED suboption 346
ADEXIT 708 and debugging 360 LONGUPPER suboption 346
describing in called program 484 APPLY WRITE-ONLY clause 10 phrase, definition of 18
INEXIT 702 arithmetic evaluations 653 physical block 153
LIBEXIT 705 arithmetic expressions 654 physical record 14, 153
MSGEXIT 709 blocking QSAM files 168, 310 PICTURE clause
PRTEXIT 707 calls 471 cannot use for internal floating
parse data item, definition 520 CBLPSHPOP considerations 428 point 44
parsing XML documents CBLPSHPOP runtime option 428 determining symbol used 317
description 520 CICS incompatible data 54
one segment at a time overview 651 N for national data 131
example 556 CICS coding 662 national-edited data 131
overview 533 coding for 651 numeric data 43
overview 518 coding tables 654 numeric-edited data 131
UTF-8 541 compiler option Z for zero suppression 45
white space 538 AFP 659 PL/I tasking
with validation ARCH 659 POSIX runtime option 513
example 558 ARITH 659 with COBOL 513
overview 530 AWO 659 pointer data item
performance considerations 531 BLOCK0 659 description 39
restrictions 531 DYNAM 660 incrementing addresses with 487
XML declaration 538 FASTSRT 660 NULL value 487
passing data between programs HGPR 660 passing addresses 487
addresses 487 MAXPCF 660 processing chained lists 487
arguments in calling program 483 NUMPROC 54, 660 used to process chained list 488
BY CONTENT 481 OPTIMIZE 657, 660 porting applications
BY REFERENCE 481 RENT 660 effect of separate sign 44
BY VALUE RMODE 661 POSIX
overview 481 SQLCCSID 438 calling APIs 456
restrictions 483 SSRANGE 661 threads 513
EXTERNAL data 491 TEST 661 POSIX runtime option
JNI services 624 THREAD 363, 661 effect on DLL search order 501
OMITTED arguments 485 TRUNC 363, 661 use in OO applications 297
options considerations 41 consistent data types 653 precedence
parameters in called program 484 data usage 653 arithmetic operators 57, 677
RETURN-CODE special register 490 effect of compiler options on 658 CICS options 424
with Java 627 effects of buffer size 311 compiler options
password exponentiations 654 in batch 277
alternate index 202 FASTSRT 231 in SYSOPTF data sets 270, 342
example 202 IMS environment 447, 663 under z/OS 272
VSAM files 202 OCCURS DEPENDING ON 655 under z/OS UNIX 284
PASSWORD clause 202 optimizer copybook search order 284
PATH environment variable overview 657 preferred sign 54
description 455 order of WHEN phrases in preinitializing the COBOL environment
example of setting 297 EVALUATE 96 with multithreading 509
path name out-of-line PERFORM compared with PRESENT-VALUE intrinsic function 61
for copybook search 288, 373 inline 102
Index 873
preserving original sequence in a program (continued) QSAM files (continued)
sort 230 decisions (continued) input/output error processing 174,
priority numbers, segmentation 658 PERFORM statement 103 241
procedure and data-name cross-reference, switches and flags 99 input/output statements for 170
description 386 developing for z/OS UNIX 453 obtaining buffers for 181
PROCEDURE DIVISION diagnostics 391 opening 170
additional information 399 initialization code 405 processing
client 596 limitations 651 existing files 179
description 17 main 463 in reverse order 171
in subprograms 486 nesting level 392 new files 180
instance method 590 reentrant 480 overview 159
RETURNING restarting 644 z/OS UNIX files 181
to return a value 17 signature information bytes 399 replacing records 172
using 490 statistics 391 retrieving 177
signature information bytes 399 structure 3 striped extended-format 180
statements subprogram 463 tape performance 169
compiler-directing 20 PROGRAM COLLATING SEQUENCE under z/OS
conditional 19 clause creating files 174, 177
delimited scope 19 does not affect national or DBCS DD statement for 174, 177
imperative 19 operands 7 defining 174, 177
terminology 17 establishing collating sequence 6 environment variable for 174
USING overridden by COLLATING file availability 171
BY VALUE 486 SEQUENCE phrase 6 job control language (JCL) 176
to receive parameters 17, 484 overrides default collating updating files 172
verbs present in 399 sequence 229 using same input/output file under
procedure integration 658 Program information FASTSRT 232
procedure-pointer data item listing example 405 writing to a printer 172
calling C/C++ 479 program processing table 422 QUALIFY compiler option 347
calling JNI services 479 Program prolog area QUOTE compiler option 348
definition 477 listing example 407
entry address for entry point 477 program termination
passing parameters to callable
services 477
actions taken in main and
subprogram 464
R
railroad track diagrams, how to read xvi
SET procedure-pointer 477 statements 464
random numbers, generating 59
with DLLs 503 PROGRAM-ID paragraph
RANGE intrinsic function
process coding 3
example statistics calculation 62
definition 508 COMMON attribute 4
example table calculation 89
PROCESS (CBL) statement INITIAL clause 5
RD parameter of JOB or EXEC
batch compiling 277 program-names
statement 644
conflicting options in 304 avoid using certain prefixes 3
READ INTO for format-V VSAM
overview 375 cross-reference 412
files 193
precedence handling of case 345
READ NEXT statement 193
in batch 277 specifying 3
READ statement
under z/OS 272 protecting VSAM files 202
AT END phrase 244
under z/OS UNIX 284 PRTEXIT suboption of EXIT option
line-sequential files 215
specifying compiler options 273 processing of 706
multithreading serialization 510
processing syntax 325
QSAM 170
chained lists
VSAM 193
example 488
reading records
overview 487
tables
Q block size 168
QSAM files from line-sequential files 216
example using indexing 77
adding records to 172 reading records from VSAM files
example using subscripting 77
ASCII tape file 182 dynamically 198
producing XML output 561
ASSIGN clause 160 randomly 198
product support xviii, 853
attributes 178 sequentially 198
program
BLOCK CONTAINS clause 168, 310 reason code from XML parsing 542, 691
attribute codes 397
block size 168, 310 record
compiling and linking using cob2
blocking enhances performance 168, description 11
DLLs 286
310 format
examples 286
blocking records 168, 181 fixed-length QSAM 161, 162
overview 285
closing 173 fixed-length VSAM 192
compiling under z/OS 255
closing to prevent reopening 171 format D 162, 163, 183
compiling under z/OS UNIX 283
DATA DIVISION entries 160 format F 161, 162, 183
decisions
ENVIRONMENT DIVISION format S 164, 165, 166
EVALUATE statement 93
entries 159 format U 166, 167, 183
IF statement 93
FASTSRT requirements 232 format V 162, 163, 183
loops 103
QSAM ASCII tape 183
874 Enterprise COBOL for z/OS, V5.2 Programming Guide
record (continued) replacing (continued) RETURN statement
format (continued) text, DB2 considerations 439 required in output procedure 224
spanned 164, 165, 166 REPLACING phrase (INSPECT), with INTO phrase 224
undefined 166, 167 example 115 RETURN-CODE special register
variable-length QSAM 162, 163 REPOSITORY paragraph calls to Language Environment
variable-length VSAM 192 class 584 services 670
order, effect of organization on 153 client 597 CICS ECI calls 423
RECORD CONTAINS clause coding 5 considerations for DB2 435
FILE SECTION entry 13 subclass 609 not set by INVOKE 601
RECORD KEY clause representation passing data between programs 490
identifying prime key in KSDS data 54 sharing return codes between
files 188 sign 53 programs 490
RECORDING MODE clause RERUN clause when control returns to operating
fixed-length records, QSAM 161 checkpoint/restart 236 system 490
QSAM files 14 reserved-word table, CICS alternate RETURNING phrase
specify record format 160 overview 427 CALL statement 491
variable-length records, QSAM 162, specifying with WORD 368 INVOKE statement 603
163 residency mode, definition 40 PROCEDURE DIVISION header 490,
recursive calls restart 591
and the LINKAGE SECTION 17 automatic 645 REVERSE intrinsic function 117
coding 477 automatic or deferred 641 reverse order of tape files 171
identifying 4 deferred 645 reversing characters 117
REDEFINES clause, making a record into overview 641 REWRITE statement
a table using 75 restarting a program 644 multithreading serialization 510
reentrant programs 480 restrictions QSAM 170
reference modification CICS VSAM 193
example 113 16 MB line 420 RLS parameter 207
expression checking with calls 421 RMODE
SSRANGE 357 coding 419 description 40
generated XML documents 562 files 5 of EXIT modules 702
intrinsic functions 111 OUTDD compiler option 344 RMODE compiler option
national data 112 parsing with validation using description 349
out-of-range values 113 FILE 531 influencing addressability 40
tables 71, 112 separate translator 425 multioption interaction 40
UTF-8 documents 141 sorting 237 performance considerations 661
reference modifier DB2 coprocessor 436 when passing data 41
arithmetic expression as 114 IMS ROUNDED phrase 676
intrinsic function as, example 114 16 MB line 420 rows in tables 69
variables as 112 coding 5, 443 RRDS (relative-record data sets)
registers used by EXIT compiler IMS SQL coprocessor 446 file access mode 191
option 702 input/output procedures 225 fixed-length records 186, 190
relation condition 98 OO programs 579 organization 190
relative file organization 154 SQL compiler option 436 performance considerations 210
RELEASE FROM statement SQL statements 432 simulating variable-length
compared to RELEASE 223 SQLIMS compiler option 446 records 190
example 222 subscripting 71 variable-length records 186, 190
RELEASE statement resubmitting a job 647 RULES compiler option
compared to RELEASE FROM 223 return code description 350
with SORT 222, 223 compiler run time
REM intrinsic function 62 depends on highest severity 282 accessing arguments in z/OS
RENT compiler option effect of message example 495
description 348 customization 712 overview 495
for DLLs 498 overview 282 accessing arguments in z/OS UNIX
for IMS 447 feedback code from Language example 459
for Java interoperability 291, 295 Environment services 670 overview 458
for OO COBOL 291, 295 from CICS ECI 423 changing file-name 9
influencing addressability 41 from DB2 SQL statements 435 multithreading restrictions 514
multioption interaction 40, 305 from XML parsing 542, 691 performance 651
performance considerations 660 RETURN-CODE special register 490, run unit
when passing data 41 670 description 463
REPLACE statement VSAM files role in multithreading 508
DB2 considerations 439 description 246 running OO applications
description 375 example 247 under z/OS UNIX
replacing RLS mode 208 overview 293
data items (INSPECT) 115 when control returns to operating XPLINK linkage 299
records in QSAM file 172 system 490 using JCL or TSO/E 296
records in VSAM file 200 XPLINK linkage 299
Index 875
runtime options section (continued) sharing (continued)
| 85 COBOL Standard definition 18 data (continued)
conformance 304 grouping 104 passing arguments to a
AIXBLD 663 segmentation 658 method 601
ALL31 469 SELECT clause PROCEDURE DIVISION
CBLOPTS 495 ASSIGN clause 8 header 486
CBLPSHPOP 428 naming files 8 RETURN-CODE special
CHECK(OFF) vary input-output file 9 register 490
performance considerations 661 SELECT OPTIONAL returning a value from a
DEBUG 380 QSAM 171 method 603
ENVAR 297 VSAM 196 scope of names 476
MSGFILE 344 SELF 599 with Java 627
NOSIMVRD 190 sentence, definition of 18 files
POSIX separate CICS translator scope of names 476
DLL search order 501 compiler options for 423, 426 using EXTERNAL clause 12, 491
use in OO applications 297 restrictions 425 using GLOBAL clause 12
specifying under z/OS 495 using 426 short listing, example 389
specifying under z/OS UNIX 453 separate sign sign condition
TRAP for line-sequential files 217 testing sign of numeric operand 98
closing files in QSAM 173 portability 44 SIGN IS SEPARATE clause
closing files in VSAM 200 printing 44 for line-sequential files 217
closing line-sequential files 217 required for signed national portability 44
ON SIZE ERROR 240 decimal 44 printing 44
XPLINK SEQUENCE compiler option 352 required for signed national decimal
not recommended as a sequential file organization 153 data 44
default 299 sequential search sign representation 53
setting 299 description 86 signature
example 86 definition of 588
sequential storage device 154 must be unique 588
S serial search
description 86
signature information bytes
compiler options in effect 399
S-format record
example 86 DATA DIVISION 399
layout 166
serialization of files with ENVIRONMENT DIVISION 399
overview 165
multithreading 510 PROCEDURE DIVISION 399
requesting 164
SERVICE compiler option 353 size of printed page, control 172
S-level error message 282, 384
SERVICE LABEL statement 375 skip a block of records 168
sample programs 795
SET condition-name TO TRUE statement softcopy information xviii
scope of names
example 102, 104 sort
global 476
switches and flags 100 alternate collating sequence 229
local 476
SET statement checkpoint/restart 236
scope terminator
for changing an index 72 completion code 230
aids in debugging 378
for changing index data items 72 controlling behavior of 234
explicit 19, 20
for function-pointer data items 477 criteria 227
implicit 20
for object references 599 data sets needed under z/OS 226
SD (sort description) entry, example 222
for procedure-pointer data items 477 DD statements for defining z/OS data
SEARCH ALL statement
for setting a condition, example 100 sets 226
binary search 87
handling of program-name in 345 description 219
example 88
using for debugging 380 determining success 230
for changing an index 72
setting diagnostic message 230
table must be ordered 87
index data items 72 FASTSRT compiler option
search order
indexes 72 improving performance 231
DLLs in the z/OS UNIX file
switches and flags 100 requirements 231
system 501
sharing using same QSAM file for input
SEARCH statement
data and output 232
example 86
between separately compiled files, describing 221
for changing an index 72
programs 491 input procedures
nesting to search more than one level
coding the LINKAGE coding 222
of a table 86
SECTION 485 example 228
serial search 86
from another program 16 keys
searching
in recursive or multithreaded defining 227
for name declarations 476
programs 17 overview 220
tables
in separately compiled NOFASTSRT compiler option 233
binary search 87
programs 16 output procedures
overview 85
overview 481 coding 224
performance 85
parameter-passing example 224, 228
serial search 86
mechanisms 481 pass control statements to 235
section
declarative 21
876 Enterprise COBOL for z/OS, V5.2 Programming Guide
sort (continued) special register (continued) SSRANGE compiler option
performance LENGTH OF 122, 482 description 357
FASTSRT 231 RETURN-CODE 490 performance considerations 661
variable-length files 226 SORT-RETURN reference modification 113
preserving original sequence 230 determining sort or merge using 383
process 220 success 230 STACK runtime option
restrictions 219 terminating sort or merge 231 influencing data location 42
restrictions on input/output using in XML parsing 522, 524 multioption interaction 40
procedures 225 WHEN-COMPILED 123 STANDARD clause, FD entry 13
special registers 234 XML-CODE 522, 525 START statement
storage use 235 XML-EVENT 522, 524 multithreading serialization 510
terminating 231 XML-INFORMATION 522 VSAM 193
under CICS 237 XML-NAMESPACE 522, 528 statement
variable-length records 226 XML-NAMESPACE-PREFIX 523, 528 compiler-directing 20
work files XML-NNAMESPACE 523, 528 conditional 19
describing 220 XML-NNAMESPACE-PREFIX 523, definition 18
workspace 236 528 delimited scope 19
SORT statement XML-NTEXT 522, 527 explicit scope terminator 20
ASCENDING|DESCENDING KEY XML-TEXT 522, 527 imperative 19
phrase 228 special register table 410 implicit scope terminator 20
COLLATING SEQUENCE phrase 7, SPECIAL-NAMES paragraph nesting level 392
229 coding 5 static calls
description 226 QSAM files 182 example 472
GIVING phrase 226 splitting data items (UNSTRING) 107 making 466
overview 219 SQL compiler option performance 471
restrictions 219 description 354 with dynamic calls 471
restrictions for CICS applications 237 restrictions static data areas, allocating storage 42
under CICS 237 compiling in batch 436 static data, definition of 579
change reserved-word table 428 OO programs 579 Static map 408
USING phrase 226 using 435 static methods
SORT-CONTROL special register 234 SQL statements definition of 579
SORT-CORE-SIZE special register 234 CCSID determination 437 invoking 614
SORT-FILE-SIZE special register 234 coding statistics intrinsic functions 62
SORT-MESSAGE special register 234 overview 432 status code, VSAM files
SORT-MODE-SIZE special register 234 restriction 432 description 246
SORT-RETURN special register 234 EXIT compiler option and 718 example 247
determining sort or merge overview 431 stderr
success 230 restrictions 432 controlling line spacing 37
terminating sort or merge 231 return codes 435 directing with DISPLAY 36
SORTCKPT DD statement 236 SQL DECLARE 433 setting DISPLAY to 455
sorting SQL INCLUDE 433 stdin
tables use for DB2 services 431 reading with ACCEPT 35
overview 88 using binary data in 435 stdout
SOURCE and NUMBER output, using character data in 433 controlling line spacing 37
example 391 using national decimal data 434 directing with DISPLAY 36
source code SQLCA setting DISPLAY to 455
compiler data set 269 declare for programs that use SQL STEPLIB environment variable
line number 392, 393, 397 statements 432 description 455
listing, description 387 declare for programs that use SQLIMS example of specifying compiler 285
program listing 274 statements 444 STGOPT compiler option 358
SOURCE compiler option return codes from DB2 435 STOP RUN statement
description 353 SQLCCSID compiler option in main program 464
getting output 387 description 355 in subprogram 464
SOURCE-COMPUTER paragraph 5 effect on CCSID of string data 437 with multithreading 464
SPACE compiler option 354 performance considerations 438 storage
spanned files 165 recommended with DB2 character data 137
spanned record format coprocessor 438 device
description 164 SQLIMS compiler option 356 direct-access 154
layout 166 restrictions sequential 154
requesting 164 compiling in batch 446 for arguments 483
special feature specification 5 using 446 management with Language
special register SQLIMS statements Environment callable services 667
ADDRESS OF coding mapping 387
use in CALL statement 482 overview 444 use during sort 235
arguments in intrinsic functions 58 EXIT compiler option and 718 stride, table 656
JNIEnvPtr SQLIMS INCLUDE 444 STRING statement
use for JNI callable services 623 SQRT intrinsic function 62 example 106
Index 877
STRING statement (continued) SYSABEND file table (continued)
overflow condition 240 description 268 description 39
using 105 SYSADATA dynamically loading 73
with DBCS data 685 file, creating 271 efficient coding 654, 656
strings output 305 elements 67
handling 105 records, exit module 707 identical element specifications 654
Java SYSADATA file index, definition 70
declaring 629 description 268 initializing
manipulating 632 example 729 all occurrences of an element 76
null-terminated 486 file contents 727 at the group level 76
striped extended-format QSAM file 180 record descriptions 730 each item individually 75
structure, initializing using record types 728 using INITIALIZE 73
INITIALIZE 30 SYSIN data set using PERFORM VARYING 103
structured programming 652 defining 269 loading values in 73
structuring OO applications 620 description 267 looping through 103
subclass SYSJAVA file multidimensional 68
coding defining 272 one-dimensional 67
example 610 description 268 processing with intrinsic
overview 607 SYSLIB data set functions 89
instance data 609 defining 270 redefining a record as 75
subprogram description 267 reference modification 71
and main program 463 when not used 703 referencing substrings of
definition 481 SYSLIB environment variable elements 112
description 463 description 284 referencing with indexes, example 70
linkage 463 specifying location of JNI.cpy 291 referencing with subscripts,
common data items 484 SYSLIN data set 271 example 70
PROCEDURE DIVISION in 486 description 268 referring to elements 70
termination SYSMDECK file rows 69
effects 464 defining 272 searching
subscript description 268 binary 87
definition 70 SYSMDUMP file overview 85
literal, example 70 description 268 performance 85
range checking 383 SYSOPTF data set sequential 86
variable, example 70 defining 269 serial 86
subscripting description 267 sorting
definition 70 SYSPRINT data set overview 88
example 77 defining 270 stride computation 656
literal, example 70 description 268 subscript, definition 70
reference modification 71 when not used 706 three-dimensional 69
relative 71 SYSPUNCH data set two-dimensional 69
restrictions 71 description 268, 271 variable-length
use data-name or literal 71 requirements for DECK compiler creating 78
variable, example 70 option 319 example of loading 80
substitution character 132 system date initializing 81
substrings under CICS 421 preventing overlay in 84
of table elements 112 system dump 239 TALLYING phrase (INSPECT),
reference modification of 111 system-determined block size example 115
SUM intrinsic function, example table compiler data sets 268 tape files
calculation 89 QSAM files 168, 310 performance 169
SUPER 604 system-name 5 reverse order 171
support xviii, 853 SYSTERM data set TERMINAL compiler option 359
switch-status condition 98 defining 271 terminal, sending messages to the 359
switches and flags description 268 terminating XML parsing 546
defining 99 sending messages to 359 termination 464
description 99 SYSUDUMP file terminology
resetting 100 description 268 VSAM 185
setting switches off, example 101 SYSUT data set 267 terms used in MAP output 395
setting switches on, example 100 test
testing multiple values, example 100 conditions 103
testing single values, example 99
SYMBOLIC CHARACTERS clause 8
T data 98
numeric operand 98
table
symbolic constant 652 UPSI switch 98
assigning values to 75
syntax diagrams, how to read xvi TEST AFTER 103
columns 67
syntax errors TEST BEFORE 103
compare to array 39
finding with NOCOMPILE compiler TEST compiler option
defining with OCCURS clause 67
option 382 description 359
definition 67
multioption interaction 305
depth 69
878 Enterprise COBOL for z/OS, V5.2 Programming Guide
TEST compiler option (continued)
performance considerations 661
UNBOUNDED groups
processing 90
V
use for debugging 387 undefined record format V-format record
text-name cross-reference, layout 167 layout 163
description 386 QSAM 183 requesting 162
text-name environment variable 284 requesting 166 validating XML documents
THREAD compiler option unfilled tracks 169 example 558
and the LINKAGE SECTION 17 Unicode overview 530
cannot use with nested description 129 performance considerations 531
programs 474 encoding and storage 137 restrictions 531
description 362 JNI services 632 VALUE clause
for Java interoperability 291, 295 processing data 125 alphanumeric literal with national
for OO COBOL 291, 295 using with DB2 433 data, example 121
multioption interaction 305 universal object references 598 alphanumeric literal with national
performance considerations 661 UNIX group, example 76
threading calling APIs 456 assigning table values
and preinitialization 509 unreachable code 657 at the group level 76
control transfer 509 UNSTRING statement to each item individually 75
ending programs 510 example 108 to each occurrence of an
z/OS UNIX considerations 453 overflow condition 240 element 76
TITLE statement 375 using 107 assigning to a variable-length
controlling header on listing 5 with DBCS data 685 group 81
top-down programming updating VSAM records 199 cannot use for external floating
constructs to avoid 652 UPPER-CASE intrinsic function 117 point 48
TRACK OVERFLOW option 169 uppercase, converting to 117 initializing internal floating-point
Trademarks 817 UPSI switches with multithreading 514 literals 44
transferring control USAGE clause large literals with COMP-5 49
between COBOL and non-COBOL at the group level 25 large, with TRUNC(BIN) 364
programs 463 incompatible data 54 VALUE IS NULL 487
between COBOL programs 465, 473 INDEX phrase, creating index data VALUE OF clause 13
called program 463 items with 72 variable
calling program 463 NATIONAL phrase at the group as reference modifier 112
main and subprograms 463 level 134 definition 23
nested programs 474 OBJECT REFERENCE 598 variable-length records
transforming COBOL data to XML USE FOR DEBUGGING declaratives OCCURS DEPENDING ON (ODO)
example 568 overview 380 clause 655
overview 561 USE statement 376 QSAM
TRAP runtime option user-defined condition 98 layout 163
closing line-sequential files 217 user-exit work area 701 requesting 162
closing QSAM files 173 USING phrase sorting 226
closing VSAM files 200 INVOKE statement 601 VSAM
ON SIZE ERROR 240 PROCEDURE DIVISION header 486, defining 192
TRUNC compiler option 591 RRDS 186
description 363 UTF-16 variable-length table
performance considerations 661 definition 129 assigning values to 81
suboptions for separate CICS encoding for national data 129 creating 78
translator 427 UTF-8 example 79
TSO avoid INSPECT 541 example of loading 80
ALLOCATE command 262 avoid moves that truncate 541 preventing overlay in 84
CALL command 262 avoid reference modification with variables, environment
compiling under XML documents 141 example of setting and accessing 456
example CLIST 264 converting to or from national 141 library-name 373
overview 262 definition 129 runtime 455
SYSTERM for compiler messages 271 encoding and storage 137 variably located data item 82
tuning considerations, performance 658, encoding for ASCII invariant variably located group 82
659 characters 129 VBREF compiler option
typed object references 598 example of generating an XML description 366
document 563 output example 415
JNI services 634 using 387
verb cross-reference listing
U parsing XML documents 541
processing data items 141 description 387
U-format record verbs used in program 387
using intrinsic functions 142
layout 167 VLR compiler option
UTF-8 data
requesting 166 description 366
using Unicode intrinsic functions 144
U-level error message 282, 384 VSAM files
unavailable files adding records to 199
QSAM 171 allocating with environment
VSAM 203 variable 206
Index 879
VSAM files (continued) WORD compiler option (continued) XML document (continued)
closing 200 multioption interaction 305 parsing with validation (continued)
coding input/output statements 193 recommended for CICS integrated restrictions 531
comparison of file organizations 187 translator 424 processing 517
creating alternate indexes 204 recommended for CICS separate specifying encoding if
DATA DIVISION entries 192 translator 427 alphanumeric 539
deleting records from 200 work data sets for compiling 267 white space 538
ENVIRONMENT DIVISION WORKING-STORAGE SECTION XML declaration 538
entries 188 client 598, 599 XML event
error processing 241 comparison with LOCAL-STORAGE CONTENT-CHARACTERS
extended addressability 211 example 15 example 557
file position indicator (CRP) 195, 198 OO client 599 when parsing segments 534
file status key 201 overview 14 encoding conflicts 545
input/output error processing 201 factory data 612 END-OF-INPUT
loading instance data 586, 609 example 557
dynamically or randomly 196 instance method 589 when parsing segments 533
extended format 197 multithreading considerations 599 EXCEPTION 544
sequentially 196 storage location for data 318 fatal errors 545
with access method services 197 workspace NAMESPACE-DECLARATION 528
opening use during sort 236 overview 524
empty 196 wrapper, definition of 620 processing 518, 522
overview 195 wrapping procedure-oriented processing procedure 520
performance considerations 209 programs 620 XML exception codes
processing files 185 Writable static area 408 for generating 700
protecting with password 202 write a block of records 168 for parsing 691
reading records from 198 WRITE ADVANCING statement 173 for parsing with
record-level sharing (RLS) WRITE statement XMLPARSE(COMPAT)
error handling 208 line-sequential files 215 handleable 693
overview 207 multithreading serialization 510 not handleable 697
preventing update problems 207 QSAM 170 for parsing with
restrictions 208 VSAM 193 XMLPARSE(XMLSS) 691
replacing records in 200 XML GENERATE statement
status codes COUNT IN 567
description 246
example 247
X NAME 565
NAMESPACE 563
x suffix with cob2 289
under z/OS NAMESPACE-PREFIX 564
XML declaration
defining data sets 203 NOT ON EXCEPTION 566
generating 563
file availability 202 ON EXCEPTION 567
specifying encoding declaration 539
JCL 206 SUPPRESS 565
white space cannot precede 538
RLS mode 207 TYPE 565
XML document
updating records 199 WITH ATTRIBUTES 563
accessing 520
VSAM terminology WITH ENCODING 566
code pages supported 536
BDAM data set 185 XML-DECLARATION 563
controlling the encoding of 566
comparison to non-VSAM terms 185 XML generation
EBCDIC special characters 540
ESDS for QSAM 185 controlling type of XML data 565
encoding 536, 537
KSDS for ISAM 185 counting generated characters 562
enhancing
RRDS for BDAM 185 description 561
example of modifying data
enhancing output
definitions 573
example of modifying data
rationale and techniques 573
W events
definitions 573
rationale and techniques 573
W-level message 282, 384 example 553
example 568
WHEN phrase generating
generating attributes 563
EVALUATE statement 95 example 568
generating elements 562
SEARCH ALL statement 87 overview 561
handling errors 567
SEARCH statement 86 handling parsing exceptions 542
ignored data items 562
WHEN-COMPILED intrinsic national language 537
naming attributes or elements 565
function 123 parser 518
no byte order mark 567
WHEN-COMPILED special register 123 parsing
overview 561
white space in XML documents 538 description 520
suppressing generation of specified
WITH DEBUGGING MODE clause example 548, 553, 556
attributes or elements 565
for debugging lines 380 large documents 535
using namespace prefixes 564
for debugging statements 380 one segment at a time 533
using namespaces 563
WITH POINTER phrase UTF-8 541
XML output
STRING 105 parsing with validation
controlling the encoding of 566
UNSTRING 107 example 558
WORD compiler option overview 530
description 367 performance considerations 531
880 Enterprise COBOL for z/OS, V5.2 Programming Guide
XML output (continued) XML-CODE special register (continued) XREF output
enhancing exception codes for parsing with COPY/BASIS cross-references 413
example of modifying data XMLPARSE(XMLSS) 691 data-name cross-references 411
definitions 573 fatal errors 545 program-name cross-references 412
rationale and techniques 573 reason code 542, 691
generating return code 542, 691
example 568
overview 561
setting to -1 525, 546
setting to 1 533
Z
z/OS
XML PARSE statement subtracting 100,000 from 545
accessing main parameters under
NOT ON EXCEPTION 521 terminating parsing 546
example 495
ON EXCEPTION 521 using in generating 566
overview 495
overview 518 using in parsing 517
compiling under 255
using 520 with code-page conflicts 545
running programs under 495
XML parser with encoding conflicts 545
z/OS UNIX
error handling 544 with generating exceptions 567
accessing environment variables
overview 518 with parsing exceptions 544
example 456
XML parsing XML-EVENT special register
overview 454
control flow with processing content 524, 547
accessing main parameters under
procedure 525 description 522
example 459
description 520 using 517, 522
overview 458
fatal errors 545 with parsing exceptions 544
compiler environment variables 283
handling encoding conflicts 545 XML-INFORMATION special
compiling from script 290
handling exceptions 542 register 535
compiling OO applications
one segment at a time content 526
example 293
example 556 description 522
overview 291
overview 533 XML-NAMESPACE special register
compiling under 283
overview 517 content 528
copybook search order 284, 288, 374
reason code 542, 691 description 522
copybooks 374
return code 542, 691 using 517
developing programs 453
special registers 522, 524 XML-NAMESPACE-PREFIX special
execution environments 453
terminating 546 register
linking OO applications
with validation content 528
example 293
example 558 description 523
overview 292
overview 530 using 517
preparing OO applications
performance considerations 531 XML-NNAMESPACE special register
example 293
restrictions 531 content 528
overview 292
XML processing procedure description 523
programs must be reentrant 480
control flow with parser 525 using 517
restrictions 453
error with EXIT PROGRAM or XML-NNAMESPACE-PREFIX special
running OO applications
GOBACK 523 register
overview 293
example content 528
XPLINK linkage 299
one segment at a time 556 description 523
running programs 453
parsing with validation 558 using 517
setting environment variables
program for processing XML 548 XML-NTEXT special register
example 456
handling encoding conflicts 546 content 527
overview 454
handling parsing exceptions 542 description 522
sort and merge restriction 219
multiple segments 533 using 517
specifying compiler options 284
restriction on XML PARSE 523 with parsing exceptions 544
z/OS UNIX file system
setting XML-CODE in 546 XML-TEXT special register
compiler data sets 258
specifying 520 content 527, 547
defining file with environment
using special registers 522, 524 description 522
variable 157
writing 522 using 517
processing files with QSAM 181
XML schemas 532 with parsing exceptions 544
reading file with ACCEPT 35
XML-CODE special register XMLPARSE compiler option
search order for DLLs in 501
content 525 choosing the parser 517
writing files with DISPLAY 36
continuation after nonzero value 546 description 368
zero suppression
control flow between parser and XPLINK linkage convention in OO
example of BLANK WHEN ZERO
processing procedure 525 applications 299
clause 45
description 522 XPLINK runtime option
PICTURE symbol Z 45
exception codes for generating 700 not recommended as a default 299
zoned decimal data (USAGE
exception codes for parsing 691 setting 299
DISPLAY) 370
exception codes for parsing with XREF compiler option
effect of ZWB on comparison to
XMLPARSE(COMPAT) description 369
alphanumeric 372
encoding conflicts 543 finding copybook data sets 386
example 43
handleable 693 finding data- and
format 47
not handleable 697 procedure-names 386
sign representation 53
getting output 387
ZONEDATA compiler option 370
Index 881
ZWB compiler option 372
882 Enterprise COBOL for z/OS, V5.2 Programming Guide
Product Number: 5655-W32
Printed in USA
SC14-7382-03
You might also like
- Systems Software Z Systems Zs Product Guide Zso03361usen 20171206No ratings yetSystems Software Z Systems Zs Product Guide Zso03361usen 20171206670 pages
- Assembler Language Programming For IBM Z System ServersNo ratings yetAssembler Language Programming For IBM Z System Servers1,313 pages
- Ibm Programming Cobol On Windows SC23-8559-00No ratings yetIbm Programming Cobol On Windows SC23-8559-00828 pages
- COBOL For AIX Programming Guide-Igyapg00No ratings yetCOBOL For AIX Programming Guide-Igyapg00748 pages
- IBM - VisualAge Cobol For Windows Programming GuideNo ratings yetIBM - VisualAge Cobol For Windows Programming Guide634 pages
- BCSC 1102 Introduction To Programming Lecture 2 Notes100% (1)BCSC 1102 Introduction To Programming Lecture 2 Notes24 pages
- PL-1 - PL-1 MVS & VM Language Reference (2nd Ed, 1995) - (IBM)No ratings yetPL-1 - PL-1 MVS & VM Language Reference (2nd Ed, 1995) - (IBM)484 pages
- COBOL Programming Course 2 Advanced TopicsNo ratings yetCOBOL Programming Course 2 Advanced Topics51 pages
- COBOL Programming Course 2 Learning COBOLNo ratings yetCOBOL Programming Course 2 Learning COBOL111 pages
- Enterprise COBOL Concepts: Dr. David Woolbright Woolbright - David@columbusstate - Edu 2013No ratings yetEnterprise COBOL Concepts: Dr. David Woolbright Woolbright - David@columbusstate - Edu 2013254 pages
- Mastering Python: A Comprehensive Approach for Beginners and BeyondFrom EverandMastering Python: A Comprehensive Approach for Beginners and BeyondNo ratings yet
- Enterprise COBOL Concepts: Dr. David Woolbright Woolbright - David@columbusstate - Edu 2013No ratings yetEnterprise COBOL Concepts: Dr. David Woolbright Woolbright - David@columbusstate - Edu 2013254 pages
- GLARE - History of The Development of A New Aircraft MaterialNo ratings yetGLARE - History of The Development of A New Aircraft Material229 pages
- MIPS Assembly Tutorial by Daniel J EllardNo ratings yetMIPS Assembly Tutorial by Daniel J Ellard97 pages
- Sap Solution Manager - Installation Guide - Windows MaxDB100% (3)Sap Solution Manager - Installation Guide - Windows MaxDB13 pages
- GCV310-RC I-Chapter 8 - Shear - Rev OE (Compatibility Mode)No ratings yetGCV310-RC I-Chapter 8 - Shear - Rev OE (Compatibility Mode)35 pages
- MDU1931 Datasheet - MagnaChip SemiconductorNo ratings yetMDU1931 Datasheet - MagnaChip Semiconductor6 pages
- The Situation of Waste Disposal in Barangay BalimbingNo ratings yetThe Situation of Waste Disposal in Barangay Balimbing13 pages
- Index of Interim Advice Notes (Ian) : Ian No. Title Manual Ref. Author Issue Date CommentsNo ratings yetIndex of Interim Advice Notes (Ian) : Ian No. Title Manual Ref. Author Issue Date Comments9 pages
- 01 - Welcome To ICND1 - Cisco Certification and Getting The Most From This SeriesNo ratings yet01 - Welcome To ICND1 - Cisco Certification and Getting The Most From This Series40 pages
- Xbox Architecture: Architecture of Consoles: A Practical Analysis, #13From EverandXbox Architecture: Architecture of Consoles: A Practical Analysis, #13No ratings yet
- MEGA Sports Camp Planning Overview ChecklistNo ratings yetMEGA Sports Camp Planning Overview Checklist5 pages
- SNES Architecture: Architecture of Consoles: A Practical Analysis, #4From EverandSNES Architecture: Architecture of Consoles: A Practical Analysis, #4No ratings yet
- Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ ScriptingFrom EverandAdvanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ ScriptingNo ratings yet
- Assignment/ Tugasan - Occupational Safety 1No ratings yetAssignment/ Tugasan - Occupational Safety 111 pages
- PlayStation Architecture: Architecture of Consoles: A Practical Analysis, #6From EverandPlayStation Architecture: Architecture of Consoles: A Practical Analysis, #6No ratings yet
- WP Maximizing Reach in LH Networks With Challenging Fiber ConditionsNo ratings yetWP Maximizing Reach in LH Networks With Challenging Fiber Conditions12 pages
- Dreamcast Architecture: Architecture of Consoles: A Practical Analysis, #9From EverandDreamcast Architecture: Architecture of Consoles: A Practical Analysis, #9No ratings yet
- Personal Data:: Course University/Boards Marks Obtained Year of PassingNo ratings yetPersonal Data:: Course University/Boards Marks Obtained Year of Passing3 pages
- General Feature of The New Numbering Plan: International Public Number StructureNo ratings yetGeneral Feature of The New Numbering Plan: International Public Number Structure2 pages
- Liquidation For MV Sheng He Hai at Narra PalawanNo ratings yetLiquidation For MV Sheng He Hai at Narra Palawan2 pages
- Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language ModelsFrom EverandSecuring ChatGPT: Best Practices for Protecting Sensitive Data in AI Language ModelsNo ratings yet
