Getting Session Started A58 with APIs. from RPG

Transcription

1 Getting Session Started A58 with APIs from RPG Getting Started with System APIs from RPG Susan Gantner Your partner in AS/400 and iseries Education The author, Susan Gantner, is co-founder of Partner400, a firm specializing in customized education and mentoring services for AS/400 and iseries developers. After a 15 year career with IBM, including several years at the Rochester and Toronto laboratories, Susan is now devoted to educating developers on techniques and technologies to extend and modernize their applications and development environments. This is done via on-site custom classes for individual companies as well as conferences and user group events. Together with her partner, Jon Paris, Susan authors regular technical articles for the IBM publication, IBM Systems Magazine, i5 edition (formerly iseries Magazine and eserver Magazine, iseries edition), and the companion electronic newsletter, i5 EXTRA (formerly iseries Extra). You may view articles in current and past issues and/or subscribe to the free newsletter or the magazine at: Feel free to contact the author at: partner400.com or visit the Partner400 web site at This presentation may contain small code examples that are furnished as simple examples to provide an illustration. These examples have not been thoroughly tested under all conditions. We therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. All code examples contained herein are provided to you "as is". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. Copyright Partner400, APIs from RPG - Page: 1-2

2 Using System APIs There are hundreds of System APIs From simple APIs you may already use e.g., QCMDEXC to more complex APIs to provide lists of information from the system Think of "Work With..." commands Lists of objects, spooled files, members, user profiles, jobs, programs, modules in programs, etc. APIs provide interfaces to system functions and system information Documented in the IBM iseries Information Center Choose your OS release Then in the left hand pane Expand the iseries Information Center, Version 5 Release x Expand the "Programming" topic Expand "APIs" - usually the first entry in the list List Type APIs require some detailed knowledge of using User Spaces, Pointers and the structure of List API data. We will be discussing that here. Many of the other types of APIs are simpler. Copyright Partner400, APIs from RPG - Page: 3-4

3 Finding APIs Three ways in Info Center's "API Finder" By Category Best if you don't know the name of the API Sometimes difficult to figure out the right category, however By Name Full or partial name Either the actual program or procedure name or the text name or title To get a list of APIs related to User Spaces either "QUS" because the program names begin with that or "User Space" because the API name or title includes it From an alphabetic list of all APIs When all else fails! A non-info Center approach Often a Google keyword search specifying site:ibm.com provides a faster way to get to the IBM documentation for a specific API May not be the release you want on the first hit But once you have the name, then you can use the API finder easily Sometimes, finding the API you need can be the toughest part of the task! If the IBM Information Center doesn't work for you, try Google with site:ibm.com to limit the search to IBM web pages. Copyright Partner400, APIs from RPG - Page: 5-6

4 Prototyping APIs Prototyping APIs provides many advantages compared to CALL... PARM, PARM, PARM... or to CALLB... PARM, PARM, PARM Use a more meaningful name for the API called The function of the API is often not intuitive from its name Proto options that are useful (sometimes required) with APIs Including options that: Allow for variable size parameters - Options(*VarSize) Allow for Optional parameters - Options(*NoPass) Allow for Omissible parameters - Options(*Omit) Allow the compiler to accept literal values, BIFs or values that are not exactly the right data type or size - CONST We'll have a quick review of prototyping basics by looking at a prototype for QCMDEXC But first, a look at the API documentation for QCMDEXC The option *NOPASS means that the parameter does not have to be passed on the call. Any parameters following that spec must also have *NOPASS specified. When the parameter is not passed to a program or procedure, the called program or procedure will simply function as if the parameter list did not include that parameter. The option *OMIT can be used for parameters which are not mandatory but which occur in the middle of a parameter sequence and therefore cannot be designated as *NOPASS. When the option is specified the special value *OMIT is allowed for that parameter on the call Option *VARSIZE gives the compiler permission to accept a character parameter that is shorter in length than the prototype specifies. This option is often used when the length of the passed field is also passed to the called program, such as in our QCMDEXC example coming up The use of the CONST keyword allows the compiler to accommodate mismatches in the definition of the parameters between the callee and the caller. For example, if the API we are calling expects a packed decimal value of 15 digits with 5 decimal places, we can pass a zoned decimal number of 3 digits and no decimal places if we prefer or a constant numeric value or a numeric expression.. Using the CONST keyword, you are telling the compiler that it is OK for it to make a copy of the data prior to passing it to accommodate such mismatches. This avoids the need for us to explicitly define a working variable of the correct size and type. The compiler can accommodate differences in: Size, decimal places, and type (zoned, packed, integer, etc.) - for Numeric fields The date format - for Date fields and Length and type (fixed or varying) - for Character fields The CONST keyword can be used for all API parameters documented as "Input" (see API documentation example in a later chart.) Copyright Partner400, APIs from RPG - Page: 7-8

5 Example: API Parameter Documentation Execute Command (QCMDEXC) API Required Parameter Group: 1 Command string Input Char(*) 2 Length of command string Input Packed (15,5) Optional Parameter: 3 IGC process control INPUT Char(3) Here is an example of part of the API documentation from the iseries Information Center for one of the APIs you have probably used before: QCMDEXC to execute a command from an RPG program. Note that the last parameter is marked as "Optional". In this case, it controls the use of double byte character sets, which are rarely used except in some Asian languages. Copyright Partner400, APIs from RPG - Page: 9-10

6 A Simple API: QCMDEXC Rather than call QCMDEXC via CALL... PARM, PARM This Prototype allows you to: Use a more meaningful name - OvrDBFile Use a Variable size parameter - Options(*VarSize) Avoid having to move values to pre-defined 15,5 fields - Const Have Optional parameters - Options(*NoPass) D CusMastOvr S 40 Inz('OVRDBF FILE(CustMast) + D TOFILE(NEWCUST)') D OvrDBFile PR ExtPgm('QCMDEXC') D CmdString 3000 Options(*VarSize) Const D CmdLength 15P 5 Const D CmdOpt 3 Options(*NoPass) Const C CallP OvrDBFile(CusMastOvr: %Len(CusMastOvr)) C CallP OvrDBFile('OVRDBF FILE(' + FileName + C ') TOFILE(' + NameToUse + ')' : 41) This example of a prototype for QCMDEXC demonstrates a number of the benefits of prototyping. - First it allows us to use a name indicative of the function performed - in this case OvrDBFile. We used the EXTPGM keyword to supply the "correct" name. Note: if the API you are calling is a bound API, you would need to use the EXTPROC keyword instead. - Second by using Options(*VarSize) we have made it possible to pass the 40 character parameter CusMastOvr when the prototype specifies that the length should be 3,000 characters long. That's 2,940 bytes saved! - Third we don't have to create a 15,5 work field just so that we can pass an integer length! Has that ever struck you as being rather odd? Why would a length ever need any decimal positions, much less 5 of them! CONST can be used on any API parameters defined as "Input" (see documentation chart earlier) - Lastly we can safely leave out the third parameter You did know that QCMDEXC has three parameters didn't you? If you didn't, don't feel bad - the third one is only used for DBCS (Double Byte Character Set) support. Copyright Partner400, APIs from RPG - Page: 11-12

7 Example: API Parameter Documentation Create User Space (QUSCRTUS) API Required Parameter Group: 1 Qualified user space name Input Char(20) 2 Extended attribute Input Char(10) 3 Initial size Input Binary(4) 4 Initial value Input Char(1) 5 Public authority Input Char(10) 6 Text description Input Char(50) Optional Parameter Group 1: 7 Replace Input Char(10) 8 Error code I/O Char(*) Here is an example of the API documentation from the iseries Information Center for another one of the APIs we will be using - Create User Space. We will talk about these data types and how to define them in RPG in upcoming charts. Note also the use of Optional Parameters. We will discuss the impact of these on our RPG programs in upcoming charts as well. Copyright Partner400, APIs from RPG - Page: 13-14

8 Interpreting API Documentation Translation of API documentation into RPG prototypes can be confusing Data types often seem foreign Some of the more common data types used in APIs include: API Documentation English Description Binary(4) 4 byte integer 10 I 0 Binary(2) 2 byte integer 5 I 0 Char(n) n byte Character field n A Char(*) Character field of indeterminate length n A PTR(SPP) Pointer * Note: "n" means any number of characters RPG Definition Char(*) fields are typically defined with the prototype keyword Options(*Varsize) to allow for different lengths One of the first things that seem to be mysterious about APIs to RPGers are the data types. Note the use of the I (integer) data type compared with the B (binary) data type. While many programmers (including those who write many of the examples in the IBM manuals and the includes in QSYSINC) still use the B type, it is better to use I (or U for unsigned integers). I supports the full range of possible values (which B cannot) and it also performs much better. If the API specifies an unsigned binary parameter, use type U instead of I. The length of the I or U field should be 10 for 4 byte fields or 5 for 2 byte fields. (Note: RPG also supports other length Integer fields, but they are rarely used in APIs.) Unfortunately many published examples (including most from IBM) continue to use the old fashioned type B data. Don't follow that lead - use the I or U data types. Copyright Partner400, APIs from RPG - Page: 15-16

9 Parameter Types for APIs APIs use 3 Parameter Types: Required: All of the parameters must be used in the specified order Optional: All or none of the parameters within the optional group You must either include or exclude the entire group You must include all preceding parameters Optional Parameters may (should) be specified with prototype parameter keyword Options(*Nopass) Omissible: The parameters will accept a null pointer in place of a value Omissible Parameters may (should) be specified with prototype parameter keyword Options(*Omit) AND a special value of *Omit must be passed D CrtUsrSpc Pr ExtPgm('QUSCRTUS') D SpaceQname 20a Const D SpaceAttr 10a Const D SpaceSize 10i 0 Const D SpaceInit 1a Const D SpaceAuth 10a Const D SpaceText 50a Const D Replace 10 Const Options(*NoPass) D ErrorFeedbk Like(ErrorInfo) D Options(*NoPass:*Varsize) Most, if not all, APIs have Required parameters. Many also have Optional Parameters. Omissible parameters are fairly rare among APIs. The prototype on this chart uses many of the features we have discussed on the last few charts, such as optional parameters and Binary(4) or Integer data types. Copyright Partner400, APIs from RPG - Page: 17-18

10 User Spaces What is a User Space? Contrary to popular belief, it's not what you find between a user's ears It is: An iseries object of type *USRSPC A simple stream of bytes that you can access directly from within a program Anything the programmer wants it to be! "List Type" APIs use User Spaces The API dumps a variable length list of items into the User Space Your program retrieves the list from the User Space The most efficient way to process the data in a User Space is by using one or more pointers Mapping the User Space to one or more Data Structures using the Based keyword The nearest that traditional programming can come to this concept is a data area, but you have to input and output data areas to and from programs. In contrast, you can immediately change the content of a User Space by merely changing the value of a field in your program. User Spaces have a fixed length and can be extended or truncated using the Change User Space Attributes (QUSCUSAT) API. This API also allows you to allow the User Space to automatically extend its size if necessary, much as physical files are set up by default. Copyright Partner400, APIs from RPG - Page: 19-20

11 A Few Examples of List Type APIs List Database File Members (QUSLMBR) List Database Relations (QDBLDBR) List Fields (QUSLFLD) List ILE Program Information (QBNLPGMI) List Job (QUSLJOB) List Job Log Messages (QMHLJOBL) List Module Information (QBNLMODI) List Object Locks (QWCLOBJL) List Objects (QUSLOBJ) List Objects That Adopt Owner Authority (QSYLOBJP) List Objects User Is Authorized to or Owns (QSYLOBJA) List Open Files (QDMLOPNF) List Program Temporary Fixes (QpzListPTF) List Record Formats (QUSLRCD) List Save File (QSRLSAVF) List Server Information (QZLSLSTI) List Service Program Information (QBNLSPGM) List Signed-On Users (QEZLSGNU) List Spooled Files (QUSLSPL) List Users Authorized to Object (QSYLUSRA) There are many additional List APIs available as well. Copyright Partner400, APIs from RPG - Page: 21-22

12 Layout of Data in the User Space HeaderInfo DS General Information... Offset to List Data Section List data Section Total Size Number of Items in the List Length of Each List Item format More General Information... ListItems DS List Item 1 List Item Last List Item This chart depicts how the List APIs interact with the User space. The List of Items is depicted by the box on the right. But the API puts out some Header information in the User Space as well to let you know interesting things such as the number of entries in the list, the size of each entry and where in the user space the first entry in the list is located. Copyright Partner400, APIs from RPG - Page: 23-24

13 Using Pointers Pointers have a data type of '*' and you don't define a length They actually use 16 bytes of storage Pointers are used to Base the storage of data in the program You need a value in the basing pointer before referencing the based data It can be set using the %Addr BIF or you can get the value from a called program, procedure or API In our example, we will be getting a value from an API D HeaderInfo DS Based(pHeaderInfo) D 103A D ListStatus 1A D 20A D ListOffset 10I 0 D ListSize 10I 0 D NbrEntries 10I 0 D EntryLen 10I 0 You don't actually have to define Pointers. If the compiler comes across a pointer in a Based keyword, it will automatically define it for you - so watch the spelling! In the example on the page above we do not need to explicitly defind pheaderinfo. The compiler will implicitly create it for us. Pointers are always 16 bytes in length and must be aligned on a 16 byte boundary. Therefore, definition of pointers in data structures may require the compiler to generate filler space. When defining pointers in data structures, refer to chapter 7 of the ILE RPG/400 Reference for more details on this phenomenon. In particular check out the ALIGN keyword. In our case, the address value for the pointer will come from the call to an API to get a pointer to the user space. Copyright Partner400, APIs from RPG - Page: 25-26

14 User Space APIs Working with User Spaces involves two APIs: Create User Space (QUSCRTUS) Retrieve Pointer to User Space (QUSPTRUS) The pointer retrieved is used to set the basing pointer of the field or DS D CrtUsrSpc Pr ExtPgm('QUSCRTUS') D SpaceQname 20a Const D SpaceAttr 10a Const D SpaceSize 10i 0 Const D SpaceInit 1a Const D SpaceAuth 10a Const D SpaceText 50a Const D Replace 10 Const Options(*NoPass) D ErrorFeedbk Like(ErrorInfo) Options(*NoPass) D Ptr2UsrSpc Pr ExtPgm('QUSPTRUS') D UsrSpcName 20 Const D PtrToUsrSpc * D ErrorFeedbk Like(ErrorInfo) You must use APIs to create User Spaces and manipulate their contents unless you have a program and/or command someone has created for you to do it. Some shops have a command to create a user space from the tools package in QUSRTOOLS that was once part of OS/400. The only OS/400 user space CL command you will find is the Delete User Space (DLTUSRSPC) command. Consider writing prototypes for all the User Space APIs so they can be easily accessed from RPG programs when needed. In many cases it will be preferable to "wrapper" them with a simple RPG subprocedure. This means that only one person needs to really understand the APIs. The others in the shop can use a simplified method to access the API. This also allows for an update to the error handling process, switching to a new improved API, etc. etc. all without changes to the "using" program. The documentation for the Pointer to User Space API looks like this: Retrieve Pointer to User Space (QUSPTRUS) API Required Parameter Group: 1 Qualified user space name Input Char(20) 2 Return pointer Output PTR(SPP) Optional Parameter: 3 Error code I/O Char(*) Copyright Partner400, APIs from RPG - Page: 27-28

15 Create & Get Access to a User Space This code creates a User Space and gets access to it via the pheaderinfo pointer Note that this is the basing pointer for our Data Structure This code exerpt uses the prototypes from the previous chart After this code runs, the Data Structure is located in the User Space D HeaderInfo DS Based(pHeaderInfo) D 103A D ListStatus 1A D 20A D ListOffset 10I 0 D ListSize 10I 0 D NbrEntries 10I 0 D EntryLen 10I 0 C CallP CrtUsrSpc ('MODULEINFOQTEMP' : C 'DTA' : : '*' : '*ALL' : C 'ILE Program Info': '*YES' : ErrorInfo) C CallP Ptr2UsrSpc ('MODULEINFOQTEMP': pheaderinfo: C ErrorInfo ) In this example, we are simply creating a User Space object by calling the CrtUsrSpc prototype (which corresponds to the QUSCRTUS API - see the prototype in the D specs on the previous chart). Then we get access to the User Space by getting an address using the Ptr2UsrSpc prototype (QUSPRTUS API). Note that the address obtained is placed into the basing pointer for the DS. Copyright Partner400, APIs from RPG - Page: 29-30

16 Example of a "List Type" API To illustrate using list APIs, we will look at QBNLPGMI List module information for ILE programs There are several formats of data available Think of a format as analogous to a record format We are using only one format: PGML0100 The layout for each format is documented in the API manual(s) Our program will create a module cross-reference database file for all the ILE programs in a library To shorten the code, our example assumes the User Space already exists List APIs place data into a user space Data begins with the Header Block of information It contains the status of the list, the number of entries retrieved, length of each entry, offset to the beginning of the first entry, etc. Using this information, your program can set a pointer to the first entry After processing an entry, increment pointer by the length of the entry to advance to the next one The following pages show a coded example of using the List ILE Program API. Our sample program simply writes the module information to a DB file to provide a module cross-reference database file. Note that we pass a parameter to the program which is the name of the library for which we want to capture module information. Special values such as *ALLUSER, *LIBL, etc. are allowed as well as a specific library name. Of course, with a bit of extra logic, we could have allowed multiple library names, etc. The program collects data for all the modules for all the ILE programs in the requested library or libraries. We are collecting a subset of the data available in the API format in our sample program. The field names in the externally described DB file match the field names in the ListItems data structure. Therefore, after setting the pointer for each entry, we simply need to write the data base record. Copyright Partner400, APIs from RPG - Page: 31-32

17 Prototyping QBNLPGMI The API documentation for QBNLPGMI is included below: List ILE Program Information (QBNLPGMI) API Required Parameter Group: 1 Qualified user space name Input Char(20) 2 Format name Input Char(8) 3 Qualified ILE program name Input Char(20) 4 Error Code I/O Char(*) D ListPgmInf PR ExtPgm('QBNLPGMI') D UsrSpcNam 20A Const D Format 8A Const D QualPgmName 20A Const D ErrorFeedbk Like(ErrorInfo) The API documenation for the parameters for QBNLPGMI and the RPG translation for those parameters are shown here. On the following pages, we will see this prototype in use, along with the User Space API prototypes. Copyright Partner400, APIs from RPG - Page: 33-34

18 Documentation for Format PGML0100 Offset Dec Offset Hex Type 0 0 CHAR(10) Program name Field 10 A CHAR(10) Program library name CHAR(10) Bound module name 30 1E CHAR(10) Bound module library name CHAR(10) Source file name CHAR(10) Source file library name 60 3C CHAR(10) Source file member name CHAR(10) Module attribute CHAR(13) Module creation date and time 93 5D CHAR(13) Source file updated date and time 106 6A CHAR(10) Sort sequence table name CHAR(10) Sort sequence table library name 126 7E CHAR(10) Language identifier BINARY(4) Optimization level A subset of the API documenation for the information in the format we're going to use with the QBNLPGMI is shown here. Format PGML0100 contains much more data than is shown here. We're just providing a glimpse at what the format documentation looks like. In addition to defining more information that is available via PGML0100 format, there are 5 other different formats of information available from this API. We could decide to retrieve other information from the other formats if we wanted to. Copyright Partner400, APIs from RPG - Page: 35-36

19 Module Cross-Reference * Copyright Partner400, * Sample code only -- no warranties expressed or implied FXrefModuleO E DISK D Ptr2UsrSpc PR ExtPgm('QUSPTRUS') D UsrSpcName 20 Const D PtrToUsrSpc * D ErrorFeedbk Like(ErrorInfo) D ListPgmInf PR ExtPgm('QBNLPGMI') D UsrSpcNam 20A Const D Format 8A Const D QualPgmName 20A Const D ErrorFeedbk Like(ErrorInfo) D QualPgmName DS D Program 10A Inz('*ALL') D Library 10A D ErrorInfo DS * Definition of the ErrorInfo DS will be shown in a later chart D LibName S 10A D I S 10I 0 Here you see the prototypes for the necessary system APIs to build the module cross-reference file. API QBNLPGMI is the "Get ILE Program information" API. We are assuming here that the User Space object has already been created. We are simply filling it (or re-filling it for update purposes). The ErrorInfo data structure is a standard error feedback mechanism that is used by most of the list type APIs. For space reasons on this chart, it is not shown here, but we will see it in detail on a later chart. Copyright Partner400, APIs from RPG - Page: 37-38

20 Module Cross-Reference (Cont.) As noted in the source, we are only using some of the fields available in format PGML0100 See the API documentation for details of other fields available D HeaderInfo DS Based(pHeaderInfo) D 103A D ListStatus 1A D 20A D ListOffset 10I 0 D ListSize 10I 0 D NbrEntries 10I 0 D EntryLen 10I 0 * More fields are available in this format, but not used here D ListItems DS Based(pListItems) D Pgm 10A D PgmLib 10A D Mod 10A D ModLib 10A D Srcf 10A D SrcLib 10A D SrcMbr 10A The API writes information to the User Space in 2 distinct pieces: The header information, followed by multiple entries - in this example one entry represents details for a module in an ILE program. Note that we have left several bytes in the header DS unnamed because we didn't need the information the API puts in those locations. For our program's purposes, the most important entries in the Header Information that the API puts into the user space are: The list status which will hopefully contain a "C" (for complete), which means the list of program information is both complete and correct. If it contains a "P" (for partial), it means the list information is accurate, but is not complete - probably because the user space wasn't large enough to hold the information. If it contains "I" (for incomplete), the information in the user space should NOT be used because it is not accurate - probably because of some error that occurred while creating the list. The offset to the first "real" entry in the list of program information. That is, this is the beginning of the first entry for the first module in the first program in the library we requested information about. The information in each entry is outlined in the second DS, called ListItems. Note that we have only included the first few items from the format. More info is available to us, but we selected to pay attention and collect only this information. The number of entries in the API wrote to the User Space for us. This will tell us how many entries to process in our RPG logic. The length of each entry in the list. This will help us to move our pointer from one entry to the next. Copyright Partner400, APIs from RPG - Page: 39-40

21 Module Cross-Reference (Cont.) The name of the library to be analyzed is passed in as a parameter QUSPTRUS is used to obtain a pointer to an existing User Space QBNLPGMI is then used to fill that space with module information The List Offset value from the fixed portion of the data returned is used to set the basing pointer plistitems to the first entry in the list C *Entry Plist C Parm Library * Get pointer to user space (assume user space already exists) C CallP Ptr2UsrSpc ('MODULEINFOQTEMP': pheaderinfo: C ErrorInfo ) * Populate User Space with *PGM Module Info with API QBNLPGMI C CallP ListPgmInf ('MODULEINFOQTEMP': 'PGML0100': C QualPgmName: ErrorInfo ) * Position plistitems pointer to first entry in User Space * using ListOffset from Header information C Eval plistitems = pheaderinfo + ListOffset In this example, for simplicity, we assume the User Space already exists. We just need to get a pointer to it by calling the API QUSPTRUS. We could use the QUSCRTUS API (prototype for it was included earlier) to create one if it did not exist. Next we need to ask the API to dump information into the User Space for the programs we're interested in. The programs we want were passed to us as input parameters. Then, using the List Offset value from the Header information in the User Space, we set the pointer to the Data Structure for the first entry in the list. Copyright Partner400, APIs from RPG - Page: 41-42

22 Module Cross-Reference (Cont.) Relevant data from entry in the User Space is written to the database The basing pointer is then updated to point to the next entry And we loop back to process the next entry until all are processed * Process each entry in list in user space and write info to DB file C Eval I = 1 C DoW I <= NbrEntries C Write MODXREFR * Increment to next entry by adding Entry Length (from Header Info) C Eval plistitems = plistitems + EntryLen C Eval I = I + 1 C EndDo C Eval *INLR = *ON The logic to retrieve the information from the User Space is fairly simple, straightforward RPG logic. In this case, we manipulate the pointer directly to get from one "entry" in the list to the next by adding the entry length of each entry (retrieved from the Header info) to the current address of the pointer. Alternatively, we could have padded the ListItems Data Structure out to the maximum length and made it either a Multiple Occurrence Data Structure or a Data Structure array. In that case, we wouldn't need to add the length to the pointer as we did here. We would use either Occur or an array index value to move from one to the other. The potential danger in using this technique is that the API information could change over time - typically adding new information to the end of each list entry. So if you want to use this technique, it would be a good idea to have the program logic compare the EntryLength value to the length (preferably using %Len) of the ListItems DS. Copyright Partner400, APIs from RPG - Page: 43-44

23 Handling API Errors The "Bytes Used" field is set non zero to indicate an error The actual exception Id will have been placed in ExpID The message text is in ExcData (the first 80 characters in this case) The example below shows how we could have used this // Standard API Error Structure D ErrorInfo DS D BytesAv 10U 0 Inz(%Size(ErrorInfo)) D BytesUsed 10U 0 D ExpID 7A D Reserved 1A D ExcData 80A // Try to obtain pointer to User Space CallP Ptr2UsrSpc ('MODULEINFOQTEMP': pheaderinfo: ErrorInfo ); If BytesUsed <> 0; // Error - Assume means not found, so create it CallP CrtUsrSpc ('MODULEINFOQTEMP' :'DTA' : : '*' : '*ALL' : 'ILE Program Info': '*YES' : ErrorInfo); CallP Ptr2UsrSpc ('MODULEINFOQTEMP': pheaderinfo: ErrorInfo ); EndIf; Many system APIs use this same data structure for error feedback. Check the BytesUsed field for > 0 to see if an error occurred. If it did, then we can check the exception ID and/or message text. We used /Free form in this example because it occupies so much less space, it gives us the ability to get a more complete example on the chart. Note that if you prefer to just let the system API send an escape message rather than monitor for and handle it yourself, you may just pass a value of 0 (zero) in the first parameter (BytesAv in our example). Replace our Inz(%Size(ErrorInfo)) with Inz(0). Copyright Partner400, APIs from RPG - Page: 45-46

24 List API Conclusions That's it! List APIs all work using the same techniques we have discussed here You simply need to know how to: Find the right API Read/interpret the API documentation and translate it into: RPG prototypes for the APIs, and Data definitions for the list items Defined a based variable or DS (based on a pointer) Create a User Space object and get access to it via a pointer in your program Define the generic List API header DS They all have the same header information and format Manipulate the basing pointer to the List Items Position to the first entry, then move through the list by adding the entry length each time Detect errors that may occur when calling APIs Via the error feedback structure and the List Status field in the list API header And we've covered all that So go find the list API you need and you should be able to use it! That's All Folks! Questions? Copyright Partner400, APIs from RPG - Page: 47-48