(c) Copyright 1995 MitranoSoft
    All Rights Reserved
    This product cannot be sold without permission from the author,
    however it can be distributed freely, but only in the entirety of 
    the bundled files.  For details, see the file License.txt bundled 
    herein.

DBAwareCollection is a plug-compatible replacement of the VB4 Collection 
object, but offers extended capabilities by adding the following object-
and database-oriented features:

	Object persistence through database tables

	Automatic implementation of the object containment hierarchy

	Automatic instantiation of contained objects

	Encapsulated SQL services

	Mapping of objects to their underlying tables

It includes a public interface for various database-related and other 
services, including:

	Returning the underlying RecordSet for use with the DataControl
	object
		Ex:
			Set Data1.RecordSet = MyDBAwareCollection.RecordSet

	Setting various database-related parameters, such as the Database 
	object, WhereClause, OrderByClause

	Adding new methods beyond the "Add", "Item" and "Remove" methods 
	found in the VB4 Collection object, such as "Replace", "Refresh", 
	"RecordSet", "RefreshRecordSet", "Remove", 	"InstantiateFromDatabase", 
	"InstantiateFromRecordSet", "CloneRecordSet", "CollectionIndex", 
	"SetDatabaseParameters", "WhereClause", "OrderByClause" and many 
	more

DBAwareCollection can function as a direct replacement for the VB4 
Collection object.  The developer simply adds the two provided Class 
Modules to the VB project, then replaces all references to the VB4 
Collection object with references to the DBAwareCollection.

	Add these Classes:
		DBAwareCollection.cls (File=DBAwarCO.cls)
		DBAwareObjectLink.cls (File=DBAwarLK.cls)

By default, DBAwareCollection operates in "Collection-Emulation" mode, 
such that there are no attempted database references.  This allows for 
the creation of the non-visual Business Object Model (which is highly 
recommended) without the need for an underlying database model (the 
database modeling process is greatly simplified if it is deferred until 
after the BOM has been finalized, anyway.)  When the database model is 
complete, the developer modifies the database model as follows:

	Table "DBAwareObjectLinks" must be created, as found in the file 
	VB4OO.MDB:
		Column: FromObjectType	Text 50 	PrimaryKey, Index1
		Column: FromObjectID	Long 		PrimaryKey, Index1
		Column: ToObjectType	Text 50	PrimaryKey, Index2
		Column: ToObjectID	Long		PrimaryKey, Index2

	All application Tables must be defined or attached to the same 
	Database used to contain Table "DBAwareObjectLinks"

	Each of the supported Tables must have a Column as follows:
		Name: ObjectID, Type: Counter

The BOM objects should be modified as follows:

	Public ObjectID as Long 
		(to be mapped to Column "ObjectID" of the corresponding 
		Table)
		
	Private MyCollection As New DBAwareCollection
		(for each contained object collection)

	Public MyDatabase as Database
		(probably necessary only once per project)

	Private Sub Class_Initialize:
		ObjectID = -1
		(possibly more code, as needed)

	Public Function InitializeFromRecordSet(RecordSet) As Long
		Copies values from the RecordSet into the object's variables
		Ex: 
			Public Function InitializeFromRecordSet(RecordSet) _
			As Long
				pvtFirstName = RecordSet("FirstName")
				pvtLastName  = RecordSet("LastName")
				InitializeFromRecordSet = Err
			End Function

	Public Function InitializeRecordSet(RecordSet) As Long 
		Copies values from the object's variables into the
		RecordSet, but NOT "ObjectID" (this is in italics, by the 
		way)
		Ex: 
			Public Function InitializeRecordSet(RecordSet) As Long
				RecordSet("FirstName") = pvtFirstName
				RecordSet("LastName")  = pvtLastName
				InitializeRecordSet = Err
			End Function

	Public Function NewInstanceOfMyClass() as <Me>
		Instantiates and returns a new object of this Class, where
		"<Me>" is replaced with the appropriate Class Type
		Ex: 
			Public Function NewInstanceOfMyClass() As Person
				Set NewInstanceOfMyClass = New Person
			End Function

	Public Function ObjectType() As String
		Returns the type of object
		Ex: 
			Public ObjectType() As String
				ObjectType = "Person"
			End Function

	Public Function TableName() as String
		Returns the name of the underlying Table
		Ex: 
			Public TableName() As String
				TableName = "PersonMaster"
			End Function

	Public Function <CollectionName> _
		(Optional ByVal ObjectID As Variant) As Variant
		Returns a DataAwareCollection.  Note the difference between 
		the example described in the VB Programmer's Guide (as 
		follows):
			Public Function Persons(Optional ByVal ObjectID As _
				Variant) As Variant
				If Not IsMissing(ObjectID) Then
					Set Persons = 
						pvtPersonsCollection.Item(ObjectID)
				Else
					Set Persons = pvtPersonsCollection
				End If
			End Function

		and the DataAwareCollection-compatible version: 
			Public Function Persons(Optional ByVal ObjectID As _
				Variant) As Variant
			' Returns a DBAwareCollection of Person objects which 
			'   are contained by this Company object,
			' or
			' Returns a Person object whose ObjectID matches the 
			'   ObjectID parameter.

				Dim tempNewPerson as New Person

				If Not _
				pvtPersonsCollection.DatabaseHasBeenReferenced _ 
				Then
				pvtPersonsCollection.SetDatabaseParameters _
			            Database:=MyDatabase, _
			            OrderByClause:= _ 
						"LastName ASC, FirstName ASC"

			        Set pvtPersonsCollection = _
				pvtPersonsCollection.InstantiateFromDatabase( _
			                Parent:=Me, _
			                SampleObject:=tempNewPerson)
				End If
    
				If Not IsMissing(ObjectID) Then
					Set Persons = _
				 pvtPersonsCollection.Item(ObjectID)
				Else
					Set Persons = pvtPersonsCollection
				End If
			End Function

The following general requirements must be met:

	The application must prepare a Database object for use

	The application must provide DBAwareCollection with the prepared
	Database object using any of the following methods:
		1.	the DBAwareCollection "Public Property Set Database" 
			method,
		2.  	the DBAwareCollection "Database:=" named parameter of 
			the "InstantiateFromDatabase" method
		3.	the "Database:=" named parameter of the 
			DBAwareCollection "SetDatabaseParameters" method

The following general recommendations should be considered:
	Each object which contains a DBAwareCollection object should have 
	a corresponding method named "Add<ContainedObjectType>" (e.g., 
	"AddPerson", "AddAddress", etc.)  This serves as a wrapper which 
	relieves the remainder of the application from	having to use 
	"Persons.Add" (which requires the "Parent:=Me" nuisance parameter 
	for correct object containment effectiveness)
		Ex: 
			Public Function AddPerson(Optional ByVal Item As _
				Variant As DBAwareCollection
				Set AddPerson = Me.Persons.Add( _
					Item:=Item, _
					Parent:=Me)
			End Function

		The referenced "Add" method would also be necessary.

Please feel free to contact me if you have any questions regarding this 
project.  I can be reached at:
	CompuServe: 73367,3470
	MSN:        KenFitzpatrick

This is a Shareware product.  Those who agree to pay a registration fee 
of $45, will be kept up-to-date with future releases.  Refer to the file 
Order.txt for registration information.

I sincerely believe DBAwareCollection will become a strategic component 
of every VB Programmer's toolbox.

Thank you and best wishes.

Microsoft Visual Basic is a registered trademark of the Microsoft Corporation.