Initialization Properties and .dsn Files

Initialization Properties

When the consumer calls IDBInitialize::Initialize, the ODBC Provider calls the ODBC function SQLSetConnectAtt to set various connection options and calls the ODBC function SQLDriverConnect to connect to an ODBC data source. The values passed to SQLSetConnectAtt and SQLDriverConnect come from the initialization properties set by the consumer.

When the data source object is first created, the value of each initialization property is set to VT_EMPTY. If the consumer then calls IPersistFile::Load to load a .dsn file, the ODBC Provider reads the values of the properties stored in the .dsn file and sets initialization properties accordingly. When the consumer calls Initialize, it can pass values for initialization properties; these overwrite the values read from the .dsn file. When the consumer calls IDBInitialize::Uninitialize, the value of each initialization property is set back to VT_EMPTY.

.dsn Files

The consumer stores the initialization properties used to connect to a particular ODBC data source in a .dsn file. The consumer can then reload the values from a .dsn file at a later time and reconnect to the same data source. The format of a .dsn file is the same as that of an .ini file; the ODBC Provider reads and writes information from it with SQLWriteFileDSN and SQLReadFileDSN.

To save properties in a .dsn file, the consumer calls IPersistFile::Save on the data source object. To load properties from a .dsn file, the consumer calls IPersistFile::Load on an uninitialized data source object.

You can also use a .dsn file to create a moniker to obtain a data source object. The consumer calls CreateFileMoniker with the path to the .dsn file. This creates a moniker that can then be bound with BindMoniker, thus creating an uninitialized data source object.

Initialization Properties Used

The following table lists each initialization property the ODBC Provider uses, the corresponding keyword used in the .dsn file, and how it is used. Any properties not listed are not used by the ODBC Provider.

Note

The data source information property, DBPROP_SERVER_NAME, is now supported by the OLE DB Provider for ODBC. This property returns, upon initialization, the name of the server to which you are connected. In many cases, this will be the same as the DBPROP_INIT_DATASOURCE property. For example, when connecting to an ODBC data source, you might specify a DSN (friendly name) and the server name would return the name of the actual server to which you were connected.

Property	.dsn file keyword	Description
DBPROP_AUTH_PASSWORD	AUTH_PASSWORD	Passed as the value of the PWD keyword in SQLDriverConnect.
DBPROP_AUTH_USERID	AUTH_USERID	Passed as the value of the UID keyword in SQLDriverConnect.
DBPROP_INIT_DATASOURCE	INIT_DATASOURCE	Passed as the value of the DSN keyword in SQLDriverConnect.
DBPROP_INIT_HWND	INIT_HWND	Passed as the value of the hwnd argument in SQLDriverConnect.
DBPROP_INIT_LOCATION	INIT_LOCATION	Passed as the value of the Server keyword in SQLDriverConnect (Microsoft SQL Server driver only). Do not use the property DBPROP_INIT_LOCATION with a Microsoft Access data source. When attempting to initialize the ODBC Provider, if you set the initialization property DBPROP_INIT_LOCATION to a valid value and specify that the DATASOURCE is a Microsoft Access data source, errors will occur.
DBPROP_INIT_MODE	INIT_MODE	Passed to SQLSetConnectAtt as the value of the SQL_ACCESS_MODE connection option. Only DB_MODE_READ and DB_MODE_READWRITE are supported. Setting DBPROP_INIT_MODE to read-only is advised but not mandatory for ODBC and this provider.
DBPROP_INIT_PROMPT	INIT_PROMPT	Passed as the value of the fDriverCompletion parameter in SQLDriverConnect.
DBPROP_INIT_PROVIDERSTRING	INIT_PROVIDERSTRING	Passed as the complete ODBC connection string (identical to the szConnStr argument in SQLDriverConnect).
DBPROP_INIT_TIMEOUT	INIT_TIMEOUT	Passed to SQLSetConnectAtt as the value of the SQL_ATTR_LOGIN_TIMEOUT connection option.

This topic is a part of:

• OLE DB Provider for ODBC