The ABCs of APIs

Written by Doug Pence Friday, 31 December 1999 18:00 - Last Updated Thursday, 04 October 2007 03:50

When IBM wants to provide more functionality, it either builds it into the operating system or provides another API. Each release of OS/400 has more APIs than the last. If you dont know how to take advantage of APIs, you may not be getting everything out of the system that you could be. A great deal of really useful information is in your system, but you must know how to use APIs to get to it. The AS/400 has a great command interface. If you want to perform a function, find the command that will take you there. Commands that return data will usually do so by sending data back to the screen, to a spool file, or to an outfile. An outfile is a simple database file where you can store the output that a command produces. Although outfile processing works well, it does not work fast. If you want speed, you need to use an API. The more you know about APIs, the more likely you are to find ways to use them. Using APIs is not very difficult and is very efficient. The key to using APIs is to call the API and pass it the correct parameters. Most of the work associated with APIs lies in handling parameters. Some parameters, such as file name and library name, are simple. Other parameter passing is more complex. More complex parameters contain items such as variable length data structures, binary fields, or pointers. These can be difficult to get just right.

Application Programming Interface 101

APIs have two distinct methods of returning data. Some APIs return data as a data structure (or series of data structures) within a parameter, and other APIs return the data via an object called a user space. Lets talk about how the data structure method works first. The Retrieve Object Description (QUSROBJD) API is a prime example of how to return data using data structures. After calling the API (Figure 1), the 100-byte variable ReceiveVar will contain information about the object named in the fourth parameter, ObjectLib. The layout of the data within this variable is dependent upon the file format name we enter in the third parameter, FileFmt. Because I have entered OBJD0100 as our file format, this API will return the least information possible. Format OBJD0200 will return all of OBJD0100 and a little more, OBJD0300 will return all of OBJD0200 and a little more, and so on. Each format requires that you define a larger ReceiveVar parameter. Most of the APIs use this technique of passing a predefined file format name to describe the data you want the API to return. In the second parameter, ReceiveLen, we define the length of the ReceiveVar parameter. ReceiveLen is a 4-byte binary field. Heres a tip: When you define a binary field as a standalone field, you must define it with a length of 9. If you define it in a data structure with the from and to positions, you define a binary field with a length of 4. Failure to define parameters may not always result in hard errors, but your results will probably not be what you are looking for. Consequently, defining the correct length of parameters is very important when dealing with APIs.

To Get Good Grades, Proof Your Own Work

As shown in Figure 1, the last parameter in the Retrieve Object Description API is called ErrorDs, and it is optional. Most APIs use this parameter to handle errors. If you code this parameter and an error occurs with the API, the system will not issue the CPF message. Instead, the API will return the message ID (MSGID) and error description within the subfields of the ErrorDs data structure. The error-handling data structure is a typical example of how APIs use data structures as parameters. The first field in the data structure, bytes provided (BytesPrv), is a 4-byte binary

1/6

The ABCs of APIs

Written by Doug Pence Friday, 31 December 1999 18:00 - Last Updated Thursday, 04 October 2007 03:50

field that you use to tell the API how large the data structure is. The bytes available (BytesAvl) field is a 4-byte binary field the API uses to tell you how much data it returned. This technique of using a fixed-length field (usually binary) to tell the length of the following data is used in a lot of API parameters.

Undergraduate Work

The second example of how APIs return data is by using an object called a user space. A user space is a chunk of AS/400 real estate that you can use any way you please. APIs can manage the creation, deletion, and retrieval of data from these user spaces. APIs that create lists of information usually employ a user space to hold the information. Because the length of the list may be larger than the maximum size of a single field, a return field parameter cannot be used. User spaces do not have the same field size restrictions and are, therefore, a more logical choice.

Pay Attention to the Examples Given in Class!

Figure 2 shows examples of how to use three different APIs. In our sample code, we create a user space, retrieve a list of data from the system and store it in a user space, and retrieve the list. Weve chosen to show this example in RPG III rather than RPG IV because we realize that not all of you have moved to RPG IV. You can still use most of the APIs in RPG III, as this example shows; however, we strongly advocate that you move to RPG IV as soon as your business concerns will allow. We should mention here that it is far easier to retrieve data from a user space with RPG IV because it supports pointers. In Figure 2, we use the Create User Space (QUSCRTUS) API to create a user space. This API is easy to use. The parameters are self-explanatory, so you shouldnt have much trouble using this one. After we have created the user space, we use the List Database Relations (QDBLDBR) API to get a list of all logical files over a physical file. The first parameter that this API wants is the name of the user space. The second parameter, OUTFMT, tells the API what kind of information you want to list by designating which file format to use to describe the returned data. We used DBLR0100 in our example, which tells the system to retrieve file information. The third parameter tells the API which file and library to use. The fourth parameter contains the member name of the physical file. And the last parameter, which weve aptly named IGNORE, is used only for OUTFMT DBLR0300, so we can ignore it. After the QDBLDBR API executes, the user space contains a list of all logical files that exist over the specified physical file. Now that we have gathered our information in the form of a list, we have to retrieve that list from our user space. To accomplish this, we use the Retrieve User Space (QUSRTVUS) API. In general, you give this API just the name of the user space, a starting position (relative to the beginning of the space), the length of data to retrieve, and a data structure variable into which the information will be returned. Its generally a little more complicated when dealing with the list APIs because we dont know the position of the data in the user space. The list API deposited variable data into the user space, and we dont know its exact position. But all list APIs follow the same convention for storing data. The beginning of the user space contains a general data structure that contains the offset position of the data. If you look at the GENDS data structure in Figure 2, youll see the OFFLST, NUMLST, and SIZENT fields, which define the number of bytes from the beginning of the user space to the beginning of the list, the number of entries in the list, and the size of each entry in the list, respectively. We can use these fields to set up a loop to retrieve each list entry

2/6

The ABCs of APIs

Written by Doug Pence Friday, 31 December 1999 18:00 - Last Updated Thursday, 04 October 2007 03:50

using the QUSRTVUS API.

Cliff Notes

Many of the formats used as parameters for APIs are already coded on your machine. Library QSYSINC stores various source files that contain the members that correspond to various APIs. Source file QRPGLESRC in library QSYSINC contains members coded in RPG IV, and source file QRPGSRC contains members coded in RPG III. If you scan through QRPGLESRC, you will find a member named QUSROBJD, which contains the definitions for the return data for this API. Figure 3 shows the layout for the OBJD0100 file format. Although QSYSINC relieves you from the task of coding the parameters and ensures that the parameters are defined correctly, it does not do it all for you. You still have to know what values are placed in those parameters. For that, you need to refer to the manuals on the IBM AS/400 Online Library (publib.boulder.ibm.com/pubs/ html/as400/online/homeeng1.htm). Get familiar with them, but get used to change. IBM seems bent on making you jump through hoops to retrieve information. Every release seems to change the Web site where information is stored. Homework can be easy if you have the right reference materials. Many times, the most difficult part of working with APIs is knowing where to look for the information. See the references at the end of this article for some Internet sites that can help you in your quest for more information about using APIs.

REFERENCES AND RELATED MATERIALS

IBM AS/400 Online Library: publib.boulder.ibm.com/pubs/html/as400/online/homeeng1.htm. (From this Web page, select your version and then enter APIs in the find field.) IBM Information Center: publib.boulder.ibm.com/pubs/html/as400/infocenter.html. (IBM is in the process of moving all APIs from the manuals to this Web site. Select programming and then select OS/400 APIs.) IBM Redbooks: www.redbooks.ibm.com. (Enter APIs in the search field. Of particular interest is A Modern Approach to Programming RPG IV with Style.) D FileFmt S 8 inz(OBJD0100) D ReceiveVar S 100 D ObjectLib S 20 inz(MYOBJECT MYLIB ) D ObjectType S 10 D Binaries DS D ReceiveLen 1 4B 0 inz(100) D ErrorDs DS 116 inz D BytesPrv 1 4B 0 inz(116) D BytesAvl 5 8B 0 D MessageId 9 15 D ERR### 16 16 D MessageDta 17 116 * Attempt to retrieve object description C call QUSROBJD C parm ReceiveVar C parm ReceiveLen C parm FileFormat C parm ObjectLib C parm *FILE ObjectType C parm ErrorDs * If file doesnt exist, send message and get out C if MessageId *BLANKS C exsr SNDMSG C endif

3/6

The ABCs of APIs

Written by Doug Pence Friday, 31 December 1999 18:00 - Last Updated Thursday, 04 October 2007 03:50

* Figure 1: This sample code calls the QUSROBJD API. * BINARY VARIABLES I DS I B 1 40 STRPOS I B 5 80 STRLEN I B 9 120 LENSPC * GENERAL DESCRIPTION IGENDS DS 140 I B 113 1160 SIZINP I B 125 1280 OFFLST I B 133 1360 NUMLST I B 137 1400 SIZENT * GENERAL FEEDBACK IINPUT DS 58 I 1 20 USRSPC I 1 10 SPCNAM I 11 20 SPCLIB I 21 28 OUTFMT I 29 48 FILLII I 29 38 FILNAI I 39 48 FILLBI I 49 58 RCDFMI * GENERIC ERROR DATA STRUCTURE IERROR IDS I B 1 40 BYTPRV I B 5 80 BYTAVA I 9 15 MSGID I 16 16 ERR### I 17 116 MSGDTA * DETAIL LIST FROM QDBLDBR--LIST DATABASE RELATIONS API ILIST DS 48 I 1 20 MAINFL I 1 10 MNFILE I 11 20 MNLIB I 21 30 DEPFIL I 31 40 DEPLIB I 41 41 DEPTYP I 42 44 DEPRSR I B 45 480 BINREF * C *ENTRY PLIST C PARM FILLIB 20 C MOVELFILLIB OUTFIL 10 C MOVE FILLIB OUTLIB 10 C MOVEL'USRSPC' SPCNAM C MOVEL'QTEMP' SPCLIB C Z-ADD116 BYTPRV * CREATE USER SPACE C CALL 'QUSCRTUS' C PARM USRSPC C PARM *BLANKS ATRSPC 10 C PARM 1024 LENSPC C PARM *BLANKS VALSPC 1 C PARM '*CHANGE' AUTSPC 10 C PARM *BLANKS TXTSPC 50 C PARM '*YES' RPLSPC 10

4/6

The ABCs of APIs

Written by Doug Pence Friday, 31 December 1999 18:00 - Last Updated Thursday, 04 October 2007 03:50

C PARM ERROR * LIST DATABASE RELATIONS TO USER SPACE C CALL 'QDBLDBR' C PARM USRSPC C PARM 'DBRL0100'OUTFMT 8 C PARM FILLIB C PARM '*FIRST' RCDFMI C PARM *BLANKS IGNORE 10 C PARM ERROR * IF FILE FOUND C MSGID IFNE 'CPF5715' C Z-ADD1 STRPOS C Z-ADD140 STRLEN * RETRIEVE USER SPACE GENERAL INFORMATION DATA STRUCTURE C CALL 'QUSRTVUS' C PARM USRSPC C PARM STRPOS C PARM STRLEN C PARM GENDS C Z-ADD1 STRPOS C Z-ADDSIZINP STRLEN * RETRIEVE DETAIL LIST INFORMATION C CALL 'QUSRTVUS' C PARM USRSPC C PARM STRPOS C PARM STRLEN C PARM INPUT C MOVEL'USRSPC' SPCNAM C MOVEL'QTEMP' SPCLIB C OFFLST ADD 1 STRPOS C Z-ADDSIZENT STRLEN * WALK THROUGH USER SPACE FOR NUMBER OF LOGICAL FILES C DO NUMLST C CALL 'QUSRTVUS' C PARM USRSPC C PARM STRPOS C PARM STRLEN C PARM LIST C DEPFIL IFEQ '*NONE' C LEAVE C ENDIF * DO SOMETHING WITH NAMES OF DEPENDENT FILES (DEPLIB/DEPFIL) C* MOVELDEPFIL DSPFIL C* MOVE DEPLIB DSPLIB * ADD SIZE OF ENTRY TO START POSITION FOR NEXT LIST ENTRY C ADD SIZENT STRPOS C ENDDO C ENDIF C SETON LR D***************************************************************** D*Type Definition for the OBJD0100 format D***************************************************************** D QUSD0100 DS D* Qus OBJD0100 D QUSBRTN06 1 4B 0 D* Bytes Returned

5/6

The ABCs of APIs

Written by Doug Pence Friday, 31 December 1999 18:00 - Last Updated Thursday, 04 October 2007 03:50

D QUSBAVL07 5 8B 0 D* Bytes Available D QUSOBJN00 9 18 D* Object Name D QUSOBJLN 19 28 D* Object Lib Name D QUSOBJT00 29 38 D* Object Type D QUSRL01 39 48 D* Return Lib D QUSASP04 49 52B 0 D* Aux Storage Pool D QUSOBJO04 53 62 D* Object Owner D QUSOBJD04 63 64 D* Object Domain D QUSCDT10 65 77 D* Create Date Time D QUSCDT11 78 90 D* Change Date Time Figure 2: This sample program shows how to use list APIs with a user space. Figure 3: This sample code is from QSYSINC/QRPGLESRC, member QUSROBJD.

6/6