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