Admin tip ...
Simplify API-generated lists processing with a generic list processing procedure – Part I
by Ron Turull
In the last few installments, we have been discussing the open-list APIs. If you followed along in the sample code provided with those articles, you may have noticed that compared to the "regular" list APIs (i.e., the list APIs that write their entire output to a user space and while your program waits), the open-list APIs do not require nearly as much "overhead" programming. Complicated data structures are usually kept to just one or two, you don't need to deal with pointers and user spaces, and you simply call an API to get entries from the list.
Well, some time ago, I got tired of all that overhead programming, and decided to create a procedure that would hide the detail of lists and greatly simplify the process of using them. It doesn't hide all the details -- it is just one procedure after all -- but it hides what for most programmers is the most complicated, error-prone part: retrieving list entries.
How the "regular" list APIs generate lists
APIs such as the List Objects (QUSLOBJ) API or the List Jobs (QUSLJOB) API produce formatted lists of entries, with each entry having the exact same format. The format is "selectable" by the calling program and list-producing APIs usually support several formats.
For example, the List Objects API supports a format that produces entries that contain just the object name, library name, and object type. This same API also supports a format that gives you, in every entry, everything you get when you do a DSPOBJD command with DETAIL(*FULL).
The problems and merits of list processing
Lists generated by APIs, even with simple formats, are complicated creatures. They involve complex data structures and control information that clouds the real data. And, getting to the actual entries involves a intricate process of pointers and offsets.
On the positive side, all the list-generating APIs use a standard data structure format for the control information. That provides us with the ability to code a generic procedure that can handle retrieving a entry from any list, no matter which API generated it and no matter what the format of the list entries.
The Get List Entry procedure
The code shown GETLISTE.RPG defines a procedure, GetListE, that lets you quickly and easily retrieve an entry from a list created by any one of the "regular" list-generating APIs. No need to worry about coding the data structures and doing the pointer arithmetic involved in processing a list. Just tell the procedure which entry number you want, and it will expeditiously return it to you.
In the next installment, we'll discuss the code that makes up the GetListE (Get List Entry) procedure, and we'll see an example of how to use it.
-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.
