What happens when we disconnect?
When you disconnect a recordset by setting the active connection to nothing what happens inside your provider is that the Cancel method is called on your command object. In fact, the Cancel method is always called when the consumer is done with the underlying data source. Thus, we can intercept the call to Cancel and use it as a trigger to release our connection to the data object. To be able to do this we need to be able to communicate between the Command object and the rowset that it creates. To achieve this communication we can add a new interface to our proxy rowset:
interface IDisconnectableRowset : IUnknown
{
HRESULT DisconnectRowset();
};
We can then query for this interface from our Command object as the last thing we do inside of the Execute method.
if (SUCCEEDED(hr))
{
hr = pGetAsRowset->GetAsRowset(
pOurUnknown,
pUnkOuter,
riid,
pcRowsAffected,
ppRowset);
pOurUnknown->Release();
}
if (SUCCEEDED(hr))
{
hr = (*ppRowset)->QueryInterface(
IID_IDisconnectableRowset,
(void**)&m_pRowset);
}
pGetAsRowset->Release();
The Command object now has a way to tell the rowset that it has been disconnected, so we can add an implementation of ICommand::Cancel() that does that.
HRESULT CConversionProviderCommand::Cancel()
{
HRESULT hr = ICommandTextImpl::Cancel();
ATLTRACE2(atlTraceDBProvider, 0, "CConversionProviderCommand::Cancel\n");
if (SUCCEEDED(hr))
{
if (m_pRowset)
{
hr = m_pRowset->DisconnectRowset();
m_pRowset->Release();
m_pRowset = 0;
}
}
return hr;
}
First calling our base class to see if we can be cancelled and if so performing the disconnection on the rowset object.
What does the Rowset do?
I chose to make all rowsets derived from CProxyRowsetImpl be disconnectable, so that's where the implementation of IDisconnectableRowset::DisconnectRowset() lives. It's fairly simple, it just causes the rowset to release the data object that it's a proxy rowset for. If nobody else has a reference to the data object at that point then it will cease to exist, that seems pretty disconnected to me...
template <
class DataClass,
class T,
class CreatorClass,
class Storage,
class ArrayType,
class RowClass,
class RowsetInterface>
HRESULT CProxyRowsetImpl<
DataClass,
T,
CreatorClass,
Storage,
ArrayType,
RowClass,
RowsetInterface>::DisconnectRowset()
{
ObjectLock lock(this);
if (m_pDataObject)
{
m_pDataObject = 0;
}
if (m_pUnkDataObject)
{
m_pUnkDataObject->Release();
m_pUnkDataObject = 0;
}
return S_OK;
}
That's all there is to it. We now have a disconnectable rowset.
Download
The following source built using Visual Studio 6.0 SP3. Using the July 2000 edition of the Platform SDK. If you don't have the Platform SDK installed then you may find that the compile will fail looking for "msado15.h". You can fix this problem by creating a file of that name that includes "adoint.h".
If your system drive isn't D:\ then you'll have to change the #import statements in IGetAsADORecordsetImpl.h and IGetAsADORecordset.cpp.
A9645971-91EE-11D1-9251-00C04FBBBFB3
I must have spent around 6 months trying to get client cursor updates to work. I tried adding IRowsetUpdate, an obvious choice, but completely unnecessary. I tried adding all manner of other interfaces, guessing at random and failing completely. The main problem with client cursor updates is that at the point when the dreaded "Insufficient base table information for updating or refreshing" message is issued your OLE DB provider's session object is queried for an undocumented interface. The IID is {A9645971-91EE-11D1-9251-00C04FBBBFB3} and according to a Microsoft support person this interface is the subject of a documentation bug which relates to updating providers that do not support SQL.
So, what's the secret
It turns out that all you need to do to get rid of the "Insufficient..." error message is to implement IColumnsRowset which isn't too hard as most of the required information can be obtained from a call to IColumnsInfo::GetColumnInfo() which is supported by the ATL templates. The main issues with the implementation of IColumnsRowset are that GetAvailableColumns() must return at least the following three optional meta data columns:
DBCOLUMN_BASETABLENAME DBCOLUMN_BASECOLUMNNAME DBCOLUMN_KEYCOLUMN
and that GetColumnsRowset() must return a rowset where these optional meta data columns are present and contain valid information.
In our current situation the table name is not really relevant, so we can fill in any old name and the base column names can be the same as the column names that IColumnsInfo reports.
Once this is done we can add support to our updateable proxy and add the appropriate rowset property and the "Insufficient..." error is no more. Unfortunately we have yet to actually fix the problem.
Once a rowset supports IColumnsRowset the client cursor engine has enough information to issue insert, update and delete requests to the rowset in SQL that is written in terms of the 'base table' information. That is it knows the real names of the columns and tables involved in an update and can write an update statement that can deal with rowsets that are the result of joins or data shape commands on an underlying data source. Unfortunately for us this means we are required to support SQL for updates, inserts and deletes.
The resulting SQL arrives at our provider as a command. If you create a table, obtain an ADO recordset from it with client side cursors and optimistic locking then a a breakpoint set in CConversionProviderCommand::Execute() will be hit as soon as you change data in the Data Grid and tab away from the cell. The value of m_strCommandText will be the SQL, something along the lines of:
update table set Col1 = ? where Col1 = ? and
Col2 = ? and Col3 = ? and Col4 = ?
The question marks are place holders for values that have been passed to us in the DBPARAMs accessor. This is because we support ICommandWithParameters (which we need to for our conversion to an ADO recordset). If we didn't support ICommandWithParameters then the SQL would hold the values in the text string itself.
update table set Col1 = 'a' where Col1 = '1' and Col2 = '2' and Col3 = '3' and Col4 = '4'
The reason for the painful where clause is that our data object doesn't have any key columns. The CCE wont use a bookmark column as a key column so unless your data source has a valid unique key column and the column flags are set to include DBCOLUMNFLAGS_ISROWID inside of your data object's GetColumnInformation method then the where clause will be written so that all columns are used to identify the row that needs to be changed.
An exercise for the reader...
I'm afraid that's where I'm going to leave this particular problem. Parsing the SQL is relatively straight forward as the statements will only ever be generated by the CCE and should remain in a consistent form. Identifying the rowset that your command is to manipulate can be done by retaining a mapping table within the provider and using the key into the mapping table as the base table name returned from a call to GetColumnsRowset for a particular rowset object. The row to be modified is easily located if your data source has a unique key and more laboriously located if not (it's a pity that the CCE can't be made to use the bookmark column if no other unique key is present...). Once you have your row handles you need to create a copy of the accessor that you're passed into your command in the context of the rowset and then call the methods in IRowsetChange to do the actual work.
I may be tempted to write another article which covers this final piece of work...
Download
The following source built using Visual Studio 6.0 SP3. Using the July 2000 edition of the Platform SDK. If you don't have the Platform SDK installed then you may find that the compile will fail looking for "msado15.h". You can fix this problem by creating a file of that name that includes "adoint.h".
If your system drive isn't D:\ then you'll have to change the #import statements in IGetAsADORecordsetImpl.h and IGetAsADORecordset.cpp.
IRowsetLocate::Hash() and to Prash Shirolkar at Microsoft for his support and the OMNI Provider article. Supporting updating from our rowset is relatively easy if if we're using server side cursors, however if we select client side cursors then things are more complex. We'll address the server side update issue in this article and cover the changes that are required for using client side cursors in the following article.
Implementing IRowsetChange
The OLE DB provider documentation seems to imply that if you want your provider to be updateable then you need to implement either IRowsetChange or IRowsetUpdate. IRowsetChange has all you need for adding new rows, deleting rows and changing data. IRowsetUpdate adds the ability to batch together a series of changes and apply them to the data source in one go. Interestingly the Janus Grid will use IRowsetChange for all updates if IRowsetUpdate is not available, but will use the later if it is available. As IRowsetUpdate is more complex to implement and doesn't add any value to our examples we won't bother with it. When attempting to get the client cursor engine updates working I added support for IRowsetUpdate but it neither helps nor hinders in getting CCE updates to work...
IRowsetChange is a relatively simple interface to implement, consisting of three fairly straight-forward methods:
HRESULT DeleteRows(
HCHAPTER hChapter,
ULONG cRows,
const HROW rghRows[],
DBROWSTATUS rgRowStatus[]);
HRESULT InsertRow(
HCHAPTER hChapter,
HACCESSOR hAccessor,
void *pData,
HROW *phRow);
HRESULT SetData(
HROW hRow,
HACCESSOR hAccessor,
void *pSrcData);
A provider can choose to implement any or all of of the three methods above, and return DB_E_NOTSUPPORTED for any functionality that it does not support. It reports its level of support via the DBPROP_UPDATABILITY property. See the interface documentation for more detail. This makes implementing the methods slightly more complex as they must first check to see that the rowset that they're being used on supports the operation required. The other main complication with the IRowsetChange methods is handling the consumer notification stages correctly. Each method can cause multiple notifications to be fired into consumers via the IRowsetNotify connection point interface. What's more, consumers can veto some actions by responding appropriately to the notification call.
Using our implementation of IRowsetChange allows us to set the following properties in our rowset's property map.
PROPERTY_INFO_ENTRY_VALUE(IRowsetChange, VARIANT_TRUE)
PROPERTY_INFO_ENTRY_EX(
UPDATABILITY,
VT_I4,
DBPROPFLAGS_ROWSET | DBPROPFLAGS_READ | DBPROPFLAGS_WRITE,
DBPROPVAL_UP_CHANGE | DBPROPVAL_UP_DELETE | DBPROPVAL_UP_INSERT,
0)
PROPERTY_INFO_ENTRY_EX(
OWNINSERT,
VT_BOOL,
DBPROPFLAGS_ROWSET | DBPROPFLAGS_READ | DBPROPFLAGS_WRITE,
VARIANT_TRUE,
0)
PROPERTY_INFO_ENTRY_EX(
OWNUPDATEDELETE,
VT_BOOL,
DBPROPFLAGS_ROWSET | DBPROPFLAGS_READ | DBPROPFLAGS_WRITE,
VARIANT_TRUE,
0)
PROPERTY_INFO_ENTRY_EX(
REMOVEDELETED,
VT_BOOL,
DBPROPFLAGS_ROWSET | DBPROPFLAGS_READ | DBPROPFLAGS_WRITE,
VARIANT_TRUE,
0)
PROPERTY_INFO_ENTRY_EX(
IConnectionPointContainer,
VT_BOOL,
DBPROPFLAGS_ROWSET | DBPROPFLAGS_READ | DBPROPFLAGS_WRITE,
VARIANT_TRUE,
0)
Supporting notifications
To support consumer callbacks via IRowsetNotify our rowset needs to be a connection point container and we need to support the connection of IRowsetNotify connection points. This is achieved relatively easily using the ATL connection point support.
The actual notification firing code is slightly more complex than the event firing code that you can get ATL to generate for you as the consumer is allowed to respond to some notifications and veto the change occurring in the rowset. This means that we need to pay special attention to the return values of the notification calls and react appropriately to requests to veto changes.
The IRowsetNotify event source is actually quite simple, but using the events is complex due to the nature of the event types and event phases that are possible. For example, before an update we might send a "column set" "ok to do" event followed by a "column set" "about to do" event, if a consumer vetoes either of these events then all consumers are sent a "column set" "failed to do" event. Because of this complexity we wrap the groups of events in helper methods which can be called from within our IRowsetChange methods.
The ordering and details of the notification events required by the OLE DB specification is quite difficult to determine from the documentation. The events that this code sends appear to be adequate but your mileage may vary... One method of investigating these events is to watch the sequence of events fired by the client cursor engine when client side cursor updates are applied to a recordset.
An updateable proxy rowset
Now that we have the IRowsetChange and IRowsetNotify event source interfaces we can implement a proxy rowset which uses these to provide update capability to our data object's rowset. CUpdatableProxyRowsetImpl derives from the proxy rowset that we developed over the previous articles and also from our implementations of IRowsetChange and IConnectionPointContainer.
template <
class DataClass,
class T,
class CreatorClass,
class Storage = CRowsetStorageProxy<T>,
class ArrayType = CRowsetArrayTypeProxy<T, Storage>,
class RowClass = CSimpleRow,
class RowsetInterface = IRowsetImpl < T, IRowset, RowClass> >
class CUpdatableProxyRowsetImpl:
public CProxyRowsetImpl<
DataClass,
T,
CreatorClass,
Storage,
ArrayType,
RowClass,
RowsetInterface >,
public IRowsetChangeImpl<T, Storage>,
public IConnectionPointContainerImpl<CUpdatableProxyRowsetImpl>
Within our rowset class we handle the connection point container that's required for our rowset notifications. We also provide code that calls our data object's rowset to perform updates. Inserts and deletes are done using the operations already available on our rowset's proxy storage object.
Please note that the SetDataHelper() method in CUpdatableProxyRowsetImpl has a horrible hard coded limit of 256 bytes of data per column. This could easily be removed but is left as an exercise for the reader ;)
Changes to our data object's rowset
We need to change our data object's rowset object to take advantage of the updateable functionality we have provided. It now inherits from our new updateable proxy rowset and it needs to implement the UpdateColumn() method. Once this is done our object can be updated via ADO as long as you have selected server side cursors. If we run the VB test harness program and create a table, then obtain a rowset from the data object with a server side cursor and batch optimistic locking we can click the button to display the rowset in the Janus Grid and set a break point inside the data object rowset's UpdateColumn() method. When we change the data in the grid we end up inside the rowset's UpdateColumn() method and the data is updated.
Interestingly for the example above to work we don't need to set the data source property DBPROP_DATASOURCEREADONLY to VARIANT_TRUE, but we probably should do... Also, inside our proxy rowset we don't indicate that that the columns are writable by adding DBCOLUMNFLAGS_WRITE to the column flags by default, again we should do. Failure to mark the column data as writable by adding this flag prevents client side cursor updates from working at all... (and yes, it took me ages to find out why they were failing in code that had previously worked fine!)
Server side updates and the DataGrid
The Microsoft DataGrid is a demanding consumer. Whilst the changes detailed above work just fine with the Janus Grid, the DataGrid fails to display any data. The reason for this is that the DataGrid also requires that the following rowset properties are set:
PROPERTY_INFO_ENTRY_VALUE(LITERALIDENTITY,VARIANT_TRUE) PROPERTY_INFO_ENTRY_VALUE(STRONGIDENTITY,VARIANT_TRUE)
These properties tell the grid that each row in the rowset is represented by a single row handle. That is, if the same row is returned from the rowset the row handle is simply add reffed and returned rather than a new row handle being created. This allows a consumer to easily match rows sent to it in notification calls with rows that it already holds.
Once these two are set the DataGrid expects IRowsetLocate::Hash() to be implemented, though I'm at a loss to understand why.
Insufficient base table information...
Our rowset now supports server side cursor updates and works with some of the common Microsoft data bound controls. However if we select client side cursors and optimistic locking in our test program and try to change data we get an error message "Insufficient base table information for updating or refreshing". Switching to batch optimistic locking simply causes the error to occur when we issue an UpdateBatch command on the recordset rather than as soon as the data is changed... We address the cause of this error and its solution in the next article.
Download
The following source built using Visual Studio 6.0 SP3. Using the July 2000 edition of the Platform SDK. If you don't have the Platform SDK installed then you may find that the compile will fail looking for "msado15.h". You can fix this problem by creating a file of that name that includes "adoint.h".
If your system drive isn't D:\ then you'll have to change the #import statements in IGetAsADORecordsetImpl.h and IGetAsADORecordset.cpp.
IRowsetLocate::Hash() and to Prash Shirolkar at Microsoft for his support and the OMNI Provider article.IRowsetLocate, or the bookmark related properties, so the bookmark functionality can't be used by consumers. In this article we'll remedy that by adding support for IRowsetLocate.
A quick search for IRowsetLocate in the MSDN leads us to a rather helpful implementation of the interface which can be found in the "Enhancing the Simple Read-Only provider" section of the OLE DB Provider template documentation. Unfortunately the original implementation that was supplied had a few bugs in it, the latest version is better, but it's still buggy when you have more than 256 rows. We'll fix those bugs and then integrate the interface into the proxy rowset. Once that's done it's easy to build implementations of IRowsetScroll and IRowsetExactScroll to complete our bookmark support.
Supporting complex Data Bound controls
One of the advantages of OLE DB is that you can choose how much functionality you wish to expose. If your provider is relatively simple then you are not forced to provide all of the complex features that you would expect to find in a provider for a relational database. Although there are various "levels" of "conformance" with the OLE DB specification it's often difficult to work out exactly what functionality is required of your provider. The flexibility of the OLE DB specification is thus something of a double edged sword, whilst it's easy to conform to the spec it's equally easy for consumers to require you to implement some additional functionality before they can use your provider.
This wouldn't be so bad if all data bound controls came with documentation that stated exactly what they expected of a provider. Unfortunately I've yet to find a control that comes with such documentation. Each control has an arbitrary set of requirements that it makes on a provider. It would seem that the only way to be sure that your provider could work will all possible consumers would be to implement the entire OLE DB specification. However even that might not be enough for some of Microsoft's own controls. If you want to support read/write functionality on Microsoft's Data Grid, for example, it appears that you are required to support some interfaces that aren't present in the documentation or SDK!
If OLE DB were to use the standard COM functionality discovery mechanism, QueryInterface(), then it would be relatively easy to work out what certain consumers required of you by simply watching for the interfaces they asked you for. Unfortunately OLE DB uses a property based mechanism for functionality discovery. If you fail to answer the "what properties do you support" questions correctly then you'll never see any QI calls for the interfaces that provide the functionality that your consumers desire. I can understand why the designers did it this way: a consumer may need to discover lots of information about a provider in one go and multiple interface requests and calls would be horribly inefficient, but it makes it very difficult to experiment and find out what third party consumers require of your provider. OLEB Service Providers confuse the matter even more by stepping in and providing extra functionality for you, in certain circumstances, if it can synthesize the functionality that you're lacking from functionality that you present. Finally the ATL implementation of the property mechanism is far from easy to trace through and doesn't have any kind of debug output to show exactly what property calls are occurring.
This makes it particularly difficult to add features to your OLE DB provider as it's impossible to know how many controls you will be able to support without actually testing your code with each of the controls. Even a relatively simple piece of functionality, like bookmarks, can be difficult to implement because of the lack of documentation about what a particular control requires.
Determining what a control needs
As an example of the difficulties of adding functionality to your provider, take a look at this simple test program and run it with the object that we developed in our last article. The test is a simple Visual Basic program that creates our object and allows us to obtain a recordset from it and then connect the recordset to various data bound controls. As you will see, if you press "Make Table" and then "Get Recordset" and then press the various buttons to connect the recordset to the controls each control reacts differently to our minimalist recordset implementation: Only the MSHFlexGrid works. The Data List and Data Combo remain blank. The Linked Edit works, but then that's a "simple data bound control" - one that's only bound to a single row - so we would expect it to work... The Data Grid tells us that it needs bookmarks and the Janus GrixEx just reports that we're an "invalid recordset".
Contrast this with the results obtained when we check the "Client" check box in the Cursor Location frame. When using the client cursor engine ADO steps in and implements the missing functionality for us. This is great, and if we really want to use client side cursors then our work here is done. However, there's a major problem with client side cursors - they're client side. In this context that means that all of the effort that we went to so that our data object could retain ownership of its data and only convert it on demand was wasted. The ADO cursor engine simply fetches all of our data from our object into the cursor engine and adds functionality to the rowset implementation... Not ideal.
We can try and work out what functionality is required of us by watching the debug strings output our provider as we attempt to attach it to each control. Add _ATL_DEBUG_QI to the project settings for the provider and do a rebuild all. Then set up Visual Basic as the debug target for the OLE DB provider and start a debug run. Load the test harness project into Visual Basic and run it. You should then see the debug string output displayed in the Visual C++ debugger. Unfortunately the results are somewhat misleading. As I indicated above, whilst we do see some QI calls, most of the negotiation appears to occur through a requests for the rowset's properties (the Janus GridEx doesn't even do that!).
The Data Grid QI's for IConnectionPointContainer (probably seeing if we support change notifications), then IColumnsInfo and ICommandText and finally makes a get properties call... The DataList just asks for ICommandText and IColumnsRowset before making a get properties call. The DataCombo calls get properties then QIs for IConnectionPointContainer, IColumnsInfo and ICommandText, makes another get properties call and then QIs for IColumnsRowset. None of this would lead us to believe that bookmarks and IRowsetLocate were the feature that was lacking...
Only the Microsoft Data Grid has given us any meaningful information about what it requires of us and that was via an error message! From that we can look up bookmark support in the OLE DB documentation and discover that we must implement IRowsetLocate and answer correctly for several property values... As we'll see, implementing bookmarks on our rowset will make it work with some of the controls in the test harness program, the others will at least give us more hints at what else they require. It's unfortunate that we could only have discovered this fact by trial and error.
Supporting IRowsetLocateImpl
To add support for Bookmarks we need to change our DataObjectRowset object so that it derives from a CProxyRowsetImpl that itself has IRowsetLocate, rather than IRowset, as its base class. As mentioned before, we can leverage (steal) an implementation from the "Enhancing the Simple Read-Only provider" section of the OLE DB Provider template documentation.
The resulting changes to our DataObjectRowset look something like this:
// This is what we did have...
class CDataObjectRowset :
public CProxyRowsetImpl<
CMyDataObject,
CDataObjectRowset,
CConversionProviderCommand>
{
// This is what we have now...
class CDataObjectRowset :
public CProxyRowsetImpl<
CMyDataObject,
CDataObjectRowset,
CConversionProviderCommand,
CRowsetStorageProxy<CDataObjectRowset>,
CRowsetArrayTypeProxy<
CDataObjectRowset,
CRowsetStorageProxy<CDataObjectRowset> >,
CSimpleRow,
IRowsetLocateImpl < CDataObjectRowset > >
{
It's times like this that you begin to wish that you'd chosen a different order for the default template parameters! The storage and array proxy classes and the simple row object were all defaulted in our original implementation. Now, as we need to replace the final template parameter, we must copy the default values from the CProxyRowsetImpl template and just replace the base class parameter.
So, our rowset now derives from our implementation of IRowsetLocate, we now need to hook it up to our interface map. Since all of the interfaces are currently handled by the CProxyRowsetImpl class we need to add a com map to our CDataObjectRowset that chains to the one that's present in the CProxyRowsetImpl and then add support for IRowsetLocate. Much like this:
BEGIN_COM_MAP(CDataObjectRowset) COM_INTERFACE_ENTRY(IRowsetLocate) COM_INTERFACE_ENTRY_CHAIN(ProxyRowsetClass) END_COM_MAP()
To make the chaining easier we've added a typedef to the CProxyRowsetImpl so that derived classes can use "ProxyRowsetClass" rather than having to specify the template and all the template parameters again!
This is all well and good, but unless we tell our consumers that we support bookmarks via the correct OLE DB properties they'll never request the IRowsetLocate interface.
Adjusting the property map
At first sight, you could be confused into thinking that the default rowset properties that ATL supplies you with includes support for bookmarks. After all, the rowset's property map looks something like this:
BEGIN_PROPSET_MAP(CConversionProviderCommand)
BEGIN_PROPERTY_SET(DBPROPSET_ROWSET)
PROPERTY_INFO_ENTRY(IAccessor)
PROPERTY_INFO_ENTRY(IColumnsInfo)
PROPERTY_INFO_ENTRY(IConvertType)
PROPERTY_INFO_ENTRY(IRowset)
PROPERTY_INFO_ENTRY(IRowsetIdentity)
PROPERTY_INFO_ENTRY(IRowsetInfo)
PROPERTY_INFO_ENTRY(IRowsetLocate)
PROPERTY_INFO_ENTRY(BOOKMARKS)
PROPERTY_INFO_ENTRY(BOOKMARKSKIPPED)
PROPERTY_INFO_ENTRY(BOOKMARKTYPE)
PROPERTY_INFO_ENTRY(CANFETCHBACKWARDS)
PROPERTY_INFO_ENTRY(CANHOLDROWS)
PROPERTY_INFO_ENTRY(CANSCROLLBACKWARDS)
PROPERTY_INFO_ENTRY(LITERALBOOKMARKS)
PROPERTY_INFO_ENTRY(ORDEREDBOOKMARKS)
END_PROPERTY_SET(DBPROPSET_ROWSET)
END_PROPSET_MAP()
All is not what it seems. If you look in atldb.h you'll see that the property info entry macro expands to include some "default" flags, types and values that are specific for each property supplied. These are used to fill in the property map. What can be confusing is that specifying a property info entry for IRowset results in flags that say you DO support the interface whereas specifying a property info entry for IRowsetLocate results in flags that say you DONT support the interface! This is hardly intuitive. To determine which properties you support from the property map you must search through atldb.h and cross reference the other macros that it contains. I feel it would be far better if all of these PROPERTY_INFO_ENTRY macros were in fact PROPERTY_INFO_ENTRY_VALUE macros (these force you to specify the value of the property, you can then see, at a glance, if you do or do not support a property etc.) of course I understand why it's done this way, it makes the wizard easier to code...
So, what the default property map actually says is this:
We do support the following interfaces: IAccessor, IColumnsInfo, IConvertType, IRowset, IRowsetIdentity, IRowsetInfo. But we don't support IRowsetLocate.
We answer true for these properties CanFetchBackwards, CanHoldRows and CanScrollBackwards. But false for these Bookmarks, BookmarkSkipped, BookmarkType, LiteralBookmarks and OrderedBookmarks.
Obvious, isn't it.
So, it should just be a case of us using the PROPERTY_INFO_ENTRY_VALUE macro and specifying the correct values, such as VARIANT_TRUE for our IRowsetLocate property? It would be nice if it were this easy. Unfortunately the flags specified if we do that means that the property is read only. OLE DB properties are used by both the provider to indicate the functionality that it supports and by the consumer to indicate the functionality it requires. If we were to use the PROPERTY_INFO_ENTRY_VALUE macro we would end up forcing the consumer to accept that we must provide IRowsetLocate. It's better for us to make the property read/write so that the consumer can read the property and see that we support the interface and then write to the property and set it to false if it doesn't require us to support it. This may allow us to optimise some memory usage as we will know that we will never be asked for the interface...
So, to specify our bookmark properties we need to use the mother of all property map macros; PROPERTY_INFO_ENTRY_EX... See the code for the resulting map entries.
The problems with IRowsetLocateImpl
Now that we have all the code in place for our implementation of IRowsetLocate to be requested, we just have to fix a couple of bugs in the code that we're stealing.
The current version of IRowsetLocateImpl that can be found here suffers from one or two problems. Firstly, the bookmarks are declared as being DWORDs yet inside IRowsetLocate they are treated as BYTEs this leads to the implementation failing if a rowset has more than 256 rows. We fix this problem by casting the bookmark pointer to a DWORD pointer before dereferencing them. Secondly there are some rather dubious locking practices employed which can cause the object to be locked and then left in a locked state if an error occurs.
An older version of this implementation (from a previous version of the same sample) additionally had a off by one error on the case where the bookmark requested was DB_BMKLST.
See the code sample for the fixed implementation.
Integration with the proxy rowset
Our bookmark implementation is almost complete. The proxy rowset class already provided some support for bookmarks so we don't need to change anything. The support is included in the following places:
CProxyRowsetImpl<>::OnPropertyChanged() handles various rowset properties being set, and sets associated properties as required.CProxyRowsetImpl<>::BookmarksRequired() is a helper function that can be called to determine if we need to return a rowset that contains a column with the bookmarks in.CProxyRowsetImpl<>::InternalGetColumnData() handles and populates requests for data from the bookmark column.CProxyRowsetImpl<>:StorageProxy_GetColumnInfo() handles adjusting the column information that we return to optionally include the bookmark column if required.and finally:
CProxyRowsetImpl<>:BuildColumnInfo() always builds a column map that includes the bookmark column, it then allows StorageProxy_GetColumnInfo to decide if we return this column to the caller.Additional bookmark interfaces
Whilst IRowsetLocate is the main interface that supports bookmarks there are several others, most notably IRowsetScroll and then short lived IRowsetExactScroll.
IRowsetScroll allows for consumers to obtain rows located at approximate positions within a rowset, it can be used when exact positioning is not required. It is derived from IRowsetLocate and an implementation can be found in IRowsetScrollImpl.h.
IRowsetExactScroll appears to have been introduced in OLE DB version 2.0 and then became deprecated in OLE DB version 2.1 - though controls often still ask for it. To include support for IRowsetExactScroll you have to be using version 2.x of the Data Access SDK. If you are using version 2.1 or later then you have to include a "deprecated" define to get the interface brought in - it's unfortunate that the define used is not named something more OLE DB specific... IRowsetExactScroll is derived from IRowsetScroll. Because of how we've implemented IRowsetScroll::GetApproximatePosition() - it gets rows at an exact position as our bookmarks are also row numbers - it's trivial to implement IRowsetExactScroll as it can simply call through to IRowsetScroll. Our implementation of IRowsetExactScroll can be found, not too surprisingly, in IRowsetExactScrollImpl.h.
The sample code assumes we're using the MDAC SDK v2.1 or later, so includes the #DEFINE deprecated. Check the OleDb.H file and search for OLEDBVER to get some idea of what version you're using...
As we're using OLE DB v2.1 we may as well have our provider advertise the fact. To do this we need to make a change to the DataSource object's property map. Locate the PROPERTY_INFO_ENTRY macro for the PROVIDEROLEDBVER property and replace it with a PROPERTY_INFO_ENTRY_VALUE macro for that property and specify a value of "2.1".
We can now add support for IRowsetScroll and IRowsetExactScroll to our rowset's property map. IRowsetScroll is easy, just use a PROPERTY_INFO_ENTRY_EX macro. IRowsetExactScroll is slightly more complex as there's no support for this property built in to the ATL wizard and headers - this isnt too much of a problem, we can use the macro as normal, but we have to add an entry to the string table that ATL provided us with. All of the properties that ATL supports have entries in a string table that's added to your project by the wizard. We need to add an entry for IDS_DBPROP_IRowsetExactScroll to this string table for the macro to work.
In the sample we add support for IRowsetExactScroll to the DataObjectRowset object by replacing the IRowsetLocateImpl<> that we used above with IRowsetExactScrollImpl<> and adding corresponding entries to the COM map.
Even with IRowsetExactScroll support the Data Grid, Data List and Data Combo fail to display data. The Data List and Data Combo query for, and use, IRowsetExactScroll and all of them create an accessor, but none of them actually pull any data! This is disappointing to say the least. Especially since the controls now silently fail and give us no obvious indication of what it is we need to do to get them to work...
Still, at least we have the Janus grid working correctly. Chances are that other non Microsoft controls might work with us also!
Download
The following source built using Visual Studio 6.0 SP3. Using the July edition of the Platform SDK. If you don't have the Platform SDK installed then you may find that the compile will fail looking for "msado15.h". You can fix this problem by creating a file of that name that includes "adoint.h".
If your system drive isn't D:\ then you'll have to change the #import statements in IGetAsADORecordsetImpl.h and IGetAsADORecordset.cpp.
Revision history
_Recordset15 should be Recordset15. Thanks to Nie Jiantao for reporting this. The rowset object that the ATL wizard has provided us with is of no use to us. It's fine for simple data where you can copy the data to be made available via ADO into the rowset's array. We want to retain control of our data and not be forced to create a copy of it, so the rowset needs to access our data in-place in our data object.
At first it may seem that the design of the ATL OLE DB provider templates is completely inappropriate for our needs. However, the design is actually very flexible and we can replace two simple components and provide the functionality that we require.
The "proxy" rowset
The standard OLE DB template rowset object, CRowsetImpl, provides access to data that's stored in a contiguous array within the rowset object itself. This is fine for simple example programs but almost useless for our required application. We want to keep our data stored within our simple data object, it may be too costly to copy all of the data into a new rowset object just to provide access via ADO. We'd rather leave the data where it is and just provide access to it.
Luckily the CRowsetImpl template relies on two template parameter classes for storing its data. The template itself looks something like this:
template < class T, class Storage, class CreatorClass, class ArrayType = CSimpleArray<Storage>, class RowClass = CSimpleRow, class RowsetInterface = IRowsetImpl < T, IRowset, RowClass> > class CRowsetImpl : etc...
The pieces we're interested in replacing are the Storage and ArrayType classes. These are used by the default implementation to retrieve the rowset data from. By replacing these two template parameters with classes that implement the required functionality we can dictate where the rowset gets its data from.
We'll write a proxy rowset template. It's a proxy because it just takes the place of a rowset object and forwards all of the interesting calls to our data object. The data object stores its data in exactly the same way as before and the proxy rowset accesses the data in-place, on demand. There's no initial startup overhead involved, though there's probably a little overhead in the actual data access.
The proxy rowset template looks like this:
template <
class DataClass,
class T,
class CreatorClass,
class Storage = CRowsetStorageProxy<T>,
class ArrayType = CRowsetArrayTypeProxy<T, Storage>,
class RowClass = CSimpleRow,
class RowsetInterface = IRowsetImpl < T, IRowset, RowClass> >
class CProxyRowsetImpl:
public CRowsetImpl<
T,
Storage,
CreatorClass,
ArrayType,
RowClass,
RowsetInterface >
The important things to note are the classes that are defaulted for the Storage and ArrayType template parameters. These two proxy classes simply forward all requests to the proxy rowset rather than fielding them themselves. The proxy rowset can then pass requests on to the data object that it's associated with. By requiring the data object to provide function bodies for several simple data access and information functions the proxy rowset can deal with all of the technicalities of being an OLE DB rowset but still pass the requests for data and information through to the data object itself.
The functions that are data object specific, and must be provided by the class derived from our proxy rowset are as follows:
virtual void GetColumnInformation( size_t column, DBTYPE &dbType, ULONG &size, std::string &columnName, DWORD &flags);
Called when building the column information structure for the rowset. Column numbering starts at 0. The type size and flags fields should be filled in with the values that are appropriate for this column of data - see DBCOLUMNINFO for more details. The data type specified in dbType should be the native data type that you are storing your data as. The proxy rowset will handle all data conversion requirements to and from this data type for you.
virtual void GetColumnData( size_t row, size_t column, DBTYPE &dbType, ULONG &size, void *&pData, bool &bIsUpdatable);
Called when access to the data in a particular row and column is required. Row and column numbering starts at 0. Type and size are the actual types and sizes of this element of the data (these are likely to be the same as those returned from GetColumnInformation for the column as a whole except in the case of variable length string data when the size returned here can be the actual length of the string, rather than the maximum length that's returned from GetColumnInformation. The void pointer, pData, should be set to point at the start of the data item itself. The proxy rowset will use this pointer to access the data. The pointer should be set to point straight at your data, you shouldn't allocate a buffer or do any copying. The bIsUpdatable flag isn't relavant until we add functionality to the proxy rowset in a later article to make it support read/write rowsets rather than simple read only rowsets.
virtual size_t GetNumColumns(); virtual size_t GetNumRows() const; virtual HRESULT AddRow(); virtual HRESULT RemoveRow(int nIndex);
The others are all fairly obvious.
The proxy rowset contains two pointers that refer to the object that it is representing. These are set up automatically when the rowset is connected to the object. You can access these from within your derived class to provide access to your data object. One pointer is a pointer to your data object's IUnknown, you're unlikely to need to use this, it's only really for maintaining a reference on your object whilst the proxy rowset object is connected to it. The second pointer is a pointer to your object itself. Through this your proxy rowset derived class can get direct access to your data object's internals. It's allowed to do this because we take great care when creating the proxy rowset to make sure it's created in the same COM apartment as the data object.
Connecting the rowset to your object
Now that we have a rowset object and all of the ADO and OLE DB framework in place all that's left is to create the rowset and connect it to your data object.
We need to move back inside our OLE DB provider objects and intercept the rowset creation request at the command object's execute method. This is where the action will happen...
At present the method probably looks something like this:
CSimpleDataObjectRowset *pRowset; return CreateRowset( pUnkOuter, riid, pParams, pcRowsAffected, ppRowset, pRowset);The ATL OLE DB template function
CreateRowset is being called which does the work of building a standard rowset of the type specified and then calls the rowset's execute method to populate it. We don't want any of this to happen, so we can rip out the above and replace it with some code that works with the custom command object we created in the ADO layer. This command has passed us the IUnknown pointer of the data object that we're providing a rowset onto. First we need to get hold of this IUnknown pointer using the parameter accessor that we are passed, then we can get to work...
As mentioned above we need to take care to create the rowset object in the same COM apartment as the data object itself. This will allow us to access the data object directly from the rowset object using a normal C++ pointer to the data object. The easiest way of making all of this work is for us to ask the data object itself to create and return the rowset object. Because the data object creates the rowset object as a C++ object we know that the rowset is in the same COM apartment as the data object. Of course, this means we need to get from the OLE DB provider's command object back into the data object.
The easiest way into the data object from the command object is via a COM call. In the command object we QueryInterface on the data object's IUnknown pointer for the _IGetAsOLEDBRowset interface. We then call the interface's only method, GetAsRowset() and pass our own IUnknown pointer in, along with a bunch of other stuff.
The work continues back inside the data object as we execute the GetAsRowset() method of the _IGetAsOLEDBRowset interface... The template implementation of this method simply calls into the data object on a method called AsRowset() and this is where the work of actually creating the rowset and linking it to the data object actually occurs.
We've jumped through a lot of hoops to get to this point, but all of the code up to now has been generic template implementations which do the right thing. We're now inside a method on our data object and we have derived a class from the proxy rowset implementation to act as our rowset class. With a little custom code like the following, we can create our rowset and link it to our data.
HRESULT CMyDataObject::AsRowset(
/* [in] */ IUnknown *pUnkCreator,
/* [in] */ IUnknown *pUnkOuter,
/* [in] */ REFIID riid,
/* [out] */ LONG *pcRowsAffected,
/* [out, iid_is(riid)] */ IUnknown **ppRowset)
{
CDataObjectRowset *pRowset = 0;
HRESULT hr = CreateRowset(
pUnkCreator,
pUnkOuter,
riid,
ppRowset,
pRowset);
if (SUCCEEDED(hr))
{
IUnknown *pUnknown = 0;
hr = QueryInterface(IID_IUnknown, (void**)&pUnknown);
if (SUCCEEDED(hr))
{
hr = pRowset->LinkToObject(this, pUnknown, pcRowsAffected);
pUnknown->Release();
}
}
return hr;
}
We can then hand the rowset back to the template implementations and they will take care of returning the object to the ADO layer which will wrap it in an ADO recordset and return it to our Visual Basic client code. We can even defer the most complex part of the code, that of creating and wiring up the rowset object, back to the _IGetAsOLEDBRowset implementation template, the call to CreateRowset() is a template member function which is paramaterised on the rowset class we pass into it. It handles creating the rowset COM object and copying the command object's properties into it - in the same way that the standard ATL OLE DB rowset is created.
The complete working example code for the above can be downloaded from here.
So, how do I give ADO access to my object?
IGetAsADORecordset, _Recordset and IGetAsOLEDBRowset interfaces.IGetAsADORecordsetImpl and IGetAsOLEDBRowsetImpl implementation templates to your class's inheritance hierarchy in your header file.COM_INTERFACE_ENTRY(_IGetAsOLEDBRowset)COM_INTERFACE_ENTRY_CHAIN(IGetAsADORecordsetImpl<CMyDataObject>)CProxyRowsetImpl and provide function bodies for the virtual functions required. These should use the pointer to your data object that's available to them as a protected member variable inherited from CProxyRowsetImpl to access your object's data.AsRowset(), probably just as shown above.All of this assumes that you have an OLE DB conversion provider that will do the conversion for you. If you are only doing this for one object, package the conversion provider inside the same DLL as the object, if you're doing lots of objects like this, create a separate provider dll and have all your objects use the one provider.
Download
The following source built using Visual Studio 6.0 SP3. Using the July 2000 edition of the Platform SDK. If you don't have the Platform SDK installed then you may find that the compile will fail looking for "msado15.h". You can fix this problem by creating a file of that name that includes "adoint.h".
If your system drive isn't D:\ then you'll have to change the #import statements in IGetAsADORecordsetImpl.h and IGetAsADORecordset.cpp.
Revision history
_Recordset15 should be Recordset15. Thanks to Nie Jiantao for reporting this. It's quite common to find a legacy data object that would benefit from being accessed via ADO. The problem is that providing ADO access is a non-trivial thing to do. The ATL OLE DB Provider templates are useful for simple situations but appear to fall down when you want your own object to own the data rather than simply copying it all into an array inside the rowset object. Also, getting access to your data isn't that easy, you have to hook yourself up to a data provider, then get a rowset from it, etc.
However, it is possible to extend the ATL templates to allow your object to retain ownership of its data, and it's also possible to hide all of the hoops that you have to jump through to wire up your object to its ADO recordset view.
This article will first cover the mechanics of providing an ADO interface onto a simple data object and then deal with writing a reusable OLE DB rowset implementation that can provide in-place access to the simple data object's data but still be used in an ATL OLE DB provider framework.
A simple data object
Suppose we have a simple data object that implements the following interface and internally represents its data in a tabular form.
interface IMyDataObject : IUnknown
{
HRESULT SetColumnSize([in] long columnSize);
HRESULT AddColumn(
[in] BSTR columnName,
[out, retval] long *index);
HRESULT GetColumnName(
[in] long index,
[out, retval] BSTR *columnName);
HRESULT AddRow([out, retval] long *index);
HRESULT RemoveRow([in] long index);
HRESULT Depth([out, retval] long *depth);
HRESULT Width([out, retval] long *width);
HRESULT SetAt(
[in] long rowIndex,
[in] long columnIndex,
[in] BSTR value);
HRESULT GetAt(
[in] long rowIndex,
[in] long columnIndex,
[out, retval] BSTR *value);
};
The object can be used to store a table of strings. It's easy enough to use this object from Visual Basic but the interface isn't ideal. You can download the simple data object and a Visual Basic test program from here.
Obtaining an ADO recordset
The ADO interface that we will use will access our data object via a custom OLE DB provider. We can add a provider to the simple data object's DLL by selecting Insert New ATL Object and choosing a Provider from the Data Access section of the object wizard. Once we've done this we can add an interface to the simple data object that will allow it to return an ADO recordset view of itself. This interface will use ADO to access the OLE DB provider that we've added and construct a recordset to return to our Visual Basic client code.
The interface that we'll add will look like this:
interface IGetAsADORecordset : IDispatch
{
[id(1), helpstring("method GetAsRecordset")]
HRESULT GetAsRecordset(
[in] CursorLocationEnum CursorLocation,
[in] LockTypeEnum LockType,
[in] CursorTypeEnum CursorType,
[out, retval] VARIANT *pvRecordset);
};
We've chosen a variant to return the recordset as it means we don't have to worry about using importlib to pull in the ADO type library. It results in one extra QI call for Visual Basic to get the correct interface from the IDispatch pointer stored in the variant but it frees us from a run-time binding to the location of the ADO type library (see knowledge base article Q186387).
The Visual Basic client code can then do something like the following:
Dim dataObject as New MyDataObject
Dim asRs as IGetAsADORecordset
Set asRs = dataObject
Dim rs as ADODB.Recordset
Set rs = asRs.GetAsRecordset( _
adUseClient, _
adLockOptimistic, _
adOpenStatic)
' now do something with the recordset we have!
We should probably make the cursor and locking flags optional and have them default to standard values which would make the code less above less complex in most cases.
We can add this interface to our simple data object's IDL and, in keeping with the ATL way of doing things, we can write a template that implements the interface for us.
The resulting implementation template looks something like this:
template <
class T,
const GUID* plibid = &CComModule::m_libid,
WORD wMajor = 1,
WORD wMinor = 0,
tihclass = CComTypeInfoHolder>
class ATL_NO_VTABLE IGetAsADORecordsetImpl
: public IDispatchImpl<
IGetAsADORecordset,
&IID_IGetAsADORecordset,
plibid,
wMajor,
wMinor,
tihclass>
{
public:
STDMETHOD(GetAsRecordset)(
CursorLocationEnum cursorLocation, // [in]
LockTypeEnum lockType, // [in]
CursorTypeEnum cursorType, // [in]
VARIANT *pvRecordset) // [out]
{
if (!pvRecordset)
{
return E_POINTER;
}
return E_NOTIMPL;
}
};
It's fairly simple, but as the interface is a dispatch based and we inherit from IDispatchImpl we take extra template parameters and default them so that our users can adjust the functionality of the IDispatch implementation if they need to.
Of course we now have to connect our data object to the OLE DB provider so that it can access our tabular data and present it via ADO. As we'll be using ADO to connect to our OLE DB provider we must somehow pass the data object through the ADO call into the OLE DB provider. Luckily ADO providers a method to do this kind of thing in the form of a Command that takes a parameter, which can be anything that fits in a variant. We'll simply pass the IUnknown pointer to our data object as the parameter to our ADO Command.
We'll use the #import feature of VC++ to make the ADO coding easier. The resulting code is something like this:
ADODB::_ConnectionPtr Connection("ADODB.Connection");
Connection->Open(
_bstr_t( L"Provider=SimpleDataObject.ConversionProvider.1"),
_bstr_t(""),
_bstr_t(""),
-1);
ADODB::_CommandPtr Command("ADODB.Command");
Command->CommandText = _bstr_t("CONVERT");
pUnknown->AddRef();
ADODB::_ParameterPtr Param1 = Command->CreateParameter(
_bstr_t("IUnknown"),
ADODB::adIUnknown,
ADODB::adParamInput,
-1,
_variant_t(pUnknown));
Command->Parameters->Append( Param1 );
Command->ActiveConnection = Connection;
CComQIPtr<IDispatch> spCommand = Command;
ADODB::_RecordsetPtr Rs1("ADODB.Recordset");
_variant_t vtEmpty (DISP_E_PARAMNOTFOUND, VT_ERROR);
Rs1->CursorLocation = (ADODB::CursorLocationEnum)cusorLocation;
Rs1->CursorType = (ADODB::CursorTypeEnum)cursorType;
Rs1->LockType = (ADODB::LockTypeEnum)lockType;
Rs1->Open(
_variant_t(spCommand),
vtEmpty,
ADODB::adOpenUnspecified,
ADODB::adLockUnspecified,
-1);
// Return the recordset in a variant...
pvRecordset->vt = VT_DISPATCH;
pvRecordset->pdispVal = (IDispatch*)Rs1.Detach();
Assuming our OLE DB Provider does its part then that's all we need to do from an ADO point of view.
Getting something to work...
We can get the code above working to the point where it will return the standard "view of a file system" ADO recordset that the default, wizard-generated, OLE DB provider returns by adjusting the wizard-generated code very slightly.
First we need to add support for ICommandWithParameters as our command object incorporates a parameter. The implementation of this interface is very straight forward since our command is so simple. Of the three methods in ICommandWithParameters, only SetParameterInfo will ever get called for the command we use above - and this can simply return S_OK.
Once we support ICommandWithParameters our ADO calls will get all the way through to the OLE DB provider's rowset implementation of the Execute method. This needs to be adjusted to make it work with our command. The wizard-generated code is expecting the command text to be a file specification, it then returns a director listing of all files that match the specification. Later we will replace the entire rowset implementation with one of our own, but for now simply hacking the szDir variable to always be set to "*.*" will suffice.
Although this recordset does not represent the data stored in our simple data object in any way, it does at least provide a quick and dirty way of testing that the framework that we're building actually works.
Exposing the recordset interface from QI
Now that we have all the code required to expose a recordset it would be nice to make it a 'real' interface on our data object rather than so obviously a separate view on the data. From a Visual Basic point of view it would be nicer if all we had to do was this:
Dim dataObject as New MyDataObject
Dim rs as ADODB.Recordset
Set rs = dataObject
' now do something with the recordset we have!
This is actually reasonably easy. We need to create the ADO recordset as a tear-off interface when we're first asked for it and aggregate it into our data object. We can then add some COM_INTERFACE_ENTRY_FUNC macros to our COM Map to handle the various flavours of ADO recordset interfaces that we might be asked for and also to handle any other interfaces that the ADO recordset object is normally expected to expose... This can all be done inside our implementation of IGetAsADORecordset which leaves us only having to chain our object's interface map to the IGetAsADORecordsetImpl one...
Download
The complete implementation of our data object with support for returning an ADO recordset (full of unrelated file system information!) via IGetAsADORecordset and also via QI, can be found here.
The following source built using Visual Studio 6.0 SP3. Using the July 2000 edition of the Platform SDK. If you don't have the Platform SDK installed then you may find that the compile will fail looking for "msado15.h". You can fix this problem by creating a file of that name that includes "adoint.h".
Revision History
_Recordset15 should be Recordset15. Thanks to Nie Jiantao for reporting this.