user documentation            CADH                        Veit Kannegieser




Installation
------------

  a)

  install using the WarpIN package

  OR

  b)

  move cadh.sym and cadh.sys to \os2\boot\

  add a "basedev=CADH.SYS" config.sys line

  run cad_wps.cmd to create an icon in the startup folder

  reboot


  put TOP.EXE from <http://home.clara.net/orac/os2.htm#top>
  somewhere reachable on %PATH%.


known problems
--------------

 * System shutdown asks to terminate program

   workaround:
   a) disable confirm

   b) kill the process from enhanced shutdown
      recommended and automaticly used

   c) use "RUN=\OS2\APPS\CAD_POP.EXE" in config.sys
      will NOT work correctly! (command shell hangs in endless prompt)

 * It seems not be possible to activate the menu during
   Lockup (even in screen saver mode). I do not think
   that i need to change that. 
   Doodle's Screen Saver does not prevent fullscreen popups.


ideas
-----

 * add function to mute/unmute audio 
   likely in an separate package using user defined hotkeys
 * mouse access - like the hard error popup?
 * network login/logoff?
   add it to the menu, if you want..
 * how do i kill "unkillable processes?" (exitlist..)
   - break in an create sleeping extra thread that can
     woken up and kills the process/alters priority
     - like watchcat addon: api filter
     - hook dll
   - use new just in time debug attach to free resources
     and end processes? - use debug command to alter cs:eip registers,
     write custom code to program, close open handles,semaphores,..
 * create online ipf helpfile
 * process list should use scroll bars (mouse?) or scrollable pageup/down
   when having too many processes/windows
 * cad_pop.exe could unlock itself to avoid confirmations when updating
   using WarpIn.

user requests
-------------

 * add date/version to distribution ARJ filename.
 * Signals (Dos16FlagProcess..)
 * in List window, add cursorkey movement to select target.
 * priority modifications
 * password protected menu entries?


hints
-----

 * You can use
   rmview /d | find /i "cadh"
   to find out if cadh.sys is loaded

 * pressing the hotkey during applications that use VioScrLock, will take
   about 30 seconds timeout after the beeps before the popup will appear, 
   on return from the popup the displayed image may be corrupted.

 * the popup will also not display until you exit from an
   hard error popup (like cmd /c a: with an empty floppy drive),
   possible solution: use MGL?

 * after the beeps, pressing Ctrl+Alt+Del again before exit from the popup,
   will cause the usual reboot function, you can press the hotkey again
   after exit from popup and hearing beeps.

 * you can use hotkey definitions in your own programs.
   planned example: master volume setting using Alt+Num+/Num- from
   inside any program (PM, Fullscree, DOS) by simply waiting for an
   event semaphore..


how it works
------------

  Cadh.sys alters kbdbase.sys code that sends a system message when CAD is
  detected, the modification causes a call of code in cadh.sys.
  Cadh.sys will either send the system message, or if any program has
  registered an event semaphore with cadh.sys, it will post that.

  Cad_pop.exe creates an named event semaphore '\SEM32\CAD_POP' and
  registers it with cadh.sys. Then it waits for an event. cap_pop.exe runs
  at a very high priority to cause instant working in case it is woken up.

  Currently cad_pop uses VioPopup services to take over keyboard and screen.
  This means that the menu can not displayed if another popup is already
  running. The VioPopup documentation says that only limited set of
  functions is available during popup, but so far all needed things like
  an external command shell run well, the only thing not possible is
  lauching PM or DOS programs.


other hotkey combinations than Ctrl+Alt+Del
-------------------------------------------

  Default activation event is pressing the reboot keyboard sequence.
  Using "cad_pop.exe /Event:6,$ff,4,$ffff", you can have the menu
  program wait for Session Manager hotkeys instead.

  Use LIST_SMH.EXE to display defined session manager hotkeys.
  Usually they should be:
    2: any Alt+Esc (switch between windows)
    1: any Ctrl+Esc (show task list)
    3: any Alt+Home (toggle windowed/fullscreen)
  fsHotKey are the shift state bits that have to be set.
  uchScancodeMake and uchScancodeBreak are the key make and break codes.
  Most times the break code is $80+make code.

  Use ADD_SMH.EXE to define additional session manager hotkey. There
  can be up to 16 hotkeys. Usage is:
  ADD_SMH.EXE fsHotKey uchScancodeMake uchScancodeBreak idHotKey

  fsHotKey bits:
    11 Right Alt key down
    10 Right Ctrl key down
     9 Left Alt key down
     8 Left Ctrl key down
     1 Left Shift key down
     0 Right Shift key down

  For Scancodes, look into programmer manuals.

  idHotKey is used as identifier. Range 1..$fffe. Using existing ID
  causes the existing definition to be replaced, so use ID >= 4.

  Example: ADD_SMH $0000 $4c $cc 4
  This defines Numeric(Keypad) 5 (key $4c) without any modifier as
  Session Manager Hotkey 4.

  The above "cad_pop.exe /Event:6,$ff,4,$ffff" can now explained as
  wait for event 6/exact -- 6=Session Manager hotkey,  having
  argument 4/exact -- Argument for Session Manager is the Hotkey ID.

  The default setting in cad_pop.exe is "/Event:7,$ff,0,0", which
  means reboot sequence, ignore argument.


  System Event                  cad_pop event option

  Ctrl+Break                    /Event:1,$ff,0,0
  Ctrl+C                        /Event:2,$ff,0,0
  Ctrl+NumLock                  /Event:3,$ff,0,0
  Ctrl+PrtSc                    /Event:4,$ff,0,0
  Shift+PrtSc                   /Event:5,$ff,0,0
  Session Manager Hotkey        /Event:6,$ff,xxxx,$ffff
    Ctrl+Esc                                 xxxx=1
    Alt+Esc                                  xxxx=2
    Alt+Home                                 xxxx=3
    your own...                              xxxx=4..
  Reboot key sequence           /Event:7,$ff,0,0
  
  Some of them do not work, or would be unpleasant to replace the
  original function, using reboot hotkey or defining an new is recommended.

  
changes
-------

   2003.06.19
   cadh.sys improvements by Dietrich Teickner
    * Warp 4 fp12 compatible (kbdbase.sys has other jump)
    * works better during high cpu load?
    * allocate context hook only after successful search for patch code
    * protect driver for only one basedev init command
    * optimisations
   tested cad_pop with 4OS2 (version 3.04B), have not found problems
   cad_pop beeps and waits for keypress on startup errors.
   error handling for CMD/TOP shells

   2003.07.20
   if cad_pop is running detached (detach cad_pop.exe or
    run=E:\OS2\APPS\CAD_POP.EXE in config.sys), then the screen
    was not painted correctly
   added process code similar to pstat/ps/go
   added filter list for process list (cad_pop.hid)
   2003.07.21
   process list filter switchable ('F')

   2004.08.18
   corrected spelling errors
   added menu configuration file cad_pop.mnu
    note: only read at program startup, you need to quit and
          restart the program
   search cad_pop.mnu/hid in %home%, then in program directory
   unlock open executables on unmount on error code 108
    open *.cat/*.ir/*.ttf files still prevent unmount
   added option to provide menu functionality even when
    cadh.sys is not loaded: "CAD_POP.EXE /NoCadH"
   split wpi in two packages, driver directory fixed, app directory selectable
   added resource manager support to cadh.sys
   restore switch list entry when program exits.

   2004.08.31
   nl translation, thanks to Jan van der Heide
   corrected handling of non-printable keys in menu. example: Delete

   2004.09.01
   simplified translation and made key usage translateable

   2004.09.02
   updated nl translation

   2004.09.09
   WarpIn installation did not install executable correctly since package
    split (2004.08.18)
   use OS error messages for 'unknown' errors.
   added semaphore lock to screen updates from mount/unmount threads

   2004.12.06
   added russian translation, thanks to Yuri Proniakin
   excluded FAT32 from unmount

   2005.01.15
   changed to use
    DosSetPriority(prtys_ProcessTree, prtyc_TimeCritical, prtyd_Maximum, 0);

   2005.02.09..12
   Italian translation, thanks to Gabriele Gamba!
   reenable switch list entry, when displaying driver ioctl error messages
   add CAD_POP.EXE to eStyler shutdown kill list
   add hotkey option! - session manager hotkey events with masks..
   cadh.sys allows now more than one program waiting for an event,
    only semaphore of last registered filter is posted
   added configuration file cad_pop.cfg, place it in %hom%.
   user selectable text mode, menu adapts to it.
   confirm remove/reboot
   password protection (dont laugh)
   function keys F1..F12 can used in menu definitions
   cahnged default to no beeps
   added usual /Q /V /W message level parameters for basedev=cadh.sys

   2005.05.11..2005.06.17
   code used DOSCALLS.DLL, sometimes DOSCALLS, unified it.
   added zh_TW translation by Ming-Lung Cheng.
   added french translation by Guillaume Gay
   use color coded keys in menu status line
   created translateable sources only package
   updated dutch, russian and italian translation for password 
    and other activation methods
   replaced the used public event semaphore from \sem32\cadh to
    \sem32\cad_pop. Now when loading ProcMan (jma) after CAD_POP,
    ProcMan has a chance to pop up -- instead of cad_pop, since
    cadh.sys selects to triggers the semaphore registered by the 
    last program: ProcMan.
   close cad_pop.cfg after reading it
   WPI install paths will be set to \ecs\bin and \ecs\doc\cadh
    to overwrite old versions, if they exist from eCS 1.2 install.
    
   2005.07.03
   changed WarpIN script rexx code to remove trailing path char,
    thanks to Hanno Sedlmayr for noticing this!
   added hint for warpin install: unlock cad_pop when prompted,
    moved description to an separate welcome/readme page.
    
   2006.01.31
   added spanish translation, thanks to Alfredo Fernandez Diaz!
   cadh.sys source code beatification, added warning message
    when hotkey table in KBDBASE.SYS could not be found.
  
   2006.10.29
   updated spanish cad_popd messages, thanks again to 
    Alfredo Fernandez Diaz!
   updated WPI archive: cosmetics, addresses, 
    removed BASE tag, to avoid having target directory 
    C:\ECS\BINC:\os2\boot
