IBM AS-400 User Manual

AS/400e ÉÂÔ

ILE RPG for AS/400 Programmer's Guide

Version 4

SC09-2507-02

AS/400e ÉÂÔ

ILE RPG for AS/400 Programmer's Guide

Version 4

SC09-2507-02

Note!

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

Third Edition (May 1999)

This edition applies to Version 4, Release 4, Modification 0, of IBM Application System/400 Integrated Language Environment RPG for AS/400 (Program 5769-RG1) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition applies only to reduced instruction set computer (RISC) systems.

This edition replaces SC09-2507-01. Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the

address that is given below. IBM welcomes your comments. You can send your comments to: IBM Canada Ltd. Laboratory

Information Development 2G/KB7/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 electronically to IBM. See “How to Send Your Comments” for a description of the methods.

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.

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.

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Programming Interface Information ......................... xii

Trademarks and Service Marks ........................... xii

About This Guide ................................... xv

Who Should Use This Guide ............................. xv

Prerequisite and Related Information ........................ xvi

How to Send Your Comments ............................ xvi

| What's New This Release? .............................. xvii

| Changes to this Guide Since V4R2 ........................ xxi

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 for AS/400 .................. 13

IBM VisualAge RPG and Cooperative Development Environment 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

| Multithreaded 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

 Copyright IBM Corp. 1994, 1999 iii

A Strategy to Avoid ................................... 31

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

iv ILE RPG for AS/400 Programmer's Guide

Changing the Optimization Level ......................... 87

Removing Observability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

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 ............. 104

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 ............. 119

Chapter 10. Calling Programs and Procedures ............... 127

Program/Procedure Call Overview ......................... 127

Calling Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Calling Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

The Call Stack ................................... 129

Recursive Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Parameter-Passing Considerations . . . . . . . . . . . . . . . . . . . . . . . 131

Using a Prototyped Call ............................... 133

Using the CALLP Operation ........................... 133

Calling within an Expression ........................... 134

Examples of Free-Form Call ........................... 135

Passing Prototyped Parameters .......................... 135

Parameter Passing Styles ............................ 135

Using Operational Descriptors .......................... 138

Omitting Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Checking for the Number of Passed Parameters ............... 141

Passing Less Data Than Required ....................... 145

Order of Evaluation ................................ 146

Interlanguage Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

| Interlanguage Calling Considerations ....................... 147

Contents v

Using the Fixed-Form Call Operations ....................... 148

Examples of CALL and CALLB ......................... 150

Passing Parameters Using PARM and PLIST ................. 150

Returning from a Called Program or Procedure ................. 152

Returning from a Main Procedure ........................ 152

Returning from a Subprocedure ......................... 154

Returning using ILE Bindable APIs ....................... 155

Using Bindable APIs ................................. 155

Examples of Using Bindable APIs ....................... 156

Calling a Graphics Routine ............................. 156

Calling Special Routines ............................... 157

| Multithreading Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

| How to Share Data Across More Than One Module ............. 158

| How to Avoid Deadlock Between Modules ................... 159

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 ......................... 170

STRDBG Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Setting Debug Options .............................. 171

Adding/Removing Programs from a Debug Session ............... 172

Example of Adding a Service Program to a Debug Session ........ 173

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 ........................ 177

Setting and Removing Unconditional Job Breakpoints ............ 178

Setting and Removing Unconditional Thread Breakpoints .......... 180

Setting and Removing Conditional Job Breakpoints ............. 181

National Language Sort Sequence (NLSS) .................. 183

Setting and Removing Job Breakpoints Using Statement Numbers .... 185

Setting and Removing Conditional Thread Breakpoints ........... 187

Removing All Job and Thread Breakpoints .................. 188

Setting and Removing Watch Conditions ..................... 188

Characteristics of Watches ............................ 189

Setting Watch Conditions ............................ 190

Displaying Active Watches ............................ 192

Removing Watch Conditions ........................... 192

Example of Setting a Watch Condition ...................... 193

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

vi ILE RPG for AS/400 Programmer's Guide

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

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 ............................ 226

Specifying Error Indicators or the 'E' Operation Code Extender ...... 227

Using an Error Subroutine ............................ 228

Specifying a Return Point in the ENDSR Operation ............. 237

ILE Condition Handlers ............................... 238

Using a Condition Handler ............................ 238

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

Contents vii

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

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

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

viii ILE RPG for AS/400 Programmer's Guide

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

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

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

Contents ix

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

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Description of the CRTRPGMOD command .................. 422

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

Reading a Compiler Listing ............................. 424

Prologue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Source Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

Additional Diagnostic Messages ......................... 431

Output Buffer Positions .............................. 432

/COPY Member Table .............................. 432

Compile-Time Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Key Field Information ............................... 434

Cross-Reference Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

External References List ............................. 435

Message Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Final Summary ................................... 436

Code Generation and Binding Errors ...................... 437

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

x ILE RPG for AS/400 Programmer's Guide

Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described 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:

IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNA-

TIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently 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

 Copyright IBM Corp. 1994, 1999 xi

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

This information contains examples of data and reports used in daily business operations. 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 Interface and Associated Guidance Information provided by the ILE RPG for AS/400 compiler.

General-Use programming interfaces allow the customer to write programs that obtain the services of the ILE RPG for AS/400 compiler.

Trademarks and Service Marks

The following terms are trademarks of the International Business Machines Corporation in the United States, or other countries, or both:

400 IBM AFP IBMLink Application System/400 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

Domino is a trademark of the Lotus Development Corporation in the United States, or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other countries.

VisualAge

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States and/or other countries.

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

Other company, product, and service names may be the trademarks or service marks of others.

xii ILE RPG for AS/400 Programmer's Guide

Registered trademarks and unregistered trademarks are denoted by  and  respectively.

Notices xiii

xiv 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

Who Should Use This Guide

This guide is for programmers who are familiar with the RPG programming language, 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 SC09-2508-02 .

Before using this guide, you should:

¹ Know how to use applicable AS/400 menus and displays, or Control Language

(CL) commands.

ILE RPG for AS/400 Reference

¹ Have the appropriate authority to the CL commands and objects described

here.

¹ Have a firm understanding of ILE as described in detail in the

SC41-5606-03.

 Copyright IBM Corp. 1994, 1999 xv

ILE Concepts

Prerequisite and Related Information

Use the AS/400 Information Center as your starting point for looking up AS/400 technical information. You can access the Information Center from the AS/400e Information Center CD-ROM (English version: SK3T-2027-01) or from one of these Web sites:

http://www.as400.ibm.com/infocenter http://publib.boulder.ibm.com/pubs/html/as400/infocenter.htm

The AS/400 Information Center contains important topics such as logical partitioning, clustering, Java, TCP/IP, Web serving, and secured networks. It also contains Internet links to Web sites such as the AS/400 Online Library and the AS/400 Technical Studio. Included in the Information Center is a link that describes at a high level the differences in information between the Information Center and the Online Library.

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

How to Send Your Comments

Your feedback is important in helping to provide the most accurate and high-quality information. IBM welcomes any comments about this book or any other AS/400 documentation.

¹ If you prefer to send comments by mail, use the the following address:

IBM Canada Ltd. Laboratory

Information Development

2G/KB7/1150/TOR

1150 Eglinton Avenue East

North York, Ontario, Canada M3C 1H7

If you are mailing a readers' comment form from a country other than the

United States, you can give the form to the local IBM branch office or IBM rep-

resentative for postage-paid mailing.

¹ If you prefer to send comments by FAX, use the following number:

– 1-416-448-6161

¹ If you prefer to send comments electronically, use one of these e-mail

addresses:

– Comments on books:

torrcf@ca.ibm.com IBMLink: toribm(torrcf)

– Comments on the AS/400 Information Center:

RCHINFOC@us.ibm.com

Be sure to include the following:

¹ The name of the book. ¹ The publication number of the book. ¹ The page number or topic to which your comment applies.

xvi ILE RPG for AS/400 Programmer's Guide

What's New This Release?

| | The major enhancements to RPG IV since V4R2 are the support for running ILE

| RPG modules safely in a threaded environment, the new 3-digit and 20-digit signed | and unsigned integer data types, and support for a new Universal Character Set | Version 2 (UCS-2) data type and for conversion between UCS-2 fields and graphic | or single-byte character fields.

| The following list describes these enhancements: | ¹ Support for calling ILE RPG procedures from a threaded application, such as

| Domino or Java. | – The new control specification keyword THREAD(*SERIALIZE) identifies

| modules that are enabled to run in a multithreaded environment. Access to | procedures in the module is serialized.

| ¹ Support for new 1-byte and 8-byte integer data types: 3I and 20I signed | integer, and 3U and 20U unsigned integer

| – These new integer data types provide you with a greater range of integer | values and can also improve performance of integer computations, taking | full advantage of the 64-bit AS/400 RISC processor.

| – The new 3U type allows you to more easily communicate with ILE C proce| dures that have single-byte character (char) return types and parameters | passed by value.

| – The new INTPREC control specification keyword allows you to specify | 20-digit precision for intermediate values of integer and unsigned binary | arithmetic operations in expressions.

| – Built-in functions %DIV and %REM have been added to support integer | division and remainder operations.

| ¹ Support for new Universal Character Set Version 2 (UCS-2) or Unicode data | type

| – The UCS-2 (Unicode) character set can encode the characters for many | written languages. The field is a character field whose characters are two | bytes long.

| – By adding support for Unicode, a single application can now be developed | for a multinational corporation, minimizing the necessity to perform code | page conversion. The use of Unicode permits the processing of characters | in multiple scripts without loss of integrity.

| – Support for conversions between UCS-2 fields and graphic or single-byte | character fields using the MOVE and MOVEL operations, and the new | %UCS2 and %GRAPH built-in functions.

| – Support for conversions between UCS-2 fields or graphic fields with dif| ferent Coded Character Set Identifiers (CCSIDs) using the EVAL, MOVE, | and MOVEL operations, and the new %UCS2 built-in function.

| Other enhancements have been made to this release as well. These include: | ¹ New parameters for the OPTION control specification keyword and on the

| create commands:

About This Guide xvii

| – *SRCSTMT allows you to assign statement numbers for debugging from | the source IDs and SEU sequence numbers in the compiler listing. (The | statement number is used to identify errors in the compiler listing by the | debugger, and to identify the statement where a run-time error occurs.) | *NOSRCSTMT specifies that statement numbers are associated with the | Line Numbers of the listing and the numbers are assigned sequentially.

| – Now you can choose not to generate breakpoints for input and output spec| ifications in the debug view with *NODEBUGIO. If this option is selected, a | STEP on a READ statement in the debugger will step to the next calcu| lation, rather than stepping through the input specifications.

| ¹ New special words for the INZ definition specification keyword: | – INZ(*EXTDFT) allows you to use the default values in the DDS for initial-

| izing externally described data structure subfields. | – Character variables initialized by INZ(*USER) are initialized to the name of

| the current user profile. | ¹ The new %XFOOT built-in function sums all elements of a specified array

| expression. | ¹ The new EVALR operation code evaluates expressions and assigns the result

| to a fixed-length character or graphic result. The assignment right-adjusts the | data within the result.

| ¹ The new FOR operation code performs an iterative loop and allows free-form | expressions for the initial, increment, and limit values.

| ¹ The new LEAVESR operation code can be used to exit from any point within a | subroutine.

| ¹ The new *NEXT parameter on the OVERLAY(name:*NEXT) keyword indicates | that a subfield overlays another subfield at the next available position.

| ¹ The ability to use hexadecimal literals with integer and unsigned integer fields | in initialization and free-form operations, such as EVAL, IF, etc.

| ¹ New control specification keyword OPENOPT{(*NOINZOFL | *INZOFL)} to indi| cate whether the overflow indicators should be reset to *OFF when a file is | opened.

| ¹ Ability to tolerate pointers in teraspace — a memory model that allows more | than 16 megabytes of contiguous storage in one allocation.

| The following tables summarize the changed and new language elements, based | on the part of the language affected.

xviii ILE RPG for AS/400 Programmer's Guide

Table 1. Changed Language Elements Since V4R2

| Language Unit| Element| Description | Control specifi-

| OPTION(*{NO}SRCSTMT)| *SRCSTMT allows you to request | cation keywords

| OPTION(*{NO}DEBUGIO)| *{NO}DEBUGIO, determines if break- | points are generated for input and | output specifications.

| Definition spec-

| INZ(*EXTDFT)| All externally described data struc- | ification

| ture subfields can now be intialized | keywords

| to the default values specified in the | DDS.

| INZ(*USER)| Any character field or subfield can | be initialized to the name of the | current user profile.

| Definition spec-

| 3 and 20 digits allowed for

| Added to the list of allowed values | ification posi-

| I and U data types

| for internal data types to support | tions 33-39 (To

| 1-byte and 8-byte integer and | Position/Length)

| unsigned data. | Command

| OPTION| *NOSRCSTMT, *SRCSTMT, | parameter

| *NODEBUGIO, and *DEBUGIO have | been added to the OPTION param- | eter on the CRTBNDRPG and | CRTRPGMOD commands.

About This Guide xix

| Control specifi-

| CCSID(*GRAPH:

| Sets the default graphic CCSID for | cation keywords

| *IGNORE | *SRC |

| the module. This setting is used for | number)

| literals, compile-time data and

Table 2 (Page 1 of 2). New Language Elements Since V4R2

Language Unit Element Description

| program-described input and output | fields and definitions. The default is | *IGNORE.

| OPENOPT{(*NO | *YES)}| Indicates whether the overflow indi- | cators should be reset to *OFF when | a file is opened.

| Definition spec-

| CCSID(number | *DFT)| Sets the graphic and UCS-2 CCSID | ification

| for the definition. | keywords

| %GRAPH(char-expr |

| Converts to graphic data from single- | graph-expr | UCS2-expr {:

| byte character, graphic, or UCS-2 | ccsid})

| data. | %REM(n:m)| Performs the integer remainder oper-

| ation on two operands n and m; the | result is the remainder of n/m. The | operands must be numeric values | with zero decimal positions.

| %UCS2(char-expr | graph-

| Converts to UCS-2 data from single- | expr | UCS2-expr {: ccsid})

| byte character, graphic, or UCS-2 | data.

| %XFOOT(array-expr)| Produces the sum of all the ele- | ments in the specified array | expression.

xx ILE RPG for AS/400 Programmer's Guide

Table 2 (Page 2 of 2). New Language Elements Since V4R2

| of the form result=expression. The | result will be right-justified.

| ENDFOR| ENDFOR ends a group of operations | started by a FOR operation.

| LEAVESR| Used to exit from anywhere within a | subroutine.

| Changes to this Guide Since V4R2

| This V4R4 guide, | in many places from the V4R2 guide,

ILE RPG for AS/400 Programmer's Guide

, SC09-2507-02, differs

, | SC09-2507-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 xxi

xxii 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 following topics that you should know:

¹ Overview of RPG IV language ¹ Role of Integrated Language Environment components in RPG programming ¹ Integrated Language Environment program creation strategies ¹ Overview of coding a module with more than one procedure and prototyped

calls

2 ILE RPG for AS/400 Programmer's Guide

RPG IV Overview

Chapter 1. Overview of the RPG IV Programming Language

This chapter presents a high-level review of the features of the RPG IV programming 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

RPG IV Specifications

RPG code is written on a variety of specification forms, each with a specific set of functions. Many of the entries which make up a specification type are positiondependent. Each entry must start in a specific position depending on the type of entry and the type of specification.

There are seven types of RPG IV specifications. Each specification type is optional. Specifications must be entered into your source program in the order shown below.

Main source section:

1. Control specifications provide the compiler with information about generating and running programs, such as the program name, date format, and use of alternate collating sequence or file translation.

2. File description specifications describe all the files that your program uses.

3. Definition specifications describe the data used by the program.

4. Input specifications describe the input records and fields used by the program.

5. Calculation specifications describe the calculations done on the data and the order of the calculations. Calculation specifications also control certain input and output operations.

ILE RPG for AS/400 Reference

6. Output specifications describe the output records and fields used by the program.

Subprocedure section:

1. Procedure specifications mark the beginning and end of the subprocedure, indicate the subprocedure name, and whether it is exported.

2. Definition specifications describe the local data used by the subprocedure.

3. Calculation specifications describe the calculations done on both the global and local data and the order of the calculations.

Cycle Programming

When a system processes data, it must do the processing in a particular order. This logical order is provided by:

¹ The ILE RPG compiler ¹ The program code

The logic the compiler supplies is called the program cycle. When you let the compiler provide the logic for your programs, it is called cycle programming.

The program cycle is a series of steps that your program repeats until an end-of-file condition is reached. Depending on the specifications you code, the program may or may not use each step in the cycle.

If you want to have files controlled by the cycle, the information that you code on RPG specifications in your source program need not specify when records for these files are read. The compiler supplies the logical order for these operations, and some output operations, when your source program is compiled.

RPG IV Overview

Start

If you do not want to have files controlled by the cycle, you must end your program some other way, either by creating an end-of-file condition by setting on the last record (LR) indicator, by creating a return condition by setting on the return (RT) indicator, or by returning directly using the RETURN operation.

Note: No cycle code is generated for subprocedures or when NOMAIN is speci-

fied on the control specification.

Figure 1 shows the specific steps in the general flow of the RPG program cycle.

Perform

detail

calculations

Write

heading and

detail lines

Move fields

Get input

record

LR on

Yes

Perform

total

calculations

Write

total

output

End of

program

Figure 1. RPG Program Logic Cycle

.1/ RPG processes all heading and detail lines (H or D in position 17 of the

output specifications).

4 ILE RPG for AS/400 Programmer's Guide

RPG IV Overview

.2/ RPG reads the next record and sets on the record identifying and

control level indicators.

.3/ RPG processes total calculations (conditioned by control level indicators

L1 through L9, an LR indicator, or an L0 entry).

.4/ RPG processes all total output lines (identified by a T in position 17 of

the output specifications).

.5/ RPG determines if the LR indicator is on. If it is on, the program ends. .6/ The fields of the selected input records move from the record to a proc-

essing area. RPG sets on field indicators.

.7/ RPG processes all detail calculations (not conditioned by control level

indicators in positions 7 and 8 of the calculation specifications). It uses the data from the record at the beginning of the cycle.

The first cycle

The first and last time through the program cycle differ somewhat from other cycles. Before reading the first record the first time through the cycle, the program does three things:

¹ handles input parameters, opens files, initializes program data ¹ writes the records conditioned by the 1P (first page) indicator ¹ processes all heading and detail output operations.

For example, heading lines printed before reading the first record might consist of constant or page heading information, or special fields such as PAGE and *DATE. The program also bypasses total calculations and total output steps on the first cycle.

The last cycle

The last time a program goes through the cycle, when no more records are available, the program sets the LR (last record) indicator and the L1 through L9 (control level) indicators to output, then all files are closed, and then the program ends.

Subprocedure logic

The general flow of a subprocedure is much simpler: the calculations of a subprocedure are done once, and then the subprocedure returns. There is no cycle code generated for a subprocedure.

. The program processes the total calculations and total

Indicators

An indicator is a one-byte character field that is either set on ('1') or off ('0'). It is generally used to indicate the result of an operation or to condition (control) the processing of an operation. Indicators are like switches in the flow of the program logic. They determine the path the program will take during processing, depending on how they are set or used.

Indicators can be defined as variables on the definition specifications. You can also use RPG IV indicators, which are defined either by an entry on a specification or by the RPG IV program itself.

Chapter 1. Overview of the RPG IV Programming Language 5

Each RPG IV indicator has a two-character name (for example, LR, 01, H3), and is referred to in some entries of some specifications just by the two-character name, and in others by the special name *INxx where xx is the two-character name. You can use several types of these indicators; each type signals something different. The positions on the specification in which you define an indicator determine the use of the indicator. Once you define an indicator in your program, it can limit or control calculation and output operations.

Indicator variables can be used any place an indicator of the form *INxx may be used with the exception of the OFLIND and EXTIND keywords on the file description specifications.

An RPG program sets and resets certain indicators at specific times during the program cycle. In addition, the state of indicators can be changed explicitly in calculation operations.

Operation Codes

The RPG IV programming language allows you to do many different types of operations on your data. Operation codes, entered on the calculation specifications, indicate what operations will be done. For example, if you want to read a new record, you could use the READ operation code. The following is a list of the types of operations available.

Arithmetic operations Indicator-setting operations Array operations Information operations Bit operations Initialization operations Branching operations Memory Management Operations Call operations Message operation Compare operations Move operations Data-Area operations String operations Date/Time/Timestamp operations Structured programming operations Declarative operations Subroutine operations File operations Test operations

Example of an ILE RPG Program

This section illustrates a simple ILE RPG program that performs payroll calculations.

Problem Statement

The payroll department of a small company wants to create a print output that lists employees' pay for that week. Assume there are two disk files, EMPLOYEE and TRANSACT, on the system.

The first file, EMPLOYEE, contains employee records. The figure below shows the format of an employee record:

EMP_REC

EMP_NUMBER

1 6 22 27

6 ILE RPG for AS/400 Programmer's Guide

EMP_NAME EMP_RATE

+ 459 hidden pages

IBM AS-400 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Notices

Programming Interface Information

Trademarks and Service Marks

About This Guide

Who Should Use This Guide

Prerequisite and Related Information

How to Send Your Comments

What's New This Release?

ILE RPG Introduction

Chapter 1. Overview of the RPG IV Programming Language

RPG IV Specifications

Cycle Programming

Indicators

Operation Codes

Example of an ILE RPG Program