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: 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("E) 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(©RIGHT) 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(©RIGHT) VALUE(©RIGHT)
/* 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 /*
/* */ /* --------------------- 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.Upload source files strclrdr.cl-cmd and strclrdrc.clp to an IFS path on your IBM i server, e.g., ~/my-source-dir.
- 2.Change the current directory to your source directory, e.g., CHDIR DIR('~/chqs/miex/111').
- 3.Compile the STRCLRDR command, e.g., CRTFRMSTMF OBJ(STRCLRDR) CMD(CRTCMD) SRCSTMF('strclrdr.cl-cmd') PARM('pgm(*libl/strclrdrc)').
- 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 / 1 QUIMNDRV QSYS / 2 QUIMGFLW QSYS / 3 QUICMD QSYS /048D QUOCPP QPDA / QUOMAIN QPDA /05B1 4 QUOCMD QSYS /012D STRCLRDRC LSBIN 22500 / 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
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 queue—for 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' 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(' 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 ****** ******** 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 *MSGQ—for 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 commands—for 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 location—for 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.
LATEST COMMENTS
MC Press Online