Enterprise COBOL for z/OS

Programming Guide
V ersion 5 Release 1

SC14-7382-00

Enterprise COBOL for z/OS

Programming Guide
V ersion 5 Release 1

SC14-7382-00

Note! Before using this information and the product it supports, be sure to read the general information under Notices on page 811.

First edition This edition applies to Version 5 Release 1 of IBM Enterprise COBOL for z/OS (program number 5655-W32) and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure that you are using the correct edition for the level of the product. You can order publications online at www.ibm.com/shop/publications/order/, or order by phone or fax. IBM Software Manufacturing Solutions takes publication orders between 8:30 a.m. and 7:00 p.m. Eastern Standard Time (EST). The phone number is (800)879-2755. The fax number is (800)445-9269. You can also order publications through your IBM representative or the IBM branch office that serves your locality. Copyright IBM Corporation 1991, 2013. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Tables . . . . . . . . . . . . . . . xiii Preface . . . . . . . . . . . . . . xv
About this information . . . . . . . . . . xv How this information will help you . . . . . xv Abbreviated terms . . . . . . . . . . . xv Comparison of commonly used terms . . . . xvi How to read syntax diagrams . . . . . . . xvi How examples are shown . . . . . . . . xviii Additional documentation and support . . . . xviii Summary of changes . . . . . . . . . . xviii Version 5 Release 1 . . . . . . . . . . xix How to send your comments . . . . . . . . xx Accessibility . . . . . . . . . . . . . . xxi Interface information . . . . . . . . . . xxi Keyboard navigation . . . . . . . . . . xxi Accessibility of this information . . . . . . xxi IBM and accessibility. . . . . . . . . . xxii Assigning values to elementary data items (MOVE) . . . . . . . . . . . . . . Assigning values to group data items (MOVE) . Assigning arithmetic results (MOVE or COMPUTE) . . . . . . . . . . . . . Assigning input from a screen or file (ACCEPT) Displaying values on a screen or in a file (DISPLAY) Displaying data on the system logical output device . . . . . . . . . . . . . . . Using WITH NO ADVANCING . . . . . . Using intrinsic functions (built-in functions) . . . Using tables (arrays) and pointers . . . . . . . Storage and its addressability . . . . . . . . Settings for RMODE . . . . . . . . . . . Location of data areas . . . . . . . . . . Storage for LOCAL-STORAGE data . . . . . Storage for external data . . . . . . . . . Storage for QSAM input-output buffers . . . . 32 33 34 35 36 37 38 39 40 40 41 42 42 42 42

| |

Part 1. Coding your program . . . . 1

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

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

Defining numeric data. . . . . . . . . . . Displaying numeric data . . . . . . . . . . Controlling how numeric data is stored . . . . . Formats for numeric data. . . . . . . . . . External decimal (DISPLAY and NATIONAL) items . . . . . . . . . . . . . . . External floating-point (DISPLAY and NATIONAL) items . . . . . . . . . . . Binary (COMP) items . . . . . . . . . . Native binary (COMP-5) items . . . . . . . Packed-decimal (COMP-3) items . . . . . . Internal floating-point (COMP-1 and COMP-2) items . . . . . . . . . . . . . . . Examples: numeric data and internal representation . . . . . . . . . . . . Data format conversions . . . . . . . . . . Conversions and precision . . . . . . . . Sign representation of zoned and packed-decimal data . . . . . . . . . . . . . . . . . Checking for incompatible data (numeric class test) Performing arithmetic . . . . . . . . . . . Using COMPUTE and other arithmetic statements . . . . . . . . . . . . . . Using arithmetic expressions . . . . . . . Using numeric intrinsic functions . . . . . . Using math-oriented callable services . . . . . Using date callable services . . . . . . . . Examples: numeric intrinsic functions . . . . Fixed-point contrasted with floating-point arithmetic Floating-point evaluations . . . . . . . . Fixed-point evaluations . . . . . . . . . Arithmetic comparisons (relation conditions) . . Examples: fixed-point and floating-point evaluations . . . . . . . . . . . . . 45 47 48 49 49 50 51 51 52 52 53 54 54 55 56 57 58 58 59 60 62 62 64 65 65 65 66

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

Using variables, structures, literals, and Using variables . . . . . . . Using data items and group items . Using literals . . . . . . . . Using constants . . . . . . . Using figurative constants . . . Assigning values to data items . . . Examples: initializing data items . Initializing a structure (INITIALIZE)
Copyright IBM Corp. 1991, 2013

constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . .

23 23 24 26 26 27 27 28 31

iii

Using currency signs . . . . . . Example: multiple currency signs .

. .

. .

. .

. .

. 67 . 68

Chapter 4. Handling tables . . . . . . 69

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

Converting data items (intrinsic functions) . . Changing case (UPPER-CASE, LOWER-CASE) Transforming to reverse order (REVERSE) . . Converting to numbers (NUMVAL, NUMVAL-C) . . . . . . . . . . . Converting from one code page to another . Evaluating data items (intrinsic functions) . . . Evaluating single characters for collating sequence . . . . . . . . . . . . . Finding the largest or smallest data item . . Finding the length of data items . . . . . Finding the date of compilation . . . . .

. 120 121 . 121 . 122 . 123 . 123 . . . . 124 124 126 127

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

COBOL statements and national data . . . . . Intrinsic functions and national data. . . . . . Unicode and the encoding of language characters Using national data (Unicode) in COBOL . . . . Defining national data items . . . . . . . Using national literals . . . . . . . . . Using national-character figurative constants Defining national numeric data items . . . . National groups . . . . . . . . . . . Using national groups . . . . . . . . . Storage of character data . . . . . . . . Converting to or from national (Unicode) representation . . . . . . . . . . . . . Converting alphanumeric, DBCS, and integer to national (MOVE) . . . . . . . . . . . Converting alphanumeric or DBCS to national (NATIONAL-OF) . . . . . . . . . . . Converting national to alphanumeric (DISPLAY-OF) . . . . . . . . . . . . Overriding the default code page. . . . . . Conversion exceptions . . . . . . . . . Example: converting to and from national data Processing UTF-8 data . . . . . . . . . . Using intrinsic functions to process UTF-8 encoded data . . . . . . . . . . . . Processing Chinese GB 18030 data . . . . . . Comparing national (UTF-16) data . . . . . . Comparing two class national operands . . . Comparing class national and class numeric operands . . . . . . . . . . . . . . Comparing national numeric and other numeric operands . . . . . . . . . . . . . . Comparing national and other character-string operands . . . . . . . . . . . . . . Comparing national data and alphanumeric-group operands . . . . . . . Coding for use of DBCS support . . . . . . . Declaring DBCS data . . . . . . . . . . Using DBCS literals . . . . . . . . . . Testing for valid DBCS characters . . . . . Processing alphanumeric data items that contain DBCS data . . . . . . . . . . . . . 130 132 133 134 135 135 136 137 137 139 141 142 142 143 144 144 144 145 145 146 151 152 153 153 154 154 154 155 155 156 157 157

. 77 . 79 . 80 81 . 83 . 84 . 84 . 85 . 86 . 88 . 89 . 90 . 91 . 92 . 92 . 93

| | |

Chapter 5. Selecting and repeating program actions . . . . . . . . . . 97

Selecting program actions . . . . . . . Coding a choice of actions . . . . . . Coding conditional expressions . . . . Repeating program actions . . . . . . . Choosing inline or out-of-line PERFORM . Coding a loop . . . . . . . . . . Looping through a table . . . . . . . Executing multiple paragraphs or sections. . . . . . . . . . 97 . 97 . 102 . 105 . 106 . 107 . 108 . 108

| | |

Chapter 6. Handling strings . . . . . 109

Joining data items (STRING) . . . . . . Example: STRING statement . . . . . Splitting data items (UNSTRING). . . . . Example: UNSTRING statement . . . . Manipulating null-terminated strings . . . Example: null-terminated strings . . . . Referring to substrings of data items . . . Reference modifiers . . . . . . . . Example: arithmetic expressions as reference modifiers . . . . . . . . . . . . Example: intrinsic functions as reference modifiers . . . . . . . . . . . . Tallying and replacing data items (INSPECT) . Examples: INSPECT statement. . . . . . . 109 . . 110 . . 111 . . 112 . . 114 . . 115 . . 115 . . 117 . . . . . 118 . 118 . 119 . 119

Chapter 8. Processing files . . . . . 159

File organization and input-output devices . . . 159

iv

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

Choosing file organization and access mode Format for coding input and output . . Allocating files . . . . . . . . . . Checking for input or output errors . . .

. . . .

. . . .

. . . .

161 162 163 164

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

Defining line-sequential files and records in COBOL . . . . . . . . . . . . . . . Describing the structure of a line-sequential file Control characters in line-sequential files . . . Allocating line-sequential files . . . . . . . . Coding input-output statements for line-sequential files . . . . . . . . . . . . . . . . Opening line-sequential files . . . . . . . Reading records from line-sequential files . . . Adding records to line-sequential files . . . . Closing line-sequential files. . . . . . . . Handling errors in line-sequential files . . . . . 219 220 220 221 221 222 222 223 223 224

Chapter 9. Processing QSAM files . . 165

Defining QSAM files and records in COBOL . . . Establishing record formats. . . . . . . . Setting block sizes . . . . . . . . . . . Coding input and output statements for QSAM files . . . . . . . . . . . . . . . . Opening QSAM files . . . . . . . . . . Dynamically creating QSAM files. . . . . . Adding records to QSAM files. . . . . . . Updating QSAM files . . . . . . . . . Writing QSAM files to a printer or spooled data set . . . . . . . . . . . . . . . . Closing QSAM files . . . . . . . . . . Handling errors in QSAM files . . . . . . . Working with QSAM files . . . . . . . . . Defining and allocating QSAM files . . . . . Retrieving QSAM files . . . . . . . . . Ensuring that file attributes match your program . . . . . . . . . . . . . . Using striped extended-format QSAM data sets Allocation of buffers for QSAM files. . . . . Accessing z/OS UNIX files using QSAM . . . . Processing QSAM ASCII files on tape . . . . . 165 166 173 176 176 177 178 178 178 179 180 181 181 183 184 187 187 188 189

Chapter 12. Sorting and merging files

225
226 226 227 228 228 229 230 231 231 232 232 233 234 235 235 236 236 237 237 238 238 240 240 241 242 243 243 244 244

Chapter 10. Processing VSAM files

191
192 193 194 195 196 197 198 199 201 202 205 205 206 207 207 207 208 209 209 210 210 211 213 215 216 217

VSAM files . . . . . . . . . . . . . . Defining VSAM file organization and records . . Specifying sequential organization for VSAM files . . . . . . . . . . . . . . . Specifying indexed organization for VSAM files Specifying relative organization for VSAM files Specifying access modes for VSAM files . . . Defining record lengths for VSAM files. . . . Coding input and output statements for VSAM files . . . . . . . . . . . . . . . . File position indicator . . . . . . . . . Opening a file (ESDS, KSDS, or RRDS) . . . . Reading records from a VSAM file . . . . . Updating records in a VSAM file . . . . . . Adding records to a VSAM file . . . . . . Replacing records in a VSAM file. . . . . . Deleting records from a VSAM file . . . . . Closing VSAM files . . . . . . . . . . Handling errors in VSAM files . . . . . . . Protecting VSAM files with a password . . . . Example: password protection for a VSAM indexed file . . . . . . . . . . . . . Working with VSAM data sets under z/OS and z/OS UNIX . . . . . . . . . . . . . . Defining VSAM files . . . . . . . . . . Creating alternate indexes . . . . . . . . Allocating VSAM files . . . . . . . . . Sharing VSAM files through RLS . . . . . . Allocation of record areas for VSAM files . . . . Improving VSAM performance . . . . . . .

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

Chapter 13. Handling errors . . . . . 245

Requesting dumps . . . . . . . . . . Handling errors in joining and splitting strings . Handling errors in arithmetic operations . . . Example: checking for division by zero . . . Handling errors in input and output operations Using the end-of-file condition (AT END) . . . . . . 245 246 246 247 247 . 249

Contents

Coding ERROR declaratives . . . . . . Using file status keys . . . . . . . . . Example: file status key . . . . . . . . Using VSAM status codes (VSAM files only) Example: checking VSAM status codes . . . Coding INVALID KEY phrases . . . . . Example: FILE STATUS and INVALID KEY . Handling errors when calling programs . . . Writing routines for handling errors . . . . .

. 250 . 251 . 252 253 . 254 . 255 . 255 . 256 . 256

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

Setting environment variables under z/OS UNIX Specifying compiler options under z/OS UNIX . Compiling and linking with the cob2 command Creating a DLL under z/OS UNIX . . . . Example: using cob2 to compile and link under z/OS UNIX . . . . . . . . . . . . cob2 syntax and options . . . . . . . . cob2 input and output files . . . . . . . Compiling using scripts . . . . . . . . . 291 . 292 293 . 294 . . . . 295 295 297 298

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

Chapter 14. Compiling under z/OS 261
261 262 267 269 269 270 271 273 273 275 276 276 277 277 277 278 278 278 279 280 281 281 281 282 283 284 284 285 286 287 287 288 288 Compiling with JCL . . . . . . . . . . . Using a cataloged procedure . . . . . . . Writing JCL to compile programs. . . . . . Compiling under TSO . . . . . . . . . . Example: ALLOCATE and CALL for compiling under TSO . . . . . . . . . . . . . Example: CLIST for compiling under TSO . . . Starting the compiler from an assembler program Defining compiler input and output . . . . . . Data sets used by the compiler under z/OS . . Defining the source code data set (SYSIN) . . . Defining a compiler-option data set (SYSOPTF) Specifying source libraries (SYSLIB) . . . . . Defining the output data set (SYSPRINT) . . . Directing compiler messages to your terminal (SYSTERM) . . . . . . . . . . . . . Creating object code (SYSLIN or SYSPUNCH) Defining an associated-data file (SYSADATA) Defining the Java-source output file (SYSJAVA) Defining the library-processing output file (SYSMDECK) . . . . . . . . . . . . Specifying compiler options under z/OS . . . . Specifying compiler options in the PROCESS (CBL) statement . . . . . . . . . . . Example: specifying compiler options using JCL Example: specifying compiler options under TSO . . . . . . . . . . . . . . . Compiler options and compiler output under z/OS . . . . . . . . . . . . . . . Compiling multiple programs (batch compilation) Example: batch compilation . . . . . . . Specifying compiler options in a batch compilation . . . . . . . . . . . . . Example: precedence of options in a batch compilation . . . . . . . . . . . . . Example: LANGUAGE option in a batch compilation . . . . . . . . . . . . . Correcting errors in your source program . . . . Generating a list of compiler messages . . . . Messages and listings for compiler-detected errors . . . . . . . . . . . . . . . Format of compiler diagnostic messages . . . Severity codes for compiler diagnostic messages

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

Compiling, linking, and running OO applications under z/OS UNIX. . . . . . . . . . . . Compiling OO applications under z/OS UNIX Preparing OO applications under z/OS UNIX Example: compiling and linking a COBOL class definition under z/OS UNIX . . . . . . . Running OO applications under z/OS UNIX Compiling, linking, and running OO applications in JCL or TSO/E . . . . . . . . . . . . Compiling OO applications in JCL or TSO/E Preparing and running OO applications in JCL or TSO/E. . . . . . . . . . . . . . Example: compiling, linking, and running an OO application using JCL . . . . . . . . Using Java SDKs for z/OS . . . . . . . . . Object-oriented syntax, and Java 5 or Java 6 . . 299 299 300 301 302 303 304 305 306 308 309

Chapter 17. Compiler options . . . . 311

Option settings for Standard conformance. . . . . . Conflicting compiler options ADATA . . . . . . . ADV . . . . . . . . AFP . . . . . . . . ARCH. . . . . . . . ARITH . . . . . . . AWO . . . . . . . . BLOCK0 . . . . . . . BUFSIZE . . . . . . . CICS . . . . . . . . CODEPAGE . . . . . . COMPILE . . . . . . CURRENCY . . . . . . DATA . . . . . . . . DBCS . . . . . . . . DECK . . . . . . . . DIAGTRUNC . . . . . DISPSIGN . . . . . . DLL . . . . . . . . DUMP . . . . . . . DYNAM . . . . . . . EXIT . . . . . . . . EXPORTALL . . . . . FASTSRT . . . . . . . FLAG . . . . . . . . FLAGSTD . . . . . . COBOL 85 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 314 315 315 316 317 318 319 319 321 321 322 325 325 326 327 328 328 329 330 331 332 332 335 335 336 337

| |

vi

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

HGPR . . . . . . . . . INTDATE . . . . . . . LANGUAGE . . . . . . LINECOUNT . . . . . . LIST . . . . . . . . . MAP . . . . . . . . . MAXPCF . . . . . . . . MDECK . . . . . . . . NAME . . . . . . . . NSYMBOL . . . . . . . NUMBER . . . . . . . NUMPROC . . . . . . . OBJECT . . . . . . . . OFFSET . . . . . . . . OPTFILE . . . . . . . . OPTIMIZE . . . . . . . OUTDD . . . . . . . . PGMNAME . . . . . . . PGMNAME(COMPAT) . . PGMNAME(LONGUPPER). PGMNAME(LONGMIXED) Usage notes . . . . . . QUOTE/APOST . . . . . RENT . . . . . . . . . RMODE . . . . . . . . SEQUENCE . . . . . . . SIZE . . . . . . . . . SOURCE . . . . . . . . SPACE . . . . . . . . SQL . . . . . . . . . SQLCCSID . . . . . . . SSRANGE . . . . . . . STGOPT . . . . . . . . TERMINAL . . . . . . . TEST . . . . . . . . . THREAD . . . . . . . . TRUNC . . . . . . . . TRUNC example 1 . . . TRUNC example 2 . . . VBREF . . . . . . . . WORD . . . . . . . . XREF . . . . . . . . . ZWB . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

338 339 340 341 341 342 343 344 345 346 347 347 348 349 350 351 352 353 353 354 354 354 355 355 357 358 358 359 359 360 361 362 363 363 364 366 368 369 370 370 371 371 373

Finding program entity definitions and references . . . . . . . . . . Listing data items . . . . . . . . Using the debugger . . . . . . . . Getting listings . . . . . . . . . . Example: short listing . . . . . . Example: SOURCE and NUMBER output Example: MAP output . . . . . . Reading LIST output . . . . . . . Example: XREF output: data-name cross-references. . . . . . . . . Example: OFFSET compiler output . . Example: VBREF compiler output . .

. . . . . . . . . . .

. . . . . . . . . . .

. . . . . . . .

388 388 389 390 392 394 395 399

. 414 . 417 . 418

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

Chapter 20. Developing COBOL programs for CICS . . . . . . . . . 421
Coding COBOL programs to run under CICS Getting the system date under CICS. . . Calling to or from COBOL programs . . Determining the success of ECI calls. . . Compiling with the CICS option . . . . . Separating CICS suboptions . . . . . Integrated CICS translator . . . . . . Using the separate CICS translator . . . . CICS reserved-word table . . . . . . . Handling errors by using CICS HANDLE . . Example: handling errors by using CICS HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 423 424 425 425 427 427 428 430 430

. 431

Chapter 21. Programming for a DB2 environment . . . . . . . . . . . . 433

DB2 coprocessor . . . . . . . . . . . . Coding SQL statements . . . . . . . . . . Using SQL INCLUDE with the DB2 coprocessor Using character data in SQL statements . . . Using national decimal data in SQL statements Using national group items in SQL statements Using binary items in SQL statements . . . . Determining the success of SQL statements . . Compiling with the SQL option . . . . . . . Separating DB2 suboptions . . . . . . . . COBOL and DB2 CCSID determination. . . . . Code-page determination for string host variables in SQL statements . . . . . . . Programming with the SQLCCSID or NOSQLCCSID option . . . . . . . . . Differences in how the DB2 precompiler and coprocessor behave . . . . . . . . . . . Period at the end of EXEC SQL INCLUDE statements . . . . . . . . . . . . . EXEC SQL INCLUDE and nested COPY REPLACING . . . . . . . . . . . . EXEC SQL and REPLACE or COPY REPLACING . . . . . . . . . . . . Source code after an END-EXEC statement . . Multiple definitions of host variables . . . .
Contents

Chapter 18. Compiler-directing statements . . . . . . . . . . . . 375 Chapter 19. Debugging . . . . . . . 379

Debugging with source language . . . . . Tracing program logic . . . . . . . Finding and handling input-output errors . Validating data . . . . . . . . . . Moving, initializing or setting uninitialized Generating information about procedures . Debugging using compiler options . . . . Finding coding errors . . . . . . . Finding line sequence problems . . . . Checking for valid ranges . . . . . . Selecting the level of error to be diagnosed . . . . . . . . data . . . . . . . . . . . . 379 380 381 381 382 382 384 384 385 385 386

433 434 435 435 436 437 437 437 438 439 439 440 440 441 441 442 442 442 442

vii

EXEC SQL statement continuation lines . . Bit-data host variables . . . . . . . . SQL-INIT-FLAG . . . . . . . . . . Choosing the DYNAM or NODYNAM compiler option . . . . . . . . . . . . . . .

. 443 . 443 . 443 . 443

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

Compiling and linking COBOL programs for running under IMS . . . . . . . . . . . Using object-oriented COBOL and Java under IMS Calling a COBOL method from a Java application under IMS . . . . . . . . . Building a mixed COBOL-Java application that starts with COBOL . . . . . . . . . . Writing mixed-language IMS applications . . . 445 446 446 447 448

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

Running in z/OS UNIX environments . . . . Setting and accessing environment variables . . Setting environment variables that affect execution . . . . . . . . . . . . . Runtime environment variables . . . . . Example: setting and accessing environment variables . . . . . . . . . . . . . Calling UNIX/POSIX APIs . . . . . . . . Accessing main program parameters under z/OS UNIX . . . . . . . . . . . . . . . Example: accessing main program parameters under z/OS UNIX. . . . . . . . . . . 451 . 452 . 453 . 453 . 454 . 454 . 456 . 457

Testing for OMITTED arguments . . . . . Coding the LINKAGE SECTION . . . . . . Coding the PROCEDURE DIVISION for passing arguments . . . . . . . . . . . . . Grouping data to be passed . . . . . . Handling null-terminated strings . . . . . Using pointers to process a chained list . . Passing return-code information . . . . . . Using the RETURN-CODE special register. . Using PROCEDURE DIVISION RETURNING . .. . . . . . . . . . . . . . . . Specifying CALL . . . RETURNING . . . . Sharing data by using the EXTERNAL clause. . Sharing files between programs (external files) . Example: using external files . . . . . . Accessing main program parameters under z/OS Example: accessing main program parameters under z/OS . . . . . . . . . . . .

. 484 . 485 . . . . . . . . . . . . 486 486 486 487 490 490 490 491 491 491 492 495

. 496

Chapter 26. Creating a DLL or a DLL application . . . . . . . . . . . . 497

Dynamic link libraries (DLLs) . . . . . . . . Compiling programs to create DLLs . . . . . . Linking DLLs . . . . . . . . . . . . . Example: sample JCL for a procedural DLL application . . . . . . . . . . . . . . Using CALL identifier with DLLs . . . . . . Search order for DLLs in the z/OS UNIX file system . . . . . . . . . . . . . . Using DLL linkage and dynamic calls together . . Using procedure or function pointers with DLLs Calling DLLs from non-DLLs . . . . . . . Example: calling DLLs from non-DLLs . . . . Using COBOL DLLs with C/C++ programs . . . Using DLLs in OO COBOL applications . . . . 497 498 499 500 501 501 502 503 504 504 506 506

Part 4. Structuring complex applications . . . . . . . . . . . 459

Chapter 24. Using subprograms . . . 461
Main programs, subprograms, and calls . . . . Ending and reentering main programs or subprograms . . . . . . . . . . . . . Transferring control to another program . . . . Making static calls. . . . . . . . . . . Making dynamic calls . . . . . . . . . AMODE switching . . . . . . . . . . Performance considerations of static and dynamic calls . . . . . . . . . . . . Making both static and dynamic calls . . . . Examples: static and dynamic CALL statements Calling nested COBOL programs . . . . . . Making recursive calls . . . . . . . . . . Calling to and from object-oriented programs . . Using procedure and function pointers . . . . . Deciding which type of pointer to use . . . . Calling alternate entry points . . . . . . . Making programs reentrant . . . . . . . . 461 462 463 464 465 468 469 470 470 472 475 475 476 477 477 478

Chapter 27. Preparing COBOL programs for multithreading . . . . . 509

Multithreading . . . . . . . . . . . . Choosing THREAD to support multithreading . Transferring control to multithreaded programs . Ending multithreaded programs . . . . . . Processing files with multithreading . . . . . File-definition (FD) storage . . . . . . . Serializing file access with multithreading . . Example: usage patterns of file input and output with multithreading. . . . . . . Handling COBOL limitations with multithreading . . . . . . . 510 511 511 512 512 513 513

. 514 515

Part 5. Using XML and COBOL together . . . . . . . . . . . . . 517

Chapter 28. Processing XML input
XML parser in COBOL . . . . . . . . . Accessing XML documents . . . . . . . . Parsing XML documents . . . . . . . . Writing procedures to process XML . . . . XML events . . . . . . . . . . . . Transforming XML text to COBOL data items

519
. . . . . 520 522 522 524 525 529

Chapter 25. Sharing data . . . . . . 481

Passing data . . . . . . . . . . . . . Describing arguments in the calling program Describing parameters in the called program . 481 483 484

viii

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

| |

Parsing XML documents with validation . . . Parsing XML documents one segment at a time Handling splits using the XML-INFORMATION special register . . . . . . . . . . . . The encoding of XML documents. . . . . . . XML input document encoding . . . . . . Parsing XML documents encoded in UTF-8 . . Handling XML PARSE exceptions . . . . . . How the XML parser handles errors. . . . . Handling encoding conflicts . . . . . . . Terminating XML parsing . . . . . . . . . XML PARSE examples . . . . . . . . . . Example: parsing a simple document . . . . Example: program for processing XML . . . . Example: parsing an XML document that uses namespaces . . . . . . . . . . . . . Example: parsing an XML document one segment at a time . . . . . . . . . . . Example: parsing XML documents with validation . . . . . . . . . . . . .

530 534 536 537 538 540 542 542 543 544 544 545 545 549 551 553

Chapter 29. Producing XML output

557
557 562 563 564 564 566 569 569 569

Generating XML output . . . . . . . . . . Controlling the encoding of generated XML output Handling XML GENERATE exceptions . . . . . Example: generating XML . . . . . . . . . Program XGFX . . . . . . . . . . . . Program Pretty . . . . . . . . . . . . Output from program XGFX . . . . . . . Enhancing XML output . . . . . . . . . . Example: enhancing XML output . . . . . .

REPOSITORY paragraph for defining a client DATA DIVISION for defining a client . . . . Comparing and setting object references . . . Invoking methods (INVOKE) . . . . . . . Creating and initializing instances of classes . . Freeing instances of classes . . . . . . . . Example: defining a client . . . . . . . . Defining a subclass . . . . . . . . . . . CLASS-ID paragraph for defining a subclass REPOSITORY paragraph for defining a subclass WORKING-STORAGE SECTION for defining subclass instance data . . . . . . . . . Defining a subclass instance method . . . . Example: defining a subclass (with methods) Defining a factory section . . . . . . . . . WORKING-STORAGE SECTION for defining factory data . . . . . . . . . . . . . Defining a factory method . . . . . . . . Example: defining a factory (with methods) . . Wrapping procedure-oriented COBOL programs Structuring OO applications . . . . . . . . Examples: COBOL applications that run using the java command . . . . . . . . . . .

593 594 595 596 601 603 603 604 605 605 606 606 607 608 609 609 612 617 618 618

Chapter 31. Communicating with Java methods . . . . . . . . . . . . . 621

Accessing JNI services . . . . . . . . . . Handling Java exceptions . . . . . . . . Managing local and global references . . . . Java access controls . . . . . . . . . . Sharing data with Java . . . . . . . . . . Coding interoperable data types in COBOL and Java . . . . . . . . . . . . . . . Declaring arrays and strings for Java . . . . Manipulating Java arrays . . . . . . . . Manipulating Java strings . . . . . . . . Example: J2EE client written in COBOL . . . . COBOL client (ConverterClient.cbl) . . . . . Java client (ConverterClient.java) . . . . . . 621 623 624 626 626 626 627 629 631 633 634 636

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

Chapter 30. Writing object-oriented programs . . . . . . . . . . . . . 575
Example: accounts. . . . . . . . . . . Subclasses . . . . . . . . . . . . Defining a class . . . . . . . . . . . CLASS-ID paragraph for defining a class . . REPOSITORY paragraph for defining a class WORKING-STORAGE SECTION for defining class instance data . . . . . . . . . . Example: defining a class . . . . . . . Defining a class instance method . . . . . . METHOD-ID paragraph for defining a class instance method . . . . . . . . . . INPUT-OUTPUT SECTION for defining a class instance method . . . . . . . . . . DATA DIVISION for defining a class instance method . . . . . . . . . . . . . PROCEDURE DIVISION for defining a class instance method . . . . . . . . . . Overriding an instance method . . . . . Overloading an instance method . . . . . Coding attribute (get and set) methods . . . Example: defining a method . . . . . . Defining a client . . . . . . . . . . . . . . . 576 577 578 580 580

Part 7. Specialized processing . . 639

Chapter 32. Interrupts and checkpoint/restart . . . . . . . . . 641
Setting checkpoints . . . . . . . . . . . Designing checkpoints . . . . . . . . . Testing for a successful checkpoint . . . . . DD statements for defining checkpoint data sets Messages generated during checkpoint . . . . Restarting programs . . . . . . . . . . . Requesting automatic restart . . . . . . . Requesting deferred restart . . . . . . . . Formats for requesting deferred restart . . . . Resubmitting jobs for restart . . . . . . . Example: restarting a job at a specific checkpoint step. . . . . . . . . . . . Example: requesting a step restart . . . . . Example: resubmitting a job for a step restart Example: resubmitting a job for a checkpoint restart . . . . . . . . . . . . . . .
Contents

. 582 . 583 . 583 . 584 . 585 . 585 . . . . . . 586 587 588 589 590 592

641 642 643 643 644 644 645 645 646 647 647 647 648 648

ix

Part 8. Improving performance and productivity . . . . . . . . . . . 651

Chapter 33. Tuning your program . . . 653
Using an optimal programming style . . . Using structured programming . . . . Factoring expressions. . . . . . . . Using symbolic constants . . . . . . Choosing efficient data types . . . . . . Choosing efficient computational data items Using consistent data types. . . . . . Making arithmetic expressions efficient . . Making exponentiations efficient . . . . Handling tables efficiently . . . . . . . Optimization of table references . . . . Optimizing your code . . . . . . . . Optimization . . . . . . . . . . Choosing compiler features to enhance performance . . . . . . . . . . . . Performance-related compiler options . . Evaluating performance . . . . . . . Running efficiently with CICS, IMS, or VSAM Choosing static or dynamic calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654 654 654 655 655 655 656 656 656 657 658 659 659 660 661 664 665 666

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

DBCS notation . . . . . . . . . . . . . Alphanumeric to DBCS data conversion (IGZCA2D) . . . . . . . . . . . . . . IGZCA2D syntax . . . . . . . . . . . IGZCA2D return codes . . . . . . . . . Example: IGZCA2D . . . . . . . . . . DBCS to alphanumeric data conversion (IGZCD2A) IGZCD2A syntax . . . . . . . . . . . IGZCD2A return codes . . . . . . . . . Example: IGZCD2A . . . . . . . . . . 687 687 688 688 689 690 690 691 691

Appendix C. XML reference material

XML PARSE exceptions . . . XML GENERATE exceptions . . . . . . . . . . . . .

693
. 693 . 695

Appendix D. EXIT compiler option . . 697

Using the user-exit work area . . . . . . Calling from exit modules . . . . . . . Processing of INEXIT. . . . . . . . . INEXIT parameters . . . . . . . . Processing of LIBEXIT . . . . . . . . Processing of LIBEXIT with nested COPY statements . . . . . . . . . . . LIBEXIT parameters . . . . . . . . Processing of PRTEXIT . . . . . . . . PRTEXIT parameters . . . . . . . . Processing of ADEXIT . . . . . . . . ADEXIT parameters . . . . . . . . Processing of MSGEXIT . . . . . . . . MSGEXIT parameters . . . . . . . Customizing compiler-message severities . Example: MSGEXIT user exit . . . . . Error handling for exit modules . . . . . Using the EXIT compiler option with CICS and SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 698 698 698 699 700 701 702 703 703 704 705 705 706 709 713

Chapter 34. Simplifying coding . . . . 667

Eliminating repetitive coding . . . . . . . Example: using the COPY statement. . . . Using Language Environment callable services . Sample list of Language Environment callable services . . . . . . . . . . . . . Calling Language Environment services . . Example: Language Environment callable services . . . . . . . . . . . . . . 667 . 668 . 669 . 670 . 671 . 672

Part 9. Appendixes . . . . . . . . 675

Appendix A. Intermediate results and arithmetic precision . . . . . . . . 677
Terminology used for intermediate results . . . . Example: calculation of intermediate results . . . Fixed-point data and intermediate results . . . . Addition, subtraction, multiplication, and division . . . . . . . . . . . . . . Exponentiation . . . . . . . . . . . . Example: exponentiation in fixed-point arithmetic . . . . . . . . . . . . . Truncated intermediate results. . . . . . . Binary data and intermediate results . . . . Intrinsic functions evaluated in fixed-point arithmetic . . . . . . . . . . . . . . Integer functions . . . . . . . . . . . Mixed functions . . . . . . . . . . . Floating-point data and intermediate results . . . Exponentiations evaluated in floating-point arithmetic . . . . . . . . . . . . . Intrinsic functions evaluated in floating-point arithmetic . . . . . . . . . . . . . Arithmetic expressions in nonarithmetic statements 678 679 679 679 680 681 681 682 682 682 683 684 685 685 685

. 714

Appendix E. JNI.cpy copybook . . . . 717 Appendix F. COBOL SYSADATA file contents . . . . . . . . . . . . . 723
Compiler options that affect the SYSADATA file SYSADATA record types . . . . . . . . Example: SYSADATA . . . . . . . . . SYSADATA record descriptions . . . . . . Common header section . . . . . . . . . Job identification record: X'0000' . . . . . . ADATA identification record: X'0001' . . . . Compilation unit start | end record: X'0002' . . Options record: X'0010' . . . . . . . . . External symbol record: X'0020' . . . . . . Parse tree record: X'0024' . . . . . . . . Token record: X'0030' . . . . . . . . . . Source error record: X'0032'. . . . . . . . Source record: X'0038' . . . . . . . . . COPY REPLACING record: X'0039' . . . . . Symbol record: X'0042' . . . . . . . . . Symbol cross-reference record: X'0044' . . . . . . . . . . . . . . . . . . . . 723 724 725 726 727 729 730 730 731 740 740 756 770 770 771 772 783

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

Nested program record: Library record: X'0060' Statistics record: X'0090' EVENTS record: X'0120'

X'0046' . . . . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

785 785 786 786

Preparing to run IGYTSALE . . . . Language elements and concepts that are illustrated . . . . . . . . . . .

. .

. .

. 804 . 805

Notices . . . . . . . . . . . . . . 811 Appendix G. Using sample programs

IGYTCARA: batch application . . . . Input data for IGYTCARA . . . . Report produced by IGYTCARA . . Preparing to run IGYTCARA . . . IGYTCARB: interactive program . . . Preparing to run IGYTCARB . . . IGYTSALE: nested program application Input data for IGYTSALE . . . . Reports produced by IGYTSALE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

791
. . . . . . . . . 791 792 793 794 795 796 798 799 801

Trademarks .

. 813

Glossary . . . . . . . . . . . . . 815 List of resources . . . . . . . . . . 847

Enterprise COBOL for z/OS Related publications . . . . . . . . . . . . . . . . . . 847 . 847

Index . . . . . . . . . . . . . . . 849

Contents

xi

xii

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

Tables
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. FILE-CONTROL entries . . . . . . . . 6 FILE SECTION entries . . . . . . . . 13 Assignment to data items in a program 27 Effect of RMODE and RENT compiler options on the RMODE attribute . . . . . 41 Ranges in value of COMP-5 data items 51 Internal representation of numeric items 53 NUMCLS(PRIM) and valid signs . . . . . 57 NUMCLS(ALT) and valid signs . . . . . 57 Order of evaluation of arithmetic operators 59 Numeric intrinsic functions . . . . . . . 60 Compatibility of math intrinsic functions and callable services . . . . . . . . . . . 61 INTDATE(LILIAN) and compatibility of date intrinsic functions and callable services . . . 62 INTDATE(ANSI) and compatibility of date intrinsic functions and callable services . . . 62 Hexadecimal values of the euro sign . . . . 67 COBOL statements and national data 130 Intrinsic functions and national character data. . . . . . . . . . . . . . . 132 National group items that are processed with group semantics . . . . . . . . 141 Encoding and size of alphanumeric, DBCS, and national data . . . . . . . . . . 141 Summary of file organizations, access modes, and record formats of COBOL files . 161 QSAM file allocation . . . . . . . . . 182 Maximum record length of QSAM files 185 Comparison of VSAM, COBOL, and non-VSAM terminology . . . . . . . . 191 Comparison of VSAM data-set types 193 VSAM file organization, access mode, and record format . . . . . . . . . . . 194 Definition of VSAM fixed-length records 198 Definition of VSAM variable-length records 199 I/O statements for VSAM sequential files 200 I/O statements for VSAM relative and indexed files . . . . . . . . . . . 201 Statements to load records into a VSAM file 204 Statements to update records in a VSAM file . . . . . . . . . . . . . . . 206 Methods for improving VSAM performance 217 Methods for checking for sort errors with NOFASTSRT . . . . . . . . . . . 240 Methods for controlling sort behavior 240 Compiler data sets . . . . . . . . . 273 Block size of fixed-length compiler data sets 275 Block size of variable-length compiler data sets . . . . . . . . . . . . . . . 275 Types of compiler output under z/OS 281 Severity codes for compiler diagnostic messages . . . . . . . . . . . . . 288 Input files to the cob2 command . . . . . 297 Output files from the cob2 command 297 41. Commands for compiling and linking a class definition . . . . . . . . . . . 42. java command options for customizing the JVM . . . . . . . . . . . . . . 43. Compiler options . . . . . . . . . . 44. Mutually exclusive compiler options 45. EBCDIC multibyte coded character set identifiers . . . . . . . . . . . . 46. DISPLAY output with the DISPSIGN(SEP) option or the DISPSIGN(SEP) option specified: . 47. Values of the LANGUAGE compiler option 48. Mapping of deprecated options to new options . . . . . . . . . . . . . 49. Severity levels of compiler messages 50. Using compiler options to get listings 51. Terms used in MAP output . . . . . . 52. Symbols used in LIST and MAP output 53. Compiler options in the INFO BYTE section 54. Signature information bytes . . . . . . 55. Calls between COBOL and assembler under CICS . . . . . . . . . . . . . . 56. Compiler options required for the integrated CICS translator . . . . . . . . . . . 57. Compiler options required for the separate CICS translator . . . . . . . . . . . 58. TRUNC compiler options recommended for the separate CICS translator