Using Relative Record Number with data files in RPG

Lately I have received a lot of emails and messages about using Relative Record Numbers, RRN, with data files in RPG programs. So many I have decided to write this post so I can refer people here rather than answer their questions individually.

Before I get started I just want to say I can think of no good business reason to use RRN to get and manipulate records from Physical or Logical files. The best I can recall the last time I wrote a program using them was way back in time in the late 1980s on an IBM System/36, one of the ancestors of the AS400 and IBM i. If someone asked me today to write a program using RRN I would ask them "Why?" and need a very good reason why.

The Relative Record Number identifies which position in a file the record is in. If, for example, a record has the RRN of 10 there does not have to be nine records before it. When a record is deleted its space in the file is retained, and it is not "freed" until the file is reorganized using the RGZPFM command, or if the file is set to reuse deleted records a new record is added to the file.

To illustrate my examples I created a very simple file:

A R TESTFILER A FLD001 1A A K FLD001

Into which I entered the letters of the first row of letters on my keyboard:

FLD001 01 Q 02 W 03 E 04 R 05 T 06 Y 07 U 08 I 09 O 10 P

To be able to use the RRN I need to use the RECNO keyword in the file definition/specification, which contains a numeric field for the number of the record:

dcl-f TESTFILE disk recno(RRN) ; dcl-s RRN packed(10) ; FFilename++IPEASF.....L.....A.Device+.Keywords+++++ TESTFILE IF E DISK recno(RRN) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++ D RRN S 10 0

Let me start with a simple program to read and display the RRN of the records in the file. My program looks like this:

01 dcl-f TESTFILE disk recno(RRN) ; 02 dcl-s RRN packed(10) ; 03 dow (1 = 1) ; 04 read TESTFILER ; 05 if (%eof) ; 06 leave ; 07 endif ; 08 dsply ('Key = ' + FLD001 + ' - ' + %char(RRN)) ; 09 enddo ; 10 *inlr = *on ;

The output displayed by the Display Message operation, DSPLY, looks like:

DSPLY Key = Q - 1 DSPLY Key = W - 2 DSPLY Key = E - 3 DSPLY Key = R - 4 DSPLY Key = T - 5 DSPLY Key = Y - 6 DSPLY Key = U - 7 DSPLY Key = I - 8 DSPLY Key = O - 9 DSPLY Key = P - 10

I can also Chain to the file to retrieve a specific record, for example the seventh:

01 chain 7 TESTFILE ; 02 if (%found) ; 03 dsply (FLD001 + ' - ' + %char(RRN)) ; 04 endif ;

Which gives me:

DSPLY Key = U - 7

I can easily delete the seventh record:

01 dcl-f TESTFILE disk recno(RRN) usage(*input:*delete) ; 02 dcl-s RRN packed(10) ; 03 chain 7 TESTFILER ; 04 if (%found) ; 05 delete TESTFILER ; 06 endif ; 07 *inlr = *on ;

For those of you unfamiliar with the USAGE(*INPUT:*DELETE) part of the file definition you should read my post File definition in RPG all free.

Now when I run the program to list all of the records with their RRN the seventh record is missing:

DSPLY Key = Y - 6 DSPLY Key = I - 8

The seventh record is not really missing it is just flagged as deleted.

I can also change a record using the RRN. In the example below I am going to replace the value in the fifth record with 'A':

01 RRN = 5 ; 02 chain RRN TESTFILER ; 03 FLD001 = 'A' ; 04 update TESTFILER ;

DSPLY Key = A – 5

My file only contains ten records, you would think if I wanted to add another record I could just do:

01 dcl-f TESTFILE disk recno(RRN) usage(*output) ; 02 dcl-s RRN packed(10) ; 03 RRN = 11 ; 04 FLD001 = 'A' ; 05 write TESTFILER ; 06 *inlr = *on ;

When I run the above program I get an error message:

I/O error CPF5006 was detected in file TESTFILE (C G D F).

It will not allow me to add the eleventh record. What I need to do is add records to the file outside of the program. Fortunately there is a CL command to do this: Initialize Physical Member, INZPFM. If there is already data in the file it will add new records to the file:

INZPFM FILE(MYLIB/TESTFILE) RECORDS(*DLT) TOTRCDS(20)

As I already have 10 records in the file and I want to add 10 more the total records parameter needs to be 20 (= 10 existing + 10 new). There is a default value for this parameter of *NXTINCR, to increase the file size by one increment, but as I always create my files with a size of *NOMAX the default is not allowed.

The RECORDS parameters allows me to say do I want to add blank records, RECORDS(*DFT), or deleted ones , RECORDS(*DLT). As both blank and deleted records take up space there is no size advantage to using either. I just prefer to add deleted records as I can then write new records to the file when needed. With blank records I now have 20 active records, my original ten and ten blank ones.

When I run the INZPFM I will receive a message informing of the number of new records added.

Message ID . . . . . . : CPC3102 Severity . . . . . . . : 00 Message type . . . . . : Information Message . . . . : Member TESTFILE initialized with 10 records. Cause . . . . . : Member TESTFILE file TESTFILE in library MYLIB was initialized with 10 records.

Now I can a new record to my file, and I don't have to write it to the 11th record. I am going to write it to the 17th.

01 dcl-f TESTFILE disk recno(RRN) usage(*output) ; 02 dcl-s RRN packed(10) ; 03 RRN = 17 ; 04 FLD001 = 'V' ; 05 write TESTFILER ; 06 *inlr = *on ;

When I run the program to display all the records I can see my new record with the RRN of 17:

DSPLY Key = Q - 1 DSPLY Key = W - 2 DSPLY Key = E - 3 DSPLY Key = R - 4 DSPLY Key = T - 5 DSPLY Key = Y - 6 DSPLY Key = U - 7 DSPLY Key = I - 8 DSPLY Key = O - 9 DSPLY Key = P - 10 DSPLY Key = V - 17

I just want to state a few things, which in my opinion should be self evident, but I am doing here just for the record:

1. I cannot use zero for RRN.
2. I cannot have two or more records with the same RRN.

 

How about you just want to see the RRN of the records read without all of malarkey described above. I can use an Information Data Structure, INFDS, with the file.

01 dcl-f TESTFILE disk keyed infds(FileDs) ; 02 dcl-ds FileDs qualified ; 03 RRN uns(10) pos(397) ; 04 end-ds ; 05 dow (1 = 1) ; 06 read TESTFILER ; 07 if (%eof) ; 08 leave ; 09 endif ; 10 dsply ('Key = ' + FLD001 + ' - ' + %char(FileDs.RRN)) ; 11 enddo ; 12 *inlr = *on ;

The INFDS is defined with the file, line 1, and I have given it the totally unimaginative name of "FileDs". The data structure contains a whole lot of information, but I am only interested in the RRN. The RRN is a ten long unsigned integer variable that starts at position 397, line 3. I have chosen to qualify my data structure subfields, see line 2.

Notice that I have defined the file as KEYED, therefore, when I read the file I am reading it in keyed order rather than by RRN.

Now I can read my file, line 6, and display the value of my key field along with the RRN, line 10.

The output shows the fields in key order with their RRN.

DSPLY Key = E - 3 DSPLY Key = I - 8 DSPLY Key = O - 9 DSPLY Key = P - 10 DSPLY Key = Q - 1 DSPLY Key = R - 4 DSPLY Key = T - 5 DSPLY Key = U - 7 DSPLY Key = W - 2 DSPLY Key = Y - 6

The equivalent definitions using fixed format would be:

FFilename++IPEASF.....L.....A.Device+.Keywords++++++ 01 FTESTFILE IF E K DISK infds(FileDS) DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+ 02 D FileDs DS qualified 03 D RRN 397 400U 0

 

You can learn more about on the IBM website:

• RPG file definition keyword RECNO
• CL command INZPFM

 

This article was written for IBM i 7.2, and should work for earlier releases too.