Midrange Programmer

Wow! I was blown away by the responses from my last article, "Back to Basics: Introduction to Subfiles." It seems the RPG community is still extremely hungry for subfile information. So much so that I am going to write another article about subfile use. In this article, I will discuss the different types of subfiles and when to use each. For those of you still waiting for the continuation of my Java series, be patient; I will get back to it next month.

The program you viewed in the last article was a load-all subfile. This means that all the records are loaded to the subfile at one time, before the subfile is displayed. What makes this program a load-all subfile is that you let OS/400 handle the paging for you and you load to the maximum number of records allowed (SFLSIZ in DDS) at one time. Notice in your RPG you have no code to page up or down through your subfile. You have only one routine that loads all the data from your data file, until either the end-of-file is reached or the maximum number of records allowed in your subfile (500, in that example) is reached.

This type of subfile is very easy to code and can allow you to get a working application up and running rather quickly. It is great if you are certain about the number of records you want to display. Since OS/400 handles the paging for you, you can just load and display. The user can page through the data, and you don't even code for it in your RPG.

Ah, but as it is with everything that seems too good to be true, it probably is. The problem with load-all subfiles comes when the amount of data increases. What if, in my last example, it turned out that there were more that 500 records to be loaded? The program would not blow up; we've coded for that in the DOW loop. But the data would not show up. Okay, I could modify the DDS and change the SFLIZ keyword as high as 9999, then go into the RPG program and change the subfile_size constant to match the SFLSIZ keyword. Now all the data would be loaded, as long as the number of records doesn't exceed 9999. But what about the poor user who has to scroll through pages of data to find what he is looking for?

That's another potential problem with the load-all subfile program and OS/400 controlled paging. The user might have to page through several pages to get to the data he wants. This can be time consuming, especially if the data is closer to the bottom of the list. You have to be careful when using the load-all technique. You must balance between how many records you want to display and how many potential pages you want the user to page through to get to the desired information. That's where self-extending subfiles come in.

The self-extending subfile works the same as a load-all subfile, in that you still cannot load more than 9999 records. But it differs in other ways. A self-extending subfile allows users to add records to the subfile only when they are needed. Normally this is done one page at a time, but it doesn't have to be. One advantage the self-extending subfile has over its load-all counterpart is that subfile performance will be more consistent. By loading only a specified amount each time, your subfile is more likely to perform to expected results. A load-all subfile may load 50 records one time and 500 records the next, depending on your data. Another advantage is that, by using a self-extending subfile and a position-to technique, I can make the navigation within the subfile more flexible.

I have included an example of a self-extending application. SelfExtDDS is the DDS, and SelfExtRPG is the RPG.

First, let's look at the DDS. It looks much like the load-all DDS, except for a few changes. I changed the SFLSIZ from 500 to 16. This does not really mean much, because both the load-all and self-extending subfiles require that the SFLSIZ be greater than the SFLPAG. Where it really matters is how you load your subfile in your RPG code. I could have used 500 here, too, but my standard for self-extending subfiles is to make SFLSIZ one greater than SFLPAG.

Next you will notice that I added the ROLLUP keyword. This will allow my RPG program to control when more records are added to the subfile. With a self-extending subfile, it is important to note that the duties of paging through the data will be shared by your RPG program and OS/400. By adding the ROLLUP keyword, I have told OS/400 that whenever the last page of the subfile is displayed and the user presses the Page Down key to get more data, my program will take control and handle the paging. When the user is not on the last page, or anytime he is paging back through the data, I want OS/400 to handle the paging. (I will discuss this more when I get to the RPG code.)

The last change I made is not required to make this a self-extending subfile, but I always use a position-to field in the subfile control record format whenever I create a self-extending subfile. To me, writing a self-extending subfile without position-to capabilities is like being forced to stop on every floor of my high-rise building even though I live on the 15th floor.

What a self-extending subfile allows is the ability for the user to select where in the subfile he wants to navigate to. If the A's in my name list are displayed, I can enter a name starting with Z in my position-to field and the subfile will position to the Z's or to the name closest to what I keyed in the position-to field.

Now that we've looked at the DDS and saw that there weren't many changes necessary to making this a self-extending subfile, let's glance at the RPG and see what's going on there.

Notice in this program I separate the clearing of the subfile from the loading of the subfile by placing them in two separate subroutines. I do that because, in this program, there will be times when you will add to the subfile and not want to clear it first. There are other times when it will be cleared before loading. Looking at the CLRSFL subroutine, you will see that I set my relative record number (RRN1) to 0 and also set a last relative record number (LSTRRN) to 0. I will use LSTRRN to hold the last relative record of the subfile, so that when I add records to the subfile I will know where I left off.

After setting on indicator 31, which conditions the SFLCLR keyword, I write to the subfile control record format to clear the subfile. Then I set indicator 31 off, which conditions the SFLDSPCTL keyword. I also set off indicator 32, which conditions the SFLDSP keyword.

My subfile load routine is a little different from the load routine in the load-all subfile. That is mainly because I do not want to load all the available records from my database file. I am only going to load one page of data at a time. In this case, field SFLPAG was set as a constant in my D-specs and will contain the same number that is used with the SFLPAG keyword in DDS. If you decide to change the keyword in the DDS, you will have to change the D-spec in your RPG. Don't let the fact that they have the same name fool you. I just like doing it that way.

If end-of-file is reached, indicator 90 will come on and I will exit the loop. Indicator 90 also conditions SFLEND. Otherwise, I increment the relative record by one and write to the subfile record format. Once the loop has finished its work, either by writing the prescribed number of records to the subfile (15, in this case) or by hitting end-of-file, I check whether I should display the subfile by conditioning indicator 32 and set LSTRRN appropriately.

Looking back at the main routine, you will see a more complex DOU loop than that of the load-all subfile. After writing the function key line and throwing the subfile, as you've seen before, I code a SELECT routine to handle the possible responses from the user. The responses I care about in the select logic are if the user keys data into the position-to field or if he presses the Page Down key to see more records.

If the Enter key is pressed after the user has keyed data into the position-to field, I will use the position-to field data to SETLL to my data file, execute the CLRSFL routine, load the subfile based on the position-to entry, and then clear the position-to field (PTNAME) before displaying the subfile again. When the Page Down (ROLLUP) key has been pressed and the subfile is not empty (*IN32 is off), I simply execute the SFLBLD subroutine, which will add to the subfile from where it left off, without clearing it.

Let's go back to the EXFMT command for a minute. Remember I said that, with a self-extending subfile, paging duties are shared between your program and OS/400. This is where that decision takes place. Your program will sit on this line of code until a valid function key (as defined in your DDS) or the Enter key is pressed. However, when the Page Down key is pressed, OS/400 is smart enough to know whether it is about to page through data already in the subfile, in which case, it will take care of it for you; or, if the last page of the subfile is already displayed, OS/400 knows to pass control back to your program.

OS/400 always handles the page up (rolldown) duties in a self-extending subfile. Basically, this means that when you call your program for the first time, the first page of data will be displayed. If you press the Page Down key to get more records, control will pass back to your program and 15 more records will be written to the subfile. Now there will be 30 records in your subfile and page two (records 16-30) will be displayed. If you press Page Up to get back to the first page of data, OS/400 will navigate that one for you and your program will do nothing, because those records already exist in the subfile.

If you decide to page down again, to get to the second page, OS/400 will handle that one, too, because records 16 through 30 already exist. If you decide to see a third page--you guessed it--control is passed to your program to add 15 new records to your subfile.

No matter where you are in your subfile, when you key something into the PTNAME field, the subfile will be cleared and 15 new records will be written and displayed based on what was entered in the PTNAME field. The self-extending subfile is probably the most widely used type of subfile. It balances nicely between letting OS/400 handle a bit of the processing while allowing some code to be added to increase flexibility for the user.

There you have it. Self-extending subfiles cause you to code a little more in your RPG program, but that extra code will allow for more control, which, in turn, will allow for more flexibility. In a future article, I will talk about a third type of subfile that is a little more complex to code, but adds even more power and flexibility. Stay tuned.