SNGCHCFLD (Single-Choice Selection Field) keyword for display files

Use this field-level keyword to define a field as a single-choice selection field.

A single-choice selection field is a field that contains a fixed number of choices from which a user can select one choice. The field appears as a vertical list of choices, with a single input field at the upper left, or as a group of radio buttons.

The format of this keyword is: 
SNGCHCFLD[([*NORSTCSR | *RSTCSR]
[*NOAUTOSLT | *AUTOSLT | *AUTOSLTENH]
[*NOSLTIND | *SLTIND]
[*NOAUTOENT | *AUTOENT | *AUTOENTNN]
[[(*NUMCOL nbr-of-cols) | (*NUMROW nbr-of-rows)]
[(*GUTTER gutter-width)]])]

Parameters are optional. If none are specified, the single-choice 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.

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 AUTOSLT parameter indicates if the ENTER key should automatically select the choice currently being indicated by the selection cursor. *NOAUTOSLT indicates that the user must select the choice. *AUTOSLTENH indicates that auto-select is only in effect if the device is connected to an enhanced controller. The default is *AUTOSLT.

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

Auto-enter will cause the record to be returned as soon as a choice is selected (as if the user had also pressed the enter key). The AUTOENT parameter indicates to what extent Auto-Enter should be enabled. *NOAUTOENT indicates that no auto-enter will be in effect. *AUTOENT will enable auto-enter on all displays unless a double digit selection number is required for any of the choices. *AUTOENTNN will enable auto-enter only if numeric selection of the choices is not required. If not specified, this parameter is set to *NOAUTOENT as default.

*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 single-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 single-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 columns of the single-choice selection field. It can only be specified if either *NUMCOL or *NUMROW has been specified and must 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 (including leading and trailing choice text attributes).

A field containing the SNGCHCFLD keyword must also contain one or more CHOICE keywords defining the choices for the field.

The field containing the SNGCHCFLD keyword must be defined as an input-capable field with data type Y, length equal to 2, and zero decimal positions. 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 radio button. On input, the field contains the number of the choice selected, or 0 if no choice was selected. On output, if the field contains a choice number, that choice is displayed as the default selection.

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

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

ALIAS
AUTO(RA)
CHANGE
CHCACCEL
CHCAVAIL
CHCUNAVAIL
CHCSLT1
CHCCTL
CHECK(ER)2
CHECK(FE)3

CHOICE
CHGINPDFT
COLOR4
DSPATR(RI UL BL CS HI ND PC)4
ERRMSG
ERRMSGID
INDTXT
PUTRETAIN
TEXT
Notes:
  1. CHCSLT functions only if the single-choice selection field is displayed in a pull-down menu that does not display selection indicators (for example, PULLDOWN(*NOSLTIND) specified).
  2. Check(ER) is not allowed with SNGCHCFLD if the AUTOENT or AUTOENTNN parameters have been specified.
  3. Check(FE) applies only to a display attached to a controller that does not support an enhanced interface.
  4. If the COLOR or DSPATR keyword is specified for a field with the SNGCHCFLD 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 SNGCHCFLD keyword:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A
     A          R RECORD
     A            :
     A            :
     A                                  3  3'Single selection field.     :'
     A            F1             2Y 0B  3 35SNGCHCFLD
     A  01                                  CHOICE(1 '>Undo       ')
     A                                      CHOICE(2 &MARKTXT);
     A                                      CHOICE(3 '>Copy       ')
     A            MARKTXT       10A  P
     A

In this example, when using a graphical display station attached to a controller that supports an enhanced interface for nonprogrammable workstations, the selection fields look like this:


A figure of the example specification displayed on a graphical display station.
Parent topic: DDS keyword entries for display files (positions 45 through 80)