;


		      The ZCPR3 VMENU Shell

		      -- ZCPR3 Utilities --
			 1 - VMENU
			 2 - VMENUCK

	 -- Using VMENU --	     -- Programming VMENU --
     U - Using VMENU	       P - Programming *.VMN Files
     S - Summary of User Cmds  C - *.VMN Internal Commands
     E - VMENU Error Messages  M - Programming Cmd Summary
				   Z - VMENU and ZCPR3

:1
Command:  VMENU 1.6

Syntax:
     VMENU	     <-- run MENU.VMN on all files in dir
or
     VMENU afn	     <-- run MENU.VMN on files selected by afn
or
     VMENU afn ufn   <-- run menu (ufn) on selected files

Function:

     VMENU  is the ZCPR3 menu front-end processor.   It is a
ZCPR3 Shell which reads a *.VMN file and processes  commands
from it.

Options:  None

Comments:
     VMENU  is a true ZCPR3 Shell.   It is described in this
HELP file.
Selected Error Messages:

     "No Command Line" means that the ZCPR3 System does  not
support  an external Command Line Buffer.   VMENU must	have
this to run.

     "No  Shell Stack" means that the ZCPR3 System does  not
support a Shell Stack.	VMENU must have this to run.

     "Shell  Stack Full" means that the Shell Stack is	full
and VMENU cannot push itself onto the stack.

     "Shell  Stack Size" means that the Shell Stack elements
are too short for VMENU to store its parameters.

     "TPA  Full" means that there is not enough room in  the
TPA to load the *.VMN file.

Examples of Use:
     See this HELP file

     VMENU is the ZCPR3 Menu-Oriented Command  Preprocessor.
It  acts as a front-end to ZCPR3,  providing a menu-oriented
user interface to ZCPR3.  Its function can be represented by
the following diagram:
		  -------    -------	-------    -------
		  |V	|    |Z    |	|B    |    |P	 |
   User 	  | M	|    | C   |	| D   |    | g	 |
   Menu      ---->|  E	|--->|	P  |--->|  O  |--->|  m  |
   Command	  |   N |    |	 R |	|   S |    |   s |
		  |    U|    |	  3|	|     |    |	 |
		  -------    -------	-------    -------

     The "User Menu Command" is a single character that  the
user  strikes  which instructs VMENU to perform a  function.
Once  VMENU  begins processing this function,  it  builds  a
command  line  for ZCPR3,  optionally asking  the  user  for
further  input	(such as a file name),	and then passes  the
command  line to ZCPR3 via the Command Line  Buffer.   ZCPR3
then runs the command line returns to VMENU.

     VMENU  builds command lines based on simple input	from
the user.   The user need never know what the actual command
line is.  The command line itself is always of the form:

	      <command> <optional user input>

     As  an example,  a command built by VMENU to  run	XDIR
with  user input for a file name specification,  could	look
like the following:

		     XDIR <user input>


     When VMENU is executed, it builds the list of  files to
be displayed, and then looks for the  desired menu file.  It
begins its search in  the current directory,  and  continues
along  the system  path  until either  it has found the menu
file,  or  all	directories in	the path  have been searched
without success.  If the menu file is found, it will be read
into  memory, and  the first menu displayed.   If it was not
found, an error message will be generated.
      If  no menu file is specified, then VMENU will default
to MENU.VMN.  If the user  has supplied a file ID  with both
the menu file name and type,  VMENU  will use this file.  If
only  the file name is	specified, the default	file type of
VMN is assumed.

     The  MENU.VMN  file can contain up to 255 menus  to  be
processed by VMENU.   The VMENU will begin processing at the
first menu in MENU.VMN.


     VMENU  itself  is a COM file,  like any  other  program
under  ZCPR3.	Unlike	most  other  programs,	however,  it
generates  command lines to be executed by ZCPR3 and  stores
its  return command in the Shell Stack.   In this way a loop
is set up:

	       -->--+->- VMENU ->- ZCPR3 ->-+
		    ^			    v
		    |			    |
		    +-<- Command Line -<----+

     Only  VMENU  itself  or a ZCPR3 tool  like  SHCTRL  can
terminate this loop.  If the VMENU programmer wishes, he can
set  up  the MENU.VMN file so that this loop will  never  be
exited, or he can set up the file to allow anyone to exit at
any  time or just a special person who knows a	password  to
exit  when  he	wishes to.   There is a lot  of  flexibility
designed into the system,  and it will be discussed later in
the section on programming MENU.VMN files.
     A MENU.VMN  file can be set up to execute	any  ZCPR3
command or sequence of commands.  The MENU.VMN file can also
be set up to not allow the user to leave VMENU, to allow him
to leave VMENU at will,  or to allow him to leave VMENU only
if he knows a password.

     This  HELP file is divided into two basic	parts.	 The
info  sections	on  "Using  VMENU"  and  "Summary  of  VMENU
Commands" are designed to be read by a person wanting to use
VMENU  but  not wanting to learn how VMENU works or  how  to
program  it.   These sections describe how to move from  one
menu  to another,  how to issue VMENU commands,  and how  to
leave VMENU if the option is presented to him.

     The  other  sections  of this HELP  file  describe  the
programming  aspects of VMENU and are intended to be used as
an  online reference for the VMENU  programmer.   The  VMENU
command  programming summary is especially useful in that it
provides   a  summary  of  the	commands  which  the   VMENU
programmer may issue to VMENU within a *.VMN file.
:U

     When VMENU is first invoked,  it will be installed as a
Shell.	If commands are pending, control will return to  the
ZCPR3  command processor for the next command in  the  line.
When the command line is exhausted,  ZCPR3 will realize that
a shell has been installed and invoke VMENU as a shell.   If
there are no pending commands, however, VMENU will begin the
menu command processing immediately.

     When VMENU begins	execution as a	Shell,	it will load
the names of the  selected  files  in the current directory,
load the menu file, and display up  to sixteen files and the
first menu in the menu file to the user.  The user will then
be prompted for a command.

     To refresh the  VMENU display,  press ^R.   To sort the
list of files in the alternate order, press ^Q.  To log into
a different directory, press ^N.


     The VMENU display is divided into two  distinct halves.
The upper half consists of up to 16 files from the  selected
list of files.	The file pointer (--->) is used to indicate
the current file, whose name and type may be used by command
lines in the current menu.  The name of the current file  is
displayed in the upper right corner of the display.

     The following movement comands are available to allow
the file pointer to be moved to the desired file:

     <SP> - Advance to next file name.	Wraparound from last
to  first  may occur.	The Word Star ^D character  or	your
right  arrow  key (if available in the Z3TCAP)	perform  the
same function.

     <BS>  - Back  up to last file  name.   Wraparound	from
first to last may occur.  The Word Star ^S character or your
left arrow key (if available in the Z3TCAP) perform the same
function.

     +	- Jump to Next Screen (if any).   If there  is	more
than  one screen of files,  the user is advanced to the next
screen. If at the last screen, wraparound to first.  ^F also
performs this function if not overridden by arrow keys.

     - - Jump to Last Screen (if any).	 Similar to + but in
the opposite direction.  May wraparound to the last screen.
^A also performs this function if not overridden by arrow.

     ^T - Move to first file in current screen.
     ^B - Move to last file in current screen.

     Word Star arrow key movement (if not overriden by arrow
keys in Z3TCAP):
			     ^E
			      ^
			 ^S <-+-> ^D
			      v
			     ^X


     The second half of the display consists of the  current
menu, and  the	menu  command prompt which has the following
general form:

Command (CR=Menu,^C=Z3,*=1st Menu,<=Prev Menu,>=Next Menu) -

     There  can  be up to 255 menus in one  VMENU.VMN  file.
The  VMENU  command  prompt varies  to	reflect  this.	 For
instance,  if  only  one Menu was present and the option  to
abort out of VMENU to ZCPR3 was not available, then the Menu
Command prompt would take its simplest form, looking like:

Command (CR=Menu) -

     Strike  ^R at this time to refresh the Menu Display, ^N
to log into  a different directory, or strike  the character 
of a Menu Option.   These are the only choices, and striking
a character  which is  not the  RETURN key or a menu  option 
results in the bell sounding.


     If  the  the option to exit to ZCPR3 was available  and
there  is  only  one Menu in the  MENU.VMN  file,  then  the
command line will look like this:

Command (CR=Menu,^C=Z3) -

     The  option of aborting to ZCPR3 by striking  Control-C
(hold  down  on the Control,  or CTRL,	key and  strike  the
letter C) is now available.   This will return to ZCPR3  and
exit VMENU.

     One  brief note on option letters before going on.   If
one  of your options is a letter in the range from A  to  Z,
then case is not significant,  and you can invoke the option
A, say, by striking an upper- or lower-case A.


     If  there is more than one menu in the *.VMN file,  the
command line options become slightly more complex,  but they
are still quite easy to follow.

     In  the following examples,  assume that the option  to
exit to ZCPR3 is off, so the "^C=Z3" option will NOT appear.

     From the first menu in the file,  the command line will
look like the following:

Command (CR=Menu,>=Next Menu) -

     To advance to the next menu,  strike the ">" or the "."
character.   On most keyboards, ">" is the shift of the ".",
so VMENU permits easy movement without having to worry about
shifting the keyboard all the time.


     If at the last menu in the file,  the command line will
look like the following:

Command (CR=Menu,*=1st Menu,<=Prev Menu) -

     This  allows  the user to strike the "*"  character  to
jump  back to the first menu in his *.VMN file.   If "<"  or
","  is struck ("<" is usually the shift of the  ","),	then
the  user will back up one menu to the previous menu in  the
file.

     If the user is somewhere in the middle of the  MENU.VMN
file, his command line will look like this:

Command (CR=Menu,*=1st Menu,<=Prev Menu,>=Next Menu) -

     Again,  "*" will go directly to the first menu,  "<" or
"," will go to the previous menu,  and ">" or "." will go to
the  next  menu.   Striking the RETURN key will refresh  the
menu display.

     One  last	option	the  user  has	under VMENU involves
access to a System Menu.  This menu is special in that there
is only one way to get to it -- via the "$" command.

     The  System  Menu is intended to give priveleged  users
access to special commands that the rest of the users  can't
run.   If  a System Menu is available, VMENU will respond to
the "$" command with the prompt:

	  Pass?

     The  user	is given one chance to type in	the  correct
password  to enter the System Menu.   If he  is  wrong,  the
message "Password Error" will appear and he will be returned
to the menu he came from.   If he is correct,  he will enter
the System Menu.   Physically, the System Menu is always the
last menu in the file, and its command prompt is:

Command (CR=Menu,*=1st Menu,<=Prev Menu) -

     If the user is at the menu just before the System Menu,
the ">" will not function to allow him to enter it, even tho
there  technically is a "Next Menu".   The ">" option in the
command  line  will not appear.   The only way	to  enter  a
System Menu is thru the "$" command.



     In  summary,  moving about within VMENU is quite  easy.
"*"  moves the user to the first menu,	"<" to the  previous
menu, ">" to the next menu.

:S

     The full VMENU Command Line looks like the following:

Command (CR=Menu,^C=Z3,*=1st Menu,<=Prev Menu,>=Last Menu) -

     The Menu Commands are:

       Command	 Function

       ^N	 Log into new Directory
       ^R	 Refresh Menu Display (RETURN Key)
       ^Q	 Resort File Display
       ^C	 Exit to ZCPR3 (Control-C)
       *	 Jump to the First Menu
       < or ,	 Jump to the Previous Menu
       > or .	 Jump to the Next Menu
       $	 Jump to the System Menu (Password Required)
       other	 Menu Option or Invalid Command; letters are
		      automatically capitalized, so a=A

     Movement Commands --
	  ^E - Move Up (Wrap to Bottom)
	  ^X - Move Down (Wrap to Top)
	  ^D - Move Right (Wrap to First File of Next Line)
	  ^S - Move Left (Wrap to Last File of Previous Line)
	  ^F - Move Screen Right (Wrap to First Screen)
	  ^A - Move Screen Left (Wrap to Last Screen)
	  ^T - Move to First File in Current Screen
	  ^B - Move to Last File in Current Screen

     The  user's Z3TCAP entry may define four other  single-
character  commands  to  conform to the arrow  keys  on  his
specific  terminal.   These commands will override  the  set
described  above  if any conflicts exist (that is,  if	your
down-arrow key generates a ^E, ^E will now mean Move Down in
all cases).

     Screen  Left  and Right make sense when there  are  too
many files to fit on one screen.   In this case,  the  files
are  broken  into screen directories,  and Screen  Left  and
Right are used to move between them.
:P

		  Programming *.VMN Files

     The  *.VMN  file  is simply a text file  which  may  be
created  with  any  conventional  CP/M	 editor,   including
WordStar.   VMENU  ignores  the Most Significant Bit of  all
bytes, so editors like WordStar, which occasionally set this
bit, can be used.

     All *.VMN files have the same general  structure.	 The
first  line is either a global option line or the  beginning
of a menu display.   If a global option line, it begins with
the  character	"-",   and  this  character  is  immediately
followed  by  global option characters.   The global  option
line, then looks like this:

-options

     After the global option line,  if any,  comes the first
menu.  Each menu is structured as follows:

			 #options
			      <Text of Menu Display>
			 #
			 menu commands

     The following are two sample Menu File structures:

	       -options 		#options
	       #options 		     <Text>
		    <Text>		#
	       #			commands
	       commands 		##
	       #options
		    <Text>
	       #
	       commands
	       ##
     There are two option characters.  In using them, case
is not significant.  These option characters are:

	  Option    Function
	     C	    Display Command Line to User
	     X	    Allow User to Exit to ZCPR3

    The C option displays the command line built by VMENU to
the user.   This option is primarily intended for  debugging
purposes,  to  allow the programmer to see what commands are
being built.   It is instructive to the user,  however,  and
may be employed for that purpose as well.

     The  X  option enables the facility which	permits  the
user to type ^C and return to ZCPR3.

     When VMENU first comes up, all options are turned off:

	  C is OFF -- no command display to user
	  X is OFF -- the user cannot exit to ZCPR3.

     The  global options line,	which,	if present,  is  the
first  line  of the file,  turns on these  options  for  the
course	of  the session in general.   That is,	if a  global
options line like

	  -x

is used  (case	is insignificant),  then exit  to ZCPR3 will
be available for all menus.  The global options line affects
all menus.


     The global options line turns on the indicated  options
for all menus in general.   However, the same options may be
presented  on the first line of each menu immediately  after
the  "#"  character  to temporarily complement	the  current
option for only that menu.

     If  an  option is NOT included in	the  global  options
line,  it  is  turned  OFF for all menus  in  general.	 The
defaults  selected  by	using the global  options  line  are
overridden on a per-menu basis by the local menu options.

     Example:


    -x
    #x
	 No exit to ZCPR3 is permitted
    #
    commands
    #dx
	 No exit to ZCPR3.
    #
    commands
    #c
	 The user may exit to ZCPR3.  Additionally, the
	 MENU-generated commands are printed to the user.
    #
    commands
    ##

     Any  option that may appear on the global options line
may  also appear on the options line for a particular  menu.
The menu options line supports one additional  option,	viz.
"$".  This option declares the following menu to be a System
Menu.
     In  programming a *.VMN file, the VMENU programmer MUST
place the System Menu as the last menu in the file if it  is
going to have one.   To do otherwise is flagged as an error.
The  following illustrates a *.VMN file containing a  System
Menu:
       #
	 The user may not exit to ZCPR3.
       #
       commands
       #$x
	 This is a System Menu, and the user may exit to ZCPR3.
       ##

     If  a  menu is a System Menu,  the "$"  character	must
immediately  follow  the  "#".	 In the case of  the  letter
options in both the global and local cases, the order is not
important ("cx" means the same as "xc").

     The  password used to enter a System Menu is hard-coded
in.   It may be altered by reassembly or use of  DDT.	Note
that this password can be upper- and lower-case, and case is
significant.

:C

		       *.VMN Commands

     This   section  describes	the  technique	and  options
available  for creating command lines in *.VMN	files.	 The
information  herein is organized into the following  subject
areas:

	  o Syntax of the command line

	  o :nn Option

	  o ! Option

	  o & Option

	  o "text" prompts and input

	  o Variables ($C, $D, $U, $Fn, $Nn, $Tn, $Pp, $$)

	  o Highlighting (^A, ^B)

							   Syntax
     The commands in a *.VMN file follow a simple structure.
Each command occupies only one line,  and blank lines in the
command  group	are  not permitted.   The  command  line  is
structured as follows:

	  l[o][command]

where:
    l is the single character used to invoke the command
	 note that it may be upper- or lower-case
    o is an opening option, which is one of:
	 :nn  -- go to Menu nn
	 &dir -- Log into directory dir
	 !    -- have VMENU wait when the command is finished
    command is an optional ZCPR3 command; note that if
	 the option is ":nn", then a command here makes no
	 sense

							   :nn Opt
     The  ":nn"  option tells VMENU to move to	a  different
menu  in  the  *.VMN file.   The first	menu  is  number  1.
Example:

	  -x
	  #
	       1st Menu:  A - Goto Menu 2     3 - Goto Menu 3
	  #
	  a:2
	  3:3
	  #
		    2nd Menu Command: 3 - Goto Menu 3
	  #
	  3:3
	  #x
		    3rd Menu Command: 2 - Goto Menu 2
	  #
	  2:2
	  ##
							   :nn Opt
     In the first menu, the user may strike:

	  "a" or "A" to goto Menu 2
	  "3" to goto Menu 3
	  ">"  or  "." to goto the next menu (Menu 2)
	  ^C to goto ZCPR3

     In the second menu, the user may strike:

	  "3" to goto Menu 3
	  "*" or "<" or "," to goto Menu 1
	  ">" or "." to goto Menu 3
	  ^C to goto ZCPR3

     In the third menu, the user may strike:

	  "2" or "<" or "," to goto Menu 2
	  "*" to goto Menu 1

							   ! Opt
     The  "!" option causes VMENU to pause and ask the	user
to "Strike Any Key" before continuing after the command line
has  been processed.   In this way,  if a command  generates
information  to be read by the user before VMENU clears  his
screen,  the "!" option may be used to give the user all the
time he wants to read this display.

							   & Opt
     The "&" option causes VMENU to log into a new directory
which may be given as drive-user or named directory.
Example:

	-x
	#
		My menu:  A - go to a3    5 - go to help
	#
	a&a3
	5&help
	##

     After the  du or dir  specification, you may  declare a 
menu change by inserting a ';' after the du/dir,  and follow
that by the name of the new menu (.VMN) file.
Example:

	a&a3;ourmenu (case is not significant)
							   "prompt"
     Embedded  within  any command line may be a prompt  for
user input.  This prompt takes the form of

	  "prompt to user"

When  encountered,  VMENU will advance to the next line  and
print the text contained within the quotes.  VMENU will then
wait for the user to input any text he desires followed by a
RETURN.    At  this  point,  the  text	the  user  input  is
capitalized and placed into the command line at the point of
the prompt.

     If  the  prompt appears at the end of a  VMENU  command
line,  the trailing quote is not required.   As many prompts
as   desired  may  appear  within  a  VMENU  command   line.
Examples:

							   "prompt"
    -x
    #
	 A - Run XDIR without Pause or Input
	 B - Run XDIR and Pause before Returning to VMENU
	 C - Run XDIR, Allow User Input, and Pause before
	      Returning to VMENU
	 M - Run MCOPY, Allow User Input of Dest Dir, Allow
	      User Input of Source Dir and File, and Pause
	      before returning to VMENU
	 Z - Run Any ZCPR3 Command and Pause before
	      Returning to VMENU
    #
    m!mcopy "Destination Dir? "="Source DIR:AFN?  "
    z!"Enter Command Line --
    axdir
    b!xdir
    c!xdir "Enter Ambiguous File Name --
    ##

							   "prompt"
     Note  the Space right before the "Prompt form in the  C
command.   This space is significant to keep the command and
user  input from running together.   This "run together"  is
desired  for the Z command.   Also note the dual prompt  for
the M command.

     With the M command,  the following prompts will  appear
(and sample input):

	  Destination Dir? BACKUP:
	  Source DIR:AFN?  *.TXT

and the following command line is built:

	  MCOPY BACKUP:=*.TXT

							   Variables
     The  command  text  which	is specified  in  the  VMENU
command line can contain embedded variables which VMENU will
expand when the command line is processed.  These variables,
which  are denoted by a dollar sign ($) followed by  one  or
two characters, are defined as follows:

     Variable  Expands as
     --------  ----------
       $C      Current DIR ('Noname' if not defined)
       $D      Current Disk
       $U      Current User Area
       $Fn     FILENAME.TYP for ZCPR3 System File n
       $Nn     FILENAME for ZCPR3 System File n
       $Tn     TYP for ZCPR3 System File n
       $Pp     Name of File being Pointed to
       $$      Place a single $ in command line

     These  variables  can also be used in the menu  display
itself,  and  their  values  will be  substituted  when  the
display is generated.  Example:
							   Variables
   -x
   #
	       Menu to Run M80 Assembler
			      Current File: $F1
			      Directory: $D$U
	  F - Define File
	  E - Edit $F1	      P - Page $F1
	  A - Assemble $F1
   #
   fsetfile 1 "Filename? "
   eedit $f1
   azex m80 $n1
   ppage $f1
   ##

							   Variables
Notes:

     1. The ZCPR3 utility SETFILE is used to define the name
of  a  ZCPR3  System File.   There  are  four  System  Files
available,  and they can be referenced by $F1 to $F4, $N1 to
$N4, and $T1 to $T4.

     2.  The A command shows the execution of ZEX.  VMENU is
a true ZCPR3 Shell, and, as such, ZEX commands can be issued
from  it and will run on top of it.   The prompt for the ZEX
command lines will be "Menu>".

     3.  Assuming that "MYFILE.MAC" is assigned to the ZCPR3
System File 1 and the user is logged into disk B user 1, the
following  screen  shows how the display and  the  resulting
command lines will be expanded when execution occurs:

							   Variables
			  Display

	       Menu to Run M80 Assembler
			      Current File: MYFILE.MAC
			      Directory: B1
	  F - Define File
	  E - Edit MYFILE.MAC	     P - Page MYFILE.MAC
	  A - Assemble MYFILE.MAC


		       Command Lines
     Menu Command	      Expansion

   fsetfile 1 "Filename? "     SETFILE 1 "Filename? "
   eedit $f1		       EDIT MYFILE.MAC
   azex m80 $n1 	       ZEX M80 MYFILE
   ppage $f1		       PAGE MYFILE.MAC

							   Highlighting
     Just  like the HELP utility can take advantage  of  the
highlighting facility provided in the Z3TCAP,  so can VMENU.
For  those  ZCPR3  Systems with a  properly-installed  TCAP,
VMENU  will  use  the clear screen command  to	refresh  the
user's	screen and highlighting can be enabled and  disabled
by  embedding ^A (to turn on highlighting) and ^B  (to	turn
off highlighting) into the *.VMN file.

     It  is recommended that when highlighting is turned on,
it  should  be turned off in the same line  for  consistency
sake and appearance.

     Example:

							   Highlighting
   #
	  ^AThis is highlighted^B and this is not
   #

will appear with "This is highlighted" in a highlighted mode
like this:

	  This is highlighted and this is not


							   Variables

     The  $Pp  variable is also available to the user  under
VMENU.	 $Pp returns information on the file currently being
pointed to by the user on the screen.  This variable has the
following forms:

	  Form	    Expands Into
	  $PF	    FILENAME.TYP of the pointed-to file
	  $PN	    FILENAME of the pointed-to file
	  $PT	    TYP of the pointed-to file

     For instance, if the file currently being pointed to is
named MYFILE.TXT, then the command line:

	  ECHO FILENAME.TYP=$PF  FILENAME=$PN  TYP=$PT

will output:

	  FILENAME.TYP=MYFILE.TXT  FILENAME=MYFILE  TYP=TXT
							   Variables
     Example:

   -x
   #
	       Menu to Run M80 Assembler
			      Directory: $D$U
	  E - Edit Pointed-to File
	  P - Page Pointed-to File
	  A - Assemble Pointed-to File
   #
   eedit $pf
   azex m80 $pn
   ppage $pf
   ##

							   Variables
Notes:

     1.  The E and P commands build command lines containing
the full file name and type of the file being pointed to.

     2.  The A command shows the execution of ZEX.  VMENU is
a true ZCPR3 Shell, and, as such, ZEX commands can be issued
from  it and will run on top of it.   The prompt for the ZEX
command lines will be "VMenu>".

     3.  Assuming that MYFILE.MAC is being pointed to by the
user, the following shows the expansion of the command lines
for this example:

     Menu Command	      Expansion
   eedit $pf		       EDIT MYFILE.MAC
   azex m80 $pn 	       ZEX M80 MYFILE
   ppage $pf		       PAGE MYFILE.MAC

							   Variables

     The  first entry in any VMENU file display is named "No
File",	and  this  entry,  when pointed to by the  user  and
expanded into the command line,  is translated into a prompt
for the user to input the name of a file.   This feature  is
provided  as a convenience to the user so that he will	have
the  ability  to easily specify new files which do  not  yet
exist  to the VMENU commands (such as for an editor  command
in which the user wants to create a new file).

     If  the  pointer is at "No File" and the  command	line
uses  several  references  to the pointer (as  in  the	ECHO
command example above),  then the user is prompted only once
for  the  name of the file,  and each reference derives  its
information from this name.

							   Closing
		       Closing Notes

     As  many commands as the printable ASCII character  set
(without   lower-case	letters   and  the   VMENU   command
characters)  will allow are permitted by VMENU.   The  text,
however,  for each menu must be able to fit on a screen with
the file directory display at the top and the command prompt
at  the bottom.   This means that the text cannot exceed  16
lines.

     VMENU  fits in nicely to the ZCPR3 System of  programs.
The  information  section on "VMENU's  Relationship  to  the
ZCPR3  System"	explains  how  VMENU  and  the	other  ZCPR3
programs work together.

     The  following  ASCII  characters may NOT	be  used  as
commands since they are used elsewhere:

	  <SPACE>   #	 %    ,    .	<    >	  *    <DEL>
	  <Any Char Less than Space>
:M

	      VMENU Programming Command Summary

     Each  VMENU command occupies only one line,  and  blank
lines  in the command group are not permitted.	 The command
line is structured as follows:

	  l[o][command]

where:
    l is the single character used to invoke the command
	 note that it may be upper- or lower-case
    o is an opening option, which is one of:
	 :nn  -- go to Menu nn
	 &dir -- log into directory dir; dir may be in du
		 or named directory form. 
	 !    -- have VMENU wait when the command is finished
    command is an optional ZCPR3 command; note that if
	 the option is ":nn", then a command here makes no
	 sense


The VMENU commands are:

    Command   Function

    :nn       Goto Menu nn, where the first menu is Menu 1
    &dir -- log into directory dir; dir may be in du
		   or named directory form. 
    !	      Wait after command line is executed before
		   processing the menu
    "Prompt"  Prompt the user for input and accept it


The VMENU variables are:

     Variable  Expands to

	$C     Current DIR ('Noname' if not defined)
	$D     Current Disk
	$U     Current User
	$Fn    FILENAME.TYP for System File n
	$Nn    FILENAME for System File n
	$Tn    TYP for System File n
	$PF    FILENAME.TYP for Pointed-to File
	$PN    FILENAME for Pointed-to File
	$PT    TYP for Pointed-to File
	$$     $

Note: System Files can be defined by the SETFILE command.

The Highlighting Embedded Characters are:

     ^A   Turn ON Highlighting
     ^B   Turn OFF Highlighting

Note:  It is recommended that if highlighting is turned  on,
it should be turned off in the same line.



The  following ASCII characters may NOT be used as  commands
since they are used elsewhere:

	  <SPACE>   #	 %    ,    .	<    >	  *    <DEL>

	  <Any Char Less than Space>

:Z

	  VMENU's Relationship to the ZCPR3 System

     VMENU, like most of the ZCPR3 utilities, interacts with
the system as a whole and cannot be used with systems  other
than  ZCPR3.	In  particular,  VMENU	requires  the  ZCPR3
Multiple  Command Line Buffer and Shell Stack facilities  to
be  available  to  it and cannot run  without  them.   VMENU
invokes  command  lines  via the  Command  Line  Buffer  and
returns  to itself thru the Shell Stack.   It also uses  the
ZCPR3  System Files for some of its variables and the Z3TCAP
facility for its screen manipulation (highlighting).

     VMENU is installed by Z3INS.


     Also, CD (Change Directory) and STARTUP (or, ST for CD)
can  come into play with VMENU.   When CD logs into  to  new
directory,  it	looks for the file ST.COM and executes it if
there  is one.	 ST is simply STARTUP renamed,	and  STARTUP
will  load the Multiple Command Line Buffer with  a  command
line and then terminate.

     From the point of view of VMENU,  the command loaded by
ST  could be VMENU.   The effect of this is to automatically
enter  VMENU  when  the user employs CD  to  enter  a  given
directory.

     Hence,  by  using CD,  a user can enter a directory and
suddenly  find	himself in a menu instead of  at  the  ZCPR3
command  level.   This	is  good for  applications  where  a
directory  is  set  aside for a specific  purpose  and	only
certain  operations  are  to be performed  in  it,  such  as
cataloging disks or handling accounts.


     Now  that VMENU is running for the directory,  a  VMENU
command  could	be another CD to another directory.   Or  it
could simply be a DU: form.  Example:

	  #
	       A - Enter ZCPR Directory
	       B - Enter A0:
	  #
	  acd zcpr:
	  ba0:
	  #

     Here,  if A is issued, then CD will move into ZCPR: and
execute ST.COM if there is one there.	If B is issued,  the
user is logged into A0:.   VMENU is the next command in both
cases (invoked as a Shell), so VMENU automatically reinvokes
and looks for MENU.VMN.   If it finds it,  we are in another
VMENU  system,	and,  if it doesn't,  we are back  to  ZCPR3
command level.

     Under the A option, if CD finds ST.COM, ST will execute
its function and,  unless this function pops the Shell Stack
(SHCTRL  POP  command),  VMENU	will reinvoke  after  it  is
complete.

     Under  the B option,  we will run VMENU next and simply
exit if a MENU.VMN file is not found.


     VMENU  interacts  heavily with the ZCPR3  System  Files
which  are  defined  as  a part  of  the  ZCPR3  Environment
Descriptor.   There are four System Files, and three of them
are used by VMENU for various purposes:

     File      Purpose
       2       Name of Current File
       3       Name of Menu File
       4       Name (containing wild cards) used to
		    Select Files for VMENU File Display

     System  File  2 contains the name of the current  VMENU
file.	By  changing this name,  a transient can  cause  the
pointer  of VMENU to point to some other file when VMENU  is
reinvoked.


     System  File 3 contains the name of the menu file which
VMENU is using to derive menu displays and command from.  By
changing this entry,  a transient can select different	menu
files dynamically.

     System  File 4 is used to indicate which files (such as
*.TXT  or *.*) are selected for display by VMENU when it  is
invoked.   By  changing this entry,  the nature of the	file
display can be changed dynamically.

:E

		    VMENU Error Messages

     In order to make VMENU as small as possible,  the error
messages have been reduced to a minimum.   VMENU provides  a
minimum indication that something is wrong and aborts.

     The  program  VMENUCK  is	designed to  tell  you	more
specifically  what  is wrong.	VMENUCK is  a  *.VMN  Syntax
Checker, and it looks for all sorts of error conditions that
can occur in a *.VMN file.

     VMENU provides the following minimal error messages:


	  Message	 Meaning

	  No Shell Stack      Shell Stack Not Available
	  No Command Line     Command Line Buffer Not Avail
	  Shell Stack Full    Shell Stack is Full
	  Shell Stack Size    Shell Stack Entries are too
				   short for VMENU cmd line
	  File x.typ Not
	     Found	      Menu File Not Found
	  TPA Full	      Memory is Full
	  <Bell>	      User Command is in Error
	  Password Error      Invalid Password Given
	  Structure Error     *.VMN File Structure Error

:2

Command:  VMENUCK 1.3

Syntax:
     VMENUCK dir:ufn	  <-- default file type is VMN

Function:

     VMENUCK is used to check the syntax of a *.VMN file for
the  ZCPR3 Menu Shell,	VMENU.	 VMENU is optimized for size
and speed,  and,  in keeping it small,	built-in diagnostics
were reduced to the minimum.  VMENUCK is intended to be used
to  analyze *.VMN files and provide informative  diagnostics
on any syntactical errors with them.

Options:
     None


Comments:

     VMENUCK checks to see if the size of the *.VMN file  is
too large for the TPA available to the VMENU command.	This
is an additional check beyond the normal syntax check.

     VMENUCK  identifies  the  location of  errors  by	line
number.  The first line in the file is line number 1.

Selected Error Messages:

     Self-Explanatory.

Examples of Use:

     VMENUCK MYMENU
	  -- perform check on MYMENU.VMN

or      Invalid Password Given
	  Structure Error     *.VM