OLE DB Data Source Objects (SQL Server Compact)

In OLE DB programming, the data source object represents a provider's underlying data store. To connect to an OLE DB provider, a consumer must first create and initialize an instance of the data source object.

The SQL Server Compact Data Source Object

In Microsoft SQL Server Compact 3.5 (SQL Server Compact 3.5), the data source object is created by calling the OLE CoCreateInstance function and then passing the CLSID (class identifier) for the OLE DB Provider for SQL Server Compact 3.5, which is CLSID_SQLSERVERCE. Because SQL Server Compact 3.5 is an in-process server, instances of SQL Server Compact 3.5 OLE DB objects are created using the CLSCTX_INPROC_SERVER macro to indicate the executable context.

SQL Server Compact 3.5 uses only the DBPROP_INIT_DATASOURCE property to specify the desired data source. This property is passed the full path of the database file to be opened. After setting this property, the consumer initializes the data source object. This establishes the environment that is required to exchange data between the consumer and SQL Server Compact 3.5. After the data source object is initialized, the consumer can obtain self-descriptive information about the data store but cannot yet access data. This data source object can then be used to create one or more session objects. These in turn are used to create the necessary transactions, commands, and rowsets.

The OLE DB provider for SQL Server Compact 3.5 also lets you create a new database. For more information, see Creating Databases with OLE DB.

Password-protected databases are also supported. With this security feature, a password must be passed when the data source object is initialized. For more information, see Accessing Password-protected Databases with OLE DB.

Limitations of the Data Source Object

Some limitations of the data source object in the OLE DB provider for SQL Server Compact 3.5 include the following:

• The concept of a catalog as defined in OLE DB is not used in SQL Server Compact 3.5. The DBPROP_INIT_DATASOURCE property defines the database to use, and the OLE DB provider for SQL Server Compact 3.5 treats this database as the current catalog.
• The ability to change the current data store is not supported. Clients that want to change the data store must uninitialize the data source object, set the new data store name, and then reinitialize the data source object.

Provider-specific Data Source Properties

SQL Server Compact 3.5 supports the following provider-specific properties in the provider-specific property set DBPROPSET_SSCE_DBINIT:

Property	Definition
DBPROP_SSCE_AUTO_SHRINK_THRESHOLD	The percent of free space in the database file that is permitted before autoshrink begins. A value of 100 disables autoshrink. If not specified, the default value is 60.
DBPROP_SSCE_DBCASESENSITIVE	A Boolean value that determines whether or not the database collation is case sensitive. Must be set to true to enable case-sensitive collation or false for case-insensitive collation. If not specified, the default value is false. Note: This property is introduced starting with the SQL Server Compact 3.5 SP1 release. For more information, see Working with Collations (SQL Server Compact).
DBPROP_SSCE_DBPASSWORD	The database password, which can be up to 40 characters in length. If not specified, the default value is no password. This property is required if you enable encryption on the database. If you specify a password, encryption is enabled on the database. For more information, see Accessing Password-protected Databases with OLE DB.
DBPROP_SSCE_DEFAULT_LOCK_ESCALATION	The number of locks a transaction will acquire before you try escalation from row to table, or from page to table. If not specified, the default value is 100.
DBPROP_SSCE_DEFAULT_LOCK_TIMEOUT	The default number of milliseconds that a transaction will wait for a lock. If not specified, the default value is 5000 milliseconds for desktops and 2000 milliseconds for devices.
DBPROP_SSCE_ENCRYPTDATABASE	A Boolean value that determines whether the database is encrypted. Must be set to true to enable encryption or false for no encryption. If not specified, the default value is false. If you enable encryption, you must also specify a password with the password property. If you specify a password, encryption is enabled regardless of how you set this property.
DBPROP_SSCE_ENCRYPTIONMODE	The type of encryption used to secure the database file. For more information on encryption mode, see the description in Provider-Specific Properties (OLE DB).
DBPROP_SSCE_FLUSH_INTERVAL	Specifies the interval time, in seconds, before all committed transactions are flushed to disk. If not specified, the default value is 10.
DBPROP_SSCE_MAXBUFFERSIZE	The maximum size of the database, in MB. If not specified, the default value is 640.
DBPROP_SSCE_MAX_DATABASE_SIZE	The maximum size of the database, in MB. If not specified, the default value is 128.
DBPROP_SSCE_TEMPFILE_DIRECTORY	The location of the temporary database. If not specified, the default is to use the database specified in the data source property for temporary storage. For more information, see Specifying the Location of the Temporary Database Using OLE DB and Temporary Databases.
DBPROP_SSCE_TEMPFILE_MAX_SIZE	The maximum size of the temporary database, in MB.