PC Online 1997 May

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

/ PC Online 1997 May / PCO_5_97.ISO / FilesBBS / OS2 / WCAT21.ARJ / WCAT21.ZIP / watchcat.inf (.txt) < prev next >

Wrap

OS/2 Help File | 1995-11-12 | 415.9 KB | 3,742 lines

ΓòÉΓòÉΓòÉ 1. Title Page ΓòÉΓòÉΓòÉ Welcome to WatchCat 2.1 - The Guardian Angel of OS/2 - ΓòÉΓòÉΓòÉ 2. Overview ΓòÉΓòÉΓòÉ Read more about the following topics: Do I need WatchCat WatchCat is not just a process killer :-) Changes since WatchCat 2.0 What do I have to pay? ΓòÉΓòÉΓòÉ 2.1. Do I need WatchCat? ΓòÉΓòÉΓòÉ WatchCat is a program to recover OS/2 2.x and OS/2 3.x from some kind of hang by killing applications. WatchCat is useful to any OS/2 user in the following situations: The Presentation Manager (PM) is blocked. Due to the single message queue of OS/2 a single ill-behaved PM program might block all PM programs in the system and prevent any program from getting user input. Therefore it is impossible to end the corrupt task or to save data in other programs. You can press Ctrl-ESC but this does not help in all situations. Due to the Full-Screen nature of WatchCat those ill-behaved programs can be killed from within WatchCat. There are several reasons why the PM might hang: - An ill-behaved PM program - An ill-behaved Windows program in a Win-OS/2 session - Erroneous Workplace Shell objects. Even though OS/2 has become much more stable with Version 3, there are still situations where the PM is blocked: - The PM user-interface is blocked because of a system-modal dialog box that cannot be closed. - User input is impossible because of a high priority process or a process that is doing a lot of swapping. Displaying process information in a non-cryptic easy-to-understand way. Learn more about OS/2 and its processes. WatchCat is also interesting to programmers in the following situations: Display all PStat-info about modules, processes, threads, etc. WatchCat periodically updates all this information. It is quick and easy to use without any PM overhead, by using the CuTe technology. Display all WatchCat information on a terminal and control WatchCat even if OS/2 crashed. Open a (windowed) remote shell on the hanging PC. (registered version only). Kill threads or change the priority of threads dynamically. (1st Aid Package only). Disable Ctrl-Alt-Del or use Ctrl-Alt-Del to activate WatchCat (registered version only). We are using WatchCat ourselves many times a day: - View the number of threads in an application. - Do all threads have the correct priority? - View the process hierarchy. Are all child processes started correctly? - Is my program really using the right DLL? Which DLL are used and what path do the DLL have? - Use WatchCat as a task switcher when Ctrl-ESC does not work. - Don't be afraid to use the debugger for critical actions (e.g. breakpoints in the window procedure), most hang-ups can be recovered. - Does my application consume much CPU time? - My application stops. Is it an endless loop or a deadlock? You may use it in special cases for debugging: Send your debugging text to WatchCat to avoid any additional PM message passing. This may be useful in some PM and WPS applications. WatchCat can be extended with its own modules via a DLL and a documented C-API. or via the simple and documented WatchCat C++ window framework. And there are more situations where WatchCat can help - read these anecdotal reports where WatchCat might also help. In contrast to WatchCat 1.x you don't need special hardware to use WatchCat 2.1. You can still use any switches you built for v1.x, but you can also simply activate WatchCat by a user-defined hotkey (default: Ctrl-Alt-W). WatchCat needs a very small amount of CPU-time. You don't see it and you won't notice it. But it is there if you need it. ΓòÉΓòÉΓòÉ <hidden> How WatchCat works ΓòÉΓòÉΓòÉ Most OS/2 users know the situation where the Presentation Manager hangs: No input from keyboard or mouse seems to be possible: WatchCat detects a hotkey sequence even when OS/2 hangs. Just press the hotkey and delete the ill-behaved application. WatchCat is not affected by a hung PM. You can even use WatchCat from a terminal. Without the ill-behaved program OS/2 is stable again. You can continue your work without rebooting. ΓòÉΓòÉΓòÉ <hidden> Two true stories about WatchCat ΓòÉΓòÉΓòÉ The first story was reported by Felix von Normann from Passau, a novice OS/2 user. Here is his true experience: "One day I installed a new text-mode editor which I called e.exe and put it before the OS/2 Standardeditor in the PATH, because I liked it more the the graphical version. A few days later I double-clicked on a READ.ME icon of a program package. Nothing happed, I turned of the computer and forgot the situation (...) When I turned on my computer the next day I noticed that it was significantly slowed down, even no program was visible on the WPS. I activated WatchCat and found out that more than 90% CPU-time was consumed by a process called 'e.exe'. Finally I remembered my double-click on the icon. With WatchCat I found out the Editor e.exe was started by the WPS as a PM-program (first column), what was wrong, because the details view proofed that it was a fullscreen program. After killing the process - thanks to WatchCat - the solution was easy to find: I don't double-click on text-icons any longer." The second story is from one of our users in the north of Germany. He told us: "I was using OS/2 with S3-VGA, 640x480 and a buggy video driver. Sometimes character simply disappeared. After the 3rd repaint a button was labled 'C ce ' instead of 'Cancel'. Activating and leaving WatchCat forced the video driver to completely redraw the whole screen. This trick (activating WatchCat every 10 minutes) helped me to use my system until I found a bug-free (?) driver." As you can see, WatchCat is not just a process killer... ΓòÉΓòÉΓòÉ 2.2. Changes since WatchCat 2.0 ΓòÉΓòÉΓòÉ WatchCat.exe bugs - Monochrome color changed to 0x7 (instead of 0xf) - Using only one semaphore (maybe an unnecessary change, s.b.) - removed uninitialized variable error causing a problem that looks like a dead-lock. - removed bug: maximize, TAB improvements - improved user interface - optimized segment loading - one context switch less on activation new features: - sort ascending, descending - Shutdown (with message box) - Reboot (with message box) - added /DLL /MOUSE, ... - Added context menu to unblock threads - Changed Init of 50-line-mode - DLL searchable via environment variable WCATDLL - sort by structure - kill entire process tree (does it work???) - kill by name - added new DLL: start programs, stdout >> window - improved options menu (added color support, ...) - parameter /RATE:x , 0<=x<=9, set DevDriv timer rate - support for windowed cmd.exe More new features C-A-D package (disable Ctrl-Alt-Del). process manipulation center (disable Ctrl-Alt-Del). Run WatchCat on a remote PC via serial connection ΓòÉΓòÉΓòÉ <hidden> What do I have to pay? ΓòÉΓòÉΓòÉ WatchCat is not free, but we believe that WatchCat is very cheap. For use in business, commercial, government, or institutional environment, you must buy a registered version or a 1st Aid Package. For personal usage you may use the unregistered version. In this case you are highly encouraged to send us a postcard. You're invited to buy a registered version or a 1st Aid Package. Both versions contain more and interesting features than the unregistered version. ΓòÉΓòÉΓòÉ 3. Copyright & more ΓòÉΓòÉΓòÉ Please read this section carefully before using or distributing WatchCat. ΓòÉΓòÉΓòÉ 3.1. Copyright ΓòÉΓòÉΓòÉ WatchCat and all software supplied in the WatchCat package is (c) Copyright 1993-95 by Felix von Normann and Thomas Opheys. All rights reserved. You are invited to distribute the unregistered version WatchCat in the sense of Shareware. This implies that you can sell only the copying service. You cannot sell the program itself without explicit permission. Repackaging the WatchCat archive is not allowed. You can also sell the registered version or the 1st Aid Package This requires our explicit permission and - of course - payment for each sold version. ΓòÉΓòÉΓòÉ 3.2. Disclaimer ΓòÉΓòÉΓòÉ We do not claim to provide error-free software or software that will meet all your requirements. This software is supplied with no warranty, neither expressed nor implied. We disclaim all warranties for any damages included but not limited to incidental or consequential damage caused directly or indirectly by this software. All software is provided AS IS. You may use this program only at your own risk. WatchCat must not be used in states that do not allow the above limitation of liability. ΓòÉΓòÉΓòÉ 3.3. The authors ΓòÉΓòÉΓòÉ WatchCat was written by: For more information refer to section How to contact the authors. ΓòÉΓòÉΓòÉ 3.4. Credits ΓòÉΓòÉΓòÉ Credits go to Will Rose (cwr@crash.cts.com) who was so kind as to read our docs (the previous level) and correct grammar, style, syntax, typos and all the other things where a German can do harm to the English language. Thanks to Jeremy Mathers (pynq@quads.uchicago.edu), Benjamin Stein (benno@liva.in-berlin.de), Mike Morrell (morrellm@seq.oit.osshe.edu), Nicole Greiber (greiber@wrcs2.urz.uni-wuppertal.de), Erich Schulman (acme@use.usit.net), Andrew DeNardo (LRSSPFLD!CHAMPAIGN!DENARDO@lrsmail.attmail.com), Sven Kiesow (kiesow@kirk.fmi.uni-passau.de) and many others for their contributions to WatchCat. THANKS A LOT! ΓòÉΓòÉΓòÉ 4. Payment for WatchCat (changed) ΓòÉΓòÉΓòÉ Topics: Why registering? The unregistered version The registered version The 1st Aid Package prices (outside Germany) Preise (Deutschland) (Nobody seems to have understood the licensing conditions of WatchCat 2.0... We are currently working on an expert system written in Prolog but it is not finished now, so we have rewritten the licensing part to be more precise. We would like to ask you to read the following text carefully. we still think we have a fair offer for you.) ΓòÉΓòÉΓòÉ 4.1. Why registering? ΓòÉΓòÉΓòÉ For use in business, commercial, government, or institutional environment, you must buy (at least) the registered version of WatchCat. (Please note: Using the unregistered Shareware version in one of the listed cases is illegal - except for evaluation purposes). You may also order a specially tailored version (with only the parts you need; special start-up messages; custom-built DLL; ...) This service will not be free. A German version is not planned now, it will be created when there is enough interest. Pre-installed WatchCat All hardware providers with pre-installed OS/2 are encouraged to pre-install WatchCat, too. To do so, you must buy one regular license per PC. Pre-installing the unregisterd Shareware-Version is not allowed. Bundle with other software: Software developers may distribute WatchCat with their software (when using the API or to increase stability). This requires: 1. One registered WatchCat license per copy of your program 2. WatchCat must remain to be a single separate product. Don't integrate WatchCat seamless into your product (you may do so vice versa...) For personal usage you may use the unregistered version permanently. In this case you are strongly invited to write us a (two!) postcard, saying that you are using the program. Of course you can also order the registered version or the 1st Aid Package This has two advantages: You get a lot of additional software and you motivate us to keep up the WatchCat work. Introduction to sending postcards: avoid asking questions like "Do you really want a postcard?", "What shall I write??" or "What picture should the postcard show?" (see the answers by double-clicking on the question) Consider: We both are not working full-time on WatchCat, but we have many ideas for enhancements and new programs. Please don't force us to think it all over and leave our big love, OS/2. If programming for Windows (and this sucker REALLY needs something like WatchCat) is more lucrative than for OS/2... So, write us a postcard now, introduce WatchCat to your office today, convince your boss to buy some licenses and sleep without feeling guilty tonight. Thanks in advance Felix & Thomas ΓòÉΓòÉΓòÉ 4.2. The unregistered version ΓòÉΓòÉΓòÉ The unregistered version of WatchCat may be distributed in the sense of Shareware. It is for private usage or evaluation purposes only. It cantains the following packages: WatchCat (including WatchCat.exe, device driver, alternative activation). Demo of the process manipulation center Demo of remote WatchCat ΓòÉΓòÉΓòÉ 4.3. The registered version ΓòÉΓòÉΓòÉ The registered version contains the following features: WatchCat (including WatchCat.exe, device driver, alternative activation) with the ability of a windowed shell. The C-A-D package remote WatchCat ΓòÉΓòÉΓòÉ 4.4. The 1st Aid Package ΓòÉΓòÉΓòÉ The WatchCat 1st Aid package contains the following features: WatchCat (including WatchCat.exe, device driver, alternative activation) with the ability of a windowed shell. The process manipulation center remote WatchCat with The C-A-D package (with the ability to kill by Hotkey (Ctrl-Alt-K) and to interrupt DOS programs (Ctrl-Alt-Break)). Some DLL sources to make programming for WatchCat easier. In addition you get the following components: program disk A hardware switch (either serial or parallel or game port) which looks like this A printed manual of the online documentation (about 50 pages high quality). ΓòÉΓòÉΓòÉ 4.5. prices ΓòÉΓòÉΓòÉ From Canada and the U.S.A., please use ORDER.US. Thank you. Note: if you don't want to pay in US-Dollars: Convert the amount to your own currency and continue... For special ordering/delivery options contact watchcat@fmi.uni-passau.de (i.e. European customers). price Item Pieces p/pce You get ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Registered version 1 $ 27 WatchCat 2.1 registered 2 $ 24 to you, one standard 3 - 9 $ 20 license, update quarantee 10 - 49 $ 19 and a program disk. 50 - 99 $ 16 100 - 499 $ 12 500 + $ 8 ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 1st Aid Package 1 $ 62 WatchCat 2.1 registered 2 $ 59 to you, license, update 3 - 5 $ 54 guarantee, program disk, 6 + $ 50 support, printed manual, hardware connector ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Printed manual 1 $ 13 Bound and printed manual 2 + $ 12 with superior quality. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Hardware connector 1 $ 27 Ready built hardware 2 $ 24 connector in a housing. 3 + $ 22 ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Update message eMail free We immediately tell you FAX $ 3 when a new version of letter $ 2 WatchCat is available. ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Available ORDERING options: 1. Send your order with a personal check. Please add $8 if the value of your order is $65 or less; for a price above $65, add $16 for money transfer costs. 2. Send your money in cash to us. This doesn't require an additional fee but it is a little unsafe. 3. Give a money order to our account to your bank. This will only be accepted if you pre-pay all money transfer expenses. Available DELIVERY options: 1. eMail. If you want to receive your registered version by eMail, there is no additional fee. NOTE! If you order a manual, connector or 1st Aid Package, email delivery is impossible! :-) 2. If your order is exactly ONE registered version and NOT MORE - no manual, no connector and no 1st Aid Package, add $3. Others add $18. ΓòÉΓòÉΓòÉ 4.6. Preise (Deutschland) ΓòÉΓòÉΓòÉ WatchCat 2.1 Preisliste - nur f╨ær Deutschland 5/95 Artikel Anzahl Preis Inhalt ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Registrierte Version 1 - 9 35 DM Standardlizenz, 10-49 25 DM Updategarantie, 50-99 20 DM Programmdiskette 100-499 15 DM 500+ 10 DM ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 1st Aid Package 1 80 DM Standardlizenz, 2 - 5 70 DM Updategarantie, 5 + 65 DM Handbuch, Hardwarestecker, Programmdiskette ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Handbuch 1 15 DM gebundenes Handbuch (nur bei Abnahme mind. einer Lizenz) ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Hardwarestecker 1 35 DM Ein Hardwarestecker fuer Parallelport, serielle Schnittstelle oder Gameport ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Update- eMail frei Wir benachrichtigen Sie, Benachrichtigung FAX 1 DM sobald eine neue Version Brief 2 DM von WatchCat verfuegbar ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Bestellung senden an: Thomas Opheys Landshuter Str. 105c C40 D-93053 Regensburg Tel.: 0941-76299 ΓòÉΓòÉΓòÉ 5. How to contact the authors ΓòÉΓòÉΓòÉ There are several ways to contact us. To order WatchCat write to: Opheys Electronic, von Normann/Opheys, Landshuter Str. 105c C40, 93053 Regensburg, Germany, watchcat@fmi.uni-passau.de By regular mail: To receive further information or to write us a postcard or letter write to one (or both) of the following addresses: Felix von Normann Thomas Opheys Innstr. 82 Landshuter Str. 105c C40 94036 Passau 93053 Regensburg Germany Germany normann@fmi.uni-passau.de opheys@fmi.uni-passau.de http://www.uni-passau.de/~normann http://www.uni-passau.de/~opheys Send email to: watchcat@fmi.uni-passau.de (for all comments about WatchCat) normann@fmi.uni-passau.de (to write a mail to Felix) opheys@fmi.uni-passau.de (to write a mail to Thomas) World Wide Web: We are currently working on a WWW homepage for WatchCat. You need a WWW browser (if you use OS/2, please note that this program is not part of the OS/2 Warp Bonus Pack, but available freely to all OS/2 users). Select URL http://www.uni-passau.de/~normann/watchcat.html Currently we have links to: - The online documentation in HTML format (for WWW). - A link to Hobbes (where you can get the latest WatchCat package). - Some pages with the latest information about WatchCat. Frequently asked questions that are not part of this documentation will be collected there. ΓòÉΓòÉΓòÉ 6. WatchCat for the impatient user ΓòÉΓòÉΓòÉ After uninstalling previous versions of WatchCat, copy all files into a single, separate directory (e.g. ramdisk, or final WatchCat directory). Now run the install program (install.exe) and follow the instructions, especially select: Easy installation: This options installs WatchCat in your CONFIG.SYS and creates a WPS object on your Workplace Shell. The only way to activate WatchCat is the keyboard. Advanced installation: Select this option if you want to use a switch for LPT, COM, etc, or if you need more than one device. Use this option also if you do not want to install the WPS object. Now installation is ready. The CONFIG.SYS is updated. Reboot. Activate WatchCat (default: Ctrl-Alt-W). Enjoy! ΓòÉΓòÉΓòÉ 7. Installation and configuration of WatchCat ΓòÉΓòÉΓòÉ (If you don't want to read much text, refer to WatchCat for the impatient user.). Before installing WatchCat 2.1 you must deinstall WatchCat 1.x, WatchCat 2.x (if present). We recommend using the installation program to copy the files and update the CONFIG.SYS. Of course, you can also install WatchCat manually. This requires you to include a device driver and a RUN= statement in the CONFIG.SYS file. To get information about which files are needed/not needed, please refer to the section Understanding the files in the WatchCat package.). ΓòÉΓòÉΓòÉ 7.1. Installation procedure ΓòÉΓòÉΓòÉ Topics: Deinstalling WatchCat 1.x Deinstalling WatchCat 2.0 The install program Installing The WPS object Installing WatchCat manually Managing remote WatchCat Uninstalling WatchCat 2.x Installing the process manipulation center Deinstalling the process manipulation center Installing C-A-D Deinstalling C-A-D ΓòÉΓòÉΓòÉ 7.1.1. Deinstalling WatchCat 1.x ΓòÉΓòÉΓòÉ Note: YOU MUST DELETE AND DEREGISTER THE WATCHCAT 1.0/2.x OBJECT FROM THE WORKPLACE SHELL. DO NOT FORGET THIS STEP!!!! If you installed the WPS object of WatchCat 1.x (the stupid cat on your Workplace Shell) please remove it BEFORE installing the new version. First delete the icon by using its context menu or dropping it on the shredder. DON'T FORGET THIS STEP! Then you can deregister the WPS class. Either run the old WatchCat 1.x, once with the parameter deregisterWPS and once with the parameter clearini: [C:\watchcat] watchcat deregisterWPS ... [C:\watchcat] watchcat clearini ... If you already deleted WatchCat 1.x you can use the install program of WatchCat 2.1 to deregister it. Just type: [C:\watchcat] install deregisterWPS Now you are ready to install WatchCat 2.1. ΓòÉΓòÉΓòÉ 7.1.2. Using the install program ΓòÉΓòÉΓòÉ It is very important to uninstall WatchCat 1.x first. It is assumed that you unpacked all files in a certain directory. You can put all the files into the final WatchCat directory or tell the installation program to do so. Then start install from the command line. You first have to choose between the easy installation and the advanced installation. The easy installation procedure will install WatchCat in your CONFIG.SYS, with as many features enabled as possible and default settings. The default to activate WatchCat is to use Ctrl-Alt-W. If you want to activate WatchCat with any other input control, you must choose the advanced installation. Please answer all questions, then in the end the install program will add WatchCat to the CONFIG.SYS. Note: Please note that you can use the install program to install the C-A-D package or the process manipulation center. ΓòÉΓòÉΓòÉ 7.1.3. Installing the WPS object ΓòÉΓòÉΓòÉ A separate installation step for the Workplace Shell object is not required any longer. That is all managed by the install program. ΓòÉΓòÉΓòÉ 7.1.4. Installing WatchCat manually ΓòÉΓòÉΓòÉ WatchCat has the following architecture: ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé WatchCat Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé physical Γöé Γöé device driver Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γöé Hardware Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Therefore you must add the statements below to your CONFIG.SYS. Substitute x:\path\ with the correct path and do not copy the italic text. (You can place these lines somewhere in your CONFIG.SYS). DEVICE=x:\path\watchcat.sys ┬á insert at the end of CONFIG.SYS to install the device driver RUN=x:\path\watchcat.exe ┬á to detach the main program In addition you need to update some variables: (WatchCat will probably not work if you do not set these variables correctly). PATH=...;x:\path\; ┬á let OS/2 find watchcat.exe LIBPATH=...;x:\path\; ┬á let OS/2 find the DLL. BOOKSHELF=...;x:\path\; ┬á let OS/2 find this documentation If you do not want to activate WatchCat with the default hotkey Ctrl-Alt-W, it is necessary to add a parameter to the device driver. The parameters are listed in the next section. ΓòÉΓòÉΓòÉ 7.1.5. Uninstalling WatchCat 2.x ΓòÉΓòÉΓòÉ Currently we don't have a deinstall program. You must deinstall WatchCat manually. To do so please follow these steps. 1. kill WatchCat (This can be done by WatchCat) 2. delete the WPS object (if there) 3. run install deregisterWPS from the commandline 4. remove WatchCat specific entries from your CONFIG.SYS ( RUN=..., DEVICE=..., LIBPATH, PATH, BOOKSHELF ) 5. reboot (!!!) 6. delete all files ΓòÉΓòÉΓòÉ 7.1.6. Managing remote WatchCat ΓòÉΓòÉΓòÉ Using WatchCat from a terminal is very easy: 1. Connect the terminal (in most cases a second PC) and the local PC via a serial cable. Start the terminal program and configure it correctly. 2. Configure the serial port of the local PC with the OS/2 mode command. 3. Now start WatchCat with the parameter /remote. Run it from the command line. Do not detach it. Now you can use WatchCat from either your local PC or from your remote terminal. For technical reasons some key combinations are not possible on a terminal. Therefore other control sequences for closing windows and changing the focus are used on the remote terminal. Please read the built-in documentation for more information. Use WatchCat on your local PC as usual. Note: You can adjust various settings by editing the file serial.cnf (This file is self-explaining). ΓòÉΓòÉΓòÉ 7.1.7. Installing the process manipulation center ΓòÉΓòÉΓòÉ New feature: This is a new feature of the 1st Aid Package of WatchCat 2.1. This package allows you to kill, suspend, resume threads or change the priority of thread in almost all processes. To use process manipulation center the follow these steps: 1. Move these files into the WatchCat directory (if not already there): viocalls.dll newvio.dll pmwin.dll pmwin32.dll 2. Now ensure that the WatchCat-path is the first path in the LIBPATH statement of your config.sys. e.g. change: LIBPATH=.;:\OS2; into LIBPATH=c:\watchcat\;.;c:\os2; 3. Add the statement DEVICE=x:\path\killer.sys to the end of your config.sys 4. reboot ΓòÉΓòÉΓòÉ 7.1.8. Deinstalling the process manipulation center package ΓòÉΓòÉΓòÉ To deinstall the process manipulation center follow these steps: 1. Remove the WatchCat path from the LIBPATH statement of your config.sys. 2. Remove the DEVICE=...killer.sys statement from the config.sys 3. Reboot (!!) 4. Delete the following DLL: viocalls.dll newvio.dll pmwin.dll pmwin32.dll Please delete these files from the WatchCat directory only!! Do not change these files in the \OS2\DLL directory. 5. You can now re-insert the WatchCat path into the LIBPATH statement or you can completely deinstall WatchCat. ΓòÉΓòÉΓòÉ 7.1.9. Installing the C-A-D package ΓòÉΓòÉΓòÉ New feature: The C-A-D package is introduced with the registered version of WatchCat 2.1. You can use the WatchCat install program to install all components of the C-A-D package. 1. Ctrl-Alt-Del feature. a. Add the following statements to the config.sys: DEVICE=x:\path\vwcat.sys RUN=x:\path\wccad.exe b. Add the following statement to the autoexec.bat: x:\path\wccad.exe PATH=...;x:\watchcatpath c. Add the following load statement to the [windows] part of the win.ini load=x:\path\wcwin.exe 2. Desktop shutdown, Shutdown Folder: run instcad from the command line. After installing and rebooting open the desktop settings. (right mouse button on desktop, Settings). Open the page labled "Shutdown". It is recommended to check at least "acknowledge shutdown". After installing try to activate WatchCat with Ctrl-Alt-Del from DOS, Windows, OS/2 Fullscreen, OS/2-PM. Try also to press Ctrl-ESC or Alt-ESC to switch between sessions. If everything works fine, the installation was correct. Please note that the source of the instcad.exe program is delivered also. Programmers may adjust this program to install the new desktop only or to install the shutdown folder only (which is not very useful as on its own...). ΓòÉΓòÉΓòÉ 7.1.10. Deinstalling the C-A-D package ΓòÉΓòÉΓòÉ 1. Ctrl-Alt-Del feature a. Remove the following statements from the config.sys: DEVICE=x:\path\vwcat.sys RUN=x:\path\wccad.exe b. Remove the following statement from the autoexec.bat: x:\path\wccad.exe PATH=...;x:\watchcatpath c. Remove the following load statement from the [windows] part of the win.ini load=x:\path\wcwin.exe 2. Desktop shutdown, Shutdown Folder: run uncad from the command line. Please note that the source of the uncad.exe program is delivered also. Programmers may compile this program on their own. ΓòÉΓòÉΓòÉ 7.2. Understanding the files in the WatchCat package ΓòÉΓòÉΓòÉ The WatchCat package contains the following (or less) files: File task deleteable? ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ readme.txt small overview yes, after reading changes.txt small overview yes install.exe install and deinstall WatchCat yes, after install save to diskette watchcat.sys device driver no WatchCat.exe The program. Executable on OS/2 2.11 and Warp wpcat.dll Workplace Shell object if you have no WPS object watchcat.inf This documentation if you don't need doc wcatwin.dll Window calls, FeelX calls. if you don't need b) FeelX alt. marking wcatdeb.dl_ rename to wcatdeb.dll to use API if you're not a programmer startpgm.dl_ rename to startpgm.dll to use this module if you don't need it tracevio.dl_ rename to tracevio.dll to trace VIO calls. if you don't need it wcat_api.zip unpack to program WatchCat if you're not a programmer wcinfo information tool for trouble shooting yes wccad.exe control C-A-D, intercept hotkeys no, if you use C-A-D wccaddll.dll used by wccad.exe yes, (not recommended) vwcat.sys virtual device driver no, if you use C-A-D wcwin.exe Windows part of C-A-D no, if you use C-A-D wcwindll.dll used by wcein no sdfolder.dll shutdown folder yes, if you don't need it wcdesk.dll extended desktop yes, if you don't need it shutdwn.exe shutdown program yes kill.exe small kill program yes instcad, etc. installation and sources yes killer.sys device driver no, if installed viocalls.dll necessary DLL no, if installed pmwin.dll necessary DLL no, if installed newvio.dll necessary DLL no, if installed pmwin32.dll necessary DLL no, if installed qsize.dll necessary DLL no, if installed ΓòÉΓòÉΓòÉ 7.3. Parameters supported by the device driver ΓòÉΓòÉΓòÉ Topics: General syntax <option> <device> <mask> <hardware> summary Converting WCat 1.x options ΓòÉΓòÉΓòÉ <hidden> General syntax ΓòÉΓòÉΓòÉ DEVICE = ΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇ WATCHCAT.SYS ΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓö¼ΓöÇΓöÇ ΓööΓöÇ <path> ΓöÇΓöÿ Γöé Γö£ΓöÇ <option> ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γöé Γöé ΓööΓöÇ <activation> ΓöÇΓöÿ Γöé ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ <option> : ΓöÇΓöÇΓö¼ΓöÇ /Q ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ Γö£ΓöÇ /mouse ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /nomouse ΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /pm ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /nopm ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /mono ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /color ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /fade ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /nofade ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /remote ΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /noremote ΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /remotepopup Γöñ Γö£ΓöÇ /dll ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /nodll ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ Γö£ΓöÇ /killpmΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓööΓöÇ /nokillpmΓöÇΓöÇΓöÇΓöÇΓöÿ <activation> : ΓöÇΓöÇΓöÇΓöÇ <device> ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇ ΓööΓöÇ : ΓöÇΓöÇ <mask> ΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ ΓööΓöÇ <hardware> ΓöÇΓöÿ The actual values are described in the following sections. ΓòÉΓòÉΓòÉ 7.3.1. <option> ΓòÉΓòÉΓòÉ You may specify the following options for the device driver (they are globally valid for all WatchCat's) or for the program (they are valid for that instance of WatchCat only). option description ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ /Q don't display device driver message on hotkeys /mouse use mouse (default) /nomouse don't use mouse /pm use PM calls (e.g. to get window list) (default) /nopm don't use PM calls /mono don't use colors /color use colors /fade fade in WatchCat screen (default) /nofade no fade in /remote use WatchCat via terminal (registered version only) /noremote don't use WatchCat via terminal (default) /remotepopup let remote WatchCat popup on activation /dll load DLL on start-up (default) /nodll don't use DLLs /killpm kill the PM on a second activation (default) /nokillpm do not kill the PM ΓòÉΓòÉΓòÉ 7.3.2. <device> ΓòÉΓòÉΓòÉ This part is to specify what kind of device you're using. name description activation mechanism(s) default bit mask default hardware ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ KEYB keyboard (key/key combination) Ctrl-Alt-W KEYB (Keyboard) GAME game port (joystick or switch) any joystick button GAME (Game Port) COM1 serial port 1 (switch) DCD,RI,DSR or CTS line COM (serial) COM2 serial port 2 (switch) as above as above COM3 serial port 3 (switch) as above as above COM4 serial port 4 (switch) as above as above LPT1 parallel port 1 (switch) BUSY,ACK,PEND,SEL,ERROR LPT (parallel) LPT2 parallel port 2 (switch) as above as above XXXX user device (any input) any bit of the port USER (user device) ΓòÉΓòÉΓòÉ 7.3.3. <mask> ΓòÉΓòÉΓòÉ Defines which input lines/port bits of the given device may be used to accept a WatchCat activation. Note that the mask byte must be hexadecimal, and exactly two characters long. Example: "F0" (upper four bits will be used). For certain devices, there are aliases for common bit masks: dev:mask description ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ GAME:JA Joystick A, any button (J1 also works) GAME:JB Joystick B, any button (J2 also works) GAME:JA1 Joystick A, button 1 GAME:JA2 Joystick A, button 2 GAME:JB1 Joystick B, button 1 GAME:JB2 Joystick B, button 2 COMx:DCD COMx, Data Carrier Detect line COMx:RI COMx, Ring Indicator line COMx:DSR COMx, Data Set Ready line COMx:CTS COMx, Clear To Send line LPTx:BUSY LPTx, BUSY line (BSY also works) LPTx:ACK LPTx, ACK (Acknowledge) line LPTx:PEND LPTx, Paper End line LPTx:SEL LPTx, Selected line LPTx:ERR LPTx, Error line (ERROR also works) xxxx:ALL all bits of the device For the KEYB device, a bit mask isn't useful. You can specify a make-code of a key instead; but normally, you use one of the following key aliases: F10, F11, F12, A, B, C, ..., X, Y, Z In addition, you can use CTRL, ALT or SHIFT or any combination of two of these three keys with the activation key: S-<key> SHIFT+<key> C-<key> CTRL+<key> A-<key> ALT+<key> CA-<key> CTRL+ALT+<key> CS-<key> CTRL+SHIFT+<key> AC-<key> ALT+CTRL+<key> AS-<key> ALT+SHIFT+<key> SC-<key> SHIFT+CTRL+<key> SA-<key> SHIFT+ALT+<key> Examples: parameter to activate WatchCat, press ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ KEYB:F12 CTRL+ALT+W KEYB:S-F11 SHIFT+F11 KEYB:CA-C CTRL+ALT+C You should not use F10 or the A...Z keys without at least CTRL and/or ALT because some programs might need these keys. Note: Depending on your keyboard hardware, it might not be possible to press several keys simultaneously. ΓòÉΓòÉΓòÉ 7.3.4. <hardware> ΓòÉΓòÉΓòÉ Define of which hardware type the device is. The following names for hardware types are available: name hardware type ΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ KEYB Keyboard GAME Game Port COM serial COM Port LPT parallel LPT Port USER user device For all standard device names like LPT1, KEYB, COM2, GAME, ... <hardware> is determined automatically. Only when <hardware> is a port address, you have to tell the device driver what kind of hardware is to be expected at this port address. KEYB - Keyboard The keyboard can be used to activate WatchCat. Btw. this also works when the keyboard seems to be "dead" or if a PM session doesn't respond to the keyboard. Currently, you can use F10, F11, F12 or A..Z keys together with any combination of one or two shift keys (CTRL,ALT,SHIFT). The defaults for KEYB are: 0060:CA-W:KEYB, that is: The keyboard read data port address hex 60 is used. CTRL+ALT+W is the default key to activate WatchCat. Internally, the port address of a KEYB device is discarded. So anything like XXXX:...:KEYB is useless because XXXX will be replaced with 0060. This isn't a problem (or are there keyboard controllers with port address<>hex 60?) If one or two additional keys (SHIFT, CTRL or ALT) are to be pressed, WatchCat looks for the make codes of all two (three) keys and activates if at least one break code of these keys is recognized. Internally, the port address of a KEYB/PKEY device is discarded. So anything like XXXX:...:KEYB is useless because XXXX will be replaced with 0060. This isn't a problem (or are there keyboard controllers with port address<>hex 60?) GAME - Game Port A joystick or a special connector on a game port can be used to activate WatchCat. The defaults for GAME are: 0201:F0:GAME, that is: The game port read data address hex 201 is used. A standard game port supports max. two joysticks with two buttons each. Bit mask hex F0 means that any of the four buttons may activate WatchCat. The meanings of the bits are: bit mask description ΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 0-3 -- X/Y positions; don't use them (confuses WatchCat) 4 10 Joystick A, button 1 5 20 Joystick A, button 2 6 40 Joystick B, button 1 7 80 Joystick B, button 2 COM - Serial Port A serial COMx port can be used to activate WatchCat, in conjunction with a special connector/switch. The defaults for COM are: <base>:F0:COM, that is: <base> is the COMx port's base port address: port base port For a COM port with a different base port ΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ address XXXX, use XXXX:F0:COM COM1 03F8 COM2 02F8 COM3 03E8 COM4 02E8 WatchCat sets the lower two bits of the COM port's MODEM CONTROL Register to 1. This register has the address of BASE+4. Setting these bits raises the COMx output lines RTS and DTR to +12V, providing +12V for the connector/switch as a logical high source. WatchCat inputs from the MODEM STATUS REGISTER which has the port address of BASE+6. Only the upper four bits are significant here, hence the bit mask hex F0. The meanings of the bits are: bit mask description ΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 0-3 -- toggle bits; don't use them (confuses WatchCat) 4 10 CTS (Clear To Send) line 5 20 DSR (Data Set Ready) line 6 40 RI (Ring Indicator) line 7 80 DCD (Data Carrier Detect) line LPT - Parallel Port A parallel LPTx port can be used to activate WatchCat, in conjunction with a special connector/switch. The defaults for LPT are: <base>:F8:LPT, that is: <base> is the LPTx port's base port address: port base port For a LPT port with a different base port ΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ address XXXX, use XXXX:F8:LPT LPT1 0378 LPT2 0278 WatchCat sets all eight bits of the parallel port's DATA OUT register, which can be found at the device's base port address. This outputs eight logical high lines which can be used to drive some electronics or provide a logical true source (+5V). WatchCat reads from the STATUS IN REGISTER which has the port address of BASE+1. Only the upper five bits are significant here, hence the bit mask hex F8. The meanings of the bits are: bit mask description ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 0-2 -- reserved; don't use them (may confuse WatchCat) 3 08 ERR (Error) line 4 10 SEL (Selected) line 5 20 PEND (Paper End) line 6 40 ACK (Acknowledge) line 7 80 BUSY (Busy) line USER - User Device Any device with a port address that reflects the electrical high/low state of a switch or other input mechanism can be used to activate WatchCat. The defaults for USER are: XXXX:FF:USER, that is: The port address XXXX is given by you. Mask hex FF enables all bits of the device's input byte. The meanings of the bits depend on the kind of device. Remark: GAME is equivalent to 0201:F0:USER Example: If you have a non-standard COM5 serial device at port address hex 3D8, use DEVICE=xxx\WATCHCAT.SYS 03D8:ALL:COM ΓòÉΓòÉΓòÉ 7.3.5. Summary ΓòÉΓòÉΓòÉ You need one parameter for each device that you want to use to activate WatchCat. Each parameter has the form: x or x:y or x:y:z. Examples: parameter(s) activate WatchCat with... ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ KEYB GAME CTRL+ALT+W key or any joystick button KEYB:CA-W CTRL+ALT+W key combination KEYB KEYB:F11 F11 or CTRL+ALT+W key GAME:JA2 button 2 of joystick A LPT2:BUSY BUSY line of LPT2 LPT1 LPT2 any input line of LPT1 and LPT2 COM1 COM2 COM3 COM4 any input line of any COM port 03D8:DCD:COM Data Carrier Detect line of a non-standard COM port at port address hex 3D8 01B1:ALL:USER any input line of port 1B of a 8255 chip with base address 01B0 ΓòÉΓòÉΓòÉ 7.3.6. Converting WatchCat 1.x options ΓòÉΓòÉΓòÉ The following table compares all WatchCat 1.x switches and the new switches. old parameter new parameter parameter for ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ /1 LPT1 watchcat.sys /2 LPT2 watchcat.sys /I=P,B P:B:hw-type watchcat.sys /G GAME watchcat.sys /GA GALL watchcat.sys /C1 COM1 watchcat.sys /C2 COM2 watchcat.sys /C3 COM3 watchcat.sys /C4 COM4 watchcat.sys /Bx GALL watchcat.sys /T not needed any longer /A menu(Options/Options...) (program) /P menu(Options/Options) (program) /D menu(Options/Options) (program) /M /NOCOLOR watchcat.sys or watchcat.exe menu(Options/Options) (program) /S:x menu(Options/Options) (program) /on /off /toggle WPS object (context menu) WPS object (right mouse button) exit not needed any longer shadow not needed any longer registerWPS installation program deregisterWPS deregisterWPS installation program clearini (automatically) ΓòÉΓòÉΓòÉ 7.4. How to build a connector ΓòÉΓòÉΓòÉ You don't have to build a connector. WatchCat now supports the keyboard, too. If you do not want to use the keyboard, you can also use a switch for the parallel port or the serial port. Another way of activating WatchCat is to use a joystick. ΓòÉΓòÉΓòÉ 7.4.1. Connecting with the parallel port ΓòÉΓòÉΓòÉ It's so simple... Just go out and buy a 25-pin male SUB-D connector that fits to your parallel port, and a single-pole double-throw (SPDT) switch. The switch looks like this: In the position shown pins 2 and 3 are connected. Connect the following pins: switch connector DB-25 1 <- 2 (DATA 0 signal, output) used as logical HIGH 2 -> 11 (BUSY signal, input) used to input the state 3 <- 19 (GROUND) used as logical LOW The following picture gives an overview how to connect for these situations: You might also want to use another kind of switch: one that simply opens and closes one connection. It's just like the one that is used as a Turbo Button in your computer case, i.e. if you don't use your Turbo Button you can use it as the activation switch for WatchCat. Get a switch that stays in the position in which you put it. You can use one like your case's Reset Button, but you might have to hold it down for a while before WatchCat recognizes it. You will also need one 4.7 kOhm resistor. In the picture shown both pins are connected when the button is pressed: Connect one end of the resistor to pin 11, the other end to pin 19 of the parallel port connector. Pin 11 is also connected to one pin of the switch. The other pin of the switch is connected to pin 2 of the parallel port. The following picture gives an overview of how to connect for these situations: ΓòÉΓòÉΓòÉ 7.4.2. Connecting with a serial COMx port ΓòÉΓòÉΓòÉ The same two kinds of connectors (as described in the previous section) can be used here, too. Get a 25-pin or 9-pin female connector for the serial port. For the first type of switch (SPDT), connect the following pins: 25-pin 9-pin connector on COMx 1 <- 20 1 <- 4 (+12V DC output) used as logical HIGH 2 -> 22 2 -> 9 (RI) used to input the state 3 <- 7 3 <- 5 (GROUND) used as logical LOW For the second type of switch: (Turbo Button...): Connect one end of the resistor to pin 22 (25 pin)/9 (9 pin), the other end to pin 7/5 of the COMx port connector. Pin 22/9 is also connected to one pin of the switch. The other pin of the switch is connected to pin 20/4 of the serial port. Note that here the resistor has to be around 12kOhm. ΓòÉΓòÉΓòÉ 7.4.3. connecting with game port ΓòÉΓòÉΓòÉ The same two kinds of connectors can be used here, too. Get a 15-pin male connector for the game port. For the first type of switch (SPDT), connect the following pins: switch connector DB-15 (game port) 1 <- 1 (+5V DC output) used as logical HIGH 2 -> XX (fire button, input) used to input the state 3 <- 4 (GROUND) used as logical LOW Where XX equals 2 for joystick A, button 1 7 joystick A, button 2 10 joystick B, button 1 <- recommended 14 joystick B, button 2 For the second type of switch: (Turbo Button...): Connect one end of the resistor to pin XX, the other end to pin 4 of the game port connector. Pin XX is also connected to one pin of the switch. The other pin of the switch is connected to pin 1 of the game port. Note that here the resistor has to be 4,7kOhm. For the game port, you should know that EVERY time you press (and hold) one joystick's fire button, WatchCat is activated. We only say this because some people are said to play games under OS/2... In this case we recommend to use one of joystick B's buttons as the WatchCat switch (or build a connector on the game port that uses the corresponding pin). ΓòÉΓòÉΓòÉ 7.5. Configuring WatchCat ΓòÉΓòÉΓòÉ Configuring WatchCat has become easier. You can use the program itself to do so. If you change any settings (sort, etc.) through a menu point, this parameter is changed until the next start of WatchCat only. If you want to change a parameter persistently (over boot time) chose Options ... from the Options menu. This window looks similar to this: ΓòöΓòíΓûáΓò₧ΓòÉΓòíOptionsΓò₧ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòíΓò₧Γòù ΓòæStart-up windows: Γòæ Γòæ [ ] Proc-info [ ] Threads [ ] Libraries Γòæ Γòæ [ ] Semaphores [ ] Shared Mem Γòæ Γòæ ( ) Modules () Processes ( ) PM Γòæ Γòæ Γòæ ΓòæSort: [ ] invers sorting Γòæ Γòæ Modules: ( ) type ( ) name ( ) pid () structure Γòæ Γòæ Processes: ( ) type ( ) name ( ) pid () structure Γòæ Γòæ PM-Processes: ( ) type ( ) name ( ) pid () structure Γòæ Γòæ Γòæ ΓòæOther: Γòæ Γòæ path: ( ) full () names only Γòæ Γòæ lines: () 25 ( ) 43 ( ) 50 Γòæ Γòæ color: () color ( ) mono Γòæ Γòæ Γòæ ΓòæColor: Γòæ Γòæ [Frame ] [white ] on [dark blue ] Γòæ Γòæ Γòæ Γòæ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ Γòæ Γòæ Γöé Save Γöé Γöé Change Γöé Γöé Cancel Γöé Γòæ Γòæ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ Γòæ ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥ Change anything that requires to be changed... If you select Save, all Settings will be saved and restored the next time WatchCat is started. If you select Change, all system parameters are changed, but they are not saved. Last but not least, if you select Cancel, the window is closed without any action. The parameters are saved in a file called watchcat.ini. This file is not an OS/2-PM standard ini-file. It is not required that this file exists. If the file does not exist, WatchCat uses the default values. If you have any problems because you changed parameters the wrong way, just delete this file. (It is placed in the directory where the device driver is installed). As you can see, there are three major sections: Start-up windows: You can select between one and three windows that should be opened automatically on program start. You can also decide whether the default view of the main window is a process list, a complete module list or just the PM-programs. Sort: For any of these three types, you can select a sort criterion. You can sort by module name, module type, process id or structure. In the last section you can decide whether all module names should be displayed with full path, how many lines you want to have and whether you need color or not. ΓòÉΓòÉΓòÉ 7.6. Using the WPS object ΓòÉΓòÉΓòÉ This chapter describes how to use the Workplace Shell object: The context menu The "Option" page The "Hotkey" page The "Window" page Note: The WatchCat object allows the user to activate WatchCat and to change some global settings. WatchCat is started by the CONFIG.SYS. Therefore there is no need to put this object into the start-up folder. Note: In contrast to WatchCat 1.x, settings like sort, ... can be done from the WatchCat program (not the object). ΓòÉΓòÉΓòÉ 7.6.1. The context menu ΓòÉΓòÉΓòÉ The context menu of WatchCat looks like this: There are two views for WatchCat. Select them by Open. Either you can activate a detached version of WatchCat (which is started by the CONFIG.SYS) or you can start a new windowed instance on the Workplace Shell. (The default can be changed on the Settings window page.) If you need help, click on WatchCat in the Help menu. This will load this online documentation. The last menu point allows the user to temporarily switch WatchCat on/off. The current state is represented by the icon (you try it...). ΓòÉΓòÉΓòÉ 7.6.2. The "Options" page ΓòÉΓòÉΓòÉ The Options page looks like this: This page allows the user to switch on or off a device specified in the CONFIG.SYS. In the case above the driver watchcat.sys was called with the parameter KEYB (or without any parameter). Therefore you can turn on or off activating WatchCat by the keyboard. All other devices (in this case Game, LPT, COM) are not selectable (disabled). Note: Per default (if you selected easy installation) only the keyboard can be used to activated WatchCat. Therefore only the keyboard can be turned on or off. All other items are not selectable (disabled). ΓòÉΓòÉΓòÉ 7.6.3. The "Hotkey" page ΓòÉΓòÉΓòÉ The Hotkey page looks like this: This page does not appear if you have not selected hotkeys in the CONFIG.SYS. You can easily change the hotkey here (e.g. if you have compatibility problems with other programs). If you have problems to activate WatchCat via device driver (this may happen in case of a bus mouse, or with the Notebook APM), you can turn off "use device driver" (like above). This selection does not employ the driver, which may solve some problems. On the other hand, there may be situations where WatchCat does not pop up when it is not activated by the driver. When turning off the driver, it is also impossible to activate WatchCat from DOS or Windows. Note: When turning off the driver, the line RUN=x:\watchcat\wccad.exe must be found in the CONFIG.SYS which is not the default. Instead the install program inserts a REMed line. So you must remove the "REM". Note: When WatchCat is activated via the driver, the parameters can be changed "live". When WatchCat is activated by wccad, it is necessary to reboot. Note: WatchCat will "remember" the changed Hotkey after rebooting only if you did not specify a hotkey in the config.sys (which is the default). It is recommended to use the driver watchcat.sys without any parameter, if possible. ΓòÉΓòÉΓòÉ 7.6.4. The "Window" page ΓòÉΓòÉΓòÉ The Window page looks like this: Select a default view here. A double-click on the WatchCat object will either activate a detached version of WatchCat or will start a windowed version depending on your choice here. This is the only boot persistent choice. (It will also be saved by DeskMan/2). In the above case, a double-click on the WatchCat item would start a second instance of WatchCat in a window. ΓòÉΓòÉΓòÉ 8. Activating WatchCat ΓòÉΓòÉΓòÉ The way you activate WatchCat depends on your configuration. If you have chosen the default configuration, simply press Ctrl-Alt-W to activate the program. Note: If you do not want to use a hotkey, you can also build a simple switch for the parallel port or the serial port, or activate WatchCat by a joystick The monitor is switched to text mode and WatchCat appears. Use the cursor keys or the mouse to select a process or module. If you want to kill an application, press k. To switch to a process (if possible), press Enter. To open a shell, press space. To get a context menu, press the right mouse button. You can also select items from the main menu. New feature: When activating WatchCat a second time before it pops up, the pmshell is killed. This helps WatchCat to popup in some situations. Also on a second activation the C-A-D feature (if installed) of the registered version is disabled, so Ctrl-Alt-Del results into regular booting. Note: Users of a bus mouse may have a "jumping mouse pointer" when activating WatchCat via the driver. Users of a APM-Notebook may find out that their notebook does not go into sleeping mode. In both cases it may be useful to activate WatchCat in another way. See information about the WPS object for more information. ΓòÉΓòÉΓòÉ 9. Understanding WatchCat ΓòÉΓòÉΓòÉ The following sections explain how to use WatchCat and how to navigate through the supplied information. ΓòÉΓòÉΓòÉ 9.1. The WatchCat package ΓòÉΓòÉΓòÉ This section explains how to use WatchCat (the main package). ΓòÉΓòÉΓòÉ 9.1.1. Using WatchCat ΓòÉΓòÉΓòÉ The usage of WatchCat is very similar to PM. You can use either the mouse or the keyboard to navigate through the windows. The main menu is at the top of the screen. A status line is visible at the bottom. The rest of the screen is filled with information windows. You can have between 1 and 4 windows visible at the same time. The main difference between the way to use WatchCat and the way to use (native) PM is that you activate a window by just moving the mouse onto it. You don't have to click explicitly on it. (BTW: This is the way of activating windows when you're using FeelX ...) The active window has a double border, while all other windows have a single border. The main idea is that there is one "main" window (this is the process or module window). All other windows show information related to one item of the main window. As a consequence, the process window cannot be closed. You can select a process / module by using the mouse or keyboard. The information in any other (most) windows depend on this selection! For example the Library window does not list all the libraries in the system but only those that are used by the current selected process. Note: All windows have a selection bar but only the selection in the process / module list has a meaning. The other windows have a selection bar only for easier usage. To learn how to use WatchCat, just play around. Note: It is not dangerous to play around with WatchCat. All you need to know is that "K" kills a program, "Enter" switches to the selected program if possible, "ESC" leaves the WatchCat screen (but does not end WatchCat). ΓòÉΓòÉΓòÉ 9.1.2. The main menu ΓòÉΓòÉΓòÉ The first menu item (called Info) can be used to select what kind of information is displayed. The topmost menu item affects the information in the main window. You can view either all modules in the system (these are Device Drivers, DLL, Dos and OS/2 programs, ...) or only the processes (in fact programs) or just the PM-programs (most often responsible for system hangups). The following items in the menu Info open new windows with additional information about the currently selected process. The Action menu allows special actions. You can open a shell with the first menu point. The second menu point forces WatchCat to redraw the entire screen and update the information. You can kill a process with the third menu item. Sending WM_QUIT does make sense only for PM programs. Sending WM_QUIT terminates the PM program, but not with as much brutality as killing the application. If this menu item does not work, you must kill the application. The Action menu now supports a windowed command shell (Demo in the unregistered version), and an interface to the process manipulation center (menu item "enhanced kill"). You can also shutdown the system from WatchCat or just reboot. The system shutdown will flush all buffers. There is a new menu item called "Kill all". Use this menu item to kill by name. (E.g. select cmd.exe and use this item to kill all cmd.exe) The Options menu lets you change a lot of settings. Please note that it is necessary to select options via the menu item Options ... to save them permanently. The Add-On menu contents depend on the WatchCat special function DLL. You can easily write your own WatchCat module. Any window created with an external DLL is listed here. If you forget something about keys and usage, select Help to get help. Note: WatchCat does not support overlaying windows. This restriction implies that the windows are not updated while a menu is visible. ΓòÉΓòÉΓòÉ 9.1.3. The "Process list" window ΓòÉΓòÉΓòÉ This is the most important window. This window lists all processes or all modules currently loaded / running in the system. ΓòöΓòÉ[Process list]ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉ[]Γòù ΓòæMOD TYPE PID CPU NAME Γòæ ΓòæΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇ Γòæ Γòæprg PM 12 83% OS2CHESS.EXE (OS/2 Γòæprg PM 15 PULSE.EXE Γûæ Γòæprg Vio 16 CMD.EXE (WatchCat.Γûæ Γòæprg Vio 19 CMD.EXE (T.EXE) Γûô Γòæprg Vio 1A CMD.EXE (CMD.EXE) Γûæ Γòæprg PM 1E VIEWDOC.EXE (Infor ΓòÜΓûôΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓò¥ The MOD column gives the type of the module: prg means program, while mod means any other module. The TYPE column gives more information about the module type. Currently the following types are supported: BaseDev - base device driver, Dev - physical device driver, VDev - virtual device driver, IFS - installable file system, DLL - Dynamic link library, Font - font, VDM - virtual DOS machine, detach - detached process, FS - full screen OS/2 program, Vio - windowed program, PM - Presentation Manager program. The PID column represents the process id of the module in hexadecimal notation. This id is available only for processes. The CPU column gives information about the relative CPU usage by all processes. This is not an exact value, but an estimation. Please note that this value is relative. It may look like WatchCat is very CPU-intensive. This is not true. If WatchCat is the only thing running, it is trivial that it alone uses the CPU. Try to run pulse and you'll see that pulse will get much more CPU time than WatchCat itself. The Name column displays the name and optionally the path of the module. Since DOS is more or less only a program loader it cannot provide information about processes, etc. Of course the virtual DOS machines inherit this problem. Therefore an OS/2 process like WatchCat can get the information concerning a virtual DOS machine. But it is impossible (except with a lot of technical tricks) to get information about the programs running in the DOS session. To provide more information about the DOS session than just "VDM", WatchCat tries to extract the window title of the VDM. This might be a hint about what program is running in the VDM. Getting the window name is not a CPU-trivial task for WatchCat. Therefore this information is updated very, very rarely. ΓòÉΓòÉΓòÉ 9.1.4. The Process info - window ΓòÉΓòÉΓòÉ This window provides a little more detailed information about a process. We believe this is self-explanatory. Γòö[Γûá]ΓòÉ[Process details]ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉ[]Γòù Γòæpath: G:\OS2\ Γòæ Γòæname: CMD.EXE Γòæ ΓòæProcess id: 19 Γòæ ΓòæParent pid: 5 Γòæ ΓòæSession: 27 Γòæ Γòæhandle: 0448 Γòæ ΓòæStatus: running Γòæ Γòætype: Windowable (32 bit) Γòæ Γòæ Γòæ ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥ ΓòÉΓòÉΓòÉ 9.1.5. The Threads window ΓòÉΓòÉΓòÉ Γòö[Γûá]ΓòÉ[Threads]ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉ[]Γòù Γòæ ID PRIO STATUS BLOCKID Γòæ ΓòæΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ Γòæ Γòæ 1 200 blocked fffe0a4e Γòæ Γòæ 2 300 running fff7c2db Γòæ Γòæ 3 200 blocked 62800ee Γòæ Γòæ 4 301 blocked fffe0a6e Γòæ ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥ The ID column lists the thread ID. The PRIO column shows the priority of a thread. This value is given in hex. The priorities have the following meaning: PRIO Explanation ΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ 1xx low priority 2xx normal priority 4xx foreground server 3xx time critical The STATUS column gives information about the thread's state. A thread can be running (but there is only one WatchCat thread running when this info is displayed...), be blocked (then the BLOCKID column gives additional information), a thread can also be ready (this means that the thread is not waiting but will be running as soon as it gets CPU time). If a thread is frozen, then the application is loaded with the preload-feature of OS/2 (or it is thread is suspended). Pressing the right mouse button (or Shift F1O) displays a thread context menu. Use it to unblock any thread. This might be useful in some situations. Please be careful, because it might damage the application. New feature: With any version of WatchCat you can unblock a thread via a thread context menu. This will resume the thread and may be useful in certain situations of testing. New feature: With the 1st Aid package of WatchCat you have the process manipulation center. For PM applications and many windowed programs each thread has an extended context menu where you can simply kill, suspend or resume any thread or even change its priority!! (This is part of the registered version only.) of testing. ΓòÉΓòÉΓòÉ 9.1.6. The Libraries window ΓòÉΓòÉΓòÉ Γòö[Γûá]ΓòÉ[Dynamic Link Libraries]ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉ[]Γòù Γòæmod DLL(32) DOSCALL1.DLL Γòæ Γòæmod DLL(32) KBDCALLS.DLL Γòæ Γòæmod DLL(32) MOUCALLS.DLL Γòæ Γòæmod DLL(32) MSG.DLL Γòæ Γòæmod DLL(32) NLS.DLL Γòæ Γòæmod DLL(32) VIOCALLS.DLL Γòæ ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥ The library window just lists all the dynamic link libraries (DLL) used by this process. Please note that this list is directly associated with the currently selected process. ΓòÉΓòÉΓòÉ 9.1.7. The Semaphores window ΓòÉΓòÉΓòÉ Γòö[Γûá]ΓòÉ[Semaphores]ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉ[]Γòù ΓòæNAME INDEX REF REQ FLΓòæ ΓòæΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇ ΓöÇΓöÇΓòæ Γòæ\SEM\LKNED001.SEM 53AC 1 0 0 Γòæ\SEM\LKNED002.SEM 53B2 1 0 0 Γûæ Γòæ\SEM\LKNED003.SEM 53B8 1 0 0 Γûæ Γòæ\SEM\PMHDERR.SEM 53CA 1 0 2 Γûæ Γòæ\SEM\SMGCONT.SEM 53BE 2 0 0 Γûæ Γòæ\SEM\VIOPOPUP 539A 19 0 0 Γûô Γòæ\SEM\VIOPRTSC 53A0 16 0 8 ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥ This window has the least information value. It lists all 16-bit semaphores that are used by the current selected process. ΓòÉΓòÉΓòÉ 9.1.8. Shared Memory window ΓòÉΓòÉΓòÉ Γòö[Γûá]ΓòÉ[Shared Memory]ΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉ[]Γòù ΓòæNAME SIZE SEL Γòæ ΓòæΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇ Γòæ ΓòæPMDRAG.MEM : 4096B 960FΓòæ ΓòæPMGLOBAL.MEM : 4096B 961FΓòæ ΓòæPULSECTL : 48K 893FΓòæ Γòæ Γòæ Γòæ Γòæ Γòæ Γòæ Γòæ Γòæ ΓòÜΓûôΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓûæΓò¥ This window lists all shared memory segments used by a process. It also shows the size of the memory block, the selector and the handle. ΓòÉΓòÉΓòÉ 9.2. The process manipulation center ΓòÉΓòÉΓòÉ New feature: This is a new feature of the 1st Aid Package of WatchCat 2.1. After installing this package there are additional entries in the context menu of most processes and threads. processes: 1. DosExit. This aborts a process in an orderly manner. 2. Breakpoint. Choose this menu point to kill a process. 3. Suspend process. This halts a process. 4. Remove embedded thread. This choice removes the embedded thread. These options are no longer available after this choice. threads: 1. Kill thread. Kill a certain thread. 2. Change priority. Change the priority of a process. 3. Suspend/Resume thread. Suspend or resume a thread. In addition this package increases the size of the message queue to 100 per queue. This is a powerful feature, but may hang the PM or cause a deadlock. Do not use this feature until you're absolutely sure what you are doing. ΓòÉΓòÉΓòÉ 9.3. Using remote WatchCat ΓòÉΓòÉΓòÉ This section explains how to use WatchCat. After correct installation, simply start WatchCat with the parameter /remote. You need a serial connection between two PC or a PC and a terminal. You can see WatchCat running on both, the local PC and the terminal. You can use WatchCat from the terminal. ΓòÉΓòÉΓòÉ 9.4. Activate remote WatchCat ΓòÉΓòÉΓòÉ Run WatchCat with the parameter /remotepopup. Now activate WatchCat on the local PC and use the terminal to view information or to kill a certain process, change the priority, etc. ΓòÉΓòÉΓòÉ 9.5. The C-A-D package ΓòÉΓòÉΓòÉ New feature: The C-A-D is introduced with WatchCat 2.1. It is part of the registered version only. You can use the WatchCat package to disable Ctrl-Alt-Del, or to activate WatchCat on Ctrl-Alt-Del. The C-A-D package also introduces a shutdown folder (like the start-up folder), which contents is executed on shutdown. The shutdown option of the Desktop is replaced, s. t. you can force the C-A-D package to kill all empty OS/2 shells before shutting down the system. (No annoying "Do you want to close ...") any longer! ΓòÉΓòÉΓòÉ 9.5.1. Configuring Ctrl-Alt-Del ΓòÉΓòÉΓòÉ Open the desktop settings (right mouse button on the desktop, -> Settings). Now select the following page: When selecting the first check box, C-A-D asks for confirmation before shutdown (which is highly recommended). Killing the empty OS/2 shells is recommended also. An OS/2 shell is empty when no program is running in it. You can also kill all DOS (VDM) shells. But be careful. A running DOS program would be killed. Use the second page to use the C-A-D package to configure WatchCat to 1. reboot 2. ignore Ctrl-Alt-Del 3. activate WatchCat (default). (this requires full installation of the C-A-D package). OS/2 experts may install only parts of the C-A-D package to disable Ctrl-Alt-Del only in DOS Shells for example. This will not be explained here. Instead, it is recommended to use the WPS object and a full installation. Experts may run wccad -? in an OS/2 and a DOS box for more information. Please note that the desktop menu has a new item: This is a quick access to alter the Ctrl-Alt-Del state, if you do want to open the Desktop settings. Note: There is no additional shutdown option. Instead: You can select the standard shutdown (in the above menu) to activate the C-A-D shutdown. Note: This package is compatible with other desktop extentions like Extended desktop by Dan Campbell, a very useful tool. Note: You can also run shutdown from the command line. It is recommended to use the C-A-D shutdown program, because it is capabable of running the shutdown folder. If you are writing your own shutdown program, use the following code sequence to run the shutdown objects and shutdown: BOOL folder() { HOBJECT h; h=WinQueryObject((PSZ)"<WP_SHUTDOWN>"); if (!h) return FALSE; if (!WinSetObjectData(h, "OPEN=SHUTDOWN")) return FALSE; return TRUE; } ΓòÉΓòÉΓòÉ 9.5.2. The shutdown folder ΓòÉΓòÉΓòÉ The shutdown folder is created (with instcad) in the OS/2 system folder, where you can also find the startup folder. Simply drag a program object onto the folder. Each time you run shutdown.exe or select shutdown from the desktop menu, all programs in the shutdown folder are started. The system will not continue to shutdown until all programs are started. Your system folder may look like this: You can drag program objects or shadows of program objects into the folder: Note: You can drop only program icons or shadows of program icons on the startup folder. To run a ReXX script, create a program icon with a * (asterisk) in th field of the program name. Enter the ReXX script as a parameter. To kill programs before the "Do you want to end ..." message appears, use the kill program (part of the C-A-D package). E.g. kill clock. The Shutdown folder currently has the following limitations: 1. Only programs can be started, not WPS-objects. 2. The object is not marked as in-use. 3. It is non-determined, which object is called first ΓòÉΓòÉΓòÉ 9.5.3. The shutdown program ΓòÉΓòÉΓòÉ You can run shutdown per program (or create a WPS object for it). Just run shutdown for a complete shutdown, or run shutdown -? for a complete description of its parameters ΓòÉΓòÉΓòÉ 9.5.4. The Ctrl-Alt-Break feature ΓòÉΓòÉΓòÉ Note: This feature is available in the 1st Aid Package only. After installing the C-A-D package, the following hotkeys are available: 1. For DOS sessions: Ctrl-Alt-Break will interrupt the current program and go back to the DOS prompt. This is very brutal and may not give back all DOS-memory but may be useful in some situations (and is available for stand-alone-DOS also). 2. For any OS/2 program: Ctrl-Alt-K will kill the currently running process, no matter whether the system is in Full-Sceen or PM mode. ΓòÉΓòÉΓòÉ 10. Running WatchCat from the command prompt ΓòÉΓòÉΓòÉ Don't forget that you can also start WatchCat from the command prompt. We distinguish between two modes: If you detach WatchCat (i.e. type detach watchcat at the command prompt), WatchCat is activated by hotkey. This is the mechanism when WatchCat is added to the CONFIG.SYS. If you start WatchCat like any other program (by typing "WatchCat" at the command prompt) it does not switch to Full-Screen, and it provides all information immediately. You don't have a hotkey for this WatchCat session. Note: You can have one detached and one or more started (windowed) WatchCat instances at the same time. Note: WatchCat supports a few options ΓòÉΓòÉΓòÉ 11. Using external WatchCat modules ΓòÉΓòÉΓòÉ On start-up, WatchCat looks for DLLs in its directory and tries to find out whether they are modules for WatchCat or not. If a DLL is a WatchCat module it is integrated into WatchCat as if it were part of the program. The advantages are: You can delete all unneeded modules You can write your own modules It is easier to extend WatchCat Currently there are three modules. wcprintf for debugging, startpgm for starting programs in a WatchCat window and tracevio for tracing the calls to the viocalls DLL. ΓòÉΓòÉΓòÉ 11.1. Using the wcprintf module ΓòÉΓòÉΓòÉ This module allows the user to print text in a WatchCat window. All you have to do is to write into the pipe \PIPE\WATCHCAT. This can also be done from DOS sessions. Example: type read.me >\PIPE\WATCHCAT If you are writing a PM program and you have trouble with the message processing, these routines might be useful because they have no additional message overhead. Examples are the following situations: You want to hook the message queue. Sending a text string to another window increases (potentially) the message processing. You need information about all mouse movement or mouse clicks in your application. Obviously moving the mouse to another window to display debugging infos would result in "wrong" messages. Your application hangs up the PM and you don't know why. You can print debugging strings, but you are not sure whether all debugging strings are displayed. WatchCat can help because it can be activated without key and mouse (by hardware switch or your program) and it is full-screen. Therefore it works even if the PM is hung. If you want to use this module simply include wcapi.h. Then #define WCDEBUG. A call to wcprintf(char *format, ...) pipes its output into a WatchCat window. If WCDEBUG is not set and optimization is turned on, the function call is optimized away. You can activate WatchCat from the program by calling WatchCat(). You must link your application with wcatdeb.lib. It is necessary that wcatdeb.dll is in the same directory as watchcat.exe ΓòÉΓòÉΓòÉ 11.2. Using the startpgm module ΓòÉΓòÉΓòÉ Use this module for starting programs and redirecting stdout of the program into a WatchCat window. You need a small description file to use this module. This file must be called: wcatpgm.ini. It's in the same directory with watchcat.sys and watchcat.exe. Let us explain the following example: "Hardware tree", "Show hardware tree", "rmview.exe /hw", windowed "qsystem ", "Show system configuration", "qsystem.exe", windowed "Exehdr ", "Show detailed module information (exehdr)", "exehdr.exe %p", update Use one line per program. The first entry specifies a title. This title is used in the menu Add-On and as a window name. It is recommend to pad spaces up to 10 characters. The next entry is the help text, shown on the status line. Specify the full command line as the 3rd parameter. Please don't forget .exe and please avoid unnecessary spaces. The last parameter is most interesting. Specifying windowed will start your program once. Specifying update will start the program evertime a new process is selected. This is especially interesting in conjunction with %p. This macro is replaced with the path and program name. In the example, the first line will start rmview a standard (but undocumented) OS/2 program. qsystem is a tool by N Couch/J Muir for detecing the hardware configuration. This program can be found on the DevCon CD. exehdr is part of the Toolkit. It displays interesting information about Modules (segments, exported names, ...). ΓòÉΓòÉΓòÉ 11.3. Using the tracevio module ΓòÉΓòÉΓòÉ Move tracevio.dll into the WatchCat path to use the tracing feature. This requires the process manipulation center to be installed. Select the package from the Add-On menu and see which VIOCALL function is called by a certain application. Very usyful for debugging. ΓòÉΓòÉΓòÉ 12. Interfacing WatchCat ΓòÉΓòÉΓòÉ There are two ways of interfacing to WatchCat. First, your program can activate WatchCat and second, you can write your own WatchCat module and write directly into a WatchCat window. The API is still under development. If one of the functions does not work as expected or you need a function not provided now, please contact us. (All functions were developed with IBM C/Set++; they are portable and partly tested for Borland, EMX, Watcom; cf. testmod.c) ΓòÉΓòÉΓòÉ 12.1. Activating WatchCat from a program ΓòÉΓòÉΓòÉ There are two ways to activate WatchCat from your own program: Use the following code sequence: #include INCL_DOSSEMAPHORES ... #include <os2.h> ... HEV hev; ... if (!DosOpenEventSem((PSZ)"\\Sem32\\WatchCat", &hev)) { DosPostEventSem(hev); DosCloseEventSem(hev); } Link with wcatdeb.lib, and use the following code sequence: #include <wcapi.h> ... WatchCat(); ΓòÉΓòÉΓòÉ 12.2. Writing your own DLL ΓòÉΓòÉΓòÉ Writing your own WatchCat DLL is not difficult. WatchCat searches its own directory for any WatchCat DLL. A WatchCat DLL is a dynamic link library that contains at least the functions WCatRegister and WCatInit. More specifically, WatchCat does the following: Call WCatRegister(), call WCatInit(), start WCatThread() as a thread, if present. To make it easier, you have to compile dllbase.c and link it with your application. Then you have access to all functions with prototypes in wcapi.h. dllbase contains WCatRegister and initializes the "system". Your own written module should contain at least WCatInit. Use this function to create all windows you need (use WCatBegWindow). You can also insert headlines (use WCatSetTitle). Don't call WCatBegWindow later. The WCatThread function is started as a normal-priority thread. You can use all functions here, too. WatchCat is event-driven. If an event occurs (mouse, keyboard, ...) WatchCat calls a specific DLL-function (if present). Your function is called with a void* parameter. This is a window handle identical to one allocated with WCatBegWindow. It is your job to find out if this handle belongs to a window which message you want to intercept. Your function can return either TRUE (non-zero) or FALSE. TRUE indicates that the parent is not called, so the default action is not done. On the other hand, FALSE indicates that the default action has to be done. Currently the following functions are supported: int WCatKey(void *win_handle, int scan, int ascii, int shift) win_handle window handle scan Make-Code ascii Ascii-Code or 0 shift 0=no shift, 2 = Ctrl, 4 = Alt int WCatB1Click(void *win_handle, int x, int y) win_handle window handle x x-coordinate (relative to window) y y-coordinate (relative to window) int WCatSelected(void *win_handle, int i) win_handle window handle i line (0-based) int WCatInformIfProcessChanged(void *win_handle, int i) win_handle window handle i line which is selected now WCatTimer() called every second WCatThread() called as a thread Please note that your DLL can provide the above functions. They are called by WatchCat. Do not call the functions yourself. On the other hand all above functions are optional. You do not need to provide any of them. Example: See the testmod.c file for an example. Writing a DLL for WatchCat is not very difficult, but not trivial either. Please read the documentation carefully to see if any library initialization is required. When one of the above functions is called you can assume that this is done in the WatchCat process context. Note that your DLL may be called from several WatchCat instances (The example ignores this problem). In the WatchCat context you can call all API functions except WCatBegWindow. If the function is called from outside the WatchCat context, you are not allowed to call this API. ΓòÉΓòÉΓòÉ 12.3. API C-Reference ΓòÉΓòÉΓòÉ The following C-reference describes all functions that can be used in your DLL. Note: To use these functions, it is necessary to compile dllbase.c and link it to your DLL. Note: These functions can only be used in the WatchCat-context. Never call these functions from another program or a DLL used by another program. This would definitely result in a protection violation. ΓòÉΓòÉΓòÉ 12.3.1. WCatBegWindow ΓòÉΓòÉΓòÉ Prototype: void * _System WCatBegWindow(char *title, char *Menuentry, char *description, void (*fn)()); Parameters: char *title The title of the window char *Menuentry This string appears in the Add-On menu char *description Your text for the status line void (*fn)() An action function associated with the menuitem Returns: A window handle of void * Notes: Use this function to add a window to the Add-On submenu. Currently it is impossible to create windows dynamically. Therefore it is absolutely necessary to create all windows on start-up (i.e. in function WCatInit()). You should save the handle that is returned. It is used for all operations and should not be altered. The function taken as the last parameter is called whenever the associated menuitem is selected. The intuitive action is to show a window (see example below) - but it is not necessary to do so. You can also ignore the window handle returned by WCatBegWindow and do some some other action when a menu item is selected. Example: void *win=0; /* window handle */ void show() { WCatShowWindow(win); WCatShowWindow } BOOL _Export _System WCatInit() { ... win=WCatBegWindow("My title", "My menu entry", "A very long description", show); ... return TRUE; } ΓòÉΓòÉΓòÉ 12.3.2. WCatClearWindow ΓòÉΓòÉΓòÉ Prototype: void _System WCatClearWindow(void *win); Parameters: void *win The window handle (returned by WinBegWindow) Returns: no return value Notes: This function simply clears the window. Example: void *win; /* window handle */ ... if (WindowShouldBeCleared==TRUE) WCatClearWindow(win); ΓòÉΓòÉΓòÉ 12.3.3. WCatShowWindow ΓòÉΓòÉΓòÉ Prototype: void _System WCatShowWindow(void *win); Parameters: void *win The window handle (returned by WinBegWindow) Returns: no return value Notes: Use this function to show the window. Nothing happens if the window is already visible. Example: void *win; /* window handle */ ... void show() { WCatShowWindow(win); } ΓòÉΓòÉΓòÉ 12.3.4. WCatAddLine ΓòÉΓòÉΓòÉ Prototype: void _System WCatAddLine(void *win, char *text); Parameters: void *win The window handle (returned by WinBegWindow) char *text A string that contains one line (excluding \n). Try to use strings with less than 200 chars. Returns: no return value Notes: This function adds a line containing text to the window associated with the window handle win This function does not scroll the contents of the window. (cf. WCatAddLineAndScroll) Example: void *win; /* window handle */ ... WCatAddLine(win, "This is a a new line"); ΓòÉΓòÉΓòÉ 12.3.5. WCatAddLineAndScroll ΓòÉΓòÉΓòÉ Prototype: void _System WCatAddLineAndScroll(void *win, char *text); Parameters: void *win The window handle (returned by WinBegWindow) char *text A string that contains one line (excluding \n). Try to use strings with less than 200 chars. Returns: no return value Notes: This function adds a line containing text to the window associated with the window handle win This function does scroll the contents of the window if necessary (cf. WCatAddLine) Example: void *win; /* window handle */ ... WCatAddLineAndScroll(win, "This is a a new line"); ΓòÉΓòÉΓòÉ 12.3.6. WCatChangeLine ΓòÉΓòÉΓòÉ Prototype: void _System WCatChangeLine(void *win, int line, char *text); Parameters: void *win The window handle (returned by WinBegWindow) int line The line in the window (0-based) char *text The new text string that replaces the old line (no \n) Returns: no return value Notes: This function can be used to replace a specific line. Example: void *win; /* window handle */ ... /* Change the first line */ WCatChangeLine(win, 0, "This is the new first line"); ΓòÉΓòÉΓòÉ 12.3.7. WCatPrintf ΓòÉΓòÉΓòÉ Prototype: void _System WCatPrintf(void *win, char *format, ...); Parameters: void *win The window handle (returned by WinBegWindow) rest usage exactly like printf Returns: no return value Notes: This is a very easy interface to print strings in a window. The line is added as the last line without scrolling. Example: void *win=0; /* window handle */ char *name1="Bill"; char *name2="Lou"; ... WCatPrintf(win, "Hi %s, my name is %s", name1, name2); ΓòÉΓòÉΓòÉ 12.3.8. WCatChangePrintf ΓòÉΓòÉΓòÉ Prototype: void _System WCatChangePrintf(void *win, int line, char *format, ...); Parameters: void *win The window handle (returned by WinBegWindow) int line The line to be changed (0-based) rest usage exactly like printf Returns: no return value Notes: This is a very easy interface to print strings in a window. A specific line is replaced. Example: void *win=0; /* window handle */ char *name1="Bill"; char *name2="Jim"; ... WCatChangePrintf(win, 0, "Hi %s, my name is %s", name1, name2); ΓòÉΓòÉΓòÉ 12.3.9. WCatQueryPID ΓòÉΓòÉΓòÉ Prototype: unsigned long _System WCatQueryPID(); Parameters: no parameters Returns: returns the process id of the currently selected process. A value of -1 indicates that no process but some other module is selected. Notes: Use this function to query what process is currently selected in the process/module list. Example: ULONG pid; pid=WCatQueryPID(); ΓòÉΓòÉΓòÉ 12.3.10. WCatQueryHandle ΓòÉΓòÉΓòÉ Prototype: unsigned long _System WCatQueryHandle(); Parameters: no parameters Returns: returns the handle of the currently selected process or module. Notes: Use this function to query what process or module is currently selected in the process/module list. Example: ULONG handle; char name[50]; pid=WCatQueryHandle(); if (DosQueryModuleName(handle, sizeof(name), name)) { if (stricmp(name, "watchcat.exe")==0) WCatPrintf("it's me! it's me!"); } ΓòÉΓòÉΓòÉ 12.3.11. WCatSetTitle ΓòÉΓòÉΓòÉ Prototype: void _System WCatSetTitle(void *win, int i, char *text); Parameters: void *win The window handle (returned by WinBegWindow) int line Title line (0 based) char *text Headline Returns: no return values Notes: Use this function to generate a headline for a window. Example: void *win; /* window handle */ ... WCatSetTitle(win, 0, "PID remark"); WCatSetTitle(win, 1, "ΓöÇΓöÇΓöÇ ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ"); ΓòÉΓòÉΓòÉ 12.3.12. WCatPopup ΓòÉΓòÉΓòÉ Prototype: void _System WCatPopup(); Parameters: no parameters Returns: no return values Notes: Forces WatchCat to be popped up. Do not use this function from another program! Example: WCatPopup(); ΓòÉΓòÉΓòÉ 12.4. API C++-Framework-Reference ΓòÉΓòÉΓòÉ Using WatchCat from C++ is even more simple. You need small experience with C++ and the framework-idea and some experience with programming DLL. WatchCat uses a binary-compatible compiler-independent (but curently not language-independent) object model. WatchCat is currently based on C++. There are plans to support Direct-to-SOM when the right DTS-compilers become available. How to program with the WatchCat window framework? 1. First #include wcapi.h in your file. Overload one of the two classes WCatWindow (a "normal" window) or WCatListbox (a listbox like most other currently used windows). Just have a look at the wcapi.h file. The class definitions are almost self-explaining. The class hierarchy does currently not reflect the "real" hierarchy used in WatchCat.exe (where it not as simple), but there is no need to care about it. WCatBaseWindow is an abstract base class and cannot be instanciated. 2. Specialize your class by overriding some methods. Each method that is not overridden will have a default meaning. 3. Provide a function call WCInit with C-Linkage (!!) and default _System linkage, which is called on start-up. Create all windows here with the overloaded new operator. Currently dynamically created windows are not supported. 4. Now compile and link with dllpbase.cpp and dllbase.c You need per-process initialization and multiple data segments. Please ensure that you have correctly initialized the compiler's run-time environment. 5. Ensure that the DLL is in the same directory where WatchCat is, or the environment variable WCATDLL is pointing to the correct path. 6. Run and enjoy. Example: How to program "hello, world" with WatchCat: How many lines do you need to write a program the prints "hello, xx" (xx=name of a process) in a WatchCat window, whenever the user selects a new process??? Well, here is the program: #define INCL_DOS #include <os2.h> #include <string.h> #include "wcapi.h" class Hello : public WCatListbox { public: Hello(char *title, void (* _Optlink fn)(), char *Menuentry=0, char *description=0) :WCatListbox(title,fn,Menuentry,description) {} virtual int processChanged(int i); }; int Hello::processChanged(int i) { char buffer[CCHMAXPATH+10]; strcpy(buffer, "hello, "); if (0==DosQueryModuleName(WCatQueryHandle(), CCHMAXPATH, buffer+7)) addLineAndScroll(buffer); return 0; } Hello *hello; void _Optlink fun() { hello->show(); } BOOL WCEXPORT WCSYSTEM WCatInit() { hello=new Hello("Hello, world", &fun, " Say hello, world", "Hello, world example"); hello->show(); return 0; } We first declare a new class (=window type) by overloading WCatListbox. This is a default listbox, except that it prints out a message when the user selects a new process. So besides a new constructor, we override processChanged. The new method calls WCatQueryHandle and detects the name with the OS/2 API DosQueryModuleName. Without error, we now print out the text "hello, xxx" with the method addLineAndScroll. All we need is one pointer per listbox. This is a global variable. Please note that you need multiple data segments when producing a DLL. The next step is to provide WCInit(). Don't forget WCEXPORT WCSYSTEM. Both words are important to ensure C and _System linkage. We simply create a window with the C++ new-operator here and show it on start-up. (The user can also select it via the menu.) As a last thing, we provide a function that is called whenever the user clicks on our menu entry. All we want to do is to show the window. Ready. Now we need to compile our WatchCat application. First we create the following module definition file for our linker: LIBRARY hello INITINSTANCE TERMINSTANCE DATA MULTIPLE NONSHARED As you can see we need a per-process initialization, because WCatInit should be called whenever WatchCat is started. And we need DATA MULTIPLE, because the global variable hello should be unique to all processes. Now we are ready for compiling. For IBM C/Set++ the procedure looks like this :icc -Rn -Ge- hello.cpp dllpbase.cpp dllbase.c hello.def. Please consult your compiler manual for more information about switches and initialization. VOILA! We're ready. Start WatchCat and enjoy your first WatchCat application. *** HAPPY PROGRAMMING! *** ΓòÉΓòÉΓòÉ 12.4.1. key ΓòÉΓòÉΓòÉ Signature: int key(int scan, int ascii, int shift) Type: This is a callback function that may be overridden to recognize key-strokes. Parameters: int scan; scan code int ascii; asciii code int shift; shift state Returns: return 0. Notes: This function is called if the user presses a key in the associated window ΓòÉΓòÉΓòÉ 12.4.2. selected ΓòÉΓòÉΓòÉ Signature: int selected (int i) Type: This is a callback function that may be overridden to recognize if the user selects an item in the listbox. Parameters: int i; The item nr. in the process window Returns: return 0. ΓòÉΓòÉΓòÉ 12.4.3. processChanged ΓòÉΓòÉΓòÉ Signature: processChanged(int i) Type: This is a callback function that may be overridden to recognize if the user selects a process. Parameters: int i; nr. in the process listbox Returns: return 0. Notes: This functio is called if the user selects an item in the process window. Use WCatQueryHandle to get more information. ΓòÉΓòÉΓòÉ 12.4.4. b1click ΓòÉΓòÉΓòÉ Signature: int b1click(int x, int y) Type: This is a callback function that may be overridden to recognize if the user clicks on the assiciated window. Parameters: int x; the logical x-coordinate (0-based) int y; the logical y-coordinate (0-based) Returns: return 0. ΓòÉΓòÉΓòÉ 12.4.5. b1dbclick ΓòÉΓòÉΓòÉ Signature: int b1dbclick(int x, int y) Type: This is a callback function that may be overridden to recognize if the user double-clicks on the assiciated window. Parameters: int x; the logical x-coordinate (0-based) int y; the logical y-coordinate (0-based) Returns: return 0. ΓòÉΓòÉΓòÉ 12.4.6. receiveFocus ΓòÉΓòÉΓòÉ Signature: int receiveFocus() Type: This is a callback function that may be overridden to recognize if the window gets the input focus. Parameters: no parameters Returns: return 0. ΓòÉΓòÉΓòÉ 12.4.7. receiveFocus ΓòÉΓòÉΓòÉ Signature: int looseFocus() Type: This is a callback function that may be overridden to recognize if the window loses the input focus. Parameters: no parameters Returns: return 0. ΓòÉΓòÉΓòÉ 12.4.8. handleShow ΓòÉΓòÉΓòÉ Signature: int handleShow() Type: This is a callback function that may be overridden to recognize if show method is displayed. Parameters: no parameters Returns: return 0. ΓòÉΓòÉΓòÉ 12.4.9. setTitle ΓòÉΓòÉΓòÉ Signature: void setTitle() Type: This is a service function that you can call to change the title. Parameters: int i; Use i=0 char *s; the title string Returns: returns nothing ΓòÉΓòÉΓòÉ 12.4.10. clrScr ΓòÉΓòÉΓòÉ Signature: void clrScr() Type: This is a service function that you can call to clear the screen (Listbox, window) Parameters: no parameters Returns: returns nothing ΓòÉΓòÉΓòÉ 12.4.11. puts ΓòÉΓòÉΓòÉ Signature: void puts(char *s) Type: This is a service function that you can call to display a string. Parameters: char *s; the string Returns: returns nothing ΓòÉΓòÉΓòÉ 12.4.12. addLine ΓòÉΓòÉΓòÉ Signature: void addLine(char *s) (WCatListbox only) Type: This is a service function that you can call to add a string to the Listbox Parameters: char *s; the string Returns: returns nothing ΓòÉΓòÉΓòÉ 12.4.13. addLineAndScroll ΓòÉΓòÉΓòÉ Signature: void addLineAndScroll(char *s) (WCatListbox only) Type: This is a service function that you can call to add a string to the Listbox and scroll down one line Parameters: char *s; the string Returns: returns nothing ΓòÉΓòÉΓòÉ 12.4.14. changeLine ΓòÉΓòÉΓòÉ Signature: void changeLine(int i, char *s) (WCatListbox only) Type: This is a service function that you can call to replace line i with the string s in the Listbox Parameters: int i; the line (0-based) char *s; the string Returns: returns nothing ΓòÉΓòÉΓòÉ 13. FAQ ΓòÉΓòÉΓòÉ ΓòÉΓòÉΓòÉ 13.1. A short technical OS/2 introduction ΓòÉΓòÉΓòÉ For all non-programmers, this chapter provides a small OS/2 introduction to explain often used technical terms that may be new to some users. All OS/2-professionals, OS/2-cracks, OS/2-gurus and OS/2-gods: STAY AWAY FROM THIS CHAPTER! This chapter (and the following chapters) was written for you, the beginners, the non-programmer, the avarage user of OS/2. I (Felix) tried to avoid unnecessary technical blah-blah. Please feel free to comment and critizise this part of the documentation if it is difficult to understand. (There is more risk that it is too depict). ΓòÉΓòÉΓòÉ 13.1.1. Multitasking ΓòÉΓòÉΓòÉ OS/2 is a multitasking operating system. Multitasking means that several processes can run at the same time. Example: After a hard day of work you're sitting in front of your TV, a cool bavarian beer in the left hand, eating potato chips with the right hand. This is a form of multitasking, because you are doing all three tasks (TV, beer, chips) at the same time. Since currently most PC only have one CPU OS/2 cannot run all programs simultanously (like you cannot drink and eat at the same time) instead all tasks are done serial but for a very short time (a few milliseconds) s.t. the user gets the impression of simultanously running programs. There are two types multitasking: 1. Cooparative multitasking: This form is used in Windows. Each task gets CPU-time and must explicitly give away the CPU-power. This is very inflexible of course. A program use the processor on its own. For example imagine your wife disturbs your TV-session and starts discussing the visit of your parents-in-law. She may use all your (CPU) time preventing you from doing some other really important tasks (TV). 2. Pre-emtive multitasking: This form of multitasking is used by OS/2. Each program gets a specific amount of CPU time. Then OS/2 interrupts the program and let the CPU concentrate on another task. There is an obvious analogy in our example: turn up the TV-noise after a few milliseconds. OS/2 supports several levels of priority, protection against other processes and much more as you can read in the next chapters. ΓòÉΓòÉΓòÉ 13.1.2. Processes and Threads ΓòÉΓòÉΓòÉ There are two important technical terms: processes and threads: process: A process is an execution instance of a program. If you are starting a program two times, there are two additional processes (1+1=2) running in the system. A process can own several resources like memory or file handles. A process can access only his own resources, it is forbidden to access other resources. This is like real life; you have small resources (e.g. money) but when you try to access other's resources (bank) you're punished and must go into prison. OS/2 is more cruel. A process that tries to access other processes' resources is killed. (Every OS/2 user knows the protection violation dialog box). All processes have a unique id called process id (PID). threads: A process is not the smallest unit of program execution. In contrast to Windows and many Unix systems parts of the program can run parallel. Remember our TV-example? Imaging your not just viewing the O.J.Simson process, but instead you're zapping through all channels. This is true multithreading. There are 3 processes (TV, beer, potato chips) and a few threads (viewing all channels at the same time). All task share the CPU (you)-time. All threads have a unique id called thread id (TID). Mostly threads are used to do time-consuming jobs (like printing) in the background. Threads share the resources of their process. Threads are not protected against each-other (within a process). OS/2 supports up to 4096 threads in total. Each process has at least one thread (primary thread). An application that has only one thread is called single-threaded. An application may produce additional threads (secondary threads) and is then multithreaded You can use WatchCat to view information about the threads in a process. Have a look at the thread state or priority. ΓòÉΓòÉΓòÉ 13.1.3. Other Modules ΓòÉΓòÉΓòÉ Now you know what processes are. Let's try to be more general. A process is a special form of a module. A module something that consists of resources and/or code. There are different types of modules explained in the following. Device drivers: With OS/2, programs are not allowed to access hardware directly (ok, ok, except 16-bit IOPL code). E.g.You don't fetch your slippers yourself, instead you order your dachshund to do so. With OS/2 each program does not directly access the hardware, instead it communicates with the device driver. there are two types of device drivers. The physical device drivers which are always 16-bit and directly access the hardware and the virtual device drivers which typically communicate with the physical device driver. Virtual device drivers (always 32-bit) provide virtual hardware for DOS programs. This is necassary because DOS programs are egoistic and want to access all hardware resources alone. The solution is to pretend hardware (virtual hardware) that DOS can access on it's own. (For a DOS session, it's April, 1st every day...). DOS programs.: DOS programs are run in a virtual DOS machine (VDM) Spiteful one can say that this is simply an OS/2 process that emulates a (complete) PC. DOS programs "think" they are running on a stand-onlone PC. No OS/2 program can look "into" a VDM. Therefore it is impossible for WatchCat to tell the users what (resident) programs are running there. Instead it finds out the window title, which is enough in most situations. With WatchCat you can see that a VDM may contain 2 threads, but this is an OS/2 feature, not DOS creating two threads... WinOS/2 programs: A WinOS/2 program is also running in a VDM. WinOS/2 sessions have the same restriction as DOS sessions have. You can run each WinOS/2 session in different VDM (like running it on different PC) or in one VDM (when one Windows program commits suicide all programs in the same VDM are also dead). Dynamic link libraries (DLL): A DLL is mostly interesting to programmers. DLL are code segments (or resources) that are not part of the program but instead loaded when starting (load-time DLL) or running (run-time DLL). DLL are a boring concept for users but an exciting concept for programmers. For example you can integrate a mini Editor (currently without hardware cursor...) in WatchCat as a DLL. To the user it looks like being part of the WatchCat package even though we (Felix and Thomas, the fathers of WatchCat don't know about it)! Another important attribute of DLL is that they can be used to share resources (and code). Consider DOS: 10 DOS applications have 10 different user interfaces with 10 times the code of one user interface. With OS/2 programs share the same code for the user interface (e.g. pmwin.dll). This means less code on your harddisk. Don't think about WatchCat now... With WatchCat you can see what DLL are used by a process. ΓòÉΓòÉΓòÉ 13.1.4. Synchronisation ΓòÉΓòÉΓòÉ Processes and threads need to be synchronized. For car traffic we know the following types of synchronization: 1. No synchronization: The weakest car must give way. 2. Minimal synchronization: The car that arrives as the latest must give way. 3. Better syncronisation: The car that arrives from the right can drive first. 4. Full synchronization: Traffic is synchronized by traffic lights. With OS/2 "traffic lights" are called Semaphores. Semaphores are used to synchronize trains, which seems to have similar problems like cars. An interesting consequence of the above example is that the first three points contain the risk of a deadlock (all cars coming at the same time). This may happen in OS/2 programs, too. You can use WatchCat to kill a hung program. To be more precise there are two types of semaphores: Event semaphores: They are like traffic lights as described above. Mutex semaphores: They can be used to protect resources. Example: You are traveling in a train and have to go to the toilet. By laying your jacket on the seat you mark the seat as occupied. Now your jacket is a mutex semaphore. For technical reasons WatchCat can currently only display 16-Bit semaphores which are commonly not used in 32-bit programs. ΓòÉΓòÉΓòÉ 13.1.5. Process communication ΓòÉΓòÉΓòÉ As explained earlier, processes cannot directly access other processes data. Instead they have to communicate with each other. OS/2 knows several ways to communicate: The simplest type is shared memory. Many processes may use the same region of memory. This communication needs careful synchronization. WatchCat can be used to display information about shared memory. Pipes: A pipe acts like a hose. One process writes into the pipe another one reads from the pipe. Queues: Queues are more complex. The can be used as FIFO (first-in-first-out) or LIFO (last-in-first-out) buffers. Other mechanisms are used by the Presentation Manager (PM) which is based on sending messages. ΓòÉΓòÉΓòÉ 13.2. PM and WatchCat ΓòÉΓòÉΓòÉ Like the previous chapter, this part of the documentation is not intended to be read by OS/2-gurus. It gives a brief introduction to the architecture of the PM. ΓòÉΓòÉΓòÉ 13.2.1. Architechture of the PM ΓòÉΓòÉΓòÉ The Presentation Manager (PM) is event-driven. This means that an application receives a message whenever something interesting happens (e.g. keystroke, mouse movement, exploding printer, etc). Events are not necessary invoked by the user. Many messages are used for internal communication. And there are not just a few messages! While working a few hours with OS/2 thousands of messages are sent between the PM and several applications. When a few people are discussing a serious problem and all members are speaking at the same time, they will probably never come to a solution. This way of discussion is a little bit ineffective. It is more effective to have a talk master who manages the discussion. In the OS/2 world we have communicating applications and the PM as the "talk master": The PM sends a message to one application (green arrow), the application answers and gives control back to the PM (blue line). Now assume that one of the applications is like a politican. Politicans mostly don't stop speaking once they have started. We need a rule for the maximum speaking time. And indeed - there is a CUA (common user access, defined by IBM) rule which says that an application should not work longer than 0.1 seconds on one message. (Imagine a politican speaking 0.1 seconds! Wow! And considering the redundancy of their speech this is not impossible...). To summarize: While one program is working on a message, other programs cannot get messages. Every program should get ready in 0.1 seconds. To avoid mis-understandings: OS/2 is a pre-emtive operations system. While one PM application is working on a message all threads that are not waiting for a PM message (in other words, they don't take part in the discussion) can do whatever they want to do (For example WatchCat can kill the PM...). What does this mean in practice? You are currently running view.exe to read this online documention. Click on Services/Search to search for a text string. When searching for a certain string the PM shows a funny small clock and you have a reason to justify opening a new can of beer. View.exe is a perfect example what happens if someone ignores the CUA guidelines. Obviously the CUA book is not much spreaded in the IBM - there are many more examples like view. The correct solution (maybe in OS/2 4.0) is to put the searching algorithm in a different (non-PM) thread. ΓòÉΓòÉΓòÉ 13.2.2. The single message queue ΓòÉΓòÉΓòÉ As you have seen above there are parts in the PM that have to be serialized. Hmmm. There seems to be an easy solution. Every application gets a message queue. Now the PM can save all messages belonging to one appliction in the queue and give the control to another application. And indeed - every application has its own message queue, but - ... there is one bottle neck: Only one system message queue. User input (keyboard, mouse) is not put directly into the application message queues, instead all user input is serialized. User input cannot be evaluated "in parallel". As long as a program is hanging or working on a message no user input can be evaluated. This is the reason why you can see the clock running; pulse is working and you are watching the ill-behaved application while it is joyfully deleting your files and (without WatchCat) you can do nothing except rebooting, because your input is saved in the system message queue but not directed to the applications. ΓòÉΓòÉΓòÉ 13.3. How does WatchCat work? ΓòÉΓòÉΓòÉ WatchCat is - of course - not a PM application. Instead it is running in a different session. It bypasses the PM handling of keyboard events by directly accessing the hardware: The PM is blocked, but WatchCat (better: its device driver) detects the hotkey sequence. It grabs the CPU time and the screen. The user can now kill the corrupt PM task (which violates CUA!) or kill the PM itself. All other PM programs are not affected. Now the PM is stable again. By pressing ESC, WatchCat turns back to the PM as you can go on working as if nothing happend: ΓòÉΓòÉΓòÉ 13.3.1. The message queue size ΓòÉΓòÉΓòÉ There were long discussions in the Internet fora whether the message queue size of OS/2 is too small. First: The process control center contains DLL to increase the message queue size of any application process to 100 messages. In spite of this feature the message queue will probably never cause problems: Technical argumentation There are two ways to distribute messages: sending messages (which is synchronous) and posting messages (which is asynchronous). Sending a message results in a procedure call, while only posted messages are put into the (application) message queue. When the PM hangs because of a limited message queue obviously one or more applications are corrupting/blocking the message queue. Therefore it exists an ill-behaved thread, which has as least 1. a message queue (non-PM threads cannot block the PM), 2. a window procedure (without it the thread simply does not take care about posted or lost messages) and 3. a condition under which this thread is blocked. As noted above, posted messages are asynchronous. I can imagine only three situations why a thread (with message queue and window procedure) might hang because of a lost posted message: 1. The window procedure waits for the posted message: Example: ... case WM_PAINT: wait_for(WM_USER); ... ... This is not possible with the PM. 2. The window proc waits for an event caused indirectly by the posted message: case WM_PAINT: DosWaitEventSem(...); This is absolutely worst PM programming style! You must not block the window procedure. A message should be answered in 0.1 seconds (CUA). In a multitasking environment you cannot make any assumptions about the performance of other threads. Therefore you should not block the thread via blocking/waiting. Instead a message should be sent/posted (e.g. WM_SEM1). The PM is not blocked with this approach. 3. A user message sends information about e.g. initialization. When this message is lost, parts of the application are not initialized. This is bad programming practice, but the result will probably be a protection violation or window garbage, but not a hung PM. So - I believe - it is almost impossible for an application to hang because of lost messages. And if there is an ill-behaved application that waits synchronously for a posted message it is programmed very ugly and will probably fail quite often (and not just because of the queue size). This does not mean that I believe messages cannot get lost. But I don't believe that the result is a hung PM. Probably a listbox does not contain all items or the window is not redrawn correctly. And there is one more thing that is difficult to understand. Assuming that a lock-up is happening rarely (e.g. 1% of the lost messages) there must be a lot of lost messages. As a consequence there must be a lot of lost button clicks, menu choices, incorrect drawn windows, etc. The slower the CPU is, the more faults are visible. But I have rarely seen problems like that on my 386/33, but I sometimes had a hung PM. non-technical argumentation The PM supports two ways of communication: synchronous (like a telephone call) and asynchronous (like sending a letter). In my opinion synchronous communication may cause hang-ups or deadlocks. (e.g. imagine you and your partner are trying to call each-other simultaneously without hangingup the phone. This results in a deadlock). Asynchronous communication cannot result in deadlocks (or are you not working while waiting for the postman?). Lost messages (letters) may result in errors, but not in system lock-ups. ΓòÉΓòÉΓòÉ 13.4. Is OS/2 instable? ΓòÉΓòÉΓòÉ Is WatchCat the proof that OS/2 is instable? NO. OS/2 is a very stable, very modern and very powerful operating system. Like many other systems there are situations where OS/2 gets into trouble. We want to improve OS/2 with WatchCat. ΓòÉΓòÉΓòÉ 13.5. What processes cannot be killed? ΓòÉΓòÉΓòÉ Unfortunately OS/2 does not support a "die, die, die" Signal (or kill -9 on Unix). OS/2 seems to believe that in doubts the nature of an application is peaceful. There are some kind of programs that cannot be killed, e.g.: programs "stopping" in the exit list programs "stopping" in a 16-Bit segment Sorry, the only chance is to reboot. ΓòÉΓòÉΓòÉ 13.6. It beeps, but why does WatchCat not pop up? ΓòÉΓòÉΓòÉ The beep is from the device driver. That is very low-level. A device driver can operate even if the operating system is damaged. The hotkey will be recognized as long as Ctr-Alt-Del is possible also. Of course in situations of a complete OS-hangup WatchCat is helpless. On the other hand the WatchCat.exe program needs to get access to the display. There are rare situations where the system locks the display and WatchCat has no chance to display its information. Activate WatchCat a second time. This forces the PM to be killed. In some situation this helps WatchCat to pop up. ΓòÉΓòÉΓòÉ 13.7. Is WatchCat a low-level program? ΓòÉΓòÉΓòÉ For some users it may be surprising that WatchCat itself is not a tricky, ill-behaved, low-level program. WatchCat uses a few tricks, but it is not as low-level as one might expect. The device driver is using a documented interface. WatchCat.exe is a ring-3 application like your complier or your text processor. The way both parts work together is the name of the game. ΓòÉΓòÉΓòÉ 14. Trouble shooting ΓòÉΓòÉΓòÉ If you have any problems with WatchCat please refer to this section. If your problem cannot be solved, have a look at the WatchCat-WWW-home page or send us a mail. ΓòÉΓòÉΓòÉ 14.1. Tips when you have problems ΓòÉΓòÉΓòÉ WatchCat is not a trivial program. It is a good-behaved program but with special hardware configurations or after a wrong installation you may detect that WatchCat is not working as expected. Please follow the following guideline to get WatchCat working. (Most of the tips are not just limited to WatchCat.) ΓòÉΓòÉΓòÉ 14.2. The installation of (a) WatchCat (component) did not work ΓòÉΓòÉΓòÉ 1. Stop working! Think it over! 2. Read the trouble shooting section carefully. Is your problem listed there? Did you follow the installation rules? Did you install WatchCat like other software? (E.g. installing a program to the RAM-Disk or CDROM does not work). 3. Don't forget to remove all older versions of WatchCat each time before installing a new version (the 1st, 2nd, 3rd time). 4. Reboot 5. Check whether the PATH and LIBPATH environment variable are set correctly. 6. If the installation was aborted, there may be some parts installed while others are not. Try to deinstall the program completey before trying again. 7. Experts may start the wcinfo utility and check the supplied information. 8. If you have Internet WWW access select http://www.fmi.uni-passau.de/~normann/wcinfo.html The latest information is collected here. 9. Send us a mail (watchcat@uni-passau.de). Describe the problem precisely (consider to include the output of the wcinfo utility). ΓòÉΓòÉΓòÉ 14.3. Suddenly WatchCat does not work any longer ΓòÉΓòÉΓòÉ 1. Stop working! Think it over! 2. Read the trouble shooting section carefully. Is your problem listed there? 3. What has changed? config.sys? The hardware? 4. Is WatchCat running? Maybe you just killed it. 5. Have a look at the config.sys? Does everything look ok? 6. Experts may start the wcinfo utility and check the supplied information. 7. If you have Internet WWW access, select http://www.fmi.uni-passau.de/~normann/wcinfo.html The latest information is collected here. 8. Send us a mail (watchcat@uni-passau.de). Describe the problem precisely (consider to include the output of the wcinfo utility). ΓòÉΓòÉΓòÉ 14.4. The system is instable when WatchCat is running ΓòÉΓòÉΓòÉ 1. Stop working! Think it over! 2. Read the trouble shooting section carefully. Is your problem listed there? Especially if you have a bus mouse or a laptop/notebook. 3. Did you follow all installation instructions? (Add WatchCat at the end of the config.sys). 4. Try to remove some of the components. a. REM out the device driver, REM out CALL=, RUN= b. Start WatchCat. Does it work? Now include the device driver. Does it work? Now include RUN=. Does it work? 5. Experts may start the wcinfo utility and check the supplied information. 6. If you have Internet WWW access select http://www.uni-passau.de/~normann/wcinfo.html The latest information is collected here. 7. Send us a mail (watchcat@uni-passau.de). Describe the problem precisely (consider to include the output of the wcinfo utility). ΓòÉΓòÉΓòÉ 14.5. Pressing Ctrl-Alt-W does not result in any action ΓòÉΓòÉΓòÉ Make sure that you included watchcat.sys in your CONFIG.SYS. Make sure that WatchCat is running DETACHED (include it with RUN= in your CONFIG.SYS). If WatchCat is running visibly, it is NOT detached. Try to find out if other ways to activate WatchCat work. ΓòÉΓòÉΓòÉ 14.6. My mouse is killed after activation ΓòÉΓòÉΓòÉ Run WatchCat with the parameter /nomouse ΓòÉΓòÉΓòÉ 14.7. The screen is black and I cannot see anything ΓòÉΓòÉΓòÉ Run WatchCat with the parameter /nofade ΓòÉΓòÉΓòÉ 14.8. My mouse is jumping ΓòÉΓòÉΓòÉ Using a bus mouse may be incompatible with WatchCat. Either use a serial mouse or choose a different mechanism for activating WatchCat. ΓòÉΓòÉΓòÉ 14.9. Some keys are hanging ΓòÉΓòÉΓòÉ This seems to be an OS/2 keyboard driver bug. Try to specify the parameter /rate:x, with 1<=x<=9, default is /rate:2. Try out if a higher value than 2 works. ΓòÉΓòÉΓòÉ 14.10. I cannot kill my program ΓòÉΓòÉΓòÉ There are some programs WatchCat cannot kill. Sorry. Since OS/2 does not provide a way to shoot'em down, we can't help. Sometimes it is impossible to get a stable system again. In this case it is necessary to boot via Ctrl-Alt-Del. Please note that this key sequence does close all files. Do not press the reset key. You may also open a shell by pressing Space (or open a windowed shell) and do some house-keeping before rebooting. ΓòÉΓòÉΓòÉ 14.11. Why is the PM-Shell killed? ΓòÉΓòÉΓòÉ It's not a bug - it's a feature! When WatchCat is activated a second time before it pops up, the PM-Shell is killed. This is very useful for some hang-ups. On the other hand, it might not be useful when using etc. the joystick (hold tzhe fire-button a few seconds). You can switch off this feature with /nokillpm. ΓòÉΓòÉΓòÉ 14.12. Problems with Notebooks ΓòÉΓòÉΓòÉ When using the device driver the notebook might not go into sleeping mode. Consider to use an alternative activation method (cf. the WPS object). ΓòÉΓòÉΓòÉ 14.13. Problems with a bus mouse ΓòÉΓòÉΓòÉ When using a bus mouse the following problems may occur: The mouse is "jumping" When only one activation key is selected (i.e. F12) WatchCat may be activated accidently. There are three solutions: Use a serial mouse Use another activation methos (e.g. joystick) Consider to use an alternative activation method (cf. the WPS object). ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Yes, please, please, please send us a postcard. We want to get drowned in postcards! Thousend thanks from Passau!!!! ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Your postcard can look like this: ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ Your country, your hometown, a funny cartoon, Claudia Schiffer, whatever you like! Sample postcard: ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The hardware switch looks similar to the following: ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ WatchCat uses the FeelX API to switch quick marking to the alternate Marking mode if it is started in a window. So it is still possible to use cut and paste, but you must press a shift key (per default: just shift, this can be selected in the FeelX notebook). Other windows are not affected. In the current version of FeelX (1.1a) it is not possible to turn off the context menu. It is recommended to use Alt-F10 to get the context window in a windowed version of WatchCat. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A single-pole double-throw (SPDT) looks like this: In this situation pins 2 and 3 are connected. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A switch like the PC's turbo button looks like this: In this situation both pins are connected if the button is pressed. For WatchCat, a switch that remains in the state in which it is set is recommended. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ DeskMan/2 (Gregory Czaja; Development Technologies, Inc.) is a powerful tool for the Workplace Shell. One of its (endless) features allows the user to save and restore Workplace Shell objects. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The CONFIG.SYS file is the OS/2 configuration file. It can be found in the root directory of the OS/2 boot drive. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A key-sequence that is used to perform some action (instead of typing characters and words) is called a hotkey. The default hotkey to activate WatchCat is Ctrl-Alt-W: ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The environment variable LIBPATH is set in the CONFIG.SYS file. You must add the WatchCat path here to ensure that all DLL's are found. Especially the WPS object cannot work without this variable. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The environment variable PATH is set in the CONFIG.SYS file. You must add the WatchCat path here to ensure that the program can be start from any command shell. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ This statement is used to integrate a device driver into OS/2. WatchCat uses a device driver to be independent from usual message processing (which might be blocked). Add the line DEVICE=x:\path\watchcat.sys (parameters) anywhere in your CONFIG.SYS file. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The environment variable LIBPATH is set in the CONFIG.SYS file. You must add the WatchCat path here to ensure that the help file is found whenever you type view watchcat in a command shell. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ This statement is responsible for detaching a program on start-up. Please add the line RUN=x:\path\watchcat anywhere in your CONFIG.SYS. In contrast to START this command detaches the process. Do NOT use START. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The PM (Presentation Manager) is responsible for the graphical appearance of OS/2. The PM manages windows, buttons, ... The best known PM-application is the WPS (Workplace Shell). ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A device driver is responsible for the communication between applications and hardware. An application cannot (should not) access hardware directly. There are 3 types of device drivers. 1. A base device driver is loaded even before other device drivers. It is very, very low level. E.G. AHA154X.ADD is driver that is responsible for the Adaptec SCSI Adapter. This driver is added to the CONFIG.SYS via BASEDEV= 2. A physical device driver (the "normal" driver) is added to the config.sys via DEVICE It is loaded after the base device drivers and before any application. Physical device drivers are always 16-Bit. 3. A virtual device driver is a special device driver. It is used by a virtual DOS machine to virtualize hardware. DOS programs can access hardware directly which is not allowed with OS/2 (s.a.). Therefore the hardware is "simulated" by the virtual device driver. The virtual device driver can communicate with a physical device driver. from the technical point of view a virtual device driver is a 32-Bit DLL. WatchCat uses a physical device driver (watchcat.sys) to by-pass the standard key processing. Therefore WatchCat notices its hotkey even when the PM is blocked. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ WatchCat uses the CuTe technology (continous update technology) for quickly updating the windows. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The OS/2 Presentation-Manager is an event-driven system. All events in the system (e.g. moving the mouse or pressing a key) are converted into a message an put into a global message queue. The applications take the messages from this queue. This is done in a serial way. The second program cannot get a message while the first application is still working on its message. Therefore one application can stop the whole system. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ The WPS (Workplace Shell) is the graphical user interface of OS/2. An WPS object is simply an icon (and its functionality). All icons on your desktop are WPS objects. Objects with the same functionality are grouped to a WPS class. Mostly one class has many objects. For example there are many folder objects which are instances of the folder class. Some classes only have one object (e.g. WatchCat). Classes that are not part of OS/2 (e.g. WatchCat) must be registered (just to tell the system that they want to be used...). This task is done by the installation program. ΓòÉΓòÉΓòÉ <hidden> ΓòÉΓòÉΓòÉ A dynamic link library (DLL) is program code that is linked to an application when the program is started. A DLL can be shared by many different processes. There are two ways of using a DLL: 1. load-time dynamic linking: The DLL is loaded when the program is started. The DLL is not part of the application, but there are references to the DLL in the program. 2. run-time dynamic linking: The DLL is loaded via an explicit command in the application. The program does not have any references to the DLL. The DLL is not loaded until the explicit call. WatchCat can display all run-time linked DLL in the Library window. ALL DLL will we displayed in main window (if "all modules" is selected).