Possible choices and values

This describes how choices and values for parameters are defined.

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:

• 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.

• 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 34 bytes 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.