Control Language

Parameters (command-line arguments) defined in the main procedures of all traditional System/38 and AS/400 programs are hard coded lists that are made up of parameters that can be numeric, alphanumeric, boolean, etc. and the order in which parameters are passed is important. This is a stark difference from the Unix and DOS worlds where the parameter list in Unix shell scripts and C programs is a set or array of character pointers and more often than not the parameters are not positionally dependent.

The developer's solution to this problem was the command object (*CMD). While the parameters on the command can be specified in any order, each parameter is defined to be passed in a specific order to the program. The programmer can also define, among other things, the parameter's data type, unique parameter name, descriptive text (for prompting), default value (used only if the parameter isn't specified during execution), if the values are restricted to a certain set or range, if the data entered should be changed to another value before calling the program, etc.

At its most basic a command names a single program to call when the user types or prompts the command and presses the Enter key. The command takes all of the parameters typed by the user, and those not typed by the user, and builds a parameter list that it passes to the program when it's called.

The BNF for a much simplified CL command syntax would be defined as follows:

 <CL-command> ::= command-name [<positional-parameter-list>] [<named-parameter-list>]

 <positional-parameter-list> ::= <parameter-value> [<positional-parameter-list>]

 <named-parameter-list> ::= parameter-name "(" <parameter-element-list> ")" [<named-parameter-list>]

 <parameter-element-list> ::= <parameter-value> [<parameter-element-list>]

 <parameter-value> ::= CL-name |
                       qualified-CL-name |
                       "*"special-value |
                       generic-CL-name"*" |
                       "'"alphanumeric-value"'" |
                       numeric-value |
                       "X'"hexadecimal-value"'"

The items above that end in -name follow object naming conventions which, generally speaking, means the name starts with a letter and can be up to ten characters in length. (CL commands are also case-insensitive.)

A good example of a typical CL command is the Change Program (CHGPGM) command below:

CHGPGM MYPGM OPTIMIZE(*FULL) RMVOBS(*BLKORD *PRCORD) TEXT('My program.')

The above command is passing four parameters to the program that does Change Program processing and they are:

• MYPGM: A positional parameter (PGM), and the only required parameter. In this case it's the name of the program being changed. Positional parameters are always first. Once a named parameter appears all parameters that follow must be named parameters.
• OPTIMIZE(*FULL): A named parameter specifying a single element which is a special value. In this case it will change the program to be fully optimized.
• RMVOBS(*BLKORD *PRCORD): A named parameter (Remove Observability) specifying multiple special values. In this case telling it to remove two kinds of profiling data from the program.
• TEXT('My program.'): Another named parameter specifying a single alphanumeric value. In this case it's changing the descriptive text of the program.

In reality the system will pass many more parameters than the four specified above. This is because the rest of the CHGPGM command's parameters were not specified, so default values will be passed instead. For every parameter on this, aside from the PGM parameter, that default is *SAME, meaning don't change it.

All CL commands can be prompted directly from the command line or within CL program source by typing the command and pressing the F4 function key. An OS/400 command can also be prompted by typing a ? before the command. (This is useful in an interactive program which cues a command string, having already filled in some values.)

The system will then present a screen with the set of parameters that the program accepts/requires (required parameters are usually highlighted).

Required parameters are listed first, and parameters with system-supplied default values are listed last of all. To see all parameters, press F10. If any one choice requires further selections, those are cued as you select that value for that parameter, by appearing onscreen.

Prompting is further enhanced to allow the programmer to find what values are valid for each parameter. To do this during prompting the user would move the cursor to the parameter field in question and press F4 again. The system would then display a screen describing the type of input required and an available list of allowable values.

To enter a longer name, or extend the list to allow you to enter extra values, type a plus sign instead of a value. (As when listing names of objects to be saved or restored.)

Cursor sensitive help can also be provided on commands but it's not required. If help has been provided one can view help for a parameter by moving the cursor to the desired parameter field and pressing F1 (help). To get help for the entire command itself (and all of its parameters) the user would press F1 anywhere on the prompt display and then press F2 (extended help).

New commands can be created to call non-system programs and they will work exactly like the inbuilt variety. The Command Definition Language is described in the CL Programmer's Guide.

It's a good idea to create help screens for new commands and their parameters. All help screens use panel group objects (*PNLGRP) and these can be created using the UIM language described in the IBM AS/400 Application Display Programming manual.

Beginning in V5R3 of the operating system a new, much simpler method of creating help was added: run the command

 GENCMDDOC CMD(MYLIB/MYCMD) TODIR('/QSYS.LIB/MYLIB.LIB/QPNLSRC.FILE) GENOPT(*UIM)

A skeleton UIM panel group will be automatically generated including all parameters described by the command. The result file can be edited (seu, wdsc, rdi), then compiled with the CRTPNLGRP command, and finally associated with the command via CHGCMD HLPPNLGRP().

There are 2,262 built-in IBM commands contained in V7R3,[3] but finding them isn't all that hard because of several designs of the system that make life easier. These labor saving designs are: Standardized Abbreviations, Command Grouping Menus, and Command Selection.

The following is a sample of CL programming. The program interactively converts dates from Julian to MDY and vice versa. Results are displayed on line 24 of the terminal. It accepts two parameters. The &IN parameter which is the date string to be converted. If a Julian string it should be in the format YYNNN where YY is the year number and NNN is the day number of the year. If a MDY string it must be in the format MMDDYY. The second parameter is &TYP which is the type of date to be converted to. It must be 'J' (Julian) or 'M' (MDY). For example: the command CALL PGM(ICVTDATC) PARM('04180' 'M') will convert the Julian date 04180 to 062804 (June 28, 2004).

PGM (&IN &TYP)

   DCL &IN  *CHAR 6
   DCL &OUT *CHAR 8
   DCL &TYP *CHAR 1

   IF (&TYP = J) +
      DO
         CVTDAT DATE(&IN) TOVAR(&OUT) FROMFMT(*MDY) +
                TOFMT(*JUL) TOSEP(*NONE)
      ENDDO

   ELSE IF (&TYP = M) +
      DO
         CVTDAT DATE(&IN) TOVAR(&OUT) FROMFMT(*JUL) +
                TOFMT(*MDY) TOSEP(*NONE)
      ENDDO

   SNDPGMMSG MSG('IN=' || &IN || '  OUT=' || &OUT) +
             MSGTYPE(*COMP)

ENDPGM  

• Qshell
• Rexx