+-----------------------------------------------------------------------------+ The line above should be centered and one-inch below the top of form. - THE CHOOSE MANUAL TEXT FOLLOWS - __________________________________ | | | tm | | CHOOSE | | | | BATCH STREAM BRANCHING | | via | | MENU SELECTION | | | | Copyright, 1990-1993 | | | | HFK Software | | Sixty-Eight Wells Road | | Lincoln, MA 01773 | | | | 617-259-0059 | | | |__________________________________| Version 2.1 12-15-93 _______ _____|_ | ---| | |------------------(R) | | O | | O___|___ | Association of | | |_| Shareware |___| | Professionals | O | -------| | |-------------------- |___|___| Member T A B L E o f C O N T E N T S INTRODUCTION 1 INTRODUCTORY DEMO 1 SYSTEM REQUIREMENTS 2 INSTALLATION 2 MENU PRESENTATION 2 MENU SELECTION 4 BATCH BRANCHING 4 SPECIAL CHARACTERS 5 HIGHLIGHTED CHARACTERS 6 MENU COLORS 6 SYSTEM RE-BOOT 7 CLOCK FORMAT 7 DEBUGGING BATCH FILES 7 VISUAL IMPAIRMENTS 7 REGISTRATION 8 APPENDIX-A -- SAMPLE BATCH FILE 9 APPENDIX-B -- SHAREWARE DECLARATION 11 REGISTRATION FORM 12 -- I N T R O D U C T I O N -- CHOOSE provides an easy to use, yet powerful, means of menu controlled branching within the AUTOEXEC or other BATCH stream. A system administrator can use CHOOSE to organize a complex DOS environment so that users of the system may run programs under the proper directories by simply making menu selections -- that is, without an understanding, or keying, of long input strings, e.g., CD\DOCS\BUSINESS\SALES ... CHOOSE may be used as a conventional menu system to provide a main menu from which programs may be run; however, CHOOSE provides much more. Since menu selections cause a branch to a specific position within a batch file, DOS commands at that position not only can run a program, but also may select drives, change directories, copy and rename files, as well as present another menu with more choices and more branches. The number of menus in a batch stream is unlimited and you may nest or cascade menus as freely as needed. The more complex the environment, the more useful CHOOSE is in keeping things simple and avoiding error prone situations. -- I N T R O D U C T O R Y D E M O -- The details in this manual are more easily understood once you have seen CHOOSE in action. If you have not already run the MENU batch, you might wish to do so now by: 1. Making sure that your CHOOSE files are in the current drive/directory, 2. Entering "MENU" on the DOS command line, and 3. Experimenting by making various selections. After running the MENU batch, you may wish to examine the batch file (MENU.BAT) and relate the file content to the observed actions. -1- -- S Y S T E M R E Q U I R E M E N T S -- CHOOSE requires about 10K bytes of RAM and runs via batch files between other application programs. CHOOSE is NOT a TSR and does not require resident memory. That is, memory is of no concern because CHOOSE requires much less than most other applications. CHOOSE runs on an IBM PC (or equivalent) under DOS version 2.0 or later. -- I N S T A L L A T I O N -- CHOOSE installation is simple. Just copy the file called "CHOOSE.COM" onto your system disk. CHOOSE.COM may reside anywhere as long as the batch processor can find it (or it is explicitly referenced). CHOOSE.COM is normally copied onto the root directory and is available via the PATH. CHOOSE does work on diskette only computers, however complex batch files generally run slowly without a hard disk. In this case it may be worthwhile using a small "RAM DRIVE" to contain CHOOSE.COM, batch, and related files. -- M E N U P R E S E N T A T I O N -- CHOOSE menu text either originates on the CHOOSE command line, or in a file whose name is specified on the command line. Normally, CHOOSE is executed via batch files; but, for tutorial purposes, you may wish to install CHOOSE and experiment by entering CHOOSE commands in response to the DOS prompt. The three basic forms of a CHOOSE command are: CHOOSE CHOOSE ^<selection-1>^ ... ^<selection-N> CHOOSE <file specification> Entering just "CHOOSE" will result in a brief command summary display. -2- Entering CHOOSE *** MAIN MENU ***^Windows^WordPerfect^Backup will present the following menu, accept a user selection, and return with the BATCH ERRORLEVEL set to indicate which selection was made. +-------------------------------------------+ | *** MAIN MENU *** | |-------------------------------------------| | Windows | | WordPerfect | | Backup | |-----------+-------------------+-----------| | 9:07:29 | UNREGISTERED USER | 15-0CT-93 | +-----------+-------------------+-----------+ Note that the CHOOSE command contained title text (*** MAIN MENU ***) terminated by a carat (^) and followed by the text of three menu selections separated by carats. Up to seventeen menu selections may be specified. A DOS command line is limited to about 125 characters which limits the size of a CHOOSE menu that may be presented directly from a command line. When a CHOOSE menu exceeds the command line capacity, simply place the menu text in a file and specify the file name on the command line. When menu text is provided in a file, CRs (carriage return characters) are treated as carats and LFs and other non-text characters are ignored. Therefore, while you may provide menu text as one long line (just as on the command line), it is generally preferable to place each menu line on a separate file line (without the carats). CHOOSE menus are displayed centered both vertically and horizontally and overlaying any screen text. That is, CHOOSE does not clear the screen before constructing a menu. When a selection is made, CHOOSE restores the overlayed display text before exiting to DOS. Therefore, use the CLS command when you prefer a blank menu background. CLS CHOOSE *** MAIN MENU ***^Windows^WordPerfect^Backup -3- You may wish to have help, sample, or other text surrounding a menu. You might also wish to clear the background upon menu selection. For example: TYPE BACKGND.TXT CHOOSE *** MAIN MENU ***^Windows^WordPerfect^Backup CLS IF ERRORLEV . . . -- M E N U S E L E C T I O N -- CHOOSE uses standard menus with single-keystroke and point-and-shoot selection methods. When a menu is displayed, the user may make a selection by: (1) striking the key corresponding to the first (or highlighted) character of a menu choice, or (2) using the UP and DOWN arrow keys and/or the SPACE bar to position the menu selection bar on a desired item, and then striking ENTER to make the selection. Striking the ESCAPE key backs out without making a selection. If a mouse is available, it may also be used to make menu selections using any button. -- B A T C H B R A N C H I N G -- The power of CHOOSE results from the ability to change the course of execution within batch streams via menu selections. DOS's "ERRORLEVEL" is used to effect branching within a batch file. Whenever a menu selection is made, CHOOSE sets the ERRORLEVEL as follows and exits to DOS. ERRORLEVEL=17 SEVENTEENTH from LAST menu selection made ERRORLEVEL=16 SIXTEENTH from LAST menu selection made ERRORLEVEL=15 FIFTEENTH from LAST menu selection made ERRORLEVEL=14 FOURTEENTH from LAST menu selection made ERRORLEVEL=13 THIRTEENTH from LAST menu selection made ERRORLEVEL=12 TWELFTH from LAST menu selection made ERRORLEVEL=11 ELEVENTH from LAST menu selection made ERRORLEVEL=10 TENTH from LAST menu selection made ERRORLEVEL=9 NINTH from LAST menu selection made ERRORLEVEL=8 EIGHTH from LAST menu selection made ERRORLEVEL=7 SEVENTH from LAST menu selection made ERRORLEVEL=6 SIXTH from LAST menu selection made ERRORLEVEL=5 FIFTH from LAST menu selection made ERRORLEVEL=4 FOURTH from LAST menu selection made -4- ERRORLEVEL=3 THIRD from LAST menu selection made ERRORLEVEL=2 SECOND from LAST menu selection made ERRORLEVEL=1 LAST menu selection made ERRORLEVEL=0 ESCAPE struck BATCH's "IF ERRORLEVEL=" sub-commands are used following each CHOOSE line to cause the appropriate branching in control flow as shown in the following example. CLS CHOOSE *** MAIN MENU ***^Windows^WordPerfect^Backup IF ERRORLEVEL=3 GOTO :WINDOWS IF ERRORLEVEL=2 GOTO :WORD_PROC IF ERRORLEVEL=1 GOTO :TAPE_BACKUP GOTO :ESC_STRUCK NOTE -- Since the IF ERRORLEVEL sub-command does not test for EQUAL, but rather tests for GREATER THAT OR EQUAL TO, you must test for ERRORLEVELs in descending order. Hence, CHOOSE sets ERRORLEVELs in increasing order from the BOTTOM UP so that you may test from the TOP DOWN. If in the example above, the second menu selection is made, then CHOOSE exits with ERRORLEVEL=2, the first IF ERRORLEVEL sub-command fails (because the ERRORLEVEL is not equal to or greater than three), the second IF ERRORLEVEL succeeds, and control is transferred to a point in the batch file labeled ":WORD_PROC" where the appropriate DOS commands are executed. -- S P E C I A L C H A R A C T E R S -- Special characters may be used in menu title and selection text via a five-character symbol consisting of the display code (decimal) enclosed in braces. For example: {003} is displayed as a heart symbol, {168} is displayed as an inverted question mark, {171} is displayed as a 1/2 symbol, {172} is displayed as a 1/4 symbol, {241} is displayed as a plus-or-minus symbol, {242} is displayed as a greater-than-or-equal symbol, {243} is displayed as a less-than-or-equal symbol, {248} is displayed as a degree symbol, {060} is displayed as a less-than symbol (<), {062} is displayed as a greater-than symbol (>), {124} is displayed as a vertical bar (|), etc. -5- See your hardware reference manual for a complete list of display codes. NOTE -- DOS uses the "<" ">" and "|" characters in command lines as filter, redirection, and piping operators. If you provide menu text on a CHOOSE command line (rather than in a file), you must use {060} {062} and {124} to specify these special characters. -- H I G H L I G H T E D C H A R A C T E R S -- A character of a selection line may be highlighted by enclosing that character in braces. Using "Word{P}erfect" as a menu selection would display the line as "WordPerfect" with the "P" displayed differently and USED AS THE SELECTION KEY. That is, this selection may be made by striking the P-key instead of the W-key. -- M E N U C O L O R S -- When your display mode is CO80, menus are displayed using white characters on a blue background with highlighted characters shown in white also. Highlighted characters are displayed with extra intensity (bold) and are recognizable even without a color difference. You may override this color selection by beginning the menu text with a five-character color specification consisting of three color indicators enclosed in braces. The first indicator specifies the normal text color, the second indicates the color of highlighted characters, and the third the background color. The following eight letters are used to indicate each of the eight possible colors. R - Red G - Green B - Blue W - White M - Magenta Y - Yellow C - Cyan K - blacK For example: CHOOSE {BCW}MAIN MENU^Windows^WordPerfect ||| ||+-- causes White background |+--- causes Cyan highlighted characters +---- causes Blue normal text When your display mode is MONO or BW80, default and specified colors are ignored and menus are displayed using black char- acters on a white background with highlighted characters shown blinking. -6- -- S Y S T E M R E - B O O T -- In a complex environment, it may be necessary to re-boot (to clear an accumulation of drivers or TSRs from memory) and start fresh via AUTOEXEC. A "CHOOSE RE-BOOT" command will restart your system just as if you had held CTRL-ALT-DEL. In some cases, your batch process may temporarily substitute new AUTOEXEC.BAT or CONFIG.SYS files to effect the appearance of continuous (seamless) control. -- C L O C K F O R M A T -- CHOOSE displays the current time and date while waiting for a menu selection to be made. When you register, you may specify a clock format of "12" or "24" which indicates whether your copy of CHOOSE will display time in a 12- or 24-hour format. |-----------+----------- |-----------+---------- | 9:07:29 | REGISTERED U | 21:07:29 | REGISTERED U +-----------+--------------- +-----------+--------------- (12-hour format) (24-hour format) -- D E B U G G I N G B A T C H F I L E S -- CHOOSE batch files are normally run with "ECHO OFF" to keep the screen clear between menu displays. If your batch file is not running properly: (1) temporarily remove (or REM-out) ECHO OFF commands, (2) strike CTRL-P to enable command logging, (3) run the batch file, and (4) examine the printed command log. Comparing a desired batch flow with the actual batch flow generally makes the necessary batch file correction obvious. -- V I S U A L I M P A I R M E N T S -- CHOOSE has been designed to work with speech and large print systems used by the blind and visually impaired. All menu text is written directly to the screen memory, except for the menu title and the menu bar selection which are displayed via the cursor and BIOS (INT 10H). -7- When a speech system is tracking BIOS screen writes and a menu is displayed, the title and the first selection are verbalized. As the SPACE BAR is struck, the menu bar cycles through the selection lines verbalizing each. When a desired option is heard, striking ENTER makes the selection. The cursor is kept invisible, but always remains on the menu bar line. Hence, the selection under the menu bar can always be examined in detail using the features of the speech system in used. -- R E G I S T R A T I O N -- CHOOSE is a complete package that is provided as SHAREWARE (see Appendix-B). Enjoy getting to know CHOOSE and under- standing the benefits it provides. Feel free to make copies for your friends and co-workers. When you put CHOOSE to productive use, a small registration fee is due. A convenient registration form is included. When you register (via mail, fax or phone): YOU PROVIDE and YOU RECEIVE "Personalization text" to The registration codes to replace UNREGISTERED USER personalize your copy of (e.g., your personal or CHOOSE. company name). Twenty dollars ($20) via The right to put CHOOSE check or MasterCard/VISA to productive use and to account number/expiration receive support. date/signature. NOTE-1: This offer is subject to change without notice. NOTE-2: Use of CHOOSE within a commercial product requires a software license. -8- A P P E N D I X - A S A M P L E B A T C H F I L E ECHO OFF :MAIN_MENU -- DISPLAY MAIN MENU CLS CHOOSE MAIN MENU^{W}indows^Word{P}erfect^{F}ormat^{B}ackup IF ERRORLEVEL=4 GOTO :WINDOWS IF ERRORLEVEL=3 GOTO :WORD_PROC IF ERRORLEVEL=2 GOTO :FORMAT IF ERRORLEVEL=1 GOTO :TAPE_BACKUP GOTO :ESC_STRUCK :WINDOWS -- "Windows" SELECTED WIN GOTO :MAIN_MENU :WORD_PROC -- "WordPerfect" SELECTED CD\WORDPERF WP CD\ GOTO :MAIN_MENU :FORMAT -- "Format" SELECTED CLS ECHO Formatting diskette in Drive-A EZ-DEX KEYBOARD_PRIME=~ARCHIVE~N~ FORMAT A:/U/V GOTO :MAIN_MENU :TAPE_BACKUP -- "Backup" SELECTED MEM/C CHOOSE IS MEMORY FREE OF TSRs?^Yes (backup)^No (re-boot) IF ERRORLEVEL=2 GOTO :START_BACKUP IF ERRORLEVEL=1 GOTO :RE-BOOT GOTO :MAIN_MENU :START_BACKUP CD\TRAKKER TAPE CD\ GOTO :MENU1 :RE-BOOT ECHO RE-BOOTING SYSTEM CHOOSE RE-BOOT :ESC_STRUCK -- ESCAPE struck -9- NOTE-1: In this simple batch file (which might be a part of an AUTOEXEC), highlights are used so that single keystrokes of "W" "P" "F" and "B" may be used to select Windows, WordPerfect, Format and Backup. Only the "P" in WordPerfect need be highlighted, but the "W" "F" and "B" are highlighted so that the four selection keys are displayed in the same color. NOTE-2: Striking the ESCAPE key results in a transfer of control to ":ESC_STRUCK" at the end of the batch file which results in a return to the DOS prompt. A menu selection of "E{x}it" might have been used, but the GOTO for the ESCAPE-struck condition should NOT be eliminated (because someone might strike ESC). NOTE-3: At ":TAPE_BACKUP" the current memory allocation is displayed via "MEM/C" (not included in DOS 3) and a menu is presented overlaying the allocation infor- mation (without covering TSR names). The tape backup program performs poorly when TSR's are using large blocks of memory and this menu allows you to view the allocation display and re-boot if too much memory is blocked-out. This menu overlaying a memory usage report appears as follows: ------------- --------------------- ------------- MSDOS 15296 ( 14.9K) 3BC0 HIMEM 1072 ( 1.0K) 430 COMMAND 2626 ( 2.6K) A40 MOUSE 16272 ( 15.9K) 3F90 COMBO 114976 (112.3K) 1C120 EZ-DEX 11264 ( 11.0K) 2C00 NAV& +-------------------------------------------+ ANSI | IS MEMORY FREE OF TSRs? | RAMDRIVE |-------------------------------------------| FREE | Yes (backup) | FREE | No (re-boot) | FREE |-----------+-------------------+-----------| | 9:07:29 | UNREGISTERED USER | 15-0CT-93 | Total FREE : +-----------+-------------------+-----------+ Total bytes available to programs : Largest executable program size : 3145728 bytes total contiguous extended memory 0 bytes available contiguous extended memory 3080192 bytes available XMS memory MS-DOS resident in High Memory Area -10- A P P E N D I X - B S H A R E W A R E D E C L A R A T I O N This product is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for a members' products. You may contact the ASP Ombudsman via: ASP Ombudsman 545 Grover Road Muskegon, MI 49442-9427 USA FAX: 616-788-2765 or CompuServe Mail: ASP Ombudsman 70007,3536 HFK Software actively supports the goals and principles of the Association of Shareware Professionals. -11- -- C H O O S E R E G I S T R A T I O N F O R M -- +-Personalization-Text:--------------------------------+ +-Clock Format:--+ | | | | +-----(10-35-characters-in-place-of-UNREGISTERED-USER)-+ +-----(12/24-hr)-+ +-MasterCard-or-VISA-Account-No:--------------+ +-Phone:------------------+ | | | | +---------------------------------------------+ +-------------------------+ +-Exp:-----+ +-Signature:--------------------+ +-Fax:--------------------+ | | | ($20) | | | +----------+ +-------------------------------+ +-------------------------+ --(fold-back-here)--------------(first-fold)--------------(fold-back-here)-- +-------+ From: ________________________________ | place | | stamp | ________________________________ | here | +-------+ ________________________________ To: +------------------------------+ | | | HFK Software | | 68 Wells Road | | Lincoln, MA 01773-3702 | | | +------------------------------+ --(fold-back-here)--------------(second-fold)-------------(fold-back-here)-- This form may be: (1) folded and placed in a standard business window envelope; (2) folded, taped, stamped, and mailed without an envelope; or (3) FAXed to HFK Software at 617-259-0626. Phone orders via: 617-259-0059 Massachusetts residents must include state sales tax.