At the end of Part I of this multipart series, we saw the command definition source code for a CRTMIPGM command, which can be used as an easy-to-use interface to the MI compiler preprocessor (the code for which was also provided in Part I -- CRTMIPG0.CLP and CRTMIPG1.RPG). Now, let's go through the command definition source code for the CRTMIPGM command.
The CMD statement
The first statement, as required, is the CMD statement. This statement defines the prompt text that is shown at the top center of the prompt screen when the CRTMIPGM command is prompted from a command line. It does not define the actual command name, which is CRTMIPGM. This will be specified later when we compile the command definition source code (just like a program name is specified when you compile the program).
The PGM parameter
The next statement is a PARM statement. This statement defines the first parameter to the program, qualified program name. The KWD parameter of the PARM statement defines the keyword that can be used if the user types-out the command on the command line. (Actually, the KWD parameter is not really a parameter. It's more of an attribute, but since the PARM statement can be prompted like a command, it looks like it has a bunch of parameters. In actuality, they are all attributes of the program parameter being defined by the PARM statement.) The keyword is the word used before the opening parenthesis of a command parameter, as in:
CRTMIPGM PGM(MYLIB/MYPGM) . . .
In this case, PGM is the keyword.
The next parameter/attribute on the PARM statement is the TYPE attribute. For simple parameters, you use one of the predefined types such as *CHAR, *DEC or *NAME. But this is not a simple parameter; it is a qualified parameter. The first 10 bytes should contain the name of the program you want to create, and the last 10 bytes should contain the library where you want to create the program. To fully define all the parts of this parameter (namely, the program name and the library), we need the help of the QUAL statement. To link this PARM statement to the group of QUAL statements that will define the qualified parts of this parameter, you specify for the TYPE attribute the same statement label that you will give the first QUAL statement in the QUAL group. The statement label can be anything you want; the value QPGM is used here.
Before jumping to the QUAL statements associated with this parameter, let's look at the remainder of the parameters/attributes of this PARM statement. The MIN attribute is used to specify the minimum number of values that must be entered when the command is executed. When you specify a number greater than zero for the MIN attribute, the parameter you are defining on the PARM statement is required. Since we want to force the user to enter the name of the program he or she wants to create, we set MIN to 1.
The PROMPT parameter/attribute on the PARM statement is used to specify the prompt text that will be displayed when the user prompts the command. Note that the prompt text specified here is associated with the first QUAL statement. (For qualified parameters, many of the attributes on the PARM statement apply to the first QUAL statement, such as the MIN parameter discussed above.)
How to define the qualified parts of the PGM parameter
The two QUAL statements associated with the PGM parameter that we just defined appear immediately below the associated PARM statement. Notice the statement label QPGM on the first QUAL statement in the group. This label links the group of QUAL statements to the above PARM statement.
It is important to remember that the order of the QUAL statements determines the order they will appear on the prompt screen when the command is prompted. Here, we want the prompt for the program name to appear first and the prompt for the library name to appear second (as is the normal case).
Many of the parameters/attributes of the QUAL statement are identical to the parameters/attributes on the PARM statement. The TYPE attribute is one of them. The value we specify for the TYPE attribute on the first QUAL statement is *NAME. This ensures that the user enters a valid program name for this qualifier. That is, the system will check the value entered by the user to make sure it is a valid object name.
The length of the qualifier, specified on the LEN attribute, is 10. This is the maximum length for an object name. If the user enters fewer than 10 characters, the system will pad the name with blanks.
The second QUAL statement defines the library name portion of the PGM parameter. Again, we specify *NAME for the TYPE attribute and 10 for the LEN attribute to ensure the user specifies a valid library name. Note that the system does not check if the library exists, only that the value entered by the user is a valid object name.
We will finish up with the rest of the source code in the next installment. Until then, make sure you fully understand the part of the source code we have just discussed.
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.