       The guide of using database handler and API for the handler

There is three components available:

1. Database handler: It is a brokering application which mediates interactions
   between client applications and the project database. 
2. APIs for the DB handler: APIs is provided for any applications which
   want to interact to project database. 
3. Project data explorer is provided to view the data in project database. 

The following is the guide of how to use the database handler and list the
methods in python APIs. 

I) Software Requirements:

You must have python, MySQL installed. 

Python can be downloaded from http://www.python.org/. 
MySQL can be downloaded from http://www.mysql.com/.

In addition, you will need to install the MySQLdb package which can be
downloaded from http://sourceforge.net/projects/mysql-python.

II) Source files required:

database/schema.sql
handler/server.py
handler/ClientAPI.py
handler/db.py
handler/dbapi.py
explorer/dataexplorer.py

(Note: handler/testscript.py could be used for test various methods in APIs)

III) Database setup:

1. Create a user account:
   Log on MySQL as a root user, use the command:  mysql -u root -p
  
2. Then create a user account, use the following command:
   Grant create, select,insert,delete,update on ProjectHistory.* to
   USERNAME@'localhost' identified by PASSWORD with grant option;
    e.g Grant create, select,insert,delete,update on ProjectHistory.* to
   'admin'@'localhost' identified by 'admin' with grant option;
3. Exit by typing 'exit;'
4. Run mysql with 'admin' user, i.e:
   mysql -u admin -p
5. Create database:
   source database/schema.sql

IV) Running the handler:

   Command: 1) run handler silently: python server.py
            2) run handler with output messages: python server.py -debug

V) Running Project Data Explorer:
   
   Command: python dataexplorer.py

VI)Python APIs:
   
   In class serverconnection, there are 17 methods available. After creation
   of a serverconnection instance, OpenDB() should be called first before any
   other methods can be used. When finish all the operations, Close() should
   be called to close the connection. 

   Usage examples: 
   
   con = serverconnection()
   con.OpenDB(host,username,password,dbname)
   con.NewProject(projectname)
   con.NewJob(projectname,jobname)
   ...
   con.Close()   

   OpenDB(host,username,password,dbname): Open a specific database.      
    
   CloseDB(): Close database.

   IsOpen():  Check whether Database open or not. Return True or False.

   NewProject(projectName):  Create a new project. Return project id. 

   NewJob(projectname,jobname): Create a new job within the specified project
                              with specified name. Return job id.

   SetData(jobid,name,value): Create an item within the specified job. Return
   fact id.

   GetData(jobid,name): 
      Get the value of specified item name within specifed job.
      Return latest value of the item.

   ImportDingbat(jobid,name,description,type,value):
     Create a new dingbat for a specified job. The dingbat will have
     name,description,type and value attributes.  
     Return dingbat id.

   ExportDingbat(jobid,name):
     Get the value associated with the most recent dingbat stored in a
     specific job and specific name. 
     
     Return latest value of dingbat.
  
   DeleteDingbat(jobid,name):
      Remove a dingbat and its associated data from a specific project for a
      specific job and specific name.
   
   DescribeDingbat(jobid,name):
      Get the description and type attributes of a dingbat for a specified job.
      Return description of dingbat.

   GetProject(projectname):
      Open an exsiting project. Return project id.

   DeleteProject(projectname):
      Delete a project. 

   Version():
      Return version of MySQLdb.
   
   ListProjects():  
      Get a list of projects.

   ListJobs(projectid):
      Get a list of jobs within specified projects.

   ListItems(jobid):
      Get a list of items within specified job.
   
-----------------------------------------------------------------------------
CVS Id $Id: README.txt,v 1.13 2005/10/11 14:25:00 wy45 Exp $
