Enterprise COBOL for z/OS and OS/390

Programming GuideV ersion 3 Release 2

SC27-1412-01

Enterprise COBOL for z/OS and OS/390

Programming GuideV ersion 3 Release 2

SC27-1412-01

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

Second Edition (September 2002) This edition applies to Version 3 Release 2 of IBM Enterprise COBOL for z/OS and OS/390 (program number 5655-G53) 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 serving your locality. Copyright International Business Machines Corporation 1991, 2002. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

ContentsAbout this document . . . . . . . . xiiiHow this document will help you . . . . . . xiii Abbreviated terms . . . . . . . . . . . . xiii Comparison of commonly used terms . . . . . xiv How to read syntax diagrams . . . . . . . . xiv How examples are shown . . . . . . . . . xv Summary of changes . . . . . . . . . . . xvi Version 3 Release 2 (September 2002) . . . . xvi Version 3 Release 1 (November 2001) . . . . xvii How to send your comments . . . . . . . . xviii Using WITH NO ADVANCING . . . Using intrinsic functions (built-in functions) Types of intrinsic functions . . . . . Nesting functions . . . . . . . . Using tables (arrays) and pointers . . . . Storage and its addressability . . . . . Settings for RMODE . . . . . . . . Storage restrictions for passing data . . Location of data areas . . . . . . Storage for external data . . . . . . Storage for QSAM input-output buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 32 32 33 33 33 34 34 35 35 35

Part 1. Coding your program . . . . 1Chapter 1. Structuring your program . . 5Identifying 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 . 6 . 6 . 6 . 7 . 7 . 8 . 8 . 9 . 10 . 10 . 12 . 12 . 14 . 16 . 17 . 18 . 21

Chapter 3. Working with numbers and arithmetic . . . . . . . . . . . . . 37Defining numeric data. . . . . . . . . . Displaying numeric data . . . . . . . . . Controlling how numeric data is stored . . . . Formats for numeric data. . . . . . . . . External decimal (DISPLAY) items . . . . . External floating-point (DISPLAY) items . . . Binary (COMP) items . . . . . . . . . Native binary (COMP-5) items . . . . . . Packed-decimal (COMP-3) items . . . . . Floating-point (COMP-1 and COMP-2) items . Examples: numeric data and internal representation . . . . . . . . . . . Data format conversions . . . . . . . . . Conversions and precision . . . . . . . Sign representation and processing . . . . . NUMPROC(PFD) . . . . . . . . . . NUMPROC(NOPFD) . . . . . . . . . NUMPROC(MIG) . . . . . . . . . . Checking for incompatible data (numeric class test) Performing arithmetic . . . . . . . . . . COMPUTE and other arithmetic statements . Arithmetic expressions . . . . . . . . Numeric intrinsic functions . . . . . . . Math and date Language Environment services Examples: numeric intrinsic functions . . . Fixed-point versus floating-point arithmetic . . Floating-point evaluations . . . . . . . Fixed-point evaluations . . . . . . . . Arithmetic comparisons (relation conditions) . Examples: fixed-point and floating-point evaluations . . . . . . . . . . . . Using currency signs . . . . . . . . . . Example: multiple currency signs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 38 39 40 40 40 41 41 42 42 42 43 44 45 45 45 45 46 47 47 47 48 49 51 53 53 54 54

Chapter 2. Using data . . . . . . . . 23Using variables, structures, literals, and constants . Variables . . . . . . . . . . . . . . Data structure: data items and group items . . . Literals . . . . . . . . . . . . . . . Constants . . . . . . . . . . . . . . Figurative constants . . . . . . . . . . Assigning values to data items . . . . . . . . Examples: initializing variables . . . . . . . Initializing a structure (INITIALIZE) . . . . . Assigning values to variables or structures (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 . . . . . . . . . . . . . . . Copyright IBM Corp. 1991, 2002

23 23 23 24 24 24 25 25 27 27 28 29 30 30

. 55 . 55 . 56

Chapter 4. Handling tables . . . . . . 59Defining a table (OCCURS) . Nesting tables . . . . . Subscripting . . . . . Indexing . . . . . . Referring to an item in a table Subscripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 60 60 61 61 62

iii

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 . . Searching a table . . . . . . . . . . . Doing a serial search (SEARCH) . . . . . Doing a binary search (SEARCH ALL) . . . Processing table items using intrinsic functions . Example: intrinsic functions . . . . . . .

. . . .

63 64 64 64

. 65 . 66 . 67 68 . 69 . 70 . 71 . 71 . 72 . 73 . 73

Chapter 5. Selecting and repeating program actions . . . . . . . . . . 75Selecting program actions . . . . . . Coding a choice of actions . . . . . Coding conditional expressions . . . . Repeating program actions . . . . . . Choosing inline or out-of-line PERFORM Coding a loop . . . . . . . . . Coding a loop through a table . . . . Executing multiple paragraphs or sections . . . . . . . . . . . . . . . . . . . . . . . . 75 75 79 82 83 84 85 85

National data items . . . . . . . . . National literals . . . . . . . . . . National characters as figurative constants . Storage of national data . . . . . . . . Converting national data . . . . . . . . Converting alphanumeric and integer to national data (MOVE) . . . . . . . . Converting alphanumeric to national data (NATIONAL-OF) . . . . . . . . . . Converting national to alphanumeric data (DISPLAY-OF) . . . . . . . . . . . Conversion exceptions . . . . . . . . Example: converting national data . . . . Processing UTF-8 data . . . . . . . . . Processing Chinese GB 18030 data . . . . . Comparing national data items . . . . . . Comparing national operands . . . . . . Comparing national and numeric operands . Comparing national and alphabetic or alphanumeric operands . . . . . . . . Comparing national and group operands . . Processing alphanumeric data items that contain DBCS data . . . . . . . . . . . . .

. . . . .

105 106 106 106 107

. 107 . 107 . . . . . . . . 108 108 108 109 110 110 111 111

. 111 . 111 . 111

Chapter 8. Processing files . . . . . 113File organization and input-output devices Choosing file organization and access mode Format for coding input and output . . Allocating files . . . . . . . . . . Checking for input or output errors . . . . . . . . . . . . . . . . . . 113 115 116 117 118

Chapter 6. Handling strings . . . . . . 87Joining data items (STRING) . . . . . . . . 87 Example: STRING statement. . . . . . . . 87 Splitting data items (UNSTRING) . . . . . . . 89 Example: UNSTRING statement . . . . . . 89 Manipulating null-terminated strings . . . . . . 91 Example: null-terminated strings . . . . . . 92 Referring to substrings of data items . . . . . . 92 Reference modifiers. . . . . . . . . . . 93 Example: arithmetic expressions as reference modifiers . . . . . . . . . . . . . . 94 Example: intrinsic functions as reference modifiers . . . . . . . . . . . . . . 95 Tallying and replacing data items (INSPECT) . . . 95 Examples: INSPECT statement . . . . . . . 95 Converting data items (intrinsic functions) . . . . 96 Converting to uppercase or lowercase (UPPER-CASE, LOWER-CASE) . . . . . . . 97 Converting to reverse order (REVERSE) . . . . 97 Converting to numbers (NUMVAL, NUMVAL-C) 97 Converting from one code page to another . . . 98 Evaluating data items (intrinsic functions) . . . . 99 Evaluating single characters for collating sequence . . . . . . . . . . . . . . 99 Finding the largest or smallest data item . . . 99 Finding the length of data items . . . . . . 101 Finding the date of compilation . . . . . . 101

Chapter 9. Processing QSAM files . . 119Defining 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 with CBLQDA . . . . . . . . . . . . . . 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 file attributes match your program Using striped extended-format QSAM data sets Accessing HFS files using QSAM . . . . . . . Labels for QSAM files . . . . . . . . . . Using trailer and header labels . . . . . . Format of standard labels . . . . . . . . Processing QSAM ASCII files on tape . . . . . Requesting the ASCII alphabet . . . . . . Defining the record formats . . . . . . . Defining the ddname . . . . . . . . . . Processing ASCII file labels . . . . . . . . . 119 120 127 129 130 130 131 131 131 132 133 133 134 136 137 139 140 141 141 143 143 144 144 144 145

Chapter 7. Coding for run-time use of national languages . . . . . . . . . 103Unicode and encoding of language characters Using national data (Unicode) in COBOL . . . . . 105 . 105

iv

Programming Guide

Chapter 10. Processing VSAM files

147148 149 150 150 151 153 154 155 157 157 159 160 161 162 162 162 163 164 164 165 165 166 168 170 171

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 UNIX . . . . . . . . . . . . . . . . Defining VSAM files . . . . . . . . . . Creating alternate indexes . . . . . . . . Allocating VSAM files . . . . . . . . . Sharing VSAM files through RLS . . . . . . Improving VSAM performance . . . . . . .

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 . . . . Sorting on windowed date fields . . . . . . 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 . . . . . . . . . Sort special registers . . . . . . . . . . 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 . . . . .

186 186 187 188 188 189 189 190 190 191 191 191 193 193 194 195 195 196 196 197 197

Chapter 13. Processing XML documents . . . . . . . . . . . . 199XML parser in COBOL . . . . . . . Accessing XML documents . . . . . . Parsing XML documents . . . . . . Processing XML events . . . . . . Writing procedures to process XML . . Understanding XML document encoding . Specifying the code page . . . . . Parsing documents in other code pages. Handling errors in XML documents . . . Unhandled exceptions . . . . . . Handling exceptions . . . . . . . Terminating the parse . . . . . . CCSID conflict exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 201 201 202 208 213 214 214 215 216 216 217 217

Chapter 11. Processing line-sequential files . . . . . . . . . . . . . . . 173Defining line-sequential files and records in COBOL . . . . . . . . . . . . . . . Allowable control characters . . . . . . . Describing the structure of a line-sequential file Defining and 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 . . . . . 173 174 174 175 175 176 176 177 177 178

Chapter 14. Handling errors . . . . . 221Requesting dumps . . . . . . . . . . Creating a formatted dump. . . . . . . Creating a system dump . . . . . . . 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) . . Coding ERROR declaratives . . . . . . Using file status keys . . . . . . . . . Example: file status key . . . . . . . . Using VSAM return codes (VSAM files only) Example: checking VSAM status codes . . . Coding INVALID KEY phrases . . . . . Example: FILE STATUS and INVALID KEY . Handling errors when calling programs . . . . . . . . . . . . . . . . . 221 221 222 222 223 223 223 226 227 228 229 229 230 231 232 233

Chapter 12. Sorting and merging filesSort 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 . . . . . . . Coding considerations when using DFSORT . Example: coding the output procedure when using DFSORT . . . . . . . . . . . Restrictions on input and output procedures . . Defining sort and merge data sets . . . . .

179. 180 . 180 . 181 . . . . . 181 182 183 183 184

. 184 . 185 . 185

Contents

v

Writing routines for handling errors .

.

.

.

.

. 233

Chapter 17. Compiling, linking, and running OO applications . . . . . . 277Compiling, linking, and running OO applications under UNIX . . . . . . . . . . . . . . Compiling OO applications under UNIX . . . Preparing OO applications under UNIX . . . Example: compiling and linking a COBOL class definition under UNIX . . . . . . . . . Running OO applications under UNIX . . . . Compiling, linking, and running OO applications using JCL or TSO/E . . . . . . . . . . . Compiling OO applications using JCL or TSO/E Preparing and running OO applications using JCL or TSO/E . . . . . . . . . . . . Example: compiling, linking, and running an OO application using JCL . . . . . . . . 277 277 278 279 279 281 281 282 283

Part 2. Compiling and debugging your program . . . . . . . . . . 235Chapter 15. Compiling under z/OS 237237 238 248 249 250 250 251 252 253 255 255 256 256 256 257 257 257 258 258 259 259 259 261 261 262 263 264 265 265 266 266 267 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) . . . Specifying source libraries (SYSLIB) . . . . . Defining the output data set (SYSPRINT) . . . Directing compiler messages to your terminal (SYSTERM) . . . . . . . . . . . . . Creating object code (SYSLIN or SYSPUNCH) Creating an associated data file (SYSADATA) Defining the output Java data set (SYSJAVA) Defining the debug data set (SYSDEBUG) . . . Specifying compiler options under z/OS . . . . Specifying compiler options with 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 error messages . . Messages and listings for compiler-detected errors . . . . . . . . . . . . . . . Format of compiler error messages . . . . . Severity codes for compiler error messages . .

Chapter 18. Compiler options . . . . 287Option settings for COBOL 85 Standard conformance. . . . . . . . . . Conflicting compiler options . . . . ADATA . . . . . . . . . . . ADV . . . . . . . . . . . . ARITH . . . . . . . . . . . AWO . . . . . . . . . . . . BUFSIZE . . . . . . . . . . . CICS . . . . . . . . . . . . CODEPAGE . . . . . . . . . . COMPILE . . . . . . . . . . CURRENCY . . . . . . . . . . DATA . . . . . . . . . . . . DATEPROC . . . . . . . . . . DBCS . . . . . . . . . . . . DECK . . . . . . . . . . . . DIAGTRUNC . . . . . . . . . DLL . . . . . . . . . . . . DUMP . . . . . . . . . . . DYNAM . . . . . . . . . . . EXIT . . . . . . . . . . . . EXPORTALL . . . . . . . . . FASTSRT . . . . . . . . . . . FLAG . . . . . . . . . . . . FLAGSTD . . . . . . . . . . INTDATE . . . . . . . . . . LANGUAGE . . . . . . . . . LIB . . . . . . . . . . . . . LINECOUNT . . . . . . . . . LIST . . . . . . . . . . . . MAP . . . . . . . . . . . . NAME . . . . . . . . . . . NSYMBOL . . . . . . . . . . NUMBER . . . . . . . . . . NUMPROC . . . . . . . . . . OBJECT . . . . . . . . . . . OFFSET . . . . . . . . . . . OPTIMIZE . . . . . . . . . . Unused data items . . . . . . OUTDD . . . . . . . . . . . PGMNAME . . . . . . . . . . PGMNAME(COMPAT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 289 290 291 291 292 292 293 294 294 295 296 297 298 298 298 299 300 301 301 301 302 302 303 304 305 306 306 306 307 308 309 309 310 311 312 312 312 313 314 314

Chapter 16. Compiling under UNIXSetting environment variables under UNIX . . Specifying compiler options under UNIX . . . Compiling and linking with the cob2 command Defining input and output . . . . . . . Creating a DLL . . . . . . . . . . . Example: using cob2 to compile under UNIX cob2 . . . . . . . . . . . . . . cob2 input and output files . . . . . . . Compiling using scripts . . . . . . . . .

269. 269 . 270 271 . 271 . 272 272 . 273 . 274 . 275

vi

Programming Guide

PGMNAME(LONGUPPER). PGMNAME(LONGMIXED) QUOTE/APOST . . . . . RENT . . . . . . . . . RMODE . . . . . . . . SEQUENCE . . . . . . . SIZE . . . . . . . . . SOURCE . . . . . . . . SPACE . . . . . . . . SQL . . . . . . . . . SSRANGE . . . . . . . TERMINAL . . . . . . . TEST . . . . . . . . . THREAD . . . . . . . . TRUNC . . . . . . . . TRUNC example 1 . . . TRUNC example 2 . . . VBREF . . . . . . . . WORD . . . . . . . . XREF . . . . . . . . . YEARWINDOW . . . . . ZWB . . . . . . . . . Compiler-directing statements .

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

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

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

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

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

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

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

314 315 316 316 317 318 318 319 319 320 321 321 322 325 326 327 328 329 329 330 331 331 332

Chapter 20. Developing COBOL programs for CICS . . . . . . . . . 375Coding COBOL programs to run under CICS Coding file input and output . . . . . Retrieving the system date and time. . . Displaying the contents of data items . . Calling to or from COBOL programs . . Coding nested programs . . . . . . Coding a COBOL program to run above the 16-MB line . . . . . . . . . . . Determining the success of ECI calls. . . Compiling with the CICS option . . . . . Compiling a sequence of programs . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 376 376 377 377 377 378 378 378 379 379 380 381 382 383

. 383

Chapter 21. Programming for a DB2 environment . . . . . . . . . . . . 385Coding SQL statements . . . . . . . . . . Using SQL INCLUDE with the DB2 coprocessor Using character data . . . . . . . . . . Using binary items . . . . . . . . . . Determining the success of SQL statements . . Compiling with the SQL option . . . . . . . Compiling in batch . . . . . . . . . . Separating DB2 suboptions . . . . . . . . DB2 coprocessor . . . . . . . . . . . 385 385 385 386 387 387 388 388 388

Chapter 19. Debugging . . . . . . . 337Debugging with source language . . . . . Tracing program logic . . . . . . . Finding and handling input-output errors . Validating data . . . . . . . . . . Finding uninitialized data . . . . . . 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 Finding program entity definitions and references . . . . . . . . . . . Listing data items . . . . . . . . . Getting listings . . . . . . . . . . . Example: short listing . . . . . . . Example: SOURCE and NUMBER output . Example: embedded map summary . . . Terms used in MAP output. . . . . . Symbols used in LIST and MAP output . Example: nested program map . . . . Reading LIST output . . . . . . . . Example: XREF output - data-name cross-references. . . . . . . . . . Example: XREF output - program-name cross-references. . . . . . . . . . Example: embedded cross-reference . . . Example: OFFSET compiler output . . . Example: VBREF compiler output . . . Preparing to use the debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 338 339 339 339 340 341 342 343 343 344 345 346 347 348 351 353 354 354 356 356

Chapter 22. Developing COBOL programs for IMS. . . . . . . . . . 391Compiling and linking COBOL programs for running under IMS . . . . . . . . . . . Using object-oriented COBOL and Java under IMS Calling a COBOL method from an IMS Java application . . . . . . . . . . . . . Building a mixed COBOL and Java application that starts with COBOL . . . . . . . . . Writing mixed-language applications . . . . 391 392 392 393 394

Chapter 23. Running COBOL programs under UNIX . . . . . . . . 397Running in UNIX environments . . . . . . Setting and accessing environment variables . . Setting environment variables that affect execution . . . . . . . . . . . . . Resetting environment variables . . . . . Accessing environment variables . . . . . Example: accessing environment variables . . Calling UNIX/POSIX APIs . . . . . . . . fork(), exec(), and spawn() . . . . . . . Samples . . . . . . . . . . . . . Accessing main program parameters . . . . Example: accessing main program parameters . 397 . 398 . . . . . . . . 398 399 399 400 400 400 401 402 402

. 368 . . . . . 369 369 370 371 371

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

Contents

vii

Part 4. Structuring complex applications . . . . . . . . . . . 405Chapter 24. Using subprograms . . . 407Main programs, subprograms, and calls . . . . Ending and reentering main programs or subprograms . . . . . . . . . . . . . Transferring control to another program . . . . Making static calls. . . . . . . . . . . Making dynamic calls . . . . . . . . . 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 a C function pointer . . . . . . . Calling to alternate entry points . . . . . . Making programs reentrant . . . . . . . . 408 408 410 410 411 413 414 414 416 419 419 420 421 421 421 422

Using DLLs in OO COBOL applications

.

.

.

. 446

Chapter 27. Preparing COBOL programs for multithreading . . . . . 449Multithreading . . . . . . . . . . . . Choosing THREAD to support multithreading . Transferring control with multithreading . . . Using cancel with threaded programs . . . Ending a program . . . . . . . . . . Preinitializing the COBOL environment . . Processing files with multithreading . . . . . File definition storage . . . . . . . . Recommended usage for file access . . . . Example: usage patterns of file input and output with multithreading. . . . . . . Handling COBOL limitations with multithreading . . . . . . . . . 449 451 451 451 451 452 452 452 453

. 453 454

Part 5. Developing object-oriented programs . . . . . . . . . . . . 457Chapter 28. Writing object-oriented programs . . . . . . . . . . . . . 459Example: 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 . . . . . . . . . . . . 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 . . . . . . . . . 460 461 462 464 464 466 467 467 468 469 469 470 471 472 473 474 475 477 478 479 480 482 483 484 484 485 486 486 487 487 488

Chapter 25. Sharing data . . . . . . 423Passing data . . . . . . . . . . . . . Describing arguments in the calling program Describing parameters in the called program 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 . . . . . . Understanding 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 . . . . . . . 423 424 425 . 425 . 425 . . . . . . . . . . . . 426 426 426 427 430 430 431 431 431 432 432

Chapter 26. Creating a DLL or a DLL application . . . . . . . . . . . . 437Dynamic link libraries (DLLs) . . . . . . . . Compiling programs to create DLLs . . . . . . Linking DLLs . . . . . . . . . . . . . Example: sample JCL for a procedural DLL application . . . . . . . . . . . . . . Prelinking certain DLLs . . . . . . . . . . Using CALL identifier with DLLs . . . . . . Search order for DLLs in HFS . . . . . . . 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 . . . 437 438 439 440 441 441 442 442 443 444 444 446

viii

Programming Guide

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 you can run using the java command . . . . . . . .

489 489 492 497 498 498

Chapter 29. Communicating with Java methods . . . . . . . . . . . . . 501Accessing 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) . . . . . . 501 502 504 505 505 506 506 507 510 512 512 515

Manipulating literals as dates . . . . . . . . Assumed century window . . . . . . . . Treatment of nondates . . . . . . . . . Setting triggers and limits . . . . . . . . . Example: using limits . . . . . . . . . Using sign conditions . . . . . . . . . Sorting and merging by date . . . . . . . . Example: sorting by date and time . . . . . Performing arithmetic on date fields. . . . . . Allowing for overflow from windowed date fields . . . . . . . . . . . . . . . Specifying the order of evaluation . . . . . Controlling date processing explicitly . . . . . Using DATEVAL . . . . . . . . . . . Using UNDATE . . . . . . . . . . . Example: DATEVAL . . . . . . . . . . Example: UNDATE . . . . . . . . . . Analyzing and avoiding date-related diagnostic messages . . . . . . . . . . . . . . . Avoiding problems in processing dates . . . . . Avoiding problems with packed-decimal fields Moving from expanded to windowed date fields

537 538 539 539 540 541 541 542 543 543 544 545 545 545 546 546 546 548 548 548

Part 7. Improving performance and productivity . . . . . . . . . . . 551Chapter 32. Tuning your program . . . 553Using an optimal programming style . . . Using structured programming . . . . Factoring expressions. . . . . . . . Using symbolic constants . . . . . . Grouping constant computations . . . . Grouping duplicate computations . . . Choosing efficient data types . . . . . . Computational data items . . . . . . Consistent data types. . . . . . . . Arithmetic expressions . . . . . . . Exponentiations . . . . . . . . . Handling tables efficiently . . . . . . . Optimization of table references . . . . Optimizing your code . . . . . . . . Optimization . . . . . . . . . . Example: PERFORM procedure integration Choosing compiler features to enhance performance . . . . . . . . . . . . Performance-related compiler options . . Evaluating performance . . . . . . . Running efficiently with CICS, IMS, or VSAM CICS . . . . . . . . . . . . . IMS . . . . . . . . . . . . . VSAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 554 554 554 554 555 555 555 556 556 556 557 558 560 560 562 562 563 566 566 566 567 567

Part 6. Specialized processing . . 517Chapter 30. Interrupts and checkpoint/restart . . . . . . . . . 519Setting 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 . . . . . . . . . . . . . . . 519 520 520 521 522 522 523 523 524 525 525 525 525 526

Chapter 31. Processing two-digit-year dates . . . . . . . . . . . . . . . 527Millennium language extensions (MLE) . . . . Principles and objectives of these extensions . . Resolving date-related logic problems . . . . . Using a century window . . . . . . . . Using internal bridging . . . . . . . . . Moving to full field expansion. . . . . . . Using year-first, year-only, and year-last date fields Compatible dates . . . . . . . . . . . Example: comparing year-first date fields . . . Using other date formats . . . . . . . . Example: isolating the year . . . . . . . . 528 528 529 530 531 532 534 535 536 536 536

Chapter 33. Simplifying coding . . . . 569Eliminating repetitive coding . . . . . . . Example: using the COPY statement. . . . Using Language Environment callable services . Sample list of Language Environment callable services . . . . . . . . . . . . . Calling Language Environment services . . . 569 . 570 . 571 . 572 . 573

Contents

ix

Example: Language Environment callable services . . . . . . . . . . . .

.

. 573

Part 8. Appendixes . . . . . . . . 575Appendix A. Intermediate results and arithmetic precision . . . . . . . . 577Terminology 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 578 579 579 579 580 581 582 582 583 583 583 584 585 585 586

Calling from exit modules . . . . . . . Processing of INEXIT. . . . . . . . . Parameter list for INEXIT . . . . . . Processing of LIBEXIT . . . . . . . . Processing of LIBEXIT with nested COPY statements . . . . . . . . . . . Parameter list for LIBEXIT . . . . . . Processing of PRTEXIT . . . . . . . . Parameter list for PRTEXIT . . . . . . Processing of ADEXIT . . . . . . . . Parameter list for ADEXIT . . . . . . Error handling for exit modules . . . . . Using the EXIT compiler option with CICS and SQL statements . . . . . . . . . . . INEXIT . . . . . . . . . . . . LIBEXIT . . . . . . . . . . . . PRTEXIT . . . . . . . . . . . . ADEXIT . . . . . . . . . . . . Example: INEXIT user exit . . . . . . .

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

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

613 613 613 614 615 616 617 617 618 619 619 620 620 620 620 621 621

Appendix F. JNI.cpy

. . . . . . . . 625

Appendix G. COBOL SYSADATA file contents . . . . . . . . . . . . . 631Existing compiler options affecting the SYSADATA file . . . . . . . . . . . . . . . . . Record types . . . . . . . . . . . . . Example: SYSADATA . . . . . . . . . . SYSADATA record descriptions . . . . . . . Common header section . . . . . . . . . . Job identification record - X0000. . . . . . . ADATA identification record - X0001 . . . . . Compilation unit start/end record - X0002 . . . Options record - X0010 . . . . . . . . . . External symbol record - X0020 . . . . . . . Parse tree record - X0024 . . . . . . . . . Token record - X0030 . . . . . . . . . . Source error record - X0032 . . . . . . . . Source record - X0038 . . . . . . . . . . COPY REPLACING record - X0039. . . . . . Symbol record - X0042 . . . . . . . . . . Symbol cross-reference record - X0044 . . . . . Nested program record - X0046 . . . . . . . Library record - X0060 . . . . . . . . . . Statistics record - X0090 . . . . . . . . . EVENTS record - X0120 . . . . . . . . . 631 632 633 634 635 636 637 637 638 647 648 661 662 662 663 664 675 676 677 678 678

Appendix B. Complex OCCURS DEPENDING ON . . . . . . . . . . 587Example: complex ODO . . . . . . . . . How length is calculated . . . . . . . Setting values of ODO objects . . . . . . Effects of change in ODO object value . . . . Preventing index errors when changing ODO object value . . . . . . . . . . . . Preventing overlay when adding elements to a variable table . . . . . . . . . . . . . . . 587 588 588 588

. 589 . 589

Appendix C. Converting double-byte character set (DBCS) data . . . . . . 593DBCS 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 . . . . . . . . . . 593 593 593 594 595 595 595 596 597

Appendix H. Sample programs . . . . 679IGYTCARA: 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 . . Preparing to run IGYTSALE . . . Language elements and concepts that are illustrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 680 681 682 683 684 686 687 689 693

Appendix D. XML reference materialXML exceptions that allow continuation . . . XML exceptions that do not allow continuation . XML conformance . . . . . . . . . . .

599. 599 . 603 . 606

Appendix E. EXIT compiler option . . 611Using the user-exit work area . . . . . . . . 612

. 694

x

Programming Guide

Notices . . . . . . . . . . . . . . 699Trademarks . . . . . . . . . . . . . . 700

Enterprise COBOL for z/OS and OS/390 . Related publications . . . . . . . .

. .

. .

. 725 . 725

Glossary . . . . . . . . . . . . . 701 List of resources . . . . . . . . . . 725

Index . . . . . . . . . . . . . . . 727

Contents

xi

xii

Programming Guide

About this documentWelcome to IBM Enterprise COBOL for z/OS and OS/390, IBMs latest host COBOL compiler! This version of IBM COBOL adds new COBOL function to help integrate COBOL business processes and Web-oriented business processes by: v Simplifying the componentization of COBOL programs and enabling interoperability with Java components v Promoting the exchange and usage of data in standardized formats, including XML and Unicode

How this document will help youThis document 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 document 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 on COBOL syntax, see IBM Enterprise COBOL Language Reference. For information on migrating programs to Enterprise COBOL, see IBM Enterprise COBOL Compiler and Run-Time Migration Guide. IBM z/OS Language Environment provides the run-time environment and run-time services that are required to run your Enterprise COBOL programs. You will find information on 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 IBM z/OS Language Environment terms, see Comparison of commonly used terms on page xiv.

Abbreviated termsCertain terms are used in a shortened form in this document. Abbreviations for the product names used most frequently are listed alphabetically in the following table:Term used CICS Enterprise COBOL Language Environment MVS UNIX Long form CICS Transaction Server IBM Enterprise COBOL for z/OS and OS/390 IBM z/OS Language Environment MVS/ESA z/OS UNIX System Services

Copyright IBM Corp. 1991, 2002

xiii

OS/390 Version 2 Release 10 and z/OS Version 1 Release 1 and later are referred to collectively as z/OS throughout this document. The e-server zSeries 900 and the S/390 hardware are referred to collectively as z/900. In addition to these abbreviated terms, the term COBOL 85 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 - COBOL - 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 at the back of this document.

Comparison of commonly used termsTo better understand the terms used throughout the IBM z/OS Language Environment and IBM Enterprise COBOL for z/OS and OS/390 publications and what terms are meant to be equivalent, see the following table:Language Environment term Aggregate Array Array element Enclave External data Local data Pass parameters directly, by value Pass parameters indirectly, by reference Enterprise COBOL equivalent Group item A table created using the OCCURS clause Table element Run unit WORKING-STORAGE data defined with EXTERNAL clause Any non-EXTERNAL data item BY VALUE BY REFERENCE

Pass parameters indirectly, by value BY CONTENT Routine Scalar Program Elementary item

How to read syntax diagramsThe following rules apply to syntax diagrams: v Read the syntax diagrams from left to right, from top to bottom, following the path of the line. symbol indicates the beginning of a statement. The

xiv

Programming Guide

The symbol indicates that the statement syntax is continued on the next line. symbol indicates that a statement is continued from the previous line. The symbol indicates the end of a statement. The 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): v Optional items appear below the main path:

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:

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

If one of the items is the default, it appears above the main path and the remaining choices are shown below:

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

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

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 shownThis document shows numerous examples of sample COBOL statements, program fragments, and small programs to illustrate the coding techniques being discussed. 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.

About this document

xv

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.

Summary of changesThis section lists the key changes that have been made to Enterprise COBOL for z/OS and OS/390. The changes that are discussed in this document have an associated page reference for your convenience. The latest technical changes are marked by a revision bar in the left margin.

Version 3 Release 2 (September 2002)| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | v The compiler has been enhanced to support new features of Debug Tool, and features of Debug Tool Utilities and Advanced Functions: Playback support lets you record and replay application execution paths and data values. Automonitor support displays the values of variables that are referenced in the current statement during debugging. Programs that have been compiled with the OPTIMIZE and TEST(NONE,SYM,. . .) options are supported for debugging (TEST on page 322). The Debug Tool GOTO command is enabled for programs that have been compiled with the NOOPTIMIZE option and the TEST option with any of its suboptions (TEST on page 322). (In earlier releases, the GOTO command was not supported for programs compiled with TEST(NONE,. . .).) For further details about these enhancements to debugging support, see Debug Tool Users Guide. v Extending Java interoperability to IMS: Object-oriented COBOL programs can run in an IMS Java dependent region. The object-oriented COBOL and Java languages can be mixed in a single application (Using object-oriented COBOL and Java under IMS on page 392). v Enhanced support for Java interoperability: The OPTIMIZE compiler option is fully supported for programs that contain OO syntax for Java interoperability. Object references of type jobjectArray are supported for interoperation between COBOL and Java (Declaring arrays and strings for Java on page 506). OO applications that begin with a COBOL main factory method can be invoked with the java command (Structuring OO applications on page 498). A new environment variable, COBJVMINITOPTIONS, is provided, enabling the user to specify options that will be used when COBOL initializes a Java virtual machine (JVM) (Running OO applications under UNIX on page 279). OO applications that begin with a COBOL program can, with some limitations, be bound as modules in a PDSE and run using batch JCL (Preparing and running OO applications using JCL or TSO/E on page 282). v Unicode enhancement for working with DB2: The code pages for host variables are handled implicitly when you use the DB2 integrated coprocessor. SQL DECLARE statements are necessary only for variables described with USAGE DISPLAY or USAGE DISPLAY-1 when COBOL and DB2 code pages do not match (Coding SQL statements on page 385).

xvi

Programming Guide

Version 3 Release 1 (November 2001)v Interoperation of COBOL and Java by means of object-oriented syntax, permitting COBOL programs to instantiate Java classes, invoke methods on Java objects, and define Java classes that can be instantiated in Java or COBOL and whose methods can be invoked in Java or COBOL (Chapter 28, Writing object-oriented programs on page 459) v Ability to call services provided by the Java Native Interface (JNI) to obtain additional Java capabilities, with a copybook JNI.cpy and special register JNIEnvPtr to facilitate access (Accessing JNI services on page 501) v XML support, including a high-speed XML parser that allows programs to consume inbound XML messages, verify that they are well formed, and transform their contents into COBOL data structures; with support for XML documents encoded in Unicode UTF-16 or several single-byte EBCDIC or ASCII code pages (Chapter 13, Processing XML documents on page 199) v Support for compilation of programs that contain CICS statements, without the need for a separate translation step (Integrated CICS translator on page 380) Compiler option CICS, enabling integrated CICS translation and specification of CICS options (CICS on page 293) v Support for Unicode provided by NATIONAL data type and national (N, NX) literals, intrinsic functions DISPLAY-OF and NATIONAL-OF for character conversions, and compiler options NSYMBOL and CODEPAGE (Chapter 7, Coding for run-time use of national languages on page 103) Compiler option CODEPAGE to specify the code page used for encoding national literals, and alphanumeric and DBCS data items and literals (CODEPAGE on page 294) Compiler option NSYMBOL to control whether national or DBCS processing should be in effect for literals and data items that use the N symbol (NSYMBOL on page 309) v Multithreading support: support of POSIX threads and asynchronous signals, permitting applications with COBOL programs to run on multiple threads within a process (Chapter 27, Preparing COBOL programs for multithreading on page 449) Compiler option THREAD, enabling programs to run in Language Environment enclaves with multiple POSIX threads or PL/I subtasks (THREAD on page 325) v VALUE clauses for BINARY data items that permit numeric literals to have a value of magnitude up to the capacity of the native binary representation, rather than being limited to the value implied by the number of 9s in the PICTURE clause (Formats for numeric data on page 40) v A 4-byte FUNCTION-POINTER data item that can contain the address of a COBOL or non-COBOL entry point, providing easier interoperability with C function pointers (Using procedure and function pointers on page 420) v The following support is no longer provided (as documented in Enterprise COBOL Compiler and Run-Time Migration Guide): SOM-based object-oriented syntax and services Compiler options CMPR2, ANALYZE, FLAGMIG, TYPECHK, and IDLGEN v Changed default values for the following compiler options: DBCS (DBCS on page 298), FLAG(I,I) (FLAG on page 302), RENT (RENT on page 316), and XREF(FULL) (XREF on page 330) For a history of changes to previous COBOL compilers, see Enterprise COBOL Compiler and Run-Time Migration Guide.About this document

xvii

How to send your commentsYour feedback is important in helping us to provide accurate, high-quality information. If you have comments about this document or any other Enterprise COBOL documentation, contact us in one of these ways: v Fill out the Readers Comment Form at the back of this document, and return it by mail or give it to an IBM representative. If the form has been removed, address your comments to: IBM Corporation H150/090 555 Bailey Avenue San Jose, CA 95141-1003 USA v Fax your comments to this U.S. number: (800)426-7773. v Use the Online Readers Comment Form at www.ibm.com/software/ad/rcf/. Be sure to include the name of the document, the publication number of the document, the version of Enterprise COBOL, and, if applicable, the specific location (for example, page number) 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 it believes appropriate without incurring any obligation to you.

xviii

Programming Guide

Part 1. Coding your programChapter 1. Structuring your program . . . . . 5 Identifying a program . . . . . . . . . . . 5 Identifying a program as recursive . . . . . . 6 Marking a program as callable by containing programs . . . . . . . . . . . . . . 6 Setting a program to an initial state. . . . . . 6 Changing the header of a source listing . . . . 7 Describing the computing environment . . . . . 7 Example: FILE-CONTROL entries . . . . . . 8 Specifying the collating sequence . . . . . . 8 Example: specifying the collating sequence . . 9 Defining symbolic characters . . . . . . . . 9 Defining a user-defined class . . . . . . . 10 Defining files to the operating system . . . . 10 Varying the input or output file at run time . 11 Optimizing buffer and device space . . . . 12 Describing the data . . . . . . . . . . . . 12 Using data in input and output operations . . . 12 FILE SECTION entries. . . . . . . . . 13 Comparison of WORKING-STORAGE and LOCAL-STORAGE . . . . . . . . . . . 14 Example: storage sections. . . . . . . . 15 Using data from another program . . . . . . 16 Sharing data in separately compiled programs 16 Sharing data in nested programs . . . . . 16 Sharing data in recursive or multithreaded programs . . . . . . . . . . . . . 17 Processing the data . . . . . . . . . . . . 17 How logic is divided in the PROCEDURE DIVISION . . . . . . . . . . . . . . 18 Imperative statements . . . . . . . . . 19 Conditional statements . . . . . . . . 19 Compiler-directing statements . . . . . . 20 Scope terminators . . . . . . . . . . 20 Declaratives . . . . . . . . . . . . . 21 Chapter 2. Using data . . . . . . . . . . Using variables, structures, literals, and constants . Variables . . . . . . . . . . . . . . Data structure: data items and group items . . . Literals . . . . . . . . . . . . . . . Constants . . . . . . . . . . . . . . Figurative constants . . . . . . . . . . Assigning values to data items . . . . . . . . Examples: initializing variables . . . . . . . Initializing a structure (INITIALIZE) . . . . . Assigning values to variables or structures (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) . . . Copyright IBM Corp. 1991, 2002

Types of intrinsic functions . . . . Nesting functions . . . . . . . Using tables (arrays) and pointers . . . Storage and its addressability . . . . Settings for RMODE . . . . . . . Storage restrictions for passing data . Location of data areas . . . . . Storage for external data . . . . . Storage for QSAM input-output buffers

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

32 33 33 33 34 34 35 35 35 37 37 38 39 40 40 40 41 41 42 42 42 43 44 44 44 45 45 45 45 46 47 47 47 48 49 49 49 49 50 51 51 52 52 53 53 53 53 54 54 55 55 56

23 23 23 23 24 24 24 25 25 27 27 28 29 30 30 31 32

Chapter 3. Working with numbers and arithmetic Defining numeric data. . . . . . . . . . . Displaying numeric data . . . . . . . . . . Controlling how numeric data is stored . . . . . Formats for numeric data. . . . . . . . . . External decimal (DISPLAY) items . . . . . . External floating-point (DISPLAY) items . . . . Binary (COMP) items . . . . . . . . . . Native binary (COMP-5) items . . . . . . . Packed-decimal (COMP-3) items . . . . . . Floating-point (COMP-1 and COMP-2) items . . Examples: numeric data and internal representation . . . . . . . . . . . . Data format conversions . . . . . . . . . . Conversions and precision . . . . . . . . Conversions that preserve precision . . . . Conversions that result in rounding . . . . Sign representation and processing . . . . . . NUMPROC(PFD) . . . . . . . . . . . NUMPROC(NOPFD) . . . . . . . . . . NUMPROC(MIG) . . . . . . . . . . . Checking for incompatible data (numeric class test) Performing arithmetic . . . . . . . . . . . COMPUTE and other arithmetic statements . . Arithmetic expressions . . . . . . . . . Numeric intrinsic functions . . . . . . . . Nesting functions and arithmetic expressions ALL subscripting and special registers . . . Math and date Language Environment services Math-oriented callable services . . . . . . Date callable services . . . . . . . . . Examples: numeric intrinsic functions . . . . General number handling . . . . . . . Date and time . . . . . . . . . . . Finance . . . . . . . . . . . . . . Mathematics . . . . . . . . . . . . Statistics . . . . . . . . . . . . . Fixed-point versus floating-point arithmetic . . . Floating-point evaluations . . . . . . . . Fixed-point evaluations . . . . . . . . . Arithmetic comparisons (relation conditions) . . Examples: fixed-point and floating-point evaluations . . . . . . . . . . . . . Using currency signs . . . . . . . . . . . Example: multiple currency signs . . . . . .

1

Chapter 4. Handling tables. . . . . . . . Defining a table (OCCURS) . . . . . . . . Nesting tables . . . . . . . . . . . . Subscripting . . . . . . . . . . . . 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) . . . . . . . . . . . . . Initializing each table item individually . . Initializing a table at the 01 level . . . . Initializing all occurrences of a table element 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 . . Searching a table . . . . . . . . . . . Doing a serial search (SEARCH) . . . . . Example: serial search . . . . . . . . Doing a binary search (SEARCH ALL) . . . Example: binary search . . . . . . . Processing table items using intrinsic functions . Example: intrinsic functions . . . . . . .

. . . . . . . . . . .

59 59 60 60 61 61 62 63 64 64 64

. 65 . 65 . 65 65 . 66 . 67 68 . 69 . 70 . 71 . 71 . 71 . 72 . 72 . 73 . 73

Example: arithmetic expressions as reference modifiers . . . . . . . . . . . . . . 94 Example: intrinsic functions as reference modifiers . . . . . . . . . . . . . . 95 Tallying and replacing data items (INSPECT) . . . 95 Examples: INSPECT statement . . . . . . . 95 Converting data items (intrinsic functions) . . . . 96 Converting to uppercase or lowercase (UPPER-CASE, LOWER-CASE) . . . . . . . 97 Converting to reverse order (REVERSE) . . . . 97 Converting to numbers (NUMVAL, NUMVAL-C) 97 Converting from one code page to another . . . 98 Evaluating data items (intrinsic functions) . . . . 99 Evaluating single characters for collating sequence . . . . . . . . . . . . . . 99 Finding the largest or smallest data item . . . 99 MAX and MIN . . . . . . . . . . . 99 ORD-MAX and ORD-MIN . . . . . . . 100 Returning variable-length results with alphanumeric functions . . . . . . . . 100 Finding the length of data items . . . . . . 101 Finding the date of compilation . . . . . . 101 Chapter 7. Coding for run-time use of national languages . . . . . . . . . . . . . Unicode and encoding of language characters . Using national data (Unicode) in COBOL . . . National data items . . . . . . . . . National literals . . . . . . . . . . National characters as figurative constants . Storage of national data . . . . . . . . Converting national data . . . . . . . . Converting alphanumeric and integer to national data (MOVE) . . . . . . . . Converting alphanumeric to national data (NATIONAL-OF) . . . . . . . . . . Converting national to alphanumeric data (DISPLAY-OF) . . . . . . . . . . . Overriding the default code page. . . . Conversion exceptions . . . . . . . . Example: converting national data . . . . Processing UTF-8 data . . . . . . . . . Processing Chinese GB 18030 data . . . . . Comparing national data items . . . . . . Comparing national operands . . . . . . Comparing national and numeric operands . Comparing national and alphabetic or alphanumeric operands . . . . . . . . Comparing national and group operands . . Processing alphanumeric data items that contain DBCS data . . . . . . . . . . . . . Chapter 8. Processing files . . . . . File organization and input-output devices Choosing file organization and access mode Format for coding input and output . . Allocating files . . . . . . . . . . Checking for input or output errors . . .

Chapter 5. Selecting and repeating program actions . . . . . . . . . . . . . . . 75 Selecting program actions . . . . . . . . . 75 Coding a choice of actions . . . . . . . . 75 Using nested IF statements . . . . . . . 76 Using the EVALUATE statement . . . . . 77 Coding conditional expressions . . . . . . . 79 Switches and flags . . . . . . . . . . 80 Defining switches and flags . . . . . . . 80 Example: switches . . . . . . . . . . 80 Example: flags . . . . . . . . . . . 81 Resetting switches and flags . . . . . . . 81 Example: set switch on . . . . . . . . 81 Example: set switch off . . . . . . . . 82 Repeating program actions . . . . . . . . . 82 Choosing inline or out-of-line PERFORM . . . 83 Example: inline PERFORM statement . . . . 83 Coding a loop . . . . . . . . . . . . 84 Coding a loop through a table . . . . . . . 85 Executing multiple paragraphs or sections . . . 85 Chapter 6. Handling strings . . . . . . . . 87 Joining data items (STRING) . . . . . . . . 87 Example: STRING statement. . . . . . . . 87 STRING program results . . . . . . . . 88 Splitting data items (UNSTRING) . . . . . . . 89 Example: UNSTRING statement . . . . . . 89 UNSTRING program results . . . . . . . 90 Manipulating null-terminated strings . . . . . . 91 Example: null-terminated strings . . . . . . 92 Referring to substrings of data items . . . . . . 92 Reference modifiers. . . . . . . . . . . 93

. . . . . . . .

103 105 105 105 106 106 106 107

. 107 . 107 . . . . . . . . . 108 108 108 108 109 110 110 111 111

. 111 . 111 . 111

. . . 113 . . . 113 . . . 115 . . . 116 . . . 117 . . . 118

Chapter 9. Processing QSAM files . . . . . 119 Defining QSAM files and records in COBOL . . . 119

2

Programming Guide

Establishing record formats. . . . . . . . Logical records . . . . . . . . . . . Requesting fixed-length format . . . . . Requesting variable-length format . . . . Requesting spanned format. . . . . . . Requesting undefined format . . . . . . Setting block sizes . . . . . . . . . . . Letting z/OS determine block size . . . . Setting block size explicitly . . . . . . . Taking advantage of LBI. . . . . . . . Block size and the DCB RECFM subparameter . . . . . . . . . . . Coding input and output statements for QSAM files . . . . . . . . . . . . . . . . Opening QSAM files . . . . . . . . . . Dynamically creating QSAM files with CBLQDA . . . . . . . . . . . . . . Adding records to QSAM files. . . . . . . Updating QSAM files . . . . . . . . . Writing QSAM files to a printer or spooled data set . . . . . . . . . . . . . . . . Controlling the page size . . . . . . . Controlling the vertical positioning of records Closing QSAM files . . . . . . . . . . Handling errors in QSAM files . . . . . . . Working with QSAM files . . . . . . . . . Defining and allocating QSAM files . . . . . Parameters for creating QSAM files . . . . Retrieving QSAM files . . . . . . . . . Parameters for retrieving QSAM files . . . Ensuring file attributes match your program Processing existing files . . . . . . . . Defining variable-length (format-V) records Defining format-U records . . . . . . . Defining fixed-length records . . . . . . Processing new files . . . . . . . . . Processing files dynamically created by COBOL . . . . . . . . . . . . . Using striped extended-format QSAM data sets Allocation of buffers for QSAM files. . . . Accessing HFS files using QSAM . . . . . . . Labels for QSAM files . . . . . . . . . . Using trailer and header labels . . . . . . Getting a user-label track . . . . . . . Handling user labels . . . . . . . . . Format of standard labels . . . . . . . . Standard user labels . . . . . . . . . Processing QSAM ASCII files on tape . . . . . Requesting the ASCII alphabet . . . . . . Defining the record formats . . . . . . . Defining the ddname . . . . . . . . . . Processing ASCII file labels . . . . . . . . . Chapter 10. Processing VSAM files . . . . . VSAM files . . . . . . . . . . . . . . Defining VSAM file organization and records . . Specifying sequential organization for VSAM files . . . . . . . . . . . . . . . Specifying indexed organization for VSAM files Alternate keys . . . . . . . . . . . Alternate index . . . . . . . . . . .

120 120 121 122 124 126 127 127 127 128 129 129 130 130 131 131 131 132 132 132 133 133 134 135 136 136 137 137 137 138 138 138 139 139 140 140 141 141 142 142 143 143 143 144 144 144 145 147 148 149 150 150 151 151

Specifying relative organization for VSAM files Fixed-length and variable-length RRDS . . . Simulating variable-length RRDS . . . . . Specifying access modes for VSAM files . . . Example: using dynamic access with VSAM files . . . . . . . . . . . . . . Defining record lengths for VSAM files. . . . Defining fixed-length records . . . . . . Defining variable-length records . . . . . Coding input and output statements for VSAM files . . . . . . . . . . . . . . . . File position indicator . . . . . . . . . Opening a file (ESDS, KSDS, or RRDS) . . . . Opening an empty file . . . . . . . . Statements to load records into a VSAM file Opening a loaded file (a file with records) Reading records from a VSAM file . . . . . Updating records in a VSAM file . . . . . . Adding records to a VSAM file . . . . . . Adding records sequentially . . . . . . Adding records randomly or dynamically 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 UNIX . . . . . . . . . . . . . . . . Defining VSAM files . . . . . . . . . . Creating alternate indexes . . . . . . . . Example: entries for alternate indexes . . . Allocating VSAM files . . . . . . . . . Sharing VSAM files through RLS . . . . . . Preventing update problems with VSAM files in RLS mode . . . . . . . . . . . Restrictions when using RLS . . . . . . Handling errors in VSAM files in RLS mode Improving VSAM performance . . . . . . . Chapter 11. Processing line-sequential files . . Defining line-sequential files and records in COBOL . . . . . . . . . . . . . . . Allowable control characters . . . . . . . Describing the structure of a line-sequential file Defining and allocating line-sequential files . . . Coding input-output statements for line-sequential files . . . . . . . . . . . . . . . . Opening line-sequential files . . . . . . . Reading records from line-sequential files . . . Adding records to line-sequential files . . . . Closing line-sequential files. . . . . . . . Handling errors in line-sequential files . . . . . Chapter 12. Sorting and merging files . . 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 . . . . . . . . . . . . .

151 152 152 153 154 154 154 154 155 157 157 158 159 159 159 160 161 161 162 162 162 162 163 164 164 165 165 166 168 168 170 170 170 171 171 173 173 174 174 175 175 176 176 177 177 178

. . 179 . . 180 . . 180 . . 181 . . 181

Part 1. Coding your program

3

Coding the input procedure . . . . . . . . Describing the output from sorting or merging . . Coding the output procedure . . . . . . . . Coding considerations when using DFSORT . . 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 . . . . Sorting on windowed date fields . . . . . . 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 . . . . . . . . . . . . . QSAM requirements . . . . . . . . . VSAM requirements . . . . . . . . . Checking for sort errors with NOFASTSRT . . . Controlling sort behavior . . . . . . . . . Sort special registers . . . . . . . . . . Changing DFSORT defaults with control statements . . . . . . . . . . . . . Default characteristics of the IGZSRTCD data set . . . . . . . . . . . . . . . Allocating storage for sort or merge operations Allocating space for sort files . . . . . . . Using checkpoint/restart with DFSORT . . . . Sorting under CICS . . . . . . . . . . . CICS SORT application restrictions . . . . .

182 183 183 184 184 185 185 186 186 187 188 188 189 189 190 190 191 191 191 192 193 193 193 194 195 195 195 196 196 197 197

Requesting dumps . . . . . . . . . . Creating a formatted dump. . . . . . . Creating a system dump . . . . . . . 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) . . Coding ERROR declaratives . . . . . . Using file status keys . . . . . . . . . Example: file status key . . . . . . . . Using VSAM return codes (VSAM files only) Example: checking VSAM status codes . . . Coding INVALID KEY phrases . . . . . INVALID KEY and ERROR declaratives . NOT INVALID KEY . . . . . . . . Example: FILE STATUS and INVALID KEY . Handling errors when calling programs . . . Writing routines for handling errors . . . . .

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

221 221 222 222 223 223 223 226 227 228 229 229 230 231 232 232 232 233 233

Chapter 13. Processing XML documents . . . 199 XML parser in COBOL . . . . . . . . . . 199 Accessing XML documents . . . . . . . . . 201 Parsing XML documents . . . . . . . . . 201 Processing XML events . . . . . . . . . 202 Writing procedures to process XML . . . . . 208 Understanding the contents of XML-CODE 208 Using XML-TEXT and XML-NTEXT . . . . 209 Transforming XML text to COBOL data items 210 Restriction on your processing procedure . . 210 Ending your processing procedure . . . . 210 Example: parsing XML . . . . . . . . 211 Understanding XML document encoding . . . . 213 Specifying the code page . . . . . . . . 214 Parsing documents in other code pages. . . . 214 Handling errors in XML documents . . . . . . 215 Unhandled exceptions . . . . . . . . . 216 Handling exceptions . . . . . . . . . . 216 Terminating the parse . . . . . . . . . 217 CCSID conflict exception . . . . . . . . 217 Chapter 14. Handling errors . . . . . . . . 221

4

Programming Guide

Chapter 1. Structuring your programA COBOL program consists of four divisions, each with a specific logical function: v IDENTIFICATION DIVISION v ENVIRONMENT DIVISION v DATA DIVISION v PROCEDURE DIVISION Only the IDENTIFICATION DIVISION is required. To define a COBOL class or method, you need to define some divisions differently than you would for a program.RELATED TASKS

Identifying a program Describing the computing environment on page 7 Describing the data on page 12 Processing the data on page 17 Defining a class on page 462 Defining a class instance method on page 467 Structuring OO applications on page 498

Identifying a programUse the IDENTIFICATION DIVISION to name your program and, if you want, give other identifying information. You can use the optional AUTHOR, INSTALLATION, DATE-WRITTEN, and DATE-COMPILED paragraphs for descriptive information about your program. The data you enter on the DATE-COMPILED paragraph is replaced with the latest compilation date.IDENTIFICATION DIVISION. Program-ID. Helloprog. Author. A. Programmer. Installation. Computing Laboratories. Date-Written. 08/21/2002. Date-Compiled. 08/21/2002.

Use the PROGRAM-ID paragraph to name your program. The program name that you assign is used in these ways: v Other programs use the name to call your program. v The name appears in the header on each page, except the first page, of the program listing generated when the program is compiled. v If you use the NAME compiler option, the name is placed on the NAME linkage-editor or binder control statement to identify the object module created by the compilation. Tip: Do not use program names that start with prefixes used by IBM products. If you try to use programs whose names start with any of the following, your CALL statements might resolve to IBM library or compiler routines rather than to your intended program:AFB AFH CBC CEE EDC

Copyright IBM Corp. 1991, 2002

5

IBM

IFY

IGY

IGZ

ILB

Tip: When the program name is case sensitive, avoid mismatches with the name the compiler is looking for. Verify that the appropriate setting of the PGMNAME compiler option is used.RELATED TASKS

Changing the header of a source listing on page 7 Identifying a program as recursive Marking a program as callable by containing programs Setting a program to an initial stateRELATED REFERENCES

Compiler limits (Enterprise COBOL Language Reference) Conventions for program names (Enterprise COBOL Language Reference)

Identifying a program as recursiveCode the RECURSIVE attribute on the PROGRAM-ID clause to specify that your 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 containing 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 419

Marking a program as callable by containing programsUse the COMMON attribute on the PROGRAM-ID clause to specify that your 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 416

Setting a program to an initial stateUse the INITIAL attribute to specify that whenever a program is called, it is placed in its initial state. If the program contains programs, these are also placed in their initial states. A program is in its initial state when the following has occurred: v Data items having VALUE clauses are set to the specified value. v Changed GO TO statements and PERFORM statements are set to their initial states. v Non-EXTERNAL files are closed.

6

Programming Guide

Changing the header of a source listingThe header on the first page of your source statement listing contains the identification of the compiler and the current release level, plus the date and time of compilation and the page number. For example:PP 5655-G53 IBM Enterprise COBOL for z/OS and OS/390 3.2.0 Date 08/21/2002 Time 15:05:19 Page 1

You can customize the header on succeeding pages of the listing with the compiler-directing TITLE statement.RELATED REFERENCES

TITLE statement (Enterprise COBOL Language Reference)

Describing the computing environmentIn the ENVIRONMENT DIVISION you describe the aspects of your program that depend on the computing environment. Use the CONFIGURATION SECTION to specify the following items: v Computer for compiling your program (in the SOURCE-COMPUTER paragraph) v Computer for running your 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 do the following: v Identify and describe the characteristics of your program files. v Associate your files with the external QSAM, VSAM, or HFS (hierarchical file system) data sets where they physically reside. The terms file, in COBOL terminology, and data set or HFS file, in operating system terminology, have essentially the same meaning and are used interchangeably in this documentation. 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. CICS does not allow COBOL definition of files. 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 on page 8RELATED TASKS

Specifying the collating sequence on page 8 Defining symbolic characters on page 9 Defining a user-defined class on page 10 Defining files to the operating system on page 10RELATED REFERENCES

Sections and paragraphs (Enterprise COBOL Language Reference)

Chapter 1. Structuring your program

7

Example: FILE-CONTROL entriesThe following table shows FILE-CONTROL entries for a QSAM sequential file, a VSAM indexed file, and a line-sequential file.QSAM file SELECT PRINTFILE ASSIGN TO UPDPRINT2 ORGANIZATION IS SEQUENTIAL3 ACCESS IS SEQUENTIAL.41

VSAM file SELECT COMMUTER-FILE ASSIGN TO COMMUTER2 ORGANIZATION IS INDEXED3 ACCESS IS RANDOM4 RECORD KEY IS COMMUTER-KEY5 FILE STATUS IS5 COMMUTER-FILE-STATUS COMMUTER-VSAM-STATUS.1

Line-sequential file SELECT PRINTFILE1 ASSIGN TO UPDPRINT2 ORGANIZATION IS LINE SEQUENTIAL3 ACCESS IS SEQUENTIAL.4

1. The SELECT clause chooses a file in the COBOL program to be associated with an external data set. 2. The ASSIGN clause associates the programs 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 files 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 119 Chapter 10, Processing VSAM files on page 147 Chapter 11, Processing line-sequential files on page 173 Describing the computing environment on page 7

Specifying the collating sequenceUse the PROGRAM COLLATING SEQUENCE clause and the ALPHABET clause of the SPECIAL-NAMES paragraph to establish the collating sequence used in the following operations: v Nonnumeric 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 on the SORT or MERGE statement Example: specifying the collating sequence on page 9 The sequence that you use can be based on one of these alphabets: v EBCDIC (use NATIVE if the native character set is EBCDIC), the default if you omit the ALPHABET clause v ASCII (use STANDARD-1) v ISO 7-bit code, International Reference Version (use STANDARD-2) 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 operands.

8

Programming Guide

RELATED TASKS

Choosing alternate collating sequences on page 188 Comparing national data items on page 110

Example: specifying the collating sequence

The following example shows the ENVIRONMENT DIVISION coding used to specify a collating sequence where uppercase and lowercase letters are similarly handled for comparisons and for sorting or 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 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 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 8

Defining symbolic charactersUse the SYMBOLIC CHARACTER clause to give symbolic names to any character of the specified alphabet. Use ordinal position to identify the character. Position 1 corresponds to character X00. Example: To give a name to the backspace character (X16 in the EBCDIC alphabet), code:SYMBOLIC CHARACTERS BACKSPACE IS 23

Chapter 1. Structuring your program

9

Defining a user-defined classUse the CLASS clause to give a name to a set of characters listed in the clause. For example, name the set of digits by using this code:CLASS DIGIT IS 0 THROUGH 9

The class-name can be referenced only in a class condition. This user-defined class is not the same as an object-oriented class.

Defining files to the operating systemFor 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: v DD statement for z/OS JCL. v ALLOCATE command under TSO. v Environment variable for z/OS or UNIX. The contents can define either an MVS data set or a file in the HFS (hierarchical file system). The following shows 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)), DCB=(BLKSIZE=400)

v Environment variable (export command):(1) export OUTFILE=DSNAME(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 ddname in the DD statement or the environment variable name in the export command, corresponds to the assignment-name in the ASSIGN clause: v //OUTFILE DD DSNAME=OUT171 . . ., or v export OUTFILE= . . . This assignment-name points to the ddname OUTFILE in the DD statement or the environment variable name OUTFILE in the export command:ASSIGN TO OUTFILE

(2)

When you specify a file in a COBOL FILE-CONTROL entry, you must describe the file in an FD entry for file-name.

10

Programming Guide

SELECT CARPOOL . . . FD CARPOOLRELATED TASKS

Optimizing buffer and device space on page 12

Varying the input or output file at run time

The file-name you code in your SELECT clause is used as a constant throughout your COBOL program, but you can associate the name of the file on the DD statement or export command with a different file at run time. Changing a file-name in your COBOL program requires changing the input statements and output statements and recompiling the program. Alternatively, you can change the dsname in the DD statement or the dsname path-name in your export command. Rules for using different files: The name 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. You can change the actual file by using the DSNAME in the DD statement or the DSNAME or path name in the environment variable. The file-name that you use with the SELECT clause (such as SELECT MASTER) must be the same as in the FD file-name entry. Two files should not use the same ddname or environment variable name in their SELECT clauses; otherwise, results could be unpredictable. For example, if DISPLAY is directed to SYSOUT, do not use SYSOUT as the ddname or environment variable name on the SELECT clause for a file. Example: using different input files Example: using different input files: Consider a COBOL program that is used in exactly the same way for several different master files. It contains this SELECT clause:SELECT MASTER ASSIGN TO DA-3330-S-MASTERA

Assume the three possible input files are MASTER1, MASTER2, and MASTER3. You must 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, prior to running 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 MASTERA will therefore be a reference to the file currently assigned to ddname or environment variable name MASTERA. Notice