Use this field-level keyword to define a choice for a selection field.
The format of the keyword is:
CHOICE(choice-number choice-text [*SPACEB])
The choice-number parameter defines an identification number for this choice. This parameter is required. The choice number returns to the application to indicate which choice in the selection field was selected. On non-graphical displays, the choice number is also displayed to the left of the choice text. Valid values for the choice-number are positive integers greater than 0 and less than or equal to 99. Duplicate choice-number values within a selection field are not allowed.
The choice-text parameter defines the text that appears in the selection field for the choice. This parameter is required. The parameter can be specified in one of two forms:
The field specified must exist in the same record as the selection field and must be defined as a character field with usage P.
The choice text for all choices within a selection field must fit on the display for the smallest display size specified in the file. Therefore, the maximum length for the choice text depends on the following items:
If the smallest display size is 24 x 80, the above must be less than or equal to 80. If the smallest display size specified is 27 x 132, this sum must be less than or equal to 132.
Within the choice text, you can specify a mnemonic for the choice by using a greater than character (>) to indicate the mnemonic character. The character to the right of the > is the mnemonic. The mnemonic is used only on a character-based graphical display attached to a controller that supports an enhanced interface for nonprogrammable workstations, where the choices are rendered using radio buttons. The mnemonic is ignored on displays where the field is rendered using numeric selection, since the system does not support both numeric and mnemonic selection on a selection field. Examples of specifying mnemonics:
In order to specify > as a character in the text, you must specify it twice, just as you must specify the apostrophe character twice in order to get a single apostrophe character in the text. For example:
The mnemonic character indicated must be a single-byte character and must not be a blank. Only one mnemonic is allowed in the choice text, and the same mnemonic character cannot be specified for more than one choice.
The *SPACEB parameter is optional and indicates that a blank space (or line) should be inserted before this choice. This parameter is used to specify logical grouping of choices that are numbered consecutively.
For vertical selection fields (selection fields arranged in a single column), if the choice numbers are not consecutive, a blank space is automatically inserted between non-consecutive choices. This does not happen for horizontal selection fields (selection fields arranged in multiple columns).
When the CHOICE keyword is specified on a field, either the SNGCHCFLD or the MLTCHCFLD keyword must also be specified.
Several CHOICE keywords can be specified for one selection field. The maximum number of CHOICE keywords that can be specified depends on the position of the selection field and the display size. All choices must fit on the smallest display size specified for the file.
Option indicators are valid for this keyword. When a CHOICE keyword is turned off, the list of choices is compressed.
The following example shows how to specify the CHOICE keyword:
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
A R RECORD
A F1 2Y 0B 1 2SNGCHCFLD
A 01 CHOICE(1 '>Undo ')
A CHOICE(2 &MARKTXT);
A CHOICE(3 '>Copy ')
A MARKTXT 12A P
A
In this example, three choices are defined for the single-choice selection field F1. The text for choice 2 is contained in field MARKTXT, and the mnemonic for choice 2 must be contained in the text supplied by the application at run time. If indicator 01 is off when the record is written, only choices 2 and 3 are displayed.