RPG Tutorial: Basic statement types (Header/File/Input/Output)

RPG source statements consist of a relatively small set of rigidly formatted specification statements.  Because RPG programs can be complex, and deal with complex collections of data, the formats of the specifications can, at first glance, seem overwhelming.  However, the specifications are designed to be able to handle a large range of needs, so in actual practice any individual program will only require entries to be made in a small number of the fields. 

Since I am intending for this to be an introductory tutorial, I have not covered every entry possible in every specification field.  For example, I have not covered combined reader/punch files since it is unlikely that under Hercules/MVT anyone will be dealing with physical card devices.  If you come to the end of the material I have presented here and find that you have needs beyond what I have covered, try the nearest university library.  You will be amazed at the books that are tucked away in some of the stacks gathering dust.

Although the number of specifications has been increased with the later extensions (RPG II, RPG III, and RPG IV), the RPG Debugging Template I acquired back in 1973 (I still have two well-worn copies) defines only ten types of specification.  Of those ten, a simple program may be written using only four:

  1. Header
  2. File Description
  3. Input
  4. Output

Update 01/30/2015:  Wally Schwarz sent me PDFs containing scans of the forms for the File Description, Input Specifications, Calculation Specifications, and Output-Format Specifications which can be printed and used to code the specifications for an RPG program.

Columns one through five of any specification statement are traditionally used for sequence numbers, with the first two digits typically containing the coding sheet page number and the last three digits containing the statement number within that page.  Like all other languages, once we started moving away from physical cards, the sequence numbers lost some of their utility and were omitted most of the time.  The default behavior of the MVT RPG compiler is to not sequence check the source, so you may leave the first five columns of each statement blank.

Column six of the specification statement designates the type - H for Header, F for File Description, I for Input, and O for Output.  The order the specification statements must occur in when processed by the compiler is:

  1. Header
  2. File Description
  3. Extension
  4. Line Counter
  5. Input
  6. Calculation
  7. Output

All specifications of an individual type are processed together.  So, there should be a single Header specification, followed by one or more File description specifications, and so on through the Output specifications.

Column seven of any specification statement may contain an asterisk (*) to designate a comment.  The contents of the card will be printed on the compiler listing and otherwise ignored.  However, the specification type (column six) must be correct and in the correct order (as shown above).  

Header Specification

The Header specification statement provides the overall characteristics of the program and its operating environment.  Most of the fields had much more significance on the earlier (smaller) IBM 360 series mainframes or on the later System/3 (and other minicomputers) than they do for RPG programs written to run under OS/360.  I do remember using some of the fields when I was writing programs on a System/3, but 99% of the time all entries are left blank.  However, the presence of the Header specification is mandatory, so you must include the card with an 'H' in column six.

The only significant entry for RPG I is the program name, which may be entered in columns 75-80.  If provided, this will be the name used for the object program (the name of the CSECT, or control section).  If omitted, the name of the program will be the default: RPGOBJ.

File Description Specification

The File Description specification statement provides the characteristics of the files to be read and/or written by the program.  No file will use every entry in the file specification and only an indexed sequential (ISAM) disk file will use a significant number of entries.

Column(s) Field Name Use
7 - 14 File Name name of file used internally and in JCL (DD name)
15 File Type I = input, O = output, U = update
16 File Designation P = primary, S = secondary, C = chained, 
R = record address, T = table
17 End of File enter E for each input file to be checked to determine when the last record has been read and processed (LR indicator)
18 Sequence A = ascending, D = descending (required for Matching Records otherwise leave blank)
19 File format F = fixed or V = variable
20 - 23 Block Length enter block size for fixed blocked, enter record size for fixed unblocked, enter largest record size for variable
24 - 27 Record Length enter record size for fixed, enter largest record size for variable
28 Mode of Processing blank = sequential, L = segment (limits), R = random
29 - 30 Length of Record Address or Length of Key Field if the file is a Record Address File file, enter the number of positions that each entry in the file occupies; if the file is an Indexed-Sequential file, enter the length of the record key
31 Record Address Type K = records retrieved using record keys 
32 Type of File Organization or
Dual I/O Areas
blank = sequential, I = indexed sequential
33 - 34 Overflow Indicator Overflow indicator (OF, OA, OB, OC, OD, OE, OG, or OV ) to use for this file
35 - 38 Key field starting location
39 Extension or Line Counter specifications E = extension specifications provided for this file, L = line counter specifications provided for this file
40 - 46 Device READ40 = card reader, PRINTER, TAPE, DISK14
47 - 52 Symbolic Device leave blank for MVT/MVS
53 Labels blank = no labels, S = standard, E = standard plus user
66 File Addition or Unordered A = new records are to be added to indexed sequential file
71 - 72 File Condition U1, U2, ... U8 external switches conditioning optional file

Input Specification

The Input specification statement provides characteristics of input records and defines the individual data fields associated with each input record.  A great deal of program logic may be specified with the input specification, such as control fields, matching multiple inputs on a common field (such as account number), automatically using a key value in one file to read the corresponding record in a secondary file, and setting indicators depending upon the presence of data in specified fields.

Using the input specification is done a bit differently from the file specification.  One or more specification statements are used to first define characteristics of the record in order to allow the program to identify the record uniquely.  Following these specification statements are one or more statements which define the data fields which are to be processed from the input record.  

To clearly differentiate these functions, I have divided the fields of the input specification into two groups.  These fields define record characteristics and provide the means to uniquely identify each discrete record type:

 Column(s) Field Name Use
7 - 14 File Name name of file used internally and in JCL (DD name)
14 - 16 OR/AND used when specifying more than 3 record identifiers or for specifying alternate indicators to be turned on for identical record formats
15 - 16 Sequence used to specify sequence checking on record groups - enter number, beginning with 01, for each record type - enter any 2 alphabetic characters for unsequenced input record groups
17 Number used in conjunction with sequence, enter 1 to indicate only one instance of a specific record type should occur in a group; enter N to indicate one or more instances may be present
18 Option used in conjunction with sequence, enter O if a specific record need not be present in a group; leave blank if an instance is required to be present
19 - 20  Record Indicator enter the indicator (01 - 99) to be set on when this record is read
21 - 24
28 - 31
34 - 38
Position in record where identifying character(s) located  
25
32
39
Negates comparison the code described must not be present in the position specified
26
33
40
Comparison Type C = character, Z = zone, D = decimal
27
34
41
Literal to Match if comparison type is C, enter any EBCDIC character; if comparison type is Z, enter & or A-I to check for 12-zone, enter - or J-R to check for 11-zone, S-Z to check for 0-zone, blank or 0-9 to check for the absence of zones
42 Stacker Select  

These fields define individual data fields in the input records, along with identifying control level, matching, and other special characteristics of data fields:

 Column(s) Field Name Use
43 Packed  enter P if field is in packed decimal format
44 - 47 Field Begins enter record position containing first position of field
48 - 51 Field Ends enter record position containing last position of field
52 Decimal Positions for numeric fields, enter the number of decimal positions (0-9)
53 - 58 Field Name  
59 - 60 Control Level L1, L2, ... L9
61 - 62 Matching Fields or 
Chaining Fields
M1, M2, M3
C1, C2, ... C9
63 - 64 Field/Record Relation enter the record indicator to relate identically named fields contained in different positions within a group of records
65 - 66 Positive

for numeric fields, enter indicator to turn on if the field contains a positive value when read

67 - 68 Negative for numeric fields, enter indicator to turn on if the field contains a negative value when read
69 - 70 Zero or Blank for numeric fields, enter indicator to turn on if the field contains zero when read; for alphabetic fields, enter indicator to turn on if the field contains blanks when read

Output Specification

The Output specification statement provides characteristics of output records and defines the individual data fields or constants to be written for a particular output (or updated) record.  

Like the input specification, the output specification is used to provide two separate, but related, types of information.  First, one or more specification statements are used to define the conditions under which an output record is produced.  Following these specification statements are one or more statements which define the data fields or literals to be written to the output record.

To clearly differentiate these functions, I have divided the fields of the output specification into two groups.  These fields define when an output record is written:

 Column(s) Field Name Use
7 - 14 File name name of file used internally and in JCL (DD name)
14 - 16 AND/OR used when specifying more than 3 record indicators
15 H = heading
D = detail
T = total
specifies the time in the RPG logic cycle when this output is to occur - note that for all practical purposes, Heading and Detail time are the same
16 - 18 ADD to add records to an ISAM file
17 Space Before enter 0-3 to specify number of lines to space before printing
18 Space After enter 0-3 to specify number of lines to space after printing
19 - 20 Skip Before enter 01-12 to specify channel to skip to before printing
21 - 22 Skip After enter 01-12 to specify channel to skip to after printing
23
26
29
Negates indicator enter N to specify that the associated indicator must not be on as a condition of this output operation
24 - 25
27 - 28
30 - 31
Indicator enter the indicator to be used to condition this output operation

These fields define individual data fields or literal values to be placed in the output record:

 Column(s) Field Name Use
32 - 37 Field Name enter field to be written to output
38 Edit Code enter edit code or leave blank to use edit constant word
39 Blank After reset source data field contents to blank or zero after field is moved to the output record
40 - 43 End Position enter position in output record to contain right-most character of output field
44 Packed  enter P if output is to be written in packed decimal format
45 - 70  Constant or
Edit Word
enter literal constant or edit word enclosed in apostrophes



Return to Site Home Page 


This page was last updated on January 30, 2015.