Category : Batch File Utilities - mostly for DOS
Archive   : ASK11C.ZIP
Filename : ASK.DOC

ASK, v1.1
-------------
from TifaWARE




What's New
----------


With version 1.1 I have significantly reorganized ASK's source code,
placing commonly-used procedures, equates, and macros in separate files.
Sharing code in this way will make it my programming task easier. From the
user's point of view, however, the only change is that ASK no longer
allows a space between '-t' and the time-out value.

Version 1.0 was the first public release of ASK.




Introduction
------------


ASK is a simple utility for batch programming. With it you can ask
questions in batch files and execute commands conditioned on the users'
responses. And its ability to time-out makes ASK perfect for "hands-off"
batch utilities.




Usage
-----


Running this program is a breeze. Assuming you've placed ASK.COM
where DOS can find it, type "ASK -?" to display a brief help message
similar to the following:

TifaWARE ASK, v1.1a, 08/28/90 - ask questions in batch files.
Usage: ask [-options] [msgtxt]

Options:
-l = convert response to lower case
-tn = wait n seconds before timing out
-u = convert response to upper case
-? = display this help message

msgtxt is an optional message to display.

[If you don't remember anything else, at least remember how to display
this help message.]

Typically you'll invoke ASK with some message text. ASK displays the
text, then waits for the user to type a single character. After it detects
a keypress, ASK exits with a return code equal to the ASCII character
code; eg, 'Y' = 89, 'N' = 78, '' = 13, '1' = 49, etc... It's then
up to you to check for specific values via the DOS ERRORLEVEL construct in
a batch file.

You can alter the actual value returned by using the '-l' or '-u'
options. These set the return value based on the character's lowercase and
uppercase ASCII character codes respectively. They are also mutually
exclusive.

You can instruct ASK to time-out rather than wait indefitely for
input. Simply specify the number of seconds to wait using the '-t' option.
If there's no input within that time ASK exits with a return code of 0.
This lets ASK improve upon the DOS PAUSE command. That is, "ASK -t60
Strike a key when ready . . ." duplicates PAUSE's functionality but waits
for input only for a minute!

All of this may be somewhat confusing so here's an example. Let's say
you sometimes, but not always, want to boot your machine with various
memory-resident programs (aka TSRs). You can do this easily by adding the
following to your AUTOEXEC.BAT file:

rem Check whether to load TSRs
Ask -t60 -u Load memory-resident programs (Y/n)?
if ERRORLEVEL 78 if not ERRORLEVEL 79 goto NoTSRs

rem Load 'em
Print /d:PRN
Graphics

:NoTSRs
rem Set environment variables
PATH=C:\BIN;C:\USR\BIN
prompt $p$g

Note how ASK is invoked here. ASK displays the text "Load memory-resident
programs (Y/n)? " then waits for up to a minute for a response. It sets
the return code to the uppercase equivalent of the user's response, if
any. The next line just checks if ERRORLEVEL equals 78, the ASCII code for
'N'. Thus, if the user types either an 'N' or 'n' in this example, TSRs
won't be loaded because execution branches to the label "NoTSRs". Any
other response from the user causes TSRs to be loaded because execution
falls through to the next statement.




If You Have Any Trouble
-----------------------


ASK will let you know of problems that arise. Here are the possible
error messages and how you should deal with each:

ask: illegal option -- x.
- Type "ASK -?" for a list of valid options.

ask: time-out value not specified.
- When you use the '-t' option you must supply
a time-out value. This number represents the
number of seconds to wait for character input
before aborting ASK.

ask: time-out value too large -- 123456789.
- The time-out value must be between 0 and
43199 seconds (12 hours = 43200 seconds).

These messages are written to the standard error device. In this way, they
won't disappear down a pipe or into a file should you redirect ASK's
output.

Additionally, ASK uses a return code to convey information about the
success or failure of its operation. Possible return values are:

Code Meaning
---- -------
0 Time-out value reached without user input
1 - 254 ASCII code for character processed
255 Help message was displayed or time-out was too large

You can test for these codes using the ERRORLEVEL variable in a batch file.
Refer to your DOS manual for a table of keys and their ASCII codes.




Limitations
-----------


To remain portable across all computers running MS-DOS, ASK does not
handle extended scan codes. What this means is that ASK distinguishes only
alphanumeric and punctuation keys. Function keys or keypad keys lead to
unpredictable results.

Keys such as , , or do *not* count as keystrokes
by themselves. They must be used in combination with others.

To handle a time-out, ASK adds the value specified to the current
time, then waits until the current time matches the result. Of course, the
amount of time ASK waits for user input will be accurate only so long as
the system clock does not change in some abnormal fashion. This might
occur if you run ASK in a DESQview window and change the time in another,
or if the system clock loses track of time around midnight while ASK is
waiting for input. It's debatable whether this approach is "good".




Requirements
------------


TifaWARE ASK runs on machines operating under DOS v2.xx or later, and
requires about 2K of memory. It does not use BIOS calls, make direct
writes to video RAM, or otherwise require machines to be "PC-compatible".
In fact, ASK even runs properly on a DEC Rainbow!




Who Owns It?
------------


I am releasing this program into the public domain. Since 1984 I have
used public-domain software extensively, and I find it to be a terrific
idea. Most programs are useful, and the source instructive. And they cost
nothing! With this small contribution to the public domain I hope to pay
back my gratitude to those other programmers who have made my computing so
much easier.

However, this program carries no obligation on my part to support
users or provide future upgrades. I try to write clean code and believe it
is "bug-free". Nevertheless, use this program ***AT YOUR OWN RISK***. Scan
the source yourself, make any desired changes, and recompile the program,
if possible. Make this standard practice with newly-acquired software and
you'll not only protect your system from viruses but also get a better
feel for exactly how programs work!

As author of this program, I have two requests: First, please keep
together the original source code, documentation, and executable if you
distribute the package. This just makes it easier for others to use the
software. Second, let me hear what you think of it - I'd appreciate a
postcard with your comments. Enjoy!




Kudos
-----


Many thanks to Borland for its stand-alone debugger, which greatly
reduced the time spent developing this program.






George A. Theall

TifaWARE
610 South 48th St
Philadelphia, PA. 19143
U.S.A.

[email protected]
[email protected]
[email protected]
[email protected]