ASK, v1.1 ------------- from TifaWARE What's New ---------- With version 1.1 I have substantially reorganized ASK's source code, placing commonly-used routines in libraries and useful equates and macros in separate files. From the user's point of view, however, there should be no change in the program except that ASK no longer allows a space between '-t' and the time-out value. Sharing code, equates and macros in this way will make it easier for me to both develop and maintain other assembly language programs. Version 1.0 was the first public release of ASK. Introduction ------------ ASK is a simple utility for batch programming. With it you can execute statements conditionally based on the user's responses to your questions. And its ability to time-out with no response 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 from reading the documentation, at least remember how to display this help message.] Generally you invoke ASK with some message text. ASK displays the text and then waits for the user to type a single character. Once a key is detected, 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. The actual value returned can be altered using the '-l' ('-u') option which converts the character to lowercase (uppercase) before ASK exits. 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 no input is detected before the time-out is reached, ASK exits with a return code of 0. Note that with this feature ASK improves on 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 I'll close this section with 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 code 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)? " and waits for up to a minute (60 seconds) for the user to type a key, which will be converted to uppercase before ASK exits. The next line is a neat way to test if ERRORLEVEL equals 78, the ASCII character code for 'N'. Thus, if the user types either an 'N' or 'n' in response to ASK, execution passes to the label "NoTSRs" and TSRs won't be loaded. Anything else causes execution to fall through to the next statement and thereby load TSRs. If You Have Any Trouble ----------------------- ASK will attempt to let you know of any 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 when redirecting 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 character 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 "typewritter keys"; ie, 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. When a time-out value is specified, ASK adds the value to the current time and then continually compares the result to the current time until the two values match. Of necessity, then, the amount of time ASK waits for user input will be accurate only as long as the system clock does not change in some abnormal fashion. This might occur if ASK is run in one DESQview window and the time is changed in another, or if the system clock loses track of time around midnight while ASK is waiting for input. It's debatable whether this is appropriate behaviour for ASK. Requirements ------------ TifaWARE ASK runs on machines operating under MS-DOS v2.xx or later, and requires less than 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, it will even run properly on a DEC Rainbow! Who Owns It? ------------ I am releasing this implementation of ASK into the public domain. Since my involvement with MS-DOS began in 1984, I've been a heavy user of public domain software. Public domain software is a terrific idea. For the most part, programs are useful and the source code instructive, all at no cost! With this small contribution to the public domain I hope to pay back, in some sense, my gratitude to those other programmers who have made my computing so much easier. As a public domain program, ASK carries no obligation on my part to support users or provide future upgrades. I have tried to write clean code and believe it to be "bug-free". Nevertheless, you must use this program ***AT YOUR OWN RISK***. I strongly urge you to scan the source code yourself, make any desired changes, and recompile the program, if this is possible. If you make this standard practice with newly acquired public domain software, you'll not only protect your system from worms and viruses but also get a better feel for exactly how each program works! As author of ASK, I ask of you two things: First, if you distribute this program, please keep together my original source code, documentation, and executable. This just makes it easier for others to use the software. Second, let me hear what you think of ASK. You don't have to send any money, just comments and suggestions. Kudos ----- Many thanks to Borland for its stand-alone debugger, which greatly reduced the time spent developing this program. George A. Theall TifaWARE 506 South 41st St., #3M Philadelphia, PA. 19104 U.S.A. +1 215 662 0558 GTHEALL@PENNDRLS.UPENN.EDU (Internet)