Defining Choice Exit Programs for Parameter Prompts in CL Commands

Troubleshooting

Problem

This document provides an example of using a choice exit program to generate a dynamic choice list for CL command parameters at runtime.

Resolving The Problem

When CL command parameters are prompted (typically with F4 function key), the choice list is generally static; the choice list is predetermined when the command object is compiled. A choice exit program can be used to generate a dynamic choice list at runtime. This document provides an example of a choice exit program. The following is a pertinent excerpt from Chapter 9 of the IBM eServer iSeries CL Programming Version 5 manual (document number SC41-5721-05):

Possible Choices and Values

The prompter will display possible choices for parameters to the right of the input field on the prompt displays. The text to be displayed can be created automatically, specified in the command definition source, or created dynamically by an exit program. Text describing possible choices can be defined for any PARM, ELEM, or QUAL statement, but because of limitations in the display format, the text is displayed only for values with a field length of 12 or less, 10 or less for all but the first qualifier in a group.

The text for possible choices is defined by the CHOICE parameter. The default for this parameter is *VALUES, which indicates that the text is to be created automatically from the values specified for the TYPE, RANGE, VALUES, SPCVAL, and SNGVAL keywords. The text is limited to 30 characters; if there are more values than can fit in this size, an ellipsis (...) is added to the end of the text to indicate that it is incomplete.

You can specify that no possible choices should be displayed (*NONE), or you can specify either a text string to be displayed or the ID of a text message which is retrieved from the message file specified in the PMTFILE parameter of the CRTCMD command.

You can also specify that an exit program to run during prompting to provide the possible choices text. This could be done if, for example, you want to show the user a list of objects that currently exist on the system. The same exit program can be used to provide the list of permissible values shown on the Specify Value for Parameter display. To specify an exit program, specify *PGM for the CHOICE parameter, and the qualified name of the exit program in the CHOICEPGM parameter on the PARM, ELEM, or QUAL statement.

The exit program must accept the following two parameters:

o Parameter 1: A 21-byte field that is passed by the prompter to the choice program, and contains the following:

Positions	Descriptions
1-10	Command name. Specifies the name of the command being processed that causes the program to run.
11-20	Keyword name. Specifies the keyword for which possible choices or permissible values are being requested.
21	C or P character indicating the type of data being requested by prompter. The letter C indicates that this is a 30-byte field into which the text for possible choices is to be returned. The letter P indicates that this a 2000-byte field into which a permissible values list is to be returned.

o Parameter 2: A 30- or 2000-byte field for returning one of the following:

-	If C is in byte 21 of the first parameter, this indicates that the text for possible choices will return. Additionally, this is a 30-byte field where the program places the text to the right of the input field on the prompt display.
-	If P is in byte 21 of the first parameter (indicating that a permissible values list is to be returned), this is a 2000-byte field into which the program is to place the list. The first two bytes of the list must contain the number of entries (in binary) in the list. This value is followed by entries that consist of a 2-byte binary length followed by the value, which must be 1 to 32 characters long. If a binary zero value is returned in the first two bytes, no permissible values are displayed. If a binary negative value is returned in the first two bytes, the list of permissible values is taken from the command.

If any exception occurs when the program is called, the possible choices text is left blank, and the list of permissible values is taken from the command.

The value passed to the program depends upon the actions the user takes with the command:

1	When the user types the command on the command line and presses F4 to prompt, the exit program is called with a 'C' in byte 21 of the first program parameter. The program must be coded to handle this parameter value; in the simplest case, the 'C' value can be trivially handled by returning to the command with no action taken.
2	After Step 1, the parameters of the command will show on the screen. If the user types ? followed by pressing the Enter or F4 key on the dynamic choice parameter, the choice exit program will run with a 'P' in byte 21 of the first program parameter. This indicates that the program should generate a list of current choices.

The attachment in this document is a save file that contains a sample source and a README file. The source is a self-contained example (in CL and RPG) that demonstrates the use of a choice exit program. The README file contains additional details.

[{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"Platform":[{"code":"PF012","label":"IBM i"}],"Version":"7.1.0"}]

Historical Number

24643608

Was this topic helpful?

Document Information

More support for:
IBM i

Software version:
7.1.0

Operating system(s):
IBM i

Document number:
640861

Modified date:
18 December 2019

UID

nas8N1017220

IBM Support

Tips