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:
,,= 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
accepts the current string and exits
restores the original value of the string; if that
original value is empty, blanks the line except, in
that case, with a blank line exits and returns an


Chapter I:OVERVIEW Page 14




Documentation for BATUTIL, Version 1.0


empty string
, move the cursor by a character
<^Left>, <^Right> move the cursor by a word
, to the beginning or end of the line
toggles insert mode which starts as overwrite mode; the
cursor shape indicates what the current mode is
and 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 and the two letter ^QS (or
^Q^S) is the same as .

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 .

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. followed by Ctrl-
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 @ 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
(where 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:
,,,<+> move the cursor down
,,,<-> move it up
, go to the first choice
, go to the last choice
exits and sets the errorlevel to 0
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 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 or 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
- ^ followed by one of [ \ ] ^ _ for those special ASCII
codes, e.g. ^[ for
- ^1, ^3, ^4, ^6, ^7, ^9 for ... as
in STACKEY
- @ followed by an alphabetic letter, number, -, _, + or =
indicated the Alt-combination as in STACKEY, e.g.
@A for
- 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 .

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
#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
(^@ 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
, 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
for Help
and hitting will give information on what is available:
Arrows move the bar cursor by one space
move up/down by one panel of 21 files
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 and 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
will go to the initial directory
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
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. exits with $f and
FDIR replaced by the empty string. If the user exits with ,
RC is set to 0 and if with 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. , ,
, do the obvious thing to the highlight. 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
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
allows you to edit the value while ^ 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
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 . 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 ; 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


$ 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) $ 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 )
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