1. QUICK START

ASK allows you to ask for input from the user in a batch file. The
simplified syntax is

ASK [prompt] [expected Keys]

Prompt is a "quoted" string that will be printed by ASK. Expected
keys is a list of key that you expect from the user. The result
is testable by the "if errorlevel" statement in a batch file. For
example (in a batch file):

echo off
ask "Do you want to run away (y/n)? " yn
if errorlevel 2 goto no
rem *** errorlevel 1 falls thru here. Now run away.
away
:no

When the user runs this batch file, he will get this prompt:

Do you want to run away (y/n)? _

He can press the 'y' or the 'n' key. If he presses the 'y'
key, errorlevel will be set to 1 (because y is the first
character in the expected keys list) and away will be run.
If he presses the 'n' key, errorlevel will be set to 2 and
away will not be run.

This should get you started. There are some other examples
in this document as well as in the file EXAMPLE.BAT (which
you can run).

2. REFERENCE

2.1 Introduction

ASK is a program for you to use in a batch file to ask for one-
key responses from the user. ASK then sets the errorlevel
according to the key pressed. The errorlevel can be tested in a
batch file to branch to different places. This allows you to ask
simple questions like the Yes-or-No type, or to set up a menu-
driven batch file. ASK also accepts options like no echo, time
out, flush type-ahead.


2.2 Syntax

ASK [Options] [Prompt] [Expected Keys]


2.2.1 Prompt

[Prompt] is the question to be displayed. It is a "quoted string"
(double quotes only). You can embbed double quotes in the prompt
by using \" (backslash-quote). If you do not supply [Prompt], ASK
will use the default '? '. If you want an empty prompt, use "".


2.2.2 [Expected Keys]

[Expected Keys] is a string of all the different keys that the
user may press in response to your question. There is no need to
quote this string unless you want to include a space in it.
Another way to include a space is to use '\ ' (blackslash-space).

If the user presses the first key listed in the [Expected Keys],
the errorlevel will be set to 1; if the user presses the second
key in the [Expected Keys], the errorlevel will be set to 2, and
so on. If the user presses a key that is not in the [Expected
Keys], ASK will beep and prompt him again until he gets it right.
You can override this action with the /q option.

If the [Expected Keys] string is not present, the errorlevel will
be set to the character code of the key the user pressed. By
default, lower case letters will be mapped to the upper case
counterpart, i.e. letters always return 65-90. You can disable
this mapping with the /c option.

If there is no [Expected Keys] and the user presses a key that
maps to an extended ASCII, ASK returns 0 (zero). The only way to
match a function key is to list that key in [Expected Keys].

When testing errorlevel, be sure to test for the highest number
first because

if errorlevel 5

means

if errorlevel equal to or greater than 5.


2.3 Options

Options are used to change the behavior of ASK somewhat. The
option letters themselves are not case sensitive so you can use
either upper or lower case.

/F - flush all keys type-ahead before accepting input

/E - no echo. Accept input but do not echo it to the
screen. The cursor is also turned off during input.

/Q - be quiet, don't yell at the user for invalid
response, but return 0 as the errorlevel. This
option is meaningless if there is no [Expected
Keys]. This is normally used when you want to trap
invalid responses and print your own error message
instead of using the built-in one.

/C - make [Expected Keys] case sensitive. This means
letters pressed by the user will only match letters
in the same case in [Expected Keys]. If there is
no [Expected Keys], then UPPER case letters will
return errorlevel 65-90, and lower case letters will
return 97-122.

/Sxxx - timeout after xxx seconds and return errorlevel 255.
xxx can be from 1 to 3 digits and range from 0 to
999.

If you supply 0 (zero) as the timeout value, ASK
will check the keyboard buffer once before it times
out. If there is a key in the buffer (typed ahead),
ASK will read it.

If you do not supply any value, ASK will time out
immediately without even checking type-ahead keys in
the keyboard buffer. You can use ASK this way as an
alternative to DOS' ECHO command. The advantage is
that you can use ASK to print control characters. E.g.
ask/s "\e" > E.TXT will put the escape character in
the file E.TXT.

If more than one timeout option is given, the effect
is cumulative. Accuracy is from +0 to -1 second. So
if you say s10 it would delay from 9 to 10 seconds.

When ASK times out it will not print a linefeed so
that the next thing you ECHO will appear immediately
after the [prompt]. I usually print *TIMEOUT* so if
a user is watching he will understand why things are
happening even though he didn't press any key.

/Myyy - timeout after yyy minutes and return errorlevel 255.
yyy can be from 1 to 3 digits and range from 0 to
999. See the /S option for other details.

More than one option letter can share a common switch, like
this:

ask /QS50C "Blah Blah? "
ask/qcm5 "Blah Blah? "
ask /c/s9/q "Blah Blah ?"


2.4 Special Characters

Characters that you normally cannot put on a command line (e.g.
carriage return, escape, backspace, ...) can be included in
either [Prompt] or [Expected Keys] using the following
conventions:

\nnn - translates to ASCII nnn where nnn is a 3-digit
decimal number. If this is not followed by another
digit then you don't need to put down all three
digits. If it is followed by a digit, then you have
to put down all three digits (add leading zeros if
necessary).

For example:

ASK "\7HI: " prints a beep and "HI: "
ASK "\0070 HI: " prints a beep and "0 HI:"
ASK "\070 HI: " prints "F HI: "

\e - the escape character. This is equivalent to \27,
\027, or \E.

\\ - the \ (backslash) character itself

\" - the double quote character (without the backslash it
will be interpreted as the beginning or the end of a
quoted string).

\~ - the tilde character itself.

~a - translates to control-a. This works when 'a' is from
ASCII 64 to 95 (which produce ASCII 0 thru 31) or is
a lower case letter.

~(X) - interpret this as a function key. X is the label on
the function key. E.g. ~(f1) refers to the key (F1),
~(ins) refers to the (Ins) key.

The label is not case sensitive, so you can use upper
or lower case. So ~(F1), ~(INS) would also work.

You can use the prefixes S-, C-, and A- with the
labels to denote Shift-, Ctrl-, and Alt- version of
the key, like ~(s-f1), ~(c-f1), and ~(a-f1).

This notation is only recognized in [Expected Keys]
and not in [Prompt], because function keys cannot be
printed.

Here's some examples on using special characters:

ask "How \"are\" you?" - will produce How "are" you?
ask "Hi?\7" - will produce Hi?*BEEP*
ask "Hi?~g" - will also produce Hi?*BEEP*
ask "hi" ~m - will let the user use the enter
key as a valid response
ask "Press (F1)" ~(f1) - wait for user to press the (F1)
key

If you want to use function keys, you should know that not all
keys have a Shift-, Alt-, or Ctrl- version. For instance, Ctrl-
Del produces nothing. If you are not sure what a certain
combination will produce, let ASK help you. Simply type

ask

and press the key in question. ASK will echo the key you just
pressed. If you press Ctrl-PgUp, you'll see this:

? (C-PgUp)

The '?' is the default prompt provided by ASK because you didn't
supply one. The (C-PgUp) is the echo of the key you just pressed.
Now you know you can use ~(c-pgup) in the [Expected Keys] to
match this key. If you had pressed Ctrl-Del, the effect is like
you didn't press any keys.

The errorlevel is set to 0 for an extended ASCII if no [Expected
Keys] is supplied, like in this case.


2.5 Other use

You can use ask for many other purposes:

1) As an ECHO command that lets you print control characters.
E.g. ask/s \7beep!

2) As a delay command. E.g. ask/m60 > nul (delay 60 minutes).

3) As a PAUSE command with your own prompt.
E.g. ask/e "Wake me up when ready ..."

4) Used it to flush type-ahead in a batch file before running
another program. E.g. ask/fs

These usages might not seem very useful, but they might inspire
you to think of something useful.


3. EXAMPLE

Here are some examples on how you could use ASK to improve your
life.

If many people use your computer and say a new version of EDLIN
just arrived, you can name the old one EDLIN1 and name the new
one EDLIN2, and put the following in EDLIN.BAT:

echo off
echo "(F1) EDLIN old version"
echo "(F2) EDLIN new version"
ask/e "Choose one - Press (F1) or (F2)" ~(f1)~(f2)
if errorlevel 2 goto new
edlin1 %1
goto end
:new
edlin2 %1
:end

When people entered EDLIN, they'll run this batch file and be
given a choice of which version to use. This way you don't have
to tell everybody that a new version of EDLIN is installed.

Here's an example that allows the user to indicate the default
response by hitting the Enter key:

echo off
ask "Should I do it or not (Y/N) [default Y]? " \13yn
rem ** errorlevel = 3 means n key
rem ** errorlevel = 2 means y key
rem ** errorlevel = 1 means return key
if errorlevel 3 goto no
DoIt
:no

Now if the user press the Enter key, the computer will DoIt. Note
that \013 can be abbreviated as \13 when it is not followed by
another numeric character.

I like to run chkdsk once in a while but if I don't put it in the
AUTOEXEC>BAT file I'll forget to run it. On the other hand, I
don't want to run it every time I boot because it takes a while.
So I put this in my autoexec.bat:

echo off
ask/s30 "Run chkdsk (y/n) [n]? " yn~m
if not error 255 goto timein
echo *TIMEOUT*
echo Running chkdsk. Take your time in the bathroom.
goto chkdsk
:timein
if errorlevel 2 goto nocheck
:chkdsk
chkdsk
:nocheck

Normally when I boot the computer I'll just hit Enter to the "Run
chkdsk" question to skip chkdsk. But sometimes I'll turn on the
machine and go to the bathroom. In that case ASK will time out
after 30 seconds and start running chkdsk. By the time I come
back from the bathroom chkdsk will be done and I've wasted no
time.

In this case, I'll see this on the screen when ASK times out:

Run chkdsk (y/n) [n]? *TIMEOUT*
Running chkdsk. Take your time in the bathroom.

If you use ANSI.SYS or similar screen driver, you can use ASK to
set color or screen mode. For example:

ask/s "\e[32m" -- set foreground to green

To restore your screen to normal white on black, type

ask/s \e[0m

The quotes can be omitted in this case since there are no spaces
in the prompt string.


4. HISTORY

The idea for ASK came from a program called BATQUES contributed
to the INFO-IBMPC library (an electronic library on the ARPANET)
by H. Fischer. The motivation for writing ASK is to avoid the
need for an ASCII table (to use BATQUES).

This is the second version of ASK (the previous one is ASK.ASM).
This version has the following changes/additions:

1) The program is written in C (IBM C 1.0, compatible with
MS C 3.0). Using C allows me to add more functions easily at
the cost of increased execution code size. But I think it's
worth it.

2) There are two special characters: \ (backslash) and ~
(tilde).

3) Support for function keys.

4) New options: time out, no echo, flush type ahead.

5) Comes with a demo batch file.

If you are switching to this version from the old version, you
have to change the special character from ^ to \ or ~ in your
existing batch files that use ASK.


5. AUTHOR

Peter Wu
Faculty Support Center
1210 W. Dayton Street, B106
University of Wisconsin, Madison
Madison, WI 53715

Electronic mail addresses:

uucp: ..{seismo|akgua|allegra|harvard|ucbvax}!uwvax!uwmacc!pwu
arpa: [email protected]
bitnet: WU at WISVMACC
compuserve: 76377,1332

Feedback, bug-report, and comments are welcome.