Call/Parm Your Open Source Apps from RPG and CL with QSHCALL

A few years back I created the QShell on IBM i (QshOni) project to allow QShell/PASE (open source) apps to be more easily integrated and used with traditional IBM i job streams written in RPG and CL. Since then, many developers have adopted QshOni to utilize their open source apps in conjunction with their classic traditional apps.

Recently I added several new commands to QshOni to make living the PASE life even easier for RPG developers. Today’s focus will be on the QSHCALL command.

I created QSHCALL and a related service program (QSHONISRV) to bring QShell and PASE program calls closer to the RPG developer. You can use them in RPG, CL, and COBOL apps to call open source scripts and programs and then return parameter values.

In IBM i-speak we’ve always referred to this technique as call/parm—calling a program and returning parameters from the called program. The QSHCALL command and service program make calling open source apps feel more comfortable for IBM i RPG developers.

Use Case for QSHCALL

Let’s talk about a potential use case for the QSHCALL command: calling utility functions written in an open source language. Many such functions can be accomplished much more easily in an open source language than in RPG, CL, or even C—which I did a lot in the late 90’s and early 2000’s when integrating to other systems. That’s only because IBM i lacked the open source environments that we have today.

Perhaps you’ve created a Command Line Interface (CLI) application or script in PHP or Python that does something useful like:

• transfer a file with SFTP,
• reach out via curl to make a call to a web service and return JSON or XML data,
• send an email message, or
• create a PDF report or document with something like Jasper Reports.

When your utility completes, you would like to send the success or failure results back to the caller, along with a few pieces of parameter information. This is where QSHCALL comes in to bridge the gap between your PASE and RPG applications.

A Closer Look

Before QshOni, we had only one way to return parameter or log information across process boundaries—by using the STDOUT (standard output) console log information that gets produced from an open source program call to QShell/PASE. Think of STDOUT as being similar to your regular IBM i job log output.

QshOni’s QSHEXEC and QSHBASH commands simplified the process. They let you call your code, return an outfile result (or the entire STDOUT log), and then run your own custom processing. QSHEXEC and QSHBASH create a copy of the STDOUT log in outfile QTEMP/STDOUTQSH, and that file can be used by your primary job from CL or RPG to process results as needed.

QSHCALL makes things even easier by automatically scanning the STDOUT log for specially-coded log entries that are prefixed with RTNPARM01-RTNPARM10. After QSHCALL completes the QShell/PASE command thread, it auto-scans and processes the STDOUTQSH outfile for you, looks for the RTNPARMxx keywords, and returns them in the appropriate output parameter variables in the QSHCALL command.

QSHCALL can be embedded directly into your CL programs. To use it with ILE RPG, wrap the QSHCALL sub-procedure in the QSHONISRV service program. Now your ILE RPG program can accomplish the same thing as the QSHCALL CL command.

Try It with Sample Scripts

If you want to give QSHCALL a try, install the latest version of QShell on i and test out the following samples. On the QShell on i site you’ll find a sample Python script (pycallparm1.py) and a PHP script (phpcallparm1.php) that can be used to test QSHCALL functionality. There is also a sample CL program (QSHCALLT.CLLE) that can be used to test out the QSHCALL command with the Python script. The CL sample program can be easily modified to call the PHP sample script or any other QShell/PASE command line as needed.

Once you are comfortable with the QSHCALL CL command, check out using the QSHONISRV service program to embed the QSHCALL functionality directly into your RPG apps to perform call/parm with your open source apps. Use this RPG program template to test the QSHCALL sub-procedure, QSHONIPR03.RPGLE.  The RPG template can be adapted to your own processes.

Now you can get started integrating your RPG, CL and open source apps using call/parm and QSHCALL.