CHOICE (Selection Field Choice) keyword for display files

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:

• As a character string: 'Choice text '
• As a program-to-system field: &field-name

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:

• The position of the selection field
• The length of the longest choice number that is displayed to the left of the choice
• The length of the choice text itself
• The number of columns in the selection field
• The width of the gutter between columns

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 > sign 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 because the system does not support both numeric and mnemonic selection on a selection field. The following examples show how to specify mnemonics.

Choice text

Appears as

'>File'

File

'F>inish'

Finish

'Save >As...'

Save As...

'X >= 1'

X = 1

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:

Choice text

Appears as

'X >>= 1'

X >= 1

'X >>>= 1'

X >= 1

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.