
*  MyDAO:	C++ wrapper libary. v0.1 (19-Feb-2000)
*  Author:	Satish (spitfire@pn3.vsnl.net.in)
*  Copying:	Feel free to use/copy/modify/add bugs/find bugs, but keep the
		author informed.
//------------------------------------------------------------------------------------  This document is divided into following parts:
	A] Introduction
	B] Programmer's Manual
	C] TODO List
//------------------------------------------------------------------------------------

A] Introduction:	
	This is C++ library for MySQL server. I was looking for a C++ library
which can create and work with Data Access Objects. I came across software
written by Roland Hanel (MySQL C++) and Ed Carp (MyC). But MyC is written in C
and cannot create recordset object in true sense. Also it can not create and
work with multiple recordset objects. Still the software was the closest to
what I was looking for. So I decided to give a try by myself and came with
this MyDAO ver 0.1. It is still under development and my change in future.
//------------------------------------------------------------------------------------

B] Programmer's Manual:
If you can not understand the description, see the examples!
	
B1> dbconnect class: One connection object must be created. It is responsible
for connecting to MySQL server and opening a database.

Properties:
1.  bool Connected;
    Connected is true if connection to MySQL server is successful.
	
2.  MYSQL *DBase;
    DBase is pointer to MYSQL structure. This is required to open recordset.
    
Methods: 
1.  void dbconnect::Connect(char *host, char *port, char *uname, char*pwd);
    Attempts to connect to MySQL server using given host, port, username
    and password. If connection is successful, Connected property will true.  

2.  void dbconnect::Disconnect();
    Disconnects the current connection to MySQL server.

3.  bool dbconnect::OpenDB(char *db);
    Opens the database given by db. If successful returns true.

Example:
	dbconnect MyConnect;
	char host[]="localhost";
	char port[]="3306";
	char name[]="satish";
	char pwd[]="";
	char db[]="orders";

	MyConnect.Connect(host, port, name, pwd);
	if (MyConnect.Connected)
		cout << "Connected" << endl;
	else	{
		cout << "Connection failed" << endl;
  		return;
		}
	if (!MyConnect.OpenDB(db)) {
		cout << "Can not open selected database" << endl;
		return;
		}
	else	{
		cout << "Opened datbase: " << db << endl;
		//open recorset(s)...
		//Manipulate data...
		}
	MyConnect.Disconnect();

B2> recordset class: Any number of recordsets can be created from this
class. It is has many features for easy manipulation of data.	

Properties:
1.	char RecSource[MAX_RECSRC_LEN];
	Source of the records from which data is to be accessed. It should be a
	SQL SELECT statement returning records.

2.	unsigned long int RecordCount;
	Number of rows in the opened recordset.

3.	unsigned long int AffectedRows;
	Can be used only with Update, AddNew or Delete. Number of rows
	actually edited/added/deleted by the server. 	
	
4.	bool EOR;
	End Of Recordset. True if you move to the last row.

5.	bool BOR;
	Begining Of Recordset. True if you move to first row.
	** EOR and BOR both are true if RecordCount is zero.

Methods:
1.  void recordset::OpenRecordset(MYSQL *Structmysql, char *sql);
    Opens a recordset based on SQL select statement.

2.  void recordset::CloseRecordset();
    Closes the recordset. Recordset must be closed to free the memory used
    by it.

3.  void recordset::MoveNext();
    Moves to next row of recordset. If already at last row, it will
    remain at the last row.

4.  void recordset::MovePrevious();
    Moves to previous row of the recordset. If already at first row, it will
    remain at the first row.

5.  void recordset::MoveFirst();
    Moves to first row in the recordset.

6.  void recordset::MoveLast();
    Move to last row in the recordset.

7.  char* recordset::GetField(char *FName);
    Returns contents of the field FName.

8.  void recordset::SetField(char *FName, char *Value);
    Sets contents of field FName with value given by Value. Changes will be
    discarded if Update/AddNew method is not used after setting the value.

9.  void recordset::Edit();
    Edit method should be used befor SetField and Update method,
    othewise changes will be discarded.

10. void recordset::AddNew();
    Used to add new row to the recordset. For this method to work, recordset
    must be based on a table. Update method must be used after
    setting all the field values. WHERE clause should not be used in Upadate
    method when it is used with AddNew. AffectedRows property gives number of
    rows added. 

11. void rercordset::Update(char *Where);
    Used to edit/add a row in conjunction with Edit/AddNew methods. WHERE
    clause should not be used with AddNew.

12. void recordset::Delete(char *Where);
    Used to delete row(s) from the recordset.

13. void recordset::Refresh();
    Changes made by Update method are not visible unless Refresh method is
    used. Refresh the recordset immediately after Update.

14. char* recordset::GetFieldN(int FNum);
	Same as GetField, Field number is used insted of field nmae.
15. void recordset::SetFieldN(int FNum, char *Value)
	Same as SetField, Field number is used insted of field nmae.


Example 1:
	//Continued from dbconnect example
	//Open table customers and print all records
	
	recordset MySet;
	char sql[]="SELECT * FROM customers";

	MySet.OpenRecordset(MyConnect.DBase, sql);
	if (MySet.EOR && MySet.BOR){
		cout << "No records found" << endl;
		return;
		}
	else	{
		// Show number of records
		cout << "No. of records: " << MySet.RecordCount << endl;

		// Show all records
		while (!MySet.EOR){
			cout << MySet.GetField("or_id") << "\t";
			cout << MySet.GetField("customers") << "\t";
			cout << MySet.GetField("city") << endl;
			MySet.MoveNext();
 			}
		}


Example 2:
	// Add a new row to the customers table

  	MySet.AddNew();
		MySet.SetField("cs_id", "7");
		MySet.SetField("name", "Satish");
		MySet.SetField("city", "Pune");
  	MySet.Update("");		// Note where claues is not used
  	MySet.Refresh();		// Make new row visible

Example 3:
	// Change name of customer
	
	MySet.Edit();
		MySet.SetField("cs_id", "7");
		MySet.SetField("name", "Suresh");
		MySet.SetField("city", "Pune");
  	MySet.Update("or_id=7");	// Note use of where clause, it is must
	MySet.Refresh();		// Make changes visible

Example 4:
	// Delete a record

		MySet.Delete("name='Suresh'");
		MySet.Refresh();

Example 5:
	// Close recordset when done
	// It is must
	
	MySet.CloseRecordset();

//------------------------------------------------------------------------------------

TODO:
	1] Better error checking
	2] Incorporate Find methods (FindFirst, FindNext, FindPrevious,
	   FindLast)
	3] Put on a graphical face for recordset

//-------------------------------------------------------------------------------------
