In the March 1993 issue of Midrange Computing, Ernie Malaga introduced an excellent way to process multiple commands in batch: the command queue. Using command queues allows you to submit more than one CL command to a batch job, something IBM’s SBMJOB command can’t handle. Until now, however, there was no easy way to resubmit a group of commands. The RTVCMDQ command presented in this article provides a powerful yet easy-to-use solution to that problem.

The AS/400 has been around for more than a decade and has seen thousands of enhancements. However, to this day, IBM has yet to provide a simple method for submitting multiple on-the-fly commands into batch. IBM’s Submit Job (SBMJOB) command allows only one command, and other IBM batch methods do not support processing commands on the fly. Therefore, we have the task of creating our own method to solve this challenge. So far, one of the best solutions has been the Submit to Command Queue (SBMCMDQ) and Start Command Queue (STRCMDQ) commands first presented in the article “Batch Job Runner” (MC, March 1993).

Retrieve from Command Queue (RTVCMDQ) is a powerful addition to the existing set of command queue commands. It provides an easy way to recall a set of commands previously submitted to a command queue. If you’re not familiar with command queue processing, you may find that SBMCMDQ and STRCMDQ are just the solutions you have always wanted but didn’t know existed. And now RTVCMDQ makes them easier than ever to use!

Blast to the Past

For those new to command queue processing, the following briefly describes this concept. (See the original 1993 article for a full explanation. Readers who don’t have that issue in hard copy may want to order the Midrange Computing ResourceCD. Code for that article is on the Web at www.midrangecomputing.com/mc/prog/93.)

A command queue “object” is really just a message queue object (type *MSGQ) in which each command string to be executed is stored as the text of a message. Commands are loaded into a command queue by using SBMCMDQ. Each execution of SBMCMDQ writes one command string to the command queue. After all desired commands have been

loaded, STRCMDQ is executed. STRCMDQ submits itself to batch and processes each command string found in the command queue one at a time. As each command is processed, it is removed and placed in a command queue history log (another message queue). Also placed in this log are all escape error messages that result from each executed command. Processing commands via a command queue does not require you to add source members or program objects to your system, making the command queue method a great alternative to writing quick, one-time CL programs.

However, using command queues has always had a drawback: Whenever you do want to process the same group of commands that you previously loaded into a command queue, you have to reload all commands one by one into the command queue. For example, let’s say that to compile the program MYPGM into library MYLIB, you first need to execute four Override with Database File (OVRDBF) commands so the compiler picks up the correct database file references. The four overrides and compile command are loaded into the command queue and submitted to batch. Oops, the compile listing shows an error (it happens to all of us). After fixing the source code, you must reenter all five commands into the command queue to resubmit the compile. Because reentering commands is always a pain, programmers often avoid the command queue method if there is any chance that the same group of commands is needed more than once.

Back to the Future

Fortunately, that drawback is now in the past. By using RTVCMDQ, you have the ability to retrieve any number of commands or groups of commands from the command queue history log and load them back into the command queue to be submitted, all in a single step! Because the order in which to execute commands is often crucial, RTVCMDQ always loads the retrieved commands in the exact order in which they appear in the command queue history log.

Although you can use RTVCMDQ to retrieve individual commands, its real power lies in its ability to retrieve and load whole groups of commands. That is why the parameter Retrieve type option (RTVTYPE) has a default value of *CMDGROUP. RTVCMDQ is not only powerful but also flexible in that you can specify the following conditions:

• A nonexistent command queue to receive retrieved commands (it will be created for you)

• The decision of whether the retrieved commands should be added to or replace commands that may already exist in the command queue

• The number of commands or groups of commands to retrieve into the command
• The decision of where in the command queue history log to begin retrieval (*BOTTOM or *TOP)

• The number of commands or groups to skip before starting the retrieval process The source code for the RTVCMDQ command object is on the Web at www.midrangecomputing.com/mc/99/05. Default names for the command queues (STDCMDQHST and STDCMDQ) follow those used in the original SBMCMDQ and STRCMDQ commands. When used with the defined defaults, RTVCMDQ retrieves the last group of commands found in the command queue history log named STDCMDQHST and places them into a cleared command queue named STDCMDQ. Only true command string “messages” are retrieved from the command queue history log; RTVCMDQ ignores all others.

Powerful, Easy Command Queues

Return to the example of submitting a compile with four required overrides. After the commands have been processed once and assuming you are using the default command queue names, you can reload that same group of commands into the command queue by executing the following command:

RTVCMDQ

queue

That’s it. And it is only the beginning of what RTVCMDQ can do! Suppose the source has compiled without errors and you want to run a test of the newly created MYLIB/MYPGM object with the same four overrides that the compile job used. As the following shows, you simply need to retrieve the four previously used overrides from the command queue and add the CALL for the program, and the command queue is ready to be submitted:

RTVCMDQ RTVTYPE(*COMMAND) +

RTVNBR(4) +

CMDQPOS(*BOTTOM 1)
SBMCMDQ CMD(CALL PGM(MYLIB/MYPGM))

If you find the test results aren’t what you expected, RTVCMDQ is again here to help. Because both groups of commands needed to compile and test MYPGM are now in the command queue history log, you can use RTVCMDQ to easily retrieve the necessary command groups to alternately compile and test MYPGM. To accomplish this, execute the following:

RTVCMDQ CMDQPOS(*BOTTOM 1)

By specifying (*BOTTOM 1) for the CMDQPOS (the CMDQ position to retrieve from), RTVCMDQ retrieves the next-to-last group of commands found in the command queue history log. It’s easy to see the power that RTVCMDQ adds to the command queue method of processing multiple commands in batch.

Details, Details

Also on the Web at www.midrangecomputing.com/mc/99/05 is the source code for the CL program CMDQ003CL. (003 is used because it follows in sequence after the two CL programs presented in the original 1993 article.) You can see that the beginning of the program deals with various initializing functions: breaking down parameter fields, verifying the existence of the qualified command queue history log, and creating and clearing the qualified command queue as needed.

With these functions completed, focus on a couple of areas worth explaining in detail: what RTVCMDQ considers to be a *CMDGROUP and how RTVCMDQ determines the correct position for beginning the retrieval process.

A *CMDGROUP is all commands in the command queue history log between two “Command queue XXXLIB/XXXCMDQ exhausted” messages (in which XXXLIB/XXXCMDQ is the qualified command queue name just processed). This message is placed in the command queue history log as part of the original STRCMDQ command. After STRCMDQ has processed and logged all commands found in a command queue, it adds one last message to the command queue history log, a CPF9898 completion message with the text “Command queue XXXLIB/XXXCMDQ exhausted.” Because this message is always the last one added to the command queue history log, determining where each group of commands starts and ends is easy. As RTVCMDQ retrieves messages from the command queue history log, any CPF9898 completion message encountered that begins with the text “Command queue” is interpreted as the end of the current *CMDGROUP and the beginning of another.

Determining the exact position in the command queue from which to begin retrieving is tricky, especially when *BOTTOM is specified in the CMDQPOS parameter. Because the retrieved commands must be loaded into the command queue in the same order in which they were originally loaded, the command queue history log must be read backwards until the first command to be retrieved is located. Looking at the logic for LOOP1, RTVCMDQ first executes Receive Message (RCVMSG) for the command queue history log with a Message Type (MSGTYPE) value of *LAST. (Note that this requires

special execution of the RCVMSG command, one without the Message Key (MSGKEY) parameter.) The command queue history log continues to be read backwards until the specified number of commands or groups to skip and retrieve has been read. After it has located the appropriate starting position, RTVCMDQ reads the command queue history log forward, retrieving the commands in correct order.

Regardless of the starting position specified, the actual work of retrieving and loading the commands into the command queue occurs inside the logic at LOOP2. The LOOP2 logic is similar to that of LOOP1, except that the command queue history log is read forward. After all of the requested commands have been loaded into the command queue, a completion message is sent showing the total number of individual commands that RTVCMDQ retrieved.

Try It; You’ll Like It

I consider RTVCMDQ the newly found “missing piece,” which completes and simplifies the command queue method of processing commands in batch. If you’ve never tried processing commands via a command queue or stopped using command queues because you grew tired of reentering the same commands, give the method a fresh try. Now that you have RTVCMDQ, you might just find yourself never writing another quick CL program again.