Migration RPG Language Reference Manual

MIGRATION RPG
LANGUAGE REFERENCE
MANUAL
jUNE 2011
Revision/Update Information: This revised manual supersedes the

Migration Language Reference Manual,
Version 7.3.
Operating System and Version: OpenVMS VAX Version 7.1 or higher
Operating System and Version: OpenVMS Alpha Version 7.3 or higher
Operating System and Version: OpenVMS Integrity Version 8.2 or higher
Software Version: Migration RPG Version 8.3 or higher
Migration Specialties International Florence, Colorado

——————————
First Printing, October 1999

Revised, January 2001
Revised, March 2002
Revised, January 2005
Revised, June 2011
——————————
The information in this document is subject to change without notice
and should not be construed as a commitment by MSI. MSI assumes no
responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and
may be used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of this software by
MSI or its affiliated companies.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government
is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights
in Technical Data and Computer Software clause at DFARS 252.227-7013.
——————————
Copyright ©2011 by Migration Specialties International, Inc. (MSI)

217 W 2nd Street, Florence, CO, USA 81226-1403
Info@MigrationSpecialties.com, www.MigrationSpecialties.com
All Rights Reserved.
Printed in U.S.A.
——————————
The following are trademarks of Migration Specialties International, Inc:
MSI, Migration RPG, SFG, S/3X Conversion Tools, CVTFILE, CBL
All other trademarks and registered names used in this document are the
property of their respective owners.
ii
Contents
PREFACE xxxiii
CHAPTER 1 UNDERSTANDING THE MIGRATION RPG LOGIC CYCLE 1–1
1.1 MIGRATION RPG OVERVIEW 1–1
1.2 RPG PROGRAM SPECIFICATIONS 1–1

1.2.1 Control Specification - H 1–2
1.2.2 File Description Specification - F 1–2
1.2.3 Extension Specification - E 1–2
1.2.4 Line Counter Specification - L 1–3
1.2.5 Input Specifications - I 1–3
1.2.6 Calculation Specification - C 1–3
1.2.7 Output Specification - O 1–3
1.3 THE RPG LOGIC CYCLE 1–7
1.4 THE RPG LOGIC CYCLE IN DETAIL 1–7

1.4.1 The First Cycle 1–15
1.4.2 A Normal Cycle 1–15
1.4.2.1 Total Time Processing • 1–16
1.4.2.2 Detail Time Processing • 1–18
1.4.3 The Last Cycle 1–20
CHAPTER 2 MIGRATION RPG PROGRAM SPECIFICATIONS 2–1
2.1 COLUMN NUMBERS 2–1
2.2 COMMON FIELDS 2–2

2.2.1 Line Number 2–2
2.2.2 Specification Type 2–2
2.2.3 Comments 2–3
2.3 COMPILER DIRECTIVES 2–3
iii
Contents
CHAPTER 3 CONTROL SPECIFICATION (H) 3–1
3.1 COLUMNS 1 - 5 (LINE NUMBER) 3–2
3.2 COLUMN 6 (SPECIFICATION IDENTIFICATION) 3–2
3.3 COLUMN 7 (COMMENT OR COMPILER DIRECTIVE) 3–2
3.4 COLUMNS 7 - 10 (NO-OP) 3–2
3.5 COLUMN 15 (DEBUG OPTION) 3–2
3.6 COLUMNS 16 - 17 (NO-OP) 3–3
3.7 COLUMN 18 (CURRENCY SYMBOL) 3–3
3.8 COLUMN 19 (DATE FORMAT CODE) 3–3
3.9 COLUMN 20 (DATE EDIT CODE) 3–4
3.10 COLUMN 21 (INVERTED PRINT CODE) 3–4
3.11 COLUMNS 22 - 25 (NO-OP) 3–5
3.12 COLUMN 26 (ALTERNATE COLLATING SEQUENCE) 3–5
3.13 COLUMNS 27 - 42 (NO-OP) 3–5
3.14 COLUMN 43 (FILE TRANSLATION CODE) 3–6
3.15 COLUMNS 44 - 59 (NO-OP) 3–6
3.16 COLUMN 60 (ZONED-DECIMAL OUTPUT) 3–6
iv
Contents
3.17 COLUMNS 61 - 74 (NO-OP) 3–6
3.18 COLUMNS 75 - 80 (COMMENTS) 3–6
CHAPTER 4 FILE DESCRIPTION SPECIFICATION (F) 4–1
4.4 COLUMNS 7 - 14 (FILE NAME) 4–2
4.5 COLUMN 15 (FILE TYPE) 4–3
4.6 COLUMN 16 (FILE DESIGNATION) 4–4
4.7 COLUMN 17 (END-OF-FILE) 4–6
4.8 COLUMN 18 (SEQUENCE CODE) 4–7
4.9 COLUMN 19 (FILE FORMAT) 4–7
4.10 COLUMNS 20 - 23 (BLOCK LENGTH) 4–8
4.11 COLUMNS 24 - 27 (RECORD LENGTH) 4–8
4.12 COLUMN 28 (PROCESSING MODE) 4–8
4.13 COLUMNS 29 - 30 (KEY LENGTH) 4–15
4.14 COLUMN 31 (RECORD ADDRESS TYPE) 4–15
v
Contents
4.15 COLUMN 32 (FILE ORGANIZATION) 4–16
4.16 COLUMNS 33 - 34 (OVERFLOW INDICATOR) 4–17
4.17 COLUMNS 35 - 38 (KEY START LOCATION) 4–17
4.18 COLUMN 39 (EXTENSION CODE) 4–18
4.19 COLUMNS 40 - 46 (DEVICE CODE) 4–18
4.20 COLUMNS 47 - 52 (NO-OP) 4–20
4.21 COLUMN 53 (CONTINUATION LINES) 4–20
4.22 COLUMNS 54 - 65 (SPECIAL DEVICE ROUTINE) 4–20
4.23 COLUMNS 54 - 59 (CONTINUATION OPTIONS) AND COLUMNS 60 -

65 (CONTINUATION ENTRIES) 4–21
4.23.1 Rules for Specifying a Continuation Line on a DISK File 4–21
4.23.2 Rules for Specifying a Continuation Line on a SPECIAL
Device File 4–21
4.23.3 Rules for Specifying a Continuation Line on a WORKSTN
Device File 4–22
4.24 COLUMN 66 (FILE ADDITION) 4–24
4.25 COLUMN 67 (NO-OP) 4–24
4.26 COLUMNS 68 - 69 (ALTERNATE KEY) 4–24
4.27 COLUMN 70 (NO-OP) 4–25
4.28 COLUMNS 71 - 72 (FILE CONDITIONING INDICATOR) 4–25
4.29 COLUMN 73 (FILE SHARING) 4–25
vi
Contents
4.30 COLUMN 74 (NO DEFERRED WRITE) 4–26
CHAPTER 5 EXTENSION SPECIFICATION (E) 5–1
5.4 COLUMNS 7 - 10 (NO-OP) 5–2
5.5 COLUMNS 11 - 18 (FROM-FILE NAME) 5–2
5.6 COLUMNS 19 - 26 (TO-FILE NAME) 5–3
5.7 COLUMNS 27 - 32 (ARRAY OR TABLE NAME - PRIMARY ENTRY) 5–4
5.8 COLUMNS 33 - 35 (NUMBER OF ENTRIES PER RECORD) 5–4
5.9 COLUMNS 36 - 39 (NUMBER OF ENTRIES IN A TABLE OR ARRAY) 5–5
5.10 COLUMNS 40 - 42 (LENGTH OF ENTRY - PRIMARY ENTRY) 5–6
5.11 COLUMN 43 (DATA FORMAT - PRIMARY ENTRY) 5–6
5.12 COLUMN 44 (DECIMAL POSITIONS - PRIMARY ENTRY) 5–7
5.13 COLUMN 45 (SEQUENCE - PRIMARY ENTRY) 5–7
5.14 COLUMNS 46 - 51 (ARRAY OR TABLE NAME - ALTERNATE ENTRY) 5–8
vii
Contents
5.15 COLUMNS 52 - 54 (LENGTH OF ENTRY - ALTERNATE ENTRY) 5–9
5.16 COLUMN 55 (DATA FORMAT - ALTERNATE ENTRY) 5–9
5.17 COLUMN 56 (DECIMAL POSITIONS - ALTERNATE ENTRY) 5–10
5.18 COLUMN 57 (SEQUENCE - ALTERNATE ENTRY) 5–10
CHAPTER 6 LINE COUNTER SPECIFICATION (L) 6–1
6.5 COLUMNS 15 - 17 (FORM LENGTH) 6–2
6.6 COLUMNS 18 - 19 (FORM LENGTH FLAG) 6–2
6.7 COLUMNS 20 - 22 (OVERFLOW LINE NUMBER) 6–2
6.8 COLUMNS 23 - 24 (OVERFLOW LINE FLAG) 6–3
viii
Contents
CHAPTER 7 INPUT SPECIFICATION (I) 7–1
7.4 COLUMNS 7 - 42 (RECORD AND DATA STRUCTURE DEFINITION) 7–1
7.6 COLUMNS 14 - 16 (AND/OR) 7–2
7.7 COLUMNS 15 - 16 (SEQUENCE) 7–2
7.8 COLUMN 17 (SEQUENCE NUMBER) 7–3
7.9 COLUMN 18 (OPTION) 7–4
7.10 COLUMNS 19 - 20 (RECORD-IDENTIFYING INDICATOR) 7–4

7.10.1 Look-Ahead Fields 7–5
7.11 COLUMNS 21 - 41 (RECORD-IDENTIFICATION CONDITIONS) 7–6

7.11.1 Columns 21 - 24, 28 - 31, 35 - 38 (Position) 7–6
7.11.2 Columns 25, 32, 39 (Not) 7–7
7.11.3 Columns 26, 33, 40 (Character, Zone, or Digit) 7–7
7.11.4 Columns 27, 34, 41 (Comparison Character) 7–8
7.11.5 Columns 14 - 16 (AND and OR Relationships) 7–8
7.12 COLUMN 42 (NO-OP) 7–9
7.13 COLUMNS 43 - 74 (FIELD DEFINITIONS) 7–9

7.13.1 Column 43 (Data Format) 7–9
7.13.2 Columns 44 - 47 and 48 - 51 (Field Start and End
Positions) 7–9
7.13.2.1 Columns 44 - 47 (Field From Location) • 7–10
7.13.2.2 Columns 48 - 51 (Field To Location) • 7–10
ix
Contents
7.13.3 Column 52 (Decimal Positions) 7–10

7.13.4 Columns 53 - 58 (Field Name) 7–11
7.13.4.1 Field Names • 7–11
7.13.4.2 PAGE, PAGE1 - PAGE7 • 7–12
7.13.4.3 *INxx, *IN,xx • 7–12
7.13.5 Columns 59 - 60 (Control break Indicator) 7–12
7.13.6 Columns 61 - 62 (Matching Fields) 7–14
7.13.7 Columns 63 - 64 (Field-Record-Relation Indicator) 7–15
7.13.8 Columns 65 - 70 (Field Indicators) 7–17
7.14 COLUMNS 71 - 74 (NO-OP) 7–17
CHAPTER 8 CALCULATION SPECIFICATION (C) 8–1
8.4 COLUMNS 7 - 8 (CONTROL LEVEL) 8–2
8.5 COLUMNS 9 - 17 (CONDITIONING INDICATORS) 8–2

8.5.1 Relationship Between Control Level and Conditioning
Indicators 8–4
8.6 COLUMNS 18 - 27 (FACTOR 1) 8–4

8.6.1 Factor 1 Restrictions 8–5
8.7 COLUMNS 28 - 32 (OPERATION CODE) 8–5
8.8 COLUMNS 33 - 42 (FACTOR 2) 8–6

8.8.1 Factor 2 Restrictions 8–7
8.9 COLUMNS 43 - 48 (RESULT FIELD) 8–7
x
Contents
8.9.1 Result Field Restrictions 8–8
8.10 COLUMNS 49 - 51 (FIELD LENGTH) 8–8
8.11 COLUMN 52 (DECIMAL POSITIONS) 8–8
8.12 COLUMN 53 (HALF-ADJUST) 8–9
8.13 COLUMNS 54 - 59 (RESULTING INDICATORS) 8–10
CHAPTER 9 OUTPUT SPECIFICATION (O) 9–1
9.5 COLUMNS 14 - 16 (AND/OR) 9–2
9.6 COLUMN 15 (RECORD TYPE) 9–3

9.6.1 Heading Records 9–3
9.6.2 Detail Records 9–3
9.6.3 Total Records 9–3
9.6.4 Exception Records 9–3
9.7 COLUMNS 16 - 18 (ADD/DEL) 9–4
9.8 COLUMN 16 (FETCH OVERFLOW OR RELEASE) 9–5
9.9 COLUMN 17 (SPACE BEFORE) 9–6
xi
Contents
9.10 COLUMN 18 (SPACE AFTER) 9–6
9.11 COLUMNS 19 - 20 (SKIP BEFORE) 9–7
9.12 COLUMNS 21 - 22 (SKIP AFTER) 9–8
9.13 COLUMNS 23 - 31 (OUTPUT INDICATORS) 9–9
9.14 COLUMNS 32 - 37 (FIELD NAME) 9–12

9.14.1 Output field names 9–12
9.14.2 Output Special Words 9–13
9.14.2.1 PAGE, PAGE1 - PAGE7 Special Words • 9–13
9.14.2.2 *PLACE Special Word • 9–14
9.14.2.3 UDATE, UMONTH, UDAY, and UYEAR Special Words • 9–15
9.14.3 Output EXCPT Names 9–16
9.15 COLUMN 38 (EDIT CODES) 9–17
9.16 COLUMN 39 (BLANK AFTER) 9–19
9.17 COLUMNS 40 - 43 (END POSITION IN OUTPUT RECORD) 9–20
9.18 COLUMN 44 (OUTPUT DATA FORMAT) 9–21
9.19 COLUMNS 45 - 70 (CONSTANT OR EDIT WORD) 9–22

9.19.1 Output Constant 9–22
9.19.2 WORKSTN Screen Format Names 9–22
9.19.3 Edit Code Modifiers 9–23
9.19.4 Edit Words 9–24
9.20 COLUMNS 71 - 74 (NO-OP) 9–28
xii
Contents
CHAPTER 10 MIGRATION RPG LANGUAGE ELEMENTS 10–1
10.1 MIGRATION RPG CHARACTER SET 10–1
10.2 RPG DATA TYPES 10–1

10.2.1 Character Data Type 10–2
10.2.2 Binary Data Type 10–4
10.2.3 Packed-decimal Data Type 10–6
10.2.4 Numeric Data Type 10–7
10.3 NAMING CONVENTIONS - USER-DEFINED NAMES 10–9
CHAPTER 11 OPERATION CODES 11–1
11.1 ARITHMETIC OPERATION CODES 11–1
11.2 BIT OPERATION CODES 11–2
11.3 BRANCHING OPERATION CODES 11–3
11.4 COMPARE AND TEST OPERATION CODES 11–3
11.5 EXTERNAL CALL OPERATION CODES 11–4
11.6 INTERNAL SUBROUTINE OPERATION CODES 11–4
11.7 MOVE OPERATION CODES 11–5
11.8 MOVE ZONED OPERATION CODES 11–6
11.9 PROGRAMMED INPUT AND OUTPUT OPERATION CODES 11–6
11.10 SET INDICATOR OPERATION CODES 11–6
xiii
Contents
11.11 STRUCTURED OPERATION CODES 11–7
11.12 OPERATION CODES 11–8

11.12.1 - ADD Operation (Addition) 11–9
11.12.2 - ANDxx Operation (Complex Conditional Operation) 11–11
11.12.3 - BEGSR Operation (Begin Subroutine) 11–13
11.12.4 - BITOF Operation (Bit Off) 11–14
11.12.5 - BITON Operation (Bit On) 11–16
11.12.6 - CABxx Operation (Compare and Branch) 11–17
11.12.7 - CALL Operation (Calling RPG Subprograms) 11–19
11.12.8 - CASxx Operation (Case) 11–21
11.12.9 - CHAIN Operation 11–24
11.12.10 - COMP Operation (Compare) 11–27
11.12.11 - DEBUG Operation 11–29
11.12.12 - DEFN Operation (Field Definition) 11–32
11.12.13 - DIV Operation (Divide) 11–34
11.12.14 - DO Operation (DO Loop) 11–36
11.12.15 - DOUxx Operation (Do Until Loop) 11–39
11.12.16 - DOWxx Operation (Do While Loop) 11–42
11.12.17 - ELSE Operation (IF/ELSE Operation) 11–45
11.12.18 - END Operation 11–47
11.12.19 - ENDSR Operation (End Subroutine) 11–49
11.12.20 - EXCPT Operation (Exception Output Operation) 11–51
11.12.21 - EXIT Operation (External Subroutine Call) 11–54
11.12.22 - EXSR Operation (Execute Subroutine) 11–56
11.12.23 - EXTRN Operation (External Name Definition) 11–57
11.12.24 - FORCE Operation 11–59
11.12.25 - FREE Operation 11–61
11.12.26 - GOTO Operation (Branching Operation) 11–63
11.12.27 - IFxx Operation 11–65
11.12.28 - KEYnn Operation 11–68
11.12.29 - LOKUP Operation 11–71
11.12.29.1 Table Elements in a LOKUP Operation • 11–73
11.12.29.2 Searching Tables Using LOKUP • 11–73
11.12.29.3 Searching Arrays Using LOKUP • 11–74
11.12.30 - MHHZO Operation (Move High Zone to High Zone) 11–79
11.12.31 - MHLZO Operation (Move High Zone to Low Zone) 11–80
11.12.32 - MLHZO Operation (Move Low Zone to High Zone) 11–81
11.12.33 - MLLZO Operation (Move Low Zone to Low Zone) 11–82
11.12.34 - MOVE Operation 11–83
11.12.35 - MOVEA Operation (Move Array) 11–85
11.12.36 - MOVEL Operation (Move Left) 11–89
11.12.37 - MULT Operation (Multiplication) 11–92
xiv
Contents
11.12.38 - MVR Operation (Move Remainder) 11–94

11.12.39 - ORxx Operation (Complex Conditional Operation) 11–96
11.12.40 - PARM Operation (RPG Subprogram Parameter
Definition) 11–98
11.12.41 - PLIST Operation (RPG Subprogram Parameter List) 11–102
11.12.42 - READ Operation 11–104
11.12.43 - READE Operation (Read Equal Key) 11–107
11.12.44 - READP Operation (Read Prior) 11–109
11.12.45 - RETRN Operation (Return From an RPG Subprogram) 11–111
11.12.46 - RLABL Operation (EXIT Operation Parameter Definition) 11–113
11.12.47 - SETnn Operation 11–115
11.12.48 - SETLL Operation (Set Lower Limit) 11–118
11.12.49 - SETOF Operation (Set Indicator[s] Off) 11–120
11.12.50 - SETON Operation (Set Indicator[s] On) 11–121
11.12.51 - SORTA Operation (Sort Array) 11–122
11.12.52 - SQRT Operation (Square Root) 11–124
11.12.53 - SUB Operation (Subtraction) 11–125
11.12.54 - TAG Operation 11–127
11.12.55 - TESTB Operation (Test Bit) 11–128
11.12.56 - TESTZ Operation (Test Zone) 11–130
11.12.57 - TIME Operation (Time of Day) 11–132
11.12.58 - $TIME Operation (Non-Year 2000 Compliant Time of
Day) 11–134
11.12.59 - XFOOT Operation (Summing the Elements of an Array) 11–136
11.12.60 - Z-ADD Operation (Zero-Add) 11–137
11.12.61 - Z-SUB Operation (Zero-Subtract) 11–138
CHAPTER 12 USING INDICATORS 12–1
12.1 AVAILABLE INDICATORS 12–1
12.2 PROGRAM DEFINED INDICATORS 12–1
12.3 INDICATOR TYPES AND USAGE 12–3
12.4 INDICATORS DEFINED BY THE PROGRAMMER 12–4

12.4.1 Record Identifying Indicators 12–4
12.4.1.1 AND and OR Relationships • 12–6
12.4.2 Field Indicators 12–8
12.4.3 Resulting Indicators 12–10
xv
Contents
12.4.4 Control Break Indicators 12–12

12.4.4.1 Using Control Break Indicators • 12–12
12.4.4.2 Rules for Specifying Control Break Indicators • 12–12
12.4.4.3 Control Break Indicator Usage Example • 12–14
12.4.4.4 Split Control Fields • 12–16
12.4.5 Overflow Indicators 12–17
12.4.6 Command Key Indicators 12–19
12.4.7 Halt Indicators 12–20
12.4.7.1 Processing Halt Indicators In RPG Subprograms • 12–22
12.4.8 Return Indicator (RT) 12–23
12.5 INDICATORS DEFINED BY THE PROGRAM 12–24

12.5.1 First Page Indicator (1P) 12–24
12.5.2 Last Record Indicator (LR) 12–26
12.5.3 Level Zero Indicator (L0) 12–27
12.5.4 Matching Record Indicator (MR) 12–28
12.5.5 External Indicators 12–30
12.6 USING INDICATORS AS FIELDS 12–31

12.6.1 *IN and *IN,xx 12–31
12.6.2 *INxx 12–32
CHAPTER 13 USING DISK FILES 13–1
13.1 FILE CHARACTERISTICS 13–1
13.2 FILE NAMES 13–2
13.3 RECORD FORMATS 13–2
13.4 FILE TYPES 13–2
13.5 FILE ORGANIZATIONS 13–3

13.5.1 Sequential Organization 13–3
13.5.2 Relative Organization 13–3
13.5.3 Indexed Organization 13–4
13.6 FILE ACCESS METHODS 13–5
xvi
Contents
13.6.1 Sequential Access 13–5

13.6.1.1 Simple Sequential Access • 13–6
13.6.1.2 Sequential Access by Key • 13–6
13.6.1.3 Sequential Access Within Limits • 13–7
13.6.1.3.1 Using a Limits File • 13–8
13.6.1.3.2 Using the SETLL Operation • 13–11
13.6.2 Random Access 13–12
13.6.2.1 Random Access by Relative Record Number • 13–12
13.6.2.2 Random Access by Key • 13–14
13.6.2.3 Random Access by Addrout File • 13–16
13.6.3 Sequential Access and Random Access by Key 13–19
13.7 CREATING FILES 13–21

13.7.1 Creating Sequential Files 13–21
13.7.2 Creating Relative Files 13–22
13.7.3 Creating Indexed Files 13–22
13.8 ADDING RECORDS TO FILES 13–24

13.8.1 Adding Records to a Sequential File 13–24
13.8.2 Adding Records to a Relative File 13–25
13.8.3 Adding Records to an Indexed File 13–25
13.9 UPDATING RECORDS IN FILES 13–26
13.10 DELETING RECORDS FROM FILES 13–28
13.11 PROCESSING FILES WITH MATCHING RECORDS 13–29

13.11.1 Checking Record Sequence for One Record Type 13–29
13.11.2 Checking Record Sequence for More Than One Record
Type 13–29
13.11.3 Using Matching Fields with Field-Record-Relation
Indicators 13–30
13.11.4 Using Matching Fields to Process More Than One File 13–32
13.12 PROCESSING FILES WITH MULTIPLE KEYS 13–38
13.13 FILE BUFFERS 13–38
xvii
Contents
CHAPTER 14 USING PRINTER OUTPUT FILES 14–1
14.1 REQUIRED SPECIFICATIONS 14–1

14.1.1 File Specification 14–1
14.1.2 Line Counter Specifications 14–2
14.1.3 Output Specifications 14–2
14.1.3.1 File Identification Entries • 14–2
14.1.3.2 Field Description Entries • 14–3
14.2 USING SPECIAL WORDS 14–4
14.3 FIELD EDITING OF NUMERIC FIELDS 14–4
14.4 SPACING AND SKIPPING LINES 14–4
14.5 CONDITIONING OUTPUT LINES 14–6

14.5.1 Printing Lines Before Reading the First Record: First-Page
Indicator 14–6
14.5.2 Specifying Page Breaks: Overflow Indicator 14–7
14.5.2.1 Automatic Handling of the Overflow Condition • 14–7
14.5.2.2 Handling of the Overflow Condition Using Overflow
Indicators • 14–7
14.5.2.3 Handling the Overflow Condition Using Fetch Overflow • 14–10
CHAPTER 15 USING TABLES AND ARRAYS 15–1
15.1 USING TABLES 15–1
15.2 COMPILE-TIME TABLES 15–2

15.2.1 Compile-Time Table Delimiter 15–3
15.3 PRE-EXECUTION-TIME TABLES 15–3
15.4 CREATING TABLE INPUT RECORDS 15–3
15.5 DEFINING TABLES 15–6
xviii
Contents
15.5.1 Defining Related Tables in Alternating Format 15–7

15.5.2 Defining a Compile-Time Table 15–7
15.5.3 Defining a Pre-execution-Time Table 15–9
15.6 REFERENCING TABLE ENTRIES 15–10
15.7 SEARCHING TABLES 15–10

15.7.1 Searching One Table 15–11
15.7.2 Searching Related Tables 15–11
15.8 UPDATING TABLES 15–13

15.8.1 Temporarily Updating Tables 15–13
15.8.2 Permanently Updating Tables 15–14
15.9 OUTPUTTING TABLES 15–15
15.10 USING ARRAYS 15–15
15.11 COMPILE-TIME ARRAYS 15–17

15.11.1 Compile-Time Array Delimiter 15–17
15.12 PRE-EXECUTION-TIME ARRAYS 15–18
15.13 EXECUTION-TIME ARRAYS 15–18
15.14 CREATING ARRAY INPUT RECORDS 15–18
15.15 DEFINING ARRAYS 15–21

15.15.1 Defining Related Arrays in Alternating Format 15–21
15.15.2 Defining a Compile-Time Array 15–22
15.15.3 Defining a Pre-execution-Time Array 15–23
15.15.4 Defining an Execution-Time Array 15–24
15.16 REFERENCING ARRAYS 15–25
15.17 SEARCHING ARRAYS 15–29

15.17.1 Searching An Array 15–30
xix
Contents
15.18 MOVING ARRAY DATA 15–31
15.19 UPDATING ARRAYS 15–32

15.19.1 Temporarily Updating Arrays 15–32
15.19.2 Permanently Updating Arrays 15–32
15.20 OUTPUTTING ARRAYS 15–33
CHAPTER 16 DEFINING AND USING DATA STRUCTURES 16–1
16.1 DATA STRUCTURE STATEMENT 16–1
16.2 DATA STRUCTURE SUBFIELDS 16–2
16.3 USING DATA STRUCTURES 16–3

16.3.1 Breaking a Field Down Using Subfields 16–4
16.3.2 Using a Data Structure Storage Area In More Than One
Way 16–5
16.3.3 Using a Data Structure to Reorganize Input Fields 16–6
16.4 LOCAL DATA AREA 16–6

16.4.1 Accessing The LDA Using SUBR21 16–7
16.5 WORKSTATION INFORMATION DATA STRUCTURE (INFDS) 16–8
CHAPTER 17 SPECIFYING AN ALTERNATE COLLATING SEQUENCE

OR A TRANSLATION FILE 17–1
17.1 SPECIFYING AN ALTERNATE COLLATING SEQUENCE 17–1

17.1.1 Coding an Alternate Sequence Table 17–1
17.2 SPECIFYING FILE TRANSLATION PARAMETERS 17–4

17.2.1 Coding File Translation Parameters 17–4
xx
Contents
CHAPTER 18 USING A SPECIAL DEVICE FILE 18–1
18.1 OVERVIEW 18–1
18.2 FILE DESCRIPTION SPECIFICATIONS 18–1

18.2.1 File Description Continuation Specifications 18–2
18.3 PROGRAMMING CONSIDERATIONS 18–3

18.3.1 Programming Features Supported 18–3
18.3.2 Migration RPG Program Logic 18–3
18.3.3 Coding the SPECIAL File Subroutine 18–4
18.4 SAMPLE PROGRAM 18–5
CHAPTER 19 CODING SUBPROGRAMS 19–1
19.1 CALL OPERATION 19–2
19.2 EXTRN OPERATION 19–4
19.3 FREE OPERATION 19–6
19.4 PARM OPERATION 19–7
19.5 PLIST OPERATION 19–11
19.6 RETRN OPERATION 19–12
19.7 RPG PROGRAM CALLING AN RPG SUBPROGRAM EXAMPLE 19–14
19.8 RPG PROGRAM CALLING A COBOL SUBPROGRAM EXAMPLE 19–17
xxi
Contents
CHAPTER 20 CALLING EXTERNAL ROUTINES, EXIT AND RLABL 20–1
20.1 ACCESS TO EXTERNAL ROUTINES 20–1
CHAPTER 21 AUTO REPORT FEATURES AND FUNCTIONS 21–1
21.1 COMPILE QUALIFIER SPECIFICATION (U) 21–1
21.2 COPYBOOKS 21–3
21.3 FILE AND FIELD MODIFIERS 21–4

21.3.1 File Description Specification Modifiers 21–4
21.3.2 Input Field Specification Modifiers 21–5
21.4 GENERATED SOURCE FILE ORGANIZATION 21–7
21.5 LIMITATIONS 21–8
APPENDIX A CHARACTER SETS A–1
APPENDIX B CONSOLE, KEYBORD, AND CRT DEVICE USAGE B–1
B.1 USING A CONSOLE DEVICE B–2

B.1.1 Limitations of a CONSOLE device B–2
B.1.2 Coding a CONSOLE Device B–2
B.1.2.1 Console Device File Description Specification • B–2
B.1.2.2 Console Device Input Specifications • B–4
B.1.3 Automatic Generation of Display Screen Formats B–7
B.1.4 Displaying CONSOLE Device Files B–8
B.1.4.1 Record Identification Code • B–8
B.1.4.2 Record Identifying Indicator • B–8
B.1.4.3 Data Fields • B–9
B.2 USING A CRT DEVICE B–10
xxii
Contents
B.2.1 Limitations of a CRT Device B–10

B.2.2 Coding a CRT Device File B–10
B.2.2.1 CRT Device File Description Specification • B–10
B.2.2.2 Output Specifications • B–12
B.2.2.3 Displaying Data Using a CRT Device • B–13
B.3 USING A KEYBORD DEVICE B–14

B.3.1 Limitations of a KEYBORD Device B–14
B.3.2 Coding a KEYBORD Device File B–14
B.3.2.1 KEYBORD Device File Description Specification • B–14
B.3.2.2 Calculation Specifications • B–15
B.3.2.3 KEYnn Operation • B–16
B.3.2.3.1 Bypassing a KEYnn Operation • B–17
B.3.2.4 SETnn Operation • B–18
INDEX
EXAMPLES
1–1 Example of first cycle output specifications 1–15
1–2 Program using total time features 1–17
1–3 Example of a program using detail time features 1–19
2–1 Example of column numbers 2–2
2–2 Line number usage 2–2
2–3 Comments in a program 2–3
4–1 File Sharing 4–26
5–1 compile time Table and Array Coding 5–3
9–1 *PLACE Special Word Usage 9–14
9–2 Output field end position in an output record 9–20
10–1 Defining character fields 10–3
10–2 Defining binary fields 10–5
10–3 Defining packed-decimal fields 10–6
11–1 ADD Operation Code Usage - 2 operands 11–10
11–2 ADD Operation Code Usage - 1 operand 11–10
11–3 ADD Operation Code Usage - Indicator controlled 11–10
11–4 ANDxx Operation Code Usage 11–12
11–5 BEGSR Operation Code Usage 11–13
11–6 BITOF Operation Code Usage 11–14
11–7 BITON Operation Code Usage 11–16
11–8 CABxx Operation Code Usage 11–18
11–9 CALL Operation Code Usage 11–20
11–10 CASxx Operation Code Usage 11–22
11–11 CASxx Operation Code Usage - Unconditional CASxx 11–23
11–12 CHAIN Operation Code Usage - Relative file 11–25
xxiii
Contents
11–13 CHAIN Operation Code Usage - Indexed file 11–26

11–14 COMP Operation Code Usage - Equal 11–28
11–15 COMP Operation Code Usage - Greater than or equal 11–28
11–16 COMP Operation Code Usage - Less than or equal 11–28
11–17 COMP Operation Code Usage - Greater than, Less than, Equal 11–28
11–18 DEBUG Operation Code Usage 11–31
11–19 DEBUG Output 11–31
11–20 DEFN Operation Code Usage 11–33
11–21 DIV Operation Code Usage - Indicator Controlled 11–35
11–22 DIV Operation Code Usage - Control Break 11–35
11–23 DIV and MVR Operation Code Usage 11–35
11–24 DO Operation Code Usage 11–38
11–25 DOUxx Operation Code Usage 11–41
11–26 DOWxx Operation Code Usage 11–44
11–27 ELSE Operation Code Usage 11–46
11–28 ENDSR Operation Code Usage 11–50
11–29 EXCPT Operation Code Usage 11–52
11–30 EXIT Operation Code Usage 11–55
11–31 EXSR operation code Usage 11–56
11–32 EXTRN, CALL, and FREE Operation Code Usage 11–58
11–33 FORCE Operation Code Usage 11–60
11–34 FREE Operation code Use 11–62
11–35 GOTO Operation Code Usage 11–64
11–36 IFxx Operation Code Usage 11–67
11–37 KEYnn Operation Code Usage 11–70
11–38 LOKUP Operation Code Usage 11–76
11–39 MHHZO Operation Code Usage 11–79
11–40 MHLZO Operation Code Usage 11–80
11–41 MLHZO Operation Code Usage 11–81
11–42 MLLZO Operation Code Usage 11–82
11–43 MOVE Operation Code Usage 11–84
11–44 MOVEA Operation Code Usage - Setup 11–87
11–45 MOVEA Operation Code Usage - Array to Array (Alphameric) 11–87
11–46 MOVEA Operation Code Usage - Array to Field (Alphameric) 11–88
11–47 MOVEA Operation Code Usage - Field to Array (Numeric) 11–88
11–48 MOVEL Operation Code Usage 11–91
11–49 MULT Operation Code Usage - 2 Operands 11–93
11–50 MULT Operation Code Usage - 1 Operand 11–93
11–51 MULT Operation Code Usage - Indicator Controlled 11–93
11–52 MVR Operation Code Usage 11–95
11–53 ORxx Operation Code Usage 11–97
11–54 CALL and PARM Operation Code Usage 11–101
11–55 PLIST and *ENTRY PLIST Usage 11–103
11–56 READ Operation Code Usage 11–106
11–57 READE Operation Code Usage 11–108
xxiv
Contents
11–58 READP Operation Code Usage 11–110

11–59 RETRN Operation code Use 11–112
11–60 RLABL Operation Code Usage 11–114
11–61 SETnn Operation Code Usage 11–117
11–62 SETLL Operation Code Usage 11–119
11–63 SETOF Operation Code Usage 11–120
11–64 SETON Operation Code Usage 11–121
11–65 SORTA Operation Code Usage 11–123
11–66 SQRT Operation Code Usage 11–124
11–67 SUB Operation Code Usage - 2 operands 11–126
11–68 SUB Operation Code Usage - 1 operand 11–126
11–69 SUB Operation Code Usage - Indicator controlled 11–126
11–70 TAG Operation Code Usage 11–127
11–71 TESTB Operation Code Usage 11–129
11–72 TESTZ Operation Code Usage 11–131
11–73 TIME Operation Code Usage 11–133
11–74 $TIME Operation Code Usage 11–135
11–75 XFOOT Operation Code Usage 11–136
11–76 Z-ADD Operation Code Usage 11–137
11–77 Z-SUB Operation Code Usage 11–138
12–1 Record Identifying Indicators Usage 12–5
12–2 Output generated by Example 12–1 12–6
12–3 AND/OR Usage With Record Identifying Indicators 12–7
12–4 Field Indicator Usage 12–9
12–5 Resulting Indicator Usage 12–11
12–6 Control Break Indicator Usage 12–14
12–7 Split control fields 12–16
12–8 Overflow Indicator Usage 12–18
12–9 Halt Indicator Usage - Record Identification 12–21
12–10 Halt Indicator Usage - Field Indicator 12–21
12–11 Halt Indicator Usage - Resulting Identification 12–21
12–12 Return Indicator Usage 12–23
12–13 First Page Indicator Usage 12–24
12–15 Last Record Indicator Usage 12–26
12–17 Level Zero Indicator Usage 12–27
12–18 Matching Record Indicator Usage 12–29
12–19 External Indicator Usage 12–30
12–20 *IN Indicator Array And Element Usage 12–31
12–21 *IN Indicator Array And Element Usage 12–32
13–1 File Description specification for a primary sequential file -
Sequential file access 13–6
13–2 File Description specification for a primary sequential file -
Sequential access by key 13–7
xxv
Contents
13–3 File Description specification for a primary indexed file - Sequential

access within limits 13–8
13–4 File Description and Extension specifications for a primary indexed
file - Sequential access within limits 13–11
13–5 Limits Processing - SETLL operation code usage 13–12
13–6 Random access by relative record number 13–14
13–7 Random access by key 13–16
13–8 Random access by addrout file 13–19
13–9 Random and sequential access using a full-procedural file 13–20
13–10 Creating a sequential file 13–21
13–11 Creating an indexed file 13–23
13–12 Adding records to a sequential file 13–24
13–13 Adding records to an indexed file 13–26
13–14 Updating records in an indexed file 13–27
13–15 Deleting records from an indexed file 13–28
13–16 Declaring matching record fields 13–30
13–17 Using OR operation in an Input specification 13–31
13–18 Matching record fields and field-record-relation indicators 13–31
13–19 Matching record fields with field-record-relation indicators 13–31
13–20 Matching record fields in primary and secondary files 13–36
13–21 Multikey file access 13–38
14–1 Sample Report Program using Spacing and Skipping 14–6
14–2 Sample Report Program using an Overflow Indicator 14–9
14–3 Sample Output from Report using an Overflow Indicator 14–10
14–4 Sample Report Program using Fetch Overflow 14–12
15–1 Migration RPG Program using a compile-time table 15–2
15–2 Table Input Record 15–5
15–3 Related Tables - Multiple entries per record 15–5
15–4 Related Tables - Single entry per record 15–6
15–5 Extension Specification to define a compile-time table 15–8
15–6 Extension Specification to define compile-time related tables 15–9
15–7 Definition of a Pre-execution-Time Table 15–9
15–8 Single table LOKUP 15–10
15–9 Related table LOKUP 15–12
15–10 Program table LOKUP 15–12
15–11 LOKUP using a sequenced table 15–13
15–12 Program to temporarily update a table 15–14
15–13 Updating a pre-execution-time table 15–14
15–14 Outputting a table 15–15
15–15 Program using compile-time arrays 15–17
15–16 Array Input Record 15–19
15–17 Related arrays defined using multiple entries per record 15–19
15–18 Related arrays defined using a single entry per record 15–21
15–19 Compile-time array 15–23
15–20 Execution-time array load from data file 15–25
xxvi
Contents
15–21 Execution-time array load from data file 15–25

15–22 Program using execution-time arrays 15–28
15–23 Array LOKUP 15–30
15–24 Array LOKUP with starting position 15–30
15–25 Program using LOKUP on an array 15–31
15–26 Program using MOVEA on an array 15–32
15–27 Updating a pre-execution-time array 15–33
15–28 Writing an execution-time array 15–34
15–29 Writing individual array elements 15–34
16–1 Input field redefined by subfields 16–4
16–2 Using a data structure to define multiple input records 16–5
16–3 Input fields reorganized by a data structure 16–6
16–4 Local data area data structure 16–6
16–5 Accessing the LDA via SUBR21 16–7
16–6 WORKSTN Information Data Structure 16–8
17–1 Alternate Sequence Table 17–3
17–2 File Translation Parameter Records 17–6
18–1 Sample Migration RPG Program using SPECIAL Device Files 18–6
18–2 SPECIAL Device Subroutine TESTSBR100 18–10
18–7 Report Generated by the Sample Migration RPG Program
SPCDEV 18–19
19–1 CALL and PARM Opcode Usage - Example 1 19–3
19–2 EXTRN, Use of Underscore in Subprogram Name 19–4
19–3 EXTRN, CALL, and FREE Opcode Usage 19–5
19–4 FREE Opcode Use 19–6
19–5 CALL and PARM Opcode Usage - Example 2 19–10
19–6 PLIST and *ENTRY PLIST Usage 19–11
19–7 RETRN Opcode Use 19–13
19–8 RPG Calling Program - CALL.RPG 19–14
19–9 RPG Subprogram - LFTJST.RPG 19–15
19–10 Commands Used to Build CALL Program 19–16
19–11 RPG Calling Program - PASS1.RPG 19–17
19–12 Macro-32 Interface Module - PASS1M.MAR 19–18
19–13 COBOL Subprogram - PASS1C.COB 19–19
19–14 Commands Used to Build PASS1 Program on a VAX System 19–19
19–15 Commands Used to Build PASS1 Program on an Alpha or Integrity
System 19–19
20–1 RPG Program Calling External Subroutine 20–2
20–2 Sample Macro-32 External Routine 20–3
21–1 Compile Qualifier (U) specification 21–3
21–2 /COPY statement layouts 21–3
xxvii
Contents
21–3 /COPY statement usage 21–4

21–4 File Description specification modification 21–5
21–5 Input field modification 21–6
B–1 Compiling and linking a CONSOLE program B–7
FIGURES
1–1 Flowchart of Basic RPG Logic Cycle 1–5
1–2 Detailed RPG Logic Cycle Flowchart 1–8
10–1 Format of a Character String 10–2
10–2 Address of a String 10–2
10–3 Word Data Type 10–4
10–4 Longword Data Type 10–4
10–5 Packed-decimal Data Type 10–6
10–6 Zoned-Decimal Data Type (123+) 10–8
10–7 Trailing Numeric Data Type (123-) 10–8
10–8 Zoned-Decimal Data Type (123-) 10–8
11–1 Fixed-Length Descriptor Format 11–99
13–1 Sequential File Organization 13–3
13–2 Relative File Organization 13–4
13–3 Indexed File Organization 13–4
13–4 Index Key Value 13–5
13–5 Sequential File Access Within Limits 13–9
13–6 Creating an Addrout File 13–17
13–7 Using Matching Fields For Multifile Processing 13–33
19–1 Fixed-Length Descriptor Format 19–8
TABLES
2–1 Column 6 (RPG Specification Identification Codes) 2–3
3–1 Column 7 (Comment or Compiler Directive) 3–2
3–2 Column 15 (DEBUG Option) 3–2
3–3 Column 18 (Currency Symbol) 3–3
3–4 Column 19 (Date Format Code) 3–3
3–5 Column 20 (Date Edit Code) 3–4
3–6 Column 21 (Inverted Print Code) 3–5
3–7 Column 26 (Alternate Collating Sequence) 3–5
3–8 Column 43 (File Translation Code) 3–6
3–9 Column 60 (Zoned-decimal output) 3–6
4–2 Column 15 (File Type) 4–3
4–3 Device Types and File Types 4–4
4–4 Column 16 (File Designation) 4–4
4–5 Column 17 (End-of-File) 4–6
xxviii
Contents
4–6 Column 18 (Sequence Code) 4–7

4–7 Column 19 (File Format) 4–7
4–8 Columns 24 - 27 (Record Length) 4–8
4–9 Column 28 (Processing Mode) 4–9
4–10 Modes of Processing for Sequential Files 4–10
4–11 Modes of Processing for Relative Files 4–11
4–12 Modes of Processing for Indexed Files 4–12
4–13 Modes of Processing for Printer Files 4–13
4–14 Modes of Processing for Workstation Files 4–13
4–15 Modes of Processing for Record Address Files 4–13
4–16 Modes of Processing for KEYBORD Files 4–14
4–17 Modes of Processing for SPECIAL Files 4–14
4–18 Columns 29 - 30 (Key Length) 4–15
4–19 Column 31 (Record Address Type) 4–15
4–20 Valid Combinations of Entries in Columns 28 and 31 for Primary,
Secondary, and Demand Files 4–16
4–21 Valid Combinations of Entries in Columns 28 and 31 for Chained
Files 4–16
4–22 Valid Combinations of Entries in Columns 28 and 31 for
Full-Procedural Files 4–16
4–23 Column 32 (File Organization) 4–17
4–24 Columns 33 - 34 (Overflow Indicator) 4–17
4–25 Columns 35 - 38 (Key Start Location) 4–18
4–26 Column 39 (Extension Code) 4–18
4–27 Columns 40 - 46 (Device Code - Standard Migration RPG Device
Types) 4–19
4–28 Columns 40 - 46 (Device Code - Supported Migration RPG Device
Types) 4–19
4–29 Column 53 (Continuation Lines) 4–20
4–30 DISK File Continuation Option 4–21
4–31 SPECIAL Device File Continuation Option 4–22
4–32 WORKSTN File Continuation Options 4–23
4–33 Column 66 (File Addition) 4–24
4–34 Columns 68 - 69 (Alternate Key) 4–24
4–35 Columns 71 - 72 (File Conditioning Indicator) 4–25
4–36 Column 73 (File Sharing) 4–26
4–37 Column 74 (No Deferred Write) 4–27
5–2 Columns 11 - 18 (From-File Name) 5–2
5–3 Columns 19 - 26 (To-File Name) 5–3
5–4 Columns 27 - 32 (Array or Table Name - Primary Entry) 5–4
5–5 Column 33 - 35 (Number of Entries Per Record) 5–4
5–6 Columns 36 - 39 (Number of Entries in a Table or Array) 5–5
5–7 Columns 40 - 42 (Length of Entry - Primary Entry) 5–6
5–8 Column 43 (Data Format - Primary Entry) 5–7
5–9 Column 44 (Decimal Positions - Primary Entry) 5–7
xxix
Contents
5–10 Column 45 (Sequence - Primary Entry) 5–7

5–11 Columns 46 - 51 (Array or Table Name - Alternate Entry) 5–8
5–12 Columns 52 - 54 (Length of Entry - Alternate Entry) 5–9
5–13 Column 55 (Data Format - Alternate Entry) 5–9
5–14 Column 56 (Decimal Positions - Alternate Entry) 5–10
5–15 Column 57 (Sequence - Alternate Entry) 5–10
6–2 Columns 7 - 14 (File Name) 6–2
6–3 Columns 15 - 17 (Form Length) 6–2
6–4 Columns 18 - 19 (Form Length Flag) 6–2
6–5 Columns 20 - 22 (Overflow Line Number) 6–2
6–6 Columns 23 - 24 (Overflow Line Flag) 6–3
7–3 Columns 15 - 16 (Sequence) 7–3
7–4 Column 17 (Sequence Number) 7–4
7–5 Column 18 (Option) 7–4
7–6 Columns 19 - 20 (Record-Identifying Indicator) 7–5
7–7 Columns 21 - 24, 28 - 31, 35 - 38 (Position) 7–7
7–8 Columns 25, 32, 39 (Not) 7–7
7–9 Columns 26, 33, 40 (Character, Zone, or Digit) 7–8
7–10 Columns 27, 34, 41 (Comparison Character) 7–8
7–11 Columns 14 - 16 (AND and OR Relationships) 7–8
7–12 Column 43 (Data Format) 7–9
7–13 Columns 44 - 47 (Field From Location) 7–10
7–14 Columns 48 - 51 (Field To Location) 7–10
7–15 Column 52 (Decimal Positions) 7–10
7–16 Columns 53 - 58 (Field Name) 7–11
7–17 Columns 59 - 60 (Control break Indicator) 7–13
7–18 Columns 61 - 62 (Matching Fields) 7–14
7–19 Columns 63 - 64 (Field-Record-Relation Indicator) 7–16
7–20 Columns 65 - 70 (Field Indicators) 7–17
7–21 Field Indicator Definitions 7–17
8–2 Columns 7 - 8 (Control Level) 8–2
8–3 Columns 9 - 17 (Conditioning Indicators) 8–3
8–4 Columns 18 - 27 (Factor 1) 8–4
8–5 Columns 28 - 32 (Operation Code) 8–5
8–6 Columns 33 - 42 (Factor 2) 8–6
8–7 Columns 43 - 48 (Result Field) 8–7
8–8 Columns 49 - 51 (Field Length) 8–8
8–9 Column 52 (Decimal Positions) 8–9
8–10 Column 53 (half-adjust) 8–9
8–11 Columns 54 - 59 (Resulting Indicators) 8–10
xxx
Contents

9–3 Columns 14 - 16 (AND/OR) 9–2
9–4 Column 15 (Record Type) 9–3
9–5 Columns 16 - 18 (ADD/DEL) 9–4
9–6 Column 16 (Fetch Overflow or Release) 9–5
9–7 Column 17 (Space Before) 9–6
9–8 Column 18 (Space After) 9–6
9–9 Columns 19 - 20 (Skip Before) 9–7
9–10 Columns 21 - 22 (Skip After) 9–8
9–11 Columns 23 - 31 (Output Indicators) 9–10
9–12 Columns 32 - 37 (Field Name) 9–12
9–13 Output EXCPT Names 9–16
9–14 Column 38 (Edit Codes) 9–17
9–15 Edit Codes and Examples 9–18
9–16 Column 39 (Blank After) 9–19
9–17 Columns 40 - 43 (End Position in Output Record) 9–20
9–18 Column 44 (Output Data Format) 9–21
9–19 Columns 45 - 47 (Constant or Edit Word) 9–23
9–20 Columns 45 - 70 (Edit Words) 9–25
9–21 Using Edit Words to Display Negative Numbers 9–27
10–1 Zoned-decimal representation of digits 10–7
11–1 Examples of MOVE Operation Results 11–84
11–2 Results of MOVEA operation in Example 11–45 11–87
11–5 Descriptor Types and Use 11–99
11–6 Default Descriptor Types 11–100
12–1 Available Indicators 12–1
12–2 Program Defined Indicators 12–2
12–3 Record Identifying Indicators 12–4
12–4 AND and OR Relationships 12–6
12–5 Field Indicators 12–8
12–6 Field Indicators 12–10
12–7 Command Key Indicators 12–19
13–1 Matching Field Lengths 13–30
13–2 Matching Primary and Secondary File Field Values 13–32
13–3 Matching Field Values 13–36
13–4 Processing Records with Matching Fields 13–37
15–1 Array Element Values 15–27
15–2 Array Elements in Calculations 15–27
16–1 Data Structure Specification Layout 16–1
16–2 Data Structure Subfield Specification Layout 16–2
17–1 Alternate Sequence Table Record Layout 17–2
17–2 File Translation Parameter Record Layout 17–5
18–1 File Specification 18–2
xxxi
Contents
18–2 File Continuation Specification Description 18–2

18–3 File Control Data Structure 18–3
18–4 Array Control Data Structure 18–4
18–5 Return Condition Codes 18–4
18–6 File Type Update - Operation Codes 18–5
18–7 File Type Combined - Operation Codes 18–5
19–1 Descriptor Types and Use 19–8
19–2 Default Descriptor Types 19–9
21–1 Compile Qualifier (U) Specification Layout 21–2
21–2 Input Field Modifier Entries 21–6
21–3 Auto Report Specification Limitations 21–8
B–1 Rules for Coding CONSOLE Device File Description Specification B–2
B–2 Rules for Coding CONSOLE Device File Input Record
Specifications B–4
B–3 Rules for Coding CONSOLE Device File Input Specifications B–6
B–4 CONSOLE Device File Display Formats B–8
B–5 Rules for Coding CRT File Description Specification B–11
B–6 Rules for Coding CRT Output Specification B–12
B–7 Rules for Coding CRT Output Field Specifications B–13
B–8 Rules for Coding KEYBORD Device File Description Specification B–14
B–9 Rules for Coding KEYBORD Calculation Specification for a KEYnn
Operation B–16
B–10 Rules for Coding KEYBORD Calculation Specification for SETnn
Operation B–18
xxxii
Preface
This manual describes the features, uses, constructs, and syntax of the
Migration RPG programming language on OpenVMS systems.
Intended Audience
The Migration RPG User’s Guide is intended for programmers who are
familiar with computer concepts and the RPG II programming language.
Migration RPG was originally developed for users moving from IBM®
System/3X platforms to Digital Equipment Corporation VAX systems and
was modeled after IBM System/36™ RPG II. It has since been enhanced
beyond the scope of IBM System/36 RPG II to provide a more generic
and complete RPG environment under the OpenVMS operating system.
Migration RPG still maintains complete IBM System/36 compatibility.
This manual is designed to be used as a reference manual.
Conventions Used In This Manual

The following conventions are used in this manual to describe commands
and keystrokes:
Convention Meaning
CTRL/X This sequence indicates that the user must hold down
the key labeled CTRL while pressing another key.
PF1 + X This sequence indicates that the user must first press
and release the key labeled PF1, then press and release
another key.
RETURN or <RETURN> A keyname is shown enclosed or within angle brackets
to indicate a key on the keyboard to be pressed by the
user.
A vertical ellipsis indicates the omission of items from
. a code example or command format. The items are
. omitted because they are not important to the topic being
. discussed.
() In format descriptions, parentheses indicate that, if more
than one option is chosen, the options must be enclosed
in parentheses.
[] In format descriptions, optional parameters in a
command are denoted by square brackets. If a
command delimiter, such as a comma or slash, is
included within the square brackets, it is also optional. If
the delimiter is outside the square brackets, it is required
in the command line. Never include the square brackets
in the command line.
BOLDFACED TEXT Commands entered by the user at the terminal are
printed in boldfaced type.
xxxiii
Preface
Associated Documents
Additional information concerning Migration RPG can be found in the
following manuals:
• Migration RPG User’s Guide
• Migration RPG Screen Format Reference Manual
Additional information concerning the use of OpenVMS with Migration

RPG programs can be found in the following manuals:
• Guide to Using OpenVMS Command Procedures
• OpenVMS Convert and Convert/Reclaim Utility Manual
• OpenVMS DCL Concepts Manual
• OpenVMS DCL Dictionary
• Guide to OpenVMS File Applications
• OpenVMS File Definition Language Facility Manual
• Guide to OpenVMS Files and Devices
• OpenVMS Librarian Utility Manual
• OpenVMS Linker Utility Manual
• Guide to Using OpenVMS
• Introduction to OpenVMS
• OpenVMS Sort/Merge Utility Manual
Additional information concerning the conversion of IBM® System/36™

RPG applications to an OpenVMS system can be found in the following
manuals:
• OpenVMS S/3X Conversion Assistance Manual
• OpenVMS S/3X Conversion Tools User’s Guide
Additional information concerning RPG programming can be found in the

following books:
• Computer Programming - RPG II, by Gary B. Shelly & Thomas J.
Cashman
• RPG and RPG II Programming; Applied Fundamentals, A Job
Approach to Learning, by Willian E. Bux & Edward C. Cunningham
• RPG II Programming, by Edward L. Essick
A special thanks to Kathy T. Parker and Gail Claremont for their

herculian efforts to compile and proof this manual.
xxxiv
1 Understanding the Migration RPG Logic Cycle
1.1 Migration RPG Overview

Migration RPG is a programming language that provides a convenient
and efficient means of preparing a wide variety of interactive and batch
programs. The language is well suited to performing commercial data
processing tasks. Migration RPG is an extended implementation of the
RPG II language that was developed by IBM; it includes extensions for
integration with the OpenVMS architecture. Migration RPG runs under
the OpenVMS operating system and consists of an RPG compiler, screen
format compiler, RPG language editor, and run-time support utilities.
For convenience, Migration RPG is referred to as RPG throughout this
manual.
RPG is a nonprocedural language; that is, every program compiled by
the Migration RPG compiler executes according to a fixed plan. Unlike a
procedural language, such as COBOL, the logic of this plan is not supplied
by the programmer, but is built into the compiler. This built-in logic is
called the RPG logic cycle. The execution of a RPG program consists of a
number of iterations of the logic cycle.
1.2 RPG Program Specifications

A programmer provides directions to an RPG program using RPG program
specifications. Specifications are the column-oriented instructions which
define input and output formats, arithmetic processes, and special
operations to be performed depending on the data input and desired
output. There are seven different specification types. They are:
• Control Specification
• File Description Specification
• Extension Specification
• Line Counter Specification
• Input Specification
• Calculation Specification
• Output Specification
There are also three types of specifications which can be used to define
RPG workstation screens and Menu and Prompt Utility screens. These are
the Screen Specification (S), Help Specification (H), and Field Description
Specification (D). These specifications are covered in the Migration RPG
Screen Format Reference Manual.
1–1
Understanding the Migration RPG Logic Cycle
Each specification is structured in an 80-column format, with the

specification type indicated by a character in column 6; the columns
are grouped into fields according to the purpose of the specification.
Specifications are grouped together by type and must appear in a fixed
order in an RPG program. The following sections briefly describe each
specification and indicate the order in which the specifications must
appear in a program.
1.2.1 Control Specification - H

The Control Specification, often referred to as the Header Specification,
provides the following general program information:
• Date format for the program
• Debug switch for the program
• Alternating Collating Sequence for the program
1.2.2 File Description Specification - F

The File Description Specification defines all of the files and devices an
RPG program accesses. For RPG programming purposes, it is easiest to
think of device access as another form of file access. The File specification
provides the following information to the program:
• File name
• File access information
• Record size
• Device associated to the file
• Conditioning by external indicators
1.2.3 Extension Specification - E

The Extension Specification describes all record address files, table
files, arrays and tables used by a program. They contain the following
information:
• Name of file, array or table
• Number of entries in an array or table record
• Total number of entries in an array or table
• Length and data type of elements in an array or table
1–2
1.2.4 Line Counter Specification - L

The Line Counter Specification is used to define the number of lines on a
report page, should this number vary from the default of 66. The following
information is provided to the compiler:
• Number of lines per page
• Overflow line on page
1.2.5 Input Specifications - I

Input Specifications describe the record layouts of input files. They also
define data structures and their elements. They include the following
information:
• Input file name
• Record identification information
• Record-identifying, control break, matching-record, and field indicators
• Data field definitions
• Data structure definitions
1.2.6 Calculation Specification - C

Calculation Specifications describe the operations which can be carried
out in an RPG program. Calculation specifications can control I/O
operations and are divided into detail and total time sections. Calculation
specifications include the following information:
• Operation code defining the function to be performed
• Conditioning and resulting indicators
• Detail time calculation section
• Total time calculation section
• Subroutine section
• Data field and literal definitions
• External calls and call parameters
1.2.7 Output Specification - O

Output Specifications describe the layout of report, output, and update
files, records, and fields. They also provide mechanisms to allow the
programmer to control output of data. They include the following
information:
• Output file names
• Output record and field definitions
• Conditional control for output of records and fields
1–3
• Skipping and spacing control for report files

• Format control of output data elements
A chapter has been devoted to each RPG specification to provide a more

detailed explanation of each specification.
The fixed RPG logic cycle was designed specifically to accommodate the
sequence of operations needed to generate most common business reports
and file maintenance functions. However, the fixed nature of the RPG
logic cycle does not prevent the programmer from controlling the set of
functions performed for each input record and the sequence and timing
of these functions. This control is provided by the use of indicators in
the Input, Calculation, and Output specifications, and operation codes
(opcodes) in the Calculation specifications.
For example, by setting various indicators on or off when certain
conditions occur, control of the sequence of program execution within
the phases of the normal logic cycle can be affected. See Chapter 12,
Using Indicators, for more information on indicators. Opcodes such as
CALL, GOTO, READ, and EXCPT can be used to add additional flexibility
to the RPG logic cycle. See Chapter 11, Operation Codes, for descriptions
of the RPG opcodes.
To write effective RPG programs and take advantage of the flexibility and
control provided with the RPG logic cycle, it is important to thoroughly
understand the structure and timing characteristics of the cycle, and to
recognize both RPG’s special capabilities and its limitations.
There are 11 fundamental operations that are performed during the
operation (and reiterations) of the RPG logic cycle, as shown in Figure 1–1,
Flowchart of Basic RPG Logic Cycle. These steps are described in the
accompanying keyed list.
1–4
Figure 1–1 Flowchart of Basic RPG Logic Cycle
START
(1)
Perform heading and

detail output.
(2)
Turn off control

break and record
ID indicators.
(3)
Read a record.
(4) (5)
Has a Yes Set on appropriate

control break control break
occurred? indicators.
No
(6)
Yes
First cycle?
No
(7)
Total time calcs.
(8)
Total time output.
(9)
Is the Yes
last record End of job
indicator
on?
No
(10)
Make record read in

step 3 available to
the program.
(11)
Detail calcs.
1–5
Key to Figure 1–1, Flowchart of Basic RPG Logic Cycle:

During program startup, or the first cycle, several initialization tasks are
accomplished. Files are opened; the local data area is loaded; the system
date is obtained from the system; and counters, tables, and arrays are
initialized. RPG programs actually start the program cycle in the output
section. While this might seem odd at first glance, it is done to give the
programmer the opportunity to output heading information in reports
before the first record is read and processed.
Steps in the Basic RPG Logic Cycle

1 The program carries out heading and detail output, which can be
controlled by indicators. Heading and detail specifications contain an
H or D in column 15 of the output specification.
2 All control break and record-identifying indicators are set off.
3 A record is read and the appropriate record-identifying indicator is set
on.
4 If the control field of the record just read is different from the control
field of the previous record, a control break occurs. If no control break
has occurred, the program branches to step 6.
5 When a control break occurs, the appropriate control break indicator
is set on, plus all lower control break indicators, except L0 which is
always on.
6 If this is the first cycle, the program branches to step 9.
7 If control level indicators (L1 - L9) are on, total time calculations
are performed. Total time calculations are indicated by control break
indicators in columns 7 - 8 of the Calculation specifications.
8 Total time output is performed. Output specifications with a T
in column 15 are processed if the appropriate indicator specified
conditions are satisfied.
9 The program checks the last-record indicator. If it is on, the program
enters the last cycle and ends.
10 The data read during step 3 is made available to the program.
11 The program performs the detail level calculations on the data read
in step 3. Detail level calculations consist of Calculation specifications
which do not have a control break indicator (L1 - L9) specified in
columns 7 - 8.
Upon detecting the last-record indicator, the program enters the last cycle,
does one-time cleanup work, including total calculations and total output
operations, and ends.
1–6
1.3 The RPG Logic Cycle

Every RPG program follows the same sequence of execution steps which
form the normal logic cycle. Special operations, such as matching record
fields, chaining, overflow processing, and look-ahead processing, are all
handled within the flow of the logic cycle.
In standard RPG programs (programs which do not deliberately disrupt
the cycle) the RPG logic cycle is executed once for each primary input
record. The logic cycle consists of the following three steps, performed in
order for each record:
1 Inputting a record
2 Performing calculations
3 Outputting one or more records
Each cycle begins when a new record is input and ends just before the
next record is input. The RPG coding specifications determine the range
and type of functions performed during each cycle. During the calculation
and output steps within each cycle, there are two distinct timing phases:
• Total time operations are performed on summary data accumulated
from a group of related records.
• Detail time operations are performed on individual records.
Sections 1.4.2.1 and 1.4.2.2 describe total time and detail time
characteristics and operations.
The first and last cycles of an RPG program are different from the rest of
the cycles in the program. They are responsible for program startup and
shutdown operations. These cycles are described in detail in the sections
1.4.1 and 1.4.3.
1.4 The RPG Logic Cycle in Detail

This section consists of a detailed, annotated flowchart describing the
RPG logic cycle. The following subsections describe specific parts of the
RPG cycle, such as the first cycle, last cycle, total time, and detail time in
greater detail.
1–7
Figure 1–2 Detailed RPG Logic Cycle Flowchart
START
(1) (8)
Turn RT indicator off. Turn off 1P indicator.

Turn off control break
indicators (L1 − L9)
Turn off record identify−
(2) ing indicators.
(2a) Turn off overflow indic−
Yes cators (OA − OG, OV).
Program Active? Get
parameters
(9)
No
(3) Last No
record ind.
Initialize fields, data (LR) on?
structures, tables, and
arrays.
Load local data area. Yes
Open files. (10)
Turn on all
(4) control break
indicators
Perform header output. (L1 − L9).
Perform detail output.
Perform overflow output.
This step is the return
point for a normal RPG
cycle. Goto step 25
(5) (11)
*GETIN
Halt No
indicator(s) Return No
on? indicator (RT)
on?
Yes
(5a) Yes
(12)
Issue message
to user. Return
parameters
(5c)
Clear (13)
halt
ind. RETURN
(5b)
Cancel?
No (14)
Yes No Primary Yes

(6) file present?
Prepare to terminate the

program.
(7) Continue with

Goto step 25 step 15
Goto step 33
Figure 1–2 Cont’d on next page
1–8
Figure 1–2 (Cont.) Detailed RPG Logic Cycle Flowchart
(15) (23)
On first cycle, retrieve

a record from the primary Have No
and all secondary files. control fields
changed?
On all other cycles,
retrieve a record from
the last file processed, Yes
if required. (24)
Set on appropriate
control break indicators
(16) (L1 − L9).
Read Yes
being forced?
(25)
No No
LR on?
(17)
Matching No
fields (MR) Yes
present?
(26)
Have
Yes LR total Yes
(18) time operations
taken place
Match fields routine. ?
No
(27)
(19) (19a) *CANCL
End Total time calculations.
of job Yes Set on
conditions L1 − L9,
met? and LR (28)
Total time output.

No
(20) (29)
Identify record and set No

on record ID indicators. LR on? Goto step 36
(33)
(21) Yes
Was (30) Close all files.
a record No
identified? Process halt indicators.
(34)
(31) If present, prepare

Yes parameters for
Output tables and arrays. return to calling
(22) program.
Control− No (32)
break indicators (35)
specified? Output local data area
and external indicators. Set return
Yes status and
exit program.
1–9
Figure 1–2 (Cont.) Detailed RPG Logic Cycle Flowchart
(36)
Overflow No
indicators on?
Yes
(37)
Overflow output routine.
(38)
Set MR indicator on or off.
(39)
Make data available from

last record read.
Set field indicators.
(40)
Look−ahead No
fields
specified?
Yes
(41)
Look−ahead routine.
(42) *DETC
Process detail
calculations.
Goto step 4
Key to Figure 1–2, Detailed RPG Logic Cycle Flowchart

The following list describes in detail each step in the RPG logic cycle.
First cycle processing
1 The return indicator (RT) is turned off. The RT indicator is used by
RPG subprograms.
2 RPG checks if this is the first invocation of the program. If it is, RPG
continues with step 3. If it is not (meaning that it is a subprogram
which has already been called at least once and has not been re-
initialized), PARM statements in the *ENTRY PLIST, which specify
fields in the result field and factor 1, are processed and the program
jumps to step 5.
1–10
3 Program initialization occurs. Initialization consists of retrieving date

information (UDATE, UDAY, UMONTH, UYEAR, $UDATE, $UDAY,
$UMNTH, and $UYEAR), obtaining the external indicators (U1 - U8)
and local data area, opening all files, initializing all fields and data
structures, and loading all pre-execution-time tables and arrays. If
this is an RPG subprogram using a *ENTRY PLIST, data is moved
from the result field to factor 1 in the PARM statements which specify
both fields.
Note: The $UDATE, $UDAY, $UMNTH, and $UYEAR reserved words
are supplied to provide backward compabitility with 6-digit
non-Year 2000 compliant dates. See the Migration RPG Year
2000 Compliance Guide for more information concerning these
fields.
Normal cycle processing
4 RPG writes heading and detail lines (identified by H or D in column 15
of the Output specification). If conditioning indicators are specified, the
conditions for the indicator must be satisfied before the specification
will be output. If fetch overflow logic is specified and the overflow
indicator is on, the appropriate overflow lines are output. If the
1P indicator is on (during the first cycle only), RPG prints all lines
conditioned by it. RPG executes this step at the beginning of the
program so that heading lines can be printed before the first data
record is read.
5 RPG checks whether any halt indicators (H1 - H9) are on. If a
halt indicator is set and the program is running in an interactive
environment, the user is prompted to enter one of the following
options:
• CONTINUE - This option tells the program to clear the halt
indicator and continue processing normally.
• EXIT - This option tells the program to terminate immediately.
• KILL - This option tells the program to terminate immediately.
The response to the CONTINUE, EXIT, KILL prompt can be
abbreviated to a single character: C, E, or K.
For all intents and purposes, the EXIT and KILL option do the same
thing in the Migration RPG processing environment. They cause a
controlled shutdown of the program and, depending upon the compiler
options selected, may return a warning status when the program exits.
Both the EXIT and KILL prompts are supported by Migration RPG to
offer a level of compatibility with non-OpenVMS versions of RPG.
The program will cycle through step 5 until all nine halt indicators
have been checked or the user selects the EXIT or KILL option at the
halt indicator prompt.
If the program is running as a batch job and a set halt indicator is
encountered at this step, the program will terminate immediately,
returning an error status. See Chapter 12, Using Indicators for more
information concerning the use of halt indicators.
1–11
If no halt indicators are set or if the user clears all set halt indicators
using the CONTINUE option, the program jumps to step 8. If a halt
indicator is set and the program is running in batch mode, or the user
selects the EXIT or KILL options at the halt prompt, the program
proceeds to step 6.
The step also serves as the return point for a *GETIN operation at the
end of a INFSR subroutine.
6 The program is being terminated due to a halt. Image termination
processing to handle the halt condition begins at this step.
7 The program jumps to step 33 to complete the halt-induced
termination.
8 Control break indicators (L1 - L9), first page indicator (1P), and all
record-identifying indicators are set off. Overflow indicators (OA
through OG, and OV) are also set off unless they were set on in the
previous cycle during detail calculations or detail output. All other
types of indicators that are on remain on.
9 The last record indicator (LR) is checked. If it is on, the program
proceeds to step 10 and begins last cycle processing. If it is not on, the
program jumps to step 11.
10 As the first step in last cycle processing, all control break indicators
(L1 - L9) are turned on. The program then jumps to step 25.
11 The return indicator (RT) is checked. If it is on, processing continues
with step 12, which will prepare for an immediate exit from the
program. If it is not on, the program jumps to step 14.
12 If the program contains a *ENTRY PLIST, contents of the fields
specified in factor 2 of the PARM statements are transferred to the
result field in preparation for passing the parameter information back
to the calling program.
13 The subprogram returns immediately to the calling program. Files,
fields, and indicators are left as they are currently set when a
subprogram exits in this fashion. If the subprogram is called again,
it will start up with all of these settings intact. The calling program
can initialize the subprogram before calling it again using the FREE
operation.
14 RPG determines whether a primary file was specified by the program.
If not, the program jumps to step 25.
15 On the first cycle, RPG reads a record from the primary input file and
each of the secondary files. On all other cycles, the program reads a
record from the last file processed, if required. If a record address file
is being used, the data retrieved from the record address file identifies
the record that is to be retrieved. If look-ahead fields are specified
in the last record processed, the record required may already be in
storage, meaning that no read will be necessary at this point.
16 If a FORCE instruction was processed during the previous cycle, the
program selects that file for processing. If a FORCE command is
processed, the program jumps to step 19, bypassing matching record
processing.
1–12
17 The program determines if matching fields have been specified. If they

are, the program continues with step 18; if not, the program jumps to
step 19.
18 The matching field routine takes control. It selects the next record
to process by matching field content between records. If a record
is processed out of sequence, the matching record routine issues
a halt and gives the user the option of bypassing the bad record
or terminating the program. See Section 13.11, Processing Files
with Matching Records, for more information on matching record
processing.
19 RPG determines if end-of-job conditions have been met and the last
record indicator (LR) should be turned on. End-of-job is signified when
all primary and secondary files with an E specified in column 17 of the
File specification are at end-of-file. If end-of-job conditions are met, the
last record (LR) and control break indicators (L1 - L9) are turned on
and the program jumps to step 25.
Step 19a serves as the return point for a *CANCL operation at the end
of a INFSR subroutine.
20 RPG identifies the next record to process and sets on the record-
identifying indicator. If a record cannot be identified, a halt is issued
and the user is prompted to continue or terminate the program.
21 RPG checks to determine that a record was successfully identified for
processing. If a record was not identified, the program jumps to step
25.
22 The program checks to see if control break processing has been
specified. If not, the program jumps to step 25.
23 RPG determines whether the record selected for processing has caused
a control break to occur. A control break occurs when the value in
the control field of the record being processed differs from the previous
value of the control field. If no control break has occurred, the program
jumps to step 25.
24 If a control break has occurred, RPG saves the contents of all
appropriate control fields. It then sets the appropriate control break
indicator (L1 - L9) on; at the same time, RPG sets all lower-level
control break indicators on.
Final cycle processing begins here. The final cycle steps are intermixed
with normal cycle steps.
25 The program checks to see if the last record indicator (LR) is on. If LR
is on, the program proceeds to last cycle processing. If LR is off, the
26 If last record processing is taking place, the program checks to see
if final cycle total time calculations need to be performed. If not, the
27 Total time calculations are performed. Calculation specifications with
control break indicators (L1 - L9) turned on in columns 7 - 8 are
processed.
1–13
28 Total time output is processed. Any Output specifications conditioned

by control break indicators (L1 - L9) are output at this time.
29 The program checks to see if the last record indicator (LR) is on. If
not, it jumps to step 36 and continues a normal cycle. If LR is on, the
program continues with step 30 and begins the final steps in the last
cycle.
30 Halt indicators are processed. If a halt indicator is on, the user
is prompted to enter the CONTINUE, EXIT, or KILL option. The
CONTINUE option will clear the halt indicator in question. The EXIT
or KILL options will allow the program to terminate with the halt
indicators set, causing the program to exit with a warning status.
31 Tables and arrays which have a file name specified in the Extension
specification (columns 19 - 26) are output.
32 External indicator settings and the contents of the local data area are
output.
33 All open data files are closed.
34 If the program contains a *ENTRY PLIST, contents of the fields
specified in factor 2 of the PARM statements are transferred to the
result field in preparation for passing the parameter information back
to the calling program.
35 The return status value is set and the program exits. If this is a
subprogram, the return status value will be used to indicate the exit
status of the subprogram to the calling program.
36 RPG determines whether any overflow indicators (OA through OG, or
OV) are on. If so, processing continues with step 37; otherwise, the
37 The overflow routine receives control. All output operations
conditioned by overflow indicators are processed.
38 The matching record indicator (MR) is set on or off. If the program
contains multiple files and the record to be processed is a matching
record, the indicator is set on. If not, the indicator is set off.
39 Data from the last record read is made available to the program. Field
indicators (columns 65 - 70 in the Input specification) are set at this
time.
40 If look-ahead fields have been specified, the program continues with
step 41; otherwise, it jumps to step 42.
41 The look-ahead routine is run. The look-ahead record is read and
look-ahead fields are extracted from the record.
42 The program performs detail calculations. After the detail calculations
section has been completed, the program branches back to step 4 to
repeat the cycle.
Step 42 also serves as the return point for a *DETC operation at the
end of a INFSR subroutine.
1–14
1.4.1 The First Cycle

When program execution begins and before the first input record is
read, several one-time-only operations are performed. These operations
constitute the first cycle. Output control during the first cycle can be
accomplished using Output specifications conditioned by the first-page (1P)
indicator, and by using Output specifications with either no conditioning
indicators or with all negative conditioning indicators. (See Chapter 12,
Using Indicators, for more details on conditioning indicators.) The first
cycle is generally used to output initial headings for reports. During the
first cycle, RPG performs the following initialization operations:
• If a *ENTRY PLIST is present, the parameters are read into the
program.
• Obtains the current system date (UDATE, UDAY, UMONTH, UYEAR,
$UDATE, $UDAY, $UMNTH, and $UYEAR).
• Loads the local data area.
• Inputs external indicator settings (U1 - U8).
• Opens all files.
• Loads pre-execution time tables and arrays.
• Initializes page number counters.
• Prints heading and detail lines conditioned by the 1P indicator, by all
negative indicators other than the 1P indicator, and by no indicators.
• Bypasses total time calculations and output steps.
Although all iterations of the logic cycle (other than the first) include a
total time phase, RPG bypasses all total time calculations and total time
steps during the first cycle unless the last-record (LR) indicator is on.
Example 1–1 shows an output record using the 1P indicator to specify that
the associated specifications should only output during the first cycle.
Example 1–1 Example of first cycle output specifications
1 2 3 4 5
1234567890123456789012345678901234567890123456789012345678
OREPORT H 1P
O 35 ’SALES REPORT’
O UDATE 80 ’ / / ’
1.4.2 A Normal Cycle

A normal cycle in an RPG program can be defined as any cycle except
the first or the last. During a normal cycle, RPG performs the following
operations:
1 Outputs heading lines, if specified.
2 Outputs detail time information, if specified.
1–15
3 Reads an input record.

4 Performs total time calculations, if required.
5 Performs total time output, if required.
6 Checks the LR indicator; if it is on, the program terminates.
7 Processes the record read in step 3; performs all detail time
calculations.
Steps 4 and 5 constitute total time operations; steps 1, 2, and 7 constitute

detail time operations. These steps are discussed in more detail in the
following sections.
This list of steps in a normal cycle is an overview only. Figure 1.4 presents
a detailed description of the RPG logic cycle.
1.4.2.1 Total Time Processing

Total time processing is triggered by control breaks which occur when a
control break indicator (L1 - L9) is set. Control break indicators are set
when the data in a control break field is changed. Control break fields are
checked when a record is input.
During total time, RPG checks which control break indicators (L1 through
L9) are defined and the control field associated with each. (See Chapter 12,
Using Indicators, for details on using control break indicators.) For
example, in an application involving the generation of a monthly sales
report, total time calculations and output for total sales by region are
controlled by L8; total time processing for total sales by district office are
controlled by L7; and total time processing for total sales by salesperson
are controlled by L6. Example 1–2 illustrates how such a program might
be coded.
1–16
Example 1–2 Program using total time features
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
FSALESFILIPE F8000 80 DISK
FREPORT O F 80 PRINTER
*
ISALESFILAA 01
I 01 04 REGIONL8
I 05 08 DIST L7
I 09 38 SALNAM
I 39 44 SALEIDL6
I P 45 492SALES
.
.
.
C SALES ADD SALTOT SALTOT 92
.
.
.
CL6 SALTOT ADD DISTOT DISTOT 92
CL7 DISTOT ADD REGTOT REGTOT 92
CL8 REGTOT ADD GRAND GRAND 102
.
.
.
OREPORT T L6
O 20 ’Total for Sales Person:’
O SALNAM 51
O SALEID 60
O SALTOT B 80 ’$ , , . ’
OREPORT T L7
O 20 ’District Total’
O DISTOT B 80 ’$ , , . ’
OREPORT T L8
O 20 ’Regional Total’
O REGTOT B 80 ’$ , , . ’
OREPORT T L9
O 15 ’Grand Total’
O GRAND B 80 ’$ , , . ’
In example 1–2, the following steps take place during total time
processing. In referring back to the detailed logic cycle (figure 1–2),
this description of total time processing will be starting at step 22.
• If, after the input of a new record, RPG determines that the
salesperson identification number in the current record differs from
the salesperson identification number in the previous record, a control
break occurs and the indicator L6 is turned on. When the L6 indicator
is turned on, all lower control break indicators are turned on as well.
Thus, the L6 control break turns on indicators L1 - L6. During total
time processing, the program will perform all L1 - L6 total time
calculations and output specifications. In the example, these are the
accumulated total sales for the salesperson whose number was found
in the previous record.
• During another cycle, the region identifier field changes. This will turn
on control break indicators L1 - L8. In this case, all L1 - L8 total time
calculations and output will be performed. In the example, the total
time processing for salesperson (L6), district (L7), and region (L8) will
all take place due to the L8 control break.
1–17
• After the last input record in the file has been read, the last record
(LR) and all control break indicators are turned on. This is part of
last cycle total time processing. With indicators L1 - L9 on, all total
time calculations and output are performed. In the case of the sample
program, total time processing for the salesperson (L6), district (L7),
region (L8), and grand total (LR) will take place.
• During the normal RPG cycle, after control breaks have been processed
and total time processing takes place, detail time processing begins.
Detail time operations are for the record just read and are described in
the next section.
1.4.2.2 Detail Time Processing

During detail time, a program performs operations specified in the detail
Output specifications and detail calculation sections. Example 1–3
expands upon the total time example (1–2) by including some heading
and detail time Output specifications.
In example 1–3, the following steps take place during the detail cycle. In
referring back to the detailed logic cycle (figure 1–2, this description of the
detail processing cycle will be starting at step 42.
1 During processing of detail calculations, the total sales for the
salesperson are added to the sales total (SALTOT) accumulator field.
2 Header and detail output take place. In the example, if any of the
control break indicators were turned on during the previous cycle,
the associated heading (H in column 15) Output specifications will
be processed. Detail (D in column 15) Output specifications are then
processed. In the example, the sales for each salesperson will be
output at detail time.
3 All control break indicators are turned off and the next record is read.
4 If the record causes a control break, the appropriate control break
indicator (L1 - L9) is turned on, and total time calculations and output
are processed. In the example, sales totals are accumulated by district,
region, and grand total during the total time calculations. During
total time output processing, the total time (T in column 15) Output
specifications are processed and output if their associated control break
indicator is on.
5 The program processes detail calculations and begins the cycle again.
1–18
Example 1–3 Example of a program using detail time features
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
FSALESFILIPE F8000 80 DISK
FREPORT O F 80 PRINTER
*
ISALESFILAA 01
I 01 04 REGIONL8
I 05 08 DIST L7
I 09 38 SALNAM
I 39 44 SALEIDL6
I P 45 492SALES
.
.
.
C SALES ADD SALTOT SALTOT 92
.
.
.
CL6 SALTOT ADD DISTOT DISTOT 92
CL7 DISTOT ADD REGTOT REGTOT 92
CL8 REGTOT ADD GRAND GRAND 102
.
.
.
OREPORT H 1P
O 35 ’SALES REPORT’
O UDATE 80 ’ / / ’
OREPORT H L8
O 07 ’Region:’
O REGION 12
OREPORT H L7
O 15 ’District:’
O DIST 20
OREPORT H L6
O 20 ’Sales Person:’
O SALNAM 50
OREPORT D 01
O SALES 50 ’$ , , . ’
OREPORT T L6
O 20 ’Total for Sales Person:’
O SALNAM 51
O SALEID 60
O SALTOT B 80 ’$ , , . ’
OREPORT T L7
O 20 ’District Total’
O DISTOT B 80 ’$ , , . ’
OREPORT T L8
O 20 ’Regional Total’
O REGTOT B 80 ’$ , , . ’
OREPORT T LR
O 15 ’Grand Total’
O GRAND B 80 ’$ , , . ’
1–19
1.4.3 The Last Cycle

The last cycle is performed after all the records specified for processing
have been read from all primary and secondary files. When the last record
from the last file has been read, RPG sets on the LR indicator and all the
control break indicators (L1 through L9). It then performs the following
operations:
• Total time calculations.
• Total time output.
• Outputs any tables or arrays that have output files associated with
them.
• Outputs the local data area.
• Outputs external indicator settings (U1 - U8).
• Closes all files.
• If a *ENTRY PLIST is present, prepares the parameters for return to
the calling program
• Ends program execution.
In example 1–3, the following steps take place during the last cycle. In
referring back to the detailed logic cycle (figure 1–2), this description of
the last cycle will be starting at step 19.
• The input file being read is at end-of-file, so the last record indicator
(LR) and all control break indicators (L1 - L9) are turned on.
• Total time calculations and output are performed for the last time.
In the example, all of the total time calculations will be performed to
finalize the accumulation of sales totals. This information will then be
output during total time output. The grand total for all sales will also
be output at this time, as its output specifications are qualified by the
LR indicator.
• The data and report files are closed and normal program shutdown
procedures take place, terminating the program.
1–20
2 Migration RPG Program Specifications
Migration RPG is a column-oriented programming language. The column

positions and their entries on each programming line determine what type
of specification is being used and what types of functions the program will
perform.
The RPG programming language is broken up into 7 major specification
types. When compiled, each program specification tells the computer what
data to use, how to process it, and what to do with the results.
The following RPG program specifications are described in Chapters 3 - 9:
• Control
• File Description
• Extension
• Line Counter
• Input
• Calculation
• Output
Each specification description includes the following information:

• A brief explanation of the specification’s purpose
• The specification’s format
• A detailed explanation of each column
This chapter provides general information concerning all RPG program

specifications. It includes a description of the notation conventions for
Migration RPG program specifications, data fields that are common to all
specifications, and special instructions to the RPG language compiler.
2.1 Column Numbers

Since RPG is a column-oriented programming language, all instructions
used within the programming specifications must be placed in the
appropriate columns. As indicated in Example 2–1, all RPG coding
examples in this manual are headed with a set of column numbers to
assist the programmer in determining the correct positions for each entry.
2–1
Migration RPG Program Specifications
Two rows of digits identify column numbers, as shown in the following

example:
Example 2–1 Example of column numbers
1 2 3 4 5
1234567890123456789012345678901234567890123456789012345678
^
The arrow in the previous example points to column 43. The first line in
the column numbers contains the tens digits; the second line contains the
units digits.
2.2 Common Fields

This section describes fields that are common to all specifications.
2.2.1 Line Number

Columns 1 - 5 are used in all RPG programming specifications for line
numbers or comments. Entries in these columns are optional and can
be useful in checking the sequence of lines or highlighting areas where
a program has been modified. The RPG compiler ignores all entries in
columns 1 - 5 until it sees a double asterisk (**) in columns 1 - 2. A **
indicates the beginning of compile time array and table data. Compile
time array and table data must appear at the end of an RPG program.
Example 2–2 Line number usage
1 2 3 4 5
1234567890123456789012345678901234567890123456789012345678
*
0056 IWORKSTN NS 99 1 C
0057 I OR 01 1 C1
0058 I 2 41 NAME
NEW I NS 04 1 C4
NEW I 2 2 ANSWER
0059 I NS 05 1 C5
.
.
.
2.2.2 Specification Type

Column 6 is always used to identify the type of program specification being
used. Table 2–1 indicates the various specification types and the code used
in column 6 to represent them.
2–2
Table 2–1 Column 6 (RPG Specification Identification Codes)

Allowable
Entries Explanation
H Control specification
F File Description specification
E Extension specification
L Line Counter specification
I Input specification
C Calculation specification
O Output specification
2.2.3 Comments
If an asterisk is placed in column 7 of a specification line, the entire line
can be used as a comment line. Comment lines do not require an entry in
column 6.
Columns 75 - 80 can be used to write comments in all RPG program
specifications. The RPG compiler ignores entries in columns 75 - 80.
Several of the RPG specifications allow comments to begin in columns
preceding column 75. See each specification section to determine where
comments can begin.
Example 2–3 Comments in a program
1 2 3 4 5 6 7
12345678901234567890123456789012345678901234567890123456789012345678901234
*
F* INDICATOR USAGE
F*
F* 01 SCREEN IDPT01 ACTIVE
F* 02 SCREEN IDPT02 ACTIVE
F* 10 HARDCOPY NOT COMPLETE
F* 15 ON-KEEP SCANNING FOR QUESTION / OFF-QUESTION
*
FWORKSTN CP F 79 WORKSTN
FDIFFHISTIC F 96 96R DISK
FREPORT O F 132 132 OF PRINTER
*
E TABA 8 8 2 A CORRECT ANS TABLE
E #ERR 1 2 41 ERROR MESSAGES
E TST 50 50 1 CORRECT ANSWERS
E ANS 50 1 USER ANSWERS
2.3 Compiler Directives

Compiler directives can be included in an RPG source file to include
program modules into the main program at compile time or provide output
format directives concerning the optional program listing the compiler
generates. Compiler directives are discussed in detail in the Migration
RPG User’s Guide.
2–3
All compiler directives begin with a slash (/) in column 7. Compiler

directives can appear anywhere in an RPG program. Column 6 can be
blank when a compiler directive is specified. The following compiler
directives are recognized by Migration RPG:
• /COPY Directive
The /COPY directive is used to copy addition modules of RPG source
code into a program at compile time.
• /EJECT Directive
The /EJECT directive can be used to force form-feeds in a compiler
listing.
• /SPACE Directive
The /SPACE directive can be used to force blank lines in a compiler
listing. The number of blank lines to insert can be specified following
the /SPACE directive.
• /TITLE Directive
The /TITLE directive can be used to force a programmer specified
heading line to appear at the beginning of each page in a compiler
listing. Columns 14 - 74 can be used to insert the text which the
programmer wishes to display.
2–4
3 Control Specification (H)
The Control specification, often referred to as the Header specification,

is an optional specification which can be used to set general program
characteristics. If specified, the Control specification must be the first
compilable statement in a program. A Control specification is identified
by an H in column 6. The Control specification can be used to provide the
following information to the compiler:
• Specify that DEBUG is turned on or off
• Assign a currency symbol; the default currency symbol is a dollar sign
($)
• Specify the format of the system date and UDATE
• Specify the notation for numeric fields, edit codes, and UDATE
• Specify an alternate collating sequence
• Specify a translation file
If multiple Control specifications appear in a program, only the first one is

processed by the compiler. Subsequent Control specifications are ignored
and the compiler issues a warning message.
3–1
Control Specification (H)
3.1 Columns 1 - 5 (Line Number)

Columns 1 - 5 can be blank, specify a line number to assist in sequencing
the program specifications, or can be used as a comment. Columns 1 - 5
are ignored by the compiler.
3.2 Column 6 (Specification Identification)

Column 6 must always contain an H to identify a Control specification.
3.3 Column 7 (Comment or Compiler Directive)
Table 3–1 Column 7 (Comment or Compiler Directive)

Allowable
Entries Explanation
* Indicates that the line is a comment line. The line will be ignored by
the compiler.
/ Indicates that a compiler directive is to follow. Allowable compiler
directives are /COPY, /EJECT, /SPACE, and /TITLE. See
the Migration RPG User’s Guide for more information on the use of
compiler directives.
3.4 Columns 7 - 10 (No-op)

Columns 7 - 10 should be left blank if column 7 is not used to specify a
comment or compiler directive.
3.5 Column 15 (DEBUG Option)
Table 3–2 Column 15 (DEBUG Option)

Allowable
Entries Explanation
Blank The DEBUG option is turned off. Any DEBUG files and operations
within the program are ignored by the compiler.
1 The DEBUG option is turned on. Any DEBUG files and operations
within the program will be processed by the compiler. When the
program is run, it will output DEBUG information. See section
11.12.11 in Chapter 11, Operation Codes, for more information on
the DEBUG operation.
3–2

Columns 16 - 17 are not used by the Control specification. They should be
left blank.
3.7 Column 18 (Currency Symbol)

Use column 18 to specify a character other than the dollar sign ( $ ) to
represent the currency symbol.
Table 3–3 Column 18 (Currency Symbol)

Allowable
Entries Explanation
Blank Uses the dollar sign ( $ ) as the currency symbol. The dollar sign is
the default.
Any other The program will use this character, instead of the dollar sign ( $ ), as
character the currency symbol. The character entered here must be coded in
any fixed or floating edit word which is to use the currency symbol.
Any character except the following can be used as a currency
symbol:
• Zero ( 0 )
• Asterisk ( * )
• Comma ( , )
• Ampersand ( & )
• Decimal point or period ( . )
• Minus sign or dash ( - )
• Letter C
• Letter R
3.8 Column 19 (Date Format Code)

Column 19 is used to indicate the format in which the program should
expect the date contained in the UDATE field. It is also used to indicate
the format in which the TIME operation code should return the system
date.
Table 3–4 Column 19 (Date Format Code)

Allowable
Entries Explanation
Blank The default format of MM/DD/YYYY is to be used for UDATE and the
system date. If column 19 is blank and column 21 contains a D, I, or
J, the default date format is DD/MM/YYYY.
M The date format is to be MM/DD/YYYY. This is the default format.
D The date format is to be DD/MM/YYYY.
Y The date format is to be YYYY/MM/DD.
3–3
If the UDATE field is being fed a date that is not in MM/DD/YYYY format
and the appropriate entry has not been made in column 19, the program
will work with the wrong date. For example, if the date 1999/02/15, which
is in YYYY/MM/DD format, is entered in the UDATE field via the REX
Utility, but the program accessing the date was not compiled with a Y
in column 19, the program will read the date in MM/DD/YYYY format,
placing 19 in the month columns, 99 in the day columns, and 0215 in the
year columns. This will no doubt confuse the end users.
The same problem can occur when using the TIME operation code to
obtain the system date. By default, this date is returned in MM/DD/YYYY
format. If the programmer is expecting to work with a date in a different
format, the appropriate date format code must be specified in column 19.
3.9 Column 20 (Date Edit Code)

Column 20 can be used to specify the separator which is used in the edit
operation carried out on an output field with a Y edit code specified in
column 38. The Y edit code is used to specify the type of edit carried out
on a date field. The default edit uses the slash (/) as a separator in the
following format: nn/nn/nnnn.
Table 3–5 Column 20 (Date Edit Code)

Allowable
Entries Explanation
Blank A slash (/) is used as the date field separator when column 19
contains a blank or M and column 21 contains blank or D. A period
(.) is assumed when column 19 contains a blank, D, or Y, and
column 21 contains an I or J.
& A blank is used as the date field separator.
Any other The character entered serves as the date field separator.
character
Note: The format of the reserved word $UDATE, which supplies the date
in a 6-digit non-Year 2000 compliant form, is also determined by
the entries in columns 19 and 20. See the Migration RPG Year 2000
Compliance Guide for more information concerning the $UDATE
field.
3.10 Column 21 (Inverted Print Code)

The Inverted Print Code specifies the constants to be used in numeric edit
codes in the Output specifications. The Inverted Print Code allows output
to conform with a variety of notation conventions. For example, using the
United States decimal period convention for expressing a number with
a comma denoting thousands and a period denoting decimals, numeric
output would be edited as 12,345.67; the same value could be correctly
expressed as 12.345,67 using a decimal comma notation. Use column 21
to specify the notation convention used for numeric fields, edit codes, and
UDATE.
3–4
Table 3–6 Column 21 (Inverted Print Code)

Allowable
Entries Explanation
Blank Uses a period as the decimal notation and a comma as the
thousands separator in numeric literals and edit codes (for example,
1,234.56 and .56). Uses a slash ( / ) as the separator for the Y edit
code if columns 19 and 20 are blank (example, 02/16/92). Uses the
MMDDYYYY format for UDATE if column 19 is blank.
D This code produces the same results as the blank entry except that
the DDMMYYYY format is used for UDATE if column 19 is blank.
I Uses a comma as the decimal notation and a period as the
thousands separator in numeric literals and edit codes (for example,
1.234,56). Uses the DDMMYYYY format for UDATE if column 19
is blank. If columns 19 and 20 are blank, the period is used as the
separator for the Y edit code (example, 24.03.83).
J Uses the same format as the I option for UDATE, numeric literals,
and edit codes with the following exception: writes a zero to the left
of the comma when the field contains only a fraction (for example,
0,56).
3.11 Columns 22 - 25 (No-op)

Columns 22 - 25 are not used in the Control specification. They should be
left blank.
3.12 Column 26 (Alternate Collating Sequence)

Use column 26 to specify the collating sequence RPG will use for
alphameric comparisons, sequence checking, and matching fields. See
Chapter 17, "Specifying An Alternate Collating Sequence Or A Translation
File", for more information on creating user-defined collating sequences.
Table 3–7 Column 26 (Alternate Collating Sequence)

Allowable
Entries Explanation
Blank Uses the ASCII collating sequence.
E Uses the EBCDIC collating sequence.
S Uses a user-defined collating sequence.
See Appendix A, Character Sets, for a listing of the ASCII and EBCDIC
character sets.
3.13 Columns 27 - 42 (No-op)

left blank.
3–5
3.14 Column 43 (File Translation Code)

Use the File Translation Code only if the data in an input, update,
combine, or output file is not standard ASCII. See Chapter 17, Specifying
An Alternate Collating Sequence Or A Translation File, for information on
translating data files.
Table 3–8 Column 43 (File Translation Code)

Allowable
Entries Explanation
Blank No file translation is needed.
F Input, update, combined, or output files are to be translated.
3.15 Columns 44 - 59 (No-op)

left blank.
3.16 Column 60 (Zoned-decimal output)

Placing a Z in column 60 forces all standard numeric output (non-packed
and non-binary) to be zoned-decimal rather than trailing numeric. Placing
a Z in column 60 has the same results as placing a Z in column 44 of every
non-editted standard numeric output field.
Table 3–9 Column 60 (Zoned-decimal output)

Allowable
Entries Explanation
Blank Standard numeric field output is trailing numeric.
Z Standard numeric field output is zoned-decimal.
3.17 Columns 61 - 74 (No-op)

left blank.
3.18 Columns 75 - 80 (Comments)

Columns 75 - 80 can be used for comments. The compiler will ignore any
entry in these columns.
3–6
4 File Description Specification (F)
The File Description specification is used to describe the files accessed by

an RPG program. It describes the following attributes for each file used in
a program:
• File name
• File type
• File designation
• Sequence
• File format
• Record length
• Processing mode
• Key length
• Key location
• Overflow indicators
• Device type
• Continuation lines
• File sharing
• External indicator conditioning
4–1
File Description Specification (F)


Column 6 must always contain an F to identify a File Description
specification. Note that File Description specification continuation lines
contain blanks in columns 7 - 52.

Allowable
Entries Explanation
the compiler.
4.4 Columns 7 - 14 (File Name)

Columns 7 - 14 are used to identify a file which will be accessed by the
RPG program.
The file name must begin in column 7 with an alphabetic character (A - Z).
It can be 1 to 8 characters in length. The remaining characters can be A -
Z, 0 - 9, $, or an underscore (_). Each file name must be unique.
A logical name can be associated with the file name specified in columns
7 - 14. This permits the actual file designation to be much longer than 8
characters. See the Migration RPG User’s Guide for more information on
specifying logical file names for RPG programs.
Migration RPG allows a maximum of 98 files to be open in a single
program. The number of files a user can open depends on the open file
quota set in the user’s UAF 1 record by the system manager. To determine
the number of files a user can have open at any one time, review the
file quota entry in the UAF file or enter the SHOW PROCESS/QUOTA
command from the user’s process and look at the number to the right of
Open File Quota. The default file quota on most OpenVMS systems is 15
open files.
1 User Authorization File
4–2
4.5 Column 15 (File Type)

Column 15 indicates how a program will use a file. A file may be
designated for input, output, input and output (combined), or update.
Table 4–2 Column 15 (File Type)

Allowable
Entries Explanation
I Designates an input file. The program reads records from an input
file. These records must be defined in Input specifications unless
column 16 contains an R or T.
O Designates an output file. The program writes records to an output
file. These records must be defined in Output specifications unless
this is a table output file. If the output file does not exist, it will be
created by the program.
U Designates an update file. An update file serves as both an input
and an output file. The program can read a record, modify fields
in the record, and then write the record back to the same place in
the file. The records in these files must be defined in the Input and
Output specifications. The input and output records in an update file
will always contain the same fields.
If the update file does not exist and it is add capable (A in column
66 of the File Description specification), it will be created by the
program.
C Designates a combined input/output file. A combined file serves as
both an input and output file for a WORKSTN or SPECIAL device file.
Unlike an update file, the input and output records in a combined file
do not always contain the same fields. The input record will contain
the fields defined in the Input specifications, while the output record
contains the fields defined in the Output specifications.
Table 4–3 shows the device types and file types which can be associated
together:
4–3
Table 4–3 Device Types and File Types

Device Type
Columns 40 - File Type
46 Column 15 Open for:
CRT O Output
DISK I Input
O Output
U Update
KEYBORD I Input
PRINT O Output
PRINTER O Output
SPECIAL I Input
O Output
U Update
C Combined
WORKSTN C Combined
4.6 Column 16 (File Designation)

Column 16 is used to further qualify how a file will be processed by an
RPG program. Column 16 should be blank for all output files except
chained output files.
Table 4–4 Column 16 (File Designation)

Allowable
Entries Explanation
Blank Specifies a non-chained output file.
P Specifies a primary file. Only one file can be designated as the
primary file. It can be an input, update, or combined file and can use
any device except CRT, PRINT, or PRINTER. In multi-file processing,
the primary file determines the order of record selection; in single file
processing, the primary file provides all input records. If a primary file
is not specified and one or more secondary files are specified, the
first secondary file is assigned as the primary file. If no primary or
secondary files are specified, the programmer must initiate last cycle
processing by manually setting on the last record (LR) indicator.
4–4
Table 4–4 (Cont.) Column 16 (File Designation)

Allowable
Entries Explanation
S Specifies a secondary file. Secondary files are only used in

programs which use multi-file processing. See Chapter 13, Using
DISK Files, for more information on record selection for multi-file
processing.
A secondary file can be an input, update, or combined file. It
can use the DISK or SPECIAL device types. Secondary files
are processed in the order in which they are coded in the File
Description specifications. If no primary file has been declared and
secondary files are present, the first secondary file encountered
will be designated the primary file by the compiler. If a WORKSTN
device is designated the primary file, no secondary files can be
specified in the program.
C Specifies a chained file. A chained file resides on disk and can be
used as an input, output, or update file. The CHAIN operation code
in the Calculation specifications is used to randomly read records by
key or relative record number from a chained file. An output chained
file can be used to add records to a relative file. A chained file
can only use the DISK device. See Chapter 11, Operation Codes,
Section 11.12.9, - CHAIN Operation, for more information on the
CHAIN operation.
F Specifies a full-procedural file. A full-procedural file can be an input
or update file and must use the DISK device.
A full-procedural file is a combination chain and demand file.
Records from a full-procedural file are accessed using the CHAIN,
READ, READE, and READP operation codes in the Calculation
specifications. See Chapter 11, Operation Codes, Sections 11.12.9,
11.12.42, 11.12.43, and 11.12.44, for more information on accessing
records from a full-procedural file.
D Specifies a demand file. A demand file can be an input, update,
or combined file. A demand file can use any device except PRINT,
PRINTER and CRT.
The READ and KEYnn operation codes are used in the
Calculation specifications to sequentially access records in a
demand file. See Chapter 11, Operation Codes, Sections 11.12.42
and 11.12.28, for more information on using the READ and KEYnn
operation codes to access records from demand files.
4–5
Table 4–4 (Cont.) Column 16 (File Designation)

Allowable
Entries Explanation
R Specifies a record-address file. A record address file contains either

key-field limits or record addresses for a DISK file. The program
uses the information from the record-address file to determine which
records from the associated data file to process and the order in
which they are to be processed. The record-address file must be
associated with a data file defined in an Extension specification. See
Chapter 13, Using DISK Files, for information on record-address
files.
A record address file is always an input file. If it contains key-
field limits, it must be associated to an indexed file. If it contains
record addresses, it can be associated to an indexed, relative, or
sequential file. Record-address files which contain record address
information are produced by the OpenVMS SORT Utility using the
SORT/PROCESS=ADDRESS command. Record address sorts
are often referred to as addrout sorts and the address files they
produce are referred to as addrout files.
T Specifies a pre-execution-time table or array. Columns 11 - 18 of
the Extension specification must contain the name of the file that
contains the data from which the table or array data will be loaded.
Array or table files must be sequential disk files. Pre-execution-time
table and array files are loaded by a program during the first cycle
before the normal cycle begins. See Chapter 15, Using Tables and
Arrays, for more information on pre-execution-time tables and arrays.
4.7 Column 17 (End-of-File)

Column 17 indicates whether a program can end before all records in a file
have been processed. Column 17 applies to primary and secondary files
only.
Table 4–5 Column 17 (End-of-File)

Allowable
Entries Explanation
Blank The program can end without processing all records in this file.
However, if column 17 is blank for all primary and secondary files, all
records in all files must be processed before the program can end.
Column 17 must be blank for WORKSTN and KEYBORD device
files.
E The program must read all the records in the file before it can end.
This option can be used on primary and secondary input, update,
and record-address files. It cannot be used on a file being processed
by a record-address file.
When matching fields are in use and an E is specified in column 17 for

the primary file and if there are matching records in the primary and
secondary files, the program reads and processes any records in the
secondary file that match the last record of the primary file before ending.
4–6
In programs which designate a WORKSTN or KEYBORD device as the

primary file, an E in column 17 is not valid. The programmer must set the
last record indicator (LR) on in the Calculation specifications to end this
type of program.
4.8 Column 18 (Sequence Code)

Use column 18 to specify ascending or descending sequence to check
matching fields. See Chapter 13, Using DISK Files, for information on
matching fields.
Table 4–6 Column 18 (Sequence Code)

Allowable
Entries Explanation
Blank Indicates that the program contains no matching fields or, if it
does, assumes the same value as specified for a previous primary
or secondary file. If the program contains matching fields and a
sequence is not specified for any file containing matching fields,
ascending order is assumed.
A Checks that records in the file are in ascending order.
D Checks that records in the file are in descending order.
The sequence code applies only to primary or secondary files with

matching fields.
The sequence code must be the same for each file processed with matching
fields.
The sequence code can be used with input, update, or combined files. It
is only valid with DISK files. Columns 61 and 62 are used to identify the
matching fields in the Input specifications.
Sequence checking is required when matching fields are used in a
program. If a record is found out of sequence, the program will halt and
the user will be given the option of skipping the record and continuing,
setting on the last record indicator (LR), and exiting the program normally,
or canceling the program immediately.
4.9 Column 19 (File Format)

Column 19 is used to specify the file format. The file format specifies
whether the records in the file are all the same length or whether they can
be different lengths. Most RPG programs use fixed-length files.
Table 4–7 Column 19 (File Format)

Allowable
Entries Explanation
Blank Defaults to an F.
F Indicates that the file contains fixed-length records.
V Indicates that the file contains variable-length records.
4–7
4.10 Columns 20 - 23 (Block Length)

Columns 20 - 23 are used to specify the length of a block read from a data
file. The block length must be a multiple of the record length specified in
columns 24 - 27. For example, if a record size of 80 is specified for the file,
block lengths of 80, 160, 320, and 8000 would all be valid, as they are all
multiples of 80.
The block length is not used by Migration RPG and can be left blank.
If a block length is entered, it will be compile checked to maintain
compatibility with non-OpenVMS versions of the RPG programming
language.
If specified, the block length must be a right-justified, numeric entry.
Leading zeros are optional.
4.11 Columns 24 - 27 (Record Length)

Columns 24 - 27 are used to specify the record length of a fixed-length file
or the longest record in a variable-length file. Record length entries must
be right-justified and numeric. Leading zeros are optional.
Table 4–8 Columns 24 - 27 (Record Length)

Allowable
Entries Explanation
1-9999 Specifies the number of characters in each record in a fixed-length
file or the maximum record size of a variable-length file.
If the record length is left blank on a terminal or printer device file

definition, a default length of 140 will be assumed. Leaving the record
length blank for any other type of file will result in a compiler error.
The record length for an addrout file can be either 3 or 6. An addrout file
produced by the OpenVMS SORT Utility contains records 6 characters in
length. An entry of 3 for an addrout file is converted to 6 by the compiler.
This feature is used by Migration RPG to support RPG II programs
transferred to an OpenVMS system from an IBM System/3, System/34, or
System/36.
4.12 Column 28 (Processing Mode)

Column 28 specifies the method used to access records in a file. The choice
of processing method depends on the entries for file designation and file
organization (columns 16 and 32). The choice of processing method for
input and update files depends on the entries for the file type (column 15),
the processing mode (column 28), the record address type (column 31), and
file organization (column 32). See Tables 4–10 through 4–17 to select the
correct value.
4–8
Table 4–9 Column 28 (Processing Mode)

Allowable
Entries Explanation
Blank Accesses records sequentially or accesses records sequentially by
key.
L Accesses records sequentially within limits.
R Accesses records randomly using a relative record number or an
index key, or using an addrout file, or tells the program to load a
direct file.
Sequential processing of a sequential file reads the records in the order in

which they were written. Sequential-by-key processing reads records from
indexed files that are used as primary, secondary, or demand files. The
records are read in the order specified by the key field associated to the
File Description specification. Sequential-within-limits processing reads
records in one of two ways:
• Specifying a range of records to be read.
• Using the SETLL operation code in the Calculation specification to set
the lowest key for the records in a demand file. The program reads
records with keys equal to or higher than the key specified.
Random processing reads records from chained files in one of the following
two ways:
• For sequential or direct files, records are accessed by their relative
record number. A relative record number identifies the position of a
record relative to the beginning of the file.
• For indexed files, records are accessed by their index key values.
Addrout file processing uses the record address file generated by the
OpenVMS SORT Utility. The addrout file contains binary record numbers
that correspond to the addresses of records; therefore, the records to be
read are located by their addresses.
The entries listed in Table 4–10 are valid for sequential files that reside on
disk.
4–9
Table 4–10 Modes of Processing for Sequential Files

Type of Access
Processing Mode Allowable Entries
Column:
15 16 28 31 32 66
Sequential Sequential I P
I S
I T
I D
U P
U S
U D
Random Using CHAIN I C R I
I C R I A
U C R I
U C R I A
Random Using Addrout I P R I
I S R I
I F
U P R I
U S R I
U F
Sequential Using READ, I F
and/or READP, and I F A
Random /or CHAIN U F
U F A
Create Output Add O
O A
4–10
The entries listed in Table 4–11 are valid for relative files that reside on
disk.
Table 4–11 Modes of Processing for Relative Files

Type of Access
Column:
15 16 28 31 32 66
Sequential Sequential I P
I S
I D
U P
U S
U D
Random Using CHAIN I C R
I C R A
U C R
U C R A
Random Using Addrout I P R I
I S R I
I F
U P R I
U S R I
U F
Sequential Using READ, I F
and/or READP, and I F A
Random /or CHAIN U F
U F A
Output CHAIN O C R
Create Output O R
4–11
The entries listed in Table 4–12 are valid for indexed files that reside on
disk.
Table 4–12 Modes of Processing for Indexed Files

Type of Access
Column:
15 16 28 31 32 66
Sequential By Key, No I P I
Add I S I
I D I
U P I
U S I
U D I
Sequential By Key, Add I P I A
I S I A
I D I A
U P I A
U S I A
U D I A
Sequential By Limits I P L I
I S L I
I D L I
I F L I
U P L I
U S L I
U D L I
U F L I
Sequential By Limits, I F L I A
With Add U F L I A
Random By Chain, I C R I
No Add U C R I
Random By Chain, I C R I A
With Add U C R I A
Random By Addrout I P R I I
I S R I I
U P R I I
U S R I I
Sequential By Key, I F I
and/or No Add U F I
Random
Sequential By Key, I F I A
and/or With Add U F I A
Random
Create Output O I
Create Output Add O I A
4–12
The entry listed in Table 4–13 is valid for printer files.
Table 4–13 Modes of Processing for Printer Files

Type of Access
Column:
15 16 28 31 32 66
- Output O
The entries listed in Table 4–14 are valid for workstation files.
Table 4–14 Modes of Processing for Workstation Files

Type of Access
Column:
15 16 28 31 32 66
- Input/Output C P
C D
The entries listed in Table 4–15 are valid for record address files. Record
address files can be associated with sequential, relative, or indexed files
that reside on disk. Record address files containing key field limits can
only be associated with indexed files.
Table 4–15 Modes of Processing for Record Address Files

Type of Access
Column:
15 16 28 31 32 66
- Input I R I T
I R
4–13
The entries listed in Table 4–16 are valid for KEYBORD files.
Table 4–16 Modes of Processing for KEYBORD Files

Type of Access
Column:
15 16 28 31 32 66
- Input I P
I D
The entries listed in Table 4–17 are valid for SPECIAL device files.
Table 4–17 Modes of Processing for SPECIAL Files

Type of Access
Column:
15 16 28 31 32 66
- Input I P
I S
I D
I
- Input/Output U
C
- Output O
4–14
4.13 Columns 29 - 30 (Key Length)

Columns 29 and 30 specify key length. Key length indicates the length in
bytes of one of the following:
• Total length of an index key in an indexed file
• Total length of an index key in a limits file
• Length of the record addresses in an addrout file
Table 4–18 Columns 29 - 30 (Key Length)

Allowable
Entries Explanation
Blank Indicates a sequential, relative, or display file.
1-99 Specifies the total length of the record key for an indexed file or a
record-address (addrout) file.
The record length for an addrout file can be either 3 or 6. An addrout file
produced by the OpenVMS SORT Utility contains records 6 characters in
length. An entry of 3 for an addrout file is converted to 6 by the compiler.
This feature is used by Migration RPG to support RPG II programs
transferred to an OpenVMS system from an IBM System/3, System/34, or
System/36.
The entry must be numeric and right-justified. Leading zeros can be
omitted.
Packed-decimal key fields can have a maximum length of 8. When
specifying the length of a packed-decimal key, use the packed length of
the field.
4.14 Column 31 (Record Address Type)

Column 31 specifies the record address type. The record address type
helps define the mode of processing.
Table 4–19 Column 31 (Record Address Type)

Allowable
Entries Explanation
Blank Uses relative record numbers to process sequential and direct
chained files, or reads records sequentially from an input or update
file, or creates or adds records to a sequential output file.
A Processes or loads indexed files according to the record keys in
alphameric format.
P Processes or loads indexed files according to record keys in packed
format.
I Processes the file according to an addrout file or identifies an addrout
file.
4–15
The following tables depict the valid combinations of entries in the

processing mode column (28) and the record address type column (31).
Table 4–20 Valid Combinations of Entries in Columns 28 and 31 for

Primary, Secondary, and Demand Files
Processing Mode Record Address Type
Method of Processing Column 28 Column 31
Sequential Blank Blank
By Address R I
(except demand
files)
Sequential by key Blank A/P
Sequential within L A/P
limits

Chained Files
Random by relative R Blank
record number
Random by key R A/P

Full-Procedural Files
Sequential Blank Blank
By Address Blank Blank
Sequential by key Blank A/P
Sequential within L A/P
limits
Random by relative Blank Blank
record number
Random by key Blank A/P
4.15 Column 32 (File Organization)

Column 32 is used to specify how records are arranged in a file. This
attribute works in conjunction with the mode of processing (column
28). See Section 4.12 for valid combinations of processing mode and
file organization entries.
4–16
Table 4–23 Column 32 (File Organization)

Allowable
Entries Explanation
Blank Indicates a sequential, direct, or indexed file processed sequentially.
I Indicates an indexed file processed sequentially or randomly by key.
T Indicates an addrout file
4.16 Columns 33 - 34 (Overflow Indicator)

Use columns 33 and 34 to specify an overflow indicator for a PRINT or
PRINTER file. An overflow indicator is used to specify output actions in
a print file when overflow occurs. See Chapter 14, Using Printer Output
Files, for more information on overflow indicators.
Table 4–24 Columns 33 - 34 (Overflow Indicator)

Allowable
Entries Explanation
Blank Specifies no overflow indicator.
OA-OG, OV Specifies an overflow indicator to condition output lines when
overflow occurs.
Overflow indicators can only be specified on PRINT or PRINTER output

File Description specifications.
Only one overflow indicator can be assigned to a PRINT or PRINTER file.
If the program uses more than one print file and overflow conditioning is
to be used on each file, a unique overflow indicator must be specified for
each file.
A maximum of 8 print files can use overflow control in a single program.
4.17 Columns 35 - 38 (Key Start Location)

Columns 35 - 38 are used to specify the key field starting location within
a file. Each record in an indexed file has a key field that RMS uses to
locate records. This key field can be anywhere in the record, but must
be in the same location for each record in the file. The key start location
specifies where to find the key field in the record. This entry can be used
in conjunction with the alternate index entry (columns 68 - 69) to specify
an alternate index for a file.
4–17
Table 4–25 Columns 35 - 38 (Key Start Location)

Allowable
Entries Explanation
Blank Indicates that the file is not indexed.
1-9999 Specifies the location of the key field.
EXTK Specifies a noncontiguous key field.
If the entry is numeric, it must be right-justified. Leading zeros can be

omitted.
If the entry is not numeric, it must be EXTK.
EXTK informs the program that the key field being referenced is non-
contiguous. The key length (columns 29 - 30) and alternate index (columns
68 - 69) entries are used in conjunction with this entry to define the key
field which should be referenced by the program.
A word of caution: When using an FDL file definition to locate the
beginning of a key field, be aware that the FDL definition specifies this
location as an offset from 0. When specifying the key start location in
the RPG program, do not specify it as an offset. For example, if an FDL
definition indicates that a key field starts in offset 9, the key start location
entry in the RPG File Description specification would contain a 10.
If a program opens an indexed file and cannot match the key definition in
the File Description specification with a key in the file, the program will
abort with an RMS error.
4.18 Column 39 (Extension Code)

Column 39 is used to specify an extension code which indicates that the file
is further defined in an Extension or Line Counter specification. Extension
specifications are used to define tables, arrays, and record-address files.
Line Counter specifications are used to define form characteristics for
PRINT or PRINTER files.
Table 4–26 Column 39 (Extension Code)

Allowable
Entries Explanation
Blank No Extension or Line Counter specification is associated with this
file.
E An Extension specification is associated with this file.
L A Line Counter specification is associated with this file.
4.19 Columns 40 - 46 (Device Code)

Use columns 40 - 46 to specify the device code that indicates on what type
of device the file is stored. Migration RPG is designed to make porting
non-OpenVMS RPG II applications to an OpenVMS system as easy as
4–18
possible. For this reason, Migration RPG supports a wide range of device
types.
The following table specifies the standard device types used in Migration
RPG. Given the ability to associate File Description specifications logically
to devices on an OpenVMS system, these device types are sufficient for
most RPG applications.
Table 4–27 Columns 40 - 46 (Device Code - Standard Migration RPG

Device Types)
Allowable
Entries Explanation
DISK An input/output device usually associated with a fixed disk device.
Disk files can be used for input, update, and output of data records.
PRINT or An output only file used to produce reports. Printer files can be
PRINTER written to disk or associated directly to a print device. On OpenVMS
systems, print files are usually written to disk and then submitted to
a print queue using the DCL PRINT command.
SPECIAL The SPECIAL device file is used to provide an interface to RPG
programs for non-standard devices and utilities. The SPECIAL
device file interfaces with a user-supplied external routine. See
Chapter 18, Using a SPECIAL Device File, for more information on
using the SPECIAL device file.
WORKSTN An input/output device used to communicate with a terminal or
workstation. Workstation screens are defined by Screen, Help,
and Field Definition specifications in a Screen Format file. The
screen format file is linked with the RPG program. See the Migration
RPG Screen Format Reference Manual for more information on
developing workstation screens.
The following device types are supported by Migration RPG to make

porting RPG II applications to an OpenVMS system as easy as possible.
Table 4–28 Columns 40 - 46 (Device Code - Supported Migration RPG

Device Types)
Allowable
Entries Explanation
CONSOLE Input/output device which communicates with display stations.
CRT Output device associated to the logical SYS$OUTPUT. A CRT device
can be used to output to a terminal or workstation.
KEYBORD Input/output device used to accept and display information from a
terminal or workstation using the SETnn and KEYnn operation
codes in the Calculation specifications.
DISC Input/output devices associated to a disk device.
DBDISK
DISK40
DKDISK
DPDISK
DMDISK
4–19
Table 4–28 (Cont.) Columns 40 - 46 (Device Code - Supported Migration

RPG Device Types)
Allowable
Entries Explanation
DECTAP Input device associated to a tape drive. Tape files can only be
TAPE processed as sequential input files.
PRINTR Output device used to define a report file.
READER Input device associated to a card reader. Card reader files can only
READ40 be processed as sequential input files.
TTY Input device associated to the logical SYS$INPUT. A TTY device can
be used to input records embedded in a command procedure.
The device type entry must be left-justified.
4.20 Columns 47 - 52 (No-op)

Columns 47 - 52 are not used in a File Description specification. They
should be left blank. Some versions of RPG use columns 47 - 52 to specify
a symbolic device. If an entry is found in columns 47 - 52, the Migration
RPG compiler will issue a warning message and ignore the entry.
4.21 Column 53 (Continuation Lines)

Column 53 is used to indicate a continuation line associated to the
previous File Description specification. Continuation lines are optional
and can be associated to DISK, WORKSTN, and SPECIAL device files.
Continuation lines are made up of File Description specifications with
blanks in columns 7 - 52 and a K in column 53. They must immediately
follow the file with which they are associated. Section 4.23 defines the
options which can be specified on a continuation line.
Table 4–29 Column 53 (Continuation Lines)

Allowable
Entries Explanation
Blank No continuation lines are associated with this file.
K One or more continuation lines are associated with this file.
4.22 Columns 54 - 65 (SPECIAL Device Routine)

Columns 54 - 65 must be used to specify the entrance point to the external
routine associated to a SPECIAL device file if SPECIAL is coded in
columns 40 - 46. The external routine name can be 1 - 12 characters in
length and must begin with an alpha character. The external routine must
be linked to the RPG program.
4–20
Columns 54 - 65 can also be used to identify the MSI supplied SPECIAL

device routine SUBR01. The SUBR01 routine opens a channel to the
logical SYS$INPUT and can be used to input records embedded in a
command procedure. SUBR01 support is provided as a compatibility
feature with IBM RPG II.
4.23 Columns 54 - 59 (Continuation Options) and Columns 60 - 65

(Continuation Entries)
Columns 54 - 59 can also be used to specify the continuation option on a
continuation line. These options are defined in the following subsections.
Columns 60 - 65 are used to specify the entries which are associated to
the continuation option. These entries are also described in the following
subsections.
All entries in columns 54 - 59 and 60 - 65 must be left-justified.
4.23.1 Rules for Specifying a Continuation Line on a DISK File

A DISK file can have one continuation line associated to it. It can be
used to specify a record number field which can be used to add records
to a sequential or relative file. The continuation is not required to add
records to sequential and relative file. It is supported to aid the porting of
non-OpenVMS versions of RPG to an OpenVMS system.
Table 4–30 DISK File Continuation Option

Option Entry
Columns 54 - 59 Columns 60 - 65
RECNO Name of a 6 digit, 0 decimal numeric field. The field must be
defined somewhere in the program.
When a record is input from a sequential or relative file, its
record number is placed in this field. When outputting a
record, place the relative record number in this field before
the record is output.
When outputting records using the RECNO option, the record
position must exist in the file in order for the write operation
to complete successfully. Sequential and relative files using
the RECNO continuation should be created in advance and
populated with blank records.
4.23.2 Rules for Specifying a Continuation Line on a SPECIAL Device File

A SPECIAL device file can have one continuation line associated to it. It
is used to specify an array defined in the Extension specifications which
can be passed to the SPECIAL device file routine.
4–21
Table 4–31 SPECIAL Device File Continuation Option

Entry
Explanation
Array The name of an array defined in the Extension specifications
Name which will be used to pass information back and forth
between a SPECIAL device routine.
4.23.3 Rules for Specifying a Continuation Line on a WORKSTN Device File

A workstation device file can have 1 to 8 continuation lines associated
with it. These specifications are used to pass information between an RPG
program and a workstation screen and to specify the INFDS exception
handling routine.
4–22
Table 4–32 WORKSTN File Continuation Options

Option Entry
Columns 54 - 59 Columns 60 - 65
FMTS Specifies the name of the screen format file containing the
screens used by the program. The entry can be up to 8
characters long, running from columns 60 - 67. This entry
is ignored by the Migration RPG compiler and is supported
for compatibility purposes with non-OpenVMS versions of
the RPG programming language. However, the BUILD
procedure provided with the Migration RPG Compiler Kit
compiler will process the FMTS continuation line. See the
description of the BUILD procedure in the Migration RPG
User’s Guide for more information on the BUILD procedure.
ID A two-character, alphameric field identifying the terminal or
workstation from which the program is running. See the
Migration RPG User’s Guide for information on establishing
and changing workstation ID’s.
IND This function has no meaning under Migration RPG. It is
supported for compatibility purposes with non-OpenVMS
versions of the RPG programming language. The Migration
RPG compiler will ignore IND continuation lines.
INFDS The name of a data structure which will receive information
from a workstation screen concerning its return status and
any exceptions processed. The data structure must be
defined in the Input specifications.
INFSR Name of the exception handling subroutine. This subroutine
must be defined in the Calculation specifications. The
INFSR subroutine is called if an exception occurs during
a workstation read and no other error trapping has been
specified for the read.
NUM This function has no meaning under Migration RPG. It is
RPG compiler will ignore NUM continuation lines.
SAVDS This function has no meaning under Migration RPG. It is
RPG compiler will ignore SAVDS continuation lines.
SLN A 2 digit, 0 decimal numeric field which is passed to the
screen format file. The SLN field defines the starting line
for a variable start line screen (V coded in column 17 of
the Screen specification). The field must be defined within
the RPG program. See the Migration RPG Screen Format
Reference Manual for information on creating a variable start
line screen.
4–23
4.24 Column 66 (File Addition)

Column 66 is used to indicate that records can be added to a file.
Section 4.12 indicates the type of File Description specifications which
allow record addition.
Table 4–33 Column 66 (File Addition)

Entry Explanation
Blank Records cannot be added to the file.
A Records can be added to the file. The entry ADD must also be
specified in columns 16 - 18 of an Output specification in order to
add records to a file.
U Records can be added to the file. The entry ADD must also be
specified in columns 16 - 18 of an Output specification in order to
add records to a file. The U entry is supported to aid porting of
non-OpenVMS RPG applications to Migration RPG.
If an update file (U in column 15) is declared add capable by entering an A

or U in column 66, and the file does not exist when the program attempts
to open it, the program will create the file.
4.25 Column 67 (No-op)

Column 67 is not used in a File Description specification. It should be left
blank.
4.26 Columns 68 - 69 (Alternate Key)

Columns 68 - 69 can be used to specify an alternate key for an indexed file.
If columns 68 and 69 are blank, the file will be accessed using its primary
key. See the Migration RPG User’s Guide for more information concerning
the use of primary and secondary keys.
Table 4–34 Columns 68 - 69 (Alternate Key)

Entry Explanation
Blank Indexed files are referenced by their primary key. This is Key 0 in an
FDL file description.
00 - 99 Specifies the key by which the file is to be accessed. Remember that
the key fields are numbered as an offset from 0; thus, the primary key
is Key 0, the first alternate key is Key 1, the second alternate key is
Key 2, and so on. An alternate key designation must be numeric and
right-justified.
4–24

Column 70 is not used in a File Description specification. It should be left
blank.
4.28 Columns 71 - 72 (File Conditioning Indicator)

Columns 71 - 72 can be used to specify an external indicator (U1 -
U8) which conditions access to the file. If the indicator is off when the
program is initialized, the file is set to an end-of-file condition and ignored.
External indicators can be used to condition input, output, or update files,
excluding table and KEYBORD input files.
Table 4–35 Columns 71 - 72 (File Conditioning Indicator)

Entry Explanation
Blank The file is not conditioned by an external indicator.
U1 - U8 The file is conditioned by the specified external indicator. If the indicator
is on, the file is processed normally. If the indicator is off, the file
is set to an end-of-file condition and ignored by the program. If the
conditioning indicator is off, no records are processed from the file.
External indicators can be set within a program or a command procedure.

See the Migration RPG User’s Guide for a description of the REX Utility,
which can be used to set external indicators.
When a program is initialized, conditioning indicators are evaluated
and access is granted or denied to the associated file. If the external
indicator is later set on within the program, it has no effect on file
access. The only exception to this rule is if the program in question is
an RPG subprogram. It would be possible to modify external indicator
settings within a subprogram, exit the subprogram, then initialize and call
the subprogram again. The subprogram would re-evaluate the updated
external indicators and access its files accordingly.
If a file is conditioned by an external indicator, all associated operations
within the Calculation specifications should also be conditioned by the
same indicator.
4.29 Column 73 (File Sharing)

Column 73 can be used to define the type of shared access that will be
allowed to a file that is opened by the program. File sharing is defined as
two or more file streams accessing the same data file at the same time. By
default, RPG programs under OpenVMS allow file access according to the
standard file sharing rules of RMS.
4–25
Table 4–36 Column 73 (File Sharing)

Entry Explanation
Blank RMS default access rules will be used to grant read/write/delete
or S access to the file.
N No shared access. The file will be open exclusively by this file
stream and will not be accessible to any other open/read/write
request from any other source.
R Read only access. The file stream controlling the file will allow other
file streams read access to the file.
A file with an ‘N’ in column 73 of the File Description specification will

not allow any other programs access to the data file. A file with an ‘R’
in column 73 will allow other programs read access to the data file, but
will not allow records to be read for update or deletion from the file. A
file with an ‘S’ or blank in column 73 allows other programs full access to
the data file, as long as this access does not conflict with the default RMS
restrictions on the file.
When using the file sharing code in column 73, it is important to realize
that the share code specified for one file stream affects all other file
streams that attempt to access the file, even if the file streams are
associated with the same program. Therefore, if file share codes are
used incorrectly, it is possible for a program to deny itself access to a file
by having two conflicting file share qualifiers set up on two file streams
accessing the same file.
Consider the following example:
Example 4–1 File Sharing
$ DEFINE/USER GREEDY USER1:GOODSTUFF.DAT

$ DEFINE/USER OUTCST USER1:GOODSTUFF.DAT
$ RUN LOD_LIB:MISTAKE
In this example, the program MISTAKE assigns two file streams to the
data file GOODSTUFF.DAT. Under default conditions, this operation
would present no problems. However, if in the program the file GREEDY
has a share code of ‘N’, the program will be unable to connect a second
stream to the data file and will abort when it tries to connect the stream
for OUTCST.
4.30 Column 74 (No Deferred Write)

Column 74 can be used to turn off the deferred write capabilities of
Migration RPG. By default, all RPG programs use deferred write when
outputting or updating a data file. This feature is used to help improve
program performance and decrease disk I/O. RMS global buffering takes
care of multiple accesses to the same record before it is written to disk.
4–26
Table 4–37 Column 74 (No Deferred Write)

Entry Explanation
Blank The program will use deferred write. Records will be written when
the internal output buffers are filled.
N The program will not use deferred write. Records are output as soon
as a write operation is executed.
Using deferred write allows a program to reduce disk I/O operations by

outputting several records in a single write operation. Records which are
output by the RPG program are stored in an RMS buffer until the buffer
fills. RMS then writes all of the records to disk in one operation. RMS
buffering can be modified using the DCL command SET RMS_DEFAULT.
Not using deferred writing will degrade program and system performance
and increase disk I/O. The ability to disable deferred writes within RPG
has been added to assist users that are running programs such as Watch
Dog, which terminate processes using a STOP PROCESS/ID, preventing
any existing record buffers from being written to disk. MSI does not
recommend or support the use of any utilities or services that terminate
processes without performing normal image shutdown operations such as
flushing file buffers and closing open files.

entries in these columns.
4–27
5 Extension Specification (E)
The Extension specification is used to describe:

• Compile time, pre-execution-time, and execution-time arrays.
• Compile time and pre-execution-time tables.
• Record address files.
The Extension specification is used to provide the following information

about a table or array:
• Name of the table or array
• Number of entries per record
• Number of entries per table or array
• Length of each table entry or array element
• Format of numeric data
• Decimal position
• Sequence of entries
• Alternate table or array definition
Compile time tables and arrays require entries in columns 19 - 45; pre-
execution-time tables and arrays require entries in columns 11 - 45;
execution-time arrays require entries in columns 27 - 32 and columns
36 - 45. An alternate table or array must be defined on the same line in
columns 46 - 57.
A record-address file requires entries in columns 11 - 26. These entries
provide the following information:
• Name of the record-address file
• Name of the data file associated with the record-address file


Column 6 must always contain an E to identify an Extension specification.
5–1
Extension Specification (E)

Allowable
Entries Explanation
the compiler.

Columns 7 - 10 should be left blank if column 7 is not used to specify a
comment or compiler directive.
5.5 Columns 11 - 18 (From-File Name)

Columns 11 - 18 can be used to specify the from-file name that identifies
the name of the record-address file or the input file used to load a pre-
execution-time table or array.
Table 5–2 Columns 11 - 18 (From-File Name)

Allowable
Entries Explanation
Blank Loads the table or array named in columns 27 - 32 (table or
array name) at compile time if columns 33 - 35 (entries per
record) are completed.
Loads the array at execution time if the array is specified
by the Input and/or Calculation specification and if columns
33 - 35 are left blank.
Record Address Name of a record-address file.
File Name
Table or Array Name of the table or array input file. The contents of this file
File Name will be loaded to the associated table or array during program
initialization.
If a file name is specified, it must also be defined in the File Description

specifications. The entry must be left-justified.
A compile time table or array is loaded when the program is compiled.
Compile time table and array data is specified at the end of the RPG
program, following the last Output specification in the program. Each set
of table or array records is separated by a pair of asterisks (**) in columns
1 - 2.
5–2
The following example displays compile time table and array Extension
specifications and the associated data coded at the end of the program.
Example 5–1 compile time Table and Array Coding
1 2 3 4
1234567890123456789012345678901234567890123456
E*
E TABCST 3 9 4 2
E ARYDB 4 8 2
.
.
.
O*
** Data for TABCST compile time table.
134592830587
283758471047
574837263746
** Data for ARYDB compile time array.
SASBSCSD
THATBTCTD
5.6 Columns 19 - 26 (To-File Name)

Columns 19 - 26 can be used to identify an input or update file associated
to the record address file specified in columns 11 - 18 (from-file name) or to
specify an output file for a table or array.
Table 5–3 Columns 19 - 26 (To-File Name)

Allowable
Entries Explanation
Blank The Extension specification describes a table or array and
the table or array is not written to a file at the end of the
program.
Input or Update Identifies the data file associated with the record-address file
File Name named in columns 11 - 18.
Output File The output file that receives the data from the table or array
Name at the end of the program.
If a file name is specified, it must be also be specified in the File

Description specifications. The entry must be left-justified.
Array and table data is output after the last-record indicator (LR) comes
on and all other output processing has been completed.
If a record address file is being used, entries must be made in both
columns 11 - 18 and 19 - 26. The from-file name (11 - 18) must contain
the record address file name; the to-file name (19 - 26) must contain the
name of the associated input or update file.
5–3
5.7 Columns 27 - 32 (Array or Table Name - Primary Entry)

Columns 27 - 32 are used to identify a table or array.
Table 5–4 Columns 27 - 32 (Array or Table Name - Primary Entry)

Allowable
Entries Explanation
Blank Indicates that the file named in columns 11 - 18 (from-file name) is a
record-address file.
Name Identifies the name of the table or array.
A table or array name can be 1 - 6 characters in length and must begin

with an alpha character. Each array and table name must be unique. The
entry must be left-justified.
This entry describes the name of the main table or array. An alternate
table or array name can be specified in columns 46 - 51.
Table names must begin with TAB.
An entire array can be referred to throughout the program by specifying
the array name. Individual entries in the array can be referred to by
associating an index to the array name.
When a program is initialized, the first element in the table is placed in
the table storage area. When the table name is specified in the Calculation
specifications, it refers to the element in the table storage area. The
exception to this is when the table name is specified in a LOKUP
operation. See Section 11.12.29, - LOKUP Operation in Chapter 11,
Operation Codes, for more information on using table names in LOKUP
operations.
Tables and arrays are processed in the order they are specified in the
Extension specifications.
See Chapter 15, Using Tables and Arrays, for additional information on
specifying and using tables and arrays.
5.8 Columns 33 - 35 (Number of Entries Per Record)

Columns 33 - 35 are used to specify the number of entries in a table
or array input record. Complete this entry for compile time and pre-
execution-time tables and arrays. If an entry is not present in these
columns for an array definition, the array is an execution-time array and is
not preloaded with data at compile time or during program initialization.
Table 5–5 Column 33 - 35 (Number of Entries Per Record)

Allowable
Entries Explanation
Blank Indicates a record-address file or an execution-time array.
1-999 Specifies the number of entries in a table or array input record.
5–4
This entry must be numeric and right-justified. Leading zeros can be

omitted.
The following rules apply to the records which contain the data used in
compile time and pre-execution-time tables and arrays.
• All records, except the last, must have the same number of entries.
The last-record can have fewer entries to accommodate a number of
entries that is not an even multiple of the defined number of entries
in the record. If a compile time array or table does not contain enough
entries, the RPG compiler will issue a warning message.
• The first entry must begin in the first position of the record.
• Leave no spaces between entries in a record.
• Entries cannot span two records.
• If table or array data are specified in an alternating format, each
record must contain a corresponding entry. The entries from the main
table or array and the corresponding entries from an alternate table or
array are treated as one entry.
The following rules apply to the from-file name (columns 11 - 18) and
number of entries in a record (columns 33 - 35) when an array name is
specified in columns 27 - 32.
• An execution-time array requires that columns 11 - 18 and 33 - 35 be
blank.
• A compile time array must have an entry specified in columns 33 - 35.
Columns 11 - 18 must be blank.
• A pre-execution-time array must have a file name specified in columns
11 - 18 and an entry in columns 33 - 35.
5.9 Columns 36 - 39 (Number of Entries in a Table or Array)

Columns 36 - 39 are used to specify the number of entries in a table or
array and in an alternate table or array, if an alternate table or array is
being defined.
Table 5–6 Columns 36 - 39 (Number of Entries in a Table or Array)

Allowable
Entries Explanation
1-9999 Specifies the number of entries in a table or array.
The entry must be numeric and right-justified. Leading zeros can be

omitted.
If a compile time or pre-execution-time table or array is not completely
full, the unused entries are filled with blanks for alphameric data and
zeros for numeric data.
5–5
If a compile time array is not full, the RPG compiler will issue a warning
message when the program is compiled.
5.10 Columns 40 - 42 (Length of Entry - Primary Entry)

Columns 40 - 42 specify the length of the entries in the array or table
defined in columns 27 - 32.
Table 5–7 Columns 40 - 42 (Length of Entry - Primary Entry)

Allowable
Entries Explanation
1-999 Specifies the number of character positions (both alphameric and
numeric) in each table or array entry.
An alphameric entry can be up to 999 characters in length.

A numeric entry can be up to 15 digits in length.
Specify the unpacked length of packed-decimal fields in this entry.
If the table or array data is in binary format, the entry is 4 for a 2-position
binary field and 9 for a 4-position binary field.
The largest record size which can be specified in a compile time table is
100 characters. This is the largest record that will be processed by the
RPG compiler.
This entry specifies the length of the entry in the primary table or array
for alternating table and array definitions.
All entries in a table or array must be the same length. When creating
the entries for compile time and pre-execution-time tables and arrays, pad
alphameric entries with blanks and numeric entries with zeros.
5.11 Column 43 (Data Format - Primary Entry)

Column 43 specifies how numeric data is stored. Data can be stored in one
of the following three formats:
• numeric/alphameric
• Packed-decimal
• Binary
5–6
Table 5–8 Column 43 (Data Format - Primary Entry)

Allowable
Entries Explanation
Blank Specifies that numeric data is in zoned-decimal or trailing numeric
format or that the table or array contains alphameric data.
P Specifies that numeric data is in packed-decimal format. This format
is valid only for pre-execution-time tables or arrays.
B Specifies that numeric data is in binary format. This format is valid
only for pre-execution-time tables or arrays.
5.12 Column 44 (Decimal Positions - Primary Entry)

Column 44 specifies the number of positions to the right of the decimal
point for numeric data in a table or array.
Table 5–9 Column 44 (Decimal Positions - Primary Entry)

Allowable
Entries Explanation
Blank The table or array contains alphameric data.
0-9 Specifies the number of positions to the right of the decimal point for
numeric data in a table or array
All numeric tables and arrays must have an entry specified in this column.
Specify a zero for numeric data with no decimal positions.
When alternating arrays or tables are specified, this entry applies to the
first entry that appears in the array or table data record.
5.13 Column 45 (Sequence - Primary Entry)

Column 45 can be used to specify the sequence of entries in the primary
table or array.
Table 5–10 Column 45 (Sequence - Primary Entry)

Allowable
Entries Explanation
Blank Indicates that the entries in a table or an array are unordered.
A Specifies that the entries in a table or array are in ascending order,
sorted from lowest to highest according to the specified collating
sequence.
D Specifies that the entries in a table or array are in descending order,
sorted from highest to lowest according to the specified collating
sequence.
Consecutive entries that are equal in value are considered to be in

sequence.
5–7
When using tables or arrays in alternating format, this entry specifies the
sequence of the primary table or array.
When a sequence is specified for a compile time table or array, the
sequence is checked by the RPG compiler. If the table or array is not
sorted in the specified sequence, the compiler issues a fatal compile time
error.
If a pre-execution-time table or array is out of sequence, the program halts
and prompts the user to ignore the error and continue, or terminate the
program.
5.14 Columns 46 - 51 (Array or Table Name - Alternate Entry)

Columns 46 - 51 are used to identify an alternate table or array. Alternate
tables and arrays are optional. They have the same number of elements
as the primary table or array. Array and table definitions cannot be mixed
on the same Extension specification.
Table 5–11 Columns 46 - 51 (Array or Table Name - Alternate Entry)

Allowable
Entries Explanation
Blank No alternate table or array is being specified, or this Extension
specification is being used to identify a record address file.
Name Identifies the name of the alternate table or array.
A table or array name can be 1 - 6 characters in length and must begin

with an alpha character. Each array and table name must be unique. The
entry must be left-justified.
Table names must begin with TAB.
An entire array can be referred to throughout the program by specifying
the array name. Individual entries in the array can be referred to by
associating an index to the array name.
When a program is initialized, the first element in a table is placed
in the table storage area. When the table name is specified in the
Calculation specifications, it refers to the element in the table storage
area. The exception to this is when the table name is specified in a
LOKUP operation. See Section 11.12.29 in Chapter 11, Operation Codes,
for more information on using table names in LOKUP operations.
Tables and arrays are processed in the order in which they are specified in
the Extension specifications.
See Chapter 15, "Using Tables and Arrays", for additional information on
specifying and using tables and arrays.
5–8
5.15 Columns 52 - 54 (Length of Entry - Alternate Entry)

Columns 52 - 54 specify the length of the entries in the alternate array or
table defined in columns 46 - 51.
Table 5–12 Columns 52 - 54 (Length of Entry - Alternate Entry)

Allowable
Entries Explanation
1-999 Specifies the number of character positions (both alphameric and
numeric) in each table or array entry.
An alphameric entry can be up to 999 characters in length.

A numeric entry can be up to 15 digits in length.
Specify the unpacked length of packed-decimal fields in this entry.
If the table or array data is in binary format, the entry is 4 for a 2-position
binary field and 9 for a 4-position binary field.
The largest record size which can be specified in a compile time table is
100 characters. This is the largest record that will be processed by the
RPG compiler.
This entry specifies the length of the entry in the alternate table or array
for alternating tables and arrays.
All entries in a table or array must be the same length. When creating
the entries for compile time and pre-execution-time tables and arrays, pad
alphameric entries with blanks and numeric entries with zeros.
5.16 Column 55 (Data Format - Alternate Entry)

Column 55 specifies how numeric data is stored. Data can be stored in one
of the following three formats:
• numeric/alphameric
• Packed-decimal
• Binary
Table 5–13 Column 55 (Data Format - Alternate Entry)

Allowable
Entries Explanation
Blank Specifies that numeric data is in zoned-decimal or trailing numeric
format or that the table or array contains alphameric data.
P Specifies that numeric data is in packed-decimal format. This format
is valid only for pre-execution-time tables or arrays.
B Specifies that numeric data is in binary format. This format is valid
only for pre-execution-time tables or arrays.
5–9
5.17 Column 56 (Decimal Positions - Alternate Entry)

Column 56 specifies the number of positions to the right of the decimal
point for numeric data in a table or array.
Table 5–14 Column 56 (Decimal Positions - Alternate Entry)

Allowable
Entries Explanation
Blank The table or array contains alphameric data.
0-9 Specifies the number of positions to the right of the decimal point for
numeric data in a table or array
All numeric tables and arrays must have an entry specified in this column.
Specify a zero for numeric data with no decimal positions.
When alternating arrays or tables are specified, this entry applies to the
second entry that appears in the array or table data record.
5.18 Column 57 (Sequence - Alternate Entry)

Column 57 can be used to specify the sequence of entries in the alternate
table or array.
Table 5–15 Column 57 (Sequence - Alternate Entry)

Allowable
Entries Explanation
Blank Indicates that the entries in a table or array are unordered.
A Specifies that the entries in a table or array are in ascending order,
sorted from lowest to highest according to the specified collating
sequence.
D Specifies that the entries in a table or array are in descending order,
sorted from highest to lowest according to the specified collating
sequence.
Consecutive entries that are equal in value are considered to be in

sequence.
When using tables or arrays in alternating format, this entry specifies the
sequence of the alternate table or array.
When a sequence is specified for a compile time table or array, the
sequence is checked by the RPG compiler. If the table or array is not
sorted in the specified sequence, the compiler issues a fatal compile time
error.
If a pre-execution-time table or array is out of sequence, the program halts
and prompts the user to ignore the error and continue, or terminate the
program.
5–10

Columns 58 - 80 can be used for comments. Entries in these columns are
ignored by the compiler.
5–11
6 Line Counter Specification (L)
The Line Counter specification allows the default form length to be

changed for a PRINT or PRINTER file. The Line Counter specification
can be used to change both the number of lines on a page and the overflow
line.
The default form length for a PRINT or PRINTER file is 66 lines; the
default overflow line is line 60. When a printer file reaches the overflow
line, the overflow indicator is set on and overflow processing takes place.


Column 6 must always contain an L to identify a Line Counter
specification.

Allowable
Entries Explanation
the compiler.

Columns 7 - 14 identify the print file with which the Line Counter
specification is associated.
6–1
Line Counter Specification (L)
Table 6–2 Columns 7 - 14 (File Name)

Allowable
Entries Explanation
File name Identifies the name of the output file.
The print file must be described in a File Description specification with

print in columns 40 - 46 (device code) and L in column 39 (extension).
The entry must be left-justified.
6.5 Columns 15 - 17 (Form Length)

Columns 15 - 17 can be used to define the number of lines available on a
page.
Table 6–3 Columns 15 - 17 (Form Length)

Allowable
Entries Explanation
1-112 Defines the maximum number of lines that can be printed on a page.
The entry must be a right-justified, numeric value. Leading zeros can be

omitted.
6.6 Columns 18 - 19 (Form Length Flag)

If an entry is specified in columns 15 - 17 (form length), FL must be
entered in columns 18 - 19 to indicate that columns 15 - 17 define the form
length.
Table 6–4 Columns 18 - 19 (Form Length Flag)

Allowable
Entries Explanation
FL Indicates that the program is to use the form length specified in
columns 15 - 17.
6.7 Columns 20 - 22 (Overflow Line Number)

Columns 20 - 22 can be used to specify the overflow line number. When
output to the PRINT or PRINTER file reaches the overflow line, the
overflow indicator is set on and overflow processing takes place.
Table 6–5 Columns 20 - 22 (Overflow Line Number)

Allowable
Entries Explanation
1-112 Specifies the overflow line number.
6–2
Line Counter Specification (L)
This entry must be equal to or less than the form length. The entry must
be a right-justified, numeric value. Leading zeros can be omitted.
When the overflow line is reached, the following actions occur if fetch
overflow has not been specified.
1 If detail output has not been completed, detail output occurs.
2 Total-time output occurs.
3 Total lines conditioned by the overflow indicator are output.
Overflow printing occurs after the overflow line has been reached. Enough
space should be left between the overflow line and the end of the page to
allow for the overflow print lines.
If the overflow line is equal to the form length, overflow does not occur.
6.8 Columns 23 - 24 (Overflow Line Flag)

If an entry is specified in columns 20 - 22 (overflow line number), OL must
be entered in columns 23 - 24 to indicate that columns 20 - 22 define the
overflow line number length.
Table 6–6 Columns 23 - 24 (Overflow Line Flag)

Allowable
Entries Explanation
OL Indicates that the program is to use the overflow line number

6–3
7 Input Specification (I)
The Input specification describes the records in input and update files.
The specifications can be divided into three categories:
• File and record descriptions. Columns 7 - 42 describe the file and its
records.
• Field descriptions. Columns 43 - 74 describe the fields in each record
and data structure.
• Data structure definitions. Columns 7 - 20 can be used to define a data
structure.
Input specifications must be used to describe each input, update, and

combined file except for table input files and record-address files.


Column 6 must always contain an I to identify an Input specification.

Allowable
Entries Explanation
the compiler.
7.4 Columns 7 - 42 (Record and Data Structure Definition)

Use columns 7 - 42 to describe the records in a file. Use columns 43 - 74 to
describe the fields in each record. Field descriptions must begin one line
below the record description.
7–1
Input Specification (I)

Columns 7 - 14 can be used to identify an input file record or a data
structure.

Allowable
Entries Explanation
File Name Identifies the input file with which the input record is
associated. The file name must match the file name specified
in columns 7 - 14 of the File Description specification.
Data Structure Optional name of a data structure. A DS must be specified
Name in columns 19 - 20 to identify this specification as a data
structure definition.
If this entry is blank, the compiler will assume that the information
in this line describes a field or record from the last file named in an
Input specification. If the line follows a data structure definition, it can
be another data structure definition (DS in columns 19 - 20) or a data
structure subfield definition.
All records and fields associated with one file should be described in one
contiguous section of Input specifications.
7.6 Columns 14 - 16 (AND/OR)

AND or OR can be specified in columns 14 - 16 to show a relationship
between record-identifying indicators or record types. The entry must be
left justified. AND/OR relationships in Input specifications are discussed
further in Section 7.11.5.
7.7 Columns 15 - 16 (Sequence)

Columns 15 and 16 are used to specify the sequence that defines the
ordering sequence of the record types in a file (for example, distinguishing
employee name records from employee badge number records). The
program does not order records according to sequence. It is used to
determine that the records are input in the correct sequence.
7–2
Table 7–3 Columns 15 - 16 (Sequence)

Allowable
Entries Explanation
Blanks Specifies no sequence checking for the record.
Any two Performs no sequence checking for the record. Any two
alphabetic letters from AA through ZZ can be used (example, BB, ZA,
characters DE). Alphabetic characters must be specified for chained,
demand, and full-procedural files and look-ahead fields.
Any Assigns a sequence number to a record. Any two-digit
two-digit number from 01 to 99 is valid. Numeric sequence codes
number must be specified in ascending order. Numeric sequence
codes must begin with 01. Gaps in the sequence numbers
are permitted.
Within one file, all records using alphabetic sequence codes must be
defined before those using numeric sequence codes.
Record sequencing can be used to insure that records from a file are
processed in the correct order. For example, in a customer order file
containing an order record followed by several detail records containing
order information, it would be important to ensure that the order record
was processed before the associated detail records. By assigning the order
record a sequence code of 01 and the detail record a sequence code of 02,
the program will ensure that the records are in the correct sequence before
it processes them.
If a record is processed out of sequence, the program halts and gives
the user the option of ignoring the sequence error and continuing or
terminating the program.
Sequence checking does not place records in order. It verifies that records
are in the correct order when they are input into the program. Sequence
checking has no relation to control levels and does not check data within a
record.
Input specifications with an AND or OR specified in columns 14 - 16
cannot have a sequence code.
7.8 Column 17 (Sequence Number)

If a numeric sequence code is assigned in columns 15 - 16, column 17 is
used to indicate the number of records in a sequence group.
7–3
Table 7–4 Column 17 (Sequence Number)

Allowable
Entries Explanation
Blank Program does not check the record for a special sequence. Columns
15 - 16 must be blank or specify an alphabetic sequence code.
1 Specifies that there is only one record of this type in a sequence
group.
N Specifies that there can be more than one record of this type in a
sequence group.
Leave this column blank if an alphabetic sequence has been specified in

columns 15 and 16.
cannot have a sequence number specified in column 17.
7.9 Column 18 (Option)

If a numeric sequence code has been assigned in columns 15 and 16,
column 18 can be used to specify whether a record of that type must be
present in a sequence group.
Table 7–5 Column 18 (Option)

Allowable
Entries Explanation
Blank Record type must be present if sequence checking has been
specified.
O Record type is optional in a sequence group.
U The program uses the data structure defined by this Input
specification as the local data area. See Chapter 16, Defining
and Using Data Structures, for more information on the local data
area. Only one local data area data structure can be defined in a
program.
Leave this column blank if a blank or alphabetic sequence has been

If all records are listed as optional, no sequence checking is performed.
cannot have a sequence option specified in column 18.
7.10 Columns 19 - 20 (Record-Identifying Indicator)

Specifying an indicator in columns 19 and 20 associates the indicator
with a particular record type. When a record of the type specified for this
program line is processed, the indicator is set on. The indicator remains
on through detail time output, unless set off by the programmer. After
detail time output, all indicators used as record-identifying indicators are
set off. See Chapter 1, Understanding the Migration RPG Logic Cycle, for
more information on the RPG logic cycle.
7–4
Table 7–6 Columns 19 - 20 (Record-Identifying Indicator)

Allowable
Entries Explanation
Blank No record indicator specified.
01-99 Specifies a record-identifying indicator.
H1-H9 Specifies a halt indicator as a record-identifying indicator, indicating
that processing this record type is an error.
L1-L9 Specifies a control break indicator as a record identifying indicator.
This allows a record type rather than a field to signal the beginning
of a new control group.
LR Specifies the last record indicator as a record identifying indicator.
The program will terminate after processing this record unless the LR
setting is overridden by the programmer.
** Indicates that the fields described on the subsequent program lines
are look-ahead fields. Look-ahead fields can only be used with input
and update files. They cannot be specified for chained, demand,
full-procedural, or WORKSTN files.
DS Specifies a data structure definition. A data structure consists of
alphameric fields and can be 1 - 9999 characters in length. Data
structure definitions must appear as the last entries in the Input
specification section. See Chapter 16, Defining and Using Data
Structures, for more information on data structures.
7.10.1 Look-Ahead Fields

Look-ahead fields provide the following functionality:
• Determine when the last record of a control group is processed.
• Extend the matching-field processing capability.
An RPG program typically processes one record at a time, with only

the data from the current record available to the program. Using look-
ahead fields, it is possible to evaluate the data from the next record to be
processed and use this data to determine which operations to perform.
Any or all of the fields in a file can be specified as look-ahead fields. The
description applies to all records regardless of their record type. All fields
associated to a record definition with a double asterisk (**) in columns
19 - 20 are considered look-ahead fields. A look-ahead record definition
must have an alphabetic sequence code.
Look-ahead fields can be used only with input or update primary or
secondary files.
For input files, look-ahead fields contain data from the next record in the
file.
For update files, look-ahead fields apply to the next record in the file only
if the current record being processed was read from another file. If only
one file is being processed and it is an update file, the look-ahead fields
will contain data from the current record.
7–5
Look-ahead fields can be specified only once in a file.

Look-ahead field names must be unique. If the data specified in a look-
ahead field is to be used both as look-ahead information and as data after
the record has been read for normal processing, define the fields a second
time in another record using different field names.
When a look-ahead operation reaches end-of-file, it fills all look-ahead
fields associated to the file with 9’s. If a look-ahead field is 10 characters
long, it will contain the 9999999999 when end-of-file is reached.
Blank after (B in column 39) cannot be specified in the Output
specifications for look-ahead fields.
7.11 Columns 21 - 41 (Record-identification Conditions)

Columns 21 - 41 can be used to specify information used to define a record
type. If all records in a file are to be processed, regardless of type, or if all
records have the same type, leave columns 21 - 41 blank.
If a file contains more than one type of record, columns 21 - 41 are used
to identify the different records. Records are identified by matching
characters specified in columns 21 - 41 with corresponding characters in
the record.
Columns 21 - 41 are divided into three subsets. Each subset specifies four
fields. The fields are used to identify the position, data type, comparison
condition, and character used to identify the record. If more than one
subset is used, the record must satisfy all conditions before it will be
processed. Used in this way, the comparison conditions form an AND
relationship.
If a record cannot be identified by the program, a halt is issued. The user
is given the option of ignoring the record and continuing the program
or terminating the program. It is a good practice to define a catch-all
record as the last record in a set of Input specifications which define the
record layouts for a file. Columns 21 - 41 will be left blank in a catch-all
record, allowing it to accept any record which did not match the previous
definitions. This will avoid program halts.
Records are checked for a record type in the order in which they are
specified in the Input specification. The first set of record-identification
conditions which are satisfied by the input record will identify the record
type.
Columns 21 - 41 are divided into three subsections. Coding rules are the
same for all three subsections.
7.11.1 Columns 21 - 24, 28 - 31, 35 - 38 (Position)

Columns 21 - 24, 28 - 31, and 35 - 38 are used to define the position in the
record that will be compared to the character in columns 27, 34, and 41.
7–6
Table 7–7 Columns 21 - 24, 28 - 31, 35 - 38 (Position)

Allowable
Entries Explanation
Blank Indicates that there is no record-identification condition. In this case, make
sure that all of the other record identification columns in this subset are
blank as well.
1-9999 Defines the position in the input record that is to be compared to the
character specified in columns 27, 34, and 41. For example, the number
10 specified in columns 28 - 31 would indicate that position 10 of the input
record should be compared to the character specified in column 34.
The position entry must be numeric and right-justified. Leading zeros can
be omitted.
7.11.2 Columns 25, 32, 39 (Not)

Columns 25, 32, and 39 are used to indicate whether an identification
character must be present in the input record.
Table 7–8 Columns 25, 32, 39 (Not)

Allowable
Entries Explanation
Blank Indicates that the identification character must be present to identify a
record type. For example, if column 25 is left blank, the identification
character specified in column 27 must be present in the input record
in the position specified in columns 21 - 24.
N Indicates that the identification character must not be present to
identify a record type. For example, if an N is specified in column
39, the identification character specified in column 41 must not be
present in the input record in the position specified in columns 35 -
38.
7.11.3 Columns 26, 33, 40 (Character, Zone, or Digit)

Columns 26, 33, and 40 are used to specify what portion of the character
to use when identifying a record. The comparison can be carried out
using the entire character (C), the zone portion of the character (Z), or the
digit portion of the character (D). When establishing record-identification
conditions using the zone or digit option, keep in mind that the zone or
digit portion of many characters is the same. See Appendix A, Character
Sets, for a listing of the ASCII and EBCDIC character sets.
7–7
Table 7–9 Columns 26, 33, 40 (Character, Zone, or Digit)

Allowable
Entries Explanation
C The entire character is used to test the record identification condition.
Z The zone portion of the character is used to test the record-
identification condition.
D The digit portion of the character is used to test the record-
identification condition.
7.11.4 Columns 27, 34, 41 (Comparison Character)

Columns 27, 34, and 41 are used to specify an alphameric character which
is used as the identification character. This character will be compared to
the specified position in the input record.
Table 7–10 Columns 27, 34, 41 (Comparison Character)

Allowable
Entries Explanation
Any Specifies the character to be used in the identification condition.
character
7.11.5 Columns 14 - 16 (AND and OR Relationships)

Entering AND in columns 14 - 16 or entering OR in columns 14 and 15
associates two input specifications that specify an identification condition.
A maximum of three identifications characters can be specified on one
Input specification. An AND line can be used to continue the record-
identification condition from the previous line. All conditions must be
matched before the record-identifying indicator will be turned on.
If a record can be identified by more than one set of conditions, an OR line
is used to separate each set of record-identification conditions.
Table 7–11 Columns 14 - 16 (AND and OR Relationships)

Allowable
Entries Explanation
AND Specifies an AND relationship between the identification conditions
on the current program line and the previous program line.
OR Specifies an OR relationship between the record identification
conditions on the current program line and the previous program line.
When an AND is used, columns 7 - 13 and 17 - 20 must be left blank.

When an OR is used, columns 7 - 13 and 16 - 18 must be left blank.
7–8
A record-identifying indicator can be specified in columns 19 - 20 in an

OR line. If columns 19 - 20 are left blank, the record-identifying indicator
specified in the preceding program line will apply to the OR line.

Column 42 is not used. It should be left blank.
7.13 Columns 43 - 74 (Field Definitions)

Use columns 43 - 74 to describe the fields in each record. Field
descriptions must begin one line below the record description. Use a
separate line to describe each field.
7.13.1 Column 43 (Data Format)

Column 43 is used to describe the format in which the field defined in
columns 53 - 58 is stored.
Table 7–12 Column 43 (Data Format)

Allowable
Entries Explanation
Blank Indicates that the field contains either alphameric characters or
numeric data in a zoned-decimal or trailing numeric format.
P Indicates that the field contains numeric data stored in packed-
decimal format.
B Indicates that the field contains numeric data stored in binary format.
If the field being defined is an array containing packed or binary data, a P

or B should be coded in this column. The to and from columns (44 - 47, 48
- 51) should identify the physical positions the array occupies in the input
record. The unpacked length of each element in the array is defined in the
associated Extension specification.
7.13.2 Columns 44 - 47 and 48 - 51 (Field Start and End Positions)

Columns 44 - 47 and 48 - 51 are used to define the physical start and end
positions of a field in a record.
The maximum length of a field depends on the type of data it contains.
• The maximum length of a numeric field is 15.
• The length of a binary numeric field must be 2 or 4.
• The maximum length of a numeric packed-decimal field is 8. To
determine the packed length of a packed-decimal field, divide the
number of digits by 2 and add 1, ignoring the remainder. For example,
if the number of digits in packed-decimal field is 9, the packed length
is 5 (9/2+1).
7–9
• The maximum length of an alphameric field is 256.

• The maximum length of a data structure is 9,999 characters.
Fields can overlap as long as each field is given a different name.

Both start and end position entries must be right-justified and numeric.
Leading zeros can be omitted.
7.13.2.1 Columns 44 - 47 (Field From Location)

Columns 44 - 47 are used to define the physical starting position of a field
in a record.
Table 7–13 Columns 44 - 47 (Field From Location)

Allowable
Entries Explanation
1-9999 Specifies the beginning character position of the field.
7.13.2.2 Columns 48 - 51 (Field To Location)

Columns 48 - 51 are used to define the physical end position of a field in a
record.
Table 7–14 Columns 48 - 51 (Field To Location)

Allowable
Entries Explanation
1-9999 Specifies the ending character position of the field.
This entry must be greater than or equal to the start position entry in
columns 44 - 47. When specifying a one-character field, the start and end
position entries will be the same.
7.13.3 Column 52 (Decimal Positions)

Column 52 is used to identify a field as numeric and to specify the number
of digits to the right of the decimal point.
Table 7–15 Column 52 (Decimal Positions)

Allowable
Entries Explanation
Blank Indicates that this field contains alphameric data.
0-9 Specifies the number of positions to the right of the decimal point.
A value must be specified in this column for a numeric field even if the
field has no decimal points. In this case, specify a zero.
The number of decimal positions must be less than or equal to the number
of digits in the numeric field. If a number greater than the length of the
field is specified, the number of decimal positions is assumed to be equal
to the length of the field.
7–10
If a 2 is specified in this column and the field contains the data 12345, the
field’s value is interpreted as 123.45. If a 4 is specified in this column and
the field contains the data 12345, the field’s value is interpreted as 1.2345.
7.13.4 Columns 53 - 58 (Field Name)

Columns 53 - 58 are used to assign a name to the field defined in columns
43 - 52.
Table 7–16 Columns 53 - 58 (Field Name)

Allowable
Entries Explanation
Name Specifies the name of the field. The name can be a field name, array
name, or array element.
PAGE Specifies a page number.
PAGE1-
PAGE7
*INxx Specifies an indicator setting.
*IN,xx
All entries in columns 53 - 58 must be left-justified.

To eliminate duplicate coding, use OR in columns 15 and 16 of the record
specification to define the same field names for different record types.
It is only necessary to define the fields in a record which are going to be
used by the program.
7.13.4.1 Field Names

The field name can be any combination of one to six alphameric characters
except for blanks or special characters. The first character must be an
alpha character.
Reserved words, such as UDATE, UDAY, UMONTH, UYEAR, $UDATE,
$UDAY, $UMNTH, $UYEAR, PAGE, and PAGE1 - PAGE7 cannot be used
as field names.
Use a unique name for each field within a record. If a field name is
duplicated within a record, the RPG compiler will use the field definition
for the last field described.
Field names can be duplicated between records as long as both fields are
numeric with the same number of digits, or both fields are alphameric
with the same length.
An entire array can be loaded from an input record by entering the array
name in columns 53 - 58. When an array is specified, columns 59 - 62 and
65 - 70 must be left blank.
Individual array elements can be loaded by entering the array name
followed by a comma and an array index.
7–11
If a data structure name is specified as an input field in an input record,

the data format must be alphameric and the field length must match the
total length of the data structure.
Control break (columns 59 - 60), match-field (columns 61 - 62), and field
indicators (columns 65 - 70) are not valid for data-structure subfield
entries.
A data structure name cannot be specified as a subfield in a data structure.
7.13.4.2 PAGE, PAGE1 - PAGE7

The PAGE and PAGE1 - PAGE7 special words can be used to specify
automatic page numbering in a PRINT or PRINTER file. By default, these
fields are internally defined as 4 digit, zero-decimal, numeric fields. The
programmer has the option of redefining these fields as 1 to 15 character,
zero-decimal, numeric fields.
By default, the PAGE fields are initialized to zero when a program begins.
The field is incremented by one each time it is processed in the output
specifications before it is output. A PAGE field can be used just like any
other numeric field in the Calculation specifications.
The PAGE fields allow the programmer to control the numbering of report
pages. If a PAGE field is specified in the Input specifications, the value
placed in the field will be used as the starting page value. Eight PAGE
fields (PAGE, PAGE1, PAGE2, PAGE3, PAGE4, PAGE5, PAGE6, PAGE7)
are provided to permit the programmer to number different page types in
a report or to control page numbering on up to eight separate reports.
When specifying a value in a PAGE field, use the following rules:
• The value specified to initialize a PAGE field should always be one less
than the value the programmer wishes to have output. This is because
a PAGE field is always automatically incremented by one before it is
output. If a programmer wishes a report page to be output as page 15,
the associated PAGE field entry should be initialized to 14.
• PAGE field entries should always be numeric and right-justified.
7.13.4.3 *INxx, *IN,xx

Indicators 01 - 99 can be referenced as single-character, alphameric fields
using the *INxx field designations or by referencing the *IN indicator
array. If an indicator field or indicator array element is defined as an
input field, it must be a defined as a single-character, alphameric field.
If the entire indicator array is specified as an input field, it must be a
99-character, alphameric entry.
7.13.5 Columns 59 - 60 (Control break Indicator)

Columns 59 - 60 can be used to specify control break indicators. Control
break indicators cause RPG to compare the contents of a field with
the contents of the same field from a previous record. If the fields are
not equal, a control break occurs and RPG sets on the control break
indicator assigned to that field and all lower control break indicators. See
7–12
Section 1.4.2.2 in Chapter 1, Understanding the Migration RPG Logic

Cycle, for an example of the use of control break indicators.
Table 7–17 Columns 59 - 60 (Control break Indicator)

Allowable
Entries Explanation
Blank Indicates that this field is not a control field.
L1-L9 Associates a control break indicator with the field.
Control break indicators can only be specified for primary and secondary
files.
Control break indicators can be assigned in any order.
Control break indicators are ranked from highest (L9) to lowest (L1).
When a control break causes RPG to set on a control break indicator,
all lower control break indicators are set on as well. All control break
indicators are set off after detail time output.
Control fields are initialized to hexadecimal zeros. This usually causes a
control break to occur on the first record with a control field. Because of
this, RPG bypasses total-time calculation and output operations on the
first cycle.
Fields with different control break indicators can overlap in a record.
The same number of control fields do not need to be specified for all record
types.
Control break indicators cannot be specified for look-ahead fields.
When the same control break indicator is assigned to more than one field,
the fields are referred to as split-control fields. In this case, the fields
must be either all numeric or all alphameric and described on adjacent
lines. The fields used within split-control fields do not need to be the same
length.
The maximum length of a control field or split-control field is 144
characters.
The total length of a split-control field must be the same length as other
fields using the same control break indicator.
The decimal positions and sign of numeric fields are ignored when
determining a control break. Thus, the fields 257.8 and 2578 would be
considered equal. The fields -3049 and 3049 would also be considered
equal.
Field names are ignored when processing control fields. This allows the
same control break indicator to be assigned to multiple fields with the
same name.
If any one control field is numeric, all fields assigned to that control break
indicator will be treated as numeric when being compared, meaning that
only the digit portion of each character will be compared.
7–13
If a control field contains packed-decimal data, the unpacked length, which

is two times the packed-decimal length minus one, is considered the length
of the field for comparison purposes.
Input fields defined as binary (B in column 43) cannot be used as control
break fields.
7.13.6 Columns 61 - 62 (Matching Fields)

Columns 61 - 62 can be used to specify matching fields. Matching fields
can be used to compare fields in one or more files. When the contents of
a field from a primary file match the contents of a field from a secondary
file, the matching-record indicator (MR) is set on.
Table 7–18 Columns 61 - 62 (Matching Fields)

Allowable
Entries Explanation
Blank Indicates that this field is not a matching field.
M1-M9 Identifies a matching field.
Matching fields can be used with one file to perform sequence checking or
with multiple files to control the order in which records are processed.
Matching fields can only be specified for records in primary and secondary
input and update files.
Up to nine different fields can be specified as match fields in a single
record.
If more than one matching field is specified for a record type, all the fields
are logically concatenated and treated as one continuous field. The fields
are combined according to descending sequence (M9 - M1) of matching
field values.
The match codes M1 - M9 are not indicators. If a record is matched, the
matching-record indicator, MR, will be turned on. The MR indicator can
be used in the Calculation and Output specifications.
The program performs sequence checking for all record types with
matching field specifications. An error in sequence will generate a halt.
The user will be given the option of ignoring the mismatched record and
continuing, or terminating the program.
The same number of matching fields and the same matching field values
(M1 - M9) must be defined for all records that contain matching fields.
The maximum length of all matching fields combined cannot exceed 144
characters.
Matching fields can be overlapped in a single record.
When more than one matching code is used, all matching fields must
match before the matching-record indicator (MR) is set on.
7–14
Matching fields assigned the same matching code (M1 - M9) should be
either numeric with the same number of digits or alphameric with the
same length. If any single match field is numeric, all fields assigned that
match code will be treated as numeric fields when compared, meaning that
only the digit portion of the field will be compared.
Not all files or all record types within one program must have matching
fields defined. However, at least one record type from each of two files
must have matching fields defined if the files are to be matched.
If the matching field contains packed-decimal data, the unpacked length,
which is two times the packed length minus one, is considered the length
of the matching field for comparison purposes. It is valid to match a
packed field in one record against a zoned-decimal or trailing numeric field
in another if the unpacked lengths are equal. The length must always be
odd because the length of a unpacked, packed-decimal field is always odd.
The file sequence specified in column 18 of the File Description
specification must be the same for the files compared using matching
fields. All files must be in ascending or descending sequence.
The sequence of a single file can be checked using M1 - M9 codes to
designate the sequence check fields. If the file is out of sequence, a halt
occurs and the user has the option of ignoring the non-sequenced record or
terminating the program.
Look-ahead fields cannot be specified as matching fields.
If an alternate collating sequence is specified, it is used when comparing
the values in matching fields containing alphameric data.
Field names are ignored when carrying out match field compares, so fields
from different records can have the same name and match code.
When specifying an ascending sequence check, match fields are initialized
to hexadecimal zeros. When a descending sequence is specified, match
fields are initialized to hexadecimal FF’s. Numeric fields are initialized to
zero.
Numeric matching fields are compared based on their absolute values;
decimal positions and signs are ignored. Thus, the field 2.987 and 298.7
would be considered equal, as would the fields 2039 and -2039.
Matching fields cannot be split; the same matching field value (M1 - M9)
cannot be used more than once within one record.
Matching fields are independent from control break indicators.
7.13.7 Columns 63 - 64 (Field-Record-Relation Indicator)

Columns 63 - 64 are used to specify field-record-relation indicators. Field-
record-relation indicators control the conditions under which data is
extracted from the input buffer into a field. These conditions include
control breaks, matching fields, halts, and external indicators.
7–15
The most common use of a field-record-relation indicator is as a record-

identifying indicator to group several different record types in an OR
relationship and associate fields with a particular record type.
Table 7–19 Columns 63 - 64 (Field-Record-Relation Indicator)

Allowable
Entries Explanation
Blank Indicates no field-record-relation indicator.
01-99 Indicates that the field-record-relation indicator is a record-identifying
indicator.
L1-L9 Indicates that the field-record-relation indicator is a control break
indicator.
MR Indicates that the field-record-relation indicator is the matching-record
indicator.
U1-U8 Indicates that the field-record-relation indicator is an external
indicator.
H1-H9 Indicates that the field-record-relation indicator is a halt indicator.
Data will only be placed in a field with a field-record-relation indicator

defined if the specified indicator is on.
The following rules apply to field-record-relation indicators used with
control and matching fields:
• Control fields and matching fields must be specified without field-
record-relation indicators before those fields with them.
• When the field-record-relation indicator associated with a matching or
control field is on, that field is used as the control or matching field
for the record rather than the same control or matching field specified
without a field-record-relation indicator.
• When an entire set of matching fields has not been specified without
a field-record-relation indicator, a full set of matching fields must be
assigned to each field-record-relation indicator used with a matching
field.
• The same field-record-relation indicator must be used for split-control
fields. Split-control fields must be defined on consecutive lines.
• Control and matching fields that use field-record-relation indicators
must be grouped according to indicator.
• Only indicators 01 - 99 and H1 - H9 can be used as field-record-
relation indicators for control and matching fields. The field-record-
relation indicator for control and matching fields must be a record-
identifying indicator specified on either the preceding record definition
line or in one of the lines in an OR relationship.
If a program has two records with eight fields each, and the first seven
fields are the same but the last field is different, a record-identifying
indicator can be used as the field-record-relation indicator to condition the
field that is different, rather than defining all eight fields for both records.
7–16
7.13.8 Columns 65 - 70 (Field Indicators)

Columns 65 - 70 can be used to specify field indicators. Field indicators
check the contents of numeric or alphameric fields when they are extracted
from the input record.
Table 7–20 Columns 65 - 70 (Field Indicators)

Allowable
Entries Explanation
Blank Indicates no field indicators.
01-99 Associates a field indicator with a field.
H1-H9 Indicates that the field indicator is a halt indicator. Halt indicators can
be used to check for errors in data. For example, a halt indicator
could be specified to check for zeros in a numeric field. If a numeric
field is processed that contains zero, the halt indicator is set on and
the program halts. The user then has the option of ignoring the
record and continuing the program, or terminating the program.
Use columns 65 - 70 to check numeric fields.

Use columns 69 and 70 to check alphameric fields.
The same field indicator can be used for more than one field in different
record types. The status of the indicator depends on the record type last
read.
Columns 65 - 70 must be blank when columns 53 - 58 contain an entire
array or look-ahead fields.
One or more field indicators can be assigned to a numeric field.
Field indicators have the following meanings:
Table 7–21 Field Indicator Definitions

Columns Meaning Explanation
65 - 66 Plus If the field is numeric, the indicator is turned on if the data
entered is greater than zero.
67 - 68 Minus If the field is numeric, the indicator is turned on if the data
entered is less than zero.
69 - 70 Zero If the field is numeric, the indicator is turned on if the data
or entered is equal to zero.
Blank If the field is alphameric, the indicator is turned on if the
field is blank.
7.14 Columns 71 - 74 (No-op)

Columns 71 - 74 are not used. They should be left blank.
7–17

7–18
8 Calculation Specification (C)
The Calculation specification describes the calculations to be performed

and defines their order in the following ways:
• Entries in columns 7 - 17 control when a calculation is performed.
• Entries in columns 18 - 53 describe the type of calculation to perform.
• Entries in columns 54 - 59 specify which indicators the program sets
on or off as a result of the calculation.
There are two general rules:

1 Specify each calculation on a single line, arranging the calculations in
the order they are to be executed.
2 Specify detail time calculations first, then total time calculations and,
finally, calculations in subroutines.


Column 6 must always contain an C to identify a Calculation specification.

Allowable
Entries Explanation
the compiler.
8–1
Calculation Specification (C)
8.4 Columns 7 - 8 (Control Level)

Columns 7 - 8 are used to indicate whether the calculation is performed at
detail time, at total time, or as part of a subroutine.
Table 8–2 Columns 7 - 8 (Control Level)

Allowable
Entries Explanation
Blank Performs the calculation at detail time or indicates that the program
line is part of a subroutine.
L0 Performs the calculation at total time for each program cycle.
L1-L9 Performs the calculation:
• at total time after a control break occurs;
• when the SETON operation is used to set on the control-level
indicator;
• when the indicator is set on as a record-identifying indicator;
• when the indicator is set on as a resulting indicator in a
calculation.
LR Performs the calculation:
• at total time after the program processes the last record;
• when the SETON operation is used to set on the last-record
(LR) indicator;
• when the indicator is set on as a record-identifying indicator;
• when the indicator is set on as a resulting indicator in a
calculation.
SR Indicates that the calculation is part of a subroutine. Subroutine
specifications must appear at the end of the Calculation
specifications.
AN or OR Establishes an AND or OR relationship between the indicators
specified in columns 9 - 17 of the previous and current program
lines. If AN is used, the conditions for the indicators in both program
lines must be satisfied before the calculation will be executed. If OR
is used, the conditions for the indicators in one program line or the
other must be satisfied before the calculation is executed.
An unlimited number of AN or OR program lines with up to three
indicators on each line can be specified to condition a single
calculation. The last line in an AN or OR relationship specifies
the calculation. Columns 18 - 59 must be blank on all but the last
line.
8.5 Columns 9 - 17 (Conditioning Indicators)

Columns 9 - 17 can be used to specify indicators to condition the execution
of calculation lines. Up to three indicators can be specified on a program
line. Preceding an indicator with N causes the condition to be valid only
when the associated indicator is not on. Use columns 9 - 11 to describe
the first indicator, columns 12 - 14 to describe the second indicator, and
columns 15 - 17 to describe the third indicator. Using the indicators in
8–2
this way forms an AND relationship. Use AN and OR codes in columns

7 - 8 if it is necessary to condition a calculation operation with more than
three indicators or more than one set of conditions.
Table 8–3 Columns 9 - 17 (Conditioning Indicators)

Allowable
Columns Entries Explanation
9, 12, Blank Specifies that the associated indicator must
15 be on to make the condition true or that no
conditioning indicator has been specified.
N Not; specifies that the associated indicator
must not be on to make the condition true.
10 - 11, Blank Indicates that no conditioning indicator has
13 - 14, been specified. If columns 9 - 17 are all
16 - 17 blank, the operation will be executed for
every program cycle in which the indicator in
columns 7 - 8 is satisfied.
01 - 99 Indicates that a record-identification, field, or
resulting indicator defined elsewhere in the
program must be on or off to execute this
operation.
H1 - H9 Indicates that a halt indicator defined
elsewhere in the program must be on or
off to execute this operation.
KA - KN, Indicates that a command-key indicator
KP - KY defined elsewhere in the program must be
on or off to execute this operation.
L1 - L9 Indicates that a control break indicator
defined elsewhere in the program must be
LR Indicates that the last-record indicator must
be on or off to execute this operation.
MR Indicates that the matching-record indicator
must be on or off to execute this operation.
OA - OG, Indicates that an overflow indicator defined
OV elsewhere in the program must be on or off
to execute this operation.
RT Indicates that the return indicator defined
elsewhere in the program must be on or off
to execute this operation.
U1 - U8 Indicates that an external indicator must be
RPG performs total calculations for a control break before performing

detail time calculations for the record that causes the control break.
An indicator specified in columns 9 - 17 can also be specified as a resulting
indicator in columns 54 - 59 of the same line.
All conditions specified by the conditioning indicators must be met before
the associated operation will be performed.
8–3
8.5.1 Relationship Between Control Level and Conditioning Indicators

In a single program cycle, all operations conditioned by the control break
indicators in columns 7 - 8 are performed before the operations conditioned
by the control break indicators in columns 9 - 17.
When a control break indicator is specified in columns 9 - 17 instead
of in columns 7 and 8 of the Calculation specification, the operation is
performed during detail time processing, not total time processing.
If a calculation is conditioned with a last-record indicator in columns 9 - 17
when columns 7 - 8 are blank, the calculation is performed only if the last-
record indicator is set on during detail time calculations. If the last-record
indicator is set on when the program reaches end of file or during total
time calculations, detail time calculations are not performed.
When a control break indicator is specified in columns 7 - 8 and the
matching-record indicator in columns 9 - 17, MR indicates the result of
matching the previous record rather than the record just read that caused
the control break. All operations conditioned by control break indicators
are executed before determining the matching condition of the record just
read.
8.6 Columns 18 - 27 (Factor 1)

Columns 18 - 27 can be used to specify the first element acted upon by a
calculation operation. This element is called factor 1. Not all operations
need an element specified in factor 1, and some operations do not permit
an entry in factor 1. See Chapter 11, Operation Codes, for descriptions of
all of the operation codes supported by Migration RPG.
Table 8–4 Columns 18 - 27 (Factor 1)

Allowable
Entries Explanation
Field name Specifies any defined data field. These are the same fields that are
defined in columns 53 - 58 of an Input specification or in columns
43 - 48 of a Calculation specification.
Alphameric Specifies an alphameric constant. Alphameric literals can be up to
Literal eight characters in length, including blanks. Alphameric literals must
be enclosed in single quotation marks (for example, ’DIVIDE’). If
a single quote must be included in a literal, two consecutive single
quotes must be specified (for example, ’CAN’’T’). Alphameric
literals cannot be specified in arithmetic operations.
Numeric Specifies a numeric constant. Numeric literals can consist of the
Literal digits 0 through 9, one decimal point, and one arithmetic sign.
Numeric literals cannot exceed 10 digits in length and cannot contain
blanks. If a sign is specified, it must be the leftmost character in the
field. An unsigned numeric literal is treated as a positive number.
Numeric literals are handled in the same way as numeric fields.
Table or Specifies a table name, array name, or array element. Tables and
Array arrays are defined in Extension specifications.
8–4
Table 8–4 (Cont.) Columns 18 - 27 (Factor 1)

Allowable
Entries Explanation
Special Specifies one of the following special words: UDATE, UMONTH,

words UDAY, UYEAR, $UDATE, $UMNTH, $UDAY, $UYEAR, PAGE, and
PAGE1 - PAGE7.
Figurative Specifies figurative constants such as *BLANK, *BLANKS, *ZERO,
Constants and *ZEROS. *BLANK and *BLANKS can only be used with
alphameric fields. *ZERO and *ZEROS can be used with both
alphameric and numeric fields. The length of the figurative constant
is assumed to be either the length of the entry in factor 2 or the
result field, depending upon the operation being performed.
*INxx and Specifies a *INxx indicator field (*IN01 - *IN99) or a *IN,xx indicator
*IN,xx array element (*IN,01 - *IN,99).
Special Specifies the special qualifier *LIKE which is associated with the
Qualifier DEFN operation.
Label Specifies the label for TAG, BEGSR, and ENDSR operations.
All entries in factor 1 must be left-justified.
8.6.1 Factor 1 Restrictions

The following restrictions apply to entries in factor 1.
• If a data structure subfield is specified in factor 1, it cannot overlap a
data structure subfield specified in factor 2 or the result field. If a data
structure subfield references an entire array or an array element using
a variable index, the entire array is used to determine overlap.
• Figurative constants cannot be used with move zone operations, bit
operations, label operations, or the DEBUG, KEYnn, SETnn, and
SQRT operation codes.
8.7 Columns 28 - 32 (Operation Code)

Columns 28 - 32 are used to specify the operation code that indicates
which operation to perform on the elements specified in factor 1, factor
2, and the result field. Operation code entries must be left-justified. See
Chapter 11, Operation Codes, for more information on valid Migration
RPG operation codes.
Table 8–5 Columns 28 - 32 (Operation Code)

Allowable
Entries Explanation
Operation Performs the action specified by the operation code.
code
8–5
8.8 Columns 33 - 42 (Factor 2)

Columns 33 - 42 can be used to specify the second element acted upon by
a calculation operation. This element is called factor 2. Not all operations
need an element specified in factor 2, and some operations do not permit
an entry in factor 2. See Chapter 11, Operation Codes, for descriptions of
all of the operation codes supported by Migration RPG.
Table 8–6 Columns 33 - 42 (Factor 2)

Allowable
Entries Explanation
Field name Specifies any defined data field. These are the same fields that are
defined in columns 53 - 58 of an Input specification or in columns
43 - 48 of a Calculation specification.
Alphameric Specifies an alphameric constant. Alphameric literals can be up to
Literal eight characters in length, including blanks. Alphameric literals must
be enclosed in single quotation marks (for example, ’COLORADO’).
If a single quote must be included in a literal, two consecutive single
quotes must be specified (for example, ’IT’’S’). Alphameric literals
cannot be specified in arithmetic operations.
Numeric Specifies a numeric constant. Numeric literals can consist of the
Literal digits 0 through 9, one decimal point, and one arithmetic sign.
Numeric literals cannot exceed 10 digits in length and cannot contain
blanks. If a sign is specified, it must be the leftmost character in the
field. An unsigned numeric literal is treated as a positive number.
Numeric literals are handled in the same way as numeric fields.
Special Specifies one of the following special words: UDATE, UMONTH,
words UDAY, UYEAR, $UDATE, $UMNTH, $UDAY, $UYEAR, PAGE, and
PAGE1 - PAGE7.
Figurative Specifies figurative constants such as *BLANK, *BLANKS, *ZERO,
Constants and *ZEROS. *BLANK and *BLANKS can only be used with
alphameric fields. *ZERO and *ZEROS can be used with both
alphameric and numeric fields. The length of the figurative constant
is assumed to be either the length of the entry in factor 1 or the
result field, depending upon the operation being performed.
Label Specifies the label for CABxx, GOTO, and EXSR operations.
File Name Specifies the file name for a CHAIN, DEBUG, FORCE, READ,
READE, READP, or SETLL operation.
EXCPT Name Specifies the Output specification name for an EXCPT operation.
External Specifies the name of an external routine, subprogram, system
Routine service, or MSI-supplied subroutine called by a CALL, CALLV, or
or EXIT operation or defined by an EXTRN operation.
Subprogram
Name
All entries in factor 2 must be left-justified.
8–6
8.8.1 Factor 2 Restrictions

The following restrictions apply to entries in factor 2.
• If a data structure subfield is specified in factor 2, it cannot overlap a
data structure subfield specified in factor 1 or the result field. If a data
structure subfield references an entire array or an array element using
a variable index, the entire array is used to determine overlap.
• Figurative constants cannot be used with move zone operations, bit
operations, label operations, or the DEBUG, KEYnn, SETnn, and
SQRT operation codes.
8.9 Columns 43 - 48 (Result Field)

Columns 43 - 48 are used to provide the result field that will contain the
outcome of the operation specified in columns 18 - 42. A previously defined
field can be used to accept the results of an operation, or columns 49 - 52
can be used to define the field within the Calculation specification.
Table 8–7 Columns 43 - 48 (Result Field)

Allowable
Entries Explanation
Field name Specifies any defined data field. This can be any valid input field,
data structure name, data structure subfield, or a field defined in a
Calculation specification.
Special Specifies one of the following special words: PAGE, PAGE1 -
words PAGE7.
*INxx Specifies any valid RPG indicator if associated with an RLABL
operation.
Subroutine Specifies any valid subroutine name if associated with a CABxx or
Name CASxx operation.
All entries in the result field must be left-justified.

A result field name must begin with an alpha character. It can be one to
six characters long and can consist of alphameric characters. The name
cannot contain blanks.
If the result field is not defined elsewhere, it can be defined within the
Calculation specification using columns 49 - 52.
8–7
8.9.1 Result Field Restrictions

The following restrictions apply to entries in the result field.
• A look-ahead field, a field defined by an EXTRN operation, and the
fields UDATE, UDAY, UMONTH, UYEAR, $UDATE, $UMNTH,
$UDAY, and $UYEAR cannot be used as a result field.
• If a data structure subfield is specified in the result field, it cannot
overlap a data structure subfield specified in factor 1 or factor 2. If a
data structure subfield references an entire array or an array element
using a variable index, the entire array is used to determine overlap.
8.10 Columns 49 - 51 (Field Length)

Columns 49 - 51 can be used to specify the length of the result field if the
Calculation specification is used to define the result field. Otherwise, leave
columns 49 - 51 blank. To prevent truncated results, make sure the length
of the result field is long enough to hold the largest possible result.
Table 8–8 Columns 49 - 51 (Field Length)

Allowable
Entries Explanation
Blank Result field is not being defined in this Calculation specification.
1-256 Result field is being defined by this Calculation specification. The
entry specifies the length of the result field.
Any entry in this field must be numeric and right-justified. Leading zeros
can be omitted.
The maximum length for a numeric field is 15 digits.
The maximum length for an alphameric field is 256 characters.
If the field is described elsewhere in the program and an entry is made in
columns 49 - 51, both entries must specify the same length. If they do not,
the compiler will issue a warning message and use the first field definition
it encountered to define the field.
8.11 Column 52 (Decimal Positions)

Column 52 can be used to define a result field as alphameric or numeric
and to define the number of decimal positions in the field if it is numeric.
8–8
Table 8–9 Column 52 (Decimal Positions)

Allowable
Entries Explanation
Blank Indicates that this field contains alphameric data or that the result
field has been defined elsewhere.
0-9 Specifies that the field is numeric and indicates the number of
positions to the right of the decimal point. If the field has no decimal
positions, specify a zero for the decimal entry.
If the field has been described previously in the program and an entry is
made in column 52, both entries for decimal positions must be the same.
If they are not, the compiler will issue a warning message and use the first
valid field definition for all occurrences of the field.
The number of decimal positions must be less than or equal to the length
of the field.
If the result field contains alphameric data, leave this column blank.
When the result is numeric, but has no decimal positions, a zero must be
specified in this column.
8.12 Column 53 (Half-adjust)

Column 53 can be used to specify whether to round numeric data in the
result field of an arithmetic operation.
Table 8–10 Column 53 (half-adjust)

Allowable
Entries Explanation
Blank Performs no half-adjusting.
H Half-adjusts the numeric data in the result field.
The half-adjust operation can only be used on the numeric results of

arithmetic operations. It cannot be specified on MVR (Move Remainder)
operations or on DIV operations immediately followed by MVR operations.
The half-adjust operation is carried out by adding the decimal position
to the right of the last specified decimal position in the result field to the
same position and then truncating result. For example, if the result of a
MULT operation was 248.9772, and the result field was defined as having
2 decimal positions and half-adjust, .007 would be added to the result field
field, giving 248.9842. The field would then be truncated to 248.98.
By default, decimal positions to the right of the last defined decimal
position in the result field are truncated. In the previous example, if half-
adjust had not been specified, the contents of the result field would have
been truncated to 248.97.
Resulting indicators are set according to the value of the result field after
half-adjusting.
8–9
8.13 Columns 54 - 59 (Resulting Indicators)

Columns 54 - 59 can be used to enter resulting indicators that indicate the
outcome of an operation. These indicators can then be used to condition
other calculation or output operations, or to establish field-record relations.
Some operations require the specification of one or more indicators.
Table 8–11 Columns 54 - 59 (Resulting Indicators)

Allowable
Entries Explanation
01-99 Uses any standard indicator as a resulting indicator.
H1-H9 Uses a halt indicator as a resulting indicator.
KA-KN Uses a command-key indicator as a resulting indicator.
KP-KY
L1-L9 Uses a control break indicator as a resulting indicator.
LR Uses the last-record indicator as a resulting indicator.
OA-OG, OV Uses an overflow indicator as a resulting indicator.
RT Uses the return indicator as a resulting indicator.
U1-U8 Uses an external indicator as a resulting indicator.
A resulting indicator is set on if the condition specified is satisfied. If the

specified condition is not satisfied, the resulting indicator is usually set
off. See Chapter 11, Operation Codes, for information on how resulting
indicators are used with each operation code.
If the same indicator is used to test the results of more than one operation,
the last operation determines the indicator setting.
Resulting indicators cannot be specified when the result field contains a
non-indexed array.
After a resulting indicator is on, it remains on until one of the following
occurs:
• The operation is repeated and the result resets the indicator.
• The indicator is set off by another operation.
• The indicator is used as a record-identification or field indicator in
Input specifications and is set off during input of a new record.
Using a control break indicator (L1 - L9) as a resulting indicator does not
automatically set on lower-level, control break indicators.
Using an external indicator (U1 - U8) as a resulting indicator allows the
indicator to be set; it can then be tested after the program exits.

8–10
9 Output Specification (O)
The Output specification is used to describe the records and fields in an

output file and the conditions under which data is output. Output can
occur with the following types of files:
• Add files (A in column 66 of the File Description specification).
• Combine files (C in column 15 of the File Description specification).
• Output files (O in column 15 of the File Description specification).
• Update files (U in column 15 of the File Description specification).
An Output specification is similar to an Input specification in that it can

be divided into two general categories. Columns 7 - 37 are used to describe
output records. Columns 23 - 74 are used to describe output fields. Field
description entries always begin one line below record description entries.


Column 6 must always contain an O to identify an Output specification.

Allowable
Entries Explanation
the compiler.
9–1
Output Specification (O)

Columns 7 - 14 are used to specify the name of the output file. The name
must be the same as the file name specified in columns 7 - 14 of the File
Description specifications.

Allowable
Entries Explanation
File name Identifies the name of the output file.
The file name must match a file name specified in the File Description
specifications. Valid output files are add, combine, output, or update files.
If columns 7 - 14 are blank, the compiler assumes that the information in
this program line describes a field or record from the file last named.
All the records for a single file need not be described together.
9.5 Columns 14 - 16 (AND/OR)

Columns 14 - 16 can be used to specify AND or OR conditions, which are
used to link output lines together, allowing more than three conditioning
indicators to be used to condition an output record.
Table 9–3 Columns 14 - 16 (AND/OR)

Allowable
Entries Explanation
AND Performs the output operation when the conditions for all indicators
in columns 23 - 31 in both program lines are met.
OR Performs the output operation when the conditions for all indicators
in columns 23 - 31 in either program line are met.
AND and OR qualifiers can only be used to associate Output specifications

for an output record. They cannot be used to allow an output field to
be conditioned by more than three indicators. A maximum of three
conditioning indicators is allowed on an output field.
At least one conditioning indicator must be specified on a program line in
an AND or OR relationship.
If an AND is specified, columns 17 - 22 must be left blank.
If AND or OR is specified, columns 7 - 13 must be blank.
An unlimited number of AND or OR lines can be used to condition an
output record.
9–2
9.6 Column 15 (Record Type)

Column 15 is used to specify the type of record to be output. An entry
in column 15 is required for every output record defined in the Output
specifications.
Table 9–4 Column 15 (Record Type)

Allowable
Entries Explanation
Blank Indicates that this program line describes a field or constant.
H Indicates that this program line describes a heading record.
D Indicates that this program line describes a detail record.
T Indicates that this program line describes a total record.
E Indicates that this program line describes an exception record.
A record type must be specified for every output record.

Records of the same type are tested for output and written in the order in
which they are specified in the Output specifications.
9.6.1 Heading Records

Heading records are normally used to describe the heading information
in a report, such as column names, page numbers, and the date. Heading
records are usually output during first-cycle processing and after a control
break or overflow condition has been processed.
9.6.2 Detail Records

Detail records usually contain data from input and calculation operations
performed at detail time. Detail records are usually output during detail
time output.
9.6.3 Total Records

Total records usually contain the data from the result of calculations on
several detail records. Total records are usually output during a control
break or overflow condition and during the last cycle.
9.6.4 Exception Records

Exception records are output records which have their output directly
controlled from the Calculation specifications. To output an exception
record, the EXCPT operation must be specified in a Calculation
specification. See Chapter 11, "Operation Codes", for more information
on the use of the EXCPT operation code.
9–3
9.7 Columns 16 - 18 (ADD/DEL)

Columns 16 - 18 can be used to specify that a record is to be added or
deleted from a file.
Table 9–5 Columns 16 - 18 (ADD/DEL)

Allowable
Entries Explanation
Blank The record is being output to an output file, updated in an update
file, or this is an output field definition.
ADD Adds a record to an input, output, or update file with an A specified
in column 66 of the File Description specification.
DEL Deletes the last record read in an update file with an indexed or
relative file organization.
The file associated with an ADD record must have an A specified in

column 66 of the File Description specification.
ADD or DEL must appear on the same line that defines the record type for
the record that is to be added or deleted.
An ADD or DEL operation applies to all AND and OR relations specified
for the output record.
The DEL operation can only be performed on an update file. The DEL
operation cannot be performed on a sequential file. The DEL operation
deletes the last record input from the update file. When a record is
deleted, it is physically removed from the data file. It cannot be recovered.
ADD and DEL operations are only valid for DISK files.
9–4
9.8 Column 16 (Fetch Overflow or Release)

Column 16 can be used to specify fetch overflow for a PRINT or PRINTER
file. Fetch overflow causes RPG to check whether the overflow indicator
assigned to the printer output file is on before printing total, detail,
or exception records. See Chapter 14, Using Printer Output Files, for
information on overflow.
Table 9–6 Column 16 (Fetch Overflow or Release)

Allowable
Entries Explanation
Blank No fetch overflow processing is performed on this Output
specification.
F Executes the overflow routine if overflow has occurred.
An entry in this column is valid only for printer output files with overflow
lines.
Do not specify an overflow indicator on the same line as fetch overflow.
If an overflow indicator is specified in columns 23 - 31 of the same
specification, the overflow routine will not be fetched for the specification.
If an OR relationship is specified between two lines, each output record
defined by the OR relationship that is to use fetch overflow must have an
F specified in column 16.
RPG fetches an overflow routine when overflow occurs and all conditions
specified by the indicators in columns 23 - 31 of the Output specification
are met. When fetch overflow is specified, only overflow output associated
with the file containing the executed fetch routine is output. The overflow
routine does not automatically advance to the next page.
9–5
9.9 Column 17 (Space Before)

Column 17 can be used to specify the number of lines to be spaced before a
line is printed in a PRINT or PRINTER file.
Table 9–7 Column 17 (Space Before)

Allowable
Entries Explanation
Blank Does not advance before printing a line of output.
0-9 Specifies the number of lines the printer will advance before printing
a line of output. A value of zero allows overprinting.
Column 17 must be left blank for an AND line.

Spacing to or past the overflow line causes RPG to set on the overflow
indicator.
9.10 Column 18 (Space After)

Column 18 can be used to specify the number of lines to be spaced after a
line is printed in a PRINT or PRINTER file.
Table 9–8 Column 18 (Space After)

Allowable
Entries Explanation
Blank Advances one line after printing a line of output.
0-9 Specifies the number of lines the printer will advance after printing a
line of output. A value of zero allows overprinting.
Column 18 must be left blank for an AND line.

Spacing to or past the overflow line causes RPG to set on the overflow
indicator.
9–6
9.11 Columns 19 - 20 (Skip Before)

Columns 19 - 20 can be used to specify the line to skip to in a PRINT or
PRINTER file before printing a record.
Table 9–9 Columns 19 - 20 (Skip Before)

Allowable
Entries Explanation
Blank Specifies no skipping before printing a line of output.
01-99 Causes the printer file to skip to line 01 - 99 before outputting a
record.
A0-A9 Causes the printer file to skip to line 100 - 109 before outputting a
record.
B0-B2 Causes the printer file to skip to line 110 - 112 before outputting a
record.
Entries can be specified in all space and skip columns for a single program
line. If this is done, the entries are executed in the following order: skip
before, space before, print the output line, skip after, and space after.
Specifying a skip before entry past the overflow line causes RPG to set on
the overflow indicator.
If a skip before entry is specified on the same line number that the printer
is currently on, no skipping takes place.
If a skip before entry is specified to a line number less than the current
line number, the printer advances to that line number on the next page.
The skip entry cannot exceed the entry for forms length (columns 18 - 19
of the Line Counter specification). If there is no Line Counter specification,
the skip entry cannot exceed the default of 66 lines.
Columns 19 - 20 must be left blank for an AND line.
If columns 19 - 20 are left blank for an OR line, the entries made for the
previous record will be applied to the OR line.
9–7
9.12 Columns 21 - 22 (Skip After)

Columns 21 - 22 can be used to specify the line to skip to in a PRINT or
PRINTER file after printing a record.
Table 9–10 Columns 21 - 22 (Skip After)

Allowable
Entries Explanation
Blank Specifies no skipping after printing a line of output.
01-99 Causes the printer file to skip to line 01 - 99 after outputting a record.
A0-A9 Causes the printer file to skip to line 100 - 109 after outputting a
record.
B0-B2 Causes the printer file to skip to line 110 - 112 after outputting a
record.
Entries can be specified in all space and skip columns for a single program
line. If this is done, the entries are executed in the following order: skip
before, space before, print the output line, skip after, and space after.
Specifying a skip after entry past the overflow line causes RPG to set on
If a skip after entry is specified on the same line number that the printer
If a skip after entry is specified to a line number less than the current line
number, the printer advances to that line number on the next page.
Columns 21 - 22 must be left blank for an AND line.
If columns 21 - 22 are left blank for an OR line, the entries made for the
previous record will be applied to the OR line.
9–8
9.13 Columns 23 - 31 (Output Indicators)

Columns 23 - 31 can be used to specify indicators to condition the output
of records and fields. Up to three indicators can be specified on an Output
specification. Preceding an indicator with N causes the condition to be
valid only when the associated indicator is not on. Use columns 23 - 25
to describe the first indicator, columns 26 - 28 to describe the second
indicator, and columns 29 - 31 to describe the third indicator. Using
the indicators in this way forms an AND relationship. Use AND or OR
codes in columns 14 - 16 if it is necessary to condition an output record
definition with more than three indicators. Output field definitions can be
conditioned by a maximum of three indicators.
9–9
Table 9–11 Columns 23 - 31 (Output Indicators)

Allowable
Columns Entries Explanation
23, 26, Blank Specifies that the associated indicator must be on to
29 make the condition true or that no conditioning indicator
has been specified.
N Not; specifies that the associated indicator must not be
on to make the condition true.
24 - 25, Blank Indicates that no conditioning indicator has been
27 - 28, specified.
30 - 31
01 - 99 Indicates that a record-identification, field, or resulting
indicator defined elsewhere in the program must be on
or off to output this record or field.
1P Indicates that the first-page indicator is being used. The
first-page indicator is on only during the first program
cycle. It cannot be controlled by the programmer. Output
of a record or field will be based on the setting of this
indicator.
H1 - H9 Indicates that a halt indicator defined elsewhere in the
program must be on or off to output this record or field.
KA - KN, Indicates that a command-key indicator defined
KP - KY elsewhere in the program must be on or off to output this
record or field.
L0 Indicates that the L0 indicator is being used. The L0
indicator is always on. It cannot be controlled by the
programmer. Output of a record or field will be based on
the setting of this indicator.
L1 - L9 Indicates that a control break indicator defined elsewhere
in the program must be on or off to output this record or
field.
LR Indicates that the last-record indicator must be on or off
to output this record or field.
MR Indicates that the matching-record indicator must be on
or off to output this record or field.
OA - OG, Indicates that an overflow indicator defined elsewhere in
OV the program must be on or off to output this record or
field.
RT Indicates that the return-from-subprogram indicator must
be on or off to output this record or field.
U1 - U8 Indicates that an external indicator must be on or off to
output this record or field.
9–10
When conditioning an entire record, enter the indicator on the line that
specifies the record type (column 15). When conditioning a field, enter the
indicator on the same line as the field name (columns 32 - 37).
If more than one indicator is specified on a line, the indicators form an
AND relationship.
Overflow indicators can be used on AND or OR lines; however, only one
overflow indicator can be associated with a group of output indicators. If
a line is to be considered an overflow line, the overflow indicator must
appear on the main specification line or on an OR line.
If an overflow indicator is used, it must be the same one assigned to the
file on the File Description specification.
Overflow indicators cannot be used to condition exception output lines, but
they can be used to condition fields in an exception record.
Note that RPG outputs those detail and heading lines conditioned by
the first-page (1P) indicator, no indicator, or all negative indicators (N in
columns 23, 26, or 29) before reading the first record from a file. Therefore,
use the 1P indicator to condition only heading and detail output lines that
do not depend on data from an input record. For a line with no indicators
or all negative indicators that requires data from an input record, use a
negative first-page indicator (N1P in columns 23 - 31) to prevent the line
from being output before reading the first record.
Because the 1P indicator is set off after the first detail time output, it
should only be used to condition heading and detail lines.
If a control break indicator is used with a total record and no overflow
indicator, the record is output when a control break occurs and after
the last record of a control group has been processed. If a control break
indicator is used with a detail record and no overflow indicator, the record
is output when a control break occurs and after the first record of a new
control group has been processed. If a control break indicator is used with
an overflow indicator, the record is output when a control break occurs and
the overflow line has been passed.
9–11
9.14 Columns 32 - 37 (Field Name)

Columns 32 - 37 can be used to specify a field name, table name, array
name or element, data structure name, special word, or EXCPT name for
output.
Table 9–12 Columns 32 - 37 (Field Name)

Allowable
Entries Explanation
Blank Indicates that this is a record definition or that there is a constant in
columns 45 - 70.
Name Specifies the name of the field to be output or the name of an
EXCPT record. A field name can be a data field name, table or array
name, array element, data structure name, or one of the following
special words: PAGE, PAGE1 - PAGE7, UDAY, UMONTH, UYEAR,
UDATE, $UDAY, $UMNTH, $UYEAR, $UDATE, *INxx, and *PLACE.
Left justify this entry.
9.14.1 Output field names

All field names must have been previously defined in an Input,
Calculation, or Extension specification.
A field name cannot be entered if a constant is entered in columns 45 -
70. If the field being output is a numeric field, an edit word can appear in
columns 45 - 70.
If a field name is entered in columns 32 - 37, columns 7 - 22 must be
blank.
If a non-indexed array name is specified, the entire array is output.
If a data structure name is specified, the entire data structure is output.
Output fields can be specified in any order in the Output specifications.
The order they are placed in the output record is determined by the
entry in columns 40 - 43. For ease in reading the RPG program, it is
recommended that Output specifications be written in the order the fields
are to be output.
If output fields overlap, the last field specified in the Output specifications
will overlay data in all previous fields that it overlaps.
The sign of a numeric field is stored in the units position of the rightmost
digit in the field. If the field contains a negative value when output to a
printer file, this digit prints as an alpha character (}, J - R) unless an edit
code or edit mask has been specified.
A field name can be 1 - 6 characters long.
9–12
9.14.2 Output Special Words

The special words PAGE, PAGE1 - PAGE7, *PLACE, UDATE, UDAY,
UMONTH, UYEAR, $UDAY, $UMNTH, $UYEAR, and $UDATE can all be
used in the Output specifications. These predefined fields are described in
detail in the following sections.
9.14.2.1 PAGE, PAGE1 - PAGE7 Special Words

The PAGE special words are used to specify automatic page numbering in
a PRINT or PRINTER file. If a PAGE field is specified in the Output
specifications without being defined elsewhere in the program, it is
assumed to be a 4-digit numeric field with zero decimal positions. A
PAGE field can also be defined and used in the Input and Calculation
specifications. It can be defined as a numeric field with 1 - 15 digits. A
PAGE field should always have zero decimal positions.
By default, a PAGE field is initialized to zero. It is incremented by one
each time it is output. The field is incremented before it is output. If a
PAGE field is being initialized by the program, it should be initialized to a
value one less than the first value to be output. For example, if the first
page number to be output is to be 10, the PAGE field should be initialized
to 9.
Page numbering can be reset at any time in a program. Remember to
initialize the field to a value one less than the initial desired output value.
A PAGE field can be initialized in the Output specifications by specifying
indicator conditions in columns 23 - 31 or by specifying blank-after in
column 39. If the indicator conditions are met or blank-after is specified,
the PAGE field is initialized to zero and one is added before the field is
printed.
Eight PAGE special words (PAGE, PAGE1 - PAGE7) are available for use
in a program. They can be used to specify different page numbering for
various types of output to a single report, or they can be used to control
page numbering in several reports being produced by one program.
Leading zeros are replaced with blanks by default when a PAGE field is
output to a PRINT or PRINTER file.
9–13
9.14.2.2 *PLACE Special Word

The *PLACE special word can be used to repeat a set of fields in the
Output specifications. Using the *PLACE special word, the following two
sections of output code will produce the same results.
In the first set of Output specifications, the fields HOTFT, DNCSTP, and
QCKFT are output twice by specifying each field twice.
Example 9–1 *PLACE Special Word Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
OREPORT D
O HOTFT 10
O DNCSTP 15
O QCKFT 25
O HOTFT 35
O DNCSTP 40
O QCKFT 50
O BALLRM 75
In the second set of Output specifications, the fields HOTFT, DNCSTP, and
QCKFT are output twice by specifying the *PLACE special word to replace
the second set of output field definitions. Note that the end position of the
*PLACE field accounts for the total size of all three fields it is duplicating.
This code will produce the same results as the code in the first output
example.
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
OREPORT D
O HOTFT 10
O DNCSTP 15
O QCKFT 25
O *PLACE 50
O BALLRM 75
A *PLACE special word repeats all fields in a record which preceded it.
The end position specified for a *PLACE special word indicates where the
fields being repeated by the *PLACE operation will end. Be sure the end
position specified accounts for the length of all of the fields being repeated
to prevent field overlapping.
The *PLACE special word can be repeated to duplicate field definitions
more than once within a output record.
Additional fields and constants can be specified following a *PLACE
special word. These items will not be affected by the *PLACE operation.
9–14
9.14.2.3 UDATE, UMONTH, UDAY, and UYEAR Special Words

The UDATE special words, UDATE, UMONTH, UDAY, UYEAR, $UDATE,
$UMNTH, $UDAY, and $UYEAR, can be used to specify the current
process date within an RPG program. By default, this date is the same
as the system date. However, the REX Utility allows the system date to
be overridden with a user-specified process date. See the Migration RPG
User’s Guide for more information concerning the use of the REX Utility.
Note: The $UDATE, $UDAY, $UMNTH, and $UYEAR reserved words are
supplied to provide backward compabitility with 6-digit non-
Year 2000 compliant dates. See the Migration RPG Year 2000
Compliance Guide for more information concerning these fields.
Because the system date can be overridden using the REX Utility, the date
returned by the UDATE or $UDATE special words may not be the same
date as that returned by the date portion of the TIME or $TIME operation
codes. The TIME and $TIME operation code always returns the system
date.
The contents of the UDATE fields cannot be modified within the program.
These fields are commonly used for comparison and output purposes.
The process date is returned in the UDATE and $UDATE field. The
UDATE field is defined as a Year 2000 compliant 8-digit, zero-decimal,
numeric field. The date is returned in one of the following formats:
• mm/dd/yyyy (default)
• yyyy/mm/dd
• dd/mm/yyyy
The $UDATE field is defined as a non-Year 2000 compliant 6-digit, zero-

decimal, numeric field. The date is returned in one of the following
formats:
• mm/dd/yy (default)
• yy/mm/dd
• dd/mm/yy
The format the process date is returned in depends upon the setting placed
in columns 19 - 21 of the Control specification. See sections 3.8, 3.9, and
3.10 in Chapter 3, Control Specification (H), for more information on how
to specify the format in which a process date is returned.
The UMONTH and $UMNTH fields specify the month portion of the
process date. These fields are defined as a 2-digit, zero-decimal, numeric
fields.
The UDAY and $UDAY fields specify the day portion of the process date.
These fields are defined as a 2-digit, zero-decimal, numeric fields.
The UYEAR and $UYEAR fields specify the year portion of the process
date. The UYEAR field is defined as a Year 2000 compliant 4-digit, zero-
decimal, numeric field. The $UYEAR field is defined as a non-Year 2000
compliant 2-digit, zero-decimal, numeric field.
9–15
9.14.3 Output EXCPT Names

When the output record type is an exception record (indicated by an E in
column 15), a name can be placed in columns 32 - 37 of the record line.
The EXCPT operation can specify the name in factor 2. The name is called
an EXCPT name.
Table 9–13 Output EXCPT Names

Allowable
Entries Explanation
Blank Identifies exception output records to be checked for output when an
EXCPT operation with a blank factor 2 is executed.
Name Identifies exception output records to be checked for output when an
EXCPT operation with the same name in factor 2 is executed.
An EXCPT name must follow the rules for field names.

An EXCPT name cannot be the same as a file name, field name, data
structure name, array name, table name, label, or subroutine name.
One or more output records can use the same EXCPT name. The records
do not have to be consecutive records in the Output specifications.
An EXCPT record is only output if the EXCPT name is matched and the
conditioning indicators in columns 23 - 31 are satisfied.
An EXCPT name is specified on the main record line. It applies to all
associated AND and OR lines.
9–16
9.15 Column 38 (Edit Codes)

Column 38 can be used to specify an edit code. Edit codes can be used to
edit a numeric field without specifying an edit word. Table 9–14 defines
valid edit codes. Table 9–15 gives examples of edit code output.
Table 9–14 Column 38 (Edit Codes)

Allowable
Entries Explanation
1 Prints a number with commas before every third digit to the left of
the decimal point, prints a zero balance, and suppresses signs and
leading zeros.
2 Prints a number with commas before every third digit to the left of
the decimal point and suppresses a zero balance, signs, and leading
zeros.
3 Prints a number without commas, prints a zero balance, and
suppresses signs and leading zeros.
4 Prints a number without commas and suppresses a zero balance,
signs, and leading zeros.
A Prints a number with commas before every third digit to the left of
the decimal point, prints a zero balance, uses CR to represent a
negative sign, and suppresses leading zeros.
B Prints a number with commas before every third digit to the left of
the decimal point, suppresses a zero balance, uses CR to represent
a negative sign, and suppresses leading zeros.
C Prints a number without commas, prints a zero balance, uses CR to
represent a negative sign, and suppresses leading zeros.
D Prints a number without commas, suppresses a zero balance, uses
CR to represent a negative sign, and suppresses leading zeros.
J Prints a number with commas before every third digit to the left of
the decimal point, prints a zero balance, prints a negative sign, and
suppresses leading zeros.
K Prints a number with commas before every third digit to the left of
the decimal point, suppresses a zero balance, prints a negative sign,
and suppresses leading zeros.
L Prints a number without commas, prints a zero balance, prints a
negative sign, and suppresses leading zeros.
M Prints a number without commas, suppresses a zero balance, prints
a negative sign, and suppresses leading zeros.
X Performs no editing.
Y Edits a date field using the format mm/dd/yy or mm/dd/yyyy. The
format dd/mm/yyyy or dd/mm/yy is used if inverted print has been
specified. The format chosen depends on the size of the date field
(6 or 8 digits). If the first digit of a date field is zero, it is suppressed.
Z Suppresses signs and leading zeros.
9–17
If an edit code is specified in column 38, columns 45 - 70 must be blank

unless an edit code modifier is specified.
If an edit code is used to edit an array, it is applied to each element in the
array. Two spaces are placed between each element in the array when it is
output.
Edit codes cannot be used on numeric data in packed, binary, or zoned-
decimal format (P, B, or Z in column 44).
To prevent overlapping of the output fields, leave enough space for the
characters the edit code will insert into the output field.
Unedited numeric output fields with negative values are output with the
overpunched representation of the sign. For example, -1 will be output as
J, -2 as K, and so on. Therefore, use an edit code or edit word to prevent
the output of an overpunched representation of a sign.
Table 9–14 shows the results of several edit code examples.
Table 9–15 Edit Codes and Examples

Edit Print Zero
Code +12345.67 +1234567 -1234.567 -1234567 Balance
none 1234567 1234567 123456P 123456P yes
1 12,345.67 1,234,567 1,234.567 1,234,567 yes
2 12,345.67 1,234,567 1,234.567 1,234,567 no
3 12345.67 1234567 1234.567 1234567 yes
4 12345.67 1234567 1234.567 1234567 no
A 12,345.67 1,234,567 1,234.567CR 1,234,567CR yes
B 12,345.67 1,234,567 1,234.567CR 1,234,567CR no
C 12345.67 1234567 1234.567CR 1234567CR yes
D 12345.67 1234567 1234.567CR 1234567CR no
J 12,345.67 1,234,567 1,234.567- 1,234,567- yes
K 12,345.67 1,234,567 1,234.567- 1,234,567- no
L 12345.67 1234567 1234.567- 1234567- yes
M 12345.67 1234567 1234.567- 1234567- no
9–18
9.16 Column 39 (Blank After)

Column 39 can be used to specify blank after, which initializes a field after
it has been output. Alphameric fields are initialized to blanks and numeric
fields are initialized to zeros. Specifying blank after is especially useful
when accumulating control group totals.
Table 9–16 Column 39 (Blank After)

Allowable
Entries Explanation
Blank The field is not initialized after output.
B Causes the field to be initialized after being output.
Column 39 must be blank for look-ahead fields, fields defined by an

EXTRN operation, constants, and the following special words: UDATE,
UDAY, UMONTH, UYEAR, $UDATE, $UDAY, $UMNTH, $UYEAR, and
*PLACE.
If indicators condition the output field, the same indicators condition the
blank after operation. The field will not be initialized unless it is output.
If blank after is to be specified for a field that is to be output more than
once during a cycle, enter B in column 39 on the last line specifying output
for the field. Otherwise, the field will be initialized before all occurrences
where it is output have been processed.
9–19
9.17 Columns 40 - 43 (End Position in Output Record)

Columns 40 - 43 are used to indicate the location of an output field or
constant in an output record.
Table 9–17 Columns 40 - 43 (End Position in Output Record)

Allowable
Entries Explanation
Blank Indicates that the Output specification is a record definition or that
the RPG compiler is to calculate the end position for the field.
1-9999 Indicates the position in the output record of the rightmost character
of an output field or constant.
K1-K8 Indicates that a WORKSTN screen format name begins in column
45. The format name can be 1 - 8 characters in length.
The end position is the location of the rightmost character in the output
field. For example, if a field contains 26 characters and 40 is specified as
the field end position, the field would be placed in the output record as
follows:
Example 9–2 Output field end position in an output record
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
Colorado Springs, Colorado
The numbers above this example are for reference only; they do not appear
in the output record.
Use K in column 42 if a WORKSTN screen format name is being specified.

The end position entry must be right-justified. Leading zeros can be
omitted.
If fields overlap, the last field specified on the Output specification is the
only field that is completely written.
When specifying the end position for an array, use the rightmost position
of the last element in the array.
The end position specified for an output field must be equal to or greater
than the total length of the field, including any edit characters. If it is not,
the compiler will issue an error message.
The end position must be less than or equal to the record length (columns
24 - 27 of the File Description specification) of the file to which the record
belongs. If it is not, the compiler will issue an error message.
Be sure to allow enough room for the number of characters in each output
field and for any editing characters specified using an edit code or edit
word.
If columns 40 - 43 are left blank and a field or constant is specified for
output, the RPG compiler will calculate the field end position based on the
field length and the end position of the previous field.
9–20
9.18 Column 44 (Output Data Format)

If an output field contains numeric data, column 44 can be used to specify
that the field be output in a packed-decimal, binary, trailing numeric, or
zoned-decimal data format. Packed decimal and binary formats conserve
disk space.
Table 9–18 Column 44 (Output Data Format)

Allowable
Entries Explanation
Blank Indicates that the field contains either alphameric data or numeric
data that is to be output in a trailing numeric format. Trailing numeric
is the default output format for numeric fields and arrays if an output
data format is not specified in column 44.
B Indicates that a numeric field is to be output in binary format.
P Indicates that a numeric field is to be output in packed-decimal
format.
Z Indicates that the field is to be output in a zoned-decimal format.
Leave this entry blank for the output field under the following conditions:
• The output file is a PRINT or PRINTER file.
• An alphameric field is being output.
• An edit code has been specified.
• An edit word has been specified.
• The special word *PLACE is being used.
When packed-decimal format is specified, the output field length is

calculated by dividing the unpacked length of the field by 2 and adding 1
to the result. Thus, if a 9-digit, unpacked numeric field is to be output in
packed-decimal format, its output field length will be 5 (9/2+1).
When binary format is specified, a trailing numeric field 1 - 4 digits in
length is converted to a 2-byte binary field for output. A trailing numeric
field 4 - 9 digits in length is converted to a 4-byte binary field.
9–21
9.19 Columns 45 - 70 (Constant or Edit Word)

Columns 45 - 70 can be used to specify an output constant, edit word, or
WORKSTN screen format name. An edit word can be used to modify an
edit code specified in column 38 or to define how data will be formatted
when it is output. These items are described in more detail in the
following sections.
9.19.1 Output Constant

Columns 45 - 70 can be used to specify constant data for output. Output
constants are commonly used as report headings and informational text
within a report and identification codes within a data file.
A constant must be enclosed by single quotation marks (’). The characters
enclosed by the quotation marks will be written to the output file or device.
The leading quotation mark must be placed in column 45.
Constants can contain up to 24 characters. If a constant is longer than
24 characters, it can be continued on the next Output specification line as
another constant.
When using constants, leave columns 32 - 39 and column 44 blank.
To include a single quote in a constant, use two consecutive single quotes
to represent one single quote (for example, ’Subroutine’’s calculations’).
9.19.2 WORKSTN Screen Format Names

Columns 45 - 54 can be used to specify a WORKSTN screen format name.
A WORKSTN screen format name is used to specify the screen format
which is to display the data being passed by the program.
A WORKSTN screen format name requires a K in column 42. Only one
screen format name can be specified for each WORKSTN output record. A
screen format name must be specified for each WORKSTN output record.
A WORKSTN screen format name must be enclosed by single quotation
marks (’). The leading quotation mark must be placed in column 45.
A WORKSTN screen format name can be 1 - 8 characters in length. The
length of the screen format name is specified in column 43. For example,
if a WORKSTN screen format was named ASBECK, the entry in columns
40 - 43 (end position) would be K6.
The WORKSTN screen format name must match a screen format name
specified in columns 7 - 15 of a Screen specification in the screen format
file. If it does not, a runtime error will occur.
The Output specification containing the WORKSTN screen format name
cannot be qualified by conditioning indicators in columns 23 - 31.
9–22
9.19.3 Edit Code Modifiers

Columns 45 - 47 can be used to specify edit code modifiers. Edit code
modifiers can replace suppressed zeros to the left of the decimal point
with asterisks (asterisk fill) or put a currency symbol before the leftmost
character (floating currency symbol). To specify these modifiers, enter the
appropriate value described as follows:
Table 9–19 Columns 45 - 47 (Constant or Edit Word)

Allowable
Entries Explanation
’*’ Replaces suppressed zeros to the left of the decimal point with
asterisks ( * ).
’Symbol’ Places the currency symbol before the first significant digit in a
numeric field. The currency symbol is defined in column 18 of the
Control specification. By default, it is the ( $ ) symbol.
Enclose edit code modifiers in single quotes.

The floating currency symbol will not be printed for a zero balance when
an edit code that suppresses a zero balance is used.
The floating currency symbol and asterisk fill cannot be used with X, Y,
and Z edit codes.
9–23
9.19.4 Edit Words

Columns 45 - 70 can be used to specify edit words. Edit words can be used
to edit a numeric field. Edit words consist of three parts: the body, the
sign, and expansion. The body is the portion of the edit word that provides
space for the digits from the field to be edited. The body begins at the
leftmost character position of the edit word and ends at the rightmost
character position that is to contain a digit from the field to be edited.
The sign is the portion of the edit word that is used to specify whether the
field is positive or negative. The sign begins at the first character position
to the right of the body and ends with CR or a negative sign ( - ). If one
of these symbols is specified and the field is positive, blank spaces will be
substituted in the edited field. If CR or a negative sign is used and the
field is negative, the specified symbol will be substituted at the end of the
edited field.
If an edit word contains no CR or a negative sign to the right of the
rightmost character that is to contain a digit, the edit word does not
contain a sign portion.
The expansion consists of additional characters that will be printed
following the last replaceable character in the edit word. The expansion
begins immediately after the sign (or body, if no sign is used) and continues
to the end of the edit word.
The following table describes the characters which can be used in the body
of an edit word. In each example, leading zeros are suppressed. A small
letter b is used to indicate blank characters in the field.
9–24
Table 9–20 Columns 45 - 70 (Edit Words)

Allowable
Entries Explanation
Blank Indicates that the position in the edited field is to contain the digit
from the same position in the numeric field.
Edit word using blank characters
Source Data Edit Word Result of Edit
00496.23 ’bbbbb.bb’ bb496.23
0 Indicates that the field is to be zero suppressed. Place the zero

in the rightmost position where zero suppression is to stop. Each
leading zero that appears to the left of and including the stop position
of the numeric field is replaced with a blank space in the edited field.
The first zero encountered when scanning the edit word is the zero
suppression character. Any zero appearing after the first zero is
treated like any other character. Zero suppression begins at the
leftmost position in the data and continues up through the stop
position unless a non-zero digit is encountered to the left of the stop
position. If a non-zero digit is encountered to the left of the stop
position, zero suppression stops at the position where the non-zero
digit is encountered; that digit and all following digits to the right of
the non-zero digit are printed.
Edit word using zero suppression
00496.23 ’bbbb0.bb’ bb496.23
00496.23 ’0bbbb.bb’ b0496.23
00496.23 ’0bbbbb.bb’ 00496.23
* Indicates that the field is to be edited using asterisk fill. Place the
asterisk in the rightmost position where asterisk fill is to stop.
Each leading zero that appears in the data to the left of and
including the stop position is replaced with an asterisk. The first
asterisk encountered when scanning the edit word is the asterisk fill
character. Any asterisk appearing after the first asterisk is treated
like any other character.
Edit word using asterisk fill
00496.23 ’bbbb*.bb’ **496.23
00496.23 ’*bbbb.bb’ *0496.23
& Indicates that the position in the edited field is to be a blank space.
Edit word using the ampersand character
00496.23 ’bbbbb.bb&-&Sales’ bb496.23b-bSales
9–25
Table 9–20 (Cont.) Columns 45 - 70 (Edit Words)

Allowable
Entries Explanation
Currency Prints the currency symbol. If the currency symbol appears in the
Symbol body of the edit word immediately to the left of the zero suppression
character or decimal point, it is printed immediately to the left of the
first significant digit in the edited field. This type of currency symbol
is called a floating currency symbol. A floating currency symbol
cannot be used with asterisk fill.
The currency symbol in the leftmost position of the edit word
indicates that the symbol is to be printed in that exact position in the
edited field. This type of currency symbol is called a fixed currency
symbol.
The currency symbol is defined in column 18 of the control
specification.
Edit word using the currency symbol
00496.23 ’bbbbb$.bb’ b$496.23
00496.23 ’$bbbbb.bb’ $bb496.23
Decimal point Indicates the exact position in the edited field where a decimal point
or comma or comma is to be printed. If a decimal point or comma appears
to the left of the most significant digit in the output field, it will be
replaced with a blank space or, if asterisk fill is specified, with an
asterisk.
Edit word using commas and a decimal point
00496.23 ’bb,bbb.bb’ bbb496.23
47496.23 ’bb,bbb.bb’ 47,496.23
Any other Prints the characters in the edited fields, if the position is to the right
character of the most significant digit in the edited field. Any character to the
left of the most significant digit in the edited field is replaced with a
blank space or an asterisk if asterisk fill is specified.
Edit word using the slash (/) character
030992 ’bb/bb/bb’ b3/09/92
030992 ’0bb/bb/bb’ 03/09/92
9–26
The following table describes the characters which can be used in the sign
portion of an edit word.
Table 9–21 Using Edit Words to Display Negative Numbers

Allowable
Entries Explanation
CR or - Indicates that the specified symbol (CR or a negative sign ( - )) is to
be printed in the edited field if the data is negative. If the edited field
is positive, the specified symbol is replaced by blanks.
Edit words for a negative field
00496.23 ’bb,bbb.bb-’ bbb496.23b
00496.23- ’bb,bbb.bb-’ bbb496.23-
47496.23 ’bb,bbb.bbCR’ 47,496.23
47496.23- ’bb,bbb.bbCR’ 47,496.23CR
Any Prints the specified character(s) in the edited field if the data is
character negative; otherwise, the character is replaced by a blank. If
an ampersand ( & ) is specified, it will be replaced by a blank
space. These characters must appear between the last replaceable
character in the edit word and the sign character(s). If they appear
to the right of the sign character(s), they are treated as extensions to
the field and will always be printed.
Edit words for a negative field using optional display characters
496.23 ’bbb.bb&30&day&CR’ 496.23bbbbbbb
496.23- ’bbb.bb&30&day&CR’ 496.23b30bdaybCR
496.23 ’bbb.bbCR&overdue’ 496.23bbboverdue
496.23- ’bbb.bbCR&overdue’ 496.23CRboverdue
When specifying an edit word, leave column 38 (edit code) blank.

Columns 32 - 37 (field name) must contain a numeric field entry.
Edit words can be used only with trailing numeric data. Column 44 (data
format) must be blank.
Edit words can be up to 24 characters long and must be enclosed in single
quotes.
The number of replaceable characters in an edit word must be greater
than or equal to the number of digits in the numeric field.
If all leading zeros are to be printed, increase the edit word by one position
to the left of the leftmost digit and place a zero in that position.
When the floating currency symbol is used, the sum of the number of
blanks and the zero suppression in the edit word must be equal to or
greater than the number of digits in the edited field. A floating currency
symbol is not counted as a digit position.
9–27
Any zeros or asterisks following the leftmost zero suppression or asterisk

fill code are treated as constants and are not replaced with digits.
9.20 Columns 71 - 74 (No-op)

Columns 71 - 74 are not used. They should be left blank.

entry in these columns.
9–28
10 Migration RPG Language Elements
This chapter describes the primitives or elements of a Migration RPG

program. These elements include the character set, the various data types,
and the names that are defined and used to identify program constructs
and certain parts of those constructs.
10.1 Migration RPG Character Set

Migration RPG uses the full ASCII character set, including:
• Uppercase letters A through Z, except for character literals and
comment fields
• Digits 0 through 9
• Special characters (such as $ and _ (underscore))
Appendix A, Character Sets, contains the complete ASCII character set

and character values.
10.2 RPG Data Types

RPG input and output operations use the following data types which
determine how many bits of storage compose a unit of data in a program,
and how that unit is to be interpreted and manipulated at program
execution time.
Migration RPG supports six different data types for input and output
operations:
• Character
• Word binary numeric
• Longword binary numeric
• Packed-decimal
• Trailing numeric
• Zoned-decimal
The following sections describe each data type.
10–1
Migration RPG Language Elements
10.2.1 Character Data Type

Character data is a string of bytes containing ASCII codes as binary
data. Character field length can be from 1 to 9999 bytes. The format of a
character string is shown in Figure 10–1.
Note: In all subsequent diagrams, A represents the address of the first
byte of the string and L represents the length of the string in
bytes.
Figure 10–1 Format of a Character String
7 0
.
.
.
A+L−1
7 0
The address of a string specifies the first character of a string. The string
XYZ is shown in Figure 10–2. The address of the string would point at the
character X.
Figure 10–2 Address of a String
7 0
X A
Y A+1
Z A+2
10–2
The following code example depicts how character fields are defined within
an RPG program:
Example 10–1 Defining character fields
1 2 3 4 5
1234567890123456789012345678901234567890123456789012345678
*
00050ISALES AA 01 1 CJ
00060I 11 35 DESCR
00070I 36 40 CODE
.
.
.
00120C MOVE ’SNOJOB’ NODE 6
Lines 60 and 70 describe two input character fields. The first, DESCR,
is 25 characters long. The second, CODE, is 5 characters long. Line
120 depicts the creation and initialization of a character field within the
Calculation specifications. Here the character literal SNOJOB is being
moved into the 6-character field NODE.
10–3
10.2.2 Binary Data Type

Binary data is stored as binary values in a word or longword. A word is
two contiguous bytes, starting on an arbitrary byte boundary. The bits are
numbered from the right (0 through 15). When interpreted as a signed
quantity, a word is a twos complement number with bits increasing in
significance from bit 0 through bit 14, and with bit 15 designating the
sign. A two-byte word supports up to four decimal digits. The largest
number that can be represented by a word in RPG is 9,999. A word data
type is shown in Figure 10–3.
Figure 10–3 Word Data Type
15 0
A longword is four bytes, starting on an arbitrary byte boundary. The bits

are numbered from the right (0 through 31). When interpreted as a signed
quantity, a word is a twos complement number with bits increasing in
significance from bit 0 through bit 30, with bit 31 designating the sign. A
four-byte longword supports up to 9 decimal digits. The largest number
that can be represented by a longword in RPG is 999,999,999. A longword
datatype is represented in Figure 10–4.
Figure 10–4 Longword Data Type
31 0
10–4
The following code example depicts how binary fields are defined within an
RPG program:
Example 10–2 Defining binary fields
1 2 3 4 5
1234567890123456789012345678901234567890123456789012345678
*
00050IINVENTRYAA 01
00060I 01 060PARTNO
00070I B 07 080QTY
00080I B 09 122COST
Lines 70 and 80 describe two binary input fields. The B in column 43 of

each field definition indicates that these are binary fields. The first, QTY,
is a 2-byte field which is capable of storing a 4-digit number. The second,
COST, is a 4-byte binary field which is capable of storing a 9-digit number.
The field PARTNO on line 60 is defined as a numeric field.
Binary fields are normally used to conserve disk space.
10–5
10.2.3 Packed-decimal Data Type

Packed-decimal data is stored as a string of bytes. Each byte is divided
into two, 4-bit half-bytes (nibbles), with one decimal digit stored in each
nibble. The first, or most significant, digit is stored in the high-order
nibble of the first byte; the second digit is stored in the low-order nibble
of the first byte; the third digit is stored in the high-order nibble of the
second byte; and so on. The sign of the number is stored in the low-order
nibble of the last byte in the field.
The number 123+ is depicted in hexadecimal format in Figure 10–5.
The low-order nibble of the last byte in the field depicts the field’s sign.
A positive sign is indicated by a hex 0C, as shown in the example. A
negative sign would be depicted by a hex 0D.
Figure 10–5 Packed-decimal Data Type
7 4 3 0
31 32 A
33 0C A+1
The following formula can be used to determine the length in digits of a

packed-decimal field:
number of digits = (2 * n) - 1
where n = number of bytes used
The following formula can be used to determine the number of bytes
needed to store a numeric field in a packed-decimal format:
number of bytes = n/2 + 1
where n = number of digits in the field
Example 10–3 Defining packed-decimal fields
1 2 3 4 5
1234567890123456789012345678901234567890123456789012345678
*
00050ILEDGER BB 10
00060I 01 10 CUSTID
00070I P 11 152INCOME
00080I P 16 222EXPENS
Lines 70 and 80 describe two packed-decimal input fields. The P in column

43 of each field definition indicates that these are packed-decimal fields.
The first, INCOME, is a 9-digit field ((2 * 5) - 1). The second, EXPENS, is
a 13-digit field ((2 * 7) - 1).
Packed-decimal fields are normally used to conserve disk space. The

largest numeric field which can be defined within an RPG program is 15
digits. Thus, the largest packed-decimal field which can be defined within
a RPG program would contain 8 bytes (15/2 + 1).
10–6
10.2.4 Numeric Data Type

Numeric data (non-packed, non-binary) is a contiguous sequence
of bytes in memory with one decimal digit in a byte. Digits of
decreasing significance are assigned to increasing addresses. The sign
is superimposed on the last digit. Numeric data can be represented in
trailing numeric or zoned-decimal format.
All bytes of numeric data, except the least significant digit, must contain
ASCII decimal digits (0 through 9). Table 10–1 lists the representation for
all digits.
Table 10–1 Zoned-decimal representation of digits

Numeric Format ASCII Characters
Trailing Zoned Valid

Digit Decimal Hexadecimal Numeric Decimal Variations
0 48 30 0 0 {[?
1 49 31 1 1 A
2 50 32 2 2 B
3 51 33 3 3 C
4 52 34 4 4 D
5 53 35 5 5 E
6 54 36 6 6 F
7 55 37 7 7 G
8 56 38 8 8 H
9 57 39 9 9 I
-0 125 7D } p ]:!
-1 74 4A J q
-2 75 4B K r
-3 76 4C L s
-4 77 4D M t
-5 78 4E N u
-6 79 4F O v
-7 80 50 P w
-8 81 51 Q x
-9 82 52 R y
The sign of a numeric field is stored with the least significant digit in an
overpunch format, meaning that the sign is combined with the last digit in
the field.
There are several variations of overpunch format. Alternate forms of
overpunch sign representation are accepted by RPG on input and the
standard trailing numeric sign representation is generated by default on
output. Output can also be defaulted to zoned-decimal representation
using the zone-decimal options in column 60 of the Control (Header)
Specifiation or column 44 of the Output Specifications.
10–7
Figure 10–6 shows 123+ in trailing numeric and zoned-decimal format.

There is no difference between the formats when using positive numeric
data.
Figure 10–6 Zoned-Decimal Data Type (123+)
7 0
1 A
2 A+1
3 A+2
Figure 10–7 shows 123- in trailing numeric format.

Figure 10–7 Trailing Numeric Data Type (123-)
7 0
1 A
2 A+1
L A+2
Figure 10–8 shows 123- in zoned-decimal format.

Figure 10–8 Zoned-Decimal Data Type (123-)
7 0
1 A
2 A+1
s A+2
10–8
10.3 Naming Conventions - User-Defined Names

A user-defined name is a named quantity that identifies items in a
Migration RPG program. These items include:
• Files—a file name is assigned to a file.
• Fields—a field name is assigned to a field in a program. A field name
can be used in more than one field definition if each definition using
that name has the same data type, the same length, and the same
number of decimal positions.
• Arrays—an array name is assigned to an array. The first three
characters cannot be TAB.
• Tables—a table name is assigned to a table. The first three characters
must be TAB.
• Labels—a label identifies the destination of a GOTO or CABxx
operation.
• Subroutines—a subroutine name is assigned to a subroutine. A
subroutine name is referenced by the BEGSR, EXSR, and CASxx
operations.
• EXCPT—an EXCPT name can be used in factor 2 of the EXCPT
operation code and in an exception record Output specification.
Naming conventions within a Migration RPG program follow standard

OpenVMS naming conventions. The following rules must be adhered to
when defining names within an RPG program:
Naming Convention
• The first character of a name must be one of the following:
— Uppercase letters A through Z
— An underscore ( _ )
— A dollar sign ( $ )
• The remaining characters of a name can be the uppercase letters A
through Z, the digits 0 through 9, an underscore ( _ ), or a dollar sign
( $ ).
• Names must be left-justified.
• Names cannot contain embedded blanks.
• RPG special words cannot be used as names.
• The maximum length of a name is six characters, except for a file
name, which can be up to eight characters long.
10–9
11 Operation Codes
The RPG programming language allows the programmer to perform many

types of operations on their data. Many of these operations are defined
by (operation codes) in the Calculation specifications. These codes are
placed in columns 28 - 32 of the Calculation specification and are usually
abbreviated versions of the command that is to be performed.
The following sections offer a general description of the operation codes
grouped by function, followed by a detailed description of each operation
code in alphabetical order.
11.1 Arithmetic Operation Codes

Arithmetic operation codes include the ADD, Z-ADD, SUB, Z-SUB, DIV,
MVR, MULT, SQRT, and XFOOT instructions. These operations perform
a variety of functions, ranging from adding two operands to taking the
square root of an operand. When using arithmetic operation codes, the
following characteristics should be kept in mind:
• Arithmetic operation codes can only be used with numeric fields and
numeric literals.
• RPG aligns the operands according to their decimal points before
performing any arithmetic operation. Results of an arithmetic
operation are aligned on the decimal point in the result field, which
can cause truncation on both ends of a result.
• The contents of factor 1 and factor 2 do not change during an
arithmetic operation unless the same field is used as the result field.
• Any existing data in the result field is replaced with the result of the
current operation.
• If the length of the result field is not large enough to hold the result of
an arithmetic operation, the result of the operation is truncated before
being placed in the result field.
• Half adjust (column 53 of the Calculation specification) can be specified
for any arithmetic operation except a MVR operation and the DIV
operation immediately preceding it.
• The same field can be specified in factor 1, factor 2, and/or the result
field.
• If factor 1 is left blank in an arithmetic operation, the contents of
factor 2 are added, multiplied, subtracted, or divided into the result
field and the result is placed in the result field.
• An entire array can be specified as an operand of the ADD, SUB,
Z-ADD, Z-SUB, MULT, DIV, and SQRT operation codes. If this is
done, the operation will take place on each element in the array. See
11–1
Operation Codes
Chapter 15, Using Tables and Arrays, for information on using arrays
in arithmetic operations.
• No field in an arithmetic operation can be longer than 15 digits.
• RPG performs all arithmetic operations algebraically.
• The results of all arithmetic operations are signed. The sign of the
result of an arithmetic operation depends on the operation:
Addition:
— If factor 1 and factor 2 have like signs, the result field has the
same sign.
— If factor 1 and factor 2 have unlike signs, the result field uses the
sign of the factor with the largest absolute value.
Subtraction:
— Change the sign of factor 2 (positive to negative or negative to
positive) and use the same rules used for addition.
Multiplication:
— If factor 1 and factor 2 have like signs, the sign of the result field
is positive.
— If factor 1 and factor 2 have unlike signs, the sign of the result
field is negative.
Division:
— If factor 1 and factor 2 have like signs, the sign of the result field
is positive.
— If factor 1 and factor 2 have unlike signs, the sign of the result
field is negative.
— The sign of the remainder is the same as the sign of factor 1.
11.2 Bit Operation Codes

BIT operation codes consist of the BITON, BITOF, and TESTB
instructions. These operation codes can be used to set, clear, and test
individual bits. When using bit operations, keep the following points in
mind:
• The field specified in factor 2 of a bit operation must be a single-
character, alphameric field. Numeric fields are considered alphameric
if they have no decimal positions defined.
• Array or table elements can be used in bit operations if the array or
table is defined as having single-character, alphameric entries.
• If a field is defined in a bit operation, it is initialized with the value
hex 20 (blank).
• The result field used in a bit operation should also be a single
character alphameric field. Bit operations are only designed to work
on single character alphameric fields.
11–2
Operation Codes
11.3 Branching Operation Codes

Branch operation codes consist of the CABxx, GOTO, and TAG
instructions. Branching operation codes can be used to skip or repeat
operations.
11.4 Compare and Test Operation Codes

Compare and test operations consist of the CABxx, CASxx, COMP, ANDxx,
ORxx, IFxx, DO, DOUxx, DOWxx, TESTN, and TESTZ instructions. These
operation codes are used to compare or test fields for certain conditions.
Based on the result of the comparison or test, resulting indicators can be
set and actions can be taken.
Quite a few of the compare operation codes are structured operation codes,
which are also covered in Section 11.11. The purpose of this section is to
describe how compare and test operations take place under RPG.
When using compare and test operations, keep the following points in
mind:
• When comparing numeric fields, the fields are aligned at their implied
decimal point. Fields are filled with zeros to the left and right of the
decimal point until both fields are equal in length. For example, if
a numeric field containing 1234.56 is compared to a numeric field
containing 1.2, RPG fills the second field (1.2) with zeros (0001.20)
until both fields are equal in length. Numeric fields cannot exceed 15
characters in length.
• If alphameric fields of unequal lengths are compared, the fields are
aligned at the leftmost character. Shorter fields are filled with blanks
until the two fields are equal in length.
• RPG compares numeric fields algebraically. Positive numeric fields are
always greater than negative numeric fields.
• Blanks within a numeric field are treated as zeros.
• Numeric fields are converted to packed decimal format (if necessary)
before they are compared.
• If an alternate collating sequence has been specified, RPG translates
alphameric fields to the alternate collating sequence before comparing
them.
• An alphameric field cannot be compared to a numeric field.
• Entire arrays and tables cannot be specified in a compare operation.
However, array and table elements can be compared.
11–3
Operation Codes
11.5 External Call Operation Codes

External call operation codes include the CALL, PARM, PLIST, FREE,
RETRN, EXIT, and RLABL instructions. These operation codes can be
used to call external subroutines, system services, and subprograms.
When using these operation codes, keep the following points in mind:
• The CALL, PARM, PLIST, FREE, and RETRN operation codes provide
a specific, internally-defined interface for calling Migration RPG
subprograms.
• The EXIT and RLABL operation codes are provided to maintain
compatibility with other versions of the RPG II programming
language. They are most commonly used to provide an interface to
the MSI-supplied subroutines SUBR01, SUBR21, and SUBR23.
11.6 Internal Subroutine Operation Codes

Subroutine operation codes consist of the BEGSR, ENDSR, CASxx and
EXSR instructions. These operation codes are used to identify and
execute internal RPG subroutines. A subroutine is a group of Calculation
specifications that can be executed more than once in a single program
cycle. When using subroutines, keep the following points in mind:
• Subroutine specifications are indicated by blanks or an SR in columns
7 and 8 of a Calculation specification.
• All subroutines must appear at the end of the calculations section
in an RPG program. The subroutine section follows the total time
calculations section.
• Subroutines cannot be defined as total time calculations, meaning
that indicators L1 - L9 cannot appear in columns 7 - 8 of subroutine
specifications. However, subroutines can be called from total time
calculations.
• Subroutines can be defined in any order.
• All subroutines must begin with a BEGSR operation and end with an
ENDSR operation.
• Any RPG operation other than a BEGSR or ENDSR operation can be
performed within a subroutine.
• Subroutines can call other subroutines or call themselves recursively.
Using recursive subroutine calls is not recommended, as they are hard
to track and can be very difficult to debug.
• Internal subroutines are always called using the EXSR operation.
CALL and EXIT operations are reserved for external routine calls.
• Branching from inside a subroutine back to a TAG in detail or total
calculations is permitted, but is not recommended. Branching from
outside a subroutine to a TAG inside a subroutine is never permitted.
11–4
Operation Codes
• Under normal conditions, a subroutine will always return to the first

executable statement following the EXSR operation which called it.
There are two possible exceptions to this rule:
— If a CABxx operation is executed within a subroutine which
references a TAG in detail or total time calculations, the
subroutine will branch to that point. This type of coding is not
recommended.
— If the subroutine being called is an INFSR subroutine, it will not
execute a normal return when its ENDSR statement is processed.
INFSR subroutines are exception handling subroutines and are
discussed in detail in the Migration RPG Screen Format Reference
Manual.
• Up to 9,999 internal subroutines can be defined in a program.
11.7 Move Operation Codes

Move operation codes include the MOVE, MOVEA, and MOVEL
instructions. MOVE operations transfer data from a field in factor 2
to the result field. Factor 1 is always blank in a move operation and
resulting indicators are not allowed. When using move operations, the
following characteristics should be kept in mind:
• The contents of factor 2 are not affected by a move operation.
• The decimal positions of numeric fields are ignored during a move
operation. If the data 387.6 is moved to a field defined as having two
decimal positions, the result of the move will be 38.76.
• Data transfer in a move operation begins with the rightmost character
of factor 2 to the rightmost character of the result field.
• If the result field is not large enough to accommodate factor 2, RPG
moves only enough characters (beginning with the rightmost character)
to fill the result field.
• If the field length of the result field is longer than factor 2, the leftmost
characters of the result field are not changed.
• When moving numeric data, the sign of the result field is the same as
the sign of factor 2.
• When moving an alphameric field to a numeric field, the digit portion
of each character is converted to its corresponding numeric character
and then moved to the result field. The zone portion of the rightmost
character is converted to its corresponding sign and then moved to the
rightmost character position of the numeric result field.
• The MOVEA operation allows data to be transferred from an array
to a field, a field to an array, or between arrays. When using the
MOVEA operation code, arrays are treated as one contiguous field. If
an array element is specified, it indicates the beginning position of the
transfer in the array. Several contiguous array elements can be moved
to a single field or a single field can be moved to several contiguous
array elements. Array element boundaries are ignored in a MOVEA
11–5
Operation Codes
operation. Therefore, movement of data can end in the middle of an

array element.
• A MOVEL operation transfers the contents of factor 2 to the result
field from left to right. It begins the transfer with the leftmost
character of factor 2, moving it to the leftmost character of the result
field. If the result field is larger than factor 2, the rightmost characters
in the result field will be unaffected by the move operation.
11.8 Move Zoned Operation Codes

Move zoned operation codes include the MHHZO, MHLZO, MLHZO, and
MLLZO instructions. These operations move only the zone portion of a
character. When using move zone instructions, keep the following points
in mind:
• When moving high zone, the field involved must always be alphameric.
• When moving low zone, the field involved can be either alphameric or
numeric.
11.9 Programmed Input and Output Operation Codes

Programmed input and output operations use the instructions CHAIN,
EXCPT, FORCE, KEYnn, READ, READE, READP, SETnn, and SETLL.
These operation codes can be used to alter the normal input and output
cycle, enabling the program to read and write records during calculations.
The $STAT$ field can be used to determine the return status of CHAIN,
READ, READE, and READP operations.
11.10 Set Indicator Operation Codes

SET operation codes consist of the SETON and SETOF instructions.
These operation codes turn the indicators specified in columns 54 - 59 on
or off. When using set operations, keep the following points in mind:
• The following indicators cannot be set using a set operation: 1P, L0,
and MR.
• Setting on a control break indicator (L1 - L9) using a set operation
does not set on lower control break indicators.
• If the last record indicator (LR) is set on at total time, processing stops
after RPG finishes total time output operations.
• If the last record indicator (LR) is set on at detail time, processing
stops after RPG finishes the next total time output operation.
• If halt indicators are set on and then are not set off before RPG
finishes detail time output operations, processing stops. The user is
given the option of clearing each set halt indicator and continuing
processing or terminating the program.
• Control level (L1 - L9) and record identifying indicators are always
turned off at the end of detail output operations.
11–6
Operation Codes
• Record identification and field indicators defined in the Input

specifications are turned on or off based on the contents of each new
input record. Previous settings of these indicators are ignored.
• Command key indicators (KA - KN, KP - KY) are turned off each time
a read operation is issued to a workstation file.
• If an 01 - 99 indicator is set in the Calculation specifications and
is not used in the Input specifications as a record identifying or
field indicator, it remains set until changed by another Calculation
specification.
11.11 Structured Operation Codes

Structured operation codes include the CASxx, DO, DOUxx, DOWxx,
IFxx, ANDxx, ORxx, ELSE, and END instructions. These operation
codes allow a series of instructions to be performed one or more times
during a single program cycle, conditional execution of instructions, and
conditional branching to subroutines. Structured operations have the
following characteristics:
• The CASxx (Case) instruction permits conditional branching to a
subroutine based on the results of the comparison of factor 1 and
factor 2.
• The DO operation executes a series of instructions one or more
times based on a start value, end value, and increment value. The
instruction set, bound by the DO and END statements, are performed
until the start value exceeds the end value. After each pass through
the Do Loop, the start value is incremented by the increment value. If
the end value exceeds the start value when the DO operation is first
encountered, none of the instructions within the DO construct will be
performed.
• The DOUxx (Do Until) operation executes a set of instructions one or
more times based on the relation between the contents of factor 1 and
factor 2. A DOUxx construct is always performed at least once.
• The DOWxx (Do While) operation executes a set of instructions one
or more times based on the relation between the contents of factor 1
and factor 2. If the relationship between factor 1 and factor 2 is not
satisfied, the DOWxx operation is not performed.
• The IFxx and ELSE operations allow code to be conditionally executed
based on the outcome of the comparison of factors 1 and 2.
• The ANDxx and ORxx operations can be used with the DOUxx,
DOWxx, and IFxx operations to build more complex test conditions.
• The END statement is used to bound all structured operations
instruction sets. In the case of the Do Loop, it is also used to define
the increment value.
11–7
Operation Codes
• The xx portion of the CASxx, IFxx, ANDxx, ORxx, DOUxx, and DOWxx
instructions identifies the type of comparison operation that is to take
place. The comparison operation can be:
— GT (Greater Than) - Comparison is true if factor 1 is greater than
factor 2.
— LT (Less Than) - Comparison is true if factor 1 is less than factor
2.
— GE (Greater Than or Equal) - Comparison is true if factor 1 is
greater than or equal to factor 2.
— LE (Less Than or Equal) - Comparison is true if factor 1 is less
than or equal to factor 2.
— EQ (Equal) - Comparison is true if factor 1 is equal to factor 2.
— NE (Not Equal) - Comparison is true if factor 1 is not equal to
factor 2.
— Blanks (Unconditional - CASxx operation only) - The CASxx
instruction allows for the unconditional execution of a CASxx
statement by leaving the comparison code blank. An unconditional
CASxx statement will always execute. Unconditional CASxx
statements are usually placed at the end of a case construct.
• A structured operation code, the statements following it, and its END
statement form a structured construct. Structured constructs have the
following characteristics:
— Structured constructs can be nested.
— When a structured construct completes execution or if a structured
construct is bypassed, execution of the program resumes at the
statement immediately following the structured construct’s END
statement.
— Structured constructs cannot be split between detail time
calculations, total time calculations, and subroutines. A structured
construct must begin and end within the same set of calculation
specifications.
— Branching into a structured construct may produce unpredictable
results.
— CASxx constructs can only contain CASxx statements.
11.12 OPERATION CODES

The remaining sections in this chapter describe each Migration RPG
operation code in detail in alphabetical order.
11–8
Operation Codes
11.12.1 - ADD Operation (Addition)
Indicators Factor 1 Opcode Factor 2 Result Fld Resulting Indicators
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional ADD Required Required Opt Opt Opt
Description
The ADD operation allows two numeric fields to be added together.
Rules
All fields specified in an ADD operation must be numeric.
Conditional indicators (columns 7 - 17) are optional.
Factor 1 is optional. If present, factor 2 is added to factor 1 and the sum
is placed in the result field.
Factor 2 is required. If factor 1 is not present, factor 2 is added to the
result field and the sum is placed in the result field.
The contents of factor 1 and factor 2 are not affected by an ADD operation.
Resulting indicators (columns 54 - 59) are optional. They can be
used to indicate whether the contents of the result field are positive
(columns 54 - 55), negative (columns 56 - 57), or zero (columns 58 - 59)
after the ADD operation completes.
Operation
RPG aligns the operands according to their decimal points before
performing any arithmetic operation. Results of an arithmetic operation
are aligned on the decimal point in the result field, which can cause
truncation on both ends of a result. More information on arithmetic
operations is available earlier in this chapter in Section 11.1.
11–9
Operation Codes
Example 11–1 ADD Operation Code Usage - 2 operands
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C FLD1 ADD 1 FLD2
In this example, the constant 1 is added to FLD1 and the result is placed
in FLD2.
Example 11–2 ADD Operation Code Usage - 1 operand
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C ADD 1 CNT
In this example, the constant 1 is added to the field CNT and the result is
placed in CNT.
Example 11–3 ADD Operation Code Usage - Indicator controlled
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C N10 CASH ADD INTRST SUM
In this example, the ADD operation is only carried out if indicator 10 is

not on. If processed, the operation will add the field INTRST to the field
CASH, placing the result in SUM.
11–10
Operation Codes
11.12.2 - ANDxx Operation (Complex Conditional Operation)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blk Required ANDxx Required Blank Blk Blk Blk
Description
The ANDxx operation allows a more complex conditional operation to be
specified in DOUxx (Do Until), DOWxx (Do While), and IFxx operations.
Fields specified in the ANDxx operation are compared and return a true
or false condition to the program. The true/false condition is used by the
program to determine if the structured construct of which the ANDxx
operation is a part should be executed or bypassed.
Rules
The ANDxx operation can be used in conjunction with the DOUxx,
DOWxx, IFxx, and ORxx operations.
Control level entries (columns 7 - 8) for the ANDxx operation must be
consistent with the control level entry for the associated DOUxx, DOWxx,
or IFxx operation.
Conditional indicators (columns 9 - 17) are not permitted.
Factor 1 and factor 2 are both required. They can contain a literal,
field, array element, table element, or data structure element. The data
types of both fields must match, meaning that both fields must be either
alphameric or numeric.
The comparison carried out in an ANDxx operation follows standard RPG
comparison rules. These rules are discussed earlier in this chapter in
Section 11.4.
Resulting indicators (columns 54 - 59) are not allowed.
11–11
Operation Codes
The xx portion of the ANDxx operation can be one of the following

instructions:
• GT (Greater Than) - Comparison is true if factor 1 is greater than
factor 2.
• LT (Less Than) - Comparison is true if factor 1 is less than factor 2.
• GE (Greater Than or Equal) - Comparison is true if factor 1 is greater
• LE (Less Than or Equal) - Comparison is true if factor 1 is less than or
equal to factor 2.
• EQ (Equal) - Comparison is true if factor 1 is equal to factor 2.
• NE (Not Equal) - Comparison is true if factor 1 is not equal to factor 2.
Further information concerning structured operation codes is available

earlier in this chapter in Section 11.11.
Example 11–4 ANDxx Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C TRICK DOUEQ4
C STER ANDLTJOKE
.
.
.
C END
In this example, the ANDxx operation is being used in conjunction with

the DOUxx operation. The DOUxx loop in this example will be performed
until the field TRICK is equal to 4 and the field STER is less than JOKE.
11–12
Operation Codes
11.12.3 - BEGSR Operation (Begin Subroutine)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blnk Required BEGSR Blank Blank Blank Blank Blank
Description
The BEGSR operation indicates the beginning of an internal subroutine.
Rules
The BEGSR operation must be the first specification in an internal
subroutine.
The entry of SR in columns 7 and 8 is optional. Conditional indicators are
not allowed.
Factor 1 contains the name of the subroutine. The name can be 1 to
6 characters long and must begin with an alphabetic character. Valid
characters in a subroutine name are A - Z, 0 - 9, $, and _ (underscore).
Each subroutine name within a program must be unique; it cannot
duplicate another subroutine name, a TAG label, a ENDSR label, a CALL
routine name, or a PLIST label.
See Section 11.6 earlier in this chapter for more information on coding and
executing internal subroutines.
Example 11–5 BEGSR Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
CSR SBGT BEGSR
.
.
.
CSR ENDSR
In this example, the BEGSR operation is used to define the internal RPG
subroutine SBGT. Note the use of the SR indicator in columns 7 - 8. Use
of this indicator is optional. Using it makes the subroutine section in an
RPG program easier to identify.
11–13
Operation Codes
11.12.4 - BITOF Operation (Bit Off)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank BITOF Required Required Blank Blank Blank
Description
The BITOF operation sets the bits specified in the mask in factor 2 off (to
0) in the result field.
Rules
Factor 1 must be blank.
Factor 2 can contain a literal bit mask or a single-character, alphameric
field which contains the bit mask used by the BITOF operation. A literal
bit mask identifies the bits as 0 through 7, with 0 as the leftmost bit. The
bit mask must be enclosed in single quotes. For example, to set bits 0, 4,
and 5 off, enter ’045’ in factor 2. A bit number cannot be specified more
than once in a mask.
If a field name is specified in factor 2, it must be a single-character,
alphameric field, table, or array element. The bits that are on in the field
name are set off in the result field. If a table or array element is specified,
each element must be a single-character, alphameric field. If factor 2 is
not a single character field or literal bit mask, a compilation error will
occur.
The result field should be a single-character, alphameric field, table,
or array element. Bit operations are only designed to work on single
character alphameric fields. The bits specified in factor 2 will be set off in
the result field. The remaining bits in the result field will be unaffected.
Example 11–6 BITOF Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C N66 BITOF’0125’ ESC 1
C N66 BITON’3467’ ESC
Example 11–6 Cont’d on next page
11–14
Operation Codes
Example 11–6 (Cont.) BITOF Operation Code Usage
This example demonstrates the use of the BITOF and BITON operations
to create the escape character (hex 1B). Note that these instructions will
only be executed if indicator 66 is off. The field ESC is being defined in the
Calculation specifications as a 1-character alphameric field (1 in column
51, blank in column 52).
11–15
Operation Codes
11.12.5 - BITON Operation (Bit On)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank BITON Required Required Blank Blank Blank
Description
The BITON operation sets the bits specified in the mask in factor 2 on (to
1) in the result field.
Rules
Factor 2 can contain a literal bit mask or a single-character, alphameric
field which contains the bit mask used by the BITON operation. A literal
bit mask identifies the bits as 0 through 7, with 0 as the leftmost bit. The
bit mask must be enclosed in single quotes. For example, to set bits 2, 5,
and 6 on, enter ’265’ in factor 2. A bit number cannot be specified more
than once in a mask.
alphameric field, table, or array element. The bits that are on in the field
name are set on in the result field. If an array element is specified, each
element in the array must be a single-character field. If factor 2 is not a
single character field or literal bit mask, a compilation error will occur.
character alphameric fields. The bits specified in factor 2 will be set on in
the result field. The remaining bits in the result field will be unaffected.
Example 11–7 BITON Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C BITON’3467’ ESC 1
C BITOF’0125’ ESC
This example demonstrates the use of the BITON and BITOF operations
to create the escape character (hex 1B).
11–16
Operation Codes
11.12.6 - CABxx Operation (Compare and Branch)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required CABxx Required Optional Opt Opt Opt
Description
The Compare and Branch operation allows a program to conditionally
branch to a TAG based on the results of the comparison of factor 1 and
factor 2.
Rules
figurative constant, field, array element, table element, or data structure
element. The data types of both fields must match, meaning that both
fields must be either alphameric or numeric.
The xx portion of the CABxx operation can be one of the following
instructions:
factor 2.
equal to factor 2.
• blank - If a TAG has been specified in the result field, a branch
operation is executed independent of the compare. If no entry is
present in the result field, the CAB operation functions like a compare.
The comparison carried out in a CABxx operation follows standard RPG

Section 11.4. If the comparison is true, a branch to the TAG label specified
in the result field is executed. If the comparison is false, the branch is
ignored and program execution continues with the next line.
An entry in the result field is optional. If an entry is present, it must be a
valid label associated to a TAG or ENDSR statement. If the result field is
empty, at least one resulting indicator must be specified and the operation
is treated like a COMP operation.
11–17
Operation Codes
Resulting indicators (columns 54 - 59) are optional.
Operation
The CABxx operation can be used to:
• Branch from any line to any line within the detail calculation section.
• Branch from detail calculations to total time calculations.
• Branch from any line to any line within total time calculations.
• Branch from a subroutine line to the detail calculations section.
• Branch from a subroutine line to the total time calculations section.
CABxx operations cannot branch from outside a subroutine into a

subroutine.
Branching from one part of the RPG logic cycle to another is not
recommended. It can be very confusing and lead to infinite loops and
other problems.
Example 11–8 CABxx Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C FLDA CABLEFLDB TGLE 040506
.
.
.
C TGLE TAG
The CABxx operation in this example will cause the program to branch
to the tag TGLE if FLDA is less than or equal to FLDB. Note the use of
optional resulting indicators. These indicators will be set based on the
results of the comparison carried out by the CABxx operation. In this
example, if FLDA contains 7 and FLDB contains 12, indicator 05 will be
turned on and the program will branch to the TGLE tag.
11–18
Operation Codes
11.12.7 - CALL Operation (Calling RPG Subprograms)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank CALL Required Optional Blank Opt Opt
Description
The CALL operation transfers control to the RPG subprogram or external
routine specified in factor 2. This operation code is used primarily to call
RPG subprograms.
Rules
The CALL operation transfers control to a subprogram much as the
BEGSR operation code transfers control to an internal subroutine. Factor
2 must contain an alphameric literal or a field defined by the EXTRN
operation code that names the subprogram. This can be a valid OpenVMS
program name. Factor 2 cannot be an array element or data field name.
The program specified in factor 2 can be written in any OpenVMS
programming language, including Migration RPG. When specifying a
program name which exceeds 8 characters, use the EXTRN operation code
to define a field which represents the program name.
The result field can contain the name of the parameter list associated
with a PLIST operation code. This enables the calling program to share
parameters with the subprogram. Individual parameters can also be
specified immediately following the CALL operation code using the PARM
operation code. Both the PLIST option and PARM statements can be used
together with the CALL operation code.
Factor 1, half adjust, and the resulting indicator in columns 54 and 55
must be blank. Any valid resulting indicator can be specified in columns
56 and 57 to be set on if the subprogram exits with an error status set.
Any valid resulting indicator can be specified in columns 58 and 59 to be
set on if the subprogram is a Migration RPG program and exits with the
LR indicator set.
Operation
While the CALL operation can call any type of subprogram or system
service, it is specifically designed to call Migration RPG subprograms and
is generally used for this purpose. It has been designed to make Migration
RPG compatible with advanced versions of RPG II.
11–19
Operation Codes
Example 11–9 CALL Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C CALL ’MAMMAL’ 23
C PARM FOX
C PARM BAT
C PARM WEASEL
C PARM WOLF
This example displays the use of the CALL and PARM operation codes.
The subprogram MAMMAL is called and passed the parameters FOX,
BAT, WEASEL and WOLF. MAMMAL can then manipulate these fields
and return their updated values to the calling program. After the
subprogram MAMMAL is processed, control returns to the next executable
statement following the last PARM statement. Indicator 23 will be set on
if MAMMAL should exit with an error status set.
11–20
Operation Codes
11.12.8 - CASxx Operation (Case)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional CASxx Optional Required Opt Opt Opt
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blnk Blank END Blank Blank Blank Blank Blank
Description
The CASxx operation allows an internal subroutine to be conditionally
selected for execution.
Rules
Factor 1 and factor 2 are both required in all CASxx operations except
when the xx portion of the CASxx operation code is blank. They can be
either field or literal data. Factor 1 and factor 2 must both contain either
alphameric or numeric data.
The result field is required. It must contain the name of a valid
subroutine. If the condition evaluated by the CASxx operation is true,
program control is passed to the subroutine. If the condition is false,
program execution continues with the next line.
The comparison carried out in a CASxx operation follows standard RPG
Section 11.4.
The xx portion of the CASxx operation can be one of the following
instructions:
factor 2.
equal to factor 2.
11–21
Operation Codes

• blank - If the conditional portion of a CASxx statement is blank, the
CAS operation is considered unconditional. This means it acts just like
a EXSR operation. Unconditional CASxx statements are often placed
at the end of a CASxx structure to provide a default subroutine call.

Resulting indicators (columns 54 - 59) are optional. If resulting indicators
are specified in an unconditional CASxx operation, factor 1 and factor 2
must be present.
Conditional indicators are not allowed on the END statement terminating
a CASxx construct.
Operation
When a subroutine is called by a CASxx operation, control is returned to
the line following the END statement associated to the CASxx construct
when the subroutine completes execution.
Example 11–10 CASxx Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C HOME CASGTVISTOR WIN
C HOME CASLTVISTOR LOSS
C HOME CASEQVISTOR TIE
C END
In this example, the CASxx operation is used to select a subroutine based

on the comparison of the HOME and VISTOR fields. If HOME is greater
than VISTOR, subroutine WIN will be executed. If HOME is less than
VISTOR, the subroutine LOSS is executed. If HOME is equal to VISTOR,
the subroutine TIE is executed.
11–22
Operation Codes
Example 11–11 CASxx Operation Code Usage - Unconditional CASxx
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C SCORE CASLTAVERAG BAD
C SCORE CAS AVERAG UPDATE 04 05
C END
In this example, the CASxx operation is used to conditionally execute

the subroutine BAD if SCORE is less than AVERAG. Otherwise,
the unconditional CASxx operation (xx is blank) will ensure that the
subroutine UPDATE is executed. Note the use of the optional resulting
indicators on the unconditional CASxx operation. Indicator 04 will be
turned on if SCORE is greater than AVERAG. Indicator 05 will be turned
on if SCORE is equal to AVERAG.
11–23
Operation Codes
11.12.9 - CHAIN Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required CHAIN Required Blank Opt Opt Blank
Description
The CHAIN operation reads a record by key from a file during calculations
and makes the contents of the record available to the program. A CHAIN
operation can read records from a sequential, relative, or indexed file.
Rules
Factor 1 is required. It contains the relative record number or key field to
be used to access the chained file. Data structure elements can be used to
specify non-contiguous keys.
Factor 2 is also required. It must contain the name of the file from which
the record is to be read. This file must be a chained or full-procedural file
(C or F in column 16 of the File Description specification) and must be
defined in the program’s File Description specifications.
The result field must be blank.
A resulting indicator in columns 58 - 59 is not allowed. A resulting
indicator in columns 54 - 55 is optional for chained files and required for
full-procedural files. This indicator serves as a record-not-found indicator
and will be turned on if the record requested is not found.
A resulting indicator in columns 56 - 57 is optional. If specified, it serves
as an error indicator, turning on if the record requested by the CHAIN
operation cannot be accessed. If this indicator is turned on, the record-not-
found indicator will also be turned on. The $STAT$ field will contain the
completion status of a CHAIN operation.
If a record-not-found or error indicator is not specified on a CHAIN
operation and the chain fails, the program will abort with an error.
Operation
If a chained file is conditioned by an external indicator (U1 - U8) in the
File Description specifications, all CHAIN operations associated to that file
should also be conditioned by the same indicator.
A record which is not found during a CHAIN operation cannot be updated.
However, it can be added.
11–24
Operation Codes
If a record is locked by another user when a second program tries to access

it and an error indicator has not been declared in columns 56 - 57, an
error message will be displayed at the terminal. The program will wait
approximately 5 minutes for the record to be freed. If it is not freed within
this time frame, the program will abort with an error message.
The $STAT$ field will contain the completion status of any CHAIN, READ,
READE, or READP operation.
When chaining to indexed files using packed-decimal keys, the key
specified in factor 1 of the CHAIN operation must have the same packed-
decimal length as the key in the file.
If a CHAIN operation is successful, the record identifying indicators
associated with the record read remain on for the rest of the cycle.
If multiple CHAIN operations are performed against the same file during
a single program cycle, only the last record read can be updated at output
time. The EXCPT operation can be used to update records during the
calculation portions of the program cycle.
Example 11–12 CHAIN Operation Code Usage - Relative file
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H
00010FINP IP F 80 80 DISK
00020FOUT OC F 52 52R DISK
00030FRPT O F 80 80 PRINTER
00040IINP AA 02
00050I 1 50TAXNUM
00060I 1 52 RECORD
00070C*
00080C 02 TAXNUM CHAINOUT 99
00090C*
00100OOUT D 02 99
00110O RECORD 52
00120ORPT D 02
00130O RECORD 52
00140O 99 70 ’ADDED’
00150O N99 70 ’DUPLICATE’
This program scans a file for duplicate records. The CHAIN operation is
used to chain into the relative file OUT to determine if the record read
from the file INP is present in the OUT file. The field TAXNUM contains
the relative record number which is used to chain into the OUT file.
Note the use of indicator 99 as the record-not-found indicator in columns
54 - 55. If 99 is on after the CHAIN, the INP record is added to the OUT
file. If 99 is off after the CHAIN, the record already exists in the OUT file
and is reported as a duplicate in the RPT file.
11–25
Operation Codes
Example 11–13 CHAIN Operation Code Usage - Indexed file
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
F*
FIDXMST UC F 57 57R 5AI 1 DISK
.
.
.
C KEY CHAINIDXMST 9899
C 99 $STAT$ CASEQ’000181B0’LCKERR
C 99 CAS GENERR
C END
In this example, the CHAIN operation is being used to access an indexed

file. Note the use of both the record-not-found indicator (columns 54 - 55)
and the error indicator (columns 56 - 57). If the error indicator (99) is set,
the $STAT$ field is checked to determine if the return status from the
CHAIN indicates a record lock error. If the problem is a record lock error,
the subroutine LCKERR is executed. If the problem is not a record lock
error, the subroutine GENERR is executed.
11–26
Operation Codes
11.12.10- COMP Operation (Compare)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required COMP Required Blank One required
Description
The COMP operation compares factor 1 and factor 2, setting resulting
indicators based upon the results of the comparison.
Rules
figurative constant, field, array element, table element, or data structure
element. The data types of both fields must match, meaning that both
fields must be either alphameric or numeric.
At least one resulting indicator (columns 54 - 59) must be specified. These
indicators indicate the results of the comparison as follows:
• High - Columns 54 - 55
Factor 1 is greater than factor 2.
• Low - Columns 56 - 57
Factor 1 is less than factor 2.
• Equal - Columns 58 - 59
Factor 1 is equal to factor 2.
All resulting indicators specified in a COMP operation are set off before
the operation begins.
The comparison carried out in a COMP operation follows standard RPG
Section 11.4.
If an alternate collating sequence has been specified, alphameric fields are
translated into the alternate collating sequence before being compared.
Alphameric and numeric fields cannot be compared against each other.
11–27
Operation Codes
Example 11–14 COMP Operation Code Usage - Equal
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C CODE COMP 24 11
In this example, the COMP operation is used to compare the field CODE
to the numeric literal 24. If CODE is equal to 24, indicator 11 will be
turned on.
Example 11–15 COMP Operation Code Usage - Greater than or equal
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C CODE COMP 3 12 11
to the numeric literal 3. If CODE is greater than 3, indicator 12 will be
turned on. If CODE is equal to 3, indicator 11 will be turned on.
Example 11–16 COMP Operation Code Usage - Less than or equal
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C CODE COMP KEY 1313
In this example, the COMP operation is used to compare the field CODE to
the field KEY. If CODE is less than or equal to the field KEY, the indicator
13 will be turned on.
Example 11–17 COMP Operation Code Usage - Greater than, Less than,
Equal
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C 01 CODE COMP CUP 203040
to the field CUP. If CODE is greater than CUP, indicator 20 is turned on.
If CODE is less than CUP, indicator 30 is turned on. If CODE is equal to
CUP, indicator 40 is turned on. Note that indicator 01 must be on before
this command will be executed.
11–28
Operation Codes
11.12.11- DEBUG Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional DEBUG Required Optional Blank Blank Blank
Description
The DEBUG operation code is provided to assist the programmer in
debugging RPG programs. It is especially useful as Migration RPG does
not interface with the OpenVMS Symbolic Debugger.
Rules
Control Specification Entry
To turn the debugging option on in an RPG program, a 1 must be coded in
column 15 of the Control (H) specification. If column 15 is blank, all debug
files and debug operation codes are ignored by the compiler.
File Description Specification Entries
An output file to which the DEBUG operation will write must be defined
in the File Description specifications. A program can contain multiple
DEBUG files, although one is usually sufficient.
A debug file must be an output file. The device type can be PRINT,
PRINTER or DISK. A debug file cannot be a WORKSTN file.
Calculation Specification Entries
Factor 1 is optional. It can contain a literal, field name, array, array
element, table element, or data structure element. The contents of factor 1
are output to the debug file. Factor 1 is most commonly used to output a
literal which can serve as a tag to indicate the section of code the program
is processing or which serves as a label to identify the contents of the
result field.
Factor 2 is required. It must contain the name of the debug file as it
appears in columns 7 - 14 of the File Description specification. The file
must be an output file.
The result field is optional. It can contain a field name, array, array
element, table element, or data structure element. The contents of the
result field are output to the debug file.
11–29
Operation Codes
Output Specification Entries

Output specifications for the DEBUG file are optional. If used, they will
follow normal RPG rules for output. In most cases, output specifications
will not be necessary when using the DEBUG operation.
Operation
A DEBUG operation always outputs all indicators which are set at the
time the DEBUG operation code is executed.
DEBUG statements can be left in a program and turned on and off by
placing a 1 in column 15 of the Control specification. When turned off,
DEBUG files and statements are ignored by the compiler and are not
included in the executable image. To turn debug on, a 1 must be placed in
column 15 of the Control specification and the program must be recompiled
and relinked.
The DEBUG operation code is useful for checking the contents of fields
and tracking a program through its cycle.
After debugging a program with the DEBUG operation code, don’t forget
to turn debug off by blanking out column 15 in the Control specification
and recompiling and relinking the program. Otherwise, the program will
continue to produce DEBUG files each time it is run.
11–30
Operation Codes
Example 11–18 DEBUG Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
* The 1 in column 15 of the Control specification
* indicates that DEBUG is to be turned on in this
* program.
H 1
.
.
.
F* This File specification defines the DEBUG file.
F* In this case the file is defined as a PRINTER
F* file. A DEBUG file can also be defined as a
F* DISK file. DEBUG files are always defined as
F* output files.
F*
FERROR O 80 PRINTER
.
.
.
C* This DEBUG operation will print the literal
C* ’START’, the contents of the field NAME, and
C* all indicators currently set in the DEBUG file
C* ERROR.
C*
C ’Start’ DEBUGERROR NAME
.
.
.
C* The first DEBUG operation in this section will
C* output the literal ’ACCNT’ and the contents of
C* the field ACCNT and all indicators currently
C* set to the DEBUG file ERROR. The second DEBUG
C* operation will output the label ’END’ and all
C* of the indicators currently set to the DEBUG
C* file ERROR.
C*
C ’ACCNT’ DEBUGERROR ACCNT
C ’End’ DEBUGERROR
Example 11–19 DEBUG Output
DEBUG = Start INDICATOR ON = L0 01 03

FIELD VALUE = MICHAEL
DEBUG = ACCNT INDICATOR ON = L0 01 03 22
FIELD VALUE = 12439
DEBUG = End INDICATOR ON = L0 01 03 22
DEBUG = Start INDICATOR ON = L0 01 03
FIELD VALUE = GEORGE
.
.
.
DEBUG = ACCNT INDICATOR ON = L0 22 45 LR
FIELD VALUE = 97983
DEBUG = End INDICATOR ON = L0 22 45 LR
This is an example of what the output to a DEBUG file using the

instructions from the previous example might look like.
11–31
Operation Codes
11.12.12- DEFN Operation (Field Definition)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blnk *LIKE DEFN Required Required Blank Blank Blank
Description
The Field Definition operation allows the programmer to define data fields
based on the attributes of other fields in the program.
Rules
Conditional indicators in columns 7 - 8 are optional.
Conditional indicators in columns 9 - 17 are not allowed.
Factor 1 is required. It must always contain the entry *LIKE.
Factor 2 is required. It must contain the name of the field that provides
the attributes for the field being defined. Factor 2 cannot be a literal or
data structure name. Factor 2 can be a field name, array, array element,
table, or data structure element.
The result field is required. It must contain the name of the field to be
defined. It cannot contain the name of an array, array element, table, or
data structure.
Entries in columns 49 - 51 (field length) are optional. They can be used
to make the field length of the entry in the result field longer or shorter
than the field length of the entry in factor 2. A plus (+) coded in column
49 indicates that the length of the new field will be increased. A minus
(-) coded in column 49 indicates that the length of the new field will be
decreased. Entries in columns 50 - 51 indicate how much to increase or
decrease the field length. If columns 49 - 51 are left blank, the field length
will be the same as that of the entry in factor 2.
Increasing a numeric field beyond 15 characters or an alphameric field
beyond 256 characters will generate a compile time error. Decreasing a
field to less than one or changing the number of decimal places defined for
it will also generate a compile time error.
The number of decimal positions in a numeric field defined by a DEFN
operation cannot be changed. The new field will have the same number of
decimal positions as the entry in factor 2.
11–32
Operation Codes
Example 11–20 DEFN Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C *LIKE DEFN TONSIL THROAT
C *LIKE DEFN TEETH MOUTH +08
C *LIKE DEFN TOES FEET -02
In this example, the DEFN operation is being used to define three fields.
The first field, THROAT, will be defined with the same characteristics as
the field TONSIL. The second field, MOUTH, will have the same data type
as the field TEETH, but will be 8 characters longer in length. The third
field, FEET, will have the same data type as the field TOES, but will be 2
characters shorter in length.
11–33
Operation Codes
11.12.13- DIV Operation (Divide)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional DIV Required Required Opt Opt Opt
Description
The Divide operation allows two numeric fields to be divided, with the
quotient being placed in the result field.
Rules
All fields specified in an DIV operation must be numeric.
Factor 1 is optional. If it is 0, the result of the DIV operation will be 0.
The contents of factor 1 are not affected by the DIV operation.
Factor 2 is required. It cannot be 0. If factor 2 is 0, the program will abort
with a divide-by-zero error. If factor 1 is present, it is divided by factor
2 and the quotient is placed in the result field. If factor 1 is not present,
the contents of the result field are divided by factor 2 and replaced in the
result field. The contents of factor 2 are not affected by the DIV operation.
The result field is required. It will contain the quotient produced by the
DIV operation.
Resulting indicators (columns 54 - 59) are optional. They can be used to
indicate whether the contents of the result field after the DIV operation
are positive (columns 54 - 55), negative (columns 56 - 57), or zero (columns
58 - 59).
Operation
Any remainder resulting from the DIV operation will be lost unless a MVR
(Move Remainder) operation immediately follows the DIV operation. See
Section 11.12.38 for more information on the MVR operation.
Half adjust (column 53 of the Calculation specification) cannot be specified
for a DIV operation immediately followed by an MVR operation.
11–34
Operation Codes
Example 11–21 DIV Operation Code Usage - Indicator Controlled
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C 03 DISCNT DIV STKPRC PERCNT 22H
In this example, the DIV operation divides the field STKPRC into DISCNT
and places the product in PERCNT. Note that PERCNT is being defined in
the Calculation specifications as a numeric field with two decimal places.
Half-adjust has been specified in column 53 to round the results of the
DIV operation. This operation will only be executed if indicator 03 is on.
Example 11–22 DIV Operation Code Usage - Control Break
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
CL1 DIV CARSTK CARPCT 22H
In this example, the field CARPCT will be divided by CARSTK and the
result placed in CARPCT. Note that this operation only takes place during
L1 control break processing.
Example 11–23 DIV and MVR Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
CL3 RIP DIV OFF SCAM 52
CL3 MVR PORK 42
In this example, the field RIP will be divided by OFF, with the result being
placed in SCAM. Any remainder from this DIV operation will be placed in
the field PORK by the MVR operation. Note that this operation only takes
place during L3 control break processing.
11–35
Operation Codes
11.12.14- DO Operation (DO Loop)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional DO Optional Optional Blank Blank Blank
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank END Optional Blank Blank Blank Blank
Description
The DO operation allows a set of operations to be performed a fixed
number of times. The DO operation code, the operation codes which follow
it, and the associated END operation code constitute a DO loop. The DO
operation code is considered a structured operation code.
Rules
Conditional indicators (columns 7 - 17) are optional. They can be specified
on both the DO statement and the associated END statement. Conditional
indicators on a DO operation are processed as follows:
• If the conditional indicators on the DO operation are not satisfied,
control passes to the next executable statement following the
associated END statement.
• If conditional indicators are satisfied on the DO operation, processing
of the DO loop begins. Conditional indicators on a DO operation are
checked once at the beginning of the DO loop, meaning that once
conditions have been satisfied to begin execution of the DO loop, they
are not checked again as the DO loop executes.
• When execution of the DO loop operations reaches the associated END
statement, conditional indicators on the END statement are checked.
If the conditional indicators are not satisfied, control passes out of
the DO loop to the next executable instruction. If the conditional
indicators are satisfied, and the index value is less than the limit
value, control passes back to the beginning of the DO loop.
A complete description of the DO loop cycle appears later in this section.
11–36
Operation Codes
Factor 1 is optional. If specified, it must contain a numeric entry with zero

decimal places. Factor 1 serves as the start value for the DO loop. When a
DO loop begins execution, the contents of factor 1 are moved to the result
field, overriding any value which might already be in the result field. If
factor 1 is not specified, the start value defaults to 1.
Factor 2 is optional. If specified, it must contain a numeric entry with
zero decimal places. Factor 2 serves as the limit value for the DO loop. If
factor 2 is not specified, the limit value defaults to 1.
The result field is optional. If specified, it must contain a numeric entry
with zero decimal places. The result field serves as the index value for
the DO loop. If the result field is not specified, the compiler will generate
an internal index field for the DO loop. The contents of factor 1, or the
start value, are always moved to the index field when a DO loop begins
execution.
Factor 2 on the associated END operation is also optional. If specified, it
must contain a positive numeric entry with zero decimal places. Factor
2 in the END operation serves as an increment value for the DO loop. If
factor 2 is not specified, the increment value defaults to 1.
Operation
A DO loop is executed as follows:
1 Conditional indicators (columns 7 - 17) on the DO operation are
checked. If satisfied, the DO operation is performed. If not satisfied,
control is passed to the first executable statement following the
2 The starting value in factor 1 is moved to the index value in the result
field.
3 If the index value is greater than the limit value in factor 2, control is
passed to the first executable statement following the associated END
statement, terminating the DO loop. Otherwise, execution of the DO
loop proceeds. The comparison carried out in a DO operation follows
standard RPG comparison rules. These rules are discussed earlier in
this chapter in Section 11.4.
4 Operations within the DO loop are executed.
5 When the associated END statement is reached, its conditional
indicators are checked. If the conditional indicators are not satisfied,
control passes to the next executable statement following the END
statement, terminating the DO loop.
6 If conditional indicators on the END statement are satisfied, the END
operation is performed. The increment value in factor 2 of the END
operation is added to the index value of the DO operation. Control
then passes back to step 3 in the DO loop. Note that steps 1 and 2 are
not performed again, meaning that conditional indicators on the DO
operation are not tested again.
11–37
Operation Codes
Some points to keep in mind when using the DO operation:

• If the limit value specified in factor 2 of the DO operation is greater
than the starting value specified in factor 1, the DO loop will never
execute.
• Specifying a negative or zero increment value in the associated END
operation may result in an infinite DO loop.
• If data fields have been specified for the start value, limit value,
index value, or increment value, they can be modified by operations
within the DO loop to affect the termination of the DO loop. Caution
is advised when manipulating these values, as the DO loop may be
thrown into an infinite loop or terminated unexpectedly if the values
are handled incorrectly.
Example 11–24 DO Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C 22 STRT4 DO LIM4
C MULT STRT4 SUBTOT 40
C SETON 04
C EXCPT
C SETOF 04
C 23 END 4
In this example, a DO loop will be executed if indicator 22 is on. It will

execute until the value in STRT4 is greater than the limit value in LIM4.
Each time the DO loop executes, the value in STRT4 will be incremented
by 4, which is specified as the increment value in factor 2 of the associated
END statement.
When the DO loop is entered, if indicator 22 is off, control will pass to
the statement immediately following the END statement. If indicator 22
is on, the value of STRT4 is 1, and the value of LIM4 is 20, the loop will
be executed 5 times, provided indicator 23 is on. If indicator 23 is not on,
processing will continue with the statement immediately following the
END statement.
11–38
Operation Codes
11.12.15- DOUxx Operation (Do Until Loop)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required DOUxx Required Blank Blank Blank Blank
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank END Blank Blank Blank Blank Blank
Description
The Do Until operation performs a set of instructions until the condition
specified by the xx portion of the instruction is met. The DOUxx operation
code, the operation codes which follow it, and the associated END
operation code constitute a DOUxx loop. The DOUxx operation code is
considered a structured operation code.
Rules
on both the DOUxx statement and the associated END statement.
Conditional indicators on a DOUxx operation are processed as follows:
• If the conditional indicators on the DOUxx operation are not satisfied,
associated END statement. If conditional indicators are satisfied
on the DOUxx operation, processing of the DOUxx loop begins.
Conditional indicators on a DOUxx operation are checked once at
the beginning of the DOUxx loop, meaning that once conditions have
been satisfied to begin execution of the DOUxx loop, they are not
checked again as the DOUxx loop executes.
• When execution of the DOUxx loop operations reaches the associated
END statement, conditional indicators on the END statement are
checked. If the conditional indicators are not satisfied, control passes
out of the DOUxx loop to the next executable instruction. If the
conditional indicators are satisfied, the comparison test specified in
factor 1 and factor 2 of the DOUxx operation is carried out. If the
comparison is false, control passes back to the beginning of the DOUxx
loop. If the comparison is true, control passes out of the DOUxx loop
to the next executable instruction.
11–39
Operation Codes
A complete description of the DOUxx loop cycle appears later in this

section.
The comparison carried out in a DOUxx operation follows standard RPG
Section 11.4.
ANDxx and ORxx operations can be associated with a DOUxx operation.
All conditions in a DOUxx construct must be met before the DOUxx loop
will terminate.
A DOUxx construct is always executed at least one time.
The xx portion of the DOUxx operation can be one of the following
instructions:
factor 2.
equal to factor 2.

Operation
A DOUxx loop is executed as follows:
1 Conditional indicators (columns 7 - 17) on the DOUxx operation
are checked. If satisfied, the DOUxx construct is performed. If not
satisfied, control is passed to the first executable statement following
the associated END statement.
2 Operations within the DOUxx loop are executed.
statement, terminating the DOUxx loop. If conditional indicators
on the END statement are satisfied, the contents of the factor 1
and factor 2 fields specified in the DOUxx operation are compared.
(Note this comparison takes place at the end of the DOUxx loop. If
the conditions specified by the DOUxx operation and any associated
ANDxx and ORxx operations are true, the DOUxx loop is terminated
11–40
Operation Codes
and control is passed to the next executable statement following the

associated END statement. If the conditions specified by the DOUxx
operation and any associated ANDxx and ORxx operations are false,
control is passed back to step 2 in the DOUxx loop. Note that step
1 is not performed again, meaning that conditional indicators on the
DOUxx operation are not tested again.
Some points to keep in mind when using the DOUxx operation:

• The data fields specified in factor 1 and factor 2 of the DOUxx
operation and any associated ANDxx and ORxx operations can be
modified by operations within the DOUxx loop to affect the termination
of the DOUxx loop. Caution is advised when manipulating these
values, as the DOUxx loop may be thrown into an infinite loop or
terminated unexpectedly if the values are handled incorrectly.
Example 11–25 DOUxx Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C INCOME DOUGTTAXES
C ADD 1 WEEK
C INCOME ADD PAYCHK INCOME
C END
In this example, the DOUxx loop will be executed until the field INCOME
is greater than the field TAXES.
11–41
Operation Codes
11.12.16- DOWxx Operation (Do While Loop)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required DOWxx Required Blank Blank Blank Blank
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Description
The Do While operation performs a set of instructions until the condition
specified by the xx portion of the instruction is no longer true. The DOWxx
operation code, the operation codes which follow it, and the associated
END operation code constitute a DOWxx loop. The DOWxx operation code
is considered a structured operation code.
Rules
on both the DOWxx statement and the associated END statement.
Conditional indicators on a DOWxx operation are processed as follows:
• If the conditional indicators on the DOWxx operation are not satisfied,
associated END statement. If conditional indicators are satisfied
on the DOWxx operation, processing of the DOWxx loop begins.
Conditional indicators on a DOWxx operation are checked once at
the beginning of the DOWxx loop, meaning that once conditions have
been satisfied to begin execution of the DOWxx loop, they are not
checked again as the DOWxx loop executes.
• The relation between factor 1 and factor 2 on the DOWxx operation
is checked. If the relation is true, execution of the DOWxx construct
proceeds. If the relation is false, the DOWxx loop is terminated
and control is passed to the next executable statement following the
• When execution of the DOWxx loop operations reaches the associated
END statement, conditional indicators on the END statement are
checked. If the conditional indicators are not satisfied, control
passes out of the DOWxx loop to the next executable instruction.
11–42
Operation Codes
If the conditional indicators are satisfied, control passes back to the

beginning of the DOWxx loop.
A complete description of the DOWxx loop cycle appears later in this

section.
The comparison carried out in a DOWxx operation follows standard RPG
Section 11.4.
ANDxx and ORxx operations can be associated with a DOWxx operations.
All conditions in a DOWxx construct must be met before the DOWxx loop
will execute.
The xx portion of the DOWxx operation can be one of the following
instructions:
factor 2.
equal to factor 2.

Operation
A DOWxx loop is executed as follows:
1 Conditional indicators (columns 7 - 17) on the DOWxx operation
are checked. If satisfied, the DOWxx operation is performed. If not
satisfied, control is passed to the first executable statement following
the associated END statement.
2 The contents of factor 1 and factor 2 are compared. As long as the
conditions specified by the DOWxx operation and any associated
ANDxx and ORxx operations are true, the DOWxx loop will be
executed. If the comparison operations are false, control is passed
to the next executable statement following the associated END
statement.
3 Operations within the DOWxx loop are executed.
11–43
Operation Codes

statement, terminating the DOWxx loop. If conditional indicators on
the END statement are satisfied, control is passed back to step 2 in the
DOWxx loop. Note that step 1 is not performed again, meaning that
conditional indicators on the DOWxx operation are not tested again.
Some points to keep in mind when using the DOWxx operation:

• The data fields specified in factor 1 and factor 2 of the DOWxx
operation and any associated ANDxx and ORxx operations can
be modified by operations within the DOWxx loop to affect
the termination of the DOWxx loop. Caution is advised when
manipulating these values, as the DOWxx loop may be thrown into
an infinite loop or terminated unexpectedly if the values are handled
incorrectly.
Example 11–26 DOWxx Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C N10 PRINC DOWLTLOAN
C ADD 1 MONTHS
C PAYMNT SUB INTRST PRINC
C END
In this example, the DOWxx loop will not execute if indicator 10 is on. If
indicator 10 is off, the DOWxx loop will execute as long as the value of
PRINC is less than the value of LOAN.
11–44
Operation Codes
11.12.17- ELSE Operation (IF/ELSE Operation)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blnk Blank ELSE Blank Blank Blank Blank Blank
Description
The ELSE operation can be paired with an IFxx operation. It allows the
program to execute a set of instructions if the IFxx operation conditions
are not met.
Rules
An ELSE operation must appear within the bounds of an IFxx/END
construct. Only one ELSE operation can be paired with an IFxx operation.
Conditional indicators in columns 7 - 8 are optional. If used, they must
match the conditional indicator appearing in the associated IFxx and END
operations.
Factor 1, factor 2, and the result field must be blank.
Operation
In an IFxx/ELSE/END construct, the operations bound by the ELSE
statement and the associated END statement will be performed if the IFxx
condition is not true. If the IFxx condition is true, the instructions bound
by the IFxx statement and the ELSE statement will be performed and
the statements bound by the ELSE statement and the associated END
statement will be skipped.
11–45
Operation Codes
Example 11–27 ELSE Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C GUN IFEQ LOADED
C EXSR SHOOT
C ELSE
C EXSR LOAD
C END
In this example, the subroutine SHOOT will be executed if the IFxx

statement comparing GUN and LOADED is true. If the IFxx statement
is not true, control will transfer to the statements following the ELSE
operation code and the subroutine LOAD will be executed.
11–46
Operation Codes
11.12.18- END Operation
END Associated With The DO Operation Code
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank END Optional Blank Blank Blank Blank
END Associated With The DOUxx And DOWxx Operation Codes
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
END Associated With The IFxx And CASxx Operation Codes
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Description
The END operation is used to specify the end of a CASxx, DO, DOUxx,
DOWxx, or IFxx/ELSE construct. END statements are always associated
with one of these structured operation codes.
Rules
Conditional indicators in columns 7 - 8 are optional on all END operations.
If these indicators are specified, they must match the conditional indicator
specified on the structured operation code associated with the END
statement.
Conditional indicators in columns 9 - 17 are not permitted on END
statements associated with CASxx and IFxx/ELSE operations.
Conditional indicators in columns 9 - 17 are optional in END statements
which are associated to the DO, DOUxx, and DOWxx operations. Sections
11.12.14, 11.12.15, and 11.12.16 describe these operation codes and the use
of conditional indicators on their associated END statements.
Factor 1, factor 2, and the result field must all be blank on all END
operations with the exception of the END operation associated with a DO
operation. An END operation associated with a DO operation can have an
optional entry in factor 2. See Section 11.12.14 for more information on
the END operation associated with the DO operation.
11–47
Operation Codes
Resulting indicators (columns 54 - 59) are not allowed on any END

operation.
Examples of END statement usage are displayed in the examples
associated with the structured operation code descriptions. See Sections
11.12.8, 11.12.14, 11.12.15, 11.12.16, and 11.12.27 for examples of END
operation usage.
11–48
Operation Codes
11.12.19- ENDSR Operation (End Subroutine)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blnk Optional ENDSR Optional Blank Blank Blank Blank
Description
The End Subroutine operation defines the end of an internal RPG
subroutine.
Rules
The ENDSR statement must be the last statement in a subroutine.
The entry of SR in columns 7 and 8 is optional. Conditional indicators are
not allowed.
An entry in factor 1 is optional. Factor 1 can contain a unique label
which can be used by GOTO and CABxx operations within the subroutine.
Branching to a label or TAG within a subroutine from outside of the
subroutine is not permitted.
If the subroutine is an INFSR subroutine, an entry in factor 2 is optional.
Otherwise, factor 2 must be blank. See the Migration RPG Screen Format
Reference Manual for information on the coding and execution of an INFSR
subroutine.
Operation
The ENDSR operation signifies the end of an internal RPG subroutine.
When it is processed, program control is returned to the first executable
statement following the EXSR or CASxx operation which called the
subroutine. The only exception to this rule is when the subroutine in
question is an INFSR (exception) subroutine.
11–49
Operation Codes
Example 11–28 ENDSR Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
CSR COOLER BEGSR
.
.
.
CSR CHIPS CABEQ0 POP
.
.
.
CSR POP ENDSR
In this example, the ENDSR operation signifies the end of the internal
RPG subroutine COOLER. Note the use of the label POP on the ENDSR
statement. If the condition checked by the CABxx operation within the
subroutine COOLER is true, control will branch to the label POP on the
ENDSR statement.
11–50
Operation Codes
11.12.20- EXCPT Operation (Exception Output Operation)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank EXCPT Optional Blank Blank Blank Blank
Description
The EXCPT operation allows records to be output during detail time or
total time calculations or a screen to be displayed to a WORKSTN device.
Rules
On the Calculation specification:
• Conditional indicators (columns 7 - 17) are optional.
• Factor 1 must be blank.
• Factor 2 is optional. It can be used to specify a unique 1 - 6 character
name which is associated to the exception records in the Output
specifications.
• The result field must be blank.
• Resulting indicators (columns 54 - 59) are not allowed.
On the Output specifications:

• An E must be specified in column 15 (Type) of the output record
definition.
• Columns 32 - 37 in the output record definition can contain the
exception name which was specified in factor 2 of the EXCPT
statement.
• Only exception records (E in column 15) can contain exception names
in columns 32 - 37.
• Overflow indicators cannot be specified in columns 23 - 31 of an
exception record.
Operation
If the exception name is blank in factor 2 of the EXCPT operation,
exception output records with a blank name in columns 32 - 37 that
satisfy the conditional indicators in columns 23 - 31 will be output.
If an exception name is declared in factor 2 of the EXCPT operation,
exception output records with a matching name in columns 32 - 37 that
satisfy the conditional indicators in columns 23 - 31 will be output.
11–51
Operation Codes
An exception name can be used on multiple EXCPT operations and on

multiple exception output records.
Example 11–29 EXCPT Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
FFIRDAT O 128 DISK
FREPORT O 80 PRINTER
.
.
.
C* The following EXCPT operation is unlabeled. All
C* exception output records which do not have a label
C* in columns 32 - 37 will be processed by this
C* operation.
C*
C EXCPT
C*
C* The following EXCPT operation will only be
C* executed if indicator 10 is on. It will process
C* all exception output records with the label REPORT
C* in columns 32 - 37.
C*
C 10 EXCPTREPORT
C*
C* The following EXCPT operation will only be
C* executed if indicators 10 and 20 are on and
C* indicator 30 is off. It will process all
C* exception output records with the label DATA
C* in columns 32 - 37.
C*
C 10 20N30 EXCPTDATA
.
.
.
O* The following record will be output when the
O* EXCPT operation labeled DATA is executed.
O*
OFIRDAT E DATA
O LOCTN 10
O DAMAGE 20
*
OLST H 1P
O 40 ’FIRE REPORT’
*
O* The following record will be output when
O* the unlabeled EXCPT operation is executed.
O*
O E
O LOCTN 20
O DAMAGE 60
*
O* The following record will be output when
O* the unlabeled EXCPT operation is executed
O* and indicator 22 is on.
O*
O E 22
O CALTIM 10
O RSPTIM 20
11–52
Operation Codes
Example 11–29 (Cont.) EXCPT Operation Code Usage

1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
O* The following record will be output when the
O* EXCPT operation labeled REPORT is executed
O* and indicator 44 is off.
O*
O E N44 REPORT
O TRUCKS 10
O PERNSL 40
This example demonstrates the use of the EXCPT operation to output data
to a disk file and a report during calculation processing.
11–53
Operation Codes
11.12.21- EXIT Operation (External Subroutine Call)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank EXIT Required Blank Blank Blank Blank
Description
The EXIT operation allows an RPG program to call an external subroutine.
In Migration RPG programs, the CALL operation code can be used to
accomplish the same function. The EXIT operation code is retained by
Migration RPG to maintain compatibility with other versions of RPG and
to support the MSI-supplied subroutines SUBR01, SUBR21, and SUBR23.
Rules
Factor 2 is required. It must contain the name of the external subroutine
which is to be called by the EXIT operation. If the subroutine is not one
of the MSI-supplied subroutines (SUBR01, SUBR21, or SUBR23), then the
subroutine must be linked to the RPG program.
Operation
RLABL statements can be associated to an EXIT operation. The RLABL
statements must immediately follow the EXIT operation.
An EXIT operation functions much like a CALL operation in that it passes
program control to an external subroutine or subprogram. When the
external routine has completed execution, it returns control to the first
executable statement following the EXIT/RLABL construct.
11–54
Operation Codes
Example 11–30 EXIT Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C EXIT SUBR23
C RLABL MIC
C RLABL DATAST
C RLABL LEVEL
C RLABL RCODE 10
This example demonstrates the use of the EXIT operation code to call the
MSI-supplied message member subroutine SUBR23.
11–55
Operation Codes
11.12.22- EXSR Operation (Execute Subroutine)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank EXSR Required Blank Blank Blank Blank
Description
The Execute Subroutine operation causes program control to be passed
to an internal RPG subroutine. When the subroutine has completed
execution, control is returned to the first executable statement following
the EXSR statement.
Rules
Factor 2 is required. It must contain the name of the subroutine which
is being called. The program must also contain a BEGSR operation code
which contains the subroutine name in factor 1.
Example 11–31 EXSR operation code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C N10 EXSR MOUNTN
.
.
.
CSR MOUNTN BEGSR
.
.
.
CSR ENDSR
This example demonstrates the use of the EXSR operation code to call the
internal RPG subroutine MOUNTN. Note that the EXSR operation will
only be executed if indicator 10 is off.
11–56
Operation Codes
11.12.23- EXTRN Operation (External Name Definition)
Indicators Factor 1 Opcode Factor 2
7−8 9−17 18−27 28−32 33−63
Blk Blk Required EXTRN Literal
Description
The EXTRN operation is used to define program names exceeding eight (8)
characters in length for the CALL and FREE operation codes.
Rules
Factor 1 and factor 2 are required entries for this operation code.
Conditional indicator entries (columns 9 - 17) are not permitted.
Factor 1 is used to name the field Migration RPG initializes, using the
value specified in factor 2. Factor 1 of the EXTRN operation is defined as
an alphameric field. This field can only be used with the CALL and FREE
operation codes and cannot be defined elsewhere in the program.
Factor 2 is used to name the external constant. A maximum of 31
characters can be used to name the constant. The constant must be
enclosed in apostrophes. The constant can be a valid OpenVMS program
name.
Operation
The EXTRN operation initializes the value of an alphameric field to a
link-time constant. It is used to assign a program name exceeding eight
(8) characters in length to a field name which can be used with the CALL
and FREE operation codes.
11–57
Operation Codes
Example 11–32 EXTRN, CALL, and FREE Operation Code Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890
C* This example depicts the use of the EXTRN operation
C* code to define the program BOEING_747_JUMBO. The
C* program FLY can then be referenced as a subprogram
C* using the CALL and FREE operation codes.
*
C FLY EXTRN’BOEING_747_JUMBO’
.
.
.
C CALL FLY
.
.
.
C FREE FLY
11–58
Operation Codes
11.12.24- FORCE Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Blk Opt Blank FORCE Required Blank Blank Blank Blank
Description
The FORCE operation allows selection of the next file from which a record
is read during multi-file processing.
Rules
Conditional indicators in columns 7 - 8 are not permitted.
Factor 2 must contain the name of the file against which the FORCE
operation is to be executed against. The file name must match a name
specified in columns 7 - 14 of the File Description specifications of an input
or update file.
Operation
The FORCE operation can be used for primary or secondary input and
update files. The FORCE operation cannot be used to read records from
WORKSTN or KEYBORD files.
When a FORCE operation is executed, it identifies the file from which the
next record will be read. The read is performed at the beginning of the
next program cycle. If more than one FORCE operation is executed during
the same program cycle, all but the last are ignored.
Although FORCE operations override normal multi-file processing, they
cannot override the first record selected by the program. Input of the first
record occurs in the first cycle before the first pass through calculations.
If a FORCE operation is issued for a file that is at its end-of-file, the file is
not selected for processing. In this case, normal multi-file processing logic
selects the next record.
A FORCE operation bypasses matching record processing.
11–59
Operation Codes
Example 11–33 FORCE Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
F*
FINNMST IP 20 DISK
FPARTS IS 20 DISK
.
.
.
C 01 FORCEPARTS
In this example, if the indicator 01 is on, the FORCE operation will be

executed, indicating that the next record read at the beginning of the next
RPG cycle will come from the PARTS file.
11–60
Operation Codes
11.12.25- FREE Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank FREE Required Blank Blank Opt Blank
Description
The FREE operation is used to remove an RPG subprogram from the
active list and ensure that subprogram initialization (first cycle processing)
takes place the next time the subprogram is called.
Rules
Factor 2 is required. It must contain an alphameric literal or a field
defined by the EXTRN operation code that names the subprogram. This
can be a valid OpenVMS program name. Factor 2 cannot be an array
element or data field name. The program specified in factor 2 must be a
Migration RPG program. Submitting a non-Migration RPG program to the
FREE operation code will produce unpredictable results. When specifying
a program name which exceeds 8 characters, use the EXTRN operation
code to define a field which represents the program name.
An error indicator can be specified in columns 56 and 57. The error
indicator will be turned on if the FREE operation is submitted to a
subprogram which has never been called or which was already freed
in a previous operation.
Resulting indicators in columns 54 - 55 and 58 - 59 are not allowed.
Operation
When a Migration RPG subprogram is called for the first time, normal
program initialization, such as file opens and field initialization, takes
place. After that, as long as the subprogram is not terminated normally
(LR indicator on) or abnormally (halt indicator on or error), each time the
program is called, it resumes operations where it left off at the previous
exit, very much like an internal subroutine. Thus, program initialization
is skipped during each additional call after the first one as long as the
subprogram has not been ended and the FREE operation code has not been
exercised against it. The FREE operation code provides the programmer
with another method to place a subprogram back into its initial starting
state.
11–61
Operation Codes
Example 11–34 FREE Operation code Use
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C* This example depicts the use of the FREE operation code
C* to reinitialize the program SKI.
*
C CALL SKI
.
.
.
C FREE SKI
11–62
Operation Codes
11.12.26- GOTO Operation (Branching Operation)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank GOTO Required Blank Blank Blank Blank
Description
The GOTO operation allows a program to pass control to a label defined by
a TAG or ENDSR operation, skipping all intervening instructions.
Rules
Factor 2 is required. It must contain the label of the TAG or ENDSR
operation to which the program is to branch. A label can be 1 - 6
characters long and must begin with an alpha character.
Operation
Branching using the GOTO operation must comply with the following
conditions:
• A GOTO operation can branch from any point in the detail calculations
section to any TAG in the detail calculations section.
• A GOTO operation can branch from any point in the total time
calculations section to any TAG in the total time calculations section
with the exception of last record calculations (LR in columns 7 - 8 of
the Calculation specification).
• A GOTO operation can branch to any TAG or ENDSR statement
within the confines of a subroutine.
• A GOTO operation cannot branch from the detail calculation section to
the total time calculation section, or vice versa.
• A GOTO operation cannot branch from outside a subroutine to a TAG
or ENDSR within a subroutine, or vice versa.
• A GOTO operation cannot branch from outside the last record
calculations section to within the last record calculations section,
or vice versa.
11–63
Operation Codes
Example 11–35 GOTO Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C LOOP TAG
.
.
.
C 10N12 GOTO LOOP
In this example, the GOTO operation is executed if indicator 10 is on

and indicator 12 is off. The GOTO operation will cause the program to
branch back to the TAG operation LOOP, which was defined earlier in the
program.
11–64
Operation Codes
11.12.27- IFxx Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required IFxx Required Blank Blank Blank Blank
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Description
The IFxx operation allows a set of instructions to be performed based on
whether the condition in the xx portion of the instruction is true. IFxx
operations can be combined with ANDxx and ORxx operations to make the
condition more complex. IFxx operations can also be paired with the ELSE
operation to allow an additional set of instructions to be executed should
the IFxx condition be false. The IFxx operation is always paired with an
END operation and is considered a structured operation code.
Rules
Conditional indicators in columns 7 - 8 are optional. If specified, the same
indicator must be used on the IFxx operation, optional ELSE operation,
and associated END operation.
Conditional indicators in columns 9 - 17 are optional on the IFxx
statement. They are not allowed on associated ELSE and END
statements. Conditional indicators on the IFxx operation control whether
the entire IFxx construct is executed or skipped. The complete operation
of an IFxx construct is detailed later in this section.
alphameric or numeric. The comparison carried out in an IFxx operation
follows standard RPG comparison rules. These rules are discussed earlier
in this chapter in Section 11.4.
11–65
Operation Codes
The xx portion of the IFxx operation can be one of the following

instructions:
factor 2.
equal to factor 2.

ANDxx and ORxx operations can be associated with an IFxx operation.
All conditions in an IFxx structure must be met before the statements
immediately following the IFxx are executed. If an ELSE operation has
been included in the IFxx construct, the statements immediately following
the ELSE operation will be executed if the IFxx conditions are not met.
Operation
An IFxx operation is processed as follows:
• If present, the conditional indicators in columns 9 - 17 are checked. If
the conditions are met, processing continues with the IFxx operation.
If the conditions are not met, program control is passed to the first
executable instruction following the associated END statement.
• The comparison operation specified by the xx of the IFxx operation
and any associated ANDxx and ORxx operations are carried out. The
following actions will occur based on the results of the comparisons
and the structure of the IFxx construct:
— If the comparison operations are true, then the statements
following the IFxx operation will be executed. Execution
will continue until an associated ELSE or END statement is
encountered. If the statement encountered is an ELSE operation,
control will pass to the first executable instruction following the
— If the comparison operations are false and there is no ELSE
operation associated with the IFxx operation, control will be
passed to the first executable statement following the associated
END statement.
— If the comparison operations are false and there is an ELSE
operation associated with the IFxx operation, control will be
passed to the first executable statement following the associated
ELSE statement.
11–66
Operation Codes
Example 11–36 IFxx Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C AIR IFGT PLANE
C Z-ADD1 RCODE
C Z-ADDTEST MIC 40
C Z-ADD1 LEVEL 10
C END
C*
C TRAIN IFLE TRACK
C EXSR PF
C Z-ADD2 XX 141011
C ELSE
C EXCPTLAST
C EXCPTDETAIL
C END
In this example, the two IFxx operations demonstrate an IFxx/END and

an IFxx/ELSE/END construct. In the first IFxx operation, the Z-ADD
instructions bound by the IFxx and END statements are executed if the
contents of the field AIR are greater than the field PLANE. In the second
IFxx operation, the EXSR and Z-ADD instructions are executed if the
contents of the field TRAIN are less than or equal to the field TRACK. If
this condition is not true, the EXCPT instructions bound by the ELSE and
END statements will be executed.
11–67
Operation Codes
11.12.28- KEYnn Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional KEYnn Blank Required Opt Opt Opt
Description
The KEYnn operation pauses a program during calculations and allows
the user to enter data from their terminal.
Rules
To use the KEYnn operation, a KEYBORD device must be specified in the
File Description specifications.
KEYnn operations are always directed at the terminal which invoked the
program.
KEYnn operations should not be specified in programs that are run as
batch jobs.
Factor 1 is optional. It can contain a literal, field, table, array, or data
structure element. The contents of factor 1 will be displayed when the
KEYnn operation is executed. If factor 1 is not specified, a message
member code must be specified with the KEYnn operation code.
The nn portion of the KEYnn operation code can be blank or can specify
a message member number from the User Level 1 message member file
(RPGUSRLV1). If the message member corresponding to the message
number in the KEYnn operation code is found, the message is displayed.
If the message member file is not present or no entry exists which
corresponds to the message number specified, nothing is displayed. If
an entry is made in factor 1 of the KEYnn operation, the message number
is ignored. If no entry is made in factor 1, the message number is required.
See the Migration RPG User’s Guide for more information on creating and
referencing message member files.
The result field is required. It must contain the name of the field which is
to accept the data keyed in by the user. The result field can be a field or a
table, array, or data structure element.
Resulting indicators are optional. They can be used to evaluate the
contents of the result field after the user has entered data. The possible
results of the evaluation are:
11–68
Operation Codes
Columns Meaning Explanation

54 - 55 Plus If the result field is numeric, the indicator is turned on if the
data entered is greater than zero.
56 - 57 Minus If the result field is numeric, the indicator is turned on if the
data entered is less than zero.
58 - 59 Zero If the result field is numeric, the indicator is turned on if the
or data entered is equal to zero.
Blank If the field is alphameric, the indicator is turned on if the result
field contains non-blank characters.
Operation
The KEYnn operation pauses the program and accepts input from the
user. The input is placed in the field specified in the result field of the
KEYnn statement. A KEYnn operation is terminated by pressing one of
the following keys:
• Return or Enter - For a numeric field, enters the field as a positive
number. For an alphameric field, simply enters the field.
• PF1 + Enter - For a numeric field, enters the field as a negative number.
Not valid for alphameric fields.
• PF4 - For a numeric field, enters the field as a positive number. For an
alphameric field, simply enters the field.
When a field is not completely filled by the user, numeric fields are right-
justified and zero-filled while alphameric fields are padded to the left with
blanks.
The user has the following options when responding to a KEYnn operation:
• Data can be entered. If it is, it replaces the contents of the result field.
• A field exit key can be pressed without entering any data. If it is, the
result field is initialized to blanks or zeros, depending upon whether it
is an alphameric or numeric field.
• The DUP key ( PF3 ) can be entered. If it is, the data currently
residing in the result field is not affected by the KEYnn operation.
11–69
Operation Codes
Example 11–37 KEYnn Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FKEYIN IP F 70 70 KEYBORD
.
.
.
C ’Name’ KEY NAME 10
C 10 KEY12 SEX
C 10 AUTO KEY CAR
In this example, the KEYnn operation is used to prompt the user to enter
information from the terminal while the program is executing. Note the
File Description specification for a KEYBORD file. A KEYBORD file must
be defined in the File Description specifications in order to use the KEYnn
operation.
The program will pause and display the prompt ’Name’ when it executes
the first KEYnn operation in the example. Any input entered by the user
will be placed in the NAME field. Note the use of indicator 10 in columns
58 - 59. If an entry is made in the NAME field, indicator 10 will turn
on. If no entry is made, indicator 10 will be turned off. The following two
KEYnn operations will only execute if indicator 10 is on.
The second KEYnn operation will display message number 12 from the
User Level 1 message member file as a prompt. It will accept input into
the SEX field.
The third KEYnn operation will display the contents of the AUTO field as
a prompt. It will accept input into the CAR field.
11–70
Operation Codes
11.12.29- LOKUP Operation
Array LOKUP
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required LOKUP Required Blank One required
Table LOKUP
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required LOKUP Required Optional One required
Description
The LOKUP operation searches for an entry in a table or array.
Rules
Factor 1 is required. It must contain a literal, field, array element, data
structure element, or table name. Factor 1 serves as the search element in
a LOKUP operation. If a table name is specified in factor 1, it refers to the
last element selected by a LOKUP operation, not the entire table.
Factor 2 is required. It must contain the name of the table or array on
which the LOKUP operation is to be performed.
The result field must be blank in an array LOKUP operation. It is optional
in a table LOKUP operation. In a table LOKUP operation, the result field
can contain the name of a related table.
Resulting indicators are required in a LOKUP operation. At least one,
but no more than two, resulting indicators can be specified. Resulting
indicators specify the type of search to be made and indicate the results of
the search.
The resulting indicators function as follows:
• Greater than search
In this case, an indicator is only specified in columns 54 - 55 (high).
The LOKUP operation searches for the first element in the table or
array that is greater than the search element specified in factor 1. If
an entry fulfilling these requirements is found, the high indicator is
turned on.
11–71
Operation Codes
• Less than search

In this case, an indicator is only specified in columns 56 - 57 (low).
array that is less than the search element specified in factor 1. If an
entry fulfilling these requirements is found, the low indicator is turned
on.
• Equal to search
In this case, an indicator is only specified in columns 58 - 59 (equal).
array that is equal to the search element specified in factor 1. If an
entry fulfilling these requirements is found, the equal indicator is
turned on.
• Greater then or equal to search
In this case, indicators are specified in columns 54 - 55 (high) and
58 - 59 (equal). The LOKUP operation searches for the first element in
the table or array that is greater than or equal to the search element
specified in factor 1. If an equal entry is found, the equal indicator is
turned on. If the entry is greater than the search element, the high
indicator is turned on.
• Less than or equal to search
In this case, indicators are specified in columns 56 - 57 (low) and
58 - 59 (equal). The LOKUP operation searches for the first element
in the table or array that is less than or equal to the search element
specified in factor 1. If an equal entry is found, the equal indicator
is turned on. If the entry is less than the search element, the low
indicator is turned on.
• If a LOKUP operation is not successful, none of the resulting indicators
are turned on.
Operation
In the LOKUP operation, factor 1 contains the search argument and factor
2 contains the name of the table or array. The search element can be an
alphameric or numeric literal, a field name, an array element, or a table
name. Search arguments must be the same length and format as the
entries in the table or array being searched. For example, both the search
element and the array or table must be numeric with the same number of
digits, or both must be alphameric with the same number of characters.
Tables and arrays should be sequenced before greater than or less than
type searches are carried out against them. Remember, the LOKUP
operation stops processing as soon as it finds an element which fulfills the
search requirements. If the search is intended to find the highest or lowest
element in the table or array and the table or array is not sequenced, the
search may not return the desired element. Table and array sequencing
can be indicated by an entry in column 45 of the Extension specification.
Compile-time arrays and tables are checked for correct sequencing during
program compilation. If the sequencing is not valid, the compiler will
generate a fatal error.
11–72
Operation Codes
Pre-execution time arrays and tables will generate a halt if they are not
in a valid sequence when being loaded during program initialization.
The user is given the option of continuing or terminating the program in
response to the halt. If the program is continued, the array or table will
be stored in an invalid sequence and may not produce the desired results.
Run-time tables and arrays cannot be checked before a program is
compiled or begins execution. If they are not in sequence, the LOKUP
operation may not produce the desired results. It is advisable to perform
a SORTA operation on run-time arrays before using them in a LOKUP
operation.
Resulting indicators are set off when a LOKUP operation begins. If a
LOKUP operation is not successful, no resulting indicators are turned on.
If an index is used with an array in a LOKUP operation, the search
begins at the array element specified by the index. Elements in the array
preceding the index are not searched.
If the index used with an array in a LOKUP operation is a variable, it will
be set to the number of the array element meeting the search criteria if
such an element is found. If the LOKUP operation is unsuccessful, the
index variable will be set to 1.
11.12.29.1 Table Elements in a LOKUP Operation

Whenever a table name is used in an operation other than as factor 2
or the result field in a LOKUP operation, the table name refers to the
data placed in storage by the last successful LOKUP operation. When a
program is initialized, the first element in the table is placed in storage.
If a table name is specified as factor 1 in a LOKUP operation, the contents
of the storage area are used as the search argument.
A table can also be used as the result field in operations other than a
LOKUP operation. In this case, the contents of the storage area are
replaced by the results of the specified operation. The corresponding entry
in the table is also changed. This allows the contents of a table to be
modified.
11.12.29.2 Searching Tables Using LOKUP

The LOKUP operation can search one table or two related tables. When
searching a single table, the following information must be specified:
• Factor 1 - Search element.
• Factor 2 - Table name.
• At least one resulting indicator.
When the LOKUP operation finds a table entry that satisfies the search,
it places a copy of the entry in a special storage area which can be
referenced in other RPG operations by specifying the table name. This
area is called the table reference field. When another LOKUP operation
completes successfully, the new entry replaces the previous entry in the
table reference field.
11–73
Operation Codes
If a LOKUP operation against a table fails, the table reference field

contents for factor 2 and the optional result field table do not change.
When a program initializes, the first entry in a table is placed in the table
reference field.
Two related tables can be searched if the second table name is specified in
the result field of the LOKUP operation. As used here, the phrase related
tables refers to any two tables defined in a program that contain related
data. It does not refer to primary and secondary tables defined on a single
Extension specification.
When searching for an entry in two related tables, the LOKUP operation
searches only the table specified in factor 2. If the search condition is
satisfied, the LOKUP operation places the corresponding entries from both
the table specified in factor 2 and the table specified in the result field in
their respective storage areas.
To program a search for an entry in related tables, the following
information must be specified:
• Factor 1 - Search element.
• Factor 2 - Table name.
• Result field - Related table name.
• At least one resulting indicator.
Both tables should have the same number of entries. The related table
must have as many or more entries than the table to be searched.
11.12.29.3 Searching Arrays Using LOKUP

LOKUP operations for arrays are similar to those performed on tables.
If the element searched for is found, the appropriate indicator is turned
on. If an indexed array is being searched and the index being used is
a variable, the index is set to the number of the array element found
which satisfies the LOKUP operation. The result field in an array LOKUP
operation must be blank.
When searching a non-indexed array, factor 1 contains the search element.
The search element must be the same length and format as the array
elements. Factor 2 contains the name of the array to be searched. The
search begins with the first element in the array and continues until the
search criteria are met or the end of the array is reached. If an entry
in the array matches the search criteria, then the appropriate resulting
indicator is turned on. If no match is found, the resulting indicators
remain off.
When searching an indexed array, it is possible to have the search start at
the element specified by the index. In this type of search, factor 1 contains
the search element. The search element must be the same length and
format as the array elements. Factor 2 contains the array name followed
by a comma and the index number of the element within the array where
the search is to begin. The LOKUP operation will begin searching the
array at the specified element.
11–74
Operation Codes
If a variable index is used when searching an array, it will be set to the

number of the array element found which matches the search criteria. If
no match is found, the array index variable is set to 1.
The resulting indicators are set or cleared during an indexed array
LOKUP operation in the same fashion as a non-indexed array LOKUP.
11–75
Operation Codes
Example 11–38 LOKUP Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
E* The elements assigned to these tables and array
E* appear at the end of the sample code.
E*
E LBS 1 6 2 A
E TABTUK 1 6 2 0D
E TABCRD 1 6 5 D
.
.
.
C PART LOKUPLBS 08 08
C*
C* In this example, a greater than or equal LOKUP
C* is being performed against the LBS array. If an
C* element in the array is greater than or equal to
C* the contents of PART, indicator 08 will be turned
C* on.
C*
C PART LOKUPLBS,X 11
C*
C* In this example, a greater than search is being
C* performed against the array LBS. If the search
C* is successful, indicator 11 will be turned on.
C* Here the LBS array is using an index variable (X).
C* The LOKUP operation will begin its search at the
C* element specified by X. If X were 3, the LOKUP
C* would begin with the element CC. If PART were
C* XX, this LOKUP would not find a match.
C* Indicator 11 would not be turned on and the
C* variable index X would be set to 1. If PART
C* were DD, this LOKUP would find that element 5,
C* EE, was greater than DD. Indicator 11 would be
C* turned on and the variable X would be set to 5.
C*
C CARD LOKUPTABTUK 66
C*
C* In this example, a less than LOKUP operation is
C* performed on the table TABTUK. If the number
C* specified in the CARD field is less than an element
C* in the table, indicator 66 will be turned on and
C* the element will be placed in the TABTUK storage
C* area. If CARD were equal to 4, the search would
C* be successful, indicator 66 would be turned on,
C* and the element 02 would be placed in the TABTUK
C* storage area.
C*
C CARD LOKUPTABTUK TABCRD 2123
C*
C* In this example, a less than or equal search is
C* performed against the table TABTUK. If the
C* search is successful, either indicator 21 or 23
C* will be turned on and the element in the TABTUK
C* table will be moved to the TABTUK storage area.
C* If the search is successful, the associated
C* element in the TABCRD table will also be moved to
C* the TABCRD storage area. If CARD were 11, the
C* search would be successful and indicator 23
C* (equal) would be turned on. The element 11 from
C* the TABTUK table would be moved to the TABTUK
C* storage area and the associated element JACK
C* would be moved to the TABCRD storage area.
11–76
Operation Codes
Example 11–38 (Cont.) LOKUP Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
O*
** LBS Array
AA
BB
CC
DD
EE
FF
** TABTUK Table
14
13
12
11
02
01
** TABCRD Table
ACE
KING
QUEEN
JACK
TRUMP
FOLD
These examples use the array LBS and the table TABTUK to demonstrate
the use of the LOKUP operation. The results of each operation are
described in the comments associated with each instruction.
The array LBS has the following characteristics:
• It is a compile-time array.
• It contains 1 element per record (columns 33 - 35).
• It has a total of 6 elements (columns 36 - 39).
• Each element has a length of 2 characters (columns 40 - 42).
• The array contains alphameric elements (column 44).
• The array is sorted in ascending order (column 45).
The table TABTUK has the following characteristics:

• It is a compile-time table.
• The table contains numeric elements with 0 decimal places
(column 44).
• The table is sorted in descending order (column 45).
11–77
Operation Codes
Example 11–38 (Cont.) LOKUP Operation Code Usage
The table TABCRD has the following characteristics:

• It is a compile-time table.
• The table contains alphameric elements (column 44).
• The table is sorted in descending order (column 45).
11–78
Operation Codes
11.12.30- MHHZO Operation (Move High Zone to High Zone)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MHHZO Required Required Blank Blank Blank
Description
The Move High Zone to High Zone operation moves the high zone of factor
2 to the high zone of the result field.
Rules
Factor 2 is required. It must contain an alphameric entry.
The result field is required. It must contain an alphameric entry.
Operation
The MHHZO operation moves the zone from the leftmost position of the
entry in factor 2 to the leftmost position of the entry in the result field.
Example 11–39 MHHZO Operation Code Usage
1 2 3 4
1234567890123456789012345678901234567890123456789
C*
C MHHZOPIT PAT
In this example, the zone portion of the leftmost character in the PIT field
will be moved to the zone portion of the leftmost character in the PAT
field.
11–79
Operation Codes
11.12.31- MHLZO Operation (Move High Zone to Low Zone)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MHLZO Required Required Blank Blank Blank
Description
The Move High Zone to Low Zone operation moves the high zone in factor
2 to the low zone in the result field.
Rules
Factor 2 is required. It must contain an alphameric entry.
The result field is required. It can be an alphameric or numeric entry.
Operation
The MHLZO operation moves the zone from the leftmost position of the
entry in factor 2 to the rightmost position of the entry in the result field.
Example 11–40 MHLZO Operation Code Usage
1 2 3 4
1234567890123456789012345678901234567890123456789
C*
C MHLZOSNAKE PIT
In this example, the zone portion of the leftmost character in the SNAKE
field will be moved to the zone portion of the rightmost character in the
PIT field.
11–80
Operation Codes
11.12.32- MLHZO Operation (Move Low Zone to High Zone)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MLHZO Required Required Blank Blank Blank
Description
The Move Low Zone to High Zone operation moves the low zone of factor 2
to the high zone of the result field.
Rules
Factor 2 is required. It can be an alphameric or numeric entry.
The result field is required. It must contain an alphameric entry.
Operation
The MLHZO operation moves the zone from the rightmost position of the
entry in factor 2 to the leftmost position of the entry in the result field.
Example 11–41 MLHZO Operation Code Usage
1 2 3 4
1234567890123456789012345678901234567890123456789
C*
C MLHZOCAR WASH
In this example, the zone portion of the rightmost character in the CAR
field will be moved to the zone portion of the leftmost character in the
WASH field.
11–81
Operation Codes
11.12.33- MLLZO Operation (Move Low Zone to Low Zone)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MLLZO Required Required Blank Blank Blank
Description
The Move Low Zone to Low Zone operation moves the low zone of factor 2
to the low zone of the result field.
Rules
Factor 2 is required. It can contain an alphameric or numeric entry.
The result field is required. It can contain an alphameric or numeric entry.
Operation
The MLLZO operation moves the zone from the rightmost position of the
entry in factor 2 to the rightmost position of the entry in the result field.
Example 11–42 MLLZO Operation Code Usage
1 2 3 4
1234567890123456789012345678901234567890123456789
C*
C MLLZOLAWN MOWER
In this example, the zone portion of the rightmost character in the LAWN
field will be moved to the zone portion of the rightmost character in the
MOWER field.
11–82
Operation Codes
11.12.34- MOVE Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MOVE Required Required Blank Blank Blank
Description
The MOVE operation carries out a right-justified transfer of characters
from factor 2 to the result field.
Rules
Factor 2 is required. It can contain a literal, figurative constant, field,
array element, table element, or data structure element.
The result field is required. It can contain a field, array element, table
element, or data structure element. It cannot contain a literal.
Operation
The MOVE operation transfers data from factor 2 to the result field. It
can carry out the following types of transfers:
• Alphameric element to alphameric element.
• Alphameric element to numeric element.
• Numeric element to alphameric element.
• Numeric element to numeric element.
When transferring alphameric data to a numeric element, only the digit

portion of each character is transferred. If the rightmost character in
factor 2 is a J through R or {, the numeric field will be considered negative.
A MOVE operation transfers data from right to left. It begins with the
rightmost character in factor 2 and transfers it to the rightmost position
in the result field. If the result field is smaller than factor 2, the leftmost
characters of factor 2 will not be moved. If the result field is larger than
factor 2, the leftmost characters of the result field will be unaffected by the
move.
11–83
Operation Codes
Example 11–43 MOVE Operation Code Usage
1 2 3 4
1234567890123456789012345678901234567890123456789
C*
C MOVE PORTER HOUSE
In this example, the contents of the field PORTER are moved to the field
HOUSE. The table following the code example depicts the results of the
MOVE operation for different field sizes.
Table 11–1 Examples of MOVE Operation Results

Factor 2 Result Field
Field Field
Size Contents Size Contents Result of MOVE
4 ROCK 4 ROCK
7 ROLLER 4 LLER
7 CONCERT 8 LICORICE LCONCERT
6 179945 4 6457 9945
4 3098 8 11111111 11113098
11–84
Operation Codes
11.12.35- MOVEA Operation (Move Array)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MOVEA Required Required Blank Blank Blank
Description
The Move Array operation carries out a left-justified transfer of alphameric
data from factor 2 to the result field. It is used to transfer data in and out
of arrays.
Rules
array, array element, table element, or data structure element.
The result field is required. It can contain a field, array, array element,
table element, or data structure element. It cannot contain a literal.
Operation
The MOVEA operation is used to move several contiguous array elements
to a single field, move a single field to several contiguous array elements,
or move contiguous array elements from one array to another. Transfer of
data from factor 2 to the result field is carried out as follows:
• If a non-indexed array is specified in factor 2, transfer of data begins
with the leftmost character of the first element in the array.
• If an indexed array is specified in factor 2, transfer of data begins with
the leftmost character of the element specified by the index.
• If a data field is specified in factor 2, transfer begins with the leftmost
character of the field.
• If a non-indexed array is specified in the result field, placement of
transferred data begins with the leftmost character of the first element
in the array.
• If an indexed array is specified in the result field, placement of
transferred data begins with the leftmost character of the element
specified by the index.
• If a data field is specified in the result field, placement of the
transferred data begins with the leftmost character of the field.
11–85
Operation Codes
The number of characters transferred in a MOVEA operation is

determined by the shorter of the two elements specified in factor 2 and
the result field. Element lengths are determined as follows:
• If a non-indexed array is specified, the length of the entire array is
used as the field length.
• If an indexed array is specified, the length of the array from the
element specified by the index to the end of the array is used as the
field length.
• If a literal, field, table element, or data structure element is specified,
the length of the element is used. Literals cannot be specified in the
result field.
If the field length of factor 2 is greater than the field length of the result
field, the excess rightmost characters in factor 2 are not moved. If the field
length of the result field is greater than the field length of factor 2, the
rightmost characters in the result field remain unchanged.
Array element boundaries are ignored in a MOVEA operation. Therefore,
movement of data into the result field can end in the middle of an array
element.
All data transferred by a MOVEA operation is treated as alphameric data.
This means that numeric data is transferred without regard for the sign.
It is up to the programmer to ensure that the transfer of numeric data is
carried out properly.
If a figurative constant (*BLANK, *BLANKS, *ZERO, or *ZEROS) is
specified in factor 2 of a MOVEA operation and the result field contains an
array, the following actions are possible:
• If the array is non-indexed, the data transfer will begin with the
leftmost character of the first element of the array and the entire
array will be blank or zero-filled.
• If the array is indexed, the data transfer will begin with the leftmost
character of the array element specified by the index and the
remainder of the array will be blank or zero-filled. Array elements
to the left of the index will not be affected.
Figurative constants cannot be specified in the result field of a MOVEA

operation.
11–86
Operation Codes
Example 11–44 MOVEA Operation Code Usage - Setup
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
E ALPHA1 5 2
E ALPHA2 5 2
E NUM 5 3 0
.
.
.
C MOVE ’XXXX’ FLDA 4
C MOVE ’9999999’ FLDN 70
.
.
.
** ALPHA1 array elements
AABBCCDDEE
** ALPHA2 array elements
GGHHIIJJKK
** NUM array elements
111222333444555
The following examples depict the use and results of the MOVEA
operation. Example 11–44 shows the array and field definitions used
in the examples.
Example 11–45 MOVEA Operation Code Usage - Array to Array
(Alphameric)
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C MOVEAALPHA1 ALPHA2
In this example, the contents of the array ALPHA1 are moved to the array
ALPHA2.
Table 11–2 Results of MOVEA operation in Example 11–45

Contents of ALPHA2 Array
Before After
GGHHIIJJKK AABBCCDDEE
11–87
Operation Codes
Example 11–46 MOVEA Operation Code Usage - Array to Field

(Alphameric)
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C MOVEAALPHA2 FLDA
In this example, the contents of the array ALPHA2 are moved to the field
FLDA.

Contents of FLDA
Before After
XXXX GGHH
Example 11–47 MOVEA Operation Code Usage - Field to Array

(Numeric)
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C MOVEAFLDN NUM,3
In this example, the contents of FLDN are placed in the NUM array,
starting with the third element.

Contents of NUM Array
Before After
111222333444555 111222999999955
11–88
Operation Codes
11.12.36- MOVEL Operation (Move Left)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MOVEL Required Required Blank Blank Blank
Description
The Move Left operation transfers the contents of factor 2 to the result
field. The transfer begins with the leftmost character of factor 2 to the
leftmost character of the result field.
Rules
array element, table element, or data structure element.
The result field is required. It can contain a field, array element, table
element, or data structure element. It cannot contain a literal.
Operation
A MOVEL operation is essentially the opposite of a MOVE operation.
A MOVEL operation transfers characters in a left-justified fashion, as
opposed to the right-justified transfer carried out by a MOVE operation.
There are three basic types of MOVEL operations, each of which is based
on the lengths of the elements in factor 2 and the result field. These
MOVEL operations are summarized in the following paragraphs.
In a MOVEL operation where the field length of factor 2 is equal to the
field length of the result field, the following rules apply:
• If factor 2 and the result field are both alphameric fields, all characters
are transferred.
• If factor 2 and the result field are both numeric, all digits are
transferred and the sign of factor 2 becomes the sign of the result
field.
• If factor 2 contains numeric data and the result field is alphameric, all
characters are transferred. The result field will contain only numeric
characters; the sign is not used.
11–89
Operation Codes
• If factor 2 contains alphameric data and the result field is numeric,

only the digit portion of each character is transferred. If the rightmost
character of factor 2 is a J through R or {, the sign of the result field
will be negative.
In a MOVEL operation where the field length of factor 2 is longer than the
field length of the result field, the following rules apply:
• If factor 2 and the result field are both alphameric, only the number of
characters needed to fill the result field are transferred.
• If factor 2 and the result field are both numeric, only the number of
digits needed to fill the result field are transferred. The sign of factor
2 becomes the sign of the result field.
• If factor 2 contains numeric data and the result field is alphameric,
only the number of characters needed to fill the result field are
transferred. The result field will contain only numeric characters;
the sign of factor 2 is not used.
• If factor 2 contains alphameric data and the result field is numeric,
the digit portion of the leftmost characters of factor 2 are moved to
the result field. The zone portion of the rightmost character in factor
2 is used to determine the sign of the result field. If the rightmost
character of factor 2 is a J through R or {, the result field will be
considered negative.
In a MOVEL operation where the field length of factor 2 is shorter than

the field length of the result field, the following rules apply:
• If factor 2 contains either numeric or alphameric data and the result
field is numeric, the digit portion of each character in factor 2 is
transferred into the leftmost character positions of the result field.
The sign of the result field remains unchanged.
• If factor 2 contains either numeric or alphameric data and the
result field is alphameric, the data is transferred into the result
field beginning with the leftmost character position. The rightmost
character positions in the result field remain unchanged.
11–90
Operation Codes
Example 11–48 MOVEL Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C MOVE ’HOTSPOT’ SUN 7
.
.
.
C MOVEL’ICE’ SUN
C MOVE ’CUBE’ SUN
This example depicts the use of the MOVEL operation code. The field
SUN (a 7-character alphameric field) is defined and initialized in the
Calculation specifications by a MOVE operation. It is initialized with the
value ’HOTSPOT’. Later in the program, the value of the field SUN
is changed by a MOVEL and a MOVE operation. After the MOVEL
operation, the contents of the field SUN will be ’ICESPOT’. The MOVEL
operation replaces the leftmost three characters of the field SUN with
the literal ’ICE’. After the MOVE operation, the field SUN will contain
’ICECUBE’. The MOVE operation replaces the rightmost four characters
of the SUN field with the literal ’CUBE’.
11–91
Operation Codes
11.12.37- MULT Operation (Multiplication)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional MULT Required Required Opt Opt Opt
Description
The Multiply operation allows two numeric elements to be multiplied
together, with the product being placed in the result field.
Rules
All elements specified in a MULT operation must be numeric.
Factor 1 is optional. If present, factor 1 is multiplied by factor 2 and the
product is placed in the result field.
Factor 2 is required. If factor 1 is not present, the result field is multiplied
by factor 2 and the product is placed in the result field.
The contents of factor 1 and factor 2 are not affected by a MULT operation.
after the MULT operation.
Operation
11–92
Operation Codes
Example 11–49 MULT Operation Code Usage - 2 Operands
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C FLD1 MULT 2 FLD2
In this example, FLD1 is multiplied by the constant 2 and the result is

placed in FLD2. If the contents of FLD1 are 10, the result in FLD2 will be
20.
Example 11–50 MULT Operation Code Usage - 1 Operand
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C MULT 2 CNT
In this example, the field CNT is multiplied by the constant 2 and the
result is placed in CNT. If the contents of CNT are 5 at the beginning of
the operation, they will be 10 when the operation is completed.
Example 11–51 MULT Operation Code Usage - Indicator Controlled
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C 10 CASH MULT PERCNT INTRST
In this example, the MULT operation is only carried out if indicator 10 is

on. If processed, the operation will multiply the field CASH by the field
PERCNT, placing the result in INTRST.
11–93
Operation Codes
11.12.38- MVR Operation (Move Remainder)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank MVR Blank Required Opt Opt Opt
Description
The Move Remainder operation moves the remainder from the Divide
operation (DIV) on the preceding line to the result field.
Rules
The MVR operation must immediately follow a DIV operation.
The result field is required. It must contain a numeric entry which will
accept the remainder from the previous DIV operation.
after the MVR operation.
Operation
The MVR operation captures the remainder of the previous DIV operation.
The MVR operation must immediately follow a DIV operation.
The number of significant decimal positions of the remainder is the greater
of either of the following:
1 The number of decimal positions specified for factor 1 in the associated
DIV operation.
2 The sum of the number of decimal positions specified for factor 2 and
the result field of the associated DIV operation.
The number of significant whole number positions in the remainder is

equal to the number of whole number positions in factor 2 of the associated
DIV operation.
The sign of the remainder is the same as the sign of factor 1 in the DIV
operation.
Because DIV and MVR operation codes work together, it is recommended
that the same conditional indicators be used on both operations.
11–94
Operation Codes
Half adjust (column 53 of the Calculation specification) cannot be specified

for a DIV operation immediately followed by an MVR operation.
Example 11–52 MVR Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C PRINC DIV MONTH PAYMNT 50
C MVR RESIDL 50
In this example, the field PRINC will be divided by MONTH, with the
result being placed in PAYMNT. Any remainder from this DIV operation
will be placed in the field RESIDL by the MVR operation. If PRINC
contains 511 and MONTH contains 12, the result of the DIV operation will
be 42, which will be placed in the field PAYMNT. The MVR operation will
move the remainder of 7 into the field RESIDL.
11–95
Operation Codes
11.12.39- ORxx Operation (Complex Conditional Operation)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blk Required ORxx Required Blank Blk Blk Blk
Description
The ORxx operation allows a more complex conditional operation to be
specified in DOUxx (Do Until), DOWxx (Do While), and IFxx operations.
Fields specified in the ORxx operation are compared and return a true
or false condition to the program. The true/false condition is used by
the program to determine if the structured construct of which the ORxx
operation is a part should be executed or bypassed.
Rules
The ORxx operation can be used in conjunction with the DOUxx, DOWxx,
IFxx, and ANDxx operations.
Control level entries (columns 7 - 8) for the ORxx operation must be
consistent with the control level entry for the associated DOUxx, DOWxx,
or IFxx operation.
The comparison carried out in an ORxx operation follows standard RPG
Section 11.4.
Resulting indicators are not allowed.
11–96
Operation Codes
The xx portion of the ORxx operation can be one of the following

instructions:
factor 2.
equal to factor 2.

Example 11–53 ORxx Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C JUGGLE DOWGT3
C BALLS OREQ PINS
.
.
.
C END
In this example, the Do While loop will continue to execute as long as the
field JUGGLE is greater than 3 or the field BALLS equals the field PINS.
11–97
Operation Codes
11.12.40- PARM Operation (RPG Subprogram Parameter Definition)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blk Optional PARM Optional Required Blank Blank Blank
Description
The PARM operation is used to exchange parameters with an RPG
subprogram.
Rules
The PARM operation code is used to define parameters which will make
up a parameter list to be passed to an RPG subprogram. The PARM
operation code is used with the CALL and PLIST operation codes. PARM
statements can appear anywhere in the Calculation specifications as long
as they immediately follow a CALL or PLIST statement. Up to 99,999
PARM statements can follow a CALL or PLIST statement.
Conditional indicator entries (columns 9 - 17) and resulting indicator
entries (columns 54 - 59) are not permitted.
Factors 1 and 2 are optional in a PARM statement. If specified, they must
have the same data type, alpha or numeric, as the result field. A literal or
figurative constant cannot be specified in factor 1.
The result field must contain a field, data structure, array, or array
element name. *ENTRY PLIST parameters cannot specify array elements
using fields as subscripts. The result field cannot contain a literal or table
name. *IN, *INxx, and *IN,xx entries are legal PARM fields, but should
be specified with caution as their settings reflect indicator settings. The
length and decimal position columns (49 - 52) can be used to define the
result field.
The field specified in the result field of a PARM statement is passed by
descriptor to the RPG subprogram. The field can be manipulated and
updated by the subprogram. The subprogram then returns the updated
value to the calling program. If an RPG subprogram terminates with an
error, any changes made to the fields specified in the PARM statements
are still returned to the calling program. To preserve a field from changes
when using it as a parameter, specify the field name in factor 2 of the
PARM statement and declare a temporary field name in the result
field. The contents of factor 2 will be copied to the result field when
the subprogram is called and the contents of the field in factor 2 will
remain unaffected.
11–98
Operation Codes
When a Migration RPG subprogram is called by a Migration RPG program,

the following steps occur:
1 In the calling program, the contents of factor 2, if specified, are copied
to the result field. Numeric fields are moved using a Z-ADD operation.
Alphameric fields are moved using a MOVE operation.
2 In the subprogram, after any program startup and initialization
processing has run, the contents of the result fields in the *ENTRY
PLIST parameters are copied to factor 1, if factor 1 is specified.
Numeric fields are moved using a Z-ADD operation. Alphameric
fields are right-justified and blank-filled. Errors and warnings will be
logged if the parameter descriptors being passed to the called program
do not match the field types and sizes specified in the *ENTRY PLIST.
3 When the subprogram returns control to the calling program, the
contents of factor 2 in each *ENTRY PLIST parameter, if specified, are
copied to the result field. Numeric fields are moved using a Z-ADD
operation. Alphameric fields are moved using a MOVE operation. The
result field descriptors are passed back to the calling program.
4 Upon return to the calling program, the contents of the result fields
are copied to factor 1, if factor 1 was specified. Numeric fields are
moved using a Z-ADD operation. Alphameric fields are moved using a
MOVE operation.
Parameter fields are passed as fixed-length descriptors. The structure of

these descriptors is shown in the following figure.
Figure 11–1 Fixed-Length Descriptor Format
31 23 15 0
1 DTYPE LENGTH
POINTER
Migration RPG understands and uses five descriptor types.
Table 11–5 Descriptor Types and Use

Descriptor type Used to represent...
DSC$K_DTYPE_T Alphameric fields, data structures, arrays
DSC$K_DTYPE_NZ Zoned-decimal fields
DSC$K_DTYPE_P Packed fields
DSC$K_DTYPE_W 2-byte binary fields
DSC$K_DTYPE_L 4-byte binary fields
When building packed and binary field descriptors in non-Migration RPG

programs, specify the actual packed or binary field length in the parameter
11–99
Operation Codes
descriptor. Do not specify the unpacked or expanded binary field length

of the field. Migration RPG will only accept binary fields 2 and 4 bytes in
length.
Fields in a Migration RPG program default to the following descriptor
types when passed as parameters in a PARM statement.
Table 11–6 Default Descriptor Types

Element type Definition Description Type
Array Alphameric Alphameric DSC$K_DTYPE_T
Numeric: Zoned-decimal, trailing Alphameric DSC$K_DTYPE_T
numeric, packed, binary
Array Element Alphameric Alphameric DSC$K_DTYPE_T
Numeric: Zoned-decimal, trailing Zoned-decimal DSC$K_DTYPE_NZ
numeric, packed, binary Trailing Numeric DSC$K_DTYPE_NZ
Input Field Col 43: blank; Col 52: blank Alphameric DSC$K_DTYPE_T
Col 43: blank; Col 52: 0 - 9 Zoned-decimal DSC$K_DTYPE_NZ
Col 43: P Col 52: 0 - 9 Trailing numeric DSC$K_DTYPE_NZ
Col 43: B Col 52: 0 - 9 Packed decimal DSC$K_DTYPE_P
Col 43: B Col 52: 0 - 9 Binary, 2 byte DSC$K_DTYPE_W
Binary, 4 byte DSC$K_DTYPE_L
Data Struct. Alphameric Alphameric DSC$K_DTYPE_T
DS Subfield Col 43: blank; Col 52: blank Alphameric DSC$K_DTYPE_T
Col 43: blank; Col 52: 0 - 9 Zoned-decimal DSC$K_DTYPE_NZ
Trailing numeric DSC$K_DTYPE_NZ
Calc field Col 52: blank Alphameric DSC$K_DTYPE_T
Col 52: 0 - 9 Zoned-decimal DSC$K_DTYPE_NZ
When using the PARM operation to pass parameters to a Migration

RPG program from a program written in another language, fixed-length
descriptors and one of the above descriptor types must be used. If the
incoming parameter is not a fixed-length descriptor and does not use one
of these descriptor types, the Migration RPG program will issue an error
message and abort.
When passing parameters between Migration RPG programs, the
parameter list passed by the calling program and the parameter list
specified in the subprogram’s *ENTRY PLIST must match data types and
should match sizes. Thus, if the first parameter passed to a program is
a 5-byte, packed-decimal field, the first parameter in the subprogram’s
*ENTRY PLIST should be a 5-byte, packed-decimal field.
It is always best to have the called program’s *ENTRY PLIST match the
data types, sizes, and number of parameters in the RPG subprogram’s
parameter list. However, the following exceptions apply when passing
parameters between Migration RPG programs:
• Parameters of the same data type, but different lengths, will generate
a warning message, but will be accepted by the subprogram. The
11–100
Operation Codes
warning message can be suppressed by compiling the subprogram

using the /NOWARNING qualifier.
• A parameter defined as alphameric in one parameter list and zoned-
decimal or trailing numeric in the other will be passed without error.
• If the calling program passes more parameters than the subprogram
is prepared to accept, a warning message will be issued and the extra
parameters will be ignored. The warning message can be suppressed
by compiling the called program using the /NOWARNING qualifier. If
the calling program passes too few parameters, the subprogram will
log an error message and return to the calling program with an error
status set.
When passing parameters between Migration RPG programs, descriptor

creation, transfer, and checking is handled automatically by the Migration
RPG runtime routines.
Example 11–54 CALL and PARM Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C* The following example illustrates the use of the
C* PARM statement with the CALL operation code.
C*
C* The first parameter passes the contents of the
C* field TAP to the called program and returns any
C* modifications to the field TAP when the called
C* program exits.
C*
C* The second parameter copies the contents of the
C* field FOX to the field TROT before passing the
C* contents of TROT to the call program. Since TROT
C* is defined as a 10-byte, alpha field, it will be
C* moved using a MOVE operation. When the called
C* program exits, TROT will contain the updated data.
C*
C* The third parameter passes the contents of the
C* field CHARLE to the called program. When the
C* called program exits, the updated contents of
C* CHARLE will be copied to STON.
C*
C* The fourth parameter copies the contents of the
C* field ROCK to the field AND when a program is
C* called. Since AND is defined as a 7-byte, numeric
C* field, the copy is carried out using a Z-ADD
C* operation. When the called program exits, the
C* updated data in AND is Z-ADDed to the field ROLL.
C*
C CALL ’DANCE’
C PARM TAP
C PARM FOX TROT 10
C STON PARM CHARLE
C ROLL PARM ROCK AND 70
11–101
Operation Codes
11.12.41- PLIST Operation (RPG Subprogram Parameter List)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blk Required PLIST Blank Blank Blank Blank Blank
Description
The PLIST operation defines a unique symbolic name for a list of
parameters that is used in a CALL operation.
Rules
A PLIST operation can be specified anywhere within the Calculation
specifications, including total time calculations and between subroutines.
A PLIST entry consists of a PLIST statement followed by one or more
PARM statements which define a list of parameters that is to be passed
to or received by a subprogram. A parameter listed is ended when an
operation other than a PARM is encountered.
Indicator entries in columns 7 - 8 are optional.
Indicator entries in columns 9 - 17 are not allowed.
Factor 1 is required. It must contain the name of the PLIST. A PLIST
name can be one to six characters in length and must be unique. If
the parameter list being defined is the entry parameter list for an RPG
subprogram, factor 1 must contain *ENTRY. Only one *ENTRY PLIST can
be defined in a program.
Operation
The elements in a parameter list supplied by a calling program and the
elements in a parameter list defined by a *ENTRY PLIST in an RPG
subprogram should match in size and data type.
11–102
Operation Codes
Example 11–55 PLIST and *ENTRY PLIST Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C* The *ENTRY PLIST is set up to accept and return
C* three parameters from a calling program. The
C* PLIST labeled FARM has three parameters assigned
C* to it. A CALL statement in this program could
C* reference the PLIST FARM and pass the FARM
C* parameter list to another program.
C*
C *ENTRY PLIST
C PARM COWS
C PARM HOGS
C PARM CHICKN
C*
C FARM PLIST
C PARM TRACTR
C PARM COMBIN
C PARM PICKUP
11–103
Operation Codes
11.12.42- READ Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank READ Required Blank Blank Opt Opt
Description
The READ operation calls for a record to be read immediately from a
demand or full-procedural file. The READ operation differs from the
FORCE operation in that the FORCE operation specifies a read from a file
on the next cycle.
Rules
Factor 2 is required. It must contain the name of the demand or full-
procedural file the READ operation is to access. The file name specified
in factor 2 must match a file name specified in columns 7 - 14 of the File
Description specifications.
The resulting indicator in columns 54 - 55 (high) must be blank. The
resulting indicator in columns 56 - 57 (low) is optional and can be used
as an exception indicator on reads to WORKSTN devices and an error
indicator on reads to data files. The resulting indicator in columns 58 - 59
(equal) is optional and indicates an end-of-file condition.
Operation
A READ operation can only be specified for a demand or full-procedural
file. These files have a D or F specified in column 16 of the File Description
specification.
A READ operation can be carried out against the following types of input
and update files:
• Sequential files processed consecutively.
• Sequential files processed randomly and consecutively.
• Relative files processed consecutively.
• Relative files processed randomly and consecutively.
• Indexed files processed sequentially by key.
• Indexed files processed sequentially by limits.
• Indexed files processed randomly and consecutively.
11–104
Operation Codes
• WORKSTN files.
• SPECIAL device files.
A resulting indicator specified in columns 58 - 59 (equal) serves as an

end-of-file indicator. The following rules apply to this indicator:
• It is required on READ operations to full-procedural files.
• The indicator turns on when end-of-file is reached and for each READ
to a file which is already at end-of-file.
• On a read to a demand file, the indicator is not turned off before the
READ operation is performed.
• On a read to a full-procedural file, the indicator is turned off before the
READ operation is performed.
• If the indicator is blank and no error indicator is present, a halt occurs
when an end-of-file condition is processed during a READ operation.
The user will be prompted to continue or terminate the program.
A resulting indicator in columns 56 - 57 is optional. If it is specified on a

READ operation to a data file, it serves as an error indicator, turning on if
the record requested by the READ operation cannot be accessed.
If a resulting indicator is specified in columns 56 - 57 (low) of a READ
operation to a WORKSTN file, it is called an exception indicator. The
following rules apply to the use of this indicator:
• If the indicator is specified, it will turn on if an exception condition
is processed. An exception condition occurs when the user enters a
function key at the workstation device. Function keys consist of the
Roll Up , Roll Down , Clear , Print , Home , and Help functions.
• If the indicator is not specified and an exception occurs, a halt will

be issued and the user will be given the opportunity to continue
or terminate the program unless an INFSR exception handling
subroutine has been defined. INFSR subroutines are discussed in
the Migration RPG Screen Format Reference Manual.
If a READ operation is successful, the record-identification indicators

associated with the record read remain on for the rest of the cycle. Other
record-identification indicators are not affected.
11–105
Operation Codes
Example 11–56 READ Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FJAZZ ID F 80 80 DISK
.
.
.
C READ JAZZ 99
.
.
.
In this example, a READ operation is being carried out against the

sequential file JAZZ. If the READ operation encounters an end-of-file
condition, indicator 99 will be turned on.
11–106
Operation Codes
11.12.43- READE Operation (Read Equal Key)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required READE Required Blank Blank Opt Req
Description
The Read Equal Key operation retrieves the next sequential record from
an indexed, full-procedural file if the key matches the entry in factor 1.
Rules
Factor 1 is required. It can contain a literal, field, array or table element,
or data structure element. The entry must have the same field type and
length as the key field of the file being read.
Factor 2 is required. It must contain the name of the file being read. The
file must be a full-procedural, indexed file and the name must match a
name specified in columns 7 - 14 of the File Description specifications.
A resulting indicator in columns 54 - 55 is not permitted. A resulting
indicator in columns 56 - 57 is optional and serves as an error indicator. A
resulting indicator in columns 58 - 59 (equal) is required and serves as a
record-not-found indicator.
Operation
The READE operation will read the next sequential record from an
indexed, full-procedural file if the key in the record matches the key
specified in factor 1. A full-procedural file is identified by an F in column
16 of the File Description specification. A CHAIN or SETLL operation
must occur before a READE operation to position the record pointer within
the file. If a READE operation fails, another SETLL or CHAIN operation
must be carried out to reposition the record pointer or all subsequent
READ, READE, and READP operations will fail.
A resulting indicator in columns 56 - 57 is optional. If specified, it serves
as an error indicator, turning on if the record requested by the READE
operation cannot be accessed. If this indicator is turned on, the record-not-
found indicator will also be turned on.
11–107
Operation Codes
The resulting indicator in columns 58 - 59 must be specified. It will be

turned off when processing of the READE operation begins. It will turn
on if the key in factor 1 does not match the record read or if an end-of-
file condition occurs. If the indicator comes on, no record is read by the
program.
If a READE operation is successful, the record-identification indicators
Example 11–57 READE Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FROCK IF F 120R 5AI 1 DISK
.
.
.
C KEY CHAINROCK 99
C LOOP TAG
C N99 KEY READEROCK 99
.
.
.
C N99 GOTO LOOP
.
.
.
In this example, the READE operation is used to read all records with a
key equal to the record located by the CHAIN operation. Note the use of
indicator 99 to indicate a record-not-found condition.
11–108
Operation Codes
11.12.44- READP Operation (Read Prior)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank READP Required Blank Blank Opt Req
Description
The Read Prior operation retrieves the previous sequential record from a
full-procedural file.
Rules
Factor 2 is required. It must contain the name of the file being read. The
file must be a full-procedural file and the name must match the name
specified in columns 7 - 14 of the File Description specification.
A resulting indicator in columns 54 - 55 is not permitted. A resulting
indicator in columns 56 - 57 (low) is optional and serves as an error
indicator. A resulting indicator in columns 58 - 59 (equal) is optional and
serves as a beginning-of-file indicator.
Operation
The READP operation will read the previous sequential record from a
full-procedural file. A full-procedural file is identified by an F in column
16 of the File Description specification. The READP operation can be used
against the following types of full-procedural files:
• A fixed-length sequential file.
• A relative file.
• An indexed file with both ascending and descending key definitions.
The resulting indicators specified in columns 56 - 59 will be turned off

when processing of the READP operation begins. The resulting indicator
in columns 58 - 59 will turn on if the beginning of the file is reached
(beginning-of-file condition). If a record is present but cannot be be
accessed, the error indicator in columns 56 - 57 will be turned on. The
$STAT$ field can be checked to determine the return status of the READP
operation. If a READP operation fails, a SETLL or CHAIN operation
must be executed to reposition the record pointer or all subsequent READ,
READE, and READP operations will fail.
11–109
Operation Codes
If a READP operation is successful, the record-identification indicators
Indexed files require some special preparation before they can be accessed
with the READP operation. Key fields within an indexed file must be
defined as both ascending and descending keys for the READP operation
to function correctly. For example, the primary key (Key 0) of an indexed
file is defined as an ascending key starting in offset 0 with a length of 6.
To access this file using the primary key with a READP operation, the first
secondary key (Key 1) in the file would need to be defined as a descending
key starting in offset 0 with a length of 6.
The rule of thumb for defining keys in an indexed file which is accessed
using the READP operation is that each key defined in the File
Description specifications must have an associated key defined as the next
secondary key in the file. Thus, if key 2 is defined in the File Description
specification, key 3 will be the key accessed by the READP operation.
Creating indexed file definitions for files which are to be accessed using
the READP operation is covered in more detail in the Migration RPG
User’s Guide. Creating indexed file definitions is covered in the OpenVMS
File Definition Language Facility Manual.
Example 11–58 READP Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FMINE UF F 120 DISK
.
.
.
C READ MINE 98
.
.
.
C READPMINE 99
.
.
.
This example depicts the use of the READ and READP operation codes
to extract records from the file MINE. The READ operation will read the
next sequential record in the file. If an end-of-file condition is returned by
the READ operation, indicator 98 will be turned on. The READP operation
will read the previous sequential record in the file. If a beginning-of-file
condition is returned, indicator 99 will be turned on.
11–110
Operation Codes
11.12.45- RETRN Operation (Return From an RPG Subprogram)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank RETRN Blank Blank Blank Blank Blank
Description
The RETRN operation causes an RPG subprogram to return to the calling
program. The RETRN operation is associated with the CALL operation.
Rules
Operation
The RETRN operation is similar in function to the ENDSR (end
subroutine) statement. It tells an RPG subprogram to exit immediately
and return control to the calling program. When a RETRN statement is
processed, the follow steps occur:
1 The halt indicators (H1 - H9) are checked. If a halt indicator is on, the
program ends abnormally, closing all data files, and returning an error
status. If warning messages are enabled, a warning is issued to the
user’s terminal when the subprogram returns.
2 If no halt indicators are on, the LR (last record) indicator is checked.
If LR is on, the subprogram ends normally, shutting down file streams
and deactivating the subprogram.
3 If neither the halt or LR indicators are on, the subprogram returns
control to the calling program. Data and indicator settings in the
subprogram are preserved.
Whether the subprogram exits normally, abnormally, or simply returns,

any parameters passed to the subprogram are returned to the calling
program. If a subprogram returns without ending, the next time it is
called, it will resume operations with the field and indicator settings which
were present when it returned. A subprogram can be reinitialized using
the FREE operation. Subprograms which end normally or abnormally are
automatically reinitialized the next time they are called.
11–111
Operation Codes
Example 11–59 RETRN Operation code Use
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C* This subprogram is called by another, passing the
C* parameters PHASER and PHOTON. After manipulation
C* of these fields, it returns to the calling program
C* without ending. Any values or indicator settings
C* established each time this subprogram is run are
C* retained as long as the calling program does not
C* run a FREE operation against it.
C*
C *ENTRY PLIST
C PARM PHASER
C PARM PHOTON
*
C PHASER ADD ENERGY PHASER
C PHOTON ADD ENERGY PHOTON
*
C RETRN
11–112
Operation Codes
11.12.46- RLABL Operation (EXIT Operation Parameter Definition)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Blk Blk Blank RLABL Blank Required Blank Blank Blank
Description
The RLABL allows parameters which are to be passed to an external
subroutine called by an EXIT operation to be defined. The RLABL
operation is maintained for compatibility with non-Digital versions of the
RPG programming language and to pass parameters to the MSI-supplied
subroutines SUBR01, SUBR21, and SUBR23. The CALL operation and
its associated instructions are recommended for calling external routines
using Migration RPG.
Rules
The result field is required. It must contain the name of the field, array,
table, or data structure element that is being passed to the external
subroutine.
11–113
Operation Codes
Example 11–60 RLABL Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
IDS DS
I 7 56 DATAST
I 17 56 DATA
I 75 820MIC
*
C MOVE NUM MIC
C MOVE 1 LEVEL 10
*
C EXIT SUBR23
C RLABL MIC
C RLABL DATAST
C RLABL LEVEL
C RLABL RCODE 10
In this example, the RLABL operation is used to pass parameters to the

MSI-supplied subroutine SUBR23. The RLABL operation is being used to
pass the numeric fields MIC, LEVEL, and RCODE, and the alphameric
field DATAST.
11–114
Operation Codes
11.12.47- SETnn Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional SETnn Blank Blank Opt Opt Opt
Description
The SETnn operation allows information to be displayed on the user’s
screen and can enable command keys for user input. The SETnn operation
is often used in conjunction with the KEYnn operation.
Rules
The SETnn operation can only be used if a KEYBORD file has been
defined in the File Description specifications. KEYBORD must be defined
as the device type in columns 40 - 46 of the File Description specification.
Factor 1 is optional. It can be a literal or data field which will be displayed
on the user’s screen when the SETnn operation is processed.
The nn portion of the SETnn operation code can be blank or can specify
a message member number from the User Level 1 message member file
(RPGUSRLV1). If the message member corresponding to the message
number in the SETnn operation code is found, the message is displayed.
If the message member file is not present or no entry exists which
corresponds to the message number specified, nothing is displayed. If
an entry is made in factor 1 of the SETnn operation, the message number
is ignored. If no entry is made in factor 1, the message number is required.
See the Migration RPG User’s Guide for more information on creating and
referencing message member files.
Resulting indicators (columns 54 - 59) are optional. If specified, they must
contain the command key indicators KA - KN and KP - KY.
11–115
Operation Codes
Operation
The SETnn operation can be used to display data and define command
keys. The following actions can occur when the SETnn operation is
executed:
• If factor 1 is present, its contents are displayed to the user’s screen.
• If factor 1 is not present, the message member defined by the nn
portion of the SETnn operation will be displayed from the User Level
1 message member file (RPGUSRLV1), if it is found.
• If no command key indicators are defined in a SETnn operation, the
program continues without stopping for user input. SETnn operations
which do not specify command key indicators can be used to create a
running display of data.
• If command key indicators (KA - KN, KP - KY) are defined in the
resulting indicator columns, the SETnn operation stops the program
and waits for user input. It will allow the user to enter the defined
command keys from the terminal. If a command key is entered, its
corresponding indicator is turned on. If the command key is entered
again during the same SETnn operation, its corresponding indicator is
turned off. Any command key indicators defined in a SETnn operation
are turned off when the SETnn operation begins execution.
• If a SETnn operation with command keys stops a program, entering a
command key does not restart the program. The user must press the
Return , Enter , or PF4 key to continue the program.
11–116
Operation Codes
Example 11–61 SETnn Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FUSERIN IP F 70 70 KEYBORD
E PRMPT 1 5 40
.
.
.
C ’WAKE UP!’SET
C PRMPT,1 SET
C SET23 KA
.
.
.
**
USER DATA ENTRY REQUIRED
In this example, the SETnn operation code is used to display information

to the user’s terminal. It then pauses the program and awaits user input
before continuing. Note the File Description specification which describes
a KEYBORD file. A KEYBORD file must be defined to use the SETnn
operation. This example also contains an Extension specification which
describes the array PRMPT.
The first SETnn operation displays the literal ’WAKE UP!’ to the user’s
screen. The second SETnn operation displays the first element in the
PROMPT array, ’USER DATA ENTRY REQUIRED’, to the user’s screen.
The third SETnn operation will display message 23 from the User Level 1
Message File. The third SETnn operation will also pause the program and
wait for input from the user. The user can simply press Enter to continue,
or can have the option of entering Command Key 1 ( PF1 + 1 ), which will
turn on indicator KA. The user will still need to press the Enter key to
terminate the SETnn operation.
11–117
Operation Codes
11.12.48- SETLL Operation (Set Lower Limit)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Required SETLL Required Blank Blank Blank Blank
Description
The Set Lower Limit operation positions the record pointer within a file at
the record with a key that is greater than or equal to the key specified in
factor 1.
Rules
The SETLL operation can only be performed against full-procedural and
demand indexed files that are being processed sequentially within limits.
The File Description specification for the SETLL file must have an F or D
in column 16 and an L in column 28.
Factor 1 is required. It can contain a literal, field, array or table element,
or data structure element. The entry must have the same field type and
Factor 2 is required. It must contain the name of the file being read.
The file must be a full-procedural or demand indexed file being processed
within limits. The file name must match the name specified in columns
7 - 14 of the File Description specification.
Operation
When a SETLL operation is performed, the file record pointer is set at the
record with the key that is greater than or equal to the key specified in
factor 1. Subsequent READ, READE, and READP operations will begin
from that point.
If the program issues a READ operation before issuing a SETLL operation,
processing begins with the first record in the file.
When end-of-file is reached on a limits file, another SETLL operation can
be used to reposition the record pointer in the file.
11–118
Operation Codes
A record-address file and the SETLL operation cannot be used with the
same data file.
Example 11–62 SETLL Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
0001 H
0002 FCUSTMSTRIF F 132L 5AI 1 DISK
0003 FINPUT CD F 32 WORKSTN
.
.
.
0009 ICUSTMSTRAA 01
0010 I 1 5 KEY
0011 I 6 20 LSTNAM
0012 I 21 35 FSTNAM
0013 *
0014 IINPUT BB 02
0015 I 1 5 KEY
.
.
.
0044 C READ INPUT 90
0045 C N90 KEY SETLLCUSTMSTR
0046 C N90 READ CUSTMSTR 90
In this example, the SETLL operation is used to position a pointer in the

CUSTMSTR file based on a customer key. The user enters a key value
via a workstation into the INPUT record. The value is placed in the field
KEY. The field KEY is used by the SETLL operation to position the file
pointer for the subsequent READ operation. Note that SETLL and READ
operations for the CUSTMSTR file are conditioned by indicator 90. If the
workstation read processes an exception, indicator 90 will be turned on
and the following SETLL and READ operations will not be performed.
11–119
Operation Codes
11.12.49- SETOF Operation (Set Indicator[s] Off)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank SETOF Blank Blank One required
Description
The Set Indicators Off operation will set one to three indicators off.
Rules
At least one resulting indicator must be specified in columns 54 - 59.
Operation
The SETOF operation will set all of the indicators specified in the resulting
indicator columns off (to 0).
Example 11–63 SETOF Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C SETOF 101112
C SETOF 20
In this example, the SETOF instruction is used to turn off indicators 10,
11, 12, and 20.
11–120
Operation Codes
11.12.50- SETON Operation (Set Indicator[s] On)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank SETON Blank Blank One required
Description
The Set Indicators On operation will set one to three indicators on.
Rules
At least one resulting indicator must be specified in columns 54 - 59.
Operation
The SETON operation will set all of the indicators specified in the
resulting indicator columns on (to 1).
Example 11–64 SETON Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C SETON 304050
C SETON 6070
In this example, the SETON instruction is used to turn on indicators 30,

40, 50, 60, and 70.
11–121
Operation Codes
11.12.51- SORTA Operation (Sort Array)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank SORTA Required Blank Blank Blank Blank
Description
The Sort Array operation allows the elements in an array to be sequenced.
Rules
Factor 2 is required. It must contain the name of an array.
Operation
The SORTA operation sequences the elements in an array. It is commonly
used to ensure that the elements of an array are properly sequenced before
a LOKUP operation is performed.
If the array sequence has been defined in columns 45 or 57 of the
Extension specification, the array is sorted accordingly. If no sequence
has been defined, the array will be sorted in an ascending sequence. All
SORTA operations use a standard ASCII collating sequence. Alternating
collating sequences are ignored.
Only the array specified is sorted.
11–122
Operation Codes
Example 11–65 SORTA Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FINPUT IP F 80 80 DISK
*
E LUFF 10 10
*
IINPUT NS 01
I 1 100 LUFF
*
C SORTALUFF
In this example, the array LUFF is loaded from an input record and then
sorted into ascending order.
11–123
Operation Codes
11.12.52- SQRT Operation (Square Root)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank SQRT Required Required Blank Blank Blank
Description
The Square Root operation calculates the square root of the value specified
in factor 2.
Rules
Factor 2 is required. It must contain a numeric entry. It can contain the
name of a numeric array if the result field also contains a numeric array.
The result field is required. It must contain a numeric entry.
Operation
The SQRT operation calculates the square root of the entry in factor
2, placing the product in the result field. The SQRT operation always
produces a positive result. If the value specified in factor 2 is negative, its
sign is changed before the square root calculation takes place.
It is recommended that the result field have at least half as many decimal
places as factor 2. Results of a SQRT operation are always half-adjusted.
Example 11–66 SQRT Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C SQRT NUM CHUCK
In this example, the SQRT operation calculates the square root of the
contents of NUM and places the result in CHUCK.
11–124
Operation Codes
11.12.53- SUB Operation (Subtraction)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Optional SUB Required Required Opt Opt Opt
Description
The Subtract operation subtracts factor 2 from factor 1, placing the
difference in the result field.
Rules
All fields specified in an SUB operation must be numeric.
Factor 1 is optional. If present, factor 2 is subtracted from factor 1 and the
difference is placed in the result field.
Factor 2 is required. If factor 1 is not present, factor 2 is subtracted from
the result field and the product is placed in the result field.
The contents of factor 1 and factor 2 are not affected by a SUB operation.
after the SUB operation.
Operation
11–125
Operation Codes
Example 11–67 SUB Operation Code Usage - 2 operands
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C FLD1 SUB 1 FLD2
In this example, the constant 1 is subtracted from FLD1 and the result is
placed in FLD2.
Example 11–68 SUB Operation Code Usage - 1 operand
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C SUB 1 CNT
In this example, the constant 1 is subtracted from the field CNT and the
result is placed in CNT.
Example 11–69 SUB Operation Code Usage - Indicator controlled
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C 10 PAY SUB TAXES PITANC
In this example, the SUB operation is only carried out if indicator 10 is

on. If processed, the operation will subtract the field TAXES from the field
PAY, placing the result in PITANC.
11–126
Operation Codes
11.12.54- TAG Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blnk Required TAG Blank Blank Blank Blank Blank
Description
The TAG operation defines a label to which a GOTO or CABxx operation
can branch.
Rules
Conditional indicators in columns 9 - 17 are not permitted.
Factor 1 is required. It must contain the label which defines the branch
destination of a GOTO or CABxx operation. A label can be 1 - 6 characters
long and must begin with an alpha character. Each TAG label name must
be unique.
Example 11–70 TAG Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C LOOPY TAG
This example depicts the use of the TAG operation to define the label
LOOPY.
11–127
Operation Codes
11.12.55- TESTB Operation (Test Bit)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank TESTB Required Required One required
Description
The Test Bit operation compares the bits specified in factor 2 to the
corresponding bits in the result field.
Rules
Factor 2 can contain a literal bit mask or a single-character field which
contains the bit mask used by the TESTB operation. A literal bit mask
identifies the bits as 0 through 7, with 0 as the leftmost bit. The bit mask
must be enclosed in single quotes. For example, to test bits 0, 5, and 6,
enter ’056’ in factor 2. A bit number cannot be specified more than once
in a mask.
alphameric field, table, or array element. The bits that are on in factor 2
are tested in the result field. If an array element is specified, each element
in the array must be a single-character field. If factor 2 is not a single
character field or literal bit mask, a compilation error will occur.
character alphameric fields. The bits specified in factor 2 will be tested in
the result field.
At least one resulting indicator (columns 54 - 59) must be specified.
Operation
The TESTB operation tests the bits in the result field which are specified
as on in factor 2.
At least one resulting indicator must be specified. All three resulting
indicators can be used. The indicators are turned on by the TESTB
operation as follows:
• High - Columns 54 - 55
This indicator turns on if each bit specified in factor 2 is off in the
result field (off status).
• Low - Columns 56 - 57
11–128
Operation Codes
This indicator turns on if some of the bits specified in factor 2 are on

and some are off in the result field (mixed status).
• Equal - Columns 58 - 59
This indicator turns on if each bit specified in factor 2 is on in the
result field (on status).
Example 11–71 TESTB Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C TESTB’04’ WK01 333435
C TESTBLOTTO WINNER 444546
In this example, the first TESTB operation checks bits 0 and 4 in the field
WK01. If both bits are off (0), indicator 33 will be turned on. If the bits
are in a mixed state, one off and one on, indicator 34 will be turned on. If
both bits are on (1), indicator 35 will turn on.
In the second TESTB operation, the bits which are on in the field LOTTO
will be compared to the corresponding bits in the field WINNER. If all bits
which are on in LOTTO are off (0) in WINNER, indicator 44 will be turned
on. If the bits which are on in the LOTTO field are in a mixed state in the
WINNER field, some on and some off, indicator 45 will be turned on. If all
bits which are on in the LOTTO field are also on (1) in the WINNER field,
indicator 46 will be turn on.
11–129
Operation Codes
11.12.56- TESTZ Operation (Test Zone)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank TESTZ Blank Required One required
Description
The Test Zone operation tests the zone of the leftmost character in an
alphameric field.
Rules
The result field is required. It must contain an alphameric field, table
element, array element, or data structure element.
At least one resulting indicator (columns 54 - 59) must be specified.
Operation
The TESTZ operation tests the zone portion of the leftmost character in
an alphameric entry. The resulting indicators are used to indicate the
results of the test. At least one resulting indicator must be specified. All
three resulting indicators can be used. The resulting indicators indicate
the following conditions:
• Plus - Columns 54 - 55
This indicator turns on if the zone of the leftmost character in the
result field is an &, A - I, or has the same zone as an A.
• Minus - Columns 56 - 57
result field is a J - R or has the same zone as a J.
• Zero - Columns 58 - 59
result field does not meet one of the first two conditions.
11–130
Operation Codes
Example 11–72 TESTZ Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C TESTZ ULP 102030
In this example, the TESTZ operation is used to test the zone portion of
the first character in the field ULP.
11–131
Operation Codes
11.12.57- TIME Operation (Time of Day)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank TIME Blank Required Blank Blank Blank
Description
The TIME operation returns the system time and date.
Rules
The result field is required. It must contain a 1 to 14-digit, zero-decimal,
numeric field. The time and date are returned by the TIME operation
in the format HHMMSSMMDDYYYY. This string is loaded from left
to right into the result field. If the result field contains a 6-digit field,
HHMMSS will be loaded into it. If the result field contains a 14-digit field,
HHMMSSMMDDYYYY will be loaded into it. If the result field contains a
4-digit field, HHMM will be loaded into it.
Operation
The TIME operation obtains the system date and time from the OpenVMS
$ASCTIM system service. The date obtained by the TIME operation may
not be the same as the date available from the UDATE or $UDATE field.
The user has the option of using the REX Utility to set a program date
which can differ from the system date. The program date is accessed via
the UDATE and $UDATE field. See the Migration RPG User’s Guide for
more information on the REX Utility.
The system date can be returned in MMDDYYYY, DDMMYYYY, or
YYYYMMDD format. The format used will depend upon the date format
code placed in column 19 of the Control specification.
11–132
Operation Codes
Example 11–73 TIME Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
IFULTIM DS
I 1 60TIME
I 7 140DATE
C*
C TIME CLOCK 60
C TIME FULTIM
In this example, the first TIME operation will move only the system time
to the field CLOCK, as CLOCK is defined as a 6-digit, numeric field. The
second TIME operation moves the system time and date into the data
structure FULTIM, which is defined as being 14 digits in length.
11–133
Operation Codes
11.12.58- $TIME Operation (Non-Year 2000 Compliant Time of Day)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank $TIME Blank Required Blank Blank Blank
Description
The $TIME operation returns the system time and a non-Year 2000
compliant date. The $TIME opcode is provides backward compatibility for
older applications which are not Year 2000 compliant.
Rules
The result field is required. It must contain a 1 to 12-digit, zero-decimal,
numeric field. The time and date are returned by the $TIME operation
in the format HHMMSSMMDDYY. This string is loaded from left to
right into the result field. If the result field contains a 6-digit field,
HHMMSS will be loaded into it. If the result field contains a 12-digit field,
HHMMSSMMDDYY will be loaded into it. If the result field contains a
2-digit field, HH will be loaded into it.
Operation
The $TIME operation obtains the system date and time from the
OpenVMS $ASCTIM system service. The date obtained by the $TIME
operation may not be the same as the date available from the UDATE or
$UDATE field. The user has the option of using the REX Utility to set a
program date which can differ from the system date. The program date
is accessed via the UDATE and $UDATE field. See the Migration RPG
User’s Guide for more information on the REX Utility.
The system date can be returned in MMDDYY, DDMMYY, or YYMMDD
format. The format used will depend upon the date format code placed in
column 19 of the Control specification.
11–134
Operation Codes
Example 11–74 $TIME Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
ITIMDAT DS
I 1 60TIME
I 7 120DATE
*
C $TIME SAVTIM 40
C $TIME TIMDAT
In this example, the first $TIME operation will move only the HHSS
portion of the system time to the field SAVTIM, as SAVTIM is defined as a
4-digit, numeric field. The second $TIME operation moves the system time
and non-Year 2000 compliant date into the data structure FULTIM, which
is defined as being 12 digits in length.
11–135
Operation Codes
11.12.59- XFOOT Operation (Summing the Elements of an Array)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank XFOOT Required Required Opt Opt Opt
Description
The XFOOT operation sums the elements in a numeric array and places
the total in the result field.
Rules
Factor 2 is required. It must contain the name of a non-indexed, numeric
array.
The result field is required. It must contain a numeric field entry which
will accept the product of the XFOOT operation.
after the XFOOT operation.
Example 11–75 XFOOT Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
E AR$ 5 5 0
.
.
.
C XFOOTAR$ TOTAR$ 70
In this example, the XFOOT operation is used to total the elements in the
numeric array AR$. The result of the XFOOT operation is placed in the
field TOTAR$.
11–136
Operation Codes
11.12.60- Z-ADD Operation (Zero-Add)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank Z−ADD Required Required Opt Opt Opt
Description
The Zero-Add operation initializes the result field with the contents of
factor 2.
Rules
Factor 2 is required. It must contain a numeric entry.
after the Z-ADD operation.
Operation
The Z-ADD operation adds the contents of factor 2 to zero and places the
product in the result field.
Example 11–76 Z-ADD Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C Z-ADD24 LOLLY 70
In this example, the Z-ADD operation is used to initialize the field LOLLY
to the value 24.
11–137
Operation Codes
11.12.61- Z-SUB Operation (Zero-Subtract)
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank Z−SUB Required Required Opt Opt Opt
Description
The Zero-Subtract operation initializes the result field with the contents of
factor 2.
Rules
Factor 2 is required. It must contain a numeric entry.
after the Z-SUB operation.
Operation
The Z-SUB operation subtracts the contents of factor 2 from zero and
places the product in the result field.
Example 11–77 Z-SUB Operation Code Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C Z-SUB100 POP 70
In this example, the Z-SUB operation is used to initialize the field POP to
the value -100.
11–138
12 Using Indicators
Indicators are one-character, alphameric fields that contain either a 0 or 1.

A 0 indicates an off condition; a 1 indicates an on condition. Indicators can
be referenced as data fields or array elements (*INxx, *IN,xx). Indicators
are used to condition when an operation occurs and what the results of an
operation are within an RPG program.
12.1 Available Indicators

The following table depicts all of the indicators available in an RPG
program and their primary functions:
Table 12–1 Available Indicators

Indicator(s) Description
01 - 99 General purpose indicators
1P First page indicator
H1 - H9 Halt indicators
KA - KN, Command key indicators
KP - KY
L0 Level Zero indicator
L1 - L9 Control break indicators
LR Last Record indicator
MR Matching record indicator
OA - OG, Overflow indicators
OV
RT Return indicator
U1 - U8 External indicators
12.2 Program Defined Indicators

Most indicators must be defined on the RPG specification lines before
they can be used to condition operations in an RPG program. However,
several indicators are defined by the RPG program itself and can be used
to condition operations within the program without first defining them on
a specification line. The following table lists these indicators and their
functions:
12–1
Using Indicators
Table 12–2 Program Defined Indicators

Indicator(s) Function Description
1P First Page This indicator is on for the first
cycle of an RPG program. It
allows the programmer to control
the output of heading lines during
first cycle output. The indicator
is turned off at the end of the
first cycle. It is entirely controlled
by the RPG program cycle and
cannot be set on or off by the
programmer.
L0 Level Zero The Level Zero indicator is always
on and can be used to condition
total time operations even when
control break fields are not in use.
LR Last Record The Last Record indicator is
turned on when all primary and
secondary input files have reached
an end-of-file condition. This
indicator can also be turned on
by the programmer in the Input or
Calculation specifications. When
the Last Record indicator is turned
on, the program carries out last
cycle processing and terminates.
MR Matching Record The matching record indicator
is turned on if match fields
(M1 - M9) are declared in a
program’s Input specifications and
a match field condition occurs.
The matching record indicator
cannot be set on or off in the
Calculation specifications.
U1 - U8 External Indicators External indicators can be set
outside of a program before it
is executed. They can also be
modified by a program and passed
to a command procedure or
another program. The REX Utility
is used to set and clear external
indicators from a command
procedure. See the Migration
RPG User’s Guide for more
information concerning the REX
Utility.
All remaining indicators must be defined in the File, Input, or Calculation

specifications before they can be used to control operations in a program.
12–2
Using Indicators
12.3 Indicator Types and Usage

Indicators function as on/off switches. To use an indicator to control
program operations, the conditions under which it is set on or off are first
defined. The status of the indicator (on or off) is then checked to determine
whether the specified operation should be performed.
Indicators are classed as types. The following types of indicators are
available within RPG program:
• User defined:
— Record Identifying
— Field
— Resulting
— Control Break
— Overflow
— Command Key
— Halt
— Return
• Program defined:
— First Page
— Last Record
— Level Zero
— Matching Record
— External
The remaining sections in this chapter describe each type of indicator and
its usage in a program.
12–3
Using Indicators
12.4 Indicators Defined By the Programmer

The indicators described in the following sections must be defined by the
programmer in the File Description, Input, or Calculation specifications.
12.4.1 Record Identifying Indicators

Record identifying indicators are used to distinguish the types of input
records that will be encountered within a program at run time.
Each input record defined in an RPG program normally has an identifying
indicator specified in columns 19 - 20. This indicator is turned on if
the data record being input matches the record identification conditions
specified in columns 21 - 41. The record identifying indicator permits the
programmer to determine the type of record which has been read and
condition program operations accordingly.
The following indicators can be specified as record identifying indicators:
Table 12–3 Record Identifying Indicators

Indicator(s) Function
01 - 99 These are general purpose indicators. They are normally used to
identify various record types.
H1 - H9 The halt indicators are normally used to indicate an error. Use
these indicators to identify invalid record types.
L1 - L9 The control break indicators can be used to specify that
calculation and output operations conditioned by control break
indicators will be performed at detail and total time. A control
break indicator set on as a record identifying indicator does not
set on all lower control break indicators.
LR The Last Record indicator indicates to the program that this is
the last record to be processed. This indicator can be used as
a record identifying indicator if input of a specific record type
indicates that the program should be terminated.
RT The return indicator is used to terminate an RPG subprogram
without resetting the program.
The record identifying indicator for a particular record type is set on when
RPG processes a record of that type. For a primary or secondary file,
the record identifying indicator is set on before total time calculations.
For a chained or demand file, the record identifying indicator is set on
immediately after the record is read. In either case, it is set off when the
program reaches the end of the current program cycle (after detail time
output).
Record identifying indicators can be set on or off within the Calculation
specifications.
If the CHAIN or READ operation is used to retrieve a record, the program
does not set the associated record identifying indicator off until the
beginning of the next program cycle. Be careful when performing more
than one CHAIN or READ operation for a file with multiple record types
12–4
Using Indicators
because more than one record identification indicator can be set on during
a single cycle.
Record identifying indicators can be used to condition both detail time
and total time calculation and output operations. The following example
shows how record identifying indicators can be used to condition program
operations:
Example 12–1 Record Identifying Indicators Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
00010FSALES IPE F 120 DISK
00020FREPORT O F 80 OF PRINTER
00030 *
00050I 2 50ITEM
00060I 10 15 DESCR
00070I 20 242SALES
00080I 30 342COST
00090I 40 432PROFIT
00100I BB 99
00110 *
00120C 01 SALES SUB COST NET 52
00130C 01 TSALES ADD SALES TSALES 62
00140C 01 TCOST ADD COST TCOST 62
00150C 01 TPROFT ADD NET TPROFT 62
00160 *
00170OREPORT H 201 1P
00180O OR OF
00190O UDATE Y 10
00200O 42 ’JANUARY SALES REPORT’
00210O 64 ’PAGE’
00220O PAGE 68
00230O H 22 1P
00240O OR OF
00250O 4 ’ITEM’
00260O 23 ’DESCRIPTION’
00270O 35 ’SALES’
00280O 47 ’COST’
00290O 60 ’PROFIT’
00300O D 01
00310O ITEM 3 5
00320O DESCR 22
00330O SALES 1 35
00340O COST 1 48
00350O PROFIT1 60
00360O T 1 LR
00370O 6 ’TOTALS’
00380O TSALES1 35 ’$’
00390O TCOST 1 48 ’$’
00400O TPROFT1 60 ’$’
12–5
Using Indicators
Example 12–1 (Cont.) Record Identifying Indicators Usage
• Line 10 indicates that the program will be reading records from the
file SALES. The identification code (columns 21 - 41) on line 40 groups
these records according to a code that represents the month. If the
code for the month is J, the record identifying indicator 01 is set on.
• Lines 120 - 150 use the record identifying indicator 01 to condition
detail time calculations. The calculation are performed each time a
record of the type described on line 40 is read.
• Line 300 uses the record identifying indicator 01 to condition detail
time output. The output operation is performed each time a record of
the type described on line 40 is read.
The output file produced by the program in Example 12–1 might appear
as follows:
Example 12–2 Output generated by Example 12–1
1 2 3 4 5 6
12345678901234567890123456789012345678901234567890123456789012345678
02/04/83 JANUARY SALES REPORT PAGE 1
ITEM DESCRIPTION SALES COST PROFIT
10005 AMMONIA 60.30 50.00 10.30
10982 MATCHES 295.00 205.00 90.00
22650 NUTMEG 209.00 170.00 39.00
TOTALS $564.30 $425.00 $139.30
12.4.1.1 AND and OR Relationships

A maximum of three identification characters can be specified on one
Input specification. An AND line can be used to continue the record
identification condition from the previous line. All conditions must be
matched before the associated record identifying indicator will be turned
on.
If a record can be identified by more than one set of conditions, an OR line
is used to separate each set of record identification conditions. An OR can
also be used to specify additional record identification indicators.
Table 12–4 AND and OR Relationships

Allowable
Entries Explanation
AND Specifies an AND relationship between the identification conditions
on the current program line and the previous program line.
OR Specifies an OR relationship between the record identification
conditions on the current program line and the previous program line.
12–6
Using Indicators
A record identifying indicator can be specified in columns 19 - 20 in an

OR line. If columns 19 - 20 are left blank, the record identifying indicator
specified in the preceding program line will apply to the OR line.
The following example depicts the use of the AND and OR qualifiers with
record identification indicators.
Example 12–3 AND/OR Usage With Record Identifying Indicators
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
00040ISALES AA 01 1 CJ 2 CU 3 CL
00041I AND 4 CY
00050I 1 9 MONTH
00060I 10 15 CODE
00061I AX 98
00070 *
00080ICUSTMST BB 02 1 CA 2 CA
00081I OR 1 CA 2 CB
00082I OR 03 1 CB 2 CB
00060I 1 5 CODE
In this example, the SALES record on lines 40 and 41 uses the AND
qualifier to construct a 4-character record identification condition. In this
case, the record identifying indicator 01 will be turned on if the first 4
positions in the SALES record are JULY.
On lines 80 - 82, the OR qualifier is used to describe three different sets of
record identification conditions which can be used to select the CUSTMST
record. If the first two characters in the CUSTMST record are AA, the
record identification conditions on line 80 are satisfied and indicator 02 is
turned on. If the first two characters in the CUSTMST record are AB, the
turned on. Note that because no record identification indicator has been
specified on line 81, the program defaults back to the indicator specified
on line 80. If the first two characters in the CUSTMST record are BB, the
turned on.
12–7
Using Indicators
12.4.2 Field Indicators

Field indicators test a field in an input record for a positive, negative, zero,
or blank value.
The following indicators can be used as field indicators:
Table 12–5 Field Indicators

01 - 99 These are general purpose indicators. They are normally used
to determine whether the contents of an input field are positive,
negative, zero, or blank.
H1 - H9 The halt indicators are normally used to identify error conditions
in the input data (for example, a negative value appearing where
one is not expected).
Field indicators are used to test the value of a field in the following ways:
• To determine if a numeric field is positive, specify a field indicator in
columns 65 - 66 of the Input specification. The indicator will be turned
on if the field’s contents are positive.
• To determine if a numeric field is negative, specify a field indicator in
on if the field’s contents are negative.
• To determine if a numeric field is zero, specify a field indicator in
on if the field’s contents are zero.
• To determine if an alphameric field is all blanks, specify a field
indicator in columns 69 - 70. The indicator will be turned on if the
field’s contents are blank.
Field indicators cannot be specified in columns 65 - 68 on an alphameric

input field.
If a numeric field is filled with blanks, it will cause the zero field indicator
(columns 69 - 70) to turn on. A blank is equivalent to a zero within a
numeric field. A zero is not equivalent to a blank in an alphameric field.
Field indicators are set when the data in the field is extracted from the
record. After a field indicator is set on, it remains on until the next
time the field is extracted, unless it is set off by another use of the same
indicator in the program. A field indicator can be used to condition any
detail time or total time operations. However, at total time, the field
indicators assigned to fields from a primary or secondary file retain the
setting from the previous detail time cycle.
12–8
Using Indicators
The following example shows how field indicators can be used to condition
a Calculation specification:
Example 12–4 Field Indicator Usage
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890
*
00024IPARTLIS AA 01 1 CF
00025I 2 100INVCDE 112233
.
.
.
00041C 11 ITEM MULT FACT1 ORDER 62H
00042C 22 ITEM MULT FACT2 ORDER H
00043C 33 ITEM MULT FACT3 ORDER H
• Line 25 tests the value of the field INVCDE to see if it contains a

positive value, a negative value, or a zero value. The following is a list
of indicators that are set on for each value:
— If the field contains a positive value, indicator 11 is set on and
indicators 22 and 33 are set off.
— If the field contains a negative value, indicator 22 is set on and
— If the field contains a zero value, indicator 33 is set on and
• Lines 41 through 43 calculate the number of parts to order according
to the status of the INVCDE field indicators.
12–9
Using Indicators
12.4.3 Resulting Indicators

Resulting indicators are used to indicate the result of an operation in the
Calculation specifications. Resulting indicators can be used to condition
calculation and output operations.
Resulting indicators are specified in columns 54 - 59 of the Calculation
specification. The following indicators can be used as resulting indicators:
Table 12–6 Field Indicators

01 - 99 These are general purpose indicators. Keep in mind that these
indicators can also be used in the Input specifications as record
identifying and field indicators.
H1 - H9 The halt indicators are generally used to indicate an error
condition.
KA - KN, The command key indicators are normally used as resulting
KP - KY indicators with the SETnn operation code.
L1 - L9 The control break indicators can be used to specify that control
break calculation and output operations will be performed at detail
and total time. A control break indicator set on as a resulting
indicator does not set on all lower control break indicators.
LR The Last Record indicator indicates to the program that this is
the last record to be processed. This indicator can be used as a
resulting indicator to indicate that the result of an operation should
terminate the program.
OA - OG, OV The overflow indicators are normally used to condition output
to a printer file. They can also be used to condition calculation
operations.
U1 - U8 The external indicators are generally used to pass information
between programs and procedures.
How and when resulting indicators are specified and set is dependent upon
the calculation operation being performed. Not all operations require or
even allow resulting indicators. Chapter 11, Operation Codes, contains
descriptions of all of the RPG operation codes and their related resulting
indicator usage.
12–10
Using Indicators
The following example shows how resulting indicators can be used to

control program operations:
Example 12–5 Resulting Indicator Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
00010C HOME COMP VISTOR 102030
00020C 10 ADD 1 WINS
00030C 20 ADD 1 LOSSES
00040C 30 ADD 1 TIES
• On line 10, a COMP operation is used to compare the contents of the

numeric fields HOME and VISTOR. The resulting indicators specified
in columns 54 - 59 will be cleared when the COMP operation begins
and will then be set based on the following conditions:
— If HOME is greater than VISTOR, indicator 10 will be set on.
— If HOME is less than VISTOR, indicator 20 will be set on.
— If HOME is equal to VISTOR, indicator 30 will be set on.
• The ADD operation on line 20 will be executed if indicator 10 is on.
12–11
Using Indicators
12.4.4 Control Break Indicators

Control break indicators indicate that a particular field in the input record
is a control field. Each time the program reads a record that contains
the control field, it compares the data in the control field with the stored
value of the control field which was obtained from a previous record. If
the contents of the control field change, a control break occurs, the control
break indicator is set on, and the value in the current control field becomes
the new stored control value.
Indicators L1 - L9 are the control break indicators. They are associated
with an input field by specifying the indicator in columns 59 - 60 of the
Input specification.
12.4.4.1 Using Control Break Indicators

When conditioning Calculation specifications, control break indicators
can be used in two ways. They can be used as conditioning indicators on
detail time Calculation specifications and they can be used to define total
time calculations. When used on detail time Calculation specifications,
the indicators are specified in columns 9 - 17. Detail time Calculation
specifications have blanks in columns 7 - 8. Total time Calculation
specifications have one of the following indicators specified in columns
7 - 8:
• L0
• L1 - L9
• LR
Calculation specifications with control break indicators specified in

columns 7 - 8 are only executed during total time processing if the
specified indicator is on.
12.4.4.2 Rules for Specifying Control Break Indicators

Control break indicators can only be specified for primary and secondary
input and update files.
Control break indicators can be assigned in any order.
Control break indicators are ranked from highest (L9) to lowest (L1).
When a control break causes RPG to set on a control break indicator,
all lower control break indicators are set on as well. For example, if the
indicator L5 is set on due to a control break, indicators L1 - L4 will also be
set on. All control break indicators are set off after detail time output.
Control fields are initialized to hexadecimal zeros. This usually causes a
control break to occur on the first record with a control field. Because of
this, RPG bypasses total time calculation and output operations on the
first cycle.
Fields with different control break indicators can overlap in a record.
The same number of control fields do not need to be specified for all record
types.
Control break indicators cannot be specified on look-ahead fields.
12–12
Using Indicators
The maximum length of a control field or split-control field is 144

characters.
The decimal position and sign of numeric fields are ignored when checking
for a control break. Thus, the fields 257.8 and 2578 would be considered
equal. The fields -3049 and 3049 would also be considered equal.
Field names are ignored when processing control fields. This allows the
same control break indicator to be assigned to multiple fields with the
same name.
If any one control field is numeric, all fields assigned to that control break
indicator will be treated as numeric when being compared, meaning that
only the digit portion of each character will be compared.
If a control field contains packed-decimal data, the zoned-decimal length,
which is two times the packed-decimal length minus one, is considered the
length of the field for comparison purposes.
Input fields defined as binary (B in column 43) cannot be used as control
break fields.
All control break indicators are set on before total time calculations when
the Last Record (LR) indicator is set on. All control break indicators are
set off after detail time output.
12–13
Using Indicators
12.4.4.3 Control Break Indicator Usage Example

The following example shows how control break indicators are used to
control total time calculations and output:
Example 12–6 Control Break Indicator Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
00010FSALESFILIPE F8000 80 DISK
00020FREPORT O F 80 PRINTER
*
00050ISALESFILAA 01
00060I 01 04 REGIONL8
00070I 05 08 DIST L7
00080I 09 38 SALNAM
00090I 39 44 SALEIDL6
00100I P 45 492SALES
.
.
.
00200C SALES ADD SALTOT SALTOT 92
.
.
.
00300CL6 SALTOT ADD DISTOT DISTOT 92
00310CL7 DISTOT ADD REGTOT REGTOT 92
00320CL8 REGTOT ADD GRAND GRAND 102
.
.
.
00400OREPORT T L6
00410O 20 ’Total for Sales Person:’
00420O SALNAM 51
00430O SALEID 60
00440O SALTOT B 80 ’$ , , . ’
00450OREPORT T L7
00460O 20 ’District Total’
00470O DISTOT B 80 ’$ , , . ’
00480OREPORT T L8
00490O 20 ’Regional Total’
00500O REGTOT B 80 ’$ , , . ’
00510OREPORT T L9
00520O 15 ’Grand Total’
00530O GRAND B 80 ’$ , , . ’
12–14
Using Indicators
Example 12–6 (Cont.) Control Break Indicator Usage
• On line 60, the field REGION is conditioned by the control break

indicator L8.
• On line 70, the field DIST is conditioned by the control break indicator
L7.
• On line 90, the field SALEID is conditioned by the control break
indicator L6.
• As long as none of the control break indicators are turned on, lines
300, 310, and 320 will not be executed.
• If, after the input of a new record, RPG determines that the field
SALEID in the current record differs from the value in storage, a
control break occurs and the indicator L6 is turned on. When the L6
indicator is turned on, all lower control break indicators are turned
on as well. Thus, the L6 control break turns on indicators L1 - L6.
During total time processing, the program will perform all L1 - L6
total time calculations and output operations. In the example, this
includes lines 300 and 400 - 440.
• If, after the input of a new record, RPG determines that the field
REGION in the current record differs from the value in storage, a
control break occurs and the indicator L8 is turned on. This will turn
on control break indicators L1 - L8. In the example, lines 300 - 320
and 400 - 500 will be executed during total time processing.
• After the last input record in the file has been read, the Last Record
indicator (LR) and all control break indicators are turned on. This is
part of last cycle, total time processing. With indicators L1 - L9 on,
all total time calculations and output are performed. In the example,
lines 300 - 320 and 400 - 530 will be processed.
12–15
Using Indicators
12.4.4.4 Split Control Fields

When the same control break indicator is assigned to more than one field,
the fields are referred to as split-control fields. In this case, the fields
must be either all numeric or all alphameric and described on adjacent
lines. The fields used within split-control fields do not need to be the same
length.
The total length of a split-control field must be the same length as other
fields using the same control break indicator.
The following example shows how to use split-control fields:
Example 12–7 Split control fields
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890
*
00050I 2 5 BRNCH L3
00060I 10 15 SLSPR L3
00070I 20 24 CUSTNOL3
00080I BB 02 1 CF
00090I 1 23 UNIT L3
In this example, the fields BRNCH, SLSPR, and CUSTNO combine to form
the control field. When the data in these fields is compared with the data
in storage obtained from a previous record, indicator L3 is set on if the
data has changed in any of the fields.
The field UNIT has also been assigned the control break indicator L3.
Note that the length of UNIT is equal to the combined length of BRNCH,
SLSPR, and CUSTNO. If the UNIT record is input, the contents of the
field UNIT will be compared to the L3 storage area.
12–16
Using Indicators
12.4.5 Overflow Indicators

An overflow indicator is defined in columns 33 - 34 of the File Description
specification. An overflow indicator can only be specified for a PRINT or
PRINTER file. It is used to indicate when the defined length of a printer
form has been reached. (See Chapter 14, Using Printer Output Files, for
information on printer output files.)
Overflow indicators are generally used to indicate which lines should be
output at the end of the current page and the beginning of the next after
the overflow line has been reached. The overflow line is usually defined as
something less than the overall form length.
The indicators OA, OB, OC, OD, OE, OF, OG, and OV are all valid
overflow indicators. Only one overflow indicator can be assigned to a
printer file.
The overflow indicator is automatically set on when the printer file reaches
the overflow line. By default, the overflow line is defined to be at line 60.
The Line Counter specification can be used to modify the overflow line to
be anything between 1 - 112. The overflow indicator is automatically set
off at the end of the next cycle.
Overflow indicators can also be used and manipulated in the Calculation
specifications.
12–17
Using Indicators
The following example depicts the use of overflow indicators to condition

the output of heading and detail lines.
Example 12–8 Overflow Indicator Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
.
.
.
00180O OR OF
00190O UDATE Y 10
00200O 44 ’SALES REPORT’
00210O 68 ’PAGE’
00220O PAGE 72
00230O H 22 1P
00240O OR OF
00250O 5 ’ITEM’
00270O 41 ’SALES’
00280O 56 ’COST’
00290O 72 ’PROFIT’
00300O D 01
00310O ITEM 3 5
00320O DESC 25
00330O SALES 1 41
00340O COST 1 57
00350O PROFIT1 72
00360O D 1 OF
00370O 30 ’SUBTOTALS’
00380O TSALES1 41 ’$’
00390O TCOST 1 57 ’$’
00400O TPROFT1 72 ’$’
00410O T 1 LR
00420O 30 ’GRAND TOTAL’
00430O TSALES1 41 ’$’
00440O TCOST 1 57 ’$’
00450O TPROFT1 72 ’$’
• On line 20, the overflow indicator OF is associated to the printer file

REPORT.
• When the overflow indicator is turned on during detail time output,
the output record on line 360 will be output at the end of the current
page. This will be followed by the output records on lines 170 and 230,
which will appear at the beginning of the next page.
See Chapter 14, Using Printer Output Files, for a full description of the
overflow routine and overflow indicators.
12–18
Using Indicators
12.4.6 Command Key Indicators

Command key indicators can be used to condition calculations, output
records, and output fields. They can also be used as resulting indicators on
the SETnn and SETOF operations. Command key indicators are generally
associated with a WORKSTN file or SETnn operation.
The command key indicators, KA - KN and KP - KY, are directly
associated to the command keys CMD1 - CMD24 , as indicated by the
following table:
Table 12–7 Command Key Indicators

Indicator Command Key Command Key Sequence
KA CMD1 PF1 + 1
KB CMD2 PF1 + 2
KC CMD3 PF1 + 3
KD CMD4 PF1 + 4
KE CMD5 PF1 + 5
KF CMD6 PF1 + 6
KG CMD7 PF1 + 7
KH CMD8 PF1 + 8
KI CMD9 PF1 + 9
KJ CMD10 PF1 + 0
KK CMD11 PF1 + -
KL CMD12 PF1 + =
KM CMD13 PF1 + Shift !
KN CMD14 PF1 + Shift @
KP CMD15 PF1 + Shift #
KQ CMD16 PF1 + Shift $
KR CMD17 PF1 + Shift %
KS CMD18 PF1 + Shift ^
KT CMD19 PF1 + Shift &
KU CMD20 PF1 + Shift *
KV CMD21 PF1 + Shift (
KW CMD22 PF1 + Shift )
KX CMD23 PF1 + Shift _
KY CMD24 PF1 + Shift +
Command key indicators are defined in the key mask of a workstation

Screen specification or as the resulting indicators in a SETnn operation. A
command key indicator is turned on when the user presses the associated
command key. If the indicator is set on by a WORKSTN device, it will be
set off the next time a record is input from the WORKSTN device. If the
indicator is set on by a SETnn operation, it will be set off the next time it
is encountered in a SETnn operation. Command key indicators can also be
set off by the SETOF operation.
12–19
Using Indicators
12.4.7 Halt Indicators

Halt indicators (H1 - H9) are used to stop an RPG program when an
unacceptable condition is detected. Halt indicators can be used as record
identifying indicators, field indicators, or resulting indicators.
When a halt indicator is turned on, the program does not stop immediately.
Halt indicators are actually checked at the beginning of the program cycle
(see Chapter 1, Understanding the Migration RPG Logic Cycle. This
means that all total and detail time operations in the current cycle are
performed before the program halts. Since the data which triggered the
halt will continue to be processed until the program stops, it is wise to use
the halt indicator to condition operations which should not be performed
when a halt condition is present.
When the halt is processed by a program running in an interactive
environment, processing stops and the user is prompted to continue or
terminate the program. The user is given the following options to respond
to a halt condition:
• CONTINUE - This option tells the program to clear the halt indicator
and continue processing normally.
• EXIT - This option tells the program to terminate immediately.
• KILL - This option tells the program to terminate immediately.
The response to the CONTINUE, EXIT, KILL prompt can be abbreviated

to a single character: C, E, or K.
For all intents and purposes, the EXIT and KILL option do the same thing
in the Migration RPG processing environment. They cause a controlled
shutdown of the program and, depending upon the compiler options
selected, may return a warning status when the program exits. Both the
EXIT and KILL prompts are supported by Migration RPG to offer a level
of compatibility with non-OpenVMS versions of RPG.
The program will cycle through the halt processing step until all nine halt
indicators have been checked or the user selects the EXIT or KILL option
at the prompt. For example, if halt indicators H1, H3, and H4 were set
during a single cycle, the user would be prompted three times to continue
or terminate the program, once for each halt indicator.
If the program is running as a batch job and a halt indicator is set, the
program will terminate at the beginning of the next cycle, returning an
error status.
If no halt indicators are set or if the user clears all set halt indicators
using the CONTINUE option, the program continues processing normally.
If a halt indicator is set and the program is running in batch mode, or the
user selects the EXIT or KILL option at the halt prompt, the program will
terminate.
12–20
Using Indicators
When a halt indicator is used as a record identifying indicator, a specific

type of record causes the halt. In the following example, a halt indicator
is used as a record identifying indicator, causing the program to check
the character in position 80 of records read from the input file FILEIN.
If the eightieth character is not an S, the halt indicator H1 is set on and
the program will stop execution at the beginning of the next cycle. If the
program is running interactively, the user will be prompted to continue
or terminate it. If the program is running in a batch process, it will
terminate with an error status set.
Example 12–9 Halt Indicator Usage - Record Identification
1 2 3 4 5
1234567890123456789012345678901234567890123456789012345678
*
IFILEIN AA 02 80 CS
I 01 10 FIELD1
I XX H1 80NCS
When a halt indicator is used as a field indicator, a halt occurs because

of erroneous input data. The following program uses a halt indicator
as a field indicator. When a record is read from the input file FILEIN,
FIELD1 is checked for a negative value. If FIELD1 contains a negative
value, the indicator H2 is set on. After this record has been processed, the
program will halt. Note that the H2 indicator has been used to condition
a Calculation specification, ensuring that the SQRT operation will not be
performed if the data in FIELD1 is invalid.
Example 12–10 Halt Indicator Usage - Field Indicator
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
IFILEIN AA 01
I 01 50FIELD1 H2
*
C NH2 SQRT FIELD1 FLD2 95
When a halt indicator is used as a resulting indicator, a halt occurs when

a calculation produces erroneous results during either detail or total
time processing. In the following example, a halt indicator is used as a
resulting indicator. If FIELD1 is equal to zero, the indicator H4 is set on.
After the current record is processed, the program halts. Note that the H4
indicator is used to condition the subsequent DIV operation, preventing a
fatal divide-by-zero error.
Example 12–11 Halt Indicator Usage - Resulting Identification
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C FIELD1 SUB 59 FIELD1 H4
C NH4 FIELD2 DIV FIELD1 FIELD1
12–21
Using Indicators
12.4.7.1 Processing Halt Indicators In RPG Subprograms

Halt indicators are processed within an RPG subprogram in the same
manner they are handled in a normal program. When a halt indicator
is turned on, processing halts at the beginning of the next cycle and
the user is given the option of continuing or terminating the program.
However, when a subprogram is terminated, it returns control to the
calling program, and it is possible to exit a subprogram with one or more
halt indicators set.
If a subprogram is exited with a halt indicator set and the /NOWARNING
option was not selected when the program was compiled, a warning
message is issued to the user. The subprogram exits with an error status,
turning on the error indicator in columns 56 - 57 of the CALL operation, if
one was specified.
If a subprogram is exiting due to the return indicator (RT) being set and a
halt indicator is also on when the subprogram exits, the subprogram will
be reset, meaning that the subprogram will be shut down upon exit and
will be reinitialized when called again. The presence of a set halt indicator
invalidates the ability of the return indicator to preserve a subprogram’s
settings for another call.
12–22
Using Indicators
12.4.8 Return Indicator (RT)

The return indicator is used to signal an RPG subprogram to return to
the calling program without resetting the subprogram. The RT indicator is
turned off when a subprogram is called again.
When an RPG subprogram is exited using the RT indicator, all of the
current indicator, field, and file settings are preserved. The next time
the subprogram is called, it begins operation with these settings intact,
essentially starting up where it left off. A subprogram can be reset by
exiting with the LR indicator on, exiting with a halt indicator (H1 - H9)
on, or using the FREE operation code in the calling program. See
Chapter 19, Coding Subprograms, for more information concerning calling
and resetting RPG subprograms.
The RT indicator is checked after the halt (H1 - H9) and Last Record (LR)
indicators have been checked. Both the halt indicators and Last Record
indicator take precedence over the RT indicator. If a subprogram exits
with either a halt or the Last Record indicator on, the subprogram will be
reset.
The RT indicator can be set by using it as a record identifying indicator,
field indicator, or resulting indicator. It can be used to condition
calculation and output operations. The RT indicator is always turned
off during program or subprogram startup.
Example 12–12 Return Indicator Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C ASTEK COMP 999 RT
C RT ADD 1 COUNT
In this example, the RT indicator is turned on if the contents of the field

ASTEK are equal to 999. The RT indicator is also used to condition the
incrementing of the field COUNT. Turning the RT indicator on indicates
that the subprogram should terminate at the end of the current cycle,
returning control to the calling program.
12–23
Using Indicators
12.5 Indicators Defined By The Program

The indicators described in the following sections are predefined within the
RPG program. They can be used without first defining them in a program
specification.
12.5.1 First Page Indicator (1P)

The first page indicator (1P) is set on at the start of the program and set
off after detail time output before the first record is read. The first page
indicator can be used to condition the heading lines to be printed before
the program processes the first record.
The first page indicator is internally defined and controlled. It cannot be
set on or off by the programmer. It is on when a program starts up, and
remains on until just before the first record is read by the program. The
purpose of the first page indicator is to allow the programmer to output
heading information on a report during the first cycle before a record is
read by the program.
The first page indicator can be used to condition detail or heading output
lines. It cannot be used to condition total time or exception output lines. If
a detail or heading output line is not to be output during the first cycle and
is conditioned by all negative indicators or has no indicators associated to
it, use a not-first page (N1P) indicator to prevent the line from being
output during the first cycle.
The following example shows how to use the 1P indicator to print a
heading on the first page of a report:
Example 12–13 First Page Indicator Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
00180O OR OF
00190O UDATE Y 10
00200O 39 ’SALES REPORT’
00210O 64 ’PAGE’
00220O PAGE 68
00230O H 22 1P
00240O OR OF
00250O 4 ’ITEM’
00270O 35 ’SALES’
00280O 47 ’COST’
00290O 60 ’PROFIT’
In this example, the output records defined on lines 170 - 180 and
230 - 240 will be output during the first cycle, ensuring that the program
has appropriate headings on the first page. The overflow indicator (OF)
ensures that the headings are repeated on each new page.
12–24
Using Indicators
The following heading lines would be printed on the first page of the report
when the specifications in Example 12–13 are executed during the first
cycle.
1 2 3 4 5 6
12345678901234567890123456789012345678901234567890123456789012345678
02/04/83 SALES REPORT PAGE 1
ITEM DESCRIPTION SALES COST PROFIT
12–25
Using Indicators
12.5.2 Last Record Indicator (LR)

The Last Record indicator (LR) is used to condition calculation and output
operations which will occur at the end of the program. Like the first cycle
in an RPG program, the last cycle differs from all other program cycles.
After the last record in all primary and secondary files for which end-of-file
processing was specified has been read, the Last Record (LR) indicator is
set on. When the Last Record indicator is turned on, all control break
indicators (L1 - L9) are also turned on. This ensures that during the last
cycle, all total time calculations and output will be performed.
If a program does not contain a primary file or the primary file is
associated to a WORKSTN or KEYBORD device, the LR indicator must be
set by the programmer to end execution of the program. When setting the
LR indicator on manually, keep the following points in mind:
• If the LR indicator is set on during input, all control break (L1 - L9)
indicators will be turned on and total time operations will take place
before the program terminates.
• If the LR indicator is set on during detail calculations, all control break
indicators (L1 - L9) are set on at the beginning of the next cycle and
total time operations will take place before the program terminates.
• If the LR indicator is set on during execution of total time calculations,
the program will terminate as soon as total time processing has been
completed. Any control break indicators (L1 - L9) which were not on
at this time will not be turned on.
The LR indicator is always represented by LR, as shown in the following

example:
Example 12–15 Last Record Indicator Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
00360O T 1 LR
00370O 6 ’TOTALS’
00380O TSALES1 35 ’$’
00390O TCOST 1 48 ’$’
00400O TPROFT1 60 ’$’
The following information will be output after processing the last record in
Example 12–15:
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890
TOTALS $564.30 $425.00 $139.30
12–26
Using Indicators
12.5.3 Level Zero Indicator (L0)

The Level Zero indicator (L0) is always on and cannot be set off by the
programmer. It can be used to condition total time and control break
operations, even when control break fields have not been specified. If no
control breaks have been defined, but total time calculations and output
are desired, use the L0 indicator to condition those operations.
The Level Zero indicator can only be used in columns 7 - 8 of the
Calculation specifications and columns 23 - 31 of the Output specifications.
In the following example, total time calculations and output are to be
performed when a record with a B in position one is read from the SALES
file. The L0 indicator is used to define the total time operations and the
02 indicator is used to determine when they will be executed.
Example 12–17 Level Zero Indicator Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890
*
00050ISALES AA 01 1 CA
00060I 01 04 REGION
00070I 05 08 DIST
00080I 09 38 SALNAM
00090I 39 44 SALEID
00100I P 45 492SALES
00050I BB 02 1 CB
.
.
.
00320CL0 02 REGTOT ADD GRAND GRAND 102
.
.
.
00510OREPORT T L0 02
00520O 15 ’Grand Total’
00530O GRAND B 80 ’$ , , . ’
12–27
Using Indicators
12.5.4 Matching Record Indicator (MR)

The matching record indicator (MR) can only be used when processing
primary and secondary input and update files. When more than one
primary and secondary file is in use, RPG multifile logic supplies a method
for selecting the next record to process via the matching record function.
When processing records from primary and secondary input and update
files, the matching record function can be used to determine which record
will be processed next. To select the next record for processing, fields
within the primary and secondary data records are compared. These fields
are called match fields and are designated using the codes M1 - M9 in
columns 61 - 62 of the Input specifications.
If all of the match fields match, the MR indicator is turned on and the
record from the secondary file is processed. If the match fields do not
match, a record from the primary file is processed and the MR indicator
is turned off. The MR indicator can be used to condition operations which
should only occur when records match.
The MR indicator is set immediately after total time operations are
performed. At detail time, the MR indicator indicates the match status
of the record just read for processing. At total time, the MR indicator
indicates the match status of the previous record.
The MR indicator cannot be set or cleared by the programmer.
12–28
Using Indicators
Example 12–18 Matching Record Indicator Usage
1 2 3 4 5 6
12345678901234567890123456789012345678901234567890123456789012
*
00003FMRGIA IP AF 40 40 DISK
00004FMRGIB IS AF 40 40 DISK
.
.
.
00006IMRGIA NS 01 01 CA
00007I 1 1 COD
00008I 2 40KEY M1
00012IMRGIB NS 03 01 CB
00013I 1 1 FUD
00014I 2 40CORE M1
.
.
.
00050C MR MOVE CORE DUP
00051C MR ADD 1 DUPCNT
.
.
.
01410O D 1 MR
01420O 30 ’DUPLICATE CODE: ’
01430O DUP 35
In this example, the fields KEY and CORE serve as match fields (M1)
for the files MRGIA and MRGIB. If the contents of KEY and CORE
match, a record is read from the secondary file (MRGIB) and the MR
indicator is turned on. Turning the MR indicator on will cause the
calculation operations on lines 50 and 51 and the output operations on
lines 1410 - 1430 to be executed.
If the contents of the KEY and CORE fields do not match, a record is read
from the primary file (MRGIA) and the MR indicator is turned off.
12–29
Using Indicators
12.5.5 External Indicators

External indicators (U1 - U8) are indicators which can be set prior to
running an RPG program. External indicators can be used to control the
following operations:
• Indicate whether a file is to be accessed by the program.
• Condition calculation operations.
• Condition output operations.
• Provide communications between programs and procedures.
External indicators can be set using the REX Utility in a command

procedure or by another program. They are automatically read into an
RPG program or subprogram when it is initialized. They can be modified
by the current program using the SETON and SETOF operations and
passed on to another program or procedure. See the Migration RPG User’s
Guide for more information concerning the REX Utility.
When an external indicator is used to condition a file, the file is opened
only if the external indicator is set on. If the external indicator is set
off, the file is placed in an end-of-file state at program startup and
ignored. It is advisable to use the file conditioning external indicator
as a conditioning indicator on calculation and output operations related to
the file, preventing them from being executed when the file is not available
for processing.
Example 12–19 External Indicator Usage
1 2 3 4 5 6 7
123456789012345678901234567890123456789012345678901234567890123456789012
*
00003FHOOSER IPE F 80 DISK
00004FFROSTY USE F 140 DISK U1
.
.
.
00050C U1 MOVE SNOW MAN
.
.
.
01410OFROSTY D U1
01420O MAN 10
In this example, the file FROSTY will not be available for processing
unless the external indicator U1 is on. If U1 is on, the file will be opened
and the calculation and output operations on lines 50 and 1410 - 1420 will
be performed. If U1 is off, the file will not be opened and the operations
on these lines will be ignored.
12–30
Using Indicators
12.6 Using Indicators as Fields

The *IN, *IN,xx, and *INxx are special words that allow indicators to
be accessed as data fields. The *INxx allows individual indicators to be
accessed as single-character, alphameric data fields. The *IN special word
allows indicators 01 - 99 to be referenced as a single-character, 99-element,
alphameric array. The *IN,xx special word allows indicators 01 - 99 to be
referenced as individual elements in the *IN array.
12.6.1 *IN and *IN,xx

The special word *IN is a predefined array with 99, one-position, character
elements. The elements in this array represent indicators 01 - 99. Use
*IN,xx, where xx is the array index, to reference an indicator. For
example, *IN,54 refers to indicator 54.
The elements in this array can assume only two character values: 0 or 1.
If an indicator is referenced using *IN,xx and the contents of the element
are 0, the indicator is off. If the contents of the element are 1, the
indicator is on. The *IN indicator array reference (xx) can be a numeric
literal or field with a value of 1 - 99.
The *IN array and array elements can be used to reference an indicator
anywhere any other one-character array or array element can be used
within an RPG program. To prevent unpredictable results when using
indicators 01 - 99, place only the characters 0 or 1 in each element. When
the program is initialized, all elements in the *IN array are set to 0.
In the following example, the program tests whether the setting for
indicator 15 is equal to the setting for indicator 20. In the next line,
indicator 20 is set on. Using the MOVE operation to transfer 1 to *IN,20
produces the same result as using the SETON operation code to set on
indicator 20.
Example 12–20 *IN Indicator Array And Element Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C *IN,20 COMP *IN,15 99
C MOVE ’1’ *IN,20
12–31
Using Indicators
12.6.2 *INxx
The special word *INxx is a predefined, single-character, alphameric field
where xx represents any valid RPG indicator. Like *IN array elements,
*INxx fields can contain only the characters 0 or 1.
*INxx fields can be used anywhere any other single-character, alphameric
field can be used.
In the following example, the value of the indicator 20 is checked in an IF
operation. If the indicator is on (value = 1), the IF construct is executed.
If the indicator is off (value = 0), the IF construct is bypassed.
Example 12–21 *IN Indicator Array And Element Usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C MOVE ’1’ ON 1
C MOVE ’0’ OFF 1
.
.
.
C *IN,20 IFEQ ON
C READ TRIPLX 99
C END
12–32
13 Using DISK Files
A file is a collection of information that is organized into groups or sections

called records. Each record consists of one or more blocks of characters or
numbers called fields.
This chapter explains the Migration RPG file organizations and
record operations that are implemented through the OpenVMS Record
Management Services (RMS). For additional information on file
organization and file and record operations, see the OpenVMS Record
Management Services Reference Manual.
13.1 File Characteristics

Files are created, modified, and processed according to their respective
characteristics, which are chosen to make the most efficient use of both
system resources and the data in the files. Significant characteristics of
files used in RPG programs are the file type, designation, and mode of
processing.
The file type used in an RPG program determines how the records in the
files are processed. File types include:
• Input (I)
• Output (O)
• Update (U)
• Combined (C)
The file designation used by an RPG program defines the method by which
the program processes the file. The file designations include:
• Primary (P)
• Secondary (S)
• Record-address (R)
• Chained (C)
• Pre-execution-time table (T)
• Demand (D)
• Full-procedural (F)
Chapter 4, File Description Specification (F), contains a complete

description of the file type and designation codes.
13–1
Using DISK Files
13.2 File Names

Columns 7 - 14 (File name) of the File Description specification define the
file name. RPG uses the entry in columns 7 - 14 and the entry in columns
47 - 52 (Symbolic device) to associate the file name with the OpenVMS file
specification. The default DISK file type is .DAT.
The entry in columns 7 - 14 can be used as a logical name representing
the OpenVMS file specification. If a logical name is not defined as the
entry in columns 7 - 14, the file specification will consist of the file name
in columns 7 - 14 and the file type .DAT. For example, if columns 7 - 14
contain the name PURRBALL, and no logical name PURRBALL has been
defined, the program will search for a file labeled PURRBALL.DAT. Using
logical file names with an RPG program is discussed in more detail in the
RPG User’s Guide.
13.3 Record Formats

The records in a file can all be the same length (fixed) or of different
lengths (variable). Most RPG applications use fixed-length records.
13.4 File Types

Files can be used in four ways:
• As input to a program
• As output from a program
• As an update file in which the records are changed by the program
• To interact with the terminal screen via a WORKSTN device
This chapter describes the use of DISK files within an RPG program. The
Migration RPG Screen Format Reference Manual describes the use of a
WORKSTN device.
13–2
Using DISK Files
13.5 File Organizations

The organization of a file determines how the records in it are arranged.
RPG allows three different file organizations:
• Sequential
• Relative
• Indexed
The following sections describe these file organizations.
13.5.1 Sequential Organization

Sequential file organization is available on all types of devices. Sequential
files contain records in the order that they were written. The first logical
record in the file is always in the first physical record position, the second
logical record in the file is always in the second physical record position,
and so on. If the fourth logical record is to be accessed, it will be found
between the third and fifth physical records, as shown in Figure 13–1.
Figure 13–1 Sequential File Organization
1 2 3 4 5 6
Fourth record
Records can be retrieved from a sequential file either sequentially, by

reading through the entire file from beginning to end, or randomly, by
using relative record numbers or an addrout file.
13.5.2 Relative Organization

Relative file organization is available on disk devices only. A relative file
is a sequential file using fixed-length records. The relative record number
indicates the record’s position relative to the beginning of the file. The
relative record number of the first record is always 1. Each record written
is assigned to a specific location within the file. Records can be randomly
written to a relative file. For example, a record can be written to the
fourth location within a relative file by assigning it relative record number
4. Figure 13–2 depicts a relative file with no data in records 2 and 5.
13–3
Using DISK Files
Figure 13–2 Relative File Organization
1 2 3 4 5 6 Relative Record
Number
A B D C
Relative files can be accessed sequentially, randomly using the CHAIN

operation code, or randomly using an addrout file. When accessing a
relative file sequentially, empty cells are skipped. When accessing a
relative file randomly using the CHAIN operation, the indicator specified
in columns 54 - 55 of the Calculation specification will be set on if an
empty record is accessed.
By default, when a relative file is created under RMS, it contains no
records. If an RPG program expects a relative file to contain predefined
record locations, the file must be seeded with blank records before it is
accessed by the program. This is easily accomplished using a program or
procedure.
13.5.3 Indexed Organization

Indexed file organization is available on disk devices only. Each record in
an indexed file contains an index key value, as shown in Figure 13–3.
Figure 13–3 Indexed File Organization
Index Key Data

Value
| Record |
An index key value is a field within each record that is defined by its
relative location within the record and by its length. The index key value
is the primary means of locating records within the file. For example,
an employee’s badge number could be used as the index key value for
an employee record. The index key value in Figure 13–4 is the first six
characters in the record or 768979.
13–4
Using DISK Files
Figure 13–4 Index Key Value
Key Data
768979 Henry Albert
| Record |
Records can be retrieved from an indexed file sequentially, randomly using

index key values, randomly using an addrout file, or sequentially within
limits. See Section 13.6.1.3 for more information on accessing an indexed
file sequentially within limits.
13.6 File Access Methods

There are several ways of accessing the records within a file. File
access methods are dependent on the file’s organization. Chapter 4,
File Description Specification (F), contains detailed descriptions of all of
the possible file access combinations within an RPG program.
Although the organization of a file is not usually changed after it has been
created, the file access method can be changed. The method used depends
on how many records the file contains and how often the file is accessed.
Use the following guidelines in selecting a file organization and access
method:
• If all records in a file are processed from beginning to end (as in
a payroll application), use a sequential file and access the records
sequentially.
• If access to some or all records within a file is needed under changing
or unpredictable conditions (as in a transaction processing system),
use an indexed or relative file and access the records randomly.
The following sections describe file access methods and provide

programming guidelines for each.
13.6.1 Sequential Access

When accessing a file sequentially, each input operation retrieves the next
record in the file, regardless of the file organization, until either end-of-file
is reached or the program terminates. For an indexed file, records are
retrieved in the order of the specified key (the default is the primary key).
The following types of sequential access are possible within an RPG
program:
• Simple sequential access
• Sequential access by key
• Sequential access by limits
13–5
Using DISK Files
The following sections describe these types of sequential file access.
13.6.1.1 Simple Sequential Access

Simple sequential file access involves reading a file consecutively from
beginning to end. This type of access is possible with all file organizations:
sequential, relative, and indexed.
To specify sequential access for a file, the following entries must be made
in the File Description specification:
• Columns 7 - 14 (file name) - specify the name of the data file.
• Column 15 (file type) - specify I or U to indicate whether the file is to
be opened for input or for update.
• Column 16 (file designation) - specify P, S, D, or F to indicate whether
the input file is primary, secondary, demand, or full-procedural.
• Column 19 (record format) - specify F or V to describe the record
format (fixed-length or variable).
• Columns 24 - 27 (record length) - specify the length of fixed-length
records or the maximum length of variable-length records.
• Columns 40 - 43 (device code) - specify DISK.
• Columns 71 - 72 (external indicators) - external indicators U1 - U8 can
be specified to indicate whether the file is to be accessed. An external
indicator based file is accessed if the external indicator is on.
The following example specifies the name of a file, SHASTA, designated as

an input primary file with fixed-length records and a record length of 60
bytes:
Example 13–1 File Description specification for a primary sequential
file - Sequential file access
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
FSHASTA IPE F 60 DISK
13.6.1.2 Sequential Access by Key

Only indexed primary, secondary, demand, and full-procedural files can
be processed sequentially by key. RMS reads records in ascending key
sequence until it reaches end-of-file or the program terminates.
To specify sequential access by key for a file, the following entries must be
made in the File Description specification:
13–6
Using DISK Files

• Columns 29 - 30 (key length) - specify the length of the key field.
• Column 31 (record address type) - specify either blank, A, or P to
indicate that the index keys are in character (blank or A) or packed-
decimal (P) format.
• Column 32 (file organization) - specify I to indicate that the file is an
indexed file.
• Columns 35 - 38 (key location) - specify the starting character position
of the key field.
The following example shows how to specify a primary input file, ZONK
with fixed-length records 120 bytes long. The file organization is indexed
with its index key in packed-decimal data format.
Example 13–2 File Description specification for a primary sequential
file - Sequential access by key
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
FZONK IPE F 120 3PI 1 DISK
13.6.1.3 Sequential Access Within Limits

Indexed files can be processed sequentially within limits using one of two
methods:
• By creating a record-limits file that specifies a range of index keys in
each record.
• By using the SETLL operation.
Both methods permit the programmer to limit the records which the
program can access.
To access a file sequentially within limits, make the following entries in
the File Description specifications:
13–7
Using DISK Files
• Column 28 (access mode) - specify L to indicate that the indexed file is

to be processed sequentially within limits.
decimal (P) format.
indexed file.
of the key field.
The following example shows how to specify an input primary file,

EMPMST, with fixed-length records 180 bytes long. This file is to be
processed sequentially within limits. The file organization is indexed; the
key field is 8 bytes long and has a character format.
Example 13–3 File Description specification for a primary indexed file -
Sequential access within limits
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
FEMPMST IP F 180L 8AI 1 DISK
13.6.1.3.1 Using a Limits File

A limits file allows a low and high range to be specified via a file’s key field
before the file is accessed by the program. The low and high key values
are specified in the limits file, which is associated to the data file using an
Extension specification
When a program is processing an indexed file using key field limits, a
limits record is first read from the limits file. The program then begins
reading records sequentially from the indexed file, starting with the low
key value specified in the limits record. When the high limits value in
the limits record is reached, the program reads another limits records
and begins reading records from the indexed file again, starting with the
new low key value supplied by the limits file. A limits file can contain as
many limits records as the programmer desires. Processing of the program
will continue until the end of the limits file is reached or the program is
terminated.
The low and high limits values can overlap between limits records, and
the same limits values can be used more than once, allowing the same set
of records to be processed repeatedly.
13–8
Using DISK Files
Figure 13–5 presents an example of how limits file processing works. The
first record in the record-limits file causes the program to retrieve those
records whose keys are greater than or equal to the low key (C) and less
than or equal to the high key (E). When the program reaches a record with
a key value greater than E or reaches end-of-file, it reads the next record
from the record-limits file to get a new low and high range. The second
record in the record-limits file causes the program to retrieve those records
whose keys are greater than or equal to the low key (A) and less than or
equal to the high key (D). The indexed file is processed until it reaches the
end of the record-limits file or the program terminates.
Figure 13–5 Sequential File Access Within Limits
Data File Record Limits

File
Key Data
A data C E First record
B data A D Second record
C data
D data High limit

Low limit
E data
F data
| Record |
Rules
• In the record-limits file, only one set of limits can be specified per
record.
• The record length of the limits file must be at least twice the length of
the indexed file key field.
• The low key must begin in character position 1, and the high key must
immediately follow the low key.
• The length of the high and low keys must be the same and must be
equal to the length of the key field in the file to be processed.
• If the key fields being used are numeric, the format of the fields in the
data file and the limits file do not have to match. For example, the
limits file could use a zoned-decimal or trailing numeric format while
the indexed file used a packed-decimal format. If the key formats
differ, the key field format must be indicated by an entry in column 31
of the File Description specifications and the unpacked length of each
field must match.
• Numeric keys cannot contain blanks; use leading zeros if it is
necessary to fill a numeric key field.
• Alphanumeric keys can contain blanks.
13–9
Using DISK Files
• If the key field being accessed by the limits file is a non-contiguous

key, the keys specified within the limits file must contain all of the
subfields which make up the key field in the data file.
• To access the record-address file from which limits records are read,
entries must be made in both the File Description and Extension
specifications. The limits file does not require any Input specifications.
To access a file sequentially within limits, the following entries must be

made in the File Description specifications for the record-limits file:
• Column 15 (file type) - specify I to indicate that the file is to be opened
for input.
• Column 16 (file designation) - specify R to indicate that the file named
in columns 7 through 14 is a record-limits file.
• Column 19 (record format) - specify F to describe a fixed-record format
(fixed-length or variable).
records.
• Column 31 (record address type) - specify either A, P, or blank to
decimal (P) format.
• Column 39 (extension) - specify E to cause the compiler to look for an
Extension specification.
When specifying a limits file, the following entries must be made in the
Extension specifications:
• Columns 11 - 18 (from file name) - specify the name of the record-limits
file.
• Columns 19 - 26 (to file name) - specify the name of the file to be
processed by the record-limits file.
The following example shows how to specify the File Description and
Extension specifications for processing a file sequentially within limits. In
the example, the limits file EMPLMT is associated to the indexed data file
EMPMST. The EMPMST file will be processed within the limits obtained
from the EMPLMT file.
13–10
Using DISK Files
Example 13–4 File Description and Extension specifications for a

primary indexed file - Sequential access within limits
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
FEMPLMT IRE F 16 8 EDISK
FEMPMST IP F 180L 8AI 1 DISK
E EMPLMT EMPMST
13.6.1.3.2 Using the SETLL Operation

Limits processing against an indexed file can also be accomplished using
the SETLL (Set Lower Limit) operation code in the Calculations section of
a program. The SETLL operation positions the record pointer within a file
at the record with a key that is greater than or equal to the key specified
in factor 1. The SETLL operation code is described in detail in Chapter 11,
Operation Codes.
The SETLL operation can only be performed against full-procedural and
demand indexed files that are being processed sequentially within limits.
The File Description specification for the SETLL file must have an F or D
in column 16 and an L in column 28.
Factor 1 of the SETLL operation is used to specify the key value that is to
be the lower-limit of the file. The entry must have the same format and
Factor 2 is used to specify the name of the file being read. The file must
be a full-procedural or demand indexed file being processed within limits.
The file name must match the name specified in columns 7 - 14 of the
File Description specification. When a SETLL operation is performed, the
file record pointer is set at the record with the key that is greater than
or equal to the key specified in factor 1. Subsequent READ, READE, and
READP operations will begin from that point. When end-of-file is reached
on a limits file, another SETLL operation can be used to reposition the
record pointer in the file.
A record-address file specifying a limits file and the SETLL operation
cannot be used with the same data file.
13–11
Using DISK Files
Example 13–5 Limits Processing - SETLL operation code usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H
FEMPMST IF F 132L 8AI 1 DISK
FREQUEST CD F 32 WORKSTN
.
.
.
IEMPMST AA 01
I 1 80BADGE
.
.
.
IREQUEST BB 02
I 1 80BADGE
.
.
.
C READ REQUEST 99
C N99 BADGE SETLLEMPMST
C N99 READ EMPMST 99
In this example, the SETLL operation is used to position a pointer in the

EMPMST file based on an employee badge number. The user enters
a badge number via a workstation into the REQUEST record. The
value is placed in the field BADGE. The field BADGE is used by the
SETLL operation to position the file pointer for the subsequent READ
operation. Note that SETLL and READ operations for the EMPMST file
are conditioned by indicator 99. If the workstation read processes an
exception, indicator 99 be turned on and the following SETLL and READ
operations will not be performed.
13.6.2 Random Access

Accessing records randomly allows records to be retrieved or written
anywhere in a file. To do this, the record location must be specified using
one of the following methods:
• Relative record numbers
• Keys
• An addrout file
The methods available to randomly access a file depend upon the

organization of the file. The following sections describe the methods
which can be used for random file access.
13.6.2.1 Random Access by Relative Record Number

Sequential and relative files can be accessed randomly by specifying the
relative record number that identifies the desired record relative to the
beginning of the file. For example, the relative record number for the fifth
record is 5. Accessing a sequential file using this method requires that the
file contain fixed-length records and that the file reside on disk.
13–12
Using DISK Files
To access a file randomly by relative record number, the following entries

must be made in the File Description specifications:
• Column 16 (file designation) - specify C or F to indicate whether the
file named in columns 7 through 14 is a chained or full-procedural file.
format (fixed-length or variable). Sequential files must use fixed-length
records.
• Column 28 (mode) - specify R to cause the program to access the file
randomly, using a relative record number.
The following entries must be made in the Calculation specifications to

access the file randomly using a relative record number:
• Columns 18 - 27 (factor 1) - specify the relative record number of the
record which is to be retrieved.
• Columns 28 - 32 (operation code) - specify the CHAIN operation code.
Use an indicator in columns 54 - 55 to signal a non-existant record
condition for a relative file. Otherwise, attempting to use the CHAIN
operation code to randomly access a non-existant record will cause a
run-time error.
• Columns 33 - 42 (factor 2) - specify the name of the file that contains
the record which is to be retrieved.
The following example depicts how random access by relative record

number can be used. In the example, the primary file CHKLST is
processed sequentially. After each record from the CHKLST file is read,
the ITMNUM field is used to CHAIN to the INVENTRY file (line 130) and
obtain the INVENTRY record. The QTYSLD field is then updated using
an EXCPT output operation (lines 150 - 190) and the transaction is logged
on a report (lines 330 - 360).
Note the use of the record-not-found indicator, 50. If 50 is turned on, the
exception output (lines 150 - 190) is not performed and a line indicating
the error is printed in the report (lines 370 - 390).
13–13
Using DISK Files
Example 13–6 Random access by relative record number
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
00001H
00010FCHKLST IPE F 10 DISK
00020FINVENTRYUC F 120R DISK
00040 *
00050ICHKLST AA 01
00060I 1 50ITMNUM
00070I 6 100QTY
00080IINVENTRYAB 02
00090I 1 50ITMNUM
00100I P 21 250QTYSLD
00110I P 26 300VALUE
00120 *
00130C ITMNUM CHAININVENTRY 50
00140C *IN50 IFNE ’1’
00150C ADD QTY QTYSLD
00160C VALUE MULT QTY SALE 70
00170C SETON 40
00180C EXCPT
00190C SETOF 40
00200C END
00210 *
00220OINVENTRYE 40
00230O ITMNUM 5
00240O QTYSLD 25P
00260O OR OF
00270O 22 ’STORE PURCHASES’
00280OREPORT H 1P
00290O OR OF
00300O 06 ’ITEM #’
00310O 22 ’QUANTITY SOLD’
00320O 30 ’PRICE’
00330O D 01N50
00340O ITMNUM 05
00350O QTYSLD 18
00360O SALE 1 31 ’$’
00370O D 01 50
00380O ITMNUM 05
00390O 20 ’ITEM NOT FOUND’
13.6.2.2 Random Access by Key

Records can be retrieved randomly from an indexed file by specifying their
index keys. Only indexed files specified as chained or full procedural can
be accessed randomly by key.
To access a file randomly by key, the following entries must be made in its
File Description specification:
• Column 16 (file designation) - specify C or F to indicate whether the
file named in columns 7 - 14 is a chained or full-procedural file. If
the file is using a non-contiguous key, it must be designated a full
procedural file (F).
13–14
Using DISK Files

• Column 28 (mode) - specify R to access records randomly using index
key values.
• Columns 29 - 30 (key length) - specify the length of the key field. If a
non-contiguous key is being used, specify the total length of all of the
key segments.
decimal (P) format.
indexed file.
of the key field. If the key is non-contiguous, specify EXTK.
• Columns 68 - 69 can be used to specify an alternate key (01 - 99). If
the columns are left blank, the compiler will assume that the primary
key (00) is being described.
The CHAIN operation code is used to randomly access an indexed file.

The following entries must be made in the Calculation specifications to
describe a CHAIN operation:
• Columns 18 - 27 (factor 1) - specify the index key of the record to be
retrieved. This can be a data field or a literal.
• Columns 28 - 32 (operation code) - use the CHAIN operation code. The
specified record can be read from the file either during detail-time or
total-time calculations.
• Columns 33 - 42 (factor 2) - specify the name of the file to be processed.
• Indicators can be specified in columns 54 - 55 and 56 - 57 to indicate
end-of-file and error conditions, respectively.
The CHAIN operation code is described in detail in Chapter 11, Operation

Codes.
The following example randomly accesses the indexed file GROCER using
keys. The primary input file STORES provides the keys in the field ITEM.
The ITEM field is then used to chain into the GROCER file to pull the
record with the same key. If the record is not found, indicator 50 is turned
on. Information retrieved from the GROCER file is placed in the output
file REPORT.
13–15
Using DISK Files
Example 13–7 Random access by key
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
00010FSTORES IP F 130 DISK
00020FGROCER IC F 100R10AI 1 DISK
00030FREPORT O F 30 PRINTER
00040ISTORES AA 01
00050I 1 11 STORE
00060I 12 210ITEM
00070IGROCER AB 02
00080I 1 100REC
00090I 11 130COUNT
00100I 14 17 VALUE
00110C ITEM CHAINGROCER 50
00120C 50 SETON LR
00140O 22 ’STORE PURCHASES’
00150O D 01N50
00160O STORE 14
00170O COUNT 20
00180O VALUE 27
00190O D 01 50
00200O ITEM 10
00210O 25 ’ITEM NOT FOUND’
13.6.2.3 Random Access by Addrout File

Records in sequential, relative, or indexed files can be accessed using an
address output (addrout) file. Addrout files are created by the OpenVMS
Sort/Merge Utility using the /PROCESS=ADDRESS qualifier and contain
record addresses rather than full data records. The addrout file can then
be accessed by a program and the record address information used to
select records from the actual data file.
Using addrout files provides the following advantages:
• Improved sort performance
• Original file is unchanged
• Smaller output file
Figure 13–6 shows how an addrout file is created from a data file using
the SORT/PROCESS=ADDRESS command. The SORT/MERGE Utility is
discussed in detail in the OpenVMS SORT/MERGE Utility Manual.
13–16
Using DISK Files
Figure 13–6 Creating an Addrout File
Data File ADDROUT File
A data 00143 Address of A
C data 94837 Address of B
SORT/PROCESS=ADDRESS/KEY=(POS:1,SIZ:1) −
FUZZ.DAT ADDROUT.DAT
D data 47382 Address of C
B data 10382 Address of D
Each record in the addrout file corresponds to a record in the original

file. The addresses of the records are referred to as Record File Addresses
(RFA’s) by RMS. For additional information on RFA’s, see the OpenVMS
Record Management Services Reference Manual.
When accessing a data file using an addrout file, the program first reads a
record from the addrout file. It then uses the record address contained in
the addrout record to retrieve a record from the data file. The addrout file
is processed sequentially by the program, while the corresponding data file
is processed randomly by record address.
Using an addrout file to access a data file requires a File Description and
Extension specification for the addrout file and a File Description and
Input specifications for the data file. No Input specifications are required
for an addrout file.
The following entries must be made in the addrout File specification:
• Column 15 (file type) - specify I to indicate that the file is to be opened
for input.
• Column 16 (file designation) - specify R to indicate that the file named
in columns 7 - 14 is an addrout file.
• Column 19 (record format) - specify F to describe a fixed-length format.
• Columns 24 - 27 (record length) - specify 6 because record addresses
are always 6 bytes in length. NOTE: An entry of 3 is also acceptable
and will be translated by the compiler to 6. The entry of 3 is
supported as a compatibility feature for porting IBM System/36 RPG
II applications.
• Columns 29 - 30 (key length) - specify 6 because key addresses are
always 6 bytes in length. NOTE: An entry of 3 is also acceptable and
will be translated by the compiler to 6. The entry of 3 is supported as
a compatibility feature for porting IBM System/36 RPG II applications.
• Column 31 (record address type) - specify I to indicate that this is an
addrout file.
13–17
Using DISK Files
• Column 32 (file organization) - specify T to indicate an addrout file.

• Column 39 (Extension) - specify E to indicate that an Extension
specification is associated with this File Description specification.
The following entries are required in an Extension specification to

associate the addrout file to a data file:
• Columns 11 - 18 (from file name) - specify the name of the addrout
file as it was specified in columns 7 - 14 of its File Description
specification.
• Columns 19 - 26 (to file name) - specify the name of the data file to be
processed by the addrout file as it was specified in columns 7 - 14 of its
File Description specification.
The following entries are required in the File Description specification for
the data file which is associated to the addrout file:
be opened for input or update.
• Column 16 (file designation) - specify P or S to indicate that the file
named in columns 7 - 14 is primary or secondary.
• Column 28 (mode) - specify R to indicate random record access.
• Columns 29 - 30 (key length) - specify the length of the key field if an
indexed file is being accessed.
• Column 31 (record address type) - specify I to cause the program to
access the file according to the addrout file.
• Column 32 (file organization) - specify I if an indexed file is being
accessed.
The following example depicts the sort command used to create an addrout
file and a program which uses the addrout file. The sort command uses the
/PROCESS=ADDRESS qualifier to create an address output file ordered
by zip code. The program then uses the addrout file to read the data file
TOWNINFO and produce a listing of towns by zip code. Note that both
13–18
Using DISK Files
the addrout and data file are defined in the File Description specificiations
and that an Extension specification ties the two files together.
Example 13–8 Random access by addrout file
$ SORT/PROCESS=ADDRESS/KEY=(POS:26,SIZ:5) -
SYS_FILE:TOWNINFO.DAT SYS_SCRATCH:ADDROUT.DAT
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H
FADDROUT IRE F 6 6IT EDISK
FTOWNINFOIP F 120R 6II 30 DISK
E ADDROUT TOWNINFO
ITOWNINFOAA 01
I 1 12 TOWN
I 13 14 STATE
I 15 25 COUNTY
I 26 30 ZIP
OREPORT H 202 1P
O OR OF
O 12 ’TOWN LIST’
O UDATE Y 70
O PAGE 80
OREPORT D 01
O TOWN 12
OREPORT D 01
O COUNTY 11
OREPORT D 3 01
O STATE 02
O ZIP 10
13.6.3 Sequential Access and Random Access by Key

A full-procedural file is defined by an F in column 16 of the File
Description specification and allows a file to be read both randomly and
sequentially. Only indexed files can be defined as full-procedural files.
A full-procedural file can be read randomly using the CHAIN operation
and sequentially using the READ, READE, and READP operations. At
least one CHAIN, READ, or READP operation must be coded in the
Calculations section of a program to retrieve data from a full-procedural
file.
To specify a full-procedural file, make the following entries for the file in
its File Description specification:
• Column 15 (file type) - specify I or U to indicate that the file is to be
opened for input or update.
• Column 16 (file designation) - specify F to indicate a full-procedural
file.
13–19
Using DISK Files

decimal (P) format.
indexed file.
of the key field. If the key is non-contiguous, specify EXTK.
• Columns 68 - 69 can be used to specify an alternate key (01 - 99). If
the columns are left blank, the compiler will assume that the primary
key (00) is being described.
The following example specifies the full-procedural file FPFJ01 to be

accessed by a CHAIN operation with the key specified in FPFI01. The file
FPFJ01 is then processed sequentially from that point on.
Example 13–9 Random and sequential access using a full-procedural
file
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FFPFJ01 IF F 80L 5AI 2 DISK
*
IFPFJ01 XX 01
I 1 1 XSTAT
I 2 6 KEYFLD
I 7 11 FLD1
I 12 16 FLD2
*
.
.
.
*
C KEYFLD CHAINFPFJ01 50
C 50 GOTO END
*
C LOOP TAG
C READ FPFJ01 90
C 90 GOTO END
.
.
.
*
C END TAG
C SETON LR
*
.
.
.
13–20
Using DISK Files
13.7 Creating Files

There are a variety of ways to create files with sequential, relative, and
indexed organizations. Sections 13.7.1 through 13.7.3 describe how to
create files using a RPG program.
13.7.1 Creating Sequential Files

Sequential files are created by writing consecutive records to an output
file. After a sequential file is created, it can be used as an input file, an
update file, or an output file with the ADD option.
To create a sequential file, make the following entries in the File
Description specification:
• Column 15 (file type) - specify O to indicate the creation of an output
file.
• Columns 24 through 27 (record length) - specify the length of fixed-
length records or the maximum length of variable-length records.
Example 13–10 Creating a sequential file
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H
*
FOUTI24 IP F 24 DISK
FOUT60A O F 24 DISK
*
IOUTI24 AA 01
I 1 3 PN
I 4 10 PNAME
I 11 12 WHOUSE
I 13 17 COLOR
I 18 200WEIGHT
I 21 240QTY
*
OOUT60A D 01
O PN 3
O PNAME 10
O WHOUSE 12
O COLOR 17
O WEIGHT 20
O QTY 24
13–21
Using DISK Files
Example 13–10 (Cont.) Creating a sequential file
This example demonstrates how to create a sequential file. During

program startup, the sequential output file OUT60A.DAT will be created.
Data is read from the input file OUTI24.DAT and written to OUT60A.DAT.
13.7.2 Creating Relative Files

A relative file can be created by specifying a chained output file. To do
this, make the following entries in its File Description specification:
file.
• Column 16 (file designation) - specify C to indicate that the file named
in columns 7 through 14 is a chained file.
• Column 19 (record format) - specify F to describe a fixed-length format.
Relative files must use a fixed-length format.
• Column 28 (mode) - specify R to cause RPG to load a relative file.
Example Example 13–10 can also be used to create a relative file. Relative
files must always use a fixed-length record format. To add records to
specific locations within a relative file, the file must first be populated with
records.
13.7.3 Creating Indexed Files

An indexed file can be created either in unordered key sequence or in
ordered key sequence. If an unordered sequence is specified, records can
be written to an indexed file in any order, regardless of the key sequence.
If an ordered sequence is specified, records must be written in the order
of their key; the order must be ascending. After the file is created, RMS
sorts the index keys in ascending order, regardless of the order in which
they were written.
To create an indexed file in ordered sequence, make the following entries
in its File Description specification:
file.
13–22
Using DISK Files

• Columns 29 and 30 (key length) - specify the length of the key field.
• Column 31 (record address type) - specify either A, or P to indicate
that the index keys are in character (A) or packed decimal (P) format.
• Column 32 (file organization) - specify I to indicate an indexed file.
• Columns 35 through 38 (key location) - specify the starting character
position of the key field.
Example 13–11 Creating an indexed file
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H
*
FOUTI24 IP F 24 DISK
FOUT60I O F 24 3AI 1 DISK
*
IOUTI24 AA 01
I 1 3 PN
I 4 10 PNAME
I 11 12 WHOUSE
I 13 17 COLOR
I 18 200WEIGHT
I 21 240QTY
*
OOUT60I D 01
O PN 3
O PNAME 10
O WHOUSE 12
O COLOR 17
O WEIGHT 20
O QTY 24
This example demonstrates how to create a single key indexed file. During
program startup, the indexed output file OUT60I.DAT will be created. The
file will contain a single ascending key. The key will start in position 1
and have a length of 3 characters. The program reads data from the input
file OUTI24.DAT and writes it to the indexed file OUT60I.DAT.
By default Migration RPG creates indexed files with a primary key that
does not allow duplicates. If duplicate primary keys are desired, or if the
file needs to be defined with additional keys, create the file using the DCL
CREATE utility with the /FDL parameter. Data can then be added to
the file by defining is as an output add file (A in column 66 of the File
specification).
13–23
Using DISK Files
13.8 Adding Records to Files

After creating a file, it may be necessary to add new records to the file.
Records can be added to a file during detail-time or total-time output, or
by using exception output. Sections 13.8.1 through 13.8.3 explain how to
add records to files on the basis of their file organization.
13.8.1 Adding Records to a Sequential File

Because the location of each record in a sequential file is fixed in relation
to all others, there is no unused space where a new record might be
inserted. Therefore, new records can only be added to the end of a
sequential file.
To add a record to the end of a sequential file, make the following entries
in its File Description specification:
• Column 15 (file type) - specify O to indicate the creation of a new
record.
• Column 66 (file addition) - specify A to cause RPG to add new records
to the file.
The following entries must alse be made in the file’s Output specification:
• Columns 7 through 14 (file name) - define the output file name.
• Columns 16 through 18 - specify ADD to identify the record to be
added.
Example 13–12 Adding records to a sequential file
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
H
*
FINFO IP F 80 DISK
FLOG O F 80 DISK A
*
IINFO AA 01
I 1 80 DATA
*
OLOG DADD 01
O DATA 80
13–24
Using DISK Files
Example 13–12 (Cont.) Adding records to a sequential file
This example demonstrates how to add records to a sequential file. Data

from the file INFO is appended to the file LOG. The A in column 66 of the
LOG File specification signifies that the file is an output add file. ADD is
required in columns 16 - 18 of the LOG Output specification to allow new
records to be added to the file.
13.8.2 Adding Records to a Relative File

To add a new record to a relative file, either specify the relative record
number of an empty cell or add the record at the end of the file.
To add records to empty cells in a relative file, make the following entries
for the file in its File Description specification:
• Column 15 (file type) - specify I or U to indicate that the file is to be
opened for input or update.
• Column 16 (file designation) - specify C or F to indicate a chained or
full-procedural file.
• Column 28 (mode) - specify R to access records randomly, using a
relative record number.
• Column 66 (addition) - specify A to add records to the file.
Make the following entry in the Output specification:

• Columns 16 through 18 - specify ADD to identify the record to add.
13.8.3 Adding Records to an Indexed File

If the file is an indexed file, records can be added at any location. The key
values for the new records are placed in the index and the entire index is
sorted in ascending sequence.
Note: When adding records to an indexed file, "A" cannot be specify in
column 66 (file addition) of the File Description specification for
13–25
Using DISK Files
indexed files processed sequentially within limits or processed by

an addrout file.
New records can be added to an indexed file while processing the file
by specifying an "A" in column 66 (file addition) of the File Description
specification. The file can be an input or update file that is processed
sequentially or randomly. To only add records, specify an output file.
Make the following entries in the Output specification:
• Columns 16 through 18 - specify ADD to identify the records to be
added.
Example 13–13 Adding records to an indexed file
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
H
*
FNEWDATA IP F 80 DISK
FMASTER UC F 80R 5AI 2 DISK A
*
INEWDATA AA 01
I 1 1 STATUS
I 2 6 KEY
I 7 80 DATA
*
IMASTER XX
*
C 01 KEY CHAINMASTER 99
*
OMASTER DADD 01N99
O STATUS 01
O KEY 06
O DATA 80
This example demonstrates how to add records to an indexed file. Data

from the file NEWDATA is added to the file MASTER. The A in column
66 of the MASTER File specification signifies that the file allows records
to be added. ADD is required in columns 16 - 18 of the MASTER Output
specification to allow new records to be added to the file.
Note the use of the CHAIN operation in the Calculation specifications to
ensure that the program does not attempt to output data to a record that
already exists in the MASTER file.
13.9 Updating Records in Files

Migration RPG allows records to be updated in primary, secondary,
demand, full-procedural, or chained files. RPG allows record updates
in a sequential file only if the records are of fixed length. Records can be
updated in a primary or secondary file only once during the program cycle
at detail time. Unlike other types of update files, records in a chained,
full-procedural, or demand file can be updated at detail time or at total
time.
13–26
Using DISK Files
To update a record, retrieve the record to change, change the contents, and
then write the record back to the file. Only the fields to be changed need
to be specify in a record. The remainder of the record is rewritten using
the data that was read into the input buffer. A data structure can be used
to update a record instead of outputting individual fields.
Example 13–14 Updating records in an indexed file
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H
*
FTRANSACTIP F 25 DISK
FMASTER UC F 80R21AI 1 DISK
*
ITRANSACTAA 01
I 1 20 NAME
I 21 25 NEW#
*
0010 IMASTER BB 10 1 CA
0020 I CC 20 1 CB
0030 I DD 99
*
C N01 GOTO END
*
* Update record type 10.
*
C MOVEL’A’ KEY 21
C MOVE NAME KEY
C KEY CHAINMASTER 99
C N99 EXCPT
*
* Update record type 20.
*
C MOVEL’B’ KEY
C MOVE NAME KEY
C KEY CHAINMASTER 99
C N99 EXCPT
*
C END TAG
*
OMASTER E 01 10
O NEW# 40
OMASTER E 01 20
O NEW# 60
This example demonstrates accessing and updating two types of records

in the file MASTER. The record type on line 10 is identified by an "A" in
column 1. The record type on line 20 is identified by a "B" in column 1.
Line 30 serves as a catch-all should the file contain records that do not
begin with "A" or "B". The field NEW# is output to different locations
based on the record type.
To update the records in a relative or indexed file and simultaneously add

new records, make the following entries for the file in its File Description
specification:
• Column 15 (file type) - specify U to indicate that the file is to be opened
for update.
• Column 66 (file addition) - specify A to add new records to the file.
13–27
Using DISK Files
Define both Input and Output specifications for the file to be updated.
Enter ADD in columns 16 through 18 of those Output specifications that
identify the records to be added. The output records without ADD in
columns 16 through 18 identify those records to be updated.
Records in an indexed file can be randomly updated by key, sequentially,
or both randomly and sequentially if the file is defined as a full-procedural
file. To specify an indexed full-procedural file to be processed in the
update mode, make the following entries for the file in its File Description
specification:
• Column 15 (file type) - specify U to indicate that the file is to be opened
for update.
• Column 16 (file designation) - specify F to indicate a full-procedural
file.
• Column 32 (file organization) - specify I to indicate an indexed file.
13.10 Deleting Records from Files

Records can only be deleted from files defined as update or full procedural.
To prevent the unintentional deletion of records, perform the following
steps:
• Retrieve the record.
• Evaluate its contents.
• Based on the results of the evaluation, set an indicator to control
deletion of the record.
The last record retrieved from the file is the one that is deleted when
DEL is specified in columns 16 - 18 of the Output specification. There is
no need to describe any fields in the output record because the operation
deletes the entire record.
Example 13–15 Deleting records from an indexed file
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H
*
FDELETE IP F 20 DISK
FMASTER UC F 80R20AI 2 DISK
*
IDELETE AA 01
I 1 20 NAME
*
IMASTER BB
*
C 01 NAME CHAINMASTER 99
C N99 EXCPTREMOVE
*
OMASTER EDEL REMOVE
13–28
Using DISK Files
Example 13–15 (Cont.) Deleting records from an indexed file
This example demonstrates how to delete a record from a file. A record

is read from the file DELETE. The field NAME is used to CHAIN to the
associated record in the MASTER file. If the MASTER record is found,
it is deleted. Note the use of the EXCPT name REMOVE to control the
delete function in the Output specifications.
13.11 Processing Files with Matching Records

Matching fields can be used with primary and secondary files to check the
sequence of records and to define the order in which records are selected
from multiple files.
To use matching fields to verify that the records in the file are in sequence
(either ascending or descending), define one or more fields to be checked
by specifying a matching field value (M1 through M9) in columns 61 and
62 in the Input specification. Then, the program checks the sequence by
comparing the matching field of one record with the matching field of the
previous record. If the field is out of order, a run-time error occurs.
13.11.1 Checking Record Sequence for One Record Type

Designate a record sequence by specifying A or D (ascending or
descending) in column 18 of the File Description specification. Assign
a matching field value (M1 through M9) to one or more of the fields to be
used as matching fields in columns 61 and 62 (matching field) of the Input
specification. If more than one matching field is specified, assign M9 to
the most important field. The program considers all matching fields as one
contiguous field with the M9 field in the leftmost position, next to the M8
field, and so on, until it reaches M1, even though the fields may not be
adjacent in the record or in numeric (M9 through M1) order.
13.11.2 Checking Record Sequence for More Than One Record Type
The fields in a record of one type can be in a different order than the
fields in other record types in the same file. For example, in a payroll file
consisting of two different record types, one type represents commission
payment and the other type represents salary. All employee records are
to be in ascending sequence according to district (DSTRCT). Records
in a district are to be in ascending sequence according to department
and employee number. Therefore, three fields (DSTRCT, DEPT, and
EMPNUM) must be checked in each record. The matching field value M3
is assigned to DSTRCT, the most important field; M2 is assigned to DEPT,
the next most important field; and M1 is assigned to EMPNUM, the least
important field. Refer to the following example:
13–29
Using DISK Files
Example 13–16 Declaring matching record fields
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
IPAYROLL AA 01 80 CC
I 1 3 DEPT M2
I 6 7 DSTRCT M3
I 14 152COMM
I 25 27 EMPNUM M1
I BB 02 80 CS
I 1 3 DEPT M2
I 8 9 DSTRCT M3
I 13 172SALARY
I 25 27 EMPNUM M1
First, the program determines the record type. Then, it looks at the
matching fields for the same record type.
In the preceding example, the same three matching fields (DSTRCT,
DEPT, and EMPNUM) appear in both record types and are the same
length.
The length of matching fields assigned to the same match code must be
the same length for each record type. Table 13–1 shows that this is true
for the previous example:
Table 13–1 Matching Field Lengths

Record Matching Field Field
Type Field Location Length
first DSTRCT 6 to 7 2
DEPT 1 to 3 3
EMPNUM 25 to 27 3
8 <— total
second DSTRCT 8 to 9 2
DEPT 1 to 3 3
EMPNUM 25 to 27 3
8 <— total
Matching fields need not be specified for all the record types in a file.
13.11.3 Using Matching Fields with Field-Record-Relation Indicators

Although there may be different record types in a file, the fields for each
record type are often the same. Many fields have the same name, contain
the same data, and are in the same character positions for all the record
types in a file. When only a few fields differ, more than one record type
can be described in an OR relationship. Refer to the following example:
13–30
Using DISK Files
Example 13–17 Using OR operation in an Input specification
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
I OR 02 80 CS
Specify common fields only once because they apply to both record types.
The field-record-relation indicators specified in columns 63 and 64 of the
Input specification identify the fields unique to a particular record type.
Therefore, the COMM field in the following example is associated with
record type 01 and the SALARY field is associated with record type 02.
The DSTRCT, DEPT, and EMPNUM matching fields are used in checking
the sequence of the records in the PAYROLL file, and the matching-
field values M1, M2, and M3 are described only once in columns 61 and
62 without any field-record-relation indicators in columns 63 and 64.
Therefore, the matching fields and their values apply to both record types
(01 and 02) as shown in the following example:
Example 13–18 Matching record fields and field-record-relation
indicators
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
I OR 02 80 CS
I 1 3 DEPT M2
I 8 9 DSTRCT M3
I 25 27 EMPNUM M1
I 14 152COMM 01
I 13 172SALARY 02
If one of the matching fields is in a different record position for each record
type, matching field entries must be assign, as shown in the following
example:
Example 13–19 Matching record fields with field-record-relation
indicators
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
*
I OR 02 80 CS
I 1 3 EMPNUM M1
I 20 21 DSTRCT M3
I 6 72COMM 01
I 10 12 DEPT M201
I 5 7 DEPT M202
I 10 142SALARY 02
For a 01 record type, matching field DEPT is in field location 10 - 12. For
a 02 record type, matching field DEPT is in field location 5 - 7.
13–31
Using DISK Files
13.11.4 Using Matching Fields to Process More Than One File

The processing of a primary file with one or more secondary files is called
multifile processing. In multifile processing without matching fields, RPG
first reads all the records from the primary file, then reads all the records
from each secondary file in the same order in which they are specified in
the File Description specification. By using matching fields, the program
can select the records from the secondary file before selecting the records
from the primary file, based on the value of their matching fields.
When using matching fields to process more than one file, the program
selects records according to the contents of the matching fields, as follows:
• One record is read from every file and the matching fields are
compared. If the records are in ascending sequence, the record
with the lowest matching field value is selected for processing. If
the records are in descending sequence, the record with the highest
matching field value is selected for processing.
• When a record is selected from a file that is then processed, the next
record from the file is read. The new record is then compared with the
other records not selected in the previous cycle.
Records with and without matching fields can be combined in the same
file. Records without matching fields are processed before records with
matching fields. If two or more of the records being compared have no
matching fields, selection of those records is determined by the priority of
their files, as follows:
• The records in primary files are processed before the records in
secondary files.
• The records in secondary files are processed in order of appearance in
the File Description specifications.
Table 13–2 shows that the matching fields from a primary file are
compared with the matching fields from a secondary file to select records
in ascending sequence. The letters represent the data in the matching
fields.
Table 13–2 Matching Primary and Secondary File Field Values

Record Number Primary File Secondary File
1 A B
2 C D2
3 D1 X
4 F Z
Figure 13–7 shows the logic flow when a program uses matching fields to
do multifile processing. A keyed list follows the figure.
13–32
Using DISK Files
Figure 13–7 Using Matching Fields For Multifile Processing
Primary File Secondary File

(1) Record 1 (2) Record 1
A B
Compare (3)
match fields. Process A
Cycle n
(4) Record 2
C
Compare (5)
match fields. Process B
Cycle n + 1
(6) Record 2
D2
Compare (7)
match fields. Process C
Cycle n + 2
(8) Record 3
D1
Compare (9)
match fields. Process D1
Cycle n + 3
13–33
Using DISK Files
Figure 13–7 (Cont.) Using Matching Fields For Multifile Processing
(10) Record 4
F
Compare (11)
match fields. Process D2
Cycle n + 4
(12) Record 3
X
Compare (13)
match fields. Process F
Cycle n + 5
Key to Figure 13–7:

1 The first record of the primary file is read and the matching field (A) is
located.
2 The first record of the secondary file is read and the matching field (B)
is located.
3 The contents of the matching field (A) of the first record in the primary
file are compared with the contents of the matching field (B) of the
first record in the secondary file. A is selected.
4 The second record of the primary file is read and the matching field (C)
is located.
5 The contents of the matching field (B) of the first record in the
secondary file are compared with the contents of the matching field (C)
of the second record in the primary file. B is selected.
6 The second record of the secondary file is read and the matching field
(D2) is located.
7 The contents of the matching field (D2) of the second record in the
secondary file are compared with the contents of the matching field (C)
of the second record in the primary file. C is selected.
8 The third record of the primary file is read and the matching field (D1)
is located.
secondary file are compared with the contents of the matching field
(D1) of the third record in the primary file. D1 is selected.
13–34
Using DISK Files
10 The fourth record of the primary file is read and the matching field (F)
is located.
secondary file are compared with the contents of the matching field (F)
of the fourth record in the primary file. D2 is selected.
12 The third record of the secondary file is read and the matching field
(X) is located.
13 The contents of the matching field (F) of the fourth record in the
primary file are compared with the contents of the matching field (X)
of the third record in the secondary file. F is selected. Because the
primary file is now at its end, the remaining records in the secondary
file (X and Z) are processed in order of appearance.
When the matching fields in a primary file match one or more of the
matching fields in the secondary files, RPG sets the matching-record (MR)
indicator on before detail-time calculations. The MR indicator can be used
to condition calculation and output operations for the record just selected.
The indicator remains on for one complete program cycle. It is set off if
the record selected for processing contains no matching fields. A record
selected using the FORCE operation code causes the MR indicator to
remain off for one program cycle while the forced record is processed.
RPG processes matching records for two or more files in the following
ways:
• When a record from the primary file matches a record from the
secondary file, the record from the primary file is processed before
the record from the secondary file is processed. The record-identifying
indicator that identifies the record type just selected is on at the time
the record is processed.
• When records from ascending files do not match, the program
processes the record with the lowest matching field content first.
• When records from descending files do not match, the program
processes the record with the highest matching field content first.
• A record type that has no matching field specification is processed
immediately after the previous record is processed. In this case, the
MR indicator is set off. If this record type is the first in the file, the
program processes this record first, even when it is not in the primary
file.
• The matching of records makes it possible to enter data from primary
records into their secondary records because the program processes
the record from the primary file before matching the record from the
secondary file. However, the transfer of data from the secondary record
to matching primary records can be done only when look-ahead fields
are specified.
In the following example, matching fields are used to combine a primary

file with two secondary files in ascending sequence. Record-identifying
indicators are assigned in the following way:
• 01 - Records from the primary file with matching fields
13–35
Using DISK Files
• 02 - Records from the primary file without matching fields

• 03 - Records from the first secondary file with matching fields
• 04 - Records from the first secondary file without matching fields
• 05 - Records from the second secondary file with matching fields
• 06 - Records from the second secondary file without matching fields
Example 13–20 Matching record fields in primary and secondary files
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456
H
*
FRECI99A IP AF 80 DISK
FRECI99B IS F 80 DISK
FRECI99C IS F 80 DISK
FOUTPUT O F 80 DISK
*
IRECI99A 01 80 C1
I 1 80 TEXT
I 1 2 MATCH M1
I 02 80 C2
I 1 80 TEXT
*
IRECI99B 03 80 C3
I 1 80 TEXT
I 1 2 MATCH M1
I 04 80 C4
I 1 80 TEXT
*
IRECI99C 05 80 C5
I 1 80 TEXT
I 1 2 MATCH M1
I 06 80 C6
I 1 80 TEXT
*
OOUTPUT D N1P
O TEXT 80
Table 13–3 lists the contents of the matching fields for all three files:
primary, first secondary, and second secondary. Field values with A after
the value represent values from the primary file. Field values with B after
the value represent values from the first secondary file. Field values with
C after the value represent values from the second secondary file.
Table 13–3 Matching Field Values

Record Primary First Secondary Second Secondary
Number File File File
1 none none 10C
2 none 20B 30C
3 20A 30B 50C
4 20A 30B 50C
5 40A 60B none
6 50A none 60C
13–36
Using DISK Files
Table 13–3 (Cont.) Matching Field Values

Record Primary First Secondary Second Secondary
Number File File File
7 none 70B 80C

8 60A 80B 80C
9 80A 80B none
Table 13–4 lists the steps involved in processing the files in Table 13–3
and those indicators that must be set on for the operation to occur.
Table 13–4 Processing Records with Matching Fields

Record Matching Field
Step Type Value Indicators for Processing
1 02 none Not MR and 02
4 05 10C Not MR and 05
5 01 20A MR and 01
6 01 20A MR and 01
7 03 20B MR and 03
8 03 30B Not MR and 03
9 03 30B Not MR and 03
10 05 30C Not MR and 05
11 01 40A Not MR and 01
12 01 50A MR and 01
14 05 50C MR and 05
15 05 50C MR and 05
17 01 60A MR and 01
18 03 60B MR and 03
20 05 60C MR and 05
21 03 70B Not MR and 03
22 01 80A MR and 01
23 03 80B MR and 03
24 03 80B MR and 03
25 05 80C MR and 05
26 05 80C MR and 05
13–37
Using DISK Files
13.12 Processing Files with Multiple Keys

The following program accesses a single indexed file that contains three
keys. The program reads the file sequentially by key. It uses three
different file specifications to define the three key fields. Note that the
three file names use identical fields, and that each file name uses a
different key to point to the same file. Also note the use of the same fields
by a data structure.
Example 13–21 Multikey file access
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
H
*
FIDXI01 IP F 24 4AI 21 DISK
FIDXJ01 IS F 24 3AI 1 DISK 01
FIDXK01 IS F 24 2AI 11 DISK 02
FIDX03A O F 24 DISK 01
*
IIDXI01 AA 01
I 1 3 PN
I 4 10 PNAME
I 11 12 WHOUSE
I 13 17 COLOR
I 18 200WEIGHT
I 21 240QTY
*
IIDXJ01 BB
I 1 3 PN
I 4 10 PNAME
I 11 12 WHOUSE
I 13 17 COLOR
I 18 200WEIGHT
I 21 240QTY
*
IIDXK01 CC
I 1 24 FIELDS
*
IFIELDS DS
I 1 3 PN
I 4 10 PNAME
I 11 12 WHOUSE
I 13 17 COLOR
I 18 200WEIGHT
I 21 240QTY
*
OIDX03A D N1P
O FIELDS 24
13.13 File Buffers

The RPG compiler creates one buffer for each file in a RPG program.
However, there are some programs in which input and output buffers for
the same file should be distinct.
As an example, consider a program that is sequentially reading an indexed
file and occasionally executing the ADD operation code in the file using
EXCPT processing at total time. At the beginning of the logic cycle, a
record is selected for input. (For this example, use the FOO record.) When
a control break occurs, the program does some total-time processing and
13–38
Using DISK Files
ends with an EXCPT operation on the same file. This results in a new
record being added to the file, for example the BAR record. Continuing
with the normal logic cycle, the program enters detail time and the record
selected for input has become the BAR record which was just written
instead of the expected FOO record. The same buffer is used for both
input and output. When the BAR record is written, the record buffer is
overwritten and its previous contents lost so that when it is time for field
extraction to occur, the wrong record is found.
There are a number of workarounds that can be used. The ADD records
could be written to a distinct output file and merged with the master files
outside of the application. Or, total-time processing can be used to save
the record to be written and set an indicator on. Then, during detail-time
processing, use the indicator to trigger the EXCPT operation. Because
the fields of the input record have been populated by this time, no conflict
occurs with a single record buffer.
The best alternative is to open two streams to the same file and have two
F specifications which essentially refer to the same file. Normal input
processing takes place using one stream and all ADD processing occurs on
the other stream. Because a record buffer is allocated for each file, two
buffers are created in this scheme, and no conflict occurs. Both files need
to use the file sharing option (S in column 68 of the F specifications) in
this case.
Only one update is allowed for each logic cycle for update files other than
demand and chained files.
13–39
14 Using Printer Output Files
Printer files give the programmer a quick and easy way to create
formatted reports. RPG provides the programmer with several features
which aid in report generation. Sections 14.2 and 14.3 describe these
features and explain how to use them.
Note: RPG printer files contain all the print control characteristics
required to properly format a report. The default DCL PRINT
command causes the insertion of a form-feed character when the
form nears the end of a page. In some cases, this may cause blank
pages to be inserted in the middle of a report. To suppress the
insertion of form-feed characters, use the /NOFEED qualifier on
the PRINT command when printing printer output files created by
RPG programs, or set the bottom margin of the form type being
used to 0 with the DCL command DEFINE/FORM.
$ PRINT/NOFEED PAYBACK.LIS
- or -
$ DEFINE/FORM/MARGIN=(BOTTOM=0) DEFAULT 0
14.1 Required Specifications

14.1.1 File Specification
To define a printer file, the programmer must code a File Description
specification and the associated Output specifications. Optionally, the
programmer can code a Line Counter specification to override the default
page size and overflow line number.
The following entries are required in the File Description specification.
• Columns 7 - 14 contain the name of the printer file to be defined.
• Column 15 must be an O to indicate the file is an output file.
• Column 19 can be an blank or F (default value) to indicate the records
in the file are fixed length.
• Columns 20 - 23 can be blank or the block length to be used when
writing records to the file. If entered, it must be a multiple of the
record length stated in columns 24 - 27. If blank, the block length is
defaulted to the record length.
• Columns 24 - 27 must contain the length of the records to be written
to the printer file.
• Columns 33 - 34 can be blank or specify one of the overflow indicators,
OA - OG or OV.
14–1
Using Printer Output Files
• Column 39 can be a blank or L. An L must be entered if the

programmer has coded a Line Counter specification for this printer
file.
• Columns 40 - 46 must contain the device name PRINT or PRINTER.
• Columns 71 - 72 can be blank or specify an external indicator (U1 -
U8) used to condition the printer file.
14.1.2 Line Counter Specifications

If the programmer wishes to change either the default page size (66) or
the overflow line (60), a Line Counter specification must be coded.
The following entries are required in the Line Counter specification. For
complete information on using Line Counter specifications, see Chapter 6,
Line Counter Specification (L).
• Columns 7 - 14 must contain the name of the printer file. This must
match the name of the printer file coded in columns 7 - 14 of the File
Description specification.
• Columns 15 - 17 must contain the number of lines per page. The page
size may range from 1 to 112 lines.
• Columns 18 - 19 must be FL to indicate that the entry in columns 15 -
17 is the form length.
• Columns 20 - 22 must contain the line number to be used as the
overflow line. The line number entered must be less than or equal
to the number of lines per page entered in columns 15 - 17. If the
line number entered is equal to the number of lines per page then an
overflow condition is not possible and overflow processing can never
occur.
• Columns 23 - 24 must be OL to indicate that the entry in columns
20 - 22 is the overflow line number.
14.1.3 Output Specifications

Output specifications are used to describe the records and fields in the
PRINT or PRINTER output file and the conditions under which data
is output. For complete information on using Output specifications, see
Chapter 9, Output Specification (O).
14.1.3.1 File Identification Entries

The following entries are required to describe a printer file output record.
• Columns 7 - 14 contain the name of the printer file to be defined.
• Columns 14 - 16 can be used to specify AND or OR conditions, which
are used to link output lines together, allowing more than three
conditioning indicators to be used to condition an output record.
• Column 15 indicates at which point in the RPG cycle the record is to
be written. The values allowed are H(heading), D(detail), T(total), or
E(exception).
14–2
• Column 16 indicates if the fetch overflow routine is to be used when

processing this record. For more information on using fetch overflow,
see Section 14.5.2.
• Column 17 indicates the number of lines to be spaced before the
record is printed. Spacing is defined as the number of lines the form
is advanced in the printer. The values allowed are 0 - 9 or blank. If a
blank is entered, the value is defaulted to 0.
• Column 18 indicates the number of lines to be spaced after the
record is printed. The values allowed are 0 - 9 or blank. If a blank
is entered, the value is defaulted to 1. A value of 0 means the form is
not advanced, which allows overprinting.
• Columns 19 - 20 indicate the line number the printer should advance
to before the record is printed. The values allowed are 01 - 99, A0 -
A9 (line 100 - 109), B0 - B2 (line 110 - 112), or blank. If a blank is
entered, no skipping takes place.
• Columns 21 - 22 indicate the line number the printer should advance
to after the record is printed. The values allowed are 01 - 99, A0 -
A9 (line 100 - 109), B0 - B2 (line 110 - 112), or blank. If a blank is
entered, no skipping takes place.
Note: See Section 14.4 for more information on line spacing and
skipping.
• Columns 23 - 31 can be used to specify indicators to condition the
output of the record. Up to three indicators can be specified on
an Output specification. Preceding an indicator with N causes the
condition to be valid only when the associated indicator is not on.
Use columns 23 - 25 to describe the first indicator, columns 26 - 28 to
describe the second indicator, and columns 29 - 31 to describe the third
indicator. Using the indicators in this way forms an AND relationship.
Use AND or OR codes in columns 14 - 16 if it is necessary to condition
an output record definition with more than three indicators.
• Columns 32 - 37 can specify an exception name if exception time
output is required (E in column 15); otherwise, they must be blank.
The EXCPT operation can specify the name in factor 2 of the
Calculation specification. This name is called an EXCPT name.
• All other columns must be blank.
14.1.3.2 Field Description Entries

The following describes the entries required to describe a field within a
printer file output record.
• Columns 23 - 31 can be used to specify indicators to condition the
output of the field. Up to three indicators can be specified on an
Output specification. Preceding an indicator with N causes the
condition to be valid only when the associated indicator is not on.
Use columns 23 - 25 to describe the first indicator, columns 26 - 28 to
describe the second indicator, and columns 29 - 31 to describe the third
indicator. Using the indicators in this way forms an AND relationship.
14–3
• Columns 32 - 37 can specify a field, data structure, array name, an

array or table element, or one of the following reserved words: PAGE,
PAGE1 - PAGE7, *PLACE, UDATE, UDAY, UMONTH, UYEAR,
$UDATE, $UDAY, $UMNTH, or $UYEAR. If the field description entry
is for a constant, then leave these columns blank.
• Column 38 can be used to specify an edit code.
• Column 39 indicates if the field is to be reset to blanks or zeros after
the output operation is complete. If the field should be reset, enter a B
in this column. A blank indicates that the field is not to be reset.
• Columns 40 - 43 are used to specify the end position of a field or
constant in the output buffer. The end position entered cannot exceed
the record length of the printer file. If these columns are left blank,
the RPG compiler will automatically calculate the field end position by
adding the field length to the end position of the previous field.
• Columns 45 - 70 can be used to specify an output constant or edit
word. An edit word can be used to modify an edit code specified in
column 38 or to define how data will be formatted when it is output.
• All other columns must be blank.
14.2 Using Special Words

RPG provides special words that enable the programmer to perform the
following kinds of formatting:
• Printing the date on every page using UDATE, UDAY, UMONTH,
UYEAR, $UDATE, $UDAY, $UMNTH, and $UYEAR.
• Printing a page number and incrementing the page number by one for
each new page using PAGE and PAGE1 - PAGE7.
• Repeating data fields in an output record using *PLACE.
For complete information on how to use these special words, see Chapter 9,
Output Specification (O).
14.3 Field Editing of Numeric Fields

The format in which a numeric field is printed is determined by the edit
code and/or the edit word specified. For more information on the use of
edit codes and edit words, see Chapter 9, Output Specification (O).
14.4 Spacing and Skipping Lines

The programmer can format a report by specifying the number of lines
to space or skip. Spacing is relative to the line currently being printed;
therefore, use spacing between detail lines in a report. Skipping lines
repositions the printer to an absolute line number; therefore, specify
skipping to format a report. For example, if overflow has been detected
and the programmer wants to skip to the top of a new page and print
headings, specify skip to line number 2. The output heading line
14–4
associated with that Output specification will be printed on the second

line of each page.
To specify the number of lines to space, make the following entries in the
Output specification:
• Column 17 (space before)—specifies the number of lines to be spaced
before printing a line.
• Column 18 (space after)—specifies the number of lines to be spaced
after printing a line.
To specify the number of lines to skip, make the following entries in the
Output specification:
• Columns 19 - 20 (skip before)—specifies the line number to skip to
before printing a line.
• Columns 21 - 22 (skip after)—specifies the line number to skip to after
printing a line.
If both spacing and skipping columns are made for the same line, RPG
formats the output in the following order:
1 Skip before
2 Space before
3 Print the output line
4 Skip after
5 Space after
When an OR line is specified for an output print record, the space and
skip entries of the preceding line are used. If space and skip requirements
differ from the preceding line, enter space and skip entries on the OR line.
Specifying a skip before entry past the overflow line causes RPG to set on
If a skip before entry is specified on the same line number that the printer
If a skip before entry is specified to a line number less than the current
line number, the printer advances to that line number on the next page.
Note: If the line printer listing of a printer output file includes an
unexpected blank page at the end of the file, use the DCL
PRINT/NOFEED command to prevent the default OpenVMS
printer settings from overriding the forms control information
embedded in an RPG printer file. Another fix for this problem is
to set the bottom margin of the form type being used to 0 with the
DEFINE/FORM command. For example:
DEFINE/FORM/MARGIN=(BOTTOM=0) DEFAULT 0
14–5
Example 14–1 prints TOP on line 1, TEST LINE on line 7, PRINT TWICE
FOR BOLDING on line 13, and the fields beginning on line 16.
Example 14–1 Sample Report Program using Spacing and Skipping
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
OREPORT H 1P
O 41 ’TOP"
O H 320411 1P
O 44 ’TEST LINE’
O H 0 1P
O 30 ’PRINT TWICE FOR BOLDING’
O H 15 1P
O 30 ’PRINT TWICE FOR BOLDING’
O D 1 N1P
O DESCR 18
O STOCK# 26
O ONHANDZ 31
O PRICE K 39 ’$’
Sample output from Example 14–1 might look like the following:
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
1 TOP
2
3
4
5
6
7 TEST LINE
8
9
10
11
12
13 PRINT TWICE FOR BOLDING
14
15
16 1 LB CARROTS VEG1MQ 47 $.79
17 6 PACK SODA DRNK2A 40 $1.48
18 1 LB BUTTER DAR0BT 38 $1.59
19 STEAK MET0 22 $3.15
20 HEAD LETTUCE VEG1WQ 63 $.35
14.5 Conditioning Output Lines

Although any type of indicator can be used to condition output, the first-
page (1P) and overflow indicators (OA - OG, OV) specifically condition
printer output. Sections 14.5.1 and 14.5.2 describe how these indicators
condition output.
14.5.1 Printing Lines Before Reading the First Record: First-Page Indicator
Use the indicator 1P to condition those heading lines which should be
printed before RPG processes the first record. The indicator 1P can
be used to condition entire records or individual fields within a record.
Specify the indicator 1P just like any other indicator in columns 24 - 25,
27 - 28, or 30 - 31 of the Output specification.
14–6
For complete information on how to use the indicator 1P, see Chapter 12,
Using Indicators, and Chapter 9, Output Specification (O).
14.5.2 Specifying Page Breaks: Overflow Indicator

Overflow occurs when the printer reaches the last line on a form on which
data is to be printed. The overflow condition can be handled in one of
three ways:
• By letting RPG handle the overflow condition automatically.
• By conditioning output to the printer file with overflow indicators.
• By specifying the fetch overflow routine when writing a record to the
printer file.
14.5.2.1 Automatic Handling of the Overflow Condition

If the programmer does not specify an overflow indicator for the printer
file (columns 33 - 34 of the File Description specification are blank), and
the fetch overflow routine has not been specified (column 16 of the output
record specification is not an "F"), then RPG will automatically handle the
overflow condition. In this case, when the overflow condition is detected,
RPG will advance the form to the top of the next page and continue
printing on the first line.
Unless the programmer has overridden the default form by specifying
a Line Counter specification for the printer file, line 60 is the default
overflow line.
14.5.2.2 Handling of the Overflow Condition Using Overflow Indicators

Overflow indicators are used to specify which of the lines in the printer
file are to be printed when the overflow occurs. These indicators (OA - OG,
OV) are used primarily to condition the printing of heading lines, but can
also be used to condition calculation operations and other types of output
lines. The programmer defines the overflow indicator to be used with the
printer file in columns 33 - 34 of the File Description specification. Only
one overflow indicator is allowed per printer file and an overflow indicator
cannot be shared by printer files.
RPG sets on an overflow indicator the first time an overflow condition
occurs for the current page. An overflow condition exists whenever one of
the following occurs:
• A line is printed on the overflow line.
• A line is printed past the overflow line.
• The overflow line is passed during a space operation.
• The overflow line is passed during a skip operation.
14–7
Rules
• Spacing past the overflow line sets the overflow indicator on.
• Skipping past the overflow line to any line on the same page sets the
overflow indicator on.
• Skipping past the overflow line to any line on the new page does
not set the overflow indicator on unless the skip is specified past the
overflow line on the new page.
• A skip to a new page specified on a line not conditioned by an overflow
indicator sets the overflow indicator off before the form advances to a
new page.
• An overflow indicator can appear on either line of an AND or an OR
relationship. In an AND relationship, the overflow indicator must
appear on the main specification line for that line to be considered
an overflow line. In an OR relationship, the overflow indicator can be
specified on either the main specification line or the OR line. However,
only one overflow indicator can be associated with one group of output
indicators.
• If an overflow indicator is used on an AND line, the line is not an
overflow line. In this case, the overflow indicator is treated like any
other output indicator.
• An overflow indicator cannot condition an exception line (E in column
15 of the Output specification), but can condition fields within the
exception record.
During a normal program cycle, RPG checks whether the overflow

indicator is set on only once, immediately following total-time output.
Detection of the overflow indicator causes the following operations:
• RPG prints all total lines conditioned by the overflow indicator.
• RPG prints those heading and detail lines conditioned by the overflow
indicator.
• Advancement to a new page does not happen automatically. Normally,
one of the overflow lines specifies a skip to the top of a new page.
• The overflow indicator is set off.
In Example 14–2, the length of a page is 15 lines. The overflow line is line
12. When the overflow line is reached, the overflow indicator is set on,
which conditions the heading line that prints the date, report title, and
page number at the top of each page.
14–8
Example 14–2 Sample Report Program using an Overflow Indicator
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
H
FINPUT IP F 80 80 DISK
FREPORT O F 132 132 OF LPRINTER
L*
LREPORT 15FL 12OL
I*
IINPUT NS 01
I 1 5 ZIP
I 10 150CEN30
I 16 210CEN40
I 22 270CEN50
I 28 330CEN60
I 34 390CEN70
I 40 450CEN80
I 46 47 STATE
I 48 59 COUNTY
I 63 74 TOWN
O*
OREPORT H 202 1P
O OR OF
O UDATE Y 12
O 47 ’SOUTHERN NEW HAMPSHIRE’
O 53 ’TOWNS’
O PAGE 77
O*
O D 1 01
O TOWN 13
O COUNTY 26
O STATE 30
O CEN80 J 38
O CEN70 J 46
O CEN60 J 54
O CEN50 J 62
O CEN40 J 70
O CEN30 J 78
14–9
A sample of the output from Example 14–2 might look like the following:
Example 14–3 Sample Output from Report using an Overflow Indicator
1 2 3 4 5 6 7
12345678901234567890123456789012345678901234567890123456789012345678901234567
12/14/1991 SOUTHERN NEW HAMPSHIRE TOWNS 1
Hampstead Rockingham NH 3,785 2,401 1,261 823 823 775
Kingston Rockingham NH 4,111 2,882 1,672 1,002 1,002 1,017
Litchfield Hillsborough NH 4,150 1,420 721 341 341 286
Newmarket Rockingham NH 4,290 3,361 3,153 2,640 2,640 2,511
Atkinson Rockingham NH 4,397 2,291 1,017 434 434 407
Rye Rockingham NH 4,508 4,083 3,244 1,246 1,246 1,081
Hollis Hillsborough NH 4,679 2,616 1,720 996 996 879
Peterborough Hillsborough NH 4,895 3,807 2,963 2,470 2,470 2,521
Raymond Rockingham NH 5,453 3,003 1,867 1,340 1,340 1,165

Plaistow Rockingham NH 5,609 4,712 2,915 1,414 1,414 1,366
Windham Rockingham NH 5,664 3,008 1,317 630 630 538
Seabrook Rockingham NH 5,917 3,053 2,209 1,782 1,782 1,666
Pelham Hillsborough NH 8,090 5,408 2,605 979 979 814
Amherst Hillsborough NH 8,243 4,605 2,051 1,174 1,174 1,115
Milford Hillsborough NH 8,685 6,622 4,863 3,927 3,927 4,068
Bedford Hillsborough NH 9,481 5,859 3,636 1,561 1,561 1,326
Hampton Rockingham NH 10,493 8,011 5,379 2,137 2,137 1,507
Exeter Rockingham NH 11,024 8,892 7,243 5,398 5,398 4,872

Goffstown Hillsborough NH 11,315 9,284 7,230 4,247 4,247 3,839
Londonderry Rockingham NH 13,598 5,346 2,457 1,429 1,429 1,373
Hudson Hillsborough NH 14,022 10,638 5,876 3,409 3,409 2,702
Merrimack Hillsborough NH 15,406 8,595 2,989 1,253 1,253 1,084
Derry Rockingham NH 18,875 11,712 6,987 5,400 5,400 5,131
Salem Rockingham NH 24,124 20,142 9,210 3,267 3,267 2,751
Portsmouth Rockingham NH 26,254 25,717 26,900 14,821 14,821 14,495
Nashua Hillsborough NH 67,865 55,820 39,096 32,927 32,927 31,463
Manchester Hillsborough NH 90,936 87,754 88,282 77,685 77,685 76,834
14.5.2.3 Handling the Overflow Condition Using Fetch Overflow

Because RPG only checks for the overflow condition after output of total
records, it is possible to print past the end of the form. This will occur
when the total number of detail, total, and/or exception lines to be printed
during a program cycle exceeds the available space left on the form. The
programmer can prevent this from happening by using the fetch overflow
routine when outputting the lines that would cause the program to print
past the end of the form.
The fetch overflow routine allows the programmer to alter the overflow
logic of the RPG program. Each time the fetch overflow routine is called,
the RPG program will check to see if the overflow indicator is on. If the
fetch overflow indicator is on, then the program will execute the fetch
overflow routine. When executed, the fetch overflow routine performs the
following operations:
• All total lines conditioned by the overflow indicator are printed.
14–10
• Heading and detail lines conditioned by the overflow indicator are

printed. Note: the forms will only be advanced to a new page if a
heading or detail line conditioned by the overflow indicator specifies a
skip to a line number which is less than the current print line.
• After printing the overflow lines, the line that specified the fetch
overflow is printed.
• RPG then prints any detail-time and total-time lines left for that
program cycle.
To request the fetch overflow routine, specify F (fetch overflow) in column

16 of the Output specification. When using the fetch overflow routine,
keep the following in mind.
Rules
• To fetch the overflow routine for each record in an OR relationship,
specify F (fetch overflow) in column 16 for each OR line.
• An overflow indicator cannot be specified in columns 23 - 31 on the
same line with F (fetch overflow) in column 16.
• The fetch overflow routine will not automatically cause the form to
advance to the top of the next page. The form will only be advanced if
a heading or detail line conditioned by the overflow indicator specifies
a skip to a line number which is less than the current print line.
To decide when to fetch the overflow routine, study all possible overflow
situations and count lines, spaces, and skips to determine what happens
when an overflow occurs.
14–11
In Example 14–4, all of the report detail is output at total time based on
the control break indicator L2. Since a large number of lines are output
at the same time, this could cause data to be printed past the end of the
form. To prevent this from occurring, the fetch overflow routine is called
every third or fourth line to check for the overflow condition.
Example 14–4 Sample Report Program using Fetch Overflow
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
H
FINPUT IP AF 234R I DISK
FADROUT IR AF 768 3 3IT EDISK
FUNITPRODIC F 256 256R 3AI 1 DISK
FPRINT O F 132 OF PRINTER
E ADROUT INPUT
E NUM 48 7 0
E NM1 12 7 0
E NM2 12 7 0
E NM3 12 7 0
E NM4 12 7 0
E CST 48 9 2
E CT1 12 9 2
E CT2 12 9 2
E CT3 12 9 2
E CT4 12 9 2
E YM 48 4 0
E YM1 12 4 0
E YM2 12 4 0
E YM3 12 4 0
E YM4 12 4 0
E COST 4 8 2
E USA 66 2
E INS 10 6 0
E MDL 10 3
E*
14–12
Example 14–4 (Cont.) Sample Report Program using Fetch Overflow

1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
IINPUT NS 01
I 2 04 MFGDTEL2
I 5 13 KEY
I 26 32 WRNTY#
I 35 400WWDATE
I 194 1970YRMM
I 227 232 WWTYPE
I 14 25 WWUMDL
I 14 16 MDL#
I 186 193 WWCM#
I 194 1990WWCMDT
I 101 120 PART1
I 101 102 FAIL2
I 101 104 FAIL4
I 101 101 FAIL1
I 121 124 FAIL24
I 227 232 WWFSE
I 87 920FAILDT
I 141 172 COST
I 173 1772HANDLG
I 178 1852FRT
I 1 10STST
I AB
IUNITPRODCZ
I 4 90MFDATE
I 4 50UNTYR
I 6 7 UNTMO
I 11 40 MDL
I 41 100 AMT
I 101 1060UNTPRD
I 107 1120UNTINS
I 121 1800INS
I DS
I 1 336 NUM
I 1 84 NM1
I 85 168 NM2
I 169 252 NM3
I 253 336 NM4
I 337 3400YYMM
I 337 3380YY
I 339 3400MM
I 341 3460DATE
I 341 3420YR
I 343 3440MO
I*
14–13

1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
I DS
I 1 432 CST
I 1 108 CT1
I 109 216 CT2
I 217 324 CT3
I 325 432 CT4
I DS
I 1 192 YM
I 1 48 YM1
I 49 96 YM2
I 97 144 YM3
I 145 192 YM4
I*
I UDS
I 1 3 FCDE
I 4 6 TCDE
I 7 9 LMDL#
I***
C*
C N99 EXSR FSTPAS
C N99 SETON 99
C L2 EXSR SETUP
C EXSR FAIL
C N61 GOTO END
C Z-ADDFAILDT DATE
C Z-ADDMO MM
C Z-ADDYR YY
C Z-ADD1 C1
C YYMM LOKUPYM,C1 50
C 50 ADD 1 NUM,C1
C 50 XFOOTCOST TMPCST 92
C 50 ADD HANDLG TMPCST
C 50 ADD FRT TMPCST
C 50 ADD TMPCST CST,C1
C END TAG
C*
CL2 60 ADD UNTINS TOTINS 60
CL2N60 Z-ADD1 X1 20
CL2N60 LMDL# LOKUPMDL,X1 50
CL2N60 50 ADD INS,X1 TOTINS
C**
CL2 XFOOTNM1 TNUM1 70
CL2 XFOOTCT1 TCST1 92
14–14

1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
C*
CSR SETUP BEGSR
C MOVE ’-’ USA
C MFGDTE CHAINUNITPROD 50
C MOVELMFDATE YYMM 40
C Z-ADDYYMM YM
C Z-ADD0 C1 20
C SETUP1 TAG
C ADD 1 C1
C C1 COMP 49 50
C 50 GOTO SETUP9
C Z-ADDYM,C1 YYMM
C C1 SUB 1 C2 20
C ADD C2 MM
C SETUP2 TAG
C MM SUB 12 TMP 20 50
C 50 ADD 1 YY
C 50 Z-ADDTMP MM
C 50 GOTO SETUP2
C Z-ADDYYMM YM,C1
C GOTO SETUP1
C SETUP9 ENDSR
C*
C FAIL BEGSR
C SETOF 61
C*
C FAIL2 COMP ’A1’ 61
C N61 FAIL2 COMP ’A2’ 61
C N61 FAIL2 COMP ’B1’ 61
C N61 FAIL2 COMP ’C1’ 61
C N61 FAIL1 COMP ’D’ 61
C ENDSR
C*
C FSTPAS BEGSR
C SETOF 60
C MOVE LMDL# MODEL 3
C LMDL# COMP ’ ’ 60
C 60 MOVE ’ALL’ MODEL
C ENDSR
C*
14–15

1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
OPRINT H 202 1P
O OR OF
O 24 ’48 MONTH DEFECT REPORT ’
O 65 ’PAGE-’
O PAGE Z 70
O 86 ’AS-OF-’
O UDATE Y 96
O 132 ’SAMPLE’
O TF 1 L2
O 20 ’INSTALLED’
O 30 ’MODEL#-’
O MODEL 33
O T 1 L2
O 3 ’MFG’
O 9 ’YR/MO’
O 16 ’UNITS’
O YM1,1 B 32 ’ 0/ ’
O YM1,2 B 47 ’ 0/ ’
O YM1,3 B 62 ’ 0/ ’
O YM1,4 B 77 ’ 0/ ’
O YM1,5 B 92 ’ 0/ ’
O YM1,6 B 107 ’ 0/ ’
O T 1 L2
O MFGDTE 3
O UNTYR ZB 6
O 7 ’/’
O UNTMO B 9
O TOTINSZB 15
O NM1,1 B 32 ’ , , 0 ’
O NM1,2 B 47 ’ , , 0 ’
O NM1,3 B 62 ’ , , 0 ’
O NM1,4 B 77 ’ , , 0 ’
O NM1,5 B 92 ’ , , 0 ’
O NM1,6 B 107 ’ , , 0 ’
O T 2 L2
O CT1,1 B 33 ’ , , 0. -’
O CT1,2 B 48 ’ , , 0. -’
O CT1,3 B 63 ’ , , 0. -’
O CT1,4 B 78 ’ , , 0. -’
O CT1,5 B 93 ’ , , 0. -’
O CT1,6 B 108 ’ , , 0. -’
O TF 1 L2
O YM1,7 B 32 ’ 0/ ’
O YM1,8 B 47 ’ 0/ ’
O YM1,9 B 62 ’ 0/ ’
O YM1,10 B 77 ’ 0/ ’
O YM1,11 B 92 ’ 0/ ’
O YM1,12 B 107 ’ 0/ ’
O 123 ’TOTALS’
14–16

1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
O T 1 L2
O NM1,7 B 32 ’ , , 0 ’
O NM1,8 B 47 ’ , , 0 ’
O NM1,9 B 62 ’ , , 0 ’
O NM1,10 B 77 ’ , , 0 ’
O NM1,11 B 92 ’ , , 0 ’
O NM1,12 B 107 ’ , , 0 ’
O TNUM1 JB 123
O T 2 L2
O CT1,7 B 33 ’ , , 0. -’
O CT1,8 B 48 ’ , , 0. -’
O CT1,9 B 63 ’ , , 0. -’
O CT1,10 B 78 ’ , , 0. -’
O CT1,11 B 93 ’ , , 0. -’
O CT1,12 B 108 ’ , , 0. -’
O TCST1 JB 123
O TF 1 L2
O YM2,1 B 32 ’ 0/ ’
O YM2,2 B 47 ’ 0/ ’
O YM2,3 B 62 ’ 0/ ’
O YM2,4 B 77 ’ 0/ ’
O YM2,5 B 92 ’ 0/ ’
O YM2,6 B 107 ’ 0/ ’
O T 1 L2
O NM2,1 B 32 ’ , , 0 ’
O NM2,2 B 47 ’ , , 0 ’
O NM2,3 B 62 ’ , , 0 ’
O NM2,4 B 77 ’ , , 0 ’
O NM2,5 B 92 ’ , , 0 ’
O NM2,6 B 107 ’ , , 0 ’
O T 2 L2
O CT2,1 B 33 ’ , , 0. -’
O CT2,2 B 48 ’ , , 0. -’
O CT2,3 B 63 ’ , , 0. -’
O CT2,4 B 78 ’ , , 0. -’
O CT2,5 B 93 ’ , , 0. -’
O CT2,6 B 108 ’ , , 0. -’
O TF 1 L2
O YM2,7 B 32 ’ 0/ ’
O YM2,8 B 47 ’ 0/ ’
O YM2,9 B 62 ’ 0/ ’
O YM2,10 B 77 ’ 0/ ’
O YM2,11 B 92 ’ 0/ ’
O YM2,12 B 107 ’ 0/ ’
O 123 ’TOTALS’
O T 1 L2
O NM2,7 B 32 ’ , , 0 ’
O NM2,8 B 47 ’ , , 0 ’
O NM2,9 B 62 ’ , , 0 ’
O NM2,10 B 77 ’ , , 0 ’
O NM2,11 B 92 ’ , , 0 ’
O NM2,12 B 107 ’ , , 0 ’
O TNUM2 JB 123
14–17

1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
O T 2 L2
O CT2,7 B 33 ’ , , 0. -’
O CT2,8 B 48 ’ , , 0. -’
O CT2,9 B 63 ’ , , 0. -’
O CT2,10 B 78 ’ , , 0. -’
O CT2,11 B 93 ’ , , 0. -’
O CT2,12 B 108 ’ , , 0. -’
O TCST2 JB 123
O TF 1 L2
O YM3,1 B 32 ’ 0/ ’
O YM3,2 B 47 ’ 0/ ’
O YM3,3 B 62 ’ 0/ ’
O YM3,4 B 77 ’ 0/ ’
O YM3,5 B 92 ’ 0/ ’
O YM3,6 B 107 ’ 0/ ’
O T 1 L2
O NM3,1 B 32 ’ , , 0 ’
O NM3,2 B 47 ’ , , 0 ’
O NM3,3 B 62 ’ , , 0 ’
O NM3,4 B 77 ’ , , 0 ’
O NM3,5 B 92 ’ , , 0 ’
O NM3,6 B 107 ’ , , 0 ’
O T 2 L2
O CT3,1 B 33 ’ , , 0. -’
O CT3,2 B 48 ’ , , 0. -’
O CT3,3 B 63 ’ , , 0. -’
O CT3,4 B 78 ’ , , 0. -’
O CT3,5 B 93 ’ , , 0. -’
O CT3,6 B 108 ’ , , 0. -’
O TF 1 L2
O YM3,7 B 32 ’ 0/ ’
O YM3,8 B 47 ’ 0/ ’
O YM3,9 B 62 ’ 0/ ’
O YM3,10 B 77 ’ 0/ ’
O YM3,11 B 92 ’ 0/ ’
O YM3,12 B 107 ’ 0/ ’
O 123 ’TOTALS’
O T 1 L2
O NM3,7 B 32 ’ , , 0 ’
O NM3,8 B 47 ’ , , 0 ’
O NM3,9 B 62 ’ , , 0 ’
O NM3,10 B 77 ’ , , 0 ’
O NM3,11 B 92 ’ , , 0 ’
O NM3,12 B 107 ’ , , 0 ’
O TNUM3 JB 123
O T 2 L2
O CT3,7 B 33 ’ , , 0. -’
O CT3,8 B 48 ’ , , 0. -’
O CT3,9 B 63 ’ , , 0. -’
O CT3,10 B 78 ’ , , 0. -’
O CT3,11 B 93 ’ , , 0. -’
O CT3,12 B 108 ’ , , 0. -’
O TCST3 JB 123
14–18

1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
O TF 1 L2
O YM4,1 B 32 ’ 0/ ’
O YM4,2 B 47 ’ 0/ ’
O YM4,3 B 62 ’ 0/ ’
O YM4,4 B 77 ’ 0/ ’
O YM4,5 B 92 ’ 0/ ’
O YM4,6 B 107 ’ 0/ ’
O T 1 L2
O NM4,1 B 32 ’ , , 0 ’
O NM4,2 B 47 ’ , , 0 ’
O NM4,3 B 62 ’ , , 0 ’
O NM4,4 B 77 ’ , , 0 ’
O NM4,5 B 92 ’ , , 0 ’
O NM4,6 B 107 ’ , , 0 ’
O T 2 L2
O CT4,1 B 33 ’ , , 0. -’
O CT4,2 B 48 ’ , , 0. -’
O CT4,3 B 63 ’ , , 0. -’
O CT4,4 B 78 ’ , , 0. -’
O CT4,5 B 93 ’ , , 0. -’
O CT4,6 B 108 ’ , , 0. -’
O TF 1 L2
O YM4,7 B 32 ’ 0/ ’
O YM4,8 B 47 ’ 0/ ’
O YM4,9 B 62 ’ 0/ ’
O YM4,10 B 77 ’ 0/ ’
O YM4,11 B 92 ’ 0/ ’
O YM4,12 B 107 ’ 0/ ’
O 123 ’TOTALS’
O T 1 L2
O NM4,7 B 32 ’ , , 0 ’
O NM4,8 B 47 ’ , , 0 ’
O NM4,9 B 62 ’ , , 0 ’
O NM4,10 B 77 ’ , , 0 ’
O NM4,11 B 92 ’ , , 0 ’
O NM4,12 B 107 ’ , , 0 ’
O TNUM4 JB 123
O T 2 L2
O CT4,7 B 33 ’ , , 0. -’
O CT4,8 B 48 ’ , , 0. -’
O CT4,9 B 63 ’ , , 0. -’
O CT4,10 B 78 ’ , , 0. -’
O CT4,11 B 93 ’ , , 0. -’
O CT4,12 B 108 ’ , , 0. -’
O TCST4 JB 123
O TF 2 L2
O USA 132
14–19
15 Using Tables and Arrays
RPG provides mechanisms for storing and retrieving associated and/or

related data in a program. The two methods for storing associated
data are tables and arrays. The programmer can then use the LOKUP
operation code to quickly and efficiently locate data stored within the table
or array.
15.1 Using Tables

In RPG, a table is a collection of similar data items arranged in a specific
order. These data items are referred to as elements. Each entry in a table
must have the same length and the same data type (either character or
numeric). If numeric, the entries must have the same number of decimal
positions. Tables are defined within a RPG program using Extension
specifications. Each Extension specification can define a single table or it
can define two tables which contain associated data items, referred to as
alternating table format.
When a table is defined using the alternating format, the rules for loading
the data into the table are:
• The first entry from the first table is read.
• Next the first entry from the second table is read.
• This alternate reading continues until all entries from both tables are
read.
RPG supports two types of tables which are used to locate a specific data
item quickly and easily.
• Single tables—consist of one group of similar entries. When searching
a single table, the result of the search is whether the item being
searched for is present in the table. If the searched-for item is found,
that entry becomes the current entry.
• Related tables—are two tables that contain associated data elements.
This means that the data element in the second table is somehow
related to the corresponding data element in the first table. For
example the first table could be a list of labor codes used in processing
warranties for a product. The corresponding data in the second table
could described the time allowed in hours for the repair operation.
When looking up information in related tables, the first table is
searched to see if the entry is present. If the entry is found, RPG
retrieves the corresponding entries from both tables and makes them
available as the current entries.
15–1
Using Tables and Arrays
Related tables can be defined by two separate Extension specifications

or they may be defined on a single Extension specification using the
alternating table format. Related tables need not have the same
number of entries unless they are described in alternating format in
the same Extension specification. However it is recommended that
related tables contain the same number of entries. If related tables do
not contain the same number of entries, the search could find an entry
in the first table and not find the corresponding entry in the second
table. This can cause undesirable results to occur.
Types of tables are differentiated by whether they are loaded at compile

time or pre-execution time. Loading is the process by which the program
assigns the data supplied to the elements in the table.
The following characteristics determine when a table should be loaded:
• The contents of a table
• The frequency with which the entries in the table require changing
• The way the table is to be used
15.2 Compile-Time Tables

Compile-time tables are part of the source program. They are compiled
with the source program and become a permanent part of the object
program. The following example shows a source program and a compile-
time table:
Example 15–1 Migration RPG Program using a compile-time table
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FINPUT IPE F 50 DISK
FREPORT O F 132 OF PRINTER
E TABA 1 5 3
IINPUT NS 01
I 1 3 ITEM
C ITEM LOKUPTABA 10
OREPORT H 202 1P
O OR OF
O 24 ’Sample Table Program ’
O 72 ’Page: ’
O PAGE Z 77
O*
O D 01
O 4 ’Item’
O ITEM 8
O 10 31 ’was found in the table’
O N10 33 ’was not found in the tab’
O N10 35 ’le’
** TABA
AAA
BBB
CCC
DDD
EEE
15–2
One advantage of compile-time tables is that they do not need to be

loaded separately each time the program is run. However, if the need
arises to change any of the entries in a compile-time table, the table
must be revised and then the program recompiled. It is possible to
make temporary changes in the table during calculations. To make these
temporary changes permanent, the table must be output. See Section 15.9
for information about outputting tables.
15.2.1 Compile-Time Table Delimiter

The data for a compile-time table must follow the source program and
any alternate sequence records. The first data record in the table must be
preceded by a delimiter record containing either double slashes ( // ) and a
blank or double asterisks ( ** ) and a blank in character positions 1 - 3.
Table delimiters must be consistent within a program. The compiler
will interpret the first delimiter found as the default delimiter for the
remainder of the program. I.E: if the first delimiter encountered is "** ",
all remaining delimiters must also be "** ".
15.3 Pre-Execution-Time Tables

Pre-execution-time tables are not part of the object program. Each pre-
execution-time table is loaded separately from an input data file. An
advantage of pre-execution-time tables is that frequent changes can be
made to the table without recompiling the program.
Pre-execution-time tables are loaded before the first program cycle begins.
15.4 Creating Table Input Records

Table input records contain the values for the entries in a table. When
creating table input records, observe the following rules.
General Rules
• The first entry must begin in character position 1.
• All entries must be contiguous, with no space between entries, as
shown in Example 15–2.
• Entries cannot span record boundaries. Therefore, the length of an
entry is limited to the device’s maximum record length. If a related
table is defined using the alternating format, corresponding entries
cannot exceed the maximum record length.
• Each input record, except the last, must have the same number of
entries. The last record can be shorter to accommodate an uneven
number of entries.
15–3
Compile-Time Rules
• The first record must be preceded by a delimier record containing
either double slashes ( // ) and a blank or double asterisks ( ** ) and a
blank in character positions 1 - 3. Because these strings are delimiters,
records in a compile-time table cannot contain either of these three
characters in positions 1 - 3.
remainder of the program. I.E: if the first delimiter encountered is "**
", all remaining delimiters must also be "** ".
15–4
Example 15–2 Table Input Record
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E TABA 6 6 5
.
.
.
** TABA
637419231290343728441937510306
\ /\ /\ /\ /\ /\ /
1 2 3 4 5 6 <-- Element
The table in Example 15–2 consists of six entries in a record, and each
entry is five characters long.
When creating table input records for related pre-execution-time and
compile-time tables in alternating format, the entry for the first table
must be followed immediately by the corresponding entry for the second
table.
Example 15–3 defines the related tables TABA and TABB. The first record
contains the first five entries for both TABA and TABB. The second record
contains the last four entries for the tables. In this example, each entry
in TABA is alphameric with a length of three. Each entry for TABB is
numeric with a length of three and zero decimals. Both tables have a total
of nine entries per table. Example 15–4 shows how the same tables, TABA
and TABB can be defined by specifying only one entry per record.
Example 15–3 Related Tables - Multiple entries per record
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E TABA 5 9 3 TABB 3 0
.
.
.
**
AAA000BBB111CCC222DDD333EEE444
FFF555GGG666HHH777III888
\ /\ /
^ ^
| |
| TABB element 6
TABA element 6
15–5
Example 15–4 Related Tables - Single entry per record
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E TABA 1 9 3 TABB 3 0
.
.
.
**
AAA000
BBB111
CCC222
DDD333
EEE444
FFF555
GGG666
HHH777
III888
15.5 Defining Tables

To define a single table, the following entries must be made in the
Extension specification:
• Columns 27 - 32 (table name) - specify the name of the table. Table
names can be up to six characters long, but the first three characters
must be TAB.
• Columns 33 - 35 (entries per record) - specify the number of entries in
a record. Because tables can have one or more entries for each record,
calculate the maximum number of entries in a record by dividing the
record length by the length of an entry.
• Columns 36 - 39 (number of entries per table) - specify the total
number of entries in the table.
• Columns 40 - 42 (length of entry) - specify the length of each entry.
The maximum length of an alphameric table element is 256 characters
in a pre-execution-time table. The maximum length of an alphameric
table element is 96 characters in a compile-time table. The maximum
length of a numeric table element is 15 digits.
• Column 43 (data format) - if the table contains numeric data, the data
format must be specified. Use a ’P’ to specify packed-decimal format, a
’B’ for binary format, or leave the entry blank for trailing numeric or
zoned-decimal format. When specifying packed-decimal format, make
sure the length of the entry represents the length of the numeric data
in unpacked form. When specifying binary format, the length of the
entry must indicate the number of bytes required to store the binary
field. (Use 4 for two-byte binary numbers or 9 for four-byte binary
numbers.)
• Column 44 (decimal positions) - for numeric data, specify the number
of positions to the right of the decimal point. A 0 must be specified for
numeric data with no decimal positions.
15–6
• Column 45 (sequence) - specify ascending (A) or descending (D) to

indicate that the entries in a table are in the specified sequence, or
leave this column blank to specify an unsequenced table.
There are additional considerations for compile-time tables and pre-

execution-time tables, which are discussed in Sections 15.5.2 and 15.5.3.
15.5.1 Defining Related Tables in Alternating Format

Two tables can be defined either individually, or as a main table with an
alternate table defined in alternating format. To define an alternate table,
make the following entries for the alternate table in the same Extension
specification used to describe the main table:
• Columns 46 - 51 (table name) - specify the name of the alternate
table. Table names can be up to six characters long. The first three
characters must be TAB.
• Columns 52 - 54 (length of entry) - specify the length of the entries in
the alternate table.
The maximum length of an alphameric table element is 256 characters
in a pre-execution-time table. The maximum length of an alphameric
table element is 96 characters in a compile-time table. The maximum
length of a numeric table element is 15 digits.
• Column 55 (data format) - if the alternate table contains numeric data,
the data format must be specified. Use a ’P’ to specify packed-decimal
format, a ’B’ for binary format, or leave the entry blank for trailing
numeric or zoned-decimal format. When specifying packed-decimal
format, make sure the length of entry represents the length of the
numeric data in unpacked form. When specifying binary format, the
length of the entry must indicate the number of bytes required to store
the binary field. (Use 4 for two-byte binary numbers or 9 for four-byte
binary numbers.)
indicate that the entries in a table are in the specified sequence, or
leave this column blank to specify an unsequenced table.
The main table’s values for entries per table (columns 36 - 39), from file
name (columns 11 - 18), and entries per record (columns 33 - 35) are also
used for the alternate table.
15.5.2 Defining a Compile-Time Table

When defining a compile-time table, make the entries described in
Section 15.5 in an Extension specification. For compile-time tables, there
is one notable exception: columns 43 and 55 must be blank for a compile-
time table because packed and binary data formats are not allowed in RPG
program source code.
15–7
When defining compile-time tables, observe the following rules.
Rules
• If the compile-time table contains numeric data, it must be in trailing
numeric or zoned-decimal format. Therefore, leave column 43 (data
format) blank. Leave column 55 (data format) blank if defining related
tables in alternating format.
• The input records for compile-time tables must be in the same order in
which the tables are defined in the Extension specifications.
• In compile-time tables the maximum length of an alphameric array
element is 96 characters. This is the maximum record size for an RPG
source program.
• If the compile-time table contains more entries than are defined for
the table in the Extension specification, a warning will be generated
stating that the table is full.
• If the compile-time table contains less entries than are defined for
the table in the Extension specification, a warning will be generated
stating that the table is short.
In the following example, the table name is TABLE1. There are 10 entries
in the table, with one entry in each record. The length of each entry is
five digits, with two decimal positions. The data type of the entry in each
record is trailing numeric, by default.
Example 15–5 Extension Specification to define a compile-time table
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E TABLE1 1 10 5 2
.
.
.
// TABLE1
63741
92312
90343
72844
19375
10306
23847
09374
59780
12361
The following example defines two related tables, TAB1 and TAB2. There
are four entries in each table, with two entries in each record. The length
of each entry is five digits, with zero decimal positions for TAB1 and TAB2.
Both tables are in ascending sort sequence.
15–8
Example 15–6 Extension Specification to define compile-time related

tables
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E TAB1 2 4 5 0ATAB2 5 0A
.
.
.
// TAB1 / TAB2
11111222223333344444
55555666667777788888
15.5.3 Defining a Pre-execution-Time Table

Defining a pre-execution-time table requires the same entries be made in
the Extension specification as those used to define a compile-time table,
(see Section 15.5 - Section 15.5.2). In addition, the name of the input
file which contains the data for the table must be specified in columns
11 - 18 (from file name). The table input file must be defined in a File
Description specification with a T in column 16 (file designation) and an E
in column 39 (extension code). Example 15–7 defines a pre-execution-time
table, TABLEA, which contains 50 elements, each 5 characters in length.
Each input record from the input table file INPDATA contains 10 table
elements.
Example 15–7 Definition of a Pre-execution-Time Table
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
FINPDATA IT F 50 EDISK
.
.
.
E INPDATA TABLEA 10 50 5
When using pre-execution-time tables, observe the following rules.
Rules
• The input file cannot contain more entries than are defined for the
table. If it does, a run-time error occurs.
• If more than one pre-execution-time table is to be loaded from table
files, each pre-execution-time table must be loaded from a different
file. The exception is when two pre-execution-time tables are defined
as alternating tables, both tables are loaded from the same table file.
15–9
15.6 Referencing Table Entries

When a table name is referenced in factor 1 or factor 2 of a Calculation
specification, the table name refers to the data retrieved by the last
successful search. The exception to this rule is when a table is referenced
as factor 2 or as the result field in a LOKUP operation.
In Example 15–8, FLD1 is the search argument in the LOKUP operation.
If the program can locate FLD1 in TAB1, indicator 10 is set on. Then, the
result of the calculation on the next line replaces the current contents of
the located entry in TAB1 because the table entry is used as the result
field.
Example 15–8 Single table LOKUP
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E TAB1 1 5 5 0
.
.
.
C FLD1 LOKUPTAB1 10
C 10 TAB1 MULT 100 TAB1
15.7 Searching Tables

The operation code LOKUP is used to search for an element in a table.
The search begins with the first entry and searches sequentially through
the table looking for an entry which satisfies the search criteria. If an
entry is found that satisfies the search criteria, a copy of the entry is
placed into a special work area for the table. After each successful search,
this special work area is updated with the current table entry. When the
table name is specified in factor 1 with any operation code or in factor 2
with any operation code expect for LOKUP, the table name is referencing
the entry stored in the special work area for that table.
To search a table for an entry, the following entries must be made in the
Calculation specification:
• Columns 18 - 27 (factor 1) - specify a field or literal representing the
entry to be located. Make sure the search argument has the same
length and data format as the entries of the table being searched.
• Columns 28 - 32 (operation code) - specify the LOKUP operation code.
• Columns 33 - 42 (factor 2) - specify the name of the table to be
searched.
• Columns 54 - 59 (resulting indicator) - specify one or more indicators
to indicate the type of search to be performed and to indicate whether
the search has been successful. The indicator(s) can then be used to
condition subsequent calculations and output operations. All indicators
specified in columns 54 - 59 are set off before the search begins. At
least one resulting indicator must be specified. If the search is not
successful, no indicators will be set on.
15–10
An indicator specified in columns 58 - 59 tells the LOKUP operation

to search for an equal condition. The table is searched for an entry
that is equal to factor 1. When the first entry is found that meets the
condition, the search is terminated and the specified indicator is set
on.
to search for a low condition. The table is searched for an entry that
is closest to factor 1 in value, but less than the value of factor 1.
When the first entry is found that meets the condition, the search is
terminated and the specified indicator is set on.
to search for a high condition. The table is searched for an entry that
is closest to factor 1 in value but greater than the value of factor 1.
If the table is to be searched using only the equal condition, then
a sequenced table is not required. To save time in searching an
unsequenced table, place the more frequently referenced entries at the
beginning of the table.
The conditions low and high can only be specified for a LOKUP
operation if the table to be searched is sequenced. If the table is
sequenced, the conditions low and equal or high and equal can be
combined. When two conditions have been combined, the equal
condition takes precedence when searching the table. If both the
low and high conditions are coded, a compile time error will be flagged.
15.7.1 Searching One Table

To search a single table, specify the data to be searched for in factor 1,
LOKUP as the operation code, the table to be searched in factor 2, and the
type of search to be conducted using the resulting indicators. The table
in factor 2 will be searched for an element which satisfies the conditions
specified. If the search is successful, the entry which satisfied the search
will be placed into the special work area for that table and the appropriate
resulting indicator will be turned on.
contents in factor 2 do not change. When a program initializes, the first
entry in a table is placed in the table reference field.
See Chapter 11 for a complete description of the LOKUP operation code.
15.7.2 Searching Related Tables

To search related tables, specify the data to be searched for in factor 1,
LOKUP as the operation code, the table to be searched in factor 2, the
name of the related table in the result field, and the type of search to
be conducted using the resulting indicators. The table in factor 2 will be
searched for an element which satisfies the conditions specified. If the
search is successful, the corresponding entry from the table will be placed
15–11
into the special work area for that table. Next, the corresponding entry is
located in the table specified in the result field and placed into the special
work area for that table.
contents in factor 2 and the optional result table reference field contents
do not change. When a program initializes, the first entry in a table is
placed in the table reference field.
See Chapter 11 for a complete description of the LOKUP operation code.
In Example 15–9, FLD1 is the search argument in the LOKUP operation.
If the program locates FLD1 in TAB1, that entry becomes the current
entry. Then the corresponding entry in TAB2 is located, and it then
becomes the current entry for TAB2.
Example 15–9 Related table LOKUP
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
C FLD1 LOKUPTAB1 TAB2 10
In Example 15–10, the program tries to match the search argument ITEM
with an entry in table TABA. If a matching entry is found, indicator 11 is
set on. If no matching entry is found, the halt indicator H1 is set on and
the program terminates. In the compile-time table TABA, there are 10
entries in a record and 50 entries in a table. Each entry is five characters
long.
Example 15–10 Program table LOKUP
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FINPUT IPE F 30 DISK
FREPORT O F 40 DISK
E TABA 10 50 5
IINPUT NS 01
I 1 5 ITEM
I 6 102FLD1
I 15 30 FLD2
C ITEM LOKUPTABA 11
C N11 SETON H1
C 11 100 ADD FLD1 NEW 62 10
OREPORT D 01 11
O NEW B 20
//
10001100021000310004100051000610007100081000910010
20001200022000320004100052000620007200082000920010
30001300023000330004100053000630007300083000930010
40001400024000340004100054000640007400084000940010
50001500025000350004100055000650007500085000950010
In Example 15–11, the program searches the unsequenced table TABLE2

for the value LENGTH. If the search is unsuccessful, processing for
TABLE1 is bypassed. Otherwise, the program searches the sequenced
table TABLE1 to check for a value greater than or equal to COST. If
the search is successful, the subroutine PROCES is called to process the
entry.
15–12
Example 15–11 LOKUP using a sequenced table
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FINFILE IP F 80 80 DISK
FFILE1 IT F 80 80 EDISK
FFILE2 IT F 80 80 EDISK
E FILE1 TABLE1 1 6 3 2A
E FILE2 TABLE2 1 6 3 0
IINFILE NS 11
I 1 32COST
I 4 60LENGTH
I 7 100NUMBER
C LENGTH LOKUPTABLE2 20
C N20 GOTO NOPROC
C COST LOKUPTABLE1 26 26
C N26 EXSR PROCES
C NOPROC TAG
.
.
.
15.8 Updating Tables

15.8.1 Temporarily Updating Tables
It is possible to change the contents of a table while the program is
executing. The changes made will remain in effect for the duration of the
program, but will be lost when the program finishes execution. The next
time the program is executed, the table will contain the original data.
To modify the contents of a table during execution, reference the table to
be modified as the result field in a calculation. When the statement is
executed the table work area will be updated as well as the table element
which corresponds to the value in the work area.
In Example 15–12, the program searches for the entry 025 in the table
TABLE3. If the search is successful, the entry 025 in both TABLE3 and
the special work area for TABLE3 will be replaced with the entry 250.
15–13
Example 15–12 Program to temporarily update a table
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
.
.
.
E TABLE3 1 6 3 0
.
.
.
C 025 LOKUPTABLE3 20
C 20 MOVE 250 TABLE3
.
.
.
15.8.2 Permanently Updating Tables

To permanently change the contents of an entry in, or add new entries to,
a compile-time table, edit and recompile the program that contains the
table.
To permanently change the contents of an entry in, or add new entries to,
a pre-execution-time table, edit the input file that contains the table. A
program can also be used to modify the current table file or to output a
completely new table file.
In Example 15–13, the program searches related tables specified using the
alternating format. The first table, TABA, consists of a list of numbers
of items in stock. The second table, TABB, consists of a list of unit prices
corresponding to the item numbers. The program will raise the unit price
of each item by 5% and output the updated table.
Example 15–13 Updating a pre-execution-time table
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FTABLE1 IT F 22 22 EDISK
FTABLE2 O F 22 22 DISK
E TABLE1 TABLE2 TABA 2 10 5 TABB 6 2
IINFILE NS 01
I 1 5 ITEM
C ITEM LOKUPTABA TABB 11
C N11 SETON H1
C 11 TABB MULT 1.05 TABB H
The related tables, TABA and TABB, are pre-execution-time tables.

They are loaded from the input table file TABLE1. In the Extension
specification, the output file TABLE2 is automatically created. (Automatic
creation means that the output file does not require an Output
specification.)
15–14
When the program executes, it reads the first record from the primary
input file MASTER. If the search argument ITEM is matched, indicator
11 is set on and the corresponding entry from TABB is made available for
processing. If no match is found, the halt indicator H1 is set on and the
program terminates without creating the output file TABLE2.
When the program ends, the updated tables TABA and TABB are written
to file TABLE2 with the same number of entries per record as the table
input file TABLE1.
15.9 Outputting Tables

When specifying the name of an output file in columns 19 - 26 (to
file name) of the Extension specification, the program creates the file
automatically, as shown in Example 15–13.
When specifying a table as a field on an Output specification, only the last
entry found by the LOKUP operation can be output.
In Example 15–14, the table TABSH is read from the file TABFILE. For
this example, the table is short; that is, not all 80 entries contain data.
The LOKUP operation searches the table for the first entry containing
zeros. This entry is replaced with a field read from the input file INFILE.
The EXCPT operation code outputs the entry TABSH with the new data.
Remember, the entry that is updated and then output by the Output
specification is the entry found by the last LOKUP operation. When
the last cycle occurs, the entire updated table will be written to the file
TABFILE2.
Example 15–14 Outputting a table
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FTABFILE IT F 80 80 EDISK
FTABFILE2O F 80 80 DISK
FOFILE O F 80 80 DISK
E TABFILE TABFILE2TABSH 10 80 4 0
IINFILE NS 01
I 1 40ENTRY
C 0000 LOKUPTABSH 11
C 11 Z-ADDENTRY TABSH H1
C 11 EXCPT
OOFILE E
O TABSH 10
15.10 Using Arrays

In RPG, an array, like a table, is a collection of similar data items
arranged in a specific order. These data items are referred to as elements.
Each entry in an array must have the same length and the same data type
(either character or numeric). If numeric, the entries must have the same
number of decimal positions. Arrays are defined within an RPG program
using Extension specifications. Each Extension specification can define
15–15
a single array or it can define two arrays which contain associated data
items, referred to as alternating format.
When an array is defined using the alternating format, the rules for
loading the data into the array are:
• The first entry from the first array is read.
• Next the first entry from the second array is read.
• This alternate reading continues until all entries from both arrays are
read.
Unlike tables, the programmer can reference individual array elements

(entries) by specifying an array index, or process an entire array by
specifying the array name during calculation operations. An array should
be used instead of a table when an operation code is to affect all the
elements in the array with a single reference, or to reference a specified
number of separate elements at the same time. For example, when it is
necessary to compute a 5% sales tax for each element in an array, a single
specification can be used to perform the operation on every element in the
array.
Just like tables, RPG supports two types of arrays.
• Single arrays—consists of one group of similar entries. When
searching a single array, the result of the search determines whether
the item being searched for is present in the array.
• Related arrays—are two arrays that contain associated data elements.
This means that the data elements in the second array are somehow
related to the corresponding data elements in the first array. For
example, the first array could be a list of valid part numbers. The
corresponding data in the second array could be the list price for the
related part number.
Related arrays can be defined by two separate Extension specifications
or they may be defined on a single Extension specification using the
alternating format. Related arrays need not have the same number
of entries unless they are described in alternating format in the same
Extension specification. However, it is recommended that related
arrays contain the same number of entries.
Types of arrays are differentiated by whether they are loaded at compile

time, pre-execution-time, or execution (run) time. Loading is the process
by which the program assigns the data supplied to the elements in an
array.
The following characteristics determine when an array should be loaded:
• The contents of an array
• The frequency with which the elements in the array require changing
• The way the array is to be used
15–16
15.11 Compile-Time Arrays

Compile-time arrays are part of the source program. They are compiled
with the source program and become a permanent part of the object
program. One advantage of compile-time arrays is that they do not need
to be loaded separately each time the program is run. However, if the
need arises to change any of the entries in a compile-time array, the
array must be revised and the program recompiled. It is possible to make
temporary changes in the array during calculation operations. To make
these temporary changes permanent, the array must be output to a file.
Then, using the output file as a reference, modify the RPG program and
recompile the program. See Section 15.20 for information about outputting
arrays.
15.11.1 Compile-Time Array Delimiter

The data for a compile-time array must follow the source program and
any alternate sequence records. The first data record in the array must be
preceded by a delimiter record containing either double slashes ( // ) and a
blank or double asterisks ( ** ) and a blank in character positions 1 - 3.
Array delimiters must be consistent within a program. The compiler
remainder of the program. I.E: if the first delimiter encountered is "// ", all
remaining delimiters must also be "// ".
The following example shows a source program with the input data for two
compile-time arrays and their alternate compile-time arrays:
Example 15–15 Program using compile-time arrays
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FPROCD IP F 80 DISK
FINLIST O F 132 OF PRINTER
E AR1 1 5 5 0ALT1 20
E AR2 4 4 5 0ALT2 4 2
IPROCD NS 01
I 1 50PRODNO
I 6 80QUAN
C Z-ADD1 I 20
C PRODNO LOKUPAR1,I 20
C Z-ADD1 T 20
C PRODNO LOKUPAR2,T 21
C 21 QUAN MULT ALT2,T AMT 72
OINLIST H 202 1P
O OR OF
O UDATE Y 18 ’ / / ’
O 47 ’INVENTORY PARTS LIST’
O PAGE 65
O H 1 1P
O OR OF
O 32 ’PRODUCT PRODUCT’
O 53 ’UNIT’
O H 2 1P
O OR OF
15–17
Example 15–15 (Cont.) Program using compile-time arrays

O 17 ’NUMBER’
O 45 ’DESCRIPTION QTY’
O 64 ’PRICE AMOUNT’
O D 1 01
O PRODNO 16 ’ 0’
O 20 ALT1,I 39
O N20 39 ’***NO DESCRIPTION***’
O QUAN 45 ’ 0 ’
O 21 ALT2,T 53 ’ 0. ’
O N21 53 ’*NONE’
O 21 AMT 65 ’ , 0. ’
O T 1 LR
O 27 ’END OF PRICE LIST’
//
17526BOLT
18171SCREW
19226NAIL
25116NUT
29258MAGNESIUM COVER
//
175260126181710059192260173292585843
15.12 Pre-execution-Time Arrays

Pre-execution-time arrays are not part of the object program; each array is
loaded separately from an input data file. An advantage of pre-execution-
time arrays is that frequent changes can be made to the array without
recompiling the program.
Pre-execution-time arrays are loaded before the first program cycle begins.
15.13 Execution-Time Arrays

Execution-time arrays are created by using Input or Calculation
specifications. These arrays are loaded either from input data or as
the result of calculation operations after program execution begins.
15.14 Creating Array Input Records

Array input records contain the values for the entries in the array. When
creating array input records for compile-time and pre-execution-time
arrays, observe the following rules.
Rules
• The first entry must begin in character position 1.
• All entries must be contiguous, with no space between entries, as
shown in Example 15–16.
The array in Example 15–16 consists of five entries,. Each entry is 10
characters long.
15–18
• Entries cannot span record boundaries. Therefore, the length of an

entry is limited to the device’s maximum record length. If using
related arrays in alternating format, corresponding entries cannot
exceed the maximum record length.
• Each array input record, except the last, must have the same number
of entries. This record can be shorter to accommodate an uneven
number of entries.
Example 15–16 Array Input Record
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E TABA 5 5 10
.
.
.
** TABA
aaaaaaaaaabbbbbbbbbbccccccccccddddddddddeeeeeeeeee
\ /\ /\ /\ /\ /
1 2 3 4 5 <--- Elements
When creating compile-time array input records, observe the following

rules.
Compile-Time Rules
• The first record must be preceded by a record containing either double
slashes ( // ) and a blank or double asterisks ( ** ) and a blank in
character positions 1 - 3. Because these strings are delimiters, records
in a compile-time array cannot contain either of these characters in
positions 1 - 3.
remainder of the program. I.E: if the first delimiter encountered is "**
", all remaining delimiters must also be "** ".
When creating array input records for related pre-execution-time and

compile-time arrays in alternating format, the entry for the first array
must be followed immediately by the corresponding entry for the second
array.
Example 15–17 defines the related arrays ARY1 and ARY2. The first
record contains the first five entries for both ARY1 and ARY2. The second
record contains the last four entries for the arrays. In this example, each
entry in ARY1 is alphameric with a length of three. Each entry for ARY2
is numeric with a length of three and zero decimals. Both arrays have
a total of nine entries per array. Example 15–18 shows how the same
arrays, ARY1 and ARY2, can be defined by specifying only one entry per
record.
Example 15–17 Related arrays defined using multiple entries per record
15–19
Example 15–17 (Cont.) Related arrays defined using multiple entries

per record
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E ARY1 5 9 3 ARY2 3 0
.
.
.
**
AAA000BBB111CCC222DDD333EEE444
FFF555GGG666HHH777III888
\ /\ /
^ ^
| |
| ARY2 element 6
ARY1 element 6
15–20
Example 15–18 Related arrays defined using a single entry per record
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E ARY1 1 9 3 ARY2 3 0
.
.
.
**
AAA000
BBB111
CCC222
DDD333
EEE444
FFF555
GGG666
HHH777
III888
15.15 Defining Arrays

The following entries are required in the Extension specification for all
arrays.
• Columns 27 - 32 (array name) - specify the name of the array. The
array name cannot begin with TAB.
• Columns 36 - 39 (number of entries per array) - specify the number of
entries in the array.
• Columns 40 - 42 (length of entry) - specify the length of each entry.
The maximum length of an alphameric array element is 256 characters
in a pre-execution-time or execution-time array. The maximum length
of an alphameric table element is 96 characters in a compile-time
array. The maximum length of a numeric array element is 15 digits.
indicate that the entries in an array are in the specified sequence, or
leave this column blank to specify an unsequenced array.
15.15.1 Defining Related Arrays in Alternating Format

When defining related arrays using alternating format, the following
entries must be made in the Extension specification in addition to the
entries required for the primary array.
• Columns 46 - 51 (array name) - specify the name of the alternate
array. The array name cannot begin with TAB.
• Columns 52 - 54 (length of entry) - specify the length of the entries in
the alternate array.
15–21
The maximum length of an alphameric array element is 256 characters

in a pre-execution-time or execution-time array. The maximum length
of an alphameric table element is 96 characters in a compile-time
array. The maximum length of a numeric array element is 15 digits.
• Column 55 (data format) - only specify the data format for alternate
pre-execution-time arrays that contain numeric data. Specify packed-
decimal format (P) or binary format (B), or leave the entry blank
(trailing numeric or zoned-decimal format). When specifying packed-
decimal format, make sure the entry length represents the length of
the numeric data in unpacked form. When specifying binary format,
the length of the entry must indicate the number of bytes required
to store the binary field. (Use 4 for two-byte binary numbers or 9 for
four-byte binary numbers.)
• Column 57 (sequence) - indicates that the order of the entries in
an alternate array are in the specified sequence. Specify either
ascending (A), descending (D), or leave this column blank to specify an
unsequenced array.
The entries made in the following columns for the main array also apply
to the alternate array:
• Columns 11 - 18 (from file name)
• Columns 33 - 35 (entries per record)
• Columns 36 - 39 (entries in array)
15.15.2 Defining a Compile-Time Array

To define a compile-time array, the following entries must be made in the
Extension specification in addition to the entries required for all arrays,
(see Section 15.15 - Section 15.15.1):
• Columns 33 - 35 (entries for each record) - specify the number of
entries in a record. Because arrays can have one or more entries
per record, calculate the maximum number of entries in a record by
dividing the record length by the length of an entry. All records, except
the last, must contain the same number of entries; each entry must be
the same length.
When defining compile-time arrays, observe the following rules.
Rules
• If the compile-time array contains numeric data, it must be in trailing
numeric or zoned-decimal format. Therefore, leave column 43 (data
format) blank. Leave column 55 (data format) blank if defining related
arrays in alternating format.
• The input records for compile-time arrays must be in the same order
in which the arrays are defined in the Extension specifications.
15–22
• In compile-time arrays, the maximum length of an alphameric array

element is 96 characters. This is the maximum record size for an RPG
source program.
• If the compile-time array contains more entries than are defined for
the array in the Extension specification, a warning will be generated
stating that the array is full.
• If the compile-time array contains less entries than are defined for
the array in the Extension specification, a warning will be generated
stating that the array is short.
Example 15–19 describes the compile-time array A1. The array has eight
entries with four entries in each record. Each entry is a character field
that is six bytes long. The array records are located at the end of the
program.
Example 15–19 Compile-time array
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E A1 4 8 6
.
.
.
**
111111222222333333444444
555555666666777777888888
15.15.3 Defining a Pre-execution-Time Array

To define a pre-execution-time array, the following entries must be made
in the Extension specification in addition to the entries required for all
arrays, (see Section 15.15 - Section 15.15.1):
• Columns 11 - 18 (from file name) - specify the name of the input file
that contains the data for the array. This input file is called an array
input file. It must be defined in a File Description specification by
specifying T in column 16 (file designation) and an E in column 39
(extension code).
• Columns 33 - 35 (entries per record) - specify the number of entries
in a record. Arrays can have one or more entries for each record.
Calculate the maximum number of entries in a record by dividing the
record length by the length of an entry. All records except the last
must contain the same number of entries; each entry must be the
same length.
• Column 43 (data format) - if the array contains numeric data, the data
sure the length of entry represents the length of the numeric data in
unpacked form. When specifying binary format, the length of the entry
must indicate the number of bytes required to store the binary field.
(Use 4 for two-byte binary numbers or 9 for four-byte binary numbers.)
15–23
When using pre-execution-time arrays, observe the following rules.
Rules
• The input file cannot contain more entries than are defined for the
array. If it does, a run-time error occurs.
• The input file can contain fewer entries than are defined for the array,
but only if a sequence is not specified. When a sequence is not specified
and the array contains fewer entries than are defined, the remaining
entries are automatically filled using blanks for alphanumeric data
and zeros for numeric data.
15.15.4 Defining an Execution-Time Array

An execution-time array is defined using the entries described in
Section 15.15 - Section 15.15.1. Execution-time arrays can be loaded
by data read in from files (via the Input specifications) or by calculations
specified in the Calculation specifications. Execution-time arrays are not
sequenced checked. The SORTA operation code can be used to sort the
array into the order specified in column 45 of the Extension specification.
If a sequence has not been specified, the sequence will default to ascending
order.
If the array is to be loaded from a data file, it will be necessary to code
one or more Input specifications. How many Input specifications are
required depends on whether the array data is stored in a single record
or in multiple records. If the array data is stored in a single record and
occupies consecutive bytes, then the array can be loaded using a single
Input specification. If the array data is stored in multiple records or is
not stored in consecutive bytes in a single record, then two or more Input
specifications will be required. In this case, an Input specification will be
required to describe each individual array element.
To load an execution-time array from an input file, the following entries
must be made for the array input file in the Input specifications:
• Column 43 (data format) - if the array contains numeric data, the data
sure the length of entry represents the length of the numeric data in
unpacked form. When specifying binary format, the length of the entry
must indicate the number of bytes required to store the binary field.
(Use 4 for two-byte binary numbers or 9 for four-byte binary numbers.)
• Columns 44 - 51 (field location) - specify the beginning and ending
character positions of the entire array, partial array, or array element
being loaded. If the data format is packed-decimal or binary, the field
location must represent the actual size of the data element in bytes.
• Columns 53 - 58 (field name) - specify the name of the array (this must
be the same name used on the Extension specification) or the name
of an individual array element (array name followed by a comma and
index).
15–24
Example 15–20 shows how to use the Input specification to load an entire
execution-time array containing packed-decimal data as a single field.
Array ARR contains seven elements, and each element is four bytes long.
The execution-time array is loaded from the input file ARRIN as a single
field in packed-decimal format. Note that the array is specified as packed-
decimal in the Input specification but as trailing numeric in the Extension
specification.
Example 15–20 Execution-time array load from data file
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
.
.
.
E ARR 7 7 0
IARRIN NS 03
I P 1 28 ARR
.
.
.
Example 15–21 shows how to use the Input specifications to load an array
with elements scattered throughout the record. Array ARR1 contains 4
elements, each 5 bytes long, which are scattered among other fields in the
input record.
Example 15–21 Execution-time array load from data file
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
.
.
.
E ARR1 4 5
IARRFILE NS 03
I 1 5 ARR1,1
I 6 8 FLD1
I 9 13 ARR1,2
I 14 20 FLD2
I 21 25 ARR1,3
I 26 32 FLD3
I 33 37 ARR1,4
.
.
.
15.16 Referencing Arrays

With tables, only the entry retrieved by the last LOKUP operation can be
referenced. With arrays, a reference can be made to either an entire array
or an individual array element. One advantage of referencing an entire
array is that a single operation can affect all the elements in the array.
In factor 1, factor 2, or the result field, an array name followed by a comma
and an index can be specified to reference an individual array element. Be
careful when referencing an individual array element in a result field, the
total length of the array name followed by a comma and an index must be
limited to six characters.
15–25
An entire array can be referenced in factor 1, factor 2, or the result field in

the following operations:
• ADD
• Z-ADD
• SUB
• Z-SUB
• MULT
• DIV
• SQRT
• MOVE
• MOVEL
• MOVEA
• XFOOT
• LOKUP
• PARM
• SORTA
When an array name is referenced in the following calculations, RPG

repeats the operation for each element in the array:
• ADD
• Z-ADD
• SUB
• Z-SUB
• MULT
• DIV
• SQRT
• MOVE
• MOVEL
See Chapter 11, Operation Codes, for a complete description of each of

these operation codes. When using entire arrays (nonindexed) in any
calculations, observe the following rules.
Rules
• When specifying arrays with the same number of elements for factor 1,
factor 2, and the result field, RPG performs the operation on the first
element, then on the second element, and so on, until all the elements
in the array have been processed.
If the arrays do not have the same number of elements, RPG ends the
operation when the last element of the array with the fewest elements
is processed.
15–26
• When one factor is a field or constant and the other factor or result
field is an entire array, RPG performs the operation once for every
element in the array.
• If the operation requires factor 2 only and the result field is an array,
RPG performs the operation once for every element in the array.
• An array must be specified for the result field.
• Resulting indicators are not allowed.
If an array is specified for the result field and an array element as one
of the factors in a calculation, RPG alters the value of the element as a
result of the calculation. When this occurs, RPG uses the new value in
all subsequent operations that reference that element. For example, two
numeric arrays contain the data shown in Table 15–1.
Table 15–1 Array Element Values

Array Element Value
ARR1,1 4
ARR1,2 3
ARR1,3 1
ARR1,4 5
ARR2,1 2
ARR2,2 7
ARR2,3 5
ARR2,4 9
If every element of ARR1 is added to element ARR2,3 and the result

is placed in ARR2, the elements of the resulting array are as shown in
Table 15–2.
Table 15–2 Array Elements in Calculations

Array Element Expression Resulting Value
ARR2,1 (4 + 5) 9
ARR2,2 (3 + 5) 8
ARR2,3 (1 + 5) 6
ARR2,4 (5 + 6) 11
An array element can be specified in most operations that take a character

or numeric field as factor 1, factor 2, or the result field. To specify an
individual array element, enter the array name, a comma, and the
index. For example, ARR,12 specifies the twelfth element of array ARR.
A numeric field can also be used to represent the index. For example,
if ARR,FLD is used to reference an array element, the index value is
determined by the value of the field FLD.
15–27
An array index, whether it is a literal or a field, must always be greater

than or equal to 1 and less than or equal to the number of elements in the
array. If a field is used as an index and the current value of the field is out
of range when the line of code is executed, a run-time error will occur.
If the same array element is to be used in a calculation for every program
cycle, use a constant number as the index. If, however, a different array
element must be referenced each time the calculation is executed, use a
field name as the index.
In the following example, a company employs eight sales people whose
weekly sales amounts are recorded in an input file. Each record in the file
contains the weekly sales amounts; one new record is recorded in the file
each week. At the end of the year, the company generates a report listing
the sales totals for each week and the grand total for the entire year.
Example 15–22 Program using execution-time arrays
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FINPUT1 IPE F 60 DISK
FREPORT O F 60 DISK
E WEEK 8 6 2
E YEAR 8 8 2
IINPUT1 NS 01
I 1 48 WEEK
C XFOOTWEEK TOTAL 82
C ADD WEEK YEAR
CLR XFOOTYEAR GRAND 102
OREPORT D 01
O 20 ’WEEKLY TOTAL=’
O TOTAL 35 ’$ , . ’
O T LR
O 20 ’YEARLY TOTAL=’
O GRAND 35 ’$ , , . ’
Two execution-time arrays, WEEK and YEAR, are defined in the Extension
specifications. The Input specifications instruct the program to load the
array WEEK after reading each sales record from the file INPUT1.
The array elements are in contiguous positions in the input record.
Therefore, when the name of the array is specified as the field name,
the data is automatically loaded into the appropriate elements of the array
as the input record is read. In this case, only one Input specification is
necessary to load the execution-time array WEEK.
The XFOOT operation calculates the sum of all the elements in the array
WEEK and puts the sum in the result field TOTAL. The next calculation
adds one array to the other. Adding arrays involves adding each element
of one array to the corresponding element of the other array. Resulting
indicators cannot be specified to indicate the result of the operation.
These arrays have the same number of elements; therefore, any specified
operation is performed until all elements have been processed. In the
case of two arrays containing different numbers of elements, the specified
operation is performed only until the last element in the shorter array is
processed.
15–28
15.17 Searching Arrays

The operation code LOKUP is used to search for an element in an array.
The search begins with the first entry and searches sequentially through
the array looking for an entry which satisfies the search criteria.
To search an array for an entry, the following entries must be made in the
• Columns 18 - 27 (factor 1) - specify a field, literal, array element, or
table representing the element to be located. Make sure the search
argument has the same length and data format as the elements in the
array being searched.
• Columns 28 - 32 (operation code) - specify the LOKUP operation code.
• Columns 33 - 42 (factor 2) - specify the name of the array to be
searched.
• Columns 54 - 59 (resulting indicator) - specify one or more indicators
to indicate the type of search to be performed and to indicate whether
the search has been successful. The indicator(s) can then be used to
condition subsequent calculations and output operations. All indicators
specified in columns 54 - 59 are set off before the search begins. At
least one resulting indicator must be specified. If the search is not
successful, no indicators will be set on.
to search for an equal condition. The array is searched for an entry
that is equal to factor 1. The first entry found which meets the search
condition terminates the search and sets on the specified indicator.
to search for a low condition. The array is searched for an entry
that is closest to factor 1 in value but less than the value of factor 1.
to search for a high condition. The array is searched for an entry that
is closest to factor 1 in value but greater than the value of factor 1.
If the array is to be searched using only the equal condition, then
a sequenced array is not required. To save time in searching an
unsequenced array, place the more frequently referenced entries at the
beginning of the array.
The conditions low and high can only be specified for a LOKUP
operation if the array to be searched is sequenced. If the array
is sequenced, the conditions low and equal or high and equal can
be combined. When two conditions have been combined, the equal
condition takes precedence when searching the array. If both the low
and high conditions are coded, a compile-time error will be flagged.
15–29
15.17.1 Searching An Array

To search an array, specify the data to be searched for in factor 1, LOKUP
as the operation code, the array to be searched in factor 2, and the type of
search to be conducted using the resulting indicators. The array in factor
2 will be searched for an element which satisfies the conditions specified.
If the search is successful, the corresponding resulting indicator is set to
indicate which condition was found.
In Example 15–23, the program tries to match the search argument QTY
with an entry in the array ARR. If a matching entry is found, indicator 11
is set on. If the entry is not found, indicator 11 is set off.
Example 15–23 Array LOKUP
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
C QTY LOKUPARR 11
Unlike the search of a table, the program can control where the search of
an array is to begin. This is done by specifying in factor 2 of the LOKUP
operation the name of the array to be searched along with an index. The
value of the index specifies the array element where the search is to begin.
The index can be a literal or a field name. See Chapter 11, Operation
Codes, for a complete description of the LOKUP operation code.
In Example 15–24, the search begins with the seventh element of array
ARR:
Example 15–24 Array LOKUP with starting position
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
C QTY LOKUPARR,7 11
If it is necessary to reference the element found by the LOKUP operation,

specify the array name and a variable index field in factor 2 of the LOKUP
operation. If the search is successful, the index value of the array element
that satisfied the condition is stored in the index field and a resulting
indicator is set on. If the search is unsuccessful, the value 1 is placed in
the index field and a resulting indicator is set off. If the index field is not
specified, a successful LOKUP operation indicates the array contains the
data being searched for, but does not return the element’s index value.
Remember to initialize the index field to the index value of the element
where the search is to begin; in most cases, this is 1.
In the following example:
• The program loads a pre-execution-time array from the file INPUT1.
• The program reads a record from the file INPUT2.
• The index field I is set to 1 so that the search will begin with the first
element in ARY1.
15–30
• If the search argument SEARCH contains the value 50000, the

LOKUP operation searches for an array element which has a value
less than 50000. If the search is successful, indicator 56 is set on.
• If the search is successful, the EXCPT operation will print the contents
of the array element (and its index) that satisfies the search condition.
Next, 1 is added to the field containing the array index. While the
index field is less then 11, the search continues by setting indicator 54
on; this causes the program to branch back to the label LOOP.
• If the search is unsuccessful, indicator 56 is set off. The program will
finish the detail cycle and read the next record from file INPUT2.
Example 15–25 Program using LOKUP on an array
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
H
FINPUT1 IT F 50 EDISK
FINPUT2 IPE F 10 DISK
FOUTPUT O F 60 DISK
E INPUT1 ARY1 10 10 5 0D
IINPUT2 NS 01
I 1 50SEARCH
C Z-ADD1 I 20
C LOOP TAG
C SEARCH LOKUPARY1,I 56
C 56 EXCPT
C 56 ADD 1 I
C 56 I COMP 11 54
C 56 54 GOTO LOOP
OOUTPUT E 56
O 7 ’INDEX=’
O I 9
O 18 ’VALUE=’
O ARY1,I 23
An example of the output file might appear as follows:

1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
INDEX=05 VALUE=40000
15.18 Moving Array Data

The MOVEA operation code can be used to move the following array data:
• Contiguous array elements to a field
• A field or literal to contiguous array elements
• Contiguous elements of one array to contiguous elements of another
array
15–31
If the array is not indexed, data movement starts with the first element of
an array or field. If the array is indexed, the move starts with the element
specified by the index. Data movement stops when one of the following
conditions is met:
• The last array element is moved or filled.
• The number of characters moved equals the length of the shorter field,
as specified either in columns 33 - 42 (factor 2) or in columns 43 - 48
(result field) of the Calculation specification.
See Chapter 11, Operation Codes, for more information on the MOVEA
operation code.
Example 15–26 shows a pre-execution-time array, ARR20, being loaded
from the file ARRFILE. A copy of ARR20 is moved into the execution-time
array ARR15 using the MOVEA operation code.
Example 15–26 Program using MOVEA on an array
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
FARRFILE IT F 80 EDISK
E ARRFILE ARR20 5 50 4
E ARR15 50 4
.
.
.
C MOVEAARR20 ARR15
15.19 Updating Arrays

15.19.1 Temporarily Updating Arrays
To make temporary changes in an array during program execution, specify
the array name in the result field. These temporary changes can be made
permanent by writing the array to an output file that can be used later as
an input file.
15.19.2 Permanently Updating Arrays

To change the contents of an element in a compile-time array, or to add
new elements to a compile-time array, edit the source program containing
the array data and then recompile the program.
To change the contents of an element in a pre-execution-time array, or to
add new elements to a pre-execution-time array, edit the input file that
contains the array.
Example 15–27 describes the array COSTL, which consists of six-digit
trailing numeric data with two decimal places. This array is loaded from
the file ARRAYIN. During program execution, changes can be made to
this array. At the completion of the program, the array will be written
to the output file ARRAYOUT. The format in which it is written is the
same as that in which it was read; that is eight entries in each record with
15–32
each entry being a six-digit, trailing numeric data type with two decimal
positions. The files ARRAYIN and ARRAYOUT must also be described in
the File Description specifications as an input table file (ARRAYIN) and an
output table file (ARRAYOUT).
Example 15–27 Updating a pre-execution-time array
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
.
.
.
FARRAYIN IT F 50 EDISK
FARRAYOUTOT F 50 EDISK
E ARRAYIN ARRAYOUTCOSTL 8 100 6 2
.
.
.
15.20 Outputting Arrays

Either an entire array or individual array elements can be output.
To output entire arrays, entries can either be made in an Extension
specification or in an Output specification.
To write a compile-time or pre-execution-time array using an Extension
specification, make the following entry:
• Columns 19 - 26 (to file name) - specify the name of a sequential output
file. This file must have been previously defined in a File Description
specification. The program automatically writes the compile-time or
pre-execution-time array specified in the Extension specification to this
output file during last-record processing.
To write a compile-time, pre-execution-time, or execution-time array using

an Output specification, make the following entries:
• Columns 32 - 37 (field name) - specify the name of the array that is to
be written. The array is written every time the program processes a
record unless controlling indicators have been specified in columns 23 -
31 of the Output specification.
• Columns 40 - 43 (end position) - specify the character position where
the last entry of the array will be written.
In Example 15–28, for each record read from FILEA, the execution-
time array DISCNT is written out to the file REPORT using Output
specifications:
15–33
Example 15–28 Writing an execution-time array
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E COSTLIST PRICE 5 10 5 2
E DISCNT 10 5 2
IFILEA NS 01
I 1 22PERCNT
.
.
.
C 01 PRICE MULT PERCNT DISCNT H
.
.
.
OREPORT D 1 01
O DISCNT 120 ’ $0. ’
To output an individual array element, specify the array and the index of
the desired element (in the form ARR,n, where n is either a constant or a
field name) in columns 32 - 37 (field name).
Example 15–29 outputs only the first and second elements of array DSCT:
Example 15–29 Writing individual array elements
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123
E COSTLIST PRICE 5 10 5 2
E DSCT 10 5 2
IFILEA NS 01
I 1 22PERCNT
.
.
.
C 01 PRICE MULT PERCNT DSCT H
.
.
.
OREPORT D 1 01
O 20 ’ITEM 1 COST: ’
O DSCT,1 32 ’ $0. ’
O 50 ’ITEM 2 COST: ’
O DSCT,2 62 ’ $0. ’
If the array or array elements being output to a report file are numeric,
edit codes or edit words can be used to add commas, dollar signs, or to
suppress leading zeros. Do not use edit codes or edit words to modify
array data if it is going to be used as input data to subsequent programs.
When specifying an edit code with an entire array (nonindexed), RPG
automatically inserts two spaces between elements of the array in the
output record.
15–34
16 Defining and Using Data Structures
A data structure is an area of storage subdivided into data fields called

subfields. A data structure can be used in the following ways:
• Define one area of storage more than one way.
• Define a data field so that it can be referred to as a single field or
subdivided into subfields.
• Reorganize fields in an input record.
• Communicate information between programs with a local data area.
• Define data elements associated to a WORKSTN file.
16.1 Data Structure Statement

Data structure definitions appear in the Input specifications following all
input file record definitions. Data structure entries are the last elements
to appear in the Input specifications.
Data structure definitions have two parts: the data structure definition
and the subfield definitions. All subfields associated to an individual data
structure must immediately follow the data structure definition.
The format of the data structure statement is as follows:
Table 16–1 Data Structure Specification Layout

Allowable
Column(s) Entries Explanation
7-12 Data Optional. Identifies the data structure. The data
structure structure name, which is not required, can be a field
name defined in an Input specification or a Calculation
specification.
18 U Optional. Identifies this data structure as the local
data area.
19-20 DS Required. Specifies that this Input specification is
defining a data structure.
Note that a data structure name can only be six characters long. Data
structure names follow field name conventions. They can be 1 - 6
characters long, must begin with an alpha character, and can be composed
of any valid alphanumeric characters.
The data structure name can appear on only one data structure
specification. It cannot be the same name specified for a look-ahead
field.
16–1
Defining and Using Data Structures
The length of the data structure is one of the following:

— The length specified in an input field specification, if the data structure
name is the same as the input field name.
— The highest end position of a subfield within the data structure, if the
data structure name does not match an input field name.
The length computed by the highest end position of a subfield within a

data structure must be less than or equal to the length specified in an
input field specification if the data structure name matches an input field
name.
If the length of a data structure exceeds the length of the input field it
is redefining, or disagrees with the length of a result field defined in a
Calculation specification, the compiler will issue a diagnostic message.
If a data structure is named, it can be used as factor 1, factor 2, or the
result field of a Calculation specification or as an output field.
A data structure name cannot be used as a subfield name in another data
structure.
Data structures cannot be individual array elements, tables, or RPG
reserved words.
16.2 Data Structure Subfields

Data structure subfields are specified in columns 44 - 58. They are defined
in the same manner as an input data field.
The format of a data structure subfield statement is as follows:
Table 16–2 Data Structure Subfield Specification Layout

Allowable
Column(s) Entries Explanation
44-47 Start position Identifies the starting position of the subfield relative
to the beginning of the data structure.
48-51 End position Identifies the end position of the subfield relative to
the beginning of the data structure.
52 Decimal If 0 - 9 is entered in this column, it identifies the field
positions as a numeric field. If the column is left blank, the field
is considered alphameric.
53-58 Subfield The name assigned to the subfield. The subfield
name name can match an input field name or a field name
defined in the result field of a Calculation specification.
The subfield name cannot appear in more than one
data structure and cannot match a data structure
name.
The field location’s start and end positions are relative to the beginning of
the data structure.
When coding a subfield definition in an Input specification, only columns
44 - 58 are used.
16–2
The subfield name can be the same as a field defined on an Input

specification or a Calculation specification. The subfield will act as a
redefinition of these fields.
Subfields can be used as factor 1, factor 2, or the result field of a
Calculation specification or as output fields.
The same subfield name cannot be used in more than one data structure.
A data structure name cannot be used as a subfield name in another data
structure.
If an array is specified as a subfield, the length specified must equal the
amount of storage required to store the entire array.
Overlapping subfields cannot be used in the same Calculation specification.
If either factor 1, factor 2, or the result field references a subfield in a data
structure that is an entire array or an array with a variable index, then
the entire array is used to determine whether overlap exists.
Any subfield previously defined in an Input specification must be the same
length as the input field.
Packed and binary field designations are not permitted when defining
numeric subfields. If a subfield redefines a packed or binary input field,
its length must be defined as the unpacked length of the input field. The
input field will be converted to trailing numeric format before it is placed
in the subfield.
Data structure subfields cannot be individual array elements, tables, or
RPG reserved words.
16.3 Using Data Structures

A data structure is considered to contain alphameric data and is initialized
to blanks at program startup. It is the programmer’s responsibility to
ensure that numeric subfields contain numeric data before they are used
in a calculation or output operation.
A data structure can be from 1 - 9,999 characters long. The maximum
length of the local data area data structure is 512 characters.
The length of a data structure is determined by a matching input field
definition or by the highest subfield end position within the data structure.
The data structure length is determined by whichever condition is
encountered first. All subsequent definitions of the data structure length
must match the original definition or they will be considered invalid and
the compiler will issue error messages.
If an input or calculation field is defined in a data structure, the physical
storage of the field’s contents will be within the data structure storage
area.
16–3
16.3.1 Breaking a Field Down Using Subfields

A data structure can be used to break an input field down into subfields.
The following example depicts the use of a data structure to break an
input field into subfields.
Example 16–1 Input field redefined by subfields
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
ICUSTMSTRAA 01
I 1 16 CUSTNO
I 17 46 NAME
.
.
.
ICUSTORDRBB 02
I 1 16 CUSTNO
I 17 25 PARTNO
.
.
.
ICUSTNO DS
I 01 02 STATE
I 03 05 CITY
I 06 100ZIP
I 11 160ID
In this example, the field CUSTNO is used in both the CUSTMSTR and
CUSTORDR files. It is redefined by a data structure and, within the data
structure, it is further broken down into the fields STATE, CITY, ZIP, and
ID. By using a data structure to redefine the CUSTNO field, only 16 bytes
of storage are used to store the field and its subfields. Furthermore, the
subfields used to redefine the CUSTNO field need only be defined once in
the data structure, rather than repeated within each input record.
16–4
16.3.2 Using a Data Structure Storage Area In More Than One Way
A data structure can be used to define a single area of storage for several
purposes. The following example depicts the use of a data structure to
define three input records.
Example 16–2 Using a data structure to define multiple input records
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
IINVENTRYAA 01 01 CM
I 1 50 ITMREC
I BB 02 01 CI
I 1 26 QTY
I CC 03 01 CO
I 1 34 ORDREC
.
.
.
I DS
I 01 50 ITMREC
I 01 01 RECCOD
I 02 100PARTNO
I 11 50 DESC
*
I 01 26 QTY
I 01 01 RECCOD
I 02 100PARTNO
I 11 160STOCK
I 17 200LOWLIM
I 21 26 LSTORD
*
I 01 34 ORDREC
I 01 01 RECCOD
I 02 100PARTNO
I 11 16 ORDDAT
I 17 220ORDQTY
I 23 280AVEORD
I 29 340BIGORD
In this example, a single data structure is used to define three input

records. By using a data structure in this fashion, it is possible to use only
50 bytes of storage for all three record types. If each record were defined
individually, they would consume 110 bytes of storage.
16–5
16.3.3 Using a Data Structure to Reorganize Input Fields

A data structure can be used to reorganize input fields from an input
record. The following example depicts a data structure being used to
reorganize fields from an input record.
Example 16–3 Input fields reorganized by a data structure
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
ICUSTORDRBB 02
I 1 16 CUSTNO
I 17 25 PARTNO
I 26 310ORDDAT
I 32 370SHPDAT
.
.
.
IORDKEY DS
I 01 16 CUSTNO
I 17 220ORDDAT
In this example, the data structure ORDKEY is constructed from the fields
CUSTNO and ORDDAT. The fields CUSTNO and ORDDAT are obtained
from the CUSTORDR file and are reordered in the data structure to build
the ORDKEY.
16.4 Local Data Area

The local data area (LDA) is a 512-byte, single-record data file which is
referenced by the logical name RPGLDA. It is processed by RPG programs
as a data structure. It can be used to pass information between programs
and command procedures. The local data area is also discussed in the
Migration RPG User’s Guide.
If specified, the local data area is automatically loaded when an RPG
program is initialized and is written back out when the program
terminates normally. To specify a local data area, a data structure must
have a U in column 18 on the Input specifications. A data structure name
is optional. Only one data structure in an RPG program may have a U
specified in column 18.
Example 16–4 Local data area data structure
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
I UDS
I 01 040RPTNO
I 17 48 USER
I 120 125 START
This example indicates how to code the local data area data structure.
16–6
16.4.1 Accessing The LDA Using SUBR21

In addition to accessing the local data area via a data structure with a U
in column 18 of the data structure record, the MSI supplied subroutine
SUBR21 can be used within an RPG program to read and write the local
data area. This subroutine is supplied to provide compatibility with IBM
System/36 RPG II applications.
SUBR21 can be used to read data from the local data area or write data to
the local data area. To call SUBR21, the EXIT and RLABL operation codes
must be employed. SUBR21 requires that four parameters be passed using
the RLABL operation. The following example indicates how a SUBR21 call
must be formatted.
Example 16–5 Accessing the LDA via SUBR21
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
C EXIT SUBR21
C RLABL I_O 1
C RLABL TERMID 2
C RLABL RETCOD 1
C RLABL LDA
SUBR21 requires that four parameters be passed using RLABL operations

in the order displayed in Example 16–5. The field names used in
Example 16–5 are user defined and could be any valid RPG field name;
they are not reserved words. The RLABL parameters provide the following
information:
• I_O - A one-character, alphameric field which must contain an I or an
O. An I indicates that the LDA record is to be input to the program.
An O indicates that the LDA record is to be output from the program.
• TERMID - A two-character, alphameric field which returns the
terminal id.
• RETDOC - A one-character, alphameric field which returns the status
of the SUBR21 operation. A return code of 0 indicates a successful
operation. A return code of 1 or 2 indicates that the operation was
unsuccessful.
• LDA - A field or data structure which will receive information from
the local data area or pass it to the local data area. If the amount of
information to be transferred exceeds 256 characters, this entry must
be a data structure name.
16–7
16.5 Workstation Information Data Structure (INFDS)

The information data structure (INFDS) is a special data structure which
can be declared in a WORKSTN continuation line in the File Description
specifications. The INFDS is used to pass information back to a program
when an exception is processed. The INFDS is discussed in more detail in
the Migration RPG Screen Format Reference Manual.
Example 16–6 WORKSTN Information Data Structure
1 2 3 4 5 6
12345678901234567890123456789012345678901234567890123456789012345
*
FTERMINALCD F 120 WORKSTN
F KINFDS EXCPTN
.
.
.
IEXCPTN DS
I *STATUS STATUS
I *OPCODE OPCODE
I *RECORD RECORD
I *SIZE SIZE
I *MODE MODE
I *INP INP
I *OUT OUT
I 23 26 RCODE
This example indicates how to code an INFDS data structure.
16–8
17 Specifying An Alternate Collating Sequence Or A
Translation File
Each character processed by a program has a hexadecimal value associated

to it. The hexadecimal values of the ASCII character set used by VAX and
Alpha computers running the OpenVMS operating system are described in
Appendix A, Character Sets. The order in which the characters appear in
the ASCII reference table, which runs from lowest hexadecimal to highest
hexadecimal value, is called the collating sequence. When comparison
operations are carried out in a program, the collating sequence is used to
determine which character is greater.
The normal ASCII collating sequence used by an RPG program can be
changed in one of three ways:
• By coding an E in column 26 of the Control specification, specifying
that an EBCDIC collating sequence is to be used by the program for
all comparison operations.
• By coding an S in column 26 of the Control specification, specifying
that user-supplied collating values for one or more characters will be
provided in an alternate sequence table at the end of the program.
• By providing file translation parameters at the end of the program.
17.1 Specifying an Alternate Collating Sequence

To define a collating sequence that is different from the standard ASCII
or EBCDIC sequences, the hexadecimal value of each character whose
position in the sequence is to be changed must be specified. This is
accomplished by coding an S in column 26 of the Control specification and
coding an alternate sequence table at the end of the program.
17.1.1 Coding an Alternate Sequence Table

An alternate sequence table is coded at the end of an RPG program.
It must appear after the last RPG program specification and any file
translation parameter entries, but before any compile-time table or array
entries.
An alternate sequence table does not require an entry in the File
Description or Extension specifications.
An S must be specified in column 26 of the Control specification or the
alternate sequence table will not be recognized by the compiler.
An alternate sequence table is preceded by a specification containing two
asterisks and a blank in columns 1 - 3 (** ). The remaining columns in
this specification can be used for comments.
17–1
Specifying An Alternate Collating Sequence Or A Translation File
The following table describes the entries used to construct an alternate

sequence table record:
Table 17–1 Alternate Sequence Table Record Layout

Allowable
Column(s) Values Explanation
1-6 ALTSEQ Indicates that an alternate sequence record is
being specified.
7-8 Blank
9-10 Hexadecimal Specifies the hexadecimal value of the ASCII
value character which is to be changed.
11-12 Hexadecimal Specifies the new hexadecimal value of the
value character specified in columns 9 - 10.
13-16, Hexadecimal Use these columns like columns 9 - 12 to define
17-20, values additional characters which are to be assigned new
..., collating values. The first two characters represent
73-76 the ASCII hexadecimal value of the character that
is to be modified. The second two characters
represent the hexadecimal value to be assigned to
the character.
The first blank space in an ALTSEQ record terminates the ALTSEQ

entries for that record. The rest of the line can be used for comments.
If a large number of characters are to be redefined, additional ALTSEQ
records can be specified.
The last ALTSEQ record in an alternate sequence table must be followed
by another record containing two asterisks and a blank (** ) in columns
1 - 3.
See Appendix A, Character Sets, for a listing of the ASCII character set.
17–2
Example 17–1 Alternate Sequence Table
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H S
.
.
.
O*
** Alternate Sequence Table
ALTSEQ 2030 blank = 0
ALTSEQ 4131 A = 1
ALTSEQ 4232 B = 2
ALTSEQ 4A33 J = 3
ALTSEQ 4B34 K = 4
** End of Alternate Sequence Table
In this example, an alternate sequence table has been specified to modify

the collating sequence of five characters. In the first ALTSEQ record, the
hexadecimal value of 20 is being replaced by 30. This will equate a blank
character to the hexadecimal value for the character 0. Since the entry of
the hexadecimal value 30 is followed by a blank, all subsequent entries on
the line are treated as comments.
In the second ALTSEQ record, the hexadecimal value of 41 is being
replaced by the value 31. This will equate the ASCII character A to the
hexadecimal value for the character 1. The third ALTSEQ record equates
the hexadecimal value of character 2 (32) to the character B (42). The
fourth ALTSEQ record equates the hexadecimal value of character 3 (33)
to the character J (4A). The fifth ALTSEQ record equates the hexadecimal
value of character 4 (34) to the character K (4B).
The following section of sample code defines the same alternate sequence
table as the previous example. The only difference is that all of the
sequence modifications have been placed in one ALTSEQ record.
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H S
.
.
.
O*
** Alternate Sequence Table
ALTSEQ 2030413142324A334B34
** End of Alternate Sequence Table
17–3
17.2 Specifying File Translation Parameters

File translation parameters are used to translate characters in a record
when they are input or output by a program. Translation parameters
are commonly used to encrypt and decrypt data. An F must be coded
in column 43 of the Control specification to indicate that file translation
parameters are to be used.
File translation parameters can be specified for individual files within a
program, or one set of translation parameters can be specified for all files
used by a program.
File translation parameters can be specified for any input, output, update,
or combined file used by a program. When a record is input to a file with
translation parameters associated to it, the input record is translated
before it is made available to the program. When a record is output to a
file with translation parameters associated to it, the record is translated
before it is written out.
17.2.1 Coding File Translation Parameters

File translation parameters are coded at the end of an RPG program.
They must appear after the last RPG program specification and before the
alternate sequence table and any compile-time table or array entries.
File translation parameter entries do not require an entry in the File
Description or Extension specifications.
An F must be specified in column 43 of the Control specification or the file
translation parameters will not be recognized by the compiler.
File translation parameters are coded in a manner similar to that used to
code an alternate sequence table.
File translation parameters are preceded by a specification containing two
asterisks and a blank in columns 1 - 3 (** ). The remaining columns in
this specification can be used for comments.
The following table describes the entries used to construct a file translation
parameter record:
17–4
Table 17–2 File Translation Parameter Record Layout

Allowable
Column(s) Values Explanation
1-6 *FILES Indicates that the translation parameter is to apply
to all files in the program. If *FILES is specified,
columns 7 - 8 must be left blank.
1-8 File name Specifies the name of the file to be translated. This
entry must match an entry in columns 7 - 14 of a
File Description specification for an input, update,
output, or combined file.
9-10 Hexadecimal Specifies the hexadecimal value of a character
value which is to be translated on input and translated
back on output.
11-12 Hexadecimal Specifies the hexadecimal value to which the
value character specified in columns 9 - 10 is translated.
Also indicates a character which will be translated
back to the value specified in columns 9 - 10 if the
record is output.
13-16, Hexadecimal Use these columns like columns 9 - 12 to
17-20, values define additional characters which are to be
..., translated. The first two characters represent
73-76 the hexadecimal value of the input character that
is to be translated. The second two characters
represent the hexadecimal value to which the
character is to be translated for internal use by the
program. This value will be translated back to the
original value if the record is output.
The first blank space in a file translation record terminates the translation
parameter entries for that record. The rest of the line can be used for
comments.
If a large number of characters are to be translated, additional translation
parameter records can be specified.
The last file translation parameter record must be followed by another
record containing two asterisks and a blank (** ) in columns 1 - 3.
17–5
Example 17–2 File Translation Parameter Records
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H F
.
.
.
O*
** File Translation Parameter Records
*FILES 2A41 * = A
*FILES 2B42 + = B
*FILES 2C43 , = C
*FILES 2D44 - = D
** End of File Translation Parameter Records
In this example, file translation parameters have been specified to

translate four characters. In the first translation record, the hexadecimal
value of 2A is being replaced by 41, translating the asterisk character (*)
to the character A. Since the entry of the hexadecimal value 41 is followed
by a blank, all subsequent entries on the line are treated as comments.
In the second translation record, the hexadecimal value of 2B is being
replaced by the value 42. This will replace the plus character (+) with the
character B. The third translation record replaces the hexadecimal value
of 2C (,) with the value 43 (C). The fourth translation record replaces the
hexadecimal value of 2D (-) with the value 44 (D).
If a record is output, the characters described in columns 11 - 12 in the
translation records would be translated back to the values specified in
columns 9 - 10.
The following section of sample code defines the same file translation
parameter records as the previous example. In this example, the
translation parameters are associated to a single file and have all been
placed in one file translation parameter record.
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
H S
FHOPSCTH IPE F 80 DISK
.
.
.
O*
** File Translation Parameter Records
HOPSCTH 2A412B422C432D44
** End of File Translation Parameter Records
17–6
18 Using a SPECIAL Device File
18.1 Overview
This chapter describes how Migration RPG provides support for SPECIAL
device files. SPECIAL device file support will allow the programmer to
access files, devices, and services which are not directly supported by RPG
or the OpenVMS Record Management Services (RMS). SPECIAL device
files coded in an RPG program can be treated like normal file definitions
with Input and Output specifications. However, the programmer is
responsible for providing an external subroutine which serves as the
I/O interface for SPECIAL device files. The external subroutine used
by the SPECIAL device file is declared in the SPECIAL device File
specification. These subroutines, which can be written in any native
OpenVMS programming language, are responsible for transferring data
back and forth between the RPG program and the special device. RPG
provides support for up to 99 SPECIAL device files in a single program.
Migration RPG provides support for reading input from SYS$COMMAND
and writing output to SYS$OUTPUT via the supplied subroutine SUBR01.
18.2 File Description Specifications

For each SPECIAL device file, the programmer must code a File
Description specification. The File Description specification for use with
SPECIAL device files is described in Table 18–1.
18–1
Using a SPECIAL Device File
Table 18–1 File Specification

Column(s) Description Allowable Values
06 Specification Type F
07-14 File Name Standard RPG File Name
15 File Type I - Input File
O - Output File
U - Update File
C - Combined File
16 File Designation P - Primary File
S - Secondary File
D - Demand File
17 End of File E or blank
18 File Sequence A, D, or blank
19 File Format F
24-27 Record Length 0001-9999
40-46 Device SPECIAL
54-65 Subroutine Name Any valid OpenVMS name
or SUBR01
See Chapter 4, File Description Specification (F), for more detailed

information concerning coding a File Description specification.
18.2.1 File Description Continuation Specifications

If desired, the programmer can code one continuation specification
which declares an associated array name. This array can be used
as a programmer-defined memory area for communication between
the RPG program and the SPECIAL device file subroutine. The File
continuation specification for use with SPECIAL device files is described
in Table 18–2.
Table 18–2 File Continuation Specification Description

Column(s) Description Allowable Values
06 Specification Type F
53 Continuation Character K
54-59 Array Name Name of array defined in an
See Chapter 4, File Description Specification (F), for more detailed

information concerning coding a File Description specification.
18–2
18.3 Programming Considerations

18.3.1 Programming Features Supported
The following features are supported for SPECIAL device files under RPG:
• FORCE operation in the Calculation specifications.
• READ operation in the Calculation specifications.
• File translation (column 43 of the Header specification).
18.3.2 Migration RPG Program Logic

During the RPG program cycle, when a read or write operation to the
SPECIAL device file is requested, a call to the subroutine named in the
SPECIAL device File specification will be generated. The call will be in
the form of the Macro-32 instruction CALLS and will pass 1 parameter to
the SPECIAL device file subroutine. This parameter will be the address
of the File Control Data Structure described in Table 18–3. The operation
code is set to the proper value based on the current I/O operation before
control is passed to the subroutine.
Table 18–3 File Control Data Structure

Bytes(Hex) Description
00 Mask for external indicators
01 Operation Code
G - Get (Read)
P - Put (Write)
U - Update
C - Close File
02 RPG File Type
I - Input File
O - Output File
U - Update File
C - Combined File
03 Not used
04-0B RPG File Name
0C-0F Buffer Length
10-13 Buffer Address
14-17 Address of the Array Control Data Structure if a continuation
line was specified. If a continuation line was not specified,
then the value is 0.
18-1F Reserved for future use
If a continuation line is coded for the SPECIAL device file, then an Array
Control Data Structure will be created and the address placed in bytes
18–3
14-17 of the File Control Data Structure. The layout of the Array Control
Data Structure is described in Table 18–4.
Table 18–4 Array Control Data Structure

Bytes(Hex) Description
00-03 Array Buffer Address
04-07 Number of elements in Array
08-0B Size of each array element
0C-11 RPG Array Name
12-19 Reserved for future use
18.3.3 Coding the SPECIAL File Subroutine

When coding the SPECIAL device file subroutine, keep the following
points in mind:
• It is the responsibility of the SPECIAL device file subroutine to create
an access path to the special device the first time a call is made to the
routine.
• When the RPG program terminates execution, a call will be made to
the SPECIAL device file subroutine with the Close (C) operation code.
It will be the responsibility of the SPECIAL device file subroutine to
terminate the access path to the special device and return control to
the RPG program.
• After the subroutine has completed processing, it must place a
completion status in register R0 before returning control to the RPG
program. Table 18–5 lists the condition codes which RPG program
expects to be returned by the subroutine.
Table 18–5 Return Condition Codes

Code Description
0 Error - Error indicator in column 56-57 of a READ operation is set on, if
specified.
1 Normal completion.
3 End of File - EOF indicator in column 58-59 of a READ operation is set
on, if specified.
• If the file type is Input, then only the Get (G) operation code is
generated by the RPG compiler for the SPECIAL device file subroutine.
• If the file type is Output, then only the Put (P) operation code is
generated by the RPG compiler for the SPECIAL device file subroutine.
• If the file type is Update, then the operation codes in Table 18–6
are generated by the RPG compiler for the SPECIAL device file
subroutine.
18–4
Table 18–6 File Type Update - Operation Codes

I/O Operation Code Description
Get G For read operations
Update U For output operations
• If the file type is Combined, then the operation codes in Table 18–7
are generated by the RPG compiler for the SPECIAL device file
subroutine.
Table 18–7 File Type Combined - Operation Codes

I/O Operation Code Description
Get G For read operations
Put P For output operations. Note that with a
Combined file, the I/O buffer is blanked before
the output data is mapped into the buffer.
18.4 Sample Program

In Example 18–1, the Migration RPG program SPCDEV uses 5 SPECIAL
device files. The purpose of this program is to demonstrate 5 different
access methods using SPECIAL device files. The 5 access methods are:
1 Update primary with associated array, file SBR100 and array ARR1.
2 Input secondary with no associated array, file SBR200.
3 Combined demand with no associated array, file SBR300.
4 Update demand with associated array, file SBR400 and array ARR2.
5 Output with no associated array, file SBR500.
18–5
The program creates a report which shows the data read from each
file along with information on the status of program indicators (see
Example 18–7). The 5 subroutines which support the SPECIAL device
files are written in VAX C.
Example 18–1 Sample Migration RPG Program using SPECIAL Device
Files
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
H
FSBR100 UP F 45 45 SPECIAL TESTSBR100
F KARR1
FNORMAL IS F 50 50 DISK
FSBR200 IS F 45 45 SPECIAL TESTSBR200
FSBR300 CD F 50 50 SPECIAL TESTSBR300
FSBR400 UD F 55 55 SPECIAL TESTSBR400
F KARR2
FSBR500 O F 60 60 SPECIAL TESTSBR500
E*
E* Array used with SPECIAL device file SBR100
E*
E ARR1 2 5 0
E*
E* Array used with SPECIAL device file SBR400
E*
E ARR2 1 5 3
E*
E* Array contains the data supplied to SPECIAL device file SBR500
E*
E D500 1 3 60
ISBR100 NS 01
I 1 45 DATA1
INORMAL NS 02
I 1 50 DATA2
ISBR200 NS 03
I 1 45 DATA3
ISBR300 NS 04
I 1 50 DATA4
ISBR400 NS 05
I 1 55 DATA5
C*
C* Process the data from SPECIAL device file SBR100
C*
C 01 ADD 1 ARR1,1
C 01 ADD 2 ARR1,2
C 01 EXCPTOUT100
C*
C* Process the data from file NORMAL
C*
C 02 EXCPTOUTNML
C*
C* Process the data from SPECIAL device file SBR200
C*
C 03 EXCPTOUT200
C*
C* After all primary and secondary files have been processed,
C* process the demand files and output only files.
C*
CLR EXSR SUB300
CLR EXSR SUB400
CLR EXSR SUB500
18–6
Example 18–1 (Cont.) Sample Migration RPG Program using SPECIAL

Device Files
C*
C* Subroutine to read data from SPECIAL device file SBR300,
C* output the data read to the report and then write the
C* output data to the SPECIAL device file.
C*
CSR SUB300 BEGSR
CSR LOP300 TAG
CSR ADD 1 X 50
CSR SETOF 049091
CSR READ SBR300 9190
CSR EXCPTINP300
CSR EXCPTOUT300
CSRN90 GOTO LOP300
CSR ENDSR
C*
C* Subroutine to read data from SPECIAL device file SBR400,
C* and then update the SPECIAL device file.
C*
CSR SUB400 BEGSR
CSR LOP400 TAG
CSR SETOF 059091
CSR READ SBR400 9190
CSR EXCPTOUT400
CSRN90 GOTO LOP400
CSR ENDSR
C*
C* Subroutine to output data to the SPECIAL device file SBR500
C*
CSR SUB500 BEGSR
CSR Z-ADD1 I 10
CSR LOP500 TAG
CSR EXCPTOUT500
CSR ADD 1 I
CSR I COMP 3 9090
CSR 90 GOTO LOP500
CSR ENDSR
O*
O* Update the record read from the SPECIAL device file SBR100.
O* The first 24 bytes of the record will be overlayed.
O*
OSBR100 E OUT100
O 24 ’OVERLAY FIRST 24 CHARS *’
O*
O* Output a record to the SPECIAL device file SBR300.
O* Since this is a combined file the record buffer will blanked
O* before the output data is mapped into the buffer.
O*
OSBR300 E OUT300
O 24 ’COMBINED, REST S/B BLANK’
O X 30
O*
O* Update the record read from the SPECIAL device file SBR400.
O* The last 24 bytes of the record will be overlayed.
O*
OSBR400 E OUT400
O 55 ’OVERLAY LAST 24 CHARS **’
O*
O* Output data to the SPECIAL device file SBR500 from the array D500.
O*
OSBR500 E OUT500
O D500,I 60
O*
O* Create a report to display the results.
18–7

Device Files
O*
OREPORT H 202 1P
O OR OF
O 24 ’Test of SPECIAL device s’
O 48 ’upport Program: SPCD’
O 72 ’EV Page: ’
O PAGE Z 77
O*
O* Display the results of the update with some debugging information.
O*
O EF OUT100
O DATA1 45
O 24 ’OVERLAY FIRST 24 CHARS *’
O 80 ’SBR100’
O 01 86 ’01 ON’
O 02 92 ’02 ON’
O 03 98 ’03 ON’
O 04 104 ’04 ON’
O 05 110 ’05 ON’
O*
O* Display the data read from NORMAL with some debugging information.
O*
O EF OUTNML
O DATA2 50
O 80 ’NORMAL’
O 01 86 ’01 ON’
O 02 92 ’02 ON’
O 03 98 ’03 ON’
O 04 104 ’04 ON’
O 05 110 ’05 ON’
O*
O* Display the data read from SBR200 with some debugging information.
O*
O EF OUT200
O DATA3 45
O 80 ’SBR200’
O 01 86 ’01 ON’
O 02 92 ’02 ON’
O 03 98 ’03 ON’
O 04 104 ’04 ON’
O 05 110 ’05 ON’
O*
O* Display the data read from SBR300.
O*
O EF INP300
O DATA4 50
O*
O* Display the results of the write with some debugging information.
O*
O EF OUT300
O 24 ’COMBINED, REST S/B BLANK’
O X 30
O 80 ’SBR300’
O 01 86 ’01 ON’
O 02 92 ’02 ON’
O 03 98 ’03 ON’
O 04 104 ’04 ON’
O 05 110 ’05 ON’
O 90 116 ’90 ON’
O 91 122 ’91 ON’
O*
O* Display the results of the update with some debugging information.
O*
18–8

Device Files
O EF OUT400
O DATA5 55
O 80 ’SBR400’
O 55 ’OVERLAY LAST 24 CHARS **’
O 01 86 ’01 ON’
O 02 92 ’02 ON’
O 03 98 ’03 ON’
O 04 104 ’04 ON’
O 05 110 ’05 ON’
O 90 116 ’90 ON’
O 91 122 ’91 ON’
O*
O* Display the results of the write.
O*
O EF OUT500
O D500,I 60
** ARR2
AAA
BBB
CCC
DDD
EEE
** D500
This is the 1st output data record for SPECIAL device SBR500
This is the 2nd output data record for SPECIAL device SBR500
This is the 3rd output data record for SPECIAL device SBR500
18–9
In subroutine TESTSBR100 (Example 18–2), 3 data records are returned

as input to the RPG program. On the 4th read request, an End-of-File
status is returned to the RPG program. When an update request is
received, the data from the program buffer is written to SYS$OUTPUT
and the contents of the associated array are written to SYS$OUTPUT.
Example 18–2 SPECIAL Device Subroutine TESTSBR100
/* Test subroutine for SPECIAL device SBR100 */

typedef struct {
char *ary_buffer;
long num_elements;
long element_size;
char array_name[6];
long fut1;
long fut2;
} Ary_Control, *Ary_Control_Ptr;
typedef struct {
char ext_ind;
char op_code;
char file_type;
char not_used;
char file_name[8];
long buff_len;
char *buffer;
Ary_Control_Ptr array;
long fut1;
long fut2;
} File_Control, *File_Control_Ptr;
static int cnt = 1;
int TESTSBR100( File_Control_Ptr File_DS )
{
char outbuf[46];
char outary[11];
char input1[] = "This is the 1st data record. 111111111 SBR100";
char input2[] = "This is the 2nd data record. 222222222 SBR100";
char input3[] = "This is the 3rd data record. 333333333 SBR100";
/* If this is a call to close than return success */
if ( File_DS->op_code == ’C’ )
{
return 1;
}
/* Is this a call for input data, op-code of G */
18–10
Example 18–2 (Cont.) SPECIAL Device Subroutine TESTSBR100
if ( File_DS->op_code == ’G’ )
{
if ( cnt == 1 )
{
memcpy( File_DS->buffer, input1, 45 );
cnt++;
return 1;
}
if ( cnt == 2)
{
cnt++;
return 1;
}
if ( cnt == 3 )
{
cnt++;
return 1;
}
return 3; /* EOF */
}
/* Is this a call for update data, op-code of U */
if ( File_DS->op_code == ’U’ )
{
memcpy( outbuf, File_DS->buffer, 45 );
outbuf[46] = 0;
printf( "Buffer Data SBR100: %s\n", outbuf );
memcpy( outary, File_DS->array->ary_buffer, 10 );
outary[11] = 0;
printf( "Array Data SBR100: %s\n", outary );
return 1;
}
return 2; /* Else return error */
}
18–11

status is returned to the RPG program.

typedef struct {
char *ary_buffer;
long num_elements;
long element_size;
char array_name[6];
long fut1;
long fut2;
typedef struct {
char ext_ind;
char op_code;
char file_type;
char not_used;
char file_name[8];
long buff_len;
char *buffer;
long fut1;
long fut2;
static int cnt = 1;
{
char input1[] = "This is the 1st data record. 111111111 SBR200";
char input2[] = "This is the 2nd data record. 222222222 SBR200";
char input3[] = "This is the 3rd data record. 333333333 SBR200";
{
return 1;
}
18–12
{
if ( cnt == 1 )
{
cnt++;
return 1;
}
if ( cnt == 2)
{
cnt++;
return 1;
}
if ( cnt == 3 )
{
cnt++;
return 1;
}
return 3; /* EOF */
}
return 2; /* Else Return error */
}
18–13

as input to the RPG program. On the 4th read request, an Error status is
returned to the RPG program. When a write request is received, the data
from the program buffer is written to SYS$OUTPUT.

typedef struct {
char *ary_buffer;
long num_elements;
long element_size;
char array_name[6];
long fut1;
long fut2;
typedef struct {
char ext_ind;
char op_code;
char file_type;
char not_used;
char file_name[8];
long buff_len;
char *buffer;
long fut1;
long fut2;
static int cnt = 1;
{
char outbuf[51];
char input1[] = "This is the 1st data record. 111111111 SBR300 AAAA";
char input2[] = "This is the 2nd data record. 222222222 SBR300 BBBB";
char input3[] = "This is the 3rd data record. 333333333 SBR300 CCCC";
{
return 1;
}
18–14
{
if ( cnt == 1 )
{
cnt++;
return 1;
}
if ( cnt == 2)
{
cnt++;
return 1;
}
if ( cnt == 3 )
{
cnt++;
return 1;
}
return 2; /* Error */
}
/* Is this a call for output data, op-code of P */
if ( File_DS->op_code == ’P’ )
{
outbuf[51] = 0;
return 1;
}
}
18–15

status is returned to the RPG program. When an update request is
received, the data from the program buffer is written to SYS$OUTPUT
and the contents of the associated array are written to SYS$OUTPUT.

typedef struct {
char *ary_buffer;
long num_elements;
long element_size;
char array_name[6];
long fut1;
long fut2;
typedef struct {
char ext_ind;
char op_code;
char file_type;
char not_used;
char file_name[8];
long buff_len;
char *buffer;
long fut1;
long fut2;
static int cnt = 1;
{
char outbuf[56];
char outary[16];
char input1[] = "SBR400 This is the 1st data record. 111111111
**********";
char input2[] = "SBR400 This is the 2nd data record. 222222222
**********";
char input3[] = "SBR400 This is the 3rd data record. 333333333
**********";
{
return 1;
}
18–16
{
if ( cnt == 1 )
{
cnt++;
return 1;
}
if ( cnt == 2)
{
cnt++;
return 1;
}
if ( cnt == 3 )
{
cnt++;
return 1;
}
return 3; /* EOF */
}
/* Is this a call for update data, op-code of U */
if ( File_DS->op_code == ’U’ )
{
outbuf[56] = 0;
memcpy( outary, File_DS->array->ary_buffer, 15 );
outary[16] = 0;
printf( "Array Data SBR400: %s\n", outary );
return 1;
}
}
18–17
In subroutine TESTSBR500 (Example 18–6), when a write request is

received, the data from the program buffer is written to SYS$OUTPUT.

typedef struct {
char *ary_buffer;
long num_elements;
long element_size;
char array_name[6];
long fut1;
long fut2;
typedef struct {
char ext_ind;
char op_code;
char file_type;
char not_used;
char file_name[8];
long buff_len;
char *buffer;
long fut1;
long fut2;
{
char outbuf[61];
{
return 1;
}
/* Is this a call for update data, op-code of P */
if ( File_DS->op_code == ’P’ )
{
outbuf[61] = 0;
return 1;
}
}
18–18
Example 18–7 Report Generated by the Sample Migration RPG Program SPCDEV
Test of SPECIAL device support Program: SPCDEV Page: 1
OVERLAY FIRST 24 CHARS *ord. 111111111 SBR100 SBR100

01 ON
01 ON
01 ON
This is the 1st data record from NORMAL dat file NORMAL
02 ON
This is the 2nd data record from NORMAL dat file NORMAL
02 ON
This is the 3rd data record from NORMAL dat file NORMAL
02 ON
This is the 1st data record. 111111111 SBR200 SBR200
03 ON
This is the 2nd data record. 222222222 SBR200 SBR200
03 ON
This is the 3rd data record. 333333333 SBR200 SBR200
03 ON
This is the 1st data record. 111111111 SBR300 AAAA
COMBINED, REST S/B BLANK 00001 SBR300
04 ON
This is the 2nd data record. 222222222 SBR300 BBBB
04 ON
This is the 3rd data record. 333333333 SBR300 CCCC
04 ON
This is the 3rd data record. 333333333 SBR300 CCCC
90 ON 91 ON
SBR400 This is the 1st data recOVERLAY LAST 24 CHARS ** SBR400
05 ON
SBR400 This is the 2nd data recOVERLAY LAST 24 CHARS ** SBR400
05 ON
SBR400 This is the 3rd data recOVERLAY LAST 24 CHARS ** SBR400
05 ON
SBR400 This is the 3rd data recOVERLAY LAST 24 CHARS ** SBR400
90 ON
This is the 1st output data record for SPECIAL device SBR500
This is the 2nd output data record for SPECIAL device SBR500
This is the 3rd output data record for SPECIAL device SBR500
18–19
19 Coding Subprograms
Migration RPG permits RPG programs to call subprograms using the

CALL opcode. Subprograms can be written in Migration RPG or other
OpenVMS programming languages. This chapter describes the opcodes
used to call subprograms and pass data between the calling program and
the subprogram. Examples of RPG, COBOL, and Macro-32 subprograms
are included in the chapter.
19–1
Coding Subprograms
19.1 CALL Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank CALL Required Optional Blank Opt Opt
The CALL operation transfers control to the program or external routine

specified in factor 2. This program is referred to as the subprogram.
The CALL operation transfers control from the calling program to a
subprogram or external routine much as the BEGSR opcode transfers
control to a subroutine. Factor 2 must contain a character literal or a field
defined by the EXTRN opcode that names the subprogram. This must be
a valid OpenVMS program name. Factor 2 cannot be an array element
or data field name. The program specified in factor 2 can be written in
any OpenVMS programming language, including Migration RPG. When
specifying a program name which exceeds 8 characters, use the EXTRN
opcode to define a field which represents the program name.
The result field can contain the name of the parameter list associated with
a PLIST opcode. This enables the calling program to share parameters
with the subprogram. Individual parameters can also be specified
immediately following the CALL opcode using the PARM opcode. Both
the PLIST option and PARM statements can be used together with the
CALL opcode. See Chapter 11, Operation Codes, for a complete description
of the PLIST and PARM opcodes.
Factor 1, half adjust, and the resulting indicator in columns 54 and 55
must be blank. Any valid resulting indicator can be specified in columns
56 and 57 to be set on if the subprogram exits with an error status set.
Any valid resulting indicator can be specified in columns 58 and 59 to be
set on if the subprogram is a Migration RPG program and exits with the
LR indicator set.
19–2
Coding Subprograms
Example 19–1 CALL and PARM Opcode Usage - Example 1
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* This example displays the use of the CALL and PARM opcodes.
* The subprogram MAMMAL is called and passed the parameters FOX,
* BAT, WEASEL and WOLF. MAMMAL can then manipulate these fields
* and return their updated values to the calling program. After
* the MAMMAL CALL is processed, control returns to the next
* statement following the last PARM statement. Indicator 23
* will be set on if MAMMAL exits with an error status set.
*
C CALL ’MAMMAL’ 23
C PARM FOX
C PARM BAT
C PARM WEASEL
C PARM WOLF
19–3
Coding Subprograms
19.2 EXTRN Operation
Indicators Factor 1 Opcode Factor 2
7−8 9−17 18−27 28−32 33−63
Blk Blk Required EXTRN Literal
The EXTRN operation is used to define subprogram names exceeding eight

(8) characters in length for the CALL and FREE opcodes.
The EXTRN operation initializes the value of an alphameric field to a
link-time constant. It is used to assign a subprogram or external routine
name exceeding eight (8) characters in length to a field name which can be
used with the CALL opcode.
Factor 1 and factor 2 are required entries for this opcode. Conditioning
indicator entries (columns 9 - 17) are not permitted.
Factor 1 is used to name the field Migration RPG initializes, using the
value specified in factor 2. Factor 1 of the EXTRN operation is defined as
an alphameric field. This field can only be used with the CALL and FREE
opcodes and cannot be defined elsewhere in the program.
Factor 2 is used to name the external constant. A maximum of 31
characters can be used to name the constant. The constant must be
enclosed in apostrophes. The constant must conform to OpenVMS naming
conventions.
When using the EXTRN opcode to define a subprogram used in a CALL
statement, preceed the subprogram name with an underscore. The
underscore prefix is not needed if the subprogram name is provided to
the CALL statement as a literal in factor 2.
Example 19–2 EXTRN, Use of Underscore in Subprogram Name
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* The following CALL statements are equivalent.
* Both call the subprogram PROG1. Note the use
* of the underscore when defining the program
* name in an EXTRN statement.
*
C PRGNM EXTRN’_PROG1’
C CALL PRGNM
C CALL ’PROG1’
The underscore is used internally by Migration RPG to make the .ENTRY

point name for the program unique. This prevents conflicts with field
names within the program.
19–4
Coding Subprograms
Example 19–3 EXTRN, CALL, and FREE Opcode Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* This example depicts the use of the EXTRN opcode to define the
* subprogram BIG_AIRPLANE. BIG_AIRPLANE can then be referenced
* using the CALL and FREE opcodes.
*
C FLY EXTRN’_BIG_AIRPLANE’
.
.
.
C CALL FLY
.
.
.
C FREE FLY
19–5
Coding Subprograms
19.3 FREE Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank FREE Required Blank Blank Opt Blank
The FREE operation is used to remove an RPG subprogram from the

active list and ensure that program initialization (first cycle processing)
takes place the next time the subprogram is called.
Factor 2 must contain a character literal or a field defined by the EXTRN
opcode that names the RPG subprogram. Factor 2 cannot be an array
element or data field name. The subprogram specified in factor 2 must be
a Migration RPG program. Submitting a non-Migration RPG subprogram
to the FREE opcode will produce unpredictable results. When specifying a
subprogram name which exceeds 8 characters, use the EXTRN opcode to
define a field which represents the subprogram name.
An error indicator can be specified in columns 56 and 57. The error
indicator will be turned on if the FREE operation is submitted to an RPG
subprogram which has never been CALL’ed or which was already FREE’d
in a previous operation.
When a Migration RPG subprogram is called for the first time, normal
program initialization, such as file opens and field initialization, takes
place. After that, as long as the subprogram is not terminated normally
(LR indicator on) or abnormally (Halt indicator on or error), each time
the subprogram is called, it resumes operations where it left off at the
previous exit, very much like an internal subroutine. Thus, program
initialization is skipped during each additional call after the first one as
long as the subprogram has not been ended and the FREE opcode has
not been exercised against it. The FREE opcode provides the programmer
with another method to place a subprogram back into its initial starting
state. See Section 11.12.25, - FREE Operation, for more information on
terminating subprograms and the use of the FREE opcode.
Example 19–4 FREE Opcode Use
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* This example depicts the use of the FREE opcode to reinitialize
* the program SKI.
*
C CALL SKI
.
.
.
C FREE SKI
19–6
Coding Subprograms
19.4 PARM Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blk Optional PARM Optional Required Blank Blank Blank
The PARM operation is used to exchange parameters with a subprogram.

The PARM opcode is used to define parameters which will make up a
parameter list to be passed to a subprogram. The PARM opcode can be
used with the CALL and PLIST opcodes. PARM statements can appear
anywhere in the Calculation Specifications as long as they immediately
follow a CALL or PLIST statement. Up to 99,999 PARM statements can
follow a CALL or PLIST statement.
Conditioning indicator entries (columns 9 - 17) and resulting indicator
entries (columns 54 - 59) are not permitted on PARM statements.
Factors 1 and 2 are optional in a PARM statement. If specified, they must
have the same data type, alpha or numeric, as the result field. A literal
cannot be specified in factor 1.
The result field must contain a field, data structure, array, or array
element name. *ENTRY PLIST parameters cannot specify array elements
using fields as subscripts. The result field cannot contain a literal or table
name. *IN, *INxx, and *IN,xx entries are legal PARM fields, but should
be specified with caution as their settings reflect indicator settings. The
length and decimal position columns (49 - 52) can be used to define the
result field.
The fields specified in the result field of a PARM statement are passed by
descriptor to the subprogram. The fields can be manipulated and updated
by the subprogram. The subprogram then returns the updated values
to the calling program. If a subprogram terminates with an error, any
changes made to the fields specified in the PARM statements are still
returned to the calling program. To preserve a field from changes when
using it as a parameter, specify the field name in factor 2 of the PARM
statement and declare a temporary field name in the result field. The
contents of factor 2 will be copied to the result field when the subprogram
is called and the contents of the field in factor 2 will remain unaffected.
When a Migration RPG subprogram is called by another Migration RPG
program, the following steps occur:
1 In the calling program, the contents of factor 2, if specified, are copied
to the result field. Numeric fields are moved using a Z-ADD operation.
Alphameric fields are left-justified and blank-filled.
19–7
Coding Subprograms
2 In the subprogram, after any program startup and initialization

processing has run, the contents of the result fields in the *ENTRY
PLIST parameters are copied to factor 1, if factor 1 is specified.
Numeric fields are moved using a Z-ADD operation. Alphameric fields
are left-justified and blank-filled. Errors and warnings will be logged
if the parameter descriptors being passed to the subprogram do not
match the field types and sizes specified in the *ENTRY PLIST.
3 When the subprogram returns control to the calling program, the
contents of factor 2 in each *ENTRY PLIST parameter, if specified,
are copied to the result field. Numeric fields are moved using a Z-ADD
operation. Alphameric fields are left-justified and blank-filled. The
result field descriptors are passed back to the calling program.
4 Upon return to the calling program, the contents of the result fields
are copied to factor 1, if factor 1 was specified. Numeric fields are
moved using a Z-ADD operation. Alphameric fields are left-justified
and blank-filled.
Parameter fields are passed as fixed-length descriptors. The structure of

these descriptors is shown in the following figure.
Figure 19–1 Fixed-Length Descriptor Format
31 23 15 0
1 DTYPE LENGTH
POINTER
Migration RPG understands and uses five descriptor types.
Table 19–1 Descriptor Types and Use

Descriptor type Used to represent...
DSC$K_DTYPE_T Alphameric fields, data structures, arrays
DSC$K_DTYPE_NZ Trailing numeric or zoned-decimal fields
DSC$K_DTYPE_P Packed fields
DSC$K_DTYPE_W 2-byte binary fields
DSC$K_DTYPE_L 4-byte binary fields
When building packed and binary field descriptors in non-Migration

RPG subprograms, specify the actual packed or binary field length in the
parameter descriptor. Do not specify the unpacked or expanded binary
field length of the field. Migration RPG will only accept binary fields with
a length of 2 or 4 bytes.
19–8
Coding Subprograms
Fields in a Migration RPG program default to the following descriptor

types when passed as parameters in a PARM statement.
Table 19–2 Default Descriptor Types

Element type Definition Description Type
Array Alphameric Alphameric DSC$K_DTYPE_T
Array Element Alphameric Alphameric DSC$K_DTYPE_T
Numeric: Zoned-decimal, trailing Zoned-decimal DSC$K_DTYPE_NZ
numeric, packed, binary Trailing numeric DSC$K_DTYPE_NZ
Input Field Col 43: blank Col 52: blank Alphameric DSC$K_DTYPE_T
Col 43: blank Col 52: 0-9 Zoned-decimal DSC$K_DTYPE_NZ
Col 43: P Col 52: 0- 9 Trailing numeric DSC$K_DTYPE_NZ
Col 43: B Col 52: 0- 9 Packed decimal DSC$K_DTYPE_P
Col 43: B Col 52: 0- 9 Binary, 2 byte DSC$K_DTYPE_W
Binary, 4 byte DSC$K_DTYPE_L
Data Struct. Alphameric Alphameric DSC$K_DTYPE_T
DS Subfield Col 43: blank Col 52: blank Alphameric DSC$K_DTYPE_T
Col 43: blank Col 52: 0 - 9 Zoned-decimal DSC$K_DTYPE_NZ
Calc field Col 52: blank Alphameric DSC$K_DTYPE_T
Col 52: 0 - 9 Zoned-decimal DSC$K_DTYPE_NZ
When passing parameters to a Migration RPG program from a program

written in another language, fixed-length descriptors and one of the above
descriptor types must be used. If the incoming parameter is not a fixed-
length descriptor and does not use one of these descriptor types, the
Migration RPG program will issue an error message and abort.
When passing parameters between Migration RPG programs, the
parameter list passed by the calling program and the parameter list
specified in the subprogram’s *ENTRY PLIST must match data types and
should match sizes. Thus, if the first parameter passed to a program is a
5-byte, packed-decimal field, the first parameter in the calling program’s
*ENTRY PLIST should be a 5-byte, packed-decimal field.
It is always best to have the subprogram’s *ENTRY PLIST match the data
types, sizes, and number of parameters in the calling program’s parameter
list. However, the following exceptions apply when passing parameters
between Migration RPG programs:
• Parameters of the same data type, but different lengths, will generate
a warning message, but will be accepted by the subprogram. The
warning message can be suppressed by compiling the subprogram
using the /NOWARNING qualifier.
• A parameter defined as alphameric in one parameter list and numeric
in the other will be passed without error.
19–9
Coding Subprograms
• If the calling program passes more parameters than the subprogram

is prepared to accept, a warning message will be issued and the extra
parameters will be ignored. The warning message can be suppressed
by compiling the subprogram using the /NOWARNING qualifier. If the
calling program passes too few parameters, the subprogram will log an
error message and return to the calling program with an error status
set.
When passing parameters between Migration RPG programs, descriptor

creation, transfer, and checking is handled automatically by the Migration
RPG runtime routines.
Example 19–5 CALL and PARM Opcode Usage - Example 2
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* The following example illustrates the use of the PARM
* statement with the CALL opcode.
*
* The first parameter passes the contents of the field TAP
* to the subprogram and returns any modifications to
* the field TAP when the subprogram exits.
*
* The second parameter copies the contents of the field FOX
* to the field TROT before passing the contents of TROT to
* the subprogram. Since TROT is defined as a 10-byte,
* alpha field, the move will be left-justified and blank-
* filled. When the subprogram exits, TROT will contain
* the updated data.
*
* The third parameter passes the contents of the field CHARLE
* to the subprogram. When the subprogram exits, the
* updated contents of CHARLE will be copied to STON.
*
* The fourth parameter copies the contents of the field ROCK
* to the field AND when the subprogram is called. Since AND
* is defined as a 7-byte, numeric field, the copy is carried
* out using a Z-ADD operation. When the subprogram exits,
* the updated data in AND is Z-ADDed to the field ROLL.
*
C CALL ’DANCE’
C PARM TAP
C PARM FOX TROT 10
C STON PARM CHARLE
C ROLL PARM ROCK AND 70
19–10
Coding Subprograms
19.5 PLIST Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Blk Required PLIST Blank Blank Blank Blank Blank
The PLIST operation defines a unique symbolic name for a list of

parameters that is used in a CALL operation. The parameter list is
defined using the PARM opcode.
A PLIST operation can be specified anywhere within the Calculation
Specifications, including total time calculations and between subroutines.
It is customary to place PLIST groups at the beginning of the Calculation
Specifications as an aid to program readability.
A PLIST entry consists of a PLIST statement followed by one or more
PARM statements. The PARM statements define a list of parameters that
are to be passed to a subprogram. The PLIST is ended when an operation
other than a PARM is encountered.
Factor 1 must contain the name of the PLIST. A PLIST name can be one
to six characters in length and must be unique. If the parameter list being
defined is the entry parameter list for a subprogram, factor 1 must contain
*ENTRY. Only one *ENTRY PLIST can be defined in a program.
The elements in a parameter list supplied by the calling program and the
elements in a parameter list defined by a *ENTRY PLIST in a subprogram
should match in size and data type.
Example 19–6 PLIST and *ENTRY PLIST Usage
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* The *ENTRY PLIST is set up to accept and return three parameters
* from a calling program. The PLIST labeled FARM has three
* parameters assigned to it. A CALL statement in this program
* could reference the PLIST FARM and pass the FARM parameter list
* to another subprogram.
*
C *ENTRY PLIST
C PARM COWS
C PARM HOGS
C PARM CHICKN
*
C FARM PLIST
C PARM TRACTR
C PARM COMBIN
C PARM PICKUP
19–11
Coding Subprograms
19.6 RETRN Operation
7−8 9−17 18−27 28−32 33−42 43−48 54−55 56−57 58−59
Opt Opt Blank RETRN Blank Blank Blank Blank Blank
The RETRN operation causes a subprogram to return to the calling

program.
The RETRN operation is similar in function to the ENDSR (end
subroutine) statement. It tells a subprogram to exit immediately and
return control to the calling program. When a RETRN statement is
processed, the follow steps occur:
1 The halt indicators (H1 - H9) are checked. If a halt indicator is on, the
subprogram ends abnormally, closing all data files, and returning an
error status. If warning messages are enabled, a warning is issued to
the user’s terminal when the program returns.
2 If no halt indicators are on, the LR (last record) indicator is checked.
If LR is on, the subprogram ends normally, shutting down file streams
and deactivating the subprogram.
3 If neither the halt or LR indicators are on, the subprogram returns
control to the calling program. Data and indicator settings in the
subprogram are preserved.
Whether the subprogram exits normally, abnormally, or simply returns,

any parameters passed to the subprogram are returned to the calling
program. If a subprogram returns without ending, the next time it is
called, it will resume operations with the field and indicator settings which
were present when the subprogram last returned. A subprogram can be
reinitialized using the FREE opcode. Subprograms which end normally or
abnormally are automatically reinitialized the next time they are called.
19–12
Coding Subprograms
Example 19–7 RETRN Opcode Use
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* This subprogram is passed the parameters PHASER and
* PHOTON. After manipulation of these fields, it
* returns to the calling program without ending. Any
* values or indicator settings established each time
* this subprogram is run are retained as long as the
* calling program does not execute a FREE operation
* against it.
*
C *ENTRY PLIST
C PARM PHASER
C PARM PHOTON
*
C PHASER ADD ENERGY PHASER
C PHOTON ADD ENERGY PHOTON
*
C RETRN
19–13
Coding Subprograms
19.7 RPG Program Calling An RPG Subprogram Example

The following program examples demostrate how to code, compile, and
link an RPG calling program and an RPG subprogram. These programs
and a build procedure (CALL.COM) can be found in the S3X$EXAMPLES
directory. It is recommended that the sample programs and procedures be
copied to a different directory before working with them.
Example 19–8 RPG Calling Program - CALL.RPG
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
H
* CALL.RPG
*
* This program demonstrates passing data between
* a Migration RPG program and subprogram. The
* subprogram in this example is an external routine
* that left justifies an alphameric field.
*
FOUTPUT O F 80 DISK
*
* Create right justified alphameric fields.
*
C MOVE ’JACK’ FLD1 10
C MOVE ’RABBIT’ FLD2 15
*
* Output fields before they are left justified.
*
C EXCPTDATA
*
* Left justify alphanumeric fields.
*
C CALL ’LFTJST’
C FLD1 PARM FLD1 $FLD 256
C PARM 10 $SIZ 30
*
C CALL ’LFTJST’
C FLD2 PARM FLD2 $FLD
C PARM 15 $SIZ
*
* Output fields after they are left justified.
*
C EXCPTDATA
*
C SETON LR
*
OOUTPUT E DATA
O FLD1 10
O FLD2 30
19–14
Coding Subprograms
Example 19–9 RPG Subprogram - LFTJST.RPG
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
* SUBPROGRAM: LFTJST.RPG
*
* This routine left justifies an alphanumeric field.
*
* On Entry:
* FLD - Original alphanumeric field
* SIZE - Size of alphanumeric field
*
* On Return:
* FLD - Left justified field
*
E ORG 256 1
E LFT 256 1
*
I DS
I 1 256 FLD
I 1 256 ORG
*
* The *ENTRY PLIST defines the parameters that will be passed
* to the subprogram and that can be passed back to the
* calling program.
*
C *ENTRY PLIST
C PARM FLD
C PARM SIZE 30
*
* This block of code left justifies the input field.
*
IF C FLD IFNE *BLANKS
AND C ORG,1 ANDEQ*BLANK
*
C MOVEA*BLANKS LFT
C Z-ADD1 I 30
*
DOW C I DOWLESIZE
AND C ORG,I ANDEQ*BLANK
C ADD 1 I
END C END
*
C MOVEAORG,I LFT,1
C MOVEALFT ORG
*
END C END
*
* The RETRN opcode returns control to the calling
* program.
*
C RETRN
19–15
Coding Subprograms
The following commands can be used to build and run the CALL program.
Example 19–10 Commands Used to Build CALL Program
$ RPG CALL
$ RPG /NOEND LFTJST !Note the use of the /NOEND
$! !qualifier on the subprogram.
$ LINK CALL, LFTJST
$!
$ ASSIGN /USER CALL.DAT OUTPUT
$ RUN CALL.EXE
19–16
Coding Subprograms
19.8 RPG Program Calling A COBOL Subprogram Example

The following program examples demostrate how to code, compile, and
link an RPG calling program, a Macro-32 interface module, and a COBOL
subprogram. These programs and a build procedure (PASS1.COM) can
be found in the S3X$EXAMPLES directory. It is recommended that the
sample programs and procedures be copied to a different directory before
working with them.
Example 19–11 RPG Calling Program - PASS1.RPG
1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123456789
*
H
* PASS1.RPG
*
* This program demonstrates passing three parameters to
* the COBOL subprogram PASS1C.COB via the Macro-32
* interface module PASS1M.MAR.
*
FOUTPUT O F8000 80 DISK
*
* The PLIST opcode is used to define a parameter list.
*
C PARAMS PLIST
C PARM ALPHA1 12
C PARM ALPHA2 16
C PARM NUM1 60
*
C MOVE ’FOXTROT ’ALPHA1
C MOVEL’SUPER ’ALPHA2
C MOVE ’WOMAN ’ALPHA2
C Z-ADD10 NUM1
C EXCPTOUT
*
* The CALL opcode is executed, calling the PASS1M
* interface module and passing it the PARAMS
* parameter list.
*
C CALL ’PASS1M’ PARAMS
*
C EXCPTOUT
C SETON LR
*
OOUTPUT E OUT
O ALPHA1 12
O ALPHA2 30
O NUM1 40
19–17
Coding Subprograms
Example 19–12 Macro-32 Interface Module - PASS1M.MAR
.TITLE PASS1M
;This module converts the RPG parameters from a
;descriptor type to a reference type. Migration
;RPG passes external parameters by descriptor,
;but DEC COBOL only accepts external parameters
;by reference.
.PSECT $CODE,PIC,REL,CON,SHR,RD,NOWRT,EXE,NOVEC,LONG
.ENTRY _PASS1M,^M<>
MOVL AP, R10 ;Get stack pointer.
TSTL (R10)+ ;Skip count of number of
;elements on stack.
TSTL (R10)+ ;Skip FREE flag.
MOVAL @(R10), R0 ;Get address of first descriptor.
MOVAL @4(R0), R1 ;Get address of first parameter.
PUSHL R1 ;Push first parameter address
;onto stack.
TSTL (R10)+ ;Move to second parameter.
MOVAL @(R10), R0 ;Get address of second descriptor.
MOVAL @4(R0), R1 ;Get address of second parameter.
PUSHL R1 ;Push second parameter address
;onto stack.
TSTL (R10)+ ;Move to third parameter.
MOVAL @(R10), R0 ;Get address of third descriptor.
MOVAL @4(R0), R1 ;Get address of third parameter.
PUSHL R1 ;Push third parameter address
;onto stack.
CALLS #3, G^PASS1C ;Call COBOL subprogram.
RET
.END
19–18
Coding Subprograms
Example 19–13 COBOL Subprogram - PASS1C.COB
IDENTIFICATION DIVISION.
PROGRAM-ID. PASS1C.
AUTHOR. MSI
This program displays the data passed to it by
the Migration RPG program PASS1.
DATA DIVISION.
LINKAGE SECTION.
01 ALPHA1 PIC X(12).
01 ALPHA2 PIC X(16).
01 NUM1 PIC 9(6).
PROCEDURE DIVISION USING ALPHA1 ALPHA2 NUM1.
P0.
DISPLAY ALPHA1.
DISPLAY ALPHA2.
DISPLAY NUM1.
EXIT PROGRAM.
The following commands can be used to build and run the PASS1 program
on a VAX system.
Example 19–14 Commands Used to Build PASS1 Program on a VAX
System
$ RPG PASS1
$ COBOL PASS1C
$ MACRO PASS1M
$ LINK PASS1, PASS1M, PASS1C
$!
$ ASSIGN /USER PASS1.DAT OUTPUT
$ RUN PASS1.EXE
The following commands can be used to build and run the PASS1 program
on an Alpha or Integrity system.
Example 19–15 Commands Used to Build PASS1 Program on an Alpha

or Integrity System
$ RPG PASS1
$ COBOL PASS1C
$ MACRO /MIGRATE /UNALIGN /OBJECT=SYS$LOGIN:PASS1M -
SYS$LIBRARY:ARCH_DEFS.MAR + SYS$LOGIN:PASS1M.MAR
$ LINK PASS1, PASS1M, PASS1C
$!
$ ASSIGN /USER PASS1.DAT OUTPUT
$ RUN PASS1.EXE
19–19
20 Calling External Routines, EXIT and RLABL
20.1 Access to External Routines

External subroutines may be referenced from an RPG program in the
same manner as from an RPG program on the IBM System/36. This
involves coding into the calculation specifications an EXIT op code. Upon
encountering the EXIT op code, the RPG program will transfer control
to the subroutine named with the EXIT op code. If parameters are to
be passed to the external subroutine, they must be identified by RLABL
op codes immediately following the EXIT op code. The RLABL op code
utilizes the result field and may be used to pass either data fields already
defined within the program, new data fields that are being defined in
the RLABL specification, or indicators. Indicators must be specified in a
special format with IN as the first two positions of the result field followed
by the two-digit number of the indicator to be passed.
The EXIT statement is translated by the compiler and generates a CALLG
instruction. The CALLG instruction is used to transfer to the desired
subroutine and also pass the address of an argument list. Upon entry into
the external subroutine, the argument list pointer (AP) will be pointing to
the beginning of the argument list. The first long word on the argument
list will be the count of the number of entries contained within the list.
Each long word following the first contains the address of a field descriptor
describing the parameters being passed in the RLABL statements that
follow the EXIT. Note that the count of the number of long words in the
argument list includes the long word containing the count. For example,
if two RLABL statements are coded following an EXIT to indicate two
addresses being passed to an external subroutine, the count in the first
long word of the argument list will be three. This represents the total
number of long words in the argument list. In this example, the first long
word would be the count of the list entries, and the following two long
words would represent the address of the field descriptor entries.
The field descriptor entries contain a long word that describes the length
of the field, a one-byte flag, and a long word giving the address of the field.
The one-byte flag is used to indicate the format of the data field and will
contain an A for alpha, N for zoned numeric, or a P for packed. In the
case of indicators, this address will be the address of a one-byte data field
which will contain a value of zero if the indicator is off or a value of one if
the indicator is on.
The following example shows the statements from an RPG program that
can be used to access a subroutine and the corresponding assembler coding
for the external subroutine.
20–1
Calling External Routines, EXIT and RLABL
Example 20–1 RPG Program Calling External Subroutine
0 1 2 3 4 5 6
123456789012345678901234567890123456789012345678901234567890123
FCALLO O F 80 PRINTER
*
IDATAST DS
I 1 4 FLD1
I 6 9 FLD2
I 11 140NUM
*
C Z-ADD1 NUM
*
C EXIT EXTSBR
C RLABL NUM
C RLABL FLD1
C RLABL FLD2
*
C SETON LR
C EXCPT
*
OCALLO E LR
O NUM 10
O FLD1 20
O FLD2 30
20–2
Calling External Routines, EXIT and RLABL
Example 20–2 Sample Macro-32 External Routine
; This program is a sample external routine called from an

; RPG program. This routine expects to receive three four-
; byte fields from the calling program. This routine will
; then copy the contents of the first field into the second
; two fields.
;
EXTSBR:: .WORD 0 ;NO REGISTERS SAVED ON ENTRY
;
; ON ENTRY AP = LIST PTR
;
; LIST = +0 NUMBER ARGUMENTS IN LIST
; (IN THIS EXAMPLE 4 SINCE 3 ARGS PASSED)
; +4 ADDR OF 1ST FIELD DESCRIPTOR
; +8 ADDR OF 2ND FIELD DESCRIPTOR
; +12 ADDR OF 3RD FIELD DESCRIPTOR
;
; EACH DESCRIPTOR IS FORMATTED AS FOLLOWS:
; +0 .LONG X WHERE X = LENGTH OF DATA FIELD
; +4 .BYTE X WHERE X = FORMAT CODE FOR FIELD
; I.E. A = ALPHA
; N = ZONED NUMERIC
; P = PACKED NUMERIC
; +5 .ADDRESS X WHERE X = ADDRESS OF FLD
CMPB (AP),#4 ;IS ARG LIST 4 WORDS LONG
BNEQ 500$ ;NO - GIVE ERROR RETURN
MOVL 4(AP),R0 ;GET FLD 1 DESC ADDR
MOVL 5(R0),R1 ;GET ADDR OF FLD1
MOVL (R1),(R2) ;COPY FLD1 INTO FLD2
MOVL (R1),(R3) ;COPY FLD1 INTO FLD3
MOVL #1,R0 ;FLAG AS GOOD RETURN
RET ;RETURN TO CALLER
500$: CLRL R0 ;FLAG AS ERROR RETURN
RET
.END
20–3
21 Auto Report Features and Functions
The Auto Report Utility allows a programmer to build and compile RPG
programs from core modules and copybooks. The utility will consolidate
unordered copybooks, sort the RPG specifications into the correct order,
make programmer-specified modifications to the source code, and compile
the program. The following sections describe Auto Report features and
functions.
The Auto Report Utility is invoked with the AUTOC command. The
AUTOC command and its qualifiers are described in the Migration RPG
User’s Guide.
21.1 Compile Qualifier Specification (U)

An Auto Report compile can be qualified on the command line with
qualifiers following the AUTOC command, or it can be qualified by
parameters specified on a Compile Qualifier specification at the beginning
of the program. When a program is assembled by the Auto Report utility,
the first Compile Qualifier (U) specification encountered is processed.
Any subsequent Compile Qualifier specifications are ignored. Any valid
qualifiers found on the Compile Qualifier specification line will override
their counterpart qualifiers specified on the command line. The Compile
Qualifier specification is removed from the program after it has been
processed to avoid generating an error when the assembled program is
submitted to the RPG compiler.
The following parameters from the Compile Qualifier specification line are
recognized by Auto Report:
21–1
Auto Report Features and Functions
Table 21–1 Compile Qualifier (U) Specification Layout

Allowable
Parameter Column(s) Entries Explanation
Form Type 6 U Identifies the specification as an
Auto Report Compile Qualifier
specification. The first Compile
Qualifier specification encountered
will be processed. Any subsequent
Compile Qualifier specifications will
be ignored.
Retain Source 7 blank Delete generated source program
after it has been compiled.
C Retain generated source program.
This parameter will override the
/SAVE qualifier in the command
line.
Save File Name 8 - 24 logical:filename Optional logical:filename which
can be assigned to the generated
source file. The System/36 format
of library,member is converted
to the OpenVMS format of
logical:filename. The logical name
is optional, but, if specified, a file
name must be specified with it.
The file will automatically be given
a default extension of .AUT. If a
different extension is desired, leave
columns 8 - 24 blank and use the
/SAVE qualifier on the AUTOC
command line to specify the save
file name.
/SAVE=file name qualifier in the
command line.
Listing 30 blank, P Compiler listing file is to be
produced by the compiler.
B No compiler listing file is produced
by the compiler.
/LIST qualifier in the command line.
The remaining columns in the Compile Qualifier specification are not used
and should be left blank.
Example 21–1 depicts a Compile Qualifier specification used to establish
some program compilation parameters. The C in column 7 indicates that
the program source file assembled by the Auto Report Utility is to be
retained. The entry in columns 8 - 24 indicates that the assembled source
file is to be named VACATION and is to be placed in the PAYROLL area.
The program will be given a default extension of .AUT. The B in column 30
indicates that no listing file is to be produced by the Auto Report compile.
21–2
Example 21–1 Compile Qualifier (U) specification
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
UCPAYROLL:VACATION B
21.2 Copybooks
Copybooks are files of RPG specifications that are copied into the
generated RPG program by Auto Report and organized correctly depending
upon specification type. Code copied in from a copybook has a C placed
in column 5 of the RPG specification line in the generated source file to
identify it as copybook code.
Copybooks are included in an Auto Report program using the /COPY
statement. The /COPY statement must begin in column 7 of an RPG
specification line. The /COPY statement can be formatted in either of two
ways, as shown in Example 21–2.
Example 21–2 /COPY statement layouts
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
C*
C/COPY logical,filename
C/COPY logical:filename
The first /COPY format is compatible with that used on an IBM System/36.
The second format is a standard OpenVMS file designation. Auto Report
will recognize and process either format.
The logical name in the /COPY statement is optional, but the file name
must be specified. If a logical name is not specified, Auto Report will
search for the copybook in the programmer’s current default directory.
Copybook files are assumed to have an extension of .RPG. If the extension
is different, it must be specified in the /COPY statement. Auto Report will
accept up to 84 characters in a logical:filename string.
After the /COPY statement is processed, it is included in the generated
source file as a comment.
If Auto Report cannot access the specified copybook, an error will be logged
to the terminal and as a comment in the generated source file.
Example 21–3 depicts the /COPY statements used to include the copybooks
INVENTORY.RPG and DATE_SUB.SUBROUTINE from the GENERIC
area into a program. The first example uses the standard OpenVMS
file format for the file names. The second example uses the System/36
compatible file format, where the System/36 library name would be
equated to a OpenVMS logical name. Note that the .RPG extension
does not need to be declared on the INVENTORY copybook because it is
the default extension. The .SUBROUTINE extension must be included on
the DATE_SUB copybook because it is a non-standard extension.
21–3
Example 21–3 /COPY statement usage
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
I/COPY GENERIC:INVENTORY
C*
C/COPY GENERIC:DATE_SUB.SUBROUTINE
- or -
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
I/COPY GENERIC,INVENTORY
C*
C/COPY GENERIC,DATE_SUB.SUBROUTINE
21.3 File and Field Modifiers

The Auto Report Utility allows File Description and Input Field
specifications to be modified after they have been copied from a copybook.
A specification may only be modified once. An ‘M’ is placed in column 5 of
each line that has been modified by Auto Report.
21.3.1 File Description Specification Modifiers

A File Description specification which is included in a program from a
copybook can be modified by a File Description specification following
the /COPY statement within the core program. The File Description
specification coming from the copybook is considered the primary definition
and the File Description specification used to modify it is considered the
modifier specification. A File Description specification is considered a
modifier specification when the file name in columns 7 - 14 matches that
of a previous File Description specification. All non-blank entries in the
modifier specification are used to replace the corresponding entries in
the primary File Description specification. Blank entries in the modifier
specification do not affect the primary specification.
If an entry is to be blanked out in the primary File Description
specification, enter an ampersand (&) in the first position of the
corresponding entry in the modifier specification.
Example 21–4 depicts the modification of the File Description specification
for the file HOGWASH. Note the use of the ampersand (&) character to
blank out the block size entry and the M placed in column 5 after the File
Description specification has been modified.
21–4
Example 21–4 File Description specification modification
(Core program module)

1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
F/COPY SYSTEM_DATA:HOGWASH
FHOGWASH U & 140
FBACON ISE F 140 DISK
(Copybook module)
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
FHOGWASH IPE F4000 40 DISK
(Program generated by Auto Report)
1 2 3 4 5
12345678901234567890123456789012345678901234567890123456789
*
F*COPY SYSTEM_DATA:HOGWASH
MFHOGWASH UPE F 140 DISK
FBACON ISE F 140 DISK
21.3.2 Input Field Specification Modifiers

Input fields included from a copybook can be changed by modifier
specifications immediately following the /COPY statement. Input
record specifications cannot be modified. All Input field specifications
immediately following a /COPY statement are considered modifier
specifications. The first non-input field specification encountered following
a /COPY statement signals the end of input field modifiers to the Auto
Report Utility.
An input field included from a copybook can be changed by a modifier
specification with an I in column 6 and the same field name in columns
53 - 58. An input field can only be modified once. Subsequent modifier
specifications with the same field name are treated as duplicate field
definitions within the input record.
Input field modifier specifications replace, add, or blank entries in
the same fashion File Description specifications are modified. Input
field entries can be added or changed by placing the modified entry in
the corresponding columns of the modifier specification. Entries can
be blanked by placing an ampersand (&) in the first position of the
corresponding entry on the modifier specification. The following entries
can be changed by a modifier specification:
21–5
Table 21–2 Input Field Modifier Entries

Column(s) Entry
43 Alphameric, packed or binary
44 - 47 Start position
48 - 51 End position
52 Decimal position(s)
59 - 60 Control level (level break indicators)
61 - 62 Matching field indicator
65 - 70 Field indicators
Example 21–5 depicts the modification of several fields which are included
from a copybook. These changes include:
• The ACCTNO field is changed from a numeric to an alphameric field.
• The BALANC field has the high and equal indicators blanked out and
the low indicator changed to 99.
• The ACTDAT field is changed from a trailing numeric field to a
packed-decimal field. The field end position is also changed.
Example 21–5 Input field modification
(Core program module)

1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890
*
I/COPY BANKDATA
I 1 10&ACCTNO
I P 11 150BALANC & 99&
I P 16 19 ACTDAT
I 20 21 ACTCOD
I P 34 380PRVBAL
(Copybook module)
1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890
*
I 1 100ACCTNO
I P 11 150BALANC 101112
I 16 210ACTDAT 20
I 22 270LSTDEP
I 28 330LSTWTH
21–6
Example 21–5 (Cont.) Input field modification
(Program generated by Auto Report)

1 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890
*
I*/COPY BANKDATA
CI*
MI 1 10 ACCTNO
MI P 11 150BALANC 99
MI P 16 190ACTDAT 20
CI 22 270LSTDEP
CI 28 330LSTWTH
I 20 21 ACTCOD
I P 34 380PRVBAL
21.4 Generated Source File Organization

Specifications processed by the Auto Report Utility do not have to be in
order. The utility will sort the specifications into order after all copybooks
have been included. The Auto Report Utility will organize the output
source file in the following manner:
• (H) Header specifications
• (F) File Description specifications
• (E) Extension specifications
• (L) Line Counter specifications
• (I) Input specifications (Records and fields)
• (I) Input specifications (Data structures)
• (I) Input specifications (SAVDS data structure)
• (I) Input specifications (Local Data Area)
• (C) Calculation specifications
• (C) Calculation specifications (L0)
• (C) Calculation specifications (LR)
21–7
• (C) Calculation specifications (SR)

• (O) Output specifications
• Compile time table and array data
Note: If System/36 Telecommunications specifications are encountered

in a program, they are commented out when they are processed by
Auto Report, as they have no meaning under OpenVMS and would
generate errors during the RPG compile.
21.5 Limitations
The following limitations, in terms of the number of RPG source lines which can be processed,
apply to the Auto Report Utility:
Table 21–3 Auto Report Specification Limitations

RPG Specification Maximum Number of Lines Allowed
(H) Header 1000
(F) File Description 1000
(E) Extension 1000
(L) Line Counter 500
(I) Input (Record and 10,000
field specs)
(I) Input (Data 10,000
Structures)
(I) Input (SAVDS Data 10,000
Structure)
(I) Input (Local Data 10,000
Area)
(C) Calculation 10,000
(C) Calculation (L0) 10,000
(C) Calculation (LR) 10,000
(C) Calculation (SR) 10,000
(O) Output 10,000
Compile time table and 10,000
array data
21–8
All comments count towards the limit of the specification type under which
they are processed. Comment lines with a blank specified in column 6 are
assigned to the specification type last processed.
21–9
A Character Sets
This appendix contains the ASCII character set, the hexidecimal value of
each ASCII character, and the EBCDIC equivalent.
ASCII EBCDIC
Character Decimal Hexadecimal Decimal Hexadecimal
NUL 000 00 000 00
SOH 001 01 001 01
STX 002 02 002 02
ETX 003 03 003 03
EOT 004 04 055 37
ENQ 005 05 045 2D
ACK 006 06 046 2E
BEL 007 07 047 2F
BS 008 08 022 16
HT 009 09 005 05
LF 010 0A 037 25
VT 011 0B 011 0B
FF 012 0C 012 0C
CR 013 0D 013 0D
SO 014 0E 014 0E
SI 015 0F 015 0F
DLE 016 10 016 10
DC1 017 11 017 11
DC2 018 12 018 12
DC3 019 13 019 13
DC4 020 14 060 3C
NAK 021 15 061 3D
SYN 022 16 050 32
ETB 023 17 038 26
CAN 024 18 024 18
EM 025 19 025 19
SUB 026 1A 063 3F
ESC 027 1B 039 27
FS 028 1C 028 1C
GS 029 1D 029 1D
RS 030 1E 030 1E
A–1
Character Sets
ASCII EBCDIC
US 031 1F 031 1F
space 032 20 064 40
! 033 21 079 4F
" 034 22 127 7F
# 035 23 123 7B
$ 036 24 091 5B
% 037 25 108 6C
& 038 26 080 50
’ 039 27 125 7D
( 040 28 077 4D
) 041 29 093 5D
* 042 2A 092 5C
+ 043 2B 078 4E
, 044 2C 107 6B
- 045 2D 096 60
. 046 2E 075 4D
/ 047 2F 097 61
0 048 30 240 F0
1 049 31 241 F1
2 050 32 242 F2
3 051 33 243 F3
4 052 34 244 F4
5 053 35 245 F5
6 054 36 246 F6
7 055 37 246 F7
8 056 38 248 F8
9 057 39 249 F9
: 058 3A 122 7A
; 059 3B 094 6E
< 060 3C 076 4C
= 061 3D 126 7E
> 062 3E 110 6E
? 063 3F 111 6F
@ 064 40 124 7C
A 065 41 193 C1
B 066 42 194 C2
C 067 43 195 C3
D 068 44 196 C4
A–2
Character Sets
ASCII EBCDIC
E 069 45 197 C5
F 070 46 198 C6
G 071 47 199 C7
H 072 48 200 C8
I 073 49 201 C9
J 074 4A 209 D1
K 075 4B 210 D2
L 076 4C 211 D3
M 077 4D 212 D4
N 078 4E 213 D5
O 079 4F 214 D6
P 080 50 215 D7
Q 081 51 216 D8
R 082 52 217 D9
S 083 53 226 E2
T 084 54 227 E3
U 085 55 228 E4
V 086 56 229 E5
W 087 57 230 E6
X 088 58 231 E7
Y 089 59 232 E8
Z 090 5A 233 E9
[ 091 5B 074 4A
\ 092 5C 224 E0
] 093 5D 090 5A
^ 094 5E 095 5F
_ 095 5F 109 6D
` 096 60 121 79
a 097 61 129 81
b 098 62 130 82
c 099 63 131 83
d 100 64 132 84
e 101 65 133 85
f 102 66 134 86
g 103 67 135 87
h 104 68 136 88
i 105 69 137 89
j 106 6A 145 91
A–3
Character Sets
ASCII EBCDIC
k 107 6B 146 92
l 108 6C 147 93
m 109 6D 148 94
n 110 6E 149 95
o 111 6F 150 96
p 112 70 151 97
q 113 71 152 98
r 114 72 153 99
s 115 73 162 A2
t 116 74 163 A3
u 117 75 164 A4
v 118 76 165 A5
w 119 77 166 A6
x 120 78 167 A7
y 121 79 168 A8
z 122 7A 169 A9
{ 123 7B 192 C0
| 124 7C 106 6A
} 125 7D 208 D0
~ 126 7E 161 A1
DEL 127 7F 007 07
A–4
B CONSOLE, KEYBORD, And CRT Device Usage
CONSOLE, KEYBORD, and CRT are device names that are similar in
function to the WORKSTN device name. All of these designations refer
to terminal and keyboard activity as interpreted by the RPG program.
However, all of these devices differ in the ways that they can interface
with the associated program and in the manner in which output may be
displayed on the terminal.
CONSOLE, KEYBORD, and CRT device designations are included to
ensure continuing compatibility with older RPG applications developed on
non-OpenVMS platforms. Because these three device designations have
display limitations (as explained under each subheading), they are not the
recommended method of providing an interactive interface between the
user and the executing program.
Using a WORKSTN device is the recommended method of providing
interactive capability between the user and the executing program. It
offers greater flexibility in programming applications. A WORKSTN device
can be defined for both input and output operations. The programmer can
specify which fields on the display are input fields, which are output fields,
and which are both input and output fields. (See the Migration RPG
Screen Format Reference Manual for information on the WORKSTN device
and how to program workstation screen specifications.)
B–1
CONSOLE, KEYBORD, And CRT Device Usage
B.1 Using a CONSOLE Device

Using the CONSOLE device in an RPG program enables the user to input
data to an executing program from a display terminal. Display screen
formats are automatically generated from the RPG input specifications
to prompt the user for the data needed. The data entered by the user is
returned to the RPG program as a record of contiguous bytes of data. This
data is received as if it had been read from a record-oriented device.
B.1.1 Limitations of a CONSOLE device

The following restrictions apply to programs using a CONSOLE device:
• A CONSOLE device can only be used as an input file.
• Records cannot be displayed (or output) using a CONSOLE device.
• Only one CONSOLE device can be defined per program.
• A CONSOLE device requires a VTxxx compatible display at execution.
• No other devices relating to terminal I/O may be used.
• The maximum alphameric field length is 66 characters.
• The maximum numeric field length is 15 digits.
• The maximum number of fields in a record type is 80.
• The maximum number of record types for a CONSOLE device file is
20.
B.1.2 Coding a CONSOLE Device

The following sections describe how to code the File Description and Input
specifications which define a CONSOLE device file.
B.1.2.1 Console Device File Description Specification

A CONSOLE file requires one File Description specification. The File
Description specification must be coded according to the following criteria:
Table B–1 Rules for Coding CONSOLE Device File Description

Specification
Column Allowable
Number Values Explanation
7-14 File name Must contain the name of the CONSOLE device file.
15 I Input File (Required entry)
16 P Primary File
B–2
Table B–1 (Cont.) Rules for Coding CONSOLE Device File Description
Specification
Column Allowable
S Secondary File
D Demand File
R Record Address File
Blank
17 E Indicates that every record must be processed before the

program can end. Column 16 must contain either P, S, or
R.
Blank Indicates that the program can end without processing
every record. It must be blank if column 16 contains a D.
18 A Indicates ascending record order. Allowed only if column

16 identifies a P (primary) or S (secondary) file.
D Indicates descending record order. Allowed only if column
16 identifies a P (primary) or S (secondary) file.
Blank Indicates that record sequence is not checked.
19 F or Blank Defines fixed file format.
20-23 Block Length must be equal to the record length defined in

length columns 24 through 27.
Blank Accepted value. Defaults to record length.
24-27 Record This value must be the same as the highest ending
length position defined for the CONSOLE file on the input
specifications.
29-30 Blank Required if column 16 contains either P, S, or D.

Key length If column 16 contains an R, then columns 29 and 30 must
contain the length of the key field to the file.
31 Blank Used for record address files only. Required if the key
fields in the record address file are the same as the key
fields in the indexed file.
A Used for record address files only. Identifies indexed files
with zoned-decimal or trailing numeric key fields.
B–3
Table B–1 (Cont.) Rules for Coding CONSOLE Device File Description
Specification
Column Allowable
39 Blank Reserved for extension codes. Required if column 16

contains P, S, or D.
E Reserved for extension codes. Required if column 16
contains an R.
40-46 CONSOLE This field must contain CONSOLE as the device name.
TTY Required entry if column 15 contains D. Program must
then be manually linked to runtime library.
71-72 U1-U8 Optional use of external indicator values.
B.1.2.2 Console Device Input Specifications

Input specifications are not allowed for record address files. Record
address files can be easily identified by checking for the value of R in
column 16 of the File Description specification.
Input specifications are required for primary, secondary, or demand files.
Each input record must be coded according to the following criteria:
Table B–2 Rules for Coding CONSOLE Device File Input Record
Specifications
Column Allowable
7-14 File name Must contain the name of the CONSOLE device file.
This name must match the name in the associated File
Description specification.
14-15 OR Optional use of line to indicate a relationship between

record-identifying indicators or record types.
15-16 Alphabetic Can contain any two alphabetic characters if sequence

characters checking of input records is not desired.
Numeric If sequence checking is desired, code a numeric entry
entry (between 01 and 99) in columns 15 and 16.
17 Blank Must be blank if columns 15 and 16 contain alphabetic

entries.
B–4
Table B–2 (Cont.) Rules for Coding CONSOLE Device File Input Record
Specifications
Column Allowable
1 If the record type can consist of only one record and

columns 15 and 16 contain numeric entries.
N If the record type can consist of one or more records and
columns 15 and 16 contain numeric entries.
18 Blank Must be blank if columns 15 and 16 contain alphabetic

entries.
O Can contain the letter O (to indicate record type is
optional) if columns 15 and 16 contain numeric entries.
19-20 01-99 Must contain a unique record-identifying indicator to

identify which command key will be used by the user
to select this record type. Each record type requires a
different indicator value.
24 1 Must contain this value to indicate that the record

identification code starts in position 1.
26 C Indicates that the entire character is used for the record

identification.
27 character Indicate expected character in position 1 of this record

format.
28-34 Used as Fill as needed for record identification in position 2.

needed
B–5
Table B–3 Rules for Coding CONSOLE Device File Input Specifications
Column Allowable
44-47 Numeric entry Must contain record location where field begins.
48-51 Numeric entry Must contain the record location where the field ends.
Subfields can redefine a larger field, but they cannot
overlap previously defined fields.
53-58 Field name Must contain a unique field name from one to six
alphameric characters. This name will display as the
prompt.
59-60 Blank Field not used.

L1-L9 Optional use of control-level indicators if this has been
defined as either a primary or secondary file.
61-62 Blank Field not used.

M1-M9 Optional use of matching record indicators if this has
been defined as either a primary or secondary file.
B–6
B.1.3 Automatic Generation of Display Screen Formats

To build an executable image of an RPG program with a CONSOLE device,
first compile the RPG program with the Migration RPG compiler. Proceed
with the next step only if no errors occurred during the compilation
process.
The next step involves invoking the RPG CONSOLE format generator,
RPGCON. RPGCON expects an input of RPG source code. It reads the
File Description and Input specifications for the CONSOLE file and
outputs a file of S & D specifications describing the screens to be used
during program execution.
RPGCON can be invoked in either of the following ways:
$ RPGCON ABC
- or -
$ RPGCON
CON>ABC
where "ABC" is the name of the file containing the RPG source code
statements. The following rules apply when using RPGCON:
• An extension of .RPG is assumed for the input file. If this is not the
file name extension, then the extension must be given explicitly.
• The output file will be given the same name as the input file, with
FM appended to the file name. The output file will have an extension
of .FRM to indicate screen format file. For example, if the RPG
source file being processed by RPGCON was labeled FOZZ.RPG, the
screen format file produced by the RPGCON Utility would be labeled
FOZZFM.FRM.
The output file generated by the RPGCON Utility contains screen format
source code (S & D specifications) and may be edited (or customized) as
much as necessary. This file must then be compiled using the screen
format generator (SFG).
Following the compilation of the screen format file, an executable image
is produced by linking the program object generated by the RPG compiler
and the screen object generated by the screen format generator.
The following example indicates how a CONSOLE program would be
compiled and linked to produce an executable image.
Example B–1 Compiling and linking a CONSOLE program
$ RPG FOZZ
$ RPGCON FOZZ
$ SFG FOZZFM
$ LINK FOZZ,FOZZFM
B–7
B.1.4 Displaying CONSOLE Device Files

The display screen generated by the preceding steps will consist of a top
line containing control information for the user and data fields arranged
on lines 2 through 23.
The data fields will display in four different formats, according to the
following criteria:
Table B–4 CONSOLE Device File Display Formats

Format Explanation
One Column Used whenever the number of fields being prompted is less than
24.
Two Columns Used whenever the number of fields being prompted is between
24 and 46.
Three Columns Used whenever the number of fields being prompted is between
47 and 69.
Four Columns Used whenever the number of fields exceeds 69.
RPG does not support the use of multiple record formats with CONSOLE
devices. All screen formats generated by the utility RPGCON are given
the format name XX. This means that only the first format in the screen
format file will be displayed to the user for the purposes of inputting
data. If multiple record types have been defined for the CONSOLE device,
the following message will be displayed when the screen format file is
compiled:
** WARNING ** 100 - Duplicate screen name, XX in S specification
The following sections describe the fields which appear on the control line
and how to interact with a CONSOLE screen.
B.1.4.1 Record Identification Code

The first field displayed on line one is the record identification code of
the record for which data is being prompted. This field contains 1 or 2
characters, as defined in the input record specification.
B.1.4.2 Record Identifying Indicator

The second field displayed on the first line is the record identifying
indicator for the input format being displayed. This field is designated
output only and cannot be modified by the user.
The third field on line one is another output only field which displays the
record identifying indicators for record types other than the one currently
selected.
B–8
B.1.4.3 Data Fields

Data fields are generated in either a one-, two-, three-, or four-column
format, depending on the number of fields and each field’s size. When a
data format is displayed, the cursor is always positioned on the first data
field of the format. Cursor control keys may be used to move from one field
to another. No data is returned to the RPG program until the PF4 key is
pressed. End-of-file is indicated by entering a CMD12 ( PF1 + = ). This
returns end-of-file to the RPG program and sets on indicator KL.
The prompt for each data field consists of
• the field name as defined in the 6-character field name of the input
specifications,
• an A for an alphameric field or an N for a numeric field, and
• the field length.
Alphameric fields will specify length. Numeric fields will specify length
and decimal positions, with a period separator between the two items.
B–9
B.2 Using a CRT Device

A CRT device can be used to display information to a user’s screen. It
cannot be used to input data. A CRT device requires the coding of a
File Description specification and Output specifications. A CRT device is
normally associated to the terminal which invokes the CRT program.
B.2.1 Limitations of a CRT Device

The following restrictions apply to a program using a CRT device:
• A CRT device can only be used as an output file.
• A CRT device can only display information.
• A CRT device requires a VTxxx compatible display at execution.
• The maximum record length for a CRT device file is 79 bytes.
B.2.2 Coding a CRT Device File

The CRT device file is designed to do the following:
• display messages and instructions to the user
To use a CRT device in an RPG program, a File Description specification

and Output specifications must be coded.
The following sections describe how to define and use a CRT device.
B.2.2.1 CRT Device File Description Specification

Each CRT device requires one File Description specification. Each File
Description specification must be coded according to the following criteria:
B–10
Table B–5 Rules for Coding CRT File Description Specification

Column Allowable
7-14 File name Must contain the name of the CRT file.
15 O Output File (Required entry)

24-27 Record Must contain the length of the largest record to be output.
length
40-46 CRT This field must contain CRT as the device name.
71-72 U1-U8 Optional use of external indicator values.
B–11
B.2.2.2 Output Specifications

The following rules apply for coding the Output specifications associated to
a CRT device file:
Table B–6 Rules for Coding CRT Output Specification

Column Allowable
7-14 File name Must contain the name of the CRT device file.
15 H Heading
D Detail
T Total
E Exception
17 0-9 Indicates how many lines to skip before writing the

current line.
18 0-9 Indicates how many lines to skip after writing the

current line.
19-20 01 Clear the display before writing a record.

Blank Do not clear the display before writing a record.
23-31 Indicators Optional use of conditioning indicators.
32-37 EXCPT Name Optional entry. If used, column 15 must contain an

E.
B–12
Table B–7 Rules for Coding CRT Output Field Specifications

Column Allowable
23-31 Indicators Optional use to condition output.
32-37 Alphameric Optional entry. Can identify the field names to be

Characters output.
38 Edit code Optional entry of predefined edit code.
39 B Optional entry to indicate resetting field to blank or

zero.
40-43 Numeric Entry to indicate ending position of entry.

Value
45-70 Alphameric Optional entry to contain either an edit word or a

Characters literal constant.
B.2.2.3 Displaying Data Using a CRT Device

Data is displayed to the user’s screen during normal detail and total-time
output operations. It can also be displayed during calculations using the
EXCPT operation and exception output records.
B–13
B.3 Using a KEYBORD Device

A KEYBORD device can be used as an input and output device. A
KEYBORD device requires a File Description specification, but does
not use Input or Output specifications. Instead, the KEYBORD device
is referenced by the SETnn and KEYnn operation codes. The KEYBORD
device is normally associated to the terminal which invokes the KEYBORD
program.
B.3.1 Limitations of a KEYBORD Device

The following restrictions apply to a program using a KEYBORD device:
• A KEYBORD device can be used for both input and output operations,
but only in conjunction with the KEYnn and SETnn operations.
• A KEYBORD device requires a VTxxx compatible display at execution.
• The maximum length for an alphameric field is 79 characters.
• The maximum length for a numeric field is 15 digits.
B.3.2 Coding a KEYBORD Device File

To use a KEYBORD device in an RPG program, a File Description
specification must be coded. Input and output specifications are not
used for a KEYBORD device. Instead, SETnn or KEYnn operations are
coded in the Calculation specifications to manipulate the necessary data.
B.3.2.1 KEYBORD Device File Description Specification

Each KEYBORD device requires one File Description specification. Each
File Description specification must be coded according to the following
criteria:
Table B–8 Rules for Coding KEYBORD Device File Description

Specification
Column Allowable
7-14 File name Must contain the name of the KEYBORD device file.
15 I Input File (Required entry)
16 P Primary File. If KEYBORD is defined as a primary file,

then no other files can be used as either primary or
secondary files.
B–14
Table B–8 (Cont.) Rules for Coding KEYBORD Device File Description
Specification
Column Allowable
D Demand File. If KEYBORD is defined as a demand file,

then the KEYnn operation code is used to read the records
from the file.
19 F or Blank Defines fixed file format.

24-27 Record Must contain the length of the largest field to be entered.
length
40-46 KEYBORD This field must contain KEYBORD as the device name.
B.3.2.2 Calculation Specifications

Although a KEYBORD file is an input/output file, it does not use Input
specifications. Instead, input and output data are handled by the SETnn
and KEYnn operations within the Calculation specifications. The KEYnn
operation causes a pause in calculations, enabling the user to enter data.
The SETnn operation can be used to display data and prompt for command
key input. The SETnn and KEYnn operations are described in detail in
Chapter 11, Operation Codes.
B–15
B.3.2.3 KEYnn Operation

The KEYnn operation provides the following functionality:
• Display the contents of the the field, literal, table, or array element
coded in factor 1
• Display user level message members (01 - 99) if specified in the SETnn
operation
• Enter data into the field specified in the result field
To use the KEYnn operation, the following rules apply for coding the
Table B–9 Rules for Coding KEYBORD Calculation Specification for a

KEYnn Operation
Column Allowable
7-8 Control-level Optional use of L1-L9, AN, OR, or blanks.
Indicator
9-17 Conditioning Optional use of indicators, command-key indicators

Indicators (KA-KN, KP-KY), or blanks.
18-27 Alphameric Can contain constant, literal, field name, table

characters or array element to be displayed. Entries in
these columns cause informational prompts to be
displayed to assist in data entry. Entries in these
columns override any entries made in columns
31-32.
28-30 KEYnn Must contain KEYnn operation code.
31-32 Message ID Optional numeric entry between 01 and 99

that corresponds to a predefined message. An
entry is required in columns 31 and 32 when
columns 18-27 are blank. A computer-generated
prompt will display the following message during
program execution if the user-defined message
is inaccessible for any reason. ( RTS-030- MIC
Message File not found )
33-42 Blank Must be blank.
43-48 Alphameric Optional entry to define name of field to be

characters entered.
B–16
Table B–9 (Cont.) Rules for Coding KEYBORD Calculation Specification

for a KEYnn Operation
Column Allowable
49-51 Field Length Required entry if not defined elsewhere in the RPG
program.
52 Blank Alphameric field must have a blank in this column.

0-9 Numeric fields require an entry that defines the
number of decimal positions.
54-59 01-99 Optional entry to test the condition of a field.
B.3.2.3.1 Bypassing a KEYnn Operation

The KEYnn operation causes a pause in program execution while waiting
for the user to enter a response. To bypass the KEYnn operation and
continue, the user can press the Enter , Return , or PF4 key. If a KEYnn
operation is bypassed, the contents of the result field are initialized to
blanks or zeros.
B–17
B.3.2.4 SETnn Operation

The SETnn operation provides the following functionality:
• Display the contents of the the field, literal, table, or array element
coded in factor 1
• Display user level message members (01 - 99) if specified in the SETnn
operation
• Enter the command keys identified in columns 54 - 59
To use the SETnn operation properly, the following rules apply for coding
the Calculation specification:
Table B–10 Rules for Coding KEYBORD Calculation Specification for

SETnn Operation
Column Allowable
7-8 Control-level Optional use of L1-L9.
Indicator
9-17 Conditioning Optional use of indicators, command-key indicators

Indicators (KA-KN, KP-KY), or blanks.
18-27 Alphameric Can contain constant, literal, field name, table

characters or array element to be displayed. Entries in
these columns cause informational prompts to be
displayed to assist in data entry. Entries in these
columns override any entries made in columns
31-32.
28-30 SETnn Must contain SETnn operation code.
31-32 Message ID Optional numeric entry between 01 and 99

that corresponds to a predefined message. An
entry is required in columns 31 and 32 when
columns 18-27 are blank. A computer-generated
prompt will display the following message during
program execution if the user-defined message
is inaccessible for any reason. ( RTS-030- MIC
Message File not found )
B–18
Table B–10 (Cont.) Rules for Coding KEYBORD Calculation

Specification for SETnn Operation
Column Allowable
54-59 Command Keys Optional entry to define up to three command keys

that can be used when the program is executing
this operation. If a command key that has been
coded on this line is used, that indicator remains
on until it is specifically turned off by a SETOF
operation or until it is used again in a SETnn
operation.
B–19
Index
ALTSEQ • 17–2
A AND
input specifications • 7–2, 7–3, 7–4, 7–8, 12–6
output specifications • 9–2
Adding records • 13–24
record identification
Addition • 11–9
example • 12–7
ADD operation code
ANDxx operation code
example • 12–11
general information • 11–3, 11–7
general information • 11–1
rules • 11–11
rules • 11–9
Arithmetic operation codes • 11–1
ADD option
rules • 11–1
signs • 11–2
addrout files
Arithmetic operations • 11–136
File Description specification • 13–17
addition • 11–9
Addrout files
division • 11–34
creating • 13–16
remainder • 11–94
example • 13–16, 13–19
multiplication • 11–92
Extension specification • 13–18
square root • 11–124
file designation • 4–6
subtraction • 11–125
function • 13–16
zero add • 11–137
record length • 4–8
zero subtract • 11–138
rules for specifying • 13–17
Array elements
specifying
outputting • 15–34
key length • 4–15
searching • 15–30
Alphameric data
Array name
defining fields
alternate entry • 5–8
example • 10–3
primary entry • 5–4
Alphameric fields
Arrays • 15–15
comparing • 11–3
alternate format • 15–21
Alphameric literals
compile-time • 15–17
factor 1
compile-timed
calculation specifications • 8–4
delimiter • 15–17
factor 2
array input records • 15–18
Alternate collating sequence • 3–5
definition • 15–15
alternate sequence table
elements
coding • 17–1
loading
specifying • 17–1
input specifications • 7–11
Alternate format
execution-time • 15–18
arrays • 15–21
*IN,xx indicators • 12–31
in calculations • 15–26
pre-execution-time • 15–21
example • 15–27
related • 15–21
indexed
Alternate keys
LOKUP operation code • 11–74
*IN indicators • 12–31
Alternate sequence table
input records
coding • 17–1
example • 15–18
Index–1
Index
Arrays (cont’d) Arrays (cont’d)

loading transferring data • 11–5
input specifications • 7–11 types
loading time compile-time • 15–17
selecting • 15–16 execution-time • 15–18
LOKUP operation code • 11–74, 15–29 pre-execution-time • 15–18
example • 15–30 updating • 15–32
MOVEA operation code • 15–31 using • 15–15
moving data • 11–5, 15–31 writing
names • 10–9 array elements • 15–34
non-indexed entire arrays • 15–33
LOKUP operation code • 11–74 XFOOT operation code
operations example • 15–28
LOKUP • 11–71 Arrays(XS)sorting • 11–122
outputting Arrays(XS)summing elements
array elements • 15–34 XFOOT • 11–136
entire arrays • 15–33 ASCII character set • A–1
permanent update • 15–32 Asterisk protection • 9–25
pre-execution-time • 15–18 AUTOC
referencing • 15–25 Auto Report Utility
array elements • 15–25 See also: Migration RPG User’s Guide • 21–1
entire arrays • 15–25 Automatic overflow • 14–7
related • 15–19 Auto Report Utility
searching • 11–74, 15–29 compile qualifiers
example • 15–30 U specification • 21–1
rules for specifying • 15–29 file description specification modifiers • 21–4
searching for elements • 15–30 Input specification modifiers • 21–5
sequencing • 11–72
set up and usage example • 11–76
specifying • 4–4, 15–21
data format B
primary entry • 5–6 BEGSR operation code
decimal positions general information • 11–4
alternate entry • 5–10 rules • 11–13
primary entry • 5–7 Binary data
elements • 15–27 defining fields
from-file name • 5–2 example • 10–5
length of entry Binary data types
alternate entry • 5–9 longword • 10–4
primary entry • 5–6 specifying
names tables and arrays
alternate entry • 5–8 alternate entry • 5–9
primary entry • 5–4 primary entry • 5–6
number of entries • 5–5 word • 10–4
number of entries per record • 5–4 Bit manipulation
sequence moving zone
alternate entry • 5–10 high to high • 11–79
primary entry • 5–7 high to low • 11–80
to-file name • 5–3 low to high • 11–81
temporary update • 15–32 low to low • 11–82
testing bits • 11–128
Index–2
Index
Bit manipulation (cont’d) Calculation specification (cont’d)

turning bits off • 11–14 factor 2 • 8–6
turning bits on • 11–16 field length • 8–8
BITOF operation code general description • 1–3
general information • 11–2 half-adjust • 8–9
rules • 11–14 indicators
BITON operation code conditioning • 8–2
general information • 11–2 operation codes • 8–5, 11–1
rules • 11–16 result field • 8–7
Bit operation codes • 11–2 resulting indicators • 8–10
Blank after CALL
output specifications • 9–19 example • 19–17
Block length • 4–8 COBOL subprogram • 19–17
Branching • 11–63 Macro-32 subprogram • 19–17
conditional • 11–17 RPG subprogram • 19–14
target label • 11–127 operation code • 19–2
Branching operation codes • 11–3 rules • 19–2
Called program operation codes
CALL • 11–19, 19–2
C EXTRN • 11–57, 19–4

subprogram naming convention • 19–4
FREE • 11–61, 19–6
CABxx PARM • 19–7
comparison operations • 11–17 PLIST • 19–11
CABxx operation code RETRN • 19–12
general information • 11–3 RPG
rules • 11–17 PARM • 11–98
Calculations PLIST • 11–102
arrays • 15–26 RETRN • 11–111
documenting • 8–10 Calling
referencing OpenVMS Run-Time Library procedures • 19–2
array elements • 15–25 subprograms • 19–2
entire arrays • 15–25 RPG • 11–19
result field • 8–7 system services • 19–2
rounding data Call interface
half-adjust • 8–9 RPG • 11–19
specifying CALL operation code
decimal positions • 8–8 general information • 11–4
factor 1 • 8–4 rules • 11–19
factor 2 • 8–4, 8–6 *CANCL
field length • 8–8 logic cycle • 1–13
operation codes • 8–5 CASxx operation code
resulting indicators • 8–10 general description • 11–8
totaling data • 12–26 general information • 11–3, 11–4, 11–7
using indicators rules • 11–21
conditioning • 8–2 Chained file • 4–5
resulting • 12–10 Chained files
Calculation specification • 8–1 processing mode
comments • 8–10 record address type
control break indicators • 8–2 valid combinations • 4–16
decimal positions • 8–8 Record address type
factor 1 • 8–4
Index–3
Index
Chained files
Compile-time arrays • 15–17
Record address type (cont’d)
advantages • 15–17
processing mode creating • 15–19, 15–22
valid combinations • 4–16 rules for specifying • 15–19
CHAIN operation delimiter • 15–19
example • 13–13 outputting • 15–33
CHAIN operation code updating • 15–32
general information • 11–6 writing • 15–33
rules • 11–24 Compile-time tables • 15–2
Character data advantage • 15–3
defining fields delimiter • 15–4
example • 10–3 input records
Character data type creating • 15–4
example • 10–2 rules for specifying • 15–4
Character sets outputting • 15–15
ASCII • A–1 rules for defining • 15–7
Decimal • A–1 COMP operation code
EBCDIC • A–1 example • 12–11
Hexadecimal • A–1 general information • 11–3
Collating sequences • 17–1 rules • 11–27
alternate • 3–5 Conditioning indicators
alternate sequence table relationship with control level indicators
coding • 17–1 calculation specifications • 8–4
ASCII • 3–5 CONSOLE • B–2 to B–9
EBCDIC • 3–5 automatic generation of display screen formats •
file translation parameters • 17–4 B–7
coding • 17–4 displaying CONSOLE device files • B–8
specifying • 17–1 control key usage • B–9
EBCDIC • 17–1 record identification code • B–8
file translation parameters • 17–1 record identification indicator • B–8
user defined • 17–1 file description specification • B–2
user-defined • 3–5 input specifications • B–4
Collating sequencess limitations of • B–2
alternate • 17–1 Constants
Column numbers • 2–1 output specifications • 9–22
Command key indicators • 12–19 Continuation entries • 4–21
Comments • 2–3, 8–10 Continuation lines • 4–20
control specification • 3–6 continuation entries • 4–21
extension specifications • 5–11 continuation options • 4–21
file description specification • 4–27 disk files • 4–21
input specifications • 7–18 INFDS data structure • 4–23
line counter specifications • 6–3 INFSR subroutine • 4–23
output specification • 9–28 SPECIAL device files
Compare operation codes entries • 4–21
COMP • 11–3 options • 4–21
Comparing data • 11–27 specifying a screen format file • 4–23
Compile Qualifier specification • 21–1 workstation device files
Compiler directives • 2–3 entries • 4–22
/COPY • 2–4 options • 4–22
/EJECT • 2–4 Continuation options • 4–21
/SPACE • 2–4
/TITLE • 2–4
Index–4
Index
CONTINUE
halt response • 1–11
Control break
D
example • 1–17
Data
indicator initialization • 1–12
comparing contents • 11–3
last record • 1–12
fields
Control break indicators • 12–12
initialization • 11–137, 11–138
moving • 11–5, 11–6, 11–83, 11–85, 11–89
conditioning data
arrays • 11–85
left-justified • 11–89
right-justified • 11–83
tables • 11–85
setting • 11–6
moving from the left • 11–6
split-control fields • 12–16
transferring • 11–5, 11–6
usage • 1–13
Data files
Control breaks • 1–13
addrout access
processing • 1–13
File Description specification • 13–18
split-control fields • 12–16
file translation parameters
Control level indicators
coding • 17–4
relationship with conditioning indicators
translation parameters • 17–4
Data formats
Control specification • 3–1
binary
Alternate collating sequence • 3–5
tables and arrays
comments • 3–6
currency symbol • 3–3
date edit code • 3–4
date format code • 3–3
DEBUG option • 3–2
general description • 1–2
input specification • 7–9
inverted print • 3–4
numeric
mulitple • 3–1
tables and arrays
/COPY
compiler directive • 2–4
Copybooks
output specification • 9–21
Auto Report • 21–3
packed-decimal
/COPY statement(XS)Auto Report utility
tables and arrays
example • 21–3
Creating files
add entry • 4–24
Data Structures • 7–1
buffers • 13–38
defining • 16–1
CRT • B–10 to B–13
defining subfields • 7–11, 7–12
file description specification • B–10
initialization • 16–3
limitations of • B–10
input specifications
output specifications • B–12
name • 7–2
field • B–12
local data area • 16–6
record • B–12
name • 7–2
Currency symbol • 3–3
output • 9–12
floating
redefining input records • 16–5
reorganizing input fields • 16–6
subfields • 16–2, 16–4
Index–5
Index
Data Structures
Detail time records
subfields (cont’d)
binary • 16–3 Device codes • 4–18
numeric • 16–3 rules for specifying • 4–20
packed • 16–3 specifying
updating files • 13–26 card reader • 4–18
using • 16–3 disk • 4–18
using storage in more than one way • 16–5 printer • 4–18
Data transfer workstation • 4–18
move WORKSTN • 4–18
rules • 11–5 Device display limitations • B–1
Data types • 10–1 Disk device
binary • 10–4 specifying • 4–18
character • 10–2 Disk files
packed-decimal • 10–6 continuation lines • 4–21
specifying Division • 11–34
tables and arrays remainder • 11–94
alternate entry • 5–9 DIV operation code
primary entry • 5–6 general information • 11–1
zoned-decimal • 10–7 MVR operation code • 11–94
Date remainder • 11–94
edit code • 3–4 rules • 11–34
format • 3–3 Do loop • 11–7
Debugging Migration RPG programs • 11–29 DO operation code
DEBUG operation code general information • 11–3, 11–7
rules • 11–29 rules • 11–36
Decimal character set • A–1 Do until loop • 11–7
Decimal positions DOUxx operation code
calculation specification • 8–8 general information • 11–3, 11–7
extension specification rules • 11–39
alternate entry • 5–10 Do while loop • 11–7
primary entry • 5–7 DOWxx operation code
input specification • 7–10 general information • 11–3, 11–7
Deferred write • 4–26 rules • 11–42
DEFN operation code
rules • 11–32
Deleting records
example • 13–28
DEL option
E
output specifications • 9–4 EBCDIC character set • A–1
Demand file • 4–5 EBCDIC collating sequence
Demand files specifying • 17–1
processing mode Edit Code modifiers
record address type output specifications • 9–23
valid combinations • 4–16 Edit codes
Detail records example • 9–18, 12–5
output specifications • 9–3 Y edit code • 13–19
Detail time • 1–7 output specifications • 9–17
processing individual records • 1–18 specifying
Detail time processing notation • 3–4
setting LR • 11–6
Index–6
Index
Edit words Exception records

body • 9–24 output specifications • 9–3
expansion • 9–24 EXCPT
output specifications • 9–24 names • 10–9
sign • 9–24 EXCPT name
specifying output specification • 9–12, 9–16
asterisk protection • 9–25 EXCPT operation
blank spaces • 9–25 CHAIN operation • 11–25
CR • 9–27 example • 13–13
negative signs • 9–27 EXCPT operation code
zero suppression • 9–25 general information • 11–6
/EJECT rules • 11–51
compiler directive • 2–4 Execution-time arrays • 15–18
ELSE operation code creating • 15–18, 15–24
general information • 11–7 rules for specifying • 15–18
rules • 11–45 outputting • 15–33
End-of-file • 4–6 writing • 15–33
matching fields • 4–6 EXIT
processing • 1–13 halt response • 1–11
End-of-job • 1–13 EXIT operation code
END operation code general information • 11–4
CASxx • 11–47 rules • 11–54
DO • 11–47 EXSR operation code
DOUxx • 11–47 general information • 11–4
DOWxx • 11–47 rules • 11–56
general information • 11–7 Extension code • 4–18
IFxx/ELSE • 11–47 Extension specification
rules • 11–47 array or table name
End position alternate entry • 5–8
output record • 9–20 primary entry • 5–4
output specifications • 9–20 comments • 5–11
ENDSR operation code data format
general information • 11–4 alternate entry • 5–9
rules • 11–49 primary entry • 5–6
*ENTRY PLIST decimal positions
processing in first cycle • 1–10 alternate entry • 5–10
returning parameters • 1–12 primary entry • 5–7
usage • 1–10 defining
Errors arrays • 5–1
handling • 12–20 record-address files • 5–1
halt indicators • 12–20 tables • 5–1
Error trapping from-file name • 5–2
INFDS data structure • 4–23 general description • 1–2
INFSR subroutine • 4–23 length of entry
record locking alternate entry • 5–9
example • 11–26 primary entry • 5–6
Exception handling name of record-address file • 5–2
INFSR data structure • 4–23 name of table input file • 5–2
INFSR subroutine • 4–23 number of entries per record • 5–4
Exception processing number of entries per table or array • 5–5
READ operation • 11–105 sequence
Index–7
Index
Extension specification Factor 1 (cont’d)

sequence (cont’d) restrictions
alternate entry • 5–10 calculation specifications • 8–5
primary entry • 5–7 special words
to-file name • 5–3 calculation specifications • 8–4
External call operation codes specifying *IN,xx indicator array elements • 8–5
general information • 11–4 specifying *INxx indicators • 8–5
External indicators • 12–30 Factor 2
controlling the opening of files • 12–30 alphameric literals
file conditioning • 4–25 calculation specifications • 8–6
file description specification • 4–25 calculation specifications • 8–6
first cycle • 1–10 figurative constants
function • 12–30 calculation specifications • 8–6
specifying • 12–30 labels
External routines calculation specifications • 8–6
SPECIAL device Numeric literals
routine name • 4–20 calculation specifications • 8–6
EXTK restrictions
specifying • 13–15 calculation specifications • 8–7
EXTRN special words
operation code • 19–4 calculation specifications • 8–6, 8–7
accessing specifying *IN,xx indicator array elements • 8–6
link-time constants • 19–4 specifying *INxx indicators • 8–6
OpenVMS Run-Time Library status Fetch overflow • 14–10
codes • 19–4 example • 14–12
OpenVMS Run-Time Library procedures • output specification • 9–5
19–4 rules for specifying • 14–11
rules • 19–4 Field definition
subprogram naming convention • 19–4 *LIKE DEFN • 11–32
subprogram naming convention • 19–4 Field indicators • 12–8
EXTRN operation code checking the condition of data fields
accessing input specifications • 7–17
link-time constants • 11–57 conditioning input data
OpenVMS Run-Time Library status codes • input specifications • 7–17
11–57 example • 12–9
OpenVMS Run-Time Library procedures • 11–57 function • 12–8
rules • 11–57 Field length
Field name
F input specification • 7–11
Field names • 10–9
Factor 1
Field positions
alphameric literals
end • 7–10
start • 7–10
Field-record-relation indicators
figurative constants
conditioning input data
labels
controlling data extraction
Numeric literals
Index–8
Index
Field-record-relation indicators (cont’d) Fields

using matching fields • 13–30 using indicators to compare contents (cont’d)
example • 13–31 input specifications • 7–12
Fields Field start and end positions • 7–9
binary data Figurative constants
example • 10–5 factor 1
calculation calculation specifications • 8–5
example • 10–3 factor 2
character data calculation specifications • 8–6
example • 10–3 File access methods
common • 2–2 random • 13–12
defining sequential • 13–5, 13–6
binary sequential by key • 13–6
example • 10–5 sequential within limits • 13–7
character table • 13–5
example • 10–3 File addition • 4–24
packed-decimal File buffers • 13–38
example • 10–6 File conditioning indicator • 4–25
defining positions File creations
end • 7–10 add entry • 4–24
start • 7–10 File description specification • 4–1
defining start and end positions • 7–9 alternate key • 4–24
indicators • 12–8 Block length • 4–8
initialization • 11–137, 11–138 comments • 4–27
input continuation entries • 4–21
binary continuation lines • 4–20
example • 10–5 continuation options • 4–21
character device code • 4–18
example • 10–3 end-of-file • 4–6
packed-decimal Extension code • 4–18
example • 10–6 file addition • 4–24
specifying file conditioning indicator • 4–25
decimal positions • 7–10 file designation • 4–4
look-ahead • 7–5 file format • 4–7
matching • 13–29 file name • 4–2
checking sequence • 4–7 file organization • 4–16
input specifications • 7–14 file sharing • 4–25
naming • 7–11 file type • 4–3
packed-decimal data key length • 4–15
example • 10–6 key start location • 4–17
specifying no deferred write • 4–26
data format • 7–9 overflow indicators • 4–17
*IN,xx • 7–11, 7–12 processing mode • 4–8
*INxx • 7–11, 7–12 record address type • 4–15
length record length • 4–8
calculation specifications • 8–8 sequence • 4–7
PAGE1 - PAGE7 special words • 7–11, 7–12 SPECIAL device routine • 4–20
PAGE special word • 7–11, 7–12 Unordered output • 4–24
split-control • 12–16 File Description specification modifiers
testing values • 12–8 Auto Report Utility • 21–4
using indicators to compare contents
Index–9
Index
Files (cont’d)
File designations • 4–4
array • 4–4 indexed
chained • 4–4 processing modes • 4–12
demand • 4–4 reading • 11–24
full-procedural • 4–4 sequential access via a key • 11–107
primary • 4–4 Setting an access point • 11–118
record-address • 4–4 specifying
secondary • 4–4 key length • 4–15
table • 4–4 input/output operation codes • 11–6
File format • 4–7 KEYBORD file
File names • 10–9 processing modes • 4–14
file Description specification • 4–2 limits
input specification • 7–2 specifying
Line Counter specification • 6–1 key length • 4–15
output specification • 9–2 look-ahead read • 1–12
rules for specifying • 13–2 matching record indicator • 12–28
File organizations • 4–16 multifile processing • 13–29
indexed • 13–4 organization • 13–3
relative • 13–3 output • 14–1
sequential • 13–3 controlling overflow • 4–17
Files using overflow indicators • 4–17
adding records • 13–24 primary • 4–4
addrout • 13–16 primary read • 1–12
specifying printer file
key length • 4–15 processing modes • 4–13
array printer output • 14–1
input controlling overflow • 4–17
specifying • 5–2 using overflow indicators • 4–17
output processing mode • 4–8
specifying • 5–3 processing using matching fields
chained • 4–5 input specifications • 7–14
characteristics • 13–1 random access • 13–12
conditioning with an external indicator • 4–25 random access by key • 13–19
creating • 13–21 record address
indexed • 13–22 processing modes • 4–13
output • 14–1 specifying • 5–2
printer output • 14–1 record-address • 4–5
record-limits • 13–7 record formats • 13–2
relative • 13–22 record-limits • 13–7
sequential • 13–21 relative
definition • 13–1 processing modes • 4–11
deleting records • 13–28 reading • 11–24
demand • 4–5 secondary • 4–4
external indicators • 12–30 secondary read • 1–12
file access methods • 13–5 sequence code • 4–7
file names • 13–2 sequential
file types • 13–2 processing modes • 4–9
first cycle sequential access • 13–5, 13–6, 13–19
openning • 1–10 sequential by key access • 13–6
full-procedural • 4–5, 13–19 sequential input • 11–104
example • 13–20 reversed • 11–109
Index–10
Index
Files (cont’d)
First-page indicator • 14–6
sequential input based on a key • 11–107 output specifications • 9–10
sequential within limits access • 13–7 First page indicators • 12–24
sharing • 4–25 conditioning output data • 12–24
SPECIAL file example • 12–24
processing modes • 4–14 function • 12–24
specifying FL
chained • 4–4 form length flag • 6–2
demand • 4–4 Floating currency symbol
display • 4–3 example • 12–5
full-procedural • 4–4 output specifications • 9–23
input • 4–3 FORCE • 1–12
output • 4–3 FORCE operation code
primary • 4–4 general information • 11–6
processing mode • 4–8 rules • 11–59
record-address • 4–4 Form length
secondary • 4–4 FL • 6–2
update • 4–3 line counter specification • 6–2
table Form length flag
input FL • 6–2
specifying • 5–2 line counter specification • 6–2
output FREE
specifying • 5–3 operation code • 19–6
updating records • 13–26 rules • 19–6
workstation address FREE operation code
processing modes • 4–13 rules • 11–61
*FILES • 17–5 From-file name
File sharing arrays • 5–2
column 73 access codes • 4–26 record-address files • 5–2
definition • 4–25 tables • 5–2
specifying • 4–25 Full-procedural file • 4–5
usage • 4–26 Full-procedural files
File specification processing mode
general description • 1–2 record address type
SUBR01 • 4–21 valid combinations • 4–16
File translation • 3–6 Record address type
File translation code • 3–6 processing mode
File translation parameters valid combinations • 4–16
coding • 17–4
specifying • 17–1, 17–4
File types • 4–3
display • 4–3
input • 4–3, 13–2
G
output • 4–3, 13–2 *GETIN
update • 4–3, 13–2 logic cycle • 1–11
First cycle • 1–15 GOTO
reading records • 1–12 TAG • 11–127
steps • 1–10 target • 11–127
First page GOTO operation code
indicator initialization • 1–12 general information • 11–3
rules • 11–63
Index–11
Index
Indexed file organization
H index key (cont’d)

example • 13–4
Indexed files
Half-adjust adding records • 13–25
calculation specification • 8–9 example • 13–26
Halt indicators • 12–20 rules for specifying • 13–26
batch • 1–11, 12–20 alternate keys
controlling program execution • 12–20 specifying • 4–24
example creating • 13–22
field indicator • 12–21 rules for specifying • 13–22
record-identifying indicator • 12–21 deleting records
resulting indicator • 12–21 example • 13–28
function • 12–20 processing modes • 4–12
handling errors • 12–20 specifying
interactive key length • 4–15
response • 1–11 key start location • 4–17
last cycle • 1–14 updating records
processing • 1–11, 12–20 example • 13–27
RPG subprograms • 12–22 rules for specifying • 13–27
response • 1–11, 12–20 Indicators • 12–1
setting • 11–6 01 - 99
Halt processing usage • 12–4, 12–8, 12–10
matching fields • 1–13 calculation specifications
record identification • 1–13 conditioning • 8–2
Header specification • 3–1 conditioning
mulitple • 3–1 calculation specifications • 8–2
Heading records output • 9–9
output specifications • 9–3 control break • 12–12
Hexadecimal character set • A–1 end-of-job • 1–13
control-level
I input specifications • 7–12

external • 12–30
first cycle • 1–10
IBM RPG II compatibility
field • 12–8
record address files
key length • 4–8, 4–15
field-record-relation
IFnn operation
example • 13–13
first page • 12–24
IFxx operation code
first-page • 14–6
ELSE • 11–45
general information • 11–3, 11–7
H1 - H9 • 12–1, 12–20
rules • 11–65
usage • 12–4, 12–8, 12–10
*IN • 12–31
halt • 12–20
*IN,xx • 12–31
*IN • 12–31
*IN,xx indicators • 12–31
*IN,xx • 12–31
example • 12–31
factor 1
Indexed file organization • 13–4
factor 2
example • 13–4
index key • 13–4
result field
Index–12
Index
Indicators Indicators
*IN,xx specifying (cont’d)
result field (cont’d) *INxx • 7–11, 7–12
calculation specifications • 8–7 types • 12–3
*INxx • 12–32 U1 - U8 • 12–1, 12–30
factor 1 usage • 12–10
calculation specifications • 8–5 usage • 12–3
factor 2 using as fields • 12–31
calculation specifications • 8–6 INFDS data structure • 16–8
result field continuation lines • 4–23
calculation specifications • 8–7 declaring • 4–23
KA - KN, KP - KY • 12–19 Information data structure • 16–8
usage • 12–10 INFSR subroutine
L0 • 12–1, 12–12, 12–27 *CANCL • 1–13
output specifications • 9–10 continuation lines • 4–23
L1 - L9 • 12–12 declaring • 4–23
usage • 12–4, 12–10 *GETIN • 1–11
last record *IN indicators • 12–31
end-of-job • 1–13 example • 12–31
Last Record • 12–26 function • 12–31
Level Zero • 12–27 specifying array elements • 12–31
LR • 12–1, 12–12 specifying arrays • 12–31
example • 12–5 Input
usage • 12–4, 12–10 forcing file selection
matching record • 12–28 FORCE • 11–59
MR • 12–1, 12–28 indexed
negating Setting a starting point • 11–118
calculation specifications • 8–2 KEYBORD device • 11–68, 11–115
OA - OG, OV • 12–17 reading by key • 11–24
usage • 12–10 sequential based on a key • 11–107
overflow • 4–17, 12–17, 14–7 sequential read • 11–104
1P • 12–1, 12–24, 14–6 reversed • 11–109
example • 12–5 Input/output operation codes • 11–6
printer output files • 14–6 Input specification modifiers
program defined • 12–1 Auto Report Utility • 21–5
record identification • 1–13 Input specifications • 7–1
record identifying AND • 7–2, 7–3, 7–4
01 - 99 • 12–4 record-identification conditions • 7–8
H1 - H9 • 12–4 comments • 7–18
L1 - L9 • 12–4 control break indicators • 7–12
LR • 12–4 data format • 7–9
record-identifying • 7–4 data structure • 7–1
resulting • 12–10 decimal positions • 7–10
calculation specifications • 8–10 field indicators • 7–17
return (RT) field name • 7–11
check • 1–12 field positions
RT • 12–23 end • 7–10
usage • 12–4, 12–8, 12–10 start • 7–10
setting off • 11–120 field-record-relation indicators • 7–15
setting on • 11–121 field start and end positions • 7–9
specifying file name • 7–2
*IN,xx • 7–11, 7–12
Index–13
Index
Input specifications (cont’d)

KEYBORD device
general description • 1–3 KEYnn • 11–68, 11–115
identifying record types • 7–4 KEYBORD files
look-ahead fields processing modes • 4–14
defining • 7–5 Key fields
matching fields • 7–14 non-contiguous
not • 7–7 EXTK • 13–15
option • 7–4 packed-decimal
OR • 7–2, 7–3, 7–4 length • 4–15
example • 13–31 specifying
record-identification conditions • 7–8 non-contiguous • 4–18
record-identification condition position • 7–6 Key length
record-identification conditions • 7–6 addrout files • 4–15
character • 7–7 indexed files • 4–15
comparison character • 7–8 limits files • 4–15
digit • 7–7 Key location • 4–17
zone • 7–7 rules for specifying • 4–18
record-identifying indicators • 7–4 KEYnn operation code
sequence • 7–2 rules • 11–68
sequence number • 7–3 KEY operation code
specifying general information • 11–6
alphabetic sequence code • 7–2 Keys
data formats • 7–9 non-contiguous
data structure names • 7–2 specifying • 4–18
data structure statement • 16–1 KILL
data structure subfield • 16–2 halt response • 1–11
file names • 7–2
look-ahead fields • 7–5
numeric sequence code • 7–2
record-identification conditions • 7–6 L
sequence code • 7–2
Inverted print • 3–4 L0 indicator • 12–27
*INxx indicators • 12–31 output specifications • 9–10
example • 12–32 Label names • 10–9
function • 12–32 Labels
representing indicators • 12–32 factor 1
factor 2
K calculation specifications • 8–6

Language elements • 10–1
Last cycle • 1–12
Key final steps • 1–14
field length Last Cycle • 1–20
length • 4–15 Last record
KEYBORD • B–14 to B–19 indicator check • 1–12
calculation specifications • B–15 processing • 1–13
KEYnn operation • B–16 Last record indicator
SETnn operation • B–18 setting
displaying KEYBORD device files detail time • 11–6
bypassing a KEYnn operation • B–17 total time • 11–6
file description specification • B–14
limitations of • B–14
Index–14
Index
Last Record indicators • 12–26 Local data area

example • 12–26 accessing
function • 12–26 SUBR21 • 16–7
totaling data • 12–26 Local data area (LDA) • 16–6
LDA (local data area) • 16–6 Logic cycle • 1–1
Length of entry basic record processing • 1–7
arrays detail • 1–7, 1–10
alternate entry • 5–9 halt indicators • 1–11
primary entry • 5–6 detail time • 1–7, 1–18
extension specifications first cycle • 1–10
alternate entry • 5–9 first cycle processing • 1–15
primary entry • 5–6 general • 1–7
tables last cycle processing • 1–20
alternate entry • 5–9 look-ahead • 1–14
primary entry • 5–6 normal • 1–15
Level break normal cycle • 1–11
see control break steps • 1–10
Level break indicators steps of
setting • 11–6 a normal cycle • 1–15
Level Zero indicator • 12–27 the first cycle • 1–15
*LIKE DEFN the last cycle • 1–20
see DEFN total time • 1–7, 1–16
Limits file • 13–8 LOKUP operation code
Limits files arrays • 15–29
specifying example • 15–30
key length • 4–15 indexed • 11–74
Limits processing non-indexed • 11–74
SETLL operation • 13–11 specifying array elements • 11–74
Limits records • 13–8 referencing entries • 15–10
Line Counter specification • 6–1 related tables • 11–74
comments • 6–3 rules • 11–71
file name • 6–1 searching
form length • 6–2 arrays • 11–74
form length flag • 6–2 related tables • 11–74
naming the output file • 6–1 tables • 11–73, 15–10
overflow line flag • 6–3 sequencing arrays • 11–122
overflow line number • 6–2 table elements • 11–73
Line numbers • 2–2 Longword binary data type
checking • 2–2 example • 10–4
Line relationships Look-ahead fields • 7–5
input specifications defining • 7–5
AND • 7–8, 12–6 function • 7–5
OR • 7–8, 12–6 Look-ahead logic cycle • 1–14
Line specification LR
general description • 1–3 example • 12–5
Literals LR indicators • 12–26
factor 1
factor 2
M
Index–15
Index
MOVE operation codes (cont’d)

Matching fields
checking record sequence • 4–7, 13–29 MOVEA • 11–5
example • 13–29 MOVEL • 11–5, 11–6
for more than one record type • 13–29 Move operations
end-of-file • 4–6 rules • 11–5
example • 13–30 Move zoned operation codes • 11–6
input specifications • 7–14 rules • 11–6
multifile processing • 13–29, 13–32 Moving data
example • 13–32, 13–35 rules • 11–5
record selection • 13–32 MR indicator • 12–28
rules for specifying • 13–32 example • 12–29
sequence checking • 7–14 Multifile processing • 13–29
using as field-record-relation indicators • 13–30 checking record sequence • 13–29
example • 13–31 example • 13–29
Matching Fields • 1–13 for more than one record types • 13–29
FORCE bypass • 1–12 matching fields • 13–29
Matching record indicator • 12–28 using
function • 12–28 matching fields • 13–29
multifile processing • 12–28 matching record indicator • 12–28
Matching records matching-record indicators • 13–29
example • 12–29 MR indicators • 13–29
MHHZO operation code multiple keys • 13–38
general information • 11–6 Multiplication • 11–92
rules • 11–79 MULT operation code
MHLZO operation code general information • 11–1
general information • 11–6 rules • 11–92
rules • 11–80 MVR operation code
Migration RPG programs general information • 11–1
logic cycle • 1–1 rules • 11–94
MLHZO operation code
rules • 11–81
MLLZO operation code
N
Names
rules • 11–82
arrays • 10–9
MOVEA
specifying
rules • 11–5
MOVEA operation code
arrays • 15–31
EXCPT • 10–9
example • 15–32
fields • 10–9
files • 10–9
rules • 11–85
labels • 10–9
MOVEL operation code • 11–6
subroutines • 10–9
tables • 10–9
rules • 11–89
specifying
MOVE operation code
example • 10–3
Naming conventions • 10–9
rules • 11–83
Non-contiguous keys
MOVE operation codes
accessing
MOVE • 11–5
EXTK • 13–15
Index–16
Index
Non-contiguous keys (cont’d)

OL
specifying • 4–18 overflow line flag • 6–3
Normal cycle OpenVMS Run-Time Library procedures
reading records • 1–12 assigning names • 11–57, 19–4
Not calling • 19–2
see record-identification conditions passing parameters • 19–7
Notations Operation codes • 11–1
edit codes • 3–4 alphabetical listing • 11–8
numeric fields • 3–4 arithmetic • 11–1
UDATE • 3–4 bit • 11–2
Number of entries per record • 5–4 branching • 11–3
arrays • 5–4 called program
tables • 5–4 CALL • 11–19, 19–2
Number of entries per table or array • 5–5 EXTRN • 11–57, 19–4
Numeric subprogram naming convention • 19–4
specifying FREE • 11–61, 19–6
tables and arrays PARM • 19–7
alternate entry • 5–9 PLIST • 19–11
primary entry • 5–6 RETRN • 19–12
Numeric data RPG
binary • 9–21 PARM • 11–98
overpunch • 9–21, 10–7 PLIST • 11–102
packed-decimal • 9–21 RETRN • 11–111
specifying compare • 11–3
format • 9–21 external call • 11–4
trailing numeric • 9–21 input/output • 11–6
zoned-decimal • 9–21 EXCPT • 9–16
Numeric data type move • 11–5
trailing numeric • 10–7 MOVEL • 11–6
zoned-decimal • 10–7 rules • 11–5
Numeric field editing • 14–4 move zoned • 11–6
Numeric fields rules • 11–6
comparing • 11–3 moving arrays • 11–5
editing Set • 11–6
edit words • 9–24 rules • 11–6
rounding specifying
half-adjust • 8–9 calculation specifications • 8–5
specifying structured • 11–7
notation • 3–4 ANDxx • 11–11
Numeric literals CASxx • 11–21
factor 1 comparison rules • 11–3
calculation specifications • 8–4 DO • 11–36
factor 2 DOUxx • 11–39
calculation specifications • 8–6 DOWxx • 11–42
Numeric sequence code ELSE • 11–45
sequence option • 7–4 END • 11–47
IFxx • 11–65
ORxx • 11–96
O subprogram
CALL • 11–19, 19–2
EXTRN • 11–57, 19–4
Index–17
Index
Operation codes Output specifications (cont’d)

subprogram edit words • 9–24
EXTRN (cont’d) end position • 9–20
subprogram naming convention • 19–4 EXCPT name • 9–12, 9–16
FREE • 11–61, 19–6 fetch overflow • 9–5
PARM • 19–7 field name • 9–12
PLIST • 19–11 special words
RETRN • 19–12 *PLACE • 9–14
RPG UDATE • 9–15
PARM • 11–98 $UDATE • 9–15
PLIST • 11–102 UDAY • 9–15
RETRN • 11–111 $UDAY • 9–15
subroutine • 11–4 $UMNTH • 9–15
Option UMONTH • 9–15
input specifications • 7–4 UYEAR • 9–15
OR $UYEAR • 9–15
Input specification file name • 9–2
example • 13–31 function • 9–1
input specifications • 7–2, 7–3, 7–4, 7–8, 12–6 general description • 1–3
output specifications • 9–2 indicators • 9–9
record identification OR • 9–2
example • 12–7 record type • 9–3
ORxx operation code skip after • 9–8
general information • 11–3, 11–7 skip before • 9–7
rules • 11–96 space after • 9–6
Output space before • 9–6
detail • 1–11 special words • 9–12, 9–13
example • 12–5 *PLACE • 9–14
exception output • 11–51 UDATE • 9–15
EXCPT • 11–51 $UDATE • 9–15
first page (1P) • 1–11 UDAY • 9–15
from calculation specifications • 11–51 $UDAY • 9–15
heading • 1–11 $UMNTH • 9–15
example • 12–5 UMONTH • 9–15
overflow • 1–11 UYEAR • 9–15
total time $UYEAR • 9–15
Output files ADD option • 9–4
controlling overflow • 4–17 DEL option • 9–4
specifying WORKSTN screen format names • 9–22
file name • 6–1 Overflow
using overflow indicators • 4–17 indicator initialization • 1–12
Output operations Overflow indicators • 4–17, 12–17, 14–7
no deferred write • 4–26 causing page breaks • 12–17
Output specifications • 9–1 example • 12–5, 12–18, 14–9
AND • 9–2 function • 12–17
Blank after • 9–19 rules for specifying • 4–17, 14–7
comments • 9–28 specifying • 12–17
constants • 9–22 fetch overflow • 9–5
data format • 9–21 Overflow line flag
edit code modifiers • 9–23 Line counter specification • 6–3
edit codes • 9–17 OL • 6–3
Index–18
Index
Overflow line number Parameter passing • 1–10

line counter specification • 6–2 Parameters
Overpunch • 10–7 list • 19–11
Overpunch data passing
example • 10–8 access types • 11–100, 19–8
mechanisms • 11–100, 19–8
by reference • 19–7
P RPG
list • 11–102
PARM
1P operation code • 19–7
example • 12–5 rules • 19–7
Packed-decimal data processing in first cycle • 1–10
defining fields PARM operation code
example • 10–6 general information • 11–4
determining length • 10–6 rules • 11–98
Packed-decimal data type 1P indicator • 12–24, 14–6
example • 10–6 conditioning output data • 12–24
specifying example • 12–24
tables and arrays function • 12–24
alternate entry • 5–9 *PLACE
primary entry • 5–6 special words
Packed-decimal fields output specifications • 9–14
key PLIST
length • 4–15 *ENTRY
PAGE usage • 1–10
example • 12–5, 13–19 operation code • 19–11
special words rules • 19–11
output specifications • 9–13 PLIST operation code
PAGE1 general information • 11–4
output specifications • 9–13 Porting RPG applications
PAGE2 device specifications • 4–18
special words disk files
output specifications • 9–13 continuation lines • 4–21
PAGE3 IBM RPG II compatibility
special words record address files
output specifications • 9–13 key length • 4–8, 4–15
PAGE4 SPECIAL device files
special words continuation lines
output specifications • 9–13 entries • 4–21
PAGE5 options • 4–21
special words SUBR01 support • 4–21
output specifications • 9–13 workstation device files
PAGE6 continuation lines
special words entries • 4–22
output specifications • 9–13 options • 4–22
PAGE7 Pre-execution-time arrays • 15–18
special words creating • 15–18, 15–23
output specifications • 9–13 rules for specifying • 15–18
outputting • 15–33
Index–19
Index
Pre-execution-time arrays (cont’d) Printer output files

searching overflow indicators (cont’d)
example • 15–30 using • 12–17
updating • 15–32 1P indicator • 12–24
writing • 15–33 printing
Pre-execution-time tables • 15–3 IMPORTANT INFORMATION • 14–1
creating required specifications • 14–1
example • 15–9 Skip entries • 14–4
outputting • 15–15 example • 14–6
rules for defining • 15–9 Space entries • 14–4
Primary file • 4–4 example • 14–6
Primary files specifying
processing mode a negative sign • 9–27
record address type asterisks • 9–25
valid combinations • 4–16 blank spaces • 9–25
Record address type constant data • 9–22
processing mode CR • 9–27
valid combinations • 4–16 fetch overflow • 9–5
Printer device page breaks • 14–7
specifying • 4–18 skip after • 9–8
Printer files skip before • 9–7
processing modes • 4–13 space after • 9–6
PRINTER files space before • 9–6
specifying zero suppression • 9–25
overflow line number • 6–2 using
page size • 6–2 fetch overflow
PRINTER file usage example • 14–12
example • 13–13 first-page indicators • 14–6
Printer output files • 14–1 indicators to condition output • 9–9
conditioning output • 14–6 overflow indicators • 4–17, 14–7
controlling overflow • 4–17 example • 14–9
creating • 14–1 1P indicator • 14–6
deleting form-feed characters • 14–1 special words • 14–4
editing PRINT files
numeric data • 9–24 specifying
editing output • 9–17 overflow line number • 6–2
file description specification • 14–1 page size • 6–2
first page indicators • 12–24 Processing
formatting files
output • 14–4 specifying
output data • 9–20, 9–23 an addrout file • 4–8
skip after • 9–8 random access • 4–8
skip before • 9–7 sequential access • 4–8
space after • 9–6 sequential within limits access • 4–8
space before • 9–6 multifiles • 13–29
generating report titles • 9–22 processing files
Last Record indicators • 12–26 multiple keys • 13–38
line counter specification • 14–2 example • 13–38
NOFEED qualifier • 14–1 Processing mode • 4–8
numeric field editing • 14–4 loading a direct file • 4–8
output specification • 14–2 record address type
overflow indicators valid combinations • 4–16
Index–20
Index
Processing mode (cont’d) Record address files (cont’d)

selecting key length • 4–15
indexed • 4–12 processing modes • 4–13
KEYBORD file • 4–14 record length • 4–8
printer file • 4–13 Record-address files
record address file • 4–13 specifying
relative • 4–11 from-file name • 5–2
sequential • 4–9 to-file name • 5–3
SPECIAL file • 4–14 Record address type • 4–15
workstation file • 4–13 processing mode
specifying valid combinations • 4–16
access Record formats
random • 4–8 fixed • 13–2
sequential • 4–8 variable • 13–2
sequential within limits • 4–8 Record identification
an addrout file • 4–8 CHAIN operation • 11–25
record address type • 4–15 example • 12–7
Program no record • 1–13
initialization • 1–10 Record-identification codes
Programs input specifications • 7–6
logic cycle • 1–1 Record identification conditions
Program specifications • 1–1 AND • 12–6
example • 12–5
OR • 12–6
R Record-identification conditions
AND • 7–8
identifying record types • 7–6
Random by addrout file access • 13–16 OR • 7–8
rules for specifying • 13–17 character • 7–7
Random by key file access • 13–14 comparison character • 7–8
example • 13–15 digit • 7–7
rules for specifying • 13–14 not • 7–7
Random file access • 13–12 position • 7–6
using zone • 7–7
an addrout file • 13–16 Record identifying indicators
keys • 13–14 example • 12–5
relative record numbers • 13–12 function • 12–4
example • 13–13 identifying record types • 12–4
rules for specifying • 13–13 Record-identifying indicators
READE operation code conditioning input data • 7–4
general information • 11–6 input specifications • 7–4
rules • 11–107 Record indentification • 1–13
READ operation code Record length • 4–8
general information • 11–6 Record-limits files
rules • 11–104 example • 13–7
READP operation code function • 13–9
general information • 11–6 rules for specifying • 13–9
rules • 11–109 Record locking
Record-address file • 4–5 trapping
Record address files example • 11–26
file designation • 4–6
Index–21
Index
Related tables
Records
creating (cont’d)
adding • 13–24
output specifications • 9–4 input records • 15–5
array input • 15–18 LOKUP operation code
basic processing cycle • 1–7 rules • 11–74
deleting • 13–28 Relative file organization • 13–3
example • 13–28 example • 13–3
output specifications • 9–4 Relative files
identifying types • 7–4 adding records • 13–25
processing totals • 1–16 rules for specifying • 13–25
record identifying indicators • 12–4 creating • 13–22
specifying rules for specifying • 13–22
detail processing modes • 4–11
output specifications • 9–3 updating records
exception rules for specifying • 13–27
output specifications • 9–3 Result field
format • 4–7 calculation specifications • 8–7
heading restrictions
output specifications • 9–3 calculation specifications • 8–8
length rounding data
fixed • 4–7 half-adjust • 8–9
variable • 4–7 specifying *IN,xx indicator array elements • 8–7
record-identification conditions • 7–6 specifying *INxx indicators • 8–7
total Resulting indicators • 12–10
output specifications • 9–3 calculation specifications • 8–10
types example • 12–11
defining the ordering sequence • 7–2 function • 12–10
output specifications • 9–3 RETRN
updating • 13–26 operation code • 19–12
example • 13–27 rules • 19–12
using record identifying indicators • 12–4 RETRN operation code
Record types rules • 11–111
defining the ordering sequence • 7–2 Return indicator
detail RT • 12–23
output specifications • 9–3 Return status
exception halt indicators • 1–14
output specifications • 9–3 RLABL operation code
heading general information • 11–4
output specifications • 9–3 rules • 11–113
identifying • 7–4 RPGCON • B–7
output specifications • 9–3 RPG II programs
specifying arrays • 15–15
record-identification conditions • 7–6 RPGLDA • 16–6
total RPG program
output specifications • 9–3 example • 1–19
using record identifying indicators • 12–4 RPG programs
Related arrays • 15–19 documenting • 2–3
alternate format • 15–21 RPG subprograms
creating • 15–19, 15–21 halt indicators
Related tables processing • 12–22
creating • 15–7 RT indicator • 12–23
Index–22
Index
SETLL operation
S limits processing • 13–11
SETLL operation code
Screen format names
rules • 11–118
SETnn operation code
Screen formats
continuation lines • 4–23
rules • 11–115
Secondary file • 4–4
SETOF operation code
Secondary files
processing mode
rules • 11–120
record address type
SETON operation code
valid combinations • 4–16
Record address type
rules • 11–121
processing mode
Set operation codes • 11–6
valid combinations • 4–16
rules • 11–6
Sequence checking
Skip after
using matching fields • 7–14
Sequence code • 4–7
Skip before
Sequence codes • 7–2
assigning a numeric code • 7–3
SORTA operation code
extension specifications
rules • 11–122
/SPACE
compiler directive • 2–4
sequence number • 7–3
Space after
specifying
alphabetic • 7–2
Space before
numeric • 7–2, 7–3
sequence option • 7–4
SPECIAL Device File
Sequence Number
Coding the SPECIAL File Subroutine • 18–4
input specification • 7–3
File Description Continuation Specifications • 18–2
Sequential by key file access
File Description Specifications • 18–1
example • 13–7
Introduction • 18–1
Migration RPG Program Logic • 18–3
Sequential file access • 13–5, 13–6
Programming Features Supported • 18–3
example • 13–6
Sample Program • 18–5
SUBR01 Support • 18–1
Sequential file organization • 13–3
SPECIAL device files
example • 13–3
continuation lines
Sequential files
entries • 4–21
adding records • 13–24
options • 4–21
example • 13–24
SPECIAL device routine
name • 4–20
SPECIAL device routines
SUBR01 • 4–21
processing modes • 4–9
SPECIAL files
Sequential input
example • 13–13
Special words • 14–4
Sequential within limits file access
factor 1
example • 13–8
record-limits file • 13–7
factor 2
Index–23
Index
Special words Specifications (cont’d)

factor 2 (cont’d) input • 7–1
calculation specifications • 8–6, 8–7 Line Counter • 6–1
output specification • 9–12, 9–13 Output • 9–1
PAGE program • 1–1
output specifications • 9–13 types • 2–2
PAGE, PAGE1 - PAGE7 Split-control fields
input specifications • 7–12 example • 12–16
PAGE1 SQRT operation code
output specifications • 9–13 general information • 11–1
PAGE2 rules • 11–124
output specifications • 9–13 Square root • 11–124
PAGE3 Structured operation codes • 11–7
output specifications • 9–13 ANDxx • 11–11
PAGE4 CASxx • 11–21
output specifications • 9–13 comparison operations • 11–8, 11–12, 11–21,
PAGE5 11–40, 11–43, 11–66, 11–97
output specifications • 9–13 comparison rules • 11–3
PAGE6 DO • 11–36
output specifications • 9–13 DOUxx • 11–39
PAGE7 DOWxx • 11–42
output specifications • 9–13 ELSE • 11–45
*PLACE END • 11–47
output specifications • 9–14 IFxx • 11–65
UDATE ORxx • 11–96
output specifications • 9–15 structured constructs • 11–8
$UDATE Subfields
output specifications • 9–15 data structures • 16–4
UDAY defining • 7–11, 7–12
output specifications • 9–15 SUB operation code
$UDAY general information • 11–1
output specifications • 9–15 rules • 11–125
$UMNTH Subprogram
output specifications • 9–15 return indicator • 1–12
UMONTH returning parameters • 1–12
output specifications • 9–15 return using RT • 1–12
UYEAR RPG
output specifications • 9–15 initialization steps • 1–10
$UYEAR passing parameters • 1–10
output specifications • 9–15 Subprogram naming convention • 19–4
Specification format Subprogram operation codes
comments • 2–3 CALL • 11–19, 19–2
line number • 2–2 EXTRN • 11–57, 19–4
notational conventions • 2–1 subprogram naming convention • 19–4
Specifications FREE • 11–61, 19–6
calculation • 8–1 PARM • 19–7
column numbers • 2–1 PLIST • 19–11
compile qualifier • 21–1 RETRN • 19–12
control • 3–1 RPG
Extension • 5–1 PARM • 11–98
file description • 4–1 PLIST • 11–102
RETRN • 11–111
Index–24
Index
Subroutines (cont’d)
Subprograms
calling • 19–2 operation codes • 11–4
RPG Subtraction • 11–125
CALL • 11–19 Symbolic device • 4–20
FREE • 11–61, 19–6 System services
parameter list • 19–11 calling • 19–2
PARM • 19–7 passing parameters • 19–7
passing parameters • 19–7
PLIST • 19–11
RETRN • 19–12
RPG
T
calling
Table
CALL • 11–19
elements
halt indicators
processing • 12–22
LOKUP operation code • 11–73
parameter list • 11–102
sequencing • 11–72
PARM • 11–98
Table name
passing parameters • 11–98
PLIST • 11–102
RETRN • 11–111
Tables • 15–1
startup • 1–10
SUBR01
rules for defining • 15–7
calling • 11–54
compile-timed
parameter passing • 11–113
delimiter • 15–3
file description specification • 4–21
creating
SPECIAL device option • 4–21
input records • 15–3
SUBR21
definition • 15–1
calling • 11–54
entries • 15–3
input records • 15–3
example • 16–7
creating • 15–3
local data area subroutine • 16–7
SUBR23
loading time
calling • 11–54
selecting • 15–2
LOKUP operation code • 11–73, 15–10
example • 11–55, 11–114
names • 10–9
Subroutines
operations
external
LOKUP • 11–71
calling
permanent update • 15–14
CALL • 11–19
EXIT • 11–54
rules for defining • 15–9
RLABL • 11–113
referencing entries • 15–10
identification • 11–13
related • 15–1, 15–5, 15–16
internal
creating • 15–7
begin
searching • 11–73, 15–10
BEGSR • 11–13
calling
set up and usage example • 11–76
EXSR • 11–56
single • 15–1, 15–16
conditional calling • 11–21
creating • 15–6
termination
ENDSR • 11–49
names • 10–9
Index–25
Index
Tables Total records (cont’d)

specifying (cont’d) output specifications • 9–3
data format Total time • 1–7, 1–16
alternate entry • 5–9 calculations • 1–13
primary entry • 5–6 output • 1–13
decimal positions Total time processing
alternate entry • 5–10 example • 1–17
primary entry • 5–7 setting LR • 11–6
from-file name • 5–2 Total-time records
length of entry output specifications • 9–3
alternate entry • 5–9 Trailing numeric data types
primary entry • 5–6 example
names overpunch • 10–8
alternate entry • 5–8 zoned-decimal • 10–8
primary entry • 5–4 overpunch • 10–7
number of entries • 5–5 representation of digits • 10–7
number of entries per record • 5–4
sequence
primary entry • 5–7 U
to-file name • 5–3
temporary update • 15–13 UDATE • 9–12, 9–13, 9–15, 14–3, 14–4
updating • 15–13 example • 1–15, 1–19, 12–5, 13–19, 14–9, 14–12,
writing • 15–15 15–17
TAG operation code first cycle • 1–10
general information • 11–3 format • 3–3
rules • 11–127 special words
Terminal device output specifications • 9–15
specifying • 4–18 $UDATE • 3–4, 9–15
TESTB operation code first cycle • 1–10
general information • 11–2 special words
rules • 11–128 output specifications • 9–15
TESTZ operation code UDATE special word
general information • 11–3 specifying notation • 3–4
rules • 11–130 UDAY • 9–12, 9–13, 9–15, 14–3, 14–4
TIME operation code first cycle • 1–10
date format • 3–3 special words
rules • 11–132 output specifications • 9–15
$TIME operation code $UDAY • 9–15
rules • 11–134 first cycle • 1–10
/TITLE special words
compiler directive • 2–4 output specifications • 9–15
To-file name $UMNTH • 9–15
outputting special words
arrays • 5–3 output specifications • 9–15
tables • 5–3 UMONTH • 9–12, 9–13, 9–15, 14–3, 14–4
record-address files • 5–3 first cycle • 1–10
writing special words
arrays • 5–3 output specifications • 9–15
tables • 5–3 $UMONTH
Total records first cycle • 1–10
Index–26
Index
XFOOT operation code (cont’d)

Unordered output • 4–24
Updating rules • 11–136
files • 13–26
randomly by key • 13–28
sequentially • 13–28
records • 13–26
Y
example • 13–27
Y2K • 1–11, 3–4, 9–15, 11–134
User defined collating sequence
Year 2000 compliance • 1–11, 3–4, 9–15, 11–134
User-defined names • 10–9
rules • 10–9
U specification
specifying Auto Report compile qualifiers • 21–1
Z
UYEAR • 9–12, 9–13, 9–15, 14–3, 14–4 Z-ADD operation code
first cycle • 1–10 general information • 11–1
output specifications • 9–15 Zero suppression • 9–25
$UYEAR • 9–15 Zoned-decimal data • 3–6
first cycle • 1–10 example • 10–8
special words overpunch • 10–8
output specifications • 9–15 output • 3–6
representation of digits • 10–7
Zone-decimal data
W overpunch • 10–7
Z-SUB operation code
Word binary data type
rules • 11–138
example • 10–4
Workstation device
return codes
INFSR data structure • 4–23
Workstation device files
continuation lines
entries • 4–22
options • 4–22
Workstation file
INFDS • 16–8
information data structure • 16–8
returning exception information • 16–8
Workstation files
WORKSTN screen format names
X
XFOOT operation code
arrays • 15–28
example • 15–28
Index–27

Migration RPG Language Reference Manual

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Migration RPG Language Reference Manual

Uploaded by

Copyright:

Available Formats

MIGRATION RPG

Revision/Update Information: This revised manual supersedes the

Migration Specialties International Florence, Colorado

First Printing, October 1999

Copyright ©2011 by Migration Specialties International, Inc. (MSI)

CHAPTER 1 UNDERSTANDING THE MIGRATION RPG LOGIC CYCLE 1–1

1.1 MIGRATION RPG OVERVIEW 1–1

1.2 RPG PROGRAM SPECIFICATIONS 1–1

1.3 THE RPG LOGIC CYCLE 1–7

1.4 THE RPG LOGIC CYCLE IN DETAIL 1–7

CHAPTER 2 MIGRATION RPG PROGRAM SPECIFICATIONS 2–1

2.1 COLUMN NUMBERS 2–1

2.2 COMMON FIELDS 2–2

2.3 COMPILER DIRECTIVES 2–3

CHAPTER 3 CONTROL SPECIFICATION (H) 3–1

3.1 COLUMNS 1 - 5 (LINE NUMBER) 3–2

3.2 COLUMN 6 (SPECIFICATION IDENTIFICATION) 3–2

3.3 COLUMN 7 (COMMENT OR COMPILER DIRECTIVE) 3–2

3.4 COLUMNS 7 - 10 (NO-OP) 3–2

3.5 COLUMN 15 (DEBUG OPTION) 3–2

3.6 COLUMNS 16 - 17 (NO-OP) 3–3

3.7 COLUMN 18 (CURRENCY SYMBOL) 3–3

3.8 COLUMN 19 (DATE FORMAT CODE) 3–3

3.9 COLUMN 20 (DATE EDIT CODE) 3–4

3.10 COLUMN 21 (INVERTED PRINT CODE) 3–4

3.11 COLUMNS 22 - 25 (NO-OP) 3–5

3.12 COLUMN 26 (ALTERNATE COLLATING SEQUENCE) 3–5

3.13 COLUMNS 27 - 42 (NO-OP) 3–5

3.14 COLUMN 43 (FILE TRANSLATION CODE) 3–6

3.15 COLUMNS 44 - 59 (NO-OP) 3–6

3.16 COLUMN 60 (ZONED-DECIMAL OUTPUT) 3–6

3.17 COLUMNS 61 - 74 (NO-OP) 3–6

3.18 COLUMNS 75 - 80 (COMMENTS) 3–6

CHAPTER 4 FILE DESCRIPTION SPECIFICATION (F) 4–1

4.1 COLUMNS 1 - 5 (LINE NUMBER) 4–2

4.2 COLUMN 6 (SPECIFICATION IDENTIFICATION) 4–2

4.3 COLUMN 7 (COMMENT OR COMPILER DIRECTIVE) 4–2

4.4 COLUMNS 7 - 14 (FILE NAME) 4–2

4.5 COLUMN 15 (FILE TYPE) 4–3

4.6 COLUMN 16 (FILE DESIGNATION) 4–4

4.7 COLUMN 17 (END-OF-FILE) 4–6

4.8 COLUMN 18 (SEQUENCE CODE) 4–7

4.9 COLUMN 19 (FILE FORMAT) 4–7

4.10 COLUMNS 20 - 23 (BLOCK LENGTH) 4–8

4.11 COLUMNS 24 - 27 (RECORD LENGTH) 4–8

4.12 COLUMN 28 (PROCESSING MODE) 4–8

4.13 COLUMNS 29 - 30 (KEY LENGTH) 4–15

4.14 COLUMN 31 (RECORD ADDRESS TYPE) 4–15

4.15 COLUMN 32 (FILE ORGANIZATION) 4–16

4.16 COLUMNS 33 - 34 (OVERFLOW INDICATOR) 4–17

4.17 COLUMNS 35 - 38 (KEY START LOCATION) 4–17

4.18 COLUMN 39 (EXTENSION CODE) 4–18

4.19 COLUMNS 40 - 46 (DEVICE CODE) 4–18

4.20 COLUMNS 47 - 52 (NO-OP) 4–20

4.21 COLUMN 53 (CONTINUATION LINES) 4–20

4.22 COLUMNS 54 - 65 (SPECIAL DEVICE ROUTINE) 4–20

4.23 COLUMNS 54 - 59 (CONTINUATION OPTIONS) AND COLUMNS 60 -

4.24 COLUMN 66 (FILE ADDITION) 4–24

4.25 COLUMN 67 (NO-OP) 4–24

4.26 COLUMNS 68 - 69 (ALTERNATE KEY) 4–24

4.27 COLUMN 70 (NO-OP) 4–25

4.28 COLUMNS 71 - 72 (FILE CONDITIONING INDICATOR) 4–25

4.29 COLUMN 73 (FILE SHARING) 4–25