
		  	  	XZET	1.0

		    Graphical System Activity Monitor		

    		         	Zman 02/94




	This document is divided into the following 7 sections:

	I.    What is XZET?
	II.   What are XETAT and TOP, and why the kludge?
	III.  What environments will XZET run in?
	IV.   What "undocumented features" does XZET have?
	V.    What is in the future for xzet?
	VI.   Tell me something good
	VII.  How do I build xzet from the source?





I.   What is XZET?
------------------

XZET is an X windows application which is Zmans' vesion of Xetat and Top,
hence the name XZET.  It provides 3 different types of real time system 
resource monitoring windows.  The first is a global system activity window
which displays stripcharts of global idle, user, system and nice
percentages.  It also displays stripcharts for free swap space and free
physical memory.  Finally, it has displays for global process counts and
states, and free space monitoring of up to three file systems.  A second
window lists information on every process running in the system.  The
information varies based on whether a short or long format is selected. The
long format is quite complete.  The user can toggle the state of this list
between "frozen" and "auto-updating".  If an entry in the list is selected
with the mouse, a third and final window type will appear.  This is an
individual process window which features an updating tachometer widget for
both the processes percent cpu load and the percent physical memory load.
Information similar to that provided in the short format of the global
process list is also enumerated.  



II.   What are XETAT and TOP, and why the kludge?
---------------------------------------------------

Xetat was created by Pierre FICHEUX of Lectra-Systemes Service R & D, and
is designed for UNIX System V release 3.2.  It is completely dependent
upon being able to read kmem and extracting pointers from the namelist
contained therein. It is an X windows application that provides graphical
system activity monitoring.  This code started out to be a simple conversion
of xetat, but it mutated into xzet for reasons (which are either obvious or
just plain not very interesting).  I have never actually seen xetat running
but the "Activity" window should look very similar (minus the file system
monitors and the global process state information) to what xzet displays.  
The global process windows for xzet and xetat are completely different, while 
the individual process windows are vaguely familiar. The underlying guts are 
radically different, due mostly to the influence of Top.

Top was created by a variety of people.  The ones credited in its' source are:
Branko Lankester, Roger Binns, Michael K. Johnson, and Robert J. Nation.
Top is a character based application which provides a continuously updating
list of the highest cpu utilizing processes (the top processes?).  It also
supplies global information about cpu and memory utilization and process 
states.  Its kind of a Super-PS.  What most interested me in top was the
fact that it get its information by reading the proc file system.  The tech-
nique it uses to read and maintain a database of knowledge about this file
system is simple and elegant. (IMHO)  I was able to create a standalone
module of less than 350 lines (with plenty of whitespace) which encapsulates
most of this functionality.  (By the way, this module is called bit-o-snap
and could be easily linked into any enterprising programmers code.  It does
not contain a single line of code which depends on anything in xzet.)     

Given the fact that all of this work came about as I was training myself on
Linux, which supports the proc file system, the reason for xzets
metamorphosis from the two should be obvious.



III.   What environments will XZET run in?
------------------------------------------

I have never run xzet on any operating system but Linux, but it should be 
a simple matter (really) to convert it to any system which supports the proc 
file system.  I am not sure if this is a standard feature of Unix System V
release 4.x, but all of the rel 4's that I have seen support it.  The truly
adventurous could get it to run on any system by merely duplicating the
functionality of 'bit-o-snap'.  (Take that "merely" with a boulder of salt.)
 
Xzet was developed and is run on a 386/33 with 8mb of memory.  On this
machine it takes about 15% of the cpu resources to run.  This is about the
same as Top utilizes, which I consider to be a pretty decent accomplishment
given that xzet is an X-windows application and Top is character based.
If you close down all pop-ups, the process list, and the system activity
monitor, xzet will idle itself. On my system this brings its cpu utilization
to between 0 and 0.1%.  This allows you to leave xzet available on your
desktop without having it consume any real cpu slices.  Be sure to quit
the windows versus just iconifying them.



IV.   What "undocumented features" does XZET have?
--------------------------------------------------

I have endeavored to make xzet as bug-free as possible, but it does have 
a few valid reasons why it might not be perfect:  1) It is the first 
X-windows application I have ever written, and the only X programming manuals 
I have are Doug Youngs (excellent) and O-Reillys "X Window System in a
Nutshell" (Probably really useful to people who actually have real programming
manuals).  2) I don't have any Linux manuals at all, let alone a
hitch-hikers guide to the kernel, which would have been really useful to a
born OS wHacker like myself.  3) The Ztach widget used in the individual
process windows was my first attempt at a widget (even though it is largely
created from John Cwikla's hdial widget [his first attempt]).  With that
said, I reiterate that I did strive to put as much quality into xzet as I
could, and I am running it even as I type this novella of a readme.  

There are  two "sort-of" bugs I have seen while running xzet which I have
not been able to isolate (and therefore exterminate). The first is very
rare, but when it has occurred it seems to hang out for 10 or 12 iterations.
Its rareness (you may never see it) leads me to beleive that it may be a 
Linux/XFree/GNU bug.  The bug manifests itself when the program is first
started:  you get the outline for the top-level window, but before you can
"click it down" (or immediately after) the process terminates with a "Bad
Window" error.  As stated, it may then do this for the next 10 or 12 attempts
to start the program, and then the problem will not show up for weeks. 
Someone with more knowledge of X than myself may be able to interpret the
error better than myself and tell me how to solve it....if so let me know.  
The other bug only occurs when the global processes window is in the short 
2 column mode.   Sometimes it occurs when you switch into this mode, other
times I have seen it occur when you are in this mode and you either select
a process to monitor from the list or when the system activity gets high.
What happens is that the list will be 2 columns wide, but only 1 column of
data appears in the window (the left column).  The fact that I have seen
this problem correct itself also makes me wonder about its true origins. 
This is not as rare as the first problem, but you still may never see it. 
I solved a very similar problem which was related to starting xzet in single
column mode, so it is possible that the two are related.  If it would rear 
its ugly head more often, I would be all too glad to take another whack at it. 

If you discover any other bugs, or have salient input on these two, do 
not hesitate to contact me.  Unfortunately, at present I have no real 
access to the internet, so it will be very inconvenient to get bug reports 
back to me.  It is possible that internet mail forwarding will be provided 
to me in the not to distant future, but for now I can only be contacted at 
LTR via phone or mail:
		Loganville Technical Resources, Inc  (404) 466-8544 
		5145 Ozora Church Road
		Loganville, Georgia   30249  USA 



V.  What is in the future for xzet?
------------------------------------

That depends on X users like yourself.  I would have liked to have added
more monitoring capabilities to xzet, but as I have stated earlier, I don't
have any of the required documentation.  I have thought about adding the 
ability to kill tasks on the global process lists, (both manually AND 
automatically, through a kind of a configurable "watchdog")  and perhaps 
the capability to browse  through the tasks memory.  I gave some thought to
adding a "peak hold" feature to the Ztach widget, put dropped it as being
perhaps a bit too gimcrackery.  I would like to be able  to monitor system I/O 
in a variety of ways, such as Disk I/O, Network I/O,  Serial I/O etc. I would 
also like to be able to monitor the R/W (and other?)  Cache hit ratios and 
the number of open files, inodes, and related structures. Of course the danger 
in adding these types of facilities is that the application becomes too 
'OS-centric' and therefore less people will be able to use it.  Still if I 
can get the documentation, I will probably start experimenting...     

I am also considering making xzet part of a larger set of
'Z-utilities'.  I have yet to find a file manager for X which I find as
useful as the character based one I converted to Linux as my first
programming effort in that environment.  It has default actions for 
Directories, Regular Files, ZIP'd, GZIP'd, Compressed, and TAR+GZIP'd 
files based on the non-case sensitive extension (.zip, .gz, .z, .tgz) of the 
files (these can also be done manually).  It also has commands for calling
graphics and animation viewers, an editor, and  "regular", "man pages",  and 
binary file browsers.  I personally find it impossible to use unix (or
Linux) without it.  Another part of the utilities would be an intelligent
file system editor which a fellow bit-pusher and I have hacked on through
the years.  It will be a lot of work to get it to run under the technicolor
variety of file systems Linux supports.   

Thats the big picture.  How much of this that I actually accomplish (or at 
least get to a distributable form) depends on you.  I have expended as 
much (probably more) non-remunerated time as I can afford, given my present 
situation.  Understand that I am NOT solicting donations of money for xzet.  
It is my gift to the Linux community (and anyone else willing to spend the 
time to get it to run on their machines).  However (theres always a 'however',
isn't there?), if anyone has any printed copies of a Linux Kernel Design 
Document (or whatever the hackers bible for linux is called) or any spare 
copies of the O'Reilly  (or anybody elses) Xlib and Xtoolikt Programming 
and Reference Manuals I would certainly be grateful...  Most importantly, 
I would be interested in  hearing from the X-windows community on the level 
of interest in xzet and in this stated course of action.       
 


VI.   Tell me something good
----------------------------

For everyone that has stuck with me this far, I offer some "good stuff
to know".  Application resource files are a great way to make your code look
clean, but a look at xzet's file may leave your head spinning.  What parts
of this file should you mess with?  First of all, at the beginning of the
file are the 3 labels for the file system monitors.  The first one is labeled
"XZet*zman_fs1*label: Free On Root:", and the other two immediately follow
it.  Change these to reflect whatever has meaning to you about the file
systems you want to monitor.  If you don't want to monitor file systems, you
can put whatever you like here (13 chars max with defaults). Just under this
section in the file you will see the place to actually specify the mount
points of the systems to be monitored.  The first of these is labelled as 
"*zman_fs1_mount_point:  /", with the other two immediately following. 
Change these to be relevant to your system and desires.  Leave them blank if
you don't want to monitor file systems (or don't have three to monitor).  By
the way, the monitors show numbers such as "2684K/433K".  This means that
there are 2684K bytes available to the root user and 433k to everyone else.
While in this area, you will see the labels for changing the size of the
global processes list and for changing the magnification factor of the free
memory stripchart (they are under the labels for the file systems).  These 
may be also be changed if you like (not the "XZet*zman_free_scale*label:"
which is under program control). Under the mount point specifiers are the
scale factors and then the labels for the global cpu activity stripcharts. 
I do not recommend changing the cpu scale factors since they are set to 
keep the scales in direct proportion to one another. (They are at 1000
because the program uses 1000 to refer to 100%.)   Feel free to change the
labels to whatever makes the most sense to you.  Around line 200 of this
file you will see labels and sizes for the quit button of the global
activity monitor and for the top-level xzet window.  Look for the header
"Buttons for the toplevel xzet widget".  There is plenty of room in the
global activity monitor to make the quit button much larger if you think it
looks a bit small given all the whitespace around it.  You may also feel
free to completely change the configuration and labeling of the top-level 
xzet window.  The definitions for the process module related widgets are in
the next section of the file.  The process list quit and auto update/freeze
toggle button are the first items in this section.  The a.u./freeze button
is necessarily labelled under program control, so altering its label  is 
useless.  After these are the definitions for the window resize buttons. 
The labels for the resize buttons are located at the top of this file in the
same section as the earlier referenced file system monitor labels.  Be
careful changing the configuration of these buttons as this can cause the
process list window to grow uneccessarily large in single column short mode. 
Immediately following the resize buttons are the definitions for the
individual process window resources.  Since these are prototypes, the
referenced resources require explicit getting and setting when creating new
process monitoring windows.  For this reason any changes made in this
section which involve adding new specifiers will have no affect.  You can
safely change the labels on the tachometers, as long as the length of the
knew labels is kept short. You can also change the rotation of the memory
tach to be clockwise by changing the value of the 'rotateCW' boolean from 
false to true.  The default of 'false' causes it to spin opposite that of
the cpu tach, an effect which I prefer.  The final two lines in the file
specify the size of the longest element in the process list and the default
number of columns of the list.  The default number of 460 is correct for the
machine xzet was developed on (using the 'fixed' font).   This actually
specifies the length of a short format entry.  The program calculates the
length of a long format entry to be about 1.5x that of a short format entry.
Be sure to change this number if you decide to use a larger (or smaller)
font.  The default number of columns should always be set at either 1 or 2
since the program is set up to allow the user to interactively toggle 
between these two widths.  All other labels, sizes and positions are better
of left alone since there a quite a few dependencies woven amongst them.



VII.  How do I build xzet from the source?
-----------------------------------------

If you are running Linux, then it should be extremely easy to build xzet, 
with no changes on your part needed at all.  Other OS's that support the
proc file system should only require minor changes (probably to the names of
some of the system level include files).  If your system doesn't support the
proc file system, then the easiest thing to do will probably be to duplicate 
the services provided within the file 'bit-o-snap.c'. That will permit you
to leave all of the rest of the source code untouched (except, as noted above,
for changes to the names of include files).  Of course, if you have System V
Rel 3.2, you may just wish to get a copy of xetat from the comp.sources
directory, volume 17.  
 
================ Starting point for patience impaired users =================
			
Changes to the code aside, once you have untared (or whatever...) the source 
code, the first thing to do is enter the sub-directory 'Ztach'.  This contains 
the source code for the tachometer widget which is used by xzet. This is a
complete distribution for the widget, including a README file, man pages,
and most importantly, an Imakefile to build the widget and a small test
client. Build the make file using either 'xmkmf' or using 'imake' with a
command line similar to the following:  

imake -DUseInstalled -I/usr/X386/lib/X11/config

Then run the 'make' command to generate the widget object and the test
client.  The test client is called 'ZtachT' and may be run at this time to
verify correct compilation.  (See the man pages and readme for further
information.) 

Once the tach widget is built, return to the main xzet directory, and create 
the make file for xzet using the same procedure specified above for the Ztach.

At this point, a 'make depend' may proove useful in finding include files
whose names may need to be changed.  I suspect that some of the  following 
files may need to be changed:  <linux/kernel.h>, <linux/sys.h>, <linux/tasks.h>,
<unistd.h>,  <sys/vfs.h>, <sys/dir.h>, <sys/user.h>  and <regex.h>.  
VFS.H is most notable here because it contains the struct for the 'statfs' 
call used to monitor the freespace in the user specified file systems.
TASKS.H only contains the 'NR_TASKS' define which sets the maximum number of
tasks which Linux can run.  Create your own file, or move the define to the
source code if your system doesn't have this file. SYS.H defines some of the
system calls (statfs), and may not be necessary to compile on your system. 
( The same may also be true of kernel, unistd, dir, user and regex ). In
fact, other than for VFS and TASKS, I would first try commenting out all
failed include files and then running a 'make', to see just how much further
work really needed to be done.  It may be less than you think!  For Linux
users, 'depends'' complaints about not finding 'stddef' and 'float' can be
ignored.

Once the include file situation is handled, a 'make' should be run to
generate the actual xzet application.  This takes less than five minutes 
on my meager 386/33.  

Before running xzet, be sure to set the application resources by either
running a 'make install' or using your own favorite technique to point to a
resource file not in the app-defaults directory.  Xzet is not well behaved
at all without its resource file!  (Install will also copy xzet to your X11
bin directory.)

Finally, use 'make install.man' to install the man pages.


Party on Wayne. Party on Garth.

	Zman			Loganville Technical Resources, Inc 
