                               KEYBOSS.BIN

          Copyright (c) 1990  John M. Bauman  All Rights Reserved

29 July, 1990   Version 1.0

keyboss.bin:    loadable/callable keyboard handler for xbase

        Keyboss provides FoxPro programmers all the power over the
keyboard that FoxPro left out.  With KEYBOSS you may:
        
        1.  Disable/Re-enable up to 26 individual keys from within your
programs.  Disable the ESCAPE key to prevent user exit from BROWSE's,
READ's, etc.  Disable the PRTSC key.  Disable the BREAK key while
your application RUN's a DOS batch file, etc.

        2.  Disable the entire keyboard during multiple ON KEY LABEL
definitions to prevent inadvertent early activation of your program's
modules.

        3.  Disable Ctrl-alt-del to prevent re-booting during disk
intensive activities (of course this doesn't prevent a power down...)

        4.  Disable the ALT activation of the SYSMENU.  This allows
you to leave SYSMENU set ON so that full window/mouse functions are
available but prevents inadvertent access to the SYSMENU functions by
end users of your applications.  (Tip:   Use ON KEY LABEL F10 * to
disable activation of SYSMENU by presses of the f10 key!)

        5.  Re-designate the ESCAPE key as another key.  KEYBOSS
comes with an option to re-designate ESCAPE as ALT-0.  This causes
ESCAPE key presses to act like ALT-0 was pressed.  Now you can use 
ON KEY LABEL ALT-0 to re-program the escape key to do what you like.
        
        6.  Advanced KEYBOARD function:  Use KEYBOSS in place of the
native KEYBOARD command to stuff the keyboard buffer with *ANY* keystroke
without having to use PLAY MACRO to do so. 

sample syntax:    (variables are NOT required but add clarity)
                
    Install   = "I"         && install keyboss keyboard handler                
    Uninstall = "U"         && uninstall keyboss keyboard handler                
    Enable    = "E"         && enable specific keys previously disabled                
    Disable   = "D"         && disable specific keys                
    Kbd       = "K"         && keyboard a specific key/key combination
                             * see below *

    Esc_to_a0 = "A"         && change escape to Alt-0

    A0_to_esc = "P"         && change escaPe back to escape

    Esc_key   = CHR(1)      && keyboard scan codes                
    Prtscr    = CHR(55)     && complete list provided in file scancode.lst           
    F1        = CHR(59)                
    Alt_rel   = CHR(184)    && disable alt activation of sysmenu FP ONLY
    Keyb_off  = CHR(255)    && turn off entire keyboard (ONLY IN programs)
    No_boot   = CHR(254)    && disable ctrl-alt-del
                
    LOAD KEYBOSS                
    CALL KEYBOSS WITH Install + No_boot    && install/lockout ctrl-alt-del
                    
    CALL KEYBOSS WITH Disable + Esc_key + Prtscr + F1
                    
    CALL KEYBOSS WITH Enable + F1
                    
    CALL KEYBOSS WITH Disable + F1 + Alt_key
                    
    CALL KEYBOSS WITH Enable + Alt_key + Esc_key
        
    CALL KEYBOSS WITH Esc_to_a0               && escape now = alt-0
                    
    CALL KEYBOSS WITH Disable + Alt_rel       && lock out sysmenu FP ONLY

    CALL KEYBOSS WITH a0_to_esc               && escape now = escape
                
    CALL KEYBOSS WITH Uninstall               && all keys active again
                
    RELEASE MODULE KEYBOSS                    && ALWAYS uninstall FIRST

Logic:

    Calling keyboss with "I" installs keyboss as a "ram resident"
keyboard handler, switching all keyboard input through itself and
monitoring keyboard input for your program requests.  Keys to be
disabled may be designated at install time, but if other keys are
to be disabled subsequently the "D" option must be used.

    Calling keyboss with "U" uninstalls the interrupt handler, making
it point back to where it was to begin with and restores all keys to
normal function.

    Calling keyboss with "D" plus key scan codes stores those codes to
a table.  Subsequent keypresses of those keys are discarded until enabled.

    Calling keyboss with "E" plus key scan codes deletes those codes from
the table so they are active again.

    Calling keyboss with "A"  (ONLY AFTER INSTALLING) causes the
escape key to be re-designated as alt-0

    Calling keyboss with "P"  (ONLY AFTER INSTALLING) causes the
escape key to register as escape again.

    Calling keyboss with "K" + [shift state code] + scancode
stuffs the keyboard buffer with the requested key/key combination. 
Shift state codes are as follows:

        A = ALT key combination
        S = SHIFT key combination
        C = CTRL key combination
        P = PLAIN                       && included for completeness

        Examples:

        LOAD KEYBOSS                    && do these two once at beginning
        CALL KEYBOSS WITH "I"           && of program
        
        CALL KEYBOSS WITH "KA" + F1         && keyboard alt-f1
        CALL KEYBOSS WITH "KC" + CHR(32)    && keyboard ctrl-d
        CALL KEYBOSS WITH "KS" + CHR(68)    && keyboard shift-f10
        CALL KEYBOSS WITH "KP" + CHR(32)    && keyboard a small "d"

        A complete list of keyboard scan code values is provided
in the separate file, scancode.lst.  The codes in the list are the
decimal codes reported for each key and should be "sent" to KEYBOSS
using the chr() function.

Caveats:

        While the program will NOT allow itself to be installed or
uninstalled more than once, it WILL lock up your machine if you
"RELEASE MODU keyboss" WITHOUT FIRST UNINSTALLING IT.  You MUST
uninstall BEFORE releasing.

        However, due to a neat trick pointed out to me by Jim Kyle,
you may QUIT xbase with the .bin file loaded AND active...i.e. LOAD'ed
and either installed or uninstalled.  However a keyboard lockup is
GUARANTEED if you RELEASE MODULE without uninstalling the keyboard
handler.

        This is a "gotcha" kind of problem because the keyboard will
still work until xbase re-uses that memory (for example your program
loads in a .bin), overwriting the keyboard handler.

        The ALT_REL code (chr(184)) is intended for use with FoxPRO.
Use with other programs may provide irregular results.

        I have tested this software on a Compaq 286-12 with no
adverse effects whatsoever.  It has undergone testing and
implementation at multiple sites.  The only problems encountered
thus far relate to SideKick or BIOS incompatibilities.  BIOS
incompatibilities are related to different implementations of the
101 keyboard and its scan codes.  Test this program with various
combinations of keys to be sure it works (especially cursor/keypad
combinations with numlock off/on) as you expect it to on your
machine.

disclaimer:

        The author does not warrant this program for fitness to
perform any specific task.  Use at your own risk, the data you save may
be your own.  Any loss of data, money, life, limb or any damage whatsoever
to any machine, program or disk this software is run on is hereby disowned.
PLEASE TEST THIS PROGRAM THOROUGHLY TO ENSURE COMPATIBILITY WITH YOUR
MACHINE'S BIOS AND YOUR PROGRAMMING NEEDS.

Version history:

version 1.00    esctrap.bin  dedicated, stops escape ONLY, 8-10 May
                1990

version 1.01    added cli/sti around install/uninstall vector moves and
                a copyright notice - 12 May 1990

version 1.1     changed from dedicated <ESCAPE> trapper to trap any
                key via its scan code. - 13 May 1990

version 1.5     changed from trapping any 1 key to trapping up to 26
                keys at a time!  13 May 1990

version 1.8     added options "E"/"D" to the calling syntax for ease of
                use.  14 May 1990

version 2.0     added hook to xbase so that
                an abrupt 'QUIT' with KEYTRAP loaded will NOT lockup
                the keyboard.  17 May, 1990

version 2.01    fixed stack problem with multiple installs. 
                as it stands, calling keytrap with "I" repeatedly will NOT
                cause a machine lock up.  (nor install multiple copies)  
                Currently disabled keys remain disabled.  However, 
                you may NOT use the "I" option to disable
                additional keys.  use the "D" option to disable additional
                keys once KEYTRAP is installed OR, uninstall first then
                Install again with new keys to be disabled.
                17 May, 1990

version 3.0     much expanded to handle turning off solitary ALT's in
                FP while leaving other alt-key functions intact, including
                keypad generation of extended characters for text input.
                3 June, 1990

                Also, keytrap respects numlock status:  Must have numlock
                on to generate ascii codes.  Shift-keypad does NOT turn
                numlock on with keytrap.  (FP returns extended codes with
                alt-keypad REGARDLESS of numlock status.)

version 3.01    Fixes problem with ALT-ALT (both alts) and ALT
                Rt-ctrl activating sysmenu in FP.  Traps extended keyboard
                codes.  5 June, 1990

version 4.0     Fixes problem with <alt> prtsc activating sysmenu when it
                should have been disabled.

                Fixes problem with ctrl and shift keys getting "stuck"
                (ie like capslock) when pressed in conjunction with <alt>,
                introduced inadvertently at version 3.01.

                Fixes problem with <ctrl> <alt> <del> and <ctrl> <alt>
                <shift> being intercepted.  Now can reboot or remove
                overlying windows in FP as you would expect.

                Added switch (chr(255)) to disable/reenable the entire
                keyboard.  This is useful if you need to define multiple
                ON KEY LABEL statements in FP and user may press one before
                all are set up.

                Added switch (chr(254)) to disable/reenable ctrl-alt-del
                while leaving individual keys functioning as expected.
                10 June, 1990
                first version uploaded to FOXFORUM ON CIS

version .95beta Renamed as KEYBOSS.BIN to indicate further abilities.
                Can redesignate escape as ctrl-w and back again.
                15 july, 1990

version 1.0     changed escape redesignation to alt-0.  Added
                extended keyboard buffer input system. 29 july, 1990

SPECIAL THANKS:

        Jim Kyle (GO CLMFOR) of Computer Language Magazine
forum on CompuServe (CIS) helped with basic interrupt operation and
tipped me to the hook which allows automagic uninstall if user QUITS
without uninstalling/releasing keyboss.

        Chip Rabinowitz (GO CLMFOR) also of CLM Forum on CIS
provided me with the buffer-stuffing code necessary to enable
ALT-Keypad keypresses to generate the ASCII codes after all my
references (and faculties) failed me.

        Guy Scharf (GO CONSULT) acted as main beta tester for
all versions from version 1.5 - 4.0 and offered many suggestions for
improvements.

        Bill Lonborg started it all with his request for a
program to disable the ESCAPE key in a FOXFORUM message.

        Steve Powell came up with idea of re-designating
escape as ctrl-w.  

        Bruce Palmer suggested that alt-0 might be a better
choice for the re-designated key so that ON KEY LABEL routines
wouldn't interfere with regular CTRL-W function.  Can use:

        ON KEY LABEL ALT-0 KEYBOARD CHR(23)
                        or
        ON KEY LABEL ALT-0 CALL KEYBOSS WITH "C" + CHR(17)

        If redesignation of ESCAPE as CTRL-W is desired.

        Mike Reed of CompuSolve, creator of COMET, the background
communications program for "xbase," provided invaluable support in the
development of the KEYBOARD function.


SHAREWARE NOTICE:       This program is NOT free.  Please try it and
test it out as much as you like.  If you use this program in a
business environment or expect to bundle it with your xbase
applications then please contact the author and register.

        Registration fees are as follows:

        Non-commercial use:  FREE

        Unlimited site license for your business location:  $35.00

        Unlimited site license for distribution to infinite sites
with your FP applications:                                  $75.00

        The above licenses are non-transferrable and include free
unlimited upgrade to all future versions of keyboard enhancing .bins
produced by the author.  Due to the variable number of hardware
platforms and FP versions perfect function can NOT be guaranteed
in advance.  Please test the program yourself in the expected
operating environment.  

Please feel free to contact me at the address/phone below.  Evenings
are preferred for phone calls, 7-10 pm, but an answering machine is
on line.  I log on to CompuServe daily.

Home address:                           CIS PPN: 71460,3122
                                                 CIS mail or
John M. Bauman                                   GO FOXFORUM
546 Graham Road
Fort Sam Houston, TX
78234

Home phone:  (512) 225-8242  (Central time zone) 
                
notice:         copyright (c) 1990  john m. bauman  all rights reserved
