What is a command on the iSeries? It is an object of type *CMD. But more important than that, it is a program interface designed to make calling a program simpler for the user.
iSeries administrators use commands such as WRKSPLF (Work with Spool Files), WRKWTR (Work with Writers) and WRKACTJOB (Work with Active Jobs) almost daily. Those commands in particular, and all iSeries commands in general, allow us to implicitly call an underlying program called the command processing program (CPP).
Specifically, commands allow us to specify the parameters to the CPP using an easy-to-use "prompt-able" interface. When the parameters of a program become numerous and/or complicated, a command interface for the program alleviates the need to remember all the details of the parameters. Commands also provide a number of validity-checking options so parameters can be validated before the program is actually called.
Understanding the basics of the command definition language
Command objects are created using a special language called the command definition language. Command definition statements are entered into a source member using SEU just as program code is. The default source file name is QCMDSRC, and the appropriate member type to use is CMD.
There are six command definition statements. We will cover the three most frequently used , which themselves can be used to create all but the most complicated commands. The three basic command definition statements are as follows:
- CMD. The CMD statement must be the first statement in the source member. Its main purpose is to introduce the command definition. It is also used to specify the prompt text for the command. For example, when you prompt the WRKSPLF command, the prompt text Work with Spool Files is displayed at the top-center of the screen.
- PARM. One of the main purposes of a command is to provide easy prompting and entry of a program's parameters. Each parameter is defined using a PARM statement. A PARM statement provides details about the corresponding program parameter, such as its name (or keyword), its type and length, the prompt text to be displayed when the command is prompted, as well as some basic validity-checking options.
- QUAL. Parameters come in many forms. Most are fairly simple, such as a simple character or numeric field. Others are a little more complicated, such as an object name followed by a library name (i.e., a 20-byte parameter with the object name in the first 10 bytes followed by the library name in the last 10 bytes). In fact, since OS/400-i5/OS is built on a single-level library system, that type of qualified parameter is very common on the iSeries. This is where the QUAL statement comes in. It is used to define the parts of a qualified parameter (i.e., one QUAL statement per part). A PARM statement is still required to define the parameter, and on it you refer to the statement label of the first QUAL statement in a group of QUAL statements that define the parts of the qualified parameter.
Command definition statements can be prompted in SEU using F4. The resulting prompt screens for command definition statements are identical to the prompt screen you get when you prompt a CL command in SEU or on a command line. (In fact, you can prompt any of the command definition statements while on a command line even though they are not executable commands.)
Sample code: The CRTMIPGM command
These two programs -- crtmipgm0.clp and crtmipgm1.rpg -- compose a bare-bones preprocessor for the MI compiler, which is accessed using the QPRCRTPG API. The QPRCRTPG API does not accept a source file name or member. Instead, it expects the MI code that you want compiled to be in a one long character string. This makes it very inconvenient -- actually nearly impossible -- to use by itself, thus requiring a preprocessor to read your source member and copy it into one long string.
The preprocessor makes the QPRCRTPG API usable; however, the parameter list of the preprocessor is still rather complicated. This makes it a perfect candidate for a command interface. The code shown here is the command definition statements for a command interface to the main program of the preprocessor, namely the CL program CRTMIPGM0.
Take some time to digest all this code. In the next installment, we will discuss the command definition source.
-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.
