When a connection occurs for an ADO.NET provider or .NET based 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:

– Dictionary<string, ConnectionSetting> UpdateConnectionSettings(Dictionary<string, object> requestSettings)
– void Connect(Dictionary<string, object> requestSettings)
– bool PromptDialog(Dictionary<string, ConnectionSetting> connResponseMap, Dictionary<string, object> connectionSettings, System.Windows.Forms.IWin32Window parentWindow, PromptType promptType);

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

When a connection occurs, a connection string is passed to the ADO.NET provider. As an example, take the connection string “User=user;Password=pass”. This connection string is broken down into key-value pairs and stored in a Dictionary<string, object> (hereafter referred to as requestSettings), in this case that map would contain two entries: {“User”, “user”} and {“Password”, “pass”}. This map is then passed down to the DSII.

The requestSettings 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 output Dictionary<string, ConnectionSetting> (hereafter referred to as the responseSettings). 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 responseSettings if you don’t want to use the utility functions.

When using an ADO.NET provider, if all of the required settings are not present during a connection it will fail. There is no mechanism to prompt for more information in ADO.NET. If there are no required settings in the responseSettings after UpdateConnectionSettings() has been called, Connect() will be called. Note that optional settings can be present in the responseSettings 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 ErrorCode.

When using an ODBC driver, 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 responseSettings, 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 responseSettings. PromptDialog 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 responseSettings 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 responseSettings after UpdateConnectionSettings() has been called, Connect() will be called. Note that optional settings can be present in the reponseSettings 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 ErrorCode.