Initialization Properties and .dsn Files

Initialization Properties

When the consumer calls IDBInitialize::Initialize, the ODBC Provider calls the ODBC functions SQLSetConnectAtt, to set various connection options, and 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 IPeristFile::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 which 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.

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).
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.
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.