ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/UTILITY/KEYBOARD/STUFF310.ZIP/STUFFIT.DOC

Text File | 1991-04-29 | 15.9 KB | 459 lines

StuffIt.Doc             Last updated by Roedy Green 1991 April 12


PURPOSE

Stuffit is a utility that automates the keyboard.  You can
provide a script of keystrokes and Stuffit will automatically
type them into your application programs.  What makes Stuffit
different from other keyboard macro programs:

  1. The keyboard remains fully functional the entire time
     for additional manual input or correction.

  2. Stuffit works with intractable programs that throw away
     keystrokes, bypass DOS etc.

  3. Stuffit watches the screen.  It does not just type
     blindly.

  4. Stuffit watches the clock.  It can wake up your computer
     at any time of the day and run programs.

  4. Stuffit can handle large scripts, up to 64K.

  5. Stuffit lets you generate more possible keystroke
     chords (combinations) than other products.

  7. Assembler source code is provided, giving you the
     option of adding new features to the program.


COMMAND LINE PARAMETERS IN A NUTSHELL

+0                  Delay until the application has used up all
                    the keystrokes in the type-ahead buffer.
                    This is useful for applications that throw
                    away keystrokes fed to it too quickly.
                    This is also a handy way to flush any pending
                    (uneaten) codes from a previous invocation of
                    StuffIt. e.g.:
                    StuffIt +0
                    empties StuffIt's internal buffer.

+hh:mm:ss           time delay. (hours and minutes optional)
                    +4   means wait 4 seconds (must be 0..59).
                    +2:4 means wait 2 minutes and 4 seconds.
                    +5:: means wait 5 hours.

=hh:mm:ss           delay until a specific time of day (24 hour
                    format)
                    (hours and minutes optional).
                    =16:00:00 means wait till 4 PM.
                    =00:00:00 means wait till midnight.
                    =0   also means wait till midnight.

nn                  stuff a given character code
                    e.g. 27 for Escape, 13 for Enter
                    Only ASCII decimal numerics are accepted.
                    There are no mnemonics for control
                    characters.
                    See ASCII code chart in your IBM AT tech
                    Reference.

@nn                 stuff an extended code preceded by a null.
                    Only numerics are accepted.  There are
                    presently no mnemonics for these characters:
                    e.g.  @68 = F10, @73 = PgUp etc.
                    See table following for common codes.

cc:ss               specify both the decimal character and its
                    scan code
                    e.g. 43:74 to mean the Plus key on the
                    numeric keypad, rather than the ordinary plus
                    key. See table following for common pairs.

'xxxx'              Stuff the characters between the quote marks.
                    The string itself may not contain 's.

"xxxx"              Stuff the characters between the double quote
                    marks.  The string itself may not contain "s.

F70,20,5,01,"Please enter your phone number"
                    The absolute FIND command.
                    Wait patiently for text to appear at col,
                    row, length, attribute.  The attribute is
                    optional.
                    StuffIt searches starting at column 70, row
                    20 for the string "Please enter your phone
                    number".
                    It waits until the string appears.  The 5
                    means allow some slop.  The string may START
                    anywhere in a window 5 characters wide.  It
                    does not mean the whole string must FIT in a
                    window five characters wide.  See note below
                    on Stuffit's co-ordinate system.  The 01 is a
                    rarely used feature.  It means, the match
                    only counts if the string is displayed with
                    decimal video attribute "01".

P10,1,160,01,"Please enter your phone number"
                    The relative PROMPT command.
                    Wait patiently for text to appear at relative
                    col, row, length, attribute.  The attribute
                    is optional.  Stuffit searches for the string
                    "Please enter your phone number" starting
                    left ten columns, and up one row from where
                    the cursor is.  It waits until the string
                    appears.  The 160 means allow some slop.  The
                    string may START anywhere in a window 160
                    characters wide (two lines).  It does not
                    mean the whole string must FIT in the window.
                    The 01 is a rarely used feature.  It means,
                    the match only counts if the string is
                    displayed with decimal video attribute "01".

!                   Reboot. (=0 ! will reboot at midnight.)

/F:MyFile.Txt       Read commands from MyFile.Txt instead for
                    from the command line.  This command may be
                    only be used on the command line, not nested
                    in a file.

/B:512              Allocate room for 512 bytes for the script.
                    You must allocate enough to store the ENTIRE
                    script once it has been converted to a
                    compact internal form.  On initial loading,
                    StuffIt will use a minimum of 512 bytes, or
                    automatically expand to whatever is necessary
                    to needed to store the compact tokenized form
                    of the input file.  If you want to save a few
                    bytes you can prune it back using the /B:
                    command.  Future versions may do this
                    automatically.

/R                  will Remove (Unload) Stuffit from RAM.
                    StuffIt is a TSR and so stays resident in
                    RAM.  The overhead is minuscule, a mere 1232
                    bytes, half of which is the buffer.


CO-ORDINATE SYSTEM

The co-ordinate system Stuffit uses for the FIND command is very
familiar to programmers who poke bytes into the video REGEN buffer
of display adapters, but it may seem a little strange to someone who
has a mathematical background.  Mathematicians have two systems:

  1. X,Y co-ordinates where the origin 0,0 is in the lower
     left corner.

  2. Matrices indexed by row and column.  Usually rows and
     columns are numbered starting with 1.  Rows are
     numbered starting at the top.  Traditionally co-
     ordinates are given in the order row, then column.

Stuffit uses a hybrid of these two schemes.  It uses row and
column, but starts numbering at 0,0 instead of 1,1 in the upper
left corner.  Stuffit uses column, row order.

For relative positioning in the PROMPT command, left and up are
considered positive.  This is the exact opposite convention to
what the FIND command uses.  Beware!


EXAMPLES:

Format floppies alternately in A: and B:, without answering any
prompts:

REM EXAMPLE 1 FLOPPY FORMATTER
echo off
:loop
Stuffit ' ' +0 13 P25,0,5,"Format another" +1 'N' 13
format A:
Stuffit ' ' +0 13 P25,0,5,"Format another" +1 'N' 13
format B:
goto loop


Use one PC for both backup and Host GW on a LAN:

REM EXAMPLE 2 AUTOEXEC.BAT
Rem Start backup program in batch mode:
Rem Use Stuffit, to reboot GW program at midnight
Stuffit =00:00:00 !
Rem Start GW program
LAN-GW



TROUBLE SHOOTING

PROBLEM: Stuffit fails to send all the keystrokes.  Only some
keystrokes get through.

SOLUTION: Your application is clearing the type-ahead buffer from
time to time.  You can outfox it by using the +2 command to
insert a short delay AFTER the program has cleared the type-ahead
buffer before Stuffit starts poking characters into it again.
This can be combined with the F and P commands to hold off
generating the keystrokes until a omen appears on the screen that
the program is ready for input and is not about to throw away the
keystrokes you feed it.  Sometimes you must combine the
techniques, an F or P command followed by a short delay.

PROBLEM: Stuffit just echoes its command syntax summary no matter
what I do.

SOLUTION:
Stuffit is laconic in its error messages.  It does not tell you
what you did wrong.  You have to guess.  The way you do this is
to take out all your commands.  Then add them one by one.  The
one you last added at the time of failure is the one with the
syntax error.

Note that Stuffit completely analyzes the script before starting
to send any keystrokes to your application.  If there is even one
tiny error in it, it will not do anything.

PROBLEM:  My program insists I use keypad - minus.  Where do I
find the magic colon pair for such keystrokes?

SOLUTION:  There is a list of the most commonly used pairs at the
end of this document.  See the IBM AT Technical reference manual
for more information on system scan codes.

PROBLEM: You referred me to the IBM AT Technical Reference Manual
for scan codes and ASCII codes.  I don't have this expensive
book.  What can I do?

SOLUTION: Call Falk Data Systems at [phone], 5322 Rockwood
Court, El Paso Texas, 79932.  They make an inexpensive wall chart
that shows the ASCII codes.

PROBLEM: I want to generate Shift-PrtSc.  There does not appear
to be a scan code for this combination.

SOLUTION: BIOS processes Shift-PrtSc and Ctrl-Alt-Del directly.
It does not put them in the keystroke buffer.  Perhaps a future
version of Stuffit will simulate Shift-PrtSc.  (The ! command
does simulate Ctrl-Alt-Del to reboot the computer.)

PROBLEM: the F command does not work to fetch a script out of a
file.

SOLUTION: The command is /F:, not F, for fetching from a file.
This is confusing.  The F command is for FINDING a magic string
on the screen.  Perhaps you forgot the colon or inserted spaces.

PROBLEM: My program does not seem to recognize the keystrokes.

SOLUTION:  It is unlikely, but one possible cause is this:  when
you DON'T use the colon form to give Stuffit both the ASCII and
scan code, then Stuffit fakes it by using 2 as the scan code.
Most programs do not check the scan code, but a few might be
confused.  Stuffit generates the proper scan code only for a few
keys -- BS, Tab, Esc, Enter.  If your application needs a
specific scan code/char combination, you must use the CC:SS form.


HOW DOES IT WORK

Most typists can type faster than programs can process
keystrokes.  Thus the BIOS stores keystrokes in a type-ahead
buffer.  Stuffit works by sneakily poking keystrokes to the type-
ahead buffer when BIOS is not looking.  Stuffit thus has no need
of taking over INT 16 to control the handing over of keystrokes
to the application.  The advantage of this method is, Stuffit
works with programs that sneak past INT 16 to use the Enhanced
101-key keyboard features.

There are 254 different extended ASCII codes that can be stored
in a byte.  However there are control sequences such as F1, Home,
Ctrl-F1 which don't have a 1-byte code.  These require a two byte
code, the first byte being a 0-byte lead in.  Stuffit can easily
handle poking that pair into the keystroke buffer, using the @nn
feature.

There are some keys duplicated on the keyboard.  For example
there is a + key sharing the = key.  There also a + key on the
numeric keypad.  Most programs do not care which + key you
pressed. Some do.  These programs find out by using interrupt HEX
16 function 00.  The processed character is returned in AL and
the semi-cooked scan code from the keyboard is returned in AH.
If you the program is picky, you can get Stuffit to generate the
precise character and scan code using the cc:ss command.

Because of history, with each new keyboard design attempting to
maintain partial compatibility with earlier designs, the process
of generating a keystroke has become more and more complex.  Each
keypress down generates a code, as does each key release.  The
keyboard itself translates the codes from row-column on the
keyboard to a raw scan code format.  Then the keyboard controller
in the PC (a miniature computer in its own right) translates them
again.  Then the BIOS translates them yet again, and matches up
the ups and downs, notices chords (multiple keys pressed at once
such as Ctrl Alt and Shift) and generates the keystrokes and puts
them in the keystroke type-ahead buffer.  Further DOS, with its
KEYB utility, may interfere with BIOS to support foreign
keyboards.  So you can see the term "scan" code has many meanings
-- depending just where in this assembly line you look at the
codes.


SCAN CODES

Here are the Stuffit codes for some keystrokes you might want to
generate.  See your IBM AT Tech manual for more:

43:13       plus + on the equal key
43:78       plus + on the keypad

45:12       minus - on the on the underscore key
45:74       minus - on the keypad

174         <<
175         >>
65          A -(normally use "A" instead)
07          Bel
@83         Del
@80         Down-Arrow
224:72 @80 Down-Arrow on the arrow pad
130         e acute
@79         End
13          Enter
13:224      Enter on the keypad
27          Esc
@71         Home
@82         Ins
@74         Left-Arrow
224:72 @74  Left-Arrow on the arrow pad
@3          nul
@81         PgDn
@73         PgUp
@77         Right-Arrow
224:72 @77  Right-Arrow on the arrow pad
09          Tab
@72         Up-Arrow
224:722 @72 Up-Arrow on the arrow pad

@59         F1
@60         F2
@61         F3
@62         F4
@63         F5
@64         F6
@65         F7
@66         F8
@67         F9
@68         F10
@87         F11
@88         F12

@120        Alt 1
@121        Alt 2
@122        Alt 3


@123        Alt 4
@124        Alt 5
@125        Alt 6
@126        Alt 7
@127        Alt 8
@128        Alt 9

@104        Alt F1
@105        Alt F2
@106        Alt F3
@107        Alt F4
@108        Alt F5
@109        Alt F6
@110        Alt F7
@111        Alt F8
@112        Alt F9
@113        Alt F10

@30         Alt-A
@48         Alt-B
@46         Alt-C
@32         Alt-D
@18         Alt-E
@33         Alt-F
@34         Alt-G
@35         Alt-H
@23         Alt-I
@36         Alt-J
@37         Alt-K
@38         Alt-L
@50         Alt-M
@49         Alt-N
@24         Alt-O
@25         Alt-P
@16         Alt-Q
@19         Alt-R
@31         Alt-S
@20         Alt-T
@22         Alt-U
@47         Alt-V
@17         Alt-W
@45         Alt-X
@21         Alt-Y
@44         Alt-Z

@94         Ctrl-F1
@95         Ctrl-F2
@96         Ctrl-F3
@97         Ctrl-F4
@98         Ctrl-F5
@99         Ctrl-F6
@100        Ctrl-F7
@101        Ctrl-F8
@102        Ctrl-F9
@103        Ctrl-F10

!           Ctrl-Alt-Del
@117        Ctrl-End
@119        Ctrl-Home
12          Ctrl-L
@115        Ctrl-Left-Arrow
@118        Ctrl-PgDn
@132        Ctrl-PgUp
@114        Ctrl-PrtSc


@116        Ctrl-Right-Arrow

@84         Shift-F1
@85         Shift-F2
@86         Shift-F3
@87         Shift-F4
@88         Shift-F5
@89         Shift-F6
@90         Shift-F7
@91         Shift-F8
@92         Shift-F9
@93         Shift-F10
            Shift-PrtSc -- there IS no code for this.

CREDITS

Terje W. Mathisen wrote Stuffit and the first documentation.
Roedy Green polished the documentation.


PAYMENT AND LICENSING

This program is absolutely FREE.  I don't want money, I have
money.  What I want is recognition (admiration?), from other
programmers.  You may use it for whatever you like, but it is not
warranted for any purpose.  Copyright 1991 by Terje W. Mathisen.

Terje W. Mathisen
Oslo, January 1991.