KEY-FAKE.DOC
(PC Magazine Vol 4 No 26 December 24, 1985 by C. Petzold)

"Press any key to begin" is a tolerable but minor nuisance. But
can you live with programs that don't maintain configuration files and
required you to enter your printer port number before you start? Or
all those that should have been designed to accept commands but which
walk you through a series of questions and answers instead? Do you
find yourself entering the same few start-up commands every time you
use them?

Usually there's not too much you can do about these annoying
program preliminaries. YOu may have created batch files to change
subdirectories and save much repetitive typing, but normal batch files
don't help once your program begins to execute.

KEY-FAKE is a utility designed to extend the usefulness of your
batch files by letting you supply all the necessary initial keystrokes
to programs automatically. In addition to handling program
preliminaries, KEY-FAKE can even be made to run a whole program
without any keyboard intervention on your part. Hard disk systems
users often assemble a collection of short batch files (often with
one-letter names) that help to navigate through the invariable maze of
subdirectories and programs. Yet once a program begins executing, it's
on its own, and batch file processing doesn't take over again until you
exit the program.

KEY-FAKE extends the power of batch files by filling this gap.
With KEY-FAKE you can put program commands in your batch files as a
series of keystrokes. When the batch file loads the program, these
keystrokes are interpreted just as if you had typed them yourself.

From one perspective, it would seem that this facility is provided
by DOS 2.0 and later versions. It's called redirection of standard
input, and it permits you to substitute a file for the normal keyboard
input. Unfortunately, while redirection of standard input is useful in
certain applications, it is not designed for and cannot be used to take
care of your program preliminaries.

For one thing, redirection only works with programs that use DOS
function calls to get keyboard information. Most large programs use
the BIOS Interrupt 16h for keyboard input instead. Another problem is
that redirection of standard input is al all-or-nothing proposition.
It doesn't switch back to the real keyboard when the redirected file
ends. Thus, if standard input is redirected from a file that is
exhausted while the program is still running, the program will hang.
The only keystroke command to which the machine will then respond is
the drastic reboot.

Unlike redirection of standard input, KEY-FAKE works with programs
that use the BIOS Interrupt 16h for keyboard input. More importantly,
once KEY-FAKE runs out of keystrokes, it relinquishes control and lets
you continue with the typing.



The best way to understand how to use KEY-FAKE and what is does is
by looking at a few simple examples. Suppose that every time you enter
BASICA you execute a COLOR command to create a blue border and
background with yellow letters. With KEY-FAKE, you could create a
two-line batch file (perhaps called B.BAT) to load BASICA:

KEY-FAKE "COLOR 14,1,1" 13 "CLS" 13
BASICA

After BASICA loads, it begins to check for commands coming from
the keyboard. The first keystrokes it reads, in this case, are those
that come from the KEY-FAKE parameter. Rule number one, then, is that
KEY-FAKE must be executed before the program that will use the
keystrokes.

Anything placed in quotation marks in the KEY-FAKE parameter is
interpreted as normal text, just as if you typed it in at the keyboard.
Simple decimal numbers (like the 13) are ASCII codes for non-printable
characters or control codes. A 13 is the Enter key, for example.
Similarly, a 27 is the Escape key, a 9 the Tab key, and an 8 is the
Backspace key.

You may use single quotes or double quotes to delimit a test
string. This is handy if you have to simulate a typed quote sign.
If your text string must include a double quote sign, for instance,
use single quotes as delimiters. (This is a neat trick used by the
IBM and Microsoft Macro Assemblers to solve the perennial quote-
within-quote problem.)

You may also include the "extended ASCII" keys (decimal codes 128
through 255) as part of the KEY-FAKE parameter. These include the
function keys, cursor movement keys, Alt-letter keys, Alt-number keys,
Ins, and Del. These keys are specified in KEY-FAKE by the "at" sign
(@) followed immediately by the extended ASCII code. For instance, if
you usually use the F3 key to load a program when you enter the BASICA
interpreter, you could add that key to the end of the KEY-FAKE command:

KEY-FAKE "COLOR 14,1,1" 13 "CLS" 13 @61

Suppose you have a terrific spelling checker called SpelRite. The
only problem is that it doesn't accept command line parameters. Every
time you run SpelRite, it asks you for the name of the file you want to
check and the subdirectory where the dictionary is located. You can
fix this SpelRite problem with a two-line batch file called SR.BAT:

KEY-FAKE "%1" 13 "\SPELRITE" 13
SPELRITE

When you enter SR followed by a filename, the name will be substituted
for %1 when the batch file executes. KEY-FAKE then answers the two
questions for you.




Suppose that WordStar on the office PC-XT is used by beginners and
experts. The beginners like a help level of 3, but the experts prefer
a help level of 1. Two batch files using KEY-FAKE solve the problem.
The first one (called WSB.BAT), for the beginners, just loads WordStar:

CD\WORDSTAR
WS

The second batch file, for the experts (WSE.BAT), is similar except
that it supplies the WordStar keystrokes to change the help level from
the main menu:

CD\WORDSTAR
KEY-FAKE "H1"
WS

Suppose you want to skip the opening "Include error messages?
(Y/N)" prompt in Turbo Pascal. Set up a batch file with KEY-FAKE
called T.BAT:

CD\TURBOPAS
KEY-FAKE "Y"
TURBO

No patch, no DEBUG, no hex addresses, no problems with different Turbo
Pascal versions. Just a simple Y typed by KEY-FAKE instead.

How would you like to print several WordStar files using one batch
command. Call this file WSP.BAT:

CD\WORDSTAR
:CHECK
IF /%1==/ GOTO END
KEY-FAKE "P%1" 27 "X"
WS
SHIFT
GOTO CHECK
:END

You execute it by typing: WSP file1 file2 file3 .....

WSP.BAT uses the IF statement to check whether a program is
present. If so, the filename parameter is substituted for %1 in the
KEY-FAKE command. When WordStar begins executing, the first keystrokes
it gets are P (for Print), the filename, as Esc (decimal 27), and X
(for Exit). WordStar won't exit until it has finished printing. When
it exits back to the batch file, WSP.BAT does a SHIFT command, making
%1 the next file in the list, and goes through the routine again.







Some programs, like Lotus's 1-2-3, clear out the keyboard buffer
when they load. This would ordinarily be a problem with KEY-FAKE, but
KEY-FAKE has it licked. When the digit 0 appears in a KEY-FAKE
parameter, it takes on special meaning. If a program checks to see
if any keys are waiting, KEY-FAKE will say "No." The program thinks
that no keys are available and the buffer is clear. When the program
checks again, KEY-FAKE says "Yes" and delivers the next keystroke.

Since virtually every time you enter 1-2-3 you do a File Retrieve
command, a batch file (L.BAT) will load Lotus in a hurry:

CD\LOTUS
KEY-FAKE 0 13 0 13 0 13 0 13 0 13 "/FR"
LOTUS

Make sure you have the system disk in drive A: before you run this one.
The string of 0's and 13's was developed empirically, but it works
well, skipping past the Lotus Access System Menu right into 1-2-3,
ready to select a file. Use KEY-FAKE and you'll have to be really
quick if you want to read the copyright notice one more time.

KEY-FAKE also helps out with some odd-ball batch file problems
that may be difficult to handle with other methods. For instance,
suppose you have a batch file that changes the subdirectory, but at
the end of the batch file you want to return to the directory from
which it was executed. The top of the batch file could save the
subdirectory with the following commands:

KEY-FAKE "CD" 26 13
COPY CON \RETDIR.BAT
CD >> \RETDIR.BAT

Here, KEY-FAKE supplies input to the subsequent COPY command. The
keystrokes are CD, a blank, a decimal 26 (Ctrl-Z or End-of-File), and
a 13 (Enter). With these keystrokes, COPY creates a file called
RETDIR.BAT in the root directory. This file contains only the
characters CD and a blank. Then, when the CD command is executed in
the third line, its output (the current directory name) is redirected
and appended to the RETDIR.BAT file. Note the use of the double angle
brackets for appending to a file rather than recreating it.

Now you have a file called RETDIR.BAT in the root directory that
contains a CD command to return to the current subdirectory. The end
of the batch file simply contains the following commands:

CD \
RETDIR

This will then execute the batch file and return you to the
subdirectory from which you started.





You could even develop KEY-FAKE parameters that carry programs
through an entire task. For instance, you could import an ASCII table
of numbers into 1-2-3, save it as a worksheet file, exit to the Lotus
Access System Menu, convert the 1-2-3 file to a .DIF file, and then
run a BASIC program that used the .DIF file, all by executing one
batch file.

Thus, if you have some applications involving several PC programs
that you'd like to automate but that now require manual keystrokes,
then KEY-FAKE may be just the answer.

To recap the syntax, then, KEY-FAKE accepts anything within a pair
of single or double quotes as normal keystrokes. ASCII codes are
specified by decimal numbers. Decimal numbers preceded by the @ symbol
are extended ASCII codes. A zero (0) is a special code to signal to
programs that the keyboard buffer is clear. Anything else in the
KEY-FAKE parameter is interpreted as "white space" delimiting valid
parameters. The KEY-FAKE program does no real error checking.

Naturally, there are some limitations with KEY-FAKE. The first
is the length of the parameter. PC-DOS limits command line parameters
to 127 characters, including the blank that separates the parameter
from the program name and the final carriage return. This limits the
number of keystrokes that KEY-FAKE can fake. If the entire KEY-FAKE
parameter is a string beginning with a quote and you leave out the
final quote and you leave out the final quote (which is allowable),
you'll be able to squeeze in 124 keystrokes.

If a KEY-FAKE command is executed before a previous KEY-FAKE
command has exhausted its stored keystrokes, the second execution will
write over the remaining keystrokes from the first. Watch out for
this if you're nesting batch file executions.

Some program get keyboard information directly from the hardware
keyboard interrupt and will thus bypass KEY-FAKE. Until XyQuest fixes
their word processor (or comes out with a new version), KEY-FAKE will
be entirely ignored by XyWrite II.

Some programs continuously monitor the keyboard and retrieve
keystrokes even if they are not able to use the keystrokes immediately.
This means that you may find that KEY-FAKE will not work well when you
are on-lien using a communications program.

KEY-FAKE cannot simulate keystrokes not supported by the PC BIOS,
such as Alt-Home. Nor can it create different keystrokes for the two
different Plus and Minus keys, which are used as separate commands by
some program (most notably Framework).

Although KEY-FAKE is a program that remains resident in memory,
it may be executed an unlimited number of times during a single PC
session. KEY-FAKE only installs itself in memory the first time it
is executed; subsequent executions take up no extra memory.



The first time KEY-FAKE is run, it saves the vector address of
Interrupt 16h and substitutes an address to its own routine. It then
decodes the parameter into keystrokes and saves them to its own
internal buffer. The decoding of the parameter accounts for about
half of KEY-FAKE's code.

Most large programs use Interrupt 16h to get keyboard information.
(Smaller programs, like the DOS utilities, use the DOS Interrupt 21h to
get keyboard information, but ultimately Interrupt 16h is invoked
anyway.) Normally, the PC's ROM BIOS answers an Interrupt 16h by just
fishing keystrokes out of a small buffer that it maintains and handing
them back to the calling program. The keystrokes get in the buffer
through the much more complex Interrupt 9h routine in the ROM BIOS.
(Interrupt 9h is a hardware interrupt generated whenever a key is
pressed. The routine in the ROM BIOS gets the scan code of the key
and must decode it into an ASCII or extended ASCII code before putting
it in the keyboard buffer.)

After KEY-FAKE is loaded, it intercepts Interrupt 16h calls and
passes back keystrokes from its own internal buffer to the calling
program. When no more keystrokes are left, it simply lets the original
Interrupt 16h operate normally.

Subsequent executions of KEY-FAKE do not remain resident in
memory. KEY-FAKE searches through memory for its copyright notice.
If it finds it, it knows that the program has been executed before.
It then uses the keystroke buffer area allocated during the first
execution and only has to decode the parameter.

The best uses of KEY-FAKE will be those you cook up to automate
your own applications. Batch files are a big help in themselves, but
KEY-FAKE really gives them a real boost in power. And it's always
nicer when your PC does your typing for you.