IDBDataSourceAdmin::CreateDataSource

Creates a new data source and data source object, and initializes the data source object to the data source.

HRESULT CreateDataSource(
   ULONG         cPropertySets,
   DBPROPSET   rgPropertySets[],
   IUnknown*      pUnkOuter,
   REFIID            riid,
   IUnknown**      ppSession);

Parameters

cPropertySets

[in]
The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method does not do anything.

rgPropertySets

[in/out]
An array of DBPROPSET structures containing properties and values to be set. The properties specified in these structures must belong to the Data Source Creation or Initialization property groups; Initialization properties must be supported by the provider for use in data source creation. If ppSession is not a null pointer, the properties can also belong to the Session property group. If the same property is specified more than once in rgPropertySets, then which value is used is provider-specific. If a provider cannot support a property, then the property is ignored. If cPropertySets is zero, this argument is ignored.

For information about the properties in the Data Source Creation, Initialization, and Session property groups that are defined by OLE DB, see "Data Source Creation Properties," "Initialization Properties," and "Session Properties" in Appendix C. For information about the DBPROPSET and DBPROP structures, see "DBPROPSET Structure" and "DBPROP Structure" in Chapter 11.

pUnkOuter

[in]
A pointer to the controlling IUnknown interface if a session is desired and is to be created as part of an aggregate. Otherwise, it is a null pointer.

riid

[in]
The requested interface for the session returned in *ppSession. Ignored if ppSession is a null pointer.

ppSession

[in/out]
A pointer to memory in which to return the pointer to the session. If ppSession is a null pointer, no session is created.

Return Code

S_OK
The method succeeded. In all DBPROP structures passed to the method, dwStatus is set to DBPROPSTATUS_OK.

DB_S_ERRORSOCCURRED
The new data source was created but one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_OPTIONAL—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. The method can fail to set properties for a number of reasons, including:

The property was not in the Data Source Creation, Initialization, or Session property group.
The property was in the Initialization property group but was not supported for use in data source creation.
The property set was not supported by the provider.
It was not possible to set the property.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
cPropertySets was not zero and rgPropertySets was a null pointer.

In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer.

E_NOINTERFACE
The session did not support the interface specified in riid.

E_OUTOFMEMORY
The provider was unable to allocate sufficient memory to create the new data source.

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

DB_E_DUPLICATEDATASOURCE
A data source with the same name already exists.

DB_E_ERRORSOCCURRED
The data source was not created because one or more properties—for which the dwOptions element of the DBPROP structure was DBPROPOPTIONS_REQUIRED or an invalid value—were not set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. None of the satisfiable properties are remembered. The method can fail to set properties for a number of reasons, including:

The property was not in the Data Source Creation, Initialization, or Session property group.
The property was in the Initialization property group but was not supported for use in data source creation.
The property set was not supported by the provider.

DB_E_NOAGGREGATION
pUnkOuter was not a null pointer and the data source being created does not support aggregation.

pUnkOuter was non-null and riid was not IID_Unknown.

DB_SEC_E_AUTH_FAILED
The provider required initialization but an authentication failed. The data source was not created and the data source object remains in an uninitialized state.

DB_SEC_E_PERMISSIONDENIED
The consumer did not have permission to create a new data source.

Comments

CreateDataSource creates a data source and a data source object and initializes the data source object in one atomic operation.

The properties DBPROP_INIT_DATASOURCE and DBPROP_INIT_LOCATION are always required by CreateDataSource. If DBPROP_INIT_LOCATION is set to VT_EMPTY, the data source is created in the default location.