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: