User Spaces and List APIs

In "Service Programs and Signatures," we covered service programs, signatures and using binder language to manage the signature values. We mentioned that it was possible to automate the process of updating all of the programs that reference a service program if you don't want to bother with binder language. Here, we explain how to do that as well as demonstrate how to use "list" APIs.

Many RPGers shy away from using list APIs because doing so effectively involves using pointers and user spaces. If you're unfamiliar with pointers, we suggest you read this previous iSeries EXTRA column for some basics on using pointers as well as some examples.

List APIs dump the information requested into a user space. Why a user space? These APIs, as the name implies, return lists of items, and you can't predict how many items will be returned in the list. Because of this, returning the results as a parameter wouldn't work, and processing an outfile is slower than the direct memory access that a user space provides. In our case, we'll be asking for a list of all of the ILE programs in a library along with some information about which service programs each program references, if any.

First, we use an API call to create the user space object to hold the output of the API. You can think of a user space as a data stream that can be formatted any way the application requires. In our case, the API QBNLPGMI determines the data structure.

In our code sample, we use prototypes when we call the APIs. If you're unfamiliar with using prototypes, this is a great time to learn, because they offer some advantages over the traditional CALL ... PARM... PARM type syntax. See this previous iSeries EXTRA column for a look at how prototypes work.

Let's first examine the prototype for the API to create a user space-QUSCRTUS. We'll use the prototype to change that to the more meaningful name CrtUsrSpc. The parameters to be passed to the API are simple and include:

  • The qualified name for the user space object (the library name begins in position 11)
  • The type of information we want to put in the user space
  • The initial size (in bytes) of the user space
  • What initialization value we want
  • The authorities for the object
  • The text for documentation.
  • Replace yes or no
  • Error Feedback structure


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.

comments powered by Disqus



2019 Solutions Edition

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

Are You Multilingual?

Rational enables development in multiplatform environments

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