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` ] }

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:

Syntax
{ NORMAL \| INPUT \| MESSAGES \| `protermcap-attribute` \| `dos-hex-attribute` \| { [ BLINK- ] [ BRIGHT- ] [ `fgnd-color` ] [ `bgnd-color` ] } \| { [ BLINK- ] [ RVV- ] [ UNDERLINE- ] [ BRIGHT- ] [ `fgnd-color` ] } \| VALUE ( `expression` ) }

{     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. 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 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.

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

If you do not specify help text in the CHOOSE statement, any help text you specify for the field in the Data Dictionary is displayed instead. If no help text is specified in either the CHOOSE statement or Data Dictionary, then the status default message is displayed throughout the CHOOSE statement.

The CHOOSE statement takes different actions depending on the key you press and whether you use the NO-ERROR option, as shown in Table 11.

Table 11: CHOOSE statement actions
Key	NO-ERROR	Action
Valid cursor motion¹	N/A	Clear saved keys and move highlight bar.
Invalid cursor motion²	NO	Clear saved keys and beep terminal.
Invalid cursor motion²	YES	Clear saved keys and return control to procedure.
A non-unique string followed by an alphanumeric character that does not form a matchable string³	NO	Clear saved keys and try to match the last key entered. If no match is available then beep terminal.
A non-unique string followed by an alphanumeric character that does not form a matchable string with the other characters	YES	Return control to procedure.
An invalid string	NO	Beep terminal.
An invalid string	YES	Return control to the procedure and, if the KEYS option was used, save any printable keys.
Other keys⁴	NO	Beep terminal.
Other keys⁴	YES	Return control to procedure.

¹Valid cursor motion keys within a frame are CURSOR UP, CURSOR DOWN, CURSOR RIGHT, CURSOR LEFT, SPACEBAR, TAB, and BACKTAB.

²Invalid cursor motion keys are CURSOR UP, CURSOR DOWN, CURSOR RIGHT, and CURSOR LEFT that cause the cursor to move outside the frame.

³The r-chs1.p procedure below, shows what the CHOOSE statement does when the user enters a non-unique string followed by a character that, together with the rest of the string, does not match anything.

⁴Other keys are non-cursor-motion, non-alphanumeric keys (function keys, BACKSPACE) except for: HELP, STOP, RETURN, GO, END, ERROR, END-ERROR. Keys defined to do the actions of these keys still do so.

r-chs1.p
DEFINE VARIABLE abc AS CHARACTER NO-UNDO FORMAT "x(3)" EXTENT 42. DEFINE VARIABLE ix AS INTEGER NO-UNDO. DO ix = 1 TO 42: abc[ix] = STRING(ix, ">9"). END. DISPLAY abc NO-LABELS WITH ATTR-SPACE CENTERED ROW 4 TITLE " CHOOSE STATEMENT " FRAME f-choose WIDTH 36. DISPLAY "Enter your selection " WITH CENTERED NO-BOX FRAME f-instruct. PAUSE 1 BEFORE-HIDE NO-MESSAGE. REPEAT: HIDE MESSAGE. CHOOSE FIELD abc AUTO-RETURN WITH FRAME f-choose. MESSAGE "You selected -> " FRAME-VALUE. END.

r-chs1.p

DEFINE VARIABLE abc AS CHARACTER NO-UNDO FORMAT "x(3)" EXTENT 42. 
DEFINE VARIABLE ix  AS INTEGER   NO-UNDO. 
   
DO ix = 1 TO 42: 
  abc[ix] = STRING(ix, ">9"). 
END. 
DISPLAY abc NO-LABELS WITH ATTR-SPACE CENTERED ROW 4 
  TITLE " CHOOSE STATEMENT " FRAME f-choose WIDTH 36. 
DISPLAY "Enter your selection " WITH CENTERED NO-BOX 
  FRAME f-instruct. 
PAUSE 1 BEFORE-HIDE NO-MESSAGE. 
REPEAT: 
  HIDE MESSAGE. 
  CHOOSE FIELD abc AUTO-RETURN WITH FRAME f-choose. 
  MESSAGE "You selected -> " FRAME-VALUE. 
END.

Once you run this procedure, your window looks like the following:

When you press 2, CHOOSE moves the highlight bar to 2. When you press 4, CHOOSE moves the bar to 24. When you press 6, CHOOSE looks for the string 246. Because it cannot find the string, it matches the last key pressed (6) and places the highlight bar on 6.

A choose field can temporarily become a handle type for internal purposes, but is not actually a widget since it does not have its own set of attributes and widgets. Therefore, you might see myhandle:TYPE = choose field in the widget tree, but you cannot manipulate the choose field.