Menu
Simba Technologies
Simba Technologies

SimbaEngine X SDK 10.1.3
Developing Drivers for SQL-Capable Data Stores

Handling Connections

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.

Obtaining Settings and Connecting to the Data Store

In your 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 out_connectionSettings parameter.

You can use the utility functions VerifyOptionalSetting and VerifyRequiredSetting to help you check if a setting exists. If a setting does not exist, these functions put the appropriate value in the out_connectionSettings map.

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.

AutoPtr<ConnectionSetting> reqSetting(new

ConnectionSetting(SETTING_REQUIRED));

reqSetting->SetLabel(L"SomeSetting");

reqSetting->RegisterWarningListener(GetWarningListener());

std::vector<Simba::Support::Variant> values;

values.push_back(Variant(L"YES"));

values.push_back(Variant(L"NO"));

values.push_back(Variant(L"UNKNOWN"));

reqSetting->SetValues(values);

out_connectionSettings[L"SomeSetting"] = reqSetting.Detach();

}

If 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 CustomerDSIIConnection::Connect function.

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 GetOptionalSetting and GetRequiredSetting to help you extract the settings from the in_connectionSettings parameter.

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.

First, 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 PromptDialog and UpdateConnectionSettings cycle until the user cancels the dialog.

Understanding the Connection Process

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:

 

Related Links

Creating and Using Dialogs