QshOni

This IBM i library contains useful CL wrapper commands to allow Qshell and Pase apps to be called and consumed from regular IBM i jobs via CL, RPG or COBOL programs. It also has a CL command to scan stdout for a specific value if you need to do something simple to check for a successful command run.

The main benefit of this wrapper is to be able to integrate Qshell/Pase applications on-the-fly with standard IBM i job streams.

There are several ways to build the library. Pick your favorite.

Library Build Note

❗ If you get an error running build.sh you may need to run dos2unix build.sh to convert CR/LF to LF in the build.sh file. You must first have dos2unix installed via the IBM i open source package management. Please open an issue to let me know if you run into this problem.

News

5/17/2025 - New command QSHGETPR2 can be used to retreive STDOUT return values to the calling job. You can optionally write the RTNPARMxx values as *DIAG messages to the joblog or to data areas for use with other calling programs.
5/17/2025 - Updated QSHPHPRUN, QSHPYRUN and QSHPYCALL to make double quotes optional for command line parameter arguments. Still defaults to double quotes for backward compatability.
2/6/2025 - New dynamic RUNSQLPRM and RUNSQLSRC SQL action commands added. Allows passing soft coded parameters to SQL statements or SQL statements in source members from CL programs.

Example of RUNSQLPRM inserting a record to QIWS/QCUSTCDT by passing SQL statement template and parms.

RUNSQLPRM SQL('INSERT INTO @@LIB.@@FILE (CUSNUM,LSTNAM) VALUES(@@CUSNUM,@@QT@@LSTNAM@@QT)')                 
         PARMS(@@LIB @@FILE @@CUSNUM @@LSTNAM @@QT)         
         PARMVALS(QIWS QCUSTCDT 123456 Test '''')           
         NAMING(*SQL)                                       
         DSPOUTPUT(*YES)

Example of RUNSQLSRC inserting a record to QIWS/QCUSTCDT using source member with template parms

RUNSQLSRC SRCFILE(QSHONI/SOURCE)                 
          SRCMBR(SQLTEST4)                       
          PARMS(@@LIB @@FILE @@CUSNUM @@LSTNAM)  
          PARMVALS(QIWS QCUSTCDT 123456 Test)    
          NAMING(*SQL)                           
          DSPOUTPUT(*YES)                        

2/6/2025 - Updated QSHQRYTMP and QSHQRYSRC SELECT SQL query commands to allow selection of Naming (*SQL or *SYS) and can also optionally add a unique ID column to the query results OUTFILE after it's created if a unique ID field is needed for your OUTFILE. Also added ability to pass soft coded parameters to SQL statements or SQL statements in source members from CL programs. This makes the queries much more dynamic when embedding in CL programs.

Example of QSHQRYTMP to select records from table QIWS/QCUSTCDT using soft coded file name parameter. This example also adds a unique ID to the outfile table after it's created.

QSHQRYTMP SQL('select * from @@LIB.@@FILE')      
         PARMS(@@LIB @@FILE)                    
         PARMVALS(QIWS QCUSTCDT)
         OUTFILE(QTEMP/SQLTMP0001)
         CRTIDCOL(*YES)

Example of QSHQRYSRC to select records from table QIWS/QCUSTCDT using soft coded file name parameters in source member SQLTEST3. This example also adds a unique ID to the outfile table after it's created.

QSHQRYSRC SRCFILE(QSHONI/SOURCE)   
          SRCMBR(SQLTEST3)         
          PARMS(@@LIB @@FILE)      
          PARMVALS(QIWS QCUSTCDT)
          OUTFILE(QTEMP/SQLTMP0001)
          CRTIDCOL(*YES)

IBM Qshell/PASE Documentation

The following IBM links take you to documentation on the Qshell and PASE environments from IBM

IBM PASE for i
https://www.ibm.com/docs/en/i/7.5?topic=programming-pase-i

IBM i QShell
https://www.ibm.com/docs/en/i/7.5?topic=languages-qshell

Check latest version info (Current Version 1.0.46 - 12/20/2025)

https://github.com/richardschoen/QshOni/blob/master/version.md

Check out one-liner Python samples

https://github.com/richardschoen/QshOni/blob/master/samples/python-oneline-samples.md

Check out sample CL wrapper use-case commands that use QSHEXEC

https://github.com/richardschoen/QshOni/tree/master/samples

Installing and Building QSHONI via getrepo-qshoni.sh script

(Important to change SRCCCSID variable in build.sh to your local CCSID before running build.sh. Default=37)

Use the following install script if you want to run a single shell script to clone the repo and build the library.
https://github.com/richardschoen/QshOni/raw/refs/heads/master/getrepo-qshoni.sh

Download and run the getrepo-qshoni.sh script in one step, using wget

❗This is the easiest way to install and build QSHONI using the most recent version source. Run the following wget command to download, build and install QSHONI quickly in a single step.
Make sure a temporary dir named /tmp/QshOni doesn't already exist before running the script or the git clone may fail to get current files from the repository.

rm -r /tmp/QshOni
wget https://github.com/richardschoen/QshOni/raw/refs/heads/master/getrepo-qshoni.sh -O - | bash

Manually download getrepo-qshoni.sh and run it

• Download the raw getrepo-qshoni.sh script or create it manually in your IFS. https://github.com/richardschoen/QshOni/refs/heads/master/getrepo-qshoni.sh
• Then run the getrepo-qshoni.sh script to automatically clone the repo and auto-run the build.sh to create the QSHONI library and associated objects.

bash getrepo-qshoni.sh

Installing and Building QSHONI via Git clone and build.sh

(Important to change SRCCCSID variable in build.sh to your local CCSID before running build.sh. Default=37)

# Use this install method if you want to manually run each command from a QSH/PASE/SSH shell.
mkdir /qshoni
cd /qshoni 
git -c http.sslVerify=false clone --recurse-submodules https://github.com/richardschoen/QshOni.git
cd qshoni
build.sh  

After building the QSHONI library the commands should be ready to use.

Installing QSHONI library via save file and creating QSHEXEC command objects

Use this install method if you want to install from a save file object.

❗The SAVF download install method is not recommended. Building from source by cloning the repository is the preferred build method so you always get current source and library objects created on your specific system.

Download the qshoni.savf save file from the selected releases page.

https://github.com/richardschoen/QshOni/releases (Latest pre-built save file version - V1.0.37. Build from source for more current)

Upload the qshoni.savf to the IFS and place it in /tmp/qshoni.savf

Run the following commands to copy the save file from the IFS into a SAVF object

CRTSAVF FILE(QGPL/QSHONI)

CPYFRMSTMF FROMSTMF('/tmp/qshoni.savf') TOMBR('/qsys.lib/qgpl.lib/qshoni.file') MBROPT(*REPLACE) CVTDTA(*NONE)

Restore the QSHONI library

RSTLIB SAVLIB(QSHONI) DEV(*SAVF) SAVF(QGPL/QSHONI)

Build the QSHONI commands

(Important co CHGJOB CCSID(37) before building from SAVF)

CHGJOB CCSID(37)

ADDLIBLE QSHONI

CRTCLPGM PGM(QSHONI/SRCBLDC) SRCFILE(QSHONI/SOURCE) SRCMBR(SRCBLDC) REPLACE(*YES)

CALL PGM(QSHONI/SRCBLDC)

Installing QSHONI library via wget and creating command objects

Use this install method if you want to install from a save file object via wget

❗The SAVF download install method is not recommended. Building from source by cloning the repository is the preferred build method so you always get current source and library objects created on your specific system.

Run the following commands to copy the save file from github into a SAVF object

CRTSAVF FILE(QGPL/QSHONI)

From QSHELL/QPTERM or BASH run:

❗This latest built save file version is V1.0.37. To get latest, build library from the GitHub repo directly.

/QOpenSys/pkgs/bin/wget https://github.com/richardschoen/QshOni/releases/download/v1.0.37/qshoni137.savf --no-check-certificate -O  /qsys.lib/qgpl.lib/qshoni.file

Restore the QSHONI library

RSTLIB SAVLIB(QSHONI) DEV(*SAVF) SAVF(QGPL/QSHONI)

Build the QSHONI commands

(Important co CHGJOB CCSID(37) before building from SAVF)

CHGJOB CCSID(37)

ADDLIBLE QSHONI

CRTCLPGM PGM(QSHONI/SRCBLDC) SRCFILE(QSHONI/SOURCE) SRCMBR(SRCBLDC) REPLACE(*YES)

CALL PGM(QSHONI/SRCBLDC)

Delays running QShell or bash commands with QSHEXEC/QSHBASH

❗ If you experience delays running QShell Commands, it's probably related to your system DNS settings. Check out the following issue: https://github.com/richardschoen/QshOni/issues/29

Using the QSHEXEC CL command to call a Qsh/Pase command sequence

The following example calls the ls command to list files for the /tmp directory:

     QSHEXEC CMDLINE('cd /tmp;ls')   
     DSPSTDOUT(*YES)         
     LOGSTDOUT(*NO)          
     PRTSTDOUT(*NO)          
     DLTSTDOUT(*YES)
     IFSSTDOUT(*NO)
     IFSFILE('/tmp/log.txt')
     IFSOPT(*REPLACE)
     PRTSPLF(QSHEXECLOG) 
     PRTUSRDTA(*NONE)    
     PRTTXT(*NONE)       

The following example runs an SQL query with db2util and exports the results as JSON to the QTEMP/STDOUTQSH outfile:

      QSHEXEC CMDLINE('export DB2UTIL_JSON_CONTAINER=array;db2util -o json "select * from qiws.qcustcdt"')     
      DSPSTDOUT(*YES)                                      

QSHEXEC command parms

Overview - This CL command can be used to run a QSH/PASE command and log the results appropriately.

Stdout Logging Note: During execution, the CL command always creates a temporary outfile in library QTEMP that gets automatically populated with standard output (stdout) from the QSH/PASE command process that gets run. The temporary stdout output file name is: QTEMP/STDOUTQSH. If the file already exists for a subsequent run of the command, the QTEMP/STDOUTQSH temporary file is automatically cleared before