Creating an ADO Data Provider

ADO lets you access data through data providers. Here’s how to create your own data provider, which can be used from ADO. Peter Vogel demonstrates this technology by creating a provider to pull Form, Query, and Report information out of an Access MDB.

From Access 95, 97, and 2000 you can use ADO to retrieve data through data providers. The available data providers include the Microsoft.Jet OLE.DB.4.0 provider, which accepts SQL commands and returns data pulled from Jet databases. But you can create your own data providers that will accept requests and return Recordsets. And your data providers can extract their data from any data source that you want! The beauty of the OLE DB framework is that no matter what format you have your data stored in, you can create a provider for that data. Once your provider is created, your data becomes accessible from any ADO-compliant tool–which means any tool that can work with COM–from Visual Basic to Access to Delphi.

In this article, I’ll show you how to create a data provider using Visual Basic and how to call it from Access. The example that I use is a simple provider that returns information about the Forms, Queries, and Reports in an MDB file.

Data providers

While data providers can be created in any language, I’ll use Visual Basic for this example. To create a data provider, you begin with either an ActiveX DLL or ActiveX EXE project in Visual Basic (an ActiveX DLL will give you the best performance). You must have two Class modules in the project. One Class module is responsible for retrieving the data. The second class module, which I’ll call the interface module, handles the communication between ADO and your data provider Class. I’ll begin by looking at the data provider Class module, stop to look at the interface module, and then return to finish the Class module.

After creating your Visual Basic project, you must add a reference to the Microsoft OLE DB Simple Provider 1.5 Library to your Project | References list. With that reference added, you’re ready to work on the Class module that will act as your data provider module. To convert the Class module to a data provider, you need to implement the OLE DB Simple Provider interface in it. You do that by adding this line to the top of the class module:

Implements OLEDBSimpleProvider

Now that you’ve added that Implements line, you’ll have to add routines for all of the methods that make up the OLE DB Simple Provider interface. The names and purpose of the methods that make up the interface are summarized in Table 1. How many of these routines you actually put code in is up to you. In order to create a read-only provider, which is all that I’ll do here, you only need to return values for the getColumnCount, getRowCount, and getVariant routines.

Table 1. Methods for an OLE DB Simple Provider.

Method Name Description
AddOLEDBSimpleProviderListener Passes an OLE DB listener to your object to fire events.
DeleteRows Passed a position in the array of records and a number, it deletes the number of rows specified, beginning at the position specified.
Find Passed a starting position, a column number, and a value, it finds the specified value and returns the row number.
GetColumnCount Returns the number of columns in the array.
GetEstimatedRows Returns the number of rows in the array, or your best guess.
GetLocale Return the locale id for the text strings in the array.
GetRowCount Returns the number of rows currently in the array.
GetRWStatus Passed a column number and a row number, it returns whether the value can be updated. If either the column or the row are —1, it returns the status for the whole row or column.
GetVariant Passed a row, a column, and a format, it returns the value at that position in the array.
InsertRows Passed a position in the array and a number of rows, it adds the number of blank rows specified after the position specified.
IsAsync Returns a True if control will be returned to the client while the array is being built.
RemoveOLEDBSimpleProviderListener Passes a listener to be removed.
SetVariant Passed a row number, a column number, a format, and a value, it updates the position in the array with the value.
StopTransfer Stops adding rows to the array.

Before looking at the code that actually retrieves the data, I’ll show you some of the simpler routines to implement in the data provider module. For my provider, I created an internal Recordset that holds three columns of information for each Form, Report, or Query in the target database: the name, the creation date, and the last modified date. As a result, the data provider’s getColumnCount method just has to return the number 3–the number of columns in the Recordset that I create:

Two other routines (get EstimatedRows and getRowCount) return the number of rows in my internal Recordset. To supply those values, I just return the RecordCount property of that Recordset in those two routines:

The routine that’s called when the user asks for data is the provider’s getVariant routine. This routine is passed the row number and the column number of the data to be returned. In my provider I use the row number to move to the requested row in my Recordset using the Recordset’s AbsolutePosition property. I use the Fields collection and the column number to return the requested column. Here’s the code (with error handling removed):

The values of the iRow and iColumn parameters must be adjusted to match the way that my Recordset works. A Recordset’s lowest AbsolutePosition is 1, but the getVariant routine passes 0 in the iRow parameter. Similarly, the first field in the Fields collection is number 0, but the iColumn parameter is passed a 1.

With the provider mostly built, I’ll turn my attention to creating the interface class that will manage access to my provider. This interface class is another Class module in the Visual Basic project. After adding the Class module you must set its DataSourceBehavior property to vbDataSource. Setting this property requires you to add a GetDataMember routine to your module. The GetDataMember routine is passed two parameters:

  • DataMember, which will contain the command passed to the provider from the calling program. My provider requires commands to consist of the type of object being requested and the path to the database (for instance, “Form;C:\My Documents\MyDB.MDB”).
  • Data, which is used to return the data provider you created to the calling program.

In the GetDataMember routine you must load the Class module that retrieves the data and perform any initialization work. Since I called my data provider Class Module clsMDBInfo, the GetDataMember’s code to create the provider Class module looks like this:

Since the GetDataMember of the interface class receives the command passed to the provider, I must pass that command on to the data provider class so that it can build its internal Recordset. I first parse out the command to get the kind of object to retrieve and the database name. Once I have them, I pass them to separate properties on the data provider and call a routine to build my internal Recordset (again, error handling has been removed):

I’ll now return to my data provider class to show how I actually retrieve the data. I need to define the two properties and the method that I used in the GetDataMember routine of the interface class. The Command and DB properties are easy: I just add Public variables at the top of the data provider Class module:

My CreateRecordset method is only slightly more complicated. First, I have to create a Recordset and add some columns to it. To create an ADO Recordset from scratch I need a reference to the ADO Recordset library in my Project | References dialog. After using the New keyword to create the Recordset, this code then adds three fields to the Recordset and opens the Recordset:

The OLE DB simple provider will use the first row in the Recordset that I return to get the names of the fields in my Recordset. I need to add a row to hold those names:

Now, I have to open a Jet database to get a list of the Forms, Reports, and Queries stored in it. In order to get at that information, I’ll fall back on good old DAO, which means that I have to add a reference to DAO to my rapidly growing References list. You must be careful when you have DAO and ADO referenced in the same project, since they share the same name for their Recordset objects. Whenever referring to a Recordset, you should always prefix it with DAO or ADODB so that VBA knows which Recordset you mean.

Once I have the reference to DAO made, I can open the requested database and find the appropriate collection (that is, Forms, Reports, or Queries).

Finally, I can use a For Each…Next loop to move through each item in the collection. For each item in the collection, I add a row to my Recordset and copy the properties that I want to report to the appropriate column in the Recordset. Here’s that code that populates my Recordset with the data from Access:

Registering your provider

The next steps require you to step out of Visual Basic. To have your class treated as an ADO provider, you need to generate a GUID and create a bunch of registry entries that identify your provider to ADO.

To generate a GUID, you can use the UUIDGen.EXE that’s distributed with Visual Studio. You can find it in C:/Program Files/Microsoft Visual Studio/common/tools or download it from the Microsoft Web site. UUIDGen is a DOS command-line utility, so to run it you can either open a DOS window or execute it from the Start menu’s Run option. I pass the utility two switches:

  • /i This switch produces a short text file containing a new GUID.
  • /o This switch should be followed by the file name where the text file should be placed.

This command line, for instance, generates the text file in c:\myguid.txt:

The resulting file will look something like this:

The only part that you need from the file is the GUID (in this case, bcde9140-5068-11d3-a8c8-00107a901a5f).

For the registry entries, I’ve borrowed the following template (Listing 1) from Robert Macdonald, whose article “Do-It-Yourself Recordsets” in the December 1998 edition of Pinnacle’s Visual Basic Developer inspired me to write my provider. I keep the template text in a file on my hard disk and update it in Notepad with the entries appropriate for my provider. After saving the file to my hard disk with a file extension of .REG, I double-click on the file in Windows Explorer to cause RegEdit to read the file’s entries and update my Windows Registry. I then store the file someplace safe to distribute with the setup routine for the component.

To modify the template for your provider, you’ll need to make the following changes:

  • Replace **GUID** with the GUID that you generated with UUIDGEN.
  • Replace **Full Name** with any descriptive text (just make sure that you use the same text in both places where the full name is required).
  • Replace **Component** with the name of your Visual Basic project from the Project | Properties menu choice.
  • Replace **Connection** with the progid of your interface class. The progid will be the project name and the class name, separated by a period.

Listing 1. Rob Macdonald’s original template.

 

Listing 2  is an example of what a typical set of entries would look like. In this case, my Visual Basic project was called MDBProvider and the interface class was called clsMDBI. I gave the provider the arbitrary name “MDBInfo”. I used a different GUID from the preceding UUIDGen example:

Listing 2. A typical set of entries.

To use this ADO provider, the developer sets the provider attribute in a connection string to the name you gave in your REG file. This code, for instance, creates a Recordset of Form information using my provider and displays all of the form names:

I’ve included a version of the MDB Information provider in this month’s Subscriber Download file. Also included is the registry file to register it. Using that code as a model, you’re now ready to create your own ADO data providers.

About Peter Vogel

After 10 years of editing Smart Access, Peter continues to develop with Access (though he also does a lot of .NET stuff). Peter is also still editing other people's article--he even self-published a book on writing user manuals ("rtfm*") with a blog here.
This entry was posted in Old Material. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *


*


This site uses Akismet to reduce spam. Learn how your comment data is processed.