We left off in Part III discussing the command definition source code for our CRTMIPGM command. Specifically, we discussed special values and replacement values for parameters and how they can be used. Let's finish up by looking at a few other key concepts related to command parameters, and then we'll look at how to compile command definition source code to create the command.
Before continuing, you may want to review the source code for the CRTMIPGM command. You may also want to review the CL and RPG source code provided in Part I, which constitutes the MI compiler preprocessor -- CRTMIPG0.CLP and CRTMIPG1.RPG).
How to define a simple-list (the OPTIONS parameter)
The next parameter of the CRTMIPG0 program (the CPP for the CRTMIPGM command) is the OPTIONS parameter, which coincides with the Option template parameter of the QPRCRTPG API. This parameter is a bit different than the others because the user can enter multiple values for it. The default value for the MAX parameter on the PARM statement is 1, meaning only one value can be entered for the parameter. Here we have specified 15 for the MAX parameter. That means the user can enter up to 15 valid entries for the OPTIONS parameter.
When MAX is greater than 1, the parameter is called a list parameter. When all the valid values are of the same type, as is the case here, the list parameter is further defined as a simple list (in contrast to mixed lists, which allow for values of different types to be specified). When a list parameter is prompted, the system initially displays two input fields, one right under the other. The user can request more input fields by typing a '+' in the first character position of one of the input fields and pressing Enter. A simple list parameter is passed to the CPP as a single unit with the number of list items specified in the first two bytes (in 2-byte binary format) followed by the individual values in an array-type format.
The PARM statement for the OPTIONS parameter also has a couple of other parameters/attributes that we have not seen so far. The VALUES parameter/attribute is used to specify a list of valid values for this parameter. When *YES is specified for the RSTD parameter/attribute (as it is here), the system validates the user input against the valid values specified on the VALUES parameter/attribute. (Note: Values specified on the SPCVAL parameter/attribute are also considered valid and do not have to be listed on the VALUES parameter/attribute as well.)
How to control parameter prompting
Finally, we specify *PMTRQS for the PMTCTL parameter/attribute on the PARM statement for the OPTIONS parameter. This tells the system not to show this parameter initially when the command is prompted. The user can request the parameter by pressing either F9 or F10 once the command is prompted. The parameter is always passed to the CPP even if it is displayed on the prompt screen.
When a command has many parameters, it is often beneficial not to display them all at once on the prompt screen, lest the user be overwhelmed. The basic rules for deciding if a parameter can be defined with PMTCTL(*PMTRQS) are as follows:
- The parameter must have a default value, one which will be sufficient in most cases when the command is used.
- The parameter will be used mainly as auxiliary information, such as processing options.
The REPLACE and AUT parameters
The last two parameters for the CRTMIPGM command -- REPLACE and AUT -- are straightforward simple parameters. The item to notice here is the type *LGL used for REPLACE. This defines REPLACE as a logical type. Notice the special values allow the user to use the more congenial *YES or *NO for this parameter, but the CPP will be passed the valid logical value '1' or '0', respectively.
Compiling the command
To compile this command definition source and create the CRTMIPGM command object, we use the Create Command command (CRTCMD). Assuming the source is contained in member CRTMIPGM in file MYLIB/QCMDSRC, the following is an example of the CRTCMD that can be used:
CRTCMD CMD(MYLIB/CRTMIPGM) PGM(CRTMIPGM0) SRCFILE(MYLIB/QCMDSRC) SRCMBR(*CMD) PRDLIB(MYLIB)
Notice that the command processing program, CRTMIPGM0, is specified on the PGM parameter.
The PRDLIB parameter is a handy parameter. When you specify a library name for it, that library is temporarily added to the user's library list during the execution of the command. That is, library MYLIB will be temporarily added to the library list when the CRTMIPGM command is executed. This is a convenient way to make sure the CPP and any supporting programs can be found at run time. And since the PRDLIB is added to the library list before the CPP is called, the CPP does not need to be qualified.
More information
If you want more information on creating commands, see the CL Programming manual. It has a whole chapter devoted to the subject.
-----------------------------------
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.
