You are currently on IBM Systems Media’s archival website. Click here to view our new website.

IBM i > DEVELOPER > RPG

Getting a Handle on RPG’s Open Access

Discover how simple it is to create a generic handler


 

This month, we’re focusing on our first real foray into the world of Open Access for RPG (OAR) handlers. In previous articles, we talked about OAR in general terms; this time we’ll get down to specifics.

You might recall that in our earlier articles “Get More from RPG” and “Making RPG Even More “Special”,” we described using RPG’s SPECIAL files and how OAR could alleviate some of their shortcomings. What we didn’t expect as we leapt headlong into our OAR explorations was how just simple it would be to create a generic handler and how much power you can get from relatively little effort.

To demonstrate this, rather than starting from the SPECIAL file program, we decided instead to create a new one that would have greater utility value. The program in question creates a Comma Separated Value (CSV) file containing one line for each record written by the RPG program. Yes, we know you can already achieve this by creating an output file and using Copy To Import File (CPYTOIMPF), but haven’t you ever wished you could just do it directly from within your RPG program? We have.

Both sample programs will use the same basic rules for the file’s output format. Character fields will be trimmed of trailing spaces and enclosed in double quotation marks. Numeric and date fields will be output as-is and any other data types (e.g., timestamps) will be ignored. Additionally, we’ll use a comma as the field separator following all fields except the last in the record.

A New SPECIAL File

You’ll recall that to use the Special File program we simply declare the file (an output file in this case) as RPG device “Special” and supply a program name via an F spec keyword. The F spec in our “calling” program looks like this:

     FIFS_OUT1  O    E             Special PgmName('IFSWRITE')

Our special file is written to expect data in a specific format, so the program declares an externally described data structure as the template for the record buffer that’s passed as the fourth parameter (A). In addition, we /Copy’d the prototypes for the IFS APIs from the IBM supplied prototypes in QSYSINC (B). We’ve also defined a few work fields and constants (C).

So the relevant D specs of the program look like this, omitting, in the interest of space, the Prototypes for the program and its internal subprocedures. (In 7.1 we’d be able to omit these from the source member if we wanted—hurray!)

    D IFSWrite        PI
    D  Action                        1A   Const
    D  Status                        1A
    D  Error                         5S 0
(A) D  RecData                            LikeDS(ExtDef)  

(B)  /copy qsysinc/qrpglesrc,ifs

(A) D ExtDef        E DS                    EXTNAME(IFS_OUT1) Template

(D) D FileHandle      S             10I 0

     //   Constants for SPECIAL file operation requests
(C) D OPEN_Request    C                   'O'
    D WRITE_Request   C                   'W'
    D CLOSE_Request   C                   'C'

The mainline logic flow for this program is very simple since all it needs to do is determine which operation is requested and invoke a procedure to handle each one. Since it’s almost identical in this respect to the previous examples, we won’t go into detail.

       If Action = OPEN_Request;

         FileHandle = openFile('/partner400/TestSG');

       elseIf Action = WRITE_Request;

         WriteFile(FileHandle);

       elseIf Action = CLOSE_Request;

         closeFile(FileHandle);
         *InLR = *On;

       EndIf;

       Return;

All of the real work happens in the procedures, but even that logic is quite simple. We’ll show you the OPEN_Request procedure. The Open action will call our program in the case of either an implicit RPG or user-controlled open request. We won’t go into the meaning of the content of the flags and mode fields. We’ll also leave the details the parameters passed to the IFS open API for your own study. To learn more about the IFS APIs, we recommend Scott Klement’s free tutorial.

 

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.



Advertisement

Advertisement

2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters