RPG Tutorial: Example Program 4 - Update ISAM file from tape (chaining)

  1  H
  2  H*
  4  H*
  5  FCOURSES IPE F6300  63           ETAPE         S
  6  FSTMASTR UC  F 250 250R 7KI     2 DISK14       S
  7  FREPORT  O   F 132 132     OF    LPRINTER
  9  LREPORT    101 6012
  10 ICOURSES AA  01
  11 I                                        1   7 IDENT   C1
  12 I                                        9  14 CN1
  13 I                                        9  140CN1N            11
  14 I                                       16  21 CN2
  15 I                                       16  210CN2N            12
  16 I                                       23  28 CN3
  17 I                                       23  280CN3N            13
  18 I                                       30  35 CN4
  19 I                                       30  350CN4N            14
  20 I                                       37  42 CN5
  21 I                                       37  420CN5N            15
  22 I                                       44  49 CN6
  23 I                                       44  490CN6N            16
  24 I                                       51  56 CN7
  25 I                                       51  560CN7N            17
  26 I                                       58  63 CN8
  27 I                                       58  630CN8N            18
  28 ISTMASTR BB  02   
  29 I                                        9  43 NAME
  30 C*
  36 C*
  37 C   01N02 H0          SETOF                     H0
  38 C*
  40 C*
  41 C   01      CCOUNT    ADD  1         CCOUNT  30
  42 C   01 02   UCOUNT    ADD  1         UCOUNT  30
  43 OSTMASTR D        01 02
  44 O                         CN8      204
  45 O                         CN7      195
  46 O                         CN6      186
  47 O                         CN5      177
  48 O                         CN4      168
  49 O                         CN3      159
  50 O                         CN2      150
  51 O                         CN1      141
  52 OREPORT  H  201   1P
  53 O       OR        OF
  54 O                                   45 'STUDENT MASTER'
  55 O                                   30 'COURSES TO'
  56 O                                   19 'POST REGISTERED'
  57 O        D  1     01
  58 O                N14      CN4N      87 '0  -   - '
  59 O                N13      CN3N      77 '0  -   - '
  60 O                N12      CN2N      67 '0  -   - '
  61 O                N11      CN1N      57 '0  -   - '
  62 O                 02      NAME      47
  63 O                N02                38 'MASTER ***'
  64 O                N02                27 '*** NO MATCHING'
  65 O                         IDENT     11 
  66 O        D  2     01
  67 O                N18      CN8N      87 '0  -   - '
  68 O                N17      CN7N      77 '0  -   - '
  69 O                N16      CN6N      67 '0  -   - '
  70 O                N15      CN5N      57 '0  -   - '
  71 O        T 31     LR
  72 O                         CCOUNTZ    7
  73 O                                   27 'COURSE REGISTRATION'
  74 O                                   40 'RECORDS READ'
  75 O        T  1     LR
  76 O                         UCOUNTZ    7
  77 O                                   22 'STUDENT MASTER'
  78 O                                   38 'RECORDS UPDATED'

Statements 5-7 are the File Description Specifications for the maintenance input (COURSES), the ISAM update (STMASTR),  and a report output (REPORT) files.  Notice that the maintenance input is on a tape file and each input block contains 100 records.  The primary input file, containing the maintenance transactions, is to be chained to the Indexed Sequential file to be updated.  The new entries in the File Description specifications required are the E in column 39 of the primary file (the chaining file), designating that a File Extension specification will be provided for this file, and an R in column 28 of the update file (the chained file), designating that the records will be accessed randomly.

Statement 8 is the File Extension specification which provides the additional information to link the primary input file (COURSES) and the update ISAM file (STMASTR) in a chaining->chained relationship.  Columns 7-8 contain the record sequence from columns 15-16 of the chaining file (AA).  Columns 9-10 contain the number of the chaining field from columns 61-70 of the Input Specification where the input field is defined (C1).  Columns 11-18 contain the name of the "chained from" file (COURSES) and columns 19-26 contain the name of the "chained to" file (STMASTR).  This establishes a relationship between the two files.  For each record read from COURSES, the RPG compiler will generate the instructions to attempt to randomly retrieve a record from STMASTR using the student identification number in columns 1-7 of the COURSES input record.

Statement 10 defines the input record expected to be read from COURSES.  No identifying characters are specified since all records read are expected to be the single record format defined here.  Indicator 01 will always be turned on when a record is read from this file.

Statements 11-27 define the fields in the COURSES record.  Notice that each course number is defined twice, once as an alphanumeric field and again as a numeric field.  On the specifications for the course number fields defined as numeric fields, the Field Indicator Zero/Blank (columns 69-70) is coded to turn on indicators 11 through 18 if the corresponding course number field is zero.  These indicators will be used during output.

Statements 28-29 define the record and single field to be read from the student master ISAM file (STMASTR).  This is a minimal definition, and does not take into consideration that a transaction might be included for a student master record flagged for deletion (position one equal to 'D').  In a production program, it would be necessary to code for this possibility, both here in the Input Specifications and elsewhere in the program.

The Calculation Specifications have been kept to a minimum since this program is intended primarily to illustrate chaining.  Statement 37 is required to prevent the program from abnormally terminating if a transaction is included for a master record which is not present (a condition that I have simulated with the test data).  H0 is always set on automatically when no record is available to read during a chaining operation.  So, I have conditioned a SETOF operation for H0 if indicator 01 is on (a COURSES record has been read), indicator 02 is off (no corresponding STMASTR record has been read), and H0 is on.

Statements  41-42 simply maintain some counters to be printed on the report.  The first, conditioned by indicator 01, counts the number of transactions read.  The second, conditioned by both indicator 01 and indicator 02, counts the number of student master records which will be updated.

Statement 43 defines the conditions under which fields are to be written to the student master record.  If indicators 01 and 02 are both on, a transaction record has been read (01 on) and the corresponding student master has been read (02 on).  It is imperative in a program similar to this that you make certain that the program has read the correct master record before performing any output, otherwise fields could be updated in the wrong record.

Statements 44-51 specify the data fields to write to the student master record.  These are the course numbers read from the COURSES record.

The remainder of the program produces the output report and I have utilized some more advanced coding than in earlier example programs to show how a lot of information can be produced by sharing specifications.  Statements 57 and 66 define the conditions under which two detail lines will be produced - when indicator 01 is on.  So, for each COURSES record read, two detail lines will be produced.  For the first line (statements 58-61) I have used the Field Indicators set on the Input Specifications to suppress printing of any course numbers which contained zeros.  The course numbers one through four will only be printed if the corresponding indicators 11 through 14 are not on.  I have used the field names for the course numbers that provide numeric definitions so that I could utilize an edit word to insert hyphens (-) to make the course number more readable.  (The first two digits are the department number; digits three through five are the course number; and the last digit is the section number.) 

In statements 62-64 I have utilized indicator 02 (on if a STMASTR record was read and updated and not on if a STMASTR record was not read) to print either the student's name if the student master was read or an error message if the student master was not found.

Statements 67-70 are used to print the last four course numbers on the second detail line in the same manner as the first four course numbers were printed on the first detail line.

The compiler listing and the output report are available for viewing here:  Example 4 SYSOUT.

The jobstream, complete with JCL and RPG source are available for download here:  Example 4 jobstream.  The primary input file is in an AWS Tape image file - jay802.aws - included in the archive with the jobstream.  You will need to ensure that the volume serial number where the ISAM dataset created in Example 3 is correct for your MVT system before running the jobstream.  Note:  There are two jobstreams in this archive, one is for MVS and the other is for MVT.  The difference is that the MVS jobstream uses the ISAM-VSAM interface to access an VSAM cluster instead of creating a native ISAM dataset.

This program and the previous (Example 3) re-acquainted me with a bug in the RPG compiler that I last dealt with in 1974.  As I recall, we never fixed the bug then, we just worked around it.  The bug is this:  if you attempt to randomly retrieve records from an ISAM file loaded by an RPG program, when an attempt is made to read a record using a key that does not exist in the file, the system will hang, forcing the job to be cancelled by the operator.  I got past this with my example programs the same way we did back in 1974 - I wrote a COBOL program to re-organize the file.  Actually a pair of programs, one to read the file sequentially copying all the records with "A" in position one to a sequential file and a second to read the sequential file and reload the ISAM file.  Not a great deal of trouble in a production environment since you need this type of reorganization process anyway, but an annoyance with what should have been a couple of simple example programs.  This bug does not seem to manifest itself when I run the programs under MVS using the ISAM-VSAM interface to access the student data contained in a VSAM cluster instead of a native ISAM dataset.

Return to Site Home Page 

This page was last updated on January 17, 2015.