MLTCHCFLD (Multiple-Choice Selection Field) keyword for display files

You use this field-level keyword to define a field as a multiple-choice selection field.

A multiple-choice selection field is a field that contains a fixed number of choices from which a user can select multiple choices. The field appears as a vertical or horizontal list of choices, an input field to the left of each choice, or as a group of check boxes.

If you see an input field, instead of a check box to the left of each choice, the selection character default value is a slash (/). Message CPX5A0C contains the country-designated selection characters. The value can be changed to allow alternate selection characters for a multiple-choice selection field. These characters are the allowed uppercase or lowercase country-designated selection characters. The characters are defined when the display file is created.

The format of the keyword is:

MLTCHCFLD[([*RSTCSR | *NORSTCSR]
[*NOSLTIND | *SLTIND]
[[(*NUMCOL nbr-of-cols) | (*NUMROW nbr-of-rows)]
[(*GUTTER  gutter-width)]])]

Parameters are optional. If none are specified, the multiple-choice selection field choices will be arranged in a single vertical column. The user will be allowed to move the selection cursor out of this field using the arrow keys. There will be three spaces between choices and selection indicators will be displayed.

The RSTCSR parameter specifies whether the arrow keys should be allowed to move the selection cursor outside of the selection field. *RSTCSR specifies that the arrow keys will not cause the selection cursor to move outside of the selection field. *NORSTCSR specifies that the arrow keys will cause the selection cursor to leave the selection field. The default is *NORSTCSR.

Note: An exception to the restrictions imposed by *RSTCSR happens if the selection field is the only field contained within a pull-down window. In that case, when the selection cursor is within the leftmost or rightmost columns, the left and right arrow keys will close the current pull-down window and open the pull-down window associated with the menu-bar choice to the left or right of the current menu-bar choice.

The *RSTCSR parameter is ignored on displays that are not connected to a controller that supports an enhanced interface for nonprogrammable workstations.

The SLTIND parameter indicates whether selection indicators (such as check boxes) should be displayed. *NOSLTIND specifies that the selection indicators should not be displayed. The default is *SLTIND.

*NUMCOL specifies that this selection field should be displayed in multiple columns with the choices spread across the columns in this manner:

choice1   choice2   choice3
choice4   choice5   choice6
choice7   choice8   choice9

The nbr-of-cols portion of the parameter specifies how many columns the selection field should contain. Nbr-of-cols must be a positive integer and the entire multiple-choice selection field must be able to fit on the display when placed in the specified number of columns.

*NUMROW specifies that this selection field should be displayed in multiple rows with the choices spread across the columns in this manner:

choice1   choice4   choice7
choice2   choice5   choice8
choice3   choice6   choice9

The nbr-of-rows portion of the parameter specifies how many rows the selection field should contain. Nbr-of-rows must be a positive integer and the entire multiple-choice selection field must be able to fit on the display when placed in the specified number of rows.

The *GUTTER parameter is optional and specifies the number of spaces to be placed between each column of the multiple-choice selection field. It can only be specified if either *NUMCOL or *NUMROW has been specified and must immediately follow the (*NUMxxx #) parameter. The gutter-width must be a positive integer of at least 2. If *GUTTER is not specified, the default of gutter-width is set to three spaces.

A field containing the MLTCHCFLD keyword must contain one or more CHOICE and CHCCTL keywords defining the choices for the field.

The field containing the MLTCHCFLD keyword must be defined as an input-capable field with the data type Y and length of two. The position specified for the field is the position of the input field displayed to the left of the first choice or of the uppermost check box. If *NOSLTIND is used on the PULLDOWN keyword and the device is attached to a controller that supports an enhanced interface for nonprogrammable workstations, the position is the first character of the text for the first choice. On input, the field contains the number of the choices selected, or 0 if no choice was selected. On output, the value of the field is ignored.

Provide a minimum of two spaces between the end of the previous field and the position specified for the multiple choice field. This allows an ending attribute for the previous field, and a beginning attribute for the multiple choice field. These attributes cannot overlap.

The following keywords can be specified on a field with the MLTCHCFLD keyword:

ALIAS
AUTO(RA)
BLANKS
CHANGE
CHCAVAIL
CHCUNAVAIL
CHCSLT¹
CHCCTL
CHECK(ER, FE)²
CHOICE

CHGINPDFT
COLOR³
FLDCSRPRG
DSPATR(RI UL BL CS HI ND PC)³
ERRMSG
ERRMSGID
INDTXT
OVRATA
OVRATR
PUTRETAIN
TEXT

Notes:

CHCSLT functions only if the multiple-choice selection field is displayed in a pull-down menu that does not display selection indicators, when PULLDOWN(*NOSLTIND) is specified.
Check(FE) applies only to a display attached to a controller that does not support an enhanced interface.
If the COLOR or DSPATR keyword is specified for a field with the MLTCHCFLD keyword, it applies only to the input field portion of the selection field on character-based displays.

Option indicators are not valid for this keyword.

Example

The following example shows how to specify the MLTCHCFLD keyword:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A
     A          R RECORD
     A            F1             2Y 0B  3 35MLTCHCFLD
     A  01                                  CHOICE(1 '>Undo       ')
     A                                      CHOICE(2 &MARKTXT);
     A                                      CHOICE(3 '>Copy       ')
     A                                      CHCCTL(1 &CTLONE1 MSG1111 QUSER/A)
     A                                      CHCCTL(2 &CTLTWO1 &MSG1 &LIB/&MSGF);
     A                                      CHCCTL(3 &CTLTHR1);
     A            CTLONE1        1Y 0H
     A            CTLTWO1        1Y 0H
     A            CTLTHR1        1Y 0H
     A            MSGF          10A  P
     A            LIB           10A  P
     A            MARKTXT       10A  P
     A

The CHCCTL keyword is required for each CHOICE keyword used for the MLTCHCFLD.

On input, the hidden field for the CHCCTL keyword indicates whether the choice was selected. 0 indicates the choice was not selected; 1 indicates the choice was selected. On output, the hidden field controls the availability of the choice, and is used to set a default selection of a choice. 0 indicates the choice should be available, 1 indicates the choice should be selected by default, and 2 indicates the choice is unavailable. Other values, such as 0, are truncated.