MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 2: Data Source and Session Objects

Creating Data Source Objects

The OLE DB connection model defines how OLE DB consumers locate and activate OLE DB data providers. Two objects are the basis for the OLE DB connection model: the data source object and the session object. To access an OLE DB provider, a consumer must first create an instance of the provider's data source object. Each provider is identified by a unique class identifier (CLSID) in the registry.

Prior to OLE DB 2.0, consumers created a provider's data source object through the root enumerator or by passing the provider's CLSID to CoCreateInstance, as in the following code example:

// Create an instance of CLSID_MSDASQL.
CoCreateInstance(CLSID_MSDASQL, NULL, CLSCTX_INPROC_SERVER, 
                 IID_IDBInitialize,(void**)&pIDBInitialize);

This model requires applications to hard-code provider CLSIDs or to obtain the CLSID at run time through application-specific mechanisms. OLE DB 2.0 provides common services that consumers can leverage by calling IDataInitialize or IDBPromptInitialize methods. The IDataInitialize interface is exposed by the Service Component Manager, which can be instantiated by using CLSID_MSDAINITIALIZE. The IDBPromptInitialize interface is exposed by the Data Links component, which can be instantiated by using CLSID_DataLinks. For more information about these interfaces, see "IDataInitialize" and "IDBPromptInitialize" in the OLE DB Core Components documentation, which is included in the Microsoft® Data Access Components (MDAC) SDK.

For example, to create an instance of a provider that can take advantage of OLE DB 2.0 services, based on the provider's CLSID, the preceding code would look like the following:

// Create an instance of the OLE DB Initialization Component.
CoCreateInstance(CLSID_MSDAINITIALIZE, NULL, CLSCTX_INPROC_SERVER, 
   IID_IDataInitialize,(void**)&pIDataInitialize);

// Create an instance of CLSID_MSDASQL with supported Services.
pIDataInitialize->CreateDBInstance(CLSID_MSDASQL, NULL, 
   CLSCTX_INPROC_SERVER, NULL, IID_IDBInitialize, 
   (IUnknown**)&pIDBInitialize);

Alternatively, the consumer could use the Data Links component of OLE DB to prompt the user to indicate the provider to use, as well as other properties to be used to initialize the data source object:

// Create an intstance of the Data Links component.
CoCreateInstance(CLSID_DataLinks, NULL, CLSCTX_INPROC_SERVER, 
   IID_IDBPromptInitialize, (void **)&pIDBPromptInitialize);

// Initialize output pointer.
*pIDBInitialize = NULL;

// Prompt the user for the provider and initialization properties.
pIDBPromptInitialize->PromptDataSource(NULL, hWndParent,
   DBPROMPTOPTIONS_PROPERTYSHEET, 0, NULL, NULL, IID_IDBInitialize, 
   (IUnknown **)&pIDBInitialize);

//Initialize the data source object.
pIDBInitialize->Initialize();

The data source object exposes IDBProperties, which the consumer uses to provide basic authentication information such as user ID and password (for cases when the data source object does not exist in an authenticated environment) as well as the name of the data store (file or database) containing the data to be accessed. It also exposes IDBInitialize, which the consumer uses to connect to the provider by initializing the data source object.

After a data source object has been successfully initialized, the consumer can call IDBProperties::GetPropertyInfo on the data source object to get information about the capabilities of the provider. These capabilities include the interfaces, rowset properties such as approximate positioning, transaction properties such as supported isolation levels, and the SQL dialects (if any) a provider supports. The consumer can then call IDBCreateSession::CreateSession to create a session object.

The session acts as a rowset, command, and transaction object factory. Not all OLE DB providers support command objects. However, all data providers, whether or not they support commands, must expose the IOpenRowset interface, which enables providers to expose their data directly as rowsets without the use of commands.