Forcing Keyword Parameters

Published: June 22, 2011

by Ted Holt

Programming languages use two conventions for passing arguments (commonly referred to as parameters) to a called routine. Some languages use positional parameters. That is, the parameters must be passed to the routine in a certain order. The other (and less error-prone) method is to password parameters in keyword format. IBM i allows you to force callers to use keyword format--to a point--when they use your CL commands. Here's how.

But first, let's review the two major problems inherent in positional parameters. First, it is easy to get a parameter value into the wrong position. Take the following OCL command for example.

LIBRLIBR HISLIB,HERLIB,,REPLACE,,REPLACE

OCL uses commas to separate positional parameters. Adjacent commas mean that you are not passing a value for a parameter. If you omit one of the commas or add an extra comma, the system will not pass the correct values to the parameters of the LIBRLIBR routine.

The second problem is that the meaning of each parameter is not obvious. Two parameters have the value REPLACE. What does each REPLACE mean in this context?

In addition to OCL, other languages that use positional notation are the CALLP opcode in RPG and Unix (and Unix-like) shells, including Qshell.

Keyword parameters do not have these problems because the order in which the parameters are coded does not matter, and each parameter's function is documented by its keyword. Look at the following CL command.

CPYSRCF FROMFILE(HISLIB/QRPGLESRC)
        TOFILE(HERLIB/QRPGLESRC)
        FROMMBR(REPLACE)
        MBROPT(*REPLACE)

Is the meaning of any parameter in doubt?

When you create a CL command of your own, give some thought to whether or not you want to force callers to enter keywords. The only advantage (of which I'm aware) of allowing users to enter parameters positionally is that the source code is sometimes cleaner and easier to read. Compare the following equivalent CL commands:

IF (&OPTION *EQ 'W') DO

IF COND(&OPTION *EQ '1') THEN(DO)

Both are legible, but I prefer the first one. The second one is too cluttered for my taste. But the IF command only has two parameters. If there were, say, a half dozen or more, the absence of keywords would decrease readability.

To force users to enter parameters in keyword format, use the MAXPOS parameter of the Create Command (CRTCMD) command.

CRTCMD CMD(MYLIB/DOIT)
       PGM(*LIBL/DOITC)
       SRCFILE(MYLIB/QCMDSRC)
       SRCMBR(DOITX)
       <b>MAXPOS(1)<b>

The help text for MAXPOS appears to me to be in error. It reads that the MAXPOS value must be greater than the number of required parameters, but my experience is that the MAXPOS value must be greater than <b>or equal to</b> the number of required parameters.

And that brings up one little feature of which I am not fond. The preceding paragraph implies that you cannot force required parameters to be entered in keyword format. That is true, and I don't like it, but nobody asked my opinion.

If a caller passes too many parameters positionally, the system responds with two error messages: CPD0065 (Number of positional parameters exceeds limit of 1); and CPF0001 (Error found on DOIT command).

For more information about positional and keyword formats, follow this link to IBM's website.

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot