
 README file for PAF WatchDog Package v. 1.00
 Document No. 2303-2441123887
 Date of creation: 23.08.2006


WELCOME TO THE PAF WATCHDOG PACKAGE VERSION 1.00
We welcome you to the PAF WatchDog package, version 1.00. This file contains 
important information about the software inside the distribution package you 
obtained. Please read this file carefully.

_____________________________________________________________________________

TABLE OF CONTENTS
  A. PRODUCT OVERVIEW
  B. PREREQUISITES FOR INSTALLATION
  C. INSTALLING AND UPDATING THE PACKAGE
  D. USING THE WATCHDOG FOR CONTROLLING TASKS
  E. FEATURES OF NEXT RELEASE
  F. NOTES ABOUT THE GERMAN HELP DOCUMENT
  G. SUPPORT AND UPDATES
_____________________________________________________________________________


A. PRODUCT OVERVIEW
During the development of the network systems software for our Arolithe PC
servers of the Epoque series, it turned out that a utility for low level
system access would be a desirable feature. Additionally, some of the TCP/IP 
demons occassionally had some errors which caused the system to end their 
processes and we needed a way to restart them after the crash without any 
human intervention in a fast and reliable manner. The answer to this and
similar problems is the PAF WatchDog system.

The PAF WatchDog package is a software system that enables users to get
important system information on a process (on aerolitheOS: on a task) level.
It consists of two parts: a demon process running in the background as AGDTP
server, and a GUI frontend acting as AGDTP client. This version of the
package works with local IPC connections only. With one of the next releases,
the frontend can connect to backends on other hosts of TCP/IP networks. This
allows system maintenance at a very low level from remote hosts. 

The watchdog system provides the following features:

o Getting system information about processes, their threads, semaphores,
  and shared memory blocks.
o Gathering CPU processing time information of running tasks.
o Killing processes that behave abnormal or that cannot be terminated on
  a normal basis.
o Oberserving tasks that registered with the demon and restart them 
  automatically in case of fatal errors.
o Causing tasks that registered with the demon to shutdown gracefully for
  system software maintainance.
o Restart tasks previously ended or killed.

We will enhance the watchdog package with forthcoming editions for getting
other system related information. Note that such features may require the
aerolitheOS Support Driver (available for free on our homepage). Additionally, 
future releases of the PAF runtime allow using IR and/ or serial ports to 
access watchdog demons on other systems without using a network connection. 
We also plan to include a scheduler inside the PAF WatchDog so that tasks 
can be started and ended depending on a predefined time schedule. 


B. PREREQUISITES FOR INSTALLATION
You need OS/2 Warp 3 with FP 32, OS/2 Warp 4 with FP 15 or any other higher 
version of OS/2 up to derivates like WSeB and eCS to install and use the 
PAF WatchDog software package successfully on your system. PAF Pre Edition 1
with FP 2 or higher must be installed on your system. The PAF WatchDog is 
FREE software for registered PAF users. However, you can test the package 
during the test period of unregistered PAF systems. If you like the program 
and want to take further use of it, you must register your PAF copy. You 
find information about the registration process on this site:

http://www.cef-it.de/pages/en/software/paf_howtoreg.htm

and the current registration fees here:

http://www.cef-it.de/pages/en/software/paf_fees.htm

If you have any further questions, please contact our support by writing an
e-mail to support@cef-it.de.


C. INSTALLING AND UPDATING THE PACKAGE
You can start the installation process by a double-click on the icon of the
distribution package or by typing the name of the package into the command
line. The package will then copy the files into your PAF directory structure.
You do not need to restart your system after installation to load the modules.
Just refer to the 'PAF WatchDog' folder in the 'PAF System' folder located on
your desktop to start the watchdog GUI. The WatchDog demon must be up and
running before the GUI is started. Please read the GUI control program's help
document carefully before using any of the watchdog's enhanced features.
Simply press the 'Help' button in the program's toolbar to display the help
document.

If the version of the software is lower than that of the distribution package, 
you can update your system appropriately. The installation program will cause
the watchdog demon (and also the GUI) to shut down gracefully before files
are replaced. The programs are reloaded automatically after the update, no
system reboot is necessary.


D. USING THE WATCHDOG FOR CONTROLLING TASKS
Besides providing information, the PAF WatchDog allows killing of processes. 
Note, that there are not any security functions available with the PAF Pre 
product line on OS/2, thus you can use the WatchDog for manipulating any 
process in the system. If a process is killed, it cannot shutdown gracefully, 
if it has not got an exit list routine. This usually results in loss of data. 
Therefore be cautious while killing tasks.

D1. Real Watchdog Functionality
Standard OS/2 applications cannot use the enhanced features of the watchdog 
package. However, if you are a PAF class implementor, you can register your
document class instances with the watchdog. Note, that this function 
can also be used by any kind of other application on OS/2, if it uses an AGDTP 
communication object to communicate with the server component of the watchdog. 
This causes the document or program to connect to the watchdog for resetting 
a counter in the watchdog's data area at specified time intervals. If the 
application cannot reset the counter, the watchdog assumes that the document 
is no longer in an active state. It then destroys the document's process (if 
there still is such a process) and restarts the document if you have set the 
appropriate service option while registering the document view with the PAF 
WatchDog. 

D2. The Process Watch List Feature
You can use the GUI frontend of the watchdog for telling the demon to check
specified process IDs regularly if these IDs refer to running processes. 
This enables you to let the demon restart other applications that cannot 
register with the watchdog since they are not PAF aware. You can use this
feature as long as the application does not use AGDTP to communicate with
the watchdog to ensure proper watchdog operation. 
Selecting processes for being watched by the watchdog is easy. Simply mark
those processes in the 'Process List' tab, call the context menu and select
the item 'Add to PWL'. PWL is an acronym for 'Process Watch List'. Once
a process has been added to the list it will remain there also across system
reboots. The watchdog takes care of its PWL entries and restarts them if
necessary. Note that you should remove programs controlled by the watchdog
from the auto start folder of WPS, your startup.cmd or the config.sys. Simply
let the watchdog do this work for you and maintain your PWL with the GUI of
the watchdog's frontend. 

D3. Controlling PM applications
The PAF WatchDog is useful to terminate processes that block the system or
parts of other subsystems for systems software maintenance. For the OS/2
GUI is based on a single system event queue, the watchdog can also be used
to terminate PM applications that cause GUI 'hangs' which WILL happen on 
OS/2 from time to time. However, using the watchdog for this purpose makes 
sense only, if the watchdog demon can be accessed from a remote host within 
a network, since - on OS/2 - its GUI frontend is also blocked like any other
PM application.


E. FEATURES OF NEXT RELEASE
The next release of the PAF WatchDog package allows the GUI frontend of the 
watchdog running on a local system to connect to another backend running on 
another host of TCP/IP networks. This enables controlling a host system at 
its process level for software maintenance tasks from remote hosts. Using
this feature requires PAF Pre 1 with FP 3 or higher to be installed on both,
the local and the remote host.  


F. NOTES ABOUT THE GERMAN HELP DOCUMENT
The German version of the PAF WatchDog GUI Client program's help document
had not been finished at the time of the product's release thus the package
contains the English version only and also the German program version will
therefore display the English help document. We will release the German
version of the help document as fast as possible. You can request it by
e-mail or download it from our homepage. Please check the newsarchive on
our site to get more information.


G. SUPPORT AND UPDATES
Support is for free. If you encounter any problems, please write an e-mail
to support@cef-it.de and include all information about the error condition
you can share with us, e.g. contents of trap screens, error messages etc.

The PAF WatchDog package is subject to frequent changes and you should always 
use the lastest version. Updates can be found in the support section of our 
homepage. For your convenience, you can also subscribe to ESDS in order to get 
the lastest build by e-mail. The program's homepage can be found here:

http://www.cef-it.de/pages/en/software/ssp_cefit_pafwtdog.htm

If you have any further questions, do not hesitate to contact us.



 End of Document - Copyright (c) cef-IT, Clemens-E. Fischer.
 -- Homepage    : www.cef-it.de
 -- Free support: support@cef-it.de
