Menu
Execute a form or array as a menu. When an item is selected, the name of the selected item is placed in the internal variable %ITEM. Then, if the menu is an executed form or array specifying a form, any DML statements contained within the form are executed.

Format
 Menu |FORM | [/Qualifiers ... ]
 |ARRAY[ ] |
 FORMForm name or #expr to execute as a menu.
 ARRAY[ ] Array to execute as a menu.

 
CREATING MENUS
 A menu is a special kind of window which may have any combination of the following features: scrolling/non-scrolling, single/multi-column, and/or single/multi-selection. A menu must have single word items on the left, which are the means by which menu users make selections. Each item may be followed optionally by a description (separated by at least one space) on the same line. The following is an example of a typical menu:
 
Main Menu
ADDAdd employees
MODModify employees
LOOKLook at employees
EXITExit from this program

EXECUTING MENUS
 When a menu executes, IDML displays the menu from which the user can select an item. This is the same as when an item is selected from an IDML procedure menu. When an item is selected from the menu, the internal variable %ITEM is set to the name of the selected item. Then, if the menu is an executed form or array specifying a form, any DML statements contained within the form are executed.
 
NOTE
 To display a list of choices from a database, use the TABLE_EDIT command with the 'Read_only' option (see /OPTIONS qualifier). It is more efficient than the MENU statement for this purpose.
 
Executing a Form as a Menu
You can create a menu with the Forms editor in the same way you would create a form. Menu forms can be very useful in designing a non-procedural screen where you wish to have a pop-up window of items from which the user can select. To be consistent with UserBase standards, a menu should be displayed as a reverse video bordered window with a title. The window must be wide enough (or the title short enough) to allow for at least one space on each end of the title.
 

 
Executing an Array as a Menu
To execute an array as a menu, the array must be formatted as follows:
array[0] = the number of items (("rows") in the array.
array[0,1] = IDML form name(optional)
array[0,2] = (NOT USED)
array[0,3] = maximum number of columns**(default = 1)
array[0,4] = default video attributes(default = none)
array[0,5] = default indentation(default = 2)
array[n,1] = item name***(required for items)
array[n,2] = item description(optional)
array[n,3] = menu column(default = 1)
array[n,4] = video attributes(default = array[0,4])
array[n,5] = indentation(default = array[0,5])
where n corresponds to the item number.
** If more than one column is specified, MENU divides the screen evenly into the number of columns specified.
*** If the item name element is null (""), the information is interpreted as Group information, and the item description element is used as the group title.
When executing an array as a menu, %ITEM always returns with the item number of the last selected item, even after the EXIT key is pressed from the menu
(use %ACTION to test for the EXIT key).
The following is an example of an array that is formatted for execution as a menu:
array[0] = 5
array[0,1] = "MENU_FORM"
array[0,3] = 1
array[0,4] = ""
array[0,5] = 4
array[1,1] = ""
array[1,2] = "Statistical Analysis"
array[1,3] = 1
array[1,4] = "BOLD"
array[1,5] = 2
array[2,1] = "INPUT"
array[2,2] = "Input statistical data"
array[2,3] = 1
array[2,4] = ""
array[2,5] = 5
array[3,1] = "REPORT"
array[3,2] = "Produce reports of analyzed data"
array[3,3] = 1
array[3,4] = ""
array[3,5] = 5
array[4,1] = "GRAPH"
array[4,2] = "Produce graphs of analyzed data"
array[4,3] = 1
array[4,4] = ""
array[4,5] = 5
array[5,1] = "EXIT"
array[5,2] = "Exit menu system"
array[5,3] = 1
array[5,4] = ""
array[5,5] = 5

NORMAL (NON-MULTIPLE OPTION) MENUS

The default action for a normal (non-multiple option) menu is to terminate after the item is selected. This behaviour occurs if the DML code contained within the form (if any) returns normally by dropping out the bottom or simply by returning with the RETURN statement as follows:
Return ! Will set %STATUS to null.
If the EXIT key is entered, it is as though the EXIT item had been selected, and the appropriate DML code is executed. This behaviour can be changed by returning %CONTINUE, %ERROR or %EXIT from the DML code within the form (if any).
Return %CONTINUELeave the cursor on the item just selected, and
re-execute the menu.
Return %ERRORRing the terminal bell, leave the cursor on the item just selected, and re-execute the menu.
Return %EXITExit as though the EXIT key had been entered (will branch to the exit label if /EXIT was specified on the MENU statement).

MULTIPLE OPTION MENUS

A multiple option menu is a menu where more than one item can be selected before continuing. The items already selected are contained as a comma separated list in the internal variable %MUTIPLE. Each selected item is highlighted.
An example is the forms background attribute menu where if REVERSE and BOLD are selected before the CONTINUE item, the background of the form is both REVERSE and BOLD. The default action for a multiple option menu is to continue executing the menu after each item is selected, until the CONTINUE item is selected (or the DO key is entered), in which case the menu terminates. This behaviour occurs if the DML code contained within the form (if any) returns normally by dropping out the bottom or simply returning with the RETURN statement. If the EXIT key is entered, the DML code is NOT executed.
Note the difference in the default actions between a multiple options and a non-multiple options menu. This behaviour can be changed by returning %CONTINUE,
%ERROR or %EXIT from the DML code within the form (if any).
Return %CONTINUEDo not select the item. If %CONTINUE is returned when the CONTINUE item is selected, the menu will not terminate.
Return %ERRORRing the terminal bell. Do not select the item.
Return %EXITDo not select the item. Exit as though the EXIT key had been entered (will branch to the exit label if /EXIT was specified on the MENU statement).

Qualifiers
 /Columns=exprThe number of columns of ITEMS on the menu (default is one). The menu is divided into the specified number of equal sized sections.
 /Default=exprSet the default item to be 'expr' when the menu first executes. 'expr' may be the item NAME or number. If not specified, the default item for a normal menu is EXIT, or CONTINUE for a multiple menu.
NOTE
Versions of IDML prior to V3.2 defaulted to the first item in the menu. This behaviour can be continued by setting the %OPTIONS internal variable to "MDO" (Menus Default to One). This is done automatically when and IDML program prior to V3.2 is recalled.
 /Exit=LABELBranch to a label if the EXIT item is selected or the EXIT key is pressed.
 /Help=exprThe Help tag for the menu. If not specified, the default help tag is the name of the menu form or array.
 /Multiple [=expr]This is a multiple option menu. If 'expr' is specified, the items specified as a comma separated list are initially selected (i.e. highlighted and stored in %MULTIPLE).
 /NoexecuteDo not execute the DML code contained within the form when an item is selected. Just execute the form as a menu. This would normally be used when the DML statements contained within the form are for some other purpose (e.g. an Input/Output or Report form).
 /NoexpertOverride any expert mode setting, and initially execute this menu in non-expert mode. Note that this does not stop the user from switching the menu back to expert mode.
 /Parameters=(par1 [,par2...])Pass parameters to any called routine.
 /Pos=row_expr, col_exprOptional qualifier indicating where to place the top-left corner of the form on the screen. If not specified, the menu is placed in its default position.
 /RemainLeave the form on the screen after the menu execution terminates. This qualifier should NOT be used with the /ROWS qualifier.
 /Rows=exprForce the form to have a different number of rows than it was originally created with. This may force the form to be copied and the copy to be executed as a scrolling menu. It should NOT be used with /REMAIN as the original form must be replaced on the screen when the menu terminates. Instead use DML statements inside the form to perform the required actions.
 /Term_list=( key [=LABEL], key [= LABEL], ...)The list of terminators to be trapped. These keys can override the automatic handling of EXIT and the /EXIT qualifier.
 A label to branch to can be specified for each terminator, otherwise the TERM_SUB subroutine is executed as each specified key is entered. If no TERM_SUB subroutine has been specified, the menu exits with the %ACTION internal variable set.
 See the %ACTION internal variable for a list of valid key-names.
Example:
/Term_list=(Q=QUIT, F19, F20)
! goto label QUIT on gold Q,
! gosub TERM_SUB subroutine on
! F19 or F20.
 /Term_sub=SUBROUTINEThe subroutine to execute after a key specified in the TERM_LIST (without a label) has been pressed. The %ACTION internal variable is ket to the key pressed.
 /Timeout=LABELThis allows a menu to terminate after the timeout period (in seconds) specified in the %TIMEOUT internal variable. IDML then branches to the specified label.
Example:
%TIMEOUT = 300
MENU A /Timeout=END
! timeout after 5 minutes
The U11_DEFAULT_INPUT_TIMEOUT and U11_DEFAULT_INPUT_TIMEOUT_MODE logicals are also available to facilitate timeout procedures. See the Userbase Installation Guide for details on these logicals.
 /Title=exprAn optional title for the form border. This allows a form to be used for more than one purpose, and to be labelled appropriately.
 

Example
Following is an sample section of a DML program executing an array as a menu and using some of the features of array execution that have just been described:
Menu array[] &
/Remain &
/Pos=3,2 &
/Default=1
If %ACTION = %EXIT then
Remove MENU_FORM
Return
End_if
Begin_case %ITEM
Case 1
...
Case 2
...
.
.
.
End_case