OLE DB Programmer's Reference |
Initializes a data source object or enumerator.
HRESULT Initialize();
Parameters
None.
Return Code
DB_S_ASYNCHRONOUS should be returned before DB_S_ERRORSOCCURRED.
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.
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.