Run CL commands from within your RPG application program.

Related to my article "V7R1 CL: Something for Everyone," published last month in an MC Special Issue, Avrohom N. sent me a note concerning an enhancement that would be a nice addition to RPG—namely, to be able to run CL commands directly from free-form RPG. The note goes on to point out that running user-created CL commands, with keywords to identify the purpose of parameters being passed to the command processing program (CPP)—rather than just parameter values as is done when calling a program—provides an easier to understand interface between programs.

As I have often needed to run a CL command from a RPG program, and I agree that command keywords could provide valuable assistance when trying to quickly understand a program call, and I am not aware of any RPG operation code or built-in to directly run CL commands, and last but not least, this column is "The API Corner," this article will look at how to run CL commands from within an RPG application program using system APIs.

There are actually several APIs that provide the ability to run a CL command from within an RPG (or any language for that matter) program. There is the Execute Command (QCMDEXC) API, which is documented here. There is the Execute a Command API system, which is compatible with the C language system function found on many other platforms. The documentation for the system API can be found in the ILE C/C++ Run-Time Library Functions manual located here. There is also the Process Commands (QCAPCMD) API, which supports several other options beyond simply running a CL command, with its documentation found here. In addition, there are other environment-specific methods available to you, such as the Execute Command (QCAEXEC) API documented with the QCMDEXC API and supporting the CL command syntax of the IBM S/38, REXX's command environment support, etc. These environment-specific alternatives will not be discussed further within this article.

All three of the previously mentioned APIs (QCMDEXC, system, and QCAPCMD) provide the basic function of running a CL command from within an RPG application program, so a reasonable question at this point might be "Are there reasons to choose one over the others"? In my mind there are. In reviewing the documentation for the various APIs, you may have noticed that the QCAPCMD API provides several features that are not available with the QCMDEXC or system APIs. The more obvious additional features, such as syntax-checking the command for a variety of environments (as opposed to running the command) and associating a CCSID to the command string, are not however currently needed as all we're interested in is simply running a CL command from within our current RPG application. So while it's nice to know the QCAPCMD API can provide these functions, they do not necessarily sway us to QCAPCMD over the other APIs. One not so obvious feature, however, is the Error code parameter, which is available only with the QCAPCMD API. When the CL command we want to run runs successfully, there isn't much difference in the APIs. When the CL command encounters a failure and we want to unconditionally end the RPG program, again there isn't much difference in the three APIs. But when the CL command we want to run encounters an error, and there are some errors we want the application to recover from and other errors for which we want to end the running of the RPG program, then the Error code parameter of QCAPCMD provides quite a bit of difference in terms of flexibility. And this additional flexibility is a difference that I often take advantage of to simplify my RPG applications.

The QCMDEXC API errors are returned as *ESCAPE messages that are logged to the job log, even if my RPG application program will handle the error situation (and therefore the message should be removed from the job log). The system API errors are always returned as an integer return value of positive 1 with the message ID of the underlying escape message returned by way of the external variable _EXCP_MSGID. When using the system API, the escape message is not written to the job log, leaving that responsibility up to my program if I elect to end the application due to the error situation. With the QCAPCMD API, you can have *ESCAPE messages sent, and logged in the job log, by setting the Bytes provided field of the Error code parameter to 0. Alternatively, by setting the Bytes provided field of the Error code parameter to 8 or greater, you can have the information related to the underlying escape message (bytes available to indicate if an error was encountered with the message ID and message data fields associated with the error) returned in the Error code parameter with no escape message logged to the job log. It is this ability to control the job log recording of escape messages based on how I anticipate handling error situations, and the direct access to message replacement data in the Error code parameter, that causes me to use the QCAPCMD API. And rather than sometimes using QCMDEXC, sometimes using system, and sometimes using QCAPCMD, I simply utilize QCAPCMD whenever I need to run a CL command from an RPG application program.

I'm out of space in the current article to start demonstrating how these APIs are actually used, but in the next column, we'll look at how to implement the three APIs as functions within a RPG application program.

Limitations

Before closing this column, I want to point out that the QCAPCMD, QCMDEXC, and system APIs do have one common limitation. Any CL command that is documented with the restriction that the command is valid only within a CL program or procedure will not be able to be run using any of the previously mentioned APIs. Some commands with this restriction are fairly obvious. For instance, it may not surprise you to find that CL commands such as DCL, DOFOR, SELECT, WHEN, and MONMSG cannot be run using the APIs. These functions would logically be done within the RPG program using definition specifications and RPG program logic with operation codes such as FOR, SELECT, WHEN, and On-ERROR within a MONITOR group.

Another set of CL commands with this limitation may, however, initially surprise you: commands that define a parameter as Return value (RTNVAL) *YES. These commands are generally retrieve type commands such as Retrieve Jobs Attributes (RTVJOBA) and Retrieve Object Description (RTVOBJD), where the retrieved information is returned directly to a CL variable, though the Change Variable (CHGVAR) command also uses RTNVAL(*YES) for the VAR parameter. If your RPG application program needs information typically accessed with a CL retrieve command, then you should use the equivalent APIs. In the case of RTVJOBA and RTVOBJD, these would be the Retrieve Job Information (QUSRJOBI) and Retrieve Object Description (QUSROBJD) APIs, respectively. As APIs are generally faster than the CL commands, and often return even more information, this should not present too much of a difficulty. Other retrieve type CL commands, such as Retrieve CL Source (RTVCLSRC) and Retrieve Configuration Source (RTVCFGSRC), which do not return information directly to CL variables, will work fine with the QCAPCMD, QCMDEXC, and system APIs. For a command such as CHGVAR, you can simply use the equivalent RPG operation.

Questions?

If you have any API questions, send them to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?