$Id: readme.txt,v 1.1 2007-07-19 04:00:06 normg Exp $

gsstat - an example program using the GemStone C++ Statistics Interface (GCSI)

Notes on using the GCSI
=======================

The GCSI API allows C++ programs to collect GemStone statistics directly from the
shared page cache without starting a database session.

Database statistics are defined in the header file $GEMSTONE/include/shrpcstats.ht.

Most statistic names closely resemble the name shown using VSD (Visual Statistic
Display).

Your program must include these header files:

	$GEMSTONE/include/shrpcstats.ht - definition of all cache stats
	$GEMSTONE/include/gcsi.hf - prototypes for all GCSI functions
	$GEMSTONE/include/gcsierr.ht - GCSI errno numbers

Your program must define a main() function somewhere.  GemStone provides a shared
library, $GEMSTONE/lib/libgcsi.so ($GEMSTONE/lib/libgcsi.sl on HPUX) which your
program will load at runtime.  $GEMSTONE/lib must be included in your
LD_LIBRARY_PATH environment variable so the runtime loader can find the
GCSI library.

$GEMSTONE/lib/libgcsi.so is a multi-threaded library, so your program must also
be compiled and linked as a multi-threaded program.  Sample makefiles for each
UNIX platform show you how to do this using the compilers we use to build the
GemStone product.  Building your program with another compiler (like g++)
may also work so long as you specify the appropriate flags to enable 
multi-threading.

Specify $GEMSTONE/lib/libgcsi.so ($GEMSTONE/lib/libgcsi.sl on HPUX) when
linking your program.  Note that this is a symbolic link that points to
the acutal shared library which includes the GemStone version in the file 
name.  For example, for GemStone64 2.2.2 we have:

lrwxrwxrwx   1 normg    users 16 Jul 16 16:28 libgcsi.so -> libgcsi64-222.so*

You should *always* link with libgcsi.so, *not* libgcsi64-222.so.  This is 
because libgcsi64-222.so MUST be matched with the shrpcstats.ht header file
from the same GemStone release.

You must re-compile and re-link all your GCSI programs each time you move
to a new GemStone version.  This is because the internal structure of
the shared cache may change from version to version.  Assuming you've 
created a makefile, all you should need to do is change $GEMSTONE
and rebuild.  Wild and crazy things may happen should you forget to 
do this.

The GCSI library allows your program to connect to a single GemStone 
shared page cache.  Only 1 shared cache connection per program is currently 
supported.  The connection is made in read-only mode, so there's no way 
you can corrupt the shared cache if your program goes haywire.

Once the connection is made, a thread is started to monitor the cache and
disconnect from it if we detect that the cache monitor process has died.
This thread is needed to prevent your program from "holding on" to the shared
cache after all other processes have detached from it.  That way, your
program can safely sleep for a long time without preventing the operating
system from freeing and recycling shared memory should the stone be shutdown
when your program wasn't looking.

The gsstat Sample Program (gsstat.cc)
=====================================

The gsstat program is used to monitor a running GemStone repository by printing
out certain statistics at a certain interval.  Think of the UNIX utilities
vmstat or iostat - now you have the equivalent for GemStone!

Invocation is simple:  all you need is the name of a running stone (or shared cache,
if running on a gem server) and a time interval in seconds.  For example:


normg@halifax:225 % gsstat norm 2

Sess     CR    PNR        PD       DNR      FP OCS     FF
---------------------------------------------------------
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505

Sess     CR    PNR        PD       DNR      FP OCS     FF
---------------------------------------------------------
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
   4      1      2         0         0     124   0   4505
^Cnormg@halifax:226 %
 
These stats have the following meanings:

	Sess - Number of logged in sessions
	CR   - Number of commit records
	PNR  - PagesNeedReclamiingSize stat
	PD   - PossibleDeadSize
	DNR  - DeadNotReclaimedSize
	FP   - FreePages (in stone)
	OCS  - Session ID holding the oldest CR, or 0 if none 
	       or only 1 CR.
	FF   - Number of free frames in the shared page cache.


<Ctrl-C> will stop the program and detach from the cache.