IDBInitialize::Initialize

OLE DB Programmer's Reference

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 object. 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 object remains in an uninitialized state.

DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.

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. To return properties in error, the provider uses DBPROPSET_PROPERTIESINERROR as described in Chapter 14: Properties. The method can fail to set properties for a number of reasons, including the following:

• 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.
• DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED. Once rowset population is complete, the consumer can see DB_S_ERRORSOCCURRED either by calling IDBAsynchStatus::GetStatus or by receiving IDBAsynchNotify::OnStop.

E_FAIL

A provider-specific error occurred.

E_OUTOFMEMORY

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

E_UNEXPECTED

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

DB_E_ALREADYINITIALIZED

IDBInitialize::Initialize had already been called for the data source object or enumerator, and an intervening call to IDBInitialize::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 initialized, but one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL—were not set. To return properties in error, the provider uses DBPROPSET_PROPERTIESINERROR as described in Chapter 14: Properties. The method can fail to set properties for a number of reasons, including the following:

• 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.

DB_SEC_E_AUTH_FAILED

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

Comments

IDBInitialize::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, IDBInitialize::Initialize can prompt for values.

If IDBInitialize::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 Appendix C: OLE DB Properties.

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: Data Source and Session Objects.

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,                                   (void**)&pIDBProperties);    pIDBProperties->SetProperties(1, &PropSet);    pIDBProperties->Release();    // Initialize the data source object.    hr = pIDBInitialize->Initialize();    pIDBInitialize->Release();    return hr; };

See Also

IDBInitialize::Uninitialize | IDBProperties::SetProperties

1998-2001 Microsoft Corporation. All rights reserved.