Example CLP to monitor and retrieve Qshell message

This article contains an example CLP to monitor and retrieve Qshell messages.

                              
This example runs a Qshell cmd to retrieve the number of lines in a text file.  
If the IFS file is not found then qshell will log a message similar to this:   
001-0023 Error found opening file /home/someuser/test.txt.                        
                                                                                
When doing this in qshell command line the stdout will display the output to the C runtime terminal session. This is the default value.       
If trying to emulate this in a CL program then the Qshell messages (stdout/strerr) gets thrown away and

any output that is produced will not be posted in the  job's program message queue.               
Since the QSHELL environment will log messages to the terminal,                 
you want to control this by setting environment variable QIBM_QSH_CMD_OUTPUT.   
This variable controls where the messages are logged.                           
For example QIBM_QSH_CMD_OUTPUT can set the IFS file where the stdout/stderr messages get written to.                                                        
This  program reads the IFS file to extract the message details.                
Reading an IFS file in a CLP program is accomplished by using SQL QSYS2.IFS_READ table function.                                     
The contents of the IFS file are copied into a regular native DB file and the CL can open and read the native file with ease.                         
                                                                                
In order to compile this CL file SOMELIB/QSHERROR has to exist.                 
Use SQL to create the file                                                      
CREATE TABLE SOMELIB.QSHERROR ( QSH_ERR FOR "QSHERR" CHAR(100) NOT NULL) ;  

Example CLP Source SHELLCL:

         PGM        PARM(&FILENAME)
         DCL        VAR(&FILENAME) TYPE(*CHAR) LEN(30)
         DCL        VAR(&MSGDTA) TYPE(*CHAR) LEN(256)
         DCL        VAR(&MSGID) TYPE(*CHAR) LEN(7)
         DCL        VAR(&EXITSTS) TYPE(*CHAR) LEN(4)
         DCL        VAR(&COUNT) TYPE(*CHAR) LEN(100)
         DCL        VAR(&STATUS) TYPE(*DEC) LEN(10 0)
         DCL        VAR(&SCRIPT) TYPE(*CHAR) LEN(200)
         DCLF       FILE(SOMELIB/QSHERROR)
         ADDENVVAR  ENVVAR(QIBM_QSH_CMD_ESCAPE_MSG) VALUE('Y') REPLACE(*YES)
         ADDENVVAR  ENVVAR(QIBM_QSH_CMD_OUTPUT) VALUE('FILE=/tmp/qsherror.txt') LEVEL(*JOB) +
                      REPLACE(*YES)
         RMVLNK     OBJLNK('/tmp/qsherror.txt')
         MONMSG     MSGID(CPFA0A9) /* Object not found */

         DLTDTAARA  DTAARA(SOMELIB/TOSHTEST)
         MONMSG     CPF2105
         CRTDTAARA  DTAARA(SOMELIB/TOSHTEST) TYPE(*CHAR) LEN(50)

         CHGVAR     VAR(&SCRIPT) VALUE('wc -l /home/someuser/' *TCAT %TRIM(&FILENAME) *TCAT ' +
                      | datarea -w /qsys.lib/somelib.lib/toshtest.dtaara')
         QSH        CMD(&SCRIPT)
         MONMSG     MSGID(QSH0005) EXEC(DO)
            RCVMSG     MSGTYPE(*LAST) RMV(*NO) MSGDTA(&MSGDTA) MSGID(&MSGID)
            CHGVAR     VAR(&EXITSTS) VALUE(%SST(&MSGDTA 1 4))
            CHGVAR     VAR(&STATUS) VALUE(%BIN(&EXITSTS))
         ENDDO
         IF         COND(&STATUS *EQ 0) THEN(DO) /* WHEN SUCCESSFUL */
            RTVDTAARA  DTAARA(SOMELIB/TOSHTEST (1 8)) RTNVAR(&COUNT)
            SNDPGMMSG  MSG('The number of records: ' *BCAT %TRIM(&COUNT))
         ENDDO
         ELSE       CMD(DO)
            CLRPFM     FILE(SOMELIB/QSHERROR)
            MONMSG     MSGID(CPF2105) /* Object &1 in &2 type *&3 not found */
            RUNSQL     SQL('CREATE OR REPLACE table SOMELIB.QSHERROR (QSHERR) AS (SELECT +
                         cast(LINE as char(100)) FROM TABLE(QSYS2.IFS_READ(PATH_NAME => +
                         ''/tmp/qsherror.txt''))) WITH DATA ON REPLACE DELETE ROWS') +
                         COMMIT(*NONE) NAMING(*SQL)
 /* Above RUNSQL creates a new QSHERROR file , and OVRDBF  LVLCHK(*NO) will prevent CPF4131   */
            OVRDBF     FILE(QSHERROR) LVLCHK(*NO)
            RCVF
            CHGVAR     VAR(&COUNT) VALUE(%TRIM(&QSHERR))
            SNDPGMMSG  MSG('QSH0005 RTNCDE : ' *BCAT %CHAR(&STATUS))
            SNDPGMMSG  MSG('The error details: ' *BCAT &COUNT)
         ENDDO
         ENDPGM      

The IFS file for this example resides in /home/someuser/TEST.TXT

Run the CL from command line:

 Type command, press Enter.   
 > call shellcl 'test.txt'                         
  Environment variable added.                     
  Environment variable added.                     
  Link removed.                                   
  Object TOSHTEST in SOMELIB type *DTAARA deleted.
  Data area TOSHTEST created in library SOMELIB.  
  Command ended normally with exit status 0.      
  The number of records: 3                        

Now test the example by passing an IFS file that does not exist:
 > call shellcl 'testy.txt'                                 
   Environment variable added.                              
   Environment variable added.                              
   Link removed.                                            
   Object TOSHTEST in SOMELIB type *DTAARA deleted.         
   Data area TOSHTEST created in library SOMELIB.           
   Command ended normally with exit status 1.               
   Member QSHERROR file QSHERROR in SOMELIB cleared.        
   Table QSHERROR in SOMELIB created but was not journaled. 
   QSH0005 RTNCDE : 1                                       
   The error details: wc: 001-0023 Error found opening file 
     /home/someuser/testy.txt. No such path or directory.   
                                                            

The message in red text is 
Message ID . . . . . . :   QSH0005       Severity . . . . . . . :   00      
Message type . . . . . :   Escape       
Message . . . . :   Command ended normally with exit status 1.  

The CLP is monitoring for this message ID and checks if the Qshell command was successful or not.