============
Introduction
============

ccmeter.pl is a script that measures ClearCase responsiveness by running 
selected cleartool commands at a certain frequency over a period of time.

================
What it includes
================

README			- this file
design.html  		- general design notes
startccmeter.cmd.unix	- sample of a startup script on UNIX
startccmeter.cmd.nt     - sample of a startup script on NT
ccmeter.pl		- perl script that calculates and logs response times 
ccplot.pl		- perl script that plots the response times using gnuplot
			  (works only on UNIX)
=============
What you need
=============

-- ClearCase
-- Perl (the scripts were tested with Perl 5.005_03)
-- Perl Module Time-HiRes-01.20 installed
-- gnuplot version 3.7
-- libpng and zlib (needed by GNUplot)

============
How it works
============

startccmeter.cmd.unix and startccmeter.cmd.nt are basic command line scripts 
that run ccmeter.pl on UNIX and NT respectively. By using these scripts,
instead of invoking the ccmeter.pl directly, ccmeter.pl does not need
to be modified in order to run on either platform. 
ccmeter.pl calculates the responses times for the cleartool commands 
specified either in the command line or defaulted and saves the values 
in a log file.  

Usage: ccmeter.pl [-o outputfile] [-c cc-cmd,cc-cmd,cc-cmd]
       [-view view-tag] [-vob vob-tag] [-i interval-in-secs]
       [-n number-iterations] [-help]
   -o:     output file
   -c:     list of ClearCase commands (maximum 3)
   -view:  view tag
   -vob:   VOB tag
   -i:     interval between iterations in seconds (default 180)
   -n:     maximum number of iterations (default 500, set to -1 to iterate forever)
   -h:     prints this usage message

ccplot.pl plots the values collected in the log by ccmeter.pl. It uses gnuplot version 3.7
to draw the graph, earlier versions of gnuplot will not work. ccplot.pl works only
on UNIX, it hasn't been ported to NT. On NT, excel could be used to generate the graph.

 Usage: ccplot.pl -f <ccmeter.pl filename> -r <refresh interval> -x <x axis range> -t <temp directory> -p <poll rate> -g <gnuplot's directory path>
    Options:
      -f  filename  Where filename is a data file created by ccmeter
      -r  refresh interval
      -x  x axis range
      -t  pathname of the temp directory
      -p  poll rate to check the file specified with -f
      -g  pathname of the directory where gnuplot is installed
      -h  display help

All the arguments to gnuplot have defaults except for -f, which requires the user enter
a filename.


======
Set up
======

- Copy the scripts to a local directory (i.e. /usr/local/bin).
  On UNIX copy:
	- startccmeter.cmd.unix
	- ccmeter.pl
	- ccplot.pl
  On NT copy:
	- startccmeter.cmd.nt
	- ccmpeter.pl
- Rename/copy startccmeter.cmd.unix or startccmeter.cmd.nt to startccmeter.cmd
- Ensure that the client where ccmeter.pl is going to run is running 
  ClearCase.
- Perl must be installed 
- Install the Perl Module Time-HiRes
- Edit startccmeter.cmd to specify the directory where Perl is installed.
- Run ccmeter.pl. Here are some examples on how to do it.

  - Using the defaults. In this case, you only need to provide
    a valid VOB tag and a view tag. For example:
    
   startccmeter.cmd ccmeter.pl -vob /vobs/systools -view ccadmin -o ccresponse.log

  - Not using the defaults. In addition to providing valid VOB and view tags,
    provide the cleartool commands, interval and number or iterations.

  startccmeter.cmd ccmeter.pl -c "cleartool lsview -host mars,cleartool lsvob /vobs/pvob_project,cleartool catcs -tag v4.2.dev" -n 300 -i 120

- On UNIX, ccplot.pl plots the values saved in the ccmeter.pl the log.
  For example:

  ccplot.pl -f ccmter.log -g /usr/local/bin

======
Author
======

Martha DasSarma
dassarma@us.ibm.com

Questions, changes or comments should be sent to me at dassarma@rational.com