Digital PDFs

AA-R431B-TE

November 1985

496 pages

Original

22MB

Document:	Programming in VAX RPG Il
Order Number:	AA-R431B-TE
Revision:	000
Pages:	496
Original Filename:

OCR Text

Programming in
VAX RPG II
Order Number: AA-R431 8-TE

November 1985
This manual describes language elements, programming constructs,
and features of the V AX RPG II language.

Revision/Update Information:

This revised document supersedes
Programming in VAX RPG /I
(Order No. AA R431 A-TEl

Operating System and Version:

VAX/VMS V4.2 or later
MicroVMS V4.2 or later

Software Version:

V AX RPG II V2.0

digital equipment corporation
maynard, massachusetts

First Printing, February 1984
Revised, November 1985
The information in this document is subject to change without notice and
should not be construed as a commitment by Digital Equipment Corporation.
Digital Equipment Corporation assumes no responsibility for any errors that
may appear in this document.
The software described in this document is furnished under a license and may
be used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated
companies.
Copyright © 1984, 1985 by Digital Equipment Corporation
All Rights Reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DEC/MMS
DECnet
DECsystem-1O
DECSYSTEM-20
DECUS
DECwriter

DIBOL
EduSystem
lAS
MASSBUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXc1uster
VMS
VT

~D~DD5lD
ZK-2787

HOW TO ORDER ADDITIONAL DOCUMENTATION
DIRECT MAIL ORDERS
USA & PUERTO RICO·

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua. New Hampshire
03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata. Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital's local subsidiary
or approved distributor

In Continental USA and Puerto Rico call 800-258-1710.
In New Hampshire. Alaska. and Hawaii call 603-884-6660.
In Canada call 800-267-6215 .
... Any prepaid order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SOC). Digital Equipment Corporation.
Westminster. Massachusetts 01473.

~..

Contents
Preface .............................................................. .................. xv
Part I
Chapter 1 The VAX RPG II Logic Cycle
1.1
1.2
1.3
1.4

The RPG II General Logic Cycle .................................................... 1-2
The First Cycle .................................................................... 1-2
The Last Cycle .................................................................... 1-3
A Normal Cycle ................................................................... 1-3
1.4.1 Total Time ................................................................. 1-4
1.4.2 Detail Time ................................................................ 1-5
1.5 RPG II Detail Program Logic Cycle ................................................ 1-16

Chapter 2 Developing Programs
2.1

Compiling Programs ............................................................... 2-1
2.1.1 Default Compiler Options .................................................... 2-2
2.1.2 RPG II Compiler Qualifiers .................................................. 2-3
2.1.2.1 CHECK ............................................................ 2-4
2.1.2.2 CROSS_REFERENCE .............................................. 2-5
2.1.2.3 DEBUG ............................................................ 2-6
2.1.2.4 LIST .............................................................. 2-6
2.1.2.5 MACHINE_CODE .................................................. 2-7
2.1.2.6 OBJECT ........................................................... 2-7
2.1.2.7 SEQUENCE_CHECK .............................................. 2-8
2.1.2.8 WARNINGS ........................................................ 2-8
2.2 Linking and Running Programs .................................................... 2-8
2.3 Interpreting RPG II Compiler Error Messages ........................................ 2-9

Chapter 3 Using the RPG II Editor
3.1

3.2
3.3
3.4
3.5

RPG II Editor Qualifiers ........................................................... 3-1
3.1.1 COMMAND ................................................................ 3-2
3.1.2 CREATE ................................................................... 3-3
3.1.3 JOURNAL ................................................................. 3-3
3.1.4 OUTPUT .................................................................. 3-3
3.1.5 READ_ONLy .............................................................. 3-3
3.1.6 RECOVER ................................................................. 3-4
3.1.7 START_POSITION ......................................................... 3-4
The RPG II Editor Screen .......................................................... 3-5
The RPG II Editor Cursor .......................................................... 3-8
The RPG II Editor Buffers .......................................................... 3-9
Keys and Functions ............................................................... 3-9

3.5.1 The GOLD Function ....................................................... 3-12
3.5.2 The HELP-KEYPAD Function .............................................. 3-13
3.5.3 The HELP_SPECIFICATIONS Function ..................................... 3-14
3.5.4 The FIND.-NEXT Function ......... '........................................ 3-16
3.5.5 The FIND Function ........................................................ 3-17
3.5.6 The DELETE_LINE Function .............................................. 3-17
3.5.7 The UNDELETE--LINE Function ........................................... 3-17
3.5.8 The PAGE Function ........................................................ 3-18
3.5.9 The COMMAND Function .................................................. 3-18
3.5.10 The SECTION Function ................................................... 3-19
3.5.11 The DISPLAY Function ................................................... 3-19
3.5.12 The REVIEW-ERROR Function ........................................... 3-19
3.5.13 The MOVE_TO--RULER Function ......................................... 3-20
3.5.14 The DELETEJIELD Function ............................................ 3-20
3.5.15 The UNDELETE_FIELD Function ......................................... 3-20
3.5.16 The ADVANCE Function .................................................. 3-20
3.5.17 The BOTTOM Function ................................................... 3-21
3.5.18 The BACKUP Function ................................................... 3-21
3.5.19 The TOP Function ........................................................ 3-21
3.5.20 The CUT Function ........................................................ 3-21
3.5.21 The PASTE Function ...................................................... 3-21
3.5.22 The SHIFT--LEFT Function ............................................... 3-22
3.5.23 The SHIFT--RIGHT Function .............................................. 3-22
3.5.24 The FIELD Function ...................................................... 3-23
3.5.25 The END_OF--LINE Function ............................................. 3-24
3.5.26 The DELETE_TO-END_OF--LINE Function ............................... 3-25
3.5.27 The CHARACTER Function ............................................... 3-26
3.5.28 The COLUMN Function ................................................... 3-26
3.5.29 The ENTER Function ..................................................... 3-26
3.5.30 The LINE Function ....................................................... 3-27
3.5.31 The OPEN--LINE Function ................................................ 3-27
3.5.32 The SELECT Function .................................................... 3-27
3.5.33 The RESET Function ..................................................... 3-27
3.5.34 The UP Function ......................................................... 3-27
3.5.35 The DOWN Function ........ , ............................................. 3-28
3.5.36 The RIGHT Function ...................................................... 3-28
3.5.37 The LEFT Function ....................................................... 3-28
3.5.38 The FIELD_BACKWARD Function ........................................ 3-28
3.5.39 The DELETE_CHARACTER Function ..................................... 3-28
3.5.40 The NEW--LINE Function ................................................. 3-28
3.5.41 The FIELD_FORWARD Function .......................................... 3-29
3.5.42 The REFRESH_SCREEN Function ........................................ 3-29
3.5.43 The DELETE_TO-BEGINNING_OF--LINE Function ....................... 3-29
3.5.44 The EXIT Function ....................................................... 3-29
3.6 RPG II Editor Commands ......................................................... 3-29
3.6.1 The COMPILE Command ................................................... 3-30
3.6.2 The DEFINE KEY Command ............................................... 3-31
3.6.3 The EXIT Command ....................................................... 3-34
3.6.4 The HELP Command ....................................................... 3-35
3.6.5 The INCLUDE Command .................................................. 3-37
3.6.6 The QUIT Command ....................................................... 3-38
3.6.7 The RESEQUENCE Command .............................................. 3-39

3.7

3.8

3.6.8 The SET Command ........................................................ 3-40
3.6.8.1 The COMMAND Option ............................................ 3-40
3.6.8.2 The DEFAULT Option ............................................. 3-40
3.6.8.3 The HELP Option .................................................. 3-41
3.6.8.4 The RULER Option ................................................ 3-41
3.6.8.5 The SCROLL Option ............................................... 3-43
3.6.8.6 The SECTION Option .............................................. 3-44
3.6.8.7 The STARTCOLUMN Option ....................................... 3-44
3.6.8.8 The SYNTAX CHECK Option ....................................... 3-44
3.6.9 The SHOW Command ...................................................... 3-45
3.6.10 The SUBSTITUTE Command ........... " ................................. 3-46
Customizing the Editor ........................................................... 3-48
3.7.1 U sing Editor Commands .................................................... 3-48
3.7.2 Startup Command Files .................................................... 3-48
3.7.3 Modifying Screen Length ................................................... 3-50
Creating and Editing Programs .................................................... 3-50
3.8.1 Creating A New Program ................................................... 3-54
3.8.2 Editing An Existing Program ............................................... 3-66

Chapter 4 Using Indicators
4.1

4.2

4.3

User Defined Indicators ............................................................ 4-1
4.1.1 Record-Identifying Indicators ................................................ 4-1
4.1.2 Field Indicators ............................................................. 4-4
4.1.3 Resulting Indicators ........................................................ 4-6
4.1.4 Control-Level Indicators ..................................................... 4-8
4.1.5 Overflow Indicators ........................................................ 4-12
4.1.6 K Indicators. . . . .. . . . . .. .. . . .. . . .. . . . .. . . . . . . . .. .. . .. ..
. ............... 4-12
Internally Defined Indicators ...................................................... 4-14
4.2.1 First-Page Indicator ........................................................ 4-14
4.2.2 Last-Record Indicator ...................................................... 4-15
4.2.3 Matching-Record Indicator ................................................. 4-16
4.2.4 External Indicators ........................................................ 4-16
4.2.5 Halt Indicators ............................................................ 4-17
Using Indicators as Fields ......................................................... 4-19
4.3.1 *IN and *IN,n ............................................................. 4-19
4.3.2 *INxx ..................................................................... 4-19

Chapter 5 Using Files
5.1 File Names ....................................................................... 5-1
5.2 Record Formats ................................................................... 5-2
5.3 File Types ........................................................................ 5-2
5.4 File Organizations ................................................................ 5-2
5.4.1 Sequential Organization ..................................................... 5-2
5.4.2 Direct Organization ......................................................... 5-3
5.4.3 Indexed Organization ....................................................... 5-4
5.5 File Access Methods ............................................................... 5-5
5.5.1 Sequential Access ........................................................... 5-6
5.5.2 Sequential Access By Key ................................................... 5-7
v

5.5.3 Sequential Access Within Limits ............................................. 5-8
5.5.4 Random Access ............................................................ 5-11
5.5.4.1 .................................................................. 5-11
5.5.4.2 .................................................................. 5-13
5.5.4.3 .................................................................. 5-14
5.5.5 Sequential Access And/or Random Access By Key ............................. 5-18
5.6 Creating Files ................................................................... 5-20
5.6.1 Creating Sequential Files ................................................... 5-20
5.6.2 Creating Direct Files ....................................................... 5-20
5.6.3 Creating Indexed Files ..................................................... 5-21
5.7 Adding Records to Files .................. ; ........................................ 5-22
5.7.1 Adding Records To A Sequential File ........................................ 5-23
5.7.2 Adding Records To A Direct File ............................................. 5-24
5.7.3 Adding Records To An Indexed File .......................................... 5-25
5.8 Updating Records in Files ......................................................... 5-26
5.8.1 Updating A File Sequentially Or Randomly By Key ........................... 5-28
5.9 Deleting Records from Files ....................................................... 5-28
5.10 Processing Files with Matching Records ........................................... 5-29
5.10.1 Checking Record Sequence for One Record Type ............................ 5-29
5.10.2 Checking Record Sequence for More Than One Record Type .................. 5-29
5.10.3 Using Matching Fields with Field-Record-Relation Indicators ................ 5-31
5.10.4 Using Matching Fields To Process More Than One File ...................... 5-33
5.11 Processing Files with Multiple Keys .............................................. 5-41

Chapter 6 Using Printer Output Files
6.1

6.2

6.3

6.4
6.5
6.6

Editing Output .................................................................... 6--1
6.1.1 Using Edit Codes and Edit Code Modifiers ..................................... 6--1
6.1.2 Using Constants ............................................................ 6--2
Using Special Words ............................................................... 6--3
6.2.1 Printing the Date: UDATE, UDAY, UMONTH, UYEAR ........................ 6--3
6.2.2 Numbering Pages: PAGE and PAGEl Through PAGE7 ......................... 6--4
6.2.3 Saving Time by Repeating Data: *PLACE ..................................... 6--7
Conditioning Output Lines ......................................................... 6--8
6.3.1 Printing Lines Before Reading the First Record: First-Page Indicator ............ 6--8
6.3.2 Specifying Page Breaks: Overflow Indicator .................................. 6--10
Automatic Overflow .............................................................. 6--13
Defining the Page Size ............................................................ 6--14
Formatting Output ............................................................... 6--14

Chapter 7 Using Tables
7.1
7.2
7.3
7.4
7.5
7.6
7.7

Compile-Time Tables .............................................................. 7-2
Pre-Execution-Time Tables ......................................................... 7-2
Creating Table Input Records ....................................................... 7-3
DefiningTables ................................................................... 7-4
Searching Tables .................................................................. 7-7
Referencing Table Entries ......................................................... 7-10
Updating Tables ................................................................. 7-11

7.8

Outputting Tables ................................................................ 7-12

Chapter 8 Using Arrays
Types of Arrays ................................................................... 8-1
8.1.1 Compile-Time Arrays ....................................................... 8-2
8.1.2 Pre-Execution-Time Arrays .................................................. 8-4
8.1.3 Execution-Time Arrays ...................................................... 8-4
8.2 Creating Array Input Records ...................................................... 8-4
8.3 Defining Arrays ................................................................... 8-5
8.3.1 Defining a Compile-Time Array .............................................. 8-6
8.3.2 Defining a Pre-Execution-Time Array ......................................... 8-6
8.3.3 Defining an Execution-Time Array ........................................... 8-7
8.3.4 Defining Related Arrays in Alternating Format ................................ 8-8
8.4 Referencing Arrays ............................................................... 8-10
8.5 Searching Arrays ................................................................ 8-15
8.6 Moving Array Data ............................................................... 8-18
8.7 Updating Arrays ................................................................. 8-19
8.8 Outputting Arrays ............................................................... 8-20
8.1

Chapter 9 Calling System Routines from VAX RPG II
Introduction ...................................................................... 9-1
9.1.1 Run-Time Library Routines .................................................. 9-2
9.1.2 System Service Routines ..................................................... 9-2
9.2 Calling System Routines from VAX RPG II .......................................... 9-3
9.2.1 Determine the Type of Call (Procedure or Function) ............................ 9-4
9.2.2 Declare the Arguments ...................................................... 9-5
9.2.2.1 Parameter Passing Mechanisms ..................................... 9-10
9.2.2.2 Parameter Access Types (column 54) ................................. 9-12
9.2.2.3 Parameter Data Types (columns 55-57) .............................. 9-12
9.2.3 Declare the System Routine ................................................. 9-14
9.2.4 Include Symbol Definitions ................................................. 9-15
9.2.5 Call the Routine or Service ................................................. 9-15
9.2.5.1 Calling a System Routine in a Function Call ......................... 9-15
9.2.5.2 Calling a System Routine in a Procedure Call ........................ 9-19
9.2.6 Check the Condition Value .................................................. 9-20
9.2.7 Locate the Result ........................ " ................................ 9-23
9.2.7.1 Function Results ................ " ................................ 9-23
9.2.7.2 Procedure Results ................................................. 9-23
9.3 Examples of Calling Run-Time Library Routines .................................... 9-24
9.4 Examples of Calling System Services ............................................... 9-28
9.5 Examples of Calling Subprograms ................................................. 9-32
9.6 Screen Handling in VAX RPG II ................................................... 9-33
9.1

Chapter 10 Debugging VAX RPG II Programs
10.1
10.2
10.3

Debugging RPG II Programs ..................................................... 10-3
Debugger Commands and Keywords .............................................. 10-3
Preparing to Debug a Program ................................................... 10-4

vii

10.3.1 SET LANGUAGE and SHOW LANGUAGE Commands ..................... 10-4
10.4 Controlling Program Execution ................................................... 10-5
10.4.1 SET BREAK, SHOW BREAK, and CANCEL BREAK Commands ............ 10-6
10.4.2 SET TRACE, SHOW TRACE, and CANCEL TRACE Commands ............. 100'i
10.4.3 SET WATCH, SHOW WATCH, and CANCEL WATCH Commands ............ 10-9
10.4.4 SHOW CALLS Command ............................................... 10-10
10.4.5 GO and STEP Commands ............................................... 10-10
10.4.6 TYPE Command ....................................................... 10-11
10.4.7 EDIT Command ........................................................ 10-12
10.4.8 CTRL/Y Command ..................................................... 10-12
10.4.9 EXIT Command ................................................ , ....... 10-12
10.5 Examining and Modifying Locations ............................................. 10-13
10.5.1 EXAMINE Command ................................................... 10-13
10.5.2 DEPOSIT Command .................................................... 10-14
10.5.3 EVALUATE Command .................................................. 10-15

Chapter 11

Interpreting a Compiler Listing

Chapter 12 Optimizing Your Programs
Optimizing with Data Structures ................................................. 12-1
Optimizing with Adjacent Fields in Records ........................................ 12-2
Optimizing with Blank Factor 1 .................................................. 12-3
Optimizing File Performance ..................................................... 12-3

12.1
12.2
12.3
12.4

Figures
1-1 RPG II Logic Cycle .... ........................................................... . 1-6
1-2 Logic Cycle for the Matching-Fields Routine ........................................ 1-16
1-3 Logic Cycle for Chained and Demand Files ......................................... 1-18
1-4 Logic Cycle for Overflow Processing ............................................... 1-19
1-5 Logic Cycle for Look-Ahead Processing ............................................ 1-20
5-1 Sequential File Organization ...................................................... 5-3
5-2 Direct File Organization ........................................................... 5-3
5-3 Indexed File Organization ......................................................... 5-4
5-4 Index Key Value .................................................................. 5-4
5-5 Sequential Access Within Limits ................................................... 5-8
5-6 Random Access by ADDROUT File ................................................ 5-15
5-7 ADDROUTFile ................................................................. 5-15
5-8 Adding Records to a Sequential File ............................................... 5-23
5-9 Adding Records to a Direct File ................................................... 5-24
5-10 Using Matching Fields to Do Multifile Processing .................................. 5-35
7-1 Table Input Record ................................................................ 7-3
7-2 Related Tables .................................................................... 7-4
8--1 Array Input Record ............................................................... 8-4
8--2 Related Arrays ................................................................... 8--5

Tables
2-1
3-1
3-2

RPG II Command Qualifiers ....................................................... 2-4
RPG/EDIT Command Qualifiers .................................................... 3-2
RPG II Editor Define Key Defaults ................................................ 3-10

viii

3-3 RPG Keynames for Valid Definable Keys ........................................... 3-33
5-1 File Access Methods ............................................................... 5-5
5-2 Matching Field Lengths .......................................................... 5-31
5-3 Matching Field Values ........................................................... 5-34
5-4 Matching Field Values ........................................................... 5-39
5-5 Processing Records with Matching Fields .......................................... 5-40
8--1 Array Element Values ............................................................ 8--11
8--2 Array Elements in Calculations ................................................... 8--12
9-1 Run-Time Library Facilities ....................................................... 9-2
9-2 Groups of System Services ......................................................... 9-3
9-3 VMS Data Structures ............................................................. 9-7
9-4 Passing Mechanisms ............................................................. 9-19
10-1 Debugger Commands and Keywords .............................................. 10-4

Part II
Chapter 1 Language Elements
1.1 RPG II Character Set .............................................................. 1-1
1.2 RPG II Data Types ................................................................. 1-1
1.2.1 Character .................................................................. 1-2
1.2.2 Binary ..................................................................... 1-3
1.2.3 Packed Decimal ............................................................. 1-3
1.2.4 Overpunched Decimal ....................................................... 1-4
1.3 User-Defined Names ............................................................... 1-6

Chapter 2 Specifications
2.1 Notation Conventions ............................................................. 2-2
2.2 Common Fields ................................................................... 2-4
2.2.1 Line Number ............................................................... 2-4
2.2.2 Specification Type ........................................................... 2-5
2.2.3 Comments ................................................................. 2-5
2.3 Compiler Directing Statements ..................................................... 2-6
2.3.1 Copy ....................................................................... 2-7
2.3.2 Copy From CDD ............................................................ 2-7
2.3.3 Copy Modifiers ............................................................. 2-9
2.4 Control Specification ............................................................. 2-11
2.4.1 Control Specification Format ................................................ 2-12
2.4.2 Specification Type .......................................................... 2-12
2.4.3 Currency Symbol .......................................................... 2-12
2.4.4 Inverted Print ............................................................. 2-12
2.4.5 Alternate Collating Sequence ............................................... 2-13
2.4.6 Forms Position ............................................................ 2-15
2.4.7 Example .................................................................. 2-15
2.5 File Description Specification ...................................................... 2-16
2.5.1 File Description Specification Format ........................................ 2-16
2.5.2 Specification Type .......................................................... 2-16
2.5.3 File Name ................................................................. 2-17
2.5.4 File Type .................................................................. 2-17
2.5.5 File Designation ........................................................... 2-18
2.5.6 End-of-File ................................................................ 2-19
2.5.7 Sequence .................................................................. 2-20
2.5.8 File Format ............................................................... 2-21
2.5.9 Block Length .............................................................. 2-21
2.5.10 Record Length ............................................................ 2-22
2.5.11 Mode of Processing ........................................................ 2-23

. ix

2.5.12 Key Length .............................................................. 2-27
2.5.13 Record Address Type ...................................................... 2-28
2.5.14 File Organization or Additional 110 Area .................................... 2-28
2.5.15 Overflow Indicators ....................................................... 2-29
2.5.16 Key Location ............................................................. 2-29
2.5.17 Extension Code ........................................................... 2-29
2.5.18 Device Code .............................................................. 2-30
2.5.19 Symbolic Device .......................................................... 2-31
2.5.20 Tape Label ............................................................... 2-31
2.5.21 Core Index ............................................................... 2-31
2.5.22 File Addition and Unordered Output ....................................... 2-32
2.5.23 Expansion Factor ......................................................... 2-33
2.5.24 File Sharing .............................................................. 2-35
2.5.25 Tape Rewind ............................................................. 2-37
2.5.26 File Condition ............................................................ 2-37
2.5.27 Example ................................................................. 2-38
2.6 Extension Specification ........................................................... 2-38
2.6.1 Extension Specification Format ............................................. 2-39
2.6.2 Specification Type .......................................................... 2-40
2.6.3 From File Name ........................................................... 2-40
2.6.4 To File Name .............................................................. 2-40
2.6.5 Table or Array Name ....................................................... 2-41
2.6.6 Number of Entries in a Record .............................................. 2-42
2.6.7 Number of Entries in a Table or Array ....................................... 2-42
2.6.8 Length of Entry ............................................................ 2-43
2.6.9 Format ................................................................... 2-44
2.6.10 Decimal Positions ......................................................... 2-44
2.6.11 Sequence ................................................................. 2-45
2.6.12 Alternate Table or Array .................................................. 2-45
2.6.13 Comments ............................................................... 2-46
2.6.14 Example ................................................................. 2-46
2.7 Line Counter Specification ........................................................ 2-47
2.7.1 Line Counter Specification Format .......................................... 2-48
2.7.2 Specification Type .......................................................... 2-48
2.7.3 File Name ................................................................. 2-48
2.7.4 Form Length .............................................................. 2-49
2.7.5 FL ........................................................................ 2-49
2.7.6 Overflow Line Number ..................................................... 2-49
2.7.7 OL ....................................................................... 2-50
2.7.8 Example .................................................................. 2-50
2.8 Input Specification ............................................................... 2-50
2.8.1 Input Specification Format .................................................. 2-51
2.8.2 Specification Type .......................................................... 2-51
2.8.3 File Name ................................................................. 2-51
2.8.4 Data Structures ........................................................... 2-52
2.8.4.1 Data Structure Statement .......................................... 2-53
2.8.4.2 Data Structure Subfields ........................................... 2-53
2.8.4.3 Local Data Area ................................................... 2-55
2.8.5 Sequence .................................................................. 2-55
2.8.6 Number ................................................................... 2-56
2.8.7 Option .................................................................... 2-56

Record-Identifying Indicator ................................................ 2-56
Record Identification Codes ................................................. 2-58
2.8.9.1 Position ........................................................... 2-59
2.8.9.2 Not ............................................................... 2-59
2.8.9.3 CZD Portion ....................................................... 2-59
2.8.9.4 Character ......................................................... 2-60
2.8.10 AND/OR ................................................................. 2-61
2.8.11 Format .................................................................. 2-62
2.8.12 Field Locations From and To ............................................... 2-63
2.8.13 Decimal Positions ......................................................... 2-64
2.8.14 Field Name .............................................................. 2-64
2.8.15 Examples of Using Data Structures ......................................... 2-65
2.8.15.1 Defining One Area of Storage More Than One Way ................. 2-66
2.8.15.2 Defining Subfields Within a Field or Subfield ....................... 2-67
2.8.15.3 Reorganizing Fields in An Input Record ........................... 2-67
2.8.15.4 Selecting the Internal Numeric Data Type for Fields ................ 2-68
2.8.15.5 Examples of Using Local Data Area ............................... 2-69
2.8.16 Control-Level Indicator ................................................... 2-71
2.8.17 Matching Fields .......................................................... 2-73
2.8.18 Field-Record-Relation Indicator ............................................ 2-75
2.8.19 Field Indicators ........................................................... 2-78
2.9 Calculation Specification .......................................................... 2-79
2.9.1 Calculation Specification Format ............................................ 2-79
2.9.2 Specification Type .......................................................... 2-79
2.9.3 Control Level .............................................................. 2-80
2.9.4 Indicators ................................................................. 2-82
2.9.5 Factors 1 and 2 ............................................................ 2-84
2.9.6 Operation Code ............................................................ 2-86
2.9.7 Result Field ............................................................... 2-86
2.9.8 Field Length .............................................................. 2-87
2.9.9 Decimal Positions .......................................................... 2-87
2.9.10 Half Adjust .............................................................. 2-88
2.9.11 Resulting Indicators ...................................................... 2-88
2.9.12 Comments ............................................................... 2-90
2.10 Output Specification ............................................................. 2-90
2.10.1 Output Specification Format .............................................. 2-90
2.10.2 Specification Type ....................................................... 2-90
2.10.3 File Name .............................................................. 2-91
2.10.4 AND and OR Lines ...................................................... 2-91
2.10.5 Record Type ............................................................. 2-93
2.10.6 ADD and DEL Options ................................................... 2-95
2.10.7 Fetch Overflow .......................................................... 2-96
2.10.8 Space Before and Space After ............................................. 2-97
2.10.9 Skip Before and Skip After ............................................... 2-98
2.10.10 Example ............................................................... 2-99
2.10.11 Indicators ............................................................. 2-100
2.10.12 Field Name ........................................................... 2-102
2.10.13 EXCPT Name ......................................................... 2-103
2.10.14 Edit Codes ............................................................ 2-104
2.10.15 Blank After ........................................................... 2-106
2.10.16 End Position .......................................................... 2-107
2.8.8
2.8.9

2.10.17 Format ............................................................... 2-109
2.10.18 Constant or Edit Word ................................................. 2-109
2.10.18.1 Edit Code Modifiers ......................................... 2-110
2.10.18.2 Constants .................................................. 2-111
2.10.18.3 Edit Words ..................... , .......... " ...... , ........ 2-112

Chapter 3 Operation Codes
3.1

3.2

3.3

3.4

3.5

3.6
3.7

3.8

xii

Arithmetic Operation Codes ........................................................ 3-1
3.1.1 ADD ....................................................................... 3-2
3.1.2 Z-ADD .................................................................... 3-2
3.1.3 SUB ....................................................................... 3-3
3.1.4 Z-SUB ..................................................................... 3-3
3.1.5 MULT ..................................................................... 3-3
3.1.6 DIV ....................................................................... 3-3
3.1.7 MVR ...................................................................... 3-3
3.1.8 SQRT ...................................................................... 3-4
3.1.9 XFOOT .................................................................... 3-4
3.1.10 Example .................................................................. 3-4
Move Operation Codes ............................................................. 3-5
3.2.1 MOVE ..................................................................... 3-5
3.2.2 MOVEA ................................................................... 3-6
3.2.3 MOVEL .................................................................... 3-6
3.2.4 Example ................................................................... 3-7
Set Operation Codes ............................................................... 3-9
3.3.1 SETON .................................................................... 3-9
3.3.2 SETOF .................................................................... 3-9
Subroutine Operation Codes ....................................................... 3-10
3.4.1 BEGSR ................................................................... 3-10
3.4.2 ENDSR ................................................................... 3-10
3.4.3 EXSR ..................................................................... 3-10
3.4.4 Example .................................................................. 3-10
Bit Operation Codes .............................................................. 3-11
3.5.1 ElTON .................................................................... 3-11
3.5.2 ElTOF .................................................................... 3-12
3.5.3 TESTB .................................................................... 3-12
3.5.4 Example .................................................................. 3-12
Compare Operation Code .......................................................... 3-13
Input and Output Operation Codes ................................................. 3-14
3.7.1 CHAIN ................................................................... 3-14
3.7.2 DSPLY ................................................................... 3-16
3.7.3 Example .................................................................. 3-17
3.7.4 EXCPT ................................................................... 3-17
3.7.5 FORCE ................................................................... 3-18
3.7.6 READ .................................................................... 3-19
3.7.7 SETLL .................................................................... 3-19
Branching Operation Codes ....................................................... 3-20
3.8.1 GOTO .................................................................... 3-20
3.8.2 TAG ...................................................................... 3-21
3.8.3 Example .................................................................. 3-22

3.9

Lookup Operation Code ........................................................... 3-22
3.9.1 Searching Tables .......................................................... 3-23
3.9.2 Searching Arrays .......................................................... 3-24
3.9.3 Example .................................................................. 3-25
3.10 Subprogram Operation Codes .................................................... 3-25
3.10.1 CALL .................................................................. 3-25
3.10.2 EXTRN ................................................................. 3-26
3.10.3 GIVNG ................................................................. 3-26
3.10.4 PARM .................................................................. 3-27
3.10.5 PARMD ................................................................. 3-28
3.10.6 PARMV ................................................................. 3-28
3.10.7 PLIST .................................................................. 3-29
3.10.8 Example ................................................................ 3-30

Appendix A Character Sets
Appendix B Differences Between VAX RPG II and PDP-11 RPG II
Appendix C PCA Applied to an RPG II Program
Figures
1-1
1-2
1-3
1-4
1-5
1-6
1-7

Character String ................................................................. 1-2
Address of a String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Word Data Type .................................................................. 1-3
Longword Data Type .............................................................. 1-3
Packed Decimal Data Type ........................................................ 1-4
Overpunched Decimal Data Type ................................................... 1-6
Overpunched Decimal Data Type ................................................... 1-6

Tables
1-1
1-2
2-1
2-2
2-3
2-4
2-5
2-6
3-1

Overpunched Decimal Representation of Nonleast Significant Digits .................. 1-5
Overpunched Decimal Representations of Least Significant Digit and Sign ............. 1-5
Modes of Processing for Primary, Secondary and Demand Files ....................... 2-24
Modes of Processing for Record Address Files ....................................... 2-25
Modes of Processing forInput or Update Chained Files .............................. 2-26
Expansion Factor and Block Length Values ........................................ 2-34
File Sharing ..................................................................... 2-36
Edit Codes and Examples ........................................................ 2-106
Summary of Operation Codes ...................................................... 3-31

xiii

',-

(

Preface
Intended Audience
This manual is intended for use by programmers familiar with the VAX RPG II language.
It is designed to be used both as a reference manual and as a user's guide.

Document Structure
This manual contains 12 chapters in Part I (programming information), 3 chapters in Part
II (language information), and 3 appendixes.
Part I
Chapter 1

Explains the VAX RPG II logic cycle.

Chapter 2

Explains how to compile, link, and run programs.

Chapter 3

Explains how to use the VAX RPG II editor to create and edit programs.

Chapter 4

Explains how to use VAX RPG II indicators.

Chapter 5

Explains how to manage files.

Chapter 6

Explains those elements that affect printer output files.

Chapter 7

Explains how to create and access tables.

Chapter 8

Explains how to create and access arrays.

Chapter 9

Explains how to use the VAX RPG II CALL interface to access RTL procedures, system services, and subprograms.

Chapter 10

Explains how to use the VAX Symbolic Debugger to debug VAX RPG II
programs.

Chapter 11

Explains the format of a listing file.

Chapter 12

Explains how to improve the efficiency of programs.

Part II
Chapter 1

Explains VAX RPG II elements and data types.

Chapter 2

Lists specifications, allowable entries, and their functions.

Chapter 3

Explains how to use VAX RPG II operation codes.

Appendix A

Lists the VAX RPG II character sets.

Appendix B

Explains the differences between the PDP-11 RPG II and the
VAX RPG II language and editor.
Shows PCA applied to an RPG II program.

Appendix C

Conventions Used In This Document
Conventions

Meaning

•

The RPG II editor cursor is represented by a box .

[]

Brackets enclose an optional portion of a format.

{}

Braces enclose a mandatory portion of a format.
A vertical ellipsis indicates that not all of the program lines in an
example are shown.

Definitions
In this manual, the following definitions apply:
Column name

The first letter of the first word of a column name is capitalized. For
example, Alternate collating sequence.

Program module

A program module is a VAX RPG II main program or a subprogram.

Subprogram

A subprogram isa separately compiled program module that must be
linked with the main program.

Subroutine

A subroutine is a block of code executed by the EXSR operation code.

xvi

Important Information
The on-line release notes contain some brief information on the product, last-minute information that was discovered too late to be printed in the documentation, and any known
restrictions. After you install VAX RPG II, read the release notes interactively by typing
the HELP RPG RELEASE_NOTES command. You can print the release notes by typing
the following DCL commands:
$ HELP/oUTPUT=RPG.LIS RPG RELEASE_NOTES
$ PRINT/DELETE RPG.LIS

Following is a list of some common problems and how to work around them:
• Leave the editor and make sure that the VMS terminal characteristics are set properly for your terminal by typing the SET TERMINAL/INQUIRE command if the following error message is displayed:
%TPU-E-NoNANSICRT. SYS$INPUT Must be an ANSI CRT

If you are using a VK100(GIGI) terminal and the terminal screen does not appear to
update correctly, leave the editor and type the SHOW TERMINAL command to make
sure that the device is a VK100. Ifit is not, type the SET TERMINAL/INQUIRE command to make sure that the VMS terminal characteristics are set properly for your"
terminal.
• Use the RPG/CHECK:BLANKS_IN_NUMERICS command to convert blanks in
numeric data to zeros if you run your program and receive the following message:
A nUMeric field contains invalid data

• If the line printer listing of a printer output file is not spacing as you expect, make
sure you are using the INOFEED qualifier with the PRINT command.
• If a source line in the compiler listing contains one or more periods (.) where you have
not entered a period in the program line, it is because the program line contains a
nonprintable character (for example, a TAB character or a null character). It is possible to enter nonprintable characters when using an editor other than the RPG II editor to create or edit a program.
• Make sure you have a BYTLM quota of at least 8192, a PRCLM quota of at least 1, and
the TMPMBX privilege if you receive the following message immediately after invoking the RPG II editor COMPILE command:
Subprocess not activated leave editor and checK quotas and privileges

xvii

• If you continue to get the above message when using the RPG II COMPILE command,
increase the BYTLM quota.
• Make sure you can run the compiler without problems using the RPG command at the
DCL command level if you receive the following message:
Unexpected error durinl cOMPilation leave editor and trY Del RPG COMMand

If you have no problem running the compiler using the RPG command, increase the
BYTLM quota.
The BYTLM and PRCLM quotas and the TMPMBX privilege can be changed by the
system manager using the VAXIVMS AUTHORIZE utility.

xviii

Chapter 1

The VAX RPG II Logic Cycle
VAX RPG II is an extended implementation of the RPG II language that was developed by
IBM as a problem-oriented language for commercial applications and includes DIGITAL
extensions for integration with the VMS architecture. In general, VAX RPG II is a language processor that provides a convenient means of preparing a wide variety of reports
and other commercial data processing applications. VAX RPG II runs under the VAX/VMS
or MicroVMS operating system and consists of a compiler and editor.
RPG II is a nonprocedural language; every program compiled by the RPG II compiler executes according to a fixed, predefined logic cycle. Unlike the logic of a procedural language
such as COBOL, the logic is not supplied by the programmer, but is built into the compiler.
This built-in logic is called the RPG II logic cycle. The execution of an RPG II program
consists of a number of iterations of the logic cycle.
The RPG II specifications you code determine what happens within the various phases of
the logic cycle, but cannot change the basic sequence of program execution.
For example, you can code an Input specification to program RPG II to recognize and process a particular record type, but you cannot program RPG II to read three input records in
a row, print a report heading, load a table, immediately write four different output records,
and then perform some total calculations; this series of steps, while perfectly acceptable in
a COBOL program, does not fit into the predetermined structure of the RPG II logic cycle.
The fixed logic cycle of RPG II was designed specifically to accommodate the sequence of
operations needed to generate most common business reports and file maintenance functions. However, the fixed nature of the RPG II logic cycle does not prevent you from controlling the set of functions performed for each input record, and, to some extent, the sequence
and timing ofthese functions. For example, by setting various indicators (see Part I, Chapter 4) on or off when certain conditions occur, you can actually affect the sequence of program execution within the phases of the general logic cycle. Therefore, to write effective
RPG II specifications, and to take advantage of what flexibility and control RPG II does
provide, you must thoroughly understand the structure and timing characteristics of the
overall RPG II logic cycle, and recognize both RPG II's special capabilities and its
limitations.

1-1

1.1 The RPG II General Logic Cycle
Every RPG II program follows the same basic series of execution steps, which form the
general logic cycle. Some of the programs you write will need to call upon one or more of the
additional operations ofRPG II: matching fields, chaining, overflow processing, and lookahead processing. Each of these additional operations is executed according to a fixed logic
cycle within the overall logic cycle of the program. These functions are described later in
this chapter.
The RPG II general logic cycle is executed once for each input record of a primary or secondary file. The general logic cycle consists of the following three steps, performed in order
for each record:
1. Inputting a record
2.

Performing calculations

Outputting one or more records

Each logic cycle begins when a new record is input, and ends just before the next record is
input. The RPG II specifications you code determine the range and type of specific functions performed during each phase. During the calculation and output steps within each
cycle, there are two distinct timing phases:
• Total time - operations are performed on summary data accumulated from a group of
related records.

• Detail time - operations are performed on individual records.
Sections 1.4.1 and 1.4.2 describe total-time and detail-time characteristics and operations.
The first and last iterations ofthe RPG II logic cycle are somewhat different from all other
iterations. Sections 1.2 and 1.3 describe these differences and explain how you can take
advantage of them.

1.2 The First Cycle
When program execution begins, and before the first input record is read, several onetime-only operations are performed. You can exert control over this process by providing
detail-time output records conditioned by the 1P (first-page) indicator, and by using output
specifications with either no conditioning indicators or with all negative conditioning
indicators. (See Part I, Chapter 4 for more details on conditioning indicators.) During the
first cycle, RPG II performs the following initialization operations:
• Obtains the current date (UDATE, UDAY, UMONTH, and UYEAR - see Part I,
Chapter 6).
• Opens all files (see Part I, Chapter 5).

1-2

The VAX RPG II Logic Cycle

(

• Loads pre-execution-time tables and arrays (see Part I, Chapters 7 and 8).
• Initializes page number counters.
• Prints heading and detail lines conditioned by the IP indicator, by all negative indicators other than the IP indicator, and by no indicators.
Although all iterations ofthe logic cycle (other than the first) include a total-time phase,
RPG II bypasses all total-time calculations and total-time steps during the first cycle
unless the LR (last-record) indicator is on. This behavior, like the logic cycle itself, is built
into RPG II.
After initialization tasks are performed, RPG II reads the first record in the primary file, if
used, and then reads the first record in each secondary file, if used, and determines the type
of each record read.

1.3 The Last Cycle
The last cycle is performed after all the records you specified for processing until end-of-file
have been read from all primary and secondary files. When the last record from the last file
has been read, RPG II sets on the LR (last-record) indicator and all the control-level indicators tLl through L9). Then, after this last record has been processed, RPG II performs the
following operations:
1. Performs total-time calculations.
2.

Writes total-time output.

Outputs any tables or arrays that have output files associated with them.

Closes all files.

Ends program execution.

1.4 A Normal Cycle
A normal cycle in an RPG II program can be defined as any cycle but the first or the last.
During a normal cycle, RPG II performs all operations necessary to process a single input
record. Because of the nature of most RPG II applications, a normal program cycle includes
two special phases - total time and detail time. Total time occurs before detail time. A
normal cycle consists of the following sequence of steps:
1.

Outputting heading lines, if specified

Outputting detail-time information pertaining to the previous record

Reading an input record

The VAX RPG II Logic Cycle

1--3

Performing total-time calculations for the previous record, if required

Performing total-time output

Checking the LR (last-record) indicator; if it is on, terminates the program (see
Section 1.3 above)

Processing the record read in Step 3; performs all detail-time calculations

Steps 4 and 5 constitute total time; Steps 1, 2, and 7 constitute detail time.
This list of steps in a normal cycle is an overview only. See Figure 1-1 for a complete
description of a normal RPG II logic cycle.

1.4.1 Total Time
During total time, RPG II checks which control-level indicators (L1 through L9) you have
defined, and the control field you have associated with each. For example, if your application involves the generation of a monthly sales report, you may have associated indicator
L9 with the grand total of monthly sales, indicator L8 with total sales by region, indicator
L 7 with total sales by district office, and indicator L6 with total sales by salesperson. (See
Part I, Chapter 4 for details on using control-level indicators.)

Field length
I Decimal positions
I IHaif adjust (H)
I
I Indicators
Operation
I II
I IIResulting
I I
I
Factor
Resu It I I lind i cators
I
I I
Factor
field I 11+ - 0
I
I I
1
2
I
I I I> < = +- Comments --+
I
I
CI NxxNxxNxxl
011
1213
I
4
1516
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contro I I eve I

** *
Cl9
Cl8
Cl7

*
MONTH
REGION
DIST

*MUlT *12

ADD REGION
ADD DIST

GRAND
TOTREG
TOTDIS

*--*** * * *

~~-----------~
ZK-4329-B5

1-4

The VAX RPG II Logic Cycle

If, during a particular cycle, it is determined that the salesperson identification number in
the record just read is different from the salesperson number in the previous record, a control break has occurred at the salesperson total level. At this point, your program will output the accumulated total sales for the salesperson whose number was found in the
previous record.
You might print each person's name and sales total on a separate line. Or, you might choose
to print a page heading (with a date), and then print a salesperson's total sales, thus providing a separate one-page report for each salesperson. The Output and Calculation specifications you code determine the contents, order, and appearance of your report.
During another cycle, it might be determined that the region identifier ofthe record just
read is different from the region number in the previous record. Given the control-level
indicators described in the first paragraph in this section, this means that a three-level
control break has occurred. In this situation, you must first output the accumulated total
for an individual salesperson, then the accumulated total for a district office, and, finally,
the accumulated total for the region.
Similarly, after the last input record in the file has been read, a four-level control break has
automatically occurred. At that point, your program must first output the accumulated
total for the last individual salesperson in the last district office; then, the accumulated
total for the last district office; then, the accumulated total for the last region; and, finally,
the accumulated grand total of all sales for the month.
After all control breaks have been taken care of, total time ends and detail time begins.
Detail-time operations deal with the record just read.

1.4.2 Detail Time
During detail time, your program performs operations specific to each individual record.
In the example described in Section 1.4.1, each time a record is read, the detail-time operations might consist ofthe following steps:
1.

Printing an output line on your report. For example, each record in your file might
contain a weekly sales figure for a particular salesperson. The report would list the
week's beginning and ending dates, and the sales figure.

Adding the sales figure to all active accumulators. Then, when the next control
break occurs, each accumulator will contain the correct amount.

Performing any other operations you defined in your specifications. These might
include moving data fields and handling errors.

Figure 1-1 provides a detailed annotated illustration of a complete, normal RPG II program cycle. Each processing and decision box is numbered; the numbers are keyed to the
annotations that immediately follow the figure.

The VAX RPG II Logic Cycle

1-5

First cycle

Get date if UDAlE, UDAY, UMONTH, or UYEAR used.
Load pre-execution-time tables and arrays.
Open all files.

Beginning of normal cycle

*DETL
Perform heading, detail, and fetched overflow output.
Set 1P indicator off.

Overflow
routine.

>-_____y_e_s_-.j

Terminate
program.

4.
Set off control-level and any record-identifying
indicators.
Set off overflow indicators unless they were set on
during detail-time calculation or output operations
of previous cycle.

5.
yes

Figure 1-1: RPG II Logic Cycle

1-6

The VAX RPG II Logic Cycle

Key to Figure 1-1
1. This step is executed only during the first cycle. It initializes your program for execution. Initialization consists of retrieving the date (if you specified UDATE,
UDAY, UMONTH, or UYEAR), opening all files, and loading all pre-executiontime tables and arrays.
2.

RPG II writes heading and detail lines (identified by H or D in column 15 (Type) of
the Output specification). Heading and detail lines are always executed at the
same time. If conditioning indicators are specified, the conditions for the indicator
must be satisfied. Ifthe fetch overflow logic is specified, and the overflow indicator
is on, RPG II writes the appropriate overflow lines. Ifthe 1P indicator is on (during
the first cycle only), RPG II prints all lines conditioned by it, then sets the 1P indicator off. RPG II executes this step at the beginning of the program so that heading
lines can be printed before actual processing begins.

RPG II checks whether any halt indicators (H1 through H9) are on; if any are, the
program terminates. If you do not want your program to terminate here, you must
set all halt indicators off previous to this step. You can set halt indicators on, however, at any time during the program.

RPG II sets control-level indicators (L1 through L9) and all indicators used as
record-identifying indicators off. RPG II also sets overflow indicators (OA through
OG, OV) off, unless they were set on during detail time (detail-time calculation or
output operations) in the preceding cycle. All other types of indicators that are on
remain on.

Here, RPG II determines whether the LR indicator is on. Ifit is, RPG II branches to
step 15 and sets on control-level indicators L1 through L9, if used.

The VAX RPG II Logic Cycle

1-7

6.
no

yes

Read input record from the last file processed, if
required. (Not required for input files with
look-ahead fields, or on the first cycle).
For the first cycle, read and determine record type
and sequence of the first record in all primary and
secondary files.

8.
yes

Determine record type and check sequence.

10.
Determine which file to process.
If a FORCE operation was specified, use unless
the file is at its EOF.
If no FORCE operation was specified, call the
matching field routine.

Matching
field routine.

Figure 1-1: RPG II Logic Cycle (Cont.)

1-8

The VAX RPG II Logic Cycle

Key to Figure 1-1: RPG II Logic Cycle (Cont.)
6.

RPG II determines whether a primary file was specified by the program. If not,
RPG II proceeds directly to step 16.

If required, RPG II reads an input record from the last primary or secondary file
processed. If this was an input file with look-ahead fields, the record is already
available; therefore, no read operation may be necessary at this time. On the first
cycle, a record is read from each primary and secondary file.

RPG II tests the file just read for end-of-file. If end-of-file has been encountered, the
program bypasses step 9.

If RPG II reads a record from a file, the record type is determined and the record
sequence is checked. If the record type cannot be determined, or the record is out of
sequence, the program terminates.

10.

In this step, RPG II determines which file to process. If a FORCE operation was
executed during the previous cycle, the forced file is selected for processing. (All
records processed with a FORCE operation are processed with the MR (matchingrecords) indicator set off.) However, ifthe forced file is at EOF (end-of-file), the normal multi-file logic selects the next record for processing. Ifno forced file was specified, RPG II determines whether matching fields were specified. If so, the
matching-fields routine is given control (see Figure 1-2). Otherwise, all records in
a primary file are processed first, then the records from each secondary file in ordpl'
of their specification.

The VAX RPG II Logic Cycle

1-9

11.

yes

12.

Set on the record-identifying indicator
for the selected record.

13.
no

14.

Save contents of the control fields.

15.

Set on control-level indicators.
as required.

Figure 1-1: RPG II Logic Cycle (Cont.)

1-10

The VAX RPG II Logic Cycle

Key to Figure 1-1: RPG II Logic Cycle (Cont.)
11. Here, RPG II determines whether the LR indicator should be set on. The LR indicator is set on when the program has reached the end of all the files that you have
specified for processing until the end-of-file, and when all the records from secondary files that match the last primary record have been processed. If the LR indicator should be set on, RPG II branches to step 15 and sets on indicators L1 through
L9.
12.

RPG II sets on the record-identifying indicator for the record selected for processing.

13. RPG II determines whether the record selected for processing has caused a control
break to occur. A control break occurs when the value in the control field of the
record being processed differs from the previous value of the control field. See Section 1.4.1. for more information.
14.

If a control break has occurred, RPG II saves the contents of all appropriate control
fields.

15. If a control break has occurred, RPG II sets the appropriate control-level indicator
(L1 through L9) on; at the same time, RPG II sets all lower-level control-level
indicators on. The L1 through L9 indicators can be used for conditioning only if
they have been defined as conditioning indicators.

The VAX RPG II Logic Cycle

1-11

16.
no

now?

17.

yes

-TOTC
Perform total-time calculations.

18.

-TOTL
Perform total-time output and
fetched overflow output.

Overflow
routine.

19.

Perform table and

>-_____y_e_s_~;array output; close
files; terminate
program.

20.
no

Figure 1-1: RPG II Logic Cycle (Cont.)

1-12

The VAX RPG II Logic Cycle

Key to Figure 1-1: RPG II Logic Cycle (Cont.)
16.

RPG II determines whether total-time calculation and output operations should be
performed. If control-level indicators are not specified in columns 59 and 60 (ControlleveD of the Input specification, RPG II bypasses total-time calculation and
output operations during the first cycle only; after the first cycle, RPG II performs
total-time calculation and output operations for every cycle.
If control-level indicators are specified, RPG II bypasses total-time calculation and
output operations until after the first record with control fields is processed. When
the LR indicator is on, RPG II always performs total-time calculation and output
operations.

17.

In this step, RPG II performs all total-time calculations conditioned by a controllevel indicator or containing LO in columns 7 and 8 ofthe Calculation specification.
Total-time calculations can include CHAIN operations, in which a record is immediately retrieved from an input file (see Figure 1-3), or READ operations, in which
the next record is retrieved from a demand file.

18.

Here, RPG II writes all total-time output lines that satisfy the conditions specified
by the indicators. If an overflow indicator (OA through OG, or OV) is on, and Fetch
overflow is specified, RPG II writes the overflow lines as well.

19.

RPG II determines whether the LR indicator is on. Ifit is, RPG II performs table
and array output, closes all files, and terminates the program.

20.

RPG II checks to determine whether any overflow indicators (OA through OG, and
OV) are on.

The VAX RPG II Logic Cycle

1-13

21.

yes

*OFL

Perform overflow output.

f----- Overflow routine.

I
22.

Set MR indicator on or off, as required.

23.

Extract data fields from the record to be processed.
Set field-record-relation indicators on or off, as
required.

24.

Look-ahead
fields
specified?

25.

yes

Perform look-ahead operation.

26.

ook-ahead routine

l
1

*DETC
Perform detail-time calculations.

Return to the beginning of the normal cycle (step 2.).

ZK-1571- 84

Figure 1-1: RPG II Logic Cycle (Cont.)
1-14

The VAX RPG II Logic Cycle

Key to Figure 1-1: RPG II Logic Cycle (Cont.)
21.

If any overflow indicators are on, the overflow routine is given control (see Figure
1-4). RPG II outputs all lines conditioned by those overflow indicators that are on.
However, RPG II outputs these lines only if they were not output by Fetch overflow
logic (step 2 or step 18).

22.

RPG II determines whether the MR (matching-record) indicator should be set on.
If this is a multifile program, and the record being processed is a matching record,
RPG II sets the MR indicator on; it remains on for the duration of the cycle during
which the matching record is processed. If not appropriate, RPG II sets the MR
indicator off.

23.

RPG II extracts data fields from the record to be processed, and sets the field indicators on or off, as appropriate, for those fields.

24.

RPG II then determines whether look-ahead fields are specified in the last file
processed and whether it is an input file.

25.

If the last file processed was an input file with look-ahead fields, RPG II passes
control to the RPG II look-ahead routine (see Figure 1-5). In this routine, RPG II
retrieves the look-ahead record and extracts the look-ahead fields. If look-ahead
fields are not specified, RPG II continues with detail-time calculations (step 26).

26. This is the detail-time calculations step. Here, RPG II performs all conditioned
detail-time calculations and subroutines. The calculations may include CHAIN
and READ operations (see Figure 1-3). Detail-time calculations complete the
RPG II logic cycle. Then, the cycle branches to step 2 to begin again.

The VAX RPG II Logic Cycle

1-15

1.5 RPG II Detail Program Logic Cycle
This section consists of annotated flowchart diagrams that illustrate in detail various routines within the predefined RPG II logic cycle. The following figures are provided:
• Figure 1-2 illustrates the RPG II matching-fields routine.
• Figure 1-3 illustrates RPG II file processing for chained and demand files.
• Figure 1-4 illustrates RPG II overflow processing.
• Figure 1-5 illustrates RPG II look-ahead processing.
1.

Determine the file
to be processed.

Issue a run-time
error message.

yes
Move the matching fields
to the temporary buffer.

Return to program.
ZK-1458-83

Figure 1-2: Logic Cycle for the Matching-Fields Routine
1-16

The VAX RPG II Logic Cycle

Key to Figure 1-2
1.

RPG II determines whether the program uses more than one primary and secondary file. Ifmultifile processing is in effect, processing continues with step 2. Otherwise, the program branches to step 3.

RPG II compares the matching fields to determine which file is to be processed.
RPG II extracts the matching fields and checks their sequence.

If the matching fields are not in sequence, a run-time error occurs and the program
terminates.

RPG II moves the matching fields into a temporary buffer. The next record is
selected, based on the value of the matching fields.

RPG II returns to the program.

The VAX RPG II Logic Cycle

1-17

Issue a run-time error.

yes

Set on resulting indicator.

ZK-1459-83

Figure 1-3: Logic Cycle for Chained and Demand Files
Key to Figure 1-3
1.

RPG II retrieves the next record in the file specified by the CHAIN or READ operation code. If the record is not found on a CHAIN operation or an end-of-file occurs
during a READ operation and a resulting indicator is not specified, a run-time
error occurs. If the record is not found on a CHAIN operation or an end-of-file
occurs during a READ operation and a resulting indicator has been specified, the
indicator is set on and control returns to the program.

RPG II sets on the record-identifying indicator associated with the chained or
demand file for the record type read.

3. Then, RPG II extracts the fields from the record just retrieved. Also, RPG II sets on
any field indicators associated with the record.
4.

RPG II returns to the program.

1-18

The VAX RPG II Logic Cycle

yes

no
Output lines conditioned
by the overflow indicator.

3.
Return to the program.

ZK-1460-83

Figure 1-4: Logic Cycle for Overflow Processing

Key to Figure 1-4
1.

RPG II determines whether the overflow lines were written previously, using the
fetch overflow routine. If so, the program branches to the specified return point;
otherwise, it continues with step 2.

RPG II evaluates all overflow lines and writes those lines that satisfy the conditions of the indicator(s).

RPG II returns to the program.

The VAX RPG II Logic Cycle

1-19

Set all look-ahead
fields to 9s.

ZK-1461-83

Figure 1-5: Logic Cycle for Look-Ahead Processing

Key to Figure 1-5
1. RPG II reads the next record for the file being processed. If the end of the file has
been reached, all look-ahead fields are filled with 9s and control is returned to the
program.
2.

RPG II extracts the look-ahead fields from the record.

3. RPG II returns to the program.

1-20

The VAX RPG II Logic Cycle

Chapter 2

Developing Programs
You can create a source program using the RPG II editor (See Part I, Chapter 3); then, you
must compile, link and run the program with commands to the VAXNMS operating system. If your RPG II program does not execute correctly, you must modify it and repeat
these steps until it does.
When you compile an RPG II program, the RPG II compiler creates an object module file.
When you link your program, you use the VAX Linker. The linker reads the object module
file and uses libraries to replace external references with the address of the executable
code that defines it. Then the linker places that code in an executable image file. When you
execute your program, the system executes that image.

2.1 Compiling Programs
To compile a source program, use the RPG command. Its format is:
RPG[/qualifier(s)] file-spec-list[/qualifier(s)]
where:
/qualifier(s) Specifies special actions the compiler is to perform. See Sections 2.1.2.1
through 2.1.2.8 for information on qualifiers.
file-spec-list Specifies the source file(s) to be compiled. Normally, you would specify a single source file, but if you need to create a single object file from more than
one source file, separate the file specifications with plus ( + ) signs. RPG II
appends the files in the order you specify. If you separate source file specifications with commas (,), RPG II compiles the programs separately and creates a single object file for each source file.
When you execute the RPG command, RPG II compiles the program and generates an
object module with the specified file name and the default file type OBJ. The compiler can
also generate other output files, depending on the qualifiers you supply.

2-1

When you compile a source file with the RPG command and specify only its file name, the
compiler searches for a source file with the specified name that:
• Is stored on the default device in the default directory
• Has a file type of RPG
If more than one file meets these conditions, the compiler chooses the one with the highest
version number.
For example, assume that your default device is DBAO:, your default directory is [SMITH],
and you give this command:
$
$

RPG FIRSTTRY

The appearance of the second DCL command prompt ($) indicates that the compilation is
finished.
The compiler searches device DBAO: in directory [SMITH], seeking the highest version
of FIRSTTRY.RPG. If you do not specify an output file, the compiler generates the file
FIRSTTRY.OBJ and stores it on device DBAO: in directory [SMITH]; with a version number that is one higher than any existing version number for FIRSTTRY.OBJ.

2.1.1 Default Compiler Options
When you compile a program, you can specify options like ILIST or INOWARNINGS. The
options you get when you do not specify them are called defaults.
You can change these defaults for your own programs by using qualifiers with the RPG
command. The RPG command accepts qualifiers to change the defaults for a single compilation, as shown in the following example:
$

RPG/LIST/NOOBJECT MYPROG

This RPG command tells RPG II to compile a single source file (MYPROG.RPG), and overrides the default compiler settings for
• Listing - The RPG II compiler will produce a compiler listing.
• Object file - The RPG II compiler will not produce an object file.
You can specify other defaults by defining RPG as a symbol, as shown in the following
example:
$

RPG :=="RPG/CHECK/LIST/CROSS"

If you type RPG MYPROG, the ICHECK, ILIST, and ICROSS qualifiers are in effect.

2-2

Developing Programs

2.1.2 RPG II Compiler Qualifiers
This section describes the RPG command itself; Sections 2.1.2.1 through 2.1.2.8 describe
the RPG command qualifiers and list their default values.
You can change defaults by using qualifiers with the RPG command. Qualifiers have the
form:
/qualifier[ = value]

Many qualifiers have a corresponding form that negates the action specified by the qualifier. The negative form is:
/NOqualifier

For example, ILIST tells the compiler to produce a listing file; /NOLIST suppresses the
listing.
You can specify qualifiers so that they affect either all files in the command, or only certain
files. If the qualifier immediately follows the RPG command, it applies to all files, as shown
in the following example:
$

RPG/LIST ABC,XYZ,RST

This command specifies listing files for ABC.RPG, XYZ.RPG, and RST.RPG.
Qualifiers following a file specification (with some exceptions) affect only the associated
file, as shown in the following example:
$

RPG/LIST ABC,XYZ/NOLIST,RST

The above RPG command specifies listing files for ABC.RPG and RST.RPG, but not for
XYZ.RPG. Qualifiers to a single file specification in an appended list of file specifications
are exceptions to this rule. (A list of file specifications separated by plus signs is called an
appended list.) See Example 5 in the following list.
1.

RPG/LIST AAA ,BBB ,ccc

RPG II compiles source files AAA.RPG, BBB.RPG, and CCC.RPG as separate files,
produces three object files (AAA.OBJ, BBB.OBJ, and CCC.OBJ), and three listing
files (AAA.LIS, BBB.LIS, and CCC.LIS).
2.

$ RPG ;OO{+YYY+zzz

RPG II appends source files XXX.RPG, YYY.RPG, and ZZZ.RPG, and compiles
them as a single program. This command produces one object file named
XXX.OBJ, but does not produce a listing file.

RPG/OBJECT=SQUARE CIRCLE

RPG II compiles source file CIRCLE.RPG and produces object file SQUARE.OBJ.
This command produces no listing file.

Developing Programs

2-3

$ RPG

AAA+BBB ,CCClLIST

RPG II produces two object files: AAA.OBJ (created from AAA.RPG and
BBB.RPG), and CCC.OBJ (created from CCC.RPG). RPG II also produces the listing file CCC.LIS.
5.

$ RPG

ABC+DEF INDDBJECT+>(YZ

RPG II appends and compiles the source files ABC.RPG, DEF.RPG, and XYZ.RPG.
Because qualifiers in a list of appended files affect all files in the list, this command
suppresses the creation of an object file.
Table 2-1 lists the qualifiers you can use with the RPG command.
Table 2-1: RPG II Command Qualifiers
Qualifier

Negative Form
LNOJBOUNDS
INOCHECK
[N01RECURSION
[NO]BLANKS_IN_NUMERICS
ALL
NONE

ICHECK=

Default
INOCHECK

ICROSS_REFERENCE

INOCROSS..REFERENCE

INOCROSS_REFERENCE

/DEBUG =

INODEBUG

/DEBUG = (TRACEBACK,NOSYMBOLS)

!LIST[ = file-spec]

INOLIST

INOLIST (interactive)
ILIST (batch)

/MACHINE_CODE

INOMACHINE_CODE

IOBJECT[ = file-spec]

INOOBJECT

IOBJECT

ISEQUENCE_CHECK

INOSEQUENCE_CHECK

INOWARNINGS

IWARNINGS = (OTHER,NOINFORMATION)

[NO]SYMBOLS
[NO]TRACEBACK
ALL
NONE

IWARNINGS =

[NO]OTHER
LNO]lNFORMATION
ALL
NONE

Sections 2.1.2.1 through 2.1.2.8 describe RPG II command qualifiers in detail.
2.1.2.1 CHECK
The CHECK qualifier causes RPG II to check for errors in array indexes, recursive calls to
subroutines, and blanks in overpunched numeric fields. The CHECK qualifier format is:
ICHECK[ = (option[, ... ])]

Developing Programs

where option can be:
[NOjBOUNDS
[NOjRECURSION
[NOjBLANKS_IN_NUMERICS
ALL
NONE

where:
BOUNDS

Checks array indexes to make sure they are within array
boundaries specified by the program.

RECURSION

Verifies that subroutines are not called recursively.
Converts blanks in overpunched numeric fields to zeros.

ALL

Indicates that RECURSION, BOUNDS, and
BLANKS_IN_NUMERICS checking will be performed.

NONE

Indicates that RECURSION, BOUNDS, and
BLANKS_IN _NUMERICS checking will not be performed.

Specifying CHECK is equivalent to specifying CHECK = ALL; NOCHECK is equivalent
to CHECK = NONE. NOCHECK is the default.
Use CHECK = (RECURSION,BOUNDS) for programs only during initial program debugging, because compiling with this qualifier results in additional code and, consequently,
takes more time to process. Using NOCHECK means that the compiler does not signal an
error for an array reference outside the bounds of an array or for a subroutine that has
been called recursively. Therefore, using NOCHECK may result in your program getting a
memory-management or access-violation error at run time.
2.1.2.2 CROSS_REFERENCE
The CROSS_REFERENCE qualifier causes the compiler to include cross-reference information in the listing file for the compiled source file. Cross-reference information lists
variable names, indicators, and the program lines in which they were referenced. Its format is:
/CROSS_REFERENCE

When you use CROSS_REFERENCE, you must also use LIST, or LIST must be in effect
(default for batch mode) to produce a listing file. NOCROSS_REFERENCE is the default.

Developing Programs

2-5

2.1.2.3 DEBUG
The DEBUG qualifier causes the compiler to provide information for the VAX Symbolic
Debugger and the system run-time error traceback mechanism. Its format is:
IOEBUG[ = (option[, ... ])]

where option can be:
[N01SYMBOLS
[N01TRACEBACK
ALL
NONE

where:
SYMBOLS

Causes the compiler to provide the debugger with local symbol definitions for user-defined names (including dimension information for
arrays). If you use SYMBOLS, you can refer to data entities by their
names when you use the debugger.

TRACEBACK

Causes the compiler to provide an address correlation table so that the
debugger and the run-time error traceback mechanism can translate
absolute addresses into source program routine names and line numbers.

ALL

Causes the compiler to provide both local symbol definitions and an
address correlation table.

NONE

Prevents the compiler from providing debugging information.

Neither the TRACEBACK qualifier nor the SYMBOLS qualifier affects a program's executable code.
Specifying DEBUG is equivalent to specifying DEBUG = ALL; NODE BUG is equivalent
to DEBUG = NONE. DEBUG = TRACEBACK is the default. For information on debugging, see Part I, Chapter 10.
2.1.2.4 LIST
The LIST qualifier controls whether or not RPG II produces a listing file for the compiled
program. The listing file contains the source program and a compilation summary. If you
also use the MACHINE_CODE qualifier, the listing file will include the compiler-generated object code for the compiled program. If you also use the CROSS_REFERENCE qualifier, the listing file will include cross-reference information. The format of the LIST
qualifier is:
ILlST[ =file-specl

You can include a file specification for the listing file. Otherwise, the output file defaults to
the name of the first source file and the file type LIS.

2-6

Developing Programs

If the RPG command is executed in interactive mode, the default is NOLIST. If the RPG
command is executed in batch mode, the default is LIST.
The listing file uses a listing page length which depends on the logical SYS$LP_LINES.
Any value between 30 and 255 can be used for SYS$LP-LINES. The listing page length
uses 3 line top and bottom margins. If the logical SYS$LP_LINES is not defined, the
default page length will be 66 lines (60 listing lines after the 3 line top and bottom margins
are subtracted).
2.1.2.5 MACHINE-CODE
The MACHINE_CODE qualifier specifies that the listing file include the compiler-generated object code. Its format is:
IMACHINE_CODE

When you use MACHINE_CODE, you must also use LIST, or LIST must be in effect
(default for batch mode) to produce a listing file. NOMACHINE_CODE is the default.
2.1.2.6 OBJECT
The OBJECT qualifier causes RPG II to produce an object module, and optionally specifies
its file name. Its format is:
IOBJECT[ = file-spec]

The default is OBJECT.
By default, the compiler generates object files as follows:
• If you specify one source file, RPG II generates one object file.
• If you specify multiple source files separated by plus signs, RPG II appends the files
and generates one object file.
• If you specify multiple source files separated by commas, RPG II compiles and generates a separate object file for each source file.
You can use both plus signs and commas in the same command line to produce different
combinations of appended and separated object files. See examples in Section 2.1.2.
To produce an object file with an explicit file specification, you must use the OBJECT qualifier, in the form OBJECT = file-spec. Otherwise, the object file has the same name as its
corresponding source file, and the default file type OBJ. By default, the object file produced
from appended source files has the name of the first source file specified. All other file specification attributes (node, device, directory, and version number) assume the default
values.
During the early stages of program development, you may find it useful to suppress the
production of object files until your source program compiles without errors. Use the
NOOBJECT qualifier to do this.
Developing Programs

2-7

2.1.2.7 SEQUENCE-CHECK
The SEQUENCE_CHECK qualifier causes the compiler to check the line numbers in columns 1 through 5 of every program line to make sure they are in ascending line-number
sequence. If the line numbers are not in sequence, the compiler issues a warning message.
Its format is:

/SEQUENCE_CHECK

NOSEQUENCE_CHECK is the default.
2.1.2.8 WARNINGS
The WARNINGS qualifier allows you to specify whether RPG II displays information and
warning messages. Its format is:
IWARNINGS[ = (option[, ... ))]

where option can be:
[NO]OTHER
[NO]INFORMATION

ALL
NONE

where:
OTHER

Causes RPG II to display warning messages.

INFORMATION

Causes RPG II to display information messages.

ALL

Causes RPG II to display both warning and information messages.

NONE

Prevents RPG II from displaying warning or information messages.

Specifying WARNINGS is equivalent to Splfcifying WARNINGS = ALL; NOWARNINGS is
equivalent to WARNINGS = NONE. WARNINGS = (NOINFORMATION,OTHER) is the
default.

2.2 Linking and Running Programs
The VAX Linker uses the object module produced by the RPG II compiler as input and
produces an executable image file as output. This file has the same name as your program
and the default file type EXE.
When your program calls other programs ~ that is, when it is made up of more than one
program module - the linker takes multiple object files and creates a single executable
image from them. See Part 1, Chapter 9 for information on subprograms.

2-8

Developing Programs

(

You use the LINK command to invoke the VAX Linker. The format of the LINK command
is:
LINK[/command-~ualifier(s)]

file-spec-list[/file-~ualifier(s)]

where:
command-qualifier(s)

Specifies output file options. Use DEBUG to provide information
for the VAX Symbolic Debugger. See Part I, Chapter 10 for information on debugging RPG II programs. See the VAX/VMS
Linker Reference Manual for information about other command
qualifiers.

file-spec-list

Specifies a file or the files to be linked.

file-qualifier(s)

Specifies input file options. See the VAX/VMS Linker Reference
Manual for information on file qualifiers.

When you type LINK, the system prompts with:
_File:

Respond by typing the file specification(s). If multiple file specifications do not fit on a single line, type a hyphen (-) as the last character on the line and continue on the next line.
For example, to link the object file created from the program FIRSTTRY in Section 2.1,
type:
$ LI NK
$

F I RSTTRY

This command tells the linker to accept FIRSTTRY.OBJ as input, and to produce
FIRSTTRY.EXE as output. Once the executable file has been created, you run it with the
RUN command:
$ RUN F I RSTTRY
$

2.3 Interpreting RPG II Compiler Error Messages
The format of an RPG II compiler error message is:
fac-severity-IDENT
where:
fac

Represents the facility. The facility is always RPG.

severity

Indicates the severity of the error. Severity can be I (information), W (warning), E (error), or F (fatal).

IDENT

Represents the IDENT field.
Developing Programs

2-9

The IDENT field of an RPG II compiler error message designates the error recovery action
taken by the RPG II compiler. IDE NT fields can have one ofthe following values:
• SPEC_IGNORED
The current specification is ignored. The resulting program, if nonfatal, acts as if the
specification was not entered.
• ENTRY_IGNORED
The entry in the current field is ignored. The resulting program, if nonfatal, acts as if
the field was blank.
• DEFN_IGNORED
The current definition ofthis field is ignored. The resulting program, if nonfatal, uses
the previous definition.
• CHAR_IGNORED
The current character is ignored. The resulting program, if nonfatal, acts as if the
column was blank.
• FATAL
No error recovery action can be taken. The severity level is always fatal.
• ACCEPTED
The compiler accepts the entry exactly as specified.
• SEE_MESSAGE
The error text contains the recovery action taken by the RPG II compiler.
• O.-ASSUMED
The entry in the current field is ignored. The resulting program, if nonfatal, acts as if
the field contained o.

2-10

Developing Programs

Chapter 3

Using the RPG II Editor
This chapter explains how to use the RPG II editor. You use the RPG II editor to create, edit
and read (or simply view) RPG II programs.
The RPG II editor is available on the VT100 family, VT200 family and VK100 (GIG!)
terminals.
The RPG II editor allows overstriking; that is, you can change a program line by placing
the cursor in the column where you want to make a change and typing a new character,
without affecting any characters to the right of the cursor.
The cursor is represented as a box CI) in the examples throughout this chapter.
All examples in this chapter assume a terminal page size of 24 lines, unless otherwise
noted.

3.1 RPG II Editor Qualifiers
Invoke the RPG II editor by typing the RPG/EDIT command. To create a file, provide a file
specification, as shown in the following example:
$

RPG/EDIT FIRSTTRY

You do not have to supply the file type .RPG, because it is the default.
To edit or read a file, include the name ofthe file you want to edit or read when you invoke
the RPG II editor. See Section 3.8.1 for an example.
When you invoke the editor, if the number of columns (SET TERMINAL/WIDTH = m) is
less than 80 or the number of lines (SET TERMINAL/PAGE = n) is less than 6, the editor
will display the following message, then will exit:
At least G lines and 80 colUMns on the screen are

required

See the VAX/VMS DeL Dictionary for information on the SET TERMINAL command.
Note that the SET TERMINAL command must be done before invoking the editor.

3-1

Ifthe file you specify when invoking the RPG II editor is a new file, the RPG II editor displays the following message:
File not found

Ifthe file you specify when invoking the RPG II editor is an existing file, the RPG II editor
displays the message:
n lines

read froM file device:[directory]filenaMe.type;version

Finally, the RPG II editor displays the following message:
Press the PF2 key to let help inforMation

Ifthe terminal page size is fewer than 17 lines, the initial help message is not displayed. If
HELP is requested using the HELP key or a SET HELP command in a startup command
file, and the terminal page size is less than 17 lines, the following message is displayed and
the usual HELP action will not be performed:
At least 17 lines on the screen are

required by the editor to provide HELP

Table 3-1 lists the qualifiers that you can use with the RPG/EDITcommand. If you precede
a qualifier with NO, that qualifier is not in effect.

Table 3-1: RPG/EDIT Command Qualifiers
Qualifier

Negative Form

Default

ICOMMAND

INOCOMMAND

ICOMMAND

ICREATE

INOCREATE

ICREATE

IJOURNAL

INOJOURNAL

IJOURNAL

IOUTPUT

INOOUTPUT

IOUTPUT

IRE AD_ONLY

INOREAD_ONLY

IRECOVER

INORECOVER

ISTART_POSITION

INOSTARTJ>OSITION

ISTART _POSITION

Sections 3.1.1 through 3.1.7 describe these qualifiers and explain how to use them.

3.1.1 COMMAND
The COMMAND qualifier causes the editor to execute a specified file in the startup command file. Its format is:
ICOMMAND[ = file-spec]

The RPG II editor will read commands from any file specified by COMMAND. Each command in the specified file will be treated as ifthe COMMAND function was used.
3-2

Using the RPG II Editor

COMMAND is present by default, with a default value of RPGINI. If NOCOMMAND is
used, then no command file is executed. See Section 3.7.2 for information on startup command files.

3.1.2 CREATE
The CREATE qualifier creates a file for the editing session. If the specified file already
exists, that file is opened. Its format is:
/CREATE[ = file-spec]

CREATE is present by default. If NOCREATE is used, the file is not created. However, if
the file already exists, it is opened.

3.1.3 JOURNAL
The JOURNAL qualifier creates a journal file for the current editing session. Its format is:
/JOURNAL[ = file-spec]

If you should leave an editing session abnormally, you can use the journal file to re-execute
all the commands you issued during the session. To do this, type the RPG/EDIT/RECOVER
file-spec command.
JOURNAL is present by default. If you do not provide a file specification with JOURNAL,
the RPG II editor creates a journal file with the same name as your input file and the
default file type JOU.

3.1.4 OUTPUT
The OUTPUT qualifier defines the name of the output file. Its format is:
/OUTPUT[ = file-spec]

OUTPUT is present by default. If you do not provide a file specification with OUTPUT, the
RPG II editor creates an output file with the same name and type as the input file, whose
version number is one higher than the highest existing version of the input file.
If you use NOOUTPUT, the RPG II editor does not create an output file. In this case, you
must either use the QUIT command or specify a file specification with the EXIT command
to leave the editor.

3.1.5 READ_ONLY
The READ_ONLY qualifier tells the RPG II editor not to create a journal file or an output
file for the file you are currently editing. Its format is:
/READ_ONLY

U sing the RPG II Editor

3-3

You can use READ_ONLY when you want to view a file without changing its contents. In
this case, you must either use the QUIT command or specify a file specification with the
EXIT command to leave the editor.
NO READ_ONLY is the default, and automatically creates ajournal file and output file for
the file you are currently editing (unless you leave the RPG II editor using the QUIT
command).
Using READ_ONLY has the same effect as using both the NOOUTPUT and the
NOJOURNAL qualifiers with the RPG/EDIT command.

3.1.6 RECOVER
The RECOVER qualifier reads the commands from a journal file and re-executes all the
edits you made during an editing session. Its format is:
IRECOVER

Once the recovery is done, the RPG II editor responds with:
Recovery cOMPlete

At this time, you can continue editing your file.
If the name of the recovery journal file is different from the default (the same file name as
the input file with the JOU file type), use JOURNAL = file-spec and RECOVER to specify
another name, as shown in the following example:
$

RPG/EDIT/JOURNAL=FILE1.JOU/RECOVER FILE2.RPG

In this example, the journal file name is FILE1.JOU and the name of both the input and
output files is FILE2.RPG. If you do not use JOURNAL, the journal file name is
FILE2.JOU.
NORECOVER is the default.

3.1. 7 START_POSITION
The START_POSITION qualifier determines where the VAX RPG II editor starts in the
editing buffer. Its format is:
ISTART_POSITION[ = (line,column)]

START_POSITION is the default. The setting is line 1, column 1.
NOSTART_POSITION is equivalent to START_POSITION = (1,1)

3-4

Using the RPG II Editor

3.2 The RPG II Editor Screen
The RPG II editor screen consists of the following:
• The help window
• An 80-column ruler
• Tab stops
• The editing window
• The Prompt line
• The Message line
Note that when you use a terminal without scrolling regions (for example, VKIOO (GIG!)),
the RPG II editor must redisplay the information on the screen rather than scrolling new
information onto the screen.

Using the RPG II Editor

3-5

The screen below shows an example of each of the above listed items. Note that all screens
shown are based on a default setting of24 lines with Ii top ruler. If you want to change the
page size, see the SET TERM/PAGE commands in the VAX/VMS DeL Dictionary.

PF1IPF2 - RPG II specification fot'lIIats
+-------+-------+-------+-------+
Pt'ess the PFlIKP7 ke!:l and t!:lpe HELP fot'
I Gold I Hell' IFnx FndlDIL UdLi
infot'lIIation on cOllllllands and functions.
+-------+-------+-------+-------+
Fot' hell' on a specific ke!:l. pt'ess the
IPag CllldlSec DsplRev HovlDIF UdFI
PF2 ke!:l followed b!:l the ke!:l fot' which
+-------+-------+-------+-------+
!:lou want hell' infot'lIIation.
IAdv BotlBck ToplCut PaslShL ShRI
Othet' ke!:ls: BS_KEY
DEL_KEY
+-------+-------+-------+-------+
TAB_KEY
UP.DOWN.LEFT.RIGHT IFld
IEol DEIiCht' Coli
CTRL_R_KEY CTRL_W_KEY
+-------+-------+-------+Ent
CTRL_U_KEY CTRL_LKEY
I
Lin OpL
I Se I Res I
+---------------+-------+-------+

011
I
2
I
3
I
4
I
5
I
6
I
7
1234567890123456789012345678901234567890123456789012345678901234567890123456789

:;;; ........ '. ..... ........ ..... ........ .............. ...............

H* FUNCTIONAL DESCRIPTION:
H*
This pt'ogt'alll pt'oduces a t'epot't of shiplllents fot' vat'ious
H*
pt'oducts bt'oken down b!:l division and depat'tillent using an
H*
input file with the shiplllent data fot' the past 4 ,,!uat'tet's.
H*-H
FSHIPS
IP F
41
DISK
Seat'ch fot': editot'
Stt'in not found

help window

SO-column
ruler
tab stops

)
source window

}

prompt
message

line
line

~--------------~
ZK-4666-85

When you use the HELP function (default = PF2), the help window appears on the screen.
It includes a diagram of the keypad and other key functions.
When the keypad diagram is displayed and you enter the HELP function again, the following message appears:
Press the key for which

YOU

want

f~rther

help inforMation

You can press the HELP key and any other key listed in the keypad diagram to display
help information on that key in the help window. See Section 3.8.1 for an example.
The HELP_SPECS function (default = PFlIPF2) causes the help window to display the
specification format for the current line. See Section 3.8.1 for an example. See the
DISPLAY function, Section 3.5.11, for information on how to remove HELP from the
screen.

3-6

Using the RPG II Editor

If you do not request help information, the RPG II editor displays the program in the entire
screen except for the ruler and tab stops and the prompt and message lines, as shown in the
following example:

011
I
2
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

*........ .* .. *...
I

1*1 I

••••••• 1*1' ••••••••••••••••• II I

•••

••

H*++

H* FUNCTIONAL DESCRIPTION:
H*
This progra~ produces a report of ship~ents for various
H*
products broken down b~ division and depart~ent using an
H*
input file with the ship~ent data for the past 4 ~uarters.
H*-H

FSHIPS IP F
FSUHREP 0 F
E

DISK
LPRINTER
420

41
98

QTY

LSUHREP 55FL 500L
ISHIPS AA 01

I
I
I
I

5 DIV

7 DEPT
8 16 PROD
17 24 QTY
01

XFOOTQTY

Press the PF2 ke to et he)

L2
L1

PROQTY 30

Information

"-------------------------~

ZK-4330-85

An 80-column ruler in reverse video is displayed above or below the source window_ See
Section 3.6.8-4 for information on setting the ruler. Below the ruler, a tab stop marks the
beginning of each field for the specification of the current line.

An asterisk (*) indicates a tab stop where you can enter a field value. A dot (.) indicates
that the column must be left blank. A dash (-) after an asterisk indicates that the field
must contain numeric data. Numeric data must be right-justified. Blanks after an asterisk
indicate that the field must contain alphanumeric data. Alphanumeric data must be leftjustified.
The RPG II editor marks the line after the last line in the editing buffer with the End-ofBuffer [EOB] symbol. The [EOB] symbol will not appear in the output file.
The last two lines of the screen consist ofthe prompt line and the message line. The prompt
line displays prompts in reverse video for input when you use functions such as FIND and
COMMAND. The message line displays informational and error messages. The following
Using the RPG II Editor

3-7

example shows what the RPG II editor screen looks like with the specification format for
the current line, the prompt for the FIND function, and an informational message.

Currenc!:j s!:jl1lbol
I Inverted print (DIJ)
I I
Alternate collating se~uence (SE)
I I
I
iP forl1ls position (1)
I I
I
I
H
I I
I
I
011
I
2
I
3
I
4
I
5
161
7
1234567890123456789012345678901234567890123456789012345678901234567890123456

*.,.

I . ' I . , ••

H*++

*.. *.... *.

I. ",

•••

I.'

.* ...

•••••• ,., •••••••••• I

••••••

H* FUNCTIONAL DESCRIPTION:
H*
This progral1l produces a report of shipl1lents for various
H*
products broken do~n b!:j division and departl1lent using an
H*
input file with the shipl1lent data for the past 4 ~uarters.
H*-H

r.I!'I!!I.-!IF.SHIPS

IP F

DISK

• I

~~------------~

ZK-4331-85

3.3 The RPG II Editor Cursor

The RPG II editor cursor is represented as a box (in reverse video) or an underscore,
depending on the cursor setting for your terminal. The cursor is displayed in the current
column on the current line. Note, however, that if the current column is column 81, the
cursor is displayed in column 80 on the current line. If you try to move the cursor to the
right of column 81 or to the left of column 1, the current column remains unchanged and
one of the following messages is displayed in the message line:
AtteMPt

to Moue

past

coluMn 81

AtteMPt to r.IO'Je before colurnn 1

3-8

Using the RPG II Editor

3.4 The RPG II Editor Buffers
The RPG II editor uses the following four buffers:
• Editing
The editing buffer contains the file of source code that is displayed on the RPG II editor screen.
• Deleted-field
The deleted-field buffer contains the field deleted when you use the DELETE_FIELD
function (default = MINUS). See Section 3.5.14 for information on the
DELETE_FIELD function. You can access the contents of the deleted-field buffer by
using the UNDELETE_FIELD function. See Section 3.5.15 for information on the
UNDELETE_FIELD function.
• Deleted-line
The deleted-line buffer contains the line deleted by the DELETE_LINE function
(default = PF4). See Section 3.5.6 for more information on the DELETE_LINE function. You can access the contents of the deleted-line buffer by pressing the
UNDELETE_LINE (default = PFlIPF4). See Section 3.5.7 for more information on
the UNDELETE_LINE function.
• Paste
The paste buffer contains the range of lines delimited by the SELECT (default =
PERIOD) and CUT (default = KP6) functions (see Section 3.5.32). You can access the
contents of the paste buffer by using the PASTE function (default = PFlIKP6). See
Section 3.5.21 for more information on the PASTE function.

3.5 Keys and Functions
To make sure the RPG II editor is using the correct VMS terminal characteristics for your
terminal, type the DCL SET TERM/INQUIRE command before invoking the RPG II editor. The following diagram is a graphic representation of the RPG II editor keypad.

U sing the RPG II Editor

3-9

VT100/VT200/VK100IGIGII Keypad

RPG II Editor Keypad
Help

Fnx Fnd D1L UdL

PFI

PF2

PF3

PFLI

Gold

Pag C!Tld Sec Dsp Re\l Mo \) D1F UdF

Ad \I Bot : B c ~~ Top lCut Pas ShL ShR

Fld

Eol Del Chr Col

Enter

E nt
Lin Dpl

Sel Res

Chapter 3 refers to those keys with numbers and symbols as KPn, where KP means
keypad and n is the number of the key shown on the VT100 family, VT200 family, and
VK100 (GIG!) keypad. For example, KP6 refers to the keypad key numbered 6. Table 3-2
lists the name and default function of each key.
Note that many keys have alternate functions. An alternate function is enabled when you
press the GOLD key (default = PF1) followed by the key you want to use. This sequence is
referred to in this chapter as PFlI[key_name].
Table 3--2: RPG II Editor Define Key Defaults
Command

Key

Default

DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY

PFl
UP
DOWN
LEFT
RIGHT
PF2
PF2
PF3
PF3
PF4
PF4
KP7
KP7
KP8
KP8
KP9
KP9
MINUS
MINUS
KP4
KP4
KP5
KP5
KP6

GOLD
UP
DOWN
LEFT
RIGHT
HELP _KEYPAD
HELP _SPECIFICATIONS
FIND_NEXT
FIND
DELETE_LINE
UNDELETE_LINE
PAGE
COMMAND
SECTION
DISPLAY
REVIEW_ERROR
MOVE_TO_RULER
DELETE_FIELD
UNDELETE_FIELD
ADVANCE
BOTTOM
BACKUP
TOP
CUT
(continued on next page)

3-10

Using the RPG II Editor

Table 3-2: RPG II Editor Define Key Defaults (Cont.)
Command

Key

Default

DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY/GOLD
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY
DEFINE KEY

KP6
COMMA
COMMA
KPI
KP2
KP2
KP3
KP3
ENTER
KPO
KPO
PERIOD
PERIOD
CTRLJLKEY
CTRL_LKEY
RETURN
CTRL_ILKEY
CTRL_U_KEY
CTRL_W_KEY
CTRLZ_KEY
DEL_KEY
FlO
F12
F15
F16
El
E2
E3
E4
E5
E6

PASTE
SHIFT_LEFT
SHIFT_RIGHT
FIELD
END_OF _LINE
DELETE_TO_END_OF_LINE
CHARACTER
COLUMN
ENTER
LINE
OPEN_LINE
SELECT
RESET
FIELD_BACKWARD
FIELD_FORWARD
NEW_LINE
REFRESH_SCREEN
DELETE_TO_BEGINNING_OF_LINE
REFRESH_SCREEN
EXIT
DELETE_CHARACTER
EXIT
FIELD_BACKWARD
HELP _KEYPAD
ENTER
FIND
PASTE
CUT
SELECT
SECTION_BACKWARD
SECTION_FORWARD

See DEFINE KEY (Section 3.6.2) for a complete list of definable keys. Sections 3.5.1
through 3.5.44 describe these functions and explain how to use them.

Using the RPG II Editor

3-11

3.5.1 The GOLD Function
The GOLD function (default = PF1) enables you to select the alternate function of a key_
In the following diagram ofthe keypad, the alternate key names appear on the right:
Gold

Help

Fnx Fnd DlL UdL

Pa9 Crnd Sec Dsp Rev Mov DlF UdF
Adv Bot BcK Top Cut Pas ShL ShR
Fld

Eol DEI Ch r Col
Ent
Lin OpL

3-12

Using the RPG II Editor

Sel Res

3.5.2 The HELP_KEYPAD Function
The HELP_KEYPAD function (default = PF2) displays the keypad diagram in the help
window, as shown in the following example:

PF1/PF2 - RPG II specification formats
+-------+-------+-------+-------+
Press the PF1/KP7 ke~ and t~pe HELP for
I Gold I Help IFnx FndlDlL UdLI
information on commands and functions.
+-------+-------+-------+-------+
For help on a specific ke~, press the
IPag CmdlSec DsplRev MovlDlF UdFI
PF2 ke~ followed b~ the ke~ fOI' which
+-------+-------+-------+-------+
~ou want help information.
IAdv BotlBck ToplCut PaslShL ShRI
Other ke~s: BS_KEY
DEL_KEY
+-------+-------+-------+-------+
TAB_KEY
UP,DOWN,LEFT,RIGHT IFld
IEol DEllChr Coli
CTRL_R_KEY CTRL_W_KEY
+-------+-------+-------+Ent
CTRL_U_KEY CTRL_Z_KEY
I
Lin OpL
ISel Resl
+---------------+-------+-------+
o I 1 I 2 I 3 I 4 I 5 Ie:; 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
*........... * .. * .... * .............. *................................ .
I
H*++
H* FUNCTIONAL DESCRIPTION:
H*
This program produces a report of shipments for various
H*
products broken down b~ division and department using an
H*
input file with the shipment data for the past 4 quarters.
H*-H

FSHIPS

IP F

DISK

~
ZK-4333-85

If HELP is requested while the terminal page size is fewer than 17 lines, the following
message will be displayed and the usual HELP action will not be performed:
At least 17 lines on the screen are

required by the editor to provide HELP

HELP cannot be displayed unless there are enough lines on the screen to position the
HELP window and still keep the ruler, prompt line, message line and one line of the editing window visible.

Using the RPG II Editor

3-13

Ifthe keypad diagram is already displayed, you can get help information on any function
(except GOLD) by using HELP_KEYPAD (default = PF2) and the key for which you want
help information. Help information will appear in the help window. The following example shows help on the CUT (default = KP6) and PASTE (default = PFlIKP6) functions:

KP6
The CUT function ~oves the selected range of lines to the paste buffer. The
selected range of lines consists of the line identified b~ the SELECT
function up to the current line. The line following the selected range of
lines beco~es the current line. The current colu~n re~ains unchanged.
The PASTE function inserts the contents of the paste buffer directl~ in
front of the current line. The current line is ~oved down to acco~~odate
the lines ft'o~ the paste buffet'. The current colu~n and line re~ain
h

011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

*...... "" .* .. *.... *.

H*++

•••••••

.* .. '"

"'"

•••••••

••••

••

FSHIPS

IP F

DISK

~-------------~

ZK-4332-85

3.5.3 The HELP_SPECIFICATIONS Function

The HELP_SPECIFICATIONS function (default = PFlIPF2) displays the specification
format for the current line. In the following example, if the current line is line 100, the
RPG II editor displays the Control specification format when you use
HELP _SPECIFICATIONS.

3-14

Using the RPG II Editor

Cur'r'enc~ s~fllbo I

I Inverted print (DIJI
I
Alternate collating sequence (SEI
I
I
IP forflls position (II

I
I
I
I

I
I

011
12
I
3
I
4
I
5
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
* •........•• * •. * ..•• * .•............ * ....•..•..••....•....•.•••..•....
I 100H*++
H* FUNCTIONAL DESCRIPTION:
H*
This prografll produces a report of shipfllents for various
H*
products broken down b~ division and departfllent using an
H*
input file with the shipfllent data for the past 4 quarters.
H*-H

FSHIPS

IP F

DISK

"'---------------------------~
ZK-4334-85

To restore the editing buffer to the entire screen, as shown in the following example, use
the DISPLAY function (default = PFlIKP8).

Using the RPG II Editor

3-15

01112131415161071
12345678901234567890123456789012345678901234567890123456789012345678901234567890

I'"

H*++

•••

*.. *.. .* .....
I

I'"

.* ..

••••••••••

I."

H* FUNCTIONAL DESCRIPTION:
H*
This prograro produces a report of shiproents for various
H*
products broken down b~ division and departroent using an
H*
input file with the shiproent data for the past 4 quarters.
H*-H

FSHIPS IP F
FSUHREP 0 F
E

41
98

QTY

LSUHREP 55FL 500L
ISHIPS AA 01

420

5 DIV L2
7 DEPT L1
8 16 PROD
17 24 QTY
1

I
I
I
I

C
C

DISK
LPRINTER

01
01

PROQTY

XFOOTQTY
ADD DEPQTY

PROQTY 30
DEPQTY 30

~~------------~
ZK-4335-85

The RPG II editor automatically updates the tab stops and the specification format, if displayed, for the specification type of the current line after a terminator (such as TAB) is
typed.

3.5.4 The FIND_NEXT Function
The FIND_NEXT function (default = PF3) moves the cursor to the first character position
ofthe next occurrence ofthe search string, depending on the current direction (ADVANCE
or BACKUP). Use the FIND function to enter the search string. Ifthe current direction is
ADVANCE, the RPG II editor will try to locate the next occurrence ofthe search string by
searching forward from the current column and line to the end of the editing buffer. If the
current direction is BACKUP, the RPG II editor will try to locate the next occurrence ofthe
search string by searching backward from the current column and line to the beginning of
the editing buffer. If the RPG II editor cannot locate the search string, the current column
and line remain unchanged and an error message is displayed in the message line. See
Section 3.8.2 for an example of the FIND_NEXT function.

3-16

Using the RPG II Editor

3.5.5 The FIND Function
The FIND function (default = PFlIPF3) locates the search string you specify. The RPG II
editor moves the cursor forward or backward to the beginning of the nearest occurrence of
the search string, depending on the current direction (ADVANCE or BACKUP). If the current direction is ADVANCE, the RPG II editor will try to locate the search string by
searching forwards from the current column and line towards the end of the editing buffer.
Ifthe current direction is BACKUP, the RPG II editor will try to locate the search string by
searching backwards from the current column and line towards the beginning ofthe editing buffer.
When you use the FIND function, the RPG II editor displays the following prompt in the
prompt line:
Search for:

You can enter up to 63 characters for the search string. Ifno search string is entered, the
RPG II editor will search for the last search string specified. Note that you cannot use control characters (RETURN, FORM FEED, TAB, and so on) in the search string.
If the RPG II editor cannot locate the search string, the current column and line remain
unchanged and the following error message is displayed in the message line:
String not found

Terminate the search string by pressing either the RETURN key or the ENTER key.
See Section 3.8.2 for an example of the FIND function.

3.5.6 The DELETEJ.INE Function
The DELETE_LINE function places the current line in the deleted-line buffer, at the same
time removing it from the screen. The line following the deleted line becomes the current
line. The current column remains unchanged. If there is no line following the deleted line,
the cursor is left in column 1 at the [EOB] mark.

3.5.7 The UNDELETE_LINE function
The UNDELETE_LINE function (default = PFlIPF4) inserts the contents of the deletedline buffer before the current line. The new line becomes the current line, and the current
column remains unchanged.
Ifthe deleted-line buffer is empty, no action is taken but an error message is displayed in
the message line.

Using the RPG II Editor

3-17

3.5.8 The PAGE Function
The PAGE function (default = KP7) causes the editing buffer to move forward or backward, depending on the current direction (ADVANCE or BACKUP), to the next page. A
page is the start or finish of a section with the same kind of specification type (column 6).
In the following example, if the current cursor position is in column 34 on line 120, the
current direction is ADVANCE, the current setting for the SET STARTCOLUMN command is 7, and you use the PAGE function, the RPG II editor moves the cursor to column 7
on line 170.

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
** *
*
* *
*
10H*++
20H* FUNCTIONAL DESCRIPTION:
30H*
This program produces a report of shipments for various
40H*
products broken down b!:j division and department using an
50H*
input file with the shipment data for the past 4 quarters.
60H*-70H
80FSHIPS IP F
41
DISK
LPRINTER
90FSUt1REP 0 F
98
QTY
100E
420
110LSUt1REP 55FL 500L
120lSHIPS AA 01
1301
1 5 DIV
L2
6 7 DEPT L1
1401
8 16 PROD
1501
17 24 QTY
1601
170C,
XFOOTQTY
PROQTY 30
180C 01
PROQTY
ADD DEPQTY
DEPQTY 30
190C 01

~~-------------~

ZK-4336-85

3.5.9 The COMMAND Function
The COMMAND function (default = PFlIKP7) allows you to execute an RPG II editor
command. The RPG II editor displays the following prompt:
COfrllrland:

3-18

Using the RPG II Editor

The following commands can be entered:
• COMPILE
• DEFINE KEY
• EXIT
• HELP
• INCLUDE
• QUIT
• RESEQUENCE
• SET
• SHOW
• SUBSTITUTE
Sections 3.6.1 through 3.6.10 describe these RPG II editor commands and explain how to
use them.

3.5.10 The SECTION Function
The SECTION function (default = KP8) causes the editing buffer to move forward or backward the number oflines specified by the current setting of the SET SECTION command.
The direction of the movement depends on the current direction (ADVANCE or BACKUP).
The current column remains unchanged. See Section 3.6.8 for information on changing the
SECTION value. See Sections 3.5.16 and 3.5.18 for information on setting the current
direction.

3.5.11 The DISPLAY Function
The DISPLAY function (default
screen.

PFlIKP8) removes any help information from the

3.5.12 The REVIEW_ERROR Function
If you use the RPG II editor COMPILE command to compile your program, and your program contains errors, the RPG II editor moves the cursor to the column and line where the
first error occurs, and displays the error text in the message line. The REVIEW _ERROR
function (default = KP9) moves the cursor to the column and line where the next error
occurs, and displays the error message for that error in the message line. You can edit the
line to correct the error and use the REVIEW _ERROR function again to move the cursor to
the next error.

Using the RPG II Editor

3-19

If you use REVIEW _ERROR and there are no more errors, the RPG II editor displays the
following message in the message line:
No More errors found

If you added or deleted a line in the program while correcting errors, the RPG II editor will
display the following message when REVIEW _ERROR is used again:
Reissue the editor COMPILE cOMMand

3.5.13 The MOVE_TO_RULER Function
The MOVE_TO-RULER function (default = PFlIKP9) places the cursor as close as possible to the top of the ruler (ifthe editing window is above it) or towards the bottom of the
ruler (if the editing window is below it). The current column remains unchanged. Movement is restricted to the boundaries of the SET SCROLL offsets. If the ruler is positioned
above the editing window and the last line of the buffer appears, movement is stopped. If
the ruler is positioned below the editing window and the first line of the buffer appears,
movement is stopped. The MOVE_TO_RULER function will have no effect ifno ruler is
visible.

3.5.14 The DELETE_FIELD Function
The DELETEYIELD function (default = MINUS) places all the characters between the
cursor and the next field (forward or backward, depending on the current direction) into
the deleted-field buffer and replaces the characters with spaces.

3.5.15 The UNDELETE_FIELD Function
The UNDELETE_FIELD function (default = PFlIMINUS) replaces the current field with
the contents ofthe deleted-field buffer. Ifthe contents ofthe deleted-field buffer are longer
than the current field, the RPG II editor just copies to the current field untill it is filled.
If the contents of the deleted-field buffer are shorter than the current field, the RPG II
editor fills the current field to the right with spaces. Also, the cursor moves to the next
field, depending on the current direction (ADVANCE or BACKUP).

3.5.16 The ADVANCE Function
The ADVANCE function (default = KP4) sets the current direction to forward, that is, to
the right and down, toward the end ofthe editing buffer. ADVANCE sets the direction for
the following functions:
• CHARACTER
• DELETE_FIELD

3-20

Using the RPG II Editor

• UNDELETE_FIELD
• FIELD
• END_OF _LINE
• FIND
• FIND_NEXT
• LINE
• PAGE
• SECTION

3.5.17 The BOTTOM Function
The BOTTOM function (default = PFlIKP4) moves the cursor to the last line in the editing buffer. The current column remains unchanged.

3.5.18 The BACKUP Function
The BACKUP function (default = KP5) sets the current direction to backward, that is, to
the left and up, toward the beginning of the editing buffer. BACKUP sets the direction for
the same functions that ADVANCE sets direction for.

3.5.19 The TOP Function
The TOP function (default = PFlIKP5) moves the cursor to the first line in the editing
buffer. The current column remains unchanged.

3.5.20 The CUT Function
The CUT function (default = KP6) moves the selected range of lines to the paste buffer.
The selected range oflines consists of the line identified by the SELECT function (default
= PERIOD) to the current line. The line following the selected range oflines becomes the
current line. The current column remains unchanged. If there is no line following the
selected range, the cursor is left in column 1 at the [EOB] mark. See Section 3.8.2 for an
example using CUT.

3.5.21 The PASTE Function
The PASTE function (default = PFlIKP6) inserts the contents of the paste buffer directly
in front of the current line. The current line is moved down to accommodate the lines from
the paste buffer. The current column and line remain unchanged. See Section 3.8.2 for an
example using PASTE.
Using the RPG II Editor

3--21

3.5.22 The'SHIFTJ,EFT Function
The SHIFT.-LEFT function (default = COMMA) causes the following events to occur:
\

• The character in the current column is deleted.
• All characters to the right ofthe current column are moved one column to the left.
• The cursor position remains the same.
In the following example, if the cursor is in column 45 on line 350, and SHIFT-LEFT is
used, the RPG II editor deletes the blank in column 45, moves all the characters to the
right of the cursor one column to the left, and inserts a blank in column 80.
Before using SHIFT_LEFT:
011
12
I
3
1415
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

3500

***** * *

***---**

48 I'Qt Q2 Q3 Q4 TOTAL'
ZK-4337-85

After using SHIFT_LEFT:
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

3500

***** * *

***---**
48 MQt Q2 Q3 Q4 TOTAL'

tcursor
ZK-4338-85

3.5.23 The SHIFT_RIGHT Function
The SHIFT_RIGHT function (default = PFlICOMMA) causes the following events:
• All characters in the current column through the end of the line are moved one column to the right.
• A space is placed in the current column.
• The current column remains unchanged.
In the following example, if the cursor is in column 44 on line 350, and SHIFT-RIGHT is
used, the RPG II editor moves all characters one column to the right of the cursor and
inserts a blank in column 44. The blank in column 80 is lost.

3-22

Using the RPG II Editor

'-.

Before using SHIFT_RIGHT:

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

3500

***** * *

***---**

481Ql Q2 Q3 Q4 TOTAL'

tcursor
ZK-4339-85

After using SHIFT_RIGHT:

o I 1 I 2 I 3 I 4 I 5 161
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
u

3500

***** * *

***---u

481'Ql Q2 Q3 Q4 TOTAL'

tcursor
ZK-4340-85

3.5.24 The FIELD Function
The FIELD function (default = KP1) moves the cursor to the nearest character in the next
nonblank field. If the current direction is ADVANCE, using FIELD moves the cursor to the
beginning ofthe next nonblank field following the current column. If the current direction
is BACKUP, FIELD moves the cursor to the end of the next nonblank field preceding the
current column.
In the following example, if the cursor is in column 16 and the current direction is
ADVANCE, FIELD moves the cursor to column 21. '
011
12
I
3
I
4
I
5
I
6
17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

IINPUT

* *** *--- *--A~
I 35 CA

*---

.**---*---**

* * * * * * ....

tcursor!ursor
after
before
ZK-4341-85

Using the RPG II Editor

3-23

In the following example, if the cursor is in column 21 and the current direction is
BACKUP, FIELD moves the cursor to column 16.

o I 1 121
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

IINPUT

* *** *--- *--A~
I 35 CA

*---

.**---*---**

* * * * * * ....

!ursor before
cursor after
ZK-4342-85

Note that you cannot use FIELD to move from one program line to another.

3.5.25 The END_OF_LINE Function
The END_OF-LINE function (default = KP2) moves the cursor one column to the right of
the end ofthe current line (the last nonblank character) if ADVANCE is the current direction. If the current direction is BACKUP, END_OF _LINE moves the cursor one column to
the right of the end of the preceding line.
If the cursor is already at the end of the current line and the current direction is
ADVANCE, END_OF-LINE moves the current column one column to the right of the next
line.
In the following example, if the cursor is in column 45 and the current direction i s , , _
ADVANCE, and if you use END_OF_LINE, the RPG II editor moves the cursor to column
68.
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

3500

***** * *

***---**

48 MQ1

Q2 Q3 Q4 TOTAL'.

tcursor before

tcursor after
ZK-4343-85

(

3-24

Using the RPG II Editor

In the following example, if the cursor is in column 68 ofline 350 and the current direction
is BACKUP, and if you use END_OF _LINE, the RPG II editor moves the cursor to column
54 in line 340.

o I 1 I 2 I 3 I 4 I 5 161 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
***** * *

3400**
3500

***---**

24 'PRODUCT'.
48 'Q1 Q2 Q3 Q4 TOTAL'.

tcursor before

cursor' after
ZK·4344·85

3.5.26 The DELETE_TO_END_OF_LINE Function
The DELETE_TO_END_OF_LINE function (default = PFlIKP2) deletes the characters
from the current column to the end ofthe line. The cursor position remains unchanged.
In the following example, if the cursor is in column 46 and you use
DELETE_TO_END_OF _LINE, the RPG II editor deletes the characters in column 46
through 67.
Before using DELETE_TO_END_OF_LINE:

011
I
2
I
3
I
4
I
5
161
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

3500**

***---**

48 '~1

Q2 Q3 Q4

TOTAL'

t
CUt'SOI'
ZK-4345-85

12345678901234567890123456789012345678901234567890123456789012345678901234567890

3500

***** * *

***---**
48 '1

tcursol'
ZK-4346-85

Using the RPG II Editor

3-25

3.5.27 The CHARACTER Function
The CHARACTER function (default = KP3) moves the cursor position to the right or left,
depending on the current direction (ADVANCE or BACKUP). If you attempt to move the
cursor to the right of column 81 or to the left of column 1, no action is taken and an error
message is displayed in the message line.
In the following example, if the cursor is in column 47 and the current direction is
ADVANCE, and if you use CHARACTER, the RPG II editor moves the cursor to column
48. If the cursor is in column 47 and the current direction is BACKUP, and if you use
CHARACTER, the RPG II editor moves the cursor to column 46.

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
3500**

***** * *

***---**
48 limB Q2 Q3 Q4 TOTAL'

tt!ursor after (ADVANCE)
cursor before
cursor after (BACKUP)

ZK-4347-85

3.5.28 The COLUMN Function
The COLUMN function (default = PFlIKP3) highlights the number of the current column
by causing the column number in the 80-column ruler to blink. The column function takes
no action if no ruler is visible.
On a terminal without AVO, the COLUMN function performs no action.
On the VK100 (GIGI) terminal, the blinking for the COLUMN function is sometimes
wider than the width of one character.

3.5.29 The ENTER Function
The ENTER function (default = ENTER) terminates the following entries:
• The FIND function (see Section 3.5.5)
• RPG II editor commands (see Section 3.5.9)
The ENTER function also clears any information in the message line.

3-26

Using the RPG II Editor

/
\

3.5.30 The LINE Function
The LINE function (default = KPO) causes the cursor to move one line up or down, depending on the current direction (ADVANCE or BACKUP). The cursor is moved to the current
setting for the SET STARTCOLUMN command.

3.5.31 The OPEN_LINE Function
The OPEN_LINE function (default = PFlIKPO) creates a new line above the current line.
The new line becomes the current line, and the cursor is moved to the current setting for
the SET STARTCOLUMN command. If the current setting for the SET STARTCOLUMN
command is greater than 6, the new line will have the same specification format as the
previous line. See Section 3.8.2 for an example of the OPEN_LINE function.

3.5.32 The SELECT Function
The SELECT function (default = PERIOD) marks the current line as the beginning of the
range oflines you are selecting (select range). The SELECT function highlights column 1
of the current line in reverse video. You can use SELECT to select a range of lines to be
deleted or moved. You can then use CUT to move the selected lines from the editing buffer
to the paste buffer (see Section 3.5.20); and you can use PASTE to reinsert them into the
editing buffer at another location (see Section 3.5.21). The cursor position in the line does
not matter - the entire line will be moved into the paste buffer when CUT is used.
If you select a line as the beginning of a select range and then delete that line, the select
range will no longer be in effect and a message will be displayed in the message line.
You cannot select the line where [EOB] appears. If you select a range oflines that includes
[EOB], [EOB] will not be placed in the paste buffer.
See Section 3.8.2 for an example ofthe SELECT function.

3.5.33 The RESET Function
You can clear the current setting for the SELECT function by using the RESET function
(default = PFlIPERIOD).

3.5.34 The UP Function
The UP function (default = UP) causes the cursor to move up one line. The current column
remains unchanged. If the current line is the first line in the editing buffer, the cursor will
not be moved and an error message will be displayed.

Using the RPG II Editor

3-27

3.5.35 The DOWN Function
The DOWN function (default = DOWN) causes the cursor to move down one line. The current column remains unchanged. Ifthe current line is the last line in the editing buffer, the
cursor will not be moved and an error message will be displayed.

3.5.36 The RIGHT Function
The RIGHT function (default = RIGHT) moves the cursor to the right one column. If the
current column is 80, the cursor is not moved and column 81 becomes the current column.
If the current column is 81, the cursor will not be moved and an error message will be
displayed.

3.5.37 The LEFT Function
The LEFT function (default = LEFT) moves the cursor to the left one column. If the current column is column 1, the cursor will not be moved and an error message will be
displayed.

3.5.38 The FIELD_BACKWARD Function
The FIELD_BACKWARD function (default = BS_KEY) moves the cursor to the tab stop
preceding the current column, or, if the cursor is before the first tab stop, moves the cursor
to column 1. If the current column is 1, the cursor will not be moved and an error message
will be displayed.

3.5.39 The DELETE_CHARACTER Function
The DELETE_CHARACTER function (default = DEL_KEY) replaces the character to
the left ofthe cursor with a space and moves the cursor one column to the left. If you try to
delete a character to the left of column 1, the cursor will not be moved and an error message
will be displayed.

3.5.40 The NEW_LINE Function
The NEW_LINE function (default = RET_KEY) creates a new line following the current
line. The lines following the current line are moved down to accommodate the new line. If
the current line is the last line in the current buffer, a new last line is created. The cursor is
moved to the current setting for the SET STARTCOLUMN command. Ifthe current setting for the SET STARTCOLUMN command is greater than 6, the new line will have the
same specification format as the previous line.

3-28

Using the RPG II Editor

3.5.41 The FIELD_FORWARD Function
The FIELD_FORWARD function (default = TAB_KEY) moves the cursor to the next tab
stop after the current column. If the cursor has already passed the last tab stop,
FIELD_FORWARD moves the cursor to column 81. Ifthe current column is column 81, the
cursor will not be moved and an error message will be displayed.

3.5.42 The REFRESH_SCREEN Function
The REFRESH_SCREEN function (default = CTRL_R_KEY and CTRL_W_KEY)
rewrites the screen display. The cursor location remains unchanged.

3.5.43 The DELETE_TO_BEGINNING_OF_LINE Function
The DELETE_TO_BEGINNING_OF _LINE function (default = CTRL_U_KEY)
replaces the characters from the current column to column 1 with spaces. The cursor location remains unchanged.

3.5.44 The EXIT Function
The EXIT function (default = CTRL--Z_KEY) writes the editing buffer to an output file as
described in Section 3.1.2. If a journal file was created, it is not saved.
If you have issued the RPG II editor COMPILE command, and then leave the RPG II editor
using EXIT, the following message will be displayed:
Subprocess terMinated

If you invoked the RPG II editor with the NOOUTPUT or the READ_ONLY qualifier, the
following message will be displayed:
Use EXIT with an output file specification or QUIT

EXIT performs the same function as the EXIT/NOSAVE command.

3.6 RPG II Editor Commands
This section describes the RPG II editor commands and explains how to use them. You
must issue the COMMAND function before executing an RPG II editor command. Section
3.5.9 discusses the COMMAND function.
The following conditions exist when executing RPG II editor commands:
• If you type a command with a missing required parameter, you will get a prompt to
supply the missing parameter.

Using the RPG II Editor

3-29

• Qualifiers can appear anywhere on the line; they do not have to immediately follow
the command and can appear in any order.
• Qualifiers can be negated.
• Command line input can be in uppercase, lowercase, or mixed case.
• Abbreviations are allowed. You must type enough information to resolve any
ambiguity.
• You can enter full line comments, end ofline comments, and blank lines in a command
line.
• You can continue a command line by entering a hyphen (-) at the end of the line. You
will get a prompt for more input.
• Terminate a command by pressing either the RETURN key or the ENTER key.

3.6.1 The COMPILE Command
The COMPILE command compiles the source code in the editing buffer, and displays both
of the following messages:
Subprocess activated
Be.innin. cOMPilation

The message "Subprocess activated" appears only when the COMPILE command is issued
for the first time during an editing session.
The format ofthe COMPILE command is:
COMPILE [/LlST]

The following message is displayed indicating how many errors were found:
COMPilation cOMPlete--n errors found

Ifn is 0, no errors were found and you can leave the editor, then link and run your program.
If the compilation encounters errors, the error text associated with the first error is displayed in the message line and the cursor is moved to the column and line where the first
error occurs. If there is more than one error, use the REVIEW _ERROR function to move
the cursor to the column and line causing the next error. See Section 3.5.12 for more information on the REVIEW _ERROR function.
You can use only the LIST qualifier with the COMPILE command to create a listing file for
the compiled source code. The default is NOLIST. OBJECT is always in effect. However, if
the compilation encounters fatal errors, an object module will not be produced.

3-30

Using the RPG II Editor

You can specify a symbol definition at the DCL command level to change the defaults for a
compilation. When you issue the RPG II editor COMPILE command, the compiler will use
these settings. In the following example, the symbol RPG is defined to compile a program
and generate a listing file with machine-generated code. The compiler will also generate
code in the program to check for blanks in numerics.
$

RPG :== RPG/lIST/MAC/CHECK:5lANKS_IN_NUMERICS

To use the debugger after you enter the COMPILE command, you must first define the
following command before invoking the editor:
$

RPG := RPG/DE5UG

See Part I, Chapter 10 for information on how to set the appropriate source file.
The COMPILE command requires each line in the editing buffer to be 140 characters or
less.
If you define RPG to invoke something other than the RPG II compiler, or if the RPG II
compiler encounters an unexpected error, the following message is displayed in the message line:
Unexpected error during compilation - leave editor and trY DCl RPG command

3.6.2 The DEFINE KEY Command
The DEFINE KEY command allows you to bind specific keys to specific RPG editor functions. These functions are listed with their default key definitions in Table 3-2 at the
beginning of Section 3.5.
The following keys are bindable in the RPG editor:
• Control keys
• Cursor keys
• Editing keys (LK201 except Rainbow)
• Function keys (LK201 except Rainbow)
• Keypad keys
• Gold versions of all these keys
exceptions
The following list contains seven control key restrictions. These are special functions of
the VMS operating system.
CTRL_C_KEY
CTRL_O_KEY
CTRL_Q_KEY
CTRL_S_KEY

CTRL_T_KEY
CTRL_X_KEY
CTRLY_KEY

Using the RPG II Editor

3-31

Note that key redefinition does not cause automatic update to the editor keypad diagram
and key-specific help text.
The format of the DEFINE KEY command is:
DEFINE KEY[/GOLD] key_name function

In this command, /GOLD indicates that you must press GOLD followed by key_name to
execute the chosen function. For example:
DEFINE KEY/GDLD KP5 CUT

When you enter this command and then press the GOLD key, followed by the KP5 key, the
CUT function is executed.
If "key_name" is not a valid definable key, or if "function" is not a valid RPG editor function that is bindable to a key, a message is displayed.
To redefine the GOLD key, enter the following line at the command prompt:
DEFINE KEY KeY_naMe GDLD

To remove the GOLD key completely, enter the following line at the command prompt:
DEFINE KEY/GOLD PFl GOLD

Note that if you use a key name other than PF1 with this command, it will be treated as if
PF1 had been entered.
Note also that you must redefine the GOLD key (default = PF1) before you can define the
PF1 key to a function other than GOLD.
See Table 3-2 for a list of default key definitions. This table provides a list of definitions
that are bindable to keys. Note that in some cases, more than one key is bound to the same
procedure. Note also that TAB_KEY and CTRL_LKEY (the default settings for
FIELD.-FORWARD), and the RETURN_KEY and CTRL_M_KEY (default settings for
RETURN), can only be bound to the same function, while the FlO key and CTRL-Z_KEY
(the default settings for EXIT) may be bound to separate functions.
The SECTION_FORWARD and the SECTION_BACKWARD functions are not bound by
default to any key on the VT100 family and VK100 (GIG!) terminal keyboards. However,
you can bind any of the valid definable keys to those functions.

3-32

Using the RPG II Editor

Table 3-3 contains additional keys that are bindable to the functions listed in Table 3-2.
Table 3-3: RPG KEYNAMES FOR VALID DEFINABLE KEYS
RPGKeyname

LK201

VT100 Family
VKI00 (GIGl)

PF1
PF2
PF3
PF4
KPO,KP1, ... ,KP9
PERIOD
COMMA
MINUS
ENTER
UP
DOWN
LEFT
RIGHT
E1
E2
E3
E4
E5
E6
HELP
DO
F7, ... ,F20
TAB_KEY
RET_KEY
DEL_KEY
LF_KEY
BS_KEY
CTRL.-A_KEY
CTRLjLKEY

PFI
PF2
PF3
PF4
0,1, ... ,9

Enter
Up-arrow
Down-arrow
Left-arrow
Right-arrow
Find/E1
Insert-here/E2

Enter
Up-arrow
Down-arrow
Left-arrow
Right-arrow

Remove/E3
Select/E4

Prev-screen/E5
Next-screen/E6
Help/F15
Do/F16

F7, ... ,F20
Tab
Return

Tab
Return
Delete
Line-feed
Back-space

CtrllB

CTRL/A
CTRL/B

CtrllZ

CTRLlZ

Ctrl/A

Note the list of exceptions at the beginning ofthis section.
You can modify the key bindings shown in Table 3-2 at editor startup by creating a startup
command file with the desired DEFINE KEY commands. See Section 3.7.2, Startup Command Files, for more information on using DEFINE KEY.

Using the RPG II Editor

3-33

3.6.3 The EXIT Command
The EXIT command writes the editing buffer to the output file and leaves the RPG II editor, returning to the DeL command prompt ($), as shown in the following example:

011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
* *** *--**
** *** *
10H*++
20H* FUNCTIONAL DESCRIPTION:
30H*
This program produces a report of shipments for various
40H*
products broken down b~ division and department using an
50H*
input file with the shipment data for the past 4 C\uat'tet's,
60H*-70H
80FSHIPS IP F
41
DISK
90FSUMREP 0 F
98
LPRINTER
QTY
100E
420
110LSUMREP 55FL 500L
120lSHIPS AA 01
1301
1 5 DIV L2
1401
6 7 DEPT L1
1501
8 16 PROD
1601
17 24 QTY
170C*
180C 01
XFOOTQTY
PROQTY 30
190C 01
PROQTY
ADD DEPQTY
DEPQTY 30
53 records written to file MYDISK:[MYDIRECTORYJMYFILE,RPG;2
$

I
ZK-434B-B5

The format of the EXIT command is:
EXIT [/SAVE] [file-spec]

The output file is one of the following:
• The file name you supplied with the EXIT command
• The file name you supplied with the OUTPUT qualifier to the RPG/EDIT command
• The same file name as the input file you specified when you invoked the RPG II editor,
ifthe READ_ONLY or the NOOUTPUT qualifiers were not used with the RPG/EDIT
command
The RPG II editor will write the editing buffer to the output file even if no changes have
been made.

3-34

Using the RPG II Editor

You can use the SAVE qualifier with the EXIT command to save the journal file, if one was
created. The file name ofthe journal file is the name of the output file, if specified, with the
JOU file type. If a journal file name was not specified, the RPG II editor uses the same file
name as the input file. See Section 3.1.3 for information on journal files.
If an error occurs during the execution of an EXIT/SAVE command and you resume edit-

ing, the journaling facility will still be in effect.
If you have issued the RPG II editor COMPILE command and then leave the RPG II editor
by typing the EXIT command, the following message will be displayed in the message line:
Subprocess terminated

3.6.4 The HELP Command
The HELP command displays information on RPG II editor functions and commands in
the help window of the RPG II editor screen. The following example shows what the screen
looks like after you issue the COMMAND function, type the HELP command, and press
either the RETURN key or the ENTER key:

read this help infor~ation while using the editor b~ t~ping the HELP
co~~and.

Additional infor~ation available:
Co~~ands

Cursor

Functions Help
121

Journal

Specs

Ke~pad

12345678901234567890123456789012345678901234567890123456789012345678901234567890
*........... * .. *.... * .............. * ................................ .
I 10H*++
20H* FUNCTIONAL DESCRIPTION:
30H*
This progra~ produces a report of ship~ents for various
40H*
products broken down b~ division and depart~ent using an
50H*
input file with the ship~ent data for the past 4 quarters.
60H*-70H
80FSHIPS IP F
41
DISK

~~------------~
ZK-4349-85

Using the RPG II Editor

3-35

The format ofthe HELP command is:
HELP [/FULLj [/PAGEj [/PROMPTjlist-of-topics

The PAGE qualifier is similar to the DCL HELP command PAGE qualifier. If the help text
does not fit in a logical page (in this case, the help window), the text is displayed a page at a
time and you must enter a RETURN to advance to the next page. The default is NOPAGE.
The PROMPT qualifier is similar to the DCL HELP command PROMPT qualifier. Once
help for the given list of topics is displayed, you are prompted for additional topics, which
are then linked to the current list oftopics. Press RETURN repeatedly to back up through
the levels of help text. CTRLlZ terminates the HELP command. The default is
NOPROMPT.
The FULL qualifier uses the entire screen, except for the prompt and message lines, to
display help text. When the requested help has been displayed, the previous screen layout
is restored. You are prompted to enter a RETURN before the screen is repainted. If the
previous screen contained help text, it is not restored. Instead, the last 11 lines of text from
the current HELP is left in the help window. The default is NOFULL.
Note that FULL, PAGE and PROMPT are positional qualifiers. If they occur after a topic
or subtopic, they are interpreted as subtopics on which help is desired.
There is no fixed number on the list of topics. Whatever can fit on the command line is
valid. If you use the PROMPT mode, you can extend the depth indefinitely.
By default, the RPG II editor searches its own help library (SYS$HELP:RPGEDIHLP) for
the given list oftopics.
You can access other libraries in the following ways:
• Ifthe first topic has the form @filespec, that library is searched instead .
• If you define logical names of the form HLP$LIBRARY, HLP$LIBRARY_l, ... ,
HLP$LIBRARY _999, the LIBRARIAN searches them in the following order: root
library, main library, process libraries, group libraries, and system libraries.

3-36

Using the RPG II Editor

The following example shows what the screen looks like after you issue the COMMAND
function, type HELP COMMANDS, and press either the RETURN key or the ENTER key:

r-::

ANDS
Editor co~~ands are executed b~ pressing the COMMAND function (PFI/KP7 - see
infor~ation for FUNCTIONS).
An~ co~~and, parallleter or 'tualifier can be
abbl'eviated so that the infOl'lIIation t~ped is una~biguous. The prolllpt
"Colllllland: " is displa~ed in reverse video on the prolllpt line. An~
characters that can norlllall~ be t~ped in the editor lIIa~ be t~ped at the
Pt'O~pt.

Qualifiers can be negated and can also appear in an~ order on a cOIII~and line
after the nallle of the cOIII~and.
Blank cO~lIIand lines are
excla~ation point ("I")

ignored. Also an~ text on a cOlllllland line after an
is ignored.

Additional infor~ation available:
COMPILE
SET

DEFINE
SHOW

EXIT
HELP
SUBSTITUTE

INCLUDE

QUIT

RESEQUENCE

011
1213
I
4
I
5
I
6
17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
* •...•...•.. * .• * .... * ....•..•.•••.• * ........•.....•.•........••.•....
I 10H*++
20H* FUNCTIONAL DESCRIPTION:
30H*
This progralll produces a report of shiplllents for various
40H*
products broken down b~ division and departlllent using an
50H*
input file with the ship~ent data for the past 4 quarters.
60H*--

~~~SHIPS

IP F

DISK

.---/

~----------------------

ZK-4350-85

After you press either the RETURN key or the ENTER key to execute a HELP command
and help information is displayed, the RPG II editor returns the cursor to its current column and line so you can resume editing.

3.6.5 The INCLUDE Command
The INCLUDE command copies a text file into the source buffer using the VAX RPG II
editor. The format of the INCLUDE command is:
INCLUDE file-spec

The file is copied into the editing buffer, immediately before the current line. The cursor
position remains unchanged. Note that the lines read in are not syntax checked.

U sing the RPG II Editor

3-37

Ifthe INCLUDE is successful, the number of records read in is displayed on the message
line.

3.6.6 The QUIT Command
The QUIT command allows you to leave the RPG II editor and return to DCL command
level, without writing the editing buffer to the output file, as shown in the following
example:

12345678901234567890123456789012345678901234567890123456789012345678901234567890
* *** *--******
**
10H*++
20H* FUNCTIONAL DESCRIPTION:
30H*
This progra~ produces a report of ship~ents for various
40H*
products broken down b~ division and depart~ent using an
50H*
input file with the ship~ent data for the past 4 ~uarters.
60H*-70H
80FSHIPS IP F
DISK
41
90FSUMREP 0 F
98
LPRINTER
QTY
420
100E
110LSUMREP 55FL 500L
120ISHIPS AA 01
1 5 DIV L2
1301
6 7 DEPT L1
1401
8 16 PROD
1501
17 24 QTY
1601
170C*
XFOOTQTY
PROQTY 30
180C 01
DEPQTY 30
PROQTY
ADD DEPQTY
190C 01
Co~~and: QUIT

~----------------------

ZK-4351-85

The format ofthe QUIT command is:
QUIT [/SAVE]

Use the QUIT command if you have made no changes to the editing buffer or if you have
decided not to save the changes you made. If you have made changes, or if you have pressed

3-38

Using the RPG II Editor

keys to move the cursor past the last nonblank character in any line, the RPG II editor
displays the following message:
The current buffer MaY have been Modified, do YOU

really want to quit?

You can respond with Y, YE, or YES. Any other response will continue the editing session.
If you resume editing, ajournal file for your edits will not be created. To resumejournaling,
you must leave the RPG II editor, and invoke the RPG II editor again.
You can use the SAVE qualifier with the QUIT command to save the journal file, if one was
created.
If you have issued the RPG II editor COMPILE command and then leave the RPG II editor
by typing the QUIT command, the following message will be displayed in the message line:
Subprocess terMinated

3.6.7 The RESEQUENCE Command
The RESEQUENCE command either generates a new line number for each program
line in the editing buffer or resequences existing line numbers. The format of the
RESEQUENCE command is:
RESEQUENCE [/REMOVE] [initial-value [increment]]

The RESEQUENCE command renumbers program lines up to the first line containing the
delimiter /lblank or **blank in columns one through three. Lines are numbered beginning
at initial-value (default = 10) and incrementing by the increment value (default = 10).
The maximum line number is 99,999. If, during resequencing, a line number plus the
increment exceeds 99,999, that line and all remaining lines are numbered 99,999. In this
case, reissue the RESEQUENCE command with smaller values for initial-value and
increment.
The RESEQUENCE/REMOVE command will remove all line numbers in the editing
buffer.
The following command will renumber the line numbers in the editing buffer beginning
with 100 and increment each number by 20:
RESEQUENCE 100 20

See Section 3.8.2 for another example ofthe RESEQUENCE command.

Using the RPG II Editor

3-39

3.6.8 The SET Command
The SET command controls RPG II editor options. Once set, these options are in effect
until you leave the RPG II editor or reissue the SET command.
You can include SET commands in a startup command file. See Section 3.7.2 for
information.
The format of the SET command is:
SET option

RPG II editor options include:
• COMMAND
• DEFAULT
• HELP
• RULER
• SCROLL
• SECTION
• STARTCOLUMN
• SYNTAXCHECK
3.6.8.1 The COMMAND option
The COMMAND option allows you to process additional startup command files at the
beginning of the RPG II session. The format of the COMMAND option is:
SET COMMAND file-spec

See Section 3.7.2, Startup Command Files, for information on the SET COMMAND
option.
3.6.8.2 The DEFAULT option
The DEFAULT option allows you to determine the default value of qualifiers used in other
editor commands. The format of the DEFAULT option is:
SET DEFAULT option

For example, the command:
SET DEFAULT PAGE,PRDMPT

means that any later HELP command uses the PAGE and PROMPT options by default.
You can turn defaults off by using the negated form of a qualifier. (For example, SET
DEFAULT NOPROMPT.)

3-40

Using the RPG II Editor

3.6.8.3 The HELP option
The HELP option allows you to choose a variety of settings. The format ofthe HELP option
is:
SET HELP {KEYPAD I NONE I SPECIFICATIONS}

The HELP KEYPAD option acts as if you used the HELP_KEYPAD function (default =
PF2). See Section 3.5.2 for information on HELP_KEYPAD.
The HELP NONE option allows you to start up as if you have used the DISPLAY function.
See Section 3.5.11 for information on DISPLAY.
The HELP SPECIFICATIONS option acts as if you used the HELP_SPECIFICATIONS
function (default = PFI/PF2). See Section 3.5.3 for information on
HELP _SPECIFICATIONS.
3.6.8.4 The RULER option
The RULER option moves the three-line 80-column ruler with tab stops as a unit, to either
the top or bottom of the current window. SET RULER NONE removes the ruler from the
screen.

The format of the RULER option is:
SET RULER {TOP I BOnOM I NONE}

Using the RPG II Editor

The example below shows an editor screen as it appears after a SET RULER BOTTOM
command, with an I8-line terminal page size. The next example shows the same screen
followed by a help request.

r--I

FSHIPS IP F
41
FSUMREP 0 F
98
QTY
E
LSUMREP 55FL 500L
ISHIPS AA 01
I
I
I
I

C*
C 01
C 01
c*

PROQTY

XFOOTQTY
ADD DEPQTY

DISK
LPRINTER
4 2 0
1 5 DIV L2
6 7 DEPT L1
8 16 PROD
17 24 QTY
PROQTY 30
DEPQTY 30

o I 1 I 2 I 3 I 4 I 5 I 6 I 7
12345678901234567890123456789012345678901234567890123456789012345678901234567
**

****** ....

~-------------~

ZK-4352-85

3-42

Using the RPG II Editor

PF1/PF2 - RPG II specification for~ats
+-------+-------+-------+-------+
Press the PF1/KP7 ke~ and t~pe HELP for
I Gold I Help IFnx FndlDIL UdLI
infor~ation on co~~ands and functions.
+-------+-------+-------+-------+
For help on a specific ke~, press the
IPag C~dlSec DsplRev HovlDIF UdFI
PF2 ke~ folloNed b~ the ke~ for Nhich
+-------+-------+-------+-------+
~ou Nant help infor~ation.
IAdv BotlBck ToplCut PaslShL ShRI
Other keMs: BS_KEY
DEL_KEY
+-------+-------+-------+-------+
TAB_KEY
UP, DOWN, LEFT, RIGHT IFld
IEol DEIIChr Coil
CTRL_R_KEY CTRL_W_KEY
+-------+-------+-------+Ent
CTRL_U_KEY CTRL_Z_KEY
I
Lin OpL
ISel Resl
+---------------+-------+-------+
I
I
6 7 DEPT L1
I
8 16 PROD
011
12
1314
1516
I
7
12345678901234567890123456789012345678901234567890123456789012345678901234567

* *** *---

*---

.**---*---**

* * * * * * ....

-~---------

ZK-4353-85

3.6.8.5 The SCROLL option
The SCROLL option specifies the region within the editing window where the cursor will
stay.
The format of the SCROLL option is:
SET SCROLL [top-offset [bottom-offset])

Top-offset is the number oflines from the top of the editing window to the top of the scrolling region. Bottom-offset is the number oflines from the bottom ofthe scrolling region to
the bottom of the editing window. If bottom-offset is omitted, the current offset from the
bottom is not changed. If the top and bottom offsets are omitted, both offsets are set to the
initial editor defaults of zero.

Using the RPG II Editor

3-43

If you enter SET SCROLL 01, then the cursor will move from the line next to the ruler on
the top, to within one line above the bottom ofthe editing window. If you want to keep the

cursor from hitting the top line, enter a number greater than zero for top-offset. The higher
the number, the greater the number of source code lines that will remain on the screen
between the cursor and the top or bottom of the editing window.
3.6.8.6 The SECTION option
The SECTION option specifies the number oflines the RPG II editor will move the cursor
(forward or backward) when the SECTION function (default = KP8) is used and there is
no help information displayed. You can specify any value between one, and five less than
the terminal page length. By default, the bottom line of the editing window moves to the
top (just under the tab stops), regardless ofthe size ofthe window.
The format of the SECTION option is:
SET SECTION lines

If you specify a SECTION value other than the default, the SECTION value, when help is
displayed, is proportional to the visible number oflines in the editing window.
3.6.8.7 The STARTCOLUMN option
The STARTCOLUMN option specifies the current column for the following functions:
• NEW_LINE
• OPEN_LINE
• LINE
• PAGE
The format of the STARTCOLUMN option is:
SET STARTCOLUMN column

The default value is column 7. When the setting for the STARTCOLUMN qualifier is
greater than 6, the RETURN key and OPEN_LINE (default = PFlIKPO) function supply
the same specification type in column 6 as is present in the current line.
3.6.8.8 The SYNTAXCHECK option
The SYNTAXCHECK option specifies that syntax checking and automatic rightjustification of numeric fields will occur.
The format of the SYNTAXCHECK option is:
SET SYNTAXCHECK {ON I OFF I PROMPT}

3-44

Using the RPG II Editor

By default, the RPG II editor starts up with the SYNTAXCHECK option on. This setting
can be changed in a startup command file, or interactively.
If you modify a line when syntax checking is on, and then attempt to move off the line, one
of the following will occur:
• If there are no errors on the line, and all numeric entries are properly justified, the
requested action takes place.
• If there are no errors on the line, but one or more numeric entries are not properly
justified, the numeric entries are justified, the justified fields are highlighted, and the
requested action takes place. The highlighting is removed from the field(s) when the
next line is syntax checked.
• If a syntax error is detected, the requested action does not take place. The cursor is
positioned at the column of the error, and the error message is displayed on the message line. You can either correct the error, or ignore the error by immediately moving
off the line. Another syntax check will take place on that line only if you modify it
again.
If you enter table and array data while SYNTAXCHECK is on, there is a risk that the data
will be right-justified as ifit were part ofthe source program, yielding unexpected results.
Therefore, it is recommended that SYNTAXCHECK be set off while entering table and
array data, or that you use the PROMPT option. When PROMPT is in effect, the editor will
highlight any proposed numeric right justification before the justification is actually done,
and will prompt you to see if you want it done.

3.6.9 The SHOW Command
The SHOW command displays the current settings for the following options:
• DEFAULT
• SCROLL
• SECTION
• STARTCOLUMN
• SYNTAX CHECK
• VERSION
The format ofthe SHOW command is:
SHOW option

Using the RPG II Editor

3-45

The current settings appear in the message line, as shown in the following examples:
COMMAND: SHOW DEFAULT PAGE,PROMPT
Current defaults are NOPAGE,NOPROMPT
COMMand: SHOW SCROLL
Scroll offset froM top is 0, froM bOttoM is

COMMand: SHOW SECTION
Section length is: 18 or when HELP is displayed: 7
COMMand: SHOW STARTCOLUMN
STARTCOLUMN value is; 7
COMMand: SHOW SYNTAXCHECK
SYNTAXCHECK is ON

The VERSION qualifier displays the current version of the RPG II editor and a VAX
RPG II copyright statement, as shown in the following example:
COMMand: SHOW VERSION
VAX RPG II V2.0 editor

3.6.10 The SUBSTITUTE Command
The SUBSTITUTE command allows you to substitute text using the VAX RPG II editor.
The format of the SUBSTITUTE command is:
SUBSTITUTE search-argument replace-argument [/SELECTl [/QUERYl

The SUBSTITUTE command replaces all occurrences of the search-argument with the
replace-argument in the specified range. If SELECT is specified, the command applies to
all lines in the select range. Otherwise, it applies to all lines in the buffer.
Only exact matches of the search-argument with text in the editing buffer are performed.
Only equal length substitutions are performed. If one argument is shorter than the other,
it is padded on the right with spaces before searching and replacing begins.
If you specify QUERY, then at each occurrence of the string to be substituted the following
occurs:
• The string to be substituted is highlighted.
• A "Substitute this occurrence (YES, NO, ALL, or QUIT)? "prompt is displayed on the
prompt line.
• You may answer YES, NO, ALL, or QUIT.
• If you answer YES, the text is replaced and the editor finds the next occurrence.
• If you answer NO, the text is not replaced and the editor finds the next occurrence.

3-46

Using the RPG II Editor

• If you answer ALL, the current text is replaced as well as any further occurrences of
the text, without additional prompting.
• If you answer QUIT, the text is not replaced and the SUBSTITUTE command
terminates.
• If you make any other response, the above sequence is repeated from the point where
the prompt message is displayed.

IfSYNTAXCHECK is on, the current line is syntax checked after each change is made. If a
syntax error is found, the substitution is terminated.
The command does not display the lines in which substitutions are made (except in
QUERY mode).
Upon completion of this command, the message "Substitutions: n" is displayed in the
message area, where 'n' indicates the number of substitutions performed.
Upon completion of this command when SELECT was specified, the select range is
removed.
The SUBSTITUTE command ignores the current editing direction. It always proceeds
from the beginning ofthe range to the end. The current editing direction is not changed, it
is just ignored for the duration of the command.
The cursor is returned to where it was before the command was issued.

Rules for specification of search-argument and replace-argument
• The search-argument must contain at least one non-blank character. Ifit does not, the
message "The search string must contain at least one non-blank character" is displayed in the message area.
• If lowercase characters are desired in the substitution, the argument must be
enclosed within double quotation marks (for example, "string"). Otherwise, lowercase
characters are converted to uppercase.
• If the argument contains a terminator, such as a blank space or a slash (I), the argument must be enclosed within double quotation marks (for example, " " and "I").

• If the argument contains a double quotation mark, two double quotation marks must
be entered.
• Single quotation marks are not treated like double quotation marks.
• Control characters cannot be entered in arguments.

Using the RPG II Editor

3-47

3.7 Customizing the Editor
This section discusses several RPG II editor commands that are available to you. These
commands enable you to customize your editing environment.

3.7.1 Using Editor Commands
For the purpose ofthis example, assume that you want the ruler to lie on the bottom of the
screen and the keypad help to show in the help window. Because you are entering a program with a compile-time table or array, you would like to be prompted before any numeric
fields are right-justified. Because you have chosen a small scrolling region, you would like
the SECTION function to give you 10 lines. Finally, you would like to use CTRLlP to
review errors.
You would use the COMMAND function (default = PFlIKP7) to enter each ofthe following commands:
SET RULER BOTTOM
SET SCROLL 2 2
SET SECTION 10
SET ~lELP KEYPAD
SET SYNTAXCHECK PROMPT
DEFINE KEY CTRL_P_KEY REVIEW_ERROR

See Section 3.6.8 for an example of a screen with the ruler on the bottom and the keypad
help displayed.

3.7.2 Startup Command Files
Startup command files allow you to specify a set of commands to be executed automatically
each time you begin an editing session. A startup command file can contain any ofthe VAX
RPG II editor commands. It can also contain comment and blank lines to improve readability. Each command is executed as if the COMMAND function were used.
The editor uses the COMMAND qualifier to find a startup file. This qualifier is present by
default, with a default value of RPGINI.
The uses of the COMMAND qualifier and their effects are:
• If COMMAND = filespec is used, the specified file is executed.
• If just COMMAND or if no COMMAND qualifier is used, the editor looks for the file
RPGINI. Iffound, it is executed.
• If INOCOMMAND is used, no command file is executed.

All startup files are opened with a default file type of RPG. The value for the COMMAND
qualifier can be a full or partial filespec, or a logical name that translates to a filespec.

3-48

Using the RPG II Editor

Control can be passed from one startup file to another by using the COMMAND option of
the SET command. When the editor is executing commands from a startup command file
and encounters a SET COMMAND command, it tries to find the associated file, translating logical names if necessary. If a file is found, the contents ofthat file are then executed in
the same way as the original startup file. The rest ofthe commands in the startup file are
not executed. If the file is not found, the rest of the commands in the startup file are
executed.
Following are several ways of using these options to customize your editing environment.
If you do not want to execute any startup file, your command line should look like this:
RPG/EDIT/NOCDMMAND file-spec

To execute your own startup commands, create a file of editor commands and define the
logical name RPGINI to reference it. For example, if you create the file MYSTARTUP.RPG
to contain:
SET DEFAULT PAGE.PROMPT
SET HELP KEYPAD
SET RULER NONE
DEFINE KEY CTRL N KEY REVIEW ERROR

and add to your LOGIN.COM the following:
S DEFINE RPGINI MYDISK:[MYDIRECTORYJMYSTARTUP.RPG

then, whenever you invoke the editor, your commands will be executed.
One way to establish a customized environment for many users at once is described here. A
system-wide startup command file can be established by defining the logical name
RPGINI in the system logical name table. Suppose that the following file exists with the
filename SYSRPGINI.RPG in the directory addressed by SYS$PUBLIC:
! System-wide startup commands
SET HELP SPECIFICATIONS
SET RULER BOTTOM
SET COMMAND RPGINI.RPG

If RPGINI was defined by:
S DEFINE/SYSTEM RPGINI SYSSPUBLIC:SYSRPGINI.RPG

then by default, all users on the system would have that set of commands executed automatically. The last command shown would mean that after executing the system-wide
commands, the editor would also execute any commands found in the file RPGINI.RPG in
the default directory.

Using the RPG II Editor

3-49

3.7.3 Modifying Screen Length
You can determine the number oflines on the terminal screen that are used by the RPG II
editor. This is a useful option for a variety of reasons. If you have a terminal in the VT100
family that does not have Advanced Video Option, you have only 14 lines when in 132
column mode. It is also useful if you have a terminal with more than 24 lines. Also, if you
have a terminal that runs at a slow baud rate, you can control the number of lines displayed on the editor screen. This would improve performance over a slow communication
line by decreasing the number of lines on the screen that must be kept updated during an
editing session.
Use the DeL command SET TERMINAL/PAGE = n to set the length of the page on your
terminal screen. You can also set the width of the page with SET TERMINAL/WIDTH = n.
If you set the width to 132 columns, you will get the full text of the editor error messages.
Note that there must be at least six lines on the screen, to allow for the two line ruler, tab
stop line, prompt line, message line, and one line in the source editing window.

3.8 Creating and Editing Programs
This section contains a sample RPG II program and some of the output it might produce.
Section 3.8.1 shows you how to create a program using the RPG II editor, and Section 3.8.2
shows you how to use the RPG II editor to edit a program. Both sections use the sample
program shown here.

3-50

Using the RPG II Editor

Note that this example assumes a 24-line screen and no startup file.

011
I
2
I
3
I
4
I
5
I
6
17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
H*++

H* FUNCTIONAL DESCRIPTION:
H*
This progra~ produces a report of ship~ents for various
H*
products broken dONn b~ division and depart~ent using an
H*
input file Nith the ship~ent data for the past 4 quarters.
H*-H

FSHIPS IP F
FSUHREP 0 F

41
98

QTY

lSUHREP 55Fl 500l
ISHIPS AA 01

DISK
lPRINTER
420
1

I
I
I
I

5 DIV

6 7 DEPT L1
8 16 PROD
17 24 (UY

C*
C 01
C 01
C*
Cll
Cll
~

PROQTY
DEPQTY
DIVQTY

XFOOTQTY
ADD DEPQTY

PROQTY 30
DEPQTY 30

ADD DIVQTY
Z-ADDO
ADD FINQTY

DIVQTY 30
DEPQTY
FINQTY 40

----------------------

ZK-4354-85

Using the RPG II Editor

3--51

12345678901234567890123456789012345678901234567890123456789012345678901234567890

OSUMREP H 001
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

"'---J

3-52

H 02

H 2

D 1

01
L2
L1

T 1
T 0

T 0

T 02

T 0

Using the RPG II Editor

48 'PRODUCT SHIPMENT REPORT'
UDATE Y

12
-48 'PRODUCT SHIPMENT REPORT'
42 'SHIPMENTS'
15 'DIVISION DEPT'
24 'PRODUCT'
48 'IU Q2 Q3 Q4 TOTAL'

DIV
DEPT
PROD

8
14

IHY

Z
PROQTYZ

25
41
48

DIV

DIVQTYZB 48
63 '<== Total for'
DIV
69
fINQTY1

48
65 '<== GRAND TOTAL'

~
ZK-4355-85

A sample of the output from this program might appear as follows:
0
1
2
3
1I
5
6
7
123115678S0123115678S0123115678S0123115678S0123115678S0123115678S0123115678S0123115678S
0
S/OS/85

PRODUCT SHIPMENT REPORT

DIVISION

DEPT

East

SHIPMENTS
TOTAL
03 Oll

CPU-1S
CPU-20

12
11

13
11

TERM-12
TERM-13
TERM-20

12
23
11

311
211
12

25
13

PRODUCT

111
311

15
10

511
1I3

35
26

115
S8
50

111

360
No rt h

211

oISK-1I5
DISK-1I8
DISK-60

18
12
10

TAPE-12
TAPE-13
TAPE-32
TAPE-33

8
1
10

7
2
10

111
10

15
20
10
6

1I
10
1I

ill

611

35
11

3
11
11
5

211
18
1I1
17

MEMORY-ll
MEMORY-16
MEMORY-17

lS
lS
12

20
18
13

21
17
13

21
16
12

1I0

SoFT-12
SoFT-lli
SoFT-23

11
6
13

13
7

SoFT-211
SoFT-25

15
3

<== Total

for No rt h

(== Total

for South

81
70
50
201

West

Total for East

1I1

286
South

{==

111

13
8
20

12
8
lS

liS
2S
66

111
3

111
1I

13
7

56
17
217

1,0611

<== Total fa r West

(== GRAND TOTAL

Using the RPG II Editor

3-53

3.8.1 Creating a New Program
Invoke the RPG II editor by typing the following command:
$

RPG/EDIT MYFILE

The RPG II editor displays the following message:
File not found

The following screen is displayed:

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

DEOBl

Press the PF2 ke

et hel

information

~--------------~

ZK-4356-85

Although RPG II does not require a Control specification, it is useful to place an asterisk in
column 7 of a Control specification to include a comment describing what your program
does_ Press either the TAB key or the RIGHT key repeatedly to move the cursor to column
6_ Enter H in column 6. Use the HELP_SPECS function (default = PFlIPF2) to display
the specification format for the Control specification. Because the current line is a Control

3-54

U sing the RPG II Editor

specification, the RPG II editor automatically displays the tab stops for the Control specification. Help information will be displayed in the help window ofthe RPG II editor screen,
as shown in the following example:

Currenc~ s~lIIbol

Inverted print (DIJ)
I
Alternate collating sequence (SE)
I I
I
IP forllls position (1)

I
I

I
I
I
I
I
I
011
12
13
I
4
I
5
I
6
17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
H

*...

•

*. *.
I

••

•

••••••••••

*.......

•• I

•

•••••••

••

•••

[EOB1 HI

~~----------~~

ZK-4357-85

Enter an asterisk (*) in column 7. Type the description ofthe program. Press the RETURN
key at the end of each line. After the RETURN key is pressed, the RPG II editor moves the
current line on the screen one line up, if necessary; automatically enters H in column 6;
and moves the cursor to column 7. (Column 7 is the default setting for the SET
STARTCOLUMN command.) To display the current default for the SET STARTCOLUMN

Using the RPG II Editor

3-55

command, issue the COMMAND function (default = PFlIKP7), type SHOW
STARTCOLUMN, and press the RETURN key, as shown in the following example:

Currenc!:j s!:jlllbol
I Inverted print (DIJ)
I I
Alternate collating sequence (SE)
I I
I
1P forllls position (1)
I
I

I
I

011
12
13
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

*.......
H*++

.*.

1*1"

.1 .. I t • • • • • • • • • •

*....

I . 1.1 • • • • • • I I . I

II I

•• I

I. I. I

•••

H* FUNCTIONAL DESCRIPTION:
H*
This progralll produces a report of shiplllents for various
H*
products broken down b!:j division and departlllent using an
H*
input file with the shiplllent data for the past 4 quarters.
H*--

[EOBl

<PFlIKP7)

Command: SHOW STARTCOLUMN
START COLUMN value is: 7

"---

--------------~

ZK-435B-B5

The specification type for the current line will be duplicated until you enter a new specification type in column 6. H is automatically entered in column 6 and the cursor is moved to
column 7. The next specification needed is the File Description specification. To replace H,
move the cursor to column 6 by using the FIELD_BACKWARD function (default =
BS-KEY), and enter F (File description).
Enter the name of the file, beginning in column 7, and then use the FIELDJ'ORWARD
function, hereafter referred to by its default setting, TAB-KEY. Since help information is

3-56

Using the RPG II Editor

displayed in the help window of the RPG II editor screen, once TAB_KEY or any terminator is pressed, the RPG II editor displays the specification format and tab stops for the File
Description specification, as shown in the following example:

Mode (LR)
IKe!:f length
Addtn(AU)
T!:fpe (lOUD) I I Record address t!:fpe (API)
IDes (PSRCTD) I I IOt'ganization (IT,i-9)
IExpand
IIEOF (E)
II IIOvet'flow indicatot'
IIShare
I I ISeC! (AD) I I I I I KeH Iocat i on
III Rewnd
1IIIFI1lt (FV) II III I Extension (EU
File
"I I
nal1le
1IIIIBIk Rec II III I IDevice S!:fl1lb Tape Core III IFile
I
I I I I II en Ien I I I I I I Icode dev 1abe I index III Icond
FI
I
I "I
I I I 5
o I 1"""I I2 ""I
I
3
4
I
6 "I "I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
**
******---*---**-*** *---**
*
*.••... *-----***.**
HH+

H* FUNCTIONAL DESCRIPTION:
H*
This progral1l produces a report of shipl1lents for various
H*
products broken down bH division and departl1lent using an
H*
input file with the shipl1lent data for the past 4 C!uarters.
H*-H

[EOBl

FSHIPS

~~-------------~
ZK-4359-85

Using the RPG II Editor

3-57

Remember, you can press TAB-KEY to move the cursor to the next tab stop. Enter the rest
of the File Description specifications as shown in the following example:

File
naJlle
I

Mode (LR)
IKe~ length
T~pe (lOUD)
I I Record address t~pe (API)
Addtn(AU)
IDes (PSRCTD)I I IOrganization (IT,i-9)
IExpand
IIEOF (E)
I I IIOverflow indicator
I IShare
I I ISe~ (AD) I I I II Ke~ location
III Rewnd
1IIIFJllt (FV) II III I Extension (El)
III I
I I I I IBlk Rec II I I I I IDevice S~Jllb Tape Core III IFile
1IIIIIen len II III I Icode dey label index III Icond
IIIIII
I II III I II
I
I
I
III II

011
12
I
3
I
4
I
5
1617
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

******---*---**-*** *---**
**
* *.. *-----***,*.
H* FUNCTIONAL DESCRIPTION:
This prograJII produces a report of shipJllents for various
H*
products broken down b~ division and departJllent using an
H*
input file with the shipJllent data for the past 4 ~uarters.
H*
H*-1

FSHIPS IP F
FSUMREP o F

[EOB]

•••

DISK
LPRINTER

~~------------~

ZK-4360-85

3-58

U sing the RPG II Editor

Replace F in column 6 with E (Extension). Press TAB_KEY. The RPG II editor displays the
specification format and tab stops for the Extension specification. Then, enter the rest of
the entries for the Extension specification, as shown in the following example:

------F = For~at (PB)
I -----D = Deci~al positions
I I ----S = Sequence (AD)
III
III Alternating table 01' al'I'a~
Fro~
Table EntEnt Lenillna~e Len
To
01'
file
file
perin of Fill
of F
na~e
na~e
EntlD
al'ra~ RecTbl Ent IDII
I
I
na~e
I I I II SI
I liS
E
I
I
I
I I I 1111
I I I I+-- Co~~ents ---+
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
*.... *
*
*
*--*---*--****
*--****
H*
This progra~ produces a report of ship~ents for various
H*
products broken down b~ division and depart~ent using an
H*
input file with the ship~ent data for the past 4 quarters.
H*-FSHIPS IP F
41
DISK
FSUHREP o F
98
LPRINTER
(HY
E
420
[EOBl

-------------------------

Using theRPG II Editor

ZK-4361-85

3-59

Enter L (Line Counter) in column 6. Then, enter the rest of the entries for the Line Counter
specification, as shown in the following example:

Forlll length (1-112)
I FL (if Forlll length used)
I I Overflow line nUlllber (1-112)
I
I I I OL (if Overflow line used)
I I I I
LI
o
I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
File
nallle

*--* *--* .
**
products broken down b~ division and departlllent using an
H*
input file with the shiPlllent data for the past 4 ~uarters.
H*
H*-I

FSHIPS IP F
FSUMREP o F
E

LSUMREP

[EOB]

•••

••

••••

•••

41
98

DISK
LPRINTER

tlTY

420

55FL 500L

••••

••

••••••

••

•••••••

~~------------~
ZK-4362-85

3-60

Using the RPG II Editor

Enter the Input specifications, as shown in the following example:

File
naPle
I
II

Sequence (AA-ZZ, 01-99)
I NUPlber (i-N)
DeciPlal positions
I 10ptionai (0)
I I IRecord identif~ing indicator
Contro I Ieve I
I
I Hatch field
I III
I
I I Fld rec rei
I III + Identif~ing codes + ForPlat I
I I (PB)
I III I
IFieid I I I
I III I
C
C
CI IFieid InaPle I I I Field
I III I
Z
ZI Ilocationil
I I I indicatrs
Z
I I I+- 0
I III Pos NDcPos NDcPos NDc IFr To II
1
I
2
131
4
I
5
I
6
I
7

o I
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

LSUHREP 55FL 500L
ISHIPS AA 01
I
I
I
I

*---

QTY

*---

.**---*---**

420

******

1 5 DIV L2
6 7 DEPT L1
8 16 PROD
17

24 QTY

[EOB]II

~~------------~
ZK-4363-85

Using the RPG II Editor

3-61

Use the DISPLAY function (default = PFlIKP8) to display the program on the entire
screen (except lines 1 through 3, 23, and 24), as shown in the following example:

011
12
I
3
I
4
15
I
5
171
12345578901234557890123455789012345578901234557890123455789012345578901234557890

H*++

* *** *---

******

H* FUNCTIONAL DESCRIPTION:
H*
This progra~ produces a report of ship~ents for various
H*
products broken down b~ division and depart~ent using an
H*
input file Nith the ship~ent data for the past 4 quarters.
H*-FSHIPS IP F
41
DISK
FSUMREP 0 F
LPRINTER
98
E

LSUMREP 55FL 500L
ISHIPS AA 01

QTY

I
I
I
I

420

1 5 DIV L2
6 7 DEPT L1
8 16 PROD
17

24 QTY

[EOB]

~~------------~~
ZK-4364-85

3-62

Using the RPG II Editor

Enter the Calculation specifications without displaying the specification format in the
help window, as shown in the following example:

011
12
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
*--*** * * *
*
** *
*
*
*
H*-DISK
FSHIPS IP F
41
LPRINTER
FSUMREP 0 F
98
QTY
4 20
E
LSUMREP 55FL 500L
ISHIPS AA 01
I
1 5 DIV L2
6 7 DEPT L~
I
8 16 PROD
I
17 24 QTY
I
C*
PROQTY 30
XFOOTQTY
C 01
PROQTY
DEPQTY 30
ADD DEPQTY
C 01
C*
DEPQTY
DIVQTY 30
ADD DIVQTY
CLi
DEPQTY
Z-ADDO
CLi
DIVQTY
FINQTY 40
ADD FINQTY
CL2
C*
[EOB]

~
ZK-4365-85

U sing the RPG II Editor

3-63

Enter the Output specifications. Note that the RPG II editor screen can display only 19
source lines at a time, when the terminal has 24 lines and when the ruler is displayed.
Once you enter more than 19 lines, the RPG II editor moves the editing window up.

o I 1 121 3 I 4 I 5 I 6 171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
**

***** * *

OSUMREP H 001

0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

H 02

***---**
48 'PRODUCT SHIPMENT REPORT'

1P
UDATE Y

H 1

H 2

D 1

01
L1

T 1

12
48 'PRODUCT SHIPMENT REPORT'
42 'SHIPMENTS'
15 'DIVISION DEPT'
24 'PRODUCT'
48 'Q1 Q2 Q3 Q4 TOTAL'

DIV
DEPT
PROD
QTY Z
PROQTYZ

8
14

25
41
48

---------------~

ZK-4366-85

3-64

Using the RPG II Editor

Enter the rest of the Output specifications. Use the EXIT function (default =
CTRL_Z_KEY) to save the contents of the editing buffer and leave the RPG II editor.
When EXIT is used, the RPG II editor displays the following message:
45 records written to file MYDISK:[MYDIRECTORYlMYFILE.RPG;l

This is shown in the following example:

011

1516

12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

H 02

H 2

D 1

01
L1

T 1
T 0

***---**

UDATE Y

12
48 'PRODUCT SHIPMENT REPORT'
42 'SHIPMENTS'
15 'DIVISION DEPT'
24 'PRODUCT'
48 'Q1 Q2 Q3 Q4 TOTAL'

DIV
DEPT
PROD
QTY Z
PROQTYZ

8
14

25
41
48

FINQTY1

48
65 '(== GRAND TOTAL'

45 records written to file MYDISK:[MYDIRECTORY1MYFILE,RPG;1

~---------------------

Using the RPG II Editor

ZK-4367-85

3-65

3.8.2 Editing an Existing Program
When you invoke the RPG II editor to edit the program created in Section 3.8.1, the RPG II
editor displays the following message:
45 records read froM file MYDISK:[MYDIRECTORYlMYFILE.RPG;l

And the following screen is displayed:

o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
II

*.....

H*++

.* .. *.. .*.
I

1'1

••

••••

*.......

I.'

••••••••••••••••

H* FUNCTIONAL DESCRIPTION:
H*
This program produces a report of shipments for various
H*
products broken down b~ division and department using an
H*
input file with the shipment data for the past 4 quarters.
H*-H

FSHIPS IP F
41
DISK
FSUMREP 0 F
98
LPRINTER
E
QTY
4 20
LSUMREP 55FL 500L
ISHIPS AA 01
I
1 5 DIV L2
I
6 7 DEPT L1
I
8 16 PROD
I
17 24 QTY
C*
C 01
XFOOTQTY
PROQTY 30
C 01
PROQTY
ADD DEPQTY
DEPQTY 30
Press the PF2 v.e to et hel

information

~~-----------~

ZK-4368-85

3-66

Using the RPG II Editor

In this session, the control-level indicator L2 needs to condition the DIV field in the detail
record Output specification. Use the FIND function (default = PFlIPF3) to locate DIY.
The RPG II editor displays the command prompt "Search for: ". Enter the search string
DIV and press the ENTER key, as shown in the following example:

011
12
I
3
I
4
I
5
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
*1 • • • • • •

•

1*' •

H*++

*.... *...

••• I

••••••

••• I.

••

••• ,

••• I

••••••• I

••••••

H* FUNCTIONAL DESCRIPTION:
H*
This progra~ produces a report of ship~ents for various
H*
products broken down b~ division and depart~ent using an
H*
i npu t file '" i th the sh i p~ent data f or the past 4 quarters.
H*-H

FSHIPS IP F
FSUHREP 0 F
E

LSUHREP 55FL 500L
ISHIPS AA 01

41
98

&ITY

DISK
LPRINTER
420

I
I

8
17

C*
C 01
C 01

Search for: DIV

PRO&lTY

XFOOT&lTY
ADD DEP&lTY

5 DIV

7 DEPT L1

16 PROD
24 &ITY

PRO&lTY 30
DEP&lTY 30

~~------------~
ZK·4369-85

Using the RPG II Editor

3-67

The RPG II editor responds by moving the cursor to the first character of the first occurrence of the search string DIV (see the comment line), as shown in the following example:

011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

*..........

'*1'*'"

.1 ... 1 1 1 1 1 1 1 "

••

*..

111 • • • • 1 • • • 1 " ' 1 III • • • • • • • I I . "

H*++
H* FUNCTIONAL DESCRIPTION:
H*
This program produces a report of shiproents for various
H*
products broken dONn b~ ~ivision and departroent using an
H*
input file Nith the shiproent data for the past 4 quarters.
H*-H

FSHIPS IP F
41
FSUHREP 0 F
98
E
QTY
LSUHREP 55FL 500L
ISH IPS AA 01
I

I
I
I
C*

C 01
C 01

PROQTY

XFOOTQTY
ADD DEPQTY

DISK
LPRINTER
4 2 0
1 5 DIV L2
6 7 DEPT L1
8 16 PROD
17 24 QTY

PROQTY 30
DEPQTY 30

ZK-4370-85

Using the RPG II Editor

Because this is not the correct string, use the FIND_NEXT function (default = PF3). The
RPG II editor moves the cursor to the first character of the next occurrence of the string
DIV, as shown in the following example:

011

12345678901234567890123456789012345678901234567890123456789012345678901234567890
* *** *--**
******
H*++

H* FUNCTIONAL DESCRIPTION:
H*
This progra~ produces a report of ship~ents for various
H*
products broken down b~ division and derart~ent using an
H*
input file with the ship~ent data for the past 4 quarters.
H*-H

FSHIPS IP F
FSUMREP 0 F
E

98
QTY

LSUMREP 55FL 500L
ISHIPS AA 01

1 5 iillV
L2
6 7 DEPT L1
8 16 PROD
17 24 QTY

I
I
I
I

C*
C

PROQTY

DISK
LPRINTER
420

XFOOTQTY
ADD DEPQTY

PROQTY 30
DEPQTY 30

~--------------~

ZK-4371-85

Using the RPG II Editor

3-69

Again, this occurrence of the string DIV is not correct, so issue the FIND_NEXT function
five more times to move the cursor to the correct occurrence. You could have specified DIV
and a blank as the search string to avoid duplicating key strokes. L2 must be entered in
columns 24 and 25. To do this, move the cursor to column 24 by pressing the BS_KEY to
column 23, then use the RIGHT function (default = RIGHT) once. Enter the string L2 in
columns 24 and 25, as shown in the following example:

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

***---**

DEPQTY 30

C*
CLi
DEPIHY
ADD DIVQTY
CLi
Z-ADDO
ADD FINQTY
CL2
DIVIHY
C*
OSUMREP H 001 1P

DIVQTY 30
DEPQTY
FINQTY 40

o
o
o
o
o
o
o
o
o
o
o
o

PROIHY

ADD DEPQTY

H 02

H 1

H 2

D 1

01
L21

UDATE Y

48 'PRODUCT SHIPMENT REPORT'
12
48 'PRODUCT SHIPMENT REPORT'
42 'SHIPMENTS'
15 'DIVISION DEPT'
24 'PRODUCT'
48 'Q1 Q2 Q3 Q4 TOTAL'

DIV

~----------------------

3-70

Using the RPG II Editor

ZK-4372-85

Number the program lines for reference by issuing the COMMAND function (default =
PFlIKP7) and typing the RESEQUENCE command, as shown in the following example:

011
I
2
I
3
I
4
I
5
16
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
***---**
**
***** * *
*
DEPQTY 30
190C 01
PROIHY
ADD DEPQTY
200C*
DEPQTY
DIVQTY 30
ADD DIVQTY
210CL1
DEPQTY
220CL1
Z-ADDO
FlNQTY 40
DIVQTY
230CL2
ADD FlNQTY
240C*
2500SUMREP H 001 lP
48 'PRODUCT SHIPMENT REPORT'
2600
2700
H 02
1P
UDATE Y 12
2800
48 'PRODUCT SHIPMENT REPORT'
2900
1P
3000
H 1
42 'SHIPMENTS'
3100
1P
3200
H 2
15 'DIVISION DEPT'
3300
24 'PRODUCT'
3400
48 'Q1 Q2 Q3 Q4 TOTAL'
3500
3600
D 1
01
DIV
8
L2t1
3700
Command: RESEQUENCE

~-------------~

ZK-4373-85

Using the RPG II Editor

3-71

Use the SECTION function (default = KP8) to move the cursor the number oflines set by
the SET SECTION command, as shown in the following example:

011

12345678901234567890123456789012345678901234567890123456789012345678901234567890

2800
2900
3000
3100
3200
3300
3400
3500
3600
3700
3800
3900
4000
4100
4200
4300
4400
4500
[EOB]

***** * *

H 1

H 2

D 1

01
L2
L1

T 1
T 0

12
48 'PRODUCT SHIPMENT REPORT'
42 'SHIPMENTS'

L1
LR

15 'DIVISION DEPT'
24 'PRODUCT'
48 'I;!! Q2 Q3 Q4 TOTAL'
DIV
DEPT
PROD
QTY Z
PROQTYZ

8
14
25

FINQTY1

48
65 '(== GRAND TOTAL'

Attem t to move

***---**

UDATE Y

ast end of buffer

~-----------~~

ZK-4374-85

3-72

Using the RPG II Editor

Enter two Output specifications between lines 420 and 430 by using the following
functions:
1.

UP (default = UP) to line 430

OPEN_LINE (default = PFlIKPO) to create a new line

Use the OPEN_LINE function to create a line preceding the current line. The RPG II editor automatically places the specification type of the current line in column 6 and moves
the cursor to column 7. Enter the new specifications, as shown in the following example:

011
1213
I
4
1516
I
7
I
1234567890123456789012345678901234567890123456789012345678901234567890123456789

2900
3000
3100
3200
3300
3400
3500
3600
3700
3800
3900
4000
4100
4200
0
0
4300
4400
4500

***** * *
H 1

H 2

D 1

01
L2
L1

T 1
T 0

T 0

***---**

48 'PRODUCT SHIPMENT REPORT'
42 'SHIPMENTS'

15 'DIVISION DEPT'
24 'PRODUCT'
48 'Q1 Q2 Q3 Q4 TOTAL'
DIV
DEPT
PROD
QTY Z
PROQTYZ

8
14
25
41
48

DIV

69.

FINQTYi

48
65 '(== GRAND TOTAL'

---------------~

ZK-4375-85

U sing the RPG II Editor

3-73

Enter another two specifications (identical to the two specifications just entered), by using
the following functions:
1.

SELECT (default = PERIOD) to mark the beginning of the selected region

UP (default = UP) once

3. CUT (default = KP6) to place the selected region into the paste buffer
4. PASTE (default = PFlIKP6) twice
The following example shows the effects of the procedure described above:

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

2900
3000
3100
3200
3300
3400
3500
3600
3700
3800
3900
4000
4100
4200
0
0
0
0
4300

***** * *
H 1

D 1

01
L2

T 1
T 0

T 0

***---**

48 'PRODUCT SHIPMENT REPORT'
42 'SHIPMENTS'

15 'DIVISION DEPT'
24 'PRODUCT'
48 'IU Q2 Q3 Q4 TOTAL'
DIV
DEPT
PROD
QTY Z
PROQTYZ

8
25
41
48

DIV

~
ZK-4376-85

3-74

Using the RPG II Editor

Enter another four specifications. Then, remove the line numbers, as shown in the following example:

011
I
2
I
3
14
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

***** * *

H 2

D 1

01
L2
L1

T 1
T 0

T 0

T 02

*
15 ' DIVISION DEPT'
24 'PRODUCT'
48 'Q1 Q2 Q3 Q4 TOTAL'
DIV
DEPT
PROD
QTY Z
PROQTYZ

8
14

25
41

Command: RESEQUENCE/REMOVE

DIV

DIVQTYZB 48
63 '<== Total fot"
DIV
691

~--------------~
ZK-4377-85

U sing the RPG II Editor

3-75

Use the COMMAND function and type the EXIT command to save the modified program,
as shown in the following example:

1234567890123456789012345678901234567890123456789012345678901234567890123

***** * *
H 2
lP

o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o
o

D 1

01
L2
L1

T 1

T 0

T 02

T 0

***---**
15 'DIVISION DEPT'
24 'PRODUCT'
48 'GIl Gl2 Gl3 Gl4 TOTAL'

DIV
DEPT
PROD
QTY Z
PROGlTYZ

DIV

14
25
41

DIVGlTYZB 48
63 '(== Total for'
DIV
691

----------~----------~

3-76

Using the RPG II Editor

ZK-4378-85

Chapter 4

Using Indicators
Indicators are two-character alphabetic, numeric, or alphanumeric entries that condition
the steps of a program cycle.
Each indicator has a specific function; however, some indicators can be used for more than
one purpose. Generally, you use indicators to control the following program decisions:
• Under what conditions RPG II uses a file during program execution
• When and under what conditions RPG II performs calculations
• When RPG II can access a field for input
• Under what conditions RPG II writes a field or record to an output file
To use an indicator to control program operations, you first define the conditions under
which it is set on or off. Then, you check the status (on or oro of the indicator to determine
what steps your program should perform.
This chapter discusses types of indicators and explains how to use them.

4.1 User Defined Indicators
You can define certain groups of indicators in your program; others are defined internally.
Sections 4.1 through 4.1.5 discuss those indicators you can define. Section 4.2 describes
internally defined indicators.

4.1.1 Record-Identifying Indicators
Record-identifying indicators, as their name implies, identify record types. Define each
record type by specifying an identification code in columns 21 through 41 ofthe Input specification. Then, associate an indicator in columns 19 and 20 with that record type.
In the following example, RPG II associates the record-identifying indicator 01 with a
record type.

4-1

File
nallle
I
II

Sequence (AA-ZZ, 01-99)
I NUlllber (i-N)
I IOptiona I (0)
Decilllal positions
I IIRecord identifying indicator
Contro I Ieve I
I
I III
I
I Hatch/chain field
I III + Identifying codes + Forlllat I
I I Field rec rei
I III I
I I
IFieid I I I
I III I
C
C
CI IFieid Inallle I I I Field
I III I
ZI Ilocationil
I I I indicators
Z
Z
I III Pos NDcPos NDcPos NDc IFr To II
I I I+- 0

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

IINPUT

* *** *---

AA 01 20 Cl

*---

.**---*---**

******
ZK-4387-85

In this example, if the character in the twentieth position is the number 1, the indicator 01
is set on. Then, you can use the indicator to condition operations for that particular record
type.
You can use any of the following indicators as record-identifying indicators:
• 01 through 99
• L1 through L9
• LR
• H1 through H9
By assigning a different record-identifying indicator for each record type in a file, you can
condition calculation and output operations for specific record types.
The record-identifying indicator for a particular record type is set on when RPG II
processes a record of that type. For a primary or secondary file, the record-identifying indicator is set on before total-time calculations. For a chained or demand file, the record-identifying indicator is set on immediately after the record is read. In either case, it is set off
when the program reaches the end of the current program cycle (after detail-time output).

4-2

Using Indicators

You can use record-identifying indicators to condition both detail-time and total-time
operations in that cycle and indicate which operation(s) to perform for each record type.
The following example shows how record-identifying indicators can be used to condition
program operations:

o I 1 121
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
,

11 ISALES AA 01 1 CJ
12 I
13 I
14 I
15 I
16 I
17 C 01
SALES
SUB COST
18 C 01
TSALES
ADD SALES
TCOST
ADD COST
19 C 01
TPROFI
ADD NET
20 C
21 OREPORT H 201 1P
22 0
OR
OF
23 0
UDATE Y
24 0
25 0
PAGE
26 0
H 22
1P
27 0
OF
28 0
OR
29 0
30 0
31 0
32 0
33 0
34 0
D
01
ITEM 3
35 0
DESCR
36 0
SALES 1
37 0
COST 1
38 0
PROFITi
39 0
40 0
T1
LR
41 0
TSALES1
42 0
TCOST 1
43 0
TPROFI1
44 0

50 ITEM
16 DESCR
242SALES
342COST
432PROFIT
NET
52
TSALES 62
TCOST 62
TPROFI 62
2
10
20
30
40

8
44 'JANUARY SALES REPORT'
72
68 'PAGE'
5 ' ITEM'
23 'DESCRIPTION'
41 'SALES'
56 'COST'
72 'PROFIT'
5
25
41
57
72
30 'TOTALS'
41 '$'
57 '$'
72 '$'
ZK-4388-85

In this example:
• Line 11 causes RPG II to begin reading records from the file SALES. The identification code (columns 21 through 41) groups these records according to a code that represents the month. If the code for the month is J, the record-identifying indicator 01 is
set on.
Using Indicators

4-3

• Lines 17 through 19 use the same record-identifying indicator 01 to condition detailtime calculations. RPG II performs the calculation each time a record is read of the
type described on line II.
• Line 34 uses the same record-identifying indicator to condition detail-time output.
RPG II performs the output operation each time a record is read ofthe type described
on line 11.
The output file produced by this program might appear as follows:

1
2 3 4
5 6 7
1234567880123456788012345678801234567880123456788012345678801234567880123456788C

JANUARY SALES REPORT

2/4/83

ITEM

DESCRIPTION
AMMONIA
MATCHES
NUTMEG

10005
10882
22650

TOTALS

$564.30

$425.00

PAGE

SALES

COST

60.30
285.00
208.00

50.00
205.00
170.00

PROF IT
10.30
80.00
38.00

$138.30

If you use the CHAIN or READ operation to retrieve records, the program does not set the
record-identifying indicators off until the beginning of the next program cycle. Be careful
when performing more than one CHAIN or READ operation for a file with multiple record
types, because more than one indicator can be set on during a single cycle.

4.1.2 Field Indicators
Field indicators test a field in an input record for a positive, negative, zero, or blank value.
The following lists ways to test for these values:
• For a positive value, specify a field indicator in columns 65 and 66 of the Input
specification.
• For a negative value, specify a field indicator in columns 67 and 68 of the Input
specification.
• For a zero or blank value, specify a field indicator in columns 69 and 70 of the Input
specification.
You can use any of the following indicators as field indicators:
• 01 through 99
• HI through H9

4-4

Using Indicators

Field indicators are set when the data in the field is extracted from the record. Once a field
indicator is set, it remains set until the next time the field is extracted, unless it is set offby
another use ofthe same indicator in the program. A field indicator can be used to condition
any detail-time or total-time operations. However, at total time, the field indicators
assigned to fields from a primary or secondary file retain the setting from the previous
detail-time cycle.
The following example shows how field indicators can be used to condition a calculation:

o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
24 IPARTLIS AA 01
25 I

41 C

42 C
43'C

22
33

ITEM
ITEM
ITEM

1 CF
2 100INVCDE

MUL T FACTi
MULT FACT2
MUll FACT3

ORDER
ORDER
ORDER

112233

62H
62H
62H

ZK-43B9-B5

In the above example:
• Line 25 tests the value of the field INVCDE to see if it contains a positive value, a
negative value, or a zero value. The following lists which indicator is set on for each
value:
- If the field contains a positive value, indicator 11 is set on and indicators 22 and 33
are set off.
- If the field contains a negative value, indicator 22 is set on and indicators 11 and 33
are set off.
- Ifthe field contains a zero value, indicator 33 is set on and indicators 11 and 22 are
set off.
• Lines 41 through 43 calculate the number of parts to order according to the status of
the field indicators.

Using Indicators

4-5

4.1.3 Resulting Indicators
Resulting indicators condition operations that depend on the result of a calculation. These
indicators specify the test (>, <, or =) and indicate the result of the calculation. If the
result matches the test, the indicators are set on. The following lists when these indicators
are set off:
• The next time the calculation is performed and the result of the calculation does not
satisfy the test the indicator specifies
• By another use of the same indicator in the program
You specify resulting indicators in columns 54 through 59 ofthe Calculation specification.
You can use any ofthe following indicators as resulting indicators:
• 01 through 99
• Ll through L9
• LR
• HI through H9
• OA through OG, and OV
• UI-U8
• KA through KZ
• KO through K9
Resulting indicators in columns 54 and 55 test for the following conditions:
• The Result field contains a positive value after an arithmetic operation.
• The value in Factor 1 is higher than the value in Factor 2 in a COMP operation.
• The value of the element found in Factor 2 is higher than the value in Factor 1 in a
LOKUP operation.
• The record is not found in a CHAIN operation.
• Each bit defined in Factor 2 is off in the Result field for a TESTB operation.
Resulting indicators in columns 56 and 57 test for the following conditions:
• The Result field contains a negative value after an arithmetic operation.
• The value in Factor 1 is lower than the value in Factor 2 in a COMP operation.
• The value of the element found in Factor 2 is lower than the value in Factor 1 in a
LOKUP operation.

4-6

U sing Indicators

• The defined bits in Factor 2 are of mixed status (some on, some off) in the Result field
for a TESTB operation.
• A subprogram returns with an error status from a CALL operation.
Resulting indicators in columns 58 and 59 test for the following conditions:
• The Result field contains a zero after an arithmetic operation.
• The value in Factor 1 is equal to the value in Factor 2 in a COMP operation.
• The value of the element found in Factor 2 is equal to the value in Factor 1 in a
LOKUP operation.
• An end-of-file condition occurs for the demand file in a READ operation.
• Each bit defined in Factor 2 is on in the Result field for a TESTB operation.
Resulting indicators are also used with the SETON and SETOF operation codes to specify
that the indicator(s) be set on or off.
The following example shows how resulting indicators can be used to control program
operations:

Field length
Conkol level
I Deci~al positions
I
I IHaif adjust (H)
I Indicators
Operation
I II
I I
I
I II Resu Iting
Factor
Resultl I I indicators
I I
I
Factor'
1 I
1
1
2
field 1 11+ - 0
1
1 II> < = +- Co~~ents --+
CI NxxNxxNxxl
1
1
o I 1 I 2 1 3 1 4 151 6 1 7 1
12345678901234567890123456789012345678901234567890123456789012345678901234567890
1111 II

10 C
20 C
30 C
40 C
50 C
60 C
70 C

SEARCH
FLDl
KEY

LOKUPTABl
COMP 100
CHAINFILEl
TESTB'123'
READ FILEl
SETOF
SUB FLD2

FLDl

TEST
RES

11--11l1li II II II

10 11
222324
32
404142
50
1011
606162
ZK-4390-85

In the above example:
• Line 10 causes RPG II to search for the field SEARCH in the table TABl. IfRPG II can
find an entry that is equal to the search word, indicator 11 is set on. IfRPG II can find
an entry that is nearest to and higher in sequence than the search word, indicator 10
is set on.

Using Indicators

4-7

• Line 20 causes RPG II to compare the contents of the field FLD1 with the numeric
literal 100. If the contents of FLD1 are greater than 100, indicator 22 is set on and
indicators 23 and 24 are set off. If the contents ofFLD1 are less than 100, indicator 23
;"
"at nn <Inri ;nri;"<ltn"" 99 <Inri 9.<1 <I"a "at nff Tftha "nntant" nfFT .n1 ann <I 1100 ;nri;"<1_
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ---- - - - ---. -- ---- ---------- - - - - - - -"'1----- - - -1--------

tor 24 is set on and indicators 22 and 23 are set off.
• Because the input file is an indexed file, line 30tells RPG II to retrieve a record using
the key KEY from the indexed file FILEl. Ifthe record is not found, indicator 32 is set
on. Otherwise, indicator 32 is set off.
• Line 40 causes RPG II to test the bits 1, 2, and 3 in the field TEST. Ifthe bits are all off,
indicator 40 is set on and indicators 41 and 42 are set off. If some bits are on and some
are off, indicator 41 is set on and indicators 40 and 42 are set off. If the bits are all on,
indicator 42 is set on and indicators 40 and 41 are set off.
• Line 50 causes RPG II to read the next record from FILEl. If an end-of-file condition
occurs, indicator 50 is set on. Otherwise, indicator 50 is set off.
• Line 60 sets indicators 10 and 11 off.
• Line 70 causes RPG II to evaluate the contents of the Result field after the SUB operation. If the Result field contains a positive value, indicator 60 is set on and indicators
61 and 62 are set off. If the Result field contains a negative value, indicator 61 is set on
and indicators 60 and 62 are set off. If the Result field contains a zero value, indicator
62 is set on and indicators 60 and 61 are set off.

4.1.4 Control·Levellndicators
You use control-level indicators to indicate that a particular field in the input record is a
control field. Each time RPG II reads a record that contains the control field, it compares
the data in the control field with the current value of the control field. If the contents
change, a control break occurs, the control-level indicator is set on, and the value in the
control field becomes the new current value.
You associate a control-level indicator with an input field by specifying the indicator in
columns 59 and 60 of the Input specification.
You can use L9, LB, L7, L6, L5, L4, L3, L2, and L1 as control-level indicators. The lowest
control level is L1 and the highest is L9. When you use more than one control-level indicator and a higher level control-level indicator is set on because of a control break, RPG II
automatically sets on all lower level control-level indicators. When you use a control-level
indicator as another type of indicator (for example, as a record-identifying indicator), and
that indicator is set on, lower level control-level indicators are not automatically set on.

4-8

Using Indicators

A control break is likely to occur after the first record with a control field is read. RPG II
compares the data in the control field with hexadecimal zeros. Therefore, RPG II bypasses
total-time calculation and output operations for the first record containing control fields.
All control-level indicators are set on before total-time calculations when the LR (lastrecord) indicator is on. All control-level indicators are set off after detail-time output.
The following example shows how to use three different control-level indicators to condition calculation and output operations.

U sing Indicators

4-9

011
12
I
3
1415
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
1H
14
DISK
2 FSLSCAR IP F
3 FSLSREP 0 F
132
OF
PRINTERTMP
~

!SLSC~R

5 I
6 I
7 I
8 I
9 C 01
SLSAMT
10 CLi
CUSTOT
11 CL2
SPTOT
12 CL3
BRTOT
13 OSLSREP H 201 1P
140
OR
OF
15 0
16 0
17 0
18 0
19 0
H 1
1P
20 0
OR
OF
21 0
22 0
23 0
24 0
25 0
H 2
1P
26 0
OR
OF
27 0
28 0
29 0
30 0
31 0
D 1
01
32 0
33 0
34 0
35 0
36 0
T 2
L1
37 0
380
39 0
T 12
L2
40 0
41 0
42 0
43 0
44 0
T 3
L3
45 0
46 0
47 0
48 0
49 0
T 1
LR
50 0
51 0
52 0

ADD
ADD
ADD
ADD

CUSTOT
SPTOT
BRTOT
FINTOT
UDATE Y
PAGE

1 20BRANCHL3
3 40SLSPERL2
5 90CUSTNOLi
10 142SLSAMT
CUSTOT 62
SPTOT 72
BRTOT 72
FINTOT 82
9
25 'SALES REPORT'
38 'PAGE'
43
6 'BRANCH'
22 'SALESPERSON'
35 'CUSTOMER'
46 'SALES'
4 'NO'
19 'NO'
32 'NO'
46 'AMOUNT'

BRANCHZ
SLSPERZ
CUSTNOZ
SLSAMTt

4
16
30
45

CUSTOTtB 45
46 ' *'
42 'TOTAL SALESPERSON'
SLSPERZ 45
SPTOT 1B 54
56 '**'
46 'TOTAL BRANCH NO'
BRANCHZ 49
BRTOT 1B 61
65 '***'
FINTOTt

46 'FINAL TOTAL'
59 '$'
64 '****'
ZK-4391-85

4-10

Using Indicators

In this example:
• Lines 5 through 7 assign three control-level indicators, one each to three different
control fields. The specification associates the highest control-level indicator (L3) to
the most significant input field BRANCH. The specification associates the next highest control-level indicator to SLSPER and the lowest control-level indicator to
CUSTNO.
If the value of BRANCH changes from the previous record, indicator L3 is set on.
Also, when indicator L3 is set on, indicators L2 and L1 are automatically set on. These
three indicators can be used to condition calculation and output operations.
• In line 10, when indicator L1 is on, RPG II adds the amount of the customer sale to the
total sales for a particular salesperson. In line 11, when indicator L2 is on, RPG II
adds the total sales for the salesperson to the total sales for each branch. In line 12
when indicator L3 is on, RPG II adds the total sales for each branch to compute the
final total.
• Line 36 causes RPG II to output the total sales for each customer number when L1 is
on.
• Line 39 causes RPG II to output the total sales for each salesperson when L2 is on.
• Line 44 causes RPG II to output total sales for each branch when L3 is on.
You can assign the same control-level indicator to more than one control field. These fields
are called split-control fields. The following example shows how to use split-control fields:
/

file
nallle
I
II

Sequence (AA-ZZ, 01-99)
I NUlllber (1-N)
Decilllal positions
I 10ptionai (0)
Control level
I
I I IRecord identif~ing indicator
I Hatch field
I
I III
I I fld rec rei
I III + Identif~ing codes + forlllat I
I III I
I I (PB)
lfield I I I
C
CI lfield Inallle I I I field
I III I
C
I I I indicatrs
Z
ZI Ilocationll
I III I
Z
I I I+- 0
I III Pos NDcPos NDcPos NDc Ifr To II

011
12
I
3
I
4
I
5
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

5 I
6 I
7 I

* *** *---

*---

.**---*---**
1
3
5

******

20BRANCHL1
40SLSPERL1
90CUSTNOL1

ZK-4392-85

In this example, the fields BRANCH, SLSPER, and CUSTNO combine to form the control
field. When RPG II compares the data in these fields with the same fields in a previous
record, indicator L1 is set on when the data changes.

Using Indicators

4-11

4.1.5 Overflow Indicators
When the printer reaches the overflow line that signals the end ofthe page, RPG II sets on
the overflow indicator assigned to that printer output file.
You can use OA, OB, OC, OD, OE, OF, OG, and OV as overflow indicators. Define overflow
indicators in columns 33 and 34 of the File Description specification.
In the following example, after reaching the overflow line, RPG II sets on the overflow indicator OF. Then, the printer moves to the top of the next page and outputs the heading lines.

File
naPle
I
01
o I

, o No CR (HDTE)
Edit codes
IFetch overfloN (n
IX
------------I ISpace
I Y date edit
Y Y 1 A J
III Skip·
I Z zero suppress Y N 2 B K
III I
N Y 3 C L
I
IBlank-after (B)
III I Indicators
N N 4 D H
III I I
Field II End position
III I I
naPle III ForPlat (PB)
III I I
I
III
I
I IBAB A NxxNxxNxxl
III
1+ Constant or edit Nord +
1
I
2
I
3
I
4
I
5
I
6
I

***** * *

T~pe

12345678901234567890123456789012345678901234567890123456789012345678901234567890
14 OSLSREP
15 0
16 0

H 201

17 0

UDATE Y
PAGE

18 0

9
25 'SALES REPORT'
38 'PAGE'
43
ZK-4393-85

See Part I, Chapter 6 for a full description of the overflow routine and overflow indicators.

4.1.6 K Indicators
K indicators can be used to condition calculations, output records and output fields. They
can also be used as resulting indicators.

4-12

Using Indicators

In the following program, the K indicator turned on is displayed when its associated cursor
control key is typed. CTRLlZ is typed to end the program.
o I 1
I
2
I
3
I
4
I
5
161
7
I
1234567890123456789012345678901234567890123456 7890 123456 7890 123456 7890 123456 7890
FH
F* File: READ_CURSOR.RPG
F*
F* This RPG II prog,'a. de.onst,'ates the use of the RTL ,'outine
F* SMGSREAD_KEYSTROKE to ,'ead a ke~st,'oke f,'o. the ter.inal.
F*
F* The p,'ogra. takes input f,'o. the te".inal until CTRLIZ is t~ped.
F* If an~ of the fou,' cursor positioning ke~s is t~ped, a string
F* is displa~ed co,','esponding to the ke~.
F*
F* Bui Id this prog,'a. using the following co •• ands:
F*
F* $ RPG READ_CURSOR
F* S CREATE SMGDEF. MAR
F*
• TITLE SMGDEF - Define SMGS constants
F*
.Ident 11-0001
F*
SSMGDEF GLOBAL
F*
.END
F* S MACRO SMGDEF
F* S LINt: READ_CURSOR, SMGDEF
F*FTTY
D V
5
TTY
C
CALL REAKEY
C* Externa I def ini tions fo,' SMG ,'outines.
C
CRE~:B
EXTRN' SMGSCREATE_ VIRTUAL_KEYBOARD'
C
DELKB
EXTRN'SMGSDELETLVIRTUALI:EYBOARD'
C
REAKEY
EXTRN' SMGSREAD_KEYSTROKE'
C* Exte,'nal definitions fo,' SMG ter.inators.
C
LUP
EXTRN' SMGSL TRM_UP'
C
LDOWN
EXTRN' SMGSI::_ TRM_DOWN'
C
LLEFT
EXTRN' SMGSL TRM_LEFT'
C
LRIGHT
EXTRN'SMGSLTRM_RIGHT'
C
LCTRLZ
EXTRN'SMGSL TRM_CTRLZ'
c* Create the virtual ~.e~boa,'d.
C N99
CALL CREI:B
C
PARM
KB_ID
90 WL
C
SETON
99
C* Read a ke~st,'oke.
C
CALL REAKEY
C
PARM
KB_ID
90 RL
C
PARM
LCODE 50 WW
C* Tut'n on an indicator if a CU"SOl' positioning ke~ was t~ped.
C
LCODE
COMP LUP
KA
C
LCODE
COMP LDOWN
I:B
C
LCODE
COMP LLEFT
KC
C
LCODE
COMP LRIGHT
KD
C* Tut'n on LR to <tuit if CTRL/Z was t~ped.
C
LCODE
COMP LCTRLZ
LR
C* Displa~ a .essage if a curso,' positioning ke~ was t~ped.
C KA
'UP'
DSPL YTTY
C KB
'DOWN'
DSPL YTTY
C KC
'LEFT'
DSPL YTTY
C KD
'RIGHT'
DSPLYTTY
C* Delete the virtual ke~board.
CLR
CALL DELKB
CLR
PARM
KB_ ID
90 RL

.EL

Using Indicators

4-13

4.2 Internally Defined Indicators
There are some indicators that you need not define; RPG II defines them for you. This section describes internally defined indicatorR :mn p.x!llHinR how t.o llRP t.hprrI

4.2.1 First-Page Indicator
When you specify a first-page (lP) indicator, it is set on at the start of the program and set
off after detail-time output but before the first record is read. Therefore, you can use the 1P
indicator to condition those heading lines you want printed before RPG II processes the
first record.
You specify the 1P indicator, which is always represented by 1P, in columns 24 and 25,27
and 28, or 30 and 31 of the Output specification.
The following example shows how to use the 1P indicator to print a header on the first page
ofa report:

o No (;I'( (HDTE>
Edit codes
IFetch over'f IOlrl (F)
I X
------------IISpace
I Y date edit
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
IBlank-after' (B)
III I Indicator's
N N 4 D M
File
III I I
Field II End position
naPle
III I I
FOI'l1lat (PB)
nal1le III
III I I
I
III
I
I
01
I IBAB A NxxNxxNxxl
1+ Constant or edit lrIord +
III
o
I
1
I
2
131
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
T~pe

***** * *

OOUTPUT H 201
o
OR

o
o
o
o
o
o
o
o
o
o
o

1P
OF

UDATE Y
PAGE

H 22

1P
OF

***---**

8
43 'SALES REPORT'
72
67 'PAGE'
5 'ITEM'

23 'DESCRIPTION'
41 'SALES'
56 'COST'
72 'PROFIT'
ZK-4385-85

4-14

Using Indicators

The following heading lines are printed on the first page:
o
2 3 4
5 6 7
12345678801234567880123456788012345678801234567880123456788012345678801234567880
SALES REPORT

5/18/83

SALES

OESCR I PTI ON

ITEM

PAGE
COST

PROFIT

You can use the IP indicator to condition only detail or heading output lines. If you have a
detail or heading output line conditioned by no indicators or all negative indicators, use a
negative IP (NIP) indicator to prevent this line from being output on the first cycle before
the first record is read.

4.2.2 Last-Record Indicator
Like the first cycle in an RPG II program, the last cycle differs from all other program
cycles. Once RPG II processes the last record in all primary and secondary files for which
you specified processing until the end-of-file, the last-record (LR) indicator is set, along
with all the other control-level indicators you specified. The LR indicator causes RPG II to
perform all total-time calculation and output operations conditioned by any control-level
indicators and by the LR indicator.
The LR indicator is always represented by LR, as shown in the following example:

File
name
I

THpe (HDTE)
o No CR Edit codes
------------IFetch oYet'f I Olrl (F)
I X
I Y date edit
IISpace
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
IBlank-aftet' (B)
III I Indicatot's
N N 4 D M
Field II End position
III I I
Fot'mat (PB)
III I I
name III
III I I
I
III
I
IIBAB A NxxNxxNxxl
III
1+ Constant Ot' edit lrIot'd +

01
011

12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
o

o
o
o
o

***** * *
T 1

LR
TSALES1
TCOST 1
TPROFIl

30 'TOTALS'
41 '$'
57 '$'
72 '$'
ZK-4384-85

The following information is printed only after processing the last record.
I)
7
2
3
5
12345678801234567880123456788012345678801234567880123456788012345678801234567880

TOTALS

$564.30

$425+00

$138.30

Using Indicators

4-15

If your program does not contain a primary input file, you must set on the LR indicator to
end the execution of the program. If your program sets on the LR indicator, RPG II automatically sets on all control-level indicators just before total-time calculations. If the LR
illdicutG~ is ::;~t~!i d~!"i~b t~t21-ti!'!!e ~~I!:l..!1~ti0!!~7 RPG II d0~~ not. ~l1tom~t:ir.::Il1y ~p-t on all
control-level indicators.

4.2.3 Matching-Record Indicator
When you use more than one primary and secondary file, RPG II multifile logic supplies
you with a method of selecting the next record to process. You can designate one or more
fields in each record to be the matching fields (columns 61 and 62 of the Input specification). When the fields from a primary file and one or more ofthe secondary files m' .~ch, the
matching-record (MR) indicator is set on. The MR indicator remains set on whil' ?rocessing the records from the primary and secondary file that match. See Part I, Chapter 5 for a
complete discussion of multifile processing.
At the beginning of detail time, the MR indicator is set on or off, as determined by the
matching status of the record to be processed. Therefore, at total time, the MR indicator
reflects the matching status ofthe previous record with the record to be processed. See Part
I, Chapter 5 for examples of using the matching-record indicator.

4.2.4 External Indicators
You can use external indicators to condition any operation in your program. External
indicators, which are always represented by Ul through US, can also appear in columns 71
and 72 of the File Description specification, and in columns 54 through 59 ofthe Calculation specification. To use the external indicator, you must also assign the logical name
RPG$EXT_INDS to an external indicator using the DEFINE or ASSIGN command, as
shown in the following example:
$ DEFINE RPG$EXT_INDS

"external-indicator-list"

An external indicator is set on by specifying it in the external-indicator-list. An external
indicator is set offby not specifying it in the external-indicator-list.
The following example sets on external indicators Ul, U5, and U4 and sets off external
indicators U2, U3, U6, U7, and US.
$ DEFINE RPG$E}(T

INDS

"54"

When you use an external indicator to condition a file, the file is opened only when the
external indicator is on. If the external indicator is off, input files being processed sequentially are treated as if the end-of-file was reached. Use the same external indicator as a
conditioning indicator to control calculation and output operations for those files being
processed by methods other than sequential processing. Otherwise, a run-time error will
occur when you attempt input or output operations to a file that was not opened because
the external indicator was off.
4-16

Using Indicators

External indicators can also be used as resulting indicators.

4.2.5 Halt Indicators
You can use halt indicators (HI through H9) as record-identifying indicators, field indicators, or resulting indicators to stop a program when a specific condition occurs. When you
use a halt indicator as a record-identifying indicator, a specific type of record causes the
halt.
The following example causes the program to check the character in position 80 of records
read from the input file FILEIN. If the eightieth character is not a S, the halt indicator HI
is set on and the program will halt execution. A run-time message is displayed saying that
this indicator is on.

Sequence (AA-ZZ, 01-99)
I Numbet' (I-N)
I 10ptional (0)
Decimal positions
I I IRecord identif~ing indicator
I
Contt'ol level
I III
I Match field
I
I III + Identif~ing codes + Fot'mat
I
I I FId t'ec re I
File
I III I
I I (PB)
IField I I I
name
I III I
C
C
CI IField
Iname I I I Field
I
I III I
Z
Z
ZI Ilocationil
I I I indicatrs
II
I III Pos NDcPos NDcPos NDc 1Ft' To II
I I I + - 0
011
12
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

IFILEIN AA HI 80NCS
I
02 80 CS
I

*---

.**---*---**

* * * * * * ....

1 10 FIELDI
ZK-4383-85

When a halt indicator is used as a field indicator, a halt occurs because of erroneous input
data.

Using Indicators

4-17

The following program uses a halt indicator as a field indicator. When a record is read from
the input file FILEIN, FIELD1 is checked for a negative value. IfFIELD1 contains a negative value, H2 is set on. After this record has been processed, the program will halt.

0'1
,
2
,
3
,
4
,
5
,
6
,
7
,
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

SQRT FIELD1

FDL2

IFILEIN AA 01

C NH2

50FIELD1
95

H2
ZK-4382-85

When a halt indicator is used as a resulting indicator, a halt occurs when calculations produce erroneous results during either detail time or total time.
In the following example, if the field FIELD1 is equal to zero, the halt indicator H4 is set
on. After the current record has been processed, the program halts.

,,
,

Field length
Deci~al positions
'Half' adjust (H)
Indicatot's
Operation
II
I
I
I IIResulting
I I
Factor
I
Factot'
Resultl I I indicators
I I
1
I
2
field I 11+ - 0
I
I II> < = +- Co~~ents --+
C' NxxNxxNxx'
0'1
,
2
,
3
,
4
,
5
,
6
,
7
,
12345678901234567890123456789012345678901234567890123456789012345678901234567890

,,
,

Contt'ol level

**
*
C

C NH4

*FIELD1
FIELD2

*SUB 59.0
*

DIV FIELD1

FIELD1
FIELD1

*--*** * * *
H4

ZK-4381-85

When a halt indicator is set on, a halt does not occur immediately. Before the program
halts, it completes the current cycle and processes the record that caused the error
condition.
If any halt indicators are on after detail-time output, a run-time error occurs.
Halt indicators can also be used as field-record-relation indicators and to condition calculation and output operations. See Part II, Chapter 2 for more information on using halt
indicators as field-record-relation indicators.

4-18

Using Indicators

4.3 Using Indicators As Fields
The *IN, *IN,n and *INxx special words refer to predefined indicators and allow you to use
those indicators in your program. Sections 4.3.1 and 4.3.2 describe each type of special
word.

4.3.1 *IN and *IN,n
*IN is a predefined array with 99 one-position character elements. The elements in this
array represent indicators 01 through 99. Use *IN,n, where n is the array index, to reference an indicator. For example, *IN,54 refers to indicator 54.
The elements in this array can assume only two character values - 1 and o. If you reference an indicator using *IN,n and the contents of the element are 0, the indicator is off. If
the contents of the element are 1, the indicator is on.
You can use either the array or the array element to reference an indicator anywhere any
other one-character array or array element can be used. You cannot, however, specify the
entire array *IN as the Result field of a PARM operation. To prevent unpredictable results
when modifying an element in *IN, assign the character literal 0 or 1 to *IN.
In the following example, the program tests whether the setting for indicator 15 is equal to
the setting for indicator 20. In the next line, indicator 20 is set on. Using the MOVE operation to transfer 1 to *IN,20 produces the same result as using the SETON operation code to
set on indicator 20.
Contl'o I I eve I
I
Opel'ation
I Indicatol's
I I
I
I I
Factor
I
Factol'
I I
1
2
I
CI NxxNxxNxxl
I
I
o I 1 121 3 I

Fie I d length
I Decimal positions
I IHaif adjust (HI
I II
I II Resulting
Resul t I I I indicators
field I 11+ - 0
I
I I I> < +- Comments --+
4
I
5
I
6
I
7

** *

12345678901234567890123456789012345678901234567890123456789012345678901234567890
C

*
*IN,20

*COMP **IN,15
MOVE '1'

*--*** * * *
99

*IN,20
ZK-4380-85

4.3.2 *INxx
*INxx is a predefined one-position character field where xx represents any indicator except
the IP (first-page), overflow, or external indicators. Like *IN, it can contain only the character 0 or l.
You can use *INxx anywhere any other one-character field can be used, except as the
Result field of a PARM operation.
Using Indicators

4-19

In the following example, the value of the MR indicator is compared to the value of M. If
they are the same, indicator 99 is set on. The MR indicator is represented as *INMR.

IFIlE1
I
I
IFIlE2
I
I
C

1 20 TEXT
19 20 HATCH

02
*INHR

COHP H

2 21 TEXT
20 21 HATCH

H1
99

H1
ZK-4379-85

4-20

U sing Indicators

Chapter 5

Using Files
A file is a collection of information, organized into groups or sections, called records. Each
record is made up of one or more blocks of characters or numbers, called fields.
This chapter explains the RPG II file organizations and record operations that are implemented through VAX Record Management Services. For additional information on file
organization and file and record operations, see the VAX/VMS Record Management
Services Reference Manual.

5.1 File Names
Columns 7 through 14 (File name) of the File Description specification define the file
name. RPG II uses the entry in columns 7 through 14 (File name) and the entry in columns
47 through 52 (Symbolic device) to associate the file name with the VAXNMS file specification. The default type for an RPG II file is DAT.
You can use a logical name for the entry in columns 47 through 52 (Symbolic device), and
then assign a VAXNMS file specification to the logical name. If you assign a full file specification to the logical name, RPG II ignores the entry in columns 7 through 14 when determining the file specification. If you do not assign the file-name part of the file specification
to the logical name, RPG II uses the entry in columns 7 through 14 when determining the
file specification. If you do not assign a file type to the logical name, RPG II uses DAT.
If you do not specify an entry in columns 47 through 52, you can use a logical name as the
entry in columns 7 through 14 for the VAXNMS file specification. If you do not specify a
logical name as the entry in columns 7 through 14, the file specification will consist of the
file name in columns 7 through 14 and the file type DAT.
The entry in columns 7 through 14 is used as the RMS default file name string. The entry
in columns 47 through 52 (Symbolic device) is used as the RMS file name string. See the
VAX/VMS Record Management Services Reference Manual for information about filename strings and default file-name strings.

5.2 Record Formats
The records in a file can be all the same length (fixed) or of different lengths (variable).
Vs:lrls:lhlo:>_lo:>nat.h
rO:>f'nrnQ nft.o:>n llQO:> nld~ Qt.nrs:lCl'O:> Qn<lf'O:> Tnnro:> o:>ffif'lo:>nth, Th., ph<lr"pt.,riQtipQ
. ------.--- ----0--- - - - - - ---- ------ --._- -_._-- ------0- -r---- ----- - -----------0/- ---- ------------ . . ---

and requirements of individual applications should be carefully considered when you
decide whether to use fixed-length or variable-length records.

5.3 File Types
You can use files in three ways:
• As input to an RPG II program
• As output from an RPG II program
• As an update file where the records in the file are changed by the program

5.4 File Organizations
The organization of a file determines how the records in it are arranged. RPG II allows
three different file organizations:
• Sequential
• Direct

• Indexed
Sections 5.4.1 through 5.4.3 describe these file organizations.

5.4.1 Sequential Organization
Sequential file organization is available on all types of devices. Sequential files contain
records in the order that they were written. The first logical record in the file is always in

5-2

Using Files

(

the first physical record position, the second logical record in the file is always in the second physical record position, and so on. If you need to access the fourth logical record, you
can find it between the third and fifth physical records, as shown in Figure 5-1:

fou,th mco,d
ZK-1462-83

Figure 5-1: Sequential File Organization
You can retrieve records from a sequential file either sequentially, by reading through the
entire file from beginning to end, or randomly, by using relative record numbers or an
ADDROUT file.

5.4.2 Direct Organization
Direct file organization is available on disk devices only. RMS handles RPG II direct files
as files with relative file organization. A direct file consists of a series of fixed-length positions (or cells) that are numbered consecutively from 1 to n. This number is the relative
record number; it indicates the record's position relative to the beginning of the file. (The
relative record number of the first cell is always 1.) Each record you write is assigned to a
specific cell within the file. For example, you can assign the second record to the fourth cell;
its relative record number would be 4. This assignment can result in empty cells; therefore, you must specify a record's relative record number to access it. Figure 5-2 shows that
cell number 2 and 5 are empty cells.
cell no.

records ~

empty cell

6
4

empty cell
ZK-1463-83

Figure 5-2: Direct File Organization

Using Files

5-3

Direct files can be accessed sequentially or randomly by using the CHAIN operation code
or by using an ADDROuT file. When you access a direct file sequentially, empty cells are
skipped. When you access a direct file randomly using the CHAIN operation, the indicator
specified in columns 54 and 55 of the Calculation specification will be set on for an empty
cell.

5.4.3 Indexed Organization
Indexed file organization is available on disk devices only. Each record in an indexed file
contains an index key value, as shown in Figure 5-3:

index key value

data

\ ' - - - - - - - record _ _ _ _ _J
ZK-1464-83

Figure 5-3: Indexed File Organization

An index key is a field within each record that is defined by its relative location within the
record, and by its length. The index key is the primary means of locating records within
the file. For example, you could use an employee's badge number as the index key value for
an employee record. The index key value in Figure 5-4 is the first six characters in the
record, 768979.

768979Henry Alberts

record
ZK-1465-83

Figure 5-4: Index Key Value

You can retrieve a record from an indexed file by specifying its index key value. In fact, you
can retrieve records in an indexed file either sequentially or randomly by using index key
values, or randomly by using an ADDROUT file.

Using Files

Another way to access records from an indexed file is sequentially within limits. See Section 5.5 for more information on accessing records from indexed files.

5.5 File Access Methods
There are several ways you can access the records in a file, depending on its organization.
Table 5-1 lists file organizations and the methods you can use to retrieve records.
Table 5-1: File Access Methods
File Designation

Organization

Access Method

Primary
Secondary
Demand
Full-procedural

Sequential

Sequentially
Randomly by ADDROUT file!
Sequentially
Randomly by ADDROUT file!
Sequentially
Sequentially by key
Sequentially within limits
Randomly by ADDROUT file!

Direct
Indexed

Chained
Full-procedural

Sequential
Direct
Indexed

Randomly by relative record number2
Randomly by relative record number
Randomly by key

You cannot process demand or full-procedural files using an ADDROUT file.
You can access the records in a sequential file randomly by relative record number only
if the records are fixed-length and the file resides on disk.

Although you cannot change the organization of a file after you have created it, you can
change the file access method each time you use the file. The method you use depends on
how many records your file contains and how often you need to access a record . Use the
following guidelines in selecting a file organization and access method:
• If you always process all the records in a file from beginning to end (as in a payroll
application), use a sequential file and access the records sequentially.

• If you need to access some or all records under changing or unpredictable conditions
(as in a transaction processing system), use an indexed or direct file and access the
records randomly.
Sections 5.5.1 through 5.5.7 describe each file access method and provide programming
guidelines for each.

Using Files

5-5

5.5.1 Sequential Access
When you access a file sequentially, each input operation retrieves the next record in the
file, regardless of the file organization, until either the end of the file is reached or the
program terminates. For an indexed file, records are retrieved in primary key order.
To specify sequential access, you must make the following entries in its File Description
specification:
• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for
input or for update.
• Column 16 (File designation) - Specify P, S, D, or F to indicate whether the input file is
primary, secondary, demand, or full-procedural.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
The following example specifies the name of a file, INPUT, designated as an input primary
file with fixed-length records and a record length of60 bytes:

Mode (LR)
IKe~ length
Addtn(AU)
T~pe (lOUD)
I I Record address t~pe (API)
IDes (PSRCTD)I I IOrganization (IT,i-9)
IExpand
IIEOF (E)
I I IIOverflow indicator
I IShare
I I ISeq (AD) I I II I Ke~ location
III Rewnd
rile
1111F",t (FV) II III I Extension (EU
III I
name
1IIIIBIk Rec II III I IDevice S~",b Tape Core III IFile
I
I I I I II en Ien I I II I I Icode dev Iabe I index III Icond
FI
IIIIII
I II III I II
I
I
I
III II
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

FINPUT

******---*---**-*** *---**
IP F

DISK

ZK-4394-85

Using Files

5.5.2 Sequential Access by Key
You can process only indexed primary, secondary, demand, and full-procedural files
sequentially by key. VAX RMS reads records in ascending key sequence until it reaches
the end of the file or until the program terminates.
To specify sequential access by key for a file, you must make the following entries in its
File Description specification:
• Column 15 (File type)-Specify I or U to indicate whether the file is to be open for input
or for update.
• Column 16 (File designation)-Specify P, S, D, or F to indicate whether the input file is
primary, secondary, demand, or full-procedural.
• Column 19 (Record format)-Specify F or V to describe the record format.
• Columns 24 through 27 (Record length)-Specify the length of fixed-length records or
the maximum length of variable-length records.
• Columns 29 and 30 (Key length)-Specify the length ofthe key field.
• Column 31 (Record address type)-Specify either A or P to tell RPG II that the index
keys are in character (A) or packed decimal (P) data format.
• Column 32 (File organization)-Specify I to indicate that the file is an indexed file.
• Columns 35 through 38 (Key location)-Specify the starting character position of the
key field.
The following example specifies a primary input file, INPUT, with fixed-length records 60
bytes long. The file organization is indexed with its index keys in packed decimal data
format.

File
nallle
I
FI
o I

Mode (LR)
IKe~ length
T~pe (lOUD)
II Recot'd addt'ess t~pe (API)
I Des (PSRCTD) I I IOt'ganization (IT, 1-9)
IIEOF (E)
II IIOvet'flow indicator
IllSect (AD) II III Ke~ location
1IIIFlllt (FV) II III I
Extension (EU
1IIIIBIk Rec II III I
IDevice S~IIIb Tape
I I I I I I en I en I I I I I I
I code
dev
I abe I
IIIIII
I
II III I
II
I
I
1. I
2
I
3
I
4
I
5

******---*---**-*** *---**

Addtn(AU)
IExpand
IIShare
III Rewnd
III I
COt'e III IFi Ie
index III Icond
I
III II
I
6
I
7

12345678901234567890123456789012345678901234567890123456789012345678901234567890
FINPUT

3PI

1 DISK

*
ZK-4395-85

Using Files

5-7

5.5.3 Sequential Access Within Limits
You can process indexed files sequentially within limits by creating a record-limits file
that specifies a range of index keys in each record.
record

record-limits file

data

~ - .... . - - first record

data

~ - .....--second record

data
file

data

t th key
low key

data

key
ZK·1466·83

Figure 5-5: Sequential Access Within Limits
In Figure 5-5, the first record in the record-limits file causes RPG II to retrieve those
records whose keys are greater than or equal to the low key (C) and less than or equal to
the high key (E). When the program reaches a record with a key value greater than E or
reaches the end-of-file, it reads the next record from the record-limits file to get a new high
and low range. The second record in the record-limits file causes the program to retrieve
those records whose keys are greater than or equal to the low key (E) and less than or equal
to the high key (G). The indexed file is processed until it reaches the end of the recordlimits file or the program terminates.
When using a record-limits file to process indexed files, observe the following rules:
• In the record-limits file, specify only one set oflimits per record.
• The record length must be at least twice the length of the record key.
• The low key must begin in character position 1, and the high key must immediately
follow the low key.

5-8

U sing Files

• The length ofthe high and low keys must be the same, and must be equal to the length
of the key field in the file to be processed.
• Numeric keys can contain leading zeros.
• Alphanumeric keys can contain blanks.
To access a file sequentially within limits, you must make the following entries in its File
Description specifications:
• Column 15 (File type) - Specify I or V to indicate whether the file is to be open for
input or for update.
• Column 16 (File designation) - Specify P, S, D, or F to indicate whether the input file is
primary, secondary, demand, or full-procedural.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
• Column 28 (Access mode) - Specify L to indicate that the indexed file is to be processed
sequentially within limits.
• Columns 29 and 30 (Key length) - Specify the length of the key field.
• Column 31 (Record address type) - Specify either A or P to indicate that the index
keys are in character (A) or packed decimal (P) data format.
• Column 32 (File organization) - Specify I to indicate that the file is an indexed file.
• Columns 35 through 38 (Key location) - Specify the starting character position ofthe
key field.

V sing Files

5-9

The following example specifies an input secondary file, INPUT, with fixed-length records
60 bytes long. This file is to be processed sequentially within limits. The file organization is
indexed, the key field is three bytes long beginning in character position 1, and the keys
are in character format.

Hode (LR)
IKe~ length
Addtn(AU)
T~pe (lOUD)
I I Record address t~pe (API)
IDes (PSRCTD)I I IOrganization (IT,i-9)
IExpand
IIEOf (E)
I I IIOverflow indicator
I IShare
I I ISe~ (AD) I I I I I Ke~ location
III Rewnd
1IIIfPlt (fV) II III I Extension (El)
III I
I I I I IBlk Rec I I III I IDevice S~Plb Tape Core III Ifile
I I I I lien len I I III I Icode dev label index III Icond
111111
I II III I I I I
I
I
III II

******---*---**-*** *---**

file
nallle
I

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

fINPUT

IS f

60L 3AI

1 DISK

*.. '11.*-----***.**

ZK-4396-85

To access a file sequentially within limits, you must make the following entries for the
record-limits file in its File Description specification:
• Column 15 (File type) - Specify I to indicate that the file is to be open for input.
• Column 16 (File designation) - Specify R to indicate that the file named in columns 7
through 14 is a record-limits file.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24-27 (Record length) - Specify the length of fixed-length records or the
maximum length of variable-length records.
• Columns 29 and 30 (Key length) - Specify the length of the key field.
• Column 31 (Record address type) - Specify either A, P, or blank to indicate that the
index keys are in character (A), packed decimal (P), or the same data format as the file
being processed by the record-address file (blank).
• Column 39 (Extension) - Specify E to cause the system to look for an Extension
specification.
You must also make the following entries for the record-limits file in its Extension
specification:
• Columns 11 through 18 (From file name) - Specify the name of the record-limits file.
• Columns 19 through 26 (To file name) - Specify the name ofthe file to be processed by
the record-limits file.

5-10

Using Files

(
\

The following example specifies the File Description and Extension specifications for
processing a file sequentially within limits:

o I 1 I 2 I 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FIDXA12 IR F
6 3A
EDISK
FIDXI12 IP F
60L 3AI
1 DISK
E
IDXA12 IDXI12
ZK-4397-85

An indexed demand or full-procedural file can also be processed sequentially within limits
using the SETLL operation. See Part II, Chapter 3 for information on the SETLL operation
code.

5.5.4 Random Access
Accessing records randomly allows you to retrieve or write a record anywhere in the file.
To do this, you must specify the record location using:
• Relative record numbers
• Keys
• ADDROUT file
The method you use depends on the organization of the file. Sections 5.5.4.1 through
5.5.4.3 explain these methods.

5.5.4.1 Random Access by Relative Record Number
You can randomly access records in sequential and direct files by specifying relative record
numbers that identify records relative to the beginning ofthe file. For example, the relative record number for the fifth record is 5. Accessing a sequential file using this method
requires that the records be of fixed length and that the file reside on disk.
To access a file randomly by relative record number, you must make the following entries
in its File Description specification:
• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for
input or for update.
• Column 16 (File designation) - Specify C or F to indicate whether the file named in
columns 7 through 14 is a chained or full-procedural file.
• Column 19 (Record format) - Specify F or V to describe the record format.

U sing Files

5--11

• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
• Column 28 (Mode) - Specify R to cause RPG II to access the file randomly, using a
relative record number.
You must also make the following entries for the file in its Calculation specification:
• Columns 18 through 27 (Factor 1) - Specify the relative record number of the record
you want to retrieve.
• Columns 28 through 32 (Operation code) - Specify the CHAIN operation code. Use an
indicator in columns 54 and 55 to signal an empty cell condition for a direct file. Otherwise, attempting to CHAIN to an empty cell will cause a run-time error.
• Columns 33 through 42 (Factor 2) - Specify the name of the file that contains the
record you want to retrieve.
The following example randomly accesses the direct file RAN07 A by relative record number. The primary input file RANI07 provides the record numbers in the field ITEM#.

011
I
2
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FRANI07 IP F
13
DISK
FRAN07A UC F
lOR
DISK
FRAN07B 0 F
PRINTER
30
IRANI07 AA 01
I
1 11 STORE
I
13 130ITEMII
IRAN07A AB 02
I
1 10RECII
I
3 50ACCESS
I
7 10 VALUE
ITEMII
50
C
CHAINRAN07A
C 50
GOTO HANDLR
C
1
ADD ACCESS
ACCESS
C
SETON
40
C
EXCPT
C
SET OF
40
C
HANDLR
TAG
C 50
SETON
LR
ORAN07A E
02 40
0
RECII
1
0
ACCESS
5
0
VALUE
10
ORAN07B H 22
lPN40
22 'STORE PURCHASES'
0
0
D
01N40
0
STORE
14
0
ACCESS
20
0
VALUE
27
ZK-4398-85

5-12

Using Files

5.5.4.2 Random Access by Key
You can randomly retrieve records from an indexed file by specifying their index keys.
To access a file randomly by key, you must make the following entries in its File Description specification:
• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for
input or for update.
• Column 16 (File designation) - Specify Cor F to indicate whether the file named in
columns 7 through 14 is a chained or full-procedural file.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
• Column 28 (Mode) - Specify R to tell RPG II to access records randomly, using index
key values.
• Columns 29 and 30 (Key length) - Specify the length of the key field.
• Column 31 (Record address type) - Specify either A or P to indicate that the index
keys are in character (A) or packed decimal (P) data format.
• Column 32 (File organization) - Specify I to indicate that the file is an indexed file.
• Columns 35 through 38 (Key location) - Specify the starting character position of the
key field.
You must also make the following entries for the file in its Calculation specification:
• Columns 18 through 27 (Factor 1) - Specify the index key of the record you want to
retrieve.
• Columns 28 through 32 (Operation code) - Use the CHAIN operation code. The record
you specify can be read from the file either during detail-time or total-time calculations. Specify an indicator in columns 54 and 55 to signal a record-not-found condition. Otherwise, a record-not-found condition will cause a run-time error.
• Columns 33 through 42 (Factor 2) - Specify the name of the file to be processed.

Using Files

5-13

The following example randomly accesses the indexed file GROCER using keys. The
primary input file STORES provides the keys in the field ITEM#.
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

rSTORES IP r
rGROCER IC r
rREPORT o r
ISTORES AA 01

13
lOR lAI
30

DISK
1 DISK
PRINTER

1 11 STORE
13 130ITEMti

IGROCER AB 02

1
3

10RECti
50COUNT
7 10 VALUE
50
LR

I
I
I
C

CHAINGROCER
ITEMti
SETON
C 50
OREPORT H 22
lPN40

o
o
o
o

01N40

STORE
COUNT
VALUE

22 'STORE PURCHASES'
14
20
27
ZK-4399-85

5.5.4.3 Random Access by ADDROUT File
Another way to process files is by using an ADDROUT file. You can use a record-limits file
to process only indexed files. You can use an ADDROUT file to process sequential, direct, or
indexed files.

5-14

Using Files

ADDROUT files are created by the VAX SORT/MERGE Utility when you use the
PROCESS = ADDRESS qualifier. You specify a field or fields in the record by which the
utility sorts the records, as shown in Figure 5-6:
record

data

field to sort
ZK-1467-83

Figure 5--6: Random Access by ADDROUT File
The utility sorts the records and places the disk addresses of the sorted records in an
ADDROUT file, as shown in Figure 5-7:
000 1 43

-..
__- - address of A

948567

-........- - address of B

76234 1

-...
__- - address of C

098745

.......
__- - address of 0

ADDROUT file

ZK-1468-83

Figure 5-7: ADDROUT File

Using Files

5-15

The program reads the records (addresses) in the ADDROUT file sequentially. Each record
in the ADDROUT file corresponds to a record in the original file. The addresses of the
records are referred to as Record File Addresses (RFAs) by RMS. For additional information on RFAs. see the VAX/VMS Record ManaRement Services Reference Manual.
To access a file using an ADDROUT file, you must make the following entries in the File
Description specification for the file to access:
• Column 15 (File type) - Specify I or U to indicate whether the file is to be open for
input or for update.
• Column 16 (File designation) - Specify P or S to indicate that the file named in columns 7 through 14 is primary or secondary.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
• Column 28 (Mode) - Specify R to cause RPG II to access records randomly.
• Columns 29 and 30 (Key length) - Specify the length of the key field if you plan to
access an indexed file.
• Column 31 (Record address type) - Specify I to cause the program to access the file
according to the ADDROUT file.
• Column 32 (File organization) - Specify I if you plan to access an indexed file.
• Columns 35 through 38 (Key location) - Specify the starting character position ofthe
key field if you plan to access an indexed file.
To access a file using an ADDROUT file, you must make the following entries for the
ADDROUT file in its File Description specification:
• Column 15 (File type) - Specify I to indicate that the file is to be open for input.
• Column 16 (File designation) - Specify R to indicate that the file named in columns
7 through 14 is an ADDROUT file.
• Column 19 (Record format) - Specify F to describe the record format.
• Columns 24 through 27 (Record length) - Specify 6, because record addresses are
always 6 bytes in length.
• Columns 29 and 30 (Key length) - Specify 6, because record addresses are always
6 bytes in length.
• Column 31 (Record address type) - Specify I to indicate that this is an ADDROUT file.

5-16

Using Files

'-,

• Column 32 (File organization) - Specify T to indicate an ADDROUT file.
• Column 39 (Extension) - Specify E to cause RPG II to look for an Extension
specification.
You must also make the following entries for the ADDROUT file in the Extension
specification:
• Columns 11 through 18 (From file name) - Specify the name of the ADDROUT file.
• Columns 19 through 26 (To file name) - Specify the name ofthe file to be processed by
the ADDROUT file.
The following example specifies the ADDROUT file IDXA13 and the file IDXI13 to be
accessed by the ADDROUT file:

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
rIDXA13 IR r
6 6IT
EDISK
60R 311
FIDXI13 IP r
80
or
FIDX13A 0 r
E
IDXA13 IDXI13
IIDXI13 AA 02
I
I
I
I
I
I
I
I
I
I
I

1
13
15
26
31
36
41

OIDX13A H 202
OR

o
o
o
o
o
o
o
o
o
o
o
o
o
o

1 DISK
PRINTER

46
51
56

or
02

3 KEY
12 TOWN
14 STATE
25 COUNTY
30 ZIP
350CEN30
400CEN40
450CEN50
500CEN60
550CEN70
600CEN80

UDATE Y 10
49 'NEW HAMPSHIRE TOWNS'
PAGE
77
TOWN
COUNTY
STATE
CEN80 J
CEN70 J
CEN60 J
CEN50 J
CEN40 J
CEN30 J

13
26
30
38
46
54
62
70
78
ZK-4400-85

Using Files

5-17

5.5.5 Sequential Access and/or Random Access by Key
A full-procedural file allows you to read a file both randomly and sequentially. If the fullprocedural file is an indexed file, then you can read the file randomly by key using the
CHAIN or ~.I£'l'LL operation, and you can read the hle sequentIally.
To specify an indexed full-procedural file, make the following entries for the file in its File
Description specification:
• Columns 7 through 14 must contain the file name.
• Column 15 (File type) - Specify I or U to indicate that the file is open for input or
update.
• Column 16 (File designation) - Specify F to indicate a full-procedural file.
• Column 32 (File organization) - Specify I to indicate an indexed file.
• Columns 40 through 43 (Device code) - Specify DISK.

5-18

Using Files

The following example specifies the full-procedural file FPFJOI to be accessed by a CHAIN
operation with the key specified in FPFIOI. The file FPFJOI is then processed sequentially
from that point on.

011
I
2
I
3
141
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FTTY
D F
80
FFPFI01 ID F
04
FFPFJ01 IF V
47R04AI
FFPF01A o V
73
LFPF01A 55FL 500L
IFPFI01

TTY
DIst::
1 DISK
LPRINTER
1

IFPFJ01

1 4 PARTNO
5 39 DESCR
40 43 PRICE
44 47 AMOUNT

I
I
I
I
C
C
C

C
C

PARTNO
98
98

C
C

'BAD'
LOOP

C NLR
C NLR

END
OFPF01A H 201

o
o
o
o
o
o
o
o
o
o
o

H 10

READ FPFI01
CHAINFPFJ01
EXCPT
DSPLYTTY
GOTO END
TAG
READ FPFJ01
EXCPT
GO TO LOOP
TAG

H 01

32 'PARTS SUMMARY INVENTORY'

H 00

4 PARTNO

11 'PART NO'
30 'DESCRIPTION'
30 ' __________ _
11 ' ______ _

E 01
PARTNO
DESCR

47
ZK-4662-85

Using Files

5-19

5.6 Creating Files
There are a variety of ways to create files with sequential, direct, and indexed organization::;. SecLiuIHS [j.o.l tllruugll [;.G.3 J~6(;iit~ lluvv tv c:tcCit6 fil.ss l.iSiiig (iii RPG II p:LVg7~~.
You can create sequential files by writing records, one after another, to an output file. Once
a sequential file is created, you can use it as an input file, an update file, or an output file
with the ADD option.

5.6.1 Creating Sequential Files
To create a sequential file, you must make the following entries in the File Description
specification:
• Column 15 (File type) - Specify 0 to indicate the creation of an output file.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
The following program creates a sequential file OUT60A:

011
12
1314
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FOUTI24 IP F
24
DISK
FOUT60A 0 F
24
DISK
IOUTI24 AA
I
1 3 PN
I
4 10 PNAME
I
11 12 WHOUSE
I
13 17 COLOR
I
18 20 WEIGHT
I
21 24 QTY
OOUT60A D
N1P
0
PN
3
0
PNAME
10
0
4 '1'
0
WHOUSE
12
0
COLOR
17
0
WEIGHT
20
QTY
0
24
ZK-4401-85

5.6.2 Creating Direct Files
You can create a direct file by specifying a chained output file. To do this, you must make
the following entries in its File Description specification:
• Column 15 (File type) - Specify 0 to indicate the creation of an output file.

5-20

Using Files

• Column 16 (File designation) - Specify C to indicate that the file named in columns
7 through 14 is a chained file.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
• Column 28 (Mode) - Specify R to cause RPG II to load a direct file.
The following program creates a direct file OUT60B with variable-length records:

o
I
1
I
2
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FOUTI24 IP F
24
DISK
FOUT60B OC V
24R
DISK
IOUTI24 AA
I
1 3 PN
I
4 10 PNAME
I
11 12 WHOUSE
I
13 17 COLOR
I
18 20 WEIGHT
I
21 24 QTY
C
COUNT
ADD 1
COUNT 10
C
COUNT
CHAINOUT60B
99
OOUT60B D
N1P 25
0
PN
3
0
PNAME
10
0
4 '3'
0
WHO USE
12
0
COLOR
17
0
WEIGHT
20
QTY
0
24
ZK-4402-85

5.6.3 Creating Indexed Files
You can create an indexed file either in ordered key sequence or in unordered key
sequence. If you specify unordered, you can write records to an indexed file in any order,
regardless ofthe key sequence. If you specify ordered, you must write records in the order
of their key; the order must be ascending. Once the file is created, VAX RMS sorts the
index keys in ascending order, regardless of the way they were written.
To create an indexed file in ordered sequence, you must make the following entries in its
File Description specification:
• Column 15 (File type) - Specify 0 to indicate the creation of an output file.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
Using Files

5--21

• Columns 29 and 30 (Key length) - Specify the length of the key field.
• Column 31 (Record address type) - Specify either A or P to indicate that the index
keys are in character (A) or packed decimal (P) data format.

• Column 32 (File organization) - Specify I to indicate an indexed file.
• Columns 35 through 38 (Key location) - Specify the starting character position of the
key field.
The following program creates an indexed file OUT60A with an alphanumeric key that is
three bytes long. The key begins in character position 1 of each record.
011
I
2
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

FOUTI24
FOUT60A
IOUTI24
I
I
I
I
I
I
OOUT60A

IP F
0

AA 01

24
24 3AI

0
0
0
0
0
0
0

DISK
1 DISK
1 3 PN
4 10 PNAHE
11 12 WHOUSE
13 17 COLOR
18 20 WEIGHT
21 24 tHY.

PN
PNAHE
WHOUSE
COLOR
WEIGHT
QTY

3
10
4 ' 1'
12
17
20
24

ZK-4403-85

To create an indexed file in unordered sequence, make the same entries as for an ordered
sequence and specify U in column 66 (Unordered).

5.7 Adding Records to Files
After you create a file, it may be necessary to add new records to the file. You can add
records to a file at detail-time or total-time output, or by using exception output. Sections
5.7.1 through 5.7.3 explain how to add records to files on the basis of their file organization.

5-22

Using Files

5.7.1 Adding Records to a Sequential File
Because the location of each record in a sequential file is fixed in relation to all others,
there is no unused space where a new record might be inserted. Therefore, you can add
records to a sequential file only at the end of the file, as shown in Figure 5-8:

Or--------t
ZK-1469-83

Figure 5-8: Adding Records to a Sequential File

To add a record to the end of a sequential file, you must make the following entries in its
File Description specification:
• Column 15 (File type) - Specify 0 to indicate the creation of a new record.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length ofvariable-le~h records.
• Column 66 (File addition) - Specify A to cause RPG II to add new records to the file.
You must also make the following entries in the file's Output specification:
• Columns 7 through 14 (File name) - Define the output file name.
• Columns 16 through 18 - Specify ADD to identify the record to be added.
The following example accepts input from the terminal and writes records to the end of the
file LOG:

o I 1 121 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FINPUT
IP F
80
TTY
FLOG
0
F
80
A
DISK
IINPUT
01
I
1 80 DATA
OLOG
DADD
01
0
DATA
80
ZK-4404-85

U sing Files

5-23

5.7.2 Adding Records to a Direct File
To add a new record to a direct file, you can either specify the relative record number of an
empty cell or add the record at the end of the file, as shown in Figure 5-9:

8----,----t _-----'t
0'

ZK-1470-83

Figure 5-9: Adding Records to a Direct File
To add records to empty cells in a direct file, you must make the following entries for the
file in its File Description specification:
• Column 15 (File type) - Specify I or U to indicate that the file is open for input or
update.
• Column 16 (File designation) - Specify C or F to indicate a chained or full-procedural
file.
• Column 19 (Record format) - Specify F or V to describe the record format.
• Columns 24 through 27 (Record length) - Specify the length of fixed-length records or
the maximum length of variable-length records.
• Column 28 (Mode) - Specify R to access records randomly, using a relative record
number.
• Column 66 (Addition) - Specify A to add records to the file.
You must also make the following entries in the Calculation specification:
• Columns 18 through 27 (Factor 1) - Specify the relative record number of the empty
cell.
• Columns 28 through 32 (Operation code) - Specify the CHAIN operation code. Use an
indicator in columns 54 and 55 to see whether the cell is empty. The indicator will be
set on if it is. If the cell is empty and an indicator is not specified, a run-time error
occurs.
• Columns 33 through 42 (Factor 2) - Specify the name of the file to which you want to
add the record.
5-24

Using Files

Finally, you must make the following entry in the Output specification:
• Columns 7 through 14 (File name) - Define the output file name.
• Columns 16 through 18 - Specify ADD to identify the record to add.
The output operation must follow the CHAIN operation, but before the next CHAIN operation. If not, the output will be to the cell specified by the second CHAIN operation.
The following example reads a primary input file and adds records to the direct file
DIRECT. The input field RECNO specifies the record cell to which the field is written.

011
12
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FINPUT IP F
35
DISK
FDIRECT IC F
30R
DISK
A
FTTY
30
TTY
D F
I1NPUT
I
1 30 DATA
I
31 350RECNO
IDIRECT
C
RECNO
CHAINDIRECT
99
C N99
'EXISTS' DSPLYTTY
ODIRECT DADD
99
o
DATA
30
ZK-4405-85

5.7.3 Adding Records to an Indexed File
If the file is an indexed file, you can add records at any location. The key values for the new
records are placed in the index and the entire index is sorted in ascending sequence.

NOTE
When adding records to an indexed file, you cannot specify A in column 66
(File addition) of the File Description specification for indexed files processed
sequentially within limits or processed by an ADD ROUT file.
You can add new records to an indexed file while processing the file by specifying an A in
column 66 (File addition) of the File Description specification. The file can be an input or
update file that is processed sequentially or randomly. If you want only to add records, you
can specify an output file.
You must also make the following entry in the Output specification:
• Columns 7 through 14 (File name) - Define the output file name.
• Columns 16 through 18 - Specify ADD to identify the records to be added.

Using Files

5-25

The following program adds records to an indexed file using the ADD option on the Output
specification:

I
•

FIDXIOl
FOUH3A
IIDXIOI
I
OOUT-43A

: .. t

IP F
0 F
AA
DADD

. : ...I

2-4
2-4 3AI
NIP

. : ...I

. : ...

DISK
1 DISK

•

I' •

A
1

• : .. t

2-4 PN

2-4
ZK-4406-85

5.8 Updating Records in Files
RPG II allows you to update the records in a primary, secondary, demand, full-procedural
or chained file. RPG II allows you to update the records in a sequential file only if the
records are of fixed length. You can update a record in a primary or secondary file only once
during the program cycle at detail time. Unlike other types of update files, records in a
chained, full-procedural or demand file can be updated at detail time or at total time.
To update a record, you must retrieve the record you want to change, change the contents,
and then write the record back to the file. You need only specify the fields to be changed in a
record. The remainder of the record is rewritten, using the data that was read into the
input buffer.
You can use a data structure to update a record. See Part I, Chapter 12 for an example of
updating files with data structures.
RPG II allows you to change the length of a variable-length record being updated. RPG II
determines the length ofthe record by using the highest End position (columns 40 through
43 of the Output specification) of any field in the record. If you need to change the contents
of a field in the middle of a variable-length record, but do not want to change the length of
the record, you must define the length of the record by defining a one-character field in the
last character position ofthe record.
The following example updates records in the master file MASTER. MASTER contains
two different record types of different lengths. Both records contain the field that must be
updated EMP# in different character positions. The fields LNGTH1 and LNGTH2 ensure
that the records are updated using the correct length. The records of type 01 are 80 characters long. The records oftype 02 are 60 characters long.

5-26

Using Files

o I 1 I 2 I 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FTRANSACTIP F
25
DISK
FMASTER UC V
80R21AI
1 DISK
ITRANSACT
1 20 NAME
I
21 25 NEW"
I
IMASTER
01 1 CA
I
36 40 EMP"
80 80 LNGTH1
I
I
02 1 CB
I
46 50 EMP"
60 60 LNGTH2
I
C* Update record t~pe 01
C
MOVEL'A'
KEY
21
C
MOVE NAME
KEY
C
KEY
CHAINMASTER
C
EXCPT
C
SETOF
01
C* Update record t~pe 02
KEY
21
C
MOVEL'B'
C
KEY
CHAINMASTER
C
EXCPT
OMASTER E
01
o
NEW"
40
o
LNGTH1
80
OMASTER E
02
o
NEW"
50
o
LNGTH2
60
ZK-4407-85

To update the records in a direct or indexed file and simultaneously add new records, complete the following entries for the file in its File Description specification:
• Column 15 (File type) - Specify U to indicate that the file is open for update .
• Column 66 (File addition) - Specify A to add new records to the file.
You must also define both Input and Output specifications for the file to be updated. Enter
ADD in columns 16 through 18 of those Output specifications that identify the records to
be added. The output records without ADD in columns 16 through 18 identify those records
to be updated.

U sing Files

5--27

5.8.1 Updating a File Sequentially or Randomly by Key
You can update records in an indexed file randomly by key, sequentially, or both randomly
and sequentially if the file is defined as a full-procedural file. To specify an indexed fullprocedural file to be processed in the update mode, make the following entries for the file in
its File Description specification:
• Column 15 (File type) - Specify U to indicate that the file is open for update.
• Column 16 (File designation) - Specify F to indicate a full-procedural file.
• Column 32 (File organization) - Specify I to indicate an indexed file.

5.9 Deleting Records From Files
You can delete records only from update direct and indexed files. To prevent the deletion of
needed records, perform the following steps:
• Retrieve the record.
• Evaluate its contents.
• Based on the results of the evaluation, set an indicator to control deletion of the
record.
The last record retrieved from the file is the one that is deleted when you specify DEL in
columns 16 through 18 of the Output specification. You do not need to describe any fields in
the output record, because the operation deletes the entire record.
The following example deletes a record in the master file MASTER, depending on the keys
read from the file DELETE:
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

F'DELETE
F'MASTER
F'TTY
!DELETE
I
IMASTER
C
C 99
OMASTER

IP F'
UC F'
D F'

4
50R 4AI
80

DISK
47 DISK
TTY

A
1

KEY
CHAINMASTER
'NOTF'OUND'DSPLYTTY
DDEL
N99N1P

4 KEY
99
ZK-4408-85

5-28

Using Files

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

5.10.1 Checking Record Sequence for One Record Type
You designate a record sequence by specifying A or D (ascending or descending) in column
18 of the File Description specification. Assign a matching field value (M1 through M9) to
one or more fields you want to use as matching fields in columns 61 and 62 (Matching field)
ofthe Input specification. When you specify more than one matching field, assign M9 to the
most important field. Your program considers all matching fields as one contiguous field
with the M9 field in the leftmost position, next to the M8 field, and so on, until you reach
M1, even though the fields may not be adjacent in the record or in numeric (M9 to M1)
order.

5.10.2 Checking Record Sequence for More Than One Record Type
The fields in a record of one type can be in a different order from the fields in other record
types in the same file. Suppose a payroll file consists of two different record types, one type
representing commission payment and the other type representing salary. All employee
records are to be in ascending sequence according to district (DSTRCT). Records in a district are to be in ascending sequence according to department and employee number.
Therefore, three fields (DSTRCT, DEPT, and EMPNUM) must be checked in each record.
M3 is assigned to DSTRCT, the most important field; M2 is assigned to DEPT, the next

U sing Files

5-29

most important field; and Ml is assigned to EMPNUM, the least important field. Refer to
the following example:

rile
nallle
I
II

(AA-ZZ, 01-99)
I NUlllber (i-N)
I IOptional (0)
Decilllal positions
I
Contro I Ieve 1
I I IRecord identif~ing indicator
I III
I
I Hatch field
I I rid rec rei
I III + Identif~ing codes + rorlllat I
I III I
lrield I I I
I I (PB)
I III I
C
C
CI lrield Inallle I I I rield
ZI Ilocationil
I I I indicatrs
I III I
Z
Z
I I I+ - 0
I III Pos NDcPos NDcPos NDc Irr To II

* *** *---

Se~uence

011
12
1314
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

IPAYROLL AA 01 80 CC
.I
I
I
I
BB 02 80 CS
I
I
I
I
I

*---

.**---*---**

******

3 DEPT
H2
7 DSTRCT H3
152COHH
25 27 EHPNUH H1
1

6
14

H2
1 3 DEPT
8 9 DSTRCT H3
13 172SALARY
25 27 EHPNUH H1
ZK-4409-85

First, the program determines the record type. Then, it looks at the matching fields for the
same record type.
In the example above, the same three matching fields (DSTRCT, DEPT, and EMPNUM)
appear in both record types and are the same length.
The length of matching fields assigned to the same match code must be the same length for
each record type. Table 5-2 shows that this is true for the following example:

IPAYROLL AA 01 80 CC ~ first record t~pe
1 3 DEPT
I
6 7 DSTRCT
I
I
25 27 EHPNUH
BB 02 80 CS ~ second record t~pe
I
1 3 DEPT
I
8 9 DSTRCT
I
25 27 EHPNUH
I

H2
H3
H1
H2
H3
H1
ZK-441 0-85

5-30

Using Files

Table 5-2: Matching Field Lengths
Record
Type

Matching
Field

Field
Location

Field
Length

first

DSTRCT
DEPT
EMPNUM

6to 7
lto3
25 to 27

2
3
3
8 total

second

DSTRCT
DEPT
EMPNUM

8 to 9
lto3
25 to 27

2
3
3
8 total

Matching fields need not be specified for all the record types in a file.

5.10.3 Using Matching Fields With Field·Record·Relation Indicators
Although there may be different record types in a file, very often the fields for each record
type are the same. Many fields have the same name, contain the same data, and are in the
same character positions for all the record types in a file. When only a few fields differ, you
can describe more than one record type in an OR relationship. Refer to the following
example:

Sequence (AA-ZZ, 01-99)
I NUPlbet' (1-N)
DeciPlal positions
I 10ptionai (0)
I
Contro I Ieve I
I IIRecord identifHing indicator
I Hatch/chain field
I
I III
I
I I Fie Id rec t'e I
I III + IdentifHing codes + ForPlat
IField I I I
File
I III I
I I
C
C
CI IField
InaPle I I I Field
naPle
I III I
I I I indicatot's
Z
Z
ZI Ilocationll
I
I III I
I I I + - 0
II
I III Pos NDcPos NDcPos NDc 1Ft' To II
o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

IPAYROLL AA 01 80 CS
I
OR 02 80 CH

*---

.**---*---**

******
ZK-4411-85

Using Files

5-31

You specify common fields only once, because they apply to both record types. The fieldrecord-relation indicators specified in columns 63 and 64 of the Input specification identify
the fields unique to a particular record type. Therefore, the COMM field in the following
example is associated with record type 01 and the SALARY field is associated with record
type 02. Because DSTRCT, DEPT, and EMPNUM are matching fields used in checking the
sequence ofthe records in the PAYROLL file and because Ml, M2, and M3 are described
only once in columns 61 and 62 without any field-record-relation indicators in columns 63
and 64, they apply to both record types (01 and 02) as shown in the following example:

Sequence (AA-ZZ, 01-99)
I NUPlber (l-N)
DeciPlal positions
I 10ptionai (0)
I
Contro I Ieve I
I IIRecord identifHing indicator
I Match/chain field
I III
I
I III + IdentifHing codes + ForPlat
I
I I Field rec reI
File
IFieid I I I
I III I
I I
naPle
CI IFieid
InaPle I I I Field
I III I
C
C
I I I indicators
I
I III I
Z
ZI Ilocationll
Z
I I I +- 0
I III Pos NDcPos NDcPos NDc IFr To II
II
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

IPAYROLLAA 01 80 CS
I
OR 02 80 CM

I
I
I
I
I

*---

******
1 3 DEPT
M2
8 9 DSTRCT M3
25 27 EMPNUM M1
14 152COMM
01
13 172SALARY
02
ZK-4412-85

5-32

Using Files

\~,

If one of the matching fields is in a different record position for each record type, you must
assign matching field entries, as shown in the following example:

Sequence (AA-ZZ, 01-99)
I NUl1Iber (1-N)
I IOpt i ona I (0 )
Decil1lal positions
I I IRecord identifHing indicator
I
Contro 1 1eve 1
I III
I
I Match/chain field
I III + IdentifHing codes + Forl1lat
I
I I Field I'ec rei
Fi Ie
I III I
I I
IFieid I I I
nal1le
I III I
C
C
CI IFieid
Inal1le I I I Field
I
I III I
Z
Z
ZI I location II
I I I indicators
II
I III Pos NDcPos NDcPos NDc IFr To II
I I I + - 0
o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

IPAYROLL AA 01 80 CS
I
OR 02 80 CM

I
I
I
I
I
I

*---

******
1 3 EMPNUM
20 21 DSTRCT
6 72COMM
10 12 DEPT
5 7 DEPT
10 142SALARY

M1
M3

01
M201
M202
02
ZK-4413-85

For a 01 record type, matching field DEPT is in Field location 10 through 12. For a 02
record type, matching field DEPT is in Field location 5 through 7.

5.10.4 Using Matching Fields to Process More Than One File
The processing of a primary file with one or more secondary files is called multifile processing. In multifile processing without matching fields, RPG II first reads all the records from
the primary file, then reads all the records from each secondary file in the same order in
which they are specified in the File Description specification. By using matching fields,
your program can select the records from the secondary file before selecting the records
from the primary file, based on the value oftheir matching fields.
When you use matching fields to process more than one file, the program selects records
according to the contents ofthe matching fields, as follows:
• One record is read from every file and the matching fields are compared. If the records
are in ascending order, the record with the lowest matching field value is selected for
processing. If the records are in descending order, the record with the highest matching field value is selected for processing .
• When a record is selected from a file and processing of that file takes place, the next
record from the file is read. The new record is then compared with the other records
not selected in the previous cycle.

U sing Files

5-33

You can combine records with and without matching fields in the same file. Records without matching fields are processed before records with matching fields. If two or more of the
records being compared have no matching fields, selection of those records is determined
by the priority of their files, as follows:
• The records in primary files are processed before the records in secondary files .
• The records in secondary files are processed in order of appearance in the File Description specifications.
In the following example, the matching fields from a primary file are compared with the
matching fields from a secondary file to select records in ascending sequence. The letters
represent the data in the matching fields.

Table 5-3: Matching Field Values
Matching Field Values
Record Number

Primary File

Secondary File

1
2
3
4

A
C
D1
F

B
D2
X

Key to Figure 5-10
1.

The first record from the primary file is read and the matching field (A) is located.

The first record from the secondary file is read and the matching field (B) is located.

The contents ofthe matching field (A) from the first record in the primary file are
compared with the contents of the matching field (B) from the first record in the
secondary file. A is selected.

The second record from the primary file is read and the matching field (C) is
located.

The contents ofthe matching field (B) from the first record in the secondary file are
compared with the contents ofthe matching field (C) from the second record in the
primary file. B is selected.

The second record from the secondary file is read and the matching field (D2) is
located.

The contents of the matching field (D2) from the second record in the secondary file
are compared with the contents ofthe matching field (C) from the second record in
the primary file. C is selected.

5-34

Using Files

Primary File
1.

[A]

Secondary File
2.

Record 1

Process A.

Cycle n

Record 2

Process B.

Cycle n + 1

Record 1

Process C.

Cycle n + 2

Figure 5-10: Using Matching Fields to Do Multifile Processing

Using Files

5-35

Key to Figure 5-10 (Cont.)
8.

The third record from the primary file is read and the matching field (D1) . ".
located.
.

The contents of the matching field (D2) from the second record in the secondary filE:
are compared to the contents of the matching field (D1) from the third record in thE
primary file. D1 is selected.

10.

The fourth record from the primary file is read and the matching field (F) iE
located.

'''.

11. The contents of the matching field (D2) from the second record in the secondary file
are compared to the contents ofthe matching field (F) from the fourth record in the
primary file. D2 is selected.
12.

The third record from the secondary file is read and the matching field (X) is
located.

13. The contents of the matching field (F) from the fourth record in the primary file are
compared to the contents of the matching field (X) from the third record in the secondary file. F is selected. Because the primary file is now at its end, the remaining
records in the secondary file (X and Z) are processed in order of appearance.

5-36

V sing Files

1
O
Ir:::::I
~ I I Record 3

Process 01.

Cycle n + 3

10.

Record 4

Process 02.

Cycle n + 4

12. IvI
x

I ~ I Record 3

Process F.

Cycle n + 5
ZK-1475-83

Figure 5-10: Using Matching Fields to Do Multifile Processing (Cont.)
When the matching fields from a primary file match one or more of the secondary files,
RPG II sets the matching-record (MR) indicator on before detail-time calculations. You can
use the MR indicator to condition calculation and output operations for the record just
Using Files

5-37

selected. The indicator remains on for one complete program cycle. It is set off if the record
selected for processing contains no matching fields. A record selected using the FORCF
operation code causes the MR indicator to remain offfor one program cycle while the fom
record is processed.
'"
RPG II processes matching records for two or more files in the following ways:
• When a record from the primary file matches a record from the secondary file, the
record from the primary file is processed before the record from the secondary file is
processed. The record-identifying indicator that identifies the record type just
selected is on at the time the record is processed.
• When records from ascending files do not match, your program processes the record
with the lowest matching field content first.
• When records from descending files do not match, your program processes the record
with the highest matching field content first.
• A record type that has no matching field specification is processed immediately after
the previous record is processed, In this case, the MR indicator is set off. If this record
type is the first in the file, your program processes this record first, even when it is not
in the primary file.
• The matching of records makes it possible to enter data from primary records into
their secondary records because your program processes the record from the primary
file before matching the record from the secondary file. However, the transfer of datI'!.
from the secondary record to matching primary records can be done only when loo(
ahead fields are specified.
,,,In the following example, matching fields are used to combine a primary file with two secondary files in ascending sequence. Record-identifying indicators are assigned in the following way:

• oI-Records from the primary file with matching fields
• 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
• OS-Records from the second secondary file without matching fields

5-38

Using Files

011
12
I
3
1415
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FRECI99A IP AF
80
DISK
FRECI99B IS F
80
DISK
FRECI99C IS F
80
DISK
FOUTPUT 0 F
80
DISK
IRECI99A
01 80 C1
I
1 80 TEXT
I
1 2 MATCH M1
02 80 C2
I
I
1 80 TEXT
IRECI99B
03 80 C3
I
1 80 TEXT
I
1 2 MATCH M1
04 80 C4
I
1 80 TEXT
I
IRECI99C
05 80 C5
I
1 80 TEXT
I
1 2 MATCH M1
I
06 80 C6
1 80 TEXT
I
OOUTPUT D
N1P
0
TEXT
80
ZK-4414-85

Table 5--4 lists the contents of the matching fields for all three files: primary, first secondary, and second secondary. Field values with A after the value represent values from the
nrimary file. Field values with B after the value represent values from the first secondary
\. Field values with C after the value represent values from the second secondary file.

Table 5-4: Matching Field Values
Record
Number

Primary
File

First Secondary
File

Second Secondary
File

I
2
3
4
5
6
7
8
9

none
none
20A
20A
40A
50A
none
60A
80A

none
20B
30B
30B
60B
none
70B
80B
80B

IOC
30C
50C
50C
none
60C
80C
80C
none

U sing Files

5-39

Table 5-5 lists the steps involved in processing these files and those indicators that must
be set on for the operation to occur.
Table 5-5: Processing Records with Matching Fields
Step

Record Type

Matching Field Value

Indicators for Processing

1
2
3
4
5
6
7
8
9
10

02
02
04
05
01
01
03
03
03
05
01
01
02
05
05
06
01
03
04
05
03
01
03
03
05
05
06

none
none
none
10C
20A
20A
20B
30B
30B
30C
40A
50A
none
50C
50C
none
60A
60B
none
60C
70B
80A
80B
80B
80C
80C
none

Not MR and 02
Not MR and 02
Not MR and 04
NotMRand05
MR and 01
MR and 01
MRand03
Not MR and 03
Not MR and 03
Not MR and 05
Not MR and 01
MR and 01
Not MR and 02
MRand05
MR and 05
Not MR and 06
MR and 01
MRand03
Not MR and 04
MRand05
Not MR and 03
MRand01
MRand03
MR and 03
MR and 05
MRand05
Not MR and 06

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

5-40

U sing Files

5.11 Processing Files With Multiple Keys
he following program reads one input file with three keys. It uses three different file specIfications to pick up the three keys. Note that the three filenames use identical fields, and
that each filename uses a different key to point to the same file. Also note the use of the
same fields by a data structure.

o I 1 I 2 I 3 I 4 I 5 161 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FIDXI01
FIDXJ01
FIDXt::01
FIDX03A
IIDXI01
I
I
I
I
I
I
IIDXJ01
I
I
I
I

IP F
IS F
IS F
F
0
AA

24 4AI
24 3AI
24 2AI
24

21 DISK
1 DISK
11 DISK
DISK

I
IIDXK01 CC
I
IFIELDS
DS
I
I
I
I
I
I
OIDX03A D
N1P
0

IDXI01
IDXI01
1
4
11
13
18
21

3 PN
10 PNAME
12 WHOUSE
17 COLOR
20 WEIGHT
24 QTY

1
4
11
13
18
21

3 PN
10 PNAME
12 WHOUSE
17 COLOR
20 WEIGHT
24 QTY
24 FIELDS

1
4
11
13
18
21
FIELDS

3 PN
10 PNAME
12 WHOUSE
17 COLOR
20 WEIGHT
24 QTY

24
ZK-4667-85

U sing Files

5-41

Chapter 6

Using Printer Output Files
If you want to create a formatted report by printing an output file, you must decide what
the report will look like before you write your program. You must know what information
is to be printed on each heading, detail, and total line, and where the individual fields are
to appear.
Designing the physical layout of your report is an important part of the work necessary to
produce a formatted report. RPG II provides several features you can use to print certain
information automatically and to control the printing of other information. Sections 6.1
and 6.2 describe these features and explain how to use them.
Printer output files cause a file to be in VAXNMS print-file format. The default PRINT
command causes the insertion of a form-feed character when the form nears the end of a
page. To suppress the insertion ofform-feed characters, use the NOFEED qualifier to the
PRINT command when printing printer output files created by RPG II programs.

6.1 Editing Output
You can use predefined Edit codes and Edit words to format numeric data for your report.
Edit codes and words supply additional information about the output, thus increasing your
report's usefulness to the end user. Section 6.1.1 describes Edit codes and explains how to
use them. See Part II, Chapter 2 for information on Edit words.

6.1.1 Using Edit Codes and Edit Code Modifiers
You can specify specialized editing for numeric data by entering one of the one-character
Edit codes in column 38 of the Output specification. Edit codes consist of (1) simple Edit
codes (X, Y, and Z) that perform one predefined function, and (2) combined Edit codes (1, 2,
3, 4, A, B, C, D, J, K, L, and M) that perform a combination of predefined functions. See
Part II, Chapter 2 for information on Edit codes.

6-1

In most cases, using one or more Edit codes to format numeric data is sufficient. However,
there are some cases where you might want to use an Edit code modifier to perform the
following special formatting:
\,

• Replace leading zeros with asterisks.
• Put a dollar sign immediately to the left of the leftmost character.
See Part II, Chapter 2 for information on Edit code modifiers.

6.1.2 Using Constants
Constants are usually used to specify headings that describe the contents of a particular
column. To specify a constant, enter the constant string, enclosed in apostrophes, in columns 45 through 70 (Constant or edit word). In the following example, SALES REPORT
appears in character positions 24 through 35 of the printed output file:

THpe (HDTE)
Edit codes
o No CR ------------IFetch ove/'f Iow (F)
I X
IISpace
I Y date edit
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
IBlank-after (B)
III I IndicatOl's
N N 4 D M
File
III I I
Field II End position
Format (PB)
name
III I I
name III
I
III I I
I
III
I
01
I IBAB A NxxNxxNxxl
III
I+ Constant 0/' edit word +
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

***---**
35 'SALES REPORT'

ZK-4415-85

When using constants, consider the following rules:
• Constants can contain from 1 to 24 characters.
• Enclose constants in apostrophes (for example, 'EMPLOYEE NAME'). The apostrophes are not printed.
• When using constants, leave columns 32 through 39 and column 44 blank.
See Part II, Chapter 2 for information on Edit words.

6-2

Using Printer Output Files

6.2 Using Special Words
RPG II provides special words that enable you to perform the following kinds of
formatting:
• Printing the date
• Printing a page number and incrementing the page number by one for each new page
• Repeating data fields in an output record
This section describes special words and explains how to use them.

6.2.1 Printing the Date: UDATE, UDAY, UMONTH, UYEAR
UDATE automatically prints the date in the format month, day, year. To put slashes (I)
between the month, day, and year (for example, 5117/85), specify Y in column 38 of the
Output specification.
The default date is the system date. To change the default date, define the logical name
RPG$UDATE to the date you want. The format ofthe date is dd-mmm-yyyy. The following
example changes the date to November 2, 1985.
S DEFINE RPGSUDATE

"2-NOV-1985"

You can change the UDATE output format by specifying D, I, orJ in column 21 of the Control specification. Specifying D changes the UDATE format to day/month/year. Specifying
lor J changes the UDATE format to day.month.year.

U sing Printer Output Files

6-3

You can use UDAY, UMONTH, and UYEAR to print each component of the date in the
format you need, as shown in the following example:

, o No CR T!:tpe (HDTE>
Edit codes
------------Iretch ovet'f I0111 (F)
I X
I ISpace
I Y date edit
Y Y 1 A J
I Z zero suppress Y N 2 B K
III Skip
III I
I
N Y 3 C L
IBlank-after (B)
N N 4 D M
III I Indicators
rile
III I I
Field IIEnd position
rOt'mat (PB)
name
III I I
name III
III
I
I
III I I
I
1+ Constant or edit word +
01
I IBAB A NxxNxxNxxl
III
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

0
0
0
0
0
0

***** * *

*
UYEAR
UMONTH
UDAY

***---**
8

9 ' -,
11

12 '-'
14

ZK-4416-85

In this example, the special words UYEAR, UMONTH, and UDAY in the Output specification change the date format to year-month-day. The output might look like this:
85-05-16

When using special words, observe the following rules:
• You cannot specify Y in column 38 (Edit code) of the Output specification for UDAY,
UMONTH, or UYEAR. Instead, specify a constant in columns 45 through 70 (Constant or edit word) to separate the day, month, and year.
• You can use these special words in Factor 1 or 2 of the Calculation specification.
• You cannot use these special words in the Result field ofthe Calculation specification.
• You cannot use the Blank after option (column 39 of the Output specification) with
these special words.

6.2.2 Numbering Pages: PAGE and PAGE1 through PAGE7
RPG II provides eight special words, PAGE and PAGEl through PAGE7, for numbering
pages in printed output files. RPG II automatically increments the page number by one for
each new page. You can use more than one paging special word to number several different
output files.

6-4

Using Printer Output Files

To use one of the paging special words, specify it as a field in the Input, Calculation, or
Output specifications. When you use a paging special word as an input field or as the
Result field of a calculation, you can use any Field length up to 15 digits, but you must
specify zero Decimal positions. RPG II suppresses leading zeros and signs on output unless
you use an Edit word, use an Edit code, or specify a packed decimal or binary data format.
If you do not define the length of a paging special word elsewhere (for example, defining a
field to represent the page number as a result of a calculation), the page number is output
as a four-digit numeric field with zero decimal positions. Page numbering begins with 1.

To change the beginning page number, enter the page number you want to use as an input
record and name the field PAGE or use a PAGE field as the result of a calculation. Enter the
field in columns 53 through 58 of the Input specification, as shown in the following
example:

o
I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
IINPUT

AA 99

OOUTPUT H 2
OR

o
o
o
o
o
o

1P
OF

UDATE Y
PAGE

40PAGE

36 'D E P 0 SIT '
49 ' REP 0 R T'
68 'PAGE'

ZK-4417-85

In this example, the contents of the field PAGE appear in character positions 69 through
72. If the value of the field is 0032, the page numbering begins with 33, because RPG II
adds 1 to the number. The output appears as follows:
0 2 3
4
5
6
7
1234567880123456788012345678801234567880123456788012345678801234567880123456788
5/16/85

D E P 0 5 I T

REP 0 R T

PAGE

Using Printer Output Files

6--5

Another way to change the page number is to assign the page number you want minus one
to a PAGE field in the Result field, as shown in the following example:
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

C N99

Z-ADD89

SETON

OOUTPUT H 2

o
o
o
o
o
o

PAGE

UDATE Y
PAGE

36 'D E P 0 SIT '
49 ' REP 0 R T'

68 'PAGE'
72

ZK-4418-85

The output appears as follows:

o
1
2
3
4
5
6
7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
5/16/85

D E P 051 T

REP 0 R T

PAGE

In this example, Z-ADD assigns 89 to PAGE. RPG II adds 1 to this number and begins
numbering pages with 90. The assignment occurs when indicator 99 is set off. That way,
RPG II makes the initial page number assignment only once and not every time a record is
read.
You can restart page numbering at any point in the program. Use anyone ofthese methods
to reset the value of a PAGE field:
• Specify the Blank after option (column 39 ofthe Output specification) for a PAGE field
to reset the page number to 1 after the current record is output.
• Use a PAGE field as the result of an operation in the Calculation specification or as an
input field.
• Use output indicators in the Output specification to condition the value of a PAGE
field. When the indicator is on, the value of the page field is reset to 1 before the current record is output. You cannot use these indicators to control the printing of a
PAGE field, because a PAGE field is always printed.

6-6

Using Printer Output Files

6.2.3 Saving Time by Repeating Data: *PLACE
You can use the special word *PLACE to repeat data in an output record. The fields or
constants you want to repeat must have been previously defined. Then, you can use the
same fields or constants without having to specify their Field names (columns 32 through
37 of the Output specification) and End positions (columns 40 through 43 of the Output
specification). When you specify *PLACE in columns 32 through 37, RPG II repeats all the
data between the beginning position and the highest End position for any previously
defined field in the output record. To prevent overlapping, the End position on the same
specification as *PLACE must be at least twice the highest End position of the group of
fields you want to repeat.
When using *PLACE, the following columns in the Output specification that contain
*PLACE must be left blank:
• Column 38 (Edit code)
• Column 39 (Blank after)
• Column 44 (Data format)
• Columns 45 through 70 (Constant or edit word)
In the following example, *PLACE specifies the following fields again:
• LIST#
• DESCR
• STOCK#
.ONHAND
• PRICE

Using Printer Output Files

6-7

011
I
2
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FOUTI91 IP F
26
DISK
FOUT91A 0 F
80
PRINTER
1*
IOUTI91 AA 01
I
1 6 STOCKIt
I
7 18 DESCR
I
19 2100NHAND
22 262PRICE
I
C*
USTIt
C 01
ADD 1
USTII 30
0*
00UT91A D
NiP
o
USTII Z
4
o
DESCR
18
o
STOCK It
26
o
ONHANDZ 31
o
PRICE K 39 '$'
o
79
*PLACE
ZK-4419-85

Sample output from this example might look like the following:
3

PARSNIPS
SKIM MILK
POTATO CHIPS

IjEG 1 PO
DAROSK
SNK845

17
134
100

$.88
$1.70
$1.18

4
5

2 ORT PEPSI
BAKED BEANS

DRNK1A
CANFOD

87
80

$1.28
$.65

4
5

PARSNIPS
SKIM MILK
POTATO CHIPS

IJEG 1 PO
DAROSK
SNK845

17
134
100

$.88
$1.70
$1.18

2 ORT PEPSI

DRNK1A
CANFOD

87
80

$1. 28
$.65

BAKED BEANS

6.3 Conditioning Output Lines
Although you can use any type of indicator to condition output, the 1P (first-page) and
overflow indicators specifically affect output. Sections 6.3.1 and 6.3.2 describe how these
indicators affect output.

6.3.1 Printing Lines Before Reading the First Record: First-Page Indicator
When you specify the 1P (first-page) indicator, the indicator is set on at the start of the
program and set off after detail-time output but before the first record is read. Therefore,
you can use this indicator to condition those heading lines you want printed before RPG II
processes the first record.
You specify the 1P (first-page) indicator, which is always represented by 1P, in columns 24
and 25, 27 and 28, or 30 and 31 of the Output specification.

6--8

Using Printer Output Files

The following example shows how to use the lP (first-page) indicator to print a header on
the first page of a report:

T!:Ipe (HDTE>
Edit codes
o No CR IFetch overflow (F)
I X
------------I ISpace
I Y date edit
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
IBlank-after (B)
III I Indicators
N N 4 D H
File
III I I
Field II End position
Forfllat (PB)
naflle
III I I
naflle III
I
III I I
I
III
I
01
IIBAB A NxxNxxNxxl
III
1+ Constant or edit word +
011
12
I
3
I
4
I
5
16
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

OOUTPUT H 201
o
OR

o
o
o
o
o
o
o
o
o
o
o

UDATE Y
PAGE

H 22

***---**
8
43 'SALES REPORT'
72
67 'PAGE'
5 'ITEM'
23 'DESCRIPTION'
41 'SALES'
56 'COST'
72 'PROFIT'
ZK-4420-85

The following lines are printed on the first page:
0 2 3 4 5 6 7
1234567890123456789012345678901234567890123456789012345678901234567890123456789

SALES REPORT

5/19/85
ITEM

DESCRIPTION

SALES

PAGE
COST

PROFIT

You can use the lP (first-page) indicator to condition only detail-time output. If you have a
detail line that is not conditioned by any indicators or by all negative indicators, you can
specify N1P as an indicator to prevent the line from being output before the first input
record is read.

Using Printer Output Files

6--9

6.3.2 Specifying Page Breaks: Overflow Indicator
You use overflow indicators to specify when a page break should occur before certain lines
are printed. These indicators are used primarily to condition the printing of heading lines,
but can also be used to condition calculation operations and other types of output lines.
You can use only overflow indicators for output files going to the printer. You define the
indicator in columns 33 and 34 of the File Description specification. The same overflow
indicator must be used to condition the overflow lines for that same file. If no indicator is
specified for that file, RPG II automatically handles overflow. See Section 6.4 for information on automatic overflow.
RPG II sets on an overflow indicator only the first time an overflow condition occurs for the
current page. An overflow condition exists whenever one of the following circumstances
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.
When using overflow indicators on an Output specification, observe the following rules:
• Spacing past the overflow line sets the overflow indicator on.
• Skipping past the overflow line to any line on the same page sets the overflow indicator on.
• Skipping past the overflow line to any line on the new page does not set the overflow
indicator on unless the skip is specified past the overflow line on the new page.
• A skip to a new page specified on a line not conditioned by an overflow indicator sets
the overflow indicator off before the form advances to a new page.
• If you specify a skip to a new line and the printer is currently on that line, a skip does
not occur.
• When an OR line is specified for an output print record, the Space and Skip entries of
the preceding line are used. If space and skip requirements differ from the preceding
line, enter Space and Skip entries on the OR line.
• An overflow indicator can appear in either line of an AND or an OR relationship. In an
AND relationship, the overflow indicator must appear on the main specification line
for that line to be considered an overflow line. In an OR relationship, the overflow
indicator can be specified on either the main specification line or the OR line. However, only one overflow indicator can be associated with one group of output
indicators.

6-10

Using Printer Output Files

• If an overflow indicator is used on an AND line, the line is not an overflow line. In this
case, the overflow indicator is treated like any other output indicator.
• An overflow indicator cannot condition an exception line (E in column 15 of the Output specification), but can condition fields within the exception record.
During a normal program cycle, RPG II checks the overflow indicator only once (immediately after total-time output) to see if it is set on. The overflow routine performs the following operations:
1.

RPG II prints all total lines conditioned by an overflow indicator when the indicator is on.

2. RPG II prints those heading and detail lines conditioned by an overflow indicator
when the indicator is on.
3. 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.
If the overflow indicator is on, you can fetch the overflow routine before printing any total
or detail line by specifying F in column 16 (Fetch overflow) of the Output specification.
Fetch overflow lets you alter the RPG II logic cycle to prevent printing detail, total, and
exception lines on or over the perforation between pages. When you fetch the overflow routine, RPG II performs the following operations:
• When an output line specifies Fetch overflow, RPG II finds out if the overflow indicator for that file is on. If it is, RPG II calls the overflow routine and prints only those
overflow lines associated with the file described on the Output specification.
• After RPG II prints the overflow lines, it prints the line that specified the Fetch
overflow.
• RPG II prints any detail-time and total-time lines left for that program cycle.
When fetching the overflow routine, observe the following rules:
• If you want to fetch the overflow line for each record in an OR relationship, you must
specify F in column 16 (Fetch overflow) for each line.
• You cannot specify an overflow indicator in columns 23 through 31 on the same line
with F in column 16 (Fetch overflow).
To decide when to fetch the overflow routine, study all possible overflow situations and
count lines, spaces, and skips to determine what happens when an overflow occurs.
In the following example, the length of a page is 15 lines. The overflow line is line 12. When
the overflow line is reached, the overflow indicator OG is set on, which conditions the heading line that prints the date, report title, and page number at the top of each page.

Using Printer Output Files

6-11

o I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FOUTI93 IP F
74
FOUT93A 0 F
80
LOUT93A 15FL 120L
IOUTI93 AA 01

DISK
LPRINTER

I
I
I
I
I
I
I
I
I
I

OOUT93A H 102
OR

0
0

10
16
22
28
34
40
46
48
63

1P
OG

UDATE Y

10
47 'SOUTHERN NEW HAMPSHIRE'
53 'TOWNS'

PAGE

TOWN
COUNTY
STATE
CEN80 J
CEN70 J
CEN60 J
CEN40 J
CEN40 J
CEN30 J

13
26
30
38
46
54
62
70
78

0
0

0
0
0
0

0
0
0
0
0
0

5 ZIP
150CEN30
210CEN40
270CEN50
330CEN60
390CEN70
450CEN80
47 STATE
59 COUNTY
74 TOWN

ZK-4421-85

A sample ofthe output from this example might look like the following:
4
5
6
7
2
3
12345678801234567880123456788012345678801234567880123456788012345678801234567880

12/14/85

HafrlPstead
Kingston
Litchfield
NelAlfTlarf(et
Atkinson
R;' e
Hollis
Pete rbo rough
Ra;'rTlond

6-12

SOUTHERN NEW HAMPSHIRE TOWNS
Rockingham
Rocf(ingharTl
Hillsborough
RocfU n gharT!
RocKinghafTl
Rocfdngham
Hillsborough
Hillsborough
RocfU n ghafTl

NH
NH
NH
NH
NH
NH
NH
NH
NH

Using Printer Output Files

3.785
4 .111
4 .150
4.280
4.387
4.508
4.678
4.885
5.453

2.401
2.882
1 .420
3.361
2.281
4.083
2.616
3.807
3.003

1 .261
1 .672
721
3.153
1 .017
3.244
1.720
2.863
1.867

823
1 .002
341
2.640
434
1 .246
886
2.470
1 .340

823
1.002
341
2.640
434
1.246
886
2.470
1 .340

775
1 .017
286
2.511
407
1 .081
878
2t521

1 .165

12/111/85

Plaisto'",
Windhafn
SeabrooK
PelhaM
AMherst
Milford
Bedford
HaMPton
Exeter

12/111/85

Goffsto'",n
Londonde r n'
Hudson
MerriMacK
Oe r ry
SaleM
PortsMouth
Nashua
Manchester

SOUTHERN NEW HAMPSHIRE TOWNS
RocKin!lha~l

RocKin!lhaM
RocKin!lhaM
Hillsborou!lh
Hillsborou!lh
Hillsborou!lh
Hillsborou!lh
RocKin!lhahl
RocKin!lhaM

NH 5.608
NH 5.6611
NH 5.817
NH 8.080
NH 8.2113
NH 8.685
NH 8.1I81
NH 10.1I83
NH 11 .0211

1I.712
3.008
3.053
5.1I08
1I.605
6.622
5.858
8.011
8.882

2.815
1 .317
2.208
2.605
2.051
1I.863
3.636
5.378
7.2113

2
1 .1I111
630
1.782
878
1 .1 711
3.827
1 .561
2.137
5.388

1 .1I111
630
1.782
878
1 .1711
3.827
1 .561
2.137
5.388

SOUTHERN NEW HAMPSHIRE TOWNS
Hi 11 sbo rou!lh
RocKin!lhaM
Hillsborou!lh
Hillsborou!lh
RocKin!lhafTl
RocKin!lhaM
Rocf\in!lhaM
Hillsborou!lh
Hi 11 sbo rou!lh

NH
NH
NH
NH
NH
NH
NH
NH
NH

11.315
13.588
111.022
15.1I06
18.875
211.1211
26.2511
67.865
80.836

8.2811
5.3116
10.638
8.585
11.712
20.1112
25.717
55.820
87.7511

7.230
2.1I57
5.876
2.888
6.887
8.210
26.800
38.086
88.282

1.366
538
1.666
8111
1 .115
1I.068
1.326
1 .507
1I.872

1I.2117
1 .1I28
3.1I08
1.253
5.1I00
3.267
111.821
32.827
77.685

1I.2117
1.1I28
3.1I08
1.253
5.1I00
3.267
111.821
32.827
77.685

3.838
1 .373
2.702
1 .0811
5.131
2.751
111.1I85
31.1I63
76.8311

6.4 Automatic Overflow
When an overflow indicator is not assigned to an output file going to the printer, the compiler assigns the first unused indicator to the file. This causes a skip to line 1 whenever an
overflow occurs, and the overflow routine executes for this file.
You can override the printing of overflow lines by specifying an overflow indicator on the
File Description specification. However, do not use the same indicator to condition any output line. This causes continuous printing oflines, regardless of page boundaries.

Using Printer Output Files

~13

6.5 Defining the Page Size
The Line Counter specification allows you to alter the default format of a printed output
file. You can use this specification to change the number of lines on a page and to change
the overflow line.
To define the page size, you must make the following entries in the Line Counter
specification:
• Columns 7 through 14 (File name) - Specify the name of the output file. This file must
have been previously defined on the File Description specification with PRINTER in
columns 40 through 46 (Device code) and L in column 39 (Extension).
• Columns 15 through 17 (Form length) - Specify the number oflines printed in a page.
• Columns 18 and 19 (FL) - If you specify an entry in columns 15 through 17 (Form
length), you must enter FL in columns 18 and 19. This entry indicates to the compiler
that columns 15 through 17 define the Form length.
If you do not specify an entry for Form length, the default is 66 lines.
To define the overflow line, you must make the following entries in the Line Counter
specification:
• Columns 20 through 22 (Overflow line number) - Specify the line number where an
overflow occurs.
• Columns 23 and 24 (OL) - If you specify an overflow line number in columns 20
through 22, you must enter OL in columns 23 and 24. This entry indicates to the compiler that columns 20 through 22 define the Overflow line number.
If you do not specify an entry for the Overflow line, the default is line 60.

6.6 Formatting Output
You can define how your printed output file will look by specifying the number of lines to
space or skip. Spacing is relative to the line currently being printed; therefore, use spacing
between detail lines in a report. Skipping repositions the printer to an absolute line number; therefore, specify skipping for the column headers of a report. For example, if you
specify skip to line number 2, the output line associated with that specification will be
printed only on the second line of each page.

6-14

Using Printer Output Files

To specify the number oflines to space, you must make the following entries in the Output
specification:
• Column 17 (Space before) - Specifies the number oflines to be spaced before printing
a line.
• Column 18 (Space after) - Specifies the number oflines to be spaced after printing a
line.
To specify the number oflines to skip, you must make the following entries in the Output
specification:
• Columns 19 and 20 (Skip before) - Specifies the line number to skip to before printing
a line.
• Columns 21 and 22 (Skip after) - Specifies the line number to skip to after printing a
line.
If you make entries in both spacing and skipping columns for the same line, RPG II formats the output in the following order:

Skip before

Space before

Print the output line

Skip after

Space after

You can specify entries in columns 17 through 22 (Space and Skip) for the second line in an
OR relationship; otherwise, the preceding line specifies the entries for spacing and
skipping.

Using Printer Output Files

6-15

The following example prints TOP on line 1, TEST LINE on line 7, PRINT TWICE FOR
BOLDING on line 13, and the fields beginning on line 16:

, 0 No CR T!:lpe (HDTE>
Edit codes
IFetch overflow (F)
I X
I ISpace
Y Y 1 A J
I Y date edit
II I Skip
I Z zero suppress Y N 2 B K
II I I
I
N Y 3 C L
III I Indicators
IBlank-after (B)
N N 4 D M
File
III I I
Field IIEnd position
naPie
naPie I I I ForPiat (PB)
III I I
I
II I I I
I
II I I
01
I IBAB A NxxNxxNxxl
III
I+ Constant or edit wOI'd +
o I 1
I
2
I
3
I
4
151
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

00UT92A
0
0
0
0
0
0
0
0
0
0
0
0

***** * *

***---**
41

'TOP'

404-

'TEST LINE'

H 320411 1P
H 0

15 1P

N1P

30 'PRINT TWICE FOR BOLDING'
30 'PRINT TWICE FOR BOLDING'
DESCR
STOCK!!
ONHANDZ
PRICE K

18
26
31
39 '$'
ZK-4422-85

6-16

Using Printer Output Files

Sample output from this example might look like the following:

o
1
2
3
4
5 6 7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
TOP
2
3
4
5
6

TEST LINE

7
8
9

10
11
12
13
14
15
16
17
18
19
20

PRINT TWICE FOR BOLOING
1 LB CARROTS
6 PACK SOOA
1 LB BUTTER
STEAK
HEAD LETTUCE

'.IEG1MQ
DRNK2A
DAROBT
METO
'.lEG 1 WQ

47
40
38
L~

$.79
$1.48
$1. 59
$3.15
$.35

Using Printer Output Files

6--17

Chapter 7

Using Tables
A table is a collection of similar items arranged in a specific order. Each entry in a table
must have the same length and the same data type (either character or numeric). In
RPG II, you use tables to locate a specific item quickly and easily.
There are single tables and related tables. Single tables consist ofjust one group of similar
entries. When you search this type of table, the result of the operation lets you know
whether the item you are searching for is present in the table. If the search is successful,
that entry becomes the current entry.
Related tables are two associated tables (like a Table of Contents) that can be entered in
alternating format. For an example of alternating format using arrays, see Part I, Section
8.3.4. You search the first table to find out if the entry is present. If the entry is found,
RPG II retrieves the corresponding entry from the second table. Related tables need not
have the same number of entries unless they are described in alternating format in the
same Extension specification.
If you describe a table in alternating format, the first entry from the first table is read first;
then, the first entry from the second table is read. This alternate reading continues until
all entries from both tables are read. Together, the corresponding entries from each table
form one record.
Any table can be loaded at either compile time or pre-execution time. Loading is the process by which the program assigns the data you supply to the entries in the table.
The following characteristics help determine when a table should be loaded:
• Its contents
• The frequency with which its entries require changing
• The way it is to be used
Sections 7.1 and 7.2 describe compile-time tables and pre-execution-time tables.

7-1

7.1 Compile-Time Tables
Compile-time tables are part of the source program. They are compiled with the source
program and become a permanent part of the object program. The following example
shows a source program and a compile-time table:

o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
rINPUT
IPE F
FREPORT 0
E

II NPUT

30
40
TABA

DISK
DISK
10 50 5

5 ITEM
102FLD1
15 30 FLD2
1

I
I
I

ITEM

C 01
C N11
C
11

OREPORT

100
D

LOKUPTABA
SETON
ADD FLD1
01 11
NEW

H1
NEW

B 20

10001100021000310004100051000610007100081000910010
20001200022000320004100052000610007200082000920010
30001300023000330004100053000610007300083000930010
40001400024000340004100054000610007400084000940010
50001500025000350004100055000610007500085000950010
1*
ZK-4431·85

One advantage of compile-time tables is that they do not need to be loaded separately each
time the program is run. However, if you need to change any of the entries in a compiletime table, you must revise the table, and then recompile the program with the revised
table. You can, however, make temporary changes in the table during calculations. To
make these temporary changes permanent, you would have to output the table. See Section 7.8 for information about outputting tables.
The data in a compile-time table must follow the source program and alternate sequence
records, if any.

7.2 Pre-Execution-Time Tables
Pre-execution-time tables are not part of the object program. Rather, each table is loaded
separately from an input data file. One advantage of pre-exec uti on-time tables is that you
can make frequent changes to the table without recompiling the program.
Pre-execution-time tables are loaded before the first program cycle begins.

7-2

Using Tables

7.3 Creating Table Input Records
Table input records are the values for the entries in a table. When creating table input
records, observe the following rules:
• The first entry must begin in character position 1; all entries must be contiguous, with
no space between entries, as shown in Figure 7-1:
, . . . . - - - - - - - - - - - - record
/
entry

entry

1 234 567 890 1 2 3 4 567 8 9 0 1 2 3 4 5 6 7 890 1 2 3 4 5 6 7 890 1 234 567 8 9 0 ...

table
ZK-1471-83

Figure 7-1: Table Input Record
This table consists of five entries in a record, each entry being ten characters long.
• You cannot span an entry across two records. Therefore, the length of a record is limited to the device's maximum record length. If you use related tables in alternating
format, corresponding records cannot exceed the maximum record length.
• Each input record must have the same number of entries except the last. This record
can be shorter to accommodate an uneven number of entries.
When creating compile-time table input records, observe the following rules:
• The first record must be preceded by a record containing either double slashes (II) and
a blank or double asterisks (**) and a blank in character positions 1 through 3. Since
these strings are delimiters, records in a compile-time table cannot contain either of
these three characters in positions 1 through 3.
• The last record of the last table or array can be followed with a record containing a
slash and an asterisk (1*) in the first two character positions. This record is optional.
When creating table input records for related pre-execution-time and compile-time tables
in alternating format, you must enter an entry from the first table and then follow with the
corresponding entry from the second table.

Using Tables

7-3

If you define each entry from the first table to be one character long and each entry from
the second table to be three characters long, your table input record might appear as in
Figure 7-2:

,,
entry

13331333133313331333 .........
_ . _ - - - one record

ty,y

Imm ,eoood .able

entry from first table
ZK-1474-83

Figure 7-2: Related Tables
In this example, each record contains five entries. Each entry consists of two related
entries. The first entry is one character long. The second entry is three characters long.

7.4 Defining Tables
To define a single table, you must make the following entries in the Extension specification:
• Columns 27 through 32 (Table name) - Specify the name of the table. Table names
can be up to six characters long, but the first three characters must always be TAB.
• Columns 33 through 35 (Entries per record) - Specify the number of entries in a
record. Because tables can have one or more entries per record, calculate the maximum number of entries in a record by dividing the record length by the length of an
entry.
• Columns 36 through 39 (Number of entries per table) - Specify the number of entries
in the table.
• Columns 40 through 42 (Length of entry) - Specify the length of each entry.

7-4

Using Tables

• Column 43 (Data format) - If the table contains numeric data, you must specify its
format. Specify P (packed decimal format), B (binary format), or leave blank
(overpunched decimal format). When you specify packed decimal format, make sure
the Length of entry represents the length of the numeric data in unpacked form.
When you specify binary format, the Length of entry you specify must indicate the
number of bytes required to store the binary field. (Use 4 for two-byte signed binary
numbers or 9 for four-byte signed binary numbers.)
This column must be blank for a compile-time table.
• Column 44 (Decimal positions) - For numeric data, specify the number of positions to
the right ofthe decimal point. You must specify 0 for no Decimal positions.
• Column 45 (Sequence) - Specify A (ascending) or D (descending) to indicate that the
entries in a table are in the specified sequence, or leave this column blank to specify
an unsequenced table.
In the following example, the table name is TABLEl. There are 10 entries in the table,
with one entry in each record. The length of each entry is 5 digits, with 2 decimal positions.
The data type ofthe entry in each record is overpunched numeric by default.

------F = Forlllat (PB)
I -----D = Decilllal positions
I I ----S = Sequence (AD)
III

IllAlternating table or arra~
Table En tEnt Lenll Inallle Len
or
perin of Fill
of F
arra~ RecTbl EntlDl1
EntlD
I
I
nallle I I I IISI
I liS
I
I
I
I I I IIII
I 111+-- COllllllents ---+
E
011
12
I
3
I
4
I
5
16
I
7
I
1234567890123456789012345678901234567890123456789012345678901234567890123456789
Frolll
file
nallle

To
file
nallle

TABLE1

*--*---*--****
1 10 5 2

ZK-4423-85

You can define one or two tables either individually, or as a table with an alternate table
defined in alternating format. To define an alternate table, you must make the following
entries for the alternate table in the same Extension specification you used to describe the
main table:
• Columns 46 through 51 (Table name) - Specify the name ofthe alternate table. Table
names can be up to six characters long. The first three characters must be TAB.
• Columns 52 through 54 (Length of entry) - Specify the length of each entry in the
alternate table.

Using Tables

7-5

• Column 55 (Data format) - If the alternate table contains numeric data, you must
specify its format. Specify P (packed decimal format), B (binary format), or leave
blank (overpunched decimal format). When you specify packed decimal format, make
sure the Length of entry represents the length of the numeric data in unpacked form.
When you specify binary format, the Length of entry you specify must indicate the
number of bytes required to store the binary field. (Use 4 for two-byte signed binary
numbers or 9 for four-byte signed binary numbers.)
This column must be blank for a compile-time table.
• Column 56 (Decimal positions) - For numeric data, specify the number of positions to
the right of the decimal point. You must specify 0 for no Decimal positions.
• Column 57 (Sequence) - You can specify A (ascending) or D (descending) to indicate
that the entries in a table are in the specified sequence, or leave this column blank to
specify an un sequenced table.
The main table's values for Entries per table (columns 36 through 39), From file name (columns 11 through 18), and Entries per record (columns 33 through 35) are also used for the
alternate table.
In the following example, two related tables are loaded from the input file INPUT. The
second table, TAB2, is the alternate table.

------F = Forlllat (PB)
I -----D = Decilllal positions
I I ----S = Sequence (AD)
III

II IAlternating table or arra~
Table En tEnt Lenll Inallle Len
or
perin of Fill
of F
arra~ RecTbl EntlDI I
EntlD
nallle I I I liS I
I I IS
I
I
I
I I
I I111
I 111+-- COllllllents ---+
E
I
I
011
12
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Frolll
file
nallle

*.... *
E

INPUT

To
file
nallle

TAB1

*--*---*--*****
2

4 5 OATAB2

*--****
5 OA

ZK·4424·85

When defining compile-time tables, observe the following rules:

• If the compile-time table contains numeric data, it must be in overpunched format.
Therefore, leave column 43 (Data format) blank or leave column 55 (Data format)
blank, if you are using related tables in alternating format.
• The input records for compile-time tables must be in the same order in which the
tables appear in the Extension specification.

7-6

Using Tables

To define a pre-execution-time table, make the same entries you made for a single table.
Also, in columns 11 through 18 (From file name), enter the name of the input file that
contains the data for the table, as shown in the following example:

------F = Forlllat (PB)
I -----D = Decilllal positions
I I ----5 = Sequence (AD)
III
I I IAlternating table or arra~
Frolll
To
Table EntEnt Lenl I Inallle Len
file
file
or
perin of Fill
of F
nallle
nallle
arra~ RecTbl EntlDl1
EntlD
I
I
nallle I I I I IS I
I I IS
I
I I
I IIII
I 111+-- COllllllents ---+
I
I
E
011
12
I
3
I
4
1516
I
7
I
12345678Q01234567890123456789012345678901234567890123456789012345678901234567890

*.... *
E

INPUTFIL

*--*---*--*****

TABLEA 10 50 5

ZK-442S-8S

The table input file must be defined in a File Description specification with T in column 16
(File designation).
When using pre-execution-time tables, observe the following rules:
• The input file cannot contain more entries than are defined for the table. If it does, a
run-time error occurs_
• The input file can contain fewer entries than are defined for the table, only if you do
not specify a sequence. When you do not specify a sequence and the table contains
fewer entries than are defined, the remaining entries are automatically filled with
blanks for character data or zeros for numeric data.

7.5 Searching Tables
The LOKUP operation code searches for an entry in a table. This operation starts with the
first entry, and searches each element for a match with the search argument. Specifying a
table sequence is not necessary when performing LOKUP operations for an equal match.
However, if you specify a sequence, the table can be searched faster. To save time searching
an unsequenced table, place the more frequently referenced entries at the beginning of the
table_

Using Tables

7-7

To search a table for an entry, you must make the following entries in the Calculation specification:
• Columns 18 through 27 (Factor 1) - Specify a field or literal representing the entry
you want to locate. Make sure the search argument has the same length and data
format as the entries of the table being searched.
• Columns 28 through 32 (Operation code) - Specify the LOKUP operation code.
• Columns 33 through 42 (Factor 2) - Specify the name ofthe table to be searched.
• Columns 54 through 59 (Resulting indicator) - Specify one or more indicators to condition the search and to indicate whether the search has been successful. You can use
this indicator to condition subsequent calculation and output operations.
In the following example, the program tries to match the search argument, ITEM, with an
entry in the table, TABA. If a matching entry is found, indicator 11 is set on. If no matching
entry is found, the halt indicator, H1, is set on and the program terminates.
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

rINPUT IPE F
30
DISK
FREPORT 0
40
DISK
E
TABA 10 50 5
IINPUT AA 01
I
1 5 ITEM
I
6 102FLDI
I
15 30 FLD2
C 01
ITEM
LOKUPTABA
11
C N11
SETON
HI
C 11
100
ADD FLDI
NEW
62
OREPORT D
01 11
0
NEW
B 20
II

In this compile-time table, there are ten entries in a record and fifty entries in a table. Each
entry is five characters long.

7-8

Using Tables

When you specify a sequence (either ascending or descending), you can use resulting
indicators (EQUAL, HIGH, and LOW) in the Calculation specification to indicate the condition to search for and the result ofthe search. You can specify one of the following search
conditions:
• Columns 54 and 55 (HIGH) - Nearest to but greater than value only
• Columns 56 and 57 (LOW) - Nearest to but less than value only
• Columns 54 and 55, and 58 and 59 (EQUAL or HIGH) - Equal or nearest to but
greater than value
• Columns 56 and 57, and 58 and 59 (EQUAL or LOW) - Equal or nearest to but less
than value
The following program searches the unsequenced table TABLE2 for the value LENGTH,
and searches the sequenced table TABLEl to check for a value greater than or equal to
COST. If both conditions are satisfied, the subroutine PROCES is called to process the
entry.

o
I
1
I
2
I
3
141
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
· ... . **. *....

•••

•••••••

*.... *......... *.

•••

*--*** *. *
I

1*' •••••••

•

••••

FrILE1 IT F 80 80
EDISK
FrILE2 IT F 80 80
EDISK
rINrILE IP F 80 80
DISK
E
FILE1
TABLE1 1 6 3 2A
E
FILE2
TABLE2 1 6 3 0
II NrILE AA 11
I
1 32COST
I
0460LENGTH
I
7 100NUHBER
C 11
LENGTH
LOKUPTABLE2
20
C N20 11
GOTO NOPROC
COST
LOKUPTABLEl
26 26
G 11
GO TO NOPROC
C N26
C
EXSR PROCES
C
NOPROC
TAG
ZK·4430·85

You can also specify a table in the Result field to retrieve the entry that corresponds to the
entry located in a LOKUP operation. (See the example in Section 7.6.)

Using Tables

7-9

7.6 Referencing Table Entries
When you use a table name as an operand in an operation other than as Factor 2 or other
than as the Result field in a LOKUP operation, the table name refers to the data retrieved
by the last successful search. You can then use the entry as an operand in a calculation or
modify the contents of the entry when the table name is used as the Result field in a
calculation.
In the following example, FLDI is the search argument in the LOKUP operation. If the
program can locate FLDI in TAB1, indicator 10 is set on. Then, the result of the calculation on the next line replaces the current contents of the located entry in TAB 1 because the
table entry is used as the Result field.

Contro I Ieve I
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I
1
CI N)()(N)()(Nx)(1

Factor
2
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resultl llindicators
field I II + - 0
I
I II> < = +- Co~~ents --+

011
12
I
3
I
4
I
5
I
6
I
7
I
1?34Rh78901234567890123456789012345678901234567890123456789012345678901234567890

. ~ .. . **. *.
C

••••••

*..

FLD1

TAB1

•

•••

1*' I

••

*......... *..

LOKUPTAB1
HULT 100

TAB1

•••

--***. *. * *
10
I

••••••

•• I

••••••••

ZK-4426-85

You can specify which entry is the current entry for related tables, and then reference the
current entry in subsequent calculations. In the following example, FLDI is the search
argument in the LOKUP operation. If the program locates FLDI in TAB1, that entry
becomes the current entry. Then, RPG II locates the corresponding entry in TAB2 and it
then becomes the current entry for TAB2. When you reference these entries in subsequent
calculations, RPG II uses the current entry in both tables.

7-10

Using Tables

Factor

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resu It I I Iindicators

field I

Control level
I

I Indicators

Operation

I I
I I
I I

I
I
I
I

Factor
1

CI N)()(N)()(N)()(I

0111213

11+-0

I II> < = +- Co~~ents --+

12~456789012~4567890123456789012345678901234567890123456789012345678901234567890

..... **.* ........ *.,.

•••••

FLD1

*.... *......... *..... *--***.*.*.* ......
LOKUPTAB1

TAB2

••

••••••••

ZK-4427-85

7.7 Updating Tables
To change the contents of an entry in or add new entries to a pre-execution table, edit the
input file that contains the table. You can also use a program to modify a table and output
the new entries.
The following example searches related tables in alternating format. The first table TABA
consists of a list of numbers of items in stock. The second table TABB consists of a list of
unit prices corresponding to the item numbers. We want to raise the unit price of each item
by 5% and output the updated table.
01112
I
3
1
4
1
516171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
***** * *
* ***---**
FMASTER IPE F
30
DISK
HABLEt IT F
EDISK
22
HABLE2 0 F
22
DISK
FREPORT 0 F
60
DISK
E
TABLEt TABLE2 TAB A 2 10 5 TABB
IMASTER AA 01
I
C

01
C Nl1
C

OREPORT D
0

ITEM

LOKUPTABA
SETON
MULT TABB

1.05

TABB
TABB

5 ITEM
62H

TABB

20
ZK-4428-85

The related tables TABA and TABB are pre-execution-time tables. They are loaded from
the input table file TABLEl. In the Extension specification, the output file TABLE2 is
automatically created. (Automatic creation means that the output file does not require an
Output specification.)

Using Tables

7-11

When the program executes, it reads the first record from the primary input file MASTER.
ITEM is the search argument. If the search argument is matched, indicator 11 is set on and
the corresponding entry from TABB is made available for processing. Ifno match is found,
the halt indicator HI is set on and the program terminates without creating the output file
TABLE2.
When the program ends, the tables TABA and TABB are written to file TABLE2 with the
same number of Entries per record as the table input file TABLEl.

7.8 Outputting Tables
When you specify the name of an output file in columns 19 through 26 (To file name) of the
Extension specification, your program creates the file automatically, as shown in the
example in Section 7.7.
When you specify a table as a field on an Output specification, you can output only the
entry found by the last LOKUP operation.
In the following example, the table TABSH is read from the file TABFILE. For this example, the table is short, meaning not all 80 entries contain data. The LOKUP operation
searches the table for the first entry containing zeros. This entry is replaced with a field
read from the input file IFILE. The EXCPT operation code outputs the entry TABSH with
the new data. Remember, the entry that is updated and then output by the Output specification is the entry found by the last LOKUP operation. When the last cycle occurs, the
entire updated table will be written to the file TABFILE2.
011
1213
14
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***---**

***** * *

*
FIFILE IP F
80
DISK
FTABFILE IT F
80
EDISK
FTABFILE20 F
80
DISK
DISK
FOFILE 0 F
80
E
TABFILE TABFILE2TABSH 10 80 4 0
IIrILE AA 01
I

C 01 20
C 01 20
OOrILE E

0000

LOKUPTABSH
Z-ADDENTRY
EXCPT
TABSH

TABSH

40ENTRY

10
ZK-4429-85

7-12

Using Tables

Chapter 8

Usi ng Arrays
An array, like a table, is a collection of similar items arranged in a specific order. You can
reference individual array elements by specifying an array index, or process an entire
array by specifying the array name during calculation operations.
You use an array instead of a table when you want to affect all the elements in the array
with a single reference or to reference a number of separate entries at the same time. For
example, when you want to compute a 5% sales tax for each element in an array, you use a
single specification to perform the operation for every element.

8.1 Types of Arrays
Array types are differentiated at the time they are loaded. An array can be loaded at any
one ofthe following times:
• Compile time
• Pre-execution time
• Execution time
Loading is the process by which the program assigns the data you specify to the elements
in an array.
The following characteristics determine when an array should be loaded:
• The contents of an array
• The frequency with which the elements in the array require changing
• The way the array is to be used

8-1

8. 1.1 Compile-Time Arrays
Compile-time arrays are part of the source program; they are compiled with the source
program and become a permanent part of the object program. One advantage of compiletime arrays is that they do not need to be loaded separately each time the program is run.
However, if you need to change any ofthe entries in a compile-time array, you must revise
the array, and then recompile the program with the revised array. You can, however, make
temporary changes in the array during calculation operations. To make these temporary
changes permanent, you would have to output the array and then, using the output file as
input, recompile the program. See Section 8.8 for information about outputting arrays.
When you use a compile-time array, the array input data must follow the source program
and any alternate sequence (ALTSEQ) records. If you use more than one array, the data for
each array must follow in the same sequence as is specified on the Extension specifications.

8-2

Using Arrays

The following example shows a source program with the input data for two compile-time
arrays and their alternate compile-time arrays:

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

01010H
NOPRIN
01040FPROCD IP F
80
DISK NOPDAT
NOPRIN
01050FINLIST 0 F
132
OF
PRINTER
NOPRIN
02010E
AR1
1 5 5 OAALT
20
NOPRIN
02020E
AR2
4 4 5 OAALT
42
03010IPROCD AA 01
030201
1 50PRODNO
030301
6 80QUAN
04010C
Z-ADD1
I
20
PRODNO
LOKUPAR1,I
04020C
20
Z-ADD1
T
04030C
20
PROD NO
LOKUPAR2,T
04040C
21
QUAN
MULT ALT2,T
04050C 21
AMT
72
050100INLIST H 201 1P
050200
OR
OF
,
020300
UDATE
18 ' 1 1
050400
47 'INVENTORY PARTS LIST'
PAGE
65 , o '
050500
050600
H 1
1P
050700
OR
OF
050800
32 'PRODUCT
PRODUCT'
53 'UNIT'
050900
H 2
1P
051000
051100
OR
OF
17 'NUMBER'
051200
45 'DESCRIPTION
QTY'
051300
051400
64 'PRICE
AMOUNT'
060100
D 1
01
060200
PRODNO
16'
0'
ALTi, I
20
39
060300
N20
060400
39 '***NO DESCRIPTION***'
ALT2,T
060450
21
53 ' O. '
QUAN
060500
45 ' 0 '
060700
53 '*NONE'
N21
AMT
65' , O.
060800
21
T1
060900
LR
27 'END OF PRICE LIST'
061000
**
17526BOLT
co~pile-ti~e arra~ AR1
18171SCREW
and
the alternate co~pile-ti~e
19226NAIL
arra~ ALTi
25116NUT
29258MAGNESIUM COVER
co~pile-ti~e arra~ AR2 and
**
175260126181710059192260173292585843
the alternate co~pile-ti~e
at·t·a~ AL T2
1*

}
}

ZK-4448-85

U sing Arrays

8-3

8.1.2 Pre-Execution-Time Arrays
Pre-execution-time arrays are not part of the object program. Rather, each array is loaded
separately (before the first program cycle begins) and is used like an input data file. One
advantage of pre-execution-time arrays is that you can make frequent changes to the
array without recompiling the program.

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

8.2 Creating Array Input Records
When creating array input records for compile-time and pre-execution-time arrays,
observe the following rules:
• The first entry must begin in character position 1; all entries must be contiguous, with
no space between entries, as shown in Figure 8-1:

entry \

1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 a 1 2 3 4 5 6 7 8 9 a 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0...

array

ZK-1473-83

Figure 8-1: Array Input Record
This array can be defined to consist of five entries. Each entry is ten characters long.
• Each array input record must have the same number of entries except the last. This
record can be shorter to accommodate an uneven number of entries.
• You cannot span an entry across two records. Therefore, the length of a record is limited to the device's maximum record length. If you use related arrays in alternating
format, corresponding entries cannot exceed the maximum record length.
When creating compile-time array input records, observe the following rules:
• The first record must be preceded by a record containing either double slashes (II) and
a blank or double asterisks (**) and a blank in character positions 1 through 3.
Because these strings are delimiters, compile-time array records cannot contain these
characters in positions 1 through 3.

8-4

Using Arrays

• The last record of the last compile-time table or array can be followed by a record containing /* in the first two character positions. This must be the last record in the
source program, if used.
When creating array input records for related pre-execution-time and compile-time arrays
in alternating format, you must enter an entry from the first array and then follow with
the corresponding entry from the second array.
If you define each entry from the first array to be one character long and each entry from
the second array to be three characters long, your array input record might appear as in
Figure 8-2:
entry

12221222122212221222

tYIc'

- ___- - one record

'<om second ",m,

entry from first array
ZK-1472-83

Figure 8-2: Related Arrays
In this example, each record contains five entries. Each entry consists of two related
entries. The first entry is one character long. The second entry is three characters long.

8.3 Defining Arrays
To define any array, you must make the following entries in the Extension specification:
• Columns 27 through 32 (Array name)-Specify the name ofthe array. You cannot use
TAB as the first three letters of an array name.
• Columns 36 through 39 (Number of entries per array)~Specify the number of entries
in the array.
• Columns 40 through 42 (Length of entry)-Specify the length of each entry.
• Column 44 (Decimal positions)-For numeric data, specify the number of positions to
the right of the decimal point. You must specify 0 for no decimal positions.
You can indicate an order to the records in an array by specifying either A (ascending) or D
(descending) in column 45 (Sequence) of the Extension specification.

U sing Arrays

8-5

8.3.1 Defining a Compile-Time Array
To define a compile-time array, you must make the following entry in the Extension specification in addition to the entries required for all arrays:
• Columns 33 through 35 (Entries per record)-Arrays can have one or more entries per
record. The length of all entries in a compile-time array cannot exceed 96 characters.
All records, except the last, must contain the same number of entries; each entry must
be the same length.
The following example describes the compile-time array AI. The array has eight entries
with four entries in each record. Each entry is a character field that is six bytes long. The
array records are located at the end ofthe program.

------F = Forlllat (PB)
I -----D = Decilllal positions
I I ----S = Sequence (AD)
III

I IIAlternating table or arra~
Table EntEnt lenl I Inallle len
or
perin of FIll
of F
arra~ RecTbl EntlDl1
EntlD
nallle I I I I ISI
I I IS
I
I
I
I I
I IIII
I I II +-- COllllllents ---+
E
I
I
011
1213
I
4
I
5
I
6
I
7
I
12345&78901234567890123456789012345678901234567890123456789012345678901234567890
*.. 1'*
*
*Ai *--*---*--*****
E
486
Frolll
file
nallle

To
file
nallle

**
KAUNISKAUPPANAINENKAIKKI
MUKAVAPAlJONJUUSTOOSOITE
1*
ZK-4434-85

8.3.2 Defining a Pre-Execution-Time Array
To define a pre-execution-time array, you must make the following entries in the Extension specification in addition to the entries required for all arrays:
• Columns 11 through 18 (From file name)-Specify the name ofthe input file that contains the data for the array. This input file is called a table input file. It must be
defined in a File Description specification with T in column 16 (File designation); the
T associates the file with the array.

8-6

U sing Arrays

• Columns 33 through 35 (Entries per record)-Arrays can have one or more entries per
record. The length of all entries in a pre-execution-time array cannot exceed the maximum number of characters for the device from which the array is loaded. All records
except the last must contain the same number of entries; each entry must be the same
length.
If your pre-execution-time array contains numeric data, you can indicate the data format
by specifying P (packed decimal format) or B (binary format), or by leaving the column
blank (overpunched decimal format). When you specify packed decimal format, make sure
the Length of entry represents the length of the numeric data in unpacked form. When you
specify binary format, the Length of entry you specify must indicate the number of bytes
required to store the binary field. (Use 4 for two-byte signed binary numbers or 9 for fourbyte signed binary numbers.)
When using pre-execution-time arrays, observe the following rules:
• The input file cannot contain more entries than are defined for the array. If it does, a
run-time error occurs.
• The input file can contain fewer entries than are defined for the array, only if you do
not specify a sequence. When you do not specify a sequence and the array contains
fewer entries than are defined, the remaining entries are automatically filled, either
with blanks for alphanumeric data or with zeros for numeric data.

8.3.3 Defining an Execution-Time Array
To define an execution-time array, no additional entries need be made in the Extension
specification over those that are required for all arrays.
If you want to load an execution-time array from an input file, you must make the following entries for the array input file in its Input specification:
• Column 43 (Data format)-When using arrays containing numeric data, indicate the
data format by specifying P (packed decimal format) or B (binary format), or by leaving the entry blank (overpunched decimal format).
• Columns 44 through 51 (Field location)-Specify the beginning and ending character
positions of the entire array, partial array, or array element being loaded. If the data
format is packed decimal or binary, the field location must represent the actual size of
an array element in bytes.
The following example shows how to use the Input specification to load an entire execution-time array containing packed decimal numbers as a single field. The array, ARR, contains seven elements; each element is four bytes long. The execution-time array is loaded
from the input file ARRIN as a single field in packed decimal format.

Using Arrays

8--7

011

12345678901234567890123456789012345678901234567890123456789012345678901234567890

IARRIN

ARR

AA 03

770

1 280ARR
ZK-4435-85

You can load part of an execution-time array using one input field. The length ofthe field
must be a multiple ofthe length of one entry. The array is loaded beginning with the first
element and continues loading elements until it reaches the end ofthe input field.

011

12345678901234567890123456789012345678901234567890123456789012345678901234567890

IARRIN

AA 03

ARR

25 1

1 100ARR
ZK-4436-85

In this example, ARR contains 25 entries. Each entry is one character long. RPG II loads
the first ten elements ofthe array ARR.

8.3.4 Defining Related Arrays in Alternating Format
You can define related arrays either individually or in alternating format. To define arrays
in alternating format, you must make the following entries for the second (alternate)
array in the same Extension specification you used to describe the first (main) array:
• Columns 46 through 51 (Array name)-Specify the name of the alternate array.
• Columns 52 through 54 (Length of entry)-Specify the length of an entry in the alternate array.
• Column 55 (Data format)-You need only specify the data format for alternate preexecution-time arrays that contain numeric data. Specify P (packed decimal format)
or B (binary format), or leave the entry blank (overpunched decimal format). When
you specify packed decimal format, make sure the Length of entry represents the
length of the numeric data in unpacked form. When you specify binary format, the
Length of entry you specify indicates the number of bytes required to store the binary
field. (Use 4 for two-byte signed binary numbers or 9 for four-byte signed binary
numbers.)

8-8

Using Arrays

• Column 56 (Decimal positions)-For numeric data, specify the number of positions to
the right of the decimal point. You must specify 0 for no decimal positions.
• Column 57 (Sequence)-You can indicate the order of entries in an alternate array by
specifying either A (ascending) or D (descending).
The entries made in the following columns for the main array also apply to the alternate
array:
• Columns 11 through 18 (From file name)
• Columns 33 through 35 (Entries per record)
• Columns 36 through 39 (Entries in array)
The following example describes the pre-execution-time array A1 with six entries in each
record and 24 entries in the array. The entries for array A1 are alternated with entries for
array Bl. A1 contains overpunched numeric data that is six digits long with no decimal
places. B1 contains overpunched numeric data that is four digits long with two decimal
places. Each record in the data file contains 6 entries for A1 and 6 entries for Bl. The
arrays are loaded from the file ARRFIL.
A sample record from ARRFIL might look like this:
000001245000000216240000034520000004799000000577770000066550
\

t t t t

Aid Bid Al.2 Bl.2

------F = Forlllat (PB)
I -----D = Decilllal positions
II ----5 = Sequence (AD)
III
I IIAlternating table or arra~
Frolll
To
Table EntEnt Lenl I Inallle Len
file
file
per in of Fli I
of F
or
nallle
nallle
EntlD
arra~ RecTbl EntlDl1
I
nallle I I I 1151
I liS
I
I I I 1111
I 111+-- COllllllents ---+
E
I
I
I
o I 1 I 2 I 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
E

ARRFIL

*A1

*--*---*--*****
6

6 0 B1

ZK-4437-85

U sing Arrays

8-9

8.4 Referencing Arrays
With tables, you can reference only the entry retrieved by the last LOKUP operation. With
arrays, you can refer to either an entire array or to an individual array element. One
advantage of referring to an entire array is that a single operation can affect all the elements in the array.
You can specify an array name, a comma, and an index that is up to ten characters for
Factor 1 or Factor 2 in a Calculation specification. You can specify an array element that is
up to six characters for the Result field.
You can use an entire array as Factor 1, Factor 2, or the Result field in the following operations:
• ADD
• Z-ADD
• SUB
• Z-SUB
• MULT
• DIV
• SQRT
• MOVE
• MOVEL
• MOVEA
• XFOOT
• LOKUP
• PARM
When you specify an array name in the following calculations, RPG II repeats the operation for each element in the array:
• ADD
• Z-ADD
• SUB
• Z-SUB
• MULT

8-10

Using Arrays

• DIV

• SQRT
• MOVE
• MOVEL

• PARM
When using entire arrays (non indexed) in any ofthe above calculations, observe the following rules:
• When you specify arrays with the same number of elements for Factor 1, Factor 2, and
the Result field, RPG II performs the operation on the first element, then on the second element, and so on, until all the elements in the array have been processed.
If the arrays do not have the same number of elements, RPG II ends the operation
when the last element of the array with the fewest elements is processed.
• When one Factor is a field or constant and the other Factor or Result field is an entire
array, RPG II performs the operation once for every element in the array.
• If the operation requires Factor 2 only and the Result field is an array, RPG II performs the operation once for every element in the array.
• You must specify an array for the Result field.
• You cannot use resulting indicators to condition calculations with arrays.
If you use an array for the Result field and an element as one ofthe Factors in a calculation,
RPG II alters the value of the element as a result of the calculation. When this occurs,
RPG II uses the new value in all subsequent operations that reference that element.
Suppose two numeric arrays have the data in Table 8-1:

Table 8-1: Array Element Values
Array Element

Value

ARRl,1
ARRl,2
ARRl,3
ARRl,4

4
3

ARR2,1
ARR2,2
ARR2,3
ARR2,4

2
7
5
9

U sing Arrays

8-11

If every element of ARR1 is added to element ARR2,3 and the result is placed in ARR2, the
elements of the resulting array are in Table 8-2:

Table 8-2: Array Elements in Calculations
Array Element

Expression

Resulting Value

ARR2,1
ARR2,2
ARR2,3
ARR2,4

(4 + 5)
(3 + 5)
(1 + 5)
(5 + 6)

9
8
6
11

You can specify an array element in most operations that take a character or numeric field
as Factor 1, Factor 2, or the Result field. To specify an individual array element, code the
array name, a comma, and the index. For example, ARR,12 specifies the twelfth element of
array ARR. You can also use a field name to represent the index. For example, if you specify ARR,FLD, the index value is determined by the value of the field FLD.
An array index, whether it be a literal or a field, must always be greater than or equal to 1
and less than or equal to the number of elements in the array. If it is not, and you specify
the CHECK = (BOUNDS) qualifier to the RPG command, a run-time error will occur. If
not, and you do not specify the CHECK = (BOUNDS) qualifier to the RPG command,
unpredictable results will occur.
If you plan to use the same array element in a calculation for every program cycle, use a
constant number as the index. If, however, you want to reference different array elements,
use a field name as the index.

When array elements are scattered throughout an input record, each field must be
described individually on the Input specification. A field description indicates the position
of an element in the array. In such cases, there are two ways to load the data into the array:
• Assign a unique field name to each field of array data on the input record, and then
code calculations to move each data field individually into the appropriate array
element .
• Assign the array name with the proper index to each field of array data in the input
record. The array is loaded automatically as the data is read.

8-12

Using Arrays

'",

The following example shows you how to load each element of an execution-time array
individually:

011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

E
IARRIN
I
I
I
I
I
I
I

AA 03

ARR

7 70
P
P
P
P
P
P
P

40ARR,1
80ARR,2
120ARR,3
160ARR,4
200ARR,5
240ARR,6
280ARR,7

1
5
9

13
17
21
25

ZK-4438-85

In the following example, a company employs eight salespeople whose weekly sales
amounts are recorded in an input file. Each record of the file contains the weekly sales
amounts; one new record is recorded in the file each week. At the end ofthe year, the company likes to have a report listing the sales totals for each week and the grand total for the
entire year.
011

171

1?34567RqOt?34~67890t23456789012345678901234567890123456789012345678901234567890

fINPUTl IPE r
60
DISK
rREPORT 0 r
DISK
60
E
WEEK
8 6 2
YEAR
E
8 8 2
II NPUTl AA 01
1 482WEEK
I
C 01
XrOOTWEEK
TOTAL 82
WEEK
ADD YEAR
YEAR
C 01
CLR
XrOOTYEAR
GRAND 102
OREPORT D
-01
20 'WEEKLY TOTAL='
0
,
35 '$
TOTAL
0
T
0
LR
0
20 'YEARLY TOTAL='
35 '$ ,
0
GRAND
ZK-4439-85

Using Arrays

8-13

Two execution-time arrays, WEEK and YEAR, are defined in the Extension specification.
The Input specification tells the program to load the array WEEK after reading each sales
record from the input file INPUTl.
The input file for the execution-time array is not like a table input file with a corresponding File Description specification. Therefore, data is not automatically loaded into the
array at the beginning of execution. Instead, you must describe the input data to be loaded
into the array on Input specifications.
The array elements are in consecutive positions in the input record. Therefore, when the
name of the array is specified as the field name, the data is automatically loaded into the
appropriate elements of the array as the input record is read. In this case, only one Input
specification is necessary to describe an input record of array data.
The XFOOT operation calculates the sum of all the elements in the array WEEK and puts
the sum in the Result field TOTAL. The next calculation adds one array to the other.
Adding arrays involves adding each element of one array to the corresponding element of
the other array. Normally, when you use an array name in a calculation, the operation is
performed on each element ofthe array; then, an array of the results is created. Therefore,
you cannot use resulting indicators to indicate the result ofthe operation.
These arrays have the same number of elements; therefore, any specified operation is performed until all elements have been processed. In the case oftwo arrays containing different numbers of elements, the specified operation would be performed only until the last
element in the shorter array was processed.
In the following example, the program produces results identical to those of the previous
example. However, here the array elements are scattered throughout the input record.

S-14

Using Arrays

o
I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
t?345678901234567890123456789012345678901234567890123456789012345678901234567890
FINPUT2
FREPORT
E
E
IINPUT
I
I
I
I
I
I
I
I
C 01
C 01
CLR
OREPORT

IPE F
F

60
60
WEEK
YEAR

AA 01

WEEK
D

0
0

DISK
DISK
8 6 2
8 8 2

XFOOTWEEK
ADD YEAR
XFOOTYEAR

1 62WEEK,1
8 132WEEK,2
15 202WEEK,3
22 272WEEK,4
29 342WEEK,5
36 412WEEK,6
43 482WEEK,7
50 552WEEK,8
TOTAL 82
YEAR
GRAND 102

TOTAL

20 'WEEKLY TOTAL='
,
35 '$

GRAND

20 'YEARLY TOTAL='
35 '$ ,
ZK-4440-85

8.5 Searching Arrays
The LOKUP operation code can search for an element in an array. To determine whether a
particular element exists, you specify a search argument and define the conditions under
which the LOKUP operation will succeed. You must also use a resulting indicator that
specifies the condition and that will indicate the result of the LOKUP operation. The indicator is set on only if the search is successful; otherwise, the indicator is set off. When
searching for a HIGH or LOW condition, you must specify a sequence for the array in column 45 (Sequence) of the Extension specification. Enter an indicator in these columns to
test for the following conditions:
• Columns 58 and 59 (EQUAL)-Equal
• Columns 54 and 55 (HIGH)-Nearest to but greater than value
• Columns 56 and 57 (LOW)-Nearest to but less than value
• Columns 54 and 55, and 58 and 59 (EQUAL or HIGH)-Equal or nearest to but greater
than value
• Columns 56 and 57, and 58 and 59 (EQUAL or LOW)-Equal or nearest to but less
than value
Using Arrays

8-15

If you specify both EQUAL and HIGH or EQUAL and LOW, the EQUAL condition takes
precedence if entries satisfy both conditions.
To search an array for an element, you must make the following entries in the Calculation
specification:
• Columns 18 through 27 (Factor I)-Specify a field, literal, array element, or table representing the element you want to locate. Make sure the search argument has the
same length and data format as the elements in the array being searched.
• Columns 28 through 32 (Operation code)-Specify the LOKUP operation code.
• Columns 33 through 42 (Factor 2)-Specify the name of the array to be searched.
• Columns 54 through 59 (Resulting indicator)-Specify one or more indicators to test
for a condition and to indicate whether the search has been successful. You can use
these indicators to condition subsequent calculation and output operations.
In the following example, the program tries to match the search argument QTY with an
entry in the array ARR. If a matching entry is found, indicator 11 is set on. If the entry is
not found, indicator 11 is set off.

Control level
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I

CI N)()(N)()(N)()(I

Factor
2
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I II Resul ting
Resu It I II indicators
field I 11+ - 0
I
I II) < = +- Co~~ents --+

011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

*GlTV

* *
LOKUPARR

*--fl* * * *
11

ZK-4441-85

8-16

Using Arrays

If you want to start searching an array at some point other than at the beginning, specify
the array and its index where you want to begin the search. The index can be a literal or a
field name. In the following example, the search begins with the seventh element of array
ARR:

Field length
I Deci~al positions
I
I IHaif adjust (H)
I Indicators
Operation
I II
I I
I
I IIResulting
I I
Factor
Factor
Resultl II indicators
I
I I
1
2
field I 11+-0
I
CI NxxNxxNxxl
I
I
I
I II> < = +- Co~~ents --+
o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contro I Ieve I

**
C *01

*QTY

* *
LOKUPARR,7

*
ZK·4442-85

If you want to reference the element found in the last LOKUP operation, specify the array
name and an index field in Factor 2 ofthe LOKUP operation. If the search is successful, the
index value ofthe array element that satisfied the condition is stored in the index field and
the resulting indicator is set on. If the search is unsuccessful, the value 1 is placed in the
index field and the resulting indicator is set off. If you do not specify the index field, a successful LOKUP operation indicates whether an element contains the data for which you
are searching, but does not return the element's index value.
If you want to begin the search with the first element, you must initialize the index field to
1 before the LOKUP operation.

You can also search for more than one array element by locating all the elements in an
array that satisfy a certain condition. When the condition is satisfied, the program adds 1
to the value in the index field to continue the search with the next element.
In the following example:
• The program loads a pre-execution-time array from the file INPUTl.
• The search argument SEARCH contains the value of 50000; the LOKUP operation
searches for any array element containing a value lower than the search argument.
• If the search is successful, indicator 56 is set on. This indicator causes the EXCPT
operation to print the contents of each array element (with its index) that satisfies the
search condition.

• After the program prints the array element, it sets indicator 56 off and adds 1 to the
field containing the array index. As long as the index field remains below 11, the
search continues by setting indicator 54 on; this causes the program to loop back to
line 01090. This process continues until all 10 elements are searched.

Using Arrays

8-17

011
12
I
3
I
4
I
5
I
6
171
1234567890123456789012345678901234567890123456789012345678901234567890123456789

01020FINPUTl IT F
50
EDISK
01030FINPUT2 IPE F
10
DISK
02040FOUTPUT 0 F
60
DISK
01050E
INPUTi
ARYl
10 10 5 OD
010601lNPUT2 AA 01
010701
1 50SEARCH
01080C 01
Z-ADDl
I
20
01090C
LOOP
TAG
01100C 01
SEARCH
LOKUPARYl, I
56
01105C 56
EXCPT
01107C
SHOF
56
01110C 01
1
ADD I
I
01120C 01
11
COMP I
54
01130C 01 54
GO TO LOOP
0114000UTPUT E
56
7 'INDEX='
011500
011600
I
9
011700
18 'VALUE='
011800
ARYl, I
23
ZK-4443-85

An example of the output file might appear as follows:
0 2 3 4 5 6 7
12345678901234567890123456789012345678901234567890123456789012345678901234567890
INDEX=06
INDEX=07
INDEX=08
INDEX=09
INDEX=10

VALUE=40000
VALUE=30000
VALUE=20000
VALUE=10000
VALUE=OOOOO

The column numbers in this example are for reference and do not appear in the output.

8.6 Moving Array Data
You can use the MOVE A operation code to move:
• Contiguous array elements to a field
• A field or literal to contiguous array elements
• Contiguous elements of one array to contiguous elements of another array

8-18

Using Arrays

Ifthe array is not indexed, data movement starts with the first element of an array or field.
Ifthe array is indexed, the move starts with the element you specify. Data movement stops
when either ofthe following conditions is met:
• The last array element is moved or filled .
• The number of characters moved equals the length of the shorter field, as specified
either in columns 33 through 42 (Factor 2) or in columns 43 through 48 (Result field)
of the Calculation specification.
See Part II, Chapter 3 for more information on the MOVEA operation code.
The following example shows a pre-exec uti on-time array ARR20 being loaded from the file
ARRFILE. A copy of ARR20 is moved into the execution-time array ARR15 using the
MOVEA operation code.

o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FARRFILE IT F
E
ARRFILE
E
C

EDISK

ARR20
5 50 -4
ARR15
50-4
HOVEAARR20
ARR15
ZK-4444-85

8.7 Updating Arrays
To change the contents of an element in a compile-time array, or to add new elements to
such an array, edit the source program containing the array data, and then recompile the
program.
To change the contents of an element in a pre-execution-time array, or to add new elements
to such an array, edit the table input file that contains the array.
You can make temporary changes in arrays during program execution by using the array
name as a Result field. You can make these temporary changes permanent by writing the
array to an output file that you can use later as an input file.
The following example describes the array COSTL, which is made up of six-digit
overpunched numeric data with two decimal places. This array is read from the file
ARRAYIN. During program execution, changes can be made to this array. At the completion ofthe program the array will be written to the output file ARRAYOUT. The format in
which it is written is the same as that in which it was read; that is, eight entries in each
record with each entry being a six-digit overpunched numeric with two decimal positions.
The files ARRAYIN and ARRAYOUT must also be described on File Description specifications as an input table file (ARRAYIN) and an output file (ARRAYOUT).

Using Arrays

8-19

------F = Forlllat (PB)
I -----D = Decilllal positions
I I ----5 = Se~uence (AD)
III
I I IAlternating table or arra~

Frolll
file
nallle

To
file
nallle

I
I

011

Table EntEnt Lenl I Inallle Len
or
perin of Fill
of F
arra~ RecTbl EntlDl1
EntlD
nallle I I I 1151
I 115
I
I I I IIII
I 111+-- COllllllents ---+

12345678901234567890123456789012345678901234567890123456789012345678901234567890

* .... *
*
*
*--*---*--****
E
ARRAYIN ARRAYOUTCOSTL 8 100 6 2
ZK-4445-85

8.8 Outputting Arrays
You can output either an entire array or individual array elements_ To output entire
arrays, you can make entries either in an Extension specification or in an Output
specification.
To write a compile-time or pre-execution-time array using an Extension specification, you
must make the following entry:
• Columns 19 through 26 (To file name)-Specify the name of a sequential output file_
This file must have been previously defined in a File Description specification_ The
program automatically writes the compile-time or pre-execution-time array you specified in the Extension specification to this output file after reaching the end of the
program_
To write a compile-time, pre-execution-time, or execution-time array using an Output
specification, you must make the following entries:
• Columns 32 through 37 (Field name)-Specify the name ofthe array you want to write_
The array is written every time the program processes a record unless you specify
indicators in columns 23 through 31 of the Output specification_
• Columns 40 through 43 (End position)-Specify the character position where the last
entry of the array ends_

8-20

Using Arrays

In the following example, for each record read from FILEA, the execution-time array
DISCNT is written out to the file FILEB using Output specifications:

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
E COSTLIST
PRICE 5 10 5 2
E
DISCNT
10 5 2
IFILEA AA 01
I
1 22PERCNT
PRICE
MULT PERCNT
C 01
DISCNT
OFILEB D 1
01
0
60 'COST WITH DISCOUNT OF '
0
PERCNT3 72
0
0
0

D 1

74 'X'

DISCNT

120 , $0.
ZK-4446-85

To output an individual array element, specify the array and the index of the desired element (in the form ARR,n where n is either a constant or a field name) in columns 32
through 37 (Field name).
The following example outputs only the first and second element of the array DSCT:

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
E
E

COSTLIST

IFILEA
I
C 01
OFILEB
0
0
0
0

AA 01

PRICE
DSCT

5 10 5 2
10 5 2

PRICE
MULT PERCNT
D 1
01
DSCT,1
DSCT,2

DSCT

22PERCNT

20 'ITEM 1 COST: '
32 ' $0.
50 'ITEM 2 COST: '
62 ' $0.
ZK-4447-85

If you want to output numeric array elements, you can use Edit codes or Edit words to add
commas or dollar signs, or to suppress leading zeros. Do not use Edit codes or Edit words to
modify array data if you are going to use the data as input to subsequent programs.

When you specify an Edit code with an entire array (nonindexed), RPG II automatically
inserts two spaces between elements of the array in the output record.

Using Arrays

S-21

Chapter 9

Calling System Routines from VAX RPG II
9.1 Introduction
This chapter describes the use of RPG II operation codes to access VAXIVMS Run-Time
Library (RTL) procedures, VAXIVMS system services, utilities (such as FMS and TDMS),
and subprograms written in languages other than RPG II. You can access these routines by
using the following RPG II operation codes:
• The CALL operation code, which invokes the routine.
• The PLIST operation code, which defines the parameter list, if used.
• The PARM, PARMD, and PARMV operation codes, which determine the parameter
passing mechanism.
• The GIVNG operation code, which receives a function value or return status.
See Part II, Chapter 3 for more information on these operation codes.
Although calling RTL procedures, system services, and subprograms can provide many
advantages, keep the following suggestions in mind:
• Do not call these routines if you can perform the same task using RPG II.
• Do not mix RTL and RPG II output routines.
• If an RTL procedure and a system service perform the same task, use the RTL
procedure.
System routines are prewritten subroutines and functions provided by VAXIVMS. Each
system routine has an entry point (the routine or service name) and an argument list. It
may also return a function value or condition value to the program that calls it.
System routines perform common tasks, such as finding the square root of a number or
allocating virtual memory. If you use system routines, you will not have to rewrite code
every time you want to perform a common task. Using system routines allows you to concentrate on application specific tasks, not utility tasks. Some system routines even help
independent parts of programs to allocate resources cooperatively.
9-1

A system routine can be called from any VAX language providing that language supports
the data structures required by the particular routine. The results of a system routine will
be the same, no matter what language you use.
The system routines that are most commonly called from user programs are Run-Time
Library routines and system services. These system routines are documented in the
VAX/VMS Run-Time Library Routines Reference Manual and the VAXIVMS System
Services Reference Manual.

9.1.1 .Run-Time Library Routines
Run-Time Library routines are grouped in facilities that represent specific types of common tasks. These facilities and the types of tasks they perform are shown in Table 9-1.

Table 9-1: Run-Time Library Facilities
Facility

Types of Tasks the Routines Perform

LIB $

General purpose procedures. Obtain records from devices, manipulate strings, convert data types for 110, allocate resources, obtain the system date or time, signal
exceptions, establish condition handlers, enable detection of hardware exceptions,
and process cross-reference data.

MTH$

Mathematics procedures. Perform arithmetic, algebraic, and trigonometric calculations.

OTS$

Language-independent support procedures. Perform tasks such as data type conversions as part of a compiler's generated code.

SMG$

Screen management procedures. Assist you in designing, composing, and keeping
track of complex images on a video screen; provide terminal-independent tasks.

STR$

String manipulation procedures. Perform tasks such as searching for substrings,
concatenating strings, and prefixing and appending strings.

9.1.2 System Service Routines
System service routines perform various tasks, such as controlling processes, communicating among processes, and coordinating 110.
Unlike Run-Time Library routines which are divided into facilities, all system services
share the same facility prefix (SYS$). However, these services are logically divided into
groups of services which perform similar tasks. Table 9-2 describes these groups.

9-2

Calling System Routines from VAX RPG II

Table 9-2: Groups of System Services
Group

Types of Tasks the Services Perform

AST

Allow processes to control the handling of ASTs.

Change Mode

Change the access mode of particular routines.

Condition Handling

Designate condition handlers for special purposes.

Event Flag

Clear, set, read, and wait for event flags, and associate with event flag
clusters.

Information

Return information about the system, queues, jobs, processes, locks,
and devices.

Input/Output

Perform 110 directly, without going through VAX RMS.

Lock Management

Enable processes to coordinate access to shareable system resources.

Logical Names

Provide methods of accessing and maintaining pairs of character
string logical names and equivalence names.

Memory Management

Increase or decrease available virtual memory, control paging and
swapping, and create and access shareable files of code or data.

Process Control

Create, delete, and control execution of processes.

Security

Enhance the security ofVAXNMS systems.

Timer and Time
Conversion

Schedule events, obtain and format binary time values.

9.2 Calling System Routines from VAX RPG II
There are seven steps required to call any system routine.
1.

Determine the type of call (procedure or function).

Declare the arguments.

Declare the system routine.

Include symbol definitions (if applicable).

Call the routine or service.

Check the condition value (if applicable).

Locate the result.

As an example, you can follow these steps in writing a program to call LIB$STAT_TIMER.
LIB$STAT_TIMER returns to its caller one of five statistics: (1) elapsed time, (2) CPU
time, (3) buffered I/O count, (4) direct I/O count, or (5) page fault count.

Calling System Routines from VAX RPG II

9-3

9.2.1 Determine the Type of Call (Procedure or Function)
Before you can set up a call to a system routine, you must determine whether the call to the
routine or service should be a procedure call or a function call.
A system routine must be called as a function if:
• it returns a function value, or
• it returns a condition value.

NOTE
To call a system routine as a function in RPG II, you must use the GIVNG
opcode. A system routine should be called as a procedure only if it does not
return a function value or a condition value.
Although it is possible to call most ofthe system routines as procedures, it is recommended
that you do so only when the text in the RETURNS section says:

RETURNS
None

You may call a system routine as a procedure if you are not interested in the condition code.
However, this is highly discouraged because not checking the condition code can lead to
many undiscovered errors. (Checking condition values is described in Section 9.2.6.)
To determine whether a routine returns a function value or a condition value, look at the
description provided in the RETURNS section of the system routine description. For
example, the RETURNS section of the LIB$STAT_TIMER documentation contains the
following description:

RETURNS
VMS Usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

If this text appears in the RETURNS section, the system routine returns a condition value
and must be called as a function. In routines which return function values, the function
value is described in the RETURNS section.
Because LIB$STAT_TIMER does return condition values, you must call it as a function.

9-4

Calling System Routines from VAX RPG II

9.2.2 Declare the Arguments
Most system routines have one or more arguments. These arguments are used to pass
information to the system routine and to obtain information from the system routine.
Arguments can be required or optional.
For example, consider the arguments for the Run-Time Library routine
LIB$STAT_TIMER. This routine had three arguments: two are required and one is
optional. You can tell which arguments are required by looking at the FORMAT section in
the documentation ofthe system routine. In the case ofLIB$STAT_TIMER, the format is:
LlB$STAT_TIMER code ,value [,handle-adr]

The handle-adr argument appears in brackets ([ ]) indicating that it is an optional argument. Only optional arguments to a system routine appear in brackets in that routine's
FORMAT section. For this example, you only want to use the two required arguments, so
you need declare only the first two arguments.
To declare an argument for a system routine, first look at that argument's description. The
argument description provided for the code argument is as follows:
code
VMS Usage:
type:
access:
mechanism:

function_code
longword integer (signed)
read only
by reference

Code specifies the statistic to be returned. The code argument contains the address of a
signed longword integer that is this code. It must be an integer from one to five.
Next, look at the VMS Usage entry, function_code. Table 9-3 lists the VAX RPG II
equivalent for each of the VMS Usages. You can declare the argument using the code provided in Table 9-3.
When your program passes a parameter by reference, the parameter list contains the
address ofthe location that contains the value of the parameter. Most languages pass scalar data by reference.
When passing a parameter by reference, you may specify an access type and a data type in
columns 54 through 57 ofthe Calculation specification for numeric data. Character data is
always passed as a fixed-length string. Numeric data, by default, is passed as a packed
decimal string. See Sections 9.2.2.2 and 9.2.2.3 for information on access type and data
type.

Calling System Routines from VAX RPG II

9-5

In the following example, the parameter contained in the field CODE is passed by
reference.

Field length
I Decimal positions
I IHaif adjust (H)
I
I Indicators
Opet'ation
I II
I IIResulting
I I
I
I I
Factor
Factor
I
Resul t I II indicatot's
field I 11+ - 0
I I
1
2
I
CI NxxNxxNxxl
I
I II) < = +- Comments --+
I
I
011
12
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contt'o I Ieve I

** *

* *
PARM

CODE

*--*** * * *
90 RL

ZK·4630·85

The procedure used in declaring an argument is also used in declaring the value argument. First, check the description of the value argument.
value
VMS Usage:
type:
access:
mechanism:

varying_arg
unspecified
write only
by reference

The value argument contains the address of a longword or quadword, and that is the statistic returned by LIB$STAT_TIMER. All statistics are longword integers except elapsed
time, which is a quadword.
The VMS Usage varying_arg indicates that the data type returned by the routine is
dependent on other factors. In this case, the data type returned is dependent on the statistic you want to return. For this example, the statistic that you want to return is code 5,
page fault count. This statistic is returned in a signed longword integer. Therefore, you
need to check Table 9-3 to find the VAX RPG II statements that are used to declare a
longword_signed.

9-6

Calling System Routines from VAX RPG II

Field length
I Decimal positions
I
I IHaif adjust (H)
I Indicatot's
Operation
I II
I I
I
IllResulting
I I
Factot'
I
Factor
Resu I t I I Iindicators
I I
1
field I 11+ - 0
I
2
CI NxxNxxNxxl
I
I
I I 1>- < = +- Comments --+
I
o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Conko I Ieve I

** *
C
C

***
*CODE *--***
90 RL

* *
PARM
PARM

VALUE

90 WL
ZK-463185

Regardless of which Run-Time Library routine or system service you are calling, the declaration statements for the arguments can be found by looking up the VMS Usage in Table
9-3.
Table 9-3: VMS Data Structures
VMS Data Structure

VAX RPG II Implementation
NA
Declare as text string of one byte. When using this data structure, you must interpret the ASCII contents ofthe string to
determine the access_mode.

address

addressJange

arg_list

ast_procedure

Boolean

byte_signed

Declare as text string of one byte. When using this data structure, you must interpret the ASCII contents ofthe string.

byte_unsigned

Same as for byte_signed. I

channel

char_string

TEXT STRING

complex_number

DATA STRUCTURE

Technically, RPG II does not support unsigned data structures. However, unsigned information may be passed
using the signed equivalent as long as the contents do not exceed the range ofthe signed data structure.
(continued on next page)

Calling System Routines from VAX RPG II

9-7

Table 9-3: VMS Data Structures (Cont.)
VMS Data Structure

VAX RPG II Implementation

cond_value

condvalue GIVNG OPCODE
Columns 43 through 58

context

date_time

Q'
TEXT STRING

eLcluster_name

TEXT STRING

eLnumber

exiLhandlecblock

DATA STRUCTURE

fab

Implicitly generated by the compiler on your behalf It is not possible for a user to access the fab data structure from an RPG II
program.

file_protection

floating_point

ForD
Column 55

function_code

io_status_block

item_list~

DATA STRUCTURE

item_lisL3

DATA STRUCTURE

item_Quota_list

lock_id

lock_statuB-block

DATA STRUCTURE

lock_value_block

DATA STRUCTURE

logicaLname

TEXT STRING

longword_signed

longword_unsigned

mask_byte

mask_longword

mask_quad word
mask_word
I

Technically, RPG II does not support unsigned data structures. However, unsigned information may be passed
using the signed equivalent as long as the contents do not exceed the range of the signed data structure.
(continued on next page)

9-8

Calling System Routines from VAX RPG II

Table 9-3: VMS Data Structures (Cont.)
VMS Data Structure

VAX RPG II Implementation

nulLarg

octaword_signed

DATA STRUCTURE

octaword_unsigned

DATA STRUCTURE

page_protection

procedure

procesLid

process_name

TEXT STRING

quadword_signed

quad word_unsigned
rightLholder
rights_id
rab

section_id

Ql
TEXT STRING

system_access_id

time_name

TEXT STRING

uic

user_arg

varying_arg

Dependent upon application.

vector_byte_signed

ARRAY OF CHARACTER STRING

vector _byte_unsigned

ARRAY OF CHARACTER STRINGI

vector_longword_signed

ARRAY OF LONGWORD INTEGER (SIGNED) L

vector_longword_ unsigned

ARRAY OF LONGWORD INTEGER Ll

vector_quadword_signed

vector_quadword_unsigned

vector_word_signed

ARRAY OF WORD INTEGER (SIGNED) W

vector_word_unsigned

ARRAY OF WORD INTEGER WI

word_signed

W
WI

word_unsigned
I

Calling System Routines from VAX RPG II

9-9

9.2.2.1 Parameter Passing Mechanisms
This section describes conventions for passing arguments in RPG II programs.
A calling program can pass a parameter in one ofthree ways:
• By value
The PARMV operation code passes a parameter by value.
• By reference
The PARM operation code passes a parameter by reference.
• By descriptor
The PARMD operation code passes a parameter by descriptor.
When your program passes a parameter by value, the parameter list contains the actual,
un interpreted 32-bit value of the parameter.
In the following example, the constant 0 is passed by value.

Field length
I Decimal positions
Contr'ol level
I IHaif adjust (H)
I
Oper'ation
I
I Indicators
I II Resu Iting
I I
I
Factor
Resultl I I indicators
I I
Factor'
I
field I 11+ - 0
I I
1
I
2
CI NxxNxxNxxl
I
I
I II> < = +- Comments --+
I
011
121
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

* *
PARMV

*o
ZK-4632-85

When your program passes a parameter by reference, the parameter list contains the
address ofthe location that contains the value of the parameter. Most languages pass scalar data by reference.
When passing a parameter by reference, you may specify an access type and a data type in
columns 54 through 57 of the Calculation specification for numeric data. Character data is
always passed as a fixed-length string. Numeric data, by default, is passed as a packed
decimal string.

9-10

Calling System Routines from VAX RPG II

In the following example, the parameter contained in the field TIMLEN is passed by
reference.

Field length
I Deci~al positions
I IHaif adjust (H)
I
I Indicatot's
Opet'ation
I II
I II Resulting
I I
I
Resultl I I indicators
I
I I
Factor
FactOt'
field I 11+-0
I I
1
2
I
I
I II} < = +- Co~~ents --+
CI NxxNxxNxxl
I
I
011
I
2
I
3
I
4
15
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Conko I Ieve I

** *
C

*PARM *

TIMLEN

*--*** * * *
90 WL

ZK-4633-85

When your program passes a parameter by descriptor, the parameter list entry contains
the address of a descriptor for the parameter.
In the following example, the field TIMBUF containing the parameter (fixed-length
string) is passed by descriptor.

Field length
I Deci~al positions
I IHaif adjust (H)
I
Opet'ation
I II
I Indicatot'S
I IIResulting
I
I I
Factor
Resu I t I II indicatot's
I I
Factor
I
field I II + - 0
I
2
I I
1
I
I II} < = +- Co~~ents --+
CI NxxNxxNxxl
I
I
011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contt'o I I eve 1

** *

* *
PARMD

*--*** * * *

TIMBUF 23

ZK-4634-85

Calling System Routines from VAX RPG II

9-11

9.2.2.2 Parameter Access Types (column 54)
The parameter access type indicates the actions that the RTL procedure is permitted to
perform on the parameter. Access types that you can use in RPG II are:
• Read-only-R
The parameter can only be read.
• Write-only- W
The parameter can only be written.
• Modify-M
The parameter can be modified (read and written).
You can specify only the parameter access type and data type of a parameter with the
PARM operation code. If you specify a parameter access type, you must also specify its data
type.
In the following example, the TIM LEN field is a longword integer (column 55) with writeonly access (column 54).

Contr'ol level
I
I Indicator's
I I
I I
Factor'
I I
1
CI NxxNxxNxxl
011
I
2

Oper'ation
I
I
Factor'
I
2
I
I
I
3
I

Field length
I Decimal positions
I IHaif adjust (HI
I
I II Resu I ting
Resultl II indicator's
field I 11+ - 0
I
I II> < = +- Comments --+
4
I
5
I
6
I
7

12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C

* *
PARM

*--*** * * *

TIMLEN 90 WL

9.2.2.3 Parameter Data Types (column 55-57)
If you specify a parameter access type, you must also specify its data type. When a program
passes a parameter to an RTL procedure, the RTL procedure expects the parameter to be of
a particular data type. The parameter data types that can be passed from an RPG II program are:
• Word integer (signed) - W
• Longword integer (signed)-L
• Quadword integer (signed)-Q
• F_fioating single-precision-F
9-12

Calling System Routines from VAX RPG II

• D_floating double precision-D
• Numeric string, right overpunched sign-NRO
• Packed decimal string (default data type for numeric data)
• Character string (default data type for character data)
Define the parameter data type in columns 55 through 57 ofthe Calculation specification.
You can specify a data type only for numeric fields passed by reference.
In the following example, the data type of the numeric field TIMLEN is a right
overpunched sign.

Control level
I
I Indicators
I I
I I
Factot'
I I
1
CI NxxNxxNxxl

Opel'ation
I
I
Factot'
I
2
I
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resultl II indicatot's
field I 11+ - 0
I
I II> < = +- Co~~ents --+

011
1213
1415
1617
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

*PARM *

TIMLEN

*--*** * * *
MNRO

ZK·4637·85

Calling System Routines from VAX RPG II

9-13

9.2.3 Declare the System Routine
Declare a system routine in your program as you declare any other external routine. The
declaration statement will vary depending on whether the system routine is being called
as a procedure or function.
The routine declaration statement for calling LIB$STAT_TIMER as a function should
appear as follows:

Field length
I Decimal positions
I IHaif adjust (H)

Contl'o I Ieve I
I

I Indicatol's

Opel'ation

I I

I
I
I

I IIResulting
I I
Factor
Factol'
Resu I t I II indicatol's
I I
1
field I 11+ - 0
2
I
I I I) < = +- Comments --+
CI NxxNxxNxxl
I
I
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

C
C
C
C
C

*STATIM

*--*** * * *

EXTRN'LIB$STAT_TIMER'
CALL STATIM
PARM
CODE
90 RL
VALUE 90 WL
PARM
GIVNG
RETVAL

ZK-4638-85

The routine declaration statement for calling LIB$STAT_TIMER as a procedure should
appear as follows:

Field length
I Decimal positions
I IHaif adjust (H)

Contl'o I Ieve I
I

I IndicatOl's

Operation

I I

I
I
I
I

I IIResulting
Resu I t I II indicatol's
I I
Factol'
Factol'
field I 11+ - 0
I I
1
2
I
I I I) < = +- Comments --+
CI NxxNxxNxxl
I
011
121
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C
C
C
C

*STATIM

EXTRN'LIB$STAT_TIMER'
CALL STATIM
PARM
CODE
PARM
VALUE

*--*** * * *
90 RL
90 WL
ZK-4639-85

9-14

Calling System Routines from VAX RPG II

9.2.4 Include Symbol Definitions
Many system routines depend on values that are defined in separate symbol definition
files. For example, when you call any Run-Time Library routine in the SMG$ facility, you
must include SMGDEF.
For Run-Time Library routines, you need to include symbol definitions such as when you
are calling an SMG$ routine, or when you are calling a routine that is ajacket to a system
service. (A jacket routine in the Run-Time Library is a routine that provides a simpler,
more easily used interface to a system service.)
All system services, however, require that you include SSDEF to check status. Many other
system services require other symbol definitions as well. To determine whether or not you
need to include other symbol definitions for the system service you wish to call, refer to the
documentation for that service. If the documentation states that values are defined in the
XXXXX macro, you must include those symbol definitions in your program.
In VAX RPG II a definition macro is included as follows:
$ CREATE SMGDEF.MAR
.TITLE SMGDEF - Define SMG$ constants
$SMGDEF GLOBAL
.END
$MACRD SMGDEF
$LINK RPGPRDG.SMGDEF

As you can see from the documentation for LIB$STAT_TIMER, it does not use any
included definition files, so this step is not applicable for this example.

9.2.5 Call the Routine or Service
The call to the routine or service is set up as an external call in VAX RPG II. The syntax of
the call statement will depend on whether the call is a function call or a procedure call.

9.2.5.1 Calling a System Routine in a Function Call
In this example, LIB$STAT_TIMER returns a condition value called reLstatus. To call a
system routine, set up the function call in the same order as the FORMAT in the routine or
service description. In this case, the format is as follows:
LlB$STALTIMER code ,value [,handle-adrj

As stated earlier, you are not using the optional handle-arg argument. In a format statement, an optional argument can appear in one of two ways:
• [,optional-argument]
• ,[optional-argument]

Calling System Routines from VAX RPG II

9-15

If the comma appears outside of the brackets (,[optional-argument]) you must pass a zero
by value. In the following example, the constant 0 is passed by value.
,/

Field length
I Deci~al positions
I IHaif adjust (H)

Control level
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I

CI NxxNxxNxxl

Factor
2
I

I IIResulting
Resultl I Iindicators
field I 11+ - 0
I
I II} < = +- Co~~ents --+

011
12
1314
I
5
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C

*PARMV *

*o
ZK·4636-B5

If the comma appears inside the brackets ([,optional-argument)) you can omit the argument, as long as it is the last argument(s) in the list. For example, look at the optional
arguments of an imaginary routine, LIB$EXAMPLE-ROUTINE:
L1B$EXAMPLE_ROUTINE arg1 [,arg2] [,arg3] [,arg4]

You can omit all of the optional arguments without using a placeholder:

Contro I Ieve I
I

I Indicators

Operation

I I

CI NxxNxxNxxl

I
I
I
I

** *

I I

Factor

I I

Factor
2
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resu It I II indicators
field I 11+ - 0
I
I II} < = +- Co~~ents --+

011
I
2
131
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
C
C
C
C

*
LIBEXA

*--*** * * *

EXTRN'LIB$EXAMPLE_ROUTINE'
CALL LIBEXA
PARM
ARG1
GIVNG
RETSTA

ZK-4640-85

9-16

Calling System Routines from VAX RPG II

However, if you omit an optional argument in the middle of the argument list, you must
insert a placeholder:

Field length
I Decimal positions
I IHalf adjust (H)

Control level
I

I Indicator's

Oper'ation

I I

I
I
I
I

I IIResulting
I I
Factor
Factor'
Resu I t I II indicator's
I I
1
field I 11+ - 0
2
CI NxxNxxNxxl
I
I
I II} < = +- Comments --+
o
I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C
C
C

*LlBEXA

C
C

*--*** * * *

EXTRN'LIBSEXAHPLE_ROUTINE'
CALL LlBEXA
PARH
ARG1
PARHV
o
PARH
ARG3
GIVNG
RETSTA

ZK-4641-85

In general, Run-Time Library routines use the format:
[,optional-argument]

while system services use the format:
,[ optional-argument]

Calling System Routines from VAX RPG II

9-17

Therefore, taking into account the optional argument (ARG2), the function call
LIB$EXAMPLE_ROUTINE routine would appear as follows:
Contro I I eve I
I
I Indicatol's
I I
I I
Factor
I I
1
CI NxxNxxNxxl
011
I
2

Opel'ation

I
I
I
I

Factol'

2
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resu I t I II indicatol's
field I 11+ - 0
I
I II} < +- Co~~ents --+
4
151
6
I
7

3
I
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C
C
C
C
C
C

*LlBEXA

*--*** * * *

EXTRN'LIB$EXAMPLE_ROUTINE'
CALL LlBEXA
PARM
ARG1
PARM
ARG2
PARM
ARG3
GIVNG
RETSTA

ZK-4642-85

In passing the arguments to the procedure, you must declare the passing mechanism.
When passing parameters by descriptor (using the PARMD operation code), RPG II uses:
• An array descriptor for entire arrays
• A scalar decimal descriptor for numeric data with positions to the right of the decimal
point
• A scalar descriptor for all other data types
RPG II passes parameters using a scalar form, unless the parameter is an entire array. See
Section 9.2.2.1 for information on parameter passing mechanisms.
The passing mechanism required for a system routine argument is indicated in the argument description. This is shown in the following description ofthe one-char-str argument
to LIB$CHAR:
one-char-str
VMS Usage:
type:
access:
mechanism:

char-string
character string
write only
by descriptor

In this case, the passing mechanism required is "by descriptor." The passing mechanisms
allowed in system routines are those listed in the VAX Procedure Calling and Condition
Handling Standard section of the Introduction to VAX!VMS System Routines.

9-18

Calling System Routines from VAX RPG II

To pass an argument using a specific passing mechanism, use the specifiers listed in Table
9-4.

Table 9-4: Passing Mechanisms
Passing Mechanism Desired

Specifier Required

By value
By reference
By descriptor

PARMV
PARM
PARMD

NOTE
Any passing mechanisms not listed in this table are unsupported in
VAX RPG II. If a system routine requires a passing mechanism not listed in this
table, it is not possible to call that routine directly from VAX RPG II.
You are required to specify the passing mechanism, as shown in the following example
where the PARM opcodes indicate that both CODE and VALUE are being passed by
reference:

Field length
I Deci~al positions
I IHaif adjust (H)
I
I Indicators
Operation
I II
I IIResulting
I I
I
Resultl I Iindicators
I I
Factor
I
Factor
I I
1
I
field I 11+ - 0
2
I
I II> { = +- Co~~ents --+
CI NxxNxxNxxl
I
I
011
I
2
I
3
I
4
I
5
1617
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contt'o I I eve I

** *

C
C
C
C
C

*STATIM

*--*** * * *

EXTRN'LIB$STAT_TIMER'
CALL STATIM
PARM
CODE
90 RL
PARM
VALUE 90 WL
GIVNG
RETSTA

ZK-4643-85

9.2.5.2 Calling a System Routine in a Procedure Call
If the routine or service you are calling does not return a function value or condition value,
you may call the system routine as a procedure. The same rules apply to optional arguments, and you still follow the calling sequence presented in the FORMAT section.

Calling System Routines from VAX RPG II

9-19

One system routine that does not return a condition value or function value is the RunTime Library routine LIB$SIGNAL. LIB$SIGNAL should always be called as a procedure,
as shown in the following code:

Field length
I Decimal positions
I IHalf adjust (H)

Conko I Ieve I
I
I Indicator's
I I
I I
Factor
I I
1

Oper'ation
I
I
I
I

2
I

I
I

Resu I t I
field I 11+ - 0
I
I II} < = +- Comments --+
CI NxxNxxNxxl
011
121
3
I
4
151
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C
C
C

*
SIGNAL

FactoI'

IIResulting
II indicator's

EXTRN'LIB$SIGNAL'
CALL SIGNAL
PARMV
CODE

*--*** * * *
90
ZK-4644-85

9.2.6 Check the Condition Value
After you call the system routine and control is returned to your program, you should
check the condition value returned, ifthere is one. In general, all system routines return a
condition value with the following exceptions:
• The system routine returns a function value. (Ifthe routine returns a function value
this is described in the RETURNS section.)
• The CONDITION VALUES RETURNED section states "None."
• There is no CONDITION VALUES RETURNED section but rather a CONDITION
VALUES SIGNALED section. (Success conditions are not signaled.)
• The call to the routine was made as a procedure call. (In this case, no condition values
are returned.)
If any ofthe conditions listed above apply, there is no condition value to check.
If there is a condition value, you must check this value to make sure that it indicates success. All success condition values are listed in the CONDITION VALUES RETURNED
section of the system routine description. Success condition values always appear first in
this list.

9-20

Calling System Routines from VAX RPG II

Many system routines return the condition value SS$_NORMAL as a success value. If this
is the only possible success condition, you can test for its presence, as shown in the following example:

Field length
I Decimal positions
I IHaif adjust (H)
I
I II
I Indicator's
Oper'ation
I IIResulting
I I
I
Resu I t I II indicator's
I I
Factor'
Factor'
I
field I 11+ - 0
2
I
I I
1
I
I II> < = +- Comments --+
CI NxxNxxNxxl
I
I
011
I
2
I
3
I
4
I
5
1617
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contr'o I Ieve I

** *
C
C
C
C
C

*SSNORM

STATIM

C
C

C N01

SSNORM
STOP

EXTRN'SS$_NORMAL'
EXTRN'LIB$STAT_TIMER'
CALL STATIM
PARM
CODE
90 RL
VALUE 90 WL
PARM
RETSTA
GIVNG
COMP RETSTA
01
EXTRN' LIB$STOP'
CALL STOP
RETSTA 90 RL
PARMV
ZK-4645-85

It is also possible to check for any success code because all success codes are odd. The following code will continue execution if any success code is returned. The call to STATIM is
conditioned by an indicator which will be set off if any success code is returned.

Fie I d length
I Decimal positions
I
I IHaif adjust (H)
I Indicators
Operation
I II
I I
I
I IIResulting
I I
Factor
Factor
Resu I t I II indicator's
I
I I
1
field I 11+ - 0
2
I
CI NxxNxxNxxl
I
I II> < = +- Comments --+
I
I
o I 1 I 2 I 3 I 4 I 5 161 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contr'o I Ieve I

** *

C
C

*
STATIM

C
C
C

C
C

STOP
01

*--*** * * *

EXTRN'LIB$STAT_TIMER'
CALL STATIM
01
PARM
CODE
90 RL
PARM
VALUE 90 WL
GIVNG
RETSTA
EXTRN'LIB$STOP'
CALL STOP
PARMV
RETSTA 90 RL

ZK-4646-85

Calling System Routines from VAX RPG II

9-21

When several success condition values are possible, you can continue execution on specific
success codes. For example, the system service $SETEF returns one of two success values,
SS$_WASSET or SS$_WASCLR. If you want to continue when the sucess code
SS$_WASSET is returned, you can check for this condition value as follows:

Contro I Ieve I
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I

CI NxxNxxNxxl

Factor
2
I

Field length
I Decimal positions
I IHaif adjust (H)
I II
I IIResulting
Resultl I Iindicators
field I 11+ - 0
I
I II> < = +- Comments --+

011
12
1314
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

C
C
C
C
C

*
SETEF
WASSET
WASSET

EXTRN'SYS$SETEF'
CALL SETEF
PARM
EFN
GIVNG
RETSTA
EXTRN'SS$_WASSET'
COMP RETSTA

*--*** * * *
RL
01
ZK-4647-85

If indicator 01 is on, then SS$_WASSET was returned by the calL
If the condition value returned is not a success condition, then the routine did not complete
normally and the information it was supposed to return may be missing, incomplete, or
incorrect.
If the condition value returned was not a success code, you can check for a particular error
condition, as shown in the following example:
011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C
C
C

*
RMSEOF
GETINP

C
C
C
C

C
C
C

02
02
03

'Error'
RMSEOF
, EOF'

*--*** * * *

MOVE 'Input: ' PRMSTR 7
EXTRN'RMS$_EOF'
EXTRN'LIB$GET_INPUT'
CALL GETINP
02
PARMD
INPSTR255
PARMD
PRMSTR
PARM
INPLEN
WW
GIVNG
RETVAL
DSPLYTTY
COMP RETVAl
03
DSPLYTTY

ZK-4648-85

9-22

Calling System Routines from VAX RPG II

9.2.7 Locate the Result
Once you have declared the arguments, called the procedure, and checked the condition
value, you are ready to use the result. To find out where the result is returned, look at the
description of the system routine you are calling.

9.2.7.1 Function Results
Ifthe routine is a function, the result is written into the variable in Factor 2 of the GIVNG
opcode.
For example, in this call to MTH$ACOS the result is written into the variable RESULT:

011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C
C
C
C

*ACOS

EXTRN'MTH$ACOS'
CALL ACOS
PARM
COS
GIVNG
RESULT

*--*** * * *
RF
ZK-4649-85

This result is described in the RETURNS section of the system routine description.

9.2.7.2 Procedure Results
If the system routine is called as a procedure, the result is written into one or more of the
arguments. To determine which argument holds the result, examine the "access" entry in
the argument descriptions. If the access entry in an argument description says "write
only" or "modify", that argument contains output information written by the procedure.
For example, LIB$CURRENCY returns the default system currency symbol. Looking at
the argument descriptions, you know that the currency string is returned in the
currency _str argument.
currency-str

VMS Usage:
type:
access:
mechanism:

char_string
character string
write only
by descriptor

In all system routines, the output information returned by the routine or service has an
access of "write only" or "modify".

Calling System Routines from VAX RPG II

9-23

9.3 Examples of Calling Run-Time Library Routines
The following examples demonstrate calls to system routines in VAX RPG II programs.
You will not be able to call all Run-Time Library procedures because RPG II cannot supply
some types of parameters, such as addresses. See the VAX/VMS Run-Time Library
Routines Reference Manual for information on all RTL procedures and the parameters
they require.
The following example shows a call to the STR$UPCASE procedure to change the lowercase string to uppercase letters. This procedure requires two parameters: 1) the source
string, and 2) the destination string. Both the source string HEAD and the destination
string RESULT must be passed by descriptor, so the PARMD operation code is used.
Because the name ofthis RTL procedure is longer than eight characters, the EXTRN operation code is used to refer to STR$UPCASE as UPCASE.

Field length
I Decimal positions
I
I IHalf adjust (H)
I Indicatol's
Operation
I II
I I
IllResulting
I
I I
Factor
FactOl'
Resu It I II indicatOl's
I
field I 11+-0
I I
1
I
2
I
I I I> < = +- Comments --+
CI NxxNxxNxxl
I
I
011
I
2
I
3
I
4
I
5
I
6
I
7
Contro I Ieve I

12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C
C
C
C
C

*
UPCASE

*--*** * * *

MOVE 'rep head'HEAD
8
EXTRN'STR$UPCASE'
CALL UPCASE
PARMD
RESULT 8
PARMD
HEAD

ZK-4650-85

9-24

Calling System Routines from VAX RPG II

The following example calls the LIB$SET_SYMBOL procedure to redefine
MY _PARAMETER, the Command Language Interpreter (CLl) symbol, to be the string
OFF. This procedure requires two parameters to be passed by descriptor: 1) the symbol to
be defined, and 2) the value to be given to the symbol. Line 220 moves the string OFF (the
value to be given to the symbol) to the field SETVAL. Line 230 assigns a five-character
name, STSYM, to this procedure name. Lines 240 and 250 assign the 12-character string
MY _PARAMETER to the field SYMBL, the symbol to be defined. Line 260 invokes this
procedure. Lines 270 and 280 pass the two parameters to the procedure.

Field length
I Deci~al positions
I IHalf adjust (H)
I
I IndicatOl's
Opel'ation
I II
I IIResulting
I I
I
Result I II indicatOl's
I I
Factor
Factol'
I
field I 11+-0
I I
1
I
2
CI NxxNxxNxxl
I
I
I
I I I> < = +- Co~~ents --+
o I 1 I 2 I 3 I 4 I 5 I 6 171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Conko I Ieve I

** *

220C
230C
240C
250C
260C
270C
280C

*
STSYM

*--*** * * *

MOVE 'OFF'
SETVAL 3
EXTRN'LIB$SET_SYMBOL'
MOVE 'METER' SYMBL 12
MOVEL'MY_PARA' SYMBL
CALL STSYM
PARMD
SYMBL
PARMD
SETVAL

ZK-4651-85

Calling System Routines from VAX RPG II

9-25

The following example calls the LIB$GETjNPUT procedure to ask the user for input
from the terminal screen. This procedure requires three parameters: 1) the input text
INPSTR (passed by descriptor) from the screen, 2) the prompt string PRMSTR (passed by
descriptor) that is displayed before accepting input, and 3) the number of characters
INPLEN (passed by reference) that are written to the input text. Also, this example supplies the field RETVAL to accept the return status (RMS$_EOF is the RTL symbolic constant representing one possible return status) of the operation. Actually, the program uses
the EXTRN operation code to retrieve the value of the symbolic constant representing a
return status. If the operation is unsuccessful, indicator 02 is set on and the string Error is
displayed on the terminal screen. If the operation is unsuccessful because the file is at its
EOF, the string EOF is displayed along with Error.

Field length
I Decimal positions
I
I IHaif adjust (HI
Operation
I II
I Indicatot's
I I
IllResulting
I
I I
Factor
I
Factot'
Resu 1t I II indicators
I I
1
field I 11+-0
2
I
I
I II) < = +- Comments --+
CI NxxNxxNxxl
I
I
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contt'o I Ieve I

** *
C
C
C
C
C
C
C
C
C
C
C

*
RMSEOF
GETINP

02
02
03

' Ert'ot"
RMSEOF
' EOF'

*--*** * * *

MOVE 'Input: ' PRMSTR 7
EXTRN'RMS$_EOF'
EXTRN'LIB$GET_INPUT'
CALL GETINP
02
PARMD
INPSTR255
PARMD
PRMSTR
PARM
INPLEN
WW
GIVNG
RETVAL
DSPLYTTY
COMP RETVAL
03
DSPLYTTY

ZK-4652-85

9-26

Calling System Routines from VAX RPG II

The following example executes TIME, a subroutine, that calls two procedures:
COB$ACC_TIME and RPG$UDATE, to return the system date and time as a 12-digit
field. The time format is hhmmssmmddyy (hours,minutes,seconds,month,day,year). Note
that RPG will automatically call the RPG$UDATE RTL routine whenever UDATE,
UDAY, UMONTH or UYEAR is referenced in the RPG program.

o I 1 121 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FTTY
D F
80
TTY
C*++
C* Execute the TIME subroutine
C*-C
EXSR TIME
C*++
C* Displa~ the time
C*-C
TIMBUF
DSPLYTTY
C*++
C* Set on an indicator to end the program
C*-C
SETON
LR
C*
C
TIME
BEGSR
C*++
C* Ca II COB$ACC_TIME to get the current time
C*-GTIME
EXTRN'COB$ACC_TIME'
C
C
CALL GTIME
C
PARMD
TEMP8 8
C*
C
MOVELTEMP8
HHMMSS 6
C*++
C* Call RPG$UDATE to get the date
C*-C
GDATE
EXTRN'RPG$UDATE'
C
CALL GDATE
PARM
DAY
2
C
PARM
MMDDYY 6
C
C
PARM
YEAR
2
C*
C
MOVELDAY
TEMP4 4
C
MOVE YEAR
TEMP4
C
MOVE TEMP4
MMDDYY
C*
C
MOVE MMDDYV
TIMBUF 12
C
MOVELHHMMSS
TIMBUF
C
ENDSR
ZK-4653-85

Calling System Routines from VAX RPG II

9-27

The information provided in this chapter is general to all system services and Run-Time
Library routines. For specific information on these routines, refer to the following manuals:
• The VAXIVMS Run-Time Library Routines Reference Manual
• The VAX/VMS System Services Reference Manual

9.4 Examples of Calling System Services
Most system services are used primarily by the VAX!VMS operating system on behalf of
users. However, many system services are useful for application programming.
The use of some system services is restricted to protect system performance and the integrity of user processes. The privileges and quotas assigned in the User Authorization File
determine whether you can use a restricted system service. These privileges and quotas
apply to every image that your process executes.
The following example calls the SYS$ASCTIM system service to obtain the time. The time
is converted from 64-bit system time format to an ASCII string. This service requires three
parameters: 1) the length ofthe returned output string TIMLEN, passed by reference, 2)
the character string TIMBUF, to receive the converted time passed by descriptor, and 3)
the conversion value 0, passed by value. A conversion value of1 causes only the hour, minute, second, and hundredth of second fields to be returned. A value of 0 causes the full date
and time to be returned. Remember, the length ofthe returned output string must be long
enough to accommodate the data to be returned. Because the TIMLEN parameter must be
a longword, the access type (write-only) and data type Oongword integer) are specified in
columns 54 and 55.
If the operation is successful, the date and time (TIMBUF) are displayed on the terminal. If
the operation is unsuccessful, indicator 02 is set on.

9-28

Calling System Routines from VAX RPG II

Conko I I eve I
I
I Indicatol's

Opel'ation
I
1 1
Factor
1
Factor
I 1
1
I
2
CI NxxNxxNxxl
1
I
o I 1 121 3 I

I 1

Field length
1 Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resu I t i l l indicatol's
field I 11+ - 0
I
I I I:> -( = +- Co~~ents --+
4
I
5
I
6
171

12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
C *

*
ASCTIM

C
C
C
C
C N02

TIMBUF

* *
*
EXTRN'SYS$ASCTIM'
CAll ASCTIM
02
PARM
TIMlEN
loll
PARMD
TIMBUF 23
PARMV
o
DSPlYTTY
ZK-4654-85

The following example calls two system services - SYS$CRELOG and SYS$GETMSG.
SYS$CRELOG sets on the external indicators 3 and 7 to control the opening of files in a
RPG II program by calling SYS$CRELOG to define the logical name RPG$EXT_INDS. If
the operation is not successful, BUFFER receives the error message which SYS$GETMSG
returns, and the program displays the error message.

Calling System Routines from VAX RPG II

9-29

This example also demonstrates a method for modifying the external indicators logical.
The effect is that subsequent program runs will have the appropriate external indicators
turned on, depending on the value ofthe RPG$EXT_INDS logical. The external indicators
in the program example below are not modified in the currently running program. See
Part I, Chapter 4 for information on modifying the external indicators in a currently running program.
011
I
2
I
3
141
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

FERROR

TTY

C*++

C* Call SYS$CRELOG to set on the external indicators 3 and 7.
C*-MOVEL'RPG$EXT_'LOGNAM 12
C
MOVE 'INDS'
LOGNAM
C
MOVE '3,7'
STRING 3
C
C*
CRELOG
EXTRN'SYS$CRELOG'
C
CALL CRELOG
99
C
C
PARMV
1
C
PARMD
LOGNAM
STRING
C
PARMD
o
C
PARMV
GIVNG
RETVAL
C
C*++

C* If the call was not successful,
C* call SYS$GETMSG to get the error text
C*-C 99
CALL GETMSG
C
PARMV
RETVAL 100
C
PARM
LENGTH 90 WL
PARMD
BUFFER 80
C
C
PARMV
0
C
PARMV
0
EXTRN'SYS$GETMSG'
GETMSG
C
C*++

C* Displa~ the error text
C*-C 99
BUFFER
DSPLYERROR
C*++

C* Set on an indicator to end the program
C*-C
SETON

LR
ZK-4655-85

9-30

Calling System Routines from VAX RPG II

The following example calls an RTL procedure and a system service. The RTL routine
LIB$CVT_HTB accepts as input an eight digit hexadecimal value. The program calls the
system service SYS$GETMSG to get the error message text associated with the condition.

o I 1 121 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FERROR

D F

TTY

C*++

C* Prompt message
C*-C
C
C
C*++

MESSAG

MOVE 'x va!ue:'MESSAG 16
MOVEL'Enter' MESSAG
DSPLYERROR
HEX
8

C* Call LIB$CVT_HTB to convert to binar~
C*-C
CALL CVTHTB
PARMV
8
C
C
PARM
HEX
C
PARM
VALUE
EXTRN'LIB$CVT_HTB'
C
CVTHTB

C*++

C* Call SYS$GETMSG to get the error text
C*-C
CALL GETMSG
C
PARMV
VALUE 90
C
PARM
LENGTH 90 WL
C
PARMD
BUFFER 80
C
PARMV
0
C
PARMV
0
EXTRN'SYS$GETMSG'
C
GETMSG
C*++

C* Displa~ the error text
C*-C
BUFFER
DSPLYERROR
C*++

C* Set on an indicator to end the program
C*-C
SETON

LR
ZK·4656·85

Calling System Routines from VAX RPG II

9-31

For additional information on coding considerations when using external routines, refer to
the following manuals:
• The Introduction to VAX/VMS System Routines
• The Guide to Creating Modular Procedures on VAXIVMS
Section 2 of the Introduction to VAX/VMS System Routines contains the VAX Procedure
Calling and Condition Handling Standard. The VAX!VMS Modular Programming Standard can be found in Appendix A of the Guide to Creating Modular Procedures on
VAX/VMS.

9.5 Examples of Calling Subprograms
Just as they call RTL procedures and system services, RPG II programs can call subprograms written in other languages.
The following program calls a VAX COBOL subprogram and a VAX BASIC subprogram.

o
I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
** *
*
*
*
*
*--*** * * *
C*-C*++

C* The same parameter list is used b~ both calls
C*-C
PARAM
PLIST
C
PARM
MESSAG 16
C*++

C* Ca II the VAX COBOL program
C*-C
MOVEL'RPG caII'MESSAG
MOVE 'ed COBOL'MESSAG
C
C
CALL 'COBOL1' PARAM
C*++

C* Call the VAX BASIC program

c*--

C
C
C*++

MOVE 'BASIC'
CALL 'BASIC!'

MESSAG
PARAM

C* Set on an indicator to end the program
C*-C
SETON

LR
ZK-4657-85

9-32

Calling System Routines from VAX RPG II

The following example is the VAX COBOL subprogram.
IDENTIFICATION DIVISION.
PROGRAM-ID. COBOL1.
DATA DII.JISION.
LINKAGE SECTION.
01 MESSAGE-l PIC X(16).
PROCEDURE DIVISION USING MESSAGE-l.
PO.
DISPLAY MESSAGE-l.
E)<I T PROGRAM.

The following example is the VAX BASIC subprogram.
100 SUB BASICl (STRING MESSAGE
200 PRINT MESSAGE
300 END SUB

= 16 BY REF)

9.6 Screen Handling in VAX RPG II
This section provides examples of RPG II program fragments that perform screen handling using TDMS, FMS and SMG.
VAX TDMS (Terminal Data Management System), VAX FMS (Form Management System), and SMG (Screen Management) are designed to make it easier to develop interactive
applications. Both TDMS and FMS provide utilities that let you define all the screen forms
outside the RPG II program. They also let you design forms by typing them directly onto
the terminal screen. An example of a TDMS program is provided in
SYS$EXAMPLES:RPGTDMS.COM.
The following TDMS examples are part of the complete program example provided in
SYS$EXAMPLES.
The following example demonstrates the use of data structures and COpy from CDD in an
RPG II program that calls TDMS. See Part II, Chapter 2 for more information on data
structures and COPY from CDD.

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

IEMPLOY
I

IEMPREC
DS
I/COPY_CDD 'EMPLOYEE_RECORD'

1 91 EMPREC

ZK-4669-85

Calling System Routines from VAX RPG II

9-33

The following· example demonstrates the use of long character literals in an RPG II program which calls TDMS. See Part II, Chapter 2 for more information on long character
literals.

Control level
I

I Indicators

Operation

I I

CI NxxNxxNxxl

I
I
I
I

** *

I I

Factor

I I

Factor
2
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resu It I II indicators
field I 11+ - 0
I
I II> < = +- Co~~ents --+

011
I
2
131
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
C
C
C
C
C

*
REQUES

EXTRN'TSSSREQUEST'
CALL REQUES
99
90 LlL
PARM
CHAN
PARM
UBID 90 LlL
PARMD
"
'EMPLOYEE_INITIAL_REQUEST'
ZK-4658.a5

For further information on VAX TDMS, see the following related documents:

• VAX TDMS Forms Manual
• VAXTDMSRequestManual
• VAX TDMS Application Programming Manual
• VAX TDMS Sample Application Manual
The following fragment is from an RPG II program that calls FMS to display a form.

Contro I Ieve I
I

I Indicators

Operation

I I

CI NxxNxxNxxl

I
I
I
I

** *

I I

Factor

I I

Factor
2
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resu It I II indicators
field I 11+ - 0
I
I II> < = +- Co~~ents --+

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
C

C
C
C

*FCLRSH

EXTRN'FDVSCLRSH'
MOVE 'FIRST' FORM1
CALL FCLRSH
PARMD
FORM1

*--*** * * *
6

ZK·4659·85

9-34

Calling System Routines from VAX RPG II

For further information on VAX FMS, see the following related document:

• VAX FMS Reference Manual
Following is an RPG II program calling SMG$ routines. This program displays the word
'Menu' beginning at line 2, column 5.
See the VAXIVMS Run-Time Library Routines Reference Manual for information on SMG
routines.

Contl'o I Ieve I
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I

CI NxxNxxNxxl

Factor
2
I

Field length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resultl I Iindicators
field I 11+ - 0
I
I II> < = +- Co~~ents --+

011
12
1314
I
5
I
6.17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
*
*
*
*
*--*** * * *
C
CREPAS
EXTRN'SMG$CREATE_PASTEBOARD'
C
CREDIS
EXTRN'SMG$CREATE_VIRTUAl_DISPlAY'
C
PUTCHA
EXTRN'SMG$PUT_CHARS'
C
PASDIS
EXTRN'SMG$PASTE_VIRTUAl_DISPlAY'
C
Z-ADDO
ZERO
90
C
Z-ADD1
lINCOl 90
C
Z-ADD2
lINE
90
C
Z-ADD5
COLUMN 90
C
MOVE 'Menu'
OUT
4
C* Create the pasteboard.
C
CAll CREPAS
PASTID 90 Wl
C
PARM
C
PARMV
ZERO
C
PARM
HEIGHT 90 Wl
C
PARM
WIDTH 90 Wl
C* Create the virtual displa~.
C
CAll CREDIS
C
PARM
HEIGHT
Rl
C
PARM
WIDTH
Rl
DISPID 90 Wl
C
PARM
C* Output the 'Menu'.
CAll PUTCHA
C
PARM
DISPID
Rl
C
C
PARMD
OUT
Rl
PARM
LINE
C
Rl
PARM
COLUMN
C
C* Paste the virtual displa!:j.
CAll PASDIS
C
C
PARM
DISPID
Rl
PARM
Rl
PASTID
C
PARM
Rl
LINCOl
C
Rl
LINCOl
C
PARM
C
SETON
lR
ZK-4668·85

Calling System Routines from VAX RPG II

9-35

Chapter 10

Debugging VAX RPG II Programs
The VAXIVMS Symbolic Debugger enables you to debug RPG II programs by monitoring
the flow of program execution and logic. For a complete description of debugger capabilities, see the VAX/VMS Symbolic Debugger Reference Manual.
The debugger lets you:
• Set breakpoints. (Breakpoints stop program execution just before a specified line is
executed.)
• Set tracepoints. (Tracepoints cause the debugger to pause and display a message
whenever a specified line is executed.)
• Set watchpoints. (Watchpoints cause the debugger to stop and display a message
whenever a specified variable is modified.)
• Examine and modify source code.
• Examine and modify data.
• Evaluate arithmetic expressions.
• Step through a program (Single STEP commands cause the debugger to execute one
or more lines and then stop program execution.)
The debugger needs information generated by both the RPG II compiler and the VAXIVMS
Linker. Specifying the DEBUG qualifier with the RPG command creates the symbolic
information for the debugger. Specifying the DEBUG qualifier with the LINK command
makes the information available to the debugger.
RPG II supports the following options at compile time for the DEBUG = options qualifier.
• ALL
• NONE
• [NO]TRACEBACK
• [NO]SYMBOLS

10-1

Specifying the DEBUG = SYMBOLS qualifier for the RPG command allows you to
examine and change the contents of variables throughout your program. However, file
names from File Description specifications are not available as variables.
If you omit the DEBUG qualifier from the RPG and LINK commands, you can specify the
DEBUG qualifier with the RUN command. In this case, no symbolic information is available to the debugger; you must make every reference to a program variable in terms of its
absolute address.
If you do not specify the DEBUG qualifier with any of the RPG, LINK, or RUN commands,
and an error occurs, you receive a traceback list (a description of the logic flow up to the
point where the error was detected). However, you cannot invoke the debugger. If you compile your program with the DEBUG = NOTRACEBACK qualifier or link your program
with the NOTRACE qualifier, you do not receive the traceback list. The default options for
the DEBUG qualifier are TRACEBACK and NOSYMBOLS.

If you want to use the source line display while using the COMPILE command, you must
inform the debugger where the source file resides. To do this, complete the following steps:
1.

Define the symbol RPG to include symbols for the VAXIVMS Symbolic Debugger
(for example, RPG : = = RPGIDEBUG).

Execute the RPG II editor COMPILE command during the editing session.

Execute the LINKIDEBUG command after exiting from the editor.

Execute the RUN command.

Enter the debugger command: SET SOURCE source-file-spec.

See Part I, Chapter 2 for information on compiling and linking RPG II programs and their
respective command qualifiers.
If you are using the VAXIVMS Performance and Coverage Analyzer, you must specify the
following:
IDEBUG=SYS$LIBRARY:PCA$DBJ.OBJ MYPROGRAM.OBJ

The VAXIVMS Performance and Coverage Analyzer consists of a collector and an analyzer. The collector gathers information (such as execution counts) on your program while
it is executing. The analyzer makes it possible to interpret the data gathered by the collector. The analyzer is used to track a performance problem in a whole program down to a
certain module, or even down to a certain line of code. See Appendix C for an example of the
VAXIVMS Performance and Coverage Analyzer applied to an RPG II program.

10-2

Debugging VAX RPG II Programs

10.1 Debugging RPG II Programs
Debugging RPG II programs is somewhat different from debugging programs in other languages. The RPG II program cycle determines the order in which the program lines are
processed. See Part I, Chapter 1 for a complete discussion of the RPG II program cycle.
You can reference those line numbers RPG II assigns to your program in the listing file.
The line numbers you specify in columns 1 through 5 of a specification are not used. The
compiler assigns line numbers only to certain specifications at specific points in the logic
cycle; therefore, you can specify a breakpoint or tracepoint at these points in the program:
• A break at a File Description specification occurs just before an input or update file is
opened or just before an output file is created. The line number of this break corresponds to the File Description specification for this file.
• A break at an Input specification occurs before the fields are loaded with data from a
record. The line number ofthis break corresponds to the record definition in an Input
specification.
• You can set two breaks for each Calculation specification. The first break occurs just
after testing control-level indicators, if used, and just before testing conditioning
indicators. The second break occurs just before executing the operation code. For
example, if a Calculation specification begins with line number 25, you can specify
the line and statement number SET BREAK 25.1 to test indicators. SET BREAK 25.2
breaks just before executing the operation code. If a particular Calculation specification has no indicators, SET BREAK 25 breaks just before executing the operation
code.
• A break at an Output specification occurs after the output buffer has been built but
before the record is output. The line number of the break corresponds to the record
definition in an Output specification.

10.2 Debugger Commands and Keywords
There are many debugger commands, but not all debugger commands are appropriate for
use in debugging RPG II programs. Table 10-1 lists some debugger commands and
keywords (and their abbreviations) that are helpful in debugging RPG II programs.

Debugging VAX RPG II Programs

10-3

Table 10--1: Debugger Commands and Keywords
Command Names

Keywords

SET (SE)
SHOW (SH)
CANCEL (CAN)
EXAMINE (E)
EVALUATE (EV)
DEPOSIT(D)
EXIT (EXI)
STEP(S)
GO (G)
EDIT (ED)

LANGUAGE (LA)
MODULE (MODU)
SCOPE (SC)
BREAK (B)
TRACE (T)
WATCH(W)

The rest ofthis chapter describes these debugger commands and explains how to use them.

10.3 Preparing to Debug a Program
This section describes the SET LANGUAGE and SHOW LANGUAGE commands. These
commands are used to establish the proper environment for debugging an RPG II program.

10.3.1 SET LANGUAGE and SHOW LANGUAGE Commands
The SET LANGUAGE command causes the debugger to conduct the debugging dialog
according to the conventions of the specified language. If your program does not call any
subprograms written in languages other than RPG II, you do not need to use the SET LANGuAGE command. If your program calls a subprogram written in another language, you
can cause the debugger to execute the subprogram by specifying the STEP/INTO command. See Section 10.4.5 for information about the INTO qualifier. Once the debugger is in
the subprogram, you must use the SET LANGUAGE command to specify the language of
the subprogram. After you have finished executing the subprogram and you have returned
to the main program, you must use the SET LANGUAGE command to specify the language of the main program.
The format of the SET LANGUAGE command is:
SET LANGUAGE language

where:
language

10-4

Specifies the language to be used.

Debugging VAX RPG II Programs

To determine the language ofthe program currently being executed, use the SHOW
LANGUAGE command. The format of the SHOW LANGUAGE command is:
SHOW LANGUAGE

The debugger responds by displaying the program's language, as shown in the following
example:
DBG>SHOW LANGUAGE
language:

RPG

10.4 Controlling Program Execution
To see what is happening during execution of your program, you must be able to suspend
and resume the program at specific points. The following commands are available for these
purposes:
SET BREAK
SHOW BREAK
CANCEL BREAK
SET TRACE
SHOW TRACE
CANCEL TRACE
SET WATCH
SHOW WATCH
CANCEL WATCH
SHOW CALLS
GO
STEP
TYPE
CTRLlY
EXIT

You can specify an RPG II label as a breakpoint or a tracepoint. These labels correspond to
specific points in the logic cycle. The following list describes RPG II labels:
• *DETL - Breaks just before outputting heading and detail lines
• *GETIN - Breaks just before reading the next record from the primary or secondary
file
• *TOTC - Breaks just before performing total-time calculations
• *TOTL - Breaks just before performing total-time output
• *OFL - Breaks just before performing overflow output
• *DETC - Breaks just before performing detail-time calculations

Debugging VAX RPG II Programs

10-5

10.4.1 SET BREAK, SHOW BREAK, and CANCEL BREAK Commands
The BREAK commands allow you to select specific locations for program suspension, so
that you can examine or modify the following data:
• Variables
• Table entries
• Array elements
When you specify a table name, you can examine or modify the entry retrieved from the
last LOKUP operation.
You can also set a breakpoint at any place listed in Section 10.l.
The BREAK commands perform the following functions:
• SET BREAK defines the line number that will suspend execution.
• SHOW BREAK displays all breakpoints currently set in the program.
• CANCEL BREAK removes selected breakpoints.
The format of the SET BREAK command is:
SET BREAK %LlNE lin-num[.stmnt-num] [DO(command(s))]

where:
lin-num

Specifies the line number where the breakpoint will occur. You can
also specify a logic cycle label, a TAG name, or a subroutine label.

stmnt-num

Specifies the statement number where the breakpoint will occur.
You can use statement numbers only with Calculation specifications that have conditioning indicators.

DO(command(s))

Requests the debugger to perform the specified debugger commands, if specified, when the breakpoint is reached.

In the following example, SET BREAK examines variables TOTAL and AREA when the
breakpoint at line 100 is reached:
DBG)SET BREAK %LINE 100 DOIEXAMINE TOTAL; EXAMINE AREAl

The format of the SHOW BREAK command is:
SHOW BREAK

10-6

Debugging VAX RPG II Programs

SHOW BREAK takes no arguments. The debugger responds by displaying the current
breakpoints, as shown in the following example:
DBG>SET BREAK LOOP
DBG>SET BREAK ZLINE 50
DBG>SHOW BREAK
breakpoint at ARRX37\LOOP
breakpoint at ARRX37\ZLINE 50

The format of the CANCEL BREAK command is:
CANCEL BREAK %LlNE lin-num[.stmnt-num]
fAll

where:
lin-num[.stmnt-num]

Removes the breakpoint at the specified line and statement number, logic cycle label, TAG name, or subroutine label

fAll

Removes all breakpoints in the program

Normally, the debugger displays the line number when it suspends execution because of a
breakpoint or step. There are two exceptions to this behavior:
• When stepping through a subroutine, the debugger displays the subroutine label.
DBG>STEP
stepped to PROG1\SUB1

• When stepping through a TAG, the debugger displays the TAG name.
DBG>STEP
stepped to PROG1\TAG1

·10.4.2 SET TRACE, SHOW TRACE, and CANCEL TRACE Commands
The TRACE commands let you set, examine, and remove tracepoints in your program. A
tracepoint is similar to a breakpoint in that it suspends program execution; however, after
displaying the trace variables, program execution resumes immediately. Thus, tracepoints let you follow the sequence of program execution to ensure that execution is being
carried out in the proper order.
Tracepoints and breakpoints are mutually exclusive. If you set a tracepoint at a current
breakpoint, the breakpoint will be canceled. If you set a breakpoint at a current tracepoint,
the tracepoint will be canceled.

Debugging VAX RPG II Programs

10-7

The TRACE commands perform the following functions:
• SET TRACE establishes points within the program where execution is momentarily
suspended.
• SHOW TRACE displays the points in the program where tracepoints are currently
set.
• CANCEL TRACE removes one or more tracepoints currently set in the program.
The format of the SET TRACE command is:
SET TRACE %LlNE lin-num[.stmnt-numJ

where:
lin-num[.stmnt-num]

Specifies the line and statement number, logic cycle label, TAG
name, or subroutine label where the tracepoint will occur.

The format ofthe SHOW TRACE command is:
SHOW TRACE

SHOW TRACE takes no arguments. The debugger responds by displaying the current
tracepoints, as shown in the following example:
DBG)SET TRACE LOOP2
DBG)SET TRACE ZLINE 100
DBG)SHOW TRACE
tracepoint at ARRX37\LOOP2
tracepoint at ARRX37\ZLINE 100

The format of the CANCEL TRACE command is:
CANCEL TRACE %LlNE lin-num[.stmnt-num]
fAll

where:
lin-num[.stmnt-num]

Removes the tracepoint at the specified line and statement number, logic cycle label, TAG name, or subroutine label

fAll

Removes all tracepoints in the program

10-8

Debugging VAX RPG II Programs

10.4.3 SET WATCH, SHOW WATCH, and CANCEL WATCH Commands
The WATCH commands let you monitor the contents of variables. Watchpoints determine
when an attempt is made to modify variables. When an attempt is made, the debugger
halts program execution, and prompts for a debugger command. Watchpoints are monitored continually. Thus, you can determine whether a particular variable is being modified
inadvertently during program execution. Watchpoints, tracepoints, and breakpoints are
mutually exclusive. The WATCH commands perform the following functions:
• SET WATCH defines the variable(s) to be monitored.
• SHOW WATCH displays the variable currently being monitored.
• CANCEL WATCH disables monitoring of specified variables.
The format of the SET WATCH command is:
SET WATCH vbl

where:
vbl

Specifies the variable to be monitored. You can monitor variables and array elements.

In the following example, SET WATCH sets a watchpoint for the variable AREA:
DBG>SET WATCH AREA

The format of the SHOW WATCH command is:
SHOW WATCH

SHOW WATCH takes no arguments. The debugger responds by displaying the current
watchpoints, as shown in the following example:
DBG)SET WATCH INDEX2
DBG)SHDW WATCH
watchpoint of ARRX37\INDEX2

The format of the CANCEL WATCH command is:
CANCEL WATCH

vbl

fAll

where:
vbl

Specifies the variable that disables monitoring.

fAll

Removes all watchpoints from the program.

The following command cancels the watch point for the variable AREA:
DBG)CANCEL WATCH AREA

Debugging VAX RPG II Programs

10-9

10.4.4 SHOW CALLS Command
SHOW CALLS can be used to produce a traceback of calls to program modules. It is particularly useful when you have returned to the debugger following a CTRLlY command. The
format of the SHOW CALLS command is:
SHOW CALLS [n]

The debugger displays a traceback list, showing the sequence of calls to program modules
leading to the current module.
If you include a value for n, the n most recent calls are displayed.

10.4.5 GO and STEP Commands
GO and STEP let you initiate and resume program execution. GO initiates execution from
the current line or at a specified point in the program, and continues to the end of the program or to the next breakpoint. STEP initiates execution from the current line; and continues for a specified number of lines.
The format of the GO command is:
GO [%LlNE lin-num[.stmnt-numlJ

where:
lin-num[.stmnt-num]

Specifies the line and statement number, TAG name, or subroutine label where execution will begin.

The normal use of GO is to continue execution after a breakpoint or at program initiation.
Resuming execution at a point other than the current line can cause unpredictable results
because of the nature of the RPG II logic cycle.
Use the STEP command to execute one or more RPG II program lines and immediately
return to the debugger. The format of the STEP command is:
STEP [/qualifiers] [n]

The value specified for n determines the number of statements to be executed. If you specify 0, or omit a value for n, a value of 1 is assumed.
You can specify the following qualifiers with the STEP command:
SYSTEM
[NO]SYSTEM

Causes the debugger to count steps wherever they occur. The NOSYSTEM qualifier is the default.

OVER

Causes the debugger to ignore calls to subprograms as it steps through
the program. That is, to step over each call to a subprogram. The
OVER qualifier is the default.

10-10

Debugging VAX RPG II Programs

INTO

Causes the debugger to recognize calls to subprograms as it steps
through the program. That is, to step into each subprogram. The
NOINTO qualifier is the default.

LINE

Causes the debugger to step through the program on a line-by-line
basis. The LINE qualifier is the default.

SOURCE

Causes the debugger to display the line(s) of source code that corresponds to the line(s) being executed with each step. Source lines are
also displayed when a breakpoint or watchpoint occurs. When stepping through Input and Output specifications, the debugger displays
the first line of a record definition.

You can specify one or more qualifiers each time you issue a STEP command, or you can
use a SET STEP command to override the defaults.
The following command specifies that the defaults for the LINE, INTO, and SYSTEM
qualifiers are overridden:
DBG)SET STEP NDLINE,INTD,SYSTEM

When you subsequently issue a STEP command with no qualifiers, the debugger assumes
these qualifiers (NOLINE, INTO, and SYSTEM) are in effect. You can, however, supersede
the current qualifiers by including a qualifier with a STEP command.
The following command executes ten lines, regardless of the SET STEP command:
DBG)STEP/LINE 10

It is advisable to use STEP to execute only one or a few lines at a time. To execute many
lines and then stop, use a SET BREAK command to set a breakpoint, then issue a GO
command.

10.4.6 TYPE Command
The TYPE command displays the line of source code you specify. The format of the TYPE
command is:
TYPE [lin-num[:line-num]L ... ll

where:
lin-num[:lin-num]

Specifies the number of lines of source code to be displayed.

The following command displays lines 1 through 30:
DBG>TYPE 1:30

Debugging VAX RPG II Programs

10-11

The following command displays lines 1 and 30:
DBG>TYPE 1 .30

You can display the line after the current line by typing TYPE and by pressing the
RETURN key.

10.4.7 EDIT Command
The EDIT command allows you to edit the file you are debugging. Before entering the
debugger, you must define the symbol LSEDIT as follows:
$

LSEDIT :== RPG/EDIT

The editing session begins at the current debugging line.
EDIT/EXIT specifies that you want to end the debugging session and begin an editing
session.
EDIT/NOEXIT specifies that you want to return to the debugging session after you make
your edits. The NOEXIT qualifier is the default.

10.4.8 CTRLlY Command
You can use the CTRLlY command at any time to return to the system command level. You
issue this command when you press the CTRL key and the Y key at the same time. The
dollar sign ($) prompt will be displayed on the terminal. To return to the debugger, type
DEBUG. Use the CTRLlY command if your program goes into an infinite loop or, for some
reason, fails to stop at a breakpoint. To find out where you were at the instant CTRL/Y was
executed, use the SHOW CALLS command after you have returned to the debugger.

10.4.9 EXIT Command
The EXIT command lets you exit from the debugger when you are ready to terminate a
debugging session. The format ofthe EXIT command is:
EXIT

EXIT takes no arguments. To return to system command level, after your program has
terminated, use the EXIT command.

10-12

Debugging VAX RPG II Programs

10.5 Examining and Modifying Locations
Once you have set breakpoints and begun execution, the next step is to see whether correct
values are being generated and, if necessary, to change the contents of variables as execution proceeds. You may also want to calculate the value of an expression that appears in
your program. The debugger provides the following commands for these purposes:
EXAMINE, DEPOSIT, and EVALUATE.

10.5.1 EXAMINE Command
The EXAMINE command lets you look at the contents of:
• A variable
• The current table entry
• An array element
• The I/O buffer
The format ofthe EXAMINE command is:
EXAMINE vbl [,vbl)

where:
vbl

Specifies a simple or subscripted variable.

The following command displays the contents of the variable SALES:
DBG>EXAMINE SALES

The following command displays the contents ofthe ninth element in array ARRAY:
DBG>EXAMINE ARRAY(S)

The following command displays the contents ofthe first through the tenth elements ofthe
array ARRAY.
DBG>EXAMINE ARRAY(1:10)

You can examine indicators to see whether they are set on or off. Precede the indicator you
want to examine with the string *IN. If an indicator is set on, 1 is displayed. If an indicator
is set off, 0 is displayed.
The following command displays the current setting for indicator 56:
DBG>EXAMINE *IN56

The debugger responds by displaying:
*IN5G:

11<)11

Debugging VAX RPG II Programs

10-13

You cannot examine external indicators this way, but you can do the following. To determine the current value ofU5, for example, enter
DBG> CALL RPG$EXTINDS(S)

The debugger responds by displaying:
value returned is 0

The program must have been linked with the NOSEYSSHARE qualifier to do this.
You can also display the current contents ofthe 110 buffer. To display the I/O buffer, specify
the name of the input file, update file, or output file, a dollar sign ($), and the string BUF.
The following command displays the contents of the I/O buffer for the input file INPUT:
DBG>EXAMINE INPUT$BUF

10.5.2 DEPOSIT Command
The DEPOSIT command lets you change the contents of specified variables. The format of
the DEPOSIT command is:
DEPOSIT vbl = value

where:
vbl

Specifies the variable that the value is deposited into.

value

Specifies the value to be deposited.

You can change the contents of a specific variable or of several consecutive variables, as
shown in the examples in this section.

Values deposited into numeric fields are aligned on the decimal point. Shorter fields are
padded with zeros to the left and right of the d~cimal point.
The following command places the decimal value 100 into the variable BONUS:
DBG)DEPOSIT BONUS=IOO

The following command places the decimal values 100, 150, and 200 into elements 1, 2,
and 3 of array ARRAY:
DBG)DEPOSIT ARRAY(I)=IOO, ISO, 200

The delimiters used to enclose ASCII strings in the DEPOSIT command can be either single (') or double (") quotation marks. Use the keyboard apostrophe for the single quotation
mark.
Values deposited into character fields are left justified. If the value contains fewer characters than the character field, the field is padded on the right with spaces.

10--14

Debugging VAX RPG II Programs

The following command places the string ACTIVE in the variable STATUS:
DBG)DEPOSIT STATUS="ACTIVE"

You can also use DEPOSIT to set indicators on or off. Precede the indicator you want to set
with the string *IN. To set an indicator on, specify 1 as the variable value. To set an indicator off, specify 0 as the variable value.
The following command sets indicator 56 on:
DBG)DEPOSIT *IN56 = "1"

10.5.3 EVALUATE Command
The EVALUATE command lets you use the debugger as a calculator to determine the
value of arithmetic expressions. The format ofthe EVALUATE command is:
EVALUATE expression

where:
expression

Specifies the expression whose value is to be determined.

The following command displays the value of the expression ARRAY(FLDl) * FLD2:
DBG)EVALUATE ARRAYIFLD1) * FLD2

Debugging VAX RPG II Programs

10-15

Chapter 11

Interpreting a Compiler Listing
This chapter explains the parts of a full compiler listing. This sample listing is for the program shown under the Source Listing title. The circled numbers on the program listing
correspond to the following numbered text.
1.

The program name.

The date and time of compilation.

The name and version number ofthe compiler.

The creation date and time of the source file.

The complete file specification (device:[directory]filename.type;version) for the
source file. The number in parentheses is a text editor page number.
Items 1 through 5 appear at the top of each page in the listing file.

The 80-column ruler.

Source line numbers assigned by the compiler. The VAX!VMS Symbolic Debugger
uses these line numbers as location specifications.
A 'c' after the line number indicates that the line was generated by a copy
directive.

Source Listing - Source code.

Machine Code Listing - The compiler-generated object code for the program you
compiled.

10.

Cross Reference in Alphabetical Order - The user-defined names in alphabetical
order and the line numbers in which they are referenced. The first column with the
pound sign (#) after the number lists the line number where the data name is
defined. For example, DEPQTY is defined in line 19 and referenced in lines 19, 21,
and 22.
DEPOT','

19#

11-1

11. Indicator Cross Reference - The indicators and the line numbers in which they are
referenced. For example, indicator 01 is referenced in lines 12, 18, 19, and 36.
01

12. PROGRAM SECTIONS - Names the PSECT numbers and names.
13. The bytes allocated for each PSECT.
14. The PSECT attributes. See the VAX/VMS Linker Reference Manual for information on PSECT attributes.
15.

COMMAND QUALIFIERS - Lists the command line you entered and names the
compiler defaults that were in effect when the program was compiled.

16.

The actual CPU time it took to compile the program.

17. The elapsed time it took to compile the program.
18. The number of page faults.
19. The number of virtual memory pages used to compile the program.

11-2

Interpreting a Compiler Listing

SHIPS

CD 28-Jun-1885 15:58:45
@

SOlJrce Listing'

9
10

11
12

13
14
15
16
17
18
19
20
21
23
24

>-<
::s.....
('D

.a....

('D
.....

5'
crq
Pl
(')

,g.....

('D

....

t""'
.....
UJ.
.....
.....
::s
crq
~
~

26
27
28
29
30
31
32
33
34
35

28-Jun-188S 15:56:12

2
3
4
5
6
8
12345678901234567890123456789012345678901234567890123456789012345678901234567890

® H*++
H*
H*
H*
H*

FUNCTIONAL DESCRIPTIDN:
This prograM produces a report of shiPMents far various
products broKen down by division and department using an
input file with the shipment data for the past a ~uarters.

H*-H
FSHIPS
FSUMREP
E
LSUMREP
ISHIPS

41
98
OTY

DISK
LPRINTER
4

55FL 500L

01
OIl)

6
8
17
C*
C
C
C*

01
01

PRDon

ell
CLl
CL2
C*
OSUMREP
0
0
0
0
0
0
0
0
0

DEPOT'(

)(FODTOTY
ADD
DEPOTY

PROOTY
DEPOT\'

30
30

01 l)QTY

o I von

DEPOT\'
FINOTY

ADO

2-ADDO
OII!OT'(
H

001

ADO

FINOTY

'PRODUCT SHIPMENT REPORT'

1P
UDATE Y

12
48 'PRODUCT SHIPMENT REPORT'

H
H

L2
Ll

1P
48

H 02

DEPT
16 PROD
24 ory

'SHIPMENTS'

15
24
48

'OJ\JISION DEPT'
'PRODUCT'
'01
02 03 04 TOTAL'

l.lAX RPG

l.J2.0

RPG$:ETSAKERES.RPGlSHIPS.RPG;1

Pa se

(II

I-'
I-'

......

::l

M(1)

'"
.....

(1)

M-

::l
crq
Pl

(1
0

i3
"C

-'"
.....
(1)

t-<

00'
M-

.....

::l
crq

36
37
38
38
4(1
41
42
43
44
45
46
47
48
49
50
51
52

53
54

01
L2

L1
0

T
T

DI\'

o I I)

DI \'OTYZB

48
63
69

L2
02

0
OIl,!

0
0
0

Total

for'

LR
FINOT'I1

SHIPS
Machine Code Listing

41
48

L1
L2

8
14

DIl.!
DEPT
PROD
OTY
Z
PRDOTYZ

48
65

.>= GRAND TOTAL'
28-Jun-1885 15:58:45
2B-Jun-1885 15:56:12

VAX RPG II V2.0

Page

RPG$:[TSAKERES,RPGlSHIPS,RPG;l

". X53 t .". )<48 t .". X48 t'" >~50 t" X53
,BYTE
";';53 t ' >~55, "'}{4D, '"j{52 , '-'><45,"' X50
.BYTE
;'{47 t·· XOG ,-'}W2, X40, '}{20 ,"}{81, )<03, i{81 ,"X44, ){2F ,"'X82 ,"){44 ,"')<2F ,···X92 ,···){OO
.BYTE
hX47,hX02,'X02,'X40,'X20,~X82,'XOO
• BYTE
X47,'X03r~X02,'X40,ftX20,'X93t'XOO
.BYTE
hXll7 ,h}<Oll ,···\02 ,·'~{llO ,··}(20 ,·'\91, ><llll, '}<2C ,'·X82 ,·'}<O3 ,·'}<81 ,·'XOO
.BYTE
XQO, XOO,~XOO,'XOC
.BYTE
, ><00000003
.LONG
.ADDRESS UDAY
.ADDRESS UMONTH
.ADDRESS UYEAR
.' ><0000000 1
.LDNG
.ADDRESS SHIPS+6B
hX00000002
.LDNG
.LDNG
X00000002
,ADDRESS SHIPS
,LONG
~<OOOOOOO 1
,ADDRESS SHIPS

;"SHIPS"

.POOOOOOOO

00000008

00000010
00000020
00000028
00000030
0000003C
00000040
00000044
00000048
0000004C
00000050
00000054
00000058
OOOD005C
00000060
00000084
00000068

(1)

"SUMREP"
"G,,@ ",D/,O/,,"
"G, ,@
"G, ,@
"G •• @ .0, •••• "

.LDNG
'XOOOOOO02
.LDNG
'XOOOOOOOI
.ADDRESS SHIPS
'XOOOOOOOI
.LONG
.ADDRESS SUMREP+G8
'XOOOOOOO2
.LONG
.LONG
'XOOOOOOOZ
.ADDRESS SUMREP
.LDNG
'XOOOOOOOI
.ADDRESS SUMREP
.LONG
'X00000002
.LONG
'XOOOOOOOI
.ADDRESS SUMREP
'X50,'X52,'X4F,'X411,'X55,'X43,'X511,'X20,'X53,'X48,'X4S,'X50,'XlID,'X1I5,'X4E,'X511
.BYTE
'X20 ,'X52 ,'X45 ,'X50 ,'X4F ,'X52 ,'X511
.BYTE
'X53 ,'X1I8 ,'X4S ,'X50 ,'X4D ,'X45 ,'X4E ,'X54,'X53
.BYTE
'X1I4,'X4S,'X56,'XlIS,'X53,'X4S,'XlIF,'XlIE,'X20,'X20,'X44,'X45,'X50,'X54
.BYTE
'X51 ,'X31 ,'X20 ,'X20 ,'X51 ,'X32, 'X20 ,'X20 ,'X51 ,'X33 ,'X20, 'X20 ,'X51 ,'X311 ,'X20 ,'X20
.BYTE
'X54,'XlIF ,'X54,'X41 ,'X4C
.BYTE
.LONG
'X00000002
.LONG
'X00000003
.ADDRESS SHIPS
• BYTE
'X3C, 'X3D, 'X3D, 'X20, 'XS4, 'X6F, 'X74,'X61 ,'X6C, 'X20, 'X6G, 'XGF,' X72
.BYTE
'X3C ,'X3D ,'X3D ,'XZO ,'X1I7 ,'X52 ,'X41,'X4E ,'X44,'X20 ,'X54,'X4F ,'X54,'X41 ,'X4C
.PSECT $CDDE
• ENTRY SH I PS, 'XOFFC
MOVAB
G'RPG$HANDLER, (FP)
MOVAB
$LOCAL+'X2G, -(SP)
SUBLZ
#'XOC, SP
MOVAB
$LOCAL+'X80, Rll
MOVAB
$POATA+'X80, RIO
MOVAB
G'RPG$IOEXCEPTION, RS'
MOVAB
G'RPG$PRINT, R8

0000006C
00000070
00000074
00000078
0000007C
00000080
00000084
00000088
0000008C
00000090
00000094
00000098
0000009C
OOOOOOAO
OOOOOOBO
000000B8
OOOOOOClI
00000004
000000E4
OOOOOOEC
OOOOOOFO
000000F4
000000F8
00000108

....
::s

00000000
00000002
00000009
00000010
00000013
OOOOOOIA
00000021
00000028

.a.,
(!)

.....

::s

(Jq

III

0
0

S
.....

-.,

'0
(!)

t'"I
.....
.....

::s

(Jq

~
~

Program epilogue code

"PRODUCT SHIPMENT"
" REPORT"
'SHIPMENTS"
"DIVISION DEPT"
"Ql
Q2 Q3 Q4
"TOTAL"

"(== Total for"
"(== GRAND TOTAL"

........
~

.....
::s

00000S39
00000S41
00000S411
00000548
00000:;4A
00000:;4A
0000054A
00000S4D

SHIPS

1-4

::sc+
(1)

.a
I-j
(1)

CALLG
OLOS
CALLG
ORO

$PDATA+-XBC(RIO). G-RPGHERM.PRINT
RO. 72$
$PDATA+·X94(RIO). G-RPG$lOEXCEPTION(R9)
73$

MDVL
RET

"-XOI. RO

72$:
73$:

Cross Reference in Alphabetical Order

,g.....

(1)
I-j

t"'
.....
c+
.....
::s
aq
Ul

DEPQTY
DEPT
DIV
DIVQTY
FINQTY
PROD
PROQTY
QTY
SHIPS
SUMREP
UDATE
SHIPS

Indicator Cross Reference

01
L1

LZ
LR
IP

19
38
37
ZI
23
3S
IS
16

18"
14"
1321_
23IS ..
IB"
10_
8_
S"
28

12
14
13
SI
25

411
23
52

1I6
48

Pa~@

28-Jun-198S IS:SB:4:;
28-Jun-19B5 IS:56:12

VAX RPG II V2.0
RPG$:[TSAKERES.RPGlSHIPS.RPG;1

Pase

(1)

28-Jun-1985 15:5B:45
-2B,ju·n-1985 15:56:12

VAX RPG II V2.0
RPG$:[TSAKERES.RPGlSHIPS.RPG;1

PaS'e

(1)

al
18

lZ
11

8
18
21
23

19
22
37

38
38
1I3

4Z
45

COMPilation SUMMary

VAX RPG II V2.0
RPG$:[TSAKERES.RPGlSHIPS.RPG;1 (I)

SHIPS

2B-Jun-18BS IS:SB:45
ZB-Jun-18B5 15:56:IZ

/--

--',

-~\

PROGRAM SECTIONS
Name

o $CODE
1 $LOCAL
Z $PDATA
3 RPG$UDATE
4 RPG$HALTS

COMMAND QUALIFIERS

Bytes

Attributes

1358
lZ80

PIC
PIC
PIC
PIC
PIC

279
6
9

CON
CON
CON
OVR
OVR

9
REL
REL
REL
REL
REL

LCL
SHR
EXE
LCL NOSHR NOEXE
LCL
SHR NOEXE
G6L NOSHR NOEXE
G6L NOSHR NOEXE

RD NOWRT Ali<n(Z)
WRT Ali<n(Z)
RD
RD NOWRT Ali<n(Z)
RD
WRT Ali<n(2)
RD
WRT Ali<n(Z)

RPG ILIST/MACHINE_CODE/CROSS_REFERENCE/CHECK=ALL/DE6UG/06JECT/SEQUENCE_CHECK/WARNINGS=ALL SHIPS,RPG
ICRDSS_REFERENCE IMACHINE_CODE ISEQUENCE_CHECK
ICHECK=(RECURSIDN,60UNDS,6LANKS_IN_NUMERICS)
IDE6UG=(SYM60LS,TRACEBACK)
IWARNINGS=(OTHER,INFORMATIDN)

STATISTICS

I
5'

(JQ
$\)

~.....

( t)

.....
~

~
~

1.:.

Run Time:

5.28 seconds

~ Elapsed TiMe:

6.58 seconds

~ Page Faults:

270

~ Dynamic Memory:

348 pa!fes

Chapter 12

Optimizing Your Programs
The word optimization, as used in this chapter, refers to the process of improving the efficiency of programs. The objective of optimization is to produce programs that achieve the
greatest amount of processing with the least amount of time, memory and secondary
storage.

12.1 Optimizing with Data Structures
U sing data structures to update files can improve the run-time performance of your programs. This example updates a file with a data structure defined in an Input specification
and used in an Output specification.

12-1

011
I
2
I
3
I
4
151
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

FOUT94A UD F
FOUT94B UD F
IOUT94A AA

24
24

DISK
DISK
1

I
I
I
I
I
I

3 PN

4 10 PNAME

12 WHOUSE
13 17 COLOR
18 20 WEIGHT
22 240QTY
11

IOUT94B AA

1 24 DS94B

IDS94B

I
I
I
I
I
I

3 PN2

4 10 PNAME2
11 12 WHOUS2

13 17 COLOR2
18 20 WEIGH2
22 240QTY2

OOUT94A E
0
0
0
0
0
0

PN
PNAME
WHOUSE
COLOR
WEIGHT
QTY

10
12
17
20
24

DS94B

OOUT94B E

ZK-4432-85

Notice in the above program example that the fields to be updated in the Output specifications for file OUT94B are not listed for a second time, as they would have to be without use
of a data structure. This results in less written code and a program less prone to error,
because the layout ofthe fields is described only once in the data structure. Without a data
structure, the fields must be described on both the Input and Output specifications.

12.2 Optimizing With Adjacent Fields in Records
Note that RPG II extracts adjacent fields from the record buffer with a single VAX MOVE
instruction and writes them back the same way, which saves time_ This optimization is
performed provided no data conversion is necessary. Therefore, it is a good idea to keep the
fields contiguous, to avoid requiring multiple MOVE instructions.

12-2

Optimizing Your Programs

12.3 Optimizing with Blank Factor 1
If you use blank Factor 1, you will have less to write and your program will be less prone to
error because you are not writing the same factor twice. The following example, which is
part of the above program, demonstrates this technique:
011
1213
I
4
I
5
I
6
17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
I

22 240QTY2

C* Read records fro~ update files.
C
READ OUT94A
LR
C NLR
READ OUT94B
C* Update ~uantit~ to reflect the fact that 100 of each part ca~e in.
C NLR
ADD 100
QTY
C NLR
ADD 100
QTY2
C* Write the updated records.
C NLR
EXCPT
ZK-4433-85

12.4 Optimizing File Performance
You can control file access and improve file performance through optimizing techniques
discussed in this manual and in the Guide to VAXIYMS File Applications manual. The
·following optimizing techniques are discussed in Part II of this manual:
• For information on the use of Expansion factors to prevent bucket splitting and to
improve search efficiency, see Section 2.5.23.
• For information on file sharing, see Section 2.5.24.
• For information about multibuffer count, see Section 2.5.2l.
• For information on longer block length for decreasing I/O processing time, see Section
2.5.9.
• For information on multiblock count, see Section 2.5.14.
All ofthe sections mentioned above point to the Guide to VAX/VMS File Applications manual, which provides pertinent information on tuning sequential, relative, and indexed
files. That manual also discusses optimizing file performance and processing in a
VAXcluster, and offers performance recommendations.

Optimizing Your Programs

12-3

Chapter 1

Language Elements
This chapter describes the following elements ofthe RPG II language:
• Character set
• Data types
• User-defined names

1.1 RPG II Character Set
RPG II uses the full ASCII character set. This includes:
• A through Z, uppercase except for character literals and comment fields
• The digits 0 through 9
• Special characters
Appendix A contains the full ASCII character set and character values.

1.2 RPG II Data Types
All data in RPG II input and output operations has a specific data type that determines
how many bits of storage should be considered as a unit and how the unit is to be interpreted and manipulated.
RPG II supports five different data types for data in input and output operations. Following sections describe each data type.
• Character
• Word binary numeric
• Longword binary numeric

1-1

• Packed decimal
• Overpunched decimal

1.2.1 Character
Character data is a string of bytes containing ASCII codes as binary data. The length can
be from 1 to 9999 bytes. The format of a character string is illustrated in Figure 1-1.

NOTE
In all subsequent diagrams, A represents the address of the first byte of the
string and L represents the length of the string in bytes.
7

....

A + L - 1

•

•
7

0
ZK-14S2-83

Figure 1-1: Character String
The address of a string specifies the first character of a string. XYZ is represented in Figure 1-2.

A + 1

....

z
ZK-14S1-83

Figure 1-2: Address of a String

1-2

Language Elements

A+2

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

ZK-1453-83

Figure 1-3: Word Data Type
A longword is four bytes, starting on an arbitrary byte boundary. The bits are numbered
from the right 0 through 31. When interpreted as a signed quantity, a word is a two's complement number with bits increasing in significance from bit 0 through bit 30, and with bit
31 designating the sign. A four byte longword supports up to 11 decimal digits. The largest
number that can be represented by a longword in RPG II is 99,999,999,999. A longword is
represented in Figure 1-4.

_A
ZK-14S4-83

Figure 1-4: Longword Data Type

1.2.3 Packed Decimal
Packed decimal data is stored as a string of bytes. Each byte is divided into two 4-bit half
bytes (nibbles), with one decimal digit stored in each half byte. The first, or most significant, digit is stored in the high-order half byte ofthe first byte, the second is stored in the
low-order half byte of the first byte, the third digit is stored in the high-order half byte of
the second byte, and so on. The sign of the number is stored in the low-order halfbyte of the
last byte of the string. The number + 123, in packed decimal format, is represented in
Figure 1-5.

Language Elements

1-3

A + 1

ZK-1455-83

Figure 1-5: Packed Decimal Data Type
A decimal 10, 12, 14, or 15 represents a plus sign, with 12 used when the number is created
as a result of a VAX arithmetic instruction. A decimal 11 or 13 represents a minus sign,
with 13 used when the number is created as a result of a VAX arithmetic instruction.
The following formula can be used to determine the length in digits of a packed decimal
field:
number of digits = 2n-1
where n = number of bytes used

See Part II, Section 2.8.15 for examples of selecting numeric data types in an RPG II
program.

1.2.4 Overpunched Decimal
Overpunched decimal data is a contiguous sequence of bytes in memory, with one decimal
digit in a byte. Digits of decreasing significance are assigned to increasing addresses. The
sign is superimposed on the last digit (trailing numeric string).
All bytes of overpunched decimal data, except the least significant digit, must contain
ASCII decimal digit characters (0 through 9). Table 1-1 lists the representation for these
nonleast significant digits.

(
1-4

Language Elements

Table 1-1: Overpunched Decimal Representation of Nonleast Significant Digits
Sign

Decimal

Hexadecimal

ASCII Character

0
1
2
3
4
5
6
7
8
9

48
49
50
51
52
53
54
55
56
57

30
31
32
33
34
35
36
37
38
39

0
1
2
3
4
5
6
7
8
9

There are several variations of overpunched decimal format. Alternate forms of
overpunched decimal format are accepted on input. The normal form of overpunched decimal format is generated on output. Valid representations of the digit and sign in each of
the latter two formats (input and output) are shown in Table 1-2.
Table 1-2: Overpunched Decimal Representations of Least Significant
Digit and Sign
Overpunched Decimal Format
Digit
Decimal
Hexadecimal
0
1
2
3
4
5
6
7
8
9
-0
-1
-2
-3
-4
-5
-6
-7
-8
-9

48
49
50
51
52
53
54
55
56
57
125
74
75
76
77
78
79
80
81
82

30
31
32
33
34
35
36
37
38
39
7D
4A
4B
4C
4D
4E
4F
50
51
52

ASCII Characters
Normal
Alternate
0
1
2
3
4
5
6
7
8
9
}
J

{[?
A
B

C
D
E
F
G
H
I

1: !

K
L
M

N
0
P
Q
R

Language Elements

1-5

The following diagrams illustrate the representation of 123 and -123 in trailing numeric
string format. Figure 1-6 represents 123 and Figure 1-7 represents -123.
4

...
...
~

·A

A + 1

A+2

ZK-1456-83

Figure 1-6: Overpunched Decimal Data Type
7

ZK-1457-83

Figure 1-7: Overpunched Decimal Data Type

1.3 USER-DEFINED NAMES
A user-defined name is a named quantity that identifies an entity in an RPG II program.
The name you define specifies the following entities:
• Files
A file name is assigned to a file .
• Fields
A field name is assigned to a field in a program. You can use a field name in more than
one field definition if each definition using that name has the same data type, the
same length, and the same number of decimal positions.

1-6

Language Elements

• Arrays
An array name is assigned to an array. The first three characters cannot be TAB.
• Tables
A table name is assigned to a table. The first three characters must be TAB.
• Labels
A label identifies the destination point for a GOTO operation code.
• Subroutines
A subroutine name is assigned to a subroutine.
• PLIST
A PLIST name is assigned to a list of parameters to be passed to a subprogram.
• EXCPT
An EXCPT name can be used in Factor 2 of the EXCPT operation code and in the
Field name field of exception record 0 specifications.
When defining a name, observe the following rules:
• The first character of a name must be one ofthe following:
- A letter A through Z
- An underscore C)
- A pound sign (#)
• The remaining characters of a name can be the letters A through Z, the numbers 0
through 9, an underscore C), or a pound sign (#).
• You must left-justify names.
• You cannot embed blanks in a name.
• You cannot use an RPG II special word as a name. See Part I, Chapter 6 for information on special words.
• The maximum length of a name is six characters, except for a file name, which can be
up to eight characters.
• Every user-defined name must be unique. For example, a name assigned to a file cannot be used as a field name.

Language Elements

1-7

Chapter 2

Specifications
This chapter describes the following RPG II specifications:
• Control
• File Description
• Extension
• Line Counter
• Input
• Calculation
• Output
Each specification description includes the following information:
• A brief explanation of the purpose of the specification
• The specification's format
• A detailed explanation of each column:
- A brief explanation of the column's purpose
- A table listing valid entries for the column
- An example of a typical use
Use the information in this chapter for quick reference. Consult the Table of Contents or
Index for information on topics requiring a more detailed explanation.

2-1

2.1 Notation Conventions
This section describes the notational conventions of the specifications described in this
chapter.
Two rows of digits identify column numbers, as shown in the following example:
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
ZK-4454-85

The arrow in the following example points to column 43.

ZK-4530-85

In the previous example, the vertical line above the first zero separates columns 30
through 39 from columns 40 through 49; the vertical line above the second zero separates
columns 40 through 49 from columns 50 through 59.
011
I
2
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

•••••••••••

It. I . " " ' , I.'

••••••• III. I

••• I' •••• I. til •••••

•• I

•••••• I

••••

ZK-4455-85

2-2

Specifications

Asterisks (*) in the dotted line below the two rows of column numbers indicate the beginnings of fields that can have values for the specification being described. Each field is terminated by another asterisk, by a dot, or by column 75.
The positions ofthe asterisks are different for each specification.
The asterisk in the example above indicates that you can enter a value in column 6.
The dots in the line below the two rows of column numbers identify fields that must be
blank.

o I 1 I 2 I 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
**

*
ZK-4456-85

Dashes after an asterisk indicate a field that must contain numeric data. Numeric data, if
entered, must be right-justified in the field. Blanks after an asterisk indicate a field that
must contain alphanumeric data. Alphanumeric data, if entered, must be left-justified in
the field.

Specifications

2-3

In the following example, the value 32 has been entered in columns 20 through 23; the
value 41 has been entered in columns 24 through 27; no value has been entered in column
28; the value 9 has been entered in columns 29 and 30; and no value has been entered in
column 31.

*---*---**-*
32

ZK-4457-85

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

2.2.1 Line Number
You can associate a line number with each line in your program. Line numbers are
optional, but can be used to check the sequence oflines. To check line numbers, you must
specify the SEQUENCE_CHECK qualifier to the RPG command. If you do not, RPG II will
ignore all line numbers. The absence of line numbers does not affect your program.

Column
Number

Allowable
Values

Explanation

1-5

Any number

Associates a line number with the program line

Additional Information
If you specify the SEQUENCE_CHECK qualifier to the RPG command and the line numbers are out of sequence, RPG II will issue a warning compile-time error.

2-4

Specifications

2.2.2 Specification Type
You must identify the type of specification on every program line. Use column 6 to specify
the type of specification.

Column
Number

Allowable
Values

Explanation

Specifies that the program line is a Control specification

Specifies that the program line is a File Description
specification

Specifies that the program line IS an Extension
specification

Specifies that the program line is a Line Counter
specification

Specifies that the program line is an Input specification

Specifies that the program line is a Calculation
specification

Specifies that the program line is an Output specification

2.2.3 Comments
Use columns 75 through 80 to write comments about the program line. RPG II ignores
entries in columns 75 through 80. In other implementations ofRPG II, these columns are
used for a program name. RPG II uses the source file name as the name ofthe program.

Column
Number

Allowable
Values

Explanation

75-80

Any character

Documents the program line

Rules
• Blank lines can appear between any two specifications. RPG II ignores blank lines .
• A specification containing only a form feed can appear between any two specifications. Specifications containing only a form feed are treated like blank lines except in
the listing file, where they cause the listing to skip to the top of the next page.

Additional Information
You can also use an entire specification to write a comment when you precede the comment
with an asterisk in column 7. You can do this with any type of specification. However, column 6 must contain an entry for a specification type.

Specifications

2-5

2.3 Compiler Directing Statements
A copy directive allows you to copy one or more source files into the main source file during
compilation. This feature can be used for copying in common subroutines, record definitions, or other useful information.

Rules
• A copy directive may appear anywhere within the source file before the first double
slash (II) or double asterisk (**) line. It cannot appear after that, because the remaining lines do not contain a specification type.
• A copy directive cannot appear within a long character literal.
• There is no limit on the number of copy directives in a program.
• Copy directives cannot be nested. A file copied in cannot contain a copy directive or a
COPY_CDD.
Copy directives can be followed by modifier statements, which supply additional information on preceding Input specification fields. See Section 2.3.3 for the syntax and rules of
modifier statements.
If you specify the SEQUENCE qualifier, then the copied lines are sequence checked separately from the main source file.

Copy and copy from CDD lines are always listed in the listing file. The copied lines immediately follow the copy directive line in the listing. Each line is given a unique listing line
number. A "c" is placed after the line number in the listing record to indicate that the line
was generated by a copy directive. There is still a single set of line numbers to mark the
entire source file, after allowing for text that has been copied into the main source file.
Ifa COMPILE command is issued from the editor and an error is flagged within the compilation of a COpy or COPY_CDD directive, the cursor is placed at the copy directive, and
the message is displayed on the message line. You must leave the editor if you want to see
the compiler source listing.

2-6

Specifications

2.3.1 Copy
Copy directives adhere to the following rules:
• A copy directive must appear on a line of its own, and have the following syntax:
- Column 6 - Any valid specification type (not checked for sequence)
- Columns 7 through 12 - Must contain "/COPY
column 12)

"(note the blank space in

- Columns 13 through 74 - Contain the file specification enclosed in single quotes;
the file specification does not have to start in column 13
• A default file type of RPG is used
Following
is
an
example
that
SO_MUCH_TIME--AND_SO_LITTLE_TO_DO.RPG

copies

file,

the

011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**.*
*
*
*
*
*--*** * * *
C/COPY 'SO_HUCH_TIHE_AND_SO_LITTLE_TO_DO'
ZK-44S8-8S

2.3.2 Copy from COO
Record definitions can be stored in the Common Data Dictionary (CDD) and shared among
RPG programs. You can extract these data definitions from the CDD and use them as field
definitions on Input or Output specifications. If you change a definition in the CDD, you do
not have to rewrite the program using it; however, you must recompile the program to
obtain the latest definition in the CDD.
The following example shows how to copy field information from the CDD, on an Input
specification.

o I 1 I 2 I 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
**
* *** *--- *--I/COPY_CDD 'RECORD. IN'

*---

.**---*---**

******
ZK-44S9-8S

RECORD.IN is the CDD path name for a record description stored in the CDD. A path
name must be enclosed in single quotation marks; note that the pathname does not have to
start in column 17.
For information on CDD pathnames, see the VAX Common Data Dictionary Users Guide.

Specifications

2-7

The CDD provides RPG-specific features. These are: NAME FOR RPG, EDIT_WORD
FOR RPG, and EDIT_CODE FOR RPG. These attributes are discussed in the VAX Common Data Dictionary Reference Manual.
The two examples below show field definitions entered in the CDD, and the Input specifications that must be entered to extract the information.
Using the CDDL utility, these field definitions are entered:
DEFINE RECORD CDD$TOP.EXAMPLE.AODRESS_RECORD
ADDR STRUCTURE.
STREET
DATATYPE IS TEXT
SIZE IS 30 CHARACTERS
CITY
DATATYPE IS TEn
SIZE IS 30 CHARACTERS
DATATYPE IS TEXT
STATE
SIZE IS 2 CHARACTERS
PHONE STRUCTURE.
DATATYPE I S NUMERIC RIGHT OVER PUNCHED
AREA
SIZE IS 3 DIGITS
NUMBER
DATATYPE IS NUMERIC RIGHT OVER PUNCHED
SIZE IS 7 DIGITS
NA ME FOR RPG IS p#
END PHONE STRUCTURE.
END ADDR STRUCTURE.
END ADDRESS_RECORD.

In the RPG II program, these Input specifications are entered:

171

12345678901234567890123456789012345678901234567890123456789012345678901234567890

!INfO

* *** *--AA

*---

.**---*---**

****** ....

I/COPY_CDD 'EXAMPLE. ADDRESS_RECORD'
ZK-4460-85

2-8

Specifications

The information is extracted from the CDD and parsed as though the user had entered the
following:

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
1?34-'678901?3456789012345678901234567890123456789012345678901234567890123456789
**
IINrO

* *** *--AA

I
I
I
I
I
I

*---

.**---*---**
1
31
61
63
63
66

* * * * * * ....

30 STREET
60 CITY
62 STATE
72 PHONE
650AREA
720PIt
ZK-4461-85

2.3.3 Copy Modifiers
To include indicators on Input fields copied from the CDD you must enter a modifier statement after the COPY _CDD statement. You can modify any field in the current record
including those copied from the CDD. The following fields can be modified:
• Control-level indicator
• Matching fields
• Field-record-relation
• Field indicators

Rules
• A modifying statement is distinguished from other specifications by an ampersand
(&) in column 7.
• Only specifications that define fields can be modified.
• As many modifiers as desired can be specified on one modifier specification.
• The same field can be modified by multiple modifiers.
• A field specification must be syntactically valid before and after a modifier is applied.

Specifications

2-9

A modifier can be used to add an indicator where there was none in the original specification. The following example shows a level indicator set on the AREA field in the above
program.

o I
1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
**
* *** *--- *--- *--IINFO
AA
I/COPY_CDD 'EXAMPLE. ADDRESS_RECORD'
1&

******
AREA L1
ZK-44S2-85

The field AREA is treated as if it had been specified with L1 in the control level indicator
field, that is, as if the specification had been as follows:
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
I
63 650AREA L1
ZK-44S3-85

A modifier can be used to supersede a previously specified value. You can also blank a field
by entering the an ampersand (&) as the first character ofthe desired field, and leaving the
rest of the field blank, as in the following example.
This example assumes that the file to be copied (MSL27 A.RPG) contains the following
specification:
011
12
1314
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
I

* *** *---

*---

.**---*---**
******
6 6 FLDA
01
ZK-44S4-85

011
1213
1415
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
* *** *--- *--IMSLI27
01 1 CA
I1COPY 'MSL27A'
1&

*---

.**---*---**
FLDA

******
&
ZK-44S5-85

2-10

Specifications

In the above example, FLDA is treated as ifno field-record-relation indicator is given, for
example, as ifthe Input specification is:
011
12
I
3
14
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
I

* *** *---

*---

.**---*---**
6

6 FLDA

******
ZK-4466-85

Modifiers can apply to all field definitions that follow the record containing the last COpy
or COPY _CDD directive. In the above example, if FLDA occurred several times in the
copied file, each occurrence would be modified.
If the source program looked like the example below, then only the occurrences of the
FLDA field associated with the second copy directive would be modified.

o I 1 I 2 131 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
**

* *** *---

IMSLl27 AA 01
I1COPY 'MSL27A'
I
BB 02
I1COPY 'MSL27A'
1&

*---

.**---*---**

* * * * * * ....

FLDA

&
ZK-4467-85

When a modifier specification is not preceded by a copy directive, all previous input fields
can be modified.

2.4 Control Specification
The Control specification allows you to do the following:
• Assign a character other than the default (a dollar sign ($)) as the currency symbol
• Specify the notation for numeric fields, Edit codes, and UDATE
• Define an alternate collating sequence
• Check the alignment of printed forms
A Control specification is not required. Complete the specification only when you need to
define the use of one or more items described in the list above. Use only one Control specification in a program.

Specifications

2-11

2.4.1 Control Specification Format
The format of the Control specification is:
Currenc~ s~lIIbol

I
I
I
I
I

Inverted print (DIJ)
I
Alternate collating sequence (SE)
I
I
1P f'orllls posi tion (1)
I

H
I
I
I
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

*........... *.. *.... *.............. *................................ .

ZK-4468-85

2.4.2 Specification Type
Use column 6 to identify the type of specification for every program line.

Column
Number

Allowable
Values

Explanation

Indicates that this program line is a Control specification

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

Column
Number

Allowable
Values

Explanation

Blank

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

Character

Uses the character you specify instead ofthe dollar sign ($)
for the currency symbol.

You can use any character for the currency symbol except zero (0), asterisk (*), comma (,),
ampersand (&), decimal point (.), minus sign (-), C (C), and R (R).

2.4.4 Inverted Print
Use column 21 to specify the notation the printer uses for numeric fields, Edit codes, and
UDATE.

2-12

Specifications

Column
Number

Allowable
Values

Explanation

Blank

Uses a period as the decimal notation and a comma as the
thousands separator in numeric literals and Edit codes
(for example, 1,234.56 and .56). Uses a slash (I) as the
separator for the Y Edit code; uses the month/day/year format for UDATE (for example, 03/24/85). See Section
2.10.14 for information on Edit codes. See Part I, Chapter 6
for information on UDATE.

Uses the same format as the Blank option for numeric
literals and Edit codes. Uses a slash (I) as the separator for
the Y Edit code; uses the day, month, and year (ddmmyy)
format for UDATE.

Uses a comma as the decimal notation and a period as the
thousands separator in numeric literals (for example,
1.234,56) and Edit codes. Uses the day, month, and year
(ddmmyy) format for UDATE; decimal points separate the
day, month, and year elements (for example, 24.03.85).

Uses the same format as the I option for UDATE, numeric
literals, and Edit codes with the following exception:
writes a zero to the left of the comma when the field contains only a fraction (for example, 0,56).

2.4.5 Alternate Collating Sequence
Use column 26 to specify the collating sequence you want RPG II to use when comparing
character fields using the COMP operation code and when checking the sequence of matching fields.
Column
Number

Allowable
Values

Explanation

Blank

Uses the ASCII collating sequence. See Appendix A for the
ASCII character set.

Uses the EBCDIC collating sequence. See Appendix A for
the EBCDIC character set.

Uses a user-defined collating sequence. See Appendix A
for the ASCII characters and their hexadecimal values.

Specifications

2--13

To define a collating sequence that is different from the standard ASCII or EBCDIC
sequences, you must specify the hexadecimal value of each character whose position in the
sequence you want to change. To do this you must
• Specify S in column 26 of the Control specification.
• Include the specification for ALTSEQ records after the Output specification, but
before any compile-time table and-arrays, ifused.
• Precede the ALTSEQ records with double slashes (1/) and a blank or double asterisks
(**) and a blank in columns 1 through 3.
• Specify the following entries:
Column
Number

Allowable
Values

Explanation

1-8

ALTSEQbb

Indicates that you are specifying an alternate collating
sequence. Note that bb represents two blanks.

9,10

Hexadecimal
value

Specifies the hexadecimal value of the character you want
to change.

11,12

Hexadecimal
value

Specifies the new hexadecimal value of the character
whose position in the collating sequence you want to
change.

Repeat this sequence of hexadecimal numbers up to column 80 for additional changes. The
first blank space in an ALTSEQ record terminates the ALTSEQ entries for that record.
The rest of the line can be used for comments.
In the following example, columns 9 and 10 and 13 and 14 contain the hexadecimal value
of the character to be changed, and columns 11 and 12 and 15 and 16 contain the new hexadecimal value of the character. In the following collating sequence, RPG II changes the
uppercase Z (5A) to an uppercase A (41) and the lowercase w (77) to an uppercase J (4A).
011
I
2
I
3
I
4
I
5
I
6
I
7
I
t2345678QOt?34567890123456789012345678901234567890123456789012345678901234567890
II

ALTSEQ 5A41774A
ZK-4469-85

(

2-14

Specifications

2.4.6 Forms Position
Use column 41 to check the alignment of printed output on a nonstandard form.

Column
Number

Allowable
Values

Explanation

Blank

Specifies no forms-positioning check

Checks the forms positioning by printing the first output
line

This entry is optional and valid only for a nonspooled device.

Additional Information
When you specify Forms positioning, the printer outputs the first line. Then, RPG II asks
the following question for each printer output file in the order that the first lines are
output:
Is forms positioning correct?
Yes. type Continue. No. type RetrY:

If you type Continue, the program will print the second output line, and so on, until all
lines are output. If the forms are not correctly positioned, realign the form, and then type
Retry. RPG II will print the first line again so that you can determine whether the form is
positioned correctly.

2.4.7 Example
In the following example, the following control characteristics are defined:
• Program line is a Control specification.
• Currency symbol is a pound sign (#).
• RPG II uses:
- A comma (,) as the decimal notation for numeric literals and Edit codes
- A period (.) as the thousands separator for numeric literals and Edit codes
- The ddmmyy format for UDATE with a period (.) separating the day, month, and
year elements
• Collating sequence is EBCDIC.
• Forms-positioning check is not required.

Specifications

2-15

Currencll Slllllbol
I Inverted print (DIJ)
I I
Alternate collating sequence (SE)
I I
I
1P forllls position (1)
I I
I
I
H
I I
I
I
011
12
1314
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

*.......... 1*' 1*," .* ............. I-, .•... I. I .... I I •.... I ....•..•....

ZK-4470-85

2.5 File Description Specification
The File Description specification describes the attributes of each file you use in your
program.

2.5.1 File Description Specification Format
The format ofthe File Description specification is:

Mode (LR)
IKell length
Tllpe (lOUD) I I Record address tllpe (API)
Addtn(AU)
IDes (PSRCTD) II IOrganization (IT, 1-9)
IExpand
IIEOF (E)
I I IIOverflow indicator
IIShat'e
I I ISeq (AD) I I I I I Kell location
III Rewnd
File
1IIIFlllt (FV) II III I Extension (EU
III I
nallle
I I I I IBlk Rec I I I I I I IDevice S~lIIb Tape COt'e III IFile
I I I I lien len I I I I I I Icode dev label index III Icond
I
FI
111111
I II III I II
I
I
I
III II
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

ZK-4471-85

2.5.2 Specification Type
Use column 6 to identify the type of specification for every program line.

Column
Number

Allowable
Values

Explanation

Indicates that this program line is a File Description
specification

2-16

Specifications

2.5.3 File Name
Use columns 7 through 14 to identify the files you use in an RPG II program.
Column
Number

Allowable
Values

Explanation

7-14

File name

Identifies the file

Rules
• The number of files you can open depends on the Open File Quota set by your system
manager. To determine the number of files you can open in an RPG II program, type
the SHOW PROCESS/QUOTA command and look for the number to the right of Open
File Quota:.
• The specification options explained in Sections 2.5.4 through 2.5.26 all apply to the
file you identify in columns 7 through 14.
• VAX RMS uses the file name as the default file specification string. See Part I, Chapter 5 for information about how RPG II uses the File name field and the Symbolic
device field to generate the VAXIVMS file specification.

2.5.4 File Type
Use column 15 to specify the File type that defines how RPG II processes the records in the
file.
Column
Number

Allowable
Values

Explanation

Designates an input file. RPG II reads the records from an
input file and uses these records as data. These records
must be defined in Input specifications unless column 16
contains R or T. Input files can reside on disk or tape, or
can be read from a terminal or from cards.

Designates an output file. The program writes or prints
the records of an output file. These records must be defined
in Output specifications unless this is a table output file.
Output files can be written to a printer, disk, tape, or terminal.

Designates an update file. Update files must reside on
disk. RPG II can read, change, and write records in an
update file. The records in these files must be defined in
the Input and Output specifications.

Specifications

2-17

Column
Number

Allowable
Values

Explanation

Designates a display input or output file. Use display files
to accept input from a terminal or to display output on a
terminal. You must complete a Calculation specification to
define the fields you want to display using the DSPLY
operation code. See Part II, Chapter 3 for information on
the DSPLY operation code.

2.5.5 File Designation
Use column 16 to specify File designation that defines the order of processing files. See
Part I, Chapter 5 for information on processing files.

Column
Number

Allowable
Values

Explanation

Blank

Specifies a nonchained output file or a display file.

Specifies a primary file. You can use only one file as the primary file. It can be an input or an update file. In multifile
processing, the primary file determines the order of record
selection; in single file processing, the primary file provides all input records. If a primary file is not specified and
one or more secondary files are specified, the first secondary file is assigned as the primary file. If no primary or
secondary files are specified, you must provide an exit for
your program by setting on the LR indicator.

Specifies a secondary file. A secondary file can be an input
or an update file. See Part I, Chapter 5 for information on
processing secondary files.

Specifies a record-address file. A record-address file indicates which records to process and the order in which they
are to be processed. This file must be associated with a file
defined in an Extension specification. See Part I, Chapter 5
for information on record-address files.

2-18.

Specifications

Column
Number

Allowable
Values

Explanation

Specifies a chained file. A chained file resides on disk and
can be used as an input, output, or update file. You use the
CHAIN operation code in the Calculation specification to
randomly read records from a chained file. You use an output chained file to add records to a direct file. The CHAIN
operation positions the file before RPG II writes each
record. See Part II, Chapter 3 for more information on
chained files.

Specifies a pre-execution-time table or array. You must
enter, in columns 11 through 18 of the Extension specification, the name of the file that contains the data from which
you want to load the table or array. See Part I, Chapter 7
for information on tables. See Part I, Chapter 8 for information on arrays.

Specifies a demand input or update file. You can use the
READ operation code in the Calculation specification to
sequentially access the records in a demand file. See Part
II, Chapter 3 for more information on using the READ
operation code to access records from demand files.

Specifies a full-procedural input or update file. You can use
the READ and/or CHAIN operation code in the Calculation specification to sequentially and/or randomly access
the records.

2.5.6 End-ol-File
Use column 17 to specify end-of-file that indicates whether or not the program can end
before RPG II processes all the records in the file.

Column
Number

Allowable
Values

Explanation

Blank

Causes the program to finish reading all the records from
every primary and secondary file before ending, if column
17 is blank for all primary and secondary files. If column
17 is not blank for all primary and secondary files, RPG II
mayor may not process all the records in this file (the file
described in this specification). If column 17 is blank for all
primary and secondary files, RPG II processes all the
records in this file (the file described in this specification).

Specifications

2-19

Column
Number

Allowable
Values

Explanation

Causes the program to finish reading the records in the file
before ending the program, regardless of the presence of
other files. You can use this option for input or update files
as primary, secondary, or record-address files. You cannot
use this option on a file being processed by a recordaddress file.
When you specify E in column 17 for the primary file, and
there are matching records in the primary and secondary
files, RPG II reads and processes any records in the secondary file that match the last record of the primary file
before ending the program.

2.5.7 Sequence
Use column 18 to specify the sequence to check matching fields, either ascending or
descending. See Part I, Chapter 5 for information on matching fields.

Column
Number

Allowable
Values

Explanation

Blank

Indicates that the program contains no matching fields or,
ifit does, assumes the same value as specified for a previous primary or secondary file. If the program contains
matching fields and you do not specify a sequence for any
file containing matching fields, RPG II assumes an ascending order.

Checks matching records for ascending order.

Checks matching records for descending order.

Rules
• This entry applies only to primary or secondary files with matching fields. See Part I,
Chapter 5 for more information .
• This entry must be the same for each file you process with matching fields.

2-20

Specifications

2.5.8 File Format
Use column 19 to specify File format. File format specifies whether the records in the file
are all the same length, or whether they can be of different lengths. You can save processing time if all the records are the same length and each record is completely filled with
data. If the records are not completely filled with data, you waste space. Variable-length
records use space more efficiently, but take longer to process.

Column
Number

Allowable
Values

Explanation

Indicates that all records are the same (fixed) length

Indicates that records can be of different (variable) lengths

Rules
• If you specify variable-length records, RPG II uses the highest value in columns 40
through 43 in the Output specification as the length for that record .
• You must specify fixed-length records for sequential files being processed as update
files.

Additional Information
When a variable-length record is read, RPG II fills the unused portion of the input buffer
with spaces. Character fields with characters beyond the end of the record will be filled
with spaces. Numeric fields with digits beyond the record will be filled with spaces. This
condition will
cause a run-time error,
unless
you
use
the
CHECK:BLANKS_IN_NUMERICS qualifier with the RPG command. A numeric field in
packed decimal or binary format cannot extend beyond the end of the input record. If it
does not, unpredictable results will occur.

2.5.9 Block Length
Use columns 20 through 23 to specify the length of a block. Data is stored in physical
records called blocks. A block is the smallest number of bytes RPG II transfers in a physical read or write operation.
In general, by specifying a longer block length, you decrease lIO processing time because
more records will be available at any given time. For example, a program that loads a
single key indexed file with approximately 1700 80-byte records could see a decrease in
direct lias of about 60% and a decrease in elapsed time of 40-50%. This would occur when
the block length is increased from 512 (RMS bucket size of 1) to 4096 (RMS bucket size of
8). However, do not specify a block length that exceeds the Working Set Quota. To display
the Working Set Quota, type the following:
$

SHOW WORKING_SET

For more information on quotas see the VAX/VMS Guide to File Applications.
Specifications

2-21

Column
Number

Allowable
Values

Explanation

20-23

Blank

Uses the same entry for Block length as the Record length
(columns 24 through 27)

1-9999

Specifies the bucket size (in bytes) for those direct and
indexed files being created on disk, or specifies the Block
length (in bytes) for files on tape

. Rules
• For disk files, the block length you specify sets the VAX RMS bucket size parameter.
RPG II divides the block length you specify by 512 and rounds the result to the next
highest integer, if necessary. For example, if you specify a block length of2048 bytes,
the VAX RMS bucket size is 4.
• For disk files, the minimum block length is 512 bytes.
• For tape files, the block length you specify sets the VAX RMS block size parameter.
The block length must be either (1) equal to the entry in columns 24 through 27
(Record length) of the File Description specification, or (2) an integer multiple of the
record length. In either case, the block length cannot be greater than the maximum
record length for the device. See your system manager for the maximum record
length.
To make your tape compatible with non-DIGITAL systems, use the ANSI standard
block length: less than or equal to 2048 bytes.
• Right-justify this entry.
• Leading zeros can be omitted.

2.5.10 Record Length
Record length specifies the length of each fixed-length record in a file, or the maximum
length for variable-length records.
Column
Number

Allowable
Values

Explanation

24-27

1-9999

Specifies the number of characters in each record

Rules
• The record length for fixed-length records in an update file must be the same value
you used to write the records.
• Right-justify this entry.
• Leading zeros can be omitted.
2-22

Specifications

2.5.11 Mode of Processing
Use column 28 to specify the method RPG II uses to access records in a file. Your choice of
processing method depends on the entries for File designation and File organization. Your
choice of processing method for input and update files depends on the entries for the File
type, the Mode of processing, the Record address type, and File organization. Refer to
Tables 2-1 through 2-3 to select the correct value.

Column
Number

Allowable
Values

Explanation

Blank

Accesses records sequentially, or accesses records sequentially by key

Accesses records sequentially within limits

Accesses records randomly, using a relative record number or an index key, or using an ADDROUT file, or tells the
program to load a direct file

Additional Information
• Sequential processing reads the records in the order in which they were written.
• Sequential by key processing reads records from indexed files that are used as primary, secondary, or demand files. The key refers to the index, which is read in ascending order.
• Sequential-within-limits processing reads records in one of two ways:
- Specifying a range of records to be read.
- Using the SETLL operation code in the Calculation specification to set the lowest
key for the records in a demand file. The program reads records with keys equal to
or higher than the key you specify.
• Random processing reads records from chained files in one of the following two ways:
- For sequential or direct files, records are accessed by their relative record number.
A relative record number identifies the position of a record relative to the beginning of the file.
- For indexed files, records are accessed by their index key values.
• ADDROUT file processing uses the ADDROUT file generated by the VAX!VMS
SORT/MERGE utility. The ADDROUT file contains binary record numbers that correspond to the addresses of records, therefore, the records to be read are located by
their addresses.
• Files on devices other than disk can be accessed only sequentially.

Specifications

2-23

Legend for Tables 2-1 through 2-3
Symbol

Meaning

Primary file
Secondary file
Indexed file
Chained file
Table
Full-Procedural file
Blank
Random
Sequential within limits
Alphabetic or Packed keys
Additional areas

I
C
T
F
b
R
L
AlP
(1-9)

For input or update primary, secondary, or demand files that reside on disk, you can use the
entries listed in the following table:

Table 2-1: Modes of Processing for Primary, Secondary and Demand Files
File
Organization

Sequential

or
Direct

Allowable
Acccess Modes

Allowable
Entries
Column:
16
28

Sequential

P
S
D
F

b
b
b
b

(b or 1-9)
(b or 1-9)
(b or 1-9)
(b or 1-9)

ByADDRODT
file

P
S

R
R

b
b

(b or 1-9)
(b or 1-9)

(continued on next page)

2-24

Specifications

Table 2-1: Modes of Processing for Primary, Secondary and Demand Files
(Cont.)
File
Organization

Indexed

Allowable
Acccess Modes

Allowable
Entries
Column:
16
28

Sequential

P
S
D
F

b
b
b
b

ByADDROUT
file

P
S

R
R

I
I

Sequential
by key

P
S
D
F

b
b
b
b

AlP
AlP
AlP
AlP

I
I
I
I

Sequential
within
limits

P
S
D
F

L
L
L
L

AlP
AlP
AlP
AlP

I
I
I
I

For record-address files, you can use the entries listed in Table 2-2.
Table 2-2: Modes of Processing for Record Address Files
File
Organization

Sequential
or
Direct
1

Allowable
Access Modes

Allowable
Entries
Column:
16
28

Sequential'

Indicates a record-limits file
Indicates an ADDROUT file

For input or update chained files, you can use the entries listed in Table 2-3.

Specifications

2-25

Table 2-3: Modes of Processing for Input or Update Chained Files
File
Organization

Allowable
Access Modes

Allowable
Entries
Column:

Sequential
or Direct

Random, by
relative record
number

Indexed

Random,
by key

R
R

b
b

R
R

AlP
AlP

I
I

C
F

In the following example, the program accesses an indexed file as a demand file and three
update chained files.

Mode (LR)
IKe!:l length
Addtn(AU)
T!:lpe (lOUD) I I Record address t!:lpe (API)
IDes (PSRCTD) II IOrganization (IT,1-9)
IExpand
I IShare
IIEOF (E)
I I IIOverflow indicator
I I ISeq (AD) I I I I I Ke!:l location
III Rewnd
File
1IIIFlllt (FV) II III I Extension (Ell
III I
nallle
1IIIIBIk Rec II III I IDevice S!:llllb Tape Core III IFile
I
I I I I II en Ien I I I I I I Icode dev Iabe I index III Icond
III II
FI
IIIIII
I II III I II
I
I
I
011
12
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890
*...... *-----***.**
******---*---**-*** *---**
**
FINDEX1 ID F
18 5AI
5 DISK *
24R
DISK
FCHAIN1 UC F
FINDEX2 UC F
24R 3AI
1 DISK
FCHAIN2 UC F
24R
DISK
ZK-4472-85

2-26

Specifications

2.5.12 Key Length
Use columns 29 and 30 to specify Key length. Key length indicates one of the following:
• The length in bytes of the index keys in an indexed file
• The length in bytes of the index keys in a record-limits file
• The length in bytes of the addresses in an ADDROUT file

Column
Number

Allowable
Values

Explanation

29,30

Blank

Indicates a sequential, direct, or display file

1-99

Specifies the length of the record key for an indexed file or
a record-address file

Rules
• You must use a value of6 for the length ofthe record addresses in an ADDROUT file.
• Right-justify this entry.
• Leading zeros can be omitted.
In the following example, the program reads a chained indexed file. The length of the
record key is 3.

F'ile
nallle
I

Hode (LR)
IKe~ length
T~pe (lOUD)
II Record address t~pe (API)
Addtn(AU)
IDes (PSRCTD) I I IOrganization (IT,i-9)
IExpand
IIEOF' (E)
I I IIOverflow indicator
IIShare
I IISeq (AD) II II I Key location
III Rewnd
I II 1F'lIIt (F'V) I I I I I I Extension (EU
III I
I I IIIBlk Rec I I I I I I IDevice S~lIIb Tape Core III IF'ile
I I I I I Ien Ien I I I I I I Icode dev Iabe I index III Icond
IIIIII
I II III I II
I
I
I
III II

F'I
011
12
13
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

F'INDEX

******---*---**-*** *---**
IC F'

24R 3AI

i DISK

*
ZK-4473-85

Specifications

2-27

2.5.13 Record Address Type
Use column 31 to specify Record address type. Record address type helps define the mode of
processing. Refer to Tables 2-1 through 2-3 to select the correct value.

Column
Number

Allowable
Values

Explanation

Blank

Uses relative record numbers to process sequential and
direct chained files, or reads records sequentially from an
input or update file, or creates or adds records to a sequential output file

Processes or loads indexed files according to the record
keys in alphanumeric format

Processes or loads indexed files according to record keys in
packed format

Processes the file according to an ADDROUT file, or identifies an ADDROUT file

2.5.14 File Organization or Additional 1/0 Area
File organization specifies how records are arranged in a file. Additional I/O allows you to
specify the number of I/O areas. Both attributes work in conjunction with the Mode of
processing. Refer to Tables 2-1 through 2-3 to select the correct value.

Column
Number

Allowable
Values

Explanation

Blank

Indicates a sequential or direct file, using one I/O area

Indicates an indexed file

Indicates an ADDROUT file

1-9

Indicates the number ofI/O areas for a sequential or direct
file

For sequential files, RPG II adds 1 to the Additional I/O area value you specify in column
32. RPG II uses the value for Additional I/O to set the VAX RMS multiblock count in the
Record Access Block (RAB).
See the Guide to VAX/VMS File Applications for information about multiblock count and
for optimizing file performance.

2-28

Specifications

2.5.15 Overflow Indicators
Use columns 33 and 34 to specify an Overflow indicator. You can use an overflow indicator
to specify a page break before or after certain lines are printed. See Part I, Chapter 6 for
information on overflow indicators.

Column
Number

Allowable
Values

Explanation

33,34

Blank

Specifies no overflow indicator

OA-OG,OV

Specifies an overflow indicator to condition output lines
when an overflow occurs

Rules
• You can use an overflow indicator to condition only printer output files.
• You can assign only one overflow indicator to a file. If you have more than one printer
output file and you want to use an overflow indicator to condition each file, you must
specify a unique overflow indicator for each file.

2.5.16 Key Location
Use columns 35 through 38 to specify Key location. Each record in an indexed file has a key
field that VAX RMS uses to locate records. This key field can be anywhere in the record,
but must be in the same location for each record in the file. Key location specifies where to
find the key field in the record.

Column
Number

Allowable
Values

Explanation

35-38

Blank

Indicates that the file is not indexed

1-9999

Specifies the location ofthe key field

Rules
• Right-justify this entry.
• Leading zeros can be omitted.

2.5.17 Extension Code
Use column 39 to specify the Extension code that causes RPG II to read either the Extension or the Line Counter specification for more information about the file. You must complete an Extension specification for tables, arrays, and record-address files. You can
complete a Line Counter specification for a printer output file. The Line Counter specification specifies the length of the printed page and defines the overflow line number.

Specifications

2-29

Column
Number

Allowable
Values

Explanation

Blank

Specifies no Extension or Line Counter specification

Causes RPG II to read the Extension specification for the
file

Causes RPG II to read the Line Counter specification for
the file

2.5.18 Device Code
Use columns 40 through 46 to specify the Device code that indicates on what type of device
the file is stored. Left justify this entry.

Column
Number

Allowable
Values

Explanation

40-46

Blank

Specifies the default disk device.

DISKXXX

Specifies a disk device where X is any character. Disk can
be specified for sequential files but is required for indexed
and direct files. Disk is the default device.

TAPE XXX

Specifies a tape device for sequential files only. X can be
any character.

PRINTXX

Specifies a print device for an output file. X can be any
character.

TTYXXXX

Specifies a terminal device for a display file or a sequentially processed input or update file. X can be any character.

READ XXX

Specifies a card reader for sequentially processed input
files. X can be any character.
To use a card reader, you must specify I in column 15 and P,
S, T, or D in column 16. Also, leave columns 28 through 38
blank.

If you specify a device name other than one of the allowable values, RPG II accepts it, but
issues a warning message at compile time. RPG II assumes a disk device, unless you specify D in column 15, in which case RPG II assumes a terminal (TTY) device.

2-30

Specifications

2.5.19 Symbolic Device
Use columns 47 through 52 to specify the Symbolic device. The Symbolic device can be a
logical name for any device. RPG II uses the Symbolic device as the file name string. VAX
RMS uses the file name string and the default file name string (the file name that appears
in columns 7 through 14) as the default name of a file being processed for input or output
operations. See Part I, Chapter 5 for information on how RPG II uses the Symbolic device
field (columns 47 through 52) and the File name field (columns 7 through 14) to generate
the VAXNMS file specification.

Column
Number

Allowable
Values

Explanation

47-52

Any
character

Represents the symbolic device

The symbolic device name can contain up to six characters.

2.5.20 Tape Label
Use column 53 to identify the label for a magnetic tape.

Column
Number

Allowable
Values

Explanation

Blank

Indicates that the magnetic tape has a standard
VAXNMS ANSI label

VAXNMS can process only magnetic tapes with VAXNMS ANSI labels.

2.5.21 Core Index
Use columns 60 through 65 to set the VAX RMS multibuffer count in the Record Access
Block (RAB). See the Guide to VAX/VMS File Applications manual for information about
multibuffer count and for optimizing file performance.

Column
Number

Allowable
Values

Explanation

60-65

Blank

Specifies that the file is not indexed or that an indexed file
has no Core index

1-9999

Specifies the number of bytes to reserve for the Core index

Specifications

2-31

Rules
• RPG II divides the Core index value by 512 and rounds the value to the next highest
integer, if necessary. For example, ifthe Core index is 513, the VAX RMS multibuffer
count is 2.
If the operation results in an integer that is greater than 127, RPG II uses 127 as the

VAX RMS multibuffer count.

• Right-justify this entry.
• Leading zeros can be omitted.

2.5.22 File Addition and Unordered Output
Use column 66 to specify File addition and Unordered output. File addition and Unordered
output determine how new records are added to a file. You can add records to sequential,
direct, and indexed files that reside on disk. On tape, you must go to the logical end of the
tape before adding records to a file; otherwise, new records would overwrite existing
records.

Column
Number

Allowable
Values

Blank,A, U

For output files, you can choose one ofthe following entries:

Entry

Explanation

Blank

Creates an indexed file and adds records by primary key, or creates a sequential or direct file.

Adds records to an existing indexed or direct file or to the end of an existing
sequential file. When you use this option, you must also specify ADD in columns 16 through 18 of the Output specification.

Creates an indexed file and adds records in an unordered sequence.

For input files, you can choose one ofthe following entries:

Entry

Explanation

Blank

Reads records from a file without adding new records or changing existing
records.

Reads records from an indexed or direct file and allows you to add new
records. When you use this option, you must also specify ADD in columns 16
through 18 ofthe Output specification.

2-32

Specifications

For update files, you can choose one ofthe following entries:

Entry

Explanation

Blank

Allows you to update the records in a file.

Allows you to update the records in, and add records to, an indexed or direct
file. When you use this option, you must also specify ADD in columns 16
through 18 of the Output specification.

You cannot add records to an indexed file that is being processed by a record-address file.

2.5.23 Expansion Factor
When records are added to indexed files, they are placed in buckets. (Buckets hold the contents of records.) If you attempt to randomly add a record into a full bucket, VAX RMS
causes the bucket to split. VAX RMS tries to keep half ofthe records in the original bucket
and moves the other records to a newly created bucket. Each split record leaves behind a
pointer to the new bucket. When the system searches for one of the records in the newly
created bucket, it must first go to the bucket where the record previously resided, read the
pointer, and then move to the bucket pointed to by the pointer. This pointer manipulation
overhead can add up, taking time and wasting disk space.
To prevent bucket splitting and improve search efficiency, use an Expansion factor when
creating an indexed file to reserve bucket space for the records you write to an indexed file.
Also, specify a bucket size that is a multiple ofthe disk cluster size. To show the disk cluster size, type the following:
$

SHOW DEVICE device/FULL

Use column 67 to specify the Expansion factor.

Column
Number

Allowable
Values

Explanation

Blank or 0

Completely fills a bucket

1 (minimum)

Sets index bucket fill size to 50% and sets data fill size to
100%

2 (average)

Sets index bucket fill size to 50% and sets data fill size to
75%

3 (above avg)

Sets index bucket fill size to 50% and sets data fill size to
60%

4 (maximum)

Sets index bucket fill size to 50% and sets data fill size to
50%

Specifications

2-33

Additional Information

• If the records you want to add are distributed unevenly by their key values, then RMS
must split the buckets. In this case, use an Expansion factor of zero.
• Records having key values that are close in sequence, and records added to the end of
the file, cause VAX RMS to split the buckets anyway. For these kinds of records, use
an Expansion factor of zero.
• For output or update indexed files that are being created, RMS uses the Expansion
factor to set the data bucket fill size and index bucket fill size in the key Extended
Attribute Block (XAB). RPG II multiplies the bucket size value by 512 and adjusts the
result based on the percentages listed above.
Table 2-4 shows how the values for Expansion factor and Block length set the values
for the following VAX RMS parameters:
- FAB$B_BKS (bucket size)
- XAB$W _IFL (indexed bucket fill size)
- XAB$W _DFL (data bucket fill size)
See the VAX Record Management Services Reference Manual for information on these
parameters. See the Guide to VAX/VMS File Applications for information on indexed
bucket fill size (index_fill) and data bucket fill size (data_fill).
Table 2-4: Expansion Factor and Block Length Values

2-34

File
Expansion

Block
Length

FAB$B_BKS

XAB$W_IFL

XAB$W_DFL

1 (minimal)
2 (average)
3 (above average)
3 (above average)
4 (maximum)

1536
2048
1024
2048
2000

3
4
2
4
4

768
1024
512
1024
1024

1536
1536
614
1228
1024

Specifications

2.5.24 File Sharing
Use column 68 to specify the file sharing requirements ofthe file. File sharing allows more
than one program to access the records in a file at the same time. If more than one program
tries to access the same record, the first program that accessed the record will be allowed to
change it and
• (S option) the record will be locked preventing access from other programs until the
first program is finished with the record;
• (R option) the record will be locked preventing update access from other programs,
but will not be locked from programs attempting to read the record.
However, on a CHAIN operation code, you can specify an indicator to be set on when a
record is locked, allowing the program to proceed while the record is still locked. See Section II 3.7.1 for information on CHAIN indicators for locked records.

Column
Number

Allowable
Values

Explanation

Blank

Uses RMS default file sharing

Specifies file sharing

Specifies file sharing with the lock for writing option

Rules
• Column 68 must be blank for a display file (D in column 15 of the File Description
specification) and for an ADDROUT file (T in column 32 of the File Description
specification) .
• Specifying S or R in column 68 is valid for a sequential file only if the sequential file
has fixed-format records (F in column 19 of the File Description specification) and
with a record length of 512.

Additional Information
• Table 2-5 illustrates file sharing that is inherently specified as a result of the combination of the entries in columns 15, 66, and 68 of the File Description specification.
The File Description specification that specifies these entries is assumed to be the first
to open the file.

Specifications

2-35

Table 2-5: File Sharing
LEGEND:
Symbol

Meaning

Blank

Columns
15

File
Type

File
Addition

Explanation

Any number of programs with the same entries in these three columns
can read the file simultaneously. Any program with a c\ifferent entry in
File Type or File Addition for this file will receive a file-locked error.

No other program is allowed simultaneous access to the file. Any other
program will receive a file-locked error.

b,A,U

b,A

I,
0,
U

b,A,U

S,
R

Any other program with an S or R in Share can access the file simultaneously, unless the file is for output and the file does not specify A for
File addition, in which case a new version of the file is created. Any
other program with a blank in Share will receive a file-locked error.

• RPG II does not set the SHR field of the FAB (File Access Block) for the file when
Share is left blank. When you specify S in column 68, RPG II sets the SHR field to
allow GET, PUT, DEL, and UPD access. When you specify R in column 68, RPG II also
sets the RLK option. See the Guide to VAX/VMS File Applications for more information on file sharing.

2-36

Specifications

2.5.25 Tape Rewind
Use column 70 to specify Tape rewind that positions a tape according to the current
conditions.

Column
Number

Allowable
Values

Explanation

Blank

Indicates either that the file does not reside on tape, or, if
the file does reside on tape, that the tape will rewind when
the file is opened and closed

UorR

Rewinds the tape when the file is opened and when the file
is closed

Does not rewind the tape

Rewinds the tape when the file is opened

Rewinds the tape when the file is closed

2.5.26 File Condition
Use columns 71 and 72 to specify the File condition. File condition associates an external
indicator with a file. External indicators control file access at run time. When you condition the file with an external indicator, RPG II opens the file only when the external indicator is set on. You can use external indicators to condition primary and secondary input and
update files, record-address files, and output files. You can condition a record-address file
by using an external indicator only if the following conditions are met:
• The record-address file is associated with a primary or secondary input or update file .
• The same indicator (or no indicator) is used to condition the associated file.
See Part I, Chapter 4 for more information on external indicators.

Column
Number

Allowable
Values

Explanation

71,72

Blank

Indicates no external indicator for this file

UI-US

N ames the external indicator that controls file access at
run time

When you condition a file with an external indicator, use the same indicator to condition
calculations and output operations for the same file.

Specifications

2-37

2.5.27 Example
In the following example,
• Line 1020 describes a primary input file with fixed-record format. Each record is 96
bytes. The file CICWMS resides on disk with a symbolic device ofXXl.
• Line 1030 describes a demand file for input with fixed-record format. Each record is 96
bytes. The file CARD58 resides on disk with a symbolic device of XX2. The external
indicator U1 must be set on if the file is to be opened.
• Line 1040 describes a demand file for update with fixed-record format. Each record is
190 bytes. The file ICM resides on disk with a symbolic device ofXX4.
• Line 1110 describes an output file with fixed-length records. Each record is 132 bytes.
The output file CONTRL will be written to the printer whose symbolic device is X11.
The overflow indicator is specified to condition output lines when an overflow occurs.

rile
nalile

Mode (LR)
IKe!:t length
T!:tpe (lOUD) II Record address t!:tpe (API)
Addtn(AU)
IDes (PSRCTD) I I IOrganization (IT,1-9)
IExpand
IIEOr (E)
II IIOyerflow indicator
I IShare
IIISeq (AD) II II I Ke!:t location
III Rewnd
I I Ilrlllt (rV) II II I I Extension (EL>
"I I
1IIIIBIk Rec II II I I IDeyice S!:tlllb Tape Core "I Irile
IllIllen len II III I Icode dey label index I I I Icond
I
111111
I ""I I II
I
I
"I "

I
FI
011
1213
I
4
I
5
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

******---*---**-*** *---**

01020rCICWMS IP r
01030rCARD58 ID r
01040FICM
UD r
01110rCONTRL o r

96
96
190
132

DISK XXl
DISK XX2
DISK XX4
PRINTR Xll

*.111 ••

*-----***.**

Ul
ZK-4474-85

2.6 Extension Specification
The Extension specification allows you to give RPG II additional information about recordaddress files, tables, and arrays. See Part I, Chapter 5 for information about record-address
files. See Part I, Chapter 7 for information about tables. See Part I, Chapter 8 for information about arrays.

(
2-38

Specifications

"-.

In general, use the Extension specification to describe the following information about a
table or array:

• Name of the table or array
• Number of entries per record
• Number of entries per table or array
• Length of each table entry or array element
• Format of numeric data
• Decimal position
• Sequence of entries
• Related tables or related arrays in alternating format
If your program uses a record-address file, complete columns 11 through 26 to provide the
following information:
• Name ofthe record-address file
• Data file associated with the record-address file

If your program uses tables or arrays, the time you load the tables or arrays determines the
columns you must complete. For compile-time tables and arrays, you must complete columns 19 through 57; for pre-execution-time tables and arrays, columns 11 through 57; and
for execution-time arrays, columns 27 through 32 and columns 36 through 45.

2.6.1 Extension Specification Format
The format of the Extension specification is:

------F = Forlllat (PB)
I -----D = Decilllal positions
I I ----5 = Sequence (AD)
III
IllAlternating table or arra~
Frolll
To
Table EntEnt Lenilinallle Len
file
file
or
perin of Fill
of F
nallle
nallle
arra~ RecTbl EntlDI
EntlD
I
I
nallle I I I I I5 I
I I I5
I
I I
I IIII
I 111+-- COllllllents ---+
I
I
E
011
1213
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

ZK-4475-85

Specifications

2-39

2.6.2 Specification Type
Use column 6 to identify the type of specification for every program line.

Column
Number

Allowable
Values

Explanation

Indicates that this program line is an Extension specification

2.6.3 From File Name
Use columns 11 through 18 to specify the From file name that identifies the name of the
record-address file or the input file used to load a pre-execution-time table or array.

Column
Number

Allowable
Values

Explanation

11-18

Blank

Loads the table or array named in columns 27 through 32
(Table or array name) at compile time, if columns 33
through 35 (Entry per record) are completed.
Loads the array at execution time if specified by the Input
and/or Calculation specification and if columns 33 through
35 are left blank.

Name

Names a record-address file, if specified. Otherwise,
names the table or array input file. RPG II uses this file to
load the table or array at pre-execution time.

Rules
• This file name must be the same file name you used in a File Description specification.
• Left-justify this entry.

2.6.4 To File Name
Use columns 19 through 26 in connection with your entry in columns 11 through 18 (From
file name). If you name a record-address file in columns 11 through 18, specify the name of
the input or update file it processes in columns 19 through 26.

2-40

Specifications

Column
Number

Allowable
Values

Explanation

19-26

Blank

Does not write the table or array file at the end of the program.

File name

Identifies the data file associated with the record-address
file, if you use a record-address file. If you do not use a
record-address file, this entry names the output file that
receives the data from the table or array at the end of the
program.

Rules
• This file name must be the same file name you used in the File Description
specification.

• If you want to write a table or an array to an output file at the end of the program,
enter the file name in columns 19 through 26.
• You cannot write an execution-time array to an output file.
• Left-justify this entry.

2.6.5 Table or Array Name
Use columns 27 through 32 to name the table or array you want to use.

Column
Number

Allowable
Values

Explanation

27-32

Blank

Indicates that the file named in columns 11 through 18
(From file name) is a record-address file

Name

Identifies the name of the table or array

Rules
• A table name can be any string of three to six alphanumeric characters, beginning
with TAB. Table names cannot contain embedded blanks.
• An array name can be any string of one to six alphanumeric characters, beginning
with an alphabetic character. Array names cannot begin with TAB and cannot contain embedded blanks.
• If you use tables or arrays in alternating format, this entry describes the name ofthe
main table or array. Identify the alternate table or array name in columns 46 through
51.

• Left-justify this entry.

Specifications

2-41

2.6.6 Number of Entries in a Record
Use columns 33 through 35 to specify the number of entries in a table or array input
record. Complete this entry for compile-time and pre-execution-time tables and arrays.

Column
Number

Allowable
Values

Explanation

33-35

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

Rules
• All records except the last must have the same number of entries. The last record can
have fewer entries to accommodate a number of entries that is not an even multiple of
the defined number of entries in the record.
• 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 you use tables or arrays in alternating format, each record must contain a corresponding entry. The entries from the main table or array and the corresponding
entries from an alternate table or array are treated as one entry.
• Right-justify this entry.
• Leading zeros can be omitted.

2.6.7 Number of Entries in a Table or Array
Use columns 36 through 39 to specify the number of entries in a table or array and in an
alternate table or array, if an alternate table or array is used.

Column
Number

Allowable
Values

Explanation

36-39

Blank

Indicates that the file named in columns 11 through 18
(From file name) is a record-address file

1-9999

Specifies the number of entries in a table or array

2-42

Specifications

Rules
• If a compile-time or pre-execution-time table or array is not completely full, RPG II
fills the unused entries with blanks for alphanumeric data or zeros for numeric data.
If you specify an entry in column 45 (Sequence) of the Extension specification, preexecution-time and compile-time tables and arrays must be full (RPG II does not fill
the short entries).
• Right-justify this entry.
• Leading zeros can be omitted.

2.6.8 Length of Entry
Use columns 40 through 42 to specify the Length of entry that defines the number of character (alphanumeric or numeric) positions in each table or array entry.

Column
Number

Allowable
Values

Explanation

40-42

Blank

Indicates that the file named in columns 11 through 18
(From file name) is a record-address file

1-999

Specifies the number of character positions (both alphanumeric and numeric) in each table or array entry

Rules
• For an alphanumeric entry, the maximum number of characters is 999.
• For a numeric entry, the maximum number of digits is 15.
• For numeric data, the maximum number of digits in binary format is 9.
• For compile-time arrays, the maximum length of an entry is 96, because this is the
largest record that can be entered in the source program.
• When you use table and arrays in alternating format, this entry specifies the length of
the entry in the main table or array.
• Because all entries in a table or array must be the same length, fill unused alphanumeric character positions with blanks and fill numeric entries with zeros.
• Right justify this entry.
• Leading zeros can be omitted.

Specifications

2-43

2.6.9 Format
Use column 43 to specify how numeric data is stored. Data format can be one of the following three formats:

,/
\,,----

• Overpunched decimal
• Packed decimal
• Binary
Base your selection offormat on the storage space available and the frequency of use. See
Part II, Chapter 1 for more information on data formats.

Column
Number

Allowable
Values

Explanation

Blank

Specifies that numeric data is in overpunched decimal format, or that the table or array contains alphanumeric
data. Jfyou do not specify a table or an array, a blank indicates that the file named in columns 11 through 18 (From
file name) is a record-address file.

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

Specifies that numeric data is in binary format. This format is valid only for pre-execution-time tables or arrays.

2.6.10 Decimal Positions
Use column 44 to specify Decimal positions that defines the number of positions to the
right of the decimal point for numeric data in a table or array.

Column
Number

Allowable
Values

Explanation

Blank

Specifies a record-address file or indicates that the table or
array, if used, contains alphanumeric data

0-9

Specifies the number of positions to the right of the decimal point for numeric data in a table or array

You must specify zero for numeric data with no Decimal positions.

2-44

Specifications

(
"-

2.6.11 Sequence
Use column 45 to specify the Sequence that defines the order of entries in a table or array.
RPG II checks each entry for the order you specify.
Column
Number

Allowable
Values

Explanation

Blank

Specifies a record-address file, or indicates that the entries
in a table or an array are unordered

Specifies that the entries in a table or array are in ascending order

Specifies that the entries in a table or array are in descending order

Rules
• Consecutive entries that are equal in value are considered to be in sequence.
• When you use tables or arrays in alternating format, this entry specifies the sequence
of the main table or array.
• When you specify a sequence for a compile-time or pre-execution-time table or array,
RPG II checks the sequence of the entries in a table or an array. If an entry in a compile-time table or array is out of sequence, RPG II reports a fatal error at compilation.
If a pre-execution-time table or array is out of sequence, a run-time error occurs.
• You must specify a sequence if you use an indicator to test for a HIGH or LOW condition in a LOKUP operation associated with the table or array. See Part II, Chapter 3
for information on LOKUP.
• You can specify a sequence for an execution-time array, but RPG II does not check the
sequence. However, if the execution-time array is not in correct sequence and you
specify a LOKUP operation with a HIGH or LOW condition, unpredictable results
will occur.

2.6.12 Alternate Table or Array
Use columns 46 through 57 to define the name, entry length, data format, number of decimal positions, and sequence for an alternate table or array. If you specify a table, you must
use another table as its alternate. If you specify an array, you must use another array as its
alternate. The same rules for columns 27 through 45 apply to the entries in columns 46
through 57.

Specifications

2.6.13 Comments
Use columns 58 through 74 to document the program line.

Column
Number

Allowable
Values

Explanation

58-74

Any
character

Documents the program line

2.6.14 Example
The following example specifies
• A pre-execution-time array to be loaded from the file TABLEF at start of program
execution (line 40)
• A compile-time table with an alternate table (line 50)
• A compile-time array (line 60)
• An execution-time array (line 70)

------r = rorlllat (PB)
I -----D = Decimal positions
II ----5 = Sequence (AD)
III

IllAlternating table or arra~
Table EntEnt Leniliname Len
or
perin of rll I
of r
arra~ RecTbl EntlDl1
EntlD
name I I I 1151
I 115
I
I
I
I I I 1111
I 111+-- Comments ---+
E
I
I
o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
t2345678901234567890123456789012345678901234567890123456789012345678901234567890
rrolll
file
nallle

*.... *

40E
50E
60E
70E

TABLE1

To
file
nallle

*--*---*--****

ARRAY1 4 8
TABLE2 4 8
ARRAY2 30 100
ARRAY3
30

50
1 TABLE3
1
1

*--****
30
ZK·4476-85

2.7 Line Counter Specification
The default length for a page of printer output is 66 lines; the default overflow line is at line
60. When the printer reaches the overflow line, RPG II sets the overflow indicator on.
The Line Counter specification allows you to alter the default page format of a printer output file. You can use this specification to change both the number oflines on a page and the
overflow line.
2-46

Specifications

2.7.1 Line Counter Specification Format
The format of the Line Counter specification is:

length (1-112)
I FL (if For~ length used)
na~e
I I Overflo~ line nu~ber (1-112)
I
I I I OL (if Overflo~ line used)
LI
I I I I
011
12
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
For~

File

ZK-4477-85

2.7.2 Specification Type
Use column 6 to identify the type of specification for every program line.

Column
Number

Allowable
Values

Explanation

Indicates that this program line is a Line Counter specification

2.7.3 File Name
Use columns 7 through 14 to name the output file.

Column
Number

Allowable
Values

Explanation

7-14

File name

Identifies the name ofthe output file

Rules
• The output file must be described on the File Description specification with PRINTER
in columns 40 through 46 (Device code) and L in column 39 (Extension) .
• Left-justify this entry.
See Part II, Chapter 1 for information on naming files.

Specifications

2-47

2.7.4 Form Length
Use columns 15 through 17 to define the number of lines printed on a page. Once the
printer reaches the last specified line, it skips to the next page and resumes printing.

Column
Number

Allowable
Values

Explanation

15-17

1-112

Defines the maximum number oflines that can be printed
on a page

Rules
• This entry must be a numeric value.
• Right-justify this entry.
• Leading zeros can be omitted.

2.7.5 FL
If you specify an entry in columns 15 through 17 (Form length), you must enter FL in columns 18 and 19. This entry specifies that columns 15 through 17 define the Form length.

Column
Number

Allowable
Values

Explanation

18,19

Causes RPG II to use the Form length defined in columns
15 through 17

2.7.6 Overflow Line Number
Use columns 20 through 22 to specify the Overflow line number. When the page reaches
the overflow line, RPG II sets the overflow indicator on.

Column
Number

Allowable
Values

Explanation

20-22

1-112

Specifies the Overflow line number

Rules
• This entry must be equal to or less than the entry in columns 15 through 17 (Form
length).
• This entry must be a numeric value.
• Right-justify this entry.
• Leading zeros can be omitted.

2-48

Specifications

2.7.7 OL
If you specify an Overflow line number in columns 20 through 22 (Overflow line number),
you must enter OL in columns 23 and 24. This entry specifies that columns 20 through 22
define the Overflow line number.

Column
Number

Allowable
Values

Explanation

23,24

Causes RPG II to use the Overflow line number defined in
columns 20 through 22.

2.7.8 Example
In the following example, the Form length is 100 lines and the Overflow line number is
line 96.

Form length (1-112)
File
I FL (if Form length used)
name
I I Overflow line number (1-112)
I
I I I OL (if Overflow I ine used)
LI
I I I I
011
1213
I
4
1516
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

LINPUT

*--* *--* .....

••••

••

••••••

••••••••

•••••

•••••••••••

100FL 960L

ZK-4478-85

2.8 Input Specification
The Input specification describes the records in input and update files. Each record is further divided into fields. Columns 7 through 42 describe the file and its records. Columns 43
through 74 describe the fields in each record.
The Input specification also describes data structure statements and data structure subfields. See Section 2.8.4 for information on data structures.
You must use an Input specification to describe each input or update file except for table
input files and record-address files.

Specifications

2-49

2.8.1 Input Specification Format
The format of the Input specification is:

(AA-ZZ, 01-99)
I NUPlber (1-N)
I 10ptional (0)
DeciPlal positions
I I IRecord identifHing indicator
I
Control level
I III
I
I Match field
I I I I + IdentifHing codes + For Plat
I
I I Fld rec reI
File
I III I
I I (PB)
IField I I I
CI IField
InaPle I I I Field
I III I C C
naPle
I III I
Z
Z
ZI I location I I
I I I indicatrs
I
II
I III Pos NDcPos NDcPos NDc IFr To II
I I 1+- 0
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Se~uence

******

ZK-4479-85

2.8.2 Specification Type
Use column 6 to identify the type of specification for every program line.

Column
Number

Allowable
Values

Explanation

Indicates that this program line is an Input specification

2.8.3 File Name
Use columns 7 through 14 to name the input or update file.

Column
Number

Allowable
Values

Explanation

7-14

File name

Identifies the name of the input or update file

Rules
• Use the same name you specified in the File Description specification.
• If this column is blank, RPG II assumes that the information in this program line
describes a field or record from the file named last.
• Describe all the records and fields for one file before describing another file.
• Left-justify this entry.

2-50

Specifications

In the following example, EMPLOYEE is the name ofthe input file, and the fields NAME
and ADDRES, each containing 20 characters, belong to each record in the file.

Sequence (AA-ZZ, 01-99)
I NUlllber (1-N)
Decilllal positions
I 10ptionai (0)
I
Contro I Ieve I
I I IRecord identif~ing indicator
I
I Match field
I III
I III + Identif~ing codes + Forlllat
I
I I Fld rec rei
File
I III I
I I (PB)
IFieid I I I
nallle
I III I
C
C
CI IField
Inallle I I I Field
I
Z
I I I indicatrs
I III I
Z
ZI II ocation I I
I I I +- 0
II
I III Pos NDcPos NDcPos NDc IFr To II
o I 1 I 2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

IEMPLOYEEAA
I
I

*---

.**---*---**

******

1 20 NAME
21 41 ADDRES
ZK-44BO-B5

2.8.4 Data Structures
Data structures consist of a data structure statement and 0 or more data structure subfields. You must describe data structures on Input specifications. Data structures follow all
Input specifications (including all modifier specifications) for records.
You can use data structures to do the following:
• Define one area of storage more than one way
• Define subfields within a field or subfield
• Reorganize fields in an Input record
• Select the internal numeric data type for fields
• Communicate information between programs with a local data area

Specifications

2-51

2.8.4.1 Data Structure Statement

Column
Number

Allowable
Values

Explanation

7-12

Data
Structure
Name

Identifies the data structure. The data structure name,
which is not required, can be a field defined on Input specifications or Calculation specifications or defined nowhere
else in the program.

Optional. Identifies this data structure as the local data
area.

19-20

Specifies a data structure.

48-51

1-9999

Columns 48 through 51 may optionally contain the data
structure length.

Rules
• The data structure name can appear on only one data structure specification, cannot
be a look-ahead field, and can be specified anywhere a character field is allowed.
• The length of the data structure is one ofthe following:
1.

The length specified in the Input specification, if the data structure name is an
Input field

The length specified in positions 48 through 51 ofthe data structure statement

The highest To position (end position) of a subfield within a data structure, if the
data structure name is not an Input field

• The length computed by the To position must be less than or equal to the length specified in 1 or 2 above.
• Any length on a Calculation specification must match the largest value specified in 1
or 2 above.
• Because it is possible to specify the length of a single data structure in all three ofthe
above ways in a single RPG II program, a compiler diagnostic will be given for any
length conflicts. This will not occur if the length in columns 48 through 51 exceeds the
highest To position for any subfield in the data structure.
2.8.4.2 Data Structure Subfields
Data structure subfields are described in columns 43 to 58. They are defined as on any
other Input field specification. See Section 2.8.11 through 2.8.14 for those field specification requirements.

2-52

Specifications

The field location start and end positions are relative to the beginning of the data structure, not to the beginning of the data record.

Rules
• All columns except columns 43 through 58 must be left blank.
• The subfield name can be the same as a field defined on an Input specification or a
Calculation specification.
• Subfields can be used as factor 1, factor 2, or the result field of a Calculation specification or as Output fields.
• The same subfield name cannot be used in more than one data structure.
• A data structure name cannot be used as a subfield name in another data structure.
• Numeric subfields must contain numeric data when used in CHAIN, LOKUP, COMP,
editing operations, or arithmetic operations.
• If arrays are specified as subfields, the length specified must equal the amount of stor-

age required to store the entire array.
• A data structure subfield can not be an indicator (*IN field) or a UDATE field.
• Overlapping subfields cannot be used in the same calculation in such a way that the
result field overlaps either factor 1 or factor 2. If either factor 1, factor 2, or the result
field references a subfield in a data structure that is an entire array or an array with a
variable index, then that array is used to determine whether overlap exists. The same
array name can be referenced in the appropriate factors of a Calculation specification
without violating the overlap rule.
• Any subfield previously defined in an Input record must agree in length (in digits),
and in decimal positions. If the numeric datatype is different from what was specified
in an Input record, the length (in digits) must still agree.
• Any subfield defined more than once in the same data structure must be defined with
the same datatype and start position, the same length, and the same decimal positions, in the data structure.
• Neither data structures nor data structure subfields can be individual array
elements.
• All entries for a data structure statement and its data structure subfields must appear
together; they cannot be mixed with entries for other data structures.
• A data structure statement and a data structure subfield cannot have the same name.
See Section 2.8.15 for examples of using data structures.

Specifications

2-53

2.8.4.3 Local Data Area
The RPG II local data area is a data structure of up to 512 bytes used as a means of communicating information from one RPG II program to another. In addition, the RPG II local
data area can be manipulated (read or written) at DCL command level or from a program
written in another language.

To specify a local data area, a data structure must have a U in column 18 on the I specs. The
data structure need not have a name. Only the first 512 bytes of the data structure are
loaded at program start and written out at program exit. At most, one data structure may
have a U in column 18.
The RPG II local data area is implemented with VMS DCL symbols (see the VAXIVMS
DCL Dictionary for examples of manipulating DCL symbols). The following 4 symbols are
used and correspond to the indicated bytes within a data structure with U in column 18:
RPG$LDA1

1-128

RPG$LDA2

129-256

RPG$LDA3

257-384

RPG$LDM

385-512

2.8.5 Sequence
Use columns 15 and 16 to specify the Sequence that defines the ordering sequence of the
record types in a file (for example, distinguishing employee name records from employee
badge number records). RPG II does not order records according to sequence; rather, it
checks the sequence of records in the input or update file.

Column
Number

Allowable
Values

Explanation

15,16

Any two
alphabetic
characters

Performs no sequence checking for this record. You can use
any two letters from AA through ZZ, for example, BB, ZA,
or DE. You must specify an alphabetic sequence for
chained and demand files and look-ahead fields.

Blanks

Specifies no sequence checking for this record.

Any
two-digit
number

Assigns a sequence number to a record. You can use any
two numbers from 01 to 99; however, you must use
sequence codes in ascending order, beginning with 01.

RPG II does not require that all Input specifications in alphabetic sequence appear before
those Input specifications in numeric sequence.

2-54

Specifications

2.8.6 Number
If you assigned a numeric sequence code in columns 15 and 16, use column 17 to indicate
the number of records in a record type.

Column
Number

Allowable
Values

Explanation

Specifies that there is only one record of this type

Specifies that there can be more than one record of this
type

Leave this column blank if you specified an alphabetic sequence in columns 15 and 16.

2.8.7 Option
If you assigned a numeric sequence code in columns 15 and 16, you can use column 18 to

specify whether a record of that type must be present to continue processing records.

Column
Number

Allowable
Values

Explanation

Blank

Specifies that a record of that type must be present

Specifies that a record of that type is optional

Leave this column blank, if you specified an alphabetic sequence in columns 15 and 16.

2.8.8 Record-Identifying Indicator
Specifying an indicator in columns 19 and 20 associates the indicator with a particular
record type. When RPG II processes a record of the type you specify for this program line, it
also sets on the indicator, which remains on until after detail-time output. Then, RPG II
sets off all indicators used as record-identifying indicators. See Part I, Chapter 4 for more
information.

Specifications

2-55

Column
Number

Allowable
Values

Explanation

19,20

Blank

Specifies not to set on an indicator when RPG II processes
a record of the type you specify.

01-99

Specifies a record-identifying indicator.

L1-L9

Specifies a control-level indicator. When RPG II sets on
this type of indicator, it does not automatically set on
lower-level control-level indicators.

H1-H9

Specifies a halt indicator.

Specifies a last-record indicator.

Specifies that the fields described on the subsequent program lines are look-ahead fields.

Specifies a data structure.

Look-ahead fields allow you to
• Determine when the last record of a control group is processed
• Extend the matching-field processing capability
Normally, RPG II processes one record at a time. The data from the record currently being
processed is available. With look-ahead fields, you can evaluate the data from the next
record to be processed and then determine which operation to perform.
Any or all of the fields in a file can be specified as look-ahead fields. The description applies
to all records regardless of their record type.
To specify a field as a look-ahead field, you must enter ** in columns 19 and 20 of the Input
specification. Also, you must specify an alphabetic sequence in columns 15 and 16 of the
Input specification. All other columns must be blank. Then, on the next program line,
enter the field name, as shown in the following example:

File
nallle
I
II

Sequence (AA-ZZ, 01-99)
I NUlllber (1-N)
I 10ptionai (0)
Deci~al positions
I I IRecord identifying indicator
I
Contro I Ieve I
I III
I
I Hatch field
I III + Identifying codes + Forlllat I
I I rId rec rei
I III I
I I (PB) IFieid I I I
I III I
C
C
CI IFieid Inallle I I I Field
I III I
Z
ZI Ilocationil
I I I indicatrs
Z
I III Pos NDcPos NDcPos NDc IFr To II
I I I+- 0

* *** *---

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
IEHPLOYEEAA 01
I
I
BB **
I

*---

.**---*---**

******

20 NAHE

25 BADGE
ZK-4481-85

2-56

Specifications

When using look-ahead fields, observe the following rules:
• Look-ahead fields can be used only with input or update primary or secondary files.
• For input files, look-ahead fields apply to the next record in the file.
• For update files, look-ahead fields apply only to the next record in the file if the current record being processed was read from another file. Therefore, if you are using
only one file, the look-ahead field is the current record being processed.
• Look-ahead fields can be specified only once in a file.
• Look-ahead fields cannot be the only record in the file.
• As RPG II processes the last record, it fills any look-ahead fields with 9s. In this case, if
the field is ten characters long, it will contain the data 9999999999.
• Columns 59 through 70 must be blank on Input specifications describing look-ahead
fields.
• You cannot specify Blank after (B in column 39 ofthe Output specification) for lookahead fields.
• A look-ahead field cannot be used as a Result field in a Calculation specification.

2.8.9 Record Identification Codes
Use columns 21 through 41 to define a record type and to specify the code that indicates
how to identify it. You can subdivide these columns into three subsets (columns 21 through
27,28 through 34, and 35 through 41), each defining a different code.
If you use more than one subset, the record must satisfy all record identification codes.
Used in this way, the codes form an AND relationship. IfRPG II cannot identify a record
according to the identification codes of all the records in a file, it issues a run-time error.
If there is only one record type for a file, you can leave these columns blank. Also, you can
leave these columns blank when describing the last record type in a file. This defines a
record type to catch all records that do not fall into any of the record types you previously
described.
RPG II checks records for a record type in the order in which you specify them on the Input
specification.

Specifications

2-57

2.8.9.1 Position
Use columns 21 though 24,28 through 31, and 35 through 38 to define the Position that
specifies where to look for the identification code in the input record.

Column
Number

Allowable
Values

Explanation

21-24
28-31
35-38

Blank

Indicates that there is no record identification code. In this
case, make sure that the corresponding Not, character (C),
zone (Z) or digit (D) portion, and the character columns are
blank.

1-9999

Defines the position of the character you specify in columns 27, 34, and 41. For example, the number in columns
28 through 31 specifies the position of the character in column34.

Rules
• Right-justify this entry.
• Leading zeros can be omitted.

2.8.9.2 Not
Use columns 25, 32, and 39 to specify whether an identification code must be present in the
input record.

Column
Number

Allowable
Values

Explanation

25,32,39

Blank

Indicates that the identification code you specify in the
next two columns (26 and 27, 33 and 34, and 40 and 41)
must be present to identify a record type. For example, if
column 32 is left blank, the identification code in columns
33 and 34 must be present.

Indicates that the identification code must not be present
to identify a record type. For example, if you specify N in
column 39, the identification code in columns 40 and 41
must not be present.

2.8.9.3 CZD Portion
Use columns 26,33, and 40 to specify what portion of the character to use when identifying
a record code. You can use the character (C), zone (Z), or digit (D) portion of the character.
Many characters have either the same zone or digit portion. To distinguish between zone
and digit portions, you must use their EBCDIC equivalent. See Appendix A for the ASCII
character set and their corresponding EBCDIC zone and digit codes.

2-58

Specifications

Column
Number

Allowable
Values

Explanation

26,33,40

Blank

Indicates that there is no record identification code. Its corresponding Position, Not, and Character columns must be
left blank.

Causes RPG II to use the entire character to identify the
record.

Causes RPG II to use the EBCDIC zone portion to identify
the record.

Causes RPG II to use the EBCDIC digit portion to identify
the record.

2.8.9.4 Character
Use columns 27, 34, and 41 to specify the identification character for the input record.

Column
Number

Allowable
Values

Explanation

27,34,41

Any
character

Specifies the character part of the identification code

In the following example:
• I in column 6 specifies that this program line is an Input specification.
• EMPLOYEE in columns 7 through 14 names the input file. This file contains the
name, address, and telephone number for each employee.
• The characters AA in columns 15 and 16 specify no sequence checking.
• RPG II sets on the indicator you specified in columns 19 and 20 (05) after it reads a
record that matches the identification codes defined in columns 21 through 4l.
There are three parts to the code that identifies this record type:
1.

Position 1 must contain the character A.

Position 31 must contain the character C.

3. Position 123 must not contain a character with an EBCDIC digit portion of the
number 6. This includes the characters F, 0, W, 6, f, 0, and w.

Specifications

2-59

Sequence (AA-ZZ, 01-99)
I NUJllber (1-N)
I I Optional (0)
Decilllal positions
I IIRecord identif~ing indicator
I
Contro I Ieye I
I III
I
I Hatch field
I III + Identif~ing codes + Forlllat
I
I I Fld rec I'el
File
I II I I
IField I I I
I I (PB)
nallle
I III I
C
CI IField
Inallle I I I Field
C
I
I II I I
Z
ZI Ilocationil
Z
I I I indicatrs
II
I III Pos NDcPos NDcPos NDc IFr To II
I I I + - 0
o I 1 121 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
**
* *** *--- *--- *--- .**---*---**
******
IEHPLOYEEAA 05 1 CA 31 CC 123ND6
ZK-4482-85

2.8.10 AND/OR
Use columns 14 through 16 to enter AND or columns 14 and 15 to enter OR that associates
two program lines to specify an identification code.
AND specifies that the identification codes in two program lines must be matched in order
to identify the record and to set on the record-identifying indicator, if one is specified.
OR specifies that the identification code in either program line must be matched in order to
identify the record and to set on the record-identifying indicator, if one is specified.

Column
Number

Allowable
Values

Explanation

14-16

AND

Specifies an AND relationship between the identification
codes on this program line and the previous program line

14,15

Specifies an OR relationship between the record identification codes on this program line and the previous program line

Rules
• If you use AND, columns 7 through 13 and 17 through 20 must be left blank.
• If you use OR, columns 7 through 13 and 16 through 18 must be left blank.
• You can enter a record-identifying indicator in columns 19 and 20 in an OR line. If you
leave columns 19 and 20 blank, the record-identifying indicator in the preceding program line also applies to this program line.

2-60

Specifications

In the following example, there are four characters that identify a record type in
EMPLOYEE:
1.

Position 1 must contain the character A.

Position 31 must contain the character C.

Position 1111 must contain the character zero.

Position 123 must not contain the character 6.

The record must meet all the conditions in both program lines before RPG II sets on the
indicator (05).
RPG II identifies a record type in the file RETIRED if position 1 contains the character I
and position 31 contains the character D, or if position 123 does not contain the character
6. The record must meet the conditions defined in either program line before RPG II sets on
the indicator (06).

(AA-ZZ, 01-99)
I NUPlber (l-N)
DeciPlal positions
I 10ptionai (0)
Conkol'level
I I IRecord identif~ing indicator
I
I III
I Match field
I
I I Fld I'ec reI
I III + Identif~ing codes + ForPlat I
File
IField I I I
I III I
I I (PB)
naPle
I III I
C
C
CI IField InaPle I I I Field
ZI II ocation II
I I I indicaks
I
I III I
Z
Z
I I I +- 0
II
I III Pos NDcPos NDcPos NDc IFr To II
o I 1 I 2 I 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Se~uence

* *** *---

*---

IEMPLOYEEAA 05 1 CA 31 CC 123NC6
I
AND
1111 CO
IRETIRED AA 06 1 CI 31 CD
I
OR
123NC6

.**---*---**

****** ....

ZK-4483-85

2.8.11 Format
Use columns 7 through 41 to describe the file and the records in the file. Use columns 43
through 75 to describe the fields of each record. Field descriptions must begin one line
below the file and record description. Use a separate line to describe each field you plan to
use.
If a field contains numeric data, use column 43 to specify its format. You can specify
overpunched decimal, packed decimal, or binary format. See Part II, Chapter 1 for information on data formats.

Specifications

2__61

Column
Number

Allowable
Values

Explanation

Blank

Indicates that the field contains either alphanumeric
characters or numeric data in overpunched decimal format

Indicates that numeric data is in packed decimal format

Indicates that numeric data is in binary format

See Part II, Chapter 1 for information on numeric data types.

2.8.12 Field Locations From and To
You define the fields of a record by specifying their location. Use columns 44 through 47 to
specify the beginning character position ofthe field. Use columns 48 through 51 to specify
the ending character position of the field.

Column
Number

Allowable
Values

Explanation

44-47

1-9999

Specifies the beginning character position of the field

48-51

1-9999

Specifies the ending character position of the field

Rules
• The maximum length of a field depends on the type of data it contains. The maximum
field length of overpunched decimal data is 15. The field length of binary data can be 2
or 4. The maximum field length of packed decimal data is 8. To determine the field
length of packed decimal data, divide the number of digits by 2 and add 1, ignoring the
remainder. For example, if the number of digits in packed decimal data is 9, th~
length is 5. The maximum field length of alphanumeric data is 9999.
• Fields can overlap if you give each field a different name.
• Right-justify this entry.
• Leading zeros can be omitted.

2-62

Specifications

2.8.13 Decimal Positions
If a field contains numeric data, use column 52 to specify the number of digits to the right of
the decimal point.

Column
Number

Allowable
Values

Explanation

Blank

Indicates that this field contains alphanumeric data

0-9

Specifies the number of positions to the right of the decimal point

Rules
• You must specify a value in this column even if the numeric data has no decimal
points. In this case, use zero.
• The number of decimal positions must be less than or equal to the number of digits in
the numeric field.
If you specify 2 in this column and the field contains the data 12345, the field's value is
interpreted as 123.45. If you specify 4 in this column and the field contains the data 12345,
the field's value is interpreted as 1.2345.

2.8.14 Field Name
Use columns 53 through 58 to assign a name to the field you defined in columns 43 through
52, or to specify the page number for PAGE.

Column
Number

Allowable
Values

Explanation

53-58

Name

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

PAGE
PAGE I-PAGE 7

Specifies a page number. See Chapter 6 for information on
paging special words.
Sets the specified indicator. See Chapter 4 for information.

Rules
• The field name can be any combination of six characters except for blanks or special
characters, as long as the first character is a letter. See Part II, Chapter 1 for more
information on user-defined names.
• You cannot use the reserved words UDATE, UDAY, UMONTH, and UYEAR as a field
name.

Specifications

2-63

• Use a unique name for each field. If you use the same name to describe more than one
field in the same record type, RPG II uses the field described last.
• You can use the same name for fields of different record types as long as both fields are
numeric with the same number of digits, or both fields are alphanumeric with the
same length.
• You can load an entire array from an input record by entering the array name in columns 53 through 58. If you do, columns 59 through 62 and 65 through 70 must be
blank.
• You can load an array element by entering the array name followed by a comma and
an array index.
To eliminate duplicate coding, use OR in columns 15 and 16 to define the same field names
for different record types, as shown in the following example:

Sequence (AA-ZZ, 01-99)
I NUlllber (1-N)
I 10ptionai (0)
Decilllal positions
I IIRecord identif~ing indicator
I
Control level
I III
I
I Match field
I III + Identif~ing codes + Forlllat
I
I I Fld rec rei
rile
I III I
IFieid I I I
I I (PB)
nallle
I III I
Inallle I I I Field
C
C
CI IFieid
I
I I I indicatrs
I III I
Z
Z
ZI Ilocationil
II
I III Pos NDcPos NDcPos NDc IF" To II
I I I +- 0
011
12
I
3
I
4
1516
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

IEMPLOYEEAA 05 1 CA
I
OR 06 51 D6

*---

I
I
I

1 30 NAME
31 50 ADD RES
51 600PHONE
ZK-4484·85

In this example, there are the same three fields (NAME, ADDRES, and PHONE) in two
different types of records. In the first record type, there is the character A in position 1. In
the second record type, there is the number 6 in position 51. The NAME field contains
alphanumeric data: it begins in position 1 and ends in position 30. The ADDRES field contains alphanumeric data: it begins in position 31 and ends in position 50. The PHONE field
contains numeric data with no decimal positions: it begins in position 51 and ends in position 60.

2.8.15 Examples of Using Data Structures
This section provides examples of using data structures in an RPG II program.

2-64

Specifications

2.8.15.1 Defining One Area of Storage More Than One Way
The following example shows two fields that would normally require 1550 and 2400 bytes
of storage without data structures. With data structures, however, these two fields are allocated using the same 2400 bytes of storage. In addition, several subfields within these
fields are defined. The byte locations for each data structure subfield identify the locations,
in a single data structure, where each data structure subfield is allocated.

This example also demonstrates the optional length specification of the data structure on
the data structure statement. If you omit the length of the data structure, RPG II computes
it as described in Section 2.8.4.1.

(AA-Zl, 01-99)
I NUlllber (i-N)
I 10ptional (0)
Decilllal positions
I I IRecord identif~ing indicator
I
Control level
I III
I
I Hatch field
I III + Identif~ing codes + Forlllat I
I I Fld rec reI
I III I
I I (PB)
IField I I I
I III I C C
CI IField Inallle I I I Field
11 Ilocationil
I I I indicatrs
I III I
Z
1
I III Pos NDcPos NDcPos NDc IFr To II
I I I+- 0

Se~uence

File
nallle
I
II

011
12
1314
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
* *** *--IPERSNELL
01

*---

IHEDICAL

*--11550 PREC

I
I

12400 HREC
2400

I
I
I
I
I
I

11550 PREC
1 50 CTGRYA
50 100 CTGRYB
100 150 CTGRYC
150 800 BKGRND
8001500 HRUSE

12400 HREC
1 550 IHNLGY
550 950 HHTLGY
9501550 RADLGY
15501950 XRAY
19502400 OPROOH

DS
I*PERSONNEL RECORDS FIELDS

I*HEDICAL RECORDS FIELDS
I
I
I
I
I

ZK-4485-85

Specifications

2-65

2.8.15.2 Defining Subfields Within a Field or Subfield
The following example shows how to divide a field into subfields. To do this, you must specify the name of the field to be divided on the Input specification data structure statement.
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *--**
ISURPLUS
01
I

lITEM

*---

.u---*---u

* * * * * * ....

1 12 ITEM

1 4 WHOSEI!
5 8 AREAl!
9 12 YEAR
11 11 DECADE

I
I

ZK-4486-85

2.8.15.3 Reorganizing Fields in an Input Record
In the following example, a data structure is used to reorganize fields from an Input record.
The first collection of fields describes the Input record field layout. The second collection of
fields (in the data structure) describes how the fields are actually organized in memory
when the program runs.
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
u

IPART
I
I
I
I
I
I
I
I

*---

.**---*---**

******

[

1 3 PN
4 10 PNAME
11

IREGROP

I
I
I
I
I
I
I

* *** *--AA

13
13
18
19
21

',,--

12 WHOUSE
20 COLWEI
17 COLOR
20 WEIGHT
200NWEIGH
24 QTY

19 21 PN
4 10 PNAME
11 17 WHO COL
11 12 WHOUSE
13 17 COLOR
1 3 WEIGHT
23 26 QTY
ZK-4487-85

Specifications

This example shows the difference between an Input field (the PART record) and a data
structure subfield (the REGROP data structure). If either of the fields COLOR or WEIGHT
is changed in a Calculation specification, no change will be reflected in the field COLWEI
because COLOR and WEIGHT are not redefinitions of that field. In contrast, if either
COLOR or WHOUSE is changed, WHOCOL will also change because COLOR is a redefinition of one portion of that field, and WHO USE is a redefinition of another portion of that
field. Changing WHOCOL changes COLOR and WHOUSE. Changing the value of
COLWEI in a Calculation specification will not change COLOR or WEIGHT.
2.8.15.4 Selecting the Internal Numeric Data Type for Fields
The following example shows how to use a data structure to select a numeric data type that
will be used internally. Choosing specific numeric data types can improve performance
where numeric fields are passed as parameters in a CALL, because numeric data type conversion is then not needed at run time. In this example, the numeric data type is as indicated by the field name.

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
I
I
I
I
I

* *** *--DS

*---

.**---*---**
P
B
B

* * * * * * ....

1 30PACKED
4 50WORD
6 90LONGWO
10 1400VERPU
ZK·4488-85

If you specify a numeric data type for a data structure subfield, RPG II does not automatically convert numerics to packed decimal. A numeric conversion is performed if you define
a subfield with a numeric data type that is different from the Input field declaration. Arithmetic comparisons are done with the field maintaining the declared data type. Note that
arithmetic (ADD/SUB/MULTIDIV) is still performed in packed decimal, and a conversion
is done before performing any of the arithmetic operations.
Where RTL routines are called with various numeric data types, you can use data structures to declare the numeric data type so a conversion is not needed for the CALL.
Note that data structures do not support floating point numeric data.

Specifications

2-67

The example below shows several numeric fields defined in an input record, then redefined
with different numeric data types in a data structure. Each field redefinition must agree in
number of digits with any previous field definition.

011
I
2
I
3
I
4
I
5
161
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

IFILE
I
I
I
I
I
I
I
I
I
I
I
I
I

*---

* *** *--BB

*---

.**---*---**
B 1
B 11

******

P 21
31
41
51

20IWORD4
HOILONG9
250IPACK9
340IOVER4
470IOVER7
590IOVER9

1
P 11
B 21
B 31
P 41
B 51

40IWORD4
150ILONG9
240IPACK9
320IOVER4
440IOVER7
540IOVER9
ZK-4489-85

Each field is named to highlight the number of digits assigned to them, as defined in the
input record. For example, PACK9 is defined to be a 5 byte (9 digit) field in the input record.
The data structure indicates that PACK9 will be stored internally in the data structure as
a longword (4 bytes). OVER7 is defined to be a 7 byte (7 digit) field in the input record. The
data structure indicates that OVER7 will be stored internally in the data structure as a
packed field (4 bytes). In all cases, the number of digits for the field as defined on the input
record must agree with the number of digits in any subsequent field redefinition.

2.8.15.5 Examples of Using Local Data Area
The following example demonstrates use of a local data area. The program LDA is as
follows:

011
1213
I
4
I
5
1617
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FTTY
I
I
I

C
C
C
C
C

V
UDS
NAME
AGE

TTY
1 15 NAME
16 170AGE
DSPLYTTY
DSPLYTTY
MOVEL'S. Jones'NAME
Z-ADD29
AGE
SETON

LR
ZK-4665-85

2-68

Specifications

The following commands load the local data area with a name and age. The name and age
are modified in the program, and this information is written back to the local data area on
exit.
$ RPG$LOAI = "K. SMith
$ RPG$LOA1[lS,2J := "as"
$ RUN LOA
K. SrTlith

as
$ SHOW SYMBOL RPG$LOAI
RPG$LOAI = uS. Jones
$ RUN LOA
S.

28"

Jones

The following example demonstrates use of a local data area which contains binary data.
The program LDA-BINARY is as follows:

o I 1 121 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
FTTY

I
I
I
C
C
C
C
C

V
UDS

TTY
1 15 NAHE
170AGE

B 16

NAHE
AGE

DSPLYTTY
DSPLYTTY
HOVEL'S. Jones'NAHE
Z-ADD29
AGE
SETON

LR
ZK-4664-85

$ RUN LOA_BINARY
S. Jones

Specifications

2-69

The following example demonstrates use of a local data area with 386 bytes of information.
The program LDA_386 is as follows:

141

12345678901234567890123456789012345678901234567890123456789012345678901234567890
IDS386

UDS

I
I
C
C

MOVE 'abc'
SETON

1 383 DATAl
384 386 DATA2
DATA2

ZK-4663-85

The following commands display the information written to the local data area by the
program:
$ RUN LDA_3aG
$ CHAR_3811 = F$E)<TRACT (127.1 .RPG$LDA3)
$ SHOW SYMBOL CHAR_3811
CHAR_3811 = "a"
$ SHOW SYMBOL RPG$LDAll
RPG$LDAll = "be"

Note that in this example, the field DATAl is spread over RPG$LDAl, RPG$LDA2 and
RPG$LDA3. The field DATA2 is written to the last byte ofRPG$LDA3 and the first 2 bytes
ofRPG$LDA4.

2.8.16 Control-Level Indicator
Use columns 59 and 60 to specify control-level indicators. Control-level indicators cause
RPG II to compare the contents of a field with the contents ofthe same field from a previous
record. If the fields are not equal, a control break occurs and RPG II sets on the controllevel indicator assigned to that field.
You can use this type of indicator to condition input, calculation, and output operations.

Column
Number

Allowable
Values

Explanation

59,60

Blank

Indicates that this field is not a control field

Ll-L9

Associates a control-level indicator with the field you specify in columns 53 through 58

2-70

Specifications

Rules
• You can specify control-level indicators for primary and secondary files only.
• You can assign control-level indicators in any order.
• Control-level indicators are ranked from highest (L9) to lowest (L1). When a control
break causes RPG II to set on a control-level indicator, all lower control-level indicators are set on. All control-level indicators are set off after detail-time output.
• When you assign the same control-level indicator to more than one field, the fields are
referred to as a split-control field. In this case, fields must be either all numeric or all
alphanumeric and described on adjacent lines. Split-control fields do not have to be
the same length.
• Fields with different control-level indicators can overlap in a record.
• You do not need to specify the same number of control fields for all record types.
• RPG II initializes control fields to hexadecimal zeros. This usually causes a control
break to occur on the first record with a control field. Because ofthis, RPG II bypasses
total-time calculation and output operations for this cycle.
• You cannot specify control-level indicators for binary data or look-ahead fields. Also,
you cannot specify a control-level indicator when you specify an array name in columns 53 through 58.
• RPG II ignores decimal positions and signs (positive and negative) when determining
a control break.
• Because field names are ignored, you can assign the same control level indicator to
multiple fields with the same name.
• If you assign the same control-level indicator to more than one field in different types
of records, the fields must be either all numeric with the same number of digits or all
alphanumeric with the same number of characters.
• The total length of a split-control field must be the same length as other uses of the
same control-level indicator.
• If a control field contains packed decimal data, the zoned decimal length, which is two
times the packed decimal length minus one, is considered the length ofthe field.
See Section 2.8.18 for information about using a field-record-relation indicator with control fields.

Specifications

2-71

In the following example, each record in the file EMPLOYEE contains the same three
fields: NAME, ADDRES, and DEPTNO. The length of NAME is 30 characters; the blank
in column 52 indicates that the contents of the field are alphanumeric. The length of
ADDRES is 20 characters. Both fields are assigned the same control-level indicator (L8),
so they are split-control fields. DEPTNO contains more significant data and as such, is
assigned a higher-level control-level indicator. When the contents of DEPTNO changes,
RPG II sets on both control-level indicators (L9 and L8).

Sequence (AA-ZZ, 01-99)
I NUlllbe,' (1-N)
Decilllal positions
I IOptional (0)
Contro I Ieve I
I
I I IRecord identif~ing indicator
I Match field
I III
I
I III + Identif~ing codes + Fot'Plat
I
I I FId ,'ec ,'e I
File
I III I
I I (PB)
IFieid I I I
nallle
CI IFieid
InaPle I I I Field
I III I
C
C
I
I III I
Z
ZI II ocation II
I I I indicat"s
Z
I I I + - 0
II
I III Pos NDcPos NDcPos NDc IFr To II
011
121
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

* *** *---

*---

IEMPLOYEEAA 05 1 CA 31 CC
I
OR 99 123ND6

*---

I
I
I

* * * * * * ....

1 30 NAME L8
31 51 ADDRESL8
123 1230DEPTNOL9
ZK·4490·85

2.8.17 Matching Fields
Use columns 61 and 62 to specify matching fields. Matching fields tell RPG II to compare
the fields in records from one or more files. When the contents of a field from a primary file
match the contents of a field from a secondary file, RPG II sets on the matching-record
indicator (MR).
You can use the matching-record indicator to condition calculation and output operations.

Column
Number

Allowable
Values

Explanation

61,62

Blank

Indicates that this field is not a matching field.

M1-M9

Identifies a matching field. See Part I, Chapter 5 for information about matching fields and multifile processing.

Rules
• You can use matching fields with one file to perform sequence checking or with multiple files to control the order of processing records. See Part I, Chapter 5 for information on multifile processing.
2-72

Specifications

• You can compare only those fields from records in primary and secondary input and
update files.
• You can compare up to nine different fields in a single record.
• If you specify more than one matching field for a record type, all the fields are logically
concatenated and treated as one continuous field. The fields are combined according
to descending sequence (M9 to Ml) of matching field values.
• The program performs sequence checking for all record types with matching field
specifications. An error in sequence causes a run-time error and terminates the
program.
• You must define the same number of matching fields and the same matching field values (MI-M9) for all those records that contain matching fields.
• You can overlap matching fields in a single record.
• Whenever you use more than one matching code, all matching fields must match
before RPG II sets on the matching-record indicator (MR).
• Matching fields assigned the same matching code (MI-M9) must be either both
numeric with the same number of digits, or both alphanumeric with the same length.
• Not all files or all record types within one program must have matching fields. However, at least one record type from each of two files must have matching fields if the
files are to be matched.
• If the matching field contains packed data, the zoned decimal length, which is two
times the packed length minus one, is considered the length ofthe matching field. It is
valid to match a packed field in one record against a zoned decimal field in another if
the digit lengths are identical. The length must always be odd, because the length of a
packed field is always odd.
• The file sequence you specify in column 18 of the File Description specification must
be the same for the files you compare - all ascending or descending.
• You can check the sequence of a single sequential file using MI-M9 codes to designate
the order of sequence. If the file is out of sequence, a run-time error occurs.
• You cannot specify matching values for binary data and look-ahead fields. You cannot
specify matching values when you specify an array name in columns 53 through 58.
• If you specify an alternate collating sequence, RPG II uses the alternate sequence
when comparing the values in matching fields containing alphanumeric data.
• RPG II ignores field names, so fields from different record types can have the same
name and match code.

Specifications

2-73

• When you specify an ascending sequence check, RPG II initializes the matching value
to hexadecimal zeros. When you specify a descending sequence check, RPG II initializes the matching value to hexadecimal FFs. RPG II initializes the matching value of
a numeric field to zero.
• RPG II compares matching fields containing numeric data based on their absolute
values because decimal positions and signs are ignored.
• Matching fields cannot be split: the same matching field value cannot be used more
than once for one type of record.
• When you specify a matching field value for a field without a field-record-relation
indicator, you must specify all matching field values once without a field-record-relation indicator. If all matching fields are not common to all records, use a dummy
matching field. See Section 2.8.18 for information on using a field-record-relation
indicator with matching fields.
• Matching fields are independent of control-level indicators.
See Part I, Chapter 5 for examples of matching fields.

2.8.18 Field-Record-Relation Indicator
Use columns 63 and 64 to specify Field-record-relation indicators that control the conditions under which RPG II extracts data from the input buffer into a field. These conditions
include control breaks, matching records, halts, and external indicators.
.
The most common use of a field-record-relation indicator is as a record-identifying indicator to group several different record types in an OR relationship and associate fields with a
particular record type. You can also use field-record-relation indicators to extract data if a
particular external indicator is on.

2-74

Specifications

Column
Number

Allowable
Values

Explanation

63,64

Blank

Indicates no field-record-relation indicator

01-99

Indicates that the field-record-relation indicator is a
record-identifying indicator

LI-L9

Indicates that the field-record-relation indicator is a control-level indicator

Indicates that the field-record-relation indicator is the
matching-record indicator

UI-US

Indicates that the field-record-relation indicator is an
external indicator

HI-H9

Indicates that the field-record-relation indicator is a halt
indicator

Rules
The following rules apply to field-record-relation indicators used with control and matching fields:
• You must specify control fields and matching fields without field-record-relation
indicators before those fields with them.
• When the field-record-relation indicator associated with a matching or control field is
on, RPG II uses that field as the control or matching field for the record rather than
the same control or matching field specified without a field-record-relation indicator.
Otherwise, RPG II uses the control or matching field without the field-record-relation
indicator.
• When you have not defined an entire set of matching fields without a field-recordrelation indicator, a full set of matching fields must be assigned to each field-recordrelation indicator used with a matching field.
• You must use the same field-record-relation indicator for split-control fields. You must
describe the split-control fields on consecutive lines.
• You must group control and matching fields that use field-record-relation indicators
according to indicator.
• Field-record-relation indicators for control and matching fields can be only 01
through 99 or HI through H9 indicators. Also, the field-record-relation indicator for
control and matching fields must be a record-identifying indicator specified on either
the preceding record definition line, or in one of the lines in an OR relationship.

Specifications

2-75

If you have two records of eight fields each, and the first seven fields are the same but the

last field is different, you can use the record-identifying indicator as the field-record-relation indicator to condition the field that is different, rather than defining all eight fields for
both records.
In the following example, the last two fields were conditioned with the same record-identifying indicators in lines 1 and 2. If the job code is 2, RPG II uses the bonus amount from
positions 72 through 74. Ifthejob code is not 2, RPG II uses the bonus amount from positions 75 through 77.

(AA-ZZ, 01-99)
I Number (i-N)
I IOptional (0)
Decimal positions
Contro I Ieve I
I I IRecord identif~ing indicator
I
I III
I Match field
I
I I Fld rec rei
I III + Identif~ing codes + Format
I
IFieid I I I
File
I III I
I I (PB)
I III I
CI IFieid
Iname I I I Field
C
C
name
ZI Ilocationil
I I I indicatl's
I III I
I
Z
Z
I I I+- 0
II
I III Pos NDcPos NDcPos NDc IFI' To II
011
12
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Se~uence

* *** *---

IEMPLOYEEAA 01 71 C2
I
OR 02 71NC2
I
I
I
I
I
I
I
I

*---

.**---*---**

******

1 10 FNAME
12 MINIT
13 33 LNAME
34 54 ADDRES
55 60 STATE
61 700PHONE
71 710JOBCDE
72 742BONUS 01
75 772BONUS 02
11

ZK·4491-85

2-76

Specifications

2.8.19 Field Indicators
Use columns 65 through 70 to specify Field indicators. Field indicators check the condition
of numeric or alphanumeric fields when they are extracted from the input record. Once
checked, the field can be in one of three conditions:
1.

If the numeric field in columns 53 through 58 is greater than zero, the condition is
positive and RPG II sets on the field indicator in columns 65 and 66. Otherwise,
RPG II sets offthe indicator.

If the numeric field in columns 53 through 58 is less than zero, the condition is
negative and RPG II sets on the field indicator in columns 67 and 68. Otherwise,
RPG II sets offthe indicator.

If the numeric field in columns 53 through 58 is equal to zero, or if the alphanumeric field in columns 53 through 58 contains blanks, the condition is null and
RPG II sets on the field indicator in columns 69 and 70. Otherwise, RPG II sets off
the indicator.

Column
Number

Allowable
Values

Explanation

65-70

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 check for errors in data. For example, you can
specify a halt indicator to check for zeros in a numeric
field. If RPG II processes the record and finds a zero in the
field, it sets on the halt indicator that results in a run-time
error.

Rules
• Use columns 65 through 70 to check numeric fields.
• Use columns 69 and 70 to check alphanumeric fields.
• You can use the same field indicator for more than one field in different record types.
The status of the indicator depends on the record type last read.
• Columns 65 through 70 must be blank when columns 53 through 58 contain an array
without an index or look-ahead fields.
• You can assign one or more field indicators to a numeric field.

Specifications

2-77

2.9 Calculation Specification
The Calculation specification allows you to describe the calculations you want to perform
and to define their order in the following ways:
• Entries in columns 7 through 17 control when a calculation is performed.
• Entries in columns 18 through 53 describe the kind of calculation.
• Entries in columns 54 through 59 specify which indicators the program sets on or off
as a result of the calculation.
There are two general rules:
1.

Specify each calculation on a single line; arrange the calculations in the order
you want them executed.

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

2.9.1 Calculation Specification Format
The format ofthe Calculation specification is:

Field length
I Deci~al positions
I IHaif adjust (H)

Contro I Ieve I
I

I Indicators

Operation

I I
I I

I
I
I
I

factor
I I
1
CI NxxNxxNxxl
011

Resultl II indicators
field I 11+ - 0
I
I II> < = +- Co~~ents --+

factor
2
I
I

"IIResulting

171

12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

ZK-4492-85

2.9.2 Specification Type
Use column 6 to identify the type of specification for every program line.

Column
Number

Allowable
Values

Explanation

Indicates that this program line is a Calculation specification.

2-78

Specifications

2.9.3 Control Level
Use columns 7 and 8 to indicate whether the calculation is performed at detail time, is
performed at total time, or is part of a subroutine.

Column
Number

Allowable
Values

Explanation

7,8

Blank

Performs the calculation at detail time, or indicates that
the program line is part of a subroutine.

Performs the calculation at total time for each program
cycle.

LI-L9

Performs the calculation at total time after a control break
occurs, or when you use the SETON operation to set on the
control-level indicator, or when the indicator is set on as a
record-identifying indicator, or when the indicator is set
on as a resulting indicator in a calculation.

Performs the calculation at total time after the program
processes the last record, or when you use the SETON
operation to set on the LR (last-record) indicator, or when
the indicator is set on as a record-identifying indicator, or
when the indicator is set on as a resulting indicator in a
calculation.

Indicates that the calculation is part of a subroutine.

ANorOR

Establishes a relationship between two program lines. If
you use AN, the conditions for the indicators in both program lines must be satisfied before RPG II executes the
calculation. If you use OR, the conditions for the indicators
in one program line or the other must be satisfied before
RPG II executes the calculation.

You can use an unlimited number of AN or OR program lines with up to three indicators on
each line to condition a single calculation. The last line in an AN or OR relationship specifies the calculation.

Additional Information
You can specify the following declarative statements in total-time calculations and optionally leave columns 7 and 8 blank:
• EXTRN
• GIVNG

Specifications

2-79

• PARM
• PARMD
• PARMV

• PLIST
• TAG
In the following example, the Ll, L2, L3, and LR control-level indicators perform calculations at total time after a control break occurs or when the SETON operation code sets on
the indicator.

Control level
I

I Indicators

Operation

I I

I
I
I
I

I I

ractor

I I

CI NxxNxxNxxl

ractor
2
I

Held length
I Deci~al positions
I IHaif adjust (H)
I II
I IIResulting
Resultl I Iindicators
field I 11+ - 0
I
I II> < = +- Co~~ents --+

011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C*
C*
CL1
CLl
CL1
CLi
CL1
C*
CL1
CL1
C*
CL1
CL3
C*
CL3
CL1
C*
CL1
CL2
CLR

*
*
*
Total calculations:

'L l'

SETor
SETor
SETor
DSPLYS
SETor

PELHAM

EXSR HILLS
TAG

'L 2'
'L 3'

DSPLYS
DSPLYS

*--*** * * *
LRL9LB
L7L6L5
L4L3L2
L2L3LR

EXSR CARROL
GOTO PETERB
'L 4'
6

DSPLYS
COMP BERRY
SETor

313233
24
ZK-4493-85

2-80

Specifications

2.9.4 Indicators
Use indicators in columns 10, 11, 13, 14, 16, and 17 to condition the calculations you specify in columns 28 and 32. You can specify up to three indicators per program line; precede
the indicator with N to cause RPG II to perform the calculation only when the indicator is
not on. Use columns 9 through 11 to describe the first indicator, columns 12 through 14 to
describe the second, and columns 15 through 17 to describe the third. Using the indicators
this way forms an AND relationship.

Column
Number

Allowable
Values

Explanation

10-11
13-14
16-17

Blank

Performs the calculation whenever the conditions specified in columns 7 and 8 are satisfied.

Indicator

Performs the calculation when the conditions for the indicator are met.

Causes RPG II to perform the calculation only when the
indicators associated with N are not set on. N in column 9
conditions the indicator in columns 10 and 11. N in column
12 conditions the indicator in columns 13 and 14. N in column 15 conditions the indicator in columns 16 and 17.

9,12,15

Additional Information
• You can use one of the following indicators in columns 10 and 11, 13 and 14, and 16
and 17:
- Record-identifying (01-99)
- Control-level (L1-L9)
- Last-record (LR)
- Matching-record (MR)
- Halt indicator (H1-H9)
- External (U1-U8)
- Overflow (OA-OG, and OV)
- K indicators (KA-KZ, and KO-K9)
• RPG II performs total calculations for a control break before performing detail-time
calculations for the record that causes the control break.

Specifications

2-81

• Halt indicators in columns 10, 11, 13, 14, 16, and 17 cause RPG II to bypass the operation when it finds an error in the input data or in a previous calculation. RPG II
processes the record that causes the error before stopping your program. In this case,
the record in error could cause an error in calculation before your program
terminated .
• Depending on the relationship between indicators in columns 7 and 8 and columns 9
through 17, the actions RPG II takes will vary as follows:
- When you specify a control-level indicator in columns 7 and 8 and a matchingrecord indicator in columns 9 through 17, MR indicates the result of matching the
previous record rather than the record just read that caused a control break. RPG II
executes all the operations conditioned by control-level indicators before determining the matching condition of the record just read.
- When you use a control-level indicator in columns 10, 11, 13, 14, 16, and 17 instead
of columns 7 and 8 of the Calculation specification, RPG II performs the calculation
on the first record of a new control group at detail time.
- In a single program cycle, RPG II performs all operations conditioned by the control-level indicators in columns 7 and 8 before it performs the operations conditioned by the control-level indicators in columns 9 through 17.
- If you condition a calculation with a last-record indicator in columns 9 through 17
when columns 7 and 8 are blank, the calculation is performed only if the last-record
indicator is set on during detail-time calculations. Ifthe last-record indicator is set
on when RPG II reaches the end of a file or during total-time calculations, RPG II
does not perform detail-time calculations.
In the following example, the record-identifying indicators 01, 02, and 03 must be on to
perform the calculation SALARY * BONUS1 = GROSS. In the second program line, the
indicator 04 must be off and indicator 05 must be on to perform the calculation
SALARY * BONUS2 = GROSS.

Field length
I Deci~al positions
I
I IHalf adjust (H)
Operation
I II
I Indicators
I I
I IIResulting
I
I I
Factor
I
Factor
Resul t I II indicators
I I
1
field I 11+ - 0
I
2
CI NxxNxxNxxl
I
I
I II> < = +- Co~~ents --+
I
011
I
2
13
I
4
I
5
I
6
I
7
Contr'o I Ieve I

12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

C 01 02 03SALARY
C N04 05 SALARY

*MULT *BONUS1

MULT BONUS2

GROSS
GROSS

*--*** * * *
ZK·4494-85

2-82

Specifications

2.9.5 Factors 1 and 2
Use columns 18 through 27 and 33 through 42 to provide the operands for the calculation
you specify in columns 28 through 32. Use columns 18 through 27 for Factor 1 and columns
33 through 42 for Factor 2. The operands you use depend on the operation you specify. See
Part II, Chapter 3 for information on operations and the operands they require.

Column
Number

Allowable
Values

Explanation

18-27 or
33-42

Field name

Names the field that contains data. These are the same
fields you defined in columns 53 through 58 of the Input
specification or in columns 43 through 48 of the Calculation specification.

18-27 or
33-42

Literal

Specifies an alphanumeric or numeric constant. Numeric
literals can consist of the digits 0 through 9, one decimal
point, and one arithmetic sign. Numeric literals cannot
exceed ten characters and cannot contain blanks. You
must specify the sign in the leftmost character position.
Alphanumeric literals can be up to eight characters
including blanks. You must enclose alphanumeric literals
in single quotation marks (for example: 'NH'). Use the
keyboard apostrophe mark for the single quotation mark.
If you want to use an apostrophe in a literal, you must
enter two consecutive apostrophes (for example: it' 's).

8-74

Long
Character
Literal

Specifies an alphanumeric constant that contains 1 to 460
characters. A double quotation mark (") is placed in the
first character of the field on the specification. The rest of
the field is left blank. On the next line, a double quotation
mark is placed in column 7. Columns 8 through 74 contain
the character literal, which must be enclosed within single
quotation marks. The character literal can be anywhere
on the line.
If you wish the character literal to continue on the next
line, follow the ending single quotation mark with a plus
sign ( + ), and continue the literal in the same manner on
the next specification. All the rules for "normal" character
literals apply to the long character literal placed in columns 8 through 74.

Specifications

2-83

Column
Number

Allowable
Values

Explanation
If more than one long character literal is entered on a calculation specification, the character literal for the first
(leftmost) entry is on the next specification, followed by
the character literal for the second entry, on the specification after that.

Table or
Array

Specifies the table name, array name, or array element
you have previously specified in an Extension specification.

Subroutine
Name

Specifies one ofthe following components of a subroutine:
BEGSR (marks the beginning of a subroutine) and EXSR
(executes a subroutine).

Special
words

Specifies one of the following special words: UDATE,
UMONTH, UDAY, UYEAR, PAGE, PAGEl through
PAGE 7 , *IN, and *IN xx. See Part I, Chapter 6 for information on special words. See Part I, Chapter 4 for information
on *IN and *INxx.

Label

Specifies the label for a TAG, GOTO, and ENDSR operation. See Part II, Chapter 3 for information on TAG,
GOTO, and ENDSR operation codes.

File name

Specifies the file name for CHAIN, DSPLY, READ,
SETLL, or FORCE operations. See Part II, Chapter 3 for
information on specifying files for these operations.

Note that you must left-justify the entries in Factors 1 and 2, unless they are numeric
literals, which must be right-justified.
In the following example, the literal 'All work and no play make Jack a dull boy.' is moved
to the field SHINE.
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
C

MOVE "

*--*** * * *

SHINE 80

C" 'All work and no pla~ Plake Jack a dull bo~.'
ZK·4495·85

2-84

Specifications

This example shows a long character literal continuing on another line.

o I 1 I 2 I 3 I 4 151 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
** *

COl
COl

'a dull bo~.'

MOVE "

*--*** * * *

80
'All ~ork and no pla~ ~ake Jack '+
SHINE

ZK·4496-B5

2.9.6 Operation Code
Use columns 28 through 32 to specify the Operation code that indicates what calculation to
perform on the operands you specified in columns 18 through 27 and 33 through 42. See
Part II, Chapter 3 for more information on operation codes.

Column
Number

Allowable
Values

Explanation

28-32

Operation
Code

Performs the action specified by the operation code. See
Part II, Chapter 3 for information on operation codes.

2.9.7 Result Field
Use columns 43 through 48 to provide the Result field that will contain the outcome of the
calculation you specified in columns 18 through 42. You can use a field you have previously
specified in an Input, Calculation, or Extension specification or use columns 49 through 52
to define its length and decimal positions.

Column
Number

Allowable
Values

Explanation

43-48

Name

Identifies the Result field. The Result field can contain a
field name, table or array name, array element, or one of
the following special words: PAGE, PAGEI-7, *IN, or
*INxx.

Rules
• The Result field name can be any combination of alphanumeric characters; the first
character must be alphabetic. Embedded blanks are not allowed .
• You cannot use a look-ahead field, a field defined by an EXTRN operation, UDATE,
UDAY, UMONTH, or UYEAR as a Result field.

Specifications

2-85

2.9.8 Field Length
If you use the Calculation specification to define a Result field, use columns 49 through 51
to define the length of the Result field you specified in columns 43 through 48. Otherwise,
you can leave columns 49 through 51 blank. To prevent undefined or truncated results,
make sure the length ofthe Result field is long enough to hold the largest possible result.

Column
Number

Allowable
Values

Explanation

49-51

1-999

Specifies the length ofthe Result field

Rules
• The maximum length for numeric data is 15 digits.
• The maximum length for alphanumeric data is 999 characters.
• If the field is described elsewhere in the program and an entry is made in columns 49
through 51, both entries must specify the same length.
• Leading zeros can be omitted.
• Right-justify this entry.

2.9.9 Decimal Positions
If you use the Calculation specification to define the Result field and the Result field contains numeric data, use column 52 to specify the number of positions to the right of the
decimal point.

Column
Number

Allowable
Values

Explanation

Blank

Indicates that this field contains alphanumeric data or
that the Result field has been defined elsewhere

0-9

Specifies the number of positions to the right of the
implied decimal point

Rules
• If the field has been previously described in the program, and an entry is made in
column 52, both entries for Decimal positions must be the same.
• The number you specify in this column must be smaller than the number in columns
49 through 51.
• If the Result field contains alphanumeric data, leave this column blank.

• When the result is numeric, but has no decimal positions, you must specify zero.

2-86

Specifications

2.9.10 Half Adjust
Use column 53 to specify whether RPG II is to round the numeric data in the Result field.
RPG II adds 5 to the position immediately to the right of the last digit and puts the new
value in the Result field. RPG II performs the addition on the absolute value ofthe number.
For example, if the result of an arithmetic operation is 123.456 and the Result field specifies two decimal positions, RPG II half-adjusts the value in the Result field to 123.46.

Column
Number

Allowable
Values

Explanation

Blank

Performs no half-adjusting

Half-adjusts the numeric data in the Result field

Rules
• You cannot half-adjust the Result field of an MVR operation, or of a DIV operation
immediately followed by an MVR operation.
• You cannot half-adjust alphanumeric data.

Additional Information
• RPG II sets resulting indicators according to the value of the Result field after halfadjusting.
• See Table 3-1 in Part II, Chapter 3 for a list of operation codes that allow you to specify
Half adjust.

2.9.11 Resulting Indicators
Use columns 54 through 59 to enter Resulting indicators that test the outcome of a calculation. You can use these resulting indicators to conditiop other calculation or output operations, or to establish field-record relations.

Specifications

2-87

Column
Number

Allowable
Values

Explanation

54-59

01-99

Uses a record-identifying indicator as the resulting indicator.

HI-H9

Uses a halt indicator as the resulting indicator.

KO-K9
KA-KZ

Used to condition calculations, output records and output
fields. They can also be used as resulting indicators.

LI-L9

Uses a control-level indicator as the resulting indicator.

Uses a last-record indicator as the resulting indicator.

OA-OG,OV

Uses an overflow indicator as the resulting indicator.

UI-US

Uses an external indicator as the resulting indicator.

Rules
• A resulting indicator is set on if the condition specified is satisfied. If the specified
condition is not satisfied, the resulting indicator is set off. See Part II, Chapter 3 for
information on how resulting indicators are used with each operation code.
• If you use the same indicator to test the results of more than one operation, the last
operation determines the indicator setting.
• You cannot use resulting indicators when the Result field contains a nonindexed
array.

Additional Information
• Once a resulting indicator is on, it remains on until one of the following occurs:
- The operation is repeated and the result resets the indicator
- The conditions the indicator specifies are not met
- The indicator is set off by another method (such as the SETOF operation)
• Using a control-level indicator as a resulting indicator does not automatically set on
lower-level indicators.
• Using an external indicator as a resulting indicator allows you to set the indicator,
then to test the indicator value after the program exits.

2-88

Specifications

2.9.12 Comments
Use columns 60 through 74 for comments.

Column
Number

Allowable
Values

Explanation

60-74

Any
character

Documents the program line

2.10 Output Specification
This specification describes the records and fields in an output, update, or input (with the
ADD option) file. Columns 7 through 37 describe the record and columns 23 through 70
describe the position and format of each field in the record.

2.10.1 Output Specification Format
The format of the Output specification is:

T!:Ipe (HDTE)
IFetch overflow (F)
I I Space

File
nallle
I

Edit codes
I X
I Y date edit
I Z zero suppress
I

, o No CR ------------y y
1 A J

III Skip
Y N 2 B K
III I
N Y 3 C L
IBlank-after (B)
III I Indicators
N N 4 D M
III I
I
Field II End position
Forlllat (PB)
III I
I
nallle III
III I
I
III
I
I
1+ Constant or edit word +
I IBAB A NxxNxxNxxl
III

011
12
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

ZK-4497-85

2.10.2 Specification Type
Use column 6 to identify the type of specification for every program line.

Column
Number

Allowable
Values

Explanation

Indicates that this program line is an Output specification

Specifications

2-89

2.10.3 File Name
Use columns 7 through 14 to name the output, update, or input (with the ADD option) file.

Column
Number

Allowable
Values

Explanation

7-14

Filename

Identifies the name of the output file

Rules
• Use the same file name you specified in the File Description specification. An output
file can be a file you specified as an output file, as an update file, or as an input file with
A in column 66 of the File Description specification.
• Left-justify this entry.
• If columns 7 through 14 are blank, RPG II assumes that the information in this program line describes a field or record from the file last named.

All the records for a single file need not be described together.

2.10.4 AND and OR Lines
If you need more than three indicators to condition record output, or if you want to output a
record under a number of conditions, use columns 14 through 16 to enter AND or columns
14 through 15 to enter OR.

Column
Number

Allowable
Values

Explanation

14,15

Performs the output operation when the conditions for all
indicators in columns 23 through 31 in either program line
are met

14-16

AND

Performs the output operation when the conditions for all
indicators in columns 23 through 31 in both program lines
are met

Rules
• You must use at least one indicator per program line in an OR or AND relationship.
• If you use AND, columns 17 through 22 must be blank.

• If you use AND or OR, columns 7 through 13 must be blank.
• You can use AND and OR lines only with record description entries, not with field
description entries.
You can specify an unlimited number of AND or OR lines.

(
2-90

Specifications

"'-

In the following example, ifthe following conditions are satisfied, RPG II writes the specified fields and constants:
• Indicator 01 is off
• Or, indicator 01 is on
• And, indicator 23 is off

, 0 No CR Edit codes
(HDTE>
IFetch overflow (F)
I X
II Space
I Y date edit
Y Y 1 A J
I Z zero suppress Y N 2 B K
I II Skip
N Y 3 C L
III I
I
IBlank-after (B)
N N 4 D M
I I I I Indicators
III I I
Field II End position
File
Forlllat (PB)
nallle
III I I
nallle III
I
III I I
I
III
I
I I I 1+ Constant or edit word +
01
I IBAB A NxxNxxNxxl
011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
T~pe

0
0
0
0
0
0
0
0
0
0

***** * *

OR
OR
AND

NOl
01
N23
01

PN
PNAME
WHOUSE
COLOR
WEIGHT
QTY

***---**
3
28 '01'
10
12
17
20
24
ZK-4498-85

Specifications

2-91

2.10.5 Record Type
Use column 15 to specify the point in the RPG II program cycle at which a record is output.
Heading records are normally used to describe the heading information in the output
report, such as column names, page numbers, and the date. Detail records contain the data
from input and calculation operations at detail time. Total records usually contain the
data from the result of calculations on several detail records at total time. Exception
records are written as a result of using the EXCPT operation in a Calculation specification.

Column
Number

Allowable
Values

Explanation

Blank

Indicates that this program line describes a field

Indicates that this program line describes a heading
record

Indicates that this program line describes a detail record

Indicates that this program line describes a total record

Indicates that this program line describes an exception
record

Rules
• You must specify a Record type for every output record .
• Records of the same type are tested for output and written in the order in which you
specify them in the Output specifications.
There is no difference between a heading record and a detail record. The different entries
are for documentation purposes only.
The following example defines heading, detail, total, and exception records.

2-92

Specifications

, o No CR THpe (HDTE>
Edit codes
IFetch overflow (F)
I X
------------IISpace
I Y date edit
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
III I Indicators
IBlank-after (B)
N N 4 D M
File
III I I
Field II End position
naPle
III I I
ForPlat (PB)
naPle III
I
III I I
I
III
I
01
I IBAB A NxxNxxNxxl
III
1+ Constant or edit word +
011
1213
I
4
I
5
1617
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

00UT44A E
0
OR
0
OR
0
0
0
0
0
0
0
0
0
0
0
H
0
0
0
0
0
0
0
0
0
D
0
OR
OR
0
AND
0
0
0
0
0
0
0
0
0
0
T
0
0
0
0
0
0

0
0

*
16
LR

N
PNAME
WHOUSE
COLOR
WEIGHT
QTY

3
10
12
17
20
24
26 'E'
28 '16'
28 '12'
28 'LR'

N
PNAME
WHOUSE
COLOR
WEIGHT
QTY

3
10
12
17
20
24
26 'H'
28 '01'

3
28 '01'
10
12
17
20
24
26 'D'

N12 16
12 01
LR

01
NOl
01 01
N23
01

***---**

PNAME
WHOUSE
COLOR
WEIGHT
QTY
N
PNAME
WHOUSE
COLOR
WEIGHT
QTY

3
10
12
17
28 '01'
20
24
26 'T'

ZK-4499-85

Specifications

2-93

2.10.6 ADD and DEL Options
Use columns 16 through 18 to add and delete records. See Part I, Chapter 5 for information
on adding and deleting records.

Column
Number

Allowable
Values

Explanation

16-18

ADD

Adds a record to an input, output, or update file with an
indexed, direct, or sequential file organization

DEL

Deletes the last record read in the update file with an
indexed or direct file organization

Rules
• You can add records to input, output, and update files that reside on disk. Therefore,
the File Description specification must contain DISK in columns 40 through 46 and A
in column 66.
• You can delete records only from update files that reside on disk.
• ADD or DEL must appear on the same line that defines the Record type for the record
you want to add or delete.
• If a line in an OR relationship follows an ADD or DEL entry, the ADD or DEL entry
applies to both lines.
The following example adds records to the file.
011
12
I
3
I
4
I
5
I
6
17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
I
U
N

o
o
o
o
o
o

PNAME
WHOUSE
COLOR
WEIGHT
IHY

3
10
12
17
20
24
ZK-4500-85

2-94

Specifications

The following example deletes the last record read from the update file.

T!:lpe (HDTE>
Edit codes
o No CR IFetch overflow (F)
IX
------------I ISpace
I Y date edit
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
N Y 3 C L
I
IBlank-after (B)
III I Indicators
N N 4 D M
File
III I I
Field II End position
nallle
III I I
nallle III Forlllat (PB)
III I I
I
I
III
I
01
I IBAB A NxxNxxNxxl
III
1+ Constant or edit word +
011
12
1314
I
5
I
6
I

12345678901234567890123456789012345678901234567890123456789012345678901234567890

**
00UT45B *****
EDEL * •N25
00UT45C EDEL

N25
ZK-4501-85

2.10.7 Fetch Overflow
Use column 16 to specify Fetch overflow. Fetch overflow causes RPG II to check whether
the overflow indicator assigned to the printer output file is on before printing total, detail,
or exception records. See Part I, Chapter 6 for information on overflow.

Column
Number

Allowable
Values

Explanation

Executes the overflow routine if overflow has occurred

Rules
• An entry in this column is valid only for printer-output files with overflow lines.
• Do not specify an overflow indicator on the same line as Fetch overflow.
• If you specify an OR relationship between two lines, you must specify Fetch overflow
for each record type that requires it in both lines of the OR relationship.

Additional Information
• RPG II fetches an overflow routine when overflow occurs and all conditions specified
by the indicators in columns 23 through 31 are met.
• When you specify Fetch overflow, only overflow output associated with the file containing the executed fetch is output.
• The overflow routine does not automatically advance to the next page.

Specifications

2-95

The following example specifies Fetch overflow.

(HDTE)
Edit codes
o No CR Ifetch ollerflolll (f")
------------I X
I ISpace
I Y date edit
Y Y 1 A J
I II Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
III I Indicator's
IBlank-after (B)
N N 4 D M
file
III I I
field II End position
naflle
III I I
naflle III forfllat (PB)
I
III I I
I
III
I
1+ Constant 01' edit word +
01
I IBAB A NxxNxxNxxl
III
011
12
I
3
I
4
I
5
I
6
17
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
T~pe

***** * *

00UT66A Ef 1
o
AND

01
02 03

*
ZK-4502-85

2.10.8 Space Before and Space After
Use columns 17 and 18 to define the physical format ofa printer output file. Use column 17
to specify the number of lines to advance before printing the next line of output. Use column 18 to specify the number of lines to advance after printing a line of output.

Column
Number

Allowable
Values

Explanation

Blank

Does not advance before printing a line of output.

0-3

Specifies the number of lines the printer will advance
before printing a line of output. A value of zero allows
overprinting.

Blank

Does not advance after printing a line of output.

0-3

Specifies the number oflines the printer will advance after
printing a line of output. A value of zero allows overprinting.

Rules
• If you leave columns 17 through 20 blank for a record specification line, RPG II automatically spaces one line after printing the output line.
• If there are no entries in columns 17 through 20 of an OR line, RPG II uses the entries
in a preceding line.

• You cannot define the spacing and skipping for an AND line.

2-96

Specifications

Additional Information
• Because you can space up to only three lines before and after a line of output, you
cannot specify more than five blank lines between output lines using entries in columns 17 and 18 .
• Spacing to or past the overflow line causes RPG II to set on the overflow indicator.

2.10.9 Skip Before and Skip After
Like the Space before and Space after columns, columns 19 through 22 help define the
physical format of a printer output file. Unlike the entries in columns 17 and 18, the
entries in columns 19 and 20 can be used to specify more than five lines between lines and
to specify a move to the next page.
Use column 19 to specify the line number the printer must move to before printing a line of
output. Use column 20 to specify the line number the printer must move to after printing a
line of output.

Column
Number

Allowable
Values

Explanation

19,20

Blank

Specifies no skipping before printing a line of output

01-99

Causes the printer to move to the line number you specify
before printing a line of output

AO-A9

Causes the printer to move to the line number you specify
100 (AO) to 109 (A9) before printing a line of output

BO-B2

Causes the printer to move to the line number you specify
110 (BO) to 112 (B2) before printing a line of output

Blank

Specifies no skipping after printing a line of output

01-99

Causes the printer to move to the line number you specify
after printing a line of output

AO-A9

Causes the printer to move to the line number you specify
100 (AO) to 109 (A9) after printing a line of output

BO-B2

Causes the printer to move to the line number you specify
110 (BO) to 112 (B2) after printing a line of output

21,22

Specifications

2-97

Rules
• Follow the same rules in Section 2.8.10 for AND and OR lines.
• You can specify entries in all Space and Skip columns for a single program line. When
you do, RPG II executes the entries in the following order: Skip before, Space before,
print the output line, Skip after, and then Space after.
• Specifying a Skip entry past the overflow line causes RPG II to set on the overflow
indicator. See Part I, Chapter 6 for more information.
• If you specify a Skip entry to the same line number that the printer is currently on, no
skipping takes place.
• If you specify a Skip entry to a line number less than the current line number, the
printer advances to that line number on the next page.
• The Skip entry cannot exceed the entry for Forms Length (columns 18 and 19 of the
Line Counter specification). If there is no Line Counter specification, the Skip entry
cannot exceed the default, line 66.

2.10.10 Example
The following example Causes RPG II to
• Skip to line 27 and space two lines before printing the output line.
• Skip to line 30 and space three lines after printing the output line.

, o No CR (HDTE>
Edit codes
------------IFetch overflow (F)
I X
Y Y 1 A J
I ISpace
I Y date edit
II I Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
IBlank-after (B)
N N 4 D M
III I Indicators
File
III I I
Field II End posi tion
Format (PB)
name
III I I
name III
I
III I I
III
I
I
1+ Constant or edit word +
01
I IBAB A NxxNxxNxxl
III
o I 1 I 2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
T~pe

0
0
0
0
0
0
0

***** * *

D 232730N1P 18

***---**

3
10
12
17
20
24

PNAME
WHOUSE
COLOR
WEIGHT

QTY

ZK-4503-85

2-98

Specifications

2.10.11 Indicators
Use columns 24 and 25, 27 and 28, and 30 and 31 to enter previously assigned indicators to
condition a line of output.

Column
Number

Allowable
Values

Explanation

24-25
27-28
30-31

Blank

Outputs the record or field.

Indicator

Outputs the record or field when the indicator you specify
is on.

Outputs the record or field when the indicator is off. N in
column 23 conditions the indicator in columns 24 and 25.
N in column 26 conditions the indicator in columns 27 and
28. N in column 29 conditions the indicator in columns 30
and 31.

23,26,29

Rules
• When you want an indicator to condition an entire record, enter the indicator on the
line that specifies the type of record. When you want an indicator to condition a field,
enter the indicator on the same line as the field name (columns 32 through 37).
• If you specify more than one indicator on a line, the indicators form an AND
relationship.
• You can use overflow indicators in AND or OR lines; however, you can associate only
one overflow indicator with a group of output indicators. If a line is to be considered an
overflow line, the overflow indicator must appear on the main specification line or on
an OR line.
• If you use an overflow indicator, it must be the same one assigned to the file on the File
Description specification.
• You cannot use overflow indicators to condition exception output lines, but you can
use them to condition fields in an exception record.

Specifications

2-99

Additional Information
• You can use one of the following indicators in columns 24-25, 27-28, and 30-31:
- Record-identifying (01-99)
- Control-level (LI-L9)
- Last-record (LR)
- Matching-record (MR)
- Halt CHI-H9)
- External (UI-U8)
- Overflow (OA-OG, and OV)
- K (KA-KZ, and KO-K9)
- First-page (IP)
• Keep in mind that RPG II outputs those detail and heading lines conditioned by the
IP (first-page) indicator, no indicator, or all negative indicators (N in columns 23, 26,
or 29) before reading the first record from a file. Therefore, use the IP (first-page) indicator to condition only heading and detail output lines that do not depend on data
from an input record. For a line with no indicators or all negative indicators that
depends on data from an input record, use a negative first-page indicator (NIP in columns 23 through 31) to prevent the line from being outputted before reading the first
record.
• Because the IP (first-page) indicator is set off after the first detail-time output, it can
be used only to condition heading and detail lines.
• If you use a control-level indicator with a total record and no overflow indicator,
RPG II writes the record when a control break occurs and after RPG II processes the
last record of a control group.
• If you use a control-level indicator with a detail record and no overflow indicator,
RPG II writes the record when a control break occurs and after it processes the first
record of a new control group.

• If you use a control-level indicator with an overflow indicator, RPG II writes the
record when a control break occurs and passes the overflow line.

2-100

Specifications

The following example causes RPG II to print the specified fields in the detail record if the
IP (first-page) indicator is off.

(HDTE>
'Fetch overfloll (F)
"Space
, " Skip

T~pe

Edit codes

, X

, Y date edit

, o No CR -------------

Y Y 1
Y N 2
N Y 3
N N -4

A J
B K
C L
D H

,,
,
"'
Indicators
'Blank-after (B)
,, ,,
"'
File
Field "End position
(PB)
naPle
naPle
, "'
, ,
,
, "' ForPlat
"'
"' 1
"'' ,+4 Constant
or edit word +
"BAB
A NxxNxxNxx'
0'
0'1
2'
3"'
15'
6'
7'
1234567890123456789012345678901234567890123456789012345678901234567890123456789
**
***** * *
00UT50A D
N1P
o
o
o
o
o
o
o

, Z zero suppress

PNAHE
WHOUSE
COLOR
WEIGHT

10
12
17
20

QTY

2-4

PAGE

30
ZK-4504-85

2.10.12 Field Name
Use columns 32 through 37 to specify the Field name that identifies the item to be written
to the output file.

Column
Number

Allowable
Values

Explanation

32-37

Blank

Indicates the presence of a constant in columns 45 through
70.

Name

Specifies the name of the item to print. The item can be a
field name, table or array name, array element, or one of
the following special words (PAGE, PAGEI-7, UDAY,
UMONTH, UYEAR, UDATE, *IN, *INxx, and *PLACE).
See Part I, Chapter 6 for information on special words.

Rules
• All field names must have been previously defined in an Input, a Calculation, or an
Extension specification.
• Left-justify this entry.
• You cannot enter a field name if you enter a constant in columns 45 through 70.

Specifications

2-101

• If you enter a field name in columns 32 through 37, columns 7 through 22 must be
blank .
• If you specify a nonindexed array name, the entire array is output.
The following example specifies fields in the detail record.

, o No CR (HDTE>
Edit codes
------------IFetch overflow (F)
I X
I ISpace
Y Y 1 A J
I Y date edit
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
III I Indicators
IBlank-after (B)
N N 4 D M
File
III I I
Field I lEnd position
nallle
III I I
nallle III Forlllat (PB)
I
III I I
I
III
I
1+ Constant or edit word +
01
IIBAB A NxxNxxNxxl
III
0'1
I
2
I
3
,
4
,
5
,
6
I
7
,
12345678901234567890123456789012345678901234567890123456789012345678901234567890
T~pe

***** * *

00UT50A D

o
o
o
o
o
o
o

NiP
N

PNAME
"IHOUSE
COLOR
WEIGHT

10
12
17
20
24
30

'HY

PAGE

ZK·4505·85

2.10.13 EXCPT Name
When the record type is an exception record (indicated by an E in column 15), a name can
be placed in columns 32 through 37 of the record line. The EXCPT operation can specify
the name assigned to a group of records to be written. The name is called an EXCPT name.

Column
Number

Allowable
Values

Explanation

32-37

Blank

Identifies exception output records to be written when an
EXCPT opcode with a blank Factor 2 is executed.

Name

Identifies exception output records to be written when an
EXCPT opcode with the same name in Factor 2 is executed.

2-102

Specifications

Rules
• An EXCPT name must follow the rules for field names.
• An EXCPT name cannot be the same as a file name, field name, data structure name,
array name, table name, label, or subroutine name.
• A group of any number of output records can use the same EXCPT name, and the
records do not have to be consecutive records.

2.10.14 Edit Codes
Use column 38 to specify an Edit code. Edit codes allow you to perform a variety of editing
functions on the data in a numeric output field.

Column
Number

Allowable
Values

Explanation

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

Prints a number with commas before every third digit to
the left of the decimal point, suppresses a zero balance,
suppresses signs, and suppresses leading zeros.

Prints a number without commas, prints a zero balance,
and suppresses signs and leading zeros.

Prints a number without commas, suppresses a zero balance, suppresses signs, and suppresses leading zeros.

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

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

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

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

Specifications

2-103

Column
Number

Allowable
Values

Explanation

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

Prints a number with commas before every third digit to
the left of the decimal point, suppresses a zero balance,
prints a negative sign, and suppresses leading zeros.

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

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

Performs no editing.

Edits a date field using the format month/day/year or the
format day/month/year, if you specify Inverted print. If the
first digit of a date field is zero, it is suppressed.

Suppresses signs and leading zeros.

Rules
• If you use an Edit code in column 38, columns 45 though 70 must be blank unless you
specify an Edit code modifier.
• If you use an Edit code to edit an array, RPG II leaves two spaces to the left between
the elements of the array.
• You cannot use Edit codes on numeric data in packed or binary format.

Additional Information
• To prevent overlapping of the output fields, leave enough space for the characters that
the Edit code will insert into the output field.
• Unedited numeric output fields with negative values are output with the
overpunched representation of the sign. For example, -1 will be output as J, -2 as K,
and so on. (See Part II, Chapter 1 for information on overpunched format.) Therefore,
use an Edit code or Edit word to prevent the output of an overpunched representation
ofa sign.
Table 2-6 shows the results of several Edit code examples.

2-104

Specifications

Table 2-6: Edit Codes and Examples
Edit +12345.67
Code

+ 1234567

none
1
2
3
4

1234567
1,234,567
1,234,567
1234567
1234567
1,234,567
1,234,567
1234567
1234567
1,234,567
1,234,567
1234567
1234567

1234567
12,345.67
12,345.67
12345.67
12345.67
12,345.67
12,345.67
12345.67
12345.67
12,345.67
12,345.67
12345.67
12345.67

A
B
C
D

J
K
L
M

-1234.567

-1234567

123456P
123456P
1,234.567
1,234,567
1,234.567
1,234,567
1234567
1234.567
1234.567
1234567
1,234.567CR 1,234,567CR
1,234.567CR 1,234,567CR
1234.567CR 1234567CR
1234.567CR 1234567CR
1,234.567 1,234,5671,234.567 1,234,5671234.567 12345671234.567 1234567-

Print Zero
Balance
yes
yes
no
yes
no
yes
no
yes
no
yes
no
yes
no

2.10.15 Blank After
Use column 39 to specify Blank after that causes RPG II to reset the contents of the output
field after writing it. RPG II resets alphanumeric data with blanks and numeric data with
zeros. Specifying Blank after is especially useful when accumulating totals for each control group.
Column
Allowable
Explanation
Number
Values
B

Causes RPG II to reset the field after writing it

Rules

• This column must be blank for look-ahead fields, fields defined by an EXTRN operation, constants, and the following special words: UDATE, UDAY, UMONTH,
UYEAR, and *PLACE.
• Ifindicators condition the field you want to reset, the same indicators condition Blank
after.
• If you specify Blank after for a field that you want to write more than once, enter Bin
this column on the last line specifying output for that field. Otherwise, the field will be
reset before being output again.

Specifications

2-105

The following example specifies Blank after for PAGE3.

Edit codes
o No CR Tl:!pe (HDTE>
Iretch ovel'f I 0111 (F)
I X
------------I ISpace
I Y date edit
Y Y 1 A J
I Z zero suppress Y N 2 B K
II I Skip
III I
N Y 3 C L
I
IBlank-after (B)
III I Indicatol's
N N 4 D H
III I I
Field IIEnd position
rorlllat (PB)
III I I
nallle III
III I I
III
I
I
I IBAB A NxxNxxNxxl
III
1+ Constant or edit word +
I

rile
nallle
I
01

011

1234567890123456789012345678901234567890123456789012345678901234567890123456789

***** * *

N1P

00UT50A D

PAGE3 ZB 50
ZK-4506-85

2.10.16 End Position
Use columns 40 through 43 to indicate the location of an output field or constant. Enter the
number ofthe position for the rightmost character. For example, if a field contains 20 characters and you specify 40 as the End position, the output might appear as follows:
0 2 3
4
12345678901234567890123456789012345678901234567890

South LvndeboroughNH

The numbers above this example are for reference only; they do not appear in the output.

Column
Number

Allowable
Values

Explanation

40-43

1-9999

Indicates the position of the rightmost character in an output field or constant

Rules
• Right-justify this entry.
• Leading zeros can be omitted.
• If fields overlap, the last field you specify on the Output specification is the only field
that is completely written.

2-106

Specifications

• When specifying the End position for an array, use the rightmost position of the last
element in the array.
• The End position must be less than or equal to the Record length (columns 24 through
27 of the File Description specification) ofthe file to which the record belongs.
Be sure to allow enough room for the number of characters in each output field and for the
editing characters you specified using an Edit code or Edit word.

THpe (HDTEl
Edit codes
o No CR IFetch overflow (F)
I X
------------IISpace
I Y date edit
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
III I Indicatol's
IBlank-after (B)
N N -4 D M
File
III I I
Field II End position
nallle
III I I
nallle III Forlllat (PB)
I
III I I
I
III
I
01
I IBAB A NxxNxxNxxl
III
I+ Constant 01' edit word +
011
12
I
3
I
4
I
5
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

o
o
o
o

***** * *

***---**

22 'EMPLOYEE NUMBER'
40 'EMPLOYEE NAME'
57 'REG EARNINGS'
75 'OVER EARNINGS'
ZK·4507·85

In the above example, the rightmost character in the
• First field is in character position 22
• Second field is in character position 40
• Third field is in character position 57
• Fourth field is in character position 75
The output appears as follows:

o
1
2
3
4
5
6
7
123456788012345678801234567880123456788012345678801234567880123456788012345678E
EMPLOYEE NUMBER

EMPLOYEE NAME

REG EARNINGS

OI)ER EARN I NGS

The numbers above this example are for reference only; they do not appear in the output.

Specifications

2-107

2.10.17 Format
If an output field contains numeric data, use column 44 to specify its data format. You can
specify overpunched decimal, packed decimal, or binary. Packed decimal and binary format conserve disk space.
Column
Number

Allowable
Values

Explanation

Blank

Indicates that the field contains either alphanumeric
characters or numeric data and is in overpunched decimal
format

Indicates that numeric data is in packed format

Indicates that numeric data is in binary format

Leave this entry blank for the output field if you specify an Edit code, Edit word, or the
special word *PLACE.
The following example specifies packed decimal format for the field QTYP and binary format for the field QTYB.

, o No CR
Edit codes
------------IFetch overflow (F)
IX
I ISpace
Y Y 1 A J
I Y date edit
II I Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
III I Indicator's
IBlank-after (B)
N N 4- D H
III I I
Field IIEnd position
III I I
nallle III Forlllat (PB)
III I I
III
I
I
1+ Constant or edit word +
IIBAB A NxxNxxNxxl
III
1
I
2
I
3
I
4I
5
I
6
I
T~pe(HDTE>

File
nallle
I
01

12345678901234567890123456789012345678901234567890123456789012345678901234567890

o**
o

***** * *

*tlTYP ***---**
32P
tlTYB

38B
ZK-4508-85

2.10.18 Constant or Edit Word
Use columns mentioned below for Edit code modifiers, Constants, and Edit words. This
section describes the options.

2-108

Specifications

2.10.18.1 Edit Code Modifiers
Use columns 45 through 47 to specify Edit code modifiers. Edit code modifiers can replace
suppressed zeros to the left ofthe decimal point with asterisks (asterisk fill) or put a dollar
sign before the leftmost character (floating currency symbol). To specify these modifiers,
enter the appropriate value described below.

Column
Number

Allowable
Values

Explanation

45-47

'*'

Replaces suppressed zeros to the left of the decimal point
wi th asterisks (*).

'Symbol'

Places the currency symbol before the first significant
digit in a numeric field. The currency symbol is the same
symbol you define in column 18 of the Control specification.

Rules
• Enclose Edit code modifiers in apostrophes.
• The floating currency symbol will not be printed for a zero balance when you use an
Edit code that suppresses a zero balance.
• You cannot use the floating currency symbol or asterisk fill with simple (X, Y, and Z)
Edit codes.
• You can specify a currency symbol before an asterisk fill by making the following
entries:
- Column 38 (Edit code) - Specify one of the combined Edit codes.
- Place a currency symbol constant one space before the beginning of the edited field
on the Output specification.
- Place an asterisk enclosed in apostrophes C*') in columns 45 through 47 on the same
line as the Edit code.

Specifications

2-109

T!:lpe (HDTE>
Edit codes
, X
'Fetch overflow (F)
, Y date edit
"Space
, Z zero suppress
"' Skip
Indicators
'Blank-after (B)
Field "End position
Forlllat (PB)
nallle

o No CR -------------

Y Y 1
Y N 2
N Y 3
N N 4

A J
B K

,
"' ,, ,
D M
"'
Fi Ie
nallle
, "'"'"' ,, ,, , "' ,
,+ Constant or edit wOl'd +
"'
"BAB A NxxNxxNxx'
0'
"'
12345678901234567890123456789012345678901234567890123456789012345678901234567890
011

o
o

***** * *

C L

***---**

OTEARN1

56 '$'
61 '*'
ZK-4509-85

In the above example, if the field OTEARN, which is four digits long with two decimal
positions, contains a zero balance, RPG II prints a dollar sign before the asterisk filL The
output might appear as follows:

o
2 3 4
5
8
7
12345878801234587880123458788012345878801234587880123458788012345878801234587880
$**.**

RPG II uses a dollar sign ($) as the currency symbol unless you specify another symbol in
column 18 (Currency symbol) ofthe Control specification_
2.10.18.2 Constants
Use columns 45 through 70 to specify Constants_ Place a double quotation mark (") in column 45 to specify a long character literal as a constant_ Constants are used to describe
constant data in an output file.

Column
Number

Allowable
Values

Explanation

Double
quotation
(")

Causes RPG II to print the characters within single quotation marks on the line(s) that follow. All the rules for long
character literals on Calculation specifications apply
when used on Output specifications. See Factors 1 and 2,
this chapter, for information on long character literals.

45-70

Any
character

Causes RPG II to print the characters in columns 45
through 70.

2-110

Specifications

Rules
• Constants can contain up to 24 characters.
• You must enclose constants within single quotation marks. Use the keyboard apostrophe mark as the single quotation mark (for example, 'Subroutine'). The single quotation marks are not printed.
• When using constants, leave columns 32 through 39 and column 44 blank.
• To include an apostrophe in a constant, you must use two consecutive apostrophes to
represent one apostrophe (for example, 'Subroutine' 's calculations').

2.10.18.3 Edit Words
Use columns 45 through 70 to specify Edit words. Edit words can be used to edit a numeric
field. Edit words consist ofthree parts: the body, sign status, and expansion. The body is the
portion of the Edit word that provides space for the digits from the field to be edited. The
body begins at the leftmost character position of the Edit word and ends at the rightmost
character position that is to contain a digit from the field to be edited.
The sign status is the portion of the Edit word that is used to specify whether the field is
positive or negative and to specify a constant, if needed. The sign status begins at the first
character position to the right of the body and ends with CR or a negative sign (-). If you
specify one ofthese symbols and the field is positive, blank spaces will be substituted in the
edited field. If you use CR or a negative sign and the field is negative, that symbol will be
substituted in the edited field.
If an Edit word contains no CR or a negative sign to the right of the rightmost character
that is to contain a digit, the Edit word contains no sign status portion.
The expansion consists of characters that will be printed regardless ofthe field's sign status. The expansion begins immediately after the sign status (or body, if no sign status is
used) and continues to the end of the Edit word.
The following table describes those characters you can use in the body of the Edit word.

Specifications

2-111

Column
Number

Allowable
Values

Explanation

45-70

Blank

Indicates that the position in the edited field is to contain
the digit from the same position in the numeric field.

Indicates that the field is to be zero suppressed. Place the
zero in the rightmost position where zero suppression is to
stop. Each leading zero that appears to the left of and
including the stop position of the numeric field is replaced
with a blank space in the edited field. The first zero RPG II
encounters is the zero suppression character. Any zero
appearing after the first zero is treated like any other
character. Zero suppression begins at the leftmost position
in the data and continues up through the stop position
unless a nonzero digit is encountered to the left of the stop
position. IfRPG II encounters a nonzero digit to the left of
the stop position, zero suppression stops at the position
where the nonzero digit is encountered; that-digit and all
following digits to the right of the nonzero digit are
printed.

Indicates that the field is to be edited using asterisk protection. Place the asterisk in the rightmost position where
asterisk protection is to stop. Each leading zero that
appears in the data to the left of and including the stop
position is replaced with an asterisk. The first asterisk
RPG II encounters is the asterisk protection character.
Any asterisk appearing after the first asterisk is treated
like any other character.

Indicates that the position in the edited field is to be a
blank space.

2-112

Specifications

Column
Number

Allowable
Values

Explanation

Symbol

Prints the currency symbol. If the currency symbol
appears in the body of the Edit word immediately to the
left of the zero suppression, it is printed immediately to
the left of the first significant digit in the edited field. This
type of currency symbol is called a floating currency symbol. A floating currency symbol cannot be used with asterisk protection.
The currency symbol in the leftmost position of the Edit
word indicates that the dollar sign is to be printed in that
exact position in the edited field. This type of currency
symbol is called a fixed currency symbol. The following
example shows both types of currency symbols.

o No CR (HDTE>
Edit codes
Ifetch overflow (f)
------------I X
I Y date edit
Y Y 1 A J
IISpace
I Z zero suppress Y N 2 B K
III Skip
III I
I
N Y 3 C l
IBlank-after (B)
III I Indicators
N N 4 D H
III I I
field II End position
III I I
nallle III forlllat (PB)
III I I
I
III
I
1+ Constant or edit word +
I IBAB A NxxNxxNxxl
III
1
I
2
1
3
I·
4
·1
5
I
6
1
T~pe

file
nallle
I
01

12345678901234567890123456789012345678901234567890123456789012345678901234567890

o
o

***** * *

*
flOAT
fIXED

***---**

45 '$0
45 '$
ZK-4510-85

In the example above, if FLOAT and FIXED contain the characters 1234, the output

appears as follows:

o
2
3
4
5
6
7
1234567890123456789012345678901234567890123456789012345678901234567890123456789
$

$1234
1234

Specifications

2-113

Column
Number

Allowable
Values

Explanation

Decimal point
or comma

Indicates the exact position in the edited field where it is to
be printed. If a decimal point or comma appears to the left
of the most significant digit, RPG II will replace it with a
blank space or, if asterisk protection is specified, with an
asterisk.
In the following example, RPG II prints a comma before
the fifth digit from the right and a decimal point before the
rightmost two digits.

Edit codes
o No CR THpe (HDTE>
------------IFetch overflow (f)
I X
Y Y 1 A J
I ISpace
I Y date edit
I Z zero suppress Y N 2 B K
III Skip
III I
N Y 3 C L
I
IBlank-after (B)
III I Indicators
N N 4 D H
File
III I I
Field II End position
Format (PB)
name
name III
III I I
III I I
I
III
I
I
1+ Constant or edit word +
01
III
I IBAB A NxxNxxNxxl
011
12
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

***** * *

FLD

***---**

45 '$
ZK-4511-85

In the above example, ifFLD contains the data 123456, the output appears as follows:

o
2
3
4
5
6
7
12345678801234567880123456788012345678801234567880123456788012345678801234567880
$1,234.56

In the above example, if FLD contains the data 56, the output appears as follows:
0 2 3
a
5
6
7
12345678801234567880123456788012345678801234567880123456788012345678801234567880
$

2-114

Specifications

Column
Number

Allowable
Values

Explanation

Any other
character

Prints the character(s) in the edited field provided that the
position is to the right of the most significant digit in the
edited field. Any character to the left of the most significant digit in the edited field is replaced with a blank space
or an asterisk if asterisk protection is specified.

File
nallle
I
01

, o No CR (HDTE>
Edit codes
IFetch overflow (n
IX
------------I ISpace
I Y date edit
Y Y 1 A J
III Skip
I Z zero suppress Y N 2 B K
III I
I
N Y 3 C L
IBlank-after (B)
III I Indicators
N N 4 D H
III I I
Field IIEnd position
III I I
nallle III Forlllat (PB)
III I I
I
III
I
1+ Constant or edit word +
IIBAB A NxxNxxNxxl
III

***** * *

T~pe

o I 1
I
2
131
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

FLD

***---**

45 ' $,

•

&BALANCE '
ZK-4512-B5

In the above example, if FLD contains the data 123456, the output appears as follows:

o
1
2 3 4
5
6
7
1234567880123456788012345678801234567880123456788012345678801234567880123456788
$1.234.56 BALANCE

The following table describes those characters you can use in the status portion of the Edit
word.

Column
Number

Allowable
Values

Explanation

45-70

CRor -

Indicates that the specified symbol (CR or a negative sign
( - )) is to be printed in the edited field if the data is negative. If the edited field is positive, the specified symbol is
replaced by blanks.

Any
character

Prints the specified character(s) in the edited field if the
data is negative; otherwise the character is replaced by a
blank. If an ampersand is specified, it will be replaced by a
blank space.

Specifications

2-115

o No CR Edit codes
(HDTE>
Ifetch overfloN (f)
IX
------------Y Y 1 A J
I ISpace
I Y date edit
I Z zero suppress Y N 2 B K
III Skip
N Y 3 C L
III I
I
IBlank-after (B)
III I Indicators
N N 4 D H
field I lEnd position
III I I
III I I
nallle III forlllat (PB)
III I I
III
I
I
1+ Constant or edit Nord +
IIBAB A NxxNxxNxxl
III

T~pe

file
nallle
I
01

',,_

o I 1
I
2
I
3
I
4
I
5
I
6
171
12345678901234567890123456789012345678901234567890123456789012345678901234567890

o**

***** * *

***---**

fLD

45 '$ ,

&CR&BALANCE'
ZK-4513-85

In the above example, ifFLD contains the data -123456, the output appears as follows:

12345678901234567890123456789012345678901234567890123456789012345678901234567890
$1.234.56 CR BALANCE

Rules
• Leave column 38 (Edit code) blank.
• You must complete columns 32 through 37 (Field name) and columns 40 through 43
(End position).
• Edit words can be used only with overpunched numeric data. (Column 44 (Data format) must be blank.)
• Edit words can consist of up to 24 characters.
• Enclose Edit words in apostrophes.
• The number of replaceable characters in an Edit word must be greater than or equal
to the number of digits in the numeric field.
• If you want all leading zeros to be printed, increase the Edit word by one position to
the left of the leftmost digit and place a zero in that position.
• When the floating currency symbol is used, the sum of the number of blanks and the
zero suppression in the Edit word must be equal to or greater than the number of digits in the edited field. A floating currency symbol is not counted as a digit position.
• Any zeros or asterisks following the leftmost zero suppression code or asterisk protection are treated as constants and are not replaced with digits.
/

2-116

(

Specifications

Chapter 3

Operation Codes
Operation codes perform calculations on the operands you specify in Calculation specifications. The following sections group operation codes by function and discuss each operation
cod~ in detail. See Table 3-1 at the end of this chapter for a summary of the options you can
use with each operation code.

3.1 Arithmetic Operation Codes
Arithmetic operation codes perform a variety of functions ranging from adding two operands to taking the square root of an operand.
When using arithmetic operation codes, consider the following restrictions and default
characteristics:
• You can use arithmetic operation codes only with numeric fields and numeric literals.
• RPG II aligns the operands according to their decimal points before performing any
arithmetic operation. Also, RPG II aligns the result on the decimal point in the Result
field which could cause truncation.
• The contents of Factor 1 and Factor 2 do not change during an arithmetic operation
unless the same field is used as the Result field.
• Any existing data in the Result field is replaced with the result of the current
operation.
• Make sure the Field length ofthe Result field is large enough to hold the result of the
operation. Otherwise, the result of the operation is truncated before being placed in
the Result field.
• You can specify Half adjust (column 53 of the Calculation specification) for any arithmetic operation except for an MVR operation and the DIV operation immediately preceding it.
• You can specify the same field for Factor 1 and Factor 2 and/or the Result field, if
desired.

3-1

• You can leave Factor 1 blank. If you do, the statement is treated as if the Result field
were specified in Factor 1.
• You can specify an entire array as an operand of the ADD, SUB, Z-ADD, Z-SUB,
MULT, DIV, and SQRT operation codes. See Part I, Chapter 8 for information on using
arrays in calculations.
• No field in an arithmetic operation can be longer than 15 digits.
• RPG II performs all arithmetic operations algebraically.
• The result of all arithmetic operations is signed. The sign ofthe result of an arithmetic operation depends on the operation.
Addition:
- If Factor 1 and Factor 2 have like signs, the Result field has the same sign.
- If Factor 1 and Factor 2 have unlike signs, the Result field uses the sign of the factor
with the largest absolute value.
Subtraction:
- Change the sign of Factor 2 (positive to negative or negative to positive) and use the
same rules as for addition.
Multiplication:
- If Factor 1 and Factor 2 have like signs, the sign of the Result field is positive.
- If Factor 1 and Factor 2 have unlike signs, the sign ofthe Result field is negative.
Division:
- If Factor 1 and Factor 2 have like signs, the sign ofthe Result field is positive.
- If Factor 1 and Factor 2 have unlike signs, the sign ofthe Result field is negative.
- The sign of the remainder is the same as the sign of Factor 1.

3.1.1 ADD
ADD adds the contents of Factor 1 to Factor 2 and puts the sum in the Result field. If
you leave Factor 1 blank, the statement is treated as if the Result field were specified in
Factor 1.

3.1.2 Z-ADD
Z-ADD assigns the value of Factor 2 to the Result field.

3-2

Operation Codes

3.1.3 SUB
SUB subtracts the contents of Factor 2 from the contents of Factor 1 and puts the difference in the Result field. If you leave Factor 1 blank, the statement is treated as if the Result
field were specified in Factor 1.

3.1.4 Z-SUB
Z-SUB multiplies the contents of Factor 2 by -1 and puts the result in the Result field.

3.1.5 MULT
MULT multiplies Factor 1 by Factor 2 and puts the product in the Result field. If you leave
Factor 1 blank, the statement is treated as if the Result field were specified in Factor 1.
The Field length of the Result field for a MULT operation should equal the sum ofthe Field
lengths of Factor 1 and Factor 2. This procedure makes sure the Result field can contain
the maximum value.

3.1.6 DlV
DIV divides Factor 1 by Factor 2 and puts the quotient in the Result field. If you leave
Factor 1 blank, the statement is treated as ifthe Result field were specified in Factor 1.
Factor 2 cannot be zero. Ifit is, a run-time error occurs. The remainder is lost unless you
use the MVR operation immediately following the DIV operation.

3.1.7 MVR
MVR moves the remainder from the division operation on the preceding line to the Result
field. The Decimal position of the remainder is the greater of either of the following:
1. The number of Decimal positions specified for Factor 1

The sum of the number of Decimal positions specified for Factor 2 and the Result
field ofthe preceding DIV operation

The sign ofthe remainder is the same as the sign of Factor 1 in the DIV operation.
Because DIV and MVR operation codes work together, use the same indicators to condition
both operations.
You cannot specify Half adjust (column 53 of the Calculation specification) for a DIVoperation immediately followed by an MVR operation.
You cannot use the MVR operation if in the immediately preceding DIV operation you
specified an entire array (nonindexed) in the Result field.

Operation Codes

3-3

3.1.8 SQRT
SQRT calculates the square root of Factor 2, half adjusts the value, and puts the result into
the Result field. The result of a SQRT operation is always half adjusted. Factor 2 cannot be
a negative number. If the field contains a negative number, a run-time error occurs. If you
use a negative numeric literal, a compile-time error occurs.

3.1.9 XFOOT
XFOOT puts the sum of all the array elements into the Result field. Factor 2 contains the
name of the array. If the Result field contains an array element ofthe array you specify in
Factor 2, the original value of the element is used during the operation.
You can half adjust the contents of the Result field.

3.1.10 Example
The following example demonstrates the use of arithmetic operation codes:

Field length
I Deci~al positions
I IHaif adjust (H)
I
I II
Operation
I Indicato,'s
I II Resul ting
I
I I
Resultl II indicators
Factor
I
I I
Factor
field I 11+ - 0
I
2
I I
1
I
I II> < = +- Co~~ents --+
I
I
CI NxxNxxNxxl
011
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contro I I eve I

* *DWNPAY
SUB
MULT .18
ADD AMTFIN
DIV 13
MVR
Z-ADD5.00
ADD AMTDUE

30 C
31 C

Z-SUB10.00
Z-ADD6.99

EAR PAY 42H
LATCHG 32H

46 C

SQRT FINCHG

TAX

** *

12 C
13 C
HC
15 C
16 C
17 C
18 C

*PURCH
AMTFIN
FINCHG
AMTDUE

AMTFIN
FINCHG
AMTDUE
MTHPAY
REMAIN
TOTDUE
TOTDUE

*--*** * * *
62H
62H
62H
52
42
62

42H
ZK-4514-85

For the example above, the following table lists the data in each operand before and after
the operation.
3-4

Operation Codes

Program
line

Factor 1

122.99

1200.00

216.00

1416.00

Operation

*
+

Factor 2

Result
Field

100.00

22.99

.18

216.00

1200.00

1416.00

108.92
0.04

MVR

ADD

1416.00

1421.00

Z-SUB

10.00

-10.00

Z-ADD

6.99

SQRT

216.00

14.70

3.2 Move Operation Codes
Move operation codes transfer data from a field in Factor 2 to the Result field. Although the
contents of Factor 2 remain unchanged, you can move all or part of the field in Factor 2,
and either retain or change the format ofthe data as you move it.
In move operations, RPG II ignores the Decimal positions of numeric fields. You cannot use
resulting indicators with any move operation.

3.2.1 MOVE
MOVE transfers the contents of Factor 2 to the Result field. The transfer begins with the
rightmost character of Factor 2 to the rightmost character of the Result field. Ifthe Result
field is not large enough to accommodate Factor 2, RPG II moves only enough characters
(beginning with the rightmost character) to fill the Result field. If the Field length of the
Result field is longer than Factor 2, the leftmost characters of the Result field are not
changed. If RPG II transfers numeric data, the sign of the Result field is the same as the
sign of Factor 2.
When you move an alphanumeric field to a numeric field, RPG II converts the digit portion
of each character to its corresponding numeric character and then moves the numeric
character to the Result field. RPG II converts the zone portion of the rightmost character to
its corresponding sign and then moves the sign to the rightmost character position ofthe
numeric Result field, where it becomes the sign ofthat field.

Operation Codes

3-5

3.2.2 MOVEA
MOVEA transfers data from Factor 2 to the Result field. Either Factor 2 or the Result field
must contain an array or array element. If you specify an array element, it specifies the
beginning position of the transfer. Both Factor 2 and the Result field must be character
fields or arrays.
You can move several contiguous array elements to a single field or move a single field to
several contiguous array elements.
Movement of data from Factor 2 to the Result field begins with one of the following:
• The leftmost character of the first element in the array, if you specify an entire array
(nonindexed)
• The leftmost character of the element you specify, if you specify an array element
(indexed)
• The leftmost character of the field, if you specify a field
The length of Factor 2 and the Result field is determined by the length of one ofthe following:
• Entire array, if you specify an entire array (nonindexed)
• Array from the specified array element to the end ofthe array, if you specify an array
element (indexed)
• Field, if you specify a field
If the Field length of Factor 2 is greater than the Field length of the Result field, RPG II
does not move the excess rightmost characters. If the Field length of the Result field is
greater than the Field length of Factor 2, the rightmost characters in the Result field
remain unchanged.
Array element boundaries are ignored in a MOVEA operation. Therefore, movement of
data into the Result field can end in the middle of an array element.

3.2.3 MOVEL
MOVEL transfers the contents of Factor 2 to the Result field. The transfer begins with the
leftmost character of Factor 2 to the leftmost character of the Result field.
When the Field length of Factor 2 is equal to the Field length ofthe Result field, the following rules apply:
• If Factor 2 contains alphanumeric data and the Result field is alphanumeric, RPG II
moves characters without changing them.
• If Factor 2 contains numeric data and the Result field is numeric, the sign of Factor 2
becomes the sign ofthe Result field.
3-6

Operation Codes

• If Factor 2 contains numeric data and the Result field is alphanumeric, RPG II moves
the sign with the rightmost character position.
• If Factor 2 contains alphanumeric data and the Result field is numeric, each character
is converted to its corresponding numeric digit and moved to the Result field. The zone
portion of the rightmost character in Factor 2 is used to determine the sign of the
Result field.
When the Field length of Factor 2 is longer than the Field length of the Result field, the
following rules apply:
• If Factor 2 contains alphanumeric data and the Result field is alphanumeric, RPG II
moves only the number of characters needed to fill the Result field.
• If Factor 2 contains numeric data and the Result field is numeric, the sign of Factor 2
becomes the sign of the Result field.
• If Factor 2 contains numeric data and the Result field is alphanumeric, the Result
field contains only numeric data; that is, the sign of Factor 2 is not used.
• If Factor 2 contains alphanumeric data and the Result field is numeric, the leftmost
character(s) of Factor 2 are converted to the corresponding numeric digit(s) and
moved to the Result field. The zone portion of the rightmost character in Factor 2 is
used to determine the sign of the Result field.
When the Field length of Factor 2 is shorter than the Field length of the Result field, the
following rules apply:
• If Factor 2 contains either numeric data or alphanumeric data and the Result field is
numeric, RPG II moves the digits of numeric fields or the corresponding numeric digits, if alphanumeric, of Factor 2 into the leftmost character positions of the Result
field. The sign ofthe Result field remains unchanged.
• If Factor 2 contains either numeric or alphanumeric data and the Result field is
alphanumeric, RPG II moves the data into the Result field beginning with the
leftmost character position. The rightmost character positions in the Result field
remain unchanged.

3.2.4 Example
In the following example, the pre-execution-time array ARRl is read from the input file
ARRFILE and is copied to the execution-time array DUPARR. The array is modified by
moving the input field INPFLD to the second and third elements of the array. Additionally,
the field MYREC consists ofthe first element in ARRl and the last three characters of the
third element in ARR1.

Operation Codes

3-7

011
1213
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

ARRFIlE

ARRl
6
DUPARR

I
C
C
C
C

HOVEAARRl
HOVEAINPF'lD
HOVE ARR1,3
HOVELARR1,1

IARRFIlE AA 01

6 5
6 5

1 10 INPF'LD
DUPARR
ARR1,2
HYREC B
HYREC
ZK-4515-85

For this example, the input file (ARR1) contains the following data:

Field

Data

ARRl,1
ARR1,2
ARR1,3
ARR1,4
ARR1,5
ARR1,6
INPFLD

12345
67890
ZZZZZ
ZZZZZ
ZZZZZ
ZZZZZ
ABCDEFGHIJ

After executing the program, the fields would contain the following data:
MYREC
ARR1,1
ARR1,2
ARR1,3
ARR1,4
ARR1,5
ARR1,6
DUPARR

3-8

= 12345HIJ
= 12345
=

ABCDE

= FGHIJ
= ZZZZZ
ZZZZZ
ZZZZZ
= 1234567890ZZZZZZZZZZZZZZZZZZZZ

=
=

Operation Codes

3.3 Set Operation Codes
Set operation codes (SETON and SETOF) set indicators on and off. They affect only those
indicators in columns 54 through 59.
If you use set operation codes to set control-level indicators on and off, they do not affect
lower control-level indicators.

3.3.1 SETON
SETON sets on the indicators you specify in columns 54 and 55,56 and 57, and 58 and 59.
You cannot set the first-page (IP) or matching-record (MR) indicators on.
If you use SETON to set the LR indicator on at total time, processing stops after RPG II
finishes total-time output operations.
If you use SETON to set the LR indicator on at detail time, processing stops after RPG II
finishes the next total-time output operation.
If you use SETON to set halt indicators on and they are not set off before RPG II finishes
detail-time output operations, processing stops.

3.3.2 SETOF
SETOF sets offthe indicators you specify in columns 54 and 55, 56 and 57, and 58 and 59.
You cannot set the first page (lP) or matching-record (MR) indicators off.
In the following example
• The SETON operation sets indicators 11 and 22 on .
• The SETOF operation sets indicator 33 off.

Field length
I Deci~al positions
I IHaif adjust (H)
I
I II
I Indicators
Operation
I IIResulting
I I
I
Factor
Resu It I I I indicators
I I
Factor
I
field I 11+ - 0
I I
1
I
2
I
I II> < = +- Co~~ents --+
CI NxxNxxNxxl
I
I
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contro I I eve I

** *
C
C

*SETON *

SETOF

*--*** * * *
1122
33

ZK-4516-85

Operation Codes

3-9

3.4 Subroutine Operation Codes
Subroutine operation codes are used to identify and execute subroutines. A subroutine is a
group of Calculation specifications that you can execute more than once in a single program cycle.
You can use SR in columns 7 and 8 to indicate that the specification is part ofa subroutine,
although this is optional. You cannot use control-level indicators in columns 7 and 8 of a
subroutine. However, you can use any indicator in columns 9 through 17. Also, you can use
AN and OR in columns 7 and 8 to set up a relationship between two program lines.
You can use up to 254 subroutines in a program. Subroutines must be placed after all other
calculations. Subroutines cannot be nested or recursive. However, you can use EXSR to
call one subroutine from another.

3.4.1 BEGSR
BEGSR indicates the beginning of a subroutine and must be the first specification in a
subroutine. Factor 1 contains the name of the subroutine. All other columns in the same
specification must be left blank except for an optional SR in columns 7 and 8.

3.4.2 ENDSR
ENDSR indicates the end of a subroutine and must be the last specification in a subroutine. Factor 1 can contain a label for a GOTO operation within the subroutine. All other
columns in this specification must be blank, except for an optional SR in columns 7 and 8.
Once the program reaches the ENDSR operation, it returns program control to the specification immediately following the EXSR operation code that invoked the subroutine.

3.4.3 EXSR
EXSR executes a subroutine. Factor 2 contains the name of the subroutine. It must be the
same name you used in Factor 1 of the BEGSR operation. You can use control-level and
conditioning indicators to condition EXSR.
After the program performs the operations in the subroutine, control branches to the specification immediately following EXSR.

3.4.4 Example
In the following example, line 11 causes RPG II to execute the subroutine SUBl. The subroutine consists oflines 22 through 24.

3-10

Operation Codes

Field length
I Decimal positions
I IHaif adjust (H)
I
I Indicators
Operation
I II
I IIResulting
I I
I
Resu I t I II indicators
I
I I
Factor
Factot'
field I 11+-0
I I
1
I
2
I
I II> < = +- Comments --+
CI NxxNxxNxxl
I
I
o I 1 I 2 I 3 I 4 I 5 I 6 I 7 I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contt'o I Ieve I

** *02
11 C

*EXSR SUB1
*

22 CSR
23 CSR 02
24 CSR

SUB1
HOURS

BEGSR
HULT RATE
ENDSR

DAYPAY 52H
ZK-4517-85

3.5 Bit Operation Codes
Bit operation codes set and test bits. You must use one-character alphanumeric fields in
Factor 2 and the Result field.

3.5.1 BITON
ElTON sets on the bits you specify in Factor 2 in the Result field, replacing the value in the
Result field. Factor 2 contains the source of bits in bit numbers or a field name.
You can set on bit numbers 0 through 7. Zero is the leftmost bit. You must enclose the bit
number in apostrophes. For example, to set bits 1, 2, and 3 on, enter '123' in Factor 2. You
cannot specify a bit number more than once.
The field name is a one-character alphanumeric field, table, or array element. The bits that
are on in the field name are set on in the Result field. If you specify an array element, each
array element must be a one-character field.
You can use indicators in columns 7 through 17, but the following columns must be left
blank:
• Columns 18 through 27 (Factor 1)
• Column 52 (Decimal positions)
• Column 53 (Half adjust)
• Columns 54 through 59 (Resulting indicators)

Operation Codes

3-11

3.5.2 BITOF
BIT OF sets offthe bits you specify in Factor 2 in the Result field, replacing the value in the
Result field. To specify operands for BITOF, follow the same guidelines as for BITON.

3.5.3 TESTB
TESTB compares the bits in Factor 2 with the corresponding bits in the Result field. Factor
2 can contain bit numbers or a one-character alphanumeric field. Bit numbers and onecharacter alphanumeric fields follow the same rules as those for BITON and BITOF.
Indicators in columns 54 through 59 reflect the status of the bits in the Result field; therefore, you must assign at least one resulting indicator. You can set up to three resulting
indicators but no more than two resulting indicators can be identical.
If Factor 2 is a field in which all bits are off, no resulting indicator is set on; otherwise,
indicators in columns 54 through 59 indicate the result of the comparison as follows:

• RPG II sets the indicator in columns 54 and 55 on, if all bits specified in Factor 2 are off
in the Result field.
• RPG II sets the indicator in columns 56 and 57 on, if some bits specified in Factor 2 are
on in the Result field and some are off.
• RPG II sets the indicator in columns 58 and 59 on, if all bits specified in Factor 2 are on
in the Result field.
You can use indicators in columns 7 through 17, but the following columns must be left
blank:
• Columns 18 through 27 (Factor 1)
• Column 52 (Decimal positions)
• Column 53 (Half adjust)

3.5.4 Example
In the following example
• Line 34 sets the bits 1,2, and 3 on in the Result field FLDl.
• Line 35 tests the bits 1,2, and 3 in the Result field FLDl. If all the bits are on, indicator 11 is set on. If one or more of the bits are off, indicator 11 is set off.
• Line 36 sets the bits 4,5, and 6 off in the Result field FLD2.
• Line 37 tests the bits 4, 5, and 6 in the Result field FLD2. If all the bits are off, indicator 22 is set on. Ifone or more of the bits are on, indicator 22 is set off.

3-12

Operation Codes

Field length
I Deci~al positions
I IHaif adjust (H)

Contt'o I I eve I
I

I Indicators

Operation

I I

I
I
I
I

I IIResulting
Resu It I II indicatot's
Factor
I I
Factor
field I 11+ - 0
2
I I
1
I
I II) < = +- Co~~ents --+
I
CI NxxNxxNxxl
011
I
2
I
3
I
4
151
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

34 C
35 C
36 C
37 C

BITON' 123'
TESTB'123'
BITOF'456'
TESTB'456'

FLDl
FLD1
FLD2
FLD2

*--*** * * *
11
22
ZK-4518-85

3.6 Compare Operation Code
COMP tests fields for certain conditions. Based on the result of the comparison, you can
assign resulting indicators to condition calculation and output operations.
COMP compares the contents of Factor 1 to the contents of Factor 2. An indicator in columns 54 through 59 indicates the result ofthe comparison as follows:
• If Factor 1 is greater than Factor 2, RPG II sets the indicator in columns 54 and 55 on.
• If Factor 1 is less than Factor 2, RPG II sets the indicator in columns 56 and 57 on.
• If Factor 1 is equal to Factor 2, RPG II sets the indicator in columns 58 and 59 on.
You must specify at least one resulting indicator. The Result field must be left blank.
When using the COMP operation code, consider the following restrictions and default
characteristics:
• If you compare numeric fields, the fields are aligned at their implied decimal point.
Fields are filled with zeros to the left and right of the decimal point until both fields
are equal in length. For example, if you compare 1234.56 to 1.2, RPG II fills the second
field (1.2) with zeros (0001.20) until both fields are equal in length.
• If you compare alphanumeric fields of unequal lengths, the fields are aligned at the
leftmost character. Shorter fields are filled with blanks until the two fields are equal
in length.
• RPG II compares numeric fields algebraically.
• Positive numeric fields are greater than negative numeric fields.

Operation Codes

3-13

• If you have specified an alternate collating sequence, RPG II translates character
fields to the alternate collating sequence before comparing them.
• You cannot compare an alphanumeric field to a numeric field.
• You cannot compare entire arrays (nonindexed).
In the following example, ifthe contents of the field CODE are greater than 1, RPG II sets
indicator 11 on and sets indicators 22 and 33 off. If the contents of CODE are less than 1,
RPG II sets indicator 22 on and sets indicators 11 and 33 off. If CODE is equal to 1, RPG II
sets indicator 33 on and sets indicators 11 and 22 off.

Control level
I
I Indicatot's
I I
Factor
I I
I I
1
CI NxxNxxNxxl
011
I
2

Field length
I Deci~al positions
I IHalf adjust (H)
Operation
I II
I
I II Resu Iting
I
Factor
Resultl I Iindicators
I
2
field I 11+ - 0
I
I
I
I II> < = +- Co~~ents --+
131
4
I
5
I
6
I
7

** *

*COMP *'1'

I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
C

*
CODE

*--*** * * *
112233

ZK-4519-85

3.7 Input and Output Operation Codes
You can use the following operation codes to alter the normal input and output sequence,
enabling the program to read and write records during calculations.

3.7.1 CHAIN
CHAIN reads a record from a file during calculations and places the contents of the record
into the fields you specify on the Input specification. You can read records randomly from a
sequential, a direct, or an indexed file.
If you want to read a record from a sequential or a direct file, Factor 1 must contain the
relative record number of that record. If you want to read a record from an indexed file,
Factor 1 must contain a field name or a literal that is the key of that record. The Field
length of the field or literal specified in Factor 1 must be the same as the Field length of the
key.
Factor 2 contains the name of the file from which the record is read. This file must be the
same file you describe in the File Description specification with a C or an F in column 16
(Type).

3-14

Operation Codes

You can use any indicator in columns 7 through 17, but columns 43 through 53, and 56 and
57 must be left blank. If you condition the chained or full-procedural file with an external
indicator, use the same indicator to condition the CHAIN operation.
You can specify an indicator in columns 54 and 55 to verify the CHAIN operation. IfRPG II
cannot locate the record, it sets the indicator in these columns on. If you do not use an
indicator in columns 54 and 55, and RPG II cannot locate the record, a run-time error
occurs. If RPG II cannot locate the record, you can add a record to the chained file (if you
use a resulting indicator to indicate that a record has not been found), but you cannot
attempt to update the record.
You can specify on a CHAIN operation that if a record is locked, to set on an indicator.
Enter the indicator for a locked record in columns 58 and 59 of a Calculation specification.
If you specify an indicator in columns 58 and 59, the program will not wait for the record to
become unlocked before proceeding, and will turn on the indicator to show that the
requested record was locked. If you do not specify the indicator, the program will wait until
any record lock is released before proceding. This indicator is only allowed on CHAINs to
files that are marked as SHARE (S or R in column 68 on File specifications). The file cannot
be an output file. Note that if another program has locked a record for update, but uses the
file sharing option R, then a CHAIN operation that accesses that record will be successful;
no lock will be seen and an indicator in columns 58 and 59 will be turned off.
If you chain to a file with packed keys, the field in Factor 1 ofthe CHAIN operation must be
numeric and have the same number of digits as the key in the chained or full-procedural
file. Packed key fields can be up to 8 bytes long.
If you use one or more chained or full-procedural files during the same program cycle, and
the previous CHAIN operation was successful, then any record-identifying indicators you
use remain on throughout the cycle. If you use a chained file more than once during the
same program cycle, only the last record processed can be updated during output, unless
you specify exception output for each CHAIN operation.
The CHAIN operation is also used to load a direct file (a chained output file). Use the
CHAIN operation to position the file to the record you want to add to the file.
See Part I, Chapter 5 for information on processing files.
In the following example
• Line 33 retrieves the record from the input file FILEI with the relative record number
specified in the field RECNO. If the record is not found, RPG II sets indicator 11 on. If
the record is found, RPG II sets indicator 11 off.
• Line 34 branches to a TAG operation to terminate the program ifthe previous CHAIN
operation causes a record-not-found error.
• Line 55 retrieves the record with the key 761 from the indexed file FILE2. If a record
with a key of 761 does not exist, RPG II sets indicator 22 on. If a record with a key of
761 does exist, RPG II sets indicator 22 off.
Operation Codes

3-15

011
12
I
3
I
4
1516
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

FTILE1
rFILE2

33 C
34 C

IC r
IC r

DISK

10 DISK

RECNO

CHAINFILE1
GO TO END

761

CHAINFILE2

55 C

80
80 5AI

ZK-4520-85

3.7.2 DSPLY
DSPLY allows you to display, on line, up to 511 characters at run time. RPG II can
• Display up to 511 characters from a field without suspending program execution. Factor 1 names the field to display.
• Display the number of characters up to one less than your screen width from the
Result field. The program suspends execution after displaying the Result field. The
cursor is positioned at the next line where you can enter a new value for the Result
field from the terminal.
When entering a new value for the Result field, terminate the input by pressing either a
RETURN key or a TAB key. If you press only a RETURN key or a TAB key for the new
value of the Result field, the data in the Result field remains the same.
When using DSPLY, observe the following restrictions and default characteristics:
• You cannot change the contents of a literal; therefore, do not specify a literal in the
Result field.
• The maximum length of the Result field is one character less than the screen width.
When entering data for the Result field, consider the following characteristics:
• You do not need to fill numeric data with leading zeros.
• Numeric data is aligned on the decimal point when entered into the Result field.
• Alphanumeric data is left-justified when entered into the Result field.
• If you enter no characters and press either the RETURN key or the TAB key, the value
in the Result field remains unchanged.

3-16

Operation Codes

3.7.3 Example
In the following example, if the data in NUMBER is greater than 100.0, the number will
be displayed on the terminal followed on the next line by the current value of RESNO.
Then, you can enter a new value for RESNO followed by pressing the RETURN key.
011
I
2
I
3
I
4
151
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

FTTYFILE D F
81
TTY
IINFILE AA 01
I
1
C 01
NUMBER
COMP 100.0
C 10
NUMBER
DSPLYTTYFILE RESNO

50NUMBER
10
50
ZK-4521-85

3.7.4 EXCPT
EXCPT allows you to write a variable number of records during detail-time or total-time
calculations. To do this you must specify the following entries:
• On the Calculation specification:
- EXCPT as the operation code
- blanks or an EXCPT name in Factor 2
• On the Output specification:
- E in column 15 (Type) for the record you want to write
- blanks or an EXCPT name in columns 32 through 37 (Field name)
The EXCPT operation writes those records that have an E in column 15 of the Output
specification and that satisfy the conditions specified by the conditioning indicators. In
addition, if the EXCPT operation has a blank Factor 2, only exception records with blanks
in columns 32 through 37 ofthe 0 specification will be written; ifthe EXCPT operation has
an EXCPT name in Factor 2, only exception records with the same name in columns 32
through 37 of the 0 specification will be written.
You can use indicators in columns 7 through 17 of the Calculation specification. Factor 2
can contain blanks or an EXCPT name. All other columns must be blank.
An EXCPT name can be used on multiple EXCPT output record lines. Only exception
records, not heading, detail, or total records, can contain an EXCPT name.
In the following example, line 22 tells RPG II to write the record described in line 89 during calculations if indicators 01, 02, and 03 are on. Line 34 tells RPG II to write the record
described in line 95 if indicator 04 is on.

Operation Codes

3-17

o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
22 C

EXCPT

34 C

EXCPTHDG

77 OOUTFIL
89 0

01 02 03

95 0

HDG
ZK-4660-85

3.7.5 FORCE
FORCE allows you to select the next file from which a record is read when doing multifile
processing. You can select primary or secondary input and update files. Factor 2 contains
the name of the file.
You can use conditioning indicators, but all other columns must be left blank.
When RPG II executes a FORCE operation, it reads, at the next program cycle, a record
from the file you specify. If you specify more than one FORCE operation during the same
program cycle, RPG II ignores all FORCE operations except the last.
Although FORCE operations override normal multifile processing, they cannot override
the first record selected by the program. Reading the first record occurs in the first cycle
before the first pass through calculations.
If a FORCE operation is issued for a file that is at its end-of-file, the file is not selected for
processing. In this case, normal multifile processing logic selects the next record.

In the following example, RPG II reads the next record from the file SPECFIL at the next
program cycle if indicators 01,02, and 03 are on.

Contt'o I I eve I
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I

CI NxxNxxNxxl

Factot'
2
I

Field length
I Decimal positions
I IHalf adjust (H)
I II
IllResulting
Resultl Ilindicatot's
field I II + - 0
I
I II> < = +- Comments --+

011
12
I
3
I
4
I
5
1617
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
33 **
C *01 02 03 *

*FORCESPECFIL
*
*
ZK-4523-85

3-18

Operation Codes

3.7.6 READ
READ causes RPG II to read a record from a demand or full-procedural file. Factor 2 contains the name ofthe file from which a record is read. You can read a record from the following types of input and update files:
• Sequential and direct disk files processed consecutively
• Indexed disk files processed sequentially by key or by limits
You can use any indicators in columns 7 through 17 and in columns 58 and 59. RPG II sets
the indicator in columns 58 and 59 on when an end-of-file condition occurs, or for each
READ operation following an end-of-file condition. If there is no indicator in columns 58
and 59, a run-time error occurs. Columns 18 through 27 and 43 through 57 must be left
blank.
IfRPG II does not open a file because an external indicator is off, a READ operation on the
file causes an end-of-file condition to occur.
In the following example, RPG II reads the next record from the file SPECFIL if indicator
99 is off. If an end-of-file condition occurs, RPG II sets indicator 99 on. If an end-of-file condition does not occur, RPG II sets indicator 99 off.
Contl'ol level
I
I Indicatol's
I I
I I
Factor'
I I
1
CI NxxNxxNxxl

Operation
I
I
Factor
I
2
I
I

Field length
I Deci~al positions
I IHalf adjust (H)
I II
I IIResulting
Resultl I I indicators
field I 11+ - 0
I
I II> < = +- Co~~ents --+

011
12
I
3
I
4
I
5
16
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** N99
*
22 C

READ SPECFIL

*
ZK-4524-85

3.7.7 SETLL
SETLL positions a file at the next record with a key that is greater than or equal to the key
you specify in Factor 1. Factor 2 contains the name of the file for which the lower limit is
set. Factor 2 must be an indexed demand or full-procedural file being processed sequentially within limits.
Factor 1 can be a field name or a literal, and must be the same size as the key specified in
the File Description specification. If the keys in the file are in packed decimal format, Factor 1 must be numeric.
You cannot use a record address file and the SETLL operation on the same file.

Operation Codes

3-19

If the program issues a READ operation before issuing a SETLL operation, processing
begins with the first record in the file.

When RPG II reaches the end of a file, you can use another SETLL operation to reposition
the file. If the SETLL operation is not successful, you must reposition the file with a successful SETLL operation.
When a SETLL operation is performed on a record whose key is greater than the highest
key in the file, the subsequent READ operation will be as ifthe current record pointer had
not changed from the previous READ operation. If a successful SETLL operation is done
followed by a SETLL operation for a record whose key is greater than the highest key in
the file, with no intervening READ operation, the next READ operation will be as if the
current record pointer had not changed from the previous READ operation. In the latter
case, it appears as if the successful SETLL operation never occurred, because it was followed by a failing SETLL operation.
In the following example, KEYl contains the lower key limit for the file FILEl. The READ
operation retrieves the first record with a key that is greater than or equal to the field
KEYl.

Field length
I Deci~al positions
I IHaif adjust (H)

Contro I Ieve I
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I

CI NxxNxxNxxl

Factor
2
I

I
Resultl
field I
I
I

IIResulting
I Iindicators
11+ - 0

II) < = +- Co~~ents --+

011
12
13
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

C
C

*KEY1

SETLLFILE1
READ FILE1

*
ZK·4525·85

3.8 Branching Operation Codes
RPG II performs operations in the order they appear in your program. However, you can
use branching operation codes to skip or repeat operations under certain conditions.

3.8.1 GOlD
GOTO transfers program control to the label you specify in Factor 2.

3-20

Operation Codes

GOTO is especially useful in the following situations:
• Skipping calculations when certain conditions occur
• Performing certain calculations for certain record types
• Repeating calculations
You can transfer control in the following cases:
• To a previous line
• From one detail-time calculation line to another
• From one total-time calculation line to another
• From one subroutine calculation to another inside the same subroutine
You cannot transfer control from the following lines:
• Detail-time calculation line to a total-time calculation line
• Total-time calculation line to a detail-time calculation line
• Line inside a subroutine to a line outside that subroutine
• Line outside a subroutine to a line inside a subroutine
When using GOTO, the following columns must be left blank:
• Columns 18 through 27 (Factor 1)
• Columns 43 through 48 (Result field)
• Columns 49 through 51 (Field length)
• Column 52 (Decimal positions)
• Column 53 (Half adjust)
• Columns 54 through 59 (Resulting indicators)

3.8.2 TAG
TAG identifies the line to which program control from a GOTO operation branches. Factor
1 contains the same label you used in Factor 2 of the GOTO operation.
You cannot use conditioning indicators (columns 9 through 17) to condition a TAG operation; however, you can use a control-level indicator ifthe TAG is in total-time calculations.

Operation Codes

3-21

3.8.3 Example
In the following example, RPG II branches to line 66 if indicators 67, 68, and 69 are on.

Field length
I Decimal positions
I IHaif adjust (H)

Contro I Ieve I
I

I Indicators

Opet'ation

I I

I
I
I
I

IllResulting
I I
Factor
Resultl I Iindicators
Factot'
I I
1
2
field I 1/+ - 0
I
I II> < = +- Comments --+
CI NxxNxxNxxl
I
011
12
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
** *
*
*
*
*
56 C 67 68 69
GOTO BRCH1

66 C

BRCH1

TAG
ZK-4526-85

3.9 LOKUP Operation Code
LOKUP searches for an entry in a table or an array. Factor 1 contains the search argument
and Factor 2 contains the name ofthe table or array. The search argument can be an alphanumeric or a numeric constant, a field name, an array element, or a table name. Search
arguments must be the same length and format as the entries in the table or array. For
example, both fields must be numeric with the same number of digits, or both must be
alphanumeric with the same number of characters.
You must use at least one, but not more than two, resulting indicators to specify:
• The type of search (high, low, or equal)
• The result ofthe search (successful or not successful)
The following list describes the three types of searches:
• A resulting indicator in columns 54 and 55 causes RPG II to search the table or array
for the entry that is nearest to but higher in sequence than the search argument. You
can specify this search only for sequenced tables and arrays.
• A resulting indicator in columns 56 and 57 causes RPG II to search the table or array
for the entry that is nearest to but lower in sequence than the search argument. You
can specify this search only for sequenced tables and arrays.
• A resulting indicator in columns 58 and 59 causes RPG II to search the table or array
for the entry that is equal to the search argument.
3-22

Operation Codes

You can use two indicators to test for HIGH and EQUAL or LOW and EQUAL conditions.
RPG II searches for an entry that satisfies either condition, with EQUAL given precedence. You cannot specify both HIGH and LOW conditions at the same time.
If the search is successful, RPG II sets on the resulting indicator(s). If the search is not
successful, RPG II sets off the resulting indicator(s).

3.9.1 Searching Tables
LOKUP can search one table or two related tables. When searching a single table, you
must specify the following:
• Factor 1
• Factor 2
• At least one resulting indicator
You can specify conditioning indicators in columns 7 through 17.
When RPG II finds a table entry that satisfies the type of search, it places a copy of the
entry in a special storage area. If you repeat the search, the new entry replaces the previous entry in the storage area.
When searching for an entry in two related tables, RPG II searches only the table specified
in Factor 2. When the search condition is satisfied, RPG II places the corresponding entries
in their respective storage areas.
To program a search for an entry in related tables, you must make the following entries:
• Specify the search argument in columns 18 through 27 (Factor 1).
• Specify the name of the table to be searched in columns 33 through 42 (Factor 2).
• Specify the name of the related table in columns 43 through 48 (Result field).
• Specify at least one resulting indicator in columns 54 through 59 (Resulting
indicators).
You can specify conditioning indicators in columns 9 through 17.
Both tables should have the same number of entries. The related table must have as many
entries as or more entries than the table to be searched.
Whenever you use a table name in an operation other than a LOKUP operation, the table
name refers to the data placed in storage by the last successful LOKUP operation. Then,
you can use the table entry in subsequent calculations. If you specify a table name in an
operation other than a LOKUP operation but before a successful LOKUP operation occurs,
unpredictable results can happen.

Operation Codes

3-23

If you specify the table name as Factor 1 in a LOKUP operation, the contents ofthe storage
area are used as the search argument.

You can also use a table as the Result field in operations other than LOKUP. In this case,
the contents of the storage area are replaced by the result of the calculation you specify.
The corresponding entry in the table is also changed. In this way, you can use calculations
to change the contents of tables.
In the following example, TABLIS has been previously defined as a table. RPG II searches
for the entry that has the same value as the field PARTNO and, if successful, sets indicator
33 on.

Field length
I Decimal positions
I IHalf adjust (H)

Contro I Ieve I
I

I Indicators

Operation

I I

I
I
I
I

I I

Factor

I I

CI NxxNxxNxxl
I
1
I

I IIResulting
Resultl I Iindicators
Factor'
field I 11+ - 0
2
I
I II> < = +- Comments --+
I
I
3
I
4
I
5
I
6
I
7.

12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *
56 C

*
PARTNO

* *
LOKUPTABLIS

*
ZK-4527-85

3.9.2 Searching Arrays
LOKUP operations for arrays are the same as those for tables, except that you cannot use
the Result field. If the element searched for is found, its contents are not moved to a storage
area. Indicators reflect whether the element is present.
To program a search for an element in an array, you must specify the name of the array to
be searched in columns 33 through 42 (Factor 2). Follow the same rules for specifying
indicators for arrays as for tables.
You can specify the element to begin searching by adding an index. The index can be a
numeric literal or a field. RPG II begins searching at the specified element and continues
the search until it finds the element or it reaches the end of the array. If you use a numeric
literal to specify the index, RPG II does not change its value to reflect the result of the
search. If you use a field to specify the index and the search is not successful, RPG II places
the value of 1 in the field. If you use a field to specify the index and the search is successful,
RPG II places the number of that array element that satisfied the search (counting from
the first element) in the field. Then, you can use the index field to reference that array
element in subsequent operations.

3-24

Operation Codes

If you use an index that is less than or equal to zero, or greater than the number of elements in the array, and you compile the program with the RPG/CHECK = BOUNDS command, RPG II issues a run-time error. If you use an index that is less than or equal to zero,
or greater than the number of elements in the array, and you do not compile the program
with the RPG/CHECK = BOUNDS command, unpredictable results can occur.

3.9.3 Example
In the following example, MNTH has been previously defined as a sequenced array and E
as a numeric field. RPG II begins searching with the first element ofthe array, because 1 is
assigned to E, and searches for the first entry with a value that is greater than and equal to
1000. If an entry is found, E will contain the index number ofthe entry and the indicator 99
will be set on. If an entry is not found, E will contain 1 and the indicator 99 will be set off.

Field length
I Deci~al positions
I IHaif adjust (H)
I
I Indicators
Operation
I II
I I
I IIResulting
I
I I
Factor
I
Factor
Resultl I Iindicators
I I
1
field I II + - 0
I
2
I
I II> < = +- Co~~ents --+
CI NxxNxxNxxl
I
I
o I 1
I
2
I
3
I
4
I
5
I
6
I
7
I
12345678901234567890123456789012345678901234567890123456789012345678901234567890
Contro I Ieve I

** *
C
C

*
1000

*Z-ADD1*

LOKUPHNTH,E

*--*** * * *
30

99 99
ZK-4528-85

3.10 Subprogram Operation Codes
RPG II programs can call subprograms written in other languages and can pass and
receive parameters between the main program and the subprogram. See Part I, Chapter 9
for examples of subprogram operation codes.

3.10.1 CALL
CALL transfers control to a subprogram. Factor 2 contains a character literal or a field
defined by the EXTRN operation code that names the entry point in the subprogram.
The Result field can contain the name of the parameter list associated with the PLIST
operation code. This way, you can share parameters between the main program and the
subprogram. You can also specify the individual parameters immediately following the
CALL operation code.

Operation Codes

3-25

Factor 1, Half adjust, and the resulting indicators in columns 54 and 55, and 58 and 59,
must be blank. However, you can specify a resulting indicator in columns 56 and 57.
RPG II sets this indicator on when the subprogram returns with an error status.

3.10.2 EXTRN
EXTRN initializes the value of a numeric unscaled field to a link-time constant. You can
use EXTRN to perform the following operations:
• Extend the subprogram name to more than eight characters.
• Allow your program to access link-time constants, including status codes.
You define link-time constants using external names. Use Factor 1 to name the field
RPG II initializes, using the value of the link-time constant. Use Factor 2 to name the
external constant. You can use up to 31 characters to name the constant. You must enclose
the constant in apostrophes.
The external name must be defined as a global symbol in an object module available to the
program at link time. Otherwise, an error will occur at link time.
Factor 1 of the EXTRN operation is defined as a nine-digit numeric field with zero Decimal
positions. The field cannot be defined elsewhere in the program. Fields defined by an
EXTRN operation cannot be used as a Result field in a calculation or have Blank after
specified when used on an Output specification.
Conditioning indicators must be left blank.

3.10.3 GIVNG
GIVNG allows you to define a parameter that receives the return status from the subprogram. (See the VAX/VMS Run-Time Library Routines Reference Manual for information on the definition of return status.) GIVNG must follow the last PARM, PARMV, and
PARMD operation following a CALL operation. The Result field contains the name of a
unscaled numeric field, table, or array element.
Entries in Decimal positions and Field length are optional. If you specify a Field length,
the entry for Decimal positions must be zero. The following columns must be left blank:
• Columns 9 through 17 (Conditioning indicators)
• Columns 18 through 27 (Factor 1)
• Columns 33 through 42 (Factor 2)
• Column 53 (Half adjust)
• Columns 54 through 59 (Resulting indicators)

3-26

Operation Codes

3.10.4 PARM
PARM passes parameters by reference to a subprogram. The Result field identifies the
parameter. The parameter can be a field, a table, an array element, or an array. Factor 2
can contain a field, a table, an array element, an array, or a literal. The contents of Factor 2
are copied into the Result field before the subprogram is called. If the Result field is
numeric, Factor 2 must be numeric. In this case, the value in Factor 2 is copied into the
Result field in the same manner as a Z-ADD operation. If the Result field is alphanumeric,
Factor 2 must be alphanumeric. In this case, the value is left-justified in the Result field
and trailing characters are filled with blanks.
The subprogram can change the contents of the Result field but cannot change the contents
of Factor 2. Using Factor 2 allows you to pass the values from Factor 2 knowing that the
subprogram cannot modify the field.
After a successful CALL operation, RPG II copies the contents of the parameter into Factor
1. Factor 1 can contain a field, a table, an array, or an array element. The copying is done in
the same manner as for Factor 2. Entries for Factor 1 and Factor 2 are optional.
Entries in Decimal positions and Field length are optional. Conditioning indicators must
be left blank. RPG II, by default, passes numeric data by reference in packed decimal
format.
You can also use PARM to convert to the numeric data type needed by the subprogram
being called. Use columns 54 through 59 (Resulting indicators) to specify the notation for
the parameter. See Part I, Chapter 9 for information on specifying parameters.
You can use one of the following access types:
• R (Read only)
The parameter is read by the subprogram(s), but not modified.
• W (Write only)
The parameter is not read by the subprogram(s), but a new value is supplied by the
subprogram.
• M (Modify)
The parameter is read by the subprogram(s) and a new value is supplied by the
subprogram.

Operation Codes

3-27

You can use one of the following data types:
• W (Word integer (signed»
• L (Longword integer (signed»
• Q (Quadword integer (signed»
• F (F Jioating single-precision)
• D (D_floating double-precision)
• NRO (Numeric string, right overpunched sign)
See Part II, Chapter 1 for information on data types.
You cannot specify an access type or data type if the Result field is an entire array
(nonindexed) .

3.10.5 PARMD
PARMD passes parameters by descriptor to a subprogram. The Result field contains the
name of the field, the name of an array element, the name of the array, or a literal that
identifies the parameter. Long character literals can be used effectively in the PARMD
result field. See Part II, Section 2.9.5 for information on long character literals.
Entries in Decimal positions and Field length are optional. The following columns must be
left blank:
• Columns 9 through 17 (Conditioning indicators)
• Columns 18 through 27 (Factor 1)
• Columns 33 through 42 (Factor 2)
• Column 53 (Half adjust)
• Columns 54 through 59 (Resulting indicators)
See the VAX/VMS Run-Time Library Routines Reference Manual for information on argument descriptor format.

3.10.6 PARMV
PARMV passes parameters by value to a subprogram. The Result field contains the name
of an unscaled numeric field, table, array, or an un scaled numeric literal that identifies the
parameter.

3-28

Operation Codes

Entries in Decimal positions and Field length are optional. If you specify a Field length,
the entry for Decimal positions must be O. The following columns must be left blank:
• Columns 9 through 17 (Conditioning indicators)
• Columns 18 through 27 (Factor 1)
• Columns 33 through 42 (Factor 2)
• Column 53 (Half adjust)
• Columns 54 through 59 (Resulting indicators)

3.10.7 PLiST
PLIST identifies the name ofthe parameter list for a subprogram. Use this operation code
with the CALL operation code to access parameters in the subprogram. You can pass up to
255 parameters.
Factor 1 contains the name of the parameter list. The following columns must be left
blank:
• Columns 9 through 17 (Conditioning indicators)
• Columns 33 through 42 (Factor 2)
• Columns 43 through 48 (Result field)
• Columns 49 through 51 (Field length)
• Column 52 (Decimal positions)
• Column 53 (Half adjust)
• Columns 54 through 59 (Resulting indicators)
If you want to pass parameters, you must use one ofthe parameter operation codes (PARM,
PARMD, PARMV) to specify how you want to pass the parameters. Parameter operation
codes must immediately follow the CALL or PLIST operation. And, parameter operation
codes must be in the order expected by the subprogram.

Operation Codes

3-29

3.10.8 Example
The following example makes a call to the STR$UPCASE RTL routine. The call places
REP HEAD in the Result field RESULT.

Field length
I Deci~al positions
I IHalf adjust (H)

Contl'o I Ieve I
I

I Indicator's

Operation

I I

I
I

Factor

I
I

2
I

I I

Factor

I I

CI NxxNxxNxxl
011

I
Resultl
field I
I
I
I

IIResulting
I Iindicators
11+ - 0
II> < = +- Co~~ents --+
5

12345678901234567890123456789012345678901234567890123456789012345678901234567890

** *

C
C
C
C
C

*
UPCASE

*--*** * * *

HOVE 'rep head'HEAD
8
EXTRN'STR$UPCASE'
CALL UPCASE
PARHD
RESULT 8
PARHD
HEAD

ZK-4529-85

3-30

Operation Codes

Table 3-1: Summary of Operation Codes
Indicators

l-j

III

......

c-t-

;:s

(1
0

Operation
Code

Factor 1

28-32

18-27

ADDIHI
BEGSR
BITOF
BITON
CALL
CHAIN
COMP'
DIVrHI
DSPLY
ENDSR
EXCPT
EXSR
EXTRN
FORCE
GIVNG
GOTO
LOKUP lA
LOKUPF
MOVE
MOVEA
MOVEL
MULT,HI
MVR
PARM
PARMD
PARMV
PLIST
READ
SETLL

0
R

R
R
0
0
0

Factor 2

Result
Field

Control
Level

Conditioning

33-42

43-48

7-8

R
R
R
R
R
R
R

R
R
0

R
0

0
R
R
R
R

R
R
R
R
R
R
R

R
R

0
R
R
R
R
R
R
R
R

Resulting
-<

9-17

54-55

56-57

58-59

0
0
0
0
0
0
0

0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

0
0

OE
ONR
OH
0+

OL
0-

ORL
OEQ
OZ

OH
OH

OL
OL

OEQ
OEQ

0+
0+

00-

OZ
OZ

0
0
0
0
0
0
0
0
0

0
0

OEOF
(continued on next page)

Cr:I

Cr:I
~

Table 3-1: Summary of Operation Codes (Cont.)

Indicators

't:$
~

Operation
Code

Factor 1

(1
0

28-32

18-27

SETOF'
SETON'
SQRTIH)
SUB IH)
TAG
TESTB'
XFOOTIH)
Z-ADDIH)
Z-SUBIH)

>oj

$ll

.....

c+
0

Factor 2

Result
Field

Control
Level

Conditioning

43-48

7-8

0
0
0
0
0
0
0
0
0

Resulting
-<

9-17

54-55

56-57

58-59

0
0
0
0

0
0

0
0
0
0

0
0+
0+
0+

0
000-

0
OZ
OZ
OZ

::I

33-42

0
R

R
R

R
R
R
R

IH) You can specify Half adjust for this operation.
, Specify at least one resulting indicator for this operation.
Conditioning indicators are valid only for executable operation codes.
Fields without entries in this table must be blank.
IA) Factor 2 is an array.
IT) Factor 2 is a table.
Legend

+ = positive
E = error
NR = no record
ZB = zero or blank

- = negative
EQ = equal
R = required
RL = record locked

j'/

EOF = end of file
0= optional
Z = zero

Appendix A

Character Sets
Character Sets
Character

ASCII
Decimal

Hexadecimal

EBCDIC
Decimal

Hexadecimal

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
DLE
DC1
DC2
DC3
DC4
NAK
SYN
ETB
CAN

000
001
002
003
004
005
006
007
008
009
010
011
012
013
014
015
016
017
018
019
020
021
022
023
024

00
01
02
03
04
05
06
07
08
09
OA
OB
OC
OD
OE
OF
10
11
12
13
14
15
16
17
18

000
001
002
003
055
045
046
047
022
005
037
011
012
013
014
015
016
017
018
019
060
061
050
038
024

00
01
02
03
37
2D
2E
2F
16
05
25
OB
OC
OD
OE
OF
10
11
12
13
3C
3D
32
26
18
(continued on next page)

A-I

Character Sets
Character

EM
SUB
ESC
FS
GS
RS
US
space
!

#
$
%

,&
(
)

0
1
2
3
4
5
6
7
8
9

,
<
>
?
@

ASCII
Decimal

025
026
027
028
029
030
031
032
033
034
035
036
037
038
039
040
041
042
043
044
045
046
047
048
049
050
051
052
053
054
055
056
057
058
059
060
061
062
063
064

Hexadecimal

19
1A
1B

1C
1D

IE
IF
20
21
22
23
24
25
26
27
28
29
2A
2B
2C
2D
2E
2F
30
31
32
33
34
35
36
37
38
39
3A
3B
3C
3D
3E
3F
40

EBCDIC
Decimal

025
063
039
028
029
030
031
064
079
127
123
091
108
080
125
077
093
092
078
107
096
075
097
240
241
242
243
244
245
246
247
248
249
122
094
076
126
110
111
124

Hexadecimal

19
3F
27
1C
1D

IE
IF
40
4F
7F
7B
5B
6C
50
7D
4D
5D
5C
4E
6B
60
4D
61
FO
Fl
F2
F3
F4
F5
F6
F7
F8
F9
7A
6E
4C
7E
6E
6F
7C
(continued on next page)

A-2

Character Sets

Character

A
B
C
D
E
F
G

H
I

J
K
L

M
N

0
P

Q
R

S
T
U
V
W

X
Y
Z
[
\
]
A

,a
b
c
d
e
f
g
h

ASCII
Decimal

Hexadecimal

EBCDIC
Decimal

Hexadecimal

065
066
067
068
069
070
071
072
073
074
075
076
077
078
079
080
081
082
083
084
085
086
087
088
089
090
091
092
093
094
095
096
097
098
099
100
101
102
103
104
105

41
42
43
44
45
46
47
48
49
4A
4B
4C
4D
4E
4F
50
51
52
53
54
55
56
57
58
59
5A
5B
5C
5D
5E
5F
60
61
62
63
64
65
66
67
68
69

193
194
195
196
197
198
199
200
201
209
210
211
212
213
214
215
216
217
226
227
228
229
230
231
232
233
074
224
090
095
109
121
129
130
131
132
133
134
135
136
137

C1
C2
C3
C4
C5
C6
C7
C8
C9
D1
D2
D3
D4
D5
D6
D7
D8
D9
E2
E3
E4
E5
E6
E7
E8
E9
4A
EO
5A
5F
6D
79
81
82
83
84
85
86
87
88
89
(continued on next page)

Character Sets

A-3

Character Sets
Character
j

k
I
m
n
0

q
r

s
t
u

v
w
x
y

z
{
I
}

DEL

A-4

Character Sets

ASCII
Decimal

106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

Hexadecimal

6A
6B
6C
6D
6E
6F
70
71

72
73
74
75
76
77
78
79
7A
7B
7C
7D
7E
7F

EBCDIC
Decimal

Hexadecimal

145
146
147
148
149
150
151
152
153
162
163
164
165
166
167
168
169
192
106
208
161
007

91
92
93
94
95
96
97
98
99
A2
A3
A4
A5
A6
A7
A8
A9
CO
6A
DO
Al
07

Appendix B

Differences Between VAX RPG II and PDP-11 RPG II
This appendix describes the following:
• PDP-11 RPG II functionality that is not supported by VAX RPG II
• VAX RPG II functionality that is supported in a different manner from PDP-11
RPGII
• Additional functionality that is supported only by VAX RPG II Version 1 and later
versions.
This appendix does not list these new features which have been added to VAX RPG II Version 2. See the on-line release notes for details of these new features.
VAX RPG II does not support the following PDP-11 RPG II functionality:
• Control specification (H)
- Column 11 (Listing options) - The equivalent functionality is implemented using
the LIST qualifier to the DCL RPG command.
- Column 15 (Debug) - The DEBUG operation code is not supported. Instead, use the
VAXNMS Symbolic Debugger.
- Column 25 (Source listing) - A single page size for the listing is supported.
• Extension specification (E)
- Columns 11 through 18 (From file name) - PDP-11 RPG II allows the same table
input file to be specified for more than one pre-execution-time table or array. VAX
RPG II requires a different file for each pre-execution-time table or array.
• Calculation specification (C)
- Columns 28 through 32 (Operation) - The DEBUG operation code is not supported.
• Output specification (0)
- Column 39 (Blank after) - Specifying Blank after for a constant field is not supported.

B-1

• General
- VAX RPG II uses PRN format files for printer output files. This format requires that
you use the NOFEED qualifier with the PRINT command when printing printer
output files.
- PDP-ll RPG II handles both zoned numeric and overpunched decimal data formats for input transparently. VAX RPG II supports only overpunched decimal data
format.
- All user-defined names must be unique in VAX RPG II.
- VAX RPG II does not support the HO indicator. Errors detected by VAX RPG II
result in run-time errors.
- VAX RPG II does not recognize LO as an indicator. While LO can be used as a control
level in columns 7 and 8 of the Calculation specification, it cannot be used in an
Output specification.
VAX RPG II supports the following functionality differently from PDP-ll RPG II:
• File specification (F)
- Column 15 (File type) - When 0 (output) is entered in column 15 and column 66
(File addition) does not contain A, VAX RPG II always creates a new version ofthe
file, even if the file is an indexed or direct file. PDP-ll RPG II accesses an existing
indexed or direct file if the specified file is found.
- Columns 40 through 46 (Device code) - VAX RPG II uses the device code to define
the functions that can be performed on the associated file. It does not refer to a specific device.
- Columns 47 through 52 (Symbolic device) - VAX RPG II uses the symbolic device in
conjunction with the file name specified in columns 7 through 14 (File name) to
associate the VAX RPG II file name with the VAXIVMS file specification.
If you specify a symbolic device on the File Description specification and no VMS
logical name translation exists for that symbolic device, then RPG II will have RMS
use the symbolic device as the file name.
If a symbolic device consists of all blanks, then RMS will act as if the symbolic
device did not exist (for example, an attempt will be made to translate the file name
as a logical name). The symbolic device may consist of any characters and will be
passed to RMS when the file is opened.

B-2

Differences Between VAX RPG II and PDP-ll RPG II

In general, the file name will be translated as a logical name, if possible, if a symbolic device is not supplied. The hierarchy by which the file name is constructed by
RMS is as follows:
1.

File name (symbolic device)

Default File name (VAX RPG II file name)

Related file name (DAT file type)

The related file name can be overridden by supplying a different file type for the
symbolic device.
- Column 68 (Share) - VAX RPG II requires you to specify S to open a file for shared
access. PDP-ll RPG II requires you to use the MULTIUSER qualifier with
RPGASN.
• Input specification CD
- Column 43 (Data format)-When loading an execution-time array from an Input
specification that is in packed decimal or binary format, VAX RPG II requires P
(packed decimal) or B (binary) in column 43 of the Input specification. PDP-ll RPG
II requires P (packed decimal) or B (binary) in column 43 on the Extension specification .
• Calculation specification (C)
- A READ operation code on a file that has not been opened because it was conditioned by an external indicator that was off sets on the end-of-file indicator if one is
specified. In this case, PDP-ll RPG II does not set on the end-of-file indicator.
- VAX RPG II MOVE and MOVEL semantics are not exactly the same as those of
PDP-ll RPG II, when the Result field is numeric. The differences are the following:
• VAX RPG II does not perform the "spurious sign" and "sign ignored" cases of
PDP-ll RPG II.
• When the sending field is a character field, VAX RPG II converts the characters in
the sending field in the following manner:
- All valid overpunched decimal characters are converted to the sign and digit
they represent.
- All other characters are converted to a positive zero (+ 0).
• If a READ operation is done before a SETLL operation, VAX RPG II will read the

record with the lowest key. PDP-ll RPG II reads a record containing blanks in
this case.

Differences Between VAX RPG II and PDP-ll RPG II

B-3

• PDP-ll RPG II does not issue any error when the DSPLY operation code is used
with a field that is larger than the File record length. VAX RPG II issues an error
in this case .
• VAX RPG II will display (DSPLY operation code) the sign of a negative numeric .
• Output Specification (0)
- Columns 17 and 18 (Space) - PDP-ll RPG II assumes a single Space after if the
entries in columns 17 and 18 are left blank or are zero. VAX RPG II assumes a single Space after only if all entries in columns 17 through 22 are left blank. Making
an entry of zero in columns 17 and 18 allows overprinting .
• General
- ALTSEQ records - VAX RPG II uses hexadecimal representation to specify the
entries in ALTSEQ records. PDP-ll RPG II uses octal representation.
- Tables - For VAX RPG II, a reference to a table before the first LOKUP operation
will locate the first element in the table. PDP-ll RPG II returns a blank.
- VAX RPG II and PDP-ll RPG II support two-word (4-byte) binary data. PDP-ll
RPG II places the words in reverse order to what is required by VAX architecture.
PDP-ll RPG II data files that include two-word (4-byte) binary data will require
conversion to be used by VAX RPG II.
- VAX RPG II uses the logical name RPG$UDATE to specify UDATE and uses the
logical name RPG$EXT_INDS to specify the settings for external indicators.
- PDP-ll RPG II treats blanks in a numeric field in overpunched decimal format
as zeros. VAX RPG II does the same when you use the
CHECK = BLANKS-.lN_NUMERICS qualifier with the RPG command.
- VAX architecture reports a reserved operand fault when invalid data is found in a
numeric field. In VAX RPG II, this causes a run-time error. PDP-ll RPG II
processes invalid numeric data without halting program execution.
- PDP-ll RPG II's run-time system changes the name ofthe process to the program
name while the program is running. VAX RPG II will not do this.

B-4

Differences Between VAX RPG II and PDP-ll RPG II

- When compiling with RPG [FOO]TEST.RPG, PDP-ll RPG II places the .OBJ,
.LST, .CMD, and .ODL files in the [FOO] directory, no matter what the current
default directory is.
VAX RPG II places the .OBJ and .LIS files into the default directory in a manner
similar to other VAX languages. This VAX RPG II operation is similar to the following PDP-ll command lines:
MCR PDPRPG
RPG>TEST=[FOOlTEST.RPG
RPG>CTRL/Z

The above commands cause PDP-ll RPG II to place the files in the current default
directory.
Use the following command to simulate the PDP-ll RPG II operation:
$

RPG [FOOlTEST/LIS/OBJ

- NOLIST is the default for invoking the VAX RPG II compiler interactively. PDP-II
RPG II produces a listing file by default.
Note that RPGDMP is not provided with VAX RPG II. A similar functionality is provided
with the VMS utilities DUMP and SORT/MERGE. See the VAXIVMS DeL Dictionary for
information on DUMP and SORT/MERGE. See the VAXIVMS Utilities Reference Volume
for information on the three SORT qualifiers CONDITION, FIELD, and INCLUDE.
VAX RPG II supports the following additional functionality:
• Control Specification (H)
- A Control specification (H) is not required.
- Column 18 (Currency symbol) - You can specify the character to represent the currency symbol.
- Column 21 (Inverted print) - An entry ofI, D, or J switches the function of decimal
point and comma notation in numeric literals and edited formats, and changes the
format ofUDATE to day, month, and year (ddmmyy) .
• File Specification (F)
- Columns 7 through 14 (File name) - File names can be up to eight characters.
- Column 16 (File designation) - VAX RPG II does not require a primary file.
- Column 19 (File format) - You can specify V to indicate that the file contains variable-length records.
- Columns 24 through 27 (Record length) - VAX RPG II allows all files, with the
exception of display files, to have a record length of up to 9999 characters.

Differences Between VAX RPG II and PDP-ll RPG II

B-5

• Extension Specification (E)
- The definition of compile-time tables and arrays can be mixed with the definition of
execution-time and pre-execution-time tables and arrays.
• Input Specification (I)
- Columns 15 and 16 (Sequence) - You can specify input records with an alphabetic
sequence before or after input records with a numeric sequence.
- Columns 19 and 20 (Record-identifying indicator) - You do not have to specify lookahead fields as the last record in a file.
• Calculation Specification (C)
- Columns 28 through 32 (Operation) - The following operations have been added to
allow VAX RPG II programs to call subprograms written in other languages, routines in the VAX Common Run-Time Library, and system services:
• CALL - Calls a subprogram with optional parameters
• PARM - Passes a parameter by reference
• PARMD - Passes a parameter by descriptor
• PARMV - Passes a parameter by value
• GIVNG - Returns the status of a subprogram
• EXTRN -Equates a VAX RPG II name with an external link-time constant
• PLIST - Defines a parameter list
- Columns 28 through 32 (Operation) - VAX RPG II allows Factor 2 and the Result
field to reference the same array on a MOVEA operation.
- Columns 49 through 52 (Field definition) - You do not have to define fields before
they are used, as long as they are defined within the program.
• Output Specification (0)
- Columns 16 through 18 (ADD/DEL) - You can specify the DEL option to identify
the record to be deleted. You can delete records from indexed or direct files.
- Columns 45 through 70 (Edit word) - The number of replaceable characters in the
Edit word can be greater than or equal to the number of digits in the numeric field.

Differences Between VAX RPG II and PDP-ll RPG II

• General
- The string containing double slashes (1/) and a blank and the string containing a
double asterisk (**) and a blank are accepted as delimiters between specifications
and any ALTSEQ records, and between compile-time tables and arrays.
- The special words, *IN and *INxx, can be used to reference indicators as one-position character fields.
- A user-defined name can contain a pound sign (#) and an underscore (_).
- A character field can have a length of up to 9999 characters.
The VAX RPG II editor does not support the following PDP-ll RPG II features:
• Editing ofSORT-ll specifications
• VT05 or VT52 terminals
• Hardcopy terminals
• The following qualifiers:
-IDENT
- PAGE and NOPAGE
- SAVE and NOSAVE
- TERMINAL
• CTRLID
• SET SKIP command
• Automatically advancing the cursor to the next tab stop if the current field is full
• Displaying a tab stop as data from an input file as the TAB character
• Renaming the input file with a BAK file type

Differences Between VAX RPG II and PDP-ll RPG II

B-7

Appendix C

peA Applied to an RPG II Program
The following command procedure produces execution information by source line:
$ rpg/debug/nolist ships
$ link/debug=sys$library:pca$obJ.obJ/noMap ships
$ run ships
set datafile ships
set counters prograM_address by line
go
$ pca ships
tabulate/counters/source Module ships by line
file pcaolis
exit
$ t}'pe pca.lis
VAX PerforMance and Coverage Analyzer

Page 1

Exact Execution Counts (164 data points total)
Percent
SHIPS\

Count

Line
1:
2:
3:
4:
5:
6:

H*++
H* FUNCTIONAL DESCRIPTION:
H*
This prograM produces a report of shiPMents f
H*
products broken down by division and departMe
H*
input file with the shiPMent data for the pas
H*--

0.6'X,

0.61.,

FSHIPS
FSUMREP

12.2'X.

24.41.,
24.4'X,

40
40

4.3%
4.3%

7
7

2.41.,

10:
11 :
12 :
13 :
14:
15 :
16:

17:
18:
18:

20:
21:
22:
23:
24:

LSUMREP
ISHIPS

IP
0

F
F

41
88
OTY

DISK
LPRINTER
4 2 0

55FL 500L
AA 01

6
8
17

XFOOTOTY
PROOTY
PROOTY
ADD DEPOTY
DEPOTY
C* (Ll b re aI, on DEPT / L2 break on DIV)
DI I,lOTY
CLl
DEPOTY
ADD DIVOTY
CLl
Z-ADDO
DEPOTY
CL2
DIVOTY
ADD FINOTY
FINOTY
C*
C
C

C-I

5 DIV
7 DEPT
16 PROD
24 OTY
30
30
30
40

0.6i:'.

o .6i:'.
0.6i:'.
0.6·X,

12.2%

25:
26:
27:
2B:
29:
30:
31:
32:
33:
311:
35:
36:
37:
3B:
39:
1I0:
1I1:
1I2:
1I3:
1I11:

1I.3i:'.
2.1Ii:'.

7
1I

2.1Ii:'.

liS:

2.1Ii:'.

1I6:
1I7:
liB:

0.6i:'.

1I9:
50:
51:
52:

53:

C-2

OSUMREP
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

peA Applied to an RPG II Program

001

1P
liB 'PRODUCT SHI

H 02

1P
UDATE Y

12
liB 'PRODUCT SHI

1P
1I2 'SHIPMENTS'

1P
15 'DIVISION D
211 'PRODUCT'
liB '01 02 03

01
L2
L1

T
T

T 02

DIV
DEPT
PROD
OTY
Z
PROOTYZ

B
111
25
1I1
liB

DIV

DIVOTYZB

liB
63
69

DIV
T

/ <= = Total

LR
FINOTY1

liB
65 1<: = = GRAND T

Master Index
The Programming in VAX RPG II manual is comprised of two parts. References to Part I,
which contains programming information, are preceded by a I. References to Part II, which
contains language reference information, are preceded by a II.
A
Access mechanism, I 9-23
ADD operation code, II 3-2
example, II 3-4
ADD option, II 2-95
example, II 2-95
rules for specifying, II 2-95
Adding records, I 5-22
Addition operation, II 3-2
Additional 110 area, II 2-28
rules for specifying, II 2-28
ADDROUT files
creating, I 5-14
example, I 5-15,5-17
function, I 5-14
rules for specifying, I 5-16
specifying
Key length, II 2-27
ADVANCE function, I 3-20
Alternate array, II 2-45
Alternate collating sequence, II 2-13 to 2-14
specifying
example, II 2-14
Alternate format
arrays, I 8-8
compile-time, I 8-8
example, I 8-9
pre-execution-time, I 8-8
related, I 8-8
Alternate table, II 2-45
AND, II 2-61,2-91
example, II 2-62
Output specification
example, II 2-92
rules for specifying, II 2-61,2-91
Arguments
optional, I 9-15
Arithmetic operation codes, II 3-1
ADD,II3-2
blank Factor 1, II 3-2
DlV, II 3-3
blank Factor 1, II 3-3
example, II 3-4

Arithmetic operation codes, (Cont.)
MULT, II 3-3
blank Factor 1, II 3-3
MVR, II 3-3
rules, II 3-1
signs, II 3-2
SQRT, II 3-4
SUB, II 3-3
blank Factor 1, II 3-3
XFOOT, II 3-4
Z-ADD, II 3-2
Z-SUB, II 3-3
Array elements
outputting, I 8-21
referencing, I 8-15
searching, I 8-17
XFOOT operation code, I 8-15
Arrays, I 8-1
addition operation, II 3-4
alternate format, I 8-8, II 2-45
compile-time, I 8-2
example, I 8-3
creating, I 8-4
array input records, I 8-4
definition, I 8-1
execution-time, I 8-4
in calculations, I 8-10
example, I 8-11
*IN indicators, I 4-19
*IN,n indicators, 14-19
input records
example, I 8-4
loading time
selecting, I 8-1
LOKUP operation code, I 8-15, II 3-24
example, I 8-16
MOVEA operation code, I 8-18
example, I 8-19
moving data, I 8-18, II 3-6
example, I 8-19
names, II 1-7
outputting
array elements, I 8-21
example, I 8-21

Arrays, outputting (Cont.)
entire arrays, I 8-20
pre-execution-time, I 8--4
referencing, 18-10
array elements, I 8-10
example, I 8-15
entire arrays, I 8-10
related, I 8-5
resulting indicators, I 8-16
searching, I 8-15, II 3-24
example, I 8-16, II 3-25
searching for elements, I 8-17
specifying, I 8-5, II 2-18
alternate format, II 2--45
Data format, II 2--44
Decimal positions, II 2--44
elements, I 8-12
From file name, II 2--40
Length of entry, II 2--43
names, II 2-41
Number of entries per record, II 2--42
Number of entries per table or array, II
2--42
Sequence, II 2--45
To file name, II 2--40
transferring data, II 3-6
types
compile-time, I 8-2
execution-time, I 8--4
pre-execution-time, I 8--4
updating, I 8-19
example, I 8-20
using, 18-1
writing
array elements, I 8-21
example,l8-21
entire arrays, I 8-20
XFOOT operation code, II 3--4
example, I 8-14
ASCII character set, II A-I
Asterisk protection, II 2-113
Automatic overflow, I 6-13

B
BACKUP function, I 3-21
BEGSR operation code, II 3-10
example, II 3-10
rules, II 3-10
Binary data types
longword, II 1-3
specifying, II 2-44
word,III-3
Bit operation codes, II 3-11
BITOF, II 3-12
BITON,lI3-11
example, II 3-12

Master Index

Bit operation codes, (Cont.)
TESTB, II 3-12
BITOF operation code, II 3-12
example, II 3-12
rules, II 3-12
BITON operation code, II 3-11
example, II 3-12
rules, II 3-11
Bits
setting off, II 3-12
setting on, II 3-11
testing, II 3-12
Blank after, II 2-106
example, II 2-107
rules for specifying, II 2-106
blank Factor 1
example, II 3--4
Block length, II 2-21
rules for specifying, II 2-22
BOTTOM function, I 3-21
Branching operation codes, II
3-20
example, II 3-22
GOTO, II 3-20
TAG,II3-21
BS_KEY
example, I 3-56
Buffers, I 3-9

c
Calculation specification, II 2-79
Comments, II 2-90
Control-level indicators, II 2-80
Decimal positions, II 2-87
Factor 1, II 2-84
Factor 2, II 2-84
Field length, II 2-87
format, II 2-79
Half adjust, II 2-88
Indicators, II 2-82
long character literal, II 2-84
operation codes, II 2-86,3-1
Result field, II 2-86
Resulting indicators, II 2-88
Type,lI2-79
Calculations
arrays,l8-10
documenting, II 2-90
operations
addition, II 3-2
division, II 3-3
multiplication, II 3-3
square root, II 3--4
subtraction, II 3-3
referencing
array elements, I 8-10

Calculations, referencing (Cont.)
entire arrays, I 8-10
Result field, II 2-86
rounding data, II 2-88
saving the remainder, II 3-3
specifying
Decimal positions, II 2-87
Factor 1, II 2-84
Factor 2, II 2-84
Field length, II 2-87
operation codes, II 2-86
Resulting indicators, II 2-88
totalling data, I 4-15
using indicators, II 2-82
control-level, I 4-9
resulting, I 4-6
Call interface, I 9-1
subprograms, I 9-32
system services, I 9-28
CALL operation code, II 3-25
example, II 3-30
rules, II 3-25
Calling
RTL procedures, II 3-25
subprograms, II 3-25
system services, II 3-25
Card reader device
specifying, II 2-30
CHAIN operation code, II 3-14
example, II 3-15
indicator for locked record, II 3-14
reading records, II 3-14
rules, II 3-14
Chained files
input
selecting Mode of processing, II 2-25
logic cycle, 11-18
flowchart, I 1-18
update
selecting Mode of processing, II 2-25
Character
see record identification codes
Character data type
example, II 1-2
CHARACTER function, I 3-26
Character sets
ASCII, II A-I
Decimal, II A-I
EBCDIC, II A-I
Hexadecimal, II A-I
CHECK qualifier, I 2-4
checking
array boundaries, I 2-5
blanks in numeric fields, I 2-5
recursive calls to subroutines, I 2-5
format, I 2-4
options, I 2-4
BLANKSjN~UMERICS, I 2-5

CHECK qualifier, options (Cont.)
BOUNDS, I 2-5
RECURSION, I 2-5
Collating sequences, II 2-14
Alternate, II 2-13
ASCII, II 2-13
EBCDIC, II 2-13
specifying
example, II 2-14
COLUMN function, I 3-26
80-column ruler, I 3-5
definition, I 3-7
COMMAND function, I 3-18
example, I 3-71
Command line
conditions, I 3-29
COMMAND qualifier, I 3-2
Commands
DCL, I 2-1
debugger, I 10-3
RPG II editor, I 3-18
commands
RUN,I2-9
Comments, II 2-5, 2-90
rules for specifying, II 2-5
COMP operation code, II 3-13
example, II 3-14
rules, II 3-13
Compare operation codes
COMP,II3-13
Compile-time arrays, I 8-2
advantages, I 8-2
creating, I 8-4, 8-6
example, I 8-6
rules for specifying, I 8-4
example, I 8-3
outputting, I 8-20
updating, I 8-19
writing, I 8-20
Compile-time tables, I 7-2
advantage, I 7-2
example, I 7-2
input records
creating,I 7-3
rules for specifying, I 7-3
outputting, I 7-12
rules for defining, I 7-6
searching
example, I 7-8
writing,I 7-12
Compiler error messages, I 2-9
format, I 2-9
IDENT field, I 2-9
interpreting, I 2-9
Compiler listing, I 11-1
command qualifiers, I 11-2
copy directive,I 11-1

Master Index

Compiler listing, (Cont.)
cross-reference information
CROSS-REFERENCE qualifier, 111-1
indicators, 111-2
user-defined names, 111-1
example,I11-3
identification, 111-1
interpreting, 111-1
machine-generated code, 111-1
MACHINE_CODE qualifier, 111-1
PSECTs,111-2
source code, I 11-1
statistical information, 111-2
Compiler options
default,12-2
example, 12-2
Compiling programs, I 2-1
example, 12-2
generating an object module, 12-1
specifying more than one
program, 12-1
Condition values
returned, 19-20
signaled, 19-20
Constants, II 2-111
rules for specifying, ll2-112
Control breaks
identifying, 14-8
split-control fields, I 4-11
Control specification, ll2-11
Alternate collating sequence, ll2-13
Currency symbol, 112-12
example, 112-15
format, ll2-12
Forms position, ll2-15
Inverted print, ll2-12
Type,!12-12
Control-level indicators, I 4-8, ll2-71, 2-80
conditioning data, ll2-71
control breaks, I 4-9
example, 14-10, ll2-73, 2-81
function, I 4-8
hierarchy, I 4-8
identifying control breaks, I 4-8
rules for specifying, ll2-72
signaling changes in control fields, I 4-8
split-control fields, I 4-11
Copy from CDD,ll2-7
COPY qualifier, II 2-7
Core index, ll2-31
rules for specifying, ll2-32
CREATE qualifier, I 3-3
CROSS-REFERENCE qualifier, I 2-5
cross referencing
indicators, 12-5
user-defined fields, I 2-5
format, I 2-5

CROSS-REFERENCE qualifier, (Cont.)
generating cross-reference information,
111-1
CTRL~J(EY

example, I 3-65
Currency symbol, ll2-12
rules for specifying, ll2-12
Cursor, 13-8
CUT function, I 3-21
example, 13-74
CZDportion
see record identification codes

D
Data
comparing contents, ll3-13
displaying, ll3-16
moving, ll3-5
moving from the left, ll3-6
repeating,! 6-7
transferring, ll3-5
Data formats
binary, ll2-44
Extension specification, ll2-44
Input specification, ll2-62
Output specification, ll2-109
example, ll2-109
overpunched decimal, ll2-44
packed decimal, II 2-44
Data structure, ll2-50
Data structure subfield, ll2-53
Data structures, II 2-52
examples of using, ll2-66 to 2-68
local data area, ll2-55
examples, II 2-69
updating files, I 5-26
Data types, lll-l
binary, lll-3
character, lll-2
overpunched decimal, lll-4
packed decimal, lll-3
specifying, ll2-44
Date
formatting, I 6-3
printing, I 6-3
DCL commands
RPG,I2-1
DCL RPG command, I 2-1
default compiler options, I 2-2
qualifiers
example, I 2-3 to 2-4
DEBUG qualifier, I 2-6, 10-1
format, I 2-6
options, 12-6
SYMBOLS, I 2-6
TRACEBACK, I 2-6
/

Master Index

DEBUG qualifier, (Cont.)
providing
an address correlation table, I 2-6
information for the VAX Symbolic
Debugger, I 2-6
local symbol definitions, I 2-6
DEBUG qualifiers
ALL,110-1
NONE,I10-1
SYMBOLS, I 10-1
TRACEBACK, I 10-1
Debugger commands
CANCEL BREAK, I 10-6
CANCEL TRACE, 110-7
CANCEL WATCH, 110-9
CTRLIY, 110-12
DEPOSIT, 110-14
EDIT, 110-12
EVALUATE, 110-15
EXAMINE, I 10-13
EXIT, 110-12
GO,I1O-1O
SET,110-7
stepping through a TAG, I 10-7
stepping through subroutines, I 10-7
SET BREAK, I 10-6
SET LANGUAGE, 110-4
SET STEP, 110-11
SET TRACE, I 10-7
SET WATCH, 110-9
SHOW BREAK, I 10-6
SHOW CALLS, 110-10
SHOW LANGUAGE, I 10-4
SHOW TRACE, 110-7
SHOW WATCH, 110-9
STEP, I 10-10
qualifiers
INTO, I 10-10
LINE, I 10-10
OVER,I10-1O
SOURCE,I10-1O
SYSTEM,I1O-1O
TYPE, I 10-11
Debugging RPG II programs, 110-1
debugger commands
table, I 10-3
*DETC logic cycle label, I 10-5
*DETL logic cycle label, I 10-5
displaying source code, I 10-11
edit the file you are debugging, 110-12
evaluating expressions, I 10-15
examining
array elements, I 10-6
contents of
array elements, I 10-13
I/O buffers, I 10-13
table entries, I 10-13
variables, 110-13

Debugging RPG II programs,
examining (Cont.)
data, I 10-6
locations, 110-13
table entries, I 10-6
executing program lines, 110-10
*GETIN logic cycle label, I 10-5
leaving the debugger, 110-12
modifying
array elements, 110-6,10-14
data, I 10-6
locations, I 10-13
table entries, I 10-6
variables, 110-14
*OFL logic cycle label, I 10-5
referencing
array elements, I 10-6
data, I 10-6
line numbers, I 10-3
logic cycle labels, I 10-5
table entries, I 10-6
resuming program execution, I 10-10
returning to system command level,
110-12
setting
breakpoints, I 10-6
indicators, 110-14
tracepoints, I 10-7
watchpoints, I 10-9
subprograms, I 10-10
suspending program execution, I 10-7
table entries, I 10-14
*TOTC logic cycle label, I 10-5
*TOTL logic cycle label, I 10-5
tracing calls, I 10-10
Decimal character set, II A-I
Decimal positions, II 2-44, 2-64, 2-87
rules for specifying, II 2-44,2-64,2-87
Default compiler options, I 2-2
DEL option, II 2-95
example, II 2-96
rules for specifying, II 2-95
DELETE TO END OF LINE function, I 3-25
DELETE_CHARACTER Function, I 3-28
DELETEJ'IELD function, I 3-20
DELETEJ.INE function, I 3-17
DELETE_TOjJEGINNING_OFJ.INE
function, I 3-29
DELETE_TOJ;ND_OF _LINE function
example, I 3-25
Deleted-field buffer, I 3-9
Deleted-line buffer, I 3-9
Demand files
logic cycle, I 1-18
flowchart, I 1-18
READ operation code, II 3-19
selecting Mode of processing, II 2-24

Master Index

Detail time, I 1-2
processing individual records, I 1-5
Developing programs
creating
example, I 3-54
generating a listing file, I 11-1
Device codes, II 2-30
rules for specifying, II 2-30
specifying
card reader, II 2-30
disk, II 2-30
magnetic tape, II 2-30
printer, II 2-30
terminal, II 2-30
Direct file organization, I 5-3
example, I 5-3
Direct files
adding records, I 5-24
example, I 5-24 to 5-25
rules for specifying, I 5-24
creating, I 5-20
example, I 5-21
rules for specifying, I 5-20
updating records
rules for specifying, I 5-27
Disk device
specifying, II 2-30
DISPLAY function, I 3-19
example, I 3-62
DIV operation code, II 3-3
example, II 3-4
Division operation, II 3-3
saving the remainder, II 3-3
DOWN function, I 3-28
DSPLY operation code, II 3-16
displaying data, II 3-16
example, II 3-17
rules, II 3-16

E
EBCDIC character set, II A-I
Edit code modifiers, II 2-110
asterisk fill, I 6-2
example, II 2-111
floating dollar sign, I 6-2
rules for specifying, II 2-110
Edit codes, II 2-104
combined, I 6-1
constants
example, I 6-2
rules for specifying, I 6-2
example, II 2-106
modifiers, I 6-2
printer output files, I 6-1
rules for specifying, II 2-105
simple, I 6-1

Master Index

Edit codes, (Cont.)
specifying
notation, II 2-12
Edit words, II 2-112
body, II 2-112
example, II 2-114
expansion, II 2-112
rules for specifying, II 2-117
sign status, II 2-112
specifying
asterisk protection, II 2-113
blank spaces, II 2-114
commas, II 2-115
CR,1I2-116
currency symbol, II 2-114
decimal points, II 2-115
negative signs, II 2-116
zero suppression, II 2-113
editing buffer, I 3-9
editing window, I 3-5
Editor
seeRPG II
End position, II 2-107
example, II 2-108
rules for specifying, II 2-107
End-of-file, II 2-19
rules for specifying, II 2-20
END_OF.-LINE function, I 3-24
example, I 3-24
ENDSR operation code, II 3-10
example, II 3-10
rules, II 3-10
ENTER function, I 3-26
ENTER key
example, I 3-67
EOB mark, I 3-7
Error messages
compiler, I 2-9
IDENT field values, I 2-10
Errors
handling, I 4-17
halt indicators, I 4-17
EXCPT
names, II 1-7
EXCPT name, II 2-103
EXCPT operation code, II 3-17
writing records during
calculations, II 3-17
Execution-time arrays, I 8-4
creating, I 8-4,8-7
example, I 8-8
rules for specifying, I 8-4
loading
example, I 8-8, 8-13
outputting, I 8-20
example, I 8-21

Execution-time arrays, (Cont.)
specifying
array elements
example, I 8-13
entire arrays
example, I 8-13 to 8-14
writing, I 8-20
example, I 8-21
EXIT function, I 3-29
Expansion factor, II 2--33
improving search efficiency, II 2-33
preventing bucket splitting, II 2--33
table, II 2-34
EXSR operation code, II 3-10
example, II 3-10
rules, II 3-10
Extension code, II 2-29
Extension specification
Comments, II 2-46
Data format, II 2-44
Decimal positions, II 2-44
defining
arrays, II 2--38
record-address files, II 2-38
tables, II 2--38
example, II 2-46
format, II 2--39
From file name, II 2-40
Length of entry, II 2-43
name of record-address file, II 2-40
name of table input file, II 2-40
Number of entries per record, II 2-42
Number of entries per table or array,
II 2-42
Sequence, II 2-45
Table or array name, II 2-41
To file name, II 2-40
Type, II 2-40
External indicators, I 4-16
controlling the opening of files, I 4-16
example, I 4-16,9--30
function, I 4-16
setting, I 4-16
specifying,l4-16
EXTRN operation code, II 3-26 .
accessing
link-time constants, II 3-26
RTL status codes, 113-26
example, II 3--30
RTL procedures, II 3-26
rules, II 3-26

F
Factor 1, II 2--84
Factor 2, II 2--84
Fetch overflow, I 6-11, II 2-96

Fetch overflow, (Cont.)
example, I 6-12, II 2-97
rules for specifying, I 6-11, II 2-96
FIELD function, I 3-23
example, I 3-23
Field indicators, I 4-4
checking the condition of data
fields, II 2-78
conditioning input data, II 2-78
example, I 4-5
function, 14-4
rules for specifying, II 2-78
Field length, II 2--87
rules for specifying, II 2-87
Field locations, II 2-63
rules for specifying, II 2-63
Field name, II 2-64, 2-102
Input specification, II 2-64
example, II 2-65
rules for specifying, II 2-64
Output specification, II 2-102
example, II 2-103
rules for specifying, II 2-102
Field names, II 1-6
Field-record-relation indicators, II 2-75
conditioning input data, II 2-75
controlling data extraction, II 2-75
example, II 2-77
rules for specifying, II 2-76
using matching fields, I 5--31
example, I 5--31 to 5-33
FIELDj3ACKWARD function, I 3-28
example, I 3-56
FLELDYORWARD function, I 3-29
Fields
common, II 2-4
defining locations, II 2-63
indicators, 14-4
input
specifying
Decimal positions, II 2-64
look-ahead, II 2-57
matching, I 5-29, II 2-73
checking sequence, II 2-20
naming, II 2-64
repeating, I 6-7
specifying
Data format, II 2-62
IN,II2-64
IN ,xx, II 2-64
length, II 2--87
PAGE special word, II 2-64
split-control, I 4-11
testing values, 14-4
that require
blanks, II 2--3
character values, II 2-3
numeric values, II 2-3

Master Index

Fields (Cont.)
using indicators to compare
contents, 112-71
File access methods
random, 15-11
sequential, I 5--6
sequential by key, I 5-7
sequential within limits, I 5-8
table, 15-5
File addition, II 2-32
rules for specifying, II 2-33
File condition, 112-37
File Description specification, II 2-16
Additional 110 area, II 2-28
Block length, II 2-21
Core index, II 2-31
Device code, II 2-30
End-of-file, II 2-19
example, II 2-38
Expansion factor, II 2-33
Extension code, II 2-29
File addition, II 2-32
File condition, II 2-37
File designation, II 2-18
File format, II 2-21
File name, II 2-17
File organization, II 2-28
File sharing, II 2-35
File type, II 2-17
format,II 2-16
Key length, II 2-27
Key location, II 2-29
Mode of processing, II 2-23
Overflow indicators, II 2-29
Record address type, II 2-28
Record length, II 2-22
Sequence, II 2-20
Symbolic device, II 2-31
Tape label, II 2-31
Tape rewind, II 2-37
Type, II 2-16
Unordered output, II 2-32
File designations, II 2-18
array, II 2-18
chained, II 2-18
demand, II 2-18
full-procedural, II 2-18
primary, II 2-18
record-address, II 2-18
secondary, II 2-18
table,I12-18
File format, II 2-21
rules for specifying, II 2-21
File names, II 1--6
File Description specification, II 2-17
rules for specifying, II 2-17
Input specification, II 2-51
rules for specifying, II 2-51

File names, (Cont.)
Line Counter specification, II 2-48
rules for specifying, II 2-48
Output specification, II 2-91
rules for specifying, II 2-91
rules for specifying, 15-1
File organizations, II 2-28
direct, I 5-3
indexed, I 5-4
sequential, I 5-2
File sharing, II 2-35
rules for specifying, II 2-35
File types, II 2-17
display, II 2-17
input, 15-2, II 2-17
output, I 5-2, II 2-17
update, 15-2, II 2-17
Files
adding records, I 5-23
ADDROUT,15-14
specifying
Key length, II 2-27
CHAIN operation code, II 3-14
changing processing order,
II 3-18
compiler listing, 111-1
conditioning with an external
indicator, II 2-37
creating, I 5-20
ADDROUT,15-15
direct, I 5-20
indexed,I5-21
output, 16-1
printer output, 16-1
record-limits, 15-8
sequential,15-20
definition, 15-1
deleting records, I 5-28
DSPLY operation code, II 3-16
EXCPT operation code, 113-17
external indicators, 14-16
file access methods, I 5-5
file names, 15-1
file types, I 5-2
FORCE operation code, II 3-18
full-procedural,15-18
example, 15-19
improving search efficiency, II 2-33
indexed
specifying
Key length, II 2-27
input
specifying
File addition, II 2-32
Unordered output, II 2-32
input/output operation codes, II 3-14
matching-record indicators, 14-16
multifile processing, I 5-29
I

Master Index

',,-

Files (Cont.)
organization, 1 5-2
output, 1 6-1
controlling overflow, II 2-29
using overflow indicators, II 2-29
preventing bucket splitting, II 2-33
printer output, 1 6-1
controlling overflow, II 2-29
using overflow indicators, II 2-29
processing using matching
fields, II 2-73
random access, 1 5-11
random access by key, 1 5-18
READ operation code, II 3-19
reading record during
calculations, II 3-14
record formats, 1 5-2
record-limits, 1 5-8
specifying
Key length, II 2-27
sequential access, 1 5-6,5-18
sequential by key access, 1 5-7
sequential within limits access, 1 5-8
SETLL operation code, II 3-19
specifying
chained, II 2-18
demand, II 2-18
display, II 2-17
full-procedural, II 2-18
input, II 2-17
Mode of processing, II 2-23
output, II 2-17
primary, II 2-18
record-address, II 2-18
secondary, II 2-18
update, II 2-17
update
specifying
File addition, II 2-33
Unordered output, II 2-33
updating records, 1 5-26
FIND function, 1 3-17
example, 1 3-67
FIND_NEXT function, 1 3-16
example, 1 3-69
First-page indicators, 1 4-14,6-8
conditioning output data, 1 4-14
example, 14-14,6-9
function, 14-14
specifying, 1 4-14
FL,II2-49
FMS, 1 9-33 to 9-34
FORCE operation code, II 3-18
changing file processing order, II 3-18
example, II 3-18
rules, II 3-18
selecting files, II 3-18
Form length, II 2-49
FL,II2-49

Form length, (Cont.)
rules for specifying, II 2-49
Forms alignment
changing, II 2-15
Forms position, II 2-15
From file name, II 2-40
arrays, II 2-40
record-address files, II 2-40
rules for specifying, II 2-40
tables, II 2-40
Function
SHIFLRIGHT, 1 3-22
Function calls
for system routines, 1 9-15
Functions, 1 3-9 to 3-10
see RPG II editor
ADVANCE, 1 3-20
BACKUP, 1 3-21
BOTTOM, 1 3-21
CHARACTER, 1 3-26
COLUMN, 1 3-26
COMMAND, 1 3-18
CUT,! 3-21
DELETE_CHARACTER,/3-28
DELETE_FIELD, 1 3-20
DELETE_LINE, 1 3-17
DELETE_TO_BEGINNING_OF _LINE,
13-29
DELETE_TO_END_OF _LINE, 1 3-25
DISPLAY, 1 3-19
displaying specification
formats, 1 3-14
DOWN,/3-28
END_OF_LINE, 1 3-24
ENTER, 1 3-26
executing editor commands, 1 3-18
EXIT, 1 3-29
FIELD,! 3-23
FIELD_BACKWARD, 1 3-28
FIELD_FORWARD, 1 3-29
FIND,! 3-17
specifying the search string, 13-17
FIND_NEXT,/3-16
finding the next occurrence of the search
string,! 3-16
GOLD,! 3-12
HELP _KEYPAD,/3-13
HELP _SPECIFICATIONS, 1 3-14
LEFT,/3-28
LINE,! 3-27
MOVE_TO~ULER, 1 3-20
NEWJ,INE, 1 3-28
OPEN_LINE, 1 3-27
PAGE,/3-18
paging through the source file, 1 3-18
PASTE, 1 3-21
REFRESH_SCREEN,/3-29
RESET, 1 3-27

Master Index

Functions, (Cont.)
REVIEW_ERROR, I 3-19
RIGHT, I 3-28
SECTION,! 3-19
SELECT, I 3-27
selecting alternate functions, I 3-12
SHIFT_LEFT, I 3-22
table, I 3-10
TOP, I 3-21
UNDELETEJ'IELD, I 3-20
UNDELETE_LINE, I 3-17
UP, I 3-27

G
GIVNG operation code, II 3-26
retrieving RTL return status, II 3-26
rules, II 3-26
GOLD function, I 3-12
GOTO operation code, II 3-20
example, II 3-22
rules, II 3-21

H
Half adjust, II 2-88
rules for specifying, II 2-88
using resulting indicators, II 3-26
Halt indicators, I 4-17
controlling program execution, I 4-17
example, 14-17 to 4-18
function, I 4-17
handling errors, I 4-17
Help window, I 3-5
definition, I 3-6
displaying help information, I 3-6
HELP j{EYPAD function, I 3-13
displaying help information on
key functions, I 3-14
example, I 3-14
HELP_SPECIFICATIONS function, I 3-14
displaying specification formats
example, I 3-15
HELP_SPECS function
example, I 3-54
Hexadecimal character set, II A-I

I/O areas
specifying
additional areas, II 2-28
IDENT field
values, I 2-10
*IN indicators, I 4-19
example, I 4-19

Master Index

*IN indicators, (Cont.)
function, 14-19
specifying arrays, I 4-19
*IN,n indicators, I 4-19
example,! 4-19
function, I 4-19
specifying array elements, I 4-19
Indexed file organization, I 5-4
example, I 5-4
index key, I 5-4
example, I 5-4
Indexed files
adding records, I 5-25
example, I 5-26
rules for specifying, I 5-25
creating, I 5-21
example, I 5-22
rules for specifyin~ I 5-21
specifying
addition of records, II 2-32
Key length, II 2-27
Key location, II 2-29
updating records
rules for specifying, I 5-27
Indicators,! 4-1
Calculation specification, II 2-82
example, II 2-83
conditioning
calculations, II 2-82
output, II 2-100
control-level, I 4-8, II 2-71,2-80
external, 14-16
field, 14-4, II 2-78
field-record-relation, II 2-75
first-page, I 4-14,6-8
function, I 4-1
halt, I 4-17 to 4-18
*IN,I4-19
*IN,n,! 4-19
internally defined, I 4-14
*INxx, 14-19
last-record, I 4-15
matching-record, 14-16
negating, II 2-82
Output specification
example,!I2-102
rules for specifying, II 2-100
overflow, 14-12,6-10, II 2-29
IP, I 4-14,6--8
printer output files, I 6-8
record-identifying, I 4-1, II 2-56
resulting, 14--6, II 2-88
setting off, II 3-9
setting on, II 3-9
usage,! 4-1
user-defined, I 4-1
using as fields, I 4-19

Input files
selecting Mode of processing, II 2-24
specifying
File addition, II 2-32
Unordered output, II 2-32
Input specification, II 2-50
AND,II2-61
Character, II 2-60
Control-level indicators, II 2-71
copy from CDD, II 2-7
copy modifiers, II 2-9
CZD portion, II 2-59
Data format, II 2-62
Data structure, II 2-50
Data structures, II 2-52
data structures
examples, II 2-66 to 2-68
Decimal positions, II 2-64
Field indicators, II 2-78
Field locations, II 2-63
Field name, II 2-64
Field-record-relation indicators, II 2-75
File name, II 2-51
format, II 2-51
identifying record types, II 2-56
Matching fields, II 2-73
Not, II 2-59
Number, II 2-56
Optional, II 2-56
OR,II2-61
Position, II 2-59
Record identification codes, II 2-58
Record-identifying indicators, II 2-56
Sequence, II 2-55
specifying
alphabetic sequence code, II 2-55
data formats, II 2-62
data structure statement, II 2-53
data structure subfield, II 2-53
filenames
example, II 2-52
input file names, II 2-51
look-ahead fields, II 2-57
numeric sequence code, II 2-55
record identification codes, II 2-58
sequence code, II 2-55
update file names, II 2-51
Type, II 2-51
Input/output operation codes, II 3-14
CHAIN, II 3-14
DSPLY, II 3-16
EXCPT, II 3-17
FORCE, II 3-18
READ, II 3-19
SETLL, II 3-19
Inverted print, II 2-12
*INxx indicators, I 4-19
example, I 4-20

*INxx indicators, (Cont.)
function, I 4-19
representing indicators, I 4--19

J
JOURNAL qualifier, I 3-3

K
K indicators, I 4-12
example,l4-12
Key length
ADDROUT files, II 2-27
example, II 2-27
Indexed files, II 2-27
Record-limits files, II 2-27
rules for specifying, II 2-27
Key location, II 2-29
rules for specifying, II 2-29
Keypad, I 3-9

L
Label names, II 1-7
Language elements, II 1-1
Last-record indicators, I 4-15
example, I 4-15
function,l4-15
totalling data, I 4-15
LEFT function, I 3-28
Length of entry, II 2-43
arrays, II 2-43
rules for specifying, II 2-43
tables, II 2-43
Line Counter specification, II 2-47
example, II 2-50
File name, II 2-48
FL,II2-49
Form length, II 2-49
format, II 2-48
naming the output file, II 2-48
OL,II2-50
Overflow line number, II 2-49
Type, II 2-48
LINE function, I 3-27
example, I 3-73
Line numbers, II 2-4
checking, I 2--8, II 2-4
Line relationships
AND,II2-61
OR,II2-61
LINK command, I 2--8
example, I 2-9
format, I 2-9
Linking programs, I 2-8

MasterIndex

LIST qualifier, 12-6
format, I 2-6
generating a listing file, I 2-6, 11-1
including cross-reference
information, I 2-6
including machine code, I 2-6
Listing file
generating, I 2-6
Local data area, II 2-55
examples, II 2-69
Logic cycle, 11-1
detail time, 11-2,1-5
flowchart, 11-6
general,l1-2
look -ahead processing, I 1-20
matching-fields routine, I 1-16
normal cycle,l1-3
overflow processing, I 1-19
processing chained and demand files,
11-18
steps of
a normal cycle, I 1-3
the first cycle, 11-2
the last cycle, I 1-3
the first cycle, I 1-2
the last cycle,l1-3
total time,l1-2, 1--4
LOKUP operation code, II 3-22
arrays,l8-15
example, I 8-16
example, II 3-24 to 3-25
referencing entries, I 7-10
searching
arrays, II 3-24
related tables, II 3-23
tables, I 7-7, II 3-23
specifying array elements, II 3-24
Long character literals, II 2-111
Longword binary data type example, II 1-3
Look-ahead fields, II 2-57
example, II 2-57
function, II 2-57
logic cycle, 11-20
flowchart, I 1-20
rules for specifying, II 2-58
LR indicators, I 4-15

M
MACHINE_CODE qualifier, I 2-7
format, I 2-7
generating machine code, I 2-7,11-1
Magnetic tape device
specifying, II 2-30
Magnetic tapes
rewinding, II 2-37

Master Index

Matching fields, II 2-73
checking record sequence, I 5-29, II 2-20
example,l5-30
for more than one record type, I 5-29
example, I 5-30
logic cycle, I 1-16
flowchart,l1-16
multifile processing, I 5-29, 5-33
example, I 5-34, 5-38
record selection, I 5-33
rules for specifying, I 5-34
rules for specifying, II 2-73
using as field-record-relation indicators,
15-31
example, I 5-31 to 5-33
Matching-record indicators, I 4-16
function, I 4-16
multifile processing, 14-16
Message line, I 3-5
definition, I 3-7
example, I 3-7
Mode of processing, II 2-23
example, II 2-26
loading a direct file, II 2-23
rules for specifying, II 2-23
selecting, II 2-24
specifying
access
random, II 2-23
sequential, II 2-23
sequential within limits, II 2-23
an ADDROUT file, II 2-23
Record address type, II 2-28
Modular Programming Standard, I 9-32
MOVE operation code, II 3-5
example, II 3-7
rules, II 3-5
Move operation codes, II 3-5
example, II 3-7
MOVE, II 3-5
MOVEA, II 3-6
MOVEL, II 3-6
MOVE_TO~ULER function, I 3-20
MOVEA operation code, II 3-6
arrays, I 8-18
example, I 8-19, II 3-7
rules, II 3-6
MOVEL operation code, II 3-6
example, II 3-7
rules, II 3-6
MULT operation code, II 3-3
example, II 3--4
Multifile processing, I 5-29
checking record sequence, I 5-29
example, I 5-30
for more than one record types, I 5-29
matching fields, I 5-30

Multifile processing, (CO NT.)
using
matching fields, I 5--29
matching-record indicators, I 4-16,5-29
MR indicators, I 5-29
mUltiple keys, I 5-41
Multiplication operation, II 3-3
MVR operation code, II 3-3
example, II 3-4
saving the remainder, II 3-3

N
Names
arrays, II 1-7
specifying, II 2-41
EXCPT, II 1-7
fields, II 1-6
files,IIl-6
labels, II 1-7
PLIST, II 1-7
subroutines, II 1-7
tables, II 1-7
specifying, II 2-41
user-defined, II 1-6
NEW-LINE function, I 3-28
Not
see record identification codes
Notations
Edit codes, II 2-12
numeric fields, II 2-12
UDATE, II 2-12
Number, II 2-56
rules for specifying, II 2-56
Number of entries per record, II 2-42
arrays, II 2-42
rules for specifying, II 2-42
tables, II 2-42
Number of entries per table or array, II 2-42
rules for specifying, II 2-43
Numeric data
specifying
format, II 2-109
Numeric fields
editing, II 2-112
example, II 2-4
rounding, II 2-88
specifying
notation, II 2-12
Numeric sequence code, II 2-56

o
OBJECT qualifier, I 2-7
format, I 2-7
generating an object module, I 2-7

OBJECT qualifier, (Cont.) rules, I 2-7
specifying an output file, I 2-7
OL, II 2-50
OPEN-LINE function, I 3-27
Operation codes, II 3-1
arithmetic, II 3-1
ADD, II 3-2
DIV, II 3-3
MULT, II 3-3
MVR,II3-3
SQRT, II 3-4
SUB, II 3-3
XFOOT, II 3-4
Z-ADD, II 3-2
Z-SUB, II 3-3
bit, II 3-11
BITOF, II 3-12
BITON, II 3-11
TESTB, II 3-12
branching, II 3-20
example, II 3-22
GOTO, II 3-20
TAG, II 3-21
compare, II 3-13
COMP, II 3-13
input/output, II 3-14
CHAIN, II 3-14
DSPLY, II 3-16
EXCPT, II 2-103,3-17
FORCE, II 3-18
READ, II 3-19
SETLL, II 3-19
LOKUP, II 3-22
move, II 3-5
MOVE, II 3-5
MOVEA, II 3-6
MOVEL, II 3-6
set, II 3-9
SETOF, II 3-9
SETON, II 3-9
specifying, II 2-86
subprogram, II 3-25
CALL, II 3-25
EXTRN, II 3-26
GIVNG, II 3-26
PARM, II 3-27
PARMD, II 3-28
PARMV, II 3-28
PLIST, II 3-29
subroutine, II 3-10
BEGSR, II 3-10
ENDSR, II 3-10
EXSR, II 3-10
summary
table, II 3-31
Optimizing
file performance, II 2-31

Master Index

Optimizing programs, I 12-1
Expansion factor, I 12-3
file applications, I 12-3
file performance, I 12-3
file sharing, 112-3
1/0 processing, I 12-3
multiblock count, I 12-3
multi buffer count, I 12-3
with adjacent fields, I 12-2
with blank Factor 1, 112-3
with data structures, 112-1
Optional, II 2-56
rules for specifying, II 2-56
OR, II 2-61,2-91
example, II 2-62
Output specification
example, II 2-92
rules for specifying, II 2-61,2-91
Output files
controlling overflow, II 2-29
specifying
File addition, II 2-32
File name, II 2--48
Unordered Output, II 2-32
using overflow indicators, II 2-29
OUTPUT qualifier, I 3-3
Output specification, II 2-90
AND,II2-91
Blank after, II 2-106
Constants
long character literals, II 2-111
copy from CDD, II 2-7
Data format, II 2-109
Edit code modifiers, II 2-110
Edit codes, II 2-104
Edit words, II 2-112
End position, II 2-107
Fetch overflow, II 2-96
Field name, II 2-102
File name, II 2-91
format, II 2-90
function, II 2-90
Indicators, II 2-100
OR,II2-91
Record type, II 2-93
Skip after, II 2-98
Skip before, II 2-98
Space after, II 2-97
Space before, II 2-97
specifying
ADD option, II 2-95
DEL option, II 2-95
Type, II 2-90
Overflow
automatic, I 6-13
Overflow indicators, I 4-12,6-10, II 2-29
causing page breaks, I 4-12
example, I 4-12,6-12

MasterIndex

Overflow indicators, (Cont.)
function, I 4-12
rules for specifying, I 6-10, II 2-29
specifying,! 4-12
Fetch overflow, II 2-96
Overflow line number, II 2--49
OL,II2-50
rules for specifying, II 2--49
Overflow processing
logic cycle, 11-19
flowchart, 11-19
Overpunched decimal
specifying, II 2--44
Overpunched decimal data type
example, II 1-6
representation ofleast significant digit and
sign,II 1-5
representation of non least
significant digits, II 1-5
trailing numeric string, II 1-4

p
1P indicators, I 4-14,6-8
conditioning output data, I 4-14
example, I 4-14,6-9
function, 14-14
specifying, 14-14
Packed decimal data type
example, II 1--4
specifying, II 2--44
PAGE function, I 3-18
example, I 3-18
Page size
defining, I 6-14
PAGE special word, I 6--4
changing the page number, I 6-5
example, I 6-5 to 6-6
resetting the page number, I 6-6
PAGEl special word, I 6--4
PAGE2 special word, I 6--4
PAGE3 special word, I 6--4
PAGE4 special word, I 6--4
PAGE5 special word, I 6--4
PAGE6 special word, I 6--4
PAGE7 special word, I 6--4
Paging special words
rules for specifying, I 6-4
Parameters
list, II 3-29
passing
access types, II 3-27
data types, II 3-28
mechanisms, II 3-27
by descriptor, II 3-28
by reference, II 3-27
by value, II 3-28

PARM operation code, II 3-27
example, 19-6, 9-11
rules, II 3-27
PARMD operation code, II 3-28
example, 19-11, II 3-30
rules, II 3-28
PARMV operation code, II 3-28
example, 19-10,9-16
rules, II 3-29
Passing mechanisms, 19-18
Paste buffer, 1 3-9
PASTE function, 13-21
example, 13-74
PDP-11 RPG II
comparison with VAX RPG II, II B-1
See VAX RPG II, II B-1
*PLACE special word, 16-7
example,l~

rules for specifying, 16--7
PLIST
names,111-7
operation code, II 3-29
rules, II 3-29
Position
see record identification codes
rules for specifying, II 2-59
Pre-execution-time arrays, 18-4
creating, 18-4,8-6
rules for specifying, 18-4
outputting, 18-20
searching
example, 18-17
updating, 18-19
writing, 18-20
Pre-execution-time tables, 17-2
creating
example, 17-7
outputting, 17-12
rules for defining, 17-7
updating, 17-11
example, 17-11
writing,17-12
Primary files
selecting Mode of processing, II 2-24
Printer device
specifying,II2-30
Printer output files, 1 6--1
automatic overflow, 16--13
changing page numbers, 1 6-4
checking the alignment, II 2-15
conditioning output, 16--8
constants
example, 16-2
controlling overflow, 112-29
creating, 16--1
defining
page numbers, 16-4

Printer output files, defining (Cont.)
page size, 16--14
rules for specifying, 16--14
deleting form-feed characters, 16--1
editing
numeric data, II 2-112
editing output, 16--1, II 2-104
first-page indicators, 1 4-14
formatting, II 2-97 to 2-98
output, 16--14
output data, II 2-107,2-110
generating report titles, II 2-111
last-record indicators, 14-15
NOFEED qualifier, 16-1
overflow indicators
using, 1 4-12
IP indicators, 1 4-14
paging, 16-4
printing
IMPORTANT INFORMATION, 16-1
printing the date, 1 6--3
repeating output records, 16-7
resetting page numbers, 16-4
Skip entries, 16-14
example, 16-16
Space entries, 16--14
example, 16-16
specifying
a negative sign, II 2-116
asterisks, 112-113
blank spaces, 112-114
commas, II 2-115
constant data, II 2-111
CR, II 2-116
currency symbol, II 2-114
decimal points, II 2-115
Fetch overflow, II 2-96
Overflow line number, II 2-49
page breaks, 16--10
page numbers, 16-4
page size, 112-49
Skip after, II 2-98
Skip before, II 2-98
Space after, II 2-97
Space before, II 2-97
zero suppression, II 2-113
using
constants, 1 6--2
Edit code modifiers, 16--2
asterisk fill, 16-2
floating dollar sign, 16-2
Edit codes, 16--1
first-page indicators, 16-8
indicators to condition output, II 2-100
overflow indicators, 16--10, II 2-29
example, 16--12
1P indicators, 1 ~
special words, 1 6-3

Master Index

Procedure Calling and Condition
Handling Standard, I 9-32
.Procedure calls, I 9-19
Processing
branching, II 3-20
files
chained
flowchart, I 1-18
demand
flowchart, I 1-18
specifying
an ADDROUT file, II 2-23
random access, II 2-23
sequential access, II 2-23
sequential within limits access, II 2-23
look-ahead fields
flowchart, I 1-20
multifiles, I 5-29
processing files
multiple keys, I 5-41
example, I 5-41
Program development, I 2-1
compiling, 12-1
linking, I 2-8
running, I 2-9
Programs
see RPG II programs
branching, II 3-21
developing, I 2-1
logic cycle, I 1-1
Prompt line, I 3-5
definition, I 3-7

Q
Qualifiers
see specific entries
debugger, I 10-1
RPG command, I 2-3
RPG/EDIT command, I 3-2

R
Random by ADDROUT file access, I 5-14
example, I 5-17
rules for specifying, I 5-16
Random by key file access, I 5-13
example, I 5-14
rules for specifying, I 5-13
Random file access, I 5-11
using
an ADDROUT file, I 5-14
keys, I 5-13
relative record numbers, I 5-11
example, I 5-12
rules for specifying, I 5-11

Master Index

READ operation code, II 3-19
demand files, II 3-19
example, II 3-19
full-procedural files, II 3-19
rules, II 3-19
READ_ONLY qualifier, I 3-3
Record address type, II 2-28
Record formats
fixed,I5-2
variable, I 5-2
Record identification codes, II 2-58
identifying record types, II 2-58
specifying
Character, II 2-60
CZD portion, II 2-59
example, II 2-60
Not, II 2-59
Position, II 2-59
Record length, II 2-22
rules for specifying, II 2-21 to 2-22
Record types, II 2-93
defining the ordering sequence, II 2-55
detail, II 2-93
example, II 2-94
exception, II 2-93
heading, II 2-93
identifying, II 2-56
rules for specifying, II 2-93
specifying
record identification codes, II 2-58
total, II 2-93
using record-identifying
indicators, I 4-2
Record-address files
selecting Mode of processing, II 2-25
specifying
From file name, II 2-40
To file name, II 2-40
Record-identifying indicators, II 2-56
conditioning input data, II 2-56
example, I 4-1,4-3
function, I 4-1
identifying record types, I 4-1
Record-limits files
example, I 5-8
function, I 5-8
rules for specifying, I 5-8
specifying
Key length, II 2-27
Records
adding, I 5-22, II 2-95
array inpu1/; I 8-4
changing processing order, II 3-19
deleting, I 5-28, II 2-95
example, I 5-28
general processing cycle, 11-2
identifying types, II 2-56
processing totals, I 1-4

Records (Cont.)
record-identifying indicators, 1 4-1
selecting
SETLL operation code, II 3-19
specifying
detail, II 2-93
exception, II 2-93
format, II 2-21
heading, II 2-93
length
fixed, II 2-21
variable, II 2-21
record identification codes, II 2-58
total, II 2-93
types, II 2-93
defining the ordering sequence, II 2-55
updating, 1 5-26
example, 1 5-27
using record-identifying indicators, 1 4-1
writing during calculations, II 3-17
RECOVER qualifier, 1 3-4
REFRESH_SCREEN, 1 3-29
Related arrays, 1 8-5
alternate format, 1 8-8
creating, 1 8-5,8-8
Related tables
alternate format
example, 1 7-11
creating, 1 7-5
example, 1 7-6
input records, 1 7-3
entries
example, 1 7-4
LOKUP operation code
rules, II 3-23
updating,! 7-11
RESET function, 1 3-27
Result field, II 2-86
rounding data, II 2-88
rules for specifying, II 2-86
Resulting indicators, 1 4-6, II 2-88
arrays, 1 8-16
example, 1 4-7
function, 1 4-6
rules for specifying, II 2-89
specifying
result of search, II 3-23
type of search, II 3-22
testing calculation results, 1 4-6
types of tests, 1 4-6
using Half adjust, II 3-26
RETURN key
example, 1 3-55
REVIEWJ;RROR function, 1 3-19
RIGHT function, 1 3-28
example, 1 3-54

RPGcommand
defining as a symbol, 1 2-2
format, 1 2-1
qualifiers, 1 2-3
CHECK,12-4
CROSS..REFERENCE, 1 2-5
DEBUG,12-6
example, 1 2-3 to 2-4
format, 1 2-3
LIST,I2-6
MACHINE_CODE, 1 2-7
negating, 1 2-3
OBJECT, 1 2-7
SEQUENCE_CHECK, 1 2-8
table, 1 2·-4
WARNINGS, 1 2-8
RPG II editor, 1 3-1
auto right justification of numeric fields,
13-44
blinking the current column, 1 3-26
buffers, 1 3-9
current, 1 3-9
deleted-field, 1 3-9
deleted-line, 1 3-9
paste, 1 3-9
compiling programs, 1 3-30
creating
a new program line, 1 3-27 to 3-28
programs
example, 1 3-54
creating files, 1 3-3
cursor, 1 3-8
customizing, 1 3-48
editor commands, 1 3-48
example, 1 3-48
startup command file, 1 3-48
SET COMMAND option, 1 3-48
deleting
a character and shifting the program line
left, 1 3-22
a character and shifting the program line
right, 1 3-22
characters from the cursor to the end of
the line, 1 3-25
fields, 1 3-20
determining where the editor starts, 1 3-4
displaying
current column setting, 1 3-46
current DEFAULT setting, 1 3-46
current SCROLL setting, 1 3-46
current SECTION setting, 1 3-46
current SYNTAXCHECK setting, 1 3-46
help information, 1 3-35
program, 1 3-19
version number and copyright, 1 3-46
editing an existing program
example, 1 3-66
finding the next error, 1 3-19

Master Index

RPG II editor, (Cont.)
functions
displaying help information, I 3-13
inserting the contents of the
paste buffer, I 3-21
invoking, I 3-1
example, 13-54
keypad, I 3-9
displaying
keypad diagram, I 3-13
example, 13-9
naming conventions, I 3-10
leaving the editor, I 3-34, 3-38
moving
current line, I 3-27
current line to the ruler, I 3-20
sections of the editing buffer, I 3-19
moving cursor
backward, I 3-21
down, 13-28
left, 13-28
right,I 3-28
to end of a program line, I 3-24
to first line, I 3-21
to last line, I 3-21
to next character, I 3-26
to next field, I 3-23
to next tab stop, I 3-29
to preceding tab stop, I 3-28
up, 13-27
naming the output file, I 3-3 to 3-4
numbering program lines, I 3-39
overstriking, I 3-1
placing selected text into the paste buffer,
13-21
recovering edits, I 3-4
renumbering existing program lines,
13-39
replacing
the preceding character with a space,
13-28
the program line with spaces, I 3-29
resetting the select range, I 3-27
rewriting the screen display, I 3-29
saving edits, I 3-3
screen, I 3-5
selecting a range oflines for the paste
buffer, I 3-27
setting
terminal characters, I 3-9
the current direction forward, I 3-20
the location of the ruler, I 3-41
the number of display lines, 13-44
the scroll region, I 3-43
single line syntax check, I 3-44
specifying the current column, I 3-44
startup command, I 3-2

RPG II editor, (Cont.)
terminating RPG II editor command
entries, I 3-26
undeleting fields, I 3-20
viewing programs, I 3-3
VKI00 (GIGI) terminal, I 3-5
writing the editing buffer to an output file,
13-29
RPG II editor commands
COMPILE, I 3-30
DEFINE KEY, I 3-31
EXIT, 13-34
example, I 3-34
SAVE qualifier, I 3-35
HELP, 13-35
example, I 3-35, 3-37
INCLUDE, I 3-37
QUIT, 13-38
example, I 3-38
SAVE qualifier, I 3-39
RESEQUENCE, I 3-39
options, I 3-39
REMOVE, I 3-39
SEQUENCE
example, I 3-39
SET,I3-40
format, I 3-40
options
COMMAND, I 3-40
HELP KEYPAD, I 3-41
HELP NONE, I 3-41
HELP SPECIFICATIONS, I 3-41
RULER, 13-41
SCROLL, I 3-43
SECTION, I 3-44
STARTCOLUMN, I 3-44
SYNTAXCHECK, I 3-44
SHOW,13-45
options
DEFAULT, I 3-46
SCROLL, I 3-46
SECTION, I 3-46
STARTCOLUMN,I3-46
SYNTAXCHECK, I 3-46
VERSION, I 3-46
SUBSTITUTE, I 3-46
RPG II editor EXIT command
example, I 3-76
RPG II editor RESEQUENCE command
example, 13-71, 3-75
RPG II editor screen
80-column ruler, I 3-5
definition, I 3-7
example, I 3-6 to 3-7
displaying help information, I 3-6
editing window, I 3-5
example, I 3-7
EOB mark, I 3-7

/
\

Master Index

\,,-

RPG II editor screen (Cont.)
help window, I 3-5
displaying help information, I 3-6
example, I 3-6
message line, I 3-5
definition, I 3-7
example, I 3-6 to 3-8
prompt line, I 3-5
definition, I 3-7
example, I 3-6, 3--8
source window
example, I 3-6
specification format
example, I 3--8
tab stops, I 3-5
definition, I 3-7
example, I 3--6 to 3-7
RPG II editor SECTION function
example, I 3-72
RPG II editor SHOW command, I 3--45
RPG II editor SHOW STARTCOLUMN
command
example, I 3-55
RPG II programs
arrays, I 8-1
call interface, I9-1
calling
subprograms, I 9-32
system services, I 9-28
compiling, I2-l
creating, I3-1
debugging,! 10-1
developing, I2-l
documenting, II 2-5
editing, I3-1
linking, I 2-8
logic cycle, I 1-1
optimizing, I 12-1
running, I 2-9
viewing, I 3-1
RPG II specifications, II 2-1
RPG/DEBUG, I 10-1
RPG/EDIT command, I3-1
qualifiers
COMMAND,I3-2
CREATE,I3-3
JOURNAL, I 3-3
OUTPUT, I 3-3
READ_ONLY, I 3-3
RECOVER, I 3--4
STARLPOSITION, I 3--4
table, I 3-2
RTL parameter access types
modify, I 9-12
read only, I 9-12
write only, I 9-12
example, I 9-12

RTL parameter data types
double precision floating point, I 9-12
longword integer,l9-12
numeric string, I 9-12
example, I 9-13
packed decimal string, I 9-12
quad word integer, I 9-12
single precision floating point, I 9-12
text string, I 9-12
word integer, I 9-12
RTL parameter passing mechanisms
by descriptor
example,! 9-11
by reference
example,! 9-6, 9-11
by value, I 9-10,9-16
example, I 9-10,9-16
RTL procedures
assigning names, II 3-26
calling, II 3-25
example, I 9-14,9-16 to 9-18, 9-24 to
9-27
GIVNG operation code, II 3-26
parameter characteristics
access types, I9-12
data types,! 9-12
passing mechanisms, I 9-10, 9-18
parameter passing mechanisms
by descriptor, I 9-10
PARMD operation code, I 9-10
by reference, I 9-10
PARM operation code, I9-10
by value, I 9-10
example,l9-10,9-16
PARMV operation code, I 9-10
passing parameters, II 3-27 to 3-28
RTL routines
Arguments
optional, I 9-5
required, I 9-5
Ruler, I 3-5
RUN command, I 2-9
example, I 2-9
format, I 2-9
Run-Time Library routines, T 9-2
example of calling, I 9-24
facilities, I 9-2
how to call, I 9-3
Running programs, I 2-9

s
Screen handling, I 9-33
FMS, I 9-33 to 9-34
example, I 9-34
SMG, I 9-33,9-35
example, I 9-35

Master Index

Screen handling, (Cont.)
TDMS, I 9-33
example, 19-33 to 9-34
Secondary files
selecting Mode of processing, II 2-24
SECTION function, I 3-19
SELECT function, I 3-27
example, I 3-74
Sequence codes, II 2-20, 2-45, 2-55
assigning a numeric code, II 2-56
Number, II 2-56
rules for specifying, II 2-20, 2-45
specifying
alphabetic, II 2-55
continued processing, II 2-56
numeric, II 2-55 to 2-56
SEQUENCE_CHECK qualifier, I 2-8
checking line number sequence, I 2-8
format, I 2-8
Sequential by key file access
example, I 5-7
rules for specifying, I 5-7
Sequential file access, I 5-6
example, I 5-S
rules for specifying, I 5-S
Sequential file organization, I 5-2
example, I 5-3
Sequential files
adding records, I 5-23
example, 15-23
rules for specifying, I 5--23
creating, I 5-20
example, 15--20
rules for specifying, I 5--20
Sequential within limits file access
example, I 5-10
record-limits file, I 5-8
SET COMMAND option, I 3-48
Set operation codes, II 3-9
example, II 3-9
SETON, II 3-9
SETLL operation code, II 3-19
example, II 3-20
rules, II 3-19
selecting the next record, II 3-19
SETOF operation code, II 3-9
example, II 3-9
rules, II 3-9
SETON operation code, II 3-9
example, II 3-9
rules, II 3-9
SHIFT-LEFT function, I 3-22
example, I 3-22
SHIFT~IGHT function, I 3-22
example, I 3-23
Skip after, II 2-98
example, II 2-99
rules for specifying, II 2-99

Master Index

Skip before, II 2-98
example, II 2-99
rules for specifying, II 2-99
SMG,I9-33,9-35
Space after, II 2-97
rules for specifying, II 2-97
Space before, II 2-97
rules for specifying, II 2-97
Special words, I 6-3
PAGE, I 6-4
PAGEl, 16-4
PAGE2,I6-4
PAGE3,I6-4
PAGE4,I6-4
PAGE5, I 6-4
PAGE6, I 6-4
PAGE7,I6-4
paging, I 6-4
*PLACE, I 6-7
rules for specifying, I 6-4
UDATE,I6-3
UDAY
example, I 6-4
UMONTH
example, I 6-4
UYEAR
example, I 6-4
Specification format
asterisks, II 2-3
column numbers, II 2-2
comments, II 2-5
dashes, II 2-3
dots, II 2-3
line number, II 2-4
notational conventions, II 2-2
Specifications
Calculation, II 2-79
Control, II 2-11
Extension, II 2-38
File Description, II 2-16
format, II 2-2
Input, II 2-50
Line Counter, II 2-47
Output, II 2-90
RPG II, II 2-1
types, II 2-5
Split-control fields
example, 14-11
SQRT operation code, II 3-4
example, II 3-4
Square root operation, II 3-4
STARTJ>OSITION qualifier, I 3-4
Startup command file, I 3-48
SUB operation code, II 3-3
example, II 3-4
Subprogram operation codes, II 3-25
CALL, II 3-25
EXTRN, II 3-26

/
i

Subprogram operation codes, (Cont.)
GIVNG, II 3-26
PARM, II 3-27
PARMD, II 3-28
PARMV, II 3-28
PLIST, II 3-29
Subprograms, I 9-32
calling, II 3-25
example, I 9-32
parameter list, II 3-29
passing parameters, II 3-27 to 3-28
PLIST, II 3-29
Subroutines
executing, II 3-10
marking the beginning, II 3-10
marking the ending, II 3-10
names, II 1-7
operation codes, II 3-10
BEGSR, II 3-10
ENDSR, II 3-10
example, II 3-10
EXSR,lI3-10
Subtraction operation, Il3-3
Symbolic device, II 2-31
System routines, I 9-1
determining the type of call
function, I 9-4
procedure, I 9-4
examples of calling, I 9-24
function calls, I 9-15
function results, I 9-23
how to call, I 9-3
passing mechanisms, I 9-18
procedure calls, I 9-19
procedure results, I 9-23
System services, I 9-28
calling, II 3-25
example, I 9-29 to 9-31
determining the type of call
function, I 9-4
procedure, I 9-4
groups, I 9-3
how to call, I 9-3
passing parameters, II 3-27 to 3-28
routines, I 9-2
symbolic constants
example, I 9-22

T
TAB function
example, I 3-54
Tab stops, I 3-5
definition, I 3-7
Table or array name, II 2-41
rules for specifying, II 2-41

Tables,l7-1
alternate format, II 2-45
compile-time, I 7-2
rules for defining, I 7-6
creating
input records, I 7-3
definition, I 7-1
entries, I 7-3
input records, I 7-3
creating, I 7-3
example, I 7-3
rules for specifying, I 7-3
loading time
selecting, I 7-1
LOKUP operation code, I 7-7, II 3-23
names, II 1-7
outputting
example, I 7-12
rules for specifying, I 7-12
pre-execution-time, I 7-2
rules for defining, I 7-7
referencing entries, I 7-10
example,l7-10
related,l7-1,7-3
creating, I 7-5
example, I 7-6
example, I 7-11
updating, I 7-11
searching, I 7-7, II 3-23
example, II 3-24
rules for specifying, I 7-8
single, I 7-1
creating, I 7-4
example, I 7-5
specifying, II 2-18
alternate format, II 2-45
current entry, I 7-10
example, I 7-11
Data format, II 2-44
Decimal positions, II 2-44
From file name, II 2-40
Length of entry, II 2-43
names, II 2-41
Number of entries per record, II 2-42
Number of entries per table or array,
II 2-42
sequence, I 7-9, II 2-45
ascending, I 7-9
descending, I 7-9
example, I 7-9
To file name, II 2-40
updating, I 7-11
writing,l7-12
TAG operation code, II 3-21
example, II 3-22
rules, II 3-21
Tapes
rewinding, II 2-37

Master Index

Tapes (Cont.)
specifying
labels, II 2-31
ANSI, II 2-31
TDMS,I9-33
Terminal device
specifying, II 2-30
TESTB operation code, II 3-12
example, II 3-12
rules, II 3-12
To file name
outputting
arrays, II 2-40
tables, II 2-40
record-address files, II 2-40
rules for specifying, II 2-41
writing
arrays, II 2-40
tables, II 2-40
TOP function, I 3-21
Total time,! 1-2,1-4
Type, II 2-90

u
UDATE special word, I 6-3
defining, I 6-3
editing, I 6-3
specifying notation, II 2-12
UNDELETE_FIELD function, I 3-20
UNDELETE_LINE function, I 3-17
Unordered output, II 2-32
rules for specifying, II 2-33
UP function, I 3-27
example, I 3-73
Update files
selecting Mode of processing, II 2-24
specifying
File addition, II 2-33
Unordered output, II 2-33
Updating
files, I 5-26
randomly by key, I 5-28
sequentially, I 5-28
records, I 5-26
example, I 5-27
User-defined names, II 1-6
rules, IIl-7

Master Index

v
VAX Procedure Calling and
Condition Handling Standard, I 9-32
VAX RPG II
differences between PDP-11 RPG II, II B-1
different support, II B-2
editor
nonsupported functionality, II B-7
new functionality, II B-5
nonsupported functionality, II B-1
new functionality, II B-5
VAXNMS Modluar Programming Standard,
19-32
VMS Usages, I 9-7
VAX RPG II equivalents, I 9-7

w
WARNINGS qualifier, I 2-8
displaying
error messages, I 2-8
information messages, I 2-8
format, I 2-8
options, I 2-8
INFORMATION, I 2-8
OTHER, I 2-8
Word binary data type
example, II 1-3

x
XFOOT operation code, II 3-4
arrays, I 8-14
example,! 8-15
referencing array elements, I 8-15

z
Z-ADD operation code, II 3-2
example, II 3-4
Z-SUB operation code, II 3-3
example, II 3-4
Zero suppression, II 2-113

Programming in

VAX RPG II
AA-R431B-TE

READER'S
COMMENTS

Note: This form is for document comments only.
DIGIT AL will use comments submitted on this form at the
company's discretion. If you require a written reply and are
eligible to receive one under Software Performance Report
(SPR) service, submit your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make
suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:

o Assembly language programmer
o Higher-level language programmer
o Occasional programmer (experienced)
o User with little programming experience
o Student programmer
o Other (please specify)
Name __________________ Date _ _ _ _ _ _ _ _ _ __
Organization _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
Street _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
City _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ State _ _ _ _ _ Zip Code - - or Country

Do Not Tear - Fold Here and Tape -

- - --I

~DmDDmD

No Postage
Necessary
if Mailed in the
United States

IIIIII

1
1
1
1

1
1

BUSINESS REPLY MAIL

FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

SSG PUBLICATIONS ZKl-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA. NEW HAMPSHIRE 03062-2698

DoNotTear-FoldHere

I
-I
1

1
1

I~
I~o

I':,
"o

I~
1