20
Mon, May
3 New Articles

Simon's Solutions: Prepared to Be Surprised by QCMD?

APIs
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

Learn the practical techniques to take advantage of the IBM-supplied request processors.

 

In a shell environment (for example, a UNIX Shell environment, or the QShell or PASE Shell environment provided by IBM i), you can run a list of commands all at once by simply separating the commands by semicolon (;) operators. For example, to obtain an estimated running time of a time-consuming program, you can invoke the target program in a QShell or PASE Shell session via the following list of Shell commands:

date; system "call snail_run"; date

Similar utilities in the CL environment are the Start Database Reader (STRDBRDR) and the Submit Database Jobs (SBMDBJOB) commands that read a batch input stream from a database file and run the requested commands in a submitted batch job. However, they cannot be used to run requested CL commands interactively. In a post (Re: Interactive version of STRDBRDR) in the Midrange-L mailing list in 2002, Simon Coulter provided a perfect solution that allows users run a list of CL commands stored in a database file at once interactively. The mechanism of Simon's solution is quite straight forward, as quoted from Simon's original post: "Just read the source file, send each line as a request message, and then give control to QCMD."

If you're unfamiliar with request (*RQS) messages, you're probably astonished by this statement. If so, I hope the following sections of this article might fulfill your curiosity about *RQS messages, request processors, and ways to utilize the IBM-supplied request processors (QCMD and QCL) to ease your daily work.

  • The Start CL Reader (STRCLRDR) Command Provided by Simon
  • How Does a Request Processor Work?
  • An Example Request Processor That Processes Either CL Commands or SQL Statements
  • Another Example of Utilizing the IBM-Supplied Request Processors: A Simple Yet Practical Batch Machine

The Start CL Reader (STRCLRDR) Command Provided by Simon

In his 2002 post, Simon provided source of a CL command Start CL Reader (STRCLRDR) and the associated Command Processor Program (CPP) STRCLRDRC. The runnable source of the CL program STRCLRDRC and the STRCLRDR command are available at project i5/OS Programmer's Toolkit (i5toolkit) as strclrdrc.clp and strclrdr.cl-cmd, respectively.

The following is Simon's original post:

Re: Interactive version of STRDBRDR

   Subject: Re:   Interactive version of STRDBRDR

   From:   "Simon Coulter" <shc@xxxxxxxxxxxxxxxxx>;

   Date: Thu, 26   Sep 02 20:06:29 +1000

   Importance: Normal

   List-archive:   <http://archive.midrange.com/midrange-l/>;

Hello Joe,

You wrote:

>If I wanted to put a few CL commands into a source   member and just run them

>(kind of like old-fashioned OCL), can I do it? The last time I did this,

>many years ago, I used STRDBRDR, but that requires   submitting to batch. Can

>it be done interactively?

Yes. Just read the source file, send each line   as a request message, and                

then give control to   QCMD.

Here is my version.   I wrote this years ago and tidied it up just for you.

I'm sure you can write your own replacements for the   EXTQUALOBJ and STDERR

commands but if you want them too then let me know.

/* ** Start of specifications   ************************************************/

/* PARMS PGM(STRCLRDRC) ALLOW(*INTERACT *IPGM *IMOD   *IREXX)                 */

/*                                                                             */

/* Command name   . . . . . . : STRCLRDR                                     */

/*                                                                            */

/* Descriptive name   . . . . : Start CL Reader                               */

/*                                                                             */

/* Function . .   . . . . . . : To interpret a CL source member.             */

/*                                                                             */

/* Copyright:                                                                 */

/*   (C)   Copyright S.H. Coulter 1987, 2002. All rights reserved.             */

/*   (C)   Copyright FlyByNight Software. 1987, 2002. All rights reserved.     */

/*                                                                             */

/* External references:                                                       */

/*   Command   processor . . . : STRCLRDRC                                     */

/*                                                                             */

/*     Messages . . . . . . . :                                                 */

/*                                                                            */

/*   Help panel   group . . . :                                                 */

/*                                                                             */

/*     Programs . . . . . . . :                                              */

/*                                                                             */

/*   Files . . .   . . . . . . :                                                 */

/*                                                                             */

/*   Data   areas . . . . . . :                                                 */

/*                                                                             */

/* Notes:                                                                     */

/*   Dependencies   . . . . . :                                                 */

/*                                                                             */

/*     Restrictions . . . . . :                                                 */

/*                                                                          */

/*   Support . .   . . . . . . : shc@xxxxxxxxxxxxxxxxx                         */

/*                                                                             */

/* Change activity:                                                          */

/*                 Rlse &                                                       */

/* Flag Reason     Level Date   Pgmr         Comments                             */

/* ---- -------- ------ ------ ----------   -----------------------------------*/

/* $A0= D                 870228 SHC:       Initial coding   of command.         */

/* $A1= D                 920107 SHC:       Support both   S/38 and AS/400 syntax*/

/* $A2= D                 020926 SHC:       Remove dumb   defaults and make more */

/*                                           like an IBM command.               */

/*                                                                             */

/* ** End of specifications   **************************************************/

STRCLRDR:   CMD        PROMPT('Start CL Reader')

               PARM       KWD(SRCFILE) TYPE(Q1)   MIN(1) PROMPT('Source +

                         file')

               PARM       KWD(SRCMBR)   TYPE(*NAME) LEN(10) MIN(1) +

                         EXPR(*YES)   PROMPT('Member')

Q1:         QUAL       TYPE(*NAME) LEN(10) MIN(1) EXPR(*YES)

               QUAL       TYPE(*NAME) LEN(10)   DFT(*LIBL) +

                         SPCVAL((*LIBL)   (*CURLIB *CURLIB)) +

                         EXPR(*YES)   PROMPT('Library')

/* ** Start of specifications   ************************************************/

/*PARMS                                                                       */

/*                                                                             */

/* Module name . . . . . . . : STRCLRDRC                                     */

/*                                                                             */

/* Descriptive name   . . . . : Start CL Reader                               */

/*                                                                            */

/* Function . .   . . . . . . : Reads a CL source member and executes         */

/*                             each CL   statement by sending each line         */

/*                             as a *RQS   message to the *EXT message         */

/*                             queue of the job   and then calling the         */

/*                             command executor   to run them.                 */

/*                             Allows   interactive CL interpretation of         */

/*                            CL command groups   similar to STRDBRDR.       */

/*                                                                             */

/* Copyright:                                                                 */

/*   (C)   Copyright S.H. Coulter 1987, 2002. All rights reserved.             */

/*   (C)   Copyright FlyByNight Software. 1987, 2002. All rights reserved.     */

/*                                                                             */

/* Module type:                                                              */

/*   Processor .   . . . . . . : CLP                                           */

/*                                                                             */

/*   Module size   . . . . . . :                                              */

/*                                                                             */

/*     Attributes . . . . . . :                                                 */

/*                                                                            */

/* Entry:                                                                     */

/*   Entry point   . . . . . . : STRCLRDRC                                     */

/*                                                                             */

/* Purpose . . . . . . . . : (See   function)                                 */

/*                                                                             */

/*   Linkage . .   . . . . . . : CPP for STRCLRDR                             */

/*                                                                            */

/* Input . . . . . . . . . . : &QUALSRCF   - Qualified source file           */

/*                             &SRCMBR     - Member name                     */

/*                                                                          */

/* Output . . .   . . . . . . : *NONE                                         */

/*                                                                             */

/* External references:                                                    */

/*     Routines . . . . . . . :   STDERR     - Standard error   handler           */

/*                             EXTQUALOBJ -   Extract qualified object         */

/*                                                                            */

/*   Files . . .   . . . . . . :                                                 */

/*                                                                             */

/*   Data   areas . . . . . . :                                                 */

/*                                                                          */

/*   Control   blocks . . . . :                                                 */

/*                                                                             */

/*   References   from UIM . . :                                                 */

/*                                                                             */

/* Exits-- Normal   . . . . . : Return to NSI                                 */

/*     -- Error   . . . . . . : Resignal escape message to caller             */

/*                                                                             */

/* Messages:                                                                   */

/*   Generated .   . . . . . . : CPF9898 - Impromptu messages                 */

/*                                                                             */

/* Resignalled .   . . . . . : *ESCAPE messages                               */

/*                             *NOTIFY   messages                            */

/*                                                                             */

/*   Monitored .   . . . . . . : CPF9999 - Function check exceptions           */

/*                             CPF0864 - End of   file.                       */

/*                                                                          */

/* Macros/Includes . . . . . :                                                 */

/*                                                                             */

/* Data/Tables . . . . . . . :                                                 */

/*                                                                             */

/* Notes:                                                                     */

/*     Dependencies . . . . . : STDERR     - Standard error handler           */

/*                             EXTQUALOBJ -   Extract qualified object         */

/*                                                                             */

/*     Restrictions . . . . . :                                              */

/*                                                                             */

/*   Register   conventions . : N/A                                           */

/*                                                                            */

/*   Patch label   . . . . . . : N/A                                           */

/*                                                                             */

/*   Support . .   . . . . . . : shc@xxxxxxxxxxxxxxxx                         */

/*                                                                          */

/* Change activity:                                                           */

/*                 Rlse &                                                       */

/* Flag Reason     Level Date   Pgmr         Comments                             */

/* ---- -------- ------ ------ ----------   -----------------------------------*/

/* $A0= D                 870128 SHC:       Initial coding   of module.         */

/* $A1= D                 920107 SHC:       Support both   S/38 and AS/400 syntax*/

/* $A2= D                 020926 SHC:       Remove dumb   defaults and make more */

/*                                           like an IBM command.               */

/*                                                                            */

/* ** End of specifications   **************************************************/

STRCLRDRC: PGM         PARM(&QUALSRCF &SRCMBR)

/*                                                                   */

/* ---------------- Input Parameter Declarations   ----------------- */

/*                                                                   */

               DCL       VAR(&QUALSRCF)   TYPE(*CHAR) LEN(20)

                         /* Qualified source file                   */

             DCL       VAR(&SRCMBR) TYPE(*CHAR) LEN(10)

                         /* Source member name                     */

/*                                                                   */

/* ------------------- Program Declarations   ---------------------- */

/*                                                                   */

               DCLF       FILE(QCLSRC)

                         /* Source file template                   */

               DCL       VAR(&SRCF)   TYPE(*CHAR) LEN(10)

                         /* Source file                             */

               DCL       VAR(&SRCFLIB)   TYPE(*CHAR) LEN(10)

                         /* Source file library                     */

               DCL       VAR(&TYPE)   TYPE(*CHAR) LEN(1)

                         /* Source member type                     */

               DCL       VAR(&SRCTYPE)   TYPE(*CHAR) LEN(10)

                         /* Source member type                     */

               DCL       VAR(&ERROR)   TYPE(*LGL) LEN(1)

                         /* Error flag                             */

/*                                                                   */

/* ---------------- Mnemonic Value Declarations   ------------------ */

/*                                                                   */

            DCL       VAR(&BLANK) TYPE(*CHAR) LEN(1)   VALUE(X'40')

                         /* Mnemonic for 'blank'                   */

               DCL       VAR(&TRUE)   TYPE(*LGL) LEN(1) VALUE('1')

                         /* Mnemonic for 'true'                      */

               DCL       VAR(&FALSE)   TYPE(*LGL) LEN(1) VALUE('0')

                         /* Mnemonic for 'false'                   */

               DCL       VAR(&STAR)   TYPE(*CHAR) LEN(1) VALUE('*')

                         /* Mnemonic for 'asterisk'                 */

               DCL       VAR(&QUOTE)   TYPE(*CHAR) LEN(1) VALUE('''')

                         /* Mnemonic for 'quote'                   */

               DCL       VAR(&BATCH)   TYPE(*CHAR) LEN(1) VALUE('0')

                         /* Mnemonic for 'batch job'               */

               DCL       VAR(&INTER)   TYPE(*CHAR) LEN(1) VALUE('1')

                         /* Mnemonic for 'interactive job'         */

               DCL       VAR(&ZERO)   TYPE(*DEC) LEN(1 0) VALUE(0)

                        /* Mnemonic for 'zero'                     */

               DCL       VAR(&HEX00)   TYPE(*CHAR) LEN(2) VALUE(X'0000')

                         /* Mnemonic for 'binary zero'             */

/*                                                                  */

/* ------------------- Copyright Declarations   -------------------- */

/*                                                                   */

               DCL       VAR(&COPYRIGHT)   TYPE(*CHAR) LEN(80) +

                         VALUE('Copyright   (C) FlyByNight Software. +

                         1987, 2002')

/*                                                                   */

/* -------------- Global Message Monitor Intercept   --------------- */

/*                                                                  */

               MONMSG     MSGID(CPF9999)   EXEC(GOTO CMDLBL(FAILED))

/*                                                                   */

/* ---------- Force Copyright Notice in Executable Code   ---------- */

/*                                                                */

               CHGVAR     VAR(&COPYRIGHT)   VALUE(&COPYRIGHT)

             /*   Initialise error indicator                         */

               CHGVAR     VAR(&ERROR)   VALUE(&FALSE)

             /*   Find out job type. Force SBMDBJOB in batch job.   */

             /*   Belts and braces code - CDO not allowed in batch. */

               RTVJOBA   TYPE(&TYPE)

               IF         COND(&TYPE *EQ   '0') THEN(DO)

                 SNDPGMMSG MSGID(CPF9898)   MSGF(QCPFMSG) MSGDTA('STRCLRDR +

                           is only valid in   an interactive job. Use +

                           SBMDBJOB for   batch execution') +

                           MSGTYPE(*ESCAPE)

               ENDDO

             /*   Split out the qualified source file names.         */

               EXTQUALOBJ QUALOBJ(&QUALSRCF) OBJ(&SRCF) LIB(&SRCFLIB)

             /*   Ensure the source member exists and can be read.   */

               CHKOBJ       OBJ(&SRCFLIB/&SRCF) OBJTYPE(*FILE) MBR(&SRCMBR) +

                            AUT(*USE)

             /*   Check that source type is valid for CL interpreter */

               RTVMBRD     FILE(&SRCFLIB/&SRCF) MBR(&SRCMBR) SRCTYPE(&SRCTYPE)

               IF         COND( (&SRCTYPE   *NE 'CL')   *AND +

                             (&SRCTYPE   *NE 'CL38') *AND +

                             (&SRCTYPE   *NE 'CLP') *AND +

                             (&SRCTYPE   *NE 'CLP38') *AND +

                             (&SRCTYPE   *NE 'CLLE') ) THEN(DO)

               SNDPGMMSG MSGID(CPF9898)   MSGF(QCPFMSG) MSGDTA('Source +

                         type of member'   *BCAT &SRCMBR *BCAT 'in +

                         file' *BCAT   &SRCF *BCAT 'in' *BCAT +

                         &SRCFLIB *BCAT   'must be CL, CL38, CLP, +

                         CLP38, or CLLE')   MSGTYPE(*ESCAPE)

               ENDDO

             /*   Point to the correct source member.               */

               OVRDBF     FILE(QCLSRC)   TOFILE(&SRCFLIB/&SRCF) MBR(&SRCMBR)

             /*   Read each record in the source member.             */

READ:       RCVF

               MONMSG     MSGID(CPF0864)   EXEC(DO)

                 RCVMSG     MSGTYPE(*LAST)

                 GOTO CMDLBL(EOF)

               ENDDO

             /*   Send the command to the external queue as a       */

               /*   request message.                                 */

               IF         COND(&SRCDTA *NE   &BLANK) THEN(DO)

                 SNDPGMMSG MSG(&SRCDTA)   TOPGMQ(*EXT) MSGTYPE(*RQS)

               ENDDO

               GOTO       CMDLBL(READ) /* Get   the next command       */

EOF:       DLTOVR     FILE(QCLSRC)

             /*   Send message to return control to the module       */

             /*   after all source statements have been executed.   */

               SNDPGMMSG MSG(RETURN)   TOPGMQ(*EXT) MSGTYPE(*RQS)

             /*   Execute the request messages                       */

               /*   -- QCL is used for   System/38 commands           */

               IF         COND((&SRCTYPE   *EQ 'CL38') *OR +

                             (&SRCTYPE   *EQ 'CLP38')) THEN(DO)

              CALL         PGM(QCL)

               ENDDO

               /*   -- QCMD is used for AS/400   commands             */

               ELSE       CMD(DO)

                 CALL       PGM(QCMD)

               ENDDO

/*                                                                  */

/* -------------------- Send User a Message   ---------------------- */

/*                                                                   */

             /*   Send completion message. This does not guarantee   */

             /*   SUCCESSFUL completion of all commands, only that   */

             /*   the file was read and statements were processed.   */

               SNDPGMMSG MSGID(CPF9898)   MSGF(QCPFMSG) +

                         MSGDTA('Commands in   member' *BCAT &SRCMBR +

                          *BCAT 'in file' *BCAT   &SRCF *BCAT 'in' +

                         *BCAT &SRCFLIB   *BCAT 'completed') MSGTYPE(*COMP)

               SNDPGMMSG MSGID(CPF9898)   MSGF(QCPFMSG) MSGDTA('Check +

                         low-level messages   for any errors +

                          encountered')   MSGTYPE(*COMP)

EXIT:       RETURN     /* Normal   end of program                   */

/*                                                                   */

/* --------------------- Exception Routine   ----------------------- */

/*                                                                   */

FAILED:     STDERR     PGMTYPE(*CPP)

               MONMSG     MSGID(CPF9999) /*   Just in case             */

STRCLRDRX: ENDPGM

Regards,

Simon Coulter.

As shown above, the STRCLRDR command accepts a qualified database file name and a member name, reads the target file member, and sends each record as a request message (*RQS) to the external message queue (*EXT) of the job. Finally, it passes control to one of the IBM-supplied request processors according to the source type of the specified file member, the QCMD program for the IBM command environment, or the QCL program for the System/38 command environment. Note that before invoking QCMD or QCL, an additional request message, the RETURN command, is sent to the *EXT message queue to tell the request processor to quit after processing all the request messages. Without the RETURN command, the request processor will display the Command Entry display and wait for further commands entered by the user. (When a command is entered, it is placed on the *EXT message queue as a request message.)

Compile the STRCLRDR command and its CPP from strclrdr.cl-cmd and strclrdrc.clp, respectively. For example, when building from IFS stream source files, you might follow these steps:

  1. 1.Upload source files strclrdr.cl-cmd and strclrdrc.clp to an IFS path on your IBM i server, e.g., ~/my-source-dir.
  2. 2.Change the current directory to your source directory, e.g., CHDIR DIR('~/chqs/miex/111').
  3. 3.Compile the STRCLRDR command, e.g., CRTFRMSTMF OBJ(STRCLRDR) CMD(CRTCMD) SRCSTMF('strclrdr.cl-cmd') PARM('pgm(*libl/strclrdrc)').
  4. 4.Compile STRCLRDR's CPP, e.g., CRTFRMSTMF OBJ(STRCLRDRC) CMD(CRTCLPGM) SRCSTMF(strclrdrc.clp).

The CRTFRMSTMF (Create Object from STMF) command is a utility that allows you build IBM i objects such as OPM CL programs, CL commands, or Panel Group (*PNLGRP) objects from IFS source whose corresponding native building commands do not support IFS source. You may also upload the source files to the /QSYS.LIB file system and compile them via the CRTCMD and CRTCLPGM commands directly.

To test the STRCLRDR command, you may prepare a source member, say SRCLIB/SRCF,CMDS, with source type CL38, containing CL commands to execute.

   SNDMSG 'HELLO' +

           *SYSOPR

   DLYJOB 100

   DLTPGM NOSUCHONE.NOSUCHLIB

   SNDMSG 'TIME TO QUIT' *SYSOPR

Invoke the STRCLRDR command like this:

STRCLRDR SRCFILE(SRCLIB/SRCF) SRCMBR(CMDS)

Since the source type of SRCLIB/SRCF,CMDS is CL38, QCL will be invoked as the request processor. After issuing the above-shown STRCLRDR command, check the call stack of your interactive job. You can find QCL near the end of the call stack; it's marked as a request processor with the currently largest request level value. Here's an example:

Type Program                 Statement         Procedure

       QCMD       QSYS                     /0512

       QUICMENU   QSYS                     /00C1

   1   QUIMNDRV   QSYS                     /060C

   2 QUIMGFLW   QSYS                     /04C8

   3   QUICMD     QSYS                     /048D

       QUOCPP     QPDA                     /07A8

       QUOMAIN   QPDA                     /05B1

   4   QUOCMD     QSYS                     /012D

       STRCLRDRC LSBIN         22500     /00A1

   5 QCL         QSYS                     /0166

       QWCDLYJB   QSYS                     /0030

Check the job log of your interactive job. You can find out what's going on with the requested commands. For example:

5 > SNDMSG 'HELLO' +

5   >       *SYSOPR

5>>   DLYJOB 100

..   DLTPGM NOSUCHONE.NOSUCHLIB

..   SNDMSG 'TIME TO QUIT' *SYSOPR

..   RETURN

Pay attention to the above-shown example job log, where:

  • 5 is the current request level
  • A greater-than symbol (>) precedes a processed request, a double greater-than (>>)precedes the current request being processed, and a double period (..) precedes a request to process.

As an experienced IBM i developer, you might be very familiar with the QCMD program and its counterpart QCL for the System/38 command environment. Now, you've also seen how handy it is to utilize QCMD and QCL as request processors to process CL commands sent as request messages to the *EXT message queue.

How Does a Request Processor Work?

 

Generally, a request processor (a program or a procedure) receives request messages from the external message queue (*EXT) of the job, interprets each request according to a specific predefined syntax, executes the requested function, and diagnoses any errors. For example, CL commands are requests that are received and processed by the IBM-supplied CL processor QCMD for the IBM i command environment and by QCL for the System/38 command environment. A custom request processor can define its own syntax. For example, an SQL request processor would expect SQL statements as its input requests. Details about the working mechanism of a request processor can be found in the following Web pages in the Information Center: Writing request-processor procedures and programs and Receiving request messages.

For simplicity, I'll list the common tasks that a request processor should perform.

First, a program or a procedure becomes a request processor after successfully receiving a request message (*RQS) via either a RCVMSG PGMQ(*EXT) MSGTYPE(*RQS) command or the Receive Program Message (QMHRCVPM) API from the external message queue (*EXT) of a job. For example:

RCVMSG PGMQ(*EXT)

       MSGTYPE(*RQS)

       RMV(*NO)

       KEYVAR(&MK)

       MSG(&CMDSTR)

       MSGLEN(&LEN)

When any request message is received, it is moved (actually, it is removed and resent) to the call message queue of the procedure or program that specified the RCVMSG command. Therefore, the correct call message queue must be used later when the message is removed. You must specify RMV(*NO) on the RCVMSG command because the procedure or program is not a request processor if the request message is removed from the call message queue. If there is no request message on *EXT, the Command Entry display is shown. The display station user enters a command on the display. When the command is entered, it is placed on *EXT as a request message.

Second, a request processor validates and interprets the received request according to request processor?specific syntax and processes the request. For example, to validate and process a request as a CL command, you can call the Process Commands (QCAPCMD) API and specify the message reference key in order to have the command analyzer process a request message. You can get the message reference key when you receive the request message. The QCAPCMD API will update the request message in the job log and add any new value supplied. QCAPCMD also hides any parameter values, such as passwords, that are to hidden in the job log.

The request processor remains a request processor until it ends (either normally or abnormally) or until a RMVMSG command is run to remove all the request messages from the request processor's call message queuefor example, a RMVMSG PGMQ(*SAME (*)) CLEAR(*ALL) command.

Note that a request processor should monitor for request-check (CPF9901) and function-check (CPF9999) escape messages, as well as CPF1907 (end request) and CPF2415 (which indicates that the user pressed F3 or F12 on the Command Entry display) escape messages.

An Example Request Processor That Processes Either CL Commands or SQL Statements

Here's an example request processor, rqs03.clp, which processes either CL commands or SQL statements following the steps mentioned above. RQS03 regards a request message starting with a percent symbol (%) as an SQL statement and executes the SQL statement in a submitted batch job via the QShell db2 utility.

             /*************************************************************/

             /* @file rqs03.clp                                           */

             /* Example request processor   that supports CL and SQL.       */

               /*************************************************************/

             DCL       VAR(&MK) TYPE(*CHAR) LEN(4)

             DCL       VAR(&LEN) TYPE(*DEC) LEN(5 0)

             DCL       VAR(&SQLSTMT) TYPE(*CHAR)   LEN(256)

             DCL       VAR(&CPOP) TYPE(*CHAR) LEN(20) +

                        VALUE(X'00000000F1F2F0000000000000000000000+

                         00000')

             DCL       VAR(&PRCTYP) TYPE(*INT)   STG(*DEFINED) LEN(4) +

                         DEFVAR(&CPOP 1)   /* Command process type. +

                         0 = run command   directly */

             DCL       VAR(&DBCSOPT) TYPE(*CHAR)   STG(*DEFINED) +

                         LEN(1)   DEFVAR(&CPOP 5) /* DBCS data +

                         handling. '1' =   handle DBCS data */

             DCL       VAR(&PMTOPT) TYPE(*CHAR)   STG(*DEFINED) +

                         LEN(1)   DEFVAR(&CPOP 6) /* Prompter action. */

             DCL       VAR(&CMDSNX) TYPE(*CHAR)   STG(*DEFINED) +

                         LEN(1)   DEFVAR(&CPOP 7) /* Command string +

                         syntax. '0' = using   system syntax +

                         (instead of S/38   syntax) */

             DCL       VAR(&RQSMSGKEY) TYPE(*CHAR)   STG(*DEFINED) +

                         LEN(4)   DEFVAR(&CPOP 8) /* Message +

                         retrieve key identifying   a request message. */

             DCL       VAR(&CMDCCSID) TYPE(*INT)   STG(*DEFINED) +

                         LEN(4)   DEFVAR(&CPOP 12) /* CCSID of +

                         command string. 0 =   use job CCSID */

             DCL       VAR(&CPOPRSVD) TYPE(*CHAR)   STG(*DEFINED) +

                         LEN(5)   DEFVAR(&CPOP 16)

             DCL       VAR(&QUSEC) TYPE(*CHAR) LEN(16) +

                           VALUE(X'00000000000000000000000000000000')

             DCL       VAR(&CMDSTR) TYPE(*CHAR) LEN(256)

             DCL       VAR(&CMDSTRLEN) TYPE(*INT) LEN(4)   VALUE(2)

             DCL       VAR(&CPOPLEN) TYPE(*INT) LEN(4)   VALUE(20)

             DCL       VAR(&CPOPFMT) TYPE(*CHAR) LEN(8)   +

                         VALUE('CPOP0100')

            DCL       VAR(&CMDRTN) TYPE(*CHAR) LEN(256)

             DCL       VAR(&CMDRTNLEN) TYPE(*INT) LEN(4)   VALUE(256)

             DCL       VAR(&CMDRRLEN) TYPE(*INT) LEN(4)

             MONMSG     MSGID(CPF1907 CPF2415) EXEC(GOTO +

                          CMDLBL(QUIT)) /* CPF1907=End   request, +

                         CPF2415=F3 or F12.   Time to quit */

/* 1) Receive a *RQS   message from message queue *EXT */

READ:         RCVMSG     PGMQ(*EXT)   MSGTYPE(*RQS) RMV(*NO) +

                         KEYVAR(&MK)   MSG(&CMDSTR) MSGLEN(&LEN)

/* 2) Process a request */

             IF         COND(%SST(&CMDSTR 1 1) *EQ '%')   THEN(DO)

                 CHGVAR %SST(&CMDSTR 1 1)   ' '

                 CHGVAR     VAR(&SQLSTMT) VALUE('db2 "'   *CAT &CMDSTR +

                              *TCAT '"')

                 SBMJOB     CMD(STRQSH CMD(&SQLSTMT))   JOB(PRC_SQL)

             ENDDO     /* END OF SQL PROCESSING */

             ELSE       CMD(DO)

                 CHGVAR     VAR(&RQSMSGKEY) VALUE(&MK)

                 CHGVAR     VAR(&CMDSTRLEN) VALUE(&LEN)

                 CALL       PGM(QCAPCMD) PARM(&CMDSTR   &CMDSTRLEN &CPOP +

                             &CPOPLEN   &CPOPFMT &CMDRTN &CMDRTNLEN +

                             &CMDRRLEN   &QUSEC)

                 MONMSG     MSGID(CPF9901) EXEC(RCLRSC) /* Request   check */

                 MONMSG     MSGID(CPF9999) EXEC(RCLRSC) /* Function   +

                             check */

             ENDDO     /* END OF CL PROCESSING */

             GOTO       CMDLBL(READ)

/* 3) Clean-up */

QUIT:         RMVMSG     PGMQ(*SAME (*))   CLEAR(*ALL)

             SNDPGMMSG MSG('Farewell :p')

BANG:         ENDPGM

Call RQS03 and enter the following commands:

   > % CREATE TABLE   QGPL.WINTER( WDATE DATE, WTEMP DECIMAL(3,0), WRMRK CHAR(32))

     Job 553723/LJL/PRC_SQL submitted to job   queue QBATCH in library QGPL.  

   > % INSERT INTO   QGPL.WINTER VALUES('2012-12-01', 5, 'A nice   Saturday')    

     Job 553726/LJL/PRC_SQL submitted to job   queue QBATCH in library QGPL.  

   > RUNQRY *N WINTER

The output might look like the following:

                                 Display   Report                              

                                               Report width . . . . . :     51

Position to line . . . . .             Shift to column . . . . . .      

Line     ....+....1....+....2....+....3....+....4....+....5.                  

       WDATE       WTEMP   WRMRK                                              

000001 2012-12-01     5   A nice Saturday                                  

****** ******** End of report ********                                    

Another Example of Utilizing the IBM-Supplied Request Processors: A Simple Yet Practical Batch Machine


As an addition example of using QCMD and QCL, I'd like to show you a practical batch machine program, RQS01, a CL program containing merely less than 10 lines of code. To start the batch machine, you simply submit a batch job that calls RQS01, which in turn receives incoming requests from a Message Queue (*MSGQ) object, BCHMCH, and executes the requested CL commands one by one. Since rqs01 accepts requests via a *MSGQ object, a client of this batch machine program can be any program or user that is authorized to the *MSGQfor example, an operator who issues a SNDMSG TOMSGQ(BCHMCH) command, or a Java program running on a PC that accesses BCHMCH and sends a message to it via JT/Open (aka IBM Toolbox for Java).

The source for RQS01, rqs01.clp, is the following:

             DCL       VAR(&CMD) TYPE(*CHAR) LEN(1000)

             RCVMSG     MSGQ(BCHMCH) MSGTYPE(*ANY) WAIT(*MAX) +

                         RMV(*YES)   MSG(&CMD)                               /* [1] */

             IF         COND(&CMD *EQ 'QUIT') THEN(GOTO   CMDLBL(ENDPGM))   /* [2] */

             SNDPGMMSG MSG(&CMD) TOPGMQ(*EXT)   MSGTYPE(*RQS)             /* [3] */

             SNDPGMMSG MSG('CALL RQS01') TOPGMQ(*EXT)   MSGTYPE(*RQS)     /* [4] */

             RETURN                                                         /* [5] */

ENDPGM:       SNDMSG     MSG('Batch machine ended.')   TOMSGQ(*SYSOPR)

Notes:

[1] Receive an input request from *MSGQ BCHMCH.

[2] If character string 'QUIT' is received, say farewell and quit.

[3] Send the requested command as a request message to the *EXT message queue so that QCMD will see and process the requested command after control being returned to it.

[4] Send another request message, CALL RQS01, to *EXT. This way, RQS01 will be invoked again each time after a requested command is processed by QCMD.

[5] Now, pass control back to QCMD via the RETURN command and let QCMD process the previously sent two request messages.

Before actually running the batch machine program, a couple of prerequisite operations are needed:

  • Create message queue BCHMCH from which the batch machine program receives requested CL commandsfor example, CRTMSGQ BCHMCH.
  • Prepare a job description (*JOBD) object for the batch machine job. A batch job ends when the request processing program QCMD or QCL encounters an escape message whose severity is equal to or greater than the End Severity (ENDSEV) value of the batch job. To avoid the batch machine job ending due to an escape message, you should create a *JOBD for the batch machine job with the ENDSEV parameter set to a value higher than the default value 30. For example, CRTJOBD JOBD(NEVEREND) ENDSEV(99).

Now, start the batch machine by issuing a Submit Job (SBMJOB) command like this:

SBMJOB CMD(CALL PGM(RQS01)) JOB(BCHMCH) JOBD(NEVEREND)

To test the batch machine, you may let it say Hello to your interactive job via a Send Message (SNDMSG) command like this:

   SNDMSG MSG('SNDBRKMSG MSG(HELLO)   TOMSGQ(ME) MSGTYPE(*INQ)')

     TOMSGQ(BCHMCH)

Here, ME should be replaced by the actual name of the workstation message queue of your interactive job.

Also, you can issue requested CL commands to the batch machine from a remote locationfor example, via the Access Classes provided by the IBM Toolbox for Java. The following Java program, rqs02.java, can be used to send CL commands to the batch machine.

import   com.ibm.as400.access.*;

public class rqs02 {

   public static void main(String[] args) {

       if(args.length == 0) {

           System.out.println("usage:   java rqs02 cl-cmd");

           System.exit(1);

       }

       MessageQueue bchmch =

           new MessageQueue(new   AS400("system-name", "user-name", "password"),

                            "/qsys.lib/*libl.lib/bchmch.msgq");

       try {

             bchmch.sendInformational(args[0]);

       } catch(Exception e) {

           System.out.println("Oops!   " + e.getMessage());

       }

       System.out.println("Command:   " + args[0]);

   }

}

Compile rqs02.java and run it:

   java rqs02 "DSPLIB QGPL"

Then check the resulting spooled file printed by the batch machine job.

To stop the batch machine, simply order it to 'QUIT' like so:

SNDMSG MSG(QUIT) TOMSGQ(BCHMCH)

About Simon's Solutions

This series of articles memorializes Simon Coulter, an outstanding IBM i expert who contributed so much to the prosperity of the IBM i platform. Loved by many developers from the IBM i community, he was one of the giants in the industry, on whose shoulders others could stand and reach for new heights. I deeply appreciate Gwen Hanna, Simon's partner, for providing the biography of Simon at the end of the first article of this series.

Many thanks to David Gibbs, who has been running the mailing lists at Midrange.com for many years and has accumulated a vast treasure trove of knowledge for IBM i developers around the world.

I also appreciate Jon Paris and Susan Gantner, who ran a touching blog article for Simon: Happy Memories of a Good Friend.

I appreciate Victoria Mack, executive editor of MC Press Online, whose hard work has made it possible for each of the Simon's Solutions articles to be available to you, the readers.

Junlei Li

Junlei Li is a programmer from Tianjin, China, with 10 years of experience in software design and programming. Junlei Li began programming under i5/OS (formerly known as AS/400, iSeries) in late 2005. He is familiar with most programming languages available on i5/OS—from special-purpose languages such as OPM/ILE RPG to CL to general-purpose languages such as C, C++, Java; from strong-typed languages to script languages such as QShell and REXX. One of his favorite programming languages on i5/OS is machine interface (MI) instructions, through which one can discover some of the internal behaviors of i5/OS and some of the highlights of i5/OS in terms of operating system design.

 

Junlei Li's Web site is http://i5toolkit.sourceforge.net/, where his open-source project i5/OS Programmer's Toolkit (https://sourceforge.net/projects/i5toolkit/) is documented.

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$0.00 Raised:
$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: