UpdatePV Sample: Implements an Updatable OLE DB Provider

  • Article

The UpdatePV sample is an OLE DB Provider Templates sample that demonstrates how to implement an updatable (read/write) provider. Specifically, it demonstrates how to perform immediate and deferred inserts/updates/deletes. UpdatePV also demonstrates how to use schema rowsets (which make it easier for some wizards to interact with a provider). UpdatePV also demonstrates the IRowsetLocateImpl class, as does MyProv.

See the AdvancedPV sample for illustrations of additional techniques on loading and saving data with a provider.

Security noteSecurity Note

This sample code is intended to illustrate a concept, and it shows only the code that is relevant to that concept. It may not meet the security requirements for a specific environment, and it should not be used exactly as shown. We recommend that you add security and error-handling code to make your projects more secure and robust. Microsoft provides this sample code "AS IS" with no warranties.

To get samples and instructions for installing them:

To access samples from Visual Studio

  • On the Help menu, click Samples.

    By default, these samples are installed in drive:\Program Files\Microsoft Visual Studio 10.0\Samples\.

  • For the most recent version of this sample and a list of other samples, see Visual Studio Samples on the MSDN Web site.

Building and Running the Sample

To demonstrate the sample's intended features, build the sample, create a consumer project with an accessor for the provider, and create a console application to access and output the data.

To build and run this sample

  1. Open the solution file UpdatePV.sln.

  2. From the Build menu, click Build Solution.

  3. Create a consumer project with the ATL Project wizard (make it an attributed .dll).

  4. Add an OLE DB consumer to the consumer project (from Add Class, select ATL OLE DB Consumer).

  5. In the ATL OLE DB Consumer wizard, click the Data Source button and in Data Link Properties, select UpProv OLE DB Provider. (The UpProv provider should be registered automatically when you build UpdatePV, but if you don't see it listed here, run regsvr32.exe on UpdatePV.dll.)

  6. Click Next to go to the Connection tab, then under Enter the initial catalog to use, make sure the path name to MyData.txt is correct.

  7. Click Ok. The Select Database Object dialog will appear, then open Tables; there is only one item: the path name for MyData.txt. Select it and click OK. You return to the ATL OLE DB Consumer wizard.

  8. In the ATL OLE DB Consumer wizard, select Table, rename the class to something shorter (if necessary) such as CMyCons, and click Finish.

  9. Dismiss the security warning dialog that pops up by pressing OK.

  10. Remove this line from CMyCons.h:

    #error Security Issue: The connection string may contain a password

    This line will prevent compilation, but is inserted to alert you to the fact that (in real-world scenarios) sensitive information should be protected.

  11. Build the consumer project by right-clicking on the project's node in the Solution Explorer and clicking Build.

  12. Create a new console application. In the .cpp file, include the consumer header and modify the code as follows:

    #include "stdafx.h"
#include <atldbcli.h>
#include "..\consumer\cmycons.h"

int _tmain(int argc, _TCHAR* argv[])
{
   HRESULT hr = CoInitialize(NULL);

   CMyCons c;

   hr = c.OpenAll();
   ATLASSERT( SUCCEEDED( hr ) );

   hr = c.MoveFirst();
   while( SUCCEEDED(hr) && hr != DB_S_ENDOFROWSET )
   {
      printf( "%d %s %s %s %s\n", c.m_Fixed, c.m_Command, c.m_Text, 
         c.m_Command2, c.m_Text2 );
      hr = c.MoveNext();
   }

   c.CloseAll();
   CoUninitialize();
   return 0;
}

  13. Place a breakpoint on the CoUninitialize function; this will make the console stay open so you can view the results. Run the console application from the development environment by clicking the Start button. You should see five columns of text printed out (one index column and four text columns).

How the Sample Works

UpdatePV is built on top of the C run-time file I/O functions. This represents a data store. Specifically, the sample takes a text file consisting of a pair of data elements and turns it into a rowset. The sample comes with a text file, MyData.txt, that contains pairs of data elements. However, you can run it against any text file (it will just parse everything into two-word tuples).

UpdatePV performs its read operations with RUpdateRowset::Execute (rowset.h). The write operations are handled with RUpdateRowset::FlushData (rowset.h). These are functions called by the OLE DB Provider Templates as part of the normal provider operation. The sample uses the OLE DB Provider Templates IRowsetChangeImpl and IRowsetUpdateImpl classes. The IRowsetChangeImpl class provides support for immediate inserts/updates/deletes. The IRowsetUpdateImpl class support deferred inserts/updates/deletes. The IRowsetUpdateImpl class inherits from IRowsetChangeImpl. For more information on getting/setting data, read Creating an Updatable Provider in the Visual C++ documentation, and Updating Data in Rowsets in the OLE DB Programmer's Reference in the Windows SDK documentation.

UpdatePV also provides support for schema rowsets. These schema rowsets allow consumers to find out information about a provider without opening a rowset or executing a command. The Visual C++ wizards use schema rowsets to generate client side accessors. The primary functions are CUpdateSessionTRSchemaRowset::Execute, CUpdateSessionColSchemaRowset::Execute, and CUpdateSessionPTSchemaRowset::Execute. All three functions return information on what tables the provider supports, columns on the tables, and the data types on the tables. For further information on schema rowsets, see the IDBSchemaRowset interface in the OLE DB Programmer's Reference.

Keywords

The sample demonstrates the following interfaces:

IRowsetChange, IRowsetUpdateImpl

The sample demonstrates the following properties:

DBPROP_IRowsetChange, DBPROP_IRowsetUpdate

See Also

Other Resources

ATL Samples