home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 11 Util
/
11-Util.zip
/
KLOCK2.ZIP
/
KEYLOCKS.DOC
< prev
next >
Wrap
Text File
|
1992-07-17
|
36KB
|
860 lines
General Information on KeyLocks II, Versions 2.00 and 2.00D
(c) Copyright 1992 Yankee Software, All rights reserved.
Notices
KeyLocks II is offered in both a general release version
and a demonstration version under a license agreement.
Examine the license agreement for the terms and conditions of
the license.
OS/2 and Presentation Manager are registered trademarks
of International Business Machines Corporation. Windows is a
registered trademark of Microsoft Corporation.
Permission is granted to quote portions of this
documentation.
Introduction
KeyLocks II allows the user to configure the state of the
three shift lock keys, num-lock, caps-lock, and scroll-lock,
from the command line, from a batch file, or by invoking
KeyLocks II from a PM program entry. KeyLocks II works
equally well under real DOS, under OS/2's emulation of DOS,
under OS/2 Virtual Boot Machines running a specific version
of DOS, under OS/2 full-screen sessions, and under the OS/2
Presentation Manager. In order to work in all these
environments, it comes as two programs. KeyLocks II for DOS
and OS/2 full-screen (KEYLOCKS.EXE), and KeyLocks II PM
(KEYLPM.EXE).
The program is easy to use. It accepts and acts on seven
parameters:
NUMLOCK
NONUMLOCK
CAPSLOCK
NOCAPSLOCK
SCROLLLOCK
NOSCROLLLOCK
BRIEF
(It makes no different whether the parameters are
written in upper or lower case letters.)
The purposes of the first six parameters are
self-explanatory. NUMLOCK turns on the num-lock key. Most
keyboards have a combination cursor/numeric key pad off to
the right of the main set of keys. When num-lock is on,
those keys produce numeric input for the program that is
running and has the keyboard focus. When num-lock is off,
cursor commands and other functions are sent instead. The
user can change this state by simply pressing the num-lock
key. However, in many cases, it is convenient to be able to
configure a known starting point that will be familiar,
invariant, and uniform. KeyLocks II provides the ability to
configure each of the shift lock keys as either on or off.
In addition, it will leave unmodified the existing state of a
shift lock key if neither the turn-on nor turnoff parameter
is supplied.
When no parameters are supplied to KeyLocks II, it
assumes that the person running it is unfamiliar with the
program and would like some helpful information. As a result
it displays a couple of screens of helpful information. It
also requires the user to hit a key to continue. The BRIEF
parameter turns off or reduces this initial display of
information, and also insures that the user is not prompted
to hit a key to continue.
How to supply parameters to KeyLocks II on the command line
The parameters that control KeyLocks II can be supplied
as command line parameters. There are basically three ways
to supply command line parameters: interactively at the
command line, on the line that invokes the program in a batch
file, or in the parameters field of the Desktop Manager's or
Workplace Shell's program entry.
When typing at the command line, the parameters follow
the name of the program and come before pressing carriage
return (the ENTER key). For example, if you are at a DOS
prompt:
C:>
You can type
keylocks brief capslock
followed by a carriage return (ENTER key) to invoke keylocks,
tell it to be brief in its user output, and turn on the
capslock key. This assumes, of course, that DOS can find the
program KEYLOCKS.EXE somewhere in the path. For more
information on DOS and OS/2 paths, consult your DOS or OS/2
command reference.
- 2 -
Batch files are text (ASCII) files that contain a number
of lines each of which is processed in a manner similar to
the way it would be processed if a user had typed them at the
keyboard. Batch files have extensions of BAT in the case of
DOS and CMD in the case of OS/2. Using a suitable editor or
word processor, you can enter a line in a batch file that
will invoke KeyLocks II with the parameters that you desire
when the batch file is run. For example, in the case of the
STARTUP.CMD batch file which is run automatically by the OS/2
at system start-up, the line
start c:\mydir\keylpm brief numlock capslock
will invoke KeyLocks II PM at system start-up and turn on the
num-lock and caps-lock keys in the PM session. (The example
assumes that the program KEYLPM.EXE has been installed in the
"C:\MYDIR" directory.) For more information on batch files,
consult your DOS or OS/2 command reference.
Finally, in the case of the Presentation Manager, the
program entry has a field where you can enter the parameters
to be passed to KeyLocks II PM. The steps to do this are
explained in the two sections, "Continuing Installation under
the Desktop Manager" and "Continuing Installation under the
Workplace Shell" below.
How to pass parameters to KeyLocks II through an environment
variable
Parameters may be passed to KeyLocks II by way of an
environment variable named "KEYLOCKS". To define the
environment variable, type the following line in your
CONFIG.SYS (OS/2) or AUTOEXEC.BAT (DOS) file:
set KEYLOCKS=brief numlock capslock
Note: use the parameters that suit your needs. Also note:
the environment variable's name "KEYLOCKS" must be in either
all upper case or all lower case letters. Finally note: OS/2
does not maintain a common environment for OS/2 and DOS. The
DOS environment must be set in the AUTOEXEC.BAT file (or some
similar startup file), while the mother environment for OS/2
(which is inherited by all OS/2 sessions) can be set in the
CONFIG.SYS file.
To pass parameters through an environment variable, first
set the KEYLOCKS environment variable to the parameters that
you wish to use as explained above. Then invoke KeyLocks II
without any command line parameters. When the program starts
up, it first looks for its parameters from the command line,
if it does not find any parameters there, it then looks for
its parameters from the environment variable.
- 3 -
Special considerations for older versions of DOS
KeyLocks II may not work properly with DOS versions
earlier than DOS 3.3.
Special considerations for OS/2
OS/2 allows the user to invoke many different sessions.
In general, the OS/2 keyboard driver maintains a different
shift lock state for each session. This means that you may
have the num-lock key on and the caps-lock key off in a DOS
session, while in an OS/2 full-screen session, you have the
num-lock key off and the caps-lock key on. Furthermore, you
may have another OS/2 full-screen session where neither the
num-lock nor the caps-lock key is turned on. And so on.
For this reason, KeyLocks II works on a session by
session basis under OS/2. To configure the shift lock keys
in each session started, run a batch or command file when the
session is started. (See the OS/2 command reference for more
information on how to do this.) Within this batch or command
file, you invoke KEYLOCKS or KEYLPM to configure the
sessions. As explained above, you may use an environment
variable to pass the parameters to KeyLocks II instead of
passing them on the command line.
Special considerations for the Presentation Manager Session
The PM session offers some peculiar challenges to a
program like KeyLocks II. The Presentation Manager retains
in memory the state of the shift lock keys which is updated
whenever the user presses a shift lock key. This memory is
not updated when a program changes the states of the shift
lock keys. The Presentation Manager allows a program to
change this state, but it never forgets the state that was in
effect after the user's last action. The problem arises when
the user switches off to another full-screen session and then
comes back to the Presentation Manager. At this point, the
Presentation Manager restores the state of the shift-lock
keys that it has remembered. This restoration is likely to
undo the changes made by a program like KeyLocks II in the PM
session. Worse yet, the Presentation Manager fails to do a
good job when it restores its remembered state, and as a
result unusual situations can arise, such as having the
num-lock key on but the keyboard's num-lock light off. To
compensate for the Presentation Manager's mucking about,
KeyLocks II PM remains resident after its first invocation to
clean up behind the Presentation Manager when it comes into
- 4 -
the foreground. It performs the cleanup by restoring the
shift lock keys to the state that was last configured either
by a program that has used the KeyLocks II Server application
programming interface, or by the user pressing a shift lock
key. If at some point, you decide to terminate the resident
KeyLocks II PM program, it will restore the keys to the state
that agrees with the Presentation Manager's memory, so that
no unusual situations arise.
Special considerations for Windows sessions under OS/2
If you invoke KeyLocks II from your AUTOEXEC.BAT file,
then when you start any Windows session under OS/2, the
KeyLocks setting used in the AUOTEXEC.BAT will take effect.
To configure different Windows sessions to configure the
shift lock keys differently in different sessions, you will
need to make use of custom batch files to configure each
session.
Demonstration and General Release versions
KeyLocks II is available in two versions. The general
release version is offered for sale under license. The
demonstration version is free and also subject to a license.
There are only two major differences between the general
release version and the demonstration version.
The first major difference is that the demonstration
version has a "nuisance feature" whose purpose is to
encourage you to purchase the real thing after you have had a
chance to test the demonstration version and determine
whether KeyLocks II is useful and meets your requirements.
As explained above, the BRIEF parameter shortens or
suppresses explanatory screens and starts up the program
without requesting user input. In the demonstration version,
the BRIEF parameter is filtered through a random function.
About 25% of the time, the random function will fail the
BRIEF parameter, and when this happens, the program acts just
as if the BRIEF parameter was not present. In the general
release version, the BRIEF parameter is acted on directly and
not filtered through a random function.
A second major difference between the general release
version and the demonstration version is that the dialog box
in the demonstration version of KeyLocks II PM is system
modal, meaning that when it comes up, you must respond to it
before doing anything else. As with the random filtering of
the BRIEF parameter, having a system modal dialog box is a
nuisance. In the general release version of the program, the
dialog boxes of KeyLocks II PM are not system modal.
- 5 -
The minor differences between the two versions are just
textual differences in the display screens or dialog boxes.
Conceptual Overview of the Software Architecture
KeyLocks II consists of four program files. The first
program file (KEYLOCKS.EXE) is KeyLocks II for DOS and OS/2
full-screen. This is a dual-mode program that runs under
both real DOS, OS/2 emulated DOS, OS/2 Virtual Boot Machines
running specific versions of DOS, and OS/2 full-screen
sessions.
The remaining three files, KEYLPM.EXE, KEYLOCK.DLL, and
SNOTICE.SYS are the components of KeyLocks II PM.
KEYLPM.EXE is, in essence, the PM version of
KEYLOCKS.EXE. However, because it is necessary for KeyLocks
II PM to monitor the Presentation Manager and clean up behind
it whenever it comes into the foreground, the first
invocation of KEYLPM.EXE remains resident to perform these
tasks.
KEYLOCK.DLL is the KeyLocks II Server. The KeyLocks II
Sever provides services to two classes of clients: private
clients and public clients. The first invocation of
KEYLPM.EXE is the only private client of the KeyLocks II
Server. KEYLPM.EXE initializes the KeyLocks II Server, uses
it to set the keys, and tells it when to clean up behind the
shell. If this first invocation of KEYLPM.EXE is terminated,
the KeyLocks II Server is de-initialized, and the keyboard is
restored to a state that is compatible with the state
remembered by the Presentation Manager. Any PM or OS/2 text
window program may be a public client of the KeyLocks II
Server. Public clients tell the KeyLocks II Server how to
set the shift-lock keys in the PM session. Public clients
can do this only if KEYLPM.EXE is running and has initialized
the server. See below for more information on the KeyLocks
II Sever application programming interface (API).
SNOTICE.SYS is a device driver that is used by the first
invocation of KEYLPM.EXE to obtain notice of the movement of
the Presentation Manager into the foreground. Since it is
necessary to reset the desired state of the shift lock keys
after the PM shell has moved into the foreground, SNOTICE.SYS
provides efficient and timely notice of this occurrence to
KEYLPM. SNOTICE.SYS is a device driver whose sole purpose is
to pass back various kinds of notices of session changes to
the caller. The caller may be a DOS or OS/2 program. The
programming API to this device driver is not documented.
Anyone who is interested in using this device driver with a
program other than KeyLocks II PM should contact the company.
- 6 -
Special considerations when installing the general release
version of the software on a system where the demonstration
version is installed
Shut down KeyLocks II PM if you have it running, and copy
the files as instructed to the same directories where you
installed the demonstration version. (You will be copying
new files over old files.)
Installation on DOS or OS/2 Systems
KeyLocks II consists of four program files. The first
program file (KEYLOCKS.EXE) is KeyLocks II for DOS and OS/2
full-screen. Copy this file to any convenient directory on
your hard disk or boot floppy. In the examples that follow,
we have assumed that you are using the subdirectory
"C:\MYDIR", but you may use any subdirectory on any drive, as
you wish. Just remember to substitute your name for ours
when following the examples.
Note: normally this would be a directory that is
mentioned in your PATH command for the sessions that
you intend to invoke it from. If this is not the
case, then you must either explicitly tell DOS or
OS/2 the path name of the directory that you are
using, so that it know where to find the program when
you invoke it, or you must make this directory the
default directory before you invoke KEYLOCKS.
For DOS only systems and for use of KeyLocks II in the
DOS sessions of OS/2, you will likely want to alter the
AUTOEXEC.BAT file by adding a line similar to the following:
KEYLOCKS BRIEF CAPSLOCK
Note: use the parameters that are suitable to your needs. If
you are using parameters supplied by setting the environment
variable KEYLOCKS, do not provide parameters in the
AUTOEXEC.BAT. If you installed KEYLOCKS.EXE in a directory
that is not listed in the current PATH or in the default
directory, you must tell DOS where to find the program by
giving a complete description of its location, as in the
following example:
C:\mydir\keylocks brief capslock
This completes installation for using KeyLocks II with
the DOS operating system.
If you are installing KeyLocks II on an OS/2 system, and
you wish to use KeyLocks II to configure OS/2 full-screen
sessions, you will want to create or alter the batch files
- 7 -
that are used to start the OS/2 sessions. Edit these batch
or command files (which have CMD extensions) and insert the
line to invoke KeyLocks II with the parameters that you want.
For example add the line:
C:\mydir\keylocks numlock noscrolllock capslock brief
to invoke the copy of KEYLOCKS.EXE stored in the C:\MYDIR,
turn on the num-lock key, turn off the scroll-lock key, and
turn on the caps-lock key. Again: if you wish to use the
parameters supplied by the environment variable KEYLOCKS, do
not supply command line parameters. For more information on
how to run an assigned batch file when starting a session,
consult your OS/2 command reference. In particular see the
documentation on "CMD" and "START".
If you are installing KeyLocks II on an OS/2 system, and
wish to configure the shift lock keys for the Presentation
Manager session, continue with the steps below.
As explained above, KeyLocks II PM has three program
files. Copy the two files KEYLPM.EXE and SNOTICE.SYS to any
desired subdirectory. For the examples below, we have
assumed that you are copying these files to the following
subdirectory.
C:\MYDIR
When you are following the directions below, substitute the
drive letter and full pathname that you have chosen.
Now look for a directory named
\OS2\DLL
This is often on the C drive, but it may be on a different
drive in your case. Copy KEYLOCK.DLL to this directory.
On the root directory of your boot disk, you will find a
file named CONFIG.SYS. Make a copy of this file to a backup
name, then using a text editor, or a word processor that can
input and output ASCII files (and which will not word wrap or
truncate long lines!) edit CONFIG.SYS file.
You need to add one line to the CONFIG.SYS file. Go to
the end of the file and add the line:
DEVICE=C:\MYDIR\SNOTICE.SYS
Now save the file CONFIG.SYS to disk. Note: if you are
using a word processor, the file must be saved as an ASCII
file. A text editor normally saves all of its files as
ASCII.
To invoke KeyLocks II PM automatically when starting up
- 8 -
the system, there are two strategies that will work. For the
first method, you alter or create a STARTUP.CMD file on the
root directory of the boot drive. This file is automatically
run by the system upon OS/2 start-up. Alter or create the
file by adding the following line with a suitable text editor
or wordprocessor:
START C:\MYDIR\KEYLPM BRIEF NUMLOCK CAPSLOCK
(Use the parameters that suit you, or no parameters at all if
you are using the environment variable.) If you have
implemented this strategy, the installation is now complete.
Shutdown and reboot your machine to make the changes you have
made take effect.
The second strategy involves creating a program entry for
KeyLocks II PM in the Desktop Manager (OS/2 1.3) or Workplace
Shell (OS/2 2.0). The program entry is then marked for
automatic start-up. To implement this strategy, follow the
instruction given in one of the two immediately following
sections, "Continuing the installation on the Desktop
Manager" or "Continuing the installation on the Workplace
Shell".
Continuing the installation on the Desktop Manager (OS/2 1.x)
Go to the Desktop Manager. Select the group to which you
want to add the KeyLock II PM program entry. Select
Program-->New. Fill out the text boxes as follows:
Program title: KeyLocks II PM
Path and file name: C:\MYDIR\KEYLPM.EXE
Parameters: BRIEF NUMLOCK
Working directory:
On the Program Type list box, click on the down arrow to
its right, and select Presentation Manager. If you want the
program to run when the system is started (as you probably
do), click on the Options button. Now go to the "Open when
system is started" selection box and click on it. Click on
the OK button and on the Add button. To change the
parameters or configuration of this program entry, select the
entry and then select from the menu Program-->Properties.
Make the changes then click on the Change button.
The installation of the program is now complete.
Shutdown and reboot the machine to make the changes that you
have made take effect. (If you invoke KeyLocks II PM before
you shut down and reboot, the program will give an error
message saying that it is unable to locate the device driver.
This is because device drivers are loaded only when the
system is started.)
- 9 -
Continuing the installation on the Workplace Shell (OS/2 2.x)
Open the Startup folder located in your System folder.
Open the Templates folder, and select the icon marked
"Program". Holding down the right mouse button, drag this
icon over to the startup folder. This operation will create
a new blank program entry that you will now configure. The
settings for this program entry will automatically be
displayed for you. On the Program page, fill out the
following fields:
Path and file name: C:\MYDIR\KEYLPM.EXE
Parameters: BRIEF ... add other parameters here
Now click on the General page tab and fill out the
following field:
Title: KeyLocks II PM
Now double click on the very small icon in the upper left
corner of the Program settings window. This will close the
Program settings window.
The installation of the program is now complete.
Shutdown and reboot the machine to make the changes that you
have made take effect. (If you invoke KeyLocks II PM before
you shut down and reboot, the program will give an error
message saying that it is unable to locate the device driver.
This is because device drivers are loaded only when the
system is started.)
API for KeyLocks II Server
This section of the documentation is intended for
programmers.
Any OS/2 PM, or OS/2 text window (WINCOMPATIBLE)
application can call the KeyLocks II Server to change the
state of the shift lock keys in the PM session. (OS/2
full-screen programs may also call the KeyLocks II Server to
change the states of the shift lock keys in their session.)
The only requirement is that KEYLPM.EXE be running since the
first invocation of this program initializes the server and
tells it when to clean up behind the shell. KEYLPM.EXE knows
when to ask the server to clean up after the shell because it
receives a notice from the SNOTICE.SYS device driver when the
session that the shell runs in moves to the foreground.
The KeyLocks II Server provides three API entry points
for public clients.
- 10 -
USHORT pascal far KeyLockSet(INT num, INT caps, INT scroll);
This call is made to set the desired state of the shift
lock keys.
num has one of three values:
1 : Turn on the num-lock key
0 : Do not alter the state of the num-lock key
-1 : Turn off the num-lock key
caps has one of three values:
1 : Turn on the caps-lock key
0 : Do not alter the state of the caps-lock key
-1 : Turn off the caps-lock key
scroll has one of three values:
1 : Turn on the scroll-lock key
0 : Do not alter the state of the scroll-lock key
-1 : Turn off the scroll-lock key
The return value will be one of the following:
0 : no problem
KL_ERROR_SYSTEM : Either the DLL or OS/2 is not
performing as expected.
KL_ERROR_BROKEN : The Server has experienced a system
error that has left it in an
unreliable state. No recovery is
possible.
KL_ERROR_SESSION: The Server is being called from a
detached session. Since no
keyboard state is associated with
this session, the call is rejected.
KL_ERROR_NO_INIT: The server has not been
initialized. (KEYLPM.EXE is not
running.)
KL_ERROR_SEM : A system limit on the number of
semaphores in use has been reached.
KL_ERROR_HANDLES: A system limit on the number of
open file handles was reached.
KL_ERROR_TIMEOUT: The server's semaphore was tied up
for longer than 30 seconds.
Note: normally, the server hold its
semaphore for only a few
milliseconds. This error would
likely indicate that the server is
stuck (hung) servicing another
client.
USHORT pascal far KeyLockTidyUp(VOID);
- 11 -
This call forces the state table returned by
WinSetKeyboardStateTable() to agree with the actual state of
the keyboard in the PM session. If you call KeyLockSet() to
change the state of the shift lock keys, you do not need to
make this call.
If, on the other hand, you follow the procedure
recommended in the programming manuals of getting the
keyboard state table, altering it, then restoring it before
your application loses the focus -- three calls in all to
WinSetKeyboardStateTable() -- then you may want to make this
call. A problem can arise if another application makes a
call to KeyLockSet() during the time that your application is
holding the keyboard state table. The keyboard state could
then change without your application receiving notice of this
event. Therefore you would restore a keyboard state table
that is out of sync with the actual state of the keyboard in
the PM session. To avoid this problem, call this function
either after or in place of the call to
WinSetKeyboardStateTable() to restore.
Another method to avoid the problem is to verify by
calling KbdGetStatus() that the keyboard state table that you
are restoring agrees with the keyboard's actual state.
Yet a third, and in many ways better, method to alter
temporarily the shift lock states while your application has
the focus, would be to avoid the calls to
WinSetKeyboardStateTable(), and instead call KbdGetStatus()
to get the current shift states, then call KeyLockSet()
twice, once to alter and once to restore the appropriate
states.
The possible return values are the same as for
KeyLockSet(), with the following exception: KL_ERROR_SESSION
will be returned unless your application is a PM application
or running in a OS/2 text window.
USHORT pascal far KeyLockQStable(VOID);
If an error is received by an application calling a
KeyLocks II Server API entry point, this function may be
called to determine the resulting state of the server.
The return value will be one of the following three:
KL_STABLE : The shift lock states and the shift
key lights are still in sync, and
the server can be expected to
restore the shift lock keys to a
state that is compatible with the
PM Shell if it is de-initialized.
- 12 -
KL_UNSTABLE : The shift lock states and the shift
key light may be out of sync,
however, the next call to any other
KeyLock II Server API can be
expected to restore the proper
relationship between the keys and
the lights if it succeeds.
KL_BROKEN : The lights and the keyboard states
may be out of sync and the server
has arrived at a point where it can
no longer recover.
Additional note: there is no requirement that this
function be called. It is provided for informational
purposes only.
Two files are included for use by programmers when
programming to use the KeyLocks II Server API. KEYLOCKS.H
contains the function declarations and definitions for the
public clients of KeyLocks II Server. KEYLOCK.LIB is the
export library to link with when calling either of the
functions documented.
- 13 -
