I recently had a requirement to retrieve the number of members currently contained in any given file. So I looked at the RTVOBJD CL command, figuring IBM would have made it object-type sensitive by now. Nope, no luck there.

I know DSPFD will give it to me, but I need it in a command or call-level interface. So I looked at RTVMBRD to see if there was an option for *NONE on the member name (and perhaps it would include the member count as a return value). Nope, no luck there.

Then I decided to use the QDBRTVFD API because I knew the information was in there. In fact, it is in the header returned by this API, so knowing all the ins and outs of the API to get, for example, the list of key fields, is unnecessary. Finally, some luck.

The QDBRTVFD API essentially does everything that the DSPFD command does, except produce a list of member names (although, now that I think about it, it probably does that too). You pass it the name of the file whose information you need, and it will return that information. Just make sure you don't use the online InfoCenter API documentation when setting up the return value data structures. The documentation for this API has several inaccuracies that can cause you days of headaches and debugging that goes nowhere.

Use the QSYSINC source member in QRPGLESRC named QDBRTVFD. The data structure named QDBQ25 is the one that contains the header information. That's all you need to retrieve the file's attributes, including the current member count.

The QDBRTVD API is a program that can be prototyped as follows:

The first parameter is the return buffer—a data structure that receives the return value. The data structure needs to be at least 400 bytes, but 700 is the minimum the API likes to return.

The second parameter is the length of the data structure specified on the first parameter. The API will return up to the value specified on this parameter. So normally you would pass in %size(myReturnDS) for this parameter.

The third parameter is a variable that receives the name of the actual file whose information is returned. This file name may be different from that specified on the fifth parameter if, for example, the library name was specified as *LIBL or *CURLIB or if overrides are applied to the file and *ON is specified for the bOverride parameter.

The fourth parameter is the API's format identifier. This tells the API what kind of information to return. In our example, we only need the basic file information, so format ID 'FILD0100' is always specified.

The fifth parameter is the name of the file whose information is going to be retrieved. The first 10 positions contain the file name. The second 10 positions contain the library name, *LIBL, or *CURLIB.

The sixth parameter is the name of the record format of the file whose information is being retrieved. For our example, we are not using this parameter, so specify either blanks or '*FIRST'. The parameter is ignored when the API format (fourth parameter) is 'FILD0100'.

The seventh parameter is an override processing flag. If specified as *ON or '1', then any overrides that apply to the file specified on the fifth parameter are taken into consideration when retrieving the file information. If *OFF or '0' is specified for this parameter, then overrides are ignored.

The eighth parameter is the local or remote file indicator. Specify *LCL if the file is located on the iSeries that is calling the API, specify *RMT if the file is on a remote system, such as a DDM file, or specify *FILETYPE if you want the API to look at the file description to determine where the file is located.

The ninth parameter is one of those parameters that isn't used very often, and in our example it is ignored. Specify either '*INT' or '*EXT' as the result will be the same.

The final parameter is the standard API error data structure. It is based on a data structure named QUSEC_T, which I created for my upcoming book RPG TNT: 101 Dynamite Tips and Techniques for RPG Programmers. The source code for QUSEC_T follows:

The first parameter of the QDBRTVFD API is a data structure. Although it would be beneficial to use a user space for the first parameter, it is not necessary in our example. Instead, the follow data structure can be specified to receive all the information necessary to retrieve the current number of members along with a lot of other information.

To use this data structure, declare a new one and specify it as the first parameter on a call to QDBRTVFD, as follows:

Note that the QDBQ25_T data structure has a KeySeqAttr subfield. This field is a nested data structure. If you are on OS/400 V5R2 or later, this syntax will work. If not, you need to create a nested data structure using the OVERLAY keyword and remove the LIKEDS keyword. The data structure on which this subfield is based follows:

Once the API was set up, I wanted to create a Retrieve File Description (RTVFILED) CL command so I could easily retrieve the member count from within CL. With today's CL capabilities, I could call the API directly and be done with it, but I wanted a nicely wrapped up CL command definition. The source for this command definition follows:

As you can see from the Command Definition source, I chose to allow not only the current member count to be returned, but also the record length, key length, key field count, field count, and CCSID of the file. A lot more information can be returned, so you could easily modify the above command to return whatever other information you need.

To compile the command definition source, be sure to specify ALLOW(*IPGM *BPGM *IMOD *BMOD); otherwise, it won't compile. I'm not sure why, after 20+ years of hearing us complain, IBM still requires you to enter these ALLOW options, when they are in fact required for command parameters that include RTNVAL(*YES). Why not just default that way? And IBM wonders why most people don't bother creating commands.

The command processing program is interesting. It uses all the latest and greatest features of RPG IV, such as prototyped entry-plist, free-format, nested data structures, and data structure templates.

Once the RPG IV program and the command are created, they can be used from with CL as follows:

As you can see, CL supports integer data types. If you don't have a release with integer data types, you can use a four-position character field and then convert that character data to numeric as follows:

Hopefully, everyone will soon be on V5R3 so we're all on a good, consistent release.