AS/400 Advanced Series ÉÂÔ

ILE RPG for AS/400

Programmer's Guide
Version 4

SC09-2507-00
AS/400 Advanced Series ÉÂÔ
ILE RPG for AS/400
Programmer's Guide
Version 4

SC09-2507-00
Note: Before using this information and the product it supports, be sure to read the general information under “Notices” on
page xix.

First Edition (February 1998)

This edition to Version 4, Release 2, Modification 0, of IBM Integrated Language Environment RPG for AS/400 (Program 5769-RG1)
and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you are using the correct
edition for the level of the product. Consult the latest edition of the applicable IBM system bibliography for current information on this
product.

Changes or additions to the text and illustrations are indicated by a vertical line to the left of the change or addition.

Order publications through your IBM representative or the IBM branch office 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, address your comments to:

IBM Canada Ltd. Laboratory

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

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

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

 Copyright International Business Machines Corporation 1998. 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.
 Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Programming Interface Information . . . . . . . . . . . . . . . . . . . . . . . . . xix
Trademarks and Service Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Who Should Use This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
| What's New This Release? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
| Changes to this Guide Since V3R7 . . . . . . . . . . . . . . . . . . . . . . . xxiii

ILE RPG Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Overview of the RPG IV Programming Language . . . . . . . . . 3

RPG IV Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Cycle Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Subprocedure logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Operation Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Example of an ILE RPG Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Using the OS/400 System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Interacting with the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
AS/400 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Application Development ToolSet . . . . . . . . . . . . . . . . . . . . . . . . . 13
| Application Development ToolSet Client Server for AS/400 . . . . . . . . . . 14

Chapter 2. RPG Programming in ILE . . . . . . . . . . . . . . . . . . . . . . . 17

Program Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Program Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Program Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Source Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Bindable APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
| Multi-Threaded Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 3. Program Creation Strategies . . . . . . . . . . . . . . . . . . . . . 23

Strategy 1: OPM-Compatible Application . . . . . . . . . . . . . . . . . . . . . . 23
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Example of OPM-Compatible Program . . . . . . . . . . . . . . . . . . . . . . 24
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Strategy 2: ILE Program Using CRTBNDRPG . . . . . . . . . . . . . . . . . . . 25
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Example of ILE Program Using CRTBNDRPG . . . . . . . . . . . . . . . . . 26
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Strategy 3: ILE Application Using CRTRPGMOD . . . . . . . . . . . . . . . . . 27
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Single-Language ILE Application Scenario . . . . . . . . . . . . . . . . . . . 28
Mixed-Language ILE Application Scenario . . . . . . . . . . . . . . . . . . . . 29
Advanced Application Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
A Strategy to Avoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

 Copyright IBM Corp. 1998 iii

 Chapter 4. Creating an Application Using Multiple Procedures . . . . . . 33
A Multiple Procedures Module — Overview . . . . . . . . . . . . . . . . . . . . 33
Main Procedures and Subprocedures . . . . . . . . . . . . . . . . . . . . . . 33
Prototyped Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Example of Module with Multiple Procedures . . . . . . . . . . . . . . . . . . . . 36
The Entire ARRSRPT Program . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Coding Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
General Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Program Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Main Procedure Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Subprocedure Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
For Further Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Main Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Subprocedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Prototyped Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Creating and Running an ILE RPG Application . . . . . . . . . . . . . . . . . . . . . . . . . 49

Chapter 5. Entering Source Statements . . . . . . . . . . . . . . . . . . . . . 51

Creating a Library and Source Physical File . . . . . . . . . . . . . . . . . . . . 51
Using the Source Entry Utility (SEU) . . . . . . . . . . . . . . . . . . . . . . . . . 52
Using SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 6. Creating a Program with the CRTBNDRPG Command . . . . . 57

Using the CRTBNDRPG Command . . . . . . . . . . . . . . . . . . . . . . . . . 57
Creating a Program for Source Debugging . . . . . . . . . . . . . . . . . . . 59
Creating a Program with Static Binding . . . . . . . . . . . . . . . . . . . . . 60
Creating an OPM-Compatible Program Object . . . . . . . . . . . . . . . . . 61
Using a Compiler Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Obtaining a Compiler Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Customizing a Compiler Listing . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Correcting Compilation Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Correcting Run-time Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Using a Compiler Listing for Maintenance . . . . . . . . . . . . . . . . . . . . 69
Accessing the RETURNCODE Data Area . . . . . . . . . . . . . . . . . . . . . 70

Chapter 7. Creating a Program with the CRTRPGMOD and CRTPGM

Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Creating a Module Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Using the CRTRPGMOD Command . . . . . . . . . . . . . . . . . . . . . . . 74
Creating a Module for Source Debugging . . . . . . . . . . . . . . . . . . . . 78
Additional Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Behavior of Bound ILE RPG Modules . . . . . . . . . . . . . . . . . . . . . . 80
Related CL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Binding Modules into a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Using the CRTPGM Command . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Additional Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Related CL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Using a Binder Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Changing a Module or Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Using the UPDPGM Command . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Changing the Optimization Level . . . . . . . . . . . . . . . . . . . . . . . . . 87
Removing Observability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

iv ILE RPG for AS/400 Programmer's Guide

 Reducing an Object's Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Chapter 8. Creating a Service Program . . . . . . . . . . . . . . . . . . . . . 91

Service Program Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Strategies for Creating Service Programs . . . . . . . . . . . . . . . . . . . . . . 92
Creating a Service Program Using CRTSRVPGM . . . . . . . . . . . . . . . . . 92
Changing A Service Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Related CL commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Sample Service Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Creating the Service Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Binding to a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Updating the Service Program . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Sample Binder Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 9. Running a Program . . . . . . . . . . . . . . . . . . . . . . . . . 103

Running a Program Using the CL CALL Command . . . . . . . . . . . . . . . 103
Passing Parameters using the CL CALL Command . . . . . . . . . . . . . 103
Running a Program From a Menu-Driven Application . . . . . . . . . . . . . . 106
Running a Program Using a User-Created Command . . . . . . . . . . . . . . 108
Replying to Run-Time Inquiry Messages . . . . . . . . . . . . . . . . . . . . . 108
Ending an ILE Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Managing Activation Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Specifying an Activation Group . . . . . . . . . . . . . . . . . . . . . . . . . 110
Running in the OPM Default Activation Group . . . . . . . . . . . . . . . . 111
Maintaining OPM RPG/400 and ILE RPG Program Compatibility . . . . . 111
Deleting an Activation Group . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Reclaim Resources Command . . . . . . . . . . . . . . . . . . . . . . . . . 112
Managing Dynamically-Allocated Storage . . . . . . . . . . . . . . . . . . . . . 113
Managing the Default Heap Using RPG Operations . . . . . . . . . . . . . 113
Heap Storage Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Managing Your Own Heap Using ILE Bindable APIs . . . . . . . . . . . . . 120

Chapter 10. Calling Programs and Procedures . . . . . . . . . . . . . . . 129

Program/Procedure Call Overview . . . . . . . . . . . . . . . . . . . . . . . . . 129
Calling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Calling Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
The Call Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Recursive Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Parameter-Passing Considerations . . . . . . . . . . . . . . . . . . . . . . . 133
Using a Prototyped Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Using the CALLP Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Calling within an Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Examples of Free-Form Call . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Passing Prototyped Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Parameter Passing Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Using Operational Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Omitting Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Checking for the Number of Passed Parameters . . . . . . . . . . . . . . . 143
Passing Less Data Than Required . . . . . . . . . . . . . . . . . . . . . . . 148
Order of Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Interlanguage Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Using the Fixed-Form Call Operations . . . . . . . . . . . . . . . . . . . . . . . 150
Examples of CALL and CALLB . . . . . . . . . . . . . . . . . . . . . . . . . 151
Passing Parameters Using PARM and PLIST . . . . . . . . . . . . . . . . . 151

Contents v
 Returning from a Called Program or Procedure . . . . . . . . . . . . . . . . . 153
Returning from a Main Procedure . . . . . . . . . . . . . . . . . . . . . . . . 153
Returning from a Subprocedure . . . . . . . . . . . . . . . . . . . . . . . . . 156
Returning using ILE Bindable APIs . . . . . . . . . . . . . . . . . . . . . . . 156
Using Bindable APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Examples of Using Bindable APIs . . . . . . . . . . . . . . . . . . . . . . . 158
Calling a Graphics Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Calling Special Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Debugging and Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Chapter 11. Debugging Programs . . . . . . . . . . . . . . . . . . . . . . . 163

The ILE Source Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Debug Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Preparing a Program for Debugging . . . . . . . . . . . . . . . . . . . . . . . . 166
Creating a Root Source View . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Creating a COPY Source View . . . . . . . . . . . . . . . . . . . . . . . . . 168
Creating a Listing View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Creating a Statement View . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Starting the ILE Source Debugger . . . . . . . . . . . . . . . . . . . . . . . . . 169
STRDBG Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Setting Debug Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Adding/Removing Programs from a Debug Session . . . . . . . . . . . . . . . 172
Example of Adding a Service Program to a Debug Session . . . . . . . . 172
Example of Removing ILE Programs from a Debug Session . . . . . . . . 173
Viewing the Program Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Viewing a Different Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Changing the View of a Module . . . . . . . . . . . . . . . . . . . . . . . . . 176
Setting and Removing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . 178
Setting and Removing Unconditional Job Breakpoints . . . . . . . . . . . . 179
| Setting and Removing Unconditional Thread Breakpoints . . . . . . . . . . 180
Setting and Removing Conditional Job Breakpoints . . . . . . . . . . . . . 181
National Language Sort Sequence (NLSS) . . . . . . . . . . . . . . . . . . 184
Setting and Removing Job Breakpoints Using Statement Numbers . . . . 185
| Setting and Removing Conditional Thread Breakpoints . . . . . . . . . . . 187
Removing All Job and Thread Breakpoints . . . . . . . . . . . . . . . . . . 187
Setting and Removing Watch Conditions . . . . . . . . . . . . . . . . . . . . . 188
Characteristics of Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Setting Watch Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Displaying Active Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Removing Watch Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Example of Setting a Watch Condition . . . . . . . . . . . . . . . . . . . . . . 192
Stepping Through the Program Object . . . . . . . . . . . . . . . . . . . . . . 194
Stepping Over Call Statements . . . . . . . . . . . . . . . . . . . . . . . . . 195
Stepping Into Call Statements . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Displaying Data and Expressions . . . . . . . . . . . . . . . . . . . . . . . . 199
Changing the Value of Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Displaying Attributes of a Field . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Equating a Name with a Field, Expression, or Command . . . . . . . . . . . . 210
Source Debug National Language Support for ILE RPG . . . . . . . . . . . . 211
Sample Source for Debug Examples . . . . . . . . . . . . . . . . . . . . . . . 211

Chapter 12. Handling Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 217

vi ILE RPG for AS/400 Programmer's Guide

 Exception Handling Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
ILE RPG Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Using Exception Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Exception Handler Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Nested Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Unhandled Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Optimization Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Using RPG-Specific Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
| Specifying Error Indicators or the 'E' Operation Code Extender . . . . . . 227
Using an Error Subroutine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Specifying a Return Point in the ENDSR Operation . . . . . . . . . . . . . 238
ILE Condition Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Using a Condition Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Using Cancel Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Problems when ILE CL Monitors for Notify and Status Messages . . . . . . . 247

Chapter 13. Obtaining a Dump . . . . . . . . . . . . . . . . . . . . . . . . . 251

Obtaining an ILE RPG Formatted Dump . . . . . . . . . . . . . . . . . . . . . 251
Using the DUMP Operation Code . . . . . . . . . . . . . . . . . . . . . . . . . 251
Example of a Formatted Dump . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Working with Files and Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Chapter 14. Defining Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Associating Files with Input/Output Devices . . . . . . . . . . . . . . . . . . . 261
Naming Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Types of File Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Using Files with External-Description as Program-Described . . . . . . . . 264
Example of Some Typical Relationships between Programs and Files . . 264
Defining Externally Described Files . . . . . . . . . . . . . . . . . . . . . . . . 265
Renaming Record-Format Names . . . . . . . . . . . . . . . . . . . . . . . 266
Renaming Field Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Ignoring Record Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Using Input Specifications to Modify an External Description . . . . . . . . 267
Using Output Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Level Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Defining Program-Described Files . . . . . . . . . . . . . . . . . . . . . . . . . 271
Data Management Operations and ILE RPG I/O Operations . . . . . . . . . . 271

Chapter 15. General File Considerations . . . . . . . . . . . . . . . . . . . 273

Overriding and Redirecting File Input and Output . . . . . . . . . . . . . . . . 273
Example of Redirecting File Input and Output . . . . . . . . . . . . . . . . . 274
File Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Record Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Sharing an Open Data Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Spooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Output Spooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
SRTSEQ/ALTSEQ in an RPG Program versus a DDS File . . . . . . . . . . 279

Chapter 16. Accessing Database Files . . . . . . . . . . . . . . . . . . . . 281

Database Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Physical Files and Logical Files . . . . . . . . . . . . . . . . . . . . . . . . . 281
Data Files and Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Contents vii
 Using Externally Described Disk Files . . . . . . . . . . . . . . . . . . . . . . . 282
Record Format Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Access Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Valid Keys for a Record or File . . . . . . . . . . . . . . . . . . . . . . . . . 285
Record Blocking and Unblocking . . . . . . . . . . . . . . . . . . . . . . . . 287
Using Program-Described Disk Files . . . . . . . . . . . . . . . . . . . . . . . . 288
Indexed File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Sequential File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Record Address File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Methods for Processing Disk Files . . . . . . . . . . . . . . . . . . . . . . . . . 291
Consecutive Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Sequential-by-Key Processing . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Random-by-Key Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Sequential-within-Limits Processing . . . . . . . . . . . . . . . . . . . . . . . 300
Relative-Record-Number Processing . . . . . . . . . . . . . . . . . . . . . . 303
Valid File Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Using Commitment Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Starting and Ending Commitment Control . . . . . . . . . . . . . . . . . . . 307
Specifying Files for Commitment Control . . . . . . . . . . . . . . . . . . . 309
Using the COMMIT Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Specifying Conditional Commitment Control . . . . . . . . . . . . . . . . . . 311
Commitment Control in the Program Cycle . . . . . . . . . . . . . . . . . . 312
DDM Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Using Pre-V3R1 DDM Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Chapter 17. Accessing Externally Attached Devices . . . . . . . . . . . . 315

Types of Device Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Accessing Printer Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Specifying PRINTER Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Handling Page Overflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Using the Fetch-Overflow Routine in Program-Described Files . . . . . . . 320
Changing Forms Control Information in a Program-Described File . . . . . 323
Accessing Tape Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Accessing Display Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Using Sequential Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Specifying a Sequential File . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Using SPECIAL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Example of Using a Special File . . . . . . . . . . . . . . . . . . . . . . . . 329

Chapter 18. Using WORKSTN Files . . . . . . . . . . . . . . . . . . . . . . 331

Intersystem Communications Function . . . . . . . . . . . . . . . . . . . . . . 331
Using Externally Described WORKSTN Files . . . . . . . . . . . . . . . . . . . 331
Specifying Function Key Indicators on Display Device Files . . . . . . . . . 334
Specifying Command Keys on Display Device Files . . . . . . . . . . . . . 334
Processing an Externally Described WORKSTN File . . . . . . . . . . . . . 335
Using Subfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Using Program-Described WORKSTN Files . . . . . . . . . . . . . . . . . . . 338
Using a Program-Described WORKSTN File with a Format Name . . . . . 339
Using a Program-Described WORKSTN File without a Format Name . . . 340
Valid WORKSTN File Operations . . . . . . . . . . . . . . . . . . . . . . . . . 341
EXFMT Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
READ Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
WRITE Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Multiple-Device Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

viii ILE RPG for AS/400 Programmer's Guide

 Chapter 19. Example of an Interactive Application . . . . . . . . . . . . . 345
Database Physical File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Main Menu Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
MAINMENU: DDS for a Display Device File . . . . . . . . . . . . . . . . . 346
CUSMAIN: RPG Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
File Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
CUSMSTL1: DDS for a Logical File . . . . . . . . . . . . . . . . . . . . . . 349
MNTMENU: DDS for a Display Device File . . . . . . . . . . . . . . . . . . 350
CUSMNT: RPG Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Search by Zip Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
CUSMSTL2: DDS for a Logical File . . . . . . . . . . . . . . . . . . . . . . 358
SZIPMENU: DDS for a Display Device File . . . . . . . . . . . . . . . . . . 359
SCHZIP: RPG Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Search and Inquiry by Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
CUSMSTL3: DDS for a Logical File . . . . . . . . . . . . . . . . . . . . . . 364
SNAMMENU: DDS for a Display Device File . . . . . . . . . . . . . . . . . 365
SCHNAM: RPG Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

Appendix A. Behavioral Differences Between OPM RPG/400 and ILE

RPG for AS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
Debugging and Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . 374
I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
DBCS Data in Character Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Appendix B. Using the RPG III to RPG IV Conversion Aid . . . . . . . . 379

Conversion Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
File Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
The Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Conversion Aid Tool Requirements . . . . . . . . . . . . . . . . . . . . . . . 381
What the Conversion Aid Won't Do . . . . . . . . . . . . . . . . . . . . . . . 382
Converting Your Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
The CVTRPGSRC Command . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Converting a Member Using the Defaults . . . . . . . . . . . . . . . . . . . 387
Converting All Members in a File . . . . . . . . . . . . . . . . . . . . . . . . 388
Converting Some Members in a File . . . . . . . . . . . . . . . . . . . . . . 388
Performing a Trial Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Obtaining Conversion Reports . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Converting Auto Report Source Members . . . . . . . . . . . . . . . . . . . 389
Converting Source Members with Embedded SQL . . . . . . . . . . . . . . 390
Inserting Specification Templates . . . . . . . . . . . . . . . . . . . . . . . . 390
Converting Source from a Data File . . . . . . . . . . . . . . . . . . . . . . 390
Example of Source Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Analyzing Your Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Using the Conversion Report . . . . . . . . . . . . . . . . . . . . . . . . . . 394
Using the Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Resolving Conversion Problems . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Compilation Errors in Existing RPG III Code . . . . . . . . . . . . . . . . . 398
Unsupported RPG III Features . . . . . . . . . . . . . . . . . . . . . . . . . 398
Use of the /COPY Compiler Directive . . . . . . . . . . . . . . . . . . . . . 398

Contents ix
 Use of Externally Described Data Structures . . . . . . . . . . . . . . . . . 401
Run-time Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

Appendix C. The Create Commands . . . . . . . . . . . . . . . . . . . . . . 405

Using CL Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
How to Interpret Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . 405
CRTBNDRPG Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Description of the CRTBNDRPG Command . . . . . . . . . . . . . . . . . . 408
CRTRPGMOD Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Description of the CRTRPGMOD command . . . . . . . . . . . . . . . . . . 421

Appendix D. Compiler Listings . . . . . . . . . . . . . . . . . . . . . . . . . 423

Reading a Compiler Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Prologue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
Source Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Additional Diagnostic Messages . . . . . . . . . . . . . . . . . . . . . . . . . 430
Output Buffer Positions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
/COPY Member Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Compile-Time Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Key Field Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Cross-Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
External References List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
Message Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Final Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
Code Generation and Binding Errors . . . . . . . . . . . . . . . . . . . . . . 436

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

x ILE RPG for AS/400 Programmer's Guide

Figures
1. RPG Program Logic Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. DDS for Employee physical file . . . . . . . . . . . . . . . . . . . . . . . . . 7
3. DDS for TRANSACT physical file . . . . . . . . . . . . . . . . . . . . . . . . 7
4. A Sample Payroll Calculation Program . . . . . . . . . . . . . . . . . . . . 10
5. Program Creation in ILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6. OPM-Compatible Application . . . . . . . . . . . . . . . . . . . . . . . . . . 24
7. ILE Program Using CRTBNDRPG . . . . . . . . . . . . . . . . . . . . . . . 26
8. Single-Language Application Using CRTRPGMOD and CRTPGM . . . . 29
9. Mixed-Language Application . . . . . . . . . . . . . . . . . . . . . . . . . . 30
10. Advanced Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
11. Scenario to Avoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
12. An ILE RPG module with Multiple Procedures . . . . . . . . . . . . . . . . 34
13. Prototype for FmtCust Procedure . . . . . . . . . . . . . . . . . . . . . . . 35
14. Prototype for NumToChar Procedure . . . . . . . . . . . . . . . . . . . . . 35
15. Calling the FmtCust Procedure . . . . . . . . . . . . . . . . . . . . . . . . 35
16. Calling the NumToChar Procedure . . . . . . . . . . . . . . . . . . . . . . 36
17. Components of the ARRSRPT Module . . . . . . . . . . . . . . . . . . . . 37
18. Source for Subprocedure InArrears . . . . . . . . . . . . . . . . . . . . . . 38
19. Source for Subprocedure FmtCust . . . . . . . . . . . . . . . . . . . . . . 39
20. Source for module CVTPROCS, containing subprocedure NumToChar . 40
21. The ARRSRPT Application . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
22. ILE RPG Complete Source for ARRSRPT Module . . . . . . . . . . . . . 41
23. Output for ARRSRPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
24. DDS for CUSTFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
25. DDS for CUSTRPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
26. ILE RPG Record Length Breakdown . . . . . . . . . . . . . . . . . . . . . 51
27. Edit Display for a New Member . . . . . . . . . . . . . . . . . . . . . . . . 53
28. Source for EMPRPT member . . . . . . . . . . . . . . . . . . . . . . . . . 54
29. DDS for EMPRPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
30. SQL Statements in an ILE RPG Program . . . . . . . . . . . . . . . . . . 56
31. Display Module Source display for EMPRPT . . . . . . . . . . . . . . . . 60
32. A Sample Payroll Calculation Program . . . . . . . . . . . . . . . . . . . . 62
33. Sample Source Part of the Listing with Indentation . . . . . . . . . . . . . 66
34. Sample Finger In-Line Diagnostic Messages . . . . . . . . . . . . . . . . 67
35. Sample Non-Finger In-Line Diagnostic Messages . . . . . . . . . . . . . . 68
36. Source for TRANSSVC member . . . . . . . . . . . . . . . . . . . . . . . . 76
37. Source for TRANSP /COPY member . . . . . . . . . . . . . . . . . . . . . 78
38. Source for TRANSRPT module . . . . . . . . . . . . . . . . . . . . . . . . 79
39. DDS for TRNSDTA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
40. Structure of Program TRPT . . . . . . . . . . . . . . . . . . . . . . . . . . 81
41. File QSYSPRT for TRPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
42. Source for Service Program CvtToHex . . . . . . . . . . . . . . . . . . . . 95
43. Source for /COPY Member with Prototype for CvtToHex . . . . . . . . . . 97
44. Source for Binder Language for CvtToHex . . . . . . . . . . . . . . . . . . 97
45. Source for Test Program CVTHEXPGM . . . . . . . . . . . . . . . . . . . 99
46. Basic Binder listing for CVTHEXPGM . . . . . . . . . . . . . . . . . . . . 101
47. ILE RPG Program that Requires Parameters at Run Time . . . . . . . 104
48. DDS for EMPRPT2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
49. Example of an Application Menu . . . . . . . . . . . . . . . . . . . . . . 106
50. Data Description Specification of an Application Menu . . . . . . . . . . 107

Contents xi
 51. Source for Menu Program . . . . . . . . . . . . . . . . . . . . . . . . . . 107
52. Memory Management - Build a Linked List of Names . . . . . . . . . . 114
53. Heap Storage Misuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
54. /COPY file DYNARRI containing prototypes for DYNARRAY module . 120
55. Global variables and local prototypes for DYNARRAY . . . . . . . . . . 121
56. DYNARRAY Subprocedures . . . . . . . . . . . . . . . . . . . . . . . . . 123
57. Sample module using procedures in DYNARRAY . . . . . . . . . . . . . 127
58. Program and Procedure Calls on the Call Stack . . . . . . . . . . . . . 131
59. Three Modules, each with subprocedures . . . . . . . . . . . . . . . . . 132
60. Recursive Call Stack To Be Avoided . . . . . . . . . . . . . . . . . . . . 133
61. Prototype for CVTCHR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
62. Calling a Prototyped Procedure within an Expression . . . . . . . . . . 136
63. Prototype for Procedure DO_CALC with VALUE Parameters . . . . . . 139
64. Procedure Interface Definition for DO_CALC Procedure . . . . . . . . . 139
65. Prototype for ILE CEE API CEETSTA with CONST Parameter . . . . . 140
66. Requesting Operational Descriptors for a Prototyped Procedure . . . . 141
67. Prototype for System API QCMDEXC with Optional Parameter . . . . . 142
68. Source for procedure FMTADDR . . . . . . . . . . . . . . . . . . . . . . 144
69. Source for /COPY member with Prototype for Procedure FMTADDR . 145
70. Source for procedure PRTADDR . . . . . . . . . . . . . . . . . . . . . . 146
71. Prototype for System API QCMDEXC with *VARSIZE Parameter . . . 148
72. Sample Call Syntax for ILE Bindable APIs . . . . . . . . . . . . . . . . . 157
73. Display Module Source display for program DEBUGEX . . . . . . . . . 171
74. Adding an ILE Service Program to a Debug Session . . . . . . . . . . . 173
75. Removing an ILE Program from a Debug Session . . . . . . . . . . . . 174
76. Changing to a Different Module . . . . . . . . . . . . . . . . . . . . . . . 176
77. Source View of ILE C procedure cproc . . . . . . . . . . . . . . . . . . . 176
| 78. Changing a View of a Module . . . . . . . . . . . . . . . . . . . . . . . . 177
79. Setting an Unconditional Job Breakpoint . . . . . . . . . . . . . . . . . . 180
80. Setting a Conditional Job Breakpoint . . . . . . . . . . . . . . . . . . . . 182
81. Setting a Conditional Job Breakpoint Using the BREAK Command . . 183
82. Setting a Breakpoint Using Statement View . . . . . . . . . . . . . . . . 186
83. Example of a Work with Watch Display . . . . . . . . . . . . . . . . . . . 190
84. Example of a Display Watch Window . . . . . . . . . . . . . . . . . . . . 190
85. Example of a Display Debug Watch Display . . . . . . . . . . . . . . . . 191
| 86. Example of Message Stating WATCH was Successfully Set . . . . . . 193
87. Example of a Display Module Source Panel . . . . . . . . . . . . . . . . 194
88. Display Module Source display of DBGEX Before Stepping Into
RPGPGM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
89. Stepping into RPGPGM . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
90. Stepping into Subprocedure Switch . . . . . . . . . . . . . . . . . . . . . 199
91. Displaying a Field using the EVAL debug command . . . . . . . . . . . 200
92. Sample EVAL commands based on Module DBGEX . . . . . . . . . . . 201
93. Sample EVAL commands for an Array . . . . . . . . . . . . . . . . . . . 202
94. Sample EVAL commands for a Table . . . . . . . . . . . . . . . . . . . . 203
95. Using EVAL with Data Structures . . . . . . . . . . . . . . . . . . . . . . 204
96. Sample EVAL commands for an Array . . . . . . . . . . . . . . . . . . . 205
97. Examples of %SUBSTR using DBGEX . . . . . . . . . . . . . . . . . . . 207
98. Examples of Changing the Values of Fields based on DBGEX . . . . . 209
99. Examples of Displaying the Attributes of Fields based on DBGEX . . . 210
100. Source for Module DBGEX . . . . . . . . . . . . . . . . . . . . . . . . . . 212
101. Source for OPM Program RPGPGM . . . . . . . . . . . . . . . . . . . . 216
102. Source for C Procedure cproc . . . . . . . . . . . . . . . . . . . . . . . . 216
103. Call Stack and Exception Message Percolation . . . . . . . . . . . . . . 219

xii ILE RPG for AS/400 Programmer's Guide

 104. Scenario for Unhandled Escape Message . . . . . . . . . . . . . . . . . 224
105. Scenario for Unhandled Function Check . . . . . . . . . . . . . . . . . . 226
106. Example of File Exception Handling . . . . . . . . . . . . . . . . . . . . . 231
107. Example of *PSSR Subroutine in Main Procedure . . . . . . . . . . . . 234
108. Example of Subprocedure *PSSR Subroutine with GOTO . . . . . . . . 235
109. Example of Subprocedure *PSSR Subroutine with RETURN . . . . . . 236
110. Avoiding a Loop in an Error Subroutine . . . . . . . . . . . . . . . . . . . 237
111. Source for Condition Handler for Out-of-Bounds Substring Error . . . . 240
112. Source for Registering a Condition Handler . . . . . . . . . . . . . . . . 242
| 113. Enabling and Coding a Cancel Handler for a Subprocedure . . . . . . . 245
114. Output from CANHDLR program . . . . . . . . . . . . . . . . . . . . . . 247
| 115. ILE Condition Handler that Ignores CPF4906 . . . . . . . . . . . . . . . 249
| 116. How to Ignore Status and Notify Messages . . . . . . . . . . . . . . . . 250
117. Program Status Information section of Formatted Dump . . . . . . . . . 252
118. Feedback Areas section of Formatted Dump . . . . . . . . . . . . . . . 254
119. Information Provided for Full-Formatted Dump . . . . . . . . . . . . . . 255
120. Data section of Formatted Dump . . . . . . . . . . . . . . . . . . . . . . 256
121. Identifying a Display File in an RPG Program . . . . . . . . . . . . . . . 262
122. Associating a file name with a display file description . . . . . . . . . . 262
123. Associating a file name with a display file description . . . . . . . . . . 263
124. Typical Relationships between an RPG Program and Files on the
AS/400 System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
125. RENAME Keyword for Record Format Names in an Externally Described
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
126. Prefix Keyword for Record Format Names in an Externally Described
File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
127. IGNORE Keyword for Record Formats in an Externally Described File 267
128. Overriding and Adding RPG Functions to an External Description . . . 268
129. Adding RPG Functions to an External Description . . . . . . . . . . . . 268
130. Output Specifications for an Externally Described File . . . . . . . . . . 270
131. Overriding File Input and Output Example . . . . . . . . . . . . . . . . . 273
132. Redirecting File Input and Output Example . . . . . . . . . . . . . . . . 275
133. Output Spooling Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
134. Example of the Data Description Specifications for a Database File . . 283
135. Example of a field Reference File . . . . . . . . . . . . . . . . . . . . . . 284
136. DDS and corresponding File-Description Specification Detail Flow of
RPG IV Exception/Error Handling . . . . . . . . . . . . . . . . . . . . . . 289
137. (Part 1 of 2). Using Data Description Specifications to Define the Access
Path (Composite Key) for an Indexed File . . . . . . . . . . . . . . . . . 289
138. (Part 2 of 2). Using Data Description Specifications to Define the Access
Path (Composite Key) for an Indexed File . . . . . . . . . . . . . . . . . 290
139. DDS for database file EMPMST (physical file) . . . . . . . . . . . . . . . 294
140. DDS for database file TRWEEK (physical file) . . . . . . . . . . . . . . . 294
141. DDS for database file EMPL1 (logical file) . . . . . . . . . . . . . . . . . 294
142. Sequential-by-Key Processing, Example 1 . . . . . . . . . . . . . . . . . 295
143. Sequential-by-Key Processing, Example 2 . . . . . . . . . . . . . . . . . 296
144. Sequential-by-Key Processing, Example 5 . . . . . . . . . . . . . . . . . 297
145. DDS for database file CHANGE (physical file) . . . . . . . . . . . . . . . 299
146. Random-by-Key Processing of an Externally Described File . . . . . . . 300
147. Sequential-within-Limits Processing of an Externally Described File . . 302
148. DDS for record address file LIMITS (physical file) . . . . . . . . . . . . . 302
149. Sequential-within-Limits Processing of a Program-Described File . . . . 303
150. Example of Using Commitment Control . . . . . . . . . . . . . . . . . . . 311
151. Example of Using Conditional Commitment Control . . . . . . . . . . . . 312

Figures xiii
 152. Printing a Heading on Every Page . . . . . . . . . . . . . . . . . . . . . 319
153. Printing a Field on Every Page . . . . . . . . . . . . . . . . . . . . . . . . 320
154. Overflow Printing: Setting of the Overflow Indicator . . . . . . . . . . . 321
155. Use of Fetch Overflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
156. Example of the PRTCTL Option . . . . . . . . . . . . . . . . . . . . . . . 325
157. SEQ Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
158. SPECIAL Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
159. User-written program USERIO . . . . . . . . . . . . . . . . . . . . . . . . 330
160. Example of the Data Description Specifications for a Display Device File 333
161. Subfile Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
162. Data Description Specifications for a Subfile Record Format . . . . . . 337
163. Data Description Specifications for a Subfile Control-Record Format . . 338
164. DDS for master database file CUSMST (physical file) . . . . . . . . . . 346
165. DDS for display device file MAINMENU . . . . . . . . . . . . . . . . . . 347
166. Source for module CUSMAIN . . . . . . . . . . . . . . . . . . . . . . . . 348
167. Customer Main Inquiry prompt screen . . . . . . . . . . . . . . . . . . . 349
168. DDS for logical file CUSMSTL1 . . . . . . . . . . . . . . . . . . . . . . . 349
169. DDS for display device file MNTMENU . . . . . . . . . . . . . . . . . . . 350
170. Source for module CUSMNT . . . . . . . . . . . . . . . . . . . . . . . . . 352
171. 'Customer File Maintenance' Display Mode prompt screen . . . . . . . 355
172. 'Customer File Maintenance' Display Mode screen . . . . . . . . . . . . 356
173. 'Customer File Maintenance' Add Mode prompt screen . . . . . . . . . 356
174. 'Customer File Maintenance' Add Mode prompt screen . . . . . . . . . 357
175. 'Customer File Maintenance' Delete Mode prompt screen . . . . . . . . 357
176. 'Customer File Maintenance' Update Mode prompt screen . . . . . . . 358
177. DDS for logical file CUSMSTL2 . . . . . . . . . . . . . . . . . . . . . . . 358
178. DDS for display device file SZIPMENU . . . . . . . . . . . . . . . . . . . 359
179. Source for module SCHZIP . . . . . . . . . . . . . . . . . . . . . . . . . 361
180. 'Customer Search by Zip' prompt screen . . . . . . . . . . . . . . . . . . 363
181. 'Customer Search by Zip' screen . . . . . . . . . . . . . . . . . . . . . . 364
182. DDS for logical file CUSMSTL3 . . . . . . . . . . . . . . . . . . . . . . . 364
183. DDS for display device file SNAMMENU . . . . . . . . . . . . . . . . . . 365
184. Source for module SCHNAM . . . . . . . . . . . . . . . . . . . . . . . . . 366
185. 'Customer Search and Inquiry by Name' prompt screen . . . . . . . . . 369
186. 'Customer Search and Inquiry by Name' information screen . . . . . . . 370
187. 'Customer Search and Inquiry by Name' detailed information screen . . 370
188. RPG IV Record Length Breakdown . . . . . . . . . . . . . . . . . . . . . 380
189. RPG III Source for TEST1 . . . . . . . . . . . . . . . . . . . . . . . . . . 391
190. Converted (RPG IV) Source for TEST1 . . . . . . . . . . . . . . . . . . . 392
191. Command Summary of Sample Conversion Report . . . . . . . . . . . . 394
192. Sample Source Section of Conversion Report . . . . . . . . . . . . . . . 395
193. Sample Message Summary of Conversion Report . . . . . . . . . . . . 395
194. Sample Final Summary of Conversion Report . . . . . . . . . . . . . . . 396
195. DDS for model log file QARNCVTLG in library QRPGLE . . . . . . . . 397
| 196. RPG III Source for TEST2 . . . . . . . . . . . . . . . . . . . . . . . . . . 399
| 197. RPG III Source for COPYDS1 . . . . . . . . . . . . . . . . . . . . . . . . 399
198. RPG III /COPY file with input fields only . . . . . . . . . . . . . . . . . . 400
| 199. RPG III Source with a renamed field . . . . . . . . . . . . . . . . . . . . 401
| 200. RPG IV source after converting source with input fields only . . . . . . 401
| 201. DDS for external data structure . . . . . . . . . . . . . . . . . . . . . . . 402
| 202. RPG III source using external data structure with array . . . . . . . . . 402
| 203. RPG IV source with two definitions for the array . . . . . . . . . . . . . 402
| 204. Corrected RPG IV source with a single definition for the array . . . . . 402
205. RPG III source with renamed and initialized external subfield . . . . . . 403

xiv ILE RPG for AS/400 Programmer's Guide

206. RPG IV source with two definitions for renamed subfield . . . . . . . . 403
207. Corrected RPG IV source with a single definition . . . . . . . . . . . . . 403
208. Structure of a Syntax Diagram . . . . . . . . . . . . . . . . . . . . . . . . 405
209. Sample Prologue for CRTBNDRPG . . . . . . . . . . . . . . . . . . . . . 425
210. Sample Source Part of the Listing . . . . . . . . . . . . . . . . . . . . . . 427
211. Sample Additional Diagnostic Messages . . . . . . . . . . . . . . . . . . 430
212. Output Buffer Position Table . . . . . . . . . . . . . . . . . . . . . . . . . 430
213. Sample /COPY Member Table . . . . . . . . . . . . . . . . . . . . . . . . 431
214. Sample Compile-Time Data Section . . . . . . . . . . . . . . . . . . . . 432
215. Sample Key Field Information . . . . . . . . . . . . . . . . . . . . . . . . 433
216. Sample Cross-Reference Table . . . . . . . . . . . . . . . . . . . . . . . 434
217. Sample External References . . . . . . . . . . . . . . . . . . . . . . . . . 435
218. Sample Message Summary . . . . . . . . . . . . . . . . . . . . . . . . . 435
219. Sample Final Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Figures xv
xvi ILE RPG for AS/400 Programmer's Guide
 Tables
1. Commonly Used CL Commands . . . . . . . . . . . . . . . . . . . . . . . . 13
2. Programming Languages Supported on the AS/400 . . . . . . . . . . . . 17
3. CRTBNDRPG Parameters and Their Default Values Grouped by Function 58
4. CRTRPGMOD Parameters and Their Default Values Grouped by Function 74
5. Parameters for CRTPGM Command and their Default Values . . . . . . 83
6. Sections of the Binder Listing based on DETAIL Parameter . . . . . . . . 86
7. Parameters for CRTSRVPGM Command and their Default Values . . . . 93
8. Parameter Passing Options . . . . . . . . . . . . . . . . . . . . . . . . . 135
9. RPG Parameter Passing Methods . . . . . . . . . . . . . . . . . . . . . . 149
10. Meaning of Factor 1 and Factor 2 Entries in PARM Operation . . . . . 152
| 11. Debug Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
12. Non-numeric Conditional Breakpoint Expressions . . . . . . . . . . . . . 185
| 13. Operation Codes Allowing Extender 'E' or an Error Indicator in Positions
| 73-74 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
14. Correlation of RPG Device Types with AS/400 File Types . . . . . . . . 262
15. Data Management Operations and the Corresponding RPG I/O
Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
16. System Open Options Allowed with User Open Options . . . . . . . . . 278
17. Processing Methods for DISK Files . . . . . . . . . . . . . . . . . . . . . 292
18. Valid File Operations for Keyed Processing Methods (Random by Key,
Sequential by Key, Sequential within Limits) . . . . . . . . . . . . . . . . 305
19. Valid File Operations for Non-keyed Processing Methods (Sequential,
Random by Relative Record Number, and Consecutive) . . . . . . . . . 306
20. AS/400 Device Files, Related CL commands, and RPG Device Name 315
21. Results of the Presence or Absence of an Overflow Indicator . . . . . . 319
22. Layout of ILE PRTCTL Data Structure . . . . . . . . . . . . . . . . . . . 323
23. Layout of OPM PRTCTL Data Structure . . . . . . . . . . . . . . . . . . 324
24. Valid File Operation Codes for a Sequential File . . . . . . . . . . . . . 326
25. Valid File Operations for a SPECIAL File . . . . . . . . . . . . . . . . . . 329
26. Valid File Operation Codes for a WORKSTN File . . . . . . . . . . . . . 341
27. Description of Each Module in the Interactive Application Example . . . 345
28. Source Member Types and their Conversion Status . . . . . . . . . . . 380
29. CVTRPGSRC Parameters and Their Default Values Grouped by
Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
30. Sections of the Compiler Listing . . . . . . . . . . . . . . . . . . . . . . . 423

 Copyright IBM Corp. 1998 xvii

xviii ILE RPG for AS/400 Programmer's Guide
 Notices
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, 500 Columbus Avenue, Thornwood, NY 10594, USA.

Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independent created programs
and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact IBM Canada Ltd., Department 071,
1150 Eglinton Avenue East, North York, Ontario M3C 1H7, Canada. Such informa-
tion may be available, subject to appropriate terms and conditions, including in
some cases payment of a fee.

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 you create programs using RPG IV source. This
publication documents general-use programming interfaces and associated guid-
ance information provided by the ILE RPG for AS/400 compiler.

General-use programming interfaces allow you to write programs that request or

receive services of the ILE RPG for AS/400 compiler.

Trademarks and Service Marks

The following terms are trademarks of the International Business Machines Corpo-
ration in the United States or other countries or both:

| 400 IBMLink
| AFP Integrated Language Environment
| AS/400 Operating System/400
| C/400 OS/400
| COBOL/400 PROFS
| DB2 RPG/400
| FORTRAN/400 System/36
| GDDM System/38
| IBM VisualAge

| Windows is a registered trademark of Microsoft Corporation.

 Copyright IBM Corp. 1998 xix

| UNIX is a registered trademark in the United States and other countries licensed
| exclusively through X/Open Company Limited.

| Registered trademarks and unregistered trademarks are denoted by  and 

| respectively.

xx ILE RPG for AS/400 Programmer's Guide

 About This Guide
| This guide provides information that shows how to use the ILE RPG for AS/400
| compiler (ILE RPG) in the Integrated Language Environment. ILE RPG is an
| implementation of the RPG IV language on the AS/400 system with the Operating
| System/400 (OS/400) operating system. Use this guide to create and run ILE
| applications from RPG IV source.

This guide shows how to:

¹ Enter RPG IV source statements
¹ Create modules
¹ Bind modules
¹ Run an ILE program
¹ Call other objects
¹ Debug an ILE program
¹ Handle exceptions
¹ Define and process files
¹ Access devices
¹ Convert programs from an RPG III format to RPG IV format
¹ Read compiler listings

For information about other AS/400 publications, see either of the following:
¹ The Publications Reference, in the AS/400 Softcopy Library.
¹ The AS/400 Information Directory a unique, multimedia interface to a
searchable database containing descriptions of titles available from IBM or from
selected other publishers. The AS/400 Information Directory is shipped with
your system at no charge.

For a list of related publications, see the “Bibliography” on page 437.

Who Should Use This Guide

This guide is for programmers who are familiar with the RPG programming lan-
guage, but who want to learn how to use it in the ILE framework. This guide is also
for programmers who want to convert programs from the RPG III to the RPG IV
format. It is designed to guide you in the use of the ILE RPG compiler on the
AS/400 system.

Though this guide shows how to use the RPG IV in an ILE framework, it does not
provide detailed information on RPG IV specifications and operations. For a
detailed description of the language, see the ILE RPG for AS/400 Reference,
SC09-2508 .

Before using this guide, you should:

¹ Know how to use applicable AS/400 menus and displays, or Control Language
(CL) commands.

 Copyright IBM Corp. 1998 xxi

 ¹ Have the appropriate authority to the CL commands and objects described
here.
¹ Have a firm understanding of ILE as described in detail in the ILE Concepts,
SC41-5606.

| What's New This Release?

| The major enhancements to RPG IV since V3R7 are the support for variable-length
| fields, several enhancements relating to indicators, and the ability to specify
| compile options on the control specifications. These further improve the RPG
| product for integration with the OS/400 operating system and ILE interlanguage
| communication.

| The following list describes these enhancements:

| ¹ Support for variable-length fields
| This enhancement provides full support for variable-length character and
| graphic fields. Using variable-length fields can simplify many string handling
| tasks.
| ¹ Ability to use your own data structure for INDARA indicators
| Users can now access logical data areas and associate an indicator data struc-
| ture with each WORKSTN and PRINTER file that uses INDARA, instead of
| using the *IN array for communicating values to data management.
| ¹ Ability to use built-in functions instead of result indicators
| Built-in functions %EOF, %EQUAL, %FOUND, and %OPEN have been added
| to query the results of input/output operations. Built-in functions %ERROR and
| %STATUS, and the operation code extender 'E' have been added for error han-
| dling.
| ¹ Compile options on the control specification
| Compile options, specified through the CRTBNDRPG and CRTRPGMOD com-
| mands, can now be specified through the control specification keywords. These
| compile options will be used on every compile of the program.

| In addition, the following new function has been added:

| ¹ Support for import and export of procedures and variables with mixed case
| names
| ¹ Ability to dynamically set the DECEDIT value at runtime
| ¹ Built-in functions %CHAR and %REPLACE have been added to make string
| manipulation easier
| ¹ New support for externally defined *CMDY, *CDMY, and *LONGJUL date data
| formats
| ¹ An extended range for century date formats
| ¹ Ability to define indicator variables
| ¹ Ability to specify the current data structure name as the parameter for the
| OVERLAY keyword
| ¹ New status code 115 has been added to indicate variable-length field errors

xxii ILE RPG for AS/400 Programmer's Guide

| ¹ Support for application profiling
| ¹ Ability to handle packed-decimal data that is not valid when it is retrieved from
| files using FIXNBR(*INPUTPACKED)
| ¹ Ability to specify the BNDDIR command parameter on the CRTRPGMOD
| command.

| Changes to this Guide Since V3R7

| This V4R2 guide, ILE RPG for AS/400 Programming Guide, SC09-2507-00, differs
| in many places from the V3R7 guide, ILE RPG/400 Programming Guide,
| SC09-2074-01. Most of the changes are related to the enhancements that have
| been made since V3R7; others reflect minor technical corrections. To assist you in
| using this manual, technical changes and enhancements are noted with a vertical
| bar (|).

About This Guide xxiii

xxiv ILE RPG for AS/400 Programmer's Guide
 ILE RPG Introduction
Before using ILE RPG to create a program, you must know certain aspects of the
environment in which you will be using it. This part provides information on the fol-
lowing topics that you should know:
¹ Overview of RPG IV language
¹ Role of ILE components in RPG programming
¹ ILE program creation strategies
¹ Overview of coding a module with more than one procedure and prototyped
calls

 Copyright IBM Corp. 1998 1

2 ILE RPG for AS/400 Programmer's Guide
Chapter 1. Overview of the RPG IV Programming Language
This chapter presents a high-level review of the features of the RPG IV program-
ming language that distinguish RPG from other programming languages. You
should be familiar and comfortable with all of these features before you program in
the RPG IV language. The features discussed here encompass the following
subjects:
¹ Coding specifications
¹ The program cycle
¹ Indicators
¹ Operation codes

For more information on RPG IV, see the ILE RPG for AS/400 Reference.

RPG IV Specifications