The ODBC application, the Simba ODBC layer, and your custom DSII layer interact to establish a connection to your data store. An important part of this process is obtaining all the required connection settings. The SimbaEngine X SDK provides functions to help you manage the set of required and optional connection settings, and to repeat the request for settings until all required settings are obtained.
For a description of the connection process, see Understanding the Connection Process below.
CustomerDSIIConnection::UpdateConnectionSetting method, the
in_connectionSettings parameter includes the connection settings that the user specified in the connection string, DSN, and/or prompt dialog. Your implementation of this method should return any modified or additional required (or optional) connection settings in the
You can use the utility functions
VerifyRequiredSetting to help you check if a setting exists. If a setting does not exist, these functions put the appropriate value in the
To specify a list of acceptable values for one of your connection settings in the
out_connectionSettings map, you must enter it yourself. For example:
DSIConnSettingRequestMap::const_iterator itr = in_connectionSettings.find(L"SomeSetting");
if (itr == in_connectionSettings.end())
// Missing the required key, so add it to the requested settings.
out_connectionSettings[L"SomeSetting"] = reqSetting.Detach();
out_connectionSettings contains additional required connection settings, then the Simba ODBC Layer will call
PromptDialog to request these settings. Connection settings can be required or optional. This retrieve-request cycle repeats until all required connection settings have been provided. Once all required settings have been provided (even if some optional settings have not been provided), then the Simba ODBC Layer will call your
Your implementation of the
CustomerDSIIConnection::Connect function should establish a connection to your data store. You should inspect the
in_connectionSettings parameter to retrieve any connection settings that are needed to establish and set up a connection to your data store. You can use the utility functions
GetRequiredSetting to help you extract the settings from the
When your implementation of the
CustomerDSIIConnection::PromptDialog function is called, you have the option of displaying a graphical dialog box to the user for requesting parameters or other connection settings. See Creating and Using Dialogs for more information about creating dialog boxes.
For example, if you require the user to enter a user id and a password, you can request those parameters from the user using this dialog box. If you do not wish to implement a dialog box, you can simply leave the
PromptDialog function empty.
Example: Handling a Missing Password
Assume your DSII requires a user ID and password to establish a connection to your data store. Then, an application attempts a connection using
SQLDriverConnect supplying the user ID setting but missing the password setting.
UpdateConnectionSettings is called so that all the settings that are needed for a connection can be verified. Your
UpdateConnectionSettingsf unction would use
VerifyRequiredSetting for both the user ID and password keys to verify that they are present.
If any key is not present, it will be added to the
out_connectionSettings parameter by
VerifyRequiredSetting. Since the password key is missing,
out_connectionSettings now contains that setting, and
UpdateConnectionSettings will return.
When the Simba ODBC layer detects that a required setting is missing, it calls
PromptDialog. This allows your DSII to prompt a dialog to the user to request any additional or missing information. Once the user has filled out the dialog and returned, the Simba ODBC layer will call
UpdateConnectionSettings again to verify that all the required settings are now present. If all the required settings are present, it will then call
Connect to proceed with the connection. If all the required settings are not present, it continue the
UpdateConnectionSettings cycle until the user cancels the dialog.
This section provides a detailed explanation of how the end user, your ODBC-enabled application, the Simba ODBC Layer and your DSII layer interact to establish a connection to your data store. It then explains how you must handle the connection process in your own custom driver.
When the end-user initiates a connection to your data store, the Simba ODBC Layer will call your
CustomerDSIIConnection::UpdateConnectionSettings function. Note that in some cases the Simba ODBC Layer may call your
CustomerDSIIConnection::PromptDialog function, discussed later in this section, first if the connection parameters indicate it should do so. This process is shown in the diagram below: