COBOL

Download as pdf or txt
Download as pdf or txt
You are on page 1of 425

Note!

Before using this information and the product it supports, be sure to read the general information under
“Notices” on page ix.

First Edition (June 1994)

This edition applies to the IBM* ILE* COBOL/400* licensed program (Program 5763-CB1), Version 3 Release 0 Modifi-
cation 5, and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you
are using the proper edition for the level of the product.

Order publications through your IBM representative or the IBM branch serving your locality. Publications are not
stocked at the address given below.

A form for readers’ comments is provided at the back of this publication. If the form has been removed, you may
address your comments to:

IBM Canada Ltd. Laboratory


Information Development
2G/345/1150/TOR
1150 Eglinton Avenue East
North York, Ontario, Canada. M3C 1H7

You can also send your comments by facsimile (attention: RCF Coordinator), or you can send your comments elec-
tronically to IBM. See “Communicating Your Comments to IBM” for a description of the methods. This page imme-
diately precedes the Readers’ Comment Form at the back of this publication.

When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way
it believes appropriate without incurring any obligation to you.

 Copyright International Business Machines Corporation 1994. All rights reserved.


Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is
subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
IBM is a registered trademark of International Business Machines Corporation, Armonk, N.Y.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Programming Interface Information . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Trademarks and Service Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . x

About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi


Who Should Use This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Industry Standards Used in Compiler Design . . . . . . . . . . . . . . . . . . . . xiii

Chapter 1. An Introduction to the COBOL/400 Programming Language . . 1


Extensions to the ANSI Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Features of the COBOL/400 Compiler . . . . . . . . . . . . . . . . . . . . . . . . . 2
Using COBOL/400 Syntax Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Reading the Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Reading IBM Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CL Entry Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
An Overview of COBOL/400 Programming . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 2. Entering Your Source Program on the AS/400 System . . . . . . 9


Designing Your COBOL/400 Program . . . . . . . . . . . . . . . . . . . . . . . . . 9
Entering Source Using SEU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 3. Compiling a COBOL/400 Program . . . . . . . . . . . . . . . . . 15


Using the Create COBOL Program (CRTCBLPGM) Command . . . . . . . . . 15
Using the CRTCBLPGM Prompt Displays . . . . . . . . . . . . . . . . . . . . 16
Entering CRTCBLPGM from the Command Line . . . . . . . . . . . . . . . . 28
Entering CRTCBLPGM from a CL Program . . . . . . . . . . . . . . . . . . . 28
Syntax of the CRTCBLPGM Command . . . . . . . . . . . . . . . . . . . . . 29
Compiling Your Source Program For the Previous Release . . . . . . . . . . . 31
Using the PROCESS Statement to Specify Compiler Options . . . . . . . . . . 32
Understanding Compiler Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Specifying the Format of Your Listing . . . . . . . . . . . . . . . . . . . . . . 38
Browsing Your Compiler Listing Using SEU . . . . . . . . . . . . . . . . . . . 39
A Sample Program and Listing . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 4. Running Your COBOL Program . . . . . . . . . . . . . . . . . . . 51


Replying to Run-Time Inquiry Messages . . . . . . . . . . . . . . . . . . . . . 52

Chapter 5. Debugging Your Program . . . . . . . . . . . . . . . . . . . . . . 55


Avoiding Common Coding Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Using Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Example of a Program Using Breakpoints . . . . . . . . . . . . . . . . . . . . 57
Changing Program Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Considerations for Using Breakpoints . . . . . . . . . . . . . . . . . . . . . . 63
Using a Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Example of Using a Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Considerations for Using a Trace . . . . . . . . . . . . . . . . . . . . . . . . . 66
Using a Debug Run-Time Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Using a COBOL Formatted Dump . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 6. COBOL/400 Exception and Error Handling . . . . . . . . . . . . 69

 Copyright IBM Corp. 1994 iii


Standard Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Error Handling Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Using Error-Handling Application Programming Interfaces (APIs) . . . . . . 70
Internal and External File Status . . . . . . . . . . . . . . . . . . . . . . . . . 70
General Error Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
How File Status is Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Message Monitor Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Ending of a COBOL Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Standard and Nonstandard Error Handling Models . . . . . . . . . . . . . . . 76
Effects of *STDERR and *NOSTDERR on File Status . . . . . . . . . . . . . 79
Processing of I/O Verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Common Exceptions and Some of Their Causes . . . . . . . . . . . . . . . . . 81
Recovery After a Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Chapter 7. File and Data Management . . . . . . . . . . . . . . . . . . . . . . 89


Device Independence and Device Dependence . . . . . . . . . . . . . . . . . . 89
Spooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Output Spool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Input Spool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
System Override Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
File and Record Locking by COBOL . . . . . . . . . . . . . . . . . . . . . . . . . 93
Locking and Releasing Records . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Sharing an Open Data Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Commitment Control Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 94
Unblocking Input Records and Blocking Output Records . . . . . . . . . . . . 102
File Status and Feedback Areas . . . . . . . . . . . . . . . . . . . . . . . . . . 103
File Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Program-Described Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Externally Described Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Data Description Specifications (DDS) . . . . . . . . . . . . . . . . . . . . . 106
Format 2 COPY Statement (DD, DDR, DDS, or DDSR Option) . . . . . . . . 112
Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Data Structures Generated . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Key Generation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Declaring Data Items Using CVTOPT Data Types . . . . . . . . . . . . . . . . 130
DBCS-Graphic Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Variable-length DBCS-Graphic Fields . . . . . . . . . . . . . . . . . . . . . 134
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Cross-system Data Considerations . . . . . . . . . . . . . . . . . . . . . . . . 137

Chapter 8. Transaction Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 139


Program-Described Transaction Files . . . . . . . . . . . . . . . . . . . . . . . 139
Externally Described Transaction Files . . . . . . . . . . . . . . . . . . . . . . 139
The Format 2 COPY Statement . . . . . . . . . . . . . . . . . . . . . . . . . 139
Data Description Specifications . . . . . . . . . . . . . . . . . . . . . . . . . 140
Processing an Externally Described Transaction File . . . . . . . . . . . . 142
Using Indicators with Transaction Files . . . . . . . . . . . . . . . . . . . . . . 142
Indicators in a Separate Indicator Area . . . . . . . . . . . . . . . . . . . . . 143
Indicators in the Record Area . . . . . . . . . . . . . . . . . . . . . . . . . . 143
ASSIGN Clause and the Separate Indicator Area Attribute . . . . . . . . . 143
Data Description Entry–Boolean Data . . . . . . . . . . . . . . . . . . . . . 144
INDICATORS Phrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Indicators in a Separate Indicator Area . . . . . . . . . . . . . . . . . . . . . 145

iv COBOL/400 User’s Guide


Indicators in the Record Area . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Indicators Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Subfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Use of Subfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Multiple Device Files and Single Device Files . . . . . . . . . . . . . . . . . 162
Environment Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
File-Control Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Data Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
File Description Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Boolean Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Procedure Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Procedure Division Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . 176
ACCEPT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
ACQUIRE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
CLOSE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
DROP Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
OPEN Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Common Processing Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . 181
READ Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
REWRITE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
WRITE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
USE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Examples of Work Station Programs . . . . . . . . . . . . . . . . . . . . . . . 200
Basic Inquiry Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Order Inquiry Programs Using Subfiles . . . . . . . . . . . . . . . . . . . . . 206
A Payment Update Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Chapter 9. Printer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233


SPECIAL-NAMES Paragraph and the ADVANCING Phrase . . . . . . . . 233
LINAGE Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
FORMATFILE Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

Chapter 10. DISK and DATABASE Files . . . . . . . . . . . . . . . . . . . . 241


DATABASE versus DISK Files . . . . . . . . . . . . . . . . . . . . . . . . . 241
Processing Methods for DISK and DATABASE Files . . . . . . . . . . . . . 241
COBOL Indexed Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Referring to a Partial Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Logical File Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
COBOL Relative Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
COBOL Sequential Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
COBOL File Organization and AS/400 File Access Path Considerations . 250
File Processing Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Descending File Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Chapter 11. COBOL/400 Programming Considerations . . . . . . . . . . 255


Issuing a CL Command from a COBOL Program . . . . . . . . . . . . . . . . 255
Using the CORRESPONDING Phrase . . . . . . . . . . . . . . . . . . . . . . 256
LIKE Clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Reference Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Reference Modification with Variable-length Tables . . . . . . . . . . . . . 263
Reference Modification Using Data Names . . . . . . . . . . . . . . . . . . 264
Reference Modification with Subscripting . . . . . . . . . . . . . . . . . . . 265
De-editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
De-editing Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Contents v
Handling Data Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
PICTURE Clauses for Numeric Items . . . . . . . . . . . . . . . . . . . . . 268
Eight-Byte Binary Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Segmentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Calling a COBOL Program from a Non-COBOL Program . . . . . . . . . . 268
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
*NORANGE Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
*DUPKEYCHK Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Relative Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Commitment Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Reading without Record Locks . . . . . . . . . . . . . . . . . . . . . . . . . 270
Initializing Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Blocking Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Program Loops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Tracing a Loop in a Program . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Errors That Can Cause a Loop . . . . . . . . . . . . . . . . . . . . . . . . . 271

Chapter 12. Communicating Between Programs . . . . . . . . . . . . . . 273


Transferring Control to Another Program . . . . . . . . . . . . . . . . . . . . . 273
Main Programs and Subprograms . . . . . . . . . . . . . . . . . . . . . . . 273
Returning Control from a Called Program . . . . . . . . . . . . . . . . . . . . . 274
Initialization of Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Calling Another Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Passing Data Using BY REFERENCE or BY CONTENT . . . . . . . . . . 279
In the Linkage Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Grouping Data to be Passed . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Call by Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Using Pointers in a COBOL/400 Program . . . . . . . . . . . . . . . . . . . . . 282
Defining Pointers and Pointer Alignment . . . . . . . . . . . . . . . . . . . . 283
Pointers and the REDEFINES Clause . . . . . . . . . . . . . . . . . . . . . 284
Reading and Writing Pointers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Initializing Pointers Using the NULL Figurative Constant . . . . . . . . . . . . 286
LENGTH OF Special Register . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Setting the Address of Linkage Items . . . . . . . . . . . . . . . . . . . . . . . 287
Using ADDRESS OF and the ADDRESS OF Special Register . . . . . . . 287
Using Pointers in a MOVE Statement . . . . . . . . . . . . . . . . . . . . . . . 287
Using Pointers in a CALL Statement . . . . . . . . . . . . . . . . . . . . . . . . 289
Using Pointers and APIs to Access User Spaces . . . . . . . . . . . . . . . . 291
Processing a Chained List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Data Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Local Data Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Program Initialization Parameters (PIP) Data Area . . . . . . . . . . . . . . 306
File Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Appendix A. Segmentation Feature . . . . . . . . . . . . . . . . . . . . . . 309


Segmentation Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Program Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Segmentation Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Segmentation Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
COBOL Source Program Considerations . . . . . . . . . . . . . . . . . . . 310
Segmentation–Special Considerations . . . . . . . . . . . . . . . . . . . . . 312

vi COBOL/400 User’s Guide


Appendix B. Debugging Features . . . . . . . . . . . . . . . . . . . . . . . . 313
COBOL Source Language Debugging . . . . . . . . . . . . . . . . . . . . . . . 313
Compile-Time Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Run-Time Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
USE FOR DEBUGGING Declarative . . . . . . . . . . . . . . . . . . . . . . 316
DEBUG-ITEM Special Register . . . . . . . . . . . . . . . . . . . . . . . . . 319
Debugging Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Appendix C. Level of Language Support . . . . . . . . . . . . . . . . . . . 323


ANSI X3.23-1985 COBOL Standard . . . . . . . . . . . . . . . . . . . . . . 323
COBOL/400 Level of Language Support . . . . . . . . . . . . . . . . . . . . 323
SAA Common Programming Interface (CPI) Support . . . . . . . . . . . . 325

Appendix D. COBOL/400 Messages, the FIPS Flagger, and SAA Flagging 327
COBOL/400 Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Interactive Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Compilation Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Responding to Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
COBOL Message Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
The Federal Information Processing Standard (FIPS) Flagger . . . . . . . . . 331
SAA Flagging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Appendix E. Differences Between ANSI 74 COBOL and ANSI 85 COBOL 335


Migrating ANSI 74 COBOL Programs to ANSI 85 COBOL . . . . . . . . . . . 335

Appendix F. Supporting International Languages with Double-Byte


Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Using DBCS Characters in Literals . . . . . . . . . . . . . . . . . . . . . . . 337
Identification Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Environment Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Data Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Procedure Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
SORT/MERGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Compiler-Directing Statements . . . . . . . . . . . . . . . . . . . . . . . . . 348
Communications between Programs . . . . . . . . . . . . . . . . . . . . . . 349
FIPS Flagger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
COBOL Program Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Appendix G. AS/400 File Processing Examples . . . . . . . . . . . . . . . 351


Sequential File Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Sequential File Updating and Extension . . . . . . . . . . . . . . . . . . . . 353
Indexed File Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Indexed File Updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Relative File Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Relative File Updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Relative File Retrieval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Sorting and Merging Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Appendix H. Example of a COBOL Formatted Dump . . . . . . . . . . . . 371

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

Glossary of Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385

Contents vii
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

viii COBOL/400 User’s Guide


Notices
References in this publication to IBM products, programs, or services do not imply
that IBM intends to make these available in all countries in which IBM operates.
Any reference to an IBM licensed program in this publication is not intended to
state or imply that only IBM’s licensed program may be used. Any functionally
equivalent product, program or service that does not infringe any of IBM’s intellec-
tual property rights may be used instead of the IBM product, program, or service.
| Evaluation and verification of operation in conjunction with other products, except
| those expressly designated by IBM, is the user’s responsibility.

IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
| these patents. You can send license inquiries, in writing, to the IBM Director of
| Licensing, IBM Corporation, 208 Harbor Drive, Stamford, Connecticut, USA
| 06904-2501

Important changes or additions to the text are indicated by a vertical line (|) to the
left of the change or addition.

This publication contains examples of data and reports used in daily business oper-
ations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

Programming Interface Information


This publication is intended to help the customer write COBOL/400 programs.

This publication also documents General-Use Programming Interface and Associ-


ated Guidance Information.

General-Use programming interfaces allow the customer to write programs that


obtain the services of the COBOL/400 compiler.

General-Use Programming Interface and Associated Guidance Information is identi-


fied where it occurs, either by an introductory statement to a chapter or section or
by the following marking:

General-Use Programming Interface

General-Use Programming Interface and Associated Guidance Information...

End of General-Use Programming Interface

 Copyright IBM Corp. 1994 ix


Trademarks and Service Marks
The following terms, denoted by an asterisk (*) in this publication, are trademarks of
the IBM Corporation in the United States and/or other countries:

Application System/400 AS/400 CICS/400


| COBOL/400 IBM ILE
Operating System/2 Operating System/400 OS/2
OS/400 RPG/400 SAA
SQL/400 System/370 Systems Application
Architecture
400

x COBOL/400 User’s Guide


About This Manual
This manual provides information an application programmer needs to write,
compile, test, debug, and run COBOL/400* programs on the IBM* Application
System/400* (AS/400*) system.

This manual refers to other IBM publications. These publications are listed in the
“Bibliography” on page 383 with their full title and base order number. When they
are referred to in text, a shortened version of the title is used.

Who Should Use This Manual


This manual is intended for programmers who have some experience with the
COBOL programming language and for the operators who run the programs. It is a
guide to programming in the COBOL/400 language for users of the AS/400 system.
As a user, you should have a basic understanding of data processing concepts, the
COBOL programming language, and the IBM Operating System/400* (OS/400*)
operating system.

Using this manual, you will be able to:


Ÿ Design COBOL/400 programs
Ÿ Code COBOL/400 programs
Ÿ Enter, compile, and run COBOL/400 programs
Ÿ Test and debug COBOL/400 programs
Ÿ Study coded COBOL/400 examples.
Note: You should be familiar with Chapters 1 through 4 of this manual before pro-
ceeding to the other chapters.

Use this manual with the COBOL/400 Reference, SC09-1813, which describes
each component and feature of the COBOL/400 language. The COBOL/400 User’s
Guide, SC09-1812 and the COBOL/400 Reference together describe the
COBOL/400 compiler and language.

For information about the complete library of AS/400 documents, consult the
Publications Guide, GC41-9678, which contains a brief description of the contents
of each AS/400 manual.

Before you use this manual, you should be familiar with the following information:
Ÿ How to use the controls and indicators on your display and how to use the keys
on your keyboard, such as:
– Cursor movement keys
– Function keys
– Field exit keys
– Insert and Delete keys
– Error Reset key.
For information about your display station, refer to:
– New User’s Guide, SC41-8211.

 Copyright IBM Corp. 1994 xi


Ÿ How to operate your display station when it is linked to the IBM AS/400 system
and running AS/400 software. This means knowing how to use the OS/400
operating system and its Control Language (CL) to do such things as:
– Sign on and sign off the display station
– Interact with displays
– Use Help
– Enter CL commands
– Use Application Development Tools
– Respond to messages
– Perform file management.
Ÿ The Programming: Control Language Programmer’s Guide, SC41-8077 which
contains the basic concepts of OS/400 CL functions.
To find out more about the operating system and its control language, refer to
these IBM publications:
– Programming: Control Language Reference, SC41-0030 (a three-volume
manual).
– Programming: Work Management Guide, SC41-8078
– Advanced Backup and Recovery Guide, SC41-8079
Ÿ The Data Management Guide, SC41-9658 which provides information on using
data management support to allow an application to work with files.
The manual includes information on:
– Fundamental structure and concepts of data management support on the
system
– Data management support for display stations, printers, tapes, and
diskettes, as well as spooling support
– Overrides and file redirection (temporarily making changes to files when an
application is run)
– Copying files by using system commands to copy data from one place to
another
– Tailoring a system using double-byte data.
Ÿ How to use the following Application Development Tools:
– The Screen Design Aid (SDA) is used to design and code displays. Infor-
mation about this product is contained in Application Development Tools:
Screen Design Aid User’s Guide and Reference, SC09-1340.
– The Source Entry Utility (SEU) is a full-display editor you can use to enter
and update your source members. Information about this product is con-
tained in Application Development Tools: Source Entry Utility User’s Guide
and Reference, SC09-1338.
Ÿ The Structured Query Language (SQL) allows you to insert SQL statements
into COBOL/400 programs. Information about this product is contained in
Systems Application Architecture* Structured Query Language/400 Reference,
SC41-9608 and in Systems Application Architecture* Structured Query
Language/400 Programmer’s Guide, SC41-9609
Ÿ The Customer Information Control System/400 (CICS/400*) licensed program
allows you to enter transactions at remote work stations, and process them
concurrently with user-written application programs. The licensed program

xii COBOL/400 User’s Guide


includes functions for building, using, and maintaining databases, and for com-
municating with CICS on other operating systems.
| Information about using this product for application programming is contained in
| the CICS/400 Application Programming Guide. SC33-0822.

Industry Standards Used in Compiler Design


The COBOL/400 compiler is designed according to the following industry standards
as understood and interpreted by IBM, as of September, 1987:
Ÿ The intermediate subset of the American National Standards Institute (ANSI
X3.23-1985) standard.
Ÿ The International Standards Organization (ISO) 1989-1985.
Ÿ The March 1986 Federal Information Processing Standards Publication (FIPS
PUB 21-2) intermediate level. Additional support is provided for many high-
level features.

Portions of this manual are copied from American National Standard Programming
Language COBOL, ANSI X3.23-1985, ISO 1989-1985 and reproduced with permis-
sion from American National Standard Programming Language COBOL, ANSI
X3.23-1985, ISO 1989-1985 (copyright 1985 by the American National Standards
Institute), copies of which you can purchase from the American National Standard
Institute at 1430 Broadway, New York, New York, 10018.

The COBOL language is maintained by the Conference On DAta SYstems Lan-


guages (CODASYL).

About This Manual xiii


xiv COBOL/400 User’s Guide
Chapter 1. An Introduction to the COBOL/400 Programming
Language
COmmon Business Oriented Language (COBOL) is a programming language that
resembles English. As its name suggests, COBOL is especially efficient for proc-
essing business problems. It emphasizes describing and handling of data items
and of input/output records; thus, it is well adapted for managing large files of data.

The COBOL/400 language delivers many elements of IBM Systems Application


Architecture* (SAA*) Common Programming Interface (CPI) COBOL, and is the
implementing product on the AS/400 system.

The COBOL/400 Compiler and Library is an IBM licensed program that accepts and
runs COBOL programs that follow the ANSI X3.23-1985 (American National
Standard Programming Language COBOL, ANSI X3.23-1985, ISO 1989-1985)
standard. ANSI is an organization consisting of producers, consumers, and general
interest groups, that establishes the procedures by which accredited organizations
create and maintain voluntary industry standards in the United States.

Extensions to the ANSI Standard


To help you use COBOL on the AS/400 system, the COBOL/400 licensed program
also includes a number of IBM extensions to the ANSI X3.23-1985 standard. Sig-
nificant extensions include:
Ÿ TRANSACTION I/O: You can send or receive records from a work station.
Ÿ COPY: You can use externally described files.
Ÿ DATABASE I/O: You can use standard COBOL Environment and Data Divi-
sion entries to specify file identification, field definitions, and data structures.
Clauses have been added to the READ, WRITE, REWRITE, DELETE, and
START verbs to support the AS/400 database.
Ÿ Extended data types: computational-3 (internal decimal or packed decimal),
and computational-4 (binary) data types are supported.
Ÿ Boolean and pointer data types are supported.
Ÿ You have the option to use the apostrophe instead of a quotation mark.
Ÿ The compiler-directing statements SKIP1/2/3, EJECT, and TITLE are sup-
ported.
Ÿ Extended ACCEPT/DISPLAY: Provides support for field-level work station I/O.
Ÿ LIKE clause: You can define the characteristics of a data name by copying
them from a previously-defined data name.
Ÿ Compiler listing suppression: You can selectively suppress portions of the
compiler listing by using the *CBL or *CONTROL statement, or the SUPPRESS
phrase of the COPY statement.
Ÿ Hexadecimal nonnumeric literals are supported.

 Copyright IBM Corp. 1994 1


Features of the COBOL/400 Compiler
The following language-independent features are available with the COBOL/400
compiler:
Ÿ Syntax checking:
The Source Entry Utility (SEU) provides a COBOL syntax checker that checks
for errors in lines of code as you enter or change them. Error messages are
displayed, allowing you to correct errors before compilation time.
Ÿ The cross-reference option:
– Provides a listing of each Data Division name and Procedure Division para-
graph name
– Indicates the statement numbers of each reference to the item.
Ÿ Suppression of diagnostic messages below a user-specified level.
Ÿ The Federal Information Processing Standard (FIPS) flagger issues messages
identifying obsolete or nonconforming language elements in the COBOL source
program. A source program is a set of instructions that is written in a pro-
gramming language and must be translated to machine language before the
program can be run.
Ÿ SAA flagging to highlight the functions in your program that are not portable to
other SAA COBOL environments.

Using COBOL/400 Syntax Notation


In COBOL, basic formats are presented in a uniform system of syntax notation
which is explained in the following paragraphs. This notation is designed to assist
you in writing COBOL source statements.
Ÿ COBOL keywords appear in uppercase letters; for example:
PARM1
They must be spelled exactly as shown. If any required keyword is missing,
the compiler considers it an error.
Ÿ Variables representing user-supplied names or values appear in all lowercase
letters; for example:
parmx
Ÿ For easier text reference, some words are followed by a hyphen and a digit or
a letter; for example:
identifier-1
This suffix does not change the syntactical definition of the word.
Ÿ Arithmetic and logical operators (+, -, *, /, **, >, <, =, >=, and <=) that appear in
syntax formats are required. These operators are special character reserved
words. For a complete listing of reserved COBOL/400 words, see the
“Reserved Words” section of the COBOL/400 Reference.
Ÿ All punctuation and other special characters appearing in the diagram are
required by the syntax of the format when they are shown; if you leave them
out, an error occurs in the program.

2 COBOL/400 User’s Guide


Ÿ You must write the required clauses and the optional clauses, (when used), in
the order shown in the diagram unless the associated rules explicitly state oth-
erwise.

Reading the Syntax Diagrams


Throughout this book, syntax is described using the structure defined below.
Ÿ Read the syntax diagrams from left to right, and from top to bottom, following
the path of the line:
55─── Indicates the beginning of a statement. Diagrams of syntactical units
other than statements, such as clauses, phrases and paragraphs, also
start with this symbol.
───5 Indicates that the statement syntax is continued on the next line.
5──── Indicates that a statement is continued from the previous line.
───5% Indicates the end of a statement. Diagrams of syntactical units other
than statements, such as clauses, phrases and paragraphs, also end
with this symbol.
Note: Statements within a diagram of an entire paragraph do not start with
55─── and end with ───5% unless their beginning or ending coincides with that
of the paragraph.
Ÿ Required items appear on the horizontal line (the main path). Optional items
appear below the main path:
55────STATEMENT───────required item──────┬───────────────┬────────────5%
└─optional item─┘

Ÿ When you can choose from two or more items, they appear vertically, in a
stack. If you must choose one of the items, one item of the stack appears on
the main path. If choosing an item is optional, the entire stack appears below
the main path:
55───STATEMENT───┬──required choice1──┬─────┬────────────────────┬────5%
└──required choice2──┘ ├──optional choice1──┤
└──optional choice2──┘

Ÿ An arrow returning to the left above an item indicates that this item can be
repeated:
┌────────────────┐
6 │
55───STATEMENT─────repeatable item──┴─────────────────────────────────5%

Chapter 1. An Introduction to the COBOL/400 Programming Language 3


Ÿ A repeat arrow above a stack of required or optional choices indicates that you
can make more than one choice from the stacked items, or repeat a single
choice:
┌───────────┐ ┌───────────┐
6 │ 6 │
55───STATEMENT────────┬───────────┼──────────┬──choice3──┼────────────5%
├──choice1──┤ └──choice4──┘
└──choice2──┘

The following example shows how the syntax is used:

Format
.3/
┌──────────┐
.1/ .2/ 6 │
55───STATEMENT──┬──identifier─1──┬──────┬──────────┼───────────────────5
└──literal─1─────┘ └──item─1──┘

5─┬────┬─identifier-3──┬───────────┬─┬─────────────────────────────────5 ±
└─TO─┘ └──ROUNDED──┘ │ ┌────────────────────────┐ .5/
│ 6 .4/ │
└─identifier-4─┬───────────┼──────5 ²
└──ROUNDED──┘

± 5──────────────────────────────────────────────┬─┬─────────────────┬──5%
.6/ │ └──END─STATEMENT──┘
² 5─┬─────────────────────────────────────────┬──┘ .7/
└─┬────┬──SIZE ERROR imperative-statement─┘
└─ON─┘

where item-1 is:


55───┬──identifier─2─────────────┬──────────────────────────────────5%
├──literal─2────────────────┤
└──arithmetic─expression─1──┘

.1/ The STATEMENT keyword must be specified and coded as shown.


.2/ This operand is required. Either identifier-1 or literal-1 must be coded.
.3/ The operand item-1 is optional. It can be coded or not, as required by the
application. If coded, it can be repeated, with each entry separated by one or
more blanks. Entry selections allowed for this operand are described at the
bottom of the diagram.
.4/ The operand identifier-4 is optional. If specified it may be repeated with one or
more blanks separating each entry. Each entry may be assigned the keyword
ROUNDED.
.5/ In cases where multiple lines must be continued past the right margin, line
order from top to bottom is preserved.
.6/ The ON keyword is optional to the keyword SIZE ERROR, which is optional
itself. If SIZE ERROR is coded, then the operand imperative-statement is
required.
.7/ The END-STATEMENT keyword can be coded to end the statement. It is not
a required delimiter.

4 COBOL/400 User’s Guide


Reading IBM Extensions
An IBM extension generally adds to or contradicts a rule or restriction that imme-
diately precedes it. The standard is presented first, because some programmers
use the COBOL/400 language without IBM extensions. The extension is then pre-
sented for those who do use them.

IBM extensions within figures or tables are shown in boxes unless they are explic-
itly identified as extensions.

Clauses and statements illustrated within syntax diagrams that are COBOL/400 lan-
guage extensions to ANSI X3.23-1985 COBOL are enclosed in double lines, as
follows:

╔══════════════════════════╗
5────RECORD─┬─────┬──┬────┬──┬──╫─EXTERNALLY-DESCRIBED-KEY─╫──┬─────────5
└─KEY─┘ └─IS─┘ │ ╚══════════════════════════╝ │
└────data-name-2─────────────────┘

IBM Extension

COBOL/400 language extensions to ANSI X3.23-1985 COBOL that are part of the
text description are enclosed in IBM Extension bars, like this paragraph.

End of IBM Extension

COBOL clauses and statements illustrated within syntax diagrams that are syntax
checked, but are treated as documentation by the COBOL/400 compiler, are
enclosed by asterisks, as follows:

\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
5────┬──────────────────────────────────────────┬─────────────────────────────5
\ └──RESERVE────integer────┬────────────┬────┘ \
\ ├────AREA────┤ \
\ └────AREAS───┘ \
\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

CL Entry Codes
The box that appears in the lower right corner of each CL syntax diagram contains
the entry codes that specify the environment in which the command can be
entered. The codes indicate whether or not the command can be:
Ÿ Used in a batch or interactive job (outside a compiled program; Job:B or I)
Ÿ Used in a batch or interactive compiled program (Pgm:B or I)
Ÿ Used in a batch or interactive REXX procedure (REXX:B or I)
Ÿ Used as a parameter for the CALL CL command, or passed as a character
string to the system program QCMDEXC (Exec).

Chapter 1. An Introduction to the COBOL/400 Programming Language 5


An Overview of COBOL/400 Programming
You follow four major steps or phases to build your COBOL/400 program:
Ÿ Entering your source program
Ÿ Compiling your source program
Ÿ Debugging your program
Ÿ Running your compiled program.

Entering Your COBOL Program


The Source Entry Utility (SEU) provides a special display that corresponds to the
standard COBOL coding form to help you enter an accurate COBOL source
program into the system. SEU also provides a COBOL syntax checker that checks
each line for errors as you enter or change them. For information on entering your
COBOL/400 source, refer to Chapter 2, “Entering Your Source Program on the
AS/400 System.” For more information on using SEU, see the SEU User’s Guide
and Reference.

Compiling Your COBOL Program


After you have entered the source program into the system, you need to compile
the source program using the Create COBOL Program (CRTCBLPGM) command.
The compiler is called to create a COBOL object program and a listing. An object
program is a set of instructions in machine-usable form. The object program is
produced by a compiler from a source program.

You can specify various compiler options by using the CRTCBLPGM command, or
by using the PROCESS statement with the desired options. Any options specified
in the PROCESS statement override the corresponding options on the
CRTCBLPGM command. This process is explained in detail in Chapter 3, “Com-
piling a COBOL/400 Program.”

Debugging Your COBOL Program


The OS/400 operating system provides the following functions that you can use to
test and debug your programs:
Ÿ Test library
Ÿ Breakpoints
Ÿ Traces.

The COBOL/400 compiler provides the following functions for program testing and
debugging:
Ÿ Debugging features
Ÿ Formatted dump.

These features allow you to monitor specific program operations during run time.
You must decide what to monitor and what information to retrieve for debugging
purposes.

See Chapter 5, “Debugging Your Program” for more information on debugging fea-
tures.

6 COBOL/400 User’s Guide


Running Your COBOL Program
You can run your COBOL program many ways, depending on how the program is
written, and who is using it. You can run a COBOL program by calling it from a CL
program, from an application program, from another high-level language program,
or from a user-created command.

When your program has ended, the system returns control to whoever called the
program.

For more information on running your program, see Chapter 4, “Running Your
COBOL Program.”

Chapter 1. An Introduction to the COBOL/400 Programming Language 7


8 COBOL/400 User’s Guide
Chapter 2. Entering Your Source Program on the AS/400
System
This chapter provides the information you need to enter your program. This
chapter also briefly describes the tools and methodology necessary to complete this
step.

There are two ways to enter a COBOL source program into the system:
Ÿ You can enter your source program using the Source Entry Utility (SEU). This
is the method documented in this chapter.
Ÿ You can enter your source program from diskette or tape by using the OS/400
copy function.
Refer to the CL Reference for more information on how to use the COPY func-
tion for entry of the source program from diskette or tape.

To enter your COBOL source program using SEU, enter the Start Source Entry
Utility (STRSEU) command, and specify CBL for the TYPE parameter. Refer to the
SEU User’s Guide and Reference for further information on the STRSEU command
and using SEU.

Designing Your COBOL/400 Program


You can use the skeleton program, Figure 1 on page 10, as a model for devel-
oping readable and efficient COBOL programs. Note that not all the entries pro-
vided below are required; most are provided for informational purposes only.

 Copyright IBM Corp. 1994 9


IDENTIFICATION DIVISION. .1/
The Identification Division .1/ is the only divi-
PROGRAM-ID. program-name.
AUTHOR. comment-entry.
sion that must be included; all other divisions
INSTALLATION. comment-entry. are optional.
DATE-WRITTEN. comment-entry.
DATE-COMPILED. comment-entry.
SECURITY. The Environment Division .2/ is made up of
\
\
The SECURITY paragraph can be used to contain the program
prologue. The prologue is a description of the program,
two sections: the Configuration Section .3/,
\
\
and it may be as detailed or brief as the guidelines of an
installation recommend. Lowercase letters are recommended
which describes the overall specifications of
\ for comments; however, because some printers can print the source and object computers, and the
\ only capital letters, the comments may be printed in
\ capitals. The underscores highlight the comments. Input-Output Section .4/, which defines each
ENVIRONMENT DIVISION. .2/ file, and specifies information needed for
CONFIGURATION SECTION. .3/
SOURCE-COMPUTER. IBM-AS4ðð.
transmission of data between an external
OBJECT-COMPUTER. IBM-AS4ðð.
SPECIAL-NAMES. REQUESTOR IS CONSOLE.
medium and the COBOL program.
INPUT-OUTPUT SECTION. .4/
FILE-CONTROL. The Data Division .5/ describes the files to be
SELECT file-name ASSIGN TO DISK-file-name
ORGANIZATION IS SEQUENTIAL used in the program and the records con-
ACCESS MODE IS SEQUENTIAL
FILE STATUS IS data-name.
tained within the files. It also describes any
internal working-storage data items that are
DATA DIVISION. .5/
FILE SECTION. needed.
FD file-name
BLOCK CONTAINS 2 RECORDS
RECORD CONTAINS 8ð CHARACTERS The Procedure Division .6/ consists of
LABEL RECORDS ARE STANDARD
DATA RECORD IS record-name
optional declaratives, and procedures that
ð1 record-name PIC X(132). contain sections and/or paragraphs, sen-
WORKING-STORAGE SECTION.
77 data-name PIC XX. tences, and statements.
LINKAGE SECTION.

PROCEDURE DIVISION. .6/


DECLARATIVES
END DECLARATIVES.
main-processing SECTION.
mainline-paragraph.
COBOL statements.
STOP RUN.

Figure 1. Example of COBOL/400 Program Structure

Source File Format


The standard record length of your source files is 92 characters. These 92 charac-
ters are made up of a 6-character sequence number, a 6-character date-last-
modified area, and an 80-character data field.

The COBOL/400 compiler supports an additional record length of 102; a field of 10


characters containing supplementary information is placed at the end of the record
(positions 93-102). This information is not used by the COBOL compiler, but is
placed on the extreme right of the compiler listing. You are responsible for placing
information into this field. If you want to use this additional field, create a source
file with a record length of 102.

IBM supplies a source file where you can store your source records if you do not
want to create your own file. This file, named QLBLSRC, is in library QGPL and
has a record length of 92 characters.

10 COBOL/400 User’s Guide


Entering Source Using SEU
SEU provides special display formats for COBOL. They correspond to the COBOL
Coding Form and are designed to help you enter your COBOL source programs.
Figure 2 shows a display format, the relationship between the headings on the
COBOL Coding Form, and the labels on the display; it also identifies where you
enter the source code.
Columns . . . : 1 71 Edit QGPL/QLBLSRC
SEU==> XMPLE1
┌──5 FMT CB ......-A+++B+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
SEU can display a format │ \\\\\\\\\\\\\\\ Beginning of data \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
line to help you make │ ððð1.ðð ENVIRONMENT DIVISION.
changes or key in %──┘ ððð2.ðð CONFIGURATION SECTION.
entries, position by ððð3.ðð SOURCE-COMPUTER. IBM-AS4ðð.
position. ððð4.ðð INPUT-OUTPUT SECTION.
ððð5.ðð FILE-CONTROL.
'''''''
ððð6.ðð SELECT FILE-1 ASSIGN TO DATABASE-MASTER.
ððð7.ðð SELECT FILE-2 ASSIGN TO DATABASE-MASTER.
\\\\\\\\\\\\\\\\\\ End of data \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

Prompt type . . . CB Sequence number . . . ððð5.ðð

Continuation

Area-A Area-B
FILE -CONTROL.

F3=Exit F4=Prompt F5=Refresh F11=Previous record


F12=Cancel F23=Select prompt F24=More keys

Figure 2. An SEU Display Format

For a complete description of how to enter a source program using SEU, refer to
the SEU User’s Guide and Reference.

Using the COBOL Syntax Checker in SEU


To use the COBOL syntax checker in SEU, specify the TYPE(CBL) parameter of
the STRSEU command. The COBOL syntax checker checks each line for errors
as you enter new lines or change existing lines. Incorrect source statements are
identified and error messages displayed, allowing you to correct the errors before
compiling the program. Because the COBOL syntax checker checks only one
statement at a time, independently of statements that precede or follow it, only
syntax errors within the source data can be detected. No interrelational errors,
such as undefined names and incorrect references to names, are detected. These
errors are detected by the COBOL compiler when the program is compiled.

Any time a source line is entered or changed, up to 496 lines of source code can
be syntax checked as one unit. The length of a single unit of syntax-checking is
determined by extending from an entered or changed line as follows:
A unit of syntax-checking extends towards the beginning of the source member
until the first source line, or a line that ends in a period is found.
A unit of syntax-checking extends towards the end of the source member until
the last source line, or a line that ends in a period is found.
If this unit spans more than 496 source lines (not including comment lines), the
system responds with an appropriate message.

Chapter 2. Entering Your Program 11


If there is an error in a unit of syntax-checking, the entire unit is presented in
reverse image. The message at the bottom of the display refers to the first error in
the unit.

Syntax checking occurs line by line as you enter the source code. Error messages
are generated by lines consisting of incomplete statements. These disappear when
the statements are completed, as in the example:

ADD A
TO BCD.

An error message is generated after the first line is entered and disappears after
the second line is entered, when the statement is completed. A COBOL sentence
can span a maximum of 496 lines. Also, if a source line is entered or changed, up
to 496 lines of source code can be syntax checked as one unit.

The following regulations apply to syntax checking for COBOL source functions:
Ÿ Source code on a line with an asterisk (*) or a slash (/) in column 7 is not
syntax checked. An asterisk indicates a comment line; a slash indicates a
comment line and page eject.
Ÿ No compiler options are honored during syntax checking.
For example, the syntax checker accepts both quotation marks or apostrophes
as nonnumeric delimiters provided they are not mixed within one unit of syntax
checking. The syntax checker does not check if the delimiter is the one that
will be specified in the CRTCBLPGM command for compiling COBOL source
statements, or in the PROCESS statement.
Ÿ The first sentence following any of the paragraph headers listed below must
begin on the same line as the paragraph header.
PROGRAM-ID.
AUTHOR.
INSTALLATION.
DATE-WRITTEN.
DATE-COMPILED.
SECURITY.
SOURCE-COMPUTER.
OBJECT-COMPUTER.
SPECIAL-NAMES.
Ÿ Character replacement specified by the CURRENCY and DECIMAL-POINT
clauses of the SPECIAL-NAMES paragraph is not honored during interactive
syntax checking.
Ÿ When using the REPLACING Identifier-1 BY Identifier-2 clause of the COPY
statement and when either identifier includes reference modification, SEU
checks for matching parentheses only. for more information on reference mod-
ification, see Chapter 11, “COBOL/400 Programming Considerations.”

Syntax for Structured Query Language (SQL) Statements


The syntax for SQL statements embedded in a COBOL source program is:

5──EXEC SQL──sql-statement──END-EXEC.─────────────────────────────5%

12 COBOL/400 User’s Guide


If the member type for the source program is SQLCBL or CICSSQLCBL, when the
COBOL syntax checker encounters an SQL statement, the statement is passed to
the SQL syntax checker. If an error is detected, a message is returned.

If an SQL statement is encountered, and if the member type is not SQLCBL or


CICSSQLCBL, a COBOL message is returned indicating that a COBOL statement
is in error.

If there are errors in the embedded SQL statement as well as errors in the pre-
ceding COBOL statements, the SQL error message will only be displayed after the
preceding COBOL errors are corrected.

For more information about SQL statements, refer to the SQL/400* Reference.

Syntax for Customer Information Control System (CICS)


Statements
The syntax for CICS statements embedded in a COBOL source program is:

5──EXEC CICS──cics-statement──END-EXEC.─────────────────────────────5%

If the member type for the source program is CICSCBL or CICSSQLCBL, when the
COBOL syntax checker encounters a CICS statement, the COBOL syntax checker
checks for only basic syntax errors.

If a CICS statement is encountered, and if the member type is not CICSCBL or


CICSSQLCBL, a COBOL message is returned indicating that a COBOL statement
is in error.

For more information about CICS/400 statements, refer to the CICS/400 Application
Programming Guide.

Chapter 2. Entering Your Program 13


14 COBOL/400 User’s Guide
Chapter 3. Compiling a COBOL/400 Program
You need to compile the COBOL/400 source program to produce a usable object
program. You do this using the Create COBOL Program (CRTCBLPGM)
command. The result of the compilation is a COBOL object program and a listing.

You can specify various compiler options by using the CRTCBLPGM command, or
from within the program using the PROCESS statement. Any options specified in
the PROCESS statement override the corresponding options on the CRTCBLPGM
command. The PROCESS statement is discussed later in “Using the PROCESS
Statement to Specify Compiler Options” on page 32.

┌───────────┐ ┌─────────┐
│ COBOL │ │ COBOL │
│ Source ├──────────5COBOL Compiler──┬───────5│ Object │
│ Program │ & & & │ │ Program │
└───────────┘ │ │ │ │ └─────────┘
│ │ 6 │
┌───────────┐ │ │ OS/4ðð │
│ Externally│ │ │ Operating │ ┌────────────────────────┐
│ Described ├───────────┘ │ System └───────5│ Listing │
│ Files │ │ │ - Command summary │
└───────────┘ │ │ - Compiler options │
& │ │ - Source listing │
│ │ │ - Verb usage │
│ │ │ - Data Division map │
┌─────┴─────┐ │ │ - FIPS messages │
│ DDS for │ ┌──────┴─┐ │ - SAA messages │
│ Externally│ │ Copy │ │ - Cross-reference │
│ Described │ │ Source │ │ - Messages │
│ Files │ │ Text │ └────────────────────────┘
└───────────┘ └────────┘

During compilation, the compiler checks the syntax of the COBOL source program
line by line, and also checks the relationships between the lines.

Using the Create COBOL Program (CRTCBLPGM) Command


To compile a COBOL/400 source program into an object program, you must enter
the CRTCBLPGM command. This calls the COBOL/400 compiler. You can use
the CRTCBLPGM command interactively, or in batch jobs, or from other programs
on the AS/400 system.

Programming Note: The number of entries in the Object Definition Table (ODT)
and the amount of storage required by a COBOL program varies with the number
and kinds of COBOL statements used in the program. A combination of these
factors can cause the AS/400 internal size limits for the program to be exceeded. If
this occurs, try using the *NOUNREF option of the GENOPT parameter. If the
problem persists, the program must be rewritten.

When the *NOUNREF option is specified, only names that are referenced or are
needed for data structuring are defined. This option is useful when the program
contains many unreferenced identifiers.

 Copyright IBM Corp. 1994 15


If you do not specify CBL as the source member type, the compiler issues a
warning.

If the Format 2 COPY statement is used in the program to access externally


described files, the operating system provides information about the externally
described files to the compiled program.

If the COBOL compiler stops, the message LBL9001


Compile failed. Program not created.
is issued. You can use a control language program that can monitor for this excep-
tion by using the control language Monitor Message (MONMSG) command.

Using the CRTCBLPGM Prompt Displays


To enter the CRTCBLPGM command from the CRTCBLPGM prompt displays, type
CRTCBLPGM and press F4 (Prompt) to show the first display. The parameters and
options are described in the order they appear on these displays, on pages 18
through 27. The default values are explained first, and are underlined.

Each parameter on this display shows a default value. Move the cursor past the
items where you want default values to apply. Type over any items to set different
values or options. If you are unsure about the setting of a parameter value, type a
question mark (?) in the first position of the field and press Enter, or F4 (Prompt), to
receive more detailed information. The question mark must be followed by a blank.

Figure 3 shows the CRTCBLPGM prompt displays. When you see the first
CRTCBLPGM prompt display, you see only the required parameters prompted. To
see the additional parameters, press F10. You see the first display shown in
Figure 3. To see the remainder of the parameters, as shown in the second and
third displays in Figure 3, page forward.

16 COBOL/400 User’s Guide


à@ Create COBOL Program (CRTCBLPGM)
ð
Type choices, press Enter.

Program . . . . . . . . . . . . \PGMID Name, \PGMID


Library . . . . . . . . . . . \CURLIB Name, \CURLIB
Source file . . . . . . . . . . QLBLSRC Name
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB
Source member . . . . . . . . . \PGM Name, \PGM
Generation severity level . . . 29 ð-29
Text 'description' . . . . . . . \SRCMBRTXT

Additional Parameters

Source listing options . . . . . \SOURCE, \NOSOURCE, \SRC...


+ for more values
Generation options . . . . . . . \NOLIST, \LIST, \NOXREF...
+ for more values

More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

á ñ
à@ Create COBOL Program (CRTCBLPGM)
ð
Type choices, press Enter.

Conversion options . . . . . . . \NOVARCHAR, \VARCHAR...

Message Limit:
Number of messages . . . . . . \NOMAX 1-9999, \NOMAX
Message limit severity . . . . 29 ð-29
Print file . . . . . . . . . . . QSYSPRT Name
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB
FIPS flagging . . . . . . . . .
+ for more values
SAA flagging . . . . . . . . . . \NOFLAG \NOFLAG, \FLAG
Extended display options . . . . \DFRWRT, \NODFRWRT...
+ for more values
Flagging severity . . . . . . . ð ð-99
Replace program . . . . . . . . \YES \NO, \YES
Target release . . . . . . . . . \CURRENT \CURRENT, \PRV, V2R1Mð...
User profile . . . . . . . . . . \USER \USER, \OWNER
More...
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

á ñ
à@ Create COBOL Program (CRTCBLPGM)
ð
Type choices, press Enter.

Authority . . . . . . . . . . . \LIBCRTAUT Name, \LIBCRTAUT, \ALL...


Compiler debugging dump:
1 1-65535, \
65535 1-65535
Intermediate text dump . . . . . ð ð-31

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

á ñ
Figure 3. The CRTCBLPGM Prompt Displays

Chapter 3. Compiling a Program 17


Parameters of the CRTCBLPGM Command
A description of the parameters for the CRTCBLPGM command follows. The default values are explained
first, and are underscored for identification. The parameters and options are described in the order they
appear on the prompt displays.

All object names specified for the CRTCBLPGM command must follow AS/400 naming conventions: the
names may be basic names, 10 characters in length, composed of alphanumeric characters, the first of
which must be alphabetic; or the names may be quoted names, 8 characters in length, enclosed in double
quotes.

If you want to relate these parameter descriptions to the CRTCBLPGM syntax diagram, refer to Figure 4
on page 29.
source-file-name
Enter the name of the source file that con-
PGM Parameter:
tains the COBOL source to be compiled.
Specifies the program name and library name
This source file should have a record
for the COBOL program object you are cre-
length of 92.
ating. The possible values are:
The possible library values are:
*PGMID
The name for the program object is taken *LIBL
from the PROGRAM-ID paragraph in the If you do not specify a library name, the
COBOL source program. system searches the library list to find the
library where the source file is located.
program-name
Enter a name to identify the compiled *CURLIB
COBOL program. If you specify a The current library is used. If you have
program name for this parameter, and run not assigned a library as the current
the compilation in batch mode, the first library, QGPL is used.
program in the batch job uses this name;
any other programs use the name speci-
library-name
Enter the name of the library where the
fied in the PROGRAM-ID paragraph in the
source file is located.
source program.
SRCMBR Parameter:
The possible library values are:
Specifies the name of the member that con-
*CURLIB tains the COBOL source to be compiled. You
If you do not specify a library name, the can specify this parameter only if the source
current library is used. If you have not file referenced in the SRCFILE parameter is a
assigned a library as the current library, database file. The possible values are:
QGPL is used.
*PGM
library-name If you specified a program name for the
Enter the name of the library to contain PGM parameter, the compiler looks for the
the created program object. source program in a member having the
same name as the program, and creates
SRCFILE Parameter:
an object program with the same name as
Specifies the name of the source file that con-
the program and member.
tains the COBOL source to be compiled. The
possible values are: If you did not specify a program name for
the PGM parameter, the compiler looks for
QLBLSRC the program source in the first member of
Specifies that the source file, QLBLSRC, the database source file, and creates an
contains the COBOL source to be com- object program using the name specified
piled. in the PROGRAM-ID paragraph.

18 COBOL/400 User’s Guide


source-file-member-name *NOSOURCE or *NOSRC
Enter the name of the member that con- The compiler does not produce the source
tains the COBOL source. part of the listing. If you do not require a
source listing, you should use this option
GENLVL Parameter:
because compilation may take less time.
Specifies the severity level that determines if a
program object is created. The severity level
corresponds to the severity level of the mes-
*NOXREF
sages produced during compilation of the
The compiler does not produce a cross-
program. If the severity level of error mes-
reference listing for the source program.
sages is greater than the value you specify, a
program object is not created. For example, if *XREF
you specify 19 for this parameter, a program The compiler produces a cross-reference
object is not created if the severity level of any listing for the source program.
of the messages is 20 or greater.
The possible values are:
*GEN
29 If errors occur with a severity level greater The compiler creates a program object
than 29, no program object is created. after the program is compiled.
severity-level *NOGEN
Specify a one or two-digit number, 0 The compiler does not create a program
through 29. If errors occur with a severity object after the source program is com-
level greater than this level, no program piled. You might specify this option if you
object is created. want only error listings at this time.
TEXT Parameter:
Allows you to enter text that briefly describes
*NOSEQUENCE
the program and its function.
The reference numbers are not checked
*SRCMBRTXT for sequence errors.
Use the same text for the program object
*SEQUENCE
as that which describes the database file
The reference numbers are checked for
member containing the COBOL source. If
sequence errors. Sequence errors do not
the source comes from a device or in-line
occur if the *LINENUMBER option is spec-
file, specifying *SRCMBRTXT has the
ified.
same effect as specifying *BLANK.

*BLANK
No text is specified. *NOVBSUM
Verb usage counts are not printed.
text-description
Enter the text that briefly describes the *VBSUM
program and its function. The text can be Verb usage counts are printed.
a maximum of 50 characters in length and
must be enclosed in apostrophes. The
apostrophes are not part of the *NONUMBER
50-character string. The source-file sequence numbers are
used for reference numbers.
OPTION Parameter:
Specifies the options to use when the COBOL *NUMBER
source is compiled. The possible values are: The user-supplied sequence numbers
(columns 1 through 6) are used for refer-
*SOURCE or *SRC
ence numbers.
The compiler produces a source listing,
consisting of the COBOL source input and
all compilation-time error messages.

Chapter 3. Compiling a Program 19


*LINENUMBER *NOSECLVL
The sequence numbers created by the Second level message text is not listed for
compiler are used for reference numbers. this compilation.
This option combines program source
*SECLVL
code and source code introduced by
Second level message text is listed for
COPY statements into one consecutively
this compilation, along with the first-level
numbered sequence. Use this option if
error text.
you specify FIPS (Federal Information
Processing Standards) flagging or SAA* Note: The first-level error text is printed
flagging. each time the error occurs.

*NOMAP *PRTCORR
The compiler does not list the Data Divi- The compiler inserts comment lines in the
sion map. compiler listing indicating which elemen-
tary items were included as a result of the
*MAP
use of the CORRESPONDING phrase.
The compiler lists the Data Division map.
*NOPRTCORR
The compiler does not insert comment
*NOOPTIONS lines in the compiler listing when the
Options in effect are not listed for this CORRESPONDING phrase is used.
compilation.

*OPTIONS
*NOSRCDBG
Options in effect are listed for this compi-
This option determines the kind of infor-
lation.
mation you see on your programmable
work station when using the CoOperative
Development Environment/400 to compile
*QUOTE
your COBOL programs. See the note on
Specifies that the delimiter quotation mark
page 21 for further information.
(") is used for nonnumeric literals and
Boolean literals. This also specifies that The compiler does not produce source-
the value of the figurative constant level debugging information. If
QUOTE has the EBCDIC value of a quo- *NOLSTDBG is also in effect, the compiler
tation mark. does not produce source-level error infor-
mation either.
Note: Boolean data is a category of data
items that are limited to a value of 1 or 0. *SRCDBG
A Boolean literal is a literal composed of a This option determines the kind of infor-
Boolean character enclosed in quotation mation you see on your programmable
marks and preceded by a B; for example: work station when using the CoOperative
B"1". Development Environment/400 product to
compile your COBOL programs. See the
*APOST
note on page 21 for further information.
Specifies that the delimiter apostrophe (')
is used for nonnumeric literals and The compiler produces source-level error
Boolean literals. This also specifies that information and source-level debugging
the value of the figurative constant information.
QUOTE has the EBCDIC value of an You cannot specify *SRCDBG and
apostrophe. *LSTDBG together. Specify one or the
other.

20 COBOL/400 User’s Guide


*NOLSTDBG GENOPT Parameter:
This option determines the kind of infor- Specifies the options to use when the program
mation you see on your programmable object is created. The listings could be
work station when using the CoOperative required if a problem occurs in COBOL. The
Development Environment/400 product to possible values are:
compile your COBOL programs. See the
*NOLIST
note on page 21 for further information.
No IRP (intermediate representation of
The compiler does not produce a listing program), associated hexadecimal code,
view, source-level error information, or or error messages are listed.
listing-level debugging information.
*LIST
*LSTDBG The IRP, its associated hexadecimal code,
This option determines the kind of infor- and any error messages are listed.
mation you see on your programmable
work station when using the CoOperative
Development Environment/400 product to *NOXREF
compile your COBOL programs. See the Does not produce a cross-reference listing
note on page 21 for further information. of the objects defined in the IRP.
The compiler produces a listing view, and *XREF
listing-level debugging information. If Produces a cross-reference listing of all
*NOSRCDBG is also in effect, the com- objects defined in the IRP.
piler does not produce source-level error
information either.
You cannot specify *SRCDBG and *NOPATCH
*LSTDBG together. Specify one or the Does not reserve space in the compiled
other. program for a program patch area.
| Note: You can only use the *PATCH
| *NOSRCDBG, *SRCDBG, Reserves space in the compiled program
| *NOLSTDBG and *LSTDBG for a program patch area. The program
| options if you are using the patch area can be used for debugging
| AD/Cycle CoOperative Develop- purposes.
| ment Environment/400 product to
| compile your program. If you
| specify one or more of these *NODUMP
| options but do not have the Does not list the program template.
| CODE/400 product installed, the
| COBOL/400 compiler will not con- *DUMP
| tinue processing and an error Lists the program template.
| message is issued. For more
| information on these options, see
| the CODE Debug Tool User's *NOATR
| Guide and Reference, SC09-1622. Does not list the attributes for the IRP
source.

*ATR
*PRINT Lists the attributes for the IRP source.
The compiler produces a spool listing.

*NOPRINT
The compiler does not produce a spool *RANGE
listing. At runtime, the system verifies that sub-
scripts are within the correct ranges, but
does not verify index ranges. It also

Chapter 3. Compiling a Program 21


checks for reference modification and *DDSFILLER
compiler-generated substring operations. When no matching fields are found by a
COPY DDS statement, a single character
*NORANGE
FILLER field description, "07 FILLER PIC
Does not verify ranges at run-time.
X", is always created.
Note: The *RANGE option generates
code for checking subscript
ranges. For example, it ensures *NOSYNC
that you are not attempting to The SYNCHRONIZED clause is syntax
access the 21st element of a checked.
20-element array.
*SYNC
The *NORANGE option does not The SYNCHRONIZED clause causes the
generate code to check subscript alignment of an elementary item on a
ranges. natural boundary in storage.
These options do not eliminate the
zero subscript checking performed
by the operating system. If zero *NOCRTF
subscripts occur, the operating Files that are unavailable at the time of an
system will not permit their use OPEN operation are not created dynam-
and issues message MCH0603. ically.

*CRTF
Files that are unavailable at the time of an
*UNREF OPEN operation are created dynamically.
Includes unreferenced data items in the | When created, the file will inherit authority
compiled program. | from the job profile. (See the discussion
*NOUNREF of the OPEN statement in the COBOL/400
Does not include unreferenced data items Reference manual for the conditions under
in the compiled program. This reduces which dynamic file creation can occur.)
the number of ODT (object definition Note: The maximum record length for a
table) entries used, allowing a larger file that will be created dynamically
program to be compiled. The unrefer- is 32 766.
enced data items still appear in the cross-
reference listings produced by specifying
OPTION (*XREF). *NODUPKEYCHK
Does not check for duplicate keys for
INDEXED files.
*NOOPTIMIZE
The compiler performs only standard opti- *DUPKEYCHK
mizations for the program. Checks for duplicate keys for INDEXED
files. (See the discussion of the READ
*OPTIMIZE statement in the COBOL/400 Reference
The compiler attempts to create a | manual for the conditions under which the
program that operates more efficiently and | existence of records with duplicate keys
uses less storage. However, specifying | will be signalled to a program.
*OPTIMIZE can substantially increase the
| Warning: Specifying this option can
time required to compile a program.
| result in a loss in compiler performance.

*NODDSFILLER
*STDERR
If no matching fields are found by a COPY
Standard error handling is used. See
DDS statement, no field descriptions are
Chapter 6, “COBOL/400 Exception and
generated.

22 COBOL/400 User’s Guide


Error Handling” on page 69 for more infor- The BLOCK CONTAINS clause controls
mation. the number of records to be blocked.

*NOSTDERR When no BLOCK CONTAINS clause is


The error handling method of Version 1, specified, the compiler allows blocking
Releases 1 and 2, is used. only of SEQUENTIAL access files with no
START statement. The operating system
determines the number of records to be
*NOEXTACCDSP blocked.
The compiler does not allow extended
ACCEPT or DISPLAY statements.
*STDINZ
*EXTACCDSP The compiler initializes user data items to
The compiler allows extended ACCEPT system defaults, provided that the items
and DISPLAY statements. Refer to are not subject to a VALUE clause.
Appendix E of the COBOL/400 Reference
for changes to the reserved word list that *NOSTDINZ
occur when you use this option. For those user items with no VALUE
clause, the compiler does not initialize
data items to system defaults.
*NOINZDLT
Relative files with sequential access are
not initialized with deleted records during *FS21DUPKY
the CLOSE operation if the files have The compiler reports a file status of 21
been opened for OUTPUT. That is, the when processing an indexed file with
record boundary is determined by the duplicate keys in random or dynamic
number of records written. Subsequent access mode, if the value of the key is
OPEN operations allow access only up to changed between the mandatory READ
the record boundary. statement and a following REWRITE or
DELETE statement.
*INZDLT
Relative files with sequential access are *NOFS21DUPKY
initialized with deleted records during the The compiler does not report a file status
CLOSE operation if the files were opened of 21 when processing an indexed file with
for OUTPUT. Active records in the files duplicate keys in random or dynamic
are not affected. That is, the record access mode. A REWRITE statement can
boundary is defined as the file size for change the key of a record.
subsequent I/O operations.
CVTOPT Parameter:
Specifies how the compiler handles SAA date,
time, and timestamp data types,
*NOBLK
DBCS-graphic data types, and variable-length
The compiler allows blocking only of
character fields passed from externally-
SEQUENTIAL access files with no START
described files to your program through COPY
statement.
DDS. The possible values are:
If a BLOCK CONTAINS clause is speci-
*NOVARCHAR
fied, the BLOCK CONTAINS clause is
Variable-length fields are ignored, and are
ignored, except for tape files.
declared as FILLER fields.
*BLK
*VARCHAR
When used with BLOCK CONTAINS, the
Variable-length fields are declared as
compiler allows blocking from DYNAMIC
fixed-length group items, and are acces-
access files and SEQUENTIAL access
sible to the program. For more informa-
files with a START statement. Blocking is
tion on variable-length fields, refer to
not allowed for RELATIVE files opened for
output operations.

Chapter 3. Compiling a Program 23


“Declaring Data Items Using CVTOPT *NOMAX
Data Types” on page 130. Compilation continues until normal
completion regardless of the number
of errors encountered.
*NODATETIME
1-9999
Date, time, and timestamp data types are
Compilation stops if the number of
ignored, and are declared as FILLER
errors of the specified severity level or
fields.
higher exceeds the number you
*DATETIME specify. If no messages equal or
Date, time, and timestamp data types are exceed the maximum severity level,
declared as fixed-length character fields, compilation continues regardless of
and are accessible to the program. the number of errors encountered.

message-severity
The possible values for the maximum
*NOGRAPHIC
error severity level are:
DBCS-graphic data types are ignored, and
are declared as FILLER fields. 29 Compilation stops if the number of
errors with severity level 29 or higher
*GRAPHIC
exceeds the maximum number of
Fixed-length DBCS-graphic data types are
error messages specified.
declared as fixed-length alphanumeric
fields, and are accessible to the program. maximum-severity-level
When the *VARCHAR option is also in Specify a one or two-digit number, 0
use, variable-length DBCS-graphic data through 29. Compilation stops if the
types are declared as fixed-length group number of errors with the specified
items, and are accessible to the program. severity level or higher exceeds the
For more information on DBCS-graphic maximum number of error messages
data types, refer to “DBCS-Graphic Fields” you specify.
on page 133. PRTFILE Parameter:
MSGLMT Parameter: Specifies the name of the file to which the
Controls compilation by indicating the compiler listing is directed and the library
maximum number of error messages of a where the file is located. The file should have
given error severity level that can occur before a minimum record length of 132. If a file with
compilation stops. a record length less than 132 is specified,
information is lost.
For example, you can stop compilation if more
than three errors with a severity level of 20 or The possible values are:
higher occur. In this example, you would QSYSPRT
specify 3 for the maximum number of error If you do not specify a file name, the com-
messages, and 20 for the maximum error piler listing is directed to QSYSPRT, an
severity level. If three errors of severity level IBM-supplied file.
20 or higher occur, compilation continues, but
when a fourth is encountered, compilation file-name
stops. If no messages equal or exceed the Enter the name of the file to which the
maximum severity level, compilation continues compiler listing is directed.
regardless of the number of errors encount-
The possible library values are:
ered.
*LIBL
message-limit
If a library-name is not specified, the
The possible values for the maximum
system searches the library list, *LIBL, to
number of error messages are:
find the library where the file is located.

24 COBOL/400 User’s Guide


*CURLIB *NOOBSOLETE
The current library is used. If you have Obsolete language elements are not
not assigned a library as the current flagged.
library, QGPL is used.
*OBSOLETE
library-name Obsolete language elements are flagged.
Enter the name of the library where the
SAAFLAG Parameter:
file is located.
Specifies if you want flagging of COBOL/400*
FLAGSTD Parameter: functions that are not supported by SAA
Specifies the options for FIPS flagging. COBOL. (Select the *LINENUMBER option to
(Select the *LINENUMBER option to ensure ensure that the reference numbers used in the
that the reference numbers used in the FIPS SAA COBOL messages are unique.) The
messages are unique.) The possible values possible values are:
are:
*NOFLAG
*NOFIPS SAA COBOL flagging is not performed.
The source program is not FIPS flagged.
*FLAG
*MINIMUM SAA COBOL flagging is performed.
FIPS flag for minimum subset and higher.
EXTDSPOPT Parameter:
*INTERMEDIATE Specifies the options to use for extended
FIPS flag for intermediate subset and ACCEPT and extended DISPLAY statements
higher. for work station I/O. The possible values are:

*HIGH *DFRWRT
FIPS flag for high subset. Extended DISPLAY statements are held in
a buffer until an extended ACCEPT state-
ment is encountered, or until the buffer is
*NOSEG filled.
The optional module SEGMENTATION is
If an extended ACCEPT statement is not
not FIPS flagged.
encountered before the buffer is filled, the
*SEG1 contents of the buffer are written to the
FIPS flag for optional module SEGMEN- display. When an extended ACCEPT
TATION level 1 and higher. statement is encountered, the current con-
tents of the buffer are written to the
*SEG2 display.
FIPS flag for optional module SEGMEN-
TATION level 2. *NODFRWRT
Each extended DISPLAY statement is per-
formed as it is encountered.
*NODEB
The optional module DEBUG is not FIPS
flagged. *UNDSPCHR
Displayable and undisplayable characters
*DEB1 are handled by extended ACCEPT and
FIPS flag for optional module DEBUG extended DISPLAY statements.
level 1 and higher.
*NOUNDSPCHR
*DEB2 | Use this option when the data to be dis-
FIPS flag for optional module DEBUG | played contains extended DBCS charac-
level 2. | ters. Only displayable characters are
handled by extended ACCEPT and
extended DISPLAY statements.

Chapter 3. Compiling a Program 25


Although you must use this option for ification level. For example, V2R2M0 is
display stations attached to remote 3174 version 2, release 2, modification level 0.
and 3274 controllers, you can also use it
Note: To use the object on the target
for local work stations. If you do use this
system, you must save the object to
option, your data must contain displayable
the target release level specified on
characters. If the data contains values
the create command and then restore
less than hexadecimal 20, the results are
it on the target system.
not predictable, ranging from unexpected
display formats to severe errors. The possible values are:

*CURRENT
The object is to be used on the release of
*ACCUPDALL
the operating system currently running on
All types of data are predisplayed in the
your system. You can also use the object
extended ACCEPT statements regardless
on a system with any subsequent release
of the existence of the UPDATE phrase.
of the operating system installed.
*ACCUPDNE
*PRV
Only numeric edited data are predisplayed
The object is to be used on the previous
in the extended ACCEPT statements that
release with modification level 0 of the
do not contain the UPDATE phrase.
operating system. You can also use the
FLAG Parameter: object on a system with any subsequent
Specifies the minimum severity level of mes- release of the operating system installed.
sages to be printed. The possible values are:
release-level
0 All messages are printed. Specify the release in the format VxRxMx.
The object can be used on a system with
severity-level the specified release or with any subse-
Enter a one or two-digit number that spec- quent release of the operating system
ifies the minimum severity level of mes- installed.
sages to be printed. Messages that have
severity levels of the specified value or Valid values depend on the current
higher are listed. version, release, and modification level,
and they change with each new release.
REPLACE Parameter:
Specifies if a new program object is created USRPRF Parameter:
when a program object of the same name in Specifies the user profile that will run the com-
the same library already exists. The possible piled COBOL program. The profile of the
values are: program owner or the program user is used to
run the program and control which objects can
*YES be used by the program (including the
A new program object is created and any authority the program has for each object).
existing program object of the same name This parameter is not updated if the program
in the specified library is moved to library already exists. To change the value of
QRPLOBJ. USRPRF, delete the program and recompile
using the correct value.
*NO
A new program object is not created if a The possible values are:
program object of the same name already
*USER
exists in the specified library.
The user profile of the program user is to
TGTRLS Parameter: be used when the program is run.
Specifies the release of the operating system
*OWNER
on which you intend to use the object being
The user profiles of both the program’s
created. You can specify an exact release
owner and user are to be used when the
level in the format VxRxMx, where Vx is the
program is run. The collective sets of
version, Rx is the release, and Mx is the mod-

26 COBOL/400 User’s Guide


object authority in both user profiles are to the program object except those limited to
be used to find and access objects during the owner or controlled by object authority
the running of the program. Any objects and object management authority. The
that are created during the program are user can change the object and perform
owned by the program’s user. basic functions on it, such as running and
debugging the program object.
Note: Specify the USRPRF parameter to
reflect the security requirements of *USE
your installation. The security Provides object operational authority and
facilities available on the AS/400 read authority; authority for basic oper-
system are described in detail in ations on the program object such as
the Security Reference. running the program. The user is pre-
vented from changing the object.
AUT Parameter:
*EXCLUDE
Specifies the authority given to users who do
The user cannot access the program
not have specific authority to the program
object.
object, who are not on the authorization list, or
whose group has no specific authority to the authorization-list-name
program object. You can alter the authority Enter the name of an authorization list of
for all users, or for specific users after the users and authorities to which the
program object is created by using the program is added. The program object is
GRTOBJAUT (Grant Object Authority) or secured by this authorization list, and the
RVKOBJAUT (Revoke Object Authority) com- public authority for the program object is
mands. set to *AUTL. The authorization list must
The possible values are: exist on the system when the
CRTCBLPGM command is issued. Use
*LIBCRTAUT the Create Authorization List (CRTAUTL)
The public authority for the object is taken command to create your own authorization
from the CRTAUT keyword of the target list.
library (the library that is to contain the
Note: Specify the AUT parameter to
created program object). This value is
reflect the security requirements of
determined when the program object is
your installation. The security
created. If the CRTAUT value for the
facilities available on the AS/400
library changes after the program object is
system are described in detail in
created, the new value does NOT affect
Security Reference.
any existing objects.

*ALL DUMP Parameter:


Provides authority for all operations on the An IBM COBOL/400 debugging aid for IBM
program object except those limited to the service personnel.
owner or controlled by authorization list
management authority. The user can ITDUMP (n) Parameter:
control the program object's existence, An IBM debugging aid provided for IBM
specify security for it, change it, and service personnel. This parameter makes the
perform basic functions on it, but cannot compiler dump the internal text at certain
transfer its ownership. times during the compilation of the source
program.
*CHANGE
Provides all data authority and the
authority for performing all operations on

Chapter 3. Compiling a Program 27


Entering CRTCBLPGM from the Command Line
You can enter the CRTCBLPGM command from the command line. Type
CRTCBLPGM followed by the appropriate parameters to compile your program. Refer
to the Figure 4 on page 29 for the correct syntax. If you are unsure about the
parameters and their meanings, refer to the parameter and option descriptions on
pages 18 through 27. Refer to the following examples of the syntax you would use
to enter the CRTCBLPGM command from the command line.

Example 1
CRTCBLPGM SRCFILE(QGPL/QLBLSRC) SRCMBR(SAMPLE) SAAFLAG(\FLAG)

Partial Source for Member SAMPLE


ID DIVISION.
PROGRAM-ID. EXAMPLE.
The preceding example creates a COBOL/400 program from the source member
SAMPLE in file QLBLSRC and library QGPL. The resulting program is called
EXAMPLE. Specifying *FLAG for the SAAFLAG parameter tells the compiler to
identify any functions that are not supported by SAA COBOL. In this example, all
parameter defaults were used with the exception of the SRCFILE, SRCMBR, and
SAAFLAG parameters.

Example 2
CRTCBLPGM PGM(TEST) SRCFILE(SOURCE1) CVTOPT(\GRAPHIC)
In the preceding example, the compiler looks for the file SOURCE1 in the library
list, and looks for the member called TEST within that file. (The value for the
SRCMBR parameter defaulted to *PGM, specifying to look for a member with the
same name as the program to be created.) The compiler creates a COBOL/400
program called TEST from the source program found in the member TEST in the
file SOURCE1. Specifying *GRAPHIC for the CVTOPT parameter indicates that if
the DDS contains DBCS-graphic data types, you want the COBOL program to be
able to reference them as alphanumeric fields.

Entering CRTCBLPGM from a CL Program


When you issue the CRTCBLPGM command from a CL program, you can use con-
catenation expressions for all parameter values. See the CL Reference for more
information about concatenation expressions. Also, see the CL Reference for a
detailed description of OS/400 object naming rules and for a complete description
of OS/400 command syntax.

General-Use Programming Interface

You can use this command in QCMDEXC.

End of General-Use Programming Interface

28 COBOL/400 User’s Guide


Syntax of the CRTCBLPGM Command
Figure 4 shows the syntax of the CRTCBLPGM command.

55──CRTCBLPGM───PGM──(─┬─\CURLIB/──────┬─┬─\PGMID───────┬─)───────────────────5
└─library-name/─┘ └─program-name─┘

5───────────┬────────────────────────────────────────────────────────────┬────5
└─SRCFILE──(──┬─\LIBL/────────┬──────┬─QLBLSRC──────────┬──)─┘
├─\CURLIB/──────┤ └─source-file-name─┘
└─library-name/─┘

5───────────┬─────────────────────────────────────────┬───────────────────────5
└─SRCMBR──(─┬─\PGM────────────────────┬─)─┘
└─source-file-member-name─┘

5───────────┬────────────────────────────┬───┬────────────────────────────┬───5
└─OPTION──(─option-details─)─┘ └─GENOPT──(─genopt-details─)─┘

5───────────┬──────────────────────────────────────────────────────────────┬──5
└─CVTOPT────(─┬─\NOVARCHAR─┬──┬─\NODATETIME─┬──┬─\NOGRAPHIC─┬─)┘
└─\VARCHAR───┘ └─\DATETIME───┘ └─\GRAPHIC───┘

5───────────┬───────────────────────────────────────────────────────────┬─────5
└─MSGLMT──(─┬──\NOMAX─────────┬───┬──29─────────────────┬─)─┘
└──message-limit──┘ └──max-severity-level─┘

5───────────┬────────────────────────────────┬────────────────────────────────5
└─GENLVL──(─┬─29─────────────┬─)─┘
└─severity-level─┘

5───────────┬─────────────────────────────────────────────────┬───────────────5
└─PRTFILE──(─┬─\LIBL/─────────┬──┬─QSYSPRT───┬─)──┘
├─\CURLIB/───────┤ └─file-name─┘
└─library-name/──┘

5───────────┬──────────────────────────────────────────────────────────────┬──5
└─FLAGSTD─(─┬\NOFIPS──────┬─┬\NOSEG┬─┬\NODEB┬─┬\NOOBSOLETE─┬─)─┘
├\MINIMUM─────┤ ├\SEG1─┤ ├\DEB1─┤ └\OBSOLETE───┘
├\INTERMEDIATE┤ └\SEG2─┘ └\DEB2─┘
└\HIGH────────┘

5───────────┬──────────────────────────┬──────────────────────────────────────5
└─SAAFLAG──(─┬─\NOFLAG─┬─)─┘
└─\FLAG───┘

5───────────┬───────────────────────────────────────────────────────────────┬─5
└─EXTDSPOPT─(─┬─\DFRWRT───┬───┬─\UNDSPCHR───┬──┬─\ACCUPDALL─┬─)─┘
└─\NODFRWRT─┘ └─\NOUNDSPCHR─┘ └─\ACCUPDNE──┘

5───────────┬──────────────────────────────┬──────┬─────────────────────┬─────5
└─FLAG──(─┬─ð──────────────┬─)─┘ └─REPLACE─(─┬─\YES─┬)─┘
└─severity-level─┘ └─\NO──┘

Figure 4 (Part 1 of 5). Syntax of the CRTCBLPGM Command

Chapter 3. Compiling a Program 29


5───────────┬─────────────────────────────┬───────┬──────────────────────┬────5
└TGTRLS─(─┬─\CURRENT──────┬───┘ └─USRPRF─(─┬─\USER──┬)─┘
├─\PRV──────────┤ └─\OWNER─┘
└─release-level─┘

5───────────┬──────────────────────────────────────┬──────────────────────────5
└─AUT──(─┬─\LIBCRTAUT──────────────┬─)─┘
├─\ALL────────────────────┤
├─\CHANGE─────────────────┤
├─\USE────────────────────┤
├─\EXCLUDE────────────────┤
└─authorization-list-name─┘

5───────────┬──────────────────────────────────────┬──────────────────────────5
└─TEXT──(─┬─\SRCMBRTXT───────────┬─)───┘
├─\BLANK───────────────┤
└─'description-text'───┘

5───────────┬───────────────────────────────────────────────────────────┬─────5
└─DUMP──(───starting-statement───────ending-statement───)───┘

5───────────┬───────────────────────┬────────────────────────────────────────5%
└─ITDUMP─(─dump-option─)┘

┌───────────────────────────────────┐
│Job: B,I Pgm: B,I REXX: B,I Exec│
└───────────────────────────────────┘
OPTION Details:

5──┬─\SRC──────┬─┬─\NOXREF─┬─┬─\GEN─────┬─┬─\NOSEQUENCE─┬─┬─\NOVBSUM────┬─────5
├─\SOURCE───┤ └─\XREF───┘ └─\NOGEN───┘ └─\SEQUENCE───┘ └─\VBSUM──────┘
├─\NOSRC────┤
└─\NOSOURCE─┘

5──┬─\NONUMBER───┬─┬─\NOMAP──┬─┬─\NOOPTIONS┬─┬───\QUOTE────┬─┬─\NOSECLVL───┬──5
├─\NUMBER─────┤ └─\MAP────┘ └─\OPTIONS──┘ └───\APOST────┘ └─\SECLVL─────┘
└─\LINENUMBER─┘

5──┬─\PRTCORR───┬─┬─\NOSRCDBG──┬─┬──\NOLSTDBG──┬─┬─\PRINT──────┬──────────────5
└─\NOPRTCORR─┘ └─\SRCDBG────┘ └──\LSTDBG────┘ └─\NOPRINT────┘

GENOPT Details:

5──┬─\NOLIST─┬───┬─\NOXREF─┬───┬─\NOPATCH─┬───┬─\NODUMP─┬───┬─\NOATR─┬────────5
└─\LIST───┘ └─\XREF───┘ └─\PATCH───┘ └─\DUMP───┘ └─\ATR───┘

Figure 4 (Part 2 of 5). Syntax of the CRTCBLPGM Command

5──┬─\RANGE───┬─┬\UNREF───┬─┬\NOOPTIMIZE─┬─┬\NODDSFILLER─┬─┬─\NOSYNC─┬────────5
└─\NORANGE─┘ └\NOUNREF─┘ └\OPTIMIZE───┘ └\DDSFILLER───┘ └─\SYNC───┘

Figure 4 (Part 3 of 5). Syntax of the CRTCBLPGM Command

5──┬─\NOCRTF─┬───┬─\NODUPKEYCHK─┬───┬─\STDERR────┬───┬─\NOEXTACCDSP──┬────────5
└─\CRTF───┘ └─\DUPKEYCHK───┘ └─\NOSTDERR──┘ └─\EXTACCDSP────┘

Figure 4 (Part 4 of 5). Syntax of the CRTCBLPGM Command

5──┬─\NOINZDLT──┬──┬──\NOBLK────┬───┬──\STDINZ───┬───┬─\FS21DUPKY────┬────────5
└─\INZDLT────┘ └──\BLK──────┘ └──\NOSTDINZ─┘ └─\NOFS21DUPKY──┘

Figure 4 (Part 5 of 5). Syntax of the CRTCBLPGM Command

30 COBOL/400 User’s Guide


Compiling Your Source Program For the Previous Release
You can compile a COBOL/400 program on an AS/400 system using the current
release of the OS/400 operating system and restore it on an AS/400 system that
uses a previous release of the operating system.

The Target Release (TGTRLS) parameter of the CRTCBLPGM command allows


you to specify the release level on which you intend to use the object program.
The TGTRLS parameter has three possible values: *CURRENT, *PRV and
release-level:
Specify *CURRENT if the object program is to be used on the release of the
operating system currently running on your system. For example, if V2R2M0 is
running on the system, *CURRENT means you intend to use the program on a
system with V2R2M0 installed. This value is the default.
Specify *PRV if the object program is to be used on the previous release with
modification level 0 of the operating system. For example, if V2R2M0 is
running on your system, *PRV means you intend to use the program on a
system with V2R1M0 installed.
release-level allows you to specify the release level on which you intend to use
the object program. The values you can enter for this parameter depend on
the current version, release, and modification level, and they change with each
new release.

For more information about the TGTRLS parameter, see page 26.

You should be aware of the following limitations:


Ÿ Support to compile for use with the previous release is only available when you
use the TGTRLS parameter of the CRTCBLPGM command. You must specify
*PRV or the release level when you compile the program; you must then save
the program, using the Save Object (SAVOBJ) or the Save Library (SAVLIB)
CL command, in order to successfully restore it to the previous release of the
operating system.
Ÿ You cannot use the TGTRLS parameter for COBOL programs created in the
System/38 environment.
Ÿ You can restore an object program to the previous release or to a subsequent
release. You cannot restore an object program on a system that is more than
one release lower. That is, only one release of downward compatibility is pro-
vided.
Ÿ You cannot use functions that are new to the current release of the operating
system in a program that you compile for use at the previous release level.
Ÿ Programs may be retranslated when they are restored to the previous release;
therefore, you cannot delete observability if the programs are to be retrans-
lated.
Ÿ No product library should be in the system portion of your library list.

Chapter 3. Compiling a Program 31


Using the PROCESS Statement to Specify Compiler Options
The PROCESS statement is an optional part of the COBOL source program. You
can use the PROCESS statement to specify options you would normally specify at
compilation time. Options specified in the PROCESS statement override the corre-
sponding options specified in the CRTCBLPGM CL command.

The format of the PROCESS statement is as follows:

Format

┌─────────┐
6 │
55───PROCESS────option-1──┴─────┬─────┬────────────────────────────────5%
└──.──┘

The following rules apply:


Ÿ The statement must be placed before the first source statement in the COBOL
program immediately preceding the IDENTIFICATION DIVISION header.
Ÿ The statement begins with the word PROCESS. Options can appear on more
than one line; however, only the first line can contain the word PROCESS.
Ÿ The word PROCESS and all options must appear within positions 8 through 72.
Position 7 must be left blank. The remaining positions can be used as in
COBOL source statements: positions 1 through 6 for sequence numbers, posi-
tions 73 through 80 for identification purposes.
Ÿ The options must be separated by blanks and/or commas.
Ÿ Options can appear in any order. If conflicting options are specified, for
example, LIST and NOLIST, the last option encountered takes precedence.
Ÿ If the option keyword is correct and the suboption is in error, the default sub-
option is assumed.

Not every CRTCBLPGM parameter has a corresponding option in the PROCESS


statement. Refer to the following tables which indicate the allowable PROCESS
statement options and the equivalent CRTCBLPGM command parameters and
options. Defaults are underlined. Descriptions of the PROCESS statement options
correspond to the parameter and option descriptions that start on page 18.

PROCESS Statement Option CRTCBLPGM


GENLVL Parameter Option
GENLVL(nn) nn

32 COBOL/400 User’s Guide


PROCESS Statement Options CRTCBLPGM
OPTION Parameter Options
GEN *GEN
NOGEN *NOGEN
NOMAP *NOMAP
MAP *MAP
NONUMBER *NONUMBER
NUMBER *NUMBER
LINENUMBER *LINENUMBER
NOSECLVL *NOSECLVL
SECLVL *SECLVL
NOOPTIONS *NOOPTIONS
OPTIONS *OPTIONS
QUOTE *QUOTE
APOST *APOST
NOSEQUENCE *NOSEQUENCE
SEQUENCE *SEQUENCE
SOURCE (or SRC) *SOURCE (or *SRC)
NOSOURCE *NOSOURCE
(or NOSRC) (or *NOSRC)
NOVBSUM *NOVBSUM
VBSUM *VBSUM
NOXREF *NOXREF
XREF *XREF
PRTCORR *PRTCORR
NOPRTCORR *NOPRTCORR

Chapter 3. Compiling a Program 33


PROCESS Statement Options CRTCBLPGM
GENOPT Parameter Options
NOINZDLT *NOINZDLT
INZDLT *INZDLT
NOLIST *NOLIST
LIST *LIST
STDERR *STDERR
NOSTDERR *NOSTDERR
NODDSFILLER *NODDSFILLER
DDSFILLER *DDSFILLER
NOSYNC *NOSYNC
SYNC *SYNC
NOCRTF *NOCRTF
CRTF *CRTF
NODUPKEYCHK *NODUPKEYCHK
DUPKEYCHK *DUPKEYCHK
NOEXTACCDSP *NOEXTACCDSP
EXTACCDSP *EXTACCDSP
NOBLK *NOBLK
BLK *BLK
STDINZ *STDINZ
NOSTDINZ *NOSTDINZ
FS21DUPKEY *FS21DUPKY
NOFS21DUPKEY *NOFS21DUPKY
RANGE *RANGE
NORANGE *NORANGE
UNREF *UNREF
NOUNREF *NOUNREF

PROCESS Statement Options CRTCBLPGM


CVTOPT Parameter Options
NOVARCHAR *NOVARCHAR
VARCHAR *VARCHAR
NODATETIME *NODATETIME
DATETIME *DATETIME
NOCVTGRAPHIC *NOGRAPHIC
CVTGRAPHIC *GRAPHIC

34 COBOL/400 User’s Guide


PROCESS Statement Options CRTCBLPGM
FLAGSTD Parameter Options
NOFIPS *NOFIPS
MINIMUM *MINIMUM
INTERMEDIATE *INTERMEDIATE
HIGH *HIGH
NOSEG *NOSEG
SEG1 *SEG1
SEG2 *SEG2
NODEB *NODEB
DEB1 *DEB1
DEB2 *DEB2
NOOBSOLETE *NOOBSOLETE
OBSOLETE *OBSOLETE

PROCESS Statement Options CRTCBLPGM


EXTDSPOPT(a b c)
EXTDSPOPT Parameter Options
DFRWRT *DFRWRT
NODFRWRT *NODFRWRT
UNDSPCHR *UNDSPCHR
NOUNDSPCHR *NOUNDSPCHR
ACCUPDALL *ACCUPDALL
ACCUPDNE *ACCUPDNE

PROCESS Statement Options CRTCBLPGM


SAAFLAG Parameter Options
NOSAAFLAG *NOFLAG
SAAFLAG *FLAG

PROCESS Statement Option CRTCBLPGM


FLAG Parameter Option
FLAG(nn) nn

PROCESS Statement Options CRTCBLPGM


NOFS9MTO0M not applicable
FS9MTO0M
NOGRAPHIC not applicable
GRAPHIC

FS9MTO0M changes a file status of 9M to a file status of 0M.

Chapter 3. Compiling a Program 35


The GRAPHIC option of the PROCESS statement is available for processing DBCS
characters in DBCS literals. See Appendix F, “Supporting International Languages
with Double-Byte Character Sets” on page 337 for information about DBCS
support.

The EXTDSPOPT option on the PROCESS statement should be coded with the
associated options in brackets similar to FLAG(nn) syntax. You can specify more
than one option within the brackets for the EXTDSPOPT option. For example, to
specify DFRWRT and UNDSPCHR, type
EXTDSPOPT(DFRWRT UNDSPCHR)
It is also valid to specify EXTDSPOPT or EXTDSPOPT( ).

When EXTDSPOPT alone is specified in the PROCESS statement, then all the
default values for the additional options are in effect.

If you specify EXTDSPOPT( ), it has no effect on your program.

If conflicting options are specified, the last option specified overrides the others.

Compiling Multiple Programs


The PROCESS statement can be used to separate multiple programs and/or sub-
programs to be compiled with a single invocation of the compiler. (A subprogram
is a called program that is combined with the calling program at run time to produce
a run unit.) When compiling multiple programs, all compiler options specified on
the CRTCBLPGM command statement, plus all default options, plus the options
specified on the last PROCESS statement preceding the program will be in effect
for the compilation of that program. All compiler output is directed to the destina-
tions specified by the CRTCBLPGM command statement.

All object programs are stored in the library specified on the PGM parameter. If
program-name is specified for the PGM parameter, the first program in the batch
job has that name, and all other programs use the name specified in the
PROGRAM-ID paragraph in the source program.

Using COPY within the PROCESS Statement


A COPY statement can be used in the source program wherever a character-string
or separator can be used. Each COPY statement must be preceded by a space
and followed by a period and a space. For more information on the COPY state-
ment, refer to the “COPY Statement” section of the COBOL/400 Reference.

The Format 1 COPY statement can be used within the PROCESS statement to
retrieve compiler options previously stored in a source library, and include them in
the PROCESS statement. COPY can be used to include options that override
those specified as defaults by the compiler. Any PROCESS statement options can
be retrieved with the COPY statement.

Compiler options can both precede and follow the COPY statement within the
PROCESS statement. The last encountered occurrence of an option overrides all
preceding occurrences of that option.

36 COBOL/400 User’s Guide


The following example shows the use of the COPY statement within the PROCESS
statement. The COPY statement must be followed by a period. Notice also that, in
this example, NOMAP overrides the corresponding option in the library member:

ððððð1 PROCESS XREF MYPROG


ððððð2 COPY DEFLTS. MYPROG
MAP, SOURCE, LIST DEFLTS
ððððð4 NOMAP, FLAG(2ð) MYPROG
ðððð1ð IDENTIFICATION DIVISION. MYPROG

Understanding Compiler Output


Compiler output can include:
Ÿ A summary of command options
Ÿ An options listing: a listing of options in effect for the compilation. Use
OPTION(*OPTIONS).
Ÿ A source listing: a listing of the statements contained in the source program.
Use OPTION(*SOURCE or *SRC).
Ÿ A verb usage listing: a listing of the COBOL verbs and the number of times
each verb is used. Use OPTION(*VBSUM).
Ÿ A Data Division map: a glossary of compiler-generated information about the
data. Use OPTION(*MAP). Also included is a mapping of user-supplied
names to compiler-generated internal names.
Ÿ SAA flagging: a list of the functions in your program that are not portable to
other SAA COBOL environments. Use SAAFLAG(*FLAG).
Ÿ FIPS messages: a list of messages for a FIPS COBOL subset, for any of the
optional modules, for all of the obsolete language elements, or for a combina-
tion of a FIPS COBOL subset, optional modules and all obsolete elements.
Refer to the information on the “FLAGSTD Parameter” on page 25 for the spe-
cific options available for FIPS flagging.
Ÿ A cross-reference listing. Use OPTION(*XREF).
Ÿ Compiler messages (including diagnostic statistics).
Ÿ Compilation statistics.
Ÿ A listing of the generated program in symbolic form.
Ÿ An object program.

The presence or absence of some of these types of compiler output is determined


by options specified in the PROCESS statement or through the CRTCBLPGM
command. The level of diagnostic messages printed depends upon the FLAG
option.

Chapter 3. Compiling a Program 37


Specifying the Format of Your Listing
A slash (/) in the indicator area (column 7) of a line results in page ejection of the
source program listing. The slash (/) comment line prints on the first line of the
next page.

IBM Extension

If you specify the EJECT statement in your program, the next source statement
prints at the top of the next page in the compiler listing. This statement may be
written anywhere in Area A or Area B and must be the only statement on the line.

The SKIP1/2/3 statement causes blank lines to be inserted in the compiler listing.
A SKIP1/2/3 statement can be written anywhere in Area A or B. It must be the only
statement on the line.
Ÿ SKIP1 inserts a single blank line (double spacing).
Ÿ SKIP2 inserts two blank lines (triple spacing).
Ÿ SKIP3 inserts three blank lines (quadruple spacing).

Each of the above SKIP statements causes a single insertion of one, two, or three
lines.

A TITLE statement places a title on each indicated page.

You can selectively list or suppress your COBOL source statements by using the
*CONTROL, *CBL, or COPY statements:
Ÿ *CONTROL NOSOURCE and *CBL NOSOURCE suppress the listing of source
statements.
Ÿ *CONTROL SOURCE and *CBL SOURCE continue the listing of source state-
ments.
Ÿ A COPY statement bearing the SUPPRESS phrase suppresses the listing of
copied statements. For its duration, this statement overrides any *CONTROL
or *CBL statement. If the copied member contains *CONTROL or *CBL state-
ments, the last one runs once the COPY member has been processed.

Refer to the COBOL/400 Reference for additional information about the EJECT,
SKIP1/2/3, *CONTROL, *CBL, COPY, and TITLE statements.

End of IBM Extension

Time-Separation Characters
The TIMSEP parameter of job-related commands (such as CHGJOB) now specifies
the time-separation character used in the time stamps that appear on compiler
listings. In the absence of a TIMSEP value, the system value QTIMSEP is used by
default.

38 COBOL/400 User’s Guide


Browsing Your Compiler Listing Using SEU
The Source Entry Utility (SEU) allows you to browse through a compiler listing in an
output queue. You can review the results of a previous compilation while making
the required changes to your source code. Figure 5 shows the split-display in SEU
that allows you to browse through the listing from a work station.

à@ ð
Columns . . . : 1 71 Edit XMPLIB/QLBLSRC
SEU==> XMPLE
FMT CB ......-A+++B+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ðð14.ðð DATA DIVISION.
ðð15.ðð FILE SECTION.
ðð16.ðð FD FILE1
ðð17.ðð RECORD CONTAINS 56 CHARACTERS
ðð18.ðð LABEL RECORDS ARE OMITTED
ðð19.ðð DATA RECORD IS REB-1.
ðð2ð.ðð ð1 REC-1 PIC X(56).
_______________________________________________________________________________
Columns . . . : 1 71 Browse Spool file . . : XMPLE
SEU==>
ðððð.5ð STMT
ðððð.51 \ 19 MSGID: LBL1327 SEVERITY: 3ð SEQNBR: ðð19ðð
ðððð.52 Message . . . . : 'REB-1' not defined in the program. Clause
ðððð.53 ignored.
ðððð.54 \ \ \ \ \ E N D O F M E S S A G E S \ \
ðððð.55 Message Summary
ðððð.56 Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39)

F6=Move split line F19=Left F2ð=Right


F21=System command F24=More keys
Syntax error found.
á ñ
Figure 5. SEU Split Edit/Browse Display

While browsing the compiler listing, you can scan for errors and correct those
source statements that have errors. To scan for errors, type F \ERR on the SEU
command line.

For complete information on browsing through a compiler listing, see the SEU
User’s Guide and Reference.

A Sample Program and Listing


The following pages illustrate the compiler options and source listing produced for
the program example. References to the figures are made throughout the following
text. These references are indexed by the reverse printing of letters on a black
background, for example (.Z/). The reverse letters in the text correspond to the
letters found in the figures.

Command Summary
This summary, which is produced as a result of compilation, lists all options speci-
fied in the CRTCBLPGM command. Refer to “Using the Create COBOL Program
(CRTCBLPGM) Command” on page 15 for more information about user-defined
options.

Chapter 3. Compiling a Program 39


5763CB1 V3RðM5 ðð1ððð IBM SAA COBOL/4ðð TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 1
Program . . . . . . . . . . . . . . : SAMPLE
Library . . . . . . . . . . . . . : TESTER
Source file . . . . . . . . . . . . : QLBLSRC
Library . . . . . . . . . . . . . : TESTER
Source member . . . . . . . . . . . : SAMPLE ð3/27/94 11:ð1:34
Generation severity level . . . . . : 29
Text 'description' . . . . . . . . . : \BLANK
Source listing options . . . . . . . : \NONE
Generation options . . . . . . . . . : \NONE
Conversion options . . . . . . . . . : \NONE
Message limit:
Number of messages . . . . . . . . : \NOMAX
Message limit severity . . . . . . : 29
Print file . . . . . . . . . . . . . : QSYSPRT
Library . . . . . . . . . . . . . : \LIBL
FIPS flagging . . . . . . . . . . . : \NOFIPS \NOSEG \NODEB \NOOBSOLETE
SAA flagging . . . . . . . . . . . . : \NOFLAG
Extended display options . . . . . . :
Flagging severity . . . . . . . . . : ð
Replace program . . . . . . . . . . : \YES
Target release . . . . . . . . . . . : \CURRENT
User profile . . . . . . . . . . . . : \USER
Authority . . . . . . . . . . . . . : \LIBCRTAUT
Compiler . . . . . . . . . . . . . . : IBM SAA COBOL/4ðð

Figure 6. Command Summary Listing

Identifying the Compiler Options in Effect


The PROCESS statement, if specified, is printed first. Figure 7 is a list of all
options in effect for the compilation of the program example: the options specified
in the CRTCBLPGM command, as modified by the PROCESS statement. Compiler
options are listed at the beginning of all compiler output when the OPTIONS
parameter is specified.

40 COBOL/400 User’s Guide


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð PROCESS OPTIONS, SAAFLAG, SOURCE, MAP, XREF, ð3/27/94
2 ððð2ðð FLAG(ðð), MINIMUM, VBSUM.
COBOL Compiler Options in Effect
OPTIONS
SOURCE
XREF
MAP
VBSUM
NONUMBER
NOSEQUENCE
GEN
GENLVL(29)
FLAG( ð)
MINIMUM
NOSEG
NODEB
NOOBSOLETE
SAAFLAG
QUOTE
NOSECLVL
NOSRCDBG
NOLSTDBG
PRINT
PRTCORR
COBOL Generation Options in Effect
NOLIST
UNREF
RANGE
NOATR
NOXREF
NODUMP
NOPATCH
NOOPTIMIZE
NODDSFILLER
NOSYNC
NOCRTF
NODUPKEYCHK
STDERR
NOEXTACCDSP
NOINZDLT
NOFS9MTOðM
NOBLK
STDINZ
FS21DUPKY
COBOL Conversion Options in Effect
NOVARCHAR
NODATETIME
NOGRAPHIC

Figure 7. List of Options in Effect

Source Listing
Figure 8 illustrates a source listing. The statements in the source program are
listed exactly as submitted. The source is not listed if the NOSOURCE option is
specified. After the page in which the PROGRAM-ID paragraph is listed, all com-
piler output pages have the program-id name listed in the heading before the
system name.

Chapter 3. Compiling a Program 41


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 4
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
.A/ .B/ .C/ .D/ .E/
3 ððð3ðð IDENTIFICATION DIVISION.
4 ððð4ðð PROGRAM-ID. SAMPLE.
5 ððð5ðð AUTHOR. PROGRAMMER NAME.
6 ððð6ðð INSTALLATION. COBOL DEVELOPMENT CENTRE.
7 ððð7ðð DATE-WRITTEN. 11/27/87.
8 ððð8ðð DATE-COMPILED. ð3/27/94 11:ð1:51 .
9 ððð9ðð ENVIRONMENT DIVISION.
1ð ðð1ððð CONFIGURATION SECTION.
11 ðð11ðð SOURCE-COMPUTER. IBM-AS4ðð. ð3/27/94
12 ðð12ðð OBJECT-COMPUTER. IBM-AS4ðð. ð3/27/94
13 ðð13ðð INPUT-OUTPUT SECTION.
14 ðð14ðð FILE-CONTROL.
15 ðð15ðð SELECT FILE-1 ASSIGN TO DISK-SAMPLE.
16 ðð16ðð DATA DIVISION.
17 ðð17ðð FILE SECTION.
18 ðð18ðð FD FILE-1
19 ðð19ðð LABEL RECORDS ARE STANDARD
2ð ðð2ððð RECORD CONTAINS 2ð CHARACTERS
21 ðð21ðð DATA RECORD IS RECORD-1.
22 ðð22ðð ð1 RECORD-1.
23 ðð23ðð ð2 FIELD-A PIC X(2ð).
24 ðð24ðð WORKING-STORAGE SECTION.
25 ðð25ðð ð1 FILLER.
26 ðð26ðð ð5 KOUNT PIC S9(2) COMP-3.
27 ðð27ðð ð5 LETTERS PIC X(26) VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
28 ðð28ðð ð5 ALPHA REDEFINES LETTERS
29 ðð29ðð PIC X(1) OCCURS 26 TIMES.
3ð ðð3ððð ð5 NUMBR PIC S9(2) COMP-3.
31 ðð31ðð ð5 DEPENDENTS PIC X(26) VALUE "ð1234ð1234ð1234ð1234ð1234ð".
32 ðð32ðð ð5 DEPEND REDEFINES DEPENDENTS
33 ðð33ðð PIC X(1) OCCURS 26 TIMES.
34 ðð34ðð COPY WRKRCD.
35 +ðððð1ð ð1 WORK-RECORD. WRKRCD
36 +ðððð2ð ð5 NAME-FIELD PIC X(1). WRKRCD
37 +ðððð3ð ð5 FILLER PIC X(1) VALUE SPACE. WRKRCD
38 +ðððð4ð ð5 RECORD-NO PIC S9(3). WRKRCD
39 +ðððð5ð ð5 FILLER PIC X(1) VALUE SPACE. WRKRCD
4ð +ðððð6ð ð5 LOCATION PIC A(3) VALUE "NYC". WRKRCD
41 +ðððð7ð ð5 FILLER PIC X(1) VALUE SPACE. WRKRCD
42 +ðððð8ð ð5 NO-OF-DEPENDENTS WRKRCD
43 +ðððð9ð PIC X(2). WRKRCD
44 +ððð1ðð ð5 FILLER PIC X(7) VALUE SPACES. WRKRCD
45 ðð35ðð 77 WORKPTR USAGE POINTER.
ðð36ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð37ðð\ THE FOLLOWING PARAGRAPH OPENS THE OUTPUT FILE TO \
ðð38ðð\ BE CREATED AND INITIALIZES COUNTERS \
ðð39ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
46 ðð4ððð PROCEDURE DIVISION.
ðð41ðð STEP-1.
47 ðð42ðð OPEN OUTPUT FILE-1.
48 ðð43ðð MOVE ZERO TO KOUNT, NUMBR.
ðð44ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð45ðð\ THE FOLLOWING 3 PARAGRAPHS CREATE INTERNALLY THE \
ðð46ðð\ RECORDS TO BE CONTAINED IN THE FILE, WRITES THEM \
ðð47ðð\ ON THE DISK, AND DISPLAYS THEM \
ðð48ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð49ðð STEP-2.
49 ðð5ððð ADD 1 TO KOUNT, NUMBR.
5ð ðð51ðð MOVE ALPHA (KOUNT) TO NAME-FIELD.
51 ðð52ðð MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS.
52 ðð53ðð MOVE NUMBR TO RECORD-NO.
ðð54ðð STEP-3.
53 ðð55ðð DISPLAY WORK-RECORD.
54 ðð56ðð WRITE RECORD-1 FROM WORK-RECORD.
ðð57ðð STEP-4.

Figure 8 (Part 1 of 2). An Example of a COBOL/400 Source Listing

42 COBOL/400 User’s Guide


55 ðð58ðð PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
ðð59ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð6ððð\ THE FOLLOWING PARAGRAPH CLOSES FILE OPENED FOR \
ðð61ðð\ OUTPUT AND RE-OPENS IT FOR INPUT \
ðð62ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð63ðð STEP-5.
56 ðð64ðð CLOSE FILE-1.
57 ðð65ðð OPEN INPUT FILE-1.
ðð66ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð67ðð\ THE FOLLOWING PARAGRAPHS READS BACK THE FILE AND \
ðð68ðð\ SINGLES OUT EMPLOYEES WITH NO DEPENDENTS \
ðð69ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð7ððð STEP-6.
58 ðð71ðð READ FILE-1 RECORD INTO WORK-RECORD
59 ðð72ðð AT END GO TO STEP-8.
ðð73ðð STEP-7.
6ð ðð74ðð IF NO-OF-DEPENDENTS IS EQUAL TO "ð"
61 ðð75ðð MOVE "Z" TO NO-OF-DEPENDENTS.
62 ðð76ðð GO TO STEP-6.
ðð77ðð STEP-8.
63 ðð78ðð CLOSE FILE-1.
64 ðð79ðð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 8 (Part 2 of 2). An Example of a COBOL/400 Source Listing

Figure 8 displays the following fields:


.A/ Compiler-generated statement number: The numbers appear to the left of
the source program listing. These numbers are referenced in all compiler
output listings except for FIPS messages listings. A statement number can
span several lines, and a line can contain more than one statement.
.B/ Reference number: The numbers appear to the left of the source state-
ments. The numbers that appear in this field and the column heading
(shown as SEQNBR in this listing) are determined by an option specified in
the CRTCBLPGM command or in the PROCESS statement, as shown in
the following table:

Option Heading Origin


NONUMBER SEQNBR Source-file sequence numbers
NUMBER NUMBER Standard COBOL sequence numbers
LINENUMBER LINNBR Compiler-generated sequence numbers

.C/ Sequence error indicator column: An S in this column indicates that the
line is out of sequence. Sequence checking is performed on the reference
number field only if the SEQUENCE option is specified.
.D/ Copyname: The copyname, as specified in the COBOL COPY statement,
is listed here for all records included in the source program by that COPY
statement. If the DDS-ALL-FORMATS phrase is used, the name
<--ALL-FMTS appears under COPYNAME.
.E/ Change/date field: The date the line was last modified is listed here.

Verb Usage by Count Listing


Figure 9 shows the alphabetic list that is produced of all verbs used in the source
program. A count of how many times each verb was used is also included. This
listing is produced when the VBSUM option is specified.

Chapter 3. Compiling a Program 43


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Verb Usage By Count TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 6
VERB COUNT
ADD 1
CLOSE 2
DISPLAY 1
GO 2
IF 1
MOVE 5
OPEN 2
PERFORM 1
READ 1
STOP 1
WRITE 1
\ \ \ \ \ E N D O F V E R B U S A G E B Y C O U N T \ \ \ \ \

Figure 9. Verb Usage by Count Listing

Data Division Map


The Data Division map is listed when the MAP option is specified. It contains infor-
mation about names in the COBOL source program. The number of bytes required
for the File Section and Working-Storage Section is given at the end of the Data
Division map.

5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Data Division Map TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 7
STMT LVL SOURCE NAME SECTION DISP LENGTH TYPE I-NAME ATTRIBUTES
.F/ .G/ .H/ .I/ .J/ .K/ .L/ .M/ .N/
18 FD FILE-1 FS .Fð1 DEVICE DISK, ORGANIZATION SEQUENTIAL,
ACCESS SEQUENTIAL, RECORD CONTAINS 2ð
CHARACTERS, LABEL RECORDS STANDARD
22 ð1 RECORD-1 FS ðððððððð 2ð GROUP .Dðð633C
23 ð2 FIELD-A FS ðððððððð 2ð AN .Dðð63AE
25 ð1 FILLER WS ðððððððð 56 GROUP .Dðð642ð
26 ð2 KOUNT WS ðððððððð 2 PACKED .Dðð649ð
27 ð2 LETTERS WS ððððððð2 26 AN .Dðð6512 VALUE
28 ð2 ALPHA WS ððððððð2 1 AN .Dðð65Bð REDEFINES .Dðð6512, DIMENSION(26)
3ð ð2 NUMBR WS ðððððð28 2 PACKED .Dðð6632
31 ð2 DEPENDENTS WS ðððððð3ð 26 AN .Dðð66B4 VALUE
32 ð2 DEPEND WS ðððððð3ð 1 AN .Dðð6754 REDEFINES .Dðð66B4, DIMENSION(26)
35 ð1 WORK-RECORD WS ðððððððð 19 GROUP .Dðð67D6
36 ð2 NAME-FIELD WS ðððððððð 1 AN .Dðð684C
37 ð2 FILLER WS ððððððð1 1 AN .Dðð68Cð VALUE
38 ð2 RECORD-NO WS ððððððð2 3 ZONED .Dðð693C
39 ð2 FILLER WS ððððððð5 1 AN .Dðð69C2 VALUE
4ð ð2 LOCATION WS ððððððð6 3 A .Dðð7A98 VALUE
41 ð2 FILLER WS ððððððð9 1 AN .Dðð7B2ð VALUE
42 ð2 NO-OF-DEPENDENTS WS ðððððð1ð 2 AN .Dðð7B9C
44 ð2 FILLER WS ðððððð12 7 AN .Dðð7C16 VALUE
45 77 WORKPTR WS ðððððððð 16 POINTR .Dðð7C92
FILE SECTION uses 2ð bytes of storage
WORKING-STORAGE SECTION uses 75 bytes of storage
\ \ \ \ \ E N D O F D A T A D I V I S I O N M A P \ \ \ \ \

Figure 10. Data Division Map

The Data Division map displays the following fields:


.F/ Statement number: The compiler-generated statement number where the
data item was defined is listed for each data item in the Data Division map.
.G/ Level of data item: The level number of the data item, as specified in the
source program, is listed here. Index-names are identified by an IX in the
level-number and a blank type field.
.H/ Source name: The data name, as specified in the source program, is listed
here.

44 COBOL/400 User’s Guide


.I/ Section: The section where the item was defined is shown here through
the use of the following codes:
FS File Section
WS Working-Storage Section
LS Linkage Section
SM Sort/Merge Section
SR Special Register.
.J/ Displacement: The offset, in bytes, of the item from the level-01 group item
is given here.
.K/ Length: The decimal length of the item is listed here.
.L/ Type: The data class type for the item is shown here through the use of
the following codes:

GROUP Group Item


A Alphabetic
AN Alphanumeric
ANE Alphanumeric edited
INDEX Index data item (USAGE INDEX)
BOOLN Boolean
ZONED Zoned decimal (external decimal)
PACKED Packed decimal (internal decimal) (USAGE COMP, COMP-3
or PACKED-DECIMAL)
BINARY Binary (USAGE COMP-4 or BINARY)
NE Numeric edited
POINTR Pointer data item (USAGE POINTER)

.M/ Internal name: The compiler-generated internal names are listed here and
are assigned as follows:
File names
The internal name uses the form .Fnn, where .F indicates a file name, and
nn is a unique two-digit number.
Data names
The internal name uses the form .Dxxxxxx, where .D indicates a data name
or index name, and xxxxxx is a unique six-digit hex value. These names
appear in the IRP listing if generated.
.N/ Attributes: The attributes of the item are listed here as follows:
Ÿ For files, the following information can be given:
Device type
ORGANIZATION
ACCESS MODE
BLOCK CONTAINS information
RECORD CONTAINS information
LABEL information
RERUN is indicated
SAME AREA is indicated
CODE-SET is indicated
SAME RECORD AREA is indicated
LINAGE is indicated.

Chapter 3. Compiling a Program 45


Ÿ For data items, the attributes indicate if the following information was
specified for the item:
REDEFINES
VALUE
JUSTIFIED
SYNCHRONIZED
BLANK WHEN ZERO
SIGN IS LEADING
SIGN IS LEADING SEPARATE
SIGN IS SEPARATE
INDICATORS.
Ÿ For table items, the dimensions for the item are listed here in the form
DIMENSION (nn). For each dimension, a maximum OCCURS value is
given. When a dimension is a variable, it is listed as such, giving the
lowest and highest OCCURS values.

FIPS Messages
The FIPS messages, Figure 11, are listed when the FLAGSTD parameter is speci-
fied. See page 25 for more information about specifying the option for FIPS flag-
ging. Only messages for the requested FIPS subset, optional modules and/or
obsolete elements are listed.
Note: The sequence number and column number are given for each time the
message is issued.

5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL FIPS Messages TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 8
FIPS-ID DESCRIPTION AND SEQUENCE NUMBERS FLAGGED.P/
.O/
LBL82ðð Following nonconforming standard items valid only at FIPS intermediate level or higher.
LBL82ð1 COPY statement.
ðð34ðð ððð8
LBL83ðð Following nonconforming standard items valid only at FIPS high level. .Q/
LBL83ð3 DATE-COMPILED paragraph.
ððð8ðð ðð1ð
LBL85ðð Following nonconforming nonstandard items are IBM-defined or are IBM extensions. .Q/
LBL85ð4 Assignment-name in ASSIGN clause.
ðð15ðð ðð36
LBL8518 USAGE IS COMPUTATIONAL-3.
ðð26ðð ðð36
ðð3ððð ðð36
LBL852ð USAGE IS POINTER.
ðð35ðð ðð26
LBL8561 COPY statement with default library assumed.
ðð34ðð ðð19
7 FIPS violations flagged..R/
\ \ \ \ \ E N D O F C O B O L F I P S M E S S A G E S \ \ \ \ \

Figure 11. FIPS Messages

The FIPS messages consist of the following fields:


.O/ FIPS-ID: This field lists the FIPS message number.
.P/ Description and reference numbers flagged: This field lists a description of
the condition flagged, followed by a list of the reference numbers from the
source program where this condition is found.

46 COBOL/400 User’s Guide


The type of reference numbers used, and their names in the heading
(shown as SEQUENCE NUMBERS in this listing) are determined by an
option specified in the CRTCBLPGM command or in the PROCESS state-
ment, as shown in the following table:

Option Heading
NONUMBER DESCRIPTION AND SEQUENCE NUMBERS FLAGGED
NUMBER DESCRIPTION AND USER-SUPPLIED NUMBERS
FLAGGED
LINENUMBER DESCRIPTION AND LINE NUMBERS FLAGGED

.Q/ Items grouped by level: These headings subdivide the FIPS messages by
level and category.
.R/ FIPS violations flagged: The total number of FIPS violations flagged is
included at the end of the FIPS listing.

SAA Messages
Figure 12 shows the SAA messages that are listed when you specify the SAA flag-
ging option. See the SAAFLAG parameter on page 25 or “Using the PROCESS
Statement to Specify Compiler Options” on page 32 for more information about
specifying this option.

5763CB1 V3RðM5 ðð1ððð SAA COBOL Messages TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 9
MSGID DESCRIPTION, SEQUENCE NUMBERS and COLUMN NUMBERS FLAGGED

LBL88ðð The following items have been flagged as non-portable across other SAA COBOL systems.
LBL88ð1 Options APOST,NUMBER,SEQUENCE,GRAPHIC,NOCRTF,NODUPKEYCHK,NOSYNC and EXTACCDSP are not SAA COBOL.
ððð1ðð ððð8
LBL88ð9 PROCESS statement.
ððð1ðð ððð8
LBL8843 USAGE IS POINTER.
ðð35ðð ðð26
3 SAA COBOL Messages were flagged.
\ \ \ \ \ E N D O F S A A C O B O L M E S S A G E S \ \ \ \ \

Figure 12. SAA Messages

For more information about SAA flagging, see “SAA Flagging” on page 333.

Cross-Reference Listing
Figure 13 shows the cross-reference listing, which is produced when the XREF
option is specified. It provides a list of all data references and procedure-name
references, by statement number, within the source program.

Chapter 3. Compiling a Program 47


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Cross Reference Listing TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 1ð
NAMES (\ = Procedure-name) DEFINED REFERENCES (\ = Changed)
.S/ .T/ .U/
ALPHA 28 5ð
DEPEND 32 51
DEPENDENTS 31 32
\DUMMY-SECTION 47
FIELD-A 23
FILE-1 18 15 47 56 57 58 63
KOUNT 26 48\ 49\ 5ð 51 55
LETTERS 27 28
LOCATION 4ð
NAME-FIELD 36 5ð\
NO-OF-DEPENDENTS 42 51\ 6ð 61\
NUMBR 3ð 48\ 49\ 52
RECORD-NO 38 52\
RECORD-1 22 21 54\
\STEP-1 47
\STEP-2 49 55
\STEP-3 53 55
\STEP-4 55
\STEP-5 56
\STEP-6 58 62
\STEP-7 6ð
\STEP-8 63 59
WORK-RECORD 35 53 54 58\
WORKPTR 45
\ \ \ \ \ E N D O F C R O S S R E F E R E N C E \ \ \ \ \

Figure 13. Cross-Reference Listing

The cross-reference listing displays the following fields:


.S/ Names field: The data name or procedure name referenced is listed here.
All procedure names are flagged with an * before the name. The names
are listed alphabetically.
.T/ Defined field: The statement number where the name was defined within
the source program is listed here.
.U/ References field: All statement numbers are listed in the same sequence
as the name is referenced in the source program. An * following a state-
ment number indicates that the item was modified in that statement.

Messages
Figure 14 shows the messages that are generated during program compilation.

5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Messages TESTER/SAMPLE AS4ððSYS ð3/27/94 11:ð1:51 Page 11
STMT .X/
\.V/ 18 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ðð18ðð .W/
Message . . . . : Blocking/Deblocking for file 'FILE-1' will
be performed by compiler-generated code. .Y/
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
.Z/ 1 1 ð ð ð ð
Source records read . . . . . . . . : 79
Copy records read . . . . . . . . . : 1ð
Copy members processed . . . . . . : 1
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program SAMPLE created in library TESTER.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 14. Diagnostic Messages

48 COBOL/400 User’s Guide


The fields displayed are:
.V/ Statement number: This field lists the compiler-generated statement
number associated with the statement in the source program for which the
message was issued.1
.W/ Reference number: The reference number is issued here.1 The numbers
that appear in this field and the column heading (shown here as SEQNBR)
are determined by an option specified in the CRTCBLPGM command or in
the PROCESS statement, as shown in the following table:

Option Heading Origin


NONUMBER SEQNBR Source-file sequence numbers
NUMBER NUMBER User-supplied sequence numbers
LINENUMBER LINNBR Compiler-generated sequence numbers

When a message is issued for a record from a copy file, the number is
preceded by a +.
.X/ MSGID and Severity Level: These fields contain the message number and
its associated severity level. Severity levels are defined as follows:

ðð Informational
1ð Warning
2ð Error
3ð Severe Error
4ð Unrecoverable (usually a user error)
5ð Unrecoverable (usually a compiler error)

.Y/ Message: The message identifies the condition and indicates the action
taken by the compiler.
.Z/ Message statistics: This field lists the total number of messages and the
number of messages by severity level.
The totals listed are the number of messages generated for each severity
by the compiler and are not always the number listed. For example, if
FLAG(10) is specified, no messages of severity less than 10 are listed.
The counts, however, do indicate the number that would have been printed
if they had not been suppressed.

1 The statement number and the reference number do not appear on certain messages that reference missing items. For example,
if the PROGRAM-ID paragraph is missing, message LBL0031 appears on the listing with no statement or reference number listed.

Chapter 3. Compiling a Program 49


50 COBOL/400 User’s Guide
Chapter 4. Running Your COBOL Program
This chapter provides the information you need to run your COBOL/400 program.

The most common ways to run a COBOL program are:


Ÿ Using a Control Language (CL) CALL command
Ÿ Using the COBOL CALL statement
Ÿ Using a menu-driven application program
Ÿ Issuing a user-created command.

You can use a CL CALL command interactively, as part of a batch job, or include it
in a CL program. An example of a CL CALL command is CALL PAYROLL.
PAYROLL is the name of a COBOL program that is called and run.

Any COBOL program can call another program with the COBOL CALL statement.
(See the “CALL Statement” section of the COBOL/400 Reference for more informa-
tion.)

Another way to run a COBOL program is from a menu-driven application. The


work station user selects an option from a menu, calling the appropriate program.
The following figure illustrates an example of an application menu.

à@ ð
PAYROLL DEPARTMENT MENU

1. Inquire into employee master


2. Change employee master
3. Add new employee
4. Return

Option:____

Figure 15. Example of an Application Menu

The menu shown in this figure is normally displayed by a CL program in which


each option calls a separate COBOL program.

You can also create a command yourself to run a COBOL program by using a
command definition. A command definition is an object that contains the defi-
nition of a command (including the command name, parameter descriptions, and
validity-checking information), and identifies the program that performs the function
requested by the command. The system-recognized identifier for the object is
*CMD.

For example, you can create a command, PAY, that calls a program, PAYROLL.
PAYROLL is the name of a COBOL program that is called and run. You can enter
the command interactively, or in a batch job. See the CL Programmer’s Guide for
further information about using the command definition.

When a COBOL program ends normally, the system returns control to the caller.
The caller could be a work station user, a CL program (such as the menu-handling
program), or another COBOL program.

 Copyright IBM Corp. 1994 51


If a COBOL program ends abnormally during run time, the escape message
LBE9001
Error message-id caused program to end.
is issued. A CL program can monitor for this exception by using the Monitor
Message (MONMSG) command. See the CL Reference for more information about
control language commands.

If a program ends for any reason other than by the use of the STOP statement or
by falling through to the end of the program, the return code is set to 2. See the
RTVJOBA and DSPJOB commands in the CL Programmer’s Guide for more infor-
mation about return codes.

When you are running a batch job that uses the ACCEPT statement, the input data
is taken from the job stream. This data must be placed immediately following the
CL CALL for the COBOL program. It is your responsibility to request (through mul-
tiple ACCEPT statements) the same amount of data as is available. See the
“ACCEPT Statement” section of the COBOL/400 Reference for more information.
Note: If more data is requested than is available, the CL command following the
data is treated as input data. If more data is available than is requested,
each extra line of data is treated as a CL command. In each instance,
undesirable results can occur.

Replying to Run-Time Inquiry Messages


When you run a COBOL program, run-time inquiry messages may be generated.
The messages require a response before the program continues running.

You can add the inquiry messages to a system reply list to provide automatic
replies to the messages. The replies for these messages may be specified individ-
ually or generally. This method of replying to inquiry messages is especially suit-
able for batch programs, which would otherwise require an operator to issue
replies.

You can add the following COBOL/400 inquiry messages to the system reply list:
LBE7200
LBE7201
LBE7203
LBE7204
LBE7205
LBE7206
LBE7207
LBE7208
LBE7209
LBE7210
LBE7211
LBE7604.

The reply list is only used when an inquiry message is sent by a job that has the
Inquiry Message Reply (INQMSGRPY) attribute specified as INQMSGRPY(\SYSRPYL).

The INQMSGRPY parameter occurs on the following CL commands:


Ÿ Change Job (CHGJOB)
Ÿ Change Job Description (CHGJOBD)

52 COBOL/400 User’s Guide


Ÿ Create Job Description (CRTJOBD)
Ÿ Submit Job (SBMJOB).
You can select one of four reply modes by specifying one of the following values
for the INQMSGRPY parameter:
SAME No change is made in the way that replies are sent to inquiry mes-
sages
RQD All inquiry messages require a reply by the receiver of the inquiry
messages
DFT A default reply is issued
SYSRPYL The system reply list is checked for a matching reply list entry. If a
match occurs, the reply value in that entry is used. If no entry exists
for that inquiry message, a reply is required.

You can use the Add Reply List Entry (ADDRPYLE) command to add entries to the
system reply list, or the Work with Reply List Entry (WRKRPYLE) command to
change or remove entries in the system reply list. See the CL Reference for details
of the ADDRPYLE and WRKRPYLE commands. You can also reply to runtime
inquiry messages with a user-defined error-handler. For more information about
error-handling APIs, refer to the System Programmer’s Interface Reference.

Chapter 4. Running Your Program 53


54 COBOL/400 User’s Guide
Chapter 5. Debugging Your Program
The COBOL/400 language and the OS/400 operating system provide functions for
debugging the programs you develop. This chapter describes those functions that
allow you to debug your programs.

OS/400 Functions COBOL/400 Functions


Breakpoints Debugging features
Traces Formatted dump

The OS/400 functions let you test programs while protecting your production files,
and let you observe and debug operations as a program runs. No special source
code is required for using the OS/400 functions.

The COBOL functions can be used independently of the OS/400 functions or in


combination with them to:
Ÿ Debug a program
Ÿ Produce a formatted dump of the contents of fields, data structures, arrays, and
tables.

Source code is required for using COBOL debugging features and formatted dump
capability. A formatted dump can also be obtained by a user’s response to a run-
time message.

OPEN-FEEDBACK and I-O-FEEDBACK contents can provide additional debugging


information. The method for obtaining this information is described later in this
chapter in “File Status and Feedback Areas” on page 103.

While testing your programs, ensure that your library list is changed to direct the
programs to a test library containing test data so that any existing real data is not
affected.

To prevent database files in production libraries from being modified unintentionally,


you can specify UPDPROD(*NO) on the Start Debug (STRDBG) command or by
using the Change Debug (CHGDBG) command. See the CL Reference for more
information.
Note: Refer to the CL Programmer’s Guide for the CL commands required for
testing and debugging programs.

No special statements for testing are contained in the program being tested. The
program can be run normally without modification. All testing functions are speci-
fied in the job that contains the program, not in the actual program.

Testing functions apply only to the job in which they are specified. A program can
be used concurrently in two jobs: one job that is in a test environment and another
that is in a normal processing environment.

Testing functions allow you to observe the operations being performed while the
program is running. These functions include using breakpoints and traces. (See
“Using Breakpoints” on page 57 and “Using a Trace” on page 64 for more informa-
tion.)

 Copyright IBM Corp. 1994 55


Avoiding Common Coding Errors
The errors made most frequently by COBOL programmers fall into two classes:
compilation-time errors and run-time errors.

The compiler can detect errors when compiling your source program. While it
makes corrections based on assumptions about certain errors it finds, you still need
to correct the source and compile again if you have errors.

Common coding mistakes include:


Ÿ Unmatched record descriptions with externally described files
Ÿ Missing copy files
Ÿ Misspellings
Ÿ Faulty punctuation, especially missing periods
Ÿ Incorrect or incomplete syntax
Ÿ Misuse of reserved words.

The following errors appear only when you run your program:
Ÿ Failing to match the record description in your source program with the format
of the actual records on the file to be read. This can either be an error by you
(the records are correct, but your description is incorrect) or an error by the
person who created the records your program reads. (For example, your
description is correct, but one or more records were entered incorrectly.)
Ÿ Moving a data item whose subscript or index is too large, is negative, or is 0.
Such a move could overlay and destroy part of your code or could fetch faulty
data.
Ÿ Forgetting to define a sign field for items that can hold negative values. (In
such a case, the sign is lost, and the negative number mistakenly becomes
positive.)
Ÿ Moving data into an area too small for it, causing unwanted truncation.
Ÿ Forgetting to initialize the data items in the Working-Storage section before they
are used. This may result in a decimal data error.
Ÿ In a called program, incorrectly matching the data descriptions in the Linkage
Section with those of the caller. Or, in the calling program, incorrectly identi-
fying the data to be passed.
Ÿ Moving a group item to another group item when the subordinate data
descriptions are incompatible.
Ÿ Specifying USAGE for a redefined data item that is different from the USAGE
originally specified for the redefined item, and then forgetting about the change
once the redefinition takes place.
Ÿ Including a GO TO statement with no procedure name, and failing to initialize it
with an ALTER statement before the running program reaches that point.
Ÿ Failing to include the AT END or INVALID KEY clauses or the USE procedures
on files described in the program.
Ÿ Failing to match the TRANSACTION file source record description with the
display format record description.

56 COBOL/400 User’s Guide


Using Breakpoints
A breakpoint is a statement number or a label in your program that stops program
processing, and gives control to the display station user or to a specified program.
If you use a statement number, it can be a statement number that appears on the
compiler listing of the COBOL source program. If you use a label as a breakpoint,
the label can be:
Ÿ Associated with a function performed by your COBOL program. For example,
.OPEN
indicates the open file function.
Ÿ An internal COBOL compiler generated label. For example,
.Lððððð1
indicates the first internally generated label.
Note: To determine the internally generated labels for your program, use the
GENOPT parameter on the CRTCBLPGM command to get an IRP listing of the
program.

When a breakpoint statement is about to be run for an interactive job, the system
displays the breakpoint at which the program has stopped and, if requested, the
values of program variables. After you get this information (in a display), you can
go to a Command Entry display and then enter OS/400 commands to request other
functions (such as displaying or changing a variable, adding a breakpoint, or adding
a trace). See the CL Programmer’s Guide for more information on breakpoint con-
cepts.

For a batch job, a breakpoint program can be called when a breakpoint is reached.
The breakpoint information is passed to the breakpoint program.

Example of a Program Using Breakpoints


Figure 16 shows an example of a COBOL program using breakpoints. The fol-
lowing OS/400 commands add breakpoints at statements 43 and 52. The value of
variable KOUNT is displayed when the breakpoint at statement 52 is reached.

OS/400 Commands:

STRDBG TESTPRT
ADDBKP STMT(43)
ADDBKP STMT(52)
PGMVAR(KOUNT)

The OS/400 commands are explained in the CL Reference.

Chapter 5. Debugging Your Program 57


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/TESTPRT AS4ððSYS ð3/3ð/94 17:ð5:37 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION.
2 ððð2ðð PROGRAM-ID. TESTPRT.
3 ððð3ðð AUTHOR. PROGRAMMER NAME.
4 ððð4ðð INSTALLATION. COBOL DEVELOPMENT CENTRE. ð3/3ð/94
5 ððð5ðð DATE-WRITTEN. 11/27/87.
6 ððð6ðð DATE-COMPILED. ð3/3ð/94 17:ð5:37 .
7 ððð7ðð ENVIRONMENT DIVISION.
8 ððð8ðð CONFIGURATION SECTION.
9 ððð9ðð SOURCE-COMPUTER. IBM-AS4ðð. ð3/3ð/94
1ð ðð1ððð OBJECT-COMPUTER. IBM-AS4ðð. ð3/3ð/94
11 ðð11ðð INPUT-OUTPUT SECTION.
12 ðð12ðð FILE-CONTROL.
13 ðð13ðð SELECT FILE-1 ASSIGN TO DISK-SAMPLE.
14 ðð14ðð DATA DIVISION.
15 ðð15ðð FILE SECTION.
16 ðð16ðð FD FILE-1
17 ðð17ðð LABEL RECORDS ARE STANDARD
18 ðð18ðð RECORD CONTAINS 2ð CHARACTERS
19 ðð19ðð DATA RECORD IS RECORD-1.
2ð ðð2ððð ð1 RECORD-1.
21 ðð21ðð ð2 FIELD-A PIC X(2ð).
22 ðð22ðð WORKING-STORAGE SECTION.
23 ðð23ðð ð1 FILLER.
24 ðð24ðð ð5 KOUNT PIC S9(2) COMP-3.
25 ðð25ðð ð5 LETTERS PIC X(26) VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
26 ðð26ðð ð5 ALPHA REDEFINES LETTERS
27 ðð27ðð PIC X(1) OCCURS 26 TIMES.
28 ðð28ðð ð5 NUMBR PIC S9(2) COMP-3.
29 ðð29ðð ð5 DEPENDENTS PIC X(26) VALUE "ð1234ð1234ð1234ð1234ð1234ð".
3ð ðð3ððð ð5 DEPEND REDEFINES DEPENDENTS
31 ðð31ðð PIC X(1) OCCURS 26 TIMES.
32 ðð32ðð ð1 WORK-RECORD.
33 ðð33ðð ð5 NAME-FIELD PIC X(1).
34 ðð34ðð ð5 FILLER PIC X(1) VALUE SPACE.
35 ðð35ðð ð5 RECORD-NO PIC S9(3).
36 ðð36ðð ð5 FILLER PIC X(1) VALUE SPACE.
37 ðð37ðð ð5 LOCATION PIC A(3) VALUE "NYC".
38 ðð38ðð ð5 FILLER PIC X(1) VALUE SPACE.
39 ðð39ðð ð5 NO-OF-DEPENDENTS
4ð ðð4ððð PIC X(2).
41 ðð41ðð ð5 FILLER PIC X(7) VALUE SPACES.
ðð42ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð43ðð\ THE FOLLOWING PARAGRAPH OPENS THE OUTPUT FILE TO \
ðð44ðð\ BE CREATED AND INITIALIZES COUNTERS \
ðð45ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
42 ðð46ðð PROCEDURE DIVISION.
ðð47ðð STEP-1.
43 ðð48ðð OPEN OUTPUT FILE-1. .1/
44 ðð49ðð MOVE ZERO TO KOUNT, NUMBR.
ðð5ððð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð51ðð\ THE FOLLOWING 3 PARAGRAPHS CREATE INTERNALLY THE \
ðð52ðð\ RECORDS TO BE CONTAINED IN THE FILE, WRITES THEM \
ðð53ðð\ ON THE DISK, AND DISPLAYS THEM \
ðð54ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð55ðð STEP-2.
45 ðð56ðð ADD 1 TO KOUNT, NUMBR.
46 ðð57ðð MOVE ALPHA (KOUNT) TO NAME-FIELD.
47 ðð58ðð MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS.
48 ðð59ðð MOVE NUMBR TO RECORD-NO.
ðð6ððð STEP-3.
49 ðð61ðð DISPLAY WORK-RECORD.
5ð ðð62ðð WRITE RECORD-1 FROM WORK-RECORD.
ðð63ðð STEP-4.
51 ðð64ðð PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
ðð65ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð66ðð\ THE FOLLOWING PARAGRAPH CLOSES FILE OPENED FOR \
ðð67ðð\ OUTPUT AND RE-OPENS IT FOR INPUT \
ðð68ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð69ðð STEP-5.
52 ðð7ððð CLOSE FILE-1. .2/
53 ðð71ðð OPEN INPUT FILE-1.
ðð72ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð73ðð\ THE FOLLOWING PARAGRAPHS READS BACK THE FILE AND \
ðð74ðð\ SINGLES OUT EMPLOYEES WITH NO DEPENDENTS \
ðð75ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

Figure 16 (Part 1 of 2). Example of a COBOL Program Using Breakpoints

58 COBOL/400 User’s Guide


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/TESTPRT AS4ððSYS ð3/3ð/94 17:ð5:37 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð76ðð STEP-6.
54 ðð77ðð READ FILE-1 RECORD INTO WORK-RECORD
55 ðð78ðð AT END GO TO STEP-8.
ðð79ðð STEP-7.
56 ðð8ððð IF NO-OF-DEPENDENTS IS EQUAL TO "ð"
57 ðð81ðð MOVE "Z" TO NO-OF-DEPENDENTS.
58 ðð82ðð GO TO STEP-6.
ðð83ðð STEP-8.
59 ðð84ðð CLOSE FILE-1.
6ð ðð85ðð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 16 (Part 2 of 2). Example of a COBOL Program Using Breakpoints

.1/ The first breakpoint shows you where you are in the program. The following
information is displayed when the break occurs:

à@ Display Breakpoint
ð
Statement/Instruction . . . . . . . . . : 43 /ðð17
Program . . . . . . . . . . . . . . . . : TESTPRT
Recursion level . . . . . . . . . . . . : 1

Press Enter to continue.

F3=Exit Program F1ð=Command entry

á ñ
Figure 17. First Breakpoint Displayed

Chapter 5. Debugging Your Program 59


.2/ The following information is displayed as a result of reaching the second
breakpoint:

à@ Display Breakpoint
ð
Statement/Instruction . . . . . . . . . : 52 /ðð56
Program . . . . . . . . . . . . . . . . : TESTPRT
Recursion level . . . . . . . . . . . . : 1
Start position . . . . . . . . . . . . : 1
Format. . . . . . . . . . . . . . . . . : \CHAR
Length. . . . . . . . . . . . . . . . . : \DCL

Variable. . . . . . . . . . . . . . . . : ð5 KOUNT
Type. . . . . . . . . . . . . . . . . : PACKED
Length. . . . . . . . . . . . . . . . : 2 ð
' 26'

Press Enter to continue.

F3=Exit Program F1ð=Command entry

á ñ
Figure 18. Second Breakpoint Displayed

To specify a variable for the PGMVAR parameter, begin every name you enter with
an alphanumeric character (A through Z, $, #, or @). It can be followed by the
characters (A through Z, 0 though 9, $, #, @, or _ ).

The following example shows how to display a COBOL variable, RECORD-NO, in


the program example. Because the hyphen is treated by the OS/400 operating
system as a special character, RECORD-NO must be enclosed in quotation marks.

STRDBG TESTPRT
ADDBKP STMT(58)
PGMVAR('RECORD-NO')

To display the value of a table element, enter the appropriate occurrence numbers
(subscripts) with the variable name. Up to seven dimensions of subscripting are
allowed, and the subscripts must be separated by commas.

Do not use an index-name or index data-item as a subscript. When an index is


entered as a subscript, the operating system uses the internal value of the index as
the subscript, and undesirable results can occur.

The following example shows how to specify the COBOL variable TABLE1 with
three dimensions.

PGMVAR('TABLE1(SUB1, SUB2, SUB3)')

One or more blanks are allowed after each comma separating subscripts, but the
total length of the variable plus subscripts, parentheses, commas, and blanks speci-
fied with the PGMVAR keyword cannot exceed 132 characters. For more informa-
tion on how to code variables in CL commands, see the CL Reference.

60 COBOL/400 User’s Guide


Variable names can be qualified in the PGMVAR parameter. For example:

PGMVAR('NAME-FIELD OF WORK-RECORD')

Another technique can be used to display variables that are not elements of a
multi-dimensional table. For example, to display the field NAME-FIELD, you can
use the COBOL Data Division map to find its COBOL internal name (I-NAME).
Next, use the IRP cross-reference listing to find the Object Definition Table (ODT)
number for the internal-name. (See “Using the PROCESS Statement to Specify
Compiler Options” on page 32 for information on how to obtain these listings.)
Figure 19 shows the Data Division map, and Figure 20 on page 62 shows the
cross-reference listing for the program example, TESTPRT.

5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Data Division Map TESTER/TESTPRT AS4ððSYS ð3/3ð/94 17:ð5:37 Page 4
STMT LVL SOURCE NAME SECTION DISP LENGTH TYPE I-NAME ATTRIBUTES
16 FD FILE-1 FS .Fð1 DEVICE DISK, ORGANIZATION SEQUENTIAL,
ACCESS SEQUENTIAL, RECORD CONTAINS 2ð
CHARACTERS, LABEL RECORDS STANDARD
2ð ð1 RECORD-1 FS ðððððððð 2ð GROUP .Dðð633C
21 ð2 FIELD-A FS ðððððððð 2ð AN .Dðð63AE
23 ð1 FILLER WS ðððððððð 56 GROUP .Dðð642ð
24 ð2 KOUNT WS ðððððððð 2 PACKED .Dðð649ð
25 ð2 LETTERS WS ððððððð2 26 AN .Dðð6512 VALUE
26 ð2 ALPHA WS ððððððð2 1 AN .Dðð65Bð REDEFINES .Dðð6512, DIMENSION(26)
28 ð2 NUMBR WS ðððððð28 2 PACKED .Dðð6632
29 ð2 DEPENDENTS WS ðððððð3ð 26 AN .Dðð66B4 VALUE
3ð ð2 DEPEND WS ðððððð3ð 1 AN .Dðð6754 REDEFINES .Dðð66B4, DIMENSION(26)
32 ð1 WORK-RECORD WS ðððððððð 19 GROUP .Dðð67D6
33 ð2 NAME-FIELD WS ðððððððð 1 AN .Dðð684C .1/
34 ð2 FILLER WS ððððððð1 1 AN .Dðð68Cð VALUE
35 ð2 RECORD-NO WS ððððððð2 3 ZONED .Dðð693C
36 ð2 FILLER WS ððððððð5 1 AN .Dðð69C2 VALUE
37 ð2 LOCATION WS ððððððð6 3 A .Dðð6A98 VALUE
38 ð2 FILLER WS ððððððð9 1 AN .Dðð6B2ð VALUE
39 ð2 NO-OF-DEPENDENTS WS ðððððð1ð 2 AN .Dðð6B9C
41 ð2 FILLER WS ðððððð12 7 AN .Dðð6C16 VALUE
FILE SECTION uses 2ð bytes of storage
WORKING-STORAGE SECTION uses 75 bytes of storage
\ \ \ \ \ E N D O F D A T A D I V I S I O N M A P \ \ \ \ \

Figure 19. Data Division Map for TESTPRT

.1/ The I-NAME for NAME-FIELD

Chapter 5. Debugging Your Program 61


5763SS1 V3RðM5 92ð925 IBM COBOL/4ðð 5763CB1 V3RðM5 IRP LISTING FOR TESTPRT ð3/3ð/94 17:ð5:37 Page 43
ODT ODT Name SEQ Cross Reference (\ Indicates Where Defined)
ð184 .DMPFBH1 514\
ð185 .DMPFBH2 515\
ð14F .DMPFBIB 452\
ð148 .DMPFBLN 445\
ð15B .DMPFBLO 471\
ð186 .DMPFBLP 512 516\
ð182 .DMPFBLS 512\
ð14C .DMPFBL1 449\ 1ð65 1ð66
ð14D .DMPFBL2 45ð\
ð16ð .DMPFBMF 476\
ð14E .DMPFBMN 451\ 995 1ð98 1ð99 1118 1119
ð18ð .DMPFBND 5ð9\
ð15ð .DMPFBOB 453\
ð15A .DMPFBOF 47ð\
ð152 .DMPFBOL 458\
ð15F .DMPFBPO 475\
ð161 .DMPFBQN 477\
ð155 .DMPFBRC 461\
ð153 .DMPFBRW 459\
ð158 .DMPFBSC 468\
ð149 .DMPFBSF 446\
ð14A .DMPFBSL 447\
ð14B .DMPFBSN 448\
ð146 .DMPFBTY 443\ 1ð97 1117
ð159 .DMPFBUF 469\
ð183 .DMPFBVL 513\
ð18B .DMPIOFB 522\
ð1Að .DMPIOFS 545\ 546 547
ð1A6 .DMPKYLN 551\
ð165 .DMPNDEV 481\ 1ð87 1145
ð144 .DMPOFBS 441\ 442 443 444 445 446 447 448 449 45ð 451 452 453 454 458 459 46ð 461 462 467 468 469 47ð 471 472 473 474 475 476
477 478 479 48ð 481 482 5ð8 5ð9 51ð
ð1AA .DMPRCD 555\
ð1AC .DMPRCDN 557\
ð1AE .DMPRDUP 559\
ð1A1 .DMPRFMT 546\
ð1A7 .DMPRRN 552\
ð1A5 .DMPSRC 55ð\
ð22ð .Dðð6A98 685\
ð221 .Dðð6B2ð 686\
ð222 .Dðð6B9C 687\ 767 914 916
ð223 .Dðð6C16 688\
ð211 .Dðð63AE 67ð\
ð21ð .Dðð633C 669\ 789 9ð4
ð212 .Dðð642ð 671\ 672 673 676 677
ð213 .Dðð649ð 672\ 753 757 761 765 815
ð216 .Dðð65Bð 675\ 763
ð214 .Dðð6512 673\ 674
ð218 .Dðð66B4 677\ 678
ð217 .Dðð6632 676\ 754 758 769
ð21B .Dðð67D6 68ð\ 681 682 683 684 685 686 687 688 778 789 9ð4
ð21A .Dðð6754 679\ 767
ð21D .Dðð68Cð 682\
ð21C .Dðð684C 681\ 763 .1/
ð21F .Dðð69C2 684\
ð21E .Dðð693C 683\ 769

Figure 20. Section of IRP Cross-Reference Listing for TESTPRT

.1/ 021C is the ODT number for NAME-FIELD

Now you can use ODT number 021C (for NAME-FIELD), with the following com-
mands, to add a breakpoint to the program example at statement 52.

STRDBG TESTPRT
ADDBKP STMT(52)
PGMVAR('/ð21C')

These commands are explained in the CL Reference.

62 COBOL/400 User’s Guide


The following is displayed when this breakpoint is reached:

à@ Display Breakpoint
ð
Statement/Instruction . . . . . . . . . : 52 /ðð56
Program . . . . . . . . . . . . . . . . : TESTPRT
Recursion level . . . . . . . . . . . . : 1
Start position. . . . . . . . . . . . . : 1
Format. . . . . . . . . . . . . . . . . : \CHAR
Length. . . . . . . . . . . . . . . . . : \DCL

proc=display.
Variable. . . . . . . . . . . . . . . . : /ð21C
Type. . . . . . . . . . . . . . . . . : CHARACTER
Length. . . . . . . . . . . . . . . . : 2
\...+....1....+....2....+....3....+....4....+....5
'Z'

Press Enter to continue.

F3=Exit Program F1ð=Command entry

á ñ
Figure 21. Breakpoint at Statement 52

Changing Program Variables


Now you can change the value of program variables to alter your program’s proc-
essing. You can use the Change Program Variable (CHGPGMVAR) command to
change the value of a variable. This procedure is explained in more detail in the
CL Reference.

You can use the DSPPGMVAR command to display pointer data items, but you
cannot use CHGPGMVAR to change pointer data items. To change pointer data
items, you use the CHGHLLPTR or CHGPTR commands. For more information on
the CHGHLLPTR and CHGPTR commands, refer to the CL Reference.

Considerations for Using Breakpoints


You should know the following breakpoint characteristics before using breakpoints:
Ÿ If a breakpoint is bypassed by, for example the GO TO statement, that break-
point isn’t processed.
Ÿ When a breakpoint is set on a statement, the breakpoint occurs before that
statement is processed.
Ÿ Breakpoint functions are specified through OS/400 commands.
These functions include:
– Adding breakpoints to programs
– Removing breakpoints from programs
– Displaying breakpoint information
– Resuming the running of a program after a breakpoint has been reached
(displayed).

Chapter 5. Debugging Your Program 63


See the CL Programmer’s Guide for descriptions of these commands and for
more details about breakpoints.

Using a Trace
A trace is a record of some or all of the statements run in a program. If requested,
a trace also records the values of specific variables used in the program state-
ments.

Program Trace
┌─────────────┐ ┌─────────────────────────────────────┐
│ Statement │ │ Processing Order Variables │
│ 1 ...... │ │ 1 ─────────5 ....... │
│ 2 ...... │ │ 6 ─────────5 ....... │
│ 3 ...... │ │ 7 ─────────5 ....... │
│ 4 ...... │ │ 8 ─────────5 ....... │
│ 5 ...... │ │ 6 ─────────5 ....... │
│ 6 ...... │ │ 7 ─────────5 ....... │
│ 7 ...... │ │ 2 ─────────5 ....... │
│ 8 ...... │ │ 6 ─────────5 ....... │
│ . │ │ 7 ─────────5 ....... │
│ . │ │ . │
│ . │ │ . │
│ │ │ │
│ │ │ │
└─────────────┘ └─────────────────────────────────────┘

A trace differs from a breakpoint because the number of statements involved in the
trace affects where the trace will end. The system records all the traced state-
ments that were processed. You can request a display of the traced information,
which shows the sequence in which the statements were processed and, if
requested, the values of the variables used in the statements.

You specify which statements the system will trace. You can also specify that vari-
ables be displayed only when their value has changed since the last trace state-
ment was run.

You can specify a trace of one statement in a program, a group of statements in a


program, or all the statements in an entire program.

Example of Using a Trace


Figure 22 on page 65 shows a portion of a COBOL program example, TESTPRT.
The following OS/400 command adds a trace of statements 54 through 58 in that
program. The variable NO-OF-DEPENDENTS is to be recorded only if its value
changes between statements 54 and 58:

ADDTRC STMT((54 58))


PGMVAR('NO-OF-DEPENDENTS')
OUTVAR(\CHG)

Note: STRDBG must be entered before the ADDTRC statement.

64 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð42ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð3/ð7/94
ðð43ðð\ THE FOLLOWING PARAGRAPH OPENS THE OUTPUT FILE TO \ ð3/ð7/94
ðð44ðð\ BE CREATED AND INITIALIZES COUNTERS \ ð3/ð7/94
ðð45ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð3/ð7/94
42 ðð46ðð PROCEDURE DIVISION. ð3/ð7/94
ðð47ðð STEP-1. ð3/ð7/94
43 ðð48ðð OPEN OUTPUT FILE-1. ð3/ð7/94
44 ðð49ðð MOVE ZERO TO KOUNT, NUMBR. ð3/ð7/94
ðð5ððð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð3/ð7/94
ðð51ðð\ THE FOLLOWING 3 PARAGRAPHS CREATE INTERNALLY THE \ ð3/ð7/94
ðð52ðð\ RECORDS TO BE CONTAINED IN THE FILE, WRITE THEM \ ð3/ð7/94
ðð53ðð\ ON THE DISK, AND DISPLAY THEM \ ð3/ð7/94
ðð54ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð3/ð7/94
ðð55ðð STEP-2. ð3/ð7/94
45 ðð56ðð ADD 1 TO KOUNT, NUMBR. ð3/ð7/94
46 ðð57ðð MOVE ALPHA (KOUNT) TO NAME-FIELD. ð3/ð7/94
47 ðð58ðð MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS. ð3/ð7/94
48 ðð59ðð MOVE NUMBR TO RECORD-NO. ð3/ð7/94
ðð6ððð STEP-3. ð3/ð7/94
49 ðð61ðð DISPLAY WORK-RECORD. ð3/ð7/94
5ð ðð62ðð WRITE RECORD-1 FROM WORK-RECORD. ð3/ð7/94
ðð63ðð STEP-4. ð3/ð7/94
51 ðð64ðð PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26.
ðð65ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð66ðð\ THE FOLLOWING PARAGRAPH CLOSES FILE OPENED FOR \
ðð67ðð\ OUTPUT AND RE-OPENS IT FOR INPUT \
ðð68ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð69ðð STEP-5.
52 ðð7ððð CLOSE FILE-1.
53 ðð71ðð OPEN INPUT FILE-1.
ðð72ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð73ðð\ THE FOLLOWING PARAGRAPHS READ BACK THE FILE AND \
ðð74ðð\ SINGLE OUT EMPLOYEES WITH NO DEPENDENTS \
ðð75ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð76ðð STEP-6.
54 ðð77ðð READ FILE-1 RECORD INTO WORK-RECORD
55 ðð78ðð AT END GO TO STEP-8.
ðð79ðð STEP-7.
56 ðð8ððð IF NO-OF-DEPENDENTS IS EQUAL TO "ð"
57 ðð81ðð MOVE "Z" TO NO-OF-DEPENDENTS.
58 ðð82ðð GO TO STEP-6.
ðð83ðð STEP-8.
59 ðð84ðð CLOSE FILE-1.
6ð ðð85ðð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 22. Example of a COBOL Program Using a Trace

Figure 23 on page 66 is an example of a listing of the traced information. This


information is produced by the Display Trace Data (DSPTRCDTA) command:
DSPTRCDTA OUTPUT(\PRINT) CLEAR(\YES)

This command is explained in the CL Reference.

Chapter 5. Debugging Your Program 65


5763SS1 V3RðM5 Display Trace Data
Job . . . : DSPð2 User . . . : PGMRS Number . . . . : ðð4122
Statement/
Program Instruction Recursion Level Sequence Number
TESTPRT 54 1 1
Start position . . . . . . . . . . . . : 1
Length . . . . . . . . . . . . . . . . : \DCL
Format . . . . . . . . . . . . . . . . : \CHAR
Variable . . . . . . . . . . . . . . . : ð5 NO-OF-DEPENDENTS
Type . . . . . . . . . . . . . . . . : CHARACTER
Length . . . . . . . . . . . . . . . : 2
\...+....1....+....2....+....3....+....4....+....5
'ð '
Statement/
Program Instruction Recursion Level Sequence Number
TESTPRT 56 1 2
TESTPRT 57 1 3
TESTPRT 58 1 4
Start position . . . . . . . . . . . . : 1
Length . . . . . . . . . . . . . . . . : \DCL
Format . . . . . . . . . . . . . . . . : \CHAR
\Variable . . . . . . . . . . . . . . . : ð5 NO-OF-DEPENDENTS
Type . . . . . . . . . . . . . . . . : CHARACTER
Length . . . . . . . . . . . . . . . : 2
\...+....1....+....2....+....3....+....4....+....5
'Z '
Statement/
Program Instruction Recursion Level Sequence Number
TESTPRT 54 1 5
TESTPRT 56 1 6
Start position . . . . . . . . . . . . : 1
Length . . . . . . . . . . . . . . . . : \DCL
Format . . . . . . . . . . . . . . . . : \CHAR
\Variable . . . . . . . . . . . . . . . : ð5 NO-OF-DEPENDENTS
Type . . . . . . . . . . . . . . . . : CHARACTER
Length . . . . . . . . . . . . . . . : 2
\...+....1....+....2....+....3....+....4....+....5
'1 '
Statement/
Program Instruction Recursion Level Sequence Number
TESTPRT 58 1 7
TESTPRT 54 1 8
TESTPRT 56 1 9
Start position . . . . . . . . . . . . : 1
Length . . . . . . . . . . . . . . . . : \DCL
Format . . . . . . . . . . . . . . . . : \CHAR
\Variable . . . . . . . . . . . . . . . : ð5 NO-OF-DEPENDENTS
Type . . . . . . . . . . . . . . . . : CHARACTER
Length . . . . . . . . . . . . . . . : 2
\...+....1....+....2....+....3....+....4....+....5
'2 '
Statement/
Program Instruction Recursion Level Sequence Number
TESTPRT 58 1 1ð
TESTPRT 54 1 11
TESTPRT 56 1 12

Figure 23. Trace Data Display Listing

Considerations for Using a Trace


You should understand the following trace characteristics before using them:
Ÿ Statements bypassed by, for example the GO TO statement, are not included
in the trace.
Ÿ Trace functions are specified through OS/400 commands in the job containing
the traced program. These functions include adding trace requests to a

66 COBOL/400 User’s Guide


program, removing trace requests from a program, removing data collected
from previous traces, displaying trace information, and displaying the traces
that have been specified for a program.
Ÿ In addition to statement numbers, names of COBOL-generated routines can
appear on the trace output STMT field.

See the CL Programmer’s Guide for more information on traces.

Using a Debug Run-Time Switch


A run-time switch is provided for the COBOL Debug facility. This switch activates
the debugging code generated when WITH DEBUGGING MODE is specified.
When the switch is set on, all compiled debugging sections are activated; when it is
set off (the default), the USE FOR DEBUGGING Declarative procedures are deacti-
vated. Refer to Appendix B, “Debugging Features” on page 313 for more informa-
tion on COBOL debugging features and the use of the run-time switch.

Using a COBOL Formatted Dump


Some COBOL run-time messages allow you to obtain a COBOL formatted dump
option by selecting either D or F. The formatted dump (choose D) includes current
information about the files in your program, contents of fields, data structures,
arrays, and tables for user-defined COBOL data variables.

If you choose the F option, the dump also includes a list of compiler-generated
fields and their contents.

Both the D option and the F option will dump the first 256 characters of program
variables. Any variable greater than 256 characters will be truncated.

If you do not want a dump, specify C (cancel with no dump). Reply C is also the
default reply for all COBOL inquiry messages that allow a dump.

For more information about reply modes see “Replying to Run-Time Inquiry
Messages” on page 52.

The output for the dump is sent to the IBM-supplied printer file QPPGMDMP.

To see an example of a formatted dump, refer to Appendix H, “Example of a


COBOL Formatted Dump” on page 371.

Chapter 5. Debugging Your Program 67


68 COBOL/400 User’s Guide
Chapter 6. COBOL/400 Exception and Error Handling
This chapter describes COBOL/400 error handling and its use. It also explains the
relationship between error handling and the processing of I/O verbs.

The COBOL/400 compiler provides two error-handling methods: standard and non-
standard. Standard error handling is not available on compilers released earlier
than Version 1 Release 3.

Standard Error Handling


Standard error handling gives you extra compatibility with other IBM COBOL com-
pilers (such as VS COBOL II) as well as non-IBM COBOL compilers. It can help
you during the processing of I/O statements by catching severe errors that might
not otherwise be noticed.

An important characteristic of standard error handling is the issuing of a run-time


message when an error occurs during the processing of an I/O statement if there is
no AT END/INVALID KEY phrase in the I/O statement, USE procedure for the file,
or FILE STATUS clause in the SELECT statement for the file.

Release Sensitivity!

Standard error handling was introduced in Version 1 Release 3 as a default


option. To get the error handling that was used in earlier releases, specify
*NOSTDERR as a generation option of the CRTCBLPGM command, or
NOSTDERR in the PROCESS statement.

Error Handling Overview


When you run a COBOL program, several types of errors can occur. The COBOL
statement active at the time of a given error causes certain COBOL clauses or
phrases to run.

During arithmetic operations, typical errors are size (MCH1210) errors and decimal
data (MCH1202) errors; the corresponding error-handling phrase is the SIZE
ERROR phrase.

Most MCH errors are not directly detected by COBOL; they are detected by the
operating system and result in system messages. COBOL then monitors for these
messages, setting internal bits that determine whether to run a SIZE ERROR
imperative statement or issue a run-time message (LBE7200) to end the program.

COBOL does detect errors that result from division by zero during an arithmetic
operation. If detected by COBOL, these errors cause the SIZE ERROR imperative
statement to run.

System message MCH1210 occurs when you move a numeric field to a receiver
that is too small. This error is monitored by COBOL, and also results in the running
of the SIZE ERROR imperative statement.

 Copyright IBM Corp. 1994 69


LBE7200 is a run-time message that is usually issued when an unmonitored severe
error occurs in your COBOL program. Under *NOSTDERR, it can also be issued
when an error occurs in the absence of an appropriate error handler.

System message MCH1202 is a typical example of an unmonitored severe error.


This kind of error results in the COBOL run-time message LBE7200 (or LBE7204 if
the error occurs in a program called by a COBOL program). System messages
MCH3601 and MCH0601 are other examples of unmonitored severe errors.

For I/O operations, there are several important error handling phrases and clauses.
These are the AT END/INVALID KEY and NO DATA phrases (coded at the COBOL
statement level), the USE procedure, and the FILE STATUS clause (coded at the
file level). During arithmetic and I/O operations, errors are detected by the system,
which sends messages; the messages are then monitored by COBOL. Similar to
the case of an error that results from division by zero, COBOL does detect some
errors during an I/O operation. Regardless of how an error is detected during an
| I/O operation, the result will always be an internal file status in which the first char-
| acter is not zero, run-time message, or both.

General-Use Programming Interface

Using Error-Handling Application Programming Interfaces (APIs)


You can use COBOL/400 APIs to control error handling for you within your pro-
grams. These APIs are Retrieve COBOL Error Handler (QLRRTVCE), and Set
COBOL Error Handler (QLRSETCE).

The Retrieve COBOL Error Handler (QLRRTVCE) API allows you to retrieve the
name of the current or pending COBOL error-handling program. You can call it
from any programming language.

The Set COBOL Error Handler (QLRSETCE) API allows you to specify the identity
of a COBOL error-handling program. You can call it from any programming lan-
guage.

You can also use the Change COBOL Main Program (QLRCHGCM) API to create
multiple run units, each with its own error handler.

For detailed information on all of these APIs, refer to the System Programmer’s
Interface Reference.

End of General-Use Programming Interface

Internal and External File Status


You must provide a FILE-CONTROL entry to specify the organization and access
method for each file used by your COBOL program. You can also code a
FILE STATUS clause in this entry.

The FILE STATUS clause designates one or two data items (coded in the
WORKING-STORAGE section) to hold a copy of the result of an I/O operation.
Your copy of the first of these items is called the external file status. If you use a
TRANSACTION file, you have a further record of the result called the external
return code, which consists of the external major and minor return codes.

70 COBOL/400 User’s Guide


COBOL keeps its own copies of these two data items, both of which are stored in
the COBOL File Information Block (FIB). In this chapter, file status and
(major/minor) return code refer to COBOL’s copies unless otherwise specified.

During the processing of an I/O statement, the file status can be updated in one of
three ways, as described below. The contents of the file status determine which
error handling procedures to run.

Error handling procedures take control after an unsuccessful input or output opera-
| tion, which is denoted by any file status in which the first character is not zero.
Before any of these procedures run, the file status is copied into the external file
status.

The file status is set in one of three ways:


Ÿ Method A (all files):
COBOL checks the contents of variables in file control blocks. If the contents
are not what is expected, a file status of other than zero is set. Most file
statuses set in this way result from checking the COBOL File Information Block
(FIB) and the system User File Control Block (UFCB).
Ÿ Method B (transaction files):
COBOL checks the major and minor return codes from the system. If the major
return code is not zero, the return code (consisting of major and minor return
codes) is translated into a file status. If the major return code is zero, the file
status may have been set by Method A or C.
Note that for subfile READ, WRITE, and REWRITE operations, only Methods A
and C apply.
For a list of return codes and their corresponding file statuses, see “File Struc-
ture Support Summary and Status Key Values” in the COBOL/400 Reference.
Ÿ Method C (all files):
A message is sent by the system when COBOL calls on data management to
perform an I/O operation. COBOL then monitors for these messages and sets
a file status accordingly.
COBOL specifically monitors for a message by generating message monitors in
the program object produced at compilation time. Message monitor generation
is based on the types of files (organization type and access type are examples)
that you specify in a program. Thus, a message that is specifically monitored
for in one program may fall under the generic I/O handler in another. More
information about message monitor generation will follow in this chapter.
COBOL monitors for most messages sent by the system in response to an I/O
operation. Typical I/O exceptions result in CPF messages that begin with
“CPF4” or “CPF5,” and COBOL does specific monitoring for these.
For a list of messages for which COBOL does specific monitoring, see “File
Structure Support Summary and Status Key Values” in the COBOL/400
Reference.

Chapter 6. COBOL/400 Exception and Error Handling 71


General Error Detection

How File Status is Set


001
Start of I/O operation
– Method A: Check contents of variables in file control blocks.
(Check, for example, that the file has been opened
properly and in the right mode.)
| Has internal file status been changed from 00?
Yes No

002
Call on data management to perform I/O operation
– Method C: Monitor for messages sent by data management and set
internal file status accordingly.
– Method A: Check system information blocks and set internal file
status if not already set using Method C.
Is the file a transaction file?
Yes No

003
Set external file status
– Move internal file status to external file status (specified in file status
clause). Based on internal file status, run error handling code.

004
Check major and minor return codes from system
– Method B: If data management has sent a message, translate major
and minor return codes associated with system message
into internal file status.
Continue at Step 003

005
Continue at Step 003

72 COBOL/400 User’s Guide


Message Monitor Generation
A message monitor provides a way for a program to handle messages sent by the
system or by another program. A message monitor can handle one or more mes-
sages.

In some respects, a message monitor resembles a USE procedure. Similar to the


way in which a USE procedure specifies actions to take in response to an I/O error,
a message monitor specifies an action to take when an error occurs during the
processing of a machine interface (MI) instruction. Note that an MI instructional
error is signalled by a system message, and note that each COBOL statement is
composed of one or more MI instructions.

Unlike a USE procedure (which may not be active during an entire program), a
COBOL message monitor becomes active as soon as the program starts.
Message monitors set file statuses and indicate SIZE ERROR, END-OF-PAGE, and
OVERFLOW conditions.

Message monitors generated by COBOL are grouped into several sets, generated
under certain conditions within a COBOL program. The following table provides
general guidelines regarding the generation of message monitors:

Table 1 (Page 1 of 2). Generation of Message Monitors


Cause of Message Monitor Sample Members of Monitored Message Set
You code a file status clause Ÿ File not found, external file status 35
Ÿ Permanent error condition, external file status 30
Ÿ OPEN mode not valid, external file status 37
Ÿ No next record, system message CPF5183 (part of
external file status 46)
Ÿ Undefined or unauthorized access type, external file
status 91
Ÿ Logic error, external file status 92 (except for system
messages CPF4740 and CPF5070)
Ÿ Record is locked, external file status 9D
Ÿ OPEN with commitment control failed, external file status
9P
Ÿ WRITE not valid, system messages CPF5018 and
CPF5272 (part of external file status 24).
You code an AT END phrase Ÿ End-of-file handler, system messages CPF5001 and
CPF5025
Ÿ File not found, external file status 35.
You specify a subfile in your Ÿ Last record written to subfile, external file status 9M or
program 0M
Ÿ Subfile record not found, system message CPF5020 (part
of external file status 23)
Ÿ Subfile boundary violation, system messages CPF5021
and CPF5043 (part of external file status 24). A
boundary violation is an attempt to write beyond the
externally defined boundaries of a sequential file.

Chapter 6. COBOL/400 Exception and Error Handling 73


Table 1 (Page 2 of 2). Generation of Message Monitors
Cause of Message Monitor Sample Members of Monitored Message Set
You code a subfile READ statement Ÿ No modified subfile record, external file status 12.
with the NEXT MODIFIED phrase
You use an indexed sequential file Ÿ No specific monitor (Method A), set internal file statuses
21 and 22.
There is a keyed READ operation Ÿ System messages CPF5006 and CPF5013 (part of
external file status 23).
There is a sequential WRITE opera- Ÿ Boundary violation, system message CPF5116 (part of
tion external file status 34).
| There is an indexed sequential Ÿ No specific monitor (Method A), set internal file statuses
| REWRITE operation 21, 43, 44, and 9S.
There is TRANSACTION I/O Ÿ READ timeout, system message CPF4743, set internal
file status 00
Ÿ No data during READ, system message CPF4742, set
NO DATA bit
Ÿ No acquired devices, system message CPF5070 (part of
external file status 92)
Ÿ No devices invited/acquired, system message CPF4740
(part of external file status 92 and external file status 10)
Ÿ Cancel job, external file status 9A
Ÿ WRITE failed, external file status 9I
Ÿ Temporary error, external file status 9N.
You specify a format clause in an Ÿ Format name not valid/not found, internal file status 9K.
I/O statement
There is any I/O at all (including Ÿ END-OF-PAGE exception handler (system message
extended ACCEPT/DISPLAY oper- CPF5004)
ations) in your program.
Ÿ Level check error, external file status 39
Ÿ Generic exception handler, external file status 90
Ÿ Indicator mismatch (run-time message LBE7421, system
message CPF4238)
Ÿ Ignore COMMIT or ROLLBACK (system message
CPF8350).
Ÿ Duplicate key, external file status 22.
Ÿ READ DYNAMIC invalid change of direction, internal file
status 9U, system message CPF5184.
Note: For a list of monitored messages that fall under a particular external file status, see “File Struc-
ture Support Summary and Status Key Values” in the COBOL/400 Reference.

Ending of a COBOL Program


There are three things that can cause a COBOL program to end:
A COBOL statement (EXIT PROGRAM, STOP RUN, or GOBACK)
A reply to an inquiry message
An implicit STOP RUN or EXIT PROGRAM statement.

74 COBOL/400 User’s Guide


A STOP RUN statement is implied when a main COBOL program has no next exe-
cutable statement (implicit EXIT PROGRAM for a COBOL subprogram), that is,
when processing falls through the last statement of a program.

Inquiry messages can be issued in response to a COBOL statement (namely a


STOP literal), but they are usually issued when a severe error occurs in a program,
or when a COBOL operation does not complete successfully. (Examples are
LBE7205, LBE7207, and LBE7208.)

There are four common replies to a COBOL inquiry message: C, D, F, and G


(cancel, cancel and dump, cancel and full dump, continue). The first three cause
(as their final steps) an implicit STOP RUN followed by escape message LBE9001.
LBE9001 indicates that the program is ending because of a message.

An implicit or explicit STOP RUN statement, or a GOBACK statement that appears


in a main program, ends the entire COBOL run unit. If an escape message
(LBE9001) is issued as the final step of a run unit, the caller of the first COBOL
program can monitor for it. (This is because the first COBOL program to be called
becomes the main program.)

If a COBOL run unit consists of several COBOL and non-COBOL programs, it is


the main COBOL program that can issue the escape message. Thus, any
non-COBOL program that is called after the main program cannot monitor for the
escape message.

Return Codes
When you specify a TRANSACTION file in your program, the FILE STATUS clause
of your SELECT statement can contain two data names: the external file status,
and the (major and minor) return code. As described under “Internal and External
File Status” on page 70, a file status can be set in one of three ways; however,
return codes are set by the system after any transaction I/O that calls data man-
agement. Consequently, most error conditions that result in a system message
also have an associated return code.

Return codes are similar to file status values. That is, CPF messages sent by the
system are grouped together under message monitors, and each message monitor
sets one or more file statuses.

Similarly, CPF messages are grouped together, and each group of messages gen-
erates the same major return code. (The minor return code is not necessarily the
same.)

The main difference between file statuses and return codes is that the grouping of
CPF messages is different.

Although COBOL only sets return codes for TRANSACTION files, other types of
files (such as printer files) also set return codes. You can access the return codes
for these files through an ACCEPT from I-O-FEEDBACK operation.

Chapter 6. COBOL/400 Exception and Error Handling 75


Standard and Nonstandard Error Handling Models
Figures 24 and 25 show the two different error handling models.

I /O Oper at i on
i s not s ucces s f ul

Unmoni t ored Yes C,D,F


severe E
er r o r ?

No

Retur n t o
Set COBOL program
i nt er nal
f i l e s t at us

I ssue
End of f i l e What Al l ot her s Yes i nf or mat i onal
Moni t ored
t ype of er r or mes s age
severe
is it? (e. g. LBE7421);
er r o r ?
s et f i l e s t at us t o 90

I nval i d No
key

Is Is Is
Is
there an No there an No No there a No
t her e an E r r or
AT END I NVA L I D K E Y f i l e s t at us
Decl arati ve?
phr as e? phr as e? cl ause?

Yes Yes Yes Yes

Run Run
Run
AT END I NVA L I D K E Y
Er ror
i mperati ve i mperati ve
Decl arati ve
st at ement st at ement

Ret ur n t o
COBOL program
Note: = Go to on next page

Figure 24 (Part 1 of 2). Standard (default) Error Handling

76 COBOL/400 User’s Guide


E
E
E

I ss ue er r or
mes s age
LBE7207

D, F What i s C
Per f or m End
r es pons e t o
COBOL dump COBOL program
LBE7207?

End Ret ur n t o
COBOL program COBOL program

Does
an Retur n t o
er r or handl er previ ous di agram
ex i s t ?

Cal l er r or
handler

Yes

No

What
is
retur n code?

Figure 24 (Part 2 of 2). Standard (default) Error Handling

Chapter 6. COBOL/400 Exception and Error Handling 77


I /O Oper at i on
i s not s ucces s f ul

G
*1 Yes
I ssue
C,D,F
severe E er r or mes s age
er r or ? LBE7200

No

*2
Yes
I ssue
Moni tored
severe er r or mes s age,
E
er r or ? e. g. L BE 7 0 21

No

Set
i nter nal
f i l e s t at us

*3 Is Is
f i l e s t at us Yes Yes
Run
t her e an Er r or Er r or
equal to Decl arati ve?
9 0 or 9 P ? Declarative

No No

What
End of f i l e Al l ot her s
t ype of er r or
is it?

I nval i d
key

Is Is Is
there an No there an No No
t her e an E r r or
AT END I N VAL I D K E Y Decl arati ve?
phr as e? phr as e?

Yes Yes Yes

Run Run
Run
AT END I N VAL I D K E Y
Er r or
i mperati ve i mperati ve
Decl arati ve
st at ement st at ement

Ret ur n t o
COBOL program

Figure 25. Nonstandard Error Handling (available through *NOSTDERR option)

78 COBOL/400 User’s Guide


Other I/O exceptions may occur that COBOL does not expect. These also result in
CPF4xxx and CPF5xxx messages, but there is not specific monitoring for them.
Instead, they are caught by a generic I/O error handler. This error handler monitors
for certain ranges of CPF4xxx and CPF5xxx messages; it sets the file status to 90
and follows the Yes branch from position *3 in Figure 25 on page 78.

An I/O exception may occur that is being specifically monitored for and which,
according to the nonstandard error handling model, is severe enough to stop the
program. In this situation no file status is set.

These I/O exceptions result in specific COBOL escape messages followed by an


ending of the program; they follow the Yes branch from position *2 in Figure 25.
Example: CPF4238 - INDARA mismatch between program and file
There is specific monitoring for this message, and the result is error message
LBE7021 followed by an ending of the program.
Other COBOL messages that fall into this category are LBE7020 and LBE7022.

During an I/O operation, a problem may occur that is not expected by the system.
These problems generally result in messages (such as those starting with “MCH”)
that fall outside the CPF4xxx and CPF5xxx range. Such errors, known as unmoni-
tored severe errors, follow the Yes branch from position *1 in Figure 25. These
errors are handled by an all-purpose message monitor and result in an ending of
the COBOL program. No file status is set.

Effects of *STDERR and *NOSTDERR on File Status


Ÿ Effects of LBE742x and LBE702x messages:
With *STDERR, file status 90 is set following the issue of LBE742x messages.
The program then continues if there is a USE procedure or a FILE STATUS
clause.
With *NOSTDERR, LBE702x messages cause the program to end without
setting a file status.
Ÿ Ending of a program because of file status 9P or 90:
With *STDERR, a file status of 9P or 90 arising from an I/O error (signalled by
CPF4xxx and CPF5xxx messages) does not cause the program to end as long
as there is a USE procedure or a FILE STATUS clause. If neither exists, error
message LBE7207 is issued.
With *NOSTDERR, a file status of 9P or 90 in the absence of a USE procedure
causes error message LBE7200 to be issued.
| Ÿ Issuing of an error message for any file status in which the first character is not
| zero when there is no error handler or FILE STATUS clause:
| With *STDERR, any file status in which the first character is not zero when
there is no AT END/INVALID KEY phrase, USE procedure, or FILE STATUS
clause causes inquiry message LBE7207 (with response options C, D, F, and
G) to be issued.
| With *NOSTDERR, any file status in which the first character is not zero when
there is no AT END/INVALID KEY phrase or USE procedure allows the
program to continue unless it has already ended.

Chapter 6. COBOL/400 Exception and Error Handling 79


Processing of I/O Verbs
The following diagram shows when the USE procedure and the (NOT) AT END,
(NOT) INVALID KEY, and NO DATA imperative statements are run. This has been
in place since Version 1 Release 3, and is independent of the error handling
method you choose (*STDERR or *NOSTDERR).

Note that the file status shown here refers to the internal file status.

File Status
is set

What Is
is leftmost leftmost Is Run
0 2 or higher No Yes
character of character of file there a USE USE
file status? status equal to procedure? procedure
2?

1 Yes No

Is Run Is Run
there an Yes AT END there an Yes INVALID KEY
AT END imperative INVALID KEY imperative
phrase? statement phrase? statement

No No

Is
there a Run
Yes
USE USE
procedure? procedure

No

Continue
COBOL program
Note: = Go to on next page

Figure 26 (Part 1 of 2). Processing of I/O Verbs

80 COBOL/400 User’s Guide


Is Run
Is
Yes there a Yes NO DATA
the NO DATA
NO DATA imperative
condition
Phrase? statement
true?

No

Is
Is
leftmost Yes Run
there a Yes
character of file status NOT INVALID KEY
NOT INVALID KEY
equal to imperative statement
phrase?
0?

No No

Is
Is Run
leftmost
Yes there a Yes NOT AT END
character of file status
NOT AT END imperative
equal to
phrase? statement
0?

No No

Continue
COBOL program

Figure 26 (Part 2 of 2). Processing of I/O Verbs

Note: Follow the parts of the diagram that apply to your statements.

Common Exceptions and Some of Their Causes


MCH1202 Decimal data error:
Ÿ A numeric elementary item has been used as a source when no valid data has
been previously stored in it. The item should have a VALUE clause, or a
MOVE statement should be used to initialize its value.
Ÿ An attempt has been made to place nonnumeric data in a numeric item.
Ÿ Bad data was written to a subfile earlier in the program. The subfile data is not
validated until it is written to the display, so the 1202 error can occur on the
WRITE of a subfile control record, but the bad data was actually put to the
subfile earlier.

MCH0601 Pointer exceptions:


Ÿ Part of a linkage section item extended beyond the space allocated.
For example, if you set the address of a linkage section item, and one or more
of its elementary data items extend beyond the space with a MOVE to the ele-
mentary data item, MCH0601 is issued.

Chapter 6. COBOL/400 Exception and Error Handling 81


For more information on using pointers, refer to “Using Pointers in a
COBOL/400 Program” on page 282.

MCH0602 Pointer alignment:


Ÿ The pointer alignment in the Working-Storage Section of the calling program
does not match the alignment in the Linkage Section of the called program.
Alignment must be on a 16-byte boundary.
For more information on using pointers, refer to “Using Pointers in a
COBOL/400 Program” on page 282.

MCH3601 Pointer error:


Ÿ A reference is made to a record or a field within a record and the associated
file has been closed or has never been opened.
For example, the OPEN for the file was unsuccessful and the processing of any
other I/O statement for that file is attempted. The file status should be checked
before any other I/O is attempted.

CPF2415 End of requests:


Ÿ An attempt has been made to accept input from the job input stream while the
system is running in batch mode and no input is available.

Recovery After a Failure

Recovery with Commitment Control


When the system is restarted after a failure, files under commitment control are
automatically restored to their status at the last commitment boundary. For addi-
tional information about commitment control, see “Commitment Control
Considerations” on page 94.

For a job failure (either because of user or system error), files under commitment
control are restored as part of job termination to the files’ status at the previous
commitment boundary.

Because files under commitment control are rolled back after system or process
failure, this feature can be used to help in restarting. You can create a separate
record to store data that may be useful should it become necessary to restart a job.
This restart data can include items such as totals, counters, record key values, rela-
tive key values, and other relevant processing information from an application.

If you keep the restart data mentioned above in a file under commitment control,
the restart data will also be permanently stored in the database when a COMMIT
statement is issued. When a ROLLBACK occurs after job or process failure, you
can retrieve a record of the extent of processing successfully processed before
failure. Note that the above method is only a suggested programming technique
and will not always be suitable, depending on the application.

82 COBOL/400 User’s Guide


TRANSACTION File Recovery
In some cases, you can recover from I/O errors on TRANSACTION files without
intervention by the operator, or the varying off/varying on of work stations or com-
munications devices.

For potentially recoverable I/O errors on TRANSACTION files, the system initiates
action in addition to the steps that must be taken in the application program to
attempt error recovery. For more information about action taken by the system,
see the Remote Work Station Guide.

By examining the file status after an I/O operation, the application program can
determine whether a recovery from an I/O error on the TRANSACTION file is pos-
sible. If the File Status Key has a value of 9N, the application program may be
able to recover from the I/O error. A recovery procedure must be coded as part of
the application program and varies depending on whether a single device was
acquired by the TRANSACTION file or whether multiple devices were attached.

For a file with one acquired device:


1. Close the TRANSACTION file with the I/O error.
2. Reopen the file.
3. Process the steps necessary to retry the failing I/O operation. This may involve
a number of steps, depending on the type of program device used. (For
example, if the last I/O operation was a READ, you may have to repeat one or
more WRITE statements, which were processed prior to the READ statement.)
For more information on recovery procedures, see the ICF Programmer’s
Guide.

For a display file with multiple devices acquired:


1. DROP the program device that caused the I/O error on the TRANSACTION file.
2. ACQUIRE the same program device.
3. See Step 3 above.

For an ICF file with multiple devices acquired:


1. ACQUIRE the same program device.
2. See Step 3 above.

For a display file with multiple devices acquired:

Application program recovery attempts should typically be tried only once.

If the recovery attempt fails:


Ÿ If the file has only one program device attached, terminate the program through
processing of the STOP RUN, EXIT PROGRAM, or GOBACK statement, and
attempt to locate the source of the error.
Ÿ If the file has multiple acquired program devices, you may want to do one of
the following:
– Continue processing without the program device that caused the I/O error
on the TRANSACTION file, and reacquire the device later.
– End the program.

Chapter 6. COBOL/400 Exception and Error Handling 83


For a description of major and minor return codes that may help in diagnosing I/O
errors on the TRANSACTION file, see the ICF Programmer’s Guide or the Data
Management Guide.

Figure 27 gives an example of an error recovery procedure.

AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*


Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key
Type of Name of S pec /(b/R/H/J/K/S /O)

Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons


Reference (R)

Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* D I S P L AY F I LE F OR E R R OR R E COV E R Y E X AMP L E
A*
A I ND A R A
A R F OR MA T 1 CF 0 1 ( 0 1 ' E ND O F P R OGR AM ' )
A*
A 12 2 8 ' E N T E R I NP U T '
A I NP U T F L D 5 I 12 42
A 28 2 6 ' F 1 = T E RM I NA T E '
A
A
A
A
A
A
A
A
A
A
A
A

Figure 27. Example of Error Recovery Procedure -- DDS

84 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð2/ð1/94
2 ððð2ðð PROGRAM-ID. RECOVERY. ð2/ð5/94
3 ððð3ðð ENVIRONMENT DIVISION. ð2/ð1/94
4 ððð4ðð CONFIGURATION SECTION. ð2/ð1/94
5 ððð5ðð SOURCE-COMPUTER. IBM-AS4ðð. ð2/ð2/94
6 ððð6ðð OBJECT-COMPUTER. IBM-AS4ðð. ð2/ð2/94
7 ððð7ðð INPUT-OUTPUT SECTION. ð2/ð1/94
8 ððð8ðð FILE-CONTROL. ð2/ð1/94
9 ððð9ðð SELECT RECOVFILE ð2/ð5/94
1ð ðð1ððð ASSIGN TO WORKSTATION-RECVFILE-SI ð3/22/94
11 ðð11ðð ORGANIZATION IS TRANSACTION ð2/ð5/94
12 ðð12ðð ACCESS MODE IS SEQUENTIAL ð2/ð1/94
13 ðð13ðð FILE STATUS IS STATUS-FLD, STATUS-FLD-2 ð2/ð5/94
14 ðð14ðð CONTROL-AREA IS CONTROL-FLD. ð2/ð5/94
15 ðð15ðð SELECT PRINTER-FILE ð2/ð5/94
16 ðð16ðð ASSIGN TO PRINTER-QPRINT. ð2/ð5/94
ðð17ðð ð2/ð1/94
17 ðð18ðð DATA DIVISION. ð2/ð1/94
18 ðð19ðð FILE SECTION. ð2/ð1/94
19 ðð2ððð FD RECOVFILE ð2/ð5/94
2ð ðð21ðð LABEL RECORDS ARE OMITTED ð2/ð5/94
21 ðð22ðð DATA RECORD IS RECOV-REC. ð2/ð5/94
22 ðð23ðð ð1 RECOV-REC. ð2/ð5/94
23 ðð24ðð COPY DDS-ALL-FORMATS OF RECVFILE. ð3/22/94
24 +ððððð1 ð5 RECVFILE-RECORD PIC X(5). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:FORMAT1 FROM FILE RECVFILE OF LIBRARY COBNATEX <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
25 +ððððð4 ð5 FORMAT1-I REDEFINES RECVFILE-RECORD. <-ALL-FMTS
26 +ððððð5 ð6 INPUTFLD PIC X(5). <-ALL-FMTS
+ððððð6\ OUTPUT FORMAT:FORMAT1 FROM FILE RECVFILE OF LIBRARY COBNATEX <-ALL-FMTS
+ððððð7\ <-ALL-FMTS
+ððððð8\ ð5 FORMAT1-O REDEFINES RECVFILE-RECORD. <-ALL-FMTS
ðð25ðð
27 ðð26ðð FD PRINTER-FILE.
28 ðð27ðð ð1 PRINTER-REC.
29 ðð28ðð ð5 PRINTER-RECORD PIC X(132).
ðð29ðð
3ð ðð3ððð WORKING-STORAGE SECTION.
ðð31ðð
31 ðð32ðð ð1 I-O-VERB PIC X(1ð).
32 ðð33ðð ð1 STATUS-FLD PIC X(2).
33 ðð34ðð 88 NO-ERROR VALUE "ðð".
34 ðð35ðð 88 ACQUIRE-FAILED VALUE "9H".
35 ðð36ðð 88 TEMPORARY-ERROR VALUE "9N".
36 ðð37ðð ð1 STATUS-FLD-2 PIC X(4).
37 ðð38ðð ð1 CONTROL-FLD.
38 ðð39ðð ð5 FUNCTION-KEY PIC X(2).
39 ðð4ððð ð5 PGM-DEVICE-NAME PIC X(1ð).
4ð ðð41ðð ð5 RECORD-FORMAT PIC X(1ð).
41 ðð42ðð ð1 END-INDICATOR PIC 1 INDICATOR 1
42 ðð43ðð VALUE B"ð".
43 ðð44ðð 88 END-NOT-REQUESTED VALUE B"ð".
44 ðð45ðð 88 END-REQUESTED VALUE B"1".
45 ðð46ðð ð1 USE-PROC-FLAG PIC 1
46 ðð47ðð VALUE B"ð".
47 ðð48ðð 88 USE-PROC-NOT-EXECUTED VALUE B"ð".
48 ðð49ðð 88 USE-PROC-EXECUTED VALUE B"1".
49 ðð5ððð ð1 RECOVERY-FLAG PIC 1
5ð ðð51ðð VALUE B"ð".
51 ðð52ðð 88 NO-RECOVERY-DONE VALUE B"ð".
52 ðð53ðð 88 RECOVERY-DONE VALUE B"1".
53 ðð54ðð ð1 HEADER-LINE.
54 ðð55ðð ð5 FILLER PIC X(6ð)
55 ðð56ðð VALUE SPACES.
56 ðð57ðð ð5 FILLER PIC X(72)
57 ðð58ðð VALUE "ERROR REPORT".
58 ðð59ðð ð1 DETAIL-LINE.
59 ðð6ððð ð5 FILLER PIC X(15)
6ð ðð61ðð VALUE SPACES.
61 ðð62ðð ð5 DESCRIPTION PIC X(25)
62 ðð63ðð VALUE SPACES.
63 ðð64ðð ð5 DETAIL-VALUE PIC X(92)
64 ðð65ðð VALUE SPACES.

Figure 28 (Part 1 of 3). Example of Error Recovery Procedure

Chapter 6. COBOL/400 Exception and Error Handling 85


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
65 ðð66ðð ð1 MESSAGE-LINE.
66 ðð67ðð ð5 FILLER PIC X(15)
67 ðð68ðð VALUE SPACES.
68 ðð69ðð ð5 DESCRIPTION PIC X(117)
69 ðð7ððð VALUE SPACES.
7ð ðð71ðð PROCEDURE DIVISION.
ðð72ðð DECLARATIVES.
ðð73ðð HANDLE-ERRORS SECTION.
ðð74ðð USE AFTER STANDARD ERROR PROCEDURE ON RECOVFILE. .1/
ðð75ðð DISPLAY-ERROR.
71 ðð76ðð SET USE-PROC-EXECUTED TO TRUE.
72 ðð77ðð WRITE PRINTER-REC FROM HEADER-LINE AFTER ADVANCING PAGE.
73 ðð78ðð MOVE "ERROR OCCURRED IN" TO DESCRIPTION OF DETAIL-LINE.
74 ðð79ðð MOVE I-O-VERB TO DETAIL-VALUE OF DETAIL-LINE.
75 ðð8ððð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 5 LINES.
76 ðð81ðð MOVE "FILE STATUS =" TO DESCRIPTION OF DETAIL-LINE.
77 ðð82ðð MOVE STATUS-FLD TO DETAIL-VALUE OF DETAIL-LINE. .2/
78 ðð83ðð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
79 ðð84ðð MOVE "EXTENDED FILE STATUS =" TO DESCRIPTION OF DETAIL-LINE.
8ð ðð85ðð MOVE STATUS-FLD-2 TO DETAIL-VALUE OF DETAIL-LINE.
81 ðð86ðð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
82 ðð87ðð MOVE "CONTROL-AREA =" TO DESCRIPTION OF DETAIL-LINE.
83 ðð88ðð MOVE CONTROL-FLD TO DETAIL-VALUE OF DETAIL-LINE.
84 ðð89ðð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
ðð9ððð CHECK-ERROR.
85 ðð91ðð IF TEMPORARY-ERROR AND NO-RECOVERY-DONE THEN
86 ðð92ðð MOVE "\\\ERROR RECOVERY BEING ATTEMPTED\\\" .3/
ðð93ðð TO DESCRIPTION OF MESSAGE-LINE
87 ðð94ðð WRITE PRINTER-REC FROM MESSAGE-LINE
ðð95ðð AFTER ADVANCING 3 LINES
88 ðð96ðð PERFORM ERROR-RECOVERY
ðð97ðð ELSE
89 ðð98ðð IF RECOVERY-DONE THEN .4/
9ð ðð99ðð MOVE "\\\ERROR AROSE FROM RETRY AFTER RECOVERY\\\"
ð1ðððð TO DESCRIPTION OF MESSAGE-LINE
91 ð1ð1ðð WRITE PRINTER-REC FROM MESSAGE-LINE
ð1ð2ðð AFTER ADVANCING 3 LINES
92 ð1ð3ðð MOVE "\\\PROGRAM TERMINATED\\\"
ð1ð4ðð TO DESCRIPTION OF MESSAGE-LINE
93 ð1ð5ðð WRITE PRINTER-REC FROM MESSAGE-LINE
ð1ð6ðð AFTER ADVANCING 2 LINES
94 ð1ð7ðð GO TO ERROR-EXIT
ð1ð8ðð ELSE
95 ð1ð9ðð SET NO-RECOVERY-DONE TO TRUE.
96 ð11ððð MOVE "\\\EXECUTION CONTINUES\\\"
ð111ðð TO DESCRIPTION OF MESSAGE-LINE.
97 ð112ðð WRITE PRINTER-REC FROM MESSAGE-LINE
ð113ðð AFTER ADVANCING 2 LINES.
98 ð114ðð GO TO END-OF-DECLARATIVES.
ð115ðð ERROR-RECOVERY.
99 ð116ðð SET RECOVERY-DONE TO TRUE.
1ðð ð117ðð DROP PGM-DEVICE-NAME FROM RECOVFILE.
1ð1 ð118ðð ACQUIRE PGM-DEVICE-NAME FOR RECOVFILE. .5/
ð119ðð ERROR-EXIT.
1ð2 ð12ððð CLOSE RECOVFILE
ð121ðð PRINTER-FILE.
ð122ðð END-OF-DECLARATIVES.
ð123ðð END DECLARATIVES.
ð124ðð
ð125ðð MAIN-PROGRAM SECTION.
ð126ðð MAINLINE.
1ð3 ð127ðð MOVE "OPEN" TO I-O-VERB.
1ð4 ð128ðð OPEN I-O RECOVFILE
ð129ðð OUTPUT PRINTER-FILE.
1ð5 ð13ððð PERFORM I-O-PARAGRAPH UNTIL END-REQUESTED. .6/
1ð6 ð131ðð CLOSE RECOVFILE
ð132ðð PRINTER-FILE.
1ð7 ð133ðð STOP RUN.
ð134ðð I-O-PARAGRAPH.
1ð8 ð135ðð MOVE "WRITE" TO I-O-VERB.
1ð9 ð136ðð SET USE-PROC-NOT-EXECUTED TO TRUE.
11ð ð137ðð WRITE RECOV-REC FORMAT IS "FORMAT1"
ð138ðð INDICATOR IS END-INDICATOR.
111 ð139ðð IF USE-PROC-EXECUTED AND RECOVERY-DONE THEN .7/
112 ð14ððð GO TO I-O-PARAGRAPH.

Figure 28 (Part 2 of 3). Example of Error Recovery Procedure

86 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
113 ð141ðð MOVE "READ" TO I-O-VERB.
114 ð142ðð SET USE-PROC-NOT-EXECUTED TO TRUE.
115 ð143ðð SET NO-RECOVERY-DONE TO TRUE.
116 ð144ðð READ RECOVFILE FORMAT IS "FORMAT1"
ð145ðð INDICATOR IS END-INDICATOR. .8/
117 ð146ðð IF NO-ERROR THEN
118 ð147ðð PERFORM SOME-PROCESSING.
ð148ðð SOME-PROCESSING.
119 ð149ðð (INSERT SOME DATABASE PROCESSING, FOR EXAMPLE).
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 28 (Part 3 of 3). Example of Error Recovery Procedure

.1/ This defines processing that takes place when an I/O error occurs on
RECOVFILE.
.2/ This prints out information to help in diagnosing the problem.
.3/ If the file-status equals 9N (temporary error), and no previous error recovery
has been attempted for this I/O operation, error recovery is now attempted.
.4/ To avoid program looping, recovery is not attempted now if it was attempted
previously.
.5/ Recovery consists of dropping, then reacquiring, the program device on
which the I/O error occurred.
.6/ The mainline of the program consists of writing to and reading from a device
until the user signals an end to the program by pressing F1.
.7/ If the WRITE operation failed but recovery was done, the WRITE is
attempted again.
.8/ If the READ operation failed, processing will continue by writing to the device
again, and then attempting the READ again.

Chapter 6. COBOL/400 Exception and Error Handling 87


88 COBOL/400 User’s Guide
Chapter 7. File and Data Management
This chapter contains general file and data management information you may need
when creating COBOL/400 applications.

This chapter describes:


Ÿ The device-independent and device-dependent characteristics of COBOL/400
programs on the AS/400 system
Ÿ Input and output spooling functions
Ÿ System override considerations
Ÿ File and record locking considerations
Ÿ Commitment control
Ÿ Unblocking and blocking records
Ÿ File status and feedback areas
Ÿ General information about the use of program-described files and externally
described files in a COBOL/400 program
Ÿ The Format 2 COPY statement (DD, DDR, DDS, or DDSR option).

The maximum number of files that you can define and open within number of files
used by a program a COBOL program is 99. If you use extended display options,
the maximum number is 98. For information on specifying the extended display
options, refer to page 23 .

Device Independence and Device Dependence


The key element for all I/O operations on the AS/400 system is the file. All files
used are defined to the operating system. The operating system maintains a
description of each file that is used by a program.

The files are kept online and serve as the connecting link between a program and
the device used for I/O. The actual device association is made when the file is
processed. In some instances, this type of I/O control allows the user to change
the attribute of the file (and, in some cases, change the device) used in a program
without changing the program.

In the COBOL/400 language, the file name specified in the ASSIGNMENT-NAME


entry of the ASSIGN clause of the file control entry is used to point to the file. This
file name points to the system file description:

COBOL program FILEX

SELECT file name


ASSIGN TO PRINTER-FILEX DEV(QPRINT)
(assignment-name)

Printer

The COBOL device name in the ASSIGN clause defines the COBOL functions that
can be processed on the selected file. At compilation time, certain COBOL func-

 Copyright IBM Corp. 1994 89


tions are valid only for a specific COBOL device name; in this respect, COBOL is
device dependent. The following are examples of device dependency:
Ÿ SUBFILE operations are valid only for a WORKSTATION device.
Ÿ Indicators are valid only for WORKSTATION or FORMATFILE devices.
Ÿ LINAGE is valid only for the PRINTER device.
Ÿ OPEN INPUT WITH NO REWIND is valid only for a TAPEFILE device.

For example, assume that the file name FILEY is associated in the COBOL
program with the FORMATFILE device. The device FORMATFILE is an inde-
pendent device type. Therefore, no line or page control specifications are valid in
the COBOL program in the WRITE ADVANCING statement. When the program is
run, the actual I/O device is specified in the description of FILEY. For example, the
device might be a printer; only the default line and page control or those defined in
the DDS would be used:

COBOL program FILEY

SELECT file-name DEV(QPRINT)


ASSIGN TO FORMATFILE-FILEY

Printer

CL commands can be used to override a parameter in the specified file description


or to redirect a file at compilation time or run time. File redirection allows the user
to specify one file at compilation time and another file at run time:

FILEX

Compile
Time DEV(QPRINT)

COBOL Program

Override Command:
SELECT file-name OVRDKTF FILE(FILEX) TOFILE (FILEA)
ASSIGN TO FORMATFILE-FILEX
FILEA
Diskette
Run DEV(QDKT)
Time

In the preceding example, the Override to Diskette File command (OVRDKTF)


allows the program to run with an entirely different device file than was specified at
compilation time.

Not all file redirections or overrides are valid. At run time, checking occurs to
ensure that the specifications within the COBOL program are valid for the file being
processed. The OS/400 operating system allows some file redirections even if
device specifics are contained in the program. For example, if the COBOL device
name is PRINTER and the actual file the program uses is not a printer, the oper-
ating system ignores the COBOL print spacing and skipping specifications.

90 COBOL/400 User’s Guide


There are other file redirections that the operating system does not allow and that
cause program termination. For example, if the COBOL device name is DATA-
BASE or DISK and a keyed READ operation is specified in the program, the
program is terminated if the actual file the program uses is not a disk or database
file.

See “System Override Considerations” on page 92 for more detailed information on


valid file redirections and file overrides.

Spooling
The AS/400 system provides for the use of input and output spooling functions.
Each AS/400 file description contains a spool attribute that determines whether
spooling is used for the file at run time. The COBOL program is not aware that
spooling is being used. The actual physical device from which a file is read or to
which a file is written is determined by the spool reader or the spool writer. See
the Data Management Guide for more detailed information on spooling.

Output Spool
Output spooling is valid for batch and interactive jobs. The description of the file
that is specified in COBOL by the system-name contains the specification for
spooling as shown in the following example:

COBOL program QPRINT Output


File Queue

SELECT file-name SPOOL(*YES) QPRINT


ASSIGN TO PRINTER-QPRINT OUTQ(QPRINT)

Run Time

Print Writer

Print Writer Time

Printer Device

File override commands can be used at run time to override the spooling options
that are specified in the file description, such as the number of copies to be printed.
In addition, AS/400 spooling support allows you to redirect a file after the program
has run. For example, you can direct the printer output to a different device, such
as a diskette.

Chapter 7. File and Data Management 91


Input Spool
Input spooling is valid only for inline data files in batch jobs. If the input data read
by COBOL comes from a spooled file, COBOL is not aware of which device the
data was spooled in from.

The data is read from a spooled inline file:

Diskette

FILEA COBOL program


*NO
DEV(QDKT) SELECT file-name
Spool SPOOL(*YES) ASSIGN TO DISKETTE-FILEA

*YES

Spooled
File

See the Data Management Guide for more information on inline data files.

System Override Considerations


You must specify any overrides before the file is opened by the COBOL program.
The system uses the file override command to determine the file to open and the
attributes of the file.

The simplest form of overriding a file is to override some attributes of the file. For
example, FILE(OUTPUT) with COPIES(2) is specified when a printer file is created.
Then, before the COBOL program is run, the number of printed copies of output
can be changed to 3. The override command is as follows:
OVRPRTF FILE(OUTPUT) COPIES(3)

Another form of file overriding is to redirect the COBOL program to access a dif-
ferent file. When the override redirects the program to a file of the same type (such
as a printer file to another printer file), the file is processed in the same manner as
the original file.

When the override redirects the program to a file of a different type, the overriding
file is processed in the same manner as the original file would have been proc-
essed. Device-dependent specifications in the COBOL program are ignored, and
the defaults are taken by the system.

Not all file redirections are valid. For example, an indexed file for a COBOL
program can only be overridden to another indexed file with a keyed access path.

Multiple member processing can be accomplished for a database file by overriding


a database file to process all members. Note the following exceptions:
Ÿ A database source file used for a COBOL program cannot be overridden to
process all members. Specifying OVRDBF MBR(*ALL) will result in the termi-
nation of the compilation.

92 COBOL/400 User’s Guide


Ÿ A database file used for a COPY statement cannot be overridden to process all
members. Specifying OVRDBF MBR(*ALL) will cause the COPY statement to
be ignored.

The COBOL programmer must ensure that file overrides are applied properly. For
more information on valid file redirections, the device dependent characteristics
ignored, and the defaults assumed, see the Data Management Guide.

File and Record Locking by COBOL


The operating system allows a lock state (exclusive, exclusive allow read, shared-
for-update, shared-no-update, or shared-for-read) to be placed on a file used during
a job step. The file can be placed in a lock state with the Allocate Object
(ALCOBJ) command.

By default, the operating system places the following lock states on database files
when the files are opened by COBOL programs:

OPEN Type Lock State


INPUT Shared-for-read
I/O Shared-for-update
EXTEND Shared-for-update
OUTPUT Shared-for-update

EXTEND mode is a method of adding records to the end of a sequential file when
the file is opened.

The shared-for-read lock state allows another user to open the file with a lock state
of shared-for-read, shared-for-update, shared-no-update, or exclusive-allow-read,
but the user cannot specify the exclusive use of the file. The shared-for-update
lock state allows another user to open the file with a shared-for-read or shared-for-
update lock state.

The operating system places the shared-for-read lock on the device file and an
exclusive-allow-read lock state on the device. Another user can open the file but
cannot use the same device.
Note: When a COBOL program opens a physical file for OUTPUT, that file will be
subject to an exclusive lock for the period of time necessary to clear the
member.

For more information on allocating resources and the lock states, see the Data
Management Guide.

Locking and Releasing Records


When a database record is read by COBOL and the file is opened for I/O, a lock is
placed on that record so that another program cannot update it. That is, the record
can be read by another program if it opens a file for input, but not if it opens the file
for I/O.

For information about the duration of record lock with and without commitment
control, refer to Table 2 on page 96.

Chapter 7. File and Data Management 93


To prevent the READ statement from locking records on files opened in I/O
(update) mode, you can use the NO LOCK phrase. The READ WITH NO LOCK
statement unlocks records locked by a previous READ statement. For more infor-
mation about this phrase, refer to the section on the READ statement in the
COBOL/400 Reference.

For a logical file based on one physical file, the lock is placed on the record in the
physical file. If a logical file is based on more than one physical file, a lock is
placed on one record in each physical file.

This lock applies not only to other programs, but also to the original program if it
attempts to update the same underlying physical record through a second file.
Note: When a file with indexed or relative organization is opened for I/O, using
random or dynamic access, a failed I/O operation on any of the I/O verbs
except WRITE also unlocks the record. A WRITE operation is not consid-
ered an update operation; therefore, the record lock is not released.

For more information about releasing database records read for update, see the
Data Management Guide.

Sharing an Open Data Path


If you have already opened a file through another program in your routing step,
your COBOL program can use the same Open Data Path (ODP) to access the file.
Note: Routing steps are described in the Programming: Work Management
Guide; a job usually contains only one routing step.

The following rules apply to shared ODPs:


1. You must specify SHARE(*YES) in the command that creates the file, in a
change command, or in an override command for the file.
2. Once a file with a shared ODP has been opened for the first time by a program
and remains open, subsequent OPEN operations within the same routing step
run faster than standard OPEN operations. The speed of I/O operations other
than opens is not affected.
3. Your use of the file within your different programs should be consistent. For
example, if a non-COBOL program performs a READ PREVIOUS operation
using blocked I/O, the COBOL READ statement might retrieve the record pre-
ceding the current file position rather than the record following the current file
position.

Commitment Control Considerations


Commitment control is a function that allows:
Ÿ Synchronization of changes to database files within the same job
Ÿ Cancelation of changes that should not be permanently entered into the data-
base
Ÿ Locking of records being changed until changes are complete
Ÿ Techniques for recovering from job or system failure.

In some applications, it is desirable to synchronize changes to database records. If


the program determines the changes are valid, the changes are then permanently

94 COBOL/400 User’s Guide


made to the database (a COMMIT statement is processed). If the changes are not
valid, or if a problem occurs during processing, the changes can be canceled (a
ROLLBACK statement is processed). (When a file is cleared after being opened
for OUTPUT, processing of a ROLLBACK does not restore cleared records to the
file.) Changes made to records in a file that is not under commitment control are
always permanent. Such changes are never affected by subsequent COMMIT or
ROLLBACK statements.

Each point where a COMMIT or ROLLBACK is successfully processed is a commit-


ment boundary. (If no COMMIT or ROLLBACK has yet been issued in a program,
a commitment boundary is created by the first open of any file under commitment
control.) The committing or rolling back of changes only affects changes made
since the previous commitment boundary.

The synchronizing of changes at commitment boundaries makes restart or recovery


procedures after a failure easier. For more information, see “Recovery After a
Failure” on page 82.

When commitment control is used for database files, records in those files are
subject to either a high lock level LCKLVL (*ALL) or a low lock level
LCKLVL(*CHG). With a low lock level (*CHG), all records that are changed
(rewritten, deleted, or added) in files under commitment control are locked until a
COMMIT or ROLLBACK statement is successfully processed. With a high lock
level (*ALL), all records accessed, whether for input or output, are locked until a
COMMIT or ROLLBACK is successfully processed. For both record locking levels,
no other job can modify data in locked records until the COMMIT or ROLLBACK
has been successfully completed. (A locked record can only be modified within the
same job and through the same physical or logical file.)

The lock level also governs whether locked records can be read. With a high lock
level (*ALL), you cannot read locked records in a database file. With a low lock
level (*CHG), you can read locked records in a database file, provided the file is
opened as INPUT in your job, or opened as I/O and READ WITH NO LOCK is
used.

| A third lock level can be obtained by specifying LCKLVL(*CS), in which every


| record accessed from files under commitment control is locked. Records that are
| not updated or deleted are locked only until a different record is accessed.
| Records that are updated, added, or deleted are locked until the transaction is com-
| mitted or rolled back.

Other jobs, where files are not under commitment control, can always read locked
records, regardless of the lock level used, provided the files are opened as INPUT.
Because it is possible in some cases for other jobs to read locked records, data
can be accessed before it is permanently committed to a database. If a
ROLLBACK statement is processed after another job has read locked records, the
data accessed will not reflect the contents of the database.

Table 2 shows record locking considerations for files with and without commitment
control.

Chapter 7. File and Data Management 95


Table 2. Record Locking Considerations with and without Commitment Control
VERB OPEN LOCK LEVEL DURATION OF RECORD LOCK
MODE Next I/O COMMIT or
Operation ROLLBACK
│ │
6 6

DELETE I-O DELETE │


.
Without Commitment Control │
─────────────────────────────────────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5

*ALL
READ INPUT READ │
.
Without Commitment Control │
.
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5

*ALL
READ I-O READ │
.
WITH Without Commitment Control │
NO .
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5
LOCK
*ALL
READ I-O READ │
───────────────────────────5
Without Commitment Control │
───────────────────────────5
With Commitment Control *CHG ────────────────────────────┼─────────────────────────────5

*ALL
REWRITE I-O REWRITE │
.
Without Commitment Control │
─────────────────────────────────────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5

*ALL
START INPUT START │
.
Without Commitment Control │
.
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5

*ALL
START I-O START │
───────────────────────────5
Without Commitment Control │
───────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5

*ALL
WRITE I-O WRITE │
.
Without Commitment Control │
─────────────────────────────────────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5

*ALL
WRITE OUTPUT WRITE │
.
Without Commitment Control │
─────────────────────────────────────────────────────────5
With Commitment Control *CHG ────────────────────────────┼────────────────────────────5

*ALL

A file under commitment control can be closed or opened without affecting the
status of changes made since the last commitment boundary. A COMMIT must still
be issued to make the changes permanent, or a ROLLBACK issued to cancel the
changes. A COMMIT statement, when processed, leaves files in the same open or
closed state as before processing.

All files under commitment control within the same job must be journaled to the
same journal. For more information about journal management and its related
functions, and for more information about commitment control, refer to the
Advanced Backup and Recovery Guide.

Commitment control must also be specified outside the COBOL language through
the OS/400 control language (CL). The Start Commitment Control (STRCMTCTL)
command establishes the capability for commitment control and sets the level of
record locking at the high level (*ALL), or the low level (*CHG). The STRCMTCTL
command does not automatically initiate commitment control for a file. That file
must also be specified in the COMMITMENT CONTROL clause of the
I-O-CONTROL paragraph within the COBOL program. The commitment control
environment is normally ended by using the End Commitment Control

96 COBOL/400 User’s Guide


(ENDCMTCTL) command. This causes any uncommitted changes for database
files under commitment control to be canceled. (An implicit ROLLBACK is proc-
essed.) Refer to the CL Reference for more information on the STRCMTCTL and
ENDCMTCTL commands.

For more information about commitment control, see the Advanced Backup and
Recovery Guide.
Note: The ability to prevent reading of uncommitted data that has been changed
is a function of commitment control and is only available if you are running
under commitment control. Normal (noncommitted) database support is not
changed by the commitment control extension, and allows reading of locked
records when a file that is opened only for input is read. Try to use files
consistently. Typically, files should always be run under commitment
control or never be run under commitment control.

Figure 29 on page 98 illustrates a possible usage of commitment control in a


banking environment. The program processes transactions for transferring funds
from one account to another. If no problems occur during the transaction, the
changes are committed to the database file. If the transfer cannot take place
because of improper account number or insufficient funds, a ROLLBACK is issued
to cancel the changes.

Chapter 7. File and Data Management 97


AS/400 DATA DESCRIPTION SPECIFICATIONS G X 2 1 - 9 8 9 1 - 0 U M/ 0 5 0 *
Pr i n t ed i n U . S . A.
I nt er nat i onal Bus i nes s Machi nes *Number of sheets per pad may var y slightl y.

Fi le Keying Graphic Description Page of


Instruction
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functions

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indicator

Reserved
Indicator

Indicator

Decimal
Not (N)

Not (N)
Not (N)

Line Pos

1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 19 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0

A* P R OMP T S CR E E N F I L E NAME ' ACC T F M T S '


A*
A I ND A R A
A R ACC T P M T
A T E X T ( ' C U S T OME R ACCOU N T P R OMP T ' )
A
A CA 0 1 ( 1 5 ' E ND O F P R OGR AM ' )
A P U T R E T A I N OV E R L A Y
A 1 3 ' ACCOU N T MA S T E R U P D A T E '
A 3 3 ' F R OM ACCOU N T N UMB E R '
A ACC T F R OM 5Y 0I 3 2 3 C H E CK ( ME )
A 99 E R R MS G ( ' I N V A L I D F R OM ACCOU N T +
A N UMB E R ' 9 9 )
A 98 E R R MS G ( ' I N S U F F I C I E N T F U ND S I N F R OM +
A ACCOU N T ' 9 8 )
A 4 3 ' T O ACCOU N T N UMB E R '
A ACC T T O 5Y 0I 4 2 3 C H E CK ( ME )
A 97 E R R MS G ( ' I N V A L I D T O ACCOU N T +
A N UMB E R ' 9 7 )
A 5 3 ' AMOU N T T R AN S F E R R E D '
A T R AN S AM T 10Y02 I 5 23
A R E R R F MT
A 96 6 5 ' I NVA L I D F I L E S T A T U S '
A 96 7 5 ' I N V A L I D K E Y I N R E WR I T E '
A
A
A
A
A
A
A
A
A
A
A

Figure 29. Example of Use of Commitment Control --DDS

98 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð2/ð1/94
2 ððð2ðð PROGRAM-ID. ACCOUNT. ð2/ð4/94
3 ððð3ðð AUTHOR. PROGRAMMER NAME. ð1/27/94
4 ððð4ðð INSTALLATION. COBOL DEVELOPMENT CENTRE. ð1/27/94
5 ððð5ðð DATE-WRITTEN. ð2/ð2/88. ð2/ð4/94
8 ðððð8ð DATE-COMPILED. ð5/24/92 14:ð2:39 . ð3/ð1/94
7 ððð7ðð ENVIRONMENT DIVISION. ð1/27/94
8 ððð8ðð CONFIGURATION SECTION. ð1/27/94
9 ððð9ðð SOURCE-COMPUTER. IBM-AS4ðð. ð1/27/94
1ð ðð1ððð OBJECT-COMPUTER. IBM-AS4ðð. ð1/27/94
11 ðð11ðð INPUT-OUTPUT SECTION. ð1/27/94
12 ðð12ðð FILE-CONTROL. ð1/27/94
13 ðð13ðð SELECT ACCOUNT-FILE ASSIGN TO DATABASE-ACCTMST ð2/ð4/94
14 ðð14ðð ORGANIZATION IS INDEXED ð2/ð4/94
15 ðð15ðð ACCESS IS DYNAMIC ð2/ð4/94
16 ðð16ðð RECORD IS EXTERNALLY-DESCRIBED-KEY ð2/ð4/94
17 ðð17ðð FILE STATUS IS ACCOUNT-FILE-STATUS. ð2/ð4/94
18 ðð18ðð SELECT DISPLAY-FILE ASSIGN TO WORKSTATION-ACCTFMTS-SI .1/ ð2/ð4/94
19 ðð19ðð ORGANIZATION IS TRANSACTION. ð2/ð4/94
ðð2ððð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð2/ð4/94
2ð ðð21ðð I-O-CONTROL. ð2/ð4/94
21 ðð22ðð COMMITMENT CONTROL FOR ACCOUNT-FILE. .2/ ð2/ð4/94
ðð23ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð2/ð4/94
22 ðð24ðð DATA DIVISION. ð2/ð4/94
23 ðð25ðð FILE SECTION. ð2/ð4/94
24 ðð26ðð FD ACCOUNT-FILE ð2/ð4/94
25 ðð27ðð LABEL RECORDS ARE STANDARD. ð2/ð4/94
26 ðð28ðð ð1 ACCOUNT-RECORD. ð2/ð4/94
27 ðð29ðð COPY DDS-ALL-FORMATS OF ACCTMST. ð2/ð4/94
28 +ððððð1 ð5 ACCTMST-RECORD PIC X(82). <-ALL-FMTS
+ððððð2\ I-O FORMAT:ACCNTREC FROM FILE ACCTMST OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
+ððððð4\THE KEY DEFINITIONS FOR RECORD FORMAT ACCNTREC <-ALL-FMTS
+ððððð5\ NUMBER NAME RETRIEVAL TYPE ALTSEQ <-ALL-FMTS
+ððððð6\ ððð1 ACCNTKEY ASCENDING SIGNED NO <-ALL-FMTS
29 +ððððð7 ð5 ACCNTREC REDEFINES ACCTMST-RECORD. <-ALL-FMTS
3ð +ððððð8 ð6 ACCNTKEY PIC S9(5). <-ALL-FMTS
31 +ððððð9 ð6 NAME PIC X(2ð). <-ALL-FMTS
32 +ðððð1ð ð6 ADDR PIC X(2ð). <-ALL-FMTS
33 +ðððð11 ð6 CITY PIC X(2ð). <-ALL-FMTS
34 +ðððð12 ð6 STATE PIC X(2). <-ALL-FMTS
35 +ðððð13 ð6 ZIP PIC S9(5). <-ALL-FMTS
36 +ðððð14 ð6 BALANCE PIC S9(8)V9(2). <-ALL-FMTS
ðð3ððð
37 ðð31ðð FD DISPLAY-FILE
38 ðð32ðð LABEL RECORDS ARE STANDARD.
39 ðð33ðð ð1 DISPLAY-REC.
4ð ðð34ðð COPY DDS-ALL-FORMATS OF ACCTFMTS.
41 +ððððð1 ð5 ACCTFMTS-RECORD PIC X(2ð). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:ACCTPMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ CUSTOMER ACCOUNT PROMPT <-ALL-FMTS
42 +ððððð4 ð5 ACCTPMT-I REDEFINES ACCTFMTS-RECORD. <-ALL-FMTS
43 +ððððð5 ð6 ACCTFROM PIC S9(5). <-ALL-FMTS
44 +ððððð6 ð6 ACCTTO PIC S9(5). <-ALL-FMTS
45 +ððððð7 ð6 TRANSAMT PIC S9(8)V9(2). <-ALL-FMTS
+ððððð8\ OUTPUT FORMAT:ACCTPMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð9\ CUSTOMER ACCOUNT PROMPT <-ALL-FMTS
+ðððð1ð\ ð5 ACCTPMT-O REDEFINES ACCTFMTS-RECORD. <-ALL-FMTS
+ðððð11\ INPUT FORMAT:ERRFMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð12\ <-ALL-FMTS
+ðððð13\ ð5 ERRFMT-I REDEFINES ACCTFMTS-RECORD. <-ALL-FMTS
+ðððð14\ OUTPUT FORMAT:ERRFMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð15\ <-ALL-FMTS
+ðððð16\ ð5 ERRFMT-O REDEFINES ACCTFMTS-RECORD. <-ALL-FMTS
46 ðð35ðð WORKING-STORAGE SECTION.
47 ðð36ðð 77 ACCOUNT-FILE-STATUS PIC X(2).

Figure 30 (Part 1 of 3). Example of Use of Commitment Control

Chapter 7. File and Data Management 99


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
48 ðð37ðð 77 IND-ON PIC 1 VALUE B"1".
49 ðð38ðð 77 IND-OFF PIC 1 VALUE B"ð".
5ð ðð39ðð ð1 DISPFILE-INDICS.
51 ðð4ððð COPY DDS-ALL-FORMATS-INDIC OF ACCTFMTS. .3/
52 +ððððð1 ð5 ACCTFMTS-RECORD. <-ALL-FMTS
+ððððð2\ INPUT FORMAT:ACCTPMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ CUSTOMER ACCOUNT PROMPT <-ALL-FMTS
53 +ððððð4 ð6 ACCTPMT-I-INDIC. <-ALL-FMTS
54 +ððððð5 ð7 IN15 PIC 1 INDIC 15. <-ALL-FMTS
+ððððð6\ END OF PROGRAM <-ALL-FMTS
55 +ððððð7 ð7 IN97 PIC 1 INDIC 97. <-ALL-FMTS
+ððððð8\ INVALID TO ACCOUNT NUMBER <-ALL-FMTS
56 +ððððð9 ð7 IN98 PIC 1 INDIC 98. <-ALL-FMTS
+ðððð1ð\ INSUFFICIENT FUNDS IN FROM ACCOUNT <-ALL-FMTS
57 +ðððð11 ð7 IN99 PIC 1 INDIC 99. <-ALL-FMTS
+ðððð12\ INVALID FROM ACCOUNT NUMBER <-ALL-FMTS
+ðððð13\ OUTPUT FORMAT:ACCTPMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð14\ CUSTOMER ACCOUNT PROMPT <-ALL-FMTS
58 +ðððð15 ð6 ACCTPMT-O-INDIC. <-ALL-FMTS
59 +ðððð16 ð7 IN97 PIC 1 INDIC 97. <-ALL-FMTS
+ðððð17\ INVALID TO ACCOUNT NUMBER <-ALL-FMTS
6ð +ðððð18 ð7 IN98 PIC 1 INDIC 98. <-ALL-FMTS
+ðððð19\ INSUFFICIENT FUNDS IN FROM ACCOUNT <-ALL-FMTS
61 +ðððð2ð ð7 IN99 PIC 1 INDIC 99. <-ALL-FMTS
+ðððð21\ INVALID FROM ACCOUNT NUMBER <-ALL-FMTS
+ðððð22\ INPUT FORMAT:ERRFMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð23\ <-ALL-FMTS
+ðððð24\ ð6 ERRFMT-I-INDIC. <-ALL-FMTS
+ðððð25\ OUTPUT FORMAT:ERRFMT FROM FILE ACCTFMTS OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð26\ <-ALL-FMTS
62 +ðððð27 ð6 ERRFMT-O-INDIC. <-ALL-FMTS
63 +ðððð28 ð7 IN95 PIC 1 INDIC 95. <-ALL-FMTS
64 +ðððð29 ð7 IN96 PIC 1 INDIC 96. <-ALL-FMTS
ðð41ðð
65 ðð42ðð PROCEDURE DIVISION.
ðð43ðð DECLARATIVES.
ðð44ðð ERROR-SECTION SECTION.
ðð45ðð USE AFTER STANDARD EXCEPTION PROCEDURE ON ACCOUNT-FILE.
ðð46ðð ERROR-PARAGRAPH.
66 ðð47ðð IF ACCOUNT-FILE-STATUS IS NOT EQUAL "23" THEN
67 ðð48ðð MOVE IND-ON TO IN96 OF ERRFMT-O-INDIC .4/
ðð49ðð ELSE
68 ðð5ððð MOVE IND-ON TO IN95 OF ERRFMT-O-INDIC. .5/
69 ðð51ðð WRITE DISPLAY-REC FORMAT IS "ERRFMT"
ðð52ðð INDICATORS ARE ERRFMT-O-INDIC.
7ð ðð53ðð READ DISPLAY-FILE.
71 ðð54ðð CLOSE DISPLAY-FILE
ðð55ðð ACCOUNT-FILE.
72 ðð56ðð STOP RUN.
ðð57ðð END DECLARATIVES.
ðð58ðð MAIN-PROGRAM SECTION.
ðð59ðð MAINLINE.
73 ðð6ððð OPEN I-O DISPLAY-FILE
ðð61ðð I-O ACCOUNT-FILE.
74 ðð62ðð MOVE ZEROS TO ACCTPMT-I-INDIC
ðð63ðð ACCTPMT-O-INDIC.
75 ðð64ðð PERFORM WRITE-READ-DISPLAY.
76 ðð65ðð PERFORM VERIFY-ACCOUNT-NO UNTIL IN15 EQUAL IND-ON.
77 ðð66ðð CLOSE DISPLAY-FILE
ðð67ðð ACCOUNT-FILE.
78 ðð68ðð STOP RUN.
ðð69ðð VERIFY-ACCOUNT-NO.
79 ðð7ððð PERFORM VERIFY-TO-ACCOUNT.
8ð ðð71ðð IF IN97 OF ACCTPMT-O-INDIC EQUAL IND-OFF THEN
81 ðð72ðð PERFORM VERIFY-FROM-ACCOUNT.
82 ðð73ðð PERFORM WRITE-READ-DISPLAY.
ðð74ðð VERIFY-FROM-ACCOUNT.
83 ðð75ðð MOVE ACCTFROM TO ACCNTKEY.
84 ðð76ðð READ ACCOUNT-FILE
85 ðð77ðð INVALID KEY MOVE IND-ON TO IN99 OF ACCTPMT-O-INDIC.
86 ðð78ðð IF IN99 OF ACCTPMT-O-INDIC EQUAL IND-ON THEN .6/
ðð79ðð\ \
ðð8ððð ROLLBACK
ðð81ðð\ \
87 ðð82ðð ELSE
88 ðð83ðð PERFORM UPDATE-FROM-ACCOUNT.

Figure 30 (Part 2 of 3). Example of Use of Commitment Control

100 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð84ðð VERIFY-TO-ACCOUNT.
89 ðð85ðð MOVE ACCTTO TO ACCNTKEY.
9ð ðð86ðð READ ACCOUNT-FILE
91 ðð87ðð INVALID KEY MOVE IND-ON TO IN97 OF ACCTPMT-O-INDIC. .7/
92 ðð88ðð IF IN97 OF ACCTPMT-O-INDIC EQUAL IND-ON THEN
ðð89ðð\ \
ðð9ððð ROLLBACK .8/
ðð91ðð\ \
93 ðð92ðð ELSE
94 ðð93ðð PERFORM UPDATE-TO-ACCOUNT.
ðð94ðð UPDATE-TO-ACCOUNT.
95 ðð95ðð ADD TRANSAMT TO BALANCE.
96 ðð96ðð REWRITE ACCOUNT-RECORD.
ðð97ðð UPDATE-FROM-ACCOUNT.
97 ðð98ðð SUBTRACT TRANSAMT FROM BALANCE.
98 ðð99ðð REWRITE ACCOUNT-RECORD.
99 ð1ðððð IF BALANCE IS LESS THAN ð THEN
1ðð ð1ð1ðð MOVE IND-ON TO IN98 OF ACCTPMT-O-INDIC
ð1ð2ðð\ \
ð1ð3ðð ROLLBACK .9/
ð1ð4ðð\ \
1ð1 ð1ð5ðð ELSE
ð1ð6ðð\ \
ð1ð7ðð COMMIT. .1ð/
ð1ð8ðð\ \
1ð2 ð1ð9ðð WRITE-READ-DISPLAY.
1ð3 ð11ððð WRITE DISPLAY-REC FORMAT IS "ACCTPMT"
ð111ðð INDICATORS ARE ACCTPMT-O-INDIC. .11/
1ð4 ð112ðð MOVE ZEROS TO ACCTPMT-I-INDIC
ð113ðð ACCTPMT-O-INDIC.
1ð5 ð114ðð READ DISPLAY-FILE RECORD
ð115ðð INDICATORS ARE ACCTPMT-I-INDIC.
ð116ðð
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 30 (Part 3 of 3). Example of Use of Commitment Control

.1/ A separate indicator area is provided for the program.


.2/ The COMMITMENT CONTROL clause specifies files to be placed under
commitment control. Any files named in this clause are affected by the
COMMIT and ROLLBACK verbs.
.3/ The Format 2 COPY statement with the indicator attribute INDIC, defines
data description entries in WORKING-STORAGE for the indicators to be
used in the program.
.4/ IN96 is set if there is an invalid file status.
.5/ IN95 is set if there is an INVALID KEY condition on the REWRITE operation.
.6/ IN99 is set if the entered account number is invalid for the account to which
money is being transferred.
.7/ IN97 is set if the entered account number is invalid for the account to which
money is being transferred.
.8/ If an INVALID KEY condition occurs on the READ, a ROLLBACK is used
and the record lock placed on the record after the first READ is released.
.9/ If the transfer of funds is not allowed (an indicator has been set), the
ROLLBACK statement is processed. All changes made to database files
under commitment control are canceled.
.1ð/ If the transfer of funds was valid (no indicators have been set), the COMMIT
statement is processed, and all changes made to database files under com-
mitment control become permanent.

Chapter 7. File and Data Management 101


.11/ The INDICATORS phrase is required for options on the work station display
that are controlled by indicators.

Unblocking Input Records and Blocking Output Records


A block contains more than one record. In the interest of improving the perform-
ance of input and output operations, the COBOL compiler generates code to
unblock input records and block output records in either of the following conditions:
1. *NOBLK is specified (with or without a BLOCK CONTAINS clause) and all of
the following conditions are met:
a. ACCESS IS SEQUENTIAL is specified for the file.
b. The file is opened only for INPUT or OUTPUT in that program.
c. The file is assigned to DISK, DATABASE, DISKETTE, or TAPEFILE.
d. No START statements are specified for the file.
For RELATIVE organization, blocking is not performed for OPEN OUTPUT.
If you specify BLOCK CONTAINS, it is ignored except for tape files. For tape
files, the BLOCK CONTAINS clause controls the number of records to be
blocked. If you do not specify BLOCK CONTAINS, the system determines the
number of records to be blocked. In the case of DISKETTE files, the system
always determines the number of records to be blocked.
2. *BLK is specified with BLOCK CONTAINS and all of the following conditions
are met:
a. ACCESS IS SEQUENTIAL or ACCESS IS DYNAMIC is specified for the
file.
b. The file is opened only for INPUT or OUTPUT in that program.
c. The file is assigned to DISK, DATABASE, DISKETTE, or TAPEFILE.
For RELATIVE organization, blocking is not performed for OPEN OUTPUT.
The BLOCK CONTAINS clause controls the number of records to be blocked.
In the case of DISKETTE files, the system always determines the number of
records to be blocked.

Even when all of the above conditions are met, certain OS/400 restrictions can
cause blocking and unblocking to not be processed. In these cases, performance
improvements will not be realized.

If you are using dynamically accessed and indexed organization files, you can use
READ PRIOR and READ NEXT to perform blocking. When using READ PRIOR
and READ NEXT to perform blocking, you cannot change direction while there are
records remaining in the block. To clear the records from a block, specify a
random operation, such as a random READ or a random START, or use a sequen-
tial READ FIRST or READ LAST.

If an illegal change of direction takes place, file status 9U results. No further I/O is
possible until the file is closed and reopened.

You can override blocking at run time by specifying SEQONLY(\NO) for the OVRDBF
command.

102 COBOL/400 User’s Guide


For disk and database files, when you use BLOCK CONTAINS, and if the blocking
factor of zero is specified or calculated, the system determines the blocking factor.

There are certain instances in which the blocking factor you specify may be
changed. See the Database Guide for more information about these situations.

Where a block of records is written or read, the I/O feedback area contains the
number of records in that block. The I/O-FEEDBACK area is not updated after
each read or write for files where multiple records are blocked and unblocked by
COBOL. It is updated when the next block is read or written. See “I/O
FEEDBACK” in the COBOL/400 Reference for more information.

For database files, you may not see all changes as they occur, if the changes are
made in different programs. For a description of the effect of blocking on changes
to database files, see the discussion on sequential-only processing in the Database
Guide.

File Status and Feedback Areas


To transfer data (OPEN-FEEDBACK or I-O-FEEDBACK areas) associated with an
open file to an identifier use the following format:

ACCEPT Statement – Format 3 – Feedback

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───ACCEPT──identifier──FROM──mnemonic-name──┬─────────────────┬────────────5% ║
║ └──FOR──file-name─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

See the “ACCEPT Statement” section of the COBOL/400 Reference for more infor-
mation on specifying this statement. See the “Attribute Data Formats” section of
the COBOL/400 Reference for information on the OPEN-FEEDBACK and the
I-O-FEEDBACK areas.

Refer to the Data Management Guide for information on OPEN-FEEDBACK and


I-O-FEEDBACK and the layout and description of the data areas contained in the
feedback areas.

When the FILE STATUS clause is specified, the system moves a value into the
status key data item after each input/output request that explicitly or implicitly refers
to this file. This 2-character value indicates the run status of the statement. When
the compiler generates code to block output records or unblock input records, file
status values that are caused by OS/400 exceptions are set only when a block is
processed. For more information about blocking records, refer to “Unblocking Input
Records and Blocking Output Records” on page 102.

The I-O-FEEDBACK area is not updated after each read or write for files in which
multiple records are blocked and unblocked by COBOL.

Chapter 7. File and Data Management 103


For database files, you may not see all changes as they occur, if the changes are
made in different programs. For a description of the effect of blocking on changes
to database files, see the discussion on Sequential-Only Processing in the
Database Guide.

File Descriptions
All files on the AS/400 system are defined to the OS/400 operating system. The
extent to which files can be defined differs:
Ÿ A program-described file is described at the field level within the COBOL
program in the Data Division. The description of the file to the operating
system includes information about the type of file and the length of the records
in the file.
Ÿ An externally described file is described at the field level to the operating
system through IDDU, SQL/400* commands, or DDS. If you create a file (for
instance, by using the CRTPF command) without specifying DDS for it, the file
still has a field description. The single field has the same name as the file, and
has the record length you specified in the create command.
The description includes information about the type of file, such as database or
a device, and a description of each field and its attributes. The file must be
created before you compile the program.

Both externally described files and program-described files must be defined in the
COBOL program within the INPUT-OUTPUT SECTION and the FILE SECTION.
Record descriptions in the FILE SECTION for externally described files can be
defined with the Format 2 COPY statement.

Device-dependent functions such as forms control are not extracted by the Format
2 COPY operation. Only field-level descriptions are extracted.

When EXTERNALLY-DESCRIBED-KEY is specified as RECORD KEY, the fields


that make up RECORD KEY are also extracted from DDS.

For more information on the Format 2 COPY statement, see Figure 37 on


page 112 and the accompanying text.
Note: Actual file processing within the Procedure Division is the same, if the file is
externally described or program-described.

Program-Described Files
Records and fields for a program-described file are described by coding record
descriptions in the File Section of the COBOL program instead of using the Format
2 COPY statement.

The file must exist on the system before the program can run, except when you
use dynamic file creation, by specifying GENOPT(*CRTF) on the CRTCBLPGM
command. For more information, refer to the description of the GENOPT param-
eter on page 22, or the OPEN statement in the COBOL/400 Reference. To create
a file, use one of the Create File commands, which can be found in the CL
Reference.

104 COBOL/400 User’s Guide


DDS can be used with the Create File commands. For a COBOL indexed file, a
keyed access path must be created. Specify a key in DDS when the file is created.
The record key in COBOL must match the key defined when the file was created.

Externally Described Files


Externally described files offer the following advantages over program-described
files:
Ÿ Less coding in COBOL programs. If the same file is used by many programs,
the fields can be defined once to the operating system, and then used by all
the programs. This eliminates the need to code a separate record description
for each program that uses the file.
Ÿ Less maintenance activity when the file’s record format is changed. You can
often update programs by changing the file’s record format and then recom-
piling the programs that use the file without changing any coding in the
program.
Ÿ Improved documentation. Programs using the same files use consistent record
format and field names.
Ÿ Any editing to be processed on externally described output files can be speci-
fied in DDS.

The external description for a file includes:


Ÿ The record format specifications that contain a description of the fields in a
record
Ÿ Access path specifications that describe how the records are to be retrieved.

These specifications come from the external file description and from the OS/400
command you use to create the file.

You can use an externally described file within a program by making it a program-
described file (by coding the record description in the source). In this case, the
compiler does not copy the external field-level description of the file at compilation
time. You may find this useful during conversions, since an existing program can
use a program-described file while a new program uses an externally described file
to refer to the same file.

Figure 31 on page 106 shows how COBOL programs can relate to files on the
AS/400 system, making use of external file descriptions from DDS.

Chapter 7. File and Data Management 105


OS/4ðð System OS/4ðð System OS/4ðð System
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│ Field-Level │ │ Record-Level │ │ Field-Level │
│ Description of │ │ Description of │ │ Description of │
│ a File │ │ a File │ │ a File │
└───────┬────────┘ └───────┬────────┘ └──────────────┬─┘
│ │ │
│ │ │
┌─────────────┴────────┐ └─────┬─────────────────────┐ │
│ │ │ │ │
6 6 6 6 6
COBOL .1/ COBOL .2/ COBOL .3/ COBOL .4/
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ File is │ │ Program- │ │ Program- │ │ File is │
│ Externally │ │ Described │ │ Described │ │ Externally │
│ Described │ │ File. The │ │ File. │ │ Described │
│ through │ │ compiler │ │ │ │ through │
│ DDS. │ │ does not │ │ │ │ DDS. │
│ │ │ copy a │ │ │ │ │
│ │ │ field-level │ │ │ │ │
│ │ │ description. │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘

Figure 31. Example showing how COBOL can relate to AS/400 files

.1/ The COBOL program uses the field level description of a file that is defined to
the operating system. The COBOL user coded a Format 2 COPY statement
for the record description. At compilation time, the compiler copies in the
external field-level description and translates it into a syntactically correct
COBOL record description. The file must exist at compilation time.
.2/ An externally described file is used as a program-described file in the COBOL
program. The entire record description for the file is coded in the COBOL
program. This file does not have to exist at compilation time.
.3/ A file is described to the operating system as far as the record level only.
The entire record description must be coded in the COBOL program. This file
does not have to exist at compilation time.
.4/ A file name can be specified for compilation time, and a different file name
can be specified for run time. A COBOL Format 2 COPY statement gener-
ates the record description for the file at compilation time. At run time, a dif-
ferent library list or a file override command can be used so that a different
file is accessed by the program. The file description copied in at compilation
time is used to describe the input records used at run time.
Note: For externally described files, the two file formats must be the same. Other-
wise, a level check error will occur.

Data Description Specifications (DDS)


You can use Data Description Specifications (DDS) to describe files at the field
level to the operating system. In DDS, each record format in an externally
described file is identified by a unique record format name.

The record format specifications describe the fields in a record and the location of
the fields in a record. The fields are located in the record in the order specified in
DDS. The field description generally includes the field name, the field type (char-
acter, binary, external decimal, or internal decimal), and the field length (including
the number of decimal positions in a numeric field). Instead of being specified in
the record format for a physical or logical file, the field attributes can be defined in a
field reference file. (See Figure 32 on page 107.)

The keys for a record format are specified in DDS. When you use a Format 2
COPY statement, a table of comments is generated in the source program listing
showing how the keys for the format are defined in DDS.

106 COBOL/400 User’s Guide


In addition, DDS keywords can be used to:
Ÿ Specify edit codes for a field (EDTCDE)
Ÿ Specify edit words for a field (EDTWRD)
Ÿ Specify that duplicate key values are not allowed for the file (UNIQUE)
Ÿ Specify a text description for a record format or a field (TEXT).

See the DDS Reference for a complete list of the DDS keywords that are valid for a
database file.

AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*


Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key
Type of Name of S pec /(b/R/H/J/K/S /O)

Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons


Reference (R)

Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A * * F L DR E F DS TRE F D I S T R I B U T I ON A P P L I C A T I ON F I E L D R E F E R E NC E
A R DS TRE F T E X T ( ' D I S T R I B U T I ON F I E L D R E F ' )
A * COMMON F I E L D S U S E D A S R E F E R E NC E
A B A S DA T 6 0 E D T CD E ( Y )
A T E X T ( ' B A S E DA T A F I E L D ' )
A * F I E L D S U S E D B Y C U S T OME R MA S T E R F I L E
A CU S T 5 CH E CK ( MF )
A CO L H DG ( ' C U S T OME R ' ' N UMB E R ' )
A N AME 20 CO L H DG ( ' C U S T OME R N AME ' )
A AD D R R R E F F L D ( N AME )
A CO L H DG ( ' C U S T OME R AD D R E S S ' )
A CI TY R R E F F L D ( N AME )
A CO L H DG ( ' C U S T OME R C I T Y ' )
A S TAT E 2 CH E CK ( MF )
A CO L H DG ( ' S T A T E ' )
A S R H COD 6 CH E CK ( MF )
A CO L H DG ( ' S E A R C H ' ' COD E ' )
A T E X T ( ' C U S T OME R N UMB E R S E A R C H COD E ' )
A Z I P 5 0 CH E CK ( MF )
A CO L H DG ( ' Z I P ' ' COD E ' )
A CU S T Y P 1 0 R A NG E ( 1 5 )
A CO L H DG ( ' C U S T ' ' T Y P E ' )
A T E X T ( ' C U S T OME R T Y P E 1 = GOV 2 = S C H 3 = B +
A U S 4 = P T 5 =O T H ' )
A AR B A L 8 2 CO L H DG ( ' ACC T S R E C ' ' B A L A NC E ' )
A E D T CD E ( J )
A OR D B A L R R E F F L D ( AR B A L )
A CO L H DG ( ' A / R AM T I N ' ' OR D E R F I L E ' )
A L S T AM T R R E F F L D ( AR B A L )
A CO L H DG ( ' L A S T ' ' AMOU N T ' ' P A I D ' )
A T E X T ( ' L A S T AMOU N T P A I D I N A / R ' )
A
A
A
A

Figure 32. Example of a Field Reference File

This example of a field reference file shows the definitions of the fields that are
used by the CUSMSTL (customer master logical) file, which is shown in Figure 33
on page 109. The field reference file normally contains the definitions of fields that

Chapter 7. File and Data Management 107


are used by other files. The following text describes some of the entries for this
field reference file.
.1/ The BASDAT field is edited by the Y edit code, as indicated by the keyword
EDTCDE (Y). If this field is used in an externally described output file for a
COBOL program, the COBOL-generated field is compatible with the data
type specified in the DDS. The field is edited when the record is written.
When the field is used in a program-described output file, compatibility with
the DDS fields in the file is the user’s responsibility. When DDS is not used
to create the file, appropriate editing of the field in the COBOL program is
also the user’s responsibility.
.2/ The CHECK(MF) entry specifies that the field is a mandatory fill field when it
is entered from a display work station. Mandatory fill means that all charac-
ters for the field must be entered from the display work station.
.3/ The ADDR and CITY fields share the same attributes that are specified for
the NAME field, as indicated by the REFFLD keyword.
.4/ The RANGE keyword, which is specified for the CUSTYP field, ensures that
the only valid numbers that can be entered into this field from a display work
station are 1 through 5.
.5/ The COLHDG keyword provides a column head for the field if it is used by
the Application Development Tools (Appl Dev Tools).
.6/ The ARBAL field is edited by the J edit code, as indicated by the keyword
EDTCDE(J).
.7/ A text description (TEXT keyword) is provided for some fields. The TEXT
keyword is used for documentation purposes and appears in various listings.

COBOL Specifications for Files Described Externally Using DDS


You can incorporate the file description in your program by coding a Format 2
COPY statement. The information from the external description is then retrieved by
the COBOL compiler, and a COBOL data structure is generated.

The following pages provide examples of DDS usage and the COBOL code that
would result from the use of a Format 2 COPY statement. (See “Format 2 COPY
Statement (DD, DDR, DDS, or DDSR Option)” on page 112 for a detailed
description of the Format 2 COPY statement.)
Ÿ Figure 33 on page 109 shows the DDS for a logical file and Figure 34 on
page 110 shows the COBOL code generated.
Ÿ Figure 35 on page 111 describes the same file but includes the ALIAS
keyword, and Figure 36 on page 112 shows the COBOL code generated.

Actual file processing within the Procedure Division is the same for both program-
described and externally described files.

108 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* * L OG I CA L CU S MS T L C U S T OME R MA S T E R F I LE
A U N I QU E
A* R CU S R E C P F I L E ( CU S MS T P )
A T E X T ( ' C U S T OME R MA S T E R R E COR D ' )
A CU S T
A N AME
A AD D R
A CI TY
A S TAT E
A Z I P
A S R H COD
A CU S T Y P
A AR B A L
A OR D B A L
A L S T AM T
A L S T DA T
A CR D L M T
A S L S YR
A S L S L YR
A K CU S T
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 33. Example of Data Description Specifications for a Logical File

.1/ A logical file for processing the customer master physical file (CUSMSTP) is
defined and named CUSMSTL.
.2/ The UNIQUE keyword indicates that duplicate key values for this file are not
allowed.
.3/ One record format (CUSREC) is defined for the CUSMSTL file, which is to
be based upon the physical file CUSMSTP.
.4/ The CUST field is identified as the key field for this file.
.5/ If field attributes (such as length, data type, and decimal positions) are not
specified in the DDS for a logical file, the attributes are obtained from the
corresponding field in the physical file. Any field attributes specified in the
DDS for the logical file override the attributes for the corresponding field in

Chapter 7. File and Data Management 109


the physical file. The definition of the fields in the physical file could refer to
a field reference file. A field reference file is a data description file consisting
of field names and their definitions, such as size and type. When a field
reference file is used, the same fields that are used in multiple record
formats have to be defined only once in the field reference file. For more
information on a field reference file, see the Database Guide.

Figure 32 on page 107 shows an example of a field reference file that defines the
attributes of the fields used in the database file. See the Database Guide for more
information regarding field reference files.

ð1 CUS-MASTER.
COPY DDS-CUSREC OF CUSLIB-CUSTMAST.
\I-O FORMAT: CUSREC FROM FILE CUSTMAST OF LIBRARY CUSLIB CUSREC
\ CUSTOMER MASTER RECORD CUSREC
\THE KEY DEFINITIONS FOR THE RECORD FORMAT CUSREC CUSREC
\NUMBER NAME RETRIEVAL TYPE ALTSEQ CUSREC
\ððð1 CUST ASCENDING AN NO CUSREC
ð5 CUSREC. CUSREC
ð6 CUST PIC X(5). CUSREC
\ CUSTOMER NUMBER CUSREC
ð6 NAME PIC X(2ð). CUSREC
\ CUSTOMER NAME CUSREC
ð6 ADDR PIC X(2ð). CUSREC
\ CUSTOMER ADDRESS CUSREC
ð6 CITY PIC X(2ð). CUSREC
\ CUSTOMER CITY CUSREC
ð6 STATE PIC X(2). CUSREC
\ STATE ABBREVIATION CUSREC
ð6 ZIP PIC S9(5) COMP-3. CUSREC
\ ZIP CODE CUSREC
ð6 SHRCOD PIC X(6). CUSREC
\ CUSTOMER NAME SEARCH CODE CUSREC
ð6 CUSTYP PIC 9(1). CUSREC
\ CUSTOMER TYPE CUSREC
ð6 ARBAL PIC S9(6)V9(2) COMP-3. CUSREC
\ ACCT/REC BALANCE CUSREC

Figure 34. Example of the Results of the Format 2 COPY Statement (DDS)

110 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* * L OG I CA L CU S MS T L C U S T OME R MA S T E R F I LE
A U N I QU E
A* R CU S R E C P F I L E ( CU S MS T P )
A T E X T ( ' C U S T OME R MA S T E R R E COR D ' )
A CU S T A L I A S ( C U S T OME R _N UMB E R )
A N AME A L I A S ( C U S T OME R _N AME )
A AD D R A L I A S ( AD D R E S S )
A CI TY
A S TAT E
A Z I P
A S R H COD A L I A S ( S E A R C H _COD E )
A CU S T Y P A L I A S ( C U S T OME R _ T Y P E )
A AR B A L A L I A S ( ACC T _R E C _B A L A NC E )
A OR D B A L
A L S T AM T
A L S T DA T
A CR D L M T
A S L S YR
A S L S L YR
A K CU S T
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 35. Example of Data Description Specifications with ALIAS

.1/ This is the name associated with the ALIAS keyword, which will be included
in the program. Available through the DDS ALIAS option, an alias is an
alternative name that allows a data name of up to 30 characters to be
included in a COBOL/400 program.

Chapter 7. File and Data Management 111


ð1 CUS-MASTER.
COPY DD-CUSREC OF CUSLIB-CUSTMAST.
\I-O FORMAT: CUSREC FROM FILE CUSTMAST OF LIBRARY CUSLIB CUSREC
\ CUSTOMER MASTER RECORD CUSREC
\THE KEY DEFINITIONS FOR THE RECORD FORMAT CUSREC CUSREC
\NUMBER NAME RETRIEVAL TYPE ALTSEQ CUSREC
\ððð1 CUSTOMER-NUMBER ASCENDING AN NO CUSREC
CUSREC
ð5 CUSREC. CUSREC
ð6 CUSTOMER-NUMBER PIC X(5). CUSREC
\ CUSTOMER NUMBER CUSREC
ð6 CUSTOMER-NAME PIC X(2ð). CUSREC
\ CUSTOMER NAME CUSREC
ð6 ADDRESS PIC X(2ð). CUSREC
\ CUSTOMER ADDRESS CUSREC
ð6 CITY PIC X(2ð). CUSREC
\ CUSTOMER CITY CUSREC
ð6 STATE PIC X(2). CUSREC
\ STATE ABBREVIATION CUSREC
ð6 ZIP PIC S9(5) COMP-3. CUSREC
\ ZIP CODE CUSREC
ð6 SEARCH-CODE PIC X(6). CUSREC
\ CUSTOMER NAME SEARCH CODE CUSREC
ð6 CUSTOMER-TYPE PIC 9(1) CUSREC
\ CUSTOMER TYPE CUSREC
ð6 ACCT-REC-BALANCE PIC S9(6)V9(2) COMP-3. CUSREC
\ ACCT/REC BALANCE CUSREC

Figure 36. Example of the Results of the Format 2 COPY Statement (DD) with the ALIAS
Keyword

IBM Extension

Format 2 COPY Statement (DD, DDR, DDS, or DDSR Option)


For general information about both formats of the COPY statement, see the
COBOL/400 Reference.

╔═══════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───COPY──┬──DD-format-name───┬──┬────────┬──┬───────────────┬───────────────5 ║
║ ├──DD-ALL-FORMATS───┤ ├─ -I───┤ ├─ -INDICATOR──┤ ║
║ ├──DDR-format-name──┤ ├─ -O───┤ ├─ -INDICATORS─┤ ║
║ ├──DDR-ALL-FORMATS──┤ └─ -I-O─┘ └─ -INDIC──────┘ ║
║ ├──DDS-format-name──┤ ║
║ ├──DDS-ALL-FORMATS──┤ ║
║ ├──DDSR-format-name─┤ ║
║ └──DDSR-ALL-FORMATS─┘ ║
║ ║
║ ║
║ 5────┬─OF─┬──┬───────────────────┬──file-name──┬────────────┬─────────────────5 ║
║ └─IN─┘ └──library-name- ──┘ └──SUPPRESS──┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────────────────────────┬────5% ║
║ │ ┌──────────────────────────────────────────────────┐ │ ║
║ │ 6 │ │ ║
║ └──REPLACING──┬─ ==pseudo-text-1== ─┬─BY─┬─ ==pseudo-text-2== ─┬─┴──┘ ║
║ ├────identifier-1─────┤ ├────identifier-2─────┤ ║
║ ├────literal-1────────┤ ├────literal-2────────┤ ║
║ └────word-1───────────┘ └────word-2───────────┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════╝

Figure 37. COPY Statement – Format 2 – DDS Translate

112 COBOL/400 User’s Guide


You can use the Format 2 COPY statement (DD, DDR, DDS, or DDSR option) to
create COBOL Data Division statements to describe a file that exists on the
system. These descriptions are based on the version of the file in existence at
compilation time. They do not make use of any DDS source statements for the file.
Refer to the “COPY Statement” section of the COBOL/400 Reference for more
information about the COPY statement.
Note: The Format 2 COPY statement (DD, DDR, DDS, or DDSR option) will be
denoted by the term Format 2 COPY statement throughout this manual.

The Format 2 COPY statement can be used only in the Data Division. You should
ensure that a group level item that has a level-number less than 05 precedes the
statement.

The DD option is used to reference ALIAS (alternative) names. The specification of


an ALIAS name in DDS allows a data name of up to 30 characters to be included
in the COBOL program.

When the DD option is used, any ALIAS names present replace the corresponding
DDS field names. All underscores in the ALIAS names are translated into hyphens
before any replacing occurs.

The DDR option does everything that the DD option does. It also copies the
internal DDS format field names, replacing the invalid COBOL characters @, #, $,
and _ with the valid COBOL characters A, N, D, and - accordingly. This option also
removes any underscores from the ends of the field names.

The DDS option copies in the internal DDS format field names. For examples of
keys and key names that can be generated when you use the DDS option of the
Format 2 COPY statement, see pages 121 through 127.

The DDSR option does everything that the DDS option does. It also copies the
internal DDS format field names, replacing the invalid COBOL characters @, #, $,
and _ with the valid COBOL characters A, N, D, and - accordingly. This option also
removes any underscores from the ends of the field names.

The following shows the effect of the DDR or DDSR option on invalid COBOL field
names:

Original Field Name Modified Field Name


FLD_A FLD-A
NUMBER#1 NUMBERN1
POINT@7 POINTA7
BALANCE$ BALANCED

When the RECORD KEY clause specifies EXTERNALLY-DESCRIBED-KEY, a


format can be copied only once under an FD. For example, if all of the formats of
a file are copied under an FD, no other Format 2 COPY statement can be specified
for the same file under that FD.

The format-name is the name of the DDS record format definition that is to be
translated into COBOL data description entries. The format-name must follow the
rules for formation of any COBOL/400 name.

Chapter 7. File and Data Management 113


If neither -I nor -O is specified, -I-O is assumed.

If format-name is specified without the Indicator attribute, and both -I and -O


formats are to be generated, each record format is generated as a redefinition of an
05 elementary item defined as:
Ÿ The size of the largest record format that will be generated.

If ALL-FORMATS is specified (without the Indicator attribute) each record format is


generated as a redefinition of an 05 elementary item defined as either:
Ÿ The size of the largest record format in the file, if the COPY statement appears
in the File Section
Ÿ The size of the largest record format that will be generated, if the COPY state-
ment appears outside of the File Section.
When the Indicator attribute is specified, no redefinition takes place. Instead, each
of the formats generates a separate data structure.

More information can be found about the Indicator attribute in the section, “Indicator
Attribute of the Format 2 COPY Statement” on page 118.

Library-name is optional. If it is not specified, the current job library list is used as
the default value.

File-name is the name of an AS/400 system file. The generated DDS entries repre-
sent the record format defined in the file. The file must be created before the
program is compiled.

If the file is a database file, a single I/O format is generated.

For all other file types, the description generated varies as follows:
Ÿ If -I is specified, the generated data description entries contain either:
– The input and input/output fields for a nonsubfile format
– The input, output, and input/output fields for a subfile format.
Ÿ If -O is specified, the generated data description entries contain either:
– The output and input/output fields for a nonsubfile format
– The input, output, and input/output fields for a subfile format.
Note: Subfile records with only output or input/output fields, and no field indicators
specified, generate I/O formats.

If a separate storage area is needed in WORKING-STORAGE for each format, an


individual COPY statement must be specified for each format.

114 COBOL/400 User’s Guide


For example, if you assume that the file CUSTMASTER contains two formats
CUSADR and CUSTDETL, the following COPY statements could be specified:

SELECT FILE-X
ASSIGN TO DATABASE-CUSTMASTER.
..
.
FD FILE-X
LABEL RECORDS ARE STANDARD.
01 FILE-X-RECS.
COPY DDS-ALL-FORMATS OF
CUSTMASTER-QGPL. (See Note 1.)
..
.
WORKING-STORAGE SECTION.
01 ADR-REC.
COPY DDS-CUSTADR OF
CUSTMASTER. (See Note 2.)
01 DETAIL-REC.
COPY DDS-CUSTDETL OF
CUSTMASTER. (See Note 2.)

Notes:
1. This COPY statement generates only one storage area for all formats.
2. These COPY statements generate separate storage areas.

Indicators
Indicators are Boolean data items that can have the values B"0" or B"1".

When you define a record format for a file using DDS, you can condition the
options using indicators; indicators can also be used to reflect particular responses.
These indicators are known as OPTION and RESPONSE, respectively. Option
indicators provide options such as spacing, underlining, and allowing or requesting
data transfer from a program to a printer or display device. Response indicators
provide response information to a program from a device, such as function keys
pressed by a work station user, and whether data has been entered.

Indicators can be used with TRANSACTION files and FORMATFILE files, but never
with database files.

Data Structures Generated


Different DDS keywords influence the creation of various types of data structures.

Format (Record) Level Structures


At the beginning of each format, a table of comments is generated in the source
program listing. These comments provide details of the files used during compila-
tion of the program. If there are record keys for the file, comments are also gener-
ated to show how the keys are defined in DDS. The record key entries that may
appear in the table and the table heading are listed below.

Chapter 7. File and Data Management 115


Heading Possible Entry
NUMBER key field number
NAME key field name
RETRIEVAL ASCENDING, DESCENDING
TYPE ZONE, DIGIT, SIGNED, ABSVAL,
AN (alphanumeric), N (numeric)
J (DBCS item), DDS - L (date),
DDS - T (time), DDS - Z (timestamp),
DDS - G (fixed-length graphic),
VARLEN (variable-length character or bracketed DBCS item),
G VARLEN (variable-length DBCS-graphic)
ALTSEQ NO, YES

If redefinition is required to allow for the generation of multiple formats, a group


level name is generated as follows:

05 file-name-RECORD
PIC X(size of largest record).

For each format, a group level name is assigned as follows:


Ÿ INPUT
05 format-name-I
Ÿ OUTPUT
05 format-name-O
Ÿ I/O Format
05 format-name

Data Field Structures


Field names, PICTURE definitions, and numeric usage clauses are derived directly
from the internal DDS format field names (or ALIAS names in the case of the DD or
DDR option) and data type representations. Field names and PICTURE definitions
are constructed as follows:

06 field-name PIC
Note: See Figure 38 on page 117 for the appropriate COBOL PICTURE defi-
nition.

116 COBOL/400 User’s Guide


Table 3. Data Field Structures
DDS COBOL DATA DIVISION
n=total field length (DDS pos. 30-34)
m=number of decimals (DDS pos. 36 & 37)
Data Type Formats If DDS pos. 36 & 37 are blank If DDS pos. 36 & 37 are not
(pos. 35) blank
PHYSICAL, LOGICAL, PRINTER, AND COMMUNICATIONS FILES
␣(Blank) Default PIC X(n) ò PIC S9(n-m)V9(m)
P Packed decimal PIC S9(n) COMP-3 PIC S9(n-m)V9(m) COMP-3
S Zoned decimal/signed numeric PIC S9(n) PIC S9(n-m)V9(m)
B Binary PIC S9(n) COMP-4 PIC S9(n-m)V9(m) COMP-4
F Floating point ñ
single precision PIC 9(5) COMP-4 PIC 9(5) COMP-4
double precision PIC 9(10) COMP-4 PIC 9(10) COMP-4
A Character PIC X(n) ò —
H Hexadecimal data PIC X(n) —
L Date ó PIC X(n) —
T Time ó PIC X(n) —
Z Timestamp ó PIC X(n) —
J DBCS-Only data PIC X(n) —
E DBCS-Either data PIC X(n) —
O DBCS-Open data PIC X(n) —
G DBCS-Graphic data PIC X(2n) ò —

DISPLAY FILES
␣(Blank) Default PIC X(n) PIC S9(n-m)V9(m)
X Alphabetic Only PIC X(n) —
N Numeric Shift PIC X(n) PIC S9(n-m)V9(m)
Y Numeric Only — PIC S9(n-m)V9(m)
I Inhibit Keyboard entry PIC X(n) PIC S9(n-m)V9(m)
W Katakana PIC X(n) —
A Alphanumeric Shift PIC X(n) —
D Digits only PIC X(n) PIC S9(n)
F Floating point ñ
single precision PIC 9(5) COMP-4 PIC 9(5) COMP-4
double precision PIC 9(10) COMP-4 PIC 9(10) COMP-4
M Numeric-only character PIC X(n) —
S Signed-numeric shift — PIC S9(n-m)V9(m)
E DBCS-either PIC X(n) —
J DBCS-only PIC X(n) —
O DBCS-open PIC X(n) —
G DBCS-graphic PIC X(2n) —

ñ COBOL treats floating point fields as FILLER. See 'Floating Point Fields'.
ò In DDS, if the field has an attribute of VARLEN, the result is two additional bytes at the beginning of the field.
ó FILLER items by default. See 'Date, Time, and Timestamp Fields'.

Figure 38. Data Field Structures

Indicator Structures
If indicators are requested, and exist in the format, an additional group name (06
level) is generated at the beginning of the structure, followed by entries (07 level)
for the relevant individual indicators.

06 format-name(-I or -O)-INDIC.
07 INxx PIC 1 INDIC xx.

where xx is the indicator number.

Chapter 7. File and Data Management 117


For example:

06 SAMPLE1-I-INDIC.
07 IN01 PIC 1 INDIC 01.
07 IN04 PIC 1 INDIC 04.
07 IN05 PIC 1 INDIC 05.
07 IN07 PIC 1 INDIC 07.
06 FLD1 PIC ... .
06 FLD2 PIC ... .

Indicator Attribute of the Format 2 COPY Statement


The Indicator attribute specifies if data description entries are generated for indica-
tors.

If the Indicator attribute is specified, data description entries are generated for indi-
cators, but not for data fields. A 05 group level entry is generated as follows:
Ÿ If the COPY is for a single structure (for example, COPY
DDS-format-name-INDIC)
05 format-name-I. (or -O as appropriate)
Ÿ If the COPY is for multiple structures
(for example, COPY DDS-ALL-FORMATS-INDIC)
05 file-name-RECORD.
The data description entries that are generated are determined by which one of the
usage attributes (I, O, or I-O) is specified or assumed in the COPY statement.
Ÿ If ...I-INDICATOR... is specified, data description entries for input (response)
indicators are generated for indicators used in the input record area.
Ÿ If ...O-INDICATOR... is specified, data description entries for output (option)
indicators are generated for indicators used in the output record area.
Ÿ If ...I-O-INDICATOR... is specified or assumed, separate data description
entries for both input and output (response and option) indicators are generated
for indicators used in the input and output record areas.

If the Indicator attribute is not specified, generation of data description entries for
indicators depends on if the file had the keyword INDARA specified in the DDS at
the time it was created.
Ÿ If INDARA was not specified, data description entries are generated for both
data fields and indicators.
Ÿ If INDARA was specified, data description entries are generated for data fields
only, not for indicators.

Generation of I/O Formats


When all field descriptions are identical, and you have requested INPUT or
OUTPUT fields implicitly or explicitly, only one set of field descriptions is generated.
This type of description is annotated with a comment line reading, “I-O FORMAT:
format-name”. Neither -I nor -O is appended to the record format name.
Note: This always happens for database files because all field descriptions within
a database file are identical.

118 COBOL/400 User’s Guide


For example:

ð1 RCUSREC.
COPY DDS-CUSREC-I OF CUSFILE.
\ I-O FORMAT: CUSREC FROM FILE CUSFILE OF LIBRARY CUSLIB CUSREC
\ THE KEY DEFINITIONS FOR RECORD FORMAT CUSREC
\ NUMBER NAME RETRIEVAL TYPE ALTSEQ
\ ððð1 ARBAL ASCENDING SIGNED NO
\ ððð2 AREACD DESCENDING ABSVAL NO
ð5 CUSREC.
ð6 ARBAL PIC S9(7)V9(2) COMP-3 CUSREC
ð6 AREACD PIC S9(3) COMP-3. CUSREC
ð6 BOSTAZ PIC X(1). CUSREC
ð6 CNTCT PIC X(15). CUSREC
ð6 CRCHKZ PIC S9(2). CUSREC
ð6 CSTAT PIC X(1). CUSREC
ð6 CUSTNZ PIC S9(6). CUSREC
ð6 DLORD PIC S9(6). CUSREC
ð6 DSCPCZ PIC S9(2)V9(3) COMP-3. CUSREC
ð6 INDUS PIC S9(2). CUSREC
ð6 NAME1 PIC X(25). CUSREC
ð6 NAME2 PIC X(25). CUSREC
ð6 NAME3 PIC X(25). CUSREC
ð6 NAME4 PIC X(25). CUSREC
ð6 PHONE PIC S9(7) COMP-3. CUSREC
ð6 PRICIZ PIC S9(2). CUSREC
ð6 SHPINZ PIC X(25). CUSREC
ð6 SLSMAZ PIC X(3). CUSREC
ð6 TAXCDZ PIC S9(2). CUSREC
ð6 TERMSZ PIC S9(2). CUSREC

Figure 39. Example of Copy DDS Showing I/O Formats

Redefinition of Formats
Pay particular attention to the REDEFINES clause that may be generated for the
ALL-FORMATS or -I-O phrases. Because all formats are redefined on the same
area (generally a buffer area), several field names can describe the same area of
storage, and unpredictable results can occur if the entire format area is not reinitial-
ized prior to each output operation.

Data items that are subordinate to the data item specified in a MOVE CORRE-
SPONDING statement do not correspond and are not moved when they contain a
REDEFINES clause or are subordinate to a redefining item.

To avoid reinitialization, multiple Format 2 COPY statements using -I and -O suf-


fixes can be used to create separate areas of storage in the Working-Storage
section for each format or format type (input or output). READ INTO and WRITE
FROM statements can be used with these record formats.

Chapter 7. File and Data Management 119


For example:

FD ORDER-ENTRY-SCREEN ...
ð1 ORDER-ENTRY-RECORD ...
..
.
WORKING-STORAGE SECTION.
ð1 ORDSFL-I-FORMAT.
COPY DDS-ORDSFL-I OF DOESCR.
ð1 ORDSFL-O-FORMAT.
COPY DDS-ORDSFL-O OF DOESCR.
..
.
PROCEDURE DIVISION.
..
.
READ SUBFILE ORDER-ENTRY-SCREEN NEXT MODIFIED RECORD
INTO ORDSFL-I-FORMAT FORMAT IS "ORDSFL"
AT END SET NO-MODIFIED-SUBFILE-RCD TO TRUE.
..
.
MOVE CORR ORDSFL-I TO ORDSFL-O.
REWRITE SUBFILE ORDER-ENTRY-RECORD FROM ORDSFL-O-FORMAT
FORMAT IS "ORDSFL" ...
..
.

120 COBOL/400 User’s Guide


Key Generation Examples
AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* P H Y S I CA L F I L E PF1 F OR KEY G E N E R A T I ON E X AMP L E S


A*
A R P F R E CO R D
A*
A MT H 2
A DAY 2
A Y E AR 4
A I T EM 8
A
A*
A K MT H
A K DAY
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 40. Data Description Specifications for a Physical File

The physical file described by Figure 40 forms a basis for the examples that follow.
Each example refers to a logical file (derived from the physical file) that specifies
EXTERNALLY-DESCRIBED-KEY in its SELECT clause.

Chapter 7. File and Data Management 121


Example Using CONCAT Keyword
AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* L OG I C A L F I L E L F1 F OR CON C A T K E Y WO R D E X AMP L E S
A*
A R R E CO R D 1 PF I L E (PF 1)
A*
A DA T E CON C A T ( M T H D A Y Y E AR )
A*
A K MT H
A K DAY
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 41. Data Description Specifications Using the CONCAT Keyword

For the logical file described by Figure 41, COPY DDS generates keys and key
names derived from the physical file:

122 COBOL/400 User’s Guide


FD LF1 LABEL RECORDS ARE STANDARD.
ð1 LOG-RECORD.
COPY DDS-ALL-FORMATS OF LF1.
ð5 LF1-RECORD PIC X(8).
\ I-O FORMAT:RECORD1 FROM FILE LF1 OF LIBRARY COPYDDS
\
\THE KEY DEFINITIONS FOR RECORD FORMAT RECORD1
\ NUMBER NAME RETRIEVAL TYPE ALTSEQ
\ ððð1 MTH-DDS ASCENDING AN NO
\ KEY NAME ORIGINATES FROM PHYSICAL FILE
\ ððð2 DAY-DDS-DDS ASCENDING AN NO
\ KEY NAME ORIGINATES FROM PHYSICAL FILE
ð5 RECORD1 REDEFINES LF1-RECORD.
ð6 DATE-DDS PIC X(8).
ð6 FILLER REDEFINES DATE-DDS.
ð7 MTH-DDS PIC X(2).
ð7 DAY-DDS-DDS PIC X(2).
ð7 FILLER PIC X(4).

Figure 42. Example Using the CONCAT Keyword

The COPY statement adds the suffix -DDS to the field names MTH and DATE
because MTH is a key that originates from the physical file, and DATE is a COBOL
reserved word. The COPY statement adds the suffix -DDS twice to the field name
DAY because DAY is both a key that originates from the physical file and a COBOL
reserved word.

Note that if you move your COPY statement from the File Section to the Working-
Storage Section or to the Linkage Section, the fields subordinate to DATE-DDS are
no longer available:

WORKING-STORAGE SECTION.
ð1 WRK-RECORD.
COPY DDS-ALL-FORMATS OF LF1.
ð5 LF1-RECORD PIC X(8).
\ I-O FORMAT:RECORD1 FROM FILE LF1 OF LIBRARY COPYDDS
\
ð5 RECORD1 REDEFINES LF1-RECORD.
ð6 DATE-DDS PIC X(8).

Figure 43. Example Using the CONCAT Keyword-- Working-Storage Section

Chapter 7. File and Data Management 123


Example Using RENAME Keyword
AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* L OG I C A L F I L E L F2 F OR R E N AM E K E Y WO R D E X AMP L E S
A*
A R R E CO R D 2 PF I L E (PF 1)
A*
A MON T H R E N AM E ( M T H )
A*
A K MT H
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 44. Data Description Specifications Using the RENAME Keyword

For the logical file described by Figure 44, COPY DDS generates a key and key
name derived from the physical file:

124 COBOL/400 User’s Guide


FD LF2 LABEL RECORDS ARE STANDARD.
ð1 LOG-RECORD.
COPY DDS-ALL-FORMATS OF LF2.
ð5 LF2-RECORD PIC X(2).
\ I-O FORMAT:RECORD2 FROM FILE LF2 OF LIBRARY COPYDDS
\
\THE KEY DEFINITIONS FOR RECORD FORMAT RECORD2
\ NUMBER NAME RETRIEVAL TYPE ALTSEQ
\ ððð1 MTH-DDS ASCENDING AN NO
\ KEY NAME ORIGINATES FROM PHYSICAL FILE
ð5 RECORD2 REDEFINES LF2-RECORD.
ð6 MONTH PIC X(2).
ð6 MTH-DDS REDEFINES MONTH PIC X(2).

Figure 45. Using the RENAME Keyword

The COPY statement adds the suffix -DDS to the field name MTH because MTH is
a key that originates from the physical file.

Chapter 7. File and Data Management 125


Example Using SST Keyword
AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* L OG I C A L F I L E L F3 F OR SS T K E Y WO R D E X AMP L E S
A*
A R R E CO R D 3 PF I L E (PF 1)
A*
A YY I S S T ( Y E AR 2 2 )
A*
A K YY
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 46. Data Description Specifications Using the SST Keyword

126 COBOL/400 User’s Guide


For the logical file described by Figure 46 on page 126, COPY DDS generates the
following specifications:

FD LF3 LABEL RECORDS ARE STANDARD.


ð1 LOG-RECORD.
COPY DDS-ALL-FORMATS OF LF3.
ð5 LF3-RECORD PIC X(2).
\ I-O FORMAT:RECORD3 FROM FILE LF3 OF LIBRARY COPYDDS
\
\THE KEY DEFINITIONS FOR RECORD FORMAT RECORD3
\ NUMBER NAME RETRIEVAL TYPE ALTSEQ
\ ððð1 YY ASCENDING AN NO
ð5 RECORD3 REDEFINES LF3-RECORD.
ð6 YY PIC X(2).

Figure 47. Using the SST Keyword

The COPY statement does not add a suffix to the field name YY because YY is
neither a key that originates from the physical file nor a COBOL reserved word.

Additional Notes on Field and Format Names


If the generated field name is a COBOL reserved word, the suffix -DDS is added to
the field name.

The REPLACING phrase cannot be used to change the name of a key field when
EXTERNALLY-DESCRIBED-KEY is used.

Floating-Point Fields
COBOL treats floating-point fields as FILLER. The fields can contain floating-point
values set outside of COBOL. A COMP-4 definition is generated to maintain proper
alignment in the record, but the data is not in binary format. No attempt must be
made to use floating-point data for processing in the COBOL program.

Floating-point key fields are not allowed. In cases where some formats exist with a
floating-point key field and other formats do not, use one or more Format 2 COPY
statements with specific format names, rather than the ALL-FORMATS option.
Note: If you have not specified your own program collating sequence, you can
create a record containing floating-point fields in your COBOL program by
moving LOW-VALUES to the entire record before moving in the values of
the non-floating-point fields. This will give the floating-point fields in the
record a value of zero. Note that the above method is only recommended if
valid floating-point fields with a value of zero are desirable for your partic-
ular application.

REPLACING Phrase in Format 2 COPY Statement


The REPLACING phrase can be used to replace any of the generated COBOL
source, including the level numbers and the format-name. Note the following
exception:
Ÿ When RECORD KEY IS EXTERNALLY-DESCRIBED-KEY is specified, the
REPLACING phrase cannot change the name of a field that is a key.

Chapter 7. File and Data Management 127


For example:

5763CB1 V3RðM5 AS/4ðð COBOL Source


STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð15ðð\ ð3/25/94
ðð16ðð\ COPY DDS W I T H O U T REPLACING OPTION ð3/25/94
ðð17ðð\ ð3/25/94
14 ðð18ðð COPY DDS-CUSMST OF CUSMSTP. ð3/25/94
+ððððð1\ I-O FORMAT:CUSMST FROM FILE CUSMSTP OF LIBRARY COBNATEX CUSMST
+ððððð2\ CUSTOMER MASTER RECORD CUSMST
15 +ððððð3 ð5 CUSMST. CUSMST
16 +ððððð4 ð6 CUST PIC X(5). CUSMST
+ððððð5\ CUSTOMER NUMBER CUSMST
17 +ððððð6 ð6 NAME PIC X(25). CUSMST
+ððððð7\ CUSTOMER NAME CUSMST
18 +ððððð8 ð6 ADDR PIC X(2ð). CUSMST
+ððððð9\ CUSTOMER ADDRESS CUSMST
19 +ðððð1ð ð6 CITY PIC X(2ð). CUSMST
+ðððð11\ CUSTOMER CITY CUSMST
2ð +ðððð12 ð6 STATE PIC X(2). CUSMST
+ðððð13\ STATE CUSMST
21 +ðððð14 ð6 ZIP PIC S9(5) COMP-3. CUSMST
+ðððð15\ ZIP CODE CUSMST

Figure 48. COPY DDS without the REPLACING Option

5763CB1 V3RðM5 AS/4ðð COBOL Source


STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð19ðð\ ð3/25/94
ðð2ððð\ COPY DDS W I T H REPLACING OPTION ð3/25/94
ðð21ðð\ ð3/25/94
31 ðð22ðð COPY DDS-CUSMST OF CUSMSTP ð3/25/94
32 ðð23ðð REPLACING NAME BY ADDR-LINE-1 ð3/25/94
33 ðð24ðð ADDR BY ADDR-LINE-2 ð3/25/94
34 ðð25ðð CITY BY ADDR-LINE-3. ð3/25/94
+ððððð1\ I-O FORMAT:CUSMST FROM FILE CUSMSTP OF LIBRARY COBNATEX CUSMST
+ððððð2\ CUSTOMER MASTER RECORD CUSMST
35 +ððððð3 ð5 CUSMST. CUSMST
36 +ððððð4 ð6 CUST PIC X(5). CUSMST
+ððððð5\ CUSTOMER NUMBER CUSMST
37 +ððððð6 ð6 ADDR-LINE-1 PIC X(25). CUSMST
+ððððð7\ CUSTOMER NAME CUSMST
38 +ððððð8 ð6 ADDR-LINE-2 PIC X(2ð). CUSMST
+ððððð9\ CUSTOMER ADDRESS CUSMST
39 +ðððð1ð ð6 ADDR-LINE-3 PIC X(2ð). CUSMST
+ðððð11\ CUSTOMER CITY CUSMST
4ð +ðððð12 ð6 STATE PIC X(2). CUSMST
+ðððð13\ STATE CUSMST
41 +ðððð14 ð6 ZIP PIC S9(5) COMP-3. CUSMST
+ðððð15\ ZIP CODE CUSMST

Figure 49. COPY DDS with the REPLACING Option

End of IBM Extension

Access Path
The description of an externally described file contains the access path that
describes how records are to be retrieved from the file. Records can be retrieved
based on an arrival sequence (nonkeyed) access path or on a keyed sequence
access path.

128 COBOL/400 User’s Guide


The arrival sequence access path is based on the order in which the records are
stored in the file. Records are added only to the end of the file.

For the keyed sequence access path, the sequence in which records are retrieved
from the file is based on the contents of the key fields defined in the DDS for the
file. For example, in the DDS shown in Figure 33 on page 109, CUST is defined
as the key field. The keyed sequence access path is updated whenever records
are added, deleted, or when the contents of a key field change.

See the Database Guide for a complete description of the access paths for an
externally described database file.

Record Keys and Common Keys


For a keyed sequence access path, one or more fields can be defined in the DDS
to be used as the key fields for a record format. All record types in a file do not
have to have the same key fields. For example, an order header record can have
the ORDER field defined as the key field, and the order detail records can have the
ORDER and LINE fields defined as the key fields.

The key for a file is determined by the valid keys for the record types in that file.
The file’s key is determined in the following manner:
Ÿ If all record types in a file have the same number of key fields defined in DDS
that are identical in attributes, the key for the file consists of all fields in the key
for the record types. (The corresponding fields do not have to have the same
name.) For example, if the file has three record types and the key for each
record type consists of fields A, B, and C, the file’s key consists of fields A, B,
and C. That is, the file’s key is the same as the records’ key.
Ÿ If all record types in the file do not have the same key fields, the key for the file
consists of the key fields common to all record types. For example, a file has
three record types and the key fields are defined as follows:
– REC1 contains key field A.
– REC2 contains key fields A and B.
– REC3 contains key fields A, B, and C.
Then the file’s key is field A, the key field common to all record types.
Ÿ If no key field is common to all record types, any keyed reference to the file will
always return the first record in the file.

In COBOL, you must specify a RECORD KEY for an indexed file to identify the
record you want to process. COBOL compares the key value with the key of the
file or record, and processes the specified operation on the record whose key
matches the RECORD KEY value.

When RECORD KEY IS EXTERNALLY-DESCRIBED-KEY is specified:


Ÿ If the FORMAT phrase is specified, the compiler builds the search argument
from the key fields in the record area for the specified format
Ÿ If the FORMAT phrase is not specified, the compiler builds the search argu-
ment from the key fields in the record area for the first record format defined in
the program for that file.
Note: For a file containing multiple key fields to be processed in COBOL, the key
fields must be contiguous in the record format used by the COBOL

Chapter 7. File and Data Management 129


program, except when RECORD KEY IS EXTERNALLY-DESCRIBED-KEY
is specified.

Overriding or Adding COBOL Functions to the External


Description
In addition to placing the external file description in the program through the use of
the Format 2 COPY statement, you can also use standard record definition and
redefinition to describe external files or to provide a group definition for a series of
fields. It is the programmer’s responsibility to ensure that program-described defi-
nitions are compatible with the external definitions of the file.

Level Checking
When a COBOL/400 program uses an externally described file, the operating
system provides a level check function (LVLCHK). This function ensures that the
format has not changed since compilation time.

The compiler always provides the information required by level checking when an
externally described file is used (that is, when a record description was defined for
the file by using the Format 2 COPY statement). Only those formats that were
copied by the Format 2 COPY statement under the FD for a file are level checked.
The level check function will be initiated at run time based on the selection made
on the create, change, or override file commands. The default on the create file
command is to request level checking. If level checking was requested, level
checking occurs on a record format basis when the file is opened. If a level check
error occurs, COBOL sets a file status of 39 at OPEN time.

When no level checking was requested, and the file is re-created using an existing
format, existing COBOL programs that use that format may not work without recom-
pilation, depending on the changes to the format. For instance,
Ÿ A change of keys will certainly cause a failure of the program on any I/O state-
ment
Ÿ A change in the record length will cause any REWRITE to fail
Ÿ A change in the record layout can cause various errors in the processing of
such a record.

You should use extreme caution when using COBOL programs without level
checking or recompiling the programs.
Note: The compiler does not provide level checking for program-described files.

For more information on level checking, see the Data Management Guide.

Declaring Data Items Using CVTOPT Data Types


The COBOL/400 compiler allows you to convert variable-length fields from
externally described files and SAA database data types to standard COBOL data
items. The SAA data types you can convert are date, time, timestamp, and
DBCS-graphic. COBOL/400 provides limited support for these data types.

130 COBOL/400 User’s Guide


Variable-length Fields
You can bring a variable-length field into your program if you specify *VARCHAR
on the CVTOPT parameter of the CRTCBLPGM command, or the VARCHAR
option of the PROCESS statement. When *VARCHAR is specified, your
COBOL/400 program will convert a variable-length field from an externally
described file into a COBOL/400 group item.

An example of such a group item is:


ð6 ITEM1.
49 ITEM1-LENGTH PIC S9(4) COMP-4.
49 ITEM1-DATA PIC X(n).
where n represents the maximum length of the variable-length field. Within the
program, the PIC S9(4) COMP-4 is treated like any other declaration of this type,
and the PIC X(n) is treated as standard alphanumeric.

Since the maximum value that ITEM1-LENGTH can hold is 9 999, this is the length
of the longest variable-length field you can write from a COBOL program.

When *VARCHAR is not specified, variable-length fields are ignored and declared
as FILLER fields in COBOL/400 programs. If *NOVARCHAR is specified, the item
is declared as follows:
ð6 FILLER PIC x(n+2).

For syntax information, see the CVTOPT parameter on page 23.

Your program can perform any valid character operations on the generated data
portion; however, because of the structure of the field, the length portion must be
valid binary data. This data is not valid if it is negative, or greater than the
maximum field length.

If the first two bytes of the field do not contain a valid binary number, an error will
occur if you try to WRITE or REWRITE a record containing the field (or UPDATE or
PUT the field in a database), and file status 90 is returned.

The following conditions apply when you specify variable-length fields:


Ÿ If a variable-length field is encountered when a field is extracted for an
externally described file or an externally described data structure, it is declared
in a COBOL/400 program as a fixed-length character field.
Ÿ For single-byte character fields, the length of the declared COBOL/400 field is
the length of the DDS field plus 2 bytes.
Ÿ For DBCS-graphic data fields, the length of the declared COBOL/400 field is
two times the length of the DDS field plus 2 bytes. For more information on
graphic data types, see “DBCS-Graphic Fields” on page 133. The two extra
bytes in the COBOL/400 field contain a binary number that represents the
current length of the variable-length field. Figure 50 on page 132 shows the
COBOL/400 field length of variable-length fields.

Chapter 7. File and Data Management 131


───┬────────┬────────────────┬──────
───5 │ length │ character-data │ ───5
───┴────────┴────────────────┴──────
BIN(2) CHAR(N)
&

declared length in DDS

For single-byte character fields: 2 + N = COBOL/4ðð field length

For DBCS-graphic data type fields: 2 + 2(N) = COBOL/4ðð field length

Figure 50. COBOL/400 Field Length of a Variable-Length Field

Ÿ Your COBOL/400 program can perform any valid character calculation oper-
ations on the declared fixed-length field. However, because of the structure of
the field, the first two bytes of the field must contain valid binary data (invalid
current field-length data is non-numeric, less than 0, or greater than the DDS
field length.) An error occurs for an input or output operation if the first two
bytes of the field contain invalid field-length data; file status 90 is returned.
Ÿ If you do not specify *VARCHAR, you can encounter problems performing
WRITE operations on variable-length fields, because you cannot assign a value
to FILLER. The two-byte field may have a value (for example X'4ð4ð') which
gives a length beyond the range allowed for the field. This causes an I/O error.

To see an example of a program using variable-length fields, refer to “Examples”


on page 134.

Date, Time, and Timestamp Fields


Date, time, and timestamp fields are brought into your program only if you specify
the *DATETIME option of the CRTCBLPGM CVTOPT parameter, or the DATETIME
option of the PROCESS statement. For a description and the syntax of the
CVTOPT parameter, see page 23. If *DATETIME is not specified, date, time, and
timestamp fields are ignored and are declared as FILLER fields in your COBOL/400
program.

Date, time or timestamp fields are brought into a COBOL/400 program as fixed-
length character fields. Your COBOL/400 program can perform any valid character
operations on the fixed-length fields. These operations will follow the standard
COBOL rules for alphanumeric data items.

The date, time, and timestamp data types each have their own format.

If a field containing date, time, or timestamp information is updated by your


program, and the updated information is to be passed back to your database, the
format of the field must be exactly the same as it was when the field was retrieved
from the database. If you do not use the same format, an error will occur. For
information on valid formats for each data type, see the DDS Reference.

If you try to WRITE a record before moving an appropriate value to a date, time, or
timestamp field, the WRITE operation will fail, and file status 90 will be returned.

132 COBOL/400 User’s Guide


If you declare date, time or timestamp items in your program as FILLER, do not
attempt to WRITE records containing these fields, since you will not be able to set
them to values that will be accepted by the system.

Null-capable Fields
Although your program can process null-capable fields, null values are not sup-
ported. READ, SORT, and MERGE operations can be performed on null-capable
fields, but if the fields actually contain null values, errors occur.

DBCS-Graphic Fields
The DBCS-graphic data type is a character string in which each character is
represented by 2 bytes. The DBCS-graphic data type does not contain shift-out
(SO) or shift-in (SI) characters. The difference between single-byte and
DBCS-graphic data is shown in the following figure:

┌────────┬────────┬────────┬────────┐
│ 1 byte │ 1 byte │ 1 byte │ 1 byte │ Single-byte
└────────┴────────┴────────┴────────┘ data
│ │ │ │ │
└────────┴────────┴────────┴────────┘
1 char 1 char 1 char 1 char

┌────────┬────────┬────────┬────────┐
│ 1 byte │ 1 byte │ 1 byte │ 1 byte │ DBCS-graphic
└────────┴────────┴────────┴────────┘ data
│ │ │
└─────────────────┴─────────────────┘
1 character 1 character
Figure 51. Comparing Single-byte and Graphic Data

DBCS-graphic data is brought into your COBOL/400 program only if you specify the
*GRAPHIC value on the CVTOPT parameter of the CRTCBLPGM command, or the
CVTGRAPHIC option of the PROCESS statement. If you do not specify
DBCS-graphic data, graphic data is ignored and declared as FILLER fields in your
COBOL/400 program. For a description and the syntax of the CVTOPT parameter,
see page 23.

The following conditions apply when DBCS-graphic data is specified:


Ÿ DBCS-graphic data is copied into a COBOL/400 program as a fixed-length
alphanumeric field.
Ÿ Every DBCS-graphic data character has a length of 2 bytes.
Ÿ Every fixed-length DBCS-graphic data field has a length of 2 bytes times the
number of characters in the field. For a description of the field length of
variable-length graphic data fields, see “Variable-length Fields” on page 131.
Ÿ Your COBOL/400 program can perform any valid character operations on the
fixed-length fields.

Chapter 7. File and Data Management 133


Variable-length DBCS-Graphic Fields
You can use variable-length fields in combination with DBCS-graphic data types, to
specify variable-length DBCS-graphic data. To specify variable-length
DBCS-graphic data, specify \VARCHAR and \GRAPHIC for the CVTOPT parameter of
the CRTCBLPGM command, or the VARCHAR and CVTGRAPHIC options for the
PROCESS statement.

If you specify either of the following: CVTOPT(\NOVARCHAR \NOGRAPHIC) or


CVTOPT(\NOVARCHAR \GRAPHIC) and the compiler encounters a variable-length
DBCS-graphic data item, the resulting program contains the following:
ð6 FILLER PIC X(2n+2).
\ (Variable-length field)

where n is the number of characters in the DDS field.

If you specify CVTOPT(\VARCHAR \NOGRAPHIC), and the compiler encounters a


variable-length DBCS-graphic data item, the resulting program contains the
following:
ð6 NAME
\ (Variable-length field)
49 NAME-LENGTH PIC S9(4) COMP-4.
\ (Number of 2-byte characters)
49 FILLER PIC X(2n).
\ (Graphic field)

where n is the number of characters in the DDS field.

If you specify CVTOPT(\VARCHAR \GRAPHIC), and the compiler encounters a variable-


length DBCS-graphic data item, the resulting program contains the following:
ð6 NAME
\ (Variable-length field)
49 NAME-LENGTH PIC S9(4) COMP-4.
\ (Number of 2-byte characters)
49 NAME-DATA PIC X(2n).
\ (Graphic field)

where n is the number of characters in the DDS field.

Examples
Figure 52 on page 135 shows an example of a DDS file that defines a variable-
length DBCS-graphic data item. Figure 53 on page 136 shows the COBOL/400
program using a COPY DDS statement, and the resulting listing when the program
is compiled.

134 COBOL/400 User’s Guide


A R SAMPLEFILE
A\
A VARITEM 1ðð VARLEN
A\
A TIMEITEM T TIMFMT(\HMS)
A DATEITEM L DATFMT(\YMD)
A TIMESTAMP Z
A\
A GRAPHITEM 1ððG
A VGRAPHITEM 1ððG VARLEN
Figure 52. DDS File Defining a Variable-Length Graphic Data Field

Chapter 7. File and Data Management 135


5763CB1 V3RðM5 ðð1ððð IBM SAA COBOL/4ðð TESTER/PGM1 AS4ððSYS ð4/24/94 ð8:55:54 Page 1
Program . . . . . . . . . . . . . . : PGM1
Library . . . . . . . . . . . . . : TESTER
Source file . . . . . . . . . . . . : QLBLSRC
Library . . . . . . . . . . . . . : TESTER
Source member . . . . . . . . . . . : PGM1 ð4/24/94 ð8:23:ð6
Generation severity level . . . . . : 29
Text 'description' . . . . . . . . . : Data types example
Source listing options . . . . . . . : \NONE
Generation options . . . . . . . . . : \NONE
Conversion options . . . . . . . . . : \VARCHAR \DATETIME \GRAPHIC
Message limit:
Number of messages . . . . . . . . : \NOMAX
Message limit severity . . . . . . : 29
Print file . . . . . . . . . . . . . : QSYSPRT
Library . . . . . . . . . . . . . : \LIBL
FIPS flagging . . . . . . . . . . . : \NOFIPS \NOSEG \NODEB \NOOBSOLETE
SAA flagging . . . . . . . . . . . . : \NOFLAG
Extended display options . . . . . . :
Flagging severity . . . . . . . . . : ð
Replace program . . . . . . . . . . : \YES
Target release . . . . . . . . . . . : \CURRENT
User profile . . . . . . . . . . . . : \USER
Authority . . . . . . . . . . . . . : \LIBCRTAUT
Compiler . . . . . . . . . . . . . . : IBM SAA COBOL/4ðð
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/PGM1 AS4ððSYS ð4/24/94 ð8:55:54 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð Identification division. ð1/ð2/94
2 ððð2ðð Program-id. pgm1. ð2/13/94
3 ððð3ðð Environment division. ð1/ð2/94
4 ððð4ðð Configuration section. ð1/ð2/94
5 ððð5ðð Source-computer. ibm-as4ðð. ð1/ð2/94
6 ððð6ðð Object-computer. ibm-as4ðð. ð1/ð2/94
7 ððð7ðð Input-output section. ð1/ð2/94
8 ððð8ðð File-control. ð1/ð2/94
9 ððð9ðð Select file1 ð4/23/94
1ð ðð1ððð assign to database-samplefile ð2/13/94
11 ðð11ðð organization is sequential ð4/23/94
12 ðð12ðð access is sequential ð4/23/94
13 ðð13ðð file status is fs1. ð4/23/94
14 ðð14ðð Data division. ð1/ð2/94
15 ðð15ðð File section. ð1/ð2/94
16 ðð16ðð fd file1. ð1/ð2/94
17 ðð17ðð ð1 record1. ð1/ð2/94
18 ðð18ðð copy dds-all-formats of samplefile. ð2/13/94
19 +ððððð1 ð5 SAMPLEFILE-RECORD PIC X(546). <-ALL-FMTS
+ððððð2\ I-O FORMAT:SAMPLEFILE FROM FILE SAMPLEFILE OF LIBRARY TESTER <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
2ð +ððððð4 ð5 SAMPLEFILE REDEFINES SAMPLEFILE-RECORD. <-ALL-FMTS
21 +ððððð5 ð6 VARITEM. <-ALL-FMTS
+ððððð6\ (Variable length field) <-ALL-FMTS
22 +ððððð7 49 VARITEM-LENGTH PIC S9(4) COMP-4. <-ALL-FMTS
23 +ððððð8 49 VARITEM-DATA PIC X(1ðð). <-ALL-FMTS
24 +ððððð9 ð6 TIMEITEM PIC X(8). <-ALL-FMTS
+ðððð1ð\ (Time field) <-ALL-FMTS
25 +ðððð11 ð6 DATEITEM PIC X(8). <-ALL-FMTS
+ðððð12\ (Date field) <-ALL-FMTS
26 +ðððð13 ð6 TIMESTAMP PIC X(26). <-ALL-FMTS
+ðððð14\ (Timestamp field) <-ALL-FMTS
27 +ðððð15 ð6 GRAPHITEM PIC X(2ðð). <-ALL-FMTS
+ðððð16\ (Graphic field) <-ALL-FMTS
28 +ðððð17 ð6 VGRAPHITEM. <-ALL-FMTS
+ðððð18\ (Variable length field) <-ALL-FMTS
29 +ðððð19 49 VGRAPHITEM-LENGTH PIC S9(4) COMP-4. <-ALL-FMTS
+ðððð2ð\ (Number of 2-byte characters) <-ALL-FMTS
3ð +ðððð21 49 VGRAPHITEM-DATA PIC X(2ðð). <-ALL-FMTS
+ðððð22\ (Graphic field) <-ALL-FMTS
31 ðð19ðð working-storage section. ð4/22/94
32 ðð2ððð 77 fs1 pic x(2). ð4/23/94
33 ðð21ðð Procedure division. ð1/ð9/94
ðð22ðð Mainline. ð1/ð2/94
34 ðð23ðð stop run. ð1/ð2/94
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5738CB1 V2R2Mð ðð1ððð AS/4ðð COBOL Messages TESTER/PGM1 AS4ððSYS ð4/24/94 ð8:55:54 Page 3
STMT
\ 16 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ðð16ðð
Message . . . . : Blocking/Deblocking for file 'FILE1' will be
performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 1 ð ð ð ð
Source records read . . . . . . . . : 23
Copy records read . . . . . . . . . : 22
Copy members processed . . . . . . : 1
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program PGM1 created in library TESTER.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 53. COBOL/400 Program Using Variable-Length DBCS-Graphic Data Items

136 COBOL/400 User’s Guide


Cross-system Data Considerations
Coded character set identifiers (CCSIDs) can help you to maintain the integrity of
character data across systems.

Character Data Representation Architecture (CDRA) defines CCSID values to iden-


tify the code points used to represent characters, and to convert these codes as
needed to preserve their meanings.

As a consequence of CDRA conversion, you might have substitution characters


(X’3F’) in your data. If you write these characters to a display, the results will not
be predictable.

For more information about CCSIDs and CDRA, see System Operation, SC41-3203
and the Data Management Guide.

Chapter 7. File and Data Management 137


138 COBOL/400 User’s Guide
Chapter 8. Transaction Files

IBM Extension

This chapter describes the COBOL/400 language extensions that support work
stations and program-to-program communication.

The TRANSACTION file organization allows a COBOL program to communicate


interactively with:
Ÿ One or more work station users
Ÿ One or more programs on a remote system
Ÿ One or more devices on a remote system.

The AS/400 system permits you to communicate with a program or device (such as
Asynchronous communication types) on a remote system. For a detailed dis-
cussion of these devices, see the ICF Programmer’s Guide.

Program-Described Transaction Files


COBOL TRANSACTION files are usually externally described. If these files are
program-described, only simple display formatting can be performed. All field-level
descriptions are defined in the COBOL program.

Do not send internal (packed) or binary data (COMP, COMP-3, or COMP-4) to a


display station as output data. Such data can contain display station control char-
acters that can cause unpredictable results.

See the Data Management Guide for more information about using program-
described display files.

Externally Described Transaction Files


A COBOL TRANSACTION file uses an externally described file that contains file
information and a description of the fields in the records. The records in this file
can be described to the COBOL program by the Format 2 COPY statement.

The Format 2 COPY Statement


Format 2 COPY statements are used to generate COBOL Data Division statements
within source programs to describe files that exist on the system.
Note: The term Format 2 COPY statement is used throughout this manual to
describe the COPY statement (DD, DDR, DDS, or DDSR option).

For more information about the Format 2 COPY statement, see “Format 2 COPY
Statement (DD, DDR, DDS, or DDSR Option)” on page 112.

 Copyright IBM Corp. 1994 139


Data Description Specifications
Data description specifications (DDS) are a description of the user’s database or
device files that are entered into the system in a fixed form. The description is then
used to create files.

In addition to the field descriptions (such as field names and attributes), the data
description specifications (DDS) for a display device file:
Ÿ Specify the line number and position number entries for each field and constant
to format the placement of the record on the display.
Ÿ Specify attention functions such as underlining and highlighting fields, reverse
image, or a blinking cursor.
Ÿ Specify validity checking for data entered at the display work station. Validity
checking functions include:
– Detecting fields where data is required
– Detecting mandatory fill fields
– Detecting incorrect data types
– Detecting data for a specific range
– Checking data for a valid entry
– Performing modules 10 or 11 check digit verification.
Ÿ Control display management functions such as when fields are to be erased,
overlaid, or retained when new data is displayed.
Ÿ Associate indicators 01 through 99 with function keys designated as type CA or
CF. If a function key is designated as CF, both the modified data record and the
response indicator are returned to the program. If a function key is designated
as CA, the response indicator is returned to the program, but the data record
usually contains default values for input-only fields and values written to the
format for hidden output/input fields. For more information about type CF and
CA function keys, see the DDS Reference.
Ÿ Assign an edit code (EDTCDE keyword) or edit word (EDTWRD keyword) to a
field to specify how the field’s values are to be displayed.
Ÿ Specify subfiles.

Display format data defines or describes a display. A display device record


format contains three types of fields:
Ÿ Input Fields: Input fields pass from the device to the program when the
program reads a record. Input fields can be initialized with a default value; if
the default value is not changed, the default value passes to the program.
Uninitialized input fields are displayed as blanks where the work station user
can enter data.
Ÿ Output Fields: Output fields pass from the program to the device when the
program writes a record to a display. The program or the record format in the
device file can provide output fields.
Ÿ Output/Input (both) Fields: An output/input field is an output field that can be
changed to become an input field. Output/input fields pass from the program
when the program writes a record to a display and pass to the program when
the program reads a record from the display. Output/input fields are used
when the user is to change or update the data that is written to the display from
the program.

140 COBOL/400 User’s Guide


For a detailed description of a data communications file, see the ICF Programmer’s
Guide. For more information on externally defined display files, see the Data Man-
agement Guide. For a list of the valid data description specifications (DDS)
keywords, see the DDS Reference.

Figure 54 shows an example of the DDS for a display device file:

AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*


Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key
Type of Name of S pec /(b/R/H/J/K/S /O)

Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons


Reference (R)

Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 2 2 23 2 4 25 2 6 27 28 29 30 3 1 3 2 33 3 4 35 3 6 37 38 39 40 4 1 4 2 43 4 4 45 4 6 47 48 49 50 5 1 5 2 5 3 5 4 55 5 6 57 5 8 5 9 60 6 1 6 2 6 3 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80

A * C U S T OME R MA S T E R I NQU I R Y F I LE - - C U S M I NQ
A*
A R E F ( CU SMS T P )
A R CU S PMT T E X T ( ' C U S T OME R P R OMP T ' )
A C A 0 3 ( 1 5 ' E ND O F P R OGR AM )
A 1 3 ' C U S T OME R MA S T E R I NQU I R Y '
A 3 3 ' C U S T OME R N UMB E R '
A CU S T R I 3 2 /0
A 99 E R R M S G ( ' C U S T OME R N UMB E R NO T F OU ND +
A P R E S S R E S E T , T H E N E N T E R V A L I D N UMB E +
A R ' 99 )
A 5 3 ' U S E F 3 T O E ND P R OG R AM , U S E E N T E R +
A T O R E T U R N T O P R OMP T S C R E E N '
A R CU S F L D S T E X T ( ' C U S T OME R D I S P L A Y ' )
A C A 0 3 ( 1 5 ' E ND O F P R OGR AM ' )
A OV E R L A Y
A 8 3 ' N AME '
A N AME R 8 11
A 9 3 ' AD D R E S S '
A AD D R R 9 11
A 1 /0 3 'CI TY '
A CI TY R 1 /0 11
A 11 3 ' S TAT E '
A S TAT E R 11 11
A 11 2 1 ' Z I P COD E '
A Z I P R 11 31
A 12 3 ' A / R B A L A NC E '
A AR B A L R 12 17
A
A

Figure 54. Example of the Data Description Specifications for a Display Device File

This display device file contains two record formats: CUSPMT and CUSFLDS.
.1/ The attributes for the fields in this file are defined in the CUSMSTP field refer-
ence file. For example, EDTCDE(J) is defined in CUSMSTP for the field
ARBAL.
.2/ The F3 key is associated with indicator 15, with which the user ends the
program.
.3/ The ERRMSG keyword identifies the error message that is displayed if indi-
cator 99 is set on in the program that uses this record format.

Chapter 8. Transaction Files 141


.4/ The OVERLAY keyword is used for the record format CUSFLDS so that the
CUSPMT record on the display will not be erased when the CUSFLDS record
is written to the display.
.5/ The constants such as ‘Name’, ‘Address’, and ‘City’ describe the fields that
are written out by the program.
.6/ The line and position entries identify where the fields or constants are written
on the display.

Processing an Externally Described Transaction File


When an externally described TRANSACTION file is processed, the operating
system transforms data from the program to the format specified for the file and
displays the data. When data passes to the program, the data is transformed to
the format used by the program.

The operating system provides device control information for performing


input/output operations for the device. When an input record is requested from the
device, the operating system issues the request, and then removes device control
information from the data before passing the data to the program. In addition, the
operating system can pass indicators to the program indicating which, if any, fields
in the record have changed.

When the program requests an output operation, it passes the output record to the
operating system. The operating system provides the necessary device control
information to display the record. It also adds any constant information specified
for the record format when the record is displayed.

When a record passes to a program, the fields are arranged in the order in which
they are specified in the DDS. The order in which the fields are displayed is based
on the display positions (line numbers and positions) assigned to the fields in the
DDS. Therefore, the order in which the fields are specified in the DDS and the
order in which they appear on the display need not be the same.

Using Indicators with Transaction Files


Indicators are Boolean data items that can have the values B"0" or B"1".

When you define a record format for a file using DDS, you can condition the
options using indicators; indicators can also be used to reflect particular responses.
These indicators are known as OPTION and RESPONSE, respectively.

Option indicators provide options such as spacing, underlining, and allowing or


requesting data transfer from a program to a printer or display device. Response
indicators provide response information to a program from a device, such as func-
tion keys pressed by a work station user, and whether data has been entered.

Indicators can be passed with data records in a record area, or outside the record
area in a separate indicator area.

142 COBOL/400 User’s Guide


Indicators in a Separate Indicator Area
If you specify the file level keyword INDARA in the DDS, all indicators defined in
the record format or formats for that file are passed to and from the program in a
separate indicator area, not in the record area. For information on how to specify
the INDARA keyword, see the DDS Reference.

The file control entry for a file that has INDARA specified in its DDS must have the
separate indicator area attribute, SI, as part of the assignment-name.

The advantages of using a separate indicator area are as follows:


Ÿ The number and order of indicators used in an I/O statement for any record
format in a file need not match the number and order of indicators specified in
the DDS for that record format.
Ÿ The program associates the indicator number in a data description entry with
the appropriate indicator.

Indicators in the Record Area


If the keyword INDARA is not used in the DDS of the file, indicators are created in
the record area. When indicators are defined in a record format for a file, they are
read, rewritten, and written with the data in the record area.

The number and order of indicators defined in the DDS for a record format for a file
determines the number and order in which the data description entries for the indi-
cators in the record format must be coded in the program.

The file control entry for a file that does not have the INDARA keyword specified in
the DDS associated with it must not have the separate indicator area attribute, SI,
as part of the assignment-name.

If a Format 2 COPY statement is used to copy indicators into a source program,


the indicators are defined in the order in which they are specified in the DDS for the
file.

ASSIGN Clause and the Separate Indicator Area Attribute


Format

55───ASSIGN──┬────┬─────WORKSTATION───── -file-name──┬───────┬───────────────5%
└─TO─┘ └─ -SI─┘

The rules for the ASSIGN clause are as follows:


Ÿ Device must be WORKSTATION
Ÿ If -SI is coded, file-name must refer to a file that has the file level keyword
INDARA specified in its DDS.

For more information about the ASSIGN clause, see “ASSIGN Clause” on
page 172.

Chapter 8. Transaction Files 143


Data Description Entry–Boolean Data
When you use indicators in a COBOL program, you must describe them as
Boolean data items using the data description entry for Boolean data.
Format 4 - Boolean Data

╔═══════════════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───level-number──┬───────────────┬──┬──────────────────────────┬──────────────────────5 ║
║ ├──data-name-1──┤ ├──REDEFINES──data-name-2──┤ ║
║ └──FILLER───────┘ └──LIKE───data-name-3──────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────┬──────────────────────────────────────────────────────5 ║
║ └──┬──PICTURE──┬─┬────┬──1──┘ ║
║ └──PIC──────┘ └─IS─┘ ║
║ ║
║ ║
║ 5────┬──────────────────────────────┬───────────────────────────────────────────────────5 ║
║ └──┬───────────────┬──DISPLAY──┘ ║
║ └──USAGE─┬────┬─┘ ║
║ └─IS─┘ ║
║ ║
║ ║
║ 5──┬────────────────────────────────────────────────────────────────────────────────────5 ± ║
║ └─OCCURS─┬─integer-1─TO─integer-2─┬───────┬─DEPENDING─┬────┬─data-name-4─┬───────────5 ² ║
║ │ └─TIMES─┘ └─ON─┘ │ ║
║ └─integer-2─┬───────┬───────────────────────────────────────────┘ ║
║ └─TIMES─┘ ║
║ ║
║ ║
║ ± 5──────────────────────────────────────────────┬────────────────────────────────────────5 ║
║ ² 5────┬──────────────────────────────────────┬──┘ ║
║ │ ┌─────────────┐ │ ║
║ │ 6 │ │ ║
║ └──INDEXED──┬────┬────index-name-1──┴──┘ ║
║ └─BY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────┬──────────────────────────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──integer-3─┘ ║
║ ├─INDICATORS─┤ ║
║ └─INDIC──────┘ ║
║ ║
║ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ 5────┬───────────────────────────────────┬──┬────────────────────────────┬──────────────5 ║
║ \ └──┬──SYNCHRONIZED──┬──┬─────────┬──┘ └──┬─JUSTIFIED─┬──┬───────┬──┘ \ ║
║ \ └──SYNC──────────┘ ├──LEFT───┤ └─JUST──────┘ └─RIGHT─┘ \ ║
║ \ └──RIGHT──┘ \ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────┬──.────────────────────────────────────────────5% ║
║ └──VALUE─┬────┬──Boolean-literal──┘ ║
║ └─IS─┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════════════════╝

Special Considerations
The special considerations for the clauses used with the Boolean data follow. All
other rules for clauses are the same as those for other data as described in the
“COBOL Program Structure” section of the COBOL/400 Reference.

PICTURE Clause: An elementary Boolean data name is defined by a PICTURE


containing a single 1.

USAGE Clause: USAGE must be defined implicitly or explicitly as DISPLAY.

144 COBOL/400 User’s Guide


OCCURS Clause: When the OCCURS clause and the INDICATOR clause are
both specified at an elementary level, a table of Boolean data items is defined with
each element in the table corresponding to an external indicator. The first element
in the table corresponds to the indicator number specified in the
INDICATOR clause; the second element corresponds to the indicator that sequen-
tially follows the indicator specified by the INDICATOR clause.

For example, if the following is coded, SWITCHES (1) corresponds to indicator 16,
SWITCHES (2) corresponds to indicator 17,..., and SWITCHES (10) corresponds to
indicator 25:

ð7 SWITCHES PIC 1
OCCURS 1ð TIMES
INDICATOR 16.

INDICATOR Clause: If indicator fields are in a separate indicator area, the


INDICATOR clause associates an indicator defined in DDS with a Boolean data
item. If indicator fields are in the record area, the INDICATOR clause is syntax-
checked, but is treated as a comment.

Integer-3 must have a value of 1 through 99.

The INDICATOR clause must be specified at an elementary level only.

VALUE Clause: The VALUE clause specifies the initial content of a Boolean data
item. The allowable values for Boolean literals are B"0", B"1", and ZERO.

LIKE Clause: You cannot use this clause to change the length of the data item.

INDICATORS Phrase
When the INDICATORS phrase is used in READ, REWRITE, and WRITE state-
ments (see Figure 57 on page 150), it specifies which indicators are to be read,
rewritten, and written.

The identifier specified in the INDICATORS phrase can be either of the following:
Ÿ An elementary Boolean data item
Ÿ A group item with elementary Boolean data items subordinate to it. (The
Boolean data items can be anywhere in the group, but they are the only items
you can read, write, or rewrite.)
The identifier cannot be subordinate to an item that is subject to an OCCURS
clause.

Indicators in a Separate Indicator Area


If INDARA is specified in the DDS for the file, the use of the indicators referenced
in the INDICATORS phrase is based on indicator number.
Ÿ In a READ statement, only the response indicator numbers referenced by the
INDICATORS phrase are updated. Indicators specified in the DDS for the
format but not referenced by the INDICATORS phrase are ignored. Indicators
referenced by the INDICATORS phrase but not specified in the DDS are not
modified.
Ÿ In a WRITE or REWRITE statement, only the option indicators referenced by
the INDICATORS phrase are used. Indicators specified in the DDS for the

Chapter 8. Transaction Files 145


format but not referenced by the INDICATORS phrase are assumed to be OFF.
Indicators referenced by the INDICATORS phrase but not used in the DDS for
the format are ignored.

If the INDICATORS phrase is not specified, the following occurs:


Ÿ In the READ statement, indicators are not updated.
Ÿ In a WRITE or REWRITE statement, indicators are treated as though they are
set to OFF.

Indicators in the Record Area


If INDARA is not specified in the DDS for the file, the size of the identifier in the
INDICATORS phrase of an I/O statement (see Figure 57 on page 150) should be
equal to the number of option or response indicators defined in the DDS for that
format.
Ÿ In a READ statement, the identifier size should be equal to the number of
response indicators.
Ÿ In a REWRITE or WRITE statement, the identifier size should be equal to the
number of option indicators.

The contents of the identifier are not checked, but are copied to or from the begin-
ning of the record, on a byte-by-byte basis; indicator numbers are ignored.

If the INDICATORS phrase is omitted, the data in the indicator fields in the record
are still passed in the record area. The INDICATORS phrase is only used to copy
indicators into the record area before a WRITE or REWRITE statement, or out of
the record area after a READ statement.

Indicators Example Programs


This section contains examples of COBOL/400 programs that illustrate the use of
indicators in either a record area or a separate indicator area.

All the programs do the following:


1. Determine the current date.
2. If it is the first day of the month, turn on an option indicator that causes an
output field to appear and blink.
3. Allow you to press function keys to terminate the program, or turn on response
indicators and call programs to write daily or monthly reports.

Figure 56 on page 148 shows a program that uses indicators in the record area
but does not use the INDICATORS phrase in any I/O statement. Figure 55 on
page 147 shows the associated DDS for the file.

Figure 57 on page 150 shows a program that uses indicators in the record area
and the INDICATORS phrase in the I/O statements. The associated DDS for
Figure 57 is Figure 55 on page 147.

Figure 59 on page 153 shows a program that uses indicators in a separate indi-
cator area, defined in WORKING-STORAGE by using the Format 2 COPY state-
ment. Figure 58 on page 152 shows the associated DDS for the file.

146 COBOL/400 User’s Guide


Figure 60 on page 155 shows a program that uses indicators in a separate indi-
cator area, defined in a table in WORKING-STORAGE. The associated DDS for
the file is the same as Figure 58 on page 152.

AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*


Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)

Conditioning

Location

U s ag e ( b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons


Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 2 2 23 2 4 25 2 6 27 28 29 30 3 1 3 2 33 3 4 35 3 6 37 38 39 40 4 1 4 2 43 4 4 45 4 6 47 48 49 50 5 1 5 2 5 3 5 4 55 5 6 57 5 8 5 9 60 6 1 6 2 6 3 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80

A* D I S P L AY F I LE DD S F OR I ND I CA T OR E X AMP L E S
A*
A R F OR MA T 1 CF /0 3 ( 9 9 ' E ND O F P R OGR AM ' )
A CF /0 5 ( 5 1 ' D A I L Y R E P OR T ' )
A CF /0 9 ( 5 2 ' MON T H L Y R E P OR T ' )
A*
A 10 1 0 ' D E P A R T ME N T N UMB E R : '
A D E P T NO 5 I 10 32
A 01 20 2 6 ' P R OD U C E MON T H L Y R E P OR T S '
A DSPAT R ( B L )
A*
A 24 01 ' F5 = D A I L Y R E P OR T '
A 24 26 ' F9 = MON T H L Y R E P OR T '
A 24 53 ' F3 = T E RM I NA T E '
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 55. Example of a Program Using Indicators in the Record Area without Using the INDICATORS Phrase in the
I/O Statement–Data Description Specifications

.1/ The INDARA keyword is not used; indicators are stored in the record area
with the data fields.
.2/ One record format, FORMAT1, is specified.
.3/ Three indicators are associated with three function keys. Indicator 99 will be
set on when you press F3, and so on.
.4/ One field is defined for input.
.5/ Indicator 01 is defined to cause the associated constant field to blink if the
indicator is on.
.6/ The function (F) key definitions are documented on the work station display.

Chapter 8. Transaction Files 147


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð3/ð9/94
2 ððð2ðð PROGRAM-ID. XMPLE71. ð3/22/94
ððð3ðð\ PROGRAM EXAMPLE WITH INDICATORS IN RECORD AREA. ð3/ð9/94
3 ððð4ðð AUTHOR. PROGRAMMER NAME. ð3/ð9/94
4 ððð5ðð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE. ð3/ð9/94
5 ððð6ðð DATE-WRITTEN. 12/ð8/88. ð3/ð9/94
6 ðððð7ð DATE-COMPILED. ð5/24/94 11:ð2:36 .
7 ððð8ðð ENVIRONMENT DIVISION. ð3/ð9/94
8 ððð9ðð CONFIGURATION SECTION. ð3/ð9/94
9 ðð1ððð SOURCE-COMPUTER. IBM-AS4ðð. ð3/25/94
1ð ðð11ðð OBJECT-COMPUTER. IBM-AS4ðð. ð3/25/94
11 ðð12ðð INPUT-OUTPUT SECTION. ð3/ð9/94
12 ðð13ðð FILE-CONTROL. ð3/ð9/94
13 ðð14ðð SELECT DISPFILE ð3/ð9/94
14 ðð15ðð ASSIGN TO WORKSTATION-DSPFILEX .1/ ð3/ð9/94
15 ðð16ðð ORGANIZATION IS TRANSACTION ð3/ð9/94
16 ðð17ðð ACCESS IS SEQUENTIAL. ð3/ð9/94
17 ðð18ðð DATA DIVISION. ð3/ð9/94
18 ðð19ðð FILE SECTION. ð3/ð9/94
19 ðð2ððð FD DISPFILE ð3/ð9/94
2ð ðð21ðð LABEL RECORDS ARE OMITTED ð3/ð9/94
21 ðð22ðð DATA RECORD IS DISP-REC. ð3/ð9/94
22 ðð23ðð ð1 DISP-REC. ð3/ð9/94
23 ðð24ðð COPY DDS-ALL-FORMATS OF DSPFILEX. .2/ ð3/ð9/94
24 +ððððð1 ð5 DSPFILEX-RECORD PIC X(8). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:FORMAT1 FROM FILE DSPFILEX OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
25 +ððððð4 ð5 FORMAT1-I REDEFINES DSPFILEX-RECORD. <-ALL-FMTS
26 +ððððð5 ð6 FORMAT1-I-INDIC. <-ALL-FMTS
27 +ððððð6 ð7 IN99 PIC 1 INDIC 99. .3/ <-ALL-FMTS
+ððððð7\ END OF PROGRAM <-ALL-FMTS
28 +ððððð8 ð7 IN51 PIC 1 INDIC 51. <-ALL-FMTS
+ððððð9\ DAILY REPORT <-ALL-FMTS
29 +ðððð1ð ð7 IN52 PIC 1 INDIC 52. <-ALL-FMTS
+ðððð11\ MONTHLY REPORT <-ALL-FMTS
3ð +ðððð12 ð6 DEPTNO PIC X(5). <-ALL-FMTS
+ðððð13\ OUTPUT FORMAT:FORMAT1 FROM FILE DSPFILEX OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð14\ <-ALL-FMTS
31 +ðððð15 ð5 FORMAT1-O REDEFINES DSPFILEX-RECORD. <-ALL-FMTS
32 +ðððð16 ð6 FORMAT1-O-INDIC. <-ALL-FMTS
33 +ðððð17 ð7 INð1 PIC 1 INDIC ð1. <-ALL-FMTS
ðð25ðð
34 ðð26ðð WORKING-STORAGE SECTION.
35 ðð27ðð ð1 CURRENT-DATE.
36 ðð28ðð ð5 CURR-YEAR PIC 9(2).
37 ðð29ðð ð5 CURR-MONTH PIC 9(2).
38 ðð3ððð ð5 CURR-DAY PIC 9(2).
39 ðð31ðð ð1 INDIC-AREA. .4/
4ð ðð32ðð ð5 INð1 PIC 1.
41 ðð33ðð 88 NEW-MONTH .5/ VALUE B"1".
42 ðð34ðð ð5 IN51 PIC 1.
43 ðð35ðð 88 WANT-DAILY VALUE B"1".
44 ðð36ðð ð5 IN52 PIC 1.
45 ðð37ðð 88 WANT-MONTHLY VALUE B"1".
46 ðð38ðð ð5 IN99 PIC 1.
47 ðð39ðð 88 NOT-END-OF-JOB VALUE B"ð".
48 ðð4ððð 88 END-OF-JOB VALUE B"1".
49 ðð41ðð PROCEDURE DIVISION.
ðð42ðð XAMPLE3-MAIN.
5ð ðð43ðð OPEN I-O DISPFILE.
51 ðð44ðð ACCEPT CURRENT-DATE FROM DATE.
52 ðð45ðð SET NOT-END-OF-JOB TO TRUE.
53 ðð46ðð PERFORM DISPLAY-SCREEN THRU READ-AND-PROCESS-SCREEN
ðð47ðð UNTIL END-OF-JOB.
54 ðð48ðð CLOSE DISPFILE.
55 ðð49ðð STOP RUN.
ðð5ððð DISPLAY-SCREEN.
56 ðð51ðð MOVE ZEROS TO INDIC-AREA. .6/
57 ðð52ðð IF CURR-DAY = ð1 THEN
58 ðð53ðð SET NEW-MONTH TO TRUE. .7/
59 ðð54ðð MOVE CORR INDIC-AREA TO FORMAT1-O-INDIC. .8/
6ð ðð55ðð WRITE DISP-REC FORMAT IS "FORMAT1". .9/
ðð56ðð READ-AND-PROCESS-SCREEN.
61 ðð57ðð MOVE ZEROS TO INDIC-AREA.
62 ðð58ðð READ DISPFILE FORMAT IS "FORMAT1". .1ð/

Figure 56 (Part 1 of 2). Example of a Program Using Indicators in the Record Area without Using the INDICATORS
Phrase in the I/O Statement–COBOL Source Program

148 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
63 ðð59ðð MOVE CORR FORMAT1-I-INDIC TO INDIC-AREA. .11/
64 ðð6ððð IF WANT-DAILY THEN
65 ðð61ðð CALL "DAILY" USING DEPTNO .12/
ðð62ðð ELSE
66 ðð63ðð IF WANT-MONTHLY THEN
67 ðð64ðð CALL "MONTHLY" USING DEPTNO.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
ð ð ð ð ð ð
Source records read . . . . . . . . : 64
Copy records read . . . . . . . . . : 17
Copy members processed . . . . . . : 1
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program XMPLE71 created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 56 (Part 2 of 2). Example of a Program Using Indicators in the Record Area without Using the INDICATORS
Phrase in the I/O Statement–COBOL Source Program

.1/ The separate indicator area attribute, SI, is not coded in the ASSIGN clause.
.2/ The Format 2 COPY statement defines data fields and indicators in the record
area.
.3/ Because the file does not have a separate indicator area, response and
option indicators are defined in the order in which they are used in the DDS,
and the indicator numbers are treated as documentation.
.4/ All indicators used by the program are defined with meaningful names in data
description entries in WORKING-STORAGE. Indicator numbers are omitted
here because they have no effect.
.5/ For each indicator, a meaningful level-88 condition-name is associated with a
value for that indicator.
.6/ Initialize group level to zeros.
.7/ IN01 in WORKING-STORAGE is set on if it is the first day of the month.
.8/ Indicators appropriate to the output of FORMAT1 are copied to the record
area.
.9/ FORMAT1 is written to the work station display with both data and indicator
values in the record area.
The INDICATORS phrase is not necessary because there is no separate indi-
cator area and indicator values have been set in the record area through the
previous MOVE CORRESPONDING statement.
.1ð/ FORMAT1, including both data and indicators, is read from the display.
.11/ The response indicators for FORMAT1 are copied from the record area to the
data description entries in WORKING-STORAGE.
.12/ If F5 has been pressed, a program call is processed.

Chapter 8. Transaction Files 149


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð3/ð7/94
2 ððð2ðð PROGRAM-ID. XMPLE713. ð3/22/94
ððð3ðð\ SAMPLE PROGRAM - FILE WITH INDICATORS IN RECORD AREA ð3/ð7/94
3 ððð4ðð AUTHOR. PROGRAMMER NAME. ð3/ð7/94
4 ððð5ðð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE. ð3/ð7/94
5 ððð6ðð DATE-WRITTEN. 12/1ð/88. ð3/ð7/94
6 ðððð7ð DATE-COMPILED. ð5/24/94 11:ð4:34 .
7 ððð8ðð ENVIRONMENT DIVISION. ð3/ð7/94
8 ððð9ðð CONFIGURATION SECTION. ð3/ð7/94
9 ðð1ððð SOURCE-COMPUTER. IBM-AS4ðð. ð3/ð7/94
1ð ðð11ðð OBJECT-COMPUTER. IBM-AS4ðð. ð3/ð7/94
11 ðð12ðð INPUT-OUTPUT SECTION. ð3/ð7/94
12 ðð13ðð FILE-CONTROL. ð3/ð7/94
13 ðð14ðð SELECT DISPFILE ð3/ð7/94
14 ðð15ðð ASSIGN TO WORKSTATION-DSPFILEX .1/ ð3/22/94
15 ðð16ðð ORGANIZATION IS TRANSACTION ð3/ð7/94
16 ðð17ðð ACCESS IS SEQUENTIAL. ð3/ð7/94
17 ðð18ðð DATA DIVISION. ð3/ð7/94
18 ðð19ðð FILE SECTION. ð3/ð7/94
19 ðð2ððð FD DISPFILE ð3/ð7/94
2ð ðð21ðð LABEL RECORDS ARE OMITTED ð3/ð7/94
21 ðð22ðð DATA RECORD IS DISP-REC. ð3/ð7/94
22 ðð23ðð ð1 DISP-REC. ð3/ð7/94
23 ðð24ðð COPY DDS-ALL-FORMATS OF DSPFILEX. .2/ ð3/22/94
24 +ððððð1 ð5 DSPFILEX-RECORD PIC X(8). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:FORMAT1 FROM FILE DSPFILEX OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
25 +ððððð4 ð5 FORMAT1-I REDEFINES DSPFILEX-RECORD. <-ALL-FMTS
26 +ððððð5 ð6 FORMAT1-I-INDIC. <-ALL-FMTS
27 +ððððð6 ð7 IN99 PIC 1 INDIC 99. .3/ <-ALL-FMTS
+ððððð7\ END OF PROGRAM <-ALL-FMTS
28 +ððððð8 ð7 IN51 PIC 1 INDIC 51. <-ALL-FMTS
+ððððð9\ DAILY REPORT <-ALL-FMTS
29 +ðððð1ð ð7 IN52 PIC 1 INDIC 52. <-ALL-FMTS
+ðððð11\ MONTHLY REPORT <-ALL-FMTS
3ð +ðððð12 ð6 DEPTNO PIC X(5). <-ALL-FMTS
+ðððð13\ OUTPUT FORMAT:FORMAT1 FROM FILE DSPFILEX OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð14\ <-ALL-FMTS
31 +ðððð15 ð5 FORMAT1-O REDEFINES DSPFILEX-RECORD. <-ALL-FMTS
32 +ðððð16 ð6 FORMAT1-O-INDIC. <-ALL-FMTS
33 +ðððð17 ð7 INð1 PIC 1 INDIC ð1. <-ALL-FMTS
ðð25ðð
34 ðð26ðð WORKING-STORAGE SECTION.
35 ðð27ðð ð1 CURRENT-DATE.
36 ðð28ðð ð5 CURR-YEAR PIC 9(2).
37 ðð29ðð ð5 CURR-MONTH PIC 9(2).
38 ðð3ððð ð5 CURR-DAY PIC 9(2).
ðð31ðð
39 ðð32ðð 77 IND-OFF PIC 1 VALUE B"ð".
4ð ðð33ðð 77 IND-ON PIC 1 VALUE B"1".
ðð34ðð
41 ðð35ðð ð1 RESPONSE-INDICS.
42 ðð36ðð ð5 END-OF-PROGRAM PIC 1. .4/
43 ðð37ðð ð5 DAILY-REPORT PIC 1.
44 ðð38ðð ð5 MONTHLY-REPORT PIC 1.
45 ðð39ðð ð1 OPTION-INDICS.
46 ðð4ððð ð5 NEW-MONTH PIC 1.
ðð41ðð
47 ðð42ðð PROCEDURE DIVISION.
ðð43ðð XMPLE3-MAIN.
48 ðð44ðð OPEN I-O DISPFILE.
49 ðð45ðð ACCEPT CURRENT-DATE FROM DATE.
5ð ðð46ðð MOVE IND-OFF TO END-OF-PROGRAM.
51 ðð47ðð PERFORM DISPLAY-SCREEN THRU READ-AND-PROCESS-SCREEN
ðð48ðð UNTIL END-OF-PROGRAM = IND-ON.
52 ðð49ðð CLOSE DISPFILE.
53 ðð5ððð STOP RUN.
ðð51ðð
ðð52ðð DISPLAY-SCREEN.
54 ðð53ðð MOVE ZEROS TO OPTION-INDICS.
55 ðð54ðð IF CURR-DAY = ð1 THEN .5/
56 ðð55ðð MOVE IND-ON TO NEW-MONTH.
57 ðð56ðð WRITE DISP-REC FORMAT IS "FORMAT1" .6/
ðð57ðð INDICATORS ARE OPTION-INDICS.
ðð58ðð

Figure 57 (Part 1 of 2). Example of a Program Using Indicators in the Record Area and the INDICATORS phrase in
the I/O Statements–COBOL Source Program

150 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð59ðð READ-AND-PROCESS-SCREEN.
58 ðð6ððð MOVE ZEROS TO RESPONSE-INDICS.
59 ðð61ðð READ DISPFILE FORMAT IS "FORMAT1" .7/
ðð62ðð INDICATORS ARE RESPONSE-INDICS. .8/
6ð ðð63ðð IF DAILY-REPORT = IND-ON THEN
61 ðð64ðð CALL "DAILY" USING DEPTNO .9/
ðð65ðð ELSE
62 ðð66ðð IF MONTHLY-REPORT = IND-ON THEN
63 ðð67ðð CALL "MONTHLY" USING DEPTNO.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
ð ð ð ð ð ð
Source records read . . . . . . . . : 67
Copy records read . . . . . . . . . : 17
Copy members processed . . . . . . : 1
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program XMPLE713 created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 57 (Part 2 of 2). Example of a Program Using Indicators in the Record Area and the INDICATORS phrase in
the I/O Statements–COBOL Source Program

.1/ The separate indicator area attribute, SI, is not coded in the ASSIGN clause.
.2/ The Format 2 COPY statement defines data fields and indicators in the
record area.
.3/ Because the file does not have a separate indicator area, response and
option indicators are defined in the order in which they are used in the DDS,
and the indicator numbers are treated as documentation.
.4/ All indicators used by the program are defined with meaningful names in
data description entries in WORKING-STORAGE. Indicator numbers are
omitted here because they have no effect. Indicators should be defined in
the order needed by the display file.
.5/ IN01 in WORKING-STORAGE is set on if it is the first day of the month.
.6/ FORMAT1 is written to the work station display:
Ÿ The INDICATORS phrase causes the contents of the variable
OPTION-INDICS to be copied to the beginning of the record area.
Ÿ Data and indicator values are written to the work station display.
.7/ FORMAT1, including both data and indicators, is read from the work station
display.
.8/ The INDICATORS phrase causes bytes to be copied from the beginning of
the record area to RESPONSE-INDICS.
.9/ If F5 has been pressed, a program call is processed.

Chapter 8. Transaction Files 151


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80

A* D I S P L AY F I LE DD S F OR I ND I CA T OR E X AMP L E S
A*
A I ND A R A
A R F OR MA T 1 CF 0 3 ( 9 9 ' E ND O F P R OGR AM ' )
A CF 0 5 ( 5 1 ' D A I L Y R E P OR T ' )
A CF 0 9 ( 5 2 ' MON T H L Y R E P OR T ' )
A*
A 10 1 0 ' D E P A R T ME N T N UMB E R : '
A D E P T NO 5 I 10 32
A 01 20 2 6 ' P R OD U C E MON T H L Y R E P OR T S '
A DSPAT R ( B L )
A*
A 24 01 ' F5 = D A I L Y R E P OR T '
A 24 26 ' F9 = MON T H L Y R E P OR T '
A 24 53 ' F3 = T E RM I NA T E '
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 58. Example of a Program Using Indicators in a Separate Indicator Area, Defined in WORKING-STORAGE by
Using the COPY Statement, DDS Format

.1/ The INDARA keyword is specified; indicators are stored in a separate indi-
cator area, not in the record area. Except for this specification, the DDS for
this file is the same as that shown in Figure 55 on page 147.

152 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð3/ð9/94
2 ððð2ðð PROGRAM-ID. XMPLE717. ð3/22/94
ððð3ðð\ SAMPLE PROGRAM - FILE WITH SEPARATE INDICATORS AREA ð3/ð9/94
3 ððð4ðð AUTHOR. PROGRAMMER NAME. ð3/ð9/94
4 ððð5ðð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE. ð3/ð9/94
5 ððð6ðð DATE-WRITTEN. 12/ð8/88. ð3/ð9/94
6 ðððð7ð DATE-COMPILED. ð5/24/94 12:53:17 .
7 ððð8ðð ENVIRONMENT DIVISION. ð3/ð9/94
8 ððð9ðð CONFIGURATION SECTION. ð3/ð9/94
9 ðð1ððð SOURCE-COMPUTER. IBM-AS4ðð. ð3/ð9/94
1ð ðð11ðð OBJECT-COMPUTER. IBM-AS4ðð. ð3/ð9/94
11 ðð12ðð INPUT-OUTPUT SECTION. ð3/ð9/94
12 ðð13ðð FILE-CONTROL. ð3/ð9/94
13 ðð14ðð SELECT DISPFILE ð3/ð9/94
14 ðð15ðð ASSIGN TO WORKSTATION-DSPFILE-SI .1/ ð3/22/94
15 ðð16ðð ORGANIZATION IS TRANSACTION ð3/ð9/94
16 ðð17ðð ACCESS IS SEQUENTIAL. ð3/ð9/94
ðð18ðð ð3/ð9/94
17 ðð19ðð DATA DIVISION. ð3/ð9/94
18 ðð2ððð FILE SECTION. ð3/ð9/94
19 ðð21ðð FD DISPFILE ð3/ð9/94
2ð ðð22ðð LABEL RECORDS ARE OMITTED ð3/ð9/94
21 ðð23ðð DATA RECORD IS DISP-REC. ð3/ð9/94
22 ðð24ðð ð1 DISP-REC. ð3/ð9/94
23 ðð25ðð COPY DDS-ALL-FORMATS OF DSPFILE. .2/ ð3/22/94
24 +ððððð1 ð5 DSPFILE-RECORD PIC X(5). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:FORMAT1 FROM FILE DSPFILE OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
25 +ððððð4 ð5 FORMAT1-I REDEFINES DSPFILE-RECORD. <-ALL-FMTS
26 +ððððð5 ð6 DEPTNO PIC X(5). <-ALL-FMTS
+ððððð6\ OUTPUT FORMAT:FORMAT1 FROM FILE DSPFILE OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð7\ <-ALL-FMTS
+ððððð8\ ð5 FORMAT1-O REDEFINES DSPFILE-RECORD. <-ALL-FMTS
ðð26ðð
27 ðð27ðð WORKING-STORAGE SECTION.
28 ðð28ðð ð1 CURRENT-DATE.
29 ðð29ðð ð5 CURR-YEAR PIC 9(2).
3ð ðð3ððð ð5 CURR-MONTH PIC 9(2).
31 ðð31ðð ð5 CURR-DAY PIC 9(2).
ðð32ðð
32 ðð33ðð 77 IND-OFF PIC 1 VALUE B"ð".
33 ðð34ðð 77 IND-ON PIC 1 VALUE B"1".
34 ðð35ðð ð1 DISPFILE-INDICS.
35 ðð36ðð COPY DDS-ALL-FORMATS-INDIC OF DSPFILE. .3/
36 +ððððð1 ð5 DSPFILE-RECORD. <-ALL-FMTS
+ððððð2\ INPUT FORMAT:FORMAT1 FROM FILE DSPFILE OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
37 +ððððð4 ð6 FORMAT1-I-INDIC. <-ALL-FMTS
38 +ððððð5 ð7 IN51 PIC 1 INDIC 51. .4/ <-ALL-FMTS
+ððððð6\ DAILY REPORT <-ALL-FMTS
39 +ððððð7 ð7 IN52 PIC 1 INDIC 52. <-ALL-FMTS
+ððððð8\ MONTHLY REPORT <-ALL-FMTS
4ð +ððððð9 ð7 IN99 PIC 1 INDIC 99. <-ALL-FMTS
+ðððð1ð\ END OF PROGRAM <-ALL-FMTS
+ðððð11\ OUTPUT FORMAT:FORMAT1 FROM FILE DSPFILE OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð12\
41 +ðððð13 ð6 FORMAT1-O-INDIC.
42 +ðððð14 ð7 INð1 PIC 1 INDIC ð1.
ðð37ðð
43 ðð38ðð PROCEDURE DIVISION.
ðð39ðð
ðð4ððð MAIN-PROCESS.
ðð41ðð
44 ðð42ðð OPEN I-O DISPFILE.
45 ðð43ðð ACCEPT CURRENT-DATE FROM DATE.
46 ðð44ðð MOVE IND-OFF TO IN99 IN FORMAT1-I-INDIC.
47 ðð45ðð PERFORM DISPLAY-SCREEN THRU READ-AND-PROCESS-SCREEN
ðð46ðð UNTIL IN99 IN FORMAT1-I-INDIC = IND-ON.
48 ðð47ðð CLOSE DISPFILE.
49 ðð48ðð STOP RUN.
ðð49ðð
ðð5ððð DISPLAY-SCREEN.
ðð51ðð
5ð ðð52ðð MOVE ZEROS TO FORMAT1-O-INDIC.
51 ðð53ðð IF CURR-DAY = ð1 THEN
52 ðð54ðð MOVE IND-ON TO INð1 IN FORMAT1-O-INDIC. .5/

Figure 59 (Part 1 of 2). COBOL Listing Using Indicators in a Separate Indicator Area

Chapter 8. Transaction Files 153


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
53 ðð55ðð WRITE DISP-REC FORMAT IS "FORMAT1"
ðð56ðð INDICATORS ARE FORMAT1-O-INDIC. .6/
ðð57ðð
ðð58ðð READ-AND-PROCESS-SCREEN.
ðð59ðð
54 ðð6ððð MOVE ZEROS TO FORMAT1-I-INDIC.
55 ðð61ðð READ DISPFILE FORMAT IS "FORMAT1"
ðð62ðð INDICATORS ARE FORMAT1-I-INDIC. .7/
56 ðð63ðð IF IN51 IN FORMAT1-I-INDIC = IND-ON THEN
57 ðð64ðð CALL "DAILY" USING DEPTNO .8/
ðð65ðð ELSE
58 ðð66ðð IF IN52 IN FORMAT1-I-INDIC = IND-ON THEN
59 ðð67ðð CALL "MONTHLY" USING DEPTNO.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 23 MSGID: LBLð6ðð SEVERITY: 1ð SEQNBR: ððð25ð
Message . . . . : No OUTPUT fields found for format FORMAT1.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 ð 1 ð ð ð
Source records read . . . . . . . . : 67
Copy records read . . . . . . . . . : 22
Copy members processed . . . . . . : 2
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : 1ð
LBLð9ð1 ðð Program XMPLE717 created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 59 (Part 2 of 2). COBOL Listing Using Indicators in a Separate Indicator Area

.1/ The separate indicator area attribute, SI, is specified in the ASSIGN clause.
.2/ The Format 2 COPY statement generates data descriptions in the record area
for data fields only. The data description entries for the indicators are not
generated because a separate indicator area has been specified for the file.
.3/ The Format 2 COPY statement, with the INDICATOR attribute, INDIC, defines
data description entries in WORKING-STORAGE for all indicators used in the
DDS for the record format for the file.
.4/ Because the file has a separate indicator area, the indicator numbers used in
the data description entries are not treated as documentation.
.5/ IN01 in the separate indicator area for FORMAT1 is set on if it is the first day
of the month.
.6/ The INDICATORS phrase is required to send indicator values to the work
station display.
.7/ The INDICATORS phrase is required to receive indicator values from the
work station display. If you have pressed F5, IN51 is set on.
.8/ If IN51 has been set on, a program call is processed.

154 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð1/22/94
2 ððð2ðð PROGRAM-ID. XMPLE72ð. ð3/22/94
ððð3ðð\ PROGRAM EXAMPLE ð1/22/94
ððð4ðð\ FILE WITH SEPARATE INDICATORS AREA IN WORKING STORAGE ð1/22/94
3 ððð5ðð AUTHOR. PROGRAMMER NAME. ð1/22/94
4 ððð6ðð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE. ð1/22/94
5 ððð7ðð DATE-WRITTEN. 12/ð8/88. ð1/22/94
6 ðððð8ð DATE-COMPILED. ð5/24/94 12:46:ðð .
7 ððð9ðð ENVIRONMENT DIVISION. ð1/22/94
8 ðð1ððð CONFIGURATION SECTION. ð1/22/94
9 ðð11ðð SOURCE-COMPUTER. IBM-AS4ðð. ð1/22/94
1ð ðð12ðð OBJECT-COMPUTER. IBM-AS4ðð. ð1/22/94
11 ðð13ðð INPUT-OUTPUT SECTION. ð1/22/94
12 ðð14ðð FILE-CONTROL. ð1/22/94
13 ðð15ðð SELECT DISPFILE ð1/22/94
14 ðð16ðð ASSIGN TO WORKSTATION-DSPFILE-SI .1/ ð3/22/94
15 ðð17ðð ORGANIZATION IS TRANSACTION ð1/22/94
16 ðð18ðð ACCESS IS SEQUENTIAL. ð1/22/94
ðð19ðð ð1/22/94
17 ðð2ððð DATA DIVISION. ð1/22/94
18 ðð21ðð FILE SECTION. ð1/22/94
19 ðð22ðð FD DISPFILE ð1/22/94
2ð ðð23ðð LABEL RECORDS ARE OMITTED ð1/22/94
21 ðð24ðð DATA RECORD IS DISP-REC. ð1/22/94
22 ðð25ðð ð1 DISP-REC. ð1/22/94
23 ðð26ðð COPY DDS-ALL-FORMATS OF DSPFILE. .2/ ð3/22/94
24 +ððððð1 ð5 DSPFILE-RECORD PIC X(5). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:FORMAT1 FROM FILE DSPFILE OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
25 +ððððð4 ð5 FORMAT1-I REDEFINES DSPFILE-RECORD. <-ALL-FMTS
26 +ððððð5 ð6 DEPTNO PIC X(5). <-ALL-FMTS
+ððððð6\ OUTPUT FORMAT:FORMAT1 FROM FILE DSPFILE OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð7\ <-ALL-FMTS
+ððððð8\ ð5 FORMAT1-O REDEFINES DSPFILE-RECORD. <-ALL-FMTS
ðð27ðð
27 ðð28ðð WORKING-STORAGE SECTION.
28 ðð29ðð ð1 CURRENT-DATE.
29 ðð3ððð ð5 CURR-YEAR PIC 9(2).
3ð ðð31ðð ð5 CURR-MONTH PIC 9(2).
31 ðð32ðð ð5 CURR-DAY PIC 9(2).
ðð33ðð
32 ðð34ðð ð1 INDIC-AREA.
33 ðð35ðð ð5 INDIC-TABLE OCCURS 99 PIC 1 INDICATOR 1. .3/
34 ðð36ðð 88 IND-OFF VALUE B"ð".
35 ðð37ðð 88 IND-ON VALUE B"1".
ðð38ðð
36 ðð39ðð ð1 DISPFILE-INDIC-USAGE.
37 ðð4ððð ð5 IND-NEW-MONTH PIC 9(2) VALUE ð1.
38 ðð41ðð ð5 IND-DAILY PIC 9(2) VALUE 51. .4/
39 ðð42ðð ð5 IND-MONTHLY PIC 9(2) VALUE 52.
4ð ðð43ðð ð5 IND-EOJ PIC 9(2) VALUE 99.
ðð44ðð
41 ðð45ðð PROCEDURE DIVISION.
ðð46ðð
ðð47ðð XMPLE-MAIN.
42 ðð48ðð OPEN I-O DISPFILE.
43 ðð49ðð ACCEPT CURRENT-DATE FROM DATE.
44 ðð5ððð SET IND-OFF (IND-EOJ) TO TRUE.
45 ðð51ðð PERFORM DISPLAY-SCREEN THRU READ-AND-PROCESS-SCREEN
ðð52ðð UNTIL IND-ON (IND-EOJ).
46 ðð53ðð CLOSE DISPFILE.
47 ðð54ðð STOP RUN.
ðð55ðð
ðð56ðð DISPLAY-SCREEN.
ðð57ðð
48 ðð58ðð MOVE ZEROS TO INDIC-AREA.
49 ðð59ðð IF CURR-DAY = ð1 THEN
5ð ðð6ððð SET IND-ON (IND-NEW-MONTH) TO TRUE. .5/
51 ðð61ðð WRITE DISP-REC FORMAT IS "FORMAT1"
ðð62ðð INDICATORS ARE INDIC-TABLE. .6/
ðð63ðð
ðð64ðð READ-AND-PROCESS-SCREEN.
ðð65ðð
52 ðð66ðð READ DISPFILE FORMAT IS "FORMAT1"
ðð67ðð INDICATORS ARE INDIC-TABLE. .7/

Figure 60 (Part 1 of 2). Example of a Program Using Indicators in a Separate Indicator Area, Defined in a Table in
WORKING-STORAGE

Chapter 8. Transaction Files 155


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
53 ðð68ðð IF IND-ON (IND-DAILY) THEN .8/
54 ðð69ðð CALL "DAILY" USING DEPTNO
ðð7ððð ELSE
55 ðð71ðð IF IND-ON (IND-MONTHLY) THEN
56 ðð72ðð CALL "MONTHLY" USING DEPTNO.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 23 MSGID: LBLð6ðð SEVERITY: 1ð SEQNBR: ððð26ð
Message . . . . : No OUTPUT fields found for format FORMAT1.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 ð 1 ð ð ð
Source records read . . . . . . . . : 72
Copy records read . . . . . . . . . : 8
Copy members processed . . . . . . : 1
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : 1ð
LBLð9ð1 ðð Program XMPLE72ð created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 60 (Part 2 of 2). Example of a Program Using Indicators in a Separate Indicator Area, Defined in a Table in
WORKING-STORAGE

.1/ The separate indicator area attribute, SI, is specified in the ASSIGN clause.
.2/ The Format 2 COPY statement generates fields in the record area for data
fields only.
.3/ A table of 99 Boolean data items is defined in WORKING-STORAGE. The
INDICATOR clause for this data description entry causes these data items to
be associated with indicators 1 through 99 respectively. The use of such a
table may result in improved performance as compared to the use of a group
item with multiple subordinate entries for individual indicators.
.4/ A series of data items is defined in WORKING-STORAGE to provide mean-
ingful subscript names with which to refer to the table of indicators. The use
of such data items is not required.
.5/ INDIC-TABLE (01) in the separate indicator area for FORMAT1 is set on if it
is the first day of the month.
.6/ The INDICATOR phrase is required to send indicator values to the work
station display.
.7/ The INDICATOR phrase is required to receive indicator values from the work
station display. If F5 has been pressed, INDIC-TABLE (51) will be set on.
.8/ If INDIC-TABLE (51) has been set on, program DAILY is called.

Subfiles
Subfiles can be specified in the DDS for a display file to allow you to handle mul-
tiple records of the same type on a display. See Figure 61 on page 157 for an
example of a subfile display. A subfile is a group of records that are read from or
written to a display device. The program processes one record at a time, but the
operating system and the work station send and receive blocks of records. If more
records are transmitted than can be shown on the display at one time, the work
station operator can page through the block of records without returning control to
the program.

156 COBOL/400 User’s Guide


Records to be included in a subfile are specified in the DDS for the file. The
number of records that can be contained in a subfile must also be specified in the
DDS. One file can contain more than one subfile; however, only twelve subfiles
can be active concurrently for a device. Twelve subfiles can be displayed on a
device at the same time.

The DDS for a subfile consists of two record formats: a subfile record format and a
subfile control record format.

The subfile record format contains the field descriptions for the records in the
subfile. Specifications of the subfile record format on a READ, WRITE, or
REWRITE causes the specified subfile record to be processed, but does not
directly affect the displayed data.

Specification of the subfile control record format on the READ or WRITE statement
causes the physical read, write, or setup operations of a subfile to take place.
Figure 62 on page 159 shows an example of the DDS for a subfile record format,
and Figure 63 on page 161 shows an example of the DDS for a subfile control
record format.

For a description of how the records in a subfile can be displayed and for a
description of the keywords that can be specified for a subfile, see the Data Man-
agement Guide and also the DDS Reference.

à@ Customer Name Search ð


Search Code _____

Number Name Address City State

XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX


XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX
XXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XX

á ñ
Figure 61. Subfile Display

To use a subfile for a display file in a COBOL program, you must specify the
SUBFILE phrase with the input/output operation. Valid subfile operations are:
Ÿ READ SUBFILE file-name RECORD
Ÿ WRITE SUBFILE record-name
Ÿ REWRITE SUBFILE record-name.

Chapter 8. Transaction Files 157


Subfiles can be processed sequentially with the READ SUBFILE NEXT MODIFIED
statement, or processed randomly by specifying a relative key value. A relative key
is an unsigned number that can be used directly by the system to locate a record in
a file.

The TRANSACTION file must be an externally defined file. In COBOL, all access
to the subfile is done with a relative record number. If the SUBFILE phrases are
used with a TRANSACTION file, the SELECT statement in the Environment Divi-
sion must state that ACCESS MODE IS DYNAMIC and must specify the RELATIVE
KEY to be used.

If more than one display device is acquired by a display file, there is a separate
subfile for each individual display device. If a subfile has been created for a partic-
ular display device acquired by a TRANSACTION file, all input operations that refer
to a record format for the subfile are performed against the subfile belonging to that
device. See the discussion on the TERMINAL phrase on page 182 of this chapter
for information about how to determine which device is used. Any operations that
reference a record format name that is not designated as a subfile are processed
as an input/output operation directly to the display device.

Use of Subfiles
Some typical uses of subfiles include:

Use Meaning
Display Only The work station user reviews the display.
Display With Selection The user requests more information about one of the items on
display.
Modification The user modifies one or more of the records.
Input Only (with no validity checking) A subfile is used for a data-entry function.
Input Only (with validity checking) A subfile is used for a data-entry function, and the records are
checked as well.
Combination of Tasks A subfile can be used as a display with modification.

158 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1- 98 91- 0 UM/05 0*
Pr i nt ed i n U. S . A.
I nt er nat i onal Bus i nes s Machi nes * Number of sheet s per pad may var y sl i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Us ag e (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne P os

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 23 2 4 25 2 6 27 2 8 29 30 3 1 32 33 3 4 35 3 6 37 38 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* DD S F OR T H E D I S P L A Y D E V I C E F I L E P A Y U P D T D
A* ACCOU N T S R E C E I V A B L E I N T E R AC T I V E P A Y ME N T UP DA T E
A*
A R S UB F I L E 1 SFL
A T E X T ( ' S UB F I L E F OR C U S T OME R P A Y ME N T ' )
A*
A AC P P M T 4A I 5 4 T E X T ( ' ACC E P T P A Y ME N T ' )
A V A L U E S ( ' * Y E S ' ' * NO ' )
A 51 D S P A T R ( R I MD T )
A N5 1 D S P A T R ( ND P R )
A*
A CU S T 5 B 5 15TEXT ( ' C U S T OME R N UMB E R ' )
A 52 DSPAT R(R I )
A 53 DSPAT R ( ND )
A 54 DSPAT R ( PR )
A*
A AMP A I D 8 02B 5 2 4 T E X T ( ' AMOU N T PA I D ' )
A CH E CK ( F E )
A AU T O( R AB )
A CMP ( G T 0 )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A E CP MS G 3 1A O 5 37TEXT ( ' E X C E P T I ON ME S S AG E ' )
A 52 DSPAT R(R I )
A 53 DSPAT R ( ND )
A 54 DSPAT R(BL )
A*
A OV R P M T 8Y 2O 5 7 0 T E X T ( ' OV E R P A Y ME N T ' )
A E D T CD E ( 1 )
A 55 DSPAT R ( B L )
A N5 6 D S P A T R ( ND )
A*
A S T S CD E 1A H T E X T ( ' S T A T U S COD E ' )

Figure 62. Data Description Specifications for a Subfile Record Format

The data description specifications (DDS) for a subfile record format describe the
records in the subfile:
.1/ The SFL keyword identifies the record format as a subfile.
.2/ The line and position entries define the location of the fields on the display.
.3/ The VALUES keyword specifies that the user can only specify *YES or *NO
as values for the ACPPMT field.
.4/ The usage entries define whether the named field is to be an output (O), input
(I), output/input (B), or hidden (H) field.
.5/ The entry CHECK(FE) specifies that the user cannot skip to the next input
field without pressing one of the field exit keys.

Chapter 8. Transaction Files 159


.6/ The entry AUTO(RAB) specifies that data entered into the field AMPAID is to
be automatically right-justified, and the leading characters are to be filled with
blanks.
.7/ The entry CMP(GT 0) specifies that the data entered for the field AMPAID is
to be compared to zero to ensure that the value is greater than zero.
.8/ The EDTCDE keyword specifies the desired editing for output field OVRPMT.
EDTCDE(1) indicates that the field OVRPMT is to be printed with commas,
decimal point, and no sign. Also, a zero balance will be printed, and leading
zeros will be suppressed.
.9/ The DSPATR keyword is used to specify the display attributes for the named
field when the corresponding indicator status is true. The attributes specified
are:
Ÿ BL (blink)
Ÿ RI (reverse image)
Ÿ PR (protect)
Ÿ MDT (set modified data tag)
Ÿ ND (nondisplay).

160 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1- 98 91- 0 UM/05 0*
Pr i nt ed i n U. S . A.
I nt er nat i onal Bus i nes s Machi nes * Number of sheet s per pad may var y sl i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of Spec (b/R/H/J/K/S/O)


Conditioning

Location

Us ag e (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne P os

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 23 2 4 25 2 6 27 2 8 29 30 3 1 32 33 3 4 35 3 6 37 38 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A R CON T R O L 1 T E X T ( ' S U B F I L E CON T R O L ' )


A S F L CT L ( S UB F I L E 1 )
A SFL S I Z ( 17 )
A S F L P AG ( 1 7 )
A 61 S F L CL R
A 62 S F LDSP
A 62 S F L DS PCT L
A OV E R L A Y
A L OC K
A*
A HE L P ( 9 9 ' HE L P K E Y ' )
A CA 1 2 ( 9 8 ' E ND P A Y ME N T U P D A T E ' )
A CA 1 1 ( 9 7 ' I GNOR E I N P U T ' )
A*
A 99 S F L MS G ( ' F 1 1 - I GNOR E I N V A L I D I N P U T +
A F 1 2 - E ND P A Y ME N T +
A U P DA T E ' )
A*
A 1 2 ' C U S T OME R P A Y ME N T U P D A T E P R OMP T '
A 1 6 5 ' DA T E '
A 1 7 8 D A T E E D T CD E ( Y )
A 63 3 2 ' ACC E P T '
A 63 4 2 ' P A Y ME N T '
A 3 1 4 ' C U S T OME R '
A 3 2 6 ' P A Y ME N T '
A 64 3 3 7 ' E X C E P T I ON ME S S AG E '
A
A
A
A
A
A
A
A
A

Figure 63. Data Description Specifications for a Subfile Control Record Format

The subfile control record format defines the attributes of the subfile, the search
input field, constants, and command keys. The keywords used indicate the fol-
lowing:
.1/ SFLCTL identifies this record as a subfile control record and names the
associated subfile record (SUBFILE1).
.2/ SFLSIZ indicates the total number of records to be included in the subfile
(17).
.3/ SFLPAG indicates the total number of records in a page (17).
.4/ SFLCLR indicates when the subfile should be cleared (when indicator 61 is
on).
.5/ SFLDSP indicates when to display the subfile (when indicator 62 is on).
.6/ SFLDSPCTL indicates when to display the subfile control record (when indi-
cator 62 is on).

Chapter 8. Transaction Files 161


.7/ The LOCK keyword prevents the work station user from using the keyboard
when the CONTROL1 record format is initially displayed.
.8/ HELP allows the user to press the Help key and sets indicator 99 on.
.9/ SFLMSG identifies the constant as a message that is displayed if indicator
99 is on.

In addition to the control information, the subfile control record format defines the
constants to be used as column headings for the subfile record format. Refer to
Figure 63 on page 161 for an example of the subfile control record format.

Multiple Device Files and Single Device Files


A multiple device file is either a display file or an intersystem communications
function (ICF) file. A multiple device file can acquire more than one program
device. For an example of the use of multiple device files, see Figure 64 on
page 163.

A single device file is a device file created with only one program device defined
for it. Printer files, diskette files and tape files are single device files. Display files
and intersystem communication function (ICF) files created with a maximum
number of one program device are also single device files.

A display file can have multiple program devices when the MAXDEV parameter of
the CRTDSPF command is greater than 1. If you specify *NONE for the DEV
parameter of this command, you must supply the name of a display device before
you use any fields that are related to the file.

For more information about how to create and use a display file, see the Data Man-
agement Guide.

ICF files can have multiple program devices when the MAXPGMDEV parameter of
the CRTICFF command is greater than 1. For more information about how to
create and use ICF files, see the ICF Programmer’s Guide.

COBOL determines at run time whether a file is a single device file or a multiple
device file, based on whether the file is capable of having multiple devices. The
actual number of devices acquired does not affect whether a file is considered a
single or multiple device file. Whether a file is a single or a multiple device file is
not determined at compilation time; this determination is based on the current
description of the display or ICF file.

For multiple device files, if a particular program device is to be used in an I/O state-
ment, that device is specified by the TERMINAL phrase. The TERMINAL phrase
can also be specified for a single device file.

The following pages contain an example illustrating the use of multiple device files.
The program uses a display file, and is intended to be run in batch mode. The
program acquires terminals and invites those terminals using a sign-on display.
After the terminals are invited, they are polled. If nobody signs on before the wait
time expires, the program ends. If you enter a valid password, you are allowed to
update an employee file by calling another COBOL program. Once the update is
complete, the device is invited again and the terminals are polled again.

162 COBOL/400 User’s Guide


GX21-9891-0 UM/050*
AS/400 DATA DESCRIPTION SPECIFICATIONS Pr i nt ed i n U. S. A.
I n t e r n a t i o n a l B u s i n e s s Ma c h i n es * Number of s heet s per pad may var y sl i gh tl y.

File Keying Graphic Descr iption Page of


I ns tr ucti on
Progr ammer Date Key

T y pe of Name o f S pec /( b /R / H/ J / K/ S /O)


Conditioning

Location

U s a g e (/ b / O / I / B / H / M / N / P )
And/Or /Comment (A/O/* )

Data Type/Keyboard Shi ft


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
For m Type

Po s i t i o n s
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 1 4 15 16 17 18 19 2 0 2 1 22 2 3 24 2 5 26 27 2 8 29 3 0 3 1 32 3 3 34 3 5 36 37 38 39 4 0 4 1 4 2 4 3 44 4 5 46 4 7 48 49 50 5 1 5 2 53 5 4 55 5 6 5 7 58 5 9 60 6 1 6 2 63 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80

A*
A * DD S F OR T H E MU L T I P L E D E V I C E D I S P L A Y F I L E
A*
A R S I GNON I NV I T E
A O 5 20 / 'b /b /b/ /b /b/b/b/b/b/b/b/b/b/b/b/b/ b/ b/ b/ b/ '
A DSPAT R ( R I )
A O 6 20 / ' b/ b/ '
A DSPAT R ( R I )
A O 6 3 8 ' b/ b/ '
A
The f or mat SI GNON has DSPAT R ( R I )
A O 7 20 / ' b/ b/ '
the
A keyword INVI TE DSPAT R ( R I )
as s oc A i a t e d wi t h i t . T h i s O 7 27 'M D F '
means A that, i f f ormat SI GNON DSPAT R ( H I B L )
A O 7 3 8 ' b/ b/ '
i s usAed i n a WRI T E s t at ement , DSPAT R ( R I )
the Adevi ce to whi ch i t i s O 8 20 / ' b/ b/ '
wr i t iAng wi l l be i nvi t ed. DSPAT R ( R I )
A O 8 3 8 ' b/ b/ '
A DSPAT R ( R I )
A O 9 20 / ' /b /b/b/b/b/b/b/b/b/b/b/b/ b/ b/ b/ b/ b/ b
/b/b/ '
A DSPAT R ( R I )
A O 2 0/ 2 0 / ' P L E A S E L OGON '
A DSPAT R ( H I )
A P A S SWOR D 1 /0 A I 2 0/ 4 3 D S P A T R ( P C ND )
A WR ONG 2 /0 A O 21 43
A R U P DA T E
A O 3 5 ' U P DA T E OF P E R S ONN E L F I L E '
A DSPAT R ( B L )
A O 7 5 ' T Y P E I N E MP L OY E E NUMB E R +
A T O B E U P DA T E D '
A NUM 7A I 7 4 4D S P A T R ( R I PC )
A R E MP L OY E E
A O 3 5 ' E MP L OY E E NUMB E R '
A NUM 7A B 3 2 5D S P A T R ( PC )
A O 5 5 ' E MP L OY E E NAME '
A NAME 3 /0 A B 5 2 5D S P A T R ( PC )
A O 7 5 ' E MP L OY E E ADD R E S S '
A O 9 5 ' S TREE T '
A S TREE T 3 /0 A B 9 2 5D S P A T R ( PC )
A O 11 5 ' AP AR T ME N T NUMB E R '
A AP T NO 5A B 1 1 2 5 ' D S P A T R ( PC )
A O 13 5 'CI TY '
A CI TY 2 /0 A B 1 3 2 5D S P A T R ( PC )
A O 15 5 ' P R OV I NC E '
A P R OV 2 /0 A B 1 5 2 5D S P A T R ( PC )
A R R E COV E R Y
A O 3 5 ' T H E E MP L OY E E NUMB E R YOU +
A HAV E G I V E N I S I NVA L I D '
A O 6 5 ' T YP E Y TO R E T R Y '
A O 8 5 ' T YP E N TO E X I T '
A AN SWE R 1X I 1 0/ 5D S P A T R ( R I PC )
A VA L U E S ( ' Y ' ' N ' )
A
A
A
A
A
A

Figure 64 (Part 1 of 3). Example of the Use of Multiple Device Files

Chapter 8. Transaction Files 163


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may vary sl i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e ( b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80

A*
A* DD S F OR T HE P H Y S I CA L F I LE P A S S WOR D
A*
A U N I QU E
A R PAS S WOR D S
A PAS SKEY 1 0/
A PAS S WOR D 10 /

A K PAS SKEY
A
A
A
A
A
A
A
A
A
A
A
A

Figure 64 (Part 2 of 3). Example of the Use of Multiple Device Files

164 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may vary sl i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e ( b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shi ft


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 1 4 15 16 17 18 19 20 2 1 22 2 3 24 2 5 26 27 2 8 29 3 0 3 1 32 3 3 34 3 5 36 37 38 39 4 0 4 1 4 2 4 3 44 4 5 46 4 7 48 49 50 5 1 5 2 5 3 5 4 55 5 6 5 7 58 5 9 60 6 1 6 2 63 6 4 65 6 6 6 7 68 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80

A*
A * D D S F OR T H E P H Y S I CA L F I L E T E R M
A * WH I C H CON T A I N S T H E L I S T O F T E R M I N A L S
A*
A R T E RM
A T E RM 1 0/
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 64 (Part 3 of 3). Example of the Use of Multiple Device Files

Chapter 8. Transaction Files 165


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/SAMPMDF AS4ððSYS ð3/31/94 13:58:ð5 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. SAMPMDF.
3 ðððð3ð AUTHOR. PROGRAMMER NAME.
ðððð4ð
ðððð5ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðððð6ð\ THE FOLLOWING PROGRAM DEMONSTRATES SOME OF THE FUNCTIONS \
ðððð7ð\ AVAILABLE WITH MULTIPLE DEVICE FILE SUPPORT. \
ðððð8ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðððð9ð
4 ððð1ðð INSTALLATION. COBOL DEVELOPMENT CENTRE.
5 ððð11ð DATE-WRITTEN. ð2/ð2/87.
6 ððð12ð DATE-COMPILED. ð3/31/94 13:58:ð5 .
7 ððð13ð ENVIRONMENT DIVISION.
8 ððð14ð CONFIGURATION SECTION.
9 ððð15ð SOURCE-COMPUTER. IBM-AS4ðð.
1ð ððð16ð OBJECT-COMPUTER. IBM-AS4ðð.
11 ððð17ð SPECIAL-NAMES. ATTRIBUTE-DATA IS ATTR. .1/
12 ððð18ð INPUT-OUTPUT SECTION.
13 ððð19ð FILE-CONTROL.
14 ððð2ðð SELECT MULTIPLE-FILE
15 ððð21ð ASSIGN TO WORKSTATION-MULT
16 ððð22ð ORGANIZATION IS TRANSACTION .2/
17 ððð23ð ACCESS MODE IS SEQUENTIAL
18 ððð24ð FILE STATUS IS MULTIPLE-FS1, MULTIPLE-FS2 .3/
19 ððð25ð CONTROL-AREA IS MULTIPLE-CONTROL-AREA.
ððð26ð .4/
2ð ððð27ð SELECT TERMINAL-FILE
21 ððð28ð ASSIGN TO DATABASE-TERM
22 ððð29ð ORGANIZATION IS SEQUENTIAL
23 ððð3ðð ACCESS IS SEQUENTIAL
24 ððð31ð FILE STATUS IS TERMINAL-FS1.
ððð32ð
25 ððð33ð SELECT PASSWORD-FILE
26 ððð34ð ASSIGN TO DATABASE-PASSWORD
27 ððð35ð ORGANIZATION IS INDEXED
28 ððð36ð RECORD KEY IS EXTERNALLY-DESCRIBED-KEY
29 ððð37ð ACCESS MODE IS RANDOM
3ð ððð38ð FILE STATUS IS PASSWORD-FS1.
ððð39ð
31 ððð4ðð SELECT PRINTER-FILE
32 ððð41ð ASSIGN TO PRINTER-QPRINT.
33 ððð42ð DATA DIVISION.
34 ððð43ð FILE SECTION.
35 ððð44ð FD MULTIPLE-FILE.
36 ððð45ð ð1 MULTIPLE-REC. COPY DDS-SIGNON OF MULT. .5/
37 +ððððð1 ð5 MULT-RECORD PIC X(2ð). SIGNON
+ððððð2\ INPUT FORMAT:SIGNON FROM FILE MULT OF LIBRARY TESTER SIGNON
+ððððð3\ SIGNON
38 +ððððð4 ð5 SIGNON-I REDEFINES MULT-RECORD. SIGNON
39 +ððððð5 ð6 PASSWORD PIC X(1ð). .6/ SIGNON
+ððððð6\ OUTPUT FORMAT:SIGNON FROM FILE MULT OF LIBRARY TESTER SIGNON
+ððððð7\ SIGNON
4ð +ððððð8 ð5 SIGNON-O REDEFINES MULT-RECORD. SIGNON
41 +ððððð9 ð6 WRONG PIC X(2ð). SIGNON
ððð46ð
42 ððð47ð FD TERMINAL-FILE.
43 ððð48ð ð1 TERMINAL-REC. COPY DDS-ALL-FORMATS OF TERM.
44 +ððððð1 ð5 TERM-RECORD PIC X(1ð). <-ALL-FMTS
+ððððð2\ I-O FORMAT:TERM FROM FILE TERM OF LIBRARY TESTER <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
45 +ððððð4 ð5 TERM REDEFINES TERM-RECORD. <-ALL-FMTS
46 +ððððð5 ð6 TERM PIC X(1ð). <-ALL-FMTS
ððð49ð
47 ððð5ðð FD PASSWORD-FILE.
48 ððð51ð ð1 PASSWORD-REC. COPY DDS-ALL-FORMATS OF PASSWORD.
49 +ððððð1 ð5 PASSWORD-RECORD PIC X(2ð). <-ALL-FMTS
+ððððð2\ I-O FORMAT:PASSWORDS FROM FILE PASSWORD OF LIBRARY TESTER <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
+ððððð4\THE KEY DEFINITIONS FOR RECORD FORMAT PASSWORDS <-ALL-FMTS
+ððððð5\ NUMBER NAME RETRIEVAL TYPE ALTSEQ <-ALL-FMTS
+ððððð6\ ððð1 PASSKEY ASCENDING AN NO <-ALL-FMTS
5ð +ððððð7 ð5 PASSWORDS REDEFINES PASSWORD-RECORD. <-ALL-FMTS
51 +ððððð8 ð6 PASSKEY PIC X(1ð). <-ALL-FMTS
52 +ððððð9 ð6 PASSWORD PIC X(1ð). <-ALL-FMTS
ððð52ð

Figure 65 (Part 1 of 4). COBOL Source Listing for Multiple Device File Support

166 COBOL/400 User’s Guide


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/SAMPMDF AS4ððSYS ð3/31/94 13:58:ð5 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
53 ððð53ð FD PRINTER-FILE.
54 ððð54ð ð1 PRINTER-REC.
55 ððð55ð ð5 PRINTER-RECORD PIC X(132).
ððð56ð
56 ððð57ð WORKING-STORAGE SECTION.
ððð58ð
ððð59ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð6ðð\ DECLARE THE FILE STATUS FOR EACH FILE \
ððð61ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð62ð
57 ððð63ð ð1 MULTIPLE-FS1 PIC X(2) VALUE SPACES.
58 ððð64ð ð1 MULTIPLE-FS2. .7/
59 ððð65ð ð5 MULTIPLE-MAJOR PIC X(2) VALUE SPACES.
6ð ððð66ð ð5 MULTIPLE-MINOR PIC X(2) VALUE SPACES.
61 ððð67ð ð1 TERMINAL-FS1 PIC X(2) VALUE SPACES.
62 ððð68ð ð1 PASSWORD-FS1 PIC X(2) VALUE SPACES.
ððð69ð
ððð7ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð71ð\ DECLARE STRUCTURE FOR HOLDING FILE ATTRIBUTES \
ððð72ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð73ð
63 ððð74ð ð1 STATION-ATTR.
64 ððð75ð ð5 STATION-TYPE PIC X(1). .8/
65 ððð76ð ð5 STATION-SIZE PIC X(1).
66 ððð77ð ð5 STATION-LOC PIC X(1).
67 ððð78ð ð5 FILLER PIC X(1).
68 ððð79ð ð5 STATION-ACQUIRE PIC X(1).
69 ððð8ðð ð5 STATION-INVITE PIC X(1).
7ð ððð81ð ð5 STATION-DATA PIC X(1).
71 ððð82ð ð5 STATION-STATUS PIC X(1).
72 ððð83ð ð5 STATION-DISPLAY PIC X(1).
73 ððð84ð ð5 STATION-KEYBOARD PIC X(1).
74 ððð85ð ð5 STATION-SIGNON PIC X(1).
75 ððð86ð ð5 FILLER PIC X(5).
ððð87ð
ððð88ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð89ð\ DECLARE THE CONTROL AREA FOR MULTIPLE-FILE \
ððð9ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð91ð
76 ððð92ð ð1 MULTIPLE-CONTROL-AREA.
77 ððð93ð ð5 MULTIPLE-KEY-FEEDBACK PIC X(2) VALUE SPACES.
78 ððð94ð ð5 MULTIPLE-DEVICE-NAME PIC X(1ð) VALUE SPACES.
79 ððð95ð ð5 MULTIPLE-FORMAT-NAME PIC X(1ð) VALUE SPACES.
ððð96ð
ððð97ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð98ð\ DECLARE ERROR REPORT VARIABLES \
ððð99ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð1ððð
8ð ðð1ð1ð ð1 HEADER-LINE.
81 ðð1ð2ð ð5 FILLER PIC X(6ð) VALUE SPACES.
82 ðð1ð3ð ð5 FILLER PIC X(72)
83 ðð1ð4ð VALUE "MDF ERROR REPORT".
84 ðð1ð5ð ð1 DETAIL-LINE.
85 ðð1ð6ð ð5 FILLER PIC X(15) VALUE SPACES.
86 ðð1ð7ð ð5 DESCRIPTION PIC X(25) VALUE SPACES.
87 ðð1ð8ð ð5 DETAIL-VALUE PIC X(92) VALUE SPACES.
ðð1ð9ð
ðð11ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð111ð\ DECLARE COUNTERS, FLAGS AND STORAGE VARIABLES \
ðð112ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð113ð
88 ðð114ð ð1 CURRENT-TERMINAL PIC X(1ð) VALUE SPACES.
89 ðð115ð ð1 TERMINAL-ARRAY.
9ð ðð116ð ð5 LIST-OF-TERMINALS OCCURS 25ð TIMES.
91 ðð117ð ð7 DEVICE-NAME PIC X(1ð).
92 ðð118ð ð1 COUNTER PIC 9(3) VALUE IS 1.
93 ðð119ð ð1 NO-OF-TERMINALS PIC 9(3) VALUE IS 1.
94 ðð12ðð ð1 TERMINAL-LIST-FLAG PIC 1.
95 ðð121ð 88 END-OF-TERMINAL-LIST VALUE IS B"1".
96 ðð122ð 88 NOT-END-OF-TERMINAL-LIST VALUE IS B"ð".
97 ðð123ð ð1 NO-DATA-FLAG PIC 1.
98 ðð124ð 88 NO-DATA-AVAILABLE VALUE IS B"1".
99 ðð125ð 88 DATA-AVAILABLE VALUE IS B"ð".
ðð126ð

Figure 65 (Part 2 of 4). COBOL Source Listing for Multiple Device File Support

Chapter 8. Transaction Files 167


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/SAMPMDF AS4ððSYS ð3/31/94 13:58:ð5 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1ðð ðð127ð PROCEDURE DIVISION.
ðð128ð
ðð129ð DECLARATIVES.
ðð13ðð
ðð131ð MULTIPLE-SECTION SECTION.
ðð132ð USE AFTER STANDARD EXCEPTION PROCEDURE ON MULTIPLE-FILE.
ðð133ð
ðð134ð MULTIPLE-PARAGRAPH.
1ð1 ðð135ð WRITE PRINTER-REC FROM HEADER-LINE AFTER ADVANCING PAGE.
1ð2 ðð136ð MOVE "FILE NAME IS:" TO DESCRIPTION OF DETAIL-LINE.
1ð3 ðð137ð MOVE "MULTIPLE FILE" TO DETAIL-VALUE OF DETAIL-LINE.
1ð4 ðð138ð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 5 LINES.
1ð5 ðð139ð MOVE "FILE STATUS IS:" TO DESCRIPTION OF DETAIL-LINE.
1ð6 ðð14ðð MOVE MULTIPLE-FS1 TO DETAIL-VALUE OF DETAIL-LINE.
1ð7 ðð141ð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
1ð8 ðð142ð MOVE "EXTENDED STATUS IS:" TO DESCRIPTION OF DETAIL-LINE. .9/
1ð9 ðð143ð MOVE MULTIPLE-FS2 TO DETAIL-VALUE OF DETAIL-LINE.
11ð ðð144ð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
111 ðð145ð ACCEPT STATION-ATTR FROM ATTR. .9A/
112 ðð146ð MOVE "FILE ATTRIBUTES ARE:" TO DESCRIPTION OF DETAIL-LINE.
113 ðð147ð MOVE STATION-ATTR TO DETAIL-VALUE OF DETAIL-LINE.
114 ðð148ð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
115 ðð149ð STOP RUN.
ðð15ðð
ðð151ð TERMINAL-SECTION SECTION.
ðð152ð USE AFTER STANDARD EXCEPTION PROCEDURE ON TERMINAL-FILE.
ðð153ð TERMINAL-PARAGRAPH.
116 ðð154ð WRITE PRINTER-REC FROM HEADER-LINE AFTER ADVANCING PAGE.
117 ðð155ð MOVE "FILE NAME IS:" TO DESCRIPTION OF DETAIL-LINE.
118 ðð156ð MOVE "TERMINAL FILE" TO DETAIL-VALUE OF DETAIL-LINE.
119 ðð157ð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 5 LINES.
12ð ðð158ð MOVE "FILE STATUS IS:" TO DESCRIPTION OF DETAIL-LINE.
121 ðð159ð MOVE TERMINAL-FS1 TO DETAIL-VALUE OF DETAIL-LINE.
122 ðð16ðð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
123 ðð161ð STOP RUN.
ðð162ð
ðð163ð PASSWORD-SECTION SECTION.
ðð164ð USE AFTER STANDARD EXCEPTION PROCEDURE ON PASSWORD-FILE.
ðð165ð PASSWORD-PARAGRAPH.
124 ðð166ð WRITE PRINTER-REC FROM HEADER-LINE AFTER ADVANCING PAGE.
125 ðð167ð MOVE "FILE NAME IS:" TO DESCRIPTION OF DETAIL-LINE.
126 ðð168ð MOVE "PASSWORD FILE" TO DETAIL-VALUE OF DETAIL-LINE.
127 ðð169ð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 5 LINES.
128 ðð17ðð MOVE "FILE STATUS IS:" TO DESCRIPTION OF DETAIL-LINE.
129 ðð171ð MOVE PASSWORD-FS1 TO DETAIL-VALUE OF DETAIL-LINE.
13ð ðð172ð WRITE PRINTER-REC FROM DETAIL-LINE AFTER ADVANCING 2 LINES.
131 ðð173ð STOP RUN.
ðð174ð
ðð175ð END DECLARATIVES.
ðð176ð
ðð177ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð178ð\ MAIN PROGRAM LOGIC BEGINS HERE \
ðð179ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð18ðð
ðð181ð MAIN-LINE SECTION.
ðð182ð MAIN-LINE-PARAGRAPH.
132 ðð183ð OPEN I-O MULTIPLE-FILE .1ð/
ðð184ð INPUT TERMINAL-FILE
ðð185ð I-O PASSWORD-FILE
ðð186ð OUTPUT PRINTER-FILE.
ðð187ð
133 ðð188ð MOVE 1 TO COUNTER.
134 ðð189ð SET NOT-END-OF-TERMINAL-LIST TO TRUE.
ðð19ðð PERFORM
135 ðð191ð FILL-TERMINAL-LIST UNTIL END-OF-TERMINAL-LIST.
ðð192ð PERFORM
136 ðð193ð ACQUIRE-AND-INVITE-TERMINALS
ðð194ð VARYING COUNTER FROM 1 BY 1
ðð195ð UNTIL COUNTER GREATER THAN NO-OF-TERMINALS.
137 ðð196ð MOVE 1 TO COUNTER.
138 ðð197ð SET DATA-AVAILABLE TO TRUE.
ðð198ð PERFORM
139 ðð199ð POLL-TERMINALS UNTIL NO-DATA-AVAILABLE.
ðð2ððð PERFORM
14ð ðð2ð1ð DROP-TERMINALS
ðð2ð2ð VARYING COUNTER FROM 1 BY 1
ðð2ð3ð UNTIL COUNTER GREATER THAN NO-OF-TERMINALS.

Figure 65 (Part 3 of 4). COBOL Source Listing for Multiple Device File Support

168 COBOL/400 User’s Guide


5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/SAMPMDF AS4ððSYS ð3/31/94 13:58:ð5 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
141 ðð2ð4ð CLOSE MULTIPLE-FILE
ðð2ð5ð TERMINAL-FILE
ðð2ð6ð PASSWORD-FILE
ðð2ð7ð PRINTER-FILE.
142 ðð2ð8ð STOP RUN.
ðð2ð9ð
ðð21ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð211ð\ PROCEDURES \
ðð212ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð213ð
ðð214ð PROCEDURE-SECTION SECTION.
ðð215ð FILL-TERMINAL-LIST.
143 ðð216ð READ TERMINAL-FILE RECORD INTO LIST-OF-TERMINALS(COUNTER)
ðð217ð AT END
144 ðð218ð SET END-OF-TERMINAL-LIST TO TRUE
145 ðð219ð SUBTRACT 1 FROM COUNTER
146 ðð22ðð MOVE COUNTER TO NO-OF-TERMINALS.
147 ðð221ð ADD 1 TO COUNTER.
ðð222ð
ðð223ð ACQUIRE-AND-INVITE-TERMINALS.
148 ðð224ð ACQUIRE LIST-OF-TERMINALS(COUNTER) FOR MULTIPLE-FILE. .11/
149 ðð225ð WRITE MULTIPLE-REC .12/
ðð226ð FORMAT IS "SIGNON"
ðð227ð TERMINAL IS LIST-OF-TERMINALS(COUNTER).
ðð228ð
ðð229ð POLL-TERMINALS.
15ð ðð23ðð READ MULTIPLE-FILE RECORD. .13/
151 ðð231ð IF MULTIPLE-FS2 EQUAL "31ð" THEN
152 ðð232ð SET NO-DATA-AVAILABLE TO TRUE. .14/
153 ðð233ð IF DATA-AVAILABLE THEN
154 ðð234ð MOVE MULTIPLE-DEVICE-NAME TO CURRENT-TERMINAL
155 ðð235ð PERFORM PASSWORD-VALIDATION. .15/
ðð236ð
ðð237ð PASSWORD-VALIDATION.
156 ðð238ð MOVE CURRENT-TERMINAL TO PASSKEY OF PASSWORD-REC.
157 ðð239ð READ PASSWORD-FILE RECORD.
158 ðð24ðð IF PASSWORD OF SIGNON-I EQUAL PASSWORD OF PASSWORD-REC THEN
159 ðð241ð CALL "UPDT" USING CURRENT-TERMINAL
16ð ðð242ð MOVE SPACES TO WRONG OF SIGNON-O
ðð243ð ELSE
161 ðð244ð MOVE "INVALID PASSWORD" TO WRONG OF SIGNON-O.
162 ðð245ð WRITE MULTIPLE-REC
ðð246ð FORMAT IS "SIGNON"
ðð247ð TERMINAL IS CURRENT-TERMINAL.
ðð248ð
ðð249ð DROP-TERMINALS.
163 ðð25ðð DROP LIST-OF-TERMINALS(COUNTER) FROM MULTIPLE-FILE. .16/
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 65 (Part 4 of 4). COBOL Source Listing for Multiple Device File Support

Device File Attributes


.1/ ATTR is the mnemonic-name associated with the function-name
ATTRIBUTE-DATA. ATTR is used in the ACCEPT statement to obtain attri-
bute data for the TRANSACTION file MULTIPLE-FILE. See item .9A/.
.2/ File MULT must have been created using the CRTDSPF command, where the
DEV parameter has a value of *NONE and the MAXDEV parameter has a
value greater than 1. The WAITRCD parameter specifies the wait time for
READ operations on the file. The WAITRCD parameter must have a value
greater than 0.
.3/ MULTIPLE-FS2 is the extended file status for the TRANSACTION file
MULTIPLE-FILE. This variable has been declared in the
WORKING-STORAGE section of the program. See item .7/.
.4/ MULTIPLE-CONTROL-AREA is the control area for the TRANSACTION file
MULTIPLE-FILE. This variable is used to determine which program device
was used to sign on. See item .15/.
.5/ The data description for MULTIPLE-REC has been defined using the COPY
DDS statement.
Note: Only the fields that are copied are named fields. Refer to the DDS of
this example for comments regarding the DDS used.

Chapter 8. Transaction Files 169


.6/ Format SIGNON is the format with the INVITE keyword. This is the format
that will be used to invite devices via the WRITE statement.
.7/ This is the declaration for the extended file-status MULTIPLE-FS2. It is a
4-byte field that is subdivided into a major return code (first 2 bytes) and a
minor return code (last 2 bytes).
.8/ STATION-ATTR is where the ACCEPT statement contains the attribute data
for the TRANSACTION file MULTIPLE-FILE. See item .9A/.
.9/ In this statement, the extended file status MULTIPLE-FS2 is being written.
.9A/ This is an example of accepting attribute-data for the TRANSACTION file
MULTIPLE-FILE. Because there is no interest in a specific program device,
but rather the last program device used, the FOR phrases are not used with
the ACCEPT.
.1ð/ This statement opens the TRANSACTION file MULTIPLE-FILE. Because the
ACQPGMDEV parameter of the CRTDSPF command has the value *NONE,
no program devices are implicitly acquired when this file is opened.
.11/ This statement acquires the program device contained in the variable
LIST-OF-TERMINALS (COUNTER), for the TRANSACTION file
MULTIPLE-FILE.
.12/ This WRITE statement is inviting the program device specified in the TER-
MINAL phrase. The format SIGNON has the DDS keyword INVITE associ-
ated with it. Refer to item .13/.
.13/ This READ statement will read from any invited program device. See item
.12/. If the wait time expires before anyone inputs to the invited devices, the
extended file status will be set to “0310” and processing will continue. See
item .14/.
.14/ In this statement, the extended file status for MULTIPLE-FILE is being
checked to see if the wait time expired.
.15/ The program device name stored in the control area is used to determine
which program device was used to sign on. See item .4/.
.16/ This DROP statement detaches the program device contained in the variable
LIST-OF-TERMINALS from the TRANSACTION file MULTIPLE-FILE.

170 COBOL/400 User’s Guide


Environment Division

File-Control Entry
The TRANSACTION file must be named by a file-control entry in the
FILE-CONTROL paragraph. This entry also specifies other information related to
the file.

Format

╔═══════════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ \ ┌───────────────────┐ \ ║
║ \ │ │ \ ║
║ \\6\\\\\\\\\\\\\\\\\\\│\\ ║
║ 55───SELECT──file-name────ASSIGN──┬────┬────┬─assignment-name-1─┼───────────────────────5 ║
║ └─TO─┘ └─literal-1─────────┘ ║
║ ║
║ ║
║ ║
║ ║
║ 5────┬───────────────────────┬──TRANSACTION─────────────────────────────────────────────5 ║
║ └──ORGANIZATION─┬────┬──┘ ║
║ └─IS─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────────────────────────────────────┬──5 ║
║ └──ACCESS──┬──────┬──┬────┬──┬─SEQUENTIAL───────────────────────────────────────┤ ║
║ └─MODE─┘ └─IS─┘ └─DYNAMIC───RELATIVE──┬─────┬──┬────┬──data-name-3─┘ ║
║ └─KEY─┘ └─IS─┘ ║
║ ║
║ 5────┬──────────────────────────────────────────────────────────┬───────────────────────5 ║
║ └─┬──────┬──STATUS─┬────┬──data-name-1──┬───────────────┬──┘ ║
║ └─FILE─┘ └─IS─┘ └──data-name-5──┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬────.──────────────────────────────────────5% ║
║ └──CONTROL-AREA──┬────┬──data-name-6──┘ ║
║ └─IS─┘ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════════════╝

Chapter 8. Transaction Files 171


ASSIGN Clause
The ASSIGN clause associates the TRANSACTION file with a display file or ICF
file through the use of assignment-name-1.

Assignment-name-1 has the following structure:

Format

55───ASSIGN──┬────┬─────WORKSTATION───── -file-name──┬───────┬───────────────5%
└─TO─┘ └─ ─SI─┘

Device specifies the type of device associated with the file. The value must be
WORKSTATION.

The AS/400 file name is a one-to-ten character external name of the display file or
ICF file specified on the create device file commands, CRTDSPF or CRTICFF.

The attribute -SI is used to specify the file level option for a separate indicator area.
See “Using Indicators with Transaction Files” on page 142 for further details.

The second and subsequent assignment-names are syntax-checked, but are


treated as documentation.

ORGANIZATION Clause
The ORGANIZATION clause specifies the logical structure of a file. TRANS-
ACTION organization signifies interaction between the program and either a work
station user or another system.

TRANSACTION Organization: TRANSACTION processing is defined as the


random arrival of a record from one of multiple possible sources followed by appro-
priate processing, and finally, by the output of results or feedback information of
some type to the source of the record.

In some cases, all records are homogeneous; that is, a logical transaction is com-
pleted with one exchange of records. In other situations, a series of records is
passed back and forth in a logical progression with various record types either
being selected by the initiator or as part of the processing based on input data
values.

Each transaction can be processed by a different program, or multiple transactions


can be processed by the same program, depending on the system environment.

The initiation of a transaction can cause a program to be scheduled to process the


transaction.

A transaction can consist of a series of alternating requests and responses (a


dialogue). Each request and response can consist of multiple logical records.

172 COBOL/400 User’s Guide


ACCESS MODE Clause
For files with TRANSACTION organization, the access mode can be SEQUENTIAL
or DYNAMIC.
Note: Dynamic processing is a method of reading from or writing to a file in a
nonsequential order and reading from a file in a sequential order with the
same OPEN statement.

When ACCESS IS SEQUENTIAL is specified or implied, the format name con-


tained in the format name field of the control area specifies which record was
accessed. When ACCESS IS SEQUENTIAL is specified for a TRANSACTION file,
do not specify the RELATIVE KEY data item.

When ACCESS IS DYNAMIC is specified, records in the file can be accessed


sequentially or randomly, depending on the form of the specific input/output
request. Random accessing of a TRANSACTION file is only valid if subfile proc-
essing is being performed. For subfile processing, you must specify ACCESS IS
DYNAMIC.

RELATIVE KEY Clause


The RELATIVE KEY clause specifies the relative record number for a specific
record in a subfile. The RELATIVE KEY data item, data-name-3, must be defined
as an unsigned integer and cannot be scaled. Also, the data item must not be
defined in a record description entry associated with the TRANSACTION file.

FILE STATUS Clause


Data-name-5 identifies the extended-file-status data item, which contains major and
minor return codes. These major and minor return codes can, in some cases, indi-
cate I/O errors when the file status code does not. After an I/O operation is per-
formed on an unopened file, the extended file status will have a value of zeros.

For more information about the FILE STATUS clause, refer to “File Status and
Feedback Areas” on page 103. General considerations about the FILE STATUS
clause and data-name-1 are described in Part 2 of the COBOL/400 Reference in
the section, “FILE STATUS Clause.”

For information about the role of file status in error handling, refer to Chapter 6,
“COBOL/400 Exception and Error Handling” on page 69.

Data-name-5 must be defined in the Data Division as a 4-byte alphanumeric data


item, and must not be defined in the File Section. The first 2 bytes of the
extended-file-status data item contain the major return code, and the second 2
bytes contain the minor return code. Return codes are moved into data-name-5
after any input or output operation (except the ACCEPT or CLOSE statement) on
the TRANSACTION file. The values placed in data-name-5 can also be accessed
by the ACCEPT statement using the I-O-FEEDBACK function-name. For more
information about the major and minor return codes, see the Data Management
Guide and the ICF Programmer’s Guide.

Chapter 8. Transaction Files 173


CONTROL-AREA Clause
The CONTROL-AREA clause specifies device-dependent and system-dependent
information that is used to control input/output operations for TRANSACTION files.

Data-name-6 is a CONTROL-AREA data item that must be defined in the LINKAGE


SECTION or WORKING-STORAGE SECTION. Data-name-6 is assumed to have
the following format:

01 data-name-6.
02 function-key PIC X(2).
(Function key feedback field)
02 device-name PIC X(10).
(Program device name)
02 record-format PIC X(10).
(Record format)

Data-name-6 must be 2, 12, or 22 characters long. Based upon the length of


data-name-6, the compiler assumes the availability of key feedback bytes, the
program device name, and record format.
Programming Note: For an ICF file, the actual name of a device may be different
from the program device name (data-name-11).

Information is moved into data-name-6 for each READ operation from a file that
has been assigned to a WORKSTATION device type. The information is valid only
if the READ operation is successfully completed (provided the wait time has not
expired). The information is in the fixed format as shown in the following example:
FILE-CONTROL.
SELECT SCREEN-FILE
ASSIGN TO WORKSTATION-MYFMTS
ORGANIZATION IS TRANSACTION
CONTROL-AREA IS
TRANSACTION-CONTROL-AREA.
..
.
WORKING-STORAGE SECTION.
ð1 TRANSACTION-CONTROL-AREA.
\ FEEDBACK ITEM
ð2 FUNCTION-KEY PIC XX.
ð2 TERMINAL-ID PIC X(1ð).
ð2 FORMAT-NAME PIC X(1ð).

174 COBOL/400 User’s Guide


Each field in the TRANSACTION-CONTROL-AREA data item in the example is
described as follows:
Ÿ FUNCTION-KEY: A two-digit number inserted in the field by the work station
interface that identifies the function key the operator pressed to initiate the
transaction. The codes are as follows:

00 Enter key
01-24 Function keys 1 through 24
90 Roll Up/Page Down key
91 Roll Down/Page Up key
92 Print key
93 Help key
94 Clear key
95 Home key
99 Undefined

Any function keys for which feedback information is desired must be defined for
the display file using DDS.
Ÿ TERMINAL-ID: The program device name.
Ÿ FORMAT-NAME: The DDS record format name that was referenced by the last
I/O statement run.

Data Division

File Description Entry


A file description entry consists of a level indicator (FD), a file name, and a series
of independent clauses. For a TRANSACTION file, the independent clauses
allowed are the RECORD CONTAINS clause, the LABEL RECORDS clause, and
the DATA RECORDS clause.

Chapter 8. Transaction Files 175


Format

╔═══════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───FD────file-name──────────────────────────────────────────────────────────5 ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────────────────────────────────────┬──5 ║
║ └──RECORD─┬──────────┬──┬─────────────────┬─integer-4──┬────────────┬─┘ ║
║ └─CONTAINS─┘ └──integer-3 TO───┘ └─CHARACTERS─┘ ║
║ ║
║ ║
║ 5────┬────────────────────────────────────────────────────┬───────────────────5 ║
║ │ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ │ ║
║ └────LABEL──┬──RECORD──┬────┬───┬──┬──STANDARD──┬────┘ ║
║ \ │ └─IS─┘ │ └──OMITTED───┘ \ ║
║ \ └──RECORDS─┬─────┬──┘ \ ║
║ \ └─ARE─┘ \ ║
║ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────────────────┬──.──────────────────5% ║
║ │ ┌───────────┐ │ ║
║ │ 6 │ │ ║
║ └──DATA──┬──RECORD──┬────┬───┬─────data-name-2─┴──┘ ║
║ │ └─IS─┘ │ ║
║ └──RECORDS─┬─────┬──┘ ║
║ └─ARE─┘ ║
║ ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════╝

The LABEL RECORDS clause specifies whether or not labels are present. This
clause is required in every file description entry. This clause is syntax-checked, but
is treated as documentation.

Boolean Data Items


The use of Boolean data and the use of indicators are described under “Data
Description Entry–Boolean Data” on page 144.

Procedure Division

Procedure Division Concepts


The COBOL/400 language provides a number of extensions to PROCEDURE
DIVISION statements to support TRANSACTION processing. The sections that
follow describe the statements involved and their usage.

176 COBOL/400 User’s Guide


ACCEPT Statement
The ACCEPT statement retrieves information (attribute data) about a particular
program device associated with a TRANSACTION file.

ACCEPT Statement – Format 6 – Attribute Data

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───ACCEPT────identifier-1────FROM────mnemonic-name──────────────────────────5 ║
║ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────────┬───────────────────5% ║
║ └──FOR──┬──identifier-2──┬──┬────────────────────┬──┘ ║
║ └──literal-1─────┘ └──FOR──file-name-1──┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

This format of the ACCEPT statement can only be used for files with an organiza-
tion of TRANSACTION. Mnemonic-name must be associated with the function-
name ATTRIBUTE-DATA in the SPECIAL-NAMES paragraph.

If file-name is not specified, the default file for the ACCEPT statement is the first
TRANSACTION file specified in a SELECT clause of the FILE-CONTROL para-
graph.

Literal-1 or the contents of identifier-2, if specified, indicates the program device


name for which attribute data is made available. This device must be defined by a
CRTDSPF, ADDICFDEVE, or OVRICFDEVE CL command. The device does not
actually have to be acquired. Literal-1, if specified, must be nonnumeric and 10
characters or fewer in length. The contents of identifier-2, if specified, must be an
alphanumeric data item 10 characters or fewer in length. If an incorrect program
device name is specified, or if the file is not open at the time the ACCEPT state-
ment is processed, message LBE7205
ACCEPT ATTRIBUTE-DATA statement has failed (C D F).
is issued and processing terminates.

If both FOR phrases are omitted (indicating the default TRANSACTION file is being
used), the ACCEPT statement uses the program device from which a READ,
WRITE, REWRITE, or ACCEPT (Attribute Data) operation on the default file was
most recently performed. If the only prior operation on the file was an OPEN, the
ACCEPT statement uses the program device implicitly acquired by the file when the
file was opened. When both FOR phrases are omitted, a program device must
have been acquired to use this particular format of the ACCEPT statement.

Program device attributes are moved into identifier-1 from the appropriate attribute
data format, according to the rules for a group MOVE without the CORRE-
SPONDING phrase.

Chapter 8. Transaction Files 177


You can make use of multiple display files along with ordinary files in a program
that includes an Extended ACCEPT or Extended DISPLAY statement. (See the
COBOL/400 Reference for more information.)

Attribute Data Formats


The attribute data retrieved by the ACCEPT statement has two different formats,
depending if the data is for a work station or for a communications device.

The ATTRIBUTE-DATA mnemonic name can be used only to obtain information


about a program device for a TRANSACTION file. Attribute data does not provide
information about the status of a completed or attempted I/O operation. To obtain
information about I/O operations, use the Format 3 ACCEPT statement with the
I-O-FEEDBACK or OPEN-FEEDBACK mnemonic names. For more information
about these mnemonic names, see the “SPECIAL NAMES Paragraph” section of
the COBOL/400 Reference.

ACQUIRE Statement
The ACQUIRE statement acquires a program device for a TRANSACTION file.

ACQUIRE Statement – TRANSACTION File

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───ACQUIRE──┬──identifier──┬──FOR──file-name──────────────────────────────5% ║
║ └──literal─────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

Literal or the contents of identifier indicates the program device name to be


acquired by the specified file. Literal, if specified, must be nonnumeric and 10
characters or fewer in length. Identifier, if specified, must refer to an alphanumeric
data item 10 characters or fewer in length.

File-name must be the name of a file with an organization of TRANSACTION, and


the file must be open when the ACQUIRE statement is run. A compilation error
message is issued if the organization is not TRANSACTION.

For a description of conditions that must be met before a communications device


can be acquired, see the ICF Programmer’s Guide. For more information about the
requirements for displays, see the Data Management Guide.

Successful completion of the ACQUIRE operation makes the program device avail-
able for input and output operations.

If the ACQUIRE operation is unsuccessful, the file status value is set to 9H and the
USE AFTER EXCEPTION/ERROR procedure is called (if specified). For more
information, refer to Chapter 6, “COBOL/400 Exception and Error Handling.”

Only one program device can be implicitly acquired when a file is opened. If a file
is an ICF file, the single implicitly acquired program device is determined by the
ACQPGMDEV parameter of the CRTICFF command. If the file is a display file, the

178 COBOL/400 User’s Guide


single implicitly acquired program device is determined by the first entry in the DEV
parameter of the CRTDSPF command. Additional program devices must be explic-
itly acquired.

A program device is explicitly acquired by using the ACQUIRE statement. For an


ICF file, that device must have been defined to the file with the ADDICFDEVE or
OVRICFDEVE CL command before the file was opened. For display files there is
no such requirement. That is, the device named in the ACQUIRE statement does
not have to be specified in the DEV parameter of the CRTDSPF command, the
CHGDSPF command, or the OVRDSPF command. For a display file, the program
device name must match the display device.

The ACQUIRE statement can also be used as an aid in recovering from I/O errors.
For more information, see the “ACQUIRE Statement” section of the COBOL/400
Reference.

For more information about these commands, see the CL Reference.

CLOSE Statement
The CLOSE statement terminates the processing of volumes and files, with optional
lock where applicable.

CLOSE Statement – Format 3 – TRANSACTION File

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ┌──────────────────────────────┐ ║
║ 6 │ ║
║ 55───CLOSE──file-name-1──┬─────────────────┼─────────────────────────────────5% ║
║ └──┬──────┬─LOCK──┘ ║
║ └─WITH─┘ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

For a detailed discussion of the CLOSE statement, see the “CLOSE Statement”
section of the COBOL/400 Reference.

DROP Statement
The DROP statement releases a program device that has been acquired by a
TRANSACTION file.

DROP Statement

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───DROP──┬─identifier─┬──FROM──file-name───────────────────────────────────5% ║
║ └─literal────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

Chapter 8. Transaction Files 179


Literal or the contents of identifier indicates the program device name of the device
to be dropped. Literal, if specified, must be nonnumeric and 10 characters or fewer
in length. Identifier, if specified, must refer to an alphanumeric data item, 10 char-
acters or fewer in length.

File-name must refer to a file with an organization of TRANSACTION, and the file
must be open to be used in the DROP statement. If no DROP statement is issued,
program devices attached to a TRANSACTION file are implicitly released when that
file is finally closed.

Program devices specified in a DROP statement must have been acquired by the
TRANSACTION file, either through an explicit ACQUIRE or through an implicit
ACQUIRE at OPEN time.

After successful running of the DROP statement, the program device is no longer
available for input or output operations through the TRANSACTION file. The
device can be reacquired if necessary. The contents of the record area associated
with a released program device are no longer available, even if the device is reac-
quired.

If the DROP operation is unsuccessful, the USE AFTER EXCEPTION/ERROR pro-


cedure is processed (if specified). For more information, refer to Chapter 6,
“COBOL/400 Exception and Error Handling.”

The DROP statement can also be used as an aid in recovering from I/O errors.
For more information, see the “DROP Statement” section of the COBOL/400
Reference.

OPEN Statement
The OPEN statement initiates the processing of files.

OPEN Statement – Format 3 – TRANSACTION Files

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ┌─────────┐ ║
║ 6 │ ║
║ 55───OPEN I-O──file-name─┴───────────────────────────────────────────────────5% ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

A TRANSACTION file must be opened in the I/O mode. For a further discussion of
the OPEN statement, see the COBOL/400 Reference.

The OPEN statement can cause a program device to be implicitly acquired for a
TRANSACTION file. For a further discussion about the acquiring of program
devices, see the “ACQUIRE Statement” on page 178.

180 COBOL/400 User’s Guide


Common Processing Facilities
The following discussion on FORMAT, INDICATORS, SUBFILE, and TERMINAL
phrases relates to the READ, REWRITE, and WRITE statements.

FORMAT Phrase
The literal or identifier specified must be a character string of 10 characters or
fewer in length.

Multiple data records, each with a different format, can be concurrently active for a
TRANSACTION file. If the FORMAT phrase is specified, it must specify a valid
format name that is defined to the system, and the I/O operation must be per-
formed on a data record of the same format. If the format is an invalid name or if it
does not exist, the FILE STATUS data item, if specified, is set to a value of 9K and
the contents of the record area are undefined.

DB-FORMAT-NAME Special Register: After the running of an input/output state-


ment for a TRANSACTION file, the DB-FORMAT-NAME special register is modified
according to the following rules:
Ÿ If the input/output operation is successful, the record format name is implicitly
moved to the special register after completion of the input/output operation.
Ÿ If the input/output operation is unsuccessful, DB-FORMAT-NAME contains the
record format name used in the last successful input/output operation.

When the FORMAT phrase is not specified, DB-FORMAT-NAME can be used if the
file contains a default record format name. The default value is always moved to
the DB-FORMAT-NAME special register.

DB-FORMAT-NAME is implicitly defined as PICTURE X(10).

INDICATORS Phrase
The identifier specified in the INDICATORS phrase must be either an elementary
Boolean data item specified without the OCCURS clause or a group item that has
elementary Boolean data items subordinate to it.

When a data record is written or rewritten, indicators can be written or rewritten


with it. The indicators can control how the record is displayed and the various data
management functions.

When a data record is read, indicators can be read with it. The indicators can be
used to pass information about the data record and how it was entered into your
program.

By defining a format using DDS, you determine what functions are to be controlled
by indicators, and which indicators control a particular function.

For detailed information on the INDICATORS phrase, refer to “Using Indicators with
Transaction Files” on page 142.

Chapter 8. Transaction Files 181


SUBFILE Phrase
When the SUBFILE phrase is specified, it indicates that all formats referenced by
the statement are subfiles. When SUBFILE is not specified in a TRANSACTION
I/O statement, it indicates that none of the formats referenced by the statement are
subfiles. This information is not verified at compilation time. If it is specified incor-
rectly, the subfile is processed as a series of input/output operations directly to the
display device. When the specified format name exists as a display file format, the
READ/WRITE operations complete successfully.

When SUBFILE is not specified, the RELATIVE KEY data item associated with the
file, if specified, is not referenced or changed by the I/O operation.

When SUBFILE is specified, a RELATIVE KEY data item must be defined for the
file. Its value is referenced, and sometimes changed, by the I/O operation. See
each of the statements associated with SUBFILE operations for a detailed
description of when and how the RELATIVE KEY data item is changed.

The SUBFILE phrase can be specified only for display files.

TERMINAL Phrase
When the TERMINAL phrase is specified, it indicates a specific program device is
to be used for a READ, WRITE, or REWRITE operation on a TRANSACTION file.

The TERMINAL phrase can be omitted for I/O operations on single device files,
because that device is always used.

If the TERMINAL phrase is omitted for an I/O operation on a TRANSACTION file


that has acquired multiple program devices, the program device that last attempted
a READ, WRITE, REWRITE, ACQUIRE, DROP, or ACCEPT (Attribute Data) oper-
ation on the file is used. If the only prior operation on the file was an OPEN, the
default program device used is the program device implicitly acquired by the
TRANSACTION file when the file was opened. A run-time error message occurs if
no program device has been acquired when the file is opened.

For a READ statement with both the TERMINAL phrase and the NO DATA phrase
specified, the imperative-statement in the NO DATA phrase is run only if data is not
immediately available from the program device specified by the TERMINAL phrase.

If the TERMINAL phrase is specified and the data-item or literal has a value of
blanks, the phrase is treated at run time as if it were not specified.

READ Statement
The READ statement makes available a record from a device, using a named
format. If the format is a subfile, the READ statement makes available a specified
record from that subfile.

182 COBOL/400 User’s Guide


READ Statement – Format 4 – TRANSACTION File (Nonsubfile)

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───READ──file-name──┬────────┬──────────────────────────────────────────────5 ║
║ └─RECORD─┘ ║
║ ║
║ 5────┬──────────────────────┬─────────────────────────────────────────────────5 ║
║ └──INTO──identifier-1──┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────┬────────────────────────────────────5 ║
║ └──FORMAT─┬────┬──┬─identifier-2─┬──┘ ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬──────────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────┬────────────────────────────────────5 ║
║ └──NO DATA──imperative-statement-1──┘ ║
║ ║
║ ║
║ 5────┬────────────────────────────────────┬───────────────────────────────────5 ║
║ └─┬────┬─END──imperative-statement-2─┘ ║
║ └─AT─┘ ║
║ ║
║ ║
║ 5────┬──────────────────────────────────────────┬──┬──────────┬──────────────5% ║
║ └──NOT─┬────┬─END──imperative-statement-3──┘ └─END-READ─┘ ║
║ └─AT─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

Format 4 is used only to read a format that is not a subfile. The RELATIVE KEY
data item, if specified in the FILE-CONTROL entry, is not used. The Format 4
READ statement is not valid for a subfile record. However, a Format 4 READ
statement for the subfile control record format must be used to place those subfile
records that were updated on a display into the subfile.

If the requested data is available, it is returned in the record area. The names of
the record format and the program device are returned in the I-O-FEEDBACK area
in the CONTROL-AREA.

The READ statement is valid only when there are acquired devices for the file. If a
READ is processed and there are no acquired devices, the file status is set to 92
(logic error).

Chapter 8. Transaction Files 183


The manner in which the Format 4 READ statement functions depends on:
Ÿ If the READ is for a single device file or a multiple device file
Ÿ If a specific program device has been requested through the TERMINAL
phrase
Ÿ If a specific record format has been requested through the FORMAT phrase
Ÿ If the NO DATA phrase has been specified.

In the following sections, references to data available or returned include the situ-
ation where only the response indicators are set. This also applies even when a
separate indicator area is used and the indicators are not returned in the record
area for the file.

The following chart shows the possible combinations of phrases and the function
performed for a single device file or a multiple device file. For example, if
TERMINAL is N, FORMAT is N, and NO DATA is N, the single device is D and
multiple device is A.

Function Phrase Y=Yes N=No


Checked at Com- TERMINAL2 NNNNYYYY
pilation FORMAT2 NNYYNNYY
NO DATA NYNYNYNY
Determined at Single Device DCDBDCDB
Run Time Multiple Device AADBDCDB

Codes A through D are explained below:

Code A–Read From Invited Program Device (Multiple Device Files only)

This type of READ receives data from the first invited program device that has data
available. Invited program devices are work stations or other communication
devices that are invited to send input. The inviting is done by writing to the
program device with a format specifying the DDS keyword INVITE. Once an invited
program device is actually read from, it is no longer invited. That program device
will not be used for input by another READ statement unless reinvited, or unless a
READ is directed to it specifying the TERMINAL phrase or FORMAT phrase.

The record format returned from the program device is determined by the system.
See the chapter on display device support in the Data Management Guide for infor-
mation on how record format is determined for work stations. See the ICF
Programmer’s Guide for information on the FMTSLT parameter on the
ADDICFDEVE and OVRICFDEVE commands.

This READ can be completed without returning any data in the following cases:
Ÿ If there are no invited devices.
Ÿ If a controlled cancelation of the job occurs. This results in a file status value
of 9A and a major/minor return code value of 0309.

2 If the phrase is specified and the data item or literal is blank, the phrase is treated at run time as if it were not specified.

184 COBOL/400 User’s Guide


Ÿ If the NO DATA phrase is omitted, and the specified wait time expires. This
results in a file status value of 00 and a major/minor return code value of 0310.
Ÿ If the specified wait time is the value entered on the WAITRCD parameter for
the file.
Ÿ If the NO DATA phrase is specified, and no data is immediately available when
the READ is processed.

If data is available, it is returned in the record area. The record format is returned
in the I-O-FEEDBACK area and in the CONTROL-AREA. For more information
about “Reading from Invited Program Devices,” see the ICF Programmer’s Guide.

Code B–Read From One Program Device (Combination not Allowed)

A compilation-time message is issued, and the NO DATA phrase is ignored. See


the table entry for the same combination of phrases with the NO DATA phrase
omitted.

Code C–Read From One Program Device (with NO DATA phrase)

This function of the READ statement never causes program processing to stop and
wait until data is available. Either the data is immediately available or the NO
DATA imperative-statement is processed.

This READ function can be used to periodically check if data is available from a
particular program device (either the default program device or one specified by the
TERMINAL phrase). This checking for data is done in the following manner:
1. The program device is determined as follows:
a. If the TERMINAL phrase was omitted or contains blanks, the default
program device is used. The default program device is the one used by
the last attempted READ, WRITE, REWRITE, ACQUIRE, or DROP state-
ment. If none of the above I/O operations were previously issued, the
default program device is the first program device acquired.
b. If the TERMINAL phrase was specified, the indicated program device is
used.
2. A check is done to determine if data is available and if the program device is
invited.
3. If data is available, that data is returned in the record area and the program
device is no longer invited. If no data is immediately available, the NO DATA
imperative-statement is run and the program device remains invited.
4. If the program device is not invited, the AT END condition exists and the file
status is set to 10.

Code D–Read From One Program Device (without NO DATA Phrase)

This READ always waits for data to be made available. Even if the job receives a
controlled cancellation, or a WAITRCD time is specified for the file, the program will
never regain control from the READ statement. This READ operation is performed
in the following manner:

Chapter 8. Transaction Files 185


1. The program device is determined as follows:
a. If the TERMINAL phrase is omitted or contains a blank value, the default
program device is used. The default program device is the program device
used by the last attempted READ, WRITE, REWRITE, ACQUIRE, DROP or
ACCEPT (Attribute Data) statement. If none of these operations has been
done, the program device implicitly acquired when the file was opened is
used. If there are no acquired devices, the AT END condition exists.
b. If the TERMINAL phrase is specified, the indicated program device is used.
2. The record format is determined as follows:
a. If the FORMAT phrase is omitted or contains blanks, the record format
returned is determined by the system. For information on how the record
format is calculated for work station devices, refer to the Data Management
Guide. For information about how the record format is determined for com-
munications, see the section on the FMTSLT parameter on the
ADDICFDEVE and OVRICFDEVE commands in the ICF Programmer’s
Guide.
b. If the FORMAT phrase is specified, the indicated record format is returned.
If the data available does not match the requested record format, a file
status of 9G is set.
3. Program processing stops until data becomes available. The data is returned
in the record area after the READ statement is run. If the program device was
previously invited, it will no longer be invited after this READ statement.

INTO Phrase
The INTO phrase can be specified if:
Ÿ Only one record description is subordinate to the file description entry,
OR
Ÿ All record names associated with file-name and the data item referenced by
identifier-1 describe a group item or an elementary alphanumeric item.

FORMAT Phrase
Literal-1 or identifier-2 specifies the name of the record format to be read. Literal-1,
if specified, must be nonnumeric and 10 characters or fewer in length. Identifier-2,
if specified, must refer to an alphanumeric data item, 10 characters or fewer in
length. If identifier-2 contains blanks, the READ statement is run as if the FORMAT
phrase were omitted.

NO DATA Phrase
When the NO DATA phrase is specified, the READ statement determines if data is
immediately available. If data is available, the data is returned in the record area.
If no data is immediately available, imperative-statement-1 is processed. The NO
DATA phrase prevents the READ statement from waiting for data to become avail-
able.

186 COBOL/400 User’s Guide


TERMINAL Phrase
Literal-2 or identifier-3 specifies the program device name. Literal-2, if specified,
must be nonnumeric and 10 characters or fewer in length. Identifier-3, if specified,
must refer to an alphanumeric data item, 10 characters or fewer in length. The
program device must have been acquired before the READ statement is processed.
If identifier-3 contains blanks, the READ statement is processed as if the TER-
MINAL phrase were omitted. For a single device file, the TERMINAL phrase can
be omitted. The program device is assumed to be that single device.

If the TERMINAL phrase is omitted for a READ of a TRANSACTION file that has
acquired multiple program devices, the default program device is used. See the
discussion of the TERMINAL phrase on page 182, to see how the default program
device is determined.

AT END Phrase
Imperative-statement-2 is performed when the AT END condition is detected.
Note: An AT END condition occurs at the following times:
Ÿ During a READ statement for a sequentially accessed file when no next logical
record exists in the file, or when the number of significant digits in the relative
record number is larger than the size of the relative key data item, or when an
optional input file is not present.
Ÿ During a RETURN statement when no logical record exists for the associated
sort or merge file.
Ÿ During a SEARCH statement when the search operation ends without satisfying
the condition specified in any of the associated WHEN phrases.

NOT AT END Phrase


This phrase allows you to specify procedures to be performed when the READ
operation is successful.

END-READ Phrase
The END-READ phrase serves to explicitly delimit the scope of the statement.

Chapter 8. Transaction Files 187


READ Statement – Format 5 – TRANSACTION File (Subfile)

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───READ SUBFILE──file-name──────────────────────────────────────────────────5 ║
║ ║
║ ║
║ 5────┬────────────────────┬──┬────────┬───────────────────────────────────────5 ║
║ └─┬──────┬─MODIFIED──┘ └─RECORD─┘ ║
║ └─NEXT─┘ ║
║ ║
║ 5────┬──────────────────────┬─────────────────────────────────────────────────5 ║
║ └──INTO──identifier-1──┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────┬────────────────────────────────────5 ║
║ └──FORMAT─┬────┬──┬─identifier-2─┬──┘ ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────TERMINAL─┬────┬──┬─identifier-3─┬────────────────────────────────────────5 ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────┬────────────────────────────5 ║
║ └──INVALID─┬─────┬──imperative-statement-1──┘ ║
║ └─KEY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬────────────────────────5 ║
║ └──NOT INVALID─┬─────┬──imperative-statement-2──┘ ║
║ └─KEY─┘ ║
║ ║
║ 5────┬────────────────────────────────────┬───────────────────────────────────5 ║
║ └─┬────┬─END──imperative-statement-3─┘ ║
║ └─AT─┘ ║
║ ║
║ ║
║ 5────┬──────────────────────────────────────────┬──┬──────────┬──────────────5% ║
║ └──NOT─┬────┬─END──imperative-statement-4──┘ └─END-READ─┘ ║
║ └─AT─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

Format 5 is used only to read a format that is a subfile record. The AT END
phrase can only be used when the NEXT MODIFIED phrase is specified. The
INVALID KEY phrase must not be used when the NEXT MODIFIED phrase is spec-
ified.

188 COBOL/400 User’s Guide


Format 5 cannot be used for communications devices. If the subfile format of the
READ statement is used for a communications device, the READ fails and a file
status of 90 is set.

Random Access of Subfile Records: The NEXT MODIFIED phrase must not be
used to randomly access records in a subfile. The INVALID KEY phrase can only
be used for random access of subfile records.

Sequential Access of Subfile Records: The NEXT MODIFIED phrase must be


specified to access subfile records sequentially. The AT END phrase can only be
specified with the NEXT MODIFIED phrase.

NEXT MODIFIED Phrase


When NEXT MODIFIED is not specified, the data record made available is the
record in the subfile with a relative record number that corresponds to the value of
the RELATIVE KEY data item.

When the NEXT MODIFIED phrase is not specified, and if the RELATIVE KEY data
item contains a value other than the relative record number of a record in the
subfile, the INVALID KEY condition exists and the running of the READ statement
is unsuccessful.

When the NEXT MODIFIED phrase is specified, the record made available is the
next modified record following the current pointer position in the file. For informa-
tion about turning on the Modified Data Tag, see the Data Management Guide.

The search for the next modified record begins:


Ÿ At the beginning of the subfile if:
– An I/O operation has been performed for the subfile control record.
– The I/O operation cleared, initialized, or displayed the subfile.
Ÿ For all other cases, with the record following the record that was read by a
previous read operation.

The value of the RELATIVE KEY data item is updated to reflect the relative record
number of the record made available to the program.

If NEXT MODIFIED is specified and there are no further user-modified records in


the subfile, the AT END condition exists. Imperative-statement-2, or an applicable
USE AFTER ERROR/EXCEPTION procedure, if any, is then run.

FORMAT Phrase
When a format-name is not specified, the format used is the last record format
written to the display device that contains input fields, input/output fields, or hidden
fields. If no such format exists for the display file, the format used is the record
format of the last WRITE operation to the display device.
Note: An input field is a field specified in a display file or database file that is
reserved for information supplied by a user.

If the FORMAT phrase is specified, literal-1 or the contents of identifier-2 must


specify a format, which is active for the appropriate program device. The READ
statement reads a data record of the specified format.

Chapter 8. Transaction Files 189


To ensure correct results, always specify the FORMAT phrase for multiple format
files. For more information on the FORMAT phrase, see the Procedure Division,
“Common Processing Facilities” on page 181.

TERMINAL Phrase
See Format 4 of the READ Statement for general considerations concerning the
TERMINAL phrase.

For a Format 5 READ, if the TERMINAL phrase is omitted for a file that has mul-
tiple devices acquired for it, a record is read from the subfile associated with the
default program device. See the discussion of the TERMINAL phrase on page 182,
to see how the default program device is determined.

INVALID KEY Phrase


If the RELATIVE KEY data item at the time of running the statement contains a
value that does not correspond to a relative record number for the subfile, the
INVALID KEY condition exists and the running of the statement is unsuccessful.
To see what happens next, refer to the diagrams on pages 76 through 78.

| For a Format 5 READ, you should specify the INVALID KEY phrase if the NEXT
MODIFIED phrase is not specified and there is no applicable USE procedure speci-
fied for the file name.

NOT INVALID KEY Phrase


This phrase allows you to specify procedures to be performed when the READ
operation is successful.

AT END Phrase
If the NEXT MODIFIED phrase is specified and there is no user-modified record in
the subfile, the AT END condition exists, and the READ operation is unsuccessful.

Specify the AT END phrase when the NEXT MODIFIED phrase is used, and no
applicable USE procedure is specified for the file name. If the AT END phrase and
a USE procedure are both specified for a file, and the AT END condition arises,
control transfers to the AT END imperative statement and the USE procedure is not
run.

NOT AT END Phrase


This phrase allows you to specify procedures to be performed when the READ
operation is successful.

END-READ Phrase
The END-READ phrase serves to explicitly delimit the scope of the statement.

190 COBOL/400 User’s Guide


REWRITE Statement
The REWRITE statement is used to replace a subfile record that already exists in
the subfile.

REWRITE Statement – Format 2 – TRANSACTION File (Subfile)

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───REWRITE SUBFILE──record-name-1─┬──────────────────────┬────────────────5 ║
║ └──FROM──identifier-1──┘ ║
║ ║
║ ║
║ 5───FORMAT─┬────┬──┬─identifier-2─┬───────────────────────────────────────────5 ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬──────────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬────────────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────┬────────────────────────────5 ║
║ └──INVALID─┬─────┬──imperative-statement-1──┘ ║
║ └─KEY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬─┬─────────────┬───────5% ║
║ └──NOT INVALID─┬─────┬──imperative-statement-2──┘ └─END-REWRITE─┘ ║
║ └─KEY─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

The number of character positions in the record referenced by record-name must


be equal to the number of character positions in the record being replaced. A suc-
cessful READ operation on the record must be done prior to the REWRITE opera-
tion. The record replaced in the subfile is the record in the subfile accessed by the
previous READ operation.

FORMAT Phrase
The record format specified in the FORMAT phrase must be the record format
accessed on the previous READ operation. Literal-1 or the contents of identifier-2
must be the name of the subfile format accessed on the previous READ. For more
information on the FORMAT phrase, see “Common Processing Facilities” on
page 181.

Chapter 8. Transaction Files 191


TERMINAL Phrase
The TERMINAL phrase indicates which program device’s subfile is to have a record
rewritten. If the TERMINAL phrase is specified, literal-2 or identifier-3 must refer to
a work station that has been acquired by the TRANSACTION file. If literal-2 or
identifier-3 contains blanks, the TERMINAL phrase has no effect. The program
device specified by the TERMINAL phrase must have been acquired, either explic-
itly or implicitly, and must have a subfile associated with the device.

Literal-2 or identifier-3 must be a valid program device name. Literal-2, if specified,


must be nonnumeric and 10 characters or fewer. Identifier-3, if specified, must
refer to an alphanumeric data item, 10 characters or fewer.

If the TERMINAL phrase is omitted from a TRANSACTION file that has acquired
multiple program devices, the subfile used is the subfile associated with the last
program device from which a READ of the TRANSACTION file was attempted.

The REWRITE statement cannot be used for communications devices. If the


REWRITE statement is used for a communications device, the operation fails and a
file status of 90 is set.

INVALID KEY Phrase


If the RELATIVE KEY data item at the time of running the statement contains a
value that does not correspond to a relative record number for the subfile, the
INVALID KEY condition exists and the running of the statement is unsuccessful.
To see what happens next, refer to the diagrams on pages 76 through 78.

NOT INVALID KEY Phrase


This phrase allows you to specify procedures to be performed when the REWRITE
operation is successful.

END-REWRITE Phrase
The END-REWRITE phrase serves to explicitly delimit the scope of the statement.

192 COBOL/400 User’s Guide


WRITE Statement
The WRITE statement releases a logical record to the file.

WRITE Statement – Format 4 – TRANSACTION File (Nonsubfile)

╔═════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───WRITE──record-name-1──┬────────────────────┬─────────────────────────────5 ║
║ └─FROM──identifier-1─┘ ║
║ ║
║ ║
║ 5────FORMAT─┬────┬──┬─identifier-2─┬──────────────────────────────────────────5 ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ 5────┬─────────────────────────────────────┬──────────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬────────────────────────5 ║
║ └──STARTING─┬────┬──┬──────┬──┬─identifier-4─┬──┘ ║
║ └─AT─┘ └─LINE─┘ └─literal-3────┘ ║
║ ║
║ ║
║ 5────┬────────────────────────────────────────────────────────────────────────5 ± ║
║ └──┬─BEFORE─┬──ROLLING──┬───────┬──┬─identifier-5─┬──────────────────────5 ² ║
║ └─AFTER──┘ ├─LINES─┤ └─literal-4────┘ ║
║ └─LINE──┘ ║
║ ║
║ ║
║ ± 5──────────────────────────────────────────────────────────────────────────┬──5 ║
║ ² 5────┬─────────┬──┬─identifier-6─┬──┬─UP───┬──┬─identifier-7─┬──┬───────┬──┘ ║
║ ├─THROUGH─┤ └─literal-5────┘ └─DOWN─┘ └─literal-6────┘ ├─LINES─┤ ║
║ └─THRU────┘ └─LINE──┘ ║
║ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬──┬───────────┬────────────────5% ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-8─┘ └─END-WRITE─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════════╝

TERMINAL Phrase
The TERMINAL phrase specifies the program devices to which the output record is
to be sent.

The contents of literal-2 or identifier-3 must be the name of a program device previ-
ously acquired, either implicitly or explicitly, by the file. Literal-2, if specified, must
be nonnumeric and 10 characters or fewer in length. Identifier-3, if specified, must
refer to an alphanumeric data item, 10 characters or fewer in length. A value of
blanks is treated as if the TERMINAL phrase were omitted.

If only a single program device was acquired by the TRANSACTION file, the

Chapter 8. Transaction Files 193


TERMINAL phrase can be omitted. That program device is always used for the
WRITE.

If the TERMINAL phrase is omitted for a WRITE operation to a TRANSACTION file


that has acquired multiple program devices, the default program device is used.
See the discussion of the TERMINAL phrase on page 182 to see how the default
program device is determined.

STARTING Phrase
The STARTING phrase specifies the starting line number for the record formats
that use the variable start line keyword. This phrase is only valid for display
devices.

The actual line number on which a field begins can be determined from the fol-
lowing equation:

Actual-line = Start-line + DDS Start-line − 1

Figure 66. Line Number Equation for the STARTING Phrase

Where:
Actual-line is the actual line number
Start-line is the starting line number specified in the program
DDS Start-line is the line number specified in positions 39 through 41 of the
Data Description Specifications form.

The WRITE operation is successful if:


Ÿ The result of the above equation is positive and less than or equal to the
number of lines on the display.
Ÿ The value specified for the STARTING phrase is 0. In this case, a value of 1 is
assumed.

The WRITE operation is unsuccessful, and the program ends, if:


Ÿ The result of the above equation is greater than the number of lines on the
display.
Ÿ The value specified for the STARTING phrase is negative.

If the value specified for the STARTING phrase is within the screen area, any fields
outside of the screen area are ignored.

Literal-3 of the STARTING phrase must be a numeric literal. Identifier-4 must be


an elementary numeric item.

To use the STARTING phrase, the DDS record level keyword SLNO(*VAR) must
be specified for the format being written. If the record format does not specify this
keyword, the STARTING phrase is ignored at run time.

The DDS keyword CLRL also affects the STARTING phrase. CLRL controls how
much of the display is cleared when the WRITE statement is processed.

194 COBOL/400 User’s Guide


See the DDS Reference for further information on SLNO(*VAR) and CLRL
keywords.

ROLLING Phrase
The ROLLING phrase allows you to move lines displayed on the work station
screen. All or some of the lines on the screen can be rolled up or down. The lines
vacated by the rolled lines are cleared, and can have another screen format written
into them. This phrase is only valid for display devices.

ROLLING is specified in the WRITE statement that is writing a new format to the
display You must specify whether the write is before or after the roll, the range of
lines you want to roll, how many lines you want to roll these lines, and whether the
roll operation is up or down.

After lines are rolled, the fields on these lines retain their DDS display attributes, for
example, underlining, but lose their DDS usage attributes, for example, input-
capability. Fields on lines that are written and then rolled (BEFORE ROLLING
phrase) also lose their usage attributes.

If any part of a format is rolled, the entire format loses its usage attributes. If more
than one format exists, only the rolled formats lose their usage attributes.

When you specify the ROLLING phrase, the following general rules apply.
Ÿ The DDS record level keyword ALWROL must be specified for every record
format written in a WRITE statement containing the ROLLING phrase.
Ÿ Other DDS keywords mutually exclusive with the ALWROL keyword must not
be used.
Ÿ Either of the DDS keywords, CLRL or OVERLAY, must be specified for a
record format that is to be written and rolled to prevent the display from being
cleared when that record format is written. See the DDS Reference manual for
more information on DDS keywords.
Ÿ All the identifiers and literals must represent positive integer values.
Ÿ The roll starting line number (identifier-5 or literal-4) must not exceed the
ending line number (identifier-6 or literal-5).
Ÿ The contents of lines that are rolled outside of the window specified by the
starting and ending line numbers disappear.

Figure 67 on page 197 shows an example of a rolling operation. An initial screen


format, FMT1, is written on the display. The program processes this screen format
and is now ready to write the next screen format, FMT2, to the work station screen.
Part of FMT1 is rolled down two lines before FMT2 is written to the display.

Processing of the following WRITE statement causes part of FMT1 to be rolled


down two lines, and FMT2 to be written to the display:
WRITE SCREENREC FORMAT "FMT2"
AFTER ROLLING LINES 14 THROUGH 2ð
DOWN 2 LINES

When this WRITE statement is run, the following steps occur:


1. The contents of lines 14 through 20 are rolled down two lines.

Chapter 8. Transaction Files 195


a. The contents of lines 14 through 18 now appear on lines 16 through 20.
b. The contents of lines 14 and 15 are vacated and cleared.
c. The contents of lines 19 and 20 are rolled outside the window and disap-
pear.
2. After the rolling operation takes place, FMT2 is written to the display.
a. Part of FMT2 is written to the area vacated by the roll operation.
b. Part of FMT2 is written over the data left from FMT1.
3. When the contents of the display are returned to the program by a READ state-
ment, only the input capable fields of FMT2 are returned.

196 COBOL/400 User’s Guide


DISPLAY BEFORE PROCESSING THE WRITE STATEMENT

┌─────────────────────────────────────────────────────────────────────┐
│ │
│ UPDATE CUSTOMER ORDER RECORD │ Line 3
│ │
│ │
│ TO END THIS JOB, PRESS F7 │ Line 8
│ │
│ │
│ ENTER YOUR OPERATOR NUMBER: ___ │ Line 13
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┐
│ │ Line 14 │
│ ENTER CUSTOMER NUMBER: _____ │ Line 15 │
│ │ │
│ PRESS F3 TO DISPLAY OPTION MENU │ Line 17 ├───┐
│ │ │ │
│ │ │ │
│ │ Line 2ð │ │
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┘ │
│ │ │
│ │ ┌─────────┘
└─────────────────────────────────────────────────────────────────────┘ │

│ These seven lines
DISPLAY AFTER PROCESSING THE WRITE STATEMENT └5of FMT1 will be
rolled down 2
┌─────────────────────────────────────────────────────────────────────┐ lines.
│ │
│ UPDATE CUSTOMER ORDER RECORD │ Line 3
│ │
│ │
│ TO END THIS JOB, PRESS F7 │ Line 8
│ │
│ │
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┐
│ ITEM NUMBER ORDERED: _____ │ Line 12 │
│ │ ├─┐
│ QUANTITY ORDERED: ______ │ Line 14 │ │
│ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── %┘ │
│ │ │
│ ENTER CUSTOMER NUMBER: XXXXX │ Line 17 │
│ │ │
│ PRESS F3 TO DISPLAY OPTION MENU │ Line 19 │
│ │ │
│ │ ┌───────┘
│ │ │
└─────────────────────────────────────────────────────────────────────┘ │
│ These three lines
└5of FMT2 have been
written over the
previous lines.

Figure 67. Example of ROLLING Operation

Chapter 8. Transaction Files 197


WRITE Statement – Format 5 – TRANSACTION File (Subfile)

╔════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───WRITE SUBFILE──record-name-1──┬──────────────────────┬─────────────5 ║
║ └──FROM──identifier-1──┘ ║
║ ║
║ ║
║ 5────FORMAT─┬────┬──┬─identifier-2─┬────────────────────────────────────5 ║
║ └─IS─┘ └─literal-1────┘ ║
║ ║
║ ║
║ 5────┬─────────────────────────────────────┬────────────────────────────5 ║
║ └──TERMINAL─┬────┬──┬─identifier-3─┬──┘ ║
║ └─IS─┘ └─literal-2────┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────┬──────────────────────────5 ║
║ └─┬─INDICATOR──┬──┬─────┬──identifier-4─┘ ║
║ ├─INDICATORS─┤ ├─IS──┤ ║
║ └─INDIC──────┘ └─ARE─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────┬──────────────────────5 ║
║ └──INVALID─┬─────┬──imperative-statement-1──┘ ║
║ └─KEY─┘ ║
║ ║
║ ║
║ 5────┬───────────────────────────────────────────────┬─┬───────────┬────5% ║
║ └──NOT INVALID─┬─────┬──imperative-statement-2──┘ └─END-WRITE─┘ ║
║ └─KEY─┘ ║
║ ║
╚════════════════════════════════════════════════════════════════════════════╝

Format 5 can only be used for display devices. If the subfile form of the WRITE
statement is used for any other type of device, the WRITE operation fails and a file
status of 90 is set.

If the format is a subfile record, and SUBFILE is specified, the RELATIVE KEY
clause must have been specified on the SELECT clause for the file being written.
The record written to the subfile is the record in the subfile identified by the format
name that has a relative record number equal to the value of the RELATIVE KEY
data item. See the Data Management Guide for more information on subfiles.

TERMINAL Phrase
See the explanation following Format 4 for general considerations concerning the
TERMINAL phrase.

The TERMINAL phrase specifies which program device’s subfile is to have a record
written to it. If the TERMINAL phrase is specified, literal-2 or identifier-3 must refer
to a work station associated with the TRANSACTION file. If literal-2 or identifier-3
contains a value of blanks, the TERMINAL phrase is treated as if it were not speci-
fied. The work station specified by the TERMINAL phrase must have been
acquired, either explicitly or implicitly.

198 COBOL/400 User’s Guide


If the TERMINAL phrase is omitted, the subfile used is the subfile associated with
the default program device. See the discussion of the TERMINAL phrase on page
182 to see how the default program device is determined.

INVALID KEY Phrase


The INVALID KEY condition exists if a record is already in the subfile with that
record number, or if the relative record number specified is greater than the
maximum allowable subfile record number. The INVALID KEY phrase should be
specified in the WRITE SUBFILE statement for all files for which an appropriate
USE procedure is not specified.

For information about what happens when the INVALID KEY condition arises, refer
to the diagrams on pages 76 through 78.

NOT INVALID KEY Phrase


This phrase allows you to specify procedures to be performed when the WRITE
operation is successful.

END-WRITE Phrase
The END-WRITE phrase serves to explicitly delimit the scope of the statement.

For a further discussion of the WRITE statement, the FROM phrase, and the
INVALID KEY phrase, see the COBOL/400 Reference. For information on the
FORMAT phrase, see the Procedure Division, “Common Processing Facilities” on
page 181.

USE Statement
The USE statement specifies procedures for input/output error handling that are in
addition to the standard procedures provided by the input/output control system.

Format

╔═════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ 55───USE AFTER──┬──────────┬──┬─EXCEPTION─┬───────────────────────────────────5 ║
║ └─STANDARD─┘ └─ERROR─────┘ ║
║ ║
║ ║
║ ║
║ ┌───────────┐ ║
║ 6 │ ║
║ 5────PROCEDURE──┬────┬────┬────file-name-1─┴──┬──────────────────────────────5% ║
║ └─ON─┘ └────I-O────────────┘ ║
║ ║
╚═════════════════════════════════════════════════════════════════════════════════╝

See the “USE Statement” section of the COBOL/400 Reference for a further dis-
cussion of the USE statement.

Chapter 8. Transaction Files 199


Examples of Work Station Programs
This section contains examples of COBOL programs that illustrate work station
applications on the AS/400 system.

Basic Inquiry Program


Figure 68 shows the associated DDS for a basic inquiry program that uses the
COBOL TRANSACTION file.

AS/400 DATA DESCRIPTION SPECIFICATIONS GX 2 1 - 9 8 9 1 - 0 U M/ 0 5 0 *


Pr i nt ed i n U. S . A.
I nt er nat i onal Busi ness Machi nes *Number of sheets per pad may vary slightl y.

Fi le Keying Graphic Description Page of


Instruction
Programmer Date Key
Type of Name of Spec /(b/R/H/J/K/S/O)

Conditioning

Location

/B/ H/M/N/P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift

Condition Name

Name Length Functions


Usage (b/O/I

Sequence
Reference (R)

Number
Form Type

Posi t i ons
Indicator

Reserved
Indicator

Indicator

/
Decimal
Not (N)

Not (N)
Not (N)

Line Pos

1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 16 1 7 1 8 1 9 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0

A * CU S T OME R MAS T E R I NQU I R Y F I L E - - CU SMI NQ


A*
A R E F ( CU SMS T P )
A R CU S PMT T E X T ( ' CU S T OME R P ROMP T ' )
A CA0 3 ( 1 5 ' E ND OF P ROGRAM ' )
A 1 3 ' CU S T OME R MAS T E R I NQU I R Y '
A 3 3 ' CU S T OME R NUMB E R '
A CU S T R I 3 2 /0
A 99 E R RMSG( ' CU S T OME R NUMB E R NOT F OUND +
A P R E S S R E S E T , T HE N E N T E R VAL I D NUMB E +
A R ' 99 )
A 5 3 ' U S E F 3 T O E ND P ROGR AM, U S E E N T E R +
A T O R E T UR N T O P ROMP T SCR E E N '
A R CU S F L D S T E X T ( ' CU S T OME R D I S P L AY ' )
A CA0 3 ( 1 5 ' E ND OF P ROGRAM ' )
A OVE R L AY
A 8 3 ' NAME '
A NAME R 8 11
A 9 3 ' ADDR E S S '
A ADDR R 9 11
A 1 /0 3 ' CI T Y '
A CI T Y R 1 /0 11
A 11 3 ' S T AT E '
A S T AT E R 11 11
A 11 2 1 ' Z I P CODE '
A ZIP R 11 31
A 12 3 ' A / R B AL ANCE '
A AR B AL R 12 17
A
A
A
A
A
A
A

Figure 68. Example of a TRANSACTION Inquiry Program Using a Single Display Device

The data description specifications (DDS) for the display device file (CUSMINQ) to
be used by this program describe two record formats: CUSPMT and CUSFLDS.

The CUSPMT record format contains the constant ‘Customer Master Inquiry’, which
identifies the display. It also contains the prompt ‘Customer Number’ and the input

200 COBOL/400 User’s Guide


field (CUST) where you enter the customer number. Five underscores appear
under the input field CUST on the display where you are to enter the customer
number. The error message:
Customer number not found
is also included in this record format. This message is displayed if indicator 99 is
set to ON by the program. In addition, this record format defines a function key
that you can press to end the program. When you press function key F3, indicator
15 is set to ON in the COBOL program. This indicator is then used to end the
program.

The CUSFLDS record format contains the following constants:


Ÿ Name
Ÿ Address
Ÿ City
Ÿ State
Ÿ Zip Code
Ÿ A/R Balance.
These constants identify the fields to be written out from the program. This record
format also describes the fields that correspond to these constants. All of these
fields are described as output fields (blank in position 38) because they are filled in
by the program; you do not enter any data into these fields. To enter another cus-
tomer number, press Enter in response to this record. Notice that the CUSFLDS
record overlays the CUSPMT record. Therefore, when the CUSFLDS record is
written to the display, the CUSPMT record remains on the display.

In addition to describing the constants, fields, and attributes for the display, the
record formats also define the line numbers and horizontal positions where the con-
stants and fields are to be displayed.
Note: The field attributes are defined in a physical file (CUSMSTP) used for field
reference purposes, instead of in the DDS for the display file. For example,
EDTCDE(J) is defined in CUSMSTP for the field ARBAL.

Chapter 8. Transaction Files 201


AS/400 DATA DESCRIPTION SPECIFICATIONS GX 2 1 - 9 8 9 1 - 0 U M/ 0 5 0 *
Pr i nt ed i n U. S . A.
I nt er nat i onal Busi ness Machi nes *Number of sheets per pad may vary sli ghtl y.

Fi l e Keying Graphic Description Page of


Instruction
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Usage (b/O/I /B/ H/M/N/P)


And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functions

Reference (R)
Sequence
Number
Form Type

Posi t i ons
Indicator

Reserved
Indicator

Indicator

Decimal
Not (N)

Not (N)
Not (N)

Line Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 1 4 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 34 35 36 37 3 8 39 4 0 4 1 42 4 3 44 4 5 46 47 4 8 49 5 0 5 1 5 2 5 3 54 5 5 56 5 7 58 59 6 0 6 1 6 2 6 3 6 4 6 5 66 6 7 68 6 9 7 0 7 1 7 2 7 3 7 4 7 5 76 7 7 78 7 9 8 0

A * * P HY S I CAL CU SMS T P CU S T OME R MAS T E R F I L E


A R CU SMS T TEXT ( ' ORDE R HE ADE R R ECORD ' )
A CU S T 5 TEXT ( ' CU S T OME R NUMB E R ' )
A NAME 25 TEXT ( ' CU S T OME R NAME ' )
A ADDR 2 /0 TEXT ( ' CU S T OME R ADDR E S S ' )
A CI T Y 2 0/ TEXT ( ' CU S T OME R C I T Y ' )
A S T AT E 2 TEXT ( ' S T AT E ' )
A ZIP 5 /0 /0 TEXT ( ' Z I P CODE ' )
A S R HCOD 6 TEXT ( ' CU S T OME R NUMB E R S E ARCH CODE ' )
A CU S T YP 1 /0 /0 TEXT ( ' CU S T OME R T YP E 1 =GOV 2 = SCH +
A 3=B U S 4 =P V T 5 =OT ' )
A AR B AL 8 /0 2 TEXT ( ' ACCOUN T S R EC . B AL ANCE ' )
A ORDB AL 8 /0 2 TEXT ( ' A / R AMT I N ORDE R F I L E ' )
A L S T AMT 8 /0 2 TEXT ( ' L AS T AMOUN T P A I D I N A / R ' )
A L S T DA T 6 /0 /0 TEXT ( ' L AS T DA T E P A I D I N A / R ' )
A CRDL MT 8 /0 2 TEXT ( ' CU S T OME R CR E D I T L I MI T ' )
A S L S YR 1 /0 /0 2 TEXT ( ' CU S T OME R S AL E S T H I S Y E AR ' )
A S L S L YR 1 /0 /0 2 TEXT ( ' CU S T OME R S AL E S L AS T Y E AR ' )
A K CU S T
A

Figure 69. Data Description Specification for the Record Format CUSMST.

The data description specifications (DDS) for the database file that is used by this
program describe one record format: CUSMST. Each field in the record format is
described, and the CUST field is identified as the key field for the record format.

202 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð1/22/94
2 ððð2ðð PROGRAM-ID. XMPLE766. ð3/22/94
ððð3ðð\ SAMPLE TRANSACTION INQUIRY PROGRAM USING 1 DISPLAY DEVICE ð1/22/94
3 ððð4ðð AUTHOR. PROGRAMMER NAME. ð1/22/94
4 ððð5ðð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE. ð1/22/94
5 ððð6ðð DATE-WRITTEN. 12/21/88. ð1/22/94
6 ðððð7ð DATE-COMPILED. ð5/24/94 13:42:5ð .
7 ððð8ðð ENVIRONMENT DIVISION. ð1/22/94
8 ððð9ðð CONFIGURATION SECTION. ð1/22/94
9 ðð1ððð SOURCE-COMPUTER. IBM-AS4ðð. ð1/22/94
1ð ðð11ðð OBJECT-COMPUTER. IBM-AS4ðð. ð1/22/94
11 ðð12ðð INPUT-OUTPUT SECTION. ð1/22/94
12 ðð13ðð FILE-CONTROL. ð1/22/94
13 ðð14ðð SELECT CUST-DISPLAY ð1/22/94
14 ðð15ðð ASSIGN TO WORKSTATION-CUSMINQ ð1/22/94
15 ðð16ðð ORGANIZATION IS TRANSACTION ð1/22/94
16 ðð17ðð CONTROL-AREA IS WS-CONTROL. ð1/22/94
17 ðð18ðð SELECT CUST-MASTER ð1/22/94
18 ðð19ðð ASSIGN TO DATABASE-CUSMSTP ð1/22/94
19 ðð2ððð ORGANIZATION IS INDEXED ð1/22/94
2ð ðð21ðð ACCESS IS RANDOM ð1/22/94
21 ðð22ðð RECORD KEY IS CUST OF CUSMST ð1/22/94
22 ðð23ðð FILE STATUS IS CM-STATUS. ð1/22/94
23 ðð24ðð DATA DIVISION. ð1/22/94
24 ðð25ðð FILE SECTION. ð1/22/94
25 ðð26ðð FD CUST-DISPLAY ð1/22/94
26 ðð27ðð LABEL RECORDS ARE OMITTED. ð1/22/94
27 ðð28ðð ð1 DISP-REC. ð1/22/94
28 ðð29ðð COPY DDS-ALL-FORMATS OF CUSMINQ. ð1/22/94
29 +ððððð1 ð5 CUSMINQ-RECORD PIC X(8ð). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:CUSPMT FROM FILE CUSMINQ OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ CUSTOMER PROMPT <-ALL-FMTS
3ð +ððððð4 ð5 CUSPMT-I REDEFINES CUSMINQ-RECORD. <-ALL-FMTS
31 +ððððð5 ð6 CUSPMT-I-INDIC. <-ALL-FMTS
32 +ððððð6 ð7 IN15 PIC 1 INDIC 15. <-ALL-FMTS
+ððððð7\ END OF PROGRAM <-ALL-FMTS
33 +ððððð8 ð7 IN99 PIC 1 INDIC 99. <-ALL-FMTS
+ððððð9\ CUSTOMER NUMBER NOT FOUND PRESS RESET, THE <-ALL-FMTS
34 +ðððð1ð ð6 CUST PIC X(5). <-ALL-FMTS
+ðððð11\ CUSTOMER NUMBER <-ALL-FMTS
+ðððð12\ OUTPUT FORMAT:CUSPMT FROM FILE CUSMINQ OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð13\ CUSTOMER PROMPT <-ALL-FMTS
35 +ðððð14 ð5 CUSPMT-O REDEFINES CUSMINQ-RECORD. <-ALL-FMTS
36 +ðððð15 ð6 CUSPMT-O-INDIC. <-ALL-FMTS
37 +ðððð16 ð7 IN99 PIC 1 INDIC 99. <-ALL-FMTS
+ðððð17\ CUSTOMER NUMBER NOT FOUND PRESS RESET, THE <-ALL-FMTS
+ðððð18\ INPUT FORMAT:CUSFLDS FROM FILE CUSMINQ OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð19\ CUSTOMER DISPLAY <-ALL-FMTS
38 +ðððð2ð ð5 CUSFLDS-I REDEFINES CUSMINQ-RECORD. <-ALL-FMTS
39 +ðððð21 ð6 CUSFLDS-I-INDIC. <-ALL-FMTS
4ð +ðððð22 ð7 IN15 PIC 1 INDIC 15. <-ALL-FMTS
+ðððð23\ END OF PROGRAM <-ALL-FMTS
+ðððð24\ OUTPUT FORMAT:CUSFLDS FROM FILE CUSMINQ OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð25\ CUSTOMER DISPLAY <-ALL-FMTS
41 +ðððð26 ð5 CUSFLDS-O REDEFINES CUSMINQ-RECORD. <-ALL-FMTS
42 +ðððð27 ð6 NAME PIC X(25). <-ALL-FMTS
+ðððð28\ CUSTOMER NAME <-ALL-FMTS
43 +ðððð29 ð6 ADDR PIC X(2ð). <-ALL-FMTS
+ðððð3ð\ CUSTOMER ADDRESS <-ALL-FMTS
44 +ðððð31 ð6 CITY PIC X(2ð). <-ALL-FMTS
+ðððð32\ CUSTOMER CITY <-ALL-FMTS
45 +ðððð33 ð6 STATE PIC X(2). <-ALL-FMTS
+ðððð34\ STATE <-ALL-FMTS
46 +ðððð35 ð6 ZIP PIC S9(5). <-ALL-FMTS
+ðððð36\ ZIP CODE <-ALL-FMTS
47 +ðððð37 ð6 ARBAL PIC S9(6)V9(2). <-ALL-FMTS
+ðððð38\ ACCOUNTS REC. BALANCE <-ALL-FMTS
ðð3ððð
48 ðð31ðð FD CUST-MASTER
49 ðð32ðð LABEL RECORDS ARE STANDARD.
5ð ðð33ðð ð1 CUST-REC.
51 ðð34ðð COPY DDS-CUSMST OF CUSMSTP.
+ððððð1\ I-O FORMAT:CUSMST FROM FILE CUSMSTP OF LIBRARY XMPLIB CUSMST

Figure 70 (Part 1 of 2). Source Listing of a TRANSACTION Inquiry Program Using a Single Display Device.

Chapter 8. Transaction Files 203


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
+ððððð2\ CUSTOMER MASTER RECORD CUSMST
+ððððð3\THE KEY DEFINITIONS FOR RECORD FORMAT CUSMST CUSMST
+ððððð4\ NUMBER NAME RETRIEVAL TYPE ALTSEQ CUSMST
+ððððð5\ ððð1 CUST ASCENDING AN NO CUSMST
52 +ððððð6 ð5 CUSMST. CUSMST
53 +ððððð7 ð6 CUST PIC X(5). CUSMST
+ððððð8\ CUSTOMER NUMBER CUSMST
54 +ððððð9 ð6 NAME PIC X(25). CUSMST
+ðððð1ð\ CUSTOMER NAME CUSMST
55 +ðððð11 ð6 ADDR PIC X(2ð). CUSMST
+ðððð12\ CUSTOMER ADDRESS CUSMST
56 +ðððð13 ð6 CITY PIC X(2ð). CUSMST
+ðððð14\ CUSTOMER CITY CUSMST
57 +ðððð15 ð6 STATE PIC X(2). CUSMST
+ðððð16\ STATE CUSMST
58 +ðððð17 ð6 ZIP PIC S9(5) COMP-3. CUSMST
+ðððð18\ ZIP CODE CUSMST
59 +ðððð19 ð6 SRHCOD PIC X(6). CUSMST
+ðððð2ð\ CUSTOMER NUMBER SEARCH CODE CUSMST
6ð +ðððð21 ð6 CUSTYP PIC S9(1) COMP-3. CUSMST
+ðððð22\ CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5=OT CUSMST
61 +ðððð23 ð6 ARBAL PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð24\ ACCOUNTS REC. BALANCE CUSMST
62 +ðððð25 ð6 ORDBAL PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð26\ A/R AMT. IN ORDER FILE CUSMST
63 +ðððð27 ð6 LSTAMT PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð28\ LAST AMT. PAID IN A/R CUSMST
64 +ðððð29 ð6 LSTDAT PIC S9(6) COMP-3. CUSMST
+ðððð3ð\ LAST DATE PAID IN A/R CUSMST
65 +ðððð31 ð6 CRDLMT PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð32\ CUSTOMER CREDIT LIMIT CUSMST
66 +ðððð33 ð6 SLSYR PIC S9(8)V9(2) COMP-3. CUSMST
+ðððð34\ CUSTOMER SALES THIS YEAR CUSMST
67 +ðððð35 ð6 SLSLYR PIC S9(8)V9(2) COMP-3. CUSMST
+ðððð36\ CUSTOMER SALES LAST YEAR CUSMST
ðð35ðð
68 ðð36ðð WORKING-STORAGE SECTION.
69 ðð37ðð ð1 ONE PIC 1 VALUE B"1".
7ð ðð38ðð ð1 CM-STATUS PIC X(2).
71 ðð39ðð ð1 WS-CONTROL.
72 ðð4ððð ð2 WS-IND PIC X(2).
73 ðð41ðð ð2 WS-FORMAT PIC X(1ð).
74 ðð42ðð PROCEDURE DIVISION.
ðð43ðð BEGIN.
75 ðð44ðð OPEN I-O CUST-DISPLAY, INPUT CUST-MASTER.
76 ðð45ðð MOVE ZERO TO IN99 OF CUSPMT-O.
ðð46ðð LOOP.
77 ðð47ðð WRITE DISP-REC FORMAT IS "CUSPMT".
78 ðð48ðð READ CUST-DISPLAY RECORD.
79 ðð49ðð IF IN15 OF CUSPMT-I
ðð5ððð IS EQUAL TO ONE
8ð ðð51ðð THEN GO TO FINIS.
81 ðð52ðð MOVE CUST OF CUSPMT-I TO CUST OF CUSMST.
82 ðð53ðð READ CUST-MASTER RECORD.
83 ðð54ðð IF CM-STATUS IS NOT EQUAL "ðð" THEN
84 ðð55ðð MOVE ONE TO IN99 OF CUSPMT-O, GO TO LOOP.
86 ðð56ðð MOVE CORRESPONDING CUSMST TO CUSFLDS-O.
87 ðð57ðð WRITE DISP-REC FORMAT IS "CUSFLDS".
88 ðð58ðð READ CUST-DISPLAY RECORD.
89 ðð59ðð IF IN15 OF CUSFLDS-I
ðð6ððð IS EQUAL TO ONE
9ð ðð61ðð THEN GO TO FINIS.
91 ðð62ðð MOVE ZERO TO IN99 OF CUSPMT-O.
92 ðð63ðð GO TO LOOP.
ðð64ðð FINIS.
93 ðð65ðð CLOSE CUST-DISPLAY, CUST-MASTER.
ðð66ðð RETURN-TO-CALLER.
94 ðð67ðð EXIT PROGRAM.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 70 (Part 2 of 2). Source Listing of a TRANSACTION Inquiry Program Using a Single Display Device.

The complete source listing for this program example is shown here. In particular,
note the FILE-CONTROL and FD entries and the data structures generated by the
Format 2 COPY statements.

204 COBOL/400 User’s Guide


The WRITE operation in statement 77 writes the CUSPMT format to the display.
This record prompts you to enter a customer number. If you enter a customer
number and press Enter, the next READ operation then reads the record back into
the program.

The READ operation in statement 82 uses the customer number (CUST) field to
retrieve the corresponding CUSMST record from the CUSMSTP file. If no record is
found in the CUSMSTP file, indicator 99 is set on. The GO TO operation in state-
ment 84, which is run when indicator 99 is set on, causes the program to branch
back to the beginning. The message:
Customer number not found
is displayed when the format is written, because it is conditioned by indicator 99 in
the DDS for the file. When you receive this message, the keyboard locks. You
must press the Reset key in response to this message to unlock the keyboard.
You can then enter another customer number.

If the READ operation retrieves a record from the CUSMSTP file, the WRITE oper-
ation writes the CUSFLDS record to the display work station. This record contains
the customer’s name, address, and accounts receivable balance.

You then press Enter, and the program branches back to the beginning. You can
enter another customer number or end the program. To end the program, press
F3, which sets on indicator 15 in the program.

When indicator 15 is on, the program closes all files and processes the EXIT
PROGRAM statement. The program then returns control to the individual who
called the COBOL program.

This is the initial display written by the WRITE operation in statement 77:

à@ ð
Customer Master Inquiry

Customer Number ________

Use F3 to end program, use enter key to return to prompt screen

This display appears if a record is found in the CUSMSTP file for the customer
number entered in response to the first display:

Chapter 8. Transaction Files 205


à@ ð
Customer Master Inquiry

Customer Number 1ððð

Use F3 to end program, use enter key to return to prompt screen

Name EXAMPLE WHOLESALERS LTD.


Address ANYWHERE STREET
City ACITY
State IL Zipcode 12345
A/R balance 137.ð2

This display appears if the CUSMSTP file does not contain a record for the cus-
tomer number entered in response to the first display:

à@ ð
Customer Master Inquiry

Customer Number

Use F3 to end program, use enter key to return to prompt screen

Customer number not found, press reset, then enter valid number

Order Inquiry Programs Using Subfiles


Figure 72 on page 210 shows an example of an order inquiry program,
XMPLE773, that uses subfiles. The associated DDS is also shown, except for the
DDS for the customer master file, CUSMSTP. Refer to Figure 69 on page 202 for
the DDS for CUSMSTP.

XMPLE773 displays all the detail order records for the requested order number.
The program prompts you to enter the order number that is to be reviewed. The
order number is checked against the order header file, ORDHDRP. If the order
number exists, the customer number accessed from the order header file is
checked against the customer master file, CUSMSTP. All order detail records in
ORDDTLP for the requested order are read and written to the subfile. A write for
the subfile control record format is processed, and the detail order records in the
subfile are displayed for you to review. You end the program by pressing F12.

206 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1- 98 91- 0 UM/05 0*
P r i n t e d i n U . S . A.
I nt er nat i onal Bus i nes s Machi nes * Number of sheets per pad may var y sl i ghtl y.

Fi l e Keying Graphic Description Page of


I nstructi on
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne P os

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80

A * * P H Y S I CAL ORDD T L P ORD E R D E T A I L F I LE


A T E X T ( ' WAR E HOU S E L OCA T I ON ' )
A*
A R ORDD T L T E X T ( ' OR D E R D E T A I L R E COR D ' )
A*
A CU S T 5 CH E CK ( MF )
A COL HDG ( ' CU S T OME R ' ' NUMB E R ' )
A*
A ORD E R N 5 /0 COL HDG ( ' ORD E R ' ' NUMB E R ' )
A*
A L I NNUM 3 /0
A COL HDG ( ' L I NE ' ' NO ' )
A T E X T ( ' L I NE NUMB E R OF L I NE I N OR D E R ' +
A )
A*
A I T EM 5 /0 CH E CK ( M1 0/ )
A COL HDG ( ' I T EM ' ' NUMB E R ' )
A QT YOR D 3 /0
A COL HDG ( ' QUAN T I T Y ' ' ORD E R E D ' )
A T E X T ( ' QUAN T I T Y OR D E R E D ' )
A*
A D E S CR P 3 /0 COL HDG ( ' I T EM D E S CR I P T I ON ' )
A*
A P R I CE 6 2 CMP ( G T 0 /)
A COL HDG ( ' P R I CE ' )
A T E X T ( ' S E L L I NG P R I CE ' )
A E D T CD E ( J )
A E X T ENS 8 2 COL HDG ( ' E X T E N S I ON ' )
A T E X T ( ' E X T E N S I ON AMOUN T OF QT YOR D X +
A P R I CE ' )
A*
A WH S L OC 3 CH E CK ( MF )
A COL HDG ( ' B I N ' ' NO . ' )
A*
A ORDDA T 6 /0 T E X T ( ' DA T E OR D E R WA S +
A ENT E R ED ' )
A CU S T Y P 1 /0 R ANGE ( 1 5 )
A COL HDG ( ' CU S T ' ' T Y P E ' )
A T E X T ( ' CU S T OME R T Y P E 1 =GOV 2 = S CH +
A 3 = B U S 4 = P V T 5 =OT ' )
A*
A S TAT E 2 CH E CK ( MF )
A COL HDG ( ' S T A T E ' )
A*
A*
A AC T MT H 2 /0 COL HDG ( ' ACC T ' ' MT H ' )
A T E X T ( ' ACCOUN T I NG MON T H OF S AL E ' )
A*
A AC T Y R 2 /0 COL HDG ( ' ACC T ' ' Y E AR ' )
A T E X T ( ' ACCOUN T I NG Y E AR OF S A L E ' )
A K ORD E R N
A K L I NNUM
A

Figure 71 (Part 1 of 3). Data Description Specifications for an Order Inquiry Program

Chapter 8. Transaction Files 207


AS/400 DATA DESCRIPTION SPECIFICATIONS GX 2 1 - 9 8 9 1 - 0 UM/ 0 5 0 *
Pr i nt ed i n U. S. A.
I n t er n at i on al Bu s i n e s s Mac h i ne s *Number of sheet s per pad may vary sl i ghtl y.

Fi l e Keying Graphic Description Page of


I nst ruct i on
Programmer Date Key

Type of Name of Spec /( b/R/H/ J/K/ S/ O)


Conditioning

Location

Data Type/Keyboard Shi ft

U s age (/ b / O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Condition Name

Name Length Funct i ons

Reference (R)
Sequence
Number
Form Type

Pos i t i on s
Indicator

Indicator

Indicator

Reserved

Decimal
Not (N)

Not (N)

Not (N)

Line Pos

1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 14 1 5 16 1 7 18 1 9 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0

/
A * * OR D I NQD E X I S T I NG OR D E R R E V I EW
A R S UB 1 SFL
A I T EM 5 /0 1 /0 2 T E X T ( ' I T E M NUMB E R ' )
A Q T YOR D 3 /0 1 /0 9 T E X T ( ' QUAN T I T Y OR D E R E D ' )
A D E S CR P 3 /0 1 /0 1 4 T E X T ( ' I T E M D E S CR I P T I ON ' )
A P R I CE 6 2 1 /0 4 6 T E X T ( ' S E L L I NG P R I CE ' )
A E X T ENS 8 2 1 /0 5 6 E D T CD E ( J )
A T E X T ( ' E X T E N S I ON AMOUN T OF +
A Q T YOR D X P R I CE ' )
A R S UBCT L 1 S F L C T L ( S UB 1 )
A 58 S F L CL R
A 57 S F LDSP
A N5 8 S F L D S PC T L
A SFL S I Z ( 57 )
A S F L P AG ( 1 4 )
A 57 S F L E ND
A OV E R L AY
A L OCK
A N4 5
AON 4 7 R OL L U P ( 9 7 ' CON T I NU E D I S P L AY ' )
A CA 1 2 ( 9 8 ' E ND OF P ROGR AM ' )
A S E T OF F ( 5 7 ' D I S P L A Y S U B F I L E ' )
A S E T OF F ( 5 8 ' OF F =D I S P L AY S U B C T L 1 ON= +
A CL E AR S U B F I L E ' )
A 1 2 ' E X I S T I NG OR D E R I NQU I R Y '
A 3 2 ' OR D E R '
A OR D E R N 5 Y /0 B 3 8 T E X T ( ' OR D E R NUMB E R ' )
A 61 E R RMS G ( ' OR D E R NUMB E R NO T F OUND ' 6 1 )
A 47 E R RMS G ( ' NO L I NE S F OR T H I S OR D E R ' 4 7 )
A 62 E R RMS G ( ' NO CU S T OME R R E COR D F OUND F O+
A R T H I S OR D E R ' 6 2 )
A 4 2 ' DA T E '
A OR DDA T 6 /0 4 7 T E X T ( ' DA T E OR D E R WA S E N T E R E D ' )
A 5 2 ' CU S T # '
A CU S T 5 5 9 T E X T ( ' CU S T OME R NUMB E R ' )
A NAME 25 3 1 6 T E X T ( ' CU S T OME R NAME ' )
A ADDR 20 4 1 6 T E X T ( ' CU S T OME R ADDR E S S ' )
A CI TY 20 5 1 6 T E X T ( ' CU S T OME R C I T Y ' )
A S TAT E 2 6 1 6 T E X T ( ' CU S T OME R S T A T E ' )
A ZIP 5 /0 6 3 1 T E X T ( ' Z I P COD E ' )
A 1 4 4 ' T OT AL '
A OR DAMT 8 2 1 5 1 T E X T ( ' T O T A L DOL L AR AMOUN T OF T H E +
A OR D E R ' )
A 2 44 ' S TAT US '
A S T S OR D 12 2 51
A 3 4 4 ' OP E N '
A S T S OP N 12 3 51
A 4 4 4 ' CU S T OME R OR D E R '
A CU S OR D 15 4 5 9 T E X T ( ' CU S T OME R P U R CHA S E OR D E R +
A NUMB E R ' )
A 5 44 ' SH I P V I A '
A S HP V I A 15 5 5 9 T E X T ( ' S H I P P I NG I N S T R UC T I ON S ' )
A 6 4 4 ' P R I N T E D DA T E '
A P R T DA T 6 /0 6 5 7 T E X T ( ' DA T E OR D E R WA S P R I N T E D ' )
A 7 2 9 ' I NVO I CE '
A I NVNUM 5 /0 7 3 8 T E X T ( ' I NVO I CE NUMB E R ' )
A 7 6 4 ' MT H '
A AC T MT H 2 /0 7 6 8 T E X T ( ' ACCOUN T I NG MON T H OF S A L E ' )
A 7 7 2 ' Y E AR '
A AC T Y R 2 /0 7 7 7 T E X T ( ' ACCOUN T I NG Y E AR OF S A L E ' )
A 8 2 ' I T EM '
A 8 8 ' QT Y '
A 8 1 4 ' I T E M D E S CR I P T I ON '
A 8 4 6 ' P R I CE '
A 8 5 5 ' E X T E N S I ON '

Figure 71 (Part 2 of 3). Data Description Specifications for an Order Inquiry Program

208 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1- 98 91- 0 UM/05 0*
P r i n t ed i n U . S . A.
I nt er nat i onal Bus i nes s Machi nes * Number of sheets per pad may var y sl i ghtl y.

Fi l e Keying Graphic Description Page of


I nstructi on
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne P os

1 2 3 4 5 6 7 8 9 1 0 1 1 1 2 1 3 1 4 1 5 1 6 1 7 1 8 19 2 0 2 1 2 2 2 3 2 4 2 5 2 6 2 7 2 8 2 9 3 0 3 1 3 2 3 3 3 4 3 5 3 6 3 7 3 8 3 9 4 0 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 5 0 5 1 5 2 5 3 5 4 5 5 5 6 5 7 5 8 5 9 6 0 6 1 6 2 6 3 6 4 6 5 6 6 6 7 6 8 6 9 7 0 7 1 7 2 7 3 7 4 7 5 7 6 7 7 7 8 7 9 8 0

A * * P H Y S I CAL ORDHDR P ORD E R H E AD E R F I L E


A R ORDHDR T E X T ( ' OR D E R H E AD E R R E COR D ' )
A CU S T 5 T E X T ( ' CU S T OME R NUMB E R ' )
A ORD E R N /
5 00 / T E X T ( ' OR D E R NUMB E R ' )
A ORDDA T 6 /0 /0 T E X T ( ' DA T E OR D E R E N T E R E D ' )
A CU S OR D 15 T E X T ( ' CU S T OME R P URCHA S E ORD E R +
A NUMB E R ' )
A S HP V I A 15 T E X T ( ' S H I P P I NG I N S T R UC T I ON S ' )
A ORD S T S 1 /0 /0 T E X T ( ' OR D E R S T A T U S 1 PCS 2CN T 3CHK +
A 4 R D Y 5 P R T 6 PCK ' )
A OP R NAM 1/0 T E X T ( ' OP E R A T OR WHO E N T E R E D +
A OR D ' )
A ORDAMT 8 /0 2 T E X T ( ' DOL L AR AMOUN T OF +
A OR D E R ' )
A CU S T Y P 1 /0 /0 T E X T ( ' CU S T OME R T Y P E 1 =GOV 2 = S CH +
A 3 = B U S 4 = P V T 5 =OT ' )
A I NVNUM 5 /0 /0 T E X T ( ' I NVO I CE NUMB E R ' )
A P R T DA T 6 /0 /0 T E X T ( ' DA T E OR D E R WA S P R I N T E D ' )
A OP N S T S 1 /0 /0 T E X T ( ' OR D E R OP E N S T A T U S 1 =OP E N +
A 2 =CL OS E 3 =CANCE L ' )
A T OT L I N 3 /0 /0 T E X T ( ' T OT AL L I NE I T EMS I N ORD E R ' )
A AC T MT H 2 /0 /0 T E X T ( ' ACCOUN T I NG MON T H OF S AL E ' )
A AC T Y R 2 /0 /0 T E X T ( ' ACCOUN T I NG Y E AR OF S A L E ' )
A S TAT E 2 T E X T ( ' S T AT E ' )
A AMP A I D 8 /0 2 T E X T ( ' T OT AL AMOUN T P A I D ' )
A K ORD E R N
A
A
A
A
A
A
A
A
A

Figure 71 (Part 3 of 3). Data Description Specifications for an Order Inquiry Program

Chapter 8. Transaction Files 209


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð1/25/94
2 ððð2ðð PROGRAM-ID. XMPLE773. ð3/22/94
ððð3ðð\ SAMPLE ORDER INQUIRY PROGRAM ð3/22/94
3 ððð4ðð AUTHOR. PROGRAMMER NAME. ð1/25/94
4 ððð5ðð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE. ð1/25/94
5 ððð6ðð DATE-WRITTEN. 12/22/88. ð1/25/94
8 ðððð8ð DATE-COMPILED. ð5/24/94 13:29:54 . ð3/ð1/94
7 ððð8ðð ENVIRONMENT DIVISION. ð1/25/94
8 ððð9ðð CONFIGURATION SECTION. ð1/25/94
9 ðð1ððð SOURCE-COMPUTER. IBM-AS4ðð. ð1/25/94
1ð ðð11ðð OBJECT-COMPUTER. IBM-AS4ðð. ð1/25/94
11 ðð12ðð INPUT-OUTPUT SECTION. ð1/25/94
12 ðð13ðð FILE-CONTROL. ð1/25/94
13 ðð14ðð SELECT ORDER-HEADER-FILE ð1/25/94
14 ðð15ðð ASSIGN TO DATABASE-ORDHDRP ð3/21/94
15 ðð16ðð ORGANIZATION IS INDEXED ð1/25/94
16 ðð17ðð ACCESS MODE IS RANDOM ð1/26/94
17 ðð18ðð RECORD KEY IS ORDERN OF ORDER-HEADER-RECORD. ð1/26/94
18 ðð19ðð SELECT ORDER-DETAIL-FILE ð1/25/94
19 ðð2ððð ASSIGN TO DATABASE-ORDDTLP ð3/21/94
2ð ðð21ðð ORGANIZATION IS INDEXED ð1/25/94
21 ðð22ðð ACCESS IS DYNAMIC ð1/25/94
22 ðð23ðð RECORD KEY IS ORDER-DETAIL-RECORD-KEY. ð1/27/94
23 ðð24ðð SELECT CUSTOMER-MASTER-FILE ð1/25/94
24 ðð25ðð ASSIGN TO DATABASE-CUSMSTP ð1/25/94
25 ðð26ðð ORGANIZATION IS INDEXED ð1/25/94
26 ðð27ðð ACCESS IS RANDOM ð1/25/94
27 ðð28ðð RECORD KEY IS CUST OF CUSTOMER-MASTER-RECORD. ð1/26/94
28 ðð29ðð SELECT EXISTING-ORDER-DISPLAY-FILE ð1/25/94
29 ðð3ððð ASSIGN TO WORKSTATION-ORDINQD ð3/23/94
3ð ðð31ðð ORGANIZATION IS TRANSACTION ð1/25/94
31 ðð32ðð ACCESS IS DYNAMIC ð1/25/94
32 ðð33ðð RELATIVE KEY IS SUBFILE-RECORD-NUMBER ð1/25/94
33 ðð34ðð FILE STATUS IS STATUS-CODE-ONE. ð1/25/94
34 ðð35ðð DATA DIVISION. ð1/25/94
35 ðð36ðð FILE SECTION. ð1/25/94
36 ðð37ðð FD ORDER-HEADER-FILE ð1/25/94
37 ðð38ðð LABEL RECORDS ARE STANDARD. ð1/25/94
38 ðð39ðð ð1 ORDER-HEADER-RECORD. ð1/25/94
39 ðð4ððð COPY DDS-ORDHDR OF ORDHDRP. ð3/21/94
+ððððð1\ I-O FORMAT:ORDHDR FROM FILE ORDHDRP OF LIBRARY XMPLIB ORDHDR
+ððððð2\ ORDER HEADER RECORD ORDHDR
+ððððð3\THE KEY DEFINITIONS FOR RECORD FORMAT ORDHDR ORDHDR
+ððððð4\ NUMBER NAME RETRIEVAL TYPE ALTSEQ ORDHDR
+ððððð5\ ððð1 ORDERN ASCENDING SIGNED NO ORDHDR
4ð +ððððð6 ð5 ORDHDR. ORDHDR
41 +ððððð7 ð6 CUST PIC X(5). ORDHDR
+ððððð8\ CUSTOMER NUMBER ORDHDR
42 +ððððð9 ð6 ORDERN PIC S9(5) COMP-3. ORDHDR
+ðððð1ð\ ORDER NUMBER ORDHDR
43 +ðððð11 ð6 ORDDAT PIC S9(6) COMP-3. ORDHDR
+ðððð12\ DATE ORDER ENTERED ORDHDR
44 +ðððð13 ð6 CUSORD PIC X(15). ORDHDR
+ðððð14\ CUSTOMER PURCHASE ORDER NUMBER ORDHDR
45 +ðððð15 ð6 SHPVIA PIC X(15). ORDHDR
+ðððð16\ SHIPPING INSTRUCTIONS ORDHDR
46 +ðððð17 ð6 ORDSTS PIC S9(1) COMP-3. ORDHDR
+ðððð18\ ORDER STATUS 1PCS 2CNT 3CHK 4RDY 5PRT 6PC ORDHDR
47 +ðððð19 ð6 OPRNAM PIC X(1ð). ORDHDR
+ðððð2ð\ OPERATOR WHO ENTERED ORD ORDHDR
48 +ðððð21 ð6 ORDAMT PIC S9(6)V9(2) COMP-3. ORDHDR
+ðððð22\ DOLLAR AMOUNT OF ORDER ORDHDR
49 +ðððð23 ð6 CUSTYP PIC S9(1) COMP-3. ORDHDR
+ðððð24\ CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5=OT ORDHDR
5ð +ðððð25 ð6 INVNUM PIC S9(5) COMP-3. ORDHDR
+ðððð26\ INVOICE NUMBER ORDHDR
51 +ðððð27 ð6 PRTDAT PIC S9(6) COMP-3. ORDHDR
+ðððð28\ DATE ORDER WAS PRINTED ORDHDR
52 +ðððð29 ð6 OPNSTS PIC S9(1) COMP-3. ORDHDR
+ðððð3ð\ ORDER OPEN STATUS 1=OPEN 2= CLOSE 3=CANCEL ORDHDR
53 +ðððð31 ð6 TOTLIN PIC S9(3) COMP-3. ORDHDR
+ðððð32\ TOTAL LINE ITEMS IN ORDER ORDHDR
54 +ðððð33 ð6 ACTMTH PIC S9(2) COMP-3. ORDHDR
+ðððð34\ ACCOUNTING MONTH OF SALE ORDHDR
55 +ðððð35 ð6 ACTYR PIC S9(2) COMP-3. ORDHDR
+ðððð36\ ACCOUNTING YEAR OF SALE ORDHDR

Figure 72 (Part 1 of 7). Example of an Order Inquiry Program

210 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
56 +ðððð37 ð6 STATE PIC X(2). ORDHDR
+ðððð38\ STATE ORDHDR
57 +ðððð39 ð6 AMPAID PIC S9(6)V9(2) COMP-3. ORDHDR
+ðððð4ð\ AMOUNT PAID ORDHDR
ðð41ðð
58 ðð42ðð FD ORDER-DETAIL-FILE
59 ðð43ðð LABEL RECORDS ARE STANDARD.
6ð ðð44ðð ð1 ORDER-DETAIL-RECORD.
61 ðð45ðð COPY DDS-ORDDTL OF ORDDTLP.
+ððððð1\ I-O FORMAT:ORDDTL FROM FILE ORDDTLP OF LIBRARY XMPLIB ORDDTL
+ððððð2\ ORDER DETAIL RECORD ORDDTL
+ððððð3\THE KEY DEFINITIONS FOR RECORD FORMAT ORDDTL ORDDTL
+ððððð4\ NUMBER NAME RETRIEVAL TYPE ALTSEQ ORDDTL
+ððððð5\ ððð1 ORDERN ASCENDING SIGNED NO ORDDTL
+ððððð6\ ððð2 LINNUM ASCENDING SIGNED NO ORDDTL
62 +ððððð7 ð5 ORDDTL. ORDDTL
63 +ððððð8 ð6 CUST PIC X(5). ORDDTL
+ððððð9\ CUSTOMER NUMBER ORDDTL
64 +ðððð1ð ð6 ORDERN PIC S9(5) COMP-3. ORDDTL
+ðððð11\ ORDER NUMBER ORDDTL
65 +ðððð12 ð6 LINNUM PIC S9(3) COMP-3. ORDDTL
+ðððð13\ LINE NUMBER OF LINE IN ORDER ORDDTL
66 +ðððð14 ð6 ITEM PIC S9(5) COMP-3. ORDDTL
+ðððð15\ ITEM NUMBER ORDDTL
67 +ðððð16 ð6 QTYORD PIC S9(3) COMP-3. ORDDTL
+ðððð17\ QUANTITY ORDERED ORDDTL
68 +ðððð18 ð6 DESCRP PIC X(3ð). ORDDTL
+ðððð19\ ITEM DESCRIPTION ORDDTL
69 +ðððð2ð ð6 PRICE PIC S9(4)V9(2) COMP-3. ORDDTL
+ðððð21\ SELLING PRICE ORDDTL
7ð +ðððð22 ð6 EXTENS PIC S9(6)V9(2) COMP-3. ORDDTL
+ðððð23\ EXTENSION AMOUNT OF QTYORD X PRICE ORDDTL
71 +ðððð24 ð6 WHSLOC PIC X(3). ORDDTL
+ðððð25\ BIN NO. ORDDTL
72 +ðððð26 ð6 ORDDAT PIC S9(6) COMP-3. ORDDTL
+ðððð27\ DATE ORDER WAS ENTERED ORDDTL
73 +ðððð28 ð6 CUSTYP PIC S9(1) COMP-3. ORDDTL
+ðððð29\ CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5= ORDDTL
74 +ðððð3ð ð6 STATE PIC X(2). ORDDTL
+ðððð31\ STATE ORDDTL
75 +ðððð32 ð6 ACTMTH PIC S9(2) COMP-3. ORDDTL
+ðððð33\ ACCOUNTING MONTH OF SALE ORDDTL
76 +ðððð34 ð6 ACTYR PIC S9(2) COMP-3. ORDDTL
+ðððð35\ ACCOUNTING YEAR OF SALE ORDDTL
77 ðð46ðð 66 ORDER-DETAIL-RECORD-KEY RENAMES ORDERN THRU LINNUM.
ðð47ðð
78 ðð48ðð FD CUSTOMER-MASTER-FILE
79 ðð49ðð LABEL RECORDS ARE STANDARD.
8ð ðð5ððð ð1 CUSTOMER-MASTER-RECORD.
81 ðð51ðð COPY DDS-CUSMST OF CUSMSTP.
+ððððð1\ I-O FORMAT:CUSMST FROM FILE CUSMSTP OF LIBRARY XMPLIB CUSMST
+ððððð2\ CUSTOMER MASTER RECORD CUSMST
+ððððð3\THE KEY DEFINITIONS FOR RECORD FORMAT CUSMST CUSMST
+ððððð4\ NUMBER NAME RETRIEVAL TYPE ALTSEQ CUSMST
+ððððð5\ ððð1 CUST ASCENDING AN NO CUSMST
82 +ððððð6 ð5 CUSMST. CUSMST
83 +ððððð7 ð6 CUST PIC X(5). CUSMST
+ððððð8\ CUSTOMER NUMBER CUSMST
84 +ððððð9 ð6 NAME PIC X(25). CUSMST
+ðððð1ð\ CUSTOMER NAME CUSMST
85 +ðððð11 ð6 ADDR PIC X(2ð). CUSMST
+ðððð12\ CUSTOMER ADDRESS CUSMST
86 +ðððð13 ð6 CITY PIC X(2ð). CUSMST
+ðððð14\ CUSTOMER CITY CUSMST
87 +ðððð15 ð6 STATE PIC X(2). CUSMST
+ðððð16\ STATE CUSMST
88 +ðððð17 ð6 ZIP PIC S9(5) COMP-3. CUSMST
+ðððð18\ ZIP CODE CUSMST
89 +ðððð19 ð6 SRHCOD PIC X(6). CUSMST
+ðððð2ð\ CUSTOMER NUMBER SEARCH CODE CUSMST
9ð +ðððð21 ð6 CUSTYP PIC S9(1) COMP-3. CUSMST
+ðððð22\ CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5=OT CUSMST
91 +ðððð23 ð6 ARBAL PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð24\ ACCOUNTS REC. BALANCE CUSMST
92 +ðððð25 ð6 ORDBAL PIC S9(6)V9(2) COMP-3. CUSMST

Figure 72 (Part 2 of 7). Example of an Order Inquiry Program

Chapter 8. Transaction Files 211


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
+ðððð26\ A/R AMT. IN ORDER FILE CUSMST
93 +ðððð27 ð6 LSTAMT PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð28\ LAST AMT. PAID IN A/R CUSMST
94 +ðððð29 ð6 LSTDAT PIC S9(6) COMP-3. CUSMST
+ðððð3ð\ LAST DATE PAID IN A/R CUSMST
95 +ðððð31 ð6 CRDLMT PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð32\ CUSTOMER CREDIT LIMIT CUSMST
96 +ðððð33 ð6 SLSYR PIC S9(8)V9(2) COMP-3. CUSMST
+ðððð34\ CUSTOMER SALES THIS YEAR CUSMST
97 +ðððð35 ð6 SLSLYR PIC S9(8)V9(2) COMP-3. CUSMST
+ðððð36\ CUSTOMER SALES LAST YEAR CUSMST
ðð52ðð
98 ðð53ðð FD EXISTING-ORDER-DISPLAY-FILE
99 ðð54ðð LABEL RECORDS ARE OMITTED.
1ðð ðð55ðð ð1 EXISTING-ORDER-DISPLAY-RECORD.
1ð1 ðð56ðð COPY DDS-ALL-FORMATS OF ORDINQD.
1ð2 +ððððð1 ð5 ORDINQD-RECORD PIC X(171). <-ALL-FMTS
+ððððð2\ I-O FORMAT:SUB1 FROM FILE ORDINQD OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
1ð3 +ððððð4 ð5 SUB1 REDEFINES ORDINQD-RECORD. <-ALL-FMTS
1ð4 +ððððð5 ð6 ITEM PIC S9(5). <-ALL-FMTS
+ððððð6\ ITEM NUMBER <-ALL-FMTS
1ð5 +ððððð7 ð6 QTYORD PIC S9(3). <-ALL-FMTS
+ððððð8\ QUANTITY ORDERED <-ALL-FMTS
1ð6 +ððððð9 ð6 DESCRP PIC X(3ð). <-ALL-FMTS
+ðððð1ð\ ITEM DESCRIPTION <-ALL-FMTS
1ð7 +ðððð11 ð6 PRICE PIC S9(4)V9(2). <-ALL-FMTS
+ðððð12\ SELLING PRICE <-ALL-FMTS
1ð8 +ðððð13 ð6 EXTENS PIC S9(6)V9(2). <-ALL-FMTS
+ðððð14\ EXTENSION AMOUNT OF QTYORD X PRICE <-ALL-FMTS
+ðððð15\ INPUT FORMAT:SUBCTL1 FROM FILE ORDINQD OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð16\ <-ALL-FMTS
1ð9 +ðððð17 ð5 SUBCTL1-I REDEFINES ORDINQD-RECORD. <-ALL-FMTS
11ð +ðððð18 ð6 SUBCTL1-I-INDIC. <-ALL-FMTS
111 +ðððð19 ð7 IN97 PIC 1 INDIC 97. <-ALL-FMTS
+ðððð2ð\ CONTINUE DISPLAY <-ALL-FMTS
112 +ðððð21 ð7 IN98 PIC 1 INDIC 98. <-ALL-FMTS
+ðððð22\ END OF PROGRAM <-ALL-FMTS
113 +ðððð23 ð7 IN57 PIC 1 INDIC 57. <-ALL-FMTS
+ðððð24\ DISPLAY SUBFILE <-ALL-FMTS
114 +ðððð25 ð7 IN58 PIC 1 INDIC 58. <-ALL-FMTS
+ðððð26\ OFF = DISPLAY SUBCTL1 ON = CLEAR SUBFILE <-ALL-FMTS
115 +ðððð27 ð7 IN61 PIC 1 INDIC 61. <-ALL-FMTS
+ðððð28\ ORDER NUMBER NOT FOUND <-ALL-FMTS
116 +ðððð29 ð7 IN47 PIC 1 INDIC 47. <-ALL-FMTS
+ðððð3ð\ NO LINE FOR THIS ORDER <-ALL-FMTS
117 +ðððð31 ð7 IN62 PIC 1 INDIC 62. <-ALL-FMTS
+ðððð32\ NO CUSTOMER RECORD <-ALL-FMTS
118 +ðððð33 ð6 ORDERN PIC S9(5). <-ALL-FMTS
+ðððð34\ ORDER NUMBER <-ALL-FMTS
+ðððð35\ OUTPUT FORMAT:SUBCTL1 FROM FILE ORDINQD OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð36\ <-ALL-FMTS
119 +ðððð37 ð5 SUBCTL1-O REDEFINES ORDINQD-RECORD. <-ALL-FMTS
12ð +ðððð38 ð6 SUBCTL1-O-INDIC. <-ALL-FMTS
121 +ðððð39 ð7 IN58 PIC 1 INDIC 58. <-ALL-FMTS
+ðððð4ð\ OFF = DISPLAY SUBCTL1 ON = CLEAR SUBFILE <-ALL-FMTS
122 +ðððð41 ð7 IN57 PIC 1 INDIC 57. <-ALL-FMTS
+ðððð42\ DISPLAY SUBFILE <-ALL-FMTS
123 +ðððð43 ð7 IN45 PIC 1 INDIC 45. <-ALL-FMTS
124 +ðððð44 ð7 IN47 PIC 1 INDIC 47. <-ALL-FMTS
+ðððð45\ NO LINE FOR THIS ORDER <-ALL-FMTS
125 +ðððð46 ð7 IN61 PIC 1 INDIC 61. <-ALL-FMTS
+ðððð47\ ORDER NUMBER NOT FOUND <-ALL-FMTS
126 +ðððð48 ð7 IN62 PIC 1 INDIC 62. <-ALL-FMTS
+ðððð49\ NO CUSTOMER RECORD <-ALL-FMTS
127 +ðððð5ð ð6 ORDERN PIC S9(5). <-ALL-FMTS
+ðððð51\ ORDER NUMBER <-ALL-FMTS
128 +ðððð52 ð6 ORDDAT PIC S9(6). <-ALL-FMTS
+ðððð53\ DATE ORDER WAS ENTERED <-ALL-FMTS
129 +ðððð54 ð6 CUST PIC X(5). <-ALL-FMTS
+ðððð55\ CUSTOMER NUMBER <-ALL-FMTS
13ð +ðððð56 ð6 NAME PIC X(25). <-ALL-FMTS
+ðððð57\ CUSTOMER NAME <-ALL-FMTS
131 +ðððð58 ð6 ADDR PIC X(2ð). <-ALL-FMTS
+ðððð59\ CUSTOMER ADDRESS <-ALL-FMTS
132 +ðððð6ð ð6 CITY PIC X(2ð). <-ALL-FMTS

Figure 72 (Part 3 of 7). Example of an Order Inquiry Program

212 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
+ðððð61\ CUSTOMER CITY <-ALL-FMTS
133 +ðððð62 ð6 STATE PIC X(2). <-ALL-FMTS
+ðððð63\ CUSTOMER STATE <-ALL-FMTS
134 +ðððð64 ð6 ZIP PIC S9(5). <-ALL-FMTS
+ðððð65\ ZIP CODE <-ALL-FMTS
135 +ðððð66 ð6 ORDAMT PIC S9(6)V9(2). <-ALL-FMTS
+ðððð67\ TOTAL AMOUNT OF ORDER <-ALL-FMTS
136 +ðððð68 ð6 STSORD PIC X(12). <-ALL-FMTS
137 +ðððð69 ð6 STSOPN PIC X(12). <-ALL-FMTS
138 +ðððð7ð ð6 CUSORD PIC X(15). <-ALL-FMTS
+ðððð71\ CUSTOMER PURCHASE ORDER NUMBER <-ALL-FMTS
139 +ðððð72 ð6 SHPVIA PIC X(15). <-ALL-FMTS
+ðððð73\ SHIPPING INSTRUCTIONS <-ALL-FMTS
14ð +ðððð74 ð6 PRTDAT PIC S9(6). <-ALL-FMTS
+ðððð75\ DATE ORDER WAS PRINTED <-ALL-FMTS
141 +ðððð76 ð6 INVNUM PIC S9(5). <-ALL-FMTS
+ðððð77\ INVOICE NUMBER <-ALL-FMTS
142 +ðððð78 ð6 ACTMTH PIC S9(2). <-ALL-FMTS
+ðððð79\ ACCOUNTING MONTH OF SALE <-ALL-FMTS
143 +ðððð8ð ð6 ACTYR PIC S9(2). <-ALL-FMTS
+ðððð81\ ACCOUNTING YEAR OF SALE <-ALL-FMTS
ðð57ðð
144 ðð58ðð WORKING-STORAGE SECTION.
145 ðð59ðð ð1 EXISTING-ORDER-DISPLAY-KEY.
146 ðð6ððð ð5 SUBFILE-RECORD-NUMBER PIC 9(2)
147 ðð61ðð VALUE ZERO.
ðð62ðð
148 ðð63ðð ð1 ORDER-STATUS-COMMENT-VALUES.
149 ðð64ðð ð5 FILLER PIC X(12)
15ð ðð65ðð VALUE "1-IN PROCESS".
151 ðð66ðð ð5 FILLER PIC X(12)
152 ðð67ðð VALUE "2-CONTINUED ".
153 ðð68ðð ð5 FILLER PIC X(12)
154 ðð69ðð VALUE "3-CREDIT CHK".
155 ðð7ððð ð5 FILLER PIC X(12)
156 ðð71ðð VALUE "4-READY PRT ".
157 ðð72ðð ð5 FILLER PIC X(12)
158 ðð73ðð VALUE "5-PRINTED ".
159 ðð74ðð ð5 FILLER PIC X(12)
16ð ðð75ðð VALUE "6-PICKED ".
161 ðð76ðð ð5 FILLER PIC X(12)
162 ðð77ðð VALUE "7-INVOICED ".
163 ðð78ðð ð5 FILLER PIC X(12)
164 ðð79ðð VALUE "8-INVALID ".
165 ðð8ððð ð5 FILLER PIC X(12)
166 ðð81ðð VALUE "9-CANCELED ".
ðð82ðð
167 ðð83ðð ð1 ORDER-STATUS-COMMENT-TABLE
168 ðð84ðð REDEFINES ORDER-STATUS-COMMENT-VALUES.
169 ðð85ðð ð5 ORDER-STATUS OCCURS 9 TIMES.
17ð ðð86ðð 1ð ORDER-STATUS-COMMENT PIC X(12).
ðð87ðð
171 ðð88ðð ð1 OPEN-STATUS-COMMENT-VALUES.
172 ðð89ðð ð5 FILLER PIC X(12)
173 ðð9ððð VALUE "1-OPEN ".
174 ðð91ðð ð5 FILLER PIC X(12)
175 ðð92ðð VALUE "2-CLOSED ".
176 ðð93ðð ð5 FILLER PIC X(12)
177 ðð94ðð VALUE "3-CANCELED ".
ðð95ðð
178 ðð96ðð ð1 OPEN-STATUS-COMMENT-TABLE
179 ðð97ðð REDEFINES OPEN-STATUS-COMMENT-VALUES.
18ð ðð98ðð ð5 OPEN-STATUS OCCURS 3 TIMES.
181 ðð99ðð 1ð OPEN-STATUS-COMMENT PIC X(12).
ð1ðððð
182 ð1ð1ðð ð1 ERRHDL-PARAMETERS.
183 ð1ð2ðð ð5 STATUS-CODE-ONE PIC X(2).
184 ð1ð3ðð 88 SUBFILE-IS-FULL VALUE "9M".
ð1ð4ðð
185 ð1ð5ðð ð1 ERRPGM-PARAMETERS.
186 ð1ð6ðð ð5 DISPLAY-PARAMETER PIC X(8)
187 ð1ð7ðð VALUE "ORD22ðD ".
188 ð1ð8ðð ð5 DUMMY-ONE PIC X(6)
189 ð1ð9ðð VALUE SPACES.
19ð ð11ððð ð5 DUMMY-TWO PIC X(8)
191 ð111ðð VALUE SPACES.

Figure 72 (Part 4 of 7). Example of an Order Inquiry Program

Chapter 8. Transaction Files 213


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
192 ð112ðð ð5 STATUS-CODE-TWO.
193 ð113ðð 1ð PRIMARY PIC X(1).
194 ð114ðð 1ð SECONDARY PIC X(1).
195 ð115ðð 1ð FILLER PIC X(5)
196 ð116ðð VALUE SPACES.
ð117ðð
197 ð118ðð ð1 SWITCH-AREA.
198 ð119ðð ð5 SWð1 PIC 1.
199 ð12ððð 88 NO-MORE-DETAIL-LINE-ITEMS VALUE B"1".
2ðð ð121ðð 88 MORE-DETAIL-LINE-ITEMS-EXIST VALUE B"ð".
2ð1 ð122ðð ð5 SWð2 PIC 1.
2ð2 ð123ðð 88 WRITE-DISPLAY VALUE B"1".
2ð3 ð124ðð 88 READ-DISPLAY VALUE B"ð".
2ð4 ð125ðð ð5 SWð3 PIC 1.
2ð5 ð126ðð 88 SUBCTL1-FORMAT VALUE B"1".
2ð6 ð127ðð 88 NOT-SUBCTL1-FORMAT VALUE B"ð".
2ð7 ð128ðð ð5 SWð4 PIC 1.
2ð8 ð129ðð 88 SUB1-FORMAT VALUE B"1".
2ð9 ð13ððð 88 NOT-SUB1-FORMAT VALUE B"ð".
ð131ðð
21ð ð132ðð ð1 INDICATOR-AREA.
211 ð133ðð ð5 IN98 PIC 1 INDIC 98.
212 ð134ðð 88 END-OF-EXISTING-ORDER-INQUIRY VALUE B"1".
213 ð135ðð ð5 IN97 PIC 1 INDIC 97.
214 ð136ðð 88 CONTINUE-DETAIL-LINES-DISPLAY VALUE B"1".
215 ð137ðð ð5 IN62 PIC 1 INDIC 62.
216 ð138ðð 88 CUSTOMER-NOT-FOUND VALUE B"1".
217 ð139ðð 88 CUSTOMER-EXIST VALUE B"ð".
218 ð14ððð ð5 IN61 PIC 1 INDIC 61.
219 ð141ðð 88 ORDER-NOT-FOUND VALUE B"1".
22ð ð142ðð 88 ORDER-EXIST VALUE B"ð".
221 ð143ðð ð5 IN58 PIC 1 INDIC 58.
222 ð144ðð 88 CLEAR-SUBFILE VALUE B"1".
223 ð145ðð 88 DISPLAY-SUBFILE-CONTROL VALUE B"ð".
224 ð146ðð ð5 IN57 PIC 1 INDIC 57.
225 ð147ðð 88 DISPLAY-SUBFILE VALUE B"1".
226 ð148ðð ð5 IN47 PIC 1 INDIC 47.
227 ð149ðð 88 NO-DETAIL-LINES-FOR-ORDER VALUE B"1".
228 ð15ððð 88 DETAIL-LINES-FOR-ORDER-EXIST VALUE B"ð".
229 ð151ðð ð5 IN45 PIC 1 INDIC 45.
23ð ð152ðð 88 END-OF-ORDER VALUE B"1".
ð153ðð
231 ð154ðð PROCEDURE DIVISION.
ð155ðð
ð156ðð DECLARATIVES.
ð157ðð TRANSACTION-ERROR SECTION.
ð158ðð USE AFTER STANDARD ERROR PROCEDURE
ð159ðð EXISTING-ORDER-DISPLAY-FILE.
ð16ððð WORK-STATION-ERROR-HANDLER.
232 ð161ðð IF SUBFILE-IS-FULL THEN
ð162ðð NEXT SENTENCE
ð163ðð ELSE
233 ð164ðð DISPLAY "WORK-STATION ERROR" STATUS-CODE-ONE.
ð165ðð END DECLARATIVES.
ð166ðð
ð167ðð INQUIRY-INTO-EXISTING-ORDER SECTION.
ð168ðð MAINLINE-ROUTINE.
234 ð169ðð PERFORM SET-UP-ROUTINE.
235 ð17ððð PERFORM EXISTING-ORDER-INQUIRY
ð171ðð UNTIL END-OF-EXISTING-ORDER-INQUIRY.
236 ð172ðð PERFORM CLEAN-UP-ROUTINE.
ð173ðð
ð174ðð SET-UP-ROUTINE.
237 ð175ðð OPEN INPUT ORDER-HEADER-FILE
ð176ðð ORDER-DETAIL-FILE
ð177ðð CUSTOMER-MASTER-FILE
ð178ðð I-O EXISTING-ORDER-DISPLAY-FILE.
238 ð179ðð MOVE SPACES TO CUST OF SUBCTL1-O
ð18ððð NAME OF SUBCTL1-O
ð181ðð ADDR OF SUBCTL1-O
ð182ðð CITY OF SUBCTL1-O
ð183ðð STATE OF SUBCTL1-O
ð184ðð STSORD OF SUBCTL1-O
ð185ðð STSOPN OF SUBCTL1-O
ð186ðð CUSORD OF SUBCTL1-O.

Figure 72 (Part 5 of 7). Example of an Order Inquiry Program

214 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
239 ð187ðð MOVE ZEROS TO ORDERN OF SUBCTL1-O
ð188ðð ORDDAT OF SUBCTL1-O
ð189ðð ZIP OF SUBCTL1-O
ð19ððð ORDAMT OF SUBCTL1-O
ð191ðð PRTDAT OF SUBCTL1-O
ð192ðð INVNUM OF SUBCTL1-O
ð193ðð ACTMTH OF SUBCTL1-O
ð194ðð ACTYR OF SUBCTL1-O.
24ð ð195ðð MOVE ALL B'ð' TO INDICATOR-AREA.
241 ð196ðð SET READ-DISPLAY
ð197ðð NOT-SUBCTL1-FORMAT
ð198ðð NOT-SUB1-FORMAT TO TRUE.
242 ð199ðð MOVE CORR INDICATOR-AREA TO SUBCTL1-O-INDIC.
243 ð2ðððð WRITE EXISTING-ORDER-DISPLAY-RECORD FORMAT IS "SUBCTL1".
244 ð2ð1ðð READ EXISTING-ORDER-DISPLAY-FILE RECORD.
245 ð2ð2ðð MOVE CORR SUBCTL1-I-INDIC TO INDICATOR-AREA.
ð2ð3ðð
ð2ð4ðð EXISTING-ORDER-INQUIRY.
246 ð2ð5ðð IF CONTINUE-DETAIL-LINES-DISPLAY THEN
247 ð2ð6ðð PERFORM READ-NEXT-ORDER-DETAIL-RECORD
248 ð2ð7ðð IF MORE-DETAIL-LINE-ITEMS-EXIST THEN
249 ð2ð8ðð IF ORDERN OF ORDER-DETAIL-RECORD IS NOT EQUAL TO
ð2ð9ðð ORDERN OF ORDER-HEADER-RECORD THEN
25ð ð21ððð SET DISPLAY-SUBFILE TO TRUE
251 ð211ðð SET NO-DETAIL-LINES-FOR-ORDER TO TRUE
ð212ðð ELSE
252 ð213ðð PERFORM SUBFILE-SET-UP
ð214ðð ELSE
253 ð215ðð SET DISPLAY-SUBFILE TO TRUE
254 ð216ðð SET NO-DETAIL-LINES-FOR-ORDER TO TRUE
ð217ðð ELSE
255 ð218ðð PERFORM ORDER-NUMBER-VALIDATION.
256 ð219ðð MOVE CORR INDICATOR-AREA TO SUBCTL1-O-INDIC.
257 ð22ððð SET WRITE-DISPLAY TO TRUE.
258 ð221ðð SET SUBCTL1-FORMAT TO TRUE.
259 ð222ðð WRITE EXISTING-ORDER-DISPLAY-RECORD FORMAT IS "SUBCTL1".
26ð ð223ðð READ EXISTING-ORDER-DISPLAY-FILE RECORD.
261 ð224ðð MOVE CORR SUBCTL1-I-INDIC TO INDICATOR-AREA.
ð225ðð ORDER-NUMBER-VALIDATION.
262 ð226ðð PERFORM READ-ORDER-HEADER-FILE.
263 ð227ðð IF ORDER-EXIST THEN
264 ð228ðð PERFORM READ-CUSTOMER-MASTER-FILE
265 ð229ðð IF CUSTOMER-EXIST THEN
266 ð23ððð PERFORM READ-FIRST-ORDER-DETAIL-RECORD
267 ð231ðð IF DETAIL-LINES-FOR-ORDER-EXIST THEN
268 ð232ðð PERFORM SUBFILE-SET-UP
ð233ðð ELSE
ð234ðð NEXT SENTENCE
ð235ðð ELSE
ð236ðð NEXT SENTENCE
ð237ðð ELSE
ð238ðð NEXT SENTENCE.
ð239ðð READ-ORDER-HEADER-FILE.
269 ð24ððð MOVE ORDERN OF SUBCTL1-I OF EXISTING-ORDER-DISPLAY-RECORD
ð241ðð TO ORDERN OF ORDER-HEADER-RECORD.
27ð ð242ðð READ ORDER-HEADER-FILE
271 ð243ðð INVALID KEY SET ORDER-NOT-FOUND TO TRUE.
ð244ðð READ-CUSTOMER-MASTER-FILE.
272 ð245ðð MOVE CUST OF ORDER-HEADER-RECORD
ð246ðð TO CUST OF CUSTOMER-MASTER-RECORD.
273 ð247ðð READ CUSTOMER-MASTER-FILE
274 ð248ðð INVALID KEY SET CUSTOMER-NOT-FOUND TO TRUE.
ð249ðð READ-FIRST-ORDER-DETAIL-RECORD.
275 ð25ððð MOVE ORDERN OF ORDER-HEADER-RECORD
ð251ðð TO ORDERN OF ORDER-DETAIL-RECORD.
276 ð252ðð MOVE 1 TO LINNUM OF ORDER-DETAIL-RECORD.
277 ð253ðð READ ORDER-DETAIL-FILE
278 ð254ðð INVALID KEY SET NO-DETAIL-LINES-FOR-ORDER TO TRUE.
ð255ðð SUBFILE-SET-UP.
279 ð256ðð SET CLEAR-SUBFILE TO TRUE.
28ð ð257ðð MOVE CORR INDICATOR-AREA TO SUBCTL1-O-INDIC.
281 ð258ðð SET WRITE-DISPLAY TO TRUE.
282 ð259ðð SET SUBCTL1-FORMAT TO TRUE.
283 ð26ððð WRITE EXISTING-ORDER-DISPLAY-RECORD FORMAT IS "SUBCTL1".
284 ð261ðð SET DISPLAY-SUBFILE-CONTROL TO TRUE.

Figure 72 (Part 6 of 7). Example of an Order Inquiry Program

Chapter 8. Transaction Files 215


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
285 ð262ðð PERFORM BUILD-DISPLAY-SUBFILE
ð263ðð UNTIL NO-MORE-DETAIL-LINE-ITEMS
ð264ðð OR SUBFILE-IS-FULL.
286 ð265ðð MOVE CORR ORDHDR OF ORDER-HEADER-RECORD
ð266ðð TO SUBCTL1-O OF EXISTING-ORDER-DISPLAY-RECORD.
287 ð267ðð MOVE CORR CUSMST OF CUSTOMER-MASTER-RECORD
ð268ðð TO SUBCTL1-O OF EXISTING-ORDER-DISPLAY-RECORD.
288 ð269ðð MOVE ORDER-STATUS(ORDSTS) TO STSORD.
289 ð27ððð MOVE OPEN-STATUS(OPNSTS) TO STSOPN.
29ð ð271ðð SET MORE-DETAIL-LINE-ITEMS-EXIST TO TRUE.
291 ð272ðð MOVE ZEROS TO SUBFILE-RECORD-NUMBER.
ð273ðð BUILD-DISPLAY-SUBFILE.
292 ð274ðð MOVE CORR ORDDTL OF ORDER-DETAIL-RECORD
ð275ðð TO SUB1 OF EXISTING-ORDER-DISPLAY-RECORD.
293 ð276ðð SET WRITE-DISPLAY TO TRUE.
294 ð277ðð SET SUB1-FORMAT TO TRUE.
295 ð278ðð ADD 1 TO SUBFILE-RECORD-NUMBER.
296 ð279ðð WRITE SUBFILE EXISTING-ORDER-DISPLAY-RECORD FORMAT IS "SUB1".
297 ð28ððð IF SUBFILE-IS-FULL THEN
298 ð281ðð SET DISPLAY-SUBFILE TO TRUE
ð282ðð ELSE
299 ð283ðð PERFORM READ-NEXT-ORDER-DETAIL-RECORD
3ðð ð284ðð IF NO-MORE-DETAIL-LINE-ITEMS THEN
ð285ðð NEXT SENTENCE
ð286ðð ELSE
3ð1 ð287ðð IF ORDERN OF ORDER-DETAIL-RECORD IS NOT EQUAL TO
ð288ðð ORDERN OF ORDER-HEADER-RECORD THEN
3ð2 ð289ðð SET DISPLAY-SUBFILE TO TRUE
3ð3 ð29ððð SET NO-MORE-DETAIL-LINE-ITEMS TO TRUE
ð291ðð ELSE
ð292ðð NEXT SENTENCE.
ð293ðð READ-NEXT-ORDER-DETAIL-RECORD.
3ð4 ð294ðð READ ORDER-DETAIL-FILE NEXT RECORD
3ð5 ð295ðð AT END SET DISPLAY-SUBFILE TO TRUE
3ð6 ð296ðð SET NO-MORE-DETAIL-LINE-ITEMS TO TRUE.
ð297ðð CLEAN-UP-ROUTINE.
3ð7 ð298ðð CLOSE ORDER-HEADER-FILE
ð299ðð ORDER-DETAIL-FILE
ð3ðððð CUSTOMER-MASTER-FILE
ð3ð1ðð EXISTING-ORDER-DISPLAY-FILE.
3ð8 ð3ð2ðð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 72 (Part 7 of 7). Example of an Order Inquiry Program

This is the initial order-entry prompt display written to the work station:

à@ Existing Order Entry Total ððððððððð


ð
Status
Order 124ðð Open
Date ðððððð Customer order
Cust # Ship via
ððððð Printed date ðððððð
Invoice ððððð Mth ðð Year ðð
Item Qty Item Description Price Extension

This display appears if there are detail order records for the customer whose order
number was entered in the first display:

216 COBOL/400 User’s Guide


à@ Existing Order Entry Total ðð7426656
ð
Status 7-INVOICED
Order 17924 ABC HARDWARE LTD. Open 2-CLOSED
Date 11ð587 123 ANYWHERE AVE. Customer order TESTCS17933ðð1I
Cust # 112ðð TORONTO Ship via TRUCKCO
ONT M4K ðAð Printed date ð82788
Invoice 17924 Mth 12 Year 88
Item Qty Item Description Price Extension
33ðð1 ðð3 TORQUE WRENCH 75LB 14 INCH ðð9115 273.45
331ðð ðð1 TORQUE WRENCH W/GAUGE 2ðð LB ð15777 65ð.95
44529 ðð4 WOOD CHISEL - 3 1/4 ðð684ð 56.87
44958 ðð2 POWER DRILL 1/2 REV ðð82ðð 797.5ð
461ð2 ðð1 WROUGHT IRON RAILING 4FTX6FT ðð793ð 237.75
462ð1 ðð1 WROUGHT IRON HAND RAIL 6FT ðð7178 77.35
479ð2 ðð2 ESCUTCHEON BRASS 15X4 INCHES ð44488 213.ðð

This display appears if the ORDHDRP file does not contain a record for the order
number entered on the first display:

à@ Existing Order Entry Total ððððððððð


ð
Status
Order 124ðð Open
Date ðððððð Customer order
Cust # Ship via
ððððð Printed date ðððððð
Invoice ððððð Mth ðð Year ðð
Item Qty Item Description Price Extension

Order number not found

á ñ

A Payment Update Program


Figure 74 on page 221 shows an example of a payment update program,
PAYUPDT. For the related DDS, see Figure 73 on page 218. For the related
display-screen examples, see page 228. For the DDS for the customer master file,
CUSMSTP, refer to Figure 69 on page 202.

In this example, payments from customers are registered. The clerk is prompted to
enter one or more customer numbers and the amount of money to be credited to
each customer’s account. The program checks the customer number and uncondi-
tionally accepts any payment for an existing customer who has invoices out-
standing. If an overpayment will result from the amount of the payment from a
customer, the clerk is given the option to accept or reject the payment. If no cus-
tomer record exists for a customer number, an error message is issued. Payments
can be entered until the clerk ends the program by pressing F12.

Chapter 8. Transaction Files 217


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1- 98 91- 0 UM/05 0*
P r i n t ed i n U . S . A.
I nt er nat i onal Bus i nes s Machi nes * Number of sheets per pad may var y sl i ghtl y.

Fi l e Keying Graphic Description Page of


I nstructi on
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne P os

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80

A * * L OG I CAL ORDHDR L ORD E R F I L E OF ORDHDR


A R ORDHDR P F I L E ( OR DHDR P )
A*
A CU S T
A I NVNUM
A ORD E R N
A ORDDA T
A CU S OR D
A S HP V I A
A ORD S T S
A OP R NAM
A ORDAMT
A CU S T Y P
A P R T DA T
A OP N S T S
A T OT L I N
A AC T MT H
A AC T Y R
A S TAT E
A AMP A I D
A K CU S T
A K I NVNUM
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 73 (Part 1 of 3). Example of a Data Description Specification for a Payment Update Program

218 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1- 98 91- 0 UM/05 0*
P r i n t ed i n U . S . A.
I nt er nat i onal Bus i nes s Machi nes * Number of sheets per pad may var y sl i ghtl y.

Fi l e Keying Graphic Description Page of


I nstructi on
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne P os

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80

A* DD S F OR T H E D I S P L AY D E V I CE F I L E P AY /UP D
/ TD
A* ACCOUN T S R E CE I VAB L E I N T E R AC T I V E P AYME N T UP DA T E
A*
A R S UB F I L E 1 SFL
A T E X T ( ' S U B F I L E F OR CU S T OME R P AYME N T ' )
A*
A ACP PMT 4A I 5 4 T E X T ( ' ACCE P T P AYME N T ' )
A VAL U E S ( ' * Y E S ' ' * NO ' )
A 51 D S P A T R ( R I MD T )
A N5 1 D S P A T R ( ND P R )
A*
A CU S T 5 B 5 1 5 T E X T ( ' CU S T OME R NUMB E R ' )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A AMP A I D 8 /0 2 B 5 2 4 T E X T ( ' AMOUN T P A I D ' )
A CH E CK ( F E )
A AU T O( R AB )
A CMP ( G T /0 )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A E CPMSG 3 1A O 5 3 7 T E X T ( ' E XCE P T I ON ME S S AGE ' )
A 52 DSPAT R ( R I )
A 53 D S P A T R ( ND )
A 54 DSPAT R ( PR )
A*
A OVR PMT 8 Y 2O 5 7 /0 T E X T ( ' OVE R P AYME N T ' )
A E D T CD E ( 1 )
A 55 DSPAT R ( B L )
A N5 6 D S P A T R ( ND )
A*
A S T S CD E 1A H T E X T ( ' S T A T U S COD E ' )

Figure 73 (Part 2 of 3). Example of a Data Description Specification for a Payment Update Program

Chapter 8. Transaction Files 219


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1- 98 91- 0 UM/05 0*
P r i n t ed i n U . S . A.
I nt er nat i onal Bus i nes s Machi nes * Number of sheets per pad may var y sl i ghtl y.

Fi l e Keying Graphic Description Page of


I nstructi on
Programmer Date Key

Type of Name of Spec /(b/R/H/J/K/S/O)


Conditioning

Location

Us age (/b/ O/ I / B/ H/ M/ N/ P)
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne P os

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 5 1 52 53 54 55 56 57 58 59 60 6 1 62 63 64 65 66 67 68 69 70 7 1 72 73 74 75 76 77 78 79 80

A* R CON T ROL 1 T E X T ( ' S U B F I L E CON T ROL ' )


A S F L CT L ( S UB F I L E 1 )
A SFL S I Z ( 17 )
A S F L P AG ( 1 7 )
A 61 S F L CL R
A 62 S F LDSP
A 62 S F L D S PC T L
A OV E R L AY
A L OCK
A*
A HE L P ( 9 9 ' HE L P K E Y ' )
A CA 1 2 ( 9 8 ' E ND P AYME N T UP DA T E ' )
A CA 1 1 ( 9 7 ' I GNOR E I NP U T ' )
A*
A 99 S F L MSG ( ' F 1 1 - I GNOR E I NVAL I D I NP U T +
A F 1 2 - E ND P AYME N T +
A U P DA T E ' )
A*
A 1 2 ' CU S T OME R P AYME N T U P DA T E P ROMP T '
A 1 6 5 ' DA T E '
A 1 7 8DA T E E D T CD E ( Y )
A 63 3 2 ' ACCE P T '
A 63 4 2 ' P AYME N T '
A 3 1 4 ' CU S T OME R '
A 3 2 6 ' P AYME N T '
A 64 3 3 7 ' E XCE P T I ON ME S S AGE '
A*
A R ME S S AGE 1 T E X T ( ' ME S S AGE R E CORD ' )
A OV E R L AY
A L OCK
A*
A 71 24 2 ' ACCE P T P AYME N T VA L U E S : ( * NO * Y E S ) '
A DSPAT R ( R I )
A
A

Figure 73 (Part 3 of 3). Example of a Data Description Specification for a Payment Update Program

220 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð2/ð1/94
2 ððð2ðð PROGRAM-ID. PAYUPDT. ð3/22/94
3 ððð3ðð ENVIRONMENT DIVISION. ð2/ð1/94
4 ððð4ðð CONFIGURATION SECTION. ð2/ð1/94
5 ððð5ðð SOURCE-COMPUTER. IBM-AS4ðð. ð2/ð2/94
6 ððð6ðð OBJECT-COMPUTER. IBM-AS4ðð. ð2/ð2/94
7 ððð7ðð INPUT-OUTPUT SECTION. ð2/ð1/94
8 ððð8ðð FILE-CONTROL. ð2/ð1/94
9 ððð9ðð SELECT CUSTOMER-INVOICE-FILE ð2/ð1/94
1ð ðð1ððð ASSIGN TO DATABASE-ORDHDRL ð2/ð1/94
11 ðð11ðð ORGANIZATION IS INDEXED ð2/ð1/94
12 ðð12ðð ACCESS MODE IS SEQUENTIAL ð2/ð1/94
13 ðð13ðð RECORD KEY IS COMP-KEY ð2/ð1/94
14 ðð14ðð FILE STATUS IS STATUS-CODE-ONE. ð2/ð1/94
15 ðð15ðð SELECT CUSTOMER-MASTER-FILE ð2/ð1/94
16 ðð16ðð ASSIGN TO DATABASE-CUSMSTP ð2/ð1/94
17 ðð17ðð ORGANIZATION IS INDEXED ð2/ð1/94
18 ðð18ðð ACCESS IS RANDOM ð2/ð1/94
19 ðð19ðð RECORD KEY IS CUST OF CUSTOMER-MASTER-RECORD. ð2/ð1/94
2ð ðð2ððð SELECT PAYMENT-UPDATE-DISPLAY-FILE ð2/ð1/94
21 ðð21ðð ASSIGN TO WORKSTATION-PAYUPDTD ð3/22/94
22 ðð22ðð ORGANIZATION IS TRANSACTION ð2/ð1/94
23 ðð23ðð ACCESS IS DYNAMIC ð2/ð1/94
24 ðð24ðð RELATIVE KEY IS REL-NUMBER ð2/ð1/94
25 ðð25ðð FILE STATUS IS STATUS-CODE-ONE ð2/ð1/94
26 ðð26ðð CONTROL-AREA IS WS-CONTROL. ð2/ð1/94
ðð27ðð ð2/ð1/94
27 ðð28ðð DATA DIVISION. ð2/ð1/94
28 ðð29ðð FILE SECTION. ð2/ð1/94
29 ðð3ððð FD CUSTOMER-INVOICE-FILE ð2/ð1/94
3ð ðð31ðð LABEL RECORDS ARE STANDARD. ð2/ð1/94
31 ðð32ðð ð1 CUSTOMER-INVOICE-RECORD. ð2/ð1/94
32 ðð33ðð COPY DDS-ORDHDR OF ORDHDRL. ð3/14/94
+ððððð1\ I-O FORMAT:ORDHDR FROM FILE ORDHDRL OF LIBRARY XMPLIB ORDHDR
+ððððð2\ ORDHDR
+ððððð3\THE KEY DEFINITIONS FOR RECORD FORMAT ORDHDR ORDHDR
+ððððð4\ NUMBER NAME RETRIEVAL TYPE ALTSEQ ORDHDR
+ððððð5\ ððð1 CUST ASCENDING AN NO ORDHDR
+ððððð6\ ððð2 INVNUM ASCENDING SIGNED NO ORDHDR
33 +ððððð7 ð5 ORDHDR. ORDHDR
34 +ððððð8 ð6 CUST PIC X(5). ORDHDR
+ððððð9\ CUSTOMER NUMBER ORDHDR
35 +ðððð1ð ð6 INVNUM PIC S9(5) COMP-3. ORDHDR
+ðððð11\ INVOICE NUMBER ORDHDR
36 +ðððð12 ð6 ORDERN PIC S9(5) COMP-3. ORDHDR
+ðððð13\ ORDER NUMBER ORDHDR
37 +ðððð14 ð6 ORDDAT PIC S9(6) COMP-3. ORDHDR
+ðððð15\ DATE ORDER ENTERED ORDHDR
38 +ðððð16 ð6 CUSORD PIC X(15). ORDHDR
+ðððð17\ CUSTOMER PURCHASE ORDER NUMBER ORDHDR
39 +ðððð18 ð6 SHPVIA PIC X(15). ORDHDR
+ðððð19\ SHIPPING INSTRUCTIONS ORDHDR
4ð +ðððð2ð ð6 ORDSTS PIC S9(1) COMP-3. ORDHDR
+ðððð21\ ORDER STATUS 1PCS 2CNT 3CHK 4RDY 5PRT 6PC ORDHDR
41 +ðððð22 ð6 OPRNAM PIC X(1ð). ORDHDR
+ðððð23\ OPERATOR WHO ENTERED ORD ORDHDR
42 +ðððð24 ð6 ORDAMT PIC S9(6)V9(2) COMP-3. ORDHDR
+ðððð25\ DOLLAR AMOUNT OF ORDER ORDHDR
43 +ðððð26 ð6 CUSTYP PIC S9(1) COMP-3. ORDHDR
+ðððð27\ CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5=OT ORDHDR
44 +ðððð28 ð6 PRTDAT PIC S9(6) COMP-3. ORDHDR
+ðððð29\ DATE ORDER WAS PRINTED ORDHDR
45 +ðððð3ð ð6 OPNSTS PIC S9(1) COMP-3. ORDHDR
+ðððð31\ ORDER OPEN STATUS 1=OPEN 2= CLOSE 3=CANCEL ORDHDR
46 +ðððð32 ð6 TOTLIN PIC S9(3) COMP-3. ORDHDR
+ðððð33\ TOTAL LINE ITEMS IN ORDER ORDHDR
47 +ðððð34 ð6 ACTMTH PIC S9(2) COMP-3. ORDHDR
+ðððð35\ ACCOUNTING MONTH OF SALE ORDHDR
48 +ðððð36 ð6 ACTYR PIC S9(2) COMP-3. ORDHDR
+ðððð37\ ACCOUNTING YEAR OF SALE ORDHDR
49 +ðððð38 ð6 STATE PIC X(2). ORDHDR
+ðððð39\ STATE ORDHDR
5ð +ðððð4ð ð6 AMPAID PIC S9(6)V9(2) COMP-3. ORDHDR
+ðððð41\ AMOUNT PAID ORDHDR
51 ðð34ðð 66 COMP-KEY RENAMES CUST THRU INVNUM.
ðð35ðð

Figure 74 (Part 1 of 8). Source Listing of a Payment Update Program Example

Chapter 8. Transaction Files 221


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
52 ðð36ðð FD CUSTOMER-MASTER-FILE
53 ðð37ðð LABEL RECORDS ARE STANDARD.
54 ðð38ðð ð1 CUSTOMER-MASTER-RECORD.
55 ðð39ðð COPY DDS-CUSMST OF CUSMSTP.
+ððððð1\ I-O FORMAT:CUSMST FROM FILE CUSMSTP OF LIBRARY XMPLIB CUSMST
+ððððð2\ CUSTOMER MASTER RECORD CUSMST
+ððððð3\THE KEY DEFINITIONS FOR RECORD FORMAT CUSMST CUSMST
+ððððð4\ NUMBER NAME RETRIEVAL TYPE ALTSEQ CUSMST
+ððððð5\ ððð1 CUST ASCENDING AN NO CUSMST
56 +ððððð6 ð5 CUSMST. CUSMST
57 +ððððð7 ð6 CUST PIC X(5). CUSMST
+ððððð8\ CUSTOMER NUMBER CUSMST
58 +ððððð9 ð6 NAME PIC X(25). CUSMST
+ðððð1ð\ CUSTOMER NAME CUSMST
59 +ðððð11 ð6 ADDR PIC X(2ð). CUSMST
+ðððð12\ CUSTOMER ADDRESS CUSMST
6ð +ðððð13 ð6 CITY PIC X(2ð). CUSMST
+ðððð14\ CUSTOMER CITY CUSMST
61 +ðððð15 ð6 STATE PIC X(2). CUSMST
+ðððð16\ STATE CUSMST
62 +ðððð17 ð6 ZIP PIC S9(5) COMP-3. CUSMST
+ðððð18\ ZIP CODE CUSMST
63 +ðððð19 ð6 SRHCOD PIC X(6). CUSMST
+ðððð2ð\ CUSTOMER NUMBER SEARCH CODE CUSMST
64 +ðððð21 ð6 CUSTYP PIC S9(1) COMP-3. CUSMST
+ðððð22\ CUSTOMER TYPE 1=GOV 2=SCH 3=BUS 4=PVT 5=OT CUSMST
65 +ðððð23 ð6 ARBAL PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð24\ ACCOUNTS REC. BALANCE CUSMST
66 +ðððð25 ð6 ORDBAL PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð26\ A/R AMT. IN ORDER FILE CUSMST
67 +ðððð27 ð6 LSTAMT PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð28\ LAST AMT. PAID IN A/R CUSMST
68 +ðððð29 ð6 LSTDAT PIC S9(6) COMP-3. CUSMST
+ðððð3ð\ LAST DATE PAID IN A/R CUSMST
69 +ðððð31 ð6 CRDLMT PIC S9(6)V9(2) COMP-3. CUSMST
+ðððð32\ CUSTOMER CREDIT LIMIT CUSMST
7ð +ðððð33 ð6 SLSYR PIC S9(8)V9(2) COMP-3. CUSMST
+ðððð34\ CUSTOMER SALES THIS YEAR CUSMST
71 +ðððð35 ð6 SLSLYR PIC S9(8)V9(2) COMP-3. CUSMST
+ðððð36\ CUSTOMER SALES LAST YEAR CUSMST
ðð4ððð
72 ðð41ðð FD PAYMENT-UPDATE-DISPLAY-FILE
73 ðð42ðð LABEL RECORDS ARE OMITTED.
74 ðð43ðð ð1 PAYMENT-UPDATE-DISPLAY-RECORD.
75 ðð44ðð COPY DDS-ALL-FORMATS OF PAYUPDTD.
76 +ððððð1 ð5 PAYUPDTD-RECORD PIC X(59). <-ALL-FMTS
+ððððð2\ INPUT FORMAT:SUBFILE1 FROM FILE PAYUPDTD OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ SUBFILE FOR CUSTOMER PAYMENT <-ALL-FMTS
77 +ððððð4 ð5 SUBFILE1-I REDEFINES PAYUPDTD-RECORD. <-ALL-FMTS
78 +ððððð5 ð6 ACPPMT PIC X(4). <-ALL-FMTS
+ððððð6\ ACCEPT PAYMENT <-ALL-FMTS
79 +ððððð7 ð6 CUST PIC X(5). <-ALL-FMTS
+ððððð8\ CUSTOMER NUMBER <-ALL-FMTS
8ð +ððððð9 ð6 AMPAID PIC S9(6)V9(2). <-ALL-FMTS
+ðððð1ð\ AMOUNT PAID <-ALL-FMTS
81 +ðððð11 ð6 ECPMSG PIC X(31). <-ALL-FMTS
+ðððð12\ EXCEPTION MESSAGE <-ALL-FMTS
82 +ðððð13 ð6 OVRPMT PIC S9(6)V9(2). <-ALL-FMTS
+ðððð14\ OVERPAYMENT <-ALL-FMTS
83 +ðððð15 ð6 STSCDE PIC X(1). <-ALL-FMTS
+ðððð16\ STATUS CODE <-ALL-FMTS
+ðððð17\ OUTPUT FORMAT:SUBFILE1 FROM FILE PAYUPDTD OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð18\ SUBFILE FOR CUSTOMER PAYMENT <-ALL-FMTS
84 +ðððð19 ð5 SUBFILE1-O REDEFINES PAYUPDTD-RECORD. <-ALL-FMTS
85 +ðððð2ð ð6 SUBFILE1-O-INDIC. <-ALL-FMTS
86 +ðððð21 ð7 IN51 PIC 1 INDIC 51. <-ALL-FMTS
87 +ðððð22 ð7 IN52 PIC 1 INDIC 52. <-ALL-FMTS
88 +ðððð23 ð7 IN53 PIC 1 INDIC 53. <-ALL-FMTS
89 +ðððð24 ð7 IN54 PIC 1 INDIC 54. <-ALL-FMTS
9ð +ðððð25 ð7 IN55 PIC 1 INDIC 55. <-ALL-FMTS
91 +ðððð26 ð7 IN56 PIC 1 INDIC 56. <-ALL-FMTS
92 +ðððð27 ð6 CUST PIC X(5). <-ALL-FMTS
+ðððð28\ CUSTOMER NUMBER <-ALL-FMTS
93 +ðððð29 ð6 AMPAID PIC S9(6)V9(2). <-ALL-FMTS
+ðððð3ð\ AMOUNT PAID <-ALL-FMTS
94 +ðððð31 ð6 ECPMSG PIC X(31). <-ALL-FMTS
+ðððð32\ EXCEPTION MESSAGE <-ALL-FMTS

Figure 74 (Part 2 of 8). Source Listing of a Payment Update Program Example

222 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
95 +ðððð33 ð6 OVRPMT PIC S9(6)V9(2). <-ALL-FMTS
+ðððð34\ OVERPAYMENT <-ALL-FMTS
96 +ðððð35 ð6 STSCDE PIC X(1). <-ALL-FMTS
+ðððð36\ STATUS CODE <-ALL-FMTS
+ðððð37\ INPUT FORMAT:CONTROL1 FROM FILE PAYUPDTD OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð38\ SUBFILE CONTROL <-ALL-FMTS
97 +ðððð39 ð5 CONTROL1-I REDEFINES PAYUPDTD-RECORD. <-ALL-FMTS
98 +ðððð4ð ð6 CONTROL1-I-INDIC. <-ALL-FMTS
99 +ðððð41 ð7 IN99 PIC 1 INDIC 99. <-ALL-FMTS
+ðððð42\ HELP KEY <-ALL-FMTS
1ðð +ðððð43 ð7 IN98 PIC 1 INDIC 98. <-ALL-FMTS
+ðððð44\ END PAYMENT UPDATE <-ALL-FMTS
1ð1 +ðððð45 ð7 IN97 PIC 1 INDIC 97. <-ALL-FMTS
+ðððð46\ IGNORE INPUT <-ALL-FMTS
+ðððð47\ OUTPUT FORMAT:CONTROL1 FROM FILE PAYUPDTD OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð48\ SUBFILE CONTROL <-ALL-FMTS
1ð2 +ðððð49 ð5 CONTROL1-O REDEFINES PAYUPDTD-RECORD. <-ALL-FMTS
1ð3 +ðððð5ð ð6 CONTROL1-O-INDIC. <-ALL-FMTS
1ð4 +ðððð51 ð7 IN61 PIC 1 INDIC 61. <-ALL-FMTS
1ð5 +ðððð52 ð7 IN62 PIC 1 INDIC 62. <-ALL-FMTS
1ð6 +ðððð53 ð7 IN99 PIC 1 INDIC 99. <-ALL-FMTS
+ðððð54\ HELP KEY <-ALL-FMTS
1ð7 +ðððð55 ð7 IN63 PIC 1 INDIC 63. <-ALL-FMTS
1ð8 +ðððð56 ð7 IN64 PIC 1 INDIC 64. <-ALL-FMTS
+ðððð57\ INPUT FORMAT:MESSAGE1 FROM FILE PAYUPDTD OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð58\ MESSAGE RECORD <-ALL-FMTS
+ðððð59\ ð5 MESSAGE1-I REDEFINES PAYUPDTD-RECORD. <-ALL-FMTS
+ðððð6ð\ OUTPUT FORMAT:MESSAGE1 FROM FILE PAYUPDTD OF LIBRARY XMPLIB <-ALL-FMTS
+ðððð61\ MESSAGE RECORD <-ALL-FMTS
1ð9 +ðððð62 ð5 MESSAGE1-O REDEFINES PAYUPDTD-RECORD. <-ALL-FMTS
11ð +ðððð63 ð6 MESSAGE1-O-INDIC. <-ALL-FMTS
111 +ðððð64 ð7 IN71 PIC 1 INDIC 71. <-ALL-FMTS
ðð45ðð
112 ðð46ðð WORKING-STORAGE SECTION.
ðð47ðð
113 ðð48ðð ð1 REL-NUMBER PIC 9(ð5)
114 ðð49ðð VALUE ZEROS.
ðð5ððð
115 ðð51ðð ð1 WS-CONTROL.
116 ðð52ðð ð5 WS-IND PIC X(ð2).
117 ðð53ðð ð5 WS-FORMAT PIC X(1ð).
118 ðð54ðð ð1 SYSTEM-DATE.
119 ðð55ðð ð5 SYSTEM-YEAR PIC 99.
12ð ðð56ðð ð5 SYSTEM-MONTH PIC 99.
121 ðð57ðð ð5 SYSTEM-DAY PIC 99.
122 ðð58ðð ð1 PROGRAM-DATE.
123 ðð59ðð ð5 PROGRAM-MONTH PIC 99.
124 ðð6ððð ð5 PROGRAM-DAY PIC 99.
125 ðð61ðð ð5 PROGRAM-YEAR PIC 99.
126 ðð62ðð ð1 FILE-DATE REDEFINES PROGRAM-DATE
127 ðð63ðð PIC S9(6).
128 ðð64ðð ð1 EXCEPTION-STATUS.
129 ðð65ðð ð5 STATUS-CODE-ONE PIC XX.
13ð ðð66ðð 88 SUBFILE-IS-FULL VALUE '9M'.
131 ðð67ðð ð1 EXCEPTION-MESSAGES.
132 ðð68ðð ð5 MESSAGE-ONE PIC X(31)
133 ðð69ðð VALUE 'CUSTOMER DOES NOT EXIST '.
134 ðð7ððð ð5 MESSAGE-TWO PIC X(31)
135 ðð71ðð VALUE 'NO INVOICES EXIST FOR CUSTOMER '.
136 ðð72ðð ð5 MESSAGE-THREE PIC X(31)
137 ðð73ðð VALUE 'CUSTOMER HAS AN OVER PAYMENT OF'.
138 ðð74ðð ð1 PROGRAM-VARIABLES.
139 ðð75ðð ð5 AMOUNT-OWED PIC S9(6)V99.
14ð ðð76ðð ð5 AMOUNT-PAID PIC S9(6)V99.
141 ðð77ðð ð5 INVOICE-BALANCE PIC S9(6)V99.
142 ðð78ðð ð1 ERRPGM-PARAMETERS.
143 ðð79ðð ð5 DISPLAY-PARAMETER PIC X(8)
144 ðð8ððð VALUE 'PAYUPDTD'.
145 ðð81ðð ð5 DUMMY-ONE PIC X(6)
146 ðð82ðð VALUE SPACES.
147 ðð83ðð ð5 DUMMY-TWO PIC X(6)
148 ðð84ðð VALUE SPACES.
149 ðð85ðð ð5 STATUS-CODE-TWO.
15ð ðð86ðð 1ð PRIMARY PIC X(1).
151 ðð87ðð 1ð SECONDARY PIC X(1).

Figure 74 (Part 3 of 8). Source Listing of a Payment Update Program Example

Chapter 8. Transaction Files 223


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
152 ðð88ðð 1ð FILLER PIC X(5)
153 ðð89ðð VALUE SPACES.
154 ðð9ððð ð5 DUMMY-THREE PIC X(1ð)
155 ðð91ðð VALUE SPACES.
ðð92ðð
156 ðð93ðð ð1 SWITCH-AREA.
157 ðð94ðð ð5 SWð1 PIC 1.
158 ðð95ðð 88 WRITE-DISPLAY VALUE B'1'.
159 ðð96ðð 88 READ-DISPLAY VALUE B'ð'.
16ð ðð97ðð ð5 SWð2 PIC 1.
161 ðð98ðð 88 SUBFILE1-FORMAT VALUE B'1'.
162 ðð99ðð 88 NOT-SUBFILE1-FORMAT VALUE B'ð'.
163 ð1ðððð ð5 SWð3 PIC 1.
164 ð1ð1ðð 88 CONTROL1-FORMAT VALUE B'1'.
165 ð1ð2ðð 88 NOT-CONTROL1-FORMAT VALUE B'1'.
166 ð1ð3ðð ð5 SWð4 PIC 1.
167 ð1ð4ðð 88 NO-MORE-TRANSACTIONS-EXIST VALUE B'1'.
168 ð1ð5ðð 88 TRANSACTIONS-EXIST VALUE B'ð'.
169 ð1ð6ðð ð5 SWð5 PIC 1.
17ð ð1ð7ðð 88 CUSTOMER-NOT-FOUND VALUE B'1'.
171 ð1ð8ðð 88 CUSTOMER-EXIST VALUE B'ð'.
172 ð1ð9ðð ð5 SWð6 PIC 1.
173 ð11ððð 88 NO-MORE-INVOICES-EXIST VALUE B'1'.
174 ð111ðð 88 CUSTOMER-INVOICE-EXIST VALUE B'ð'.
175 ð112ðð ð5 SWð7 PIC 1.
176 ð113ðð 88 NO-MORE-PAYMENT-EXIST VALUE B'ð'.
177 ð114ðð 88 PAYMENT-EXIST VALUE B'ð'.
178 ð115ðð ð5 SWð8 PIC 1.
179 ð116ðð 88 INPUT-ERRORS-EXIST VALUE B'1'.
18ð ð117ðð 88 NO-INPUT-ERRORS-EXIST VALUE B'ð'.
181 ð118ðð ð5 SWð9 PIC 1.
182 ð119ðð 88 OVER-PAYMENT-DISPLAYED-ONCE VALUE B'1'.
183 ð12ððð 88 OVER-PAYMENT-NOT-DISPLAYED VALUE B'ð'.
ð121ðð
184 ð122ðð ð1 INDICATOR-AREA.
185 ð123ðð ð5 IN99 PIC 1 INDIC 99.
186 ð124ðð 88 HELP-IS-NEEDED VALUE B'1'.
187 ð125ðð 88 HELP-IS-NOT-NEEDED VALUE B'ð'.
188 ð126ðð ð5 IN98 PIC 1 INDIC 98.
189 ð127ðð 88 END-OF-PAYMENT-UPDATE VALUE B'1'.
19ð ð128ðð ð5 IN97 PIC 1 INDIC 97.
191 ð129ðð 88 IGNORE-INPUT VALUE B'1'.
192 ð13ððð ð5 IN51 PIC 1 INDIC 51.
193 ð131ðð 88 DISPLAY-ACCEPT-PAYMENT VALUE B'1'.
194 ð132ðð 88 DO-NOT-DISPLAY-ACCEPT-PAYMENT VALUE B'ð'.
195 ð133ðð ð5 IN52 PIC 1 INDIC 52.
196 ð134ðð 88 REVERSE-FIELD-IMAGE VALUE B'1'.
197 ð135ðð 88 DO-NOT-REVERSE-FIELD-IMAGE VALUE B'ð'.
198 ð136ðð ð5 IN53 PIC 1 INDIC 53.
199 ð137ðð 88 DO-NOT-DISPLAY-FIELD VALUE B'1'.
2ðð ð138ðð 88 DISPLAY-FIELD VALUE B'ð'.
2ð1 ð139ðð ð5 IN54 PIC 1 INDIC 54.
2ð2 ð14ððð 88 PROTECT-INPUT-FIELD VALUE B'1'.
2ð3 ð141ðð 88 DO-NOT-PROTECT-INPUT-FIELD VALUE B'ð'.
2ð4 ð142ðð ð5 IN55 PIC 1 INDIC 55.
2ð5 ð143ðð 88 MAKE-FIELD-BLINK VALUE B'1'.
2ð6 ð144ðð 88 DO-NOT-MAKE-FIELD-BLINK VALUE B'ð'.
2ð7 ð145ðð ð5 IN56 PIC 1 INDIC 56.
2ð8 ð146ðð 88 DISPLAY-OVER-PAYMENT VALUE B'1'.
2ð9 ð147ðð 88 DO-NOT-DISPLAY-OVER-PAYMENT VALUE B'ð'.
21ð ð148ðð ð5 IN61 PIC 1 INDIC 61.
211 ð149ðð 88 CLEAR-SUBFILE VALUE B'1'.
212 ð15ððð 88 DO-NOT-CLEAR-SUBFILE VALUE B'ð'.
213 ð151ðð ð5 IN62 PIC 1 INDIC 62.
214 ð152ðð 88 DISPLAY-SCREEN VALUE B'1'.
215 ð153ðð 88 DO-NOT-DISPLAY-SCREEN VALUE B'ð'.
216 ð154ðð ð5 IN63 PIC 1 INDIC 63.
217 ð155ðð 88 DISPLAY-ACCEPT-HEADING VALUE B'1'.
218 ð156ðð 88 DO-NOT-DISPLAY-ACCEPT-HEADING VALUE B'ð'.
219 ð157ðð ð5 IN64 PIC 1 INDIC 64.
22ð ð158ðð 88 DISPLAY-EXCEPTION VALUE B'1'.
221 ð159ðð 88 DO-NOT-DISPLAY-EXCEPTION VALUE B'ð'.
222 ð16ððð ð5 IN71 PIC 1 INDIC 71.
223 ð161ðð 88 DISPLAY-ACCEPT-MESSAGE VALUE B'1'.
224 ð162ðð 88 DO-NOT-DISPLAY-ACCEPT-MESSAGE VALUE B'ð'.
ð163ðð

Figure 74 (Part 4 of 8). Source Listing of a Payment Update Program Example

224 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
225 ð164ðð PROCEDURE DIVISION.
ð165ðð
ð166ðð DECLARATIVES.
ð167ðð
ð168ðð TRANSACTION-ERROR SECTION.
ð169ðð USE AFTER STANDARD ERROR PROCEDURE
ð17ððð PAYMENT-UPDATE-DISPLAY-FILE.
ð171ðð WORK-STATION-ERROR-HANDLER.
226 ð172ðð IF SUBFILE-IS-FULL THEN
ð173ðð NEXT SENTENCE
ð174ðð ELSE
227 ð175ðð DISPLAY 'ERROR IN PAYMENT-UPDATE' STATUS-CODE-ONE.
ð176ðð END DECLARATIVES.
ð177ðð
ð178ðð CUSTOMER-PAYMENT-UPDATE SECTION.
ð179ðð MAINLINE-ROUTINE.
228 ð18ððð PERFORM SET-UP-ROUTINE.
229 ð181ðð PERFORM PROCESS-TRANSACTION-FILE
ð182ðð UNTIL END-OF-PAYMENT-UPDATE.
23ð ð183ðð PERFORM CLEAN-UP-ROUTINE.
ð184ðð
ð185ðð SET-UP-ROUTINE.
231 ð186ðð OPEN I-O CUSTOMER-INVOICE-FILE
ð187ðð CUSTOMER-MASTER-FILE
ð188ðð PAYMENT-UPDATE-DISPLAY-FILE.
232 ð189ðð MOVE ALL B'ð' TO INDICATOR-AREA
ð19ððð SWITCH-AREA.
233 ð191ðð ACCEPT SYSTEM-DATE FROM DATE.
234 ð192ðð MOVE SYSTEM-YEAR TO PROGRAM-YEAR.
235 ð193ðð MOVE SYSTEM-MONTH TO PROGRAM-MONTH.
236 ð194ðð MOVE SYSTEM-DATE TO PROGRAM-DAY.
237 ð195ðð SET WRITE-DISPLAY
ð196ðð CONTROL1-FORMAT
ð197ðð DO-NOT-DISPLAY-OVER-PAYMENT
ð198ðð DO-NOT-PROTECT-INPUT-FIELD
ð199ðð DO-NOT-REVERSE-FIELD-IMAGE
ð2ðððð DO-NOT-MAKE-FIELD-BLINK
ð2ð1ðð CLEAR-SUBFILE TO TRUE.
238 ð2ð2ðð MOVE CORR INDICATOR-AREA TO CONTROL1-O-INDIC.
239 ð2ð3ðð WRITE PAYMENT-UPDATE-DISPLAY-RECORD
ð2ð4ðð FORMAT IS 'CONTROL1'.
24ð ð2ð5ðð SET DO-NOT-CLEAR-SUBFILE TO TRUE.
241 ð2ð6ðð PERFORM INITIALIZE-SUBFILE-RECORD 17 TIMES.
242 ð2ð7ðð SET DISPLAY-SCREEN TO TRUE.
243 ð2ð8ðð MOVE CORR INDICATOR-AREA TO CONTROL1-O-INDIC.
244 ð2ð9ðð WRITE PAYMENT-UPDATE-DISPLAY-RECORD
ð21ððð FORMAT IS 'CONTROL1'.
245 ð211ðð READ PAYMENT-UPDATE-DISPLAY-FILE RECORD
ð212ðð FORMAT IS 'CONTROL1'.
246 ð213ðð MOVE CORR CONTROL1-I-INDIC TO INDICATOR-AREA.
ð214ðð PROCESS-TRANSACTION-FILE.
247 ð215ðð IF HELP-IS-NOT-NEEDED THEN
248 ð216ðð IF IGNORE-INPUT THEN
249 ð217ðð SET WRITE-DISPLAY
ð218ðð CONTROL1-FORMAT
ð219ðð CLEAR-SUBFILE
ð22ððð DISPLAY-FIELD
ð221ðð DO-NOT-DISPLAY-OVER-PAYMENT
ð222ðð DO-NOT-PROTECT-INPUT-FIELD
ð223ðð DO-NOT-REVERSE-FIELD-IMAGE
ð224ðð DO-NOT-DISPLAY-ACCEPT-PAYMENT
ð225ðð DO-NOT-DISPLAY-ACCEPT-HEADING
ð226ðð DO-NOT-DISPLAY-ACCEPT-MESSAGE
ð227ðð DO-NOT-MAKE-FIELD-BLINK TO TRUE
25ð ð228ðð MOVE CORR INDICATOR-AREA TO CONTROL1-O-INDIC
251 ð229ðð WRITE PAYMENT-UPDATE-DISPLAY-RECORD
ð23ððð FORMAT IS 'CONTROL1'
252 ð231ðð SET DO-NOT-CLEAR-SUBFILE TO TRUE
253 ð232ðð MOVE ð TO REL-NUMBER
254 ð233ðð PERFORM INITIALIZE-SUBFILE-RECORD 17 TIMES
ð234ðð ELSE
255 ð235ðð SET TRANSACTIONS-EXIST
ð236ðð DO-NOT-DISPLAY-ACCEPT-HEADING
ð237ðð DO-NOT-DISPLAY-ACCEPT-MESSAGE
ð238ðð DO-NOT-DISPLAY-EXCEPTION TO TRUE
256 ð239ðð PERFORM READ-MODIFIED-SUBFILE-RECORD

Figure 74 (Part 5 of 8). Source Listing of a Payment Update Program Example

Chapter 8. Transaction Files 225


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
257 ð24ððð PERFORM TRANSACTION-VALIDATION
ð241ðð UNTIL NO-MORE-TRANSACTIONS-EXIST
258 ð242ðð SET NO-INPUT-ERRORS-EXIST TO TRUE
259 ð243ðð PERFORM TEST-FOR-RECORD-INPUT-ERRORS
ð244ðð VARYING REL-NUMBER
ð245ðð FROM 1
ð246ðð BY 1
ð247ðð UNTIL REL-NUMBER IS GREATER THAN 17
ð248ðð OR INPUT-ERRORS-EXIST
26ð ð249ðð IF NO-INPUT-ERRORS-EXIST THEN
261 ð25ððð IF OVER-PAYMENT-DISPLAYED-ONCE THEN
262 ð251ðð SET WRITE-DISPLAY
ð252ðð CONTROL1-FORMAT
ð253ðð DO-NOT-DISPLAY-OVER-PAYMENT
ð254ðð DO-NOT-PROTECT-INPUT-FIELD
ð255ðð DO-NOT-REVERSE-FIELD-IMAGE
ð256ðð DO-NOT-MAKE-FIELD-BLINK
ð257ðð DO-NOT-DISPLAY-ACCEPT-PAYMENT
ð258ðð DO-NOT-DISPLAY-ACCEPT-HEADING
ð259ðð DO-NOT-DISPLAY-ACCEPT-MESSAGE
ð26ððð DO-NOT-DISPLAY-EXCEPTION
ð261ðð CLEAR-SUBFILE
ð262ðð DISPLAY-FIELD
ð263ðð TO TRUE
263 ð264ðð MOVE CORR INDICATOR-AREA TO CONTROL1-O-INDIC
264 ð265ðð WRITE PAYMENT-UPDATE-DISPLAY-RECORD
ð266ðð FORMAT IS 'CONTROL1'
265 ð267ðð SET DO-NOT-CLEAR-SUBFILE TO TRUE
266 ð268ðð MOVE ð TO REL-NUMBER
267 ð269ðð PERFORM INITIALIZE-SUBFILE-RECORD 17 TIMES
ð27ððð ELSE
268 ð271ðð SET OVER-PAYMENT-DISPLAYED-ONCE TO TRUE
ð272ðð ELSE
ð273ðð NEXT SENTENCE
ð274ðð ELSE
ð275ðð NEXT SENTENCE.
269 ð276ðð SET WRITE-DISPLAY, DISPLAY-SCREEN TO TRUE.
27ð ð277ðð MOVE CORR INDICATOR-AREA TO MESSAGE1-O-INDIC.
271 ð278ðð WRITE PAYMENT-UPDATE-DISPLAY-RECORD
ð279ðð FORMAT IS 'MESSAGE1'.
272 ð28ððð SET WRITE-DISPLAY, CONTROL1-FORMAT TO TRUE.
273 ð281ðð MOVE CORR INDICATOR-AREA TO CONTROL1-O-INDIC.
274 ð282ðð WRITE PAYMENT-UPDATE-DISPLAY-RECORD
ð283ðð FORMAT IS 'CONTROL1'.
275 ð284ðð READ PAYMENT-UPDATE-DISPLAY-FILE RECORD
ð285ðð FORMAT IS 'CONTROL1'.
276 ð286ðð MOVE CORR CONTROL1-I-INDIC TO INDICATOR-AREA.
ð287ðð READ-MODIFIED-SUBFILE-RECORD.
277 ð288ðð READ SUBFILE PAYMENT-UPDATE-DISPLAY-FILE
ð289ðð NEXT MODIFIED RECORD FORMAT IS 'SUBFILE1'
278 ð29ððð AT END SET NO-MORE-TRANSACTIONS-EXIST TO TRUE.
ð291ðð TEST-FOR-RECORD-INPUT-ERRORS.
279 ð292ðð READ SUBFILE PAYMENT-UPDATE-DISPLAY-FILE RECORD
ð293ðð FORMAT IS 'SUBFILE1'.
28ð ð294ðð IF STSCDE OF SUBFILE1-I IS EQUAL TO '1' THEN
281 ð295ðð SET INPUT-ERRORS-EXIST TO TRUE
ð296ðð ELSE
ð297ðð NEXT SENTENCE.
ð298ðð TRANSACTION-VALIDATION.
282 ð299ðð MOVE CUST OF SUBFILE1-I OF PAYMENT-UPDATE-DISPLAY-RECORD
ð3ðððð TO CUST OF CUSTOMER-MASTER-RECORD.
283 ð3ð1ðð SET CUSTOMER-EXIST TO TRUE.
284 ð3ð2ðð READ CUSTOMER-MASTER-FILE
285 ð3ð3ðð INVALID KEY SET CUSTOMER-NOT-FOUND TO TRUE.
286 ð3ð4ðð IF CUSTOMER-EXIST THEN
287 ð3ð5ðð MOVE CUST OF CUSMST TO CUST OF ORDHDR
288 ð3ð6ðð MOVE ZEROES TO INVNUM
289 ð3ð7ðð SET CUSTOMER-INVOICE-EXIST TO TRUE
29ð ð3ð8ðð PERFORM START-ON-CUSTOMER-INVOICE-FILE
291 ð3ð9ðð IF CUSTOMER-INVOICE-EXIST THEN
292 ð31ððð PERFORM READ-CUSTOMER-INVOICE-RECORD
293 ð311ðð IF CUSTOMER-INVOICE-EXIST THEN
294 ð312ðð PERFORM CUSTOMER-MASTER-FILE-UPDATE
295 ð313ðð MOVE AMPAID OF SUBFILE1-I TO AMOUNT-PAID
296 ð314ðð SET PAYMENT-EXIST TO TRUE

Figure 74 (Part 6 of 8). Source Listing of a Payment Update Program Example

226 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
297 ð315ðð PERFORM PAYMENT-UPDATE
ð316ðð UNTIL NO-MORE-INVOICES-EXIST
ð317ðð OR NO-MORE-PAYMENT-EXIST
298 ð318ðð IF ARBAL OF CUSTOMER-MASTER-RECORD IS NEGATIVE
299 ð319ðð SET MAKE-FIELD-BLINK
ð32ððð DISPLAY-FIELD
ð321ðð DO-NOT-REVERSE-FIELD-IMAGE
ð322ðð OVER-PAYMENT-NOT-DISPLAYED
ð323ðð DISPLAY-OVER-PAYMENT
ð324ðð DISPLAY-EXCEPTION
ð325ðð DO-NOT-DISPLAY-ACCEPT-PAYMENT
ð326ðð PROTECT-INPUT-FIELD TO TRUE
3ðð ð327ðð MOVE ARBAL TO OVRPMT OF SUBFILE1-O
3ð1 ð328ðð MOVE MESSAGE-THREE TO ECPMSG OF SUBFILE1-O
3ð2 ð329ðð MOVE 'ð' TO STSCDE OF SUBFILE1-O
3ð3 ð33ððð PERFORM REWRITE-DISPLAY-SUBFILE-RECORD
ð331ðð ELSE
3ð4 ð332ðð SET DO-NOT-DISPLAY-FIELD
ð333ðð DO-NOT-DISPLAY-OVER-PAYMENT
ð334ðð DO-NOT-REVERSE-FIELD-IMAGE
ð335ðð DO-NOT-MAKE-FIELD-BLINK
ð336ðð DO-NOT-DISPLAY-ACCEPT-PAYMENT
ð337ðð PROTECT-INPUT-FIELD TO TRUE
3ð5 ð338ðð MOVE SPACES TO ECPMSG OF SUBFILE1-O
3ð6 ð339ðð MOVE ZEROES TO OVRPMT OF SUBFILE1-O
3ð7 ð34ððð MOVE 'ð' TO STSCDE OF SUBFILE1-O
3ð8 ð341ðð PERFORM REWRITE-DISPLAY-SUBFILE-RECORD
ð342ðð ELSE
3ð9 ð343ðð PERFORM NO-CUSTOMER-INVOICE-ROUTINE
ð344ðð ELSE
31ð ð345ðð PERFORM NO-CUSTOMER-INVOICE-ROUTINE
ð346ðð ELSE
311 ð347ðð SET REVERSE-FIELD-IMAGE
ð348ðð DO-NOT-PROTECT-INPUT-FIELD
ð349ðð DISPLAY-FIELD
ð35ððð DO-NOT-DISPLAY-OVER-PAYMENT
ð351ðð DO-NOT-MAKE-FIELD-BLINK
ð352ðð DISPLAY-EXCEPTION
ð353ðð DO-NOT-DISPLAY-ACCEPT-PAYMENT
ð354ðð DO-NOT-PROTECT-INPUT-FIELD TO TRUE
312 ð355ðð MOVE ZEROES TO OVRPMT OF SUBFILE1-O
313 ð356ðð MOVE MESSAGE-ONE TO ECPMSG OF SUBFILE1-O
314 ð357ðð MOVE '1' TO STSCDE OF SUBFILE1-O
315 ð358ðð PERFORM REWRITE-DISPLAY-SUBFILE-RECORD.
316 ð359ðð PERFORM READ-MODIFIED-SUBFILE-RECORD.
ð36ððð START-ON-CUSTOMER-INVOICE-FILE.
317 ð361ðð START CUSTOMER-INVOICE-FILE
ð362ðð KEY IS GREATER THAN COMP-KEY
318 ð363ðð INVALID KEY SET NO-MORE-INVOICES-EXIST TO TRUE.
ð364ðð READ-CUSTOMER-INVOICE-RECORD.
319 ð365ðð READ CUSTOMER-INVOICE-FILE NEXT RECORD
32ð ð366ðð AT END SET NO-MORE-INVOICES-EXIST TO TRUE.
321 ð367ðð IF CUST OF CUSTOMER-MASTER-RECORD
ð368ðð IS NOT EQUAL TO CUST OF CUSTOMER-INVOICE-RECORD THEN
322 ð369ðð SET NO-MORE-INVOICES-EXIST TO TRUE
ð37ððð ELSE
ð371ðð NEXT SENTENCE.
ð372ðð CUSTOMER-MASTER-FILE-UPDATE.
323 ð373ðð MOVE FILE-DATE TO LSTDAT OF CUSTOMER-MASTER-RECORD.
324 ð374ðð MOVE AMPAID OF SUBFILE1-I
ð375ðð TO LSTAMT OF CUSTOMER-MASTER-RECORD.
325 ð376ðð SUBTRACT AMPAID OF SUBFILE1-I
ð377ðð FROM ARBAL OF CUSTOMER-MASTER-RECORD.
326 ð378ðð REWRITE CUSTOMER-MASTER-RECORD.
ð379ðð REWRITE-DISPLAY-SUBFILE-RECORD.
327 ð38ððð MOVE AMPAID OF SUBFILE1-I TO AMPAID OF SUBFILE1-O.
328 ð381ðð MOVE CUST OF SUBFILE1-I TO CUST OF SUBFILE1-O.
329 ð382ðð SET WRITE-DISPLAY TO TRUE.
33ð ð383ðð SET SUBFILE1-FORMAT TO TRUE.
331 ð384ðð MOVE CORR INDICATOR-AREA TO SUBFILE1-O-INDIC.
332 ð385ðð REWRITE SUBFILE PAYMENT-UPDATE-DISPLAY-RECORD
ð386ðð FORMAT IS 'SUBFILE1'.
ð387ðð NO-CUSTOMER-INVOICE-ROUTINE.
333 ð388ðð IF STSCDE OF SUBFILE1-I IS EQUAL TO '1' THEN
334 ð389ðð IF ACPPMT OF SUBFILE1-I IS EQUAL TO '\NO' THEN
335 ð39ððð SET DO-NOT-DISPLAY-FIELD

Figure 74 (Part 7 of 8). Source Listing of a Payment Update Program Example

Chapter 8. Transaction Files 227


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ð391ðð DO-NOT-DISPLAY-OVER-PAYMENT
ð392ðð DO-NOT-REVERSE-FIELD-IMAGE
ð393ðð DO-NOT-MAKE-FIELD-BLINK
ð394ðð DO-NOT-DISPLAY-ACCEPT-PAYMENT
ð395ðð PROTECT-INPUT-FIELD
ð396ðð TO TRUE
336 ð397ðð MOVE SPACES TO ECPMSG OF SUBFILE1-O
337 ð398ðð MOVE ZEROES TO OVRPMT OF SUBFILE1-O
338 ð399ðð MOVE 'ð' TO STSCDE OF SUBFILE1-O
339 ð4ðððð PERFORM REWRITE-DISPLAY-SUBFILE-RECORD
ð4ð1ðð ELSE
34ð ð4ð2ðð PERFORM CUSTOMER-MASTER-FILE-UPDATE
341 ð4ð3ðð SET MAKE-FIELD-BLINK
ð4ð4ðð DISPLAY-FIELD
ð4ð5ðð DO-NOT-REVERSE-FIELD-IMAGE
ð4ð6ðð OVER-PAYMENT-NOT-DISPLAYED
ð4ð7ðð DISPLAY-OVER-PAYMENT
ð4ð8ðð DISPLAY-EXCEPTION
ð4ð9ðð DO-NOT-DISPLAY-ACCEPT-PAYMENT
ð41ððð PROTECT-INPUT-FIELD
ð411ðð TO TRUE
342 ð412ðð MOVE ARBAL TO OVRPMT OF SUBFILE1-O
343 ð413ðð MOVE MESSAGE-THREE TO ECPMSG OF SUBFILE1-O
344 ð414ðð MOVE 'ð' TO STSCDE OF SUBFILE1-O
345 ð415ðð PERFORM REWRITE-DISPLAY-SUBFILE-RECORD
ð416ðð ELSE
346 ð417ðð SET REVERSE-FIELD-IMAGE
ð418ðð DISPLAY-FIELD
ð419ðð DO-NOT-PROTECT-INPUT-FIELD
ð42ððð DO-NOT-DISPLAY-OVER-PAYMENT
ð421ðð DISPLAY-EXCEPTION
ð422ðð DISPLAY-ACCEPT-PAYMENT
ð423ðð DISPLAY-ACCEPT-HEADING
ð424ðð DISPLAY-ACCEPT-MESSAGE
ð425ðð DO-NOT-MAKE-FIELD-BLINK
ð426ðð TO TRUE
347 ð427ðð MOVE ZEROS TO OVRPMT OF SUBFILE1-O
348 ð428ðð MOVE MESSAGE-TWO TO ECPMSG OF SUBFILE1-O
349 ð429ðð MOVE '1' TO STSCDE OF SUBFILE1-O
35ð ð43ððð PERFORM REWRITE-DISPLAY-SUBFILE-RECORD.
ð431ðð PAYMENT-UPDATE.
351 ð432ðð SUBTRACT AMPAID OF CUSTOMER-INVOICE-RECORD
ð433ðð FROM ORDAMT OF CUSTOMER-INVOICE-RECORD
ð434ðð GIVING AMOUNT-OWED.
352 ð435ðð SUBTRACT AMOUNT-PAID
ð436ðð FROM AMOUNT-OWED
ð437ðð GIVING INVOICE-BALANCE.
353 ð438ðð IF INVOICE-BALANCE IS LESS THAN .ð1 THEN
354 ð439ðð MOVE 2 TO OPNSTS OF CUSTOMER-INVOICE-RECORD
355 ð44ððð MOVE ORDAMT OF CUSTOMER-INVOICE-RECORD
ð441ðð TO AMPAID OF CUSTOMER-INVOICE-RECORD
356 ð442ðð SUBTRACT AMOUNT-OWED
ð443ðð FROM AMOUNT-PAID
ð444ðð ELSE
357 ð445ðð ADD AMOUNT-PAID TO AMPAID OF CUSTOMER-INVOICE-RECORD
358 ð446ðð SET NO-MORE-PAYMENT-EXIST TO TRUE.
359 ð447ðð REWRITE CUSTOMER-INVOICE-RECORD.
36ð ð448ðð IF NO-MORE-PAYMENT-EXIST THEN
ð449ðð NEXT SENTENCE
ð45ððð ELSE
361 ð451ðð PERFORM READ-CUSTOMER-INVOICE-RECORD.
ð452ðð INITIALIZE-SUBFILE-RECORD.
362 ð453ðð MOVE SPACES TO CUST OF SUBFILE1-O.
363 ð454ðð MOVE SPACES TO ECPMSG OF SUBFILE1-O.
364 ð455ðð MOVE 'ð' TO STSCDE OF SUBFILE1-O.
365 ð456ðð MOVE ZEROS TO AMPAID OF SUBFILE1-O.
366 ð457ðð MOVE ZEROS TO OVRPMT OF SUBFILE1-O.
367 ð458ðð ADD 1 TO REL-NUMBER.
368 ð459ðð MOVE CORR INDICATOR-AREA TO SUBFILE1-O-INDIC.
369 ð46ððð WRITE SUBFILE PAYMENT-UPDATE-DISPLAY-RECORD
ð461ðð FORMAT IS 'SUBFILE1'.
ð462ðð CLEAN-UP-ROUTINE.
37ð ð463ðð CLOSE CUSTOMER-INVOICE-FILE
ð464ðð CUSTOMER-MASTER-FILE
ð465ðð PAYMENT-UPDATE-DISPLAY-FILE.
371 ð466ðð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 74 (Part 8 of 8). Source Listing of a Payment Update Program Example

This is the initial display that is written to the work station to prompt you to enter
the customer number and payment:

228 COBOL/400 User’s Guide


à@ ð
Customer Payment Update Prompt Date ð5/24/94

Customer Payment

______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________
______ __________

______ __________
______ __________
______ __________
______ __________
______ __________

á ñ
Enter the customer numbers and payments:

à@ ð
Customer Payment Update Prompt Date ð5/24/94

Customer Payment

345ðð 2ððð
4ð5ðð 3ðððð
36ððð 25ðð
125ðð 2ðð
22799 45ðð
419ðð 75ðð
1ððð1 5ððð
495ðð 25ðð
133ðð 35ðð
569ðð 4ððð

á ñ
Payments that would result in overpayments or that have incorrect customer
numbers are left on the display and appropriate messages are added:

Chapter 8. Transaction Files 229


à@ Customer Payment Update Prompt Date ð5/24/94
ð
Accept Customer Payment Exception Message
Payment

_____ 4ð5ðð 3ðððð NO INVOICES EXIST FOR CUSTOMER

_____ 125ðð 2ðð NO INVOICES EXIST FOR CUSTOMER

_____ 419ðð 75ðð NO INVOICES EXIST FOR CUSTOMER


1ððð1 5ððð CUSTOMER DOES NOT EXIST

_____ 133ðð 35ðð NO INVOICES EXIST FOR CUSTOMER

Accept payment values: (\NO \YES)

á ñ
Indicate which payments to accept:

à@ Customer Payment Update Prompt Date ð5/24/94


ð
Accept Customer Payment Exception Message
Payment

\NO 4ð5ðð 3ðððð NO INVOICES EXIST FOR CUSTOMER

\YES 125ðð 2ðð NO INVOICES EXIST FOR CUSTOMER

\NO 419ðð 75ðð NO INVOICES EXIST FOR CUSTOMER


1ððð1 5ððð CUSTOMER DOES NOT EXIST

\NO 133ðð 35ðð NO INVOICES EXIST FOR CUSTOMER

Accept payment values: (\NO \YES)

á ñ
The accepted payments are processed, and overpayment information is displayed:

230 COBOL/400 User’s Guide


à@ Customer Payment Update Prompt Date ð5/24/94
ð
Accept Customer Payment Exception Message
Payment

125ðð 2ðð CUSTOMER HAS AN OVERPAYMENT OF 58.5ð

1ððð1 5ððð CUSTOMER DOES NOT EXIST

á ñ
End of IBM Extension

Chapter 8. Transaction Files 231


232 COBOL/400 User’s Guide
Chapter 9. Printer Files
This chapter describes how COBOL/400 interacts with the different kinds of printer
files.

You can obtain printed output from a COBOL program by issuing WRITE state-
ments to one or more printer files. Each printer file must have a unique name and
be assigned to a device of PRINTER or FORMATFILE in the ASSIGN clause of
that file’s FILE-CONTROL entry.

A device of PRINTER must be used for program-described files, and a device of


FORMATFILE must be used for externally described printer files. The Create Print
File (CRTPRTF) command can be used to create a printer file (see the CL
Reference for further information on the CRTPRTF command), or one of the
IBM-supplied printer-device files, such as QPRINT can be used.

The file operations that are valid for a printer file are WRITE, OPEN, and CLOSE.
For a complete description of these operations, see the COBOL/400 Reference.

See the DDS Reference for information on the DDS for externally described printer
files. For more information on FORMATFILE files, see “FORMATFILE Files” on
page 234.

SPECIAL-NAMES Paragraph and the ADVANCING Phrase


When the mnemonic-name associated with the function-name CSP is specified in
the ADVANCING phrase of a WRITE statement for a printer file, it has the same
effect as specifying ADVANCING 0 LINES.

When the mnemonic-name associated with the function-name C01 is specified in


the ADVANCING phrase of a WRITE statement for a printer file, it has the same
effect as specifying ADVANCING PAGE.

The ADVANCING phrase cannot be specified in WRITE statements for files


assigned to FORMATFILE.

LINAGE Clause
When the LINAGE clause is specified for a file assigned to PRINTER, all spacing
and paging controls are handled internally by compiler generated code.

Paper positioning is done only when the first WRITE statement is run. The paper
in the printer is positioned to a new physical page, and the LINAGE-COUNTER is
set to 1. When the printer file is shared and other programs have written records to
the file, the COBOL WRITE statement is still considered to be the first WRITE
statement. Paper positioning is handled by the COBOL/400 compiler even though
it is not the first WRITE statement for that file.

All spacing and paging for WRITE statements is controlled internally. The physical
size of the page is ignored when paper positioning is not properly defined for the
COBOL/400 compiler. For a file that has a LINAGE clause and is assigned to
PRINTER, paging consists of spacing to the end of the logical page (page body)
and then spacing past the bottom and top margins.

 Copyright IBM Corp. 1994 233


Use of the LINAGE clause degrades performance. The LINAGE clause should be
used only as necessary. If the physical paging is acceptable, the LINAGE clause is
not necessary.

The LINAGE clause should not be used for files assigned to FORMATFILE.

FORMATFILE Files
Externally described printer files must be assigned to a device of FORMATFILE.
The term FORMATFILE is used because the FORMAT phrase is valid in WRITE
statements for the file, and the data formatting is specified in the DDS for the file.

When you have specified a device of FORMATFILE, you can obtain formatting of
printed output in two ways:
1. Choose the formats to print and their order by using appropriate values in the
FORMAT phrases specified for WRITE statements. For example, use one
format once per page to produce a heading, and use another format to produce
the detail lines on the page.
2. Choose the appropriate options to be taken when each format is printed by
setting indicator values and passing these indicators through the INDICATOR
phrase for the WRITE statement. For example, fields may be underlined, blank
lines may be produced before or after the format is printed, or the printing of
certain fields may be skipped.

The use of external descriptions for printer files has the following advantages over
program descriptions:
Ÿ Multiple lines can be printed by one WRITE statement. When multiple lines are
written by one WRITE statement and the END-OF-PAGE condition is reached,
the END-OF-PAGE imperative statement is processed after all of the lines are
printed. It is possible to print lines in the overflow area, and onto the next page
before the END-OF-PAGE imperative statement is processed.
Figure 75 on page 235 shows an example of an occurrence of the
END-OF-PAGE condition through FORMATFILE.
Ÿ Optional printing of fields based on indicator values is possible.
Ÿ Editing of field values is easily defined.
Ÿ Maintenance of print formats, especially those used by multiple programs, is
easier.

Use of the ADVANCING phrase for FORMATFILE files causes a compilation error
to be issued. Advancing of lines is controlled in a FORMATFILE file through DDS
keywords, such as SKIPA and SKIPB, and through the use of line numbers.

For FORMATFILE files, the LINAGE clause is invalid.

234 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð2/ð1/94
2 ððð2ðð PROGRAM-ID. FRMTFILE. ð3/22/94
3 ððð3ðð AUTHOR. PROGRAMMER NAME. ð1/27/94
4 ððð4ðð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE. ð1/27/94
5 ððð5ðð DATE-WRITTEN. ð2/ð2/89. ð2/ð4/94
8 ðððð8ð DATE-COMPILED. ð5/24/94 14:29:31 . ð3/ð1/94
7 ððð7ðð ENVIRONMENT DIVISION. ð1/27/94
8 ððð8ðð CONFIGURATION SECTION. ð1/27/94
9 ððð9ðð SOURCE-COMPUTER. IBM-AS4ðð. ð1/27/94
1ð ðð1ððð OBJECT-COMPUTER. IBM-AS4ðð. ð1/27/94
11 ðð11ðð INPUT-OUTPUT SECTION. ð1/27/94
12 ðð12ðð FILE-CONTROL. ð1/27/94
13 ðð13ðð SELECT PERSREPT ASSIGN TO FORMATFILE-PERSREPT-SI .1/ ð2/ð4/94
14 ðð14ðð ORGANIZATION IS SEQUENTIAL. ð2/ð4/94
15 ðð15ðð SELECT PERSFILE ASSIGN TO DATABASE-PERSFILE ð2/ð4/94
16 ðð16ðð ORGANIZATION IS INDEXED ð2/ð4/94
17 ðð17ðð ACCESS MODE IS SEQUENTIAL ð2/ð4/94
18 ðð18ðð RECORD IS EXTERNALLY-DESCRIBED-KEY. ð2/ð4/94
19 ðð19ðð DATA DIVISION. ð1/27/94
2ð ðð2ððð FILE SECTION. ð1/27/94
21 ðð21ðð FD PERSREPT ð2/ð4/94
22 ðð22ðð LABEL RECORDS ARE STANDARD. ð2/ð4/94
23 ðð23ðð ð1 PERSREPT-REC. ð2/ð4/94
24 ðð24ðð COPY DDS-ALL-FORMATS-O OF PERSREPT. .2/
25 +ððððð1 ð5 PERSREPT-RECORD PIC X(13ð). <-ALL-FMTS
+ððððð2\ OUTPUT FORMAT:HEADING FROM FILE PERSREPT OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
26 +ððððð4 ð5 HEADING-O REDEFINES PERSREPT-RECORD. <-ALL-FMTS
27 +ððððð5 ð6 ORDERTYPE PIC X(15). <-ALL-FMTS
+ððððð6\ OUTPUT FORMAT:DETAIL FROM FILE PERSREPT OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð7\ <-ALL-FMTS
28 +ððððð8 ð5 DETAIL-O REDEFINES PERSREPT-RECORD. .3/ <-ALL-FMTS
29 +ððððð9 ð6 NAME PIC X(3ð). <-ALL-FMTS
3ð +ðððð1ð ð6 EMPLNO PIC S9(6). <-ALL-FMTS
31 +ðððð11 ð6 BIRTHDATE PIC X(6). <-ALL-FMTS
32 +ðððð12 ð6 ADDRESS1 PIC X(35). <-ALL-FMTS
33 +ðððð13 ð6 MARSTAT PIC X(1). <-ALL-FMTS
34 +ðððð14 ð6 SPOUSENAME PIC X(3ð). <-ALL-FMTS
35 +ðððð15 ð6 ADDRESS2 PIC X(2ð). <-ALL-FMTS
36 +ðððð16 ð6 NUMCHILD PIC S9(2). <-ALL-FMTS
37 ðð25ðð FD PERSFILE
38 ðð26ðð LABEL RECORDS ARE STANDARD.
39 ðð27ðð ð1 PERSFILE-REC.
4ð ðð28ðð COPY DDS-ALL-FORMATS-O OF PERSFILE.
41 +ððððð1 ð5 PERSFILE-RECORD PIC X(13ð). <-ALL-FMTS
+ððððð2\ I-O FORMAT:PERSREC FROM FILE PERSFILE OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
+ððððð4\THE KEY DEFINITIONS FOR RECORD FORMAT PERSREC <-ALL-FMTS
+ððððð5\ NUMBER NAME RETRIEVAL TYPE ALTSEQ <-ALL-FMTS
+ððððð6\ ððð1 EMPLNO ASCENDING SIGNED NO <-ALL-FMTS
42 +ððððð7 ð5 PERSREC REDEFINES PERSFILE-RECORD. <-ALL-FMTS
43 +ððððð8 ð6 EMPLNO PIC S9(6). <-ALL-FMTS
44 +ððððð9 ð6 NAME PIC X(3ð). <-ALL-FMTS
45 +ðððð1ð ð6 ADDRESS1 PIC X(35). <-ALL-FMTS
46 +ðððð11 ð6 ADDRESS2 PIC X(2ð). <-ALL-FMTS
47 +ðððð12 ð6 BIRTHDATE PIC X(6). <-ALL-FMTS
48 +ðððð13 ð6 MARSTAT PIC X(1). <-ALL-FMTS
49 +ðððð14 ð6 SPOUSENAME PIC X(3ð). <-ALL-FMTS
5ð +ðððð15 ð6 NUMCHILD PIC S9(2). <-ALL-FMTS
51 ðð29ðð WORKING-STORAGE SECTION.
52 ðð3ððð 77 HEAD-ORDER PIC X(15)
53 ðð31ðð VALUE "EMPLOYEE NUMBER".
54 ðð32ðð ð1 PERSREPT-INDICS.
55 ðð33ðð COPY DDS-ALL-FORMATS-O-INDIC OF PERSREPT. .4/
56 +ððððð1 ð5 PERSREPT-RECORD. <-ALL-FMTS
+ððððð2\ OUTPUT FORMAT:HEADING FROM FILE PERSREPT OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð3\ <-ALL-FMTS
+ððððð4\ ð6 HEADING-O-INDIC. <-ALL-FMTS
+ððððð5\ OUTPUT FORMAT:DETAIL FROM FILE PERSREPT OF LIBRARY XMPLIB <-ALL-FMTS
+ððððð6\ <-ALL-FMTS
57 +ððððð7 ð6 DETAIL-O-INDIC. <-ALL-FMTS
58 +ððððð8 ð7 INð1 PIC 1 INDIC ð1. <-ALL-FMTS
ðð34ðð
59 ðð35ðð 77 EOF-FLAG PIC X(1)
6ð ðð36ðð VALUE "ð".
61 ðð37ðð 88 NOT-END-OF-FILE VALUE "ð".

Figure 75 (Part 1 of 2). Example of the END-OF-PAGE Condition

Chapter 9. Printer Files 235


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
62 ðð38ðð 88 END-OF-FILE VALUE "1".
63 ðð39ðð 77 MARRIED PIC X(1)
64 ðð4ððð VALUE "M".
ðð41ðð
65 ðð42ðð PROCEDURE DIVISION.
ðð43ðð FIRST-SECT SECTION.
ðð44ðð FIRST-PARA.
66 ðð45ðð OPEN INPUT PERSFILE
ðð46ðð OUTPUT PERSREPT.
67 ðð47ðð PERFORM HEADING-LINE.
68 ðð48ðð PERFORM PROCESS-RECORD UNTIL END-OF-FILE.
69 ðð49ðð CLOSE PERSFILE
ðð5ððð PERSREPT.
7ð ðð51ðð STOP RUN.
ðð52ðð
ðð53ðð PROCESS-RECORD.
71 ðð54ðð READ PERSFILE AT END SET END-OF-FILE TO TRUE.
73 ðð55ðð IF NOT-END-OF-FILE THEN
74 ðð56ðð PERFORM PRINT-RECORD. .5/
ðð57ðð
ðð58ðð PRINT-RECORD.
75 ðð59ðð MOVE CORR PERSREC TO DETAIL-O. .6/
76 ðð6ððð IF MARSTAT IN PERSFILE-REC IS EQUAL MARRIED THEN .7/
77 ðð61ðð MOVE B"1" TO INð1 IN DETAIL-O-INDIC
ðð62ðð ELSE
78 ðð63ðð MOVE B"ð" TO INð1 IN DETAIL-O-INDIC.
79 ðð64ðð WRITE PERSREPT-REC FORMAT IS "DETAIL" .8/
ðð65ðð INDICATORS ARE DETAIL-O-INDIC
8ð ðð66ðð AT EOP PERFORM HEADING-LINE. .9/
ðð67ðð HEADING-LINE.
81 ðð68ðð MOVE HEAD-ORDER TO ORDERTYPE
82 ðð69ðð WRITE PERSREPT-REC FORMAT IS "HEADING".
ðð7ððð
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 75 (Part 2 of 2). Example of the END-OF-PAGE Condition

.1/ The externally described printer file is assigned to device FORMATFILE.


.2/ The Format 2 COPY statement is used to copy the fields for the printer file
into the program.
.3/ Note that, although the fields in format DETAIL will be printed on three sepa-
rate lines, they are defined in one record.
.4/ COPY-DDS is used to copy the indicators used in the printer file into the
program.
.5/ Paragraph PROCESS-RECORD processes PRINT-RECORD for each
employee record.
.6/ All fields in the employee record are moved to the record for format DETAIL.
.7/ If the employee is married, indicator 01 is turned on; if not, the indicator is
turned off, preventing the spouse’s name field in DETAIL from being printed.
.8/ Format DETAIL is printed with indicator 01 passed to control printing.
.9/ If the number of lines per page has been exceeded, END-OF-PAGE occurs.
The format HEADING is printed on a new page.

236 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 2 2 23 2 4 25 2 6 27 28 29 30 3 1 3 2 33 3 4 35 3 6 37 38 39 40 4 1 4 2 43 4 4 45 4 6 47 48 49 50 5 1 5 2 5 3 5 4 55 5 6 57 5 8 5 9 60 6 1 6 2 6 3 6 4 65 6 6 67 6 8 6 9 70 7 1 7 2 7 3 7 4 75 7 6 77 7 8 7 9 80

A* P H Y S I CA L F I LE DD S F OR P E R S ON N E L F I LE IN F OR MA T F I L E E X AMP L E
A
A* R P E R S R EC
A E MP L NO 6S
A N AME 30
A AD D R E S S 1 35
A AD D R E S S 2 20
A B I R T HD A T E 6
A MA R S T A T 1
A S P OU S E N AME 30
A N UMC H I L D 2S
A K E MP L NO
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 76 (Part 1 of 2). DDS Example of the Use of Externally Described Printer Files Assigned to a Device of
FORMATFILE

Chapter 9. Printer Files 237


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A* PR I NT ER F I LE DD S F OR F OR MA T F I L E E X AMP L E
A*
A I ND A R A R E F ( P E R S F I L E )
A R H E AD I NG S K I P B ( 1 ) S P AC E A ( 3 )
A 1 5 ' P E R S ON N E L L I S T I NG '
A U ND E R L I N E
A 3 3 ' - OR D E R E D B Y '
A OR D E R T Y P E 15 46
A 8 0 D A T E E D T CD E ( Y )
A 9 3 T I ME
A 1 1 5 ' P AG E : '
A + 1 P AGN B R E D T CD E ( 3 )
A*
A R DE T A I L S P AC E A ( 3 )
A* L I NE 1
A 1 ' N AME : '
A N AME R 1 1 U ND E R L I N E
A 5 5 ' E MP L O Y E E N UMB E R : '
A E MP L NO R 73
A 8 7 ' DA T E OF B I R T H : '
A B I R T HD A T E R 1 0 3 S P AC E A ( 1 )
A* L I NE 2
A 1 ' AD D R E S S : '
A AD D R E S S 1 R 11
A 5 5 ' MA R I T A L S T A T U S : '
A MA R S T A T R 73
A 01 8 7 ' S P OU S E ' ' S N AME : '
A 01 S P OU S E N AME R 103
A* L I NE 3
A AD D R E S S 2 R 1 1 S P AC E B ( 1 )
A 5 5 ' CH I L D R E N : '
A N UMC H I L D R 7 3 E D T CD E ( 3 )
A
A
A

Figure 76 (Part 2 of 2). DDS Example of the Use of Externally Described Printer Files Assigned to a Device of
FORMATFILE

.1/ INDARA specifies that a separate indicator area is to be used for the file.
.2/ HEADING is the format name that provides headings for each page.
.3/ SKIPB(1) and SPACEA(3) are used to:
1. Skip to line 1 of the next page before format HEADING is printed.
2. Leave 3 blank lines after format HEADING is printed.
.4/ DATE, TIME, and PAGNBR are used to have the current date, time and
page number printed automatically when format HEADING is printed.
.5/ DETAIL is the format name used to print the detail line for each employee in
the personnel file.

238 COBOL/400 User’s Guide


.6/ SPACEA(3) causes three lines to be left blank after each employee detail
line.
.7/ SPACEA(1) causes a blank line to be printed after the field BIRTHDATE is
printed. As a result, subsequent fields in the same format are printed on a
new line.
.8/ 01 means that these fields are printed only if the COBOL program turns indi-
cator 01 on and passes it when format DETAIL is printed.
.9/ EDTCDE(3) is used to remove leading zeros when printing this numeric field.

Chapter 9. Printer Files 239


240 COBOL/400 User’s Guide
Chapter 10. DISK and DATABASE Files
Database files, which are associated with the COBOL devices of DATABASE and
DISK, can be:
Ÿ Externally described files, whose fields are described to OS/400 through DDS
Ÿ Program-described files, whose fields are described in the program that uses
the file.

All database files are created by OS/400 Create File commands. See the
Database Guide for a description of the Create File commands for database files.

DATABASE versus DISK Files


Assigning a file to DISK in COBOL restricts the user to traditional DISK processing.
The use of DATABASE as the device permits the user to make use of the special
COBOL/400 database features such as formats and duplicate record keys.

Processing Methods for DISK and DATABASE Files

COBOL Indexed Files


An indexed file is a file whose access path is built on key values. The user must
create a keyed access path for an indexed file by using DDS.

To write standard ANSI X3.23-1985 COBOL programs that access an indexed file,
you must create the file with certain characteristics. The following table lists these
characteristics and what controls them:

Characteristic Control
The file must be a physical file. The CL command CRTPF
The file cannot have records with duplicate The DDS keyword UNIQUE
key values.
The file cannot be a shared file. The CL command CRTPF
A key must be defined for the file. DDS
Keys must be in ascending sequence. DDS
Keys must be contiguous within the record. DDS
Key fields must be alphanumeric. They DDS
cannot be numeric only.
The value of the key used for sequencing DDS
must include all 8 bits of every byte.
A starting position for retrieving records cannot The CL command OVRDBF
be specified.
Select/omit level keywords cannot be used for DDS
the file.

An indexed file is identified by the ORGANIZATION IS INDEXED clause of the


SELECT statement.

 Copyright IBM Corp. 1994 241


The key fields identify the records in an indexed file. The user specifies the key
field in the RECORD KEY clause of the SELECT statement. The RECORD KEY
data item must be defined within a record description for the indexed file. If there
are multiple record descriptions for the file, only one need contain the RECORD
KEY data name. However, the same positions within the record description that
contain the RECORD KEY data item are accessed in the other record descriptions
as the KEY value for any references to the other record descriptions for that file.

An indexed file can be accessed sequentially, randomly by key, or dynamically.

Valid RECORD KEYS


The DDS for the file specifies the fields to be used as the key field. If the file has
multiple key fields, the key fields must be contiguous in each record unless
RECORD KEY IS EXTERNALLY-DESCRIBED-KEY is specified.

When the DDS specifies only one key field for the file, the RECORD KEY must be
a single field of the same length as the key field defined in the DDS.

If a Format 2 COPY statement is specified for the file, the RECORD KEY clause
must specify one of the following:
Ÿ The name used in the DDS for the key field if the name is not a COBOL
reserved word.
Ÿ The name used in the DDS for the key field with -DDS added to the end if the
name is a COBOL reserved word.
Ÿ The data name defined with the proper length and at the proper location in a
program-described record description for the file.
Ÿ EXTERNALLY-DESCRIBED-KEY. This keyword specifies that the keys defined
in DDS for each record format are to be used for accessing the file. These
keys can be noncontiguous. They can be defined at different positions within
the record format.

When the DDS specifies multiple contiguous key fields, the RECORD KEY data
name must be a single field with its length equal to the sum of the lengths of the
multiple key fields in the DDS. If a Format 2 COPY statement is specified for the
file, there must also be a program-described record description for the file that
defines the RECORD KEY data name with the proper length and at the proper
position in the record.

Contiguous items are consecutive elementary or group items in the Data Division
that are contained in a single data hierarchy.

Referring to a Partial Key


A generic START statement allows the use of a partial key. The KEY IS phrase is
required.

Refer to the “START Statement” in the COBOL/400 Reference for information about
the rules for specifying a search argument that refers to a partial key.

Figure 77 on page 243 shows an example of generic START statements using a


program-described file.

242 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
7 ððð7ðð FILE-CONTROL.
8 ððð8ðð SELECT FILE-1 ASSIGN TO DISK-FILE1
9 ððð9ðð ACCESS IS DYNAMIC RECORD KEY IS FULL-NAME IN FILE-1
1ð ðð1ððð ORGANIZATION IS INDEXED.
11 ðð11ðð DATA DIVISION.
12 ðð12ðð FILE SECTION.
13 ðð13ðð FD FILE-1 LABEL RECORDS ARE STANDARD.
14 ðð14ðð ð1 RECORD-DESCRIPTION.
15 ðð15ðð ð3 FULL-NAME.
16 ðð16ðð ð5 LAST-AND-FIRST-NAMES.
17 ðð17ðð ð7 LAST-NAME PIC X(2ð).
18 ðð18ðð ð7 FIRST-NAME PIC X(2ð).
19 ðð19ðð ð5 MIDDLE-NAME PIC X(2ð).
2ð ðð2ððð ð3 LAST-FIRST-MIDDLE-INITIAL-NAME REDEFINES FULL-NAME
21 ðð21ðð PIC X(41).
22 ðð22ðð ð3 REST-OF-RECORD
ðð23ðð/
23 ðð24ðð PROCEDURE DIVISION.
ðð25ðð START-PROGRAM.
24 ðð26ðð OPEN INPUT FILE-1.
ðð27ðð\
ðð28ðð\ POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF
ðð29ðð\ "SMITH"
25 ðð3ððð MOVE "SMITH" TO LAST-NAME.
26 ðð31ðð START FILE-1 KEY IS EQUAL TO LAST-NAME
27 ðð32ðð INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " LAST-NAME
28 ðð33ðð GO-TO ERROR ROUTINE.
ðð34ðð\
ðð35ðð\
ðð36ðð\
ðð37ðð\
ðð38ðð\ POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF
ðð39ðð\ "SMITH" AND A FIRST NAME OF "ROBERT"
29 ðð4ððð MOVE "SMITH" TO LAST-NAME.
3ð ðð41ðð MOVE "ROBERT" TO FIRST-NAME.
31 ðð42ðð START FILE-1 KEY IS EQUAL TO LAST-AND-FIRST-NAMES
32 ðð43ðð INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR "
ðð44ðð LAST-AND-FIRST-NAMES
33 ðð45ðð GO-TO ERROR ROUTINE.
ðð46ðð\
ðð47ðð\
ðð48ðð\
ðð49ðð\
ðð5ððð\ POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF
ðð51ðð\ "SMITH", AND A FIRST NAME OF "ROBERT", AND A MIDDLE INITIAL OF "M"
34 ðð52ðð MOVE "SMITH" TO LAST-NAME.
35 ðð53ðð MOVE "ROBERT" TO FIRST-NAME.
36 ðð54ðð MOVE "M" TO MIDDLE-NAME.
37 ðð55ðð START FILE-1 KEY IS EQUAL TO LAST-AND-FIRST-MIDDLE-INITIAL-NAME
38 ðð56ðð INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR "
ðð57ðð LAST-FIRST-MIDDLE-INITIAL-NAME
39 ðð58ðð GO-TO ERROR ROUTINE.
ðð59ðð
ðð6ððð
ðð61ðð ERROR-ROUTINE.
4ð ðð62ðð STOP-RUN.

Figure 77. Generic START Statements Using a Program-Described File

Figure 78 and Figure 79 show an example of generic START statements using an


externally described file.

Chapter 10. DISK and DATABASE Files 243


DATA DESCRIPTION SOURCE
SEQNBR \... ... 1 ... ... 2 ... ... 3 ... ... 4 ... ... 5 ... ... 6 ... ... 7 ... ... 8 DATE
1ðð A UNIQUE
2ðð A R RDE TEXT('RECORD DESCRIPTION')
3ðð A FNAME 2ð TEXT('FIRST NAME')
4ðð A MINAME 1 TEXT('MIDDLE INITIAL NAME')
5ðð A MNAME 19 TEXT('REST OF MIDDLE NAME')
6ðð A LNAME 2ð TEXT('LAST NAME')
7ðð A PHONE 1ð ð TEXT('PHONE NUMBER')
8ðð A DATA 4ð TEXT('REST OF DATA')
9ðð A K LNAME
1ððð A K FNAME
11ðð A K MINAME
12ðð A K MNAME

Figure 78. Generic START Statements Using an Externally Described File -- DDS

244 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
7 ððð7ðð FILE-CONTROL.
8 ððð8ðð SELECT FILE-1 ASSIGN TO DATABASE-NAMES
9 ððð9ðð ACCESS IS DYNAMIC RECORD KEY IS EXTERNALLY-DESCRIBED-KEY
1ð ðð1ððð ORGANIZATION IS INDEXED.
11 ðð11ðð DATA DIVISION.
12 ðð12ðð FILE SECTION.
13 ðð13ðð FD FILE-1 LABEL RECORDS ARE STANDARD.
14 ðð14ðð ð1 RECORD-DESCRIPTION
15 ðð15ðð COPY DDS-RDE IN NAMES-PUBS.
17 +ððððð1 RDE
+ððððð2\ FROM FILE NAMES OF LIBRARY XMPLIB RDE
+ððððð3\ RECORD DESCRIPTION RDE
18 +ððððð4 ð5 RDE. RDE
+ððððð5\ RECORD KEY FOR INDEXED FILE, KEY'ððð2 KEY FIELD NAME FNAME . RDE
19 +ððððð6 ð6 FNAME PIC X(2ð). RDE
+ððððð7\ FIRST NAME RDE
+ððððð8\ RECORD KEY FOR INDEXED FILE, KEY'ððð3 KEY FIELD NAME MINAME . RDE
2ð +ððððð9 ð6 MINAME PIC X(1). RDE
+ðððð1ð\ MIDDLE INITIAL NAME RDE
+ðððð11\ RECORD KEY FOR INDEXED FILE, KEY'ððð4 KEY FIELD NAME MNAME . RDE
21 +ðððð12 ð6 MNAME PIC X(19). RDE
+ðððð13\ REST OF MIDDLE NAME RDE
+ðððð14\ RECORD KEY FOR INDEXED FILE, KEY'ððð1 KEY FIELD NAME LNAME . RDE
22 +ðððð15 ð6 LNAME PIC X(2ð). RDE
+ðððð16\ LAST NAME RDE
23 +ðððð17 ð6 PHONE PIC S9(1ð). COMP-3 RDE
+ðððð18\ PHONE NUMBER RDE
24 +ðððð19 ð6 DATA-DDS PIC X(4ð). RDE
+ðððð2ð\ REST OF DATA RDE
25 ðð16ðð 66 MIDDLE-NAME RENAMES MINAME THRU MNAME.
ðð17ðð/
26 ðð18ðð PROCEDURE DIVISION.
ðð19ðð START PROGRAM.
27 ðð2ððð OPEN INPUT FILE-1.
ðð21ðð\
ðð22ðð\ POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME
ðð23ðð\ OF "SMITH"
28 ðð24ðð MOVE "SMITH" TO LNAME.
29 ðð25ðð START FILE-1 KEY IS EQUAL TO LNAME
3ð ðð26ðð INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR " LNAME
31 ðð27ðð GO TO ERROR-ROUTINE.
ðð28ðð\ .
ðð29ðð\ .
ðð3ððð\ .
ðð31ðð\
ðð32ðð\ POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME
ðð33ðð\ OF "SMITH" AND A FIRST NAME OF "ROBERT"
32 ðð34ðð MOVE "SMITH" TO LNAME.
33 ðð35ðð MOVE "ROBERT" TO FNAME.
34 ðð36ðð START FILE-1 KEY IS EQUAL TO LNAME, FNAME
35 ðð37ðð INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR "
ðð38ðð LNAME " " FNAME
36 ðð39ðð GO TO ERROR-ROUTINE.
ðð4ððð\ .
ðð41ðð\ .
ðð42ðð\ .
ðð43ðð\
ðð44ðð\ POSITION THE FILE STARTING WITH RECORDS THAT HAVE A LAST NAME OF
ðð45ðð\ "SMITH", A FIRST NAME OF "ROBERT", AND A MIDDLE INITIAL OF "M"
32 ðð46ðð MOVE "SMITH" TO LNAME.
33 ðð47ðð MOVE "ROBERT" TO FNAME.
33 ðð48ðð MOVE "M" TO MINAME.
34 ðð49ðð START FILE-1 KEY IS EQUAL TO LNAME, FNAME, MINAME
35 ðð5ððð INVALID KEY DISPLAY "NO DATA IN SYSTEM FOR "
ðð51ðð LNAME SPACE FNAME SPACE MINAME
42 ðð52ðð GO TO ERROR-ROUTINE.
ðð53ðð
ðð54ðð
ðð55ðð ERROR-ROUTINE.
ðð56ðð STOP-RUN.

Figure 79. Generic START Statements Using an Externally Described File

Chapter 10. DISK and DATABASE Files 245


Logical File Considerations
When a logical file with multiple record formats, each having associated key fields,
is processed as an indexed file in COBOL, the following restrictions and consider-
ations apply:
Ÿ The FORMAT phrase must be specified on all WRITE statements to the file
unless a Record Format Selector Program exists and has been specified in the
FMTSLR parameter of the Create Logical File (CRTLF) command, the Change
Logical File (CHGLF) command, or the Override Database File (OVRDBF)
command. For information on the use of format selector programs, refer to the
Database Guide.
Ÿ If the access mode is RANDOM or DYNAMIC, and the DUPLICATES phrase is
not specified for the file, the FORMAT phrase must be specified on all DELETE
and REWRITE statements.
Ÿ When the FORMAT phrase is not specified, only the portion of the RECORD
KEY data item that is common to all record formats for the file is used by the
system as the key for the I/O statement. When the FORMAT phrase is speci-
fied, only the portion of the RECORD KEY data item that is defined for the
specified record format is used by the system as the key. See the Database
Guide for more information on logical file processing.
Ÿ When *NONE is specified as the first key field for any format in a file, records
can only be accessed sequentially. When a file is read randomly:
– If a format name is specified, the first record with the specified format is
returned.
– If a format name is not specified, the first record in the file is returned.
In both cases, the value of the RECORD KEY data item is ignored.
Ÿ For a program-defined key field:
– Key fields within each record format must be contiguous.
– The first key field for each record format must begin at the same relative
position within each record.
– The length of the RECORD KEY data item must be equal to the length of
the longest key for any format in the file.
Ÿ For an EXTERNALLY-DESCRIBED-KEY:
– Key fields within each record format can be noncontiguous.
– The key fields can begin at different positions in each record format.

Figure 80 on page 247 and Figure 81 on page 248 show examples of how to use
DDS to describe the access path for indexed files.

246 COBOL/400 User’s Guide


AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*
Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)


Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons

Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A R F OR MA T A P F I L E ( OR D D T L P )
A T E X T ( ' ACC E S S P A T H F OR I ND E X E D F I LE ' )
A F L DA 14
A OR D E R N 5S 0
A F L DB 101
A K OR D E R N
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 80. Using Data Description Specifications to Define the Access Path for an Indexed File

Data description specifications must be used to create the access path for a
program-described indexed file.

In the DDS for the record format FORMATA for the logical file ORDDTLL, the field
ORDERN, which is five digits long, is defined as the key field. The definition of
ORDERN as the key field establishes the keyed access for this file. Two other
fields, FLDA and FLDB, describe the remaining positions in this record as character
fields.

The program-described input field ORDDTLL is described in the FILE-CONTROL


section in the SELECT clause as an indexed file.

Chapter 10. DISK and DATABASE Files 247


The COBOL descriptions of each field in the FD entry must agree with the corre-
sponding description in the DDS file. The RECORD KEY data item must be
defined as a five-digit numeric integer beginning in position 15 of the record.

AS/400 DATA DESCRIPTION SPECIFICATIONS GX2 1-98 91-0 UM/05 0*


Pr i nt ed i n U. S . A.
I n t er n at i on al B u s i n e s s Mac h i n es * Number of s heet s per pad may var y s l i ghtl y.

Fi l e Keying Graphic Description Page of


I ns tructi on
Programmer Date Key

Type of Name of S pec /(b/R/H/J/K/S /O)

Conditioning

Location

U s ag e (/b / O/ I / B/ H/ M/ N/ P )
And/Or/Comment (A/O/*)

Data Type/Keyboard Shift


Condition Name

Name Length Functi ons


Reference (R)
Sequence
Number
Form Type

Pos i t i ons
Indi cator

Reserved
Indi cator

Indi cator

Decimal
Not (N)

Not (N)
Not (N)

Li ne Pos

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 2 1 22 2 3 2 4 25 2 6 27 2 8 29 30 3 1 32 3 3 3 4 35 3 6 37 3 8 39 40 4 1 42 4 3 4 4 45 4 6 47 4 8 49 5 0 5 1 52 5 3 5 4 5 5 5 6 57 5 8 59 6 0 6 1 62 6 3 6 4 6 5 6 6 67 6 8 69 7 0 7 1 72 7 3 7 4 7 5 7 6 77 7 8 79 8 0

A R F OR MA T P F I L E ( OR D D T L P )
A T E X T ( ' ACC E S S P A T H F OR I ND E X E D F I LE ' )
A F L DA 14
A OR D E R N 5S 0
A I T EM 5
A F L DB 96
A K OR D E R N
A K I T EM
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A
A

Figure 81. Data Description Specifications for Defining the Access Path (a Composite Key) of an Indexed File

In this example, the data description specifications define two key fields for the
record format FORMAT in the logical file ORDDTLL. For the two fields to be used
as a composite key for a program-described indexed file, the key fields must be
contiguous in the record.

The COBOL description of each field must agree with the corresponding description
in the DDS file. A 10-character item beginning in position 15 of the record must be
defined in the RECORD KEY clause of the file-control entry. The COBOL

248 COBOL/400 User’s Guide


descriptions of the DDS fields ORDERN and ITEM would be subordinate to the
10-character item defined in the RECORD KEY clause.

COBOL Relative Files


A COBOL relative file is a file to be processed by a relative record number. To
process a file by relative record number, you must specify ORGANIZATION IS
RELATIVE in the SELECT statement for the file. A relative file can be accessed
sequentially, randomly by record number, or dynamically.

To write standard ANSI X3.23-1985 COBOL programs that access a relative file,
you must create the file with certain characteristics. The following table lists these
characteristics and what controls them.

Characteristic Control
The file must be a physical file. The CL command CRTPF
The file cannot be a shared file. The CL command CRTPF
No key can be specified for the file. DDS
A starting position for retrieving records cannot The CL command OVRDBF
be specified.
Select/omit level keywords cannot be used for DDS
the file.
Records in the file cannot be reused. The CL command CRTPF

For a COBOL file with an organization of RELATIVE, the Reorganize Physical File
Member (RGZPFM) CL command can:
Ÿ Remove all deleted records from the file. Because COBOL initializes all rela-
tive file records to deleted records, any record that has not been explicitly
written will be removed from the file. The relative record numbers of all records
after the first deleted record in the file will change.
Ÿ Change the relative record numbers if the file has a key and the arrival
sequence is changed to match a key sequence (with the KEYFILE parameter).

In addition, a Change Physical File (CHGPF) CL command bearing the REUSEDLT


option can change the order of retrieved or written records when the file is operated
on sequentially, because it allows the reuse of deleted records.

COBOL Sequential Files


A COBOL sequential file is a file in which records are processed in the order in
which they were placed in the file, that is, in arrival sequence. For example, the
tenth record placed in the file occupies the tenth record position and is the tenth
record to be processed. To process a file as a sequential file, you must specify
ORGANIZATION IS SEQUENTIAL in the SELECT clause, or omit the ORGANIZA-
TION clause. A sequential file can only be accessed sequentially.

To write standard ANSI X3.23-1985 COBOL programs that access a sequential file,
you must create the file with certain characteristics. The following table lists these
characteristics and what controls them.

Chapter 10. DISK and DATABASE Files 249


Characteristic Control
The file must be a physical file. The CL command CRTPF
The file cannot be a shared file. The CL command CRTPF
No key can be specified for the file. DDS
The file must have a file type of DATA. The CL command CRTPF
Field editing cannot be used. DDS
Line and position information cannot be speci- DDS
fied.
Spacing and skipping keywords cannot be DDS
specified.
Indicators cannot be used. DDS
System-supplied functions such as date, time, DDS
and page number cannot be used.
Select/omit level keywords cannot be used for DDS
the file.
Records in the file cannot be reused. The CL command CRTPF

To preserve the sequence of records in a file that you open in I/O (update) mode,
do not change the file so that you can reuse the records in it. That is, do not use a
Change Physical File (CHGPF) CL command bearing the REUSEDLT option.

Note: The COBOL/400 compiler does not check that the device associated with
the external file is of the type specified in the device portion of assignment-
name. The device specified in the assignment-name must match the actual
device to which the file is assigned. See the “ASSIGN Clause” section of
the COBOL/400 Reference for more information.

COBOL File Organization and AS/400 File Access Path Considerations


A file with a keyed sequence access path can be processed in COBOL as a file
with INDEXED, RELATIVE, or SEQUENTIAL organization.

For a keyed sequence file to be processed as a relative file in COBOL, it must be a


physical file, or a logical file whose members are based on one physical file
member. For a keyed sequence file to be processed as a sequential file in
COBOL, it must be a physical file, or a logical file that is based on one physical file
member and that does not contain select/omit logic.

A file with an arrival sequence access path can be processed in COBOL as a file
with RELATIVE or SEQUENTIAL organization. The file must be a physical file or a
logical file where each member of the logical file is based on only one physical file
member.

When sequential access is specified for a logical file, records in the file are
accessed through the access path created with create file options.

250 COBOL/400 User’s Guide


File Processing Methods
Figure 82 on page 252 shows the valid processing methods and expected opera-
tion for combinations of organization, access mode, open state, I/O verb, and I/O
verb modifiers.

All physical database files that are opened for OUTPUT are cleared. Database
files with RELATIVE organization, and with dynamic or random access mode, are
also initialized with deleted records.

New relative files opened for OUTPUT in sequential access mode are treated differ-
ently. Table 4 summarizes conditions affecting them.

Table 4. Initialization of Relative Output Files


File Access and Conditions at Conditions at
CL Specifications Opening Time Closing Time File Boundary
Sequential Records not All increments
*INZDLT written are
initialized
Sequential CLOSE succeeds Up to boundary of
*INZDLT File status is 0Q records written
*NOMAX size
Sequential Up to boundary of
*NOINZDLT records written
Random or Records are All increments
dynamic initialized
File is open
Random or OPEN fails File is empty
dynamic File status is 9Q
*NOMAX size

To extend a file boundary beyond the current number of records, but remaining
within the file size, use the INZPFM command to add deleted records before proc-
essing the file. You need to do this if you receive a file status of 0Q, and you still
want to add more records to the file.

Any attempt to extend a relative file beyond its current size results in a boundary
violation.

To recover from a file status of 9Q, use the CHGPF command as described in the
associated run-time message text.

Lengthy delays are normal when there remains an extremely large number of
records (over 1 000 000) to be initialized to deleted records when the CLOSE state-
ment runs.

When the first OPEN statement for the file is not OPEN OUTPUT, relative files
should be cleared and initialized with deleted records before they are used. See
the discussion of the CLRPFM and INZPFM commands in the CL Reference for
more information.

Chapter 10. DISK and DATABASE Files 251


The RECORDS parameter of the INZPFM command must specify *DLT. Overrides
are applied when the clear and initialize operations are processed by COBOL, but
not when they are processed with CL commands.

Lengthy delays in OPEN OUTPUT processing are normal for extremely large rela-
tive files (over 1 000 000 records) that you access in dynamic or random mode.
┌─────┬─────┬──────┬────────┬──────┬───────┬───────┬─────────┬────────┬───────┬────────┬────────┐
│ │ │ │ │ │ │ │ │ │ │ │ SELECT │
│ │ │ │ │ │ │ │ │ │ │ │ CLAUSE │
│ ORG │ ACC │ DEV │ OPEN │ READ │ WRITE │ START │ REWRITE │ DELETE │ CLOSE │ FORMAT │ KEY IS │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ S │ S │ ANY │ INPUT │ X │ │ │ │ │ X │ │ │
│ S │ S │ ANY │ OUTPUT │ │ X(F1) │ │ │ │ X │ A1 │ │
│ S │ S │ ANY │ I-O │ X │ │ │ X │ │ X │ │ │
│ S │ S │ ANY │ EXTEND │ │ X │ │ │ │ X │ │ │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ I │ S │ D/DB │ INPUT │ X │ │ X │ │ │ X │ B1 │ C1 │
│ I │ S │ D/DB │ OUTPUT │ │ X(F1) │ │ │ │ X │ B1 │ C1 │
│ I │ S │ D/DB │ I-O │ X │ │ X │ X │ X │ X │ B1 │ C1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ I │ R │ D/DB │ INPUT │ X │ │ │ │ │ X │ B1 │ D1 │
│ I │ R │ D/DB │ OUTPUT │ │ X(F1) │ │ │ │ X │ B1 │ D1 │
│ I │ R │ D/DB │ I-O │ X │ X │ │ X │ X │ X │ B1 │ D1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ I │ D │ D/DB │ INPUT │ X │ │ X │ │ │ X │ B1 │ D1 │
│ I │ D │ D/DB │ OUTPUT │ │ X(F1) │ │ │ │ X │ B1 │ D1 │
│ I │ D │ D/DB │ I-O │ X │ X │ X │ X │ X │ X │ B1 │ D1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ R │ S │ D/DB │ INPUT │ X │ │ X │ │ │ X │ │ C1 │
│ R │ S │ D/DB │ OUTPUT │ │ X(G1) │ │ │ │ X │ │ C1 │
│ R │ S │ D/DB │ I-O │ X │ │ X │ X │ X │ X │ │ C1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ R │ R │ D/DB │ INPUT │ X │ │ │ │ │ X │ │ E1 │
│ R │ R │ D/DB │ OUTPUT │ │ X(G1) │ │ │ │ X │ │ E1 │
│ R │ R │ D/DB │ I-O │ X │ X │ │ X │ X │ X │ │ E1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ R │ D │ D/DB │ INPUT │ X │ │ X │ │ │ X │ │ E1 │
│ R │ D │ D/DB │ OUTPUT │ │ X(G1) │ │ │ │ X │ │ E1 │
│ R │ D │ D/DB │ I-O │ X │ X │ X │ X │ X │ X │ │ E1 │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ T │ S │ W │ I-O │ X │ X │ │ │ │ X │ H1 │ │
├─────┼─────┼──────┼────────┼──────┼───────┼───────┼─────────┼────────┼───────┼────────┼────────┤
│ T │ D │ W │ I-O │ X(K1)│ X(K1) │ │ X │ │ X │ I1 │ J1 │
├─────┴─────┴──────┴────────┼──────┴───────┴───────┴─────────┼────────┴───────┴────────┴────────┤
│ORG: │ ACC: │ DEV: │
│ │ │ │
│ S = Sequential │ S = Sequential │ ANY = Any Device │
│ R = Relative │ R = Random │ D = DISK │
│ I = Indexed │ D = Dynamic │ DB = DATABASE │
│ T = TRANSACTION │ │ W = WORKSTATION │
└───────────────────────────┴────────────────────────────────┴──────────────────────────────────┘

Figure 82. Processing Methods Summary Chart

The following paragraphs explain the keys used in Figure 82.


X The combination is allowed.
A1 The FORMAT phrase is required for FORMATFILE files with multiple formats,
and is not allowed for all other device files.
B1 The FORMAT phrase is optional for DATABASE files, and not allowed for
DISK files. If the FORMAT phrase is not specified, the default format name of
the file is used. The default format name of the file is the first format name
defined in the file.
The special register, DB-FORMAT-NAME, can be used to retrieve the format
name used on the last successful I/O operation.
C1 The SELECT clause KEY phrase is ignored except for the START statement.
If the KEY phrase is not specified on the START statement, the RECORD
KEY phrase or the RELATIVE KEY phrase in the SELECT clause is used and
KEY = is assumed.

252 COBOL/400 User’s Guide


D1 The SELECT clause KEY phrase is used except for the START statement. If
the KEY phrase is not specified on the START statement, the RECORD KEY
phrase in the SELECT clause is used and KEY = is assumed.
NEXT, PRIOR, FIRST, or LAST can be specified only for the READ statement
for DATABASE files with DYNAMIC access. If NEXT, PRIOR, FIRST, or
LAST is specified, the SELECT clause KEY phrase is ignored.
E1 The SELECT clause RELATIVE KEY phrase is used.
The NEXT phrase can be specified only for the READ statement for a file with
DYNAMIC access mode. If NEXT is specified, the SELECT clause KEY
phrase is ignored.
The RELATIVE KEY data item is updated with the relative record number for
files with sequential access on READ operations.
F1 A physical file opened for output is cleared.
G1 A physical file opened for output is cleared and initialized to deleted records.
There are some exceptions depending on the file size and the options speci-
fied. For more information, refer to Table 4 on page 251.
H1 The FORMAT phrase is required for the WRITE statement.
I1 The FORMAT phrase is required to distinguish between the subfile records
and the subfile control record. The WRITE FORMAT IS control-record-format-
name displays the subfile, but a READ FORMAT IS control-record-format-
name is required to allow data to be entered and to cause the operator input
for the subfile records on the display to be placed in the subfile.
J1 The SELECT clause RELATIVE KEY phrase is used for READ, WRITE, and
REWRITE statements that use the SUBFILE phrase, except that the READ
SUBFILE NEXT MODIFIED uses the current system relative record number
rather than the RELATIVE KEY data item. The RELATIVE KEY data item is
updated with the relative record number for subfile records for READ state-
ments with the NEXT MODIFIED clause.
K1 The SUBFILE phrase is required when an I/O operation deals with a particular
record rather than an entire file.

Descending File Considerations


Files created with a descending keyed sequence (in DDS) cause the READ state-
ment NEXT, PRIOR, FIRST, and LAST phrases to work in a fashion exactly oppo-
site that of a file with an ascending key sequence. In descending key sequence,
the data is arranged in order from the highest value of the key field to the lowest
value of the key field.

For example, READ FIRST retrieves the record with the highest key value, and
READ LAST retrieves the record with the lowest key value. Files with a
descending key sequence also cause the START qualifiers to work in the opposite
manner. For example, START GREATER THAN positions the current record
pointer to a record with a key less than the current key.

Chapter 10. DISK and DATABASE Files 253


254 COBOL/400 User’s Guide
Chapter 11. COBOL/400 Programming Considerations
This chapter describes:
Ÿ Issuing a CL command from a COBOL program
Ÿ The CORRESPONDING phrase
Ÿ The LIKE clause
Ÿ Reference modification
Ÿ De-editing
Ÿ Performance considerations.
General-Use Programming Interface

Issuing a CL Command from a COBOL Program


You can issue a CL command from a COBOL program through a CALL to QCMDEXC.

In the following example program, the CALL to QCMDEXC (at sequence number
001600) results in the processing of the Add Library List Entry (ADDLIBLE) CL
command (at sequence number 001100). The successful completion of the CL
command results in the addition of the library, COBOLTEST, to the library list.

-A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..
ððð1ðð IDENTIFICATION DIVISION.
ððð2ðð PROGRAM-ID. CMDXMPLE.
ððð3ðð ENVIRONMENT DIVISION.
ððð4ðð CONFIGURATION SECTION.
ððð5ðð SOURCE-COMPUTER. IBM-AS4ðð.
ððð6ðð OBJECT-COMPUTER. IBM-AS4ðð.
ððð7ðð DATA DIVISION.
ððð8ðð WORKING-STORAGE SECTION.
ððð9ðð ð1 PROGRAM-VARIABLES.
ðð1ððð ð5 CL-CMD PIC X(33)
ðð11ðð VALUE "ADDLIBLE COBOLTEST".
ðð12ðð ð5 PACK-VAL PIC 9(1ð)V9(5) COMP-3
ðð13ðð VALUE 18.
ðð14ðð PROCEDURE DIVISION.
ðð15ðð MAINLINE.
ðð16ðð CALL "QCMDEXC" USING CL-CMD PACK-VAL.
ðð17ðð STOP RUN.

Note: Do not use the Reclaim Resource (RCLRSC) Command in this situation. It
cancels all programs higher in the program stack so that the STOP RUN
statement in the program will cause a run-time exception.

For more information about QCMDEXC, see the CL Programmer’s Guide.

End of General-Use Programming Interface

 Copyright IBM Corp. 1994 255


Using the CORRESPONDING Phrase
In the following example program, the ADD CORRESPONDING statement at
sequence number 000270 adds GROUP1 ITEM1 to GROUP2 ITEM1, and adds
GROUP1 ITEM2 to GROUP2 ITEM2. The MOVE CORRESPONDING statement at
sequence number 000290 moves GROUP1 ITEM1, ITEM2, ITEM3, and ITEM4 to
GROUP2 ITEM1, ITEM2, ITEM3, and ITEM4.

The MOVE CORRESPONDING statement at sequence number 000300 is not proc-


essed because there are no corresponding items to move, and an error message is
generated.

Figure 83 on page 257 was produced with the PRTCORR option in effect.

256 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source XMPLIB/CORR
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. CORRPHRASE.
3 ðððð3ð AUTHOR. PROGRAMMER NAME.
4 ðððð4ð INSTALLATION. TORONTO COBOL DEVELOPMENT CENTRE.
5 ðððð5ð DATE-WRITTEN. ð5/24/91.
6 ðððð6ð DATE-COMPILED. ð5/24/94 11:ð9:11 .
7 ðððð7ð ENVIRONMENT DIVISION.
8 ðððð8ð CONFIGURATION SECTION.
9 ðððð9ð SOURCE-COMPUTER. IBM-AS4ðð.
1ð ððð1ðð OBJECT-COMPUTER. IBM-AS4ðð.
11 ððð11ð DATA DIVISION.
12 ððð12ð WORKING-STORAGE SECTION.
13 ððð13ð ð1 GROUP1.
14 ððð14ð ð5 ITEM1 PIC 99 VALUE 1.
15 ððð15ð ð5 ITEM2 PIC 99 VALUE 2.
16 ððð16ð ð5 ITEM3 PIC X(1ð) VALUE "GREEN".
17 ððð17ð ð5 ITEM4 PIC X(1ð) VALUE "BLUE".
18 ððð18ð ð1 GROUP2.
19 ððð19ð ð5 ITEM1 PIC 99 VALUE 8.
2ð ððð2ðð ð5 ITEM2 PIC 99 VALUE 9.
21 ððð21ð ð5 ITEM3 PIC XXBX(8) VALUE SPACES.
22 ððð22ð ð5 ITEM4 PIC X(1ð) VALUE SPACES.
23 ððð23ð ð1 GROUP3.
24 ððð24ð ð5 SPECIAL PIC XX.
25 ððð25ð PROCEDURE DIVISION.
ððð26ð MAINLINE.
26 ððð27ð ADD CORRESPONDING GROUP1 TO GROUP2.
\ \\ CORRESPONDING items for statement 26:
\ \\ ITEM1
\ \\ ITEM2
\ \\ End of CORRESPONDING items for statement 26
27 ððð28ð SUBTRACT CORRESPONDING GROUP1 FROM GROUP2.
\ \\ CORRESPONDING items for statement 27:
\ \\ ITEM1
\ \\ ITEM2
\ \\ End of CORRESPONDING items for statement 27
28 ððð29ð MOVE CORRESPONDING GROUP1 TO GROUP2.
\ \\ CORRESPONDING items for statement 28:
\ \\ ITEM1
\ \\ ITEM2
\ \\ ITEM3
\ \\ ITEM4
\ \\ End of CORRESPONDING items for statement 28
29 ððð3ðð MOVE CORRESPONDING GROUP3 TO GROUP2.
\ \\ CORRESPONDING items for statement 29:
\ \\ No CORRESPONDING items found
\ \\ End of CORRESPONDING items for statement 29
3ð ððð31ð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages XMPLIB/CORR
STMT
\ 29 MSGID: LBLð336 SEVERITY: 1ð SEQNBR: ððð3ðð
Message . . . . : No CORRESPONDING items found. Statement
ignored.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 ð 1 ð ð ð
Source records read . . . . . . . . : 31
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : 1ð
LBLð9ð1 ðð Program CORR created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 83. Example of the CORRESPONDING Phrase

Chapter 11. COBOL/400 Programming Considerations 257


IBM Extension

LIKE Clause
The LIKE clause allows you to define the PICTURE, USAGE, SIGN, and BLANK
WHEN ZERO characteristics of a data name by copying them from a previously
defined data name. LIKE can only refer to a data name or index name, and such
names must be uniquely qualified if they have been previously defined. It also
allows you to change the length of the data name you define.

This clause is particularly helpful because you can use it to define identifiers in the
Working-Storage Section of your program that have the same attributes as vari-
ables that you define using the COPY statement.

To create data name DEPTH with the same attributes as data name HEIGHT, write:
DEPTH LIKE HEIGHT

To create data name PROVINCE with the same attributes as data name STATE, except
1 byte longer, write:
PROVINCE LIKE STATE (+1)

This example shows how you can create data item WS-KEY3 with the same attri-
butes as data item KEY3 in the Working-Storage Section:

5763CB1 V3RðM5 AS/4ðð COBOL Source


STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S

ðð14ðð FILE SECTION.


ðð15ðð FD FILE1.
ðð16ðð ð1 FILE1-REC.
ðð17ðð COPY DDS-ALL-FORMATS OF COPYDDS2.
+ððððð1 ð5 COPYDDS2-RECORD PIC X(2ð).
+ððððð2\ I-O FORMAT: RECORD1 FROM FILE COPYDDS2 OF LIBRARY COPYLIB
+ððððð3\
+ððððð4\THE KEY DEFINITIONS FOR RECORD FORMAT RECORD1
+ððððð5\ NUMBER NAME RETRIEVAL TYPE
+ððððð6\ ððð1 KEY1-DDS ASCENDING
+ððððð7\ KEYNAME ORIGINATES FROM PHYSICAL FILE
+ððððð8 ð5 RECORD1 REDEFINES COPYDDS2-RECORD.
+ððððð9 ð6 KEY3 PIC X(8).
+ðððð1ð ð6 FILLER REDEFINES KEY3.
+ðððð11 ð7 KEY1-DDS PIC X(4).
+ðððð12 ð7 FILLER PIC X(4).
+ðððð13 ð6 DATA1 PIC X(12).
ðð18ðð WORKING-STORAGE SECTION.
ðð19ðð ð1 WS-KEY3 LIKE KEY3.
\ PICTURE IS X(8)

Figure 84. COPY DDS with the LIKE Clause

The LIKE clause cannot be used in conjunction with the REDEFINES, SIGN,
USAGE, or PICTURE clauses. If you use any of these clauses with the LIKE
clause, a duplication error occurs. Similarly, BLANK WHEN ZERO can only be
specified in conjunction with the LIKE clause if the BLANK WHEN ZERO attribute
has not been inherited by the LIKE clause.

258 COBOL/400 User’s Guide


A valid LIKE clause has the format of one of the following:
data-name-1 LIKE-clause xxxxx.
data-name-1 xxxxx LIKE-clause.
data-name-1 xxxxx LIKE-clause xxxxx.
The xxxxx is one or a combination of the following clauses: JUSTIFIED,
SYNCHRONIZED, BLANK WHEN ZERO, VALUE, OCCURS.

The following show what the LIKE clause can do:


ð1 INCOME.
ð5 ANNUAL-WAGES PIC 9(6)V9(2) COMP-3.
ð1 YTD-WAGES LIKE ANNUAL-WAGES.
\ PICTURE IS 9(6)V9(2)
\ USAGE IS PACKED-DECIMAL

ð1 RATES.
ð5 MONTHLY-RATE PIC 9(3).
66 GROSS-RATE RENAMES MONTHLY-RATE.
ð1 NET-RATE LIKE GROSS-RATE.
\ PICTURE IS 9(3)

ð1 FAMILY-NAME PIC X(2ð) VALUE "JONES".


ð1 GIVEN-NAME LIKE FAMILY-NAME.
\ PICTURE IS X(2ð)

ð1 EMPLOYEE-NUMBER PIC X(6).


ð1 DEPARTMENT-MEMBERS.
ð5 DEPT-EMPLOYEE-NUMBER LIKE EMPLOYEE-NUMBER
OCCURS 1ð TIMES.
\ PICTURE IS X(6)
Note: DEPARTMENT-MEMBERS in the above example is 60 bytes long.

ð5 TENANT-NAME PIC X(2ð) OCCURS 1ð TIMES.


ð1 RENEWAL-RECORD.
ð5 RENEWAL-MONTH PIC X(3).
ð5 RENEWAL-NAME LIKE TENANT-NAME.
\ PICTURE IS X(2ð)
Note: RENEWAL-RECORD in the above example is only 23 bytes long.

Chapter 11. COBOL/400 Programming Considerations 259


The PICTURE portion of the generated comment is shown in a concise format.
Note: A numeric field with the BLANK WHEN ZERO attribute is considered to be
a numeric edited field.
ð1 ORDER-DETAILS.
ð5 ORDER-TYPE PIC XX.
ð5 ORDER-CODE LIKE ORDER-TYPE.
\ PICTURE IS X(2)

ð1 FASTENINGS.
ð5 NAILS PIC 9V99 BLANK WHEN ZERO.
ð5 RIVETS LIKE NAILS.
\ PICTURE IS 9V9(2)
\ BLANK WHEN ZERO

ð1 MORTGAGE-PAYMENT.
ð5 MORTGAGE-TOTAL PIC S999V99 SIGN IS LEADING SEPARATE.
ð5 MORTGAGE-INTEREST LIKE MORTGAGE-TOTAL.
\ PICTURE IS S9(3)V9(2)
\ SIGN IS LEADING SEPARATE

ð1 PROFIT.
ð5 GROSS-PROFIT PIC 999(3)PP(5).
ð5 NET-PROFIT LIKE GROSS-PROFIT.
\ PICTURE IS 9(5)P(6)

You can use an integer to increase or decrease the length of the field. The fol-
lowing example shows how to increase the field length of WEEKLY-AMOUNT:

ð1 WEEKLY-AMOUNT PIC 9(3).


ð1 ANNUAL-AMOUNT LIKE WEEKLY-AMOUNT (+3).
\ PICTURE IS 9(6)

You should also be aware of the following:


Ÿ Any field that has attributes of BLANK WHEN ZERO is considered to be an
edited field
Ÿ If an integer of zero is specified, an informational message is generated.

Only the integer portion of the field length can be increased or decreased. You
cannot change the number of decimal places in a data item.

The default attributes, SIGN IS TRAILING and USAGE IS DISPLAY, are never
printed as comments following a LIKE operation.

When you use the LIKE clause, the normal data name qualification rules apply to
the parent data name; however, the referenced data name must be uniquely quali-
fied if it has previously been defined more than once. For example:

260 COBOL/400 User’s Guide


ð1 COMBINATIONS.
ð5 PHENOTYPE PIC XX.
ð5 GENOTYPE LIKE PHENOTYPE.
\ PICTURE IS X(2)
ð1 PHENOTYPE-TRAITS.
ð5 PHENOTYPE PIC X(3ð).
ð5 PHENO-GROUP LIKE PHENOTYPE OF COMBINATIONS.
\ PICTURE IS X(2)
If you do not uniquely qualify the parent data name, the compiler assigns it a
picture clause of X(2), and you receive an error message.

The use of the LIKE clause can sometimes result in group items that are not valid.
For example, if you define a COMP-4 group item and then use the LIKE clause to
define a COMP-3 item that is subordinate to it, an error will result.

The following example is valid:


77 SWITCHES-IN-STOCK PIC S99.
ð1 PARTS-ON-ORDER SIGN IS LEADING SEPARATE.
ð5 SWITCHES-ON-ORDER LIKE SWITCHES-IN-STOCK.
\ PICTURE IS S9(2)
Note: SWITCHES-ON-ORDER has the same SIGN attribute (SIGN IS TRAILING)
as SWITCHES-IN-STOCK.

In the case of B LIKE A where A is a group item, B cannot be subordinate to A. In


all other cases, B will be defined as an alphanumeric item with a length in bytes
equal to the length of group A.
ð1 GARAGE-1.
ð5 STD-PARKING-1 PIC 9(3).
ð1 GARAGE-2.
ð5 STD-PARKING-2 PIC 9(3) COMP-3.
77 VACANCIES-1 LIKE GARAGE-1.
\ PICTURE IS X(3)
77 VACANCIES-2 LIKE GARAGE-2.
\ PICTURE IS X(2)

STD-PARKING-1 is a zoned numeric field, so VACANCIES-1 requires 3 bytes of


storage. STD-PARKING-2 is a packed numeric field, so VACANCIES-2 requires
only 2 bytes of storage.

You can use the LIKE clause with the USAGE IS POINTER clause:
ð1 CUSTOMER-RECORD.
ð5 CUST-NAME PIC X(16).
ð5 CUST-ADDR-POINTER POINTER.
ð5 CUST-STATS-POINTER LIKE CUST-ADDR-POINTER.
\ USAGE IS POINTER
ð5 CUST-NUMBER PIC S9(8).
Note: You cannot use the LIKE clause to change the length of a pointer.

For additional information about the LIKE clause, see the COBOL/400 Reference.

End of IBM Extension

Chapter 11. COBOL/400 Programming Considerations 261


Reference Modification
Reference modification allows you to reference substrings of a data item. You
simply specify the position within the data item at which you want the substring to
start, and the length of the substring. The length is optional: if you omit it, it auto-
matically extends to the end of the data item.

You can write both the starting position and the length value as integer literals, data
items, or arithmetic expressions.

The starting position must be at least 1, and cannot be greater than the length of
the referenced data item. The length must be at least 1.

The result of adding the starting position to the length specification, then subtracting
1, must fall between 1 and the total length of the referenced data item, inclusive.
When the length value is greater than the total length of the data item, an error
results.

For additional information on reference modification, see the COBOL/400


Reference.

The *RANGE generation option produces code to detect out-of-range reference


modification conditions, and to flag violations with a run-time message.

Suppose you want to retrieve the current time from the system, and display its
value in an expanded format. You can retrieve it with the ACCEPT statement,
which returns the hours, minutes, seconds, and hundredths of seconds in the
format:
HHMMSSss
However, you may want to view the current time in the format:
HH:MM:SS

Without reference modification, you must define the following data items:
ð1 TIME-GROUP.
ð5 INTERESTING-FIELDS.
1ð HOURS PIC XX.
1ð MINUTES PIC XX.
1ð SECONDS PIC XX.
ð5 UNINTERESTING-FIELDS.
1ð HUNDREDTHS-OF-SECONDS PIC XX.
ð1 EXPANDED-TIME-GROUP.
ð5 INTERESTING-FIELDS.
1ð HOURS PIC XX.
1ð FILLER PIC X VALUE ":".
1ð MINUTES PIC XX.
1ð FILLER PIC X VALUE ":".
1ð SECONDS PIC XX.
The following code would retrieve the time value, convert it to its expanded format,
and display the new value:

262 COBOL/400 User’s Guide


ACCEPT TIME-GROUP FROM TIME
MOVE CORRESPONDING
INTERESTING-FIELDS OF TIME-GROUP TO
INTERESTING-FIELDS OF EXPANDED-TIME-GROUP
DISPLAY "CURRENT TIME IS: " EXPANDED-TIME-GROUP

With reference modification, you do not need to provide names for the subfields
that describe the time elements. The only data definition you must have is:
ð1 REFMOD-TIME-ITEM PIC X(8).

The code to retrieve and expand the time value appears as follows:
ACCEPT REFMOD-TIME-ITEM FROM TIME
DISPLAY "CURRENT TIME IS: "
REFMOD-TIME-ITEM (1:2)
":"
REFMOD-TIME-ITEM (3:2)
":"
REFMOD-TIME-ITEM (5:2)

The following example shows a reference beginning at character position 1, for a


length of 2, thus retrieving the portion of the time value that corresponds to the
number of hours:
REFMOD-TIME-ITEM (1:2)

The following example shows a reference beginning at character position 3, for a


length of 2, thus retrieving the portion of the time value that corresponds to the
number of minutes:
REFMOD-TIME-ITEM (3:2)

The following example shows a reference beginning at character position 5, for a


length of 2, thus retrieving the portion of the time value that corresponds to the
number of seconds:
REFMOD-TIME-ITEM (5:2)

Reference Modification with Variable-length Tables


Suppose you are using variable-length tables to contain names:
ð1 NAME-GROUP.
ð5 NAME-LENGTH PIC 99.
ð5 NAME-PORTION.
1ð FILLER PIC X
OCCURS 1 TO 17 TIMES
DEPENDING ON NAME-LENGTH.
ð1 NEW-NAME-GROUP.
ð5 NEW-NAME-LENGTH PIC 99.
ð5 NEW-NAME-PORTION.
1ð FILLER PIC X
OCCURS 1 TO 17 TIMES
DEPENDING ON NEW-NAME-LENGTH.

The OCCURS DEPENDING ON object of the NAME-PORTION table is set to 8 so


that only the first eight occurrences of the table are referenced, even though the
entire 17 bytes of NAME-PORTION are filled in.

Chapter 11. COBOL/400 Programming Considerations 263


┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
│ð│8│W│I│L│L│I│A│M│S│ │T│H│O│M│A│S│ │J│
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

Suppose you want to change the value in the item NAME-PORTION without
changing the portion of the item that is defined beyond the currently defined length.
You might try coding:
MOVE NEW-NAME-GROUP TO NAME-GROUP
in which the contents of NEW-NAME-GROUP are:
┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
│ð│5│S│M│I│T│H│ │ │ │ │ │M│I│C│H│A│E│L│
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

According to the rules for the MOVE statement, the entire contents of the receiving
field NAME-GROUP would be replaced. This problem can be avoided by using
reference modification in the MOVE statement:
MOVE NEW-NAME-GROUP TO NAME-GROUP ( 1 :LENGTH OF NAME-GROUP )
By specifying the reference modification with the LENGTH OF special register, the
length of NAME-GROUP is now determined by the value in the NAME-LENGTH
variable.

The new value of NAME-GROUP will be:


┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
│ð│5│S│M│I│T│H│ │ │ │ │T│H│O│M│A│S│ │J│
└─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘

Reference Modification Using Data Names


So far, all of the reference modification examples have shown simple numeric
literals as the reference modification starting position and length values. These
values can also be data items or arithmetic expressions.

Suppose a field contains some right-justified characters, and you want to move
them to another field, but left-justified instead of right. Using reference modification
and an INSPECT statement, you can do it.

The program would have the following data:


ð1 LEFTY PIC X(3ð).
ð1 RIGHTY PIC X(3ð)
JUSTIFIED RIGHT.
ð1 I PIC 9(9)
USAGE BINARY.

The program then counts the number of leading spaces, and, using arithmetic
expressions in a reference modification expression, moves the right-justified charac-
ters into another (left-justified) field:
MOVE SPACES TO LEFTY
MOVE ZERO TO I
INSPECT RIGHTY
TALLYING I FOR LEADING SPACE
IF I IS LESS THAN 3ð THEN
MOVE RIGHTY ( I + 1 : 3ð - I ) TO LEFTY
END-IF

264 COBOL/400 User’s Guide


The MOVE statement transfers characters from RIGHTY, beginning at the position
computed in I + 1, for a length that is computed in 30 − I, into the field LEFTY.

Reference Modification with Subscripting


define a table like this:
ð1 ANY-TABLE.
ð5 TABLE-ELEMENT PIC X(1ð)
OCCURS 3 TIMES
VALUE "ABCDEFGHIJ".

You can change both the third and fourth bytes of the first element of
TABLE-ELEMENT to the value “??” with the following MOVE statement:
MOVE "??" TO TABLE-ELEMENT ( 1 ) ( 3 : 2 )

This statement will move the value “??” into table element number 1, beginning at
character position 3, for a length of 2.

ANY-TABLE would look like this before the change:


┌──────────┐
│ABCDEFGHIJ│
├──────────┤
│ABCDEFGHIJ│
├──────────┤
│ABCDEFGHIJ│
└──────────┘

It would look like this after the change:


┌──────────┐
│AB??EFGHIJ│
├──────────┤
│ABCDEFGHIJ│
├──────────┤
│ABCDEFGHIJ│
└──────────┘

De-editing
De-editing allows you to move a numeric-edited data item into a numeric or
numeric-edited receiving data item. The compiler accomplishes this by first estab-
lishing the unedited value of the numeric-edited item. It then moves the unedited
value to the receiver.

De-editing can occur in operations such as MOVE and INITIALIZE. A VALUE


clause does not de-edit.

Note that unedited numeric values can involve signs.

Suppose that you use a character field to contain a numeric value that displays on
the terminal, and also to contain a value that the computer operator supplies.
Suppose that this field has the following definition:
Ÿ One character position for a sign (to contain a space if the numeric field is posi-
tive or zero, or a minus sign if the numeric field is negative);
Ÿ Six digit positions, in which leading zeros are represented by spaces;

Chapter 11. COBOL/400 Programming Considerations 265


Ÿ A decimal point;
Ÿ Two decimal-digit positions.

The data item that you use to define this field would look like this:
ð1 NUM-EDIT PIC −Z(6).9(2) USAGE IS DISPLAY.

You could initialize this field using this statement:


MOVE ZEROS TO NUM-EDIT
and when it displays on the terminal, it would contain the value ␣␣␣␣␣␣␣.00.

Later, the computer operator might use this field for data entry. If the operator puts
␣␣␣␣123.45 into the field, you can obtain the numeric value of the field by moving it
into a data item defined as:
ð1 NUMERIC-ITEM PIC S9(6)V9(2) USAGE IS PACKED-DECIMAL.

This statement:
MOVE NUM-EDIT TO NUMERIC-ITEM
causes de-editing to take place, whereby the numeric item receives the numeric
value of the numeric-edited field NUM-EDIT. As a result, the numeric item contains
the value +123.45.

De-editing Examples
Table 5 and Table 6 show examples of COBOL/400 de-editing.

Table 5. Moving Numeric-edited Items into Numeric Receivers


Source Picture Source Value Receiving Picture Receiving Value
$+++,+++.++ $␣␣␣+123.45 S9(5)V9(5) +123.45
USAGE IS
DISPLAY
$+++,+++.++ $␣−1,234.56 S9(5)V9(5) −1234.56
USAGE IS
BINARY
*****.999+ **123.450− S9(5)V9(5) −123.45
USAGE IS
PACKED-DECIMAL

Table 6. Moving Numeric-edited Items into Numeric-edited Receivers


Source Picture Source Value Receiving Picture Receiving Value
$+++,+++.++ $␣␣␣+123.45 $$$$,$$$.$$CR ␣␣␣␣$123.45␣␣
$+++,+++.++ $␣−1,234.56 −−−−,−−−.99 ␣␣−1,234.56
*****.999+ **123.450− ZZZBZZZBVZZZ ␣␣␣␣123␣450
ZZZ999CR ␣12345␣␣ $++++9999 $␣␣+12345
ZZZ999CR ␣12345CR 999999.99− 012345.00−

266 COBOL/400 User’s Guide


Handling Data Errors
The compiler provides some run-time error checking for move operations that
involve de-editing.

The compiler does not perform this checking for source values of zero, and it
ignores simple insertion characters (such as / B 0 , .).

Sign Test
The compiler validates signs in numeric-edited source items according to the fol-
lowing rules.

PICTURE Definition Allowable Contents


Fixed + + or −
Fixed − ␣ or −
CR ␣␣ or CR
DB ␣␣ or DB

If these rules are disobeyed, a sign error occurs, and the program stops.

Float Test
If the source has a string of floating characters, this test verifies the correctness of
leading floating characters in the data field.

The rules for the float test are:


Ÿ If the source PICTURE clause contains floating $ symbols, the first non-blank
character in the relevant portion of the source field (positions 2 through 7 in the
example) must be a $, and its location must be correct according to the rules
for PICTURE clause editing. (See the COBOL/400 Reference for more infor-
mation about these rules.)
For example:
Location of a Leading Floating Character
ð1 A PIC +$$B,$$$.
.
.
/\ Note that "b" represents one space \/
/\ PIC String: +$$B,$$$ \/
/\ Position indexes: 12345678 \/
MOVE 1 TO A. /\ A = "+bbbbb$1" \/
MOVE 12 TO A. /\ A = "+bbbb$12" \/
MOVE 123 TO A. /\ A = "+bbb$123" \/
MOVE 1234 TO A. /\ A = "+$1b,234" \/

In this example, the $ must be located at position 2, 5, 6, or 7.


Ÿ If the source PICTURE clause contains floating + symbols, the first non-blank
character in the relevant portion of the source field must be + or −, and its
location must be correct according to the rules for PICTURE clause editing.

Chapter 11. COBOL/400 Programming Considerations 267


Ÿ If the source PICTURE clause contains floating − symbols, the relevant portion
of the source field must start with:
– One or more contiguous spaces, the last of which must be correctly located
according to the rules for PICTURE clause editing
– One or more contiguous spaces, with a − immediately following it. The
location of the − must be correct according to the rules for PICTURE clause
editing.
– A −.

If these rules are disobeyed, a float error occurs, and the program stops.

Performance Considerations

PICTURE Clauses for Numeric Items


Because hardware instructions use signs, you can improve performance by
including an S in a picture clause whenever possible.

You can also improve performance by specifying odd numbers of numeric character
positions in the picture clauses for COMP-3 (packed decimal) items. Internally, the
rightmost byte of a packed decimal item contains a digit and a sign, and any other
bytes contain two digits. If you use the more efficient configuration, the compiler
does not need to supply the missing digit.

Eight-Byte Binary Items


Avoid using 8-byte binary items. You can specify these items for convenience, but
the compiler must make conversions in order to use them.

Segmentation
Use of segmentation increases the compile and run times of the COBOL program.
The segmentation feature is provided only for compatibility with other systems. You
do not have to be concerned with storage management when using COBOL/400
programs.

Calling a COBOL Program from a Non-COBOL Program


Repeated calls of a COBOL program from a non-COBOL program can result in a
marked decrease in compiler performance due to the fact that exiting from the main
COBOL program (the program that initiated the COBOL run unit) causes the
program to be deactivated.

268 COBOL/400 User’s Guide


A new function, MGTFUNC has been added to the COBOL run-time routine,
QRLMAIN to prevent this deactivation by causing the main COBOL program to be
treated as a subprogram. Because this fix depends on the size of MGT, it is
recommended that the run-time routine, QLRMAIN be called from the main COBOL
program with MGTFUNC = 9, as shown in the following example:
ð1 mgtstruc.
ð3 FILLER PIC X(277).
ð3 mgtfunc pic 9(2) comp-4 value 9.
77 TEST-VAR PIC X(1ð) value spaces.

if test-var = spaces then


display 'spaces'
move 'faked' to test-var
call 'QLRMAIN' using mgtstruc
else
display 'not spaces ' test-var.

Notes:
1. The ð1 mgtstruc must be on a 16 byte boundary. If a boundary error occurs,
add 77 aa PIC X. in front of the ð1.
2. Because the call to QLRMAIN changes the main COBOL program to a subpro-
gram, you should use the EXIT PROGRAM command and not STOP RUN,
which may cause errors.
3. RCLRSC will deactivate the main program (now a subprogram)

Debugging
COBOL source language debugging is provided to help the COBOL programmer
debug a program that is not functioning as expected. Use of this facility increases
the compile and run times of a COBOL program.

*NORANGE Option
This GENOPT parameter option of the CRTCBLPGM command removes the run-
time checks for subscript and reference modification ranges.

This option can improve performance when:


Ÿ You make frequent references to tables, and the subscripts always reference
elements that are in the tables
Ÿ You use reference modification often.
Note: The *RANGE option generates code for checking subscript ranges. For
example, it ensures that you are not attempting to access the 21st element
of a 20-element array.

The *NORANGE option does not generate code to check subscript or reference
modification ranges.

These options do not eliminate the zero subscript checking performed by the oper-
ating system. If zero subscripts occur, the operating system will not permit their
use and issues message MCH0603.

Chapter 11. COBOL/400 Programming Considerations 269


*DUPKEYCHK Option
This GENOPT parameter option of the CRTCBLPGM command indicates that dupli-
cate key checking for INDEXED files will be performed. Using DUPKEYCHK while
reading INDEXED files can adversely affect performance.

Relative Files
You can experience lengthy delays if you open or close relative files in which very
large volumes of records are being initialized to deleted records.

See Table 4 on page 251 for more information.

Indicators
If you use indicators in a separate indicator area (INDARA keyword specified in
DDS) instead of in the record area, the use of the OCCURS clause to specify a
table with up to 99 indicators can improve performance. See Figure 60 on
page 155 for more information.

Commitment Control
Generally, the use of commitment control increases the run time of a COBOL
program. In addition, the record locking that results from the use of commitment
control by a job may cause delays for other users attempting to access the same
file.

Reading without Record Locks


To avoid unnecessary record locks, you can include the NO LOCK phrase in your
READ statement. For more information about this phrase, refer to the section on
the READ statement in the COBOL/400 Reference.

Initializing Variables
You can reduce program run time by choosing not to initialize program variables
that have no value clauses associated with them. You can specify no initialization
by specifying \NOSTDINZ for the GENOPT parameter of the CRTCBLPGM
command, or by specifying NOSTDINZ in the PROCESS statement. The compiler
then initializes only those variables that have value clauses declared. An additional
benefit to this option is that you can also compile larger programs with a greater
number of variables.

If you specify \NOSTDINZ, you must ensure that all data items contain valid data
before you attempt to manipulate the items. If an item does not contain valid data,
decimal data errors can occur.

Blocking Records
You can use record blocking to improve your run-time performance. The key bene-
fits for blocking are realized when you read multiple records sequentially, such as a
random read followed by sequential reads.

For information on blocking, refer to “Unblocking Input Records and Blocking


Output Records” on page 102.

270 COBOL/400 User’s Guide


Program Loops
When a program repeatedly processes the same series of instructions, and it is
apparent that this will continue indefinitely, the program is in a loop. To identify
loops, you can use information known about the program itself, as follows:
Ÿ Time: If the actual run time is substantially exceeding the expected run time,
the program could be in a loop.
Ÿ I/O operations: If no input/output operations are taking place and I/O is
expected to be occurring repeatedly, the program is probably in a loop.

Tracing a Loop in a Program


Frequently, a loop encompasses many instructions in a program. In this case, you
can use the COBOL debugging features as described in Chapter 5, “Debugging
Your Program” on page 55.

Errors That Can Cause a Loop


A PERFORM statement with an UNTIL clause can cause a loop when the condition
specified in the UNTIL clause cannot be met. For example:
PERFORM ... UNTIL COUNTR LESS THAN ZERO

where COUNTR is an unsigned numeric item.

A GO TO statement that refers to a previous procedure-name can cause a loop


when no conditional statement exists to prevent the GO TO statement from being
processed again. For example:
PARA-1.
MOVE ...
MOVE ...
MOVE ...
PARA-2.
MOVE ...
GO TO PARA-1.

A possible variation of this case occurs when a conditional statement exists, but the
condition cannot be met or the statement does not branch (through a GO TO state-
ment) to a paragraph outside the range of the loop.

Chapter 11. COBOL/400 Programming Considerations 271


272 COBOL/400 User’s Guide
Chapter 12. Communicating Between Programs
Sometimes an application is simple enough to be coded as a single, self-sufficient
program. In many cases, however, an application's solution will consist of several,
separately compiled programs used together.

The AS/400 system provides communication between COBOL programs, and


between COBOL and non-COBOL programs.

A COBOL run unit is a set of one or more programs that function as a unit at run
time to provide a problem solution. A COBOL run unit starts with the first COBOL
program in the program stack, and includes all programs (of any type) that are
below it. A program stack is a list of programs linked together as a result of pro-
grams calling other programs, or implicitly from some other event within the same
job.

When a run unit consists of several, separately compiled programs that call each
other, the programs must be able to communicate with each other. They need to
transfer control and usually need to have access to common data. This chapter
describes the methods that accomplish this interprogram communication between
separately compiled programs.

Transferring Control to Another Program


In the Procedure Division, a program can call another program (generally called a
subprogram in COBOL terms), and this called program may itself call another
program. The program that calls another program is referred to as the calling
program, and the program it calls is referred to as the called program.

The called COBOL program starts running at the top of the Procedure Division.

When the called program processing is completed, the program can either transfer
control back to the calling program or end the run unit.

A called program must not directly or indirectly execute its caller (such as program
X calling program Y; program Y calling program Z; and program Z then calling
program X). This is called a recursive call. COBOL/400 allows recursion in both
main programs and subprograms. However, if you want your programs to conform
to SAA standards, do not use recursive calls.

Main Programs and Subprograms


The first COBOL program to be executed begins the COBOL run unit, and is the
main program. No specific source statements or options identify a COBOL
program to be a main program or a subprogram. A subprogram is a program in
the run unit below the main program in the program stack. For more information
about program stacks and other terms concerning interprogram communication, see
the CL Programmer’s Guide.

 Copyright IBM Corp. 1994 273


Returning Control from a Called Program
It is important to know if a COBOL program is a main program or a subprogram to
determine how control is returned from a called program when an error occurs, or a
program ends.

You can issue a STOP RUN, EXIT PROGRAM, or GOBACK statement to return
control from a called program.

If execution ends in the main program, either STOP RUN or GOBACK is used.
These statements end the run unit, and control is returned to the caller of the main
program.

If execution ends in a subprogram, the subprogram may end with an EXIT


PROGRAM, a GOBACK, or a STOP RUN statement. If the subprogram ends with
an EXIT PROGRAM or a GOBACK statement, control returns to its immediate
caller without ending the run unit. An implicit EXIT PROGRAM statement is gener-
ated if there is no next executable statement in a called program. If it ends with a
STOP RUN statement, the effect is the same as it is in a main program: all
COBOL programs in the run unit are terminated, and control returns to the caller of
the main program.

A subprogram is left in its last-used state when it terminates with EXIT PROGRAM
or GOBACK. The next time it is called in the run unit, its internal values will be as
they were left, except that return values for PERFORM statements will be reset to
their initial values. In contrast, a main program is initialized each time it is called.

The following examples illustrate the use of the EXIT PROGRAM and STOP RUN
statements in different parts of a run unit.
Ÿ The example in Figure 85 on page 275 shows a single run unit.
Ÿ The example in Figure 86 on page 276 shows multiple run units that run con-
secutively
Ÿ The example in Figure 87 on page 277 shows a run unit with a shared
program that is both a subprogram and a main program.
Ÿ The example in Figure 88 on page 278 shows multiple run units that run con-
currently.
Note: You can substitute a GOBACK statement for an EXIT PROGRAM statement
that appears in a subprogram, or a STOP RUN statement that appears in a
main program.

274 COBOL/400 User’s Guide


CALL
RUN UNIT A LEVEL
┌─ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ──┐
│ │
┌─────────────────┐
│ │ PGMA │ │
│ │ n
│ │ Main │ │
│ Program COBOL │
│ └────────┬────────┘ │

│ ┌─────────────┴──────────────┐ │
│ │
│ │ │ │
┌────────┴────────┐ ┌────────┴────────┐
│ │ PGMB │ │ PGMC │ │
│ │ │ │ n + 1
│ │ │ │ │ │
│ COBOL │ │ Non-COBOL │
│ └────────┬────────┘ └────────┬────────┘ │
│ │
│ │ │ │
┌───────────┴─────────┐ ┌─────────┴────────────┐
│ │ │ │ │ │
┌──────┴───────┐ ┌───┴────────┴───┐ ┌────────┴───────┐
│ │ PGMD │ │ PGME │ │ PGMF │ │
│ │ │ │ │ │ n + 2
│ │ │ │ │ │ │ │
│ COBOL │ │ COBOL │ │ Non-COBOL │
│ └──────────────┘ └────────────────┘ └────────────────┘ │
└─ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ──┘

PROGRAM RUNNING STATEMENT


┌─────────┬──────────┬──────────┬─────────┐
STATEMENT │ PGMA │ PGMB │ PGMD │ PGME │
┌────────────────────┼─────────┼──────────┼──────────┼─────────┤
│ │ │ │ │ │
│ EXIT PROGRAM │ .1/ │ .2/ │ .2/ │ .2/ │
├────────────────────┼─────────┼──────────┼──────────┼─────────┤
│ │ │ │ │ │
│ STOP RUN │ .3/ │ .3/ │ .3/ │ .3/ │
└────────────────────┴─────────┴──────────┴──────────┴─────────┘

Figure 85. Example of a Single Run Unit

.1/ No operation is processed because the statement is processed in a main


program. Processing continues with the next statement in PGMA.
.2/ Control returns to the caller of the program that processes the EXIT
PROGRAM statement.
.3/ Run unit A ends. For all programs in the run unit, open files are closed.
Storage is freed for all programs in the run unit. Control returns to the
program that is at call level n-1. If n=1, the following considerations apply:
Ÿ Run unit A operates as a job step. See the CL Programmer’s Guide for
more information.
Ÿ For batch jobs, the STOP RUN statement ends the job. For interactive
jobs, control returns to the system and the system ends the job step.

Chapter 12. Communicating Between Programs 275


CALL
LEVEL
┌─────────────────┐
│ PGMA │
│ │ n
│ │
│ Non-COBOL │
└────────┬────────┘

┌─────────────┴──────────────┐
RUN UNIT B │ │ RUN UNIT C
┌─ ── ── ── ── ── ── ┼─ ── ── ── ──┐ ┌─ ── ── ── ┼─ ── ── ── ── ── ── ─ ─┐
┌────────┴────────┐ │ │ ┌────────┴────────┐ │
│ │ PGMB │ │ PGMC │
│ │ │ │ │ │ │ n + 1
│ │ Main │ │ Main │
│ Program COBOL │ │ │ │ Program COBOL │ │
│ └────────┬────────┘ └────────┬────────┘
│ │ │ │ │
│ │ ┌─ ── ── ── ──┘ │
┌───────────┴──┼──────┐ │ ┌─────────┴────────────┐ │
│ │ │ └── ─┼─ ── ─┐ │
┌──────┴───────┐ │ ┌───┴────────┴───┐ ┌────────┴───────┐ │
│ │ PGMD │ │ PGME │ │ │ PGMF │
│ │ │ │ │ │ │ │ n + 2
│ │ │ │ │ │ │ │
│ Non-COBOL │ │ │ COBOL │ │ COBOL │ │
│ └──────────────┘ └────────────────┘ │ └────────────────┘
└─ ── ── ── ── ── ── ── ┼─ ── ── ── ── ── ── ──┘ │
└─ ── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ──┘

PROGRAM RUNNING STATEMENT


┌─────────┬──────────┬──────────┬─────────┬────────┐
│ │ │ PGME │ PGME │ │
│ PGMB │ PGMC │ (RUN │ (RUN │ PGMF │
STATEMENT │ │ │ UNIT B) │ UNIT C) │ │
┌────────────────────┼─────────┼──────────┼──────────┼─────────┼────────┤
│ │ │ │ │ │ │
│ EXIT PROGRAM │ .1/ │ .1/ │ .2/ │ .2/ │ .2/ │
├────────────────────┼─────────┼──────────┼──────────┼─────────┼────────┤
│ │ │ │ │ │ │
│ STOP RUN │ .3/ │ .4/ │ .3/ │ .4/ │ .4/ │
└────────────────────┴─────────┴──────────┴──────────┴─────────┴────────┘

Figure 86. Example of Multiple Run Units That Run Consecutively

.1/ No operation is processed because the statement is processed in a main


program. Processing continues with the next statement in the main program.
.2/ Control returns to the caller of the program that processes the EXIT
PROGRAM statement.
.3/ Run unit B ends. All open files in run unit B are closed. Storage is freed for
all programs in run unit B. Control returns to the caller of the main program
for the run unit (PGMA).
.4/ Run unit C ends. All open files in run unit C are closed. Storage is freed for
all programs in run unit C. Control returns to the caller of the main program
for the run unit (PGMA).

276 COBOL/400 User’s Guide


CALL
LEVEL

┌─────────────────┐
│ PGMA │
│ │ n
│ │
│ Non-COBOL │
└────────┬────────┘

┌─────────────┴──────────────┐
RUN UNIT B │ │
┌── ── ── ── ── ── ──│── ── ── ── ─┐ │
│ ┌────────┴────────┐ │ ┌────────┴────────┐
│ PGMB │ │ PGMC │
│ │ │ │ │ │ n + 1
│ Main │ │ │
│ │ Program COBOL │ │ │ Non-COBOL│
└────────┬────────┘ └────────┬────────┘
│ │ └─ ── ── ── ─┐ │
│ │ │
│ ┌───────────┴─────────┐ ┌─────────┴────────────┐
│ RUN│ UNIT E │ │ RUN│ UNIT F
│ │ ┌─ ── ┼─ ── ── ┼─ ── ┐ ┌─ ── ── ──│── ── ── ┐
┌──────┴───────┐ │ ┌───┴────────┴───┐ │ │ ┌────────┴───────┐ │
│ │ PGMD │ │ PGME │ │ │ PGMF │
│ │ │ │ │ │ │ │ │ │ n + 2
│ │ │ │ │ │ │Main │
│ Non-COBOL │ │ │ COBOL │ │ │ │Program COBOL │ │
│ └──────────────┘ └────────────────┘ │ └────────────────┘
└─ ── ── ── ── ── ── ┘ │ └─ ── ── ── ── ── ── ┘
└── ── ── ── ── ── ── ── ── ── ── ── ── ── ── ──┘

PROGRAM RUNNING STATEMENT


┌─────────┬──────────┬──────────┬──────────┐
│ │ PGME │ PGME │ │
│ PGMB │ (RUN │ (RUN │ PGMF │
STATEMENT │ │ UNIT B) │ UNIT E) │ │
┌────────────────────┼─────────┼──────────┼──────────┼──────────┤
│ │ │ │ │ │
│ EXIT PROGRAM │ .1/ │ .2/ │ .1/ │ .1/ │
├────────────────────┼─────────┼──────────┼──────────┼──────────┤
│ │ │ │ │ │
│ STOP RUN │ .3/ │ .3/ │ .4/ │ .5/ │
└────────────────────┴─────────┴──────────┴──────────┴──────────┘

Figure 87. Example of a Run Unit with a Shared Program that is Both a Subprogram and a
Main Program

.1/ No operation is processed because the statement is processed in a main


program. Processing continues with the next statement in the main program.
.2/ Control returns to the caller of the program that processes the EXIT
PROGRAM statement.
.3/ Run unit B ends. All open files in run unit B are closed. Storage is freed for
all programs in run unit B. Control returns to the caller of the main program
for the run unit (PGMA).

Chapter 12. Communicating Between Programs 277


.4/ Run unit E ends. All open files in run unit E are closed. Storage is freed for
PGME. Control returns to the caller of the main program for the run unit
(PGMC).
.5/ Run unit F ends. All open files in run unit F are closed. Storage is freed for
PGMF. Control returns to the caller of the main program for the run unit
(PGMC).
CALL
LEVEL
┌─────────────────┐
│ PGMA │
│ │ n
│ │
│ Non-COBOL │
RUN UNIT B └────────┬────────┘
┌ ── ── ── ── ── ── ── ── ┼─ ── ── ┐
6 │
│ ┌─────────────────┐
│ PGMB │ │ n+1
│ │ │
│ Main │ │
│ │ Program COBOL │
└─────┬───────────┘ │
│ ┌─────────────────┴──┐
6 6 │
│ ┌─────────────────┐ ┌─────────────────┐ n+2
│ PGMC │ │ PGMD │ │
│ │ │ │ │
│ │ │ │ │
│ │ COBOL │ │ non-COBOL │ RUN UNIT E
└─────────────────┘ └─────────────┬───┘ │ ┌─ ── ── ── ── ── ┐
│ ┌────┴────────┼──────────┐
6 │ 6 │
│ ┌─────────────────┐ │ ┌─────────────────┐
│ PGM QLRCHGCM │ │ │ PGME │ │ n+3
│ │ │ │ │ Main │
│ │ │ │ Program │ │
│ │ API │ │ │ 2 COBOL │
└─────────────────┘ │ └────────┬────────┘ │
└─ ── ── ── ── ── ── ── ── ── ── ── ┘ │ │
6 │
│ ┌─────────────────┐
│ PGMF │ │ n+4
│ │ │
│ │ │
│ │ COBOL │
└─────────────────┘ │
└ ── ── ── ── ── ┘

PROGRAM RUNNING STATEMENT


┌─────────┬──────────┬──────────┬──────────┐
│ │ PGMC │ PGME │ PGMF │
│ PGMB │ (RUN │ │ (RUN │
STATEMENT │ │ UNIT B) │ │ UNIT E) │
┌────────────────────┼─────────┼──────────┼──────────┼──────────┤
│ │ │ │ │ │
│ EXIT PROGRAM │ .1/ │ .2/ │ .1/ │ .2/ │
├────────────────────┼─────────┼──────────┼──────────┼──────────┤
│ │ │ │ │ │
│ STOP RUN │ .3/ │ .3/ │ .4/ │ .4/ │
└────────────────────┴─────────┴──────────┴──────────┴──────────┘

Figure 88. Example of Multiple Run Units That Run Concurrently

.1/ No operation is processed because the statement is processed in a main


program. Processing continues with the next statement in the main program.
.2/ Control returns to the caller of the program that processes the EXIT
PROGRAM statement.

278 COBOL/400 User’s Guide


.3/ Run unit B can only end after run unit E completes a STOP RUN. When run
unit B ends, all open files in run unit B are closed. Storage is freed for all
programs in run unit B, and control returns to the caller of the main program
(PGMA).
.4/ Run unit E ends. All open files in run unit E are closed. Storage is freed for
all programs in run unit E. Control returns to PGMD in run unit B.

Concurrent run units are achieved by using the QLRCHGCM API. Refer to the
System Programmer’s Interface Reference for more information on this API.

Initialization of Storage
The first time a COBOL program in a run unit is called, its storage is initialized.
Storage is initialized again under the following conditions:
Ÿ The run unit is terminated, then reinitiated.
Ÿ The program is canceled (using the CANCEL statement for COBOL, the FREE
operation for the RPG/400* programming language, or the Reclaim Resource
(RCLRSC) command), and then called again.

If a non-COBOL program is named in a CANCEL statement, its name must


conform to the rules for formation of a COBOL program name.

Calling Another Program


You will often want your COBOL programs to communicate with other COBOL and
non-COBOL programs.

Passing Data Using BY REFERENCE or BY CONTENT


BY REFERENCE means that the subprogram is referring to and processing the
data items in the calling program's storage, rather than working on a copy of the
data.

BY CONTENT means that the calling program is passing only the contents of the
literal, or identifier. With a CALL . . . BY CONTENT, the called program cannot
change the value of the literal or identifier in the calling program, even if it modifies
the variable in which it received the literal or identifier.

Whether you pass data items BY REFERENCE or BY CONTENT depends on what


you want your program to do with the data:
Ÿ If you want the definition of the argument of the CALL statement in the calling
program and the definition of the parameter in the called program to share the
same memory, specify:
CALL . . . BY REFERENCE identifier.
Any changes made by the subprogram to the parameter affect the argument in
the calling program.
An identifier in the USING phrase of the CALL . . . BY REFERENCE statement
may be a file-name, in addition to a data-name.
File-names as CALL operands are allowed by the compiler as an extension.

Chapter 12. Communicating Between Programs 279


Ÿ If you want to pass the address of a record area to a called program, specify:
CALL . . . BY REFERENCE ADDRESS OF record-name.
The subprogram receives the ADDRESS OF special register for the record-
name you specify.
You must define the record name as a level-01 or level-77 item in the Linkage
Section of the called and calling programs. A separate ADDRESS OF special
register is provided for each record in the Linkage Section.
Ÿ If you do not want the definition of the argument of the CALL statement in the
calling program and the definition of the parameter in the called subprogram to
share the same memory, specify:
CALL . . . BY CONTENT identifier.
Ÿ If you want to pass a literal value to a called program, specify:
CALL . . . BY CONTENT literal.
The called program cannot change the value of the literal. The literal cannot
be numeric.
Ÿ If you want to pass the length of a data item, specify:
CALL . . . BY CONTENT LENGTH OF identifier.
The calling program passes the length of identifier from its LENGTH OF special
register. When literals are passed BY CONTENT, the called program cannot
change their values.
Ÿ If you want to pass both a data item and its length to a subprogram, specify a
combination of BY REFERENCE and BY CONTENT. For example:
CALL 'ERRPROC' USING BY REFERENCE A
BY CONTENT LENGTH OF A.

Data items in a calling program can be described in the Linkage Section of all the
programs it calls directly or indirectly. In this case, storage for these items is allo-
cated in the highest calling program. That is, program A calls program B, which
calls program C. Data items in program A can be described in the Linkage
Sections of programs B and C, so that one set of data can be made available to all
three programs.

Describing Arguments in the Calling Program


In the calling program, the arguments are described in the Data Division in the
same manner as other data items in the Data Division. Unless they are in the
Linkage Section, storage is allocated for these items in the calling program. If you
reference data in a file, the file must be open when the data is referenced. Code
the USING clause of the CALL statement to pass the arguments.

Describing Parameters in the Called Program


In the called program, parameters are described in the Linkage Section. Code the
USING clause after the PROCEDURE-DIVISION header to receive the parameters.

280 COBOL/400 User’s Guide


In the Linkage Section
You must know what is being passed from the calling program and set up the
Linkage Section in the called program to accept it. To the called program, it
doesn't matter which clause of the CALL statement you use to pass the data (BY
REFERENCE or BY CONTENT). In either case, the called program must describe
the data it is receiving. It does this in the Linkage Section.

The number of data-names in the identifier list of a called program must not be
greater than the number of data-names in the identifier list of the calling program.
There is a one-to-one positional correspondence; that is, the first identifier of the
calling program is passed to the first identifier of the called program, and so forth.
The compiler makes no attempt to match arguments and parameters.

Grouping Data to be Passed


Consider grouping all the data items you want to pass between programs and
putting them under one level-01 item. If you do this, you can pass a single level-01
record between programs. For an example of this method, see Figure 89.

To make the possibility of mismatched records even smaller, put the level-01 record
in a copy member, and copy it in both programs. (That is, copy it in the Working-
Storage Section of the calling program and in the Linkage Section of the called
program.)

Calling Program Description Called Program Description

WORKING─STORAGE SECTION. LINKAGE SECTION.


┌───────────────────────────┐ ┌──────────────────────────┐
│ð1 PARAM─LIST. │ │ð1 USING─LIST. │
│ ð5 PARTCODE PIC A. ├─────────5│ 1ð PART─ID PIC X(5). │
│ ð5 PARTNO PIC X(4). │ │ 1ð SALES PIC 9(5). │
│ ð5 U─SALES PIC 9(5). │ │ │
└──────────────────────┬────┘ └────────────────────┬─────┘
. │ . │
. │ . │
. │ . │
│ │
PROCEDURE DIVISION. │ PROCEDURE DIVISION 6
. │ ┌───────────┐
. │ USING │USING─LIST.│
. │ └───────────┘

CALL CALLED─PROG 6
┌───────────┐
USING │PARAM─LIST.│ In the called program, the code
└───────────┘ for parts and the part number
are combined into one data item
In the calling program, the code (PART─ID). In the called
for parts (PARTCODE) and the part program, a reference to PART─ID
number (PARTNO) are referred to is the only valid reference to
separately. them.

Figure 89. Common Data Items in Subprogram Linkage

Chapter 12. Communicating Between Programs 281


Call by Identifier
A system pointer that associates an identifier with an object is set the first time you
use the identifier in a CALL statement.

Important for compatibility!

If you carry out a call by an identifier to a program that you subsequently delete
or rename, you must use the CANCEL statement to null the system pointer
associated with the identifier. This ensures that when you next use the identi-
fier to call your program, the associated system pointer will be set again.

The following example shows how to apply the CANCEL statement to an identifier:
MOVE "ABCD" TO IDENT-1.
CALL IDENT-1.
CANCEL IDENT-1.
If you apply the CANCEL statement directly to the literal "ABCD", you do not null
the system pointer associated with IDENT-1. Instead, you can continue to call
program ABCD simply by using IDENT-1 in your CALL statement.

The value of the system pointer also changes if you change the value of the identi-
fier and perform a call using this new value.

Using Pointers in a COBOL/400 Program


You can use a pointer (a data item in which address values can be stored) within
a COBOL program when you want to pass and receive addresses of a variably-
located data item, and to accomplish limited base addressing.

On the AS/400 system, pointers are 16 bytes long. COBOL pointers are AS/400
space pointers since they point to system space objects. One part of the pointer
describes its attributes, such as which AS/400 space object it is pointing to.
Another part of the pointer contains the offset into the AS/400 system space object.

To define a COBOL pointer, called a pointer data item, code a USAGE IS


POINTER clause on the data item. A pointer data item is a 16-byte elementary
item that can be compared for equality, or used to set the value of other pointer
items.

A pointer data item can be used only in:


A SET statement (Format 5 only)
A relation condition
The USING phrase of a CALL statement, or the Procedure Division header.
The operand for the LENGTH OF and ADDRESS OF special registers.

If pointers are used in a relational condition, the only valid operators are equal to,
or not equal to.

Because pointer data items are not simply binary numbers on the AS/400 system,
manipulating pointers as integers does not work.

282 COBOL/400 User’s Guide


Pointer data items are defined explicitly with the USAGE IS POINTER clause, and
are implicit when using an ADDRESS OF special register or the ADDRESS OF an
item.

If a group item is described with the USAGE IS POINTER clause, the elementary
items within the group item are pointer items. The group itself is not a pointer data
item, and cannot be used in the syntax where a pointer data item is allowed. The
USAGE clause of an elementary item cannot contradict the USAGE clause of a
group to which the item belongs.

Pointer data items can be part of a group that is referred to in a MOVE statement
or an input/output statement; however, if a pointer data item is part of a group,
there is no conversion of pointer values to another form of internal representation
when the statement is executed.

Defining Pointers and Pointer Alignment


Pointer data items can be defined at any level (except 88) in the File, Working-
Storage, or Linkage sections of a program.

When a pointer is referenced on the AS/400 system, it must be on a 16-byte


storage boundary. Pointer alignment refers to the COBOL/400 compiler's process
of positioning pointer items within a group item to offsets that are multiples of 16
bytes from the beginning of the record. If a pointer item is not on a 16-byte
boundary, a pointer alignment exception (MCH0602) is sent to the COBOL/400
program. In general, pointer alignment exceptions occur in the Linkage Section,
where it is up to the user to align these items.

In the File and Working-Storage sections, the compiler ensures that this exception
does not occur by adding implicit FILLER items. Every time an implicit FILLER
item is added by the compiler, a warning is issued. In the Linkage Section, no
implicit FILLER items are added by the compiler; however, warnings are issued
indicating how many bytes of FILLER would have been added had the group item
appeared in the File or Working-Storage sections.

You can define a data item as a pointer by specifying the USAGE IS POINTER
clause as shown in the following example:

WORKING-STORAGE SECTION.
77 APTR USAGE POINTER.
ð1 AB.
ð5 BPTR USAGE POINTER.
ð5 BVAR PIC S9(3) PACKED-DECIMAL.
LINKAGE SECTION.
ð1 AVAR.
ð5 CVAR PIC X(3ð).
PROCEDURE DIVISION.
SET APTR TO ADDRESS OF AVAR.

Figure 90. Defining a Pointer Data Item

In the above example, AVAR is an 01-level data item, so the ADDRESS OF AVAR
is the ADDRESS OF special register. Because a special register is an actual
storage area, the SET statement moves the contents of ADDRESS OF AVAR into
pointer data item APTR.

Chapter 12. Communicating Between Programs 283


In the above example, if the SET statement used ADDRESS OF CVAR, no special
register exists. Instead, the pointer data item APTR is assigned the calculated
address of CVAR.

In File and Working-Storage Sections


In the File and Working-Storage sections, all 01-level items (and some 66 and
77-level items) are placed on 16-byte boundaries.

Within a group structure, pointer data items must also occur on a 16-byte boundary.
To ensure this, the COBOL/400 compiler adds FILLER items immediately before
the pointer data item. To avoid these FILLER items, you should place pointer data
items at the beginning of a group item.

If the pointer data item is part of a table, the first item in the table is placed on a
16-byte boundary. To ensure that all subsequent occurrences of the pointer fall on
a 16-byte boundary, a FILLER item is added to the end of the table if necessary.

An example of pointer data item alignment follows:

WORKING-STORAGE SECTION.
77 APTR USAGE POINTER.
ð1 AB.
ð5 ALPHA-NUM PIC X(1ð).
ð5 BPTR USAGE POINTER.
ð1 EF.
ð5 ARRAY-1 OCCURS 3 TIMES.
1ð ALPHA-NUM-TWO PIC X(14).
1ð CPTR USAGE POINTER.
1ð ALPHA-NUM-THREE PIC X(5).
Figure 91. Aligning Pointer Data Items

In the above example, APTR is a pointer data item. The 77-level item, therefore, is
placed on a 16-byte boundary. The group item AB is an 01-level item and is auto-
matically placed on a 16-byte boundary. Within the group item AB, BPTR is not on
a 16-byte boundary. To align it properly, the compiler inserts a 6-byte FILLER item
after ALPHA-NUM. Finally, CPTR requires a FILLER of 2 bytes to align its first
occurrence. Because ALPHA-NUM-THREE is only 5 bytes long, another 11-byte
FILLER must be added to the end of ARRAY-1 to align all subsequent occurrences
of CPTR.

When a pointer is defined in the File Section, and a file does not have blocking in
effect, each 01-level item will be on a 16-byte boundary. If a file has blocking in
effect, only the first record of a block is guaranteed to be on a 16-byte boundary.
Thus pointer data items should not be defined for files with blocking in effect. For
more information on blocking, refer to “Unblocking Input Records and Blocking
Output Records” on page 102.

Pointers and the REDEFINES Clause


A pointer data item may be the subject or object of a REDEFINES clause.

When a pointer is the subject of a REDEFINES clause, the object data item must
be on a 16-byte boundary.

284 COBOL/400 User’s Guide


For example:

WORKING-STORAGE SECTION.
ð1 AB.
ð5 ALPHA-NUM PIC X(16).
ð5 APTR REDEFINES ALPHA-NUM USAGE POINTER.
ð5 BPTR USAGE POINTER.
ð5 CPTR REDEFINES BPTR USAGE POINTER.
Figure 92. REDEFINES and Aligned Pointer Data Items

In the above example, both APTR and CPTR are pointer data items that redefine
16-byte aligned items. In the following example, the redefined item would result in
a severe compiler error:

WORKING-STORAGE SECTION.
ð1 EF.
ð5 ALPHA-NUM PIC X(5).
ð5 HI.
1ð ALPHA-NUM-TWO PIC X(11).
1ð APTR USAGE POINTER.
ð5 BPTR REDEFINES HI USAGE POINTER.
Figure 93. REDEFINES and Aligned Pointer Data Items - Incorrect Method

In the above example, APTR is aligned on a 16-byte boundary. That is, the
COBOL/400 compiler did not need to add FILLER items to align APTR. The group
item HI is not on a 16-byte boundary, and so neither is pointer data item BPTR.
Because the COBOL/400 compiler cannot add FILLER items to place BPTR on a
16-byte boundary, a severe error will result. In the following example, similar to the
above, the COBOL/400 compiler is able to place the pointer data item on a 16-byte
boundary:

WORKING-STORAGE SECTION.
ð1 EF.
ð5 ALPHA-NUM PIC X(5).
ð5 HI.
1ð ALPHA-NUM-TWO PIC X(11).
1ð APTR USAGE POINTER.
1ð ALPHA-NUM-THREE PIC X(5).
ð5 KL REDEFINES HI.
1ð BPTR USAGE POINTER.
Figure 94. REDEFINES and Unaligned Pointer Data Items - Correct Method

In the above example, group item KL is not on a 16-byte boundary; however, the
compiler adds an 11-byte FILLER before pointer data item BPTR to ensure that it
falls on a 16-byte boundary.

Reading and Writing Pointers


Pointer data items can be defined in the File Section, and can be set and used as
can any other Working-Storage pointer data items. There are, however, some
restrictions:
Ÿ If a file has blocking in effect, only the first record of a block is guaranteed to
be on a 16-byte boundary. Thus pointer data items should not be defined for
files with blocking in effect.

Chapter 12. Communicating Between Programs 285


Ÿ A record containing pointers can be written to a file; however, on subsequent
reading of that record, the pointer data items equal NULL.

Initializing Pointers Using the NULL Figurative Constant


The NULL figurative constant represents a value used to indicate that data items
defined with USAGE IS POINTER, ADDRESS OF, or the ADDRESS OF special
register do not contain a valid address. For example:

WORKING-STORAGE SECTION.
77 APTR USAGE POINTER VALUE NULL.
PROCEDURE DIVISION.
IF APTR = NULL THEN
DISPLAY 'APTR IS NULL'
END-IF.
Figure 95. Using NULL to Initialize a Pointer

In the above example, pointer APTR is set to NULL in the Working-Storage section.
The comparison in the procedure division will be true and the display statement is
executed.

On the AS/400 system, the initial value of a pointer data item with or without a
VALUE clause of NULL, equals NULL.

LENGTH OF Special Register


The LENGTH OF special register contains the number of bytes used by an identi-
fier. It returns a value of 16 for a pointer data item.

You can use LENGTH OF in the Procedure Division anywhere a numeric data item
having the same definition as the implied definition of the LENGTH OF special reg-
ister is used; however, LENGTH OF cannot be used as a subscript or a receiving
data item. LENGTH OF has the implicit definition:
USAGE IS BINARY, PICTURE 9(9)

The following example shows how you can use LENGTH OF with pointers:

WORKING-STORAGE SECTION.
77 APTR USAGE POINTER.
ð1 AB.
ð5 BPTR USAGE POINTER.
ð5 BVAR PIC S9(3) PACKED-DECIMAL.
ð5 CVAR PIC S9(3) PACKED-DECIMAL.
PROCEDURE DIVISION.
MOVE LENGTH OF AB TO BVAR.
MOVE LENGTH OF BPTR TO CVAR.
Figure 96. Using LENGTH OF with Pointers

In the above example, the length of group item AB is moved to variable BVAR.
BVAR has a value of 20 because BPTR is 16 bytes long, and both variables BVAR
and CVAR are 2 bytes long. CVAR receives a value of 16.

You can also use the LENGTH OF special register to set up data structures within
user spaces, or to increment addresses received from another program. To see an

286 COBOL/400 User’s Guide


example of a program that uses the LENGTH OF special register to define data
structures within user spaces, refer to Figure 99 on page 291.

Setting the Address of Linkage Items


Generally, when one COBOL program calls another, data passes between the two
programs in the following manner: the calling program uses the CALL USING state-
ment to pass operands to the called program, and the called program specifies the
USING phrase in the Procedure Division header. There should be a one-to-one
mapping between the operands in the USING phrases of each program.

When using the ADDRESS OF special register, you no longer need to ensure a
one-to-one mapping between the USING phrases of the two programs. For those
data items in the Linkage Section that are not specified in the USING phrase of the
Procedure Division header, you can use a SET statement to specify the starting
address of the data structure. Once the SET statement is run, the data item is then
treated as if it was passed from another program. For an example of a SET state-
ment used in this manner, refer to Figure 100 on page 292. .16/ on page 295
illustrates how the SET statement is used to set the starting address of the data
structures ls-header-record and ls-user-space at the beginning of the user space.

Using ADDRESS OF and the ADDRESS OF Special Register


When you specify ADDRESS OF in a COBOL program, the compiler determines
whether to use the calculated address of a data item, referred to as ADDRESS OF,
or the ADDRESS OF special register. The ADDRESS OF special register is the
starting address of the data structure from which all calculated addresses are deter-
mined. Because the ADDRESS OF special register is the starting address of a
structure, it must be an 01-level or 77-level data item. If you reference modify this
data item, it is no longer the starting address of the data structure. It is a calcu-
lated address, or ADDRESS OF. If you are taking the ADDRESS OF an elemen-
tary item, and the ADDRESS OF the 01-level item has been set to NULL, a pointer
exception (MCH3601) results.

You cannot use the calculated ADDRESS OF where an item can be changed.
Only the ADDRESS OF special register can be changed. For example, in
Figure 100, the SET statement at .18/ on page 295 uses the ADDRESS OF
special register because it is an 01-level item. At .19/ on page 295 ADDRESS OF
is used because, although it is an 01-level item, it is reference-modified.

Using Pointers in a MOVE Statement


Elementary pointer data items cannot be moved using the MOVE statement; a SET
statement must be used; however, pointer data items are implicitly moved when
they are part of a group item.

When compiling a MOVE statement, the COBOL/400 compiler generates code to


maintain (a pointer MOVE) or not maintain (a non-pointer MOVE) pointers within a
group item.

A pointer MOVE is done when all of the following conditions are met:
1. The source or receiver of a MOVE statement contains a pointer
2. Both of the items are at least 16 bytes long

Chapter 12. Communicating Between Programs 287


3. The data items are properly aligned
4. The data items are alphanumeric or group items.

Of the conditions listed above, determining if two data items are properly aligned
can be the most difficult.

If the items being moved are 01-level items, or are part of an 01-level item, they
must be on the same offset relative to a 16-byte boundary for a pointer MOVE to
occur. (A warning is issued if this is not true.) The following example shows three
data structures, and the results when a MOVE statement is issued:

WORKING-STORAGE SECTION.
ð1 A.
ð5 B PIC X(1ð).
ð5 C.
1ð D PIC X(6).
1ð E POINTER.
ð1 A2.
ð5 B2 PIC X(6).
ð5 C2.
1ð D2 PIC X(1ð).
1ð E2 POINTER.
ð1 A3.
ð5 B3 PIC X(22).
ð5 C3.
1ð D3 PIC X(1ð).
1ð E3 POINTER.

PROCEDURE DIVISION.
MOVE A to A2. .1/
MOVE A to A3. .1/
MOVE C to C2. .2/
MOVE C2 to C3. .3/

.1/ This results in a pointer move because the offset of each group item to
be moved is zero. Pointer integrity is maintained.
.2/ This results in a non-pointer move, because the offsets do not match.
The offset of group item C is 10, and the offset of group item C2 is 6.
Pointer integrity is not maintained.
.3/ This results in a pointer move, because the offset of group item C2 is 6,
and the offset of C3 relative to a 16-byte boundary is also 6. (When the
offset is greater than 16, the offset relative to a 16-byte boundary is cal-
culated by dividing the offset by 16. The remainder is the relative offset.
In this case, the offset was 22, which, when divided by 16, leaves a
remainder, or relative offset, of 6.) Pointer integrity is maintained.
If a group item contains a pointer, and the compiler cannot determine
the offset relative to a 16-byte boundary, the compiler issues a warning
message, and the pointer move is attempted. However, pointer integrity
may not be maintained. The compiler cannot determine the offset if the
item is defined in the Linkage Section, or if the item is reference-
modified with an unknown starting position. You must ensure that
pointer alignment is maintained, or MCH0602 may result.

288 COBOL/400 User’s Guide


The COBOL/400 compiler places all 01-level items on a 16-byte boundary whether
or not they contain pointer data items.

If one of the items in a MOVE statement is an 01-level item with a pointer, and the
other a 77-level Working-Storage item, the 77-level Working-Storage item is forced
to a 16-byte boundary.

Using Pointers in a CALL Statement


When a pointer data item is passed in a CALL statement, the item is treated as all
other USING items. In other words, a pointer to the pointer data item (or copy of
the pointer data item) is passed to the called program.

Special consideration must be given when a CALL statement with the BY


CONTENT phrase is used to pass pointers and group items containing pointers.
This is similar to the case of a MOVE statement. For a CALL BY CONTENT, an
implicit MOVE of an item is done to create it in a temporary area. If the compiler
can determine the offset of an item relative to a 16-byte boundary, that same offset
is used when the implicit MOVE of the BY CONTENT item is done into the tempo-
rary area. When the compiler cannot determine the offset of an item relative to a
16-byte boundary, the implicit MOVE of the BY CONTENT item is done into a tem-
porary area that is aligned on a 16-byte boundary.

The compiler is not able to determine the offset of an item relative to a 16-byte
boundary when the BY CONTENT item is:
Ÿ Reference modified with an unknown starting position, or
Ÿ Defined in the Linkage Section.

When an operand is reference-modified, the offset is the reference modification


starting position minus one, plus the operand's offset within the data structure.
When an operand is in the Linkage Section, its offset can be determined from the
calling program.

To avoid pointer alignment problems, pass items by reference.

The following is an example of passing items containing pointers, where pointer


integrity is maintained in some cases, and not in others.

WORKING-STORAGE SECTION.

ð1 A. .1/
ð5 B PIC X(3).
ð5 C..2/
1ð FILLER PIC X(13).
1ð D POINTER.

PROCEDURE DIVISION.

CALL "B" USING A C.


Figure 97. Program A -- Main Program

Chapter 12. Communicating Between Programs 289


WORKING-STORAGE SECTION.

ð1 E.
ð5 F PIC X(16).
ð5 G POINTER.
77 K PIC S9(3) VALUE 8.

LINKAGE SECTION.

ð1 A. .3/
ð5 B PIC X(3).
ð5 C.
1ð FILLER PIC X(13).
1ð D POINTER.
ð1 C2..4/
ð5 FILLER PIC X(13).
ð5 D2 POINTER.

PROCEDURE DIVISION USING A C2.

CALL "C" USING BY CONTENT


A, C2,.5/ E(5: ),.6/ E(K: ),.7/ F. .8/

Figure 98. Program B -- Subprogram

In the previous example, Program A passes two group items to Program B. .1/ is
an 01-level group item, with an offset of zero. .2/ is an 05-level group item, and
has an offset of 3. Because the items are passed by reference, pointer integrity is
maintained for both group items A and C.

Program B passes five items to another program, C. The items are passed by
content to Program C. Because they are passed by content, Program C receives a
copy of the items, and pointer integrity is not maintained in all cases.
Ÿ .3/ Because this item is defined in the Linkage Section, it has an unknown
offset. The compiler assumes it is 16-byte aligned, and in this case, when A is
passed, pointer integrity of D is maintained, but a compiler warning message is
issued on the CALL.
Ÿ .4/ This item contains a pointer, and a pointer move is accomplished by .5/.
However, because the item is defined in the Linkage Section and the offset is
unknown, pointer integrity is not maintained. The compiler attempts to move
C2 to a 16-byte aligned area, and a compiler warning message is issued.
Ÿ .6/ Because E contains a pointer, a pointer move is accomplished. The offset
can be calculated because the reference modification start position is a numeric
literal. In this case, pointer integrity is maintained, and the item is placed at an
offset of 4 from the 16-byte boundary.
Ÿ .7/ Because E contains a pointer, a pointer move is attempted. Because E is
reference-modified with an unknown starting position (K), the compiler cannot
calculate the offset, and assumes it is aligned on a 16-byte boundary. A com-
piler warning message is issued. If the value of K causes E to be aligned on a
16-byte boundary, pointer integrity is maintained. For this to occur, K must be
1 or 17.
Ÿ .8/ F is an item defined in the Working-Storage Section, and contains no
pointers, so no pointer moves are expected.

290 COBOL/400 User’s Guide


Using Pointers and APIs to Access User Spaces
The following example shows how you can use pointers to access user spaces and
to chain records together.

POINTA is a program that reads customer names and addresses into a user space,
and then displays the information in a list. The program assumes that the customer
information exists in a file called POINTACU.

The customer address field is a variable-length field, to allow for lengthy addresses.

A\ THIS IS THE CUSTOMER INFORMATION FILE - POINTACUST


A
A
A R FSCUST TEXT('CUSTOMER MASTER RECORD')
A FS_CUST_NO 8Sðð TEXT('CUSTOMER NUMBER')
A ALIAS(FS_CUST_NUMBER)
A FS_CUST_NM 2ð TEXT('CUSTOMER NAME')
A ALIAS(FS_CUST_NAME)
A FS_CUST_AD 1ðð TEXT('CUSTOMER ADDRESS')
A ALIAS(FS_CUST_ADDRESS)
A VARLEN

Figure 99. Example Using Pointers to Access User Spaces -- DDS

Chapter 12. Communicating Between Programs 291


5763CB1 V3RðM5 ðð1ððð IBM SAA COBOL/4ðð TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 1
Program . . . . . . . . . . . . . . : POINTA
Library . . . . . . . . . . . . . : TESTER
Source file . . . . . . . . . . . . : QLBLSRC
Library . . . . . . . . . . . . . : TESTER
Source member . . . . . . . . . . . : POINTA ð5/ð1/94 17:55:27
Generation severity level . . . . . : 29
Text 'description' . . . . . . . . . : \BLANK
Source listing options . . . . . . . : \NONE
Generation options . . . . . . . . . : \NONE
Conversion options . . . . . . . . . : \NONE
Message limit:
Number of messages . . . . . . . . : \NOMAX
Message limit severity . . . . . . : 29
Print file . . . . . . . . . . . . . : QSYSPRT
Library . . . . . . . . . . . . . : \LIBL
FIPS flagging . . . . . . . . . . . : \NOFIPS \NOSEG \NODEB \NOOBSOLETE
SAA flagging . . . . . . . . . . . . : \NOFLAG
Extended display options . . . . . . :
Flagging severity . . . . . . . . . : ð
Replace program . . . . . . . . . . : \YES
Target release . . . . . . . . . . . : \CURRENT
User profile . . . . . . . . . . . . : \USER
Authority . . . . . . . . . . . . . : \LIBCRTAUT
Compiler . . . . . . . . . . . . . . : IBM SAA COBOL/4ðð
Customer Information Display .1/
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 2
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð PROCESS extaccdsp varchar .2/
2 ðððð2ð ID DIVISION. CBTððð1ð

ðððð4ð\ This program reads in a file of variable length records


ðððð5ð\ into a user space. It then shows the records on
ðððð6ð\ the display.
3 ðððð7ð PROGRAM-ID. pointa.
4 ðððð8ð ENVIRONMENT DIVISION.
5 ðððð9ð CONFIGURATION SECTION.
6 ððð1ðð SPECIAL-NAMES. CONSOLE IS CRT,
7 ððð11ð CRT STATUS IS ws-crt-status. .3/
8 ððð12ð INPUT-OUTPUT SECTION.
9 ððð13ð FILE-CONTROL.
1ð ððð14ð SELECT cust-file ASSIGN TO DATABASE-pointacu
11 ððð15ð ORGANIZATION IS SEQUENTIAL
12 ððð16ð FILE STATUS IS ws-file-status.
13 ððð17ð DATA DIVISION.
14 ððð18ð FILE SECTION.
15 ððð19ð FD cust-file.
16 ððð2ðð ð1 fs-cust-record.
ððð21ð\ copy in field names turning underscores to dashes
ððð22ð\ and using alias names
17 ððð23ð COPY DDR-ALL-FORMATS-I OF pointacu.
18 +ððððð1 ð5 POINTACU-RECORD PIC X(13ð). <-ALL-FMTS
+ððððð2\ I-O FORMAT:FSCUST FROM FILE POINTACU OF LIBRARY TESTER <-ALL-FMTS
+ððððð3\ CUSTOMER MASTER RECORD <-ALL-FMTS
19 +ððððð4 ð5 FSCUST REDEFINES POINTACU-RECORD. <-ALL-FMTS
2ð +ððððð5 ð6 FS-CUST-NUMBER PIC S9(8). <-ALL-FMTS
+ððððð6\ CUSTOMER NUMBER <-ALL-FMTS
21 +ððððð7 ð6 FS-CUST-NAME PIC X(2ð). <-ALL-FMTS
+ððððð8\ CUSTOMER NAME <-ALL-FMTS
22 +ððððð9 ð6 FS-CUST-ADDRESS. .4/ <-ALL-FMTS
+ðððð1ð\ (Variable length field) <-ALL-FMTS
23 +ðððð11 49 FS-CUST-ADDRESS-LENGTH <-ALL-FMTS
24 +ðððð12 PIC S9(4) COMP-4. <-ALL-FMTS
25 +ðððð13 49 FS-CUST-ADDRESS-DATA <-ALL-FMTS
26 +ðððð14 PIC X(1ðð). <-ALL-FMTS
+ðððð15\ CUSTOMER ADDRESS <-ALL-FMTS
27 ððð24ð WORKING-STORAGE SECTION.
28 ððð25ð ð1 ws-file-status.
29 ððð26ð ð5 ws-file-status-1 PIC X.
3ð ððð27ð 88 ws-file-stat-good VALUE "ð".
31 ððð28ð 88 ws-file-stat-at-end VALUE "1".
32 ððð29ð ð5 ws-file-status-2 PIC X.
33 ððð3ðð ð1 ws-crt-status. .5/
34 ððð31ð ð5 ws-status-1 PIC 9(2).
35 ððð32ð 88 ws-status-1-ok VALUE ð.
36 ððð33ð 88 ws-status-1-func-key VALUE 1.

Figure 100 (Part 1 of 7). Example Using Pointers to Access User Spaces

292 COBOL/400 User’s Guide


Customer Information Display
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 3
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
37 ððð34ð 88 ws-status-1-error VALUE 9.
38 ððð35ð ð5 ws-status-2 PIC 9(2).
39 ððð36ð 88 ws-func-ð3 VALUE 3.
4ð ððð37ð 88 ws-func-ð7 VALUE 7.
41 ððð38ð 88 ws-func-ð8 VALUE 8.
42 ððð39ð ð5 ws-status-3 PIC 9(2).
43 ððð4ðð ð1 ws-params. .6/
44 ððð41ð ð5 ws-space.
45 ððð42ð 1ð ws-space-name PIC X(1ð) VALUE "MYSPACE".
46 ððð43ð 1ð ws-space-lib PIC X(1ð) VALUE "QTEMP".
47 ððð44ð ð5 ws-attr PIC X(1ð) VALUE "PF".
48 ððð45ð ð5 ws-init-size PIC S9(5) VALUE 32ððð BINARY.
49 ððð46ð ð5 ws-init-char PIC X VALUE SPACE.
5ð ððð47ð ð5 ws-auth PIC X(1ð) VALUE "\ALL".
51 ððð48ð ð5 ws-text PIC X(5ð) VALUE
52 ððð49ð "Customer Information Records".
53 ððð5ðð ð5 ws-replace PIC X(1ð) VALUE "\YES".
54 ððð51ð ð5 ws-err-data. .7/
55 ððð52ð 1ð ws-input-l PIC S9(6) BINARY VALUE ZERO.
56 ððð53ð 1ð ws-output-l PIC S9(6) BINARY VALUE ZERO.
57 ððð54ð 1ð ws-exception-id PIC X(7).
58 ððð55ð 1ð ws-reserved PIC X(1).
59 ððð56ð 1ð ws-exception-data PIC X(87).
6ð ððð57ð ð5 ws-space-ptr POINTER. .8/
61 ððð58ð ð5 ws-map-ptr POINTER.
ððð59ð
62 ððð6ðð 77 ws-accept-data PIC X.
63 ððð61ð 88 ws-acc-create-space VALUE "Y", "y".
64 ððð62ð 88 ws-acc-delete-space VALUE "Y", "y".
65 ððð63ð 88 ws-acc-no-space VALUE "N", "n".
ððð64ð
66 ððð65ð 77 ws-prog-indicator PIC X VALUE "G".
67 ððð66ð 88 ws-prog-continue VALUE "G".
68 ððð67ð 88 ws-prog-end VALUE "C".
69 ððð68ð 88 ws-prog-loop VALUE "L".
ððð69ð
7ð ððð7ðð 77 ws-line PIC S99.
ððð71ð\ error message line
71 ððð72ð 77 ws-error-msg PIC X(5ð) VALUE SPACES.
ððð73ð\ more address information indicator
72 ððð74ð 77 ws-plus PIC X.
ððð75ð\ length of address information to display
73 ððð76ð 77 ws-temp-size PIC 9(2).
ððð77ð
74 ððð78ð 77 ws-current-rec PIC S9(4) VALUE 1.
75 ððð79ð 77 ws-old-rec PIC S9(4) VALUE 1.
76 ððð8ðð 77 ws-old-space-ptr POINTER.
ððð81ð\ max number of lines to display
77 ððð82ð 77 ws-displayed-lines PIC S99 VALUE 2ð.
ððð83ð\ line on which to start displaying records
78 ððð84ð 77 ws-start-line PIC S99 VALUE 5.
ððð85ð\ variables to create new record in space
79 ððð86ð 77 ws-addr-inc PIC S9(4) PACKED-DECIMAL.
8ð ððð87ð 77 ws-temp PIC S9(4) PACKED-DECIMAL.
81 ððð88ð 77 ws-temp-2 PIC S9(4) PACKED-DECIMAL.
ððð89ð\ pointer to previous record
82 ððð9ðð 77 ws-cust-prev-ptr POINTER VALUE NULL.
83 ððð91ð LINKAGE SECTION.
84 ððð92ð ð1 ls-header-record. .9/
85 ððð93ð ð5 ls-hdr-cust-ptr USAGE POINTER.
ððð94ð\ number of records read in from file
86 ððð95ð ð5 ls-record-counter PIC S9(3) BINARY.
87 ððð96ð ð5 FILLER PIC X(14). .1ð/
88 ððð97ð ð1 ls-user-space. .11/
89 ððð98ð ð5 ls-customer-rec.
ððð99ð\ pointer to previous customer record
9ð ðð1ððð 1ð ls-cust-prev-ptr USAGE POINTER.
91 ðð1ð1ð 1ð ls-cust-rec-length PIC S9(4) BINARY.
92 ðð1ð2ð 1ð ls-cust-name PIC X(2ð).
93 ðð1ð3ð 1ð ls-cust-number PIC S9(8).

Figure 100 (Part 2 of 7). Example Using Pointers to Access User Spaces

Chapter 12. Communicating Between Programs 293


Customer Information Display
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 4
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð1ð4ð\ total length of this record including filler bytes
ðð1ð5ð\ to make sure next record on 16 byte boundary
94 ðð1ð6ð 1ð ls-cust-address-length PIC S9(4) BINARY.
95 ðð1ð7ð ð5 ls-cust-address-data PIC X(116).
ðð1ð8ð
ðð1ð9ð\ Size of ls-user-space is 16 more than actually needed. This
ðð11ðð\ allows the start address of the next record
ðð111ð\ record to be established without exceeding the declared size
ðð112ð\ The size is 16 bigger to allow for pointer alignment
ðð113ð
96 ðð114ð PROCEDURE DIVISION.
ðð115ð\ note no need for "USING" entry on PROC... DIV.
ðð116ð DECLARATIVES.
ðð117ð cust-file-para SECTION.
ðð118ð USE AFTER ERROR PROCEDURE ON cust-file.
ðð119ð cust-file-para-2.
97 ðð12ðð MOVE "Error XX on file pointacu" TO ws-error-msg.
98 ðð121ð MOVE ws-file-status TO ws-error-msg(7:2).
ðð122ð END DECLARATIVES.
ðð123ð main-section section.
ðð124ð main-proc.
ðð125ð\ keep reading initial display until entered data correct
99 ðð126ð SET ws-prog-loop to TRUE.
1ðð ðð127ð PERFORM initial-display THRU read-initial-display
ðð128ð UNTIL NOT ws-prog-loop.
ðð129ð\ if want to continue with program and want to create
ðð13ðð\ customer information area, fill the space with
ðð131ð\ records from the customer file
1ð1 ðð132ð IF ws-prog-continue and
ðð133ð ws-acc-create-space THEN
1ð2 ðð134ð PERFORM read-customer-file
1ð3 ðð135ð MOVE 1 TO ws-current-rec
ðð136ð\ set ptr to header record
1ð4 ðð137ð SET ADDRESS OF ls-header-record TO ws-space-ptr
ðð138ð\ set to first customer record in space
1ð5 ðð139ð SET ADDRESS OF ls-user-space TO ls-hdr-cust-ptr
ðð14ðð END-IF.
1ð6 ðð141ð IF ws-prog-continue THEN
1ð7 ðð142ð PERFORM main-loop UNTIL ws-prog-end
ðð143ð END-IF.
ðð144ð end-program.
1ð8 ðð145ð PERFORM clean-up.
1ð9 ðð146ð STOP RUN.
ðð147ð initial-display. .12/
11ð ðð148ð DISPLAY "Create Customer Information Area" AT ð118 WITH
ðð149ð BLANK SCREEN REVERSE-VIDEO
ðð15ðð "Create customer information area (Y/N)=> <="
ðð151ð AT 1ð15
ðð152ð "F3=Exit" AT 22ð2.
111 ðð153ð IF ws-error-msg NOT = SPACES THEN
112 ðð154ð DISPLAY ws-error-msg at 23ð2 with beep highlight
113 ðð155ð MOVE SPACES TO ws-error-msg
ðð156ð END-IF.
ðð157ð read-initial-display. .13/
114 ðð158ð ACCEPT ws-accept-data AT 1ð56 WITH REVERSE-VIDEO
ðð159ð ON EXCEPTION
115 ðð16ðð IF ws-status-1-func-key THEN
116 ðð161ð IF ws-func-ð3 THEN
117 ðð162ð SET ws-prog-end TO TRUE
ðð163ð ELSE
118 ðð164ð MOVE "Invalid Function Key" TO ws-error-msg
ðð165ð END-IF
ðð166ð ELSE
119 ðð167ð MOVE "Unknown Error" TO ws-error-msg
ðð168ð END-IF
ðð169ð NOT ON EXCEPTION

Figure 100 (Part 3 of 7). Example Using Pointers to Access User Spaces

294 COBOL/400 User’s Guide


Customer Information Display
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 5
12ð ðð17ðð IF ws-acc-create-space THEN
121 ðð171ð PERFORM create-space THRU get-space
122 ðð172ð SET ws-prog-continue TO TRUE
ðð173ð ELSE
123 ðð174ð IF NOT ws-acc-no-space THEN
124 ðð175ð MOVE "Invalid Character Entered" TO ws-error-msg
ðð176ð ELSE
125 ðð177ð SET ws-prog-continue TO TRUE
126 ðð178ð PERFORM get-space
ðð179ð END-IF
ðð18ðð END-IF
ðð181ð END-ACCEPT.
ðð182ð create-space.
127 ðð183ð CALL "QUSCRTUS" .14/
ðð184ð USING ws-space, ws-attr, ws-init-size,
ðð185ð ws-init-char, ws-auth, ws-text,
ðð186ð ws-replace, ws-err-data.
ðð187ð\ check for errors in creating space
ðð188ð get-space.
128 ðð189ð CALL "QUSPTRUS" USING ws-space, ws-space-ptr. .15/
ðð19ðð\ set header record to beginning of space
129 ðð191ð SET ADDRESS OF ls-header-record .16/
ðð192ð ADDRESS OF ls-user-space .17/
ðð193ð TO ws-space-ptr.
ðð194ð\ set first customer record after header record
13ð ðð195ð SET ADDRESS OF ls-user-space TO .18/
ðð196ð ADDRESS OF ls-user-space(LENGTH OF ls-header-record .19/
ðð197ð + 1:1).
ðð198ð\ save ptr to first record in header record
131 ðð199ð SET ls-hdr-cust-ptr TO ADDRESS OF ls-user-space.
ðð2ððð delete-space.
132 ðð2ð1ð CALL "QUSDLTUS" USING ws-space, ws-err-data. .2ð/
ðð2ð2ð read-customer-file.
ðð2ð3ð\ read all records from customer file and move into space
133 ðð2ð4ð OPEN INPUT cust-file.
134 ðð2ð5ð IF ws-file-stat-good THEN
135 ðð2ð6ð READ cust-file AT END CONTINUE
136 ðð2ð7ð END-READ
137 ðð2ð8ð PERFORM VARYING ls-record-counter FROM 1 BY 1
ðð2ð9ð UNTIL not ws-file-stat-good
138 ðð21ðð SET ls-cust-prev-ptr TO ws-cust-prev-ptr
ðð211ð\ Move information from file into space
139 ðð212ð MOVE fs-cust-name TO ls-cust-name
14ð ðð213ð MOVE fs-cust-number TO ls-cust-number
141 ðð214ð MOVE fs-cust-address-length TO ls-cust-address-length
142 ðð215ð MOVE fs-cust-address-data(1:fs-cust-address-length)
ðð216ð TO ls-cust-address-data(1:ls-cust-address-length)
ðð217ð\ Save ptr to current record
143 ðð218ð SET ws-cust-prev-ptr TO ADDRESS OF ls-user-space
ðð219ð\ Make sure next record on 16 byte boundary
144 ðð22ðð ADD LENGTH OF ls-customer-rec .21/
ðð221ð ls-cust-address-length TO 1 GIVING ws-addr-inc
145 ðð222ð DIVIDE ws-addr-inc BY 16 GIVING ws-temp
ðð223ð REMAINDER ws-temp-2
146 ðð224ð SUBTRACT ws-temp-2 FROM 16 GIVING ws-temp
ðð225ð\ Save total record length in user space
147 ðð226ð ADD ws-addr-inc TO ws-temp GIVING ls-cust-rec-length
148 ðð227ð SET ADDRESS OF ls-user-space
ðð228ð TO ADDRESS OF ls-user-space(ls-cust-rec-length + 1:1)
ðð229ð\ Get next record from file
149 ðð23ðð READ cust-file AT END CONTINUE
15ð ðð231ð END-READ
ðð232ð END-PERFORM
ðð233ð\ At the end of the loop have one more record than really
ðð234ð\ have
151 ðð235ð SUBTRACT 1 FROM ls-record-counter
ðð236ð END-IF.
152 ðð237ð CLOSE cust-file.
ðð238ð
ðð239ð main-loop. .22/
ðð24ðð\ write the records to the display until F3 entered

Figure 100 (Part 4 of 7). Example Using Pointers to Access User Spaces

Chapter 12. Communicating Between Programs 295


Customer Information Display
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 6
153 ðð241ð DISPLAY "Customer Information" AT ð124 WITH
ðð242ð BLANK SCREEN REVERSE-VIDEO
ðð243ð "Cust Customer Name Customer"
ðð244ð AT ð3ð5
ðð245ð " Address"
ðð246ð "Number" AT ð4ð5
ðð247ð "F3=Exit" AT 22ð2.
ðð248ð\ if a pending error put on the display
154 ðð249ð IF ws-error-msg NOT = SPACES THEN
155 ðð25ðð DISPLAY ws-error-msg at 23ð2 with beep highlight
156 ðð251ð MOVE SPACES TO ws-error-msg
ðð252ð END-IF.
ðð253ð\ if in the middle of the list put F7 on the display
157 ðð254ð IF ws-current-rec > 1 THEN .23/
158 ðð255ð DISPLAY "F7=Back" AT 224ð
ðð256ð END-IF.
ðð257ð\ save the current record
159 ðð258ð MOVE ws-current-rec TO ws-old-rec.
16ð ðð259ð SET ws-old-space-ptr TO ADDRESS OF ls-user-space. .24/
ðð26ðð\ move each record to the display
161 ðð261ð PERFORM VARYING ws-line FROM ws-start-line BY 1
ðð262ð UNTIL ws-line > ws-displayed-lines or
ðð263ð ws-current-rec > ls-record-counter
ðð264ð\ if address is greater than display width show "+"
162 ðð265ð IF ls-cust-address-length > 4ð THEN
163 ðð266ð MOVE "+" TO ws-plus
164 ðð267ð MOVE 4ð TO ws-temp-size
ðð268ð ELSE
165 ðð269ð MOVE ls-cust-address-length TO ws-temp-size
166 ðð27ðð MOVE SPACE TO ws-plus
ðð271ð END-IF
167 ðð272ð DISPLAY ls-cust-number at line ws-line column 5
ðð273ð ls-cust-name ls-cust-address-data with
ðð274ð size ws-temp-size ws-plus at line
ðð275ð ws-line column 78
ðð276ð\ get next record in the space
168 ðð277ð ADD 1 TO ws-current-rec
169 ðð278ð SET ADDRESS OF ls-user-space
ðð279ð TO ADDRESS OF ls-user-space
ðð28ðð (ls-cust-rec-length + 1:1)
ðð281ð END-PERFORM.
ðð282ð\ if can go forward put F8 on the display
17ð ðð283ð IF ws-current-rec < ls-record-counter THEN .23/
171 ðð284ð DISPLAY "F8=Forward" AT 225ð
ðð285ð END-IF.
ðð286ð\ check to see if continue, exit, or get next records or
ðð287ð\ previous records
172 ðð288ð ACCEPT ws-accept-data WITH SECURE .25/
ðð289ð ON EXCEPTION
173 ðð29ðð IF ws-status-1-func-key THEN
174 ðð291ð IF ws-func-ð3 THEN
175 ðð292ð SET ws-prog-end TO TRUE
ðð293ð ELSE
176 ðð294ð IF ws-func-ð7 THEN
177 ðð295ð PERFORM back-screen
ðð296ð ELSE
178 ðð297ð IF ws-func-ð8 THEN
179 ðð298ð PERFORM forward-screen
ðð299ð ELSE
18ð ðð3ððð MOVE "Invalid Function Key" TO ws-error-msg
181 ðð3ð1ð MOVE ws-old-rec TO ws-current-rec
182 ðð3ð2ð SET ADDRESS OF ls-user-space TO ws-old-space-ptr
ðð3ð3ð END-IF
ðð3ð4ð END-IF
ðð3ð5ð ELSE
183 ðð3ð6ð MOVE "Unknown Error" TO ws-error-msg
184 ðð3ð7ð MOVE ws-old-rec TO ws-current-rec
185 ðð3ð8ð SET ADDRESS OF ls-user-space TO ws-old-space-ptr
ðð3ð9ð END-IF
ðð31ðð NOT ON EXCEPTION
186 ðð311ð MOVE ws-old-rec TO ws-current-rec
187 ðð312ð SET ADDRESS OF ls-user-space TO ws-old-space-ptr
ðð313ð END-ACCEPT.
ðð314ð clean-up.
ðð315ð\ do clean up for program

Figure 100 (Part 5 of 7). Example Using Pointers to Access User Spaces

296 COBOL/400 User’s Guide


Customer Information Display
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Source TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 7
ðð316ð\ keep reading end display until entered data correct
188 ðð317ð SET ws-prog-loop to TRUE.
189 ðð318ð PERFORM end-display THRU read-end-display .26/
ðð319ð UNTIL NOT ws-prog-loop.
ðð32ðð end-display.
19ð ðð321ð DISPLAY "Delete Customer Information Area" AT ð118 WITH .27/
ðð322ð BLANK SCREEN REVERSE-VIDEO
ðð323ð "Delete customer information area (Y/N)=> <="
ðð324ð AT 1ð15
ðð325ð "F3=Exit" AT 22ð2.
191 ðð326ð IF ws-error-msg NOT = SPACES THEN
192 ðð327ð DISPLAY ws-error-msg at 23ð2 with beep highlight
193 ðð328ð MOVE SPACES TO ws-error-msg
ðð329ð END-IF.
ðð33ðð read-end-display.
194 ðð331ð ACCEPT ws-accept-data AT 1ð56 WITH REVERSE-VIDEO
ðð332ð ON EXCEPTION
195 ðð333ð IF ws-status-1-func-key THEN
196 ðð334ð IF ws-func-ð3 THEN
197 ðð335ð SET ws-prog-end TO TRUE
ðð336ð ELSE
198 ðð337ð MOVE "Invalid Function Key" TO ws-error-msg
ðð338ð END-IF
ðð339ð ELSE
199 ðð34ðð MOVE "Unknown Error" TO ws-error-msg
ðð341ð END-IF
ðð342ð NOT ON EXCEPTION
2ðð ðð343ð IF ws-acc-delete-space THEN
2ð1 ðð344ð PERFORM delete-space
2ð2 ðð345ð SET ws-prog-continue TO TRUE
ðð346ð ELSE
2ð3 ðð347ð IF NOT ws-acc-no-space THEN
2ð4 ðð348ð MOVE "Invalid Character Entered" TO ws-error-msg
ðð349ð ELSE
2ð5 ðð35ðð SET ws-prog-continue TO TRUE
ðð351ð END-IF
ðð352ð END-IF
ðð353ð END-ACCEPT.
ðð354ð back-screen. .28/
2ð6 ðð355ð IF ws-old-rec <= 1 THEN
2ð7 ðð356ð MOVE "Top of customer records" TO ws-error-msg
2ð8 ðð357ð MOVE ws-old-rec TO ws-current-rec .29/
2ð9 ðð358ð SET ADDRESS OF ls-user-space TO ws-old-space-ptr
ðð359ð ELSE
21ð ðð36ðð MOVE ws-old-rec TO ws-current-rec .29/
211 ðð361ð SET ADDRESS OF ls-user-space TO ws-old-space-ptr
212 ðð362ð PERFORM VARYING ws-line FROM ws-start-line BY 1
ðð363ð UNTIL ws-line > ws-displayed-lines or
ðð364ð ws-current-rec <= 1
ðð365ð\ Back up one record at a time
213 ðð366ð SET ws-cust-prev-ptr TO ls-cust-prev-ptr
214 ðð367ð SET ADDRESS OF ls-user-space TO ws-cust-prev-ptr .3ð/
215 ðð368ð SUBTRACT 1 FROM ws-current-rec
ðð369ð END-PERFORM
ðð37ðð END-IF.
ðð371ð forward-screen. .31/
ðð372ð\ if current record greater or equal to the max records
ðð373ð\ print error, have reached max records
216 ðð374ð IF ws-current-rec >= ls-record-counter
217 ðð375ð MOVE "No more customer records" TO ws-error-msg
218 ðð376ð MOVE ws-old-rec TO ws-current-rec
219 ðð377ð SET ADDRESS OF ls-user-space TO ws-old-space-ptr
ðð378ð ELSE
22ð ðð379ð MOVE ws-current-rec TO ws-old-rec
221 ðð38ðð SET ws-old-space-ptr TO ADDRESS OF ls-user-space
ðð381ð END-IF.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
Customer Information Display
5763CB1 V3RðM5 ðð1ððð AS/4ðð COBOL Messages TESTER/POINTA AS4ððSYS ð5/ð1/94 18:ð1:14 Page 8
STMT
\ 15 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð19ð
Message . . . . : Blocking/Deblocking for file 'CUST-FILE'
will be performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \

Figure 100 (Part 6 of 7). Example Using Pointers to Access User Spaces

Chapter 12. Communicating Between Programs 297


Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 1 ð ð ð ð
Source records read . . . . . . . . : 381
Copy records read . . . . . . . . . : 15
Copy members processed . . . . . . : 1
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program POINTA created in library TESTER.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 100 (Part 7 of 7). Example Using Pointers to Access User Spaces

.1/ The compiler directive TITLE is used to create this title that appears at
the beginning of each page.
.3/ CRT STATUS IS specifies a data name into which a status value is
placed after the termination of an extended ACCEPT statement. In this
example, the STATUS key value is used to determine which function
key was pressed.
.4/ fs-cust-address is a variable-length field. To see meaningful names
here rather than FILLER, specify *VARCHAR for the CVTOPT param-
eter of the CRTCBLPGM command, or VARCHAR in the PROCESS
statement, as shown in .2/. For more information about variable-length
fields, refer to “Declaring Data Items Using CVTOPT Data Types” on
page 130.
.5/ CRT STATUS as mentioned in .3/ is defined here.
.6/ The ws-params structure contains the parameters used when calling the
APIs to access user spaces.
.7/ ws-err-data is the structure for the error parameter for the user space
APIs. Note that the ws-input-l is zero, meaning that any exceptions are
signalled to the program, and not passed in the error code parameter.
For more information on error code parameters, refer to the System
Programmer’s Interface Reference.
.8/ ws-space-ptr defines a pointer data item set by the API QUSPTRUS.
This points to the beginning of the user space, and is used to set the
addresses of items in the Linkage Section.
.9/ The first data structure (ls-header-record) to be defined in the user
space.
.1ð/ FILLER is used to maintain pointer alignment, because it makes Is-
header-record a multiple of 16 bytes long.
.11/ The second data structure (ls-user-space) to be defined in the user
space.
.12/ initial-display shows the Create Customer Information Area display. This
display is shown in Figure 101 on page 300.
.13/ read-initial-display reads the first display, and determines if the user
chooses to continue or end the program. If the user continues the
program by pressing Enter, then the program checks ws-accept-data to
see if the customer information area is to be created.
.14/ QUSCRTUS is an API used to create user spaces.

298 COBOL/400 User’s Guide


.15/ QUSPTRUS is an API used to return a pointer to the beginning of a
user space.
.16/ Maps the first data structure (ls-header-record) over the beginning of the
user space.
.17/ Maps the second data structure (ls-user-space) over the beginning of
the user space.
.18/ Uses ADDRESS OF special register
.19/ Uses ADDRESS OF, not the ADDRESS OF special register, because it
is reference modified.
.2ð/ QUSDLTUS is an API used to delete a user space.
.21/ The following four arithmetic statements calculate the total length of
each record, and ensure that each record is a multiple of 16 bytes in
length.
.22/ main-loop puts up the Customer Information display. Refer to
Figure 102 on page 300.
.23/ These statements determine if the program should display function keys
F7 and F8.
.24/ Saves a pointer to the first customer record on the display.
.25/ This ACCEPT statement waits for input from the Customer Information
display. Based on the function key pressed, it calls the appropriate par-
agraph to display the next set of records (forward-screen), or the pre-
vious set of records (back-screen), or sets an indicator to end the
routine if F3 is pressed.
.26/ The clean up routine displays the Delete Customer Information Area
display until an appropriate key is pressed.
.27/ This statement puts up the Delete Customer Information Area display.
.28/ Each record contains a pointer to the previous customer record. The
ADDRESS OF special register points to the current customer record.
By changing the ADDRESS OF special register, the current customer
record is changed.
back-screen moves the current record pointer backward one record at a
time .3ð/, by moving the pointer to the previous customer record into
the pointer to the current customer record (ADDRESS OF). Before
moving backward one record at a time, the program sets the current
customer record to the first record currently displayed .29/.
.31/ forward-screen sets ws-old-space-ptr (which points to the first record in
the display) to point to the current record (which is after the last record
displayed.)
A user space always begins on a 16-byte boundary, so the method illus-
trated here ensures that all records are aligned. ls-cust-rec-length is
also used to chain the records together.

Chapter 12. Communicating Between Programs 299


When you run POINTA, you see the following displays:

à@ Create Customer Information Area


ð

Create customer information area (Y/N)=> y <=

F3=Exit

á ñ
Figure 101. Create Customer Information Area Display

If you specify Y to create the user space, the program reads the customer records
from the file and puts the information in the user space. The records are chained
together.

When you press enter from the previous display, the Customer Information display
appears:

à@ Customer Information
ð
Cust Customer Name Customer Address
Number
ððððððð1 Bakery Unlimited 3ð Bake Way, North York
ððððððð2 Window World 15ð Eglinton Ave E., North York, Ontario
ððððððð3 Jons Clothes 1ð1 Park St, North Bay, Ontario, Canada
ððððððð4 Pizza World 254 Main Street, Toronto, Ontario +
ððððððð5 Marv's Auto Body 9 George St, Peterborough, Ontario, Cana +
ððððððð6 Jack's Snacks 23 North St, Timmins, Ontario, Canada
ððððððð7 Video World 14 Robson St, Vancouver, B.C, Canada
ððððððð8 Pat's Daycare 8 Kingston Rd, Pickering, Ontario, Canad +
ððððððð9 Mary's Pies 3 Front St, Toronto, Ontario, Canada
ðððððð1ð Carol's Fashions 19 Spark St, Ottawa, Ontario, Canada
ðððððð11 Grey Optical 5 Lundy's Lane, Niagara Falls, Ont. Cana +
ðððððð12 Fred's Forage 33 Dufferin St, Toronto, Ontario, Canada +
ðððððð13 Dave's Trucking 15 Water St, Guelph, Ontario, Canada
ðððððð14 Doug's Music 1ð1 Queen St. Toronto, Ontario, Canada +
ðððððð15 Anytime Copiers 3ðð Warden Ave, Scarborough, Ontario, Ca +
ðððððð16 Rosa's Ribs 44ð Avenue Rd, Toronto, Ontario, Canada

F3=Exit F8=Forward

á ñ
Figure 102. Customer Information Area Display

If there are more than 16 records in the user space (based on the starting line in
ws-start-line), the program enables the F8=Forward key, to allow the user to page

300 COBOL/400 User’s Guide


forward in the list. Once the user has rolled forward, the F7=Backward key is
enabled to allow the user to page backward in the list, as shown in the following
display:

à@ Customer Information
ð
Cust Customer Name Customer Address
Number
ðððððð17 Picture It 33 Kingston Rd, Ajax, Ontario, Canada
ðððððð18 Paula's Flowers 144 Pape Ave, Toronto, Ontario, Canada
ðððððð19 Mom's Diapers 1ð1 Ford St, Toronto, Ontario, Canada
ðððððð2ð Chez Francois 12ð2 Rue Ste Anne, Montreal, PQ, Canada
ðððððð21 Vetements de Louise 892 Rue Sherbrooke, Montreal E, PQ, Cana +
ðððððð22 Good Eats 355 Lake St, Port Hope, Ontario, Canada

F3=Exit F7=Back

á ñ
Figure 103. Customer Information Display (Second Display)

When the user exits from the above display, the option to delete the user space is
presented, as shown in the following display:

à@ Delete Customer Information Area


ð

Delete customer information area (Y/N)=> n <=

F3=Exit

á ñ
Figure 104. Delete Customer Information Display

Chapter 12. Communicating Between Programs 301


Processing a Chained List
A typical application for using pointer data items is in processing a chained list (a
series of records where each one points to the next).

For this example, picture a chained list of data that is composed of individual salary
records. Figure 105 shows one way to visualize how these records are linked in
storage:

┌─────────┐ ┌───────────┐
│ │ │ │
SALARY RECORD 6 │ 6 │ 6
┌───────────┴─┐ ┌──────────┴─┐ ┌─────────────┐
PTR─NEXT─REC │addr of next │ │ │ │NULL─invalid │
│rec │ │ │ │addr │
NAME ├─────────────┤ ├────────────┤ . . . ├─────────────┤
│ │ │ │ │ │
SALARY ├─────────────┤ ├────────────┤ ├─────────────┤
│ │ │ │ │ │
└─────────────┘ └────────────┘ └─────────────┘

Figure 105. Representation of a Chained List Ending with NULL

The first item in each record (except for the last record) points to the next record.
The first item in the last record, in order to indicate that it is the last record, con-
tains a null value instead of an address.

The high-level logic of an application that processes these records might look
something like this:
OBTAIN ADDRESS OF FIRST RECORD IN CHAINED LIST FROM ROUTINE
CHECK FOR END OF THE CHAINED LIST
DO UNTIL END OF THE CHAINED LIST
PROCESS RECORD
GO ON TO THE NEXT RECORD
END

Figure 106 on page 303 contains an outline of the processing program, LISTS,
used in this example of processing a chained list.

302 COBOL/400 User’s Guide


IDENTIFICATION DIVISION.
PROGRAM-ID. LISTS.
ENVIRONMENT DIVISION.
DATA DIVISION.
\\\\\\
WORKING-STORAGE SECTION.
77 PTR-FIRST POINTER VALUE IS NULL.
77 DEPT-TOTAL PIC 9(4) VALUE IS ð.
\\\\\\
LINKAGE SECTION.
ð1 SALARY-REC.
ð2 PTR-NEXT-REC POINTER.
ð2 NAME PIC X(2ð).
ð2 DEPT PIC 9(4).
ð2 SALARY PIC 9(6).
ð1 DEPT-X PIC 9(4).
\\\\\\
PROCEDURE DIVISION USING DEPT-X.
\\\\\\
\ FOR EVERYONE IN THE DEPARTMENT RECEIVED AS DEPT-X,
\ GO THROUGH ALL OF THE RECORDS IN THE CHAINED LIST BASED ON THE
\ ADDRESS OBTAINED FROM THE PROGRAM CHAIN-ANCH
\ AND ACCUMULATE THE SALARIES.
\ IN EACH RECORD, PTR-NEXT-REC IS A POINTER TO THE NEXT RECORD
\ IN THE LIST; IN THE LAST RECORD, PTR-NEXT-REC IS NULL.
\ DISPLAY THE TOTAL.
\\\\\\
CALL "CHAIN-ANCH" USING PTR-FIRST
SET ADDRESS OF SALARY-REC TO PTR-FIRST
\\\\\\
PERFORM WITH TEST BEFORE UNTIL ADDRESS OF SALARY-REC = NULL
IF DEPT = DEPT-X
THEN ADD SALARY TO DEPT-TOTAL
ELSE CONTINUE
END-IF
SET ADDRESS OF SALARY-REC TO PTR-NEXT-REC
END-PERFORM
\\\\\\
DISPLAY DEPT-TOTAL
GOBACK.

Figure 106. Program for Processing a Chained List

Passing Addresses between Programs


To obtain the address of the first SALARY-REC record area, the LISTS program
calls the program CHAIN-ANCH:
CALL "CHAIN-ANCH" USING PTR-FIRST

PTR-FIRST is defined in WORKING-STORAGE in the calling program (LISTS) as a


pointer data item:
WORKING-STORAGE SECTION.
77 PTR-FIRST POINTER VALUE IS NULL.

Upon return from the call to CHAIN-ANCH, PTR-FIRST contains the address of the
first record in the chained list.

PTR-FIRST is initially defined as having a null value as a logic check. If an error


occurs with the call, and PTR-FIRST never receives the value of the address of the
first record in the chain, a null value remains in PTR-FIRST and, according to the
logic of the program, the records will not be processed.

Chapter 12. Communicating Between Programs 303


NULL is a figurative constant used to assign the value of a non-valid address to
pointer items. It can be used in the VALUE IS NULL clause, in the SET statement,
and as an operand in a relation condition with a pointer data item.

The Linkage Section of the calling program contains the description of the records
in the chained list. It also contains the description of the department code that is
passed through the USING phrase of the CALL statement.
LINKAGE SECTION.
ð1 SALARY-REC.
ð2 PTR-NEXT-REC POINTER.
ð2 NAME PIC X(2ð).
ð2 DEPT PIC 9(4).
ð2 SALARY PIC 9(6).
ð1 DEPT-X PIC 9(4).

To “base” the record description SALARY-REC on the address contained in


PTR-FIRST, use a SET statement:
CALL "CHAIN-ANCH" USING PTR-FIRST
SET ADDRESS OF SALARY-REC TO PTR-FIRST

Check for the End of the Chained List


The chained list in this example is set up so that the last record contains a non-
valid address. To do this, the pointer data item in the last record would be
assigned the value NULL.

A pointer data item can be assigned the value NULL in two ways:
Ÿ A pointer data item can be defined with a VALUE IS NULL clause in its data
definition.
Ÿ NULL can be the sending field in a SET statement.
Ÿ The initial value of a pointer data item with or without a VALUE clause of NULL
equals NULL.

In the case of a chained list in which the pointer in the last record contains a null
value, the code to check for the end of the list would be:
IF PTR-NEXT-REC = NULL
..
.

(logic for end of chain)

If you have not reached the end of the list, process the record and move on to the
next record.

In the program LISTS, this test for the end of the chained list is accomplished with
a “do while” structure:
PERFORM WITH TEST BEFORE UNTIL ADDRESS OF SALARY-REC = NULL
IF DEPT = DEPT-X
THEN ADD SALARY TO DEPT-TOTAL
ELSE CONTINUE
END-IF
SET ADDRESS OF SALARY-REC TO PTR-NEXT-REC
END-PERFORM

304 COBOL/400 User’s Guide


Continuing Processing the Next Record
To move on to the next record, set the address of the record in the Linkage Section
to be equal to the address of the next record. This is accomplished through the
pointer data item sent as the first field in SALARY-REC:
SET ADDRESS OF SALARY-REC TO PTR-NEXT-REC

Then repeat the record-processing routine, which will process the next record in the
chained list.

Incrementing Addresses Received from Another Program


The data passed from a calling program might contain header information that you
want to ignore (for example, in data received from a CICS application that is not
migrated to the command level).

Because pointer data items are not numeric, you cannot directly perform arithmetic
on them. You can, however, use the SET verb to increment the passed address in
order to bypass header information.

You could set up the Linkage Section as follows:


LINKAGE SECTION.
ð1 RECORD-A.
ð2 HEADER PIC X(16).
ð2 REAL-SALARY-REC PIC X(3ð).
..
.
ð1 SALARY-REC.
ð2 PTR-NEXT-REC POINTER.
ð2 NAME PIC X(2ð).
ð2 DEPT PIC 9(4).
ð2 SALARY PIC 9(6).

Within the Procedure Division, base the address of SALARY-REC on the address
of REAL-SALARY-REC:
SET ADDRESS OF SALARY-REC TO ADDRESS OF REAL-SALARY-REC

SALARY-REC is now based on the address of RECORD-A + 16.

Data Areas
A data area is an object used to communicate data such as variable values
between programs within a job and between jobs. A data area can be created and
declared to a program before it is used in that program or job. For information on
how to create and declare a data area, see the CL Programmer’s Guide.

Local Data Area


The local data area can be used to pass any desired information between pro-
grams in a job. This information may be free-form data, such as informal mes-
sages, or may consist of a fully structured or formatted set of fields.

The system automatically creates a local data area for each job. The local data
area is defined outside the COBOL program as an area of 1024 bytes.

Chapter 12. Communicating Between Programs 305


When a job is submitted, the submitting job’s local data area is copied into the sub-
mitted job’s local data area. If there is no submitting job, the local data area is
initialized to blanks.

A COBOL program can access the local data area for its job with the ACCEPT and
DISPLAY statements, using a mnemonic name associated with the function-name
LOCAL-DATA.

There is only one local data area associated with each job. Even if several work
stations are acquired by a single job, only one local data area exists for that job.
There is not a local data area for each work station.

Program Initialization Parameters (PIP) Data Area


The PIP data area is used by a prestart job. Generally, a prestart job is a job from
a remote system under ICF that you start and keep ready to run until you call it.

If you use a prestart job, you do not have to wait for a program that you call to go
through job initiation processing. Job initiation is performed before a program can
actually start. Because job initiation has already taken place, a prestart job allows
your program to start more quickly after the program start request is received.

A COBOL program can access the PIP data area for its job with the ACCEPT
statement, using a mnemonic name associated with the function-name PIP-DATA.

The PIP data area is a 2 000-byte alphanumeric item and contains parameters
received from a calling program. It provides the program initialization parameters
that, in non-prestart jobs, is provided through standard COBOL parameters.

You use a Format 5 ACCEPT statement to access the PIP data area, similar to the
way in which you use a Format 4 ACCEPT statement to read from the local data
area. Note that you cannot update the PIP data area using COBOL. See the
COBOL/400 Reference for detailed syntax information.

For more information regarding prestart jobs and the PIP data area, refer to the
Work Management Guide and the CL Programmer’s Guide.

File Considerations
You can pass a file name as a parameter in a COBOL program, but you cannot
use that file in the called program. If a file is defined in both a calling program and
a called program, it is treated as two separate files. The contents of the record
area and the current record pointer in each program are independent, unless
shared files are specified in CL commands. See the Data Management Guide for
further information on shared files.

The following statements affect file status differently:


Ÿ An EXIT PROGRAM statement does not change the status of any of the files in
a run unit.
Ÿ A STOP RUN statement closes all of the files in a run unit.

306 COBOL/400 User’s Guide


IBM Extension

Ÿ A GOBACK statement issued from a main program closes all of the files in a
run unit. A GOBACK statement issued from a subprogram does not change
the status of any of the files in a run unit.

End of IBM Extension

Ÿ A CANCEL statement does not change the status of any of the files in the
program that is canceled. It does free the storage that contains information
about the file. If the program has files that are open when the CANCEL state-
ment is processed, those files are closed when that program is cancelled. The
program can no longer use the file. If the canceled program is called again,
the program considers the file closed. If the program opens the file, a new
linkage to the file is established. This can cause additional system storage to
be used.

Chapter 12. Communicating Between Programs 307


308 COBOL/400 User’s Guide
Appendix A. Segmentation Feature
You do not have to be concerned with storage management when writing
COBOL/400 programs. Storage segmentation is, however, available for compat-
ibility with other systems.

The segmentation feature provides programmer-controlled storage optimization of


the Procedure Division by allowing that division to be subdivided both physically
and logically.

Segmentation Concepts
Although it is not required, the Procedure Division of a source program is often
written as a consecutive group of sections, each of which is made up of a series of
related operations that perform a particular function. Thus, the entire Procedure
Division is made up of a number of logical subdivisions. Segmentation allows the
programmer to physically divide the Procedure Division into segments, each of
which has specific physical and logical attributes.

When Segmentation is used, the entire Procedure Division must be divided into
sections. Each section must then be classified as to its physical and logical attri-
butes. Classification is specified by means of segment numbers. All sections given
the same segment number make up one program segment.

Segment numbers must be integers from 0 through 99.

Program Segments
There are three types of program segments; fixed permanent, fixed overlayable,
and independent.

Fixed Segments
Fixed-permanent segments and fixed-overlayable segments make up the fixed
portion, the part of the Procedure Division that is logically treated as if it were
always physically present in main storage. Fixed-portion segment numbers must
be integers from 0 through 49.

A fixed-permanent segment is always made available in its last-used state.

A fixed-overlayable segment is logically always in main storage during program


processing; therefore, it is always available in its last-used state. Any overlay of
such a segment is transparent to the user. Thus, a fixed-overlayable segment is
logically identical with a fixed-permanent segment.

Independent Segments
Logically, an independent segment can overlay and be overlaid by other segments
during a program’s run.

An independent segment is made available in its initial state the first time control is
passed to it (explicitly or implicitly) during a program’s run.

 Copyright IBM Corp. 1994 309


An independent segment is made available in its initial state during subsequent
transfers of control when:
Ÿ The transfer is the result of an implicit transfer of control between consecutive
statements that are in different segments (that is, when control drops through
into the independent segment from the physically preceding segment).
Ÿ The transfer is the result of an implicit transfer from a SORT or MERGE state-
ment in one segment to a SORT input procedure or SORT/MERGE output pro-
cedure in an independent segment.
Ÿ An explicit transfer of control from a section with a different segment number
takes place (as, for example, during the transfer of control in a PERFORM n
TIMES statement).

An independent segment is made available in its last-used state during subsequent


transfers of control when:
Ÿ With the exception of the two preceding kinds of implied transfers, an implicit
transfer from a section with a different priority takes place (as, for example,
when control is returned to the independent segment from a Declarative proce-
dure).
Ÿ An explicit transfer results from an EXIT PROGRAM or GOBACK statement.

Independent segments must be assigned segment numbers 50 through 99.

Segmentation Logic
In a segmented program, the sections are classified by a system of segment
numbers according to the following criteria:
Ÿ Frequency of Reference–Much-referenced sections, or those that must be
available for reference at all times, should be placed within fixed permanent
segments. Less frequently used sections can be within either fixed overlayable
or independent segments, depending on the program logic.
Ÿ Frequency of Use–The more frequently a section is used, the lower its segment
number; the less frequently it is referred to, the higher its segment number.
Ÿ Logical Relationships–Sections that frequently communicate with each other
should be given identical segment numbers.

Segmentation Control
Except for specific transfers of control, the logical sequence and the physical
sequence of program instructions are the same. The compiler inserts any
instructions necessary to initialize a segment. It is not necessary to transfer control
to the beginning of a segment, or to the beginning of a section within a segment.
Instead, control can be transferred to any paragraph in the Procedure Division.

COBOL Source Program Considerations


The following elements of a COBOL source program implement the Segmentation
feature:
Ÿ The SEGMENT-LIMIT clause in the OBJECT-COMPUTER paragraph of the
Environment Division. This clause allows you to control the specification of
fixed-permanent and fixed-overlayable segments.

310 COBOL/400 User’s Guide


Ÿ Procedure Division segment numbers, which group sections into segments.
The segment numbering scheme also allows specifications of independent seg-
ments, fixed-permanent segments, and (in conjunction with the
SEGMENT-LIMIT clause) of fixed-overlayable segments.

Segmentation–Environment Division
In the OBJECT-COMPUTER paragraph, the SEGMENT-LIMIT clause allows the
user to reclassify fixed permanent segments while retaining the properties of fixed
portion segments for the reclassified segments.

Format

55───SEGMENT-LIMIT──┬────┬──segment-number───────────── . ───────────────────5%
└─IS─┘

The SEGMENT-LIMIT clause allows the programmer to specify certain permanent


segments as capable of being overlaid by independent segments without losing the
logical properties of fixed portion segments.

segment-number must be an integer ranging in value from 1 through 49.

When the SEGMENT-LIMIT clause is specified:


Ÿ Fixed-permanent segments are those with segment numbers from 0 up to, but
not including, the segment number specified.
Ÿ Fixed-overlayable segments are those with segment numbers from the segment
number specified through 49.

For example, if SEGMENT-LIMIT IS 25 is specified, sections with segment


numbers 0 through 24 are fixed-permanent segments, and sections with segment
numbers 25 through 49 are fixed-overlayable segments.

When the SEGMENT-LIMIT clause is omitted, all sections with segment numbers 0
through 49 are fixed-permanent segments.

Segmentation–Procedure Division
In the Procedure Division of a segmented program, section classification is speci-
fied through segment numbers in the section headers. The segment number must
be an integer from 0 through 99.

Format

55───section-name──SECTION──┬────────────────┬──.────────────────────────────5%
└─segment-number─┘

All sections with the same segment number make up one program segment. Such
sections need not be contiguous in the source program.

Appendix A. Segmentation Feature 311


Segments with segment numbers 0 through 49 are in the fixed portion of the
program. Declarative sections can be assigned only these segment numbers.
Segments with segment numbers from 50 through 99 are independent segments.
If the segment number is omitted from the section header, the segment number is
assumed to be 0.

Segmentation–Special Considerations
When segmentation is used, there are restrictions on the ALTER, PERFORM,
SORT, and MERGE statements. There are also special considerations for calling
and called programs.

ALTER Statement
A GO TO statement in an independent segment must not be referred to by an
ALTER statement in a different segment. All other uses of the ALTER statement
are valid and are performed, even if the GO TO statement referred to is in a fixed-
overlayable segment.

PERFORM Statement
A PERFORM statement in the fixed portion can have in its range, in addition to any
Declarative procedures, the processing of which is caused within that range, only
one of the following:
Ÿ Sections and/or paragraphs in the fixed portion
Ÿ Sections and/or paragraphs contained within a single independent segment.

A PERFORM statement in an independent segment can have within its range, in


addition to any Declarative procedures, the processing of which is caused within
that range, only one of the following:
Ÿ Sections and/or paragraphs in the fixed portion
Ÿ Sections and/or paragraphs wholly contained in the same independent segment
as the PERFORM statement.

SORT and MERGE Statements


If a SORT or MERGE statement appears in the fixed portion, any SORT input pro-
cedures or SORT/MERGE output procedures must appear completely in one of the
following:
Ÿ The fixed portion
Ÿ A single independent segment.

If a SORT or MERGE statement appears in an independent segment, any SORT


input procedures or SORT/MERGE output procedures must appear completely in
one of the following:
Ÿ The fixed portion
Ÿ The same independent segment as the SORT or MERGE statement.

Calling and Called Programs


The CALL statement can appear anywhere within a segmented program. When a
CALL statement appears in an independent segment, that segment is in its last-
used state when control is returned to the calling program.

312 COBOL/400 User’s Guide


Appendix B. Debugging Features
The debugging features specify the conditions under which procedures are to be
monitored during program run time.

COBOL source language debugging statements are provided. You must decide
what to monitor, and what information you need to retrieve for debugging purposes.
The COBOL debugging features simply provide access to pertinent information.

COBOL Source Language Debugging


COBOL language elements that implement the Debugging Feature are a compile-
time switch (WITH DEBUGGING MODE), a run-time switch, a USE FOR DEBUG-
GING Declarative, the special register DEBUG-ITEM, and debugging lines that can
be written in the Environment, Data, and Procedure Divisions.

Compile-Time Switch
In the SOURCE-COMPUTER paragraph of the Configuration Section, the WITH
DEBUGGING MODE clause acts as a compile-time switch.

Format

55───SOURCE-COMPUTER.─┬─────────────────────────────────────────────┬─.──────5%
└─computer name─┬──────────────────────────┬──┘
└─┬──────┬──DEBUGGING MODE─┘
└─WITH─┘

The WITH DEBUGGING MODE clause serves as a compile-time switch for the
debugging statements written in the source program.

When WITH DEBUGGING MODE is specified, all debugging sections and debug-
ging lines are compiled as specified in this appendix. When WITH DEBUGGING
MODE is omitted, all debugging sections and debugging lines are treated as doc-
umentation.

 Copyright IBM Corp. 1994 313


Run-Time Switch
The run-time switch dynamically activates the debugging code that is generated
when WITH DEBUGGING MODE is specified.

Two commands are provided to control the run-time switch. To set the run-time
switch on, enter the command:
STRCBLDBG
and press F4.

You see the following display:

à@ Start COBOL Debug (STRCBLDBG)


ð
Type choices, press Enter.

Program . . . . . . . . . . . . Name
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

á ñ

The following diagram shows the syntax of the STRCBLDBG command:

55──STRCBLDBG──┬────────────────────────────────────────────┬─────────────────5%
└─PGM──(─┬─────────────────┬──program-name─)─┘
├──\LIBL/─────────┤
├──\CURLIB/───────┤
└──library-name/──┘

┌───────────────────────────────────┐
│Job: B,I Pgm: B,I REXX: B,I Exec│
└───────────────────────────────────┘

Figure 107. Syntax of the STRCBLDBG Command

This command is allowed in interactive and batch processing, and in CL programs.

General-Use Programming Interface

You can use this command in QCMDEXC.

End of General-Use Programming Interface

314 COBOL/400 User’s Guide


To set the run-time switch off, enter the command:
ENDCBLDBG
and press F4.

You see the following display:

à@ End COBOL Debug (ENDCBLDBG)


ð
Type choices, press Enter.

Program . . . . . . . . . . . . Name
Library . . . . . . . . . . . \LIBL Name, \LIBL, \CURLIB

Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys

á ñ

The following diagram shows the syntax of the ENDCBLDBG command:

55──ENDCBLDBG──┬────────────────────────────────────────────┬─────────────────5%
└─PGM──(─┬─────────────────┬──program-name─)─┘
├──\LIBL/─────────┤
├──\CURLIB/───────┤
└──library-name/──┘

┌───────────────────────────────────┐
│Job: B,I Pgm: B,I REXX: B,I Exec│
└───────────────────────────────────┘

Figure 108. Syntax of the ENDCBLDBG Command

This command is allowed in interactive and batch processing, and in CL programs.

General-Use Programming Interface

You can use this command in QCMDEXC.

End of General-Use Programming Interface

The default for the run-time switch is off.

When debugging mode is specified through the run-time switch, all the debugging
sections and debugging lines (D in column 7) compiled into the program are acti-
vated.

Appendix B. Debugging Features 315


You must enter the STRCBLDBG command for each COBOL program (main
program or called program) to be debugged in the next COBOL run unit. At the
end of the run unit, all run-time switches that are on are set off. If a switch must be
set off before starting a COBOL run unit, use the ENDCBLDBG command. Run-
time switches for up to 15 programs can be on at once.

When the STRCBLDBG or ENDCBLDBG command is issued in a CL program,


concatenation expressions can be used for all parameter values. See the CL
Programmer’s Guide for more information about concatenation expressions.

When debugging mode is suppressed, through the run-time switch, any USE FOR
DEBUGGING Declarative procedures are inhibited. All debugging lines (D in
column 7) remain in effect.

Recompilation of the source program is not required to activate or deactivate the


run-time switch.

When WITH DEBUGGING MODE is not specified in the SOURCE-COMPUTER


paragraph, the run-time switch has no effect on the running of the program.

USE FOR DEBUGGING Declarative


The USE FOR DEBUGGING sentence in the Procedure Division identifies the
items in the source program that are to be monitored by the associated debugging
declarative procedure.

Format

┌────────────────────────────────────────┐
6 │
55───USE─┬─────┬─DEBUGGING─┬────┬─┬─┬───────────────────────┬─identifier-1─┼─5%
└─FOR─┘ └─ON─┘ │ └─ALL─┬───────────────┬─┘ │
│ └─REFERENCES OF─┘ │
├─file-name-1────────────────────────────┤
├─procedure-name-1───────────────────────┤
└─ALL PROCEDURES─────────────────────────┘

Identifier-1 cannot be reference modified.

When specified, all debugging sections must be written immediately after the
DECLARATIVES header. Except for the USE FOR DEBUGGING sentence there
must be no reference to any non-declarative procedure within the debugging proce-
dure.

Note that the USE FOR DEBUGGING declarative causes all subsequent state-
ments to be ignored up to a valid USE AFTER EXCEPTION/ERROR statement, or
END DECLARATIVES delimiter. Entire programs can be ignored because of this.

Automatic running of a debugging section is not caused by a statement appearing


in a debugging section.

316 COBOL/400 User’s Guide


A debugging section for a specific operand is processed only once as the result of
the running of a single statement, no matter how many times the operand is speci-
fied in the statement. An exception to this rule is that each specification of a sub-
scripted or indexed identifier where the subscripts or indexes are different causes
the calling of the debugging Declarative. For a PERFORM statement that causes
repeated running of a procedure, any associated procedure name debugging
Declarative section is run only once for each processing of the procedure.

For debugging purposes, each separate occurrence of an imperative verb within an


imperative statement begins a separate statement.

Statements appearing outside the debugging sections must not refer to procedure
names defined within the debugging sections.

Except for the USE FOR DEBUGGING sentence itself, statements within a debug-
ging Declarative section can only refer to procedure names defined in a different
USE procedure through the PERFORM statement. Procedure names within debug-
ging Declarative sections must not appear in USE FOR DEBUGGING sentences.

Table 7 defines the points during program run time when the USE FOR DEBUG-
GING procedures are processed. Identifier-n, file-name-n, and procedure-name-n
refer to the first and all subsequent specifications of that type of operand in one
USE FOR DEBUGGING sentence. Any particular identifier, file name, or procedure
name can appear in only one USE FOR DEBUGGING sentence, and only once in
that sentence.

An identifier in a USE FOR DEBUGGING sentence:


Ÿ Must be specified without the subscripting or indexing normally required if it
contains an OCCURS clause or is subordinate to an entry containing an
OCCURS clause. (A SEARCH or SEARCH ALL statement that refers to such
an identifier does not call the USE FOR DEBUGGING procedures.)
Ÿ Must not be a special register.

When ALL PROCEDURES is specified in a USE FOR DEBUGGING sentence,


procedure-name-1, procedure-name-2, procedure-name-3, and so on, must not be
specified in any USE FOR DEBUGGING sentence. The ALL PROCEDURES
phrase can be specified only once in a program.

When a USE FOR DEBUGGING operand is used as a qualifier, such a reference


in the program does not activate the debugging procedures.

References to the DEBUG-ITEM special register can be made only from within a
debugging Declarative procedure.

Appendix B. Debugging Features 317


Table 7. Running Debugging Declaratives
USE FOR The USE FOR DEBUGGING procedures run
DEBUGGING Operand immediately after the following:
identifier-n Before REWRITE/WRITE identifier-n and after FROM
phrase move, if applicable.

After each initialization, modification, or


evaluation of identifier-n in
PERFORM/VARYING/AFTER/UNTIL identifier-n.

After any other COBOL statement that explicitly


refers to identifier-n and could change its
contents. (See note.)
ALL REFERENCES OF Before GO TO DEPENDING ON identifier-n, control is
identifier-n transferred, and before any associated debugging
section for the procedure name runs.

Before REWRITE/WRITE identifier-n and FROM phrase


move, if applicable.

After each initialization, modification or


evaluation of identifier-n in
PERFORM/VARYING/AFTER/UNTIL identifier-n.

After any other COBOL statement explicitly


referring to identifier-n. (See note.)
file-name-n After CLOSE/DELETE/OPEN/START file-name-n.

After READ file-name-n where AT END/INVALID KEY


was not run.
procedure-name-n Before each running of the named procedure.

After running an ALTER statement referring


to the named procedure.
ALL PROCEDURES Before each running of every non-debugging
procedure.

After running every ALTER statement (except


ALTER statements in Declarative procedures).

Note: Operands acted upon but not explicitly named in such statements as ADD,
MOVE, or SUBTRACT CORRESPONDING never cause activation of a USE
FOR DEBUGGING procedure when such statements are run. If identifier-n
is specified in a phrase that is not processed, the associated debugging
section is not run.

318 COBOL/400 User’s Guide


DEBUG-ITEM Special Register
The DEBUG-ITEM special register provides information for a debugging Declarative
procedure. DEBUG-ITEM has the following implicit description:

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

The DEBUG-ITEM special register provides information about the conditions


causing the running of a debugging section.

Before each debugging section is processed, DEBUG-ITEM is filled with spaces.


The contents of the DEBUG-ITEM subfields are then updated according to the rules
for the MOVE statement, with one exception: DEBUG-CONTENTS is updated as if
the move were an alphanumeric-to-alphanumeric elementary move without conver-
sion of data from one form of internal representation to another. After updating,
each field contains:
Ÿ DEBUG-LINE: The compiler-generated statement number, right justified and
padded on the left with zeros. For example, 000112.
Ÿ DEBUG-NAME: The first 30 characters of the name causing the debugging
section to run. All qualifiers are separated by the word OF (subscripts or
indexes are not entered in DEBUG-NAME).
Ÿ DEBUG-SUB-1, DEBUG-SUB-2, DEBUG-SUB-3: If the DEBUG-NAME is sub-
scripted or indexed, the occurrence number of each level is entered in the
respective DEBUG-SUB-n. If the item is not subscripted or indexed, these
fields remain spaces.
Ÿ DEBUG-CONTENTS: Data is moved into DEBUG-CONTENTS as shown in
Table 8. DEBUG-CONTENTS is the same size as the largest identifier in the
program.

Appendix B. Debugging Features 319


Table 8. DEBUG-ITEM Subfield Contents
DEBUG-LINE
Contains Number
Item Causing of COBOL
Debug Section Statement DEBUG-NAME DEBUG-CONTENTS
To Run Referring to Contains Contains
identifier-n identifier-n identifier-n Contents of identifier-n
when control passes
to debug section.
file-name-n file-name-n file-name-n For READ: contents of record
retrieved. Other references:
spaces.
procedure-name-n ALTER statement procedure-name-n procedure-name-n in TO
ALTER reference PROCEED TO phrase
GO TO procedure- GO TO statement procedure-name-n
name-n
procedure-name-n in SORT/MERGE state- procedure-name-n “SORT INPUT” “SORT
SORT/MERGE ment OUTPUT” “MERGE OUTPUT”
INPUT/OUTPUT as applicable
PROCEDURE
PERFORM statement This PERFORM procedure-name-n “PERFORM LOOP”
transfer of control statement
procedure-name-n in Statement causing procedure-name-n “USE PROCEDURE”
a USE procedure USE procedure
running
Implicit transfer from Previous statement procedure-name-n “FALL THROUGH”
previous sequential processed in previous
procedure sequential procedure
(see note)
First entry into first Line number of first First non- “START PROGRAM”
non-declarative pro- statement in the pro- declarative proce-
cedure cedure dure name

Note: If this paragraph is preceded by a section header and control is passed


through the section header, the statement number refers to the section
header.

320 COBOL/400 User’s Guide


Debugging Lines
Debugging lines can help determine the cause of an error. A debugging line is any
line in a source program with a D coded in column 7 (the continuation area). If a
debugging line contains nothing but spaces in Area A and Area B, it is considered
a blank line.

Each debugging line must be written so that a syntactically correct program results
whether the debugging lines are compiled into the program or syntax-checked, but
are treated as documentation.

Successive debugging lines are permitted. Debugging lines can be continued.


However, each continuation line must contain a D in column 7, and character-
strings must not be broken across two lines.

Debugging lines can be specified only after the OBJECT-COMPUTER paragraph.

When the WITH DEBUGGING MODE clause is specified in the


SOURCE-COMPUTER paragraph, all debugging lines are compiled as part of the
object program.

When the WITH DEBUGGING MODE clause is omitted, all debugging lines are
syntax-checked, but are treated as documentation.

Appendix B. Debugging Features 321


322 COBOL/400 User’s Guide
Appendix C. Level of Language Support

ANSI X3.23-1985 COBOL Standard


The ANSI X3.23-1985 COBOL standard consists of eleven functional processing
modules, seven of which are required and four of which are optional.

The seven required modules are: Nucleus, Sequential I-O, Relative I-O, Indexed
I-O, Inter-Program Communication, Sort-Merge, and Source Text Manipulation.
The four optional modules are: Report Writer, Communication, Debug and Seg-
mentation.

Language elements within the modules may be classified as level 1 elements and
level 2 elements. Elements within nine of the modules are divided into level 1 ele-
ments and level 2 elements. Two of the modules (SORT-MERGE and REPORT
WRITER) contain only level 1 elements. For instance, Nucleus level 1 elements
perform basic internal operations. Nucleus level 2 elements provide for more
extensive and sophisticated internal processing.

The three subsets of Standard COBOL are the high subset, the intermediate
subset, and the minimum subset. Each subset is composed of a level of the seven
required modules: Nucleus, Sequential I-O, Relative I-O, Indexed I-O, Inter-
Program Communication, Sort-Merge, and Source Text Manipulation. The four
optional modules (Report Writer, Communication, Debug and Segmentation) are
not required in the three subsets of Standard COBOL.
The high subset is composed of all language elements of the highest level of
all required modules. That is:
Ÿ Level 2 elements from Nucleus, Sequential I-O, Relative I-O, Indexed I-O,
Inter-Program Communication, and Source Text Manipulation
Ÿ Level 1 elements from Sort-Merge.
The intermediate subset is composed of all language elements of level 1 of all
required modules. That is:
Ÿ Level 1 elements from Nucleus, Sequential I-O, Relative I-O, Indexed I-O,
Inter-Program Communication, Sort-Merge, and Source Text Manipulation.
The minimum subset is composed of all language elements of level 1 of the
Nucleus, Sequential I-O, and Inter-Program Communication modules.

The four optional modules are not an integral part of any of the subsets. However,
none, all, or any combination of the optional modules may be associated with any
of the subsets.

COBOL/400 Level of Language Support


The COBOL/400 compiler supports:
Ÿ Level 1 of the Nucleus, Sequential I-O, Relative I-O, Indexed I-O, Inter-Program
Communication, Sort-Merge, and Source Text Manipulation modules
Ÿ Level 2 of the Debug and Segmentation modules.

 Copyright IBM Corp. 1994 323


The Report Writer and Communication modules of ANSI X3.23-1985 COBOL are
not supported by the COBOL/400 compiler.

The level of support provided by the COBOL/400 compiler is represented in the


table below. The table:
Ÿ Shows the level of COBOL/400 compiler support for each functional processing
module of the ANSI X3.23-1985 COBOL standard
Ÿ Describes each module.

Following is an explanation of the notation used within the table:

A 3-character code that identifies the module.


In this example, the Segmentation module, is
referenced.



6
┌───┐
2 SEG ð,2
└─┘ └───┘
& &
│ │
│ │
│ │
The level of this module supported by The range of levels of support
the COBOL/4ðð compiler. In this defined by the ANSI X3.23-1985 COBOL
example, support is provided for the standard. A level of ð means a minimum
higher of the two levels of the standard COBOL does not need to support
Segmentation module. this module to conform to the standard.

Table 9 (Page 1 of 2). Level of COBOL/400 Compiler Support


COBOL/400
Level of
Language
Supported Module Description
Nucleus Contains the language elements necessary for internal processing
1 NUC 1,2 of data within the four basic divisions of a program and the capa-
bility for defining and accessing tables.
Sequential I-O Provides access to file records by the established sequence in
1 SEQ 1,2 which they were written to the file.
Relative I-O Provides access to records in either a random or sequential
1 REL 0,2 manner. Each record is uniquely identified by an integer that
represents the record’s logical position in the file.
Indexed I-O Provides access to records in either random or sequential
1 INX 0,2 manner. Each record in an indexed file is uniquely identified by a
record key.
Inter-program Allows a COBOL program to communicate with other programs
Communication through transfers of control and access to common data items.
1 IPC 1,2
Sort-Merge Orders one or more files of records, or combines two or more
1 SRT 0,1 identically ordered files according to user-specified keys.
Source-Text Allows insertion of predefined COBOL text into a program at
Manipulation compile time.
1 STM 0,2

324 COBOL/400 User’s Guide


Table 9 (Page 2 of 2). Level of COBOL/400 Compiler Support
COBOL/400
Level of
Language
Supported Module Description
Report Writer Provides semiautomatic production of printed reports.
0 RPW 0,1
Communications Provides the ability to access, process, and create messages or
0 COM 0,2 portions of messages; also allows communication through a
Message Control System with local and remote communication
devices.
Debug Allows you to specify statements and procedures for debugging.
2 DEB 0,2
Segmentation Provides the overlaying at object time of Procedure Division
2 SEG 0,2 sections.

SAA Common Programming Interface (CPI) Support


Source file QILBINC in product libraries QLBL and QLBLP contains members that
hold specifications for multiple SAA Common Programming Interfaces. These
specifications describe parameter interfaces. This file is IBM-owned and should not
be changed.

If you want to customize any of the specifications, you must copy any members
that you want to change to a source file in one of your libraries. You can use the
Copy File (CPYF) command to do this. For more information about the CPYF
command, refer to the CL Reference.

If you copy these specifications to your library, you must refresh your copies when
a new product release is installed, or when any changes are made using a
Program Temporary Fix (PTF). IBM provides maintenance for these specifications
only in the libraries in which they are distributed.

Appendix C. Language Support 325


326 COBOL/400 User’s Guide
Appendix D. COBOL/400 Messages, the FIPS Flagger, and
SAA Flagging

COBOL/400 Messages
This appendix provides a general description of messages that IBM supplies with
the COBOL/400 licensed program.

Interactive Messages
In an interactive environment, messages are displayed on the work station display.
They can appear on the current display as a result of the running of the program or
in response to your keyed input to prompts, menus, command entry displays, or
Application Development Tools (Appl Dev Tools). The messages can also appear
on request, as a result of a display command or an option on a menu.

The messages for the COBOL/400 licensed program begin with an LSC, LBE, or
LBL prefix.

The LSC messages are issued by the COBOL/400 syntax checker when the
Source Entry Utility (SEU) is used to enter your COBOL/400 source. For example,
you see the following display after incorrectly entering the program name in the
PROGRAM-ID paragraph.

à@ Columns . . . : 1 71 Edit XMPLIB/QLBLSRC


ð
SEU==> TESTPR
FMT CB ......-A+++B+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\\\\\\\\\\\\\\\ Beginning of data \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðððð.1ð IDENTIFICATION DIVISION.
ðððð.2ð PROGRAM-ID. #TESTPR.
ðððð.7ð ENVIRONMENT DIVISION.
ðððð.9ð SOURCE-COMPUTER. IBM-AS4ðð.
\\\\\\\\\\\\\\\\\\ End of data \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

F3=Exit F4=Prompt F5=Refresh F9=Retrieve F1ð=Cursor


F16=Repeat find F17=Repeat change F24=More keys
# not in COBOL character set. Line rejected.
á ñ
Figure 109. Example of a COBOL/400 Syntax Checker Message

 Copyright IBM Corp. 1994 327


LBE messages provide you with additional information about system operation
during run time. For example, you might see the following display if you have a
run-time error:

à@ Display Program Messages


ð
Job ð11111/PGMRS/E34 started on ð3/ð4/9ð at 14:35:ð2 in subsystem QINTER in
Message CPF41ð1 in XMPLDUMP in COBOLEX (C D F G).

Type reply, press Enter.


Reply . . . _______________________________________________________________
________________________________________________________________________________

F3=Exit F12=Cancel

á ñ
Figure 110. Run-Time Error Message

If you move the cursor to the line on which message number CPF4101 is indicated
and press either the HELP key or F1, the LBE message information is displayed as
shown:

à@ Additional Message Information


ð
Message ID . . . . . . : LBE72ðð Severity . . . . . . : 99
Message type . . . . . : INQUIRY
Date sent . . . . . . . : ð3/ð4/9ð Time sent . . . . . : 14:37:15
From program . . . . . : QLREXHAN Instruction . . . . : ðððð
To program . . . . . . : \EXT Instruction . . . . : ðððð

Message . . . . : Message CPF41ð1 in XMPLDUMP in COBOLEX (C D F G).


Cause . . . . . : Message CPF41ð1 was detected in COBOL statement .OPEN (MI
instruction ðð7E) in program XMPLDUMP in COBOLEX.
Recovery . . . : Enter a G to continue the program at the next MI
instruction, or a C if no dump is wanted, a D if a dump of the COBOL
identifiers is wanted, or and F to dump both the COBOL identifiers and the
compiler-generated variables. The message text for CPF41ð1 follows: File
SALES in library \LIBL not found or inline data file missing.
Possible choices for replying to message . . . . . . . . . . . . . . . :
C -- No formatted dump is given
D -- A dump of the COBOL identifiers is given
F -- A dump of all variables is given
G -- To continue the program at the next MI instruction.
Bottom
Press Enter to continue.

F3=Exit F1ð=Display messages in job log F12=Cancel


á ñ
Figure 111. Run-Time Error Message—Second-Level Text

LBE messages 7900 to 7999 are used as headings for information printed during a
COBOL/400 formatted dump.

328 COBOL/400 User’s Guide


The LBL messages are described under “Compilation Messages” below.

“Responding to Messages” on page 329 explains how to display second-level


message text and how to reply to messages.

Compilation Messages
LBL messages are printed in the program listing when errors are found during
program compilation. The LBL messages include the message issued when
Federal Information Processing Standard (FIPS) flagging is requested; for more
information on the FIPS messages, refer to page 331 in this appendix.

Program Listings
In the compiler output, the COBOL/400 messages listing follows the source listing.
The COBOL/400 messages listing gives the message identifier, severity, text,
usually the location of the error, and the messages summary.

For more information about Program Listings, see “Source Listing” on page 41.

Responding to Messages
In an interactive environment, a message is indicated by one or several of these
conditions:
Ÿ A brief message (called first-level text) on the message line
Ÿ Reverse image highlighting of the input field in error
Ÿ A locked keyboard
Ÿ The sound of an alarm (if the alarm option is installed).

The following paragraphs briefly describe some methods of responding to error


messages; more information is available in the New User’s Guide and the Applica-
tion Development Tools publications.

If the necessary correction is obvious from the initial display, you can press the
Error Reset key (if the keyboard is locked), enter the correct information, and con-
tinue your work.

If the message requires that you choose a reply (such as C to cancel, D to dump
COBOL identifiers, F to dump all variables, or G to resume processing at the next
COBOL statement), the reply options are shown in parentheses in the first-level
message text. For an example, see Figure 110 on page 328.

If the information on the initial information display does not provide sufficient data
for you to handle the error, you can press the HELP key (after positioning the
cursor to the message line, if required) to get a second-level display with additional
information about how to correct this error. To return to the initial display, press the
Enter key; then press the Error Reset key (if the keyboard is locked), and make
your correction or response.

If the error occurs when you are compiling or running a program, you might need to
modify your COBOL/400 source statements or control language (CL) commands.
Refer to the SEU User’s Guide and Reference for information on how to change
the statements.

Appendix D. COBOL/400 Messages 329


COBOL Message Descriptions
The messages for the COBOL/400 licensed program begin with prefixes LSC, LBE,
or LBL.
The LSC messages are issued by the COBOL syntax checker when SEU is
used to enter your COBOL source.
The LBE messages provide you with additional information about system oper-
ation during run time.
The LBL messages are compiler-generated messages.

Message numbers are assigned as follows:

Error Message Description


LBE7000 through LBE7199 Escape Messages
LBE7200 through LBE7999 Run-time messages
LBE9001 Escape message
LBL0000 through LBL0999 Messages with severity less than 30
LBL1000 through LBL1999 Messages with severity greater than or
equal to 30
LBL8000 through LBL8799 FIPS Flagger messages
LBL8800 through LBL8899 SAA Flagging messages
LSC0000 through LSC1999 Syntax checker messages

Severity Levels
The COBOL/400 licensed program provides the following message severity levels:
Severity Meaning
00 Informational: This level is used to convey information to the user.
No error has occurred. Informational messages are listed only when
the FLAG (00) option is specified.
10 Warning: This level indicates that an error was detected but is not
serious enough to interfere with the running of the program.
20 Error: This level indicates that an error was made, but the compiler
is taking a recovery that might yield the desired code.
30 Severe Error: This level indicates that a serious error was detected.
Compilation is completed, but running of the program cannot be
attempted.
40 Unrecoverable: This level usually indicates a user error that forces
termination of processing.
50 Unrecoverable: This level usually indicates a compiler error that
forces termination of processing.
99 Action: Some manual action is required, such as entering a reply,
changing printer forms, or replacing diskettes.
Note: 00, 10, and 20 messages are suppressed when the FLAG(30) option of the
PROCESS statement is used or the CRTCBLPGM command specifies
FLAG(30) and is not overridden by the PROCESS statement. See “Using
the PROCESS Statement to Specify Compiler Options” on page 32 for
further information.

330 COBOL/400 User’s Guide


The compiler always attempts to provide full diagnostics of all source text in the
program, even when errors have been detected. If the compiler cannot continue on
a given statement, the message states that the compiler cannot continue and that it
will ignore the rest of the statement. When this error occurs, the programmer
should examine the entire statement.

The OS/400 message facility is used to produce all messages. The COBOL/400
compiler messages reside in the message file, QLBLMSG, and the run-time mes-
sages reside in the message file, QLBLMSGE.

Substitution variables and valid reply values are determined by the program
sending the message, not by the message description stored in the message file.
However, certain elements of a message description can be changed: for example,
the text, severity level, default response, or dump list. To effect such changes, you
need to define another message description using an Add Message Description
(ADDMSGD) command, place the modified description in a user-created message
file,1 and specify that file in the Override Message File (OVRMSGF) command.
Using the OVRMSGF command allows the compiler to retrieve messages from the
specified file. See the ADDMSGD and OVRMSGF commands in the CL Reference
for additional information.

CAUTION: Overriding an IBM-supplied message with a user-created message can


produce results you do not anticipate. If reply values are not retained, the program
might not respond to any replies. Changing default replies on *NOTIFY type mes-
sages could affect the ability of the program to run in unattended mode. Changing
the severity could cancel a job not previously canceled. Be cautious when over-
riding IBM-supplied messages with user-created messages.

The Federal Information Processing Standard (FIPS) Flagger


The FIPS flagger can be specified to monitor a FIPS COBOL subset, any of the
optional modules, all of the obsolete language elements, or a combination of a
FIPS COBOL subset, optional modules and all obsolete elements.

The monitoring is an analysis that compares the syntax used in the source program
with the syntax included in the user-selected FIPS subset and optional modules.
Any syntax used in the source program that does not conform to the selected FIPS
COBOL subset and optional modules is identified. Any syntax for an obsolete lan-
guage element used in the source program will also be identified (depending on the
compiler option chosen). See page 25 for more information on the parameters for
FIPS flagging.

1986 FIPS COBOL specifications are the language specifications contained in ANSI
X3.23-1985 COBOL. FIPS COBOL is subdivided into three subsets and four
optional modules. The three subsets are identified as Minimum, Intermediate and
High. The four optional modules are Report Writer, Communication, Debug, and
Segmentation. These four optional modules are not an integral part of any of the
subsets; however, none, all, or any combination of the optional modules may be
associated with any of the subsets. Any program written to conform to the 1986
FIPS standard must conform to one of the subsets of 1986 FIPS COBOL.

1 If an IBM-supplied message must be changed and replaced in its message file, call your service representative.

Appendix D. COBOL/400 Messages 331


Table 10 on page 332 shows the 1985 ANSI Standard COBOL processing
modules included in each of the subsets of 1986 FIPS COBOL.

Following is an explanation of the notation used within the table:

A 3-character code that identifies the module.


In this example, the Segmentation module, is
referenced.



6
┌───┐
2 SEG ð,2
└─┘ └───┘
& &
│ │
│ │
│ │
The level of this module supported by The range of levels of support
the 1986 FIPS COBOL standard. In this defined by the ANSI X3.23-1985 COBOL
example, support is provided for the standard. A level of ð means a minimum
higher of the two levels of the standard COBOL does not need to support
Segmentation module. this module to conform to the standard.

Table 10. 1985 American National Standard COBOL and 1986 FIPS Levels
1985 ANSI
Module Name High Intermediate Minimum
FIPS FIPS FIPS
Nucleus 2 NUC 1,2 1 NUC 1,2 1 NUC 1,2
Sequential I-O 2 SEQ 1,2 1 SEQ 1,2 1 SEQ 1,2
Relative I-O 2 REL 0,2 1 REL 0,2 0 REL 0,2
Indexed I-O 2 INX 0,2 1 INX 0,2 0 INX 0,2
Source-Text
Manipulation 2 STM 0,2 1 STM 0,2 0 STM 0,2
Sort-Merge 1 SRT 0,1 1 SRT 0,1 0 SRT 0,1
Inter-Program
Communication 2 IPC 1,2 1 IPC 1,2 1 IPC 1,2
Report Writer 0, or 1 RPW 0,1 0, or 1 RPW 0,1 0, or 1 RPW 0,1
Segmentation 0,1 or 2 SEG 0,2 0,1 or 2 SEG 0,2 0,1 or 2 SEG 0,2
Debug 0,1 or 2 DEB 0,2 0,1 or 2 DEB 0,2 0,1 or 2 DEB 0,2
Communications 0,1 or 2 COM 0,2 0,1 or 2 COM 0,2 0,1 or 2 COM 0,2

Note: The COBOL/400 compiler supports the Segmentation and Debug optional
modules.

Elements that are specified in the COBOL/400 source program and that are not
included in 1986 FIPS COBOL are flagged as described in Appendix C, “Level of
Language Support” on page 323.

332 COBOL/400 User’s Guide


SAA Flagging
You can choose to perform SAA flagging to determine if the COBOL/400 functions
that you are using are portable to other SAA COBOL environments.

Flagging is performed on those COBOL/400 functions that are outside of SAA


COBOL, such as:
COBOL/400 extensions
COBOL/400 compiler limits
Non-SAA reserved words
Compiler options.

In this way, you can write programs that conform to the SAA COBOL definition.

For an example of SAA flagging in a compiler listing, see Figure 12 on page 47.
To perform SAA flagging through the CRTCBLPGM CL command, specify
SAAFLAG(*FLAG). To perform SAA flagging through a PROCESS statement,
specify SAAFLAG.

To compile a program to conform to the SAA definition, using the CRTCBLPGM


command, specify the following:
OPTION(\QUOTE \NOSEQUENCE \NONUMBER)
GENOPT(\CRTF \DUPKEYCHK \SYNC)
SAAFLAG(\FLAG)

If you use the PROCESS statement, specify the following:


QUOTE, NOSEQUENCE, NONUMBER, CRTF,
DUPKEYCHK, SYNC, SAAFLAG.

For more information about specifying the option for SAA flagging, see the
SAAFLAG parameter on page 25, and the “Using the PROCESS Statement to
Specify Compiler Options” on page 32.

For information about compiler limits, see the Compiler Limits appendix in the
COBOL/400 Reference.

Appendix D. COBOL/400 Messages 333


334 COBOL/400 User’s Guide
Appendix E. Differences Between ANSI 74 COBOL and ANSI
85 COBOL
This appendix identifies the ANSI 85 COBOL language elements that are incompat-
ible with ANSI 74 COBOL. These items identify the changes and conditions that
ANSI 74 COBOL users need to be aware of when migrating to ANSI 85 COBOL.

See “Industry Standards Used in Compiler Design” on page xiii for more informa-
tion on ANSI 85 COBOL.

Migrating ANSI 74 COBOL Programs to ANSI 85 COBOL


The following are some of the new features or changes to ANSI 85 COBOL that
could affect ANSI 74 COBOL programs:
Ÿ The keyword ALPHABET must precede alphabet-name within the alphabet-
name clause of the SPECIAL-NAMES paragraph. An alphabet-name is a user-
defined word in the SPECIAL-NAMES paragraph that names a character set or
collating sequence.
Ÿ The relative key data item specified in the RELATIVE KEY phrase must not
contain the PICTURE symbol “P.”
Ÿ The ALPHABETIC class test is true for uppercase letters, lowercase letters,
and the space character.
Ÿ When there is no next statement to be processed in a called program, an
implicit EXIT PROGRAM is run.
Ÿ No two files in a MERGE statement can be specified in the SAME AREA or
SAME SORT-MERGE AREA clause. The only files in a MERGE statement that
can be specified in the SAME RECORD AREA clause are those associated
with the GIVING phrase.
Ÿ Within the READ statement, the INTO phrase cannot be specified unless:
All records associated with the file and the data item specified in the INTO
phrase are group items or elementary alphanumeric items, or only one
record description is subordinate to the file description entry.
Ÿ Within the RETURN statement, the INTO phrase cannot be specified unless:
All records associated with the file and data item specified in the INTO
phrase are group items or elementary alphanumeric items, or only one
record description is subordinate to the sort-merge file description entry.
Ÿ File position indicator - the concept of a current record pointer has been
changed to a file position indicator.
Ÿ Reserved words - new reserved words have been added.
Ÿ I/O status - new I/O status values have been added.
Ÿ Pseudo-text-1 on the COPY statement must not consist entirely of a separator
comma or a separator semicolon.
Ÿ A data item appearing in the USING phrase of the Procedure Division header
must not have a REDEFINES clause in its data description entry.

 Copyright IBM Corp. 1994 335


Ÿ If the FOOTING phrase is not specified, no end-of-page condition independent
of the page overflow condition exists.
Ÿ The NO REWIND phrase cannot be specified in a CLOSE statement having the
REEL/UNIT phrase.
Ÿ The CANCEL and STOP RUN statements close all open files.
Ÿ When a receiving item is a variable-length data item and contains the object of
the DEPENDING ON phrase, the maximum length of the item will be used.
Ÿ Within the VARYING ... AFTER phrase of the PERFORM statement, identifier-2
is augmented before identifier-5 is set.
Ÿ Any subscripts for identifier-4 in the DIVIDE statement REMAINDER phrase are
evaluated after the result of the DIVIDE operation is stored in identifier-3 of the
GIVING phrase.
Ÿ The phrase ADVANCING PAGE and END-OF-PAGE must not both be in a
single WRITE statement.
Ÿ The picture character-string of an alphabetic item can contain only the symbol
“A.” No editing is allowed for the alphabetic data category.
Note: An alphabetic character is a letter or a space character.
Ÿ When a data item described by a PICTURE containing the character “P” is ref-
erenced, the digit positions specified by “P” are considered to contain zeros in
the following operations:
– Any operation requiring a numeric sending operand
– A MOVE statement where the sending operand is numeric and its
PICTURE character-string contains the symbol “P”
– A MOVE statement where the sending operand is numeric edited and its
PICTURE character-string contains the symbol “P” and the receiving
operand is numeric or numeric edited
– A comparison operation where both operands are numeric.
Ÿ The literal in the CURRENCY SIGN clause cannot be a figurative constant.
Ÿ If the COPY statement appears in a comment-entry, it is considered part of the
comment-entry.
Ÿ The following special cases of exponentiation are defined:
– If an expression having a zero value is raised to a negative or zero power,
the size error condition exists.
– If the evaluation of the exponentiation yields both a positive and a negative
real number, the positive number is returned.
– If no real number exists as the result of the evaluation, the size error condi-
tion exists.
Ÿ When the figurative constant ALL literal is not associated with another data
item, the length of the string is the length of the literal.

336 COBOL/400 User’s Guide


Appendix F. Supporting International Languages with
Double-Byte Character Sets

IBM Extension

This appendix describes only those enhancements made to the COBOL program-
ming language for writing programs that process double-byte characters.

Specifically, this appendix describes where you can use Double-Byte Character Set
(DBCS) characters in each portion of a COBOL program, and considerations for
working with DBCS data in the COBOL/400 language.

There are two ways to specify DBCS characters:


Ÿ Bracketed-DBCS
Ÿ DBCS-graphic data

In general, COBOL handles bracketed-DBCS characters in the same way it handles


alphanumeric characters. Bracketed-DBCS is a character string in which each
character is represented by two bytes. The character starts with a shift-out (SO)
character, and ends with a shift-in (SI) character. It is up to you to know (or have
the COBOL program check) which data items contain DBCS characters, and to
make sure the program receives and processes this information correctly.

You can now use DDS descriptions that define DBCS-graphic data fields with your
COBOL/400 programs. DBCS-graphic pertains to a character string where each
character is represented by two bytes. The character string does not contain
shift-out or shift-in characters. You cannot use source programs containing graphic
data. For information on specifying graphic data items with your COBOL/400 pro-
grams, refer to “DBCS-Graphic Fields” on page 133.

Using DBCS Characters in Literals

Types of Literals
There are two types of literals in which you can use DBCS characters: the DBCS
literal and the mixed literal. A mixed literal consists of Double-Byte Character Set
(DBCS) and Single-Byte Character Set (SBCS) characters.

DBCS Literals: The COBOL compiler recognizes DBCS characters in DBCS


literals when you use the GRAPHIC option on the PROCESS statement.
Note: The GRAPHIC option on the PROCESS statement is not to be confused
with the *GRAPHIC value in the CVTOPT parameter of the CRTCBLPGM
command and the CVTGRAPHIC option on the PROCESS statement,
which are used to specify double-byte graphic data from a DDS description.
For more information on specifying graphic data, refer to “DBCS-Graphic
Fields” on page 133.

DBCS/SBCS Literals: The COBOL compiler recognizes DBCS characters in


DBCS/SBCS (mixed) literals, when you are on a DBCS system and the GRAPHIC
option on the PROCESS statement is not specified.

 Copyright IBM Corp. 1994 337


How to Specify Literals Containing DBCS Characters
When you specify any literal that contains DBCS characters, follow the same rules
that apply in specifying alphanumeric literals, as well as the following rules specific
to the literal types:

How to Specify a DBCS Literal: When you specify a DBCS literal, keep in mind
the following:

The format for a DBCS literal is:


"ðEK1K2ðF"
Ÿ A quotation mark opens and closes the literal.
Ÿ A shift-out character (ðE) immediately follows the initial quotation mark and
occupies 1 byte. A shift-out character is a control character (hex 0E) that indi-
cates the start of a string of double-byte characters.
Ÿ A shift-in character (ðF) immediately precedes the final quotation mark and
occupies 1 byte. A shift-in character is a control character (hex 0F) that indi-
cates the end of a string of double-byte characters.
Ÿ All DBCS characters appear between the shift-out and shift-in characters.
Ÿ Only DBCS characters may appear in the literal (null strings are valid).

The maximum length of a DBCS literal is 80 DBCS characters, including the shift
control characters. (These counted together are equivalent in length to one DBCS
character.) The shift control characters are part of the literal, and take part in all
operations.

See “How to Continue DBCS Literals on a New Line” on page 339 for information
on how to extend DBCS literals.

How to Specify a DBCS/SBCS Literal: When you specify a DBCS/SBCS literal,


keep in mind the following:
Ÿ DBCS/SBCS literals can take many different forms. The following is only one
possible example:
"SINGLEðEK1K2K3ðFBYTES"
Ÿ USAGE DISPLAY must be either explicit or implicit.
Ÿ A quotation mark opens and closes the literal.
Ÿ EBCDIC characters can appear before or after any DBCS string in the mixed
literal.
Ÿ All DBCS strings appear between shift-out and shift-in characters.
Ÿ Double all SBCS quotation marks that occur within the literal. DBCS quotation
marks within the literal do not require doubling.
Ÿ You can use null DBCS strings (shift-out and shift-in characters without any
DBCS characters) only when the literal contains at least one SBCS character.

The shift-out and shift-in characters cannot be nested.

The shift control characters are part of the literal, and take part in all operations.

338 COBOL/400 User’s Guide


DBCS/SBCS literals cannot continue across lines. They are restricted to the space
of AREA B on one line.

Other Considerations

Quotation Marks: Although the preceding discussion uses the term a quotation
mark to describe the character that identifies a literal, the character actually used
can vary depending upon the option specified on the CRTCBLPGM CL command,
or on the PROCESS statement. If you specify the APOST option, an apostrophe
(') is used. Otherwise, a quotation mark (") is used. In this appendix, a quotation
mark refers to both an apostrophe and a quotation mark. The character that you
choose does not affect the rules for specifying a literal.

Shift Characters: The shift-out and shift-in characters separate EBCDIC characters
from DBCS characters. They are part of both the DBCS and the DBCS/SBCS
literal. Therefore, the shift code characters participate in all operations when they
appear in either DBCS or DBCS/SBCS literals.

How the COBOL Compiler Checks DBCS Characters


When the COBOL compiler finds a DBCS string, it checks the DBCS string by
scanning it one DBCS character at a time.

The following conditions cause the COBOL compiler to diagnose a literal containing
DBCS characters as not valid:
Ÿ The syntax for the literal is incorrect.
Ÿ The DBCS literal is longer than one line and does not follow the rules for con-
tinuing nonnumeric literals. (See “How to Continue DBCS Literals on a New
Line” for more information.)
Ÿ The DBCS/SBCS literal is longer than one line.

When the COBOL compiler finds a DBCS literal that is not valid, it generates an
error message, and then processes the literal as an alphanumeric literal.

For each DBCS or SBCS literal that is not valid, the compiler generates an error
message and accepts or ignores the literal.

How to Continue DBCS Literals on a New Line


To continue a DBCS literal onto another line of source code, do all of the following:
Ÿ Place a shift-in character in either column 71 or column 72 of the line to be
continued (If you put the shift-in character in column 71, the blank in column 72
is ignored)
Ÿ Place a hyphen (-) in column 7 (the continuation area) of the new line
Ÿ Place a quotation mark, then a shift-out character, and then the rest of the
literal in Area B of the new line.

For example:
-A 1 B
..
.
ð1 DBCS1 PIC X(12) VALUE "ðEK1K2K3ðF
- "ðEK4K5ðF".
..
.

Appendix F. Supporting International Languages with Double-Byte Character Sets 339


The value of DBCS1 is "0EK1K2K3K4K50F".

The shift-in character, quotation mark, and shift-out character used to continue a
line are not counted in the length of the DBCS literal. The first shift-out and final
shift-in characters are counted.

Where You Can Use DBCS Characters in a COBOL Program


In general, you can use DBCS, or DBCS/SBCS literals wherever nonnumeric
literals are allowed. Literals for the following, however, cannot include double-byte
characters:
Ÿ ALPHABET-NAME clause
Ÿ CURRENCY SIGN clause
Ÿ ASSIGN clause
Ÿ CLASS clause
Ÿ CALL statement
Ÿ CANCEL statement.
Note: You cannot use DBCS characters for COBOL words or names. See the
COBOL/400 Reference for information on rules for formatting COBOL
system-names, reserved words, and user-defined words such as data
names and file names.

How to Write Comments


You can write comments containing DBCS characters in a COBOL program by
putting an asterisk (*) or slash (/) in column seven of the program line. Either
symbol causes the compiler to treat any information following column seven as doc-
umentation. The slash also causes a page eject. Because the COBOL compiler
does not check the contents of comment lines, DBCS characters in comments are
not detected. DBCS characters that are not valid can cause the compiler listing to
print improperly.

Identification Division
You can put comment entries that contain DBCS characters in any portion of the
Identification Division except the PROGRAM-ID paragraph. The program name
specified in the PROGRAM-ID paragraph must be alphanumeric.

Environment Division

Configuration Section
You can use DBCS characters in comment entries only in the Configuration Section
paragraph. All function-names, mnemonic-names, condition-names, and alphabet-
names must be specified with alphanumeric characters. For the
SOURCE-COMPUTER and the OBJECT-COMPUTER entry, use the alphanumeric
computer name:

IBM-AS400

You cannot use DBCS or DBCS/SBCS literals in the Configuration Section.


Instead, use alphanumeric literals to define an alphabet-name and the literal in the
CURRENCY SIGN clause of the SPECIAL-NAMES paragraph. There is no DBCS
alphabet. Use the EBCDIC character set instead.

340 COBOL/400 User’s Guide


Input-Output Section
Specify all data names, file names, and assignment names using alphanumeric
characters. You can use DBCS characters in comments.

For indexed files, the data name in the RECORD KEY clause can refer to a DBCS
or DBCS/SBCS data item within a record. The number of fields in the record, plus
the number of positions occupied by the record key, together cannot be greater
than 120.
Note: Each DBCS character occupies two positions, and the shift control charac-
ters each occupy one position. Ensure that both the data description of the
key and the key position within the file match those specified when you
created the file.

You cannot use DBCS and DBCS/SBCS data as the RELATIVE KEY in relative
files.

File Control Paragraph


ASSIGN Clause: You cannot use literals containing DBCS characters in the
ASSIGN clause to specify an external medium such as a printer or a database.

Data Division

File Section
For the FD (File Description) Entry, you can use DBCS or DBCS/SBCS data items
or literals in the VALUE OF clause. The DATA RECORDS clause can refer to data
items only. Because the COBOL/400 compiler treats both the VALUE OF clause
and the DATA RECORDS clause in the File Section as documentation, neither
clause has any effect when you run the program. However, the COBOL compiler
checks all literals in the VALUE OF clause to make sure they are valid.

For magnetic tapes, the system can only read DBCS characters from, or write
DBCS characters to, the tape in the EBCDIC format. The system cannot perform
tape functions involving a tape in the ASCII format. Define the alphabet-name in
the CODE-SET clause as NATIVE. Use alphanumeric characters to specify the
alphabet-name.

Working-Storage Section
REDEFINES Clause: The existing rules for redefining data also apply to data that
contains DBCS characters. When you determine the length of a redefining or rede-
fined data item, remember that each DBCS character is twice as long as an alpha-
numeric character.

Also, ensure that redefined data items contain the shift control characters when and
where necessary.

OCCURS Clause: Use this clause to define tables for storing DBCS or
DBCS/SBCS data. If you specify the ASCENDING/DESCENDING KEY phrase,
COBOL assumes the contents of the table are in the EBCDIC program collating
sequence. The shift control characters in DBCS and DBCS/SBCS data take part in
the collating sequence.

For more information about handling tables that contain DBCS characters, see
“Table Handling–SEARCH Statement” on page 348.

Appendix F. Supporting International Languages with Double-Byte Character Sets 341


JUSTIFIED RIGHT Clause: Use the JUSTIFIED RIGHT clause to align DBCS or
DBCS/SBCS data at the rightmost position of an elementary receiving field. If the
receiving field is shorter than the sending field, COBOL truncates the rightmost
characters. If the receiving field is longer than the sending field, COBOL pads (fills)
the unused space on the left of the receiving field with blanks.

The JUSTIFIED clause does not affect the initial setting in the VALUE clause.

VALUE Clause: You can use DBCS or DBCS/SBCS literals to specify an initial
value for a data item that is not numeric, or to define values for level-88 condition-
name entries.

Any shift control characters in the literal are considered part of the literal’s picture
string, except when used to continue a new line. When you continue a DBCS
literal, the compiler does not include the shift-in character in column 71 or 72, or
the initial quotation mark (") and shift-out character on the continued line as part of
the DBCS literal. Make certain, however, that the DBCS literal does not exceed the
size of the data item specified in the PICTURE clause, otherwise truncation occurs.
Note: DBCS/SBCS mixed literals cannot be continued to a new line.

When you use literals that contain DBCS characters in the VALUE clause for
level-88 condition-name entries, COBOL treats the DBCS characters as alphanu-
meric. Therefore, follow the rules for specifying alphanumeric data, including
allowing a THROUGH option. This option uses the normal EBCDIC collating
sequence, but remember that shift control characters in DBCS and DBCS/SBCS
data take part in the collating sequence.

PICTURE Clause: Use the PICTURE symbol X to define DBCS and DBCS/SBCS
data items. Because DBCS characters are twice as long as alphanumeric, and are
enclosed within shift control characters, you would define a DBCS data item con-
taining n DBCS characters as
PICTURE X(2n+2)

A DBCS/SBCS data item containing m SBCS characters, and one string of n DBCS
characters would be defined as
PICTURE X(m+2n+2)

You can use all edited alphanumeric PICTURE symbols for DBCS and
DBCS/SBCS data items. The editing symbols have the same effect on the DBCS
data in these items as they do on alphanumeric data items. Check that you have
obtained the desired results.

RENAMES Clause: Use this clause to specify alternative groupings of elementary


data items. The existing rules for renaming alphanumeric data items also apply to
DBCS and DBCS/SBCS data items.

342 COBOL/400 User’s Guide


Procedure Division

Declaratives
An identifier in the USE FOR DEBUGGING sentence of the DECLARATIVES
section can refer to a DBCS or a DBCS/SBCS data item.

You cannot use DBCS characters for file names or procedure names in the USE
FOR DEBUGGING sentence.

Conditional Expressions
Because condition-names (level-88 entries) can refer to data items that contain
DBCS characters, you can use the condition-name condition to test this data. (See
“VALUE Clause” on page 342.) Follow the rules listed in the COBOL/400
Reference for using conditional variables and condition-names.

You can use DBCS or DBCS/SBCS data items or literals as the operands in a
relation condition. Because COBOL treats DBCS data as alphanumeric, all com-
parisons occur according to the rules for alphanumeric operands. Keep the fol-
lowing in mind:
Ÿ The system does not recognize the mixed content.
Ÿ The system uses the shift codes in comparisons of DBCS and DBCS/SBCS
data.
Ÿ The system compares the data using either the EBCDIC collating sequence, or
a user-defined sequence.
Ÿ In a comparison of DBCS or DBCS/SBCS items with similar items of unequal
size, the smaller item is padded on the right with EBCDIC spaces.

See “SPECIAL-NAMES Paragraph” section in the COBOL/400 Reference for more


information.

You can use class conditions and switch status conditions as described in the
COBOL/400 Reference.

Input/Output Statements
ACCEPT Statement: The input data received from a device by using a Format 1
ACCEPT statement can include DBCS or DBCS/SBCS data. All DBCS and
DBCS/SBCS data must be identified by the proper syntax. The input data,
including shift control characters, replaces the existing contents of the identifier.
COBOL does not perform editing or error checking on the data.

If you use the Format 3 ACCEPT statement to get OPEN-FEEDBACK information


about a file, that information includes a field showing whether the file has DBCS or
DBCS/SBCS data.

Information received from the local data area by a Format 4 ACCEPT statement
can include DBCS or DBCS/SBCS character strings. Information received replaces
the existing contents. COBOL does not perform any editing or checking for errors.
This also applies to information received from the PIP data area by a Format 5
ACCEPT statement.

Using the Format 6 ACCEPT statement, you can get the attributes of a work station
display and its keyboard. For display stations that can display DBCS characters,

Appendix F. Supporting International Languages with Double-Byte Character Sets 343


the system sets the appropriate value in the ATTRIBUTE-DATA data item. You
cannot use DBCS characters to name a device.

If you use an extended (Format 7) ACCEPT statement for field-level work station
input, you must ensure that DBCS data is not split across lines. COBOL does not
perform any editing or checking for errors.

DISPLAY Statement: You can specify DBCS or DBCS/SBCS data items or


literals in the DISPLAY statement. You can mix the types of data. DBCS and
DBCS/SBCS data, from either data items or literals, is sent as it appears to the
program device or local data area that is the target named on the DISPLAY state-
ment.

Because COBOL does not know the characteristics of the device on which data is
being displayed, you must make sure that the DBCS and DBCS/SBCS data is
| correct. It may be necessary to specify the extended display option
| *NOUNDSPCHAR (or the equivalent process statement parameter option) when the
| program is compiled, to ensure that a workstation can handle DBCS data correctly.
Note: ALL is a valid option for mixed literals.

If you use an extended (Format 3) DISPLAY statement for field-level work station
output, you must ensure that DBCS data is not split across lines.

READ Statement: You can use DBCS or DBCS/SBCS data items as the
RECORD KEY for an indexed file. See “Input-Output Section” on page 341 for
more information.

INTO Phrase: You can read a record into a DBCS or a DBCS/SBCS data item
using the INTO phrase. This phrase causes a MOVE statement (without the COR-
RESPONDING option) to be performed. The compiler moves DBCS and
DBCS/SBCS data in the same manner that it moves alphanumeric data. It does
not make sure that this data is valid.

REWRITE Statement: Use the FROM phrase of this statement to transfer DBCS
or DBCS/SBCS data from a DBCS or a DBCS/SBCS data item to an existing
record. The FROM phrase causes both types of data to be moved in the same
manner as the INTO phrase with the READ statement. (See “READ Statement.”)

START Statement: If you use DBCS characters in the key of an indexed file,
specify a corresponding data item in the KEY phrase of the START statement.

One of the following must be true:


Ÿ The data item must be the same as the data item specified in the RECORD
KEY clause of the FILE-CONTROL paragraph.
Ÿ The data item has the same first character as the record key and is not longer
than the record key.

You can specify valid operators (such as EQUAL, GREATER THAN, NOT LESS
THAN) in the KEY phrase. The system can follow either the EBCDIC or a user-
defined collating sequence.

344 COBOL/400 User’s Guide


WRITE Statement: Use the FROM phrase of this statement to write DBCS or
DBCS/SBCS data to a record. This phrase moves the data in the same manner as
the REWRITE statement. (See “REWRITE Statement.”)

You must include the shift control characters when you write the data into a device
file.

Data Manipulation Statements


Arithmetic Statements: Because COBOL treats DBCS characters in the same
manner that it treats alphanumeric characters, do not use DBCS characters in
numeric operations, nor manipulate them with arithmetic statements.

INSPECT Statement: You can use any DBCS or DBCS/SBCS data item as an
operand for the INSPECT statement. The system tallies and replaces on each half
of a DBCS character, including the shift control characters in these operations.
Therefore, the data may not be matched properly.

You can use any combination of double-byte character and alphanumeric operands
and double-byte character literals or data items. If you use the REPLACING
phrase, you might cause parts of the inspected item to be replaced by alphanu-
meric data, or vice versa.

You cannot replace a character string with a string of a different length. Consider
this when replacing alphanumeric characters with DBCS characters, or vice versa.

If you want to control the use of the INSPECT statement with items containing
DBCS characters, define data items containing shift control characters. Use the
shift-out and shift-in characters as BEFORE/AFTER operands in the INSPECT
statement.

The following example shows how you can use the INSPECT statement to replace
one DBCS character with another.
ð1 SUBJECT-ITEM PICTURE X(5ð).
ð1 DBCS-CHARACTERS VALUE "ðEK1K2ðF".
ð5 SHIFT-OUT PICTURE X.
ð5 DBCS-CHARACTER-1 PICTURE XX.
ð5 DBCS-CHARACTER-2 PICTURE XX.
ð5 SHIFT-IN PICTURE X.

The INSPECT statement would be coded as follows:


INSPECT SUBJECT-ITEM
REPLACING ALL DBCS-CHARACTER-1
BY DBCS-CHARACTER-2
AFTER INITIAL SHIFT-OUT.
Note: Using the AFTER INITIAL SHIFT-OUT phrase helps you to avoid the risk of
accidentally replacing two consecutive alphanumeric characters that have
the same EBCDIC values as DBCS-CHARACTER-1 (in cases where
SUBJECT-ITEM contains DBCS/SBCS data).

Appendix F. Supporting International Languages with Double-Byte Character Sets 345


You can also use the INSPECT statement to determine if a data item contains
DBCS characters, so that appropriate processing can occur. For example:
ð1 SUBJECT-FIELD PICTURE X(5ð).
ð1 TALLY-FIELD PICTURE 9(3) COMP.
ð1 SHIFTS VALUE "ðEðF".
ð5 SHIFT-OUT PICTURE X.
ð5 SHIFT-IN PICTURE X.

In the Procedure Division you might enter the following:


MOVE ZERO TO TALLY-FIELD.
INSPECT SUBJECT-FIELD TALLYING TALLY-FIELD
FOR ALL SHIFT-OUT.
IF TALLY-FIELD IS GREATER THAN ZERO THEN
PERFORM DBCS-PROCESSING
ELSE
PERFORM A-N-K-PROCESSING.

MOVE Statement: All DBCS characters are moved as alphanumeric character


strings. The system does not convert the data or examine it.

You can move DBCS/SBCS literals to group items and alphanumeric items.

If the length of the receiving field is different from that of the sending field, COBOL
does one of the following:
Ÿ Truncates characters from the sending item if it is longer than the receiving
item. This operation can reduce data integrity.
Ÿ Pads the sending item with blanks if it is shorter than the receiving item.

To understand more about the effect of editing symbols in the PICTURE clause of
the receiving data item, see the COBOL/400 Reference.

SET Statement (Condition-Name Format): When you set the condition name to
TRUE on this statement, COBOL moves the literal from the VALUE clause to the
associated data item. You can move a literal with DBCS characters.

STRING Statement: You can use the STRING statement to construct a data item
that contains DBCS or DBCS/SBCS subfields. All data in the source data items or
literals, including shift control characters, is moved to the receiving data item, one-
half of a DBCS character at a time.

UNSTRING Statement: The UNSTRING statement treats DBCS data and


DBCS/SBCS data the same as alphanumeric data. The UNSTRING operation is
performed on one-half of a DBCS character at a time.

Data items can contain both alphanumeric and DBCS characters within the same
field.

Use the DELIMITED BY phrase to locate double-byte and alphanumeric subfields


within a data field. Identify the data items containing shift control characters, and
use those data items as identifiers on the DELIMITED BY phrase. See the fol-
lowing examples for more information on how to do this. Use the POINTER vari-
able to continue scanning through subfields of the sending field.

346 COBOL/400 User’s Guide


After the system performs the UNSTRING operation, you can check the delimiters
stored by the DELIMITER IN phrases against the shift control character values to
see which subfields contain DBCS and which contain alphanumeric characters.

The following example shows how you might set up fields to prepare for the
unstring operation on a character string that contain DBCS/SBCS data:
ð1 SUBJECT-FIELD PICTURE X(4ð)
ð1 FILLER.
ð5 UNSTRING-TABLE OCCURS 4 TIMES.
1ð RECEIVER PICTURE X(4ð).
1ð DELIMTR PICTURE X.
1ð COUNTS PICTURE 99 COMP.
ð1 SHIFTS VALUE "ðEðF".
ð5 SHIFT-OUT PICTURE X.
ð5 SHIFT-IN PICTURE X.

Code the UNSTRING statement as follows:


UNSTRING SUBJECT-FIELD DELIMITED BY SHIFT-OUT
OR SHIFT-IN
INTO RECEIVER (1) DELIMITER IN DELIMTR (1)
COUNT IN COUNTS (1)
INTO RECEIVER (2) DELIMITER IN DELIMTR (2)
COUNT IN COUNTS (2)
INTO RECEIVER (3) DELIMITER IN DELIMTR (3)
COUNT IN COUNTS (3)
INTO RECEIVER (4) DELIMITER IN DELIMTR (4)
COUNT IN COUNTS (4)
ON OVERFLOW PERFORM UNSTRING-OVERFLOW-MESSAGE.

This UNSTRING statement divides a character string into its alphanumeric and
DBCS parts. Assuming that the data in the character string is valid, a delimiter
value of shift-out indicates that the corresponding receiving field contains alphanu-
meric data, while a value of shift-in indicates that corresponding receiving field has
DBCS data. You can check the COUNT data items to determine whether each
receiving field received any characters. The following figure is an example that
shows the results of the UNSTRING operation just described:
SUBJECT-FIELD = ABCðEK1K2K3ðFDðEK4K5K6ðF
RECEIVER (1) = ABC DELIMTR (1) = ðE COUNTS (1) = 3
RECEIVER (2) = K1K2K3 DELIMTR (2) = ðF COUNTS (2) = 6
RECEIVER (3) = D DELIMTR (3) = ðE COUNTS (3) = 1
RECEIVER (4) = K4K5K6 DELIMTR (4) = ðF COUNTS (4) = 6

SUBJECT-FIELD = ðEK1K2K3ðFABCðEK4ðF
RECEIVER (1) = (blanks) DELIMTR (1) = ðE COUNTS (1) = ð
RECEIVER (2) = K1K2K3 DELIMTR (2) = ðF COUNTS (2) = 6
RECEIVER (3) = ABC DELIMTR (3) = ðE COUNTS (3) = 3
RECEIVER (4) = K4 DELIMTR (4) = ðF COUNTS (4) = 2

Appendix F. Supporting International Languages with Double-Byte Character Sets 347


Procedure Branching Statements
You can use either a DBCS or a DBCS/SBCS literal as the operand for the STOP
statement. When you do, the system displays the literal as you entered it at your
work station for interactive jobs. For batch jobs, the system displays underscores
where the literal would normally appear on the system operator’s message queue.
The system does not edit or check the contents of the literal.

Table Handling–SEARCH Statement


You can perform a Format 1 SEARCH statement (sequential search of a table) on
a table that contains DBCS or DBCS/SBCS data half a DBCS character at a time.

You can also perform a Format 2 SEARCH statement (SEARCH ALL) against a
DBCS or DBCS/SBCS table as well. Order the table according to the chosen col-
lating sequence.
Note: The shift control characters in DBCS and DBCS/SBCS data participate in
the comparison.

SORT/MERGE
You cannot perform a DBCS alphabet sort using COBOL. However, you can use
DBCS or DBCS/SBCS data items as keys in a SORT or MERGE statement. The
sort operation orders data according to the collating sequence specified in the
SORT, MERGE, or SPECIAL NAMES paragraph. The system orders any shift
control characters contained in DBCS and DBCS/SBCS keys.

Use the RELEASE statement to transfer records containing DBCS characters from
an input/output area to the initial phase of a sort operation. The system performs
the FROM phrase with the RELEASE statement in the same way it performs the
FROM phrase with the WRITE statement. (See “WRITE Statement” on page 345.)

You can also use the RETURN statement to transfer records containing DBCS
characters from the final phase of a sort or merge operation to an input/output area.
The system performs the INTO phrase with the RETURN statement in the same
manner that it performs the INTO phrase with the READ statement. (See “READ
Statement” on page 344.)

Compiler-Directing Statements

COPY Statement
You can use the COPY statement to copy source text that contains DBCS charac-
ters into a COBOL program. When you do, make sure that you specify the
member name, file name, and library name using alphanumeric data, and that you
specify these names according to the rules stated in the COBOL/400 Reference.

Use the Format 2 COPY statement to copy fields defined in the data description
specifications (DDS). DBCS and DBCS/SBCS data items (the value in column 35
of the DDS form is O) are copied into a COBOL program in the PICTURE X(n)
format. The compiler listing does not indicate that these fields contain DBCS char-
acters, unless a field is a key field. In those cases, the system prints an O in the
comment table for keys.

DBCS-graphic data items are copied into a COBOL program in the PICTURE X(N)
format. The compiler listing indicates that these fields contain graphic data. See

348 COBOL/400 User’s Guide


“DBCS-Graphic Fields” on page 133 for a description of the DBCS-graphic data
type.

You can put DBCS characters in text comments that are copied from DDS if the
associated DDS field has comments.

If you specify the REPLACING phrase of the COPY statement, consider the fol-
lowing:
Ÿ Pseudo-text can contain any combination of DBCS and alphanumeric charac-
ters.
Ÿ You can use literals with DBCS or DBCS/SBCS content.
Ÿ Identifiers can refer to data items that contain DBCS characters.

TITLE Statement
You can use DBCS/SBCS literals as the literal in the TITLE statement.

Communications between Programs


You can specify entries for DBCS or DBCS/SBCS data items in the Linkage
Section of the Data Division.

You can pass DBCS characters from one program to another program by speci-
fying those data items in the USING phrase. You cannot use DBCS characters in
the CALL statement for the program-name of the called program.

You cannot use DBCS characters in the CANCEL statement because they specify
program-names.

FIPS Flagger
Enhancements to the COBOL language that let you use DBCS characters are
flagged (identified) by the FIPS (Federal Information Processing Standard) flagger
provided by the compiler as IBM extensions.

COBOL Program Listings


DBCS characters can appear in listings that originate from DBCS-capable source
files, and that are produced on DBCS-capable systems.

DBCS characters that appear in a program listing originate from the source file,
from source text generated by the COPY statement, or from COBOL compiler mes-
sages.

A listing containing DBCS characters should be output to a printer file that is


capable of processing DBCS data. Listings containing DBCS characters are
handled correctly if one of the following conditions is true:
Ÿ The printer file specified by the PRTFILE parameter of the CRTCBLPGM
command is defined with the required attribute, using the CRTPRTF or
CHGPRTF command.
Ÿ The source file is defined as capable of containing DBCS data using the
IGCDTA parameter of the CRTSRCPF command. In this case, the program
overrides the existing value of the attribute for the output printer file.

Appendix F. Supporting International Languages with Double-Byte Character Sets 349


Ÿ The user has specified the required attribute for the output printer, using the
IGCDTA parameter of the OVRPRTF command, before compiling the program.
Note: The IGCDTA parameter is only available on DBCS systems, and it cannot
be defined or displayed on non-DBCS systems. You can, however, create
objects with DBCS attributes on a non-DBCS system by copying them from
a DBCS system. You should check for possible incompatibilities if you do
this.

The compiler may use characters from your source program as substitution param-
eters in compiler and syntax checker messages. The system does not check or
edit the substitution parameters. If you do not specify DBCS characters properly,
the system may print or display parts of messages incorrectly.

End of IBM Extension

350 COBOL/400 User’s Guide


Appendix G. AS/400 File Processing Examples
This appendix contains sample programs that illustrate the fundamental program-
ming techniques associated with each type of AS/400 file organization. These
examples are intended to be used for planning purposes only, and to illustrate the
input/output statements necessary for certain access methods. Other COBOL fea-
tures (the use of the PERFORM statement, for example) are used only incidentally.
The programs illustrated are:
Ÿ Sequential File Creation
Ÿ Sequential File Updating and Extension
Ÿ Indexed File Creation
Ÿ Indexed File Updating
Ÿ Relative File Creation
Ÿ Relative File Updating
Ÿ Relative File Retrieval.

Sequential File Creation


This program creates a sequential file of employee salary records. The input
records are arranged in ascending order of employee number. The output file has
the identical order. (An output file is a file that is opened in either the output mode
or the extend mode.)

 Copyright IBM Corp. 1994 351


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. CRTSEQ.
ðððð3ð
3 ðððð4ð ENVIRONMENT DIVISION.
4 ðððð5ð CONFIGURATION SECTION.
5 ðððð6ð SOURCE-COMPUTER. IBM-AS4ðð. ð5/24/94
6 ðððð7ð OBJECT-COMPUTER. IBM-AS4ðð. ð5/24/94
7 ðððð8ð SPECIAL-NAMES. CONSOLE IS TYPEWRITER.
8 ðððð9ð INPUT-OUTPUT SECTION.
9 ððð1ðð FILE-CONTROL.
1ð ððð11ð SELECT INPUT-FILE ASSIGN TO DISK-FILEA
11 ððð12ð FILE STATUS IS INPUT-FILE-STATUS.
12 ððð13ð SELECT OUTPUT-FILE ASSIGN TO DISK-FILEB
13 ððð14ð FILE STATUS IS OUTPUT-FILE-STATUS.
14 ððð15ð DATA DIVISION.
15 ððð16ð FILE SECTION.
16 ððð17ð FD INPUT-FILE LABEL RECORDS STANDARD.
17 ððð18ð ð1 INPUT-RECORD.
18 ððð19ð ð5 INPUT-EMPLOYEE-NUMBER PICTURE 9(6).
19 ððð2ðð ð5 INPUT-EMPLOYEE-NAME PICTURE X(28).
2ð ððð21ð ð5 INPUT-EMPLOYEE-CODE PICTURE 9.
21 ððð22ð ð5 INPUT-EMPLOYEE-SALARY PICTURE 9(6)V99.
22 ððð23ð FD OUTPUT-FILE LABEL RECORDS STANDARD.
23 ððð24ð ð1 OUTPUT-RECORD.
24 ððð25ð ð5 OUTPUT-EMPLOYEE-NUMBER PICTURE 9(6).
25 ððð26ð ð5 OUTPUT-EMPLOYEE-NAME PICTURE X(28).
26 ððð27ð ð5 OUTPUT-EMPLOYEE-CODE PICTURE 9.
27 ððð28ð ð5 OUTPUT-EMPLOYEE-SALARY PICTURE 9(6)V99.
28 ððð29ð WORKING-STORAGE SECTION.
29 ððð3ðð 77 INPUT-FILE-STATUS PICTURE XX.
3ð ððð31ð 77 OUTPUT-FILE-STATUS PICTURE XX.
31 ððð32ð ð1 INPUTEND PICTURE X VALUE SPACE.
32 ððð33ð 88 THE-END-OF-INPUT VALUE "E".
33 ððð34ð ð1 DISP-RECORD.
34 ððð35ð ð5 OP-NAME PICTURE X(7).
35 ððð36ð ð5 FILLER PICTURE XX VALUE SPACE.
36 ððð37ð ð5 FILE-NAME PICTURE X(11).
37 ððð38ð ð5 FILLER PICTURE XX VALUE SPACE.
38 ððð39ð ð5 FILLER PICTURE X(14)
39 ððð4ðð VALUE "FILE STATUS IS".
4ð ððð41ð ð5 FILLER PICTURE XX VALUE SPACE.
41 ððð42ð ð5 SK PICTURE XX.
42 ððð43ð PROCEDURE DIVISION.
ððð44ð DECLARATIVES.
ððð45ð I-O-ERROR SECTION.
ððð46ð USE AFTER STANDARD ERROR PROCEDURE ON INPUT-FILE,
ððð47ð OUTPUT-FILE.
ððð48ð I-O-ERROR-PARA.
ððð49ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð5ðð\ DUMMY DECLARATIVES TO ENSURE CONTROL IS RETURNED TO THIS \
ððð51ð\ PROGRAM WHEN AN ERROR OCCURS DURING FILE PROCESSING. \
ððð52ð\ ERROR HANDLING IS DONE AFTER EACH I/O STATEMENT. \
ððð53ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ððð54ð END DECLARATIVES.
ððð55ð MAIN-PROGRAM SECTION.
ððð56ð OPEN-FILES.
43 ððð57ð OPEN INPUT INPUT-FILE
ððð58ð OUTPUT OUTPUT-FILE.
44 ððð59ð IF INPUT-FILE-STATUS NOT = "ðð"
45 ððð6ðð MOVE "OPEN" TO OP-NAME
46 ððð61ð MOVE "INPUT-FILE" TO FILE-NAME
47 ððð62ð MOVE INPUT-FILE-STATUS TO SK
48 ððð63ð PERFORM ERROR-OUT-1 THROUGH ERROR-OUT-2.
49 ððð64ð IF OUTPUT-FILE-STATUS NOT = "ðð"
5ð ððð65ð MOVE "OPEN" TO OP-NAME
51 ððð66ð MOVE "OUTPUT-FILE" TO FILE-NAME
52 ððð67ð MOVE OUTPUT-FILE-STATUS TO SK
53 ððð68ð PERFORM ERROR-OUT-1 THROUGH ERROR-OUT-2.
54 ððð69ð PERFORM BUILD-FILE UNTIL THE-END-OF-INPUT.
ððð7ðð CLOSE-FILES.
55 ððð71ð CLOSE INPUT-FILE
ððð72ð OUTPUT-FILE.
56 ððð73ð STOP RUN.
ððð74ð BUILD-FILE.

Figure 112 (Part 1 of 2). Example of a Sequential File of Employee Salary Records

352 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
57 ððð75ð READ INPUT-FILE INTO OUTPUT-RECORD
58 ððð76ð AT END SET THE-END-OF-INPUT TO TRUE.
59 ððð77ð IF INPUT-FILE-STATUS NOT = "ðð"
6ð ððð78ð MOVE "WRITE" TO OP-NAME
61 ððð79ð MOVE "OUTPUT-FILE" TO FILE-NAME
62 ððð8ðð MOVE OUTPUT-FILE-STATUS TO SK
63 ððð81ð PERFORM ERROR-OUT-1 THROUGH ERROR-OUT-2
64 ððð82ð GO TO CLOSE-FILES.
65 ððð83ð WRITE OUTPUT-RECORD.
66 ððð84ð IF OUTPUT-FILE-STATUS NOT = "ðð"
67 ððð85ð MOVE "WRITE" TO OP-NAME
68 ððð86ð MOVE "OUTPUT-FILE" TO FILE-NAME
69 ððð87ð MOVE OUTPUT-FILE-STATUS TO SK
7ð ððð88ð PERFORM ERROR-OUT-1 THROUGH ERROR-OUT-2
71 ððð89ð GO TO CLOSE-FILES.
ððð9ðð ERROR-OUT-1.
72 ððð91ð DISPLAY "FILE PROCESSING ERROR" UPON TYPEWRITER.
73 ððð92ð DISPLAY DISP-RECORD UPON TYPEWRITER.
74 ððð93ð CLOSE INPUT-FILE
ððð94ð OUTPUT-FILE.
75 ððð95ð STOP RUN.
ððð96ð ERROR-OUT-2.
ððð97ð EXIT.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 16 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð17ð
Message . . . . : Blocking/Deblocking for file 'INPUT-FILE'
will be performed by compiler-generated code.
\ 22 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð23ð
Message . . . . : Blocking/Deblocking for file 'OUTPUT-FILE'
will be performed by compiler-generated code.
\ 43 MSGID: LBLð335 SEVERITY: ðð SEQNBR: ððð54ð
Message . . . . : Empty paragraph or section precedes 'END
DECLARATIVES' paragraph or section.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
3 3 ð ð ð ð
Source records read . . . . . . . . : 97
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program CRTSEQ created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 112 (Part 2 of 2). Example of a Sequential File of Employee Salary Records

Sequential File Updating and Extension


This program updates and extends the file created by the CRTSEQ program. The
INPUT-FILE and the MASTER-FILE are each read. When a match is found between
INPUT-EMPLOYEE-NUMBER and MST-EMPLOYEE-NUMBER, the input record replaces the
original record. After the MASTER-FILE is processed, new employee records are
added to the end of the file.

Appendix G. File Processing Examples 353


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. UPDTSEQ.
3 ðððð3ð ENVIRONMENT DIVISION.
4 ðððð4ð CONFIGURATION SECTION.
5 ðððð5ð SOURCE-COMPUTER. IBM-AS4ðð. ð5/24/94
6 ðððð6ð OBJECT-COMPUTER. IBM-AS4ðð. ð5/24/94
7 ðððð7ð INPUT-OUTPUT SECTION.
8 ðððð8ð FILE-CONTROL.
9 ðððð9ð SELECT INPUT-FILE ASSIGN TO DISK-FILES
1ð ððð1ðð FILE STATUS IS INPUT-FILE-STATUS. .A/
11 ððð11ð SELECT MASTER-FILE ASSIGN TO DISK-MSTFILEB
12 ððð12ð FILE STATUS IS MASTER-FILE-STATUS. .B/
ððð13ð
13 ððð14ð DATA DIVISION.
14 ððð15ð FILE SECTION.
15 ððð16ð FD INPUT-FILE LABEL RECORDS STANDARD.
16 ððð17ð ð1 INPUT-RECORD.
17 ððð18ð ð5 INPUT-EMPLOYEE-NUMBER PICTURE 9(6).
18 ððð19ð ð5 INPUT-EMPLOYEE-NAME PICTURE X(28).
19 ððð2ðð ð5 INPUT-EMPLOYEE-CODE PICTURE 9.
2ð ððð21ð ð5 INPUT-EMPLOYEE-SALARY PICTURE 9(6)V99.
21 ððð22ð FD MASTER-FILE LABEL RECORDS STANDARD.
22 ððð23ð ð1 MASTER-RECORD.
23 ððð24ð ð5 MST-EMPLOYEE-NUMBER PICTURE 9(6).
24 ððð25ð ð5 MST-EMPLOYEE-NAME PICTURE X(28).
25 ððð26ð ð5 MST-EMPLOYEE-CODE PICTURE 9.
26 ððð27ð ð5 MST-EMPLOYEE-SALARY PICTURE 9(6)V99.
27 ððð28ð WORKING-STORAGE SECTION.
28 ððð29ð 77 INPUT-FILE-STATUS PICTURE XX.
29 ððð3ðð 77 MASTER-FILE-STATUS PICTURE XX.
3ð ððð31ð ð1 INPUTEND PICTURE X VALUE SPACE.
31 ððð32ð 88 THE-END-OF-INPUT VALUE "E".
32 ððð33ð ð1 MASTEREND PICTURE X VALUE SPACE.
33 ððð34ð 88 THE-END-OF-MASTER VALUE "E".
34 ððð35ð ð1 ERROR-INFO.
35 ððð36ð ð5 OP-NAME PICTURE X(12).
36 ððð37ð ð5 FILLER PICTURE XX VALUE SPACE.
37 ððð38ð ð5 FILE-NAME PICTURE X(11).
38 ððð39ð ð5 FILLER PICTURE XX VALUE SPACE.
39 ððð4ðð ð5 FILLER PICTURE X(14)
4ð ððð41ð VALUE "FILE STATUS IS".
41 ððð42ð ð5 FILLER PICTURE XX VALUE SPACE.
42 ððð43ð ð5 SK PICTURE XX.
43 ððð44ð PROCEDURE DIVISION.
ððð45ð DECLARATIVES.
ððð46ð INPUT-FILE-ERROR SECTION.
ððð47ð USE AFTER STANDARD ERROR PROCEDURE ON INPUT-FILE. .C/
ððð48ð INPUT-FILE-ERROR-PARA.
44 ððð49ð MOVE INPUT-FILE-STATUS TO SK.
45 ððð5ðð MOVE "INPUT-FILE" TO FILE-NAME.
46 ððð51ð DISPLAY "FILE PROCESSING ERROR".
47 ððð52ð DISPLAY ERROR-INFO.
48 ððð53ð DISPLAY "PROCESSING TERMINATED DUE TO I-O ERROR".
49 ððð54ð STOP RUN.
ððð55ð I-O-FILE-ERROR SECTION.
ððð56ð USE AFTER STANDARD ERROR PROCEDURE ON MASTER-FILE. .D/
ððð57ð MASTER-FILE-ERROR-PARA.
5ð ððð58ð MOVE MASTER-FILE-STATUS TO SK.
51 ððð59ð MOVE "MASTER-FILE" TO FILE-NAME.
52 ððð6ðð DISPLAY "FILE PROCESSING ERROR".
53 ððð61ð DISPLAY ERROR-INFO.
54 ððð62ð DISPLAY "PROCESSING TERMINATED DUE TO I-O ERROR".
55 ððð63ð STOP RUN.
ððð64ð END DECLARATIVES.
ððð65ð MAIN-PROGRAM SECTION.
ððð66ð OPEN-FILES.
56 ððð67ð MOVE "OPEN" TO OP-NAME.
57 ððð68ð OPEN INPUT INPUT-FILE
ððð69ð I-O MASTER-FILE.
ððð7ðð PROCESSING-LOGIC.
58 ððð71ð PERFORM READ-INPUT-FILE.
59 ððð72ð PERFORM READ-MASTER-FILE.
6ð ððð73ð PERFORM PROCESS-FILES UNTIL THE-END-OF-INPUT.

Figure 113 (Part 1 of 2). Example of a Sequential File Update Program

354 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ððð74ð CLOSE-FILES.
61 ððð75ð MOVE "CLOSE" TO OP-NAME.
62 ððð76ð CLOSE MASTER-FILE
ððð77ð INPUT-FILE.
63 ððð78ð STOP RUN.
ððð79ð READ-INPUT-FILE.
64 ððð8ðð MOVE "READ" TO OP-NAME.
65 ððð81ð READ INPUT-FILE
66 ððð82ð AT END SET THE-END-OF-INPUT TO TRUE.
ððð83ð READ-MASTER-FILE.
67 ððð84ð MOVE "READ" TO OP-NAME.
68 ððð85ð READ MASTER-FILE
ððð86ð AT END
69 ððð87ð SET THE-END-OF-MASTER TO TRUE
7ð ððð88ð MOVE "AT END CLOSE" TO OP-NAME
71 ððð89ð CLOSE MASTER-FILE
72 ððð9ðð MOVE "OPEN EXTEND" TO OP-NAME
73 ððð91ð OPEN EXTEND MASTER-FILE.
ððð92ð PROCESS-FILES.
74 ððð93ð IF THE-END-OF-MASTER
75 ððð94ð WRITE MASTER-RECORD FROM INPUT-RECORD
76 ððð95ð PERFORM READ-INPUT-FILE
ððð96ð ELSE
77 ððð97ð IF MST-EMPLOYEE-NUMBER LESS THAN INPUT-EMPLOYEE-NUMBER
78 ððð98ð PERFORM READ-MASTER-FILE
ððð99ð ELSE
79 ðð1ððð IF MST-EMPLOYEE-NUMBER = INPUT-EMPLOYEE-NUMBER
8ð ðð1ð1ð MOVE "REWRITE" TO OP-NAME
81 ðð1ð2ð REWRITE MASTER-RECORD FROM INPUT-RECORD
82 ðð1ð3ð PERFORM READ-INPUT-FILE
83 ðð1ð4ð PERFORM READ-MASTER-FILE
ðð1ð5ð ELSE
84 ðð1ð6ð DISPLAY "ERROR RECORD -> ", INPUT-EMPLOYEE-NUMBER
85 ðð1ð7ð PERFORM READ-INPUT-FILE.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 15 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð16ð
Message . . . . : Blocking/Deblocking for file 'INPUT-FILE'
will be performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 1 ð ð ð ð
Source records read . . . . . . . . : 1ð7
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program UPDTSEQ created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 113 (Part 2 of 2). Example of a Sequential File Update Program

The example in Figure 113 on page 354 includes:


.A/ A FILE STATUS clause so that the program records the status of the most
recent I/O request involving INPUT-FILE.
.B/ A FILE STATUS clause so that the program records the status of the most
recent I/O request involving MASTER-FILE.
.C/ A USE procedure that is run when an I/O error occurs during the proc-
essing of INPUT-FILE.
.D/ A USE procedure that is run when an I/O error occurs during the proc-
essing of MASTER-FILE.

File status values and USE procedures play important roles in error handling. For
more information, see Chapter 6, “COBOL/400 Exception and Error Handling.”

Appendix G. File Processing Examples 355


Indexed File Creation
An indexed file is a file that records the key and the position of each record in a
separate part of the file called an index.

This program creates an indexed file of summary records for bank depositors. The
key within each indexed file record is INDEX-KEY (the depositor’s account
number); the input records are ordered in ascending sequence upon this key.
Records are read from the input file and transferred to the indexed file record area.
The indexed file record is then written.

5763CB1 V3RðM5 AS/4ðð COBOL Source


STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. CRTIND.
ðððð3ð
3 ðððð4ð ENVIRONMENT DIVISION.
4 ðððð5ð CONFIGURATION SECTION.
5 ðððð6ð SOURCE-COMPUTER. IBM-AS4ðð. ð5/24/94
6 ðððð7ð OBJECT-COMPUTER. IBM-AS4ðð. ð5/24/94
7 ðððð8ð INPUT-OUTPUT SECTION.
8 ðððð9ð FILE-CONTROL.
9 ððð1ðð SELECT INDEXED-FILE ASSIGN TO DISK-INDEXFILE
1ð ððð11ð ORGANIZATION IS INDEXED
11 ððð12ð ACCESS IS SEQUENTIAL
12 ððð13ð RECORD KEY IS INDEX-KEY
13 ððð14ð FILE STATUS IS INDEXED-FILE-STATUS.
14 ððð15ð SELECT INPUT-FILE ASSIGN TO DISK-FILEG
15 ððð16ð FILE STATUS IS INPUT-FILE-STATUS.
16 ððð17ð DATA DIVISION.
17 ððð18ð FILE SECTION.
18 ððð19ð FD INDEXED-FILE LABEL RECORDS STANDARD.
19 ððð2ðð ð1 INDEX-RECORD.
2ð ððð21ð ð5 INDEX-KEY PICTURE X(1ð).
21 ððð22ð ð5 INDEX-FLD1 PICTURE X(1ð).
22 ððð23ð ð5 INDEX-NAME PICTURE X(2ð).
23 ððð24ð ð5 INDEX-BAL PICTURE S9(5)V99.
24 ððð25ð FD INPUT-FILE LABEL RECORDS STANDARD.
25 ððð26ð ð1 INPUT-RECORD.
26 ððð27ð ð5 INPUT-KEY PICTURE X(1ð).
27 ððð28ð ð5 INPUT-NAME PICTURE X(2ð).
28 ððð29ð ð5 INPUT-BAL PICTURE S9(5)V99.
29 ððð3ðð WORKING-STORAGE SECTION.
3ð ððð31ð 77 INDEXED-FILE-STATUS PICTURE XX.
31 ððð32ð 77 INPUT-FILE-STATUS PICTURE XX.
32 ððð33ð 77 OP-NAME PICTURE X(7).
33 ððð34ð ð1 INPUTEND PICTURE X VALUE SPACES.
34 ððð35ð 88 THE-END-OF-INPUT VALUE "E".
35 ððð36ð ð1 ERRORFLAG PICTURE X VALUE SPACES.
36 ððð37ð 88 ERROR-OCCURRED VALUE "1".
37 ððð38ð PROCEDURE DIVISION.
ððð39ð DECLARATIVES.
ððð4ðð INPUT-ERROR SECTION.
ððð41ð USE AFTER STANDARD ERROR PROCEDURE ON INPUT.
ððð42ð INPUT-ERROR-PARA.
38 ððð43ð DISPLAY "UNEXPECTED ERROR ON ", OP-NAME, " FOR INPUT-FILE ".
39 ððð44ð DISPLAY "FILE STATUS IS ", INPUT-FILE-STATUS.
4ð ððð45ð SET ERROR-OCCURRED TO TRUE.
ððð46ð OUTPUT-ERROR SECTION.
ððð47ð USE AFTER STANDARD ERROR PROCEDURE ON OUTPUT.
ððð48ð OUTPUT-ERROR-PARA.
41 ððð49ð DISPLAY "UNEXPECTED ERROR ON ", OP-NAME, " FOR INDEXED-FILE ".
42 ððð5ðð DISPLAY "FILE STATUS IS ", INDEXED-FILE-STATUS.
43 ððð51ð SET ERROR-OCCURRED TO TRUE.
ððð52ð END DECLARATIVES.
ððð53ð MAIN-PROCESSING SECTION.
ððð54ð MAIN-PROCEDURE.
44 ððð55ð MOVE "OPEN" TO OP-NAME.
45 ððð56ð OPEN INPUT INPUT-FILE
ððð57ð OUTPUT INDEXED-FILE.
46 ððð58ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
48 ððð59ð PERFORM READ-INPUT-FILE.
49 ððð6ðð PERFORM LOAD-INDEXED-FILE THRU READ-INPUT-FILE
ððð61ð UNTIL THE-END-OF-INPUT.

Figure 114 (Part 1 of 2). Example of an Indexed File Program

356 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
5ð ððð62ð MOVE "CLOSE" TO OP-NAME.
51 ððð63ð CLOSE INPUT-FILE
ððð64ð INDEXED-FILE.
52 ððð65ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
54 ððð66ð STOP RUN.
ððð67ð LOAD-INDEXED-FILE.
55 ððð68ð MOVE INPUT-KEY TO INDEX-KEY.
56 ððð69ð MOVE INPUT-NAME TO INDEX-NAME.
57 ððð7ðð MOVE INPUT-BAL TO INDEX-BAL.
58 ððð71ð MOVE SPACES TO INDEX-FLD1.
59 ððð72ð MOVE "WRITE" TO OP-NAME.
6ð ððð73ð WRITE INDEX-RECORD
ððð74ð INVALID KEY
61 ððð75ð DISPLAY "WRITE FAILED FOR KEY ", INDEX-KEY.
62 ððð76ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
ððð77ð READ-INPUT-FILE.
64 ððð78ð MOVE "READ" TO OP-NAME.
65 ððð79ð READ INPUT-FILE
66 ððð8ðð AT END SET THE-END-OF-INPUT TO TRUE.
67 ððð81ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
ððð82ð ERROR-TERMINATION.
69 ððð83ð DISPLAY "I-O ERROR OCCURRED - PROCESS TERMINATING".
7ð ððð84ð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 18 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð19ð
Message . . . . : Blocking/Deblocking for file 'INDEXED-FILE'
will be performed by compiler-generated code.
\ 24 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð25ð
Message . . . . : Blocking/Deblocking for file 'INPUT-FILE'
will be performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
2 2 ð ð ð ð
Source records read . . . . . . . . : 84
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program CRTIND created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 114 (Part 2 of 2). Example of an Indexed File Program

Indexed File Updating


This program updates the indexed file created in the CRTIND program, using
dynamic access.

The input records contain the key for the record, the depositor name, and the
amount of the transaction.

When the input record is read, the program tests for:


Ÿ If this is a transaction record (in which case, all fields of the record are filled)
Ÿ If this is a record requesting sequential retrieval of a specific generic class (in
which case, only the INPUT-GEN-FLD field of the input record contains data).

Random access is used for the updating and printing of the transaction records.
Sequential access is used for the retrieval and printing of all records within one
generic class.

Appendix G. File Processing Examples 357


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. UPDTIND.
ðððð3ð
3 ðððð4ð ENVIRONMENT DIVISION.
4 ðððð5ð CONFIGURATION SECTION.
5 ðððð6ð SOURCE-COMPUTER. IBM-AS4ðð. ð5/24/94
6 ðððð7ð OBJECT-COMPUTER. IBM-AS4ðð. ð5/24/94
7 ðððð8ð INPUT-OUTPUT SECTION.
8 ðððð9ð FILE-CONTROL.
9 ððð1ðð SELECT MASTER-FILE ASSIGN TO DISK-INDXFILE
1ð ððð11ð ORGANIZATION IS INDEXED
11 ððð12ð ACCESS IS DYNAMIC
12 ððð13ð RECORD KEY IS MASTER-KEY
13 ððð14ð FILE STATUS IS MASTER-FILE-STATUS.
14 ððð15ð SELECT INPUT-FILE ASSIGN TO DISK-FILEH
15 ððð16ð FILE STATUS IS INPUT-FILE-STATUS.
16 ððð17ð SELECT PRINT-FILE ASSIGN TO PRINTER-QSYSPRT
17 ððð18ð FILE STATUS IS PRINT-FILE-STATUS.
18 ððð19ð DATA DIVISION.
19 ððð2ðð FILE SECTION.
2ð ððð21ð FD MASTER-FILE LABEL RECORDS STANDARD.
21 ððð22ð ð1 MASTER-RECORD.
22 ððð23ð ð5 MASTER-KEY.
23 ððð24ð 1ð MASTER-GEN-FLD PICTURE X(5).
24 ððð25ð 1ð MASTER-DET-FLD PICTURE X(5).
25 ððð26ð ð5 MASTER-FLD1 PICTURE X(1ð).
26 ððð27ð ð5 MASTER-NAME PICTURE X(2ð).
27 ððð28ð ð5 MASTER-BAL PICTURE S9(5)V99.
28 ððð29ð FD INPUT-FILE LABEL RECORDS STANDARD.
29 ððð3ðð ð1 INPUT-REC.
3ð ððð31ð ð5 INPUT-KEY.
31 ððð32ð 1ð INPUT-GEN-FLD PICTURE X(5).
32 ððð33ð 1ð INPUT-DET-FLD PICTURE X(5).
33 ððð34ð ð5 INPUT-NAME PICTURE X(2ð).
34 ððð35ð ð5 INPUT-AMT PICTURE S9(5)V99.
35 ððð36ð FD PRINT-FILE LABEL RECORDS OMITTED
36 ððð37ð LINAGE 12 LINES FOOTING AT 9.
37 ððð38ð ð1 PRINT-RECORD-1.
38 ððð39ð ð5 PRINT-KEY PICTURE X(1ð).
39 ððð4ðð ð5 FILLER PICTURE X(5).
4ð ððð41ð ð5 PRINT-NAME PICTURE X(2ð).
41 ððð42ð ð5 FILLER PICTURE X(5).
42 ððð43ð ð5 PRINT-BAL PICTURE $$$,$$9.99-.
43 ððð44ð ð5 FILLER PICTURE X(7).
44 ððð45ð ð5 PRINT-AMT PICTURE $$$,$$9.99-.
45 ððð46ð ð5 FILLER PICTURE X(5).
46 ððð47ð ð5 PRINT-NEW-BAL PICTURE $$$,$$9.99-.
47 ððð48ð ð1 PRINT-RECORD-2 PICTURE X(89).
48 ððð49ð WORKING-STORAGE SECTION.
49 ððð5ðð 77 MASTER-FILE-STATUS PICTURE XX.
5ð ððð51ð 77 INPUT-FILE-STATUS PICTURE XX.
51 ððð52ð 77 PRINT-FILE-STATUS PICTURE XX.
52 ððð53ð 77 LINES-TO-FOOT PICTURE 99.
53 ððð54ð ð1 PAGE-HEAD.
54 ððð55ð ð5 FILLER PICTURE X(38) VALUE SPACES.
55 ððð56ð ð5 FILLER PICTURE X(13) VALUE "UPDATE REPORT".
56 ððð57ð ð5 FILLER PICTURE X(38) VALUE SPACES.
57 ððð58ð ð1 COLUMN-HEAD.
58 ððð59ð ð5 FILLER PICTURE X(6) VALUE "KEY ID".
59 ððð6ðð ð5 FILLER PICTURE X(9) VALUE SPACES.
6ð ððð61ð ð5 FILLER PICTURE X(4) VALUE "NAME".
61 ððð62ð ð5 FILLER PICTURE X(21) VALUE SPACES.
62 ððð63ð ð5 FILLER PICTURE X(11) VALUE "CUR BALANCE".
63 ððð64ð ð5 FILLER PICTURE X(6) VALUE SPACES.
64 ððð65ð ð5 FILLER PICTURE X(13) VALUE "UPDATE AMOUNT".
65 ððð66ð ð5 FILLER PICTURE X(4) VALUE SPACES.
66 ððð67ð ð5 FILLER PICTURE X(11) VALUE "NEW BALANCE".
67 ððð68ð ð5 FILLER PICTURE X(4) VALUE SPACES.
68 ððð69ð ð1 PAGE-FOOT.
69 ððð7ðð ð5 FILLER PICTURE X(81) VALUE SPACES.
7ð ððð71ð ð5 FILLER PICTURE A(6) VALUE "PAGE ".
71 ððð72ð ð5 PG-NUMBER PICTURE 99 VALUE ðð.
ððð73ð
72 ððð74ð ð1 INPUTEND PICTURE X VALUE SPACE.
73 ððð75ð 88 THE-END-OF-INPUT VALUE "E".

Figure 115 (Part 1 of 4). Example of an Indexed File Update Program

358 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
74 ððð76ð ð1 ERRORFLAG PICTURE X VALUE SPACE.
75 ððð77ð 88 ERROR-OCCURRED VALUE "1".
76 ððð78ð ð1 ERROR-DATA.
77 ððð79ð ð5 FILLER PICTURE X(21)
78 ððð8ðð VALUE "STATEMENT FAILING IS ".
79 ððð81ð ð5 OP-NAME PICTURE X(9).
8ð ððð82ð ð5 FILLER PICTURE X(16)
81 ððð83ð VALUE "FILE STATUS IS".
82 ððð84ð ð5 STATUS-VALUE PICTURE XX.
83 ððð85ð ð1 INPUT-MESSAGE.
84 ððð86ð ð5 FILLER PICTURE X(3ð)
85 ððð87ð VALUE "UNEXPECTED ERROR ON INPUT-FILE" .
86 ððð88ð ð1 I-O-MESSAGE.
87 ððð89ð ð5 FILLER PICTURE X(31)
88 ððð9ðð VALUE "UNEXPECTED ERROR ON MASTER-FILE" .
89 ððð91ð ð1 OUTPUT-MESSAGE.
9ð ððð92ð ð5 FILLER PICTURE X(3ð)
91 ððð93ð VALUE "UNEXPECTED ERROR ON PRINT-FILE" .
92 ððð94ð PROCEDURE DIVISION.
ððð95ð DECLARATIVES.
ððð96ð INPUT-ERROR SECTION.
ððð97ð USE AFTER STANDARD ERROR PROCEDURE ON INPUT.
ððð98ð INPUT-ERROR-PARA.
93 ððð99ð DISPLAY INPUT-MESSAGE.
94 ðð1ððð MOVE INPUT-FILE-STATUS TO STATUS-VALUE.
95 ðð1ð1ð DISPLAY ERROR-DATA.
96 ðð1ð2ð SET ERROR-OCCURRED TO TRUE.
ðð1ð3ð I-O-ERROR SECTION.
ðð1ð4ð USE AFTER STANDARD ERROR PROCEDURE ON I-O.
ðð1ð5ð I-O-ERROR-PARA.
97 ðð1ð6ð DISPLAY I-O-MESSAGE.
98 ðð1ð7ð MOVE MASTER-FILE-STATUS TO STATUS-VALUE.
99 ðð1ð8ð DISPLAY ERROR-DATA.
1ðð ðð1ð9ð SET ERROR-OCCURRED TO TRUE.
ðð11ðð OUTPUT-ERROR SECTION.
ðð111ð USE AFTER STANDARD ERROR PROCEDURE ON OUTPUT.
ðð112ð OUTPUT-ERROR-PARA.
1ð1 ðð113ð DISPLAY OUTPUT-MESSAGE.
1ð2 ðð114ð MOVE PRINT-FILE-STATUS TO STATUS-VALUE.
1ð3 ðð115ð DISPLAY ERROR-DATA.
1ð4 ðð116ð SET ERROR-OCCURRED TO TRUE.
ðð117ð END DECLARATIVES.
ðð118ð MAIN-PROCESSING SECTION.
ðð119ð MAIN-PROCEDURE.
1ð5 ðð12ðð MOVE "OPEN" TO OP-NAME.
1ð6 ðð121ð OPEN INPUT INPUT-FILE
ðð122ð I-O MASTER-FILE
ðð123ð OUTPUT PRINT-FILE.
1ð7 ðð124ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
1ð9 ðð125ð PERFORM PAGE-START.
11ð ðð126ð PERFORM READ-INPUT-FILE.
111 ðð127ð PERFORM PROCESS-DATA THRU READ-INPUT-FILE
ðð128ð UNTIL THE-END-OF-INPUT.
112 ðð129ð PERFORM PAGE-END.
113 ðð13ðð MOVE "CLOSE" TO OP-NAME.
114 ðð131ð CLOSE INPUT-FILE
ðð132ð MASTER-FILE
ðð133ð PRINT-FILE.
115 ðð134ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
117 ðð135ð STOP RUN.
ðð136ð
ðð137ð PROCESS-DATA.
118 ðð138ð IF INPUT-DET-FLD EQUAL SPACES
119 ðð139ð PERFORM INIT-SEQUENTIAL-PROCESS
ðð14ðð ELSE
12ð ðð141ð PERFORM DYNAMIC-PROCESS.
ðð142ð READ-INPUT-FILE.
121 ðð143ð MOVE "READ" TO OP-NAME.
122 ðð144ð READ INPUT-FILE
123 ðð145ð AT END SET THE-END-OF-INPUT TO TRUE.
124 ðð146ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
ðð147ð
ðð148ð INIT-SEQUENTIAL-PROCESS.

Figure 115 (Part 2 of 4). Example of an Indexed File Update Program

Appendix G. File Processing Examples 359


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
126 ðð149ð MOVE INPUT-GEN-FLD TO MASTER-GEN-FLD.
127 ðð15ðð MOVE "START" TO OP-NAME.
128 ðð151ð START MASTER-FILE
ðð152ð KEY IS NOT LESS THAN MASTER-GEN-FLD
ðð153ð INVALID KEY
129 ðð154ð DISPLAY "MASTER-FILE START FAILED: INVALID KEY ",
ðð155ð MASTER-GEN-FLD
13ð ðð156ð MOVE HIGH-VALUE TO MASTER-GEN-FLD.
131 ðð157ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
133 ðð158ð PERFORM SEQUENTIAL-PROCESS
ðð159ð UNTIL INPUT-GEN-FLD NOT EQUAL MASTER-GEN-FLD.
ðð16ðð
ðð161ð SEQUENTIAL-PROCESS.
134 ðð162ð MOVE "READ NEXT" TO OP-NAME.
135 ðð163ð READ MASTER-FILE NEXT RECORD
136 ðð164ð AT END MOVE HIGH-VALUE TO MASTER-GEN-FLD.
137 ðð165ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
139 ðð166ð IF INPUT-GEN-FLD EQUAL MASTER-GEN-FLD
14ð ðð167ð MOVE MASTER-KEY TO PRINT-KEY
141 ðð168ð MOVE MASTER-NAME TO PRINT-NAME
142 ðð169ð MOVE MASTER-BAL TO PRINT-NEW-BAL
143 ðð17ðð PERFORM PRINT-DETAIL.
ðð171ð
ðð172ð DYNAMIC-PROCESS.
144 ðð173ð MOVE INPUT-KEY TO MASTER-KEY.
145 ðð174ð MOVE "READ" TO OP-NAME.
146 ðð175ð READ MASTER-FILE
ðð176ð INVALID KEY
147 ðð177ð DISPLAY "MASTER-FILE READ FAILED: INVALID KEY ",
ðð178ð MASTER-KEY
148 ðð179ð MOVE HIGH-VALUE TO MASTER-GEN-FLD.
149 ðð18ðð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
151 ðð181ð IF INPUT-GEN-FLD EQUAL MASTER-GEN-FLD
152 ðð182ð MOVE MASTER-KEY TO PRINT-KEY
153 ðð183ð MOVE MASTER-NAME TO PRINT-NAME
154 ðð184ð MOVE MASTER-BAL TO PRINT-BAL
155 ðð185ð MOVE INPUT-AMT TO PRINT-AMT
156 ðð186ð ADD INPUT-AMT TO MASTER-BAL
157 ðð187ð MOVE MASTER-BAL TO PRINT-NEW-BAL
158 ðð188ð PERFORM PRINT-DETAIL
159 ðð189ð MOVE "REWRITE" TO OP-NAME
16ð ðð19ðð REWRITE MASTER-RECORD
ðð191ð INVALID KEY
161 ðð192ð DISPLAY "MASTER-FILE REWRITE FAILED: INVALID KEY ",
ðð193ð MASTER-KEY
162 ðð194ð MOVE HIGH-VALUE TO MASTER-GEN-FLD.
163 ðð195ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
ðð196ð PRINT-DETAIL.
165 ðð197ð MOVE "WRITE" TO OP-NAME.
166 ðð198ð WRITE PRINT-RECORD-1
ðð199ð AT END-OF-PAGE
167 ðð2ððð PERFORM PAGE-END THROUGH PAGE-START.
168 ðð2ð1ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
17ð ðð2ð2ð MOVE SPACES TO PRINT-RECORD-1.
ðð2ð3ð
ðð2ð4ð PAGE-END.
171 ðð2ð5ð MOVE "WRITE" TO OP-NAME.
172 ðð2ð6ð ADD 1 TO PG-NUMBER.
173 ðð2ð7ð SUBTRACT LINAGE-COUNTER OF PRINT-FILE FROM 12
ðð2ð8ð GIVING LINES-TO-FOOT.
174 ðð2ð9ð MOVE SPACES TO PRINT-RECORD-1.
175 ðð21ðð WRITE PRINT-RECORD-1
ðð211ð AFTER ADVANCING LINES-TO-FOOT.
176 ðð212ð WRITE PRINT-RECORD-2 FROM PAGE-FOOT
ðð213ð BEFORE ADVANCING PAGE.
177 ðð214ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.

Figure 115 (Part 3 of 4). Example of an Indexed File Update Program

360 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ðð215ð PAGE-START.
179 ðð216ð WRITE PRINT-RECORD-2 FROM PAGE-HEAD
ðð217ð AFTER ADVANCING ð LINES.
18ð ðð218ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
182 ðð219ð MOVE SPACES TO PRINT-RECORD-2.
183 ðð22ðð WRITE PRINT-RECORD-2 FROM COLUMN-HEAD
ðð221ð AFTER ADVANCING 1 LINE.
184 ðð222ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
186 ðð223ð MOVE SPACES TO PRINT-RECORD-2.
ðð224ð ERROR-TERMINATION.
187 ðð225ð DISPLAY "PROCESS TERMINATING ABNORMALLY".
188 ðð226ð STOP RUN.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 28 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð29ð
Message . . . . : Blocking/Deblocking for file 'INPUT-FILE'
will be performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 1 ð ð ð ð
Source records read . . . . . . . . : 226
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program UPDTIND created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 115 (Part 4 of 4). Example of an Indexed File Update Program

Relative File Creation


This program creates a relative file of summary sales records using sequential
access. Each record contains a five-year summary of unit and dollar sales for one
week of the year; there are 52 records within the file, each representing one week.

Each input record represents the summary sales for one week of one year. The
records for the first week of the last five years (in ascending order) are the first five
input records. The records for the second week of the last five years are the next
five input records, and so on. Thus, five input records fill one output record.

The RELATIVE KEY for the RELATIVE-FILE is not specified because it is not required
for sequential access unless the START statement is used. (For updating,
however, the key is INPUT-WEEK.)

Appendix G. File Processing Examples 361


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. CRTREL.
ðððð3ð
3 ðððð4ð ENVIRONMENT DIVISION.
4 ðððð5ð CONFIGURATION SECTION.
5 ðððð6ð SOURCE-COMPUTER. IBM-AS4ðð. ð5/24/94
6 ðððð7ð OBJECT-COMPUTER. IBM-AS4ðð. ð5/24/94
7 ðððð8ð SPECIAL-NAMES. REQUESTOR IS REQUESTOR.
8 ðððð9ð FILE-CONTROL.
9 ððð1ðð SELECT RELATIVE-FILE ASSIGN TO DISK-FILED
1ð ððð11ð ORGANIZATION IS RELATIVE
11 ððð12ð ACCESS IS SEQUENTIAL
12 ððð13ð FILE STATUS RELATIVE-FILE-STATUS.
13 ððð14ð SELECT INPUT-FILE ASSIGN TO DISK-FILEC
14 ððð15ð FILE STATUS INPUT-FILE-STATUS.
ððð16ð
15 ððð17ð DATA DIVISION.
16 ððð18ð FILE SECTION.
17 ððð19ð FD RELATIVE-FILE LABEL RECORDS ARE STANDARD.
18 ððð2ðð ð1 RELATIVE-RECORD-ð1.
19 ððð21ð ð5 RELATIVE-RECORD OCCURS 5 TIMES INDEXED BY REL-INDEX.
2ð ððð22ð 1ð RELATIVE-YEAR PICTURE 99.
21 ððð23ð 1ð RELATIVE-WEEK PICTURE 99.
22 ððð24ð 1ð RELATIVE-UNIT-SALES PICTURE S9(6).
23 ððð25ð 1ð RELATIVE-DOLLAR-SALES PICTURE S9(9)V99.
24 ððð26ð FD INPUT-FILE LABEL RECORDS STANDARD.
25 ððð27ð ð1 INPUT-RECORD.
26 ððð28ð ð5 INPUT-YEAR PICTURE 99.
27 ððð29ð ð5 INPUT-WEEK PICTURE 99.
28 ððð3ðð ð5 INPUT-UNIT-SALES PICTURE S9(6).
29 ððð31ð ð5 INPUT-DOLLAR-SALES PICTURE S9(9)V99.
3ð ððð32ð WORKING-STORAGE SECTION.
31 ððð33ð 77 INPUT-FILE-STATUS PICTURE XX.
32 ððð34ð 77 RELATIVE-FILE-STATUS PICTURE XX.
33 ððð35ð ð1 WORK-RECORD.
34 ððð36ð ð5 WORK-YEAR PICTURE 99 VALUE ðð.
35 ððð37ð ð5 WORK-WEEK PICTURE 99.
36 ððð38ð ð5 WORK-UNIT-SALES PICTURE S9(6).
37 ððð39ð ð5 WORK-DOLLAR-SALES PICTURE S9(9)V99.
38 ððð4ðð ð1 ERROR-INFO.
39 ððð41ð ð5 OP-NAME PICTURE X(5).
4ð ððð42ð ð5 FILLER PICTURE X(1ð)
41 ððð43ð VALUE " ERROR ON ".
42 ððð44ð ð5 FILE-NAME PICTURE X(13).
43 ððð45ð ð5 FILLER PICTURE X(16)
44 ððð46ð VALUE " FILE STATUS IS ".
45 ððð47ð ð5 STATUS-VALUE PICTURE XX.
46 ððð48ð ð1 ERROR-FLAG PICTURE X VALUE SPACE.
47 ððð49ð 88 ERROR-OCCURRED VALUE "1".
48 ððð5ðð ð1 INPUTEND PICTURE X VALUE SPACE.
49 ððð51ð 88 THE-END-OF-INPUT VALUE "E".
ððð52ð
5ð ððð53ð PROCEDURE DIVISION.
ððð54ð DECLARATIVES.
ððð55ð
ððð56ð INP-FILE-ERROR SECTION.
ððð57ð USE AFTER STANDARD ERROR PROCEDURE ON INPUT-FILE.
ððð58ð INPUT-FILE-ERROR.
51 ððð59ð MOVE "INPUT-FILE" TO FILE-NAME.
52 ððð6ðð MOVE INPUT-FILE-STATUS TO STATUS-VALUE.
53 ððð61ð SET ERROR-OCCURRED TO TRUE.
ððð62ð REL-FILE-ERROR SECTION.
ððð63ð USE AFTER STANDARD ERROR PROCEDURE ON RELATIVE-FILE.
ððð64ð RELATIVE-FILE-ERROR.
54 ððð65ð MOVE "RELATIVE-FILE" TO FILE-NAME.
55 ððð66ð MOVE RELATIVE-FILE-STATUS TO STATUS-VALUE.
56 ððð67ð SET ERROR-OCCURRED TO TRUE.
ððð68ð END DECLARATIVES.
ððð69ð BEGIN-PROCESSING SECTION.
ððð7ðð PROCESSING-CONTROL.
57 ððð71ð MOVE "OPEN" TO OP-NAME.
58 ððð72ð OPEN INPUT INPUT-FILE
ððð73ð OUTPUT RELATIVE-FILE.
59 ððð74ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
61 ððð75ð SET REL-INDEX TO 1.
62 ððð76ð PERFORM READ-INPUT-FILE.

Figure 116 (Part 1 of 2). Example of a Relative File Program

362 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
63 ððð77ð PERFORM PROCESS-DATA THRU READ-INPUT-FILE
ððð78ð UNTIL THE-END-OF-INPUT.
64 ððð79ð CLOSE RELATIVE-FILE INPUT-FILE.
65 ððð8ðð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
67 ððð81ð STOP RUN.
ððð82ð ERROR-TERMINATION.
68 ððð83ð DISPLAY ERROR-INFO UPON REQUESTOR.
69 ððð84ð DISPLAY "PROCESSING TERMINATED DUE TO I-O ERROR"
ððð85ð UPON REQUESTOR.
7ð ððð86ð STOP RUN.
ððð87ð PROCESS-DATA.
71 ððð88ð MOVE INPUT-RECORD TO RELATIVE-RECORD (REL-INDEX).
72 ððð89ð IF REL-INDEX NOT = 5
73 ððð9ðð SET REL-INDEX UP BY 1
ððð91ð ELSE
74 ððð92ð SET REL-INDEX TO 1
75 ððð93ð PERFORM RELATIVE-FILE-WRITE.
ððð94ð READ-INPUT-FILE.
76 ððð95ð MOVE "READ" TO OP-NAME.
77 ððð96ð READ INPUT-FILE
78 ððð97ð AT END SET THE-END-OF-INPUT TO TRUE.
79 ððð98ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
ððð99ð RELATIVE-FILE-WRITE.
81 ðð1ððð MOVE "WRITE" TO OP-NAME.
82 ðð1ð1ð WRITE RELATIVE-RECORD-ð1.
83 ðð1ð2ð IF ERROR-OCCURRED GO TO ERROR-TERMINATION.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ MSGID: LBLðð27 SEVERITY: 1ð SEQNBR:
Message . . . . : I-O SECTION not found. Assumed present
\ 17 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð19ð
Message . . . . : Blocking/Deblocking for file 'RELATIVE-FILE'
will be performed by compiler-generated code.
\ 24 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð26ð
Message . . . . : Blocking/Deblocking for file 'INPUT-FILE'
will be performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
3 2 1 ð ð ð
Source records read . . . . . . . . : 1ð2
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : 1ð
LBLð9ð1 ðð Program CRTREL created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 116 (Part 2 of 2). Example of a Relative File Program

Relative File Updating


This program uses sequential access to update the file of summary sales records
created in the CRTREL program. The updating program adds a record for the new
year and deletes the oldest year’s records from RELATIVE-FILE.

The input record represents the summary sales record for one week of the pre-
ceding year. The RELATIVE KEY for the RELATIVE-FILE is in the input record as
INPUT-WEEK. The RELATIVE KEY is used to check that the record was correctly
written.

Appendix G. File Processing Examples 363


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. UPDTREL.
ðððð3ð
3 ðððð4ð ENVIRONMENT DIVISION.
4 ðððð5ð CONFIGURATION SECTION.
5 ðððð6ð SOURCE-COMPUTER. IBM-AS4ðð. ð5/24/94
6 ðððð7ð OBJECT-COMPUTER. IBM-AS4ðð. ð5/24/94
7 ðððð8ð INPUT-OUTPUT SECTION.
8 ðððð9ð FILE-CONTROL.
9 ððð1ðð SELECT RELATIVE-FILE ASSIGN TO DISK-FILED
1ð ððð11ð ORGANIZATION IS RELATIVE
11 ððð12ð ACCESS IS SEQUENTIAL
12 ððð13ð RELATIVE KEY INPUT-WEEK
13 ððð14ð FILE STATUS STATUS-VALUE.
14 ððð15ð SELECT INPUT-FILE ASSIGN TO DISK-FILES2
15 ððð16ð FILE STATUS STATUS-VALUE.
ððð17ð
16 ððð18ð DATA DIVISION.
17 ððð19ð FILE SECTION.
18 ððð2ðð FD RELATIVE-FILE LABEL RECORDS STANDARD.
19 ððð21ð ð1 RELATIVE-RECORD PICTURE X(1ð5).
2ð ððð22ð FD INPUT-FILE LABEL RECORDS STANDARD.
21 ððð23ð ð1 INPUT-RECORD.
22 ððð24ð ð5 INPUT-YEAR PICTURE 99.
23 ððð25ð ð5 INPUT-WEEK PICTURE 99.
24 ððð26ð ð5 INPUT-UNIT-SALES PICTURE S9(6).
25 ððð27ð ð5 INPUT-DOLLAR-SALES PICTURE S9(9)V99.
26 ððð28ð WORKING-STORAGE SECTION.
ððð29ð
27 ððð3ðð ð1 INPUTEND PICTURE X VALUE SPACE.
28 ððð31ð 88 THE-END-OF-INPUT VALUE "E".
29 ððð32ð ð1 WORK-RECORD.
3ð ððð33ð ð5 FILLER PICTURE X(21).
31 ððð34ð ð5 CURRENT-WORK-YEARS PICTURE X(84).
32 ððð35ð ð5 NEW-WORK-YEAR.
33 ððð36ð 1ð WORK-YEAR PICTURE 99.
34 ððð37ð 1ð WORK-WEEK PICTURE 99.
35 ððð38ð 1ð WORK-UNIT-SALES PICTURE S9(6).
36 ððð39ð 1ð WORK-DOLLAR-SALES PICTURE S9(9)V99.
37 ððð4ðð 66 WORK-OUT-RECORD RENAMES
38 ððð41ð CURRENT-WORK-YEARS THROUGH NEW-WORK-YEAR.
39 ððð42ð ð1 ERROR-MESSAGE.
4ð ððð43ð ð5 OP-NAME PICTURE X(7).
41 ððð44ð ð5 FILLER PICTURE X(1ð)
42 ððð45ð VALUE " ERROR ON ".
43 ððð46ð ð5 FILE-NAME PICTURE X(13).
44 ððð47ð ð5 FILLER PICTURE X(16)
45 ððð48ð VALUE " FILE STATUS IS ".
46 ððð49ð ð5 STATUS-VALUE PICTURE X(2).
ððð5ðð
47 ððð51ð PROCEDURE DIVISION.
ððð52ð DECLARATIVES.
ððð53ð I-O-ERROR SECTION.
ððð54ð USE AFTER STANDARD ERROR PROCEDURE ON RELATIVE-FILE,
ððð55ð INPUT-FILE.
ððð56ð ERROR-PROCEDURE.
48 ððð57ð DISPLAY ERROR-MESSAGE.
49 ððð58ð DISPLAY "PROCESSING TERMINATING".
5ð ððð59ð STOP RUN.
ððð6ðð END DECLARATIVES.
ððð61ð MAIN-PROCEDURE SECTION.
ððð62ð BEGIN-PROCESSING.
51 ððð63ð MOVE "OPEN" TO OP-NAME.
52 ððð64ð MOVE "INPUT-FILE" TO FILE-NAME.
53 ððð65ð OPEN INPUT INPUT-FILE.
54 ððð66ð MOVE "RELATIVE-FILE" TO FILE-NAME.
55 ððð67ð OPEN I-O RELATIVE-FILE.
56 ððð68ð PERFORM READ-FILES.
57 ððð69ð PERFORM UPDATE-RELATIVE-FILE THRU READ-FILES
ððð7ðð UNTIL THE-END-OF-INPUT.
58 ððð71ð MOVE "CLOSE" TO OP-NAME.
59 ððð72ð MOVE "INPUT-FILE" TO FILE-NAME.
6ð ððð73ð CLOSE INPUT-FILE.
61 ððð74ð MOVE "RELATIVE-FILE" TO FILE-NAME.
62 ððð75ð CLOSE RELATIVE-FILE.
63 ððð76ð STOP RUN.

Figure 117 (Part 1 of 2). Example of a Relative File Update Program

364 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ððð77ð UPDATE-RELATIVE-FILE.
64 ððð78ð MOVE "REWRITE" TO OP-NAME.
65 ððð79ð MOVE "RELATIVE-FILE" TO FILE-NAME.
66 ððð8ðð REWRITE RELATIVE-RECORD FROM WORK-OUT-RECORD.
ððð81ð READ-FILES.
67 ððð82ð MOVE "READ" TO OP-NAME.
68 ððð83ð MOVE "RELATIVE-FILE" TO FILE-NAME.
69 ððð84ð READ RELATIVE-FILE INTO WORK-RECORD
7ð ððð85ð AT END SET THE-END-OF-INPUT TO TRUE.
71 ððð86ð MOVE "INPUT-FILE" TO FILE-NAME.
72 ððð87ð READ INPUT-FILE INTO NEW-WORK-YEAR
73 ððð88ð AT END SET THE-END-OF-INPUT TO TRUE.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 2ð MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð22ð
Message . . . . : Blocking/Deblocking for file 'INPUT-FILE'
will be performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 1 ð ð ð ð
Source records read . . . . . . . . : 88
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program UPDTREL created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 117 (Part 2 of 2). Example of a Relative File Update Program

Relative File Retrieval


This program retrieves the summary file created by the CRTREL program, using
dynamic access.

The records of the INPUT-FILE contain one required field (INPUT-WEEK), which is
the RELATIVE KEY for RELATIVE-FILE, and one optional field (END-WEEK). An
input record containing data in INPUT-WEEK and spaces in END-WEEK requests a
printout for that one specific RELATIVE-RECORD; the record is retrieved through
random access. (Random processing is a method of processing in which records
can be read from, written to, or removed from a file in an order requested by the
program that is using them.) An input record containing data in both INPUT-WEEK
and END-WEEK requests a printout of all the RELATIVE-FILE records within the RELA-
TIVE KEY range of INPUT-WEEK through END-WEEK inclusive. These records are
retrieved through sequential access.

Appendix G. File Processing Examples 365


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. RTRVREL.
ðððð3ð
3 ðððð4ð ENVIRONMENT DIVISION.
4 ðððð5ð CONFIGURATION SECTION.
5 ðððð6ð SOURCE-COMPUTER. IBM-AS4ðð. ð5/24/94
6 ðððð7ð OBJECT-COMPUTER. IBM-AS4ðð. ð5/24/94
7 ðððð8ð SPECIAL-NAMES. REQUESTOR IS REQUESTOR.
8 ðððð9ð INPUT-OUTPUT SECTION.
9 ððð1ðð FILE-CONTROL.
1ð ððð11ð SELECT RELATIVE-FILE ASSIGN TO DISK-FILED
11 ððð12ð ORGANIZATION IS RELATIVE
12 ððð13ð ACCESS IS DYNAMIC
13 ððð14ð RELATIVE KEY INPUT-WEEK
14 ððð15ð FILE STATUS IS RELATIVE-FILE-STATUS.
15 ððð16ð SELECT INPUT-FILE ASSIGN TO DISK-FILEF
16 ððð17ð FILE STATUS IS INPUT-FILE-STATUS.
17 ððð18ð SELECT PRINT-FILE ASSIGN TO PRINTER-QSYSPRT
18 ððð19ð FILE STATUS IS PRINT-FILE-STATUS.
ððð2ðð
19 ððð21ð DATA DIVISION.
2ð ððð22ð FILE SECTION.
21 ððð23ð FD RELATIVE-FILE LABEL RECORDS STANDARD.
22 ððð24ð ð1 RELATIVE-RECORD-ð1.
23 ððð25ð ð5 RELATIVE-RECORD OCCURS 5 TIMES INDEXED BY REL-INDEX.
24 ððð26ð 1ð RELATIVE-YEAR PICTURE 99.
25 ððð27ð 1ð RELATIVE-WEEK PICTURE 99.
26 ððð28ð 1ð RELATIVE-UNIT-SALES PICTURE S9(6).
27 ððð29ð 1ð RELATIVE-DOLLAR-SALES PICTURE S9(9)V99.
28 ððð3ðð FD INPUT-FILE LABEL RECORDS STANDARD.
29 ððð31ð ð1 INPUT-RECORD.
3ð ððð32ð ð5 INPUT-WEEK PICTURE 99.
31 ððð33ð ð5 END-WEEK PICTURE 99.
32 ððð34ð FD PRINT-FILE LABEL RECORDS OMITTED.
33 ððð35ð ð1 PRINT-RECORD.
34 ððð36ð ð5 PRINT-WEEK PICTURE 99.
35 ððð37ð ð5 FILLER PICTURE X(5).
36 ððð38ð ð5 PRINT-YEAR PICTURE 99.
37 ððð39ð ð5 FILLER PICTURE X(5).
38 ððð4ðð ð5 PRINT-UNIT-SALES PICTURE ZZZ,ZZ9.
39 ððð41ð ð5 FILLER PICTURE X(5).
4ð ððð42ð ð5 PRINT-DOLLAR-SALES PICTURE $$$$,$$$,$$$.99.
41 ððð43ð WORKING-STORAGE SECTION.
42 ððð44ð 77 RELATIVE-FILE-STATUS PICTURE XX.
43 ððð45ð 77 INPUT-FILE-STATUS PICTURE XX.
44 ððð46ð 77 PRINT-FILE-STATUS PICTURE XX.
45 ððð47ð 77 HIGH-WEEK PICTURE 99 VALUE 53.
46 ððð48ð 77 OP-NAME PICTURE X(9).
47 ððð49ð ð1 INPUTEND PICTURE X(9).
48 ððð5ðð 88 THE-END-OF-INPUT VALUE "E".
49 ððð51ð PROCEDURE DIVISION.
ððð52ð DECLARATIVES.
ððð53ð RELATIVE-FILE-ERROR SECTION.
ððð54ð USE AFTER STANDARD ERROR PROCEDURE ON RELATIVE-FILE.
ððð55ð RELATIVE-ERROR-MSG.
5ð ððð56ð DISPLAY OP-NAME, " ERROR ON RELATIVE-FILE ".
51 ððð57ð DISPLAY "FILE STATUS VALUE IS ", RELATIVE-FILE-STATUS.
52 ððð58ð DISPLAY "PROCESSING TERMINATED ".
53 ððð59ð STOP RUN.
ððð6ðð INPUT-FILE-ERROR SECTION.
ððð61ð USE AFTER STANDARD ERROR PROCEDURE ON INPUT-FILE.
ððð62ð INPUT-ERROR-MSG.
54 ððð63ð DISPLAY OP-NAME, " ERROR ON INPUT-FILE ".
55 ððð64ð DISPLAY "FILE STATUS VALUE IS ", INPUT-FILE-STATUS.
56 ððð65ð DISPLAY "PROCESSING TERMINATED ".
57 ððð66ð STOP RUN.
ððð67ð PRINT-FILE-ERROR SECTION.
ððð68ð USE AFTER STANDARD ERROR PROCEDURE ON PRINT-FILE.
ððð69ð PRINT-ERROR-MSG.
58 ððð7ðð DISPLAY OP-NAME, " ERROR ON PRINT-FILE ".
59 ððð71ð DISPLAY "FILE STATUS VALUE IS ", PRINT-FILE-STATUS.
6ð ððð72ð DISPLAY "PROCESSING TERMINATED ".
61 ððð73ð STOP RUN.
ððð74ð END DECLARATIVES.

Figure 118 (Part 1 of 2). Example of a Relative File Retrieval Program

366 COBOL/400 User’s Guide


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
ððð75ð MAIN-PROCEDURE SECTION.
ððð76ð MAIN-PROCESSING.
62 ððð77ð MOVE "OPEN" TO OP-NAME.
63 ððð78ð OPEN INPUT INPUT-FILE RELATIVE-FILE
ððð79ð OUTPUT PRINT-FILE.
64 ððð8ðð MOVE SPACES TO PRINT-RECORD.
65 ððð81ð PERFORM READ-INPUT-FILE.
66 ððð82ð PERFORM CONTROL-PROCESS THRU READ-INPUT-FILE
ððð83ð UNTIL THE-END-OF-INPUT.
67 ððð84ð MOVE "CLOSE" TO OP-NAME.
68 ððð85ð CLOSE RELATIVE-FILE
ððð86ð INPUT-FILE
ððð87ð PRINT-FILE.
69 ððð88ð STOP RUN.
ððð89ð CONTROL-PROCESS.
7ð ððð9ðð IF (END-WEEK = SPACES OR END-WEEK = ðð)
71 ððð91ð PERFORM RANDOM-PROCESS
ððð92ð ELSE
72 ððð93ð PERFORM SEQUENTIAL-PROCESS.
ððð94ð READ-INPUT-FILE.
73 ððð95ð MOVE "READ" TO OP-NAME.
74 ððð96ð READ INPUT-FILE
75 ððð97ð AT END SET THE-END-OF-INPUT TO TRUE.
ððð98ð RANDOM-PROCESS.
76 ððð99ð MOVE "READ" TO OP-NAME.
77 ðð1ððð READ RELATIVE-FILE
78 ðð1ð1ð INVALID KEY MOVE HIGH-WEEK TO RELATIVE-WEEK(1).
79 ðð1ð2ð IF RELATIVE-WEEK(1) NOT EQUAL HIGH-WEEK
8ð ðð1ð3ð PERFORM PRINT-SUMMARY VARYING REL-INDEX FROM 1 BY 1
ðð1ð4ð UNTIL REL-INDEX > 5.
ðð1ð5ð SEQUENTIAL-PROCESS.
81 ðð1ð6ð MOVE "READ" TO OP-NAME.
82 ðð1ð7ð READ RELATIVE-FILE
83 ðð1ð8ð INVALID KEY MOVE HIGH-WEEK TO RELATIVE-WEEK(1).
84 ðð1ð9ð PERFORM READ-REL-SEQ
ðð11ðð UNTIL RELATIVE-WEEK(1) GREATER THAN END-WEEK.
ðð111ð
ðð112ð READ-REL-SEQ.
85 ðð113ð PERFORM PRINT-SUMMARY VARYING REL-INDEX FROM 1 BY 1
ðð114ð UNTIL REL-INDEX > 5.
86 ðð115ð MOVE "READ NEXT" TO OP-NAME.
87 ðð116ð READ RELATIVE-FILE NEXT RECORD
88 ðð117ð AT END MOVE HIGH-WEEK TO RELATIVE-WEEK(1).
ðð118ð PRINT-SUMMARY.
89 ðð119ð MOVE RELATIVE-YEAR (REL-INDEX) TO PRINT-YEAR.
9ð ðð12ðð MOVE RELATIVE-WEEK (REL-INDEX) TO PRINT-WEEK.
91 ðð121ð MOVE RELATIVE-UNIT-SALES (REL-INDEX) TO PRINT-UNIT-SALES.
92 ðð122ð MOVE RELATIVE-DOLLAR-SALES(REL-INDEX) TO PRINT-DOLLAR-SALES.
93 ðð123ð MOVE "WRITE" TO OP-NAME.
94 ðð124ð WRITE PRINT-RECORD AFTER ADVANCING 2 LINES.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \
5763CB1 V3RðM5 AS/4ðð COBOL Messages
STMT
\ 28 MSGID: LBLð65ð SEVERITY: ðð SEQNBR: ððð3ðð
Message . . . . : Blocking/Deblocking for file 'INPUT-FILE'
will be performed by compiler-generated code.
\ \ \ \ \ E N D O F M E S S A G E S \ \ \ \ \
Message Summary
Total Info(ð-4) Warning(5-19) Error(2ð-29) Severe(3ð-39) Terminal(4ð-99)
1 1 ð ð ð ð
Source records read . . . . . . . . : 124
Copy records read . . . . . . . . . : ð
Copy members processed . . . . . . : ð
Sequence errors . . . . . . . . . . : ð
Highest severity message issued . . : ð
LBLð9ð1 ðð Program RTRVREL created in library XMPLIB.
\ \ \ \ \ E N D O F C O M P I L A T I O N \ \ \ \ \

Figure 118 (Part 2 of 2). Example of a Relative File Retrieval Program

Appendix G. File Processing Examples 367


Sorting and Merging Files
Figure 119 illustrates the creation of sorted files of current sales and year-to-date
sales.

First, the SORT statement for current sales is executed. The input procedure for
this sorting operation is SCREEN-DEPT. The records are sorted in ascending
order of department, and within each department, in descending order of net sales.
The output for this sort is then printed.

After the sorting operation is completed, the current sales records are merged with
the year-to-date sales records. The records in this file are merged in ascending
order of department number and, within each department, in ascending order of
employee numbers, and, for each employee, in ascending order of months to
create an updated year-to-date master file.

When the merging process finishes, the updated year-to-date master file is printed.

5763CB1 V3RðM5 91ð524 AS/4ðð COBOL Source


STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ðððð1ð IDENTIFICATION DIVISION.
2 ðððð2ð PROGRAM-ID. SORTMERGE.
ðððð3ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðððð4ð\ THIS IS A SORT/MERGE EXAMPLE USING AN INPUT PROCEDURE \
ðððð5ð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
3 ðððð6ð ENVIRONMENT DIVISION.
4 ðððð7ð CONFIGURATION SECTION.
5 ðððð8ð SOURCE-COMPUTER. IBM-AS4ðð.
6 ðððð9ð OBJECT-COMPUTER. IBM-AS4ðð.
7 ððð1ðð SPECIAL-NAMES.
8 ððð11ð REQUESTOR IS CONSOLE.
9 ððð12ð INPUT-OUTPUT SECTION.
1ð ððð13ð FILE-CONTROL.
11 ððð14ð SELECT WORK-FILE ASSIGN TO DISK-WRK.
12 ððð15ð SELECT CURRENT-SALES-FILE-IN ASSIGN TO DISK-CURRIN.
13 ððð16ð SELECT CURRENT-SALES-FILE-OUT ASSIGN TO DISK-CURROUT.
14 ððð17ð SELECT YTD-SALES-FILE-IN ASSIGN TO DISK-YTDIN.
15 ððð18ð SELECT YTD-SALES-FILE-OUT ASSIGN TO DISK-YTDOUT.
16 ððð19ð SELECT PRINTER-OUT ASSIGN TO PRINTER-QPRINT.
17 ððð2ðð DATA DIVISION.
18 ððð21ð FILE SECTION.
19 ððð22ð SD WORK-FILE
2ð ððð23ð DATA RECORD IS SALES-RECORD.
21 ððð24ð ð1 SALES-RECORD.
22 ððð25ð ð5 EMPL-NO PIC 9(6).
23 ððð26ð ð5 DEPT PIC 9(2).
24 ððð27ð ð5 SALES PIC 9(7)V99.
25 ððð28ð ð5 NAME-ADDR PIC X(61).
26 ððð29ð ð5 MONTH PIC X(2).
27 ððð3ðð FD CURRENT-SALES-FILE-IN
28 ððð31ð LABEL RECORDS STANDARD
29 ððð32ð DATA RECORD CURRENT-SALES-IN.
3ð ððð33ð ð1 CURRENT-SALES-IN.
31 ððð34ð ð5 EMPL-NO PIC 9(6).
32 ððð35ð ð5 DEPT PIC 9(2).
33 ððð36ð 88 ON-SITE-EMPLOYEE VALUES ð
34 ððð37ð THRU 6, 8.
35 ððð38ð ð5 SALES PIC 9(7)V99.
36 ððð39ð ð5 NAME-ADDR PIC X(61).
37 ððð4ðð ð5 MONTH PIC X(2).
38 ððð41ð FD CURRENT-SALES-FILE-OUT
39 ððð42ð LABEL RECORDS STANDARD
4ð ððð43ð DATA RECORD CURRENT-SALES-OUT.
41 ððð44ð ð1 CURRENT-SALES-OUT.
42 ððð45ð ð5 EMPL-NO PIC 9(6).
43 ððð46ð ð5 DEPT PIC 9(2).
44 ððð47ð ð5 SALES PIC 9(7)V99.
45 ððð48ð ð5 NAME-ADDR PIC X(61).
46 ððð49ð ð5 MONTH PIC X(2).

Figure 119 (Part 1 of 3). Example of Use of SORT/MERGE

368 COBOL/400 User’s Guide


5763CB1 V3RðM5 91ð524 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
47 ððð5ðð FD YTD-SALES-FILE-IN
48 ððð51ð LABEL RECORDS STANDARD
49 ððð52ð DATA RECORD YTD-SALES-IN.
5ð ððð53ð ð1 YTD-SALES-IN.
51 ððð54ð ð5 EMPL-NO PIC 9(6).
52 ððð55ð ð5 DEPT PIC 9(2).
53 ððð56ð ð5 SALES PIC 9(7)V99.
54 ððð57ð ð5 NAME-ADDR PIC X(61).
55 ððð58ð ð5 MONTH PIC X(2).
56 ððð59ð FD YTD-SALES-FILE-OUT
57 ððð6ðð LABEL RECORDS STANDARD
58 ððð61ð DATA RECORD YTD-SALES-OUT.
59 ððð62ð ð1 YTD-SALES-OUT.
6ð ððð63ð ð5 EMPL-NO PIC 9(6).
61 ððð64ð ð5 DEPT PIC 9(2).
62 ððð65ð ð5 SALES PIC 9(7)V99.
63 ððð66ð ð5 NAME-ADDR PIC X(61).
64 ððð67ð ð5 MONTH PIC X(2).
65 ððð68ð FD PRINTER-OUT
66 ððð69ð LABEL RECORDS OMITTED
67 ððð7ðð DATA RECORD PRINT-LINE.
68 ððð71ð ð1 PRINT-LINE.
69 ððð72ð ð5 RECORD-LABEL PIC X(25).
7ð ððð73ð ð5 DISK-RECORD-DISPLAY PIC X(8ð).
71 ððð74ð WORKING-STORAGE SECTION.
72 ððð75ð ð1 SALES-FILE-IN-EOF-STATUS PIC X VALUE "F".
73 ððð76ð 88 SALES-FILE-IN-END-OF-FILE VALUE "T".
74 ððð77ð ð1 SALES-FILE-OUT-EOF-STATUS PIC X VALUE "F".
75 ððð78ð 88 SALES-FILE-OUT-END-OF-FILE VALUE "T".
76 ððð79ð ð1 YTD-SALES-OUT-EOF-STATUS PIC X VALUE "F".
77 ððð8ðð 88 YTD-SALES-OUT-END-OF-FILE VALUE "T".
78 ððð81ð PROCEDURE DIVISION.
ððð82ð OPEN-PRINTER-FILE SECTION.
ððð83ð ðð5-PRINTER-FILE.
79 ððð84ð OPEN OUTPUT PRINTER-OUT.
ððð85ð LIST-SORT-LIST-CURRENT-SALES SECTION.
ððð86ð ð1ð-LIST-SORT-CURRENT-SALES.
8ð ððð87ð SORT WORK-FILE
ððð88ð ON ASCENDING KEY DEPT OF SALES-RECORD
ððð89ð ON DESCENDING KEY SALES OF SALES-RECORD
ððð9ðð INPUT PROCEDURE SCREEN-DEPT
ððð91ð GIVING CURRENT-SALES-FILE-OUT.
ððð92ð ð2ð-LIST-SORTED-SALES.
81 ððð93ð OPEN INPUT CURRENT-SALES-FILE-OUT.
82 ððð94ð PERFORM 1ðð-PRINT-SALES-FILE-OUT
ððð95ð THRU 11ð-END-PRINT-SALES-FILE-OUT
ððð96ð UNTIL SALES-FILE-OUT-END-OF-FILE.
83 ððð97ð CLOSE CURRENT-SALES-FILE-OUT.
ððð98ð UPDATE-YEARLY-REPORT SECTION.
ððð99ð ð4ð-MERGE-CURRENT-PREVIOUS.
84 ðð1ððð MERGE WORK-FILE
ðð1ð1ð ON ASCENDING KEY DEPT OF SALES-RECORD
ðð1ð2ð ON ASCENDING KEY EMPL-NO OF SALES-RECORD
ðð1ð3ð ON ASCENDING KEY MONTH OF SALES-RECORD
ðð1ð4ð USING YTD-SALES-FILE-IN
ðð1ð5ð CURRENT-SALES-FILE-IN
ðð1ð6ð GIVING YTD-SALES-FILE-OUT.
ðð1ð7ð ð4ð-PRINT-YTD-SALES-OUT.
85 ðð1ð8ð OPEN INPUT YTD-SALES-FILE-OUT.
86 ðð1ð9ð PERFORM 12ð-READ-PRINT-YTD-SALES-OUT
ðð11ðð UNTIL YTD-SALES-OUT-END-OF-FILE.
87 ðð111ð CLOSE YTD-SALES-FILE-OUT
ðð112ð PRINTER-OUT.
88 ðð113ð STOP RUN.
ðð114ð SCREEN-DEPT SECTION.
ðð115ð ð6ð-S-D-1.
89 ðð116ð OPEN INPUT CURRENT-SALES-FILE-IN
9ð ðð117ð PERFORM ð7ð-READ-SELECT-DEPT THRU ð8ð-END-READ-SELECT-DEPT
ðð118ð UNTIL SALES-FILE-IN-END-OF-FILE.
91 ðð119ð CLOSE CURRENT-SALES-FILE-IN.
92 ðð12ðð GO TO ð9ð-END-S-D-1.
ðð121ð ð7ð-READ-SELECT-DEPT.
93 ðð122ð READ CURRENT-SALES-FILE-IN
94 ðð123ð AT END MOVE "T" TO SALES-FILE-IN-EOF-STATUS
95 ðð124ð GO TO ð8ð-END-READ-SELECT-DEPT.

Figure 119 (Part 2 of 3). Example of Use of SORT/MERGE

Appendix G. File Processing Examples 369


5763CB1 V3RðM5 91ð524 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
96 ðð125ð MOVE "UNSORTED CURRENT SALES ",
ðð126ð TO RECORD-LABEL OF PRINT-LINE.
97 ðð127ð MOVE CURRENT-SALES-IN TO DISK-RECORD-DISPLAY.
98 ðð128ð WRITE PRINT-LINE.
99 ðð129ð IF ON-SITE-EMPLOYEE
1ðð ðð13ðð MOVE CURRENT-SALES-IN TO SALES-RECORD
1ð1 ðð131ð RELEASE SALES-RECORD.
ðð132ð ð8ð-END-READ-SELECT-DEPT.
ðð133ð EXIT.
1ð2 ðð134ð ð9ð-END-S-D-1.
ðð135ð END-SCREEN-DEPT SECTION.
ðð136ð 1ðð-PRINT-SALES-FILE-OUT.
1ð3 ðð137ð READ CURRENT-SALES-FILE-OUT
1ð4 ðð138ð AT END MOVE "T" TO SALES-FILE-OUT-EOF-STATUS
1ð5 ðð139ð GO TO 11ð-END-PRINT-SALES-FILE-OUT.
1ð6 ðð14ðð MOVE "SORTED CURRENT SALES "
ðð141ð TO RECORD-LABEL OF PRINT-LINE.
1ð7 ðð142ð MOVE CURRENT-SALES-OUT TO DISK-RECORD-DISPLAY.
1ð8 ðð143ð WRITE PRINT-LINE.
ðð144ð 11ð-END-PRINT-SALES-FILE-OUT.
ðð145ð EXIT.
1ð9 ðð146ð 12ð-READ-PRINT-YTD-SALES-OUT.
11ð ðð147ð READ YTD-SALES-FILE-OUT
111 ðð148ð AT END MOVE "T" TO YTD-SALES-OUT-EOF-STATUS
112 ðð149ð GO TO 13ð-END-READ-PRT-YTD-SALES-OUT.
113 ðð15ðð MOVE "MERGED YTD SALES ",
ðð151ð TO RECORD-LABEL OF PRINT-LINE.
114 ðð152ð MOVE YTD-SALES-OUT TO DISK-RECORD-DISPLAY.
115 ðð153ð WRITE PRINT-LINE.
ðð154ð 13ð-END-READ-PRT-YTD-SALES-OUT.
ðð155ð EXIT.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

Figure 119 (Part 3 of 3). Example of Use of SORT/MERGE

370 COBOL/400 User’s Guide


Appendix H. Example of a COBOL Formatted Dump
| Figure 120 on page 372 shows an example of a COBOL formatted dump. To
| ensure that a dump is available if something goes wrong when you try to run your
| program, change the INQMSGRPY parameter of the job (for instance, by using the
| CHGJOB command) to *RQD. When prompted, you can then specify that a dump
| be generated.

The following list describes the labeled areas of the figure:


.A/ The exception for which the dump was requested and the location in the
program where the exception occurred.
.B/ The COBOL statement number of the last I-O operation that was run before
the exception occurred. This information is produced only if at least one I-O
operation has been processed.
.C/ The current information for each file. This information is produced only if the
program has files.
.D/ Beginning of compiler-generated fields (included in the dump if you respond
with an F option).
.E/ I-O flags for the current file:
Bit Meaning

1 File is open
2 File is locked
3 End of file
4 (Reserved)
5 Optional file
6 Check indexed file for duplicates at open
7 End of page
8 (Reserved).
.F/ Previous status code.
.G/ Beginning of Module Global Table (MGT).3
.H/ Last exception code.
.I/ Invocation number of current program.
.J/ Qualified program name and library.
.K/ Beginning of the Program Global Table (PGT).4
.L/ Invocation number of the main COBOL program.
.M/ Job date (YYMMDD).
.N/ Beginning of user fields.
.O/ Invalid zoned field printed in hexadecimal.

3 The Module Global Table (MGT) defines a common area for the module. The table is used to pass information to run-time
subroutines.
4 The Program Global Table (PGT) is a communication area for the entire COBOL run unit. There is only one PGT for the run unit.

 Copyright IBM Corp. 1994 371


5763CB1 V3RðM5 AS/4ðð COBOL Source
STMT SEQNBR -A 1 B..+....2....+....3....+....4....+....5....+....6....+....7..IDENTFCN S COPYNAME CHG DATE
1 ððð1ðð IDENTIFICATION DIVISION. ð3/ð7/94
2 ððð2ðð PROGRAM-ID. XMPLDUMP. ð3/22/94
3 ððð3ðð AUTHOR. PROGRAMMER NAME. ð3/ð7/94
4 ððð4ðð INSTALLATION. COBOL DEVELOPMENT CENTRE. ð3/ð7/94
5 ððð5ðð DATE-WRITTEN. 11/27/88. ð3/ð7/94
6 ððð6ðð DATE-COMPILED. ð5/24/94 12:21:54. ð3/ð7/94
7 ððð7ðð ENVIRONMENT DIVISION. ð3/ð7/94
8 ððð8ðð CONFIGURATION SECTION. ð3/ð7/94
9 ððð9ðð SOURCE-COMPUTER. IBM-AS4ðð. ð3/ð7/94
1ð ðð1ððð OBJECT-COMPUTER. IBM-AS4ðð. ð3/ð7/94
11 ðð11ðð INPUT-OUTPUT SECTION. ð3/ð7/94
12 ðð12ðð FILE-CONTROL. ð3/ð7/94
13 ðð13ðð SELECT FILE-1 ASSIGN TO DISK-SALES. ð3/22/94
14 ðð14ðð DATA DIVISION. ð3/ð7/94
15 ðð15ðð FILE SECTION. ð3/ð7/94
16 ðð16ðð FD FILE-1 ð3/ð7/94
17 ðð17ðð LABEL RECORDS ARE STANDARD. ð2/17/94
18 ðð18ðð ð1 RECORD-1. ð3/ð7/94
19 ðð19ðð ð5 R-TYPE PIC X(1). ð2/17/94
2ð ðð2ððð ð5 R-AREA-CODE PIC 9(2). ð2/17/94
21 ðð21ðð 88 R-NORTH-EAST VALUES 15 THROUGH 3ð. ð2/17/94
22 ðð22ðð ð5 R-SALES-CAT-1 PIC S9(5)V9(2) COMP-3. ð2/17/94
23 ðð23ðð ð5 R-SALES-CAT-2 PIC S9(5)V9(2) COMP-3. ð2/17/94
24 ðð24ðð ð5 FILLER PIC X(1). ð2/17/94
ðð25ðð ð2/17/94
25 ðð26ðð WORKING-STORAGE SECTION. ð3/ð7/94
26 ðð27ðð ð1 W-SALES-VALUES. ð2/17/94
27 ðð28ðð ð5 W-CAT-1 PIC S9(8)V9(2). ð2/17/94
28 ðð29ðð ð5 W-CAT-2 PIC S9(8)V9(2). ð2/17/94
29 ðð3ððð ð5 W-TOTAL PIC S9(8)V9(2). ð2/17/94
ðð31ðð ð2/17/94
3ð ðð32ðð ð1 W-EDIT-VALUES. ð2/17/94
31 ðð33ðð ð5 FILLER PIC X(8) VALUE "TOTALS: ". ð2/17/94
32 ðð34ðð ð5 W-EDIT-1 PIC Z(7)9.9(2)-. ð2/17/94
33 ðð35ðð ð5 FILLER PIC X(3) VALUE SPACES. ð2/17/94
34 ðð36ðð ð5 W-EDIT-2 PIC Z(7)9.9(2)-. ð2/17/94
35 ðð37ðð ð5 FILLER PIC X(3) VALUE SPACES. ð2/17/94
36 ðð38ðð ð5 W-EDIT-TOTAL PIC Z(7)9.9(2)-. ð2/17/94
ðð39ðð ð2/17/94
37 ðð4ððð ð1 END-FLAG PIC X(1) VALUE SPACE. ð2/17/94
38 ðð41ðð 88 END-OF-INPUT VALUE "Y". ð2/17/94
ðð42ðð ð2/17/94
39 ðð43ðð PROCEDURE DIVISION. ð2/17/94
ðð44ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð2/17/94
ðð45ðð\ OPEN THE INPUT FILE, CLEAR TOTALS, CALL MAIN PROCESS THEN \ ð2/17/94
ðð46ðð\ DISPLAY THE RESULTS AND END THE RUN. \ ð2/17/94
ðð47ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ ð2/17/94
ðð48ðð P-START. ð2/17/94
4ð ðð49ðð OPEN INPUT FILE-1. ð2/17/94
41 ðð5ððð MOVE ZEROS TO W-SALES-VALUES. ð2/17/94
42 ðð51ðð PERFORM P-MAIN UNTIL END-OF-INPUT. ð2/17/94
ðð52ðð ð2/17/94
43 ðð53ðð MOVE W-CAT-1 TO W-EDIT-1. ð2/17/94
44 ðð54ðð MOVE W-CAT-2 TO W-EDIT-2. ð2/17/94
45 ðð55ðð MOVE W-TOTAL TO W-EDIT-TOTAL. ð2/17/94
46 ðð56ðð DISPLAY W-EDIT-VALUES.
47 ðð57ðð STOP RUN.
ðð58ðð
ðð59ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð6ððð\ READ THE INPUT FILE PROCESSING ONLY THOSE RECORDS FOR THE \
ðð61ðð\ NORTH EAST AREA. WHEN END-OF-INPUT REACHED, SET THE FLAG \
ðð62ðð\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
ðð63ðð P-MAIN.
48 ðð64ðð READ FILE-1 AT END SET END-OF-INPUT TO TRUE.
5ð ðð65ðð IF R-NORTH-EAST AND NOT END-OF-INPUT
51 ðð66ðð ADD R-SALES-CAT-1 TO W-CAT-1, W-TOTAL
52 ðð67ðð ADD R-SALES-CAT-2 TO W-CAT-2, W-TOTAL.
\ \ \ \ \ E N D O F S O U R C E \ \ \ \ \

MCH12ð2 exception in program XMPLDUMP in QTEMP at MI instruction number ðð5C COBOL statement number 51..A/
Last I-O operation was at statement 48..B/
LBE79ð3-Information pertaining to file FILE-1..C/
LBE79ð5-File is open.
LBE79ð6-Last I-O operation completed for file was READ.
LBE79ð7-Last file status for file was ð4.
LBE791ð-Last extended file status for file was.

Figure 120 (Part 1 of 10). Example of a COBOL Formatted Dump

372 COBOL/400 User’s Guide


FORMATTED DATA DUMP FOR PROGRAM XMPLDUMP.QTEMP 13:39:ð8 ð5/24/94
NAME OFFSET ATTRIBUTES VALUE .D/
.ADBUF ððð48ð POINTER(SPP) NULL
.ADBUFVL ðððB9ð CHAR(68) ' '
ðððB9ð VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ðððBB8 +41 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
.ADDEV ððð4B4 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.ADENV ððð493 CHAR(1) 'I'
.ADFILE ððð4Cð POINTER(SPP) NULL
.ADFUNC ððð49ð CHAR(1) ' ' 'ðð'X
.ADLN ððð494 BINARY(2) ð
.ADMID ððð496 BINARY(2) ð
.ADPGM ððð49B CHAR(1ð) 'XMPLDUMP '
.ADRLN ððð498 BINARY(2) ð
.ADRTN ððð47ð POINTER(IP) NULL
.ADRTYP ððð49A CHAR(1) ' ' 'ðð'X
.ADTOD ððð4A5 CHAR(15) ' ' 'ðððððððððððððððððððððððððððððð'X
.ADTYP ððð491 BINARY(2) ð
.BINSUB ððð558 BINARY(4) ð
.BIN2 ððð55C BINARY(2) ð
.BPCA ððð4Bð CHAR(32767) ' A T Dð1 <HHH D12 <HHH D15 <H'
ððð5ðA +91 'HH D15 <HHH D22 <HHH D99 <HHH '
ððð564 +181 ' Dð1 <HHH D23 <HHH D25 <HHH '
ððð4Bð VALUE IN HEX '8ððððððððððððððððð3DC19EB7ðððA4ðððð1ððA3ðð19ðððE4ð4ð4ð4ð4ð4ð4ð4ðC4FðF14444444C88'X
ððð4D8 +41 '88888C4ð4ð4ðððð1ððððððð1ðððððððð4ðC4F1F24444444C8888888C4ð4ð4ðððð1ððððððð2ðððððð'X
ððð5ðð +81 'ðð4ðC4F1F54444444C8888888C4ð4ð4ðððð1ððððððð3ðððððððð4ðC4F1F54444444C8888888C4ð4ð'X
ððð528 +121 '4ðððð1ððððððð4ðððððððð4ðC4F2F24444444C8888888C4ð4ð4ðððð1ððððððð5ðððððððð4ðC4F9F9'X
ððð55ð +161 '4444444C8888888C4ð4ð4ðððð1ððððððð6ðððððððð4ðC4FðF14444444C8888888C4ð4ð4ðððð1ðððð'X
ððð578 +2ð1 'ððð7ðððððððð4ðC4F2F34444444C8888888C4ð4ð4ðððð1ððððððð8ðððððððð4ðC4F2F54444444C88'X
ððð5Að +241 '88888C4ð4ð4ðððð1ððððððð9ðððððððð'X
.BPCACTR ððð4Cð BINARY(2) 1
.BPCAFB ððð4C6 BINARY(2) 14
.BPCAMXR ððð4C2 BINARY(2) 163
.BPCARCD ððð4Bð POINTER(SPP) SPACE OFFSET 1632 'ððððð66ð'X
OBJECT SALES COBOLEX SALESFILE
.BPCARIO ððð4C4 BINARY(2) 25
.BPð1CA ððð4Bð CHAR(32767) ' A T Dð1 <HHH D12 <HHH D15 <H'
ððð5ðA +91 'HH D15 <HHH D22 <HHH D99 <HHH '
ððð564 +181 ' Dð1 <HHH D23 <HHH D25 <HHH '
ððð4Bð VALUE IN HEX '8ððððððððððððððððð3DC19EB7ðððA4ðððð1ððA3ðð19ðððE4ð4ð4ð4ð4ð4ð4ð4ðC4FðF14444444C88'X
ððð4D8 +41 '88888C4ð4ð4ðððð1ððððððð1ðððððððð4ðC4F1F24444444C8888888C4ð4ð4ðððð1ððððððð2ðððððð'X
ððð5ðð +81 'ðð4ðC4F1F54444444C8888888C4ð4ð4ðððð1ððððððð3ðððððððð4ðC4F1F54444444C8888888C4ð4ð'X
ððð528 +121 '4ðððð1ððððððð4ðððððððð4ðC4F2F24444444C8888888C4ð4ð4ðððð1ððððððð5ðððððððð4ðC4F9F9'X
ððð55ð +161 '4444444C8888888C4ð4ð4ðððð1ððððððð6ðððððððð4ðC4FðF14444444C8888888C4ð4ð4ðððð1ðððð'X
ððð578 +2ð1 'ððð7ðððððððð4ðC4F2F34444444C8888888C4ð4ð4ðððð1ððððððð8ðððððððð4ðC4F2F54444444C88'X
ððð5Að +241 '88888C4ð4ð4ðððð1ððððððð9ðððððððð'X
.BPð1CTR ððð4Cð BINARY(2) 1
.BPð1FB ððð4C6 BINARY(2) 14
.BPð1MXR ððð4C2 BINARY(2) 163
.BPð1RCD ððð4Bð POINTER(SPP) SPACE OFFSET 1632 'ððððð66ð'X
OBJECT SALES COBOLEX SALESFILE
.BPð1RIO ððð4C4 BINARY(2) 25
.BSTRING NOT ADDRESSABLE
.BUFFER NOT ADDRESSABLE
.BUFPTR ððð77ð POINTER(SPP) NULL
.CALERP ððð58ð POINTER(SPP) SPACE OFFSET 1376 'ððððð56ð'X
OBJECT PSSA
.CALLOWR ðððC7ð CHAR(27) ' ETAOINSHRDLUCMFWYPVBGKQJXZ' '4ð85A381968995A288998493A4839486A6A897A58287929891A7A9'X
.CALPHAB ðððC2ð CHAR(53) ' ETAOINSHRDLUCMFWYPVBGKQJXZETAOINSHRDLUCMFWYPVBGKQJXZ'
ðððC2ð VALUE IN HEX '4ðC5E3C1D6C9D5E2C8D9C4D3E4C3D4C6E6E8D7E5C2C7D2D8D1E7E985A381968995A288998493A483'X
ðððC48 +41 '9486A6A897A58287929891A7A9'X
.CALUPPR ðððC55 CHAR(27) ' ETAOINSHRDLUCMFWYPVBGKQJXZ'
.CIMBSGN ðððBDA CHAR(6ð) 'ð123456789 JKLMNOPQR STUVWXYZ ABCDEFGHI STUVWXYZ'
ðððBDA VALUE IN HEX 'FðF1F2F3F4F5F6F7F8F9DðD1D2D3D4D5D6D7D8D9AðA1A2A3A4A5A6A7A8A9BðB1B2B3B4B5B6B7B8B9'X
ðððCð2 +41 'CðC1C2C3C4C5C6C7C8C9EðE1E2E3E4E5E6E7E8E9'X
.CNUMERC ðððC16 CHAR(1ð) 'ð123456789'
.CPADCHR ðððC8B CHAR(1) ' '
.CRCLEAR ðððDðð POINTER(SYP) OBJECT QLRCLEAR
CONTEXT QSYS
.CSEPSGN ðððBD8 CHAR(2) '+-'
.DBUGRTN ððð45ð POINTER(IP) NULL
.DEVPTR ððð73ð POINTER(SPP) SPACE OFFSET 324 'ððððð144'X
OBJECT SALES COBOLEX SALESFILE
.DISPPOS ðððCBð BINARY(2) ð
.DISPPTR ðððCAð POINTER(SPP) NULL
.DLINENO ððð552 CHAR(6) ' ' 'ðððððððððððð'X
.DMCACIN ððð87ð BINARY(2) 121
.DMCACQR ððð872 BINARY(2) 66

Figure 120 (Part 2 of 10). Example of a COBOL Formatted Dump

Appendix H. Example of a COBOL Formatted Dump 373


.DMCBLKR ððð3BD CHAR(1) '\'
.DMCCPCL ððð178 BINARY(2) 13
.DMCCPOP ððð17A BINARY(2) 17
.DMCDBOF ðððð2ð BINARY(4) 7ð4
.DMCDDS ððð2Cð CHAR(298) ' R A ð A ð '
ððð31A +91 ' TY '
ððð374 +181 ' 3 CPF \ '
ððð2Cð VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð8ððððððððððð8ððð'X
ððð2E8 +41 'ðð1ððð99ðFððð4Bð8ððððððððððððððððð3DC19EB7ððð6Fð8ððððððððððððððððð3DC19EB7ððð6Fð'X
ððð31ð +81 '48ððððððððððððððððððððA3E8ðððð11ðððððððððððððððððððððððððððððððððððððððððððððð19'X
ððð338 +121 'ðððððððEðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð36ð +161 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð388 +2ð1 'ððððððððððððððððððððððððððððððððððððððððððððððððððððððððF3ððððð1ðððððððððððððððð'X
ððð3Bð +241 'ððFFððððððC3D7C6ðððððððððð5CEððð'X
.DMCDELT ððð166 BINARY(2) 69
.DMCDROP ððð874 BINARY(2) 71
.DMCFDEL ððð3E9 CHAR(1) ' ' 'ðð'X
.DMCFEOD ððð168 BINARY(2) 111
.DMCFRCE ððð16A BINARY(2) 69
.DMCGET ððð158 BINARY(2) 77ð
.DMCGETD ððð15A BINARY(2) 14
.DMCGETK ððð15C BINARY(2) 69
.DMCLINK ððð7A5 BINARY(2) ð
.DMCODP ðððððð CHAR(32767) 'E M M F A '
ðððð5A +91 ' A DBSA'
ððððB4 +181 'LES COBOLEX SALESFILE A'
ðððððð VALUE IN HEX '85ððððð2ðððð14D4ðððð14D4ððððððBðððððð14ðððððð1C6ððððð28ðððððððððððððð2Cððððððððð'X
ðððð28 +41 'ððððððððððððð14ððððððððððððððððððððððððððððððððððððððððððððððððððð3DC19EB7ðððDFF'X
ðððð5ð +81 'ðððððððððððððððððððððððððððððððð8ððððððððððððððððð3DCððð36ðððAEð8ððððððððððððððð'X
ðððð78 +121 'ðð3DC19EB7ðð189Bððððððððððððððððððððððððððððððððð19ððððððððððððððððððððCðððððððð'X
ððððAð +161 'ðCððððððððððððððððð4BðððððððððððC4C2E2C1D3C5E24ð4ð4ð4ð4ðC3D6C2F3F8C5E74ð4ð4ððððð'X
ððððC8 +2ð1 'ðððððððððððððððððððððððððððððððððððððððððððEððððE2C1D3C5E2C6C9D3C54ððððð1ðð4ðððð'X
ððððFð +241 'ðððððððððððððððððððððððððððð11C1'X
.DMCOFFS ðððð1ð BINARY(4) 32ð
.DMCPTGT ððð162 BINARY(2) 69
.DMCPUT ððð16ð BINARY(2) 69
.DMCPUTD ððð15E BINARY(2) 69
.DMCRLSE ððð17ð BINARY(2) 69
.DMCRSTD ððð16E BINARY(2) 69
.DMCSPDD ððð16C BINARY(2) 69
.DMCSPTB ððð17C BINARY(2) ð
.DMCTBLE ððð17E BINARY(2) 1
.DMCUPD ððð164 BINARY(2) 69
.DMPBDMJ NOT ADDRESSABLE
.DMPBDSE NOT ADDRESSABLE
.DMPCDFO ððð1C6 BINARY(2) 144
.DMPCDFP ððð79ð POINTER(SPP) NULL
.DMPDBFB NOT ADDRESSABLE
.DMPDBFL ððð19ð CHAR(1) ' ' 'ðð'X
.DMPDENT ððð144 CHAR(13ð) DIMENSION(25ð)
ððð144 (1) 'DATABASE ? '
ððð19E +91 ' '
ððð144 VALUE IN HEX 'C4C1E3C1C2C1E2C54ð4ðððððððððððððððððððððð3ð2ðððEðð45ðð45ðð45ðð45ðð45ðð45ðð6Fðð45'X
ððð16C +41 'ðð45ðð45ðð45ðBFDðð45ðð45ðððDðð11ððððððð1ðððððððððððððððððððððððððððððððððððððððð'X
ððð194 +81 2 LINES OF ZEROES SUPPRESSED
ððð1C6 (2) ' SALESFILE '
ððð22ð +91 ' '
ððð1C6 VALUE IN HEX 'ðð9ðððððððððððððððð1ððððððððððððððððððð1E2C1D3C5E2C6C9D3C54ððððððððððððððððððððð'X
ððð1EE +41 'ðððððððððððEðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð216 +81 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð23E +121 'ðððððððððððððð11ðððð'X
ððð248 (3) ' R '
ððð2A2 +91 ' R AA '
ððð248 VALUE IN HEX 'ðððððððððððððððððððððððððððððððððð22ððððððððððððððððððð1ððððð48ðððð4ðððððððððððð'X
ððð27ð +41 'ððððððð1ðððððð11ððððððððððððððððððððððð2ðð3ððððððððððððððððð3ððððððððððððððððððð'X
ððð298 +81 'ðð1ððð99ðEðððDFFðððððððððððððð18ðð1ððð99ðBðððB1ð8181ðððððððððððððððððððððððððððð'X
ððð2Cð +121 'ðððððððððððððððððððð'X
ððð2CA (4) ' R A ð A ð TY '
ððð324 +91 ' '
ððð2CA VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððð8ððððððððððð8ððððð1ððð99ðFððð4Bð8ððð'X
ððð2F2 +41 'ðððððððððððððð3DC19EB7ððð6Fð8ððððððððððððððððð3DC19EB7ððð6Fð48ðððððððððððððððððð'X
ððð31A +81 'ððA3E8ðððð11ðððððððððððððððððððððððððððððððððððððððððððððð19ðððððððEðððððððððððð'X
ððð342 +121 'ðððððððððððððððððððð'X
ððð34C (5) ' 3 '
ððð3A6 +91 ' CPF \ T '
ððð34C VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð374 +41 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð39C +81 'ððððððððððððððððF3ððððð1ððððððððððððððððððFFððððððC3D7C6ðððððððððð5CEððððððððð3C'X

Figure 120 (Part 3 of 10). Example of a COBOL Formatted Dump

374 COBOL/400 User’s Guide


ððð3C4 +121 'ððA3ðððððððððððððððð'X
ððð3CE (6) ' '
ððð428 +91 ' SALESFILE 2A248'
ððð3CE VALUE IN HEX 'ððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð1ðððð'X
ððð3F6 +41 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð41E +81 'ðððððððððððððððððððððð11ðððððððððððððððððððððððððððððððEððððððððððð1E2C1D3C5E2C6'X
ððð446 +121 'C9D3C54ðððF2C1F2F4F8'X
ððð45ð (7) '33FFð3CF U & '
ððð4AA +91 ' A T Dð'
ððð45ð VALUE IN HEX 'F3F3C6C6FðF3C3C6ðððððððððððEððð1ððððððð1ðððððððððððððððððððððððððððððððððððððððð'X
ððð478 +41 'ððððððððððððððððððððððððððððððððððððððððððððððððA4ðððððððððððð5ððððððððððððððððð'X
ððð4Að +81 'ðððððððððððððððððððððððððððððððð8ððððððððððððððððð3DC19EB7ðððA4ðððð1ððA3ðð19ðððE'X
ððð4C8 +121 '4ð4ð4ð4ð4ð4ð4ð4ðC4Fð'X
ððð4D2 (8) '1 <HHH D12 <HHH D15 <HHH D15 <HHH '
ððð52C +91 ' D22 <HHH D99 <'
ððð4D2 VALUE IN HEX 'F14444444C8888888C4ð4ð4ðððð1ððððððð1ðððððððð4ðC4F1F24444444C8888888C4ð4ð4ðððð1ðð'X
ððð4FA +41 'ððððð2ðððððððð4ðC4F1F54444444C8888888C4ð4ð4ðððð1ððððððð3ðððððððð4ðC4F1F54444444C'X
ððð522 +81 '8888888C4ð4ð4ðððð1ððððððð4ðððððððð4ðC4F2F24444444C8888888C4ð4ð4ðððð1ððððððð5ðððð'X
ððð54A +121 'ðððð4ðC4F9F94444444C'X
ððð554 (9) 'HHH Dð1 <HHH D23 <HHH D25 <HHH '
ððð5AE +91 ' D88 <HHH D99 <HHH '
ððð554 VALUE IN HEX '8888888C4ð4ð4ðððð1ððððððð6ðððððððð4ðC4FðF14444444C8888888C4ð4ð4ðððð1ððððððð7ðððð'X
ððð57C +41 'ðððð4ðC4F2F34444444C8888888C4ð4ð4ðððð1ððððððð8ðððððððð4ðC4F2F54444444C8888888C4ð'X
ððð5A4 +81 '4ð4ðððð1ððððððð9ðððððððð4ðC4F8F84444444C8888888C4ð4ð4ðððð1ðððððððAðððððððð4ðC4F9'X
ððð5CC +121 'F94444444C8888888C4ð'X
ððð5D6 (1ð) ' D22 <HHH Dð1 <HHH D66 <HHH D2'
ððð63ð +91 '2 <HHH D77 <HHH '
ððð5D6 VALUE IN HEX '4ð4ðððð1ðððððððBðððððððð4ðC4F2F24444444C8888888C4ð4ð4ðððð1ðððððððCðððððððð4ðC4Fð'X
ððð5FE +41 'F14444444C8888888C4ð4ð4ðððð1ðððððððDðððððððð4ðC4F6F64444444C8888888C4ð4ð4ðððð1ðð'X
ððð626 +81 'ðððððEðððððððð4ðC4F2F24444444C8888888C4ð4ð4ðððð1ðððððððFðððððððð4ðC4F7F74444444C'X
ððð64E +121 '8888888C4ð4ð4ðððð1ðð'X
ððð658 (11) ' H25ðððððððð < '
ððð658 VALUE IN HEX 'ðððð1ððððððððð4ðC8F2F5FðFðFðFðFðFðFðFð4ð4ð4Cððð1ðððððð11ðððððððð4ð4ð4ð4ð4ð4ð4ð4ð'X
ððð68ð +41 '4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð'X
ððð6A8 +81 '4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð'X
ððð6Dð +121 '4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð'X
ðð14ðE (12-38) ' '
ðð149ð (39) ' '
ðð14EA +91 ' '
ðð149ð VALUE IN HEX '4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð'X
ðð14B8 +41 '4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ððððððððððððððððððððððððð'X
ðð14Eð +81 2 LINES OF ZEROES SUPPRESSED
CANNOT DUMP - SPACE ADDRESSING OR BOUNDARY ALIGNMENT EXCEPTION
.DMPDEVN ððð1E6 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.DMPDIOF NOT ADDRESSABLE
.DMPDRN NOT ADDRESSABLE
.DMPDSEK NOT ADDRESSABLE
.DMPDVNM ððð144 CHAR(1ð) 'DATABASE '
.DMPENT ððð144 CHAR(13ð) 'DATABASE ? '
ððð19E +91 ' '
ððð144 VALUE IN HEX 'C4C1E3C1C2C1E2C54ð4ðððððððððððððððððððððð3ð2ðððEðð45ðð45ðð45ðð45ðð45ðð45ðð6Fðð45'X
ððð16C +41 'ðð45ðð45ðð45ðBFDðð45ðð45ðððDðð11ððððððð1ðððððððððððððððððððððððððððððððððððððððð'X
ððð194 +81 2 LINES OF ZEROES SUPPRESSED
.DMPFBAC ððððBð CHAR(32767) 'DBSALES COBOLEX SALESFILE AR NU '
ððð1ðA +91 '& T DATABASE '
ððð164 +181 ' ? '
ððððBð VALUE IN HEX 'C4C2E2C1D3C5E24ð4ð4ð4ð4ðC3D6C2F3F8C5E74ð4ð4ððððððððððððððððððððððððððððððððððððð'X
ððððD8 +41 'ðððððððððððEððððE2C1D3C5E2C6C9D3C54ððððð1ðð4ðððððððððððððððððððððððððððððððð11C1'X
ððð1ðð +81 'D9ððD5A4ðððððððððððð5ðððððððððððððððððððððððððððððððA3ðððððð19ððððð3Eððððððððððð'X
ððð128 +121 'ððððððððððððððð1ððððððð1ð2ððððððððððððððððððððððððð1ððð1C4C1E3C1C2C1E2C54ð4ððððð'X
ððð15ð +161 'ððððððððððððððððð3ð2ðððEðð45ðð45ðð45ðð45ðð45ðð45ðð6Fðð45ðð45ðð45ðð45ðBFDðð45ðð45'X
ððð178 +2ð1 'ðððDðð11ððððððð1ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð1Að +241 'ðððððððððððððððððððððððððððððððð'X
.DMPFBAT ððððFF CHAR(2) 'AR'
.DMPFBCL ððððF9 BINARY(2) ð
.DMPFBCT ðð8ð38 BINARY(2) CANNOT DUMP - SPACE ADDRESSING OR BOUNDARY ALIGNMENT EXCEPTION
.DMPFBDC ððððF2 BINARY(2) ð
.DMPFBDE ðð8ð3C CHAR(5ð) DIMENSION(32)
CANNOT DUMP - SPACE ADDRESSING OR BOUNDARY ALIGNMENT EXCEPTION
.DMPFBDU ððð1ð1 CHAR(1) ' ' 'ðð'X
.DMPFBFN ððððB2 CHAR(1ð) 'SALES '
.DMPFBH1 NOT ADDRESSABLE
.DMPFBH2 NOT ADDRESSABLE
.DMPFBIB ððððEA BINARY(4) 41ðð
.DMPFBLN ððððBC CHAR(1ð) 'COBOLEX '
.DMPFBLO ððð117 BINARY(2) ð
.DMPFBLP ððð74ð POINTER(SPP) NULL
.DMPFBLS NOT ADDRESSABLE

Figure 120 (Part 4 of 10). Example of a COBOL Formatted Dump

Appendix H. Example of a COBOL Formatted Dump 375


.DMPFBL1 ððððDC BINARY(2) 14
.DMPFBL2 ððððDE BINARY(2) ð
.DMPFBMF ððð123 CHAR(1) ' ' 'ðð'X
.DMPFBMN ððððEð CHAR(1ð) 'SALESFILE '
.DMPFBND ðð8ð3A BINARY(2) CANNOT DUMP - SPACE ADDRESSING OR BOUNDARY ALIGNMENT EXCEPTION
.DMPFBOB ððððEE BINARY(4) ð
.DMPFBOF ððð1ðD CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.DMPFBOL ððððF4 CHAR(3) ' ' 'ðððððð'X
.DMPFBPO ððð11F BINARY(4) 992
.DMPFBQN ððð124 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.DMPFBRC ððððFB BINARY(4) 17
.DMPFBRW ððððF7 BINARY(2) ð
.DMPFBSC ððð1ð2 CHAR(1) 'N'
.DMPFBSF ððððC6 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.DMPFBSL ððððDð CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.DMPFBSN ððððDA BINARY(2) ð
.DMPFBTY ððððBð CHAR(2) 'DB'
.DMPFBUF ððð1ð3 CHAR(1ð) 'U & ' 'A4ðððððððððððð5ððððð'X
.DMPFBVL NOT ADDRESSABLE
.DMPIOFB ððð1C6 CHAR(32767) ' SALESFILE '
ððð22ð +91 ' '
ððð27A +181 ' R R AA '
ððð1C6 VALUE IN HEX 'ðð9ðððððððððððððððð1ððððððððððððððððððð1E2C1D3C5E2C6C9D3C54ððððððððððððððððððððð'X
ððð1EE +41 'ðððððððððððEðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð216 +81 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð23E +121 'ðððððððððððððð11ðððððððððððððððððððððððððððððððððððððð22ððððððððððððððððððð1ðððð'X
ððð266 +161 'ð48ðððð4ððððððððððððððððððð1ðððððð11ððððððððððððððððððððððð2ðð3ððððððððððððððððð'X
ððð28E +2ð1 '3ððððððððððððððððððððð1ððð99ðEðððDFFðððððððððððððð18ðð1ððð99ðBðððB1ð8181ðððððððð'X
ððð2B6 +241 'ðððððððððððððððððððððððððððððððð'X
.DMPIOFS ððð1C6 CHAR(144) ' SALESFILE '
ððð22ð +91 ' '
ððð1C6 VALUE IN HEX 'ðð9ðððððððððððððððð1ððððððððððððððððððð1E2C1D3C5E2C6C9D3C54ððððððððððððððððððððð'X
ððð1EE +41 'ðððððððððððEðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð216 +81 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð23E +121 'ðððððððððððððð11ðððððððððððððððððððððððððððððððð'X
.DMPKYLN NOT ADDRESSABLE
.DMPNDEV ððð142 BINARY(2) 1
.DMPOFBS ððððBð CHAR(17126) DIMENSION(2)
CANNOT DUMP - SPACE ADDRESSING OR BOUNDARY ALIGNMENT EXCEPTION
.DMPRCD NOT ADDRESSABLE
.DMPRCDN NOT ADDRESSABLE
.DMPRDUP NOT ADDRESSABLE
.DMPRFMT ððð1DA CHAR(1ð) 'SALESFILE '
.DMPRRN NOT ADDRESSABLE
.DMPSRC NOT ADDRESSABLE
.EXCODE ðððD3ð CHAR(1) ' ' 'ðð'X
.EXMSGID ðððD35 CHAR(4) ' ' 'ðððððððð'X
.EXPARMS ðððD3ð CHAR(12) ' ' 'ðððððððððððððððððððððððð'X
.EXPTR ðððD4ð POINTER(SPP) SPACE OFFSET 3376 'ðððððD3ð'X
OBJECT PSSA
.FCLPP ððð6DF CHAR(3) ' ' 'ðððððð'X
.FCLSTC ððð6DC CHAR(12) ' ' 'ðððððððððððððððððððððððð'X
.FCLSTC# ððð6Dð CHAR(12) ' PU ' 'ðDððð3D7E44ðð6ððð2ððð1FF'X
.FCLSTP ððð6FF CHAR(21) ' ' 'ðððððððððððððððððððððððððððððððððððððððððð'X
.FCLSTP# ððð6EA CHAR(21) ' ' 'ð9ððð2ðððððAððð2ðððððBððð2ðððððCððð2ððððFF'X
.FCPARM ððð5Bð CHAR(22) ' '
.FCPARMP ððð5Dð POINTER(SPP) SPACE OFFSET 1456 'ððððð5Bð'X
OBJECT PSSA
.FCPTR ððð5Að POINTER(SYP) OBJECT QLREXHAN
CONTEXT QSYS
.FIB ððð8Að CHAR(32767) 'FILE-1 ð4ðð '
ððð8FA +91 ' A '
ððð954 +181 ' '
ððð8Að VALUE IN HEX 'C6C9D3C56ðF14ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ððð8ðð3ððððð1FðF4FðFð'X
ððð8C8 +41 'ððð4ðððððððððððððððððððððððððððððððð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ðððððððððð1ððð1ððð1ðððCðð'X
ððð8Fð +81 '8ððððððððððððððððð3DCððð36ðððAEððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð918 +121 'ðððððððððððððððððððððððððððððððððððððððððððððððð8ððððððððððððððððð3DC19EB7ððð89ð'X
ððð94ð +161 '4ð4ð4ð4ð4ð4ð4ð4ð4ð4ðððð1ðððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð968 +2ð1 2 LINES OF ZEROES SUPPRESSED
.FIB#OPT ððð62C CHAR(8) ' ' 'ðððððððððððððððð'X
.FIB#OP1 NOT ADDRESSABLE
.FIBACC ððð8E9 BINARY(2) 1
.FIBACQ ððð6E8 BINARY(2) ð
.FIBACTL ððð6Cð CHAR(8) ' ' '16ððð4ððððððððFF'X
.FIBALT ððð8BE CHAR(1) ' ' 'ðð'X
.FIBCA ððð955 CHAR(22) ' ' 'ðððððððððððððððððððððððððððððððððððððððððððð'X
.FIBCFMT ððð961 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.FIBCFS ððð8C4 CHAR(2) 'ð4'

Figure 120 (Part 5 of 10). Example of a COBOL Formatted Dump

376 COBOL/400 User’s Guide


.FIBCFS1 ððð8C4 CHAR(1) 'ð'
.FIBCFS2 ððð94C CHAR(4) ' ' 'ðððððððð'X
.FIBCHAN ððð92ð POINTER(SPP) NULL
.FIBCKID ððð955 ZONED(2,ð) \\ 'ðððð'X
.FIBCOP ððð8Cð CHAR(4) ' ' 'ð3ððððð1'X
.FIBCRP ððð8E4 CHAR(1) ' ' 'ðð'X
.FIBCTID ððð957 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.FIBCTL ððð75ð POINTER(SPP) NULL
.FIBCUR ððð8Cð CHAR(6) ' ð4' 'ð3ððððð1FðF4'X
.FIBCURK ððð634 CHAR(123) ' '
ððð68E +91 ' '
ððð634 VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð65C +41 3 LINES OF ZEROES SUPPRESSED
.FIBDEVC ððð8E5 BINARY(2) ð
.FIBDEVI ððð94A BINARY(2) 1
.FIBDEVN ððð94ð CHAR(1ð) ' '
.FIBFLGS ððð8BF CHAR(1) ' ' '8ð'X .E/
.FIBFMT ððð8DA CHAR(1ð) ' '
.FIBFN ððð8Að CHAR(3ð) 'FILE-1 '
.FIBK#LN ððð62D BINARY(2) ð
.FIBK#R# ððð62F BINARY(4) ð
.FIBK#RK ððð631 BINARY(2) ð
.FIBK#TP ððð62C CHAR(1) ' ' 'ðð'X
.FIBKCGK ððð6ðð CHAR(8) ' ' 'ð8ððð4ððððððððð9'X
.FIBKCGR ððð6ð8 CHAR(8) ' ' 'ð2ððð4ððððððððFF'X
.FIBKCPD ððð61ð CHAR(8) ' ' 'ð4ððð4ððððððððFF'X
.FIBKCTL ððð618 BINARY(2) ð
.FIBKDLN ððð628 BINARY(2) 2
.FIBKDM# ððð62A BINARY(2) ð
.FIBKDTP ððð627 CHAR(1) ' ' 'ðF'X
.FIBKEY ððð8CA BINARY(4) ð
.FIBKFLN ððð61B BINARY(2) 1ð
.FIBKFMT ððð61D CHAR(1ð) ' '
.FIBKFTP ððð61A CHAR(1) ' ' 'ð1'X
.FIBKKEY ððð636 CHAR(121) ' '
ððð69ð +91 ' '
ððð636 VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð65E +41 3 LINES OF ZEROES SUPPRESSED
.FIBKKLN ððð634 BINARY(2) ð
.FIBKKTP ððð633 CHAR(1) ' ' 'ðð'X
.FIBKLEN ððð8CE BINARY(2) ð
.FIBKSTC ððð62C CHAR(1) ' ' 'ðð'X
.FIBKSTE ððð631 CHAR(1) ' ' 'ðð'X
.FIBKSTL ððð62D BINARY(2) ð
.FIBKSTT ððð62F BINARY(2) ð
.FIBLBO ððð8Dð BINARY(2) ð
.FIBLFT ððð8CC BINARY(2) ð
.FIBLIN ððð8CA BINARY(2) ð
.FIBLINE ððð8D2 BINARY(2) ð
.FIBLTO ððð8CE BINARY(2) ð
.FIBMBRN ððð9D6 CHAR(1ð) 'SALESFILE '
.FIBOFMT ððð9CC CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.FIBOFS ððð8C6 CHAR(2) 'ðð' .F/
.FIBOFS1 ððð8C6 CHAR(1) 'ð'
.FIBOKEY ððð953 CHAR(121) ' '
ððð9AD +91 ' '
ððð953 VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð97B +41 3 LINES OF ZEROES SUPPRESSED
.FIBOKLN ððð951 BINARY(2) ð
.FIBOLDK ððð951 CHAR(123) ' '
ððð9AB +91 ' '
ððð951 VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð979 +41 3 LINES OF ZEROES SUPPRESSED
.FIBOP ððð7A1 CHAR(4) ' ' 'ð3ððððð1'X
.FIBOP1 ððð7A1 CHAR(1) ' ' 'ð3'X
.FIBOP2 ððð7A2 CHAR(1) ' ' 'ðð'X
.FIBOP3 ððð7A3 CHAR(1) ' ' 'ðð'X
.FIBOP4 ððð7A4 CHAR(1) ' ' 'ð1'X
.FIBORG ððð8E7 BINARY(2) 1
.FIBORRN ððð951 BINARY(4) ð
.FIBOTP ððð8EB BINARY(2) 1
.FIBPTR ððð3Bð POINTER(SPP) SPACE OFFSET 22ð8 'ððððð8Að'X
OBJECT PSSA
.FIBP1 ððð93ð POINTER(SPP) SPACE OFFSET 12ðð 'ððððð4Bð'X
OBJECT SALES COBOLEX SALESFILE
.FIBRECS ððð8ED BINARY(2) 12
.FIBREL NOT ADDRESSABLE
.FIBRLPT ððð6Bð POINTER(SPP) NULL

Figure 120 (Part 6 of 10). Example of a COBOL Formatted Dump

Appendix H. Example of a COBOL Formatted Dump 377


.FIBROLC NOT ADDRESSABLE
.FIBROLE NOT ADDRESSABLE
.FIBROLL NOT ADDRESSABLE
.FIBRSL NOT ADDRESSABLE
.FIBRVAL NOT ADDRESSABLE
.FIBSPC ððð8CA CHAR(14) ' ' 'ðððððððððððððððððððððððððððð'X
.FIBTAPE ððð6C8 CHAR(8) ' ' '11ððð4ððððððððFF'X
.FIBTLEN ððð6CB BINARY(4) ð
.FIBUBTO ððð9ðð POINTER(IP) NULL
.FIBUFCB ððð8Fð POINTER(SPP) SPACE OFFSET 2528 'ððððð9Eð'X
OBJECT PSSA
.FIBURTN ððð91ð POINTER(SPP) NULL
.FIBUSAV ððð5Fð POINTER(IP) NULL
.FIBUSE# ððð8D8 BINARY(2) ð
.FIBVERB ððð8C8 BINARY(2) 4
.FSKA ððð7ðC BINARY(2) ð
.FSKB ððð7ð2 BINARY(2) ð
.FSPA ððð711 BINARY(2) ð
.FSPB ððð7ð7 BINARY(2) ð
.FSTKS ððð6E5 BINARY(2) ð
.FWTRCD ððð6C3 BINARY(4) ð
.Fð1ACC ððð8E9 BINARY(2) 1
.Fð1ALTS ððð8BE CHAR(1) ' ' 'ðð'X
.Fð1CFS2 ððð94C CHAR(4) ' ' 'ðððððððð'X
.Fð1CHAN ððð92ð POINTER(SPP) NULL
.Fð1COP ððð8Cð CHAR(4) ' ' 'ð3ððððð1'X
.Fð1CRP ððð8E4 CHAR(1) ' ' 'ðð'X
.Fð1CUR ððð8Cð CHAR(6) ' ð4' 'ð3ððððð1FðF4'X
.Fð1DEVC ððð8E5 BINARY(2) ð
.Fð1DEVI ððð94A BINARY(2) 1
.Fð1DEVN ððð94ð CHAR(1ð) ' '
.Fð1FLGS ððð8BF CHAR(1) ' ' '8ð'X
.Fð1FMT ððð8DA CHAR(1ð) ' '
.Fð1FN ððð8Að CHAR(3ð) 'FILE-1 '
.Fð1MBRN ððð9D6 CHAR(1ð) 'SALESFILE '
.Fð1OFMT ððð9CC CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.Fð1OFS ððð8C6 CHAR(2) 'ðð'
.Fð1OKLN ððð951 BINARY(2) ð
.Fð1OLDK ððð953 CHAR(121) ' '
ððð9AD +91 ' '
ððð953 VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð97B +41 3 LINES OF ZEROES SUPPRESSED
.Fð1ORG ððð8E7 BINARY(2) 1
.Fð1OTP ððð8EB BINARY(2) 1
.Fð1P1 ððð93ð POINTER(SPP) SPACE OFFSET 12ðð 'ððððð4Bð'X
OBJECT SALES COBOLEX SALESFILE
.Fð1RECS ððð8ED BINARY(2) 12
.Fð1SPC ððð8CA CHAR(14) ' ' 'ðððððððððððððððððððððððððððð'X
.Fð1UBTO ððð9ðð POINTER(IP) NULL
.Fð1UFCB ððð8Fð POINTER(SPP) SPACE OFFSET 2528 'ððððð9Eð'X
OBJECT PSSA
.Fð1URTN ððð91ð POINTER(SPP) NULL
.Fð1USE# ððð8D8 BINARY(2) ð
.Fð1VERB ððð8C8 CHAR(2) ' ' 'ððð4'X
.IOCPTR ððð86ð POINTER(SPP) SPACE OFFSET 1952 'ððððð7Að'X
OBJECT PSSA
.IOEPTR ððð84ð POINTER(SYP) OBJECT QDBGETM
CONTEXT QSYS
.IOFDBEX ððð78ð POINTER(SPP) NULL
.IOOPTR ððð85ð POINTER(SPP) SPACE OFFSET 224ð 'ððððð8Cð'X
OBJECT PSSA
.IORTN ððð3Að POINTER(IP) STMT 48 INSTR # ðððððð4F
OBJECT XMPLDUMP
CONTEXT QTEMP
.IPðððð1 ðððC9ð POINTER(IP) STMT 52 INSTR # ðððððð65
OBJECT XMPLDUMP
CONTEXT QTEMP
.MAINRTN ððð44ð POINTER(SYP) OBJECT QLRMAIN
CONTEXT QSYS
.MGT ððð23ð CHAR(16) 'COBOL MGT ðð.ðLR' .G/
.MGTBIN8 ððð347 CHAR(8) ' ' 'ðððððððððððððððð'X
.MGTB81 ððð347 BINARY(4) ð
.MGTCNTR ððð2Cð BINARY(4) DIMENSION(2ð)
ððð3ðC (4ð-2ð) ð
.MGTCPGM ððð39ð POINTER(SYP) NULL
.MGTDBUG ððð328 CHAR(1) 'ð'
.MGTEXCP ððð31C CHAR(7) ' ' .H/
.MGTFIB ððð25ð POINTER(SPP) SPACE OFFSET 22ð8 'ððððð8Að'X

Figure 120 (Part 7 of 10). Example of a COBOL Formatted Dump

378 COBOL/400 User’s Guide


OBJECT PSSA
.MGTFUNC ððð345 BINARY(2) 2
.MGTIND ððð323 CHAR(1) DIMENSION(32)
ððð329 (1-7) 'ð'
ððð32A (8) '1'
ððð342 (9-32) 'ð'
.MGTINVC ððð31A BINARY(2) 3 .I/
.MGTLIB ððð41A CHAR(1ð) 'QTEMP '
.MGTMSGI ððð3F2 CHAR(7) ' ' 'ðððððððððððððð'X
.MGTMSGN ððð3Fð BINARY(2) ð
.MGTMSGR ððð3Eð POINTER(SPP) NULL
.MGTMSGS ððð3Cð POINTER(IP) NULL
.MGTMSGT ððð3Dð POINTER(SPP) NULL
.MGTNAME ððð31ð CHAR(1ð) 'XMPLDUMP '
.MGTNEXT ððð24ð POINTER(SPP) NULL
.MGTOSZ ððð323 CHAR(1) 'ð'
.MGTOVFL ððð325 CHAR(1) 'ð'
.MGTPACK ððð34F PACKED(31,ð) \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 'ðððððððððððððððððððððððððððððððð'X
.MGTPARM ððð4ðð POINTER(SPP) NULL
.MGTPASA ððð27ð POINTER(SPP) SPACE OFFSET 576ð 'ðððð168ð'X
OBJECT PASA
.MGTPASC ððð27ð CHAR(16) ' ' '8ððððððððððððððððð3DCððð37ðð178ð'X
.MGTPCS ððð37ð POINTER(SPP) NULL
.MGTPFM ððð327 CHAR(1) 'ð'
.MGTPGM ððð2Að POINTER(SYP) OBJECT XMPLDUMP .J/
CONTEXT QTEMP
.MGTPGT ððð26ð POINTER(SPP) SPACE OFFSET 5952 'ðððð174ð'X
OBJECT PSSA
.MGTPLVL ððð361 BINARY(2) ð
.MGTPROG ððð41ð CHAR(1ð) 'XMPLDUMP '
.MGTPTP ððð38ð POINTER(SPP) SPACE OFFSET 2864 'ðððððB3ð'X
OBJECT PSSA
.MGTPTR ððð46ð POINTER(SPP) SPACE OFFSET 56ð 'ððððð23ð'X
OBJECT PSSA
.MGTRST ððð2Bð POINTER(IP) NULL
.MGTSEG ððð35F BINARY(2) ð
.MGTSEPT ððð28ð POINTER(SPP) SPACE OFFSET ð 'ðððððððð'X
OBJECT QINSEPT
CONTEXT QSYS
.MGTSOSZ ððð324 CHAR(1) 'ð'
.MGTSPCD ððð329 CHAR(1) 'ð'
.MGTSW ððð343 CHAR(1) ' ' '8ð'X
.MGTTYPE ððð344 CHAR(1) 'I'
.MGTUPTR ððð29ð POINTER(SPP) SPACE OFFSET 1984 'ððððð7Cð'X
OBJECT E34 PGMRS ð11111
.MGT9ðð1 ððð32A CHAR(1) '1'
.NULLCL ððð7Að CHAR(1) ' ' 'FF'X
.ODPBPTR ððð76ð POINTER(SPP) SPACE OFFSET ð 'ðððððððð'X
OBJECT SALES COBOLEX SALESFILE
.ODPDBAS ððð89ð POINTER(SPP) SPACE OFFSET 7ð4 'ððððð2Cð'X
OBJECT SALES COBOLEX SALESFILE
.ONSAVE ððð4Dð CHAR(32) ' '
ððð4Dð VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
.PBPDUM ððð8Að POINTER(IP) NULL
.PBPððð3 ðððB4ð POINTER(IP) STMT 42 INSTR # ðððððð3ð
OBJECT XMPLDUMP
CONTEXT QTEMP
.PERFCTR ððð55ð BINARY(2) 1
.K/
.PGT ðð174ð CHAR(32767) 'PGT ðð.ð ð1ðððððððððððððððððððððððððððððð ( .'
ðð179A +91 ' QTEMP XMPLDUMP . '
ðð17F4 +181 ' '
ðð174ð VALUE IN HEX 'D7C7E34ðFðFð4BFð4ð4ð4ð4ð4ð4ð4ð4ð8ððððððððððððððððð3DCððð36ððð33ððððððððððððððððð'X
ðð1768 +41 'ððððððððððððððððFðF1FðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFðFð'X
ðð179ð +81 'ððð3ðððððð4Dðððððð4Bð1ð4ð1D8E3C5D4D74ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð'X
ðð17B8 +121 '4ð4ð4ðð2ð1E2C1D4D7C4E4D4D74ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð38ðððððððð'X
ðð17Eð +161 'ðððððð4Bððððððððð1ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ðð18ð8 +2ð1 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð29ðð'X
ðð183ð +241 'ððððððð1ðððððððððððððððððððððððð'X
.PGTIND ðð177ð CHAR(1) DIMENSION(32)
ðð177ð (1) 'ð'
ðð1771 (2) '1'
ðð178F (3-32) 'ð'
.PGTINVC ðð179ð BINARY(2) 3 .L/
.PGTLVL ðð174ð CHAR(16) 'PGT ðð.ð '
.PGTMGTL ðð176ð POINTER(SPP) NULL
.PGTMGT1 ðð175ð POINTER(SPP) SPACE OFFSET 56ð 'ððððð23ð'X
OBJECT PSSA

Figure 120 (Part 8 of 10). Example of a COBOL Formatted Dump

Appendix H. Example of a COBOL Formatted Dump 379


.PNPððð3 ðððB4ð CHAR(48) ' T T '
ðððB4ð VALUE IN HEX '4ððððððððððððððððð3Dð3E33Cððð61A4ððððððððððððððððð3Dð3E33Cððð856ððð3ðððððððððððð'X
ðððB68 +41 'ðððððððððððððððð'X
.PTABLE ðððB3ð CHAR(16) 'PT ð1.ð ð ' 'D7E34ðFðF14BFððð1ðððð1Fððððððððð'X
.PTHSIZE ðððB37 BINARY(2) 16
.PTNUM ðððB39 BINARY(2) 1
.PTSEG ðððB3B CHAR(1) 'ð'
.Pð2ððð1 ðððCDð PACKED(2,ð) 25
.QLRDISP ðððCCð POINTER(SYP) OBJECT QLRADRTN
CONTEXT QSYS
.QLRXHAN ðððD5ð POINTER(SYP) OBJECT QLREXHAN
CONTEXT QSYS
.RCDFDBK ððð88ð POINTER(SPP) NULL
.RETURNP ððð82ð POINTER(IP) NULL
.RTNPTR ððð56ð POINTER(SPP) SPACE OFFSET 576ð 'ðððð168ð'X
OBJECT PASA
.RUNRTN ððð83ð POINTER(IP) NULL
.SAVKKEY ððð7A7 CHAR(121) ' '
ððð8ð1 +91 ' '
ððð7A7 VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ððð7CF +41 3 LINES OF ZEROES SUPPRESSED
.SEPTP ððð43ð POINTER(SPP) NULL
.SIZERP ððð59ð POINTER(SPP) SPACE OFFSET 1376 'ððððð56ð'X
OBJECT PSSA
.SUBLEN ðððD1ð BINARY(2) ð
.SUBNAME ðððD12 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.SUBTXT ðððD1ð CHAR(12) ' ' 'ðððððððððððððððððððððððð'X
.SUBTXTA ðððD2ð POINTER(SPP) SPACE OFFSET 3344 'ðððððD1ð'X
OBJECT PSSA
.SUB2FST ðððD62 CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.SUB2LEN ðððD6ð BINARY(2) ð
.SUB2SCD ðððD6C CHAR(1ð) ' ' 'ðððððððððððððððððððð'X
.SUB2TP ðððD8ð POINTER(SPP) SPACE OFFSET 3424 'ðððððD6ð'X
OBJECT PSSA
.SUB2TXT ðððD6ð CHAR(22) ' ' 'ðððððððððððððððððððððððððððððððððððððððððððð'X
.TCðððð1 ðððBD4 CHAR(2) ' ' 'ðððð'X
.TCðððð2 ðððBD6 CHAR(2) ' ' 'ðððð'X
.TMPNðð1 ðððCDð CHAR(32) ' ¬ '
ðððCDð VALUE IN HEX 'ð25Fðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
.Tððððð1 NOT ADDRESSABLE
.Tððððð2 ðððB7ð PACKED(7,2) 88888.88
.Tððððð3 ðððB7ð PACKED(7,2) 88888.88
.T1 ððð4Fð CHAR(32) ' '
ððð4Fð VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
.T2 ððð51ð CHAR(32) ' '
ððð51ð VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
.T3 ððð53ð CHAR(32) ' '
ððð53ð VALUE IN HEX 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
.UCB ððð9Eð CHAR(32767) ' A A A A A W '
ðððA3A +91 ' SALES \LIBL ð1ðð'
ðððA94 +181 ' ¢ " ¬ ðð311111ð8ðð6222'
ððð9Eð VALUE IN HEX '8ððððððððððððððððð3DC19EB7ððð3Eð8ððððððððððððððððð3DC19EB7ððð89ð8ððððððððððððððð'X
ðððAð8 +41 'ðð3DC19EB7ððð89ð8ððððððððððððððððð3DC19EB7ððð49ð8ððððððððððððððððð3DC19EB7ððð5A6'X
ðððA3ð +81 'ðððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
ðððA58 +121 'ððððððððððððððððE2C1D3C5E24ð4ð4ð4ð4ðFFB55CD3C9C2D34ð4ð4ð4ð4ðFFB94ð4ð4ð4ð4ð4ð4ð4ð'X
ðððA8ð +161 '4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ð4ðððð1ð12ðFðF1FðFðððð1654A2ððððððð2ððððððððððððððððððððððð'X
ðððAA8 +2ð1 'ððððððððððððððððððð1ðððCðð148ðððð38ððð3C8ððð3A8ðððððððð6ðð7FFFð15Fð3ðFðððððððððð'X
ðððADð +241 'FðFðF3F1F1F1F1F1FðF8FðFðF6F2F2F2'X
.UCBCLMG ðððA98 CHAR(1) ' ' '2ð'X
.UCBEDOP ðððA99 CHAR(1) ' ' 'ðð'X
.UCBFILE ðððA6ð CHAR(1ð) 'SALES '
.UCBFLGS ðððA8E CHAR(2) ' ' 'ð12ð'X
.UCBFLG1 ðððA8E CHAR(1) ' ' 'ð1'X
.UCBFLG2 ðððA8F CHAR(1) ' ' '2ð'X
.UCBIBR@ ððð9Fð POINTER(SPP) SPACE OFFSET 12ðð 'ððððð4Bð'X
OBJECT SALES COBOLEX SALESFILE
.UCBINDX ðððA8C BINARY(2) 1
.UCBIOF@ ðððA2ð POINTER(SPP) SPACE OFFSET 454 'ððððð1C6'X
OBJECT SALES COBOLEX SALESFILE
.UCBLAST ðððA82 CHAR(1ð) ' '
.UCBLBID ðððA6A BINARY(2) -75
.UCBLIB ðððA6C CHAR(1ð) '\LIBL '
.UCBLIBS ðððA6A CHAR(12) ' \LIBL ' 'FFB55CD3C9C2D34ð4ð4ð4ð4ð'X
.UCBMBID ðððA76 BINARY(2) -71
.UCBMBRS ðððA76 CHAR(12) ' ' 'FFB94ð4ð4ð4ð4ð4ð4ð4ð4ð4ð'X
.UCBMLIB ðððA78 CHAR(1ð) ' '
.UCBNXT@ ðððA3ð POINTER(SPP) NULL
.UCBOBR@ ðððAðð POINTER(SPP) SPACE OFFSET 12ðð 'ððððð4Bð'X

Figure 120 (Part 9 of 10). Example of a COBOL Formatted Dump

380 COBOL/400 User’s Guide


OBJECT SALES COBOLEX SALESFILE
.UCBODP@ ððð9Eð POINTER(SPP) SPACE OFFSET ð 'ðððððððð'X
OBJECT SALES COBOLEX SALESFILE
.UCBOPF@ ðððA1ð POINTER(SPP) SPACE OFFSET 176 'ððððððBð'X
OBJECT SALES COBOLEX SALESFILE
.UCBPARM ðððABð BINARY(2) 1
.UCBRLEN ðððAB2 BINARY(2) 12
.UCBRLVR ðððA9ð CHAR(4) 'ð1ðð'
.UCBSEP@ ðððA4ð POINTER(SPP) NULL
.UFCBPTR ððð72ð POINTER(SPP) SPACE OFFSET 2528 'ððððð9Eð'X
OBJECT PSSA
.UFLGSAV ðððCFð CHAR(2) ' ' 'ðððð'X
.USERTN ððð5Eð POINTER(IP) NULL
.USEWRK@ ðððD9ð POINTER(SPP) NULL
.Uð1CLMG ðððA98 CHAR(1) ' ' '2ð'X
.Uð1FLGS ðððA8E CHAR(2) ' ' 'ð12ð'X
.Uð1IBF@ ððð9Fð POINTER(SPP) SPACE OFFSET 12ðð 'ððððð4Bð'X
OBJECT SALES COBOLEX SALESFILE
.Uð1OBF@ ðððAðð POINTER(SPP) SPACE OFFSET 12ðð 'ððððð4Bð'X
OBJECT SALES COBOLEX SALESFILE
.Uð1SEQO ðððABF CHAR(1) ' ' '8ð'X
.Uð1UFCB ððð9Eð POINTER(SPP) SPACE OFFSET ð 'ðððððððð'X
OBJECT SALES COBOLEX SALESFILE
.VALTðð1 ðððB7ð CHAR(32) 'HHH '
ðððB7ð VALUE IN HEX '8888888Fðððððððððððððððððððððððððððððððððððððððððððððððððððððððð'X
.Vðð5622 ððð662 CHAR(1) '5'
.WCBCNLS ððð7Dð CHAR(1) 'ð'
.WCBJDAT ððð7D1 CHAR(7) 'ð89ð623' .M/
.WCBLURC ððð7Cð BINARY(2) 2
.WCBPINF ððð7C2 BINARY(2) ð
.WCBSWTC ððð7D8 CHAR(8) 'ðððððððð'
.WCBUDTA ððð7Cð CHAR(32767) ' ðð89ð623ðððððððð '
ððð81A +91 2 LINES OF BLANKS SUPPRESSED
ððð7Cð VALUE IN HEX 'ððð2ððððððððððððððððððððððððððððFðFðF8F9FðF6F2F3FðFðFðFðFðFðFðFððððððððððððððððð'X
ððð7E8 +41 6 LINES OF ZEROES SUPPRESSED
.WCBURC ððð7CE CHAR(2) ' ' 'ðððð'X
.WCBUð ððð7D8 CHAR(1) 'ð'
.WCBU1 ððð7D9 CHAR(1) 'ð'
.WCBU2 ððð7DA CHAR(1) 'ð'
.WCBU3 ððð7DB CHAR(1) 'ð'
.WCBU4 ððð7DC CHAR(1) 'ð'
.WCBU5 ððð7DD CHAR(1) 'ð'
.WCBU6 ððð7DE CHAR(1) 'ð'
.WCBU7 ððð7DF CHAR(1) 'ð'
END-FLAG ðððB28 CHAR(1) ' ' .N/
END-OF-INPUT ðððB29 CHAR(1) 'Y'
FILE-1 ððð66ð CHAR(12) 'H25ðððððððð '
FILLER ððð66B CHAR(1) ' '
FILLER ðððB13 CHAR(3) ' '
FILLER ðððBð4 CHAR(3) ' '
FILLER ðððAFð CHAR(8) 'TOTALS: '
R-AREA-CODE ððð661 ZONED(2,ð) 25
R-NORTH-EAST ðððAC9 PACKED(2,ð) 3ð
R-NORTH-EAST ðððAC7 PACKED(2,ð) 15
R-SALES-CAT-1 ððð663 PACKED(7,2)
\\INVALID DATA 'FðFðFðFð'X .O/
R-SALES-CAT-2 ððð667 PACKED(7,2)
\\INVALID DATA 'FðFðFðFð'X
R-TYPE ððð66ð CHAR(1) 'H'
RECORD-1 ððð66ð CHAR(12) 'H25ðððððððð '
W-CAT-1 ðððADð ZONED(1ð,2) 311111.ð8
W-CAT-2 ðððADA ZONED(1ð,2) 622222.16
W-EDIT-TOTAL ðððB16 CHAR(12) ' '
W-EDIT-VALUES ðððAFð CHAR(5ð) 'TOTALS: '
W-EDIT-1 ðððAF8 CHAR(12) ' '
W-EDIT-2 ðððBð7 CHAR(12) ' '
W-SALES-VALUES ðððADð CHAR(3ð) 'ðð311111ð8ðð62222216ðð93333324'
W-TOTAL ðððAE4 ZONED(1ð,2) 933333.24
STATIC STORAGE FOR PROGRAM XMPLDUMP.QTEMP BEGINS AT OFFSET ððð23ð IN THE PROGRAM STATIC STORAGE AREA (PSSA)
AUTOMATIC STORAGE FOR PROGRAM XMPLDUMP.QTEMP BEGINS AT OFFSET ðð16Cð IN THE PROGRAM AUTOMATIC STORAGE AREA (PASA)

Figure 120 (Part 10 of 10). Example of a COBOL Formatted Dump

Appendix H. Example of a COBOL Formatted Dump 381


382 COBOL/400 User’s Guide
Bibliography
For additional information about topics related to Ÿ CICS/400 Application Programming Guide,
COBOL/400 programming on the AS/400 system, refer SC33-0822
to the following IBM AS/400 publications: Short title: CICS/400 Application Programming
Guide
Ÿ Communications: Management Guide, SC41-0024
Short title: Communications Management Guide Ÿ Communications: Remote Work Station Guide,
SC41-0002
Ÿ Device Configuration Guide, SC41-8106
Short title: Remote Work Station Guide
Short title: Device Configuration Guide
Ÿ Advanced Backup and Recovery Guide, SC41-8079
Ÿ Software Installation, SC41-3120
Short title: Advanced Backup and Recovery Guide
Short title: Software Installation
Ÿ Programming: Control Language Programmer’s
Ÿ System Programmer’s Interface Reference,
Guide, SC41-8077
SC41-8223
Short title: CL Programmer’s Guide
Short title: System Programmer’s Interface
Reference Ÿ New User’s Guide, SC41-8211
Short title: New User’s Guide
Ÿ Database Guide, SC41-9659
Short title: DDS Reference Ÿ Programming: Control Language Reference,
SC41-0030
Ÿ Data Description Specifications Coding Form,
Short title: CL Reference
SX41-9891
Short title: DDS Coding Form Ÿ Publications Guide, GC41-9678
Short title: Publications Guide
Ÿ Communications: Intersystem Communications
Function Programmer’s Guide, SC41-9590 Ÿ Programming: Work Management Guide,
Short title: ICF Programmer’s Guide SC41-8078
Short title: Work Management Guide
Ÿ System Operation, SC41-3203
Short title: System Operation Ÿ Systems Application Architecture* Structured Query
Language/400 Reference, SC41-9608
Ÿ Basic Security Guide, SC41-0047 and Security
Short title: SQL/400* Reference
Reference, SC41-8083
Short titles: Basic Security Guide and Security Ÿ Data Management Guide, SC41-9658
Reference Short title: Data Management Guide
Ÿ Distributed Data Management Guide, SC41-9600 Ÿ COBOL/400 Reference, SC09-1813
Short title: DDM Guide Short title: COBOL/400 Reference
Ÿ Database Guide, SC41-9659 Ÿ American National Standard Programming Lan-
Short title: Database Guide guage COBOL, ANSI X3.23-1985, ISO 1989-1985
Short title: American National Standard Program-
Ÿ Utilities: Interactive Data Definition Utility User’s
ming Language COBOL, ANSI X3.23-1985, ISO
Guide, SC41-9657
1989-1985
Short title: IDDU User’s Guide
Ÿ System Programmer’s Interface Reference, For information about Common Programming Interface
SC41-8223 (CPI) COBOL, refer to the following publication:
Short title: System Programmer’s Interface
Ÿ Systems Application Architecture Common Pro-
Reference
gramming Interface COBOL Reference, SC26-4354.

 Copyright IBM Corp. 1994 383


384 COBOL/400 User’s Guide
Glossary of Abbreviations
Abbrevi- Meaning Explana- Abbrevi- Meaning Explana-
ation tion ation tion
Appl Dev Application Development Consisting ASCII American National The code
Tools Tools of pro- Standard Code for Infor- developed
grams for mation Interchange by Amer-
the AS/400 ican
system, National
such as the Standards
Screen Institute for
Design Aid information
(SDA) and exchange
the Source among data
Entry Utility processing
(SEU). systems,
data com-
ANSI American National An organ-
munications
Standards Institute ization con-
systems,
sisting of
and associ-
producers,
ated equip-
consumers,
ment. The
and general
ASCII char-
interest
acter set
groups, that
consists of
establishes
8-bit char-
the proce-
acters, con-
dures by
sisting of
which
7-bit control
accredited
characters
organiza-
and sym-
tions create
bolic char-
and main-
acters, plus
tain volun-
one parity-
tary
check bit.
industry
standards
in the
United
States.

 Copyright IBM Corp. 1994 385


Abbrevi- Meaning Explana- Abbrevi- Meaning Explana-
ation tion ation tion
CICS Customer Information An IBM DBCS Double-Byte Character A set of
Control Service licensed Set characters
program in which
that each char-
enables acter is
trans- represented
actions by 2 bytes.
entered at Languages
remote such as
work Japanese,
stations to Chinese,
be proc- and
essed con- Korean,
currently by which
user-written contain
application more
programs. symbols
The than can be
licensed represented
program by 256
includes code
functions points,
for building, require
using, and double-byte
maintaining character
databases, sets.
and for Because
communi- each char-
cating with acter
CICS on requires 2
other oper- bytes, the
ating typing, dis-
systems. playing,
and printing
CL Control Language The set of
of DBCS
all com-
characters
mands with
requires
which a
hardware
user
and pro-
requests
grams that
system
support
functions.
DBCS.
Four
double-byte
character
sets are
supported
by the
system:
Japanese,
Korean,
Simplified
Chinese,
and Tradi-
tional
Chinese.
Contrast
with single-
byte char-
acter set.

386 COBOL/400 User’s Guide


Abbrevi- Meaning Explana- Abbrevi- Meaning Explana-
ation tion ation tion
DDM Distributed Data Man- A function ICF Intersystem Communi- A function
agement of the oper- cations Function of the oper-
ating ating
system that system that
allows an allows a
application program to
program or communi-
user on cate inter-
one system actively
to use data with
files stored another
on remote program or
systems. system.
The
I/O Input/Output Data pro-
systems
vided to the
must be
computer
connected
or data
by a com-
resulting
munications
from com-
network,
puter proc-
and the
essing.
remote
systems LVLCHK Level Checking A function
must also that com-
be using pares the
DDM. record
format-level
DDS Data Description Specifi- A
identifiers
cations description
of a file to
of the
be opened
user’s data-
with the file
base or
description
device files
that is part
that is
of a com-
entered into
piled
the system
program to
in a fixed
determine if
form. The
the record
description
format for
is then
the file
used to
changed
create files.
since the
EBCDIC Extended Binary-Coded A coded program
Decimal Interchange character was com-
Code. set con- piled.
sisting of
256
eight-bit
characters.
FIPS Federal Information An official
Processing Standard standard to
improve the
utilization
and man-
agement of
computers
and data
processing
in business.

Glossary of Abbreviations 387


Abbrevi- Meaning Explana- Abbrevi- Meaning Explana-
ation tion ation tion
ODT Object Definition Table A table built SQL/400 Structured Query An IBM
at compile Language/400 licensed
time by the program
system to supporting
keep track the rela-
of objects tional data-
declared in base that is
the used to put
program. information
The into a data-
program base and to
objects in get and
the table organize
include var- selected
iables, con- information
stants, from a
labels, database.
operand
UPSI User Program Status An external
lists and
Indicator switch program
exception
switch that
descriptions.
performs
The table
the func-
resides in
tions of a
the com-
hardware
piled
switch.
program
Eight
object.
switches
OS/400 Operating System/400 The AS/400 are pro-
operating vided: UPSI
system. 0 - 7.
SDA Screen Design Aid A function
of the Note: The abbreviations for OS/400 commands do not
AS/400 appear here. Refer to the CL Reference for
Application OS/400 commands and their usage.
Develop-
ment Tools
licensed
program
that helps
the user
design,
create, and
maintain
displays
and menus.
SEU Source Entry Utility A function
of the
AS/400
Application
Develop-
ment Tools
licensed
program
that is used
to create
and change
source
members.

388 COBOL/400 User’s Guide


Index
ALTER statement 312
Special Characters American National Standards Institute (ANSI) xiii,
/ (slash) 12, 38
1, 323, 331, 385
maximum number in a program 89
ANSI 74 COBOL versus ANSI 85 COBOL 335
* (asterisk) 12
conforming to standards
with indexed files 241
Numerics with relative files 249
8-byte binary items, and performance 268 with sequential files 249
standard xiii, 1, 331
APIs (Application Programming Interfaces)
A error-handling 53, 70
abnormal program termination 52 using with pointers 291
about this manual xi *APOST option 20
ACCEPT statement 103, 177, 343 Application Development Manager/400
access mode 173, 241, 249 Application Development Tools, messages 327
DYNAMIC 246 Appliciation Programming Interfaces (APIs)
RANDOM 246 error-handling 53, 70
access path using with pointers 291
description 128 arguments, describing in the calling program 280
example for indexed files 247 arithmetic operators 2
file processing 250, 251 arrival sequence 129, 249, 250
specifications 105 arrows, shown in syntax 3
*ACCUPDALL option 26 ASSIGN clause 89, 143, 172
*ACCUPDNE option 26 device name 89
ACQUIRE statement 178 assignment name 89, 143, 172, 341
ADDMSGD (Add Message Description) * (asterisk) 12
command 331 AT END condition 80, 187, 190
ADDRESS OF special register 280, 287 *ATR option 21
description 287 ATTRIBUTE DATA 178
difference from calculated ADDRESS OF 287 attributes
addresses of data items 46
incrementing using pointers 305 of files 45
passing between programs 303 of table items 46
ADM/400 ATTRIBUTES field 45
ADVANCING phrase 233 AUT parameter for CRTCBLPGM command 27
for FORMATFILEs 234 authorization-list-name option 27
ADVANCING PAGE phrase 336
ALCOBJ (Allocate Object) command 93
ALIAS keyword 111 B
alias name 113 batch compiles 36
alias, definition 111 batch jobs, representation of DBCS data in 348
*ALL option 27 binary items, and performance 268
Allocate Object (ALCOBJ) command 93 *BLANK option 19
alphabet-name, definition 335 BLANK WHEN ZERO
alphabetic character, definition 336 defining with LIKE clause 258
*BLK option 23

 Copyright IBM Corp. 1994 389


block, description 102 calling the COBOL compiler 15
blocking output records 102 CANCEL statement 282, 307, 336
Boolean data types 20, 144, 176 with non-COBOL programs 279
Boolean literal, definition 20 *CBL statement 38
boundary CCSIDs (Coded Character Set IDentifiers) 137
definition 95 CDRA (Character Data Representation Architec-
record 23 ture) 137
violation 73, 251 Change Debug (CHGDBG) command 55
breakpoints *CHANGE option 27
as an OS/400 function 55 Change Program Variable (CHGPGMVAR)
considerations for using 63 command 63
description 57 change/date (CHGDATE) field 43
displaying table elements 60 changes from ANSI 74 COBOL 335—336
displaying variables 60 changing the value of variables 63
example 57 Character Data Representation Architecture
traces, differences between 64 (CDRA) 137
use of 57, 62 characters, double-byte 337
browsing a compiler listing characters, replaced in field name 113
See source entry utility (SEU) checking DBCS literals 339
BY CONTENT, definition 279 checking work station validity 140
BY REFERENCE, definition 279 CHGDBG (Change Debug) command 55
CHGPGMVAR (Change Program Variable)
command 63
C choices, shown in syntax 3
calculation operations
CICS (Customer Information Control System)
on fixed-length fields 132
statements 13
call by identifier 282
CICSCBL member type 13
CALL statement
CICSSQLCBL member type 13
BY CONTENT identifier 280
CL (control language) commands
BY CONTENT LENGTH OF identifier 280
for running programs 7
BY CONTENT literal 280
for testing programs 55
BY CONTENT, implicit MOVE 289
issuing using QCMDEXC in a program 255
by identifier 282
clauses
BY REFERENCE ADDRESS OF
ACCESS MODE 173
record-name 280
ASSIGN 143, 172
BY REFERENCE identifier 279
CONTROL-AREA 174
recursive, description 273
CURRENCY clause 12
to QCMDEXC 255
DECIMAL-POINT clause 12
using pointers 289
FILE STATUS 103, 173
within a segmented program 312
INDICATOR 145
called program
JUSTIFIED 342
definition 273
LIKE 145
calling programs
LINAGE 233
BY CONTENT 279
OCCURS 145, 341
BY REFERENCE 279
ORGANIZATION 172
definition 273
ORGANIZATION IS INDEXED 241
from a non-COBOL program 268
PICTURE 144, 267, 342
to begin at another entry point
RECORD KEY 129
using pointers 289
REDEFINES 335, 341
within a segmented program 312
RELATIVE KEY 173

390 COBOL/400 User’s Guide


clauses (continued) commitment control 82, 94, 98
RENAMES 342 example 97
REPLACING identifier-1 BY identifier-2 locking level 95
clause 12 common keys 129
SAME AREA 335 Common Programming Interface (CPI)
SAME RECORD AREA 335 support 325
SEGMENT-LIMIT 310 communication module 325
SORT-MERGE AREA 335 communications, interactive
syntax, notation for 3 interprogram considerations 273, 349
USAGE 144 recovery 83
VALUE 145, 342 with other programs 139
WITH DEBUGGING MODE 313 with remote systems 139
CLOSE operation 23 with work station users 139
CLOSE statement 179, 336 COMP-3 items, and performance 268
closing files with the CANCEL statement 336 compile-time errors 56
code optimizing 22 compiler failure 16
CODE/400 compiler options
Coded Character Set Identifiers (CCSIDs) 137 See also PROCESS statement
coding errors 56 also parameters, CRTCBLPGM command
coding form 6, 11 *ACCUPDALL 26
coding formats provided by SEU 11 *ACCUPDNE 26
coding tables 263 *ALL 27
command summary listing 39 and syntax checking with SEU 12
command syntax, using 3 *APOST 20
commands as specified in PROCESS statement 32
Add Message Description (ADDMSGD) 331 *ATR 21
Allocate Object (ALCOBJ) 93 authorization-list-name option 27
Change Debug (CHGDBG) 55 batch compiling 36
Change High Level Language Pointer *BLANK 19
(CHGHLLPTR) 63 *BLK 23
Change Pointer (CHGPTR) 63 *CHANGE 27
Change Program Variable (CHGPGMVAR) 63 check for sequence errors 19
Create Authorization List (CRTAUTL) 27 check subscript ranges at run time 21
Create COBOL Program (CRTCBLPGM) compiler options listing 37, 40
See Create COBOL Program command count verb usage 19
Display Program Variable (DSPPGMVAR) 63 create cross-reference listing 19, 21, 47
Display Trace Data (DSPTRCDTA) 65 create Data Division map 20
End COBOL Debug (ENDCBLDBG) 315, 316 create object code 19
Grant Object Authority (GRTOBJAUT) 27 create source listing 19, 41
Monitor Message (MONMSG) 16 *CRTF 22
Override Message File (OVRMSGF) 331 *CURLIB 18, 25
Override to Diskette File (OVRDKTF) 90 *CURRENT 26, 31
Start COBOL Debug (STRCBLDBG) 314, 316 *DATETIME 24
Start Debug (STRDBG) 55 *DDSFILLER 22
Start Source Entry Utility (STRSEU) *DEB1 25
See source entry utility *DEB2 25
comments with DBCS characters 340 delimiter for nonnumeric and Boolean
COMMIT statement 95, 96 literals 20
commitment boundary, definition 95 *DFRWRT 25
*DUMP 21

Index 391
compiler options (continued) compiler options (continued)
*DUPKEYCHK 22 *NORANGE 22
*EXCLUDE 27 *NOSECLVL 20
*EXTACCDSP 23 *NOSEG 25
file-name option 24 *NOSEQUENCE 19
*FLAG 25, 37 *NOSOURCE 19
*FS21DUPKY 23 *NOSRCDBG 20
*GEN 19 *NOSTDERR 22
*GRAPHIC option 24 *NOSTDINZ 23
*HIGH 25 *NOSYNC 22
include attributes for the IRP 21 *NOUNDSPCHR 25
*INTERMEDIATE 25 *NOUNREF 22
*INZDLT 23 *NOVARCHAR 23
*LIBCRTAUT 27 *NOVBSUM 19
*LIBL 18, 24 *NOXREF 19, 21
library-name option 18, 25 *NUMBER 19
*LINENUMBER 20 *OBSOLETE 25
*LIST 21 *OPTIMIZE 22
list compiler options in effect 37, 41 optimizing source code 22
*LSTDBG 21 *OPTIONS 20, 37
*MAP 20, 37 overview 6
maximum-severity-level option 24 *OWNER 26
message-limit option parameters of the CRTCBLPGM
*MINIMUM 25 command 18—31
*NOATR 21 *PATCH 21
*NOBLK 23 *PGM 18
*NOCRTF 22 *PGMID 18
*NODATETIME option 24 *PRINT 21
*NODDSFILLER 22 PROCESS statement, using to specify 32
*NODEB 25 program listings, DBCS characters in 349
*NODFRWRT 25 program-name 18
*NODUMP 21 *PRTCORR 20
*NODUPKEYCHK 22 *PRV 26, 31
*NOEXTACCDSP 23 QLBLSRC (default source file) 18
*NOFIPS 25 QSYSPRT (default printer file) option 24
*NOFLAG 25 *QUOTE 20
*NOFS21DUPKY 23 *RANGE 21
*NOGEN 19 release-level option 26, 31
*NOINZDLT 23 *SECLVL 20
*NOLIST 21 *SEG1 25
*NOLSTDBG 21 *SEG2 25
*NOMAP 20 *SEQUENCE 19
*NOMAX 24 severity-level option 19, 26
*NONUMBER 19 *SOURCE 18, 19, 37
*NOOBSOLETE 25 source-file-member-name option 19
*NOOPTIMIZE 22 source-file-name option 18
*NOOPTIONS 20 specifying
*NOPATCH 21 *SRCDBG 20
*NOPRINT 21 *SRCMBRTXT 19
*NOPRTCORR 20 *STDERR 23

392 COBOL/400 User’s Guide


compiler options (continued) CONCAT keyword 122
*STDINZ 23 Configuration Section, description 10, 340
suppressing second-level messages 20 conforming to ANSI standards 332
suppressing source listing 41 constant, NULL figurative 286
*SYNC 22 contents of DEBUG-ITEM special register 319
text-description 19 contiguous items, definition 242
*UNDSPCHR 25 contiguous key fields, multiple 242
*UNREF 22 control
*USE 27 returning 274
use compiler-generated sequence numbers 20 transferring 273
use user-supplied sequence numbers 19 CONTROL-AREA clause 174—175
*USER 26 control language commands
V2R1M0 value for release-level option 31 See CL commands
V2R1M1 value for release-level option 31 control of segmentation 310
V2R2M0 value for release-level option 31 *CONTROL statement 38
*VARCHAR 23 COPY DDS, use with indicators 118
*VBSUM 19, 37 control, returning from a called program 274
*XREF 19, 21, 37 control, transferring to another program 273
compiler output CoOperative Development Environment/400
See also messages copies of ANSI standard available xiii
browsing 39 COPY statement
See also source entry utility and DBCS characters 348
command summary listing 39 and externally described data 113
compiler output 36, 37 and floating-point 127
cross-reference listing 47 changes from ANSI 74 COBOL 335
CRTCBLPGM options 37 data field structures 116
Data Division map 44 DD, DDR, DDS, or DDSR 112
description 37 DDS results 110, 118
examples 37 description 112
FIPS messages listing 46 example of data structures generated by 204
listing descriptions 37 examples of key generation 121
listing options 40 format-1 COPY statement 36
messages 329 in File Section 114
options listing 39, 40 key fields 242
program listings, DBCS characters in 349 listing source statements 38
suppressing source listing 41 outside File Section 114
compiling COBOL programs PROCESS statement containing COPY state-
abnormal compiler termination 16 ment 37
compiler-detected errors 56 suppressing source statements 38
example listing 39 use with PROCESS statement 36
exceeding internal size limits 15 use with TRANSACTION files 139
failed attempts 16 with ALL-FORMATS 114
for extended ACCEPT/DISPLAY 23 COPYNAME field 43
for the previous release 31 corresponding options, PROCESS and
invoking the compiler 15 CRTCBLPGM 32
messages 329 CORRESPONDING phrase 256
multiple programs 36 counting verbs in a source program 19, 43, 49
output 37 CPI (Common Programming Interface)
redirecting files 90 support 325
TGTRLS, using 31

Index 393
Create Authorization List (CRTAUTL) CVTOPT parameter 23, 34
command 27
Create COBOL Program (CRTCBLPGM)
command
D
data area
AUT parameter 27
description 305
CVTOPT parameter 23, 34
local 305
description of 6
PIP 306
DUMP parameter 27
data class type (TYPE) field 45
entering from CL program 28
data communications file 139, 172
entering from command line 28
data description entry for Boolean data 144
EXTDSPOPT parameter 35
data description specifications (DDS)
FLAG parameter 26, 35
command attention (CA) keys 140
FLAGSTD parameter 25, 35, 37
CONCAT keyword 122
GENLVL parameter 19, 32
Create File commands 105
GENOPT parameter 21, 34
date fields 132
ITDUMP (n) parameter 27
DD option, description 113
MSGLMT parameter 24
DDR option, description 113
OPTION parameter 19, 33, 37
DDS option, description 113
parameters, description of 18—31
DDSR option, description 113
PGM parameter 18
definition 140
prompt displays, using 16
description 106
PRTFILE parameter 24
display management 140
REPLACE parameter 26
examples
SAAFLAG parameter 25, 35, 37
CONCAT keyword 122
SRCFILE parameter 18
for a display device file 141
SRCMBR parameter 18
for field reference file 107
syntax of 29
for subfile record format 159, 161
TEXT parameter 19
formats, data structures generated by 204
TGTRLS parameter 26
key generation 121
USRPRF parameter 26
keyed access path for an indexed file 247
creating files
RENAME keyword 124
indexed files 351, 356
specifications for a database file 110
relative files 351, 361
specifying a record format 109
sequential files 351
SST keyword 126
cross-reference listing
work station programs 200, 231
and breakpoints 57
externally described files 104, 242
CRTCBLPGM options 19, 21
FORMATFILE files 234
description of listing 48
function keys 140
example 47
function of 140
testing, using in 61
graphic data fields 133
CRTAUTL (Create Authorization List)
incorporate description in program 108
command 27
key fields 242
CRTCBLPGM command
multiple device files 162
See Create COBOL Program command
program-described files 104
*CRTF option 22
RENAME keyword 124
*CURLIB option 18, 25
SAA fields 132
*CURRENT option 26, 31
SST keyword 126
Customer Information Control System (CICS)
subfiles 156
statements 13
suffixes 123
time fields 132

394 COBOL/400 User’s Guide


data description specifications (DDS) (continued) *DDSFILLER option 22
timestamp fields 132 DDSR name 113
TRANSACTION files 139 de-editing 265
use of keywords 107 definition 265
variable-length fields 131 examples 266
work station validity checking 140 *DEB1 option 25
Data Division *DEB2 option 25
arguments for calling program 280 debugging programs 55, 313
Boolean data facilities 176 breakpoints
DBCS characters 341 considerations for using 63
description 10 description 57
map of, compiler option 20, 44 changing variable contents 63
transaction files 173, 175 compile-time switch 313
data errors with de-editing, handling 267 Data Division map and IRP listing, using 61
data field 10 debug module 325
data field structures 116 DEBUG-CONTENTS 319
data item DEBUG-ITEM special register 319
attributes of 46 DEBUGGING MODE as compile-time
defining as a pointer 283 switch 313
in subprogram linkage 281 declaratives, running of 316
passing, with its length 280 description 6, 55, 269
substring reference 262 displaying table elements 60
data items, unreferenced 22 displaying variables 60
data types 130 ENDCBLDBG (End COBOL Debug)
date 132 command 315, 316
graphic 133 features available 313
restrictions for SAA data types 132 file status 103
time 132 formatted dump 67
timestamp 132 functions for 55
data, passing line, definition 321
BY CONTENT and BY REFERENCE 280 lines of a source program 321
in groups 281 OS/400 functions for 55
database files overview 6
See also disk files run-time switch 67, 314
DATABASE file considerations 241 STRCBLDBG (Start COBOL Debug)
DATABASE versus DISK 241 command 314, 316
DISK file considerations 241 traces
processing methods 241 considerations for using 66
date data type 132 description 64
date-last-modified area 10 USE FOR DEBUGGING procedures 316
*DATETIME option 24 default source file (QLBLSRC) 10, 18
DBCS support default values, indication of 16
See double-byte character set support DEFINED field 48
DBCS-graphic data type 133 delays, reducing length of on initialization 251
DD name 113 deleted records, initializing files with 23, 251
DDR name 113 delimiting SQL statements 12
DDS descending file considerations 253
See data description specifications descending key sequence, definition 253
DDS name 113 description and reference numbers flagged
field 46

Index 395
designing your program 9 divisions of programs (continued)
destination of compiler output 36 Environment Division 171, 310, 311, 340
device control information 142 Identification Division 10
device dependence 89 optional 10
examples 90 Procedure Division 176, 311, 343—348
device files required 10
and I/O 89 do while structure, testing for end of chained
DATABASE file considerations 241 list 304
DISK file considerations 241 double spacing 38
multiple 162 double-byte character set (DBCS)
single 162 support 337—350
device independence 89 ACCEPT statement 343
*DFRWRT option 25 and alphanumeric data 346
diagnostic levels 330 checking 339
diagnostic messages 48 comments with DBCS characters 340
diagrams, syntax 29 communications between programs 349
direct files definition 386
See relative files enabling in COBOL programs 337
disclaimers graphic 348
examples in the Data Division 341
patents ix in the Environment Division 340
sending information to IBM in the Identification Division 340
US government users in the Procedure Division 343—348
disk files 241 open 348
processing methods 252 PROCESS statement 337, 345
displacement (DISP) field 45 representation of DBCS data in batch
display device jobs 348
DDS for 140 searching for in a table 348
record format 140, 141 sorting 348
display device file 140 specifying DBCS literals 337, 338
display format data, definition 140 DROP statement 179
DISPLAY statement 344 DSPTRCDTA (Display Trace Data) command 65
Display Trace Data (DSPTRCDTA) command 65 *DUMP option 21
displaying a compiler listing 39 DUMP parameter for CRTCBLPGM command 27
displays dump, formatted 371
CRTCBLPGM prompt display 17 *DUPKEYCHK option 22, 270
data description specifications (DDS) for 140 duplication errors 258
display program messages 328 dynamic access mode 158, 173, 249, 253
ENDCBLDBG prompt display 315 dynamic file creation 22
for sample programs dynamic processing, definition 173
order inquiry 216, 217
payment update 228, 229, 230
transaction inquiry 205
E
EBCDIC character, definition 387
SEU display messages 327
editing source programs 9
STRCBLDBG prompt display 314
subfiles 157
See also source entry utility (SEU)
efficiency considerations 268
distributed data management (DDM) 387
efficiency, increased 22
DIVIDE statement 336
eight-byte binary items, and performance 268
divisions of programs
Data Division 20, 173, 175, 341

396 COBOL/400 User’s Guide


EJECT statement 38 examples (continued)
elementary pointer data items 287 DDS (continued)
embedded SQL 12 for subfiles 159, 161
End COBOL Debug (ENDCBLDBG) key generation 121
command 315, 316 RENAME keyword 124
end of chained list, testing for 304 SST keyword 126
END-OF-PAGE phrase 336 diagnostic messages listing 48
END-READ phrase 187, 190 END-OF-PAGE condition 235
END-REWRITE phrase 192 entering CRTCBLPGM from command line 28
END-WRITE phrase 199 error recovery 82
ending a called program 274 externally described printer files 237
entering CRTCBLPGM from CL program 28 file processing
entering CRTCBLPGM from command line 28 indexed files 356, 357
entering source programs 9, 11 relative files 361, 363
entering your program sequential files 351, 353
See source entry utility (SEU) FIPS messages listing 46
Environment Division FORMATFILE file 234
and DBCS characters 340 formatted dump 371
and transaction files 171 generic START 242, 243
SEGMENT-LIMIT clause 310, 311 indicators 146
error checking for de-editing, run time 267 LENGTH OF special register with pointers 286
error handling 69 length of variable-length field 132
APIs 53, 70 MOVE with pointers 288
nonstandard 77 multiple device files 165
overview 69 pointers
standard 76 aligning 284
error recovery, example 82 and LENGTH OF special register 286
errors and REDEFINES clause 285
ADVANCING phrase with FORMATFILE and results of MOVE 288
files 234 initializing with NULL 286
duplication 258 passing items containing 289
errors to avoid 56 processing chained list 302
errors, in syntax program structure 9
See syntax errors record format specifications 107, 110
examples ROLLING phrase 195
access path for indexed file 247 run units
breakpoint 57 multiples, running concurrently 278
COBOL and files 105 multiples, running consecutively 276
commitment control 94, 98 single unit 274
compiler options listing 20, 37 with shared program 277
COPY DDS results 110, 119 SEU display messages 327
COPY statement in PROCESS statement 37 source listing 41
cross-reference listing 47 trace 64
Data Division map 44 using pointers in chained list 302
DDS variable-length graphic data 134
CONCAT keyword 122 verb usage by count listing 43
for a display device file 140, 141 work station application programs
for a record format 109 order inquiry 206
for a record format with ALIAS keyword 111 payment update 217
for field reference file 107 transaction inquiry 200
for multiple device files 162

Index 397
exceptions 16, 52, 71, 81 Federal Information Processing Standard (FIPS)
*EXCLUDE option 27 (continued)
exclusive-allow-read lock state 93 standards to which the compiler adheres xiii
EXIT PROGRAM statement 274, 306 with DBCS characters 349
expressions 264, 343 FIB (file information block) 71
*EXTACCDSP option 23 field names
EXTDSPOPT parameter of the CRTCBLPGM -DDS added to 123, 125
command 35 additional notes 127
EXTEND mode, definition 93 construction of 116
extended ACCEPT and DISPLAY statements 23 fields
extensions, IBM attributes
double-byte character set (DBCS) BLANK WHEN ZERO 260
support 337—350 defaults 260
flagging 25, 331 SIGN IS TRAILING 260
format, indication in syntax 5 USAGE IS DISPLAY 260
GOBACK BLANK WHEN ZERO attribute 260
overview 1 date 132
reading 5 fixed length 132
transaction files 139—231 floating-point 127
extensions, list of 1 null-capable 133
external description time 132
adding functions to 130 time separator 38
overriding functions to 130 timestamp 132
external file status 70 variable-length 131
externally described files 113, 236 character 131
adding functions 130 graphic 131, 134
advantages of using for printer files 234 length of, example 132
and COPY statement, DD, DDR, DDS, DDSR maximum length 131
format 119 restrictions 131
considerations for using 105 figurative constant QUOTE 20
DDS for 108 figurative constant, NULL 286
description 104 file and record locking 93, 95
level checking 130 file boundaries 251
overriding functions 130 file considerations 89, 241, 306
printer files, specifying with FORMATFILE 234 file control entry 89
EXTERNALLY-DESCRIBED-KEY 242 of Environment Division 171
externally described TRANSACTION TRANSACTION file processing entry 171
files 139—142 file descriptions 108, 175
file information block (FIB) 71
file locking 93
F file-name option 24
failed I/O and record locking 94
file operations for printer file 233
failure of compiler 16
file organization 250
Federal Information Processing Standard (FIPS)
file processing
1986 COBOL standard 331
See files
description 331
file redirection 90, 92
flagging deviations from 25, 331, 349
file status
FLAGSTD parameter 25, 46
0Q 251
messages 46, 329, 331
9N 83
options 25
9Q 251
standard modules 331

398 COBOL/400 User’s Guide


file status (continued) FIPS flagging
after I/O 83 See Federal Information Processing Standard
coded examples 353 FIPS-ID field 46
from message monitors 73 FIPS violations flagged, total 47
how it is set 72 fixed length graphic fields 133
internal and external 70 *FLAG option 25, 37
obtaining 103 FLAG parameter for CRTCBLPGM command 26,
statements that affect 306 35
FILE STATUS clause 103 FLAGSTD parameter for CRTCBLPGM
files command 25, 35, 46
See also disk files, externally described files, float test, de-editing 267
program-described files, source files floating-point fields 127
access paths 250 FOOTING phrase 336
attributes of 45 format (record) level structures 115
closing 336 format-1 COPY statement 36
creation of format-2 COPY statement 16
indexed 351, 356 format names, additional notes 127
relative 351, 361 FORMAT phrase 181, 186, 189, 191
sequential 351 FORMATFILE files
DATABASE 241 description 234
DATABASE versus DISK 241 sample program 234
description 351 formats, using SEU
DISK 241 See source entry utility
examples formatted dump 55, 67, 371
indexed files 356, 357 *FS21DUPKY option 23
relative files 361, 363 function keys
sequential files 351, 353 and CONTROL-AREA clause 175
external description 105 specifying with DDS
FORMATFILE 234 See transaction files
indexed organization 241 functional processing modules 323
keys 129
logical 246
methods of 251
G
*GEN option 19
on AS/400 systems 89, 351
general-use programming interfaces
preserving sequence of records 250
description ix
PRINTER 233
error-handling 70
processing methods 241
QCMDEXC 28, 255
redirecting access to 90
generation of I/O formats 118
relative 249
generation of keys 121
relative organization 249
generation of message monitors 73
retrieval of, relative 351, 365
generic START statement 242
sample programs 351—367
GENLVL parameter for CRTCBLPGM
sequential 249
command 19, 32
sequential organization 249
GENOPT parameter for CRTCBLPGM
specific 233
command 21, 34
techniques for processing 351—367
GIVING phrase 335, 336
TRANSACTION 139
GO TO statement 312
files unavailable at OPEN time 22
GOBACK statement 307
FILLER
floating-point fields 127

Index 399
Grant Object Authority (GRTOBJAUT) indexed files, definition 356
command 27 indexed I-O module 324
graphic data types 133 indicator structures 117
restrictions 133 indicators
*GRAPHIC option 24 and ASSIGN clause 143
group level names 116 and Boolean data items 144
group structures, aligning pointers within 284 and COPY statement 114, 118
GRTOBJAUT (Grant Object Authority) associated with command keys 140
command 27 data description entries 144
description 115, 142
example, using in programs 146
H in a separate indicator area 143, 145, 270
handling data errors, de-editing 267
in the record area 143, 146
*HIGH option 25
INDARA DDS keyword 143
highlights 2, 351
INDICATOR clause 145
hyphen, produced when copying ALIAS
INDICATORS phrase 145
names 113
performance considerations 270
sample programs 146
I special considerations for 144
I/O formats 118 structures 116
IBM extensions TRANSACTION file processing 142
double-byte character set (DBCS) using 144
support 337—350 industry standards xiii
flagging 25, 331 initialization of storage 279
format, indication in syntax 5 initializing files with deleted records 251
GOBACK initializing pointers 286
overview 1 with NULL figurative constant 286
reading 5 input field 140, 189
transaction files 139—231 input records 102
ICF input spool 91, 92
See intersystem communications function input verbs, processing of
Identification Division since Version 1, Release 3 80
and DBCS characters 340 Input-Output formats 118
description 10 input-output verbs, processing of
identifier since Version 1, Release 3 80
call by 282 INSPECT statement 345
defining in Working-Storage section 258 inter-program module 324
unreferenced 22 *INTERMEDIATE option 25
increasing efficiency 22 intermediate representation of program (IRP)
INDARA keyword 118 cross-reference listing 21
independence, device 89 how to list 21
independent segments 309 how to list attributes 21
indexed files how to use 57
creation 351, 356 sample listing 62
description 241 internal file status 70
key fields 241 internal name (I-NAME) field 45
processing methods for types DISK and DATA- internal size limits 15
BASE 241 International Standards Organization (ISO) xiii
updating 351, 357 interprogram calls using pointers 289

400 COBOL/400 User’s Guide


interprogram communication considerations 273 keys (continued)
intersystem communications function (ICF) validity 242
ACCESS MODE clause 173 keywords
ASSIGN clause 172 DDS 111, 122, 124, 126
communications 156 in syntax diagrams 2
CONTROL-AREA clause 174 INDARA 118
FILE STATUS clause 173
multiple and single device files 162
ORGANIZATION clause 172
L
language elements
RELATIVE KEY clause 173
using to specify subfiles 156
See program structure
last-used state, description 274
INTO phrase 186, 335
LDA (local data area) 305
introduction to COBOL/400 1
length (LENGTH) field 45
invalid characters 113
length of records in source file 10
DDR and DDSR options 113
LENGTH OF special register 280, 286
INVALID KEY phrase 190, 192, 199
length of statement, maximum 11, 12
role since Version 1, Release 3 80
level checking 130
*INZDLT option 23, 251
level of data item (LVL) field 44
I-O feedback 55, 103, 343
level of language support 323, 324, 331
I-O flags 371
*LIBCRTAUT option 27
I-O operation 371
*LIBL option 18, 24
I/O verbs, processing of
libraries, test 55
since Version 1, Release 3 80
library-name option 18, 25
IRP (intermediate representation of program)
LIKE clause
See intermediate representation of program
description 258
(IRP)
format of 259
ITDUMP parameter for CRTCBLPGM
PICTURE portion 260
command 27
limitations 89
items grouped by level 47
TGTRLS parameter 31
limits, internal, size 15
J LINAGE clause 233
job failure, recovery 82 *LINENUMBER option 20
JUSTIFIED clause 342 linkage items, setting the address of 287
Linkage Section
describing data to be received 281
K parameters for a called program 280
key fields
*LIST option 21
contiguous, multiple 242
listings
descending keys 253
browsing
for indexed files 241
See source entry utility
name, -DDS added to 123, 125
command summary 39
partial keys 242
compiler options in effect 20
program-defined 246
cross-reference 47
keyed read 91
Data Division map 44, 61
keyed sequence 129, 241, 250, 253
DBCS characters in 349
keys
default output file 24
common 129
example, source listing 19, 41, 43
floating-point 127
examples of 40
generation of 121
FIPS messages 46
record 129
messages
description 48

Index 401
listings (continued) messages (continued)
messages (continued) interactive 327
example 48 responding to in an interactive
from COBOL/400 compiler 329 environment 329
minimum record length 24 run-time 328
options 40 and standard error handling 69
scanning for syntax errors 39 SAA, flagged 47
specifying output file for 24 severity levels 19, 24, 330
verb usage by count 19, 43 statistics 49
literals, DBCS 338—340, 348 types 327
literals, delimiting 20 methodology for entering programs 9
local data area (LDA), definition 305 migrating
lock level ANSI 74 COBOL programs 335
(*CS), under commitment control 95 to ANSI 85 COBOL 335
high, under commitment control 95 to COBOL/400 language 335
low, under commitment control 95 *MINIMUM option 25
lock state 93 mismatched records, reducing occurrence 281
locking, file and record 93 module global table (MGT), definition 371
logic of segmentation 310 Monitor Message (MONMSG) command 16
logical file considerations 246 monitoring exceptions 16
logical operators 2 monitoring operations
looking at a compiler listing monitors, message 73
See source entry utility (SEU) MONMSG (Monitor Message) command 16
loops in a program 271 MOVE statement 319, 346
*LSTDBG option 21 CORRESPONDING phrase 256
using pointers 287
MSGID and severity level field 49
M MSGLMT parameter 24
main program, description 273
multiple contiguous key fields 242
major/minor return codes 75
multiple device files 162—170, 178, 184, 190
*MAP option 20, 37
multiple members 92
maximum record length, dynamically created
files 22
maximum-severity-level option 24 N
maximum source statement length 11, 12 name, assignment 89, 143, 172, 341
member type names defined when GENOPT(*NOUNREF) spec-
See source member type ified 15
members 92 NAMES field 48
memory management NEXT MODIFIED phrase 189
See segmentation NO DATA phrase 186
MERGE statement 312, 335, 348, 368 role since Version 1, Release 3 80
message files 331 NO LOCK phrase, and performance 94, 270
message-limit option 24 NO REWIND phrase 336
message monitor generation 73 *NOATR option 21
messages *NOBLK option 23
Application Development Tools 327 *NOCRTF option 22
compilation 329 *NODATETIME option 24
compile-time 327 *NODDSFILLER option 22
diagnostic 48 *NODEB option 25
field on diagnostic messages listing 49
FIPS 329

402 COBOL/400 User’s Guide


*NODFRWRT option 25 null-capable fields 133
*NODUMP option 21 NULL figurative constant 286
*NODUPKEYCHK option 22 null values 133, 304
*NOEXTACCDSP option 23 *NUMBER option 19
*NOFIPS option 25 numeric items
*NOFLAG option 25 and performance 268
*NOFS21DUPKY option 23 moving with de-editing 265
*NOGEN option 19 numeric usage clauses 116
*NOGRAPHIC option 24
*NOINZDLT option 23
*NOLIST option 21
O
Object Definition Table (ODT) 22
*NOLSTDBG option 21
object names, OS/400 16
*NOMAP option 20
object program
*NOMAX option 24
compiler options, specifying 21
nonnumeric literals 20
optimizing, specifying at compile-time 22
nonstandard error handling 77
output from compiler 15
nonstandard language extensions
specifying authority to 27
See IBM extensions
subscript range checking 21
*NONUMBER option 19
object program, definition 6
*NOOBSOLTE option 25
*OBSOLETE option 25
*NOOPTIMIZE option 22
OCCURS clause 341
*NOOPTIONS option 20
ODP (open data path) 94
*NOPATCH option 21
ODT (Object Definition Table) 22
*NOPRINT option 21
offset, relative to 16-byte boundary 289
*NOPRTCORR option 20
open data path (ODP) 94
*NORANGE option 22, 269
OPEN operation, increasing speed of 94
*NOSECLVL option 20
OPEN statement 180
*NOSEG option 25
OPEN type 93
*NOSEQUENCE option 19
OPEN-FEEDBACK 343
*NOSOURCE option 19
operation, more efficient 22
*NOSRCDBG option 20
operators, arithmetic and logical 2
*NOSTDERR option 23
*OPTIMIZE option 22
*NOSTDINZ option 23
optimizing code 22
*NOSYNC option 22
OPTION parameter for CRTCBLPGM
NOT AT END phrase 187, 190
command 19, 37
role since Version 1, Release 3 80
optional clauses 3
NOT INVALID KEY phrase 190, 192, 199
optional divisions 10
role since Version 1, Release 3 80
optional items, syntax 3
notation, syntax 2
optional processing modules 324
notices
options
description ix
data formats, *NORANGE option 269
patents ix
for the PROCESS statement 36
revision bars ix
listing 40
*NOUNDSPCHR option 25
of CRTCBLPGM command
*NOUNREF option 22
parameters 18—31
*NOVARCHAR option 23
segmentation 311
*NOVBSUM option 19
OPTIONS listing 40
*NOXREF option 19, 21
*OPTIONS option 20, 33, 37
nucleus module 324

Index 403
order of clauses 3 passing data item and its length 280
ORGANIZATION clause 172 *PATCH option 21
ORGANIZATION IS INDEXED clause 241 PERFORM statement 312, 336
OS/400 operating system performance considerations 268
and messages 331 I/O operations 102
breakpoint commands 57 permanent segment 309
device control information 142 *PGM option 18
device independence and device PGM parameter for CRTCBLPGM command 18
dependence 89 *PGMID option 18
functions for debugging 55 phrases
input/output 142 ADVANCING 233
internal size limits 15 ADVANCING PAGE 336
object names 16 AT END 187, 190
security, maintaining while testing 55 CORRESPONDING 20
testing, functions for 55 END-OF-PAGE 336
output END-REWRITE 192
compiler 37 END-WRITE 199
compiler, displaying 39 FOOTING 336
output field 140 FORMAT 181, 186, 189, 191
output file, definition 351 GIVING 335, 336
output spool 91 INDICATORS 145, 181
output verbs, processing of INTO 186, 335
since Version 1, Release 3 80 INVALID KEY 190, 192, 199
Override Message File (OVRMSGF) NEXT MODIFIED 189
command 331 NO DATA 186
Override to Diskette File (OVRDKTF) NO REWIND 336
command 90 NOT AT END 187, 190
overriding messages 331 NOT INVALID KEY 190, 192, 199
overriding program-specified files 92 REEL/UNIT 336
overview 6 RELATIVE KEY 335
OVRDKTF command 90 REMAINDER 336
OVRMSGF command 331 ROLLING 195
*OWNER option 26 STARTING 194
SUBFILE 182
TERMINAL 182, 187, 190, 192, 193, 198
P USING 335
packed decimal items 268
PICTURE clause 267, 342
paper positioning 233
and performance 268
parameters of CRTCBLPGM command 18
defining with LIKE clause 258
See also Create COBOL Program PICTURE definitions 116
(CRTCBLPGM) command
PIP (program initialization parameters) data
parameters, describing in the called program 280
area 306
partial key, referring to 242
description 306
parts of a COBOL program
pointer alignment, definition 283
See program structure pointer data items
parts of a program 9
definition 282
passing addresses between programs 303
elementary items 287
passing data 279
pointers
in groups 281
aligning on boundaries
01-level items 284
77-level items 284

404 COBOL/400 User’s Guide


pointers (continued) Procedure Division (continued)
aligning on boundaries (continued) and transaction files 176
automatically using FILLER 284 changes from ANSI 74 COBOL 335
with blocking in effect 284 description 10
and REDEFINES clause 284 segmentation 311
assigning null value 304 specifying debugging in 316
defining 283 subdivisions in 309
defining alignment 283 USE FOR DEBUGGING declarative 316
definition 282 using SET statement to specify address 287
description 282 PROCESS statement 337
examples allowable options for 32
accessing user space 291 compiler options specified in 32
processing chained list 302 compiler output 37
in CALL statement 289 considerations
in File Section 284 blocking output records 102
in Linkage Section 281 commitment control considerations 94
in MOVE statement 287 DATABASE files 241
restrictions 287 device dependencies 89
in records 286 DISK files 241
in tables 284 file and record locking 93
in Working-Storage 284 overriding program-specified files 92
initializing 286 overview 255
length of 282 processing methods for types DISK and
manipulating data items 283 DATABASE 241
moving between group items 289 program-described and externally described
null value 304 files 104
processing a chained list 302 spooling 91
reading 285 unblocking input records 102
writing 285 COPY statement, using with 36, 37
portability considerations description 32
See segmentation format of 32
position of PROCESS statement 32 options 36
preface xi position of statement 32
prestart job 306 rules for 32
previous release, compiling for 31 scope of options with CRTCBLPGM
*PRINT option 21 command 36
printer file, default 24 specifying compiler options 40
printing techniques
based on indicators 234 file processing 351
editing field values 234 indexed file creation 356
in overflow area 234 indexed file updating 357
maintaining print formats 234 relative file creation 361
multiple lines 234 relative file retrieval 365
output from job with WRITE statement 233 relative file updating 363
paging 233 sequential file creation 351
paper positioning 233 sequential file updating and extension 353
spacing 233 using to specify compiler options 32
procedure branching statements 348 processing methods for DATABASE files 241
Procedure Division processing methods for DISK files 241
and DBCS characters 343

Index 405
processing of I/O verbs program termination (continued)
since Version 1, Release 3 80 with the CANCEL statement 336
program control program variables
returning 274 changing 63
transferring 273 pointers 63
program-described files program-defined key fields 246
considerations for using 105 programming considerations 255
description 104 programming notes
externally described by DDS with Create File number of entries in Object Definition Table
commands 104 (ODT) 15, 22
TRANSACTION files 139 prompts, using SEU
program global table (PGT), definition 371 See source entry utility
program initialization parameters (PIP) data area *PRTCORR option 20
See PIP data area example listing 256
program listings, DBCS characters in 349 PRTFILE parameter for CRTCBLPGM
program loops 271 command 24
program-name 18 *PRV option 26, 31
program object punctuation 2
compiler options, specifying 21 purpose of this manual xi
optimizing, specifying at compile-time 22
output from compiler 15
specifying authority to 27
Q
QCMDEXC, using in a program 28, 255
subscript range checking 21
QLBLMSG compile-time message file 331
program parts 9
QLBLMSGE run-time message file 331
program patch area 21
QLBLSRC (default source file) 10, 18
program segments 309
QLRCHGCM API 70
program size 22
QLRRTVCE API 70
program stack, definition 273
QLRSETCE API 53, 70
program structure
QRLMAIN
Data Division 175
MGTFUNC 269
Data Division map 44
QSYSPRT (default printer file) option 24
data field 116
quadruple spacing 38
Environment Division 171
*QUOTE option 20
example 9, 10
QUOTE, figurative constant, value of 20
format (record) level 115
Identification Division 10
indicator 116, 117 R
level of language support 325 random processing, definition 365
Procedure Division 176 *RANGE option 21
required and optional divisions 10 reference modification 262
skeleton program 9 READ statement 344
program syntax, debugging line 321 changes in the use of ANSI 74 COBOL 335
program template 21 description 182
program termination format, nonsubfile 186—187
abnormal 52 format, subfile 189—190
and the CALL statement 312 indicators 145, 146
file considerations 273 processing facilities 181—182
initialization 279 FORMAT phrase 181
returning control 274
STOP RUN statement 274

406 COBOL/400 User’s Guide


READ WITH NO LOCK 93, 95 reference numbers 19, 43, 49
record boundary 23 REFERENCES field 48
record format references to other manuals xi
composition for display device 140 referring to a partial key 242
DDS for subfiles 159, 161 register 319
example, record format specification 105, 107, reinitialization, avoiding 119
110 related printed information
fields 140 relative files
indicators 142 and performance 270
specification, use of DDS keywords in 107 creating 351, 361
subfiles 157 definition 249
RECORD KEY clause 129 for OPEN OUTPUT 270
EXTERNALLY-DESCRIBED-KEY 129 in COBOL 249
record keys 129 initializing for output 251
RECORD KEYS, valid 242 retrieval of 351, 365
record length of source file 10 sequential access 23
records updating 351, 363
blocking output 102 relative I-O module 324
containing pointers 286 RELATIVE KEY clause 173
locking RELATIVE KEY phrase 335
and failed I/O 94 relative key, definition 158
and performance 270 release-level option 26, 31
by COBOL 93 RELEASE statement 348
updating database records 93 releasing a record read for update 93
preserving sequence of 250 REMAINDER phrase 336
reducing mismatches 281 remote systems, communications between 139,
unblocking input 102 306
recovery 82 RENAME keyword 124
example 84 RENAMES clause 342
procedure in program 83 REPLACE parameter for CRTCBLPGM
with multiple acquired devices 83 command 26
with one acquired device 83 REPLACING, in format 2 COPY 127
transaction files 83 reply modes 52
with commitment control 82 report writer module 325
recursive call, definition 273 required
REDEFINES Clause 341 clauses 3
for ALL-FORMATS or I/O phrases 119 divisions 10
pointer data item as subject or object 284 items, in syntax 3
redefinition of formats 119 reserved word list, and extended
redefinition, group level name 116 ACCEPT/DISPLAY 23
redirecting files 90, 92 reserved word, -DDS added to 123, 127
REEL/UNIT phrase 336 responding to messages in an interactive environ-
reference modification ment 329
and *RANGE option 22 restrictions 89
and INSPECT statement 264 return codes 75
calculating offset 289 return of control from called program 274
description 262 RETURN statement 348
left-justification 264 REUSEDLT option
retrieving time value 262 See reusing deleted records

Index 407
reusing deleted records SAA flagging 47, 333
indexed files 242 SAAFLAG parameter for CRTCBLPGM
relative files 249 command 25, 35
sequential files 250 screens
Revoke Object Authority (RVKOBJAUT) See displays
command 27 SEARCH statement 348
REWRITE statement searching DBCS characters in a table 348
and DBCS 344 *SECLVL option 20
description 191 SECTION field 45
for program-described transaction files 191 security
for TRANSACTION file 191 maintaining while testing 55
format 191, 192 specifying authority to object program 27
indicators 145, 146 *SEG1 option 25
processing facilities 181, 182 *SEG2 option 25
ROLLBACK statement 95 SEGMENT-LIMIT clause 310
boundary 95 segment-numbers 309—311
ROLLING phrase 195 segmentation 268, 309—312, 325, 368
run time segmented program 309
common errors 56 SELECT statement,
debugging 67, 314 EXTERNALLY-DESCRIBED-KEY 121
debugging switch 313 separate indicator area (SI) attribute 143
error handling, de-edit 267 sequence
messages 328 combining numbers 20
and standard error handling 69 errors, checking for 19
monitoring exceptions 16 number 10
program termination 52 of records, preserving 250
redirecting files 90 sequence error indicator (S) 43
subscript range checks, specifying 21 *SEQUENCE option 19
switch 67, 314, 315 sequential access mode 23, 173, 187, 189, 249,
run unit 251
definition 36, 273 sequential files
examples creation 249, 351
multiples, running consecutively 276 definition 249
single run unit 274 in COBOL 249
with a shared program 277, 278 updating and extension 351, 353
running COBOL/400 programs sequential I-O module 324
description 51 service marks x
system reply list and reply modes 52 SET statement 346
RVKOBJAUT (Revoke Object Authority) SEU (source entry utility)
command 27 browsing a compiler listing 39
editing source programs 6, 9, 11
entering source programs 6, 9, 11
S errors
S in PICTURE clause 268
coding errors 56
SAA Common Programming Interface (CPI)
common errors 56
support 325
detected by compiler 56
SAA CPI (Common Programming Interface)
listing 48
support 325
messages at run time 328
SAA data types
formats, using 11
prompts and formats 11

408 COBOL/400 User’s Guide


SEU (source entry utility) (continued) source member type (continued)
Start Source Entry Utility (STRSEU) specifying 9, 11
command 9 SQLCBL 13
syntax-checking 11—13, 327 syntax-checking 11, 13
TYPE parameter 9 SOURCE NAME field 44
severity-level 19, 26 *SOURCE option 19, 37
severity level of messages 19, 24, 330 source program
shared files 93 compiling 15, 313
shared-for-read 93 counting verbs used 19
shared-for-read lock state 93 DEBUG-ITEM special register 319
shared-for-update 93 debugging lines 321
shared-no-update 93 definition 2
shared ODP (open data path) 94 editing source programs
shared records 93 See SEU (source entry utility)
shift-in character, definition 338 entering source programs
shift-out character, definition 338 See SEU (source entry utility)
SIGN clause, defining with LIKE clause 258 listing 19, 41
sign in PICTURE clause, and performance 268 WITH DEBUGGING MODE switch and compila-
sign test, de-editing 267 tion 313
single device files 162 source text manipulation module 324
size limits, internal 15 space pointer, definition 282
skeleton program 9 spacing 38
SKIP statement 38 special registers
SKIP1 statement 38 ADDRESS OF 280
SKIP2 statement 38 LENGTH OF 280
SKIP3 statement 38 implicit definition 286
slash (/) 12, 38 in Procedure Division 286
SORT statement 312, 348, 368 SPECIAL-NAMES paragraph 12, 233, 335
sort-merge module 324 specific file processing 233
SORT/MERGE statement 348 spooling 91, 92
Source Entry Utility SQL (Structured Query Language) statements 12
See SEU SQLCBL member type 13
source file *SRCDBG option 20
default 10 SRCFILE parameter for CRTCBLPGM
fields 10 command 18
logical structure, specifying 172 SRCMBR parameter for CRTCBLPGM
program, suppressing listing 41 command 18
record length 10 *SRCMBRTXT option 19
source file format SST keyword 126
description 10 stacks, shown in syntax 3
program segments 309 standard error handling 69, 76
record length 10 standard, ANSI X3.23-1985 xiii
source-file-member-name 19 Start COBOL Debug (STRCBLDBG)
source-file-name 18 command 314, 316
source language debugging 313 Start Debug (STRDBG) command 55
source listing, example 41 Start Source Entry Utility (STRSEU) command 9
source member type START statement 242, 344
CICSCBL 13 STARTING phrase 194
CICSSQLCBL 13 starting the compiler 15
compiling 16

Index 409
statement length, maximum 11, 12 storage, initialization of 279
statement number (STMT) field 44, 49 storage, using less 22
statement number, compiler-generated STRCBLDBG (Start COBOL Debug)
(STMT) 43 command 314, 316
statements STRDBG (Start Debug) command 55
ACCEPT 103, 177, 343 STRING statement 346
ACQUIRE 178 STRSEU (Start Source Entry Utility) command 9
ALTER 312 structure, program
arithmetic, in DBCS processing 345 See program structure
breakpoints 57 Structured Query Language (SQL) statements 12
CALL 312 subfield contents, DEBUG-ITEM special
CANCEL 336 register 319
CLOSE 179, 336 subfiles 156—158, 182
COMMIT 95 subprogram 36, 273
compiler output 37 linkage 281
COPY 104, 114, 335, 348 subscript range checking, specifying 21
DISPLAY 344 subscript ranges 21
DIVIDE 336 subscripting 265
DROP 179 substitution character (X’3F’) in data 137
EJECT 38 suffix -DDS
in syntax diagrams 3 added to key field name 123, 125
INSPECT 345 added to reserved word 123, 127
MERGE 312, 335, 348, 368 summary of changes
MOVE 319, 346 changes made in Version 2 Release 1.1
OPEN 180 changes made in Version 2 Release 2
PERFORM 312, 336 support for ANSI X3.23-1985 standard 323
PROCESS 32, 337 suppressing source listing 41
READ 182, 335, 344 suppression of messages 330
RELEASE 348 switch, run-time 67, 314, 315
RETURN 335, 348 symbols used in syntax 3
REWRITE 191, 344 *SYNC option 22
ROLLBACK 95 syntax
SEARCH 348 arrows 3
SET 346 checking, in SEU 11, 12, 39
SKIP 38 checking, unit of 11
SORT 312, 368 debugging lines 321
START 344 diagrams, using 3
START, generic 242 keywords in 2
STOP 348 notation 2
STRING 346 of CRTCBLPGM command 29
UNSTRING 346 optional items 3
USE 199 punctuation 2
WRITE 193, 336, 345 required and optional clauses 3
*STDERR option 22 required items 3
*STDINZ option 23 stacks 3
STOP RUN statement 274, 306 symbols 3
STOP statement 348 system override considerations 92
storage optimization system reply list 52
See segmentation

410 COBOL/400 User’s Guide


transaction files (continued)
T display management 140
table items, attributes of 46
Environment Division considerations 171
table, reference modification 263
externally described 139
target release 26, 31
file control entry and Environment
template, program 21
Division 171
TERMINAL phrase 182, 187, 190, 192, 193, 198
file description entry and Environment
termination, program 52, 336
Division 175
testing COBOL/400 programs
FILE STATUS clause 173
and debugging 55
file status, setting of 71
breakpoints 57, 63
major return code 71
changing variable contents 63
minor return code 71
Data Division map and IRP listing, using 61
ORGANIZATION clause 172
displaying table elements 55, 60
organization of 172
displaying variables 60
Procedure Division considerations 176
file status 103
processing externally described 142
formatted dump 67
program-described
OS/400 functions for 55
RELATIVE KEY clause 173
overview 6
return codes 71
security, maintaining 55
sample programs, work station 200
test libraries 55
transferring control to another program 273
traces 64, 66
transferring program control 273
text-description 19
triple spacing 38
TEXT parameter for CRTCBLPGM command 19
TGTRLS parameter for CRTCBLPGM
command 26, 31 U
time data type 132 UFCB (user file control block) 71
time value, retrieving 262 unattended mode, running the program 331
time-separation characters 38 unblocking input records 102
timestamp data type 132 underscores, removed from end of field
TITLE statement 38 name 113
tools for entering source programs 9 underscores, translated to hyphens 113
traces *UNDSPCHR option 25
as an OS/400 function 55 unit of syntax checking 11
considerations 66 *UNREF option 22
description 64 unreferenced data items 22
example 64 unreferenced identifiers 15
using 64 UNSTRING statement 346
tracing a loop 271 updating
trademarks x and extension of sequential files 351, 353
transaction files indexed files 351, 357
ACCESS MODE clause 173 relative files 351, 363
and subfiles 158 sequential files 353
ASSIGN clause 172 UPSI (user program status indicator) switch
Boolean data facilities 176 USAGE clause
CONTROL-AREA clause 174 defining with LIKE clause 258
data description specifications (DDS) for 139, numeric 116
140 USAGE IS POINTER 282
Data Division considerations 173, 175 with transaction files 144
defining 139
description 139

Index 411
USE FOR DEBUGGING declarative 316, 317
in the Procedure Division 316
W
where DBCS characters can be used 340
using the procedures 317
WITH DEBUGGING MODE switch and compila-
*USE option 27
tion 313
USE procedure
work stations
role since Version 1, Release 3 80
communications between 139
USE statement
sample programs
coded examples 353, 354
order inquiry 206
description 199
payment update 217
EXCEPTION/ERROR for TRANSACTION
transaction inquiry 200
file 199
validity checking 140
format 199
Working-Storage section
user file control block (UFCB) 71
defining identifiers 258
*USER option 26
WRITE statement
user profile 26
and DBCS 345
user program status indicator (UPSI) switch
changes from ANSI 74 COBOL 336
user spaces
description 193
accessing using APIs 291
for program-described transaction files 193
using a subfile for display 156—158
for TRANSACTION file 193
using double-byte characters 337
format, nonsubfile 193—195
using less storage 22
format, subfile 198—199
USING phrase 335
indicators 145, 146
using REPLACING in format 2 COPY
processing facilities 181—182
statement 127
using the COBOL/400 language
See COBOL/400 language X
USRPRF parameter for CRTCBLPGM X’3F’ (substitution character) in data 137
command 26 *XREF option 19, 21, 37

V
V2R1M0 option 31
V2R1M1 option 31
V2R2M0 option 31
valid RECORD KEYS 242
validity checking 140
VALUE clause 342
VALUE IS NULL 304
value of figurative constant QUOTE 20
*VARCHAR option 23
variable-length fields 131
defining 131
example of 131, 134
length of, example of 132
maximum length of 131
restrictions 131
variables, changing values while testing 63
*VBSUM option 19, 37
verbs usage by count listing 43

412 COBOL/400 User’s Guide

You might also like