Problem solve Get help with specific problems with your technologies, process and projects.

Simplify API-generated lists processing with a generic list processing procedure -- part 2

In a number of recent installments, we discussed the open-list APIs. When compared to the "regular" list APIs, we saw -- among other things -- that the open-list APIs do not require nearly as much "overhead" programming. Some of the "regular" list APIs have an open-list API counterpart, but most do not. So, in part 1 we introduced the GetListE procedure that lets you quickly and easily retrieve an entry from a list created by any one of the "regular" list-generating APIs without all the overhead programming.


Ron Turull
In a number of recent installments, we discussed the open-list APIs. When compared to the "regular" list APIs, we saw -- among other things -- that the open-list APIs do not require nearly as much "overhead" programming. Some of the "regular" list APIs have an open-list API counterpart, but most do not. So, in part 1 we introduced the GetListE procedure that lets you quickly and easily retrieve an entry from a list created by any one of the "regular" list-generating APIs without all the overhead programming.

More Information
  • Simplify API-generated lists processing with a generic list processing procedure

    Part 1

  • Open-list API provides crucial information on activation groups

    Part 1
    Part 2
  • Open-list API provides crucial information on activation groups

    Part 1
    Part 2

Understanding how to call the GetListE procedure

Here's what you need to know: The parameters of the GetListE (Get List Entry) procedure are:

  • Qualified User Space Name (Input). A 20-character parameter containing the qualified name of the user space where the list is stored. Specify the name of the user space in the first ten bytes (bytes 1-10) and the library name in the second ten bytes (bytes 11-20). You can specify *LIBL for the library name portion. You can also specify blanks for the entire parameter to reset the user space name.

  • Entry Number (Input). A four-byte unsigned integer used to indicate which entry number you want to retrieve.

  • Number of Entries in the List (Output – optional). A four-byte unsigned integer in which the procedure will return the total number of entries in the list. This is an optional parameter.

  • Subsetted List (Output – optional). An indicator value that will inform you if the list entries are subsetted. Some APIs produce data that can't fit in the space allotted by the format. Details can be found in the specific API documentation. This is an optional parameter – unless you have a compelling reason to use this parameter, you will want to omit it.

    The GetListE procedure returns a pointer to the requested list entry. If you request an entry that doesn't exist (e.g., if you request an entry number beyond the end of the list), the procedure returns a null-pointer ( *Null ). You access the entry by basing a variable (e.g., a data structure) on the pointer.

    Using the GetListE procedure

    The program shown TGETLSTE.RPG illustrates how to use the GetListE procedure. This sample program calls the List Objects (QUSLOBJ) API to fill a user space (QTEMP/US) with a list of object names (all objects in library RONT). It then calls the GetListE procedure in a loop to retrieve each entry one by one.

    Notice the return value is assigned to the pointer pObjectDS, upon which the ObjectDS data structure is based. After each call, we can access the ObjectDS data structure to retrieve the data in the entry.

    -----------------------------------
    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.


  • Dig Deeper on Business-to-business (EDI, UCCnet)

    Start the conversation

    Send me notifications when other members comment.

    Please create a username to comment.

    -ADS BY GOOGLE

    SearchDataCenter

    Close