1 MENU MENU is a program that reads "menu files", and creates menus which the user can then use to select items and cause things to be done. MENU provides the menu builder with a fairly simple, yet fairly robust set of options to create menus. The current implementation is geared towards single column menus, with the standard up & down arrow or item name selection generally found in simple menus. A second "free flow" type of menu is also supported, although there isn't support for selecting items via arrow key manipulation. Menus are composed of instructions that create title lines (text lines), item lines (which describe an item that can be selected with the arrow keys), and command lines (lines that define "hidden" items, or otherwise affect menus). 1.1 Menu Command Procedure The command procedure MENU.COM can be used to start up MENU, it can be modified to suit site/application specific needs. You should probably just start using menu by defining a symbol such as: $ MENU :== "@dev[dir]MENU MAIN dev:[dir].MENU The command procedure uses the first argument (P1) to determine the name of the menu file, and the second (P2) as the default filespec to use when opening the menu. P3 determines which (sub)menu is the current menu to display. P4 determines where the arrow will be displayed. P5 contains any pending commands. The above symbol definition therefore starts up menu using the menu file MAIN.MENU. 1.2 (Sub)Menu Name The Menu name (or submenu name) is declared on a line starting with a percent sign. This is the name used to reference the (sub)menu from within a different menu. In general, it is a good practice to set the first menu name to be the same as the file name, so for instance, if you were to create MAIN.MENU, you would want the first menu in the menu file to be started with: %MAIN Note that you can have default options which will be applied to all menus in the menu file by placing them before the first menu occurs in the file. These include such things as hidden menu items, wait prompt, selection prompt, and the separator character. Page 2 1.3 Title (text) Lines A title line is one that simply describes a line and how it will appear on the screen. This is handy for title lines, and for "free flow" menus. What I describe as a "free flow" menu is one in which you simply present a page of text, with "item" keywords displayed in bold. For every "item" you declare a hidden item using the same name as the bolded word in the text. The format of a title line is: % text justification The line must begin with a percent sign, be followed by some text, followed by some separator character (by default a comma), followed by a justification keyword, one of CENTER, LEFT, or RIGHT. An unrecognized justification keyword will be treated as LEFT. As with all text that can be displayed, you may enter formatting options, as follows: Formatting options: o ^b = bolded video rendition o ^f = flashing video rendition o ^n = normal video rendition o ^r = reverse video rendition o ^u = underline video rendition A caret, followed by any other character, will be replaced by that character. Note that video renditions are accumulative. For example, to display a line of text with a bolded word in it, center justified, you could use: %the word ^bbold^n is ^bbold^ned,center The separator character doesn't have to be a comma. You can change it with the following menu command: !>SEPARATOR=character See the section on 'command lines' for more information on the !>SEPARATOR command. 1.4 Item Lines An item line describes a selectable item. There are hidden items and displayable items. A hidden item start with "!>HIDE=" and lacks a description but is similar to a displayable item in all other respects. Furthermore, a hidden item can occur before the first menu has been started, in which case the item is available to all menus in the menu file in which it occurs. The format of a displayable item is as follows: Page 3 item-nameitem-descriptioncommand[optional...] The item name is a keyword that can be entered to select the item and cause the command associated with that item to be executed. The item description is simply text that gets displayed. Note that you can use the formatting options as described in the 'Title Lines' section on both the item name and the item description. The command must be one of the following: o $ command Do the command 'command'. Also, sets the MNU$WAIT symbol, according to the value given by a preceding !>WAIT command. After the command completes the arrow will return to this item, unless instructed to do otherwise. The arrow can be forced to return to a different item by using the DEFAULT option. The FORCE option can be used to force other items to be selected and executed exactly as if the user had typed in the option, in which case the arrow will move accordingly. o ^ menu-name Try loading an internal menu (by the name of 'menu-name'). If an internal menu isn't found, then try loading an external menu. This allows you to build a complex menu system that can get treated differently depending on how you set it up, so that, for instance, when you are interpreting it the menu loads only a little bit at a time, and when you wish to compile it, all the menus get loaded at once (by having different main menus). o < menu-file Load an external menu file (by the name of 'menu-file'). The first menu in the external menu file will be the menu displayed. o > menu-name Load an internal menu (by the name of 'menu-name') o * internal-command Performs an internal command - currently EXIT, SPAWN, COMPILE, and DTR are allowed. SPAWN can be followed by a command to be spawned via lib$spawn. COMPILE causes an interpreted menu to be compiled. An already compiled menu will just exit the image. EXIT will exit the image and force the command procedure to exit,by performing a "$GOTO END_OF_COMFILE" command. Page 4 DTR can be used to send a command to Datatrieve. This option exists to demonstrates how/why you might want to add your own internal commands. There isn't an automatic method provided for doing this, however, if you edit LOOP.C, and search for DTR, you should be able to figure out how to change it or add another. In any case, the DTR option currently starts a Datatrieve backend process (if it needs to), which it sends commands to via a mailbox. This saves a lot of Datatrieve initialization time (except of course the first time it gets called). For an example of a menu that uses this, check out MAIN_4.MENU. Note that you need Datatrieve to use this command! The optional parameters are keyword parameters and are: o DEFAULT=default Determines where the arrow will be placed after the command is executed o FORCE=item Forces the item(s) to execute as though user typed them in. Note that you specify the item names in the same way as the user would. You can specify multiple items by separating them with a dash. o HELP=helpfile|helptopic This is used when the help key is pressed, this overrides the current menu default. Note the "|" between the helpfile and helptopic. The helpfile or helptopic can be left blank, in which case the menu wide default is applied. The menu default can be used to set the helpfile, and this option can be used to then set a help topic. Of course, this could be used to override the current help file as well. o PARAMS=numparams Currently not implemented, force user to enter this many parameters o PROMPT=prompt If no parameters were passed, user will be prompted with this string. Parameters are indicated by a leading space, or a slash. The parameter will be concatenated with the command string and the new command string will then be executed. This works for external commands, and for the internal spawn command. If you wish to make it impossible to pass excess parameters with a command, you could end the command with an exclamation point "!", causing the parameters to be ignored. Page 5 o WAIT=string Set the MNU$WAIT symbol to this string, this overrides the current menu default. The MNU$WAIT symbol is used in the MENU.COM file, if it is not empty then the string is used as a prompt causing a wait in the menu loop. Waiting will also occur for the internal spawn command if requested. 1.5 Comment Lines A line beginning with an exclamation point is a comment line. Comments aren't allowed to be just anywhere, you must waste a whole line on them. A comment line can not start with "!>" as that is reserved for special commands. 1.6 Command Lines A line beginning with "!>" is a command line. There are several commands. If these commands occur before the first menu in a file, they are taken to be menu-wide defaults. So, for example, if you want a hidden command EXIT in all your menus, you could define a menu-wide EXIT command by putting a hidden menu item before the first menu. Commands o !>INCLUDE=includefile Includes data from a separate file, this is usefull for menu file initialization. Include files can be nested as deeply as you have quota for (i.e. Authorize parameter FILLM). o !>ALIGN All menu item descriptions get lined up, according to the size of the largest displayable item name. o !>NOALIGN Menu item descriptions don't get lined up. o !>ARROW=arrow This defines the pointer. It can be formatted (see 'Text Lines'). o !>NUMBERS Page 6 Menu item names are to be preceded by a line number (which can be used to choose an item). o !>NONUMBERS Menu item names are not to be preceded by a line number. o !>KEY=key-definition A key definition looks like Key-name "Definition"[qualifiers] where the allowable qualifiers are /[NO]ECHO, /[NO]TERMINATE This is similar to the DCL command DEFINE/KEY. o !>SEPARATOR=character This determines the character to use as a separator in commands where a separator is required. o !>WIDTH=width (decimal) This determines the width at which to display the menu. Note that the terminal width is returned to its original value whenever the menu program exits. o !>HELP=helpfile|helptopic This sets the help file and help topic to be used when the help key is pressed. Generally this is used to point at the help file to be used for the menu, and the items themselves declare a help topic to be used. o !>PROMPT=prompt This is the menu selection prompt, which appears towards the bottom of the screen (actually, currently hard-coded to line 22). o !>WAIT=string This is a string to set the MNU$WAIT symbol. This string is displayed as a prompt after execution of the item, causing a wait to occur until the user types return. This symbol is used in MENU.COM. If the symbol is set to nothing then no prompting (thus no waiting) will occur. This is also used for the internal spawn command. o !>DEFAULT=default Default item for arrow to appear on, when menu is displayed. Page 7 o !>HIDE=itemname,command,optionalparameters This looks just like a displayable item line, except it's missing the description, since it will never be displayed. See description above. This allows you to have hidden commands, this is usefull for example, for defining an EXIT command, and other commands that you don't want to waste menu space on, or that you simply don't want the casual user to know about (i.e. SPAWN), or for creating a "free flow" or "in-text" type of menu. 1.7 Default Settings o ALIGN Item alignment is enabled. o ARROW=-> (With a trailing space) o HELP=| No help library or topic. o NONUMBER Line numbers are not displayed. o SEPARATOR=, o PROMPT=Enter selection (With a trailing space) o WAIT=Press return to continue (With a trailing space) o WIDTH=80 1.8 Editing Keys o prev_screen Page 8 (not currently implemented) o ^b, up Move the selection arrow up one line. If at top it loops to the bottom. o next_screen (not currently implemented) o down Move the selection arrow down one line. If at bottom it loops to the top. o help Display help, as defined by the menu & item helpfile|helptopic setting. o ^z Causes the internal exit command to be executed. o f10 "EXIT" is returned for this. o do, ^m, Process the command that the arrow is on Note that the function keys can be redefined via !>KEY statements. (Control keys can't be redefined though, i.e. ^Z) 1.9 Compiling Menus can be "compiled". To do so, you need to create a menu item that executes the internal command "compile". For example, you could use lines similar to: !>HIDE=!@#COMPILE,*compile !>HIDE=!@#COMPILE!,*compile Then, to compile the menu, load it up and type in "!@#COMPILE". This will force the compile to begin. This is a very slow process. Several files will be created, using the name of the menu file as a prefix. A C main program (quite minimal), and four macro files will be created, as well as a command procedure to compile and link the mess. This command procedure is then executed. Page 9 The reason I use two lines above is to force the command to have to be written out in full, otherwise it would be easy to accidentally cause a compile to happen. By using "!@#COMPILE" and "!@#COMPILE!" you are forced to enter all of "!@#COMPILE" since anything less would be ambiguous. 1.10 Example Menus MAIN_1.MENU !>hide=exit,*exit %main_1 ! this is a fairly standard, simple menu ^uusers,Show users,$show users ^usystem,Show system,$show system ^ubatch,Show batch queues,$show que/batch,prompt=Queue: ^uprint,Show print queues,$show que/device,prompt=Queue: MAIN_2.MENU %main_2 ! This is a "free-form" menu !>hide=exit,*exit !>hide=users,$show users !>hide=system,$show system !>hide=batch,$show que/batch,prompt=Queue? !>hide=print,$show que/device,prompt=Queue? % You can do all sorts of things in this menu\title % You can find out what ^bUsers^n are logged in, or you can\title % find out what any of the process on the ^bsystem^n are.\title % Or you can find out about the ^batch^n or ^bprint^n queues\title % or, if you hate this menu, you can ^bexit^n the thing.. MAIN_3.MENU MAIN_3.MENU !>hide=exit,*exit !>hide=spawn,*spawn !>help=sys$help:helplib| ! ! This is a 2 menu file, which can also reference main_1 and main_2 ! %main_3 %Type ^bEXIT^n to exit this menu or ^bSPAWN^n to spawn a subprocess,left menu1,* Go to menu MAIN_1,^main_1,help=dummy|main_1 menu2,* Go to menu MAIN_2,^main_2,help=dummy|main_2 sub1,* Go to menu SUB_1,^sub_1,help=dummy|sub_1 logout, Log off and go home,$logout,help=|logout %sub_1 !>separator=\ %Type ^BEXIT^N, or ^BSPAWN^N, or choose one of the following items\left ^uitem1^n\* Go to the main menu\^main_3 ^uitem2^n\ Show the current time\$show time- Page 10 \wait=That was the time, hit return to continue\help=|show time ^uitem3^n\ Monitor utility\$monitor\help=sys$help:mnrhelp|Help MAIN_4.MENU %main_4 %This menu demonstrates the internal DTR command,center spawn,spawn a subprocess,*spawn one,First item,*dtr ;print "Number one" two,Second item,*dtr ;print "Number two" three,Third item,*dtr ;print "Number three"