A Generic Command Choice Program

September 22, 2004 Bruce Guetzkow

The code for this article is available for download.

I’ve had many opportunities to create my own commands on the AS/400, iSeries, and i5. Although you can use the VALUES or SPCVAL keywords to hardcode valid values, changing valid values requires changing the command source. On occasion I’ve created a command with a keyword for which valid values are already stored in a file. By specifying the CHOICE and CHOICEPGM parameters on the PARM, ELEM or QUAL statements, you can create a program to display the list of valid values stored in that file. The following is an example of a generic program you can use for any command/keyword combination with data in nearly any file.

CONTROL FILE

A choice program is called directly by the operating system when F4 is used to prompt a command if any parameters specify CHOICE(*PGM) and CHOICEPGM(library/program). In this instance the program receives parameters indicating that 30 bytes will be returned, to be displayed as text. It is called again when F4 is used to prompt one of those parameters. This time the program receives parameters indicating that 2000 bytes will be returned as a list of valid choices.

I’ve written a couple of these programs for specific purposes, but have found that writing a different program for each instance is a nuisance. Program CMDCHOICE is a write-once, use-anywhere program, so I no longer need to write a program for each need.

Because we plan on using the same choice program for many commands and command keywords, we will need to store information about each command and keyword that will use this program in a file. File CMDCHOICE contains the following fields:

• CKCOMMAND–Command name.

• CKKEYWORD–Command keyword.

• CKLIB–Library containing value reference file.

• CKFILE–Value reference file.

• CKFIELD–Value reference field.

• CKTEXT–Display text.

This file is uniquely keyed by fields CKCOMMAND and CKKEYWORD. Fields CKLIB, CKFILE, and CKFIELD indicate the library, file, and field that contain the list of valid choices. Field CKTEXT holds the text that is displayed alongside the keyword when the command is initially prompted.

CHOICE PROGRAM

Now take a look at the program. The choice program (CMDCHOICE) receives two parameters. Parm 1 is 21 bytes long and consists of a command name (10 bytes), command keyword (10 bytes), and data type (1 byte).

Parm 2 is specified as 2000 bytes, but actually returns either 30 or 2000, depending on the data type specified in parm 1.

The data type will contain a C when the command is prompted, indicating that 30 bytes of text is to be returned. A P is placed in the data type parm when the command keyword is prompted, indicating that 2000 bytes of data containing a list of valid values is to be returned.

The executable part of the program begins by moving parm 1 to a data structure and clearing parm 2. The specific command and keyword are then retrieved from file CMDCHOICE. If data type C (text) has been specified, the text found in file CMDCHOICE for this command/keyword combination is placed in parm 2 and the program ends. If no record was found for the command/keyword, the text ** Choices NOT Found ** is returned.

If data type P (values) has been requested, the program continues by building a dynamic SQL select statement, using the file and field from file CMDCHOICE for this command/keyword. The statement is prepared, a cursor is declared, and then the cursor is opened. The dou loop that follows then fetches the valid values and loads them into parm 2. Parm 2 is structured as follows:

1. Number of values (bytes 1-2, binary)

2. Values

• Length of value (2 bytes, binary)
• Value

Since we won’t know how many values there will be until after parm 2 is completely loaded, we’ll skip over the first two bytes and load the first value starting in byte 3 (this is why field strpos is initialized to 3). The program continues to fetch values and append them to parm 2 until all values have been retrieved. Field count is used to keep track of the number of values being returned. After all values have been fetched, the first two bytes of parm 2 are updated with the number of values and the cursor is closed.

MAKING IT WORK

To make this all work, first compile the DDS for file CMDCHOICE:

CRTPF FILE(library/CMDCHOICE)
      SRCFILE(library/QDDSSRC)
      SRCMBR(CMDCHOICE)

Next, compile program CMDCHOICE:

CRTSQLRPGI OBJ(library/CMDCHOICE)
           SRCFILE(library/QRPGLESRC)
           SRCMBR(CMDCHOICE)
           OBJTYPE(*PGM)

For each command keyword that will use this program specify on the PARM, ELEM, or QUAL statements:

CHOICE(*PGM) CHOICEPGM(library/CMDCHOICE)

Compile your command as you normally do, using option 14 from PDM or using the CRTCMD command.

Use your favorite database file utility to add a record to file CMDCHOICE for each command/keyword as needed. Be sure to specify entries for fields CKCOMMAND, CKKEYWORD, CKLIB, CKFILE, and CKFIELD in upper case. Field CKTEXT can (and probably should be) in mixed case, as this text will be displayed.

SOME NOTES

There are only two limitations to any choice program: valid values stored in a file can be no longer than 32 bytes, and there is a maximum number of valid values that can be displayed. For 1-byte values, that number is 666. Fewer values are allowed for longer values. The maximum number of allowed values is the size of the parm (2000 bytes), minus the space for the number of returned values (2 bytes), divided by the size of the returned values plus 2 bytes (for the length of each value).

There are also two limitations to this program: values must be defined as alphanumeric, and the file where valid values are stored must be accessible by a single key field.

You can find more information on choice programs in CL Programming (in PDF format) on IBM’s InfoCenter. Select Programming, CL, Related Information, CL Programming, Chapter 9 (Defining Commands), Defining Lists for Parameters, and Possible Choices and Values.

You can also specify values not in the reference file by using the VALUES or SPCVAL parms; however, those values will not appear in the list when you prompt on the keyword.

STAY TUNED

A choice program is a convenient way to present a list of valid values for a command keyword. One thing it does not do is validate the value entered. So how do you ensure that entries are valid? In a future article, I’ll show you a service program that you can include in your validity checking program that will validate entries from files referenced by this choice program.

Bruce Guetzkow has programmed on the AS/400 and iSeries since 1990, in manufacturing, distribution, and other industries. He is currently the IS director at United Credit Service in Elkhorn, Wisconsin. Click here to contact author.