Don’t Let Your RPG Just Drift, Grab an OAR!
October 13, 2010 Jon Paris
|
When IBM Rational Open Access (OAR): RPG Edition was announced, all the buzz was about how it would (or would not) impact the green-screen world. But the possibilities for OAR go far beyond workstations. Perhaps more to the point, while few people have the skills to write their own 5250 handlers, writing handlers for other purposes is well within the grasp of the average RPG programmer. In this tip I am going to introduce you to the basic mechanics of how an OAR handler works. In a sub-sequent tip, I will put that theory into practice by describing the workings of a simple handler. What Is OAR? For those who have not yet read much on OAR, a brief introduction may be in order. IBM’s documenta-tion says it as well as anything I can say, so: “(Open Access) . . . provides a way for RPG programmers to use the simple and well-understood RPG I/O model to access resources and devices that are not directly supported by RPG. Open Access opens up RPG’s file I/O capabilities, allowing anyone to write innovative I/O handlers to access other devices and resources such as: browsers, mobile devices, cloud computing resources, Web services, . . . .” This extract was taken from the IBM document Rational Open Access: RPG Edition, which you can download from IBM’s RPG Cafe. So, with the appropriate handlers (programs or procedures), my RPG IV programs can access Web ser-vices using simple CHAIN operations. Or perhaps UPDATE an Excel spreadsheet using the row and column numbers as the keys. Or READ directly from a comma-separated-values (.csv) file. All of these things can be done with the right handler. The person who writes the handler “handles” all the nuts and bolts of accessing the Web service, updating the spreadsheet or parsing the .csv stream file, while the application programmer simply codes the READ, CHAIN, or UPDATE. The significance of this is that these kinds of functions can be used by any RPG programmer without the need to understand the mechanics of the underlying technology. We all take advantage of RPG operations such as CHAIN and EXFMT without knowing how RPG implements the interface under the covers. OAR gives us the opportunity to spread this ease of use to a wider and, more importantly, more modern set of devices and interfaces. Of course in a limited sense such things have been possible for many years using SPECIAL files. But the limited amount of information passed to a SPECIAL file program by the RPG run-time makes it very difficult to write generic routines. In addition SPECIAL files only permit sequential operations, so keyed operations are not supported. As a result SPECIAL files, while they have been around for years, have not been widely used. If you are not familiar with how SPECIAL files work, you may want to take a look at some of the articles listed in the Related Stories section at the end of this article before read-ing on. The OAR Difference What’s so different about what OAR offers over SPECIAL files? Aside from handling keyed I/O opera-tions, the biggest difference is the ability to obtain a wealth of information about the file and the data involved in the I/O operation. Let’s take a look at some of that data. Whereas a SPECIAL file receives the record buffer in one piece, an OAR handler can choose to receive individual fields, along with the details of the field type, length, etc. This makes it much easier to write a single OAR handler that can deal with a variety of situations. A word of warning: If you have never dealt with nested data structures and basing pointers in RPG, you’ll need to have those skills before you can deal with writing an OA handler. And if you’re allergic to field names longer than six (or even 14) characters, you may want to have some Benadryl handy. Fortunately, you don’t need to code all the complex structures yourself. The IBM document I mentioned earlier contains full details of the data layout. IBM has also posted on the RPG Cafe PDF copies of the /COPY source files that describe the various DS layouts used. You can find them here. As you can see in those documents, IBM includes all of the required constants as well as the various data structure layouts. The relationship between the various structures is demonstrated in Figure 1, which you can see at this link. I don’t have the space here to describe all the data structures in detail, but let’s take a look at the primary one that you’ll use to get access to the individual field values. The top level structure looks like this: D QrnNamesValues_T... D DS QUALIFIED TEMPLATE ALIGN D num 10I 0 D field LIKEDS(QrnNameValue_T) D DIM(32767) The “num” field contains the number of field descriptions in the buffer. This is how you determine how many of the 32,767 DS array elements are actually in use. The really important pieces of information are in the “field” DS array, whose elements look like this: D QrnNameValue_T... D DS QUALIFIED TEMPLATE D externalName... D 10A D dataType... D 3U 0 D numericDefinedLen... D 3U 0 D decimals... D 3U 0 D dtzFormat... D 3U 0 D dtSeparator... D 1A D input... D N D output... D N D isNullCapable... D N D hasNullValue... D N D reserved1... D 13A D valueLenBytes... D 10U 0 D valueMaxLenBytes... D 10U 0 D valueCcsid... D 10I 0 D reserved2... D 10U 0 D value... D * D reserved3... D * As you can see there is a lot of information here. But don’t worry, you will rarely need to use even half of the information provided in any given handler. In addition you will find that the actual IBM docu-ments contain many comments to help decipher this information. I have omitted the comments here for space reasons. The key pieces of information from this structure for most handler applications are the field name, data type, length, and decimal positions (if numeric), which are contained in the first four subfields. The actual field value is accessed via the pointer found in the “value” subfield. To access the field data, you would typically define a BASED field that looks something like the example below. In this case, the pointer from the OAR DS value subfield would be copied into the basing pointer pfieldValue. The supplied data length (valueLenBytes) can then be used with the %SUBST() BIF to extract the actual data. All values appear in character format with simple formatting, as if each non-character value had used %Char. D fieldValue s 32470a Based(pfieldValue) In addition to the field name/value information we have covered here, there are several other pieces of information in the data structure passed as the parameter to the OAR handler. These include the details of the file being used in the application program using the handler (e.g., its name, whether it is keyed and the number of key fields, and its declared RPG device type). There is also a code to identify the specific operation that invoked the handler on this occasion (e.g., OPEN, READ, CHAIN, EXFMT, etc.) There are fields that communicate information back and forth between the RPG run time routines and the handler. These include feedback to RPG on the status of the I/O and whether the handler prefers the name/value detail as described above versus the “raw” record buffer, à la SPECIAL files. In my next tip, you’ll see an example of using these structures to produce a handler and we’ll address a typical flow for an OAR handler. Jon Paris is one of the world’s most knowledgeable experts on programming on the System i plat-form. Paris cut his teeth on the System/38 way back when, and in 1987 he joined IBM’s Toronto software lab to work on the COBOL compilers for the System/38 and System/36. He also worked on the creation of the COBOL/400 compilers for the original AS/400s back in 1988, and was one of the key developers behind RPG IV and the CODE/400 development tool. In 1998, he left IBM to start his own education and training firm, a job he does to this day with his wife, Susan Gantner–also an expert in System i programming. Paris and Gantner, along with Paul Tuohy and Skip Marchesani, are co-founders of System i Developer, which hosts the new RPG & DB2 Summit conference. Send your questions or comments for Jon to Ted Holt via the IT Jungle Contact page. RELATED STORIES Basing Pointer Variables in RPG: The Basics Use Special Files to Access the IFS OS400 V5R2: More Features Added to RPG IV
|
Just noticed that most (all?) of the links in this article that reference charts etc. are broken.