TOP 0.3 - Ian.Hargreaves@ibm.net

Disclaimer
==========
THIS IS AN EARLY VERSION! IT IS BEING PROVIDED PRIMARILY FOR EVALUATION 
PURPOSES ONLY. PLEASE DO NOT USE THIS SOFTWARE IN ANY PRODUCTION ENVIRONMENT.
THE AUTHOR CANNOT BE HELD RESPONSIBLE FOR ANY LOSS OR DAMAGE CAUSED BY USING
THIS SOFTWARE. BY READING THIS YOU AGREE TO THE ABOVE TERMS AND CONDITIONS.
IF YOU DO NOT AGREE TO THESE TERMS - PLEASE DESTROY ALL COPIES OF THIS 
SOFTWARE. 

THIS SOFTWARE IS PROVIDED AS IS AND COMES WITH NO WARRANTY OF ANY KIND. 


License
=======
This software is E-MAILWARE. Simply send me an e-mail to Ian.Hargreaves@ibm.net
and you can use this software for as long as you want.

The software and all associated files are copyrighted by Ian Hargreaves. You 
may copy this software for backup purposes. You may also copy and share 
unmodified copies of the whole package, providing that the copyright notice
is reproduced and included on all copies.


Introduction
============
This utility is similar to the Un*x tool TOP. It displays a list of processes 
and the amount of CPU they are using. The amount of CPU is calculated using 
the undocumented OS/2 call DosQProcStatus. This function gives details for each
thread on how much SYSTEM (kernel time) and how much USER (application) time is
being used.

This is NOT a load monitor - the statistics displayed are not real time, they 
are the statistics for the previous monitoring period, which is currently 2 
seconds.

The load is calculated by comparing the amount of CPU that a process has used
in the current monitoring period compared to how much the same process used in
the last monitoring period.


Display
=======
A list of active processes is displayed and sorted according to the current
sort specification.

Processes are displayed in colour according to how much CPU they have been
using .... 

    0%  - 33% GREEN 
    34% - 66% YELLOW 
    67% - 99% WHITE_ON_RED 

Here is some sample output from TOP...

Procs:26  Threads:119 Ready:2  Loaded:3  Blocked:113 Time:13:11:52 Up:  3:03:48
Total CPU     CPU% Avg% Pid Thr Pri Name
  0:00:01.209  0.0  0.0   6   1 200 C:\IBMCOM\LANMSGEX.EXE
  0:00:00.155  0.0  0.0   4   1 21F C:\OS2\SYSTEM\LOGDAEM.EXE
  0:10:57.665 30.6>25.2  22  24 200 C:\OS2\PMSHELL.EXE

Procs:      Total number of running processes.

Threads:    Total number of threads

Loaded:     Threads that are loaded but not running or blocked - used to keep
            processes in memory without them actually running

BLocked:    Blocked threads - waiting for some event to happen.

Time:       Guess.

Up:         System up time.

Total CPU:  Total amount of SYSTEM and USER time this process has used.
            (HH:MM:SS.MMMM)

CPU%:       The percentage of the total CPU usage in the last time period that
            was used by this process

Avg%        Average CPU percentage of this process (reset by pressing A)

Pid:        Process identification number. Each process is given a unique 
            identification number before it can start execution. This number
            could in theory loop around to start from 0 again.

Thr:        The number of threads this process has created.

Pri:        Process priority. Processes don't actually have a priority - 
            threads do. This is the figure for the priority of the first thread
            in a process (every process has at least one thread).

Name:       Work it out yourself.

Please note that the the loaded+blocked+ready threads does not equal total
threads. This is because the number of running threads is not included, and
unless you are lucky enough to have a multi-processor system - you will only
ever see one thread in the RUNNING state.


Keyboard Options
================
The following keys may be used once top has started.

F1  - Display this help text

F3, X, Q, ESC
    - End program

S:Sort Options
    U: Sort by percent CPU Usage
    T: Sort by Total CPU Usage
    P: Sort by Process ID
    N: Sort by Process Name
    I: Sort by prIority
    O: nO sort order

Process Name
    N: Toggle full path,  or .EXE name only

Kill Process
    K: Enter PID Number - This will only kill the top level process 
       NOT the whole process tree.

Memory/Process Details
    M: Toggle display of memory, and swap or process summary

Average CPU Reset
    A: Resets CPU average to 0, and re-starts average calculation

Display Process
    D: Enter PID of process to display

Page Up/Down
    Move process list up/down for long lists


Technical Information
=====================
TOP uses only 2 threads - one to process keyboard options, and another one to 
call DosQProcStatus, calculate usage, and display the results.

Both threads run at the default priority class and in total will not impact 
system performance by any significant amount.

TOP is a VIO mode program. This means that if you increase the number if lines
that are available at the command prompt, TOP will use those extra lines to 
display more information.

So, it might be a good idea to run choose a smaller font, and set the number of
lines to 50 .. [C:\]MODE CO80,50

By the way - remember this is NOT a load monitor. Most load monitors work by 
having a background thread run constantly to calculate CPU usage.

TOP spends most of it's time sleeping between screen updates during which time
the CPU is free to do other more useful stuff.


Known Bugs
==========

Very large numbers appear sporadically in CPU usage column under heavy system
load.

Sometimes CPU usage is 0 for all processes or 50% for just one process.

Contacting the author
=====================
Please feel free to provide any feedback - positive or negative, and/or
enhancement requests to the author at the following addresses.

E-Mail:     Ian.Hargreaves@ibm.net  (preferred)
Compuserve: 100432,2162

------------------------------------EOF----------------------------------------