When a connection occurs for an ODBC driver built using the SDK the following process occurs to validate the connection settings and establish a connection.

The connection process will use the following functions in your IConnection object:

– void UpdateConnectionSettings(const DSIConnSettingRequestMap& in_connectionSettings, DSIConnSettingResponseMap& out_connectionSettings)
– bool PromptDialog(DSIConnSettingResponseMap& in_connResponseMap, DSIConnSettingRequestMap& io_connectionSettings, HWND in_parentWindow, PromptType in_promptType)
– void Connect(const DSIConnSettingRequestMap& in_connectionSettings)

See the header comments for each function for more detail on each of the parameters.

When a connection occurs, a connection string is passed to the ODBC driver. As an example, take the connection string “DSN=Quickstart;UID=user;”. This connection string is broken down into key-value pairs and stored in a DSIConnSettingRequestMap, in this case that map would contain two entries: {DSN, Quickstart} and {UID, user}. If a DSN is specified, then the DSN value is removed from the map and any entries that are stored in the preconfigured DSN are inserted into the map. Once the map has been created with all the key-value pairs from the connection string and DSN, this map is passed down to the DSII.

The map is first passed to UpdateConnectionSettings(), which is responsible for verifying that all of the required, and any optional, connection settings are present. Any settings that are not present should be added to the DSIConnSettingResponseMap parameter. Since this is a common task there are utility functions that can be used to facilitate this: VerifyRequiredSetting() and VerifyOptionalSetting(). See any of the sample drivers for examples on how to use these functions. You can also manually add entries to the DSIConnSettingResponseMap if you don’t want to use the utility functions.

Depending on how the connection was initiated by the application, the SDK may call PromptDialog() to allow the user to specify more information. In general, if there are any required settings present in the DSIConnSettingResponseMap, then PromptDialog() will be called. Note that, if the application requests, PromptDialog() may not be called in this case or may be called even if there are no settings in the DSIConnSettingResponseMap. PropmtDialog should display a dialog and get the user to enter any missing settings. Note that PromptDialog() will not be called when built as a server, as the clients are responsible for gathering any necessary connection information. After PromptDialog() returns, UpdateConnectionSettings() will be called again to verify the new connection settings.

If there are required settings in the DSIConnSettingResponseMap and the SDK has been informed not to call PromptDialog() by the application, then the connection will fail and Connect() will not be called. If there are no required settings in the DSIConnSettingResponseMap after UpdateConnectionSettings() has been called, Connect() will be called. Note that optional settings can be present in the DSIConnSettingResponseMap as they are not required for a connection to be made. During Connect(), you should have all the needed settings to make a connection as verified by UpdateConnectionSettings(). You can use the utility functions GetRequiredSetting() and GetOptionalSetting() to request the required and optional settings for your connection, and attempt to make an actual connection. If a required setting is not present at this stage, it is a logic error and the connection should fail. If verification of any of the settings fails, such as an incorrect user name or password, then an exception should be thrown with the DIAG_INVALID_AUTH_SPEC DiagState. Alternatively, you can use the utility function DSIExceptionUtilities::DSIThrowRequiredSettingNotFoundException() to throw the required exception.