home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / rexx / rexxmenu / rexxmenu.doc < prev    next >
Encoding:
Text File  |  1992-11-25  |  11.1 KB  |  236 lines
  1. RexxMenu - An OS/2 REXX utility for prompting user selection from a choice
  2.            list.  Useful for quick access to commonly used programs or calls,
  3.            and for choosing options from among any file list.
  4.  
  5.            Written by Brent Noorda.
  6.            Copyright 1992 Nombas
  7.  
  8.            This document applies to version 1.1 of RexxMenu.dll.
  9.  
  10. RexxMenu is a Dynamic Link Library (DLL) which provides the OS/2 REXX
  11. programmer with the ability to get user input from a choice-list of options.
  12. EnviMenu.cmd and MenuPick.cmd are both REXX program files that can be
  13. called from the command line or batch file if you want to be
  14. protected from learning about the Rexx language.
  15.  
  16. This utility is shareware.  You are encouraged to freely copy and distribute
  17. all or part of it, provided that no fee is charged beyond normal media
  18. duplication and shipping costs, and that the entire contents of this
  19. distribution archive are included and referenced as separate shareware.
  20.  
  21. For registration information see the end of this file, choose the Register
  22. option from ReadMe.cmd, or use the file Register.FRM.
  23.  
  24. -------- New for version 1.1 from 1.01 and 1.0 ---------
  25.  
  26. 1. The /HID <str> option has been added, so that "secret" or "password"
  27.    options can be chosen from the menu but will not be displayed.
  28.  
  29. 2. The EnviMenu.cmd utility has been added so that RexxMenu can be called from
  30.    the command line or from a batch file.  This is done so that no specific
  31.    knowledge of REXX is required to create simple choice menus.
  32.  
  33. 3. The MenuPick.cmd utility has been added for common selection of from a
  34.    command-line list of options, as demonstrated in the Prompts.cmd
  35.    batch file.  Also for the REXXaphobic.
  36.  
  37. ------------------ Installation ------------------------
  38.  
  39. After unzipping RexxMenu.zip into a directory, you need only to run
  40. ReadMe.cmd, either from the command line or from the desktop.  ReadMe.cmd
  41. uses RexxMenu to learn about, install, and register RexxMenu.
  42.  
  43. -------------------- File List -------------------------
  44.  
  45. ReadMe.cmd   - Run this first.  This REXX file uses RexxMenu to guide you
  46.                through learning about, installing, and registering RexxMenu.
  47.  
  48. RexxMenu.doc - what you are now reading
  49.  
  50. RexxMenu.dll - Dynamic Link Library for calling RexxMenu and RexxMenuHelp
  51.                from a rex file.  ReadMe.cmd expects this file to be in the
  52.                current directory, but to use RexxMenu.dll from any
  53.                directory you must copy RexxMenu.dll into one of the
  54.                directories in you LIBPATH environment setting (see the
  55.                LIBPATH= line in your CONFIG.SYS).  The Install option in
  56.                ReadMe.cmd attempts to do this LIBPATH installation for you.
  57.  
  58. Register.FRM - This form can be printed out to register your shareware
  59.                version of RexxMenu.  The Register option in ReadMe.cmd
  60.                attempts to print this form for you.
  61.  
  62. EnviMenu.cmd - Utility for setting an environment variable from a file-based
  63.                menu list.  This is RexxMenu.dll for those who only work
  64.                from the command-line or from batch files, but are above
  65.                learning about REXX.
  66.  
  67. MenuPick.cmd - Like EnviMenu.cmd, this simple utility is a non-REXX shell
  68.                for command-line or batch file menus, but this version takes
  69.                the menu options in the command line, rather than from a
  70.                batch file.
  71.  
  72. AllInf.cmd   - This sample REXX program builds a list of all the *.INF files
  73.                on your disk and then uses RexxMenu to let you choose which
  74.                *.INF file to VIEW.
  75.  
  76. AttrMenu.cmd - This sample REXX program is similar to the ATTRIB.EXE command,
  77.                but it uses RexxMenu to let you pick, one at a time, which
  78.                file to apply the attribute change to.
  79.  
  80. CDMenu.cmd   - This sample REXX program uses RexxMenu to let you interactively
  81.                traverse drives and directory trees.
  82.  
  83. QuikMenR.cmd - This is a sample REXX file for a REXX program, which you might
  84. QuikMenE.cmd   put on your desktop, for quickly accessing your commonly used
  85.                programs or command files.  With a couple of keystrokes or
  86.                mouse-clicks your menu-chosen function is up and running.
  87.  
  88.                QuikMenR.cmd uses RexxMenu.dll directly, and is a REXX program.
  89.                QuikMenE.cmd uses the EnviMenu utility, and is a batch file for
  90.                performing almost identically to QuikMenR.cmd.
  91.  
  92.                I use QuikMenu many times a day, and this is the primary
  93.                reason why I created RexxMenu. This sample is taken from my
  94.                own desktop, and so not all of the options will work on your
  95.                system, as they may rely on my particular configuration,
  96.                program-set, and paths.  QuikMenu can be easily modified for
  97.                your own frequently-used functions.
  98.  
  99. Solitair.cmd - Many times a program will save a single configuration, without
  100.                consideration that you may want different configurations at
  101.                different times or for different people; KLONDIKE (OS/2
  102.                Solitaire applet) is such a program.  Solitair.cmd is a
  103.                sample REXX program that lets you choose and save a
  104.                personal configuration for KLONDIKE.  Now Joe, for example,
  105.                will not mess up Julie's preferred mode of play.
  106.  
  107. ViewInfo.cmd - This sample REXX file, which I frequently use, uses RexxMenu
  108.                to choose from a fixed list of commonly-accessed .INF files
  109.                for viewing.
  110.  
  111. Prompts.cmd  - This examples uses the MenuPick utility to select the environment
  112.                window for an OS/2 or DOS command-line session.
  113.  
  114. BRENT.SOL    - These *.SOL Files are used by the Solitair.cmd demonstration
  115. JOE.SOL      - program.
  116. JULIE.SOL    -
  117. ZACHARY.SOL  -
  118.  
  119. ---------------- How to use RexxMenu -------------------
  120.  
  121. If you can create a list of options in a file, then RexxMenu can prompt the
  122. user to choose an item from that list, using either the keyboard or a mouse.
  123.  
  124. SYNTAX: <Choice> = RexxMenu(<File>,[OPTIONS])
  125. Where:
  126.    File  - Menu selections will be taken from this file after all leading and
  127.            trailing whitespace, and all blank lines, have been ignored.
  128.    Choice - User-selected option from File.  If there is an error, no file
  129.             options are available, or /ESC exit, then return NULL string "".
  130.  OPTIONS are:
  131.    /INIT,str - Initial Menu selection will be first match to str
  132.    /SORT    - All menu options will be alphabetically sorted.
  133.    /PRE,str - Specifies that only lines in <File> that begin with <str> will be
  134.               menu choices. The Prefix <str> will be ignored.
  135.    /SUF,str - Specifies that only lines in <File> that end with <str> will be
  136.               menu choices. The Suffix <str> will be ignored.
  137.    /COM,str - Specifies that lines in <File> that immediately follow menu-
  138.               option lines and that begin with <str> will be shown as comments
  139.               when the menu option is chosen.
  140.    /PROMPT,str - Specifies the prompt <str> for keyboard entry. Default is
  141.               "Match:". If <str> is "NONE" then no prompt.
  142.    /TIME,sec - Specifies <sec> seconds timeout for default selection if no
  143.               initial action is taken.
  144.    /ESC     - Specify that if the ESCAPE key is pressed, then exit with
  145.               NULL string; if no /ESC then a selection MUST be made.
  146.    /HID,str - Specifies that menu selections beginning with <str> will not
  147.               be displayed. These selections can only be found by typing them
  148.               at the keyboard, not including <str>.
  149.  
  150. A REXX file called MONTHDOC.CMD that uses most of these options may look
  151. something like this:
  152.  
  153.    /* MONTHDOC.CMD - REXXMENU EXAMPLE FILE TO CHOOSE A DOCUMENT TO EDIT FOR
  154.     *                A MONTH. EXAMPLE: JANUARY.DOC, FEBRUARY.DOC, ETC....
  155.     *                WILL BE LISTED ALPHABETICALLY JUST SO WE CAN USE THE
  156.     *                /SORT OPTION.  THIS PROGRAM IS AN EXAMPLE OF WHEN A
  157.     *                REXXMENU REXX PROGRAM READS THE .CMD FILE ITSELF FOR
  158.     *                AN OPTION LIST.
  159.     */
  160.    CALL RxFuncAdd 'RexxMenu', 'RexxMenu', 'RexxMenu'
  161.    MonthChoice = RexxMenu('MONTHDOC.CMD','/INIT','January',,
  162.                           '/SORT','/SUF','.1992:','/COM','/* ',,
  163.                           '/PROMPT','Pick a month for DOC editing:',,
  164.                           '/TIME','10','/ESC')
  165.    if \ 0 = COMPARE(MonthChoice,'') then
  166.       '@start /F e.exe' MonthChoice
  167.    EXIT
  168.  
  169.    January.1992:
  170.    /* Recover from New Years.  Martin Luther King.  31 days.
  171.     */
  172.    February.1992:
  173.    /* Short month.
  174.     */
  175.    March.1992:
  176.    /* Long month.  Watch out for lions.
  177.     */
  178.    April.1992:
  179.    /* Short month.  Keep a look out for may flowers.
  180.     */
  181.  
  182. ----------------- RexxMenu Examples --------------------
  183.  
  184. Please try the included Examples for using RexxMenu (*.cmd files).  Some are
  185. silly, and some are useful programs that I frequently use myself.  These
  186. example programs are not optimized for speed (they often create temporary
  187. files wherever they happen to be) and possibly may not work in directory
  188. paths that contain the space character.
  189.  
  190. I will be collecting RexxMenu sample programs from any willing registered
  191. RexxMenu users to use in future updates.
  192.  
  193. ---------- RexxMenu Registration Information -----------
  194.  
  195. Thank you for Registering your shareware copy of RexxMenu version 1.1.  You
  196. may pay whatever amount you think RexxMenu is worth to you.  I suggest $5 as
  197. a minimum amount for a clean conscience for an indivdual, especially if you
  198. find that you are making frequent use of RexxMenu.  I would expect
  199. corporations with many RexxMenu users to pay proportionately more, of course.
  200. For any registration $10 or more, you will be notified that your registration
  201. has been accepted, and you will be notified of future bug-fixes, updates, and
  202. new uses (my own and other registered user's examples) for RexxMenu.
  203.  
  204. All comments, suggestions, and bug reports are welcome, whether or not you
  205. are registered.  Send to the address below, or contact Brent at:
  206.     Internet: bsn@world.std.com  or  (617)391-5289
  207.  
  208.     Enclosed RexxMenu registration amount:
  209.  
  210.        [ ] $5 conscience-ware
  211.        [ ] $10 support-ware
  212.        [ ] Other amount $__________
  213.  
  214.     How did you obtain this program? (optional) ____________________
  215.  
  216.     ________________________________________________________________
  217.  
  218.     Name: __________________________________________________________
  219.  
  220.     Address: _______________________________________________________
  221.  
  222.     ________________________________________________________________
  223.  
  224.     ________________________________________________________________
  225.                                          (add ZIPcode if applicable)
  226.     Country: ___________________________
  227.  
  228.     Comments: ______________________________________________________
  229.  
  230.     ________________________________________________________________
  231.  
  232.     Mail To:            Brent Noorda
  233.                         Nombas
  234.                         36 Tainter Street
  235.                         Medford, MA  02155    USA
  236.