Data Source Object States

When a data source object is created, it is in an uninitialized state. For example, if the data source is a file, the data source object has not yet opened the file; if the data source is an SQL database, the data source object has not yet connected to the database.

In the uninitialized state, the consumer can do only the following with the data source:

If the consumer calls any other OLE DB method, the provider returns E_UNEXPECTED.  The provider may also return E_UNEXPECTED or E_NOINTERFACE if the consumer calls QueryInterface for an interface other than those listed.

To initialize the data source, the consumer first calls IDBProperties::SetProperties to set the value of properties in the Initialization property group. For example, if the data source is a text file, the consumer might specify the name and location of the file. If the data source is a database in an SQL database management system, the consumer might specify the name of the server on which the database resides along with the user ID and password to use.

Certain properties in the Initialization property group are required by the data source object for initialization. To determine which properties these are, the consumer calls IDBProperties::GetPropertyInfo for properties in the Initialization property group. For required properties, the DBPROPFLAGS_REQUIRED bit is set in the dwFlags element of the returned DBPROPINFO structure.

After the consumer has finished setting properties, it calls IDBInitialize::Initialize. Initialize can prompt for additional information, especially if the consumer has not set values for all required properties. The consumer can control how much Initialize prompts, including suppressing prompting altogether. After Initialize returns successfully, the data source object is in an initialized state. The consumer can also initialize a data source by calling IDBDataSourceAdmin::CreateDataSource to create and initialize a new data source.

If the consumer needs to reinitialize the data source object after it is initialized, it must first uninitialize the data source. For example, if the data source is a file and the consumer needs to use a different file, the consumer must close the first file before opening the second. If the data source is an SQL database and the consumer needs to use a different database, the consumer must disconnect from the first database before connecting to the second. To uninitialize the data source object, the consumer calls IDBInitialize::Uninitialize.

The following figure shows the data source object states and the methods that change them.

Data source object states