Migrating to Netware 4.1

- 12 -

Setting Up Menus

Creating Menus
- Menu Commands
- Organizational Commands
- Menu Control Commands
Converting NetWare 3.x Menus

Novell Menus enables you to create a menu-driven user inter-face. You can associate a number of commands with each option or specify that another submenu be invoked when an option is selected.

In NetWare 3.11, this was provided by Novell Menus. NetWare 3.11 Novell Menus was adequate in simple situations, but many network administrators preferred the more robust third-party tools. An example of such a tool is the Saber menus program. For NetWare 4.x, Novell licensed the Saber menu technology and used it to build the NetWare 4.x. menus package. Currently, NetWare 4.x menus package does not have the full functionality of the commercial Saber menu system package, but it is a vast improvement over NetWare 3.x Novell Menus. NetWare 4.x uses the NMENU utility to create menus. NetWare 3.12 (and higher versions)also use the NMENU utility. NMENU is a batch program that invokes other utilities such as MENUEXE.EXE and MENURSET.EXE.

This chapter shows you how to create menus for the users on your network with the NMENU utility. You will also see how to convert your NetWare 3.x menus into NetWare 4.x menus using the MENUCNVT.EXE conversion tool included with NetWare 4.x.

Creating Menus

A scripting language is used to create the source file for the NMENU utility. The source (SRC extension) file is then compiled to produce a data file (DAT extension). The data file is then used with an NMENU.BAT utility that interprets and executes the DAT file. The steps to perform these operations are depicted in figure 12.1.

Figure 12.1 The Novell menu compilation steps.

A NetWare 4.x menu can consist of four components (see fig. 12.2). The components are specified in the menu source file and are listed as follows:

1. A main menu that has a title and at least one option.

2. Commands to be executed when an option is selected.

3. Submenus that are displayed when an option is selected.

4. Prompts for user input.

The first two of the parts listed here are necessary. The remaining parts, such as the submenus and prompted user input, are optional.

Figure 12.2 The parts of a menu.

Menu Commands

The principal menu commands are MENU, ITEM, and EXEC. The MENU and ITEM commands are used for organizing the structure and appearance of the menu. The EXEC command is used for controlling the execution of commands when a particular item is selected. In general, menu commands can be divided into two categories:

1. Organizational commands

2. Control commands

These two categories of commands are discussed next in greater detail.

Organizational Commands

Organizational commands are responsible for the overall organization and contents of the menu; they also determine the appearance of the menu on the screen. Currently, only two commands are defined for this category. These are:

MENU command
ITEM command

Every menu and submenu is defined by a MENU command. The parameters for the MENU command are a menu number and the title of the menu. Its general syntax is:

MENU menuNumber,menuTitle

The menuNumber is unique per menu, and it can be any number between 1 and 255. There is no special ordering relationship between the menu numbers and the menus that are displayed. The only requirement is that they be unique. There should not be any spaces between the menuNumber, the comma, and the menuTitle. The menuTitle is a string of characters that should not exceed 40 characters. The menuTitle is displayed at the top of the menu. It is used to identify the title of the menu.

For example, if a menu is given a number of 5 and a title of "Available Options," its menu command should appear as:

MENU 5,Available Options

The preceding command would define the start of the menu Available Options that is identified by the menu number 5.

NOTE: There is currently no method of controlling the position of the menu on the screen, the way it could be done in the NetWare 3.11 Novell Menus. The NetWare 4.x Menus automatically cascade the menus using their own positioning algorithm.

The ITEM organizational command is used to define the option that is displayed for a menu. The items are listed in the order in which you want them to appear in the menu. An option consists of a text string parameter to the ITEM command. The general syntax of the ITEM command is:

ITEM  itemText { itemOption itemOption ... }

ITEM  ^tagchar itemText { itemOption itemOption ... }

In the first format for the ITEM command, every itemText is preceded by a letter that is automatically assigned by the Menus utility. The letters are from A to Z, with the first ITEM command being assigned A, the next B, and so on. These letters or item tags serve as a short-cut to selecting the option. Pressing the letter key corresponding to an option causes that menu item to be selected. The item tags do not determine the order in which the menu is displayed. The display order is determined by the order in which the items are listed. The itemText is the text string that you want displayed for the menu option. The itemOptions are placed within curly braces ({ }) and can consist of zero or more item options that further qualify the menu option. The itemOptions is discussed in greater detail in the following section. An example of the syntax for the first format is shown here:

ITEM    NetAdmin Tool { }

The itemText is "NetAdmin Tool," and there are no itemOptions that are specified, and therefore the curly braces are empty. When the curlies are empty, they can be left out. For example:

ITEM Display Context EXEC CX

If this were the first ITEM listed under a MENU command, it would have a tag character of A; if this were the second item, its tag character would be B, and so on.

The second format for the command is similar to the first format. The difference is that ^tagchar can precede the itemText. The caret (^) character followed by a single character, the tagchar, allows this character to override the default letter assignment for that item. For example, if you wanted to use digits 1 to 6 to designate the menu options, you would use the following:

ITEM  ^1First Option { } ITEM  ^2Second Option { } ITEM  ^3Third Option { } ITEM  ^4Fourth Option { } ITEM  ^5Fifth Option { } ITEM  ^6Sixth Option { }

The item options are displayed in the order in which they are listed. The Menus utility makes no attempt to sort them based on any tag characters you have specified.

NOTE: You should be familar with the syntax of the MENU and ITEM command as discussed in this section.

ITEM Options

The itemOptions that are placed in the curly braces in the ITEM command further qualify how the commands associated with the ITEM are executed. The listing that follows shows the ITEM command and the commands that are executed when an item is selected:

ITEM Menu Option Text { } command 1 command 2    : command N

The commands that are executed when the ITEM is selected are listed immediately following the ITEM. These commands are preceded by one of the following keywords: EXEC, LOAD, SHOW, GETO, GETR, GETP. These keywords will be discussed in greater detail in the next section.

NOTE: It is not necessary to indent the commands in relationship to the ITEM command. However, indenting is recommended as it makes the menu script more readable.

The itemOption that can be placed in curly braces can be either of the following:

BATCH
CHDIR
SHOW
PAUSE

The BATCH item option is used to free up additional memory when running an application. The Novell NetWare 4.x Menus utility by itself takes up 32 KB of RAM. For applications that take up a large amount of memory, it would be desirable to use as much RAM as possible for the application. By using the BATCH option, the commands associated with the menu are written in a temporary batch file. The Menus utility is removed from memory and the batch file run. The last command in the batch file re-invokes the Menus utility. To run the NETADMIN utility using a batch file, you would use the following:

ITEM NetAdmin Utility {BATCH} EXEC NETADMIN

TIP: Use the BATCH option when running large programs, or when you are unable to run a program from the Menus utility because of insufficient memory.

The CHDIR item option is used to restore the default directory to the one that existed prior to executing the command. Some programs give you the option of changing the default directory when they are run. After exiting these programs, you might be placed in a default directory that is different from the one that was in use prior to executing the program. It is often desirable to have the same default directory when programs are excepted from the menu utility. To keep the same default directory throughout the execution of a program called TELNET, you could use the following:

ITEM Telnet Application{CHDIR} EXEC TELNET

The different item options can be combined. For example, to execute FILER as a batch file and to retain the same default directory, you could use the following:

ITEM Filer Utility {BATCH CHDIR} EXEC FILER

The order in which the item options are placed inside curly braces is not significant. Therefore, the above statements are equivalent to those listed below:

ITEM Filer Utility {CHDIR BATCH} EXEC FILER

TIP: Use the CHDIR option consistently to always return to a known default directory.

The SHOW item option is used to display the name of the DOS command executed from the Menus utility on the upper-left hand corner of the screen as it executes. This is particularly useful if the DOS command that is executing is passed a parameter, which is also displayed as the command executes. An example of this usage is shown below:

ITEM Directory Contents Listing {SHOW} EXEC DIR

The PAUSE option causes the message "Press any key to continue" at the end of executing the command(s). This gives the user an opportunity to read the screen before proceeding to the next step. The Menus utility will not proceed to the next step, unless the user presses a key. An example of using the PAUSE option is shown below:

ITEM Search for files that have "SCS (C)opyright"  {PAUSE} EXEC GREP  "SCS (C)opyright"  *.*

TIP: Use the PAUSE option when running a utility that prints messages to the standard output or standard error stream and terminates. The standard output and standard error streams are set to the display console by default.

TIP: The PAUSE option can be combined with the SHOW option for many DOS commands that terminate after displaying their results.

Table 12.1 summarizes the different ITEM options that were discussed previously.

TABLE 12.1 ITEM Options

Item Option	Description	Example
BATCH	Frees up RAM occupied by Menus utility (32K) when a program runs.	ITEM Application X {BATCH}
CHDIR	Restores default directory to that which existed prior to running the commands associated with the menu item.	ITEM Application X {CHDIR}
SHOW	Shows DOS commands on upper-left corner of screen as they execute.	ITEM Application X {SHOW}
PAUSE	Pauses display, and waits for user to press a key, at end of executing a command.	ITEM Application X {PAUSE}

Menu Control Commands

The MENU and ITEM commands that were discussed in the previous section are used to determine the contents of a menu or submenu and the manner in which options should be displayed or run. The actual commands that are processed occur after the ITEM command. These commands are called control commands, and they are used to execute applications from within the menu utility (NMENU), load menu definitions kept in separate files, show submenus, and obtain user input. There are six control commands that begin with keywords listed as follows:

EXEC
LOAD
SHOW
GETO
GETR
GETP

The first three of the control commands listed here (EXEC, LOAD, SHOW) deal with executing programs, and loading and displaying submenus. The last three of these commands (GETO, GETR, GETP) solicit input from the user, which can then be used as parameters for commands and programs that are executed.

The EXEC Control Command

The EXEC (or EXECUTE) command is used to run an application. The command that is run can be an EXE, COM, BAT, an internal DOS command or any of the following:

DOS
EXIT
LOGOUT

An example of using the EXEC command for a DOS internal command is as follows:

ITEM  ^DShow Directory listing {SHOW} EXEC DIR

An example of using the EXEC command for a NetWare EXE program file is as follows:

ITEM  ^UNetwork User {BATCH} EXEC NETUSER

The EXEC DOS command runs a second copy of the command shell. For DOS, this is the COMMAND.COM command processor. When a second copy of the command shell runs, you are presented with a command prompt and can type in any DOS or application command. The NMENU utility and the previous copy of the command shell are still loaded, so you are limited by the remaining memory available for your DOS application. An example of the EXEC DOS command is shown here:

ITEM  Exit to DOS { } EXEC DOS

To return to NMENU, you must type the EXIT command at the command prompt. This terminates the second shell and returns you to NMENU.

TIP: You might want to use the BATCH item option to free up memory when using the EXEC DOS command:

ITEM  Exit to DOS {BATCH} EXEC DOS

For secure environments, you might want to control the applications a user can run on the network. In this case, you might want to restrict the user's access to the command prompt and not use the EXEC DOS command in an item option.

If you want to give users the option of exiting the menu program completely and going to the DOS prompt, you can use the EXEC EXIT command. This command terminates the menu utility program, which causes the system to remove the program from memory. Control is returned to the command shell and the command prompt. If, for security reasons, you want to control a user's access to the command, you should not use the EXEC EXIT command. An example of the use of the EXEC EXIT command is shown below:

ITEM  Exit NMENU { } EXEC EXIT

In many environments it is desirable to control a user's access to the command prompt so that none of the options, EXEC DOS or EXEC EXIT, are suitable (because they give a user access to the command prompt). Yet it is still necessary for a user to terminate the use of the network and the Novell menus. To accomplish this, a special EXEC LOGOUT command has been defined. When the EXEC LOGOUT option is used, it logs the user out of the network and simultaneously terminates the Novell Menus utility.

An example of the use of the EXEC LOGOUT command is shown below:

ITEM  Exit Novell Menus and logout { } EXEC LOGOUT

Table 12.2 summarizes the different EXEC commands that can be used.

TABLE 12.2 EXEC Command Summary

EXEC Type	Description
EXEC command	Replace command with a DOS internal/external command, an EXE or COM program file, or a DOS batch file.
EXEC DOS	Starts a secondary shell and gives user access to the command prompt via the secondary shell.
EXEC EXIT	Terminates the Novell Menus (NMENU) utility, and returns control to the command shell and the command prompt.
EXEC LOGOUT	Terminates the Novell Menus (NMENU) utility, and logs the user out of the network. Provides a secure option to exit the Novell Menus.

The SHOW Control Command

A menu is defined using the MENU command in which you must define the menu number and the menu title. There can be many such menu commands in a single file. The first menu command, in a compiled file that is passed as a parameter to the NMENU command, becomes the first menu that is displayed. This is the main menu. All other menus in the file are displayed by using the SHOW command. The syntax of the SHOW command is

SHOW menuNumber

The menuNumber should be replaced with a number that represents the menu number defined in the MENU statement for the submenu that should be displayed. There can be up to 255 submenus or menu commands (menu definitions) in a single menu file.

The submenu that is displayed is cascaded in relationship to the previous menu. Its position on the screen is determined automatically by the Novell menu utility. Currently there is no way of changing the position at which the menu is displayed.

The LOAD Control Command

A menu is defined using the MENU command in which you must define the menu number and the menu title. There is a limit of up to 255 submenus or menu commands (menu definitions) in a single menu file. For large menu systems, it is necessary to place the menu definitions in separate files. You may decide to use separate files for menu systems that are not large because doing so can help you organize and manage the menu definitions. To load a menu that is in a separate file, you must use the load command.

The syntax of the LOAD command is shown here:

LOAD menuName

The menuName should be replaced by the filename of the compiled menu file. When the LOAD command is executed, the original menu system is left running, but a second menu is added to the screen.

The GETx Commands

There are three forms of the GETx commands: GETO, GETR, and GETP. Like the other control commands, GETx commands are listed after an ITEM command and are executed when the menu item is selected. An example of some of the GETx commands is shown below:

ITEM   ^LDirectory Listing GETO  Enter directory name: {} 45,, {} EXEC DIR %

The GETO Command The GETO command is used for obtaining an optional input from the user. The O in GETO is for the word "optional." When the GETO command is executed, as shown in the previous example, a dialog box is displayed. The message in the dialog box, the width of the user input, the initial value of the user input, and so on are passed as parameters to the GETO command.

With the GETO, GETR, and GETP commands, the Enter key signals that you have completed the information, and the F10 key signals that you want to continue with the menu execution.

The user has a choice of making or not making an entry (optional GET). In either case, when the user presses F1, execution continues. If the user makes an entry, the entered value is passed as a parameter to the command that follows. In the preceding example, the command that follows is the EXEC DIR command. In this example, if a user had made the entry F:\SYSTEM, the EXEC command that would be executed is as follows:

EXEC DIR F:\SYSTEM

The preceding command would display the contents of the directory F:\SYSTEM. If the user had not made any entry, but just typed in F10, the EXEC command that would be executed would be the following:

EXEC DIR

The preceding command would display the contents of the current directory.

The % character can be used as a placeholder for a single user input. The above example of the use of the GETO command can be alternatively expressed using the % placeholder.

ITEM ^LDirectory Listing GETO Enter directory name: {} 45,, {} EXEC DIR %

NOTE: The O in GETO stands for Optional input.

The GETR Command The GETR command works in a manner similar to the GETO command described previously. The big difference is that the GETR command requires users to enter information. Just pressing F10 only (or Enter if GETR is in its own dialog box) will not cause the GETR command to continue execution. The menu display will be paused and will not continue until a valid input has been entered.

An example of the use of GETR is shown as follows:

ITEM User Command GETR Enter a user command: {}80,,{} EXEC %

The preceding passes the user-typed string as a command to be executed by the EXEC command.

NOTE: The R in GETR stands for Required input.

The GETP Command The GETP command works in a manner similar to the other GETx commands described in this chapter. A special feature of GETP is that it assigns a variable to the user input. This variable can then be used in other commands. An example of the use of the GETP command follows:

ITEM  Network Copy {PAUSE SHOW} GETP  Source: {} 60,, {} GETP  Destination: {} 60,,{} EXEC  NCOPY  %1 %2

The first GETP parameter assigns the user input to the variable %1, and the second GETP command assigns its user input to %2. These parameters are used in the EXEC NCOPY command as the source and destination, respectively.

NOTE: The P in GETP stands for Parameter variable.

Table 12.3 summarizes the different GETx commands.

TABLE 12.3 GETx Commands

GETx Command	Description
GETO	Obtains optional user input from the user.
GETR	Obtains required user input from the user.
GETP	Obtains user input that is assigned to variables %1, %2, and so on.

GETx Parameter Options

In the examples of the GETx commands in the previous section, you noticed the use of the curlies and the commas as part of the syntax of the GETx command. This syntax is part of a general syntax that gives you options to control the width of the user input and the initial value that is displayed for the user. You can also modify the user input by prepending and/or appending special text string values to the user input. The syntax of these parameters is shown as follows:

GETx  promptString, {prependString} length,prefillString,{appendString}

GETx  promptString, {prependString} length,prefillString,SECURE {appendString}

The x in GETx is replaced by O, R, or P, depending on which command you are using (see table 12.3). The promptString is the text that is displayed for the GET command and is used to prompt the user for the appropriate value. The prependString placed inside the curly braces is a string that is attached to the beginning of the data the user enters. If there is no value that you want to prepend to the entered data, you must enter the empty string inside the curlies. An example of the use of the prepend string is shown here:

ITEM  ZIP code for Montana Residents GETR  {MT }5,,{} EXEC  RecZip %

In this example the prepend string "MT" will be prepended to the supplied user input. RecZip represents a custom application that processes user-supplied data.

TIP: There is a difference between {} braces and { } braces. The former represents a null or empty string, and means that no value will be prepended to the user data. The latter represents a blank character that is prepended to the user data. These comments also apply to the {appendString} in the GETx command syntax.

The length specifies the size of the user input field. It is the number of characters the user can enter for the GET command. The length field is mandatory and can have a maximum value of 80 characters. The example that follows shows a maximum length field of 80 being used:

ITEM  Address Information GETR  Enter your street address {}80,,{} EXEC  RecData %

RecData in the EXEC command in this example is meant as an example of a custom application (RecData) that can process the user-supplied information.

The prefillString is the initial value that is placed in the user's response field. It is used as the default value that the user can accept, if the user chooses not to enter a different value. The prefillString is optional. The prefillString is separated from the length field by a comma and no spaces. If no prefill string is used, it can be omitted as shown in the following example:

ITEM  Get user information GETO  Enter your company name:{}50,,{} EXEC  RecData  %

This example shows a prefill string being used:

ITEM  Get user information GETO  Enter your company name:{}50,IBM,{} EXEC  RecData  %

Here, the "Enter your company name" field in the dialog box for the GETO command will have an initial value of IBM. The user can accept this value or override it with a different value. The user-supplied value is used as a parameter to a custom application called RecData.

The SECURE keyword is optional. If present, it must occur between the prefillString parameter and the {appendString} parameter. If the SECURE keyword exists as part of the GET command syntax, it means that the typed-in user data will not be displayed (hidden). This is useful if the user wants to enter a password, security code, or some other confidential data. An example of the use of the SECURE keyword is as follows:

ITEM  Security Information GETR  Enter Personal Identification Number(PIN): {}4,,SECURE{} EXEC  ValidPIN %

The ValidPIN in the EXEC command is meant to signify a custom application--one that, perhaps, validates the user-supplied PIN data.

The appendString placed inside the curlies {} is a string that is attached to the end (appended) of the data the user enters. If there is no value that you want to append to the entered data, you must enter the empty string inside the curlies {}. An example of the use of the append string is shown here:

ITEM  Security Information GETR  Enter Personal Identification Number(PIN): {}4,,SECURE{KXVZ} EXEC  ProcPIN

In this example, the append string "KXVZ" will be appended to the supplied user input. The ProcPIN represents a custom application that processes the user-supplied data. In this example the append string is used as a special security code that is sent in conjunction with the user-supplied data to the processing program ProcPIN.

If several GET commands are listed under an ITEM command, the GET fields are grouped in the order of occurrence with 10 GETs per dialog box. In other words, there can be a maximum of 10 GET command prompts per dialog box. If you want to override this default behavior and have a GET command appear in its own dialog box, you must use the caret (^) at the beginning of the prompt text for the GET command. The following example shows how each of the GET commands can appear in their own dialog box:

ITEM  Enter User Information GETP  ^User Name:{}50,,{} GETP  ^Address:{}80,,{} GETP  ^Password:{}30,,SECURE{} EXEC  ProcUser %1 %2 %3

The ProcUser represents a custom application that processes the user-supplied input.

There can be no more than 100 GET commands per ITEM command. Also, the GETO and GETR commands must be entered between the ITEM and the EXEC line that is associated with them. The general syntax of the GETx command is as follows:

GETx  promptString, {prependString} length,prefillString,[SECURE]{appendString}

The brackets ([ ]) around SECURE imply that SECURE is optional; it is not part of the syntax for GETx.

Table 12.4 summarizes the different GETx parameters that have been discussed here.

TABLE 12.4 GETx Parameters

GETx Parameter	Description
promptString	This is the message that must be displayed to the user.
prependString	The user-entered data is prepended with the prependString placed in the first set of curlies {}.
length	Maximum number of characters for the user field. Its maximum value is 80 characters.
prefillString	The prefillString is used as the default response, in case the user does not enter a value.
SECURE	The user-typed information is not displayed. Used for secure data such as passwords and codes.
appendString	The user-entered data is appended with the appendString placed in the first set of curlies {}.

Converting NetWare 3.x Menus

Older menu script files (MNU extension) that were used with the scripting language of the NetWare 3.11 Novell Menus utility can be converted to the NetWare 4.x menu script language using a conversion tool called MENUCNVT.EXE. The conversion process is shown in figure 12.3.

Figure 12.3 The Novell menu conversion process.

If the older Novells script file is named MAIN.MNU, to convert, compile, and run the menu using the NetWare 4.x menu system, you can perform the following steps:

1. MENUCNVT MAIN.MNU (Produces a MAIN.SRC file)

2. Examine MAIN.SRC file and edit as necessary

3. MENUMAKE MAIN.SRC (Produces a MAIN.DAT file)

4. MENU MAIN.DAT

TIP: The MENUCNVT.EXE program does not always do a complete translation. You can expect to do some manual editing of the SRC file to make the menus behave as expected.

This chapter examined the new Novell Menus utility (NMENU) for creating menu-driven interface. This utility is an improvement over the NetWare 3.11 MENU.EXE utility. NMENU is based on the popular Saber menus.

You learned how to create a menu source file, how to compile a menu, and how to convert NetWare 3.x menus to NetWare 4.x format.

Migrating to Netware 4.1 -- Ch 12 -- Setting Up Menus