readme.txt

Visual C++ 数 据 库

DaoLib 1.0 - A complete solution for real world database development.


1 - Requirements - Getting started
2 - Introduction
3 - Core components
4 - Intermediate abstractions
5 - User interface components
6 - Tutorial and code samples
7 - Deployment
8 - Feedback - Support
9 - Reference



1 - Requirements - Getting started

	Unzip the DaoLib file maintaining the directory structure (-d). This
library requires Visual C++ 6.x installed on the development system. The 
evaluation version is fully functional, with a limit of 10 controls per 
dialog and an annoying reminder.



2 - Introduction

	The power of the DAO interface for dealing with databases is an
undeniable fact. It provides a fast and reliable mechanism for data management 
of Access and other ISAM and ODBC databases. Though it was engineered 
targeting scripting languages such as Visual Basic and VBA, it provides a dual 
interface, which allows straightforward C and C++ handling of its methods and 
properties.
	
	The C/C++ developer has several options:

	a) Deal with COM interfaces such as DAODatabase, DAORecordset and the 
like using the OS built-in OLE support. This could be tedious and error prone, 
since the developer has to deal with reference counting, object releasing and 
other COM annoying aspects.

	b) Go up one level through a C++ proxy. Microsoft provides such a 
proxy-wrapper in its DAO library. This library is rowset-oriented and provides 
a valuable variable binding mechanism, but it is not the best solution for 
handling record-oriented applications.

	c) Use some framework which integrates the database specifics with a 
user interface management. MFC-DAO is an example of this approach. The problem 
here is that the integration is best suited for a Doc/View architecture, and 
it adds some complexity when dealing with dialog intensive applications.

	DaoLib was built with this three-level separation of concerns. It deals 
with all the COM burden, such as exception handling, reference counting and 
object lifespan. It provides a wrapper level you can access directly, and it 
integrates to MFC with little overhead.



3 - Core components

	The classes at this level are wrapped around DAO components. In 
addition, we provide a handful of helper classes such as Bstr, Variant and 
Currency, which encapsulate the BSTR, VARIANT and CURRENCY semantics, allowing 
a very robust parameter handling. ErrorInfo manages error handling, converting 
COM error objects into C++ exceptions.

	The instantiation of Dao objects was simplified through smart 
constructors, many of which take no arguments or a single string object. The 
enumerator semantics is replaced by a simpler indexing mechanism. The use of 
the 'property' Microsoft extension allows a 'VB-like' syntax in many cases: 
using Variant indexes, you can refer to a specific field as:
	FieldValue[0] or as: FieldValue["CustomerID"]
In addition, the same property (if marked read/write) can be a left or right 
value.

	These are the core components and their mapping to DAO components:

	Field			DAOField
	Recordset		DAORecordset
	Database		DAODatabase
	Workspace		DAOWorkspace
	DBEngine		DAODBEngine
	Parameter		DAOParameter
	QueryDef		DAOQueryDef
	TableDef		DAOTableDef
	Index			DAOIndex
	User			DAOUser
	Group			DAOGroup
	Relation		DAORelation
	Connection		DAOConnection
	Property		DAOProperty

	These are the helper classes and their COM counterparts:

	Bstr			BSTR
	Variant			VARIANT
	Currency		CURRENCY

	These have no counterparts:
	
	ErrorInfo		Error handling through exception throwing.
	DaoBase			Base class for every Dao component. It manages
				reference counting and object releasing.



4 - Intermediate abstractions

	In order to connect database objects with user interface elements 
such as controls, windows or dialogs, a couple of intermediate level 
abstract classes must be added to the hierarchy. These are DaoWindow and 
DaoControl. A windowing user interface element must inherit from DaoWindow 
and a control element from DaoControl to have complete control of its 
underlying database objects. They interact tightly with MFC transfer 
mechanisms. 



5 - User interface components

	DaoLib comes with several user interface components, but its open 
architecture allows you to add your own custom components. The basic 
components are:

	Windowing components:
		
		DaoDialog
		DaoPropSheet
		DaoPropPage

	Control components:
		
		DaoEdit
		DaoCheck
		DaoRadio
		DaoGroup
		DaoCombo
		DaoListCtrl

	Complete components:
		
		ListDialog
		
	The windowing components are intended to be used as base classes of
your dialog objects. You can create regular dialogs or property pages using 
the ClassWizard and then replace the base class in the declaration and add
the constructor arguments. ClassWizard will still recognize your class and 
it even will use DaoDialog or DaoPropPage when adding base class references.

	The control classes can be used directly. Once again, you create 
control objects with ClassWizard and then replace their declaration (you can 
use the 'Replace' command if you have many controls). You can manage some 
attributes of the controls at declaration time, such as enabling or writing 
denial.

	DaoLib includes a powerful dialog-based component called ListDialog.
It manages the display of Recordset objects through a list control, naming 
each header column upon the field's name and formatting the data according 
to each data type. In addition, it provides complete printing support for the
list control's contents, sorting through column header clicking, keyboard 
support (Insert for adding records, Delete for deleting, Enter for viewing),
and a mouse driven context menu with those same functions.



6 - Tutorial and code samples

	The use of the library does not require any special skill. If you use
Visual C++ and feel comfortable with the ClassWizard, you can produce DaoLib 
code immediately. The steps to follow are:

	1 - You can create a project without database support, or use an 
existing project. Add DaoLib.lib to the libraries in the project settings 
(Link page). Map the include path accordingly (C/C++ - Preprocessor).


	2 - In your project's main file add a global DBEngine object:

// The one and only CMyApp object

CMyApp theApp;

becomes:

// The one and only CMyApp object

DBEngine dbeng;
CMyApp theApp;


	3 - In the declaration of your App class, add the core #include and a 
Database object:

#include "resource.h"       // main symbols

becomes:

#include "resource.h"       // main symbols
#include "bordao.h"

and: 

class CMyApp : public CWinApp
{
public:
 
becomes:

class CMyApp : public CWinApp
{
	Database db;
public:
 

	4 - In InitInstance, add the Database initialization:

	CMainFrame* pFrame = new CMainFrame;
	m_pMainWnd = pFrame;

becomes:

	try {
	  	db = "mydata.mdb";		//full path here, unless same
  		Recordset::pdbase = &db;	//directory as .EXE
	}
	catch(ErrorInfo& e) {
   		e.Show(0);
		e.Destroy();
		return FALSE;
	}

	CMainFrame* pFrame = new CMainFrame;
	m_pMainWnd = pFrame;


	5 - Create the appropiate dialog resource. Assign each control an ID
that resembles the name of the field with which it is associated. You can 
optionally add a Modify button (ID = 302). It must be the first in the 
control creation order. You may also add a Enter button (ID = 301). It must 
be non-visible, non-tabstop and marked as default button (unmark the OK 
button).


	6 - Open the ClassWizard and create the CDialog as usual. For each 
control, assign a member variable (Category: Control) of the required type. 
If you want to use the macros provided with DaoLib (recommended), give each 
control the exact name of the corresponding field, prefixed with 'm_' (for a 
field named CustomerID it should be m_CustomerID).
	

	7 - Close the ClassWizard and go to the dialog's class declaration 
(*.h file). Replace CDialog with CDaoDialog in the inheritance tag and add 
two parameters to the constructor before the existing one:

class CMyDialog : public CDialog
{
// Construction
public:
	CMyDialog(CWnd* Parent = NULL);

becomes:

class CMyDialog : public CDaoDialog
{
// Construction
public:
	CMyDialog(LPCSTR s = 0, bool a = 0, CWnd* Parent = NULL);
	

	8 - Replace the member control objects with the appropiate ones:

// Dialog Data
	//{{AFX_DATA(CMyDialog)
	enum { IDD = IDD_MYDIALOG };
	CEdit	m_CustomerID;
	CButton m_NewCustomer;

becomes:

// Dialog Data
	//{{AFX_DATA(CMyDialog)
	enum { IDD = IDD_MYDIALOG };
	CDaoEdit	m_CustomerID;
	CDaoCheck 	m_NewCustomer;
	

	9 - Go to the implementation file (*.cpp) and add the #includes you
need before the declaration file #include. In this case:

#include "stdafx.h"
#include "MyDialog.h"

becomes:

#include "stdafx.h"
#include "DaoDialog.h"
#include "DaoEdit.h"
#include "DaoCheck.h"
#include "MyDialog.h"


	10 - Modify the constructor accordingly.

CMyDialog::CMyDialog(CWnd* pParent /*=NULL*/)
	: CDialog(CMyDialog::IDD, pParent)
{

becomes:

CMyDialog::CMyDialog(LPCSTR s, bool a, CWnd* pParent /*=NULL*/)
	: CDaoDialog(CMyDialog::IDD, pParent, s, a)
{


	11 - In the body of the constructor, add the initialization macros.

	//}}AFX_DATA_INIT
}

becomes:

	//}}AFX_DATA_INIT
	DAOCONTROL(CustomerID);
	DAOCONTROL(NewCustomer);
}


	12 - Replace CDialog in the message map macro with CDaoDialog

BEGIN_MESSAGE_MAP(CMyDialog, CDialog)
	//{{AFX_MSG_MAP(CMyDialog)

becomes:

BEGIN_MESSAGE_MAP(CMyDialog, CDaoDialog)
	//{{AFX_MSG_MAP(CMyDialog)


	13 - That's it. Now you can construct an instance of your dialog and
execute it. This can be done from inside a menu response function:

	CString sql = "select * from Customers where CustomerID = 5477";
	try {
		CMyDialog Cust(sql);
		Cust.DoModal();
	}
	catch(ErrorInfo& e) {
		e.Show(*this);
		e.Destroy();
		return;
	}

or, for inserting a record:

	CString sql = "select * from Customers";
	try {
		CMyDialog Cust(sql, true);
		Cust.DoModal();
	}
	catch(ErrorInfo& e) {
		e.Show(*this);
		e.Destroy();
		return;
	}

or, if you want to use a ListCtrl:

	Recordset rs;
	try {
		rs = "select * from Customers";
	}
	catch(ErrorInfo& e) {
		e.Show(*this);
		e.Destroy();
		return;
	}
	CMyDialog Cust;
	CListDialog Lis(rs, &Cust);
	Lis.SetCaption("Listing of Customers");
	Lis.DoModal();

	Don't forget to #include the DaoLib specific headers in this file too, 
before the dialog declaration #include. If you use the ListCtrl component, you 
must add the corresponding resources from DaoLib.rc to your resource file.

#include "DaoDialog.h"
#include "DaoEdit.h"
#include "DaoCheck.h"
#include "MyDialog.h"
#include "ListDialog.h"	//if using ListDialog

	If you don't use all the functionality of DaoLib, the linker may issue
warnings about not referencing some libraries: this is the normal behavior. 
If you compile and link a Debug version, you can get some other warnings about
conflicting libraries. The non-evaluation version of DaoLib comes with a 
Debug static library and complete source code.


	14 - The procedure for a property sheet is very similar. Take a look
at the accompanying sample code.



7 - Deployment

	Programs built using DaoLib need no additional dlls. Of course DAO is
required. A DaoLib license allows unlimited deployment.



8 - Feedback - Support

	This is not a Beta release: we at ARGSOFT use this library since 1996 
(VC++ 4.2) for our custom products, and it only required some updating from 
time to time. We are aware that other developers may have quite different 
needs, so we will appreciate feedback. Please write to:
 
	[e-mail]

	ARGSOFT provides full support for the registered version. Evaluators
may ask for support, and in most cases they will get it. Please write to:

	[e-mail]



9 - Reference