IDBDataSourceAdmin::CreateDataSource

Creates and initializes a new data store.

Syntax

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 store creation. If the same property is specified more than once in rgPropertySets, the value used is provider-specific. If a provider cannot support a property, the property is ignored. If cPropertySets is zero, this argument is ignored.

  The properties specified in these structures must belong to the Data Source Creation, Initialization property or Session Property group. If one of these groups is specified and ppSession is not specified, the session properties are ignored

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

• 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 store 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 following:

  • The property was not in the Data Source Creation or Initialization property group.

  • The property was in the Initialization property group but was not supported for use in data store 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 store.

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

• DB_E_CANCELED
  The provider prompted the user for additional information, and the user selected Cancel. A data store was not created and the data source was not initialized.

• DB_E_DUPLICATEDATASOURCE
  A data store with the same name already exists.

• DB_E_ERRORSOCCURRED
  The data store 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 following:

  • The property was not in the Data Source Creation or Initialization property group.

  • The property was in the Initialization property group but was not supported for use in data store creation.

  • The property set was not supported by the provider.

• DB_E_NOAGGREGATION
  pUnkOuter was not a null pointer, and the provider is an OLE DB 1.0 or 1.1 provider that does not support aggregation of the data source object being created.

  pUnkOuter was not a null pointer, and riid was not IID_IUnknown.

• DB_SEC_E_AUTH_FAILED
  The provider required initialization, but an authentication failed. The data store was not created.

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

Comments

IDBDataSourceAdmin::CreateDataSource creates a data store and initializes a data source object in one atomic operation.

The consumer must set any Data Source Creation or Initialization properties required by the provider to create the data store and initialize the data source object. If DBPROP_INIT_LOCATION is set to VT_EMPTY, the data source object is created in the default location.

When cPropertySets is 0:

• S_OK is returned.

• CreateDataSource does not perform any functionality.

• *ppSession is not set.

See Also

Reference

IDBDataSourceAdmin::DestroyDataSource

IDBDataSourceAdmin::ModifyDataSource