Read an Excerpt
APIs at Work
By Bruce Vining, Doug Pence, Ron Hawkins MC Press
Copyright © 2007 MC Press
All rights reserved.
ISBN: 978-1-58347-692-5
CHAPTER 1
API Fundamentals
All APIs use a set of standards that define how system programs communicate with application programs. While every API communicates different information, they all communicate that information using the same set of standards. Notice that standards is plural. Different types of APIs use different ways to pass data. Some use one long variable to pass data back to your program, while others use a user space to do it. (If you are not familiar with this terminology, don't worry. You'll learn the terms as you progress through the book.) You will soon see that once you understand the different formats used, you are well on your way to using any API in the system.
Begin with the Basics
Application Programming Interfaces (APIs) are simply formal definitions of how you, as a developer, can communicate with the system. You may not be aware of it, but when you code an RPG OPEN statement or use a built-in such as %SCAN, you are, in a sense, using an API. OPEN and %SCAN are formal functions defined by the RPG language to insulate you from knowing how a given file is being opened by the system or what technology might be in use when scanning a character string. (Many, many different technologies might be used!) Likewise, Control Language (CL) represents a set of APIs. You can code a Retrieve Job Attributes (RTVJOBA) command and be confident that the command will work reliably today and tomorrow, independent of what changes i5/OS might make in how a job is managed by the system.
In this book, you will learn about a set of APIs known as system APIs. System APIs let you get at system information or objects that you normally cannot access through more generic interfaces such as CL commands or the RPG language. You can, however, call these APIs from CL and RPG programs and then process the information returned by the APIs using the strengths of the CL and RPG languages. For the remainder of this book, when we refer to APIs, we will be referring to these system APIs.
Like RPG and CL, API standards allow for future enhancements. Even if IBM changes a particular API in the future, that API will still be compatible with older versions, so you can upgrade to new releases of i5/OS without having to change your use of APIs. Of course, you won't be able to take advantage of the new enhancements to the API unless you modify your code, but your existing code will still function just as it did when you wrote it.
Another benefit of APIs is speed. Some CL commands retrieve information about the system into a special kind of file called an outfile. You can then process this outf ile to get at the information you want. While this method works and is easy to use, it is rather slow because the system has to build the file and then write records to it for your application to read later. For example, if you specify OUTPUT(*OUTFILE) OUTFILE(SOMENAME) with the Display Object Description command (DSPOBJD), you can then read the file SOMENAME to get at the information about the object. A much faster way to access this same information is via the Retrieve Object Description API, QUSROBJD. When you call QUSROBJD, it returns the same information as in the outfile (if not more), but as a parameter. Because it doesn't have to build and process the file, this method is much faster than using the command.
APIs can perform many different kinds of functions. For example, the Command Line API, QUSCMDLN, brings up a screen that lets you enter commands to the system. Others, like QCMDEXC and QCAPCMD, let you execute commands directly from within application programs. (See chapter 4 for examples of these handy APIs.) There are APIs to handle messages, process spool files, and work with virtually any object on the system.
Where to Get Information about APIs from IBM
The best source for information about APIs (with the exception of this fine publication, of course) is the IBM Information Center. To access it, point your browser to this site:
http://publib.boulder.ibm.com/iseries
From here, select the release of i5/OS you are interested in. In the Information Center, you will find APIs under the "Programming" topic. In the API topic, you can search for APIs by keyword (using the API Finder) or by category. At first, using the Finder will most likely be easiest for you. As you become more familiar with APIs, you will most likely want to browse the available APIs by category, instead.
When writing applications using APIs, you will want to use the IBM Information Center appropriate for your installed release of i5/OS. This book is written based on the API capabilities provided with V5R4 of i5/OS. IBM has enhanced existing APIs, and introduced new ones, with every release of the operating system since V1R3. You certainly will not want to miss out on the latest API capabilities.
Information Already on Your System
If you have a library called QSYSINC, you already have a wealth of information about APIs on your system. Every system comes with this library, but you have to install it. This library contains source members that could save you a great deal of time while using APIs. The QSYSINC library is installed with option 13 (System Openness Includes) of i5/OS.
The examples in this book assume that the QSYSINC library is installed. If that's not the case, ask your system administrator to install option 13 of i5/OS using either the Work with Licensed Programs menu (GO LICPGM) and option 10, or the RSTLICPGM command.
There are over 20 source files in the QSYSINC library. Most of these files are for using APIs in different languages such as C, COBOL, and RPG. The main file for ILE RPG is QRPGLESRC. Each member in the file contains data structure definitions for i5/OS provided APIs. For program (*PGM) APIs, the name of the API and the name of the member correspond. For service program (*SRVPGM) APIs, the name of the *SRVPGM and the name of the member correspond. There are also some generic members that cross multiple APIs, such as the QUSGEN member, which contains common structures for the user-space APIs.
Try to use these definitions every time you use an API. This provides consistency from program to program. It also reduces problems with erroneous definitions of the data structures. It does not completely eliminate the potential for problems with the definition, though, because some fields are defined as varying in length, where you supply the length of the field. These fields are usually dependent on how much data you want the API to return. Still, using the supplied definitions will save you lots of time overall.
One drawback to using the members in this library is its size. The structures are so well documented (when was the last time you heard that about an IBM manual?) that a simple structure can balloon into hundreds of lines of code. It's not uncommon for a 200-line program to expand to 1,000 lines with all of the text describing each field in each structure. Comments are not pulled into the compiled object, though, so this is not a significant problem.
The sheer volume of documentation with each API caused us a problem in writing this book. While we feel the correct way to use the API is to pull in the complete definition of the structures from QSYSINC, we could not show this with each sample program. If we did, this book would quickly have become encyclopedic. To keep the book to a manageable size, therefore, we haven't included all of the source documentation.
About the Examples
The examples in this book are written using the free-form syntax of ILE RPG. The APIs we discuss can, however, be used by non – free-form ILE RPG, in addition to languages such as CL, COBOL, Java, C, and RPG III (admittedly with some limitations related to features such as pointers not being supported by the language).
Appendix B contains the examples in the chapters re-done to use APIs from fixed-form ILE RPG, and appendix C has examples using ILE COBOL. So, Figures B2.2 and C2.2 correspond to Figure 2.2 in chapter 2. Refer to the text associated with Figure 2.2 to fully understand the code example in Figure B2.2 or C2.2.
Most of the example programs are named based on their figure names in this book. So, a reference to program FIG12_3 is a reference to the program compiled from the source shown in Figure 12.3. We recommend that you use the same convention when naming your source members. The example RPG programs are generally created with the Create Bound RPG Program command, CRTBNDRPG, with no additional parameters specified beyond PGM. That is, to create the example in Figure 2.2, you would use CRTBNDRPG FIG2_2. In a few cases, we create a module using the Create RPG Module command, CRTRPGMOD, followed by the Create Service Program command, CRTSRVPGM. These exceptions are clearly pointed out in the book.
Our examples also tend to make heavy use of the Display Message (DSPLY) operation code. This is not to suggest that you should use DSPLY in production code or simply present an end user with the DSPLY of an error situation. We chose to use DSPLY so that the examples could provide displayable output to you, while not cluttering the example programs with how to load subfiles or work with simple display-file record formats. The intent of this book, after all, is how to use APIs, not how to use i5/OS workstation support. Having said that, some examples do use display files (*DSPFs) where it seemed more natural to provide a full set of information with a *DSPF record.
In addition, the example programs make extensive use of the lowercase letters a to z. If you are working in a Japanese environment using CCSID 5026, we strongly recommend that you change to a CCSID environment such as 5035 or 1399 when compiling and running the example programs.
At the end of each chapter, we also have a "Check Your Knowledge" section. This is an opportunity for you to write a program confirming your understanding of the chapter. The tasks in this section generally involve using APIs different from, but similar to, those used in our examples. Appendix D provides possible solutions to the tasks. As with the example programs, solutions for fixed-form RPG and ILE COBOL can be found in appendixes B and C, respectively.
The code that is available on the Web contains the complete source code for the examples used in this book. Appendix A provides a cross-reference for these examples and instructions on how to load this source onto your system. We recommend that you actually re-type the source code for the examples. Most of them are quite small, in terms of lines of code, and entering them yourself will give you a much better understanding of how they work than just reading them. You get much more of an opportunity to wonder, "Now why are they doing this?"
Pass the Data, Please ...
To use a callable API, you simply code an appropriate call statement. Most APIs pass information back and forth by parameters. It's important to understand how these parameters work. Table 1.1 provides an example of how parameters are documented in the Information Center.
Since APIs can be called by developers using various languages, such as RPG, CL, COBOL, and C, the Information Center normally documents API parameters in a language-neutral fashion. Rather than providing a RPG-specific prototype, for example, the API parameters are described using the parameter order, a short name for the parameter, the usage type of the parameter, and the size of the parameter.
When you call APIs, you usually pass parameters just as you would if you were calling another application program. The appropriate terminology to use when describing this technique is passing parameters by reference. When one RPG program calls another, you generally pass parameters by reference. Your program doesn't actually pass the data from program to program, even though you specify a data field as a parameter. Instead, a pointer to that data is passed. This is why a change to the data by the called program is automatically seen in the calling program, even if the called program ends abnormally. The change to the data occurs immediately, and both programs have pointers that point to the same data.
In APIs documented as in Table 1.1, parameters are passed by reference. The order of the parameters is indicated by the parameter number (1, 2, etc.). A brief description, such as "Receiver Variable," is also provided. (The description will be very brief until you get used to APIs!) Additional information on the content of each parameter is provided later in the API documentation.
API parameters come in three types:
• Input — Your program is supplying information to the API.
• Output — The API is returning information to your program.
• Input/Output (I/O) — You are both providing information and getting information returned to you.
The vast majority of API parameters are either input or output.
Size represents the size of the parameter passed to the API. A size such as Char(8), which is used for the third parameter in Table 1.1 (Format Name), tells you that this parameter is eight bytes long. Similarly, the fourth parameter, Qualified Output Queue Name, is Char(20), or 20 bytes long. Often, you will find a parameter with a size of Char(*), as seen in Table 1.1 for the first parameter (Receiver Variable). This indicates that the parameter is of variable length, and the actual length will be specified somewhere else in the call to the API. (In case you're wondering, for this example, the length would be specified in the second parameter, Length of Receiver Variable.) You will also find many APIs using a size of Binary(4). This indicates that the API is expecting a four-byte binary (or integer) value. Less frequently, you might find Binary(2) and Binary(8), which correspond to two-byte and eight-byte binary parameters, respectively. It is important that you always pass a parameter of at least the size indicated by the API documentation. Declaring or defining a parameter larger than is documented is OK, but declaring a parameter that is smaller can result in some bizarre errors. This point will be covered in more detail later.
With the above information, the QSPROUTQ API described in Table 1.1 can be prototyped as shown in Figure 1.1. (Don't worry about the ErrCde definition — we'll get to that shortly.) If you are interested in more information concerning this API (which is not really necessary at this point), you can find it in the Information Center under "Programming," "APIs," "APIs by Category," "Print," and "General Print APIs." Or, since you know the API's name, you can find it in the Information Center under "Programming," "APIs," "API Finder," and "Find by Name," using QSPROUTQ.
By convention, we prototype Char(*) variable-length parameters with options(*varsize) and a length of one when referencing an output parameter, and a length of 65,535 when working with input parameters. The Receiver parameter, for instance, is defined as a one-byte variable-length parameter in Figure 1.1.
Some APIs support a different method of passing data. This method is referred to as passing parameters by value. Passing by value actually passes the data between the programs. RPG IV, for example, supports this method with the keyword VALUE. So, if the API you are using has been categorized as pass-by-value, be sure to use the VALUE keyword. This method is generally applicable to Unix-type and C-language run-time APIs, which are documented using a different style, as shown in Figure 1.2.
With this type of API, the parameter descriptions are read differently, although in a manner that will be very familiar to developers who have worked with C. The parameters are defined within parentheses after the API name. Various types of data might be used when defining a parameter. An int represents a four-byte integer value, like Binary(4) does for QSPROUTQ. Short indicates a two-byte integer, long long an eight-byte integer value, an asterisk represents a pointer, and char represents a character variable. With this type of API, char (character) data is generally of a variable length, like Char(*) in QSPROUTQ, but you often do not explicitly tell the API how long the variable is. Instead, the end of the character string is typically indicated by a null byte, where null is defined as x '00'. Fortunately, ILE RPG can handle this type of character definition in many cases by using the OPTIONS(*STRING) keyword on the prototypes. If you don't see an explicit parameter defining the length of an input character parameter, you should use the OPTIONS(*STRING) keyword. The names Path and Oflag are brief descriptions of the parameters. They are further described later in the API documentation, along with whether a parameter is input, output, or I/O.
(Continues...)
Excerpted from APIs at Work by Bruce Vining, Doug Pence, Ron Hawkins. Copyright © 2007 MC Press. Excerpted by permission of MC Press.
All rights reserved. No part of this excerpt may be reproduced or reprinted without permission in writing from the publisher.
Excerpts are provided by Dial-A-Book Inc. solely for the personal use of visitors to this web site.
