You are currently on IBM Systems Media’s archival website. Click here to view our new website.


Get More from RPG

SPECIAL files process IFS directories and more


In last month’s EXTRA, we discussed some of the possibilities that IBM’s upcoming Open I/O support for RPG might offer. We also mentioned some of those capabilities are already available today via the often-ignored RPG SPECIAL files. This month, we’re presenting an example of a SPECIAL file in action.

Imagine if, instead of opening a database and reading through all of the records, RPG also allowed you to open a directory in the IFS and to read all of the directory entries. Along with the name of each file (or directory) it would also provide you with information on the latest date the entry was created, modified and accessed.

Well, IBM hasn’t actually added this capability to RPG, but we have. The program we’re presenting here, when used as an RPG SPECIAL file, provides exactly this capability. It relieves the RPG programmer from having to understand the mechanics of reading IFS directory entries. They simply have to know how to specify they want to use this "file" and then use regular READ operations to retrieve the records.

We’re not going to describe the inner workings of the SPECIAL file program as far as the directory processing is concerned. If you want to understand that in detail, please read our earlier articles starting with "Walking Through an IFS Directory," which explain the entire process. Instead we’re going to focus on the details of how the programmer specifies and uses the SPECIAL file. We’ll be highlighting sections of the code in this article, but if you would prefer to see the full source code you can download it from our website.

The way a SPECIAL file works is really straightforward. Whenever the program executes an I/O operation against the file, the request is passed to the SPECIAL file program for action. In this example, it will first receive a request to open the file; it does this by opening the specified directory. Once the file is open, it will receive a series of read requests. It will respond to each request by reading an entry from the directory, formatting the required data and then returning that data as a record to the program—just as if it was read from a database.

Once the SPECIAL file has read all of the entries in the directory, it will signal end-of-file and subsequently will receive a close request, which it will action by closing the directory.

Let’s see how programmers specifies they want to use the file.

The User Program USESPECIAL

The first thing programmers must do is code the F-spec for the file:

FDirEntriesIF   F  732        SPECIAL PgmName('DIRREADER') 
F                                     PList(DirReaderParm) 
F                                     UsrOpn            

The first thing to note is this is a program-described file, and this is perhaps the biggest single problem with today’s SPECIAL file support; it only works with program-described files. So, you need to specify the maximum record length on the F-spec (the "732" entry for those of you who haven’t coded a program described file in decades). The next thing is to specify SPECIAL for the file-type designation. That tells the compiler a program will be used to handle the file processing. The PgmName keyword identifies the actual program used; ours is called DIRREADER. Because there’s no equivalent to an OVRDBF command to allow us to specify the directory you want to read, you need another way of passing that information to the SPECIAL file program. That’s the purpose of the PList keyword. It names the parameter list used to supply the directory name.

Because you’re forced to use a PLIST, you’re also forced to use fixed-form coding. We normally do all of our coding in /Free, so we’ve buried the PLIST at the bottom of the program in a dummy subprocedure to keep it out of the way and preserve the aesthetics of our beautiful code!

     PListDummy    BegSr                                 
     DirReaderParm PList                                 
                   Parm                    directoryName 

For this particular program, only one additional parameter (the name of the directory to be opened) is needed. It’ll actually become the fifth parameter to the SPECIAL file program, since it will be added to the standard group of four parameters that are always passed. If you need additional parameters, they’d simply be added to this PLIST.

In this particular example, we also chose to code USROPN to simplify the detection and reporting of any open failures.

Since you can’t use external descriptions to describe the record layout, you must devise your own. In this case, we chose to use the DS directoryData to provide the record layout. This is included in the program via the /COPY of the member DIRDATA. Using this, you can ensure the data definitions used here and in the SPECIAL file program match. By specifying this DS on the READ operation, you avoid hard coding any input specifications.

The balance of the program is hopefully self-explanatory, since it uses nothing but standard RPG READ and EXCEPT op-codes for the I/O, which is the whole point of using SPECIAL files. They let us make more complex facilities—such as reading through IFS directories—available to all of our programmers through conventional RPG I/O operations.


Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters