Enterprise Cobol Programming Guide For Zos And

Os390 32 Ibm download

https://ebookbell.com/product/enterprise-cobol-programming-guide-
for-zos-and-os390-32-ibm-23632996

Explore and download more ebooks at ebookbell.com

Here are some recommended products that we believe you will be
interested in. You can click the link to download.

Enterprisegrade It Security For Small And Medium Businesses Denny

Cherry

https://ebookbell.com/product/enterprisegrade-it-security-for-small-
and-medium-businesses-denny-cherry-46152490

Enterprise Systems Architecture Aligning Business Operating Models To

Technology Landscapes 1st Edition Daljit Roy Banger

https://ebookbell.com/product/enterprise-systems-architecture-
aligning-business-operating-models-to-technology-landscapes-1st-
edition-daljit-roy-banger-46346492

Enterprise Design Operations And Computing 26th International

Conference Edoc 2022 Bozenbolzano Italy October 37 2022 Proceedings
1st Ed 2022 Joo Paulo A Almeida

https://ebookbell.com/product/enterprise-design-operations-and-
computing-26th-international-conference-edoc-2022-bozenbolzano-italy-
october-37-2022-proceedings-1st-ed-2022-joo-paulo-a-almeida-46470046

Enterprise Architecture For Digital Business Transforming It Geng Lin

https://ebookbell.com/product/enterprise-architecture-for-digital-
business-transforming-it-geng-lin-46503372
Enterprise Api Management Design And Deliver Valuable Business Apis
Luis Weir

https://ebookbell.com/product/enterprise-api-management-design-and-
deliver-valuable-business-apis-luis-weir-46651782

Enterprise Architecture And Cartography From Practice To Theory From

Representation To Design Pedro Sousa

https://ebookbell.com/product/enterprise-architecture-and-cartography-
from-practice-to-theory-from-representation-to-design-pedro-
sousa-47214946

Enterprise React Development With Umijs Learn Efficient Techniques And

Best Practices Douglas Alves Venancio

https://ebookbell.com/product/enterprise-react-development-with-umijs-
learn-efficient-techniques-and-best-practices-douglas-alves-
venancio-47666172

Enterprise Information Systems And The Digitalization Of Business

Functions Tavana

https://ebookbell.com/product/enterprise-information-systems-and-the-
digitalization-of-business-functions-tavana-48075008

Enterprise Interoperability Ix Interoperability In The Era Of

Artificial Intelligence Bernard Archimde

https://ebookbell.com/product/enterprise-interoperability-ix-
interoperability-in-the-era-of-artificial-intelligence-bernard-
archimde-49158402
Enterprise COBOL for z/OS and OS/390


Programming Guide
Version 3 Release 2

SC27-1412-01
Enterprise COBOL for z/OS and OS/390


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

Part 1. Coding your program . . . . 1

Chapter 3. Working with numbers and
arithmetic . . . . . . . . . . . . . 37
Chapter 1. Structuring your program . . 5
Defining numeric data. . . . . . . . . . . 37
Identifying a program . . . . . . . . . . . 5
Displaying numeric data . . . . . . . . . . 38
Identifying a program as recursive . . . . . . 6
Controlling how numeric data is stored . . . . . 39
Marking a program as callable by containing
Formats for numeric data. . . . . . . . . . 40
programs . . . . . . . . . . . . . . 6
External decimal (DISPLAY) items . . . . . . 40
Setting a program to an initial state. . . . . . 6
External floating-point (DISPLAY) items . . . . 40
Changing the header of a source listing . . . . 7
Binary (COMP) items . . . . . . . . . . 41
Describing the computing environment . . . . . 7
Native binary (COMP-5) items . . . . . . . 41
Example: FILE-CONTROL entries . . . . . . 8
Packed-decimal (COMP-3) items . . . . . . 42
Specifying the collating sequence . . . . . . 8
Floating-point (COMP-1 and COMP-2) items . . 42
Defining symbolic characters . . . . . . . . 9
Examples: numeric data and internal
Defining a user-defined class . . . . . . . 10
representation . . . . . . . . . . . . 42
Defining files to the operating system . . . . 10
Data format conversions . . . . . . . . . . 43
Describing the data . . . . . . . . . . . . 12
Conversions and precision . . . . . . . . 44
Using data in input and output operations . . . 12
Sign representation and processing . . . . . . 45
Comparison of WORKING-STORAGE and
NUMPROC(PFD) . . . . . . . . . . . 45
LOCAL-STORAGE . . . . . . . . . . . 14
NUMPROC(NOPFD) . . . . . . . . . . 45
Using data from another program . . . . . . 16
NUMPROC(MIG) . . . . . . . . . . . 45
Processing the data . . . . . . . . . . . . 17
Checking for incompatible data (numeric class test) 46
How logic is divided in the PROCEDURE
Performing arithmetic . . . . . . . . . . . 47
DIVISION . . . . . . . . . . . . . . 18
COMPUTE and other arithmetic statements . . 47
Declaratives . . . . . . . . . . . . . 21
Arithmetic expressions . . . . . . . . . 47
Numeric intrinsic functions . . . . . . . . 48
Chapter 2. Using data . . . . . . . . 23 Math and date Language Environment services 49
Using variables, structures, literals, and constants . 23 Examples: numeric intrinsic functions . . . . 51
Variables . . . . . . . . . . . . . . 23 Fixed-point versus floating-point arithmetic . . . 53
Data structure: data items and group items . . . 23 Floating-point evaluations . . . . . . . . 53
Literals . . . . . . . . . . . . . . . 24 Fixed-point evaluations . . . . . . . . . 54
Constants . . . . . . . . . . . . . . 24 Arithmetic comparisons (relation conditions) . . 54
Figurative constants . . . . . . . . . . 24 Examples: fixed-point and floating-point
Assigning values to data items . . . . . . . . 25 evaluations . . . . . . . . . . . . . 55
Examples: initializing variables . . . . . . . 25 Using currency signs . . . . . . . . . . . 55
Initializing a structure (INITIALIZE) . . . . . 27 Example: multiple currency signs . . . . . . 56
Assigning values to variables or structures
(MOVE) . . . . . . . . . . . . . . 27 Chapter 4. Handling tables . . . . . . 59
Assigning arithmetic results (MOVE or
Defining a table (OCCURS) . . . . . . . . . 59
COMPUTE) . . . . . . . . . . . . . 28
Nesting tables . . . . . . . . . . . . . 60
Assigning input from a screen or file (ACCEPT) 29
Subscripting . . . . . . . . . . . . . 60
Displaying values on a screen or in a file (DISPLAY) 30
Indexing . . . . . . . . . . . . . . 61
Displaying data on the system logical output
Referring to an item in a table . . . . . . . . 61
device . . . . . . . . . . . . . . . 30
Subscripting . . . . . . . . . . . . . 62

© Copyright IBM Corp. 1991, 2002 iii

 Indexing . . . . . . . . . . . . . . 63 National data items . . . . . . . . . . 105
Putting values into a table . . . . . . . . . 64 National literals . . . . . . . . . . . 106
Loading a table dynamically. . . . . . . . 64 National characters as figurative constants . . 106
Initializing a table (INITIALIZE) . . . . . . 64 Storage of national data . . . . . . . . . 106
Assigning values when you define a table Converting national data . . . . . . . . . 107
(VALUE) . . . . . . . . . . . . . . 65 Converting alphanumeric and integer to
Example: PERFORM and subscripting . . . . 66 national data (MOVE) . . . . . . . . . 107
Example: PERFORM and indexing. . . . . . 67 Converting alphanumeric to national data
Creating variable-length tables (DEPENDING ON) 68 (NATIONAL-OF) . . . . . . . . . . . 107
Loading a variable-length table . . . . . . . 69 Converting national to alphanumeric data
Assigning values to a variable-length table . . . 70 (DISPLAY-OF) . . . . . . . . . . . . 108
Searching a table . . . . . . . . . . . . 71 Conversion exceptions . . . . . . . . . 108
Doing a serial search (SEARCH) . . . . . . 71 Example: converting national data . . . . . 108
Doing a binary search (SEARCH ALL) . . . . 72 Processing UTF-8 data . . . . . . . . . . 109
Processing table items using intrinsic functions . . 73 Processing Chinese GB 18030 data . . . . . . 110
Example: intrinsic functions . . . . . . . . 73 Comparing national data items . . . . . . . 110
Comparing national operands . . . . . . . 111
Chapter 5. Selecting and repeating Comparing national and numeric operands . . 111
program actions . . . . . . . . . . 75 Comparing national and alphabetic or
alphanumeric operands . . . . . . . . . 111
Selecting program actions . . . . . . . . . 75
Comparing national and group operands . . . 111
Coding a choice of actions . . . . . . . . 75
Processing alphanumeric data items that contain
Coding conditional expressions . . . . . . . 79
DBCS data . . . . . . . . . . . . . . 111
Repeating program actions . . . . . . . . . 82
Choosing inline or out-of-line PERFORM . . . 83
Coding a loop . . . . . . . . . . . . 84 Chapter 8. Processing files . . . . . 113
Coding a loop through a table . . . . . . . 85 File organization and input-output devices . . . 113
Executing multiple paragraphs or sections . . . 85 Choosing file organization and access mode . . . 115
Format for coding input and output . . . . . 116
Chapter 6. Handling strings . . . . . . 87 Allocating files . . . . . . . . . . . . . 117
Checking for input or output errors . . . . . . 118
Joining data items (STRING) . . . . . . . . 87
Example: STRING statement. . . . . . . . 87
Splitting data items (UNSTRING) . . . . . . . 89 Chapter 9. Processing QSAM files . . 119
Example: UNSTRING statement . . . . . . 89 Defining QSAM files and records in COBOL . . . 119
Manipulating null-terminated strings . . . . . . 91 Establishing record formats. . . . . . . . 120
Example: null-terminated strings . . . . . . 92 Setting block sizes . . . . . . . . . . . 127
Referring to substrings of data items . . . . . . 92 Coding input and output statements for QSAM
Reference modifiers. . . . . . . . . . . 93 files . . . . . . . . . . . . . . . . 129
Example: arithmetic expressions as reference Opening QSAM files . . . . . . . . . . 130
modifiers . . . . . . . . . . . . . . 94 Dynamically creating QSAM files with
Example: intrinsic functions as reference CBLQDA . . . . . . . . . . . . . . 130
modifiers . . . . . . . . . . . . . . 95 Adding records to QSAM files. . . . . . . 131
Tallying and replacing data items (INSPECT) . . . 95 Updating QSAM files . . . . . . . . . 131
Examples: INSPECT statement . . . . . . . 95 Writing QSAM files to a printer or spooled data
Converting data items (intrinsic functions) . . . . 96 set . . . . . . . . . . . . . . . . 131
Converting to uppercase or lowercase Closing QSAM files . . . . . . . . . . 132
(UPPER-CASE, LOWER-CASE) . . . . . . . 97 Handling errors in QSAM files . . . . . . . 133
Converting to reverse order (REVERSE) . . . . 97 Working with QSAM files . . . . . . . . . 133
Converting to numbers (NUMVAL, NUMVAL-C) 97 Defining and allocating QSAM files . . . . . 134
Converting from one code page to another . . . 98 Retrieving QSAM files . . . . . . . . . 136
Evaluating data items (intrinsic functions) . . . . 99 Ensuring file attributes match your program 137
Evaluating single characters for collating Using striped extended-format QSAM data sets 139
sequence . . . . . . . . . . . . . . 99 Accessing HFS files using QSAM . . . . . . . 140
Finding the largest or smallest data item . . . 99 Labels for QSAM files . . . . . . . . . . 141
Finding the length of data items . . . . . . 101 Using trailer and header labels . . . . . . 141
Finding the date of compilation . . . . . . 101 Format of standard labels . . . . . . . . 143
Processing QSAM ASCII files on tape . . . . . 143
Chapter 7. Coding for run-time use of Requesting the ASCII alphabet . . . . . . 144
Defining the record formats . . . . . . . 144
national languages . . . . . . . . . 103 Defining the ddname . . . . . . . . . . 144
Unicode and encoding of language characters . . 105 Processing ASCII file labels . . . . . . . . . 145
Using national data (Unicode) in COBOL . . . . 105

iv Programming Guide
Chapter 10. Processing VSAM files 147 Sorting variable-length records . . . . . . . 186
VSAM files . . . . . . . . . . . . . . 148 Requesting the sort or merge . . . . . . . . 186
Defining VSAM file organization and records . . 149 Setting sort or merge criteria . . . . . . . 187
Specifying sequential organization for VSAM Example: sorting with input and output
files . . . . . . . . . . . . . . . 150 procedures . . . . . . . . . . . . . 188
Specifying indexed organization for VSAM files 150 Choosing alternate collating sequences . . . . 188
Specifying relative organization for VSAM files 151 Sorting on windowed date fields . . . . . . 189
Specifying access modes for VSAM files . . . 153 Preserving the original sequence of records with
Defining record lengths for VSAM files. . . . 154 equal keys . . . . . . . . . . . . . 189
Coding input and output statements for VSAM Determining whether the sort or merge was
files . . . . . . . . . . . . . . . . 155 successful . . . . . . . . . . . . . . 190
File position indicator . . . . . . . . . 157 Stopping a sort or merge operation prematurely 190
Opening a file (ESDS, KSDS, or RRDS) . . . . 157 Improving sort performance with FASTSRT . . . 191
Reading records from a VSAM file . . . . . 159 FASTSRT requirements for JCL . . . . . . 191
Updating records in a VSAM file . . . . . . 160 FASTSRT requirements for sort input and
Adding records to a VSAM file . . . . . . 161 output files . . . . . . . . . . . . . 191
Replacing records in a VSAM file. . . . . . 162 Checking for sort errors with NOFASTSRT . . . 193
Deleting records from a VSAM file . . . . . 162 Controlling sort behavior . . . . . . . . . 193
Closing VSAM files . . . . . . . . . . 162 Sort special registers . . . . . . . . . . 194
Handling errors in VSAM files . . . . . . . 163 Changing DFSORT defaults with control
Protecting VSAM files with a password . . . . 164 statements . . . . . . . . . . . . . 195
Example: password protection for a VSAM Allocating storage for sort or merge operations 195
indexed file . . . . . . . . . . . . . 164 Allocating space for sort files . . . . . . . 196
Working with VSAM data sets under z/OS and Using checkpoint/restart with DFSORT . . . . 196
UNIX . . . . . . . . . . . . . . . . 165 Sorting under CICS . . . . . . . . . . . 197
Defining VSAM files . . . . . . . . . . 165 CICS SORT application restrictions . . . . . 197
Creating alternate indexes . . . . . . . . 166
Allocating VSAM files . . . . . . . . . 168 Chapter 13. Processing XML
Sharing VSAM files through RLS . . . . . . 170 documents . . . . . . . . . . . . 199
Improving VSAM performance . . . . . . . 171 XML parser in COBOL . . . . . . . . . . 199
Accessing XML documents . . . . . . . . . 201
Chapter 11. Processing line-sequential Parsing XML documents . . . . . . . . . 201
files . . . . . . . . . . . . . . . 173 Processing XML events . . . . . . . . . 202
Defining line-sequential files and records in Writing procedures to process XML . . . . . 208
COBOL . . . . . . . . . . . . . . . 173 Understanding XML document encoding . . . . 213
Allowable control characters . . . . . . . 174 Specifying the code page . . . . . . . . 214
Describing the structure of a line-sequential file 174 Parsing documents in other code pages. . . . 214
Defining and allocating line-sequential files . . . 175 Handling errors in XML documents . . . . . . 215
Coding input-output statements for line-sequential Unhandled exceptions . . . . . . . . . 216
files . . . . . . . . . . . . . . . . 175 Handling exceptions . . . . . . . . . . 216
Opening line-sequential files . . . . . . . 176 Terminating the parse . . . . . . . . . 217
Reading records from line-sequential files . . . 176 CCSID conflict exception . . . . . . . . 217
Adding records to line-sequential files . . . . 177
Closing line-sequential files. . . . . . . . 177 Chapter 14. Handling errors . . . . . 221
Handling errors in line-sequential files . . . . . 178 Requesting dumps . . . . . . . . . . . 221
Creating a formatted dump. . . . . . . . 221
Chapter 12. Sorting and merging files 179 Creating a system dump . . . . . . . . 222
Sort and merge process . . . . . . . . . . 180 Handling errors in joining and splitting strings . . 222
Describing the sort or merge file . . . . . . . 180 Handling errors in arithmetic operations . . . . 223
Describing the input to sorting or merging . . . 181 Example: checking for division by zero . . . . 223
Example: describing sort and input files for Handling errors in input and output operations 223
SORT . . . . . . . . . . . . . . . 181 Using the end-of-file condition (AT END) . . . 226
Coding the input procedure . . . . . . . . 182 Coding ERROR declaratives . . . . . . . 227
Describing the output from sorting or merging . . 183 Using file status keys . . . . . . . . . . 228
Coding the output procedure . . . . . . . . 183 Example: file status key . . . . . . . . . 229
Coding considerations when using DFSORT . . 184 Using VSAM return codes (VSAM files only) 229
Example: coding the output procedure when Example: checking VSAM status codes . . . . 230
using DFSORT . . . . . . . . . . . . 184 Coding INVALID KEY phrases . . . . . . 231
Restrictions on input and output procedures . . . 185 Example: FILE STATUS and INVALID KEY . . 232
Defining sort and merge data sets . . . . . . 185 Handling errors when calling programs . . . . 233

Contents v
Writing routines for handling errors . . . . . . 233 Chapter 17. Compiling, linking, and
running OO applications . . . . . . 277
Part 2. Compiling and debugging Compiling, linking, and running OO applications
your program . . . . . . . . . . 235 under UNIX . . . . . . . . . . . . . . 277
Compiling OO applications under UNIX . . . 277
Preparing OO applications under UNIX . . . 278
Chapter 15. Compiling under z/OS 237 Example: compiling and linking a COBOL class
Compiling with JCL . . . . . . . . . . . 237 definition under UNIX . . . . . . . . . 279
Using a cataloged procedure . . . . . . . 238 Running OO applications under UNIX . . . . 279
Writing JCL to compile programs. . . . . . 248 Compiling, linking, and running OO applications
Compiling under TSO . . . . . . . . . . 249 using JCL or TSO/E . . . . . . . . . . . 281
Example: ALLOCATE and CALL for compiling Compiling OO applications using JCL or TSO/E 281
under TSO . . . . . . . . . . . . . 250 Preparing and running OO applications using
Example: CLIST for compiling under TSO . . . 250 JCL or TSO/E . . . . . . . . . . . . 282
Starting the compiler from an assembler program 251 Example: compiling, linking, and running an
Defining compiler input and output . . . . . . 252 OO application using JCL . . . . . . . . 283
Data sets used by the compiler under z/OS . . 253
Defining the source code data set (SYSIN) . . . 255
Chapter 18. Compiler options . . . . 287
Specifying source libraries (SYSLIB) . . . . . 255
Option settings for COBOL 85 Standard
Defining the output data set (SYSPRINT) . . . 256
conformance. . . . . . . . . . . . . . 289
Directing compiler messages to your terminal
Conflicting compiler options . . . . . . . . 289
(SYSTERM) . . . . . . . . . . . . . 256
ADATA . . . . . . . . . . . . . . . 290
Creating object code (SYSLIN or SYSPUNCH) 256
ADV . . . . . . . . . . . . . . . . 291
Creating an associated data file (SYSADATA) 257
ARITH . . . . . . . . . . . . . . . 291
Defining the output Java data set (SYSJAVA) 257
AWO . . . . . . . . . . . . . . . . 292
Defining the debug data set (SYSDEBUG) . . . 257
BUFSIZE . . . . . . . . . . . . . . . 292
Specifying compiler options under z/OS . . . . 258
CICS . . . . . . . . . . . . . . . . 293
Specifying compiler options with the PROCESS
CODEPAGE . . . . . . . . . . . . . . 294
(CBL) statement . . . . . . . . . . . 258
COMPILE . . . . . . . . . . . . . . 294
Example: specifying compiler options using JCL 259
CURRENCY . . . . . . . . . . . . . . 295
Example: specifying compiler options under
DATA . . . . . . . . . . . . . . . . 296
TSO . . . . . . . . . . . . . . . 259
DATEPROC . . . . . . . . . . . . . . 297
Compiler options and compiler output under
DBCS . . . . . . . . . . . . . . . . 298
z/OS . . . . . . . . . . . . . . . 259
DECK . . . . . . . . . . . . . . . . 298
Compiling multiple programs (batch compilation) 261
DIAGTRUNC . . . . . . . . . . . . . 298
Example: batch compilation . . . . . . . 261
DLL . . . . . . . . . . . . . . . . 299
Specifying compiler options in a batch
DUMP . . . . . . . . . . . . . . . 300
compilation . . . . . . . . . . . . . 262
DYNAM . . . . . . . . . . . . . . . 301
Example: precedence of options in a batch
EXIT . . . . . . . . . . . . . . . . 301
compilation . . . . . . . . . . . . . 263
EXPORTALL . . . . . . . . . . . . . 301
Example: LANGUAGE option in a batch
FASTSRT . . . . . . . . . . . . . . . 302
compilation . . . . . . . . . . . . . 264
FLAG . . . . . . . . . . . . . . . . 302
Correcting errors in your source program . . . . 265
FLAGSTD . . . . . . . . . . . . . . 303
Generating a list of compiler error messages . . 265
INTDATE . . . . . . . . . . . . . . 304
Messages and listings for compiler-detected
LANGUAGE . . . . . . . . . . . . . 305
errors . . . . . . . . . . . . . . . 266
LIB . . . . . . . . . . . . . . . . . 306
Format of compiler error messages . . . . . 266
LINECOUNT . . . . . . . . . . . . . 306
Severity codes for compiler error messages . . 267
LIST . . . . . . . . . . . . . . . . 306
MAP . . . . . . . . . . . . . . . . 307
Chapter 16. Compiling under UNIX 269 NAME . . . . . . . . . . . . . . . 308
Setting environment variables under UNIX . . . 269 NSYMBOL . . . . . . . . . . . . . . 309
Specifying compiler options under UNIX . . . . 270 NUMBER . . . . . . . . . . . . . . 309
Compiling and linking with the cob2 command 271 NUMPROC . . . . . . . . . . . . . . 310
Defining input and output . . . . . . . . 271 OBJECT . . . . . . . . . . . . . . . 311
Creating a DLL . . . . . . . . . . . . 272 OFFSET . . . . . . . . . . . . . . . 312
Example: using cob2 to compile under UNIX 272 OPTIMIZE . . . . . . . . . . . . . . 312
cob2 . . . . . . . . . . . . . . . 273 Unused data items . . . . . . . . . . 312
cob2 input and output files . . . . . . . . 274 OUTDD . . . . . . . . . . . . . . . 313
Compiling using scripts . . . . . . . . . . 275 PGMNAME . . . . . . . . . . . . . . 314
PGMNAME(COMPAT) . . . . . . . . . 314

vi Programming Guide
 PGMNAME(LONGUPPER). . . . . . . . 314 Chapter 20. Developing COBOL
PGMNAME(LONGMIXED) . . . . . . . 315 programs for CICS . . . . . . . . . 375
QUOTE/APOST . . . . . . . . . . . . 316 Coding COBOL programs to run under CICS . . 375
RENT . . . . . . . . . . . . . . . . 316 Coding file input and output . . . . . . . 376
RMODE . . . . . . . . . . . . . . . 317 Retrieving the system date and time. . . . . 376
SEQUENCE . . . . . . . . . . . . . . 318 Displaying the contents of data items . . . . 377
SIZE . . . . . . . . . . . . . . . . 318 Calling to or from COBOL programs . . . . 377
SOURCE . . . . . . . . . . . . . . . 319 Coding nested programs . . . . . . . . 377
SPACE . . . . . . . . . . . . . . . 319 Coding a COBOL program to run above the
SQL . . . . . . . . . . . . . . . . 320 16-MB line . . . . . . . . . . . . . 378
SSRANGE . . . . . . . . . . . . . . 321 Determining the success of ECI calls. . . . . 378
TERMINAL . . . . . . . . . . . . . . 321 Compiling with the CICS option . . . . . . . 378
TEST . . . . . . . . . . . . . . . . 322 Compiling a sequence of programs . . . . . 379
THREAD . . . . . . . . . . . . . . . 325 Separating CICS suboptions . . . . . . . 379
TRUNC . . . . . . . . . . . . . . . 326 Integrated CICS translator . . . . . . . . 380
TRUNC example 1 . . . . . . . . . . 327 Using the separate CICS translator . . . . . . 381
TRUNC example 2 . . . . . . . . . . 328 CICS reserved-word table . . . . . . . . . 382
VBREF . . . . . . . . . . . . . . . 329 Handling errors by using CICS HANDLE . . . . 383
WORD . . . . . . . . . . . . . . . 329 Example: handling errors by using CICS
XREF . . . . . . . . . . . . . . . . 330 HANDLE . . . . . . . . . . . . . 383
YEARWINDOW . . . . . . . . . . . . 331
ZWB . . . . . . . . . . . . . . . . 331
Compiler-directing statements . . . . . . . . 332
Chapter 21. Programming for a DB2
environment . . . . . . . . . . . . 385
Chapter 19. Debugging . . . . . . . 337 Coding SQL statements . . . . . . . . . . 385
Using SQL INCLUDE with the DB2 coprocessor 385
Debugging with source language . . . . . . . 338
Using character data . . . . . . . . . . 385
Tracing program logic . . . . . . . . . 338
Using binary items . . . . . . . . . . 386
Finding and handling input-output errors . . . 339
Determining the success of SQL statements . . 387
Validating data . . . . . . . . . . . . 339
Compiling with the SQL option . . . . . . . 387
Finding uninitialized data . . . . . . . . 339
Compiling in batch . . . . . . . . . . 388
Generating information about procedures . . . 340
Separating DB2 suboptions . . . . . . . . 388
Debugging using compiler options . . . . . . 341
DB2 coprocessor . . . . . . . . . . . 388
Finding coding errors . . . . . . . . . 342
Finding line sequence problems . . . . . . 343
Checking for valid ranges . . . . . . . . 343 Chapter 22. Developing COBOL
Selecting the level of error to be diagnosed . . 344 programs for IMS. . . . . . . . . . 391
Finding program entity definitions and Compiling and linking COBOL programs for
references . . . . . . . . . . . . . 345 running under IMS . . . . . . . . . . . 391
Listing data items . . . . . . . . . . . 346 Using object-oriented COBOL and Java under IMS 392
Getting listings . . . . . . . . . . . . . 347 Calling a COBOL method from an IMS Java
Example: short listing . . . . . . . . . 348 application . . . . . . . . . . . . . 392
Example: SOURCE and NUMBER output . . . 351 Building a mixed COBOL and Java application
Example: embedded map summary . . . . . 353 that starts with COBOL . . . . . . . . . 393
Terms used in MAP output. . . . . . . . 354 Writing mixed-language applications . . . . 394
Symbols used in LIST and MAP output . . . 354
Example: nested program map . . . . . . 356 Chapter 23. Running COBOL
Reading LIST output . . . . . . . . . . 356 programs under UNIX . . . . . . . . 397
Example: XREF output - data-name
Running in UNIX environments . . . . . . . 397
cross-references. . . . . . . . . . . . 368
Setting and accessing environment variables . . . 398
Example: XREF output - program-name
Setting environment variables that affect
cross-references. . . . . . . . . . . . 369
execution . . . . . . . . . . . . . . 398
Example: embedded cross-reference . . . . . 369
Resetting environment variables . . . . . . 399
Example: OFFSET compiler output . . . . . 370
Accessing environment variables . . . . . . 399
Example: VBREF compiler output . . . . . 371
Example: accessing environment variables . . . 400
Preparing to use the debugger. . . . . . . . 371
Calling UNIX/POSIX APIs . . . . . . . . . 400
fork(), exec(), and spawn() . . . . . . . . 400
Part 3. Targeting COBOL programs Samples . . . . . . . . . . . . . . 401
for certain environments . . . . . 373 Accessing main program parameters . . . . . 402
Example: accessing main program parameters 402

Contents vii
Part 4. Structuring complex Using DLLs in OO COBOL applications . . . . 446

applications . . . . . . . . . . . 405
Chapter 27. Preparing COBOL
programs for multithreading . . . . . 449
Chapter 24. Using subprograms . . . 407
Multithreading . . . . . . . . . . . . . 449
Main programs, subprograms, and calls . . . . 408
Choosing THREAD to support multithreading . . 451
Ending and reentering main programs or
Transferring control with multithreading . . . . 451
subprograms . . . . . . . . . . . . . 408
Using cancel with threaded programs . . . . 451
Transferring control to another program . . . . 410
Ending a program . . . . . . . . . . . 451
Making static calls. . . . . . . . . . . 410
Preinitializing the COBOL environment . . . 452
Making dynamic calls . . . . . . . . . 411
Processing files with multithreading . . . . . . 452
Performance considerations of static and
File definition storage . . . . . . . . . 452
dynamic calls . . . . . . . . . . . . 413
Recommended usage for file access . . . . . 453
Making both static and dynamic calls . . . . 414
Example: usage patterns of file input and
Examples: static and dynamic CALL statements 414
output with multithreading. . . . . . . . 453
Calling nested COBOL programs . . . . . . 416
Handling COBOL limitations with multithreading 454
Making recursive calls . . . . . . . . . . 419
Calling to and from object-oriented programs . . 419
Using procedure and function pointers . . . . . 420 Part 5. Developing object-oriented
Deciding which type of pointer to use . . . . 421 programs . . . . . . . . . . . . 457
Calling a C function pointer . . . . . . . 421
Calling to alternate entry points . . . . . . 421
Chapter 28. Writing object-oriented
Making programs reentrant . . . . . . . . 422
programs . . . . . . . . . . . . . 459
Example: accounts. . . . . . . . . . . . 460
Chapter 25. Sharing data . . . . . . 423
Subclasses . . . . . . . . . . . . . 461
Passing data . . . . . . . . . . . . . . 423
Defining a class . . . . . . . . . . . . 462
Describing arguments in the calling program 424
CLASS-ID paragraph for defining a class . . . 464
Describing parameters in the called program 425
REPOSITORY paragraph for defining a class 464
Testing for OMITTED arguments . . . . . . 425
WORKING-STORAGE SECTION for defining
Coding the LINKAGE SECTION . . . . . . . 425
class instance data . . . . . . . . . . . 466
Coding the PROCEDURE DIVISION for passing
Example: defining a class . . . . . . . . 467
arguments . . . . . . . . . . . . . . 426
Defining a class instance method . . . . . . . 467
Grouping data to be passed . . . . . . . 426
METHOD-ID paragraph for defining a class
Handling null-terminated strings . . . . . . 426
instance method . . . . . . . . . . . 468
Using pointers to process a chained list . . . 427
INPUT-OUTPUT SECTION for defining a class
Passing return code information . . . . . . . 430
instance method . . . . . . . . . . . 469
Understanding the RETURN-CODE special
DATA DIVISION for defining a class instance
register . . . . . . . . . . . . . . 430
method . . . . . . . . . . . . . . 469
Using PROCEDURE DIVISION RETURNING . .
PROCEDURE DIVISION for defining a class
.. . . . . . . . . . . . . . . . . 431
instance method . . . . . . . . . . . 470
Specifying CALL . . . RETURNING . . . . . 431
Overriding an instance method . . . . . . 471
Sharing data by using the EXTERNAL clause. . . 431
Overloading an instance method . . . . . . 472
Sharing files between programs (external files) . . 432
Coding attribute (get and set) methods . . . . 473
Example: using external files . . . . . . . 432
Example: defining a method . . . . . . . 474
Defining a client . . . . . . . . . . . . 475
Chapter 26. Creating a DLL or a DLL REPOSITORY paragraph for defining a client 477
application . . . . . . . . . . . . 437 DATA DIVISION for defining a client . . . . 478
Dynamic link libraries (DLLs) . . . . . . . . 437 Comparing and setting object references . . . 479
Compiling programs to create DLLs . . . . . . 438 Invoking methods (INVOKE) . . . . . . . 480
Linking DLLs . . . . . . . . . . . . . 439 Creating and initializing instances of classes . . 482
Example: sample JCL for a procedural DLL Freeing instances of classes . . . . . . . . 483
application . . . . . . . . . . . . . . 440 Example: defining a client . . . . . . . . 484
Prelinking certain DLLs . . . . . . . . . . 441 Defining a subclass . . . . . . . . . . . 484
Using CALL identifier with DLLs . . . . . . 441 CLASS-ID paragraph for defining a subclass 485
Search order for DLLs in HFS . . . . . . . 442 REPOSITORY paragraph for defining a subclass 486
Using DLL linkage and dynamic calls together . . 442 WORKING-STORAGE SECTION for defining
Using procedure or function pointers with DLLs 443 subclass instance data . . . . . . . . . 486
Calling DLLs from non-DLLs . . . . . . . 444 Defining a subclass instance method . . . . 487
Example: calling DLLs from non-DLLs . . . . 444 Example: defining a subclass (with methods) 487
Using COBOL DLLs with C/C++ programs . . . 446 Defining a factory section . . . . . . . . . 488

viii Programming Guide

 WORKING-STORAGE SECTION for defining Manipulating literals as dates . . . . . . . . 537
factory data . . . . . . . . . . . . . 489 Assumed century window . . . . . . . . 538
Defining a factory method . . . . . . . . 489 Treatment of nondates . . . . . . . . . 539
Example: defining a factory (with methods) . . 492 Setting triggers and limits . . . . . . . . . 539
Wrapping procedure-oriented COBOL programs 497 Example: using limits . . . . . . . . . 540
Structuring OO applications . . . . . . . . 498 Using sign conditions . . . . . . . . . 541
Examples: COBOL applications that you can run Sorting and merging by date . . . . . . . . 541
using the java command . . . . . . . . 498 Example: sorting by date and time . . . . . 542
Performing arithmetic on date fields. . . . . . 543
Chapter 29. Communicating with Java Allowing for overflow from windowed date
methods . . . . . . . . . . . . . 501 fields . . . . . . . . . . . . . . . 543
Specifying the order of evaluation . . . . . 544
Accessing JNI services . . . . . . . . . . 501
Controlling date processing explicitly . . . . . 545
Handling Java exceptions . . . . . . . . 502
Using DATEVAL . . . . . . . . . . . 545
Managing local and global references . . . . 504
Using UNDATE . . . . . . . . . . . 545
Java access controls . . . . . . . . . . 505
Example: DATEVAL . . . . . . . . . . 546
Sharing data with Java . . . . . . . . . . 505
Example: UNDATE . . . . . . . . . . 546
Coding interoperable data types in COBOL and
Analyzing and avoiding date-related diagnostic
Java . . . . . . . . . . . . . . . 506
messages . . . . . . . . . . . . . . . 546
Declaring arrays and strings for Java . . . . 506
Avoiding problems in processing dates . . . . . 548
Manipulating Java arrays . . . . . . . . 507
Avoiding problems with packed-decimal fields 548
Manipulating Java strings . . . . . . . . 510
Moving from expanded to windowed date fields 548
Example: J2EE client written in COBOL . . . . 512
COBOL client (ConverterClient.cbl) . . . . . 512
Java client (ConverterClient.java) . . . . . . 515 Part 7. Improving performance and
productivity . . . . . . . . . . . 551
Part 6. Specialized processing . . 517
Chapter 32. Tuning your program . . . 553
Chapter 30. Interrupts and Using an optimal programming style . . . . . 553
checkpoint/restart . . . . . . . . . 519 Using structured programming . . . . . . 554
Setting checkpoints . . . . . . . . . . . 519 Factoring expressions. . . . . . . . . . 554
Designing checkpoints . . . . . . . . . 520 Using symbolic constants . . . . . . . . 554
Testing for a successful checkpoint . . . . . 520 Grouping constant computations . . . . . . 554
DD statements for defining checkpoint data sets 521 Grouping duplicate computations . . . . . 555
Messages generated during checkpoint . . . . 522 Choosing efficient data types . . . . . . . . 555
Restarting programs . . . . . . . . . . . 522 Computational data items . . . . . . . . 555
Requesting automatic restart . . . . . . . 523 Consistent data types. . . . . . . . . . 556
Requesting deferred restart . . . . . . . . 523 Arithmetic expressions . . . . . . . . . 556
Formats for requesting deferred restart . . . . 524 Exponentiations . . . . . . . . . . . 556
Resubmitting jobs for restart . . . . . . . 525 Handling tables efficiently . . . . . . . . . 557
Example: restarting a job at a specific Optimization of table references . . . . . . 558
checkpoint step. . . . . . . . . . . . 525 Optimizing your code . . . . . . . . . . 560
Example: requesting a step restart . . . . . 525 Optimization . . . . . . . . . . . . 560
Example: resubmitting a job for a step restart 525 Example: PERFORM procedure integration . . 562
Example: resubmitting a job for a checkpoint Choosing compiler features to enhance
restart . . . . . . . . . . . . . . . 526 performance . . . . . . . . . . . . . . 562
Performance-related compiler options . . . . 563
Evaluating performance . . . . . . . . . 566
Chapter 31. Processing two-digit-year Running efficiently with CICS, IMS, or VSAM . . 566
dates . . . . . . . . . . . . . . . 527 CICS . . . . . . . . . . . . . . . 566
Millennium language extensions (MLE) . . . . 528 IMS . . . . . . . . . . . . . . . 567
Principles and objectives of these extensions . . 528 VSAM . . . . . . . . . . . . . . . 567
Resolving date-related logic problems . . . . . 529
Using a century window . . . . . . . . 530 Chapter 33. Simplifying coding . . . . 569
Using internal bridging . . . . . . . . . 531
Eliminating repetitive coding . . . . . . . . 569
Moving to full field expansion. . . . . . . 532
Example: using the COPY statement. . . . . 570
Using year-first, year-only, and year-last date fields 534
Using Language Environment callable services . . 571
Compatible dates . . . . . . . . . . . 535
Sample list of Language Environment callable
Example: comparing year-first date fields . . . 536
services . . . . . . . . . . . . . . 572
Using other date formats . . . . . . . . 536
Calling Language Environment services . . . 573
Example: isolating the year . . . . . . . . 536

Contents ix
 Example: Language Environment callable Calling from exit modules . . . . . . . . . 613
services . . . . . . . . . . . . . . 573 Processing of INEXIT. . . . . . . . . . . 613
Parameter list for INEXIT . . . . . . . . 613
Processing of LIBEXIT . . . . . . . . . . 614
Part 8. Appendixes . . . . . . . . 575
Processing of LIBEXIT with nested COPY
statements . . . . . . . . . . . . . 615
Appendix A. Intermediate results and Parameter list for LIBEXIT . . . . . . . . 616
arithmetic precision . . . . . . . . 577 Processing of PRTEXIT . . . . . . . . . . 617
Terminology used for intermediate results . . . . 578 Parameter list for PRTEXIT . . . . . . . . 617
Example: calculation of intermediate results . . . 579 Processing of ADEXIT . . . . . . . . . . 618
Fixed-point data and intermediate results . . . . 579 Parameter list for ADEXIT . . . . . . . . 619
Addition, subtraction, multiplication, and Error handling for exit modules . . . . . . . 619
division . . . . . . . . . . . . . . 579 Using the EXIT compiler option with CICS and
Exponentiation . . . . . . . . . . . . 580 SQL statements . . . . . . . . . . . . . 620
Example: exponentiation in fixed-point INEXIT . . . . . . . . . . . . . . 620
arithmetic . . . . . . . . . . . . . 581 LIBEXIT . . . . . . . . . . . . . . 620
Truncated intermediate results. . . . . . . 582 PRTEXIT . . . . . . . . . . . . . . 620
Binary data and intermediate results . . . . 582 ADEXIT . . . . . . . . . . . . . . 621
Intrinsic functions evaluated in fixed-point Example: INEXIT user exit . . . . . . . . . 621
arithmetic . . . . . . . . . . . . . . 583
Integer functions . . . . . . . . . . . 583 Appendix F. JNI.cpy . . . . . . . . 625
Mixed functions . . . . . . . . . . . 583
Floating-point data and intermediate results . . . 584
Appendix G. COBOL SYSADATA file
Exponentiations evaluated in floating-point
arithmetic . . . . . . . . . . . . . 585 contents . . . . . . . . . . . . . 631
Intrinsic functions evaluated in floating-point Existing compiler options affecting the SYSADATA
arithmetic . . . . . . . . . . . . . 585 file . . . . . . . . . . . . . . . . . 631
Arithmetic expressions in nonarithmetic statements 586 Record types . . . . . . . . . . . . . 632
Example: SYSADATA . . . . . . . . . . 633
SYSADATA record descriptions . . . . . . . 634
Appendix B. Complex OCCURS
Common header section . . . . . . . . . . 635
DEPENDING ON . . . . . . . . . . 587 Job identification record - X’0000’. . . . . . . 636
Example: complex ODO . . . . . . . . . . 587 ADATA identification record - X’0001’ . . . . . 637
How length is calculated . . . . . . . . 588 Compilation unit start/end record - X’0002’ . . . 637
Setting values of ODO objects . . . . . . . 588 Options record - X’0010’ . . . . . . . . . . 638
Effects of change in ODO object value . . . . . 588 External symbol record - X’0020’ . . . . . . . 647
Preventing index errors when changing ODO Parse tree record - X’0024’ . . . . . . . . . 648
object value . . . . . . . . . . . . . 589 Token record - X’0030’ . . . . . . . . . . 661
Preventing overlay when adding elements to a Source error record - X’0032’ . . . . . . . . 662
variable table . . . . . . . . . . . . 589 Source record - X’0038’ . . . . . . . . . . 662
COPY REPLACING record - X’0039’. . . . . . 663
Appendix C. Converting double-byte Symbol record - X’0042’ . . . . . . . . . . 664
character set (DBCS) data . . . . . . 593 Symbol cross-reference record - X’0044’ . . . . . 675
DBCS notation . . . . . . . . . . . . . 593 Nested program record - X’0046’ . . . . . . . 676
Alphanumeric to DBCS data conversion Library record - X’0060’ . . . . . . . . . . 677
(IGZCA2D) . . . . . . . . . . . . . . 593 Statistics record - X’0090’ . . . . . . . . . 678
IGZCA2D syntax . . . . . . . . . . . 593 EVENTS record - X’0120’ . . . . . . . . . 678
IGZCA2D return codes . . . . . . . . . 594
Example: IGZCA2D . . . . . . . . . . 595 Appendix H. Sample programs . . . . 679
DBCS to alphanumeric data conversion (IGZCD2A) 595 IGYTCARA: batch application . . . . . . . . 679
IGZCD2A syntax . . . . . . . . . . . 595 Input data for IGYTCARA . . . . . . . . 680
IGZCD2A return codes . . . . . . . . . 596 Report produced by IGYTCARA . . . . . . 681
Example: IGZCD2A . . . . . . . . . . 597 Preparing to run IGYTCARA . . . . . . . 682
IGYTCARB: interactive program . . . . . . . 683
Appendix D. XML reference material 599 Preparing to run IGYTCARB . . . . . . . 684
XML exceptions that allow continuation . . . . 599 IGYTSALE: nested program application . . . . 686
XML exceptions that do not allow continuation . . 603 Input data for IGYTSALE . . . . . . . . 687
XML conformance . . . . . . . . . . . . 606 Reports produced by IGYTSALE . . . . . . 689
Preparing to run IGYTSALE . . . . . . . 693
Appendix E. EXIT compiler option . . 611 Language elements and concepts that are
illustrated . . . . . . . . . . . . . . 694
Using the user-exit work area . . . . . . . . 612

x Programming Guide
Notices . . . . . . . . . . . . . . 699 Enterprise COBOL for z/OS and OS/390 . . . . 725
Trademarks . . . . . . . . . . . . . . 700 Related publications . . . . . . . . . . . 725

Glossary . . . . . . . . . . . . . 701 Index . . . . . . . . . . . . . . . 727

List of resources . . . . . . . . . . 725

Contents xi
xii Programming Guide
About this document
Welcome to IBM Enterprise COBOL for z/OS and OS/390, IBM’s 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 you

This 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 terms
Certain 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 Long form

CICS CICS Transaction Server
Enterprise COBOL IBM Enterprise COBOL for z/OS and OS/390
Language Environment IBM z/OS Language Environment
MVS MVS/ESA
UNIX 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 terms

To 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 Enterprise COBOL equivalent

Aggregate Group item
Array A table created using the OCCURS clause
Array element Table element
Enclave Run unit
External data WORKING-STORAGE data defined with EXTERNAL clause
Local data Any non-EXTERNAL data item
Pass parameters directly, by value BY VALUE
Pass parameters indirectly, by BY REFERENCE
reference
Pass parameters indirectly, by value BY CONTENT
Routine Program
Scalar Elementary item

How to read syntax diagrams

The 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.
The symbol indicates the beginning of a statement.

xiv Programming Guide

 The symbol indicates that the statement syntax is continued on the next
line.
The symbol indicates that a statement is continued from the previous line.
The symbol indicates the end of a statement.
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 shown

This 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 changes
This 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 User’s 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 comments
Your 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 program
Chapter 1. Structuring your program . . . . . 5 Types of intrinsic functions . . . . . . . . 32
Identifying a program . . . . . . . . . . . 5 Nesting functions . . . . . . . . . . . 33
Identifying a program as recursive . . . . . . 6 Using tables (arrays) and pointers . . . . . . . 33
Marking a program as callable by containing Storage and its addressability . . . . . . . . 33
programs . . . . . . . . . . . . . . 6 Settings for RMODE . . . . . . . . . . . 34
Setting a program to an initial state. . . . . . 6 Storage restrictions for passing data . . . . . 34
Changing the header of a source listing . . . . 7 Location of data areas . . . . . . . . . 35
Describing the computing environment . . . . . 7 Storage for external data . . . . . . . . . 35
Example: FILE-CONTROL entries . . . . . . 8 Storage for QSAM input-output buffers . . . . 35
Specifying the collating sequence . . . . . . 8
Example: specifying the collating sequence . . 9 Chapter 3. Working with numbers and arithmetic 37
Defining symbolic characters . . . . . . . . 9 Defining numeric data. . . . . . . . . . . 37
Defining a user-defined class . . . . . . . 10 Displaying numeric data . . . . . . . . . . 38
Defining files to the operating system . . . . 10 Controlling how numeric data is stored . . . . . 39
Varying the input or output file at run time . 11 Formats for numeric data. . . . . . . . . . 40
Optimizing buffer and device space . . . . 12 External decimal (DISPLAY) items . . . . . . 40
Describing the data . . . . . . . . . . . . 12 External floating-point (DISPLAY) items . . . . 40
Using data in input and output operations . . . 12 Binary (COMP) items . . . . . . . . . . 41
FILE SECTION entries. . . . . . . . . 13 Native binary (COMP-5) items . . . . . . . 41
Comparison of WORKING-STORAGE and Packed-decimal (COMP-3) items . . . . . . 42
LOCAL-STORAGE . . . . . . . . . . . 14 Floating-point (COMP-1 and COMP-2) items . . 42
Example: storage sections. . . . . . . . 15 Examples: numeric data and internal
Using data from another program . . . . . . 16 representation . . . . . . . . . . . . 42
Sharing data in separately compiled programs 16 Data format conversions . . . . . . . . . . 43
Sharing data in nested programs . . . . . 16 Conversions and precision . . . . . . . . 44
Sharing data in recursive or multithreaded Conversions that preserve precision . . . . 44
programs . . . . . . . . . . . . . 17 Conversions that result in rounding . . . . 44
Processing the data . . . . . . . . . . . . 17 Sign representation and processing . . . . . . 45
How logic is divided in the PROCEDURE NUMPROC(PFD) . . . . . . . . . . . 45
DIVISION . . . . . . . . . . . . . . 18 NUMPROC(NOPFD) . . . . . . . . . . 45
Imperative statements . . . . . . . . . 19 NUMPROC(MIG) . . . . . . . . . . . 45
Conditional statements . . . . . . . . 19 Checking for incompatible data (numeric class test) 46
Compiler-directing statements . . . . . . 20 Performing arithmetic . . . . . . . . . . . 47
Scope terminators . . . . . . . . . . 20 COMPUTE and other arithmetic statements . . 47
Declaratives . . . . . . . . . . . . . 21 Arithmetic expressions . . . . . . . . . 47
Numeric intrinsic functions . . . . . . . . 48
Chapter 2. Using data . . . . . . . . . . 23 Nesting functions and arithmetic expressions 49
Using variables, structures, literals, and constants . 23 ALL subscripting and special registers . . . 49
Variables . . . . . . . . . . . . . . 23 Math and date Language Environment services 49
Data structure: data items and group items . . . 23 Math-oriented callable services . . . . . . 49
Literals . . . . . . . . . . . . . . . 24 Date callable services . . . . . . . . . 50
Constants . . . . . . . . . . . . . . 24 Examples: numeric intrinsic functions . . . . 51
Figurative constants . . . . . . . . . . 24 General number handling . . . . . . . 51
Assigning values to data items . . . . . . . . 25 Date and time . . . . . . . . . . . 52
Examples: initializing variables . . . . . . . 25 Finance . . . . . . . . . . . . . . 52
Initializing a structure (INITIALIZE) . . . . . 27 Mathematics . . . . . . . . . . . . 53
Assigning values to variables or structures Statistics . . . . . . . . . . . . . 53
(MOVE) . . . . . . . . . . . . . . 27 Fixed-point versus floating-point arithmetic . . . 53
Assigning arithmetic results (MOVE or Floating-point evaluations . . . . . . . . 53
COMPUTE) . . . . . . . . . . . . . 28 Fixed-point evaluations . . . . . . . . . 54
Assigning input from a screen or file (ACCEPT) 29 Arithmetic comparisons (relation conditions) . . 54
Displaying values on a screen or in a file (DISPLAY) 30 Examples: fixed-point and floating-point
Displaying data on the system logical output evaluations . . . . . . . . . . . . . 55
device . . . . . . . . . . . . . . . 30 Using currency signs . . . . . . . . . . . 55
Using WITH NO ADVANCING . . . . . . 31 Example: multiple currency signs . . . . . . 56
Using intrinsic functions (built-in functions) . . . 32

© Copyright IBM Corp. 1991, 2002 1

Chapter 4. Handling tables. . . . . . . . . 59 Example: arithmetic expressions as reference
Defining a table (OCCURS) . . . . . . . . . 59 modifiers . . . . . . . . . . . . . . 94
Nesting tables . . . . . . . . . . . . . 60 Example: intrinsic functions as reference
Subscripting . . . . . . . . . . . . . 60 modifiers . . . . . . . . . . . . . . 95
Indexing . . . . . . . . . . . . . . 61 Tallying and replacing data items (INSPECT) . . . 95
Referring to an item in a table . . . . . . . . 61 Examples: INSPECT statement . . . . . . . 95
Subscripting . . . . . . . . . . . . . 62 Converting data items (intrinsic functions) . . . . 96
Indexing . . . . . . . . . . . . . . 63 Converting to uppercase or lowercase
Putting values into a table . . . . . . . . . 64 (UPPER-CASE, LOWER-CASE) . . . . . . . 97
Loading a table dynamically. . . . . . . . 64 Converting to reverse order (REVERSE) . . . . 97
Initializing a table (INITIALIZE) . . . . . . 64 Converting to numbers (NUMVAL, NUMVAL-C) 97
Assigning values when you define a table Converting from one code page to another . . . 98
(VALUE) . . . . . . . . . . . . . . 65 Evaluating data items (intrinsic functions) . . . . 99
Initializing each table item individually . . . 65 Evaluating single characters for collating
Initializing a table at the 01 level . . . . . 65 sequence . . . . . . . . . . . . . . 99
Initializing all occurrences of a table element 65 Finding the largest or smallest data item . . . 99
Example: PERFORM and subscripting . . . . 66 MAX and MIN . . . . . . . . . . . 99
Example: PERFORM and indexing. . . . . . 67 ORD-MAX and ORD-MIN . . . . . . . 100
Creating variable-length tables (DEPENDING ON) 68 Returning variable-length results with
Loading a variable-length table . . . . . . . 69 alphanumeric functions . . . . . . . . 100
Assigning values to a variable-length table . . . 70 Finding the length of data items . . . . . . 101
Searching a table . . . . . . . . . . . . 71 Finding the date of compilation . . . . . . 101
Doing a serial search (SEARCH) . . . . . . 71
Example: serial search . . . . . . . . . 71 Chapter 7. Coding for run-time use of national
Doing a binary search (SEARCH ALL) . . . . 72 languages . . . . . . . . . . . . . . 103
Example: binary search . . . . . . . . 72 Unicode and encoding of language characters . . 105
Processing table items using intrinsic functions . . 73 Using national data (Unicode) in COBOL . . . . 105
Example: intrinsic functions . . . . . . . . 73 National data items . . . . . . . . . . 105
National literals . . . . . . . . . . . 106
Chapter 5. Selecting and repeating program National characters as figurative constants . . 106
actions . . . . . . . . . . . . . . . 75 Storage of national data . . . . . . . . . 106
Selecting program actions . . . . . . . . . 75 Converting national data . . . . . . . . . 107
Coding a choice of actions . . . . . . . . 75 Converting alphanumeric and integer to
Using nested IF statements . . . . . . . 76 national data (MOVE) . . . . . . . . . 107
Using the EVALUATE statement . . . . . 77 Converting alphanumeric to national data
Coding conditional expressions . . . . . . . 79 (NATIONAL-OF) . . . . . . . . . . . 107
Switches and flags . . . . . . . . . . 80 Converting national to alphanumeric data
Defining switches and flags . . . . . . . 80 (DISPLAY-OF) . . . . . . . . . . . . 108
Example: switches . . . . . . . . . . 80 Overriding the default code page. . . . . 108
Example: flags . . . . . . . . . . . 81 Conversion exceptions . . . . . . . . . 108
Resetting switches and flags . . . . . . . 81 Example: converting national data . . . . . 108
Example: set switch on . . . . . . . . 81 Processing UTF-8 data . . . . . . . . . . 109
Example: set switch off . . . . . . . . 82 Processing Chinese GB 18030 data . . . . . . 110
Repeating program actions . . . . . . . . . 82 Comparing national data items . . . . . . . 110
Choosing inline or out-of-line PERFORM . . . 83 Comparing national operands . . . . . . . 111
Example: inline PERFORM statement . . . . 83 Comparing national and numeric operands . . 111
Coding a loop . . . . . . . . . . . . 84 Comparing national and alphabetic or
Coding a loop through a table . . . . . . . 85 alphanumeric operands . . . . . . . . . 111
Executing multiple paragraphs or sections . . . 85 Comparing national and group operands . . . 111
Processing alphanumeric data items that contain
Chapter 6. Handling strings . . . . . . . . 87 DBCS data . . . . . . . . . . . . . . 111
Joining data items (STRING) . . . . . . . . 87
Example: STRING statement. . . . . . . . 87 Chapter 8. Processing files . . . . . . . . 113
STRING program results . . . . . . . . 88 File organization and input-output devices . . . 113
Splitting data items (UNSTRING) . . . . . . . 89 Choosing file organization and access mode . . . 115
Example: UNSTRING statement . . . . . . 89 Format for coding input and output . . . . . 116
UNSTRING program results . . . . . . . 90 Allocating files . . . . . . . . . . . . . 117
Manipulating null-terminated strings . . . . . . 91 Checking for input or output errors . . . . . . 118
Example: null-terminated strings . . . . . . 92
Referring to substrings of data items . . . . . . 92 Chapter 9. Processing QSAM files . . . . . 119
Reference modifiers. . . . . . . . . . . 93 Defining QSAM files and records in COBOL . . . 119

2 Programming Guide
 Establishing record formats. . . . . . . . 120 Specifying relative organization for VSAM files 151
Logical records . . . . . . . . . . . 120 Fixed-length and variable-length RRDS . . . 152
Requesting fixed-length format . . . . . 121 Simulating variable-length RRDS . . . . . 152
Requesting variable-length format . . . . 122 Specifying access modes for VSAM files . . . 153
Requesting spanned format. . . . . . . 124 Example: using dynamic access with VSAM
Requesting undefined format . . . . . . 126 files . . . . . . . . . . . . . . 154
Setting block sizes . . . . . . . . . . . 127 Defining record lengths for VSAM files. . . . 154
Letting z/OS determine block size . . . . 127 Defining fixed-length records . . . . . . 154
Setting block size explicitly . . . . . . . 127 Defining variable-length records . . . . . 154
Taking advantage of LBI. . . . . . . . 128 Coding input and output statements for VSAM
Block size and the DCB RECFM files . . . . . . . . . . . . . . . . 155
subparameter . . . . . . . . . . . 129 File position indicator . . . . . . . . . 157
Coding input and output statements for QSAM Opening a file (ESDS, KSDS, or RRDS) . . . . 157
files . . . . . . . . . . . . . . . . 129 Opening an empty file . . . . . . . . 158
Opening QSAM files . . . . . . . . . . 130 Statements to load records into a VSAM file 159
Dynamically creating QSAM files with Opening a loaded file (a file with records) 159
CBLQDA . . . . . . . . . . . . . . 130 Reading records from a VSAM file . . . . . 159
Adding records to QSAM files. . . . . . . 131 Updating records in a VSAM file . . . . . . 160
Updating QSAM files . . . . . . . . . 131 Adding records to a VSAM file . . . . . . 161
Writing QSAM files to a printer or spooled data Adding records sequentially . . . . . . 161
set . . . . . . . . . . . . . . . . 131 Adding records randomly or dynamically 162
Controlling the page size . . . . . . . 132 Replacing records in a VSAM file. . . . . . 162
Controlling the vertical positioning of records 132 Deleting records from a VSAM file . . . . . 162
Closing QSAM files . . . . . . . . . . 132 Closing VSAM files . . . . . . . . . . 162
Handling errors in QSAM files . . . . . . . 133 Handling errors in VSAM files . . . . . . . 163
Working with QSAM files . . . . . . . . . 133 Protecting VSAM files with a password . . . . 164
Defining and allocating QSAM files . . . . . 134 Example: password protection for a VSAM
Parameters for creating QSAM files . . . . 135 indexed file . . . . . . . . . . . . . 164
Retrieving QSAM files . . . . . . . . . 136 Working with VSAM data sets under z/OS and
Parameters for retrieving QSAM files . . . 136 UNIX . . . . . . . . . . . . . . . . 165
Ensuring file attributes match your program 137 Defining VSAM files . . . . . . . . . . 165
Processing existing files . . . . . . . . 137 Creating alternate indexes . . . . . . . . 166
Defining variable-length (format-V) records 137 Example: entries for alternate indexes . . . 168
Defining format-U records . . . . . . . 138 Allocating VSAM files . . . . . . . . . 168
Defining fixed-length records . . . . . . 138 Sharing VSAM files through RLS . . . . . . 170
Processing new files . . . . . . . . . 138 Preventing update problems with VSAM files
Processing files dynamically created by in RLS mode . . . . . . . . . . . 170
COBOL . . . . . . . . . . . . . 139 Restrictions when using RLS . . . . . . 170
Using striped extended-format QSAM data sets 139 Handling errors in VSAM files in RLS mode 171
Allocation of buffers for QSAM files. . . . 140 Improving VSAM performance . . . . . . . 171
Accessing HFS files using QSAM . . . . . . . 140
Labels for QSAM files . . . . . . . . . . 141 Chapter 11. Processing line-sequential files . . 173
Using trailer and header labels . . . . . . 141 Defining line-sequential files and records in
Getting a user-label track . . . . . . . 142 COBOL . . . . . . . . . . . . . . . 173
Handling user labels . . . . . . . . . 142 Allowable control characters . . . . . . . 174
Format of standard labels . . . . . . . . 143 Describing the structure of a line-sequential file 174
Standard user labels . . . . . . . . . 143 Defining and allocating line-sequential files . . . 175
Processing QSAM ASCII files on tape . . . . . 143 Coding input-output statements for line-sequential
Requesting the ASCII alphabet . . . . . . 144 files . . . . . . . . . . . . . . . . 175
Defining the record formats . . . . . . . 144 Opening line-sequential files . . . . . . . 176
Defining the ddname . . . . . . . . . . 144 Reading records from line-sequential files . . . 176
Processing ASCII file labels . . . . . . . . . 145 Adding records to line-sequential files . . . . 177
Closing line-sequential files. . . . . . . . 177
Chapter 10. Processing VSAM files . . . . . 147 Handling errors in line-sequential files . . . . . 178
VSAM files . . . . . . . . . . . . . . 148
Defining VSAM file organization and records . . 149 Chapter 12. Sorting and merging files . . . . 179
Specifying sequential organization for VSAM Sort and merge process . . . . . . . . . . 180
files . . . . . . . . . . . . . . . 150 Describing the sort or merge file . . . . . . . 180
Specifying indexed organization for VSAM files 150 Describing the input to sorting or merging . . . 181
Alternate keys . . . . . . . . . . . 151 Example: describing sort and input files for
Alternate index . . . . . . . . . . . 151 SORT . . . . . . . . . . . . . . . 181

Part 1. Coding your program 3

Coding the input procedure . . . . . . . . 182 Requesting dumps . . . . . . . . . . . 221
Describing the output from sorting or merging . . 183 Creating a formatted dump. . . . . . . . 221
Coding the output procedure . . . . . . . . 183 Creating a system dump . . . . . . . . 222
Coding considerations when using DFSORT . . 184 Handling errors in joining and splitting strings . . 222
Example: coding the output procedure when Handling errors in arithmetic operations . . . . 223
using DFSORT . . . . . . . . . . . . 184 Example: checking for division by zero . . . . 223
Restrictions on input and output procedures . . . 185 Handling errors in input and output operations 223
Defining sort and merge data sets . . . . . . 185 Using the end-of-file condition (AT END) . . . 226
Sorting variable-length records . . . . . . . 186 Coding ERROR declaratives . . . . . . . 227
Requesting the sort or merge . . . . . . . . 186 Using file status keys . . . . . . . . . . 228
Setting sort or merge criteria . . . . . . . 187 Example: file status key . . . . . . . . . 229
Example: sorting with input and output Using VSAM return codes (VSAM files only) 229
procedures . . . . . . . . . . . . . 188 Example: checking VSAM status codes . . . . 230
Choosing alternate collating sequences . . . . 188 Coding INVALID KEY phrases . . . . . . 231
Sorting on windowed date fields . . . . . . 189 INVALID KEY and ERROR declaratives . . 232
Preserving the original sequence of records with NOT INVALID KEY . . . . . . . . . 232
equal keys . . . . . . . . . . . . . 189 Example: FILE STATUS and INVALID KEY . . 232
Determining whether the sort or merge was Handling errors when calling programs . . . . 233
successful . . . . . . . . . . . . . . 190 Writing routines for handling errors . . . . . . 233
Stopping a sort or merge operation prematurely 190
Improving sort performance with FASTSRT . . . 191
FASTSRT requirements for JCL . . . . . . 191
FASTSRT requirements for sort input and
output files . . . . . . . . . . . . . 191
QSAM requirements . . . . . . . . . 192
VSAM requirements . . . . . . . . . 193
Checking for sort errors with NOFASTSRT . . . 193
Controlling sort behavior . . . . . . . . . 193
Sort special registers . . . . . . . . . . 194
Changing DFSORT defaults with control
statements . . . . . . . . . . . . . 195
Default characteristics of the IGZSRTCD data
set . . . . . . . . . . . . . . . 195
Allocating storage for sort or merge operations 195
Allocating space for sort files . . . . . . . 196
Using checkpoint/restart with DFSORT . . . . 196
Sorting under CICS . . . . . . . . . . . 197
CICS SORT application restrictions . . . . . 197

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 program
A 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 program
Use 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 state”

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

Identifying a program as recursive

Code the RECURSIVE attribute on the PROGRAM-ID clause to specify that 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 programs

Use 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 state

Use 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 listing
The 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 environment

In 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 8

RELATED 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 10

RELATED REFERENCES
Sections and paragraphs (Enterprise COBOL Language Reference)

Chapter 1. Structuring your program 7

 Example: FILE-CONTROL entries
The following table shows FILE-CONTROL entries for a QSAM sequential file, a
VSAM indexed file, and a line-sequential file.

QSAM file VSAM file Line-sequential file

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

1. The SELECT clause chooses a file in the COBOL program to be associated with an external data set.
2. The ASSIGN clause associates the program’s name for the file with the external name for the actual data file. You
can define the external name with a DD statement or an environment variable.
3. The ORGANIZATION clause describes the file’s organization. For QSAM files, the ORGANIZATION clause is optional.
4. The ACCESS MODE clause defines the manner in which the records are made available for processing: sequential,
random, or dynamic. For QSAM and line-sequential files, the ACCESS MODE clause is optional. These files always
have sequential organization.
5. For VSAM files, you might have additional statements in the FILE-CONTROL paragraph depending on the type of
VSAM file you use.

RELATED TASKS
Chapter 9, “Processing QSAM files” on page 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 sequence

Use 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 characters

Use 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 X’00’. Example: To give a name to the backspace character
(X’16’ in the EBCDIC alphabet), code:
SYMBOLIC CHARACTERS BACKSPACE IS 23

Chapter 1. Structuring your program 9

 Defining a user-defined class
Use 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 system

For all files that you process in your COBOL program, you need to define the files
to the operating system with an appropriate system data definition:
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 CARPOOL

RELATED 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 that in this example, you cannot use the PATH(path) form of the export
command to reference a line-sequential file in the HFS, because you cannot specify
an organization field (S- or AS-) with a line-sequential file.

Chapter 1. Structuring your program 11

 Optimizing buffer and device space
Use the APPLY WRITE-ONLY clause to make optimum use of buffer and device space
when creating a sequential file with blocked variable-length records. With APPLY
WRITE-ONLY specified, a buffer is truncated only when the next record does not fit
in the unused portion of the buffer. Without APPLY WRITE-ONLY specified, a buffer is
truncated when it does not have enough space for a maximum-size record.

The APPLY WRITE-ONLY clause has meaning only for sequential files that have
variable-length records and are blocked.

The AWO compiler option applies an implicit APPLY WRITE-ONLY clause to all eligible
files. The NOAWO compiler option has no effect on files that have the APPLY
WRITE-ONLY clause specified. The APPLY WRITE-ONLY clause takes precedence over
the NOAWO compiler option.

The APPLY-WRITE ONLY clause can cause input files to use a record area rather than
process the data in the buffer. This use might affect the processing of both input
files and output files.

RELATED REFERENCES
“AWO” on page 292

Describing the data

Define the characteristics of your data and group your data definitions into one of
the sections in the DATA DIVISION:
v Define data used in input-output operations (FILE SECTION).
v Define data developed for internal processing:
– To have storage be statically allocated and exist for the life of the run unit
(WORKING-STORAGE SECTION).
– To have storage be allocated each time a program is called and deallocated
when the program ends (LOCAL-STORAGE SECTION).
v Describe data from another program (LINKAGE SECTION).

The Enterprise COBOL compiler limits the maximum size of DATA DIVISION
elements.

RELATED CONCEPTS
“Comparison of WORKING-STORAGE and LOCAL-STORAGE” on page 14

RELATED TASKS
“Using data in input and output operations”
“Using data from another program” on page 16

RELATED REFERENCES
Compiler limits (Enterprise COBOL Language Reference)

Using data in input and output operations

Define the data you use in input and output operations in the FILE SECTION:
v Name the input and output files your program will use. Use the FD entry to give
names to your files that the input-output statements in the PROCEDURE DIVISION
can refer to.
Data items defined in the FILE SECTION are not available to PROCEDURE DIVISION
statements until the file has been successfully opened.

12 Programming Guide
v In the record description following the FD entry, describe the fields of the records
in the file:
– You can code a level-01 description of the entire record, and then in the
WORKING-STORAGE SECTION code a working copy that describes the fields of the
record in more detail. Use the READ INTO statement to bring the records into
WORKING-STORAGE. Processing occurs on the copy of data in WORKING-STORAGE.
A WRITE FROM statement then writes processed data into the record area
defined in the FILE SECTION.
– The record-name established is the object of WRITE and REWRITE statements.
– For QSAM files only, you can set the record format in the RECORDING MODE
clause. If you omit the RECORDING MODE clause, the compiler determines the
record format based on the RECORD clause and on the level-01 record
descriptions.
– For QSAM files, you can set a blocking factor for the file in the BLOCK
CONTAINS clause. If you omit the BLOCK CONTAINS clause, the file defaults to
unblocked. However, you can override this with z/OS data management
facilities (including a DD file job control statement).
– For line-sequential files, you can set a blocking factor for the file in the BLOCK
CONTAINS clause. When you code BLOCK CONTAINS 1 RECORDS, or BLOCK
CONTAINS n CHARACTERS, where n is the length of one logical record, WRITE
statements result in the record being transferred immediately to the file,
rather than being buffered. This technique is useful when you want each
record written immediately, such as to an error log.

Programs in the same run unit can share, or have access to, common files. The
method for doing this depends on whether the programs are part of a nested
(contained) structure or are separately compiled (including programs compiled as
part of a batch sequence).

You can use the EXTERNAL clause for separately compiled programs. A file that is
defined as EXTERNAL can be referenced by any program in the run unit that
describes the file.

You can use the GLOBAL clause for programs in a nested, or contained, structure. If
a program contains another program (directly or indirectly), both programs can
access a common file by referencing a GLOBAL file name.

RELATED CONCEPTS
“Nested programs” on page 416

RELATED TASKS
“Sharing files between programs (external files)” on page 432

RELATED REFERENCES
“FILE SECTION entries”

FILE SECTION entries

Clause To define Notes
FD The file-name to be referred to Must match file-name in the SELECT
in PROCEDURE DIVISION clause. file-name is associated with a
input-output statements (OPEN, ddname through the assignment-name.
CLOSE, READ, also START and
DELETE for VSAM)

Chapter 1. Structuring your program 13

 Clause To define Notes
BLOCK CONTAINS Size of physical record QSAM: If provided, must match
information on JCL or data set label. If
not provided, the system determines
the optimal block size for you.

Line sequential: Can be specified to

control buffering for WRITE statements.

VSAM: Handled as comments.

RECORD CONTAINS Size of logical records (fixed If provided, must match information on
n length) JCL or data set label. If n is equal to 0,
LRECL must be coded on JCL or data set
label.
RECORD IS Size of logical records If provided, must match information on
VARYING (variable length) JCL or data set label; compiler checks
match with record descriptions.
RECORD CONTAINS Size of logical records If provided, must match information on
n TO m (variable length) JCL or data set label; compiler checks
match with record descriptions.
LABEL RECORDS Labels for QSAM files VSAM: Handled as comments
STANDARD Labels exist QSAM: Handled as comments
OMITTED Labels do not exist QSAM: Handled as comments
data-name Labels defined by the user QSAM: Allowed for (optional) tape or
disk
VALUE OF An item in the label records Comments only
associated with file
DATA RECORDS Names of records associated Comments only
with file
LINAGE Depth of logical page QSAM only
CODE-SET ASCII or EBCDIC files QSAM only.

When an ASCII file is identified with

the CODE-SET clause, the corresponding
DD statement might need to have
DCB=(OPTCD=Q. . .) or
DCB=(RECFM=D. . .) coded if the file
was not created using VS COBOL II,
COBOL for OS/390 & VM, or IBM
Enterprise COBOL for z/OS and
OS/390.
RECORDING MODE Physical record description QSAM only

RELATED CONCEPTS
“Labels for QSAM files” on page 141

Comparison of WORKING-STORAGE and LOCAL-STORAGE

| WORKING-STORAGE for programs is allocated at the start of the run unit. Any data
items with VALUE clauses are initialized to the appropriate value at that time. For
the duration of the run unit, WORKING-STORAGE items persist in their last-used state.
Exceptions are:
v A program with INITIAL specified in the PROGRAM-ID paragraph

14 Programming Guide
 In this case, WORKING-STORAGE data items are reinitialized each time that the
program is entered.
v A subprogram that is dynamically called and then canceled
In this case, WORKING-STORAGE data items are reinitialized on the first reentry into
the program following the CANCEL.

WORKING-STORAGE is deallocated at the termination of the run unit.

| See the related tasks for information about WORKING-STORAGE in COBOL class
| definitions.

| A separate copy of LOCAL-STORAGE data is allocated for each call of a program or

| invocation of a method, and is freed on return from the program or method. If you
| specify a VALUE clause on a LOCAL-STORAGE item, the item is initialized to that value
| on each call or invocation. If a VALUE clause is not specified, the initial value of the
| item is undefined.

Threading: Each invocation of a program that runs simultaneously on multiple

threads shares access to a single copy of WORKING-STORAGE data. Each invocation
has a separate copy of LOCAL-STORAGE data.

“Example: storage sections”

RELATED TASKS
“WORKING-STORAGE SECTION for defining class instance data” on page 466
Chapter 27, “Preparing COBOL programs for multithreading” on page 449
“Ending and reentering main programs or subprograms” on page 408

RELATED REFERENCES
Working-Storage section (Enterprise COBOL Language Reference)
Local-Storage section (Enterprise COBOL Language Reference)

Example: storage sections

The following is an example of a recursive program that uses both
WORKING-STORAGE and LOCAL-STORAGE.
CBL pgmn(lu)
*********************************
* Recursive Program - Factorials
*********************************
IDENTIFICATION DIVISION.
Program-Id. factorial recursive.
ENVIRONMENT DIVISION.
DATA DIVISION.
Working-Storage Section.
01 numb pic 9(4) value 5.
01 fact pic 9(8) value 0.
Local-Storage Section.
01 num pic 9(4).
PROCEDURE DIVISION.
move numb to num.

if numb = 0
move 1 to fact
else
subtract 1 from numb
call ’factorial’
multiply num by fact
end-if.

Chapter 1. Structuring your program 15

 display num ’! = ’ fact.
goback.
End Program factorial.

The following tables show the changing values of the data items in LOCAL-STORAGE
(L-S) and WORKING-STORAGE (W-S) in the successive recursive calls of the program,
and in the ensuing gobacks. During the gobacks, fact progressively accumulates
the value of 5! (five factorial).
Recursive
CALLs: Main 1 2 3 4 5
___________________________________
L-S num 5 4 3 2 1 0
___________________________________
W-S numb 5 4 3 2 1 0
fact 0 0 0 0 0 0
___________________________________
Recursive
GOBACKs: 5 4 3 2 1 Main
____________________________________
L-S num 0 1 2 3 4 5
____________________________________
W-S numb 0 0 0 0 0 0
fact 1 1 2 6 24 120
____________________________________

RELATED CONCEPTS
“Comparison of WORKING-STORAGE and LOCAL-STORAGE” on page 14

Using data from another program

How you share data depends on the type of program. You share data differently in
programs that are separately compiled than you do for programs that are nested or
for programs that are recursive or multithreaded.

RELATED TASKS
“Sharing data in separately compiled programs”
“Sharing data in nested programs”

Sharing data in separately compiled programs

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

RELATED TASKS
“Passing data” on page 423

Sharing data in nested programs

Some applications consist of nested programs—programs that are contained in
other programs. Level-01 LINKAGE SECTION data items can include the GLOBAL
attribute. This attribute allows any nested program that includes the declarations
to access these LINKAGE SECTION data items.

A nested program can also access data items in a sibling program (one at the same
nesting level in the same containing program) that is declared with the COMMON
attribute.

RELATED CONCEPTS
“Nested programs” on page 416

16 Programming Guide
 Sharing data in recursive or multithreaded programs
If you compile your program as RECURSIVE or with the THREAD compiler option,
data that is defined in the LINKAGE SECTION is not accessible on subsequent
invocations of the program.

To address a record in the LINKAGE SECTION, use either of these techniques:

v Pass an argument to the program and specify the record in an appropriate
position in the USING phrase in the program.
v Use the format-5 SET statement.

If you compile your program as RECURSIVE or with the THREAD compiler option, the
address of the record is valid for a particular instance of the program invocation.
The address of the record in another execution instance of the same program must
be reestablished for that execution instance. Unpredictable results will occur if you
refer to a data item for which the address has not been established.

RELATED CONCEPTS
“Multithreading” on page 449

RELATED TASKS
“Making recursive calls” on page 419
“Processing files with multithreading” on page 452

RELATED REFERENCES
SET statement (Enterprise COBOL Language Reference)
“THREAD” on page 325

Processing the data

In the PROCEDURE DIVISION of a program, you code the executable statements that
process the data you have defined in the other divisions. The PROCEDURE DIVISION
contains one or two headers and the logic of your program.

The PROCEDURE DIVISION begins with the division header and a procedure-name
header. The division header for a program can simply be:
PROCEDURE DIVISION.

You can code your division header to receive parameters with the USING phrase or
to return a value with the RETURNING phrase.

To receive an argument that was passed by reference (the default) or by content,

code the division header for a program in either of these ways:
PROCEDURE DIVISION USING dataname
PROCEDURE DIVISION USING BY REFERENCE dataname

Be sure to define dataname in the LINKAGE SECTION of the DATA DIVISION.

To receive a parameter that was passed by value, code the division header for a
program as follows:
PROCEDURE DIVISION USING BY VALUE dataname

To return a value as a result, code the division header as follows:

PROCEDURE DIVISION RETURNING dataname2

You can also combine USING and RETURNING in a PROCEDURE DIVISION header:

Chapter 1. Structuring your program 17

 PROCEDURE DIVISION USING dataname RETURNING dataname2

Be sure to define dataname and dataname2 in the LINKAGE SECTION of the DATA
DIVISION.

RELATED CONCEPTS
“How logic is divided in the PROCEDURE DIVISION”

RELATED TASKS
“Eliminating repetitive coding” on page 569

How logic is divided in the PROCEDURE DIVISION

The PROCEDURE DIVISION of a program is divided into sections and paragraphs,
which contain sentences and statements:
Section
Logical subdivision of your processing logic.
A section has a section header and is optionally followed by one or more
paragraphs.
A section can be the subject of a PERFORM statement. One type of section is
for declaratives.
Paragraph
Subdivision of a section, procedure, or program.
A paragraph has a name followed by a period and zero or more sentences.
A paragraph can be the subject of a statement.
Sentence
Series of one or more COBOL statements ending with a period.
Many structured programs do not have separate sentences. Each paragraph
can contain one sentence.
Statement
Performs a defined step of COBOL processing, such as adding two
numbers.
A statement is a valid combination of words, beginning with a COBOL
verb. Statements are imperative (indicating unconditional action),
conditional, or compiler-directing. Using explicit scope terminators instead
of periods to show the logical end of a statement is preferred.
Phrase
A subdivision of a statement.

RELATED CONCEPTS
“Compiler-directing statements” on page 20
“Scope terminators” on page 20
“Imperative statements” on page 19
“Conditional statements” on page 19
“Declaratives” on page 21

RELATED REFERENCES
PROCEDURE DIVISION structure (Enterprise COBOL Language Reference)

18 Programming Guide
Imperative statements
An imperative statement indicates an unconditional action to be taken (such as
ADD, MOVE, INVOKE, or CLOSE).

An imperative statement can be ended with an implicit or explicit scope

terminator.

A conditional statement that ends with an explicit scope terminator becomes an

imperative statement called a delimited scope statement. Only imperative statements
(or delimited scope statements) can be nested.

RELATED CONCEPTS
“Conditional statements”
“Scope terminators” on page 20

Conditional statements
A conditional statement is either a simple conditional statement (IF, EVALUATE,
SEARCH) or a conditional statement made up of an imperative statement that
includes a conditional phrase or option.

You can end a conditional statement with an implicit or explicit scope terminator.
If you end a conditional statement explicitly, it becomes a delimited scope
statement (which is an imperative statement).

You can use a delimited scope statement in these ways:

v To delimit the range of operation for a COBOL conditional statement and to
explicitly show the levels of nesting
For example, use an END-IF statement instead of a period to end the scope of an
IF statement within a nested IF.
v To code a conditional statement where the COBOL syntax calls for an imperative
statement
For example, code a conditional statement as the object of an inline PERFORM:
PERFORM UNTIL TRANSACTION-EOF
PERFORM 200-EDIT-UPDATE-TRANSACTION
IF NO-ERRORS
PERFORM 300-UPDATE-COMMUTER-RECORD
ELSE
PERFORM 400-PRINT-TRANSACTION-ERRORS
END-IF
READ UPDATE-TRANSACTION-FILE INTO WS-TRANSACTION-RECORD
AT END
SET TRANSACTION-EOF TO TRUE
END-READ
END-PERFORM

An explicit scope terminator is required for the inline PERFORM statement, but it is
not valid for the out-of-line PERFORM statement.

For additional program control, you can use the NOT phrase with conditional
statements. For example, you can provide instructions to be performed when a
particular exception does not occur, such as NOT ON SIZE ERROR. The NOT phrase
cannot be used with the ON OVERFLOW phrase of the CALL statement, but it can be
used with the ON EXCEPTION phrase.

Do not nest conditional statements. Nested statements must be imperative

statements (or delimited scope statements) and must follow the rules for
imperative statements.

Chapter 1. Structuring your program 19

 The following statements are examples of conditional statements if they are coded
without scope terminators:
v Arithmetic statement with ON SIZE ERROR
v Data-manipulation statements with ON OVERFLOW
v CALL statements with ON OVERFLOW
v I/O statements with INVALID KEY, AT END, or AT END-OF-PAGE
v RETURN with AT END

RELATED CONCEPTS
“Imperative statements” on page 19
“Scope terminators”

RELATED TASKS
“Selecting program actions” on page 75

RELATED REFERENCES
Conditional statements (Enterprise COBOL Language Reference)

Compiler-directing statements
A compiler-directing statement is not part of the program logic. A
compiler-directing statement causes the compiler to take specific action about the
program structure, COPY processing, listing control, or control flow.

RELATED REFERENCES
“Compiler-directing statements” on page 332
Compiler-directing statements (Enterprise COBOL Language Reference)

Scope terminators
Scope terminators can be explicit or implicit. Explicit scope terminators end a verb
without ending a sentence. They consist of END followed by a hyphen and the
name of the verb being terminated, such as END-IF. An implicit scope terminator is
a period (.) that ends the scope of all previous statements not yet ended.

Each of the two periods in the following program fragment ends an IF statement,
making the code equivalent to the code after it that instead uses explicit scope
terminators:
IF ITEM = “A”
DISPLAY “THE VALUE OF ITEM IS ” ITEM
ADD 1 TO TOTAL
MOVE “C” TO ITEM
DISPLAY “THE VALUE OF ITEM IS NOW ” ITEM.
IF ITEM = “B”
ADD 2 TO TOTAL.
IF ITEM = “A”
DISPLAY “THE VALUE OF ITEM IS ” ITEM
ADD 1 TO TOTAL
MOVE “C” TO ITEM
DISPLAY “THE VALUE OF ITEM IS NOW ” ITEM
END-IF
IF ITEM = “B”
ADD 2 TO TOTAL
END-IF

If you use implicit terminators, the end of statements can be unclear. As a result,
you might end statements unintentionally, changing your program’s logic. Explicit
scope terminators make a program easier to understand and prevent unintentional

20 Programming Guide
 ending of statements. For example, in the program fragment below, changing the
location of the first period in the first implicit scope example changes the meaning
of the code:
IF ITEM = “A”
DISPLAY “VALUE OF ITEM IS ” ITEM
ADD 1 TO TOTAL.
MOVE “C” TO ITEM
DISPLAY “ VALUE OF ITEM IS NOW ” ITEM
IF ITEM = “B”
ADD 2 TO TOTAL.

The MOVE statement and the DISPLAY statement after it are performed regardless of
the value of ITEM, despite what the indentation indicates, because the first period
terminates the IF statement.

For improved program clarity and to avoid unintentional ending of statements, use
explicit scope terminators, especially within paragraphs. Use implicit scope
terminators only at the end of a paragraph or the end of a program.

Be careful when coding an explicit scope terminator for an imperative statement

that is nested within a conditional statement. Ensure that the scope terminator is
paired with the statement for which it was intended. In the following example, the
scope terminator will be paired with the second READ statement, though the
programmer intended it to be paired with the first.
READ FILE1
AT END
MOVE A TO B
READ FILE2
END-READ

To ensure that the explicit scope terminator is paired with the intended statement,
the preceding example can be recoded in this way:
READ FILE1
AT END
MOVE A TO B
READ FILE2
END-READ
END-READ

RELATED CONCEPTS
“Conditional statements” on page 19
“Imperative statements” on page 19

Declaratives
Declaratives provide one or more special-purpose sections that are executed when
an exception condition occurs.

Start each declarative section with a USE statement that identifies the function of
the section; in the procedures, specify the actions to be taken when the condition
occurs.

RELATED TASKS
“Finding and handling input-output errors” on page 339

RELATED REFERENCES
Declaratives (Enterprise COBOL Language Reference)

Chapter 1. Structuring your program 21

22 Programming Guide
Chapter 2. Using data
This section is intended to help the non-COBOL programmer relate terms used in
other programming languages to COBOL terms for data. It introduces COBOL
fundamentals for:
v Variables, structures, literals, and constants
v Assigning and displaying values
v Intrinsic (built-in) functions
v Tables (arrays) and pointers

RELATED CONCEPTS
“Storage and its addressability” on page 33

RELATED TASKS
“Using variables, structures, literals, and constants”
“Assigning values to data items” on page 25
“Displaying values on a screen or in a file (DISPLAY)” on page 30
“Using intrinsic functions (built-in functions)” on page 32
“Using tables (arrays) and pointers” on page 33
Chapter 7, “Coding for run-time use of national languages” on page 103

Using variables, structures, literals, and constants

Most high-level programming languages share the concept of data being
represented as variables, structures, literals, and constants. You place all data
definitions in the DATA DIVISION of your program. The data in a COBOL program
can be alphabetic, alphanumeric, or numeric.

Variables
A variable is a data item; its value can change during a program. The values are
restricted, however, to the data type that you define when you give the variable a
name and a length. For example, if a customer name is a variable in your program,
you could code:
Data Division.
. . .
01 Customer-Name Pic X(20).
01 Original-Customer-Name Pic X(20).
. . .
Procedure Division.
. . .
Move Customer-Name to Original-Customer-Name
. . .

Data structure: data items and group items

Related data items can be parts of a hierarchical data structure. A data item that
does not have any subordinate items is called an elementary data item. A data item
that is composed of subordinated data items is called a group item. A record can be
either an elementary data item or a group of data items.

In this example, Customer-Record is a group item composed of two group items

(Customer-Name and Part-Order), each of which contains elementary data items.

© Copyright IBM Corp. 1991, 2002 23

 You can refer to the entire group item or to parts of the group item as shown in
the MOVE statements in the PROCEDURE DIVISION.
Data Division.
File Section.
FD Customer-File
Record Contains 45 Characters.
01 Customer-Record.
05 Customer-Name.
10 Last-Name Pic x(17).
10 Filler Pic x.
10 Initials Pic xx.
05 Part-Order.
10 Part-Name Pic x(15).
10 Part-Color Pic x(10).
Working-Storage Section.
01 Orig-Customer-Name.
05 Surname Pic x(17).
05 Initials Pic x(3).
01 Inventory-Part-Name Pic x(15).
. . .
Procedure Division.
. . .
Move Customer-Name to Orig-Customer-Name
Move Part-Name to Inventory-Part-Name
. . .

Literals
A literal is a character string whose value is given by the characters themselves.
When you know the value you want to use for a data item, use a literal
representation of the data value in the PROCEDURE DIVISION. You do not need to
define it or refer to a data-name. For example, you can prepare an error message
for an output file this way:
Move “Name is not valid” To Customer-Name

You can compare a data item to a certain number this way:

01 Part-number Pic 9(5).
. . .
If Part-number = 03519 then display “Part number was found”

In these examples, “Name is not valid” is an alphanumeric literal, and 03519 is a

numeric literal.

Constants
A constant is a data item that has only one value. COBOL does not define a
construct specifically for constants. However, most COBOL programmers define a
data item with an initial VALUE (as opposed to initializing a variable using the
INITIALIZE statement). For example:
Data Division.
. . .
01 Report-Header pic x(50) value “Company Sales Report”.
. . .
01 Interest pic 9v9999 value 1.0265.

Figurative constants
Certain commonly used constants and literals are provided as reserved words
called figurative constants: ZERO, SPACE, HIGH-VALUE, LOW-VALUE, QUOTE, NULL, and ALL.
Because they represent fixed values, figurative constants do not require a data
definition. For example:

24 Programming Guide
 Move Spaces To Report-Header

RELATED REFERENCES
PICTURE clause (Enterprise COBOL Language Reference)
Literals (Enterprise COBOL Language Reference)
Figurative constants (Enterprise COBOL Language Reference)

Assigning values to data items

After you have defined a data item, you can assign a value to it at any time.
Assignment takes many forms in COBOL, depending on what you want to do.

What you want to do How to do it

To assign values to a data item or large Use one of these ways:
data area v INITIALIZE statement
v MOVE statement
v STRING or UNSTRING statement
v VALUE clause (to set data items to the values
you want them to have when the program is
in its initial state)
To assign the results of arithmetic Use the COMPUTE statement.
To replace characters or groups of Use the INSPECT statement.
characters in a data item
To receive values from a file Use the READ (or READ INTO) statement.
To receive values from a screen or a file Use the ACCEPT statement.
To display values on a screen or in a file Use the DISPLAY statement.
To establish a constant1 Use the VALUE clause in the definition of the data
item.2

1. A constant is not a feature of COBOL.

2. For optimized code only: the optimizer recognizes an invariant VALUE item and treats it
as a constant.

“Examples: initializing variables”

RELATED TASKS
“Initializing a structure (INITIALIZE)” on page 27
“Assigning values to variables or structures (MOVE)” on page 27
“Joining data items (STRING)” on page 87
“Splitting data items (UNSTRING)” on page 89
“Assigning arithmetic results (MOVE or COMPUTE)” on page 28
“Tallying and replacing data items (INSPECT)” on page 95
“Assigning input from a screen or file (ACCEPT)” on page 29
“Displaying values on a screen or in a file (DISPLAY)” on page 30
Chapter 7, “Coding for run-time use of national languages” on page 103

Examples: initializing variables

Initializing a variable to blanks or zeros:
INITIALIZE identifier-1

IDENTIFIER-1 PICTURE IDENTIFIER-1 before IDENTIFIER-1 after

9(5) 12345 00000

Chapter 2. Using data 25

 IDENTIFIER-1 PICTURE IDENTIFIER-1 before IDENTIFIER-1 after
X(5) AB123 bbbbb1
99XX9 12AB3 bbbbb1
XXBX/XX ABbC/DE bbbb/bb1
**99.9CR 1234.5CR **00.0bb1
A(5) ABCDE bbbbb1
+99.99E+99 +12.34E+02 +00.00E+00

1. The symbol b represents a blank space.

Initializing a right-justified field:

01 ANJUST PIC X(8) JUSTIFIED RIGHT.
01 ALPHABETIC-1 PIC A(4) VALUE “ABCD”.
. . .
INITIALIZE ANJUST
REPLACING ALPHANUMERIC DATA BY ALPHABETIC-1

ALPHABETIC-1 ANJUST before ANJUST after

ABCD bbbbbbbb1 bbbbABCD1

1. The symbol b represents a blank space.

Initializing an alphanumeric variable:

01 ALPHANUMERIC-1 PIC X.
01 ALPHANUMERIC-3 PIC X(1) VALUE “A”.
. . .
INITIALIZE ALPHANUMERIC-1
REPLACING ALPHANUMERIC DATA BY ALPHANUMERIC-3

ALPHANUMERIC-3 ALPHANUMERIC-1 before ALPHANUMERIC-1 after

A y A

Initializing a numeric variable:

01 NUMERIC-1 PIC 9(8).
01 NUM-INT-CMPT-3 PIC 9(7) COMP VALUE 1234567.
. . .
INITIALIZE NUMERIC-1
REPLACING NUMERIC DATA BY NUM-INT-CMPT-3

NUM-INT-CMPT-3 NUMERIC-1 before NUMERIC-1 after

1234567 98765432 01234567

Initializing an edited alphanumeric variable:

01 ALPHANUM-EDIT-1 PIC XXBX/XXX.
01 ALPHANUM-EDIT-3 PIC X/BB VALUE “M/bbb”.
. . .
INITIALIZE ALPHANUM-EDIT-1
REPLACING ALPHANUMERIC-EDITED DATA BY ALPHANUM-EDIT-3

ALPHANUM-EDIT-3 ALPHANUM-EDIT-1 before ALPHANUM-EDIT-1 after

M/bb1 ABbC/DEF1 M/bb/bbb1

1. The symbol b represents a blank space.

26 Programming Guide
 RELATED TASKS
“Initializing a structure (INITIALIZE)”

Initializing a structure (INITIALIZE)

You can reset the values of all subordinate items in a group by applying the
INITIALIZE statement to the group item. However, it is inefficient to initialize an
entire group unless you really need all the items in the group initialized.

The following example shows how you can reset fields in a transaction record
produced by a program to spaces and zeros. The fields are not identical in each
record produced.
01 TRANSACTION-OUT.
05 TRANSACTION-CODE PIC X.
05 PART-NUMBER PIC 9(6).
05 TRANSACTION-QUANTITY PIC 9(5).
05 PRICE-FIELDS.
10 UNIT-PRICE PIC 9(5)V9(2).
10 DISCOUNT PIC V9(2).
10 SALES-PRICE PIC 9(5)V9(2).
. . .
INITIALIZE TRANSACTION-OUT

Record TRANSACTION-OUT before TRANSACTION-OUT after

1 R001383000240000000000000000 b0000000000000000000000000001
2 R001390000480000000000000000 b0000000000000000000000000001
3 S001410000120000000000000000 b0000000000000000000000000001
4 C001383000000000425000000000 b0000000000000000000000000001
5 C002010000000000000100000000 b0000000000000000000000000001

1. The symbol b represents a blank space.

Assigning values to variables or structures (MOVE)

Use the MOVE statement to assign values to variables or structures.

For example, the following statement assigns the contents of the variable
Customer-Name to the variable Orig-Customer-Name:
Move Customer-Name to Orig-Customer-Name

If Customer-Name were longer than Orig-Customer-Name, truncation would occur on

the right. If it were shorter, the extra character positions on the right would be
filled with spaces.

When you move a group item to another group item, be sure the subordinate data
descriptions are compatible. The compiler performs all MOVE statements regardless
of whether the items fit, even if a destructive overlap could occur at run time.

For variables that contain numbers, moves can be more complicated because there
are several ways numbers are represented. In general, the algebraic values of
numbers are moved if possible (as opposed to the digit-by-digit move performed
with character data):

Chapter 2. Using data 27

 01 Item-x Pic 999v9.
. . .
Move 3.06 to Item-x

This move would result in Item-x containing the value 3.0, represented by 0030.

You can move an alphanumeric item or an integer item to a national variable; the
item is converted. You can move a national item only to another national variable.
In either case padding or truncation might occur, and you must ensure that
truncation does not occur within a character.

The following example shows a data item in the Greek language that moves into a
national data item:
CBL CODEPAGE(00875)
. . .
01 Data-in-Unicode Pic N(100) usage national.
01 Data-in-Greek Pic X(100).
. . .
Read Greek-file into Data-in-Greek
Move Data-in-Greek to Data-in-Unicode

RELATED CONCEPTS
“Unicode and encoding of language characters” on page 105

RELATED REFERENCES
MOVE statement (Enterprise COBOL Language Reference)
“CODEPAGE” on page 294
“Converting national data” on page 107

Assigning arithmetic results (MOVE or COMPUTE)

When assigning a number to a variable, consider using the COMPUTE statement
instead of the MOVE statement. For example, the following two statements
accomplish the same thing in most cases:
Move w to z
Compute z = w

The MOVE statement carries out the assignment with truncation. You can, however,
specify the DIAGTRUNC compiler option to request that the compiler issue a warning
diagnostic for MOVE statements that might truncate numeric receivers.

When significant left-order digits would be lost in execution, the COMPUTE statement
can detect the condition and allow you to handle it.

When you use the ON SIZE ERROR phrase of the COMPUTE statement, the compiler
generates code to detect a size-overflow condition. If the condition occurs, the code
in the ON SIZE ERROR phrase is performed, and the content of z remains
unchanged. If the ON SIZE ERROR phrase is not specified, the assignment is carried
out with truncation. There is no ON SIZE ERROR support for the MOVE statement.

You can also use the COMPUTE statement to assign the result of an arithmetic
expression (or intrinsic function) to a variable. For example:
Compute z = y + (x ** 3)
Compute x = Function Max(x y z)

Results of date, time, and mathematical calculations, as well as other operations,

can be assigned to data items using Language Environment callable services. These
Language Environment services are available via a standard COBOL CALL

28 Programming Guide
 statement, and the values they return are passed in the parameters in the CALL
statement. For example, you can call the Language Environment service CEESIABS
to find the absolute value of a variable with the statement:
Call ’CEESIABS’ Using Arg, Feedback-code, Result.

As a result of this call, the variable Result is assigned to be the absolute value of
the value that is in the variable Arg; the variable Feedback-code contains the return
code indicating whether the service completed successfully. You have to define all
the variables in the Data Division using the correct descriptions, according to the
requirements of the particular callable service you are using. For the example
above, the variables could be defined like this:
77 Arg Pic s9(9) Binary.
77 Feedback-code Pic x(12) Display.
77 Result Pic s9(9) Binary.

RELATED REFERENCES
“DIAGTRUNC” on page 298
Intrinsic functions (Enterprise COBOL Language Reference)
Callable services (Language Environment Programming Reference)

Assigning input from a screen or file (ACCEPT)

One way to assign a value to a variable is to read the value from a screen or a file.
To enter data from the screen, first associate the monitor with a mnemonic-name in
the SPECIAL-NAMES paragraph. Then use ACCEPT to assign the line of input entered
at the screen to a variable.

For example:
Environment Division.
Configuration Section.
Special-Names.
Console is Names-Input.
. . .
Accept Customer-Name From Names-Input

To read from a file instead of the screen, make the following change:
v Change Console to device, where device is any valid system device (for example,
SYSIN). For example:
SYSIN is Names-Input

Note that device can be a ddname that references a hierarchical file system (HFS)
path. If this DD is not defined and your program is running in a UNIX
environment, stdin is the input source. If this DD is not defined and your
program is not running in a UNIX environment, the ACCEPT statement fails.

When you assign a value to a national data item, input data from the console is
converted from EBCDIC to Unicode representation (UTF-16), based on the value of
the CODEPAGE option. This is the only situation where conversion of national data is
done when you use the ACCEPT statement, because the input is known to be
coming from a screen.

If you want conversion done when the input data is from any other device, use the
NATIONAL-OF intrinsic function.

RELATED CONCEPTS
“Unicode and encoding of language characters” on page 105

Chapter 2. Using data 29

 RELATED REFERENCES
“CODEPAGE” on page 294
SPECIAL-NAMES paragraph (Enterprise COBOL Language Reference)

Displaying values on a screen or in a file (DISPLAY)

You can display the value of a variable on a screen or write it to a file by using the
DISPLAY statement. For example:
Display “No entry for surname ’” Customer-Name
“’ found in the file.”.

If the content of the variable Customer-Name is JOHNSON, then the statement

above displays the following message on the system logical output device:
No entry for surname ’JOHNSON’ found in the file.

To write data to a destination other than the system logical output device, use the
UPON clause with a destination other than SYSOUT. For example, the following
statement writes to the file specified in the SYSPUNCH DD statement:
Display “Hello” upon syspunch.

You can specify a file in the hierarchical file system (HFS) with this ddname. For
example, with the following definition, your DISPLAY output is written to the HFS
file /u/userid/cobol/demo.lst:
//SYSPUNCH DD PATH=’/u/userid/cobol/demo.lst’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU,
// FILEDATA=TEXT

The following statement writes to the job log or console and to the TSO screen if
you are running under TSO:
Display “Hello” upon console.

When you display the value of a national data item to the console, it is converted
from Unicode representation (UTF-16) to EBCDIC, based on the value of the
CODEPAGE option. This is the only situation where conversion of national data is
done when you use the DISPLAY statement, because the output is known to be
directed to a screen.

If you want a national data item to be converted when you direct output to a
different device, use the DISPLAY-OF intrinsic function, such as in this example:
01 Data-in-Unicode pic N(10) usage national.
. . .
Display function Display-of(Data-in-Unicode, 00037)

Displaying data on the system logical output device

To write data to the system logical output device, either omit the UPON clause or
use the UPON clause with destination SYSOUT. For example:
Display “Hello” upon sysout.

The output is directed to the ddname that you specify in the OUTDD compiler
option. You can specify a file in the hierarchical file system (HFS) with this
ddname.

If the OUTDD ddname is not allocated and you are not running in a UNIX
environment, a default DD of SYSOUT=* is allocated.

30 Programming Guide
Other documents randomly have
different content
THE FULL PROJECT GUTENBERG LICENSE
 PLEASE READ THIS BEFORE YOU DISTRIBUTE OR USE THIS WORK

To protect the Project Gutenberg™ mission of promoting the free

distribution of electronic works, by using or distributing this work (or
any other work associated in any way with the phrase “Project
Gutenberg”), you agree to comply with all the terms of the Full
Project Gutenberg™ License available with this file or online at
www.gutenberg.org/license.

Section 1. General Terms of Use and

Redistributing Project Gutenberg™
electronic works
1.A. By reading or using any part of this Project Gutenberg™
electronic work, you indicate that you have read, understand, agree
to and accept all the terms of this license and intellectual property
(trademark/copyright) agreement. If you do not agree to abide by all
the terms of this agreement, you must cease using and return or
destroy all copies of Project Gutenberg™ electronic works in your
possession. If you paid a fee for obtaining a copy of or access to a
Project Gutenberg™ electronic work and you do not agree to be
bound by the terms of this agreement, you may obtain a refund
from the person or entity to whom you paid the fee as set forth in
paragraph 1.E.8.

1.B. “Project Gutenberg” is a registered trademark. It may only be

used on or associated in any way with an electronic work by people
who agree to be bound by the terms of this agreement. There are a
few things that you can do with most Project Gutenberg™ electronic
works even without complying with the full terms of this agreement.
See paragraph 1.C below. There are a lot of things you can do with
Project Gutenberg™ electronic works if you follow the terms of this
agreement and help preserve free future access to Project
Gutenberg™ electronic works. See paragraph 1.E below.
1.C. The Project Gutenberg Literary Archive Foundation (“the
Foundation” or PGLAF), owns a compilation copyright in the
collection of Project Gutenberg™ electronic works. Nearly all the
individual works in the collection are in the public domain in the
United States. If an individual work is unprotected by copyright law
in the United States and you are located in the United States, we do
not claim a right to prevent you from copying, distributing,
performing, displaying or creating derivative works based on the
work as long as all references to Project Gutenberg are removed. Of
course, we hope that you will support the Project Gutenberg™
mission of promoting free access to electronic works by freely
sharing Project Gutenberg™ works in compliance with the terms of
this agreement for keeping the Project Gutenberg™ name associated
with the work. You can easily comply with the terms of this
agreement by keeping this work in the same format with its attached
full Project Gutenberg™ License when you share it without charge
with others.

1.D. The copyright laws of the place where you are located also
govern what you can do with this work. Copyright laws in most
countries are in a constant state of change. If you are outside the
United States, check the laws of your country in addition to the
terms of this agreement before downloading, copying, displaying,
performing, distributing or creating derivative works based on this
work or any other Project Gutenberg™ work. The Foundation makes
no representations concerning the copyright status of any work in
any country other than the United States.

1.E. Unless you have removed all references to Project Gutenberg:

1.E.1. The following sentence, with active links to, or other

immediate access to, the full Project Gutenberg™ License must
appear prominently whenever any copy of a Project Gutenberg™
work (any work on which the phrase “Project Gutenberg” appears,
or with which the phrase “Project Gutenberg” is associated) is
accessed, displayed, performed, viewed, copied or distributed:
 This eBook is for the use of anyone anywhere in the United
States and most other parts of the world at no cost and with
almost no restrictions whatsoever. You may copy it, give it away
or re-use it under the terms of the Project Gutenberg License
included with this eBook or online at www.gutenberg.org. If you
are not located in the United States, you will have to check the
laws of the country where you are located before using this
eBook.

1.E.2. If an individual Project Gutenberg™ electronic work is derived

from texts not protected by U.S. copyright law (does not contain a
notice indicating that it is posted with permission of the copyright
holder), the work can be copied and distributed to anyone in the
United States without paying any fees or charges. If you are
redistributing or providing access to a work with the phrase “Project
Gutenberg” associated with or appearing on the work, you must
comply either with the requirements of paragraphs 1.E.1 through
1.E.7 or obtain permission for the use of the work and the Project
Gutenberg™ trademark as set forth in paragraphs 1.E.8 or 1.E.9.

1.E.3. If an individual Project Gutenberg™ electronic work is posted

with the permission of the copyright holder, your use and distribution
must comply with both paragraphs 1.E.1 through 1.E.7 and any
additional terms imposed by the copyright holder. Additional terms
will be linked to the Project Gutenberg™ License for all works posted
with the permission of the copyright holder found at the beginning
of this work.

1.E.4. Do not unlink or detach or remove the full Project

Gutenberg™ License terms from this work, or any files containing a
part of this work or any other work associated with Project
Gutenberg™.

1.E.5. Do not copy, display, perform, distribute or redistribute this

electronic work, or any part of this electronic work, without
prominently displaying the sentence set forth in paragraph 1.E.1
with active links or immediate access to the full terms of the Project
Gutenberg™ License.

1.E.6. You may convert to and distribute this work in any binary,
compressed, marked up, nonproprietary or proprietary form,
including any word processing or hypertext form. However, if you
provide access to or distribute copies of a Project Gutenberg™ work
in a format other than “Plain Vanilla ASCII” or other format used in
the official version posted on the official Project Gutenberg™ website
(www.gutenberg.org), you must, at no additional cost, fee or
expense to the user, provide a copy, a means of exporting a copy, or
a means of obtaining a copy upon request, of the work in its original
“Plain Vanilla ASCII” or other form. Any alternate format must
include the full Project Gutenberg™ License as specified in
paragraph 1.E.1.

1.E.7. Do not charge a fee for access to, viewing, displaying,

performing, copying or distributing any Project Gutenberg™ works
unless you comply with paragraph 1.E.8 or 1.E.9.

1.E.8. You may charge a reasonable fee for copies of or providing

access to or distributing Project Gutenberg™ electronic works
provided that:

• You pay a royalty fee of 20% of the gross profits you derive
from the use of Project Gutenberg™ works calculated using the
method you already use to calculate your applicable taxes. The
fee is owed to the owner of the Project Gutenberg™ trademark,
but he has agreed to donate royalties under this paragraph to
the Project Gutenberg Literary Archive Foundation. Royalty
payments must be paid within 60 days following each date on
which you prepare (or are legally required to prepare) your
periodic tax returns. Royalty payments should be clearly marked
as such and sent to the Project Gutenberg Literary Archive
Foundation at the address specified in Section 4, “Information
 about donations to the Project Gutenberg Literary Archive
Foundation.”

• You provide a full refund of any money paid by a user who

notifies you in writing (or by e-mail) within 30 days of receipt
that s/he does not agree to the terms of the full Project
Gutenberg™ License. You must require such a user to return or
destroy all copies of the works possessed in a physical medium
and discontinue all use of and all access to other copies of
Project Gutenberg™ works.

• You provide, in accordance with paragraph 1.F.3, a full refund of

any money paid for a work or a replacement copy, if a defect in
the electronic work is discovered and reported to you within 90
days of receipt of the work.

• You comply with all other terms of this agreement for free
distribution of Project Gutenberg™ works.

1.E.9. If you wish to charge a fee or distribute a Project Gutenberg™

electronic work or group of works on different terms than are set
forth in this agreement, you must obtain permission in writing from
the Project Gutenberg Literary Archive Foundation, the manager of
the Project Gutenberg™ trademark. Contact the Foundation as set
forth in Section 3 below.

1.F.

1.F.1. Project Gutenberg volunteers and employees expend

considerable effort to identify, do copyright research on, transcribe
and proofread works not protected by U.S. copyright law in creating
the Project Gutenberg™ collection. Despite these efforts, Project
Gutenberg™ electronic works, and the medium on which they may
be stored, may contain “Defects,” such as, but not limited to,
incomplete, inaccurate or corrupt data, transcription errors, a
copyright or other intellectual property infringement, a defective or
damaged disk or other medium, a computer virus, or computer
codes that damage or cannot be read by your equipment.

1.F.2. LIMITED WARRANTY, DISCLAIMER OF DAMAGES - Except for

the “Right of Replacement or Refund” described in paragraph 1.F.3,
the Project Gutenberg Literary Archive Foundation, the owner of the
Project Gutenberg™ trademark, and any other party distributing a
Project Gutenberg™ electronic work under this agreement, disclaim
all liability to you for damages, costs and expenses, including legal
fees. YOU AGREE THAT YOU HAVE NO REMEDIES FOR
NEGLIGENCE, STRICT LIABILITY, BREACH OF WARRANTY OR
BREACH OF CONTRACT EXCEPT THOSE PROVIDED IN PARAGRAPH
1.F.3. YOU AGREE THAT THE FOUNDATION, THE TRADEMARK
OWNER, AND ANY DISTRIBUTOR UNDER THIS AGREEMENT WILL
NOT BE LIABLE TO YOU FOR ACTUAL, DIRECT, INDIRECT,
CONSEQUENTIAL, PUNITIVE OR INCIDENTAL DAMAGES EVEN IF
YOU GIVE NOTICE OF THE POSSIBILITY OF SUCH DAMAGE.

1.F.3. LIMITED RIGHT OF REPLACEMENT OR REFUND - If you

discover a defect in this electronic work within 90 days of receiving
it, you can receive a refund of the money (if any) you paid for it by
sending a written explanation to the person you received the work
from. If you received the work on a physical medium, you must
return the medium with your written explanation. The person or
entity that provided you with the defective work may elect to provide
a replacement copy in lieu of a refund. If you received the work
electronically, the person or entity providing it to you may choose to
give you a second opportunity to receive the work electronically in
lieu of a refund. If the second copy is also defective, you may
demand a refund in writing without further opportunities to fix the
problem.

1.F.4. Except for the limited right of replacement or refund set forth
in paragraph 1.F.3, this work is provided to you ‘AS-IS’, WITH NO
OTHER WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PURPOSE.

1.F.5. Some states do not allow disclaimers of certain implied

warranties or the exclusion or limitation of certain types of damages.
If any disclaimer or limitation set forth in this agreement violates the
law of the state applicable to this agreement, the agreement shall be
interpreted to make the maximum disclaimer or limitation permitted
by the applicable state law. The invalidity or unenforceability of any
provision of this agreement shall not void the remaining provisions.

1.F.6. INDEMNITY - You agree to indemnify and hold the Foundation,

the trademark owner, any agent or employee of the Foundation,
anyone providing copies of Project Gutenberg™ electronic works in
accordance with this agreement, and any volunteers associated with
the production, promotion and distribution of Project Gutenberg™
electronic works, harmless from all liability, costs and expenses,
including legal fees, that arise directly or indirectly from any of the
following which you do or cause to occur: (a) distribution of this or
any Project Gutenberg™ work, (b) alteration, modification, or
additions or deletions to any Project Gutenberg™ work, and (c) any
Defect you cause.

Section 2. Information about the Mission

of Project Gutenberg™
Project Gutenberg™ is synonymous with the free distribution of
electronic works in formats readable by the widest variety of
computers including obsolete, old, middle-aged and new computers.
It exists because of the efforts of hundreds of volunteers and
donations from people in all walks of life.

Volunteers and financial support to provide volunteers with the

assistance they need are critical to reaching Project Gutenberg™’s
goals and ensuring that the Project Gutenberg™ collection will
remain freely available for generations to come. In 2001, the Project
Gutenberg Literary Archive Foundation was created to provide a
secure and permanent future for Project Gutenberg™ and future
generations. To learn more about the Project Gutenberg Literary
Archive Foundation and how your efforts and donations can help,
see Sections 3 and 4 and the Foundation information page at
www.gutenberg.org.

Section 3. Information about the Project

Gutenberg Literary Archive Foundation
The Project Gutenberg Literary Archive Foundation is a non-profit
501(c)(3) educational corporation organized under the laws of the
state of Mississippi and granted tax exempt status by the Internal
Revenue Service. The Foundation’s EIN or federal tax identification
number is 64-6221541. Contributions to the Project Gutenberg
Literary Archive Foundation are tax deductible to the full extent
permitted by U.S. federal laws and your state’s laws.

The Foundation’s business office is located at 809 North 1500 West,

Salt Lake City, UT 84116, (801) 596-1887. Email contact links and up
to date contact information can be found at the Foundation’s website
and official page at www.gutenberg.org/contact

Section 4. Information about Donations to

the Project Gutenberg Literary Archive
Foundation
Project Gutenberg™ depends upon and cannot survive without
widespread public support and donations to carry out its mission of
increasing the number of public domain and licensed works that can
be freely distributed in machine-readable form accessible by the
widest array of equipment including outdated equipment. Many
small donations ($1 to $5,000) are particularly important to
maintaining tax exempt status with the IRS.

The Foundation is committed to complying with the laws regulating

charities and charitable donations in all 50 states of the United
States. Compliance requirements are not uniform and it takes a
considerable effort, much paperwork and many fees to meet and
keep up with these requirements. We do not solicit donations in
locations where we have not received written confirmation of
compliance. To SEND DONATIONS or determine the status of
compliance for any particular state visit www.gutenberg.org/donate.

While we cannot and do not solicit contributions from states where

we have not met the solicitation requirements, we know of no
prohibition against accepting unsolicited donations from donors in
such states who approach us with offers to donate.

International donations are gratefully accepted, but we cannot make

any statements concerning tax treatment of donations received from
outside the United States. U.S. laws alone swamp our small staff.

Please check the Project Gutenberg web pages for current donation
methods and addresses. Donations are accepted in a number of
other ways including checks, online payments and credit card
donations. To donate, please visit: www.gutenberg.org/donate.

Section 5. General Information About

Project Gutenberg™ electronic works
Professor Michael S. Hart was the originator of the Project
Gutenberg™ concept of a library of electronic works that could be
freely shared with anyone. For forty years, he produced and
distributed Project Gutenberg™ eBooks with only a loose network of
volunteer support.
Project Gutenberg™ eBooks are often created from several printed
editions, all of which are confirmed as not protected by copyright in
the U.S. unless a copyright notice is included. Thus, we do not
necessarily keep eBooks in compliance with any particular paper
edition.

Most people start at our website which has the main PG search
facility: www.gutenberg.org.

This website includes information about Project Gutenberg™,

including how to make donations to the Project Gutenberg Literary
Archive Foundation, how to help produce our new eBooks, and how
to subscribe to our email newsletter to hear about new eBooks.
Welcome to our website – the perfect destination for book lovers and
knowledge seekers. We believe that every book holds a new world,
offering opportunities for learning, discovery, and personal growth.
That’s why we are dedicated to bringing you a diverse collection of
books, ranging from classic literature and specialized publications to
self-development guides and children's books.

More than just a book-buying platform, we strive to be a bridge

connecting you with timeless cultural and intellectual values. With an
elegant, user-friendly interface and a smart search system, you can
quickly find the books that best suit your interests. Additionally,
our special promotions and home delivery services help you save time
and fully enjoy the joy of reading.

Join us on a journey of knowledge exploration, passion nurturing, and

personal growth every day!

ebookbell.com