Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD1.mdf / batch / library / stackey3 / batutil.doc next >

Wrap

Text File | 1990-03-25 | 258.6 KB | 6,031 lines

BBBBBB AAA TTTTTT UU UU TTTTTT IIII LLLL (tm) BB BBB AA AA T TT T UU UU T TT T II LL BB BB AA AA TT UU UU TT II LL BBBBB AA AA TT UU UU TT II LL BB BB AAAAAAA TT UU UU TT II LL BB BBB AA AA TT UU UU TT II LL LL BBBBBB AA AA TTTT UUUU TTTT IIII LLLLLLL Version 1.0 CTRLALT Associates _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER TABLE OF CONTENTS Chapter I:OVERVIEW........................................3 I.1 Shareware Considerations...........................3 I.2 What BATUTIL does..................................6 I.3 Help and Verbose Mode..............................8 I.4 Basic Syntax......................................10 I.5 Setting BATUTIL options from the environment......12 I.6 Reading commands from a file......................13 I.7 BATUTIL's line editor.............................14 I.8 The HAltif command................................15 I.9 Control Break handling............................16 Chapter II:SYSTEM INFORMATION............................18 II.1 Overview.........................................18 II.2 Time.............................................19 II.3 Operating System and Memory Information..........19 II.4 Console Information..............................22 II.5 Hardware Information.............................23 II.6 File information.................................24 II.7 The RUn Command..................................27 II.8 TOdayfile and MAkefile...........................28 II.9 The ERrorlevel command...........................29 Chapter III: DISPLAY TOOLS...............................30 III.1 Overview........................................30 III.2 Metastring Translation..........................30 III.3 BATUTIL's ECho command..........................34 III.4 The PRetty command..............................35 III.5 Bigecho.........................................36 III.6 Getting Echo/Pretty Input from a file...........39 III.7 Cursor Position and Hiding the Cursor...........40 III.8 The STdout command..............................40 III.9 Sounds..........................................41 Chapter IV:USER INPUT....................................43 IV.1 Menu Basics......................................43 IV.2 Getting a menu from a file.......................44 IV.3 Menu Options.....................................45 IV.4 GEtkey Basics....................................47 IV.5 GEtkey Options...................................49 IV.6 AScii, SCanread..................................52 IV.7 USername.........................................52 IV.8 Parameter Matching...............................53 IV.9 Querying the Lock status.........................54 Chapter V:ENVIRONMENTAL CONTROL..........................55 V.1 Environmental Impact Statement....................55 V.2 Environment Reports...............................57 V.3 SEt basics........................................58 V.4 Getting User Strings into the Environment.........59 V.5 Using the file pick list..........................61 V.6 Saving and loading the environment to a file......62 V.7 Batch file path control...........................64 V.8 Direct Editing of the path........................65 V.9 Direct editing of the environment.................66 Chapter VI:TIPS AND EXAMPLES.............................67 VI.1 General tips.....................................67 VI.2 Returning to your initial directory..............67 VI.3 Using BATUTIL in your autoexec.bat...............68 VI.4 A shell for LIST.................................70 VI.5 A two year olds' delight.........................70 VI.6 Sample batch files...............................71 Chapter VII:COMMAND REFERENCE............................74 Chapter VIII:ERROR MESSAGES.............................104 VIII.1 Fatal Errors..................................104 VIII.2 List of Error Codes...........................104 VIII.3 Explanation of Error Codes....................105 Chapter I:OVERVIEW I.1 Shareware Considerations BATUTIL is a program included in the STACKEY package by CTRLALT Associates. Full details as to warranty and license terms can be found in the STACKEY documentation. BATUTIL is shareware. You have a 30 day trial period from the time that you first use the program to see if it meets your needs. If you continue to use it after that time you are required to pay a license fee not as a contribution but because you are getting use from our program. Shareware is dedicated to the idea that users are best served by a chance to fully try out something as complex and individualistic as software before they buy it and that authors are served by an ethic that encourages wide copying for trial runs. But in order for the system to work you need to respect the trust that we show in you and register if you continue to use our program. BATUTIL can only be registered as part of the STACKEY package. License fees are as follows: License to STACKEY with printed docs $39 Consultants License to STACKEY $200 All licensing will get you the latest version on disk. The printed documentation is essentially identical to the documentation on disk. Details about what a consultant's license entitles you are contained in the STACKEY docs. Basically, you cannot distribute BATUTIL as part of a package of goods or services for which you charge a fee without one of the following: - a separate license for each person receiving the program - a consultant's license and you meet its requirements - the right to distribute this program as shareware for a fee - an arrangement with Ctrlalt Associates Details are in the STACKEY documentation. These restriction do NOT apply to copies you give for no fee to others for shareware evaluation. You may register by phoning or writing Support Group, Inc Lake Technology Park PO Box 130 McHenry, MD 21541 1(800)872-4768 (1-800-USA-GROUP) FAX 1(301)387-7322 Chapter I:OVERVIEW Page 3 Documentation for BATUTIL, Version 1.0 Mastercard/Visa and purchase orders from approved institutions are accepted. This is not the number for support (see below). Payment of the license fee gives you the right to use any version of BATUTIL with a major version number of 1. If there is a Version 2, an update fee may be required. In addition to the thirty day trial period, you may return the disks (and printed documentation) for a full refund if you are not totally satisfied for a period of 90 days after initial payment. You have the choice of one of two license terms: "use like a book" OR a single user license. The former allows you to place copies of this software on as many machines as you wish so long as there is NO CHANCE that more than one copy of BATUTIL will be loaded into any of the machine's memories at one time. The latter allows you to place copies on all machines for which YOU are the principal user even if there is a chance that OCCASIONALLY more than one copy is in use (for example, if you use BATUTIL on a office machine while a family member might OCCASIONALLY use a copy on a home machine at the same time). The 800 number is for orders only. Registered users may obtain support by writing to CTRLALT Associates or via Compuserve. Details can be found in the STACKEY documentation. In particular, Ctrlalt Associates have a section (Section 12) on Compuserve's PCVENA forum - leave messages there for 76004,1664. If you like the program, please give it to your friends, place it on bulletin boards and otherwise spread it around. We explicitly allow TRIAL use of it privately and in a commercial environment. You may give it away, but you may not charge for it or include it with commercial software without our written permission, or include as part of a package of services for which you charge without a consultant's license. An exception is made for user groups and shareware software distributors who are approved shareware distributors of the Association of Shareware Professionals, an organization to which both authors of BATUTIL belong. Details on these restrictions, ASP and information on the ASP Ombudsman can be found in the STACKEY documentation. The following names may be trademarked: Turbo Pascal, Turbo Professional, Turbo Plus, Pianoman, Desqview, Omniview, Software Carousel, Techhelp, Flambeaux Software, Intel, Microsoft, Lotus, 123, List, Ultravision, 4DOS, Qemm, 386Max, Eemram. BATUTIL, CTRLALT and STACKEY are trademarks of Ctrlalt Associates. Chapter I:OVERVIEW Page 4 Documentation for BATUTIL, Version 1.0 BATUTIL was written in Turbo Pascal. Extensive use was made of the routines in Turbo Professional published by Turbo Power Software and of Turbo Plus published by Nostradamus. The tunes used in the sound command were developed with Pianoman, a shareware program also available from Support Group, Inc. We would like to thank Quarterdeck Office Systems and Sunny Hill Software for providing information on the programming interfaces to Desqview and Omniview respectively, and Scott Bussinger and Kim Kokkonen for comments on our Ctrl-Break handler. BATUTIL is warranted for no particular purpose. While we have tried to make the program bug free, no software can be guaranteed to be free of bugs. Due to the complex nature of computer software CTRLALT ASSOCIATES does not warrant that the licensed Software is completely error-free, will operate without interruption, or is compatible with all equipment and software configurations. Repair, replacement or refund, at the option of the CTRLALT ASSOCIATES, is the exclusive remedy of the customer, in the event of a defect. By using this program, you accept it AS IS and agree that we will NOT be held responsible for any damages including but not limited to consequential damages or loss of data. This includes damages caused by problems of which CTRLALT Associates is already aware. We will attempt to correct any bug which is pointed out to us. Registered users are entitled to use bug fixes while still numbered 1.xx. We do not intend to support Version 1.xx once a Version 2.xx is available and you may need to pay an upgrade fee to a new version if there are any bug fixes made once Version 2.xx is available. You may ask for a full refund of your registration for a period up to 90 days after you register but only if you return the program package sent registered users and agree to destroy any copies of BATUTIL and STACKEY in your possession and cease using the programs. While we have attempted to make this documentation as clear as possible, we cannot guarantee that there will not be misunderstanding or user error. We specifically exclude any warranties, EXPRESS OR IMPLIED, including the IMPLIED WARRANTIES OF MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. SOME STATES DO NOT ALLOW THE IMPLIED WARRANTIES TO BE EXCLUDED. CONSULT A LAWYER TO SEE WHETHER OR NOT THE ABOVE EXCLUSIONS APPLY TO YOU IN YOUR STATE. Chapter I:OVERVIEW Page 5 Documentation for BATUTIL, Version 1.0 I.2 What BATUTIL does BATUTIL is a program with two purposes: to give you power inside your batch files and to give you more control over the DOS environment. Included in the information that you can get returned in either the DOS errorlevel or an environmental variable are - current time, date, day of the week - total amount and amount free of disk space, memory and EMS - CPU type and type of coprocessor if present - whether a file exists not only in the current directory but on the DOS path and if it exists on the DOS path, the actual directory can be returned in another environmental variable - whether a file has today's date or not - whether one of two files is older than another - you can parse a filespec into individual components Some of these options may not seem so useful at first sight, but, for example, whether a file has today's date or not can be used to make a routine that will only get run once per day. Chapter VI will explain sample uses of BATUTIL. - whether Desqview, Carousel or Omniview is running and, if, so which partition you are in Central to the design of BATUTIL is the notion of "high level" language. There are much more sophisticated batch languages available and in them one can write menus at least as involved as are available in BATUTIL's MENU command. But doing so requires you to write a little program in the batch language while MENU is a built in command of BATUTIL. Virtually all the language elements (branching) will come from DOS' IF command (although BATUTIL does have a HAltif command, which is primitive but useful). In addition to getting information from the operating system, you can pass information to and get information from the user. BATUTIL gives you considerable control over displaying information including the possibility of turning the cursor on and off and displaying messages in various colors. And BATUTIL understands the metastrings that STACKEY does so you can easily display data like today's date in English. As for user input it can be obtained in various forms - There is a getkey routine that lets you list a set of keys using STACKEY syntax and get which key in the list the user has hit - whether a lock key is currently pressed - with some simple commands, you can popup an elegant menu Chapter I:OVERVIEW Page 6 Documentation for BATUTIL, Version 1.0 for the user to pick from and have the choice returned in the errorlevel - You can have the user input a string and get it stored in the environment - You can have the user type in a user name or password and see whether it matches a predetermined list and have which item is matched reported in the errorlevel - You can popup a filename list for the user to choose from and have the answer stored in the environment BATUTIL also gives you considerable control over the DOS environment. It is able to do this by using undocumented features of the operating system. As always, such features should be used with care. PLEASE READ CAREFULLY THE WARNING AT THE START OF CHAPTER V CONCERNING USING UNDOCUMENTED FEATURES TO ACCESS THE DOS ENVIRONMENT. BATUTIL's environmental control has been tested with PCDOS Version 2.0, 2.1, 3.0, 3.1, 3.2, 3.3, 4.0 and some flavors of MSDOS. Besides being able to place information into the environment via user input, BATUTIL will - display more information about the environment than the SET command - allow you to put strings in the environment up to a length of 255 characters rather than the 127 character maximum that DOS allows. In particular, with BATUTIL, your PATH string can be up to 250 characters rather than the 122 characters that you can enter with DOS. While DOS doesn't care about long paths, you may have an application program that does and crashes if it finds a path over 127 bytes (during the entire testing period, we only found one program Techhelp from Flambeaux Software with this problem). - allow simple commands to add a directory to your PATH without inadvertently adding one already there and allow deletion of a directory from your PATH - allow full screen editing of your environment and PATH. - allow you to save the environment to a file, to load or merge a file into the environment and to kill the environment (use with care). The files in the BATUTIL package are as follows: BATUTIL.EXE The basic program. The only file required to use BATUTIL BATUTIL.HLP Online help called by BATUTIL if you use BATUTIL ? or BATUTIL ! BATUTIL.DOC Documentation in electronic form BUDEMO.BAT Sample batch file which will call Chapter I:OVERVIEW Page 7 Documentation for BATUTIL, Version 1.0 the other sample batch files COLORDEM.BAT Sample batch file shows color capability EQUIP.BAT Sample batch file shows ability to read hardware INPUTDEM.BAT Sample batch file shows ability to get input from the user MENUDEMO.BAT Sample batch file shows BATUTIL's menu making capability SHOWDEMO.BAT Sample batch file shows display options including big characters and metastrings SOUNDEMO.BAT Sample batch file with BATUTIL's 20 sounds/tunes WHATEL.EXE Program described in Section II.7 to determine errorlevel and timing for some command BATUTIL, its help file and documentation are copyright 1988- 90 by Barry Simon and Richard Wilson, all rights reserved. If you obtain BATUTIL/STACKEY from Support Group, Inc directions for installing the programs can be found in the STACKEY docs and with a readme.com file. ******************************************************************* IMPORTANT NOTES Users of 4DOS version 2.x; please read Section V.1 before calling for technical support. CTRLALT Associates wishes to warn you that the SO command may change in future versions - the precise sounds for sounds 1-10 may change. In addition, future versions of BATUTIL may adopt the Windows standard use of & in menu choices so you should avoid the use of the & symbol in your menu choices (although && for & will be supported). ******************************************************************* I.3 Help and Verbose Mode You can obtain interactive help for BATUTIL by typing in BATUTIL ? or BATUTIL ! at the DOS prompt. To obtain help, the binary file BATUTIL.HLP Chapter I:OVERVIEW Page 8 Documentation for BATUTIL, Version 1.0 must be available in the current directory or the directory where BATUTIL is loaded or in your path. BATUTIL looks for the first two non-blank characters following the ? (or !) and if they are a valid BATUTIL command, you will be immediately sent to the help for that command; otherwise, the main help menu will be displayed. For example BATUTIL ? SE would display help for BATUTIL's SET command as would BATUTIL ?see the beautiful program BATUTIL ? displays the menu oriented help with various special effects. If these effects and the slightly longer time they take bother you, BATUTIL ! will display help without the special fades for displaying material. The help program uses color attributes on a graphics monitor. If you have a two color graphics monitor (such as on a laptop) or the colors are hard to see, the help program will use monochrome attributes if you use SET BU!=bw in your autoexec.bat file or at the DOS command line before running BATUTIL. Note that on a true monochrome adapter (IBM MDA or Hercules monographics card), the help program will not use color attributes whether you use that set command or not. Normally, BATUTIL exits when there is an error and sets the errorlevel between 200 and 253; see the discussion in Chapter VIII. There are three levels of visual error reporting that you can have turned on. For debugging purposes the default is a verbose mode where BATUTIL will explain why it is exiting. For batch files you distribute you may want to have verbose mode turned off and instead use a Quiet mode where no messages are displayed. To turn on this quiet mode, just make the first non blank character in the command line the letter Q. Thus, BATUTIL {} would display an error message while BATUTIL Q {} would exit without any message. For distributed batch files made with BATUTIL, you may want to turn on quiet mode using an environmental variable as described in Section I.5. Command line mode takes precedence over any mode set in the environment and, in particular, you can override the mode set in the environment and restore to the default Verbose mode by making V the first letter on the command line after "BATUTIL". Chapter I:OVERVIEW Page 9 Documentation for BATUTIL, Version 1.0 Chapter VIII has a complete list of error codes with an explanation of each. The online help main menu has an option to list all error numbers and their meaning. In batch files, the error message may disappear too fast for you to see. In addition to Verbose mode, BATUTIL has a Pause mode which shows the error message and waits for a key before exiting. Pause mode is set with the letter P. To see the information which BATUTIL is placing in the environment while testing out what a command will do the following one line batch file (or an equivalent CED synonym) is useful: batutil %1 %2 %3 %4 %5 %6 %7 %8 %9 {EC $x(rc)} The final command echoes the current value of the environmental variable RC to the screen. I.4 Basic Syntax Command: REmark You give BATUTIL a series of commands on the command line. There are about 100 different commands - lest that overwhelm you, we note that many are just giving different pieces of hardware information which you'll rarely want and even the most complex idea (menus) are controlled by one basic command and fewer than ten commands which effect options like whether the menu explodes. Chapter VII is a detailed alphabetical command reference. When you invoke BATUTIL's help, one option is an alphabetical list of commands which will give you a panel with syntax and parameters for each. The basic syntax is BATUTIL {command1} {command2} ... Each command is placed inside braces {} (or square brackets []; see below). The braces are critical - it doesn't matter whether you have spaces between } and the next { or not. All commands have a two element minimal truncation. That is all commands are distinguished already in the first two symbols and any substring of the command that has at least two letters will work. For example, the basic command to get a report on the environment is BATUTIL {envrep} The minimal truncation for that is EN so we'll often write ENvrep Chapter I:OVERVIEW Page 10 Documentation for BATUTIL, Version 1.0 to emphasize this. Thus BATUTIL {en} or BATUTIL {envr} would work just as well as the full name. The basic commands are not case sensitive so {EN} or {En} or even {eNvRe} would do the same thing as {envrep}. Roughly fifty of the commands return to the user (i.e. you as a batch file writer) a number from 0 to 199. If the command in question appears inside {} then that number is stored in the environmental variable RC (short for "return code"; environmental variable are discussed at the start of Chapter V). If the command appears in [], then BATUTIL will exit without running the rest of the command line and place this integer in the DOS errorlevel where you can test it with commands like if errorlevel .... (see Chapter VI). IF THE LAST COMMAND ON THE LINE RETURNS AN INTEGER AND IT IS PLACED IN {}, THEN the integer is both placed in the real environment and placed in the error level. For example, DRive reports the current drive with 0=A, 1=B, etc. If the current drive is D, then BATUTIL .... [DR] will set the errorlevel to 3, while BATUTIL .....{DR} {echo hi there!} would set an environmental variable RC to 3 and then echo "hi there!". Thus if you ran the SET command after batutil, you'd find the line RC=3 on your screen. Some commands will take optional parameters which also appear inside the braces for that command. Thus @Disk gives the free disk space. If no parameter is specified, then the current default drive will be used. Otherwise you can specify a drive as in BATUTIL {@D C} BATUTIL will object to incorrect syntax so if you tried BATUTIL {@D 3} then BATUTIL will exit (with an appropriate message if Verbose mode is on). You can separate the command from the first parameter by any of the following: <space>,<comma>,= or : Rules of separation of multiple parameters for those few commands which accept multiple parameters depend on the commands. Chapter I:OVERVIEW Page 11 Documentation for BATUTIL, Version 1.0 Before doing anything BATUTIL scans the command line and makes sure that every command is a proper one for this version of BATUTIL. If not, it will exit. Otherwise, it will execute the commands one at a time. It does not check for parameter syntax until that command is reached. Thus {@D 3} will halt BATUTIL when reached but earlier commands will already have run. We are well aware that many of you will run into the problem that DOS limits commands to 127 characters. As we will explain in Section I.6, three commands will read parameters in from a file. We hope that a future release will allow reading in a file of all commands. User feedback will determine how high on the list we put such an enhancement. You may place remarks in the BATUTIL command line by enclosing them inside {} with the REmark command as in BATUTIL {AT 4F}{CL}{REM clears the screen in red!} I.5 Setting BATUTIL options from the environment When BATUTIL loads, before reading the rest of its command line, it looks for an environmental string of the form BU@=string and it first reads that string as if it were a command line and places the commands in it to be processed first. This is intended primarily to allow you to change the built in default options to some other value. For example, to turn off beeps and change the default on GEtkey from flushing the keyboard to not, you'd use: BU@={NB}{NF} This option is useful if you want to permanently turn on pause mode; you'd use BU@=P {NB} if you wanted to also turn beeps off. Since BATUTIL looks in the environment, you place the information that you want there using the DOS SET command (or BATUTIL's SET command if you want!); for example, you might place a line set BU@=P {NB} in your autoexec.bat file. It is important to place NO spaces between BU@ and the =. Spaces after the = are unimportant. Chapter I:OVERVIEW Page 12 Documentation for BATUTIL, Version 1.0 There are three other environmental variables of interest. One is the variable BU$. At the end of the commands to edit your path and the environment ({PAthedit} and {EDitenv}) and after using help, a screen will appear reminding you of the fact that BATUTIL is shareware limited to a 30 day trial period. You can suppress this screen by placing BU$=I paid in your environment. Obviously, having told you the secret, you can do it even if you haven't paid - let your conscience be your guide. The variable BU^ can be used to turn off ^Break handling; see Section I.9. The final environmental string that BATUTIL pays attention to is CUR (for CURSOR). It looks for two possibilities: CUR=no Normally, BATUTIL restores the cursor when exiting, even if you have turned it off with the {CU -} command of Section III.7 If this string is present the cursor is not turned back on but its state is not changed. The other possibility is CUR=off When starting or exiting the program, BATUTIL will turn the cursor off if this string is found at that point. All other values of CUR are ignored. Because it takes a noticable time for BATUTIL to load, if you are processing multiple BATUTIL lines in a batch file, you may want to have the cursor turned off. I.6 Reading commands from a file Three commands are able to read information in from a file. The ECho command displays text on the screen in colors you set before the echo command; PRetty displays text in colors that you can adjust as part of the string displayed and MEnu displays a user defined menu. The analogous file reading commands are FEcho, FPretty and FMenu. Each command takes two parameters: the first is a filename and is required, the second a label name which is optional. If the filename is given without a drive or directory, then it is searched for first in the current directory. If not found by BATUTIL, BATUTIL will attempt to add an extension of bat and look again. Then the same search is made in the directory that batutil was loaded from (under DOS 3.0 and later) and finally in the DOS path. If still not found, BATUTIL exits and an error message is issued. Chapter I:OVERVIEW Page 13 Documentation for BATUTIL, Version 1.0 If no label name is given, then BATUTIL will start reading and processing the file from its beginning. If a label is given, BATUTIL reads the file from the beginning but searches until it find a line beginning with :label (leading spaces before the : are ignored and labels are NOT case sensitive). For example batutil {FE foobar.txt hi} would look a file named foobar.txt and then search for a line starting with :hi If the label is not found, then BATUTIL exits with an error message. Otherwise the file is processed one line at a time until the next line beginning with a : is located. Lines whose first symbol is a ; are ignored (i.e. treated as remarks). You can combine batch file labels and BATUTIL's labels to keep the extra lines to display in the batch file itself. For example, the following could be at the start of a batch file: goto codestart :echostart This line will be echoed and this will appear on the next line ;but this line is a remark The last line doesn't have an explicit CR added :codestart batutil {FEcho %0 echostart} Because BATUTIL will add .bat to a filename if it cannot find the file without that, the %0 will be properly interpreted (unless you happen to have a file with the same name as the batch file and no extension). I.7 BATUTIL's line editor Four of BATUTIL's commands allow editing of line input: the EDenv and PAthedit commands which allow you to edit any environmental variable and your path, the USername command which prompts for a string to be matched and the $Q/$? subcommands of BATUTIL's SET which place information in the environment. When such input is asked for the following edit keys are active <Enter> accepts the current string and exits <Esc> restores the original value of the string; if that original value is empty, <Esc> blanks the line except, in that case, <Esc> with a blank line exits and returns an Chapter I:OVERVIEW Page 14 Documentation for BATUTIL, Version 1.0 empty string <Left>, <Right> move the cursor by a character <^Left>, <^Right> move the cursor by a word <Home>, <End> to the beginning or end of the line <Ins> toggles insert mode which starts as overwrite mode; the cursor shape indicates what the current mode is <Del> and <Bks> do their usual single character functions <^X> or <^Y> blanks the entire line <^End> blanks to the end of the line <^Home> blanks from the start of the line ot the current position. <^T> blanks from the cursor position through the next blank space In addition, WordStar commands are accepted for most of these functions, e.g. ^S is the same as <Left> and the two letter ^QS (or ^Q^S) is the same as <Home>. In situations where the quantity being edited has a prior value, that value is displayed when the line editor starts up and the cursor is at the end of line. Hitting an alphanumeric key (as opposed to a cursor key) as the first key will blank the original value which can be restored with <Esc>. In each case, the input string has a maximum length which may be larger than the edit window on screen. If it is larger, the line editor with scroll horizontally if the cursor moves to the start or end of the edit window. The point is that the editor is quite intuitive and most users will have no trouble using it without explicit directions. I.8 The HAltif command Command: HAltif Parameters: two strings separated by one of =, $g, $l or $q with an optional "~ " preceding the strings. BATUTIL has one rather simple branching command. HALTIF is followed by a condition. If the condition holds then BATUTIL halts execution with that command and exits with an errorlevel of 254. If the condition fails then the remainder of the command line is processed. The condition compares two strings with a comparison of =, > or <. SINCE > AND < ARE DOS REDIRECTION SYMBOLS NEVER USE THEM IN ACTUAL COMMAND. As we'll explain in Section III.2, BATUTIL Chapter I:OVERVIEW Page 15 Documentation for BATUTIL, Version 1.0 has a set of metastring translations which are a superset of those used by DOS' prompt command and by STACKEY. The parameters after HAltif are translated using the metastring rules and, in particular, $g, $l, $q become >,< and = (you can use = if you prefer). If, after translation, both strings can be interpreted as whole numbers less than 134217727 in magnitude, then the comparison is done as numbers (so 012 is the same as 12 and 05 is great than 3). Otherwise the comparison is done as ASCII strings which compares characters one by one and regards a substring as less than a longer string (so a05 is smaller than a3). One or both strings can be empty. You can preface the strings by ~ followed by a space in which case the condition is negated, i.e. BATUTIL halts if the condition after ~ fails. Here are some examples {HA $x(comspec)=} will halt only if there is no environmental string called comspec ($x(...) translates to an environmental variable). {HA $H $l 12} halts if the current hour ($H) is smaller than noon. {HA ~ $x(rc)=0} will halt unless the environment has a string rc=0 (or rc=00 or ...). I.9 Control Break handling BATUTIL looks especially for the user to press ^Break. If this is pressed during the running of batutil, then the message ╒════════════════════╕ │ Quit BATUTIL(Y/N)? │ ╘════════════════════╛ pops up. If you answer no, then BATUTIL continues where it was interrupted. Otherwise, it pops up a message: ╒═══════════════════════════╕ │ Halt Batch file too(Y/N)? │ ╘═══════════════════════════╛ In either event, BATUTIL is then halted. If you've also answered yes to the second question, then BATUTIL will turn DOS Break on and place a ^C buffer so the batch file should offer you the chance to Chapter I:OVERVIEW Page 16 Documentation for BATUTIL, Version 1.0 terminate it. If you prefer running with Break off, you'll need to do that by hand if you use this emergency exit. This response is to ^Break only and NOT also to Ctrl-C. If you quit BATUTIL with ^Break but elect not to halt the batch file, BATUTIL exits with the errorlevel set to 255. For third party batch files, you may want to turn off ^Break to prevent the user from breaking at an inconvenient point. When BATUTIL loads, it checks to see if BU^=no is in the environment; if it is, then the Ctrl-Break handler is not installed, so just include set BU^=no in the batch file to avoid this premature exit. Chapter I:OVERVIEW Page 17 Chapter II:SYSTEM INFORMATION II.1 Overview You can use BATUTIL to query the system to get information about the current date and time, the current drive, hardware information like the number of monitors or printer ports, file information like whether a particular file exists on the DOS path. Related are a primitive MAKE command which examines two files and tells you which is older and a RUN command which will tell you the errorlevel that a subsidiary program returns. You can get the information stored in the special environment variable RC or in the errorlevel or both. For example, BATUTIL [HO] returns the current hour in the errorlevel while BATUTIL {HO} returns it in both RC and the errorlevel. Only the last {} command on the line has information returned in errorlevel. If any [] command is encountered then that is the last command that BATUTIL executes before exiting. Except for the internal FDir command, all commands discussed in this chapter are dual mode []/{} commands. If an intermediate result is stored in an environmental variable like RC, you can have it placed in the errorlevel with the ERrorlevel command as in batutil {HO}{EC The current hour is $x(rc)}[ER $x(rc)] The $x syntax is discussed in Section III.1. Many commands come in pairs like #Disk and @Disk starting with # or @. Typically, # refers to total and @ to free so that BATUTIL [#D] places in the errorlevel the total space on the default drive and BATUTIL [@D] the amount of free space. As in STACKEY, the left round parenthesis, (, is a synonym for @ and the right round parenthesis, ), for #. Thus the last command could also be BATUTIL [(D] Commands have full names such as HOUR but any name can be abbreviated by using two or more letters as in HO or HOU. To emphasize this, we'll write the commands as HOur but that does not mean you have to type the command with that capitalization. BATUTIL's command interpreter is not case sensitive. When you want to squeeze a lot on the command line, you'll want to use the two letter abbreviation. Chapter II:SYSTEM INFORMATION Page 18 Documentation for BATUTIL, Version 1.0 You'll often want to use the SEt command and metastring expansion in connection with or instead of the commands of this chapter. The SEt command is described in Section V.3 and metastrings in Section III.1. As examples of what we mean, BATUTIL {#comm}{set comm=$x(rc)}{#prn}{set prn=$x(rc)} would place the number of comm ports in the environment as comm=nn and then the number of printers as prn=nn but one wouldn't use BATUTIL {HO}{set hour=$x(rc)} since there is a metastring for the current hour and one could just as well use BATUTIL {set hour=$H}. II.2 Time Commands: HOur, MInute, WEekday, DAte, MOnth, YEar You can return information on the time and date in the errorlevel as follows HOur the hour in military time from 0 to 23 MInute the number of minutes past the hour from 0 to 59 WEekday the day of the week from 0=Sunday to 6=Saturday DAte the day of the month from 1 to 31 MOnth the number of the month from 1 to 12 YEar the number of years since 1980 from 0 to 19 so in 1988 this would return 8. II.3 Operating System and Memory Information Commands: DOs, DRive, LIm, HImem, CArousel, DView, OView, #Mem, @Mem, #Lim, @Lim, #Xtended, @Xtended, #Env, @Env, #Disk, @Disk Parameters: For #D and @D, no parameter picks default drive or you can give a drive letter. For DOs, nothing or "4" You can return the following information about the operating environment: DOs returns the DOS Version times 10 rounded downwards so DOS 2.1 would return 21 and DOS 3.21 would return 32. Chapter II:SYSTEM INFORMATION Page 19 Documentation for BATUTIL, Version 1.0 "DOs 4" returns information about the program 4DOS from JP Software, an alternative to Command.com. If a swapping version of 4DOS is loaded anywhere in memory, then the value 10 times the 4DOS version number is returned; otherwise the value 0 is returned. This requires 4DOS Version 2.1 or later. DRive returns the current drive with 0=A, 1=B, ...., 25=Z. This is the drive as DOS reports it so if SUBST is in effect, the subst letter will be used. LIm returns 0 if no EMS manager is installed and the Version times 10 rounded downwards so to check whether an EMS 4.0 driver is installed you'd use BATUTIL [LI] if errorlevel 40 ..... HImem returns 0 if no XMS manager setting up the Microsoft Himem area is installed and a 1 if such a manager is installed. Examples of XMS managers are Himem, which comes with some versions of Windows and DOS, 386 to the max and QEMM/386. CArousel returns 0 if SoftLogic's SOFTWARE CAROUSEL is not installed and otherwise returns the partition number from 1 to 12 (1 to 10 with Carousel version prior to 3.0). DView returns 0 if Quarterdeck's DESQVIEW is not installed and otherwise returns the partition number from 1 to 255. OView returns 0 if Sunny Hill's OMNIVIEW is not installed and otherwise returns the partition number from 1 to 10. You can also get information about memory and disk resources: #Mem returns the total conventional memory in units of 4K from 0 to 160 (160 means 640K); the amount is rounded down. If you have an appropriate program/hardware combination to have more than 640K of conventional memory (EEMRAM, 386 to the max or QEMM, for example), then the number returned may be more than 640K but it will never be more than 184. @Mem returns the free conventional memory in units of 4K #Lim returns 0 if no EMS memory is present; otherwise, it returns the total EMS memory in units of 64K from 0 to 199. This Chapter II:SYSTEM INFORMATION Page 20 Documentation for BATUTIL, Version 1.0 is rounded down and with 12736K or more of EMS, 199 is returned. @Lim returns 0 if no EMS memory is present; otherwise, it returns the free EMS memory in units of 16K from 0 to 199. This is rounded down and with 3184K or more of free EMS, 199 is returned. #Xtended returns 0 if no extended memory is present; otherwise, it returns the total extended memory in units of 64K from 0 to 199. This is rounded down and with 12736K or more of extended memory, 199 is returned. @Xtended returns 0 if no extended memory is present; otherwise, it returns the "free" extended memory in units of 16K from 0 to 199. This is rounded down and with 3184K or more of extended memory, 199 is returned. Because there is no standard for extended memory usage, BATUTIL is not totally accurate in its count of free extended memory. It subtracts from the total available the amount used by VDISK and VDISK compatible programs. #Env returns the total amount of environment space in units of 16 bytes. See Section V.1 for a discussion of the DOS environment area. The answer can be from 0 to 199 with 199 corresponding to 3184 or more bytes. @Env returns the free environment space in units of 1 byte. The answer can be from 0 to 199 with the later indicated 199 or more. #Disk returns the total amount of disk space. An optional parameter is allowed of a letter. If no parameter is given, then the response is for the default drive. For drives A and B the errorlevel is space in units of 8K from 0 to 199 rounded down. If there is more than 1592K (not possible on currently available diskettes) a value of 199 is returned. For drives other than A, B the amount is in units of 256K from 0 to 199. For drives of 49.75 Meg or more (possible only under DOS versions greater than 3.30 or with special software), 199 is returned. If an invalid drive letter is given, the errorlevel is set to 232. If there is a syntax error such as asking for {#D 7}, the errorlevel is set to 208. @Disk returns the amount of free space on a disk drive with the same parameters and errorlevels for errors as #D. For any Chapter II:SYSTEM INFORMATION Page 21 Documentation for BATUTIL, Version 1.0 drive, the amount free is reported in units of 8K from 0 to 199. With more than 1592K free, the value returned is 199. Please note that @D and #D use different units. II.4 Console Information Commands: #Terminal, @Terminal, #Vmode, #Whichmon, #Altmon, @Ansi, #Keyboard, #Rodent BATUTIL will give you information about the system monitors and keyboards as follows: #Terminal with no parameter returns the number of monitors you have, either 1 or 2. With the parameter R (or r or even Rows if you prefer), it returns the number of rows on the screen. IBM EGAs support 43 rows as well as 25 and VGAs support 50. Many superVGAs support 33, 36 or 60 rows. UltaVision also supports non-standard numbers of rows. Similar UltraVision and some SuperEGA or SuperVGAs support 120 or 132 columns and #T with the C parameter returns the number of columns. Some programs require 1 less than the number of rows so S, for Special as a parameter returns that. @Terminal returns the currently active monitor: 0 if mono and 1 if color (or CGA compatible B/W like the old style Compaq monitors). #Vmode returns the current video mode as reported by int 10H. #Whichmon returns the type of the current monitor according to the following table: 1 = monochrome (old style MDA) 2 = cga color 4 = ega color 5 = ega mono 6 = professional graphics controller 7 = vga mono 8 = vga color 11 = mcga mono 12 = mcga color 21 = hercules mono 22 = hercules monochrome plus (with RAM font) 23 = hercules Incolor 99 = unknown If this ordering seems bizarre to you, it does to us also! The Chapter II:SYSTEM INFORMATION Page 22 Documentation for BATUTIL, Version 1.0 numbers below 20 are taken from the official "Display Combination Code" in the IBM PS/2 computer BIOS and who are we to argue with IBM. #Altmon returns information about the second monitor if you have one. Allowed values are 0 (which indicates no second monitor) and the numbers above. @Ansi returns 1 if an ANSI.SYS compatible console driver is installed and 0 otherwise. #Keyboard will return whether an "enhanced" keyboard is attached (the enhanced keyboard is the 101 key keyboard with the function keys across the top and the CapsLock where everyone knows the Ctrl key should be). A 0 response indicates a 84 key keyboard and a 1 the enhanced keyboard. Actually, BATUTIL is not testing the keyboard but rather the presence of BIOS support for the enhanced keyboard. #Rodent returns 1 if a Microsoft compatible mouse is found and 0 otherwise. II.5 Hardware Information Commands: #Intel, @Intel, #Prn, @Prn, #Comm, #Game, #Floppy, @Floppy Parameters: For @P, printer number from 1 to 3; no parameter picks LPT1. #Intel tests what CPU you have and reports as follows: 0 = 8086/8088 1 = 80186 2 = 80286 3 = 80386 20 = NEC V20/V30 @Intel tests what kind of math coprocessor that you have and reports as follows: 0 = no math coprocessor 1 = 8087 2 = 80287 3 = 80387 Chapter II:SYSTEM INFORMATION Page 23 Documentation for BATUTIL, Version 1.0 For technical reasons, only one occurrence of #I/@I per running of BATUTIL is allowed; you'll need to place @I and #I on separate lines if you want both. If two occurrence are found on the command line, BATUTIL will exit with a syntax error 210. #Prn reports the number of printers attached to your system (or more precisely the number that DOS thinks you have attached) @Prn returns error information for one of your printers. You can specify a printer number or, if none is given, LPT1 will be tested. The number returned means: 0 = printer status OK 1 = paper out error 2 = I/O error 3 = Timeout error 4 = invalid printer 5 = other printer error If you have a print spooler installed, you'll get a response of 0 even if the printer is offline or out of paper. #Comm returns the number of serial ports that you have; with more than 2 ports present, the method may not be reliable depending on how your non-DOS ports are added on. #Game returns the number of game ports that you have (or at least that BIOS thinks you have as stored in the equipment byte). #Floppy returns the number of Diskette drives you have @Floppy returns the following information 0 = you have none or more than 1 diskette drive 1 = you have a single diskette drive which is currently logical drive A 2 = you have a single diskette drive which is currently logical drive B II.6 File information Commands: EXist, CHeck, NUmberfiles Parameters: for EXist - filename (no wildcards) for CHeck - pathname with or without trailing \ for NUmberfiles - filespec(s) with wildcards Internal Command: FDir Chapter II:SYSTEM INFORMATION Page 24 Documentation for BATUTIL, Version 1.0 BATUTIL has a number of commands that will return information about files on disk. Each of these commands must have a parameter describing the filespec of the file or path you want information about. They will only take a single parameter except for NUmberfiles. EXist is a more powerful version of DOS' "if exist" command. If a filename is given with no path or drive, the responses are 0 = the file exists in the default directory or the filename is the name of a device loaded in your config.sys (see below) 1 = the file does not exist in the current directory but it does exist somewhere on the PATH. The directory can be returned in an environmental variable; see the discussion of FDir below. 2 = the file does not exist in the path codes above 200 indicate DOS, syntax or environmental errors; see Chapter VIII. If a path or drive is given as in "batutil {EX C:foobar.txt}" or "batutil {EX \bin\foobar.txt}", then the responses are 0 = the file exists in the specified drive and/or directory 2 = the file does not exist in the specified drive and/or directory 9 = the path given is not a valid path codes above 200 indicate DOS, syntax or environmental errors; see Chapter VIII. EX does not interpret wildcards, that is if you look for a file named foo*.* as in "batutil {ex foo*.*}", then BATUTIL will look precisely for a file with that exact name and not find it. If a filename with no explicit path is entered as the parameter for EX and the file is not found in the current directory, then the DOS path is searched for it and optionally, the directory where it is found is placed in the environment. By default, the name FDIR is used so that if foobar.txt existed in directory C:\bin which was in your path, then after running batutil {EX foobar.txt} RC would have the value 1 and FDIR the value C:\bin, that is a DOS SET (or batutil {envrep}) will include FDIR=C:\BIN RC=1 The FDir command allows you to change where this directory name is stored. If no new name is given then the directory name is not stored so batutil {FD}{EX foobar.txt} Chapter II:SYSTEM INFORMATION Page 25 Documentation for BATUTIL, Version 1.0 would not store the name C:\BIN anywhere while batutil {FD foo}{EX foobar.txt} would store the string FOO=C:\BIN You might want to use this directory name in a way that requires a backslash; for example you might want to copy the file. Just adding the backslash by hand won't work if the directory is the root (which already ends in a backslash). If you use FDIR to define a variable which begins with a \, then a trailing backslash is added. Thus batutil {FD \foo}{EX foobar.txt} would store the string \FOO=C:\BIN\ and you could then use the command copy %\foo%foobar.txt A: FDIR is also used by the $f file picklist discussed in Section V.5. If your machine has a config.sys file, it likely loads various device drivers with the "device=" command. In addition, DOS sets up various devices like NUL, CON, PRN and LPT2. Some of the devices have explicit names. For example, any EMS driver will call its device EMMXXXX0, the memory manager 386 to the Max calls its device 386MAX$$ and the Microsoft Himem program loads a device called XMSXXXX0. If you use DOS' "if exist" it will recognize a device in any directory, so, for example if exist \somepath\nul echo hi will echo if and only if the directory \somepath\ exists. In the same way, BATUTIL {EX ...} will return a code of 0 if ... is a device. But to distinguish devices from files, it does an extra check to see if the specified file is a device. If it is, it sets FDIR (or whatever you've replaced fdir by with the FDIR command) to the value IS_A_DEVICE. CHeck will check whether a path exists and reply 0 if it does and 9 if it does not. You can include a tailing backslash or not as you wish. If you want a batch file to act differently depending on whether A: has a diskette in it or not, use BATUTIL Q {CH A:\} which will return errorlevel 0 if there is a diskette and errorlevel 230 (drive not ready) if not. If you used if exist A:\nul instead and no diskette were there, the batch file would halt with Chapter II:SYSTEM INFORMATION Page 26 Documentation for BATUTIL, Version 1.0 an Abort, Retry, Fail message. NUmberfiles takes a filespec with wildcards and tells you how many files match in the default directory match that filespec, for example BATUTIL {NU C:\bin\*.*} would tell you the total number of files in that directory. The answer will be between 0 and 199; the answer 199 indicates that there are 199 or more matching files. NU will take more than one file spec so that BATUTIL {NU C:\bin\*.com C:\bin\*.exe} would tell you the total number of executables in C:\bin. II.7 The RUn Command Command: RUn Parameter: program name BATUTIL has a command that will let you run another program and get the errorlevel that program exits with recorded in the environment as the value of RC. The syntax is BATUTIL {RU programname} programname can include a path if you wish. Like DOS, BATUTIL will ignore any extension that you give and first try a COM file and then an EXE file. Afterward the program has run, RC will be set to the errorlevel of programname. A typical application of this would be to get the errorlevel reported on screen by BATUTIL {RU programname}{EC $x(RC)} For this purpose, a stand alone program called WHATEL is provided. Just type in WHATEL programname and the program will report the errorlevel and the time it took programname to run. This time is rounded up in units of 55 milliseconds (the smallest unit of time one can measure without reprogammming the PC's internal clock) so that time differences of .06 seconds are insignificant. BATUTIL {RU ...} takes about 175K to run which is that much less for "programname". WHATEL takes less than 17K. There is a slight difference between how BATUTIL {RU ...} and WHATEL work. The former searches for a COM or EXE executable binary file in the current directory or on the path. It will yield Chapter II:SYSTEM INFORMATION Page 27 Documentation for BATUTIL, Version 1.0 an error message if you use a batch file name, DOS internal command or bad command name. The philosophy is that since batch files don't yield errorlevels, it is an error to try RUn with one. But since WHATEL is also a timing utility, it might be used for batch files, internal commands or even to time a bad command. So, if WHATEL cannot locate a suitable COM or EXE file, it passes your command to DOS to see if DOS can make sense if it. In that case instead of reporting: "Errorlevel returned by ... was ..." WHATEL reports "...run from a shell of DOS". II.8 TOdayfile and MAkefile Commands: TOdayfile, MAkefile Parameters: For TOdayfile: either a filename or an hour and a filename; for MAkefile: two filenames The TOdayfile command is intended to tell you whether a given file has today's date. As we'll explain in Chapter VI, it is intended for use in a batch file, usually an autoexec.bat file, to make sure that some operation is only done once a day. In the simplest form, the syntax is BATUTIL {TO filename} and the responses are 0 = the file has today's date 1 = the file exists and doesn't have today's date 2 = file not found 9 = invalid path above 200; DOS and syntax errors as in Chapter VIII; allowed values are 230, 231 (for DOS error) or 204 - 207 (for syntax errors). If you wish, TO will take an optional numeric parameter as its first parameter, i.e. with syntax BATUTIL {TO hour filename} where hour is between 0 and 23. This parameter is used if you'd like the day to begin at a time other than midnight (0 is therefore a redundant choice put in only for completeness). For example if you type in BATUTIL {TO 5 test.dat} then BATUTIL will look at days beginning at 5 in the morning and see whether test.dat and the current date/time are on the same "day". Thus if test.dat was made yesterday at 8:15 AM the above command would return an errorlevel of 0 if the current time is before 5 AM and an errorlevel of 1 if after 5 AM. This will Chapter II:SYSTEM INFORMATION Page 28 Documentation for BATUTIL, Version 1.0 prevent an action from happening if you stay up late at night and don't want to think of that as a new day. MAkefile requires two file names which we'll call file1 and file2. The errorlevel returned is as follows: 0 = file2 not found 1 = file2 is strictly older 2 = file1 not found 3 = file1 older or the same age as file2 9 = path not found above 200; DOS and syntax errors as in Chapter VIII; allowed values are 230, 231 (for DOS disk errors) and 204,205 (for syntax error) This choice is made because if file2 doesn't exist or is older, one will want to take an action like compile something or backup something else. II.9 The ERrorlevel command You can set the errorlevel to a prescribed number between 0 and 199 with the ERrorlevel command. ER must be followed by a number or by a metastring beginning with $ that translate into a number or by $$ followed by a hex number. If, after metastring translation, the parameter is not a number, BATUTIL exits with the errorlevel set to 206 (and an error message if Verbose mode is on). If the number is less than 0, 0 is returned and if greater than 199, then 199 is returned. For example batutil [ER $H] is the same as batutil [HO] and batutil ....[ER $x(RC)] would set the exit errorlevel to the value of RC set by an earlier command. Chapter II:SYSTEM INFORMATION Page 29 Chapter III: DISPLAY TOOLS III.1 Overview One of the most important aspects of a batch files on which DOS is woefully inadequate is communicating with the batch file user. In this chapter, we'll discuss enhancements to better display messages giving you control on colors, on where the messages are displayed and allowing you easily place system information like the current drive in your messages. BATUTIL also provides 10 sounds and 10 tunes with you can use to communicate with the batch file user. In the next chapter we'll discuss the tools that BATUTIL gives you to get input from the user. One of those methods pops up a menu and another pops up a file list and so they also involve display. In Section III.2, we'll discuss some automatic translation that gets done when you ask BATUTIL to display a string. This translation mechanism is also relevant to the SEt command discussed in Section V.3. By default, BATUTIL displays by writing directly to the screen but as we'll discuss in Section III.7, you can instruct BATUTIL to use standard output if you wish to redirect the ECho command to a file or printer. III.2 Metastring Translation Commands: $Translate, ^Translate Parameters: - to turn off The DOS PROMPT command supports a set of what the DOS manual calls metastrings; something like $p is translated into the current path name. STACKEY extended this set of metastrings. BATUTIL uses all the STACKEY metastrings and adds a few extra ones to accommodate its special structure. This metastring translation takes place for the ECho and PRetty commands discussed in this chapter, the MEnu command of the next chapter and the SEt command of Chapter V. As we'll explain you can tell BATUTIL not to make the translation if you wish. Here are the PROMPT metastrings, all of which are used by BATUTIL: $$ The character "$" $t The time in HH:MM:SS.hh format $d The date in DAY MM-DD-YYYY format e.g. Tue 9-30-1986 Chapter III: DISPLAY TOOLS Page 30 Documentation for BATUTIL, Version 1.0 $p The current path in full, e.g. C:\BIN\FOO $v The current DOS version $n The current default drive $g The character ">" $l The character "<" $b The character "|" $q The character "=" $h The backspace $e The ESCape $_ CR/LF (i.e. <Enter> followed by Ctrl-<Enter> and the special STACKEY metastrings which are used by BATUTIL: $P same as $p in the root dir and as $p\ elsewhere $T time in HHMM format $M month in MM format, e.g. 09 $D day in DD format, e.g. 03 $Y year in YY format, e.g. 86 in 1986 and 01 in 2001 $W day of the week in English, e.g. Sunday $E the date in English, e.g. February 18, 1988 $H hour from 00 to 23 $m minute from 0 to 59 and BATUTIL will make the translation of ^ to indicate a control character, e.g. ^A and ^B will display happy faces. In addition, there are several metastrings special to BATUTIL starting with some simple translations: $S a space $^ The character ^ $( The character { $) The character } $` The character [ $' The character ] The $S is necessary in situations where BATUTIL uses spaces to separate parameters and you want a space in a string. For example BATUTIL {ME a b c} would pop up a menu of the form ╒═══╕ │ a │ │ b │ │ c │ ╘═══╛ while Chapter III: DISPLAY TOOLS Page 31 Documentation for BATUTIL, Version 1.0 BATUTIL {ME a$Sb c} would pop up a menu of the form ╒═════╕ │ a b │ │ c │ ╘═════╛ $(, $), $` and $' are needed because {,},[,] are command separators for BATUTIL and their use in the middle of a display string would likely produce something other than what you want. BATUTIL will do filename parsing; if ... is a filename, then $a(...) = path of ... without trailing backslash $A(...) = path of ... with trailing backslash added $B(...) = name of ... $C(...) = extension of .... Note that these commands are case sensitive. For example $A(C:\bin\batfiles\foobar.bat) = C:\bin\batfiles\ $a(C:\bin\batfiles\foobar.bat) = C:\bin\batfiles $B(C:\bin\batfiles\foobar.bat) = foobar $C(C:\bin\batfiles\foobar.bat) = bat Metastring translation is not done on the string in ... with one crucial exception. The $x/$X environmental substitution is made. The most common use of these filename parsers would be to use the $f command to have the user choose a file from a popup list which you could then parse, e.g. BATUTIL {EC Pick file}{SET foo=$f fooext=$C($x(foo))} You can access environmental variables with either $x(var) or $X(var) where "var" is the name of an environment variable. $X will first translate the string using metastring translation while $x will not. Thus if your environment includes FOO=$p the DOS level command BATUTIL {EC $x(foo)} would display the string $p on the screen while BATUTIL {EC $X(foo)} would display the current directory. You can have a $x or $X as part of the variable being translated by $X in which case there is recursion. To avoid a crash if an infinite loop results as it would if foo1=$X(foo2) and foo2=$X(foo1), $X's are only translated 60 times at which point no further translation is done. When preparing batch files for third parties, use caution with $X. If there is a metastring syntax error (like using $j, an improper Chapter III: DISPLAY TOOLS Page 32 Documentation for BATUTIL, Version 1.0 metastring) in foo, then use of $X(foo) will cause BATUTIL to exit with error 209. There are two subtle differences between the $x command and using DOS' %...% command. There is no effective difference between BATUTIL {EC $x(foo)} and BATUTIL {EC %foo%} but if your environment starts out with FOO=initial then BATUTIL {SET foo=final}{EC $x(foo)} would display "final" on the screen while BATUTIL {SET foo=final}{EC %foo%} would display "initial" on the screen. In addition, DOS does the translation of %foo% before passing the command onto BATUTIL which could bring the command line above the maximum 127 characters supported by DOS while BATUTIL only expands $x(foo) after getting the command line and there is not the same limitation. In the SEt command, $Q, $? and $f have special meaning; see the discussion Sections V.4 and V.5. In connection with the {GEtkey WAit} command, $L sets the location of a time countdown if used in an ECho or PRetty command. See the discussion in Section IV.5 If you wish to turn off metastring translation, you can with the commands $T - to turn off $ translation $T to turn $ translation back on ^T - to turn off ^ translation ^T to turn ^ translation back on It is important to bear in mind that BATUTIL has no memory from one running to the next so that BATUTIL {$T -}{EC $p}{$T}{EC $q$p} would display $p=C:\BIN if BIN were your current directory but BATUTIL {$T -} BATUTIL {EC $p}{$T}{EC $q$p} would display C:\BIN=C:\BIN Chapter III: DISPLAY TOOLS Page 33 Documentation for BATUTIL, Version 1.0 III.3 BATUTIL's ECho command Commands: ECho, ATtribute, MNattribute, CLs, EOline Parameters: EC takes the string to echo AT, MN take a hex byte. AT T is also legal; see Section IV.5 EOline takes an optional parameter of + You can echo a string to the screen with the FEcho command discussed in Section III.5 below or with BATUTIL {EC string} The reasons to use BATUTIL's echo rather than DOS' echo are the following - metastring translation takes place with BATUTIL - there is not an automatic CR (which means you'll need to remember to add $_) but you can place several lines of text on one echo line (subject to DOS' 127 character limitation) by using $_ - if you use BATUTIL's ECho command between two cursor location commands, BATUTIL will only be loaded once while if you use DOS' echo it will not - as we'll explain, BATUTIL gives you color control BATUTIL stores away two color combinations that it uses: one for color screens which defaults to yellow on blue and one for monochrome screens which defaults to dull foreground (attribute 07 hex). This attribute is used in several places: it is used by the ECho command it is used to set the colors by the CLs command it is used for shadows in the MEnu command (Section IV.2) it is used to determine the attributes in the input box for the $? query command (Section V.4) You can change the attributes used with the ATtribute and MNattribute commands. Each takes a hex byte either in the form 1A or $1A. The color values are those which are popped up in CTRLALT PLUS' ^@R or CTRLALT's ^@T table. The first digit is the background and the second foreground with the following rules Background Foreground 0 Black Black 1 Blue Blue 2 Green Green 3 Cyan Cyan 4 Red Red 5 Magenta Magenta 6 Brown Brown 7 Grey Grey Chapter III: DISPLAY TOOLS Page 34 Documentation for BATUTIL, Version 1.0 8 Black+Blinking Dark Grey 9 Blue+Blinking Light Blue A Green+Blinking Light Green B Cyan+Blinking Light Cyan C Red+Blinking Light Red D Magenta+Blinking Light Magenta E Brown+Blinking Yellow F Grey+Blinking White where "blinking" refers to the foreground and should be used sparingly. For example, AT=$AF would set the attribute to blinking white on green (ugh!). For the hex digits a-f, you may use upper or lower case. Two attributes are special: $55 and $66. $55 tells BATUTIL to use the attributes at the cursor position at the time the string writing begins as the attributes for the entire string. $66 tells BATUTIL to write without changing any attributes. These two are the same if the block to be written to has uniform attributes but different if they the attributes change as the block is traversed. CLs clears the screen in the current ATtribute or MNattribute and sets the cursor to the upper left. Here is an example using the ROw and COlumn commands discussed below: BATUTIL {CL}{AT=4F}{RO=15}{CO=5}{EC Hi! there} which would clear the screen in the default attributes of yellow on blue and then display "Hi! there" in white on red starting at row 15, column 5. EOline, short for "End of Line" will erase the current line from the cursor position until the end of the line in the current attributes. If you use a parameter of + as in BATUTIL {EO +} then the entire line is erased. BATUTIL strips leading and tailing blanks from the string following EC so that {EC hi } is the same as {EC hi}. If you actually want the leading or tailing blanks, you'll need to use $S as in {EC $S hi $S}. Note that the blanks between the first/final $S and "hi" are not stripped. III.4 The PRetty command Command: PRetty Parameters: string to display with @<Hex> for attribute change Chapter III: DISPLAY TOOLS Page 35 Documentation for BATUTIL, Version 1.0 With the ECho command, you can display strings in multiple colors but it is rather tedious to have to write: BATUTIL {AT 4F}{EC H}{AT 4E}{EC ello} to display Hello with the H in white on read and the rest in yellow on red. The PRetty command lets you use the @ sign to signal a color change. If the @ sign is followed by two hex digits (or a $ and two hex digits), then the string following it will be displayed in that color until the next @ sign. So the above command line could be replace by BATUTIL {PR @4FH@4Eello} Until you specify a new attribute with an @ command, PR will use the attributes set with the AT and MN commands (or their defaults 1E and 07). Irrespective of what you do with @ commands, when you complete a PR command (i.e. the closing } occurs), the value of AT and MN that were in place before will be in effect, for example BATUTIL {AT 4E}{PR @20 hi$S}{EC there} will display "hi " in black on green (attribute 20) but then "there" in yellow on red (attribute 4E). As for the AT and MN commands, the HEX digits following @ can have a-f upper or lower case and an optional $ after the @ is allowed. III.5 Bigecho Commands: BEcho, BPretty, BIgchar Parameters: for BEcho: String to echo with special meanings for leading or trailing ~ or a trailing ^ for BPretty: String with PRetty @ commands; special meaning to trailing ^ for BIgchar a foreground character and optional second background character. Each can be a character or a number from 1 to 255 (255 has special meaning). BIGECHO is a free program from Ctrlalt Associates available on many bulletin boards. As its name implies, it echoes large characters to the screen. One font is 8 characters high and 8 wide and uses the built in CGA character set found in ROM. There are additional smaller sets based on publicly available EGA fonts. BATUTIL includes a BIgecho command which uses the builtin 8x8 font. That is, messages displayed with it are eight lines (except for letters like j and g, the eighth line is blank) and are eight characters wide which means that up to 10 characters can be Chapter III: DISPLAY TOOLS Page 36 Documentation for BATUTIL, Version 1.0 displayed on a line. The simplest command is BEcho which followed by a string displays that string in the large characters. The current attribute set with AT (or MN) is used. Any characters that don't fit on the line will be truncated (this may be fewer than 10 characters if you don't start with the cursor in column 1). At the end of the line a "big carriage return" is issued, i.e. the cursor is moved to the first column of the row below the big characters. As we'll explain below, a leading ~ or trailing ^ or ~ will be suppressed and special actions will take place. Each character is stored as a set of dot patterns with the on dots normally displayed as the "foreground" color and the off dots as the "background color". Thus the letter R is stored as the dot pattern (1 = on, 0 = off) 11111100 $$$$$$ 01100110 $$ $$ 01100110 $$ $$ 01111100 corresponding to $$$$$ 01101100 $$ $$ 01100110 $$ $$ 11100110 $$$ $$ By default, BATUTIL, when BEchoing will replace each off dot by a space (character 32 in the ASCII scheme) and each on dot by the solid block (ASCII 219) so that R becomes ██████ ██ ██ ██ ██ █████ ██ ██ ██ ██ ███ ██ However, you can replace these two characters by any pair of characters using the BIgchar command. This command takes one or two parameters. The first parameter specifies the character used for "on" dots while the second, which is optional, the character for off dots. If the second parameter is absent, the off character is left unchanged from what it was (or from the default space if you haven't changed it). The parameters can be either a single ASCII character or a number from 01 to 255. To distinguish a number less than 10 from the corresponding ASCII character, place a 0 in front of the number. Thus {BI 1} will use "1" for the on character while {BI 01} will use a happy face (ASCII 1). Hex Chapter III: DISPLAY TOOLS Page 37 Documentation for BATUTIL, Version 1.0 digits if proceeded with a $ are also allowed (e.g. $20 in place of 32). For example, to show the pattern ╬╬ ╬ ╬╬ ╬ ╬ ╬╬ ╬ ╬ ╬╬ ╬ ╬ ╬╬ ╬ ╬╬ ╬ ╬╬ ╬ ╬╬╬╬╬╬╬╬ you'd want to use {BI 32 ╬} or {BI 32 206} or {BI $20 $CE}. Use of the on character 255 is special. It is interpreted to use the character itself for the on character (and space for the off character) so BATUTIL {BI 255}{BE Hi there} would yield HH HH ii t hhh HH HH tt hh HH HH iii ttttt hh hh eeee rr rrr eeee HHHHHH ii tt hhh hh ee ee rrr rr ee ee HH HH ii tt hh hh eeeeee rr rr eeeeee HH HH ii tt t hh hh ee rr ee HH HH iiii tt hhh hh eeee rrrr eeee Metastring translation takes place for the BEchoed string. You'll use this mainly for $S spaces at the start (although it may be more useful to use the CO command to adjust the column of the cursor). If you do not want the big CR which is issued by default, end the string with a ^. The cursor is then left on the initial row in the column where the next large character would have appeared. Thus BATUTIL {BI 255}{BE B^}{BI 219}{BE at} would yield BBBBBB █ BB BB ██ BB BB ████ █████ BBBBB ██ ██ BB BB █████ ██ BB BB ██ ██ ██ █ BBBBBB ███ ██ ██ If you have an off character other than the default space, BATUTIL assumes that you want the entire line to covered with that Chapter III: DISPLAY TOOLS Page 38 Documentation for BATUTIL, Version 1.0 character except where the foreground appears (try BATUTIL {BI 32 206}{CO 9}{BE Hi there} to see what we mean). If you don't want this effect, add ~ both before and after the string as in {BE ~Hi there~}. A ~ at the start of the only will not fill in the space before the string. When a non-space off character is used, a ^ at the end and a ~ at the beginning also suppresses filling in spaces after the string. BPretty is like BEcho with the following changes: - as with Pretty, you can use @ followed by a hex attribute to change colors - Off character fillin as described above for BEcho does not take place so leading and trailing ~ characters have no effect (but are stripped off). You cannot redirect BEcho or BPretty to STDOUT (i.e. {ST +} will be ignored by these commands). III.6 Getting Echo/Pretty Input from a file Commands: FEcho, FPretty Parameters: filename, optional label as second parameter If you have several lines to display, using the ECho or PRetty commands can be a nuisance because of the 127 character limitation on the DOS command line. You'll have to prepare several BATUTIL lines in your batch file and BATUTIL will have to load several times slowing the display. To avoid these problems, there are the FEcho and FPretty commands which take input for ECho and PRetty from a file. Rules for finding the filename (your path is searched) and the use of labels are discussed in Section I.5. Lines are read in from the file and processed as they would be by the ECho or PRetty command with two exceptions: - leading and trailing blanks are not striped off - that is lines will display as they appear. - each new line in the file causes a new line on the display except that there is not a new line command issued for the last line displayed (unless it ends in a $_). In particular, blank lines in the file display as blank lines on the screen. Unless turned off with the $T - command, full metastring translation takes place and @ color changes are done by FPretty. Chapter III: DISPLAY TOOLS Page 39 Documentation for BATUTIL, Version 1.0 III.7 Cursor Position and Hiding the Cursor Commands: ROw, COl, CUrsor Parameter: RO takes a number from 1 to 25; may begin with + or -. A T is also legal; see Section IV.5 CO takes a number from 1 to 80; may begin with + or -. A T is also legal; see Section IV.5 CU takes + or - If you want a screen in a batch file to begin with 10 blank lines under DOS, you've got to have 10 lines with echo <char 255> (where <char 255> is the ASCII 255 character) or something similar. BATUTIL allows you to control cursor position. {ROw n} where n runs from 1 to 25 sends the cursor to row n and similar {COl n} to column n. If just a number is listed after RO or CO, then the coordinates are absolute but if you precede then with a + or -, then the coordinates are relative. For example BATUTIL {RO 5}{CO 5}{EC hi}{RO -3}{CO +3}{EC there} would print "hi" on row 5, col 5 and then "there" on row 2, column 10 (since writing "hi" move the cursor to column 7). BATUTIL will not wrap to the next line with relative coordinates and it will stop at the right or left edge if a relative coordinate shift would take it off the screen. The same is true of the top. However, if a relative row shift would take it below the bottom edge, it will scroll the screen. It is often more elegant if the cursor is hidden when you are displaying a message on the screen. {CUrsor -} will hide the cursor while {CUrsor +} will restore it to normal shape. When BATUTIL finishes running, the cursor is automatically restored so you'll only need {CU +} if you want the cursor to reappear in the middle of a sequence of commands. Places where you'd normally want BATUTIL to show a cursor like $Q in a set command, BATUTIL will show a cursor even if {CU -} is in effect so you'll only use {CU +} rarely. III.8 The STdout command Command: STdout Parameter: + or - Chapter III: DISPLAY TOOLS Page 40 Documentation for BATUTIL, Version 1.0 DOS' echo command is sent to standard output while, by default, BATUTIL will write directly to the screen. If you want EC to go to standard output, use {STdout +}. To turn off this use {STdout -}. You would use {ST +} (the + is not necessary) if you wanted to redirect the output of the EC command (or of the messages from the SA, LO or KI commands) to a file or to NUL. To make a beep in the middle of a BATUTIL sequence, redirect output to STDOUT and echo a ^G as in BATUTIL {ST}{EC ^G}{ST -}{EC You dummy!!!} If you echo to the screen with ST in effect, color commands have no effect. III.9 Sounds Command: SOund, NSound Parameter: SOund takes a single required number from 1 to 20 and an optional second number NSound takes a - or an optional + BATUTIL comes with ten brief sounds and ten tunes - the ten tunes were made with PIANOMAN. Each has a number; the ten sounds: 1:ping 2:wolf whistle 3:random electronic sound (needs a repeat to sound much) 4:short buzz 5:tweet 6:alarm clock ring 7:buzzer 8:electronic sound 1 9:electronic sound 2 10:train with Doppler effect while the tunes are fragments from: 11:Dance of the Clowns 12:Habana from Carmen 13:Sailor's Hornpipe 14:Mapleleaf Rag 15:Land of Hope and Glory (Pomp and Circumstance) 16:Porky Pig Theme ("That's All Folks") 17:Pop Goes the Weasel Chapter III: DISPLAY TOOLS Page 41 Documentation for BATUTIL, Version 1.0 18:William Tell Overture (Lone Ranger's Theme), part I 19:William Tell Overture (Lone Ranger's Theme), part II 20:Yellow Rose of Texas You invoke a sound with BATUTIL by using the sound command which takes one or two parameters. The first parameter must be an integer from 1 to 20 and indicates the sound from the above list. The second parameter indicates the number of times to repeat the sound; if the second parameter is absent the sound is issued once. For most sounds you won't want any repeats but for sound 3, you'll want a repeat count of 15 or more and sound 4 will do with a few repeats. The repeat count must lie between 1 and 60. Thus batutil {so 3 30} will repeat sound 3 thirty times. The William Tell Overture is broken into two parts, to allow you to take an action in the middle as in batutil {ec CTRLALT Associates}{so 18}{ec $Spresents}{so 19} If you don't want the SOund command issued, you can use the NSound command. This is intended primarily for use in the options set in the environment as in set @BU={NS} which would be useful if you normally had sounds in your batch files but were working late at night and didn't want to disturb others. The {NS -} command would turn sound back on even if there is a previous {NS}. ******************************************************************* IMPORTANT NOTE CTRLALT Associates wishes to warn you that the SO command may change in future versions - the precise sounds for sounds 1-10 may change. ******************************************************************* Chapter III: DISPLAY TOOLS Page 42 Chapter IV:USER INPUT IV.1 Menu Basics Command: MEnu, NMouse Parameter: for MEnu, list of choices DOS provides very little in the way of user input to batch files - essentially the only way to modify the way a batch file runs from one time to the next is to change the parameters on the command line. BATUTIL provides a number of alternates which we'll discuss in this chapter: you can pop up a menu from which the user chooses and have the choice returned in the errorlevel, you can have the user hit one of a specified number of keys, you can react to a specified state of the Capslock or Numlock or use a number of other devices. You can also get an input string or filename from the user and store it in the environment but that command is most naturally described in detail in the next chapter. (see Sections V.4 and V.5) You can have BATUTIL pop up a menu of choices: you can have up to 16 choices - if you try more, BATUTIL will exit with an errorlevel over 200 set (and an error message if verbose mode is on). Each choice can be up to 60 characters long (after metastring translation). If the string is longer, then it is truncated at 60 characters. The syntax is BATUTIL {MEnu choice1 choice2 choice3 ...} Each pair of choices must be separated by a space. If you want a choice to appear with a space in the middle, use $S and rely on metastring translation to turn those into spaces. For example BATUTIL {ME choice$S1 choice$S2 choice$S3} would pop up a menu of the form ╒══════════╕ │ choice 1 │ │ choice 2 │ │ choice 3 │ ╘══════════╛ A highlight appear initially on the top choice and the following keys (plus others - see below) work: <Down>,<Tab>,<Spacebar>,<+> move the cursor down <Up>,<Shift-Tab>,<Backspace>,<-> move it up <Home>,<PgUp> go to the first choice <End>,<PgDn> go to the last choice <Esc> exits and sets the errorlevel to 0 <Enter> makes the highlighted choice If the user picks the nth choice on the menu, the errorlevel is set Chapter IV:USER INPUT Page 43 Documentation for BATUTIL, Version 1.0 to n. In default mode, BATUTIL will look for a Microsoft compatible mouse and, if found, the mouse will work on the menus: moving the mouse up or down will move the highlighting and either mouse button will choose the highlighted item. If you don't want the mouse active in the menus, use the {NMouse} command. The bar wraps around from top to bottom or vice versa. The screen is saved upon menu popup and restored on pop down. In this version of BATUTIL, you cannot modify the menu colors or the border type. BATUTIL automatically centers the menu on the screen both from left to right and top to bottom. You can cannot adjust the position of the menu in this version. BATUTIL gives special treatment to the first capital letter or number in each choice. That symbol will appear in a special highlight and hitting that key will make that choice. For example BATUTIL {Copy Erase reName format eXit} will display a menu with five choices. Hitting upper or lower case C, E, N, X will choose the first, second, third or fifth choice. There is no shortcut choice for "format" since no letter is capitalized. Only the first capitalized letter in each choice counts so that if "Copy" were replaced by "COPY" only the first C would have a unique color and would be the quick key to make that choice. If two different choices have the same capitalized letter, e.g. if "eXit" above were replaced by "Exit", only the first E would have the special color and only the first choice would be made if an <E> were hit. Future versions of BATUTIL may adopt the Windows standard use of & in menu choices so you should avoid the use of the & symbol in your menu choices (although && for & will be supported). Extra options for how menus look and/or choices are made can be found in the third section. The sample batch file MENUDEMO.BAT will display sample menus and studying it should help clarify issues of syntax. IV.2 Getting a menu from a file Command: FMenu Parameters: filename, optional label as a second parameter Chapter IV:USER INPUT Page 44 Documentation for BATUTIL, Version 1.0 If your menu has many choices or long descriptions, you will have trouble fitting it on a single DOS command line. While suitable use of environmental variables and the $x command can get around that, a special command is provided for reading in a menu from a file. The syntax of the FMenu command is the same as for FEcho and FPretty and is discussed in sections I.5 and III.5. Leading and trailing spaces will be stripped and blank lines will be ignored. The separate lines will then be viewed as separate lines in the constructed menus. Embedded blanks will be treated as blanks, that is, unlike the MEnu command where blanks must be indicated with the $S command, blanks in FMenu do not require $S (although metastring translation is done so that $S will be interpreted as spaces). If you are reading in a menu from a file, you have the option of associating each menu item with a line of "help text". After listing the menu items, place a line with an @ as the first nonblank character. The rest of that line is ignored, but subsequent lines until the next : line will be regarded as help text. They are associated in order, in a one-one way with menu choices. If there are fewer help lines then menu lines, the final few menu items won't have help text. If there are more help lines than menu items the last few help lines will be ignored. Help text is displayed in the attributes set with the ATtr or MAttr commands and replaced with blanks in that attribute when the menu finishes. IV.3 Menu Options Commands: MHeader, POp, SHadow, FKey Parameters: MHeader takes a text string POp takes a + or S to turn on sound effects. There are a number of options you can choose which effect the appearance of menus popped up with the MEnu command and one of them effects which keys work. If you wish you may add two extra lines to the top of the menu with the MHeader command. The first line is a text string that you insert as a parameter to MH - spaces are allowed. The second is a graphic line. The MH command must proceed the ME command. So BATUTIL {MH This is a header}{ME a b c d e} would display a menu in the form ╒══════════════════╕ │ This is a header │ Chapter IV:USER INPUT Page 45 Documentation for BATUTIL, Version 1.0 ├──────────────────┤ │ a │ │ b │ │ c │ │ d │ │ e │ ╘══════════════════╛ The menu choices are always left justified while the header is centered. You can use $S's to adjust this justification if you wish. A blank MH, i.e. {MH} will get ignored but {MH $S} would display a blank header. Like menu choices, headers are truncated at 60 characters if they are longer than that after metastring translation. You can have the menu popup with a shadow effect by using the SHadow command. The attributes of the shadow are the ones current set with the AT or MN commands. A typical menu popup command might be set with BATUTIL {AT 30}{CL}{SH}{AT 0}{ME choices.....} The first AT sets the attributes to black on cyan to produce a cyan screen when you CLear the screen. The second AT then sets the attributes used by the shadow (black). You can have the menu visually explode when popping up and implode upon exiting. You turn this effect on with the POp command. POp will take an optional parameter of + or S to also turn on sound effects. Try out MENUDEMO.BAT to see what the effect is. The final option is to turn on function keys with the FKey command so that BATUTIL {FK}{ME choice1 choice2 choice3} will display a menu ╒═════════════╕ │F1 - choice1 │ │F2 - choice2 │ │F3 - choice3 │ ╘═════════════╛ with Fn labels indicated. Now in addition to the other choices, the function keys will make choices as will the number keys. FK will have an effect if your menu has nine or fewer choices. It is ignored if the menu has more choices than that. Chapter IV:USER INPUT Page 46 Documentation for BATUTIL, Version 1.0 In the unlikely event that you try to put more than one ME command on a line, the options are all reset by the first menu displayed so that, for example BATUTIL {MH hi!}{FK}{ME a b c d}{ME 1 2 3 4} would display a header and function keys on the first menu but not the second. IV.4 GEtkey Basics Command: GEtkey Parameters: list of "keys" separated by spaces, commas or semicolons. For many purposes where you want single key input, the MEnu command will be best but that is certainly overkill when you really want to ask something like Backup text files (Y/N)? where a simple <y> or <n> will suffice. The GEtkey command is intended for these situations. In its simplest form, the GEtkey command is followed by a set of "keys" separated by one of space, comma or semicolon (mixed choices are allowed) in the form: BATUTIL [GEtkey key1 key2 ....] where the syntax for allowed keys will be discussed below. BATUTIL will then wait patiently for the user to hit one of the keys in the list and then exit with the errorlevel set to n if choice n was made. For example BATUTIL [GEtkey y n] would wait patiently for one of y,Y,n,N and set the errorlevel to 1 if y or Y was picked and 2 if n or N were picked. By default, the keys are not case sensitive so that as above y or Y will work. Also, by default, BATUTIL will flush the keyboard buffer before getting a keystroke. BATUTIL will also echo the choice made to give the user feedback and by default will display nothing in response to a key not corresponding to any choice. However, these defaults, including whether there is any visible echo, can be changed as we'll explain in the next section. The maximum number of keys that can be listed is 40. BATUTIL doesn't mind if a key is repeated in the list of keys but it will report the first match so that BATUTIL [GE Y Y y n n y y n] would return errorlevel 1 with a y or Y and errorlevel 4 with an n or N. Chapter IV:USER INPUT Page 47 Documentation for BATUTIL, Version 1.0 Unlike STACKEY, BATUTIL does not distinguish between the Grey plus and the top row plus nor between the top row numbers and the number pad numbers. Here are the possible choices for keyn in the basic syntax (the two letter codes are essentially those recognized by STACKEY with exceptions like G+ as described above, and the fact that this version does not support keys special to the enhanced keyboard.) - any single ASCII character with some exceptions given below - # followed by any number from 0 to 255 indicating precisely that ASCII code (there must be no spaces between the # and the number) - F1,..,F0; S1,..,S0; A1,..,A0; C1,..,C0 for the 40 function keys as in STACKEY - ^ followed by any upper or lower case letter for the control-character, e.g. ^B for <Ctrl-B> - ^ followed by one of [ \ ] ^ _ for those special ASCII codes, e.g. ^[ for <Esc> - ^1, ^3, ^4, ^6, ^7, ^9 for <Ctrl-End>...<Ctrl-PgUp> as in STACKEY - @ followed by an alphabetic letter, number, -, _, + or = indicated the Alt-combination as in STACKEY, e.g. @A for <Alt-A> - The following two letter codes which have the same meaning as in STACKEY: FF, ST, SP, SQ, CB, CR, LA, RA, UA, DA, TA, ES, TB, BT, BS, LF, DQ, IN, DE, HM, EN, PU, PD; for example ES for <esc>. The following ASCII codes cannot be used as a single code because they have special meaning to DOS or to BATUTIL: ASCII code (symbol in paren) │ Use instead ─────────────────────────────────────┼───────────────────── #13 (carriage return) │ #13, CR, ^M #10 (line feed) │ #10, LF, ^J > │ #62 < │ #60 | │ #124 % │ #37 #26 (control Z) │ #26, ^Z { │ #123 } │ #125 Chapter IV:USER INPUT Page 48 Documentation for BATUTIL, Version 1.0 [ │ #81 ] │ #83 , │ #44 <space> │ #32, SP ; │ #59 IV.5 GEtkey Options Commands: NFlush, CSent, VIsual Parameters: For VI - A,1,N,D,DA,D1,DN Extra GEtkey parameters: in first place WAitnn for wait in first place WAitEnn for wait with Echo in last place BEep or ELse GEtkey has various extra options to make it more flexible. While it is normally case insensitive, by preceding it with CSent, it will become case sensitive. For example BATUTIL {CS}{GE Y N} would only accept Y and N and not y or n. Similarly, NFlush will avoid the default behavior which is to flush the keyboard before getting a keystroke. You can adjust the visible feedback that GEtkey gives with the VIsual command. This command takes a parameter which tells it what to do. The choices are the following: The default which echoes the choice the user makes as written in the GEtkey command line, e.g. if you use BATUTIL {GE Y #78} (N is ASCII 78) and the user picks N, then "#78" is echoed 1 which will only echo 1 character choices, e.g. with the above example, Y would get echoed but not #78 N which suppresses the visual echo (N for No) A which provides an echo for all user responses: if the choice is not one on the list a character plus a ? appears. For alphanumeric characters, the character itself is used. For all other keys an upside down question mark appears as the first character. The incorrect choice indicator is erased each time a new choice is made. By default, BATUTIL inserts a space before echoing a response so that a Y response to BATUTIL {ec Are you sure(Y/N)?}{GE Y N} Chapter IV:USER INPUT Page 49 Documentation for BATUTIL, Version 1.0 would appear on the screen as: Are you sure(Y/N)? Y with a space after the question mark. If you Don't want this space use a D in the visual command. You can combine the D parameter with another one so long as you place the D first and place no space after it. Thus BATUTIL {vi da}{ge Y N} would provide an echo to all choices with no leading space. In addition, the GEtkey command itself has extra options for parameters other than a list of keys. The last "key" in the list can be one of the key words BEep or ELse (as usual, two letter truncations are allowed). If the keyword BEep occurs, then the user is beeped for every wrong key picked. PLEASE use this sparingly. We hate programs that beep too much and offer it with some misgivings. Be careful since BATUTIL {GE BE} will do a pretty good imitation of a machine that has crashed (^@<F9> will get you out if CTRLALT PLUS is installed). If the keyword ELse occurs as the last "key", then rather than wait patiently for a key on the list to be hit, BATUTIL will exit with any key hit. If the key is not on the list then the errorlevel is set to the position of the word "else"; for example BATUTIL {GE y n else} would return errorlevel 1 if y or Y is hit, 2 if n or N is hit and 3 for any other key. If ELse is used a VIsual level of A is ignored. The final option concerns the first "key" on the list which can be WAit followed without any spaces by a number, N, from 1 up to over 8,000 (you will not get an error over 8000 but the response will not be what you expect) or followed by the letter E and a number. BATUTIL will then not wait patiently for a key to be struck but after approximately N seconds, it will exit with an errorlevel of 0 if no other choice is made. Thus two lines in a batch file like BATUTIL {GE WA3 y n} if errorlevel 2 goto No would have the effect of choosing a default choice of Y if no key is struck for 3 seconds. The letter E between the number and WAit tells BATUTIL to echo the first choice on the list if the exit is due to a timeout. This is for use in examples like the above where the timeout choice will pick a default. To get the visual feedback for timeout in the above you'd use {GE WAE3 y n}. Chapter IV:USER INPUT Page 50 Documentation for BATUTIL, Version 1.0 There is a system dependent end effect involving the time to load BATUTIL so that WA1 is likely to be anywhere between 1/2 and 2 seconds and WA10 will be between 8 and 12 seconds. In addition, if you start with the GEtkey list with a WAit and end with a BEep and the user holds down the wrong key, then the time before (merciful) exit will be longer than you asked for because beeping takes a considerable amount of time and is not included in the count down time. There may be times that you'll want to visually count down the remaining time. BATUTIL stores two internal parameters called the timerow and timecolumn, initially set to zero. If both numbers have no zero values than a countdown will take place with numbers in the row numbered timerow and beginning in column number timecolumn. There are two ways to change these two parameters. The ROw and COl commands can take the form {RO Ty}{CO Tx} to change these parameters to the numbers y and x. y must lie in the range 1 to the screen height and x in the range 1 to the screen width. Secondly, if you use $L (L for Location) in an ECho or PRetty command, nothing is displayed for the $L but timerow and timecolumn are set to the current cursor position so BATUTIL {EC Time left: $L seconds}{GE WA60} will work the way that you'd expect. Notice that there are three spaces after the $L - two for the numbers 59,.... which will appear and one for a space before the word. There are two additional parameters that you can use with GEtkey WAit and this display. They are set with {AT Tmn} where m defaults to 3 and n to 4. m can be from 0 to 3 (the 0 need not be explicit) and adjusts how much is the time is offset. To take into account the time to load BATUTIL, GEtkey WAits actually subtracts 3/4 of a second off from the time counted so if you ask to count from 60, the time will start at 59. The wait is m/4 seconds if you set m. In addition, you can change the number counted with n. Time is counted down in units of n times 1/4 second with n between 1 and 8. So n=2 is half second and n=8 is 2 second pauses. The countdown is in this unit BUT the number set after {GEtkey WAit} is always interpreted as seconds. Chapter IV:USER INPUT Page 51 Documentation for BATUTIL, Version 1.0 IV.6 AScii, SCanread Commands: AScii, SCanread Every keystroke returns a "scan code" and an ASCII code - these are the int 16 codes as discussed in section VI.1 of the STACKEY documentation. The commands {SC} and {AS} wait for the next key to be pressed and return respectively the scan code or ASCII part. They are sensitive to the prior use of NFlush. That is, by default, the keyboard buffer is flushed before reading but a prior use of {NF} can suppress the buffer flushing. SCan codes are always smaller than 128 but ASCII codes could be above 200. This command is one of only two commands that can return an errorlevel above 200 without indicating an error (the other one is the RUn command). IV.7 Username/Password checking Command: USername Parameters: sequence of names; first one can be a number of tries; second can be * You may have a batch file which you want to branch depending on what "username" the user enters. This is what the USername command is for. The simplest syntax is BATUTIL {US name1 name2 name3 ....} with names separated by spaces. The names cannot have more than one word since metastring translation does NOT take place. BATUTIL will display an edit box preceded by ===> which allows entry of a name up to 20 characters. The usual edit keys work. After the user presses <Enter>, the string entered is compared with the list of names - if there is a match with the Nth name on the list, an errorlevel of N is returned. Otherwise an error level of 0 is returned. As an option, the first parameter can be a number. In that case, that number indicates an additional number of tries which are allowed. If N is 3 or more, and the first entry isn't a match, BATUTIL will beep and display the message: Please try again ===> When there is only one try left, (and in particular if N=2 after the first try), the message Only one more try ===> will appear. Chapter IV:USER INPUT Page 52 Documentation for BATUTIL, Version 1.0 There is another special and VERY DANGEROUS option to be used with care. If the first parameter is a number and the second parameter is a * as in BATUTIL {1 * abc def} then if the number of chances is exhausted, rather than return an error level of 0, BATUTIL will respond Invalid! System halted and go into a tight loop. This is a very crude security measure since even if you place it in your autoexec.bat, booting from a floppy can give an intruder access to your system. But it will be effective against an unsophisticated but nosy intruder. When either the number or number and * options are used, the numbering of choices is counted starting after these optional special parameters. That is, in the last example, "abc" would set an errorlevel of 1 and "def" an errorlevel of 2. By default, USername is not case sensitive and flushes the buffer before asking for input but either of these can be changed by a prior use of {CS} or {NF} as described in section IV.4. IV.8 Parameter Matching Command: PMatch Parameters: list of words The PMatch command is followed by a list of words as in BATUTIL {PM word0 word1 ....} It checks word0 against each of word1, .... If there is a match first with wordN the error level is set to N, otherwise to 0. This is typically used to check for errors in batch file parameters. For example if allowed parameters are "comp" and "bold", you could use echo off batutil {PM %1 comp bold} if errorlevel 1 goto %1 echo %1 is not a valid choice; use COMP or BOLD goto end :comp LINES for comp goto end :bold LINES for bold :end This has several advantages over the more usual sequence of Chapter IV:USER INPUT Page 53 Documentation for BATUTIL, Version 1.0 if %1 == bold goto bold First, it is only one command. Secondly, because labels are not case sensitive, you can use "goto %1" to handle all the different, Bold, BOLD, etc cases. By default, PM is not case sensitive but you can make it so with the {CS} command if you wish. IV.9 Querying the Lock status Command: QLock Parameter: first is C, S, N or I; second (optional) is + or - If you have a long autoexec.bat file which branches in the middle, you may want to set it up with a Y/N question which uses GEtkey with the WA parameter to pick a default choice. But suppose you don't want the default choice. Is there any way to overrule the default without waiting around for the Y/N question to appear? The QLock command is precisely made for such situations. It will read the status of CapsLock or NumLock or .... and return it in the errorlevel. So you could test for the CapsLock as an antidote to the automatic yes. We'll describe an example of this in Section VI.3. QLock takes one mandatory parameter and one optional one. The mandatory one determines which lock will get queried; the choices are C, S, N and I for CapsLock, ScrollLock, NumLock and Insert. Thus BATUTIL [QL C] will test the state of CapsLock and set the errorlevel to 1 if it is on and 0 if it is off. The optional parameter is a + (resp -) which makes sure that the lock state is left on (resp off) when BATUTIL is done. For example BATUTIL [QL C -] would read the lock state but make sure that it was off when the process was done. Chapter IV:USER INPUT Page 54 Chapter V:ENVIRONMENTAL CONTROL V.1 Environmental Impact Statement DOS keeps an area of memory called the active environment where it stores the information that you put in your PROMPT and PATH commands and where it stores the location of the file command.com. In addition, some programs ask you to store information there which you place with the SET command. Because the DOS command line is limited to 127 characters, you are unable with DOS tools to have a prompt string over 120 characters (127 minus the length of "prompt=") nor a path over 122 characters. The syntax of the set command is set foo=string and we will refer to "foo" as the variable name and "string" as the value of foo. Programs, when they load, are given a copy of this active environment and it is this copy that they are supposed to consult or modify. The location of the active environment is undocumented and programs are not "supposed" to access it. Batch files can access the environment - if the string %foo% appears anywhere in a batch file, DOS looks for a variable "foo" in the active environment and if it finds it, then %foo% is replaced by this string. If there is not a variable named foo, then %foo% is replaced by the empty string. This %foo%, which only works in batch files, was undocumented until DOS 3.3 but has worked in all versions of DOS. BATUTIL gives you considerable control over the active environment including the following: - you can query the user and have the answered stored in the environment - You can have environmental strings up to 255 characters rather than the DOS 127 character limit and, in particular, your PATH can be up to 250 characters and your PROMPT up to 248 - you can add or delete directories from your path. - you can get a more informative report of what is in your environment than what DOS supplies with the SET command - you can call up an editor to edit by hand the path or the environment as a whole - you can save the current environment to a file and later reload it. Chapter V:ENVIRONMENTAL CONTROL..Page 55 Documentation for BATUTIL, Version 1.0 !!!WARNING!!! BATUTIL can do these things by directly accessing the DOS active environment which violates the general guidelines for "well behaved" programs and uses undocumented features. We have extensively tested these things with many versions of DOS and we feel that these actions are safe BUT you use these undocumented commands at your own risk. BATUTIL has certain safeguards built in so that it will exit with an error code if it doesn't find an appropriate candidate for the environment so it should be safe but CTRLALT Associates cannot be responsible for any problems caused by your willingness to use our attempt at giving you improved performance by mildly violating the rules. DOS' treatment of the environment has varied from version to version and while we have tested it under DOS 2.0 thru 4.0, there is a chance that we will not find the proper environment under future versions of DOS. In addition we have tested running with a path over 122 characters in length and DOS seems to behave perfectly. However, an application program might get unhappy at finding a path over what it regards as the theoretical maximum. Indeed, Flambeaux Software's TechHelp!! crashes while loading with a path of more than 122 characters and 1986 versions of PKXARC behave erratically with a long path. IMPORTANT NOTES: DOS' SET command only displays the first 128 characters in each environmental string. You may think that BATUTIL has failed to increase your path beyond 128 bytes if you just try set, but the full path will work. Use BATUTIL {EN} to get a full report of all the strings of any length up to 255 bytes. If you use another program to get environmental strings over 255 bytes in length, BATUTIL will refuse to load. If you need strings over 255 bytes, let us know and BATUTIL may support them in a future version. Especially with the extra capability that BATUTIL gives you, you may find the 160 character default environment provided by DOS is too small. You can get around this in two ways: DOS 3.1 has an undocumented option and DOS 3.2/3.3/4.0 a documented option to change the environment with the following command in your CONFIG.SYS: shell=C:\command.com /P /E:xxxx where C:\ can be replaced by whatever path points to command.com and xxxx is the number of bytes you want in the environment under DOS 3.2/3.3/4.0 and it is the number of 16 byte units under DOS 3.1. Thus for a 512 byte environment you'd replace xxxx by 512 under DOS Chapter V:ENVIRONMENTAL CONTROL..Page 56 Documentation for BATUTIL, Version 1.0 3.2/3.3/4.0 and by 32 under DOS 3.1. The second method which you'll need under DOS versions prior to DOS 3.1 is to patch command.com. Information for such patches is available on many bulletin board systems. SHELLs under DOS 3.2 and later can have enlarged environments. Just use command /e:xxxx where xxxx is the number of bytes that you want environment in the shell of DOS to have. Softlogic's Software Carousel sets up a larger environment in its partitions than you specified in a shell command in your config.sys and since BATUTIL reflects reality, it will report this larger environment size. JP Associates' 4DOS program in certain modes INCLUDING the default for version 2.1 will not work with BATUTIL. Instead BATUTIL will exit with an error message. In order for BATUTIL to work with 4DOS you must: - have version 3.00 or later of 4DOS - or a version after 2.10 and you load 4DOS with the /M:xxxx (where xxxx is the desired environment size) switch In addition, be warned that there is a special problem that arises if you try to run 4DOS and BATUTIL together on a system whose underlying DOS version is 3.2. If you load a shell of 4DOS (perhaps as the base command processor) and then load a shell of command.com, BATUTIL will not change the active DOS environment but another memory area. No harm will be done but you will not effect the path or other DOS variables in this rather special circumstance. V.2 Environment Reports Command: ENvrep The command BATUTIL {ENvrep} will display a listing of all environmental strings as DOS' SET command does but it will also list the following: - the length of each environmental string - the total size and amount of free space in the environment - the location of the active environment Chapter V:ENVIRONMENTAL CONTROL..Page 57 Documentation for BATUTIL, Version 1.0 V.3 SEt basics Command: SEt Parameters: var1=string1 var2=string2 (separated by spaces) BATUTIL has a SEt command that lets you place variables into the environment. The syntax is BATUTIL {SE foo1=string1 foo2=string2 ...} You can enter more than one string at a time (although one string is also allowed). Distinct strings are separated by spaces. If any string is missing an = sign, BATUTIL will exit with an errorlevel of 208 (and issues a message if you are in Verbose mode). If you want to place a space into the value of one of the strings, use $S which will get translated into a space. "But", you say, "DOS' SET lets me put strings in the environment, so why do I need BATUTIL." Often DOS is the way to go but BATUTIL's set has the following advantages: - You can place more than one variable into the environment at a time - BATUTIL does metastring translation so that you could use something like BATUTIL {se today=$E} to get today's date in English into the environment or if you want control-Z as part of your prompt string (the right pointing arrow is an interesting alternative to the more usual greater than sign), then you'll have trouble doing that from a batch file but the pair of symbols ^ and Z in a BATUTIL SET will work, e.g. batutil {se prompt=$$p)^Z} - You can use SEt to get variable values of length over 127 characters into the environment (see below). As with DOS' set command, {SE foo=} with no string after "foo=" will remove any variable named "foo" from the environment. Because of the metastring translation, you'll need to exercise some care when using prompt strings. For example, if your prompt were $t$_$p$g which displays the time and then on a second line the path and a '>', and you decided to add the date and used BATUTIL {SE prompt=$d;$X(prompt)} you'd not get what you wanted. The $d would get translated into today's date (which wouldn't be bad although it would waste Chapter V:ENVIRONMENTAL CONTROL..Page 58 Documentation for BATUTIL, Version 1.0 environment space) but the $t and $p would get "evaluated" and would no longer change as you the time changed or you changed directory. Instead you should use BATUTIL {SE prompt=$$d;$x(prompt)} (recall that $X does metastring translation while $x does not). Careful use of $x, $$ and occasional use of the {$T - } will avoid problems but care is needed. DOS is limited to 127 characters on a command line and it does %foo% translations at a point where that limitation is still in effect so that if your path has 120 characters and you use the DOS command set path=%path%;C:\bin; in a batch file, DOS will expand the %path% and crowd all but the ";C" off the line. But BATUTIL only does the translation later and allows environmental strings up to 255 characters so that BATUTIL {se path=$x(path);C:\bin;} would work perfectly - it is with the use of the $x command that you can get environment strings over 127 characters (as well as with the ADdpath and LOadenv) commands. Actually, you wouldn't want to use the above command line - adding to your path is sufficiently important that it is a primitive BATUTIL command and you'd use: BATUTIL {AD C:\bin} V.4 Getting User Strings into the Environment Commands: ?Length, ?Size, LEngth, QUery Parameters: ?L takes a number from 1 to 255 ?S takes a number from 1 to 80 LE takes a string QU takes - Metastrings: $Q, $? As part of the set command, you can query the user for a string to be placed into the environment. The metastrings $Q and $? are used with slightly different display possibilities. Do not confuse $q (the prompt metastring for the character =) and $Q, the Query command. The usual form that you'll use is BATUTIL {se foo=$Q} or BATUTIL {se foo=$?} although there is no reason that $Q or $? couldn't be part of a complex string. Only one $Q or $? will be translated per string so Chapter V:ENVIRONMENTAL CONTROL..Page 59 Documentation for BATUTIL, Version 1.0 that BATUTIL {se foo=$Q$Q$?} would Query the user and append the characters "$Q$?" to the end of the input. But multiple strings each with its on query are in principle possible so that BATUTIL {se foo1=$Q foo2=$Q} would query the user twice. You will need to place an appropriate prompt on the screen to indicate to the user what you expect as in BATUTIL {EC Enter filename to use$_}{SE foo=$Q} or BATUTIL {EC Enter two filenames to use$_}{SE foo1=$Q foo2=$Q} With the $Q command, the BATUTIL adds it own prompt of ===> in distinctive colors (yellow on black on a color monitor) and then displays an edit box in reverse video on a monochrome screen and yellow on green on a color monitor. The edit box is 50 columns wide and the maximum string length that can be entered is 80 characters (with horizontal scrolling as described in Section I.7). These can be adjusted with the ?L and ?S commands as we'll describe. All the editing commands discussed in Section I.7 are active. The $? gives you more control over the display but at the "cost" of more effort on your part. You can customize your own prompt. Rather than use a fixed set of attributes, the AT and MN attributes are used to determine the colors of the edit window. For example, to duplicate BATUTIL {SE foo=$Q} you'd use BATUTIL {AT 0E}{EC ===$g$S}{AT 2E}{MN 70}{SE foo=$?} Of course, you would not do this to duplicated $Q but you can adjust colors and prompts in this way. The {$T -} command does NOT turn off $Q/$? expansion. Rather you can turn this off independently of the state of $T with the QUery command: {QU -} would turn it off and {QU +} will turn it back on. While the default maximum length of input for the $Q and $? commands is 80 characters, you can adjust this with the ?L command. Similarly, the ?S command effects the size of the edit window. Chapter V:ENVIRONMENTAL CONTROL..Page 60 Documentation for BATUTIL, Version 1.0 Thus BATUTIL {?L 30}{?S 5}{set foo=$Q} would give a small 5 character window scrolling to support a 30 character input. The ?S command takes a value between 1 and 80 - any other value will cause BATUTIL to exit with a syntax error. With window sizes that are close to maximum value (or if you have moved the cursor prior to calling {SE foo=$?}), the edit window may wrap to the next line. ?L will take values from 1 to 255. If ?L is smaller than ?S then BATUTIL automatically adjust ?S down to the size of ?L. If you want to know the length of a string input by the user or which you'll need for some other reason [LEngth string] will return that length after metastring translation unless {$T -} is in effect. An error level of 199 is returned if the string is 199 characters or more in length. Normally, LE is used with something requiring metastring translation, especially a $x variable. V.5 Using the file pick list Metastrings: $F,$f BATUTIL lets you popup a file list from which the user can choose a file and you can have the filename chosen saved in the environment. Within the set command, just use a $f or $F on the right side of an equal sign and a file list will popup. The list will have the statement <F1> for Help and hitting <F1> will give information on what is available: Arrows move the bar cursor by one space <PgUp> <PgDn> move up/down by one panel of 21 files <Home> <End> move to the first/last file The list begins with a listing of subdirectories. Hitting enter on the subdirectory will cause that subdirectory to be displayed. Included in the list unless you are already in the root are, two special ones labelled <PARENT_DIR> and <ROOT_DIR> which go to the obvious places; in addition hitting . will go to the parent directory \ will go to the root directory a letter (e.g. a or A) will change drives <space> will go to the initial directory <tab> will go to the default directory (see below) Chapter V:ENVIRONMENTAL CONTROL..Page 61 Documentation for BATUTIL, Version 1.0 alt-letter will move to the first file beginning with that letter <Enter> chooses that file and fills its full pathname in place of the $f. The directory is stored in the variable FDIR with the provisos discussed in section II.6. <Esc> exits with $f and FDIR replaced by the empty string. If the user exits with <Enter>, RC is set to 0 and if with <Esc> to 2. If there is a DOS disk error, RC is set to the 23x errorcodes normally placed in the errorlevel. If a path is specified but the path is invalid, RC is set to 1. Optionally, you can place a filespec in parentheses immediately after $f as in $f(A:d*.*) The filelist will then only list matching files and subdirectories. If there are no matching files or subdirectories, then BATUTIL exits with RC set to 3. If no wildcards are given and there is a single matching file then the single file is used in place of $f and RC is set to 1. Metastring processing is done inside $f primarily to allow for the use of $x. Thus the following works as you'd expect: batutil {ec Enter filespec}{set foo=$Q foo=$f($x(foo))} Only the first $f is expanded on the right side of an equal sign. However, within a single set command, $f's associated with distinct variables will each be processed. While this capability is there, we recommend against normally using it as the user can get confused about there really being several commands. V.6 Saving and loading the environment to a file Commands: SAvenv, LOadenv, KIllenv Parameters: SAvenv and LOadenv take a filename with LOad allowing an extra /m to merge; KIllenv takes a list of variables to keep. BATUTIL allows you to do automated bulk operations to the environment: - {SAvenv filename} will save a copy of the environment in the file "filename". If the file already exists, you will asked confirmation to overwrite. If the user responds N, then the error Chapter V:ENVIRONMENTAL CONTROL..Page 62 Documentation for BATUTIL, Version 1.0 level is set to 199 - {LOadenv filename} and {LOad filename /m} will load a previously saved environment. The first command will completely replace the environment with the one in the file saving nothing from the prior environment. The command with the /m will merge the saved environment with the current environment - variables which are in the current environment but not in the saved environment will be kept. Variables which occur in both the current and saved environment will be assigned the value in the filename. - {KIllenv} will remove all strings from the current environment except for the COMSPEC string which BATUTIL will not remove (if you insist on removing it, use SET comspec= as a DOS command). In addition you can save some specific environmental variables by including their names as parameters. For example BATUTIL {KI path prompt} would remove all non-DOS variables from the environment. The environment saved by the {SA} command is saved as an ASCII file with one variable per line. You can edit it with any ASCII editor that will support lines which are long enough. You can freely add lines but no line should have over 255 characters. Any line added must have the form VARNAME=value (without leading blanks) where VARNAME is all caps, and value is not an empty string. The KIllenv command is intended for use in third party batch files if used with care. You can save the user's environment to a file, use KIllenv and later load the saved environment. You can then use the environment for variable space while your batch file runs. It is recommended that if you do this, you exercise several cautions: - check for sufficient space without killing the environment and if there is sufficient space, don't save and kill. You could also consider checking if the user has DOS 3.2 or later and get the larger environment by using command /c /e:1024 to rerun the batch file with a larger environment - warn the user what you are about to do and give them the option of aborting the batch file. - Be sure to use SA and KI in the same command line as in Chapter V:ENVIRONMENTAL CONTROL..Page 63 Documentation for BATUTIL, Version 1.0 BATUTIL {SA foo1}{KI} since a file error during the save operation will halt BATUTIL and so the KI command won't happen if the SA doesn't work. Also, BATUTIL halts if the file exists and the user says not to overwrite. Check for errorlevel 199 - Be sure to erase the saved environment file when your batch file ends to avoid giving the user a file he/she knows nothing about and to avoid problems if your batch file is rerun. - Check for the existence of the filename you want to save for first and give the user more useful information than the general `File exists; Overwrite (Y/N)?' that BATUTIL provides. V.7. Batch file path control Commands: ADdpath, DElpath Parameters: list of paths separated by space, comma or semicolon - $p and $P are processed. BATUTIL will let you easily add additional directories to your DOS search path and delete directories. The syntax is BATUTIL {AD dir1 dir2 ...} BATUTIL {DE dir1 dir2 ...} The keyword ADdpath or DElpath and the directories in the list may be separated from one another by any combination of spaces, semicolons, and commas. ADdpath can be compared with what you can do in a DOS batch file by saying set path=%path%dir1;dir2; ADdpath allows paths over 127 characters (actually, if you really want a path over 127 characters, you should consider changing your disk setup - too many directory entries in a path will slow DOS down), the $p,$P translation as discussed below and it won't let you duplicate an entry in the path list (so long as you don't try to do something like C:\bin and \bin which it will allow). DElpath will search the path and remove the specified directories if found in the path. The string listed in the command must agree (except for case) with a directory name in the path. ADdpath and DElpath do not do metastring translation except for $p and $P. For example, the following batch files would add and subtract the current directory from the DOS path Chapter V:ENVIRONMENTAL CONTROL..Page 64 Documentation for BATUTIL, Version 1.0 addpath.bat BATUTIL {AD $p} delpath.bat BATUTIL {DE $p} A typical application of these commands would be if a program silly.com requires that its directory C:\rudeprog be in the path when it is run. A batch file to do this would read: BATUTIL {AD C:\rudeprog} C:\rudeprog\silly BATUTIL {DE C:\rudeprog} BATUTIL has no problem reading in paths which don't end with a semicolon but the paths that it writes out always have a semicolon at the end. The AD and DE commands return information in the errorlevel and/or variable RC. AD tells you the number of directories actually added to the path (since entries are not duplicated, this may be smaller than the number listed) and DE the number deleted (since you may have listed a directory not in the path, this may be smaller the number listed). V.8 Direct Editing of the path Command: PAthedit, NBeep BATUTIL {PAthedit} brings up an interactive editor which allows you to edit your path. Up to 17 directories can be displayed at once, with more, you can use the arrow keys to scroll or PgUp/PgDn to move by 10 directories at a time. One of the directories is highlighted. <Up>, <Down>, <Home>, <End> do the obvious thing to the highlight. <Enter> picks out that entry and lets you edit it using the line editor discussed in section I.5. Ctrl-D will delete the directory the cursor is on from the path list (but not change the actually on disk directory) and Ctrl- A will let you add a new path. The order of the directories in your path matters somewhat in that DOS searches in the specified order (in particular, if you have a RAM disk, put its directories before the any others). Alt-T moves the highlighted directory to the Top of the list and Alt-B to the bottom. Chapter V:ENVIRONMENTAL CONTROL..Page 65 Documentation for BATUTIL, Version 1.0 All these changes only effect the in memory copy of the path but not the true path as stored in the environment. When you press <Esc> to exit, if you have made any changes, then BATUTIL will offer to save them to the true path as stored in the DOS environment. There are various places that BATUTIL will beep and display a message to warn you; for example, when you exit and are asked if you want to save the edited environment. If you don't like beeps, the NBeep command will turn off the beeps for the PAthedit and EDitenv commands. You could call up the PAthedit command with BATUTIL {NB}{PA} or can place {NB} in the BATUTIL environment string. V.9 Direct editing of the environment Command: EDitenv Parameter: optional name BATUTIL {EDitenv} brings up an edit module for the full environment very similar to that discussed in the last section. The main difference are the following: - Total and free environment space is listed on the bottom line - Only the first 80 characters of each environment string is displayed. - Each environmental variable has two pieces: the name of the variable and its value stored as name=value <Enter> allows you to edit the value while ^<Enter> the name. While Ctrl-T/B are active, the order of variables in the environment does not normally make any difference. You can also follow ED with a single variable name. If the variable is in the environment, that value is brought into the line editor for editing. If it is a new variable you get to use the line editor to define it. NBeep applies to this module also. You are limited to editing environments with no more than 511 strings (each with no more than 255 bytes). Chapter V:ENVIRONMENTAL CONTROL..Page 66 Chapter VI:TIPS AND EXAMPLES VI.1 General tips After a BATUTIL menu, you'll typically need to branch on a number of different possibilities. The commands if errorlevel 6 goto menu6 if errorlevel 5 goto menu5 if errorlevel 4 goto menu4 if errorlevel 3 goto menu3 if errorlevel 2 goto menu2 if errorlevel 1 goto menu1 followed by choice 0 code will work but the following is more elegant. If there are six menu choices, have labels :menu0,..., :menu6. Use {ME ..} (or {FM ..}) rather than [ME ..] so the choice is placed in the environmental variable RC and then follow this command with goto menu%RC% This gives you a kind of CASE statement. For an example of this see the sample batch file BUDEMO.BAT. Because BATUTIL takes time to reload, you'll want to place several commands on one line. But what if you want to get information about several hardware items - isn't there a problem that each will use the environmental variable rc? No, because unlike DOS' %rc% which is evaluated before the command line is acted on, BATUTIL's $x(rc) does its translation as the command with $x is reached. Thus BATUTIL {#D}{set d1=$x(rc)}{@D} would return the total disk space (#D) in the variable d1 and the free disk space (@D) in rc. For uses of this idea, see the sample batch file equip.bat. It is most convenient to place the fmenu and fecho lines in the batch file itself. If the batch file is foobar.bat, you could use {fecho foobar.bat label} but that will fail if the user renames the batch file so use {fecho %0 label} instead. To handle this possibility, BATUTIL looks first for the filename specified with a {fecho ....} command by name and if that fails it tries the extension bat. VI.2 Returning to your initial directory Chapter VI:TIPS AND EXAMPLES Page 67 Documentation for BATUTIL, Version 1.0 You can arrange to return to your initial directory in a batch file, say one that changes to C:\123 and runs lotus with batutil {set dr=$n di=$p} C: cd \123 lotus %dr%: cd %di% This uses DOS' environmental substitution. You could arrange to save a set of your earlier directories and return to them with two batch files, pushdir and popdir. Pushdir.bat would read batutil {set dr3=$x(dr2) di3=$x(di2) dr2=$x(dr1) di2=$x(di1) dr1=$n di1=$p} all on one line. Popdir would read %dr1% cd %dr1% batutil {set dr2=$x(dr3) di2=$x(di3) dr1=$x(dr2) di1=$x(di2) dr3= di3= } In terms of directory manipulation, suppose you not only want to return to the original directory but you have a program silly in \foo which insists that its directory be in the path even if it is the default directory. You want to add it to the path but later remove it. Use: batutil {set dr=$n di=$p}{ad C:\foo} C: cd \foo silly batutil {de C:\foo) %dr%: cd %di% VI.3 Using BATUTIL in your autoexec.bat There are a number of actions special to an autoexec.bat that make BATUTIL valuable. Your autoexec.bat may take a long time to run because you run a defragmenting utility like VOPT or use a FAT/root dir saver like Norton's FR or you might copy a lot of files to a RAM disk. You might care to branch at the end of the batch file, say to run Software Carousel or not. Of course, you can ask a question but what if you don't want to always stand around and would like to default to running Carousel if you aren't Chapter VI:TIPS AND EXAMPLES Page 68 Documentation for BATUTIL, Version 1.0 there. You could use (as a fragment of your autoexec.bat): BATUTIL {ec Run Carousel (Y/N)?}{ge wa6 y n} if errorlevel 2 goto nocar carousel :nocar You could even have the time counted down by replacing the first line with BATUTIL {ec Run Carousel (Y/N)? $L secs left}{ge wa6 y n} So you've solved the problem of waiting around if you do want to run Carousel. But what if you don't want to. With the above fragment you'd need to wait around. Here is where the test of the lock keys comes in. Immediately before the first line of the above fragment, you could put BATUTIL {ql C-} if errorlevel 1 goto nocar Then, if you hit Capslock before you go off Carousel wouldn't run. Actually, you could avoid an extra running of batutil and two lines of the file by using: BATUTIL {ql C-}{HA $x(rc)=1}{ec Run Carousel (Y/N)?}{ge wa6 y n} as the first line of the fragment. For then if Caps was set, the HAltif command should cause BATUTIL to exit with an errorlevel above 2 (namely with errorlevel 255). Another problem that you'll often want to cope with in a batch file is some operation, like defragmentation that you only want to run once a day. Here is a fragment to do that: BATUTIL {to newday.tst} if not errorlevel 1 goto already echo a >newday.tst STUFF TO DO ONCE :already What this does, is if the error level is exactly 0, then one skips to the label already. Otherwise, the file newday.tst is given today's date so that the next time it is run, "BATUTIL {to newday.tst}" will return errorlevel 0. But what if you sometimes work past midnight and don't want the newday stuff done until morning. Replace BATUTIL {to newday.tst} with BATUTIL {to 5 newday.tst} which will make the change over at 5AM rather than midnight. Chapter VI:TIPS AND EXAMPLES Page 69 Documentation for BATUTIL, Version 1.0 VI.4 A shell for LIST Vern Buerg's LIST program is a lovely file lister but you cannot choose files from a list. If you call it with wildcards, it will successively display every file in the list and going back and forth through them all can be tedious. Moreover, you are limited to the current directory. Here is a way to use BATUTIL to allow more options. Make a batch file called l.bat (assuming the Buerg program is called list and is in the path): echo off :again batutil {AT 0F}{CL}{FE %0 message}{set foo=$F(%1)} if %RC%==2 goto clear if a%foo%==a goto clear list %foo% if %RC%==0 goto again goto clear :message Pick File to List <Esc> exits :clear cls If you type in "l" with no filename, you get to pick from a list of all files and from the BATUTIL pick list and when you exit list the list of filenames will be displayed again. This will happen until you press <Esc>. If there is a filename or filespec listed, you get a choice from those matching files only. If there is a unique matching file, then l just calls list and exits when it is done (that is the reason for the test for RC=2). You could make this shell fancier by allowing the user the option of typing in a file spec using $q which you could pass to $f using $f($x(varname)). To make something like this work, $x translation is done before $f translations. VI.5 A two year olds' delight Here is a simple batch file which delights Barry's two year old daughter for %%a in (1 2 3 4 5 6 7 8 9) do batutil {ge IN}{so 1%%a} Chapter VI:TIPS AND EXAMPLES Page 70 Documentation for BATUTIL, Version 1.0 This will wait for the insert key and then play 9 tunes. The INsert key was especially picked for two reasons: it is large and easy for little hands to reach. It is not a repeating key so that it is less likely that several keystrokes will get through and abort the tunes. VI.6 Sample batch files You will learn a lot about how to use BATUTIL by studying the sample batch files provided. We'll make some comments about them here. One complex nuisance is getting enough environment to run them since it is convenient to store results from BATUTIL in the environment. If it is your own machine or a client's machine, just be sure to have a large enough environment to begin with. DOS 3.2 and later have a documented switches on the shell command that lets you specify a larger environment. DOS 3.1 has an undocumented switch. Various patches to arrange for a larger environment in DOS versions prior to 3.1 are available on BBS systems. But what if you don't know about your users. At a minimum, you can use the {@Env} command to confirm that there is enough environment for your program and exit if there isn't. If you know that your batch file will be running on a machine with DOS 3.2 or later, you could try a shell of DOS with the /e command to make a huge environment. Something like a batch file foo.bat which starts with echo off if (%1)==(restart) goto past %comspec% /c /e:1500 foo restart goto end :past bulk of batch file :end You might add an explicit test for DOS 3.2 or greater using [DOs] and you should certainly use an {@Env} test after the command /c or a {#Env} test before to handle the situation where the user already has a full 1500 byte environment! Perhaps the best method to use is the one exploited in the sample batch files (budemo, equip and input; menudemo uses the simpler halt without 40 bytes free of memory). One saves the environment to a file, kills the environment and later reloads it from the file. It is important to have the {KIll} command on the Chapter VI:TIPS AND EXAMPLES Page 71 Documentation for BATUTIL, Version 1.0 same command line as the {SAvenv} because if the {SA} is not successful, then BATUTIL will exit and the environment will not be {KI}lled. In the budemo case,we check for a minimal free environment and so the {set foo..} is added as a check that there wasn't an exit during the {SA}ve. In the other two files, we can check this with an explicit errorlevel check. Note that budemo checks for at least 136 bytes of environment. This is the maximum that you can by sure of after a {SA ...}{KI} when dealing with naive users. Such users will have the 160 byte environment that DOS gives and they will have the default comspec=C:\command.com 22 byte string (and a double ASCII zero) so they'll have 136 bytes free. There is one other device about controlling the environment which is illustrated in budemo. When DOS makes a shell, it sets up the minimal environment to fit the defined environment of the parent. Thus, the fact that one has 136 bytes free in the environment when %comspec% /c is called is irrelevant - the child will have less than 16 bytes free! This is the reason for the strange set a=aaaaa.... and set b=aaaaa...... lines in the budemo file, the fact that the subsidiary files are called with parameters and that they have the set a= and set b= lines. There are two potential problems with the {SA...}{KI} solution. One is that the user might try to ^Break out of the file and find his environment gone. The other is that the path won't be there. In particular, if command.com is not in the current directory, "command" won't work. Use %comspec% instead - recall that {KI} leaves the comspec variable. Other than the environment, budemo is rather straightforward. It uses the {fecho %0} and goto fmenu%RC% tricks discussed in section 1. It turns the cursor off with the set cur=off command. Soundemo.bat is also straightforward. Note the way the fpretty command is used to produce the second screen with its special box. Showdemo's most interesting feature may be the last panel that illustrates how to use the fpretty command for a display of different columns in different colors. Note the use of the $$. Chapter VI:TIPS AND EXAMPLES Page 72 Documentation for BATUTIL, Version 1.0 Note inputdem's use of $L with spaces after it. Note that equip gets all its information and saves it in the environment and then displays it all at once. The study of these samples should give you an idea of how to use BATUTIL. Chapter VI:TIPS AND EXAMPLES Page 73 Chapter VII:COMMAND REFERENCE In this chapter, we present an alphabetical list of commands with a complete reference for each command in the following format: COMMAND []/{} Input: INPUT Output: OUTPUT Parameters: LIST DESCRIPTION Values: LIST Manual reference: LIST Examples: SAMPLES Internal parameters: LIST See also: LIST ---------------------------------------------------------------------- Here after each command appears []/{} or just {} to indicate whether the command can appear on the command line only within {} or if [] is also allowed. The items in CAPS change from item to item. Input is one or more of the following (inside [] we indicate the abbreviation used): Cmdline [CM] indicates the command takes parameters System [SY] indicates that it reads the internals of your computer Batutil [BU] uses internal flags in BATUTIL User [US] input from user required File [FI] text in a file between sets of labels Output is one or more of the following (inside [] we indicate the abbreviation used): Errorlevel [EL] sets errorlevel and/or the variable RC Environment [EN] effects one or more environmental variables Display [DI] displays on screen or speaker Internal [IN] if an internal flag like CS is effected Values only appears if the commands returns one of a set of numbers and lists those values. Internal parameters lists the internal flags (if any) like CS which BATUTIL keeps and which effect the command. Manual reference gives cross references to the manual. ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 74 Documentation for BATUTIL, Version 1.0 #Altmon []/{} Input: SY Output: EL Parameters: None Returns the type of a second monitor, if any Values: 0 = none 8 = vga color 1 = monochrome (MDA) 11 = mcga mono 2 = cga color 12 = mcga color 4 = ega color 21 = hercules mono 5 = ega mono 22 = hercules monochrome plus 6 = prof. graphics 23 = hercules Incolor 7 = vga mono 99 = unknown Manual reference: Section II.4 Examples: BATUTIL [#A] See also: #Terminal, #Whichmon, @Terminal ---------------------------------------------------------------------- #Comm []/{} Input: SY Output: EL Parameters: None Returns the number of comm ports from 0 to 4 as determined from non-zero addresses in the BIOS area. If there are more than two comm ports, this number may not be accurate since DOS only supports two comm ports and some non-standard method may be used by the system. Values: 0 through 4 Manual reference: Section II.5 Examples: BATUTIL [#C] ---------------------------------------------------------------------- #Disk []/{} Input: SY Output: EL Parameters: Drive letter; no parameter means default drive This command returns the total disk space; for drives A and B in units of 8K; for other drives in units of 256K; rounded down; capped at 199. Values: 0 to 199; 239 means invalid drive letter or drive not ready Manual reference: Section II.3 Examples: BATUTIL [#D C] See also: @Disk ---------------------------------------------------------------------- #Env []/{} Input: SY Output: EL Parameters: None Total environment space in units of 16 bytes up to 3184. Values: 0 to 199 (199 for 3184 bytes of environment or more) Manual reference: Section II.3 Examples: BATUTIL [#E] See also: @Env ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 75 Documentation for BATUTIL, Version 1.0 #Floppy []/{} Input: SY Output: EL Parameters: None Number of floppy drives as reported by the BIOS equipment byte Values: 0 to 4 Manual reference: Section II.5 Examples: BATUTIL [#F] See also: @Floppy ---------------------------------------------------------------------- #Game []/{} Input: SY Output: EL Parameters: None Number of game ports as reported by the BIOS equipment byte Values: 0 or 1 Manual reference: Section II.5 Examples: BATUTIL [#G] ---------------------------------------------------------------------- #Intel []/{} Input: SY Output: EL Parameters: None Returns the CPU type. Values: 0 = 8086/8088; 1 = 80186; 2 = 80286; 3 = 80386; 20 = NEC V20/V30 Manual reference: Section II.5 Examples: BATUTIL [#I] See also: @Intel ---------------------------------------------------------------------- #Keyboard []/{} Input: SY Output: EL Parameters: None Tests for the presence of BIOS support for the enhanced (101 key) keyboard Values: 0 = not enhanced; 1 = enhanced Manual reference: Section II.4 Examples: BATUTIL [#K] ---------------------------------------------------------------------- #Lim []/{} Input: SY Output: EL Parameters: None Reports the total amount of Lotus Intel Microsoft Expanded memory in units of 64K up to 12736 K (rounded down) Values: 0 to 199 (0 if no EMS) Manual reference: Section II.3 Examples: BATUTIL [#L] See also: LIm, #Mem, #Xtended, @Lim, @Mem, @Xtended ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 76 Documentation for BATUTIL, Version 1.0 #Mem []/{} Input: SY Output: EL Parameters: None Returns the total DOS memory in units of 4K rounded down (640K corresponds to 160; because PS/2's have only 639K, 159 will be reported) Values: 0 to 160 Manual reference: Section II.3 Examples: BATUTIL [#M] See also: #Lim, #Xtended, @Lim, @Mem, @Xtended ---------------------------------------------------------------------- #Prn []/{} Input: SY Output: EL Parameters: None Returns the number of printer ports (to which printers may or may not be attached) Values: 0 to 3 Manual reference: Section II.5 Examples: BATUTIL [#P] See also: @Prn ---------------------------------------------------------------------- #Rodent []/{} Input: SY Output: EL Parameters: None Returns 0 if no mouse; 1 if a mouse is present Values: 0 or 1 Manual reference: Section II.4 Examples: BATUTIL [#R] ---------------------------------------------------------------------- #Terminal []/{} Input: SY Output: EL Parameters: None, R, S or C Returns 1 or 2 depending on the number of monitors if no parameter; number of Rows, Columns or Special=Rows - 1 Values: 1 or 2; R=25,43,50 typically; C=40 or 80 typically Manual reference: Section II.4 Examples: BATUTIL [#T]; BATUTIL {#T R}{ec Screen has $x(rc) rows} See also: @Terminal, #Altmon, #Whichmon ---------------------------------------------------------------------- #Vmode []/{} Input: SY Output: EL Parameters: None Returns the currently active mode, e.g. 7 for monochrome text, 2 or 3 for text on a graphics monitor, 16 for EGA hires graphics, etc. Values: 1 to 16 Manual reference: Section II.4 Examples: BATUTIL [#V] See also: #Terminal, #Altmon, #Whichmon, @Terminal ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 77 Documentation for BATUTIL, Version 1.0 #Whichmon []/{} Input: SY Output: EL Parameters: None Returns the type of the currently active monitor Values: 8 = vga color 1 = monochrome (MDA) 11 = mcga mono 2 = cga color 12 = mcga color 4 = ega color 21 = hercules mono 5 = ega mono 22 = hercules monochrome plus 6 = prof. graphics 23 = hercules Incolor 7 = vga mono 99 = unknown Manual reference: Section II.4 Examples: BATUTIL [#W] See also: #Terminal, #Altmon, #Vmode, @Terminal ---------------------------------------------------------------------- #Xtended []/{} Input: SY Output: EL Parameters: None Amount of AT extended memory in units of 64K rounded down up to a maximum of 12736K; with more than that 199 is returned. On an 80386 machine with 386 control software, this number may not be reliable. Values: 0 to 199 Manual reference: Section II.3 Examples: BATUTIL [#X] See also: #Lim, #Mem, @Lim, @Mem, @Xtended ---------------------------------------------------------------------- $A,$a,$B,$C in diverse cmd Input: SY, CM Output: EN,DI Parameters: Filespec in () Parses the file spec in (); $a gives path; $A path with trailing backspace; $B the filename and $C the extension. Manual reference: Section III.2 Examples: BATUTIL {SE file=$f(*.bat) ext=$C($x(file))} See also: SEt, $F ---------------------------------------------------------------------- $F or $f in SEt command Input: SY, CM, US Output: EN Parameters: None or filespec in () Calls up a file list from which the user can pick a file which then replaces $f in the SEt command Values: 0 = file picked; 1 = unique matching file; 2 = Exit with <Esc>; 3 = Invalid path 4 = No wildcards - file not found; 9 = Invalid path Manual reference: Section V.5 Examples: BATUTIL {EC Pick a batch file}{SE file=$f(*.bat)} Internal parameters: FDIR See also: SEt, FDir, $A,a,B,C ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 78 Documentation for BATUTIL, Version 1.0 $L in Echo command Input: CM, SY Output: IN Parameters: None The place where $L would have appeared is remembered by BATUTIL and a subsequent GEtkey with a WAit will have a ticking clock placed in the place. You must place explicit spaces in the echoed string Manual reference: Section IV.5 Examples: BATUTIL {EC Today is $E and you have $L seconds left}{GE WA60} Internal parameters: TimeRow, TimeCol See also: ROw, COl, ATtribute ---------------------------------------------------------------------- $Q or $? in SEt command Input: US, BU Output: EN Parameters: None In the midst of a SEt string, $Q and $? pause to get a string input from the user and that string then replaces the $Q or $?. $Q uses a standard (===>) prompt and standard colors. $? allows you to set colors with the AT/MN commands and puts no special prompt in. Manual reference: Section V.4 Examples: BATUTIL {EC What is your name?$_}{SE name=$Q} Internal parameters: ?Length, ?Size See also: SEt, ?Length, ?Size, QUery, AT, MN ---------------------------------------------------------------------- $X or $x in diverse cmds Input: EN Output: EN, DI Parameters: Variable name in () $x(varname) searches the environment for a variable varname and if it finds it replaces $x(varname) by it value. Otherwise $x(varname) is replaced by the empty string. $X translates the value of the variable using metastring translation. Applies to ECho, PRetty, MEnu, SEt commands Manual reference: Section III.2 Examples: BATUTIL {EC your PATH is $x(path)} Internal parameters: $Translate See also: ECho, FEcho, PRetty, FPretty, MEnu, FMenu, SEt ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 79 Documentation for BATUTIL, Version 1.0 $<letter> in diverse cmds Input: SY Output: EN, DI Parameters: $ followed by $,t,p,d,v,n,g,l,b,q,h,e,_,P,T,M,D,Y, W,E,H,m,S,^,(,),`,' In various places (ECho, PRetty, MEnu, SEt) $<letter> is translated according to DOS prompt metastring rules, SEND/STACKEY extensions and some special BATUTIL extensions. See the list in section III.2 Manual reference: Section III.2 Examples: BATUTIL {EC Today is $E} Internal parameters: $Translate See also: ECho, FEcho, PRetty, FPretty, MEnu, FMenu, SEt ---------------------------------------------------------------------- $Translate {} Input: CM Output: IN Parameters: none or - {$T -} sets an internal flag turning off translation of $letter metastrings in the set, echo and menu commands. $T undoes the effect of $T -. BATUTIL does not keep internal flags from one running to the next so $ translation is turned back on for each new loading. Manual reference: Section III.2 Examples: BATUTIL {$T-}{EC $E}{$T}{EC $Shi $E} would echo "$E hi July 23, 1988" on July 23, 1988 See also: ^Translate, QUery ---------------------------------------------------------------------- ? or ! HELP Initial Parameter Output: IN Parameters: Only first two letters count If ? (not in {} or []) is the first parameter on the command line, help is called and the rest of the command line is ignored except that if the first two letters (or first two letters after a { or [) match a command, help for that command is displayed rather than the main help menu. For help to be available, batutil.hlp must be in the default directory or in your path. ! works the same as ? except that ? has some fancy visual effects and ! suppresses them. Manual reference: I.3 Examples: BATUTIL ? getkey ---------------------------------------------------------------------- ?Length {} Input: CM Output: IN Parameters: 1 to 255 (default is 80) Adjusts the maximum length of user input to a $Q or $? in a set command Manual reference: Section V.4 Examples: BATUTIL {EC Enter your name}{?L 30}{set foo=$Q} See also: ?Size, SEt ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 80 Documentation for BATUTIL, Version 1.0 ?Size {} Input: CM Output: IN Parameters: 1 to 80 Adjusts the size of the edit box for the $Q or $? in a set command Values: 1 to 80 (default is 50); if ?L is less than ?S, then ?S is adjusted downwards Manual reference: Section V.4 Examples: BATUTIL {EC Enter your name}{?L 30}{?S 20}{set foo=$Q} See also: ?Length, SEt ---------------------------------------------------------------------- @Ansi []/{} Input: SY Output: EL Parameters: None Determines if there is an ANSI compatible screen driver present (by saving the current screen and using an ANSI command to move the cursor and checking that the cursor really moved). Values: 0 = No ANSI driver; 1 = ANSI driver found Manual reference: Section II.4 Examples: BATUTIL [@A] ---------------------------------------------------------------------- @Disk []/{} Input: SY Output: EL Parameters: Drive letter; no parameter means default drive Free disk space on the specified or default drive in units of 8K rounded down with 199 returned for 1592K or more free Values: 0 to 199; 239 means invalid drive letter or drive not ready Manual reference: Section II.3 Examples: BATUTIL [@D C] See also: #Disk ---------------------------------------------------------------------- @Env []/{} Input: SY Output: EL Parameters: None Number of bytes of free environment with 199 returned if there are 199 or more free bytes. This is information about the current ACTIVE DOS environment. Values: 1 to 199 Manual reference: Section II.3 Examples: BATUTIL [@E] See also: #Env ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 81 Documentation for BATUTIL, Version 1.0 @Floppy []/{} Input: SY Output: EL Parameters: None For use in systems with a single floppy drive which can be either drive A or B Values: 0 = other than one floppy; 1 = single floppy currently set to drive A; 2= single floppy currently set to drive B Manual reference: Section II.5 Examples: BATUTIL [@F] See also: #Floppy ---------------------------------------------------------------------- @Intel []/{} Input: SY Output: EL Parameters: None Returns information on the type of math coprocessor present Values: 0 = no '87 chip, 1 = 8087, 2= 80287, 3 = 80387 Manual reference: Section II.5 Examples: BATUTIL See also: #Intel ---------------------------------------------------------------------- @Lim []/{} Input: SY Output: EL Parameters: None Returns the amount of free EMS memory in units of 16K rounded down up to 3184K or more which returns 199 Values: 0 to 199 Manual reference: Section II.3 Examples: BATUTIL [@L] See also: LIm, #Lim, #Mem, #Xtended, @Mem, @Xtended ---------------------------------------------------------------------- @Mem []/{} Input: SY Output: EL Parameters: None Free DOS memory in units of 4K rounded down Values: 0 to 160 Manual reference: Section II.3 Examples: BATUTIL [@M] See also: #Lim, #Mem, #Xtended, @Lim, @Xtended ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 82 Documentation for BATUTIL, Version 1.0 @Prn []/{} Input: SY Output: EL Parameters: printer number from 1 to 3, no parameter defaults to LPT1 Returns information about the status of the printer whose number is given as a parameter. Values: returns information about printer as follows: 0 = printer status OK 1 = paper out error 2 = I/O error 3 = Timeout error 4 = invalid printer 5 = other printer error Manual reference: Section II.5 Examples: BATUTIL [@P 2] See also: #Prn ---------------------------------------------------------------------- @Terminal []/{} Input: SY Output: EL Parameters: None Returns the active monitor Values: 0 = monochrome (including Hercules monographics); 1= graphics monitor (CGA, EGA, VGA) Manual reference: Section II.4 Examples: BATUTIL [@T] See also: #Terminal, #Altmon, #Whichmon ---------------------------------------------------------------------- @Xtended []/{} Input: SY Output: EL Parameters: None Returns the amount of free extended memory in units of 16K. Since there is no standard for extended memory, BATUTIL may think that some memory which is used by an application is actually free. It takes into account any VDISK compatible usage. Values: 0 to 199 Manual reference: Section II.3 Examples: BATUTIL [@X] See also: #Lim, #Mem, #Xtended, @Lim, @Mem ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 83 Documentation for BATUTIL, Version 1.0 ^Translate {} Input: CM Output: IN Parameters: None or - {^T -} sets an internal flag turning off translation of ^letter metastrings in the set, echo and menu commands. ^T undoes the effect of ^T -. BATUTIL does not keep internal flags from one running to the next so ^ translation is turned back on for each new loading. Manual reference: Section III.2 Examples: BATUTIL {^T -}{EC ^A}{^T}{EC ^A} would echo the letters ^A and then happy face (= ctrl-A) See also: $Translate, QUery ---------------------------------------------------------------------- ADdpath []/{} Input: CM Output: EN,EL Parameters: list of paths separated by spaces; $p or $P processed Adds the indicated paths to the PATH unless they are already in the path statement. $p is replaced by the current path and $P by the current path with a trailing backslash. Values: 0 to 199 - number of directories actually added to the PATH Manual reference: Section V.7 Examples: BATUTIL [AD $p] would add the current directory to the path See also: DElpath, PAthedit, EDitenv ---------------------------------------------------------------------- ASciiread []/{} Input: US Output: EL Parameters: None Waits for a keystroke and reports the ASCII value of the key struck (0 for extended keys like <F1>) Values: 0 to 255 Manual reference: Section IV.6 Examples: BATUTIL [AS] Internal parameters: NFlush (determines whether the keyboard is flushed) See also: SCanread, GEtkey, NFlush ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 84 Documentation for BATUTIL, Version 1.0 ATtribute {} Input: CM Output: IN Parameters: Hex number from 0 to FF with optional leading $; special meaning if the parameter is T followed by a one or two digit number. BATUTIL keeps an internal attribute used when EChoing, for shadows in MEnus, when the CLs command clears the screen,for the $? command. It defaults to $1E (yellow on blue). The {AT xx} changes it. See section III.3 for a list of attributes. Two special values do not have their default meaning: $55 uses the attribute at the cursor at the time that ECho is called; $66 write with no change in the underlying attributes. {AT Tnm} effects how the time is displayed in a {GEtkey WAit...} command: n from 0-3 (default 3) effects how much time is adjusted and m from 1 to 8, the units used in 1/4 seconds (default is 4; i.e. 1 second). Manual reference: Section III.3, Section IV.5 Examples: BATUTIL {EC hello$S}{AT $4F}{EC there} would echo "hello " in yellow on blue and "there" in white on red. See also: MNattribute, ECho, PRetty, CLs, EOline, ROw, COl ---------------------------------------------------------------------- BEcho {} Input: CM, BU Output: DI Parameters: string to be echoed (special handling of leading ~ and trailing ~ or ^) Echoes a string with large (8x8) characters to the screen with metastring translation and an automatic big CR. Colors determined by the AT and MN flags (defaulting to $1E on color and $07 on monochrome). A final ^ on the string suppress the big CR. Dot patterns for letters replaced by space for off dots and ASCII 219 for on. This can be changed by the BIgchar command. See that description for the treatment of leading/trailing ~'s. Manual reference: Section III.5 Examples: BATUTIL {BE hi there!} Internal parameters: AT, MN, BI, $T, ^T See also: ECho, PRetty, BPretty, ATttribute, MNattribute, BIgchar ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 85 Documentation for BATUTIL, Version 1.0 BIgchar {} Input: CM Output: IN Parameters: one or two ASCII characters. Each character can be replaced by a number from 01 to 255 (use leading 0 for numbers below 10) or a hex number preceded by a $. BEcho and BPretty display large letters based on the dot patterns stored in ROM. On dots are replaced by an "on character" and off dots by an "off character" which default to ASCII 219 (solid block) and ASCII 32 (space). BIgchar allows you to change that - the first parameter is the on character and the second the off character. If the on character is ASCII 255, then the on character displayed is the same as the character being displayed. By default for BEcho, the background character is different from space is displayed on the entire line; leading and trailing ~'s will suppress that. Manual reference: Section III.5 Examples: BATUTIL {BI $20 01}{BP @1FH@1Ei} See also: BEcho, BPretty ---------------------------------------------------------------------- BPretty {} Input: CM, BU Output: DI Parameters: string to be echoed with embedded @ commands (special handling of trailing ~) Echoes a string with large (8x8) characters to the screen with metastring translation and an automatic big CR. Colors determined by the AT and MN flags (defaulting to $1E on color and $07 on monochrome). A final ^ on the string suppress the big CR. Dot patterns for letters replaced by space for off dots and ASCII 219 for on. This can be changed by the BIgchar command. Colors can be changed by @'s in the string to be printed; see the PRetty command. Manual reference: Section III.5 Examples: BATUTIL {BP @1FH@1Ei} Internal parameters: AT, MN, BI, $T, ^T See also: ECho, PRetty, BEcho, ATttribute, MNattribute, BIgchar ---------------------------------------------------------------------- CArousel []/{} Input: SY Output: EL Parameters: None CArousel is special to Softlogic's SOFTWARE CAROUSEL. It returns 0 is CArousel isn't loaded and otherwise returns the current partition number from 1 to 10 (1 to 12 with Carousel 3.0) Values: 0 to 12 Manual reference: Section II.2 Examples: BATUTIL [CA] ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 86 Documentation for BATUTIL, Version 1.0 CHeck []/{} Input: CM, SY Output: EL Parameters: Path with or without trailing backslash Determines whether a given path is present in the system Values: 0 = path valid; 9 = path not found Manual reference: Section II.6 Examples: BATUTIL {CH C:\bin} See also: EXist ---------------------------------------------------------------------- CLs {} Input: BU Output: DI Parameters: None Clears the screen in the current internal attributes which are $1E (yellow on blue) by default on a graphics screen and $07 (normal) on a monochrome screen; may be changed with the AT and MN commands Manual reference: Section III.3 Examples: BATUTIL {AT $1F}{CL} would clear the screen in white on red (!) See also: ATtribute, MNattribute, EOline ---------------------------------------------------------------------- COl {} Input: CM Output: DI Parameters: One decimal number with optional +, - or T in front; decimal number must be between 1 and 80. Moves the cursor; if just a number is given the cursor is moved to precisely that column. If a plus or minus precedes the number, then the movement is relative to the current position but wrapping does not take place so that, for example {CO +80} will always go to column 80. {CO Txx} sets the location of where the countdown clock will occur with {GEtkey WAit} Manual reference: Section III.7, Section IV.5 Examples: BATUTIL {CO 5}{EC This line is indented} BATUTIL {RO 1}{EC Time Left:}{RO T1}{CO T12}{GE WA60} See also: ROw, CUrsor ---------------------------------------------------------------------- CSent {} Input: None Output: IN Parameters: None Input for GEtkey, PMatch and USername are not case sensitive by default; CSent will tell the next call to either of these to be case sensitive. The internal flag is reset by such a call. Manual reference: Section IV.5 Examples: BATUTIL {CS}{GE Y N}{GE Y N} ; the first call would require Y or N; the second would accept Y,y,N or n See also: GEtkey, PMatch, USername ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 87 Documentation for BATUTIL, Version 1.0 CUrsor {} Input: CM Output: DI Parameters: + or - required Turns off the Cursor if a minus is used; turns it back on if a + is used. In either case, the cursor is turned back on when BATUTIL exits. Manual reference: Section III.7 Examples: BATUTIL {CU}{EC hit any key}{AS} See also: ROw, COl ---------------------------------------------------------------------- DAte []/{} Input: None Output: EL Parameters: None Returns the day of the month from 1 to 31 Values: 1 to 31 Manual reference: Section II.2 Examples: BATUTIL [DA] See also: HOur, MInute, WEekday, MOnth, YEar ---------------------------------------------------------------------- DElpath []/{} Input: CM Output: EN,EL Parameters: list of paths separated by spaces; $p or $P processed Deletes the indicated paths from the PATH if they are in the path statement. $p is replaced by the current path and $P by the current path with a trailing backslash. Values: 0 to 199 - number of directories actually removed from the PATH Manual reference: Section V.7 Examples: BATUTIL [DE $p] would remove the current directory from the path See also: ADdpath, PAthedit, EDitenv ---------------------------------------------------------------------- DOs []/{} Input: None Output: EL Parameters: None or 4 Returns the DOS version times ten rounded downwards. "DOS 4" returns 1 if 4DOS is loaded in memory and 0 if not Values: 20,21,30,31,32,33,40 (should work on later versions) 0,1 for "DOS 4" Manual reference: Section II.3 Examples: BATUTIL [DO] ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 88 Documentation for BATUTIL, Version 1.0 DRive []/{} Input: None Output: EL Parameters: None DRive returns the current drive with 0=A, 1=B, ...., 25=Z. This is the drive as DOS reports it so if SUBST is in effect, the subst letter will be used. Values: 0 to 25 Manual reference: Section II.3 Examples: BATUTIL [DR] See also: #Disk, @Disk ---------------------------------------------------------------------- DView []/{} Input: SY Output: EL Parameters: None Dview is special to Quarterdeck's DESQVIEW multitasking software. It returns 0 is DesqView isn't loaded and otherwise returns the current partition number from 1 to 199. Values: 0 to 199 Manual reference: Section II.2 Examples: BATUTIL [DV] ---------------------------------------------------------------------- ECho {} Input: CM, BU Output: DI Parameters: string to be echoed Echoes a string to the screen with metastring translation but no automatic CR/LF. Colors determined by the AT and MN flags (defaulting to $1E on color and $07 on monochrome). Can echo to STDOUT if the STdout command is used. PRetty gives more color control. Manual reference: Section III.3 Examples: BATUTIL {EC hi there!} Internal parameters: AT, MN, ST, $T, ^T See also: FEcho, PRetty, FPretty, ATttribute, MNattribute, STdout,BEcho ---------------------------------------------------------------------- EDitenv {} Input: CM, SY, US Output: EN Parameters: Optional Environment variable With no parameter, this command calls up a full screen listing of all variables in the environment with directions on how to edit them. If a single word is given as a parameter, you can edit the string with that value if there is one or you can enter the value of a new variable. Lengths are limited to 255 bytes (rather than DOS' 127) Manual reference: Section V.9 Examples: BATUTIL {ED prompt} Internal parameters: NBeep See also: SEt, PAthedit, NBeep ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 89 Documentation for BATUTIL, Version 1.0 ENvrep {} Input: SY Output: DI Parameters: None Gives a report on the screen of the total size and free space of the environment, its location in memory and a listing of all strings with their lengths. Manual reference: Section V.2 Examples: BATUTIL {EN} ---------------------------------------------------------------------- EOline {} Input: CM Output: DI Parameters: None or + {EO} erases to the end of the line in the current attributes as set with AT or MN; {EO +} erase the entire line. {EO} does not change the cursor position; {EO +} moves the cursor to column 1. Manual reference: Section III.3 Examples: BATUTIL {RO -5}{EO +}{CO 5}{EC hi} Internal parameters: AT, MN See also: ATtribute, MNattribute, CLs ---------------------------------------------------------------------- ERrorlevel []/{} Input: CM Output: EL Parameters: Decimal number or Hex number preceded by $$ or $x(environmental variable) This allows the setting of errorlevel to a given number. Values: 0 to 199 Manual reference: Section II.9 Examples: BATUTIL {EC Yes or No?}{GE Y N}{EC $_Thanks!}{ER $(RC)} See also: RUn ---------------------------------------------------------------------- EXist []/{} Input: CM,SY Output: EL, EN Parameters: A single filename without wildcards A powerful extension of DOS' "if exist". If filename has no path or drive, the possible responses are 0 = file exists in default directory; 1 = file exists on path (directory will be given in FDIR; see FDIR below); 2 = file doesn't exist on path. If the filename has a drive or path responses are 0 = file exists; 2 = file does not exist; 9 = path invalid. Possible errors in 23x range - see chapter VIII. If the 'file' is a device then FDIR is set to IS_A_DEVICE. Values: 0,1,2,9 Manual reference: Section II.6 Examples: BATUTIL {EX autoexec.bat} Internal parameters: FDIR See also: FDir, CHeck, NUmberfiles, MAke, TOdayfile ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 90 Documentation for BATUTIL, Version 1.0 FDir {} Input: CM Output: IN Parameters: Variable name with leading \ treated specially By default if {EX ...} finds a file in the path but not in the default directory, then the directory of the file is stored in the environmental variable FDIR. Similarly, a choice made by the user in a $f will place the path in the environmental variable FDIR. {FD} with no parameter will suppress and {FD varname} will place it in the variable varname. If varname starts with \ a trailing backspace is added to the path. Manual reference: Section II.6 Examples: BATUTIL {FD \PATH}{EX command.com} See also: EXist, $f ---------------------------------------------------------------------- FEcho {} Input: CM, FI Output: DI Parameters: filename and optional label {FE filename label} finds the file "filename" and searches for a line ":label". It then echoes each line between that label and the next line starting with ":". Full metastring translation takes place. A CR/LF is echoed for each line in the file except for the last. Manual reference: Sections III.5, I.5 Examples: BATUTIL {FE %0 foo} Internal parameters: AT, MN, $T, ^T See also: ECho, PRetty, FPretty, ATttribute, MNattribute ---------------------------------------------------------------------- FKey {} Input: None Output: IN Parameters: None When used before a MEnu or FMenu command, if there are 9 or fewer menu items, this command turns on display of F1, F2, etc to the left of the menu list and the function and number keys make choices Manual reference: Section IV.3 Examples: BATUTIL {FK}{FM %0 menulist} See also: MEnu, FMenu ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 91 Documentation for BATUTIL, Version 1.0 FMenu []/{} Input: CM,FI,BU,US Output: EL Parameters: filename and optional label {FM filename label} finds the file "filename" and searches for a line ":label". It then processes each line between that label and the next line starting with ":". The input lines up to one beginning with @ are treated as menu items; lines after a @ are treated as help text. Manual reference: Sections IV.2, I.5 Examples: BATUTIL [FM %0 menulist] Internal parameters: NMouse, MHeader, POp, SHadow, FKey See also: MEnu, NMouse, MHeader, POp, SHadow, FKey ---------------------------------------------------------------------- FPretty {} Input: CM, FI Output: DI Parameters: filename and optional label {FP filename label} finds the file "filename" and searches for a line ":label". It then echoes each line between that label and the next line starting with ":". The initial attributes are determined by AT and MN but they can by changed by using @ followed immediately by a hex attribute. Full metastring translation takes place. A CR/LF is echoed for each line in the file except for the last. Attributes reset to AT/MN for each new line. Manual reference: Sections III.5, I.5 Examples: BATUTIL {FP %0 foo} Internal parameters: AT, MN See also: ECho, FEcho, FPretty, ATttribute, MNattribute ---------------------------------------------------------------------- GEtkey []/{} Input: CM, US Output: EL Parameters: List of keys as found in Section IV.4. First parameter may be WAnnn or WAEnnn and final one may be BEep or ELse GEtkey waits for a keystroke from the user from a list supplied with the command and returns the number of the choice in the errorlevel. The choice is echoed on the screen. If the final "key" is BEep, the user is beeped for incorrect choices; if it is ELse, an incorrect choice causes an exit. WAit and WAit with Echo will exit after a period with errorlevel set to 0 Values: 0 to 64 Manual reference: Sections IV.4, IV.5 Examples: BATUTIL {GE Y N} Internal parameters: NFlush, CSent, VIsual See also: MEnu, NFlush, CSent, VIsual ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 92 Documentation for BATUTIL, Version 1.0 HAltif {} Input: CM Output: EL, IN Parameters: (~) string1 compare string2 where compare is one of = (or $q), $l or $g Strings1 and 2 as well as the comparison undergo metastring translation. If both strings can be evaluated as numbers up to 134217727 in absolute value, then the comparison is made as numbers, otherwise as strings. If the comparison is valid (or if ~ followed by space is the first parameter), then BATUTIL exits with an errorlevel of 254. Otherwise, the remainder of the command line is processed. Values: 254 Manual reference: Section I.8 Examples: BATUTIL {CA}{HA ~ $x(RC)=0}{EC You are not running Carousel} BATUTIL {HA $H$l12}{EC It's before noon} ---------------------------------------------------------------------- HImem []/{} Input: None Output: EL Parameters: None Returns 0 if no XMS (Himem) driver is loaded and 1 if one is loaded Values: 0 or 1 Manual reference: Section II.3 Examples: BATUTIL [HI] ---------------------------------------------------------------------- HOur []/{} Input: None Output: EL Parameters: None Returns the hour of the day in military time from 0 to 23 Values: 0 to 23 Manual reference: Section II.2 Examples: BATUTIL [HO] See also: DAte, MInute, WEekday, MOnth, YEar ---------------------------------------------------------------------- KIllenv {} Input: CM Output: EN Parameters: List of environment variables Removes all strings from the environment except for COMSPEC and any variables explicitly listed after {KI} Manual reference: Section V.6 Examples: BATUTIL {SA present.env}{KI path} See also: SAvenv, LOadenv ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 93 Documentation for BATUTIL, Version 1.0 LEngth []/{} Input: CM Output: EL Parameters: string with metastring translation Returns the length of the string given so {LE $x(foo)} would return the length of the environmental variable foo. Values: 0 to 199 Manual reference: Section V.4 Examples: BATUTIL [LE $x(name)] ---------------------------------------------------------------------- LIm []/{} Input: None Output: EL Parameters: None Returns 0 if no EMS driver is found and otherwise 10 times the LIM version. Values: Various - most common are 0, 32, 40 Manual reference: Section II.3 Examples: BATUTIL [LI] ---------------------------------------------------------------------- LOadenv {} Input: CM Output: EN Parameters: Filename or Filename /m Finds the file given (looks on path if need be) and if found either replaces the environment with the content of the file or if the /m parameter is included merges it with the environment. No action taken if the file is not appropriate (ASCII with an equal sign on each line and all caps prior to the equal sign). Manual reference: Section V.6 Examples: BATUTIL {LO present.env} See also: KIllenv, SAvenv ---------------------------------------------------------------------- MAke []/{} Input: CM, SY Output: EL Parameters: A pair of filenames Intended for a homebrewed UNIX type MAKE utility this takes two filenames and returns codes as follows: 0 = file2 not found 1 = file2 is strictly older 2 = file1 not found 3 = file1 older or the same age as file2 9 = path not found Values: 0,1,2,3,9 Manual reference: Section II.8 Examples: BATUTIL [MA foobar.pas foobar.exe] See also: EXist, TOdayfile ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 94 Documentation for BATUTIL, Version 1.0 MEnu []/{} Input: CM, BU, US Output: EL Parameters: List of choices separated by spaces Makes a menu with choices given by the list of parameters following the ME command. The number of the user's choice is returned in the errorlevel. Capital letters used for speed choices. Manual reference: Sections IV.1,3 Examples: BATUTIL [ME Copy Erase Rename eXit] Internal parameters: NMouse, MHeader, POp, SHadow, FKey See also: FMenu, NMouse, MHeader, POp, SHadow, FKey ---------------------------------------------------------------------- MHeader {} Input: CM Output: IN Parameters: String Allows you to specify a header to appear at top of a menu prepared with a subsequent MEnu or FMenu command (on the same BATUTIL command line ). Metastring translation is done. Manual reference: Section IV.3 Examples: BATUTIL {MH My menu: $E}[ME Copy Erase Rename eXit] See also: FMenu, MEnu ---------------------------------------------------------------------- MInute []/{} Input: None Output: EL Parameters: None Returns the minute of the hour from 0 to 59 Values: 0 to 59 Manual reference: Section II.2 Examples: BATUTIL [MI] See also: DAte, HOur, WEekday, MOnth, YEar ---------------------------------------------------------------------- MNattribute {} Input: CM Output: IN Parameters: Hex number from 0 to FF with optional leading $ BATUTIL keeps an internal attribute used when EChoing, for shadows in MEnus, when the CLs command clears the screen,for the $? command. Separate attributes are keep for graphics and monochrome screens. It defaults to $07 (normal). The {MN xx} changes it. See section III.3 for a list of attributes. Two special values do not have their default meaning: $55 uses the attribute at the cursor at the time that ECho is called; $66 write with no change in the underlying attributes. Manual reference: Section III.3 Examples: BATUTIL {EC hello$S}{MN $70}{EC there} would echo "hello " in normal and "there" in reverse video See also: ATtribute, ECho, PRetty, CLs, EOline ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 95 Documentation for BATUTIL, Version 1.0 MOnth []/{} Input: None Output: EL Parameters: None Returns the month of the year from 1 to 12 Values: 1 to 12 Manual reference: Section II.2 Examples: BATUTIL [MO] See also: DAte, HOur, WEekday, MInute, YEar ---------------------------------------------------------------------- NBeep {} Input: None Output: IN Parameters: None Suppresses beeps in the EDitenv and PAthedit commands Manual reference: Section V.8 Examples: BATUTIL {NB}{ED} See also: EDitenv, PAthedit ---------------------------------------------------------------------- NFlush {} Input: None Output: IN Parameters: None The keyboard is flushed before user input is gotten for the GEtkey and USername commands; NFlush will tell the next call to either of these to not flush the keyboard allowing STACKEY input or prior user input. The internal flag is reset by such a call. Manual reference: Section IV.5 Examples: BATUTIL {NF}{GE Y N}{GE Y N} ; the first call would not flush the buffer; the second would. See also: GEtkey, USername ---------------------------------------------------------------------- NMouse {} Input: None Output: IN Parameters: None MEnu and FMenu allow the use of a Microsoft compatible mouse if present. NMouse will suppress the use of a mouse. The internal flag is reset by such a call. Manual reference: Section IV.1 Examples: BATUTIL {NM}[ME Copy Erase Rename eXit] See also: MEnu, FMenu ---------------------------------------------------------------------- NSound {} Input: None Output: IN Parameters: None The sound command will be suppressed if this parameter is set. Only makes sense if used as part of an BU@ environment string. Manual reference: Section III.9 Examples: set BU@={NS} See also: SOund ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 96 Documentation for BATUTIL, Version 1.0 NUmberfiles []/{} Input: CM, SY Output: EL Parameters: filespec(s) with path and wildcards allowed. Returns the total number of files found matching one of the given filespecs up to 199 Values: 0 to 199 Manual reference: Section II.6 Examples: BATUTIL {NU C:\bin\*.com C:\bin\*.exe} See also: EXist, CHeck ---------------------------------------------------------------------- OView []/{} Input: SY Output: EL Parameters: None OView is special to Sunny Hill's OMNIVIEW multitasking software. It returns 0 is OmniView isn't loaded and otherwise returns the current partition number from 1 to 10. In versions current at the time this manual is written, the partition is numbered up to 10 but if it increased, this should still work Values: 0 to 10 Manual reference: Section II.2 Examples: BATUTIL [OV] ---------------------------------------------------------------------- P Pause mode Initial Parameter Output: IN Parameters: None If the first parameter on the command line or in BU@ is P (or p), then Pause mode is turned on and messages are displayed when BATUTIL exits with an error and processing is halted until you hit a key. Manual reference: I.3 Examples: BATUTIL P {ec $A} ---------------------------------------------------------------------- PAthedit {} Input: SY, US Output: EN Parameters: None Calls up an interactive editor to edit the path Manual reference: Section V.8 Examples: BATUTIL {PA} Internal parameters: NBeep See also: EDitenv, NBeep, ADdpath, DElpath ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 97 Documentation for BATUTIL, Version 1.0 PMatch []/{} Input: CM Output: EL Parameters: List of words If the words are labelled word0, word1, ... , this command will try to match word0 to word1,.... If there is no match the errorlevel is set to 0; otherwise to number of the first match found. Intended to check batch file parameters. By default not case sensitive. Values: 0 to 64 Manual reference: Section IV.7 Examples: BATUTIL {PM %1 bold compressed underline} Internal parameters: CSent See also: CSent ---------------------------------------------------------------------- POp {} Input: CM Output: IN Parameters: None or + By default, menus just appear on the screen. {PO} will cause them to appear with a visual explosion and {PO +} with a visual explosion and a popping sound. The visual/sound effects occur also when the menu pops down. The internal flag is reset by such a call. Manual reference: Section IV.3 Examples: BATUTIL {PO +}[FM %0 menulist] See also: MEnu, FMenu ---------------------------------------------------------------------- PRetty {} Input: CM Output: DI Parameters: String to display with embedded @ commands Like ECho, this will display a string but with a change in attribute possible in mid-string by inserting @ followed by the hex attribute number. Manual reference: Section III.4 Examples: BATUTIL {PR @1FH@1Ei} Internal parameters: AT, MN See also: ECho, FEcho, FPretty, ATttribute, MNattribute ---------------------------------------------------------------------- QLock []/{} Input: CM, SY Output: EL, SY Parameters: First parameter one of C,N,S,I; second optional +/- Returns errorlevel based on the states of one of CapsLock, Numlock, ScrollLock, Insert mode. Optional turns off (-) or on (+) Values: 0 = off, 1 = on Manual reference: Section IV.9 Examples: BATUTIL [C -] will test Capslock and turn it off ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 98 Documentation for BATUTIL, Version 1.0 QUery {} Input: CM Output: IN Parameters: - or + {QU -} sets an internal flag turning off translation of $Q and $? metastrings in the set command. {QU +} undoes the effect of {QU -}. BATUTIL does not keep internal flags from one running to the next so $Q, $? translation is turned back on for each new loading. Manual reference: Section V.4 Examples: BATUTIL {QU-}{set foo1=$Q}{QU +}{set foo2=$Q} would set foo1 to $Q and foo2 to a user entered string. See also: $Translates, ^Translate, $Q/$? ---------------------------------------------------------------------- REm {} Input: None Output: None Parameters: None Allows placing of remarks in a BATUTIL command line Examples: BATUTIL {AT $4E}{CL}{RE clears screen in red!} ---------------------------------------------------------------------- ROw {} Input: CM Output: DI Parameters: One decimal number with optional +, - or T in front; decimal number must be between 1 and 25. Moves the cursor; if just a number is given the cursor is moved to precisely that row. If a plus or minus precedes the number, then the movement is relative to the current position but wrapping does not take place at the screen top. Scrolling will take place at the screen bottom. {RO Txx} sets the location of where the countdown clock will occur with {GEtkey WAit}. Manual reference: Section III.7, Section IV.5 Examples: BATUTIL {CL}{RO 5}{EC This line is line 5} BATUTIL {RO 1}{EC Time Left:}{RO T1}{CO T12}{GE WA60} See also: COl, CUrsor ---------------------------------------------------------------------- RUn []/{} Input: CM Output: EL Parameters: Program name and parameters This will search the path for the program in question, run it and return the errorlevel. Generally better to run WHATEL which takes less memory away from the program being run. Values: 0 to 255 Manual reference: Section II.7 Examples: BATUTIL [RU programname] ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 99 Documentation for BATUTIL, Version 1.0 SAvenv {} Input: CM Output: EN Parameters: Filename Saves the current environment to an ASCII file in the form VARNANE=var_value one variable per line. Errorlevel set to 199 if the filename exists and user doesn't allow the file to be overwritten Manual reference: Section V.6 Examples: BATUTIL {SA present.env} See also: KIllenv, LOadenv ---------------------------------------------------------------------- SCanread []/{} Input: US Output: EL Parameters: None Waits for a keystroke and reports the "Scancode" part of the int 16H value for the keystruck. Values: 0 to 199 Manual reference: Section IV.6 Examples: BATUTIL [SC] Internal parameters: NFlush (determines whether the keyboard is flushed) See also: ASciiread, GEtkey, NFlush ---------------------------------------------------------------------- SEt {} Input: CM Output: EN Parameters: One or more of the form varname=varvalue SE allows you to place variables in the active DOS environment. Metastring translation takes place including $x, $f, $Q/$? Manual reference: Sections V.3,4,5 Examples: BATUTIL {ec Enter filespec}{set ab=$Q file=$f($x(ab))} Internal parameters: $Translate, ^Translate, QUery See also: $f, $x, $Q/$?, $Translate, ^Translate, QUery ---------------------------------------------------------------------- SHadow {} Input: None Output: IN Parameters: None By default, menus just appear on the screen. {SH} will cause them to appear with shadow in the current colors as set by AT/MN. The internal flag is reset by such a call. Manual reference: Section IV.3 Examples: BATUTIL {SH}[FM %0 menulist] Internal parameters: AT, MN See also: MEnu, FMenu ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 100 Documentation for BATUTIL, Version 1.0 SOund {} Input: CM Output: DI Parameters: Sound number from 1 to 20; optional repeat count Makes one of 20 sounds; 1 to 10 are small sounds, 11 to 20 are tunes. Manual reference: Section III.9 Examples: BATUTIL {SO 18} Internal parameters: NSound See also: NSound ---------------------------------------------------------------------- STdout {} Input: CM Output: IN Parameters: - or optional + {ST +} (equivalent to {ST}) will direct output from the BATUTIL {ECho} command to standard output which can redirected. {ST -} will return to the default behavior of writing ECho output directly to the screen in colors set with AT/MN. Manual reference: Section III.8 Examples: BATUTIL {ST}{EC ^G}{ST -}{EC You dummy!!!} See also: ECho ---------------------------------------------------------------------- TOdayfile []/{} Input: CM, SY Output: EL Parameters: Filename without wildcards; optional hour {TO filename} will search for the file specified and check its date against today's date and return the following: 0 = the file has today's date 1 = the file exists and doesn't have today's date 2 = file not found 9 = invalid path If two parameters are given, the first must be a number from 0 to 23. Then, "today" and the file date/time will be compared assuming days start at the hour in the first parameter. Values: 0,1,2,9 Manual reference: Section II.8 Examples: BATUTIL {TO test.txt} BATUTIL {TO 5 test.txt} See also: EXist, MAke ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 101 Documentation for BATUTIL, Version 1.0 USername []/{} Input: CM, US Output: EL Parameters: sequence of names; first one can be a number of tries; second can be * In its simplest form, a sequence of words are given following {US. The user types in a "username" and BATUTIL responds which number in the list was matched and 0 if the string did not match. If a number is given as the first parameter, the user will have additional chances and the remaining parameters are labelled 1,2,.. and the same rules apply. If the second parameter is *, the same rules apply (with the third parameter now as choice 1) BUT the system is halted if no correct choice is given. Values: 0 to 64 Manual reference: Section IV.7 Examples: BATUTIL Internal parameters: CSent See also: CSent ---------------------------------------------------------------------- V Verbose mode Initial Parameter Output: IN Parameters: None If the first parameter on the command line or in BU@ is V (or v), then Verbose mode is turned on and messages are displayed when BATUTIL exits with an error. Manual reference: I.3 Examples: BATUTIL V {ec $A} ---------------------------------------------------------------------- VIsual {} Input: CM Output: IN Parameters: A,1,N,D,DA,D1,DN Determines the degree of visual feedback from the GEtkey command. The default is to have matching choices echoed including #nnn and two letter abbreviations. A will have incorrect choices echoed in the form letter? or ¿? for keys without ASCII codes. 1 will restrict echoes only to single ASCII codes and N will suppress echos. By default, the cursor moves on space after a GEtkey - D suppresses that space. Manual reference: Section IV.5 Examples: BATUTIL {VI DA}{EC Choose a key}{GE Y N} See also: GEtkey ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 102 Documentation for BATUTIL, Version 1.0 WEekday []/{} Input: None Output: EL Parameters: None Returns the day of the week from 0 = Sunday to 6 = Saturday Values: 0 to 6 Manual reference: Section II.2 Examples: BATUTIL [WE] See also: DAte, HOur, MOnth, MInute, YEar ---------------------------------------------------------------------- Year []/{} Input: None Output: EL Parameters: None Returns the year since 1980 (i.e. 0 = 1980, 10 = 1990) Values: 0 to 19 Manual reference: Section II.2 Examples: BATUTIL [YE] See also: DAte, HOur, WEekday, MInute, MOnth ---------------------------------------------------------------------- Chapter VII:COMMAND REFERENCE Page 103 Chapter VIII:ERROR MESSAGES VIII.1 Fatal Errors There are certain errors that you may make in syntax or problems with your trying to place something in the environment for which there isn't room where BATUTIL cannot recover or where it cannot figure out the action you'd want it to take. There may also be situations where what we think is the environment doesn't seem right and BATUTIL would then want you to contact us and inform us of what has happened. In all these situations BATUTIL exits. One action it does to indicate such a fatal error is to exit with the DOS errorlevel set to a number between 200 and 253. Only the AScii command and the RUn command can return errorlevels in this range without indicating an error. Errorlevel 254 is reserved for the HAltif command and errorlevel 255 for ^Break exits. All other commands set an errorlevel in the range 0 to 199. While debugging a BATUTIL script, you can use either VERBOSE or PAUSE mode. The verbose mode is the default and can be turned off by using a Q (not in brackets) as the first non blank character on the BATUTIL command line or in the BU@ environmental variable. Pause mode can be turneed on similarly except that P is used in place of V. See Section I.3 for further discussion. VIII.2 List of Error Codes 200: Not a BATUTIL command 201: Does not effect errorlevel; use {} not [ ] 202: Incorrect placement of [,],{ or } 204: Some of the required parameters are missing 205: Too many parameters 206: Number expected 207: Number out of allowed range 208: Illegal value for parameter 209: Metastring syntax error 210: Only one #I/@I command allowed per command line 211: Unable to locate DOS environment 212: Environment corrupted or not found 213: Internal error in environment handling 215: Too many variables in environment 216: Environmental variable too large 217: Environment too small for attempted change 220: SAVENV error: path not found 221: SAVENV/LOADENV error: file access error 222: LOADENV error: file not found Chapter VIII:ERROR MESSAGES Page 104 Documentation for BATUTIL, Version 1.0 223: LOADENV error: invalid environment in file 224: LOADENV error: Too large environment in file 226: Invalid path variable in environment 227: Proposed new path is too long 230: Drive not ready 231: Other DOS disk error 232: DOS unable to access drive {DRIVE LETTER} 235: RUN error: Program not found 236: RUN error: Insufficient memory to run program 237: RUN error: DOS error 240: FECHO, FPRETTY, FMENU error: file not found 241: FECHO, FPRETTY, FMENU error: label not found 242: FECHO, FPRETTY, FMENU error: too many lines between labels 243: FECHO, FPRETTY, FMENU error: no lines between labels 245: Too many items in MENU or FMENU 246: Improper FMENU lines 250: HALTIF error: No comparison given 253: Turbo Pascal Runtime Error! VIII.3 Explanation of Error Codes 200: Not a BATUTIL command The first word inside each pair of {} or [] must be one of the BATUTIL commands or must be a valid truncation (have at least the first two letters and the remaining letters agree with a BATUTIL command). ========================================================================== 201: Does not effect errorlevel; use {} not [ ] Some BATUTIL commands set the errorlevel and may be placed inside [] (see section I.4). You placed a command NOT of this type inside []. ========================================================================== 202: Incorrect placement of [,],{ or } BATUTIL was unable to parse the command line because of extra or missing brackets. Here are some examples where you will get this error: BATUTIL {} BATUTIL {EC hi BATUTIL {EC hi{ ========================================================================== 204: Some of the required parameters are missing The command requires more parameters than you have given or you may have given no parameters Chapter VIII:ERROR MESSAGES Page 105 Documentation for BATUTIL, Version 1.0 ========================================================================== 205: Too many parameters BATUTIL has found more parameters than it expected. If you place a parameter with a space in it, you will often get this error since BATUTIL parses a space as a separator between parameters. To place a space in most parameters, use $S ========================================================================== 206: Number expected There are certain place where BATUTIL expects a number, e.g. in {AT xx} where xx should be a number. If there is not a number there, then you'll get this message, for example if you type BATUTIL {AT HI} ========================================================================== 207: Number out of allowed range In a command like {CO xx}, the parameter x must lie in the range 1 to 80 (unless proceeded by a + or -). At least this is so if the screen is 80 columns wide. You'll get this error if a number out of the allowed range is provided. ========================================================================== 208: Illegal value for parameter BATUTIL uses this to indicate some other error in the form of a parameter, e.g. {CU x} must have x equal to + or - and you'll get this error if you use another value. In some places, you'll get this error when error 205 might be more appropriate. ========================================================================== 209: Metastring syntax error BATUTIL found an error when trying to do metastring translation. This most often happens when a $ or a ^ is followed by an illegal character. To place an actual $ or ^ in a string (which can then be followed by anything) remember to use $$ or $^. ========================================================================== 210: Only one #I/@I command allowed per command line You cannot place both an @I and a #I command on the same command line nor are two calls to either allowed. ========================================================================== 211: Unable to locate DOS environment Please report this error to CTRLALT Associates. Since BATUTIL will manipulate the true DOS environment, it is essential that it be found. We believe that our method using undocumented information will always work but if BATUTIL cannot find what it is sure is the real environment, it will exit. ========================================================================== 212: Environment corrupted or not found Please report this error to CTRLALT Associates. Since BATUTIL Chapter VIII:ERROR MESSAGES Page 106 Documentation for BATUTIL, Version 1.0 will manipulate the true DOS environment, it is essential that it be found. We believe that our method using undocumented information will always work but if BATUTIL cannot find what it is sure is the real environment, it will exit. This message indicates that BATUTIL found what it believes to be the DOS environment and it didn't have the proper form. Either BATUTIL didn't find the true environment or your true environment is corrupted. IMPORTANT NOTE: If you are using 4DOS and get this error, only report it if you loaded 4DOS with the /M:xxx parameter. BATUTIL is incompatible with versions of 4DOS prior to 2.1 or ones not loaded with /M. ========================================================================== 213: Internal error in environment handling Please report this error to CTRLALT Associates. Since BATUTIL will manipulate the true DOS environment, it is essential that it be found. We believe that our method using undocumented information will always work but if BATUTIL cannot find what it is sure is the real environment, it will exit. ========================================================================== 215: Too many variables in environment BATUTIL cannot handle environments with more than 510 different strings in it. If you have more than that many strings, let us know - we're curious what you could possibly have there! ========================================================================== 216: Environmental variable too large BATUTIL cannot handle environments where any string has more than 255 characters. Normally, you shouldn't have any such strings since DOS only allows strings up to 127 characters and BATUTIL only up to 255. ========================================================================== 217: Environment too small for attempted change You tried, e.g. with a {SE } command to place something in the environment for which there was insufficient room. ========================================================================== 220: SAVENV error: path not found The directory part of the filespec in {SA filespec} was invalid. ========================================================================== 221: SAVENV/LOADENV error: file access error There was a disk or other error that prevented access to the file in question. The most common cause of this will be a disk full or write protected disk during a SAVENV. The error message displayed on the screen will give extra information (ignore the extra error number given) Chapter VIII:ERROR MESSAGES Page 107 Documentation for BATUTIL, Version 1.0 ========================================================================== 222: LOADENV error: file not found The file which you asked to have loaded into the environment could not be found. ========================================================================== 223: LOADENV error: invalid environment in file There was a line in the file you asked to have loaded into the environment or it did not have the form INCAPS=string on each line. A file obtained with {SAvenv} should always load without this message. If you get this message with a file saved with BATUTIL, please notify CTRLALT Associates. ========================================================================== 224: LOADENV error: Too large environment in file No room in the DOS environment for the file you tried to load ========================================================================== 226: Invalid path variable in environment In parsing the path for a {DElpath ...} or {ADdpath ...} command, BATUTIL found an invalid path. Valid paths have strings without spaces separated by semicolons with an optional semicolon at the end. DOS will accept invalid path strings with its PATH command. ========================================================================== 227: Proposed new path is too long BATUTIL limits environmental strings to 255 bytes each. Your attempt to use {ADdpath ...} or {PAthedit} would have resulting in a path in excess of 255 characters and so it was not accomplished. ========================================================================== 230: Drive not ready DOS error - usually due to an open diskette drive door. ========================================================================== 231: Other DOS disk error DOS wouldn't allow access to the file and reported an error other than Drive not ready. ========================================================================== 232: DOS unable to access drive {DRIVE LETTER} Used by the #Disk and @Disk commands to indicate either error 230 or 231. ========================================================================== 235: RUN error: Program not found The program name after a {RUn ...} command wasn't in the current directory or on the path (or in the directory name that you gave}. RUn can only run EXE and COM programs and not batch files. ========================================================================== Chapter VIII:ERROR MESSAGES Page 108 Documentation for BATUTIL, Version 1.0 236: RUN error: Insufficient memory to run program DOS reported insufficient free memory to run the program you asked to RUn ========================================================================== 237: RUN error: DOS error DOS reported an error when trying to run the program that you asked to RUn. All these errors are unusual and you should report any such message to CTRLALT Associates together with the extra "special error number" which was reported. ========================================================================== 240: FECHO, FPRETTY, FMENU error: file not found In {FEcho filename label}, the file filename could not be found or similarly for FPretty or FMenu ========================================================================== 241: FECHO, FPRETTY, FMENU error: label not found In {FEcho filename label}, the label could not be found or similarly for FPretty or FMenu ========================================================================== 242: FECHO, FPRETTY, FMENU error: too many lines between labels These commands can only read in 25 lines (which is all you'd normally want!) and will give an error if the end of the file or another label is not reached before 26 lines (exclusive of comments) are read. ========================================================================== 243: FECHO, FPRETTY, FMENU error: no lines between labels Either the first line in a file where no label was given or the line following the label give was itself a label line (i.e. began with :) ========================================================================== 245: Too many items in MENU or FMENU Menus are limited to 16 choices. ========================================================================== 246: Improper FMENU lines The first line in FMENU began with an @ which is only used to separate menu items from help text ========================================================================== 250: HALTIF error: No comparison given Each HAltif parameter must have an =, > or < (NOTE: THE > OR < MUST BE ENTERED AS $g OR $l TO AVOID A DOS REDIRECTION) ========================================================================== 253: Turbo Pascal Runtime Error! Most errors indicate mistakes you made or system errors but if you get this message, it means that we made an error because we failed to catch an error and the underlying Turbo Pascal code was Chapter VIII:ERROR MESSAGES Page 109 Documentation for BATUTIL, Version 1.0 called into play. Please report the problem to us with the extra information displayed on the screen =========================================================================== Chapter VIII:ERROR MESSAGES Page 110 INDEX #Altmon 23,75 ECho 34,89 #Comm 24,75 EDitenv 66,89 #Disk 21,75 environment 12,55 #Env 21,75 environment,loading 63 #Floppy 24,76 environment, saving 62 #Game 24,76 ENvrep 57,90 #Intel 23,76 EOline 35,90 #Keyboard 23,76 ERrorlevel 11,29,90 #Lim 20,76 EXist 25,90 #Mem 20,77 Fatal Errors 104 #Prn 24,77 FDir 25,91 #Rodent 23,77 FEcho 13,91 #Terminal 22,77 file pick list 61 #Vmode 22,77 filename parsing 32 #Whichmon 22,78 FKey 45,91 #Xtended 21,78 FMenu 13,44,92 $Translate 30,80 FPretty 13,92 4DOS 8,20,57 GEtkey 47,49,92 ?Length 59,80 HAltif 15,93 ?Size 59,81 help 8 @Ansi 23,81 HImem 20,93 @Disk 21,81 HOur 19,93 @Env 21,81 IS_A_DEVICE. 26 @Floppy 24,82 KIllenv 62,93 @Lim 21,82 label 14 @Mem 20,82 laptop 9 @Prn 24,83 LEngth 59,94 @Terminal 22,83 LIm 20,94 @Xtended 21,83 line editor 14 ^Translate 30,84 LOadenv 62,94 ADdpath 64,84 loading the AScii 52 environment 63 ASciiread 84 Lock status 54 ATtribute 35,85 MAke 94 BEcho 37,85 MAkefile 29 BIgchar 86 MEnu 43,45,95 BIGECHO 36 MENUDEMO 44 BPretty 86 menus 67 CArousel 20,86 metastrings 30 CHeck 26,87 MHeader 45,95 CLs 35,87 minimal truncation 10 COl 40,51,87 MInute 19,95 consultant's license 3 MNattribute 35,95 Control Break 16 MOnth 19,96 CSent 49,87 NBeep 65,96 cursor 13,40 NFlush 49,96 CUrsor 88 NMouse 43,96 DAte 19,88 NSound 41,96 DElpath 64,88 NUmberfiles 27,97 DOs 19,88 OView 20,97 DRive 20,89 parsing 32 DView 20,89 path control 64 PAthedit 65,97 Pause mode 10,97 PIANOMAN 41 pick list 61 PMatch 53,98 POp 45,98 PRetty 35,98 PROMPT metastrings 30 QLock 54,98 QUery 59,99 Quiet mode 9 registration 3 ROw 40 ROw 51,99 RUn 27,99 SAvenv 62,100 saving the environment 62 SCanread 52,100 SEt 58,100 SHadow 45,100 SOund 41,101 STACKEY metastrings 31 standard output 41 STdout 41,101 syntax 10 TOdayfile 28,101 USername 52,102 Verbose mode 9,102 VIsual 49,102 WARNING 56 WEekday 19,103 WHATEL 27 Year 19,103