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:
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:
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).
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.
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 |
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 |
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 |
This page was last updated on January 30, 2015.