OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / sysutils / mf2_keyb / keylocks / keylocks.doc < prev next >

Wrap

Text File | 1992-07-17 | 35.1 KB | 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 -