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.
|
Parameter
|
Input/Output
|
Definition
|
|
Current library
|
Input
|
Char(11)
|
|
Product library 1
|
Input
|
Char(11)
|
|
Product library 2
|
Input
|
Char(11)
|
|
User library list
|
Input
|
Array of Char(11)
|
|
User library list count
|
Input
|
Int(4) in RPG 9B0 or 10i0
|
|
Standard API error data structure
|
Output
|
Char(16)
|
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.
|
Parameter
|
Input/Output
|
Definition
|
|
Library list
|
Output
|
Char(*)
|
|
Length of first parameter variable
|
Input
|
Int(4)
|
|
Format name
|
Input
|
Char(8) 'JOBI0700'
|
|
Qualified job name
|
Input
|
Char(26)
|
|
Internal job identifier
|
Input
|
Char(16)
|
|
Standard API error data structure
|
Output
|
Char(16)
|
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
Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.
MC Press books written by Robert Cozzi available now on the MC Press Bookstore.
 |
||
 |
|
RPG TnT Get this jam-packed resource of quick, easy-to-implement RPG tips! List Price $65.00 Now On Sale
|
|
||
 |
|
The Modern RPG IV Language Cozzi on everything RPG! What more could you want? List Price $99.95
Now On Sale
|
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online