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.

Check latest version info (Current Version 1.0.33 - 8/6/2024)

https://github.com/richardschoen/QshOni/blob/master/VERSION.TXT

1.0.33 - Updated QSHIFSSIZ with stat64 to support up to 15 digit numeric return.
1.0.32 - Added QSHQRYSRC command for querying data via a static source member in a library or IFS text file and placing results in an outfile. This is good for using SQL to prep data for a report or aggregate data for a secondary process.
Added QSHSAVLIB and QSHSAVIFS commands for savng library and IFS objects and outputting an IFS save file when save is complete.

1.0.31 - Changed QSHIFSSIZ command return length from 9 to 15. We can currently still only
return max size value of 2,147,483,647 bytes until we convert the command to use stat64 at
some point, but most IFS files you might use this command with will probably by under 2gb in size.
If this is not the case you can always use stat64 in your own RPG code to retreive IFS file sizes. 

1.0.30 - Added QSHIFSSIZ command to retrieve the file size and allocated size of an IFS file.

1.0.29 - Added QSHCALL procedure to the Service Program Wrapper. Service program name: QSHONISRV
Also created RPG test program for QSHCALL:
QSHONIPR03 - to test running a QShell/PASE commmand via QSHCALL from RPG and returning up to 10 parameter values to the calling RPG program.

1.0.28 - Created RPG Service Program Wrapper for QSHEXEC and QSHBASH commands. Service program name: QSHONISRV
Also created 2 RPG test programs:
QSHONIPR01 - to test running a QShell/PASE commmand via QSHEXEC from RPG and processing STDOUT outfile all from a single RPG program.
QSHONIPR02 - to test running a QShell/PASE commmand via QSHBASH from RPG and processing STDOUT outfile all from a single RPG program.

1.0.27 - Two new commands added: QSHCALL and QSHPYCALL to call Python or other open source and return parameters.

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 this install script if you want to run a single shell script to clone the repo and build the library.
https://github.com/richardschoen/QshOni/blob/master/getrepo-qshoni.sh

# Download the getrepo-qshoni.sh script or create it manually in your IFS. 
# 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.

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.14. 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

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:

/QOpenSys/pkgs/bin/wget https://github.com/richardschoen/QshOni/releases/download/V1.0.5/qshoni.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 qith QSHEXEC/QSHBASH

❗ If you experience delays running QShell Commands, it's probably related to your system DNS settings. Check out the following issue: #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 running so each run gets a fresh copy of QTEMP/STDOUTQSH. The QTEMP/STDOUTQSH temp file gets created automatically always, even if none of the switches such as: DSPSTDOUT, LOGSTDOUT, PRTSTDOUT or IFSSTDOUT are specified.

CMDLINE - Qsh/Pase command line sequence to run. Semicolons can be used to run multiple commands.

SETPKGPATH - Add the IBM i Open Source Package path to PATH environment variable by calling QSHPATH command before running QSH/PASE commands. Default = *YES.

DSPSTDOUT - Display the outfile contents. Nice when debugging.

LOGSTDOUT - Place STDOUT log entries into the current jobs job log. Use this if you want the log info in the IBM i joblog. All STDOUT entries are written as CPF message: QSS9898

PRTSTDOUT - Print STDOUT to a spool file. Use this if you want a spool file of the log output.

DLTSTDOUT - This option insures that the STDOUT IFS temp files get cleaned up after processing. All IFS log files get created in the /tmp/qsh directory.

IFSSTDOUT - Copy std output to an IFS file. Nice for aggregating log results to a file.

IFSFILE - IFS file for stdout results. Needs to be specified if IFSSTDOUT = *YES.

IFSOPT - IFS file option. *REPLACE = replace stdout IFS file. *ADD = Add to stdout IFS file.

CCSID - When using the iToolkit component for command access, I originally had some issues with CL commands not working correctly. However I don't currently remember exactly why. This may have been solved, however I recommend still passing a value of 37 unless you are in a non US country. If you set to *SAME, the CCSID will stay the same as your current job with no change.

PRTSPLF - This option holds the name of the spool file used when PRTSTDOUT = *YES. It's a nice way to customize the stdout log prints. Default = QSHEXECLOG

PRTUSRDTA - This option holds the name of the spool file user data used when PRTSTDOUT = *YES. ***Default = *NONE ***

PRTTXT - This option holds the name of the spool file print txt to be used when PRTSTDOUT = *YES. ***Default = *NONE ***

PRTHOLD - This option determines if the spool file is held if one is generated when PRTSTDOUT = *YES. ***Default = *YES ***

PRTOUTQ - This option determines the output queue where the spool file will generated to when PRTSTDOUT = *YES. ***Default = *SAME ***

OUTFILE - Output physical file to receive STDOUT from the QSH/PASE command. Default file: QTEMP/STDOUTQSH This output file always gets created and populated.

MBROPT - Output file option. Default: *REPLACE *REPLACE = replace outfile contents. *ADD = Add to outfile contents. Generally you should replace the file contents. If you want to append to a log file it's recommended to use the IFS output file option to write or append to an IFS file log. This is much more amenable to log readers or processors.

PASEJOBNAM - PASE fork thread job names. Set PASE_FORK_JOBNAME environment variable to set forked thread jobs to have a unique name other than: QP0ZSPWP which is the default. Set the value or *DEFAULT=QP0ZSPWP.

Using the QSHEXECSRC CL command to call a Qsh/Pase command sequence from a classic IBM i source member

The following example calls a QShell source member QSHELL01 stored in source file QSHONI/SOURCE to run the ls command to list files for the /tmp directory:

     QSHEXECSRC SRCFILE(QSHONI/SOURCE)
     SRCMBR(QSHELL01)      
     CMDPARM(' ')               
     DSPSTDOUT(*YES)         
     LOGSTDOUT(*NO)          
     PRTSTDOUT(*NO)          
     DLTSTDOUT(*YES)
     IFSSTDOUT(*NO)
     IFSFILE('/tmp/log.txt')
     IFSOPT(*REPLACE)
     PRTSPLF(QSHEXECLOG) 
     PRTUSRDTA(*NONE)    
     PRTTXT(*NONE)       
     RMVTMPSCR(*YES)            
     PROMPTCMD(*NO)

Sample QShell source member: QSHONI/SOURCE(QSHELL01) Type: TXT Text: QShell script to List Files in /tmp folder

cd /tmp
ls -l

QSHEXECSRC command parms

Overview - This CL command can be used to run a QSH/PASE command shell script from a classic source physical file member and log the results appropriately.

The use case would be for an app where you want to store your QShell/PASE/Python/PHP/Etc. scripts as part of your library source and execute those scripts directly from a source physical file.

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 running so each run gets a fresh copy of QTEMP/STDOUTQSH. The QTEMP/STDOUTQSH temp file gets created automatically always, even if none of the switches such as: DSPSTDOUT, LOGSTDOUT, PRTSTDOUT or IFSSTDOUT are specified.

SRCFILE - Source physical file where QShell/PASE script is stored.

SRCMBR - Source member name where QShell/PASE script is stored. Script is automatically copied to an IFS based temp file in IFS dir /tmp/qsh for execution. The IFS temp file is auto-deleted by default after it runs unless you specify *NO to the RMVTMPSCR parameter.

Changes to your script source members can be made usig via the SEU, RDi or VS Code editors.

CMDPARM - Command line parms to pass to the selected Qsh/Pase script that runs. If no parameters are needed simply pass ' ' for the CMDPARM value.

Parameters can be delimited with double quotes if needed.
Ex: "parm1" "parm2" "parm3"