PSHBTNCHC (Push Button Field Choice) keyword for display files

You use this field-level keyword to define a choice for a push button field.

The format of the keyword is:

PSHBTNCHC(choice-number choice-text [command-key] [*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 push-button field was selected. 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 push-button field are not allowed.

The choice-text parameter defines the text that appears in the push-button 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 must fit on one line of the display for the smallest display size specified for the file. The maximum length for the choice text depends on the following conditions:

Position of the push-button field
Length of the choice text
Gutter width between choices
Number of columns of choices
Smallest display size
Window width, if displayed in a window

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. Examples of specifying mnemonics:

Choice text: Appears as
'F2=>File': F2=File
'F3=F>inish': F3=Finish
'>Enter': Enter

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

Note: You cannot specify the > as the mnemonic.

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 should not be specified for more than one choice. If the same mnemonic character is used more than once than the first definition of the mnemonic is used.

The command-key parameter is optional and indicates which function key should be generated when this push-button choice is selected. The following keys can be used as parameters: CA01 to CA24, CF01 to CF24, PRINT, HELP, CLEAR, ENTER, HOME, ROLLUP, and ROLLDOWN. If the command-key specified is not defined at the file level for this record, then the key will be added to this record. If a parameter is not defined then ENTER will be used.

The *SPACEB parameter is optional and indicates that a blank spot where this choice will be located should be inserted before this choice. This parameter is used to specify logical grouping of choices.

When the PSHBTNCHC keyword is specified on a field, the PSHBTNFLD keyword must also be specified.

Several PSHBTNCHC keywords can be specified for one push-button field. The number of PSHBTNCHC keywords that can be specified depends on the position of the push-button field and the display size. More than one choice can occupy one line, and all choices must fit on the smallest display size specified for the file. The maximum number of choices is 99.

Option indicators are valid for this keyword. When a PSHBTNCHC keyword is off, the list of choices is compressed.

Push buttons always behave as if AUTOENT and AUTOSLT are on.

Example

The following example shows how to specify the PSHBTNCHC keyword:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8

     A
     A          R RECORD
     A            :
     A            :
     A            F1             2Y 0B 24 02PSHBTNFLD
     A  01                                  PSHBTNCHC(1 '>Help' HELP)
     A                                      PSHBTNCHC(2 &F3 CA03)
     A                                      PSHBTNCHC(3 'E>nter')
     A            F3             4A  P
     A
     A

In this example, three choices are defined for the push-button field F1. The text for choice 2 is contained in field F3, 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.