
                             AUMenu for UNIX
                              Version 1.4.2
                 Copyright (c) 1996-99 Eugenio J. Alvarez
                           All Rights Reserved

                              September 1999

What is AUMenu?

  AUMenu is a multi-platform menu shell. It creates an environment that
  is easily understood. You simply select from a list of numbered items by 
  using the arrow keys or keying in the number of an item, then pressing the 
  enter key to execute the command. Another means of selection is a hot key 
  character that can be assigned for each menu item. Pressing a hot key 
  character immediately executes its associated item.  Menus are created 
  with the AUMenu script language. The AUMenu script language is easy to 
  learn and use. 


Features

   User Interface Features
     . Simple selection of menu items with only arrow keys and enter key.
     . Quick execution of menu items via hot key characters.
     . Help text or a help file can be assigned to Menu/Menu Items.
     . User prompting to complete a menu item command.
     . Screen colors can be defined for each menu.

   Security Features
     . Passwords can be assigned to Menus/Menu Items. 
     . Limit User and/or Group access to Menus/Menu Items.

   Administrative Features
     . Optional Autologout/Exit after a configured amount of inactive minutes.
     . Optional Screen Saver with changable message.
     . Optional Logging when and who executes a menu item.

   Design Features
     . Uses simple menu script language to create menus.
     . Supports a large number of menus and menu items.

   Portability Feature
     . Menu scripts are usable on multiple Operation Systems.

   Value Licensing Feature
     . Unlimited number of users per computer.



AUMenu Script Language

  Each Menu contains items. Items are mostly a title and an operating system 
  command to execute. This is an example menu item:

  ItemTitle=List directory with the unix ls command.
  ItemExecp=ls
  ItemEnd

  Each menu item begins with the keyword ItemTitle and ends with the keyword
  ItemEnd.

  Sometimes the output of an operating system command should continue to be 
  displayed until pressing the enter key. The above example waits for an enter 
  key after the command is executed. This lets the user see the results of the 
  command. Sometimes seeing the results are not necessary, in this case use 
  ItemExec instead of ItemExecp. The p at the end means prompt. So, if you 
  want to execute a command then return immediately to AUMenu you would write
  the following:

  ItemTitle=Run vi editor and don't wait when vi is done.
  ItemExec=vi  
  ItemEnd

  If you want to execute a command then automatically exit AUMenu you would 
  write the following.
 
  ItemTitle=Transfer a file via Zmodem then exit AUMenu.
  ItemExecExit=zmodem file
  ItemEnd
 
  If you want to prompt before exiting use the ItemExecpExit command.

  MenuItems are always inside menus. Here is a simple menu example:

  MenuBegin MainMenu

    ItemTitle=List directory with the unix ls command.
    ItemExecp=ls
    ItemEnd

    ItemTitle=Run vi editor and don't wait when vi is done.
    ItemExec=vi  
    ItemEnd

    ItemTitle=Exit Menu.
    ItemExit
    ItemEnd

  MenuEnd MainMenu

  Menus always begin with the keyword MenuBegin and end with the keyword 
  MenuEnd. The above menu name "MainMenu" is a special menu. Each script
  file must have one menu named "MainMenu". This is the first menu displayed
  when AUMenu begins.  A new command, ItemExit, is included in the above 
  example. ItemExit is a command inside a menu item that exits AUMenu.

  The Above menu does not have a title. Each menu can have up to three 
  lines describing the menu. Menu titles are entered after the MenuBegin
  line. Here is a script with a menu title:   
 
  MenuBegin MainMenu

    MenuTitle1=Menu Title line 1.
    MenuTitle2=Menu Title line 2.
    MenuTitle3=Menu Title line 3.

    ItemTitle=List directory with the unix ls command.
    ItemExecp=ls
    ItemEnd

    ItemTitle=Run vi editor and don't wait when vi is done.
    ItemExec=vi  
    ItemEnd

    ItemTitle=Exit Menu.
    ItemExit
    ItemEnd

  MenuEnd MainMenu

  Menu titles are optional. You can have just one line describing the menu
  or none.
 
  Sometimes you need a little more text to describe a menu command than the
  ItemTitle provides. The ItemNote keyword is used for this purpose.  Text 
  associated with the ItemNote is displayed in the lower left hand corner 
  of the screen. Here is an example:   

  ItemTitle=List directory with the unix ls command.
  ItemNote=Additional information displayed on the lower part of the screen.
  ItemExecp=ls
  ItemEnd


Calling Additional Menus

  Creating and calling other menus is easy. Just remember that each menu in a 
  script file must have a unique name. Here is an example:     
 
  #
  # pound sign begins a comment.
  # ----------------------------
  MenuBegin MainMenu

	# Up to three title lines per menu.
	# ---------------------------------
	MenuTitle1=Title1
	MenuTitle2=Title2
	MenuTitle3=Title3

	#
	# The ItemMenu keyword calls another menu.
	# ----------------------------------------
	ItemTitle=Item that calls another menu.
	ItemMenu=SubMenu
	ItemEnd

        ItemTitle=Item that exits this program and menu.
	ItemExit
	ItemEnd
	
  MenuEnd MainMenu 

  #
  # Using Submenu as an example menu name, could be any name.
  # ---------------------------------------------------------
  MenuBegin Submenu

	#
	# The ItemReturn keyword returns to the previous menu.
	# ----------------------------------------------------
	ItemTitle=Sub menu item title.
	ItemReturn
	ItemEnd

  MenuEnd Submenu

  Two keywords are introduced in the above example, ItemMenu and ItemReturn.
  ItemMenu calls another menu. ItemReturn returns to the menu that called it.
  ItemReturn exits the menu program if called from the "MainMenu" menu.


Adding Help

  Help is accessed via the question mark character ?. Menus and menu items
  can have associated help text and/or a help file. Example:

  MenuBegin MainMenu

	MenuTitle1=Title1

	# If a menu item has no assigned help this help will be displayed.
        # Use the MenuHelp for small amounts of help text. Less than a screen.
	# --------------------------------------------------------------------
	MenuHelpTitle=Help title here.
	MenuHelp=Help text here.
	MenuHelp=More help text here.

        # Use MenuHelpFile for large amounts of help text. 
	# ----------------------------------------------------------------
	# MenuHelpFile=${AUMENU_HOME}/help/help.txt

        # Use the ItemHelp for small amounts of help text. Less than a screen.
	# --------------------------------------------------------------------
        ItemTitle=List directory with the unix ls command.
        ItemExecp=ls
	ItemHelpTitle=Help title here.
	ItemHelp=Help text here.
	ItemHelp=More help text here.
        ItemEnd

        # Use the ItemHelpFile for large amounts of help text. 
	# ----------------------------------------------------------------
        ItemTitle=List directory with the unix ls command.
        ItemExecp=ls
	ItemHelpFile=${AUMENU_HOME}/help/ls.hlp
        ItemEnd

        ItemTitle=Item that exits this program and menu.
	ItemExit
	ItemEnd
	
  MenuEnd MainMenu 


Customizing AUMenu's Text

  The prompt text and navigation text, which is the text below the prompt,
  can be changed to suit your needs. The MenuPrompt and MenuNavText 
  commands specify the Prompt text and Navigation text respectively.
  Additional text can also be display on the border. The commands to 
  display text on the border are MenuHeader and MenuFooter. The MenuHeader
  displays text centered on top of the menu border. The MenuFooter command
  displays text centered on the bottom of the menu border.
  An Example : 

  MenuBegin MainMenu

        # Specify the Header text for this menu.
	# ----------------------------------------------------------------
        MenuHeader=This text is displayed on the top of the border

        # Specify the Footer text for this menu.
	# ----------------------------------------------------------------
        MenuFooter=This text is displayed on the bottom of the border.

        # Specify Prompt text for this menu.
	# ----------------------------------------------------------------
        MenuPrompt=Menu prompt here

        # Specify Navigation text for this menu.
	# ----------------------------------------------------------------
        MenuNavText=Menu navigation text

        # Specify a bar border for this menu. 
        # See the "Customizing AUMenu's Border" section for a description 
        # of the MenuDisplay command.
	# ----------------------------------------------------------------
        MenuDisplay=BarBorder

	MenuTitle1=Title1

        ItemTitle=List directory with the unix ls command.
        ItemExecp=ls
        ItemEnd

        ItemTitle=Item that exits this program and menu.
	ItemExit
	ItemEnd
	
  MenuEnd MainMenu 


Customizing AUMenu's Border

  Normally, AUMenu's border is a box style display.  This can be changed 
  to display a bar style border or no border. The command to control a menu's 
  border is MenuDisplay. The possible options for MenuDisplay are BarBorder, 
  BoxBorder and NoBorder. See the "Customizing AUMenu's Text" example for an 
  example use of the MenuDisplay command.


File Level Commands

  Many of the menu commands can be applied to all menus in a script. These 
  include FilePrompt for MenuPrompt and FileNavText for MenuNavText. Other 
  file level commands include FileHeader, FileFooter, FileHelpTitle and
  FileHelp.  File level commands must be placed in the beginning of the 
  script before any menus are defined. 
   
  An Example of some file level commands :

  # Define prompt text for all menus in this script. The %d is changed to
  # the number of menu items in the menu. The %d is optional.
  # ----------------------------------------------------------------
  FilePrompt=My custom prompt text (1-%d)

  # Define navigation text for all menus in this script.
  # ----------------------------------------------------------------
  FileNavText=My custom Navigation text


Prompting to Complete a Command
 
  Sometimes an Operating System command has to be completed by a user. Here 
  is an example of how to create a menu item to telnet to another machine.

    ItemTitle=Telnet to another machine
    ItemExec=telnet %Enter machine name to telnet%
    ItemEnd
 
  The words inside the percent characters are used to prompt the user for 
  the name of a machine. The prompt words and percents characters are then 
  replaced by the user's response. So if the user enters a machine name of 
  foobar the command that would be executed would be 'telnet foobar'.

  Each menu item can have up to four substitutions in the ItemExec line.
  An example with four substitutions:

     ItemTitle=Program with for options to replace at runtime.
     ItemExec=theprogram %Enter one% %Enter two% %Enter three% %Enter four%
     ItemEnd

  The prompted options are required to execute the command. To make the options
  optional use the ItemExecParam command. Here is an example to make the 
  second argument optional:

     ItemTitle=Program with for options to replace at runtime.
     ItemExec=theprogram %Enter one% %Enter two% %Enter three% %Enter four%
     ItemExecParam2=optional
     ItemEnd
   
  If you do not want to display the substituted text while entering it, use the 
  password argument to the ItemExecParam command. The next example hides the 
  text entered in the first argument.

     ItemTitle=Program with four options to replace at runtime.
     ItemExec=theprogram %Enter one% %Enter two% %Enter three% %Enter four%
     ItemExecParam1=password
     ItemEnd

  You may combine the optional and password statements on the ItemExecParam 
  line by separating the words with a comma. Here is an example:

     ItemTitle=Program with four options to replace at runtime.
     ItemExec=theprogram %Enter one% %Enter two% %Enter three% %Enter four%
     ItemExecParam1=optional,password
     ItemEnd


Dyanamic text via environment variables

   The text in the MenuTitle, ItemTitle and ItemNote can contain environment 
   variables that are replaced at runtime. Two forms of inserting environment 
   variables are supported. One with curly brackets and the other without. 
   Here is an example :
   
     ItemTitle=Program $HOME ${HOME}.
     ItemExec=ls $HOME
     ItemEnd


Setting a working directory

   A Menu or individual menu item can set its working directory before 
   executing its associated command. An example :

   MenuBegin MenuName

       MenuDir=$HOME

       ItemTitle=Execute command in /tmp directory
       ItemExec=ls
       ItemDir=/tmp
       ItemEnd

   MenuEnd MenuName

   As the example above illustrates, environment variables can to used to 
   specify directories. The MenuDir command sets the directory for all the
   items in a menu. If an individual menu item needs to be executed in a 
   specific directory the ItemDir command can specify the appropriate 
   directory. 


Executing a command when entering or leaving a menu

   The MenuExec command can execute a command upon entering a menu as well as 
   before leaving a menu. An example :

   MenuBegin MenuName

       MenuDir=$HOME

       MenuExec=Execute this command upon entering this menu

       ItemTitle=Execute command in /tmp directory
       ItemExec=ls
       ItemDir=/tmp
       ItemEnd

       MenuExec=Execute this command before leaving this menu.

   MenuEnd MenuName


Access to Items

  Limiting access to items is achieved with two keywords, ItemUser and 
  ItemUserGroup.  When a user does not have access to an item it is 
  not displayed. Here is an example limiting menu item access to one user:

  ItemTitle=List user on system
  ItemUser=user1
  ItemExecp=who
  ItemEnd
  
  Limiting access to just a few users is easy. Here is an example:

  ItemTitle=List user on system
  ItemUser=user1,user2,user3
  ItemExecp=who
  ItemEnd

  Perhaps you want to limit access to an item based on the group a user 
  belongs to. Here is an example of limiting access based on group:

  ItemTitle=List user on system
  ItemUserGroup=group1,group2
  ItemExecp=who
  ItemEnd


Access to Items (Short Cuts)
 
  If all or most of the items on a menu will only be accessible by a user 
  or group two additional keywords come in handy, MenuUser and MenuUserGroup.  
  Here is an example: 
  
  #
  # Example Menu using keywords MenuUser and MenuUserGroup  
  # ---------------------------------------------------------
  MenuBegin Submenu

	MenuUser=user1
	MenuUserGroup=group1

	#
	# This menu item will only be accessible by user1 or group1 
	# -----------------------------------------------------------
	ItemTitle=Menu item for user1 or group1.
	ItemExecp=echo hello user1 or group1	
	ItemEnd

	#
	# This menu item will only be accessible by user2 or group2 
	# -----------------------------------------------------------
	ItemTitle=Menu item for user2 or group2.
	ItemUser=user2
	ItemUserGroup=group2
	ItemExecp=echo hello user2 or group2	
	ItemEnd

  MenuEnd Submenu


Password Protected Menu Items

  Any menu item can be protected via a password. Additional configuration
  of the AUMenu program and script file are required to prohibit users from
  casually reading the script file to determine a menu item password. Refer to
  the installation section for details on how to setup AUMenu for passwords.
  Here is an example script:

  MenuBegin MainMenu

	#
	# Example item with a password. 
	# ----------------------------------------
	ItemTitle=Item that is password protected.
	ItemExecp=echo hello
	ItemPassword=mypass
	ItemEnd

        ItemTitle=Item that exits this program and menu.
	ItemExit
	ItemEnd
	
  MenuEnd MainMenu 


Hot Keys

  Any menu item can be assigned a hot key character. Available hot key 
  characters are the 26 letters in the english alphabet. 

  MenuBegin MainMenu

	#
	# Example item with a hot key. 
	# ---------------------------
	ItemTitle=Press the letter Z to execute this menu item.
	ItemExecp=echo hello
	ItemKey=Z
	ItemEnd

        ItemTitle=Item that exits this program and menu.
	ItemExit
	ItemEnd
	
  MenuEnd MainMenu 


Menu Colors

  Any menu can be assigned a foreground and background color via the AUMenu 
  script language.

  Valid colors are: black, blue, green, cyan, red, magenta, yellow and white.

  MenuBegin MainMenu

	#
	# Menu color will have a black foreground color and white background.  
	# -------------------------------------------------------------------
	MenuColor=black-white

	ItemTitle=Echo hello
	ItemExecp=echo hello
	ItemEnd

        ItemTitle=Item that exits this program and menu.
	ItemExit
	ItemEnd
	
  MenuEnd MainMenu 


AUMenu as a User's Login Shell
 
  There are several options to use AUMenu as a login shell.
 
  Option 1: Call AUMenu from a shell startup script.
  Option 2: Exec AUMenu from a shell startup script.
 
  If AUMenu is exec'd in a startup script (.profile, .cshrc, etc ) the user 
  is automatically logged off the system after exiting AUMenu. If AUMenu is 
  called, but not exec'd the user will return to the unix prompt. Setting up 
  AUMenu as a shell from the password file is not recommended.


Installation 

  Make the aumenu home directory /opt1/local/aumenu or /usr/local/aumenu.
  Copy menu, menuview, menucfg and the default system menu script to that 
  directory.  Configure the aumenu executable to read the system default 
  menu script file (example below). Add a symbolic link to the AUMenu 
  executable to a directory on the users path. 

  To use passwords I suggest that an aumenu user be created on the system. 
  The aumenu executable and script should be owned by this user (Only the 
  aumenu user should have read access to the script file). Set the suid bit 
  on the aumenu executable. After AUMenu reads the script it sets its suid 
  bit back to the normal permissions of the user that is running it. Here 
  are the example Unix commands to set the suid bit and change permissions 
  on a the script file.

  chmod 4711 menu
  chmod  600 menu.mdf

  The first command sets the suid bit and removes read access to the 
  executable to all except the owner. The second command provides read and
  write access only to the owner of the file.  The owner should be a user 
  login setup to own and administer AUMenu. 


Setup/Configuration 
  
  The menucfg program changes several defaults in the AUMenu executable.

  Set the default menu script 
    menucfg menu -menu default_menu.mdf
  Examples:
    menucfg menu -menu my.mdf
    menucfg menu -menu /opt1/local/aumenu/my.mdf
    menucfg menu -menu /usr/local/aumenu/my.mdf
  
  AUMenu also checks the environment variable AUMENU_SCRIPT. If this 
  environment variable is set it is used as the default menu script.
  

  Set the number of minutes before exiting/logout out of AUMenu.
    menucfg menu -autologout minutes

  Set the number of minutes before activating the Screen Saver.
    menucfg menu -screensaver minutes

  Set the Screen Saver message.
    menucfg menu -screensavermessage "message"

  Set log file name. 
    menucfg menu -logfile logfile.log
  
  Enable logging.
    menucfg menu -logenable

  Disable logging.
    menucfg menu -logdisable

  Determine logging status.
    menucfg menu -logstatus

  Set the default menu color.
    menucfg menu -color fgcolor-bgcolor

  Set the exit window prompt color.
    menucfg menu -ewcolor fgcolor-bgcolor

  Set the password window prompt color.
    menucfg menu -pwcolor fgcolor-bgcolor

  Valid colors are: black, blue, green, cyan, red, magenta, yellow and white.

  fgcolor is the foreground color.
  bgcolor is the background color.


Multi-Platform Menu Script file 

  Since AUMenu is available on multiple Operating Systems the keyword ItemOS
  is available to create script files that can work on different operating 
  systems. Here is an example:

  #
  # Example Menu using keyword ItemOS 
  # ---------------------------------
  MenuBegin Submenu

	#
	# This menu item will only be seen on the Solaris Operating System 
	# ----------------------------------------------------------------
	ItemTitle=Display processes in memory.
	ItemExecp=ps -ef	
	ItemOS=Solaris
	ItemEnd

	#
	# This menu item will only be seen on the FreeBSD Operating System 
	# ----------------------------------------------------------------
	ItemTitle=Display processes in memory.
	ItemExecp=ps -aux	
	ItemOS=FreeBSD
	ItemEnd

  MenuEnd Submenu
 
  Valid Operating System names for the ItemOS keyword are: 
	1)Solaris
	2)SunOS
	3)BSDI
	4)FreeBSD
	5)Linux
	6)IRIX
	7)SCO
	8)DOS 


                       DISCLAIMER OF WARRANTY

   THIS SOFTWARE AND MANUAL ARE DISTRIBUTED "AS IS" AND WITHOUT
WARRANTIES  AS TO PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES
WHETHER EXPRESSED OR IMPLIED.  BECAUSE OF THE  VARIOUS HARDWARE AND 
SOFTWARE  ENVIRONMENTS INTO WHICH THESE PROGRAMS MAY  BE  PUT,  NO 
WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED.

   GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY
TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT.  THE USER  MUST ASSUME
THE ENTIRE RISK OF USING THE PROGRAM.  ANY LIABILITY OF THE SELLER WILL 
BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE.
 

Distribution

The DOS version of AUMenu for Unix may be distributed freely as long as the 
contents of this package is not modified in anyway, excluding archiving
in a different format.


Trademarks

   UNIX is a registered trademark of the X/Open Consortium.


Closing Notes

Please contact me for any questions, comments or bugs........

   Send a check or money order in the amount of $49 US dollars per machine 
along with an order form to the address below to receive your registered copy
of AUMenu for Unix. If you can't find the order form, print the following 
WWW URL: http://members.aol.com/aumenu/order.html . For prompt handling
of your order send an email to alvareze@aol.com stating that you have sent 
payment via postal mail.

U.S. Mail
Eugenio Alvarez 
12337 N.W. 98th Court
Hialeah Gardens, FL 33018 USA

E-Mail
alvareze@aol.com

World Wide Web 
http://members.aol.com/aumenu/index.html

