ILE-RPG v7.1 Ref

IBM iVersion 7.1

ProgrammingIBM Rational Development Studio for iILE RPG Reference

NoteBefore using this information and the product it supports, read the information in Notices on page A-1.

This edition applies to IBM Rational Development Studio for i (product number 5770-WDS) and to all subsequentreleases and modifications until otherwise indicated in new editions. This version does not run on all reducedinstruction set computer (RISC) models nor does it run on CISC models.

This document may contain references to Licensed Internal Code. Licensed Internal Code is Machine Code and islicensed to you under the terms of the IBM License Agreement for Machine Code.

Copyright IBM Corporation 1994, 2014.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsILE RPG Reference

About ILE RPG Reference . . . . . . 1-1Who Should Use This Reference . . . . . . . 1-1Prerequisite and Related Information . . . . . 1-1How to Send Your Comments . . . . . . . . 1-1

What's New . . . . . . . . . . . . 2-1What's New since 7.1? . . . . . . . . . . 2-1What's New in 7.1? . . . . . . . . . . . 2-7What's New in 6.1? . . . . . . . . . . . 2-10What's New in V5R4? . . . . . . . . . . 2-14What's New in V5R3? . . . . . . . . . . 2-18What's New in V5R2? . . . . . . . . . . 2-22What's New in V5R1? . . . . . . . . . . 2-24What's New in V4R4? . . . . . . . . . . 2-29What's New in V4R2? . . . . . . . . . . 2-32What's New in V3R7? . . . . . . . . . . 2-36What's New in V3R6/V3R2? . . . . . . . . 2-39

RPG IV Concepts . . . . . . . . . . 3-1Symbolic Names and Reserved Words . . . . . 3-1

Symbolic Names . . . . . . . . . . . 3-1Array Names . . . . . . . . . . . 3-2Conditional Compile Names . . . . . . 3-2Data Structure Names . . . . . . . . 3-2EXCEPT Names . . . . . . . . . . 3-2Field Names . . . . . . . . . . . . 3-2KLIST Names . . . . . . . . . . . 3-2Labels . . . . . . . . . . . . . . 3-2Named Constants . . . . . . . . . . 3-2PLIST Names . . . . . . . . . . . 3-2Prototype Names . . . . . . . . . . 3-3Record Names . . . . . . . . . . . 3-3Subroutine Names . . . . . . . . . . 3-3Table Names . . . . . . . . . . . . 3-3

RPG IV Words with Special Functions/ReservedWords . . . . . . . . . . . . . . . 3-3User Date Special Words. . . . . . . . . 3-5

Rules for User Date . . . . . . . . . 3-5PAGE, PAGE1-PAGE7. . . . . . . . . . 3-6

Rules for PAGE, PAGE1-PAGE7 . . . . . 3-7Compiler Directives . . . . . . . . . . . 3-7

/FREE... /END-FREE . . . . . . . . . . 3-8/TITLE . . . . . . . . . . . . . . 3-8/EJECT . . . . . . . . . . . . . . 3-8/SPACE . . . . . . . . . . . . . . 3-8/COPY or /INCLUDE . . . . . . . . . 3-9

Results of the /COPY or /INCLUDE duringCompile . . . . . . . . . . . . . 3-10Nested /COPY or /INCLUDE . . . . . 3-10Using /COPY, /INCLUDE in Source Fileswith Embedded SQL. . . . . . . . . 3-11

Conditional Compilation Directives . . . . . 3-11

Defining Conditions . . . . . . . . . 3-11/DEFINE . . . . . . . . . . . 3-11/UNDEFINE . . . . . . . . . . 3-11

Predefined Conditions . . . . . . . . 3-12Conditions Relating to the Environment 3-12Conditions Relating to the CommandBeing Used . . . . . . . . . . . 3-12Conditions Relating to the Target Release 3-12

Condition Expressions . . . . . . . . 3-13Testing Conditions . . . . . . . . . 3-13

/IF Condition-Expression . . . . . . 3-13/ELSEIF Condition-Expression . . . . 3-13/ELSE . . . . . . . . . . . . 3-14/ENDIF . . . . . . . . . . . . 3-14Rules for Testing Conditions . . . . . 3-14

The /EOF Directive . . . . . . . . . 3-14/EOF . . . . . . . . . . . . . 3-14

Handling of Directives by the RPGPreprocessor . . . . . . . . . . . 3-15

Procedures and the Program Logic Cycle . . . . 3-16Subprocedure Definition . . . . . . . . 3-17

Procedure Interface Definition . . . . . 3-18Return Values . . . . . . . . . . . 3-19Scope of Definitions . . . . . . . . . 3-19Subprocedures and Subroutines . . . . . 3-20

Program Flow in RPG Modules: Cycle VersusLinear . . . . . . . . . . . . . . 3-21

Cycle Module . . . . . . . . . . . 3-22Use Caution Exporting Subprocedures inCycle Modules. . . . . . . . . . 3-23

Linear Module. . . . . . . . . . . 3-24Linear Main Module. . . . . . . . 3-24NOMAIN Module . . . . . . . . 3-24

Module Initialization . . . . . . . . 3-25Initialization of Global Data . . . . . 3-25

RPG Cycle and other implicit Logic. . . . . 3-25Program Cycle. . . . . . . . . . . 3-25

General RPG IV Program Cycle . . . . 3-26Detailed RPG IV Program Cycle . . . . 3-27

Subprocedure Calculations. . . . . . . 3-37Implicit Opening of Files and Locking ofData Areas . . . . . . . . . . . . 3-39Implicit Closing of Files and Unlocking ofData Areas . . . . . . . . . . . . 3-40

RPG IV Indicators . . . . . . . . . . . 3-40Indicators Defined on RPG IV Specifications 3-40

Overflow Indicators . . . . . . . . . 3-41Record Identifying Indicators . . . . . . 3-41

Rules for Assigning Record IdentifyingIndicators . . . . . . . . . . . 3-41

Control Level Indicators (L1-L9) . . . . . 3-42Rules for Control Level Indicators . . . 3-43Split Control Field . . . . . . . . 3-48

Field Indicators . . . . . . . . . . 3-50Rules for Assigning Field Indicators . . 3-51

Resulting Indicators . . . . . . . . . 3-51

Copyright IBM Corp. 1994, 2014 iii

||##

Rules for Assigning Resulting Indicators 3-52Indicators Not Defined on the RPG IVSpecifications . . . . . . . . . . . . 3-52

External Indicators . . . . . . . . . 3-53Internal Indicators . . . . . . . . . 3-53

First Page Indicator (1P) . . . . . . 3-53Last Record Indicator (LR) . . . . . . 3-53Matching Record Indicator (MR). . . . 3-54

Return Indicator (RT) . . . . . . . . 3-54Using Indicators . . . . . . . . . . . 3-54

File Conditioning . . . . . . . . . . 3-54Rules for File Conditioning . . . . . 3-55

Field Record Relation Indicators . . . . . 3-55Assigning Field Record RelationIndicators . . . . . . . . . . . 3-55

Function Key Indicators . . . . . . . 3-57Halt Indicators (H1-H9). . . . . . . . 3-58Indicators Conditioning Calculations . . . 3-58

Positions 7 and 8 . . . . . . . . . 3-58Positions 9-11 . . . . . . . . . . 3-58

Indicators Used in Expressions . . . . . 3-61Indicators Conditioning Output . . . . . 3-61

Indicators Referred to As Data . . . . . . 3-64*IN . . . . . . . . . . . . . . 3-64*INxx . . . . . . . . . . . . . . 3-64Additional Rules . . . . . . . . . . 3-65

Summary of Indicators . . . . . . . . . 3-65File and Program Exception/Errors . . . . . . 3-67

File Exception/Errors . . . . . . . . . 3-68File Information Data Structure . . . . . 3-68

File Feedback Information . . . . . . 3-69Open Feedback Information . . . . . 3-72Input/Output Feedback Information . . 3-73Device Specific Feedback Information 3-74Get Attributes Feedback Information . . 3-77Blocking Considerations . . . . . . 3-79File Status Codes . . . . . . . . . 3-80

File Exception/Error Subroutine (INFSR) 3-82Program Exception/Errors . . . . . . . . 3-84

Program Status Data Structure . . . . . 3-85Program Status Codes . . . . . . . 3-89PSDS Example . . . . . . . . . . 3-91

Program Exception/Error Subroutine . . . 3-93General File Considerations . . . . . . . . 3-93

Rules for File Names . . . . . . . . . 3-94File devices . . . . . . . . . . . . . 3-94

File device types . . . . . . . . . . 3-94Global and Local Files . . . . . . . . . 3-95Open Access Files . . . . . . . . . . 3-95

Locating an Open Access Handler . . . . 3-95Open Access Handlers . . . . . . . . 3-95

Example of an Open Access Handler . . 3-97File Parameters . . . . . . . . . . . 3-105Variables Associated with Files . . . . . . 3-105

Example of passing a file and passing adata structure with the associated variables. 3-106

Full Procedural Files . . . . . . . . . 3-108Primary/Secondary Multi-file Processing 3-108

Multi-file Processing with No Match Fields 3-108Multi-file Processing with Match Fields 3-108

Assigning Match Field Values (M1-M9) 3-109

Processing Matching Records . . . . 3-113File Translation . . . . . . . . . . . 3-116

Specifying File Translation . . . . . . 3-117Translating One File or All Files . . . . 3-117Translating More Than One File . . . . 3-118

Specifying the Files . . . . . . . . 3-118Specifying the Table . . . . . . . 3-118

Definitions . . . . . . . . . . . . . 4-1Defining Data and Prototypes . . . . . . . . 4-1

General Considerations . . . . . . . . . 4-1Scope of Definitions . . . . . . . . . 4-2Storage of Definitions . . . . . . . . . 4-3

Standalone Fields . . . . . . . . . . . 4-3Variable Initialization . . . . . . . . . 4-3

Constants . . . . . . . . . . . . . . 4-4Literals . . . . . . . . . . . . . 4-4

Example of Defining Literals . . . . . 4-7Example of Using Literals with ZeroLength . . . . . . . . . . . . . 4-8

Named Constants . . . . . . . . . . 4-8Figurative Constants . . . . . . . . . 4-9

Rules for Figurative Constants . . . . 4-10Data Structures . . . . . . . . . . . 4-10

Qualifying Data Structure Names . . . . 4-11Array Data Structures . . . . . . . . 4-12Defining Data Structure Parameters in aPrototype or Procedure Interface. . . . . 4-13Defining Data Structure Subfields . . . . 4-13

Specifying Subfield Length . . . . . 4-14Aligning Data Structure Subfields . . . 4-14Initialization of Nested Data Structures 4-15

Special Data Structures . . . . . . . . 4-15Data Area Data Structure . . . . . . 4-15File Information Data Structure . . . . 4-16Program-Status Data Structure . . . . 4-16Indicator Data Structure . . . . . . 4-16

Data Structure Examples . . . . . . . 4-16Prototypes and Parameters . . . . . . . 4-27

Prototypes . . . . . . . . . . . . 4-27Prototyped Parameters . . . . . . . . 4-28Procedure Interface . . . . . . . . . 4-30

Using Arrays and Tables . . . . . . . . . 4-31Arrays . . . . . . . . . . . . . . 4-32

Array Name and Index . . . . . . . . 4-32The Essential Array Specifications . . . . 4-32Coding a Run-Time Array . . . . . . . 4-32Loading a Run-Time Array . . . . . . 4-33

Loading a Run-Time Array by ReadingOne Record from a File . . . . . . . 4-33Loading a Run-Time Array by ReadingSeveral Records from A File . . . . . 4-34Loading an Array from IdenticalExternally-Described Fields . . . . . 4-34Sequencing Run-Time Arrays . . . . . 4-35

Coding a Compile-Time Array . . . . . 4-36Loading a Compile-Time Array . . . . . 4-36

Rules for Array Source Records . . . . 4-36Coding a Prerun-Time Array . . . . . . 4-37Example of Coding Arrays. . . . . . . 4-38Loading a Prerun-Time Array. . . . . . 4-38

iv IBM i: ILE RPG Reference

||||||||||||

||

Sequence Checking for Character Arrays 4-38Initializing Arrays . . . . . . . . . . 4-39

Run-Time Arrays . . . . . . . . . . 4-39Compile-Time and Prerun-Time Arrays . . 4-39

Defining Related Arrays . . . . . . . . 4-39Searching Arrays . . . . . . . . . . . 4-41

Searching an Array Without an Index . . . 4-41Searching an Array Data Structure . . . . 4-42Searching an Array with an Index . . . . 4-42

Using Arrays . . . . . . . . . . . . 4-43Specifying an Array in Calculations. . . . 4-43

Sorting Arrays . . . . . . . . . . . . 4-44Sorting using part of the array as a key . . 4-44Sorting an Array Data Structure . . . . . 4-45

Array Output . . . . . . . . . . . . 4-45Editing Entire Arrays . . . . . . . . 4-45

Using Dynamically-Sized Arrays. . . . . . 4-45Tables . . . . . . . . . . . . . . 4-46

LOOKUP with One Table . . . . . . . 4-47LOOKUP with Two Tables . . . . . . . 4-47Specifying the Table Element Found in aLOOKUP Operation . . . . . . . . . 4-48

Data Types and Data Formats . . . . . . . 4-48Internal and External Formats . . . . . . 4-49

Internal Format . . . . . . . . . . 4-49External Format . . . . . . . . . . 4-49

Specifying an External Format for aNumeric Field . . . . . . . . . . 4-50Specifying an External Format for aCharacter, Graphic, or UCS-2 Field . . . 4-50Specifying an External Format for aDate-Time Field . . . . . . . . . 4-51

Character Data Type . . . . . . . . . . 4-51Character Format . . . . . . . . . . 4-51Indicator Format . . . . . . . . . . 4-52Graphic Format . . . . . . . . . . 4-52UCS-2 Format . . . . . . . . . . . 4-53Variable-Length Character, Graphic andUCS-2 Formats . . . . . . . . . . 4-54

Size of the Length-Prefix for a VaryingLength Item . . . . . . . . . . 4-55Rules for Variable-Length Character,Graphic, and UCS-2 Formats . . . . . 4-55Using Variable-Length Fields . . . . . 4-57CVTOPT(*VARCHAR) andCVTOPT(*VARGRAPHIC) . . . . . . 4-59

Conversion between Character, Graphic andUCS-2 Data . . . . . . . . . . . . 4-62

CCSIDs of Data . . . . . . . . . 4-62Conversions . . . . . . . . . . 4-63

Alternate Collating Sequence . . . . . . 4-63Changing the Collating Sequence . . . 4-63Using an External Collating Sequence 4-63Specifying an Alternate CollatingSequence in Your Source . . . . . . 4-64Formatting the Alternate CollatingSequence Records. . . . . . . . . 4-64

Numeric Data Type . . . . . . . . . . 4-65Binary-Decimal Format . . . . . . . . 4-65

Processing of a Program-DescribedBinary Input Field . . . . . . . . 4-65

Processing of an Externally DescribedBinary Input Field . . . . . . . . 4-66

Float Format . . . . . . . . . . . 4-66External Display Representation of aFloating-Point Field . . . . . . . . 4-67

Integer Format. . . . . . . . . . . 4-67Packed-Decimal Format. . . . . . . . 4-68

Determining the Digit Length of aPacked-Decimal Field . . . . . . . 4-68

Unsigned Format . . . . . . . . . . 4-69Zoned-Decimal Format . . . . . . . . 4-70Considerations for Using Numeric Formats 4-70

Guidelines for Choosing the NumericFormat for a Field . . . . . . . . 4-71

Representation of Numeric Formats . . . 4-71Date Data Type . . . . . . . . . . . 4-73

Separators . . . . . . . . . . . . 4-75Initialization . . . . . . . . . . . 4-75

Time Data Type . . . . . . . . . . . 4-75Separators . . . . . . . . . . . . 4-76Initialization . . . . . . . . . . . 4-76*JOBRUN . . . . . . . . . . . . 4-77

Timestamp Data Type . . . . . . . . . 4-77Separators . . . . . . . . . . . . 4-77Initialization . . . . . . . . . . . 4-77

Object Data Type . . . . . . . . . . . 4-77Where You Can Specify an Object Field . . 4-78

Basing Pointer Data Type . . . . . . . . 4-79Setting a Basing Pointer . . . . . . . 4-80Examples . . . . . . . . . . . . 4-81

Procedure Pointer Data Type . . . . . . . 4-85Database Null Value Support . . . . . . . 4-86

User Controlled Support for Null-CapableFields and Key Fields . . . . . . . . 4-87

Null-capable fields inexternally-described data structures. . . 4-87Input of Null-Capable Fields . . . . . 4-88Output of Null-Capable Fields . . . . 4-88Keyed Operations . . . . . . . . 4-89

Input-Only Support for Null-Capable Fields 4-92ALWNULL(*NO) . . . . . . . . . . 4-92

Error Handling for Database Data MappingErrors. . . . . . . . . . . . . . . 4-92

Editing Numeric Fields . . . . . . . . . . 4-92Edit Codes . . . . . . . . . . . . . 4-93

Simple Edit Codes . . . . . . . . . 4-93Combination Edit Codes . . . . . . . 4-93User-Defined Edit Codes . . . . . . . 4-95Editing Considerations . . . . . . . . 4-95Summary of Edit Codes . . . . . . . 4-95

Edit Words . . . . . . . . . . . . . 4-98How to Code an Edit Word . . . . . . 4-99Parts of an Edit Word . . . . . . . . 4-99

Forming the Body of an Edit Word 4-100Forming the Status of an Edit Word 4-102Formatting the Expansion of an EditWord . . . . . . . . . . . . 4-103

Summary of Coding Rules for Edit Words 4-103Editing Externally Described Files . . . . . 4-103

Contents v

##

##

Specifications . . . . . . . . . . . 5-1About Specifications . . . . . . . . . . . 5-1

RPG IV Specification Types . . . . . . . . 5-1Main Source Section Specifications . . . . 5-2Subprocedure Specifications . . . . . . 5-3Program Data . . . . . . . . . . . 5-3

Free-Form Statements . . . . . . . . . . 5-3Conditional Directives Within a Free-FormStatement . . . . . . . . . . . . . 5-4Differences between fixed-form and free-formto be aware of . . . . . . . . . . . 5-4

Common Entries . . . . . . . . . . . 5-6Syntax of Keywords . . . . . . . . . 5-6Continuation Rules . . . . . . . . . 5-7

Control Specification Keyword Field . . . 5-9File Description Specification KeywordField . . . . . . . . . . . . . 5-9Definition Specification Keyword Field . . 5-9Calculation Specification ExtendedFactor-2 . . . . . . . . . . . . 5-10Free-Form Specification . . . . . . . 5-10Output Specification Constant/EditwordField . . . . . . . . . . . . . 5-11Definition and Procedure SpecificationName Field . . . . . . . . . . . 5-11

Control Specifications . . . . . . . . . . 5-12Using a Data Area as a Control Specification 5-13Free-Form Control Statement . . . . . . . 5-14Traditional Control-Specification Statement . . 5-15

Position 6 (Form Type) . . . . . . . . 5-15Positions 7-80 (Keywords) . . . . . . . 5-15

Control-Specification Keywords . . . . . . 5-15ALLOC(*STGMDL | *TERASPACE |*SNGLVL) . . . . . . . . . . . . 5-16ACTGRP(*STGMDL | *NEW | *CALLER |'activation-group-name') . . . . . . . 5-16ALTSEQ{(*NONE | *SRC | *EXT)} . . . . 5-17ALWNULL(*NO | *INPUTONLY |*USRCTL) . . . . . . . . . . . . 5-17AUT(*LIBRCRTAUT | *ALL | *CHANGE |*USE | *EXCLUDE | 'authorization-list-name') . . . . . . . . . . . . . 5-18BNDDIR('binding-directory-name'{:'binding-directory-name'...}) . . . . . . 5-18CCSID(*GRAPH : parameter | *UCS2 :number | *CHAR : *JOBRUN) . . . . . 5-19CCSIDCVT(*EXCP | *LIST) . . . . . . 5-19COPYNEST(number) . . . . . . . . 5-21COPYRIGHT('copyright string') . . . . . 5-21CURSYM('sym') . . . . . . . . . . 5-21CVTOPT(*{NO}DATETIME *{NO}GRAPHIC*{NO}VARCHAR *{NO}VARGRAPHIC) . . 5-22DATEDIT(fmt{separator}) . . . . . . . 5-23DATFMT(fmt{separator}) . . . . . . . 5-23DEBUG{(*INPUT | *DUMP | *XMLSAX |*NO | *YES)} . . . . . . . . . . . 5-23DECEDIT(*JOBRUN | 'value') . . . . . 5-24DECPREC(30|31|63) . . . . . . . . 5-24DFTACTGRP(*YES | *NO) . . . . . . 5-25DFTNAME(rpg_name) . . . . . . . . 5-26ENBPFRCOL(*PEP | *ENTRYEXIT | *FULL) 5-26

EXPROPTS(*MAXDIGITS | *RESDECPOS) 5-26EXTBININT{(*NO | *YES)} . . . . . . 5-26FIXNBR(*{NO}ZONED*{NO}INPUTPACKED) . . . . . . . . 5-27FLTDIV{(*NO | *YES)} . . . . . . . . 5-27FORMSALIGN{(*NO | *YES)} . . . . . 5-27FTRANS{(*NONE | *SRC)} . . . . . . 5-28GENLVL(number) . . . . . . . . . 5-28INDENT(*NONE | 'character-value') . . . 5-28INTPREC(10 | 20) . . . . . . . . . 5-28LANGID(*JOBRUN | *JOB |'language-identifier') . . . . . . . . . 5-28MAIN(main_procedure_name) . . . . . 5-29NOMAIN . . . . . . . . . . . . 5-30OPENOPT (*NOINZOFL | *INZOFL) . . . 5-31OPTIMIZE(*NONE | *BASIC | *FULL) . . 5-31OPTION(*{NO}XREF *{NO}GEN*{NO}SECLVL *{NO}SHOWCPY*{NO}EXPDDS *{NO}EXT *{NO}SHOWSKP)*{NO}SRCSTMT) *{NO}DEBUGIO)*{NO}UNREF . . . . . . . . . . . 5-31PGMINFO(*PCML | *NO { : *MODULE } ) 5-32

Examples . . . . . . . . . . . 5-33PRFDTA(*NOCOL | *COL) . . . . . . 5-33SRTSEQ(*HEX | *JOB | *JOBRUN |*LANGIDUNQ | *LANGIDSHR |'sort-table-name') . . . . . . . . . . 5-33STGMDL(*INHERIT | *SNGLVL |*TERASPACE) . . . . . . . . . . . 5-33TEXT(*SRCMBRTXT | *BLANK |'description') . . . . . . . . . . . 5-34THREAD(*CONCURRENT | *SERIALIZE) 5-34

THREAD(*CONCURRENT) . . . . . 5-35THREAD(*SERIALIZE) . . . . . . . 5-35General thread considerations . . . . 5-35

TIMFMT(fmt{separator}) . . . . . . . 5-35TRUNCNBR(*YES | *NO) . . . . . . . 5-36USRPRF(*USER | *OWNER) . . . . . . 5-36VALIDATE(*NODATETIME) . . . . . . 5-36

File Description Specifications . . . . . . . 5-37Free-Form File Definition Statement . . . . 5-38

Equivalent Free-form Coding for Fixed-FormFile Entries . . . . . . . . . . . . 5-39Device-type Keywords . . . . . . . . 5-39Defining the File Usage in Free-Form . . . 5-39

Traditional File Description SpecificationStatement . . . . . . . . . . . . . 5-40

File-Description Keyword Continuation Line 5-40Position 6 (Form Type) . . . . . . . . 5-41Positions 7-16 (File Name) . . . . . . . 5-41

Program-Described File . . . . . . . 5-41Externally-Described File . . . . . . 5-41

Position 17 (File Type) . . . . . . . . 5-42Input Files . . . . . . . . . . . 5-42Output Files . . . . . . . . . . 5-42Update Files . . . . . . . . . . 5-42Combined Files . . . . . . . . . 5-42

Position 18 (File Designation) . . . . . . 5-42Primary File . . . . . . . . . . 5-42Secondary File . . . . . . . . . . 5-43Record Address File (RAF). . . . . . 5-43

vi IBM i: ILE RPG Reference

||||||||

||

###

||

###

|||||||||||

Array or Table File . . . . . . . . 5-43Full Procedural File . . . . . . . . 5-43

Position 19 (End of File) . . . . . . . 5-43Position 20 (File Addition) . . . . . . . 5-44Position 21 (Sequence) . . . . . . . . 5-44Position 22 (File Format) . . . . . . . 5-45Positions 23-27 (Record Length) . . . . . 5-45Position 28 (Limits Processing) . . . . . 5-46Positions 29-33 (Length of Key or RecordAddress). . . . . . . . . . . . . 5-46Position 34 (Record Address Type) . . . . 5-47

Blank=Non-keyed Processing . . . . . 5-47A=Character Keys . . . . . . . . 5-47P=Packed Keys . . . . . . . . . 5-48G=Graphic Keys . . . . . . . . . 5-48K=Key . . . . . . . . . . . . 5-48D=Date Keys . . . . . . . . . . 5-48T=Time Keys . . . . . . . . . . 5-48Z=Timestamp Keys . . . . . . . . 5-48F=Float Keys . . . . . . . . . . 5-48

Position 35 (File Organization) . . . . . 5-48Blank=Non-keyed Program-DescribedFile . . . . . . . . . . . . . 5-49I=Indexed File . . . . . . . . . . 5-49T=Record Address File . . . . . . . 5-49

Positions 36-42 (Device). . . . . . . . 5-49File device types . . . . . . . . . 5-49

Position 43 (Reserved) . . . . . . . . 5-50Positions 44-80 (Keywords) . . . . . . 5-50

File-Description Keywords. . . . . . . . 5-50ALIAS . . . . . . . . . . . . . 5-50BLOCK(*YES |*NO) . . . . . . . . . 5-51COMMIT{(rpg_name)} . . . . . . . . 5-52DATFMT(format{separator}) . . . . . . 5-52DEVID(fieldname) . . . . . . . . . 5-52DISK{(*EXT | record-length)} . . . . . . 5-53EXTDESC(external-filename) . . . . . . 5-53EXTFILE(filename | *EXTDESC). . . . . 5-54EXTIND(*INUx) . . . . . . . . . . 5-55EXTMBR(membername) . . . . . . . 5-56FORMLEN(number) . . . . . . . . . 5-56FORMOFL(number) . . . . . . . . . 5-56HANDLER(program-or-procedure { :communication-area)}) . . . . . . . . 5-56IGNORE(recformat{:recformat...}) . . . . 5-58INCLUDE(recformat{:recformat...}) . . . . 5-58INDDS(data_structure_name) . . . . . . 5-59INFDS(DSname) . . . . . . . . . . 5-59INFSR(SUBRname) . . . . . . . . . 5-59KEYED{(*CHAR : key-length)} . . . . . 5-59KEYLOC(number) . . . . . . . . . 5-60LIKEFILE(parent-filename) . . . . . . 5-60

Rules for the LIKEFILE keyword: . . . 5-60MAXDEV(*ONLY | *FILE) . . . . . . 5-63OFLIND(indicator) . . . . . . . . . 5-64PASS(*NOIND) . . . . . . . . . . 5-64PGMNAME(program_name) . . . . . . 5-64PLIST(Plist_name) . . . . . . . . . 5-64PREFIX(prefix{:nbr_of_char_replaced}) . . . 5-65PRINTER{(*EXT | record-length)} . . . . 5-66PRTCTL(data_struct{:*COMPAT}) . . . . 5-67

Extended Length PRTCTL Data Structure 5-67*COMPAT PRTCTL Data Structure . . . 5-67

QUALIFIED . . . . . . . . . . . 5-67Rules for the QUALIFIED keyword: . . 5-68

RAFDATA(filename) . . . . . . . . . 5-68RECNO(fieldname) . . . . . . . . . 5-68RENAME(Ext_format:Int_format) . . . . 5-69SAVEDS(DSname) . . . . . . . . . 5-69SAVEIND(number) . . . . . . . . . 5-69SEQ{(*EXT | record-length)} . . . . . . 5-69SFILE(recformat:rrnfield) . . . . . . . 5-70SLN(number) . . . . . . . . . . . 5-70SPECIAL{(*EXT | record-length)} . . . . 5-70STATIC . . . . . . . . . . . . . 5-71

Rules for the STATIC keyword: . . . . 5-71TEMPLATE. . . . . . . . . . . . 5-71

Rules for the TEMPLATE keyword: . . . 5-72TIMFMT(format{separator}) . . . . . . 5-72USAGE(*INPUT *OUTPUT *UPDATE*DELETE) . . . . . . . . . . . . 5-72USROPN . . . . . . . . . . . . 5-72WORKSTN{(*EXT | record-length)}. . . . 5-73

File Types and Processing Methods . . . . . 5-73Definition Specifications . . . . . . . . . 5-74

Free-Form Definition Statement . . . . . . 5-74Data-type Keywords . . . . . . . . . 5-76Keyword differences between fixed formand free form definitions . . . . . . . 5-77Free-Form Named Constant Definition. . . 5-77Free-Form Standalone Field Definition . . . 5-78

Equivalent Free-form Coding forStandalone Field Entries . . . . . . 5-78

Free-Form Data Structure Definition . . . 5-78Equivalent Free-form Coding for DataStructure Entries . . . . . . . . . 5-81

Free-Form Subfield Definition . . . . . 5-82Equivalent Free-form Coding for SubfieldEntries . . . . . . . . . . . . 5-82

Free-Form Prototype Definition . . . . . 5-83Equivalent Free-form Coding forPrototype Entries . . . . . . . . . 5-84

Free-Form Procedure Interface Definition 5-84Equivalent Free-form Coding forProcedure Interface Entries . . . . . 5-86

Free-Form Parameter Definition . . . . . 5-86Equivalent Free-form Coding forParameter Entries. . . . . . . . . 5-86

Traditional Definition Specification Statement 5-86Definition Specification KeywordContinuation Line . . . . . . . . . 5-87Definition Specification Continued NameLine . . . . . . . . . . . . . . 5-87Position 6 (Form Type) . . . . . . . . 5-87Positions 7-21 (Name) . . . . . . . . 5-88Position 22 (External Description) . . . . 5-88Position 23 (Type of Data Structure) . . . 5-89Positions 24-25 (Definition Type). . . . . 5-89Positions 26-32 (From Position) . . . . . 5-90Positions 33-39 (To Position / Length) . . . 5-90Position 40 (Internal Data Type) . . . . . 5-91Positions 41-42 (Decimal Positions) . . . . 5-92

Contents vii

||

##

||

|||

||

||

||

||

|||||

|||||||||||||||||||||||||||||||||||||||

Position 43 (Reserved) . . . . . . . . 5-92Positions 44-80 (Keywords) . . . . . . 5-92

Definition-Specification Keywords . . . . . 5-92ALIAS . . . . . . . . . . . . . 5-93ALIGN . . . . . . . . . . . . . 5-94ALT(array_name) . . . . . . . . . . 5-94ALTSEQ(*NONE) . . . . . . . . . . 5-95ASCEND . . . . . . . . . . . . 5-95BASED(basing_pointer_name) . . . . . 5-95BINDEC(digits {: decimal-positions}) . . . 5-96CCSID(number | *DFT) . . . . . . . 5-96CHAR(length) . . . . . . . . . . . 5-96CLASS(*JAVA:class-name) . . . . . . . 5-97CONST{(constant)} . . . . . . . . . 5-97CTDATA . . . . . . . . . . . . 5-98DATE{(format{separator})} . . . . . . . 5-98DATFMT(format{separator}) . . . . . . 5-98DESCEND . . . . . . . . . . . . 5-98DIM(numeric_constant) . . . . . . . . 5-99DTAARA keyword . . . . . . . . . 5-99

Free-form DTAARA keyword for a fieldor subfield. . . . . . . . . . . 5-100Free-form DTAARA keyword for a datastructure . . . . . . . . . . . 5-101Fixed-form DTAARA keyword . . . . 5-102

EXPORT{(external_name)} . . . . . . 5-102EXT . . . . . . . . . . . . . . 5-103EXTFLD{(field_name)} . . . . . . . . 5-103EXTFMT(code) . . . . . . . . . . 5-104EXTNAME(file-name{:format-name}{:*ALL|*INPUT|*OUTPUT|*KEY}) . . . . . . 5-105EXTPGM{(name)} . . . . . . . . . 5-106EXTPROC({*CL|*CWIDEN|*CNOWIDEN|{*JAVA:class-name:}}name) . . . . . . 5-106

Specifying *DCLCASE as the ExternalName . . . . . . . . . . . . 5-111

FLOAT(bytes). . . . . . . . . . . 5-111FROMFILE(file_name) . . . . . . . . 5-112GRAPH(length) . . . . . . . . . . 5-112IMPORT{(external_name)} . . . . . . 5-112INT(digits). . . . . . . . . . . . 5-113IND . . . . . . . . . . . . . . 5-113INZ{(initial value)} . . . . . . . . . 5-114LEN(length) . . . . . . . . . . . 5-115

Rules for the LEN keyword: . . . . . 5-115LIKE(name {: length-adjustment}) . . . . 5-116

LIKE(object-name) . . . . . . . . 5-117LIKEDS(data_structure_name) . . . . . 5-117LIKEFILE(filename). . . . . . . . . 5-119

Rules for the LIKEFILE keyword forprototyped parameters: . . . . . . 5-119

LIKEREC(intrecname{:*ALL|*INPUT|*OUTPUT|*KEY}) . . . . . . . . . . . . 5-120NOOPT . . . . . . . . . . . . 5-121OBJECT{(*JAVA:class-name)}. . . . . . 5-122OCCURS(numeric_constant) . . . . . . 5-122OPDESC . . . . . . . . . . . . 5-123OPTIONS(*NOPASS *OMIT *VARSIZE*STRING *TRIM *RIGHTADJ *NULLIND) . 5-123OVERLAY(name{:start_pos | *NEXT}) 5-134PACKED(digits {: decimal-positions}) . . . 5-136

PACKEVEN . . . . . . . . . . . 5-136PERRCD(numeric_constant) . . . . . . 5-137POINTER{(*PROC)} . . . . . . . . 5-137POS(starting-position) . . . . . . . . 5-137PREFIX(prefix{:nbr_of_char_replaced}) 5-138PROCPTR . . . . . . . . . . . . 5-139PSDS . . . . . . . . . . . . . 5-139QUALIFIED . . . . . . . . . . . 5-139RTNPARM . . . . . . . . . . . 5-139STATIC{(*ALLTHREAD)} . . . . . . . 5-143

Additional Considerations forSTATIC(*ALLTHREAD) . . . . . . 5-144

TEMPLATE . . . . . . . . . . . 5-144Rules for the TEMPLATE keyword forDefinition specifications: . . . . . . 5-144

TIME{(format{separator})} . . . . . . 5-145TIMESTAMP . . . . . . . . . . . 5-145TIMFMT(format{separator}) . . . . . . 5-145TOFILE(file_name) . . . . . . . . . 5-146UCS2(length) . . . . . . . . . . . 5-146UNS(digits) . . . . . . . . . . . 5-146VALUE . . . . . . . . . . . . . 5-147VARCHAR(length {:2 | 4}) . . . . . . 5-147VARGRAPH(length {:2 | 4}) . . . . . . 5-147VARUCS2(length {:2 | 4}). . . . . . . 5-148VARYING{(2 | 4)} . . . . . . . . . 5-148ZONED(digits {: decimal-positions}) . . . 5-149

Summary According to DefinitionSpecification Type . . . . . . . . . . 5-149

Input Specifications. . . . . . . . . . . 5-153Input Specification Statement . . . . . . 5-154

Program Described . . . . . . . . . 5-154Externally Described . . . . . . . . 5-154

Program Described Files . . . . . . . . 5-154Position 6 (Form Type) . . . . . . . 5-154

Record Identification Entries. . . . . . . 5-154Positions 7-16 (File Name) . . . . . . 5-155Positions 16-18 (Logical Relationship). . . 5-155Positions 17-18 (Sequence) . . . . . . 5-155

Alphabetic Entries . . . . . . . . 5-155Numeric Entries . . . . . . . . . 5-155

Position 19 (Number) . . . . . . . . 5-156Position 20 (Option) . . . . . . . . 5-156Positions 21-22 (Record IdentifyingIndicator, or **) . . . . . . . . . . 5-156

Indicators . . . . . . . . . . . 5-156Lookahead Fields . . . . . . . . 5-157

Positions 23-46 (Record IdentificationCodes) . . . . . . . . . . . . . 5-157

Positions 23-27, 31-35, and 39-43(Position) . . . . . . . . . . . 5-158Positions 28, 36, and 44 (Not) . . . . 5-158Positions 29, 37, and 45 (Code Part) 5-158Positions 30, 38, and 46 (Character) 5-159AND Relationship . . . . . . . . 5-159OR Relationship . . . . . . . . . 5-159

Field Description Entries . . . . . . . . 5-159Position 6 (Form Type) . . . . . . . 5-159Positions 7-30 (Reserved) . . . . . . . 5-159Positions 31-34 (Data Attributes) . . . . 5-159Position 35 (Date/Time Separator) . . . . 5-160

viii IBM i: ILE RPG Reference

##

||||

||

||||||

||

|||||||||||

||

||

||||

||##

||||

||||||||||||

Position 36 (Data Format). . . . . . . 5-160Positions 37-46 (Field Location) . . . . . 5-160Positions 47-48 (Decimal Positions) . . . 5-161Positions 49-62 (Field Name) . . . . . 5-161Positions 63-64 (Control Level) . . . . . 5-162Positions 65-66 (Matching Fields) . . . . 5-162Positions 67-68 (Field Record Relation) 5-163Positions 69-74 (Field Indicators) . . . . 5-163

Externally Described Files . . . . . . . 5-164Position 6 (Form Type) . . . . . . . 5-164

Record Identification Entries. . . . . . . 5-164Positions 7-16 (Record Name) . . . . . 5-164Positions 17-20 (Reserved) . . . . . . 5-164Positions 21-22 (Record IdentifyingIndicator) . . . . . . . . . . . . 5-164Positions 23-80 (Reserved) . . . . . . 5-164

Field Description Entries . . . . . . . . 5-164Positions 7-20 (Reserved) . . . . . . . 5-165Positions 21-30 (External Field Name) . . 5-165Positions 31-48 (Reserved) . . . . . . 5-165Positions 49-62 (Field Name) . . . . . 5-165Positions 63-64 (Control Level) . . . . . 5-165Positions 65-66 (Matching Fields) . . . . 5-165Positions 67-68 (Reserved) . . . . . . 5-165Positions 69-74 (Field Indicators) . . . . 5-166Positions 75-80 (Reserved) . . . . . . 5-166

Calculation Specifications. . . . . . . . . 5-166Traditional Syntax . . . . . . . . . . 5-167

Calculation Specification Extended Factor-2Continuation Line . . . . . . . . . 5-167Position 6 (Form Type) . . . . . . . 5-167Positions 7-8 (Control Level). . . . . . 5-167

Control Level Indicators . . . . . . 5-168Last Record Indicator . . . . . . . 5-168Subroutine Identifier . . . . . . . 5-168AND/OR Lines Identifier . . . . . 5-168

Positions 9-11 (Indicators) . . . . . . 5-169Positions 12-25 (Factor 1) . . . . . . . 5-169Positions 26-35 (Operation and Extender) 5-169

Operation Extender. . . . . . . . 5-169Positions 36-49 (Factor 2) . . . . . . . 5-170Positions 50-63 (Result Field) . . . . . 5-170Positions 64-68 (Field Length) . . . . . 5-171Positions 69-70 (Decimal Positions) . . . 5-171Positions 71-76 (Resulting Indicators) . . . 5-171

Extended Factor 2 Syntax. . . . . . . . 5-172Positions 7-8 (Control Level). . . . . . 5-172Positions 9-11 (Indicators) . . . . . . 5-172Positions 12-25 (Factor 1) . . . . . . . 5-172Positions 26-35 (Operation and Extender) 5-172

Operation Extender. . . . . . . . 5-172Positions 36-80 (Extended Factor 2) . . . 5-173

Free-Form Calculation Statement . . . . . 5-173Positions 8-80 (Free-form Operations). . . 5-175

Output Specifications . . . . . . . . . . 5-175Output Specification Statement . . . . . . 5-175

Program Described . . . . . . . . . 5-175Externally Described . . . . . . . . 5-176

Program Described Files . . . . . . . . 5-176Position 6 (Form Type) . . . . . . . 5-176

Record Identification and Control Entries 5-176

Positions 7-16 (File Name) . . . . . . 5-176Positions 16-18 ( Logical Relationship) 5-176Position 17 (Type) . . . . . . . . . 5-177Positions 18-20 (Record Addition/Deletion) 5-177Position 18 (Fetch Overflow/Release) . . . 5-178

Fetch Overflow . . . . . . . . . 5-178Release . . . . . . . . . . . . 5-179

Positions 21-29 (Output ConditioningIndicators) . . . . . . . . . . . . 5-179Positions 30-39 (EXCEPT Name) . . . . 5-180Positions 40-51 (Space and Skip) . . . . 5-180Positions 40-42 (Space Before) . . . . . 5-181Positions 43-45 (Space After). . . . . . 5-181Positions 46-48 (Skip Before). . . . . . 5-181Positions 49-51 (Skip After) . . . . . . 5-181

Field Description and Control Entries. . . . 5-181Positions 21-29 (Output Indicators) . . . 5-181Positions 30-43 (Field Name) . . . . . 5-181

Field Names, Blanks, Tables and Arrays 5-182PAGE, PAGE1-PAGE7 . . . . . . . 5-182*PLACE . . . . . . . . . . . 5-182User Date Reserved Words . . . . . 5-182*IN, *INxx, *IN(xx) . . . . . . . . 5-182

Position 44 (Edit Codes) . . . . . . . 5-182Position 45 (Blank After) . . . . . . . 5-183Positions 47-51 (End Position) . . . . . 5-183Position 52 (Data Format). . . . . . . 5-184Positions 53-80 (Constant, Edit Word, DataAttributes, Format Name) . . . . . . 5-185

Constants . . . . . . . . . . . 5-185Edit Words . . . . . . . . . . 5-186Data Attributes . . . . . . . . . 5-186Record Format Name . . . . . . . 5-186

Externally Described Files . . . . . . . 5-186Position 6 (Form Type) . . . . . . . 5-186

Record Identification and Control Entries 5-186Positions 7-16 (Record Name) . . . . . 5-186Positions 16-18 ( Logical Relationship) 5-186Position 17 (Type) . . . . . . . . . 5-187Position 18 (Release) . . . . . . . . 5-187Positions 18-20 (Record Addition) . . . . 5-187Positions 21-29 (Output Indicators) . . . 5-187Positions 30-39 (EXCEPT Name) . . . . 5-187

Field Description and Control Entries. . . . 5-187Positions 21-29 (Output Indicators) . . . 5-187Positions 30-43 (Field Name) . . . . . 5-187Position 45 (Blank After) . . . . . . . 5-188

Procedure Specifications . . . . . . . . . 5-188Free-Form Procedure Statement. . . . . . 5-189Traditional Procedure Specification Statement 5-190

Procedure Specification KeywordContinuation Line . . . . . . . . . 5-190Procedure Specification Continued NameLine . . . . . . . . . . . . . . 5-190Position 6 (Form Type) . . . . . . . 5-191Positions 7-21 (Name) . . . . . . . . 5-191Position 24 (Begin/End Procedure) . . . 5-191Positions 44-80 (Keywords) . . . . . . 5-192

Procedure-Specification Keywords . . . . . 5-192EXPORT . . . . . . . . . . . . 5-192SERIALIZE . . . . . . . . . . . 5-192

Contents ix

||

Operations, Expressions, andFunctions . . . . . . . . . . . . . 6-1Operations . . . . . . . . . . . . . . 6-1

Operation Codes . . . . . . . . . . . 6-1Built-in Functions . . . . . . . . . . . 6-8Arithmetic Operations . . . . . . . . . 6-13

Ensuring Accuracy . . . . . . . . . 6-14Performance Considerations . . . . . . 6-15Integer and Unsigned Arithmetic . . . . 6-15Arithmetic Operations Examples. . . . . 6-16

Array Operations . . . . . . . . . . . 6-17Bit Operations . . . . . . . . . . . . 6-17Branching Operations . . . . . . . . . 6-18Call Operations . . . . . . . . . . . 6-19

Prototyped Calls . . . . . . . . . . 6-20Operational Descriptors. . . . . . . . 6-21Parsing Program Names on a Call . . . . 6-21

Program CALL Example . . . . . . 6-22Parsing System Built-In Names . . . . . 6-22Value of *ROUTINE . . . . . . . . . 6-23

Compare Operations. . . . . . . . . . 6-23Conversion Operations . . . . . . . . . 6-24Data-Area Operations . . . . . . . . . 6-25Date Operations . . . . . . . . . . . 6-26

Unexpected Results . . . . . . . . . 6-28Declarative Operations . . . . . . . . . 6-29Error-Handling Operations . . . . . . . 6-29File Operations . . . . . . . . . . . 6-30

Keys for File Operations . . . . . . . 6-32Indicator-Setting Operations . . . . . . . 6-33Information Operations . . . . . . . . . 6-33Initialization Operations . . . . . . . . 6-33Memory Management Operations . . . . . 6-34Message Operation . . . . . . . . . . 6-36Move Operations . . . . . . . . . . . 6-36

Moving Character, Graphic, UCS-2, andNumeric Data . . . . . . . . . . . 6-37Moving Date-Time Data . . . . . . . 6-38

Examples of Converting a Character Fieldto a Date Field. . . . . . . . . . 6-39

Move Zone Operations . . . . . . . . . 6-41Result Operations. . . . . . . . . . . 6-42Size Operations . . . . . . . . . . . 6-42String Operations . . . . . . . . . . . 6-42Structured Programming Operations . . . . 6-44Subroutine Operations . . . . . . . . . 6-46

Coding Subroutines . . . . . . . . . 6-47Subroutine Coding Examples . . . . . 6-48

Test Operations . . . . . . . . . . . 6-48XML Operations . . . . . . . . . . . 6-49

Expressions . . . . . . . . . . . . . . 6-49General Expression Rules . . . . . . . . 6-51Expression Operands . . . . . . . . . 6-52Expression Operators . . . . . . . . . 6-52Operation Precedence . . . . . . . . . 6-53Data Types . . . . . . . . . . . . . 6-54

Data Types Supported by ExpressionOperands . . . . . . . . . . . . 6-54Format of Numeric Intermediate Results 6-58

For the operators +, -, and *: . . . . . 6-58For the / operator: . . . . . . . . 6-58

For the ** operator: . . . . . . . . 6-58Precision Rules for Numeric Operations . . . 6-58

Using the Default Precision Rules . . . . 6-59Precision of Intermediate Results . . . . 6-60Example of Default Precision Rules . . . . 6-60Using the "Result Decimal Position"Precision Rules . . . . . . . . . . 6-62Example of "Result Decimal Position"Precision Rules . . . . . . . . . . 6-62

Short Circuit Evaluation . . . . . . . . 6-63Order of Evaluation . . . . . . . . . . 6-64

Built-in Functions. . . . . . . . . . . . 6-64%ABS (Absolute Value of Expression) . . . . 6-64%ADDR (Get Address of Variable) . . . . . 6-65%ALLOC (Allocate Storage) . . . . . . . 6-67%BITAND (Bitwise AND Operation) . . . . 6-67%BITNOT (Invert Bits) . . . . . . . . . 6-68%BITOR (Bitwise OR Operation). . . . . . 6-68%BITXOR (Bitwise Exclusive-OR Operation) 6-69

Examples of Bit Operations . . . . . . 6-70%CHAR (Convert to Character Data) . . . . 6-72%CHECK (Check Characters) . . . . . . . 6-73%CHECKR (Check Reverse) . . . . . . . 6-75%DATE (Convert to Date) . . . . . . . . 6-76%DAYS (Number of Days). . . . . . . . 6-77%DEC (Convert to Packed Decimal Format) 6-77

Numeric or character expression. . . . . 6-77Date, time or timestamp expression. . . . 6-77

%DECH (Convert to Packed Decimal Formatwith Half Adjust) . . . . . . . . . . . 6-78

%DECH Examples . . . . . . . . . 6-79%DECPOS (Get Number of Decimal Positions) 6-79%DIFF (Difference Between Two Date, Time, orTimestamp Values) . . . . . . . . . . 6-80%DIV (Return Integer Portion of Quotient) . . 6-82%EDITC (Edit Value Using an Editcode) . . . 6-82%EDITFLT (Convert to Float ExternalRepresentation) . . . . . . . . . . . 6-84%EDITW (Edit Value Using an Editword) . . 6-85%ELEM (Get Number of Elements) . . . . . 6-85%EOF (Return End or Beginning of FileCondition) . . . . . . . . . . . . . 6-86%EQUAL (Return Exact Match Condition) . . 6-87%ERROR (Return Error Condition) . . . . . 6-89%FIELDS (Fields to update) . . . . . . . 6-89%FLOAT (Convert to Floating Format) . . . 6-90%FOUND (Return Found Condition) . . . . 6-90%GRAPH (Convert to Graphic Value) . . . . 6-92%HANDLER (handlingProcedure :communicationArea ) . . . . . . . . . 6-93%HOURS (Number of Hours) . . . . . . 6-96%INT (Convert to Integer Format) . . . . . 6-97

%INTH (Convert to Integer Format withHalf Adjust) . . . . . . . . . . . 6-97

%KDS (Search Arguments in Data Structure) 6-98%LEN (Get or Set Length) . . . . . . . . 6-98

%LEN Used for its Value . . . . . . . 6-99%LEN Used to Set the Length ofVariable-Length Fields . . . . . . . . 6-100%LEN Used to Get the Maximum Lengthof Varying-Length Expressions . . . . . 6-100

x IBM i: ILE RPG Reference

###

%LOOKUPxx (Look Up an Array Element) 6-101Sequenced arrays that are not in the correctsequence . . . . . . . . . . . . 6-104

%MINUTES (Number of Minutes) . . . . . 6-104%MONTHS (Number of Months) . . . . . 6-104%MSECONDS (Number of Microseconds) 6-105%NULLIND (Query or Set Null Indicator) 6-105%OCCUR (Set/Get Occurrence of a DataStructure) . . . . . . . . . . . . . 6-106%OPEN (Return File Open Condition) . . . 6-106%PADDR (Get Procedure Address) . . . . 6-107

%PADDR Used with a Prototype . . . . 6-108%PARMS (Return Number of Parameters) 6-109%PARMNUM (Return Parameter Number) 6-111%REALLOC (Reallocate Storage) . . . . . 6-112%REM (Return Integer Remainder) . . . . 6-113%REPLACE (Replace Character String) . . . 6-114%SCAN (Scan for Characters) . . . . . . 6-115%SCANRPL (Scan and Replace Characters) 6-116%SECONDS (Number of Seconds) . . . . . 6-118%SHTDN (Shut Down) . . . . . . . . 6-118%SIZE (Get Size in Bytes). . . . . . . . 6-119%SQRT (Square Root of Expression) . . . . 6-120%STATUS (Return File or Program Status) 6-121%STR (Get or Store Null-Terminated String) 6-123

%STR Used to Get Null-Terminated String 6-124%STR Used to Store Null-Terminated String 6-125

%SUBARR (Set/Get Portion of an Array) 6-125%SUBDT (Extract a Portion of a Date, Time, orTimestamp) . . . . . . . . . . . . 6-128%SUBST (Get Substring) . . . . . . . . 6-129

%SUBST Used for its Value . . . . . . 6-129%SUBST Used as the Result of anAssignment . . . . . . . . . . . 6-130

%THIS (Return Class Instance for NativeMethod) . . . . . . . . . . . . . 6-130%TIME (Convert to Time) . . . . . . . 6-131%TIMESTAMP (Convert to Timestamp) . . . 6-132%TLOOKUPxx (Look Up a Table Element) 6-132%TRIM (Trim Characters at Edges) . . . . 6-133%TRIML (Trim Leading Characters) . . . . 6-134%TRIMR (Trim Trailing Characters) . . . . 6-135%UCS2 (Convert to UCS-2 Value) . . . . . 6-136%UNS (Convert to Unsigned Format) . . . 6-137

%UNSH (Convert to Unsigned Format withHalf Adjust) . . . . . . . . . . . 6-137

%XFOOT (Sum Array Expression Elements) 6-138%XLATE (Translate) . . . . . . . . . 6-138%XML (xmlDocument {:options}) . . . . . 6-139%YEARS (Number of Years) . . . . . . . 6-140

Operation Codes . . . . . . . . . . . 6-140ACQ (Acquire) . . . . . . . . . . . 6-140ADD (Add) . . . . . . . . . . . . 6-141ADDDUR (Add Duration) . . . . . . . 6-141ALLOC (Allocate Storage) . . . . . . . 6-143ANDxx (And) . . . . . . . . . . . 6-144BEGSR (Beginning of Subroutine) . . . . . 6-145BITOFF (Set Bits Off) . . . . . . . . . 6-145BITON (Set Bits On) . . . . . . . . . 6-146CABxx (Compare and Branch) . . . . . . 6-149CALL (Call a Program) . . . . . . . . 6-150

CALLB (Call a Bound Procedure) . . . . . 6-151CALLP (Call a Prototyped Procedure orProgram) . . . . . . . . . . . . . 6-152CASxx (Conditionally Invoke Subroutine) 6-156CAT (Concatenate Two Strings). . . . . . 6-157CHAIN (Random Retrieval from a File) . . . 6-159CHECK (Check Characters) . . . . . . . 6-162CHECKR (Check Reverse) . . . . . . . 6-164CLEAR (Clear) . . . . . . . . . . . 6-166

Clearing Variables . . . . . . . . . 6-167Clearing Record Formats . . . . . . . 6-167CLEAR Examples . . . . . . . . . 6-168

CLOSE (Close Files) . . . . . . . . . 6-170COMMIT (Commit) . . . . . . . . . 6-170COMP (Compare) . . . . . . . . . . 6-171DEALLOC (Free Storage) . . . . . . . . 6-172DEFINE (Field Definition) . . . . . . . 6-173

*LIKE DEFINE . . . . . . . . . . 6-174*DTAARA DEFINE . . . . . . . . . 6-175

DELETE (Delete Record) . . . . . . . . 6-176DIV (Divide) . . . . . . . . . . . . 6-177DO (Do) . . . . . . . . . . . . . 6-178DOU (Do Until) . . . . . . . . . . . 6-180DOUxx (Do Until) . . . . . . . . . . 6-180DOW (Do While) . . . . . . . . . . 6-182DOWxx (Do While). . . . . . . . . . 6-183DSPLY (Display Message) . . . . . . . 6-185DUMP (Program Dump) . . . . . . . . 6-187ELSE (Else) . . . . . . . . . . . . 6-188ELSEIF (Else If) . . . . . . . . . . . 6-189ENDyy (End a Structured Group) . . . . . 6-189ENDSR (End of Subroutine) . . . . . . . 6-190EVAL (Evaluate expression) . . . . . . . 6-191EVALR (Evaluate expression, right adjust) 6-193EVAL-CORR (Assign corresponding subfields) 6-194

Examples of the EVAL-CORR operation 6-197EXCEPT (Calculation Time Output) . . . . 6-200EXFMT (Write/Then Read Format) . . . . 6-201EXSR (Invoke Subroutine) . . . . . . . 6-203EXTRCT (Extract Date/Time/Timestamp) 6-203FEOD (Force End of Data) . . . . . . . 6-205FOR (For) . . . . . . . . . . . . . 6-206FORCE (Force a Certain File to Be Read NextCycle) . . . . . . . . . . . . . . 6-208GOTO (Go To) . . . . . . . . . . . 6-209IF (If) . . . . . . . . . . . . . . 6-210IFxx (If). . . . . . . . . . . . . . 6-211IN (Retrieve a Data Area). . . . . . . . 6-212ITER (Iterate) . . . . . . . . . . . . 6-214KFLD (Define Parts of a Key) . . . . . . 6-215KLIST (Define a Composite Key) . . . . . 6-216LEAVE (Leave a Do/For Group) . . . . . 6-218LEAVESR (Leave a Subroutine) . . . . . . 6-219LOOKUP (Look Up a Table or Array Element) 6-220MHHZO (Move High to High Zone) . . . . 6-223MHLZO (Move High to Low Zone) . . . . 6-223MLHZO (Move Low to High Zone) . . . . 6-224MLLZO (Move Low to Low Zone) . . . . 6-224MONITOR (Begin a Monitor Group) . . . . 6-224MOVE (Move) . . . . . . . . . . . 6-226MOVEA (Move Array). . . . . . . . . 6-239

Contents xi

##

##

Character, graphic, and UCS-2 MOVEAOperations . . . . . . . . . . . 6-240Numeric MOVEA Operations . . . . . 6-240General MOVEA Operations. . . . . . 6-240

MOVEL (Move Left) . . . . . . . . . 6-245MULT (Multiply) . . . . . . . . . . 6-254MVR (Move Remainder) . . . . . . . . 6-255NEXT (Next) . . . . . . . . . . . . 6-255OCCUR (Set/Get Occurrence of a DataStructure) . . . . . . . . . . . . . 6-256ON-ERROR (On Error) . . . . . . . . 6-260OPEN (Open File for Processing) . . . . . 6-261ORxx (Or) . . . . . . . . . . . . . 6-262OTHER (Otherwise Select) . . . . . . . 6-263OUT (Write a Data Area) . . . . . . . . 6-264PARM (Identify Parameters) . . . . . . . 6-265PLIST (Identify a Parameter List) . . . . . 6-267POST (Post) . . . . . . . . . . . . 6-268READ (Read a Record) . . . . . . . . 6-270READC (Read Next Changed Record) . . . 6-272READE (Read Equal Key) . . . . . . . 6-273READP (Read Prior Record) . . . . . . . 6-276READPE (Read Prior Equal) . . . . . . . 6-277REALLOC (Reallocate Storage with NewLength) . . . . . . . . . . . . . . 6-280REL (Release). . . . . . . . . . . . 6-281RESET (Reset) . . . . . . . . . . . 6-282

Resetting Variables . . . . . . . . . 6-282Resetting Record Formats. . . . . . . 6-283Additional Considerations . . . . . . 6-283RESET Examples . . . . . . . . . 6-284

RETURN (Return to Caller) . . . . . . . 6-288ROLBK (Roll Back) . . . . . . . . . . 6-291SCAN (Scan String). . . . . . . . . . 6-292SELECT (Begin a Select Group) . . . . . . 6-294SETGT (Set Greater Than) . . . . . . . 6-295SETLL (Set Lower Limit) . . . . . . . . 6-298SETOFF (Set Indicator Off) . . . . . . . 6-301SETON (Set Indicator On) . . . . . . . 6-302SHTDN (Shut Down) . . . . . . . . . 6-302SORTA (Sort an Array) . . . . . . . . 6-303SQRT (Square Root) . . . . . . . . . 6-307SUB (Subtract) . . . . . . . . . . . 6-308SUBDUR (Subtract Duration) . . . . . . 6-308

Subtract a duration . . . . . . . . . 6-309Calculate a duration . . . . . . . . 6-310Possible error situations . . . . . . . 6-310SUBDUR Examples . . . . . . . . . 6-311

SUBST (Substring) . . . . . . . . . . 6-311TAG (Tag) . . . . . . . . . . . . . 6-313TEST (Test Date/Time/Timestamp) . . . . 6-314TESTB (Test Bit) . . . . . . . . . . . 6-316TESTN (Test Numeric). . . . . . . . . 6-318TESTZ (Test Zone) . . . . . . . . . . 6-319

TIME (Retrieve Time and Date). . . . . . 6-320UNLOCK (Unlock a Data Area or Release aRecord) . . . . . . . . . . . . . . 6-321

Unlocking data areas . . . . . . . . 6-322Releasing record locks . . . . . . . . 6-322

UPDATE (Modify Existing Record) . . . . 6-323WHEN (When True Then Select) . . . . . 6-324WHENxx (When True Then Select) . . . . 6-325WRITE (Create New Records) . . . . . . 6-327XFOOT (Summing the Elements of an Array) 6-328XLATE (Translate) . . . . . . . . . . 6-329XML-INTO (Parse an XML Document into aVariable) . . . . . . . . . . . . . 6-330

%XML options for the XML-INTOoperation code . . . . . . . . . . 6-334

doc (default string) . . . . . . . . 6-334ccsid (default best) . . . . . . . . 6-335path . . . . . . . . . . . . . 6-336case (default lower) . . . . . . . . 6-338trim (default all) . . . . . . . . . 6-342allowmissing (default no) . . . . . . 6-343allowextra (default no) . . . . . . . 6-345datasubf . . . . . . . . . . . 6-348countprefix . . . . . . . . . . 6-350ns (default keep) . . . . . . . . . 6-353nsprefix . . . . . . . . . . . 6-354

Expected format of XML data . . . . . 6-355Rules for transferring XML data to RPGvariables . . . . . . . . . . . . 6-359Examples of the XML-INTO operation 6-361

XML-SAX (Parse an XML Document). . . . 6-363%XML options for the XML-SAX operationcode . . . . . . . . . . . . . . 6-364XML-SAX event-handling procedure . . . 6-365XML events . . . . . . . . . . . 6-366Examples of the XML-SAX operation . . . 6-372

Z-ADD (Zero and Add) . . . . . . . . 6-377Z-SUB (Zero and Subtract) . . . . . . . 6-378

Appendixes . . . . . . . . . . . . 7-1Appendix A. RPG IV Restrictions . . . . . . . 7-1Appendix B. EBCDIC Collating Sequence . . . . 7-2

Bibliography

Notices . . . . . . . . . . . . . . A-1Programming interface information . . . . . . A-3Trademarks . . . . . . . . . . . . . . A-3Terms and conditions . . . . . . . . . . A-3

Index . . . . . . . . . . . . . . . X-1

xii IBM i: ILE RPG Reference

####||||

ILE RPG ReferenceThis reference provides information about the RPG IV language as it is implemented using the ILE RPGcompiler with the IBM i operating system.

This reference covers:v Basics of RPG IV:

RPG IV character set RPG IV reserved words Compiler directives RPG IV program cycle Files Indicators Error Handling Subprocedures

v Definitions: Defining Data and Prototypes Data types and Data formats

v RPG IV specifications: Control File description Definition Input Calculation Output Procedure

v Ways to manipulate data or devices: Built-in Functions Expressions Operation Codes

Copyright IBM Corp. 1994, 2014

||

IBM i: ILE RPG Reference

About ILE RPG ReferenceRead this section for information about the reference.

Read this section for information about the reference.

Who Should Use This ReferenceThis reference is for programmers who are familiar with the RPG IV programming language.

This reference provides a detailed description of the RPG IV language. It does not provide information onhow to use the ILE RPG compiler or how to convert RPG III programs to ILE RPG. For information onthose subjects, see the IBM Rational Development Studio for i: ILE RPG Programmer's Guide, SC09-2507.

Before using this reference, you shouldv Know how to use applicable IBM i menus and displays or Control Language (CL) commands.v Have a firm understanding of Integrated Language Environment as described in detail in ILE

Concepts, SC41-5606.

Prerequisite and Related InformationUse the IBM i Information Center as your starting point for looking up IBM i technical information. Youcan access the Information Center from the following Web site:http://www.ibm.com/systems/i/infocenter/

The IBM i Information Center contains new and updated system information, such as softwareinstallation, Linux, WebSphere, Java, high availability, database, logical partitions, CL commands, andsystem application programming interfaces (APIs). In addition, it provides advisors and finders to assistin planning, troubleshooting, and configuring your system hardware and software.

For a list of related publications, see the Bibliography.

How to Send Your CommentsYour feedback is important in helping to provide the most accurate and high-quality information. IBMwelcomes any comments about this book or any other IBM i documentation.v If you prefer to send comments by mail, use the the following address:

IBM Canada Ltd. LaboratoryInformation Development8200 Warden AvenueMarkham, Ontario, Canada L6G 1C7

If you are mailing a readers' comment form from a country other than the United States, you can givethe form to the local IBM branch office or IBM representative for postage-paid mailing.

v If you prefer to send comments by fax , use 18454917727, attention: RCF Coordinator.v If you prefer to send comments electronically, use one of these e-mail addresses:

Comments on books:[email protected]

Comments on the IBM i Information Center:

Copyright IBM Corp. 1994, 2014 1-1

|||

|||||||

#

[email protected]

Be sure to include the following:v The name of the book.v The publication number of the book.v The page number or topic to which your comment applies.

1-2 IBM i: ILE RPG Reference

What's NewNew and changed features in each release of the ILE RPG compiler since V3R1

There have been several releases of RPG IV since the first V3R1 release. The following is a list ofenhancements made for each release since V3R1 to the current release:v What's New since 7.1?v What's New in 7.1? on page 2-7v What's New in 6.1? on page 2-10v What's New in V5R4? on page 2-14v What's New in V5R3? on page 2-18v What's New in V5R2? on page 2-22v What's New in V5R1? on page 2-24v What's New in V4R4? on page 2-29v What's New in V4R2? on page 2-32v What's New in V3R7? on page 2-36v What's New in V3R6/V3R2? on page 2-39

You can use this section to link to and learn about new RPG IV functions.

Note: The information for this product is up-to-date with the 7.1 release of RPG IV. If you are using aprevious release of the compiler, you will need to determine what functions are supported on yoursystem. For example, if you are using a V5R1 system, the functions new to the 7.1 release will not besupported.

What's New since 7.1?This section describes the enhancements made to ILE RPG after 7.1.

Free-form Control, File, Definition, and Procedure statements

v Free-form Control statements begin with CTL-OPT and end with a semicolon. See Free-FormControl Statement on page 5-14.CTL-OPT OPTION(*SRCSTMT : *NODEBUGIO)

ALWNULL(*USRCTL);

v Free-form File definition statements begin with DCL-F and end with a semicolon. SeeFree-Form File Definition Statement on page 5-38.The following statements define three files1. An externally-described DISK file opened for input and update.2. An externally-described WORKSTN file opened for input and output.3. A program-described PRINTER file with record-length 132.DCL-F custFile usage(*update) extfile(custFilename);DCL-F screen workstn;DCL-F qprint printer(132) oflind(qprintOflow);

v Free-form data definition statements begin with DCL-C, DCL-DS, DCL-PI, DCL-PR, or DCL-S,and end with a semicolon. See Free-Form Definition Statement on page 5-74.The following statements define several items1. A named constant MAX_ELEMS.2. A standalone varying length character field fullName.

Copyright IBM Corp. 1994, 2014 2-1

|#

####

|||||||||||||||||||||

3. A qualified data structure with an integer subfield num and a UCS-2 subfield address.4. A prototype for the procedure 'Qp0lRenameUnlink'.DCL-C MAX_ELEMS 1000;DCL-S fullName VARCHAR(50)

INZ(Unknown name);DCL-DS ds1 QUALIFIED;

num INT(10);address UCS2(100);

END-DS;DCL-PR Qp0lRenameUnlink INT(10) EXTPROC(*DCLCASE);

oldName POINTER VALUE OPTIONS(*STRING);newName POINTER VALUE OPTIONS(*STRING);

END-PR;

v Free-form Procedure definition statements begin with DCL-PROC and end with a semicolon.The END-PROC statement is used to end a procedure. See Free-Form Procedure Statementon page 5-189.The following example shows a free-form subprocedure definition.DCL-PROC getCurrentUserName EXPORT;

DCL-PI *n CHAR(10) END-PI;DCL-S curUser CHAR(10) INZ(*USER);

RETURN curUser;END-PROC;

v The /FREE and /END-FREE directives are no longer required. The compiler will ignore them.v Free-form statements and fixed-form statements may be intermixed.

IF endDate < beginDate;C GOTO internalError

ENDIF;duration = %DIFF(endDate : beginDate : *days);. . .

C internalError TAG

Tip: See Differences between fixed-form and free-form to be aware of on page 5-4.

Open Access filesAn Open Access file is a file which has all its operations handled by a user-written program orprocedure, rather than by the operating system. This program or procedure is called an "OpenAccess Handler" or simply a "handler". The HANDLER keyword specifies the handler. See OpenAccess Files on page 3-95.

New XML-INTO options

v XML namespaces are supported by the "ns" and "nsprefix" options. See ns option and nsprefixoption.

v XML names with characters that are not supported by RPG for subfield names are supportedby the "case=convert" option. See case option.

Support for CCSID conversions that cause a loss of data when a source character does not exist in thetarget character set

Control-specification keyword CCSIDCVT(*EXCP : *LIST). See CCSIDCVT(*EXCP | *LIST) onpage 5-19.v Use CCSIDCVT(*EXCP) to get an exception if a CCSID conversion loses data due to the source

character not having a match in the target character set.v Use CCSIDCVT(*LIST) to get a listing of every CCSID conversion in the module, with a

diagnostic message indicating whether the conversion has the potential of losing data.

VALIDATE(*NODATETIME) to allow the RPG compiler to skip the validation step when workingwith date, time and timestamp data

What's New


|||||||||||||||||||||||||||||||||||||||||||||||||||||

Use Control-specification keyword VALIDATE(*NODATETIME) to allow the RPG compiler totreat date, time, and timestamp data as character data, without performing the checks for validity.See VALIDATE(*NODATETIME) on page 5-36.

This may improve the performance of some date, time, and timestamp operations.

Note: Skipping the validation step can lead to serious data corruption problems. You should onlyuse this feature when you are certain that your date, time, and timestamp data is always valid.

Table 2-1. Changed Language Elements Since 7.1: Control specification keywordsElement Description

DFTACTGRPkeyword

DFTACTGRP(*NO) is assumed if there are any free-form Control specifications, and if atleast one of the ACTGRP, BNDDIR, or STGMDL keyword is used. See DFTACTGRP(*YES |*NO) on page 5-25.

Table 2-2. Changed Language Elements Since 7.1: DirectivesElement Description

/FREE and/END-FREEdirectives

These directives are no longer necessary to indicate the beginning and ending of free-formcode. They are ignored by the compiler. See /FREE... /END-FREE on page 3-8.

Table 2-3. Changed Language Elements Since 7.1: Definition-specification keywordsElement Description

DTAARA keyword In a free-form definition:

v *VAR is not used. If the name is specified without quotes, it is assumed to be the name ofa variable or named constant.

v For a data structure, *AUTO is used to specify that it is a Data Area Data Structure.*USRCTL is used to specify that the data area can be manipulated using IN, OUT andUNLOCK operations.

See DTAARA keyword on page 5-99.

EXTFLD keyword In a free-form subfield definition

v The parameter is optionalv If the parameter is specified without quotes, it is assumed to be the name of a

previously-defined named constant.

See EXTFLD{(field_name)} on page 5-103.

EXTNAME keyword In a free-form data structure definition

v If the file-name or format-name parameter is specified without quotes, it is assumed to bethe name of a previously-defined named constant.

See EXTNAME(file-name{:format-name}{:*ALL| *INPUT|*OUTPUT|*KEY}) on page 5-105.

EXPORT andIMPORT keywords

In a free-form definition

v *DCLCASE may be specified for the external name indicating that the external name isidentical to the way the stand-alone field or data structure is specified, with the samemixed case letters.

See EXPORT{(external_name)} on page 5-102 and IMPORT{(external_name)} on page5-112.

What's New

What's New 2-3

|||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Table 2-3. Changed Language Elements Since 7.1: Definition-specification keywords (continued)Element Description

EXTPROC keyword In a free-form prototype definition or a procedure-interface definition

v *DCLCASE may be specified for the external procedure or method name indicating thatthe external name is identical to the way the prototype or procedure interface is specified,with the same mixed case letters.

v If the procedure interface name is specified as *N, the external name is taken from theDCL-PROC statement.

See EXTPROC({*CL|*CWIDEN|*CNOWIDEN| {*JAVA:class-name:}}name) on page 5-106.

CLASS, DATFMT,PROCPTR, TIMFMT,and VARYINGkeywords

These keywords are not used in a free-form definition. The information specified by thesekeywords is specified as part of the related data-type keywords.

FROMFILE,PACKEVEN, andTOFILE keywords

These keywords are not allowed in a free-form definition.

OVERLAY keyword The parameter cannot be the name of the data structure for a free-form subfield definition.The POS keyword is used instead.

See POS(starting-position) on page 5-137.

Table 2-4. Changed Language Elements Since 7.1: Order of statementsElement Description

File and Definitionstatements

File and Definition statements can be intermixed.

See RPG IV Specification Types on page 5-1.

Table 2-5. New Language Elements Since 7.1: Free-form statementsElement Description

CTL-OPT Begins a free-form Control statement

See Free-Form Control Statement on page 5-14.

DCL-F Begins a free-form File definition

See Free-Form File Definition Statement on page 5-38.

DCL-C Begins a free-form Named Constant definition

See Free-Form Named Constant Definition on page 5-77.

DCL-DS Begins a free-form Data Structure definition

See Free-Form Data Structure Definition on page 5-78.

DCL-SUBF Begins a free-form Subfield definition. Specifying "DCL-SUBF" is optional unless the subfieldname is the same as an operation code allowed in free-form calculations.

See Free-Form Subfield Definition on page 5-82.

END-DS Ends a free-form Data Structure definition. If there are no subfields, it can be specified afterthe last keyword of the DCL-DS statement.

See Free-Form Data Structure Definition on page 5-78.

DCL-PI Begins a free-form Procedure Interface definition

See Free-Form Procedure Interface Definition on page 5-84.

What's New


|||||||||||||||

||

||||

|||||||||||||||||||||||||||||||||||||||||

Table 2-5. New Language Elements Since 7.1: Free-form statements (continued)Element Description

DCL-PR Begins a free-form Prototype definition

See Free-Form Prototype Definition on page 5-83.

DCL-PARM Begins a free-form Parameter definition. Specifying "DCL-PARM" is optional unless theparameter name is the same as an operation code allowed in free-form calculations

See Free-Form Parameter Definition on page 5-86..

END-PI Ends a free-form Procedure Interface definition. If there are no parameters, it can be specifiedafter the last keyword of the DCL-PI statement.

See Free-Form Procedure Interface Definition on page 5-84.

END-PR Ends a free-form Prototype definition. If there are no parameters, it can be specified after thelast keyword of the DCL-PR statement.

See Free-Form Prototype Definition on page 5-83.

DCL-S Begins a free-form Standalone Field definition

See Free-Form Standalone Field Definition on page 5-78.

DCL-PROC Begins a free-form Procedure definition

See Free-Form Procedure Statement on page 5-189.

END-PROC Ends a free-form Procedure definition

See Free-Form Procedure Statement on page 5-189.

Table 2-6. New Language Elements Since 7.1: File definition keywordsElement Description

HANDLER Specifies that the file is an Open Access file.

See HANDLER(program-or-procedure { : communication-area)}) on page 5-56.

DISK{(*EXT |record-length)}

Device keywords to specify the device type of a free-form File definition.

v The default device type is DISK.v The default parameter for each device-type keyword is *EXT, indicating that it is an

externally-described file.

See File devices on page 3-94.

PRINTER{(*EXT |record-length)}

SEQ{(*EXT |record-length)}

SPECIAL{(*EXT |record-length)}

WORKSTN{(*EXT |record-length)}

USAGE(*INPUT*OUTPUT *UPDATE*DELETE)

Specifies the usage of the file in a free-form file definition.

See USAGE(*INPUT *OUTPUT *UPDATE *DELETE) on page 5-72.

KEYED{(*CHAR :key-length)}

Indicates that the file is keyed in a free-form file definition.

See KEYED{(*CHAR : key-length)} on page 5-59.

What's New

What's New 2-5

||||||||||||||||||||||||||||||||||||||||||

||||||||||||||||||

Table 2-7. New Language Elements Since 7.1: Free-form data-type keywordsElement Description

CHAR(length) Fixed-length alphanumeric data type

See CHAR(length) on page 5-96.

VARCHAR(length{:prefix-size})

Varying-length alphanumeric data type

See VARCHAR(length {:2 | 4}) on page 5-147.

GRAPH(length) Fixed-length Graphic data type

See GRAPH(length) on page 5-112.

VARGRAPH(length{:prefix-size})

Varying-length Graphic data type

See VARGRAPH(length {:2 | 4}) on page 5-147.

UCS2(length) Fixed-length UCS-2 data type

See UCS2(length) on page 5-146.

VARUCS2(length{:prefix-size})

Varying-length UCS-2 data type

See VARUCS2(length {:2 | 4}) on page 5-148.

IND Indicator data type

See IND on page 5-113.

INT(digits) Integer data type

See INT(digits) on page 5-113.

UNS(digits) Unsigned integer data type

See UNS(digits) on page 5-146.

PACKED(digits{:decimals})

Packed decimal data type

See PACKED(digits {: decimal-positions}) on page 5-136.

ZONED(digits{:decimals})

Zoned decimal data type

See ZONED(digits {: decimal-positions}) on page 5-149.

BINDEC(digits{:decimals})

Binary decimal data type

See BINDEC(digits {: decimal-positions}) on page 5-96.

FLOAT(size) Float data type

See FLOAT(bytes) on page 5-111.

DATE{(format)} Date data type

See DATE{(format{separator})} on page 5-98.

TIME{(format)} Time data type

See TIME{(format{separator})} on page 5-145.

TIMESTAMP Timestamp data type

See TIMESTAMP on page 5-145.

POINTER{(*PROC)} Pointer data type. The optional parameter *PROC indicates that it is a procedure pointer.

See POINTER{(*PROC)} on page 5-137.

What's New


|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

Table 2-7. New Language Elements Since 7.1: Free-form data-type keywords (continued)Element Description

OBJECT{(*JAVA :class-name)}

Object data type. The parameters are optional if it is defining the return type of a Javaconstructor.

See OBJECT{(*JAVA:class-name)} on page 5-122.

Table 2-8. New Language Elements Since 7.1: Free-form data definition keywordsElement Description

EXT Indicates that a data structure is externally described. This keyword is optional if theEXTNAME keyword is specified as the first keyword for a data structure definition. SeeEXT on page 5-103.

POS(subfield-start-position)

Specifies the starting position of a subfield in the data structure.

See POS(starting-position) on page 5-137.

PSDS Specifies that the data structure is a Program Status Data Structure. See PSDS on page5-139.

What's New in 7.1?This section describes the enhancements made to ILE RPG in 7.1.

Sort and search data structure arrays

Data structure arrays can be sorted and searched using one of the subfields as a key.// Sort the custDs array by the amount_owing subfieldSORTA custDs(*).amount_owing;

// Search for an element in the custDs array where the// account_status subfield is "K"elem = %LOOKUP("K" : custDs(*).account_status);

Sort an array either ascending or descending

An array can be sorted ascending using SORTA(A) and descending using SORTA(D). The arraycannot be a sequenced array (ASCEND or DESCEND keyword).

// Sort the salary array in descending orderSORTA(D) salary;

New built-in function %SCANRPL (scan and replace)

The %SCANRPL built-in function scans for all occurrences of a value within a string and replacesthem with another value.

// Replace NAME with Tomstring1 = See NAME. See NAME run. Run NAME run.;string2 = %ScanRpl(NAME : Tom : string1);// string2 = See Tom. See Tom run. Run Tom run.

%LEN(varying : *MAX)

The %LEN builtin function can be used to obtain the maximum number of characters for avarying-length character, UCS-2 or Graphic field.

Use ALIAS names in externally-described data structures

Use the ALIAS keyword on a Definition specification to indicate that you want to use thealternate names for the subfields of externally-described data structures. Use the ALIAS keywordon a File specification to indicate that you want to use the alternate names for LIKEREC datastructures defined from the records of the file.

What's New

What's New 2-7

||||||||||||||||||||||||||#

#

#

#######

#

####

#

######

#

##

#

####

A R CUSTRECA CUSTNM 25A ALIAS(CUSTOMER_NAME)A CUSTAD 25A ALIAS(CUSTOMER_ADDRESS)A ID 10P 0

D custDs e ds ALIASD QUALIFIED EXTNAME(custFile)/free

custDs.customer_name = John Smith;custDs.customer_address = 123 Mockingbird Lane;custDs.id = 12345;

Faster return values

A procedure defined with the RTNPARM keyword handles the return value as a hiddenparameter. When a procedure is prototyped to return a very large value, especially a very largevarying value, the performance for calling the procedure can be significantly improved bydefining the procedure with the RTNPARM keyword.

D getFileData pr a varying len(1000000)D rtnparmD file a const varying len(500)D data S a varying len(1000)/free

data = getFileData (/home/mydir/myfile.txt);

%PARMNUM built-in function

The %PARMNUM(parameter_name) built-in function returns the ordinal number of theparameter within the parameter list. It is especially important to use this built-in function when aprocedure is coded with the RTNPARM keyword.

D piD name 100a const varyingD id 10i 0 valueD errorInfo likeds(errs_t)D options(*nopass)/free

// Check if the "errorInfo" parameter was passedif %parms >= %parmnum(errorInfo);

Optional prototypes

If a program or procedure is not called by another RPG module, it is optional to specify theprototype. The prototype may be omitted for the following types of programs and procedures:v A program that is only intended to be used as an exit program or as the command-processing

program for a commandv A program that is only intended to be called from a different programming languagev A procedure that is not exported from the modulev A procedure that is exported from the module but only intended to be called from a different

programming language

Pass any type of string parameterImplicit conversion will be done for string parameters passed by value or by read-only reference.For example, a procedure can be prototyped to have a CONST UCS-2 parameter, and characterexpression can be passed as a parameter on a call to the procedure. This enables you to write asingle procedure with the parameters and return value prototyped with the UCS-2 type. To callthat procedure, you can pass any type of string parameter, and assign the return value to anytype of string variable.

// The makeTitle procedure upper-cases the value// and centers it within the provided lengthalphaTitle = makeTitle(alphaValue : 50);ucs2Title = makeTitle(ucs2Value : 50);dbcsTitle = makeTitle(dbcsValue : 50);

What's New


###########

#

##########

#

###########

#

########

############

Two new options for XML-INTO

v The datasubf option allows you to name a subfield that will receive the text data for an XMLelement that also has attributes.

v The countprefix option reduces the need for you to specify the allowmissing=yes option. Itspecifies the prefix for the names of the additional subfields that receive the number of RPGarray elements or non-array subfields set by the XML-INTO operation.

These options are also available through a PTF for 6.1.

Teraspace storage model

RPG modules and programs can be created to use the teraspace storage model or to inherit thestorage model of their caller. With the teraspace storage model, the system limits regardingautomatic storage are significantly higher than those for the single-level storage model. There arelimits for the amount of automatic storage for a single procedure and for the total automaticstorage of all the procedures on the call stack.

Use the storage model (STGMDL) parameter on the CRTRPGMOD or CRTBNDRPG command, oruse the STGMDL keyword on the Control specification.

*TERASPACEThe program or module uses the teraspace storage model.

*SNGLVLThe program or module uses the single-level storage model.

*INHERITThe program or module inherits the storage model of its caller.

Change to the ACTGRP parameter of the CRTBNDRPG command and the ACTGRP keyword on theControl specification

The default value of the ACTGRP parameter and keyword is changed from QILE to *STGMDL.

ACTGRP(*STGMDL) specifies that the activation group depends on the storage model of theprogram. When the storage model is *TERASPACE, ACTGRP(*STGMDL) is the same asACTGRP(QILETS). Otherwise, ACTGRP(*STGMDL) is the same as ACTGRP(QILE).

Note: The change to the ACTGRP parameter and keyword does not affect the default way theactivation group is assigned to the program. The default value for the STGMDL parameter andkeyword is *SNGLVL, so when the ACTGRP parameter or keyword is not specified, theactivation group of the program will default to QILE as it did in prior releases.

Allocate teraspace storage

Use the ALLOC keyword on the Control specification to specify whether the RPGstorage-management operations in the module will use teraspace storage or single-level storage.The maximum size of a teraspace storage allocation is significantly larger than the maximum sizeof a single-level storage allocation.

Encrypted listing debug view

When a module's listing debug view is encrypted, the listing view can only be viewed during adebug session when the person doing the debugging knows the encryption key. This enables youto send debuggable programs to your customers without enabling your customers to see yoursource code through the listing view. Use the DBGENCKEY parameter on the CRTRPGMOD,CRTBNDRPG, or CRTSQLRPGI command.

What's New

What's New 2-9

######

#

#

|||||##

##

##

##

##

#

###

####

#

####

#

#####

Table 2-9. Changed Language Elements Since 6.1Language Unit Element Description

Control specification keywords ACTGRP(*STGMDL) *STGMDL is the new default for theACTGRP keyword and commandparameter. If the program uses theteraspace storage module, theactivation group is QILETS.Otherwise it is QILE.

Built-in functions %LEN(varying-field : *MAX) Can now be used to obtain themaximum number of characters of avarying-length field.

Operation codes SORTA(A | D) The SORTA operation code nowallows the A and D operationextenders indicating whether thearray should be sorted ascending (A)or descending (D).

Table 2-10. New Language Elements Since 6.1Language Unit Element Description

Control specification keywords STGMDL(*INHERIT | *TERASPACE| *SNGLVL)

Controls the storage model of themodule or program

ALLOC(*STGMDL | *TERASPACE |*SNGLVL)

Controls the storage model for thestorage-managent operations%ALLOC, %REALLOC, DEALLOC,ALLOC, REALLOC

File specification keywords ALIAS Use the alternate field names for thesubfields of data structures definedwith the LIKEREC keyword

Definition specification keywords ALIAS Use the alternate field names for thesubfields of the externally-describeddata structure

RTNPARM Specifies that the return value for theprocedure should be handled as ahidden parameter

Built-in functions %PARMNUM Returns the ordinal number of theparameter in the parameter list

%SCANRPL Scans for all occurrences of a valuewithin a string and replaces themwith another value

XML-INTO options datasubf Name a subfield that will receive thetext data for an XML element thatalso has attributes

countprefix Specifies the prefix for the names ofthe additional subfields that receivethe number of RPG array elements ornon-array subfields set by theXML-INTO operation

What's New in 6.1?This section describes the enhancements made to ILE RPG in 6.1.

THREAD(*CONCURRENT)

What's New


##########################

##################################################

#

When THREAD(*CONCURRENT) is specified on the Control specification of a module, itprovides ability to run concurrently in multiple threads:v Multiple threads can run in the module at the same time.v By default, static variables will be defined so that each thread will have its own copy of the

static variable.v Individual variables can be defined to be shared by all threads using STATIC(*ALLTHREAD).v Individual procedures can be serialized so that only one thread can run them at one time, by

specifying SERIALIZE on the Procedure-Begin specification.

Ability to define a main procedure which does not use the RPG cycle

Using the MAIN keyword on the Control specification, a subprocedure can be identified as theprogram entry procedure. This allows an RPG application to be developed where none of themodules uses the RPG cycle.

Files defined in subprocedures

Files can be defined locally in subprocedures. I/O to local files can only be done with datastructures; I and O specifications are not allowed in subprocedures, and the compiler does notgenerate I and O specifications for externally described files. By default, the storage associatedwith local files is automatic; the file is closed when the subprocedure returns. The STATICkeyword can be used to indicate that the storage associated with the file is static, so that allinvocations of the subprocedure will use the same file, and if the file is open when thesubprocedure returns, it will remain open for the next call to the subprocedure.

Qualified record formats

When a file is defined with the QUALIFIED keyword, the record formats must be qualified bythe file name, MYFILE.MYFMT. Qualified files do not have I and O specifications generated bythe compiler; I/O can only be done through data structures.

Files defined like other files

Using the LIKEFILE keyword, a file can be defined to use the same settings as another Filespecification, which is important when passing a file as a parameter. If the file isexternally-described, the QUALIFIED keyword is implied. I/O to the new file can only be donethrough data structures.

Files passed as parameters

A prototyped parameter can be defined as a File parameter using the LIKEFILE keyword. Anyfile related through the same LIKEFILE definition may be passed as a parameter to theprocedure. Within the called procedure or program, all supported operations can be done on thefile; I/O can only be done through data structures.

EXTDESC keyword and EXTFILE(*EXTDESC)

The EXTDESC keyword identifies the file to be used by the compiler at compile time to obtainthe external decription of the file; the filename is specified as a literal in one of the forms'LIBNAME/FILENAME' or 'FILENAME'. This removes the need to provide a compile-timeoverride for the file.

The EXTFILE keyword is enhanced to allow the special value *EXTDESC, indicating that the filespecified by EXTDESC is also to be used at runtime.

EXTNAME to specify the library for the externally-described data structure

The EXTNAME keyword is enhanced to allow a literal to specify the library for the external file.EXTNAME('LIBNAME/FILENAME') or EXTNAME('FILENAME') are supported. This removesthe need to provide a compile-time override for the file.

EXFMT allows a result data structure

What's New

What's New 2-11

The EXFMT operation is enhanced to allow a data structure to be specified in the result field. Thedata structure must be defined with usage type *ALL, either as an externally-described datastructure for the record format (EXTNAME(file:fmt:*ALL), or using LIKEREC of the record format(LIKEREC(fmt:*ALL).

Larger limits for data structures, and character, UCS-2 and graphic variables

v Data structures can have a size up to 16,773,104.v Character definitions can have a length up to 16,773,104. (The limit is 4 less for variable length

character definitions.)v Character definitions can have a length up to 16,773,104. (The limit is 4 less for variable length

character definitions.)v UCS-2 definitions can have a length up to 8,386,552 UCS-2 characters. (The limit is 2 less for

variable length UCS-2 definitions.)v Graphic definitions can have a length up to 8,386,552 DBCS characters. (The limit is 2 less for

variable length graphic definitions.)v The VARYING keyword allows a parameter of either 2 or 4 indicating the number of bytes

used to hold the length prefix.

%ADDR(varying : *DATA)

The %ADDR built-in function is enhanced to allow *DATA as the second parameter to obtain theaddress of the data part of a variable length field.

Larger limit for DIM and OCCURS

An array or multiple-occurrence data structure can have up to 16,773,104 elements, provided thatthe total size is not greater than 16,773,104.

Larger limits for character, UCS-2 and DBCS literals

v Character literals can now have a length up to 16380 characters.v UCS-2 literals can now have a length up to 8190 UCS-2 characters.v Graphic literals can now have a length up to 16379 DBCS characters.

TEMPLATE keyword for files and definitions

The TEMPLATE keyword can be coded for file and variable definitions to indicate that the namewill only be used with the LIKEFILE, LIKE, or LIKEDS keyword to define other files or variables.Template definitions are useful when defining types for prototyped calls, since the compiler onlyuses them at compile time to help define other files and variables, and does not generate anycode related to them.

Template data structures can have the INZ keyword coded for the data structure and itssubfields, which will ease the use of INZ(*LIKEDS).

Relaxation of some UCS-2 rules

The compiler will perform some implicit conversion between character, UCS-2 and graphicvalues, making it unnecessary to code %CHAR, %UCS2 or %GRAPH in many cases. Thisenhancement is also available through PTFs for V5R3 and V5R4. Implicit conversion is nowsupported forv Assignment using EVAL and EVALR.v Comparison operations in expressions.v Comparison using fixed form operations IFxx, DOUxx, DOWxx, WHxx, CASxx, CABxx, COMP.v Note that implicit conversion was already supported for the conversion operations MOVE and

MOVEL.

UCS-2 variables can now be initialized with character or graphic literals without using the%UCS2 built-in function.

What's New


Eliminate unused variables from the compiled object

New values *UNREF and *NOUNREF are added to the OPTION keyword for the CRTBNDRPGand CRTRPGMOD commands, and for the OPTION keyword on the Control specification. Thedefault is *UNREF. *NOUNREF indicates that unreferenced variables should not be generatedinto the RPG module. This can reduce program size, and if imported variables are not referenced,it can reduce the time taken to bind a module to a program or service program.

PCML can now be stored in the module

Program Call Markup Language (PCML) can now be stored in the module as well as in a streamfile. By using combinations of the PGMINFO command parameter and/or the new PGMINFOkeyword for the Control specification, the RPG programmer can choose where the PCMLinformation should go. If the PCML information is placed in the module, it can later be retrievedusing the QBNRPII API. This enhancement is also available through PTFs for V5R4, but onlythrough the Control specification keyword.

Table 2-11. Changed Language Elements Since V5R4Language Unit Element Description

Control specification keywords OPTION(*UNREF | *NOUNREF) Specifies that unused variablesshould not be generated into themodule.

THREAD(*CONCURRENT) New parameter *CONCURRENTallows running concurrently inmultiple threads.

File specification keywords EXTFILE(*EXTDESC) Specifies that the value of theEXTDESC keyword is also to be usedfor the EXTFILE keyword.

Built-in functions %ADDR(varying-field : *DATA) Can now be used to obtain theaddress of the data portion of avarying-length variable.

Definition specification keywords DIM(16773104) An array can have up to 16773104elements.

EXTNAME('LIB/FILE') Allows a literal for the file name. Theliteral can include the library for thefile.

OCCURS(16773104) A multiple-occurrence data structurecan have up to 16773104 elements.

VARYING{(2|4)} Can now take a parameter indicatingthe number of bytes for the lengthprefix.

Definition specifications Length entry Can be up to 9999999 for DataStructures, and definitions of type A,C or G. (To define a longer item, theLEN keyword must be used.)

Input specifications Length entry Can be up to 999

Documents

ILE-RPG v7.1 Ref