IDBInitialize::Initialize

Initializes a data source object or enumerator.

HRESULT Initialize();

Parameters

None.

Return Code

S_OK
The method succeeded.

DB_S_ASYNCHRONOUS
The method has initiated asynchronous initialization of the data source. The consumer can call IDBAsynchStatus::GetStatus to poll for status or can register for notifications of asynchronous processing. Until asynchronous processing completes, the data source remains in an uninitialized state.

DB_S_ERRORSOCCURRED
The data source object or enumerator was initialized but one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL—were not set. In order to return properties in error, the provider uses DBPROPSET_PROPERTIESINERROR as described in Chapter 11, "Properties." The method can fail to set properties for a number of reasons, including:

It was not possible to set the property.
The value in vValue in the DBPROP structure was invalid.
The property's value conflicted with an existing property.

E_FAIL
A provider-specific error occurred.

E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in order to initialize the data source object or enumerator.

E_UNEXPECTED
The data source is in the process of being initialized asynchronously. To cancel asynchronous execution, call IDBAsynchStatus::Abort.

DB_E_ALREADYINITIALIZED
Initialize had already been called for the data source object or enumerator and an intervening call to Uninitialize had not been made.

DB_E_CANCELED
The provider prompted for additional information and the user selected Cancel.

DB_E_ERRORSOCCURRED
The data source object or enumerator was not initialized because one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were in error. The method can fail to set properties for any of the reasons specified in DB_S_ERRORSOCCURRED, except the reason that states that it was not possible to set the property.

DB_SEC_E_AUTH_FAILED
Authentication of the consumer to the data source or enumerator failed. The data source object or enumerator remains in the uninitialized state.

Comments

Initialize initializes the data source object or enumerator. It uses the values of properties in the Initialization property group that have been set with IDBProperties::SetProperties. If the consumer has not set values for all required properties, Initialize can prompt for values.

If Initialize returns DB_S_ERRORSOCCURRED or DB_E_ERRORSOCCURRED, the consumer can immediately call IDBProperties::GetProperties with the DBPPROPSET_PROPERTIESINERROR property set to return the properties that could not be set. For more information, see "Property Sets" in Chapter 11.

For information about what the consumer can and cannot do with a data source object or enumerator before it is initialized, see "Data Source Object States" and "Enumerator States" in Chapter 2.

Initializing a Data Source Object Through a Network Connection

The following shows how to instantiate a data source object as an in-process object using CoCreateInstance.

#include <oledb.h>
extern CLSID CLSID_DSO;
int main() {
 HRESULT    hr;
 IDBInitialize *pIDBInitialize;

 // Create the data source object.
 hr = CoCreateInstance(CLSID_DSO, NULL, CLSCTX_INPROC_SERVER,
         IID_IDBInitialize, (void**) &pIDBInitialize);

 // Set the initialization properties.
 DBPROP rgProps[8];
 for (ULONG i = 0; i <= 7; i++) {
  VariantInit(&rgProps[i].vValue);
  rgProps[i].dwOptions = DBPROPOPTIONS_REQUIRED;
 };

 rgProps[0].dwPropertyID = DBPROP_INIT_LOCATION; 
 V_VT(&(rgProps[0].vValue)) = VT_BSTR;
 V_BSTR(&(rgProps[0].vValue)) = SysAllocStringLen(OLESTR("server"),
                 wcslen(OLESTR("server")));

 rgProps[1].dwPropertyID = DBPROP_INIT_DATASOURCE;
 V_VT(&(rgProps[1].vValue)) = VT_BSTR;
 V_BSTR(&(rgProps[1].vValue)) = SysAllocStringLen(OLESTR("database"),
                 wcslen(OLESTR("database")));

 rgProps[2].dwPropertyID = DBPROP_AUTH_PASSWORD;
 V_VT(&(rgProps[2].vValue)) = VT_BSTR;
 V_BSTR(rgProps[2].vValue) = SysAllocStringLen(OLESTR("password"),
                 wcslen(OLESTR("password")));

 rgProps[3].dwPropertyID = DBPROP_AUTH_USERID;
 V_VT(&(rgProps[3].vValue)) = VT_BSTR;
 V_BSTR(&(rgProps[3].vValue)) = SysAllocStringLen(OLESTR("username"),
                 wcslen(OLESTR("username")));

 rgProps[4].dwPropertyID = DBPROP_AUTH_ENCRYPT_PASSWORD;
 V_VT(&(rgProps[4].vValue)) = VT_BOOL;
 V_BOOL(&(rgProps[4].vValue)) = VARIANT_TRUE;

 rgProps[5].dwPropertyID = DBPROP_AUTH_CACHE_AUTHINFO;
 V_VT(&(rgProps[5].vValue)) = VT_BOOL;
 V_BOOL(&(rgProps[5].vValue)) = VARIANT_TRUE;

 rgProps[6].dwPropertyID = DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO;
 V_VT(&(rgProps[6].vValue)) = VT_BOOL;
 V_BOOL(&(rgProps[6].vValue)) = VARIANT_TRUE;

 rgProps[7].dwPropertyID = DBPROP_AUTH_PERSIST_ENCRYPTED;
 V_VT(&(rgProps[7].vValue)) = VT_BOOL;
 V_BOOL(&(rgProps[7].vValue)) = VARIANT_TRUE;

 // Create the structure containing the properties.
 DBPROPSET PropSet;
 PropSet.rgProperties  = rgProps;
 PropSet.cProperties   = 8;
 PropSet.guidPropertySet = DBPROPSET_DBINIT;

 // Get an IDBProperties pointer and set the initialization properties.
 IDBProperties *pIDBProperties;
 pIDBInitialize->QueryInterface(IID_IDBProperties, &pIDBProperties);
 pIDBProperties->SetProperties(1, &PropSet);
 pIDBProperties->Release();

 // Initialize the data source object.
 hr = pIDBInitialize->Initialize();
 return hr;
};