home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / ZCPR33 / S-Z / VMENU26.LBR / VMENU.HZP / VMENU.HLP
Text File  |  2000-06-30  |  36KB  |  1,081 lines
  1. ;
  2.  
  3.  
  4.               The ZCPR3 VMENU Shell
  5.  
  6.               -- ZCPR3 Utilities --
  7.              1 - VMENU
  8.              2 - VMENUCK
  9.  
  10.      -- Using VMENU --         -- Programming VMENU --
  11.      U - Using VMENU           P - Programming *.VMN Files
  12.      S - Summary of User Cmds  C - *.VMN Internal Commands
  13.      E - VMENU Error Messages  M - Programming Cmd Summary
  14.                    Z - VMENU and ZCPR3
  15.  
  16. :1
  17. Command:  VMENU 1.6
  18.  
  19. Syntax:
  20.      VMENU         <-- run MENU.VMN on all files in dir
  21. or
  22.      VMENU afn         <-- run MENU.VMN on files selected by afn
  23. or
  24.      VMENU afn ufn   <-- run menu (ufn) on selected files
  25.  
  26. Function:
  27.  
  28.      VMENU  is the ZCPR3 menu front-end processor.   It is a
  29. ZCPR3 Shell which reads a *.VMN file and processes  commands
  30. from it.
  31.  
  32. Options:  None
  33.  
  34. Comments:
  35.      VMENU  is a true ZCPR3 Shell.   It is described in this
  36. HELP file.
  37. Selected Error Messages:
  38.  
  39.      "No Command Line" means that the ZCPR3 System does  not
  40. support  an external Command Line Buffer.   VMENU must    have
  41. this to run.
  42.  
  43.      "No  Shell Stack" means that the ZCPR3 System does  not
  44. support a Shell Stack.    VMENU must have this to run.
  45.  
  46.      "Shell  Stack Full" means that the Shell Stack is    full
  47. and VMENU cannot push itself onto the stack.
  48.  
  49.      "Shell  Stack Size" means that the Shell Stack elements
  50. are too short for VMENU to store its parameters.
  51.  
  52.      "TPA  Full" means that there is not enough room in  the
  53. TPA to load the *.VMN file.
  54.  
  55. Examples of Use:
  56.      See this HELP file
  57.  
  58.      VMENU is the ZCPR3 Menu-Oriented Command  Preprocessor.
  59. It  acts as a front-end to ZCPR3,  providing a menu-oriented
  60. user interface to ZCPR3.  Its function can be represented by
  61. the following diagram:
  62.           -------    -------    -------    -------
  63.           |V    |    |Z    |    |B    |    |P     |
  64.    User       | M    |    | C   |    | D   |    | g     |
  65.    Menu      ---->|  E    |--->|    P  |--->|  O  |--->|  m  |
  66.    Command      |   N |    |     R |    |   S |    |   s |
  67.           |    U|    |      3|    |     |    |     |
  68.           -------    -------    -------    -------
  69.  
  70.      The "User Menu Command" is a single character that  the
  71. user  strikes  which instructs VMENU to perform a  function.
  72. Once  VMENU  begins processing this function,  it  builds  a
  73. command  line  for ZCPR3,  optionally asking  the  user  for
  74. further  input    (such as a file name),    and then passes  the
  75. command  line to ZCPR3 via the Command Line  Buffer.   ZCPR3
  76. then runs the command line returns to VMENU.
  77.  
  78.      VMENU  builds command lines based on simple input    from
  79. the user.   The user need never know what the actual command
  80. line is.  The command line itself is always of the form:
  81.  
  82.           <command> <optional user input>
  83.  
  84.      As  an example,  a command built by VMENU to  run    XDIR
  85. with  user input for a file name specification,  could    look
  86. like the following:
  87.  
  88.              XDIR <user input>
  89.  
  90.  
  91.      When VMENU is executed, it builds the list of  files to
  92. be displayed, and then looks for the  desired menu file.  It
  93. begins its search in  the current directory,  and  continues
  94. along  the system  path  until either  it has found the menu
  95. file,  or  all    directories in    the path  have been searched
  96. without success.  If the menu file is found, it will be read
  97. into  memory, and  the first menu displayed.   If it was not
  98. found, an error message will be generated.
  99.       If  no menu file is specified, then VMENU will default
  100. to MENU.VMN.  If the user  has supplied a file ID  with both
  101. the menu file name and type,  VMENU  will use this file.  If
  102. only  the file name is    specified, the default    file type of
  103. VMN is assumed.
  104.  
  105.      The  MENU.VMN  file can contain up to 255 menus  to  be
  106. processed by VMENU.   The VMENU will begin processing at the
  107. first menu in MENU.VMN.
  108.  
  109.  
  110.      VMENU  itself  is a COM file,  like any  other  program
  111. under  ZCPR3.    Unlike    most  other  programs,    however,  it
  112. generates  command lines to be executed by ZCPR3 and  stores
  113. its  return command in the Shell Stack.   In this way a loop
  114. is set up:
  115.  
  116.            -->--+->- VMENU ->- ZCPR3 ->-+
  117.             ^                v
  118.             |                |
  119.             +-<- Command Line -<----+
  120.  
  121.      Only  VMENU  itself  or a ZCPR3 tool  like  SHCTRL  can
  122. terminate this loop.  If the VMENU programmer wishes, he can
  123. set  up  the MENU.VMN file so that this loop will  never  be
  124. exited, or he can set up the file to allow anyone to exit at
  125. any  time or just a special person who knows a    password  to
  126. exit  when  he    wishes to.   There is a lot  of  flexibility
  127. designed into the system,  and it will be discussed later in
  128. the section on programming MENU.VMN files.
  129.      A MENU.VMN  file can be set up to execute    any  ZCPR3
  130. command or sequence of commands.  The MENU.VMN file can also
  131. be set up to not allow the user to leave VMENU, to allow him
  132. to leave VMENU at will,  or to allow him to leave VMENU only
  133. if he knows a password.
  134.  
  135.      This  HELP file is divided into two basic    parts.     The
  136. info  sections    on  "Using  VMENU"  and  "Summary  of  VMENU
  137. Commands" are designed to be read by a person wanting to use
  138. VMENU  but  not wanting to learn how VMENU works or  how  to
  139. program  it.   These sections describe how to move from  one
  140. menu  to another,  how to issue VMENU commands,  and how  to
  141. leave VMENU if the option is presented to him.
  142.  
  143.      The  other  sections  of this HELP  file  describe  the
  144. programming  aspects of VMENU and are intended to be used as
  145. an  online reference for the VMENU  programmer.   The  VMENU
  146. command  programming summary is especially useful in that it
  147. provides   a  summary  of  the    commands  which  the   VMENU
  148. programmer may issue to VMENU within a *.VMN file.
  149. :U
  150.  
  151.      When VMENU is first invoked,  it will be installed as a
  152. Shell.    If commands are pending, control will return to  the
  153. ZCPR3  command processor for the next command in  the  line.
  154. When the command line is exhausted,  ZCPR3 will realize that
  155. a shell has been installed and invoke VMENU as a shell.   If
  156. there are no pending commands, however, VMENU will begin the
  157. menu command processing immediately.
  158.  
  159.      When VMENU begins    execution as a    Shell,    it will load
  160. the names of the  selected  files  in the current directory,
  161. load the menu file, and display up  to sixteen files and the
  162. first menu in the menu file to the user.  The user will then
  163. be prompted for a command.
  164.  
  165.      To refresh the  VMENU display,  press ^R.   To sort the
  166. list of files in the alternate order, press ^Q.  To log into
  167. a different directory, press ^N.
  168.  
  169.  
  170.      The VMENU display is divided into two  distinct halves.
  171. The upper half consists of up to 16 files from the  selected
  172. list of files.    The file pointer (--->) is used to indicate
  173. the current file, whose name and type may be used by command
  174. lines in the current menu.  The name of the current file  is
  175. displayed in the upper right corner of the display.
  176.  
  177.      The following movement comands are available to allow
  178. the file pointer to be moved to the desired file:
  179.  
  180.      <SP> - Advance to next file name.    Wraparound from last
  181. to  first  may occur.    The Word Star ^D character  or    your
  182. right  arrow  key (if available in the Z3TCAP)    perform  the
  183. same function.
  184.  
  185.      <BS>  - Back  up to last file  name.   Wraparound    from
  186. first to last may occur.  The Word Star ^S character or your
  187. left arrow key (if available in the Z3TCAP) perform the same
  188. function.
  189.  
  190.      +    - Jump to Next Screen (if any).   If there  is    more
  191. than  one screen of files,  the user is advanced to the next
  192. screen. If at the last screen, wraparound to first.  ^F also
  193. performs this function if not overridden by arrow keys.
  194.  
  195.      - - Jump to Last Screen (if any).     Similar to + but in
  196. the opposite direction.  May wraparound to the last screen.
  197. ^A also performs this function if not overridden by arrow.
  198.  
  199.      ^T - Move to first file in current screen.
  200.      ^B - Move to last file in current screen.
  201.  
  202.      Word Star arrow key movement (if not overriden by arrow
  203. keys in Z3TCAP):
  204.                  ^E
  205.                   ^
  206.              ^S <-+-> ^D
  207.                   v
  208.                  ^X
  209.  
  210.  
  211.      The second half of the display consists of the  current
  212. menu, and  the    menu  command prompt which has the following
  213. general form:
  214.  
  215. Command (CR=Menu,^C=Z3,*=1st Menu,<=Prev Menu,>=Next Menu) -
  216.  
  217.      There  can  be up to 255 menus in one  VMENU.VMN  file.
  218. The  VMENU  command  prompt varies  to    reflect  this.     For
  219. instance,  if  only  one Menu was present and the option  to
  220. abort out of VMENU to ZCPR3 was not available, then the Menu
  221. Command prompt would take its simplest form, looking like:
  222.  
  223. Command (CR=Menu) -
  224.  
  225.      Strike  ^R at this time to refresh the Menu Display, ^N
  226. to log into  a different directory, or strike  the character 
  227. of a Menu Option.   These are the only choices, and striking
  228. a character  which is  not the  RETURN key or a menu  option 
  229. results in the bell sounding.
  230.  
  231.  
  232.      If  the  the option to exit to ZCPR3 was available  and
  233. there  is  only  one Menu in the  MENU.VMN  file,  then  the
  234. command line will look like this:
  235.  
  236. Command (CR=Menu,^C=Z3) -
  237.  
  238.      The  option of aborting to ZCPR3 by striking  Control-C
  239. (hold  down  on the Control,  or CTRL,    key and  strike  the
  240. letter C) is now available.   This will return to ZCPR3  and
  241. exit VMENU.
  242.  
  243.      One  brief note on option letters before going on.   If
  244. one  of your options is a letter in the range from A  to  Z,
  245. then case is not significant,  and you can invoke the option
  246. A, say, by striking an upper- or lower-case A.
  247.  
  248.  
  249.      If  there is more than one menu in the *.VMN file,  the
  250. command line options become slightly more complex,  but they
  251. are still quite easy to follow.
  252.  
  253.      In  the following examples,  assume that the option  to
  254. exit to ZCPR3 is off, so the "^C=Z3" option will NOT appear.
  255.  
  256.      From the first menu in the file,  the command line will
  257. look like the following:
  258.  
  259. Command (CR=Menu,>=Next Menu) -
  260.  
  261.      To advance to the next menu,  strike the ">" or the "."
  262. character.   On most keyboards, ">" is the shift of the ".",
  263. so VMENU permits easy movement without having to worry about
  264. shifting the keyboard all the time.
  265.  
  266.  
  267.      If at the last menu in the file,  the command line will
  268. look like the following:
  269.  
  270. Command (CR=Menu,*=1st Menu,<=Prev Menu) -
  271.  
  272.      This  allows  the user to strike the "*"  character  to
  273. jump  back to the first menu in his *.VMN file.   If "<"  or
  274. ","  is struck ("<" is usually the shift of the  ","),    then
  275. the  user will back up one menu to the previous menu in  the
  276. file.
  277.  
  278.      If the user is somewhere in the middle of the  MENU.VMN
  279. file, his command line will look like this:
  280.  
  281. Command (CR=Menu,*=1st Menu,<=Prev Menu,>=Next Menu) -
  282.  
  283.      Again,  "*" will go directly to the first menu,  "<" or
  284. "," will go to the previous menu,  and ">" or "." will go to
  285. the  next  menu.   Striking the RETURN key will refresh  the
  286. menu display.
  287.  
  288.      One  last    option    the  user  has    under VMENU involves
  289. access to a System Menu.  This menu is special in that there
  290. is only one way to get to it -- via the "$" command.
  291.  
  292.      The  System  Menu is intended to give priveleged  users
  293. access to special commands that the rest of the users  can't
  294. run.   If  a System Menu is available, VMENU will respond to
  295. the "$" command with the prompt:
  296.  
  297.       Pass?
  298.  
  299.      The  user    is given one chance to type in    the  correct
  300. password  to enter the System Menu.   If he  is  wrong,  the
  301. message "Password Error" will appear and he will be returned
  302. to the menu he came from.   If he is correct,  he will enter
  303. the System Menu.   Physically, the System Menu is always the
  304. last menu in the file, and its command prompt is:
  305.  
  306. Command (CR=Menu,*=1st Menu,<=Prev Menu) -
  307.  
  308.      If the user is at the menu just before the System Menu,
  309. the ">" will not function to allow him to enter it, even tho
  310. there  technically is a "Next Menu".   The ">" option in the
  311. command  line  will not appear.   The only way    to  enter  a
  312. System Menu is thru the "$" command.
  313.  
  314.  
  315.  
  316.      In  summary,  moving about within VMENU is quite  easy.
  317. "*"  moves the user to the first menu,    "<" to the  previous
  318. menu, ">" to the next menu.
  319.  
  320. :S
  321.  
  322.      The full VMENU Command Line looks like the following:
  323.  
  324. Command (CR=Menu,^C=Z3,*=1st Menu,<=Prev Menu,>=Last Menu) -
  325.  
  326.      The Menu Commands are:
  327.  
  328.        Command     Function
  329.  
  330.        ^N     Log into new Directory
  331.        ^R     Refresh Menu Display (RETURN Key)
  332.        ^Q     Resort File Display
  333.        ^C     Exit to ZCPR3 (Control-C)
  334.        *     Jump to the First Menu
  335.        < or ,     Jump to the Previous Menu
  336.        > or .     Jump to the Next Menu
  337.        $     Jump to the System Menu (Password Required)
  338.        other     Menu Option or Invalid Command; letters are
  339.               automatically capitalized, so a=A
  340.  
  341.      Movement Commands --
  342.       ^E - Move Up (Wrap to Bottom)
  343.       ^X - Move Down (Wrap to Top)
  344.       ^D - Move Right (Wrap to First File of Next Line)
  345.       ^S - Move Left (Wrap to Last File of Previous Line)
  346.       ^F - Move Screen Right (Wrap to First Screen)
  347.       ^A - Move Screen Left (Wrap to Last Screen)
  348.       ^T - Move to First File in Current Screen
  349.       ^B - Move to Last File in Current Screen
  350.  
  351.      The  user's Z3TCAP entry may define four other  single-
  352. character  commands  to  conform to the arrow  keys  on  his
  353. specific  terminal.   These commands will override  the  set
  354. described  above  if any conflicts exist (that is,  if    your
  355. down-arrow key generates a ^E, ^E will now mean Move Down in
  356. all cases).
  357.  
  358.      Screen  Left  and Right make sense when there  are  too
  359. many files to fit on one screen.   In this case,  the  files
  360. are  broken  into screen directories,  and Screen  Left  and
  361. Right are used to move between them.
  362. :P
  363.  
  364.           Programming *.VMN Files
  365.  
  366.      The  *.VMN  file  is simply a text file  which  may  be
  367. created  with  any  conventional  CP/M     editor,   including
  368. WordStar.   VMENU  ignores  the Most Significant Bit of  all
  369. bytes, so editors like WordStar, which occasionally set this
  370. bit, can be used.
  371.  
  372.      All *.VMN files have the same general  structure.     The
  373. first  line is either a global option line or the  beginning
  374. of a menu display.   If a global option line, it begins with
  375. the  character    "-",   and  this  character  is  immediately
  376. followed  by  global option characters.   The global  option
  377. line, then looks like this:
  378.  
  379. -options
  380.  
  381.      After the global option line,  if any,  comes the first
  382. menu.  Each menu is structured as follows:
  383.  
  384.              #options
  385.                   <Text of Menu Display>
  386.              #
  387.              menu commands
  388.  
  389.      The following are two sample Menu File structures:
  390.  
  391.            -options         #options
  392.            #options              <Text>
  393.             <Text>        #
  394.            #            commands
  395.            commands         ##
  396.            #options
  397.             <Text>
  398.            #
  399.            commands
  400.            ##
  401.      There are two option characters.  In using them, case
  402. is not significant.  These option characters are:
  403.  
  404.       Option    Function
  405.          C        Display Command Line to User
  406.          X        Allow User to Exit to ZCPR3
  407.  
  408.     The C option displays the command line built by VMENU to
  409. the user.   This option is primarily intended for  debugging
  410. purposes,  to  allow the programmer to see what commands are
  411. being built.   It is instructive to the user,  however,  and
  412. may be employed for that purpose as well.
  413.  
  414.      The  X  option enables the facility which    permits  the
  415. user to type ^C and return to ZCPR3.
  416.  
  417.      When VMENU first comes up, all options are turned off:
  418.  
  419.       C is OFF -- no command display to user
  420.       X is OFF -- the user cannot exit to ZCPR3.
  421.  
  422.      The  global options line,    which,    if present,  is  the
  423. first  line  of the file,  turns on these  options  for  the
  424. course    of  the session in general.   That is,    if a  global
  425. options line like
  426.  
  427.       -x
  428.  
  429. is used  (case    is insignificant),  then exit  to ZCPR3 will
  430. be available for all menus.  The global options line affects
  431. all menus.
  432.  
  433.  
  434.      The global options line turns on the indicated  options
  435. for all menus in general.   However, the same options may be
  436. presented  on the first line of each menu immediately  after
  437. the  "#"  character  to temporarily complement    the  current
  438. option for only that menu.
  439.  
  440.      If  an  option is NOT included in    the  global  options
  441. line,  it  is  turned  OFF for all menus  in  general.     The
  442. defaults  selected  by    using the global  options  line  are
  443. overridden on a per-menu basis by the local menu options.
  444.  
  445.      Example:
  446.  
  447.  
  448.     -x
  449.     #x
  450.      No exit to ZCPR3 is permitted
  451.     #
  452.     commands
  453.     #dx
  454.      No exit to ZCPR3.
  455.     #
  456.     commands
  457.     #c
  458.      The user may exit to ZCPR3.  Additionally, the
  459.      MENU-generated commands are printed to the user.
  460.     #
  461.     commands
  462.     ##
  463.  
  464.      Any  option that may appear on the global options line
  465. may  also appear on the options line for a particular  menu.
  466. The menu options line supports one additional  option,    viz.
  467. "$".  This option declares the following menu to be a System
  468. Menu.
  469.      In  programming a *.VMN file, the VMENU programmer MUST
  470. place the System Menu as the last menu in the file if it  is
  471. going to have one.   To do otherwise is flagged as an error.
  472. The  following illustrates a *.VMN file containing a  System
  473. Menu:
  474.        #
  475.      The user may not exit to ZCPR3.
  476.        #
  477.        commands
  478.        #$x
  479.      This is a System Menu, and the user may exit to ZCPR3.
  480.        ##
  481.  
  482.      If  a  menu is a System Menu,  the "$"  character    must
  483. immediately  follow  the  "#".     In the case of  the  letter
  484. options in both the global and local cases, the order is not
  485. important ("cx" means the same as "xc").
  486.  
  487.      The  password used to enter a System Menu is hard-coded
  488. in.   It may be altered by reassembly or use of  DDT.    Note
  489. that this password can be upper- and lower-case, and case is
  490. significant.
  491.  
  492. :C
  493.  
  494.                *.VMN Commands
  495.  
  496.      This   section  describes    the  technique    and  options
  497. available  for creating command lines in *.VMN    files.     The
  498. information  herein is organized into the following  subject
  499. areas:
  500.  
  501.       o Syntax of the command line
  502.  
  503.       o :nn Option
  504.  
  505.       o ! Option
  506.  
  507.       o & Option
  508.  
  509.       o "text" prompts and input
  510.  
  511.       o Variables ($C, $D, $U, $Fn, $Nn, $Tn, $Pp, $$)
  512.  
  513.       o Highlighting (^A, ^B)
  514.  
  515.                                Syntax
  516.      The commands in a *.VMN file follow a simple structure.
  517. Each command occupies only one line,  and blank lines in the
  518. command  group    are  not permitted.   The  command  line  is
  519. structured as follows:
  520.  
  521.       l[o][command]
  522.  
  523. where:
  524.     l is the single character used to invoke the command
  525.      note that it may be upper- or lower-case
  526.     o is an opening option, which is one of:
  527.      :nn  -- go to Menu nn
  528.      &dir -- Log into directory dir
  529.      !    -- have VMENU wait when the command is finished
  530.     command is an optional ZCPR3 command; note that if
  531.      the option is ":nn", then a command here makes no
  532.      sense
  533.  
  534.                                :nn Opt
  535.      The  ":nn"  option tells VMENU to move to    a  different
  536. menu  in  the  *.VMN file.   The first    menu  is  number  1.
  537. Example:
  538.  
  539.       -x
  540.       #
  541.            1st Menu:  A - Goto Menu 2     3 - Goto Menu 3
  542.       #
  543.       a:2
  544.       3:3
  545.       #
  546.             2nd Menu Command: 3 - Goto Menu 3
  547.       #
  548.       3:3
  549.       #x
  550.             3rd Menu Command: 2 - Goto Menu 2
  551.       #
  552.       2:2
  553.       ##
  554.                                :nn Opt
  555.      In the first menu, the user may strike:
  556.  
  557.       "a" or "A" to goto Menu 2
  558.       "3" to goto Menu 3
  559.       ">"  or  "." to goto the next menu (Menu 2)
  560.       ^C to goto ZCPR3
  561.  
  562.      In the second menu, the user may strike:
  563.  
  564.       "3" to goto Menu 3
  565.       "*" or "<" or "," to goto Menu 1
  566.       ">" or "." to goto Menu 3
  567.       ^C to goto ZCPR3
  568.  
  569.      In the third menu, the user may strike:
  570.  
  571.       "2" or "<" or "," to goto Menu 2
  572.       "*" to goto Menu 1
  573.  
  574.                                ! Opt
  575.      The  "!" option causes VMENU to pause and ask the    user
  576. to "Strike Any Key" before continuing after the command line
  577. has  been processed.   In this way,  if a command  generates
  578. information  to be read by the user before VMENU clears  his
  579. screen,  the "!" option may be used to give the user all the
  580. time he wants to read this display.
  581.  
  582.                                & Opt
  583.      The "&" option causes VMENU to log into a new directory
  584. which may be given as drive-user or named directory.
  585. Example:
  586.  
  587.     -x
  588.     #
  589.         My menu:  A - go to a3    5 - go to help
  590.     #
  591.     a&a3
  592.     5&help
  593.     ##
  594.  
  595.      After the  du or dir  specification, you may  declare a 
  596. menu change by inserting a ';' after the du/dir,  and follow
  597. that by the name of the new menu (.VMN) file.
  598. Example:
  599.  
  600.     a&a3;ourmenu (case is not significant)
  601.                                "prompt"
  602.      Embedded  within  any command line may be a prompt  for
  603. user input.  This prompt takes the form of
  604.  
  605.       "prompt to user"
  606.  
  607. When  encountered,  VMENU will advance to the next line  and
  608. print the text contained within the quotes.  VMENU will then
  609. wait for the user to input any text he desires followed by a
  610. RETURN.    At  this  point,  the  text    the  user  input  is
  611. capitalized and placed into the command line at the point of
  612. the prompt.
  613.  
  614.      If  the  prompt appears at the end of a  VMENU  command
  615. line,  the trailing quote is not required.   As many prompts
  616. as   desired  may  appear  within  a  VMENU  command   line.
  617. Examples:
  618.  
  619.                                "prompt"
  620.     -x
  621.     #
  622.      A - Run XDIR without Pause or Input
  623.      B - Run XDIR and Pause before Returning to VMENU
  624.      C - Run XDIR, Allow User Input, and Pause before
  625.           Returning to VMENU
  626.      M - Run MCOPY, Allow User Input of Dest Dir, Allow
  627.           User Input of Source Dir and File, and Pause
  628.           before returning to VMENU
  629.      Z - Run Any ZCPR3 Command and Pause before
  630.           Returning to VMENU
  631.     #
  632.     m!mcopy "Destination Dir? "="Source DIR:AFN?  "
  633.     z!"Enter Command Line --
  634.     axdir
  635.     b!xdir
  636.     c!xdir "Enter Ambiguous File Name --
  637.     ##
  638.  
  639.                                "prompt"
  640.      Note  the Space right before the "Prompt form in the  C
  641. command.   This space is significant to keep the command and
  642. user  input from running together.   This "run together"  is
  643. desired  for the Z command.   Also note the dual prompt  for
  644. the M command.
  645.  
  646.      With the M command,  the following prompts will  appear
  647. (and sample input):
  648.  
  649.       Destination Dir? BACKUP:
  650.       Source DIR:AFN?  *.TXT
  651.  
  652. and the following command line is built:
  653.  
  654.       MCOPY BACKUP:=*.TXT
  655.  
  656.                                Variables
  657.      The  command  text  which    is specified  in  the  VMENU
  658. command line can contain embedded variables which VMENU will
  659. expand when the command line is processed.  These variables,
  660. which  are denoted by a dollar sign ($) followed by  one  or
  661. two characters, are defined as follows:
  662.  
  663.      Variable  Expands as
  664.      --------  ----------
  665.        $C      Current DIR ('Noname' if not defined)
  666.        $D      Current Disk
  667.        $U      Current User Area
  668.        $Fn     FILENAME.TYP for ZCPR3 System File n
  669.        $Nn     FILENAME for ZCPR3 System File n
  670.        $Tn     TYP for ZCPR3 System File n
  671.        $Pp     Name of File being Pointed to
  672.        $$      Place a single $ in command line
  673.  
  674.      These  variables  can also be used in the menu  display
  675. itself,  and  their  values  will be  substituted  when  the
  676. display is generated.  Example:
  677.                                Variables
  678.    -x
  679.    #
  680.            Menu to Run M80 Assembler
  681.                   Current File: $F1
  682.                   Directory: $D$U
  683.       F - Define File
  684.       E - Edit $F1          P - Page $F1
  685.       A - Assemble $F1
  686.    #
  687.    fsetfile 1 "Filename? "
  688.    eedit $f1
  689.    azex m80 $n1
  690.    ppage $f1
  691.    ##
  692.  
  693.                                Variables
  694. Notes:
  695.  
  696.      1. The ZCPR3 utility SETFILE is used to define the name
  697. of  a  ZCPR3  System File.   There  are  four  System  Files
  698. available,  and they can be referenced by $F1 to $F4, $N1 to
  699. $N4, and $T1 to $T4.
  700.  
  701.      2.  The A command shows the execution of ZEX.  VMENU is
  702. a true ZCPR3 Shell, and, as such, ZEX commands can be issued
  703. from  it and will run on top of it.   The prompt for the ZEX
  704. command lines will be "Menu>".
  705.  
  706.      3.  Assuming that "MYFILE.MAC" is assigned to the ZCPR3
  707. System File 1 and the user is logged into disk B user 1, the
  708. following  screen  shows how the display and  the  resulting
  709. command lines will be expanded when execution occurs:
  710.  
  711.                                Variables
  712.               Display
  713.  
  714.            Menu to Run M80 Assembler
  715.                   Current File: MYFILE.MAC
  716.                   Directory: B1
  717.       F - Define File
  718.       E - Edit MYFILE.MAC         P - Page MYFILE.MAC
  719.       A - Assemble MYFILE.MAC
  720.  
  721.  
  722.                Command Lines
  723.      Menu Command          Expansion
  724.  
  725.    fsetfile 1 "Filename? "     SETFILE 1 "Filename? "
  726.    eedit $f1               EDIT MYFILE.MAC
  727.    azex m80 $n1            ZEX M80 MYFILE
  728.    ppage $f1               PAGE MYFILE.MAC
  729.  
  730.                                Highlighting
  731.      Just  like the HELP utility can take advantage  of  the
  732. highlighting facility provided in the Z3TCAP,  so can VMENU.
  733. For  those  ZCPR3  Systems with a  properly-installed  TCAP,
  734. VMENU  will  use  the clear screen command  to    refresh  the
  735. user's    screen and highlighting can be enabled and  disabled
  736. by  embedding ^A (to turn on highlighting) and ^B  (to    turn
  737. off highlighting) into the *.VMN file.
  738.  
  739.      It  is recommended that when highlighting is turned on,
  740. it  should  be turned off in the same line  for  consistency
  741. sake and appearance.
  742.  
  743.      Example:
  744.  
  745.                                Highlighting
  746.    #
  747.       ^AThis is highlighted^B and this is not
  748.    #
  749.  
  750. will appear with "This is highlighted" in a highlighted mode
  751. like this:
  752.  
  753.       This is highlighted and this is not
  754.  
  755.  
  756.                                Variables
  757.  
  758.      The  $Pp  variable is also available to the user  under
  759. VMENU.     $Pp returns information on the file currently being
  760. pointed to by the user on the screen.  This variable has the
  761. following forms:
  762.  
  763.       Form        Expands Into
  764.       $PF        FILENAME.TYP of the pointed-to file
  765.       $PN        FILENAME of the pointed-to file
  766.       $PT        TYP of the pointed-to file
  767.  
  768.      For instance, if the file currently being pointed to is
  769. named MYFILE.TXT, then the command line:
  770.  
  771.       ECHO FILENAME.TYP=$PF  FILENAME=$PN  TYP=$PT
  772.  
  773. will output:
  774.  
  775.       FILENAME.TYP=MYFILE.TXT  FILENAME=MYFILE  TYP=TXT
  776.                                Variables
  777.      Example:
  778.  
  779.    -x
  780.    #
  781.            Menu to Run M80 Assembler
  782.                   Directory: $D$U
  783.       E - Edit Pointed-to File
  784.       P - Page Pointed-to File
  785.       A - Assemble Pointed-to File
  786.    #
  787.    eedit $pf
  788.    azex m80 $pn
  789.    ppage $pf
  790.    ##
  791.  
  792.                                Variables
  793. Notes:
  794.  
  795.      1.  The E and P commands build command lines containing
  796. the full file name and type of the file being pointed to.
  797.  
  798.      2.  The A command shows the execution of ZEX.  VMENU is
  799. a true ZCPR3 Shell, and, as such, ZEX commands can be issued
  800. from  it and will run on top of it.   The prompt for the ZEX
  801. command lines will be "VMenu>".
  802.  
  803.      3.  Assuming that MYFILE.MAC is being pointed to by the
  804. user, the following shows the expansion of the command lines
  805. for this example:
  806.  
  807.      Menu Command          Expansion
  808.    eedit $pf               EDIT MYFILE.MAC
  809.    azex m80 $pn            ZEX M80 MYFILE
  810.    ppage $pf               PAGE MYFILE.MAC
  811.  
  812.                                Variables
  813.  
  814.      The  first entry in any VMENU file display is named "No
  815. File",    and  this  entry,  when pointed to by the  user  and
  816. expanded into the command line,  is translated into a prompt
  817. for the user to input the name of a file.   This feature  is
  818. provided  as a convenience to the user so that he will    have
  819. the  ability  to easily specify new files which do  not  yet
  820. exist  to the VMENU commands (such as for an editor  command
  821. in which the user wants to create a new file).
  822.  
  823.      If  the  pointer is at "No File" and the  command    line
  824. uses  several  references  to the pointer (as  in  the    ECHO
  825. command example above),  then the user is prompted only once
  826. for  the  name of the file,  and each reference derives  its
  827. information from this name.
  828.  
  829.                                Closing
  830.                Closing Notes
  831.  
  832.      As  many commands as the printable ASCII character  set
  833. (without   lower-case    letters   and  the   VMENU   command
  834. characters)  will allow are permitted by VMENU.   The  text,
  835. however,  for each menu must be able to fit on a screen with
  836. the file directory display at the top and the command prompt
  837. at  the bottom.   This means that the text cannot exceed  16
  838. lines.
  839.  
  840.      VMENU  fits in nicely to the ZCPR3 System of  programs.
  841. The  information  section on "VMENU's  Relationship  to  the
  842. ZCPR3  System"    explains  how  VMENU  and  the    other  ZCPR3
  843. programs work together.
  844.  
  845.      The  following  ASCII  characters may NOT    be  used  as
  846. commands since they are used elsewhere:
  847.  
  848.       <SPACE>   #     %    ,    .    <    >      *    <DEL>
  849.       <Any Char Less than Space>
  850. :M
  851.  
  852.           VMENU Programming Command Summary
  853.  
  854.      Each  VMENU command occupies only one line,  and  blank
  855. lines  in the command group are not permitted.     The command
  856. line is structured as follows:
  857.  
  858.       l[o][command]
  859.  
  860. where:
  861.     l is the single character used to invoke the command
  862.      note that it may be upper- or lower-case
  863.     o is an opening option, which is one of:
  864.      :nn  -- go to Menu nn
  865.      &dir -- log into directory dir; dir may be in du
  866.          or named directory form. 
  867.      !    -- have VMENU wait when the command is finished
  868.     command is an optional ZCPR3 command; note that if
  869.      the option is ":nn", then a command here makes no
  870.      sense
  871.  
  872.  
  873. The VMENU commands are:
  874.  
  875.     Command   Function
  876.  
  877.     :nn       Goto Menu nn, where the first menu is Menu 1
  878.     &dir -- log into directory dir; dir may be in du
  879.            or named directory form. 
  880.     !          Wait after command line is executed before
  881.            processing the menu
  882.     "Prompt"  Prompt the user for input and accept it
  883.  
  884.  
  885. The VMENU variables are:
  886.  
  887.      Variable  Expands to
  888.  
  889.     $C     Current DIR ('Noname' if not defined)
  890.     $D     Current Disk
  891.     $U     Current User
  892.     $Fn    FILENAME.TYP for System File n
  893.     $Nn    FILENAME for System File n
  894.     $Tn    TYP for System File n
  895.     $PF    FILENAME.TYP for Pointed-to File
  896.     $PN    FILENAME for Pointed-to File
  897.     $PT    TYP for Pointed-to File
  898.     $$     $
  899.  
  900. Note: System Files can be defined by the SETFILE command.
  901.  
  902. The Highlighting Embedded Characters are:
  903.  
  904.      ^A   Turn ON Highlighting
  905.      ^B   Turn OFF Highlighting
  906.  
  907. Note:  It is recommended that if highlighting is turned  on,
  908. it should be turned off in the same line.
  909.  
  910.  
  911.  
  912. The  following ASCII characters may NOT be used as  commands
  913. since they are used elsewhere:
  914.  
  915.       <SPACE>   #     %    ,    .    <    >      *    <DEL>
  916.  
  917.       <Any Char Less than Space>
  918.  
  919. :Z
  920.  
  921.       VMENU's Relationship to the ZCPR3 System
  922.  
  923.      VMENU, like most of the ZCPR3 utilities, interacts with
  924. the system as a whole and cannot be used with systems  other
  925. than  ZCPR3.    In  particular,  VMENU    requires  the  ZCPR3
  926. Multiple  Command Line Buffer and Shell Stack facilities  to
  927. be  available  to  it and cannot run  without  them.   VMENU
  928. invokes  command  lines  via the  Command  Line  Buffer  and
  929. returns  to itself thru the Shell Stack.   It also uses  the
  930. ZCPR3  System Files for some of its variables and the Z3TCAP
  931. facility for its screen manipulation (highlighting).
  932.  
  933.      VMENU is installed by Z3INS.
  934.  
  935.  
  936.      Also, CD (Change Directory) and STARTUP (or, ST for CD)
  937. can  come into play with VMENU.   When CD logs into  to  new
  938. directory,  it    looks for the file ST.COM and executes it if
  939. there  is one.     ST is simply STARTUP renamed,    and  STARTUP
  940. will  load the Multiple Command Line Buffer with  a  command
  941. line and then terminate.
  942.  
  943.      From the point of view of VMENU,  the command loaded by
  944. ST  could be VMENU.   The effect of this is to automatically
  945. enter  VMENU  when  the user employs CD  to  enter  a  given
  946. directory.
  947.  
  948.      Hence,  by  using CD,  a user can enter a directory and
  949. suddenly  find    himself in a menu instead of  at  the  ZCPR3
  950. command  level.   This    is  good for  applications  where  a
  951. directory  is  set  aside for a specific  purpose  and    only
  952. certain  operations  are  to be performed  in  it,  such  as
  953. cataloging disks or handling accounts.
  954.  
  955.  
  956.      Now  that VMENU is running for the directory,  a  VMENU
  957. command  could    be another CD to another directory.   Or  it
  958. could simply be a DU: form.  Example:
  959.  
  960.       #
  961.            A - Enter ZCPR Directory
  962.            B - Enter A0:
  963.       #
  964.       acd zcpr:
  965.       ba0:
  966.       #
  967.  
  968.      Here,  if A is issued, then CD will move into ZCPR: and
  969. execute ST.COM if there is one there.    If B is issued,  the
  970. user is logged into A0:.   VMENU is the next command in both
  971. cases (invoked as a Shell), so VMENU automatically reinvokes
  972. and looks for MENU.VMN.   If it finds it,  we are in another
  973. VMENU  system,    and,  if it doesn't,  we are back  to  ZCPR3
  974. command level.
  975.  
  976.      Under the A option, if CD finds ST.COM, ST will execute
  977. its function and,  unless this function pops the Shell Stack
  978. (SHCTRL  POP  command),  VMENU    will reinvoke  after  it  is
  979. complete.
  980.  
  981.      Under  the B option,  we will run VMENU next and simply
  982. exit if a MENU.VMN file is not found.
  983.  
  984.  
  985.      VMENU  interacts  heavily with the ZCPR3  System  Files
  986. which  are  defined  as  a part  of  the  ZCPR3  Environment
  987. Descriptor.   There are four System Files, and three of them
  988. are used by VMENU for various purposes:
  989.  
  990.      File      Purpose
  991.        2       Name of Current File
  992.        3       Name of Menu File
  993.        4       Name (containing wild cards) used to
  994.             Select Files for VMENU File Display
  995.  
  996.      System  File  2 contains the name of the current  VMENU
  997. file.    By  changing this name,  a transient can  cause  the
  998. pointer  of VMENU to point to some other file when VMENU  is
  999. reinvoked.
  1000.  
  1001.  
  1002.      System  File 3 contains the name of the menu file which
  1003. VMENU is using to derive menu displays and command from.  By
  1004. changing this entry,  a transient can select different    menu
  1005. files dynamically.
  1006.  
  1007.      System  File 4 is used to indicate which files (such as
  1008. *.TXT  or *.*) are selected for display by VMENU when it  is
  1009. invoked.   By  changing this entry,  the nature of the    file
  1010. display can be changed dynamically.
  1011.  
  1012. :E
  1013.  
  1014.             VMENU Error Messages
  1015.  
  1016.      In order to make VMENU as small as possible,  the error
  1017. messages have been reduced to a minimum.   VMENU provides  a
  1018. minimum indication that something is wrong and aborts.
  1019.  
  1020.      The  program  VMENUCK  is    designed to  tell  you    more
  1021. specifically  what  is wrong.    VMENUCK is  a  *.VMN  Syntax
  1022. Checker, and it looks for all sorts of error conditions that
  1023. can occur in a *.VMN file.
  1024.  
  1025.      VMENU provides the following minimal error messages:
  1026.  
  1027.  
  1028.       Message     Meaning
  1029.  
  1030.       No Shell Stack      Shell Stack Not Available
  1031.       No Command Line     Command Line Buffer Not Avail
  1032.       Shell Stack Full    Shell Stack is Full
  1033.       Shell Stack Size    Shell Stack Entries are too
  1034.                    short for VMENU cmd line
  1035.       File x.typ Not
  1036.          Found          Menu File Not Found
  1037.       TPA Full          Memory is Full
  1038.       <Bell>          User Command is in Error
  1039.       Password Error      Invalid Password Given
  1040.       Structure Error     *.VMN File Structure Error
  1041.  
  1042. :2
  1043.  
  1044. Command:  VMENUCK 1.3
  1045.  
  1046. Syntax:
  1047.      VMENUCK dir:ufn      <-- default file type is VMN
  1048.  
  1049. Function:
  1050.  
  1051.      VMENUCK is used to check the syntax of a *.VMN file for
  1052. the  ZCPR3 Menu Shell,    VMENU.     VMENU is optimized for size
  1053. and speed,  and,  in keeping it small,    built-in diagnostics
  1054. were reduced to the minimum.  VMENUCK is intended to be used
  1055. to  analyze *.VMN files and provide informative  diagnostics
  1056. on any syntactical errors with them.
  1057.  
  1058. Options:
  1059.      None
  1060.  
  1061.  
  1062. Comments:
  1063.  
  1064.      VMENUCK checks to see if the size of the *.VMN file  is
  1065. too large for the TPA available to the VMENU command.    This
  1066. is an additional check beyond the normal syntax check.
  1067.  
  1068.      VMENUCK  identifies  the  location of  errors  by    line
  1069. number.  The first line in the file is line number 1.
  1070.  
  1071. Selected Error Messages:
  1072.  
  1073.      Self-Explanatory.
  1074.  
  1075. Examples of Use:
  1076.  
  1077.      VMENUCK MYMENU
  1078.       -- perform check on MYMENU.VMN
  1079.  
  1080. or      Invalid Password Given
  1081.       Structure Error     *.VM