CHOOSE statement

After you display data, the CHOOSE statement moves a highlight bar among a series of choices and selects a choice when you press GO, RETURN, or enter a unique combination of initial characters.

This statement is supported only for backward compatibility.

Note: Does not apply to SpeedScript programming.

Syntax

CHOOSE

 {    { ROW field  [ HELP char-constant ] }
   |  { FIELD { field [ HELP char-constant ] } ...}
 }
 [ AUTO-RETURN ] [ COLOR color-phrase ] 
 [ GO-ON ( key-label ... ) ] [ KEYS char-variable ]
 [ NO-ERROR ] [ PAUSE expression ]
 { [ frame-phrase ] }

You can specify the AUTO-RETURN, COLOR, GO-ON, KEYS, NO-ERROR, and PAUSE options in any order.

ROW field
Tells CHOOSE to move a highlight bar among iterations of a down frame. The field is the name of the field that you want the highlight bar to begin highlighting. The ROW option is useful for browsing through a set of records, although field does not have to refer to database records.

If you use the ROW option with the CHOOSE statement, use the SCROLL statement as well. See the SCROLL statement reference entry examples.

If you use ROW, you can add a COLOR statement to control the video display highlighting.

FIELD field
Tells CHOOSE to move a highlight bar through a set of fields or set of array elements in a frame. The field argument is the table record or array variable with fields or elements through which you want to move the highlight bar. These fields or array elements must be defined as ABL default FILL-IN widgets (not specified with the FILL-IN NATIVE option). The FIELD option is useful for building menus. You can also supply help for field.
HELP char-constant
Lets you provide help text for each field in a CHOOSE FIELD statement or for the entire CHOOSE ROW statement. For the CHOOSE ROW statement, the help text is displayed throughout the CHOOSE operation. For the CHOOSE FIELD statement, the help text you specify for a field is displayed whenever you move to the field.
AUTO-RETURN
Tells the AVM to use the selection when you enter a unique string of initial characters. When you use AUTO-RETURN and the user enters a unique string of initial characters, the AVM sets the value of LASTKEY to KEYCODE (return).
COLOR color-phrase
Specifies a video attribute or color for the highlight bar. Following is the syntax for color-phrase:
{     NORMAL
   | INPUT
   | MESSAGES
   | protermcap-attribute
   | dos-hex-attribute
   | { [ BLINK- ] [ BRIGHT- ]
          [fgnd-color] [ bgnd-color ] }
   | { [ BLINK- ] [ RVV- ] [ UNDERLINE- ] [ BRIGHT- ]
          [ fgnd-color ] }
   | VALUE ( expression ) 
}

For more information on color-phrase, see the COLOR phrase reference entry.

GO-ON ( key-label ) . . .
Names key-labels for keys that cause CHOOSE to return control to the procedure. If you do not use the GO-ON option, CHOOSE returns control to the procedure when the user presses GO, RETURN, END-ERROR, or types a unique substring when AUTO-RETURN is in effect. If you don't specify F1, RETURN, or F4, those keys are still GO-ON keys by default.
KEYS char-variable
If you want to highlight a particular choice when entering a CHOOSE statement, or if you want to know what keys the user pressed to make a selection, use the KEYS option. When you use the KEYS option, you must give the name of a character variable, char-variable. If char-variable is initialized to one of the choices before entering the CHOOSE statement, the AVM highlights that choice. As the user presses keys to move the highlight bar, the AVM saves those keystrokes in char-variable. You can test the value of char-variable after the CHOOSE statement returns control to the procedure. There is a 40-character limit when using the KEYS option.
NO-ERROR
Overrides default error handling by the CHOOSE statement, and returns control to the procedure. If you do not use the NO-ERROR option, the CHOOSE statement causes the terminal to beep when the user presses an invalid key.

If you use the NO-ERROR option and the user presses an invalid key, the CHOOSE statement ends. At this point, you usually want to use the LASTKEY function to test the value of the last key the user pressed and then take the appropriate action.

Note that the NO-ERROR option of the CHOOSE statement does not have any affect on the ERROR-STATUS system handle.

PAUSE expression
Specifies a time-out period in seconds. If the user does not make a keystroke for the specified number of seconds, the CHOOSE statement times out and returns control to the procedure. You can choose a whole or a fractional value for the time-out interval. If the time-out period you specify is a fractional value, the value is rounded to the nearest whole millisecond.

The time-out period begins before the user's first keystroke and is reset after each keystroke. If CHOOSE times out, the value of LASTKEY is -1. Use the time-out period to prevent inactivity.

frame-phrase
Specifies the overall layout and processing properties of a frame. For more information on frame-phrase, see the Frame phrase reference entry.

If your procedure might eventually run on a spacetaking terminal, use the ATTR-SPACE option for the CHOOSE statement. Omitting this option makes the highlight bar invisible.

Example

The following procedure displays a strip menu with four choices. The procedure defines two arrays; one holds the items for selection on the menu, the other holds the names of the programs associated with the menu selections. The CHOOSE statement allows the user to select an item from the strip menu. The AVM finds the number (within the array) associated with the item selected and the program associated with that number in the proglist array. The AVM runs the program, if it exists, and displays a message. It also allows the user to select another item if the program does not exist. (In your own application, you associate actions with items selected by the CHOOSE statement.)

r-chsmnu.p

DEFINE VARIABLE menu     AS CHARACTER NO-UNDO EXTENT 4 FORMAT "x(7)"
  INITIAL [ "Browse", "Create", "Update", "Exit" ].
DEFINE VARIABLE proglist AS CHARACTER NO-UNDO EXTENT 4
  INITIAL [ "brws.p", "cre.p", "upd.p", "exit.p"].

FORM "Use the sample strip menu to select an action."
  WITH FRAME instruc CENTERED ROW 10.

REPEAT:
  VIEW FRAME instruc.
  DISPLAY menu WITH NO-LABELS ROW 21 NO-BOX ATTR-SPACE
    FRAME f-menu CENTERED.
  HIDE MESSAGE.
  CHOOSE FIELD menu GO-ON (F5) AUTO-RETURN 
    WITH FRAME f-menu.
  IF SEARCH(proglist[FRAME-INDEX]) = ? THEN DO:
    MESSAGE "The program" proglist[FRAME-INDEX] "does not exist.".
    MESSAGE "Please make another choice.".
  END.
  ELSE RUN VALUE(proglist[FRAME-INDEX]).
END.

The GO-ON option sets the GET key to perform an action like GO. With the LASTKEY function, you could check for F5 and take another action relevant to your application.

Notes

See also

COLOR phrase, Frame phrase, SCROLL statement, STATUS statement