Trailing-Edge
-
PDP-10 Archives
-
decuslib10-10
-
43,50517/rpgman.doc
There is 1 other file named rpgman.doc in the archive. Click here to see a list.
DECsystem-10 RPG II Report Program Generator
Reference Manual
Revision: 2
June 1, 1977
Copyright (C) 1977
Cerritos Community College District and Robert Currier
This software is furnished under license for use only on a single
computer system and may be copied only with the inclusion of the above
copyright notice. This software, or any other copies thereof, may not
be provided or otherwise made available to any other person except for
use on such system and to one who agrees to these license terms.
Title to and ownership of the software shall at all times remain with
Cerritos Community College District and Robert Currier.
The information in this software is subject to change without notice
and should not be construed as a commitment by either Cerritos
Community College District or Robert Currier.
DECsystem-10 RPG II Reference Manual Page 2
DECsystem-10 RPG II Reference Manual Page 3
Table of Contents
CHAPTER 1 INTRODUCTION
1.1 THE RPG II CYCLE ........................ 1-2
1.1.1 Single Input File Processing ......... 1-2
1.1.2 Multiple Input File Processing ....... 1-3
1.1.3 Changes to the Standard Cycle ........ 1-5
1.1.4 Cycle Summary ........................ 1-5
1.2 RPG II FUNCTIONS - THE SPECIFICATIONS ... 1-5
1.3 DEFINITION OF TERMS ..................... 1-7
CHAPTER 2 RPG II SPECIFICATIONS FORMS
2.1 QUICK REFERENCE CHARTS .................. 2-1
CHAPTER 3 COMMON ENTRIES
3.1 PAGE NUMBER ............................. 3-1
3.2 LINE NUMBER ............................. 3-2
3.3 FORM TYPE ............................... 3-2
3.4 COMMENTS ................................ 3-3
3.5 PROGRAM IDENTIFICATION .................. 3-3
CHAPTER 4 CONTROL SPECIFICATIONS -- FORM H
4.1 OBJECT PROGRAM EXECUTION SIZE ........... 4-1
4.2 DEBUG ................................... 4-1
4.3 FORMS POSITIONING ....................... 4-2
CHAPTER 5 FILE DESCRIPTIONS SPECIFICATIONS -- FORM F
5.1 FILENAME ................................ 5-1
5.2 FILE TYPE ............................... 5-2
5.2.1 Input Files .......................... 5-2
5.2.2 Output Files ......................... 5-2
5.2.3 Update Files ......................... 5-3
5.2.4 Combined Files ....................... 5-3
5.2.5 Display Files ........................ 5-3
5.3 FILE DESIGNATION ........................ 5-4
5.3.1 Primary Files ........................ 5-4
5.3.2 Secondary Files ...................... 5-4
5.3.3 Chained Files ........................ 5-5
5.3.4 Record Address Files ................. 5-5
5.3.5 Table or Array Files ................. 5-5
5.3.6 Demand Files ......................... 5-6
5.4 END OF FILE ............................. 5-6
5.5 SEQUENCE ................................ 5-7
5.6 FILE FORMAT ............................. 5-7
5.7 BLOCK LENGTH ............................ 5-7
5.8 RECORD LENGTH ........................... 5-8
5.9 MODE OF PROCESSING ...................... 5-8
5.9.1 Consecutive Processing ............... 5-10
5.9.2 Sequential Processing of Indexed Files 5-10
DECsystem-10 RPG II Reference Manual Page 4
5.9.3 Processing by ADDROUT File ........... 5-10
5.9.4 Random Processing .................... 5-11
5.10 LENGTH OF KEY OR RECORD ADDRESS FIELD ... 5-11
5.11 RECORD ADDRESS TYPE ..................... 5-11
5.12 TYPE OF FILE ORGANIZATION ............... 5-12
5.13 PRINT FILE OVERFLOW INDICATOR ........... 5-12
5.14 KEY FIELD STARTING LOCATION ............. 5-13
5.15 EXTENSION CODE .......................... 5-13
5.16 DEVICE CODE ............................. 5-14
5.17 FILENAME ................................ 5-14
5.17.1 Default Extensions ................... 5-15
5.18 CONTINUATION LINES ...................... 5-16
5.18.1 Column 53 ............................ 5-16
5.18.2 Continuation Lines Options ........... 5-16
5.19 FILE ADDITION AND UNORDERED OUTPUT ...... 5-16
5.20 TAPE REWIND ............................. 5-17
CHAPTER 6 EXTENSION SPECIFICATION -- FORM E
6.1 FROM FILENAME ........................... 6-1
6.2 TO FILENAME ............................. 6-2
6.3 NAME OF TABLE OR ARRAY .................. 6-2
6.4 NUMBER OF ENTRIES PER RECORD ............ 6-3
6.5 NUMBER OF ENTRIES PER TABLE OR ARRAY .... 6-4
6.6 LENGTH OF ENTRY ......................... 6-5
6.7 DATA FORMAT ............................. 6-5
6.8 DECIMAL POSITIONS ....................... 6-6
6.9 SEQUENCE ................................ 6-6
6.10 ALTERNATE TABLE OR ARRAY ................ 6-7
6.11 COMMENTS ................................ 6-7
CHAPTER 7 LINE COUNTER SPECIFICATIONS -- FORM L
7.1 FILENAME ................................ 7-1
7.2 NUMBER OF LINES PER PAGE ................ 7-1
7.3 FORM LENGTH ............................. 7-2
7.4 OVERFLOW LINE NUMBER .................... 7-2
7.5 OVERFLOW LINE ........................... 7-2
CHAPTER 8 INPUT SPECIFICATIONS -- FORM I
8.1 FILENAME ................................ 8-1
8.2 SEQUENCE ................................ 8-2
8.3 NUMBER .................................. 8-3
8.4 OPTION .................................. 8-3
8.5 RECORD IDENTIFYING INDICATOR ............ 8-3
8.6 RECORD IDENTIFICATION CODES ............. 8-5
8.6.1 Position ............................. 8-5
8.6.2 NOT .................................. 8-6
8.6.3 C .................................... 8-6
8.6.4 Record Identification Character ...... 8-6
8.7 ADDITIONAL RECORD IDENTIFICATIONS ....... 8-6
8.8 FIELD TYPE .............................. 8-7
8.9 FIELD LOCATION .......................... 8-7
8.10 DECIMAL POSITIONS ....................... 8-8
DECsystem-10 RPG II Reference Manual Page 5
8.11 FIELD NAME .............................. 8-8
8.11.1 Special Words -- PAGE, PAGE1, PAGE2 .. 8-9
8.12 CONTROL LEVEL ........................... 8-9
8.13 MATCHING FIELDS ......................... 8-10
8.14 FIELD RECORD RELATION ................... 8-11
8.15 FIELD INDICATORS ........................ 8-13
CHAPTER 9 CALCULATION SPECIFICATIONS -- FORM C
9.1 CONTROL LEVEL ........................... 9-3
9.2 INDICATORS .............................. 9-4
9.2.1 AN/OR Lines .......................... 9-5
9.3 FACTOR 1 AND FACTOR 2 ................... 9-7
9.3.1 Field Names .......................... 9-8
9.3.2 Literals ............................. 9-8
9.3.2.1 Numeric ........................... 9-8
9.3.2.2 Alphanumeric ...................... 9-9
9.3.3 Names and Elements ................... 9-9
9.3.4 Date Field Names ..................... 9-9
9.3.5 Special Names ........................ 9-9
9.3.6 Labels ............................... 9-10
9.3.7 Filenames ............................ 9-10
9.4 OPERATION -- COLUMNS 28-32 .............. 9-10
9.4.1 Arithmetic Operations ................ 9-12
9.4.2 Move Operations ...................... 9-12
9.4.3 Move Zone Operations ................. 9-12
9.4.3.1 MHHZO ............................. 9-13
9.4.3.2 MHLZO ............................. 9-13
9.4.3.3 MLLZO ............................. 9-13
9.4.3.4 MLHZO ............................. 9-13
9.4.4 Compare, Bit and Test Operations ..... 9-13
9.4.4.1 COMP .............................. 9-13
9.4.4.2 BITON, BITOF, TESTB ............... 9-18
9.4.4.3 TESTZ ............................. 9-19
9.4.5 Branch and Exit ...................... 9-19
9.4.5.1 GOTO .............................. 9-20
9.4.5.2 TAG ............................... 9-20
9.4.5.3 EXSR .............................. 9-20
9.4.5.4 BEGSR ............................. 9-21
9.4.5.5 ENDSR ............................. 9-21
9.4.5.6 EXIT .............................. 9-21
9.4.5.7 RLABL ............................. 9-21
9.4.6 Indicator Operations ................. 9-21
9.4.6.1 SETON ............................. 9-21
9.4.6.2 SETOF ............................. 9-22
9.4.7 Table Operation ...................... 9-22
9.4.7.1 LOKUP With One Table .............. 9-23
9.4.7.2 LOKUP With Two Tables ............. 9-23
9.4.7.3 LOKUP With Arrays ................. 9-23
9.4.8 Input/Output Operations .............. 9-27
9.4.8.1 EXCPT ............................. 9-27
9.4.8.2 FORCE ............................. 9-27
9.4.8.3 DSPLY ............................. 9-28
9.4.8.4 READ .............................. 9-28
9.4.8.5 CHAIN ............................. 9-29
DECsystem-10 RPG II Reference Manual Page 6
9.4.8.5.1 Random Input Processing ........ 9-29
9.4.8.5.2 Direct File Output Load ........ 9-29
9.4.9 DEBUG Operation ...................... 9-30
9.4.10 TIME Operation ....................... 9-32
9.5 RESULT FIELD ............................ 9-32
9.6 FIELD LENGTH ............................ 9-33
9.7 DECIMAL POSITIONS ....................... 9-33
9.8 HALF ADJUST ............................. 9-33
9.9 RESULTING INDICATORS .................... 9-34
9.10 COMMENTS ................................ 9-35
9.11 CALCULATION SPECIFICATIONS EXAMPLES ..... 9-35
CHAPTER 10 OUTPUT-FORMAT SPECIFICATIONS - FORM O
10.1 FILENAME ............................... 10-1
10.2 AND/OR RELATIONSHIPS ................... 10-1
10.3 RECORD TYPE ............................ 10-2
10.4 ADD RECORD ............................. 10-4
10.5 FETCH OVERFLOW ......................... 10-4
10.6 FORMS CONTROL - SPACE/SKIP ............. 10-7
10.6.1 Space Forms Control ................. 10-7
10.6.2 Skip Forms Control .................. 10-7
10.7 OUTPUT INDICATORS ...................... 10-8
10.8 FIELD NAME ............................. 10-9
10.8.1 Field Names ......................... 10-9
10.8.2 PAGE, PAGE1, PAGE2 .................. 10-10
10.8.3 *PLACE .............................. 10-10
10.8.4 Date Field .......................... 10-11
10.9 EDIT CODES (COLUMN 38) ................. 10-11
10.10 BLANK AFTER ............................ 10-11
10.11 END POSITION IN OUTPUT RECORD .......... 10-14
10.12 FIELD TYPE ............................. 10-14
10.13 CONSTANT OR EDIT WORD .................. 10-14
10.13.1 Constants ........................... 10-15
10.13.2 Edit Code Modifiers -- * and $ ...... 10-15
10.13.3 Edit Words .......................... 10-15
10.14 OUTPUT-FORMAT SPECIFICATIONS EXAMPLES .. 10-17
CHAPTER 11 USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING
11.1 FORMING TABLES AND ARRAYS .............. 11-5
11.2 USING TABLES AND ARRAYS ................ 11-12
CHAPTER 12 RPG II FILE PROCESSING
12.1 SEQUENTIAL FILE PROCESSING ............. 12-1
12.1.1 Matching Records .................... 12-2
12.1.2 Look-Ahead Fields ................... 12-8
12.2 INDEXED FILE PROCESSING ................ 12-13
12.3 DIRECT FILE PROCESSING ................. 12-13
APPENDIX A SUMMARY OF RPG II SPECIFICATIONS
A.1 COMMON ENTRIES .......................... A-1
A.2 CONTROL SPECIFICATIONS - FORM H ......... A-3
DECsystem-10 RPG II Reference Manual Page 7
A.3 FILE DESCRIPTION SPECIFICATION - FORM F . A-4
A.4 EXTENSION SPECIFICATION - FORM E ........ A-8
A.5 LINE COUNTER SPECIFICATIONS - FORM L .... A-10
A.6 INPUT SPECIFICATIONS - FORM I ........... A-11
A.7 CALCULATION SPECIFICATIONS - FORM C ..... A-15
A.8 OUTPUT-FORMAT SPECIFICATIONS - FORM O ... A-18
APPENDIX B REFERENCE TABLES
APPENDIX C RPG II CYCLE
APPENDIX D CHARACTER SETS
APPENDIX E RPG II HALT PROCEDURES
APPENDIX F COMMAND STRINGS
APPENDIX G RPG II STANDARD CALLING SEQUENCE
G.1 EXIT OPERATION .......................... G-1
G.2 RLABL SPECIFICATION ..................... G-1
CHAPTER 1
INTRODUCTION
DECsystem-10 RPG II is a one-pass multi-phase compiler and run time
system. Along with the other programs on the DECsystem-10, RPG II
resides on the system device, a disk. RPG II operations have three
phases; compilation, linking, and execution. Input to the
compilation phase is a set of specifications for the application
program, and sometimes additional data arranged in tables or arrays.
Such data is usually information that is unlikely to change for the
life of the program. Output from the compilation phase includes (1) a
relocatable binary (REL) module (input to the linking loader) and (2)
a listing of the specifications plus any error messages.
Once the listings indicate error-free specifications, the user can
make the REL module "executable" by running the linking loader (LINK)
program. LINK takes the REL module and produces an executable core
image. This core image may then be saved as an EXE file so that later
runs do not require the user to relink the RPG II program. The user
may store the REL module or the EXE file on disk, DECtape, or magtape.
The EXE file plus data stored in files or entered from a terminal make
up the input to the execution phase. The execution phase can occur
repeatedly with different data. The output of that phase is
determined by the application. It may include reports, modifications
to the input data files, or completely new data files.
In addition to the EXE file, the object program makes use of a
collection of routines, called the Object Time System (OTS or RPGLIB).
Because these routines are needed by all RPG II users, they are
implemented as sharable code, so that only one copy must be present on
the machine, regardless of the number of users.
RPG II OTS can perform sequential access with files on any device. In
addition, disk allows (1) indexed and random access by key or record
number and (2) access according to a separate file called a Record
Address File. Record Address Files list which records to process in
the order of processing.
Indexed files are actually two files; one containing the data and the
other containing the index.
INTRODUCTION Page 1-2
1.1 THE RPG II CYCLE
RPG II works from this premise: most business applications which
process data files perform the same operations on a significant number
of records in the files. Hence, RPGLIB can work in a standard
cycle--roughly, input a record, process it, and output some data.
1.1.1 Single Input File Processing
The simplest case involves a program to process a single input file
with a single record type. Example: a program to read a file of
sales records, print buyer and price, and show total receipts at the
end. An RPG II specification for such a program would contain (1) a
description of input and output files and records, and (2) a single
calculation statement to specify continued summing of the receipts for
each record. RPGLIB would accomplish all input and output, one record
at a time, in the standard cycle.
In single input file processing, there can be at least three areas of
complication: (1) files with different record types, (2) look ahead
fields, and (3) different levels in the report structure. A sales
file with different record types might have a type for each product
line, and one for salesmen, as well. When a file has more than one
record type, users can assign internal switches called "indicators"
for "conditioning" calculations and/or output according to the type of
record currently being processed. When a file has multiple record
types, the cycle remains the same, but different things can happen for
different records. In addition, record type groups can be specified
to reflect well-structured files. Example: a product line record
must be followed by exactly one statistical record and then by any
number of (or no) salesmen records.
The look-ahead capability allows RPGLIB to examine fields in the next
record while it is processing the current one. This is useful, for
example, when the program is processing a file with multiple record
types, and the user needs to know the next record's type in order to
handle correctly the current record.
Levels in the report structure often correspond to the management
levels in a company. Thus, a sales report for a national company
might show subtotals at the salesman, office, district, and regional
levels, and end with a total for the whole company. Calculations
appropriate for the salesman level may be irrelevant to other levels,
and vice-versa, so RPG II gives users easy methods for specifying the
correct level for calculations. The Object Time System can
automatially set an indicator when, say, the office number changes
from one record to the next.
For a national company, a master sales file with one record per sale
might list sales by order number within salesman, within office,
within district, within region. If the file is sorted in that
hierarchy, a change in one level (the next district, perhaps) implies
a change in all lower levels (office and salesmen), so that totals for
INTRODUCTION Page 1-3
all those levels (district, office, and salesman) are required. Each
time the salesman listed on the record is different from the one
listed on the previous record, the program might total up the previous
man's sales and print out information needed for the salesman level.
Then, RPGLIB would do detail calculations and output for the new
record. Each time office, district, or region differs from that on
the previous record, RPGLIB could do all lower level calculations
until it completes those for the level that caused the interruption.
These interruptions are called control breaks. Users must specify
which parts of the records (control fields) pertain to each level, and
which calculations and output should be done when each level's control
break occurs. He can leave the rest up to the RPG II cycle. When
control break processing has been specified, the RPG II cycle is
expanded to become (1) input, (2) determine whether a control break
has occurred: if not, go to step (5); (3) perform control break
calculations (also called total calculations); (4) perform control
break (total) output; (5) perform detail calculations; (6) perform
detail output.
1.1.2 Multiple Input File Processing
Multiple Input File processing can be quite complicated. Each file
may have the complexity of a single file, and the files can be
interrelated, as well. The user has complete control over the order
in which RPGLIB reads records. When he does not exercise that
control, however, RPGLIB reads and processes one file after the other,
as if all the files were strung end-to-end.
In cases where files are interrelated, the user can specify matching
records. Matching records involves a comparison of field(s) from
records in several input files. When the fields match, RPGLIB turns
on the matching record indicator and selects the record for the
current cycle according to the order indicated by the file
specifications forms. When records do not match, RPGLIB selects the
record whose matching record field(s) are first in the collating
sequence. As with record types and control levels, the matching
record indicator can condition calculations and output. Matching
records operations allow simplified file merging. Example:
incorporation of a transaction file into a master file. Refer to
paragraph 12.1 for more information.
INTRODUCTION Page 1-4
Figure 1-1
Typical RPG II Flow
INTRODUCTION Page 1-5
1.1.3 Changes To The Standard Cycle
In cases where the above operations do not apply, the user can specify
which file to read on the next cycle, or even modify the cycle
entirely by using special input and output commands.
1.1.4 Cycle Summary
As the above discussion implies, RPG II distinguishes between
operations done each cycle and those done only after a control break.
Operations done each cycle are called detail operations; the others
are total operations. Control breaks occur when RPGLIB reads a record
with a control field different from the last record's control field.
All input records processed between one control break and the next
constitute a control group. Since breaks occur only when RPGLIB reads
a record from outside the current control group, RPGLIB does
processing for the control break before it does detail operations for
the current record.
In addition to detail and total operations, there are 1P (first page)
output operations and LR (last record) operations. 1P output is
unique to the first cycle. It must be conditioned by the 1P
indicator, and may include printing the title of a report or
positioning preprinted forms on the printer. When RPGLIB reaches the
end of the last file to be processed, it sets the LR indicator. Users
can condition calculations and output to occur after the last cycle by
using the LR indicator.
1.2 RPG II FUNCTIONS -- THE SPECIFICATIONS FORMS
Figure 1-1 illustrates the function flow of RPG II. In that figure,
original input is shown as punched card files. Interactive data
terminals, disk, and a magtape can also supply input data. output can
go to a printer, a terminal, disk, or a magtape. After someone has
produced an initial statement showing the desired results, production
of most RPG II programs involves four steps: (a) coding and creating
the specifications for the report program; (b) compilation of an
object program that meets the specifications; (c) task building the
object program with the necessary run-time routines; and (d)
executing the task module.
The specifications mentioned in steps (a) and (b) have several
possible formats, seven of which DIGITAL supplies on preprinted coding
forms. There is a control specification for the whole job, and there
are six form types for input, calculation, and output.
The Control Specification (Form H) supplies
information pertaining to the compilation as a
whole.
INTRODUCTION Page 1-6
The File Description Specification (Form F) and
the Extension Specification (Form E) describe the
files, tables, and arrays to be used by the
program.
The Line Counter Specification (Form L) gives
special information about print files.
The Input Specification (Form I) describes the
input records in the files named in Forms F and E.
The Calculation Specification (Form C) describes
the operations to be performed.
The Output Specification (Form O) describes the
format and contents of the output files named in
Form F.
In addition, the user may specify: (1) the contents of tables and
arrays which won't change for the life of the program; and (2)
alternate collating sequence tables to modify the standard ASCII
collating sequence in certain operations. These two specification
types do not require special coding forms, but they must be prepared
according to well-defined formatting rules. The relationships of form
type to logical specification area are shown in Table 1-1.
Table 1-1
Summary of Form Types
Specification Forms Logical Specification Area
Input Calculation Output
Control Specification (H)
File Description (F) X X
File Extension (E) X X
Line Counter (L) X
Input (I) X
Calculation (C) X X X
Output-Format (O) X
Chapter 2 summarizes the form types for experienced RPG users.
Chapter 3 through 10 describe all form types in detail. For this
introductory discussion of RPG II problem specifications, the
orientation will be in terms of the logical specification areas rather
than the physical form types.
The user describes the input to be available to the object program in
terms of files, records, fields and file devices. A file is an
aggregation of data that is organized for a consistent purpose.
Examples: inventory file, employee file, accounts payable file, file
of equipment characteristics. A record is the major entry of a file.
Records usually carry an identification value and a number of
INTRODUCTION Page 1-7
additional information elements called fields. Example: an inventory
file includes records for each item in the inventory identified by the
item stock number. The item stock number of an inventory record is
considered a field, as is the item balance and the bin location. The
description of input need only be complete enough to allow selection
of necessary records and fields. The user can omit descriptions of
fields not germane to desired processing.
File devices are the computer's equipment media for input and output.
In the calculation specifications the user describes the conditions
under which each calculation operation is to be performed. Examples
of conditions: presence or absence of a record identifying code, a
specified control level, a positive result of a previous calculation
or retrieval of the last record of a file. The calculation operations
include arithmetic, movement of fields, comparisons, definition of
internal subroutines, execution of internal subroutines, setting of
indicators for later reference, setting and testing of flag bits,
table lookup, and limited input/output operations.
The output specifications describe the files, records, fields, and
file devices for the output. The specifications also include the
conditions which must be met for output to be produced. For files to
be updated, output specifications must supplement the descriptions
provided in the input specifications. For a new output file to be
produced, the record organization and field positions are given. For
listing output, the editing desired for fields is described. Editing
includes functions such as zero suppression, insertion of floating
dollar sign, insertion of credit balance symbol, and printing numeric
fields with commas and a decimal point.
The RPG II compilation of an object program for which specifications
have been prepared is performed under control of the RPG II Compiler.
If specification errors are found, indicative messages are printed.
Compilation is completed and task building is allowed, even though
errors are found which would prohibit successful execution. Certain
omissions from specifications can be tolerated. In such cases, the
compiler may insert default values and processes into the object
program. The occurence of default cases, insertions, and subroutines
is noted in the printed record of the compilation.
1.3 DEFINITIONS OF TERMS
Alphabetic Characters - The ASCII characters A through Z
Alphanumeric Characters - The set of 128 ASCII characters
Alphanumeric Fields - A field for which a decimal place entry
was omitted from a specification form.
ASCII Character Set - The set of 128 seven-bit ASCII
characters (listed in Appendix D).
INTRODUCTION Page 1-8
Compilation Time - The time at which the RPG II compiler
accepts source program specifications, produces program and
diagnostic listings, and generates the object program.
Detail Time - The time when those operations not conditioned
by control level indicators are executed.
EBCDIC Character Set - An alternate character set widely used
in the computing industry.
Execution Time (or Run Time) - The time during which object
program cycles are being executed.
Numeric Characters - The ASCII characters 0 through 9.
Numeric Field - A field for which a decimal place entry
(including 0) was made on a specifications form. Only numeric
characters are valid in a numeric field.
Pre-Execution Time - The time during which the object program
is entering execution: i.e., when the object program has been
loaded into core memory, input/output files are being opened,
certain Tables and Arrays are being read, and just before the
first program cycle is executed.
Record Key - The field or fields that uniquely identify a
record in an indexed file. The Record Key determines the
order in which the records may be sequentially processed.
RPG II Names -
Filename - Up to eight alphabetic and numeric
characters. The first character of a filename must be
alphabetic, and the first six characters of a filename
must be a unique combination. Embedded blanks are not
allowed. Filenames are left-justified in the fields
in which they appear.
Field Name - Up to six alphabetic and numeric
characters. All the restrictions listed above for
filenames also apply to field names.
Special Characters - The 91 nonalphanumeric ASCII characters.
Total Time - The time after a control break when operations
for a control group occur. (See paragraph 1.1.4.)
CHAPTER 2
RPG II SPECIFICATIONS FORMS
As described in Chapter 1, an RPG II source program consists of a
series of records or lines originally written on formatted coding
sheets called RPG II Specifications forms, and transcribed into
machine readable form. There are seven different RPG II
Specifications forms, each designed for a specific purpose; not all,
however, are mandatory for a given job.
Table 2-1 lists the seven forms in the order in which they appear in
the source program and indicates the minimum and maximum number of
lines allowable.
2.1 QUICK REFERENCE CHARTS
The following pages contain a separate chart for each of the seven
RPG II Specifications forms. Each chart presents a summary of the use
and content for entries on the form.
For readers already familiar with RPG or RPG II, these reference
charts should be basically self-explanatory. Should the reader
encounter an entry whose usage or content differs from the RPG version
with which he is familiar, he can refer to the detailed description or
further clarification.
For readers new to RPG II, these charts will serve as a general
overview of the RPG II Specifications forms. After scanning them and
becoming familiar with the basic purpose of each, these readers should
continue with Chapters 3 through 10.
Once the user begins working with RPG II, he will find these charts
helpful as a reference source for refreshing his memory or checking
the correctness of entries. DIGITAL also supplies these forms as
separate forms guides.
RPG II SPECIFICATIONS FORMS Page 2-2
Table 2-1
RPG II Specifications Forms: Minimum Required
and Maximum Allowable
Form Type Minimum # of Maximum # of
Lines Required Lines Allowed
Control Specification 1 1
File Description Specifications 1 20
Extension Specifications 0 NSL
Line Counter Specifications 0 2
Input Specifications Lines required
to describe one NSL
input file
Calculations Specifications 0 NSL
Output-Format Specifications Lines required
to describe one NSL
output file
The minima given for Input and Output are practical limits. A working
RPG II program could be run with special I/O commands from Form C, and
no Form I or no Form O. That would be unusual, however.
NSL = No Specific Limit -- depends on a combination of factors, such
as core memory available and space used by other components.
RPG II SPECIFICATIONS FORMS Page 2-3
RPG II SPECIFICATIONS FORMS Page 2-4
RPG II SPECIFICATIONS FORMS Page 2-5
RPG II SPECIFICATIONS FORMS Page 2-6
RPG II SPECIFICATIONS FORMS Page 2-7
RPG II SPECIFICATIONS FORMS Page 2-8
RPG II SPECIFICATIONS FORMS Page 2-9
CHAPTER 3
COMMON ENTRIES
This chapter describes Specifications Form entries that are common to
all RPG II coding sheet formats, except the forms described in Chapter
11. The common entries are:
Columns 1-2 Page Number Page and line together
make up the "Sequence
Columns 3-5 Line Number Number".
Column 6 Form Type
Column 7 Comments
Columns 75-80 Program Identification
3.1 PAGE NUMBER
Column Values
1-2 01-99
These columns ordinarily receive the number filled in at the upper
right corner of each coding sheet. Those specification types used
must come in the following order:
Control Specifications
File Description Specifications
Extension Specifications
Line Counter Specifications
Input Specifications
Calculation Specifications
Output - Format Specifications
A specifications type may require more than one sheet, but the listed
COMMON ENTRIES Page 3-2
order by type must be maintained.
3.2 LINE NUMBER
Columns Value
3-5 Any 3-digit number
Most of the lines on each form have two-digit numbers already printed
in columns three and four. If the line number is completed by
entering a zero in column 5, the lines are numbered by tens on each
specifications page. This is a helpful convention, because it allows
the user to subsequently insert lines without re-numbering.
Programmers can use the unnumbered lines at the bottom of the form for
insertion.
3.3 FORM TYPE
The form type is preprinted in column six on each Specification Form.
The compiler uses this column to determine the type of specification
of each source statement.
Column Values Meaning
6 H Control Specifications
F File Description Specifications
E Extension Specifications
L Line Counter Specifications
I Input Specifications
C Calculation Specifications
O Output-Format Specifications
3.4 COMMENTS
Column Values Meaning
7 * This specification contains comments
only
COMMON ENTRIES Page 3-3
blank This is a normal specification line
The compiler treats as a comment any line containing an asterisk in
column 7. Columns following the asterisk may contain any ASCII
characters. The compiler checks the sequence and prints comments
lines in the source program listing. Otherwise, it ignores them.
3.5 PROGRAM IDENTIFICATION
Columns Values
75-80 Blanks or a valid RPG II name
This field has meaning only on the Control Specification; for other
form Specs. it will be listed but otherwise ignored by the compiler.
RPG treats the name entered in columns 75-80 of the Control
Specification as the internal program name, and includes it on the
header of the listing.
CHAPTER 4
CONTROL SPECIFICATIONS -- FORM H
The Control Specifications form is optional. In the absence of a
Control Specification form, a blank form is assumed. The shaded areas
of Figure 4-1 indicate the areas of the form containing information
pertinent to the RPG II compilation. Other columns, except those
listed in Chapter 3, should contain blanks.
4.1 OBJECT PROGRAM EXECUTION SIZE
Columns Value Meaning
13-14 Blank The object program will be compiled to
use as much space as necessary. No
check is made to see if this much is
available.
01-64 The main storage available for program
execution.
Use columns 13-14 to specify some multiple of 1K words of storage (K =
1024).
Columns 13-14 define the main storage available for program execution
(not including storage space requirements for the runtime system).
The entry must end in column 14.
Because the current runtime system does not expand the user's program
storage space dynamically, these columns have little practical use.
4.2 DEBUG
Column Values Meaning
15 blank Do no DEBUG operations.
1 Do any requested DEBUG operations.
CONTROL SPECIFICATIONS -- FORM H Page 4-2
The DEBUG specification indicates whether or not a DEBUG operation
will (1) or will not (blank) be performed. (Chapter 9 explains the
DEBUG specification.) A DEBUG operation will be performed only when
requested by this specification and by a DEBUG operation code on a
Calculations Specifications form. Thus, when a program has been
debugged, the only change required to eliminate the DEBUG checks is in
this one column of the Control Specification.
4.3 FORMS POSITIONING
Column Values Meaning
41 Blank No forms positioning required.
1 Forms positioning required.
Users should specify forms positioning when line printer output must
go onto pre-printed forms, such as check blanks. When requested,
forms positioning allows the operator to correctly position output
forms by first printing a test line.
When forms positioning has been specified, RPG II enters the 1P Halt
Procedure (see Appendix E). A BYPASS response will continue the
execution; a CONTINUE response will give another 1P line and a
repetition of the Halt Procedure.
Forms positioning may only be used when the printer is directly
assigned to the user's job. It will not work properly when the
printer spooler is intercepting output.
CHAPTER 5
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F
Programmers must name and describe all files to be handled at runtime
on Form F, the File Description Specifications. Figure 5-1
illustrates the File Descriptions Specifications Form. Form F
describes all files except compile-time tables and arrays. Those are
described only on Form E. Information about file records must appear
on other forms, depending on the type of file:
Input data records are described on Input
Specifications -- Form I
Output data records are described on Output Format
Specifications -- Form O
Update records are described on both Form I and Form O
In addition, Record Address files and Pre-execution and Execution time
tables and arrays are further described on Extension Specifications --
Form E. Display File records need no extra forms.
Each file requires a single line of Form F. RPG programs can handle a
maximum of sixteen files.
5.1 FILENAME
A unique filename identifies each file to be handled by the object
program.
Columns Value
7-14 Any valid RPG II filename
Use columns 7-14 to assign a unique filename to every file used in
your program except compile time table and array files, which must not
be named on the File Descriptions Specifications sheet. The filename
can be from 1 to 8 characters long, must begin in column 7, and must
be a valid RPG II name. The filename can be the same as a field name.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-2
Pre-execution time table and array files are described on the File
Description Specifications sheet. More than one table or array file
can be described for device READ01, but the File Description entries
must be in the same order as the tables that are to be loaded. Thus
if you are going to load tables TABA and TABB from READ01, and TABA is
associated with FILEA, and TABB with FILEB; if the data for TABA is
to be loaded first, the File Description entry for FILEA must precede
that for FILEB.
5.2 FILE TYPE
Column Value Meaning
15 I Input file
O Output file
U Update file
C Combined file
D Display file
Use column 15 to identify the way in which your program is to use the
file.
5.2.1 Input File
Input files are records that the program uses as a source of data.
When input files are described in a program it indicates that records
are to read from the file. All input files except table and record
address files must be further defined on the Input Specifications
sheet. Table and record address files must be further described in
the Extension Specifications.
5.2.2 Output Files
Output files are records that are written or printed by a program.
All output files, except table and array output files, must be further
described on the Output Format Specifications Sheet.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-3
5.2.3 Update Files
Update files are disk files from which a program reads a record,
updates fields in the record, and writes the record back in the same
location from which it was read. Update files must be further
described on both the Input Specification sheet and the Output Format
sheet. A record in an update file can be updated only once during a
cycle (see Output File - Output Indicator description). A chained
file or a demand file may be updated at detail time, total time, or
execution time. All other files should be updated only at detail
time, during the same program cycle that reads the record, otherwise,
results of the update will be unpredictable at best.
5.2.4 Combined Files
A combined file is both an input and an output file. A combined file
can only be assigned to the simulated MFCU. A program reads records
from a combined file and includes output data on the records in the
file. The result is one file that contains both input and output
data. Combined files must be further described on both the Input
Specification Sheet and the Output Format Sheet.
Do not condition output to a combined file such that more than one
record can satisfy the output conditions during the same cycle. (This
condition should not exist for the entire detail output cycle, even if
output is going to more than one combined file.)
All output records to a combined file are stored in a hold area until
another record is read from the combined file. The output record is
punched just prior to the time the next record is read.
Since each record stored in the hold area overlays and replaces any
previous record in the hold area, only one record can be available as
output to a combined file during any one RPG II cycle. This record
will be the last record that satisfied output conditions during the
cycle.
5.2.5 Display Files
A display file is a collection of information from fields used by a
program. The DSPLY operation code must be used on the Calculation
Specification Sheet in order to print a field or record directly from
storage and/or key data into a field or record in storage. Display
files need only be described on the File Description Specifications
Sheet. The device associated with a display file must be an
interactive terminal (CONSOLE). See DSPLY in Chapter 9 for more
information.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-4
5.3 FILE DESIGNATION
Column Value Meaning
16 P Primary file
S Secondary file
C Chained file
R Record Address file
T Table or array file (pre-execution
time tables or arrays)
D Demand file
Use column 16 to further identify the use of input, update, combined,
and chained output files. Leave this column blank for display files
and all output files except chained output files (direct load).
5.3.1 Primary Files
A primary file is the main file from which a program reads records.
In multifile processing the primary file is used to control the order
in which records are selected for processing. It can be an input,
update, or combined file. In programs that read records from only one
file, that file is the primary file. Every program must have exactly
one primary file.
5.3.2 Secondary Files
Secondary files apply to programs that do multifile processing. All
of the files involved in multifile processing, except the primary
file, are secondary files. A secondary file can be an input, update,
or combined file. Secondary files are processed in the order in which
they are written on the File Description Specifications Sheet.
Note that table, chained, record address, and demand files are not
involved in record selection in multifile processing. See Multifile
Processing (columns 61-62) in Chapter 8 for more information on
primary and secondary files.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-5
5.3.3 Chained Files
A chained file is a disk file that is read randomly or loaded directly
via the CHAIN operation code.
A chained file can be an input, output, or update file. See Column 28
(Mode of Processing, Random) in this chapter, and the CHAIN operation
code in Chapter 9 for more information.
5.3.4 Record Address Files
A record address file is an input file that indicates which records
are to be read from a disk file, and the order in which those records
are to be read. A record address files must be further defined in the
Extension Specifications.
Record address file contain binary relative record numbers. Because
the record number are stored as 18-bit binary numbers, record address
files can only reside on disk or tape.
Record address files on disk are call ADDROUT (address output) files.
They can be produced by a disk sort program and can be used with any
type of disk file, except ISAM files. See Column 28 (Mode of
Processing, via ADDROUT) in this chapter for more information.
5.3.5 Table Or Array Files
A table or array file is a sequential input file that contains table
or array entries. The entries can be read into the program during
compilation or immediatly before execution of the program. Only
pre-execution time table or array files are described on the File
Description Sheet. However, both pre-execution and compile time
tables and arrays must be described on the Extension Specifications
sheet.
A table or array output file (written or punched after LR output) is
defined as a normal output file and does not require an entry in
column 16.
Table and array files are not involved in record selection and
processing. They are only a means of supplying entries for tables and
arrays used by the program. When table or array files are read during
the execution of the program, the program reads all the entries from
the table and array files before it begins record processing. See
Tables and Arrays in Chapter 6 for additional information.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-6
5.3.6 Demand Files
Demand files can be input, update, or combined files. The READ
operation code must be used on the Calculation Specification Sheet in
order to read from a demand file. Demand files may be processed
either sequentially by key, or consecutively. See the READ operation
code in Chapter 9 for a discussion of the processing of demand files.
5.4 END OF FILE
Column Value Meaning
17 Blank a. If none of the Primary, Secondary,
or Record Address files has an 'E'
in its specification, RPGLIB will
read all such files to their end.
b. If any has an 'E' in its
specification, those with a blank
in column 17 need not be read to
end of file.
E RPGLIB will read this file to its end
before performing end-of-job process-
ing.
In single file processing, RPGLIB will read the Primary File to its
end, regardless of column 17 in the File Specification.
In multi-file processing, RPGLIB will process all files to
end-of-file, unless some have an "E" in column 17 of their
Specifications. In that case, it will process all files with an "E"
to their completion.
EXCEPTION: When the primary file is the only file with an "E" in
column 17, and a matching records operation has been specified between
it and one or more secondary files, and record(s) in the secondary
file(s) which match the last record of the primary file are read and
processed before end-of-job operations.
When processing with a Record Address file, end-of-file processing is
specified for the Record Address file, not for its object file.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-7
5.5 SEQUENCE
Users may request RPGLIB to monitor the order of input records.
Column Values Meaning
18 Blank RPGLIB need not check sequence
A This is a sequential primary or
secondary file. The value of the
fields specified by M1-M9 should be
lowest in the first record, and equal
or higher in each succeeding record.
D This is a sequential primary or
secondary file. The value of the
fields specified by M1-M9 should be
highest in the first record, and equal
or lower in each succeeding record.
An entry in column 18 is required when matching fields (columns 61-62)
are specified on form I. Files with matching fields must be either
all Ascending or all Descending. This column does not apply to tables
and arrays, Chain, Demand or Record Address files.
5.6 FILE FORMAT
Column Value
19 F
Column 19 must contain an F to indicate that all the records in the
file have a fixed length.
5.7 BLOCK LENGTH
Column Value Meaning
20-23 1-4096 Number of characters in each logical
block of a file
Block length must either equal the record length value specified in
columns 24-27, or it must be an integer multiple of record length.
Block length can not be greater than the maximum record length for the
device.
The blocking factor of a file is calculated by dividing the Block Size
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-8
by the Record Length. If the block and record sizes are equal, RPG II
calculates the optimum blocking factor based on the file devices
physical characteristics. All ASCII files are unblocked.
5.8 RECORD LENGTH
Columns Values Meaning
24-27 1-4096 Number of characters per record
These columns specify the length of all records in the file. For an
Update file, record length must not vary between input and output
phases. The value is right-adjusted, and leading zeroes may be
suppressed. The maximum record length for each device type is as
follows:
Device Maximum Record Length
MFCU 96
READ01 80
PRINTER 132
CONSOLE 132
DISK 4096
TAPE 4096
5.9 MODE OF PROCESSING
RPGLIB must know in advance how it will process each file.
Column Values Meaning
28 Blank a. Access will be consecutive, or
b. Access will be sequential, in the
order the records appear in the
index. This is called sequential
by key.
R a. Access will be random by relative
record number or by key, or
b. An ADDROUT record address file
will determine access, or
c. This will be a direct (random)
file load.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-9
Users must coordinate the file type (column 16) with the file
processing mode (column 28), the record address type (column 31), and
the file organization (column 32) for all Input and Update files.
Input files not resident on disk have sequential organization and must
be accessed consecutively. Such files must be designated Primary,
Secondary, Demand, Table/Array, or Record Address with record key
limits and their specifications must contain blanks in columns 28 and
31, and blank or 1-9 in 32.
Direct or indexed Input and Update files must reside on disk. Table
5-1 illustrates the legal combinations of entries in columns 16, 28,
31, for any Input or Update files stored on disk.
Table 5-1
Legal Combinations for Input or Update Disk Files
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-10
5.9.1 Consecutive Processing (Blank In Column 28)
Consecutive processing occurs when a program examines each record as
it occurs on a medium.
RPGLIB can do consecutive processing on files on any device; it can
only do consecutive processing on non-random access devices. The
nature of such devices requires RPG II to examine each record as it
appears -- for example, one card after the other.
Disk allows several file organizations. The only ones suited for
consecutive processing are sequential and direct organizations. A
sequential organization occurs when records come one right after the
other, just as in a card deck or magnetic tape. A direct organization
is similar to sequential, but gaps may occur in the file, to allow for
future additions. (One might simulate direct organization in a card
file by inserting blank cards every so often.) The gaps are really
records filled with blank characters. Users should test for such gaps
when processing a direct organized file.
5.9.2 Sequential Processing Of Indexed Files By Key (Blank In Column 28)
Sequential processing by key is similar to consecutive processing in
that the index entries are accessed consecutively, but the data
records of the file are processed in the order determined by the
index. Primary, Secondary, and Demand files may be processed
sequentially by key. Sequential processing by key requires an indexed
file. Files with indexes work just like books with indexes. In
books, key words are scattered all through the volume. The index
lists the key words in alphabetic order, and gives their location. In
an indexed file, records may be scattered here and there on the
device, but the index lists the record keys in an order, and gives the
record location within the file.
Indexed files are a little more complicated than books, because book
indexes are always in alphabetic order, but file indexes may have one
of a variety of orders. For example, in a file that contains
information about employees, an index might be ordered by employee
name, employee number, employee address, department, or salary.
Whichever field governs the order of the index is called the key.
Each index entry contains the key value and number of each record in
the file. Keys must always have an ascending order before RPGLIB can
process an indexed file.
5.9.3 Processing By ADDROUT File (R In Column 28)
A sort utility program can produce ADDROUT files, which are Record
Address files containing record numbers. They are similar to the
indexes for indexed files, but they do not contain keys. When a
programmer has produced more than one ADDROUT file, he can process the
same data file in one order one time and in another order (with a
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-11
different ADDROUT file) at a different time. Although ADDROUT files
may reside on disk or magnetic tape, their object files (the files
they point to) may reside only on disk.
5.9.4 Random Processing (R In Column 28)
Random processing applies to Chained files and occurs only when
requested by a CHAIN operation code. (CHAIN is described in paragraph
9.4) CHAIN retrieves records from sequential and direct files
according to a record number. With indexed files, record retrieval is
based on a key value in the record.
5.10 LENGTH OF KEY OR RECORD ADDRESS FIELD
Indexed files and ADDROUT files must have an entry in this field.
Columns Values Meaning
29-30 Blank Output, Input, Update or Demand file
to be processed sequentially, or
chained file by relative record
number.
1-64 Indexed file with key length as
entered.
The value must be right-justified in the field, and leading zeroes may
be suppressed.
5.11 RECORD ADDRESS TYPE
This entry gives more information about how RPGLIB is to retrieve
records from the file.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-12
Column Values Meaning
31 Blank a. Output file, or
b. Chained sequential/direct file, or
c. Input or update file, and access
will be consecutive.
A Access will be via an alphameric key.
I a. This is an ADDROUT file, or
b. This file will be processed via an
ADDROUT file.
5.12 TYPE OF FILE ORGANIZATION
This entry gives additional information about file organization.
Column Values Meaning
32 I Indexed (ISAM) file
T ADDROUT file
Blank Sequential or direct file
NOTE: ISAM files require an "A" in column 31.
5.13 PRINT FILE OVERFLOW INDICATOR
This entry allows the user to name an overflow indicator to be
associated with a print file.
Columns Value Meaning
33-34 Blank a. Not a print file, or
b. Print file with no overflow
indicator associated with it.
OA-OG or OV Print file, and the name of its
overflow indicator is the two
characters entered.
The overflow indicator is associated with the area of the print page
starting with the overflow line and ending with the bottom of the
page. This area is called the overflow area, and it can be specified
via Form L (see Chapter 7). RPGLIB turns on the named overflow
indicator when a space or skip terminates in the overflow area.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-13
Paragraph 10.5 discusses overflow in detail.
Overflow indicators can be turned on and off by SETON and SETOF
operation codes and may be used with control level indicators L0-L9.
Use of overflow indicators with other indicators may cause a variable
number of lines to be printed on successive pages. The user should
take care to leave enough room for the maximum, and yet retain good
spacing on the page when few lines are printed.
5.14 KEY FIELD STARTING LOCATION
RPG II must know the location of the key field in the records of
indexed files. This entry specifies the first (high order) position
of the key field.
Column Values Meaning
35-38 Blanks Not an indexed file.
1-4096 Indexed file; the key starts at the
character with the number entered.
The entry must be numeric and right justified. Leading zeroes may be
omitted.
An entry of blanks or zeroes in columns 35-37, and 6 in column 38
specifies the key field starting location in the example above.
5.15 EXTENSION CODE
Print files, Record Address files, tables and arrays may require a
Form E or L for a complete specification. This entry indicates that
such a form has been prepared.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-14
Column Values Meaning
39 Blank No additional form has been prepared.
E An extension Specification (Form E)
has been prepared for this file.
Tables, arrays, and Record Address
files require Form E specifications.
L A Line Counter Specification (Form L)
has been prepared for this print file.
5.16 DEVICE CODE
By the nature of files, each one is associated with a device. This
entry names that device.
Columns Values Meaning
40-46 DISK A disk device (DSK:)
READ01 A card reader (CDR:)
PRINTER A line-printer (LPT:)
PRINTR A line-printer (LPT:)
TAPE A mag-tape (TAPEn:, where n is unit
number)
CONSOLE A console device (TTY:)
MFCU1 Simulated MFCU input hopper 1
MFCU2 Simulated MFCU input hopper 2
44 0-7 Unit number (for TAPE only)
Names must be left-justified (start in column 40) in the field.
5.17 FILENAME
Use this entry to define a filename to a file.
Columns Values Meaning
47-52 Blanks This file is not associated with a
multiple file device.
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-15
Valid DEC-10 Filename This entry defines the six-character
filename to be used for this file.
Since file-structured devices contain more than one file, RPGLIB must
have some way of choosing a particular file. Whenever a file is
assigned to a file-structured device, either by entering "DISK" in
columns 40-45, or via use of logical device names; an entry must be
made in these columns.
It is often convenient to define a filename in these columns for all
files, even if they are never planned to be used with a
file-structured device. If a case arises, such as debugging, where a
file formerly assigned to a non-file-structured device must be
changed, it makes the change a matter of assigning logical device
names at the monitor level, rather than having to supply a new F card.
5.17.1 Default Extensions
In addition to the six character filename, the DECsystem-10 also uses
a three character extension to define a unique file. Because there is
no room on the F card to supply this extension, it is defaulted as
follows:
Extension Type of File
MF1 MFCU input hopper 1 file
MF2 MFCU input hopper 2 file
ST1-ST4 MFCU output stackers 1-4 (These files
are assigned automatically by RPG II
as the simulated MFCU output files)
IDX ISAM file index
IDA ISAM file data portion
RGA ADDROUT file
RGD Any file not described above
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-16
5.18 CONTINUATION LINES
Continuation lines provide further information on the file being
defined. In particular they allow a file to be declared as an ASCII
format file.
5.18.1 Column 53
Column Values Meaning
53 Blank No continuation line follows this card
K A continuation line follows this card
To specify that this F card is followed by a continuation card, a K
should be entered in column 53.
5.18.2 Continuation Lines Option
These options are placed in the columns listed below, on the card
immediatly following the one containing the K in column 53.
Columns Value Meaning
54-59 ASCII The file is defined as being in ASCII
format
5.19 FILE ADDITION AND UNORDERED OUTPUT
Column Values Meaning
66 Blank a. Input file, or
b. Non-indexed Output or Update file.
A a. Pre-existing indexed file, and the
current program will be adding new
records by key, or
b. Pre-existing disk or Magtape file,
and the current program will be
adding records to the end.
Note that files with non-blank entries must be disk or magtape files.
In particular, they must be indexed, sequential or direct. (Direct
files are consecutive files with gaps for adding records.) Further,
when adding records to a pre-existing Indexed file which is being
processed sequentially by key, the key value of the added record must
FILE DESCRIPTIONS SPECIFICATIONS -- FORM F Page 5-17
fall between those for the last and next records processed from that
file.
When there is an "A" in column 66, RPGLIB will add new records to the
ends of files. EXCEPTION: the CHAIN operation allows insertion of
new records within Direct files.
A program may add records to a file at detail, total, or exception
time. Records to be added must be identified by an "ADD" entry in
columns 16-18 of the corresponding Output/Format Specifications (FORM
O).
NOTE
On the DECsystem-10, all indexed files
must be created by the ISAM program.
Once a file has been created via the
ISAM program, it may be loaded via an
RPG II program, however, RPG II is not
capable of creating indexed files ex
nihilo.
5.20 TAPE REWIND
This column specifies positioning for magnetic tape units.
Column Value Meaning
70 R Rewind tape at end of file
U Unload tape at end of file
N Leave tape at end of file
Blank Leave tape at end of file
CHAPTER 6
EXTENSION SPECIFICATION -- FORM E
RPG II requires more information about Record Address files, Tables
and Arrays than space on the File Specification Form permits. The
Extension Specification gives the required extra information, and
allows the complete description of Compilation time Tables and Arrays.
Figure 6-1 shows the positions used for the four types of datasets
described on Extension Specifications:
1. Compilation time Tables and Arrays,
2. Pre-execution time Table and Arrays,
3. Execution time Arrays, and,
4. Record Address files.
Chapters 12 and 13 contain comprehensive discussions of Table and
Array organization and usage, and of disk file operations involving
Record Address files.
6.1 FROM FILENAME
Pre-execution time Tables and Arrays and Record Address files require
this entry.
Columns Values Meaning
11-18 Blanks Compilation or Execution time Table or
Array.
Filename Name of Record Address file, or name
of Input file that contains
pre-execution time Table or Array
data.
The name must be left-justified in the field, and must be the same as
a filename in the File Description Specifications.
EXTENSION SPECIFICATION -- FORM E Page 6-2
6.2 TO FILENAME
For Record Address files, this entry specifies the data file to be
used with the Record Address file. For Tables and Arrays, this entry
specifies the name of an output file to receive the data file. An
Execution time array may not be written out in this manner.
Columns Values Meaning
19-26 Blanks Execution time array, or Table or
Array with no associated output file.
Filename a. Record Address file: this entry
names the data file associated
with the Record Adress file.
b. Compilation or Pre-execution time
Table or Array: this entry names
the file to receive the table or
array after compilation or
execution.
The name should be left-justified in the field, and it must be the
same as a filename in the Field Description Specifications.
6.3 NAME OF TABLE OR ARRAY
Record Address files must have no more entries after column 26, except
for comments.
Columns Values Meaning
27-32 Blanks Record Address file
Name Name of a Table or Array
All names must be valid RPG II names. Table names must start with
"TAB"; array names must not. If the form describes an alternating
(paired) Table or Array, this is the name of the first one -- the
other appears further on. The name should be left-justified in the
field.
EXTENSION SPECIFICATION -- FORM E Page 6-3
NOTE
RPG II processes table and array files
in the order they appear in the Form E
Specifications. In particular, when
more than one Form E references the same
file or device, RPG II expects the
tables in the order of the Form E
Specifications (for Input files) and
writes them out in the order of the Form
E Specifications (for Output files).
6.4 NUMBER OF ENTRIES PER RECORD
This field pertains to Compilation and Pre-execution time Tables and
Arrays. It indicates how many entries will be present in each
physical record. EXAMPLE: In a card file, this entry shows the
number of entries on each card.
Columns Values Meaning
33-35 Blanks Record Address file or Execution time
Array
1-999 Compilation or Pre-execution time
single Table or Array: entry
indicates the number of arguments in
each physical record, or
Compilation or Pre-execution time
paired (alternating) Table or Array:
the entry indicates the number of
pairs of arguments in each physical
record.
All records except the last must have the same number of arguments.
The last record may have fewer. Entries must begin in the first
position of the record, and no spaces may occur between entries in a
single record. No entry may start in one record and finish in the
next.
EXTENSION SPECIFICATION -- FORM E Page 6-4
EXAMPLE:
This is a table file on punched cards. Arguments have eleven
characters, and there are seven entries per record.
EXAMPLE:
This is a file of related tables on punched cards. Arguments come in
pairs -- a five-character item followed by a seven-character item.
There are six pairs of entries per record, even though the card has
unused columns that could contain another five-character item. Pairs
must not be split across record boundaries.
The table name of items 1A, 2A, etc. would appear in columns 27-32.
The table name of items 1B, 2B, etc. would appear in columns 46-51.
The number of entries per record field must be numeric and right
justified. Leading zeroes may be omitted. These columns must be
blank for execution time arrays.
6.5 NUMBER OF ENTRIES PER TABLE OR ARRAY
This field specifies one of two things:
1. The exact number of entries or pairs of entries in the entire
table or array, when full, or
2. the maximum number of entries a table or array may have if
not full (termed a "short" table or array).
EXTENSION SPECIFICATION -- FORM E Page 6-5
Columns Values Meaning
36-39 Blanks Record Address file.
1-999 Table or Array: see above.
The number of entries must be numeric and right-justified. Leading
zeroes may be omitted.
6.6 LENGTH OF ENTRY
Columns Values Meaning
40-42 Blanks Record Address file.
1-256 Entry specifies the number of
character positions of the table or
array with the following maximum
values:
a. 256 if alphanumeric
b. 15 if numeric
For paired (alternate) Tables or Arrays, this entry refers to the
length of entries in the first. The length entered in columns 40-42
must be right-justified. Leading zeroes may be omitted.
Physical Aspects of Tables: In the file that contains tables and
arrays, numeric items which are shorter than the length specified must
be padded with leading zeroes or blanks. Short alphanumeric items
must be padded with blanks on either end.
6.7 DATA FORMAT
Column Value
43 Blank
All Extension Specification cards must contain a blank in this column.
DECsystem-10 RPG II supports only alphanumeric and unpacked decimal
format.
EXTENSION SPECIFICATION -- FORM E Page 6-6
6.8 DECIMAL POSITIONS
Column Values Meaning
44 Blank a. Record Address file, or
b. Data will be alphanumeric.
0 Data will be decimal integers.
1-9 Data will be decimal numbers, with the
indicated number of places after the
decimal point.
6.9 SEQUENCE
The order of a table or array (if any) determines how RPG II will
perform LOKUP operations.
Column Values Meaning
45 Blank Record Address file, or entries are in
arbitrary order
A Entries are in ascending order
D Entries are in descending order
Consecutive equal entries are always considered to be in sequence.
Column 45 refers only to the first of alternate (paired) Tables or
Arrays.
EXTENSION SPECIFICATION -- FORM E Page 6-7
6.10 ALTERNATE TABLE OR ARRAY
When a specification describes paired or alternate Tables or Arrays,
columns 46 through 57 describe the second one. The rules listed for
the first one apply to the second. Note that the two names must both
be unique. Corresponding field positions are the following:
Field First Table or Array Second Table or Array
Name 27-32 46-51
Length of 40-42 52-54
entry
Data format 43 55
Decimal 44 56
Positions
Sequence 45 57
A table may not be paired with an array.
6.11 COMMENTS
Columns Values
58-74 Any ASCII characters
The comments field does not affect compilation or object program
execution, but it is useful in program listings for later analysis,
checkout and documentation.
CHAPTER 7
LINE COUNTER SPECIFICATIONS -- FORM L
The Line Counter Specifications form (Figure 7-1) is used for all
printer output files with an L in column 39 of the corresponding File
Description Specification (FORM F). Form L specifies form size and
overflow line. When a printer file does not have a Form L, RPG II
uses default values of 66 lines per page and an overflow line at 60.
7.1 FILENAME
Columns Values Meaning
7-14 filename Filename entered on the corresponding
form F.
The device assigned to the corresponding file must be a line printer.
7.2 NUMBER OF LINES PER PAGE
Columns Values Meaning
15-17 Blanks The user wishes the default -- 66
lines per page
1-112 The entry specifies the exact number
of print lines available on a page
(exact number of lines from one top of
form to the next)
The entry must be numeric and right-justified. Leading zeroes may be
suppressed.
LINE COUNTER SPECIFICATIONS -- FORM L Page 7-2
7.3 FORM LENGTH
Columns Values
20-22 FL
This field must contain the characters FL to indicate that the
preceding field defines form length.
7.4 OVERFLOW LINE NUMBER
Columns Values Meaning
20-22 Blanks The user wishes the RPG II default of
line 60.
1-112 Spaces, skips, or print operations
that terminate on or before this line
will set overflow conditions.
See also paragraph 5.13. Different overflow lines can be specified
for individual printer files. This may be necessary for varying
numbers of lines printed in overflow conditions.
Use of overflow indicators with other indicators may cause a variable
number of lines to be printed on sucessive pages. The user should
take care to leave enough room for the maximum, and yet retain good
spacing on the page when few lines are printed.
7.5 OVERFLOW LINE
Columns Value
23-24 OL
This field must contain the letters OL to indicate that the preceding
field defines an overflow line.
CHAPTER 8
INPUT SPECIFICATIONS -- FORM I
Form F describes all files except compile time tables and arrays.
Form I, Input Specifications, describes the records of input and
update files. Each file consists of one or more record types and each
record type may consist of one or more fields. Form I has a section
for records, and one for fields. Record descriptions go in the
columns labeled Record Identification (columns 7-41, Figure 8-1).
Descriptions of the fields within that record type go in columns
43-70, field description, of as many succeeding lines as required--
one line for each field. Then the next record type may be described,
and so on, until all record types and fields have been described.
8.1 FILENAME
This entry names the file that holds the record. The filename
provides the link between information contained on Form F and Form I.
Columns Values Meaning
7-14 blanks a. Field descriptor
b. File name is the same as that on
the last record description.
Filename from
a Form F entry Named file.
The name of every input or update file (except table input files and
record address files) described in form F must be entered on this
sheet. The filename must be the first line that contains information
concerning the records in that file. If the filename is omitted, the
last filename is assumed to be the file being described. All the
records and fields for one file must be completely described before
another file is described.
INPUT SPECIFICATIONS -- FORM I Page 8-2
8.2 SEQUENCE
This entry allows users to tell RPGLIB to check for a sequence of
record types.
Columns Values Meaning
15-16 blanks a. Field description, or
b. AND or OR line
01-99 RPGLIB will perform sequence checking
AA-ZZ This record type not part of a
sequence. Note that "ND" and "R " are
not permitted as they would interfere
with AND/OR lines.
This field may contain an alphabetic or numeric code. The alphabetic
code may be any two alphabetic characters (e.g., AA, BC, DQ) and
signifies that this specific record type is not part of a
predetermined sequence. The record may appear at any time in the
file, so long as it does not interrupt some other sequence. Chained
files require alphabetic sequence codes.
A numeric code (01-99) specifies sequence checking. The codes must be
in ascending order for each record type checked. This gives the
correct order for records in the sequence. The first record type in a
sequence must have 01 in columns 15-16. There may be only one
sequence per file. Note that the leading zero must be entered in
column 15. Records to be sequence-checked also must be specified on
the form in the order in which they should occur when read from the
file. When these columns contain a numeric entry, an entry must be
made in column 17, and an entry in column 18 must be considered.
Note that this type of sequence checking ensures only that record
types appear in a given order in the file. A sequence specification
on Form F causes sequence checking based on matching record
specifications.
In the Form I entries for a file, record types with alphabetic
sequence specifications must come before those with numeric entries.
AND and OR lines (description continuation lines) must not have
entries in these columns. Presumably, the line preceding the AND or
OR line specifies any required sequence checking.
If sequence checking is specified and RPGLIB detects a sequence error,
it enters a Halt Procedure. Halt Procedures are defined more fully in
Appendix E.
INPUT SPECIFICATIONS -- FORM I Page 8-3
8.3 NUMBER
Users must make an entry here if columns 15-16 have a numeric entry.
This column indicates whether more than one record of a type may be
present before a different record type is encountered.
Column Values Meaning
17 blank Column 15-16 contain alphabetic
characters or blanks.
1 Only one record of this type may
appear in the sequence of each group.
N Multiple records of this type may
appear before a record type change of
each group
8.4 OPTION
Column Values Meaning
18 blank a. No record type sequence checking
is to be performed (columns 15-16
are alphabetic).
b. Record type sequence checking is
being done and this type must be
present in each group (columns
15-16 numeric) except the last
group which isn't checked.
O Record type sequence checking is is
being performed and this type may or
may not be present in each group
(columns 15-16 numeric).
An entry should not be made in this column for lines which have an AND
or OR relationship with a preceding line. The first line of an AND/OR
relationship specifies the column 18 option.
8.5 RECORD IDENTIFYING INDICATOR AND LOOK-AHEAD FIELD
Each different type of input or update record may have an identifier
encoded in columns 19-20.
INPUT SPECIFICATIONS -- FORM I Page 8-4
Columns Values Meaning
19-20 blanks a. Field description, or
b. No destinction need be given this
and the preceding record type.
01-99 General record identifying indicator
(RII)
L1-L9 Control level indicator used as a
record identifying indicator when
record type rather than control field
triggers a control break.
H1-H9 Halt indicator to be set when RPGLIB
encounters this type.
LR Last record indicator -- simulates
end-of-file condition.
** Look-ahead field
When RPGLIB selects a record for processing and identifies it, it sets
on the indicator specified by this entry. Users can specify this code
to condition functions and operations in Calculations Specifications,
Output-Format Specifications and additional Input Specifications.
The entry in columns 19-20 may be unique for each input record type if
desired, but sometimes it is useful to assign the same one to
different record types. Example: a file with several record types,
only the first of which is to be used in a given calculation. The
others are handled by a common subroutine. Assignment of the same
identifying indicator to all but the first type allows a single
indicator to condition the subroutine for all the appropriate records.
When RPGLIB turns on a record identifying indicator, it turns off any
indicator which is on because of a previous record. Exception: when
a record is retrieved by chaining from another record, the indicators
for both records are on simultaneously and can condition further
processing.
When a control level indicator is set on by a record type, lower
levels remain off.
The record identifying indicator field must be blank for AND lines of
an AND relationship. (See paragraph 8.7.)
When a line has a pair of asterisks, fields defined on succeeding
specifications lines are "look-ahead" fields. A look-ahead field can
be examined in the next record of the file, while the current record
is still being processed. For update files, look-ahead fields apply
only to the current record.
Look-ahead fields can not be specified for chained or demand files, or
INPUT SPECIFICATIONS -- FORM I Page 8-5
as array fields. Neither can the fields be altered as a result of
calculations or blank-after operations. Lines containing asterisks
require alphabetic sequence code specifications. Columns 17, 18 and
21-74 must be blank, as well.
Only one set of look-ahead fields can be described per file. The
description applies to all records in the file, regardless of record
type.
If a field is to be available for processing before and after
selection, the field must be described on two specifications lines--
as a look-ahead field and as a normal field.
Look-ahead fields are useful for extending the matching record
capability and for searching for the last record of a control group.
8.6 RECORD IDENTIFICATION CODES - COLUMNS 21-41
These entries tell RPGLIB how to distinguish among record types in a
file. They allow up to three identifying codes per line as indicated
by the 1, 2, and 3 on form I. For more than three codes, additional
lines may be used as described in paragraph 8.7. These lines may be
in an AND or OR relationship. Identification codes on a single line
are considered in an AND relationship: code 1 AND code 2 AND code 3.
If a file contains only one type of record, or if a distinction
between record types is not important, columns 21-41 may be left
blank. If RPGLIB encounters an input record which cannot be
identified, it enters halt procedure "U1". For more data on Halt
Procedures, see Appendix E.
8.6.1 Position
Each record identification code is one character in size. The
position (number of characters from beginning of record) of this
character in the input record goes in 21-24, 28-31, or 35-38,
right-justified.
Columns Values Meaning
21-24, 28-31 blanks No record identification code
or 35-38
1-4096 Position in the record of the
identification code.
If the record identification code is not needed, this field is left
blank.
INPUT SPECIFICATIONS -- FORM I Page 8-6
8.6.2 Not
Column Values Meaning
25, 32, or 39 blank Code in the next two columns must be
present.
N Code must not be present.
8.6.3 C
This entry tells RPGLIB which part of the character in column 27, 34,
or 41 to use for comparison with the input record. This field is left
blank if columns 21-25 are blank.
Columns Values Meaning
26, 33 or 40 blank No entry in 21-24, 38-31 or 35-38,
respectively.
C Full character comparison
A C says the entire character specified in column 27, 34, or 41 is
used for the comparison.
8.6.4 Record Identification Character
Column Values
27, 34, or 41 Blank or any alphanumeric character
RPGLIB will use a character entered here for comparison with the input
record.
8.7 ADDITIONAL RECORD IDENTIFICATIONS
Columns Values
14-16 AND or OR
More than three record identification codes may be designated by
entering the word AND in columns 14 through 16 of the next line and
using columns 21-41 as described in paragraph 8.6.
RPG II allows an OR relationship between record identification codes
INPUT SPECIFICATIONS -- FORM I Page 8-7
for one record type or between record types for efficient field
description when:
One record type can be identified by different combinations of
record identification codes. Example: all records having 'A',
'B', or 'C' in column 1 are to be considered as the same record
type.
Two or more record types have identical field descriptions but
must be considered as different records.
Two or more record types have very similar field descriptions, but
a small number of fields may be in different positions or may
occur in one record type but not the other.
Grouping record types in OR relationships simplifies coding by
allowing their common fields to be specified once only. Those few
fields which are not common can then be linked to their corresponding
record types by entering the record's identifying indicator in columns
63-64 of the field description line (see paragraph 8.14).
OR in columns 14 and 15 specifies the OR relationship.
A maximum of 20 AND and OR lines in any combination may be used to
describe the record identification code.
8.8 FIELD TYPE
Column 43 starts the field description.
Column Values Meaning
43 blank a. Record description, or
b. Alphanumeric or unpacked decimal
field
8.9 FIELD LOCATION
Columns Values
44-51 Two 1-4 digit numbers
Field location designates the starting and ending positions of a field
within a record. The starting position goes in the From Field
Location (columns 44-47); the ending position in the To Field
Location (columns 48-51). A one-position field is designated by
encoding the same position in both the From and To location fields;
otherwise the From location must be smaller than the To location.
INPUT SPECIFICATIONS -- FORM I Page 8-8
Entries must be right-justified; leading zeroes may be omitted.
These entries indicate field position and size. The maximum size for
numeric data is 15 digits; for alphanumeric data, 256 characters.
Fields within a record may be defined in any order. Fields may
overlap and the same positions may be given different field names.
8.10 DECIMAL POSITION
Column Values Meaning
52 blank Alphameric field
0-9 Numeric field - entry gives number of
places to right of decimal
The number entered cannot be larger than the effective field length
designated in Field Location (columns 44-51).
Only numeric fields may be edited or used in arithmetic calculations.
8.11 FIELD NAME
References to input fields require a name; this entry supplies it.
Columns Values
53-58 A valid RPG II field name, array name, array element,
PAGE, PAGE1, or PAGE2
Unused portions of a record need not be named. Different fields in
the same record should have different names; because of this, each
field of a record is defined on a separate line. If a field is to be
used as both an alphanumeric and numeric field, it must be defined
twice by designating two different field names for the same position.
Fields in different record types may have the same name if they have
the same length and format. To avoid duplicate coding to describe the
same field in two or more records, one can use an OR relationship
(paragraph 8.7) to define the field name once for all the records in
which it occurs.
INPUT SPECIFICATIONS -- FORM I Page 8-9
8.11.1 Special Words -- PAGE, PAGE1, And PAGE2
A PAGE entry on the Output-Format Specifications form (Chapter 10)
causes RPGLIB to write page numbers on a print file. An entry of
PAGE, PAGE1, or PAGE2 as a field name specifies that the indicated
portion of the record being defined contains a starting page number
minus one. (When special words are not entered here, page numbering
begins with 1.)
Three special words exist so that three page number counters can
operate in one object program. Because the counters have field names,
they can enter into calculations like other field definitions. The
format specified for a special word name must be numeric with zero
decimal positions. Page numbering is restarted when the specified
field of an input record contains a different value.
8.12 CONTROL LEVEL
Columns Values
59-60 Blanks or L1-L9
These columns allow the specification of a control level indicator.
Control level indicators are ranked from L9 (highest) to L1 (lowest),
but may appear in any order on the Input Specification Form. The L0
indicator is always on, thus may not be used to indicate a control
break.
If RPGLIB encounters a field which has been assigned a control level,
the contents of that field are compared with the contents of the same
field from the previous record. If they are not equal, RPGLIB turns
on the specified control level indicator and all lower control level
indicators.
For example, if the field in question has been assigned a control
level of L4 and a control break occurs, indicators L4, L3, L2, and L1
are turned on. These indicators can control timing of calculations
and output functions.
If the user does not wish lower level calculations performed when
their respective level indicators are turned on by a higher level
control break, he may use the SETOF function on form C.
Users can make several fields in an input record into one control
field by giving them all the same control level indicator. This is
called a split control field. All fields of a given control level
must have the same format and must be specified in adjacent field
description lines. The first field specified is considered the high
order part of the control field; and the last is the low order part;
any in between have the order in which they appear. RPGLIB ignores
decimal positions in control fields.
INPUT SPECIFICATIONS -- FORM I Page 8-10
Control level indicators can not be specified for chained or demand
files.
This entry is left blank if the field being described is not a control
field.
8.13 MATCHING FIELDS
Columns Values
61-62 Blanks or M1-M9
Entries in columns 61-62 indicate fields which are used for matching
of records from different sequential files and for sequence checking
of a single sequential file. Record matching is the technique for
associating records from two or more sequential files.
Consider posting stock issue transactions against an inventory balance
file to update the balances. Assume that both files are sequenced on
item stock number within warehouse location; warehouse location and
stock number are used as matching fields. These fields are designated
in columns 61-62 by encoding a matching record code (M1-M9) for the
records to be matched from both files. The issue file is encoded as
primary (P in column 16) on the File Description Specification Form F
and the inventory balance file is encoded as a secondary file. As
issue records are read in, the inventory balance file is advanced and
the designated matching fields of the records are compared. When
matching occurs, the matching records (MR) indicator is set on. This
indicator subsequently may be used as a condition for the issue
posting calculation.
In record matching, the file sequences must be consistent -- all
ascending or all descending, and so encoded in column 18 of form F.
The order in which multiple matching fields are checked depends on the
value (M1-M9) assigned. M9 designates a highest order field; M1
designates a lowest order field. If the program has a single
sequential file, it may be sequence checked by entering M1-M9 codes to
designate the sequence control field(s) in proper order. As in record
matching, the higher order code must be assigned to the higher order
control fields, etc. RPGLIB enters Halt Procedure "L1" if a file is
found out of sequence. Sequence checking occurs automatically when
fields are being matched. Table 8-1 gives rules for matching fields.
Note that M1-M9 are not indicators, but cause the indicator MR to be
set on when a match occurs.
INPUT SPECIFICATIONS -- FORM I Page 8-11
Table 8-1
Rules for Matching Fields
Number of A given record may have as many as nine matching field
Codes codes.
Length The lengths of fields to be matched (those having
corresponding Mn codes) must be equal. The length of
the combined matching fields of a record must be the
same as for any record against which matching takes
place.
Format Fields to be matched must have the same format-- both
numeric or both alphanumeric. An alphanumeric field
may be treated as numeric for matching or sequence
checking by defining it again with a different field
name and designating it as numeric (by an entry in
column 52). The Mn code then is used with the
redefined field.
Decimals and Decimal positions are ignored in matching numeric
Leading fields. Also, a numeric field with leading zeroes
Zeroes will match a field having the same value with
suppressed leading zeroes.
Sign Only the digit portions of numeric fields are matched.
ignored Thus a negative number can match a positive number.
AND Multiple matching fields are in an AND relationship.
relationship Matches must occur in all matching fields specified
for a record before RPGLIB sets on the MR indicator.
Initial Alphanumeric matching fields are initialized to bla-
value nks. Initial value for numerics is zero.
Only Matching records may be specified only for input and
Input or update files.
Update
8.14 FIELD RECORD RELATION
Columns Values
63-64 Blanks, 01-99, L1-L9, MR, U1-U8, or H1-H9.
This field can be used as a means of minimizing the number of field
definition entries to be written. It also provides a convenient means
for selective control of processing.
INPUT SPECIFICATIONS -- FORM I Page 8-12
The meanings of the allowable entries are the following:
01-99 Record identifying indicator assigned to a record
type.
L1-L9 Control level indicator previously used.
MR Matching record indicator
U1-U8 External indicator previously set
H1-H9 Halt indicator previously used
The following general rules apply to this entry:
1. All fields without a field record relation should be
specified before fields with field record relations.
2. All fields with the same field record relation entry should
be entered on consecutive lines.
3. All parts of a split control field must have the same field
record relation entry and must be described on consecutive
specification lines.
A record identifying indicator (01-99) can be specified here for
records in an OR relationship having fields occupying different
positions in the records. In this case, the indicator specifies the
record for which the field description applies.
Control fields and matching fields can also be associated with a
record having an OR relationship by a field record relation. Also, a
field record relation may be specified for only one of a pair of
control fields or matching fields. In this case, the specification
having the relation is used when the indicator is on and the
specification not having the relation is used when the indicator is
off.
A control level indicator (L1-L9) or matching record indicator (MR)
can be specified as a field record relation when the defined field is
to be used only when the control break or matching records occurs. An
L1-L9 or MR entry cannot be specified here when the defined field is a
control field or matching field.
When U1-U8 has been encoded in columns 63-64, the normal processing
for that field is carried out if the specified external indicator has
been set on by a job control command. If the indicator is off, all
input processing of the field in this record is bypassed. The
external encoding must not be used for fields defined as matching or
control level fields. A halt indicator (H1-H9) is specified here for
records which have OR relationships and have the halt indicator
specified in columns 19-20.
INPUT SPECIFICATIONS -- FORM I Page 8-13
8.15 FIELD INDICATORS
Columns Values
65-70 Blanks, 01-99, H1-H9
This field is used to specify that the contents of the field are to be
examined when its record has been selected for processing. The data
contained in the field can be tested for the following conditions:
Plus
Minus
Zero or Blank
As can be seen on the Input Specifications Form, there is a two
position subfield representing each of these conditions. Allowable
encoding for indicators in each of these subfields is 01-99 and H1
through H9.
If the specified condition is not met, the designated indicator is
turned off for the input record. If the condition specified is met,
the designated indicator is turned on. The Plus and Minus conditions
can be used only with numeric fields. All field indicators are off at
the beginning of object program execution.
CHAPTER 9
CALCULATION SPECIFICATIONS -- FORM C
The Calculation Specifications tell RPG II which run-time operations
to perform. General rules:
Each operation must be specified on a single line of the
coding form. Generally, operations must be in the order of
execution.
Detail calculations must come first, then all total
calculations, then all subroutines.
Form C (Figure 9-1) has three major sections:
Entries in columns 7-17 control when the calculation is to be
performed.
Those in columns 18-53 describe the calculation.
Those in columns 54-59 specify which indicators should be
turned on or off as a result of the calculation.
Columns 60-74, COMMENTS, have no significance to the compiler.
RPG II prints any entries in the COMMENTS field on the source program
listing to aid the user or other readers.
CALCULATION SPECIFICATIONS -- FORM C Page 9-2
Figure 9-1
Form C
CALCULATION SPECIFICATIONS -- FORM C Page 9-3
9.1 CONTROL LEVEL
Columns Values Meaning
7, 8 Blanks Calculation operation is performed at
detail time
L0 Calculation operation is performed at
total time. (L0 is always on.)
L1-L9 Calculation is performed when the
corresponding or a higher level
control break occurs, or when a SETON
operation has set it on.
LR Calculation operation is done after
the last record has been processed, or
after LR has been set on.
SR Calculation operation is part of a
subroutine.
AN or OR Indicators listed on the current line
are in an AND or OR relationship with
indicators on the preceding line(s).
Calculation form entries must be presented to the compiler in the
above order, with the exception that AN/OR lines are specified with
their associated lines. Paragraph 9.2 gives more information about AN
and OR.
RPGLIB performs calculations at either detail or total time. Blanks
in columns 7-8 indicate performance at detail time. Control level
indicators L0, L1 through L9 and LR designate calculations to be
performed at total time. As is described in paragraph 8.12, control
level indicators are set by control breaks. A break in control at any
given level sets the indicator at that level and all lower levels.
Exception:
In the following cases, lower level indicators are not turned on:
1. Higher level indicator is set by a SETON operation. (See
paragraph 9.4.5).
2. The higher level indicator is set on as a record identifying
indicator. (See paragraph 8.5.)
The last record indicator, LR, is set on after the last input record
has been read and processed. Control level indicators L1 through L9
are also turned on when this occurs. When LR is set on by anything
other than the last record, for example, by a SETON operation, L1
through L9 are not affected.
CALCULATION SPECIFICATIONS -- FORM C Page 9-4
The L0 indicator is on throughout the exception phase and marks total
calculations to be performed even if a control break has not occurred.
An SR in columns 7 and 8 identifies the line as part of a subroutine.
Specifications for subroutine operations may not show the control
level(s) for those operations in columns 7-8 because these spaces are
occupied by the code SR. Subroutines may be entered, however, from
either a detail or a total calculation sequence. Individual
operations within the subroutine may be conditioned by any indicators,
including L0-L9, encoded in columns 9-17.
9.2 INDICATORS
The entries in these columns (if any) specify the additional
conditions which must be met after those in 7 and 8 are satisfied, if
the conditioned operation is to be performed. These conditions are
expressed in terms of indicators which must be on and/or off.
RPGLIB sets (turns on) or clears (turns off) indicators according to
input conditions or previous calculations. Up to three indicators may
be specified (one each in columns 10-11, 13-14, and 16-17); if two or
more are specified they are considered to be in an AND relationship.
If the desired indicator state is off, an N should be encoded in the
preceding column (9, 12, or 15).
Columns Values Meaning
10-11, 13-14 Blanks Columns 7-8 list the only conditioner.
or 16-17 If columns 7-8 are blank, do the
operation for every record read.
01-99 Do operation when this result or input
indicator is set.
L1-L9 Do operation when the named control
level indicator is on.
LR Do operation when the last record
indicator is on.
MR Do operation when matching records
have been found.
H1-H9 Do operation when the named halt
indicator is on.
U1-U8 Do operation when the named external
indicator is on.
OA-OG, OV Do operation when the named overflow
indicator is on.
CALCULATION SPECIFICATIONS -- FORM C Page 9-5
Through AN and OR entries in columns 7 and 8 more than three
indicators can be used to condition one operation.
9.2.1 AN/OR Lines
A maximum of seven AN/OR lines may condition a single operation, and
up to three indicators may be specified on each AN/OR line. The last
line of an AN/OR group lists the operation and operands to be used
when the conditions are met. The others should not specify
operations, operands, or resulting indicators.
AN/OR lines give flexibility for conditioning. If more than three
indicators must be on or off for a particular operation, AN lines
allow up to eighteen more indicators. OR lines allow alternate
conditions. When there are combinations of AN and OR lines, AN has
the higher binding power.
Example:
01N03 09
AN 02 04 07
OR 99 98N 97
OR 96N95 LR
AN 93N92 ----------OPERATION--------------
OPERATION will be performed if conditions listed on the first two
lines, or those on the third, or those on the last two are met. In
particular if 01 is set, 03 is not set, and 09, 02, 04 and 07 are set,
or 99 and 98 are set, and 97 is not set, or 96 is set, 95 is not set,
LR and 93 are set, and 92 is not set.
Users may enter halt indicators to prevent a calculation from being
performed with erroneous data.
Points to remember when filling in columns 7-8 and 9-17:
1. When columns 7-8 contain a control level indicator and
columns 9-17 specify MR, the matching record description
applies to the last record processed -- not the record
causing the control break. MR will not be set for the
current record until all the total calculations specified for
the appropriate control break in 7-8 have been performed.
2. A control level entry in columns 7-8 indicates a total
calculation. A control level entry in columns 9-17 specifies
a detail operation to be performed after the control break.
The organization of the RPG II program cycle causes RPGLIB to
perform total operations for a control break before the
detail operations for the record causing the control break.
CALCULATION SPECIFICATIONS -- FORM C Page 9-6
Figure 9-2
Conditioning Calculations
CALCULATION SPECIFICATIONS -- FORM C Page 9-7
Figure 9-2 shows examples. Explanation:
Line 010 - The detail calculation is performed only if
indicator 01 is on.
Line 030 - The detail calculation is performed only if control
break indicator L2 is on.
Line 040 - The total calculation is performed when the L4
control break indicator is on and MR has not been
set by the previously processed record.
9.3 FACTOR 1 AND FACTOR 2
Many RPG II Calculation operations require the specification of
factors. Entries may be needed for Factor 1, Factor 2, both, or
neither, depending on the particular operation. The following
paragraphs discuss requirements for each operation. Appendix A is a
summary of Calculation Specification Entries.
Columns Values
18-27, 33-42 Factor 1 and Factor 2 may contain the following
entries:
Field name
Alphanumeric or numeric literal
Array element, or name of subroutine, table or
array
Date field name (UDATE, UMONTH, UDAY, UYEAR)
Special name (PAGE, PAGE1, PAGE2)
Label for a TAG, BEGSR, or ENDSR operation (Factor
1) or a label for a GOTO or EXSR operation (Factor
2)
Filename (first six characters) for a CHAIN,
DEBUG, DSPLY, READ, or FORCE operation (Factor 2)
Entries are left-justified in the two fields. The rules for each
entry type:
CALCULATION SPECIFICATIONS -- FORM C Page 9-8
9.3.1 Field Names
All field names must be defined if they are to be used in writing a
Calculation Specifications line. A field name is defined by an entry
in columns 53-58 of an Input Specifications form or by an entry in
columns 43-48 (result field) of a Calculation Specifications line. A
field name not defined as input may be used as a Factor 1 or Factor 2
entry only if it is defined (1) as a result field on the same
Calculation Specifications line where it is first used as a factor or,
(2) as a result field on an earlier line. A compiler error results if
a field name is entered which is undefined or defined in a later
Calculation line.
9.3.2 Literals
Literals are self defining data and may be numeric or alphanumeric.
Examples: 123.4 (numeric) or 'ABC', '123.4' (alphanumeric)
9.3.2.1 Numeric - A combination of digits (0-9), one decimal point,
and one arithmetic sign.
Rules:
1. Numeric literals must
1. not exceed ten positions,
2. not contain embedded blanks,
3. be left-justified
4. have the sign, if encoded, in the leftmost column 18 or
33); an unsigned literal is assumed to be positive
5. not be enclosed in apostrophes.
2. The decimal point, if encoded, may appear anywhere in the
literal. If it is not encoded, it is assumed to follow the
rightmost digit.
CALCULATION SPECIFICATIONS -- FORM C Page 9-9
9.3.2.2 Alphanumeric - An alphanumeric literal is a combination of
characters enclosed in apostrophes.
Rules:
1. It must not exceed eight position, plus two apostrophes.
2. It may contain any alphanumeric character including blanks.
3. It must be left-justified. An apostrophe within a literal
must be encoded by entering two consecutive apostrophes.
Example:
The word USER'S is encoded as a literal 'USER''S'.
123 is a numeric literal; '123' is an alphanumeric literal.
9.3.3 Names And Elements
Table and array names were described briefly in Chapter 6. These
names and array element names are discussed in greater detail in
Chapter 12.
Rule for Labels and Subroutine Names:
1. must be left-justified
2. must start with an alphabetic character
3. must not exceed six characters
4. must not be the same as any field name
5. must not include special characters or embedded blanks
9.3.4 Date Field Names
The date field names--UDATE, UMONTH, UDAY, and UYEAR--refer to the
current date that RPGLIB supplies to the object program. These values
cannot be changed by calculations specifications, so they may not
appear in columns 43-48. They may appear as factors to, for example,
produce the next month's billing date.
CALCULATION SPECIFICATIONS -- FORM C Page 9-10
9.3.5 Special Names
The special names--PAGE, PAGE1, and PAGE2--are described in paragraph
10.8.2. These names are used for the three page number counters
available to RPGLIB. The programmer may increment these counters
explicitly in the calculations specifications, or implicitly in output
specifications.
9.3.6 Labels
Paragraph 9.3.3 gives rules for establishing Factor 1 labels (used
with TAG, BEGSR, and ENDSR operations) and Factor 2 labels (used with
GOTO and EXSR operations).
9.3.7 Filenames
Any valid RPG II filename can be used as Factor 2 for CHAIN, DEBUG,
DSPLY, READ, and FORCE operations, subject to the specific
requirements of each operation.
9.4 OPERATION -- COLUMNS 28-32
This field specifies the operation to be performed using Factor 1,
Factor 2 and the Result Field, as appropriate. Allowable operations
are summarized in Table 9-1. Operation codes must be left-justified.
Detailed rules for each code are given in subsequent paragraphs.
CALCULATION SPECIFICATIONS -- FORM C Page 9-11
TABLE 9-1
Operations for Calculation Specifications
Class Code Operation
Arithmetic ADD Add
Z-ADD Zero and Add
SUB Subtract
Z-SUB Zero and Subtract
MULT Multiply
DIV Divide
MVR Move Remainder
SQRT Square Root
XFOOT Crossfoot - Sum Elements of an Array
Move MOVE Move
MOVEL Move Left
MOVEA Move Array
Move Zone MHHZO Move High to High Zone
MHLZO Move High to Low Zone
MLLZO Move Low to Low Zone
MLHZO Move Low to High Zone
Compare, Bit,
and Test COMP Compare
BITON Set Bit On
BITOF Set Bit Off
TESTB Test Bit
TESTZ Test Zone
Branch and Tags GOTO Go To
TAG Provide a Branching Label
EXSR Execute an RPG II Subroutine
BEGSR Begin an RPG II Subroutine
ENDSR End an RPG II Subroutine
EXIT Enter a non-RPG II Subroutine
RLABL Pass Parameters to a non-RPG II
Subroutine
Indicator SETON Set Indicator On
SETOF Set Indicator Off
Table LOKUP Table or Array Lookup
Input/Output EXCPT Force Output Printing
FORCE Force Record to be Read
DSPLY Print and/or Accept Data at the
Console Device
READ Read from Demand File
CHAIN Retreive Defined Record
Debugging DEBUG Aid in Finding Programming Errors
Miscellaneous TIME Retreive Time of Day from RPGLIB
CALCULATION SPECIFICATIONS -- FORM C Page 9-12
9.4.1 Arithmetic Operations
The fields and literals used in arithmetic operations must be numeric.
None of the fields specified as Factor 1, Factor 2, or the Result
Field can exceed 15 digits. RPGLIB aligns decimal points before all
arithmetic operations. The arithmetic operation codes and their
corresponding fields are listed below:
Factor 1 Operation Factor 2 Result Field
required ADD
blanks Z-ADD
required SUB
blanks Z-SUB required required
required MULT
required DIV
MVR blanks
blanks SQRT required
XFOOT required
Up to three distinct names may be in a single statement. Factor 1 and
2 fields are not altered by the operations unless one or both of the
names are the same as the Result Field Name. The previous contents of
a Result Field are lost after an arithmetic operation. Table 9-2
describes Arithmetic Operations.
9.4.2 Move Operations
When using the MOVE, MOVEL or MOVEA operations the form of the data
may be changed from alphanumeric to numeric and vice versa. When an
alphanumeric field is moved to a numeric field, blanks are converted
to zeroes. Move operations do not align decimal positions. Factor 1
and the resulting indicators columns must be blank for move
operations.
Table 9-3 describes Move Operations.
9.4.3 Move Zone Operations
These operations are used to move the zone portion of a character.
There are four varieties of the move zone operation.
Note: Generally, whenever the word high is used, the field involved
must be alphanumeric; whenever low is used, the field involved may be
either alphanumeric or numeric.
CALCULATION SPECIFICATIONS -- FORM C Page 9-13
9.4.3.1 MHHZO - This operation moves the zone from the leftmost
position of Factor 2 to the leftmost position of the Result Field.
Factor 2 and the Result Field must be alphanumeric.
9.4.3.2 MHLZO - This operation moves the zone from the leftmost
position of Factor 1 to the rightmost position of the Result Field.
Factor 2 can only be alphanumeric. The Result Field can be either
numeric or alphanumeric.
9.4.3.3 MLLZO - This operation moves the zone from the rightmost
position of Factor 2 to the rightmost position of the result field.
Factor 2 and the Result Field may be either alphanumeric or numeric.
9.4.3.4 MLHZO - This operation moves the zone from the rightmost
position of Factor 2 to the leftmost position of the Result Field.
Factor 2 can be either numeric or alphanumeric, but the Result Field
can only be alphanumeric.
9.4.4 Compare, Bit And Test Operations
9.4.4.1 COMP - The operation COMP compares the literal or the
contents of the field in Factor 1 against the literal or contents of
the field in Factor 2. The Factor 1 and Factor 2 fields must have
identical formats--both numeric or both alphanumeric. An entire array
cannot be specified as either Factor. The Result Field must be left
blank.
At least one resulting indicator (columns 54-59) must be specified.
Depending upon the results of the comparison, the appropriate
indicators are turned on:
High Factor 1 is greater than Factor 2.
Low Factor 1 is less than Factor 2.
Equal Factor 1 equals Factor 2.
Table 9-4 gives rules for comparisons.
CALCULATION SPECIFICATIONS -- FORM C Page 9-14
TABLE 9-2
Arithmetic Operations
Operation Description
ADD Factor 2 is added to Factor 1 and the sum is placed in
the Result Field.
Z-ADD Factor 2 is placed in the Result Field.
SUB Factor 2 is subtracted from Factor 1 and the
difference is placed in the Result Field. When Factor
1 and Factor 2 have the same name, the Result Field is
zeroed.
Z-SUB Factor 2 is placed in the Result Field with its sign
reversed.
MULT Factor 1 is multiplied by Factor 2 and the product is
placed in the Result Field.
DIV Factor 1 is divided by Factor 2 and the quotient is
placed in the Result Field. Factor 2 can not be zero.
The remainder of a divide is lost, unless an MVR
operation follows on the next Calculation
Specifications line; when a move remainder operation
is specified, half-adjusting can not be requested for
the divide, and the MVR must be the next line.
MVR The remainder from the immediately preceding divide
operation is moved to the Result Field. Since the DIV
and MVR operations go together they should be
conditioned by the same indicators, if any. The
number of significant decimal positions in the
remainder is the greater of:
1. The number of decimal positions specified for the
Factor 1 field of the divide
2. The sum of the number of decimal positions
specified for the Factor 2 and Result fields of
the preceding divide operation.
SQRT The square root of Factor 2 is calculated,
half-adjusted and placed in the Result Field. Factor
2 can not be a negative number. The number of
significant whole number and decimal positions in the
Result Field is one-half that of Factor 2,
half-adjusted to the next highest whole number.
CALCULATION SPECIFICATIONS -- FORM C Page 9-15
TABLE 9-2 (cont'd)
Arithmetic Operations
Operation Description
XFOOT The sum of all the elements of the Factor 2 array is
placed in the single element Result Field.
Half-adjusting can be specified for the Result Field
If the Result Field is an element of the Factor 2
array, the original value of the element is used in
the addition, and then replaced by the sum.
CALCULATION SPECIFICATIONS -- FORM C Page 9-16
Table 9-3
Move Operations
Operation Description
MOVE Causes characters, starting at the rightmost
character, to be moved from the data field or literal
specified in Factor 2 to the rightmost positions of
the Result Field. The contents of the data specified
by Factor 2 remain unchanged in all cases.
If the Result Field length is shorter than the length
of the Factor 2 data field, RPGLIB moves only enough
to fill the Result Field.
If the Result Field is longer than the Factor 2 data
field, RPGLIB moves all available characters, and
leaves excess characters of the Result Field
unaffected. A numeric Result Field assumes the sign
associated with Factor 2.
MOVEL This operation is similar to the MOVE, except that
characters are moved from the leftmost position of the
Factor 2 data field to the leftmost characters
position of the Result Field. If a numeric Result
Field is the same length as Factor 2, it assumes the
sign associated with Factor 2. If a numeric Result
Field is longer than Factor 2, it retains its sign,
but a spurious sign will appear over the rightmost
result character contributed by Factor 2. A numeric
Result Field shorter than Factor 2 will have no sign.
MOVEA Moves the data starting at the leftmost position of
Factor 2 to the leftmost position of the Result Field.
The shorter field (Factor 2 or the Result Field)
determines the length of the move. If Factor 2 is
longer than the Result Field, the excess rightmost
characters of Factor 2 will not be moved. If the
Result Field is longer than Factor 2, the characters
to the right of the data moved into the Result Field
will remain unchanged. All arrays an field referenced
by a MOVEA instruction must be alphanumeric.
The MOVEA operation makes it possible to move such
things as:
1. Several contiguous array elements to a single
field.
2. A single field to several contiguous array
elements.
CALCULATION SPECIFICATIONS -- FORM C Page 9-17
Table 9-3 (cont'd)
Move Operations
Operation Description
XFOOT (cont'd) 3. Contiguous elements of one array to contiguous
elements of another array.
The movement of data starts with the first element of
an array or field. If the array is indexed, the move
starts with the element referenced. The movement of
data is terminated when the last array element has
been moved or filled, or when the number of characters
moved equals the length of the shorter field specified
in Factor 2 or the Result Field. This may cause the
move to be terminated in the middle of an array
element.
Note: Both Factor 2 and the Result Field cannot
reference the same array.
Table 9-4
Rules for Comparisons
TYPE TOPIC RULE
Numeric Length Maximum length is 15 digits.
Alignment RPGLIB aligns decimal points before
comparison.
Padding When necessary, RPGLIB pads with
zeroes until lengths are equal.
Comparison The comparison is algebraic.
Alphanumeric Length Maximum length is 256 characters.
Alignment RPGLIB aligns the left-most characters
before the comparison.
Padding RPGLIB pads with blanks on the right
when lengths are unequal.
Comparison Characters are compared according to
the normal collating sequence.
CALCULATION SPECIFICATIONS -- FORM C Page 9-18
9.4.4.2 BITON, BITOF, TESTB - The bit operations allow users to set
(BITON), clear (BITOF), and test (TESTB) bits which can be used for
conditioning operations.
The Result Field specification must be a 1-character alphanumeric
field or element in a table or array.
The Factor 2 specification can have two formats:
1. Bit numbers (0-5) can be specified. The numbers specify
which bits are to be set on, set off, or tested. Up to 6
bits can be specified in any order. Bits are numbered 0-5
from left to right in the 1-character Result Field. Bits
specified in Factor 2 are enclosed in apostrophes. When
Factor 2 has the value '0', the leftmost bit of the Result
Field is to be set or tested. An entry of '5342' causes bits
2-5 (the rightmost four bits) to be set or tested.
2. Factor 2 can also be a 1-character field or element in a
table or array. In this case, the contents of the Factor 2
specification (that is, those bits which are equal to
one--set) indicates the bits to be set or tested.
No matter which format is used for Factor 2, unspecified bit positions
cause the corresponding Result Field bits to be ignored. Bit
operations can be conditioned by entries in columns 7-17. If field
length is specified, the value must be 1. Factor 1, Decimal
Positions, and Half-Adjust must be blank for bit operations.
Resulting Indicators (columns 54-59) are blank for BITON and BITOF,
but must have at least one entry for TESTB operations.
The BITON operation causes bits specified in Factor 2 to be set equal
to one in the corresponding Result Field bit positions. That is,
RPGLIB places the inclusive OR of Factor 2 and the Result Field into
the Result Field.
The BITOF operation causes bits specified in Factor 2 to be cleared to
zero in the corresponding Result Field bit positions. (RPGLIB ANDs
the Result Field with the complement of Factor 2.)
Bits specified in Factor 2 of a TESTB operation cause corresponding
bit positions in the Result Field specification to be tested for an on
or off condition and resulting indicators to be set accordingly.
(RPGLIB ANDs the Result Field with Factor 2.) At least one indicator
must be specified in the Resulting Indicators field. A user may
specify up to three, but a single indicator may not be specified in
more than two positions. If Factor 2 is a field which is all zeroes,
no indicators are set by a TESTB operation. Otherwise, RPGLIB sets
resulting indicators according to the following conditions:
1. An indicator in columns 54-55 is set if each Result Field bit
specified by the Factor 2 entry is off (0).
CALCULATION SPECIFICATIONS -- FORM C Page 9-19
2. An indicator in columns 56-57 is set if the Result Field bits
specified by the Factor 2 entry are in a mixed condition
(some on, some off). If the Factor 2 entry causes only one
bit to be tested, an indicator specified here will not be
set.
3. An indicator in columns 58-59 is set if each Result Field bit
specified by the Factor 2 entry is one (1).
9.4.4.3 TESTZ - This operation tests the zone of the leftmost
character in the result field (see Appendix D for information on
character structure). The Result Field must be alphanumeric since
this operation can only be done on alphanumeric characters. Resulting
indicators are used to determine the results of the test. The zone
portion of characters & and A-I causes the plus indicator to turn on.
The zone portion of the characters } (right curly-bracket), - (minus),
and J-R causes the minus indicator to turn on. All other characters,
when tested, cause the blank indicator to turn on. Factor 1 and
Factor 2 are not used in this operation.
9.4.5 Branch And Exit
RPGLIB usually does calculations in the order in which they are
entered on specifications lines. Operations listed in this section,
however, can alter this sequence for the following sample reasons:
1. Some operations should be skipped as a result of certain
conditions.
2. Operations defined on preceding specifications forms should
be repeated as a result of certain conditions.
3. A sequence of operations is to be performed over and over
again.
It is also desireable, at times, to be able to access subroutines not
written in RPG II, in order to do system-dependent functions not
possible in RPG II. For this reason subroutine linkages to accomplish
this are provided.
Branch and exit operations:
GOTO (Branch)
TAG (Provide a name for a branch)
EXSR (Transfer to an RPG II subroutine)
BEGSR (Begin an RPG II subroutine)
ENDSR (End an RPG II subroutine)
EXIT (Transfer to a non-RPG II subroutine)
RLABL (Pass a parameter to a non-RPG II subroutine)
CALCULATION SPECIFICATIONS -- FORM C Page 9-20
Branch and exit operations and their corresponding fields are listed
below:
9.4.5.1 GOTO - If the conditions specified in columns 7-17 are met,
control is transferred to the point in the program specified by the
name in Factor 2. (See TAG, next paragraph.) Both forward and
backward referencing is allowed. WARNING: (1) Control may not be
transferred to a TAG within a subroutine from outside that subroutine.
Transfer may not be made from a calculation not conditioned by
indicators in columns 7-8 to one that is; or vice versa. When
conditions are not specified for the GOTO operation, the transfer
always occurs.
Factor 1 and Result Field must be blank for a GOTO operation.
9.4.5.2 TAG - The TAG operation defines names to which a GOTO
operation may transfer control. The name goes in Factor 1 and may be
1 to 6 characters long. The first character must be alphabetic and be
placed in column 18. No special characters or embedded blanks may be
used.
Columns 9-17 must be blank for a TAG operation code, but a control
level indicator can be specified in columns 7-8 to signal that the
branch is to occur at total time.
9.4.5.3 EXSR - The EXSR operation causes a transfer of control to an
internal subroutine written in RPG II as a part of the same program.
After the subroutine has been performed, control returns to the next
specification following the EXSR operation.
The name of the subroutine is left-justified in Factor 2. EXSR
operations may be conditioned by entries in columns 7-17.
Nesting (an EXSR for a second subroutine in an RPG II subroutine) may
occur, but a subroutine may not call itself, nor any subroutine that
called itself and so on.
CALCULATION SPECIFICATIONS -- FORM C Page 9-21
9.4.5.4 BEGSR - The BEGSR operation defines the entry point of an
RPG II subroutine. The left-justified name of the subroutine goes in
Factor 1. Columns 7-8 must contain SR; all other columns except
COMMENTS (columns 60-74) must be blank.
9.4.5.5 ENDSR - An ENDSR operation is the last statement of an RPG II
subroutine. The Factor 1 field may contain a name which is referenced
by GOTO operations within the subroutine. Columns 7-8 must contain
SR.
9.4.5.6 EXIT - The EXIT operation generates a call to an external
subroutine, using linkages compatible with such standard DECsystem-10
language processors as MACRO, FORTRAN, and COBOL. See Appendix G for
more information on this calling sequence.
Factor 2 must contain the name of the external subroutine. Factor 2
must therefore contain a legal RAD50 symbol, compatible with LINK-10.
(A legal RAD50 name may contain the characters A-Z, 0-9, ".", "$",
"%", or " ".)
9.4.5.7 RLABL - The RLABL operation allows the passing of a field,
table or array, as a parameter to an external non-RPG II subroutine.
The parameter passing procedure is compatible with most other
DECsystem-10 language processors (see Appendix G for more
information).
9.4.6 Indicator Operations
RPG II provides two indicator operations. Both may be conditioned by
entries in columns 7-17.
9.4.6.1 SETON (Set Indicators On) - This operation turns on the
indicators specified in columns 54-55, 56-57, 58-59. Any indicators
may be referenced except 1P, MR, L0, and U1-U8.
When LR is set on by an operation conditioned by a control level
indicator (columns 7-8). processing stops after all total output
operations are completed. If the SETON is not conditioned by a
control level indicator, processing stops after the next total output
sequence is completed.
If one or more halt indicators (H1-H9) is SETON and not turned off
before detail operations are completed, processing stops at that time.
Setting a control level indicator (L1-L9) on does not set lower
CALCULATION SPECIFICATIONS -- FORM C Page 9-22
control level indicators on. A control level indicator which has been
SETON is automatically turned off at the completion of the detail
output operation cycle.
Record identifying indicators (01-99) are conditioned by a new record,
regardless of previous SETON and SETOF operations. That is, SETON or
SETOF only lasts until the next input record is identified.
9.4.6.2 SETOF (Set Indicators Off) - This operation is identical to
SETON, except specified indicators are turned off rather than on, and
LR cannot be set off.
9.4.7 Table Operation
RPG II provides a table lookup operation, encoded LOKUP. Factor 1
specifies the search argument and Factor 2 specifies the name of the
internally stored argument table or array to be searched. RPGLIB
begins all table searches with the first element and stops searching
when conditions have been satisfied. At least one indicator must be
designated in columns 54-59 to specify the type of search.
The search argument (Factor 1) may be:
1. An alphanumeric or numeric constant.
2. A field name.
3. A table name.
4. An array element.
As described below, when a table is named as Factor 1, the table
element last selected by LOKUP operation is the search argument.
Factor 1 and Factor 2 must have equal lengths and data type (i.e.,
both numeric or both alphanumeric), and decimal points of the two
items are ignored.
The type of search is specified by entries in the resulting indicators
field (54-59). Before the search, all indicators are turned off. The
specified indicators are turned on when the conditions are met.
Conditions possible are:
HIGH (columns 54-55) -- RPGLIB turns on the indicator specified in
54-55 and stops searching when it finds the smallest entry
which is greater than Factor 1 (search argument).
LOW (columns 56-57) -- Same as HIGH, except RPGLIB searches for
the largest entry which is less than Factor 1 (search
argument).
EQUAL (columns 58-59) -- Same as HIGH, except RPGLIB searches for
CALCULATION SPECIFICATIONS -- FORM C Page 9-23
the first entry equal to Factor 1 (search argument).
Combinations of HIGH and EQUAL may be specified with EQUAL given
precedence. Thus, if there is an entry which is equal, RPGLIB will
find it. HIGH and LOW may not be specified simultaneously.
Comparisons made during a search are algebraic for numeric quantities.
Alphanumeric quantities are compared by the ASCII collating sequence.
Tables and arrays to be searched by a LOKUP operation must have an
entry in column 45 (sequence specification) of Form E unless the
search is for an equal condition only (entry in columns 58-59 and none
in columns 54-55 and 56-57).
LOKUP operations can be conditioned by entries in columns 7-17.
9.4.7.1 LOKUP With One Table - If a single-table search is
successful, RPGLIB retrieves the table value and stores it in a
holding area. Previous contents of the holding area (i.e., the result
of a prior LOKUP) are destroyed. If the search is unsuccessful,
RPGLIB does not change the holding area. References to a table name
in later operations (other than another LOKUP) actually refer to the
item currently in the holding area. Thus, the later operations should
be conditioned by indicators set by a successful search.
When a table name is used as a search argument (Factor 1) of a LOKUP,
RPGLIB uses the current value in the holding area in the search. When
a table name which has been Factor 2 in a successful search is named
as the result field of a calculation operation, the holding area and
the last element retrieved receive the result of the operation. This
allows object programs to change table items.
9.4.7.2 LOKUP With Two Tables - Chapter 12 describes related tables.
Related tables can be specified as Factor 2 and Result Field in a
LOKUP operation. Factor 2 names the first table to be searched. When
a search is successful, two items are moved to the holding area: the
Factor 2 item resulting from the successful search and the
corresponding item from the related table. Both holding area values
remain available according to the rules specified above. When the
number of elements does not match, the shorter number of elements
determines the number to be searched. Thus, the last elements in the
longer table are ignored.
9.4.7.3 LOKUP With Arrays - When a LOKUP operation is performed with
an array named as Factor 2, the result field must be blank. Searching
an array is similar to searching a table except that RPGLIB does not
move an item to a holding area when a search is successful. RPGLIB
does set appropriate indicators after a successful array search.
CALCULATION SPECIFICATIONS -- FORM C Page 9-24
When Factor 2 is an unindexed array, RPGLIB begins the search at the
first element of the array.
When Factor 2 is an array name and index, the search begins with the
element indicated by the index. The Factor 2 format in this case is
[array name],[index]
where the index can be a field name or a numeric literal. If the
index is a field name, a successful search causes RPGLIB to place the
appropriate element number in the field used as the index. The array
element can then be referenced like a found table item in calculation
and output, using the array and index names. RPG II places a 1 in the
index field if the search was unsuccessful. This resets the index for
a subsequent search. When the index is a literal, only the indicators
tell if the search conditions are satisfied. That is, RPGLIB does not
change the value of the literal or identify the array element
satisfying a search.
Figure 9-3 illustrates LOKUP operations on tables and arrays. At
lines 010-030, TABLE1 is searched for an argument stored at ACTNO. If
RPGLIB finds a match it adds the matching element to a value stored at
TOTAL and stores the sum at TOTAL. When the HIGH indicator is set by
the search, that indicator conditions a branch to a TAG called ERROR.
Calculations at lines 080 and 090 are conditioned by the Equal
indicator of the LOKUP operation at 010. If the LOKUP at line 080 is
performed, RPGLIB searches TABA for an element which equals the
element retrieved at line 010. If this search is successful, RPGLIB
sets indicator 01 and squares the associated element in TABB. At line
130, RPGLIB searches ARRAY for an element equal to a value stored at
ARG. If a match is not found, control is transferred to a TAG named
FILL.
At lines 170 and 180, RPGLIB searches array ARRAY for the first
element having a value less than 0556. The field INDX initially
contains the number of the array element at which the search should
begin. If the search is unsuccessful, RPGLIB sets INDX to value 1.
When the search is successful, INDX contains the number of the element
that satisfied the search. The next line causes RPGLIB to move the
element satisfying the condition to a field named HOLD.
CALCULATION SPECIFICATIONS -- FORM C Page 9-25
Figure 9-3
LOKUP with Tables
CALCULATION SPECIFICATIONS -- FORM C Page 9-26
Figure 9-4
LOKUP with Arrays
CALCULATION SPECIFICATIONS -- FORM C Page 9-27
9.4.8 Input/Output Operations
In the RPG II program logic outlined in Appendix C, RPGLIB reads
records, performs calculations, and outputs records. Deviation from
this pattern is possible via five operation codes which allow input or
output at calculations time:
1. EXCPT (exception)
2. FORCE (force)
3. DSPLY (display)
4. READ (read)
5. CHAIN (chain)
9.4.8.1 EXCPT - The EXCPT operation allows records to be written at
calculations time. Use this primarily when you like to have a number
of similar or identical records to be written in one program cycle.
When the EXCPT operation is used, except columns 28-32 and only
columns 7-17 may have entries. The line or lines which are to be
written out are indicated by an E in column 15 of the output sheet.
9.4.8.2 FORCE - The FORCE operation overrides normal record
selection, and allows the user to select the file that will supply
input for the next cycle. The forced file can be a primary or
secondary input or update file. Factor 2 names the file from which a
record is to be forced.
The FORCE can be conditioned by columns 7-17, but all other columns
except COMMENTS on the line must be blank.
If a FORCE operation is executed, the next program cycle will process
the next available record from the FORCEd file. If several FORCE
operations occur in one calculations cycle, RPGLIB executes the last
one only. The effect of a FORCE lasts only one cycle.
In multi-file processing, RPGLIB selects the first record to be
processed in the normal fashion, but thereafter records can be forced
in an abnormal manner. At end of file on a forced file, normal record
selection resumes. See also 1.1.2, 5.3 and 13.1.1
CALCULATION SPECIFICATIONS -- FORM C Page 9-28
9.4.8.3 DSPLY - Through a DSPLY operation, either or both of the
following can occur:
1. Up to 125 characters are printed from storage onto the
console device without a halt in program execution. Programs
may display characters from a literal, a field, or a table or
array element named as Factor 1.
2. Up to 125 characters of a field or table or array element
named as the Result Field are printed on the console device.
The program then halts, allowing the contents of the field or
element to be altered from the console.
A display file is described completely on Form F; it needs no record
descriptions. The filename goes in Factor 2 on the DSPLY operation
line. The operation can be conditioned by entries in columns 7-17.
The rules for entering data during program execution:
1. A literal cannot be altered (i.e., cannot be entered in the
Result Field).
2. Numeric data need not be entered with leading zeroes; the
data is right-justified in the result field or element.
3. Alphameric data is left-justified in the receiving field or
element.
4. Typing a single space causes a numeric field or element to be
cleared to zeroes and an alphanumeric field or element to be
set to blanks.
5. A field or element is not changed if characters are not
entered.
9.4.8.4 READ - The READ operation causes RPGLIB to read and process a
record from a demand file during the calculations cycle. Unlike a
record read by a FORCE operation, RPGLIB reads it immediately, not at
the start of the next program cycle. Demand files are processed
sequentially.
The demand file is described on Forms F and I, and the filename is
entered as Factor 2 for the READ operation. The READ can be
conditioned by entries in columns 7-17. All other columns should be
blank except 58 and 59, in which an indicator may be specified, and
COMMENTS. RPGLIB turns on the indicator when it reaches end-of-file
in the demand file. When columns 58-59 are blank, program execution
halts at end-of-file.
A demand file's record identifying indicator remains on throughout the
program cycle after a record has been READ from the file.
CALCULATION SPECIFICATIONS -- FORM C Page 9-29
A demand file must have a D in column 16 on Form F and must be input
or update. Demand file records can be accessed only through READ
operations. Control levels, matching records, and look-ahead fields
can not be specified for demand files, nor can numeric sequence
checking be requested.
When a demand file is conditioned by an external indicator (U1-U8)
which is not on, no records are read from the file and the end-of-file
indicator (columns 58-59) is not set on.
9.4.8.5 CHAIN - The CHAIN operation is used for two purposes:
1. Random processing of an indexed, sequential, or direct file.
2. Loading (creating) a direct file.
The operation requires Factor 1 and Factor 2 entries, but columns
43-53 and 56-59 must be blank.
A CHAIN may be conditioned by entries in columns 7-17.
An indicator should be specified in columns 54-55. This indicator is
set when a record is not found; output can not occur to a chained
file when the specified record is not found unless the operation
indicator was intended to ADD a record (see 10.4). If columns 54-55
are blank and the record is not found, program execution halts.
When RPGLIB processes Chained files, more than one record identifying
indicator may be on at the same time.
9.4.8.5.1 Random Input Processing - The entry in Factor 1 identifies
the record to be retrived. The value is either a numeric relative
record number (for sequential and direct files) or a record key (for
indexed files). The entry in Factor 2 identifies the file. This file
must be described on Forms F and I.
9.4.8.5.2 Direct File Output Load - When a direct file is created
(loaded), the file is described as a chained output file on forms F
and O. Factor 1 names a relative record number and Factor 2 names the
file.
The relative record number can be all or part of a field in an input
record, or it can be generated by the RPG II program.
When direct file load is to occur, RPGLIB clears to blanks the entire
area reserved for the file. As a record is being output, the relative
record number points to the disk record to which output occurs.
Records not specified in the load are left blank.
CALCULATION SPECIFICATIONS -- FORM C Page 9-30
When records are added to a sequential or indexed file, records are
added at the end of existing records. Records are updated in a direct
file, however, according to the relative record number.
Once the direct file has been created, the file can be modified in
later program executions by defining the file as an update file.
It may be that duplicate record numbers will be entered as Factor 1.
This could happen if information to be loaded is specified in
different portions of several records. Since a direct file load
implies a blank area, only the last record loaded for one relative
record number will appear in the created file. The records can be
completed in succeeding program executions, if direct file is declared
an update file.
9.4.9 DEBUG Operation
The DEBUG operation can assist in isolating programming errors in the
object program. Whenever a DEBUG operation is executed, one or more
records are written to the output file specified as Factor 2.
All DEBUG statements in a program must refer to the same output file.
A DEBUG operation is executed only if requested on the Control
Specifications form (1 in column 15). When that column is blank,
RPG II ignores DEBUG. Thus, DEBUG can be used during program checkout
and only form H need be changed when the RPG II program is
operational. The operation may be conditioned by entries in columns
7-17.
Factor 1 is optional but may contain a literal or field name to
identify the DEBUG output record. The Result Field is also optional
but may name a field a table or array element, or an entire array. An
entry in the Result Field causes the named item to be written to the
output file when the DEBUG operation is executed. Columns 49-59 of
the DEBUG line must be blank.
The first record is automatically produced by a DEBUG operation and is
a list of all the indicators which are currently on in the program.
The format of the first record is:
CALCULATION SPECIFICATIONS -- FORM C Page 9-31
Record Positions Values
2-7 DEBUG
8 Blank
9-16 The constant specified as Factor 1 or the
statement number of the DEBUG operation line.
17 Blank
18-31 INDICATORS ON-
32-end of record The names of all the indicators which are on,
seperated by blanks.
If the indicator list will not fit in one record, the list is con-
tinued in the next record starting at position 2.
RPGLIB writes additional records to the output file if a Result Field
is specified for the DEBUG operation. Format of additional records:
Record Positions Values
2-12 FIELD VALUE or
TABLE VALUE or
ARRAY VALUE
13-14 Blanks
15-end of record The contents of the Result Field specification
(up to 256 characters per element). A minus
sign is appended to a negative element. When
an entire array is written, the elements are
seperated by blanks.
The record will be continued starting in position 2 of the next
record, if required.
In Figure 9-4, a search is made of ARRAY for an element matching a
value at ACTNO. If a match is not found, the following records are
written to DBGFILE (assuming Form H contains a 1 in column 15):
A list of indicators currently on.
The word ACTNO and the value of that field.
A list of indicators currently on.
The contents of the entire array, ARRAY.
CALCULATION SPECIFICATIONS -- FORM C Page 9-32
When the match is not found, RPGLIB bypasses the MOVE operation. When
a match is found, the DEBUG operations are bypasses and the MOVE is
executed.
9.4.10 TIME Operation
This calculation operation code allows you to access the system time
of day as well as the system date. To use this operation code,
columns 28-32 must contain the operation code TIME and the Result
Field must specify the name of a numeric field. To contain the time
of day, the field specified by the Result Field must be six-digit
numeric (with no decimals). To contain both the time of day and the
date, the Result Field must specify the name of a 12-digit numeric
field (with no decimals). Whole arrays cannot be specified in the
Result Field.
Columns 49-52 may be used to define the time of day field. Factor 1
and Factor 2 are not used and must be left blank. Half Adjust and
Resulting Indicators (columns 53-59) are not used and must also be
blank.
If the field specified in the Result Field is six-digit numeric, time
will be returned in the followin format:
hhmmss
Where hh is hours, mm is minutes, and ss is seconds.
If the field specified in the Result Field is 12-digit numeric, both
time and date will be returned as follows:
hhmmssmmddyy
Where hh is hours, mm is minutes, ss is seconds, mm is month, dd is
day, and yy is year.
9.5 RESULT FIELD
Columns Values
43-48 Name of field, table, array, or array element
This entry names a location where the result of a calculation
operation is placed. The name must conform to the rules for naming
fields, tables, and arrays. The result field name together with
entries in columns 49-52 define the result field for further
references. If the name has not been defined in extension, input, or
previous calculation specifications, appropriate entries must be made
in columns 49-52 and the entry must not be referenced prior to this
line. A field first defined in this entry is initialized to zeroes
CALCULATION SPECIFICATIONS -- FORM C Page 9-33
(numeric) or blanks (alphameric) by the RPG II compiler.
When the name has already been defined, entries in columns 49-52, if
any, must agree with the previous definition.
9.6 FIELD LENGTH
Columns Values
49-51 blanks or 1-256
The length of the result field may be entered in these columns,
right-justified. Leading zeroes may be omitted. The maximum length
for numeric fields is 15 characters; the maximum for alphanumeric
fields is 256 characters. Unpacked lengths must be specified for
numeric fields.
If the field length for this field has been specified on an Input
Specifications Form I, it need not go here. If it does, however, the
length entered must agree with the Form I entry. If a result field
length is first specified on Form C, subsequent references to the
field for results need not give the length.
9.7 DECIMAL POSITIONS
Columns Values
52 Blank or 0-9
For numeric result fields, this entry specifies the number of
positions to the right of the decimal point. No entry is made for
alphanumeric fields. A zero means the numeric field contains only an
integer (whole number).
A result field may have not more than 9 decimal positions. The number
of decimal positions must never exceed the field length. When the
number of decimal positions for a numeric result field has been
specified, subsequent entries which reference the field do not need
respecification. An entry in columns 49-51 is required when an entry
is made here.
When the result of a calculation produces fewer decimal positions than
specified here, RPGLIB pads the low-order positions with zeroes.
RPGLIB drops the low-order decimal positions when this specification
is smaller than the number of decimal positions produced in a
calculation.
CALCULATION SPECIFICATIONS -- FORM C Page 9-34
9.8 HALF ADJUST
Column Values
53 Blank or H
An H in this column specifies that the result of an arithmetic
operation is to be half-adusted (rounded). Half-adjusting is
accomplished by adding a five to the position immediately to the right
of the last position of the number to be stored in the result field.
The addition is performed on the absolute value of the number to be
stored. The correct sign is replaced before the rounded result is
stored. If the move remainder (MVR) operation is used, half-adjusting
must not be specified either for the MVR result or for the preceding
divide (DIV) operation.
9.9 RESULTING INDICATORS
Columns Values
54-59 blanks or 01-99, H1-H9, L1-L9, LR, OA-OG, OV
Indicators specified in these columns serve four purposes:
1. To describe the value of a result field after an arithmetic
operation.
2. To indicate the outcome of a CHAIN, LOKUP, COMP, or TESTB
operation.
3. To specify indicators for SETON and SETOF operations.
4. To signal end-of-file for the READ operation code.
The specified uses of this field have been defined in the preceding
paragraphs, with one exception: When arithmetic operations are
performed, the results are tested and indicators are turned on as
follows:
Indicator specified in columns 54-55 if result is positive. Indicator
specified in columns 56-57 if result is negative.
Indicator specified in columns 58-59 if result is zero.
If a single resulting indicator is specified on more than one
calculations line, its condition reflects the result of the last
calculation performed.
CALCULATION SPECIFICATIONS -- FORM C Page 9-35
9.10 COMMENTS
Columns Values
60-74 Blanks or any alphanumeric characters
These columns are not interpreted by the RPG II compiler, but are
printed on the source program listing.
9.11 CALCULATION SPECIFICATIONS EXAMPLES
Figure 9-5 highlights some of the principles just discussed. The
meanings are explained below.
Line 010 If halt indicator H1 and indicator 16 are both on, H1
and 15 are set off.
Line 020 If indicator 13 is on and LR is not on, indicator 43
is set on.
Line 030 As the comments field entry indicates, bits 0-7 of
FLAGS are set off.
Line 040 If indicator 23 is off, control is transferred to
label LOOK.
Line 050 Otherwise, FLD1 is compared with the numeric literal
21; if they are equal, indicator 12 is turned on.
Line 060 If indicator 12 is on, control is transferred to
subroutine SUBR.
Line 070 Defines label LOOK, to which a transfer was made at
line 040.
Line 080 If bit 2 or 4 (but not both) is on in the flag word,
indicator 77 is set.
Line 090 If H2 is not on, a table lookup is performed using the
content of a field named NAME as the argument in
searching a table named TABNAM. TABADD is the name of
a related table. If an equal case is found, indicator
77 is set on.
Line 100 If indicator 77 is on, the value retrieved by the last
executed table lookup is moved to a field ADDOUT which
is defined as a 6-character numeric field with 2
decimal positions.
Line 110 If a level 3 control break has occurred, a field named
SUBTOT is added to a field named TOTAL and the result
is half-adjusted and stored in TOTAL. TOTAL is an
CALCULATION SPECIFICATIONS -- FORM C Page 9-36
8-character numeric field having 2 decimal positions.
If the result is positive, indicator 63 is turned on.
If the result is negative, indicator 64 is turned on.
Line 120 If L3 and indicator 64 are on, an exception record(s)
is output.
Line 130 If L3 and 63 are on, ADDOUT is multiplied by the
numeric literal 3 and the result is stored in TRIPLE,
an 8-character numeric field with 2 decimal positions.
Line 140 This entry names the beginning of a subroutine. Lines
through 210 are part of the subroutine (SR in columns
7-8).
Line 160 A record is read at this time from a demand file named
NEWFILE. Indicator H2 is set on if end-of-file has
been reached.
Line 170 If H2 is on bit 2 is set on at FLAGS.
Line 180 If H2 is not on, control is transferred to SUBXIT.
Line 210 SUBXIT is named as the label of the last instruction
and exit of the subroutine.
CALCULATION SPECIFICATIONS -- FORM C Page 9-37
Figure 9-5
Calculations Examples
CHAPTER 10
OUTPUT - FORMAT SPECIFICATIONS - FORM O
Output specifications describe your output records. Logically these
specifications may be divided into two portions.
1. Record description portions (columns 7-31) which describe the
output file records to be written out.
2. Field description portion (columns 23-70) which indicates the
position and the format of data on the output record.
All output fields are initialized to blanks before each cycle.
10.1 FILENAME
Columns Values
7-14 Blanks or a valid RPG II filename
The filename must be one of those defined in the file description
specification as output on update files. The filename must begin in
column 7. You need to specify the output filename only once. It must
be on the first line that identifies the file.
10.2 AND/OR RELATIONSHIPS
Columns Values Meaning
14-16 Blank Field Specfication
AND Record Specification: Output
Indicators on this line are in an AND
relationship with those on the
previous line.
OR Record Specification: OR relationship
with indicators on the previous line.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-2
One line in Form O allows up to three indicators for conditioning
record output. If more than three indicators are needed for a record,
an AND in columns 14-16 of the next line allows three more indicator
codes. All codes are then considered in an AND relationship.
An OR in columns 14-15 of the next line allows the user to specify up
to three alternate output indicators for a record. For Example, a
page heading line (record) usually goes on each new page. Forms eject
to a new page may occur when the page is full, or when directed after
certain control breaks. Thus, the heading record could be conditioned
by overflow OR by Ln. When the OR conditions are used, the space and
skip entries (columns 17-22) need not be filled in unless different
spacing/skipping is desired for the alternate case.
The AND/OR relationships may be used for record-definition lines only.
Up to 20 AND, OR or mixed AND and OR lines are allowed for one output
operation. AND/OR lines are not allowed in field definitions.
10.3 RECORD TYPE
Column Values Meaning
15 Blank Field Specification
H Heading Record
D Detail Record
T Total Record
E Exception Record
Record type determines when a record should be output. Heading
records apply only to print files, and normally are output at the
beginning of printing by virtue of the first page indicator (1P) being
defined as a condition. Subsequently, heading lines are usually
printed as a result of overflow processing and skipping to a new page.
Detail lines usually are output after each detail record has been
processed. Total lines usually are output after control breaks have
occurred and total calculations performed, and at end of job (LR
indicator). Exception records are output when directed by the
calculation operation EXCPT.
Exception output conditioned by control level indicators or total
output may not be specified for update files.
The user may find it helpful to prepare Form O entries for each file
in the following order: all heading records, followed by all detail
records, followed by all total records, followed by exception records.
It is not mandatory, however, that this sequence be followed.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-3
Figure 10-1
Form O
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-4
10.4 ADD RECORD
This field allows records to be added to files. The corresponding
files FORM F specification must have an A in column 66.
Columns Value Meaning
16-18 ADD This record will be added to an
existing disk file.
The ADD entry must be on the first Form O line describing a record to
be added.
10.5 FETCH OVERFLOW
An F in this column indicates that the overflow routine can be used
for a printer file at this point.
Column Values Meaning
16 Blank Standard overflow
F Fetch overflow
An F can go on any total, detail or exception line except those
conditioned by an overflow indicator. Table 10-1 describes the effect
of overflow usage. An F in this column can cause printing of overflow
lines and a forms advance to occur before the printing of detail and
total lines is completed. Overflow can be fetched only if all the
conditions specified in columns 23-31 are met and overflow has been
sensed.
Forms advance takes place only by explicit request (probably on the
first heading line for a new page).
When fetch overflow has not been specified, all detail and total lines
conditioned for print during one cycle are printed. If any of those
lines get printed on or below the overflow line, all remaining lines
will be printed before output conditioned by the overflow indicator
gets done. Thus, if there are more lines remaining to be printed than
are available before the end of the page, unattractive output will
result. Use of the fetch overflow feature can ensure the occurence of
overflow processing before the page end is reached. Table 10-1
further describes the effects of overflow indicator usage.
Figure 10-2 illustrates partial specifications for fetching overflow.
Lines 030, 060, and 070 can fetch overflow. This can happen, however,
only when indicators OA and L1 are set. After overflow has been
fetched, the OA indicator is reset (following the forms advance
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-5
requested on line 010).
When the output line specified on line 030 is ready to be printed, and
OA and L1 are on, the forms advance occurs, the heading record (line
010) is printed, and records corresponding to lines 030 through 080
are printed on the new page. If overflow has not been sensed by line
030 but is set on when that line is printed, line 060 causes the
overflow routine to be fetched. In that case, the forms advance
occurs, the heading record is printed, and records described on lines
060 through 080 are printed on the new page.
Notice that if line 060 fetches overflow, line 070 will not, because
the overflow indicator will be reset at the forms advance.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-6
Table 10-1
Effects of Overflow Indicator Usage
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-7
10.6 FORMS CONTROL - SPACE/SKIP
RPGLIB allows relative and absolute forms control. Columns 17 and 18
allow up to three lines of spacing, before and/or after a print line,
relative to adjacent lines. Columns 19-22 allow absolute spacing to
any particular line on a page, before and/or after a print line. If
both spacing and skipping are specified on the same line, the skip
always precedes the space. Thus, entries in all four yields:
1. Skip before
2. Space before
(print required line)
3. Skip after
4. Space after
If all these columns are blank, single spacing occurs after each line
is printed. Entries in these columns are only applicable to printer
files.
10.6.1 Space Forms Control
Column 17 specifies the spacing before and column 18 the spacing after
printing a line.
Columns Values Meaning
17,18 Blank Default: blank in 17 = 0; blank in
18 = 1
1-3 Indicated number of spaces before
(column 17) or after (column 18)
printing. Entry in 17 yields same
number blank lines; in 18 yields one
less blank line.
Use of columns 17 and 18 does not conflict with the ADD encoding
described in 10.4 because records may not be ADDed to printer files,
and line spacing is not germane to disk or magtape files.
10.6.2 Skip Forms Control
Columns 19-20 and 21-22 specify skipping before and after printing a
line.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-8
Columns Values Meaning
19-20, or Blanks Skipping is not requested
21-22
01-99 Lines 01-99
A0-A9 Lines 100-109
B0-B2 Lines 110-112
The codes indicate the forms location of the next line to be printed.
An entry in columns 19-20 specifies a skip before the line is printed;
an entry in columns 21-22 specifies a skip after the line is printed.
When the skip is to a lower line number, the forms are advanced.
No action occurs when the forms are already positioned at the
specified line. Exception: There is no way to obtain overprint.
Thus, a skip to 5 before and after yields a skip to 5 on the next page
after printing.
If the destination of a skip (or space) is beyond the overflow line
but before a top of form, the overflow indicator is set on and remains
on until forms advance occurs.
A skip code cannot exceed the forms length specified on Form L, or 66,
if there is no Form L.
The skip function is useful in moving form stock more than the lines
possible by a spacing entry, or when the number of spaces to the de-
sired print position may vary. The skip function is also useful in
positioning for subtotal, total, and heading lines.
10.7 OUTPUT INDICATORS
Columns Values
23-31 any indicators
The output indicator entries can condition output of entire records
and/or their component fields. Any of the indicators associated with
RPG II may be specified.
The indicator codes are entered in columns 24-25, 27-28, 30-31 and are
in an AND relationship. If the indicator should be off for output to
occur, N goes in the preceding column (23, 26 or 29). If no
indicators, or only negative ones are specified for a heading or
detail operation, the record will be output before the first cycle.
Warning: Only one record can be written to an update file in one
cycle, so the user must be careful not to specify multiple records in
one cycle for update files.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-9
All total records conditioned by the LR indicator are produced last.
Control level indicators condition when output records or fields are
written. Total records (T in column 15) with no overflow indicator in
columns 23-31, are written only after the last record in a control
group has been processed. Detail records (D in column 15) with no
overflow indicator in 23-31, are written only after the first record
of the new control group has been processed. When columns 23-31
contain both a control level indicator and an overflow indicator, the
record is produced only when overflow has been sensed and the control
break has occurred.
Print records conditioned by an overflow indicator are produced only
when overflow has been sensed. An overflow indicator cannot condition
an E (exception) record but can condition a field of an exception
record. A specified overflow indicator must be identical to the
overflow indicator named on the Form F for the file that will receive
the record.
An overflow indicator may have an OR condition with the 1P indicator
if identical heading records will go on every page. The 1P indicator,
however, can be specified only for heading and detail print lines.
10.8 FIELD NAME
Entries in columns 32-37 identify each field to be included in the
output record or print line last specified.
Columns Values
32-37 1. Any field name previously defined in the program.
2. The special words PAGE, PAGE1, PAGE2, *PLACE,
UDATE, UDAY, UMONTH, and UYEAR.
3. The name of a table, array, or array element.
If a constant is to be included in the output, columns 32-37 are left
blank and the constant is defined in columns 45-70. If an entry is
made in the field name columns, columns 7-22 must be blank.
10.8.1 Field Names
The order in which the fields appear in the output record is
determined by the entries in columns 40-43 (described in paragraph
13), not by the order of the field name entries of Form O. A field
name is entered left-justified in columns 32-37. It must be
previously defined as a field of an input record in columns 53-58 of
the Input Specifications Form I or as a result field of an operation
in columns 43-48 of the Calculation Specifications Form C.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-10
If overlapping fields are specified in one record, the field listed
last overlays prior specifications, resulting in lost data.
10.8.2 PAGE, PAGE1, PAGE2
RPGLIB will automatically number print file pages if PAGE, PAGE1, or
PAGE2 is entered in columns 32-37 instead of a field name. (The three
names provide three page counters for multiple sections of a printed
output file). Each page of the output will be numbered consecutively
in the print position called out by columns 40-43. The page number is
taken from a four-digit numeric counter which RPGLIB increments by one
before using it on each page.
Page numbering usually starts with the number 1. The user can,
however, start with any number via a Calculation result or by
specifying a record on the Input Specification Form I containing a
field named PAGE, PAGE1, or PAGE 2. The field may be constant (one
less than the desired number) or dependent on input.
A page number may be reset to zero by use of the blank after code (B
in column 39) in the line where the page counter label is entered.
The reset function also may be conditioned by an output indicator such
as L1-L9. The output indicators for PAGE, PAGE1 or PAGE2 mean this:
Whenever indicator conditions assigned to PAGE, PAGE1 or PAGE2 are
satisfied, the specified page counter is reset to zero and incremented
by one before printing. Z-ADD or MOVE with the desired reset value
entered as a numeric literal in Factor 2 are two of the ways a
Calculation can change a counter value. Conditioning indicators may
be used in this case also.
10.8.3 *PLACE
The RPG II special word *PLACE allows fields to occupy more than one
position in an output record without being respecified. When *PLACE
is encountered, all fields previously specified for the record are
repeated in the same relative position, ending at the character
position named in columns 40-43 of the *PLACE line.
Rules for using *PLACE:
1. *PLACE goes on the line following the last field
specification which is to be repeated.
2. *PLACE entries may be made on successive lines.
3. An *PLACE specification causes all prior field specifications
for the record to be moved.
4. The end position specified for an *PLACE must be at least
twice the previously named end position for the record.
(This does not include previous *PLACE specifications.) If
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-11
not, some output fields will overlap, and characters will be
lost.
5. The starting (left-most) character position for an *PLACE
move is always position 1 of the record.
6. An *PLACE line cannot be conditioned by indicators in columns
23-31. *PLACE movements are automatically conditioned by
indicators listed in the preceding field specifications.
10.8.4 Date Field
The special words UDATE, UMONTH, UDAY, UYEAR refer to the current
system date. A reference to UDATE yields a six-character numeric
field in the format mmddyy. UMONTH refers to the 2-character mm, UDAY
to dd, and UYEAR to yy. When a UDATE field is edited (paragraph
10.11), the result is of the form mm/dd/yy.
None of these special words can be specified in the result field of a
calculations specification. Any of the words, however, can be Factor
1 and Factor 2 names on Form C.
10.9 EDIT CODES (COLUMN 38)
This entry is used to specify editing for numeric fields. No entry
should be made for alphanumeric fields, or if an editing word is
entered in columns 45-70. Modifiers affecting the editing function
specified in column 38 may be encoded in columns 45-47.
There are two kinds of edit codes. Codes in the first category do not
cause punctuation of the numeric output field, and entries in columns
45-47 are not allowed. Codes in the second category may cause
punctuation of the output field and affixing of negative balance
indicators, and entries in columns 45-47 are allowed. Table 10-2
summarizes the Edit codes.
A plus or minus sign is encoded with the low-order digit of an numeric
field. The sign is printed with the digit, producing a non-numeric
character, unless the field is edited.
10.10 BLANK AFTER
Column Values
39 Blank or B
The entry of B in this column causes the source field to be reset to
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-12
blanks if alphanumeric, or zeroes if numeric after the content of the
field has been placed in the output record. If no entry is made in
column 39, the source field remains unchanged. A blank after
operation can not be specified for a date field name (e.g., UDATE) a
look-ahead field, or a field in an update file.
When blank after is requested for a table name, RPGLIB blanks the
element corresponding to the one in the holding area, and the holding
area itself. When blank after is requested for a constant, the
constant is set to blanks after its first use.
Care must be taken in specifying blank after for a field which is used
in output. The blank after should be designated in the last record in
which the field is output to avoid premature clearing of the field.
Blank after provides a convenient means for resetting control break
accumulators after they are printed at total time.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-13
TABLE 10-2
Edit Codes
Column Values Meaning
Category 1 (no punctuation; no entry in 45-47 allowed)
38 X Suppress a plus sign for non-negative
fields.
Y Causes a date field to be edited as
follows:
mm/dd/yy
where the first digit of the date is
suppressed if zero.
Z Causes suppression of leading zeroes
in the output field and removal of the
sign.
Category 2 (punctuation; entry in 45-47 allowed)
1 Print with commas, print zero balance,
suppress sign.
2 Print with commas, suppress zero
balance, suppress sign.
3 Print without commas, print zero
balance, suppress sign.
4 Print without commas, suppress zero
balance, suppress sign.
A Print with commas, print zero balance,
print sign as CR. *
B Print with commas, suppress zero
balance, print sign as CR.
C Print without commas, print zero
balance, print sign as CR.
D Print without commas, suppress zero
balance, print sign as CR.
J Print with commas, print zero balance,
print sign as -.
K Print with commas, suppress zero
balance, print sign as -.
L Print without commas, print zero
balance, print sign as -.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-14
TABLE 10-2 (cont'd)
Edit Codes
Column Values Meaning
M Print without commas, suppress zero
balance, print sign as -.
* For codes A through M if the field is positive, no sign indication
is printed.
10.11 END POSITION IN OUTPUT RECORD
This entry specifies the rightmost or least significant position of
the designated field or constant in the output record.
Columns Values
40-43 any number less than or equal to the record length.
The entry is numeric and right-justified. Leading zeroes may be
omitted. The end position entry must not exceed the record length
specification for the file.
If punctuation or other charaters are added to the field by editing,
the effective field length is increased. The entry in columns 40-43
must reflect the length of the edited field. If columns 32-35 contain
PAGE columns 40-43 must show the low order position of the page number
in the print line. The end position of an *PLACE specification is the
rightmost character position to which the move occurs.
10.12 FIELD TYPE
Column Value Meaning
44 Blank Alphanumeric or unpacked decimal data
10.13 CONSTANT OR EDIT WORD, COLUMNS 45-70
The entries in these columns (1) define a constant to be placed in the
output record, (2) indicate a modification to the edit function coded
in column 38, or specify an edit word for output format.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-15
10.13.1 Constants
An alphanumeric constant may be defined by encoding an apostrophe in
column 45 followed by up to 24 characters in any combination
terminated by another apostrophe. Any alphanumeric characters
including blanks may be used. An apostrophe within the constant is
encoded by entering two consecutive apostrophes. EXAMPLE: IT'S is
defined as a constant by encoding 'IT''S' beginning in column 45.
When a constant is used as a source field for data in an output
record, Field Name (columns 32-37) must be left blank.
When a constant exceeding 24 characters is required, subsets of
characters go on successive lines, as if they were independent. Each
line must have an appropriate entry in columns 40-43.
10.13.2 Edit Code Modifiers -- * And $
Two edit code modifiers may be entered in columns 45 and 46,
left-justified, for use in conjunction with the Edit Code (column 38).
An asterisk (*) says that all leading zeroes of the numeric field
shall be replaced by the asterisk character. '$' indicates that a
dollar sign shall be placed just preceding the high order non-zero
digit of the numeric output field. This is called the floating dollar
sign function. The asterisk and dollar sign allow check protection.
10.13.3 Edit Words
The Edit Codes for column 38, plus asterisk and dollar signs provide
normal editing of typical numeric fields. The edit word facility
allows more unusual or complex editing. An edit word is like a mask
or framework which allows insertion of numeric characters from the
source field named in columns 32-37. Edit words allow inclusion of
decimal points, commas, dollar signs, negative balance indicator (if
any), even whole words between one digit and the next. Table 10-3
gives the rules for edit words.
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-16
Table 10-3
Rules for Edit Words
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-17
10.14 OUTPUT-FORMAT SPECIFICATIONS EXAMPLES
Figure 10-3 shows various examples of the Output-Format Specifications
Form O. The examples are discussed below.
Page 08 Lines 010 and 020--A header record for a file named PRTFIL is
to be spaced two lines after printing (column 18) and a skip
before printing should be made to line 6 (columns 19-20). The
line is printed if indicators 17, U3 and 06 are on, (AND in
columns 14-16), and 05 is not on.
Line 030--The same header record is printed if overflow
indicator OA is on.
Lines 040 through 070--The contents of UDATE are to be edited
and placed in the print line ending in position 68; the
contents of page counter PAGE1 are to end in position 100.
The remainder of the heading, consisting of the title PRINT
FILE LIST and the captions DATE and PAGE are supplied as
constants to be placed to end in positions 59 and 95. (Notice
that the length of the heading line required that components
be split.)
Line 080--A detail record of PRTFIL is printed if indicator 02
is on--the carriage is spaced one line after printing, since
no skip or space is indicated. Lines 090 and 100 describe the
fields of this record.
Line 090--FLD1 is placed to end in position 60 of the print
line. Leading zeroes are suppressed (Z in column 38).
Line 100--FLDX is zero suppressed and placed to end in
position 45 of the print line. RPGLIB will print FLDX only if
indicator 15 is on (15 in columns 24-25), and the record
conditioner 02 is on.
Line 110--If indicator L1 is on, RPGLIB will print a total
record of PRTFIL after a skip to line 60. Lines 120 and 130
describe the fields of this record.
Lines 120 and 130--The total line is made up of the caption
SUBTOTAL supplied as a constant and the field named ATOTAL.
RPGLIB will set this field to zeroes after printing (B in
column 39).
Line 140--If indicator LR is on RPGLIB will print a total
record of PRTFIL after spacing three lines. After printing
it, RPGLIB will skip to line 06.
Line 150 through 200--The total record has the following
configuration:
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-18
Figure 10-3
Output Example
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-19
Figure 10-3 (cont'd)
Output Example
OUTPUT - FORMAT SPECIFICATIONS - FORM O Page 10-20
Page 09
Line 010--A record is added (ADD in columns 16-18) to DSKFIL
if indicator 22 is on.
Line 020--The record consists of a field named DTL to be
output in binary format ending in position 80.
Line 030--RPGLIB will print a detail record of LISTFIL, with
one space after (default) if indicator 23 is on.
Lines 040 and 050--The detail line contains an account code
(ACCT in Field Name) and an amount (AMT in Field Name). The
source field AMT is edited according to the edit word given in
columns 45-62. The trailing asterisk entered in column 61 of
the edit word is placed in position 30 of the print line. The
edit word provides for the fixed dollar sign, comma and
explicit decimal point punctuation, zero suppression and
asterisk protection ending just before the decimal point, a
space after the cents position, the CR symbol if the source
field is negative, and a trailing asterisk.
CHAPTER 11
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING
Chapter 6 describes specification of tables and arrays. This chapter
describes their use and formation.
Tables are systematically arranged sets of information more limited in
scope than other files. Examples: tables of freight rates,
withholding percentages, prices, conversion coefficients. RPGLIB
treats tables much as clerks do in manual systems. A document (or
record) provides a piece of known information such as item stock
number. The clerk (or RPGLIB) then uses it to obtain another piece of
information from a table by search or lookup. Thus, item stock number
may be used in looking up the item price in a table of prices listed
by stock number.
Tables might be used to provide verification only. For example, an
input account code may be used to search a table of all active account
codes to determine the input code's validity. RPGLIB may extract an
element from a table with a MOVE operation.
RPG II allows table updating, whereby entries may be changed during
processing. An example is the substitution of new prices in a price
table.
Arrays are also systematically arranged sets of information which can
be searched for a uniquely identified data item. In addition, an
array element may be referenced by position number. Another
difference is that an unindexed reference to an array name is a
reference to the entire set of data rather than to an item in a
holding area (paragraph 9.4.6). RPGLIB can use an array element or
the entire array as an operand in a calculation.
Advantages of table and array formats over file formats: (1) A table
or array is compact and may be completely contained in computer memory
for random accessing. (2) Any member of the entire set of entries
comprising the table or array may be retrieved for use once or
repeatedly during the course of processing by an RPG II object
program.
Table names begin with TAB; array names do not. Both follow the
rules for naming fields.
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-2
Each element in a table or array has the same length, format
(alphanumeric or numeric), and number of decimal positions.
DEFINITIONS:
1. Compile Time Table or Array. A compile time table or array
is compiled with the source program and becomes part of the
object program. A compile time table or array can be
permanently changed only through recompilation, but it can be
output after other processing is completed at end of job, if
requested on Form E.
2. Pre-Execution Time Table or Array. A pre-execution time
table or array is loaded with the object just prior to
reading the first non-table or array input record. A
pre-execution time table or array can be modified by the
program and output at program termination.
3. Execution Time Array. An execution time array is read or
created during the input or calculations phase of an object
program cycle but cannot be output at program termination.
4. Related Tables and Arrays. Related tables and arrays are
files which are used together. They may be specified
separately or in alternating format. Whereas all items in
one table or array must have the same characteristics
(element length, etc.), related tables or arrays need not
have identical characteristics, nor must they contain the
same number of elements. When a search of related tables is
successful, corresponding items of the two tables are brought
to the holding areas. A successful search of related indexed
arrays causes the index field to point to the corresponding
items in the related arrays.
Figure 11-1 illustrates a use of related tables. A shipping
transaction file (at 1) is sequenced by a stock number within record
type within customer number. There is one type 1 record for each
customer and a variable number of type 2 records. The type 1 record
shows the date of shipment and the address to which shipment was made.
Each type 2 record shows a stock number for each item shipped and the
quantity shipped. Item stock numbers and associated item prices are
maintained in related tables (at 2). The stock number from the type 2
transaction record is used as a search argument for item price from
the price table (at 3). The price then is used in extending the item
quantity to produce line item price. A record for the line item is
output for invoicing. Figure 11-2 illustrates two methods for
specifying related tables.
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-3
Figure 11-1
A Use for Related Tables
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-4
Figure 11-2
Two Methods for Specifying Related Tables
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-5
5. Short Tables and Arrays. A short table or array contains
some null elements. Null elements equal zero, if numeric, or
blanks if alphanumeric. Significant elements may replace the
null elements at a later time. A short table or array must
have at least one non-null element.
6. Full Table or Array. Every element of a full table or array
contains significant data.
11.1 FORMING TABLES AND ARRAYS
Tables and arrays may be formed inside or outside the computer.
Elements formed on the outside may be entered through any input
device. Any computer program, including an RPG II program, may also
form them, and they may be output to any sequential file medium.
Tables and arrays have the same format and structure rules whether
they are formed outside or within the computer. The complete set of
entries comprising a table or array is considered a sequentially
organized file, although the entries need not be in sequence within
the table or array.
A table or array file must have a unique name consistent with the file
naming rules stated in Paragraph 1.6. The filename must not be
confused with the table or array name described earlier in this
chapter. Table and array files may be assigned to the same device, if
required. The files are read from the device in the order they are
specified on Form F.
Chapter Six describes rules for table files. An array file can abide
by the rules for table files or it can be described as any other input
file on the Input Specifications form, Form I. Exception: An
execution time array to be read by the program can only be described
on Form I.
The definition on Form I specifies whether the array is a single
record or many records, and whether the elements are contiguous in a
record. If the array name appears as the field name (paragraph 8.11)
then the array is contained in one record, and the elements are
contiguous. Otherwise, each array element must be specified on its
own Form I line, with the appropriate field positions specified. An
array cannot be used until every element is in core. Calculation and
output operations, therefore, may have to be suspended for several
program cycles until RPGLIB has read all array file records.
Figures 11-3 and 11-4 illustrate the coding required to fill an array
from contiguous elements of a single input record. Figure 11-5
illustrates that required when elements are separated by 1-character
values which serve as index values for the array.
Rules for entering a compile time table or array:
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-6
1. The table or array must be on the device that holds the
source program and follow the RPG II source program.
2. Each distinct table or array must be preceded by a record
having **b in positions 1-3. As this record is a delimiter,
the first element of a table or array record must not contain
those characters in the first three positions.
3. The last compile time table or array is followed by a record
reading /* in positions 1 and 2.
4. The tables and arrays must be loaded in the order specified
on Form E, ignoring any pre-execution time table and array
definitions that may be interspersed with compile time
entries on that form.
5. Numeric tables and arrays must be in unpacked decimal form.
Figure 11-6 illustrates the placement of compile time tables and
arrays in the compiler input stream. In this example, the user has
two of his own compile time tables, TABA and TABB.
Pre-execution time tables and arrays are not loaded with the source
program but rather just prior to execution of the object program.
Rules for pre-execution time tables or arrays:
1. Each table and array is terminated by an end of file. The /*
record is not used.
2. The tables and arrays are loaded before the first input
record is read.
3. Pre-execution time tables and arrays must be arranged in the
order specified on form F.
An execution time array is loaded or created during execution of the
object program. The array is not checked for sequence, but column 45
of Form E (Sequence) must contain an A or D code if high or low LOKUP
is specified for the array.
If the execution time array is in packed decimal or binary format, an
appropriate entry must be specified in column 43 of Form I. Length
specified for arrays in these formats reflect the packed or binary
length of an element, in numbers of bytes. Columns 19-26 and 46-57 of
Form E must be blank for execution time arrays. That is, the array
cannot be output at end of job, and an alternating array cannot be
specified.
In Figure 11-7, an array is to be built during the calculations phases
of execution. It is to contain square roots of the numeric values
contained in two input records. The first input record is defined by
a 1 in position 80; the second record type has a 2 in position 80.
The conventions for naming arrays have been established in preceding
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-7
paragraphs. The names must be shorter, however, when indexing is used
with the array name. When the array is used as the result field in
calculations specifications, the array name plus comma and index can
not exceed six characters, so the array name must be four characters
or less.
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-8
Figure 11-3
Coding to Fill an Array from Contiguous Elements
of a Single Input Record
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-9
Figure 11-4
Coding for Contiguous Elements of a Single Input Record
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-10
Figure 11-5
Illustration of Required Array Elements Supported
by One-Character Values
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-11
Figure 11-6
Placement of Compile Time Tables and Arrays
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-12
11.2 USING TABLES AND ARRAYS
LOKUP operations specify table and array search. Paragraph 9.4.6
describes LOKUP.
When elements in a short table or array are being added, deleted
(replaced by zeroes or blanks), or changed, the number of entries per
table or array is not altered by the operations. This number is fixed
on the Extention Specifications, Form E. Rather, the number of
meaningful entries in a table or array can be altered. By selection
of proper search arguments and criteria, the non-meaningful entries
can be ignored during processing.
The following rules apply when using arrays in Calculations
Specifications.
1. When Factor 1, Factor 2, and the Result Field specifications
are all unindexed array names, RPGLIB does the operation
using the first element of each array, then the second
element of each array, and so on until at least one of the
arrays is exhausted. Result field array elements not
participating in the calculations (i.e., unreferenced
elements in a longer array) remain the same.
2. When one of the factors is a field or constant and the other
factor and result field are unindexed arrays, RPGLIB does the
operation once for each element in the shorter array. RPGLIB
uses the field or constant in each operation, and does not
change unreferenced result field array elements.
3. Resulting indicators can not be specified unless the
operation code is LOKUP or XFOOT (yielding one result).
4. In arithmetic operations, arrays must be numeric.
Half-adjusting can be specified.
5. A Result Field can not be specified for the LOKUP operation.
In Output-Format Specifications, a table element and an indexed array
element are treated like any other field specification. Blank after
codes can be used.
When an unindexed array name is specified as a field name of Form O,
The value specified as the end position in the output record is the
position of the right-most character of the last element in the array.
Any editing specified for the array applied to each element in the
array. Elements, therefore, must be individually specified as indexed
elements if uniform editing can not be used.
RPGLIB automatically inserts two blank characters in front of each
element of the array unless an edit word is used. Edit words for
unindexed arrays must contain explicit leading blanks, if desired.
The following example illustrates the use of arrays in Output-Format
Specifications, and shows how they can reduce the number of coding
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-13
lines required. In this program three levels of totals are maintained
and output at specified control breaks.
In Figure 11-8, as input records are read and record identifying
indicator 25 is set, fields FLDA, FLDB, FLDC, and FLDD are added to
level 1 subtotals L1TA, L1TB, L1TC, and L1TD, respectively.
At a level 1 control break, the level 1 subtotals are added to
subtotals L2TA, L2TB, L2TC, and L2TD, respectively.
At a level 2 control break, totals L3TA, L3TB, L3TC, and L3TD are
updated. Total lines are output when the appropriate control level
indicators are on, and totals are blanked to zeroes after printing.
Since L1TA-L1TD, L2TA-L2TD, and L3TA-L3TD are first defined as result
fields in Form C, the fields have already been initialized to zeroes
by RPG II. They do not, therefore, require initial clearing by the
source program.
In Figure 11-9, execution time arrays SL1, SL2, and TL3 are defined
for accumulation of the various subtotals and totals. The output
produced by Figures 11-8 and -9 is identical. Figure 11-9, however,
eliminates most of the repetitious coding lines of Figure 11-8. Since
the array elements are defined on Form E in Figure 11-9, the
definitions are not repeated on Form C. Whereas in Figure 11-8 the
level 1-3 fields are defined with lengths of 6, 7, and 8 characters,
respectively, each element of each array is defined as 8 characters,
for equal spacing on the output line. The equal spacing occurs in
Figure 11-8 as a result of individual end position specifications for
the fields.
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-14
Figure 11-7
Example of an Array Built During the Calculations
Phase of Execution
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-15
Figure 11-7 (cont'd)
Example of an Array Built During the Calculations
Phase of Execution
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-16
Figure 11-8
Input Records
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-17
Figure 11-8 (cont'd)
Input Records
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-18
Figure 11-9
Definition of Execution Time Arrays
USE OF TABLES AND ARRAYS IN RPG II PROGRAMMING Page 11-19
Figure 11-9 (cont'd)
Definition of Execution Time Arrays
CHAPTER 12
RPG II FILE PROCESSING
The various file structures and modes of processing available in
RPG II were described briefly in Chapter 5. This chapter discusses in
detail the subject of record selection and the significance of file
structures to the modes of processing.
12.1 SEQUENTIAL FILE PROCESSING
All records in files with Sequential organization are written to the
storage medium with no intervening logical gaps -- each one followed
by the next.
Files may be in sequential organization on any medium subject to
specification for RPG II. Frequently, the records of a sequentially
organized file are logically in sequence. For RPG II, logical
sequence implies keys in the file that are in ascending or descending
order. RPG II can handle ordered and unordered sequentially organized
files. The SORT-10 program can put sequential files in order or
RPG II object programs can create them in order, if the input data is
in the correct sequence.
All files on any medium can be created in sequential order by RPG II.
Files on disk may be created with indexed organization to permit
random processing later. Other sequential disk files may be processed
non-sequentially as well through use of a record address file of tags
(ADDROUT file).
RPG II object programs process records of sequential files as they
appear from the beginning of the file. RPGLIB can process to end of
file, or stop in the middle (see paragraph 5.4, END OF FILE).
Example: A customer billing address file is referenced in preparing
bills for mailing. When the record of the last customer to be billed
has been reached, there is no further use for the mailing address file
in this run, although there may be many address records remaining in
the file.
An indexed file may be processed from beginning to end of the index or
within limits supplied by a record address file. Example: A program
must process an inventory file to generate an inventory valuation
RPG II FILE PROCESSING Page 12-2
report for selected warehouses. If the file is sequenced by stock
number within warehouse, the record address file specifies the lowest
and highest possible record keys for the warehouses for which the
report is desired.
When there is only one input file it is the primary file (P in col.
16 of Form F). The entire file is processed beginning with the first
record and continuing until end of file. At end of file, RPGLIB sets
on the LR (last record) indicator, and starts end of job activities.
With multiple input files, one is primary and the other(s) are
secondary. If there is no relationship between the processing of the
files, RPGLIB processes the primary file to end of file before it
processes the secondary file(s). RPGLIB processes two or more
secondary files in the order of their Form F descriptions.
When a record matching relationship exists among multiple files, the
file which controls processing is primary and the others are
secondary. In the example of mailing bills, the billing transaction
input file would be primary and the billing address file would be
secondary. The problem determines primary and secondary designations.
In a file update involving posting, posting occurs to the record
currently being processed. In this case, the posting file is
designated a secondary file, ensuring that individual records to be
posted (from the primary file) have already been read and are
available.
In the following discussion of primary and secondary input files, note
that RPGLIB first reads records into a read area, and then moves them
to a process area. When a control break occurs, RPGLIB executes all
control break processing and then moves the record to the process
area.
12.1.1 Matching Records
Interrelated multiple files are processed via the matching record
technique. The matching field entries on Form I (columns 61-62)
determine when records of a secondary file are to be processed.
Rules for matching field entries:
There can be up to nine matching field specification
entries (M1-M9) per record.
The locations of the matching fields within a record
type of file must be the same for all records of that
type.
The locations of the matching fields in different
record types may be different.
Not all the record types in a file need have a
matching field.
RPG II FILE PROCESSING Page 12-3
Records can be matched by one field, many fields, or
the entire record.
The same number of matching field entries must be
specified for records of two or more files being
matched.
The combined lengths of the matching fields for a
given record must equal the combined lengths for any
record to be matched.
The combined lengths must not exceed 256 bytes.
If matching fields are specified for a single input
file, they are used in sequence checking of the file.
Matching fields can be specified for a file even if not all records
are to be matched. A matching field entry is not made for records
which are not to be matched.
RPGLIB turns on the Matching Record Indicator (MR) when a match occurs
among records of a primary file and secondary file(s). This indi-
cator may condition calculation operations and output functions
specified on Forms C and O. RPGLIB leaves the MR indicator on during
the complete processing of the record and turns it off after all
calculations and printing specified for the record are completed.
If no matching occurs among records of a primary file and secondary
file(s), the MR indicator is not turned on. Its off status may con-
dition calculations for unmatched records or selection of unmatched
records for output.
If there is more than one matching field entry for a record, the codes
M1-M9 must be assigned in turn to the fields of increasing
significance, in the order of significance of the match. If a
matching field in any record is defined as numeric, the fields at that
same level (i.e., having the same value of Mn, will be treated as
numeric in all records to be matched. If all fields at a given level
are defined as alphanumeric, they will be compared logically.
In matching records of primary and secondary files, four situations
can occur:
1. There is a matching primary record.
2. There is a matching secondary record.
3. There is an unmatched primary record.
4. There is an unmatched secondary record.
Rule for order of processing: Records having no designated matching
fields are processed before records having matching fields. When
records match, the primary file record is processed first; when the
RPG II FILE PROCESSING Page 12-4
records do not match, the record first in sequence according to the
matching field value is processed regardless of file. Matching
records of additional secondary files are processed in the order of
specification of the files on Form F.
Figure 12-1 illustrates the selection based on matching fields of
records from one primary and one secondary file. The result is shown
as a merger of the two files. The MR indicator is on (set) during
processing of the shaded records. The files shown are in ascending
sequence; the record selection would be inverted if the files were in
descending sequence.
RPG II FILE PROCESSING Page 12-5
Figure 12-1
Selection Based on Matching Fields
RPG II FILE PROCESSING Page 12-6
Figure 12-2
Read and Process Areas for
Records in Figure 12-1
RPG II FILE PROCESSING Page 12-7
Figure 12-2 (cont'd)
Read and Process Areas for
Records in Figure 12-1
RPG II FILE PROCESSING Page 12-8
12.1.2 Look-Ahead Fields
Look-ahead extends the matching record capability by allowing fields
in the read area to be used before the record has been selected for
processing. Look-ahead can not be specified for chained or demand
files, as records in these files are not held in a read area before
processing.
Figure 12-2 illustrates the read and process areas as the records in
Figure 12-1 are being selected.
In picture 1, the first record of each file has been read. In picture
2, the secondary record with no matching field specification has been
selected for processing. In pictures 2 through 4, the records
selected for processing and available for look-ahead are charted
below:
Records
Picture Record Being Processed Available
2 S1 P1 and S2
3 P1 P2 and S2
4 P2 P3 and S2
Look-ahead can be specified for an update file, but it applies to the
current record of the file only. A copy of the current update record
remains in the read area until the end of cycle; thus, the next
record is not available for look-ahead until the next cycle.
If the primary file in Figure 12-1 were an update file, the read and
process areas would take the configurations shown in Figure 12-3. In
pictures 2 through 4, the following list indicates the current record
being processed and the records available for look-ahead.
Records
Picture Record Being Processed Available
2 S1 U1 and S2
3 U1 U1 and S2
4 U2 U2 and S2
Figure 12-4 illustrates an application for look-ahead fields. A price
table is defined as a primary update file named PTABLE. Price changes
for some items in the table are contained in a secondary file named
SFILE. When matching occurs, the new price is taken from SFILE and
placed in positions 11-18 of the PTABLE record. When matching does
not occur and a secondary record is being processed, the erroneous
record is printed out.
RPG II FILE PROCESSING Page 12-9
Figure 12-3
Read and Process Areas if Figure 12-1
Were an Update File
RPG II FILE PROCESSING Page 12-10
Figure 12-3 (cont'd)
Read and Process Areas if Figure 12-1
Were an Update File
RPG II FILE PROCESSING Page 12-11
Figure 12-4
An Application for Look-Ahead Fields
RPG II FILE PROCESSING Page 12-12
Figure 12-4 (cont'd)
An Application for Look-Ahead Fields
RPG II FILE PROCESSING Page 12-13
12.2 INDEXED FILE PROCESSING
Indexed (ISAM) files may be loaded by RPG II as output files. As this
occurs (through use of the indexed access method -- ISAM), RPGLIB uses
the record keys to form an index. Once the file has been loaded, ISAM
may be used to access records in later runs on a random basis. RPGLIB
uses the record key of the desired record to find the index that
points to the right record. The record then may be used as an
information source for other processing or changes may be made to the
record, after which it is returned to its position in the disk file.
NOTE
It is very important that the user
understand that RPG II is not capable of
actually creating indexed files. In
order for RPG II to utilize the ISAM
access method, the file must first be
created using the ISAM program. This
program will create an empty indexed
file, which can then be loaded with data
via an RPG II program.
RPGLIB can add new records to an indexed file which is being accessed
randomly. ISAM provides for changing the index as required to
accommodate the new record.
Processing an indexed file with specific keys using CHAIN allows
greater selectivity than processing within limits. Further, while
processing within limits reduces the number of records to be handled,
it still requires sequential accessing within those limits. With
CHAIN the order of processing may be completely non-sequential. This
mode of processing allows retrieval of specific information in an
indexed file. For example, an inventory manager may be concerned
about the balances of certain critical stock items. Inquiry can be
accomplished by entering the critical item numbers in a file to be
used with the CHAIN operation.
Figure 12-5 illustrates the creation of an indexed file on disk or
DECtape. In the example, the values in parentheses are the re- cord
key values (one digit numbers for simplicity in this case). D1, D2,
etc. are disk addresses.
12.3 DIRECT FILE PROCESSING
Direct access files are sequentially organized disk files which also
may be processed randomly. Records are retrieved through ADDROUT
files or with the CHAIN operation. A direct file is created in RPG II
through the CHAIN operation.
Because a direct file is not organized according to a known key
RPG II FILE PROCESSING Page 12-14
sequence, sequential processing of the file by key or limits is not
possible. Figure 12-6 illustrates the organization of a direct file
on disk. At file creation, relative record numbers are supplied with
the records to be loaded. The shaded areas in the illustration
indicate null records (containing blanks) into which a record was not
loaded.
RPG II FILE PROCESSING Page 12-15
Figure 12-5
Indexed File Organization
Figure 13-6
A Direct File Load
APPENDIX A
SUMMARY OF RPG II SPECIFICATIONS
This appendix is provided as a brief summary of Chapters 3-10. It is
intended as a quick reference for programmers who are acquainted with
RPG II.
On any form, columns for which specifications are not listed are to be
left blank.
A.1 COMMON ENTRIES
RPG II specifications forms should be ordered in ascending numeric
sequence based on columns 1-5. Pages should be arranged in the
following order and numbered accordingly:
1. Control Specification (Form H)
2. File Description Specifications (Form F)
3. Extension Specifications (Form E)
4. Line Counter Specifications (Form L)
5. Input Specifications (Form I)
6. Calculation Specifications (Form C)
7. Output-Format Specifications (Form O)
Columns 1-2 (Page) Numeric page number
Columns 3-5 (Line) Numeric line number within page
Column 6 (Form Type) Enter an H, F, E, L, I, C, or O to
indicate the specifications form type.
Column 7 (Comments) An asterisk in this position indicates
that the entire line is commentary.
SUMMARY OF RPG II SPECIFICATIONS Page A-2
Columns 75-80 (Program ID) Enter any valid character into these
columns to identify the object
program. Only the entry on Form H is
used to identify the program.
SUMMARY OF RPG II SPECIFICATIONS Page A-3
A.2 CONTROL SPECIFICATIONS - FORM H
Column 15 (Debug)
Blank DEBUG operation not used.
1 DEBUG operation used.
Column 41 (Forms Positioning)
Blank 1P line printer only once
1 First 1P line printed repeatedly to allow
forms positioning.
SUMMARY OF RPG II SPECIFICATIONS Page A-4
A.3 FILE DESCRIPTION SPECIFICATION - FORM F
Columns 7-14 (Filename)
Enter a 1-8 character RPG II filename, beginning in column 7.
Each name must be unique in the first six characters.
Column 15 (File Type)
I Input
O Output
U Update
C Combined
D Display
Column 16 (File Designation)
Blank Display or output file other than chained
output file.
P Primary
S Secondary
C Chained
R Record address
T Table or array
D Demand
Column 17 (End of File)
Blank Program can end before end of file is reached
on this file.
E Program termination not possible before end of
file on this file.
If column 17 is blank or E for all files, every record of
every input and update file is processed before the program
terminates. An E in this column requires an I, U, or C in
column 15, and a P, S, or R in column 16.
Column 18 (Sequence)
Blank Sequence checking not requested.
A Records to be checked for ascending sequence.
SUMMARY OF RPG II SPECIFICATIONS Page A-5
D Records to be checked for descending sequence.
An entry is required here when matching fields are used.
Column 18 applies to primary and secondary files; these files
must conform to the same sequence specification.
Column 19 (File Format)
F Fixed length records
All files are required to have fixed length records.
Columns 20-23 (Block Length)
2-4096
Block length must be an even integral multiple of record
length.
Columns 24-27 (Record Length)
Device Maximum Record Length
TAPEn, DISK 4096
READ01 80
CONSOLE, MFCUn 96
PRINTER 132
Column 28 (Mode of Processing)
Blank Sequential by key
Consecutive
R Random by relative record number
Random by key
By ADDROUT file
Direct file load (Random load)
This column applies only to file-structured devices.
Column 29-30 (Length of Field or Record Address Field)
Indexed Length of record key
file
ADDROUT Length of record
file
Maximum record key length is 64 characters.
SUMMARY OF RPG II SPECIFICATIONS Page A-6
Column 31 (Record Address Type)
Blank Sequential, direct, or consecutive
A Indexed file, alphanumeric key
I ADDROUT file or processed by ADDROUT file
This column applied to input, update, or chained output files.
Column 32 (File Organization or Additional I/O Area)
I Indexed organization
T ADDROUT file
Blank Sequential or direct file; uses one I/O area
for the file
Columns 33-34 (Overflow Indicator)
OA-OG, OV Overflow indicator used to condition records
in the file
Blank No overflow indicator is used
Column 35-38 (Key Field Starting Location)
For indexed files, enter the beginning position of the key
field in the record.
Column 39 (Extension Code)
E The file described on this line is a table
file, array file or record address file
further described on extension specifications
(Form E).
L The File described on this line is a printer
file further described on line counter
specifications (Form L).
Columns 40-46 (Device)
Enter the device code for the input/output unit used by the
file specified in columns 7-14, as follows:
SUMMARY OF RPG II SPECIFICATIONS Page A-7
Actual Device RPG Device System Device Name
Multi-Function Card Unit 1 MFCU1 DSK:??????.MF1
Multi-Function Card Unit 2 MFCU2 DSK:??????.MF2
Card Reader READ01 CDR:
Line Printer PRINTER LPT:
Line Printer PRINTR LPT:
Interactive Terminal CONSOLE TTY:
Disk DISK DSK:
Magnetic Tape Unit n TAPEn TAPEn:
Columns 47-52 (Physical File Name)
Specify a six character (alphanumeric with leading alphabetic)
name which can be used as the system filename, under which the
file is to be stored in the user's directory. The three
character extension is defaulted as follows:
Extension Type of File
MFn MFCU input hopper n file
STn MFCU output stacker n
IDA ISAM data file
IDX ISAM index file
RGA RPG II ADDROUT address file
RGD Miscellaneous data file (anything other than
above)
Column 60-65 (Unused)
Column 66 (File Addition)
A New records will be added to the file.
This position applies to sequential and indexed disk files.
Column 70 (Tape Rewind)
Specifies what is to be done to the tape after processing is
done.
Entry Action
R Rewind tape at end of file.
U Unload tape at end of file.
N or Blank Leave tape at end of file.
SUMMARY OF RPG II SPECIFICATIONS Page A-8
A.4 EXTENSION SPECIFICATIONS - FORM E
Columns 11-18 (From Filename)
1. The filename of a pre-execution time table or array;
2. The filename of a record address file named on Form F.
Columns 19-26 (To Filename)
1. The output file to which the compilation or pre-execution
time table or array is to be written at job termination.
Leave To Filename blank if the table or array is not
written out.
2. The name of the file for which the From Filename record
address file controls record selection.
Columns 27-32 (Table or Array Name)
Enter the name of a table or array used in the program. Table
names start with the three characters TAB; array names must
not start with TAB. If alternating tables or arrays are
specified on this line, enter here the name of the table or
array to which the first element of the input record(s)
belongs.
Columns 33-35 (Number of Entries per Record)
Enter the number of table or array elements contained in each
record. An entry must be made here for compilation and
pre-execution time tables and arrays; these positions must be
blank for execution time arrays.
Columns 36-39 (Number of Entries per Table or Array)
Enter here, right-justified, the maximum of entries in the
table or array named in columns 27-32. When alternating
format is used, a pair of elements is considered to be one
entry.
Columns 40-42 (Length of Entry) Enter, right-justified, the length of
each table or array entry. The maximum length is 256 for
alphanumeric entries and 15 for numeric entries. For packed
binary tables and arrays, enter the number of bytes of storage
required to represent the data in unpacked format.
Column 43 (Field Type)
Blank Alphanumeric or unpacked data in table or
array
SUMMARY OF RPG II SPECIFICATIONS Page A-9
Column 44 (Decimal Positions)
Blank Alphanumeric table or array
0-9 Number of positions to be right of the decimal
(0 of integers)
Column 45 (Sequence)
Blank No particular sequence
A Ascending sequence
D Descending sequence
This position describes the sequence of data in a table or
array. Column 45 must contain an entry if high or low look-up
is to be used.
Columns 46-57 (Alternate Table or Array)
These positions, corresponding in definitions to columns
27-45, describe a table or array which is in alternating
format with the table or array named in columns 27-32.
Columns 58-74 (Comments)
An entry in these columns is assumed by the compiler to be
entirely commentary.
SUMMARY OF RPG II SPECIFICATIONS Page A-10
A.5 LINE COUNTER SPECIFICATIONS - FORM L
Columns 7-14 (Filename)
Enter the name of a printer file for which you wish to specify
a form size and overflow line.
Columns 15-17 (Line Number - Number of Lines per Page)
1-112 Number of lines available for printing on the
printer form
Blank Standard value of 59 is assumed
Columns 18-19 (Form Length)
Enter FL to indicate that the previous entry is the forms
length.
Columns 20-22 (Line Number - Overflow Line)
1-112 Number of the overflow line
Blank Standard value of 65 is assumed
Columns 23-24 (Overflow Line)
Enter OL to indicate that the previous entry is the overflow
line.
SUMMARY OF RPG II SPECIFICATIONS Page A-11
A.6 INPUT SPECIFICATIONS - FORM I
Entries must be made on this form for every input and update file used
in the program.
Columns 7-14 (Filename)
The filename of an input or update file.
Columns 15-16 (Sequence)
Enter a 2-digit number to assign a special sequence to record
types in a file and to request that the record type sequence
be checked by the program. Enter two alphabetic charaters to
indicate that record type sequence is not checked. Alphabetic
characters must be used for a chained file. Within a file,
record types with an alphabetic sequence entry must be
described before record types with a numeric sequence entry.
Column 17 (Number)
Blank Positions 15-16 contain alphabetic characters
(record type sequence is not being checked)
1 Positions 15-16 contain numeric characters;
only one record of this type is present in
each
N Positions 15-16 contain numeric characters;
one or more records of this type can be
present in the sequenced group
Column 18 (Option)
Blank Record type must be present
O Optional. Record type may or may not be
present
This position is used when columns 15-16 contain a numeric
entry.
SUMMARY OF RPG II SPECIFICATIONS Page A-12
Columns 19-20 (Record Identifying Indicator, **)
01-99 Record identifying indicator
L1-L9 Control level indicator used as a record
identifying indicator when record type rather
than control field signals start of a new
control group
LR Last record indicator
H1-H9 Halt indicator used as a record identifying
indicator when checking for a record type that
causes an error condition
** Look-ahead fields
Columns 21-41 (Record Identification Codes)
This field is divided into three identical sub-fields. An AND
relationship exists between the sub-fields.
Columns 21-24 (Position)
Blank A record identification code is not specified
1-4096 Character position of the record
identification code
Column 25 (Not)
Blank Either columns 21-24 are blank or the
character (or zone or digit) must be present
to identify the record
N the character, zone, or digit must not be
present in the position being described
Column 26 (C)
C Entire character
Additional record identification codes are specified as above
in columns 27-32 and 33-41, if necessary. If more than three
codes are needed to identify a record, enter AND in columns
14-16 of the next line and enter additional codes. Enter OR
in columns 14-15 of the next line if an OR relationship exists
between the codes. Up to 20 AND or OR lines in any
combination can be specified for one record.
Column 43 (Field Type)
Blank Input field in unpacked decimal or
alphanumeric format
SUMMARY OF RPG II SPECIFICATIONS Page A-13
Columns 44-51 (Field Location)
Enter two 1-4 digit numbers to identify the beginning of a
field (From) and the end of a field (To) in the input record.
These entries are identical for a one-position field.
Column 52 (Decimal Position)
Blank Alphanumeric field
0-9 The number of decimal positions in the numeric
field named in positions 53-58 (zero for an
integer)
Columns 53-58 (Field Name)
These positions name the field specified in columns 43-52.
The following entries can be made here:
A valid RPG II field name
An array name element
The special words PAGE, PAGE1, OR PAGE2
Columns 59-60 (Control Level)
Blank The field being described is not a control
field
L1-L9 The level of the control field being defined
These columns must be blank for chained or demand files.
Columns 61-62 (Matching Fields)
Enter a matching-level identifier (M1-M9) to indicate matching
fields and sequence checking when you have two or more input
or update files with matched fields. When you have just one
input or update file with match fields this entry causes only
sequence checking.
Columns 63-64 (Field Record Relation)
01-99 Record identifying indicator assigned to a
record type.
L1-L9 Control level indicator previously used.
MR Matching record indicator.
U1-U8 External indicator previously set
H1-H9 Halt indicator previously used.
SUMMARY OF RPG II SPECIFICATIONS Page A-14
The following general rules apply to this entry:
1. All fields without field record relation should be
specified before fields with field record relation
2. All fields with the same field record relation entry
should be entered on consecutive lines.
3. All parts of a split control field must have the same
field record relation entry and must be described on
consecutive specification lines.
Columns 65-70 (Field Indicators)
01-99 Field indicator
H1-H9 Halt indicator (when checking for an error
condition in the field data)
When indicators are specified in these positions, RPG II make
appropriate settings when the field is input. When the field
is numeric, indicators are specified for positive, negative,
and zero conditions in columns 65-66, and 69-70, respectively.
One, two, or three indicators can be specified, but only the
indicator which reflects the result of the test is set on;
other specified indicators are set off. An alphanumeric field
can be tested only for all blanks (columns 69-70).
SUMMARY OF RPG II SPECIFICATIONS Page A-15
A.7 CALCULATION SPECIFICATIONS - FORM C
Columns 7-8 (Control Level)
Blank Operation done at detail time
L0 Calculation is performed at total time (always
on)
L1-L9 Calculation operation is done when the
appropriate control break occurs or the
specified indicator is set on
LR Calculation operation is done after the last
record has been processed or after LR has been
set on
SR Calculation operation is part of a subroutine
Calculation specifications must be ordered by the sequence
listed above. AND or OR can be entered in these positions to
indicate that indicators (columns 0-17) on the line are in an
AND or OR relationship with indicators on the preceding line.
Columns 9-17 (Indicators) Enter one to three indicators. Any RPG II
indicators except 1P and LO can be used. Columns 9, 12, and
15 may contain blank or N. An AND relationship exists between
indicators on a line. Additional lines may be used containing
indicators in columns 9-17 which are in an AND or OR
relationship with those on the first line by entering AND or
OR in columns 7-8.
Columns 18-27 (Factor 1) and Columns 33-42 (Factor 2) Factor 1 and
Factor 2 may contain the following entries:
1. Name of any field that has been defined
2. Alphanumeric or numeric literal
3. Subroutine, table or array name, or array element
4. Date field name (UDATE, UMONTH, UDAY, UYEAR)
5. Special name (PAGE, PAGE1, OR PAGE2)
6. Label for a TAG, BEGSR, or ENDSR operation (Factor 1) or a
label for a GOTO or EXSR operation (Factor 2)
7. Filename (first 6 characters) for a CHAIN, DEBUG, DSPLY,
READ, or FORCE operation (Factor 2)
SUMMARY OF RPG II SPECIFICATIONS Page A-16
Columns 28-32 (Operation)
ADD EXCPT MOVE SUB
BEGSR EXIT MOVEA TAG
BITOF EXSR MOVEL TESTB
BITON FORCE MULT TESTZ
CHAIN GOTO MVR TIME
COMP LOKUP READ XFOOT
DEBUG MHHZO RLABL Z-ADD
DIV MHLZO SETOF Z-SUB
DSPLY MLHZO SETON
ENDSR MLLZO SQRT
Columns 43-48 (Result Field)
Enter the name of the field, table, array, or array element
that holds the result of the operation specified in positions
28-32. If the field named in Result Field has not been
defined in extension, input, or previous calculation
specifications, it must be defined by making entries in
positions 49-52.
Columns 49-51 (Field Length)
Blank The result field entry was defined elsewhere
1-256 Result field length (right-justified)
The maximum length of a numeric field is 15 digits; the
maximum length of an alphanumeric field is 256 characters.
Column 52 (Decimal Positions)
Blank Field designated elsewhere or alphanumeric
field
0-9 Number of decimal places in a numeric field
Column 53 (Half Adjust)
Blank Do not adjust the result field
H Half adjust the result field
Half adjusting can be specified only with arithmetic
operations.
Columns 54-59 (Resulting Indicators)
Enter any of the following indicators: 01-99, H1-H9, L1-L9,
LR, OA-OG, and OV. Columns 54-59 are used:
1. To test the value of the result field after an arithmetic
operation. Enter up to 3 indicators to test for a
positive result (columns 54-55), negative result (columns
SUMMARY OF RPG II SPECIFICATIONS Page A-17
56-57), or a result of zero (columns 58-59).
2. To check the outcome of a CHAIN, LOKUP, COMP, or TESTB
operation. With the CHAIN operation, an indicator
specified in columns 54-55 is set on if the record is not
found.
With the LOKUP operation, up to 3 indicators are specified
to indicate that Factor 2 is HIGH (columns 54-55). LOW
(columns 56-57), or equal (columns 58-59). For the COMP
operation, up to 3 indicators are specified to indicate
that Factor 1 is greater than (columns 54-55), less than
(columns 56-57), or equal to (columns 58-59) Factor 2.
With the TESTB operation, resulting indicators have the
following meanings:
Positions 54-55: An indicator in these positions is
turned on if each bit specified in Factor 2 is off in the
Result Field.
Positions 56-57: An indicator in these positions is
turned on if two or more bits were tested and of mixed
status (some bits on and some bits off).
Positions 58-59: An indicator in these positions is
turned on if each bit specified in Factor 2 is on in the
Result Field.
3. To specify up to 3 indicators to SETON or SETOFF.
4. To indicate end of file for the READ operation code. An
indicator specified in columns 58-59 is set on if an
end-of-file condition is reached through a READ operation.
Columns 60-74 (Comments)
The compiler treats entries in these columns as entirely
commentary.
SUMMARY OF RPG II SPECIFICATIONS Page A-18
A.8 OUTPUT - FORMAT SPECIFICATIONS - FORM O
Columns 7-14 (Filename)
Enter a valid RPG II filename for each output and update file
used. Each filename need be specified only once, on the first
line describing that file.
Columns 14-16 (AND/OR Relationship) Enter AND in positions 14-16 or OR
in positions 14-15 if output records are in an AND or OR
relationship.
Column 15 (Type)
H Heading record description
D Detail record description
T Total record description
E Exception record description
Columns 16-18 (Add a Record) Enter ADD in these columns if the record
is added to an input, update or output disk file. An A must
also be coded in position 66 of the File Description sheet for
the file to which a record is added.
Column 16 (Fetch Overflow)
Blank Standard overflow procedures in effect
F Fetch overflow routine used
Columns 17-22 (Space/Skip) If these columns are blank, single spacing
occurs after each line is printed. Spacing and skipping are
not allowed on the printer/keyboard.
Columns 17-18 (Space)
Enter a number (1-3) to specify how many lines to skip before
(column 17) and after (column 18) a line is printed.
Columns 19-22 (Skip)
Blank No skipping
01-99 Lines 1-99
A0-A9 Lines 100-109
B0-B9 Lines 110-112
Enter one of the two-character specifications listed above to
indicate the next line to be printed. A skip before printing
is specified in columns 19-20, a skip after, in columns 21-22.
SUMMARY OF RPG II SPECIFICATIONS Page A-19
If the skip line number is less than the current line number,
a skip to a new page occurs.
Columns 23-31 (Output Indicators)
Enter one to three indicators to condition the output record.
Any RPG II indicators can be specified. An N may be entered
in columns 23, 26, and 29 to indicate negative conditioning.
An AND relationship exists between indicators on a line. Up
to 20 additional sets of indicators can be specified following
lines having AND in columns 14-16 or OR in columns 14-15.
Columns 32-37 (Field Name)
Enter one of the following to name every field written out:
Any field name previously defined in this program.
The special words, PAGE, PAGE1, PAGE2, *PLACE, UDATE UDAY,
UMONTH, and UYEAR.
A previously defined table name, array name, or array
element.
These positions must be blank if a constant is entered on
positions 45-70 of the line. If an entry is made under field
name, positions 7-22 must be blank.
Column 38 (Edit Codes)
Enter an edit code in position 38 when you want to:
1. Suppress leading zeros for a numeric field.
2. Omit a sign from the low order position of a numeric
field.
3. Punctuate a numeric field without setting up your own edit
word.
A table summarizing the edit codes that can be used is printed
above positions 45-70 on the Output-Format Sheet.
Column 39 (Blank Option)
Blank Field is not modified after output
B Field is reset to blanks (if alphanumeric) or
zeros (if numeric) after being output
This column must be blank for look-ahead and update fields.
If field name is a table name, the last table element
retrieved is reset.
Column 40-43 (End Position in Output Record)
SUMMARY OF RPG II SPECIFICATIONS Page A-20
Positions 40-43 indicate the location on the output record of
the field or constant written. Enter the number of the
position occupied by the right-most character of the output
field. The end position entry must not be greater than the
record length.
Column 44 (Packed or Binary Field)
Blank Field is unpacked numeric or alphanumeric data
Position 44 must be blank with *PLACE fields.
Column 45-70 (Constant or Edit Word)
Constant
1. Field name (positions 32-37) must be blank.
2. A constant is enclosed in apostrophes. Enter the leading
apostrophe in position 45.
3. An apostrophe is represented in a constant by two
apostrophes.
4. Up to 24 characters of constant information can be placed
in one line. Additional lines may be used, but each line
must be treated as a separate line of constants. The end
position of each line must appear in positions 40-43.
Edit Word
Enter any edit word to specify editing of numeric fields.
Edit words must be enclosed by apostrophes. Constants are
allowed within edit words. Edit words are not used with edit
codes. However, when edit codes 1-4, A-D, and J-M are used,
positions 45-47 may contain an * (to denote asterisk fill) or
a $ (to denote a floating dollar sign).
APPENDIX B
REFERENCE TABLES
Table B-1
Edit Codes
Edit Decimal Sign for Negative Value Zero
Code Commas Point No Sign CR - Suppress
1 Yes Yes No Sign Yes
2 Yes Yes No Sign Yes
3 No Yes No Sign Yes
4 No Yes No Sign Yes
A Yes Yes CR Yes
B Yes Yes CR Yes
C No Yes CR Yes
D No Yes CR Yes
J Yes Yes - Yes
K Yes Yes - Yes
L No Yes - Yes
M No Yes - Yes
X No No No
Y No No Yes (1)
Z No No Yes
(1) The left-most zero, only, is suppressed.
REFERENCE TABLES Page B-2
Table B-2
Operation Codes
REFERENCE TABLES Page B-3
Table B-2 (cont'd)
Operation Codes
Table B-3
Summary of Program Indicators
REFERENCE TABLES Page B-4
Table B-3 (Cont'd)
Summary of Program Indicators
REFERENCE TABLES Page B-5
Table B-4
Valid Indicators
APPENDIX C
RPG II CYCLE
RPG II CYCLE Page C-2
RPG II CYCLE Page C-3
RPG II CYCLE Page C-4
For each record that is processed, the RPG II object program goes
through the same general cycle of operations. After a record is read,
there are two different instances in time when calculations are
performed, and records written out. These instances are called total
time and detail time. During total time, all total calculation
operations (those conditioned by control level indicators in columns
7-8 of the Calculation Sheet) and all total output operations (those
conditioned by control level indicators) are done. During detail
time, all detail calculation operations (those not conditioned by
control level indicators in columns 7-8) and all detail output
operations are done. Total time includes steps 18 and 19 of the
RPG II object program cycle; detail time includes steps 25 and 3 of
the cycle.
Total calculations are performed before the information on the record
selected for processing is made available. Detail calculations are
performed after the information on the selected reocrd is made
available. The following discussion describes this concept in detail.
Whenever a record is read, a check is made to determine if information
in a control field (when one has been specified) is different from
control field information on the previous record. A change in the
control field information indicates that all records from a particular
group have been read, and that a new group is starting. When all
records from a group have been read (indicated by control level
indicators turning on), operations may be done using information
accumulated from all records in that group. At this time, all
calculations conditioned by control indicators in columns 7-8 are
done. Total output operations are performed immediately after all
total calculations are completed. Remember that information on the
record read at the beginning of the program cycle is not used in these
operations; only information from records in the previous control
group is used.
Detail calculations (all calculations not conditioned by control level
indicators in columns 7-8) occur after the information on the selected
record has been made available. Detail calculations are used to
calculate values needed each time a record is processed. They are
also used to calculate totals for the current control group (if
control fields are specified). Immediately after detail calculation
operations are completed, detail output operations are performed.
The specific steps taken in the program cycle are shown in Figure C-1.
The item numbers in the following description refer to the numbers in
the figure. A program cycle begins with step 3 and continues through
step 25.
1. All data files to be used by the RPG II object program are
opened; that is, they are prepared to be processed by the
object program. Pre-execution time tables and arrays are
loaded before the first program cycle.
2. The object program performs all output conditioned by the 1P
indicator. This output is performed only once per job, and
does not fall within the program cycle (steps 3 through 25).
RPG II CYCLE Page C-5
3. The object program performs all specified heading and detail
output operations whose conditions are satisfied. This
includes specifications that are conditioned by the overflow
indicator if the overflow indicator has been fetched.
4. The object program performs a test to determine if the
overflow line was encountered during detail calculations in
the previous cycle or when heading and detail output was
written in the current cycle. If it was, the overflow
indicators turns on. Otherwise, the indicator turns off,
unless overflow was fetched in step 3.
5. The object program tests the halt indicators. If the halt
indicators are off, the program branches to step 6.
5A. The execution of the program is stopped once for each halt
indicator that is on. The operator can select one of three
options: continue, controlled cancel, or immediate cancel.
See Appendix E for an explanation of operator options.
5B. If the operator desires to continue the job, the program
returns to step 5 to test for other halt indicators. If the
operator selects one of the cancel options, a branch is taken
to step 34.
6. All record identifying indicators and indicators 1P, L1-L9,
an H1-H9 are turned off.
7. The program tests to see if the LR indicator is on. If it
is, the program branches to step 26.
8. The program reads the next input record. At the beginning of
processing, one record from each input file (except forced
files and demand files) is read. If the file has look-ahead
fields, it is read only on the first cycle. After that,
records with look-ahead fields are identified only.
9. The program performs a test to determine of the record is an
end-of-file record. If an end-of-file condition has occured,
the program branches to step 11.
10. If an end of file has not occurred, the program performs a
test to determine if the input records are in the sequence
specified for them on the Input Sheet. If the sequence is
incorrect, the program branches to step 32. The program also
branches to step 32 if non-sequential input records are
specified and the record cannot be identified.
11. If end-of-job conditions have been met, a branch to step 26
is taken. All files for which an E has been specified in
columns 17 of the File Description Sheet must be at end of
file.
RPG II CYCLE Page C-6
12. When multiple input files are used, it is necessary to select
the next record to process. A branch to step 27 is made.
13. If there is only one input file, no record selection is
needed. A test is made to determine if sequence checking has
been requested. If so, a branch is taken to step 30.
14. The record identifying indicator specified for the current
record type turns on. Data from the current record type is
not available for processing until step 24.
15. If the record contains control fields, the object program
preforms a test to determine if a control break has occured (
the contents of the control field are not equal to the
contents of a previously stored field). If a control break
has not occurred or control fields are not specified, the
program branches to step 17.
16. If a control break has occurred, the control level indicator
reflecting this condition is turned on. All lower control
level indicators are also turned on.
17. If this is the first program cycle or first control break,
the program bypasses all total calculation and output
operations and branches to step 20.
18. All calculations conditioned by control level indicators
(columns 7-8 of calculation specifications) are performed and
resulting indicators are turned on or off as speccified. If
the LR indicator is on, calculations conditioned by LR are
done after all other total calculations. Fetch overflow is
performed if it is required by exception output. If the
overflow line has been reached because of exception output,
the overflow indicator is turned on.
19. All total output that is not conditioned by an overflow
indicator is performed. The program performs a test to
determine if an overflow condition has occurred. If an
overflow condition has occurred at any time during this
cycle, the overflow indicator turns on. If the LR indicator
is on, output conditioned by LR is done after other total
output. Fetch overflow is performed if required.
20. The program performs a test to determine is the last record
(LR) indicator is on. If the indicator is on, the program
branches to step 37.
21. The program performs a test to determine if any overflow
indicators are on. If no overflow indicators are on, the
program branches to step 23.
22. All output operations conditioned by a positive (no N
preceding the indicator) overflow indicator are performed.
RPG II CYCLE Page C-7
23. The MR indicator turns on if this is a multifile job and the
record to be processed is a matching record. Otherwise MR
turns off.
24. Field indicators are turned on or off as specified. Data
from the last record read and from specified look-ahead
fields is made available for processing.
25. Any calculations not conditioned by control level indicators
(columns 7-8 of the calculation specifications) are
performed, and resulting indicators are turned on or off as
specified. Fetch overflow is performed if it is required by
exception output. If the overflow line has been reached
because of exception output, the overflow indicator is turned
on. Processing continues with step 3.
26. The last record indicator (LR) and all control level
indicators (L1-L9) are turned on and processing continues
with step 18.
27. If a file has been forced, the next record in that file is
selected for processing and a branch is taken to step 14.
28. If a record with no matching fields is found in a normal
input file which is not at end of file, it is selected.
29. When matching fields are specified, the normal file with the
highest priority matching record field is selected. If two
or more files have the equal and highest priority matching
record fields, the highest priority file of those is
selected. (The primary file has the highest priority, the
first specified secondary file is next, and so forth.)
30. The match field value is compared to the match field value of
the last record. If it is in sequence, the record is
accepted and processing continues with step 14. If the
record is out of sequence, processing goes to step 31.
31. The execution of the program is stopped because a file with
matching fields is out of sequence. The operator's option,
indicated in step 33, is to bypass (read the next record from
the same file) or cancel the job.
32. The execution of the program is stopped because of a record
type sequence error or an unidentified record.
33. Step 33 tests the operator's decision either to bypass the
record which causes the error condition (branch to step 4) or
to cancel the job.
34. If the operator elects to terminate the job by means of a
controlled cancel, steps 35 through 39 are performed. If the
operator selects an immediate cancle, the job is terminated.
RPG II CYCLE Page C-8
35. All operations conditioned by the LR indicator are done.
36. Same as 35.
37. The program writes out any tables or arrays for which a To
Filename is specified on the Extension Sheet.
38. All files used by the program are closed (final termination
functions are done).
39. End of job occurs.
APPENDIX D
CHARACTER SETS
DECsystem-10 RPG II uses the sixbit subset of the ASCII character set
for all internal calculation. While this works fine for most
operations, it presents a problem when using the move and test zone
operations. Because the DECsystem-10 does not normally work with the
EBCDIC character set, nor with 8-bit bytes, the implementation of
these operations is marginal at best.
When a zone operation is encountered, the character that must have its
zone moved/modified/examined is converted to an 8-bit EBCDIC character
from its native SIXBIT. The zone operation is then carried out on
this 8-bit quantity. When all operation have been completed on the
character, it is converted back to SIXBIT. Because the conversion
between character sets (shown in Table D-1) is not always totally
accurate, due to fundamental differences between the different sets,
the zone operations do not always give the same results that they
would under a System/3 RPG II.
It is recommended that the zone operations only be used as an aid in
conversion of existing RPG II programs, and not be used in new ones.
CHARACTER SETS Page D-2
Table D-1 shows ASCII and SIXBIT collating sequence and the
conversions from ASCII to EBCDIC, and SIXBIT to EBCDIC. If the ASCII
character does not convert to the same character in EBCDIC, the EBCDIC
character is shown in parentheses next to the EBCDIC code. Note that
the first and last 32 characters do not exist in SIXBIT. Also,
characters in the first column (NULL, SOH, STX, etc.) are control
characters, which are nonprinting.
Table D-1
ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC
CHARACTER SETS Page D-3
Table D-1 (cont'd)
ASCII and SIXBIT Collating Sequence and Conversion to EBCDIC
CHARACTER SETS Page D-4
Table D-2 shows the conversion of ASCII code to SIXBIT code. The
table does not show ASCII codes 000 through 037 because they all
convert to SIXBIT 74 (\), except 22 (TAB) which converts to SIXBIT 00
(space).
Table D-2
ASCII to SIXBIT Conversion
CHARACTER SETS Page D-5
Table D-2 (cont'd)
ASCII to SIXBIT Conversion
CHARACTER SETS Page D-6
Table D-3 shows the EBCDIC collating sequence and the conversion from
EBCDIC to ASCII. When conversion is from EBCDIC to SIXBIT, it is done
as if the code was converted to ASCII, and then from ASCII to SIXBIT.
Table D-3
EBCDIC Collating Sequence and Conversion to ASCII
CHARACTER SETS Page D-7
Table D-3 (cont'd)
EBCDIC Collating Sequence and Conversion to ASCII
CHARACTER SETS Page D-8
Table D-3 (cont'd)
EBCDIC Collating Sequence and Conversion to ASCII
CHARACTER SETS Page D-9
Table D-3 (cont'd)
EBCDIC Collating Sequence and Conversion to ASCII
APPENDIX E
RPG II HALT PROCEDURES
When an error occurs during the execution of an RPG II program, a halt
procedure is entered. The runtime system (RPGLIB) notifies the user
of this by typing:
%Entered Halt Procedure xx error-text
Please select a halt option:
Where xx is the two character halt code and error-text is a brief
summary of the error. An optional third line tells which file is
affected by the error.
The halt codes have been chosen to be compatible with those given by
IBM System-3 RPG II. In respone to the above message, the user should
enter one of the follwing responses:
CONTINUE Control is returned to the program, and
processing continues.
BYPASS The remainder of the program cycle is
bypassed, and the next record is read.
CONTROLLED CANCEL End-of-job operations (conditioned by an LR
indicator) are done, tables are dumped and
files are closed.
IMMEDIATE CANCEL Files are closed and the job stops.
DEFAULT Use the default operation (see table E-1).
DDT DDT is entered if it was loaded during
compiler generation.
<CR> Same as DEFAULT.
0 Same as CONTINUE.
1 Same as BYPASS.
2 Same as CONTROLLED CANCEL.
RPG II HALT PROCEDURES Page E-2
3 Same as IMMEDIATE CANCEL.
4 Same as DDT
Table E-1
Halt Procedure Definitions
Halt Display Error Description Options Default
H1 Indicator H1 is on 0234 none
H2 Indicator H2 is on 0234 none
H3 Indicator H3 is on 0234 none
H4 Indicator H4 is on 0234 none
H5 Indicator H5 is on 0234 none
H6 Indicator H6 is on 0234 none
H7 Indicator H7 is on 0234 none
H8 Indicator H8 is on 0234 none
H9 Indicator H9 is on 0234 none
11 Square root of a neg- 0234 2
ative number asked
12 Overflow during div- 0234 2
ide
13 Division by zero 0234 2
14 Zero, negative, or 0234 2
invalid array index
15 Table out of sequence 0234 2
16 No table data found 0234 2
17 Too much data for 0234 2
table
1A Exceeded specified 34 3
object core
1E End-of-file on 0234 2
demand file
1F Attempting to ac- 234 2
cess beyond extent
RPG II HALT PROCEDURES Page E-3
Table E-1 (cont'd)
Halt Procedure Definitions
Halt Display Error Description Options Default
1H Attempting to add 0234 2
duplicate key
1P 1P forms allignment 014 none
1U Record not found. 1234 2
Key not in index or
record number too
large.
1Y Invalid response 1234 2
to display
1b Prepare for 034 none
table output
J1 Record out of 1234 2
sequence
L1 File out of match- 1234 2
ing sequence
U1 Unidentified record 1234 2
APPENDIX F
COMMAND STRINGS
The general form of the command string is as follows:
RELFIL,LSTFIL=SRC1,SRC2,...
Table F-1
Explanation of Command String Terms
Term Meaning
RELFIL The file that is to hold the generated code.
If no generated code is desired, the
descriptor for RELFIL is replaced by a hyphen.
Example: -,LSTFIL=SRC1,SRC2...
LSTFIL The file that is to hold the generated
listing. If no listing is desired, the
descriptor for LSTFIL is replaced by a hyphen.
Example: RELFIL,-=SRC1,SRC2,...
SRC1,SRC2 The source files required to from one input
program.
Each file description has the following form:
DEVICE:FILE.TYP[PROJECT,PROGRAMMER]/SWITCH
Certain default assignments are made by the compiler whenever terms
are omitted from the command strings or file descriptions.
1. If the device is omitted in any output file description, DSK
is assumed. If the device is omitted in an input file
description, either the preceding device or DSK (if no
preceding device was specified) is assumed.
2. If the filename for RELFIL and/or LSTFIL is omitted, the
filename of the first source file is used.
COMMAND STRINGS Page F-2
3. If the file type is omitted from RELFIL, .REL is assumed; if
it is omitted from LSTFIL, .LST is assumed. If the type is
omitted from the source file desriptor, the compiler looks in
the file area for the named file with the type .RPG. If that
file is not found, the compiler looks for the named file
without a type.
4. If the [PROJECT,PROGRAMMER] option is omitted on any file,
the users directory is used.
Table F-2
Explanation of File Description Terms
Term Meaning
DEVICE The name of a device. The name is composed of
6 or fewer letters and/or digits.
FILE The name of a file. The name is composed of 6
or fewer letters and/or digits.
TYP The file type (extension). It is composed of
3 or fewer letters and/or digits.
PROJECT A user's project number.
PROGRAMMER A user's programmer number.
SWITCH Any of the switches shown in Table F-3.
Table F-3
RPG II Switch Summary
Switch Action by Compiler
A Allows the listing of the code generated (the
source program is listed whenever a listing
file is specified).
E Checks the program for errors but does not
generate code.
H Types a description of RPG II command strings
and lists the switches. When this switch is
used, the other parts of the command string
are ignored.
N The source errors are not typed on the user's
terminal.
W Rewinds the device before reading or writing.
(This is valid for magnetic tape only.)
APPENDIX G
RPG II STANDARD CALLING SEQUENCE
Subroutines written in FORTRAN or MACRO may be called from an RPG II
program by use of the EXIT and RLABL operations. These operations
generate the standard calling sequence used by FORTRAN, MACRO, and
COBOL programs.
G.1 EXIT OPERATION
The rules for use of the EXIT operation in RPG II calculation
specification are as follows:
Columns Entry
Operation EXIT
Factor 1 Blank
Factor 2 The name of the subroutine to which control is
to be passed.
Result Field Blank
Resulting Indicators Blank
The EXIT operation can be conditioned by control level entries
(columns 7-8) and indicator entries (columns 9-17). If not
conditioned by control level entries, the EXIT operation occurs at
detail calculation time.
G.2 RLABL SPECIFICATION
Through the RLABL operation, a field, table, or array defined in the
RPG II program can be referenced by the subroutine to which the EXIT
operation gives control. The rules for use of RLABL in RPG II
programs are as follows:
RPG II STANDARD CALLING SEQUENCE Page G-2
Columns Entry
Operation RLABL
Result Field Field, table or array name
Field Length Length of field (optional)
Decimal Positions Decimal indication (optional)
The RLABL specifications must immediately follow the EXIT
specifications for the subroutine which references the RPG II field.
A name specified by a TAG, BEGSR, or ENDSR specification cannot be
used in an RLABL specification.
Page Index-1
INDEX
*place . . . . . . . . . . . . . . 10-10
1p . . . . . . . . . . . . . . . . 4-2
Add operation . . . . . . . . . . 9-12, 9-14
Alphabetic characters . . . . . . 1-7
Alphanumeric characters . . . . . 1-7
Alphanumeric fields . . . . . . . 1-7
Arithmetic operations . . . . . . 9-12
Ascii . . . . . . . . . . . . . . 1-7, D-1
Ascii files . . . . . . . . . . . 5-8, 5-16
Begsr operation . . . . . . . . . 9-21
Bitof operation . . . . . . . . . 9-18
Biton operation . . . . . . . . . 9-18
Block length . . . . . . . . . . . 5-7
Blocking factor . . . . . . . . . 5-7
Calculation factors . . . . . . . 9-7
Calculations operations
add . . . . . . . . . . . . . . 9-12, 9-14
begsr . . . . . . . . . . . . . 9-21
bitof . . . . . . . . . . . . . 9-18
biton . . . . . . . . . . . . . 9-18
chain . . . . . . . . . . . . . 5-5, 5-11, 9-29
comp . . . . . . . . . . . . . . 9-13
debug . . . . . . . . . . . . . 4-1, 9-30
div . . . . . . . . . . . . . . 9-12, 9-14, 9-34
dsply . . . . . . . . . . . . . 5-3, 9-28
endsr . . . . . . . . . . . . . 9-21
excpt . . . . . . . . . . . . . 9-27
exit . . . . . . . . . . . . . . 9-21, G-1
exsr . . . . . . . . . . . . . . 9-20
force . . . . . . . . . . . . . 9-27
goto . . . . . . . . . . . . . . 9-20
lokup . . . . . . . . . . . . . 9-22, 9-24
mhhzo . . . . . . . . . . . . . 9-13
mhlzo . . . . . . . . . . . . . 9-13
mlhzo . . . . . . . . . . . . . 9-13
mllzo . . . . . . . . . . . . . 9-13
move . . . . . . . . . . . . . . 9-12, 9-16
movea . . . . . . . . . . . . . 9-12, 9-16
movel . . . . . . . . . . . . . 9-12, 9-16
mult . . . . . . . . . . . . . . 9-12, 9-14
mvr . . . . . . . . . . . . . . 9-12, 9-14, 9-34
read . . . . . . . . . . . . . . 5-6, 9-28
rlabl . . . . . . . . . . . . . 9-21, G-1
setof . . . . . . . . . . . . . 8-9, 9-22
seton . . . . . . . . . . . . . 9-3, 9-21
sqrt . . . . . . . . . . . . . . 9-12, 9-14
sub . . . . . . . . . . . . . . 9-12, 9-14
tag . . . . . . . . . . . . . . 9-20
testb . . . . . . . . . . . . . 9-18
testz . . . . . . . . . . . . . 9-19
time . . . . . . . . . . . . . . 9-32
xfoot . . . . . . . . . . . . . 9-15
z-add . . . . . . . . . . . . . 9-12, 9-14
z-sub . . . . . . . . . . . . . 9-12, 9-14
Chain operation . . . . . . . . . 5-5, 5-11, 9-29
Character sets . . . . . . . . . . D-1
Character zones . . . . . . . . . D-1
Command strings . . . . . . . . . F-1
Comp operation . . . . . . . . . . 9-13
Compilation time . . . . . . . . . 1-7
Console . . . . . . . . . . . . . 5-3
Continuation lines . . . . . . . . 5-16
Control levels . . . . . . . . . . 9-3
Control specifications . . . . . . 4-1
Date field names . . . . . . . . . 9-9
Debug operation . . . . . . . . . 4-1
Demand files . . . . . . . . . . . 9-28
Detail time . . . . . . . . . . . 1-8
Device code . . . . . . . . . . . 5-14
Direct load . . . . . . . . . . . 5-4, 9-29
Div operation . . . . . . . . . . 9-12, 9-14
Dsply operation . . . . . . . . . 5-3, 9-28
Ebcdic . . . . . . . . . . . . . . 1-8, D-1
Edit codes . . . . . . . . . . . . 10-11
End of file processing . . . . . . 5-6
Endsr operation . . . . . . . . . 9-21
Entries per record . . . . . . . . 6-3
Excpt operation . . . . . . . . . 9-27
Execution time . . . . . . . . . . 1-8
Exit operation . . . . . . . . . . 9-21, G-1
Exsr operation . . . . . . . . . . 9-20
Extension code . . . . . . . . . . 5-13
Extensions . . . . . . . . . . . . 5-15, A-7
Fetch overflow . . . . . . . . . . 10-4
Field indicators . . . . . . . . . 8-13
Field record relation . . . . . . 8-11
Field type
alphanumeric . . . . . . . . . . 1-7
numeric . . . . . . . . . . . . 1-8
File description . . . . . . . . . 5-1
File designation
chained . . . . . . . . . . . . 5-5
demand . . . . . . . . . . . . . 5-6
primary . . . . . . . . . . . . 5-4
record address . . . . . . . . . 5-5
secondary . . . . . . . . . . . 5-4
table or array . . . . . . . . . 5-5
File format . . . . . . . . . . . 5-7
File organization . . . . . . . . 5-12
File processing
direct . . . . . . . . . . . . . 12-13
indexed . . . . . . . . . . . . 12-13
sequential . . . . . . . . . . . 12-1
File type
combined . . . . . . . . . . . . 5-3
display . . . . . . . . . . . . 5-3
input . . . . . . . . . . . . . 5-2
output . . . . . . . . . . . . . 5-2
update . . . . . . . . . . . . . 5-3
Filename extensions . . . . . . . 5-15, A-7
Force operation . . . . . . . . . 9-27
Form length . . . . . . . . . . . 7-2
Forms positioning . . . . . . . . 4-2
From filename . . . . . . . . . . 6-1
Goto operation . . . . . . . . . . 9-20
H card . . . . . . . . . . . . . . 4-1
Half-adjust . . . . . . . . . . . 9-34
Halt procedures . . . . . . . . . E-1
Indicators
control level . . . . . . . . . 8-9, 8-11, 9-3 to 9-4, 9-21
external . . . . . . . . . . . . 8-11, 9-4
field . . . . . . . . . . . . . 8-13
halt . . . . . . . . . . . . . . 8-11, 8-13, 9-4, 9-21
last record . . . . . . . . . . 9-4, 9-21
matching record . . . . . . . . 8-10 to 8-11, 9-4, 12-3
mr . . . . . . . . . . . . . . . 8-10 to 8-11
output . . . . . . . . . . . . . 10-8
overflow . . . . . . . . . . . . 9-4
record identifying . . . . . . . 8-3, 8-5, 8-11, 8-13, 9-4,
9-22
resulting . . . . . . . . . . . 9-4, 9-34
Isam processing . . . . . . . . . 12-13
Key field . . . . . . . . . . . . 5-11, 5-13
Lines per page . . . . . . . . . . 7-1
default . . . . . . . . . . . . 7-1
Lokup operation . . . . . . . . . 9-22, 9-24
Look-ahead fields . . . . . . . . 8-3 to 8-4, 12-8
Matching fields . . . . . . . . . 8-10
Matching records . . . . . . . . . 12-2
Mfcu . . . . . . . . . . . . . . . 5-3
Mhhzo operation . . . . . . . . . 9-13
Mhlzo operation . . . . . . . . . 9-13
Mlhzo operation . . . . . . . . . 9-13
Mllzo operation . . . . . . . . . 9-13
Mode of processing
by addrout . . . . . . . . . . . 5-10
consecutive . . . . . . . . . . 5-10
random . . . . . . . . . . . . . 5-11
sequential by key . . . . . . . 5-10
Move operation . . . . . . . . . . 9-12, 9-16
Movea operation . . . . . . . . . 9-12, 9-16
Movel operation . . . . . . . . . 9-12, 9-16
Mult operation . . . . . . . . . . 9-12, 9-14
Multi-file processing . . . . . . 5-4, 5-6, 9-27, 12-2
Mvr operation . . . . . . . . . . 9-12, 9-14
Numeric characters . . . . . . . . 1-8
Numeric field . . . . . . . . . . 1-8
Overflow indicator . . . . . . . . 5-12
Overflow line . . . . . . . . . . 7-2
default . . . . . . . . . . . . 7-1
Overflow line number . . . . . . . 7-2
Pre-execution time . . . . . . . . 1-8
Program identification . . . . . . 3-3
Random files . . . . . . . . . . . 9-29
Read operation . . . . . . . . . . 5-6, 9-28
Record address field . . . . . . . 5-11
Record address type . . . . . . . 5-11
Record key . . . . . . . . . . . . 1-8
Record length . . . . . . . . . . 5-8
Result field . . . . . . . . . . . 9-32
Rlabl operation . . . . . . . . . 9-21, G-1
Sequence checking . . . . . . . . 5-7
Setof operation . . . . . . . . . 8-9, 9-22
Seton operation . . . . . . . . . 9-3, 9-21
Single file processing . . . . . . 5-6
Sixbit . . . . . . . . . . . . . . D-1
Special characters . . . . . . . . 1-8
Special words
page . . . . . . . . . . . . . . 8-9, 9-7, 9-10, 10-10
page1 . . . . . . . . . . . . . 8-9, 9-7, 9-10, 10-10
page2 . . . . . . . . . . . . . 8-9, 9-7, 9-10, 10-10
udate . . . . . . . . . . . . . 9-7, 9-9, 10-11
uday . . . . . . . . . . . . . . 9-7, 9-9, 10-11
umonth . . . . . . . . . . . . . 9-7, 9-9, 10-11
uyear . . . . . . . . . . . . . 9-7, 9-9, 10-11
Sqrt operation . . . . . . . . . . 9-12, 9-14
Sub operation . . . . . . . . . . 9-12, 9-14
Subroutines . . . . . . . . . . . 9-3
Tables and arrays . . . . . . . . 11-1
advantages . . . . . . . . . . . 11-1
alternate . . . . . . . . . . . 6-7
compile time . . . . . . . . . . 11-5
execution time . . . . . . . . . 11-6
files . . . . . . . . . . . . . 5-5
forming . . . . . . . . . . . . 11-5
full . . . . . . . . . . . . . . 11-5
naming . . . . . . . . . . . . . 11-1
output . . . . . . . . . . . . . 5-5
pre-execution time . . . . . . . 11-6
sequence . . . . . . . . . . . . 6-6
short . . . . . . . . . . . . . 11-5
Tag operation . . . . . . . . . . 9-20
Tape rewind . . . . . . . . . . . 5-17
Testb operation . . . . . . . . . 9-18
Testz operation . . . . . . . . . 9-19
Time operation . . . . . . . . . . 9-32
To filename . . . . . . . . . . . 6-2
Total time . . . . . . . . . . . . 1-8
Xfoot operation . . . . . . . . . 9-15
Z-add operation . . . . . . . . . 9-12, 9-14
Z-sub operation . . . . . . . . . 9-12, 9-14