Even though many people say the iSeries 400 is a closed and proprietary system, it does offer a huge number of "openness" application program interfaces (APIs).

I remember years ago when IBM Rochester held the first meetings to discuss the idea of adding APIs to the system. The first set of APIs included User Space, User Index, and Data Queue APIs. At the time, all the API names were designed to begin with the letters QUS. The "US" identifier stood for "USER"--IBM's term for "programmer" back then.

Today, there are so many APIs that the manual itself is over 3,000 pages long! I don't know the exact number of APIs available in OS/400, but it's hundreds and hundreds if not well over a thousand by now. So the naming convention of QUSxxxxx has long since been retired.

Rather than attempt to keep track of all the APIs and their purpose in life, I've tried to maintain an easy way to search and review the APIs I may need. I keep a copy of the OS/400 System API Reference manual in PDF form on my PC. When a new release of OS/400 becomes available, I usually download an updated copy of the API manual. It is available at http://publib.boulder.ibm.com/html/as400/v5r1/ic2924/books/c4158000.pdf.

What Good Are APIs?

APIs provide a program interface to system routines. Just like the CL command interface provides access to virtually every system function, APIs provide a way for high-level language (HLL) programs to run these same types of system functions.

For example, suppose you need to retrieve a system value while you're inside an RPG IV program. You could simply write a CL program that calls the RTVSYSVAL command and then return the corresponding value to the RPG program through a parameter; nothing wrong with that.

Using APIs, however, you could simply call the same interface that the RTVSYSVAL command uses from within RPG. The API is QWCRSVAL. A cool thing about the APIs is that added function is often provided. For example, the QWCRSVAL API allows you to retrieve several system values simultaneously. You could, for example, retrieve all the password-related system values with one call to QWCRSVAL.

Two very interesting APIs are the Retrieve Job Information API (which I use to retrieve the library list) and the Change Library List) API. These allow you to, as expected, retrieve or change the library list from within an HLL. But the great thing about these APIs, particularly the Change Library List API, is that they allow you to actually set the so-called product libraries as well as the current library and the library list.

Change Library List (QLICHGLL)

QLICHGLL allows you to modify the library list for your job. As I mentioned, you can change the regular "user portion" of the library list as well as the two product libraries and the current library.

The first parameter is the current library name. It must be specified (it cannot be blank), and it must be left-justified with a trailing blank. In addition to any valid library name, the current library parameter accepts the following special values:

*SAME--The current library is not changed.

*CRTDFT--There is no current library. The CRTxxxPGM command will use QGPL as the default library name.

The product library parameters have the same restrictions as the current library parameter. In addition, the product library parameters accept the following special values:

*NONE--The product library (if any) is removed. Either product library 1 or 2 may have this value.

*SAME--The product library is not changed. Either product library 1 or 2 may have this value.

The user library list parameter is an array of 11-position character values. Each array element may contain a library name, left-justified with a trailing blank in position 11.

The user library list count parameter tells the API how many library names have been specified in the User Library List. Effectively, this is the number of used array elements. This value is a 4-byte binary or 4-byte integer field.

The final parameter is the standard API error data structure. Often, we just ignore that parameter by passing it a value of X'00'.

The following CPF error messages may be generated by the QLICHGLL API:
CPF2106 Library list not changed.
CPF2110 Library &1 not found.
CPF2113 Cannot allocate library &1.
CPF2133 First product library on library list destroyed.
CPF2134 Second product library on library list destroyed.
CPF2137 Current library on library list destroyed.
CPF2176 Library &1 damaged.
CPF2182 Not authorized to library &1.
CPF2184 Library list not replaced.
CPF219A Library QTEMP cannot be specified.
CPF219F Number of libraries for library list not valid.
CPF24B4 Severe error while addressing parameter list.
CPF3C90 Literal value cannot be changed.
CPF3CF1 Error code parameter not valid.
CPF9872 Program or service program &1 in library &2 ended. Reason code &3.

Retrieve Job Information (QUSRJOBI)

The QUSRJOBI API is an old API, but it has been continually updated throughout the years. QUSRJOBI can retrieve most information about the current running job, including the library list.

The first parameter, library list, is a return value--a data structure that contains all the libraries on the library list, including system portion, user portion, product libraries, and the current library name. Note that the QLICHGLL API does not support changing the system portion of the library list. But that is typically never done in production code, so this shouldn't be an issue.

The second parameter is the length of the data structure being used to receive the library list (i.e., the length of the first parameter).

The third parameter is the name of the format used by the API. This format controls what type of information the API returns. The QUSRJOBI API can return a lot of different information, so the convention for this and many other APIs is to accept a format ID that indicates which pieces of information the API should return. To retrieve the library list, format ID 'JOBI0700' is passed.

The fourth parameter is the qualified job name for the job whose information is being retrieved. Yes, you can retrieve the library list for another job if you want. But a more practical use is to retrieve the library list for the current job. So rather than pass in a 26-byte data structure simply create a field that is 26 positions in length and set the first character of the field to an asterisk (*). Leave the rest of the field blank.

The fifth parameter is the internal job name. Leave this parameter blank.

The sixth and final parameter is the standard API error data structure.

Wrapping It All Up

Logically, we would need to call QUSRJOBI to retrieve the current library list, modify the list, and then call QLICHGLL to set the list to what we want.

But wouldn't it be more useful to have this function wrapped in a usable RPG IV procedure? Listed in Figure 1 is the RPG IV source for two procedure prototypes, and they are:

GETLIBL--Retrieve the library list for the job.

SETLIBL--Change the library list to the new list specified.

To use the procedures, you need to include the prototypes for them in your code using either the /COPY or /INCLUDE compiler directives.

Figure 1: Prototypes for Library List Procedures

Listed in Figure 2 is the RPG IV source for two procedures that wrap the functionality of these two APIs to provide a simplified interface to their function.

Figure 2: Source code for Library List Procedures