Integrate Python into CL & RPG on IBM i - 2021 Update

Python on IBM i has proven itself as a tool for building utilities to create/read Excel files, transfer data, automate processes, call REST APIs such as Salesforce and ServiceNow, monitor applications, and more. What was missing was an easy way to use the power of Python from CL and RPG.

In 2019 we introduced you to the PYRUN command for running Python scripts from CL and RPG programs.

In this post we introduce you to QSHPYRUN, the next generation of PYRUN and part of Richard Schoen’s open source QShell on i Library – QshOni. QSHONI makes it easy for traditional CL and RPG programs to call Python utilities and use their output. This is supported via the QSHPYRUN command. QSHONI also supports general calls to other QShell, PASE and bash calls via the QSHEXEC and QSHBASH commands. This means QSHONI commands support calling Python, Node, PHP, Java and all things open source, making QSHONI much more versatile than the standalone PYRUN command was. The QSHONI commands can safely live side-by-side with the PYRUN command because they live in different IBM i libraries. This allows for migration to QSHPYRUN to happen as needed.

Before trying QSHPYRUN, you must install the Python language itself, as described by Stephanie Rabbani in the linked IT Jungle Guru tip.

The challenge

Because Python runs in PASE, traditional IBM i jobs must spawn a new PASE job to run the selected Python script. The calling application can’t consume the PASE output without a little help.

A solution: QSHPYRUN

The QSHPYRUN command is a front-end wrapper command that does the following:

Allows various calling options, including the Python path and script name, automatically setting the path to the IBM Open Source packages (via parameter: SETPKGPATH=*YES), passing a list of up to 40 input parameters as needed, and parameter switches that determine how QSHPYRUN should return the Python script’s results.
Calls the Python script.
Captures Python’s output from standard output (STDOUT) and sends it to the requested location so that the output can be consumed by the calling job or other applications.

Choose where you would like your output

We’ve been calling PASE scripts (PHP, Python, Node, more) from CL and RPG for years, but QSHPYRUN is special. With QSHPYRUN, we can choose several ways to receive output from the script. By default, output is logged to the table QTEMP/STDOUTQSH. (On IBM i, every job has its own, unique QTEMP library.) QSHPYRUN can also return output via several other options:

DSPSTDOUT – Display the outfile contents within your interactive (5250 mode) program (good for debugging.)
LOGSTDOUT – Place STDOUT log entries into the calling job’s job log.
Note: Don’t log to the job log if you expect your Python script to output thousands of lines to STDOUT. You will litter your IBM i job log with superfluous info in many cases or you may even kill the IBM i job if the job message queue hits its limit and the IBM i job is not set to wrap its job log. You can easily identify QSHPYRUN’s messages by its CPF message ID of PYM9898.
PRTSTDOUT – Print STDOUT to a spool file. Handy for batch jobs.
DLTSTDOUT – This option ensures that QSHPYRUN cleans up its internally used IFS temp files after processing.
IFSSTDOUT – This option ensures that QSHPYRUN can capture the entire IFS log to another IFS log file. This option coupled with the IFSOPT parameter to *APPEND or *REPLACE the specific IFS log file can be a good way to aggregate the result of multiple command calls to QSHPYRUN, QSHEXEC or QSHBASH to a single log file.

Once your Python script has completed and the QSHPYRUN command returns without any errors, your CL, RPG, or COBOL application can then read QTEMP/STDOUTQSH to process any useful data such as return values.

Extend QSHPYRUN using your own CL programs

You could make this even easier by writing your own wrapper program or CL command to call QSHPYRUN to run a Python script, and then read STDOUTQSH for return values and send them back through your custom CL command return parameters. Example: say you wrote a Python script to read a database and generate an Excel file with an auto-generated name. You need to get the name back. Python could write the name to STDOUT so that the calling CL or RPG application could read it in and then do something with the new Excel file. There are limitless uses for running Python scripts from traditional IBM i applications and then consuming the result for use.

Create your own utilities with the QSHPYRUN Command

This post was just a quick introduction to the QSHPYRUN command. In future posts, or during training or consulting engagements, we can teach you how to use QSHPYRUN and the other QShOni commands in your own applications. Enjoy Python on IBM i and send us your feedback.