CHCCTL (Choice Control) keyword for display files

You use this field-level keyword on a selection field to control the availability of the choices for the field.

The format of the keyword is either

CHCCTL(choice-number &control-field [msg-id [msg-lib/]msg-file])
or
CHCCTL(choice-number &control-field [&msg-id [&msg-lib/]&msg-file])

The choice-number parameter is required and it specifies the choice to which this keyword applies. Valid values are 1 to 99.

The control-field parameter is required and it specifies the name of a 1-byte numeric hidden field that, on output, contains the control value for the choice. The field must be defined within the same record as the field you are defining, and must be defined as data type Y (numeric) with length 1, decimal positions 0, and usage H. On input for multiple-choice selection fields, the selection field indicates whether the field was selected.

The following table shows the control values for the hidden field, and their meaning on input and output:

Table 1. Control values for hidden fields
Control value	Meaning on output	Meaning on input
0	Available	Unselected
1	Selected	Selected
2	Unavailable (Cannot place cursor on choice unless help for choice is available.)
3	Unavailable (Placing cursor on choice is allowed.)
4	Unavailable (Cannot place cursor on choice even if help for choice is available.)

Note: The cursor restrictions described only apply to displays that are connected to a controller that supports an enhanced interface for nonprogrammable workstations. If another display is used, the cursor is not restricted.

The message-id and message-file parameters are optional and specify a message to be displayed when the user selects an unavailable choice. If these parameters are not specified, the system issues a default message, CPD919B, when the user selects an unavailable choice. If a field is used for the message-id, that field must exist in the record you are defining and it must be defined as data type A, usage P, and length of 7.

The message-file parameter is a required parameter when the message-id parameter is used. If you do not specify the library parameter, *LIBL is used to search for the message file at program run time. If a field is used for the message library or message file, that field must exist in the record you are defining and it must be defined as data type A, usage P, and length of 10.

When the CHCCTL keyword is specified on a field, a CHOICE or PSHBTNCHC keyword with the same choice number must also be specified for the field.

Option indicators are not valid for this keyword.

Example

The following example shows how to specify the CHCCTL keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A                                      :
     A                                      :
     A            F1             2Y 0B  3 35SNGCHCFLD
     A                                      CHOICE(1 '>Undo       ')
     A                                      CHOICE(2 '>Mark       ')
     A                                      CHOICE(3 '>Copy       ')
     A                                      CHCCTL(1 &CTLUNDO MSG1112 QUSER/A)
     A                                      CHCCTL(2 &CTLMARK &MSG &LIB/&MSGF);
     A                                      CHCCTL(3 &CTLCOPY);
     A            CTLUNDO        1Y 0H
     A            CTLMARK        1Y 0H
     A            CTLCOPY        1Y 0H
     A            MSG            7A  P
     A            MSGF          10A  P
     A            LIB           10A  P
     A

When using a graphical display station attached to a controller that supports an enhanced interface for nonprogrammable workstations, the selection field looks like this:

A figure of the example specification displayed on a graphical display station.