MIGRATION RPG LANGUAGE REFERENCE MANUAL

MIGRATION RPGLANGUAGE REFERENCEMANUAL

jUNE 2011

Revision/Update Information: This revised manual supersedes theMigration 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 1999Revised, January 2001Revised, March 2002Revised, January 2005Revised, June 2011——————————The information in this document is subject to change without noticeand should not be construed as a commitment by MSI. MSI assumes noresponsibility for any errors that may appear in this document.The software described in this document is furnished under a license andmay 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 byMSI or its affiliated companies.Restricted Rights: Use, duplication, or disclosure by the U.S. Governmentis subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rightsin 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 [email protected], www.MigrationSpecialties.comAll 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 theproperty 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–11.2.1 Control Specification - H 1–21.2.2 File Description Specification - F 1–21.2.3 Extension Specification - E 1–21.2.4 Line Counter Specification - L 1–31.2.5 Input Specifications - I 1–31.2.6 Calculation Specification - C 1–31.2.7 Output Specification - O 1–3

1.3 THE RPG LOGIC CYCLE 1–7

1.4 THE RPG LOGIC CYCLE IN DETAIL 1–71.4.1 The First Cycle 1–151.4.2 A Normal Cycle 1–15

1.4.2.1 Total Time Processing • 1–161.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–22.2.1 Line Number 2–22.2.2 Specification Type 2–22.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–214.23.1 Rules for Specifying a Continuation Line on a DISK File 4–214.23.2 Rules for Specifying a Continuation Line on a SPECIAL

Device File 4–214.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–47.10.1 Look-Ahead Fields 7–5

7.11 COLUMNS 21 - 41 (RECORD-IDENTIFICATION CONDITIONS) 7–67.11.1 Columns 21 - 24, 28 - 31, 35 - 38 (Position) 7–67.11.2 Columns 25, 32, 39 (Not) 7–77.11.3 Columns 26, 33, 40 (Character, Zone, or Digit) 7–77.11.4 Columns 27, 34, 41 (Comparison Character) 7–87.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–97.13.1 Column 43 (Data Format) 7–97.13.2 Columns 44 - 47 and 48 - 51 (Field Start and End

Positions) 7–97.13.2.1 Columns 44 - 47 (Field From Location) • 7–107.13.2.2 Columns 48 - 51 (Field To Location) • 7–10

ix

Contents

7.13.3 Column 52 (Decimal Positions) 7–107.13.4 Columns 53 - 58 (Field Name) 7–11

7.13.4.1 Field Names • 7–117.13.4.2 PAGE, PAGE1 - PAGE7 • 7–127.13.4.3 *INxx, *IN,xx • 7–12

7.13.5 Columns 59 - 60 (Control break Indicator) 7–127.13.6 Columns 61 - 62 (Matching Fields) 7–147.13.7 Columns 63 - 64 (Field-Record-Relation Indicator) 7–157.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–28.5.1 Relationship Between Control Level and Conditioning

Indicators 8–4

8.6 COLUMNS 18 - 27 (FACTOR 1) 8–48.6.1 Factor 1 Restrictions 8–5

8.7 COLUMNS 28 - 32 (OPERATION CODE) 8–5

8.8 COLUMNS 33 - 42 (FACTOR 2) 8–68.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–39.6.1 Heading Records 9–39.6.2 Detail Records 9–39.6.3 Total Records 9–39.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–129.14.1 Output field names 9–129.14.2 Output Special Words 9–13

9.14.2.1 PAGE, PAGE1 - PAGE7 Special Words • 9–139.14.2.2 *PLACE Special Word • 9–149.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–229.19.1 Output Constant 9–229.19.2 WORKSTN Screen Format Names 9–229.19.3 Edit Code Modifiers 9–239.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–110.2.1 Character Data Type 10–210.2.2 Binary Data Type 10–410.2.3 Packed-decimal Data Type 10–610.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–811.12.1 - ADD Operation (Addition) 11–911.12.2 - ANDxx Operation (Complex Conditional Operation) 11–1111.12.3 - BEGSR Operation (Begin Subroutine) 11–1311.12.4 - BITOF Operation (Bit Off) 11–1411.12.5 - BITON Operation (Bit On) 11–1611.12.6 - CABxx Operation (Compare and Branch) 11–1711.12.7 - CALL Operation (Calling RPG Subprograms) 11–1911.12.8 - CASxx Operation (Case) 11–2111.12.9 - CHAIN Operation 11–2411.12.10 - COMP Operation (Compare) 11–2711.12.11 - DEBUG Operation 11–2911.12.12 - DEFN Operation (Field Definition) 11–3211.12.13 - DIV Operation (Divide) 11–3411.12.14 - DO Operation (DO Loop) 11–3611.12.15 - DOUxx Operation (Do Until Loop) 11–3911.12.16 - DOWxx Operation (Do While Loop) 11–4211.12.17 - ELSE Operation (IF/ELSE Operation) 11–4511.12.18 - END Operation 11–4711.12.19 - ENDSR Operation (End Subroutine) 11–4911.12.20 - EXCPT Operation (Exception Output Operation) 11–5111.12.21 - EXIT Operation (External Subroutine Call) 11–5411.12.22 - EXSR Operation (Execute Subroutine) 11–5611.12.23 - EXTRN Operation (External Name Definition) 11–5711.12.24 - FORCE Operation 11–5911.12.25 - FREE Operation 11–6111.12.26 - GOTO Operation (Branching Operation) 11–6311.12.27 - IFxx Operation 11–6511.12.28 - KEYnn Operation 11–6811.12.29 - LOKUP Operation 11–71

11.12.29.1 Table Elements in a LOKUP Operation • 11–7311.12.29.2 Searching Tables Using LOKUP • 11–7311.12.29.3 Searching Arrays Using LOKUP • 11–74

11.12.30 - MHHZO Operation (Move High Zone to High Zone) 11–7911.12.31 - MHLZO Operation (Move High Zone to Low Zone) 11–8011.12.32 - MLHZO Operation (Move Low Zone to High Zone) 11–8111.12.33 - MLLZO Operation (Move Low Zone to Low Zone) 11–8211.12.34 - MOVE Operation 11–8311.12.35 - MOVEA Operation (Move Array) 11–8511.12.36 - MOVEL Operation (Move Left) 11–8911.12.37 - MULT Operation (Multiplication) 11–92

xiv

Contents

11.12.38 - MVR Operation (Move Remainder) 11–9411.12.39 - ORxx Operation (Complex Conditional Operation) 11–9611.12.40 - PARM Operation (RPG Subprogram Parameter

Definition) 11–9811.12.41 - PLIST Operation (RPG Subprogram Parameter List) 11–10211.12.42 - READ Operation 11–10411.12.43 - READE Operation (Read Equal Key) 11–10711.12.44 - READP Operation (Read Prior) 11–10911.12.45 - RETRN Operation (Return From an RPG Subprogram) 11–11111.12.46 - RLABL Operation (EXIT Operation Parameter Definition) 11–11311.12.47 - SETnn Operation 11–11511.12.48 - SETLL Operation (Set Lower Limit) 11–11811.12.49 - SETOF Operation (Set Indicator[s] Off) 11–12011.12.50 - SETON Operation (Set Indicator[s] On) 11–12111.12.51 - SORTA Operation (Sort Array) 11–12211.12.52 - SQRT Operation (Square Root) 11–12411.12.53 - SUB Operation (Subtraction) 11–12511.12.54 - TAG Operation 11–12711.12.55 - TESTB Operation (Test Bit) 11–12811.12.56 - TESTZ Operation (Test Zone) 11–13011.12.57 - TIME Operation (Time of Day) 11–13211.12.58 - $TIME Operation (Non-Year 2000 Compliant Time of

Day) 11–13411.12.59 - XFOOT Operation (Summing the Elements of an Array) 11–13611.12.60 - Z-ADD Operation (Zero-Add) 11–13711.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–412.4.1 Record Identifying Indicators 12–4

12.4.1.1 AND and OR Relationships • 12–612.4.2 Field Indicators 12–812.4.3 Resulting Indicators 12–10

xv

Contents

12.4.4 Control Break Indicators 12–1212.4.4.1 Using Control Break Indicators • 12–1212.4.4.2 Rules for Specifying Control Break Indicators • 12–1212.4.4.3 Control Break Indicator Usage Example • 12–1412.4.4.4 Split Control Fields • 12–16

12.4.5 Overflow Indicators 12–1712.4.6 Command Key Indicators 12–1912.4.7 Halt Indicators 12–20

12.4.7.1 Processing Halt Indicators In RPG Subprograms • 12–2212.4.8 Return Indicator (RT) 12–23

12.5 INDICATORS DEFINED BY THE PROGRAM 12–2412.5.1 First Page Indicator (1P) 12–2412.5.2 Last Record Indicator (LR) 12–2612.5.3 Level Zero Indicator (L0) 12–2712.5.4 Matching Record Indicator (MR) 12–2812.5.5 External Indicators 12–30

12.6 USING INDICATORS AS FIELDS 12–3112.6.1 *IN and *IN,xx 12–3112.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–313.5.1 Sequential Organization 13–313.5.2 Relative Organization 13–313.5.3 Indexed Organization 13–4

13.6 FILE ACCESS METHODS 13–5

xvi

Contents

13.6.1 Sequential Access 13–513.6.1.1 Simple Sequential Access • 13–613.6.1.2 Sequential Access by Key • 13–613.6.1.3 Sequential Access Within Limits • 13–713.6.1.3.1 Using a Limits File • 13–813.6.1.3.2 Using the SETLL Operation • 13–11

13.6.2 Random Access 13–1213.6.2.1 Random Access by Relative Record Number • 13–1213.6.2.2 Random Access by Key • 13–1413.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–2113.7.1 Creating Sequential Files 13–2113.7.2 Creating Relative Files 13–2213.7.3 Creating Indexed Files 13–22

13.8 ADDING RECORDS TO FILES 13–2413.8.1 Adding Records to a Sequential File 13–2413.8.2 Adding Records to a Relative File 13–2513.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–2913.11.1 Checking Record Sequence for One Record Type 13–2913.11.2 Checking Record Sequence for More Than One Record

Type 13–2913.11.3 Using Matching Fields with Field-Record-Relation

Indicators 13–3013.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–114.1.1 File Specification 14–114.1.2 Line Counter Specifications 14–214.1.3 Output Specifications 14–2

14.1.3.1 File Identification Entries • 14–214.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–614.5.1 Printing Lines Before Reading the First Record: First-Page

Indicator 14–614.5.2 Specifying Page Breaks: Overflow Indicator 14–7

14.5.2.1 Automatic Handling of the Overflow Condition • 14–714.5.2.2 Handling of the Overflow Condition Using Overflow

Indicators • 14–714.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–215.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–715.5.2 Defining a Compile-Time Table 15–715.5.3 Defining a Pre-execution-Time Table 15–9

15.6 REFERENCING TABLE ENTRIES 15–10

15.7 SEARCHING TABLES 15–1015.7.1 Searching One Table 15–1115.7.2 Searching Related Tables 15–11

15.8 UPDATING TABLES 15–1315.8.1 Temporarily Updating Tables 15–1315.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–1715.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–2115.15.1 Defining Related Arrays in Alternating Format 15–2115.15.2 Defining a Compile-Time Array 15–2215.15.3 Defining a Pre-execution-Time Array 15–2315.15.4 Defining an Execution-Time Array 15–24

15.16 REFERENCING ARRAYS 15–25

15.17 SEARCHING ARRAYS 15–2915.17.1 Searching An Array 15–30

xix

Contents

15.18 MOVING ARRAY DATA 15–31

15.19 UPDATING ARRAYS 15–3215.19.1 Temporarily Updating Arrays 15–3215.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–316.3.1 Breaking a Field Down Using Subfields 16–416.3.2 Using a Data Structure Storage Area In More Than One

Way 16–516.3.3 Using a Data Structure to Reorganize Input Fields 16–6

16.4 LOCAL DATA AREA 16–616.4.1 Accessing The LDA Using SUBR21 16–7

16.5 WORKSTATION INFORMATION DATA STRUCTURE (INFDS) 16–8

CHAPTER 17 SPECIFYING AN ALTERNATE COLLATING SEQUENCEOR A TRANSLATION FILE 17–1

17.1 SPECIFYING AN ALTERNATE COLLATING SEQUENCE 17–117.1.1 Coding an Alternate Sequence Table 17–1

17.2 SPECIFYING FILE TRANSLATION PARAMETERS 17–417.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–118.2.1 File Description Continuation Specifications 18–2

18.3 PROGRAMMING CONSIDERATIONS 18–318.3.1 Programming Features Supported 18–318.3.2 Migration RPG Program Logic 18–318.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–421.3.1 File Description Specification Modifiers 21–421.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–2B.1.1 Limitations of a CONSOLE device B–2B.1.2 Coding a CONSOLE Device B–2

B.1.2.1 Console Device File Description Specification • B–2B.1.2.2 Console Device Input Specifications • B–4

B.1.3 Automatic Generation of Display Screen Formats B–7B.1.4 Displaying CONSOLE Device Files B–8

B.1.4.1 Record Identification Code • B–8B.1.4.2 Record Identifying Indicator • B–8B.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–10B.2.2 Coding a CRT Device File B–10

B.2.2.1 CRT Device File Description Specification • B–10B.2.2.2 Output Specifications • B–12B.2.2.3 Displaying Data Using a CRT Device • B–13

B.3 USING A KEYBORD DEVICE B–14B.3.1 Limitations of a KEYBORD Device B–14B.3.2 Coding a KEYBORD Device File B–14

B.3.2.1 KEYBORD Device File Description Specification • B–14B.3.2.2 Calculation Specifications • B–15B.3.2.3 KEYnn Operation • B–16B.3.2.3.1 Bypassing a KEYnn Operation • B–17B.3.2.4 SETnn Operation • B–18

INDEX

EXAMPLES1–1 Example of first cycle output specifications 1–151–2 Program using total time features 1–171–3 Example of a program using detail time features 1–192–1 Example of column numbers 2–22–2 Line number usage 2–22–3 Comments in a program 2–34–1 File Sharing 4–265–1 compile time Table and Array Coding 5–39–1 *PLACE Special Word Usage 9–149–2 Output field end position in an output record 9–2010–1 Defining character fields 10–310–2 Defining binary fields 10–510–3 Defining packed-decimal fields 10–611–1 ADD Operation Code Usage - 2 operands 11–1011–2 ADD Operation Code Usage - 1 operand 11–1011–3 ADD Operation Code Usage - Indicator controlled 11–1011–4 ANDxx Operation Code Usage 11–1211–5 BEGSR Operation Code Usage 11–1311–6 BITOF Operation Code Usage 11–1411–7 BITON Operation Code Usage 11–1611–8 CABxx Operation Code Usage 11–1811–9 CALL Operation Code Usage 11–2011–10 CASxx Operation Code Usage 11–2211–11 CASxx Operation Code Usage - Unconditional CASxx 11–2311–12 CHAIN Operation Code Usage - Relative file 11–25

xxiii

Contents

11–13 CHAIN Operation Code Usage - Indexed file 11–2611–14 COMP Operation Code Usage - Equal 11–2811–15 COMP Operation Code Usage - Greater than or equal 11–2811–16 COMP Operation Code Usage - Less than or equal 11–2811–17 COMP Operation Code Usage - Greater than, Less than, Equal 11–2811–18 DEBUG Operation Code Usage 11–3111–19 DEBUG Output 11–3111–20 DEFN Operation Code Usage 11–3311–21 DIV Operation Code Usage - Indicator Controlled 11–3511–22 DIV Operation Code Usage - Control Break 11–3511–23 DIV and MVR Operation Code Usage 11–3511–24 DO Operation Code Usage 11–3811–25 DOUxx Operation Code Usage 11–4111–26 DOWxx Operation Code Usage 11–4411–27 ELSE Operation Code Usage 11–4611–28 ENDSR Operation Code Usage 11–5011–29 EXCPT Operation Code Usage 11–5211–30 EXIT Operation Code Usage 11–5511–31 EXSR operation code Usage 11–5611–32 EXTRN, CALL, and FREE Operation Code Usage 11–5811–33 FORCE Operation Code Usage 11–6011–34 FREE Operation code Use 11–6211–35 GOTO Operation Code Usage 11–6411–36 IFxx Operation Code Usage 11–6711–37 KEYnn Operation Code Usage 11–7011–38 LOKUP Operation Code Usage 11–7611–39 MHHZO Operation Code Usage 11–7911–40 MHLZO Operation Code Usage 11–8011–41 MLHZO Operation Code Usage 11–8111–42 MLLZO Operation Code Usage 11–8211–43 MOVE Operation Code Usage 11–8411–44 MOVEA Operation Code Usage - Setup 11–8711–45 MOVEA Operation Code Usage - Array to Array (Alphameric) 11–8711–46 MOVEA Operation Code Usage - Array to Field (Alphameric) 11–8811–47 MOVEA Operation Code Usage - Field to Array (Numeric) 11–8811–48 MOVEL Operation Code Usage 11–9111–49 MULT Operation Code Usage - 2 Operands 11–9311–50 MULT Operation Code Usage - 1 Operand 11–9311–51 MULT Operation Code Usage - Indicator Controlled 11–9311–52 MVR Operation Code Usage 11–9511–53 ORxx Operation Code Usage 11–9711–54 CALL and PARM Operation Code Usage 11–10111–55 PLIST and *ENTRY PLIST Usage 11–10311–56 READ Operation Code Usage 11–10611–57 READE Operation Code Usage 11–108

xxiv

Contents

11–58 READP Operation Code Usage 11–11011–59 RETRN Operation code Use 11–11211–60 RLABL Operation Code Usage 11–11411–61 SETnn Operation Code Usage 11–11711–62 SETLL Operation Code Usage 11–11911–63 SETOF Operation Code Usage 11–12011–64 SETON Operation Code Usage 11–12111–65 SORTA Operation Code Usage 11–12311–66 SQRT Operation Code Usage 11–12411–67 SUB Operation Code Usage - 2 operands 11–12611–68 SUB Operation Code Usage - 1 operand 11–12611–69 SUB Operation Code Usage - Indicator controlled 11–12611–70 TAG Operation Code Usage 11–12711–71 TESTB Operation Code Usage 11–12911–72 TESTZ Operation Code Usage 11–13111–73 TIME Operation Code Usage 11–13311–74 $TIME Operation Code Usage 11–13511–75 XFOOT Operation Code Usage 11–13611–76 Z-ADD Operation Code Usage 11–13711–77 Z-SUB Operation Code Usage 11–13812–1 Record Identifying Indicators Usage 12–512–2 Output generated by Example 12–1 12–612–3 AND/OR Usage With Record Identifying Indicators 12–712–4 Field Indicator Usage 12–912–5 Resulting Indicator Usage 12–1112–6 Control Break Indicator Usage 12–1412–7 Split control fields 12–1612–8 Overflow Indicator Usage 12–1812–9 Halt Indicator Usage - Record Identification 12–2112–10 Halt Indicator Usage - Field Indicator 12–2112–11 Halt Indicator Usage - Resulting Identification 12–2112–12 Return Indicator Usage 12–2312–13 First Page Indicator Usage 12–2412–14 Output generated by Example 12–13 12–2512–15 Last Record Indicator Usage 12–2612–16 Output generated by Example 12–15 12–2612–17 Level Zero Indicator Usage 12–2712–18 Matching Record Indicator Usage 12–2912–19 External Indicator Usage 12–3012–20 *IN Indicator Array And Element Usage 12–3112–21 *IN Indicator Array And Element Usage 12–3213–1 File Description specification for a primary sequential file -

Sequential file access 13–613–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 - Sequentialaccess within limits 13–8

13–4 File Description and Extension specifications for a primary indexedfile - Sequential access within limits 13–11

13–5 Limits Processing - SETLL operation code usage 13–1213–6 Random access by relative record number 13–1413–7 Random access by key 13–1613–8 Random access by addrout file 13–1913–9 Random and sequential access using a full-procedural file 13–2013–10 Creating a sequential file 13–2113–11 Creating an indexed file 13–2313–12 Adding records to a sequential file 13–2413–13 Adding records to an indexed file 13–2613–14 Updating records in an indexed file 13–2713–15 Deleting records from an indexed file 13–2813–16 Declaring matching record fields 13–3013–17 Using OR operation in an Input specification 13–3113–18 Matching record fields and field-record-relation indicators 13–3113–19 Matching record fields with field-record-relation indicators 13–3113–20 Matching record fields in primary and secondary files 13–3613–21 Multikey file access 13–3814–1 Sample Report Program using Spacing and Skipping 14–614–2 Sample Report Program using an Overflow Indicator 14–914–3 Sample Output from Report using an Overflow Indicator 14–1014–4 Sample Report Program using Fetch Overflow 14–1215–1 Migration RPG Program using a compile-time table 15–215–2 Table Input Record 15–515–3 Related Tables - Multiple entries per record 15–515–4 Related Tables - Single entry per record 15–615–5 Extension Specification to define a compile-time table 15–815–6 Extension Specification to define compile-time related tables 15–915–7 Definition of a Pre-execution-Time Table 15–915–8 Single table LOKUP 15–1015–9 Related table LOKUP 15–1215–10 Program table LOKUP 15–1215–11 LOKUP using a sequenced table 15–1315–12 Program to temporarily update a table 15–1415–13 Updating a pre-execution-time table 15–1415–14 Outputting a table 15–1515–15 Program using compile-time arrays 15–1715–16 Array Input Record 15–1915–17 Related arrays defined using multiple entries per record 15–1915–18 Related arrays defined using a single entry per record 15–2115–19 Compile-time array 15–2315–20 Execution-time array load from data file 15–25

xxvi

Contents

15–21 Execution-time array load from data file 15–2515–22 Program using execution-time arrays 15–2815–23 Array LOKUP 15–3015–24 Array LOKUP with starting position 15–3015–25 Program using LOKUP on an array 15–3115–26 Program using MOVEA on an array 15–3215–27 Updating a pre-execution-time array 15–3315–28 Writing an execution-time array 15–3415–29 Writing individual array elements 15–3416–1 Input field redefined by subfields 16–416–2 Using a data structure to define multiple input records 16–516–3 Input fields reorganized by a data structure 16–616–4 Local data area data structure 16–616–5 Accessing the LDA via SUBR21 16–716–6 WORKSTN Information Data Structure 16–817–1 Alternate Sequence Table 17–317–2 File Translation Parameter Records 17–618–1 Sample Migration RPG Program using SPECIAL Device Files 18–618–2 SPECIAL Device Subroutine TESTSBR100 18–1018–3 SPECIAL Device Subroutine TESTSBR200 18–1218–4 SPECIAL Device Subroutine TESTSBR300 18–1418–5 SPECIAL Device Subroutine TESTSBR400 18–1618–6 SPECIAL Device Subroutine TESTSBR500 18–1818–7 Report Generated by the Sample Migration RPG Program

SPCDEV 18–1919–1 CALL and PARM Opcode Usage - Example 1 19–319–2 EXTRN, Use of Underscore in Subprogram Name 19–419–3 EXTRN, CALL, and FREE Opcode Usage 19–519–4 FREE Opcode Use 19–619–5 CALL and PARM Opcode Usage - Example 2 19–1019–6 PLIST and *ENTRY PLIST Usage 19–1119–7 RETRN Opcode Use 19–1319–8 RPG Calling Program - CALL.RPG 19–1419–9 RPG Subprogram - LFTJST.RPG 19–1519–10 Commands Used to Build CALL Program 19–1619–11 RPG Calling Program - PASS1.RPG 19–1719–12 Macro-32 Interface Module - PASS1M.MAR 19–1819–13 COBOL Subprogram - PASS1C.COB 19–1919–14 Commands Used to Build PASS1 Program on a VAX System 19–1919–15 Commands Used to Build PASS1 Program on an Alpha or Integrity

System 19–1920–1 RPG Program Calling External Subroutine 20–220–2 Sample Macro-32 External Routine 20–321–1 Compile Qualifier (U) specification 21–321–2 /COPY statement layouts 21–3

xxvii

Contents

21–3 /COPY statement usage 21–421–4 File Description specification modification 21–521–5 Input field modification 21–6B–1 Compiling and linking a CONSOLE program B–7

FIGURES1–1 Flowchart of Basic RPG Logic Cycle 1–51–2 Detailed RPG Logic Cycle Flowchart 1–810–1 Format of a Character String 10–210–2 Address of a String 10–210–3 Word Data Type 10–410–4 Longword Data Type 10–410–5 Packed-decimal Data Type 10–610–6 Zoned-Decimal Data Type (123+) 10–810–7 Trailing Numeric Data Type (123-) 10–810–8 Zoned-Decimal Data Type (123-) 10–811–1 Fixed-Length Descriptor Format 11–9913–1 Sequential File Organization 13–313–2 Relative File Organization 13–413–3 Indexed File Organization 13–413–4 Index Key Value 13–513–5 Sequential File Access Within Limits 13–913–6 Creating an Addrout File 13–1713–7 Using Matching Fields For Multifile Processing 13–3319–1 Fixed-Length Descriptor Format 19–8

TABLES2–1 Column 6 (RPG Specification Identification Codes) 2–33–1 Column 7 (Comment or Compiler Directive) 3–23–2 Column 15 (DEBUG Option) 3–23–3 Column 18 (Currency Symbol) 3–33–4 Column 19 (Date Format Code) 3–33–5 Column 20 (Date Edit Code) 3–43–6 Column 21 (Inverted Print Code) 3–53–7 Column 26 (Alternate Collating Sequence) 3–53–8 Column 43 (File Translation Code) 3–63–9 Column 60 (Zoned-decimal output) 3–64–1 Column 7 (Comment or Compiler Directive) 4–24–2 Column 15 (File Type) 4–34–3 Device Types and File Types 4–44–4 Column 16 (File Designation) 4–44–5 Column 17 (End-of-File) 4–6

xxviii

Contents

4–6 Column 18 (Sequence Code) 4–74–7 Column 19 (File Format) 4–74–8 Columns 24 - 27 (Record Length) 4–84–9 Column 28 (Processing Mode) 4–94–10 Modes of Processing for Sequential Files 4–104–11 Modes of Processing for Relative Files 4–114–12 Modes of Processing for Indexed Files 4–124–13 Modes of Processing for Printer Files 4–134–14 Modes of Processing for Workstation Files 4–134–15 Modes of Processing for Record Address Files 4–134–16 Modes of Processing for KEYBORD Files 4–144–17 Modes of Processing for SPECIAL Files 4–144–18 Columns 29 - 30 (Key Length) 4–154–19 Column 31 (Record Address Type) 4–154–20 Valid Combinations of Entries in Columns 28 and 31 for Primary,

Secondary, and Demand Files 4–164–21 Valid Combinations of Entries in Columns 28 and 31 for Chained

Files 4–164–22 Valid Combinations of Entries in Columns 28 and 31 for

Full-Procedural Files 4–164–23 Column 32 (File Organization) 4–174–24 Columns 33 - 34 (Overflow Indicator) 4–174–25 Columns 35 - 38 (Key Start Location) 4–184–26 Column 39 (Extension Code) 4–184–27 Columns 40 - 46 (Device Code - Standard Migration RPG Device

Types) 4–194–28 Columns 40 - 46 (Device Code - Supported Migration RPG Device

Types) 4–194–29 Column 53 (Continuation Lines) 4–204–30 DISK File Continuation Option 4–214–31 SPECIAL Device File Continuation Option 4–224–32 WORKSTN File Continuation Options 4–234–33 Column 66 (File Addition) 4–244–34 Columns 68 - 69 (Alternate Key) 4–244–35 Columns 71 - 72 (File Conditioning Indicator) 4–254–36 Column 73 (File Sharing) 4–264–37 Column 74 (No Deferred Write) 4–275–1 Column 7 (Comment or Compiler Directive) 5–25–2 Columns 11 - 18 (From-File Name) 5–25–3 Columns 19 - 26 (To-File Name) 5–35–4 Columns 27 - 32 (Array or Table Name - Primary Entry) 5–45–5 Column 33 - 35 (Number of Entries Per Record) 5–45–6 Columns 36 - 39 (Number of Entries in a Table or Array) 5–55–7 Columns 40 - 42 (Length of Entry - Primary Entry) 5–65–8 Column 43 (Data Format - Primary Entry) 5–75–9 Column 44 (Decimal Positions - Primary Entry) 5–7

xxix

Contents

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

xxx

Contents

9–2 Columns 7 - 14 (File Name) 9–29–3 Columns 14 - 16 (AND/OR) 9–29–4 Column 15 (Record Type) 9–39–5 Columns 16 - 18 (ADD/DEL) 9–49–6 Column 16 (Fetch Overflow or Release) 9–59–7 Column 17 (Space Before) 9–69–8 Column 18 (Space After) 9–69–9 Columns 19 - 20 (Skip Before) 9–79–10 Columns 21 - 22 (Skip After) 9–89–11 Columns 23 - 31 (Output Indicators) 9–109–12 Columns 32 - 37 (Field Name) 9–129–13 Output EXCPT Names 9–169–14 Column 38 (Edit Codes) 9–179–15 Edit Codes and Examples 9–189–16 Column 39 (Blank After) 9–199–17 Columns 40 - 43 (End Position in Output Record) 9–209–18 Column 44 (Output Data Format) 9–219–19 Columns 45 - 47 (Constant or Edit Word) 9–239–20 Columns 45 - 70 (Edit Words) 9–259–21 Using Edit Words to Display Negative Numbers 9–2710–1 Zoned-decimal representation of digits 10–711–1 Examples of MOVE Operation Results 11–8411–2 Results of MOVEA operation in Example 11–45 11–8711–3 Results of MOVEA operation in Example 11–46 11–8811–4 Results of MOVEA operation in Example 11–47 11–8811–5 Descriptor Types and Use 11–9911–6 Default Descriptor Types 11–10012–1 Available Indicators 12–112–2 Program Defined Indicators 12–212–3 Record Identifying Indicators 12–412–4 AND and OR Relationships 12–612–5 Field Indicators 12–812–6 Field Indicators 12–1012–7 Command Key Indicators 12–1913–1 Matching Field Lengths 13–3013–2 Matching Primary and Secondary File Field Values 13–3213–3 Matching Field Values 13–3613–4 Processing Records with Matching Fields 13–3715–1 Array Element Values 15–2715–2 Array Elements in Calculations 15–2716–1 Data Structure Specification Layout 16–116–2 Data Structure Subfield Specification Layout 16–217–1 Alternate Sequence Table Record Layout 17–217–2 File Translation Parameter Record Layout 17–518–1 File Specification 18–2

xxxi

Contents

18–2 File Continuation Specification Description 18–218–3 File Control Data Structure 18–318–4 Array Control Data Structure 18–418–5 Return Condition Codes 18–418–6 File Type Update - Operation Codes 18–518–7 File Type Combined - Operation Codes 18–519–1 Descriptor Types and Use 19–819–2 Default Descriptor Types 19–921–1 Compile Qualifier (U) Specification Layout 21–221–2 Input Field Modifier Entries 21–621–3 Auto Report Specification Limitations 21–8B–1 Rules for Coding CONSOLE Device File Description Specification B–2B–2 Rules for Coding CONSOLE Device File Input Record

Specifications B–4B–3 Rules for Coding CONSOLE Device File Input Specifications B–6B–4 CONSOLE Device File Display Formats B–8B–5 Rules for Coding CRT File Description Specification B–11B–6 Rules for Coding CRT Output Specification B–12B–7 Rules for Coding CRT Output Field Specifications B–13B–8 Rules for Coding KEYBORD Device File Description Specification B–14B–9 Rules for Coding KEYBORD Calculation Specification for a KEYnn

Operation B–16B–10 Rules for Coding KEYBORD Calculation Specification for SETnn

Operation B–18

xxxii

Preface

This manual describes the features, uses, constructs, and syntax of theMigration RPG programming language on OpenVMS systems.

Intended AudienceThe Migration RPG User’s Guide is intended for programmers who arefamiliar 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 andwas modeled after IBM System/36™ RPG II. It has since been enhancedbeyond the scope of IBM System/36 RPG II to provide a more genericand 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 ManualThe following conventions are used in this manual to describe commandsand keystrokes:

Convention Meaning

CTRL/X This sequence indicates that the user must hold downthe key labeled CTRL while pressing another key.

PF1 + X This sequence indicates that the user must first pressand release the key labeled PF1, then press and releaseanother key.

RETURN or <RETURN> A keyname is shown enclosed or within angle bracketsto indicate a key on the keyboard to be pressed by theuser.

.

.

.

A vertical ellipsis indicates the omission of items froma code example or command format. The items areomitted because they are not important to the topic beingdiscussed.

( ) In format descriptions, parentheses indicate that, if morethan one option is chosen, the options must be enclosedin parentheses.

[ ] In format descriptions, optional parameters in acommand are denoted by square brackets. If acommand delimiter, such as a comma or slash, isincluded within the square brackets, it is also optional. Ifthe delimiter is outside the square brackets, it is requiredin the command line. Never include the square bracketsin the command line.

BOLDFACED TEXT Commands entered by the user at the terminal areprinted in boldfaced type.

xxxiii

Preface

Associated DocumentsAdditional information concerning Migration RPG can be found in thefollowing manuals:

• Migration RPG User’s Guide

• Migration RPG Screen Format Reference Manual

Additional information concerning the use of OpenVMS with MigrationRPG 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 followingmanuals:

• OpenVMS S/3X Conversion Assistance Manual

• OpenVMS S/3X Conversion Tools User’s Guide

Additional information concerning RPG programming can be found in thefollowing books:

• Computer Programming - RPG II, by Gary B. Shelly & Thomas J.Cashman

• RPG and RPG II Programming; Applied Fundamentals, A JobApproach 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 theirherculian efforts to compile and proof this manual.

xxxiv

1 Understanding the Migration RPG Logic Cycle

1.1 Migration RPG OverviewMigration RPG is a programming language that provides a convenientand efficient means of preparing a wide variety of interactive and batchprograms. The language is well suited to performing commercial dataprocessing tasks. Migration RPG is an extended implementation of theRPG II language that was developed by IBM; it includes extensions forintegration with the OpenVMS architecture. Migration RPG runs underthe OpenVMS operating system and consists of an RPG compiler, screenformat compiler, RPG language editor, and run-time support utilities.For convenience, Migration RPG is referred to as RPG throughout thismanual.

RPG is a nonprocedural language; that is, every program compiled bythe Migration RPG compiler executes according to a fixed plan. Unlike aprocedural language, such as COBOL, the logic of this plan is not suppliedby the programmer, but is built into the compiler. This built-in logic iscalled the RPG logic cycle. The execution of a RPG program consists of anumber of iterations of the logic cycle.

1.2 RPG Program SpecificationsA programmer provides directions to an RPG program using RPG programspecifications. Specifications are the column-oriented instructions whichdefine input and output formats, arithmetic processes, and specialoperations to be performed depending on the data input and desiredoutput. 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 defineRPG workstation screens and Menu and Prompt Utility screens. These arethe Screen Specification (S), Help Specification (H), and Field DescriptionSpecification (D). These specifications are covered in the Migration RPGScreen Format Reference Manual.

1–1

Understanding the Migration RPG Logic Cycle

Each specification is structured in an 80-column format, with thespecification type indicated by a character in column 6; the columnsare grouped into fields according to the purpose of the specification.Specifications are grouped together by type and must appear in a fixedorder in an RPG program. The following sections briefly describe eachspecification and indicate the order in which the specifications mustappear in a program.

1.2.1 Control Specification - HThe 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 - FThe File Description Specification defines all of the files and devices anRPG program accesses. For RPG programming purposes, it is easiest tothink of device access as another form of file access. The File specificationprovides 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 - EThe Extension Specification describes all record address files, tablefiles, arrays and tables used by a program. They contain the followinginformation:

• 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 - LThe Line Counter Specification is used to define the number of lines on areport page, should this number vary from the default of 66. The followinginformation is provided to the compiler:

• Number of lines per page

• Overflow line on page

1.2.5 Input Specifications - IInput Specifications describe the record layouts of input files. They alsodefine data structures and their elements. They include the followinginformation:

• 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 - CCalculation Specifications describe the operations which can be carriedout in an RPG program. Calculation specifications can control I/Ooperations and are divided into detail and total time sections. Calculationspecifications 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 - OOutput Specifications describe the layout of report, output, and updatefiles, records, and fields. They also provide mechanisms to allow theprogrammer to control output of data. They include the followinginformation:

• 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 moredetailed explanation of each specification.

The fixed RPG logic cycle was designed specifically to accommodate thesequence of operations needed to generate most common business reportsand file maintenance functions. However, the fixed nature of the RPGlogic cycle does not prevent the programmer from controlling the set offunctions performed for each input record and the sequence and timingof these functions. This control is provided by the use of indicators inthe Input, Calculation, and Output specifications, and operation codes(opcodes) in the Calculation specifications.

For example, by setting various indicators on or off when certainconditions occur, control of the sequence of program execution withinthe phases of the normal logic cycle can be affected. See Chapter 12,Using Indicators, for more information on indicators. Opcodes such asCALL, GOTO, READ, and EXCPT can be used to add additional flexibilityto the RPG logic cycle. See Chapter 11, Operation Codes, for descriptionsof the RPG opcodes.

To write effective RPG programs and take advantage of the flexibility andcontrol provided with the RPG logic cycle, it is important to thoroughlyunderstand the structure and timing characteristics of the cycle, and torecognize both RPG’s special capabilities and its limitations.

There are 11 fundamental operations that are performed during theoperation (and reiterations) of the RPG logic cycle, as shown in Figure 1–1,Flowchart of Basic RPG Logic Cycle. These steps are described in theaccompanying keyed list.

1–4


Figure 1–1 Flowchart of Basic RPG Logic Cycle

START

(1)

Perform heading anddetail output.

(5)

Has a Yes Set on appropriatecontrol breakindicators.

control breakoccurred?

End of job

on?

No

(2)

Turn off controlbreak and recordID indicators.

Is the

YesFirst cycle?

indicator

No

(3)

Read a record.

Yeslast record

No

(4)

Total time calcs.

(6)

Total time output.

(7)

Make record read instep 3 available tothe program.

(8)

Detail calcs.

(9)

(10)

(11)

1–5


Key to Figure 1–1, Flowchart of Basic RPG Logic Cycle:

During program startup, or the first cycle, several initialization tasks areaccomplished. Files are opened; the local data area is loaded; the systemdate is obtained from the system; and counters, tables, and arrays areinitialized. RPG programs actually start the program cycle in the outputsection. While this might seem odd at first glance, it is done to give theprogrammer the opportunity to output heading information in reportsbefore 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 becontrolled by indicators. Heading and detail specifications contain anH 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 seton.

4 If the control field of the record just read is different from the controlfield of the previous record, a control break occurs. If no control breakhas occurred, the program branches to step 6.

5 When a control break occurs, the appropriate control break indicatoris set on, plus all lower control break indicators, except L0 which isalways 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 calculationsare performed. Total time calculations are indicated by control breakindicators in columns 7 - 8 of the Calculation specifications.

8 Total time output is performed. Output specifications with a Tin column 15 are processed if the appropriate indicator specifiedconditions are satisfied.

9 The program checks the last-record indicator. If it is on, the programenters 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 readin step 3. Detail level calculations consist of Calculation specificationswhich do not have a control break indicator (L1 - L9) specified incolumns 7 - 8.

Upon detecting the last-record indicator, the program enters the last cycle,does one-time cleanup work, including total calculations and total outputoperations, and ends.

1–6


1.3 The RPG Logic CycleEvery RPG program follows the same sequence of execution steps whichform the normal logic cycle. Special operations, such as matching recordfields, chaining, overflow processing, and look-ahead processing, are allhandled within the flow of the logic cycle.

In standard RPG programs (programs which do not deliberately disruptthe cycle) the RPG logic cycle is executed once for each primary inputrecord. The logic cycle consists of the following three steps, performed inorder 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 thenext record is input. The RPG coding specifications determine the rangeand type of functions performed during each cycle. During the calculationand output steps within each cycle, there are two distinct timing phases:

• Total time operations are performed on summary data accumulatedfrom 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 timecharacteristics and operations.

The first and last cycles of an RPG program are different from the rest ofthe cycles in the program. They are responsible for program startup andshutdown operations. These cycles are described in detail in the sections1.4.1 and 1.4.3.

1.4 The RPG Logic Cycle in DetailThis section consists of a detailed, annotated flowchart describing theRPG logic cycle. The following subsections describe specific parts of theRPG cycle, such as the first cycle, last cycle, total time, and detail time ingreater 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 breakindicators (L1 − L9)Turn off record identify−ing indicators.Turn off overflow indic−cators (OA − OG, OV).

(2a)Yes

Program Active? Getparameters

NoLast No

record ind.(LR) on?

Yes

Turn on allcontrol breakindicators(L1 − L9).

Halt Noindicator(s) Return

(5a)

Return

(5c)

Cancel?No

No

Continue withGoto step 25

(2)

(3)

(9)

(10)

(11)

(12)

(13)

(14)

Initialize fields, datastructures, tables, andarrays.Load local data area.Open files.

Yes

on?

No

Goto step 25

parameters

Yes

indicator (RT)on?

Issue messageto user.

Primary

RETURN

(4)

Perform header output.Perform detail output.Perform overflow output.This step is the returnpoint for a normal RPGcycle.

Yes Yesfile present?

(5b)

(5)*GETIN

Prepare to terminate theprogram.

step 15Goto step 33

Clearhaltind.

(6)

(7)

Figure 1–2 Cont’d on next page

1–8


Figure 1–2 (Cont.) Detailed RPG Logic Cycle Flowchart

(15) (23)

On first cycle, retrievea record from the primaryand all secondary files.

On all other cycles,retrieve a record fromthe last file processed,if required.

Have Nocontrol fields

changed?

Yes

Set on appropriatecontrol break indicators(L1 − L9).

Read Yesbeing forced?

No NoLR on?

Matchingfields (MR) Yes

LR totaltime operations

?

(19a) *CANCLEnd

Set onL1 − L9,and LR

Goto step 36

(33)

Close all files.No

If present, prepareparameters forreturn to callingprogram.

break indicators

Set returnstatus andexit program.

(16)

(17)

(18)

(24)

Match fields routine.

Yes

Total time calculations.of job

No

YesHave

present?

conditions

No

taken place

met?

(34)

(19)

(20)

(25)

Identify record and seton record ID indicators.

No

Total time output.

Yes

No

LR on?

a recordidentified?

YesWas

(35)

(21)

(22)

(26)

Process halt indicators.

No

Yes

Control−

specified?

(27)

Output tables and arrays.

Yes

(28)

Output local data areaand external indicators.

(29)

(30)

(31)

(32)


1–9


Figure 1–2 (Cont.) Detailed RPG Logic Cycle Flowchart

(36)

(37)

Overflow Noindicators on?

Yes

Overflow output routine.

Set MR indicator on or off.

Look−ahead

specified?fields

Goto step 4

(38)

No

Yes

Make data available fromlast record read.Set field indicators.

(39)

Look−ahead routine.

(40)

(41)

Process detailcalculations.

(42) *DETC

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 byRPG subprograms.

2 RPG checks if this is the first invocation of the program. If it is, RPGcontinues with step 3. If it is not (meaning that it is a subprogramwhich has already been called at least once and has not been re-initialized), PARM statements in the *ENTRY PLIST, which specifyfields in the result field and factor 1, are processed and the programjumps to step 5.

1–10


3 Program initialization occurs. Initialization consists of retrieving dateinformation (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 datastructures, and loading all pre-execution-time tables and arrays. Ifthis is an RPG subprogram using a *ENTRY PLIST, data is movedfrom the result field to factor 1 in the PARM statements which specifyboth fields.

Note: The $UDATE, $UDAY, $UMNTH, and $UYEAR reserved wordsare supplied to provide backward compabitility with 6-digitnon-Year 2000 compliant dates. See the Migration RPG Year2000 Compliance Guide for more information concerning thesefields.

Normal cycle processing

4 RPG writes heading and detail lines (identified by H or D in column 15of the Output specification). If conditioning indicators are specified, theconditions for the indicator must be satisfied before the specificationwill be output. If fetch overflow logic is specified and the overflowindicator is on, the appropriate overflow lines are output. If the1P indicator is on (during the first cycle only), RPG prints all linesconditioned by it. RPG executes this step at the beginning of theprogram so that heading lines can be printed before the first datarecord is read.

5 RPG checks whether any halt indicators (H1 - H9) are on. If ahalt indicator is set and the program is running in an interactiveenvironment, the user is prompted to enter one of the followingoptions:

• CONTINUE - This option tells the program to clear the haltindicator 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 beabbreviated to a single character: C, E, or K.

For all intents and purposes, the EXIT and KILL option do the samething in the Migration RPG processing environment. They cause acontrolled shutdown of the program and, depending upon the compileroptions selected, may return a warning status when the program exits.Both the EXIT and KILL prompts are supported by Migration RPG tooffer a level of compatibility with non-OpenVMS versions of RPG.

The program will cycle through step 5 until all nine halt indicatorshave been checked or the user selects the EXIT or KILL option at thehalt indicator prompt.

If the program is running as a batch job and a set halt indicator isencountered at this step, the program will terminate immediately,returning an error status. See Chapter 12, Using Indicators for moreinformation concerning the use of halt indicators.

1–11


If no halt indicators are set or if the user clears all set halt indicatorsusing the CONTINUE option, the program jumps to step 8. If a haltindicator is set and the program is running in batch mode, or the userselects the EXIT or KILL options at the halt prompt, the programproceeds to step 6.

The step also serves as the return point for a *GETIN operation at theend of a INFSR subroutine.

6 The program is being terminated due to a halt. Image terminationprocessing to handle the halt condition begins at this step.

7 The program jumps to step 33 to complete the halt-inducedtermination.

8 Control break indicators (L1 - L9), first page indicator (1P), and allrecord-identifying indicators are set off. Overflow indicators (OAthrough OG, and OV) are also set off unless they were set on in theprevious cycle during detail calculations or detail output. All othertypes of indicators that are on remain on.

9 The last record indicator (LR) is checked. If it is on, the programproceeds to step 10 and begins last cycle processing. If it is not on, theprogram 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 continueswith step 12, which will prepare for an immediate exit from theprogram. If it is not on, the program jumps to step 14.

12 If the program contains a *ENTRY PLIST, contents of the fieldsspecified in factor 2 of the PARM statements are transferred to theresult field in preparation for passing the parameter information backto the calling program.

13 The subprogram returns immediately to the calling program. Files,fields, and indicators are left as they are currently set when asubprogram exits in this fashion. If the subprogram is called again,it will start up with all of these settings intact. The calling programcan initialize the subprogram before calling it again using the FREEoperation.

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 andeach of the secondary files. On all other cycles, the program reads arecord from the last file processed, if required. If a record address fileis being used, the data retrieved from the record address file identifiesthe record that is to be retrieved. If look-ahead fields are specifiedin the last record processed, the record required may already be instorage, meaning that no read will be necessary at this point.

16 If a FORCE instruction was processed during the previous cycle, theprogram selects that file for processing. If a FORCE command isprocessed, the program jumps to step 19, bypassing matching recordprocessing.

1–12


17 The program determines if matching fields have been specified. If theyare, the program continues with step 18; if not, the program jumps tostep 19.

18 The matching field routine takes control. It selects the next recordto process by matching field content between records. If a recordis processed out of sequence, the matching record routine issuesa halt and gives the user the option of bypassing the bad recordor terminating the program. See Section 13.11, Processing Fileswith Matching Records, for more information on matching recordprocessing.

19 RPG determines if end-of-job conditions have been met and the lastrecord indicator (LR) should be turned on. End-of-job is signified whenall primary and secondary files with an E specified in column 17 of theFile specification are at end-of-file. If end-of-job conditions are met, thelast record (LR) and control break indicators (L1 - L9) are turned onand the program jumps to step 25.

Step 19a serves as the return point for a *CANCL operation at the endof 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 issuedand the user is prompted to continue or terminate the program.

21 RPG checks to determine that a record was successfully identified forprocessing. If a record was not identified, the program jumps to step25.

22 The program checks to see if control break processing has beenspecified. If not, the program jumps to step 25.

23 RPG determines whether the record selected for processing has causeda control break to occur. A control break occurs when the value inthe control field of the record being processed differs from the previousvalue of the control field. If no control break has occurred, the programjumps to step 25.

24 If a control break has occurred, RPG saves the contents of allappropriate control fields. It then sets the appropriate control breakindicator (L1 - L9) on; at the same time, RPG sets all lower-levelcontrol break indicators on.

Final cycle processing begins here. The final cycle steps are intermixedwith normal cycle steps.

25 The program checks to see if the last record indicator (LR) is on. If LRis on, the program proceeds to last cycle processing. If LR is off, theprogram jumps to step 27.

26 If last record processing is taking place, the program checks to seeif final cycle total time calculations need to be performed. If not, theprogram jumps to step 29.

27 Total time calculations are performed. Calculation specifications withcontrol break indicators (L1 - L9) turned on in columns 7 - 8 areprocessed.

1–13


28 Total time output is processed. Any Output specifications conditionedby control break indicators (L1 - L9) are output at this time.

29 The program checks to see if the last record indicator (LR) is on. Ifnot, it jumps to step 36 and continues a normal cycle. If LR is on, theprogram continues with step 30 and begins the final steps in the lastcycle.

30 Halt indicators are processed. If a halt indicator is on, the useris prompted to enter the CONTINUE, EXIT, or KILL option. TheCONTINUE option will clear the halt indicator in question. The EXITor KILL options will allow the program to terminate with the haltindicators set, causing the program to exit with a warning status.

31 Tables and arrays which have a file name specified in the Extensionspecification (columns 19 - 26) are output.

32 External indicator settings and the contents of the local data area areoutput.

33 All open data files are closed.

34 If the program contains a *ENTRY PLIST, contents of the fieldsspecified in factor 2 of the PARM statements are transferred to theresult field in preparation for passing the parameter information backto the calling program.

35 The return status value is set and the program exits. If this is asubprogram, the return status value will be used to indicate the exitstatus of the subprogram to the calling program.

36 RPG determines whether any overflow indicators (OA through OG, orOV) are on. If so, processing continues with step 37; otherwise, theprogram jumps to step 38.

37 The overflow routine receives control. All output operationsconditioned by overflow indicators are processed.

38 The matching record indicator (MR) is set on or off. If the programcontains multiple files and the record to be processed is a matchingrecord, 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. Fieldindicators (columns 65 - 70 in the Input specification) are set at thistime.

40 If look-ahead fields have been specified, the program continues withstep 41; otherwise, it jumps to step 42.

41 The look-ahead routine is run. The look-ahead record is read andlook-ahead fields are extracted from the record.

42 The program performs detail calculations. After the detail calculationssection has been completed, the program branches back to step 4 torepeat the cycle.

Step 42 also serves as the return point for a *DETC operation at theend of a INFSR subroutine.

1–14


1.4.1 The First CycleWhen program execution begins and before the first input record isread, several one-time-only operations are performed. These operationsconstitute the first cycle. Output control during the first cycle can beaccomplished using Output specifications conditioned by the first-page (1P)indicator, and by using Output specifications with either no conditioningindicators or with all negative conditioning indicators. (See Chapter 12,Using Indicators, for more details on conditioning indicators.) The firstcycle is generally used to output initial headings for reports. During thefirst cycle, RPG performs the following initialization operations:

• If a *ENTRY PLIST is present, the parameters are read into theprogram.

• 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 allnegative 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 atotal time phase, RPG bypasses all total time calculations and total timesteps 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 thatthe associated specifications should only output during the first cycle.

Example 1–1 Example of first cycle output specifications

1 2 3 4 51234567890123456789012345678901234567890123456789012345678

OREPORT H 1PO 35 ’SALES REPORT’O UDATE 80 ’ / / ’

1.4.2 A Normal CycleA normal cycle in an RPG program can be defined as any cycle exceptthe first or the last. During a normal cycle, RPG performs the followingoperations:

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

Steps 4 and 5 constitute total time operations; steps 1, 2, and 7 constitutedetail time operations. These steps are discussed in more detail in thefollowing sections.

This list of steps in a normal cycle is an overview only. Figure 1.4 presentsa detailed description of the RPG logic cycle.

1.4.2.1 Total Time ProcessingTotal time processing is triggered by control breaks which occur when acontrol break indicator (L1 - L9) is set. Control break indicators are setwhen the data in a control break field is changed. Control break fields arechecked when a record is input.

During total time, RPG checks which control break indicators (L1 throughL9) are defined and the control field associated with each. (See Chapter 12,Using Indicators, for details on using control break indicators.) Forexample, in an application involving the generation of a monthly salesreport, total time calculations and output for total sales by region arecontrolled by L8; total time processing for total sales by district office arecontrolled by L7; and total time processing for total sales by salespersonare controlled by L6. Example 1–2 illustrates how such a program mightbe coded.

1–16


Example 1–2 Program using total time features

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*FSALESFILIPE F8000 80 DISKFREPORT O F 80 PRINTER*ISALESFILAA 01I 01 04 REGIONL8I 05 08 DIST L7I 09 38 SALNAMI 39 44 SALEIDL6I P 45 492SALES

.

.

.C SALES ADD SALTOT SALTOT 92

.

.

.CL6 SALTOT ADD DISTOT DISTOT 92CL7 DISTOT ADD REGTOT REGTOT 92CL8 REGTOT ADD GRAND GRAND 102

.

.

.OREPORT T L6O 20 ’Total for Sales Person:’O SALNAM 51O SALEID 60O SALTOT B 80 ’$ , , . ’OREPORT T L7O 20 ’District Total’O DISTOT B 80 ’$ , , . ’OREPORT T L8O 20 ’Regional Total’O REGTOT B 80 ’$ , , . ’OREPORT T L9O 15 ’Grand Total’O GRAND B 80 ’$ , , . ’

In example 1–2, the following steps take place during total timeprocessing. 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 thesalesperson identification number in the current record differs fromthe salesperson identification number in the previous record, a controlbreak occurs and the indicator L6 is turned on. When the L6 indicatoris turned on, all lower control break indicators are turned on as well.Thus, the L6 control break turns on indicators L1 - L6. During totaltime processing, the program will perform all L1 - L6 total timecalculations and output specifications. In the example, these are theaccumulated total sales for the salesperson whose number was foundin the previous record.

• During another cycle, the region identifier field changes. This will turnon control break indicators L1 - L8. In this case, all L1 - L8 total timecalculations and output will be performed. In the example, the totaltime processing for salesperson (L6), district (L7), and region (L8) willall 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 oflast cycle total time processing. With indicators L1 - L9 on, all totaltime calculations and output are performed. In the case of the sampleprogram, 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 processedand total time processing takes place, detail time processing begins.Detail time operations are for the record just read and are described inthe next section.

1.4.2.2 Detail Time ProcessingDuring detail time, a program performs operations specified in the detailOutput specifications and detail calculation sections. Example 1–3expands upon the total time example (1–2) by including some headingand detail time Output specifications.

In example 1–3, the following steps take place during the detail cycle. Inreferring back to the detailed logic cycle (figure 1–2, this description of thedetail processing cycle will be starting at step 42.

1 During processing of detail calculations, the total sales for thesalesperson are added to the sales total (SALTOT) accumulator field.

2 Header and detail output take place. In the example, if any of thecontrol break indicators were turned on during the previous cycle,the associated heading (H in column 15) Output specifications willbe processed. Detail (D in column 15) Output specifications are thenprocessed. In the example, the sales for each salesperson will beoutput 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 breakindicator (L1 - L9) is turned on, and total time calculations and outputare processed. In the example, sales totals are accumulated by district,region, and grand total during the total time calculations. Duringtotal time output processing, the total time (T in column 15) Outputspecifications are processed and output if their associated control breakindicator 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 6123456789012345678901234567890123456789012345678901234567890123456789

FSALESFILIPE F8000 80 DISKFREPORT O F 80 PRINTER*ISALESFILAA 01I 01 04 REGIONL8I 05 08 DIST L7I 09 38 SALNAMI 39 44 SALEIDL6I P 45 492SALES

.

.

.C SALES ADD SALTOT SALTOT 92

.

.

.CL6 SALTOT ADD DISTOT DISTOT 92CL7 DISTOT ADD REGTOT REGTOT 92CL8 REGTOT ADD GRAND GRAND 102

.

.

.OREPORT H 1PO 35 ’SALES REPORT’O UDATE 80 ’ / / ’OREPORT H L8O 07 ’Region:’O REGION 12OREPORT H L7O 15 ’District:’O DIST 20OREPORT H L6O 20 ’Sales Person:’O SALNAM 50OREPORT D 01O SALES 50 ’$ , , . ’OREPORT T L6O 20 ’Total for Sales Person:’O SALNAM 51O SALEID 60O SALTOT B 80 ’$ , , . ’OREPORT T L7O 20 ’District Total’O DISTOT B 80 ’$ , , . ’OREPORT T L8O 20 ’Regional Total’O REGTOT B 80 ’$ , , . ’OREPORT T LRO 15 ’Grand Total’O GRAND B 80 ’$ , , . ’

1–19


1.4.3 The Last CycleThe last cycle is performed after all the records specified for processinghave been read from all primary and secondary files. When the last recordfrom the last file has been read, RPG sets on the LR indicator and all thecontrol break indicators (L1 through L9). It then performs the followingoperations:

• Total time calculations.

• Total time output.

• Outputs any tables or arrays that have output files associated withthem.

• 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 tothe calling program

• Ends program execution.

In example 1–3, the following steps take place during the last cycle. Inreferring back to the detailed logic cycle (figure 1–2), this description ofthe 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 tofinalize the accumulation of sales totals. This information will then beoutput during total time output. The grand total for all sales will alsobe output at this time, as its output specifications are qualified by theLR indicator.

• The data and report files are closed and normal program shutdownprocedures take place, terminating the program.

1–20

2 Migration RPG Program Specifications

Migration RPG is a column-oriented programming language. The columnpositions and their entries on each programming line determine what typeof specification is being used and what types of functions the program willperform.

The RPG programming language is broken up into 7 major specificationtypes. When compiled, each program specification tells the computer whatdata 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 programspecifications. It includes a description of the notation conventions forMigration RPG program specifications, data fields that are common to allspecifications, and special instructions to the RPG language compiler.

2.1 Column NumbersSince RPG is a column-oriented programming language, all instructionsused within the programming specifications must be placed in theappropriate columns. As indicated in Example 2–1, all RPG codingexamples in this manual are headed with a set of column numbers toassist 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 followingexample:

Example 2–1 Example of column numbers

1 2 3 4 51234567890123456789012345678901234567890123456789012345678

^

The arrow in the previous example points to column 43. The first line inthe column numbers contains the tens digits; the second line contains theunits digits.

2.2 Common FieldsThis section describes fields that are common to all specifications.

2.2.1 Line NumberColumns 1 - 5 are used in all RPG programming specifications for linenumbers or comments. Entries in these columns are optional and canbe useful in checking the sequence of lines or highlighting areas wherea program has been modified. The RPG compiler ignores all entries incolumns 1 - 5 until it sees a double asterisk (**) in columns 1 - 2. A **indicates the beginning of compile time array and table data. Compiletime array and table data must appear at the end of an RPG program.

Example 2–2 Line number usage

1 2 3 4 51234567890123456789012345678901234567890123456789012345678

*0056 IWORKSTN NS 99 1 C0057 I OR 01 1 C10058 I 2 41 NAMENEW I NS 04 1 C4NEW I 2 2 ANSWER0059 I NS 05 1 C5

.

.

.

2.2.2 Specification TypeColumn 6 is always used to identify the type of program specification beingused. Table 2–1 indicates the various specification types and the code usedin column 6 to represent them.

2–2


Table 2–1 Column 6 (RPG Specification Identification Codes)

AllowableEntries 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 CommentsIf an asterisk is placed in column 7 of a specification line, the entire linecan be used as a comment line. Comment lines do not require an entry incolumn 6.

Columns 75 - 80 can be used to write comments in all RPG programspecifications. The RPG compiler ignores entries in columns 75 - 80.Several of the RPG specifications allow comments to begin in columnspreceding column 75. See each specification section to determine wherecomments can begin.

Example 2–3 Comments in a program

1 2 3 4 5 6 712345678901234567890123456789012345678901234567890123456789012345678901234

*F* INDICATOR USAGEF*F* 01 SCREEN IDPT01 ACTIVEF* 02 SCREEN IDPT02 ACTIVEF* 10 HARDCOPY NOT COMPLETEF* 15 ON-KEEP SCANNING FOR QUESTION / OFF-QUESTION*FWORKSTN CP F 79 WORKSTNFDIFFHISTIC F 96 96R DISKFREPORT O F 132 132 OF PRINTER*E TABA 8 8 2 A CORRECT ANS TABLEE #ERR 1 2 41 ERROR MESSAGESE TST 50 50 1 CORRECT ANSWERSE ANS 50 1 USER ANSWERS

2.3 Compiler DirectivesCompiler directives can be included in an RPG source file to includeprogram modules into the main program at compile time or provide outputformat directives concerning the optional program listing the compilergenerates. Compiler directives are discussed in detail in the MigrationRPG User’s Guide.

2–3


All compiler directives begin with a slash (/) in column 7. Compilerdirectives can appear anywhere in an RPG program. Column 6 can beblank when a compiler directive is specified. The following compilerdirectives are recognized by Migration RPG:

• /COPY Directive

The /COPY directive is used to copy addition modules of RPG sourcecode into a program at compile time.

• /EJECT Directive

The /EJECT directive can be used to force form-feeds in a compilerlisting.

• /SPACE Directive

The /SPACE directive can be used to force blank lines in a compilerlisting. The number of blank lines to insert can be specified followingthe /SPACE directive.

• /TITLE Directive

The /TITLE directive can be used to force a programmer specifiedheading line to appear at the beginning of each page in a compilerlisting. Columns 14 - 74 can be used to insert the text which theprogrammer 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 programcharacteristics. If specified, the Control specification must be the firstcompilable statement in a program. A Control specification is identifiedby an H in column 6. The Control specification can be used to provide thefollowing 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 isprocessed by the compiler. Subsequent Control specifications are ignoredand 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 sequencingthe program specifications, or can be used as a comment. Columns 1 - 5are 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)


* Indicates that the line is a comment line. The line will be ignored bythe compiler.

/ Indicates that a compiler directive is to follow. Allowable compilerdirectives are /COPY, /EJECT, /SPACE, and /TITLE. Seethe Migration RPG User’s Guide for more information on the use ofcompiler directives.

3.4 Columns 7 - 10 (No-op)Columns 7 - 10 should be left blank if column 7 is not used to specify acomment or compiler directive.

3.5 Column 15 (DEBUG Option)

Table 3–2 Column 15 (DEBUG Option)


Blank The DEBUG option is turned off. Any DEBUG files and operationswithin the program are ignored by the compiler.

1 The DEBUG option is turned on. Any DEBUG files and operationswithin the program will be processed by the compiler. When theprogram is run, it will output DEBUG information. See section11.12.11 in Chapter 11, Operation Codes, for more information onthe DEBUG operation.

3–2


3.6 Columns 16 - 17 (No-op)Columns 16 - 17 are not used by the Control specification. They should beleft blank.

3.7 Column 18 (Currency Symbol)Use column 18 to specify a character other than the dollar sign ( $ ) torepresent the currency symbol.

Table 3–3 Column 18 (Currency Symbol)


Blank Uses the dollar sign ( $ ) as the currency symbol. The dollar sign isthe default.

Any othercharacter

The program will use this character, instead of the dollar sign ( $ ), asthe currency symbol. The character entered here must be coded inany fixed or floating edit word which is to use the currency symbol.Any character except the following can be used as a currencysymbol:

• 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 shouldexpect the date contained in the UDATE field. It is also used to indicatethe format in which the TIME operation code should return the systemdate.

Table 3–4 Column 19 (Date Format Code)


Blank The default format of MM/DD/YYYY is to be used for UDATE and thesystem date. If column 19 is blank and column 21 contains a D, I, orJ, 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 formatand the appropriate entry has not been made in column 19, the programwill work with the wrong date. For example, if the date 1999/02/15, whichis in YYYY/MM/DD format, is entered in the UDATE field via the REXUtility, but the program accessing the date was not compiled with a Yin 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 theyear columns. This will no doubt confuse the end users.

The same problem can occur when using the TIME operation code toobtain the system date. By default, this date is returned in MM/DD/YYYYformat. If the programmer is expecting to work with a date in a differentformat, 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 editoperation carried out on an output field with a Y edit code specified incolumn 38. The Y edit code is used to specify the type of edit carried outon a date field. The default edit uses the slash (/) as a separator in thefollowing format: nn/nn/nnnn.

Table 3–5 Column 20 (Date Edit Code)


Blank A slash (/) is used as the date field separator when column 19contains a blank or M and column 21 contains blank or D. A period(.) is assumed when column 19 contains a blank, D, or Y, andcolumn 21 contains an I or J.

& A blank is used as the date field separator.

Any othercharacter

The character entered serves as the date field separator.

Note: The format of the reserved word $UDATE, which supplies the datein a 6-digit non-Year 2000 compliant form, is also determined bythe entries in columns 19 and 20. See the Migration RPG Year 2000Compliance Guide for more information concerning the $UDATEfield.

3.10 Column 21 (Inverted Print Code)The Inverted Print Code specifies the constants to be used in numeric editcodes in the Output specifications. The Inverted Print Code allows outputto conform with a variety of notation conventions. For example, using theUnited States decimal period convention for expressing a number witha comma denoting thousands and a period denoting decimals, numericoutput would be edited as 12,345.67; the same value could be correctlyexpressed as 12.345,67 using a decimal comma notation. Use column 21to specify the notation convention used for numeric fields, edit codes, andUDATE.

3–4


Table 3–6 Column 21 (Inverted Print Code)


Blank Uses a period as the decimal notation and a comma as thethousands separator in numeric literals and edit codes (for example,1,234.56 and .56). Uses a slash ( / ) as the separator for the Y editcode if columns 19 and 20 are blank (example, 02/16/92). Uses theMMDDYYYY format for UDATE if column 19 is blank.

D This code produces the same results as the blank entry except thatthe DDMMYYYY format is used for UDATE if column 19 is blank.

I Uses a comma as the decimal notation and a period as thethousands separator in numeric literals and edit codes (for example,1.234,56). Uses the DDMMYYYY format for UDATE if column 19is blank. If columns 19 and 20 are blank, the period is used as theseparator 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 leftof 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 beleft blank.

3.12 Column 26 (Alternate Collating Sequence)Use column 26 to specify the collating sequence RPG will use foralphameric comparisons, sequence checking, and matching fields. SeeChapter 17, "Specifying An Alternate Collating Sequence Or A TranslationFile", for more information on creating user-defined collating sequences.

Table 3–7 Column 26 (Alternate Collating Sequence)


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 EBCDICcharacter sets.


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, SpecifyingAn Alternate Collating Sequence Or A Translation File, for information ontranslating data files.

Table 3–8 Column 43 (File Translation Code)


Blank No file translation is needed.

F Input, update, combined, or output files are to be translated.


3.16 Column 60 (Zoned-decimal output)Placing a Z in column 60 forces all standard numeric output (non-packedand non-binary) to be zoned-decimal rather than trailing numeric. Placinga Z in column 60 has the same results as placing a Z in column 44 of everynon-editted standard numeric output field.

Table 3–9 Column 60 (Zoned-decimal output)


Blank Standard numeric field output is trailing numeric.

Z Standard numeric field output is zoned-decimal.


3.18 Columns 75 - 80 (Comments)Columns 75 - 80 can be used for comments. The compiler will ignore anyentry in these columns.

3–6

4 File Description Specification (F)

The File Description specification is used to describe the files accessed byan RPG program. It describes the following attributes for each file used ina 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)


4.2 Column 6 (Specification Identification)Column 6 must always contain an F to identify a File Descriptionspecification. Note that File Description specification continuation linescontain blanks in columns 7 - 52.






4.4 Columns 7 - 14 (File Name)Columns 7 - 14 are used to identify a file which will be accessed by theRPG 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 columns7 - 14. This permits the actual file designation to be much longer than 8characters. See the Migration RPG User’s Guide for more information onspecifying logical file names for RPG programs.

Migration RPG allows a maximum of 98 files to be open in a singleprogram. The number of files a user can open depends on the open filequota set in the user’s UAF 1 record by the system manager. To determinethe number of files a user can have open at any one time, review thefile quota entry in the UAF file or enter the SHOW PROCESS/QUOTAcommand from the user’s process and look at the number to the right ofOpen File Quota. The default file quota on most OpenVMS systems is 15open 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 bedesignated for input, output, input and output (combined), or update.

Table 4–2 Column 15 (File Type)


I Designates an input file. The program reads records from an inputfile. These records must be defined in Input specifications unlesscolumn 16 contains an R or T.

O Designates an output file. The program writes records to an outputfile. These records must be defined in Output specifications unlessthis is a table output file. If the output file does not exist, it will becreated by the program.

U Designates an update file. An update file serves as both an inputand an output file. The program can read a record, modify fieldsin the record, and then write the record back to the same place inthe file. The records in these files must be defined in the Input andOutput specifications. The input and output records in an update filewill always contain the same fields.

If the update file does not exist and it is add capable (A in column66 of the File Description specification), it will be created by theprogram.

C Designates a combined input/output file. A combined file serves asboth an input and output file for a WORKSTN or SPECIAL device file.Unlike an update file, the input and output records in a combined filedo not always contain the same fields. The input record will containthe fields defined in the Input specifications, while the output recordcontains the fields defined in the Output specifications.

Table 4–3 shows the device types and file types which can be associatedtogether:

4–3


Table 4–3 Device Types and File Types

Device TypeColumns 40 -46

File TypeColumn 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 anRPG program. Column 16 should be blank for all output files exceptchained output files.

Table 4–4 Column 16 (File Designation)


Blank Specifies a non-chained output file.

P Specifies a primary file. Only one file can be designated as theprimary file. It can be an input, update, or combined file and can useany device except CRT, PRINT, or PRINTER. In multi-file processing,the primary file determines the order of record selection; in single fileprocessing, the primary file provides all input records. If a primary fileis not specified and one or more secondary files are specified, thefirst secondary file is assigned as the primary file. If no primary orsecondary files are specified, the programmer must initiate last cycleprocessing by manually setting on the last record (LR) indicator.

4–4


Table 4–4 (Cont.) Column 16 (File Designation)


S Specifies a secondary file. Secondary files are only used inprograms which use multi-file processing. See Chapter 13, UsingDISK Files, for more information on record selection for multi-fileprocessing.

A secondary file can be an input, update, or combined file. Itcan use the DISK or SPECIAL device types. Secondary filesare processed in the order in which they are coded in the FileDescription specifications. If no primary file has been declared andsecondary files are present, the first secondary file encounteredwill be designated the primary file by the compiler. If a WORKSTNdevice is designated the primary file, no secondary files can bespecified in the program.

C Specifies a chained file. A chained file resides on disk and can beused as an input, output, or update file. The CHAIN operation codein the Calculation specifications is used to randomly read records bykey or relative record number from a chained file. An output chainedfile can be used to add records to a relative file. A chained filecan only use the DISK device. See Chapter 11, Operation Codes,Section 11.12.9, - CHAIN Operation, for more information on theCHAIN operation.

F Specifies a full-procedural file. A full-procedural file can be an inputor 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 Calculationspecifications. See Chapter 11, Operation Codes, Sections 11.12.9,11.12.42, 11.12.43, and 11.12.44, for more information on accessingrecords 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 theCalculation specifications to sequentially access records in ademand file. See Chapter 11, Operation Codes, Sections 11.12.42and 11.12.28, for more information on using the READ and KEYnnoperation codes to access records from demand files.

4–5


Table 4–4 (Cont.) Column 16 (File Designation)


R Specifies a record-address file. A record address file contains eitherkey-field limits or record addresses for a DISK file. The programuses the information from the record-address file to determine whichrecords from the associated data file to process and the order inwhich they are to be processed. The record-address file must beassociated with a data file defined in an Extension specification. SeeChapter 13, Using DISK Files, for information on record-addressfiles.

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 containsrecord addresses, it can be associated to an indexed, relative, orsequential file. Record-address files which contain record addressinformation are produced by the OpenVMS SORT Utility using theSORT/PROCESS=ADDRESS command. Record address sortsare often referred to as addrout sorts and the address files theyproduce are referred to as addrout files.

T Specifies a pre-execution-time table or array. Columns 11 - 18 ofthe Extension specification must contain the name of the file thatcontains the data from which the table or array data will be loaded.Array or table files must be sequential disk files. Pre-execution-timetable and array files are loaded by a program during the first cyclebefore the normal cycle begins. See Chapter 15, Using Tables andArrays, 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 filehave been processed. Column 17 applies to primary and secondary filesonly.

Table 4–5 Column 17 (End-of-File)


Blank The program can end without processing all records in this file.However, if column 17 is blank for all primary and secondary files, allrecords in all files must be processed before the program can end.Column 17 must be blank for WORKSTN and KEYBORD devicefiles.

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 processedby a record-address file.

When matching fields are in use and an E is specified in column 17 forthe primary file and if there are matching records in the primary andsecondary files, the program reads and processes any records in thesecondary file that match the last record of the primary file before ending.

4–6


In programs which designate a WORKSTN or KEYBORD device as theprimary file, an E in column 17 is not valid. The programmer must set thelast record indicator (LR) on in the Calculation specifications to end thistype of program.

4.8 Column 18 (Sequence Code)Use column 18 to specify ascending or descending sequence to checkmatching fields. See Chapter 13, Using DISK Files, for information onmatching fields.

Table 4–6 Column 18 (Sequence Code)


Blank Indicates that the program contains no matching fields or, if itdoes, assumes the same value as specified for a previous primaryor secondary file. If the program contains matching fields and asequence 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 withmatching fields.

The sequence code must be the same for each file processed with matchingfields.

The sequence code can be used with input, update, or combined files. Itis only valid with DISK files. Columns 61 and 62 are used to identify thematching fields in the Input specifications.

Sequence checking is required when matching fields are used in aprogram. If a record is found out of sequence, the program will halt andthe 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 specifieswhether the records in the file are all the same length or whether they canbe different lengths. Most RPG programs use fixed-length files.

Table 4–7 Column 19 (File Format)


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 datafile. The block length must be a multiple of the record length specified incolumns 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 allmultiples 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 maintaincompatibility with non-OpenVMS versions of the RPG programminglanguage.

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 fileor the longest record in a variable-length file. Record length entries mustbe right-justified and numeric. Leading zeros are optional.

Table 4–8 Columns 24 - 27 (Record Length)


1-9999 Specifies the number of characters in each record in a fixed-lengthfile or the maximum record size of a variable-length file.

If the record length is left blank on a terminal or printer device filedefinition, a default length of 140 will be assumed. Leaving the recordlength 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 fileproduced by the OpenVMS SORT Utility contains records 6 characters inlength. 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 programstransferred to an OpenVMS system from an IBM System/3, System/34, orSystem/36.

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

4–8


Table 4–9 Column 28 (Processing Mode)


Blank Accesses records sequentially or accesses records sequentially bykey.

L Accesses records sequentially within limits.

R Accesses records randomly using a relative record number or anindex key, or using an addrout file, or tells the program to load adirect file.

Sequential processing of a sequential file reads the records in the order inwhich they were written. Sequential-by-key processing reads records fromindexed files that are used as primary, secondary, or demand files. Therecords are read in the order specified by the key field associated to theFile Description specification. Sequential-within-limits processing readsrecords in one of two ways:

• Specifying a range of records to be read.

• Using the SETLL operation code in the Calculation specification to setthe lowest key for the records in a demand file. The program readsrecords with keys equal to or higher than the key specified.

Random processing reads records from chained files in one of the followingtwo ways:

• For sequential or direct files, records are accessed by their relativerecord number. A relative record number identifies the position of arecord 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 theOpenVMS SORT Utility. The addrout file contains binary record numbersthat correspond to the addresses of records; therefore, the records to beread are located by their addresses.

The entries listed in Table 4–10 are valid for sequential files that reside ondisk.

4–9


Table 4–10 Modes of Processing for Sequential Files

Type ofProcessing

AccessMode Allowable Entries

Column:

15 16 28 31 32 66

Sequential Sequential IIIIUUU

PSTDPSD

Random Using CHAIN IIUU

CCCC

RRRR

IIII

A

A

Random Using Addrout IIIUUU

PSFPSF

RR

RR

II

II

Sequentialand/orRandom

Using READ,READP, and/or CHAIN

IIUU

FFFF

A

A

Create Output Add OO A

4–10


The entries listed in Table 4–11 are valid for relative files that reside ondisk.

Table 4–11 Modes of Processing for Relative Files

Type ofProcessing


Column:

15 16 28 31 32 66

Sequential Sequential IIIUUU

PSDPSD

Random Using CHAIN IIUU

CCCC

RRRR

A

A

Random Using Addrout IIIUUU

PSFPSF

RR

RR

II

II


Using READ,READP, and/or CHAIN

IIUU

FFFF

A

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

Table 4–12 Modes of Processing for Indexed Files

Type ofProcessing


Column:

15 16 28 31 32 66

Sequential By Key, NoAdd

IIIUUU

PSDPSD

IIIIII

Sequential By Key, Add IIIUUU

PSDPSD

IIIIII

AAAAAA

Sequential By Limits IIIIUUUU

PSDFPSDF

LLLLLLLL

IIIIIIII

Sequential By Limits,With Add

IU

FF

LL

II

AA

Random By Chain,No Add

IU

CC

RR

II

Random By Chain,With Add

IU

CC

RR

II

AA

Random By Addrout IIUU

PSPS

RRRR

IIII

IIII


By Key,No Add

IU

FF

II


By Key,With Add

IU

FF

II

AA

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 ofProcessing


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 ofProcessing


Column:

15 16 28 31 32 66

- Input/Output CC

PD

The entries listed in Table 4–15 are valid for record address files. Recordaddress files can be associated with sequential, relative, or indexed filesthat reside on disk. Record address files containing key field limits canonly be associated with indexed files.

Table 4–15 Modes of Processing for Record Address Files

Type ofProcessing


Column:

15 16 28 31 32 66

- Input II

RR

I T

4–13


The entries listed in Table 4–16 are valid for KEYBORD files.

Table 4–16 Modes of Processing for KEYBORD Files

Type ofProcessing


Column:

15 16 28 31 32 66

- Input II

PD

The entries listed in Table 4–17 are valid for SPECIAL device files.

Table 4–17 Modes of Processing for SPECIAL Files

Type ofProcessing


Column:

15 16 28 31 32 66

- Input IIII

PSD

- Input/Output UC

- Output O

4–14


4.13 Columns 29 - 30 (Key Length)Columns 29 and 30 specify key length. Key length indicates the length inbytes 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)


Blank Indicates a sequential, relative, or display file.

1-99 Specifies the total length of the record key for an indexed file or arecord-address (addrout) file.

The record length for an addrout file can be either 3 or 6. An addrout fileproduced by the OpenVMS SORT Utility contains records 6 characters inlength. 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 programstransferred to an OpenVMS system from an IBM System/3, System/34, orSystem/36.

The entry must be numeric and right-justified. Leading zeros can beomitted.

Packed-decimal key fields can have a maximum length of 8. Whenspecifying the length of a packed-decimal key, use the packed length ofthe field.

4.14 Column 31 (Record Address Type)Column 31 specifies the record address type. The record address typehelps define the mode of processing.

Table 4–19 Column 31 (Record Address Type)


Blank Uses relative record numbers to process sequential and directchained files, or reads records sequentially from an input or updatefile, or creates or adds records to a sequential output file.

A Processes or loads indexed files according to the record keys inalphameric format.

P Processes or loads indexed files according to record keys in packedformat.

I Processes the file according to an addrout file or identifies an addroutfile.

4–15


The following tables depict the valid combinations of entries in theprocessing mode column (28) and the record address type column (31).

Table 4–20 Valid Combinations of Entries in Columns 28 and 31 forPrimary, Secondary, and Demand Files

Method of ProcessingProcessing ModeColumn 28

Record Address TypeColumn 31

Sequential Blank Blank

By Address(except demandfiles)

R I

Sequential by key Blank A/P

Sequential withinlimits

L A/P

Table 4–21 Valid Combinations of Entries in Columns 28 and 31 forChained Files



Random by relativerecord number

R Blank

Random by key R A/P

Table 4–22 Valid Combinations of Entries in Columns 28 and 31 forFull-Procedural Files



Sequential Blank Blank

By Address Blank Blank

Sequential by key Blank A/P

Sequential withinlimits

L A/P

Random by relativerecord number

Blank Blank

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. Thisattribute works in conjunction with the mode of processing (column28). See Section 4.12 for valid combinations of processing mode andfile organization entries.

4–16


Table 4–23 Column 32 (File Organization)


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 orPRINTER file. An overflow indicator is used to specify output actions ina print file when overflow occurs. See Chapter 14, Using Printer OutputFiles, for more information on overflow indicators.

Table 4–24 Columns 33 - 34 (Overflow Indicator)


Blank Specifies no overflow indicator.

OA-OG, OV Specifies an overflow indicator to condition output lines whenoverflow occurs.

Overflow indicators can only be specified on PRINT or PRINTER outputFile 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 isto be used on each file, a unique overflow indicator must be specified foreach 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 withina file. Each record in an indexed file has a key field that RMS uses tolocate records. This key field can be anywhere in the record, but mustbe in the same location for each record in the file. The key start locationspecifies where to find the key field in the record. This entry can be usedin conjunction with the alternate index entry (columns 68 - 69) to specifyan alternate index for a file.

4–17


Table 4–25 Columns 35 - 38 (Key Start Location)


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

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 (columns68 - 69) entries are used in conjunction with this entry to define the keyfield which should be referenced by the program.

A word of caution: When using an FDL file definition to locate thebeginning of a key field, be aware that the FDL definition specifies thislocation as an offset from 0. When specifying the key start location inthe RPG program, do not specify it as an offset. For example, if an FDLdefinition indicates that a key field starts in offset 9, the key start locationentry in the RPG File Description specification would contain a 10.

If a program opens an indexed file and cannot match the key definition inthe File Description specification with a key in the file, the program willabort with an RMS error.

4.18 Column 39 (Extension Code)Column 39 is used to specify an extension code which indicates that the fileis further defined in an Extension or Line Counter specification. Extensionspecifications are used to define tables, arrays, and record-address files.Line Counter specifications are used to define form characteristics forPRINT or PRINTER files.

Table 4–26 Column 39 (Extension Code)


Blank No Extension or Line Counter specification is associated with thisfile.

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 typeof device the file is stored. Migration RPG is designed to make portingnon-OpenVMS RPG II applications to an OpenVMS system as easy as

4–18


possible. For this reason, Migration RPG supports a wide range of devicetypes.

The following table specifies the standard device types used in MigrationRPG. Given the ability to associate File Description specifications logicallyto devices on an OpenVMS system, these device types are sufficient formost RPG applications.

Table 4–27 Columns 40 - 46 (Device Code - Standard Migration RPGDevice Types)


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 orPRINTER

An output only file used to produce reports. Printer files can bewritten to disk or associated directly to a print device. On OpenVMSsystems, print files are usually written to disk and then submitted toa print queue using the DCL PRINT command.

SPECIAL The SPECIAL device file is used to provide an interface to RPGprograms for non-standard devices and utilities. The SPECIALdevice file interfaces with a user-supplied external routine. SeeChapter 18, Using a SPECIAL Device File, for more information onusing the SPECIAL device file.

WORKSTN An input/output device used to communicate with a terminal orworkstation. Workstation screens are defined by Screen, Help,and Field Definition specifications in a Screen Format file. Thescreen format file is linked with the RPG program. See the MigrationRPG Screen Format Reference Manual for more information ondeveloping workstation screens.

The following device types are supported by Migration RPG to makeporting RPG II applications to an OpenVMS system as easy as possible.

Table 4–28 Columns 40 - 46 (Device Code - Supported Migration RPGDevice Types)


CONSOLE Input/output device which communicates with display stations.

CRT Output device associated to the logical SYS$OUTPUT. A CRT devicecan be used to output to a terminal or workstation.

KEYBORD Input/output device used to accept and display information from aterminal or workstation using the SETnn and KEYnn operationcodes in the Calculation specifications.

DISCDBDISKDISK40DKDISKDPDISKDMDISK

Input/output devices associated to a disk device.

4–19


Table 4–28 (Cont.) Columns 40 - 46 (Device Code - Supported MigrationRPG Device Types)


DECTAPTAPE

Input device associated to a tape drive. Tape files can only beprocessed as sequential input files.

PRINTR Output device used to define a report file.

READERREAD40

Input device associated to a card reader. Card reader files can onlybe processed as sequential input files.

TTY Input device associated to the logical SYS$INPUT. A TTY device canbe 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. Theyshould be left blank. Some versions of RPG use columns 47 - 52 to specifya symbolic device. If an entry is found in columns 47 - 52, the MigrationRPG 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 theprevious File Description specification. Continuation lines are optionaland can be associated to DISK, WORKSTN, and SPECIAL device files.

Continuation lines are made up of File Description specifications withblanks in columns 7 - 52 and a K in column 53. They must immediatelyfollow the file with which they are associated. Section 4.23 defines theoptions which can be specified on a continuation line.

Table 4–29 Column 53 (Continuation Lines)


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 externalroutine associated to a SPECIAL device file if SPECIAL is coded incolumns 40 - 46. The external routine name can be 1 - 12 characters inlength and must begin with an alpha character. The external routine mustbe linked to the RPG program.

4–20


Columns 54 - 65 can also be used to identify the MSI supplied SPECIALdevice routine SUBR01. The SUBR01 routine opens a channel to thelogical SYS$INPUT and can be used to input records embedded in acommand procedure. SUBR01 support is provided as a compatibilityfeature 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 acontinuation line. These options are defined in the following subsections.Columns 60 - 65 are used to specify the entries which are associated tothe continuation option. These entries are also described in the followingsubsections.

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 FileA DISK file can have one continuation line associated to it. It can beused to specify a record number field which can be used to add recordsto a sequential or relative file. The continuation is not required to addrecords to sequential and relative file. It is supported to aid the porting ofnon-OpenVMS versions of RPG to an OpenVMS system.

Table 4–30 DISK File Continuation Option

OptionColumns 54 - 59

EntryColumns 60 - 65

RECNO Name of a 6 digit, 0 decimal numeric field. The field must bedefined somewhere in the program.

When a record is input from a sequential or relative file, itsrecord number is placed in this field. When outputting arecord, place the relative record number in this field beforethe record is output.

When outputting records using the RECNO option, the recordposition must exist in the file in order for the write operationto complete successfully. Sequential and relative files usingthe RECNO continuation should be created in advance andpopulated with blank records.

4.23.2 Rules for Specifying a Continuation Line on a SPECIAL Device FileA SPECIAL device file can have one continuation line associated to it. Itis used to specify an array defined in the Extension specifications whichcan be passed to the SPECIAL device file routine.

4–21


Table 4–31 SPECIAL Device File Continuation Option

EntryExplanation

ArrayName

The name of an array defined in the Extension specificationswhich will be used to pass information back and forthbetween a SPECIAL device routine.

4.23.3 Rules for Specifying a Continuation Line on a WORKSTN Device FileA workstation device file can have 1 to 8 continuation lines associatedwith it. These specifications are used to pass information between an RPGprogram and a workstation screen and to specify the INFDS exceptionhandling routine.

4–22


Table 4–32 WORKSTN File Continuation Options

OptionColumns 54 - 59

EntryColumns 60 - 65

FMTS Specifies the name of the screen format file containing thescreens used by the program. The entry can be up to 8characters long, running from columns 60 - 67. This entryis ignored by the Migration RPG compiler and is supportedfor compatibility purposes with non-OpenVMS versions ofthe RPG programming language. However, the BUILDprocedure provided with the Migration RPG Compiler Kitcompiler will process the FMTS continuation line. See thedescription of the BUILD procedure in the Migration RPGUser’s Guide for more information on the BUILD procedure.

ID A two-character, alphameric field identifying the terminal orworkstation from which the program is running. See theMigration RPG User’s Guide for information on establishingand changing workstation ID’s.

IND This function has no meaning under Migration RPG. It issupported for compatibility purposes with non-OpenVMSversions of the RPG programming language. The MigrationRPG compiler will ignore IND continuation lines.

INFDS The name of a data structure which will receive informationfrom a workstation screen concerning its return status andany exceptions processed. The data structure must bedefined in the Input specifications.

INFSR Name of the exception handling subroutine. This subroutinemust be defined in the Calculation specifications. TheINFSR subroutine is called if an exception occurs duringa workstation read and no other error trapping has beenspecified for the read.

NUM This function has no meaning under Migration RPG. It issupported for compatibility purposes with non-OpenVMSversions of the RPG programming language. The MigrationRPG compiler will ignore NUM continuation lines.

SAVDS This function has no meaning under Migration RPG. It issupported for compatibility purposes with non-OpenVMSversions of the RPG programming language. The MigrationRPG compiler will ignore SAVDS continuation lines.

SLN A 2 digit, 0 decimal numeric field which is passed to thescreen format file. The SLN field defines the starting linefor a variable start line screen (V coded in column 17 ofthe Screen specification). The field must be defined withinthe RPG program. See the Migration RPG Screen FormatReference Manual for information on creating a variable startline 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 whichallow 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 bespecified in columns 16 - 18 of an Output specification in order toadd records to a file.

U Records can be added to the file. The entry ADD must also bespecified in columns 16 - 18 of an Output specification in order toadd records to a file. The U entry is supported to aid porting ofnon-OpenVMS RPG applications to Migration RPG.

If an update file (U in column 15) is declared add capable by entering an Aor U in column 66, and the file does not exist when the program attemptsto 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 leftblank.

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 primarykey. See the Migration RPG User’s Guide for more information concerningthe 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 anFDL file description.

00 - 99 Specifies the key by which the file is to be accessed. Remember thatthe key fields are numbered as an offset from 0; thus, the primary keyis Key 0, the first alternate key is Key 1, the second alternate key isKey 2, and so on. An alternate key designation must be numeric andright-justified.

4–24


4.27 Column 70 (No-op)Column 70 is not used in a File Description specification. It should be leftblank.

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 theprogram 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 indicatoris on, the file is processed normally. If the indicator is off, the fileis set to an end-of-file condition and ignored by the program. If theconditioning 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 evaluatedand access is granted or denied to the associated file. If the externalindicator is later set on within the program, it has no effect on fileaccess. The only exception to this rule is if the program in question isan RPG subprogram. It would be possible to modify external indicatorsettings within a subprogram, exit the subprogram, then initialize and callthe subprogram again. The subprogram would re-evaluate the updatedexternal indicators and access its files accordingly.

If a file is conditioned by an external indicator, all associated operationswithin the Calculation specifications should also be conditioned by thesame indicator.

4.29 Column 73 (File Sharing)Column 73 can be used to define the type of shared access that will beallowed to a file that is opened by the program. File sharing is defined astwo or more file streams accessing the same data file at the same time. Bydefault, RPG programs under OpenVMS allow file access according to thestandard file sharing rules of RMS.

4–25


Table 4–36 Column 73 (File Sharing)

Entry Explanation

Blankor S

RMS default access rules will be used to grant read/write/deleteaccess to the file.

N No shared access. The file will be open exclusively by this filestream and will not be accessible to any other open/read/writerequest from any other source.

R Read only access. The file stream controlling the file will allow otherfile streams read access to the file.

A file with an ‘N’ in column 73 of the File Description specification willnot 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, butwill not allow records to be read for update or deletion from the file. Afile with an ‘S’ or blank in column 73 allows other programs full access tothe data file, as long as this access does not conflict with the default RMSrestrictions on the file.

When using the file sharing code in column 73, it is important to realizethat the share code specified for one file stream affects all other filestreams that attempt to access the file, even if the file streams areassociated with the same program. Therefore, if file share codes areused incorrectly, it is possible for a program to deny itself access to a fileby having two conflicting file share qualifiers set up on two file streamsaccessing 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 thedata file GOODSTUFF.DAT. Under default conditions, this operationwould present no problems. However, if in the program the file GREEDYhas a share code of ‘N’, the program will be unable to connect a secondstream to the data file and will abort when it tries to connect the streamfor OUTCST.

4.30 Column 74 (No Deferred Write)Column 74 can be used to turn off the deferred write capabilities ofMigration RPG. By default, all RPG programs use deferred write whenoutputting or updating a data file. This feature is used to help improveprogram performance and decrease disk I/O. RMS global buffering takescare 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 whenthe internal output buffers are filled.

N The program will not use deferred write. Records are output as soonas a write operation is executed.

Using deferred write allows a program to reduce disk I/O operations byoutputting several records in a single write operation. Records which areoutput by the RPG program are stored in an RMS buffer until the bufferfills. RMS then writes all of the records to disk in one operation. RMSbuffering can be modified using the DCL command SET RMS_DEFAULT.

Not using deferred writing will degrade program and system performanceand increase disk I/O. The ability to disable deferred writes within RPGhas been added to assist users that are running programs such as WatchDog, which terminate processes using a STOP PROCESS/ID, preventingany existing record buffers from being written to disk. MSI does notrecommend or support the use of any utilities or services that terminateprocesses without performing normal image shutdown operations such asflushing file buffers and closing open files.

4.31 Columns 75 - 80 (Comments)Columns 75 - 80 can be used for comments. The compiler will ignore anyentries 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 informationabout 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 columns36 - 45. An alternate table or array must be defined on the same line incolumns 46 - 57.

A record-address file requires entries in columns 11 - 26. These entriesprovide the following information:

• Name of the record-address file

• Name of the data file associated with the record-address file


5.2 Column 6 (Specification Identification)Column 6 must always contain an E to identify an Extension specification.

5–1

Extension Specification (E)






5.4 Columns 7 - 10 (No-op)Columns 7 - 10 should be left blank if column 7 is not used to specify acomment or compiler directive.

5.5 Columns 11 - 18 (From-File Name)Columns 11 - 18 can be used to specify the from-file name that identifiesthe 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)


Blank Loads the table or array named in columns 27 - 32 (table orarray name) at compile time if columns 33 - 35 (entries perrecord) are completed.

Loads the array at execution time if the array is specifiedby the Input and/or Calculation specification and if columns33 - 35 are left blank.

Record AddressFile Name

Name of a record-address file.

Table or ArrayFile Name

Name of the table or array input file. The contents of this filewill be loaded to the associated table or array during programinitialization.

If a file name is specified, it must also be defined in the File Descriptionspecifications. 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 RPGprogram, following the last Output specification in the program. Each setof table or array records is separated by a pair of asterisks (**) in columns1 - 2.

5–2


The following example displays compile time table and array Extensionspecifications and the associated data coded at the end of the program.

Example 5–1 compile time Table and Array Coding

1 2 3 41234567890123456789012345678901234567890123456

E*E TABCST 3 9 4 2E ARYDB 4 8 2

.

.

.O*

** Data for TABCST compile time table.134592830587283758471047574837263746** Data for ARYDB compile time array.SASBSCSDTHATBTCTD

5.6 Columns 19 - 26 (To-File Name)Columns 19 - 26 can be used to identify an input or update file associatedto the record address file specified in columns 11 - 18 (from-file name) or tospecify an output file for a table or array.

Table 5–3 Columns 19 - 26 (To-File Name)


Blank The Extension specification describes a table or array andthe table or array is not written to a file at the end of theprogram.

Input or UpdateFile Name

Identifies the data file associated with the record-address filenamed in columns 11 - 18.

Output FileName

The output file that receives the data from the table or arrayat the end of the program.

If a file name is specified, it must be also be specified in the FileDescription specifications. The entry must be left-justified.

Array and table data is output after the last-record indicator (LR) comeson and all other output processing has been completed.

If a record address file is being used, entries must be made in bothcolumns 11 - 18 and 19 - 26. The from-file name (11 - 18) must containthe record address file name; the to-file name (19 - 26) must contain thename 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)


Blank Indicates that the file named in columns 11 - 18 (from-file name) is arecord-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 beginwith an alpha character. Each array and table name must be unique. Theentry must be left-justified.

This entry describes the name of the main table or array. An alternatetable 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 specifyingthe array name. Individual entries in the array can be referred to byassociating an index to the array name.

When a program is initialized, the first element in the table is placed inthe table storage area. When the table name is specified in the Calculationspecifications, it refers to the element in the table storage area. Theexception to this is when the table name is specified in a LOKUPoperation. See Section 11.12.29, - LOKUP Operation in Chapter 11,Operation Codes, for more information on using table names in LOKUPoperations.

Tables and arrays are processed in the order they are specified in theExtension specifications.

See Chapter 15, Using Tables and Arrays, for additional information onspecifying 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 tableor array input record. Complete this entry for compile time and pre-execution-time tables and arrays. If an entry is not present in thesecolumns for an array definition, the array is an execution-time array and isnot preloaded with data at compile time or during program initialization.

Table 5–5 Column 33 - 35 (Number of Entries Per Record)


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

The following rules apply to the records which contain the data used incompile 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 ofentries that is not an even multiple of the defined number of entriesin the record. If a compile time array or table does not contain enoughentries, 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, eachrecord must contain a corresponding entry. The entries from the maintable or array and the corresponding entries from an alternate table orarray are treated as one entry.

The following rules apply to the from-file name (columns 11 - 18) andnumber of entries in a record (columns 33 - 35) when an array name isspecified in columns 27 - 32.

• An execution-time array requires that columns 11 - 18 and 33 - 35 beblank.

• 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 columns11 - 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 orarray and in an alternate table or array, if an alternate table or array isbeing defined.

Table 5–6 Columns 36 - 39 (Number of Entries in a Table or Array)



1-9999 Specifies the number of entries in a table or array.

The entry must be numeric and right-justified. Leading zeros can beomitted.

If a compile time or pre-execution-time table or array is not completelyfull, the unused entries are filled with blanks for alphameric data andzeros for numeric data.

5–5


If a compile time array is not full, the RPG compiler will issue a warningmessage 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 tabledefined in columns 27 - 32.

Table 5–7 Columns 40 - 42 (Length of Entry - Primary Entry)



1-999 Specifies the number of character positions (both alphameric andnumeric) 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-positionbinary field and 9 for a 4-position binary field.

The largest record size which can be specified in a compile time table is100 characters. This is the largest record that will be processed by theRPG compiler.

This entry specifies the length of the entry in the primary table or arrayfor alternating table and array definitions.

All entries in a table or array must be the same length. When creatingthe entries for compile time and pre-execution-time tables and arrays, padalphameric 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 oneof the following three formats:

• numeric/alphameric

• Packed-decimal

• Binary

5–6


Table 5–8 Column 43 (Data Format - Primary Entry)


Blank Specifies that numeric data is in zoned-decimal or trailing numericformat or that the table or array contains alphameric data.

P Specifies that numeric data is in packed-decimal format. This formatis valid only for pre-execution-time tables or arrays.

B Specifies that numeric data is in binary format. This format is validonly 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 decimalpoint for numeric data in a table or array.

Table 5–9 Column 44 (Decimal Positions - Primary Entry)


Blank The table or array contains alphameric data.

0-9 Specifies the number of positions to the right of the decimal point fornumeric 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 thefirst 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 primarytable or array.

Table 5–10 Column 45 (Sequence - Primary Entry)


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

D Specifies that the entries in a table or array are in descending order,sorted from highest to lowest according to the specified collatingsequence.

Consecutive entries that are equal in value are considered to be insequence.

5–7


When using tables or arrays in alternating format, this entry specifies thesequence of the primary table or array.

When a sequence is specified for a compile time table or array, thesequence is checked by the RPG compiler. If the table or array is notsorted in the specified sequence, the compiler issues a fatal compile timeerror.

If a pre-execution-time table or array is out of sequence, the program haltsand prompts the user to ignore the error and continue, or terminate theprogram.

5.14 Columns 46 - 51 (Array or Table Name - Alternate Entry)Columns 46 - 51 are used to identify an alternate table or array. Alternatetables and arrays are optional. They have the same number of elementsas the primary table or array. Array and table definitions cannot be mixedon the same Extension specification.

Table 5–11 Columns 46 - 51 (Array or Table Name - Alternate Entry)


Blank No alternate table or array is being specified, or this Extensionspecification 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 beginwith an alpha character. Each array and table name must be unique. Theentry must be left-justified.

Table names must begin with TAB.

An entire array can be referred to throughout the program by specifyingthe array name. Individual entries in the array can be referred to byassociating an index to the array name.

When a program is initialized, the first element in a table is placedin the table storage area. When the table name is specified in theCalculation specifications, it refers to the element in the table storagearea. The exception to this is when the table name is specified in aLOKUP 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 inthe Extension specifications.

See Chapter 15, "Using Tables and Arrays", for additional information onspecifying 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 ortable defined in columns 46 - 51.

Table 5–12 Columns 52 - 54 (Length of Entry - Alternate Entry)


1-999 Specifies the number of character positions (both alphameric andnumeric) 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-positionbinary field and 9 for a 4-position binary field.

The largest record size which can be specified in a compile time table is100 characters. This is the largest record that will be processed by theRPG compiler.

This entry specifies the length of the entry in the alternate table or arrayfor alternating tables and arrays.

All entries in a table or array must be the same length. When creatingthe entries for compile time and pre-execution-time tables and arrays, padalphameric 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 oneof the following three formats:

• numeric/alphameric

• Packed-decimal

• Binary

Table 5–13 Column 55 (Data Format - Alternate Entry)


Blank Specifies that numeric data is in zoned-decimal or trailing numericformat or that the table or array contains alphameric data.

P Specifies that numeric data is in packed-decimal format. This formatis valid only for pre-execution-time tables or arrays.

B Specifies that numeric data is in binary format. This format is validonly 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 decimalpoint for numeric data in a table or array.

Table 5–14 Column 56 (Decimal Positions - Alternate Entry)


Blank The table or array contains alphameric data.

0-9 Specifies the number of positions to the right of the decimal point fornumeric 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 thesecond 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 alternatetable or array.

Table 5–15 Column 57 (Sequence - Alternate Entry)


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

D Specifies that the entries in a table or array are in descending order,sorted from highest to lowest according to the specified collatingsequence.

Consecutive entries that are equal in value are considered to be insequence.

When using tables or arrays in alternating format, this entry specifies thesequence of the alternate table or array.

When a sequence is specified for a compile time table or array, thesequence is checked by the RPG compiler. If the table or array is notsorted in the specified sequence, the compiler issues a fatal compile timeerror.

If a pre-execution-time table or array is out of sequence, the program haltsand prompts the user to ignore the error and continue, or terminate theprogram.

5–10


5.19 Columns 58 - 80 (Comments)Columns 58 - 80 can be used for comments. Entries in these columns areignored by the compiler.

5–11

6 Line Counter Specification (L)

The Line Counter specification allows the default form length to bechanged for a PRINT or PRINTER file. The Line Counter specificationcan be used to change both the number of lines on a page and the overflowline.

The default form length for a PRINT or PRINTER file is 66 lines; thedefault overflow line is line 60. When a printer file reaches the overflowline, the overflow indicator is set on and overflow processing takes place.


6.2 Column 6 (Specification Identification)Column 6 must always contain an L to identify a Line Counterspecification.






6.4 Columns 7 - 14 (File Name)Columns 7 - 14 identify the print file with which the Line Counterspecification is associated.

6–1

Line Counter Specification (L)

Table 6–2 Columns 7 - 14 (File Name)


File name Identifies the name of the output file.

The print file must be described in a File Description specification withprint 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 apage.

Table 6–3 Columns 15 - 17 (Form Length)


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

6.6 Columns 18 - 19 (Form Length Flag)If an entry is specified in columns 15 - 17 (form length), FL must beentered in columns 18 - 19 to indicate that columns 15 - 17 define the formlength.

Table 6–4 Columns 18 - 19 (Form Length Flag)


FL Indicates that the program is to use the form length specified incolumns 15 - 17.

6.7 Columns 20 - 22 (Overflow Line Number)Columns 20 - 22 can be used to specify the overflow line number. Whenoutput to the PRINT or PRINTER file reaches the overflow line, theoverflow indicator is set on and overflow processing takes place.

Table 6–5 Columns 20 - 22 (Overflow Line Number)


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 mustbe a right-justified, numeric value. Leading zeros can be omitted.

When the overflow line is reached, the following actions occur if fetchoverflow 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. Enoughspace should be left between the overflow line and the end of the page toallow 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 mustbe entered in columns 23 - 24 to indicate that columns 20 - 22 define theoverflow line number length.

Table 6–6 Columns 23 - 24 (Overflow Line Flag)


OL Indicates that the program is to use the overflow line numberspecified in columns 20 - 22.


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

• Field descriptions. Columns 43 - 74 describe the fields in each recordand data structure.

• Data structure definitions. Columns 7 - 20 can be used to define a datastructure.

Input specifications must be used to describe each input, update, andcombined file except for table input files and record-address files.


7.2 Column 6 (Specification Identification)Column 6 must always contain an I to identify an Input specification.






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 todescribe the fields in each record. Field descriptions must begin one linebelow the record description.

7–1

Input Specification (I)

7.5 Columns 7 - 14 (File Name)Columns 7 - 14 can be used to identify an input file record or a datastructure.



File Name Identifies the input file with which the input record isassociated. The file name must match the file name specifiedin columns 7 - 14 of the File Description specification.

Data StructureName

Optional name of a data structure. A DS must be specifiedin columns 19 - 20 to identify this specification as a datastructure definition.

If this entry is blank, the compiler will assume that the informationin this line describes a field or record from the last file named in anInput specification. If the line follows a data structure definition, it canbe another data structure definition (DS in columns 19 - 20) or a datastructure subfield definition.

All records and fields associated with one file should be described in onecontiguous section of Input specifications.


7.6 Columns 14 - 16 (AND/OR)AND or OR can be specified in columns 14 - 16 to show a relationshipbetween record-identifying indicators or record types. The entry must beleft justified. AND/OR relationships in Input specifications are discussedfurther in Section 7.11.5.

7.7 Columns 15 - 16 (Sequence)Columns 15 and 16 are used to specify the sequence that defines theordering sequence of the record types in a file (for example, distinguishingemployee name records from employee badge number records). Theprogram does not order records according to sequence. It is used todetermine that the records are input in the correct sequence.

7–2


Table 7–3 Columns 15 - 16 (Sequence)


Blanks Specifies no sequence checking for the record.

Any twoalphabeticcharacters

Performs no sequence checking for the record. Any twoletters from AA through ZZ can be used (example, BB, ZA,DE). Alphabetic characters must be specified for chained,demand, and full-procedural files and look-ahead fields.

Anytwo-digitnumber

Assigns a sequence number to a record. Any two-digitnumber from 01 to 99 is valid. Numeric sequence codesmust be specified in ascending order. Numeric sequencecodes must begin with 01. Gaps in the sequence numbersare permitted.

Within one file, all records using alphabetic sequence codes must bedefined before those using numeric sequence codes.

Record sequencing can be used to insure that records from a file areprocessed in the correct order. For example, in a customer order filecontaining an order record followed by several detail records containingorder information, it would be important to ensure that the order recordwas processed before the associated detail records. By assigning the orderrecord 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 beforeit processes them.

If a record is processed out of sequence, the program halts and givesthe user the option of ignoring the sequence error and continuing orterminating the program.

Sequence checking does not place records in order. It verifies that recordsare in the correct order when they are input into the program. Sequencechecking has no relation to control levels and does not check data within arecord.

Input specifications with an AND or OR specified in columns 14 - 16cannot have a sequence code.

7.8 Column 17 (Sequence Number)If a numeric sequence code is assigned in columns 15 - 16, column 17 isused to indicate the number of records in a sequence group.

7–3


Table 7–4 Column 17 (Sequence Number)


Blank Program does not check the record for a special sequence. Columns15 - 16 must be blank or specify an alphabetic sequence code.

1 Specifies that there is only one record of this type in a sequencegroup.

N Specifies that there can be more than one record of this type in asequence group.

Leave this column blank if an alphabetic sequence has been specified incolumns 15 and 16.

Input specifications with an AND or OR specified in columns 14 - 16cannot 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 bepresent in a sequence group.

Table 7–5 Column 18 (Option)


Blank Record type must be present if sequence checking has beenspecified.

O Record type is optional in a sequence group.

U The program uses the data structure defined by this Inputspecification as the local data area. See Chapter 16, Definingand Using Data Structures, for more information on the local dataarea. Only one local data area data structure can be defined in aprogram.

Leave this column blank if a blank or alphabetic sequence has beenspecified in columns 15 - 16.

If all records are listed as optional, no sequence checking is performed.Input specifications with an AND or OR specified in columns 14 - 16cannot 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 indicatorwith a particular record type. When a record of the type specified for thisprogram line is processed, the indicator is set on. The indicator remainson through detail time output, unless set off by the programmer. Afterdetail time output, all indicators used as record-identifying indicators areset off. See Chapter 1, Understanding the Migration RPG Logic Cycle, formore information on the RPG logic cycle.

7–4


Table 7–6 Columns 19 - 20 (Record-Identifying Indicator)


Blank No record indicator specified.

01-99 Specifies a record-identifying indicator.

H1-H9 Specifies a halt indicator as a record-identifying indicator, indicatingthat 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 beginningof 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 LRsetting is overridden by the programmer.

** Indicates that the fields described on the subsequent program linesare look-ahead fields. Look-ahead fields can only be used with inputand update files. They cannot be specified for chained, demand,full-procedural, or WORKSTN files.

DS Specifies a data structure definition. A data structure consists ofalphameric fields and can be 1 - 9999 characters in length. Datastructure definitions must appear as the last entries in the Inputspecification section. See Chapter 16, Defining and Using DataStructures, for more information on data structures.

7.10.1 Look-Ahead FieldsLook-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 onlythe 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 beprocessed 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. Thedescription applies to all records regardless of their record type. All fieldsassociated to a record definition with a double asterisk (**) in columns19 - 20 are considered look-ahead fields. A look-ahead record definitionmust have an alphabetic sequence code.

Look-ahead fields can be used only with input or update primary orsecondary files.

For input files, look-ahead fields contain data from the next record in thefile.

For update files, look-ahead fields apply to the next record in the file onlyif the current record being processed was read from another file. If onlyone file is being processed and it is an update file, the look-ahead fieldswill 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 afterthe record has been read for normal processing, define the fields a secondtime in another record using different field names.

When a look-ahead operation reaches end-of-file, it fills all look-aheadfields associated to the file with 9’s. If a look-ahead field is 10 characterslong, it will contain the 9999999999 when end-of-file is reached.

Blank after (B in column 39) cannot be specified in the Outputspecifications 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 recordtype. If all records in a file are to be processed, regardless of type, or if allrecords have the same type, leave columns 21 - 41 blank.

If a file contains more than one type of record, columns 21 - 41 are usedto identify the different records. Records are identified by matchingcharacters specified in columns 21 - 41 with corresponding characters inthe record.

Columns 21 - 41 are divided into three subsets. Each subset specifies fourfields. The fields are used to identify the position, data type, comparisoncondition, and character used to identify the record. If more than onesubset is used, the record must satisfy all conditions before it will beprocessed. Used in this way, the comparison conditions form an ANDrelationship.

If a record cannot be identified by the program, a halt is issued. The useris given the option of ignoring the record and continuing the programor terminating the program. It is a good practice to define a catch-allrecord as the last record in a set of Input specifications which define therecord layouts for a file. Columns 21 - 41 will be left blank in a catch-allrecord, allowing it to accept any record which did not match the previousdefinitions. This will avoid program halts.

Records are checked for a record type in the order in which they arespecified in the Input specification. The first set of record-identificationconditions which are satisfied by the input record will identify the recordtype.

Columns 21 - 41 are divided into three subsections. Coding rules are thesame 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 therecord 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, makesure that all of the other record identification columns in this subset areblank as well.

1-9999 Defines the position in the input record that is to be compared to thecharacter specified in columns 27, 34, and 41. For example, the number10 specified in columns 28 - 31 would indicate that position 10 of the inputrecord should be compared to the character specified in column 34.

The position entry must be numeric and right-justified. Leading zeros canbe omitted.

7.11.2 Columns 25, 32, 39 (Not)Columns 25, 32, and 39 are used to indicate whether an identificationcharacter must be present in the input record.

Table 7–8 Columns 25, 32, 39 (Not)


Blank Indicates that the identification character must be present to identify arecord type. For example, if column 25 is left blank, the identificationcharacter specified in column 27 must be present in the input recordin the position specified in columns 21 - 24.

N Indicates that the identification character must not be present toidentify a record type. For example, if an N is specified in column39, the identification character specified in column 41 must not bepresent 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 characterto use when identifying a record. The comparison can be carried outusing the entire character (C), the zone portion of the character (Z), or thedigit portion of the character (D). When establishing record-identificationconditions using the zone or digit option, keep in mind that the zone ordigit portion of many characters is the same. See Appendix A, CharacterSets, for a listing of the ASCII and EBCDIC character sets.

7–7


Table 7–9 Columns 26, 33, 40 (Character, Zone, or Digit)


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 whichis used as the identification character. This character will be compared tothe specified position in the input record.

Table 7–10 Columns 27, 34, 41 (Comparison Character)


Anycharacter

Specifies the character to be used in the identification condition.

7.11.5 Columns 14 - 16 (AND and OR Relationships)Entering AND in columns 14 - 16 or entering OR in columns 14 and 15associates two input specifications that specify an identification condition.

A maximum of three identifications characters can be specified on oneInput specification. An AND line can be used to continue the record-identification condition from the previous line. All conditions must bematched before the record-identifying indicator will be turned on.

If a record can be identified by more than one set of conditions, an OR lineis used to separate each set of record-identification conditions.

Table 7–11 Columns 14 - 16 (AND and OR Relationships)


AND Specifies an AND relationship between the identification conditionson the current program line and the previous program line.

OR Specifies an OR relationship between the record identificationconditions 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 anOR line. If columns 19 - 20 are left blank, the record-identifying indicatorspecified in the preceding program line will apply to the OR line.

7.12 Column 42 (No-op)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. Fielddescriptions must begin one line below the record description. Use aseparate 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 incolumns 53 - 58 is stored.

Table 7–12 Column 43 (Data Format)


Blank Indicates that the field contains either alphameric characters ornumeric 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 Por 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 inputrecord. The unpacked length of each element in the array is defined in theassociated 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 endpositions 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. Todetermine the packed length of a packed-decimal field, divide thenumber 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 lengthis 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 fieldin a record.

Table 7–13 Columns 44 - 47 (Field From Location)


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

Table 7–14 Columns 48 - 51 (Field To Location)


1-9999 Specifies the ending character position of the field.

This entry must be greater than or equal to the start position entry incolumns 44 - 47. When specifying a one-character field, the start and endposition 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 numberof digits to the right of the decimal point.

Table 7–15 Column 52 (Decimal Positions)


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 thefield has no decimal points. In this case, specify a zero.

The number of decimal positions must be less than or equal to the numberof digits in the numeric field. If a number greater than the length of thefield is specified, the number of decimal positions is assumed to be equalto the length of the field.

7–10


If a 2 is specified in this column and the field contains the data 12345, thefield’s value is interpreted as 123.45. If a 4 is specified in this column andthe 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 columns43 - 52.

Table 7–16 Columns 53 - 58 (Field Name)


Name Specifies the name of the field. The name can be a field name, arrayname, or array element.

PAGEPAGE1-PAGE7

Specifies a page number.

*INxx*IN,xx

Specifies an indicator setting.

All entries in columns 53 - 58 must be left-justified.

To eliminate duplicate coding, use OR in columns 15 and 16 of the recordspecification 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 beused by the program.

7.13.4.1 Field NamesThe field name can be any combination of one to six alphameric charactersexcept for blanks or special characters. The first character must be analpha character.

Reserved words, such as UDATE, UDAY, UMONTH, UYEAR, $UDATE,$UDAY, $UMNTH, $UYEAR, PAGE, and PAGE1 - PAGE7 cannot be usedas field names.

Use a unique name for each field within a record. If a field name isduplicated within a record, the RPG compiler will use the field definitionfor the last field described.

Field names can be duplicated between records as long as both fields arenumeric with the same number of digits, or both fields are alphamericwith the same length.

An entire array can be loaded from an input record by entering the arrayname in columns 53 - 58. When an array is specified, columns 59 - 62 and65 - 70 must be left blank.

Individual array elements can be loaded by entering the array namefollowed 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 thetotal length of the data structure.

Control break (columns 59 - 60), match-field (columns 61 - 62), and fieldindicators (columns 65 - 70) are not valid for data-structure subfieldentries.

A data structure name cannot be specified as a subfield in a data structure.

7.13.4.2 PAGE, PAGE1 - PAGE7The PAGE and PAGE1 - PAGE7 special words can be used to specifyautomatic page numbering in a PRINT or PRINTER file. By default, thesefields are internally defined as 4 digit, zero-decimal, numeric fields. Theprogrammer 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 outputspecifications before it is output. A PAGE field can be used just like anyother numeric field in the Calculation specifications.

The PAGE fields allow the programmer to control the numbering of reportpages. If a PAGE field is specified in the Input specifications, the valueplaced in the field will be used as the starting page value. Eight PAGEfields (PAGE, PAGE1, PAGE2, PAGE3, PAGE4, PAGE5, PAGE6, PAGE7)are provided to permit the programmer to number different page types ina 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 lessthan the value the programmer wishes to have output. This is becausea PAGE field is always automatically incremented by one before it isoutput. 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,xxIndicators 01 - 99 can be referenced as single-character, alphameric fieldsusing the *INxx field designations or by referencing the *IN indicatorarray. If an indicator field or indicator array element is defined as aninput 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 a99-character, alphameric entry.

7.13.5 Columns 59 - 60 (Control break Indicator)Columns 59 - 60 can be used to specify control break indicators. Controlbreak indicators cause RPG to compare the contents of a field withthe contents of the same field from a previous record. If the fields arenot equal, a control break occurs and RPG sets on the control breakindicator 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 LogicCycle, for an example of the use of control break indicators.

Table 7–17 Columns 59 - 60 (Control break Indicator)


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

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 breakindicators are set off after detail time output.

Control fields are initialized to hexadecimal zeros. This usually causes acontrol break to occur on the first record with a control field. Because ofthis, RPG bypasses total-time calculation and output operations on thefirst 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 recordtypes.

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 fieldsmust be either all numeric or all alphameric and described on adjacentlines. The fields used within split-control fields do not need to be the samelength.

The maximum length of a control field or split-control field is 144characters.

The total length of a split-control field must be the same length as otherfields using the same control break indicator.

The decimal positions and sign of numeric fields are ignored whendetermining a control break. Thus, the fields 257.8 and 2578 would beconsidered equal. The fields -3049 and 3049 would also be consideredequal.

Field names are ignored when processing control fields. This allows thesame control break indicator to be assigned to multiple fields with thesame name.

If any one control field is numeric, all fields assigned to that control breakindicator will be treated as numeric when being compared, meaning thatonly the digit portion of each character will be compared.

7–13


If a control field contains packed-decimal data, the unpacked length, whichis two times the packed-decimal length minus one, is considered the lengthof the field for comparison purposes.

Input fields defined as binary (B in column 43) cannot be used as controlbreak fields.

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

Table 7–18 Columns 61 - 62 (Matching Fields)


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 orwith multiple files to control the order in which records are processed.

Matching fields can only be specified for records in primary and secondaryinput and update files.

Up to nine different fields can be specified as match fields in a singlerecord.

If more than one matching field is specified for a record type, all the fieldsare logically concatenated and treated as one continuous field. The fieldsare combined according to descending sequence (M9 - M1) of matchingfield values.

The match codes M1 - M9 are not indicators. If a record is matched, thematching-record indicator, MR, will be turned on. The MR indicator canbe used in the Calculation and Output specifications.

The program performs sequence checking for all record types withmatching field specifications. An error in sequence will generate a halt.The user will be given the option of ignoring the mismatched record andcontinuing, 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 144characters.

Matching fields can be overlapped in a single record.

When more than one matching code is used, all matching fields mustmatch before the matching-record indicator (MR) is set on.

7–14


Matching fields assigned the same matching code (M1 - M9) should beeither numeric with the same number of digits or alphameric with thesame length. If any single match field is numeric, all fields assigned thatmatch code will be treated as numeric fields when compared, meaning thatonly the digit portion of the field will be compared.

Not all files or all record types within one program must have matchingfields defined. However, at least one record type from each of two filesmust 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 lengthof the matching field for comparison purposes. It is valid to match apacked field in one record against a zoned-decimal or trailing numeric fieldin another if the unpacked lengths are equal. The length must always beodd because the length of a unpacked, packed-decimal field is always odd.

The file sequence specified in column 18 of the File Descriptionspecification must be the same for the files compared using matchingfields. All files must be in ascending or descending sequence.

The sequence of a single file can be checked using M1 - M9 codes todesignate the sequence check fields. If the file is out of sequence, a haltoccurs and the user has the option of ignoring the non-sequenced record orterminating the program.

Look-ahead fields cannot be specified as matching fields.

If an alternate collating sequence is specified, it is used when comparingthe values in matching fields containing alphameric data.

Field names are ignored when carrying out match field compares, so fieldsfrom different records can have the same name and match code.

When specifying an ascending sequence check, match fields are initializedto hexadecimal zeros. When a descending sequence is specified, matchfields are initialized to hexadecimal FF’s. Numeric fields are initialized tozero.

Numeric matching fields are compared based on their absolute values;decimal positions and signs are ignored. Thus, the field 2.987 and 298.7would 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 isextracted from the input buffer into a field. These conditions includecontrol 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 ORrelationship and associate fields with a particular record type.

Table 7–19 Columns 63 - 64 (Field-Record-Relation Indicator)


Blank Indicates no field-record-relation indicator.

01-99 Indicates that the field-record-relation indicator is a record-identifyingindicator.

L1-L9 Indicates that the field-record-relation indicator is a control breakindicator.

MR Indicates that the field-record-relation indicator is the matching-recordindicator.

U1-U8 Indicates that the field-record-relation indicator is an externalindicator.

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 indicatordefined if the specified indicator is on.

The following rules apply to field-record-relation indicators used withcontrol 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 orcontrol field is on, that field is used as the control or matching fieldfor the record rather than the same control or matching field specifiedwithout a field-record-relation indicator.

• When an entire set of matching fields has not been specified withouta field-record-relation indicator, a full set of matching fields must beassigned to each field-record-relation indicator used with a matchingfield.

• The same field-record-relation indicator must be used for split-controlfields. Split-control fields must be defined on consecutive lines.

• Control and matching fields that use field-record-relation indicatorsmust 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 definitionline or in one of the lines in an OR relationship.

If a program has two records with eight fields each, and the first sevenfields are the same but the last field is different, a record-identifyingindicator can be used as the field-record-relation indicator to condition thefield 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 indicatorscheck the contents of numeric or alphameric fields when they are extractedfrom the input record.

Table 7–20 Columns 65 - 70 (Field Indicators)


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 canbe used to check for errors in data. For example, a halt indicatorcould be specified to check for zeros in a numeric field. If a numericfield is processed that contains zero, the halt indicator is set on andthe program halts. The user then has the option of ignoring therecord 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 differentrecord types. The status of the indicator depends on the record type lastread.

Columns 65 - 70 must be blank when columns 53 - 58 contain an entirearray 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 dataentered is greater than zero.

67 - 68 Minus If the field is numeric, the indicator is turned on if the dataentered is less than zero.

69 - 70 ZeroorBlank

If the field is numeric, the indicator is turned on if the dataentered is equal to zero.

If the field is alphameric, the indicator is turned on if thefield 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 performedand 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 setson or off as a result of the calculation.

There are two general rules:

1 Specify each calculation on a single line, arranging the calculations inthe order they are to be executed.

2 Specify detail time calculations first, then total time calculations and,finally, calculations in subroutines.


8.2 Column 6 (Specification Identification)Column 6 must always contain an C to identify a Calculation specification.






8–1

Calculation Specification (C)

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

Table 8–2 Columns 7 - 8 (Control Level)


Blank Performs the calculation at detail time or indicates that the programline 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. Subroutinespecifications must appear at the end of the Calculationspecifications.

AN or OR Establishes an AND or OR relationship between the indicatorsspecified in columns 9 - 17 of the previous and current programlines. If AN is used, the conditions for the indicators in both programlines must be satisfied before the calculation will be executed. If ORis used, the conditions for the indicators in one program line or theother must be satisfied before the calculation is executed.

An unlimited number of AN or OR program lines with up to threeindicators on each line can be specified to condition a singlecalculation. The last line in an AN or OR relationship specifiesthe calculation. Columns 18 - 59 must be blank on all but the lastline.

8.5 Columns 9 - 17 (Conditioning Indicators)Columns 9 - 17 can be used to specify indicators to condition the executionof calculation lines. Up to three indicators can be specified on a programline. Preceding an indicator with N causes the condition to be valid onlywhen the associated indicator is not on. Use columns 9 - 11 to describethe first indicator, columns 12 - 14 to describe the second indicator, andcolumns 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 columns7 - 8 if it is necessary to condition a calculation operation with more thanthree indicators or more than one set of conditions.

Table 8–3 Columns 9 - 17 (Conditioning Indicators)

ColumnsAllowableEntries Explanation

9, 12,15

Blank Specifies that the associated indicator mustbe on to make the condition true or that noconditioning indicator has been specified.

N Not; specifies that the associated indicatormust not be on to make the condition true.

10 - 11,13 - 14,16 - 17

Blank Indicates that no conditioning indicator hasbeen specified. If columns 9 - 17 are allblank, the operation will be executed forevery program cycle in which the indicator incolumns 7 - 8 is satisfied.

01 - 99 Indicates that a record-identification, field, orresulting indicator defined elsewhere in theprogram must be on or off to execute thisoperation.

H1 - H9 Indicates that a halt indicator definedelsewhere in the program must be on oroff to execute this operation.

KA - KN,KP - KY

Indicates that a command-key indicatordefined elsewhere in the program must beon or off to execute this operation.

L1 - L9 Indicates that a control break indicatordefined elsewhere in the program must beon or off to execute this operation.

LR Indicates that the last-record indicator mustbe on or off to execute this operation.

MR Indicates that the matching-record indicatormust be on or off to execute this operation.

OA - OG,OV

Indicates that an overflow indicator definedelsewhere in the program must be on or offto execute this operation.

RT Indicates that the return indicator definedelsewhere in the program must be on or offto execute this operation.

U1 - U8 Indicates that an external indicator must beon or off to execute this operation.

RPG performs total calculations for a control break before performingdetail time calculations for the record that causes the control break.

An indicator specified in columns 9 - 17 can also be specified as a resultingindicator in columns 54 - 59 of the same line.

All conditions specified by the conditioning indicators must be met beforethe associated operation will be performed.

8–3


8.5.1 Relationship Between Control Level and Conditioning IndicatorsIn a single program cycle, all operations conditioned by the control breakindicators in columns 7 - 8 are performed before the operations conditionedby the control break indicators in columns 9 - 17.

When a control break indicator is specified in columns 9 - 17 insteadof in columns 7 and 8 of the Calculation specification, the operation isperformed during detail time processing, not total time processing.

If a calculation is conditioned with a last-record indicator in columns 9 - 17when 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-recordindicator is set on when the program reaches end of file or during totaltime calculations, detail time calculations are not performed.

When a control break indicator is specified in columns 7 - 8 and thematching-record indicator in columns 9 - 17, MR indicates the result ofmatching the previous record rather than the record just read that causedthe control break. All operations conditioned by control break indicatorsare executed before determining the matching condition of the record justread.

8.6 Columns 18 - 27 (Factor 1)Columns 18 - 27 can be used to specify the first element acted upon by acalculation operation. This element is called factor 1. Not all operationsneed an element specified in factor 1, and some operations do not permitan entry in factor 1. See Chapter 11, Operation Codes, for descriptions ofall of the operation codes supported by Migration RPG.

Table 8–4 Columns 18 - 27 (Factor 1)


Field name Specifies any defined data field. These are the same fields that aredefined in columns 53 - 58 of an Input specification or in columns43 - 48 of a Calculation specification.

AlphamericLiteral

Specifies an alphameric constant. Alphameric literals can be up toeight characters in length, including blanks. Alphameric literals mustbe enclosed in single quotation marks (for example, ’DIVIDE’). Ifa single quote must be included in a literal, two consecutive singlequotes must be specified (for example, ’CAN’’T’). Alphamericliterals cannot be specified in arithmetic operations.

NumericLiteral

Specifies a numeric constant. Numeric literals can consist of thedigits 0 through 9, one decimal point, and one arithmetic sign.Numeric literals cannot exceed 10 digits in length and cannot containblanks. If a sign is specified, it must be the leftmost character in thefield. An unsigned numeric literal is treated as a positive number.Numeric literals are handled in the same way as numeric fields.

Table orArray

Specifies a table name, array name, or array element. Tables andarrays are defined in Extension specifications.

8–4


Table 8–4 (Cont.) Columns 18 - 27 (Factor 1)


Specialwords

Specifies one of the following special words: UDATE, UMONTH,UDAY, UYEAR, $UDATE, $UMNTH, $UDAY, $UYEAR, PAGE, andPAGE1 - PAGE7.

FigurativeConstants

Specifies figurative constants such as *BLANK, *BLANKS, *ZERO,and *ZEROS. *BLANK and *BLANKS can only be used withalphameric fields. *ZERO and *ZEROS can be used with bothalphameric and numeric fields. The length of the figurative constantis assumed to be either the length of the entry in factor 2 or theresult field, depending upon the operation being performed.

*INxx and*IN,xx

Specifies a *INxx indicator field (*IN01 - *IN99) or a *IN,xx indicatorarray element (*IN,01 - *IN,99).

SpecialQualifier

Specifies the special qualifier *LIKE which is associated with theDEFN 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 RestrictionsThe following restrictions apply to entries in factor 1.

• If a data structure subfield is specified in factor 1, it cannot overlap adata structure subfield specified in factor 2 or the result field. If a datastructure subfield references an entire array or an array element usinga variable index, the entire array is used to determine overlap.

• Figurative constants cannot be used with move zone operations, bitoperations, label operations, or the DEBUG, KEYnn, SETnn, andSQRT operation codes.

8.7 Columns 28 - 32 (Operation Code)Columns 28 - 32 are used to specify the operation code that indicateswhich operation to perform on the elements specified in factor 1, factor2, and the result field. Operation code entries must be left-justified. SeeChapter 11, Operation Codes, for more information on valid MigrationRPG operation codes.

Table 8–5 Columns 28 - 32 (Operation Code)


Operationcode

Performs the action specified by the operation code.

8–5


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

Table 8–6 Columns 33 - 42 (Factor 2)


Field name Specifies any defined data field. These are the same fields that aredefined in columns 53 - 58 of an Input specification or in columns43 - 48 of a Calculation specification.

AlphamericLiteral

Specifies an alphameric constant. Alphameric literals can be up toeight characters in length, including blanks. Alphameric literals mustbe enclosed in single quotation marks (for example, ’COLORADO’).If a single quote must be included in a literal, two consecutive singlequotes must be specified (for example, ’IT’’S’). Alphameric literalscannot be specified in arithmetic operations.

NumericLiteral

Specifies a numeric constant. Numeric literals can consist of thedigits 0 through 9, one decimal point, and one arithmetic sign.Numeric literals cannot exceed 10 digits in length and cannot containblanks. If a sign is specified, it must be the leftmost character in thefield. An unsigned numeric literal is treated as a positive number.Numeric literals are handled in the same way as numeric fields.

Table orArray


*INxx and*IN,xx


Specialwords

Specifies one of the following special words: UDATE, UMONTH,UDAY, UYEAR, $UDATE, $UMNTH, $UDAY, $UYEAR, PAGE, andPAGE1 - PAGE7.

FigurativeConstants

Specifies figurative constants such as *BLANK, *BLANKS, *ZERO,and *ZEROS. *BLANK and *BLANKS can only be used withalphameric fields. *ZERO and *ZEROS can be used with bothalphameric and numeric fields. The length of the figurative constantis assumed to be either the length of the entry in factor 1 or theresult 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.

ExternalRoutineorSubprogramName

Specifies the name of an external routine, subprogram, systemservice, or MSI-supplied subroutine called by a CALL, CALLV, orEXIT operation or defined by an EXTRN operation.

All entries in factor 2 must be left-justified.

8–6


8.8.1 Factor 2 RestrictionsThe following restrictions apply to entries in factor 2.

• If a data structure subfield is specified in factor 2, it cannot overlap adata structure subfield specified in factor 1 or the result field. If a datastructure subfield references an entire array or an array element usinga variable index, the entire array is used to determine overlap.

• Figurative constants cannot be used with move zone operations, bitoperations, label operations, or the DEBUG, KEYnn, SETnn, andSQRT operation codes.

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

Table 8–7 Columns 43 - 48 (Result Field)


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 aCalculation specification.

Table orArray


*INxx and*IN,xx


Specialwords

Specifies one of the following special words: PAGE, PAGE1 -PAGE7.

*INxx Specifies any valid RPG indicator if associated with an RLABLoperation.

SubroutineName

Specifies any valid subroutine name if associated with a CABxx orCASxx 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 tosix characters long and can consist of alphameric characters. The namecannot contain blanks.

If the result field is not defined elsewhere, it can be defined within theCalculation specification using columns 49 - 52.

8–7


8.9.1 Result Field RestrictionsThe following restrictions apply to entries in the result field.

• A look-ahead field, a field defined by an EXTRN operation, and thefields 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 cannotoverlap a data structure subfield specified in factor 1 or factor 2. If adata structure subfield references an entire array or an array elementusing 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 theCalculation specification is used to define the result field. Otherwise, leavecolumns 49 - 51 blank. To prevent truncated results, make sure the lengthof the result field is long enough to hold the largest possible result.

Table 8–8 Columns 49 - 51 (Field Length)


Blank Result field is not being defined in this Calculation specification.

1-256 Result field is being defined by this Calculation specification. Theentry specifies the length of the result field.

Any entry in this field must be numeric and right-justified. Leading zeroscan 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 incolumns 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 definitionit encountered to define the field.

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

8–8


Table 8–9 Column 52 (Decimal Positions)


Blank Indicates that this field contains alphameric data or that the resultfield has been defined elsewhere.

0-9 Specifies that the field is numeric and indicates the number ofpositions to the right of the decimal point. If the field has no decimalpositions, specify a zero for the decimal entry.

If the field has been described previously in the program and an entry ismade 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 firstvalid field definition for all occurrences of the field.

The number of decimal positions must be less than or equal to the lengthof 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 bespecified in this column.

8.12 Column 53 (Half-adjust)Column 53 can be used to specify whether to round numeric data in theresult field of an arithmetic operation.

Table 8–10 Column 53 (half-adjust)


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 ofarithmetic 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 positionto the right of the last specified decimal position in the result field to thesame position and then truncating result. For example, if the result of aMULT operation was 248.9772, and the result field was defined as having2 decimal positions and half-adjust, .007 would be added to the result fieldfield, giving 248.9842. The field would then be truncated to 248.98.

By default, decimal positions to the right of the last defined decimalposition in the result field are truncated. In the previous example, if half-adjust had not been specified, the contents of the result field would havebeen truncated to 248.97.

Resulting indicators are set according to the value of the result field afterhalf-adjusting.

8–9


8.13 Columns 54 - 59 (Resulting Indicators)Columns 54 - 59 can be used to enter resulting indicators that indicate theoutcome of an operation. These indicators can then be used to conditionother 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)


01-99 Uses any standard indicator as a resulting indicator.

H1-H9 Uses a halt indicator as a resulting indicator.

KA-KNKP-KY

Uses a command-key indicator as a resulting indicator.

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 thespecified condition is not satisfied, the resulting indicator is usually setoff. See Chapter 11, Operation Codes, for information on how resultingindicators 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 anon-indexed array.

After a resulting indicator is on, it remains on until one of the followingoccurs:

• 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 inInput specifications and is set off during input of a new record.

Using a control break indicator (L1 - L9) as a resulting indicator does notautomatically set on lower-level, control break indicators.

Using an external indicator (U1 - U8) as a resulting indicator allows theindicator 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 anoutput file and the conditions under which data is output. Output canoccur 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 canbe divided into two general categories. Columns 7 - 37 are used to describeoutput records. Columns 23 - 74 are used to describe output fields. Fielddescription entries always begin one line below record description entries.


9.2 Column 6 (Specification Identification)Column 6 must always contain an O to identify an Output specification.






9–1

Output Specification (O)

9.4 Columns 7 - 14 (File Name)Columns 7 - 14 are used to specify the name of the output file. The namemust be the same as the file name specified in columns 7 - 14 of the FileDescription specifications.



File name Identifies the name of the output file.

The file name must match a file name specified in the File Descriptionspecifications. Valid output files are add, combine, output, or update files.


If columns 7 - 14 are blank, the compiler assumes that the information inthis 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 areused to link output lines together, allowing more than three conditioningindicators to be used to condition an output record.

Table 9–3 Columns 14 - 16 (AND/OR)


AND Performs the output operation when the conditions for all indicatorsin columns 23 - 31 in both program lines are met.

OR Performs the output operation when the conditions for all indicatorsin columns 23 - 31 in either program line are met.

AND and OR qualifiers can only be used to associate Output specificationsfor an output record. They cannot be used to allow an output field tobe conditioned by more than three indicators. A maximum of threeconditioning indicators is allowed on an output field.

At least one conditioning indicator must be specified on a program line inan 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 anoutput record.

9–2


9.6 Column 15 (Record Type)Column 15 is used to specify the type of record to be output. An entryin column 15 is required for every output record defined in the Outputspecifications.

Table 9–4 Column 15 (Record Type)


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 inwhich they are specified in the Output specifications.

9.6.1 Heading RecordsHeading records are normally used to describe the heading informationin a report, such as column names, page numbers, and the date. Headingrecords are usually output during first-cycle processing and after a controlbreak or overflow condition has been processed.

9.6.2 Detail RecordsDetail records usually contain data from input and calculation operationsperformed at detail time. Detail records are usually output during detailtime output.

9.6.3 Total RecordsTotal records usually contain the data from the result of calculations onseveral detail records. Total records are usually output during a controlbreak or overflow condition and during the last cycle.

9.6.4 Exception RecordsException records are output records which have their output directlycontrolled from the Calculation specifications. To output an exceptionrecord, the EXCPT operation must be specified in a Calculationspecification. See Chapter 11, "Operation Codes", for more informationon 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 ordeleted from a file.

Table 9–5 Columns 16 - 18 (ADD/DEL)


Blank The record is being output to an output file, updated in an updatefile, or this is an output field definition.

ADD Adds a record to an input, output, or update file with an A specifiedin column 66 of the File Description specification.

DEL Deletes the last record read in an update file with an indexed orrelative file organization.

The file associated with an ADD record must have an A specified incolumn 66 of the File Description specification.

ADD or DEL must appear on the same line that defines the record type forthe record that is to be added or deleted.

An ADD or DEL operation applies to all AND and OR relations specifiedfor the output record.

The DEL operation can only be performed on an update file. The DELoperation cannot be performed on a sequential file. The DEL operationdeletes the last record input from the update file. When a record isdeleted, 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 PRINTERfile. Fetch overflow causes RPG to check whether the overflow indicatorassigned to the printer output file is on before printing total, detail,or exception records. See Chapter 14, Using Printer Output Files, forinformation on overflow.

Table 9–6 Column 16 (Fetch Overflow or Release)


Blank No fetch overflow processing is performed on this Outputspecification.

F Executes the overflow routine if overflow has occurred.

An entry in this column is valid only for printer output files with overflowlines.

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 samespecification, the overflow routine will not be fetched for the specification.

If an OR relationship is specified between two lines, each output recorddefined by the OR relationship that is to use fetch overflow must have anF specified in column 16.

RPG fetches an overflow routine when overflow occurs and all conditionsspecified by the indicators in columns 23 - 31 of the Output specificationare met. When fetch overflow is specified, only overflow output associatedwith the file containing the executed fetch routine is output. The overflowroutine 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 aline is printed in a PRINT or PRINTER file.

Table 9–7 Column 17 (Space Before)


Blank Does not advance before printing a line of output.

0-9 Specifies the number of lines the printer will advance before printinga 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 overflowindicator.

9.10 Column 18 (Space After)Column 18 can be used to specify the number of lines to be spaced after aline is printed in a PRINT or PRINTER file.

Table 9–8 Column 18 (Space After)


Blank Advances one line after printing a line of output.

0-9 Specifies the number of lines the printer will advance after printing aline 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 overflowindicator.

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 orPRINTER file before printing a record.

Table 9–9 Columns 19 - 20 (Skip Before)


Blank Specifies no skipping before printing a line of output.

01-99 Causes the printer file to skip to line 01 - 99 before outputting arecord.

A0-A9 Causes the printer file to skip to line 100 - 109 before outputting arecord.

B0-B2 Causes the printer file to skip to line 110 - 112 before outputting arecord.

Entries can be specified in all space and skip columns for a single programline. If this is done, the entries are executed in the following order: skipbefore, space before, print the output line, skip after, and space after.

Specifying a skip before entry past the overflow line causes RPG to set onthe overflow indicator.

If a skip before entry is specified on the same line number that the printeris currently on, no skipping takes place.

If a skip before entry is specified to a line number less than the currentline number, the printer advances to that line number on the next page.

The skip entry cannot exceed the entry for forms length (columns 18 - 19of 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 theprevious 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 orPRINTER file after printing a record.

Table 9–10 Columns 21 - 22 (Skip After)


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

B0-B2 Causes the printer file to skip to line 110 - 112 after outputting arecord.

Entries can be specified in all space and skip columns for a single programline. If this is done, the entries are executed in the following order: skipbefore, space before, print the output line, skip after, and space after.

Specifying a skip after entry past the overflow line causes RPG to set onthe overflow indicator.

If a skip after entry is specified on the same line number that the printeris currently on, no skipping takes place.

If a skip after entry is specified to a line number less than the current linenumber, 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 theprevious 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 outputof records and fields. Up to three indicators can be specified on an Outputspecification. Preceding an indicator with N causes the condition to bevalid only when the associated indicator is not on. Use columns 23 - 25to describe the first indicator, columns 26 - 28 to describe the secondindicator, and columns 29 - 31 to describe the third indicator. Usingthe indicators in this way forms an AND relationship. Use AND or ORcodes in columns 14 - 16 if it is necessary to condition an output recorddefinition with more than three indicators. Output field definitions can beconditioned by a maximum of three indicators.

9–9


Table 9–11 Columns 23 - 31 (Output Indicators)

ColumnsAllowableEntries Explanation

23, 26,29

Blank Specifies that the associated indicator must be on tomake the condition true or that no conditioning indicatorhas been specified.

N Not; specifies that the associated indicator must not beon to make the condition true.

24 - 25,27 - 28,30 - 31

Blank Indicates that no conditioning indicator has beenspecified.

01 - 99 Indicates that a record-identification, field, or resultingindicator defined elsewhere in the program must be onor off to output this record or field.

1P Indicates that the first-page indicator is being used. Thefirst-page indicator is on only during the first programcycle. It cannot be controlled by the programmer. Outputof a record or field will be based on the setting of thisindicator.

H1 - H9 Indicates that a halt indicator defined elsewhere in theprogram must be on or off to output this record or field.

KA - KN,KP - KY

Indicates that a command-key indicator definedelsewhere in the program must be on or off to output thisrecord or field.

L0 Indicates that the L0 indicator is being used. The L0indicator is always on. It cannot be controlled by theprogrammer. Output of a record or field will be based onthe setting of this indicator.

L1 - L9 Indicates that a control break indicator defined elsewherein the program must be on or off to output this record orfield.

LR Indicates that the last-record indicator must be on or offto output this record or field.

MR Indicates that the matching-record indicator must be onor off to output this record or field.

OA - OG,OV

Indicates that an overflow indicator defined elsewhere inthe program must be on or off to output this record orfield.

RT Indicates that the return-from-subprogram indicator mustbe on or off to output this record or field.

U1 - U8 Indicates that an external indicator must be on or off tooutput this record or field.

9–10


When conditioning an entire record, enter the indicator on the line thatspecifies the record type (column 15). When conditioning a field, enter theindicator on the same line as the field name (columns 32 - 37).

If more than one indicator is specified on a line, the indicators form anAND relationship.

Overflow indicators can be used on AND or OR lines; however, only oneoverflow indicator can be associated with a group of output indicators. Ifa line is to be considered an overflow line, the overflow indicator mustappear on the main specification line or on an OR line.

If an overflow indicator is used, it must be the same one assigned to thefile on the File Description specification.

Overflow indicators cannot be used to condition exception output lines, butthey can be used to condition fields in an exception record.

Note that RPG outputs those detail and heading lines conditioned bythe first-page (1P) indicator, no indicator, or all negative indicators (N incolumns 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 thatdo not depend on data from an input record. For a line with no indicatorsor all negative indicators that requires data from an input record, use anegative first-page indicator (N1P in columns 23 - 31) to prevent the linefrom being output before reading the first record.

Because the 1P indicator is set off after the first detail time output, itshould only be used to condition heading and detail lines.

If a control break indicator is used with a total record and no overflowindicator, the record is output when a control break occurs and afterthe last record of a control group has been processed. If a control breakindicator is used with a detail record and no overflow indicator, the recordis output when a control break occurs and after the first record of a newcontrol group has been processed. If a control break indicator is used withan overflow indicator, the record is output when a control break occurs andthe 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, arrayname or element, data structure name, special word, or EXCPT name foroutput.

Table 9–12 Columns 32 - 37 (Field Name)


Blank Indicates that this is a record definition or that there is a constant incolumns 45 - 70.

Name Specifies the name of the field to be output or the name of anEXCPT record. A field name can be a data field name, table or arrayname, array element, data structure name, or one of the followingspecial words: PAGE, PAGE1 - PAGE7, UDAY, UMONTH, UYEAR,UDATE, $UDAY, $UMNTH, $UYEAR, $UDATE, *INxx, and *PLACE.

Left justify this entry.

9.14.1 Output field namesAll 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 incolumns 45 - 70.

If a field name is entered in columns 32 - 37, columns 7 - 22 must beblank.

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 theentry in columns 40 - 43. For ease in reading the RPG program, it isrecommended that Output specifications be written in the order the fieldsare to be output.

If output fields overlap, the last field specified in the Output specificationswill overlay data in all previous fields that it overlaps.

The sign of a numeric field is stored in the units position of the rightmostdigit in the field. If the field contains a negative value when output to aprinter file, this digit prints as an alpha character (}, J - R) unless an editcode or edit mask has been specified.

A field name can be 1 - 6 characters long.

9–12


9.14.2 Output Special WordsThe special words PAGE, PAGE1 - PAGE7, *PLACE, UDATE, UDAY,UMONTH, UYEAR, $UDAY, $UMNTH, $UYEAR, and $UDATE can all beused in the Output specifications. These predefined fields are described indetail in the following sections.

9.14.2.1 PAGE, PAGE1 - PAGE7 Special WordsThe PAGE special words are used to specify automatic page numbering ina PRINT or PRINTER file. If a PAGE field is specified in the Outputspecifications without being defined elsewhere in the program, it isassumed to be a 4-digit numeric field with zero decimal positions. APAGE field can also be defined and used in the Input and Calculationspecifications. It can be defined as a numeric field with 1 - 15 digits. APAGE field should always have zero decimal positions.

By default, a PAGE field is initialized to zero. It is incremented by oneeach time it is output. The field is incremented before it is output. If aPAGE field is being initialized by the program, it should be initialized to avalue one less than the first value to be output. For example, if the firstpage number to be output is to be 10, the PAGE field should be initializedto 9.

Page numbering can be reset at any time in a program. Remember toinitialize the field to a value one less than the initial desired output value.

A PAGE field can be initialized in the Output specifications by specifyingindicator conditions in columns 23 - 31 or by specifying blank-after incolumn 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 isprinted.

Eight PAGE special words (PAGE, PAGE1 - PAGE7) are available for usein a program. They can be used to specify different page numbering forvarious types of output to a single report, or they can be used to controlpage numbering in several reports being produced by one program.

Leading zeros are replaced with blanks by default when a PAGE field isoutput to a PRINT or PRINTER file.

9–13


9.14.2.2 *PLACE Special WordThe *PLACE special word can be used to repeat a set of fields in theOutput specifications. Using the *PLACE special word, the following twosections of output code will produce the same results.

In the first set of Output specifications, the fields HOTFT, DNCSTP, andQCKFT are output twice by specifying each field twice.

Example 9–1 *PLACE Special Word Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*OREPORT DO HOTFT 10O DNCSTP 15O QCKFT 25O HOTFT 35O DNCSTP 40O QCKFT 50O BALLRM 75

In the second set of Output specifications, the fields HOTFT, DNCSTP, andQCKFT are output twice by specifying the *PLACE special word to replacethe 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 outputexample.

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*OREPORT DO HOTFT 10O DNCSTP 15O QCKFT 25O *PLACE 50O 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 thefields being repeated by the *PLACE operation will end. Be sure the endposition specified accounts for the length of all of the fields being repeatedto prevent field overlapping.

The *PLACE special word can be repeated to duplicate field definitionsmore than once within a output record.

Additional fields and constants can be specified following a *PLACEspecial word. These items will not be affected by the *PLACE operation.

9–14


9.14.2.3 UDATE, UMONTH, UDAY, and UYEAR Special WordsThe UDATE special words, UDATE, UMONTH, UDAY, UYEAR, $UDATE,$UMNTH, $UDAY, and $UYEAR, can be used to specify the currentprocess date within an RPG program. By default, this date is the sameas the system date. However, the REX Utility allows the system date tobe overridden with a user-specified process date. See the Migration RPGUser’s Guide for more information concerning the use of the REX Utility.

Note: The $UDATE, $UDAY, $UMNTH, and $UYEAR reserved words aresupplied to provide backward compabitility with 6-digit non-Year 2000 compliant dates. See the Migration RPG Year 2000Compliance Guide for more information concerning these fields.

Because the system date can be overridden using the REX Utility, the datereturned by the UDATE or $UDATE special words may not be the samedate as that returned by the date portion of the TIME or $TIME operationcodes. The TIME and $TIME operation code always returns the systemdate.

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. TheUDATE 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 followingformats:

• mm/dd/yy (default)

• yy/mm/dd

• dd/mm/yy

The format the process date is returned in depends upon the setting placedin columns 19 - 21 of the Control specification. See sections 3.8, 3.9, and3.10 in Chapter 3, Control Specification (H), for more information on howto specify the format in which a process date is returned.

The UMONTH and $UMNTH fields specify the month portion of theprocess date. These fields are defined as a 2-digit, zero-decimal, numericfields.

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 processdate. 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 2000compliant 2-digit, zero-decimal, numeric field.

9–15


9.14.3 Output EXCPT NamesWhen the output record type is an exception record (indicated by an E incolumn 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 calledan EXCPT name.

Table 9–13 Output EXCPT Names


Blank Identifies exception output records to be checked for output when anEXCPT operation with a blank factor 2 is executed.

Name Identifies exception output records to be checked for output when anEXCPT 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, datastructure name, array name, table name, label, or subroutine name.

One or more output records can use the same EXCPT name. The recordsdo not have to be consecutive records in the Output specifications.

An EXCPT record is only output if the EXCPT name is matched and theconditioning indicators in columns 23 - 31 are satisfied.

An EXCPT name is specified on the main record line. It applies to allassociated 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 toedit a numeric field without specifying an edit word. Table 9–14 definesvalid edit codes. Table 9–15 gives examples of edit code output.

Table 9–14 Column 38 (Edit Codes)


1 Prints a number with commas before every third digit to the left ofthe decimal point, prints a zero balance, and suppresses signs andleading zeros.

2 Prints a number with commas before every third digit to the left ofthe decimal point and suppresses a zero balance, signs, and leadingzeros.

3 Prints a number without commas, prints a zero balance, andsuppresses 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 ofthe decimal point, prints a zero balance, uses CR to represent anegative sign, and suppresses leading zeros.

B Prints a number with commas before every third digit to the left ofthe decimal point, suppresses a zero balance, uses CR to representa negative sign, and suppresses leading zeros.

C Prints a number without commas, prints a zero balance, uses CR torepresent a negative sign, and suppresses leading zeros.

D Prints a number without commas, suppresses a zero balance, usesCR to represent a negative sign, and suppresses leading zeros.

J Prints a number with commas before every third digit to the left ofthe decimal point, prints a zero balance, prints a negative sign, andsuppresses leading zeros.

K Prints a number with commas before every third digit to the left ofthe 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 anegative sign, and suppresses leading zeros.

M Prints a number without commas, suppresses a zero balance, printsa 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. Theformat dd/mm/yyyy or dd/mm/yy is used if inverted print has beenspecified. 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 blankunless an edit code modifier is specified.

If an edit code is used to edit an array, it is applied to each element in thearray. Two spaces are placed between each element in the array when it isoutput.

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 thecharacters the edit code will insert into the output field.

Unedited numeric output fields with negative values are output with theoverpunched representation of the sign. For example, -1 will be output asJ, -2 as K, and so on. Therefore, use an edit code or edit word to preventthe 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

EditCode +12345.67 +1234567 -1234.567 -1234567

Print ZeroBalance

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 afterit has been output. Alphameric fields are initialized to blanks and numericfields are initialized to zeros. Specifying blank after is especially usefulwhen accumulating control group totals.

Table 9–16 Column 39 (Blank After)


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 anEXTRN 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 theblank 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 thanonce during a cycle, enter B in column 39 on the last line specifying outputfor the field. Otherwise, the field will be initialized before all occurrenceswhere 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 orconstant in an output record.

Table 9–17 Columns 40 - 43 (End Position in Output Record)


Blank Indicates that the Output specification is a record definition or thatthe RPG compiler is to calculate the end position for the field.

1-9999 Indicates the position in the output record of the rightmost characterof an output field or constant.

K1-K8 Indicates that a WORKSTN screen format name begins in column45. The format name can be 1 - 8 characters in length.

The end position is the location of the rightmost character in the outputfield. For example, if a field contains 26 characters and 40 is specified asthe field end position, the field would be placed in the output record asfollows:

Example 9–2 Output field end position in an output record

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

Colorado Springs, Colorado

The numbers above this example are for reference only; they do not appearin 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 beomitted.

If fields overlap, the last field specified on the Output specification is theonly field that is completely written.

When specifying the end position for an array, use the rightmost positionof the last element in the array.

The end position specified for an output field must be equal to or greaterthan 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 (columns24 - 27 of the File Description specification) of the file to which the recordbelongs. If it is not, the compiler will issue an error message.

Be sure to allow enough room for the number of characters in each outputfield and for any editing characters specified using an edit code or editword.

If columns 40 - 43 are left blank and a field or constant is specified foroutput, the RPG compiler will calculate the field end position based on thefield 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 specifythat the field be output in a packed-decimal, binary, trailing numeric, orzoned-decimal data format. Packed decimal and binary formats conservedisk space.

Table 9–18 Column 44 (Output Data Format)


Blank Indicates that the field contains either alphameric data or numericdata that is to be output in a trailing numeric format. Trailing numericis the default output format for numeric fields and arrays if an outputdata 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-decimalformat.

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 iscalculated by dividing the unpacked length of the field by 2 and adding 1to the result. Thus, if a 9-digit, unpacked numeric field is to be output inpacked-decimal format, its output field length will be 5 (9/2+1).

When binary format is specified, a trailing numeric field 1 - 4 digits inlength is converted to a 2-byte binary field for output. A trailing numericfield 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, orWORKSTN screen format name. An edit word can be used to modify anedit code specified in column 38 or to define how data will be formattedwhen it is output. These items are described in more detail in thefollowing sections.

9.19.1 Output ConstantColumns 45 - 70 can be used to specify constant data for output. Outputconstants are commonly used as report headings and informational textwithin a report and identification codes within a data file.

A constant must be enclosed by single quotation marks (’). The charactersenclosed 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 than24 characters, it can be continued on the next Output specification line asanother constant.

When using constants, leave columns 32 - 39 and column 44 blank.

To include a single quote in a constant, use two consecutive single quotesto represent one single quote (for example, ’Subroutine’’s calculations’).

9.19.2 WORKSTN Screen Format NamesColumns 45 - 54 can be used to specify a WORKSTN screen format name.A WORKSTN screen format name is used to specify the screen formatwhich is to display the data being passed by the program.

A WORKSTN screen format name requires a K in column 42. Only onescreen format name can be specified for each WORKSTN output record. Ascreen format name must be specified for each WORKSTN output record.

A WORKSTN screen format name must be enclosed by single quotationmarks (’). The leading quotation mark must be placed in column 45.

A WORKSTN screen format name can be 1 - 8 characters in length. Thelength of the screen format name is specified in column 43. For example,if a WORKSTN screen format was named ASBECK, the entry in columns40 - 43 (end position) would be K6.

The WORKSTN screen format name must match a screen format namespecified in columns 7 - 15 of a Screen specification in the screen formatfile. If it does not, a runtime error will occur.

The Output specification containing the WORKSTN screen format namecannot be qualified by conditioning indicators in columns 23 - 31.

9–22


9.19.3 Edit Code ModifiersColumns 45 - 47 can be used to specify edit code modifiers. Edit codemodifiers can replace suppressed zeros to the left of the decimal pointwith asterisks (asterisk fill) or put a currency symbol before the leftmostcharacter (floating currency symbol). To specify these modifiers, enter theappropriate value described as follows:

Table 9–19 Columns 45 - 47 (Constant or Edit Word)


’*’ Replaces suppressed zeros to the left of the decimal point withasterisks ( * ).

’Symbol’ Places the currency symbol before the first significant digit in anumeric field. The currency symbol is defined in column 18 of theControl 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 whenan 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 WordsColumns 45 - 70 can be used to specify edit words. Edit words can be usedto edit a numeric field. Edit words consist of three parts: the body, thesign, and expansion. The body is the portion of the edit word that providesspace for the digits from the field to be edited. The body begins at theleftmost character position of the edit word and ends at the rightmostcharacter 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 thefield is positive or negative. The sign begins at the first character positionto the right of the body and ends with CR or a negative sign ( - ). If oneof these symbols is specified and the field is positive, blank spaces will besubstituted in the edited field. If CR or a negative sign is used and thefield is negative, the specified symbol will be substituted at the end of theedited field.

If an edit word contains no CR or a negative sign to the right of therightmost character that is to contain a digit, the edit word does notcontain a sign portion.

The expansion consists of additional characters that will be printedfollowing the last replaceable character in the edit word. The expansionbegins immediately after the sign (or body, if no sign is used) and continuesto the end of the edit word.

The following table describes the characters which can be used in the bodyof an edit word. In each example, leading zeros are suppressed. A smallletter b is used to indicate blank characters in the field.

9–24


Table 9–20 Columns 45 - 70 (Edit Words)


Blank Indicates that the position in the edited field is to contain the digitfrom the same position in the numeric field.

Edit word using blank charactersSource Data Edit Word Result of Edit

00496.23 ’bbbbb.bb’ bb496.23

0 Indicates that the field is to be zero suppressed. Place the zeroin the rightmost position where zero suppression is to stop. Eachleading zero that appears to the left of and including the stop positionof the numeric field is replaced with a blank space in the edited field.The first zero encountered when scanning the edit word is the zerosuppression character. Any zero appearing after the first zero istreated like any other character. Zero suppression begins at theleftmost position in the data and continues up through the stopposition unless a non-zero digit is encountered to the left of the stopposition. If a non-zero digit is encountered to the left of the stopposition, zero suppression stops at the position where the non-zerodigit is encountered; that digit and all following digits to the right ofthe non-zero digit are printed.

Edit word using zero suppressionSource Data Edit Word Result of Edit

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 theasterisk in the rightmost position where asterisk fill is to stop.Each leading zero that appears in the data to the left of andincluding the stop position is replaced with an asterisk. The firstasterisk encountered when scanning the edit word is the asterisk fillcharacter. Any asterisk appearing after the first asterisk is treatedlike any other character.

Edit word using asterisk fillSource Data Edit Word Result of Edit

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 characterSource Data Edit Word Result of Edit

00496.23 ’bbbbb.bb&-&Sales’ bb496.23b-bSales

9–25


Table 9–20 (Cont.) Columns 45 - 70 (Edit Words)


CurrencySymbol

Prints the currency symbol. If the currency symbol appears in thebody of the edit word immediately to the left of the zero suppressioncharacter or decimal point, it is printed immediately to the left of thefirst significant digit in the edited field. This type of currency symbolis called a floating currency symbol. A floating currency symbolcannot be used with asterisk fill.

The currency symbol in the leftmost position of the edit wordindicates that the symbol is to be printed in that exact position in theedited field. This type of currency symbol is called a fixed currencysymbol.

The currency symbol is defined in column 18 of the controlspecification.

Edit word using the currency symbolSource Data Edit Word Result of Edit

00496.23 ’bbbbb$.bb’ b$496.23

00496.23 ’$bbbbb.bb’ $bb496.23

Decimal pointor comma

Indicates the exact position in the edited field where a decimal pointor comma is to be printed. If a decimal point or comma appearsto the left of the most significant digit in the output field, it will bereplaced with a blank space or, if asterisk fill is specified, with anasterisk.

Edit word using commas and a decimal pointSource Data Edit Word Result of Edit

00496.23 ’bb,bbb.bb’ bbb496.23

47496.23 ’bb,bbb.bb’ 47,496.23

Any othercharacter

Prints the characters in the edited fields, if the position is to the rightof the most significant digit in the edited field. Any character to theleft of the most significant digit in the edited field is replaced with ablank space or an asterisk if asterisk fill is specified.

Edit word using the slash (/) characterSource Data Edit Word Result of Edit

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 signportion of an edit word.

Table 9–21 Using Edit Words to Display Negative Numbers


CR or - Indicates that the specified symbol (CR or a negative sign ( - )) is tobe printed in the edited field if the data is negative. If the edited fieldis positive, the specified symbol is replaced by blanks.

Edit words for a negative fieldSource Data Edit Word Result of Edit

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

Anycharacter

Prints the specified character(s) in the edited field if the data isnegative; otherwise, the character is replaced by a blank. Ifan ampersand ( & ) is specified, it will be replaced by a blankspace. These characters must appear between the last replaceablecharacter in the edit word and the sign character(s). If they appearto the right of the sign character(s), they are treated as extensions tothe field and will always be printed.

Edit words for a negative field using optional display charactersSource Data Edit Word Result of Edit

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 (dataformat) must be blank.

Edit words can be up to 24 characters long and must be enclosed in singlequotes.

The number of replaceable characters in an edit word must be greaterthan 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 positionto 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 ofblanks and the zero suppression in the edit word must be equal to orgreater than the number of digits in the edited field. A floating currencysymbol is not counted as a digit position.

9–27


Any zeros or asterisks following the leftmost zero suppression or asteriskfill 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.

9.21 Columns 75 - 80 (Comments)Columns 75 - 80 can be used for comments. The compiler will ignore anyentry in these columns.

9–28

10 Migration RPG Language Elements

This chapter describes the primitives or elements of a Migration RPGprogram. These elements include the character set, the various data types,and the names that are defined and used to identify program constructsand certain parts of those constructs.

10.1 Migration RPG Character SetMigration RPG uses the full ASCII character set, including:

• Uppercase letters A through Z, except for character literals andcomment fields

• Digits 0 through 9

• Special characters (such as $ and _ (underscore))

Appendix A, Character Sets, contains the complete ASCII character setand character values.

10.2 RPG Data TypesRPG input and output operations use the following data types whichdetermine how many bits of storage compose a unit of data in a program,and how that unit is to be interpreted and manipulated at programexecution time.

Migration RPG supports six different data types for input and outputoperations:

• 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 TypeCharacter data is a string of bytes containing ASCII codes as binarydata. Character field length can be from 1 to 9999 bytes. The format of acharacter string is shown in Figure 10–1.

Note: In all subsequent diagrams, A represents the address of the firstbyte of the string and L represents the length of the string inbytes.

Figure 10–1 Format of a Character String

7 0

A

A + L − 1

.

.

.

7 0

The address of a string specifies the first character of a string. The stringXYZ is shown in Figure 10–2. The address of the string would point at thecharacter X.

Figure 10–2 Address of a String

7 0

X A

A + 1

A + 2

Y

Z

10–2


The following code example depicts how character fields are defined withinan RPG program:

Example 10–1 Defining character fields

1 2 3 4 51234567890123456789012345678901234567890123456789012345678

*00050ISALES AA 01 1 CJ00060I 11 35 DESCR00070I 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. Line120 depicts the creation and initialization of a character field within theCalculation specifications. Here the character literal SNOJOB is beingmoved into the 6-character field NODE.

10–3


10.2.2 Binary Data TypeBinary data is stored as binary values in a word or longword. A word istwo contiguous bytes, starting on an arbitrary byte boundary. The bits arenumbered from the right (0 through 15). When interpreted as a signedquantity, a word is a twos complement number with bits increasing insignificance from bit 0 through bit 14, and with bit 15 designating thesign. A two-byte word supports up to four decimal digits. The largestnumber that can be represented by a word in RPG is 9,999. A word datatype is shown in Figure 10–3.

Figure 10–3 Word Data Type

15 0

A

A longword is four bytes, starting on an arbitrary byte boundary. The bitsare numbered from the right (0 through 31). When interpreted as a signedquantity, a word is a twos complement number with bits increasing insignificance from bit 0 through bit 30, with bit 31 designating the sign. Afour-byte longword supports up to 9 decimal digits. The largest numberthat can be represented by a longword in RPG is 999,999,999. A longworddatatype is represented in Figure 10–4.

Figure 10–4 Longword Data Type

31 0

A

10–4


The following code example depicts how binary fields are defined within anRPG program:

Example 10–2 Defining binary fields

1 2 3 4 51234567890123456789012345678901234567890123456789012345678

*00050IINVENTRYAA 0100060I 01 060PARTNO00070I B 07 080QTY00080I B 09 122COST

Lines 70 and 80 describe two binary input fields. The B in column 43 ofeach 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 TypePacked-decimal data is stored as a string of bytes. Each byte is dividedinto two, 4-bit half-bytes (nibbles), with one decimal digit stored in eachnibble. The first, or most significant, digit is stored in the high-ordernibble of the first byte; the second digit is stored in the low-order nibbleof the first byte; the third digit is stored in the high-order nibble of thesecond byte; and so on. The sign of the number is stored in the low-ordernibble 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. Anegative sign would be depicted by a hex 0D.

Figure 10–5 Packed-decimal Data Type

7 4 3 0

31 32 A

A + 133 0C

The following formula can be used to determine the length in digits of apacked-decimal field:

number of digits = (2 * n) - 1where n = number of bytes used

The following formula can be used to determine the number of bytesneeded to store a numeric field in a packed-decimal format:

number of bytes = n/2 + 1where n = number of digits in the field

Example 10–3 Defining packed-decimal fields

1 2 3 4 51234567890123456789012345678901234567890123456789012345678

*00050ILEDGER BB 1000060I 01 10 CUSTID00070I P 11 152INCOME00080I P 16 222EXPENS

Lines 70 and 80 describe two packed-decimal input fields. The P in column43 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, isa 13-digit field ((2 * 7) - 1).

Packed-decimal fields are normally used to conserve disk space. Thelargest numeric field which can be defined within an RPG program is 15digits. Thus, the largest packed-decimal field which can be defined withina RPG program would contain 8 bytes (15/2 + 1).

10–6


10.2.4 Numeric Data TypeNumeric data (non-packed, non-binary) is a contiguous sequenceof bytes in memory with one decimal digit in a byte. Digits ofdecreasing significance are assigned to increasing addresses. The signis superimposed on the last digit. Numeric data can be represented intrailing numeric or zoned-decimal format.

All bytes of numeric data, except the least significant digit, must containASCII decimal digits (0 through 9). Table 10–1 lists the representation forall digits.

Table 10–1 Zoned-decimal representation of digits

Numeric Format ASCII Characters

Digit Decimal HexadecimalTrailingNumeric

ZonedDecimal

ValidVariations

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 anoverpunch format, meaning that the sign is combined with the last digit inthe field.

There are several variations of overpunch format. Alternate forms ofoverpunch sign representation are accepted by RPG on input and thestandard trailing numeric sign representation is generated by default onoutput. Output can also be defaulted to zoned-decimal representationusing 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 numericdata.

Figure 10–6 Zoned-Decimal Data Type (123+)

7 0

1 A

A + 1

A + 2

2

3

Figure 10–7 shows 123- in trailing numeric format.

Figure 10–7 Trailing Numeric Data Type (123-)

7 0

1 A

A + 1

A + 2

2

L

Figure 10–8 shows 123- in zoned-decimal format.

Figure 10–8 Zoned-Decimal Data Type (123-)

7 0

1 A

A + 1

A + 2

2

s

10–8


10.3 Naming Conventions - User-Defined NamesA user-defined name is a named quantity that identifies items in aMigration 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 namecan be used in more than one field definition if each definition usingthat name has the same data type, the same length, and the samenumber of decimal positions.

• Arrays—an array name is assigned to an array. The first threecharacters cannot be TAB.

• Tables—a table name is assigned to a table. The first three charactersmust be TAB.

• Labels—a label identifies the destination of a GOTO or CABxxoperation.

• Subroutines—a subroutine name is assigned to a subroutine. Asubroutine name is referenced by the BEGSR, EXSR, and CASxxoperations.

• EXCPT—an EXCPT name can be used in factor 2 of the EXCPToperation code and in an exception record Output specification.

Naming conventions within a Migration RPG program follow standardOpenVMS naming conventions. The following rules must be adhered towhen 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 Athrough 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 filename, which can be up to eight characters long.

10–9

11 Operation Codes

The RPG programming language allows the programmer to perform manytypes of operations on their data. Many of these operations are definedby (operation codes) in the Calculation specifications. These codes areplaced in columns 28 - 32 of the Calculation specification and are usuallyabbreviated versions of the command that is to be performed.

The following sections offer a general description of the operation codesgrouped by function, followed by a detailed description of each operationcode in alphabetical order.

11.1 Arithmetic Operation CodesArithmetic operation codes include the ADD, Z-ADD, SUB, Z-SUB, DIV,MVR, MULT, SQRT, and XFOOT instructions. These operations performa variety of functions, ranging from adding two operands to taking thesquare root of an operand. When using arithmetic operation codes, thefollowing characteristics should be kept in mind:

• Arithmetic operation codes can only be used with numeric fields andnumeric literals.

• RPG aligns the operands according to their decimal points beforeperforming any arithmetic operation. Results of an arithmeticoperation are aligned on the decimal point in the result field, whichcan cause truncation on both ends of a result.

• The contents of factor 1 and factor 2 do not change during anarithmetic operation unless the same field is used as the result field.

• Any existing data in the result field is replaced with the result of thecurrent operation.

• If the length of the result field is not large enough to hold the result ofan arithmetic operation, the result of the operation is truncated beforebeing placed in the result field.

• Half adjust (column 53 of the Calculation specification) can be specifiedfor any arithmetic operation except a MVR operation and the DIVoperation immediately preceding it.

• The same field can be specified in factor 1, factor 2, and/or the resultfield.

• If factor 1 is left blank in an arithmetic operation, the contents offactor 2 are added, multiplied, subtracted, or divided into the resultfield 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 isdone, 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 arraysin 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 theresult of an arithmetic operation depends on the operation:

Addition:

— If factor 1 and factor 2 have like signs, the result field has thesame sign.

— If factor 1 and factor 2 have unlike signs, the result field uses thesign of the factor with the largest absolute value.

Subtraction:

— Change the sign of factor 2 (positive to negative or negative topositive) and use the same rules used for addition.

Multiplication:

— If factor 1 and factor 2 have like signs, the sign of the result fieldis positive.

— If factor 1 and factor 2 have unlike signs, the sign of the resultfield is negative.

Division:

— If factor 1 and factor 2 have like signs, the sign of the result fieldis positive.

— If factor 1 and factor 2 have unlike signs, the sign of the resultfield is negative.

— The sign of the remainder is the same as the sign of factor 1.

11.2 Bit Operation CodesBIT operation codes consist of the BITON, BITOF, and TESTBinstructions. These operation codes can be used to set, clear, and testindividual bits. When using bit operations, keep the following points inmind:

• The field specified in factor 2 of a bit operation must be a single-character, alphameric field. Numeric fields are considered alphamericif they have no decimal positions defined.

• Array or table elements can be used in bit operations if the array ortable is defined as having single-character, alphameric entries.

• If a field is defined in a bit operation, it is initialized with the valuehex 20 (blank).

• The result field used in a bit operation should also be a singlecharacter alphameric field. Bit operations are only designed to workon single character alphameric fields.

11–2

Operation Codes

11.3 Branching Operation CodesBranch operation codes consist of the CABxx, GOTO, and TAGinstructions. Branching operation codes can be used to skip or repeatoperations.

11.4 Compare and Test Operation CodesCompare and test operations consist of the CABxx, CASxx, COMP, ANDxx,ORxx, IFxx, DO, DOUxx, DOWxx, TESTN, and TESTZ instructions. Theseoperation codes are used to compare or test fields for certain conditions.Based on the result of the comparison or test, resulting indicators can beset 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 todescribe how compare and test operations take place under RPG.

When using compare and test operations, keep the following points inmind:

• When comparing numeric fields, the fields are aligned at their implieddecimal point. Fields are filled with zeros to the left and right of thedecimal point until both fields are equal in length. For example, ifa numeric field containing 1234.56 is compared to a numeric fieldcontaining 1.2, RPG fills the second field (1.2) with zeros (0001.20)until both fields are equal in length. Numeric fields cannot exceed 15characters in length.

• If alphameric fields of unequal lengths are compared, the fields arealigned at the leftmost character. Shorter fields are filled with blanksuntil the two fields are equal in length.

• RPG compares numeric fields algebraically. Positive numeric fields arealways 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 translatesalphameric fields to the alternate collating sequence before comparingthem.

• 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 CodesExternal call operation codes include the CALL, PARM, PLIST, FREE,RETRN, EXIT, and RLABL instructions. These operation codes can beused 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 providea specific, internally-defined interface for calling Migration RPGsubprograms.

• The EXIT and RLABL operation codes are provided to maintaincompatibility with other versions of the RPG II programminglanguage. They are most commonly used to provide an interface tothe MSI-supplied subroutines SUBR01, SUBR21, and SUBR23.

11.6 Internal Subroutine Operation CodesSubroutine operation codes consist of the BEGSR, ENDSR, CASxx andEXSR instructions. These operation codes are used to identify andexecute internal RPG subroutines. A subroutine is a group of Calculationspecifications that can be executed more than once in a single programcycle. When using subroutines, keep the following points in mind:

• Subroutine specifications are indicated by blanks or an SR in columns7 and 8 of a Calculation specification.

• All subroutines must appear at the end of the calculations sectionin an RPG program. The subroutine section follows the total timecalculations section.

• Subroutines cannot be defined as total time calculations, meaningthat indicators L1 - L9 cannot appear in columns 7 - 8 of subroutinespecifications. However, subroutines can be called from total timecalculations.

• Subroutines can be defined in any order.

• All subroutines must begin with a BEGSR operation and end with anENDSR operation.

• Any RPG operation other than a BEGSR or ENDSR operation can beperformed within a subroutine.

• Subroutines can call other subroutines or call themselves recursively.Using recursive subroutine calls is not recommended, as they are hardto 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 totalcalculations is permitted, but is not recommended. Branching fromoutside 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 firstexecutable 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 whichreferences a TAG in detail or total time calculations, thesubroutine will branch to that point. This type of coding is notrecommended.

— If the subroutine being called is an INFSR subroutine, it will notexecute a normal return when its ENDSR statement is processed.INFSR subroutines are exception handling subroutines and arediscussed in detail in the Migration RPG Screen Format ReferenceManual.

• Up to 9,999 internal subroutines can be defined in a program.

11.7 Move Operation CodesMove operation codes include the MOVE, MOVEA, and MOVELinstructions. MOVE operations transfer data from a field in factor 2to the result field. Factor 1 is always blank in a move operation andresulting indicators are not allowed. When using move operations, thefollowing 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 moveoperation. If the data 387.6 is moved to a field defined as having twodecimal positions, the result of the move will be 38.76.

• Data transfer in a move operation begins with the rightmost characterof factor 2 to the rightmost character of the result field.

• If the result field is not large enough to accommodate factor 2, RPGmoves 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 leftmostcharacters of the result field are not changed.

• When moving numeric data, the sign of the result field is the same asthe sign of factor 2.

• When moving an alphameric field to a numeric field, the digit portionof each character is converted to its corresponding numeric characterand then moved to the result field. The zone portion of the rightmostcharacter is converted to its corresponding sign and then moved to therightmost character position of the numeric result field.

• The MOVEA operation allows data to be transferred from an arrayto a field, a field to an array, or between arrays. When using theMOVEA operation code, arrays are treated as one contiguous field. Ifan array element is specified, it indicates the beginning position of thetransfer in the array. Several contiguous array elements can be movedto a single field or a single field can be moved to several contiguousarray elements. Array element boundaries are ignored in a MOVEA

11–5

Operation Codes

operation. Therefore, movement of data can end in the middle of anarray element.

• A MOVEL operation transfers the contents of factor 2 to the resultfield from left to right. It begins the transfer with the leftmostcharacter of factor 2, moving it to the leftmost character of the resultfield. If the result field is larger than factor 2, the rightmost charactersin the result field will be unaffected by the move operation.

11.8 Move Zoned Operation CodesMove zoned operation codes include the MHHZO, MHLZO, MLHZO, andMLLZO instructions. These operations move only the zone portion of acharacter. When using move zone instructions, keep the following pointsin mind:

• When moving high zone, the field involved must always be alphameric.

• When moving low zone, the field involved can be either alphameric ornumeric.

11.9 Programmed Input and Output Operation CodesProgrammed 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 outputcycle, 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 CodesSET operation codes consist of the SETON and SETOF instructions.These operation codes turn the indicators specified in columns 54 - 59 onor 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 operationdoes not set on lower control break indicators.

• If the last record indicator (LR) is set on at total time, processing stopsafter RPG finishes total time output operations.

• If the last record indicator (LR) is set on at detail time, processingstops after RPG finishes the next total time output operation.

• If halt indicators are set on and then are not set off before RPGfinishes detail time output operations, processing stops. The user isgiven the option of clearing each set halt indicator and continuingprocessing or terminating the program.

• Control level (L1 - L9) and record identifying indicators are alwaysturned off at the end of detail output operations.

11–6

Operation Codes

• Record identification and field indicators defined in the Inputspecifications are turned on or off based on the contents of each newinput record. Previous settings of these indicators are ignored.

• Command key indicators (KA - KN, KP - KY) are turned off each timea read operation is issued to a workstation file.

• If an 01 - 99 indicator is set in the Calculation specifications andis not used in the Input specifications as a record identifying orfield indicator, it remains set until changed by another Calculationspecification.

11.11 Structured Operation CodesStructured operation codes include the CASxx, DO, DOUxx, DOWxx,IFxx, ANDxx, ORxx, ELSE, and END instructions. These operationcodes allow a series of instructions to be performed one or more timesduring a single program cycle, conditional execution of instructions, andconditional branching to subroutines. Structured operations have thefollowing characteristics:

• The CASxx (Case) instruction permits conditional branching to asubroutine based on the results of the comparison of factor 1 andfactor 2.

• The DO operation executes a series of instructions one or moretimes based on a start value, end value, and increment value. Theinstruction set, bound by the DO and END statements, are performeduntil the start value exceeds the end value. After each pass throughthe Do Loop, the start value is incremented by the increment value. Ifthe end value exceeds the start value when the DO operation is firstencountered, none of the instructions within the DO construct will beperformed.

• The DOUxx (Do Until) operation executes a set of instructions one ormore times based on the relation between the contents of factor 1 andfactor 2. A DOUxx construct is always performed at least once.

• The DOWxx (Do While) operation executes a set of instructions oneor more times based on the relation between the contents of factor 1and factor 2. If the relationship between factor 1 and factor 2 is notsatisfied, the DOWxx operation is not performed.

• The IFxx and ELSE operations allow code to be conditionally executedbased 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 operationsinstruction sets. In the case of the Do Loop, it is also used to definethe increment value.

11–7

Operation Codes

• The xx portion of the CASxx, IFxx, ANDxx, ORxx, DOUxx, and DOWxxinstructions identifies the type of comparison operation that is to takeplace. The comparison operation can be:

— GT (Greater Than) - Comparison is true if factor 1 is greater thanfactor 2.

— LT (Less Than) - Comparison is true if factor 1 is less than factor2.

— GE (Greater Than or Equal) - Comparison is true if factor 1 isgreater than or equal to factor 2.

— LE (Less Than or Equal) - Comparison is true if factor 1 is lessthan 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 tofactor 2.

— Blanks (Unconditional - CASxx operation only) - The CASxxinstruction allows for the unconditional execution of a CASxxstatement by leaving the comparison code blank. An unconditionalCASxx statement will always execute. Unconditional CASxxstatements are usually placed at the end of a case construct.

• A structured operation code, the statements following it, and its ENDstatement form a structured construct. Structured constructs have thefollowing characteristics:

— Structured constructs can be nested.

— When a structured construct completes execution or if a structuredconstruct is bypassed, execution of the program resumes at thestatement immediately following the structured construct’s ENDstatement.

— Structured constructs cannot be split between detail timecalculations, total time calculations, and subroutines. A structuredconstruct must begin and end within the same set of calculationspecifications.

— Branching into a structured construct may produce unpredictableresults.

— CASxx constructs can only contain CASxx statements.

11.12 OPERATION CODESThe remaining sections in this chapter describe each Migration RPGoperation 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

9−17 18−27 33−42 43−48 56−57 58−59

ADD Required Opt Opt Opt

7−8

Optional

28−32

Required

54−55

OptOpt

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 sumis placed in the result field.

Factor 2 is required. If factor 1 is not present, factor 2 is added to theresult 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 beused 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 beforeperforming any arithmetic operation. Results of an arithmetic operationare aligned on the decimal point in the result field, which can causetruncation on both ends of a result. More information on arithmeticoperations 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 512345678901234567890123456789012345678901234567890123456789

C*C FLD1 ADD 1 FLD2

In this example, the constant 1 is added to FLD1 and the result is placedin FLD2.

Example 11–2 ADD Operation Code Usage - 1 operand

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C ADD 1 CNT

In this example, the constant 1 is added to the field CNT and the result isplaced in CNT.

Example 11–3 ADD Operation Code Usage - Indicator controlled

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C N10 CASH ADD INTRST SUM

In this example, the ADD operation is only carried out if indicator 10 isnot on. If processed, the operation will add the field INTRST to the fieldCASH, placing the result in SUM.

11–10

Operation Codes

11.12.2 - ANDxx Operation (Complex Conditional Operation)


9−17 18−27 33−42 43−48 56−57 58−59

Blk Blk Blk

7−8

Required

28−32

Required

54−55

Blk BlankOpt ANDxx

Description

The ANDxx operation allows a more complex conditional operation to bespecified in DOUxx (Do Until), DOWxx (Do While), and IFxx operations.Fields specified in the ANDxx operation are compared and return a trueor false condition to the program. The true/false condition is used by theprogram to determine if the structured construct of which the ANDxxoperation 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 beconsistent 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 datatypes of both fields must match, meaning that both fields must be eitheralphameric or numeric.

The comparison carried out in an ANDxx operation follows standard RPGcomparison rules. These rules are discussed earlier in this chapter inSection 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 followinginstructions:

• GT (Greater Than) - Comparison is true if factor 1 is greater thanfactor 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 greaterthan or equal to factor 2.

• LE (Less Than or Equal) - Comparison is true if factor 1 is less than orequal 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 availableearlier in this chapter in Section 11.11.

Example 11–4 ANDxx Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C TRICK DOUEQ4C STER ANDLTJOKE

.

.

.C END

In this example, the ANDxx operation is being used in conjunction withthe DOUxx operation. The DOUxx loop in this example will be performeduntil 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)


9−17 18−27 33−42 43−48 56−57 58−597−8

Required

28−32 54−55

Blnk Blank Blank Blank BlankOpt BEGSR Blank

Description

The BEGSR operation indicates the beginning of an internal subroutine.

Rules

The BEGSR operation must be the first specification in an internalsubroutine.

The entry of SR in columns 7 and 8 is optional. Conditional indicators arenot allowed.

Factor 1 contains the name of the subroutine. The name can be 1 to6 characters long and must begin with an alphabetic character. Validcharacters in a subroutine name are A - Z, 0 - 9, $, and _ (underscore).Each subroutine name within a program must be unique; it cannotduplicate another subroutine name, a TAG label, a ENDSR label, a CALLroutine name, or a PLIST label.


See Section 11.6 earlier in this chapter for more information on coding andexecuting internal subroutines.

Example 11–5 BEGSR Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*CSR SBGT BEGSR

.

.

.CSR ENDSR

In this example, the BEGSR operation is used to define the internal RPGsubroutine SBGT. Note the use of the SR indicator in columns 7 - 8. Useof this indicator is optional. Using it makes the subroutine section in anRPG program easier to identify.

11–13

Operation Codes

11.12.4 - BITOF Operation (Bit Off)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt BITOF Blank

Description

The BITOF operation sets the bits specified in the mask in factor 2 off (to0) in the result field.

Rules


Factor 1 must be blank.

Factor 2 can contain a literal bit mask or a single-character, alphamericfield which contains the bit mask used by the BITOF operation. A literalbit mask identifies the bits as 0 through 7, with 0 as the leftmost bit. Thebit 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 morethan 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 fieldname 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 isnot a single character field or literal bit mask, a compilation error willoccur.

The result field should be a single-character, alphameric field, table,or array element. Bit operations are only designed to work on singlecharacter alphameric fields. The bits specified in factor 2 will be set off inthe result field. The remaining bits in the result field will be unaffected.


Example 11–6 BITOF Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C N66 BITOF’0125’ ESC 1C 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 operationsto create the escape character (hex 1B). Note that these instructions willonly be executed if indicator 66 is off. The field ESC is being defined in theCalculation specifications as a 1-character alphameric field (1 in column51, blank in column 52).

11–15

Operation Codes

11.12.5 - BITON Operation (Bit On)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt BITON Blank

Description

The BITON operation sets the bits specified in the mask in factor 2 on (to1) in the result field.

Rules



Factor 2 can contain a literal bit mask or a single-character, alphamericfield which contains the bit mask used by the BITON operation. A literalbit mask identifies the bits as 0 through 7, with 0 as the leftmost bit. Thebit 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 morethan 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 fieldname are set on in the result field. If an array element is specified, eachelement in the array must be a single-character field. If factor 2 is not asingle 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 singlecharacter alphameric fields. The bits specified in factor 2 will be set on inthe result field. The remaining bits in the result field will be unaffected.


Example 11–7 BITON Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C BITON’3467’ ESC 1C BITOF’0125’ ESC

This example demonstrates the use of the BITON and BITOF operationsto create the escape character (hex 1B).

11–16

Operation Codes

11.12.6 - CABxx Operation (Compare and Branch)


9−17 18−27 33−42 43−48 56−57 58−59

Optional Opt Opt Opt

7−8

Required

28−32

Required

54−55

OptOpt CABxx

Description

The Compare and Branch operation allows a program to conditionallybranch to a TAG based on the results of the comparison of factor 1 andfactor 2.

Rules


Factor 1 and factor 2 are both required. They can contain a literal,figurative constant, field, array element, table element, or data structureelement. The data types of both fields must match, meaning that bothfields must be either alphameric or numeric.

The xx portion of the CABxx operation can be one of the followinginstructions:







• blank - If a TAG has been specified in the result field, a branchoperation is executed independent of the compare. If no entry ispresent in the result field, the CAB operation functions like a compare.

The comparison carried out in a CABxx operation follows standard RPGcomparison rules. These rules are discussed earlier in this chapter inSection 11.4. If the comparison is true, a branch to the TAG label specifiedin the result field is executed. If the comparison is false, the branch isignored and program execution continues with the next line.

An entry in the result field is optional. If an entry is present, it must be avalid label associated to a TAG or ENDSR statement. If the result field isempty, at least one resulting indicator must be specified and the operationis 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 asubroutine.

Branching from one part of the RPG logic cycle to another is notrecommended. It can be very confusing and lead to infinite loops andother problems.

Example 11–8 CABxx Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C FLDA CABLEFLDB TGLE 040506

.

.

.C TGLE TAG

The CABxx operation in this example will cause the program to branchto the tag TGLE if FLDA is less than or equal to FLDB. Note the use ofoptional resulting indicators. These indicators will be set based on theresults of the comparison carried out by the CABxx operation. In thisexample, if FLDA contains 7 and FLDB contains 12, indicator 05 will beturned on and the program will branch to the TGLE tag.

11–18

Operation Codes

11.12.7 - CALL Operation (Calling RPG Subprograms)


9−17 18−27 33−42 43−48 56−57 58−59

CALL Optional Opt Opt

7−8 28−32

Required

54−55

Opt BlankOpt Blank

Description

The CALL operation transfers control to the RPG subprogram or externalroutine specified in factor 2. This operation code is used primarily to callRPG subprograms.

Rules


The CALL operation transfers control to a subprogram much as theBEGSR operation code transfers control to an internal subroutine. Factor2 must contain an alphameric literal or a field defined by the EXTRNoperation code that names the subprogram. This can be a valid OpenVMSprogram name. Factor 2 cannot be an array element or data field name.The program specified in factor 2 can be written in any OpenVMSprogramming language, including Migration RPG. When specifying aprogram name which exceeds 8 characters, use the EXTRN operation codeto define a field which represents the program name.

The result field can contain the name of the parameter list associatedwith a PLIST operation code. This enables the calling program to shareparameters with the subprogram. Individual parameters can also bespecified immediately following the CALL operation code using the PARMoperation code. Both the PLIST option and PARM statements can be usedtogether with the CALL operation code.

Factor 1, half adjust, and the resulting indicator in columns 54 and 55must be blank. Any valid resulting indicator can be specified in columns56 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 beset on if the subprogram is a Migration RPG program and exits with theLR indicator set.

Operation

While the CALL operation can call any type of subprogram or systemservice, it is specifically designed to call Migration RPG subprograms andis generally used for this purpose. It has been designed to make MigrationRPG compatible with advanced versions of RPG II.

11–19

Operation Codes

Example 11–9 CALL Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C CALL ’MAMMAL’ 23C PARM FOXC PARM BATC PARM WEASELC 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 fieldsand return their updated values to the calling program. After thesubprogram MAMMAL is processed, control returns to the next executablestatement following the last PARM statement. Indicator 23 will be set onif MAMMAL should exit with an error status set.

11–20

Operation Codes

11.12.8 - CASxx Operation (Case)


9−17 18−27 33−42 43−48 56−57 58−59

Required Opt Opt Opt

7−8

Optional

28−32

Optional

54−55

OptOpt CASxx


9−17 18−27 33−42 43−48 56−57 58−59

END

7−8 28−32 54−55

Blnk Blank Blank Blank Blank BlankOpt Blank

Description

The CASxx operation allows an internal subroutine to be conditionallyselected for execution.

Rules


Factor 1 and factor 2 are both required in all CASxx operations exceptwhen the xx portion of the CASxx operation code is blank. They can beeither field or literal data. Factor 1 and factor 2 must both contain eitheralphameric or numeric data.

The result field is required. It must contain the name of a validsubroutine. 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 RPGcomparison rules. These rules are discussed earlier in this chapter inSection 11.4.

The xx portion of the CASxx operation can be one of the followinginstructions:





11–21

Operation Codes



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


Resulting indicators (columns 54 - 59) are optional. If resulting indicatorsare specified in an unconditional CASxx operation, factor 1 and factor 2must be present.

Conditional indicators are not allowed on the END statement terminatinga CASxx construct.

Operation

When a subroutine is called by a CASxx operation, control is returned tothe line following the END statement associated to the CASxx constructwhen the subroutine completes execution.

Example 11–10 CASxx Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C HOME CASGTVISTOR WINC HOME CASLTVISTOR LOSSC HOME CASEQVISTOR TIEC END

In this example, the CASxx operation is used to select a subroutine basedon the comparison of the HOME and VISTOR fields. If HOME is greaterthan VISTOR, subroutine WIN will be executed. If HOME is less thanVISTOR, 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 512345678901234567890123456789012345678901234567890123456789

C*C SCORE CASLTAVERAG BADC SCORE CAS AVERAG UPDATE 04 05C END

In this example, the CASxx operation is used to conditionally executethe subroutine BAD if SCORE is less than AVERAG. Otherwise,the unconditional CASxx operation (xx is blank) will ensure that thesubroutine UPDATE is executed. Note the use of the optional resultingindicators on the unconditional CASxx operation. Indicator 04 will beturned on if SCORE is greater than AVERAG. Indicator 05 will be turnedon if SCORE is equal to AVERAG.

11–23

Operation Codes

11.12.9 - CHAIN Operation


9−17 18−27 33−42 43−48 56−57 58−59

Opt Opt

7−8

Required

28−32

Required

54−55

Opt Blank BlankOpt CHAIN

Description

The CHAIN operation reads a record by key from a file during calculationsand makes the contents of the record available to the program. A CHAINoperation can read records from a sequential, relative, or indexed file.

Rules


Factor 1 is required. It contains the relative record number or key field tobe used to access the chained file. Data structure elements can be used tospecify non-contiguous keys.

Factor 2 is also required. It must contain the name of the file from whichthe 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 bedefined in the program’s File Description specifications.

The result field must be blank.

A resulting indicator in columns 58 - 59 is not allowed. A resultingindicator in columns 54 - 55 is optional for chained files and required forfull-procedural files. This indicator serves as a record-not-found indicatorand will be turned on if the record requested is not found.

A resulting indicator in columns 56 - 57 is optional. If specified, it servesas an error indicator, turning on if the record requested by the CHAINoperation cannot be accessed. If this indicator is turned on, the record-not-found indicator will also be turned on. The $STAT$ field will contain thecompletion status of a CHAIN operation.

If a record-not-found or error indicator is not specified on a CHAINoperation 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 theFile Description specifications, all CHAIN operations associated to that fileshould 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 accessit and an error indicator has not been declared in columns 56 - 57, anerror message will be displayed at the terminal. The program will waitapproximately 5 minutes for the record to be freed. If it is not freed withinthis 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 keyspecified 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 indicatorsassociated with the record read remain on for the rest of the cycle.

If multiple CHAIN operations are performed against the same file duringa single program cycle, only the last record read can be updated at outputtime. The EXCPT operation can be used to update records during thecalculation portions of the program cycle.

Example 11–12 CHAIN Operation Code Usage - Relative file

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

H00010FINP IP F 80 80 DISK00020FOUT OC F 52 52R DISK00030FRPT O F 80 80 PRINTER00040IINP AA 0200050I 1 50TAXNUM00060I 1 52 RECORD00070C*00080C 02 TAXNUM CHAINOUT 9900090C*00100OOUT D 02 9900110O RECORD 5200120ORPT D 0200130O RECORD 5200140O 99 70 ’ADDED’00150O N99 70 ’DUPLICATE’

This program scans a file for duplicate records. The CHAIN operation isused to chain into the relative file OUT to determine if the record readfrom the file INP is present in the OUT file. The field TAXNUM containsthe 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 columns54 - 55. If 99 is on after the CHAIN, the INP record is added to the OUTfile. If 99 is off after the CHAIN, the record already exists in the OUT fileand 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 512345678901234567890123456789012345678901234567890123456789

F*FIDXMST UC F 57 57R 5AI 1 DISK

.

.

.C KEY CHAINIDXMST 9899C 99 $STAT$ CASEQ’000181B0’LCKERRC 99 CAS GENERRC END

In this example, the CHAIN operation is being used to access an indexedfile. 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 theCHAIN 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 lockerror, the subroutine GENERR is executed.

11–26

Operation Codes

11.12.10- COMP Operation (Compare)


9−17 18−27 33−42 43−48 56−57 58−59

COMP One required

7−8

Required

28−32

Required

54−55

Opt BlankOpt

Description

The COMP operation compares factor 1 and factor 2, setting resultingindicators based upon the results of the comparison.

Rules


Factor 1 and factor 2 are both required. They can contain a literal,figurative constant, field, array element, table element, or data structureelement. The data types of both fields must match, meaning that bothfields must be either alphameric or numeric.


At least one resulting indicator (columns 54 - 59) must be specified. Theseindicators 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 beforethe operation begins.

The comparison carried out in a COMP operation follows standard RPGcomparison rules. These rules are discussed earlier in this chapter inSection 11.4.

If an alternate collating sequence has been specified, alphameric fields aretranslated 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 512345678901234567890123456789012345678901234567890123456789

C*C CODE COMP 24 11

In this example, the COMP operation is used to compare the field CODEto the numeric literal 24. If CODE is equal to 24, indicator 11 will beturned on.

Example 11–15 COMP Operation Code Usage - Greater than or equal

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C CODE COMP 3 12 11

In this example, the COMP operation is used to compare the field CODEto the numeric literal 3. If CODE is greater than 3, indicator 12 will beturned 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 512345678901234567890123456789012345678901234567890123456789

C*C CODE COMP KEY 1313

In this example, the COMP operation is used to compare the field CODE tothe field KEY. If CODE is less than or equal to the field KEY, the indicator13 will be turned on.

Example 11–17 COMP Operation Code Usage - Greater than, Less than,Equal

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C 01 CODE COMP CUP 203040

In this example, the COMP operation is used to compare the field CODEto 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 toCUP, indicator 40 is turned on. Note that indicator 01 must be on beforethis command will be executed.

11–28

Operation Codes

11.12.11- DEBUG Operation


9−17 18−27 33−42 43−48 56−57 58−59

Optional

7−8

Optional

28−32

Required

54−55

Opt Blank BlankOpt DEBUG Blank

Description

The DEBUG operation code is provided to assist the programmer indebugging RPG programs. It is especially useful as Migration RPG doesnot 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 incolumn 15 of the Control (H) specification. If column 15 is blank, all debugfiles 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 definedin the File Description specifications. A program can contain multipleDEBUG 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, arrayelement, table element, or data structure element. The contents of factor 1are output to the debug file. Factor 1 is most commonly used to output aliteral which can serve as a tag to indicate the section of code the programis processing or which serves as a label to identify the contents of theresult field.

Factor 2 is required. It must contain the name of the debug file as itappears in columns 7 - 14 of the File Description specification. The filemust be an output file.

The result field is optional. It can contain a field name, array, arrayelement, table element, or data structure element. The contents of theresult 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 willfollow normal RPG rules for output. In most cases, output specificationswill not be necessary when using the DEBUG operation.

Operation

A DEBUG operation always outputs all indicators which are set at thetime the DEBUG operation code is executed.

DEBUG statements can be left in a program and turned on and off byplacing a 1 in column 15 of the Control specification. When turned off,DEBUG files and statements are ignored by the compiler and are notincluded in the executable image. To turn debug on, a 1 must be placed incolumn 15 of the Control specification and the program must be recompiledand relinked.

The DEBUG operation code is useful for checking the contents of fieldsand tracking a program through its cycle.

After debugging a program with the DEBUG operation code, don’t forgetto turn debug off by blanking out column 15 in the Control specificationand recompiling and relinking the program. Otherwise, the program willcontinue to produce DEBUG files each time it is run.

11–30

Operation Codes

Example 11–18 DEBUG Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

** 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 PRINTERF* file. A DEBUG file can also be defined as aF* DISK file. DEBUG files are always defined asF* output files.F*FERROR O 80 PRINTER

.

.

.C* This DEBUG operation will print the literalC* ’START’, the contents of the field NAME, andC* all indicators currently set in the DEBUG fileC* ERROR.C*C ’Start’ DEBUGERROR NAME

.

.

.C* The first DEBUG operation in this section willC* output the literal ’ACCNT’ and the contents ofC* the field ACCNT and all indicators currentlyC* set to the DEBUG file ERROR. The second DEBUGC* operation will output the label ’END’ and allC* of the indicators currently set to the DEBUGC* file ERROR.C*C ’ACCNT’ DEBUGERROR ACCNTC ’End’ DEBUGERROR

Example 11–19 DEBUG Output

DEBUG = Start INDICATOR ON = L0 01 03FIELD VALUE = MICHAELDEBUG = ACCNT INDICATOR ON = L0 01 03 22FIELD VALUE = 12439DEBUG = End INDICATOR ON = L0 01 03 22DEBUG = Start INDICATOR ON = L0 01 03FIELD VALUE = GEORGE

.

.

.DEBUG = ACCNT INDICATOR ON = L0 22 45 LRFIELD VALUE = 97983DEBUG = End INDICATOR ON = L0 22 45 LR

This is an example of what the output to a DEBUG file using theinstructions from the previous example might look like.

11–31

Operation Codes

11.12.12- DEFN Operation (Field Definition)


9−17 18−27 33−42 43−48 56−57 58−59

DEFN Required

7−8 28−32

Required

54−55

Blnk *LIKE Blank BlankOpt Blank

Description

The Field Definition operation allows the programmer to define data fieldsbased 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 providesthe attributes for the field being defined. Factor 2 cannot be a literal ordata 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 bedefined. It cannot contain the name of an array, array element, table, ordata structure.

Entries in columns 49 - 51 (field length) are optional. They can be usedto make the field length of the entry in the result field longer or shorterthan the field length of the entry in factor 2. A plus (+) coded in column49 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 bedecreased. Entries in columns 50 - 51 indicate how much to increase ordecrease the field length. If columns 49 - 51 are left blank, the field lengthwill be the same as that of the entry in factor 2.

Increasing a numeric field beyond 15 characters or an alphameric fieldbeyond 256 characters will generate a compile time error. Decreasing afield to less than one or changing the number of decimal places defined forit will also generate a compile time error.

The number of decimal positions in a numeric field defined by a DEFNoperation cannot be changed. The new field will have the same number ofdecimal positions as the entry in factor 2.


11–32

Operation Codes

Example 11–20 DEFN Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C *LIKE DEFN TONSIL THROATC *LIKE DEFN TEETH MOUTH +08C *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 asthe field TONSIL. The second field, MOUTH, will have the same data typeas the field TEETH, but will be 8 characters longer in length. The thirdfield, FEET, will have the same data type as the field TOES, but will be 2characters shorter in length.

11–33

Operation Codes

11.12.13- DIV Operation (Divide)


9−17 18−27 33−42 43−48 56−57 58−59

DIV Required Opt Opt Opt

7−8

Optional

28−32

Required

54−55

OptOpt

Description

The Divide operation allows two numeric fields to be divided, with thequotient 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 abortwith a divide-by-zero error. If factor 1 is present, it is divided by factor2 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 theresult 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 theDIV operation.

Resulting indicators (columns 54 - 59) are optional. They can be used toindicate whether the contents of the result field after the DIV operationare positive (columns 54 - 55), negative (columns 56 - 57), or zero (columns58 - 59).

Operation

Any remainder resulting from the DIV operation will be lost unless a MVR(Move Remainder) operation immediately follows the DIV operation. SeeSection 11.12.38 for more information on the MVR operation.

Half adjust (column 53 of the Calculation specification) cannot be specifiedfor 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 512345678901234567890123456789012345678901234567890123456789

C*C 03 DISCNT DIV STKPRC PERCNT 22H

In this example, the DIV operation divides the field STKPRC into DISCNTand places the product in PERCNT. Note that PERCNT is being defined inthe Calculation specifications as a numeric field with two decimal places.Half-adjust has been specified in column 53 to round the results of theDIV 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 512345678901234567890123456789012345678901234567890123456789

C*CL1 DIV CARSTK CARPCT 22H

In this example, the field CARPCT will be divided by CARSTK and theresult placed in CARPCT. Note that this operation only takes place duringL1 control break processing.

Example 11–23 DIV and MVR Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*CL3 RIP DIV OFF SCAM 52CL3 MVR PORK 42

In this example, the field RIP will be divided by OFF, with the result beingplaced in SCAM. Any remainder from this DIV operation will be placed inthe field PORK by the MVR operation. Note that this operation only takesplace during L3 control break processing.

11–35

Operation Codes

11.12.14- DO Operation (DO Loop)


9−17 18−27 33−42 43−48 56−57 58−59

DO Optional

7−8

Optional

28−32

Optional

54−55

Opt Blank BlankOpt Blank


9−17 18−27 33−42 43−48 56−57 58−59

END

7−8 28−32

Optional

54−55

Opt Blank Blank Blank BlankOpt Blank

Description

The DO operation allows a set of operations to be performed a fixednumber of times. The DO operation code, the operation codes which followit, and the associated END operation code constitute a DO loop. The DOoperation code is considered a structured operation code.

Rules

Conditional indicators (columns 7 - 17) are optional. They can be specifiedon both the DO statement and the associated END statement. Conditionalindicators 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 theassociated END statement.

• If conditional indicators are satisfied on the DO operation, processingof the DO loop begins. Conditional indicators on a DO operation arechecked once at the beginning of the DO loop, meaning that onceconditions have been satisfied to begin execution of the DO loop, theyare not checked again as the DO loop executes.

• When execution of the DO loop operations reaches the associated ENDstatement, conditional indicators on the END statement are checked.If the conditional indicators are not satisfied, control passes out ofthe DO loop to the next executable instruction. If the conditionalindicators are satisfied, and the index value is less than the limitvalue, 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 zerodecimal places. Factor 1 serves as the start value for the DO loop. When aDO loop begins execution, the contents of factor 1 are moved to the resultfield, overriding any value which might already be in the result field. Iffactor 1 is not specified, the start value defaults to 1.

Factor 2 is optional. If specified, it must contain a numeric entry withzero decimal places. Factor 2 serves as the limit value for the DO loop. Iffactor 2 is not specified, the limit value defaults to 1.

The result field is optional. If specified, it must contain a numeric entrywith zero decimal places. The result field serves as the index value forthe DO loop. If the result field is not specified, the compiler will generatean internal index field for the DO loop. The contents of factor 1, or thestart value, are always moved to the index field when a DO loop beginsexecution.

Factor 2 on the associated END operation is also optional. If specified, itmust contain a positive numeric entry with zero decimal places. Factor2 in the END operation serves as an increment value for the DO loop. Iffactor 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 arechecked. If satisfied, the DO operation is performed. If not satisfied,control is passed to the first executable statement following theassociated END statement.

2 The starting value in factor 1 is moved to the index value in the resultfield.

3 If the index value is greater than the limit value in factor 2, control ispassed to the first executable statement following the associated ENDstatement, terminating the DO loop. Otherwise, execution of the DOloop proceeds. The comparison carried out in a DO operation followsstandard RPG comparison rules. These rules are discussed earlier inthis chapter in Section 11.4.

4 Operations within the DO loop are executed.

5 When the associated END statement is reached, its conditionalindicators are checked. If the conditional indicators are not satisfied,control passes to the next executable statement following the ENDstatement, terminating the DO loop.

6 If conditional indicators on the END statement are satisfied, the ENDoperation is performed. The increment value in factor 2 of the ENDoperation is added to the index value of the DO operation. Controlthen passes back to step 3 in the DO loop. Note that steps 1 and 2 arenot performed again, meaning that conditional indicators on the DOoperation 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 greaterthan the starting value specified in factor 1, the DO loop will neverexecute.

• Specifying a negative or zero increment value in the associated ENDoperation 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 operationswithin the DO loop to affect the termination of the DO loop. Cautionis advised when manipulating these values, as the DO loop may bethrown into an infinite loop or terminated unexpectedly if the valuesare handled incorrectly.

Example 11–24 DO Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C 22 STRT4 DO LIM4C MULT STRT4 SUBTOT 40C SETON 04C EXCPTC SETOF 04C 23 END 4

In this example, a DO loop will be executed if indicator 22 is on. It willexecute 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 incrementedby 4, which is specified as the increment value in factor 2 of the associatedEND statement.

When the DO loop is entered, if indicator 22 is off, control will pass tothe statement immediately following the END statement. If indicator 22is on, the value of STRT4 is 1, and the value of LIM4 is 20, the loop willbe executed 5 times, provided indicator 23 is on. If indicator 23 is not on,processing will continue with the statement immediately following theEND statement.

11–38

Operation Codes

11.12.15- DOUxx Operation (Do Until Loop)


9−17 18−27 33−42 43−48 56−57 58−597−8

Required

28−32

Required

54−55

Opt Blank Blank BlankOpt DOUxx Blank


9−17 18−27 33−42 43−48 56−57 58−59

END

7−8 28−32 54−55

Opt Blank Blank Blank Blank BlankOpt Blank

Description

The Do Until operation performs a set of instructions until the conditionspecified by the xx portion of the instruction is met. The DOUxx operationcode, the operation codes which follow it, and the associated ENDoperation code constitute a DOUxx loop. The DOUxx operation code isconsidered a structured operation code.

Rules

Conditional indicators (columns 7 - 17) are optional. They can be specifiedon 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,control passes to the next executable statement following theassociated END statement. If conditional indicators are satisfiedon the DOUxx operation, processing of the DOUxx loop begins.Conditional indicators on a DOUxx operation are checked once atthe beginning of the DOUxx loop, meaning that once conditions havebeen satisfied to begin execution of the DOUxx loop, they are notchecked again as the DOUxx loop executes.

• When execution of the DOUxx loop operations reaches the associatedEND statement, conditional indicators on the END statement arechecked. If the conditional indicators are not satisfied, control passesout of the DOUxx loop to the next executable instruction. If theconditional indicators are satisfied, the comparison test specified infactor 1 and factor 2 of the DOUxx operation is carried out. If thecomparison is false, control passes back to the beginning of the DOUxxloop. If the comparison is true, control passes out of the DOUxx loopto the next executable instruction.

11–39

Operation Codes

A complete description of the DOUxx loop cycle appears later in thissection.


The comparison carried out in a DOUxx operation follows standard RPGcomparison rules. These rules are discussed earlier in this chapter inSection 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 loopwill terminate.


A DOUxx construct is always executed at least one time.

The xx portion of the DOUxx operation can be one of the followinginstructions:








Operation

A DOUxx loop is executed as follows:

1 Conditional indicators (columns 7 - 17) on the DOUxx operationare checked. If satisfied, the DOUxx construct is performed. If notsatisfied, control is passed to the first executable statement followingthe associated END statement.

2 Operations within the DOUxx loop are executed.

3 When the associated END statement is reached, its conditionalindicators are checked. If the conditional indicators are not satisfied,control passes to the next executable statement following the ENDstatement, terminating the DOUxx loop. If conditional indicatorson the END statement are satisfied, the contents of the factor 1and factor 2 fields specified in the DOUxx operation are compared.(Note this comparison takes place at the end of the DOUxx loop. Ifthe conditions specified by the DOUxx operation and any associatedANDxx and ORxx operations are true, the DOUxx loop is terminated

11–40

Operation Codes

and control is passed to the next executable statement following theassociated END statement. If the conditions specified by the DOUxxoperation and any associated ANDxx and ORxx operations are false,control is passed back to step 2 in the DOUxx loop. Note that step1 is not performed again, meaning that conditional indicators on theDOUxx 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 DOUxxoperation and any associated ANDxx and ORxx operations can bemodified by operations within the DOUxx loop to affect the terminationof the DOUxx loop. Caution is advised when manipulating thesevalues, as the DOUxx loop may be thrown into an infinite loop orterminated unexpectedly if the values are handled incorrectly.

Example 11–25 DOUxx Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C INCOME DOUGTTAXESC ADD 1 WEEKC INCOME ADD PAYCHK INCOMEC END

In this example, the DOUxx loop will be executed until the field INCOMEis greater than the field TAXES.

11–41

Operation Codes

11.12.16- DOWxx Operation (Do While Loop)


9−17 18−27 33−42 43−48 56−57 58−597−8

Required

28−32

Required

54−55

Opt Blank Blank BlankOpt DOWxx Blank


9−17 18−27 33−42 43−48 56−57 58−59

END

7−8 28−32 54−55

Opt Blank Blank Blank Blank BlankOpt Blank

Description

The Do While operation performs a set of instructions until the conditionspecified by the xx portion of the instruction is no longer true. The DOWxxoperation code, the operation codes which follow it, and the associatedEND operation code constitute a DOWxx loop. The DOWxx operation codeis considered a structured operation code.

Rules

Conditional indicators (columns 7 - 17) are optional. They can be specifiedon 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,control passes to the next executable statement following theassociated END statement. If conditional indicators are satisfiedon the DOWxx operation, processing of the DOWxx loop begins.Conditional indicators on a DOWxx operation are checked once atthe beginning of the DOWxx loop, meaning that once conditions havebeen satisfied to begin execution of the DOWxx loop, they are notchecked again as the DOWxx loop executes.

• The relation between factor 1 and factor 2 on the DOWxx operationis checked. If the relation is true, execution of the DOWxx constructproceeds. If the relation is false, the DOWxx loop is terminatedand control is passed to the next executable statement following theassociated END statement.

• When execution of the DOWxx loop operations reaches the associatedEND statement, conditional indicators on the END statement arechecked. If the conditional indicators are not satisfied, controlpasses out of the DOWxx loop to the next executable instruction.

11–42

Operation Codes

If the conditional indicators are satisfied, control passes back to thebeginning of the DOWxx loop.

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


The comparison carried out in a DOWxx operation follows standard RPGcomparison rules. These rules are discussed earlier in this chapter inSection 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 loopwill execute.


The xx portion of the DOWxx operation can be one of the followinginstructions:








Operation

A DOWxx loop is executed as follows:

1 Conditional indicators (columns 7 - 17) on the DOWxx operationare checked. If satisfied, the DOWxx operation is performed. If notsatisfied, control is passed to the first executable statement followingthe associated END statement.

2 The contents of factor 1 and factor 2 are compared. As long as theconditions specified by the DOWxx operation and any associatedANDxx and ORxx operations are true, the DOWxx loop will beexecuted. If the comparison operations are false, control is passedto the next executable statement following the associated ENDstatement.

3 Operations within the DOWxx loop are executed.

11–43

Operation Codes

4 When the associated END statement is reached, its conditionalindicators are checked. If the conditional indicators are not satisfied,control passes to the next executable statement following the ENDstatement, terminating the DOWxx loop. If conditional indicators onthe END statement are satisfied, control is passed back to step 2 in theDOWxx loop. Note that step 1 is not performed again, meaning thatconditional 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 DOWxxoperation and any associated ANDxx and ORxx operations canbe modified by operations within the DOWxx loop to affectthe termination of the DOWxx loop. Caution is advised whenmanipulating these values, as the DOWxx loop may be thrown intoan infinite loop or terminated unexpectedly if the values are handledincorrectly.

Example 11–26 DOWxx Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C N10 PRINC DOWLTLOANC ADD 1 MONTHSC PAYMNT SUB INTRST PRINCC END

In this example, the DOWxx loop will not execute if indicator 10 is on. Ifindicator 10 is off, the DOWxx loop will execute as long as the value ofPRINC is less than the value of LOAN.

11–44

Operation Codes

11.12.17- ELSE Operation (IF/ELSE Operation)


9−17 18−27 33−42 43−48 56−57 58−59

ELSE

7−8 28−32 54−55


Description

The ELSE operation can be paired with an IFxx operation. It allows theprogram to execute a set of instructions if the IFxx operation conditionsare not met.

Rules

An ELSE operation must appear within the bounds of an IFxx/ENDconstruct. Only one ELSE operation can be paired with an IFxx operation.

Conditional indicators in columns 7 - 8 are optional. If used, they mustmatch the conditional indicator appearing in the associated IFxx and ENDoperations.


Factor 1, factor 2, and the result field must be blank.


Operation

In an IFxx/ELSE/END construct, the operations bound by the ELSEstatement and the associated END statement will be performed if the IFxxcondition is not true. If the IFxx condition is true, the instructions boundby the IFxx statement and the ELSE statement will be performed andthe statements bound by the ELSE statement and the associated ENDstatement will be skipped.

11–45

Operation Codes

Example 11–27 ELSE Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C GUN IFEQ LOADEDC EXSR SHOOTC ELSEC EXSR LOADC END

In this example, the subroutine SHOOT will be executed if the IFxxstatement comparing GUN and LOADED is true. If the IFxx statementis not true, control will transfer to the statements following the ELSEoperation code and the subroutine LOAD will be executed.

11–46

Operation Codes

11.12.18- END Operation

END Associated With The DO Operation Code


9−17 18−27 33−42 43−48 56−57 58−59

END

END Associated With The DOUxx And DOWxx Operation Codes

7−8

Factor 1

28−32

Optional

Result Fld

54−55

Opt Blank

33−42

Blank Blank Blank

END

END Associated With The IFxx And CASxx Operation Codes

Opt

Factor 1

Opcode Factor 2

Result Fld

Blank

9−17 18−27

Blank

43−48 56−57 58−59

END

Indicators

28−32

Factor 2

Resulting Indicators

Opt Blank

33−42

Blank Blank Blank

7−8

Opcode

54−55

9−17 18−27

Blank

43−48 56−57 58−59

Opt

28−32

Blank

Blnk Blank Blank Blank Blank

Indicators Resulting Indicators

7−8 54−55

Opt Blank

Description

The END operation is used to specify the end of a CASxx, DO, DOUxx,DOWxx, or IFxx/ELSE construct. END statements are always associatedwith 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 indicatorspecified on the structured operation code associated with the ENDstatement.

Conditional indicators in columns 9 - 17 are not permitted on ENDstatements associated with CASxx and IFxx/ELSE operations.

Conditional indicators in columns 9 - 17 are optional in END statementswhich are associated to the DO, DOUxx, and DOWxx operations. Sections11.12.14, 11.12.15, and 11.12.16 describe these operation codes and the useof conditional indicators on their associated END statements.

Factor 1, factor 2, and the result field must all be blank on all ENDoperations with the exception of the END operation associated with a DOoperation. An END operation associated with a DO operation can have anoptional entry in factor 2. See Section 11.12.14 for more information onthe END operation associated with the DO operation.

11–47

Operation Codes

Resulting indicators (columns 54 - 59) are not allowed on any ENDoperation.

Examples of END statement usage are displayed in the examplesassociated with the structured operation code descriptions. See Sections11.12.8, 11.12.14, 11.12.15, 11.12.16, and 11.12.27 for examples of ENDoperation usage.

11–48

Operation Codes

11.12.19- ENDSR Operation (End Subroutine)


9−17 18−27 33−42 43−48 56−57 58−597−8

Optional

28−32

Optional

54−55

Blnk Blank Blank BlankOpt ENDSR Blank

Description

The End Subroutine operation defines the end of an internal RPGsubroutine.

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 arenot allowed.


An entry in factor 1 is optional. Factor 1 can contain a unique labelwhich can be used by GOTO and CABxx operations within the subroutine.Branching to a label or TAG within a subroutine from outside of thesubroutine 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 FormatReference Manual for information on the coding and execution of an INFSRsubroutine.


Operation

The ENDSR operation signifies the end of an internal RPG subroutine.When it is processed, program control is returned to the first executablestatement following the EXSR or CASxx operation which called thesubroutine. The only exception to this rule is when the subroutine inquestion is an INFSR (exception) subroutine.


11–49

Operation Codes

Example 11–28 ENDSR Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*CSR COOLER BEGSR

.

.

.CSR CHIPS CABEQ0 POP

.

.

.CSR POP ENDSR

In this example, the ENDSR operation signifies the end of the internalRPG subroutine COOLER. Note the use of the label POP on the ENDSRstatement. If the condition checked by the CABxx operation within thesubroutine COOLER is true, control will branch to the label POP on theENDSR statement.

11–50

Operation Codes

11.12.20- EXCPT Operation (Exception Output Operation)


9−17 18−27 33−42 43−48 56−57 58−597−8 28−32

Optional

54−55

Opt Blank Blank Blank BlankOpt EXCPT Blank

Description

The EXCPT operation allows records to be output during detail time ortotal 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 charactername which is associated to the exception records in the Outputspecifications.

• 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 recorddefinition.

• Columns 32 - 37 in the output record definition can contain theexception name which was specified in factor 2 of the EXCPTstatement.

• Only exception records (E in column 15) can contain exception namesin columns 32 - 37.

• Overflow indicators cannot be specified in columns 23 - 31 of anexception 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 thatsatisfy 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 thatsatisfy 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 onmultiple exception output records.

Example 11–29 EXCPT Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

FFIRDAT O 128 DISKFREPORT O 80 PRINTER

.

.

.C* The following EXCPT operation is unlabeled. AllC* exception output records which do not have a labelC* in columns 32 - 37 will be processed by thisC* operation.C*C EXCPTC*C* The following EXCPT operation will only beC* executed if indicator 10 is on. It will processC* all exception output records with the label REPORTC* in columns 32 - 37.C*C 10 EXCPTREPORTC*C* The following EXCPT operation will only beC* executed if indicators 10 and 20 are on andC* indicator 30 is off. It will process allC* exception output records with the label DATAC* in columns 32 - 37.C*C 10 20N30 EXCPTDATA

.

.

.O* The following record will be output when theO* EXCPT operation labeled DATA is executed.O*OFIRDAT E DATAO LOCTN 10O DAMAGE 20*OLST H 1PO 40 ’FIRE REPORT’*O* The following record will be output whenO* the unlabeled EXCPT operation is executed.O*O EO LOCTN 20O DAMAGE 60*O* The following record will be output whenO* the unlabeled EXCPT operation is executedO* and indicator 22 is on.O*O E 22O CALTIM 10O RSPTIM 20


11–52

Operation Codes

Example 11–29 (Cont.) EXCPT Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*O* The following record will be output when theO* EXCPT operation labeled REPORT is executedO* and indicator 44 is off.O*O E N44 REPORTO TRUCKS 10O PERNSL 40

This example demonstrates the use of the EXCPT operation to output datato a disk file and a report during calculation processing.

11–53

Operation Codes

11.12.21- EXIT Operation (External Subroutine Call)


9−17 18−27 33−42 43−48 56−57 58−59

EXIT

7−8 28−32

Required

54−55


Description

The EXIT operation allows an RPG program to call an external subroutine.In Migration RPG programs, the CALL operation code can be used toaccomplish the same function. The EXIT operation code is retained byMigration RPG to maintain compatibility with other versions of RPG andto support the MSI-supplied subroutines SUBR01, SUBR21, and SUBR23.

Rules



Factor 2 is required. It must contain the name of the external subroutinewhich is to be called by the EXIT operation. If the subroutine is not oneof the MSI-supplied subroutines (SUBR01, SUBR21, or SUBR23), then thesubroutine must be linked to the RPG program.



Operation

RLABL statements can be associated to an EXIT operation. The RLABLstatements must immediately follow the EXIT operation.

An EXIT operation functions much like a CALL operation in that it passesprogram control to an external subroutine or subprogram. When theexternal routine has completed execution, it returns control to the firstexecutable statement following the EXIT/RLABL construct.

11–54

Operation Codes

Example 11–30 EXIT Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C EXIT SUBR23C RLABL MICC RLABL DATASTC RLABL LEVELC RLABL RCODE 10

This example demonstrates the use of the EXIT operation code to call theMSI-supplied message member subroutine SUBR23.

11–55

Operation Codes

11.12.22- EXSR Operation (Execute Subroutine)


9−17 18−27 33−42 43−48 56−57 58−59

EXSR

7−8 28−32

Required

54−55


Description

The Execute Subroutine operation causes program control to be passedto an internal RPG subroutine. When the subroutine has completedexecution, control is returned to the first executable statement followingthe EXSR statement.

Rules



Factor 2 is required. It must contain the name of the subroutine whichis being called. The program must also contain a BEGSR operation codewhich contains the subroutine name in factor 1.




Example 11–31 EXSR operation code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C N10 EXSR MOUNTN

.

.

.CSR MOUNTN BEGSR

.

.

.CSR ENDSR

This example demonstrates the use of the EXSR operation code to call theinternal RPG subroutine MOUNTN. Note that the EXSR operation willonly 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

9−17 18−27 33−637−8

Required

28−32

LiteralBlkBlk EXTRN

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 thevalue specified in factor 2. Factor 1 of the EXTRN operation is defined asan alphameric field. This field can only be used with the CALL and FREEoperation codes and cannot be defined elsewhere in the program.

Factor 2 is used to name the external constant. A maximum of 31characters can be used to name the constant. The constant must beenclosed in apostrophes. The constant can be a valid OpenVMS programname.

Operation

The EXTRN operation initializes the value of an alphameric field to alink-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 CALLand FREE operation codes.

11–57

Operation Codes

Example 11–32 EXTRN, CALL, and FREE Operation Code Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890

C* This example depicts the use of the EXTRN operationC* code to define the program BOEING_747_JUMBO. TheC* program FLY can then be referenced as a subprogramC* 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


9−17 18−27 33−42 43−48 56−57 58−597−8 28−32

Required

54−55

Opt Blank Blank Blank BlankBlk FORCE Blank

Description

The FORCE operation allows selection of the next file from which a recordis 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 FORCEoperation is to be executed against. The file name must match a namespecified in columns 7 - 14 of the File Description specifications of an inputor update file.



Operation

The FORCE operation can be used for primary or secondary input andupdate files. The FORCE operation cannot be used to read records fromWORKSTN or KEYBORD files.

When a FORCE operation is executed, it identifies the file from which thenext record will be read. The read is performed at the beginning of thenext program cycle. If more than one FORCE operation is executed duringthe same program cycle, all but the last are ignored.

Although FORCE operations override normal multi-file processing, theycannot override the first record selected by the program. Input of the firstrecord 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 isnot selected for processing. In this case, normal multi-file processing logicselects 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 512345678901234567890123456789012345678901234567890123456789

F*FINNMST IP 20 DISKFPARTS IS 20 DISK

.

.

.C 01 FORCEPARTS

In this example, if the indicator 01 is on, the FORCE operation will beexecuted, indicating that the next record read at the beginning of the nextRPG cycle will come from the PARTS file.

11–60

Operation Codes

11.12.25- FREE Operation


9−17 18−27 33−42 43−48 56−57 58−59

FREE Opt

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt Blank

Description

The FREE operation is used to remove an RPG subprogram from theactive 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 fielddefined by the EXTRN operation code that names the subprogram. Thiscan be a valid OpenVMS program name. Factor 2 cannot be an arrayelement or data field name. The program specified in factor 2 must be aMigration RPG program. Submitting a non-Migration RPG program to theFREE operation code will produce unpredictable results. When specifyinga program name which exceeds 8 characters, use the EXTRN operationcode to define a field which represents the program name.


An error indicator can be specified in columns 56 and 57. The errorindicator will be turned on if the FREE operation is submitted to asubprogram which has never been called or which was already freedin 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, normalprogram initialization, such as file opens and field initialization, takesplace. After that, as long as the subprogram is not terminated normally(LR indicator on) or abnormally (halt indicator on or error), each time theprogram is called, it resumes operations where it left off at the previousexit, very much like an internal subroutine. Thus, program initializationis skipped during each additional call after the first one as long as thesubprogram has not been ended and the FREE operation code has not beenexercised against it. The FREE operation code provides the programmerwith another method to place a subprogram back into its initial startingstate.

11–61

Operation Codes

Example 11–34 FREE Operation code Use

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C* This example depicts the use of the FREE operation codeC* to reinitialize the program SKI.*C CALL SKI

.

.

.C FREE SKI

11–62

Operation Codes

11.12.26- GOTO Operation (Branching Operation)


9−17 18−27 33−42 43−48 56−57 58−59

GOTO

7−8 28−32

Required

54−55


Description

The GOTO operation allows a program to pass control to a label defined bya TAG or ENDSR operation, skipping all intervening instructions.

Rules



Factor 2 is required. It must contain the label of the TAG or ENDSRoperation to which the program is to branch. A label can be 1 - 6characters long and must begin with an alpha character.



Operation

Branching using the GOTO operation must comply with the followingconditions:

• A GOTO operation can branch from any point in the detail calculationssection to any TAG in the detail calculations section.

• A GOTO operation can branch from any point in the total timecalculations section to any TAG in the total time calculations sectionwith the exception of last record calculations (LR in columns 7 - 8 ofthe Calculation specification).

• A GOTO operation can branch to any TAG or ENDSR statementwithin the confines of a subroutine.

• A GOTO operation cannot branch from the detail calculation section tothe total time calculation section, or vice versa.

• A GOTO operation cannot branch from outside a subroutine to a TAGor ENDSR within a subroutine, or vice versa.

• A GOTO operation cannot branch from outside the last recordcalculations 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 512345678901234567890123456789012345678901234567890123456789

C*C LOOP TAG

.

.

.C 10N12 GOTO LOOP

In this example, the GOTO operation is executed if indicator 10 is onand indicator 12 is off. The GOTO operation will cause the program tobranch back to the TAG operation LOOP, which was defined earlier in theprogram.

11–64

Operation Codes

11.12.27- IFxx Operation


9−17 18−27 33−42 43−48 56−57 58−59

IFxx

7−8

Required

28−32

Required

54−55



9−17 18−27 33−42 43−48 56−57 58−59

END

7−8 28−32 54−55


Description

The IFxx operation allows a set of instructions to be performed based onwhether the condition in the xx portion of the instruction is true. IFxxoperations can be combined with ANDxx and ORxx operations to make thecondition more complex. IFxx operations can also be paired with the ELSEoperation to allow an additional set of instructions to be executed shouldthe IFxx condition be false. The IFxx operation is always paired with anEND operation and is considered a structured operation code.

Rules

Conditional indicators in columns 7 - 8 are optional. If specified, the sameindicator must be used on the IFxx operation, optional ELSE operation,and associated END operation.

Conditional indicators in columns 9 - 17 are optional on the IFxxstatement. They are not allowed on associated ELSE and ENDstatements. Conditional indicators on the IFxx operation control whetherthe entire IFxx construct is executed or skipped. The complete operationof an IFxx construct is detailed later in this section.

Factor 1 and factor 2 are both required. They can contain a literal,field, array element, table element, or data structure element. The datatypes of both fields must match, meaning that both fields must be eitheralphameric or numeric. The comparison carried out in an IFxx operationfollows standard RPG comparison rules. These rules are discussed earlierin this chapter in Section 11.4.



11–65

Operation Codes

The xx portion of the IFxx operation can be one of the followinginstructions:








ANDxx and ORxx operations can be associated with an IFxx operation.All conditions in an IFxx structure must be met before the statementsimmediately following the IFxx are executed. If an ELSE operation hasbeen included in the IFxx construct, the statements immediately followingthe 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. Ifthe conditions are met, processing continues with the IFxx operation.If the conditions are not met, program control is passed to the firstexecutable instruction following the associated END statement.

• The comparison operation specified by the xx of the IFxx operationand any associated ANDxx and ORxx operations are carried out. Thefollowing actions will occur based on the results of the comparisonsand the structure of the IFxx construct:

— If the comparison operations are true, then the statementsfollowing the IFxx operation will be executed. Executionwill continue until an associated ELSE or END statement isencountered. If the statement encountered is an ELSE operation,control will pass to the first executable instruction following theassociated END statement.

— If the comparison operations are false and there is no ELSEoperation associated with the IFxx operation, control will bepassed to the first executable statement following the associatedEND statement.

— If the comparison operations are false and there is an ELSEoperation associated with the IFxx operation, control will bepassed to the first executable statement following the associatedELSE statement.

11–66

Operation Codes

Example 11–36 IFxx Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C AIR IFGT PLANEC Z-ADD1 RCODEC Z-ADDTEST MIC 40C Z-ADD1 LEVEL 10C ENDC*C TRAIN IFLE TRACKC EXSR PFC Z-ADD2 XX 141011C ELSEC EXCPTLASTC EXCPTDETAILC END

In this example, the two IFxx operations demonstrate an IFxx/END andan IFxx/ELSE/END construct. In the first IFxx operation, the Z-ADDinstructions bound by the IFxx and END statements are executed if thecontents of the field AIR are greater than the field PLANE. In the secondIFxx operation, the EXSR and Z-ADD instructions are executed if thecontents of the field TRAIN are less than or equal to the field TRACK. Ifthis condition is not true, the EXCPT instructions bound by the ELSE andEND statements will be executed.

11–67

Operation Codes

11.12.28- KEYnn Operation


9−17 18−27 33−42 43−48 56−57 58−59


7−8

Optional

28−32 54−55

Opt BlankOpt KEYnn

Description

The KEYnn operation pauses a program during calculations and allowsthe user to enter data from their terminal.

Rules

To use the KEYnn operation, a KEYBORD device must be specified in theFile Description specifications.

KEYnn operations are always directed at the terminal which invoked theprogram.

KEYnn operations should not be specified in programs that are run asbatch jobs.


Factor 1 is optional. It can contain a literal, field, table, array, or datastructure element. The contents of factor 1 will be displayed when theKEYnn operation is executed. If factor 1 is not specified, a messagemember code must be specified with the KEYnn operation code.

The nn portion of the KEYnn operation code can be blank or can specifya message member number from the User Level 1 message member file(RPGUSRLV1). If the message member corresponding to the messagenumber in the KEYnn operation code is found, the message is displayed.If the message member file is not present or no entry exists whichcorresponds to the message number specified, nothing is displayed. Ifan entry is made in factor 1 of the KEYnn operation, the message numberis 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 andreferencing message member files.


The result field is required. It must contain the name of the field which isto accept the data keyed in by the user. The result field can be a field or atable, array, or data structure element.

Resulting indicators are optional. They can be used to evaluate thecontents of the result field after the user has entered data. The possibleresults 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 thedata entered is greater than zero.

56 - 57 Minus If the result field is numeric, the indicator is turned on if thedata entered is less than zero.

58 - 59 ZeroorBlank

If the result field is numeric, the indicator is turned on if thedata entered is equal to zero.

If the field is alphameric, the indicator is turned on if the resultfield contains non-blank characters.

Operation

The KEYnn operation pauses the program and accepts input from theuser. The input is placed in the field specified in the result field of theKEYnn statement. A KEYnn operation is terminated by pressing one ofthe following keys:

• Return or Enter - For a numeric field, enters the field as a positivenumber. 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 analphameric 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 withblanks.

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, theresult field is initialized to blanks or zeros, depending upon whether itis an alphameric or numeric field.

• The DUP key ( PF3 ) can be entered. If it is, the data currentlyresiding 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 512345678901234567890123456789012345678901234567890123456789

*FKEYIN IP F 70 70 KEYBORD

.

.

.C ’Name’ KEY NAME 10C 10 KEY12 SEXC 10 AUTO KEY CAR

In this example, the KEYnn operation is used to prompt the user to enterinformation from the terminal while the program is executing. Note theFile Description specification for a KEYBORD file. A KEYBORD file mustbe defined in the File Description specifications in order to use the KEYnnoperation.

The program will pause and display the prompt ’Name’ when it executesthe first KEYnn operation in the example. Any input entered by the userwill be placed in the NAME field. Note the use of indicator 10 in columns58 - 59. If an entry is made in the NAME field, indicator 10 will turnon. If no entry is made, indicator 10 will be turned off. The following twoKEYnn operations will only execute if indicator 10 is on.

The second KEYnn operation will display message number 12 from theUser Level 1 message member file as a prompt. It will accept input intothe SEX field.

The third KEYnn operation will display the contents of the AUTO field asa prompt. It will accept input into the CAR field.

11–70

Operation Codes

11.12.29- LOKUP Operation

Array LOKUP


9−17 18−27 33−42 43−48 56−57 58−59

One required

Optional

Table LOKUP

7−8

Required

28−32

Required

Result Fld

54−55

Opt

18−27 33−42

Blank

56−57 58−59

One required

Opt

Factor 1

LOKUP

Factor 2 Resulting Indicators

9−17 43−48

Indicators

Required

Opcode

Required

54−55

Opt

7−8 28−32

Opt LOKUP

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, datastructure element, or table name. Factor 1 serves as the search element ina LOKUP operation. If a table name is specified in factor 1, it refers to thelast element selected by a LOKUP operation, not the entire table.

Factor 2 is required. It must contain the name of the table or array onwhich the LOKUP operation is to be performed.

The result field must be blank in an array LOKUP operation. It is optionalin a table LOKUP operation. In a table LOKUP operation, the result fieldcan 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. Resultingindicators specify the type of search to be made and indicate the results ofthe 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 orarray that is greater than the search element specified in factor 1. Ifan entry fulfilling these requirements is found, the high indicator isturned on.

11–71

Operation Codes

• Less than search

In this case, an indicator is only specified in columns 56 - 57 (low).The LOKUP operation searches for the first element in the table orarray that is less than the search element specified in factor 1. If anentry fulfilling these requirements is found, the low indicator is turnedon.

• Equal to search

In this case, an indicator is only specified in columns 58 - 59 (equal).The LOKUP operation searches for the first element in the table orarray that is equal to the search element specified in factor 1. If anentry fulfilling these requirements is found, the equal indicator isturned on.

• Greater then or equal to search

In this case, indicators are specified in columns 54 - 55 (high) and58 - 59 (equal). The LOKUP operation searches for the first element inthe table or array that is greater than or equal to the search elementspecified in factor 1. If an equal entry is found, the equal indicator isturned on. If the entry is greater than the search element, the highindicator is turned on.

• Less than or equal to search

In this case, indicators are specified in columns 56 - 57 (low) and58 - 59 (equal). The LOKUP operation searches for the first elementin the table or array that is less than or equal to the search elementspecified in factor 1. If an equal entry is found, the equal indicatoris turned on. If the entry is less than the search element, the lowindicator is turned on.

• If a LOKUP operation is not successful, none of the resulting indicatorsare turned on.

Operation

In the LOKUP operation, factor 1 contains the search argument and factor2 contains the name of the table or array. The search element can be analphameric or numeric literal, a field name, an array element, or a tablename. Search arguments must be the same length and format as theentries in the table or array being searched. For example, both the searchelement and the array or table must be numeric with the same number ofdigits, or both must be alphameric with the same number of characters.

Tables and arrays should be sequenced before greater than or less thantype searches are carried out against them. Remember, the LOKUPoperation stops processing as soon as it finds an element which fulfills thesearch requirements. If the search is intended to find the highest or lowestelement in the table or array and the table or array is not sequenced, thesearch may not return the desired element. Table and array sequencingcan be indicated by an entry in column 45 of the Extension specification.

Compile-time arrays and tables are checked for correct sequencing duringprogram compilation. If the sequencing is not valid, the compiler willgenerate a fatal error.

11–72

Operation Codes

Pre-execution time arrays and tables will generate a halt if they are notin a valid sequence when being loaded during program initialization.The user is given the option of continuing or terminating the program inresponse to the halt. If the program is continued, the array or table willbe stored in an invalid sequence and may not produce the desired results.

Run-time tables and arrays cannot be checked before a program iscompiled or begins execution. If they are not in sequence, the LOKUPoperation may not produce the desired results. It is advisable to performa SORTA operation on run-time arrays before using them in a LOKUPoperation.

Resulting indicators are set off when a LOKUP operation begins. If aLOKUP operation is not successful, no resulting indicators are turned on.

If an index is used with an array in a LOKUP operation, the searchbegins at the array element specified by the index. Elements in the arraypreceding the index are not searched.

If the index used with an array in a LOKUP operation is a variable, it willbe set to the number of the array element meeting the search criteria ifsuch an element is found. If the LOKUP operation is unsuccessful, theindex variable will be set to 1.

11.12.29.1 Table Elements in a LOKUP OperationWhenever a table name is used in an operation other than as factor 2or the result field in a LOKUP operation, the table name refers to thedata placed in storage by the last successful LOKUP operation. When aprogram 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 contentsof the storage area are used as the search argument.

A table can also be used as the result field in operations other than aLOKUP operation. In this case, the contents of the storage area arereplaced by the results of the specified operation. The corresponding entryin the table is also changed. This allows the contents of a table to bemodified.

11.12.29.2 Searching Tables Using LOKUPThe LOKUP operation can search one table or two related tables. Whensearching 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 bereferenced in other RPG operations by specifying the table name. Thisarea is called the table reference field. When another LOKUP operationcompletes successfully, the new entry replaces the previous entry in thetable reference field.

11–73

Operation Codes

If a LOKUP operation against a table fails, the table reference fieldcontents 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 tablereference field.

Two related tables can be searched if the second table name is specified inthe result field of the LOKUP operation. As used here, the phrase relatedtables refers to any two tables defined in a program that contain relateddata. It does not refer to primary and secondary tables defined on a singleExtension specification.

When searching for an entry in two related tables, the LOKUP operationsearches only the table specified in factor 2. If the search condition issatisfied, the LOKUP operation places the corresponding entries from boththe table specified in factor 2 and the table specified in the result field intheir respective storage areas.

To program a search for an entry in related tables, the followinginformation 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 tablemust have as many or more entries than the table to be searched.

11.12.29.3 Searching Arrays Using LOKUPLOKUP operations for arrays are similar to those performed on tables.If the element searched for is found, the appropriate indicator is turnedon. If an indexed array is being searched and the index being used isa variable, the index is set to the number of the array element foundwhich satisfies the LOKUP operation. The result field in an array LOKUPoperation 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 arrayelements. Factor 2 contains the name of the array to be searched. Thesearch begins with the first element in the array and continues until thesearch criteria are met or the end of the array is reached. If an entryin the array matches the search criteria, then the appropriate resultingindicator is turned on. If no match is found, the resulting indicatorsremain off.

When searching an indexed array, it is possible to have the search start atthe element specified by the index. In this type of search, factor 1 containsthe search element. The search element must be the same length andformat as the array elements. Factor 2 contains the array name followedby a comma and the index number of the element within the array wherethe search is to begin. The LOKUP operation will begin searching thearray at the specified element.

11–74

Operation Codes

If a variable index is used when searching an array, it will be set to thenumber of the array element found which matches the search criteria. Ifno match is found, the array index variable is set to 1.

The resulting indicators are set or cleared during an indexed arrayLOKUP 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 512345678901234567890123456789012345678901234567890123456789

E* The elements assigned to these tables and arrayE* appear at the end of the sample code.E*E LBS 1 6 2 AE TABTUK 1 6 2 0DE TABCRD 1 6 5 D

.

.

.C PART LOKUPLBS 08 08C*C* In this example, a greater than or equal LOKUPC* is being performed against the LBS array. If anC* element in the array is greater than or equal toC* the contents of PART, indicator 08 will be turnedC* on.C*C PART LOKUPLBS,X 11C*C* In this example, a greater than search is beingC* performed against the array LBS. If the searchC* 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 theC* element specified by X. If X were 3, the LOKUPC* would begin with the element CC. If PART wereC* XX, this LOKUP would not find a match.C* Indicator 11 would not be turned on and theC* variable index X would be set to 1. If PARTC* were DD, this LOKUP would find that element 5,C* EE, was greater than DD. Indicator 11 would beC* turned on and the variable X would be set to 5.C*C CARD LOKUPTABTUK 66C*C* In this example, a less than LOKUP operation isC* performed on the table TABTUK. If the numberC* specified in the CARD field is less than an elementC* in the table, indicator 66 will be turned on andC* the element will be placed in the TABTUK storageC* area. If CARD were equal to 4, the search wouldC* be successful, indicator 66 would be turned on,C* and the element 02 would be placed in the TABTUKC* storage area.C*C CARD LOKUPTABTUK TABCRD 2123C*C* In this example, a less than or equal search isC* performed against the table TABTUK. If theC* search is successful, either indicator 21 or 23C* will be turned on and the element in the TABTUKC* table will be moved to the TABTUK storage area.C* If the search is successful, the associatedC* element in the TABCRD table will also be moved toC* the TABCRD storage area. If CARD were 11, theC* search would be successful and indicator 23C* (equal) would be turned on. The element 11 fromC* the TABTUK table would be moved to the TABTUKC* storage area and the associated element JACKC* would be moved to the TABCRD storage area.


11–76

Operation Codes

Example 11–38 (Cont.) LOKUP Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

O*** LBS ArrayAABBCCDDEEFF** TABTUK Table141312110201** TABCRD TableACEKINGQUEENJACKTRUMPFOLD

These examples use the array LBS and the table TABTUK to demonstratethe use of the LOKUP operation. The results of each operation aredescribed 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)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt MHHZO Blank

Description

The Move High Zone to High Zone operation moves the high zone of factor2 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 theentry in factor 2 to the leftmost position of the entry in the result field.

Example 11–39 MHHZO Operation Code Usage

1 2 3 41234567890123456789012345678901234567890123456789

C*C MHHZOPIT PAT

In this example, the zone portion of the leftmost character in the PIT fieldwill be moved to the zone portion of the leftmost character in the PATfield.

11–79

Operation Codes

11.12.31- MHLZO Operation (Move High Zone to Low Zone)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt MHLZO Blank

Description

The Move High Zone to Low Zone operation moves the high zone in factor2 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 theentry in factor 2 to the rightmost position of the entry in the result field.

Example 11–40 MHLZO Operation Code Usage

1 2 3 41234567890123456789012345678901234567890123456789

C*C MHLZOSNAKE PIT

In this example, the zone portion of the leftmost character in the SNAKEfield will be moved to the zone portion of the rightmost character in thePIT field.

11–80

Operation Codes

11.12.32- MLHZO Operation (Move Low Zone to High Zone)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt MLHZO Blank

Description

The Move Low Zone to High Zone operation moves the low zone of factor 2to 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 theentry in factor 2 to the leftmost position of the entry in the result field.

Example 11–41 MLHZO Operation Code Usage

1 2 3 41234567890123456789012345678901234567890123456789

C*C MLHZOCAR WASH

In this example, the zone portion of the rightmost character in the CARfield will be moved to the zone portion of the leftmost character in theWASH field.

11–81

Operation Codes

11.12.33- MLLZO Operation (Move Low Zone to Low Zone)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt MLLZO Blank

Description

The Move Low Zone to Low Zone operation moves the low zone of factor 2to 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 theentry in factor 2 to the rightmost position of the entry in the result field.

Example 11–42 MLLZO Operation Code Usage

1 2 3 41234567890123456789012345678901234567890123456789

C*C MLLZOLAWN MOWER

In this example, the zone portion of the rightmost character in the LAWNfield will be moved to the zone portion of the rightmost character in theMOWER field.

11–82

Operation Codes

11.12.34- MOVE Operation


9−17 18−27 33−42 43−48 56−57 58−59

MOVE Required

7−8 28−32

Required

54−55


Description

The MOVE operation carries out a right-justified transfer of charactersfrom 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, tableelement, or data structure element. It cannot contain a literal.


Operation

The MOVE operation transfers data from factor 2 to the result field. Itcan 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 digitportion of each character is transferred. If the rightmost character infactor 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 therightmost character in factor 2 and transfers it to the rightmost positionin the result field. If the result field is smaller than factor 2, the leftmostcharacters of factor 2 will not be moved. If the result field is larger thanfactor 2, the leftmost characters of the result field will be unaffected by themove.

11–83

Operation Codes

Example 11–43 MOVE Operation Code Usage

1 2 3 41234567890123456789012345678901234567890123456789

C*C MOVE PORTER HOUSE

In this example, the contents of the field PORTER are moved to the fieldHOUSE. The table following the code example depicts the results of theMOVE operation for different field sizes.

Table 11–1 Examples of MOVE Operation Results

Factor 2 Result Field

FieldSize Contents

FieldSize 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)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt MOVEA Blank

Description

The Move Array operation carries out a left-justified transfer of alphamericdata from factor 2 to the result field. It is used to transfer data in and outof arrays.

Rules



Factor 2 is required. It can contain a literal, figurative constant, field,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 elementsto a single field, move a single field to several contiguous array elements,or move contiguous array elements from one array to another. Transfer ofdata 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 beginswith the leftmost character of the first element in the array.

• If an indexed array is specified in factor 2, transfer of data begins withthe leftmost character of the element specified by the index.

• If a data field is specified in factor 2, transfer begins with the leftmostcharacter of the field.

• If a non-indexed array is specified in the result field, placement oftransferred data begins with the leftmost character of the first elementin the array.

• If an indexed array is specified in the result field, placement oftransferred data begins with the leftmost character of the elementspecified by the index.

• If a data field is specified in the result field, placement of thetransferred data begins with the leftmost character of the field.

11–85

Operation Codes

The number of characters transferred in a MOVEA operation isdetermined by the shorter of the two elements specified in factor 2 andthe result field. Element lengths are determined as follows:

• If a non-indexed array is specified, the length of the entire array isused as the field length.

• If an indexed array is specified, the length of the array from theelement specified by the index to the end of the array is used as thefield 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 theresult field.

If the field length of factor 2 is greater than the field length of the resultfield, the excess rightmost characters in factor 2 are not moved. If the fieldlength of the result field is greater than the field length of factor 2, therightmost 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 arrayelement.

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 iscarried out properly.

If a figurative constant (*BLANK, *BLANKS, *ZERO, or *ZEROS) isspecified in factor 2 of a MOVEA operation and the result field contains anarray, the following actions are possible:

• If the array is non-indexed, the data transfer will begin with theleftmost character of the first element of the array and the entirearray will be blank or zero-filled.

• If the array is indexed, the data transfer will begin with the leftmostcharacter of the array element specified by the index and theremainder of the array will be blank or zero-filled. Array elementsto the left of the index will not be affected.

Figurative constants cannot be specified in the result field of a MOVEAoperation.

11–86

Operation Codes

Example 11–44 MOVEA Operation Code Usage - Setup

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*E ALPHA1 5 2E ALPHA2 5 2E NUM 5 3 0

.

.

.C MOVE ’XXXX’ FLDA 4C MOVE ’9999999’ FLDN 70

.

.

.** ALPHA1 array elementsAABBCCDDEE** ALPHA2 array elementsGGHHIIJJKK** NUM array elements111222333444555

The following examples depict the use and results of the MOVEAoperation. Example 11–44 shows the array and field definitions usedin the examples.

Example 11–45 MOVEA Operation Code Usage - Array to Array(Alphameric)

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*C MOVEAALPHA1 ALPHA2

In this example, the contents of the array ALPHA1 are moved to the arrayALPHA2.

Table 11–2 Results of MOVEA operation in Example 11–45

Contents of ALPHA2 ArrayBefore After

GGHHIIJJKK AABBCCDDEE

11–87

Operation Codes

Example 11–46 MOVEA Operation Code Usage - Array to Field(Alphameric)

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*C MOVEAALPHA2 FLDA

In this example, the contents of the array ALPHA2 are moved to the fieldFLDA.


Contents of FLDABefore After

XXXX GGHH

Example 11–47 MOVEA Operation Code Usage - Field to Array(Numeric)

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*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 ArrayBefore After

111222333444555 111222999999955

11–88

Operation Codes

11.12.36- MOVEL Operation (Move Left)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32

Required

54−55

Opt Blank Blank BlankOpt MOVEL Blank

Description

The Move Left operation transfers the contents of factor 2 to the resultfield. The transfer begins with the leftmost character of factor 2 to theleftmost character of 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, tableelement, 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, asopposed to the right-justified transfer carried out by a MOVE operation.There are three basic types of MOVEL operations, each of which is basedon the lengths of the elements in factor 2 and the result field. TheseMOVEL operations are summarized in the following paragraphs.

In a MOVEL operation where the field length of factor 2 is equal to thefield length of the result field, the following rules apply:

• If factor 2 and the result field are both alphameric fields, all charactersare transferred.

• If factor 2 and the result field are both numeric, all digits aretransferred and the sign of factor 2 becomes the sign of the resultfield.

• If factor 2 contains numeric data and the result field is alphameric, allcharacters are transferred. The result field will contain only numericcharacters; 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 rightmostcharacter of factor 2 is a J through R or {, the sign of the result fieldwill be negative.

In a MOVEL operation where the field length of factor 2 is longer than thefield length of the result field, the following rules apply:

• If factor 2 and the result field are both alphameric, only the number ofcharacters needed to fill the result field are transferred.

• If factor 2 and the result field are both numeric, only the number ofdigits needed to fill the result field are transferred. The sign of factor2 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 aretransferred. 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 tothe result field. The zone portion of the rightmost character in factor2 is used to determine the sign of the result field. If the rightmostcharacter of factor 2 is a J through R or {, the result field will beconsidered negative.

In a MOVEL operation where the field length of factor 2 is shorter thanthe field length of the result field, the following rules apply:

• If factor 2 contains either numeric or alphameric data and the resultfield is numeric, the digit portion of each character in factor 2 istransferred 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 theresult field is alphameric, the data is transferred into the resultfield beginning with the leftmost character position. The rightmostcharacter positions in the result field remain unchanged.

11–90

Operation Codes

Example 11–48 MOVEL Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C MOVE ’HOTSPOT’ SUN 7

.

.

.C MOVEL’ICE’ SUNC MOVE ’CUBE’ SUN

This example depicts the use of the MOVEL operation code. The fieldSUN (a 7-character alphameric field) is defined and initialized in theCalculation specifications by a MOVE operation. It is initialized with thevalue ’HOTSPOT’. Later in the program, the value of the field SUNis changed by a MOVEL and a MOVE operation. After the MOVELoperation, the contents of the field SUN will be ’ICESPOT’. The MOVELoperation replaces the leftmost three characters of the field SUN withthe literal ’ICE’. After the MOVE operation, the field SUN will contain’ICECUBE’. The MOVE operation replaces the rightmost four charactersof the SUN field with the literal ’CUBE’.

11–91

Operation Codes

11.12.37- MULT Operation (Multiplication)


9−17 18−27 33−42 43−48 56−57 58−59

MULT Required Opt Opt Opt

7−8

Optional

28−32

Required

54−55

OptOpt

Description

The Multiply operation allows two numeric elements to be multipliedtogether, 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 theproduct is placed in the result field.

Factor 2 is required. If factor 1 is not present, the result field is multipliedby 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.

Resulting indicators (columns 54 - 59) are optional. They can beused 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 MULT operation.

Operation


11–92

Operation Codes

Example 11–49 MULT Operation Code Usage - 2 Operands

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C FLD1 MULT 2 FLD2

In this example, FLD1 is multiplied by the constant 2 and the result isplaced in FLD2. If the contents of FLD1 are 10, the result in FLD2 will be20.

Example 11–50 MULT Operation Code Usage - 1 Operand

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C MULT 2 CNT

In this example, the field CNT is multiplied by the constant 2 and theresult is placed in CNT. If the contents of CNT are 5 at the beginning ofthe operation, they will be 10 when the operation is completed.

Example 11–51 MULT Operation Code Usage - Indicator Controlled

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C 10 CASH MULT PERCNT INTRST

In this example, the MULT operation is only carried out if indicator 10 ison. If processed, the operation will multiply the field CASH by the fieldPERCNT, placing the result in INTRST.

11–93

Operation Codes

11.12.38- MVR Operation (Move Remainder)


9−17 18−27 33−42 43−48 56−57 58−59

MVR Required Opt Opt Opt

7−8 28−32 54−55

Opt Blank BlankOpt

Description

The Move Remainder operation moves the remainder from the Divideoperation (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 willaccept the remainder from the previous DIV operation.

Resulting indicators (columns 54 - 59) are optional. They can beused 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 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 greaterof either of the following:

1 The number of decimal positions specified for factor 1 in the associatedDIV operation.

2 The sum of the number of decimal positions specified for factor 2 andthe result field of the associated DIV operation.

The number of significant whole number positions in the remainder isequal to the number of whole number positions in factor 2 of the associatedDIV operation.

The sign of the remainder is the same as the sign of factor 1 in the DIVoperation.

Because DIV and MVR operation codes work together, it is recommendedthat the same conditional indicators be used on both operations.

11–94

Operation Codes

Half adjust (column 53 of the Calculation specification) cannot be specifiedfor a DIV operation immediately followed by an MVR operation.

Example 11–52 MVR Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C PRINC DIV MONTH PAYMNT 50C MVR RESIDL 50

In this example, the field PRINC will be divided by MONTH, with theresult being placed in PAYMNT. Any remainder from this DIV operationwill be placed in the field RESIDL by the MVR operation. If PRINCcontains 511 and MONTH contains 12, the result of the DIV operation willbe 42, which will be placed in the field PAYMNT. The MVR operation willmove the remainder of 7 into the field RESIDL.

11–95

Operation Codes

11.12.39- ORxx Operation (Complex Conditional Operation)


9−17 18−27 33−42 43−48 56−57 58−59

ORxx Blk Blk Blk

7−8

Required

28−32

Required

54−55

Blk BlankOpt

Description

The ORxx operation allows a more complex conditional operation to bespecified in DOUxx (Do Until), DOWxx (Do While), and IFxx operations.Fields specified in the ORxx operation are compared and return a trueor false condition to the program. The true/false condition is used bythe program to determine if the structured construct of which the ORxxoperation 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 beconsistent with the control level entry for the associated DOUxx, DOWxx,or IFxx operation.



The comparison carried out in an ORxx operation follows standard RPGcomparison rules. These rules are discussed earlier in this chapter inSection 11.4.

Resulting indicators are not allowed.

11–96

Operation Codes

The xx portion of the ORxx operation can be one of the followinginstructions:








Example 11–53 ORxx Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C JUGGLE DOWGT3C BALLS OREQ PINS

.

.

.C END

In this example, the Do While loop will continue to execute as long as thefield 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)


9−17 18−27 33−42 43−48 56−57 58−59

PARM Required

7−8

Optional

28−32

Optional

54−55

Blk Blank BlankOpt Blank

Description

The PARM operation is used to exchange parameters with an RPGsubprogram.

Rules

The PARM operation code is used to define parameters which will makeup a parameter list to be passed to an RPG subprogram. The PARMoperation code is used with the CALL and PLIST operation codes. PARMstatements can appear anywhere in the Calculation specifications as longas they immediately follow a CALL or PLIST statement. Up to 99,999PARM statements can follow a CALL or PLIST statement.

Conditional indicator entries (columns 9 - 17) and resulting indicatorentries (columns 54 - 59) are not permitted.

Factors 1 and 2 are optional in a PARM statement. If specified, they musthave the same data type, alpha or numeric, as the result field. A literal orfigurative constant cannot be specified in factor 1.

The result field must contain a field, data structure, array, or arrayelement name. *ENTRY PLIST parameters cannot specify array elementsusing fields as subscripts. The result field cannot contain a literal or tablename. *IN, *INxx, and *IN,xx entries are legal PARM fields, but shouldbe specified with caution as their settings reflect indicator settings. Thelength and decimal position columns (49 - 52) can be used to define theresult field.

The field specified in the result field of a PARM statement is passed bydescriptor to the RPG subprogram. The field can be manipulated andupdated by the subprogram. The subprogram then returns the updatedvalue to the calling program. If an RPG subprogram terminates with anerror, any changes made to the fields specified in the PARM statementsare still returned to the calling program. To preserve a field from changeswhen using it as a parameter, specify the field name in factor 2 of thePARM statement and declare a temporary field name in the resultfield. The contents of factor 2 will be copied to the result field whenthe subprogram is called and the contents of the field in factor 2 willremain 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 copiedto 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 initializationprocessing has run, the contents of the result fields in the *ENTRYPLIST parameters are copied to factor 1, if factor 1 is specified.Numeric fields are moved using a Z-ADD operation. Alphamericfields are right-justified and blank-filled. Errors and warnings will belogged if the parameter descriptors being passed to the called programdo not match the field types and sizes specified in the *ENTRY PLIST.

3 When the subprogram returns control to the calling program, thecontents of factor 2 in each *ENTRY PLIST parameter, if specified, arecopied to the result field. Numeric fields are moved using a Z-ADDoperation. Alphameric fields are moved using a MOVE operation. Theresult field descriptors are passed back to the calling program.

4 Upon return to the calling program, the contents of the result fieldsare copied to factor 1, if factor 1 was specified. Numeric fields aremoved using a Z-ADD operation. Alphameric fields are moved using aMOVE operation.

Parameter fields are passed as fixed-length descriptors. The structure ofthese 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 RPGprograms, 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 lengthof the field. Migration RPG will only accept binary fields 2 and 4 bytes inlength.

Fields in a Migration RPG program default to the following descriptortypes when passed as parameters in a PARM statement.

Table 11–6 Default Descriptor Types

Element type Definition Description Type

Array AlphamericNumeric: Zoned-decimal, trailingnumeric, packed, binary

AlphamericAlphameric

DSC$K_DTYPE_TDSC$K_DTYPE_T

Array Element AlphamericNumeric: Zoned-decimal, trailingnumeric, packed, binary

AlphamericZoned-decimalTrailing Numeric

DSC$K_DTYPE_TDSC$K_DTYPE_NZDSC$K_DTYPE_NZ

Input Field Col 43: blank; Col 52: blankCol 43: blank; Col 52: 0 - 9Col 43: P Col 52: 0 - 9Col 43: B Col 52: 0 - 9Col 43: B Col 52: 0 - 9

AlphamericZoned-decimalTrailing numericPacked decimalBinary, 2 byteBinary, 4 byte

DSC$K_DTYPE_TDSC$K_DTYPE_NZDSC$K_DTYPE_NZDSC$K_DTYPE_PDSC$K_DTYPE_WDSC$K_DTYPE_L

Data Struct. AlphamericNumeric: Zoned-decimal, trailingnumeric, packed, binary



DS Subfield Col 43: blank; Col 52: blankCol 43: blank; Col 52: 0 - 9

AlphamericZoned-decimalTrailing numeric


Calc field Col 52: blankCol 52: 0 - 9



When using the PARM operation to pass parameters to a MigrationRPG program from a program written in another language, fixed-lengthdescriptors and one of the above descriptor types must be used. If theincoming parameter is not a fixed-length descriptor and does not use oneof these descriptor types, the Migration RPG program will issue an errormessage and abort.

When passing parameters between Migration RPG programs, theparameter list passed by the calling program and the parameter listspecified in the subprogram’s *ENTRY PLIST must match data types andshould match sizes. Thus, if the first parameter passed to a program isa 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 thedata types, sizes, and number of parameters in the RPG subprogram’sparameter list. However, the following exceptions apply when passingparameters between Migration RPG programs:

• Parameters of the same data type, but different lengths, will generatea warning message, but will be accepted by the subprogram. The

11–100

Operation Codes

warning message can be suppressed by compiling the subprogramusing 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 subprogramis prepared to accept, a warning message will be issued and the extraparameters will be ignored. The warning message can be suppressedby compiling the called program using the /NOWARNING qualifier. Ifthe calling program passes too few parameters, the subprogram willlog an error message and return to the calling program with an errorstatus set.

When passing parameters between Migration RPG programs, descriptorcreation, transfer, and checking is handled automatically by the MigrationRPG runtime routines.

Example 11–54 CALL and PARM Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C* The following example illustrates the use of theC* PARM statement with the CALL operation code.C*C* The first parameter passes the contents of theC* field TAP to the called program and returns anyC* modifications to the field TAP when the calledC* program exits.C*C* The second parameter copies the contents of theC* field FOX to the field TROT before passing theC* contents of TROT to the call program. Since TROTC* is defined as a 10-byte, alpha field, it will beC* moved using a MOVE operation. When the calledC* program exits, TROT will contain the updated data.C*C* The third parameter passes the contents of theC* field CHARLE to the called program. When theC* called program exits, the updated contents ofC* CHARLE will be copied to STON.C*C* The fourth parameter copies the contents of theC* field ROCK to the field AND when a program isC* called. Since AND is defined as a 7-byte, numericC* field, the copy is carried out using a Z-ADDC* operation. When the called program exits, theC* updated data in AND is Z-ADDed to the field ROLL.C*C CALL ’DANCE’C PARM TAPC PARM FOX TROT 10C STON PARM CHARLEC ROLL PARM ROCK AND 70

11–101

Operation Codes

11.12.41- PLIST Operation (RPG Subprogram Parameter List)


9−17 18−27 33−42 43−48 56−57 58−597−8

Required

28−32 54−55

Blk Blank Blank Blank BlankOpt PLIST Blank

Description

The PLIST operation defines a unique symbolic name for a list ofparameters that is used in a CALL operation.

Rules

A PLIST operation can be specified anywhere within the Calculationspecifications, including total time calculations and between subroutines.A PLIST entry consists of a PLIST statement followed by one or morePARM statements which define a list of parameters that is to be passedto or received by a subprogram. A parameter listed is ended when anoperation 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 PLISTname can be one to six characters in length and must be unique. Ifthe parameter list being defined is the entry parameter list for an RPGsubprogram, factor 1 must contain *ENTRY. Only one *ENTRY PLIST canbe defined in a program.




Operation

The elements in a parameter list supplied by a calling program and theelements in a parameter list defined by a *ENTRY PLIST in an RPGsubprogram should match in size and data type.

11–102

Operation Codes

Example 11–55 PLIST and *ENTRY PLIST Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C* The *ENTRY PLIST is set up to accept and returnC* three parameters from a calling program. TheC* PLIST labeled FARM has three parameters assignedC* to it. A CALL statement in this program couldC* reference the PLIST FARM and pass the FARMC* parameter list to another program.C*C *ENTRY PLISTC PARM COWSC PARM HOGSC PARM CHICKNC*C FARM PLISTC PARM TRACTRC PARM COMBINC PARM PICKUP

11–103

Operation Codes

11.12.42- READ Operation


9−17 18−27 33−42 43−48 56−57 58−59

READ Opt Opt

7−8 28−32

Required

54−55

Opt Blank BlankOpt Blank

Description

The READ operation calls for a record to be read immediately from ademand or full-procedural file. The READ operation differs from theFORCE operation in that the FORCE operation specifies a read from a fileon 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 specifiedin factor 2 must match a file name specified in columns 7 - 14 of the FileDescription specifications.


The resulting indicator in columns 54 - 55 (high) must be blank. Theresulting indicator in columns 56 - 57 (low) is optional and can be usedas an exception indicator on reads to WORKSTN devices and an errorindicator 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-proceduralfile. These files have a D or F specified in column 16 of the File Descriptionspecification.

A READ operation can be carried out against the following types of inputand 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 anend-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 READto a file which is already at end-of-file.

• On a read to a demand file, the indicator is not turned off before theREAD operation is performed.

• On a read to a full-procedural file, the indicator is turned off before theREAD operation is performed.

• If the indicator is blank and no error indicator is present, a halt occurswhen 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 aREAD operation to a data file, it serves as an error indicator, turning on ifthe record requested by the READ operation cannot be accessed.


If a resulting indicator is specified in columns 56 - 57 (low) of a READoperation to a WORKSTN file, it is called an exception indicator. Thefollowing rules apply to the use of this indicator:

• If the indicator is specified, it will turn on if an exception conditionis processed. An exception condition occurs when the user enters afunction key at the workstation device. Function keys consist of theRoll Up , Roll Down , Clear , Print , Home , and Help functions.

• If the indicator is not specified and an exception occurs, a halt willbe issued and the user will be given the opportunity to continueor terminate the program unless an INFSR exception handlingsubroutine has been defined. INFSR subroutines are discussed inthe Migration RPG Screen Format Reference Manual.

If a READ operation is successful, the record-identification indicatorsassociated with the record read remain on for the rest of the cycle. Otherrecord-identification indicators are not affected.

11–105

Operation Codes

Example 11–56 READ Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*FJAZZ ID F 80 80 DISK

.

.

.C READ JAZZ 99

.

.

.

In this example, a READ operation is being carried out against thesequential file JAZZ. If the READ operation encounters an end-of-filecondition, indicator 99 will be turned on.

11–106

Operation Codes

11.12.43- READE Operation (Read Equal Key)


9−17 18−27 33−42 43−48 56−57 58−59

Opt Req

7−8

Required

28−32

Required

54−55

Opt BlankOpt READE Blank

Description

The Read Equal Key operation retrieves the next sequential record froman 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 andlength as the key field of the file being read.

Factor 2 is required. It must contain the name of the file being read. Thefile must be a full-procedural, indexed file and the name must match aname specified in columns 7 - 14 of the File Description specifications.


A resulting indicator in columns 54 - 55 is not permitted. A resultingindicator in columns 56 - 57 is optional and serves as an error indicator. Aresulting indicator in columns 58 - 59 (equal) is required and serves as arecord-not-found indicator.

Operation

The READE operation will read the next sequential record from anindexed, full-procedural file if the key in the record matches the keyspecified in factor 1. A full-procedural file is identified by an F in column16 of the File Description specification. A CHAIN or SETLL operationmust occur before a READE operation to position the record pointer withinthe file. If a READE operation fails, another SETLL or CHAIN operationmust be carried out to reposition the record pointer or all subsequentREAD, READE, and READP operations will fail.

A resulting indicator in columns 56 - 57 is optional. If specified, it servesas an error indicator, turning on if the record requested by the READEoperation 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 beturned off when processing of the READE operation begins. It will turnon 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 theprogram.

If a READE operation is successful, the record-identification indicatorsassociated with the record read remain on for the rest of the cycle. Otherrecord-identification indicators are not affected.

Example 11–57 READE Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*FROCK IF F 120R 5AI 1 DISK

.

.

.C KEY CHAINROCK 99C LOOP TAGC N99 KEY READEROCK 99

.

.

.C N99 GOTO LOOP

.

.

.

In this example, the READE operation is used to read all records with akey equal to the record located by the CHAIN operation. Note the use ofindicator 99 to indicate a record-not-found condition.

11–108

Operation Codes

11.12.44- READP Operation (Read Prior)


9−17 18−27 33−42 43−48 56−57 58−59

Opt Req

7−8 28−32

Required

54−55

Opt Blank BlankOpt READP Blank

Description

The Read Prior operation retrieves the previous sequential record from afull-procedural file.

Rules



Factor 2 is required. It must contain the name of the file being read. Thefile must be a full-procedural file and the name must match the namespecified in columns 7 - 14 of the File Description specification.


A resulting indicator in columns 54 - 55 is not permitted. A resultingindicator in columns 56 - 57 (low) is optional and serves as an errorindicator. A resulting indicator in columns 58 - 59 (equal) is optional andserves as a beginning-of-file indicator.

Operation

The READP operation will read the previous sequential record from afull-procedural file. A full-procedural file is identified by an F in column16 of the File Description specification. The READP operation can be usedagainst 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 offwhen processing of the READP operation begins. The resulting indicatorin 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 beaccessed, the error indicator in columns 56 - 57 will be turned on. The$STAT$ field can be checked to determine the return status of the READPoperation. If a READP operation fails, a SETLL or CHAIN operationmust 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 indicatorsassociated with the record read remain on for the rest of the cycle. Otherrecord-identification indicators are not affected.

Indexed files require some special preparation before they can be accessedwith the READP operation. Key fields within an indexed file must bedefined as both ascending and descending keys for the READP operationto function correctly. For example, the primary key (Key 0) of an indexedfile 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 firstsecondary key (Key 1) in the file would need to be defined as a descendingkey starting in offset 0 with a length of 6.

The rule of thumb for defining keys in an indexed file which is accessedusing the READP operation is that each key defined in the FileDescription specifications must have an associated key defined as the nextsecondary key in the file. Thus, if key 2 is defined in the File Descriptionspecification, key 3 will be the key accessed by the READP operation.Creating indexed file definitions for files which are to be accessed usingthe READP operation is covered in more detail in the Migration RPGUser’s Guide. Creating indexed file definitions is covered in the OpenVMSFile Definition Language Facility Manual.

Example 11–58 READP Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*FMINE UF F 120 DISK

.

.

.C READ MINE 98

.

.

.C READPMINE 99

.

.

.

This example depicts the use of the READ and READP operation codesto extract records from the file MINE. The READ operation will read thenext sequential record in the file. If an end-of-file condition is returned bythe READ operation, indicator 98 will be turned on. The READP operationwill read the previous sequential record in the file. If a beginning-of-filecondition is returned, indicator 99 will be turned on.

11–110

Operation Codes

11.12.45- RETRN Operation (Return From an RPG Subprogram)


9−17 18−27 33−42 43−48 56−57 58−597−8 28−32 54−55

Opt Blank Blank Blank Blank BlankOpt RETRN Blank

Description

The RETRN operation causes an RPG subprogram to return to the callingprogram. The RETRN operation is associated with the CALL operation.

Rules






Operation

The RETRN operation is similar in function to the ENDSR (endsubroutine) statement. It tells an RPG subprogram to exit immediatelyand return control to the calling program. When a RETRN statement isprocessed, the follow steps occur:

1 The halt indicators (H1 - H9) are checked. If a halt indicator is on, theprogram ends abnormally, closing all data files, and returning an errorstatus. If warning messages are enabled, a warning is issued to theuser’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 streamsand deactivating the subprogram.

3 If neither the halt or LR indicators are on, the subprogram returnscontrol to the calling program. Data and indicator settings in thesubprogram are preserved.

Whether the subprogram exits normally, abnormally, or simply returns,any parameters passed to the subprogram are returned to the callingprogram. If a subprogram returns without ending, the next time it iscalled, it will resume operations with the field and indicator settings whichwere present when it returned. A subprogram can be reinitialized usingthe FREE operation. Subprograms which end normally or abnormally areautomatically reinitialized the next time they are called.

11–111

Operation Codes

Example 11–59 RETRN Operation code Use

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C* This subprogram is called by another, passing theC* parameters PHASER and PHOTON. After manipulationC* of these fields, it returns to the calling programC* without ending. Any values or indicator settingsC* established each time this subprogram is run areC* retained as long as the calling program does notC* run a FREE operation against it.C*C *ENTRY PLISTC PARM PHASERC PARM PHOTON*C PHASER ADD ENERGY PHASERC PHOTON ADD ENERGY PHOTON*C RETRN

11–112

Operation Codes

11.12.46- RLABL Operation (EXIT Operation Parameter Definition)


9−17 18−27 33−42 43−48 56−57 58−59

Required

7−8 28−32 54−55

Blk Blank Blank Blank BlankBlk RLABL Blank

Description

The RLABL allows parameters which are to be passed to an externalsubroutine called by an EXIT operation to be defined. The RLABLoperation is maintained for compatibility with non-Digital versions of theRPG programming language and to pass parameters to the MSI-suppliedsubroutines SUBR01, SUBR21, and SUBR23. The CALL operation andits associated instructions are recommended for calling external routinesusing 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 externalsubroutine.


11–113

Operation Codes

Example 11–60 RLABL Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*IDS DSI 7 56 DATASTI 17 56 DATAI 75 820MIC*C MOVE NUM MICC MOVE 1 LEVEL 10*C EXIT SUBR23C RLABL MICC RLABL DATASTC RLABL LEVELC RLABL RCODE 10

In this example, the RLABL operation is used to pass parameters to theMSI-supplied subroutine SUBR23. The RLABL operation is being used topass the numeric fields MIC, LEVEL, and RCODE, and the alphamericfield DATAST.

11–114

Operation Codes

11.12.47- SETnn Operation


9−17 18−27 33−42 43−48 56−57 58−59

Opt Opt Opt

7−8

Optional

28−32 54−55

Opt Blank BlankOpt SETnn

Description

The SETnn operation allows information to be displayed on the user’sscreen and can enable command keys for user input. The SETnn operationis often used in conjunction with the KEYnn operation.

Rules

The SETnn operation can only be used if a KEYBORD file has beendefined in the File Description specifications. KEYBORD must be definedas 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 displayedon the user’s screen when the SETnn operation is processed.

The nn portion of the SETnn operation code can be blank or can specifya message member number from the User Level 1 message member file(RPGUSRLV1). If the message member corresponding to the messagenumber in the SETnn operation code is found, the message is displayed.If the message member file is not present or no entry exists whichcorresponds to the message number specified, nothing is displayed. Ifan entry is made in factor 1 of the SETnn operation, the message numberis 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 andreferencing message member files.



Resulting indicators (columns 54 - 59) are optional. If specified, they mustcontain 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 commandkeys. The following actions can occur when the SETnn operation isexecuted:

• 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 nnportion of the SETnn operation will be displayed from the User Level1 message member file (RPGUSRLV1), if it is found.

• If no command key indicators are defined in a SETnn operation, theprogram continues without stopping for user input. SETnn operationswhich do not specify command key indicators can be used to create arunning display of data.

• If command key indicators (KA - KN, KP - KY) are defined in theresulting indicator columns, the SETnn operation stops the programand waits for user input. It will allow the user to enter the definedcommand keys from the terminal. If a command key is entered, itscorresponding indicator is turned on. If the command key is enteredagain during the same SETnn operation, its corresponding indicator isturned off. Any command key indicators defined in a SETnn operationare turned off when the SETnn operation begins execution.

• If a SETnn operation with command keys stops a program, entering acommand key does not restart the program. The user must press theReturn , Enter , or PF4 key to continue the program.

11–116

Operation Codes

Example 11–61 SETnn Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*FUSERIN IP F 70 70 KEYBORDE PRMPT 1 5 40

.

.

.C ’WAKE UP!’SETC PRMPT,1 SETC SET23 KA

.

.

.**USER DATA ENTRY REQUIRED

In this example, the SETnn operation code is used to display informationto the user’s terminal. It then pauses the program and awaits user inputbefore continuing. Note the File Description specification which describesa KEYBORD file. A KEYBORD file must be defined to use the SETnnoperation. This example also contains an Extension specification whichdescribes the array PRMPT.

The first SETnn operation displays the literal ’WAKE UP!’ to the user’sscreen. The second SETnn operation displays the first element in thePROMPT array, ’USER DATA ENTRY REQUIRED’, to the user’s screen.The third SETnn operation will display message 23 from the User Level 1Message File. The third SETnn operation will also pause the program andwait 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 willturn on indicator KA. The user will still need to press the Enter key toterminate the SETnn operation.

11–117

Operation Codes

11.12.48- SETLL Operation (Set Lower Limit)


9−17 18−27 33−42 43−48 56−57 58−597−8

Required

28−32

Required

54−55

Opt Blank Blank BlankOpt SETLL Blank

Description

The Set Lower Limit operation positions the record pointer within a file atthe record with a key that is greater than or equal to the key specified infactor 1.

Rules

The SETLL operation can only be performed against full-procedural anddemand indexed files that are being processed sequentially within limits.The File Description specification for the SETLL file must have an F or Din 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 andlength 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 or demand indexed file being processedwithin limits. The file name must match the name specified in columns7 - 14 of the File Description specification.



Operation

When a SETLL operation is performed, the file record pointer is set at therecord with the key that is greater than or equal to the key specified infactor 1. Subsequent READ, READE, and READP operations will beginfrom 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 canbe 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 thesame data file.

Example 11–62 SETLL Operation Code Usage

1 2 3 4 5123456789012345678901234567890123456789012345678901234567890001 H0002 FCUSTMSTRIF F 132L 5AI 1 DISK0003 FINPUT CD F 32 WORKSTN

.

.

.0009 ICUSTMSTRAA 010010 I 1 5 KEY0011 I 6 20 LSTNAM0012 I 21 35 FSTNAM0013 *0014 IINPUT BB 020015 I 1 5 KEY

.

.

.0044 C READ INPUT 900045 C N90 KEY SETLLCUSTMSTR0046 C N90 READ CUSTMSTR 90

In this example, the SETLL operation is used to position a pointer in theCUSTMSTR file based on a customer key. The user enters a key valuevia a workstation into the INPUT record. The value is placed in the fieldKEY. The field KEY is used by the SETLL operation to position the filepointer for the subsequent READ operation. Note that SETLL and READoperations for the CUSTMSTR file are conditioned by indicator 90. If theworkstation read processes an exception, indicator 90 will be turned onand the following SETLL and READ operations will not be performed.

11–119

Operation Codes

11.12.49- SETOF Operation (Set Indicator[s] Off)


9−17 18−27 33−42 43−48 56−57 58−59

One required

7−8 28−32 54−55

Opt Blank Blank BlankOpt SETOF

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 resultingindicator columns off (to 0).

Example 11–63 SETOF Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C SETOF 101112C 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)


9−17 18−27 33−42 43−48 56−57 58−59

One required

7−8 28−32 54−55

Opt Blank Blank BlankOpt SETON

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 theresulting indicator columns on (to 1).

Example 11–64 SETON Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C SETON 304050C 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)


9−17 18−27 33−42 43−48 56−57 58−597−8 28−32

Required

54−55

Opt Blank Blank Blank BlankOpt SORTA 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 commonlyused to ensure that the elements of an array are properly sequenced beforea LOKUP operation is performed.

If the array sequence has been defined in columns 45 or 57 of theExtension specification, the array is sorted accordingly. If no sequencehas been defined, the array will be sorted in an ascending sequence. AllSORTA operations use a standard ASCII collating sequence. Alternatingcollating sequences are ignored.

Only the array specified is sorted.

11–122

Operation Codes

Example 11–65 SORTA Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*FINPUT IP F 80 80 DISK*E LUFF 10 10*IINPUT NS 01I 1 100 LUFF*C SORTALUFF

In this example, the array LUFF is loaded from an input record and thensorted into ascending order.

11–123

Operation Codes

11.12.52- SQRT Operation (Square Root)


9−17 18−27 33−42 43−48 56−57 58−59

SQRT Required

7−8 28−32

Required

54−55


Description

The Square Root operation calculates the square root of the value specifiedin factor 2.

Rules



Factor 2 is required. It must contain a numeric entry. It can contain thename 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 factor2, placing the product in the result field. The SQRT operation alwaysproduces a positive result. If the value specified in factor 2 is negative, itssign is changed before the square root calculation takes place.

It is recommended that the result field have at least half as many decimalplaces as factor 2. Results of a SQRT operation are always half-adjusted.

Example 11–66 SQRT Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C SQRT NUM CHUCK

In this example, the SQRT operation calculates the square root of thecontents of NUM and places the result in CHUCK.

11–124

Operation Codes

11.12.53- SUB Operation (Subtraction)


9−17 18−27 33−42 43−48 56−57 58−59

SUB Required Opt Opt Opt

7−8

Optional

28−32

Required

54−55

OptOpt

Description

The Subtract operation subtracts factor 2 from factor 1, placing thedifference 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 thedifference is placed in the result field.

Factor 2 is required. If factor 1 is not present, factor 2 is subtracted fromthe 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.

Resulting indicators (columns 54 - 59) are optional. They can beused 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 SUB operation.

Operation


11–125

Operation Codes

Example 11–67 SUB Operation Code Usage - 2 operands

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C FLD1 SUB 1 FLD2

In this example, the constant 1 is subtracted from FLD1 and the result isplaced in FLD2.

Example 11–68 SUB Operation Code Usage - 1 operand

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C SUB 1 CNT

In this example, the constant 1 is subtracted from the field CNT and theresult is placed in CNT.

Example 11–69 SUB Operation Code Usage - Indicator controlled

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C 10 PAY SUB TAXES PITANC

In this example, the SUB operation is only carried out if indicator 10 ison. If processed, the operation will subtract the field TAXES from the fieldPAY, placing the result in PITANC.

11–126

Operation Codes

11.12.54- TAG Operation


9−17 18−27 33−42 43−48 56−57 58−59

TAG

7−8

Required

28−32 54−55

Blnk Blank Blank Blank BlankOpt Blank

Description

The TAG operation defines a label to which a GOTO or CABxx operationcan branch.

Rules


Conditional indicators in columns 9 - 17 are not permitted.

Factor 1 is required. It must contain the label which defines the branchdestination of a GOTO or CABxx operation. A label can be 1 - 6 characterslong and must begin with an alpha character. Each TAG label name mustbe unique.




Example 11–70 TAG Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C LOOPY TAG

This example depicts the use of the TAG operation to define the labelLOOPY.

11–127

Operation Codes

11.12.55- TESTB Operation (Test Bit)


9−17 18−27 33−42 43−48 56−57 58−59

Required One required

7−8 28−32

Required

54−55

Opt BlankOpt TESTB

Description

The Test Bit operation compares the bits specified in factor 2 to thecorresponding bits in the result field.

Rules



Factor 2 can contain a literal bit mask or a single-character field whichcontains the bit mask used by the TESTB operation. A literal bit maskidentifies the bits as 0 through 7, with 0 as the leftmost bit. The bit maskmust 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 oncein 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 factor 2are tested in the result field. If an array element is specified, each elementin the array must be a single-character field. If factor 2 is not a singlecharacter 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 singlecharacter alphameric fields. The bits specified in factor 2 will be tested inthe 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 specifiedas on in factor 2.

At least one resulting indicator must be specified. All three resultingindicators can be used. The indicators are turned on by the TESTBoperation as follows:

• High - Columns 54 - 55

This indicator turns on if each bit specified in factor 2 is off in theresult 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 onand 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 theresult field (on status).

Example 11–71 TESTB Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C TESTB’04’ WK01 333435C TESTBLOTTO WINNER 444546

In this example, the first TESTB operation checks bits 0 and 4 in the fieldWK01. If both bits are off (0), indicator 33 will be turned on. If the bitsare in a mixed state, one off and one on, indicator 34 will be turned on. Ifboth bits are on (1), indicator 35 will turn on.

In the second TESTB operation, the bits which are on in the field LOTTOwill be compared to the corresponding bits in the field WINNER. If all bitswhich are on in LOTTO are off (0) in WINNER, indicator 44 will be turnedon. If the bits which are on in the LOTTO field are in a mixed state in theWINNER field, some on and some off, indicator 45 will be turned on. If allbits 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)


9−17 18−27 33−42 43−48 56−57 58−59

Required One required

7−8 28−32 54−55

Opt Blank BlankOpt TESTZ

Description

The Test Zone operation tests the zone of the leftmost character in analphameric field.

Rules




The result field is required. It must contain an alphameric field, tableelement, 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 inan alphameric entry. The resulting indicators are used to indicate theresults of the test. At least one resulting indicator must be specified. Allthree resulting indicators can be used. The resulting indicators indicatethe following conditions:

• Plus - Columns 54 - 55

This indicator turns on if the zone of the leftmost character in theresult field is an &, A - I, or has the same zone as an A.

• Minus - Columns 56 - 57

This indicator turns on if the zone of the leftmost character in theresult field is a J - R or has the same zone as a J.

• Zero - Columns 58 - 59

This indicator turns on if the zone of the leftmost character in theresult 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 512345678901234567890123456789012345678901234567890123456789

C*C TESTZ ULP 102030

In this example, the TESTZ operation is used to test the zone portion ofthe first character in the field ULP.

11–131

Operation Codes

11.12.57- TIME Operation (Time of Day)


9−17 18−27 33−42 43−48 56−57 58−59

TIME Required

7−8 28−32 54−55


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 operationin the format HHMMSSMMDDYYYY. This string is loaded from leftto 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 a4-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 maynot 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 datewhich can differ from the system date. The program date is accessed viathe UDATE and $UDATE field. See the Migration RPG User’s Guide formore information on the REX Utility.

The system date can be returned in MMDDYYYY, DDMMYYYY, orYYYYMMDD format. The format used will depend upon the date formatcode placed in column 19 of the Control specification.

11–132

Operation Codes

Example 11–73 TIME Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

IFULTIM DSI 1 60TIMEI 7 140DATEC*C TIME CLOCK 60C TIME FULTIM

In this example, the first TIME operation will move only the system timeto the field CLOCK, as CLOCK is defined as a 6-digit, numeric field. Thesecond TIME operation moves the system time and date into the datastructure 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)


9−17 18−27 33−42 43−48 56−57 58−59

$TIME Required

7−8 28−32 54−55


Description

The $TIME operation returns the system time and a non-Year 2000compliant date. The $TIME opcode is provides backward compatibility forolder 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 operationin the format HHMMSSMMDDYY. This string is loaded from left toright 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 a2-digit field, HH will be loaded into it.


Operation

The $TIME operation obtains the system date and time from theOpenVMS $ASCTIM system service. The date obtained by the $TIMEoperation 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 aprogram date which can differ from the system date. The program dateis accessed via the UDATE and $UDATE field. See the Migration RPGUser’s Guide for more information on the REX Utility.

The system date can be returned in MMDDYY, DDMMYY, or YYMMDDformat. The format used will depend upon the date format code placed incolumn 19 of the Control specification.

11–134

Operation Codes

Example 11–74 $TIME Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

ITIMDAT DSI 1 60TIMEI 7 120DATE*C $TIME SAVTIM 40C $TIME TIMDAT

In this example, the first $TIME operation will move only the HHSSportion of the system time to the field SAVTIM, as SAVTIM is defined as a4-digit, numeric field. The second $TIME operation moves the system timeand non-Year 2000 compliant date into the data structure FULTIM, whichis defined as being 12 digits in length.

11–135

Operation Codes

11.12.59- XFOOT Operation (Summing the Elements of an Array)


9−17 18−27 33−42 43−48 56−57 58−59

XFOOT Required Opt Opt Opt

7−8 28−32

Required

54−55

Opt BlankOpt

Description

The XFOOT operation sums the elements in a numeric array and placesthe total in the result field.

Rules



Factor 2 is required. It must contain the name of a non-indexed, numericarray.

The result field is required. It must contain a numeric field entry whichwill accept the product of the XFOOT operation.

Resulting indicators (columns 54 - 59) are optional. They can beused 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 XFOOT operation.

Example 11–75 XFOOT Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*E AR$ 5 5 0

.

.

.C XFOOTAR$ TOTAR$ 70

In this example, the XFOOT operation is used to total the elements in thenumeric array AR$. The result of the XFOOT operation is placed in thefield TOTAR$.

11–136

Operation Codes

11.12.60- Z-ADD Operation (Zero-Add)


9−17 18−27 33−42 43−48 56−57 58−59


7−8 28−32

Required

54−55

Opt BlankOpt Z−ADD

Description

The Zero-Add operation initializes the result field with the contents offactor 2.

Rules



Factor 2 is required. It must contain a numeric entry.


Resulting indicators (columns 54 - 59) are optional. They can beused 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 Z-ADD operation.

Operation

The Z-ADD operation adds the contents of factor 2 to zero and places theproduct in the result field.

Example 11–76 Z-ADD Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C Z-ADD24 LOLLY 70

In this example, the Z-ADD operation is used to initialize the field LOLLYto the value 24.

11–137

Operation Codes

11.12.61- Z-SUB Operation (Zero-Subtract)


9−17 18−27 33−42 43−48 56−57 58−59


7−8 28−32

Required

54−55

Opt BlankOpt Z−SUB

Description

The Zero-Subtract operation initializes the result field with the contents offactor 2.

Rules



Factor 2 is required. It must contain a numeric entry.


Resulting indicators (columns 54 - 59) are optional. They can beused 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 Z-SUB operation.

Operation

The Z-SUB operation subtracts the contents of factor 2 from zero andplaces the product in the result field.

Example 11–77 Z-SUB Operation Code Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C Z-SUB100 POP 70

In this example, the Z-SUB operation is used to initialize the field POP tothe 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 canbe referenced as data fields or array elements (*INxx, *IN,xx). Indicatorsare used to condition when an operation occurs and what the results of anoperation are within an RPG program.

12.1 Available IndicatorsThe following table depicts all of the indicators available in an RPGprogram 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,KP - KY

Command key indicators

L0 Level Zero indicator

L1 - L9 Control break indicators

LR Last Record indicator

MR Matching record indicator

OA - OG,OV

Overflow indicators

RT Return indicator

U1 - U8 External indicators

12.2 Program Defined IndicatorsMost indicators must be defined on the RPG specification lines beforethey can be used to condition operations in an RPG program. However,several indicators are defined by the RPG program itself and can be usedto condition operations within the program without first defining them ona specification line. The following table lists these indicators and theirfunctions:

12–1

Using Indicators

Table 12–2 Program Defined Indicators

Indicator(s) Function Description

1P First Page This indicator is on for the firstcycle of an RPG program. Itallows the programmer to controlthe output of heading lines duringfirst cycle output. The indicatoris turned off at the end of thefirst cycle. It is entirely controlledby the RPG program cycle andcannot be set on or off by theprogrammer.

L0 Level Zero The Level Zero indicator is alwayson and can be used to conditiontotal time operations even whencontrol break fields are not in use.

LR Last Record The Last Record indicator isturned on when all primary andsecondary input files have reachedan end-of-file condition. Thisindicator can also be turned onby the programmer in the Input orCalculation specifications. Whenthe Last Record indicator is turnedon, the program carries out lastcycle processing and terminates.

MR Matching Record The matching record indicatoris turned on if match fields(M1 - M9) are declared in aprogram’s Input specifications anda match field condition occurs.The matching record indicatorcannot be set on or off in theCalculation specifications.

U1 - U8 External Indicators External indicators can be setoutside of a program before itis executed. They can also bemodified by a program and passedto a command procedure oranother program. The REX Utilityis used to set and clear externalindicators from a commandprocedure. See the MigrationRPG User’s Guide for moreinformation concerning the REXUtility.

All remaining indicators must be defined in the File, Input, or Calculationspecifications before they can be used to control operations in a program.

12–2

Using Indicators

12.3 Indicator Types and UsageIndicators function as on/off switches. To use an indicator to controlprogram operations, the conditions under which it is set on or off are firstdefined. The status of the indicator (on or off) is then checked to determinewhether the specified operation should be performed.

Indicators are classed as types. The following types of indicators areavailable 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 andits usage in a program.

12–3

Using Indicators

12.4 Indicators Defined By the ProgrammerThe indicators described in the following sections must be defined by theprogrammer in the File Description, Input, or Calculation specifications.

12.4.1 Record Identifying IndicatorsRecord identifying indicators are used to distinguish the types of inputrecords that will be encountered within a program at run time.

Each input record defined in an RPG program normally has an identifyingindicator specified in columns 19 - 20. This indicator is turned on ifthe data record being input matches the record identification conditionsspecified in columns 21 - 41. The record identifying indicator permits theprogrammer to determine the type of record which has been read andcondition 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 toidentify various record types.

H1 - H9 The halt indicators are normally used to indicate an error. Usethese indicators to identify invalid record types.

L1 - L9 The control break indicators can be used to specify thatcalculation and output operations conditioned by control breakindicators will be performed at detail and total time. A controlbreak indicator set on as a record identifying indicator does notset on all lower control break indicators.

LR The Last Record indicator indicates to the program that this isthe last record to be processed. This indicator can be used asa record identifying indicator if input of a specific record typeindicates that the program should be terminated.

RT The return indicator is used to terminate an RPG subprogramwithout resetting the program.

The record identifying indicator for a particular record type is set on whenRPG 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 onimmediately after the record is read. In either case, it is set off when theprogram reaches the end of the current program cycle (after detail timeoutput).

Record identifying indicators can be set on or off within the Calculationspecifications.

If the CHAIN or READ operation is used to retrieve a record, the programdoes not set the associated record identifying indicator off until thebeginning of the next program cycle. Be careful when performing morethan 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 duringa single cycle.

Record identifying indicators can be used to condition both detail timeand total time calculation and output operations. The following exampleshows how record identifying indicators can be used to condition programoperations:

Example 12–1 Record Identifying Indicators Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*00010FSALES IPE F 120 DISK00020FREPORT O F 80 OF PRINTER00030 *00040ISALES AA 01 1 CJ00050I 2 50ITEM00060I 10 15 DESCR00070I 20 242SALES00080I 30 342COST00090I 40 432PROFIT00100I BB 9900110 *00120C 01 SALES SUB COST NET 5200130C 01 TSALES ADD SALES TSALES 6200140C 01 TCOST ADD COST TCOST 6200150C 01 TPROFT ADD NET TPROFT 6200160 *00170OREPORT H 201 1P00180O OR OF00190O UDATE Y 1000200O 42 ’JANUARY SALES REPORT’00210O 64 ’PAGE’00220O PAGE 6800230O H 22 1P00240O OR OF00250O 4 ’ITEM’00260O 23 ’DESCRIPTION’00270O 35 ’SALES’00280O 47 ’COST’00290O 60 ’PROFIT’00300O D 0100310O ITEM 3 500320O DESCR 2200330O SALES 1 3500340O COST 1 4800350O PROFIT1 6000360O T 1 LR00370O 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 thefile SALES. The identification code (columns 21 - 41) on line 40 groupsthese records according to a code that represents the month. If thecode for the month is J, the record identifying indicator 01 is set on.

• Lines 120 - 150 use the record identifying indicator 01 to conditiondetail time calculations. The calculation are performed each time arecord of the type described on line 40 is read.

• Line 300 uses the record identifying indicator 01 to condition detailtime output. The output operation is performed each time a record ofthe type described on line 40 is read.

The output file produced by the program in Example 12–1 might appearas follows:

Example 12–2 Output generated by Example 12–1

1 2 3 4 5 61234567890123456789012345678901234567890123456789012345678901234567802/04/83 JANUARY SALES REPORT PAGE 1

ITEM DESCRIPTION SALES COST PROFIT

10005 AMMONIA 60.30 50.00 10.3010982 MATCHES 295.00 205.00 90.0022650 NUTMEG 209.00 170.00 39.00

TOTALS $564.30 $425.00 $139.30

12.4.1.1 AND and OR RelationshipsA maximum of three identification characters can be specified on oneInput specification. An AND line can be used to continue the recordidentification condition from the previous line. All conditions must bematched before the associated record identifying indicator will be turnedon.

If a record can be identified by more than one set of conditions, an OR lineis used to separate each set of record identification conditions. An OR canalso be used to specify additional record identification indicators.

Table 12–4 AND and OR Relationships


AND Specifies an AND relationship between the identification conditionson the current program line and the previous program line.

OR Specifies an OR relationship between the record identificationconditions 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 anOR line. If columns 19 - 20 are left blank, the record identifying indicatorspecified in the preceding program line will apply to the OR line.

The following example depicts the use of the AND and OR qualifiers withrecord identification indicators.

Example 12–3 AND/OR Usage With Record Identifying Indicators

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*00040ISALES AA 01 1 CJ 2 CU 3 CL00041I AND 4 CY00050I 1 9 MONTH00060I 10 15 CODE00061I AX 9800070 *00080ICUSTMST BB 02 1 CA 2 CA00081I OR 1 CA 2 CB00082I OR 03 1 CB 2 CB00060I 1 5 CODE

In this example, the SALES record on lines 40 and 41 uses the ANDqualifier to construct a 4-character record identification condition. In thiscase, the record identifying indicator 01 will be turned on if the first 4positions in the SALES record are JULY.

On lines 80 - 82, the OR qualifier is used to describe three different sets ofrecord identification conditions which can be used to select the CUSTMSTrecord. If the first two characters in the CUSTMST record are AA, therecord identification conditions on line 80 are satisfied and indicator 02 isturned on. If the first two characters in the CUSTMST record are AB, therecord identification conditions on line 81 are satisfied and indicator 02 isturned on. Note that because no record identification indicator has beenspecified on line 81, the program defaults back to the indicator specifiedon line 80. If the first two characters in the CUSTMST record are BB, therecord identification conditions on line 82 are satisfied and indicator 03 isturned on.

12–7

Using Indicators

12.4.2 Field IndicatorsField 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 usedto 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 conditionsin the input data (for example, a negative value appearing whereone 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 incolumns 65 - 66 of the Input specification. The indicator will be turnedon if the field’s contents are positive.

• To determine if a numeric field is negative, specify a field indicator incolumns 67 - 68 of the Input specification. The indicator will be turnedon if the field’s contents are negative.

• To determine if a numeric field is zero, specify a field indicator incolumns 69 - 70 of the Input specification. The indicator will be turnedon if the field’s contents are zero.

• To determine if an alphameric field is all blanks, specify a fieldindicator in columns 69 - 70. The indicator will be turned on if thefield’s contents are blank.

Field indicators cannot be specified in columns 65 - 68 on an alphamericinput 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 anumeric 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 therecord. After a field indicator is set on, it remains on until the nexttime the field is extracted, unless it is set off by another use of the sameindicator in the program. A field indicator can be used to condition anydetail time or total time operations. However, at total time, the fieldindicators assigned to fields from a primary or secondary file retain thesetting from the previous detail time cycle.

12–8

Using Indicators

The following example shows how field indicators can be used to conditiona Calculation specification:

Example 12–4 Field Indicator Usage

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890

*00024IPARTLIS AA 01 1 CF00025I 2 100INVCDE 112233

.

.

.00041C 11 ITEM MULT FACT1 ORDER 62H00042C 22 ITEM MULT FACT2 ORDER H00043C 33 ITEM MULT FACT3 ORDER H

• Line 25 tests the value of the field INVCDE to see if it contains apositive value, a negative value, or a zero value. The following is a listof indicators that are set on for each value:

— If the field contains a positive value, indicator 11 is set on andindicators 22 and 33 are set off.

— If the field contains a negative value, indicator 22 is set on andindicators 11 and 33 are set off.

— If the field contains a zero value, indicator 33 is set on andindicators 11 and 22 are set off.

• Lines 41 through 43 calculate the number of parts to order accordingto the status of the INVCDE field indicators.

12–9

Using Indicators

12.4.3 Resulting IndicatorsResulting indicators are used to indicate the result of an operation in theCalculation specifications. Resulting indicators can be used to conditioncalculation and output operations.

Resulting indicators are specified in columns 54 - 59 of the Calculationspecification. 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 theseindicators can also be used in the Input specifications as recordidentifying and field indicators.

H1 - H9 The halt indicators are generally used to indicate an errorcondition.

KA - KN,KP - KY

The command key indicators are normally used as resultingindicators with the SETnn operation code.

L1 - L9 The control break indicators can be used to specify that controlbreak calculation and output operations will be performed at detailand total time. A control break indicator set on as a resultingindicator does not set on all lower control break indicators.

LR The Last Record indicator indicates to the program that this isthe last record to be processed. This indicator can be used as aresulting indicator to indicate that the result of an operation shouldterminate the program.

OA - OG, OV The overflow indicators are normally used to condition outputto a printer file. They can also be used to condition calculationoperations.

U1 - U8 The external indicators are generally used to pass informationbetween programs and procedures.


How and when resulting indicators are specified and set is dependent uponthe calculation operation being performed. Not all operations require oreven allow resulting indicators. Chapter 11, Operation Codes, containsdescriptions of all of the RPG operation codes and their related resultingindicator usage.

12–10

Using Indicators

The following example shows how resulting indicators can be used tocontrol program operations:

Example 12–5 Resulting Indicator Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*00010C HOME COMP VISTOR 10203000020C 10 ADD 1 WINS00030C 20 ADD 1 LOSSES00040C 30 ADD 1 TIES

• On line 10, a COMP operation is used to compare the contents of thenumeric fields HOME and VISTOR. The resulting indicators specifiedin columns 54 - 59 will be cleared when the COMP operation beginsand 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 IndicatorsControl break indicators indicate that a particular field in the input recordis a control field. Each time the program reads a record that containsthe control field, it compares the data in the control field with the storedvalue of the control field which was obtained from a previous record. Ifthe contents of the control field change, a control break occurs, the controlbreak indicator is set on, and the value in the current control field becomesthe new stored control value.

Indicators L1 - L9 are the control break indicators. They are associatedwith an input field by specifying the indicator in columns 59 - 60 of theInput specification.

12.4.4.1 Using Control Break IndicatorsWhen conditioning Calculation specifications, control break indicatorscan be used in two ways. They can be used as conditioning indicators ondetail time Calculation specifications and they can be used to define totaltime calculations. When used on detail time Calculation specifications,the indicators are specified in columns 9 - 17. Detail time Calculationspecifications have blanks in columns 7 - 8. Total time Calculationspecifications have one of the following indicators specified in columns7 - 8:

• L0

• L1 - L9

• LR

Calculation specifications with control break indicators specified incolumns 7 - 8 are only executed during total time processing if thespecified indicator is on.

12.4.4.2 Rules for Specifying Control Break IndicatorsControl break indicators can only be specified for primary and secondaryinput 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 theindicator L5 is set on due to a control break, indicators L1 - L4 will also beset on. All control break indicators are set off after detail time output.

Control fields are initialized to hexadecimal zeros. This usually causes acontrol break to occur on the first record with a control field. Because ofthis, RPG bypasses total time calculation and output operations on thefirst 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 recordtypes.

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 144characters.

The decimal position and sign of numeric fields are ignored when checkingfor a control break. Thus, the fields 257.8 and 2578 would be consideredequal. The fields -3049 and 3049 would also be considered equal.

Field names are ignored when processing control fields. This allows thesame control break indicator to be assigned to multiple fields with thesame name.

If any one control field is numeric, all fields assigned to that control breakindicator will be treated as numeric when being compared, meaning thatonly 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 thelength of the field for comparison purposes.

Input fields defined as binary (B in column 43) cannot be used as controlbreak fields.

All control break indicators are set on before total time calculations whenthe Last Record (LR) indicator is set on. All control break indicators areset off after detail time output.

12–13

Using Indicators

12.4.4.3 Control Break Indicator Usage ExampleThe following example shows how control break indicators are used tocontrol total time calculations and output:

Example 12–6 Control Break Indicator Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*00010FSALESFILIPE F8000 80 DISK00020FREPORT O F 80 PRINTER

*00050ISALESFILAA 0100060I 01 04 REGIONL800070I 05 08 DIST L700080I 09 38 SALNAM00090I 39 44 SALEIDL600100I P 45 492SALES

.

.

.00200C SALES ADD SALTOT SALTOT 92

.

.

.00300CL6 SALTOT ADD DISTOT DISTOT 9200310CL7 DISTOT ADD REGTOT REGTOT 9200320CL8 REGTOT ADD GRAND GRAND 102

.

.

.00400OREPORT T L600410O 20 ’Total for Sales Person:’00420O SALNAM 5100430O SALEID 6000440O SALTOT B 80 ’$ , , . ’00450OREPORT T L700460O 20 ’District Total’00470O DISTOT B 80 ’$ , , . ’00480OREPORT T L800490O 20 ’Regional Total’00500O REGTOT B 80 ’$ , , . ’00510OREPORT T L900520O 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 breakindicator L8.

• On line 70, the field DIST is conditioned by the control break indicatorL7.

• On line 90, the field SALEID is conditioned by the control breakindicator L6.

• As long as none of the control break indicators are turned on, lines300, 310, and 320 will not be executed.

• If, after the input of a new record, RPG determines that the fieldSALEID in the current record differs from the value in storage, acontrol break occurs and the indicator L6 is turned on. When the L6indicator is turned on, all lower control break indicators are turnedon as well. Thus, the L6 control break turns on indicators L1 - L6.During total time processing, the program will perform all L1 - L6total time calculations and output operations. In the example, thisincludes lines 300 and 400 - 440.

• If, after the input of a new record, RPG determines that the fieldREGION in the current record differs from the value in storage, acontrol break occurs and the indicator L8 is turned on. This will turnon control break indicators L1 - L8. In the example, lines 300 - 320and 400 - 500 will be executed during total time processing.

• After the last input record in the file has been read, the Last Recordindicator (LR) and all control break indicators are turned on. This ispart 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 FieldsWhen 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 fieldsmust be either all numeric or all alphameric and described on adjacentlines. The fields used within split-control fields do not need to be the samelength.

The total length of a split-control field must be the same length as otherfields 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 6123456789012345678901234567890123456789012345678901234567890

*00040ISALES AA 01 1 CJ00050I 2 5 BRNCH L300060I 10 15 SLSPR L300070I 20 24 CUSTNOL300080I BB 02 1 CF00090I 1 23 UNIT L3

In this example, the fields BRNCH, SLSPR, and CUSTNO combine to formthe control field. When the data in these fields is compared with the datain storage obtained from a previous record, indicator L3 is set on if thedata 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 thefield UNIT will be compared to the L3 storage area.

12–16

Using Indicators

12.4.5 Overflow IndicatorsAn overflow indicator is defined in columns 33 - 34 of the File Descriptionspecification. An overflow indicator can only be specified for a PRINT orPRINTER file. It is used to indicate when the defined length of a printerform has been reached. (See Chapter 14, Using Printer Output Files, forinformation on printer output files.)

Overflow indicators are generally used to indicate which lines should beoutput at the end of the current page and the beginning of the next afterthe overflow line has been reached. The overflow line is usually defined assomething less than the overall form length.

The indicators OA, OB, OC, OD, OE, OF, OG, and OV are all validoverflow indicators. Only one overflow indicator can be assigned to aprinter file.

The overflow indicator is automatically set on when the printer file reachesthe 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 tobe anything between 1 - 112. The overflow indicator is automatically setoff at the end of the next cycle.

Overflow indicators can also be used and manipulated in the Calculationspecifications.

12–17

Using Indicators

The following example depicts the use of overflow indicators to conditionthe output of heading and detail lines.

Example 12–8 Overflow Indicator Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*00020FREPORT O F 80 OF PRINTER

.

.

.00170OREPORT H 201 1P00180O OR OF00190O UDATE Y 1000200O 44 ’SALES REPORT’00210O 68 ’PAGE’00220O PAGE 7200230O H 22 1P00240O OR OF00250O 5 ’ITEM’00260O 23 ’DESCRIPTION’00270O 41 ’SALES’00280O 56 ’COST’00290O 72 ’PROFIT’00300O D 0100310O ITEM 3 500320O DESC 2500330O SALES 1 4100340O COST 1 5700350O PROFIT1 7200360O D 1 OF00370O 30 ’SUBTOTALS’00380O TSALES1 41 ’$’00390O TCOST 1 57 ’$’00400O TPROFT1 72 ’$’00410O T 1 LR00420O 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 fileREPORT.

• 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 currentpage. 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 theoverflow routine and overflow indicators.

12–18

Using Indicators

12.4.6 Command Key IndicatorsCommand key indicators can be used to condition calculations, outputrecords, and output fields. They can also be used as resulting indicators onthe SETnn and SETOF operations. Command key indicators are generallyassociated with a WORKSTN file or SETnn operation.

The command key indicators, KA - KN and KP - KY, are directlyassociated to the command keys CMD1 - CMD24 , as indicated by thefollowing 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 workstationScreen specification or as the resulting indicators in a SETnn operation. Acommand key indicator is turned on when the user presses the associatedcommand key. If the indicator is set on by a WORKSTN device, it will beset off the next time a record is input from the WORKSTN device. If theindicator is set on by a SETnn operation, it will be set off the next time itis encountered in a SETnn operation. Command key indicators can also beset off by the SETOF operation.

12–19

Using Indicators

12.4.7 Halt IndicatorsHalt indicators (H1 - H9) are used to stop an RPG program when anunacceptable condition is detected. Halt indicators can be used as recordidentifying 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. Thismeans that all total and detail time operations in the current cycle areperformed before the program halts. Since the data which triggered thehalt will continue to be processed until the program stops, it is wise to usethe halt indicator to condition operations which should not be performedwhen a halt condition is present.

When the halt is processed by a program running in an interactiveenvironment, processing stops and the user is prompted to continue orterminate the program. The user is given the following options to respondto a halt condition:

• CONTINUE - This option tells the program to clear the halt indicatorand 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 abbreviatedto a single character: C, E, or K.

For all intents and purposes, the EXIT and KILL option do the same thingin the Migration RPG processing environment. They cause a controlledshutdown of the program and, depending upon the compiler optionsselected, may return a warning status when the program exits. Both theEXIT and KILL prompts are supported by Migration RPG to offer a levelof compatibility with non-OpenVMS versions of RPG.

The program will cycle through the halt processing step until all nine haltindicators have been checked or the user selects the EXIT or KILL optionat the prompt. For example, if halt indicators H1, H3, and H4 were setduring a single cycle, the user would be prompted three times to continueor terminate the program, once for each halt indicator.

If the program is running as a batch job and a halt indicator is set, theprogram will terminate at the beginning of the next cycle, returning anerror status.

If no halt indicators are set or if the user clears all set halt indicatorsusing the CONTINUE option, the program continues processing normally.If a halt indicator is set and the program is running in batch mode, or theuser selects the EXIT or KILL option at the halt prompt, the program willterminate.

12–20

Using Indicators

When a halt indicator is used as a record identifying indicator, a specifictype of record causes the halt. In the following example, a halt indicatoris used as a record identifying indicator, causing the program to checkthe 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 andthe program will stop execution at the beginning of the next cycle. If theprogram is running interactively, the user will be prompted to continueor terminate it. If the program is running in a batch process, it willterminate with an error status set.

Example 12–9 Halt Indicator Usage - Record Identification

1 2 3 4 51234567890123456789012345678901234567890123456789012345678

*IFILEIN AA 02 80 CSI 01 10 FIELD1I XX H1 80NCS

When a halt indicator is used as a field indicator, a halt occurs becauseof erroneous input data. The following program uses a halt indicatoras a field indicator. When a record is read from the input file FILEIN,FIELD1 is checked for a negative value. If FIELD1 contains a negativevalue, the indicator H2 is set on. After this record has been processed, theprogram will halt. Note that the H2 indicator has been used to conditiona Calculation specification, ensuring that the SQRT operation will not beperformed if the data in FIELD1 is invalid.

Example 12–10 Halt Indicator Usage - Field Indicator

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*IFILEIN AA 01I 01 50FIELD1 H2*C NH2 SQRT FIELD1 FLD2 95

When a halt indicator is used as a resulting indicator, a halt occurs whena calculation produces erroneous results during either detail or totaltime processing. In the following example, a halt indicator is used as aresulting 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 H4indicator is used to condition the subsequent DIV operation, preventing afatal divide-by-zero error.

Example 12–11 Halt Indicator Usage - Resulting Identification

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*C FIELD1 SUB 59 FIELD1 H4C NH4 FIELD2 DIV FIELD1 FIELD1

12–21

Using Indicators

12.4.7.1 Processing Halt Indicators In RPG SubprogramsHalt indicators are processed within an RPG subprogram in the samemanner they are handled in a normal program. When a halt indicatoris turned on, processing halts at the beginning of the next cycle andthe user is given the option of continuing or terminating the program.However, when a subprogram is terminated, it returns control to thecalling program, and it is possible to exit a subprogram with one or morehalt indicators set.

If a subprogram is exited with a halt indicator set and the /NOWARNINGoption was not selected when the program was compiled, a warningmessage 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, ifone was specified.

If a subprogram is exiting due to the return indicator (RT) being set and ahalt indicator is also on when the subprogram exits, the subprogram willbe reset, meaning that the subprogram will be shut down upon exit andwill be reinitialized when called again. The presence of a set halt indicatorinvalidates the ability of the return indicator to preserve a subprogram’ssettings 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 tothe calling program without resetting the subprogram. The RT indicator isturned off when a subprogram is called again.

When an RPG subprogram is exited using the RT indicator, all of thecurrent indicator, field, and file settings are preserved. The next timethe subprogram is called, it begins operation with these settings intact,essentially starting up where it left off. A subprogram can be reset byexiting with the LR indicator on, exiting with a halt indicator (H1 - H9)on, or using the FREE operation code in the calling program. SeeChapter 19, Coding Subprograms, for more information concerning callingand 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 Recordindicator take precedence over the RT indicator. If a subprogram exitswith either a halt or the Last Record indicator on, the subprogram will bereset.

The RT indicator can be set by using it as a record identifying indicator,field indicator, or resulting indicator. It can be used to conditioncalculation and output operations. The RT indicator is always turnedoff during program or subprogram startup.

Example 12–12 Return Indicator Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*C ASTEK COMP 999 RTC RT ADD 1 COUNT

In this example, the RT indicator is turned on if the contents of the fieldASTEK are equal to 999. The RT indicator is also used to condition theincrementing of the field COUNT. Turning the RT indicator on indicatesthat 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 ProgramThe indicators described in the following sections are predefined within theRPG program. They can be used without first defining them in a programspecification.

12.5.1 First Page Indicator (1P)The first page indicator (1P) is set on at the start of the program and setoff after detail time output before the first record is read. The first pageindicator can be used to condition the heading lines to be printed beforethe program processes the first record.

The first page indicator is internally defined and controlled. It cannot beset on or off by the programmer. It is on when a program starts up, andremains on until just before the first record is read by the program. Thepurpose of the first page indicator is to allow the programmer to outputheading information on a report during the first cycle before a record isread by the program.

The first page indicator can be used to condition detail or heading outputlines. It cannot be used to condition total time or exception output lines. Ifa detail or heading output line is not to be output during the first cycle andis conditioned by all negative indicators or has no indicators associated toit, use a not-first page (N1P) indicator to prevent the line from beingoutput during the first cycle.

The following example shows how to use the 1P indicator to print aheading on the first page of a report:

Example 12–13 First Page Indicator Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*00170OREPORT H 201 1P00180O OR OF00190O UDATE Y 1000200O 39 ’SALES REPORT’00210O 64 ’PAGE’00220O PAGE 6800230O H 22 1P00240O OR OF00250O 4 ’ITEM’00260O 23 ’DESCRIPTION’00270O 35 ’SALES’00280O 47 ’COST’00290O 60 ’PROFIT’

In this example, the output records defined on lines 170 - 180 and230 - 240 will be output during the first cycle, ensuring that the programhas 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 reportwhen the specifications in Example 12–13 are executed during the firstcycle.


1 2 3 4 5 61234567890123456789012345678901234567890123456789012345678901234567802/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 outputoperations which will occur at the end of the program. Like the first cyclein 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-fileprocessing was specified has been read, the Last Record (LR) indicator isset on. When the Last Record indicator is turned on, all control breakindicators (L1 - L9) are also turned on. This ensures that during the lastcycle, all total time calculations and output will be performed.

If a program does not contain a primary file or the primary file isassociated to a WORKSTN or KEYBORD device, the LR indicator must beset by the programmer to end execution of the program. When setting theLR 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 placebefore the program terminates.

• If the LR indicator is set on during detail calculations, all control breakindicators (L1 - L9) are set on at the beginning of the next cycle andtotal 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 beencompleted. Any control break indicators (L1 - L9) which were not onat this time will not be turned on.

The LR indicator is always represented by LR, as shown in the followingexample:

Example 12–15 Last Record Indicator Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*00360O T 1 LR00370O 6 ’TOTALS’00380O TSALES1 35 ’$’00390O TCOST 1 48 ’$’00400O TPROFT1 60 ’$’

The following information will be output after processing the last record inExample 12–15:


1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890TOTALS $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 theprogrammer. It can be used to condition total time and control breakoperations, even when control break fields have not been specified. If nocontrol breaks have been defined, but total time calculations and outputare desired, use the L0 indicator to condition those operations.

The Level Zero indicator can only be used in columns 7 - 8 of theCalculation specifications and columns 23 - 31 of the Output specifications.

In the following example, total time calculations and output are to beperformed when a record with a B in position one is read from the SALESfile. The L0 indicator is used to define the total time operations and the02 indicator is used to determine when they will be executed.

Example 12–17 Level Zero Indicator Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890

*00050ISALES AA 01 1 CA00060I 01 04 REGION00070I 05 08 DIST00080I 09 38 SALNAM00090I 39 44 SALEID00100I P 45 492SALES00050I BB 02 1 CB

.

.

.00320CL0 02 REGTOT ADD GRAND GRAND 102

.

.

.00510OREPORT T L0 0200520O 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 processingprimary and secondary input and update files. When more than oneprimary and secondary file is in use, RPG multifile logic supplies a methodfor selecting the next record to process via the matching record function.

When processing records from primary and secondary input and updatefiles, the matching record function can be used to determine which recordwill be processed next. To select the next record for processing, fieldswithin the primary and secondary data records are compared. These fieldsare called match fields and are designated using the codes M1 - M9 incolumns 61 - 62 of the Input specifications.

If all of the match fields match, the MR indicator is turned on and therecord from the secondary file is processed. If the match fields do notmatch, a record from the primary file is processed and the MR indicatoris turned off. The MR indicator can be used to condition operations whichshould only occur when records match.

The MR indicator is set immediately after total time operations areperformed. At detail time, the MR indicator indicates the match statusof the record just read for processing. At total time, the MR indicatorindicates 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 612345678901234567890123456789012345678901234567890123456789012

*00003FMRGIA IP AF 40 40 DISK00004FMRGIB IS AF 40 40 DISK

.

.

.00006IMRGIA NS 01 01 CA00007I 1 1 COD00008I 2 40KEY M100012IMRGIB NS 03 01 CB00013I 1 1 FUD00014I 2 40CORE M1

.

.

.00050C MR MOVE CORE DUP00051C MR ADD 1 DUPCNT

.

.

.01410O D 1 MR01420O 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 COREmatch, a record is read from the secondary file (MRGIB) and the MRindicator is turned on. Turning the MR indicator on will cause thecalculation operations on lines 50 and 51 and the output operations onlines 1410 - 1430 to be executed.

If the contents of the KEY and CORE fields do not match, a record is readfrom the primary file (MRGIA) and the MR indicator is turned off.

12–29

Using Indicators

12.5.5 External IndicatorsExternal indicators (U1 - U8) are indicators which can be set prior torunning an RPG program. External indicators can be used to control thefollowing 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 commandprocedure or by another program. They are automatically read into anRPG program or subprogram when it is initialized. They can be modifiedby the current program using the SETON and SETOF operations andpassed on to another program or procedure. See the Migration RPG User’sGuide for more information concerning the REX Utility.

When an external indicator is used to condition a file, the file is openedonly if the external indicator is set on. If the external indicator is setoff, the file is placed in an end-of-file state at program startup andignored. It is advisable to use the file conditioning external indicatoras a conditioning indicator on calculation and output operations related tothe file, preventing them from being executed when the file is not availablefor processing.

Example 12–19 External Indicator Usage

1 2 3 4 5 6 7123456789012345678901234567890123456789012345678901234567890123456789012

*00003FHOOSER IPE F 80 DISK00004FFROSTY USE F 140 DISK U1

.

.

.00050C U1 MOVE SNOW MAN

.

.

.01410OFROSTY D U101420O MAN 10

In this example, the file FROSTY will not be available for processingunless the external indicator U1 is on. If U1 is on, the file will be openedand the calculation and output operations on lines 50 and 1410 - 1420 willbe performed. If U1 is off, the file will not be opened and the operationson these lines will be ignored.

12–30

Using Indicators

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

12.6.1 *IN and *IN,xxThe special word *IN is a predefined array with 99, one-position, characterelements. The elements in this array represent indicators 01 - 99. Use*IN,xx, where xx is the array index, to reference an indicator. Forexample, *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 elementare 0, the indicator is off. If the contents of the element are 1, theindicator is on. The *IN indicator array reference (xx) can be a numericliteral or field with a value of 1 - 99.

The *IN array and array elements can be used to reference an indicatoranywhere any other one-character array or array element can be usedwithin an RPG program. To prevent unpredictable results when usingindicators 01 - 99, place only the characters 0 or 1 in each element. Whenthe program is initialized, all elements in the *IN array are set to 0.

In the following example, the program tests whether the setting forindicator 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,20produces the same result as using the SETON operation code to set onindicator 20.

Example 12–20 *IN Indicator Array And Element Usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*C *IN,20 COMP *IN,15 99C MOVE ’1’ *IN,20

12–31

Using Indicators

12.6.2 *INxxThe special word *INxx is a predefined, single-character, alphameric fieldwhere 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, alphamericfield can be used.

In the following example, the value of the indicator 20 is checked in an IFoperation. 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 512345678901234567890123456789012345678901234567890123456789

*C MOVE ’1’ ON 1C MOVE ’0’ OFF 1

.

.

.C *IN,20 IFEQ ONC READ TRIPLX 99C END

12–32

13 Using DISK Files

A file is a collection of information that is organized into groups or sectionscalled records. Each record consists of one or more blocks of characters ornumbers called fields.

This chapter explains the Migration RPG file organizations andrecord operations that are implemented through the OpenVMS RecordManagement Services (RMS). For additional information on fileorganization and file and record operations, see the OpenVMS RecordManagement Services Reference Manual.

13.1 File CharacteristicsFiles are created, modified, and processed according to their respectivecharacteristics, which are chosen to make the most efficient use of bothsystem resources and the data in the files. Significant characteristics offiles used in RPG programs are the file type, designation, and mode ofprocessing.

The file type used in an RPG program determines how the records in thefiles 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 whichthe 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 completedescription of the file type and designation codes.

13–1

Using DISK Files

13.2 File NamesColumns 7 - 14 (File name) of the File Description specification define thefile name. RPG uses the entry in columns 7 - 14 and the entry in columns47 - 52 (Symbolic device) to associate the file name with the OpenVMS filespecification. The default DISK file type is .DAT.

The entry in columns 7 - 14 can be used as a logical name representingthe OpenVMS file specification. If a logical name is not defined as theentry in columns 7 - 14, the file specification will consist of the file namein columns 7 - 14 and the file type .DAT. For example, if columns 7 - 14contain the name PURRBALL, and no logical name PURRBALL has beendefined, the program will search for a file labeled PURRBALL.DAT. Usinglogical file names with an RPG program is discussed in more detail in theRPG User’s Guide.

13.3 Record FormatsThe records in a file can all be the same length (fixed) or of differentlengths (variable). Most RPG applications use fixed-length records.

13.4 File TypesFiles 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. TheMigration RPG Screen Format Reference Manual describes the use of aWORKSTN device.

13–2

Using DISK Files

13.5 File OrganizationsThe 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 OrganizationSequential file organization is available on all types of devices. Sequentialfiles contain records in the order that they were written. The first logicalrecord in the file is always in the first physical record position, the secondlogical 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 foundbetween 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, byreading through the entire file from beginning to end, or randomly, byusing relative record numbers or an addrout file.

13.5.2 Relative OrganizationRelative file organization is available on disk devices only. A relative fileis a sequential file using fixed-length records. The relative record numberindicates the record’s position relative to the beginning of the file. Therelative record number of the first record is always 1. Each record writtenis assigned to a specific location within the file. Records can be randomlywritten to a relative file. For example, a record can be written to thefourth location within a relative file by assigning it relative record number4. 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 RecordNumber

A B D C

Relative files can be accessed sequentially, randomly using the CHAINoperation code, or randomly using an addrout file. When accessing arelative file sequentially, empty cells are skipped. When accessing arelative file randomly using the CHAIN operation, the indicator specifiedin columns 54 - 55 of the Calculation specification will be set on if anempty record is accessed.

By default, when a relative file is created under RMS, it contains norecords. If an RPG program expects a relative file to contain predefinedrecord locations, the file must be seeded with blank records before it isaccessed by the program. This is easily accomplished using a program orprocedure.

13.5.3 Indexed OrganizationIndexed file organization is available on disk devices only. Each record inan indexed file contains an index key value, as shown in Figure 13–3.

Figure 13–3 Indexed File Organization

Index KeyValue

Data

| Record |

An index key value is a field within each record that is defined by itsrelative location within the record and by its length. The index key valueis the primary means of locating records within the file. For example,an employee’s badge number could be used as the index key value foran employee record. The index key value in Figure 13–4 is the first sixcharacters 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 usingindex key values, randomly using an addrout file, or sequentially withinlimits. See Section 13.6.1.3 for more information on accessing an indexedfile sequentially within limits.

13.6 File Access MethodsThere are several ways of accessing the records within a file. Fileaccess methods are dependent on the file’s organization. Chapter 4,File Description Specification (F), contains detailed descriptions of all ofthe possible file access combinations within an RPG program.

Although the organization of a file is not usually changed after it has beencreated, the file access method can be changed. The method used dependson how many records the file contains and how often the file is accessed.Use the following guidelines in selecting a file organization and accessmethod:

• If all records in a file are processed from beginning to end (as ina payroll application), use a sequential file and access the recordssequentially.

• If access to some or all records within a file is needed under changingor 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 provideprogramming guidelines for each.

13.6.1 Sequential AccessWhen accessing a file sequentially, each input operation retrieves the nextrecord in the file, regardless of the file organization, until either end-of-fileis reached or the program terminates. For an indexed file, records areretrieved in the order of the specified key (the default is the primary key).

The following types of sequential access are possible within an RPGprogram:

• 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 AccessSimple sequential file access involves reading a file consecutively frombeginning 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 madein 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 tobe opened for input or for update.

• Column 16 (file designation) - specify P, S, D, or F to indicate whetherthe input file is primary, secondary, demand, or full-procedural.

• Column 19 (record format) - specify F or V to describe the recordformat (fixed-length or variable).

• Columns 24 - 27 (record length) - specify the length of fixed-lengthrecords or the maximum length of variable-length records.

• Columns 40 - 43 (device code) - specify DISK.

• Columns 71 - 72 (external indicators) - external indicators U1 - U8 canbe specified to indicate whether the file is to be accessed. An externalindicator based file is accessed if the external indicator is on.

The following example specifies the name of a file, SHASTA, designated asan input primary file with fixed-length records and a record length of 60bytes:

Example 13–1 File Description specification for a primary sequentialfile - Sequential file access

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*FSHASTA IPE F 60 DISK

13.6.1.2 Sequential Access by KeyOnly indexed primary, secondary, demand, and full-procedural files canbe processed sequentially by key. RMS reads records in ascending keysequence until it reaches end-of-file or the program terminates.

To specify sequential access by key for a file, the following entries must bemade 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 toindicate 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 anindexed file.

• Columns 35 - 38 (key location) - specify the starting character positionof the key field.



The following example shows how to specify a primary input file, ZONKwith fixed-length records 120 bytes long. The file organization is indexedwith its index key in packed-decimal data format.

Example 13–2 File Description specification for a primary sequentialfile - Sequential access by key

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*FZONK IPE F 120 3PI 1 DISK

13.6.1.3 Sequential Access Within LimitsIndexed files can be processed sequentially within limits using one of twomethods:

• By creating a record-limits file that specifies a range of index keys ineach record.

• By using the SETLL operation.

Both methods permit the programmer to limit the records which theprogram can access.

To access a file sequentially within limits, make the following entries inthe File Description specifications:






13–7

Using DISK Files

• Column 28 (access mode) - specify L to indicate that the indexed file isto be processed sequentially within limits.




• Columns 35 - 38 (key location) - specify the starting character positionof 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 beprocessed sequentially within limits. The file organization is indexed; thekey 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 6123456789012345678901234567890123456789012345678901234567890123456

*FEMPMST IP F 180L 8AI 1 DISK

13.6.1.3.1 Using a Limits FileA limits file allows a low and high range to be specified via a file’s key fieldbefore the file is accessed by the program. The low and high key valuesare specified in the limits file, which is associated to the data file using anExtension specification

When a program is processing an indexed file using key field limits, alimits record is first read from the limits file. The program then beginsreading records sequentially from the indexed file, starting with the lowkey value specified in the limits record. When the high limits value inthe limits record is reached, the program reads another limits recordsand begins reading records from the indexed file again, starting with thenew low key value supplied by the limits file. A limits file can contain asmany limits records as the programmer desires. Processing of the programwill continue until the end of the limits file is reached or the program isterminated.

The low and high limits values can overlap between limits records, andthe same limits values can be used more than once, allowing the same setof records to be processed repeatedly.

13–8

Using DISK Files

Figure 13–5 presents an example of how limits file processing works. Thefirst record in the record-limits file causes the program to retrieve thoserecords whose keys are greater than or equal to the low key (C) and lessthan or equal to the high key (E). When the program reaches a record witha key value greater than E or reaches end-of-file, it reads the next recordfrom the record-limits file to get a new low and high range. The secondrecord in the record-limits file causes the program to retrieve those recordswhose keys are greater than or equal to the low key (A) and less than orequal to the high key (D). The indexed file is processed until it reaches theend of the record-limits file or the program terminates.

Figure 13–5 Sequential File Access Within Limits

Data File Record LimitsFile

Data

A C E First record

Second record

| Record |

Key

data

B A Ddata

C

Low limitHigh limit

data

D data

E data

F data

Rules

• In the record-limits file, only one set of limits can be specified perrecord.

• The record length of the limits file must be at least twice the length ofthe indexed file key field.

• The low key must begin in character position 1, and the high key mustimmediately follow the low key.

• The length of the high and low keys must be the same and must beequal 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 thedata file and the limits file do not have to match. For example, thelimits file could use a zoned-decimal or trailing numeric format whilethe indexed file used a packed-decimal format. If the key formatsdiffer, the key field format must be indicated by an entry in column 31of the File Description specifications and the unpacked length of eachfield must match.

• Numeric keys cannot contain blanks; use leading zeros if it isnecessary 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-contiguouskey, the keys specified within the limits file must contain all of thesubfields 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 Extensionspecifications. The limits file does not require any Input specifications.

To access a file sequentially within limits, the following entries must bemade in the File Description specifications for the record-limits file:


• Column 15 (file type) - specify I to indicate that the file is to be openedfor input.

• Column 16 (file designation) - specify R to indicate that the file namedin 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).

• Columns 24 - 27 (record length) - specify the length of fixed-lengthrecords.


• Column 31 (record address type) - specify either A, P, or blank toindicate that the index keys are in character (blank or A) or packed-decimal (P) format.

• Column 39 (extension) - specify E to cause the compiler to look for anExtension specification.



When specifying a limits file, the following entries must be made in theExtension specifications:

• Columns 11 - 18 (from file name) - specify the name of the record-limitsfile.

• Columns 19 - 26 (to file name) - specify the name of the file to beprocessed by the record-limits file.

The following example shows how to specify the File Description andExtension specifications for processing a file sequentially within limits. Inthe example, the limits file EMPLMT is associated to the indexed data fileEMPMST. The EMPMST file will be processed within the limits obtainedfrom the EMPLMT file.

13–10

Using DISK Files

Example 13–4 File Description and Extension specifications for aprimary indexed file - Sequential access within limits

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*FEMPLMT IRE F 16 8 EDISKFEMPMST IP F 180L 8AI 1 DISKE EMPLMT EMPMST

13.6.1.3.2 Using the SETLL OperationLimits processing against an indexed file can also be accomplished usingthe SETLL (Set Lower Limit) operation code in the Calculations section ofa program. The SETLL operation positions the record pointer within a fileat the record with a key that is greater than or equal to the key specifiedin 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 anddemand indexed files that are being processed sequentially within limits.The File Description specification for the SETLL file must have an F or Din column 16 and an L in column 28.

Factor 1 of the SETLL operation is used to specify the key value that is tobe the lower-limit of the file. The entry must have the same format andlength as the key field of the file being read.

Factor 2 is used to specify the name of the file being read. The file mustbe a full-procedural or demand indexed file being processed within limits.The file name must match the name specified in columns 7 - 14 of theFile Description specification. When a SETLL operation is performed, thefile record pointer is set at the record with the key that is greater thanor equal to the key specified in factor 1. Subsequent READ, READE, andREADP operations will begin from that point. When end-of-file is reachedon a limits file, another SETLL operation can be used to reposition therecord pointer in the file.

A record-address file specifying a limits file and the SETLL operationcannot 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 512345678901234567890123456789012345678901234567890123456789

HFEMPMST IF F 132L 8AI 1 DISKFREQUEST CD F 32 WORKSTN

.

.

.IEMPMST AA 01I 1 80BADGE

.

.

.IREQUEST BB 02I 1 80BADGE

.

.

.C READ REQUEST 99C N99 BADGE SETLLEMPMSTC N99 READ EMPMST 99

In this example, the SETLL operation is used to position a pointer in theEMPMST file based on an employee badge number. The user entersa badge number via a workstation into the REQUEST record. Thevalue is placed in the field BADGE. The field BADGE is used by theSETLL operation to position the file pointer for the subsequent READoperation. Note that SETLL and READ operations for the EMPMST fileare conditioned by indicator 99. If the workstation read processes anexception, indicator 99 be turned on and the following SETLL and READoperations will not be performed.

13.6.2 Random AccessAccessing records randomly allows records to be retrieved or writtenanywhere in a file. To do this, the record location must be specified usingone of the following methods:

• Relative record numbers

• Keys

• An addrout file

The methods available to randomly access a file depend upon theorganization of the file. The following sections describe the methodswhich can be used for random file access.

13.6.2.1 Random Access by Relative Record NumberSequential and relative files can be accessed randomly by specifying therelative record number that identifies the desired record relative to thebeginning of the file. For example, the relative record number for the fifthrecord is 5. Accessing a sequential file using this method requires that thefile 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 entriesmust be made in the File Description specifications:



• Column 16 (file designation) - specify C or F to indicate whether thefile named in columns 7 through 14 is a chained or full-procedural file.

• Column 19 (record format) - specify F or V to describe the recordformat (fixed-length or variable). Sequential files must use fixed-lengthrecords.


• Column 28 (mode) - specify R to cause the program to access the filerandomly, using a relative record number.



The following entries must be made in the Calculation specifications toaccess the file randomly using a relative record number:

• Columns 18 - 27 (factor 1) - specify the relative record number of therecord 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 recordcondition for a relative file. Otherwise, attempting to use the CHAINoperation code to randomly access a non-existant record will cause arun-time error.

• Columns 33 - 42 (factor 2) - specify the name of the file that containsthe record which is to be retrieved.

The following example depicts how random access by relative recordnumber can be used. In the example, the primary file CHKLST isprocessed sequentially. After each record from the CHKLST file is read,the ITMNUM field is used to CHAIN to the INVENTRY file (line 130) andobtain the INVENTRY record. The QTYSLD field is then updated usingan EXCPT output operation (lines 150 - 190) and the transaction is loggedon a report (lines 330 - 360).

Note the use of the record-not-found indicator, 50. If 50 is turned on, theexception output (lines 150 - 190) is not performed and a line indicatingthe 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 51234567890123456789012345678901234567890123456789012345678900001H00010FCHKLST IPE F 10 DISK00020FINVENTRYUC F 120R DISK00030FREPORT O F 80 OF PRINTER00040 *00050ICHKLST AA 0100060I 1 50ITMNUM00070I 6 100QTY00080IINVENTRYAB 0200090I 1 50ITMNUM00100I P 21 250QTYSLD00110I P 26 300VALUE00120 *00130C ITMNUM CHAININVENTRY 5000140C *IN50 IFNE ’1’00150C ADD QTY QTYSLD00160C VALUE MULT QTY SALE 7000170C SETON 4000180C EXCPT00190C SETOF 4000200C END00210 *00220OINVENTRYE 4000230O ITMNUM 500240O QTYSLD 25P00250OREPORT H 22 1P00260O OR OF00270O 22 ’STORE PURCHASES’00280OREPORT H 1P00290O OR OF00300O 06 ’ITEM #’00310O 22 ’QUANTITY SOLD’00320O 30 ’PRICE’00330O D 01N5000340O ITMNUM 0500350O QTYSLD 1800360O SALE 1 31 ’$’00370O D 01 5000380O ITMNUM 0500390O 20 ’ITEM NOT FOUND’

13.6.2.2 Random Access by KeyRecords can be retrieved randomly from an indexed file by specifying theirindex keys. Only indexed files specified as chained or full procedural canbe accessed randomly by key.

To access a file randomly by key, the following entries must be made in itsFile Description specification:



• Column 16 (file designation) - specify C or F to indicate whether thefile named in columns 7 - 14 is a chained or full-procedural file. Ifthe file is using a non-contiguous key, it must be designated a fullprocedural file (F).


13–14

Using DISK Files


• Column 28 (mode) - specify R to access records randomly using indexkey values.

• Columns 29 - 30 (key length) - specify the length of the key field. If anon-contiguous key is being used, specify the total length of all of thekey segments.



• Columns 35 - 38 (key location) - specify the starting character positionof the key field. If the key is non-contiguous, specify EXTK.


• Columns 68 - 69 can be used to specify an alternate key (01 - 99). Ifthe columns are left blank, the compiler will assume that the primarykey (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 todescribe a CHAIN operation:

• Columns 18 - 27 (factor 1) - specify the index key of the record to beretrieved. This can be a data field or a literal.

• Columns 28 - 32 (operation code) - use the CHAIN operation code. Thespecified record can be read from the file either during detail-time ortotal-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 indicateend-of-file and error conditions, respectively.

The CHAIN operation code is described in detail in Chapter 11, OperationCodes.

The following example randomly accesses the indexed file GROCER usingkeys. 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 therecord with the same key. If the record is not found, indicator 50 is turnedon. Information retrieved from the GROCER file is placed in the outputfile REPORT.

13–15

Using DISK Files

Example 13–7 Random access by key

1 2 3 4 51234567890123456789012345678901234567890123456789012345678900010FSTORES IP F 130 DISK00020FGROCER IC F 100R10AI 1 DISK00030FREPORT O F 30 PRINTER00040ISTORES AA 0100050I 1 11 STORE00060I 12 210ITEM00070IGROCER AB 0200080I 1 100REC00090I 11 130COUNT00100I 14 17 VALUE00110C ITEM CHAINGROCER 5000120C 50 SETON LR00130OREPORT H 22 1P00140O 22 ’STORE PURCHASES’00150O D 01N5000160O STORE 1400170O COUNT 2000180O VALUE 2700190O D 01 5000200O ITEM 1000210O 25 ’ITEM NOT FOUND’

13.6.2.3 Random Access by Addrout FileRecords in sequential, relative, or indexed files can be accessed using anaddress output (addrout) file. Addrout files are created by the OpenVMSSort/Merge Utility using the /PROCESS=ADDRESS qualifier and containrecord addresses rather than full data records. The addrout file can thenbe accessed by a program and the record address information used toselect 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 usingthe SORT/PROCESS=ADDRESS command. The SORT/MERGE Utility isdiscussed 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

Address of B

Address of C

Address of D

SORT/PROCESS=ADDRESS/KEY=(POS:1,SIZ:1) −FUZZ.DAT ADDROUT.DAT

C data 94837

D data 47382

B data 10382

Each record in the addrout file corresponds to a record in the originalfile. The addresses of the records are referred to as Record File Addresses(RFA’s) by RMS. For additional information on RFA’s, see the OpenVMSRecord Management Services Reference Manual.

When accessing a data file using an addrout file, the program first reads arecord from the addrout file. It then uses the record address contained inthe addrout record to retrieve a record from the data file. The addrout fileis processed sequentially by the program, while the corresponding data fileis processed randomly by record address.

Using an addrout file to access a data file requires a File Description andExtension specification for the addrout file and a File Description andInput specifications for the data file. No Input specifications are requiredfor 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 openedfor input.

• Column 16 (file designation) - specify R to indicate that the file namedin 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 addressesare always 6 bytes in length. NOTE: An entry of 3 is also acceptableand will be translated by the compiler to 6. The entry of 3 issupported as a compatibility feature for porting IBM System/36 RPGII applications.

• Columns 29 - 30 (key length) - specify 6 because key addresses arealways 6 bytes in length. NOTE: An entry of 3 is also acceptable andwill be translated by the compiler to 6. The entry of 3 is supported asa compatibility feature for porting IBM System/36 RPG II applications.

• Column 31 (record address type) - specify I to indicate that this is anaddrout 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 Extensionspecification is associated with this File Description specification.



The following entries are required in an Extension specification toassociate the addrout file to a data file:

• Columns 11 - 18 (from file name) - specify the name of the addroutfile as it was specified in columns 7 - 14 of its File Descriptionspecification.

• Columns 19 - 26 (to file name) - specify the name of the data file to beprocessed by the addrout file as it was specified in columns 7 - 14 of itsFile Description specification.

The following entries are required in the File Description specification forthe data file which is associated to the addrout file:


• Column 15 (file type) - specify I or U to indicate whether the file is tobe opened for input or update.

• Column 16 (file designation) - specify P or S to indicate that the filenamed 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 anindexed file is being accessed.

• Column 31 (record address type) - specify I to cause the program toaccess the file according to the addrout file.

• Column 32 (file organization) - specify I if an indexed file is beingaccessed.



The following example depicts the sort command used to create an addroutfile and a program which uses the addrout file. The sort command uses the/PROCESS=ADDRESS qualifier to create an address output file orderedby zip code. The program then uses the addrout file to read the data fileTOWNINFO 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 specificiationsand 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 512345678901234567890123456789012345678901234567890123456789

HFADDROUT IRE F 6 6IT EDISKFTOWNINFOIP F 120R 6II 30 DISKFREPORT O F 80 80 OF PRINTERE ADDROUT TOWNINFOITOWNINFOAA 01I 1 12 TOWNI 13 14 STATEI 15 25 COUNTYI 26 30 ZIPOREPORT H 202 1PO OR OFO 12 ’TOWN LIST’O UDATE Y 70O PAGE 80OREPORT D 01O TOWN 12OREPORT D 01O COUNTY 11OREPORT D 3 01O STATE 02O ZIP 10

13.6.3 Sequential Access and Random Access by KeyA full-procedural file is defined by an F in column 16 of the FileDescription specification and allows a file to be read both randomly andsequentially. Only indexed files can be defined as full-procedural files.A full-procedural file can be read randomly using the CHAIN operationand sequentially using the READ, READE, and READP operations. Atleast one CHAIN, READ, or READP operation must be coded in theCalculations section of a program to retrieve data from a full-proceduralfile.

To specify a full-procedural file, make the following entries for the file inits File Description specification:


• Column 15 (file type) - specify I or U to indicate that the file is to beopened for input or update.

• Column 16 (file designation) - specify F to indicate a full-proceduralfile.




13–19

Using DISK Files



• Columns 35 - 38 (key location) - specify the starting character positionof the key field. If the key is non-contiguous, specify EXTK.


• Columns 68 - 69 can be used to specify an alternate key (01 - 99). Ifthe columns are left blank, the compiler will assume that the primarykey (00) is being described.


The following example specifies the full-procedural file FPFJ01 to beaccessed by a CHAIN operation with the key specified in FPFI01. The fileFPFJ01 is then processed sequentially from that point on.

Example 13–9 Random and sequential access using a full-proceduralfile

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*FFPFJ01 IF F 80L 5AI 2 DISK*IFPFJ01 XX 01I 1 1 XSTATI 2 6 KEYFLDI 7 11 FLD1I 12 16 FLD2*

.

.

.*C KEYFLD CHAINFPFJ01 50C 50 GOTO END*C LOOP TAGC READ FPFJ01 90C 90 GOTO END

.

.

.*C END TAGC SETON LR*

.

.

.

13–20

Using DISK Files

13.7 Creating FilesThere are a variety of ways to create files with sequential, relative, andindexed organizations. Sections 13.7.1 through 13.7.3 describe how tocreate files using a RPG program.

13.7.1 Creating Sequential FilesSequential files are created by writing consecutive records to an outputfile. After a sequential file is created, it can be used as an input file, anupdate file, or an output file with the ADD option.

To create a sequential file, make the following entries in the FileDescription specification:


• Column 15 (file type) - specify O to indicate the creation of an outputfile.


• 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 512345678901234567890123456789012345678901234567890123456789

H*FOUTI24 IP F 24 DISKFOUT60A O F 24 DISK*IOUTI24 AA 01I 1 3 PNI 4 10 PNAMEI 11 12 WHOUSEI 13 17 COLORI 18 200WEIGHTI 21 240QTY*OOUT60A D 01O PN 3O PNAME 10O WHOUSE 12O COLOR 17O WEIGHT 20O QTY 24


13–21

Using DISK Files

Example 13–10 (Cont.) Creating a sequential file

This example demonstrates how to create a sequential file. Duringprogram 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 FilesA relative file can be created by specifying a chained output file. To dothis, make the following entries in its File Description specification:



• Column 16 (file designation) - specify C to indicate that the file namedin 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. Relativefiles must always use a fixed-length record format. To add records tospecific locations within a relative file, the file must first be populated withrecords.

13.7.3 Creating Indexed FilesAn indexed file can be created either in unordered key sequence or inordered key sequence. If an unordered sequence is specified, records canbe 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 orderof their key; the order must be ascending. After the file is created, RMSsorts the index keys in ascending order, regardless of the order in whichthey were written.

To create an indexed file in ordered sequence, make the following entriesin its File Description specification:



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 indicatethat 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 characterposition of the key field.


Example 13–11 Creating an indexed file

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

H*FOUTI24 IP F 24 DISKFOUT60I O F 24 3AI 1 DISK*IOUTI24 AA 01I 1 3 PNI 4 10 PNAMEI 11 12 WHOUSEI 13 17 COLORI 18 200WEIGHTI 21 240QTY*OOUT60I D 01O PN 3O PNAME 10O WHOUSE 12O COLOR 17O WEIGHT 20O QTY 24

This example demonstrates how to create a single key indexed file. Duringprogram startup, the indexed output file OUT60I.DAT will be created. Thefile will contain a single ascending key. The key will start in position 1and have a length of 3 characters. The program reads data from the inputfile OUTI24.DAT and writes it to the indexed file OUT60I.DAT.

By default Migration RPG creates indexed files with a primary key thatdoes not allow duplicates. If duplicate primary keys are desired, or if thefile needs to be defined with additional keys, create the file using the DCLCREATE utility with the /FDL parameter. Data can then be added tothe file by defining is as an output add file (A in column 66 of the Filespecification).

13–23

Using DISK Files

13.8 Adding Records to FilesAfter 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, orby using exception output. Sections 13.8.1 through 13.8.3 explain how toadd records to files on the basis of their file organization.

13.8.1 Adding Records to a Sequential FileBecause the location of each record in a sequential file is fixed in relationto all others, there is no unused space where a new record might beinserted. Therefore, new records can only be added to the end of asequential file.

To add a record to the end of a sequential file, make the following entriesin its File Description specification:


• Column 15 (file type) - specify O to indicate the creation of a newrecord.



• Column 66 (file addition) - specify A to cause RPG to add new recordsto 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 beadded.

Example 13–12 Adding records to a sequential file

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

H*FINFO IP F 80 DISKFLOG O F 80 DISK A*IINFO AA 01I 1 80 DATA*OLOG DADD 01O 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. Datafrom the file INFO is appended to the file LOG. The A in column 66 of theLOG File specification signifies that the file is an output add file. ADD isrequired in columns 16 - 18 of the LOG Output specification to allow newrecords to be added to the file.

13.8.2 Adding Records to a Relative FileTo add a new record to a relative file, either specify the relative recordnumber 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 entriesfor the file in its File Description specification:


• Column 15 (file type) - specify I or U to indicate that the file is to beopened for input or update.

• Column 16 (file designation) - specify C or F to indicate a chained orfull-procedural file.



• Column 28 (mode) - specify R to access records randomly, using arelative 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 FileIf the file is an indexed file, records can be added at any location. The keyvalues for the new records are placed in the index and the entire index issorted in ascending sequence.

Note: When adding records to an indexed file, "A" cannot be specify incolumn 66 (file addition) of the File Description specification for

13–25

Using DISK Files

indexed files processed sequentially within limits or processed byan addrout file.

New records can be added to an indexed file while processing the fileby specifying an "A" in column 66 (file addition) of the File Descriptionspecification. The file can be an input or update file that is processedsequentially 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 beadded.

Example 13–13 Adding records to an indexed file

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

H*FNEWDATA IP F 80 DISKFMASTER UC F 80R 5AI 2 DISK A*INEWDATA AA 01I 1 1 STATUSI 2 6 KEYI 7 80 DATA*IMASTER XX*C 01 KEY CHAINMASTER 99*OMASTER DADD 01N99O STATUS 01O KEY 06O DATA 80

This example demonstrates how to add records to an indexed file. Datafrom the file NEWDATA is added to the file MASTER. The A in column66 of the MASTER File specification signifies that the file allows recordsto be added. ADD is required in columns 16 - 18 of the MASTER Outputspecification to allow new records to be added to the file.

Note the use of the CHAIN operation in the Calculation specifications toensure that the program does not attempt to output data to a record thatalready exists in the MASTER file.

13.9 Updating Records in FilesMigration RPG allows records to be updated in primary, secondary,demand, full-procedural, or chained files. RPG allows record updatesin a sequential file only if the records are of fixed length. Records can beupdated in a primary or secondary file only once during the program cycleat 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 totaltime.

13–26

Using DISK Files

To update a record, retrieve the record to change, change the contents, andthen write the record back to the file. Only the fields to be changed needto be specify in a record. The remainder of the record is rewritten usingthe data that was read into the input buffer. A data structure can be usedto update a record instead of outputting individual fields.

Example 13–14 Updating records in an indexed file

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

H*FTRANSACTIP F 25 DISKFMASTER UC F 80R21AI 1 DISK*ITRANSACTAA 01I 1 20 NAMEI 21 25 NEW#*

0010 IMASTER BB 10 1 CA0020 I CC 20 1 CB0030 I DD 99

*C N01 GOTO END** Update record type 10.*C MOVEL’A’ KEY 21C MOVE NAME KEYC KEY CHAINMASTER 99C N99 EXCPT** Update record type 20.*C MOVEL’B’ KEYC MOVE NAME KEYC KEY CHAINMASTER 99C N99 EXCPT*C END TAG*OMASTER E 01 10O NEW# 40OMASTER E 01 20O NEW# 60

This example demonstrates accessing and updating two types of recordsin the file MASTER. The record type on line 10 is identified by an "A" incolumn 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 notbegin with "A" or "B". The field NEW# is output to different locationsbased on the record type.

To update the records in a relative or indexed file and simultaneously addnew records, make the following entries for the file in its File Descriptionspecification:

• Column 15 (file type) - specify U to indicate that the file is to be openedfor 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 thatidentify the records to be added. The output records without ADD incolumns 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-proceduralfile. To specify an indexed full-procedural file to be processed in theupdate mode, make the following entries for the file in its File Descriptionspecification:

• Column 15 (file type) - specify U to indicate that the file is to be openedfor update.

• Column 16 (file designation) - specify F to indicate a full-proceduralfile.

• Column 32 (file organization) - specify I to indicate an indexed file.

13.10 Deleting Records from FilesRecords can only be deleted from files defined as update or full procedural.To prevent the unintentional deletion of records, perform the followingsteps:

• Retrieve the record.

• Evaluate its contents.

• Based on the results of the evaluation, set an indicator to controldeletion of the record.

The last record retrieved from the file is the one that is deleted whenDEL is specified in columns 16 - 18 of the Output specification. There isno need to describe any fields in the output record because the operationdeletes the entire record.

Example 13–15 Deleting records from an indexed file

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

H*FDELETE IP F 20 DISKFMASTER UC F 80R20AI 2 DISK*IDELETE AA 01I 1 20 NAME*IMASTER BB*C 01 NAME CHAINMASTER 99C 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 recordis read from the file DELETE. The field NAME is used to CHAIN to theassociated record in the MASTER file. If the MASTER record is found,it is deleted. Note the use of the EXCPT name REMOVE to control thedelete function in the Output specifications.

13.11 Processing Files with Matching RecordsMatching fields can be used with primary and secondary files to check thesequence of records and to define the order in which records are selectedfrom 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 checkedby specifying a matching field value (M1 through M9) in columns 61 and62 in the Input specification. Then, the program checks the sequence bycomparing the matching field of one record with the matching field of theprevious record. If the field is out of order, a run-time error occurs.

13.11.1 Checking Record Sequence for One Record TypeDesignate a record sequence by specifying A or D (ascending ordescending) in column 18 of the File Description specification. Assigna matching field value (M1 through M9) to one or more of the fields to beused as matching fields in columns 61 and 62 (matching field) of the Inputspecification. If more than one matching field is specified, assign M9 tothe most important field. The program considers all matching fields as onecontiguous field with the M9 field in the leftmost position, next to the M8field, and so on, until it reaches M1, even though the fields may not beadjacent in the record or in numeric (M9 through M1) order.

13.11.2 Checking Record Sequence for More Than One Record TypeThe fields in a record of one type can be in a different order than thefields in other record types in the same file. For example, in a payroll fileconsisting of two different record types, one type represents commissionpayment and the other type represents salary. All employee records areto be in ascending sequence according to district (DSTRCT). Recordsin a district are to be in ascending sequence according to departmentand employee number. Therefore, three fields (DSTRCT, DEPT, andEMPNUM) must be checked in each record. The matching field value M3is assigned to DSTRCT, the most important field; M2 is assigned to DEPT,the next most important field; and M1 is assigned to EMPNUM, the leastimportant field. Refer to the following example:

13–29

Using DISK Files

Example 13–16 Declaring matching record fields

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*IPAYROLL AA 01 80 CCI 1 3 DEPT M2I 6 7 DSTRCT M3I 14 152COMMI 25 27 EMPNUM M1I BB 02 80 CSI 1 3 DEPT M2I 8 9 DSTRCT M3I 13 172SALARYI 25 27 EMPNUM M1

First, the program determines the record type. Then, it looks at thematching 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 samelength.

The length of matching fields assigned to the same match code must bethe same length for each record type. Table 13–1 shows that this is truefor the previous example:

Table 13–1 Matching Field Lengths

RecordType

MatchingField

FieldLocation

FieldLength

first DSTRCTDEPTEMPNUM

6 to 71 to 325 to 27

2338 <— total

second DSTRCTDEPTEMPNUM

8 to 91 to 325 to 27

2338 <— 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 IndicatorsAlthough there may be different record types in a file, the fields for eachrecord type are often the same. Many fields have the same name, containthe same data, and are in the same character positions for all the recordtypes in a file. When only a few fields differ, more than one record typecan 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 6123456789012345678901234567890123456789012345678901234567890123456

*IPAYROLL AA 01 80 CCI 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 theInput specification identify the fields unique to a particular record type.Therefore, the COMM field in the following example is associated withrecord type 01 and the SALARY field is associated with record type 02.

The DSTRCT, DEPT, and EMPNUM matching fields are used in checkingthe sequence of the records in the PAYROLL file, and the matching-field values M1, M2, and M3 are described only once in columns 61 and62 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-relationindicators

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*IPAYROLL AA 01 80 CCI OR 02 80 CSI 1 3 DEPT M2I 8 9 DSTRCT M3I 25 27 EMPNUM M1I 14 152COMM 01I 13 172SALARY 02

If one of the matching fields is in a different record position for each recordtype, matching field entries must be assign, as shown in the followingexample:

Example 13–19 Matching record fields with field-record-relationindicators

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456

*IPAYROLL AA 01 80 CCI OR 02 80 CSI 1 3 EMPNUM M1I 20 21 DSTRCT M3I 6 72COMM 01I 10 12 DEPT M201I 5 7 DEPT M202I 10 142SALARY 02

For a 01 record type, matching field DEPT is in field location 10 - 12. Fora 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 FileThe processing of a primary file with one or more secondary files is calledmultifile processing. In multifile processing without matching fields, RPGfirst reads all the records from the primary file, then reads all the recordsfrom each secondary file in the same order in which they are specified inthe File Description specification. By using matching fields, the programcan select the records from the secondary file before selecting the recordsfrom the primary file, based on the value of their matching fields.

When using matching fields to process more than one file, the programselects records according to the contents of the matching fields, as follows:

• One record is read from every file and the matching fields arecompared. If the records are in ascending sequence, the recordwith the lowest matching field value is selected for processing. Ifthe records are in descending sequence, the record with the highestmatching field value is selected for processing.

• When a record is selected from a file that is then processed, the nextrecord from the file is read. The new record is then compared with theother records not selected in the previous cycle.

Records with and without matching fields can be combined in the samefile. Records without matching fields are processed before records withmatching fields. If two or more of the records being compared have nomatching fields, selection of those records is determined by the priority oftheir files, as follows:

• The records in primary files are processed before the records insecondary files.

• The records in secondary files are processed in order of appearance inthe File Description specifications.

Table 13–2 shows that the matching fields from a primary file arecompared with the matching fields from a secondary file to select recordsin ascending sequence. The letters represent the data in the matchingfields.

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 todo 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 FileRecord 1 (2) Record 1

A B

Compare (3)match fields. Process A

Cycle n

(1)

Record 2

(6) Record 2

C

D2

Compare (5)match fields. Process B

Cycle n + 1

(4)

Record 3D1

Compare (7)match fields. Process C

Cycle n + 2

(8)

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 4F

Compare (11)match fields. Process D2

Cycle n + 4

(12) Record 3X

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) islocated.

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 primaryfile are compared with the contents of the matching field (B) of thefirst 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 thesecondary 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 thesecondary 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.

9 The contents of the matching field (D2) of the second record in thesecondary 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

1 0 The fourth record of the primary file is read and the matching field (F)is located.

1 1 The contents of the matching field (D2) of the second record in thesecondary file are compared with the contents of the matching field (F)of the fourth record in the primary file. D2 is selected.

1 2 The third record of the secondary file is read and the matching field(X) is located.

1 3 The contents of the matching field (F) of the fourth record in theprimary file are compared with the contents of the matching field (X)of the third record in the secondary file. F is selected. Because theprimary file is now at its end, the remaining records in the secondaryfile (X and Z) are processed in order of appearance.

When the matching fields in a primary file match one or more of thematching fields in the secondary files, RPG sets the matching-record (MR)indicator on before detail-time calculations. The MR indicator can be usedto condition calculation and output operations for the record just selected.The indicator remains on for one complete program cycle. It is set off ifthe record selected for processing contains no matching fields. A recordselected using the FORCE operation code causes the MR indicator toremain off for one program cycle while the forced record is processed.

RPG processes matching records for two or more files in the followingways:

• When a record from the primary file matches a record from thesecondary file, the record from the primary file is processed beforethe record from the secondary file is processed. The record-identifyingindicator that identifies the record type just selected is on at the timethe record is processed.

• When records from ascending files do not match, the programprocesses the record with the lowest matching field content first.

• When records from descending files do not match, the programprocesses the record with the highest matching field content first.

• A record type that has no matching field specification is processedimmediately after the previous record is processed. In this case, theMR indicator is set off. If this record type is the first in the file, theprogram processes this record first, even when it is not in the primaryfile.

• The matching of records makes it possible to enter data from primaryrecords into their secondary records because the program processesthe record from the primary file before matching the record from thesecondary file. However, the transfer of data from the secondary recordto matching primary records can be done only when look-ahead fieldsare specified.

In the following example, matching fields are used to combine a primaryfile with two secondary files in ascending sequence. Record-identifyingindicators 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 6123456789012345678901234567890123456789012345678901234567890123456

H*FRECI99A IP AF 80 DISKFRECI99B IS F 80 DISKFRECI99C IS F 80 DISKFOUTPUT O F 80 DISK*IRECI99A 01 80 C1I 1 80 TEXTI 1 2 MATCH M1I 02 80 C2I 1 80 TEXT*IRECI99B 03 80 C3I 1 80 TEXTI 1 2 MATCH M1I 04 80 C4I 1 80 TEXT*IRECI99C 05 80 C5I 1 80 TEXTI 1 2 MATCH M1I 06 80 C6I 1 80 TEXT*OOUTPUT D N1PO 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 afterthe value represent values from the primary file. Field values with B afterthe value represent values from the first secondary file. Field values withC after the value represent values from the second secondary file.

Table 13–3 Matching Field Values

RecordNumber

PrimaryFile

First SecondaryFile

Second SecondaryFile

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

RecordNumber

PrimaryFile

First SecondaryFile

Second SecondaryFile

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–3and those indicators that must be set on for the operation to occur.

Table 13–4 Processing Records with Matching Fields

StepRecordType

Matching FieldValue 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 KeysThe following program accesses a single indexed file that contains threekeys. The program reads the file sequentially by key. It uses threedifferent file specifications to define the three key fields. Note that thethree file names use identical fields, and that each file name uses adifferent key to point to the same file. Also note the use of the same fieldsby a data structure.

Example 13–21 Multikey file access

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

H*FIDXI01 IP F 24 4AI 21 DISKFIDXJ01 IS F 24 3AI 1 DISK 01FIDXK01 IS F 24 2AI 11 DISK 02FIDX03A O F 24 DISK 01*IIDXI01 AA 01I 1 3 PNI 4 10 PNAMEI 11 12 WHOUSEI 13 17 COLORI 18 200WEIGHTI 21 240QTY*IIDXJ01 BBI 1 3 PNI 4 10 PNAMEI 11 12 WHOUSEI 13 17 COLORI 18 200WEIGHTI 21 240QTY*IIDXK01 CCI 1 24 FIELDS*IFIELDS DSI 1 3 PNI 4 10 PNAMEI 11 12 WHOUSEI 13 17 COLORI 18 200WEIGHTI 21 240QTY*OIDX03A D N1PO FIELDS 24

13.13 File BuffersThe RPG compiler creates one buffer for each file in a RPG program.However, there are some programs in which input and output buffers forthe same file should be distinct.

As an example, consider a program that is sequentially reading an indexedfile and occasionally executing the ADD operation code in the file usingEXCPT processing at total time. At the beginning of the logic cycle, arecord is selected for input. (For this example, use the FOO record.) Whena 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 newrecord being added to the file, for example the BAR record. Continuingwith the normal logic cycle, the program enters detail time and the recordselected for input has become the BAR record which was just writteninstead of the expected FOO record. The same buffer is used for bothinput and output. When the BAR record is written, the record buffer isoverwritten and its previous contents lost so that when it is time for fieldextraction to occur, the wrong record is found.

There are a number of workarounds that can be used. The ADD recordscould be written to a distinct output file and merged with the master filesoutside of the application. Or, total-time processing can be used to savethe record to be written and set an indicator on. Then, during detail-timeprocessing, use the indicator to trigger the EXCPT operation. Becausethe fields of the input record have been populated by this time, no conflictoccurs with a single record buffer.

The best alternative is to open two streams to the same file and have twoF specifications which essentially refer to the same file. Normal inputprocessing takes place using one stream and all ADD processing occurs onthe other stream. Because a record buffer is allocated for each file, twobuffers are created in this scheme, and no conflict occurs. Both files needto use the file sharing option (S in column 68 of the F specifications) inthis case.

Only one update is allowed for each logic cycle for update files other thandemand and chained files.

13–39

14 Using Printer Output Files

Printer files give the programmer a quick and easy way to createformatted reports. RPG provides the programmer with several featureswhich aid in report generation. Sections 14.2 and 14.3 describe thesefeatures and explain how to use them.

Note: RPG printer files contain all the print control characteristicsrequired to properly format a report. The default DCL PRINTcommand causes the insertion of a form-feed character when theform nears the end of a page. In some cases, this may cause blankpages to be inserted in the middle of a report. To suppress theinsertion of form-feed characters, use the /NOFEED qualifier onthe PRINT command when printing printer output files created byRPG programs, or set the bottom margin of the form type beingused 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 SpecificationTo define a printer file, the programmer must code a File Descriptionspecification and the associated Output specifications. Optionally, theprogrammer can code a Line Counter specification to override the defaultpage 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 recordsin the file are fixed length.

• Columns 20 - 23 can be blank or the block length to be used whenwriting records to the file. If entered, it must be a multiple of therecord length stated in columns 24 - 27. If blank, the block length isdefaulted to the record length.

• Columns 24 - 27 must contain the length of the records to be writtento 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 theprogrammer has coded a Line Counter specification for this printerfile.

• 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 SpecificationsIf the programmer wishes to change either the default page size (66) orthe overflow line (60), a Line Counter specification must be coded.

The following entries are required in the Line Counter specification. Forcomplete 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 mustmatch the name of the printer file coded in columns 7 - 14 of the FileDescription specification.

• Columns 15 - 17 must contain the number of lines per page. The pagesize 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 theoverflow line. The line number entered must be less than or equalto the number of lines per page entered in columns 15 - 17. If theline number entered is equal to the number of lines per page then anoverflow condition is not possible and overflow processing can neveroccur.

• Columns 23 - 24 must be OL to indicate that the entry in columns20 - 22 is the overflow line number.

14.1.3 Output SpecificationsOutput specifications are used to describe the records and fields in thePRINT or PRINTER output file and the conditions under which datais output. For complete information on using Output specifications, seeChapter 9, Output Specification (O).

14.1.3.1 File Identification EntriesThe 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, whichare used to link output lines together, allowing more than threeconditioning indicators to be used to condition an output record.

• Column 15 indicates at which point in the RPG cycle the record is tobe written. The values allowed are H(heading), D(detail), T(total), orE(exception).

14–2


• Column 16 indicates if the fetch overflow routine is to be used whenprocessing 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 therecord is printed. Spacing is defined as the number of lines the formis advanced in the printer. The values allowed are 0 - 9 or blank. If ablank is entered, the value is defaulted to 0.

• Column 18 indicates the number of lines to be spaced after therecord is printed. The values allowed are 0 - 9 or blank. If a blankis entered, the value is defaulted to 1. A value of 0 means the form isnot advanced, which allows overprinting.

• Columns 19 - 20 indicate the line number the printer should advanceto 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 isentered, no skipping takes place.

• Columns 21 - 22 indicate the line number the printer should advanceto 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 isentered, no skipping takes place.

Note: See Section 14.4 for more information on line spacing andskipping.

• Columns 23 - 31 can be used to specify indicators to condition theoutput of the record. Up to three indicators can be specified onan Output specification. Preceding an indicator with N causes thecondition to be valid only when the associated indicator is not on.Use columns 23 - 25 to describe the first indicator, columns 26 - 28 todescribe the second indicator, and columns 29 - 31 to describe the thirdindicator. Using the indicators in this way forms an AND relationship.Use AND or OR codes in columns 14 - 16 if it is necessary to conditionan output record definition with more than three indicators.

• Columns 32 - 37 can specify an exception name if exception timeoutput is required (E in column 15); otherwise, they must be blank.The EXCPT operation can specify the name in factor 2 of theCalculation specification. This name is called an EXCPT name.

• All other columns must be blank.

14.1.3.2 Field Description EntriesThe following describes the entries required to describe a field within aprinter file output record.

• Columns 23 - 31 can be used to specify indicators to condition theoutput of the field. Up to three indicators can be specified on anOutput specification. Preceding an indicator with N causes thecondition to be valid only when the associated indicator is not on.Use columns 23 - 25 to describe the first indicator, columns 26 - 28 todescribe the second indicator, and columns 29 - 31 to describe the thirdindicator. Using the indicators in this way forms an AND relationship.

14–3


• Columns 32 - 37 can specify a field, data structure, array name, anarray 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 entryis 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 afterthe output operation is complete. If the field should be reset, enter a Bin 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 orconstant in the output buffer. The end position entered cannot exceedthe record length of the printer file. If these columns are left blank,the RPG compiler will automatically calculate the field end position byadding the field length to the end position of the previous field.

• Columns 45 - 70 can be used to specify an output constant or editword. An edit word can be used to modify an edit code specified incolumn 38 or to define how data will be formatted when it is output.

• All other columns must be blank.

14.2 Using Special WordsRPG provides special words that enable the programmer to perform thefollowing 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 foreach 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 FieldsThe format in which a numeric field is printed is determined by the editcode and/or the edit word specified. For more information on the use ofedit codes and edit words, see Chapter 9, Output Specification (O).

14.4 Spacing and Skipping LinesThe programmer can format a report by specifying the number of linesto space or skip. Spacing is relative to the line currently being printed;therefore, use spacing between detail lines in a report. Skipping linesrepositions the printer to an absolute line number; therefore, specifyskipping to format a report. For example, if overflow has been detectedand the programmer wants to skip to the top of a new page and printheadings, specify skip to line number 2. The output heading line

14–4


associated with that Output specification will be printed on the secondline of each page.

To specify the number of lines to space, make the following entries in theOutput specification:

• Column 17 (space before)—specifies the number of lines to be spacedbefore printing a line.

• Column 18 (space after)—specifies the number of lines to be spacedafter printing a line.

To specify the number of lines to skip, make the following entries in theOutput specification:

• Columns 19 - 20 (skip before)—specifies the line number to skip tobefore printing a line.

• Columns 21 - 22 (skip after)—specifies the line number to skip to afterprinting a line.

If both spacing and skipping columns are made for the same line, RPGformats 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 andskip entries of the preceding line are used. If space and skip requirementsdiffer 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 onthe overflow indicator.

If a skip before entry is specified on the same line number that the printeris currently on, no skipping takes place.

If a skip before entry is specified to a line number less than the currentline number, the printer advances to that line number on the next page.

Note: If the line printer listing of a printer output file includes anunexpected blank page at the end of the file, use the DCLPRINT/NOFEED command to prevent the default OpenVMSprinter settings from overriding the forms control informationembedded in an RPG printer file. Another fix for this problem isto set the bottom margin of the form type being used to 0 with theDEFINE/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 TWICEFOR 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 6123456789012345678901234567890123456789012345678901234567890123456789

*OREPORT H 1PO 41 ’TOP"O H 320411 1PO 44 ’TEST LINE’O H 0 1PO 30 ’PRINT TWICE FOR BOLDING’O H 15 1PO 30 ’PRINT TWICE FOR BOLDING’O D 1 N1PO DESCR 18O STOCK# 26O ONHANDZ 31O PRICE K 39 ’$’

Sample output from Example 14–1 might look like the following:

1 2 3 4 5 61234567890123456789012345678901234567890123456789012345678901234567891 TOP234567 TEST LINE8910111213 PRINT TWICE FOR BOLDING141516 1 LB CARROTS VEG1MQ 47 $.7917 6 PACK SODA DRNK2A 40 $1.4818 1 LB BUTTER DAR0BT 38 $1.5919 STEAK MET0 22 $3.1520 HEAD LETTUCE VEG1WQ 63 $.35

14.5 Conditioning Output LinesAlthough any type of indicator can be used to condition output, the first-page (1P) and overflow indicators (OA - OG, OV) specifically conditionprinter output. Sections 14.5.1 and 14.5.2 describe how these indicatorscondition output.

14.5.1 Printing Lines Before Reading the First Record: First-Page IndicatorUse the indicator 1P to condition those heading lines which should beprinted before RPG processes the first record. The indicator 1P canbe 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 IndicatorOverflow occurs when the printer reaches the last line on a form on whichdata is to be printed. The overflow condition can be handled in one ofthree 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 theprinter file.

14.5.2.1 Automatic Handling of the Overflow ConditionIf the programmer does not specify an overflow indicator for the printerfile (columns 33 - 34 of the File Description specification are blank), andthe fetch overflow routine has not been specified (column 16 of the outputrecord specification is not an "F"), then RPG will automatically handle theoverflow condition. In this case, when the overflow condition is detected,RPG will advance the form to the top of the next page and continueprinting on the first line.

Unless the programmer has overridden the default form by specifyinga Line Counter specification for the printer file, line 60 is the defaultoverflow line.

14.5.2.2 Handling of the Overflow Condition Using Overflow IndicatorsOverflow indicators are used to specify which of the lines in the printerfile are to be printed when the overflow occurs. These indicators (OA - OG,OV) are used primarily to condition the printing of heading lines, but canalso be used to condition calculation operations and other types of outputlines. The programmer defines the overflow indicator to be used with theprinter file in columns 33 - 34 of the File Description specification. Onlyone overflow indicator is allowed per printer file and an overflow indicatorcannot be shared by printer files.

RPG sets on an overflow indicator the first time an overflow conditionoccurs for the current page. An overflow condition exists whenever one ofthe 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 theoverflow indicator on.

• Skipping past the overflow line to any line on the new page doesnot set the overflow indicator on unless the skip is specified past theoverflow line on the new page.

• A skip to a new page specified on a line not conditioned by an overflowindicator sets the overflow indicator off before the form advances to anew page.

• An overflow indicator can appear on either line of an AND or an ORrelationship. In an AND relationship, the overflow indicator mustappear on the main specification line for that line to be consideredan overflow line. In an OR relationship, the overflow indicator can bespecified on either the main specification line or the OR line. However,only one overflow indicator can be associated with one group of outputindicators.

• If an overflow indicator is used on an AND line, the line is not anoverflow line. In this case, the overflow indicator is treated like anyother output indicator.

• An overflow indicator cannot condition an exception line (E in column15 of the Output specification), but can condition fields within theexception record.

During a normal program cycle, RPG checks whether the overflowindicator 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 overflowindicator.

• 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 line12. When the overflow line is reached, the overflow indicator is set on,which conditions the heading line that prints the date, report title, andpage number at the top of each page.

14–8


Example 14–2 Sample Report Program using an Overflow Indicator

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

HFINPUT IP F 80 80 DISKFREPORT O F 132 132 OF LPRINTERL*LREPORT 15FL 12OLI*IINPUT NS 01I 1 5 ZIPI 10 150CEN30I 16 210CEN40I 22 270CEN50I 28 330CEN60I 34 390CEN70I 40 450CEN80I 46 47 STATEI 48 59 COUNTYI 63 74 TOWNO*OREPORT H 202 1PO OR OFO UDATE Y 12O 47 ’SOUTHERN NEW HAMPSHIRE’O 53 ’TOWNS’O PAGE 77O*O D 1 01O TOWN 13O COUNTY 26O STATE 30O CEN80 J 38O CEN70 J 46O CEN60 J 54O CEN50 J 62O CEN40 J 70O 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 712345678901234567890123456789012345678901234567890123456789012345678901234567

12/14/1991 SOUTHERN NEW HAMPSHIRE TOWNS 1

Hampstead Rockingham NH 3,785 2,401 1,261 823 823 775Kingston Rockingham NH 4,111 2,882 1,672 1,002 1,002 1,017Litchfield Hillsborough NH 4,150 1,420 721 341 341 286Newmarket Rockingham NH 4,290 3,361 3,153 2,640 2,640 2,511Atkinson Rockingham NH 4,397 2,291 1,017 434 434 407Rye Rockingham NH 4,508 4,083 3,244 1,246 1,246 1,081Hollis Hillsborough NH 4,679 2,616 1,720 996 996 879Peterborough Hillsborough NH 4,895 3,807 2,963 2,470 2,470 2,521Raymond 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,366Windham Rockingham NH 5,664 3,008 1,317 630 630 538Seabrook Rockingham NH 5,917 3,053 2,209 1,782 1,782 1,666Pelham Hillsborough NH 8,090 5,408 2,605 979 979 814Amherst Hillsborough NH 8,243 4,605 2,051 1,174 1,174 1,115Milford Hillsborough NH 8,685 6,622 4,863 3,927 3,927 4,068Bedford Hillsborough NH 9,481 5,859 3,636 1,561 1,561 1,326Hampton Rockingham NH 10,493 8,011 5,379 2,137 2,137 1,507Exeter 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,839Londonderry Rockingham NH 13,598 5,346 2,457 1,429 1,429 1,373Hudson Hillsborough NH 14,022 10,638 5,876 3,409 3,409 2,702Merrimack Hillsborough NH 15,406 8,595 2,989 1,253 1,253 1,084Derry Rockingham NH 18,875 11,712 6,987 5,400 5,400 5,131Salem Rockingham NH 24,124 20,142 9,210 3,267 3,267 2,751Portsmouth Rockingham NH 26,254 25,717 26,900 14,821 14,821 14,495Nashua Hillsborough NH 67,865 55,820 39,096 32,927 32,927 31,463Manchester Hillsborough NH 90,936 87,754 88,282 77,685 77,685 76,834

14.5.2.3 Handling the Overflow Condition Using Fetch OverflowBecause RPG only checks for the overflow condition after output of totalrecords, it is possible to print past the end of the form. This will occurwhen the total number of detail, total, and/or exception lines to be printedduring a program cycle exceeds the available space left on the form. Theprogrammer can prevent this from happening by using the fetch overflowroutine when outputting the lines that would cause the program to printpast the end of the form.

The fetch overflow routine allows the programmer to alter the overflowlogic 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 thefetch overflow indicator is on, then the program will execute the fetchoverflow routine. When executed, the fetch overflow routine performs thefollowing operations:

• All total lines conditioned by the overflow indicator are printed.

14–10


• Heading and detail lines conditioned by the overflow indicator areprinted. Note: the forms will only be advanced to a new page if aheading or detail line conditioned by the overflow indicator specifies askip to a line number which is less than the current print line.

• After printing the overflow lines, the line that specified the fetchoverflow is printed.

• RPG then prints any detail-time and total-time lines left for thatprogram cycle.

To request the fetch overflow routine, specify F (fetch overflow) in column16 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 thesame line with F (fetch overflow) in column 16.

• The fetch overflow routine will not automatically cause the form toadvance to the top of the next page. The form will only be advanced ifa heading or detail line conditioned by the overflow indicator specifiesa skip to a line number which is less than the current print line.

To decide when to fetch the overflow routine, study all possible overflowsituations and count lines, spaces, and skips to determine what happenswhen an overflow occurs.

14–11


In Example 14–4, all of the report detail is output at total time based onthe control break indicator L2. Since a large number of lines are outputat the same time, this could cause data to be printed past the end of theform. To prevent this from occurring, the fetch overflow routine is calledevery third or fourth line to check for the overflow condition.

Example 14–4 Sample Report Program using Fetch Overflow

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*HFINPUT IP AF 234R I DISKFADROUT IR AF 768 3 3IT EDISKFUNITPRODIC F 256 256R 3AI 1 DISKFPRINT O F 132 OF PRINTERE ADROUT INPUTE NUM 48 7 0E NM1 12 7 0E NM2 12 7 0E NM3 12 7 0E NM4 12 7 0E CST 48 9 2E CT1 12 9 2E CT2 12 9 2E CT3 12 9 2E CT4 12 9 2E YM 48 4 0E YM1 12 4 0E YM2 12 4 0E YM3 12 4 0E YM4 12 4 0E COST 4 8 2E USA 66 2E INS 10 6 0E MDL 10 3E*


14–12


Example 14–4 (Cont.) Sample Report Program using Fetch Overflow

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*IINPUT NS 01I 2 04 MFGDTEL2I 5 13 KEYI 26 32 WRNTY#I 35 400WWDATEI 194 1970YRMMI 227 232 WWTYPEI 14 25 WWUMDLI 14 16 MDL#I 186 193 WWCM#I 194 1990WWCMDTI 101 120 PART1I 101 102 FAIL2I 101 104 FAIL4I 101 101 FAIL1I 121 124 FAIL24I 227 232 WWFSEI 87 920FAILDTI 141 172 COSTI 173 1772HANDLGI 178 1852FRTI 1 10STSTI ABIUNITPRODCZI 4 90MFDATEI 4 50UNTYRI 6 7 UNTMOI 11 40 MDLI 41 100 AMTI 101 1060UNTPRDI 107 1120UNTINSI 121 1800INSI DSI 1 336 NUMI 1 84 NM1I 85 168 NM2I 169 252 NM3I 253 336 NM4I 337 3400YYMMI 337 3380YYI 339 3400MMI 341 3460DATEI 341 3420YRI 343 3440MOI*


14–13



1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*I DSI 1 432 CSTI 1 108 CT1I 109 216 CT2I 217 324 CT3I 325 432 CT4I DSI 1 192 YMI 1 48 YM1I 49 96 YM2I 97 144 YM3I 145 192 YM4I*I UDSI 1 3 FCDEI 4 6 TCDEI 7 9 LMDL#I***C*C N99 EXSR FSTPASC N99 SETON 99C L2 EXSR SETUPC EXSR FAILC N61 GOTO ENDC Z-ADDFAILDT DATEC Z-ADDMO MMC Z-ADDYR YYC Z-ADD1 C1C YYMM LOKUPYM,C1 50C 50 ADD 1 NUM,C1C 50 XFOOTCOST TMPCST 92C 50 ADD HANDLG TMPCSTC 50 ADD FRT TMPCSTC 50 ADD TMPCST CST,C1C END TAGC*CL2 60 ADD UNTINS TOTINS 60CL2N60 Z-ADD1 X1 20CL2N60 LMDL# LOKUPMDL,X1 50CL2N60 50 ADD INS,X1 TOTINSC**CL2 XFOOTNM1 TNUM1 70CL2 XFOOTNM2 TNUM2 70CL2 XFOOTNM3 TNUM3 70CL2 XFOOTNM4 TNUM4 70CL2 XFOOTCT1 TCST1 92CL2 XFOOTCT2 TCST2 92CL2 XFOOTCT3 TCST3 92CL2 XFOOTCT4 TCST4 92


14–14



1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*C*CSR SETUP BEGSRC MOVE ’-’ USAC MFGDTE CHAINUNITPROD 50C MOVELMFDATE YYMM 40C Z-ADDYYMM YMC Z-ADD0 C1 20C SETUP1 TAGC ADD 1 C1C C1 COMP 49 50C 50 GOTO SETUP9C Z-ADDYM,C1 YYMMC C1 SUB 1 C2 20C ADD C2 MMC SETUP2 TAGC MM SUB 12 TMP 20 50C 50 ADD 1 YYC 50 Z-ADDTMP MMC 50 GOTO SETUP2C Z-ADDYYMM YM,C1C GOTO SETUP1C SETUP9 ENDSRC*C FAIL BEGSRC SETOF 61C*C FAIL2 COMP ’A1’ 61C N61 FAIL2 COMP ’A2’ 61C N61 FAIL2 COMP ’A3’ 61C N61 FAIL2 COMP ’A4’ 61C N61 FAIL2 COMP ’A5’ 61C N61 FAIL2 COMP ’B1’ 61C N61 FAIL2 COMP ’B2’ 61C N61 FAIL2 COMP ’B3’ 61C N61 FAIL2 COMP ’B4’ 61C N61 FAIL2 COMP ’B5’ 61C N61 FAIL2 COMP ’C1’ 61C N61 FAIL2 COMP ’C2’ 61C N61 FAIL2 COMP ’C3’ 61C N61 FAIL2 COMP ’C4’ 61C N61 FAIL2 COMP ’C5’ 61C N61 FAIL1 COMP ’D’ 61C ENDSRC*C FSTPAS BEGSRC SETOF 60C MOVE LMDL# MODEL 3C LMDL# COMP ’ ’ 60C 60 MOVE ’ALL’ MODELC ENDSRC*


14–15



1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*OPRINT H 202 1PO OR OFO 24 ’48 MONTH DEFECT REPORT ’O 65 ’PAGE-’O PAGE Z 70O 86 ’AS-OF-’O UDATE Y 96O 132 ’SAMPLE’O TF 1 L2O 20 ’INSTALLED’O 30 ’MODEL#-’O MODEL 33O T 1 L2O 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 L2O MFGDTE 3O UNTYR ZB 6O 7 ’/’O UNTMO B 9O TOTINSZB 15O 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 L2O 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 L2O 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 6123456789012345678901234567890123456789012345678901234567890123456789

*O T 1 L2O 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 123O T 2 L2O 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 123O TF 1 L2O 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 L2O 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 L2O 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 L2O 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 L2O 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 6123456789012345678901234567890123456789012345678901234567890123456789

*O T 2 L2O 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 123O TF 1 L2O 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 L2O 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 L2O 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 L2O 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 L2O 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 123O T 2 L2O 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 6123456789012345678901234567890123456789012345678901234567890123456789

*O TF 1 L2O 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 L2O 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 L2O 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 L2O 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 L2O 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 123O T 2 L2O 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 123O TF 2 L2O USA 132

14–19

15 Using Tables and Arrays

RPG provides mechanisms for storing and retrieving associated and/orrelated data in a program. The two methods for storing associateddata are tables and arrays. The programmer can then use the LOKUPoperation code to quickly and efficiently locate data stored within the tableor array.

15.1 Using TablesIn RPG, a table is a collection of similar data items arranged in a specificorder. These data items are referred to as elements. Each entry in a tablemust have the same length and the same data type (either character ornumeric). If numeric, the entries must have the same number of decimalpositions. Tables are defined within a RPG program using Extensionspecifications. Each Extension specification can define a single table or itcan define two tables which contain associated data items, referred to asalternating table format.

When a table is defined using the alternating format, the rules for loadingthe 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 areread.

RPG supports two types of tables which are used to locate a specific dataitem quickly and easily.

• Single tables—consist of one group of similar entries. When searchinga single table, the result of the search is whether the item beingsearched 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 somehowrelated to the corresponding data element in the first table. Forexample the first table could be a list of labor codes used in processingwarranties for a product. The corresponding data in the second tablecould described the time allowed in hours for the repair operation.When looking up information in related tables, the first table issearched to see if the entry is present. If the entry is found, RPGretrieves the corresponding entries from both tables and makes themavailable as the current entries.

15–1

Using Tables and Arrays

Related tables can be defined by two separate Extension specificationsor they may be defined on a single Extension specification using thealternating table format. Related tables need not have the samenumber of entries unless they are described in alternating format inthe same Extension specification. However it is recommended thatrelated tables contain the same number of entries. If related tables donot contain the same number of entries, the search could find an entryin the first table and not find the corresponding entry in the secondtable. This can cause undesirable results to occur.

Types of tables are differentiated by whether they are loaded at compiletime or pre-execution time. Loading is the process by which the programassigns 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 TablesCompile-time tables are part of the source program. They are compiledwith the source program and become a permanent part of the objectprogram. 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 71234567890123456789012345678901234567890123456789012345678901234567890123

HFINPUT IPE F 50 DISKFREPORT O F 132 OF PRINTERE TABA 1 5 3IINPUT NS 01I 1 3 ITEMC ITEM LOKUPTABA 10OREPORT H 202 1PO OR OFO 24 ’Sample Table Program ’O 72 ’Page: ’O PAGE Z 77O*O D 01O 4 ’Item’O ITEM 8O 10 31 ’was found in the table’O N10 33 ’was not found in the tab’O N10 35 ’le’

** TABAAAABBBCCCDDDEEE

15–2


One advantage of compile-time tables is that they do not need to beloaded separately each time the program is run. However, if the needarises to change any of the entries in a compile-time table, the tablemust be revised and then the program recompiled. It is possible tomake temporary changes in the table during calculations. To make thesetemporary changes permanent, the table must be output. See Section 15.9for information about outputting tables.

15.2.1 Compile-Time Table DelimiterThe data for a compile-time table must follow the source program andany alternate sequence records. The first data record in the table must bepreceded by a delimiter record containing either double slashes ( // ) and ablank or double asterisks ( ** ) and a blank in character positions 1 - 3.

Table delimiters must be consistent within a program. The compilerwill interpret the first delimiter found as the default delimiter for theremainder of the program. I.E: if the first delimiter encountered is "** ",all remaining delimiters must also be "** ".

15.3 Pre-Execution-Time TablesPre-execution-time tables are not part of the object program. Each pre-execution-time table is loaded separately from an input data file. Anadvantage of pre-execution-time tables is that frequent changes can bemade to the table without recompiling the program.

Pre-execution-time tables are loaded before the first program cycle begins.

15.4 Creating Table Input RecordsTable input records contain the values for the entries in a table. Whencreating 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, asshown in Example 15–2.

• Entries cannot span record boundaries. Therefore, the length of anentry is limited to the device’s maximum record length. If a relatedtable is defined using the alternating format, corresponding entriescannot exceed the maximum record length.

• Each input record, except the last, must have the same number ofentries. The last record can be shorter to accommodate an unevennumber of entries.

15–3


Compile-Time Rules

• The first record must be preceded by a delimier record containingeither double slashes ( // ) and a blank or double asterisks ( ** ) and ablank in character positions 1 - 3. Because these strings are delimiters,records in a compile-time table cannot contain either of these threecharacters in positions 1 - 3.

Table delimiters must be consistent within a program. The compilerwill interpret the first delimiter found as the default delimiter for theremainder 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 71234567890123456789012345678901234567890123456789012345678901234567890123

E TABA 6 6 5...

** TABA637419231290343728441937510306\ /\ /\ /\ /\ /\ /1 2 3 4 5 6 <-- Element

The table in Example 15–2 consists of six entries in a record, and eachentry is five characters long.

When creating table input records for related pre-execution-time andcompile-time tables in alternating format, the entry for the first tablemust be followed immediately by the corresponding entry for the secondtable.

Example 15–3 defines the related tables TABA and TABB. The first recordcontains the first five entries for both TABA and TABB. The second recordcontains the last four entries for the tables. In this example, each entryin TABA is alphameric with a length of three. Each entry for TABB isnumeric with a length of three and zero decimals. Both tables have a totalof nine entries per table. Example 15–4 shows how the same tables, TABAand 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 71234567890123456789012345678901234567890123456789012345678901234567890123

E TABA 5 9 3 TABB 3 0...

**AAA000BBB111CCC222DDD333EEE444FFF555GGG666HHH777III888\ /\ /^ ^| || TABB element 6TABA element 6

15–5


Example 15–4 Related Tables - Single entry per record

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E TABA 1 9 3 TABB 3 0...

**AAA000BBB111CCC222DDD333EEE444FFF555GGG666HHH777III888

15.5 Defining TablesTo define a single table, the following entries must be made in theExtension specification:

• Columns 27 - 32 (table name) - specify the name of the table. Tablenames can be up to six characters long, but the first three charactersmust be TAB.

• Columns 33 - 35 (entries per record) - specify the number of entries ina record. Because tables can have one or more entries for each record,calculate the maximum number of entries in a record by dividing therecord length by the length of an entry.

• Columns 36 - 39 (number of entries per table) - specify the totalnumber 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 charactersin a pre-execution-time table. The maximum length of an alphamerictable element is 96 characters in a compile-time table. The maximumlength of a numeric table element is 15 digits.

• Column 43 (data format) - if the table contains numeric data, the dataformat must be specified. Use a ’P’ to specify packed-decimal format, a’B’ for binary format, or leave the entry blank for trailing numeric orzoned-decimal format. When specifying packed-decimal format, makesure the length of the entry represents the length of the numeric datain unpacked form. When specifying binary format, the length of theentry must indicate the number of bytes required to store the binaryfield. (Use 4 for two-byte binary numbers or 9 for four-byte binarynumbers.)

• Column 44 (decimal positions) - for numeric data, specify the numberof positions to the right of the decimal point. A 0 must be specified fornumeric data with no decimal positions.

15–6


• Column 45 (sequence) - specify ascending (A) or descending (D) toindicate that the entries in a table are in the specified sequence, orleave 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 FormatTwo tables can be defined either individually, or as a main table with analternate table defined in alternating format. To define an alternate table,make the following entries for the alternate table in the same Extensionspecification used to describe the main table:

• Columns 46 - 51 (table name) - specify the name of the alternatetable. Table names can be up to six characters long. The first threecharacters must be TAB.

• Columns 52 - 54 (length of entry) - specify the length of the entries inthe alternate table.

The maximum length of an alphameric table element is 256 charactersin a pre-execution-time table. The maximum length of an alphamerictable element is 96 characters in a compile-time table. The maximumlength 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-decimalformat, a ’B’ for binary format, or leave the entry blank for trailingnumeric or zoned-decimal format. When specifying packed-decimalformat, make sure the length of entry represents the length of thenumeric data in unpacked form. When specifying binary format, thelength of the entry must indicate the number of bytes required to storethe binary field. (Use 4 for two-byte binary numbers or 9 for four-bytebinary numbers.)


• Column 57 (sequence) - specify ascending (A) or descending (D) toindicate that the entries in a table are in the specified sequence, orleave this column blank to specify an unsequenced table.

The main table’s values for entries per table (columns 36 - 39), from filename (columns 11 - 18), and entries per record (columns 33 - 35) are alsoused for the alternate table.

15.5.2 Defining a Compile-Time TableWhen defining a compile-time table, make the entries described inSection 15.5 in an Extension specification. For compile-time tables, thereis 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 RPGprogram 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 trailingnumeric or zoned-decimal format. Therefore, leave column 43 (dataformat) blank. Leave column 55 (data format) blank if defining relatedtables in alternating format.

• The input records for compile-time tables must be in the same order inwhich the tables are defined in the Extension specifications.

• In compile-time tables the maximum length of an alphameric arrayelement is 96 characters. This is the maximum record size for an RPGsource program.

• If the compile-time table contains more entries than are defined forthe table in the Extension specification, a warning will be generatedstating that the table is full.

• If the compile-time table contains less entries than are defined forthe table in the Extension specification, a warning will be generatedstating that the table is short.

In the following example, the table name is TABLE1. There are 10 entriesin the table, with one entry in each record. The length of each entry isfive digits, with two decimal positions. The data type of the entry in eachrecord is trailing numeric, by default.

Example 15–5 Extension Specification to define a compile-time table

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E TABLE1 1 10 5 2...

// TABLE163741923129034372844193751030623847093745978012361

The following example defines two related tables, TAB1 and TAB2. Thereare four entries in each table, with two entries in each record. The lengthof 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 relatedtables

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E TAB1 2 4 5 0ATAB2 5 0A...

// TAB1 / TAB21111122222333334444455555666667777788888

15.5.3 Defining a Pre-execution-Time TableDefining a pre-execution-time table requires the same entries be made inthe 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 inputfile which contains the data for the table must be specified in columns11 - 18 (from file name). The table input file must be defined in a FileDescription specification with a T in column 16 (file designation) and an Ein column 39 (extension code). Example 15–7 defines a pre-execution-timetable, TABLEA, which contains 50 elements, each 5 characters in length.Each input record from the input table file INPDATA contains 10 tableelements.

Example 15–7 Definition of a Pre-execution-Time Table

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

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 thetable. If it does, a run-time error occurs.

• If more than one pre-execution-time table is to be loaded from tablefiles, each pre-execution-time table must be loaded from a differentfile. The exception is when two pre-execution-time tables are definedas alternating tables, both tables are loaded from the same table file.

15–9


15.6 Referencing Table EntriesWhen a table name is referenced in factor 1 or factor 2 of a Calculationspecification, the table name refers to the data retrieved by the lastsuccessful search. The exception to this rule is when a table is referencedas 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, theresult of the calculation on the next line replaces the current contents ofthe located entry in TAB1 because the table entry is used as the resultfield.

Example 15–8 Single table LOKUP

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E TAB1 1 5 5 0...

C FLD1 LOKUPTAB1 10C 10 TAB1 MULT 100 TAB1

15.7 Searching TablesThe operation code LOKUP is used to search for an element in a table.The search begins with the first entry and searches sequentially throughthe table looking for an entry which satisfies the search criteria. If anentry is found that satisfies the search criteria, a copy of the entry isplaced into a special work area for the table. After each successful search,this special work area is updated with the current table entry. When thetable name is specified in factor 1 with any operation code or in factor 2with any operation code expect for LOKUP, the table name is referencingthe entry stored in the special work area for that table.

To search a table for an entry, the following entries must be made in theCalculation specification:

• Columns 18 - 27 (factor 1) - specify a field or literal representing theentry to be located. Make sure the search argument has the samelength 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 besearched.

• Columns 54 - 59 (resulting indicator) - specify one or more indicatorsto indicate the type of search to be performed and to indicate whetherthe search has been successful. The indicator(s) can then be used tocondition subsequent calculations and output operations. All indicatorsspecified in columns 54 - 59 are set off before the search begins. Atleast one resulting indicator must be specified. If the search is notsuccessful, no indicators will be set on.

15–10


An indicator specified in columns 58 - 59 tells the LOKUP operationto search for an equal condition. The table is searched for an entrythat is equal to factor 1. When the first entry is found that meets thecondition, the search is terminated and the specified indicator is seton.

An indicator specified in columns 56 - 57 tells the LOKUP operationto search for a low condition. The table is searched for an entry thatis 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 isterminated and the specified indicator is set on.

An indicator specified in columns 54 - 55 tells the LOKUP operationto search for a high condition. The table is searched for an entry thatis closest to factor 1 in value but greater than the value of factor 1.When the first entry is found that meets the condition, the search isterminated and the specified indicator is set on.

If the table is to be searched using only the equal condition, thena sequenced table is not required. To save time in searching anunsequenced table, place the more frequently referenced entries at thebeginning of the table.

The conditions low and high can only be specified for a LOKUPoperation if the table to be searched is sequenced. If the table issequenced, the conditions low and equal or high and equal can becombined. When two conditions have been combined, the equalcondition takes precedence when searching the table. If both thelow and high conditions are coded, a compile time error will be flagged.

15.7.1 Searching One TableTo 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 thetype of search to be conducted using the resulting indicators. The tablein factor 2 will be searched for an element which satisfies the conditionsspecified. If the search is successful, the entry which satisfied the searchwill be placed into the special work area for that table and the appropriateresulting indicator will be turned on.

If a LOKUP operation against a table fails, the table reference fieldcontents in factor 2 do not change. When a program initializes, the firstentry 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 TablesTo 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, thename of the related table in the result field, and the type of search tobe conducted using the resulting indicators. The table in factor 2 will besearched for an element which satisfies the conditions specified. If thesearch 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 islocated in the table specified in the result field and placed into the specialwork area for that table.

If a LOKUP operation against a table fails, the table reference fieldcontents in factor 2 and the optional result table reference field contentsdo not change. When a program initializes, the first entry in a table isplaced 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 currententry. Then the corresponding entry in TAB2 is located, and it thenbecomes the current entry for TAB2.

Example 15–9 Related table LOKUP

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

C FLD1 LOKUPTAB1 TAB2 10

In Example 15–10, the program tries to match the search argument ITEMwith an entry in table TABA. If a matching entry is found, indicator 11 isset on. If no matching entry is found, the halt indicator H1 is set on andthe program terminates. In the compile-time table TABA, there are 10entries in a record and 50 entries in a table. Each entry is five characterslong.

Example 15–10 Program table LOKUP

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

HFINPUT IPE F 30 DISKFREPORT O F 40 DISKE TABA 10 50 5IINPUT NS 01I 1 5 ITEMI 6 102FLD1I 15 30 FLD2C ITEM LOKUPTABA 11C N11 SETON H1C 11 100 ADD FLD1 NEW 62 10OREPORT D 01 11O NEW B 20

//1000110002100031000410005100061000710008100091001020001200022000320004100052000620007200082000920010300013000230003300041000530006300073000830009300104000140002400034000410005400064000740008400094001050001500025000350004100055000650007500085000950010

In Example 15–11, the program searches the unsequenced table TABLE2for the value LENGTH. If the search is unsuccessful, processing forTABLE1 is bypassed. Otherwise, the program searches the sequencedtable TABLE1 to check for a value greater than or equal to COST. Ifthe search is successful, the subroutine PROCES is called to process theentry.

15–12


Example 15–11 LOKUP using a sequenced table

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

HFINFILE IP F 80 80 DISKFFILE1 IT F 80 80 EDISKFFILE2 IT F 80 80 EDISKE FILE1 TABLE1 1 6 3 2AE FILE2 TABLE2 1 6 3 0IINFILE NS 11I 1 32COSTI 4 60LENGTHI 7 100NUMBERC LENGTH LOKUPTABLE2 20C N20 GOTO NOPROCC COST LOKUPTABLE1 26 26C N26 EXSR PROCESC NOPROC TAG

.

.

.

15.8 Updating Tables

15.8.1 Temporarily Updating TablesIt is possible to change the contents of a table while the program isexecuting. The changes made will remain in effect for the duration of theprogram, but will be lost when the program finishes execution. The nexttime the program is executed, the table will contain the original data.To modify the contents of a table during execution, reference the table tobe modified as the result field in a calculation. When the statement isexecuted the table work area will be updated as well as the table elementwhich corresponds to the value in the work area.

In Example 15–12, the program searches for the entry 025 in the tableTABLE3. If the search is successful, the entry 025 in both TABLE3 andthe 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 71234567890123456789012345678901234567890123456789012345678901234567890123

H...

E TABLE3 1 6 3 0...

C 025 LOKUPTABLE3 20C 20 MOVE 250 TABLE3

.

.

.

15.8.2 Permanently Updating TablesTo permanently change the contents of an entry in, or add new entries to,a compile-time table, edit and recompile the program that contains thetable.

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. Aprogram can also be used to modify the current table file or to output acompletely new table file.

In Example 15–13, the program searches related tables specified using thealternating format. The first table, TABA, consists of a list of numbersof items in stock. The second table, TABB, consists of a list of unit pricescorresponding to the item numbers. The program will raise the unit priceof each item by 5% and output the updated table.

Example 15–13 Updating a pre-execution-time table

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

HFINFILE IP F 80 80 DISKFTABLE1 IT F 22 22 EDISKFTABLE2 O F 22 22 DISKE TABLE1 TABLE2 TABA 2 10 5 TABB 6 2IINFILE NS 01I 1 5 ITEMC ITEM LOKUPTABA TABB 11C N11 SETON H1C 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 Extensionspecification, the output file TABLE2 is automatically created. (Automaticcreation means that the output file does not require an Outputspecification.)

15–14


When the program executes, it reads the first record from the primaryinput file MASTER. If the search argument ITEM is matched, indicator11 is set on and the corresponding entry from TABB is made available forprocessing. If no match is found, the halt indicator H1 is set on and theprogram terminates without creating the output file TABLE2.

When the program ends, the updated tables TABA and TABB are writtento file TABLE2 with the same number of entries per record as the tableinput file TABLE1.

15.9 Outputting TablesWhen specifying the name of an output file in columns 19 - 26 (tofile name) of the Extension specification, the program creates the fileautomatically, as shown in Example 15–13.

When specifying a table as a field on an Output specification, only the lastentry found by the LOKUP operation can be output.

In Example 15–14, the table TABSH is read from the file TABFILE. Forthis example, the table is short; that is, not all 80 entries contain data.The LOKUP operation searches the table for the first entry containingzeros. 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 Outputspecification is the entry found by the last LOKUP operation. Whenthe last cycle occurs, the entire updated table will be written to the fileTABFILE2.

Example 15–14 Outputting a table

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

HFINFILE IP F 80 80 DISKFTABFILE IT F 80 80 EDISKFTABFILE2O F 80 80 DISKFOFILE O F 80 80 DISKE TABFILE TABFILE2TABSH 10 80 4 0IINFILE NS 01I 1 40ENTRYC 0000 LOKUPTABSH 11C 11 Z-ADDENTRY TABSH H1C 11 EXCPTOOFILE EO TABSH 10

15.10 Using ArraysIn RPG, an array, like a table, is a collection of similar data itemsarranged 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 samenumber of decimal positions. Arrays are defined within an RPG programusing Extension specifications. Each Extension specification can define

15–15


a single array or it can define two arrays which contain associated dataitems, referred to as alternating format.

When an array is defined using the alternating format, the rules forloading 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 areread.

Unlike tables, the programmer can reference individual array elements(entries) by specifying an array index, or process an entire array byspecifying the array name during calculation operations. An array shouldbe used instead of a table when an operation code is to affect all theelements in the array with a single reference, or to reference a specifiednumber of separate elements at the same time. For example, when it isnecessary to compute a 5% sales tax for each element in an array, a singlespecification can be used to perform the operation on every element in thearray.

Just like tables, RPG supports two types of arrays.

• Single arrays—consists of one group of similar entries. Whensearching a single array, the result of the search determines whetherthe 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 somehowrelated to the corresponding data elements in the first array. Forexample, the first array could be a list of valid part numbers. Thecorresponding data in the second array could be the list price for therelated part number.

Related arrays can be defined by two separate Extension specificationsor they may be defined on a single Extension specification using thealternating format. Related arrays need not have the same numberof entries unless they are described in alternating format in the sameExtension specification. However, it is recommended that relatedarrays contain the same number of entries.

Types of arrays are differentiated by whether they are loaded at compiletime, pre-execution-time, or execution (run) time. Loading is the processby which the program assigns the data supplied to the elements in anarray.

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 ArraysCompile-time arrays are part of the source program. They are compiledwith the source program and become a permanent part of the objectprogram. One advantage of compile-time arrays is that they do not needto be loaded separately each time the program is run. However, if theneed arises to change any of the entries in a compile-time array, thearray must be revised and the program recompiled. It is possible to maketemporary changes in the array during calculation operations. To makethese temporary changes permanent, the array must be output to a file.Then, using the output file as a reference, modify the RPG program andrecompile the program. See Section 15.20 for information about outputtingarrays.

15.11.1 Compile-Time Array DelimiterThe data for a compile-time array must follow the source program andany alternate sequence records. The first data record in the array must bepreceded by a delimiter record containing either double slashes ( // ) and ablank or double asterisks ( ** ) and a blank in character positions 1 - 3.

Array delimiters must be consistent within a program. The compilerwill interpret the first delimiter found as the default delimiter for theremainder of the program. I.E: if the first delimiter encountered is "// ", allremaining delimiters must also be "// ".

The following example shows a source program with the input data for twocompile-time arrays and their alternate compile-time arrays:

Example 15–15 Program using compile-time arrays

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

HFPROCD IP F 80 DISKFINLIST O F 132 OF PRINTERE AR1 1 5 5 0ALT1 20E AR2 4 4 5 0ALT2 4 2IPROCD NS 01I 1 50PRODNOI 6 80QUANC Z-ADD1 I 20C PRODNO LOKUPAR1,I 20C Z-ADD1 T 20C PRODNO LOKUPAR2,T 21C 21 QUAN MULT ALT2,T AMT 72OINLIST H 202 1PO OR OFO UDATE Y 18 ’ / / ’O 47 ’INVENTORY PARTS LIST’O PAGE 65O H 1 1PO OR OFO 32 ’PRODUCT PRODUCT’O 53 ’UNIT’O H 2 1PO 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 01O PRODNO 16 ’ 0’O 20 ALT1,I 39O 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 LRO 27 ’END OF PRICE LIST’

//17526BOLT18171SCREW19226NAIL25116NUT29258MAGNESIUM COVER//175260126181710059192260173292585843

15.12 Pre-execution-Time ArraysPre-execution-time arrays are not part of the object program; each array isloaded separately from an input data file. An advantage of pre-execution-time arrays is that frequent changes can be made to the array withoutrecompiling the program.

Pre-execution-time arrays are loaded before the first program cycle begins.

15.13 Execution-Time ArraysExecution-time arrays are created by using Input or Calculationspecifications. These arrays are loaded either from input data or asthe result of calculation operations after program execution begins.

15.14 Creating Array Input RecordsArray input records contain the values for the entries in the array. Whencreating array input records for compile-time and pre-execution-timearrays, observe the following rules.

Rules

• The first entry must begin in character position 1.

• All entries must be contiguous, with no space between entries, asshown in Example 15–16.

The array in Example 15–16 consists of five entries,. Each entry is 10characters long.

15–18


• Entries cannot span record boundaries. Therefore, the length of anentry is limited to the device’s maximum record length. If usingrelated arrays in alternating format, corresponding entries cannotexceed the maximum record length.

• Each array input record, except the last, must have the same numberof entries. This record can be shorter to accommodate an unevennumber of entries.

Example 15–16 Array Input Record

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E TABA 5 5 10...

** TABAaaaaaaaaaabbbbbbbbbbccccccccccddddddddddeeeeeeeeee\ /\ /\ /\ /\ /

1 2 3 4 5 <--- Elements

When creating compile-time array input records, observe the followingrules.

Compile-Time Rules

• The first record must be preceded by a record containing either doubleslashes ( // ) and a blank or double asterisks ( ** ) and a blank incharacter positions 1 - 3. Because these strings are delimiters, recordsin a compile-time array cannot contain either of these characters inpositions 1 - 3.

Table delimiters must be consistent within a program. The compilerwill interpret the first delimiter found as the default delimiter for theremainder 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 andcompile-time arrays in alternating format, the entry for the first arraymust be followed immediately by the corresponding entry for the secondarray.

Example 15–17 defines the related arrays ARY1 and ARY2. The firstrecord contains the first five entries for both ARY1 and ARY2. The secondrecord contains the last four entries for the arrays. In this example, eachentry in ARY1 is alphameric with a length of three. Each entry for ARY2is numeric with a length of three and zero decimals. Both arrays havea total of nine entries per array. Example 15–18 shows how the samearrays, ARY1 and ARY2, can be defined by specifying only one entry perrecord.

Example 15–17 Related arrays defined using multiple entries per record


15–19


Example 15–17 (Cont.) Related arrays defined using multiple entriesper record

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E ARY1 5 9 3 ARY2 3 0...

**AAA000BBB111CCC222DDD333EEE444FFF555GGG666HHH777III888\ /\ /^ ^| || ARY2 element 6ARY1 element 6

15–20


Example 15–18 Related arrays defined using a single entry per record

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E ARY1 1 9 3 ARY2 3 0...

**AAA000BBB111CCC222DDD333EEE444FFF555GGG666HHH777III888

15.15 Defining ArraysThe following entries are required in the Extension specification for allarrays.

• Columns 27 - 32 (array name) - specify the name of the array. Thearray name cannot begin with TAB.

• Columns 36 - 39 (number of entries per array) - specify the number ofentries 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 charactersin a pre-execution-time or execution-time array. The maximum lengthof an alphameric table element is 96 characters in a compile-timearray. The maximum length of a numeric array element is 15 digits.


• Column 45 (sequence) - specify ascending (A) or descending (D) toindicate that the entries in an array are in the specified sequence, orleave this column blank to specify an unsequenced array.

15.15.1 Defining Related Arrays in Alternating FormatWhen defining related arrays using alternating format, the followingentries must be made in the Extension specification in addition to theentries required for the primary array.

• Columns 46 - 51 (array name) - specify the name of the alternatearray. The array name cannot begin with TAB.

• Columns 52 - 54 (length of entry) - specify the length of the entries inthe alternate array.

15–21


The maximum length of an alphameric array element is 256 charactersin a pre-execution-time or execution-time array. The maximum lengthof an alphameric table element is 96 characters in a compile-timearray. The maximum length of a numeric array element is 15 digits.

• Column 55 (data format) - only specify the data format for alternatepre-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 ofthe numeric data in unpacked form. When specifying binary format,the length of the entry must indicate the number of bytes requiredto store the binary field. (Use 4 for two-byte binary numbers or 9 forfour-byte binary numbers.)


• Column 57 (sequence) - indicates that the order of the entries inan alternate array are in the specified sequence. Specify eitherascending (A), descending (D), or leave this column blank to specify anunsequenced array.

The entries made in the following columns for the main array also applyto 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 ArrayTo define a compile-time array, the following entries must be made in theExtension 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 ofentries in a record. Because arrays can have one or more entriesper record, calculate the maximum number of entries in a record bydividing the record length by the length of an entry. All records, exceptthe last, must contain the same number of entries; each entry must bethe same length.

When defining compile-time arrays, observe the following rules.

Rules

• If the compile-time array contains numeric data, it must be in trailingnumeric or zoned-decimal format. Therefore, leave column 43 (dataformat) blank. Leave column 55 (data format) blank if defining relatedarrays in alternating format.

• The input records for compile-time arrays must be in the same orderin which the arrays are defined in the Extension specifications.

15–22


• In compile-time arrays, the maximum length of an alphameric arrayelement is 96 characters. This is the maximum record size for an RPGsource program.

• If the compile-time array contains more entries than are defined forthe array in the Extension specification, a warning will be generatedstating that the array is full.

• If the compile-time array contains less entries than are defined forthe array in the Extension specification, a warning will be generatedstating that the array is short.

Example 15–19 describes the compile-time array A1. The array has eightentries with four entries in each record. Each entry is a character fieldthat is six bytes long. The array records are located at the end of theprogram.

Example 15–19 Compile-time array

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E A1 4 8 6...

**111111222222333333444444555555666666777777888888

15.15.3 Defining a Pre-execution-Time ArrayTo define a pre-execution-time array, the following entries must be madein the Extension specification in addition to the entries required for allarrays, (see Section 15.15 - Section 15.15.1):

• Columns 11 - 18 (from file name) - specify the name of the input filethat contains the data for the array. This input file is called an arrayinput file. It must be defined in a File Description specification byspecifying T in column 16 (file designation) and an E in column 39(extension code).

• Columns 33 - 35 (entries per record) - specify the number of entriesin a record. Arrays can have one or more entries for each record.Calculate the maximum number of entries in a record by dividing therecord length by the length of an entry. All records except the lastmust contain the same number of entries; each entry must be thesame length.

• Column 43 (data format) - if the array contains numeric data, the dataformat must be specified. Use a ’P’ to specify packed-decimal format, a’B’ for binary format, or leave the entry blank for trailing numeric orzoned-decimal format. When specifying packed-decimal format, makesure the length of entry represents the length of the numeric data inunpacked form. When specifying binary format, the length of the entrymust 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 thearray. 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 specifiedand the array contains fewer entries than are defined, the remainingentries are automatically filled using blanks for alphanumeric dataand zeros for numeric data.

15.15.4 Defining an Execution-Time ArrayAn execution-time array is defined using the entries described inSection 15.15 - Section 15.15.1. Execution-time arrays can be loadedby data read in from files (via the Input specifications) or by calculationsspecified in the Calculation specifications. Execution-time arrays are notsequenced checked. The SORTA operation code can be used to sort thearray into the order specified in column 45 of the Extension specification.If a sequence has not been specified, the sequence will default to ascendingorder.

If the array is to be loaded from a data file, it will be necessary to codeone or more Input specifications. How many Input specifications arerequired depends on whether the array data is stored in a single recordor in multiple records. If the array data is stored in a single record andoccupies consecutive bytes, then the array can be loaded using a singleInput specification. If the array data is stored in multiple records or isnot stored in consecutive bytes in a single record, then two or more Inputspecifications will be required. In this case, an Input specification will berequired to describe each individual array element.

To load an execution-time array from an input file, the following entriesmust be made for the array input file in the Input specifications:

• Column 43 (data format) - if the array contains numeric data, the dataformat must be specified. Use a ’P’ to specify packed-decimal format, a’B’ for binary format, or leave the entry blank for trailing numeric orzoned-decimal format. When specifying packed-decimal format, makesure the length of entry represents the length of the numeric data inunpacked form. When specifying binary format, the length of the entrymust 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 endingcharacter positions of the entire array, partial array, or array elementbeing loaded. If the data format is packed-decimal or binary, the fieldlocation must represent the actual size of the data element in bytes.

• Columns 53 - 58 (field name) - specify the name of the array (this mustbe the same name used on the Extension specification) or the nameof an individual array element (array name followed by a comma andindex).

15–24


Example 15–20 shows how to use the Input specification to load an entireexecution-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 singlefield in packed-decimal format. Note that the array is specified as packed-decimal in the Input specification but as trailing numeric in the Extensionspecification.

Example 15–20 Execution-time array load from data file

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

.

.

.E ARR 7 7 0IARRIN NS 03I P 1 28 ARR

.

.

.

Example 15–21 shows how to use the Input specifications to load an arraywith elements scattered throughout the record. Array ARR1 contains 4elements, each 5 bytes long, which are scattered among other fields in theinput record.

Example 15–21 Execution-time array load from data file

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

.

.

.E ARR1 4 5IARRFILE NS 03I 1 5 ARR1,1I 6 8 FLD1I 9 13 ARR1,2I 14 20 FLD2I 21 25 ARR1,3I 26 32 FLD3I 33 37 ARR1,4

.

.

.

15.16 Referencing ArraysWith tables, only the entry retrieved by the last LOKUP operation can bereferenced. With arrays, a reference can be made to either an entire arrayor an individual array element. One advantage of referencing an entirearray 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 commaand an index can be specified to reference an individual array element. Becareful when referencing an individual array element in a result field, thetotal length of the array name followed by a comma and an index must belimited to six characters.

15–25


An entire array can be referenced in factor 1, factor 2, or the result field inthe 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, RPGrepeats 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 ofthese operation codes. When using entire arrays (nonindexed) in anycalculations, 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 firstelement, then on the second element, and so on, until all the elementsin the array have been processed.

If the arrays do not have the same number of elements, RPG ends theoperation when the last element of the array with the fewest elementsis processed.

15–26


• When one factor is a field or constant and the other factor or resultfield is an entire array, RPG performs the operation once for everyelement 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 oneof the factors in a calculation, RPG alters the value of the element as aresult of the calculation. When this occurs, RPG uses the new value inall subsequent operations that reference that element. For example, twonumeric 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 resultis placed in ARR2, the elements of the resulting array are as shown inTable 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 characteror numeric field as factor 1, factor 2, or the result field. To specify anindividual array element, enter the array name, a comma, and theindex. 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 isdetermined by the value of the field FLD.

15–27


An array index, whether it is a literal or a field, must always be greaterthan or equal to 1 and less than or equal to the number of elements in thearray. If a field is used as an index and the current value of the field is outof 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 programcycle, use a constant number as the index. If, however, a different arrayelement must be referenced each time the calculation is executed, use afield name as the index.

In the following example, a company employs eight sales people whoseweekly sales amounts are recorded in an input file. Each record in the filecontains the weekly sales amounts; one new record is recorded in the fileeach week. At the end of the year, the company generates a report listingthe 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 71234567890123456789012345678901234567890123456789012345678901234567890123

HFINPUT1 IPE F 60 DISKFREPORT O F 60 DISKE WEEK 8 6 2E YEAR 8 8 2IINPUT1 NS 01I 1 48 WEEKC XFOOTWEEK TOTAL 82C ADD WEEK YEARCLR XFOOTYEAR GRAND 102OREPORT D 01O 20 ’WEEKLY TOTAL=’O TOTAL 35 ’$ , . ’O T LRO 20 ’YEARLY TOTAL=’O GRAND 35 ’$ , , . ’

Two execution-time arrays, WEEK and YEAR, are defined in the Extensionspecifications. The Input specifications instruct the program to load thearray 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 arrayas the input record is read. In this case, only one Input specification isnecessary to load the execution-time array WEEK.

The XFOOT operation calculates the sum of all the elements in the arrayWEEK and puts the sum in the result field TOTAL. The next calculationadds one array to the other. Adding arrays involves adding each elementof one array to the corresponding element of the other array. Resultingindicators cannot be specified to indicate the result of the operation.

These arrays have the same number of elements; therefore, any specifiedoperation is performed until all elements have been processed. In thecase of two arrays containing different numbers of elements, the specifiedoperation is performed only until the last element in the shorter array isprocessed.

15–28


15.17 Searching ArraysThe operation code LOKUP is used to search for an element in an array.The search begins with the first entry and searches sequentially throughthe array looking for an entry which satisfies the search criteria.

To search an array for an entry, the following entries must be made in theCalculation specification:

• Columns 18 - 27 (factor 1) - specify a field, literal, array element, ortable representing the element to be located. Make sure the searchargument has the same length and data format as the elements in thearray being searched.

• Columns 28 - 32 (operation code) - specify the LOKUP operation code.

• Columns 33 - 42 (factor 2) - specify the name of the array to besearched.

• Columns 54 - 59 (resulting indicator) - specify one or more indicatorsto indicate the type of search to be performed and to indicate whetherthe search has been successful. The indicator(s) can then be used tocondition subsequent calculations and output operations. All indicatorsspecified in columns 54 - 59 are set off before the search begins. Atleast one resulting indicator must be specified. If the search is notsuccessful, no indicators will be set on.

An indicator specified in columns 58 - 59 tells the LOKUP operationto search for an equal condition. The array is searched for an entrythat is equal to factor 1. The first entry found which meets the searchcondition terminates the search and sets on the specified indicator.

An indicator specified in columns 56 - 57 tells the LOKUP operationto search for a low condition. The array is searched for an entrythat 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 isterminated and the specified indicator is set on.

An indicator specified in columns 54 - 55 tells the LOKUP operationto search for a high condition. The array is searched for an entry thatis closest to factor 1 in value but greater than the value of factor 1.When the first entry is found that meets the condition, the search isterminated and the specified indicator is set on.

If the array is to be searched using only the equal condition, thena sequenced array is not required. To save time in searching anunsequenced array, place the more frequently referenced entries at thebeginning of the array.

The conditions low and high can only be specified for a LOKUPoperation if the array to be searched is sequenced. If the arrayis sequenced, the conditions low and equal or high and equal canbe combined. When two conditions have been combined, the equalcondition takes precedence when searching the array. If both the lowand high conditions are coded, a compile-time error will be flagged.

15–29


15.17.1 Searching An ArrayTo search an array, specify the data to be searched for in factor 1, LOKUPas the operation code, the array to be searched in factor 2, and the type ofsearch to be conducted using the resulting indicators. The array in factor2 will be searched for an element which satisfies the conditions specified.If the search is successful, the corresponding resulting indicator is set toindicate which condition was found.

In Example 15–23, the program tries to match the search argument QTYwith an entry in the array ARR. If a matching entry is found, indicator 11is set on. If the entry is not found, indicator 11 is set off.

Example 15–23 Array LOKUP

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

C QTY LOKUPARR 11

Unlike the search of a table, the program can control where the search ofan array is to begin. This is done by specifying in factor 2 of the LOKUPoperation the name of the array to be searched along with an index. Thevalue 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, OperationCodes, for a complete description of the LOKUP operation code.

In Example 15–24, the search begins with the seventh element of arrayARR:

Example 15–24 Array LOKUP with starting position

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

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 LOKUPoperation. If the search is successful, the index value of the array elementthat satisfied the condition is stored in the index field and a resultingindicator is set on. If the search is unsuccessful, the value 1 is placed inthe index field and a resulting indicator is set off. If the index field is notspecified, a successful LOKUP operation indicates the array contains thedata being searched for, but does not return the element’s index value.Remember to initialize the index field to the index value of the elementwhere 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 firstelement in ARY1.

15–30


• If the search argument SEARCH contains the value 50000, theLOKUP operation searches for an array element which has a valueless than 50000. If the search is successful, indicator 56 is set on.

• If the search is successful, the EXCPT operation will print the contentsof the array element (and its index) that satisfies the search condition.Next, 1 is added to the field containing the array index. While theindex field is less then 11, the search continues by setting indicator 54on; this causes the program to branch back to the label LOOP.

• If the search is unsuccessful, indicator 56 is set off. The program willfinish 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 71234567890123456789012345678901234567890123456789012345678901234567890123

HFINPUT1 IT F 50 EDISKFINPUT2 IPE F 10 DISKFOUTPUT O F 60 DISKE INPUT1 ARY1 10 10 5 0DIINPUT2 NS 01I 1 50SEARCHC Z-ADD1 I 20C LOOP TAGC SEARCH LOKUPARY1,I 56C 56 EXCPTC 56 ADD 1 IC 56 I COMP 11 54C 56 54 GOTO LOOPOOUTPUT E 56O 7 ’INDEX=’O I 9O 18 ’VALUE=’O ARY1,I 23

An example of the output file might appear as follows:

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123INDEX=05 VALUE=40000INDEX=06 VALUE=40000INDEX=07 VALUE=30000INDEX=08 VALUE=20000INDEX=09 VALUE=10000INDEX=10 VALUE=00000

15.18 Moving Array DataThe 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 anotherarray

15–31


If the array is not indexed, data movement starts with the first element ofan array or field. If the array is indexed, the move starts with the elementspecified by the index. Data movement stops when one of the followingconditions 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 MOVEAoperation code.

Example 15–26 shows a pre-execution-time array, ARR20, being loadedfrom the file ARRFILE. A copy of ARR20 is moved into the execution-timearray ARR15 using the MOVEA operation code.

Example 15–26 Program using MOVEA on an array

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

FARRFILE IT F 80 EDISKE ARRFILE ARR20 5 50 4E ARR15 50 4

.

.

.C MOVEAARR20 ARR15

15.19 Updating Arrays

15.19.1 Temporarily Updating ArraysTo make temporary changes in an array during program execution, specifythe array name in the result field. These temporary changes can be madepermanent by writing the array to an output file that can be used later asan input file.

15.19.2 Permanently Updating ArraysTo change the contents of an element in a compile-time array, or to addnew elements to a compile-time array, edit the source program containingthe array data and then recompile the program.

To change the contents of an element in a pre-execution-time array, or toadd new elements to a pre-execution-time array, edit the input file thatcontains the array.

Example 15–27 describes the array COSTL, which consists of six-digittrailing numeric data with two decimal places. This array is loaded fromthe file ARRAYIN. During program execution, changes can be made tothis array. At the completion of the program, the array will be writtento the output file ARRAYOUT. The format in which it is written is thesame 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 decimalpositions. The files ARRAYIN and ARRAYOUT must also be described inthe File Description specifications as an input table file (ARRAYIN) and anoutput table file (ARRAYOUT).

Example 15–27 Updating a pre-execution-time array

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

.

.

.FARRAYIN IT F 50 EDISKFARRAYOUTOT F 50 EDISKE ARRAYIN ARRAYOUTCOSTL 8 100 6 2

.

.

.

15.20 Outputting ArraysEither an entire array or individual array elements can be output.To output entire arrays, entries can either be made in an Extensionspecification or in an Output specification.

To write a compile-time or pre-execution-time array using an Extensionspecification, make the following entry:

• Columns 19 - 26 (to file name) - specify the name of a sequential outputfile. This file must have been previously defined in a File Descriptionspecification. The program automatically writes the compile-time orpre-execution-time array specified in the Extension specification to thisoutput file during last-record processing.

To write a compile-time, pre-execution-time, or execution-time array usingan Output specification, make the following entries:

• Columns 32 - 37 (field name) - specify the name of the array that is tobe written. The array is written every time the program processes arecord unless controlling indicators have been specified in columns 23 -31 of the Output specification.

• Columns 40 - 43 (end position) - specify the character position wherethe 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 Outputspecifications:

15–33


Example 15–28 Writing an execution-time array

1 2 3 4 5 6 71234567890123456789012345678901234567890123456789012345678901234567890123

E COSTLIST PRICE 5 10 5 2E DISCNT 10 5 2IFILEA NS 01I 1 22PERCNT

.

.

.C 01 PRICE MULT PERCNT DISCNT H

.

.

.OREPORT D 1 01O DISCNT 120 ’ $0. ’

To output an individual array element, specify the array and the index ofthe desired element (in the form ARR,n, where n is either a constant or afield 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 71234567890123456789012345678901234567890123456789012345678901234567890123

E COSTLIST PRICE 5 10 5 2E DSCT 10 5 2IFILEA NS 01I 1 22PERCNT

.

.

.C 01 PRICE MULT PERCNT DSCT H

.

.

.OREPORT D 1 01O 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 tosuppress leading zeros. Do not use edit codes or edit words to modifyarray data if it is going to be used as input data to subsequent programs.

When specifying an edit code with an entire array (nonindexed), RPGautomatically inserts two spaces between elements of the array in theoutput record.

15–34

16 Defining and Using Data Structures

A data structure is an area of storage subdivided into data fields calledsubfields. 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 orsubdivided 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 StatementData structure definitions appear in the Input specifications following allinput file record definitions. Data structure entries are the last elementsto appear in the Input specifications.

Data structure definitions have two parts: the data structure definitionand the subfield definitions. All subfields associated to an individual datastructure must immediately follow the data structure definition.

The format of the data structure statement is as follows:

Table 16–1 Data Structure Specification Layout

Column(s)AllowableEntries Explanation

7-12 Datastructurename

Optional. Identifies the data structure. The datastructure name, which is not required, can be a fielddefined in an Input specification or a Calculationspecification.

18 U Optional. Identifies this data structure as the localdata area.

19-20 DS Required. Specifies that this Input specification isdefining a data structure.

Note that a data structure name can only be six characters long. Datastructure names follow field name conventions. They can be 1 - 6characters long, must begin with an alpha character, and can be composedof any valid alphanumeric characters.

The data structure name can appear on only one data structurespecification. It cannot be the same name specified for a look-aheadfield.

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 structurename is the same as the input field name.

— The highest end position of a subfield within the data structure, if thedata structure name does not match an input field name.

The length computed by the highest end position of a subfield within adata structure must be less than or equal to the length specified in aninput field specification if the data structure name matches an input fieldname.

If the length of a data structure exceeds the length of the input field itis redefining, or disagrees with the length of a result field defined in aCalculation specification, the compiler will issue a diagnostic message.

If a data structure is named, it can be used as factor 1, factor 2, or theresult field of a Calculation specification or as an output field.

A data structure name cannot be used as a subfield name in another datastructure.

Data structures cannot be individual array elements, tables, or RPGreserved words.

16.2 Data Structure SubfieldsData structure subfields are specified in columns 44 - 58. They are definedin 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

Column(s)AllowableEntries Explanation

44-47 Start position Identifies the starting position of the subfield relativeto the beginning of the data structure.

48-51 End position Identifies the end position of the subfield relative tothe beginning of the data structure.

52 Decimalpositions

If 0 - 9 is entered in this column, it identifies the fieldas a numeric field. If the column is left blank, the fieldis considered alphameric.

53-58 Subfieldname

The name assigned to the subfield. The subfieldname can match an input field name or a field namedefined in the result field of a Calculation specification.The subfield name cannot appear in more than onedata structure and cannot match a data structurename.

The field location’s start and end positions are relative to the beginning ofthe data structure.

When coding a subfield definition in an Input specification, only columns44 - 58 are used.

16–2


The subfield name can be the same as a field defined on an Inputspecification or a Calculation specification. The subfield will act as aredefinition of these fields.

Subfields can be used as factor 1, factor 2, or the result field of aCalculation 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 datastructure.

If an array is specified as a subfield, the length specified must equal theamount 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 datastructure that is an entire array or an array with a variable index, thenthe entire array is used to determine whether overlap exists.

Any subfield previously defined in an Input specification must be the samelength as the input field.

Packed and binary field designations are not permitted when definingnumeric subfields. If a subfield redefines a packed or binary input field,its length must be defined as the unpacked length of the input field. Theinput field will be converted to trailing numeric format before it is placedin the subfield.

Data structure subfields cannot be individual array elements, tables, orRPG reserved words.

16.3 Using Data StructuresA data structure is considered to contain alphameric data and is initializedto blanks at program startup. It is the programmer’s responsibility toensure that numeric subfields contain numeric data before they are usedin a calculation or output operation.

A data structure can be from 1 - 9,999 characters long. The maximumlength of the local data area data structure is 512 characters.

The length of a data structure is determined by a matching input fielddefinition or by the highest subfield end position within the data structure.The data structure length is determined by whichever condition isencountered first. All subsequent definitions of the data structure lengthmust match the original definition or they will be considered invalid andthe compiler will issue error messages.

If an input or calculation field is defined in a data structure, the physicalstorage of the field’s contents will be within the data structure storagearea.

16–3


16.3.1 Breaking a Field Down Using SubfieldsA 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 aninput field into subfields.

Example 16–1 Input field redefined by subfields

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*ICUSTMSTRAA 01I 1 16 CUSTNOI 17 46 NAME

.

.

.ICUSTORDRBB 02I 1 16 CUSTNOI 17 25 PARTNO

.

.

.ICUSTNO DSI 01 02 STATEI 03 05 CITYI 06 100ZIPI 11 160ID

In this example, the field CUSTNO is used in both the CUSTMSTR andCUSTORDR files. It is redefined by a data structure and, within the datastructure, it is further broken down into the fields STATE, CITY, ZIP, andID. By using a data structure to redefine the CUSTNO field, only 16 bytesof storage are used to store the field and its subfields. Furthermore, thesubfields used to redefine the CUSTNO field need only be defined once inthe data structure, rather than repeated within each input record.

16–4


16.3.2 Using a Data Structure Storage Area In More Than One WayA data structure can be used to define a single area of storage for severalpurposes. The following example depicts the use of a data structure todefine three input records.

Example 16–2 Using a data structure to define multiple input records

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*IINVENTRYAA 01 01 CMI 1 50 ITMRECI BB 02 01 CII 1 26 QTYI CC 03 01 COI 1 34 ORDREC

.

.

.I DSI 01 50 ITMRECI 01 01 RECCODI 02 100PARTNOI 11 50 DESC*I 01 26 QTYI 01 01 RECCODI 02 100PARTNOI 11 160STOCKI 17 200LOWLIMI 21 26 LSTORD*I 01 34 ORDRECI 01 01 RECCODI 02 100PARTNOI 11 16 ORDDATI 17 220ORDQTYI 23 280AVEORDI 29 340BIGORD

In this example, a single data structure is used to define three inputrecords. By using a data structure in this fashion, it is possible to use only50 bytes of storage for all three record types. If each record were definedindividually, they would consume 110 bytes of storage.

16–5


16.3.3 Using a Data Structure to Reorganize Input FieldsA data structure can be used to reorganize input fields from an inputrecord. The following example depicts a data structure being used toreorganize fields from an input record.

Example 16–3 Input fields reorganized by a data structure

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*ICUSTORDRBB 02I 1 16 CUSTNOI 17 25 PARTNOI 26 310ORDDATI 32 370SHPDAT

.

.

.IORDKEY DSI 01 16 CUSTNOI 17 220ORDDAT

In this example, the data structure ORDKEY is constructed from the fieldsCUSTNO and ORDDAT. The fields CUSTNO and ORDDAT are obtainedfrom the CUSTORDR file and are reordered in the data structure to buildthe ORDKEY.

16.4 Local Data AreaThe local data area (LDA) is a 512-byte, single-record data file which isreferenced by the logical name RPGLDA. It is processed by RPG programsas a data structure. It can be used to pass information between programsand command procedures. The local data area is also discussed in theMigration RPG User’s Guide.

If specified, the local data area is automatically loaded when an RPGprogram is initialized and is written back out when the programterminates normally. To specify a local data area, a data structure musthave a U in column 18 on the Input specifications. A data structure nameis optional. Only one data structure in an RPG program may have a Uspecified in column 18.

Example 16–4 Local data area data structure

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*I UDSI 01 040RPTNOI 17 48 USERI 120 125 START

This example indicates how to code the local data area data structure.

16–6


16.4.1 Accessing The LDA Using SUBR21In addition to accessing the local data area via a data structure with a Uin column 18 of the data structure record, the MSI supplied subroutineSUBR21 can be used within an RPG program to read and write the localdata area. This subroutine is supplied to provide compatibility with IBMSystem/36 RPG II applications.

SUBR21 can be used to read data from the local data area or write data tothe local data area. To call SUBR21, the EXIT and RLABL operation codesmust be employed. SUBR21 requires that four parameters be passed usingthe RLABL operation. The following example indicates how a SUBR21 callmust be formatted.

Example 16–5 Accessing the LDA via SUBR21

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*C EXIT SUBR21C RLABL I_O 1C RLABL TERMID 2C RLABL RETCOD 1C RLABL LDA

SUBR21 requires that four parameters be passed using RLABL operationsin the order displayed in Example 16–5. The field names used inExample 16–5 are user defined and could be any valid RPG field name;they are not reserved words. The RLABL parameters provide the followinginformation:

• I_O - A one-character, alphameric field which must contain an I or anO. 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 theterminal id.

• RETDOC - A one-character, alphameric field which returns the statusof the SUBR21 operation. A return code of 0 indicates a successfuloperation. A return code of 1 or 2 indicates that the operation wasunsuccessful.

• LDA - A field or data structure which will receive information fromthe local data area or pass it to the local data area. If the amount ofinformation to be transferred exceeds 256 characters, this entry mustbe a data structure name.

16–7


16.5 Workstation Information Data Structure (INFDS)The information data structure (INFDS) is a special data structure whichcan be declared in a WORKSTN continuation line in the File Descriptionspecifications. The INFDS is used to pass information back to a programwhen an exception is processed. The INFDS is discussed in more detail inthe Migration RPG Screen Format Reference Manual.

Example 16–6 WORKSTN Information Data Structure

1 2 3 4 5 612345678901234567890123456789012345678901234567890123456789012345

*FTERMINALCD F 120 WORKSTNF KINFDS EXCPTN

.

.

.IEXCPTN DSI *STATUS STATUSI *OPCODE OPCODEI *RECORD RECORDI *SIZE SIZEI *MODE MODEI *INP INPI *OUT OUTI 23 26 RCODE

This example indicates how to code an INFDS data structure.

16–8

17 Specifying An Alternate Collating Sequence Or ATranslation File

Each character processed by a program has a hexadecimal value associatedto it. The hexadecimal values of the ASCII character set used by VAX andAlpha computers running the OpenVMS operating system are described inAppendix A, Character Sets. The order in which the characters appear inthe ASCII reference table, which runs from lowest hexadecimal to highesthexadecimal value, is called the collating sequence. When comparisonoperations are carried out in a program, the collating sequence is used todetermine which character is greater.

The normal ASCII collating sequence used by an RPG program can bechanged in one of three ways:

• By coding an E in column 26 of the Control specification, specifyingthat an EBCDIC collating sequence is to be used by the program forall comparison operations.

• By coding an S in column 26 of the Control specification, specifyingthat user-supplied collating values for one or more characters will beprovided 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 SequenceTo define a collating sequence that is different from the standard ASCIIor EBCDIC sequences, the hexadecimal value of each character whoseposition in the sequence is to be changed must be specified. This isaccomplished by coding an S in column 26 of the Control specification andcoding an alternate sequence table at the end of the program.

17.1.1 Coding an Alternate Sequence TableAn alternate sequence table is coded at the end of an RPG program.It must appear after the last RPG program specification and any filetranslation parameter entries, but before any compile-time table or arrayentries.

An alternate sequence table does not require an entry in the FileDescription or Extension specifications.

An S must be specified in column 26 of the Control specification or thealternate sequence table will not be recognized by the compiler.

An alternate sequence table is preceded by a specification containing twoasterisks and a blank in columns 1 - 3 (** ). The remaining columns inthis 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 alternatesequence table record:

Table 17–1 Alternate Sequence Table Record Layout

Column(s)AllowableValues Explanation

1-6 ALTSEQ Indicates that an alternate sequence record isbeing specified.

7-8 Blank

9-10 Hexadecimalvalue

Specifies the hexadecimal value of the ASCIIcharacter which is to be changed.


Specifies the new hexadecimal value of thecharacter specified in columns 9 - 10.

13-16,17-20,...,73-76

Hexadecimalvalues

Use these columns like columns 9 - 12 to defineadditional characters which are to be assigned newcollating values. The first two characters representthe ASCII hexadecimal value of the character thatis to be modified. The second two charactersrepresent the hexadecimal value to be assigned tothe character.

The first blank space in an ALTSEQ record terminates the ALTSEQentries for that record. The rest of the line can be used for comments.

If a large number of characters are to be redefined, additional ALTSEQrecords can be specified.

The last ALTSEQ record in an alternate sequence table must be followedby another record containing two asterisks and a blank (** ) in columns1 - 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 512345678901234567890123456789012345678901234567890123456789

H S...

O*** Alternate Sequence TableALTSEQ 2030 blank = 0ALTSEQ 4131 A = 1ALTSEQ 4232 B = 2ALTSEQ 4A33 J = 3ALTSEQ 4B34 K = 4** End of Alternate Sequence Table

In this example, an alternate sequence table has been specified to modifythe collating sequence of five characters. In the first ALTSEQ record, thehexadecimal value of 20 is being replaced by 30. This will equate a blankcharacter to the hexadecimal value for the character 0. Since the entry ofthe hexadecimal value 30 is followed by a blank, all subsequent entries onthe line are treated as comments.

In the second ALTSEQ record, the hexadecimal value of 41 is beingreplaced by the value 31. This will equate the ASCII character A to thehexadecimal value for the character 1. The third ALTSEQ record equatesthe hexadecimal value of character 2 (32) to the character B (42). Thefourth ALTSEQ record equates the hexadecimal value of character 3 (33)to the character J (4A). The fifth ALTSEQ record equates the hexadecimalvalue of character 4 (34) to the character K (4B).

The following section of sample code defines the same alternate sequencetable as the previous example. The only difference is that all of thesequence modifications have been placed in one ALTSEQ record.

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

H S...

O*** Alternate Sequence TableALTSEQ 2030413142324A334B34** End of Alternate Sequence Table

17–3


17.2 Specifying File Translation ParametersFile translation parameters are used to translate characters in a recordwhen they are input or output by a program. Translation parametersare commonly used to encrypt and decrypt data. An F must be codedin column 43 of the Control specification to indicate that file translationparameters are to be used.

File translation parameters can be specified for individual files within aprogram, or one set of translation parameters can be specified for all filesused 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 withtranslation parameters associated to it, the input record is translatedbefore it is made available to the program. When a record is output to afile with translation parameters associated to it, the record is translatedbefore it is written out.

17.2.1 Coding File Translation ParametersFile translation parameters are coded at the end of an RPG program.They must appear after the last RPG program specification and before thealternate sequence table and any compile-time table or array entries.

File translation parameter entries do not require an entry in the FileDescription or Extension specifications.

An F must be specified in column 43 of the Control specification or the filetranslation parameters will not be recognized by the compiler.

File translation parameters are coded in a manner similar to that used tocode an alternate sequence table.

File translation parameters are preceded by a specification containing twoasterisks and a blank in columns 1 - 3 (** ). The remaining columns inthis specification can be used for comments.

The following table describes the entries used to construct a file translationparameter record:

17–4


Table 17–2 File Translation Parameter Record Layout

Column(s)AllowableValues Explanation

1-6 *FILES Indicates that the translation parameter is to applyto 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. Thisentry must match an entry in columns 7 - 14 of aFile Description specification for an input, update,output, or combined file.


Specifies the hexadecimal value of a characterwhich is to be translated on input and translatedback on output.


Specifies the hexadecimal value to which thecharacter specified in columns 9 - 10 is translated.Also indicates a character which will be translatedback to the value specified in columns 9 - 10 if therecord is output.

13-16,17-20,...,73-76

Hexadecimalvalues

Use these columns like columns 9 - 12 todefine additional characters which are to betranslated. The first two characters representthe hexadecimal value of the input character thatis to be translated. The second two charactersrepresent the hexadecimal value to which thecharacter is to be translated for internal use by theprogram. This value will be translated back to theoriginal value if the record is output.

The first blank space in a file translation record terminates the translationparameter entries for that record. The rest of the line can be used forcomments.

If a large number of characters are to be translated, additional translationparameter records can be specified.

The last file translation parameter record must be followed by anotherrecord containing two asterisks and a blank (** ) in columns 1 - 3.

17–5


Example 17–2 File Translation Parameter Records

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

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 totranslate four characters. In the first translation record, the hexadecimalvalue of 2A is being replaced by 41, translating the asterisk character (*)to the character A. Since the entry of the hexadecimal value 41 is followedby a blank, all subsequent entries on the line are treated as comments.

In the second translation record, the hexadecimal value of 2B is beingreplaced by the value 42. This will replace the plus character (+) with thecharacter B. The third translation record replaces the hexadecimal valueof 2C (,) with the value 43 (C). The fourth translation record replaces thehexadecimal value of 2D (-) with the value 44 (D).

If a record is output, the characters described in columns 11 - 12 in thetranslation records would be translated back to the values specified incolumns 9 - 10.

The following section of sample code defines the same file translationparameter records as the previous example. In this example, thetranslation parameters are associated to a single file and have all beenplaced in one file translation parameter record.

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

H SFHOPSCTH IPE F 80 DISK

.

.

.O*

** File Translation Parameter RecordsHOPSCTH 2A412B422C432D44** End of File Translation Parameter Records

17–6

18 Using a SPECIAL Device File

18.1 OverviewThis chapter describes how Migration RPG provides support for SPECIALdevice files. SPECIAL device file support will allow the programmer toaccess files, devices, and services which are not directly supported by RPGor the OpenVMS Record Management Services (RMS). SPECIAL devicefiles coded in an RPG program can be treated like normal file definitionswith Input and Output specifications. However, the programmer isresponsible for providing an external subroutine which serves as theI/O interface for SPECIAL device files. The external subroutine usedby the SPECIAL device file is declared in the SPECIAL device Filespecification. These subroutines, which can be written in any nativeOpenVMS programming language, are responsible for transferring databack and forth between the RPG program and the special device. RPGprovides support for up to 99 SPECIAL device files in a single program.

Migration RPG provides support for reading input from SYS$COMMANDand writing output to SYS$OUTPUT via the supplied subroutine SUBR01.

18.2 File Description SpecificationsFor each SPECIAL device file, the programmer must code a FileDescription specification. The File Description specification for use withSPECIAL 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 nameor SUBR01

See Chapter 4, File Description Specification (F), for more detailedinformation concerning coding a File Description specification.

18.2.1 File Description Continuation SpecificationsIf desired, the programmer can code one continuation specificationwhich declares an associated array name. This array can be usedas a programmer-defined memory area for communication betweenthe RPG program and the SPECIAL device file subroutine. The Filecontinuation specification for use with SPECIAL device files is describedin 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 anExtension specification

See Chapter 4, File Description Specification (F), for more detailedinformation concerning coding a File Description specification.

18–2


18.3 Programming Considerations

18.3.1 Programming Features SupportedThe 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 LogicDuring the RPG program cycle, when a read or write operation to theSPECIAL device file is requested, a call to the subroutine named in theSPECIAL device File specification will be generated. The call will be inthe form of the Macro-32 instruction CALLS and will pass 1 parameter tothe SPECIAL device file subroutine. This parameter will be the addressof the File Control Data Structure described in Table 18–3. The operationcode is set to the proper value based on the current I/O operation beforecontrol 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 continuationline 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 ArrayControl 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 ControlData 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 SubroutineWhen coding the SPECIAL device file subroutine, keep the followingpoints in mind:

• It is the responsibility of the SPECIAL device file subroutine to createan access path to the special device the first time a call is made to theroutine.

• When the RPG program terminates execution, a call will be made tothe SPECIAL device file subroutine with the Close (C) operation code.It will be the responsibility of the SPECIAL device file subroutine toterminate the access path to the special device and return control tothe RPG program.

• After the subroutine has completed processing, it must place acompletion status in register R0 before returning control to the RPGprogram. Table 18–5 lists the condition codes which RPG programexpects 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, ifspecified.

1 Normal completion.

3 End of File - EOF indicator in column 58-59 of a READ operation is seton, if specified.

• If the file type is Input, then only the Get (G) operation code isgenerated by the RPG compiler for the SPECIAL device file subroutine.

• If the file type is Output, then only the Put (P) operation code isgenerated by the RPG compiler for the SPECIAL device file subroutine.

• If the file type is Update, then the operation codes in Table 18–6are generated by the RPG compiler for the SPECIAL device filesubroutine.

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–7are generated by the RPG compiler for the SPECIAL device filesubroutine.

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 aCombined file, the I/O buffer is blanked beforethe output data is mapped into the buffer.

18.4 Sample ProgramIn Example 18–1, the Migration RPG program SPCDEV uses 5 SPECIALdevice files. The purpose of this program is to demonstrate 5 differentaccess 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 eachfile along with information on the status of program indicators (seeExample 18–7). The 5 subroutines which support the SPECIAL devicefiles are written in VAX C.

Example 18–1 Sample Migration RPG Program using SPECIAL DeviceFiles

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*HFSBR100 UP F 45 45 SPECIAL TESTSBR100F KARR1FNORMAL IS F 50 50 DISKFSBR200 IS F 45 45 SPECIAL TESTSBR200FSBR300 CD F 50 50 SPECIAL TESTSBR300FSBR400 UD F 55 55 SPECIAL TESTSBR400F KARR2FSBR500 O F 60 60 SPECIAL TESTSBR500FREPORT O F 132 132 OF PRINTERE*E* Array used with SPECIAL device file SBR100E*E ARR1 2 5 0E*E* Array used with SPECIAL device file SBR400E*E ARR2 1 5 3E*E* Array contains the data supplied to SPECIAL device file SBR500E*E D500 1 3 60ISBR100 NS 01I 1 45 DATA1INORMAL NS 02I 1 50 DATA2ISBR200 NS 03I 1 45 DATA3ISBR300 NS 04I 1 50 DATA4ISBR400 NS 05I 1 55 DATA5C*C* Process the data from SPECIAL device file SBR100C*C 01 ADD 1 ARR1,1C 01 ADD 2 ARR1,2C 01 EXCPTOUT100C*C* Process the data from file NORMALC*C 02 EXCPTOUTNMLC*C* Process the data from SPECIAL device file SBR200C*C 03 EXCPTOUT200C*C* After all primary and secondary files have been processed,C* process the demand files and output only files.C*CLR EXSR SUB300CLR EXSR SUB400CLR EXSR SUB500


18–6


Example 18–1 (Cont.) Sample Migration RPG Program using SPECIALDevice Files

C*C* Subroutine to read data from SPECIAL device file SBR300,C* output the data read to the report and then write theC* output data to the SPECIAL device file.C*CSR SUB300 BEGSRCSR LOP300 TAGCSR ADD 1 X 50CSR SETOF 049091CSR READ SBR300 9190CSR EXCPTINP300CSR EXCPTOUT300CSRN90 GOTO LOP300CSR ENDSRC*C* Subroutine to read data from SPECIAL device file SBR400,C* and then update the SPECIAL device file.C*CSR SUB400 BEGSRCSR LOP400 TAGCSR SETOF 059091CSR READ SBR400 9190CSR EXCPTOUT400CSRN90 GOTO LOP400CSR ENDSRC*C* Subroutine to output data to the SPECIAL device file SBR500C*CSR SUB500 BEGSRCSR Z-ADD1 I 10CSR LOP500 TAGCSR EXCPTOUT500CSR ADD 1 ICSR I COMP 3 9090CSR 90 GOTO LOP500CSR ENDSRO*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 OUT100O 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 blankedO* before the output data is mapped into the buffer.O*OSBR300 E OUT300O 24 ’COMBINED, REST S/B BLANK’O X 30O*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 OUT400O 55 ’OVERLAY LAST 24 CHARS **’O*O* Output data to the SPECIAL device file SBR500 from the array D500.O*OSBR500 E OUT500O D500,I 60O*O* Create a report to display the results.


18–7



O*OREPORT H 202 1PO OR OFO 24 ’Test of SPECIAL device s’O 48 ’upport Program: SPCD’O 72 ’EV Page: ’O PAGE Z 77O*O* Display the results of the update with some debugging information.O*O EF OUT100O DATA1 45O 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 OUTNMLO DATA2 50O 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 OUT200O DATA3 45O 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 INP300O DATA4 50O*O* Display the results of the write with some debugging information.O*O EF OUT300O 24 ’COMBINED, REST S/B BLANK’O X 30O 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



O EF OUT400O DATA5 55O 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 OUT500O D500,I 60

** ARR2AAABBBCCCDDDEEE** D500This is the 1st output data record for SPECIAL device SBR500This is the 2nd output data record for SPECIAL device SBR500This is the 3rd output data record for SPECIAL device SBR500

18–9


In subroutine TESTSBR100 (Example 18–2), 3 data records are returnedas input to the RPG program. On the 4th read request, an End-of-Filestatus is returned to the RPG program. When an update request isreceived, the data from the program buffer is written to SYS$OUTPUTand 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){


}if ( cnt == 3 ){


}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


In subroutine TESTSBR200 (Example 18–3), 3 data records are returnedas input to the RPG program. On the 4th read request, an End-of-Filestatus is returned to the RPG program.







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 ){


}if ( cnt == 2){


}if ( cnt == 3 ){



}

return 2; /* Else Return error */}

18–13


In subroutine TESTSBR300 (Example 18–4), 3 data records are returnedas input to the RPG program. On the 4th read request, an Error status isreturned to the RPG program. When a write request is received, the datafrom the program buffer is written to SYS$OUTPUT.







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 ){


}if ( cnt == 2){


}if ( cnt == 3 ){


}return 2; /* Error */

}

/* Is this a call for output data, op-code of P */

if ( File_DS->op_code == ’P’ ){

memcpy( outbuf, File_DS->buffer, 50 );outbuf[51] = 0;printf( "Buffer Data SBR300: %s\n", outbuf );return 1;

}


}

18–15


In subroutine TESTSBR400 (Example 18–5), 3 data records are returnedas input to the RPG program. On the 4th read request, an End-of-Filestatus is returned to the RPG program. When an update request isreceived, the data from the program buffer is written to SYS$OUTPUTand the contents of the associated array are written to SYS$OUTPUT.







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 ){


}if ( cnt == 2){


}if ( cnt == 3 ){



}

/* Is this a call for update data, op-code of U */

if ( File_DS->op_code == ’U’ ){

memcpy( outbuf, File_DS->buffer, 55 );outbuf[56] = 0;printf( "Buffer Data SBR400: %s\n", outbuf );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 isreceived, the data from the program buffer is written to SYS$OUTPUT.








{char outbuf[61];



return 1;}

/* Is this a call for update data, op-code of P */

if ( File_DS->op_code == ’P’ ){

memcpy( outbuf, File_DS->buffer, 60 );outbuf[61] = 0;printf( "Buffer Data SBR500: %s\n", outbuf );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 SBR10001 ONOVERLAY FIRST 24 CHARS *ord. 222222222 SBR100 SBR10001 ONOVERLAY FIRST 24 CHARS *ord. 333333333 SBR100 SBR10001 ONThis is the 1st data record from NORMAL dat file NORMAL

02 ONThis is the 2nd data record from NORMAL dat file NORMAL

02 ONThis is the 3rd data record from NORMAL dat file NORMAL

02 ONThis is the 1st data record. 111111111 SBR200 SBR200

03 ONThis is the 2nd data record. 222222222 SBR200 SBR200

03 ONThis is the 3rd data record. 333333333 SBR200 SBR200

03 ONThis is the 1st data record. 111111111 SBR300 AAAACOMBINED, REST S/B BLANK 00001 SBR300

04 ONThis is the 2nd data record. 222222222 SBR300 BBBBCOMBINED, REST S/B BLANK 00002 SBR300

04 ONThis is the 3rd data record. 333333333 SBR300 CCCCCOMBINED, REST S/B BLANK 00003 SBR300

04 ONThis is the 3rd data record. 333333333 SBR300 CCCCCOMBINED, REST S/B BLANK 00004 SBR300

90 ON 91 ONSBR400 This is the 1st data recOVERLAY LAST 24 CHARS ** SBR400

05 ONSBR400 This is the 2nd data recOVERLAY LAST 24 CHARS ** SBR400

05 ONSBR400 This is the 3rd data recOVERLAY LAST 24 CHARS ** SBR400

05 ONSBR400 This is the 3rd data recOVERLAY LAST 24 CHARS ** SBR400

90 ONThis is the 1st output data record for SPECIAL device SBR500This is the 2nd output data record for SPECIAL device SBR500This is the 3rd output data record for SPECIAL device SBR500

18–19

19 Coding Subprograms

Migration RPG permits RPG programs to call subprograms using theCALL opcode. Subprograms can be written in Migration RPG or otherOpenVMS programming languages. This chapter describes the opcodesused to call subprograms and pass data between the calling program andthe subprogram. Examples of RPG, COBOL, and Macro-32 subprogramsare included in the chapter.

19–1

Coding Subprograms

19.1 CALL Operation


9−17 18−27 33−42 43−48 56−57 58−59

CALL Optional Opt Opt

7−8 28−32

Required

54−55

Opt BlankOpt Blank

The CALL operation transfers control to the program or external routinespecified in factor 2. This program is referred to as the subprogram.

The CALL operation transfers control from the calling program to asubprogram or external routine much as the BEGSR opcode transferscontrol to a subroutine. Factor 2 must contain a character literal or a fielddefined by the EXTRN opcode that names the subprogram. This must bea valid OpenVMS program name. Factor 2 cannot be an array elementor data field name. The program specified in factor 2 can be written inany OpenVMS programming language, including Migration RPG. Whenspecifying a program name which exceeds 8 characters, use the EXTRNopcode to define a field which represents the program name.

The result field can contain the name of the parameter list associated witha PLIST opcode. This enables the calling program to share parameterswith the subprogram. Individual parameters can also be specifiedimmediately following the CALL opcode using the PARM opcode. Boththe PLIST option and PARM statements can be used together with theCALL opcode. See Chapter 11, Operation Codes, for a complete descriptionof the PLIST and PARM opcodes.

Factor 1, half adjust, and the resulting indicator in columns 54 and 55must be blank. Any valid resulting indicator can be specified in columns56 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 beset on if the subprogram is a Migration RPG program and exits with theLR indicator set.

19–2

Coding Subprograms

Example 19–1 CALL and PARM Opcode Usage - Example 1

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

** 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’ 23C PARM FOXC PARM BATC PARM WEASELC PARM WOLF

19–3

Coding Subprograms

19.2 EXTRN Operation

Indicators Factor 1 Opcode Factor 2

9−17 18−27 33−637−8

Required

28−32

LiteralBlkBlk EXTRN

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 alink-time constant. It is used to assign a subprogram or external routinename exceeding eight (8) characters in length to a field name which can beused with the CALL opcode.

Factor 1 and factor 2 are required entries for this opcode. Conditioningindicator entries (columns 9 - 17) are not permitted.

Factor 1 is used to name the field Migration RPG initializes, using thevalue specified in factor 2. Factor 1 of the EXTRN operation is defined asan alphameric field. This field can only be used with the CALL and FREEopcodes and cannot be defined elsewhere in the program.

Factor 2 is used to name the external constant. A maximum of 31characters can be used to name the constant. The constant must beenclosed in apostrophes. The constant must conform to OpenVMS namingconventions.

When using the EXTRN opcode to define a subprogram used in a CALLstatement, preceed the subprogram name with an underscore. Theunderscore prefix is not needed if the subprogram name is provided tothe CALL statement as a literal in factor 2.

Example 19–2 EXTRN, Use of Underscore in Subprogram Name

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

** 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 PRGNMC CALL ’PROG1’

The underscore is used internally by Migration RPG to make the .ENTRYpoint name for the program unique. This prevents conflicts with fieldnames within the program.

19–4

Coding Subprograms

Example 19–3 EXTRN, CALL, and FREE Opcode Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

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


9−17 18−27 33−42 43−48 56−57 58−59

FREE Opt

7−8 28−32

Required

54−55


The FREE operation is used to remove an RPG subprogram from theactive 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 EXTRNopcode that names the RPG subprogram. Factor 2 cannot be an arrayelement or data field name. The subprogram specified in factor 2 must bea Migration RPG program. Submitting a non-Migration RPG subprogramto the FREE opcode will produce unpredictable results. When specifying asubprogram name which exceeds 8 characters, use the EXTRN opcode todefine a field which represents the subprogram name.

An error indicator can be specified in columns 56 and 57. The errorindicator will be turned on if the FREE operation is submitted to an RPGsubprogram which has never been CALL’ed or which was already FREE’din a previous operation.

When a Migration RPG subprogram is called for the first time, normalprogram initialization, such as file opens and field initialization, takesplace. After that, as long as the subprogram is not terminated normally(LR indicator on) or abnormally (Halt indicator on or error), each timethe subprogram is called, it resumes operations where it left off at theprevious exit, very much like an internal subroutine. Thus, programinitialization is skipped during each additional call after the first one aslong as the subprogram has not been ended and the FREE opcode hasnot been exercised against it. The FREE opcode provides the programmerwith another method to place a subprogram back into its initial startingstate. See Section 11.12.25, - FREE Operation, for more information onterminating subprograms and the use of the FREE opcode.

Example 19–4 FREE Opcode Use

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

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


9−17 18−27 33−42 43−48 56−57 58−59

PARM Required

7−8

Optional

28−32

Optional

54−55

Blk Blank BlankOpt Blank

The PARM operation is used to exchange parameters with a subprogram.

The PARM opcode is used to define parameters which will make up aparameter list to be passed to a subprogram. The PARM opcode can beused with the CALL and PLIST opcodes. PARM statements can appearanywhere in the Calculation Specifications as long as they immediatelyfollow a CALL or PLIST statement. Up to 99,999 PARM statements canfollow a CALL or PLIST statement.

Conditioning indicator entries (columns 9 - 17) and resulting indicatorentries (columns 54 - 59) are not permitted on PARM statements.

Factors 1 and 2 are optional in a PARM statement. If specified, they musthave the same data type, alpha or numeric, as the result field. A literalcannot be specified in factor 1.

The result field must contain a field, data structure, array, or arrayelement name. *ENTRY PLIST parameters cannot specify array elementsusing fields as subscripts. The result field cannot contain a literal or tablename. *IN, *INxx, and *IN,xx entries are legal PARM fields, but shouldbe specified with caution as their settings reflect indicator settings. Thelength and decimal position columns (49 - 52) can be used to define theresult field.

The fields specified in the result field of a PARM statement are passed bydescriptor to the subprogram. The fields can be manipulated and updatedby the subprogram. The subprogram then returns the updated valuesto the calling program. If a subprogram terminates with an error, anychanges made to the fields specified in the PARM statements are stillreturned to the calling program. To preserve a field from changes whenusing it as a parameter, specify the field name in factor 2 of the PARMstatement and declare a temporary field name in the result field. Thecontents of factor 2 will be copied to the result field when the subprogramis called and the contents of the field in factor 2 will remain unaffected.

When a Migration RPG subprogram is called by another Migration RPGprogram, the following steps occur:

1 In the calling program, the contents of factor 2, if specified, are copiedto 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 initializationprocessing has run, the contents of the result fields in the *ENTRYPLIST parameters are copied to factor 1, if factor 1 is specified.Numeric fields are moved using a Z-ADD operation. Alphameric fieldsare left-justified and blank-filled. Errors and warnings will be loggedif the parameter descriptors being passed to the subprogram do notmatch the field types and sizes specified in the *ENTRY PLIST.

3 When the subprogram returns control to the calling program, thecontents of factor 2 in each *ENTRY PLIST parameter, if specified,are copied to the result field. Numeric fields are moved using a Z-ADDoperation. Alphameric fields are left-justified and blank-filled. Theresult field descriptors are passed back to the calling program.

4 Upon return to the calling program, the contents of the result fieldsare copied to factor 1, if factor 1 was specified. Numeric fields aremoved using a Z-ADD operation. Alphameric fields are left-justifiedand blank-filled.

Parameter fields are passed as fixed-length descriptors. The structure ofthese 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-MigrationRPG subprograms, specify the actual packed or binary field length in theparameter descriptor. Do not specify the unpacked or expanded binaryfield length of the field. Migration RPG will only accept binary fields witha length of 2 or 4 bytes.

19–8

Coding Subprograms

Fields in a Migration RPG program default to the following descriptortypes when passed as parameters in a PARM statement.

Table 19–2 Default Descriptor Types

Element type Definition Description Type

Array AlphamericNumeric: Zoned-decimal, trailingnumeric, packed, binary



Array Element AlphamericNumeric: Zoned-decimal, trailingnumeric, packed, binary



Input Field Col 43: blank Col 52: blankCol 43: blank Col 52: 0 - 9Col 43: P Col 52: 0 - 9Col 43: B Col 52: 0 - 9Col 43: B Col 52: 0 - 9

AlphamericZoned-decimalTrailing numericPacked decimalBinary, 2 byteBinary, 4 byte

DSC$K_DTYPE_TDSC$K_DTYPE_NZDSC$K_DTYPE_NZDSC$K_DTYPE_PDSC$K_DTYPE_WDSC$K_DTYPE_L

Data Struct. AlphamericNumeric: Zoned-decimal, trailingnumeric, packed, binary



DS Subfield Col 43: blank Col 52: blankCol 43: blank Col 52: 0 - 9



Calc field Col 52: blankCol 52: 0 - 9



When passing parameters to a Migration RPG program from a programwritten in another language, fixed-length descriptors and one of the abovedescriptor types must be used. If the incoming parameter is not a fixed-length descriptor and does not use one of these descriptor types, theMigration RPG program will issue an error message and abort.

When passing parameters between Migration RPG programs, theparameter list passed by the calling program and the parameter listspecified in the subprogram’s *ENTRY PLIST must match data types andshould match sizes. Thus, if the first parameter passed to a program is a5-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 datatypes, sizes, and number of parameters in the calling program’s parameterlist. However, the following exceptions apply when passing parametersbetween Migration RPG programs:

• Parameters of the same data type, but different lengths, will generatea warning message, but will be accepted by the subprogram. Thewarning message can be suppressed by compiling the subprogramusing the /NOWARNING qualifier.

• A parameter defined as alphameric in one parameter list and numericin the other will be passed without error.

19–9

Coding Subprograms

• If the calling program passes more parameters than the subprogramis prepared to accept, a warning message will be issued and the extraparameters will be ignored. The warning message can be suppressedby compiling the subprogram using the /NOWARNING qualifier. If thecalling program passes too few parameters, the subprogram will log anerror message and return to the calling program with an error statusset.

When passing parameters between Migration RPG programs, descriptorcreation, transfer, and checking is handled automatically by the MigrationRPG runtime routines.

Example 19–5 CALL and PARM Opcode Usage - Example 2

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

** 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 TAPC PARM FOX TROT 10C STON PARM CHARLEC ROLL PARM ROCK AND 70

19–10

Coding Subprograms

19.5 PLIST Operation


9−17 18−27 33−42 43−48 56−57 58−597−8

Required

28−32 54−55

Blk Blank Blank Blank BlankOpt PLIST Blank

The PLIST operation defines a unique symbolic name for a list ofparameters that is used in a CALL operation. The parameter list isdefined using the PARM opcode.

A PLIST operation can be specified anywhere within the CalculationSpecifications, including total time calculations and between subroutines.It is customary to place PLIST groups at the beginning of the CalculationSpecifications as an aid to program readability.

A PLIST entry consists of a PLIST statement followed by one or morePARM statements. The PARM statements define a list of parameters thatare to be passed to a subprogram. The PLIST is ended when an operationother than a PARM is encountered.

Factor 1 must contain the name of the PLIST. A PLIST name can be oneto six characters in length and must be unique. If the parameter list beingdefined 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 theelements in a parameter list defined by a *ENTRY PLIST in a subprogramshould match in size and data type.

Example 19–6 PLIST and *ENTRY PLIST Usage

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

** 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 PLISTC PARM COWSC PARM HOGSC PARM CHICKN*C FARM PLISTC PARM TRACTRC PARM COMBINC PARM PICKUP

19–11

Coding Subprograms

19.6 RETRN Operation


9−17 18−27 33−42 43−48 56−57 58−597−8 28−32 54−55

Opt Blank Blank Blank Blank BlankOpt RETRN Blank

The RETRN operation causes a subprogram to return to the callingprogram.

The RETRN operation is similar in function to the ENDSR (endsubroutine) statement. It tells a subprogram to exit immediately andreturn control to the calling program. When a RETRN statement isprocessed, the follow steps occur:

1 The halt indicators (H1 - H9) are checked. If a halt indicator is on, thesubprogram ends abnormally, closing all data files, and returning anerror status. If warning messages are enabled, a warning is issued tothe 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 streamsand deactivating the subprogram.

3 If neither the halt or LR indicators are on, the subprogram returnscontrol to the calling program. Data and indicator settings in thesubprogram are preserved.

Whether the subprogram exits normally, abnormally, or simply returns,any parameters passed to the subprogram are returned to the callingprogram. If a subprogram returns without ending, the next time it iscalled, it will resume operations with the field and indicator settings whichwere present when the subprogram last returned. A subprogram can bereinitialized using the FREE opcode. Subprograms which end normally orabnormally are automatically reinitialized the next time they are called.

19–12

Coding Subprograms

Example 19–7 RETRN Opcode Use

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

** 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 PLISTC PARM PHASERC PARM PHOTON*C PHASER ADD ENERGY PHASERC PHOTON ADD ENERGY PHOTON*C RETRN

19–13

Coding Subprograms

19.7 RPG Program Calling An RPG Subprogram ExampleThe following program examples demostrate how to code, compile, andlink an RPG calling program and an RPG subprogram. These programsand a build procedure (CALL.COM) can be found in the S3X$EXAMPLESdirectory. It is recommended that the sample programs and procedures becopied to a different directory before working with them.

Example 19–8 RPG Calling Program - CALL.RPG

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*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 10C 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 256C PARM 10 $SIZ 30*C CALL ’LFTJST’C FLD2 PARM FLD2 $FLDC PARM 15 $SIZ** Output fields after they are left justified.*C EXCPTDATA*C SETON LR*OOUTPUT E DATAO FLD1 10O FLD2 30

19–14

Coding Subprograms

Example 19–9 RPG Subprogram - LFTJST.RPG

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

** 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 1E LFT 256 1*I DSI 1 256 FLDI 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 PLISTC PARM FLDC PARM SIZE 30** This block of code left justifies the input field.*

IF C FLD IFNE *BLANKSAND C ORG,1 ANDEQ*BLANK

*C MOVEA*BLANKS LFTC Z-ADD1 I 30*

DOW C I DOWLESIZEAND C ORG,I ANDEQ*BLANK

C ADD 1 IEND C END

*C MOVEAORG,I LFT,1C 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 ExampleThe following program examples demostrate how to code, compile, andlink an RPG calling program, a Macro-32 interface module, and a COBOLsubprogram. These programs and a build procedure (PASS1.COM) canbe found in the S3X$EXAMPLES directory. It is recommended that thesample programs and procedures be copied to a different directory beforeworking with them.

Example 19–11 RPG Calling Program - PASS1.RPG

1 2 3 4 5 6123456789012345678901234567890123456789012345678901234567890123456789

*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 PLISTC PARM ALPHA1 12C PARM ALPHA2 16C PARM NUM1 60*C MOVE ’FOXTROT ’ALPHA1C MOVEL’SUPER ’ALPHA2C MOVE ’WOMAN ’ALPHA2C Z-ADD10 NUM1C EXCPTOUT** The CALL opcode is executed, calling the PASS1M* interface module and passing it the PARAMS* parameter list.*C CALL ’PASS1M’ PARAMS*C EXCPTOUTC SETON LR*OOUTPUT E OUTO ALPHA1 12O ALPHA2 30O 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 bythe 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 programon a VAX system.

Example 19–14 Commands Used to Build PASS1 Program on a VAXSystem

$ 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 programon an Alpha or Integrity system.

Example 19–15 Commands Used to Build PASS1 Program on an Alphaor 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 RoutinesExternal subroutines may be referenced from an RPG program in thesame manner as from an RPG program on the IBM System/36. Thisinvolves coding into the calculation specifications an EXIT op code. Uponencountering the EXIT op code, the RPG program will transfer controlto the subroutine named with the EXIT op code. If parameters are tobe passed to the external subroutine, they must be identified by RLABLop codes immediately following the EXIT op code. The RLABL op codeutilizes the result field and may be used to pass either data fields alreadydefined within the program, new data fields that are being defined inthe RLABL specification, or indicators. Indicators must be specified in aspecial format with IN as the first two positions of the result field followedby the two-digit number of the indicator to be passed.

The EXIT statement is translated by the compiler and generates a CALLGinstruction. The CALLG instruction is used to transfer to the desiredsubroutine and also pass the address of an argument list. Upon entry intothe external subroutine, the argument list pointer (AP) will be pointing tothe beginning of the argument list. The first long word on the argumentlist 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 descriptordescribing the parameters being passed in the RLABL statements thatfollow the EXIT. Note that the count of the number of long words in theargument list includes the long word containing the count. For example,if two RLABL statements are coded following an EXIT to indicate twoaddresses being passed to an external subroutine, the count in the firstlong word of the argument list will be three. This represents the totalnumber of long words in the argument list. In this example, the first longword would be the count of the list entries, and the following two longwords would represent the address of the field descriptor entries.

The field descriptor entries contain a long word that describes the lengthof 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 willcontain an A for alpha, N for zoned numeric, or a P for packed. In thecase of indicators, this address will be the address of a one-byte data fieldwhich will contain a value of zero if the indicator is off or a value of one ifthe indicator is on.

The following example shows the statements from an RPG program thatcan be used to access a subroutine and the corresponding assembler codingfor 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 6123456789012345678901234567890123456789012345678901234567890123

FCALLO O F 80 PRINTER*IDATAST DSI 1 4 FLD1I 6 9 FLD2I 11 140NUM*C Z-ADD1 NUM*C EXIT EXTSBRC RLABL NUMC RLABL FLD1C RLABL FLD2*C SETON LRC EXCPT*OCALLO E LRO NUM 10O FLD1 20O 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 LONGBNEQ 500$ ;NO - GIVE ERROR RETURN

MOVL 4(AP),R0 ;GET FLD 1 DESC ADDRMOVL 5(R0),R1 ;GET ADDR OF FLD1



MOVL (R1),(R2) ;COPY FLD1 INTO FLD2MOVL (R1),(R3) ;COPY FLD1 INTO FLD3

MOVL #1,R0 ;FLAG AS GOOD RETURNRET ;RETURN TO CALLER

500$: CLRL R0 ;FLAG AS ERROR RETURNRET

.END

20–3

21 Auto Report Features and Functions

The Auto Report Utility allows a programmer to build and compile RPGprograms from core modules and copybooks. The utility will consolidateunordered copybooks, sort the RPG specifications into the correct order,make programmer-specified modifications to the source code, and compilethe program. The following sections describe Auto Report features andfunctions.

The Auto Report Utility is invoked with the AUTOC command. TheAUTOC command and its qualifiers are described in the Migration RPGUser’s Guide.

21.1 Compile Qualifier Specification (U)An Auto Report compile can be qualified on the command line withqualifiers following the AUTOC command, or it can be qualified byparameters specified on a Compile Qualifier specification at the beginningof 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 validqualifiers found on the Compile Qualifier specification line will overridetheir counterpart qualifiers specified on the command line. The CompileQualifier specification is removed from the program after it has beenprocessed to avoid generating an error when the assembled program issubmitted to the RPG compiler.

The following parameters from the Compile Qualifier specification line arerecognized by Auto Report:

21–1

Auto Report Features and Functions

Table 21–1 Compile Qualifier (U) Specification Layout

Parameter Column(s)AllowableEntries Explanation

Form Type 6 U Identifies the specification as anAuto Report Compile Qualifierspecification. The first CompileQualifier specification encounteredwill be processed. Any subsequentCompile Qualifier specifications willbe ignored.

Retain Source 7 blank Delete generated source programafter it has been compiled.

C Retain generated source program.

This parameter will override the/SAVE qualifier in the commandline.

Save File Name 8 - 24 logical:filename Optional logical:filename whichcan be assigned to the generatedsource file. The System/36 formatof library,member is convertedto the OpenVMS format oflogical:filename. The logical nameis optional, but, if specified, a filename must be specified with it.The file will automatically be givena default extension of .AUT. If adifferent extension is desired, leavecolumns 8 - 24 blank and use the/SAVE qualifier on the AUTOCcommand line to specify the savefile name.

This parameter will override the/SAVE=file name qualifier in thecommand line.

Listing 30 blank, P Compiler listing file is to beproduced by the compiler.

B No compiler listing file is producedby the compiler.

This parameter will override the/LIST qualifier in the command line.

The remaining columns in the Compile Qualifier specification are not usedand should be left blank.

Example 21–1 depicts a Compile Qualifier specification used to establishsome program compilation parameters. The C in column 7 indicates thatthe program source file assembled by the Auto Report Utility is to beretained. The entry in columns 8 - 24 indicates that the assembled sourcefile 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 30indicates 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 512345678901234567890123456789012345678901234567890123456789

UCPAYROLL:VACATION B

21.2 CopybooksCopybooks are files of RPG specifications that are copied into thegenerated RPG program by Auto Report and organized correctly dependingupon specification type. Code copied in from a copybook has a C placedin column 5 of the RPG specification line in the generated source file toidentify it as copybook code.

Copybooks are included in an Auto Report program using the /COPYstatement. The /COPY statement must begin in column 7 of an RPGspecification line. The /COPY statement can be formatted in either of twoways, as shown in Example 21–2.

Example 21–2 /COPY statement layouts

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

C*C/COPY logical,filenameC/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 Reportwill recognize and process either format.

The logical name in the /COPY statement is optional, but the file namemust be specified. If a logical name is not specified, Auto Report willsearch for the copybook in the programmer’s current default directory.Copybook files are assumed to have an extension of .RPG. If the extensionis different, it must be specified in the /COPY statement. Auto Report willaccept up to 84 characters in a logical:filename string.

After the /COPY statement is processed, it is included in the generatedsource file as a comment.

If Auto Report cannot access the specified copybook, an error will be loggedto the terminal and as a comment in the generated source file.

Example 21–3 depicts the /COPY statements used to include the copybooksINVENTORY.RPG and DATE_SUB.SUBROUTINE from the GENERICarea into a program. The first example uses the standard OpenVMSfile format for the file names. The second example uses the System/36compatible file format, where the System/36 library name would beequated to a OpenVMS logical name. Note that the .RPG extensiondoes not need to be declared on the INVENTORY copybook because it isthe default extension. The .SUBROUTINE extension must be included onthe DATE_SUB copybook because it is a non-standard extension.

21–3


Example 21–3 /COPY statement usage

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*I/COPY GENERIC:INVENTORYC*C/COPY GENERIC:DATE_SUB.SUBROUTINE

- or -

1 2 3 4 512345678901234567890123456789012345678901234567890123456789

*I/COPY GENERIC,INVENTORYC*C/COPY GENERIC,DATE_SUB.SUBROUTINE

21.3 File and Field ModifiersThe Auto Report Utility allows File Description and Input Fieldspecifications 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 ofeach line that has been modified by Auto Report.

21.3.1 File Description Specification ModifiersA File Description specification which is included in a program from acopybook can be modified by a File Description specification followingthe /COPY statement within the core program. The File Descriptionspecification coming from the copybook is considered the primary definitionand the File Description specification used to modify it is considered themodifier specification. A File Description specification is considered amodifier specification when the file name in columns 7 - 14 matches thatof a previous File Description specification. All non-blank entries in themodifier specification are used to replace the corresponding entries inthe primary File Description specification. Blank entries in the modifierspecification do not affect the primary specification.

If an entry is to be blanked out in the primary File Descriptionspecification, enter an ampersand (&) in the first position of thecorresponding entry in the modifier specification.

Example 21–4 depicts the modification of the File Description specificationfor the file HOGWASH. Note the use of the ampersand (&) character toblank out the block size entry and the M placed in column 5 after the FileDescription 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:HOGWASHFHOGWASH U & 140FBACON 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 DISKFBACON ISE F 140 DISK

21.3.2 Input Field Specification ModifiersInput fields included from a copybook can be changed by modifierspecifications immediately following the /COPY statement. Inputrecord specifications cannot be modified. All Input field specificationsimmediately following a /COPY statement are considered modifierspecifications. The first non-input field specification encountered followinga /COPY statement signals the end of input field modifiers to the AutoReport Utility.

An input field included from a copybook can be changed by a modifierspecification with an I in column 6 and the same field name in columns53 - 58. An input field can only be modified once. Subsequent modifierspecifications with the same field name are treated as duplicate fielddefinitions within the input record.

Input field modifier specifications replace, add, or blank entries inthe same fashion File Description specifications are modified. Inputfield entries can be added or changed by placing the modified entry inthe corresponding columns of the modifier specification. Entries canbe blanked by placing an ampersand (&) in the first position of thecorresponding entry on the modifier specification. The following entriescan 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 includedfrom 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 andthe low indicator changed to 99.

• The ACTDAT field is changed from a trailing numeric field to apacked-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 BANKDATAI 1 10&ACCTNOI P 11 150BALANC & 99&I P 16 19 ACTDATI 20 21 ACTCODI P 34 380PRVBAL

(Copybook module)1 2 3 4 5 6 7

1234567890123456789012345678901234567890123456789012345678901234567890*I 1 100ACCTNOI P 11 150BALANC 101112I 16 210ACTDAT 20I 22 270LSTDEPI 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 ACCTNOMI P 11 150BALANC 99MI P 16 190ACTDAT 20CI 22 270LSTDEPCI 28 330LSTWTHI 20 21 ACTCODI P 34 380PRVBAL

21.4 Generated Source File OrganizationSpecifications processed by the Auto Report Utility do not have to be inorder. The utility will sort the specifications into order after all copybookshave been included. The Auto Report Utility will organize the outputsource 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 encounteredin a program, they are commented out when they are processed byAuto Report, as they have no meaning under OpenVMS and wouldgenerate errors during the RPG compile.

21.5 LimitationsThe 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 andfield specs)

10,000

(I) Input (DataStructures)

10,000

(I) Input (SAVDS DataStructure)

10,000

(I) Input (Local DataArea)

10,000

(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 andarray data

10,000

21–8


All comments count towards the limit of the specification type under whichthey are processed. Comment lines with a blank specified in column 6 areassigned to the specification type last processed.

21–9

A Character Sets

This appendix contains the ASCII character set, the hexidecimal value ofeach ASCII character, and the EBCDIC equivalent.

CharacterASCIIDecimal Hexadecimal

EBCDICDecimal 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



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



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



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 infunction to the WORKSTN device name. All of these designations referto terminal and keyboard activity as interpreted by the RPG program.However, all of these devices differ in the ways that they can interfacewith the associated program and in the manner in which output may bedisplayed on the terminal.

CONSOLE, KEYBORD, and CRT device designations are included toensure continuing compatibility with older RPG applications developed onnon-OpenVMS platforms. Because these three device designations havedisplay limitations (as explained under each subheading), they are not therecommended method of providing an interactive interface between theuser and the executing program.

Using a WORKSTN device is the recommended method of providinginteractive capability between the user and the executing program. Itoffers greater flexibility in programming applications. A WORKSTN devicecan be defined for both input and output operations. The programmer canspecify which fields on the display are input fields, which are output fields,and which are both input and output fields. (See the Migration RPGScreen Format Reference Manual for information on the WORKSTN deviceand how to program workstation screen specifications.)

B–1

CONSOLE, KEYBORD, And CRT Device Usage

B.1 Using a CONSOLE DeviceUsing the CONSOLE device in an RPG program enables the user to inputdata to an executing program from a display terminal. Display screenformats are automatically generated from the RPG input specificationsto prompt the user for the data needed. The data entered by the user isreturned to the RPG program as a record of contiguous bytes of data. Thisdata is received as if it had been read from a record-oriented device.

B.1.1 Limitations of a CONSOLE deviceThe 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 is20.

B.1.2 Coding a CONSOLE DeviceThe following sections describe how to code the File Description and Inputspecifications which define a CONSOLE device file.

B.1.2.1 Console Device File Description SpecificationA CONSOLE file requires one File Description specification. The FileDescription specification must be coded according to the following criteria:

Table B–1 Rules for Coding CONSOLE Device File DescriptionSpecification

Column AllowableNumber 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 DescriptionSpecification


S Secondary File

D Demand File

R Record Address File

Blank

17 E Indicates that every record must be processed before theprogram can end. Column 16 must contain either P, S, orR.

Blank Indicates that the program can end without processingevery record. It must be blank if column 16 contains a D.

18 A Indicates ascending record order. Allowed only if column16 identifies a P (primary) or S (secondary) file.

D Indicates descending record order. Allowed only if column16 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 Blocklength

Length must be equal to the record length defined incolumns 24 through 27.

Blank Accepted value. Defaults to record length.

24-27 Recordlength

This value must be the same as the highest endingposition defined for the CONSOLE file on the inputspecifications.

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 mustcontain the length of the key field to the file.

31 Blank Used for record address files only. Required if the keyfields in the record address file are the same as the keyfields in the indexed file.

A Used for record address files only. Identifies indexed fileswith zoned-decimal or trailing numeric key fields.

B–3


Table B–1 (Cont.) Rules for Coding CONSOLE Device File DescriptionSpecification


39 Blank Reserved for extension codes. Required if column 16contains P, S, or D.

E Reserved for extension codes. Required if column 16contains an R.

40-46 CONSOLE This field must contain CONSOLE as the device name.

TTY Required entry if column 15 contains D. Program mustthen be manually linked to runtime library.

71-72 U1-U8 Optional use of external indicator values.

B.1.2.2 Console Device Input SpecificationsInput specifications are not allowed for record address files. Recordaddress files can be easily identified by checking for the value of R incolumn 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 RecordSpecifications


7-14 File name Must contain the name of the CONSOLE device file.This name must match the name in the associated FileDescription specification.

14-15 OR Optional use of line to indicate a relationship betweenrecord-identifying indicators or record types.

15-16 Alphabeticcharacters

Can contain any two alphabetic characters if sequencechecking of input records is not desired.

Numericentry

If sequence checking is desired, code a numeric entry(between 01 and 99) in columns 15 and 16.

17 Blank Must be blank if columns 15 and 16 contain alphabeticentries.

B–4


Table B–2 (Cont.) Rules for Coding CONSOLE Device File Input RecordSpecifications


1 If the record type can consist of only one record andcolumns 15 and 16 contain numeric entries.

N If the record type can consist of one or more records andcolumns 15 and 16 contain numeric entries.

18 Blank Must be blank if columns 15 and 16 contain alphabeticentries.

O Can contain the letter O (to indicate record type isoptional) if columns 15 and 16 contain numeric entries.

19-20 01-99 Must contain a unique record-identifying indicator toidentify which command key will be used by the userto select this record type. Each record type requires adifferent indicator value.

24 1 Must contain this value to indicate that the recordidentification code starts in position 1.

26 C Indicates that the entire character is used for the recordidentification.

27 character Indicate expected character in position 1 of this recordformat.

28-34 Used asneeded

Fill as needed for record identification in position 2.

B–5


Table B–3 Rules for Coding CONSOLE Device File Input Specifications


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 cannotoverlap previously defined fields.

53-58 Field name Must contain a unique field name from one to sixalphameric characters. This name will display as theprompt.

59-60 Blank Field not used.

L1-L9 Optional use of control-level indicators if this has beendefined as either a primary or secondary file.

61-62 Blank Field not used.

M1-M9 Optional use of matching record indicators if this hasbeen defined as either a primary or secondary file.

B–6


B.1.3 Automatic Generation of Display Screen FormatsTo build an executable image of an RPG program with a CONSOLE device,first compile the RPG program with the Migration RPG compiler. Proceedwith the next step only if no errors occurred during the compilationprocess.

The next step involves invoking the RPG CONSOLE format generator,RPGCON. RPGCON expects an input of RPG source code. It reads theFile Description and Input specifications for the CONSOLE file andoutputs a file of S & D specifications describing the screens to be usedduring program execution.

RPGCON can be invoked in either of the following ways:

$ RPGCON ABC

- or -

$ RPGCONCON>ABC

where "ABC" is the name of the file containing the RPG source codestatements. The following rules apply when using RPGCON:

• An extension of .RPG is assumed for the input file. If this is not thefile name extension, then the extension must be given explicitly.

• The output file will be given the same name as the input file, withFM appended to the file name. The output file will have an extensionof .FRM to indicate screen format file. For example, if the RPGsource file being processed by RPGCON was labeled FOZZ.RPG, thescreen format file produced by the RPGCON Utility would be labeledFOZZFM.FRM.

The output file generated by the RPGCON Utility contains screen formatsource code (S & D specifications) and may be edited (or customized) asmuch as necessary. This file must then be compiled using the screenformat generator (SFG).

Following the compilation of the screen format file, an executable imageis produced by linking the program object generated by the RPG compilerand the screen object generated by the screen format generator.

The following example indicates how a CONSOLE program would becompiled 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 FilesThe display screen generated by the preceding steps will consist of a topline containing control information for the user and data fields arrangedon lines 2 through 23.

The data fields will display in four different formats, according to thefollowing criteria:

Table B–4 CONSOLE Device File Display Formats

Format Explanation

One Column Used whenever the number of fields being prompted is less than24.

Two Columns Used whenever the number of fields being prompted is between24 and 46.

Three Columns Used whenever the number of fields being prompted is between47 and 69.

Four Columns Used whenever the number of fields exceeds 69.

RPG does not support the use of multiple record formats with CONSOLEdevices. All screen formats generated by the utility RPGCON are giventhe format name XX. This means that only the first format in the screenformat file will be displayed to the user for the purposes of inputtingdata. If multiple record types have been defined for the CONSOLE device,the following message will be displayed when the screen format file iscompiled:

** WARNING ** 100 - Duplicate screen name, XX in S specification

The following sections describe the fields which appear on the control lineand how to interact with a CONSOLE screen.

B.1.4.1 Record Identification CodeThe first field displayed on line one is the record identification code ofthe record for which data is being prompted. This field contains 1 or 2characters, as defined in the input record specification.

B.1.4.2 Record Identifying IndicatorThe second field displayed on the first line is the record identifyingindicator for the input format being displayed. This field is designatedoutput only and cannot be modified by the user.

The third field on line one is another output only field which displays therecord identifying indicators for record types other than the one currentlyselected.

B–8


B.1.4.3 Data FieldsData fields are generated in either a one-, two-, three-, or four-columnformat, depending on the number of fields and each field’s size. When adata format is displayed, the cursor is always positioned on the first datafield of the format. Cursor control keys may be used to move from one fieldto another. No data is returned to the RPG program until the PF4 key ispressed. End-of-file is indicated by entering a CMD12 ( PF1 + = ). Thisreturns 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 inputspecifications,

• 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 lengthand decimal positions, with a period separator between the two items.

B–9


B.2 Using a CRT DeviceA CRT device can be used to display information to a user’s screen. Itcannot be used to input data. A CRT device requires the coding of aFile Description specification and Output specifications. A CRT device isnormally associated to the terminal which invokes the CRT program.

B.2.1 Limitations of a CRT DeviceThe 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 FileThe 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 specificationand 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 SpecificationEach CRT device requires one File Description specification. Each FileDescription specification must be coded according to the following criteria:

B–10


Table B–5 Rules for Coding CRT File Description Specification


7-14 File name Must contain the name of the CRT file.

15 O Output File (Required entry)

20-23 Blocklength



24-27 Recordlength

Must contain the length of the largest record to be output.

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 SpecificationsThe following rules apply for coding the Output specifications associated toa CRT device file:

Table B–6 Rules for Coding CRT Output Specification


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 thecurrent line.

18 0-9 Indicates how many lines to skip after writing thecurrent 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 anE.

B–12


Table B–7 Rules for Coding CRT Output Field Specifications


23-31 Indicators Optional use to condition output.

32-37 AlphamericCharacters

Optional entry. Can identify the field names to beoutput.

38 Edit code Optional entry of predefined edit code.

39 B Optional entry to indicate resetting field to blank orzero.

40-43 NumericValue

Entry to indicate ending position of entry.

45-70 AlphamericCharacters

Optional entry to contain either an edit word or aliteral constant.

B.2.2.3 Displaying Data Using a CRT DeviceData is displayed to the user’s screen during normal detail and total-timeoutput operations. It can also be displayed during calculations using theEXCPT operation and exception output records.

B–13


B.3 Using a KEYBORD DeviceA KEYBORD device can be used as an input and output device. AKEYBORD device requires a File Description specification, but doesnot use Input or Output specifications. Instead, the KEYBORD deviceis referenced by the SETnn and KEYnn operation codes. The KEYBORDdevice is normally associated to the terminal which invokes the KEYBORDprogram.

B.3.1 Limitations of a KEYBORD DeviceThe 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 FileTo use a KEYBORD device in an RPG program, a File Descriptionspecification must be coded. Input and output specifications are notused for a KEYBORD device. Instead, SETnn or KEYnn operations arecoded in the Calculation specifications to manipulate the necessary data.

B.3.2.1 KEYBORD Device File Description SpecificationEach KEYBORD device requires one File Description specification. EachFile Description specification must be coded according to the followingcriteria:

Table B–8 Rules for Coding KEYBORD Device File DescriptionSpecification


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 orsecondary files.

B–14


Table B–8 (Cont.) Rules for Coding KEYBORD Device File DescriptionSpecification


D Demand File. If KEYBORD is defined as a demand file,then the KEYnn operation code is used to read the recordsfrom the file.

19 F or Blank Defines fixed file format.

20-23 Blocklength



24-27 Recordlength

Must contain the length of the largest field to be entered.

40-46 KEYBORD This field must contain KEYBORD as the device name.

B.3.2.2 Calculation SpecificationsAlthough a KEYBORD file is an input/output file, it does not use Inputspecifications. Instead, input and output data are handled by the SETnnand KEYnn operations within the Calculation specifications. The KEYnnoperation causes a pause in calculations, enabling the user to enter data.The SETnn operation can be used to display data and prompt for commandkey input. The SETnn and KEYnn operations are described in detail inChapter 11, Operation Codes.

B–15


B.3.2.3 KEYnn OperationThe KEYnn operation provides the following functionality:

• Display the contents of the the field, literal, table, or array elementcoded in factor 1

• Display user level message members (01 - 99) if specified in the SETnnoperation

• Enter data into the field specified in the result field

To use the KEYnn operation, the following rules apply for coding theCalculation specification:

Table B–9 Rules for Coding KEYBORD Calculation Specification for aKEYnn Operation


7-8 Control-levelIndicator

Optional use of L1-L9, AN, OR, or blanks.

9-17 ConditioningIndicators

Optional use of indicators, command-key indicators(KA-KN, KP-KY), or blanks.

18-27 Alphamericcharacters

Can contain constant, literal, field name, tableor array element to be displayed. Entries inthese columns cause informational prompts to bedisplayed to assist in data entry. Entries in thesecolumns override any entries made in columns31-32.

28-30 KEYnn Must contain KEYnn operation code.

31-32 Message ID Optional numeric entry between 01 and 99that corresponds to a predefined message. Anentry is required in columns 31 and 32 whencolumns 18-27 are blank. A computer-generatedprompt will display the following message duringprogram execution if the user-defined messageis inaccessible for any reason. ( RTS-030- MICMessage File not found )

33-42 Blank Must be blank.


Optional entry to define name of field to beentered.

B–16


Table B–9 (Cont.) Rules for Coding KEYBORD Calculation Specificationfor a KEYnn Operation


49-51 Field Length Required entry if not defined elsewhere in the RPGprogram.

52 Blank Alphameric field must have a blank in this column.

0-9 Numeric fields require an entry that defines thenumber of decimal positions.

54-59 01-99 Optional entry to test the condition of a field.

B.3.2.3.1 Bypassing a KEYnn OperationThe KEYnn operation causes a pause in program execution while waitingfor the user to enter a response. To bypass the KEYnn operation andcontinue, the user can press the Enter , Return , or PF4 key. If a KEYnnoperation is bypassed, the contents of the result field are initialized toblanks or zeros.

B–17


B.3.2.4 SETnn OperationThe SETnn operation provides the following functionality:

• Display the contents of the the field, literal, table, or array elementcoded in factor 1

• Display user level message members (01 - 99) if specified in the SETnnoperation

• Enter the command keys identified in columns 54 - 59

To use the SETnn operation properly, the following rules apply for codingthe Calculation specification:

Table B–10 Rules for Coding KEYBORD Calculation Specification forSETnn Operation


7-8 Control-levelIndicator

Optional use of L1-L9.

9-17 ConditioningIndicators

Optional use of indicators, command-key indicators(KA-KN, KP-KY), or blanks.


Can contain constant, literal, field name, tableor array element to be displayed. Entries inthese columns cause informational prompts to bedisplayed to assist in data entry. Entries in thesecolumns override any entries made in columns31-32.

28-30 SETnn Must contain SETnn operation code.

31-32 Message ID Optional numeric entry between 01 and 99that corresponds to a predefined message. Anentry is required in columns 31 and 32 whencolumns 18-27 are blank. A computer-generatedprompt will display the following message duringprogram execution if the user-defined messageis inaccessible for any reason. ( RTS-030- MICMessage File not found )

B–18


Table B–10 (Cont.) Rules for Coding KEYBORD CalculationSpecification for SETnn Operation


54-59 Command Keys Optional entry to define up to three command keysthat can be used when the program is executingthis operation. If a command key that has beencoded on this line is used, that indicator remainson until it is specifically turned off by a SETOFoperation or until it is used again in a SETnnoperation.

B–19

Index

AAdding records • 13–24Addition • 11–9ADD operation code

example • 12–11general information • 11–1rules • 11–9

ADD optionoutput specifications • 9–4

addrout filesFile Description specification • 13–17

Addrout filescreating • 13–16example • 13–16, 13–19Extension specification • 13–18file designation • 4–6function • 13–16record length • 4–8rules for specifying • 13–17specifying

key length • 4–15Alphameric data

defining fieldsexample • 10–3

Alphameric fieldscomparing • 11–3

Alphameric literalsfactor 1

calculation specifications • 8–4factor 2

calculation specifications • 8–6Alternate collating sequence • 3–5

alternate sequence tablecoding • 17–1

specifying • 17–1Alternate format

arrays • 15–21compile-time • 15–21pre-execution-time • 15–21related • 15–21

Alternate keysspecifying • 4–24

Alternate sequence tablecoding • 17–1

ALTSEQ • 17–2AND

input specifications • 7–2, 7–3, 7–4, 7–8, 12–6output specifications • 9–2record identification

example • 12–7ANDxx operation code

general information • 11–3, 11–7rules • 11–11

Arithmetic operation codes • 11–1rules • 11–1

signs • 11–2Arithmetic operations • 11–136

addition • 11–9division • 11–34

remainder • 11–94multiplication • 11–92square root • 11–124subtraction • 11–125zero add • 11–137zero subtract • 11–138

Array elementsoutputting • 15–34searching • 15–30

Array namealternate entry • 5–8primary entry • 5–4

Arrays • 15–15alternate format • 15–21compile-time • 15–17compile-timed

delimiter • 15–17creating • 15–18

array input records • 15–18definition • 15–15elements

loadinginput specifications • 7–11

execution-time • 15–18*IN,xx indicators • 12–31in calculations • 15–26

example • 15–27indexed

LOKUP operation code • 11–74*IN indicators • 12–31input records

example • 15–18

Index–1

Index

Arrays (cont’d)

loadinginput specifications • 7–11

loading timeselecting • 15–16

LOKUP operation code • 11–74, 15–29example • 15–30

MOVEA operation code • 15–31moving data • 11–5, 15–31names • 10–9non-indexed

LOKUP operation code • 11–74operations

LOKUP • 11–71outputting

array elements • 15–34entire arrays • 15–33

permanent update • 15–32pre-execution-time • 15–18referencing • 15–25


related • 15–19searching • 11–74, 15–29

example • 15–30rules for specifying • 15–29

searching for elements • 15–30sequencing • 11–72set up and usage example • 11–76specifying • 4–4, 15–21

data formatalternate entry • 5–9primary entry • 5–6

decimal positionsalternate entry • 5–10primary entry • 5–7

elements • 15–27from-file name • 5–2length of entry

alternate entry • 5–9primary entry • 5–6

namesalternate entry • 5–8primary entry • 5–4

number of entries • 5–5number of entries per record • 5–4sequence


to-file name • 5–3temporary update • 15–32

Arrays (cont’d)

transferring data • 11–5types

compile-time • 15–17execution-time • 15–18pre-execution-time • 15–18

updating • 15–32using • 15–15writing


XFOOT operation codeexample • 15–28

Arrays(XS)sorting • 11–122Arrays(XS)summing elements

XFOOT • 11–136ASCII character set • A–1Asterisk protection • 9–25AUTOC

Auto Report UtilitySee also: Migration RPG User’s Guide • 21–1

Automatic overflow • 14–7Auto Report Utility

compile qualifiersU specification • 21–1

file description specification modifiers • 21–4Input specification modifiers • 21–5

BBEGSR operation code

general information • 11–4rules • 11–13

Binary datadefining fields

example • 10–5Binary data types

longword • 10–4specifying

tables and arraysalternate entry • 5–9primary entry • 5–6

word • 10–4Bit manipulation

moving zonehigh to high • 11–79high to low • 11–80low to high • 11–81low to low • 11–82

testing bits • 11–128

Index–2

Index

Bit manipulation (cont’d)

turning bits off • 11–14turning bits on • 11–16

BITOF operation codegeneral information • 11–2rules • 11–14

BITON operation codegeneral information • 11–2rules • 11–16

Bit operation codes • 11–2Blank after

output specifications • 9–19Block length • 4–8Branching • 11–63

conditional • 11–17target label • 11–127

Branching operation codes • 11–3

CCABxx

comparison operations • 11–17CABxx operation code


Calculationsarrays • 15–26documenting • 8–10referencing


result field • 8–7rounding data

half-adjust • 8–9specifying

decimal positions • 8–8factor 1 • 8–4factor 2 • 8–4, 8–6field length • 8–8operation codes • 8–5resulting indicators • 8–10

totaling data • 12–26using indicators

conditioning • 8–2resulting • 12–10

Calculation specification • 8–1comments • 8–10control break indicators • 8–2decimal positions • 8–8factor 1 • 8–4

Calculation specification (cont’d)

factor 2 • 8–6field length • 8–8general description • 1–3half-adjust • 8–9indicators

conditioning • 8–2operation codes • 8–5, 11–1result field • 8–7resulting indicators • 8–10

CALLexample • 19–17

COBOL subprogram • 19–17Macro-32 subprogram • 19–17RPG subprogram • 19–14

operation code • 19–2rules • 19–2

Called program operation codesCALL • 11–19, 19–2EXTRN • 11–57, 19–4

subprogram naming convention • 19–4FREE • 11–61, 19–6PARM • 19–7PLIST • 19–11RETRN • 19–12RPG

PARM • 11–98PLIST • 11–102RETRN • 11–111

CallingOpenVMS Run-Time Library procedures • 19–2subprograms • 19–2

RPG • 11–19system services • 19–2

Call interfaceRPG • 11–19

CALL operation codegeneral information • 11–4rules • 11–19

*CANCLlogic cycle • 1–13

CASxx operation codegeneral description • 11–8general information • 11–3, 11–4, 11–7rules • 11–21

Chained file • 4–5Chained files

processing moderecord address type

valid combinations • 4–16Record address type

Index–3

Index

Chained filesRecord address type (cont’d)

processing modevalid combinations • 4–16

CHAIN operationexample • 13–13

CHAIN operation codegeneral information • 11–6rules • 11–24

Character datadefining fields

example • 10–3Character data type

example • 10–2Character sets

ASCII • A–1Decimal • A–1EBCDIC • A–1Hexadecimal • A–1

Collating sequences • 17–1alternate • 3–5alternate sequence table

coding • 17–1ASCII • 3–5EBCDIC • 3–5file translation parameters • 17–4

coding • 17–4specifying • 17–1

EBCDIC • 17–1file translation parameters • 17–1user defined • 17–1

user-defined • 3–5Collating sequencess

alternate • 17–1Column numbers • 2–1Command key indicators • 12–19Comments • 2–3, 8–10

control specification • 3–6extension specifications • 5–11file description specification • 4–27input specifications • 7–18line counter specifications • 6–3output specification • 9–28

Compare operation codesCOMP • 11–3

Comparing data • 11–27Compile Qualifier specification • 21–1Compiler directives • 2–3

/COPY • 2–4/EJECT • 2–4/SPACE • 2–4/TITLE • 2–4

Compile-time arrays • 15–17advantages • 15–17creating • 15–19, 15–22

rules for specifying • 15–19delimiter • 15–19outputting • 15–33updating • 15–32writing • 15–33

Compile-time tables • 15–2advantage • 15–3delimiter • 15–4input records

creating • 15–4rules for specifying • 15–4

outputting • 15–15rules for defining • 15–7

COMP operation codeexample • 12–11general information • 11–3rules • 11–27

Conditioning indicatorsrelationship with control level indicators

calculation specifications • 8–4CONSOLE • B–2 to B–9

automatic generation of display screen formats •B–7

displaying CONSOLE device files • B–8control key usage • B–9record identification code • B–8record identification indicator • B–8

file description specification • B–2input specifications • B–4limitations of • B–2

Constantsoutput specifications • 9–22

Continuation entries • 4–21Continuation lines • 4–20

continuation entries • 4–21continuation options • 4–21disk files • 4–21INFDS data structure • 4–23INFSR subroutine • 4–23SPECIAL device files

entries • 4–21options • 4–21

specifying a screen format file • 4–23workstation device files


Continuation options • 4–21

Index–4

Index

CONTINUEhalt response • 1–11

Control breakexample • 1–17indicator initialization • 1–12last record • 1–12

Control break indicators • 12–12calculation specifications • 8–2conditioning data

input specifications • 7–12function • 12–12input specifications • 7–12setting • 11–6split-control fields • 12–16usage • 1–13

Control breaks • 1–13processing • 1–13split-control fields • 12–16

Control level indicatorsrelationship with conditioning indicators

calculation specifications • 8–4Control specification • 3–1

Alternate collating sequence • 3–5comments • 3–6currency symbol • 3–3date edit code • 3–4date format code • 3–3DEBUG option • 3–2general description • 1–2inverted print • 3–4mulitple • 3–1

/COPYcompiler directive • 2–4

CopybooksAuto Report • 21–3

/COPY statement(XS)Auto Report utilityexample • 21–3

Creating filesadd entry • 4–24buffers • 13–38

CRT • B–10 to B–13file description specification • B–10limitations of • B–10output specifications • B–12

field • B–12record • B–12

Currency symbol • 3–3floating

output specifications • 9–23rules for specifying • 3–3

DData

comparing contents • 11–3fields

initialization • 11–137, 11–138moving • 11–5, 11–6, 11–83, 11–85, 11–89

arrays • 11–85left-justified • 11–89right-justified • 11–83tables • 11–85

moving from the left • 11–6transferring • 11–5, 11–6

Data filesaddrout access

File Description specification • 13–18file translation parameters

coding • 17–4translation parameters • 17–4

Data formatsbinary


Extension specificationalternate entry • 5–9primary entry • 5–6

input specification • 7–9numeric


output specification • 9–21packed-decimal


Data Structures • 7–1defining • 16–1defining subfields • 7–11, 7–12initialization • 16–3input specifications

name • 7–2local data area • 16–6name • 7–2output • 9–12output specifications • 9–12redefining input records • 16–5reorganizing input fields • 16–6subfields • 16–2, 16–4

Index–5

Index

Data Structuressubfields (cont’d)

binary • 16–3numeric • 16–3packed • 16–3

updating files • 13–26using • 16–3using storage in more than one way • 16–5

Data transfermove

rules • 11–5Data types • 10–1

binary • 10–4character • 10–2packed-decimal • 10–6specifying


zoned-decimal • 10–7Date

edit code • 3–4format • 3–3

Debugging Migration RPG programs • 11–29DEBUG operation code

rules • 11–29Decimal character set • A–1Decimal positions

calculation specification • 8–8extension specification


input specification • 7–10Deferred write • 4–26DEFN operation code

rules • 11–32Deleting records

example • 13–28DEL option

output specifications • 9–4Demand file • 4–5Demand files


valid combinations • 4–16Detail records

output specifications • 9–3Detail time • 1–7

processing individual records • 1–18Detail time processing

setting LR • 11–6

Detail time recordsoutput specifications • 9–3

Device codes • 4–18rules for specifying • 4–20specifying

card reader • 4–18disk • 4–18printer • 4–18workstation • 4–18WORKSTN • 4–18

Device display limitations • B–1Disk device

specifying • 4–18Disk files

continuation lines • 4–21Division • 11–34

remainder • 11–94DIV operation code

general information • 11–1MVR operation code • 11–94remainder • 11–94rules • 11–34

Do loop • 11–7DO operation code


Do until loop • 11–7DOUxx operation code


Do while loop • 11–7DOWxx operation code


EEBCDIC character set • A–1EBCDIC collating sequence

specifying • 17–1Edit Code modifiers

output specifications • 9–23Edit codes

example • 9–18, 12–5Y edit code • 13–19

output specifications • 9–17specifying

notation • 3–4

Index–6

Index

Edit wordsbody • 9–24expansion • 9–24output specifications • 9–24sign • 9–24specifying

asterisk protection • 9–25blank spaces • 9–25CR • 9–27negative signs • 9–27zero suppression • 9–25

/EJECTcompiler directive • 2–4

ELSE operation codegeneral information • 11–7rules • 11–45

End-of-file • 4–6matching fields • 4–6processing • 1–13

End-of-job • 1–13END operation code

CASxx • 11–47DO • 11–47DOUxx • 11–47DOWxx • 11–47general information • 11–7IFxx/ELSE • 11–47rules • 11–47

End positionoutput record • 9–20output specifications • 9–20

ENDSR operation codegeneral information • 11–4rules • 11–49

*ENTRY PLISTprocessing in first cycle • 1–10returning parameters • 1–12usage • 1–10

Errorshandling • 12–20

halt indicators • 12–20Error trapping

INFDS data structure • 4–23INFSR subroutine • 4–23record locking

example • 11–26Exception handling

INFSR data structure • 4–23INFSR subroutine • 4–23

Exception processingREAD operation • 11–105

Exception recordsoutput specifications • 9–3

EXCPTnames • 10–9

EXCPT nameoutput specification • 9–12, 9–16

EXCPT operationCHAIN operation • 11–25example • 13–13

EXCPT operation codegeneral information • 11–6rules • 11–51

Execution-time arrays • 15–18creating • 15–18, 15–24

rules for specifying • 15–18outputting • 15–33writing • 15–33

EXIThalt response • 1–11

EXIT operation codegeneral information • 11–4rules • 11–54

EXSR operation codegeneral information • 11–4rules • 11–56

Extension code • 4–18Extension specification

array or table namealternate entry • 5–8primary entry • 5–4

comments • 5–11data format



definingarrays • 5–1record-address files • 5–1tables • 5–1

from-file name • 5–2general description • 1–2length of entry


name of record-address file • 5–2name of table input file • 5–2number of entries per record • 5–4number of entries per table or array • 5–5sequence

Index–7

Index

Extension specificationsequence (cont’d)


to-file name • 5–3External call operation codes

general information • 11–4External indicators • 12–30

controlling the opening of files • 12–30file conditioning • 4–25file description specification • 4–25first cycle • 1–10function • 12–30specifying • 12–30

External routinesSPECIAL device

routine name • 4–20EXTK

specifying • 13–15EXTRN

operation code • 19–4accessing

link-time constants • 19–4OpenVMS Run-Time Library status

codes • 19–4OpenVMS Run-Time Library procedures •

19–4rules • 19–4

subprogram naming convention • 19–4subprogram naming convention • 19–4

EXTRN operation codeaccessing

link-time constants • 11–57OpenVMS Run-Time Library status codes •

11–57OpenVMS Run-Time Library procedures • 11–57rules • 11–57

FFactor 1

alphameric literalscalculation specifications • 8–4

calculation specifications • 8–4figurative constants

calculation specifications • 8–5labels

calculation specifications • 8–5Numeric literals

calculation specifications • 8–4

Factor 1 (cont’d)

restrictionscalculation specifications • 8–5

special wordscalculation specifications • 8–4

specifying *IN,xx indicator array elements • 8–5specifying *INxx indicators • 8–5

Factor 2alphameric literals

calculation specifications • 8–6calculation specifications • 8–6figurative constants

calculation specifications • 8–6labels

calculation specifications • 8–6Numeric literals

calculation specifications • 8–6restrictions

calculation specifications • 8–7special words

calculation specifications • 8–6, 8–7specifying *IN,xx indicator array elements • 8–6specifying *INxx indicators • 8–6

Fetch overflow • 14–10example • 14–12output specification • 9–5rules for specifying • 14–11

Field definition*LIKE DEFN • 11–32

Field indicators • 12–8checking the condition of data fields

input specifications • 7–17conditioning input data

input specifications • 7–17example • 12–9function • 12–8

Field lengthcalculation specifications • 8–8

Field nameinput specification • 7–11output specification • 9–12

Field names • 10–9Field positions

end • 7–10start • 7–10

Field-record-relation indicatorsconditioning input data

input specifications • 7–15controlling data extraction

input specifications • 7–15input specifications • 7–15

Index–8

Index

Field-record-relation indicators (cont’d)

using matching fields • 13–30example • 13–31

Fieldsbinary data

example • 10–5calculation

example • 10–3character data

example • 10–3common • 2–2defining

binaryexample • 10–5

characterexample • 10–3

packed-decimalexample • 10–6

defining positionsend • 7–10start • 7–10

defining start and end positions • 7–9indicators • 12–8initialization • 11–137, 11–138input

binaryexample • 10–5

characterexample • 10–3

packed-decimalexample • 10–6

specifyingdecimal positions • 7–10

look-ahead • 7–5matching • 13–29

checking sequence • 4–7input specifications • 7–14

naming • 7–11packed-decimal data

example • 10–6specifying

data format • 7–9*IN,xx • 7–11, 7–12*INxx • 7–11, 7–12length

calculation specifications • 8–8PAGE1 - PAGE7 special words • 7–11, 7–12PAGE special word • 7–11, 7–12

split-control • 12–16testing values • 12–8using indicators to compare contents

Fieldsusing indicators to compare contents (cont’d)

input specifications • 7–12Field start and end positions • 7–9Figurative constants

factor 1calculation specifications • 8–5


File access methodsrandom • 13–12sequential • 13–5, 13–6sequential by key • 13–6sequential within limits • 13–7table • 13–5

File addition • 4–24File buffers • 13–38File conditioning indicator • 4–25File creations

add entry • 4–24File description specification • 4–1

alternate key • 4–24Block length • 4–8comments • 4–27continuation entries • 4–21continuation lines • 4–20continuation options • 4–21device code • 4–18end-of-file • 4–6Extension code • 4–18file addition • 4–24file conditioning indicator • 4–25file designation • 4–4file format • 4–7file name • 4–2file organization • 4–16file sharing • 4–25file type • 4–3key length • 4–15key start location • 4–17no deferred write • 4–26overflow indicators • 4–17processing mode • 4–8record address type • 4–15record length • 4–8sequence • 4–7SPECIAL device routine • 4–20Unordered output • 4–24

File Description specification modifiersAuto Report Utility • 21–4

Index–9

Index

File designations • 4–4array • 4–4chained • 4–4demand • 4–4full-procedural • 4–4primary • 4–4record-address • 4–4secondary • 4–4table • 4–4

File format • 4–7File names • 10–9

file Description specification • 4–2input specification • 7–2Line Counter specification • 6–1output specification • 9–2rules for specifying • 13–2

File organizations • 4–16indexed • 13–4relative • 13–3sequential • 13–3

Filesadding records • 13–24addrout • 13–16

specifyingkey length • 4–15

arrayinput

specifying • 5–2output

specifying • 5–3chained • 4–5characteristics • 13–1conditioning with an external indicator • 4–25creating • 13–21

indexed • 13–22output • 14–1printer output • 14–1record-limits • 13–7relative • 13–22sequential • 13–21

definition • 13–1deleting records • 13–28demand • 4–5external indicators • 12–30file access methods • 13–5file names • 13–2file types • 13–2first cycle

openning • 1–10full-procedural • 4–5, 13–19

example • 13–20

Files (cont’d)

indexedprocessing modes • 4–12reading • 11–24sequential access via a key • 11–107Setting an access point • 11–118specifying

key length • 4–15input/output operation codes • 11–6KEYBORD file

processing modes • 4–14limits


look-ahead read • 1–12matching record indicator • 12–28multifile processing • 13–29organization • 13–3output • 14–1

controlling overflow • 4–17using overflow indicators • 4–17

primary • 4–4primary read • 1–12printer file

processing modes • 4–13printer output • 14–1

controlling overflow • 4–17using overflow indicators • 4–17

processing mode • 4–8processing using matching fields

input specifications • 7–14random access • 13–12random access by key • 13–19record address

processing modes • 4–13specifying • 5–2

record-address • 4–5record formats • 13–2record-limits • 13–7relative

processing modes • 4–11reading • 11–24

secondary • 4–4secondary read • 1–12sequence code • 4–7sequential

processing modes • 4–9sequential access • 13–5, 13–6, 13–19sequential by key access • 13–6sequential input • 11–104

reversed • 11–109

Index–10

Index

Files (cont’d)

sequential input based on a key • 11–107sequential within limits access • 13–7sharing • 4–25SPECIAL file

processing modes • 4–14specifying

chained • 4–4demand • 4–4display • 4–3full-procedural • 4–4input • 4–3output • 4–3primary • 4–4processing mode • 4–8record-address • 4–4secondary • 4–4update • 4–3

tableinput

specifying • 5–2output

specifying • 5–3updating records • 13–26workstation address

processing modes • 4–13*FILES • 17–5File sharing

column 73 access codes • 4–26definition • 4–25specifying • 4–25usage • 4–26

File specificationgeneral description • 1–2SUBR01 • 4–21

File translation • 3–6File translation code • 3–6File translation parameters

coding • 17–4specifying • 17–1, 17–4

File types • 4–3display • 4–3input • 4–3, 13–2output • 4–3, 13–2update • 4–3, 13–2

First cycle • 1–15reading records • 1–12steps • 1–10

First pageindicator initialization • 1–12

First-page indicator • 14–6output specifications • 9–10

First page indicators • 12–24conditioning output data • 12–24example • 12–24function • 12–24

FLform length flag • 6–2

Floating currency symbolexample • 12–5output specifications • 9–23

FORCE • 1–12FORCE operation code


Form lengthFL • 6–2line counter specification • 6–2

Form length flagFL • 6–2line counter specification • 6–2

FREEoperation code • 19–6

rules • 19–6FREE operation code

rules • 11–61From-file name

arrays • 5–2record-address files • 5–2tables • 5–2

Full-procedural file • 4–5Full-procedural files




G*GETIN

logic cycle • 1–11GOTO

TAG • 11–127target • 11–127

GOTO operation codegeneral information • 11–3rules • 11–63

Index–11

Index

HHalf-adjust

calculation specification • 8–9Halt indicators • 12–20

batch • 1–11, 12–20controlling program execution • 12–20example

field indicator • 12–21record-identifying indicator • 12–21resulting indicator • 12–21

function • 12–20handling errors • 12–20interactive

response • 1–11last cycle • 1–14processing • 1–11, 12–20

RPG subprograms • 12–22response • 1–11, 12–20setting • 11–6

Halt processingmatching fields • 1–13record identification • 1–13

Header specification • 3–1mulitple • 3–1

Heading recordsoutput specifications • 9–3

Hexadecimal character set • A–1

IIBM RPG II compatibility

record address fileskey length • 4–8, 4–15

IFnn operationexample • 13–13

IFxx operation codeELSE • 11–45general information • 11–3, 11–7rules • 11–65

*IN • 12–31*IN,xx • 12–31*IN,xx indicators • 12–31

example • 12–31function • 12–31

Indexed file organization • 13–4example • 13–4index key • 13–4

Indexed file organizationindex key (cont’d)

example • 13–4Indexed files

adding records • 13–25example • 13–26rules for specifying • 13–26

alternate keysspecifying • 4–24


deleting recordsexample • 13–28

processing modes • 4–12specifying

key length • 4–15key start location • 4–17

updating recordsexample • 13–27rules for specifying • 13–27

Indicators • 12–101 - 99

usage • 12–4, 12–8, 12–10calculation specifications

conditioning • 8–2conditioning

calculation specifications • 8–2output • 9–9

control break • 12–12end-of-job • 1–13

control-levelcalculation specifications • 8–2input specifications • 7–12

external • 12–30first cycle • 1–10

field • 12–8input specifications • 7–17

field-record-relationinput specifications • 7–15

first page • 12–24first-page • 14–6

output specifications • 9–10H1 - H9 • 12–1, 12–20

usage • 12–4, 12–8, 12–10halt • 12–20*IN • 12–31*IN,xx • 12–31



result field

Index–12

Index

Indicators*IN,xx

result field (cont’d)

calculation specifications • 8–7*INxx • 12–32



result fieldcalculation specifications • 8–7

KA - KN, KP - KY • 12–19usage • 12–10

L0 • 12–1, 12–12, 12–27output specifications • 9–10

L1 - L9 • 12–12usage • 12–4, 12–10

last recordend-of-job • 1–13

Last Record • 12–26Level Zero • 12–27LR • 12–1, 12–12

example • 12–5usage • 12–4, 12–10

matching record • 12–28MR • 12–1, 12–28negating

calculation specifications • 8–2OA - OG, OV • 12–17

usage • 12–10overflow • 4–17, 12–17, 14–71P • 12–1, 12–24, 14–6

example • 12–5printer output files • 14–6program defined • 12–1record identification • 1–13record identifying

01 - 99 • 12–4H1 - H9 • 12–4L1 - L9 • 12–4LR • 12–4

record-identifying • 7–4resulting • 12–10

calculation specifications • 8–10return (RT)

check • 1–12RT • 12–23

usage • 12–4, 12–8, 12–10setting off • 11–120setting on • 11–121specifying

*IN,xx • 7–11, 7–12

Indicatorsspecifying (cont’d)

*INxx • 7–11, 7–12types • 12–3U1 - U8 • 12–1, 12–30

usage • 12–10usage • 12–3using as fields • 12–31

INFDS data structure • 16–8continuation lines • 4–23declaring • 4–23

Information data structure • 16–8INFSR subroutine

*CANCL • 1–13continuation lines • 4–23declaring • 4–23*GETIN • 1–11

*IN indicators • 12–31example • 12–31function • 12–31specifying array elements • 12–31specifying arrays • 12–31

Inputforcing file selection

FORCE • 11–59indexed

Setting a starting point • 11–118KEYBORD device • 11–68, 11–115reading by key • 11–24sequential based on a key • 11–107sequential read • 11–104

reversed • 11–109Input/output operation codes • 11–6Input specification modifiers

Auto Report Utility • 21–5Input specifications • 7–1

AND • 7–2, 7–3, 7–4record-identification conditions • 7–8

comments • 7–18control break indicators • 7–12data format • 7–9data structure • 7–1decimal positions • 7–10field indicators • 7–17field name • 7–11field positions

end • 7–10start • 7–10

field-record-relation indicators • 7–15field start and end positions • 7–9file name • 7–2

Index–13

Index

Input specifications (cont’d)

general description • 1–3identifying record types • 7–4look-ahead fields

defining • 7–5matching fields • 7–14not • 7–7option • 7–4OR • 7–2, 7–3, 7–4

example • 13–31record-identification conditions • 7–8

record-identification condition position • 7–6record-identification conditions • 7–6

character • 7–7comparison character • 7–8digit • 7–7zone • 7–7

record-identifying indicators • 7–4sequence • 7–2sequence number • 7–3specifying

alphabetic sequence code • 7–2data formats • 7–9data structure names • 7–2data structure statement • 16–1data structure subfield • 16–2file names • 7–2look-ahead fields • 7–5numeric sequence code • 7–2record-identification conditions • 7–6sequence code • 7–2

Inverted print • 3–4*INxx indicators • 12–31

example • 12–32function • 12–32representing indicators • 12–32

KKey

field lengthlength • 4–15

KEYBORD • B–14 to B–19calculation specifications • B–15

KEYnn operation • B–16SETnn operation • B–18

displaying KEYBORD device filesbypassing a KEYnn operation • B–17

file description specification • B–14limitations of • B–14

KEYBORD deviceKEYnn • 11–68, 11–115

KEYBORD filesprocessing modes • 4–14

Key fieldsnon-contiguous

EXTK • 13–15packed-decimal

length • 4–15specifying

non-contiguous • 4–18Key length

addrout files • 4–15indexed files • 4–15limits files • 4–15

Key location • 4–17rules for specifying • 4–18

KEYnn operation coderules • 11–68

KEY operation codegeneral information • 11–6

Keysnon-contiguous

specifying • 4–18KILL

halt response • 1–11

LL0 indicator • 12–27

output specifications • 9–10Label names • 10–9Labels



Language elements • 10–1Last cycle • 1–12

final steps • 1–14Last Cycle • 1–20Last record

indicator check • 1–12processing • 1–13

Last record indicatorsetting

detail time • 11–6total time • 11–6

Index–14

Index

Last Record indicators • 12–26example • 12–26function • 12–26totaling data • 12–26

LDA (local data area) • 16–6Length of entry

arraysalternate entry • 5–9primary entry • 5–6

extension specificationsalternate entry • 5–9primary entry • 5–6

tablesalternate entry • 5–9primary entry • 5–6

Level breaksee control break

Level break indicatorssetting • 11–6

Level Zero indicator • 12–27*LIKE DEFN

see DEFNLimits file • 13–8Limits files


Limits processingSETLL operation • 13–11

Limits records • 13–8Line Counter specification • 6–1

comments • 6–3file name • 6–1form length • 6–2form length flag • 6–2naming the output file • 6–1overflow line flag • 6–3overflow line number • 6–2

Line numbers • 2–2checking • 2–2

Line relationshipsinput specifications

AND • 7–8, 12–6OR • 7–8, 12–6

Line specificationgeneral description • 1–3

Literalsfactor 1


calculation specifications • 8–6

Local data areaaccessing

SUBR21 • 16–7Local data area (LDA) • 16–6Logic cycle • 1–1

basic record processing • 1–7detail • 1–7, 1–10

halt indicators • 1–11detail time • 1–7, 1–18first cycle • 1–10first cycle processing • 1–15general • 1–7last cycle processing • 1–20look-ahead • 1–14normal • 1–15normal cycle • 1–11steps • 1–10steps of

a normal cycle • 1–15the first cycle • 1–15the last cycle • 1–20

total time • 1–7, 1–16LOKUP operation code

arrays • 15–29example • 15–30indexed • 11–74non-indexed • 11–74specifying array elements • 11–74

referencing entries • 15–10related tables • 11–74rules • 11–71searching

arrays • 11–74related tables • 11–74tables • 11–73, 15–10

sequencing arrays • 11–122table elements • 11–73

Longword binary data typeexample • 10–4

Look-ahead fields • 7–5defining • 7–5function • 7–5

Look-ahead logic cycle • 1–14LR

example • 12–5LR indicators • 12–26

M

Index–15

Index

Matching fieldschecking record sequence • 4–7, 13–29

example • 13–29for more than one record type • 13–29

end-of-file • 4–6example • 13–30input specifications • 7–14multifile processing • 13–29, 13–32

example • 13–32, 13–35record selection • 13–32rules for specifying • 13–32

sequence checking • 7–14using as field-record-relation indicators • 13–30

example • 13–31Matching Fields • 1–13

FORCE bypass • 1–12Matching record indicator • 12–28

function • 12–28multifile processing • 12–28

Matching recordsexample • 12–29

MHHZO operation codegeneral information • 11–6rules • 11–79

MHLZO operation codegeneral information • 11–6rules • 11–80

Migration RPG programslogic cycle • 1–1

MLHZO operation codegeneral information • 11–6rules • 11–81

MLLZO operation codegeneral information • 11–6rules • 11–82

MOVEArules • 11–5

MOVEA operation codearrays • 15–31example • 15–32general information • 11–5rules • 11–85

MOVEL operation code • 11–6general information • 11–5rules • 11–89

MOVE operation codeexample • 10–3general information • 11–5rules • 11–83

MOVE operation codesMOVE • 11–5

MOVE operation codes (cont’d)

MOVEA • 11–5MOVEL • 11–5, 11–6

Move operationsrules • 11–5

Move zoned operation codes • 11–6rules • 11–6

Moving datarules • 11–5

MR indicator • 12–28example • 12–29

Multifile processing • 13–29checking record sequence • 13–29

example • 13–29for more than one record types • 13–29

matching fields • 13–29using

matching fields • 13–29matching record indicator • 12–28matching-record indicators • 13–29MR indicators • 13–29

multiple keys • 13–38Multiplication • 11–92MULT operation code


MVR operation codegeneral information • 11–1rules • 11–94

NNames

arrays • 10–9specifying


EXCPT • 10–9fields • 10–9files • 10–9labels • 10–9subroutines • 10–9tables • 10–9

specifyingalternate entry • 5–8primary entry • 5–4

Naming conventions • 10–9Non-contiguous keys

accessingEXTK • 13–15

Index–16

Index

Non-contiguous keys (cont’d)

specifying • 4–18Normal cycle

reading records • 1–12

Notsee record-identification conditions

Notationsedit codes • 3–4numeric fields • 3–4UDATE • 3–4

Number of entries per record • 5–4arrays • 5–4tables • 5–4

Number of entries per table or array • 5–5Numeric

specifyingtables and arrays


Numeric databinary • 9–21overpunch • 9–21, 10–7packed-decimal • 9–21specifying

format • 9–21trailing numeric • 9–21zoned-decimal • 9–21

Numeric data typetrailing numeric • 10–7zoned-decimal • 10–7

Numeric field editing • 14–4Numeric fields

comparing • 11–3editing

edit words • 9–24rounding

half-adjust • 8–9specifying

notation • 3–4Numeric literals



Numeric sequence codesequence option • 7–4

O

OLoverflow line flag • 6–3

OpenVMS Run-Time Library proceduresassigning names • 11–57, 19–4calling • 19–2passing parameters • 19–7

Operation codes • 11–1alphabetical listing • 11–8arithmetic • 11–1bit • 11–2branching • 11–3called program

CALL • 11–19, 19–2EXTRN • 11–57, 19–4


PARM • 11–98PLIST • 11–102RETRN • 11–111

compare • 11–3external call • 11–4input/output • 11–6

EXCPT • 9–16move • 11–5

MOVEL • 11–6rules • 11–5

move zoned • 11–6rules • 11–6

moving arrays • 11–5Set • 11–6

rules • 11–6specifying

calculation specifications • 8–5structured • 11–7

ANDxx • 11–11CASxx • 11–21comparison rules • 11–3DO • 11–36DOUxx • 11–39DOWxx • 11–42ELSE • 11–45END • 11–47IFxx • 11–65ORxx • 11–96

subprogramCALL • 11–19, 19–2EXTRN • 11–57, 19–4

Index–17

Index

Operation codessubprogram

EXTRN (cont’d)


PARM • 11–98PLIST • 11–102RETRN • 11–111

subroutine • 11–4Option

input specifications • 7–4OR

Input specificationexample • 13–31

input specifications • 7–2, 7–3, 7–4, 7–8, 12–6output specifications • 9–2record identification

example • 12–7ORxx operation code


Outputdetail • 1–11

example • 12–5exception output • 11–51EXCPT • 11–51first page (1P) • 1–11from calculation specifications • 11–51heading • 1–11

example • 12–5overflow • 1–11total time

example • 12–5Output files

controlling overflow • 4–17specifying

file name • 6–1using overflow indicators • 4–17

Output operationsno deferred write • 4–26

Output specifications • 9–1AND • 9–2Blank after • 9–19comments • 9–28constants • 9–22data format • 9–21edit code modifiers • 9–23edit codes • 9–17

Output specifications (cont’d)

edit words • 9–24end position • 9–20EXCPT name • 9–12, 9–16fetch overflow • 9–5field name • 9–12

special words*PLACE • 9–14UDATE • 9–15$UDATE • 9–15UDAY • 9–15$UDAY • 9–15$UMNTH • 9–15UMONTH • 9–15UYEAR • 9–15$UYEAR • 9–15

file name • 9–2function • 9–1general description • 1–3indicators • 9–9OR • 9–2record type • 9–3skip after • 9–8skip before • 9–7space after • 9–6space before • 9–6special words • 9–12, 9–13

*PLACE • 9–14UDATE • 9–15$UDATE • 9–15UDAY • 9–15$UDAY • 9–15$UMNTH • 9–15UMONTH • 9–15UYEAR • 9–15$UYEAR • 9–15

specifyingADD option • 9–4DEL option • 9–4

WORKSTN screen format names • 9–22Overflow

indicator initialization • 1–12Overflow indicators • 4–17, 12–17, 14–7

causing page breaks • 12–17example • 12–5, 12–18, 14–9function • 12–17rules for specifying • 4–17, 14–7specifying • 12–17

fetch overflow • 9–5Overflow line flag

Line counter specification • 6–3OL • 6–3

Index–18

Index

Overflow line numberline counter specification • 6–2

Overpunch • 10–7Overpunch data

example • 10–8

P1P

example • 12–5Packed-decimal data

defining fieldsexample • 10–6

determining length • 10–6Packed-decimal data type



Packed-decimal fieldskey

length • 4–15PAGE

example • 12–5, 13–19special words

output specifications • 9–13PAGE1

special wordsoutput specifications • 9–13

PAGE2special words



PAGE4special words



PAGE6special words



Parameter passing • 1–10Parameters

list • 19–11passing

access types • 11–100, 19–8mechanisms • 11–100, 19–8

by reference • 19–7RPG

list • 11–102PARM


processing in first cycle • 1–10PARM operation code


1P indicator • 12–24, 14–6conditioning output data • 12–24example • 12–24function • 12–24

*PLACEspecial words

output specifications • 9–14PLIST

*ENTRYusage • 1–10


PLIST operation codegeneral information • 11–4rules • 11–102

Porting RPG applicationsdevice specifications • 4–18disk files

continuation lines • 4–21IBM RPG II compatibility

record address fileskey length • 4–8, 4–15

SPECIAL device filescontinuation lines


SUBR01 support • 4–21workstation device files

continuation linesentries • 4–22options • 4–22

Pre-execution-time arrays • 15–18creating • 15–18, 15–23

rules for specifying • 15–18outputting • 15–33

Index–19

Index

Pre-execution-time arrays (cont’d)

searchingexample • 15–30

updating • 15–32writing • 15–33

Pre-execution-time tables • 15–3creating

example • 15–9outputting • 15–15rules for defining • 15–9

Primary file • 4–4Primary files




Printer devicespecifying • 4–18

Printer filesprocessing modes • 4–13

PRINTER filesspecifying

overflow line number • 6–2page size • 6–2

PRINTER file usageexample • 13–13

Printer output files • 14–1conditioning output • 14–6controlling overflow • 4–17creating • 14–1deleting form-feed characters • 14–1editing

numeric data • 9–24editing output • 9–17file description specification • 14–1first page indicators • 12–24formatting

output • 14–4output data • 9–20, 9–23skip after • 9–8skip before • 9–7space after • 9–6space before • 9–6

generating report titles • 9–22Last Record indicators • 12–26line counter specification • 14–2NOFEED qualifier • 14–1numeric field editing • 14–4output specification • 14–2overflow indicators

Printer output filesoverflow indicators (cont’d)

using • 12–171P indicator • 12–24printing

IMPORTANT INFORMATION • 14–1required specifications • 14–1Skip entries • 14–4

example • 14–6Space entries • 14–4


a negative sign • 9–27asterisks • 9–25blank spaces • 9–25constant data • 9–22CR • 9–27fetch overflow • 9–5page breaks • 14–7skip after • 9–8skip before • 9–7space after • 9–6space before • 9–6zero suppression • 9–25

usingfetch overflow

example • 14–12first-page indicators • 14–6indicators to condition output • 9–9overflow indicators • 4–17, 14–7

example • 14–91P indicator • 14–6special words • 14–4

PRINT filesspecifying

overflow line number • 6–2page size • 6–2

Processingfiles

specifyingan addrout file • 4–8random access • 4–8sequential access • 4–8sequential within limits access • 4–8

multifiles • 13–29processing files

multiple keys • 13–38example • 13–38

Processing mode • 4–8loading a direct file • 4–8record address type

valid combinations • 4–16

Index–20

Index

Processing mode (cont’d)

selectingindexed • 4–12KEYBORD file • 4–14printer file • 4–13record address file • 4–13relative • 4–11sequential • 4–9SPECIAL file • 4–14workstation file • 4–13

specifyingaccess

random • 4–8sequential • 4–8sequential within limits • 4–8

an addrout file • 4–8record address type • 4–15

Programinitialization • 1–10

Programslogic cycle • 1–1

Program specifications • 1–1

RRandom by addrout file access • 13–16


Random by key file access • 13–14example • 13–15rules for specifying • 13–14

Random file access • 13–12using

an addrout file • 13–16keys • 13–14relative record numbers • 13–12


READE operation codegeneral information • 11–6rules • 11–107

READ operation codegeneral information • 11–6rules • 11–104

READP operation codegeneral information • 11–6rules • 11–109

Record-address file • 4–5Record address files

file designation • 4–6

Record address files (cont’d)

key length • 4–15processing modes • 4–13record length • 4–8

Record-address filesspecifying

from-file name • 5–2to-file name • 5–3

Record address type • 4–15processing mode

valid combinations • 4–16Record formats

fixed • 13–2variable • 13–2

Record identificationCHAIN operation • 11–25example • 12–7no record • 1–13

Record-identification codesinput specifications • 7–6

Record identification conditionsAND • 12–6example • 12–5OR • 12–6

Record-identification conditionsAND • 7–8identifying record types • 7–6OR • 7–8specifying

character • 7–7comparison character • 7–8digit • 7–7not • 7–7position • 7–6zone • 7–7

Record identifying indicatorsexample • 12–5function • 12–4identifying record types • 12–4

Record-identifying indicatorsconditioning input data • 7–4input specifications • 7–4

Record indentification • 1–13Record length • 4–8Record-limits files

example • 13–7function • 13–9rules for specifying • 13–9

Record lockingtrapping

example • 11–26

Index–21

Index

Recordsadding • 13–24

output specifications • 9–4array input • 15–18basic processing cycle • 1–7deleting • 13–28

example • 13–28output specifications • 9–4

identifying types • 7–4processing totals • 1–16record identifying indicators • 12–4specifying

detailoutput specifications • 9–3

exceptionoutput specifications • 9–3

format • 4–7heading

output specifications • 9–3length

fixed • 4–7variable • 4–7

record-identification conditions • 7–6total

output specifications • 9–3types

defining the ordering sequence • 7–2output specifications • 9–3

updating • 13–26example • 13–27

using record identifying indicators • 12–4Record types

defining the ordering sequence • 7–2detail

output specifications • 9–3exception

output specifications • 9–3heading

output specifications • 9–3identifying • 7–4output specifications • 9–3specifying

record-identification conditions • 7–6total

output specifications • 9–3using record identifying indicators • 12–4

Related arrays • 15–19alternate format • 15–21creating • 15–19, 15–21

Related tablescreating • 15–7

Related tablescreating (cont’d)

input records • 15–5LOKUP operation code

rules • 11–74Relative file organization • 13–3

example • 13–3Relative files

adding records • 13–25rules for specifying • 13–25


processing modes • 4–11updating records

rules for specifying • 13–27Result field

calculation specifications • 8–7restrictions

calculation specifications • 8–8rounding data

half-adjust • 8–9specifying *IN,xx indicator array elements • 8–7specifying *INxx indicators • 8–7

Resulting indicators • 12–10calculation specifications • 8–10example • 12–11function • 12–10

RETRNoperation code • 19–12

rules • 19–12RETRN operation code

rules • 11–111Return indicator

RT • 12–23Return status

halt indicators • 1–14RLABL operation code


RPGCON • B–7RPG II programs

arrays • 15–15RPGLDA • 16–6RPG program

example • 1–19RPG programs

documenting • 2–3RPG subprograms

halt indicatorsprocessing • 12–22

RT indicator • 12–23initialization • 1–10

Index–22

Index

SScreen format names

output specifications • 9–22Screen formats

continuation lines • 4–23Secondary file • 4–4Secondary files




Sequence checkingusing matching fields • 7–14

Sequence code • 4–7Sequence codes • 7–2

assigning a numeric code • 7–3extension specifications


sequence number • 7–3specifying

alphabetic • 7–2numeric • 7–2, 7–3sequence option • 7–4

Sequence Numberinput specification • 7–3

Sequential by key file accessexample • 13–7rules for specifying • 13–6

Sequential file access • 13–5, 13–6example • 13–6rules for specifying • 13–6

Sequential file organization • 13–3example • 13–3

Sequential filesadding records • 13–24



processing modes • 4–9Sequential input

example • 13–13Sequential within limits file access

example • 13–8record-limits file • 13–7

SETLL operationlimits processing • 13–11

SETLL operation codegeneral information • 11–6rules • 11–118

SETnn operation codegeneral information • 11–6rules • 11–115

SETOF operation codegeneral information • 11–6rules • 11–120

SETON operation codegeneral information • 11–6rules • 11–121

Set operation codes • 11–6rules • 11–6

Skip afteroutput specifications • 9–8

Skip beforeoutput specifications • 9–7

SORTA operation coderules • 11–122

/SPACEcompiler directive • 2–4

Space afteroutput specification • 9–6

Space beforeoutput specification • 9–6

SPECIAL Device FileCoding the SPECIAL File Subroutine • 18–4File Description Continuation Specifications • 18–2File Description Specifications • 18–1Introduction • 18–1Migration RPG Program Logic • 18–3Programming Features Supported • 18–3Sample Program • 18–5SUBR01 Support • 18–1

SPECIAL device filescontinuation lines


SPECIAL device routinename • 4–20

SPECIAL device routinesSUBR01 • 4–21

SPECIAL filesprocessing modes • 4–14

Special words • 14–4factor 1


Index–23

Index

Special wordsfactor 2 (cont’d)

calculation specifications • 8–6, 8–7output specification • 9–12, 9–13PAGE

output specifications • 9–13PAGE, PAGE1 - PAGE7

input specifications • 7–12PAGE1







output specifications • 9–13*PLACE

output specifications • 9–14UDATE

output specifications • 9–15$UDATE

output specifications • 9–15UDAY

output specifications • 9–15$UDAY

output specifications • 9–15$UMNTH

output specifications • 9–15UMONTH

output specifications • 9–15UYEAR

output specifications • 9–15$UYEAR

output specifications • 9–15Specification format

comments • 2–3line number • 2–2notational conventions • 2–1

Specificationscalculation • 8–1column numbers • 2–1compile qualifier • 21–1control • 3–1Extension • 5–1file description • 4–1

Specifications (cont’d)

input • 7–1Line Counter • 6–1Output • 9–1program • 1–1types • 2–2

Split-control fieldsexample • 12–16

SQRT operation codegeneral information • 11–1rules • 11–124

Square root • 11–124Structured operation codes • 11–7

ANDxx • 11–11CASxx • 11–21comparison operations • 11–8, 11–12, 11–21,

11–40, 11–43, 11–66, 11–97comparison rules • 11–3DO • 11–36DOUxx • 11–39DOWxx • 11–42ELSE • 11–45END • 11–47IFxx • 11–65ORxx • 11–96structured constructs • 11–8

Subfieldsdata structures • 16–4

defining • 7–11, 7–12SUB operation code


Subprogramreturn indicator • 1–12returning parameters • 1–12return using RT • 1–12RPG

initialization steps • 1–10passing parameters • 1–10

Subprogram naming convention • 19–4Subprogram operation codes

CALL • 11–19, 19–2EXTRN • 11–57, 19–4


PARM • 11–98PLIST • 11–102RETRN • 11–111

Index–24

Index

Subprogramscalling • 19–2

RPGCALL • 11–19

FREE • 11–61, 19–6parameter list • 19–11PARM • 19–7passing parameters • 19–7PLIST • 19–11RETRN • 19–12RPG

callingCALL • 11–19

halt indicatorsprocessing • 12–22

parameter list • 11–102PARM • 11–98passing parameters • 11–98PLIST • 11–102RETRN • 11–111startup • 1–10

SUBR01calling • 11–54

parameter passing • 11–113file description specification • 4–21SPECIAL device option • 4–21


parameter passing • 11–113example • 16–7local data area subroutine • 16–7


parameter passing • 11–113example • 11–55, 11–114

Subroutinesexternal

callingCALL • 11–19EXIT • 11–54RLABL • 11–113

identification • 11–13internal

beginBEGSR • 11–13

callingEXSR • 11–56

conditional calling • 11–21termination

ENDSR • 11–49names • 10–9

Subroutines (cont’d)

operation codes • 11–4Subtraction • 11–125Symbolic device • 4–20System services

calling • 19–2passing parameters • 19–7

TTable

elementsinitialization • 11–73LOKUP operation code • 11–73

sequencing • 11–72Table name


Tables • 15–1compile-time • 15–2

rules for defining • 15–7compile-timed

delimiter • 15–3creating

input records • 15–3definition • 15–1entries • 15–3input records • 15–3


loading timeselecting • 15–2

LOKUP operation code • 11–73, 15–10names • 10–9operations

LOKUP • 11–71permanent update • 15–14pre-execution-time • 15–3

rules for defining • 15–9referencing entries • 15–10related • 15–1, 15–5, 15–16

creating • 15–7searching • 11–73, 15–10

rules for specifying • 15–10set up and usage example • 11–76single • 15–1, 15–16

creating • 15–6compile-time • 15–7pre-execution-time • 15–9

specifying • 4–4

Index–25

Index

Tablesspecifying (cont’d)

data formatalternate entry • 5–9primary entry • 5–6


from-file name • 5–2length of entry


namesalternate entry • 5–8primary entry • 5–4

number of entries • 5–5number of entries per record • 5–4sequence


to-file name • 5–3temporary update • 15–13updating • 15–13writing • 15–15

TAG operation codegeneral information • 11–3rules • 11–127

Terminal devicespecifying • 4–18

TESTB operation codegeneral information • 11–2rules • 11–128

TESTZ operation codegeneral information • 11–3rules • 11–130

TIME operation codedate format • 3–3rules • 11–132

$TIME operation coderules • 11–134

/TITLEcompiler directive • 2–4

To-file nameoutputting

arrays • 5–3tables • 5–3

record-address files • 5–3writing

arrays • 5–3tables • 5–3

Total records

Total records (cont’d)

output specifications • 9–3Total time • 1–7, 1–16

calculations • 1–13output • 1–13

Total time processingexample • 1–17setting LR • 11–6

Total-time recordsoutput specifications • 9–3

Trailing numeric data typesexample

overpunch • 10–8zoned-decimal • 10–8

overpunch • 10–7representation of digits • 10–7

UUDATE • 9–12, 9–13, 9–15, 14–3, 14–4

example • 1–15, 1–19, 12–5, 13–19, 14–9, 14–12,15–17

first cycle • 1–10format • 3–3special words

output specifications • 9–15$UDATE • 3–4, 9–15

first cycle • 1–10special words

output specifications • 9–15UDATE special word

specifying notation • 3–4UDAY • 9–12, 9–13, 9–15, 14–3, 14–4


output specifications • 9–15$UDAY • 9–15


output specifications • 9–15$UMNTH • 9–15


UMONTH • 9–12, 9–13, 9–15, 14–3, 14–4first cycle • 1–10special words

output specifications • 9–15$UMONTH

first cycle • 1–10

Index–26

Index

Unordered output • 4–24Updating

files • 13–26randomly by key • 13–28sequentially • 13–28

records • 13–26example • 13–27

User defined collating sequencespecifying • 17–1

User-defined names • 10–9rules • 10–9

U specificationspecifying Auto Report compile qualifiers • 21–1

UYEAR • 9–12, 9–13, 9–15, 14–3, 14–4first cycle • 1–10special words

output specifications • 9–15$UYEAR • 9–15


output specifications • 9–15

WWord binary data type

example • 10–4Workstation device

return codesINFSR data structure • 4–23

Workstation device filescontinuation lines


Workstation fileINFDS • 16–8information data structure • 16–8returning exception information • 16–8

Workstation filesprocessing modes • 4–13

WORKSTN screen format namesoutput specifications • 9–22

XXFOOT operation code

arrays • 15–28example • 15–28general information • 11–1

XFOOT operation code (cont’d)

rules • 11–136

YY2K • 1–11, 3–4, 9–15, 11–134Year 2000 compliance • 1–11, 3–4, 9–15, 11–134

ZZ-ADD operation code


Zero suppression • 9–25Zoned-decimal data • 3–6

example • 10–8overpunch • 10–8

output • 3–6representation of digits • 10–7

Zone-decimal dataoverpunch • 10–7

Z-SUB operation codegeneral information • 11–1rules • 11–138

Index–27