Last month, in "Command Prompting 101," I talked about the command definition object and how you can use it to pass parameters more accurately than you can by calling them with the CALL command.

Now, I want to illustrate several important command definition features, including qualified parameters and simple list parameters.

Qualified Parameters

If you've ever entered a CPYF or DSPOBJD command, you've no doubt typed an object name using qualified syntax. This is second nature to iSeries developers and is pervasive throughout the CL commands. Qualified parameters are entered in one format, converted by the CL processor to a fixed structure, and then passed to your program. This structure is as follows: positions 1 to 10—object name; positions 11 to 20—library name.

In the previous article, the command definition interfaced with an OS/400 API that may be one of the few that does not expect a qualified object name. Instead, two separate parameters, 10 bytes each, are passed in: one with the object name, the other with the library name. Normally, the qualified syntax is used, and that's what we're going to review here.

When an object is qualified on a command, the library name is specified, followed by an object name. The object is qualified to the library with the forward slash (/) character. The CL processor uses this forward slash to parse the library/object name. If no slash is detected, only the object name is specified.

The CL processor isolates each component and stores it in a temporary variable that is subsequently passed to your program. For example, suppose a fictitious command named ENCFILE (Encrypt File) is specified as follows:

In RPG IV, the parameter structure might be similar to the following:

In the RPG IV program, by accessing the FILENAME and LIBNAME subfields, you can easily access the parameter values.

Of course, with virtually everyone running OS/400 V5R1 and later today (not many V4Rx users left), we would want to create a data structure template and then use that template as the parameter definition. So perhaps a better model might be as follows:

Then, in our program, we would declare our input parameter:

Within our program, we could access the data from that parameter using qualified data structure syntax, as follows:

The key to creating a CL command with a qualified parameter is the QUAL statement. The QUAL statement is a command definition statement that is used in groups of two or more. That's right; you can have a qualified parameter with more than two values. Think of the DSPJOB command and its JOB parameter, which uses three QUAL statements. The QUAL statement is similar to the basic PARM statement but does not have parameter name attributes. That is because the name is specified on an associated PARM statement.

To create a QUAL parameter, you need to be able to specify multiple definitions for the same parameter. To do this, specify a user-defined name for the TYPE parameter of the PARM statement. For example, normally the following would define a typical parameter in a command definition:

The TYPE keyword of the PARM statement indicates the data type for the parameter. In this example TYPE(*NAME) is specified. The basic types include *CHAR, *DEC, *INT2, *INT4, and *DATE, but there are others.

When TYPE(*NAME) is specified, it is similar to specifying TYPE(*CHAR); however, *NAME has some built-in checking, so the value specified for this parameter must be in valid object name syntax. If it is not, the CL processor will reject it—no coding required by you.

But PARM only supports unqualified parameters. To allow a qualified file name for our user-written command, we must specify a user-supplied value for the TYPE keyword. Instead of TYPE(*NAME), we must specify TYPE(user-specified) where "user-specified" is any value up to 10 characters in length. Here's an example:

The value TYPE(Q1) is specified for the parameter type. But since a type of Q1 does not exist, we need to create it. Doing so is so easy that you might ask yourself, "It can't be that simple, can it?" Yes, it can, and here it is:

What we've done is created a set of additional QUAL statements. These QUAL statements simply mean that each of their values is qualified to the other. The first QUAL statement includes a label. This label matches the TYPE keyword of the PARM statement. The qualified parameter continues until another label or another PARM statement is detected.

Now, let's put it all together. The following is the command definition syntax for a simple qualified parameter of library/object with the library name being optional.

The following RPG IV code will receive this parameter:

Simple Lists

The next style of command parameter I want to illustrate is simple lists. These are fundamental to several commands, such as DSPOBJD's OBJTYPE parameter as well as the OBJ, LIB, DEV, and OBJTYPE parameters of the SAVOBJ command.

This one is very easy, but not very obvious. Here's how it works: To allow any parameter to be specified more than once, the PARM statement's MAX keyword must be specified. For example, the following command definition source allows an object type to be specified up to 10 times:

The parameter OBJTYPE is declared and must have at least one object type specified but no more than 10 object types specified. For example, the following are valid options for this parameter:

The OBJTYPE(*ALL) option is a special case. Notice that in the example PARM statement above, I included the SPCVAL((*ALL)) keyword. This forces the parameter to accept the value *ALL even though it may not conform to the rest of the parameter's criteria.

In our example, SPCVAL((*ALL)) is sort of out of place because no restrictions on object type, other than the length, have been specified. What would be more practical is if we could simply limit the object type to only *ALL if and when it is specified. This means that when OBJTYPE(*ALL) is specified, no other object types are allowed. Well, we can do that. Simply change SPCVAL (special value) to SNGVAL (single value), and that handles it for us:

One final adjustment: It doesn't "cost" anything to allow more or fewer parameters via the MAX keyword. If the application may accept a large number now or sometime in the future, you can specify the larger limitations today rather than change things later on. Command definition parameters accept up to 300 for the MAX keyword, so let's change it to 300:

PARM KWD(OBJTYPE) TYPE(*CHAR) LEN(10) +
SNGVAL((*ALL)) MIN(1) MAX(300) +
EXPR(*YES) +
PROMPT('Object type')

The RPG IV code to process this kind of parameter is much easier than the old RPG III code was. RPG IV is so much more capable that I wouldn't even try this today with RPG III.

When a list is passed as a parameter, it is prefixed with a 2-byte integer (5i0 value) that identifies the number of items the end-user specified for the parameter. This is the number of items on your list parameter.

The following data structure can be used to declare this type of parameter. If desired, change the subfield named OBJ to the name of the parameter itself, and modify its data type and length to match that of your own command's parameter definition.

To declare this as a parameter, use the following code in an RPG IV source member:

To access the elements of the list parameter, use qualified array syntax, like so:

By combining qualified parameters and list parameters, you can handle 80 percent of all situations involving complex parameters definitions. In the next issue of RPG Developer, we'll go over the less-often-used mixed or "element" list parameters.

Bob Cozzi is a programmer/consultant, writer/author, and software developer. His popular RPG xTools add-on subprocedure library for RPG IV is fast becoming a standard with RPG developers. His book The Modern RPG Language has been the most widely used RPG programming book for more than a decade. He, along with others, speaks at and produces the highly popular RPG World conference for RPG programmers.

---

MC Press books written by Robert Cozzi available now on the MC Press Bookstore.

		RPG TnT Get this jam-packed resource of quick, easy-to-implement RPG tips! List Price $65.00 Now On Sale
		The Modern RPG IV Language Cozzi on everything RPG! What more could you want? List Price $99.95 Now On Sale