DSIConnection Class Reference

This class exposes an interface to interact with the customer DSII for connection details. More...

Inherits Simba::DSI::IConnection.

List of all members.

Public Member Functions

virtual void BeginTransaction ()
 Begins a transaction.
virtual void ClearCancel ()
 Clear any previous cancel notification requested by the application.
virtual void ClonePropertyMap (DSIConnPropertyKeyValueMap &io_propertyMap)
 Retrieves a clone of the property map for the connection.
virtual void Commit ()
 This method commits all transactions within this connection.
virtual void Connect (const DSIConnSettingRequestMap &in_connectionSettings)=0
 Attempts to connect to the data source, using connection settings generated by a call to UpdateConnectionSettings().
virtual Simba::DSI::IStatementCreateStatement ()=0
 Creates and returns a new IStatement instance.
virtual void Disconnect ()=0
 Disconnect the connection.
virtual const
ConnectionSettingInfoMap
GetConnectionSettingInfo ()
 Gets information about connection settings that are accepted by the UpdateConnectionSettings and Connect functions.
virtual AttributeDataGetCustomProperty (simba_int32 in_key)
 Retrieves a custom property value.
virtual AttributeType GetCustomPropertyType (simba_int32 in_key)
 Retrieves the type associated with the custom property with the given ODBC attribute key.
virtual const simba_wstringGetDataSourceName ()
 Retrieves the name of the data source.
virtual const simba_string & GetLocale ()
 Retrieves the connection-wide locale.
virtual ILoggerGetLog ()
 Gets the ILogger for the connection.
virtual SharedPtr< IMessageSourceGetMessageSource ()
 Retrieves the message source.
const
Simba::DSI::IMetadataFilterFactory
GetMetadataFilterFactory ()
 Gets the IMetaDataFilterFactory to create filters.
Simba::DSI::IEnvironmentGetParentEnvironment ()
 Gets the parent environment for this connection.
virtual const AttributeDataGetProperty (Simba::DSI::DSIConnPropertyKey in_key)
 Returns a connection property corresponding to the in_key.
const VariantGetRequiredSetting (const simba_wstring &in_settingName, const Simba::DSI::DSIConnSettingRequestMap &in_connectionSettings)
 Get the required setting, and throw an exception if it isn't present.
virtual SqlCDataPoolGetSqlCDataPool ()
 Gets the SqlCDataTypeUtilities for this connection.
virtual SqlCDataTypeUtilitiesGetSqlCDataTypeUtilities ()
 Creates a SqlCDataTypeUtilities.
virtual SqlConverterFactoryGetSqlConverterFactory ()
 Creates a SqlConverterFactory.
virtual SqlCTypeMetadataFactoryGetSqlCTypeMetadataFactory ()
 Creates a SqlCTypeMetadataFactory.
virtual SqlDataFactoryGetSqlDataFactory ()
 Creates a SqlDataFactory.
virtual SqlDataTypeUtilitiesGetSqlDataTypeUtilities ()
 Creates a SqlDataTypeUtilities.
virtual const
ISqlToCBulkConverterFactory
GetSqlToCBulkConverterFactory ()
 Returns a reference to this connection's SQL -> C bulk converter factory.
virtual SqlTypeMetadataFactoryGetSqlTypeMetadataFactory ()
 Creates a SqlTypeMetadataFactory.
virtual TypeConversionInfoGetTypeConversionInfo ()
 Gets the TypeConversionInfo for this connection.
virtual bool IsCustomProperty (simba_int32 in_key)
 Determine if the property associated with the key is custom.
virtual bool IsSensitiveAttribute (const simba_wstring &in_attribute)
 Determine if a connection attribute is sensitive to Log.
virtual void OnCancel ()
 Notify that a cancel of the current operation was requested by the application.
virtual bool PromptDialog (DSIConnSettingResponseMap &io_connResponseMap, DSIConnSettingRequestMap &io_connectionSettings, HWND in_parentWindow, PromptType in_promptType)=0
 Displays a dialog box that prompts the user for settings for this connection.
virtual void RegisterTransactionStateListener (Simba::DSI::ITransactionStateListener *in_transactionStateListener)
 Registers an ITransactionStateListener* with this connection.
virtual void RegisterWarningListener (IWarningListener *in_warningListener)
 Registers an IWarningListener*, which may be retrieved using GetWarningListener().
virtual void Reset ()
 Reset this connection to a clean state (w.r.t. connection properties).
virtual void Rollback ()
 Through this call, the DSII rolls back the transaction within this connection.
virtual void SetAppDialogInfo (bool in_isAllowed, SQLHWND in_windowHandle=0)
 Indicate if the driver may display a dialog during connection based on what is defined by the application.
virtual void SetCustomProperty (simba_int32 in_key, AttributeData *in_value)
 Sets the custom connection property with the given ODBC attribute key to the given value.
virtual void SetProperty (Simba::DSI::DSIConnPropertyKey in_key, AttributeData *in_value)
 Sets the connection property with the given key to the given value.
virtual void ToNativeSQL (const simba_wstring &in_string, simba_wstring &out_string)
 Takes in an ODBC-formatted SQL query and returns it customized and optimized for the data source.
virtual void UpdateConnectionSettings (const DSIConnSettingRequestMap &in_connectionSettings, DSIConnSettingResponseMap &out_connectionSettings)=0
 Updates the connection settings by checking if required settings are present.
virtual ~DSIConnection ()
 Destructor.

Static Public Member Functions

static bool GetOptionalSetting (const simba_wstring &in_settingName, const Simba::DSI::DSIConnSettingRequestMap &in_connectionSettings, const Variant **out_data)
 Get the optional setting.
static const VariantGetOptionalSettingOrDefault (const simba_wstring &in_settingName, const Simba::DSI::DSIConnSettingRequestMap &in_connectionSettings, const Variant &in_default)
 Get the optional setting, or the specified default if the setting is not present.
static void VerifyOptionalSetting (const simba_wstring &in_settingName, const Simba::DSI::DSIConnSettingRequestMap &in_connectionSettings, const std::vector< Variant > &in_possibleValues, Simba::DSI::DSIConnSettingResponseMap &out_connectionSettings, bool in_allowEmpty=true)
 Verify that an optional setting is present. Adds information to the response map if the setting is not present.
static void VerifyOptionalSetting (const simba_wstring &in_settingName, const Simba::DSI::DSIConnSettingRequestMap &in_connectionSettings, Simba::DSI::DSIConnSettingResponseMap &out_connectionSettings, bool in_allowEmpty=true)
 Verify that an optional setting is present. Adds information to the response map if the setting is not present.
static void VerifyRequiredSetting (const simba_wstring &in_settingName, const Simba::DSI::DSIConnSettingRequestMap &in_connectionSettings, const std::vector< Variant > &in_possibleValues, Simba::DSI::DSIConnSettingResponseMap &out_connectionSettings, bool in_allowEmpty=true)
 Verify that a required setting is present. Adds information to the response map if the setting is not present.
static void VerifyRequiredSetting (const simba_wstring &in_settingName, const Simba::DSI::DSIConnSettingRequestMap &in_connectionSettings, Simba::DSI::DSIConnSettingResponseMap &out_connectionSettings, bool in_allowEmpty=true)
 Verify that a required setting is present. Adds information to the response map if the setting is not present.

Protected Member Functions

void ClearPropertyValues ()
 Clears out engine property values from m_connectionProperties.
virtual AutoPtr
< Simba::DSI::IMetadataFilterFactory
CreateMetadataFilterFactory ()
 Creates and returns a new IMetaDataFilterFactory instance.
virtual void DoReset ()=0
 Called by Reset() to reset subclass-specific state.
 DSIConnection (Simba::DSI::IEnvironment *in_environment, bool in_initializeDefaults=true)
 Constructor.
virtual SQLHWND GetParentWindowHandle ()
 Get the handle of the parent window.
IWarningListenerGetWarningListener ()
 Retrieves the warning listener associated with the DSIConnection.
bool IsBeingReset () const
 True iff currently in a call to DSIConnection::Reset().
virtual bool IsDialogAllowed ()
 Check if the driver may display a dialog to request information necessary to establish a successful connection.
virtual bool IsValidCatalog (const simba_wstring &in_catalog)
 Determine if the specified catalog is valid or not.

Protected Attributes

DSIConnPropertyKeyValueMap m_connectionProperties
DSIConnSettingRequestMap m_connectionSettingsMap
Simba::DSI::IEnvironmentm_environment
bool m_isDialogAllowed
bool m_isLocaleSet
simba_string m_locale
ConnectionSettingInfoMap m_settingInfo
 Connection setting info returned by GetConnectionSettingInfo;.
AutoPtr
< ISqlToCBulkConverterFactory
m_sqlToCBulkConverterFactory
 This connection's SQL -> C bulk converter factory. Lazily-initialized.
Simba::DSI::ITransactionStateListenerm_transactionStateListener
SQLHWND m_windowHandle
 Handle of the parent window. Can be 0 if no parent window was provided.

Detailed Description

This class exposes an interface to interact with the customer DSII for connection details.


Constructor & Destructor Documentation

virtual ~DSIConnection (  )  [virtual]

Destructor.

DSIConnection ( Simba::DSI::IEnvironment in_environment,
bool  in_initializeDefaults = true 
) [protected]

Constructor.

Sets default property values for properties used by the engine.

Parameters:
in_environment IEnvironment that is associated with this connection. (NOT OWN)
in_initializeDefaults Flag indicating if default property values should be initialized. Only set this to false if you know you are going to initialize every connection property.

Member Function Documentation

virtual void BeginTransaction (  )  [virtual]

Begins a transaction.

NOTE: This is a default implementation, which simply throws an exception if this function is called. Sub-classes should override this function if transactions are to be supported.

Exceptions:
DSIException indicating this function is not supported.

Implements IConnection.

virtual void ClearCancel (  )  [virtual]

Clear any previous cancel notification requested by the application.

The SEN calls this function at the beginning of a cancelable function to allow the DSI to clear any pending cancel notification.

The default implementation does actually nothing. A DSII can override it if it needs to delete a cancel request (e.g. clear a cancel request flag).

NOTE: It is useful in the following context. An application calls SQLCancelHandle to cancel a running ODBC function, but the function is already at the end of its processing. This function will then miss the cancel and therefore won't clear it. The next ODBC function would then see that a cancel was requested and therefore immediately terminate. To avoid this issue, the SEN calls this method at the start of each ODBC function if it finds a pending cancel request to allow the DSII to clear it.

Implements IConnection.

void ClearPropertyValues (  )  [protected]

Clears out engine property values from m_connectionProperties.

virtual void ClonePropertyMap ( DSIConnPropertyKeyValueMap io_propertyMap  )  [virtual]

Retrieves a clone of the property map for the connection.

Parameters:
io_propertyMap Property map to clone all properties into. Any properties already in the map will be deleted. (OWN)

Implements IConnection.

virtual void Commit (  )  [virtual]

This method commits all transactions within this connection.

NOTE: This is a default implementation, which simply throws an exception if this function is called. Sub-classes should override this function if transactions are to be supported.

Exceptions:
DSIException indicating this function is not supported.

Implements IConnection.

virtual void Connect ( const DSIConnSettingRequestMap in_connectionSettings  )  [pure virtual]

Attempts to connect to the data source, using connection settings generated by a call to UpdateConnectionSettings().

A call to Connect() occurs when the ODBC connection is formed, not when the connection handle is allocated. If a Disconnect() call occurs, Connect() may be called again if a new connection is made against the same handle.

Parameters:
in_connectionSettings Connection settings generated by a call to UpdateConnectionSettings()
Exceptions:
ErrorException if there is a problem making a connection.
ErrorException with key DIAG_INVALID_AUTH_SPEC if there is a problem with authorization.

Implements IConnection.

virtual AutoPtr<Simba::DSI::IMetadataFilterFactory> CreateMetadataFilterFactory (  )  [protected, virtual]

Creates and returns a new IMetaDataFilterFactory instance.

This default implementation constructs a DSIDefaultMetaDataFilterFactory. The DSII can create their own custom filter by subclassing this method.

Returns:
New IMetaDataFilterFactory instance. (OWN)
virtual Simba::DSI::IStatement* CreateStatement (  )  [pure virtual]

Creates and returns a new IStatement instance.

Returns:
New IStatement instance. (OWN)

Implements IConnection.

virtual void Disconnect (  )  [pure virtual]

Disconnect the connection.

This call is a request to the DSII layer to free up all memory that it has allocated for the database, and to close any tables that are currently open for the database.

Implements IConnection.

virtual void DoReset (  )  [protected, pure virtual]

Called by Reset() to reset subclass-specific state.

Note: m_connectionProperties will have already been reset to DSIConnection's defaults.

virtual const ConnectionSettingInfoMap& GetConnectionSettingInfo (  )  [inline, virtual]

Gets information about connection settings that are accepted by the UpdateConnectionSettings and Connect functions.

This is currently only used by OLEDB providers.

How the map keys are interpreted is dependent on if this is an ODBC or OLEDB connection.

In OLEDB Mode, the following values are used to map initialization properties to connection settings:

OLEDB ID | OLEDB Description | Variant Type --------------------------|-----------------------------|------------------------------ DBPROP_AUTH_USERID | User ID | WString DBPROP_AUTH_PASSWORD | Password | WString DBPROP_AUTH_INTEGRATED | Integrated Security | WString DBPROP_INIT_DATASOURCE | Data Source | WString DBPROP_INIT_LOCATION | Location | WString DBPROP_INIT_CATALOG | Initial Catalog | WString DBPRPO_INIT_LCID | Locale Identifier | WString (See Note)

Notes on specific properties: DBPROP_AUTH_INTEGRATED

  • This property is a WString which OLEDB describes as being the name of the security service to use.
  • Many windows applications will pass a value of "SSPI" to this property.
  • A value of "" means to use integrated security with the default service.
  • In many applications, when a user selects this option, the application will disable entry fields for USERID and PASSWORD and will not pass values for them. If you would like to receive those values along with a similar one for integrated security, you must not use this and should define a custom ID.

DBPROP_INIT_CATALOG

  • If you don't describe this property, or describe an empty key, it will still be supported if your DSII supports Catalogs. It will instead be passed to IConnection::SetProperty(DSI_CONN_CURRENT_CATALOG) before connecting.
  • If you describe a non-empty key for this in your info map, DBPROP_INIT_CATALOG will be passed to your UpdateConnectionSettings and Connect functions.

DBPROP_INIT_LCID

  • This property always maps to key "LOCALE"
  • It defaults to optional but may be reported as required.
  • The type WString is what will be passed to the connection settings map, however, OLEDB defines this as an int32 locale identifier. We look up this identifier value and pass its string representation.

Other properties (initialization or otherwise) are not mapped.

Custom properties may be present but must not conflict with existing property IDs and only be used within the range 0x80000000 to 0xFFFFFFFF.

In ODBC Mode, the map keys currently have no defined relationship with the setting info.

The DSII must remain prepared to deal with entries in the DSIConnSettingRequestMap passed to UpdateConnectionSettings or Connect that were not described by this function.

Returns:
Reference to map to filled in with settings accepted.

Implements IConnection.

virtual AttributeData* GetCustomProperty ( simba_int32  in_key  )  [virtual]

Retrieves a custom property value.

This default implementation simply throws a 'CustomPropNotFound' error if this function is called. Sub-classes should override this function if custom properties are needed.

Parameters:
in_key ODBC attribute key.
Returns:
Custom property value. (NOT OWN)
Exceptions:
DSIException because custom properties are not supported by default.

Implements IConnection.

virtual AttributeType GetCustomPropertyType ( simba_int32  in_key  )  [virtual]

Retrieves the type associated with the custom property with the given ODBC attribute key.

This default implementation simply throws a 'CustomPropNotFound' error if this function is called. Sub-classes should override this function if custom properties are needed.

Must throw an ErrorException if the given key does not correspond to a custom property. A value does not have to be available for this property in order to be able to retrieve the corresponding type.

Parameters:
in_key ODBC attribute key.
Returns:
Type associated with the custom property.
Exceptions:
DSIException because custom properties are not supported by default.

Implements IConnection.

virtual const simba_wstring& GetDataSourceName (  )  [virtual]

Retrieves the name of the data source.

The data source name is set by setting the "DSN" connection key to a valid value.

Returns:
Data source name.

Implements IConnection.

virtual const simba_string& GetLocale (  )  [virtual]

Retrieves the connection-wide locale.

The locale is set by setting the "LOCALE" connection key to a valid value. See LocaleDefns.h for more details.

Returns:
The connection-wide locale.

Implements IConnection.

virtual ILogger* GetLog (  )  [virtual]

Gets the ILogger for the connection.

Returns:
ILogger instance. (NOT OWN)

Implements IConnection.

virtual SharedPtr<IMessageSource> GetMessageSource (  )  [virtual]

Retrieves the message source.

Returns:
Message source. (NOT OWN)

Implements IConnection.

const Simba::DSI::IMetadataFilterFactory& GetMetadataFilterFactory (  )  [virtual]

Gets the IMetaDataFilterFactory to create filters.

The DSII should override the CreateMetaDataFilter method if implementing a custom filter factory. This method would throw an error if CreateMetaDataFilter doesn't return proper filterFactory

Returns:
This connection's metadata filter factory.

Implements IConnection.

static bool GetOptionalSetting ( const simba_wstring in_settingName,
const Simba::DSI::DSIConnSettingRequestMap in_connectionSettings,
const Variant **  out_data 
) [static]

Get the optional setting.

Parameters:
in_settingName The name of the setting to retrieve.
in_connectionSettings Connection settings generated by a call to UpdateConnectionSettings().
out_data The Variant representing the specified setting. (NOT OWN)
Returns:
True if the setting was present; false otherwise.
static const Variant& GetOptionalSettingOrDefault ( const simba_wstring in_settingName,
const Simba::DSI::DSIConnSettingRequestMap in_connectionSettings,
const Variant in_default 
) [static]

Get the optional setting, or the specified default if the setting is not present.

Parameters:
in_settingName The name of the setting to retrieve.
in_connectionSettings Connection settings generated by a call to UpdateConnectionSettings().
in_default The default value to return if in_settingName is not present.
Returns:
The value of the setting if present; in_default if not.
Simba::DSI::IEnvironment* GetParentEnvironment (  )  [virtual]

Gets the parent environment for this connection.

Returns:
The parent environment instance. (NOT OWN)

Implements IConnection.

virtual SQLHWND GetParentWindowHandle (  )  [inline, protected, virtual]

Get the handle of the parent window.

Returns:
The handle of the parent window or 0 if none was available.
virtual const AttributeData* GetProperty ( Simba::DSI::DSIConnPropertyKey  in_key  )  [virtual]

Returns a connection property corresponding to the in_key.

Please refer to the DSI Design and Implementation Guide for detailed information on the supported properties.

The default implementation returns a value from m_propertiesFromEngine.

Parameters:
in_key Connection property key supported by DSI.
Returns:
The connection property corresponding to the in_key. (NOT OWN)

Implements IConnection.

const Variant& GetRequiredSetting ( const simba_wstring in_settingName,
const Simba::DSI::DSIConnSettingRequestMap in_connectionSettings 
)

Get the required setting, and throw an exception if it isn't present.

Parameters:
in_settingName The name of the setting to retrieve.
in_connectionSettings Connection settings generated by a call to UpdateConnectionSettings().
Exceptions:
ErrorException if the required setting is not present.
Returns:
The Variant representing the specified setting.
virtual SqlCDataPool& GetSqlCDataPool (  )  [virtual]

Gets the SqlCDataTypeUtilities for this connection.

Override this function if you have implemented your own subclass of SqlCDataTypeUtilities. Return your subclass of SqlCDataTypeUtilities.

Returns:
A SqlCDataTypeUtilities.

Implements IConnection.

virtual SqlCDataTypeUtilities& GetSqlCDataTypeUtilities (  )  [virtual]

Creates a SqlCDataTypeUtilities.

Override this function if you have implemented your own subclass of SqlCDataTypeUtilities. Return your subclass of SqlCDataTypeUtilities.

Returns:
A SqlCDataTypeUtilities.

Implements IConnection.

virtual SqlConverterFactory& GetSqlConverterFactory (  )  [virtual]

Creates a SqlConverterFactory.

Override this function if you have implemented your own subclass of SqlConverterFactory. Return your subclass of SqlConverterFactory.

Returns:
A SqlConverterFactory.

Implements IConnection.

virtual SqlCTypeMetadataFactory& GetSqlCTypeMetadataFactory (  )  [virtual]

Creates a SqlCTypeMetadataFactory.

Override this function if you have implemented your own subclass of SqlCTypeMetadataFactory. Return your subclass of SqlCTypeMetadataFactory.

Returns:
A SqlCTypeMetadataFactory.

Implements IConnection.

virtual SqlDataFactory& GetSqlDataFactory (  )  [virtual]

Creates a SqlDataFactory.

Override this function if you have implemented your own subclass of SqlDataFactory. Return your subclass of SqlDataFactory.

Returns:
A SqlDataFactory.

Implements IConnection.

virtual SqlDataTypeUtilities& GetSqlDataTypeUtilities (  )  [virtual]

Creates a SqlDataTypeUtilities.

Override this function if you have implemented your own subclass of SqlDataTypeUtilities. Return your subclass of SqlDataTypeUtilities.

Returns:
A SqlDataTypeUtilities.

Implements IConnection.

virtual const ISqlToCBulkConverterFactory& GetSqlToCBulkConverterFactory (  )  [virtual]

Returns a reference to this connection's SQL -> C bulk converter factory.

Returns:
A reference to this connection's SQL -> C bulk converter factory.
Exceptions:
If Bulk-Fetch is not supported on this connection.

Implements IConnection.

virtual SqlTypeMetadataFactory& GetSqlTypeMetadataFactory (  )  [virtual]

Creates a SqlTypeMetadataFactory.

Override this function if you have implemented your own subclass of SqlTypeMetadataFactory. Return your subclass of SqlTypeMetadataFactory.

Returns:
A SqlTypeMetadataFactory.

Implements IConnection.

virtual TypeConversionInfo& GetTypeConversionInfo (  )  [virtual]

Gets the TypeConversionInfo for this connection.

Override this function if you have implemented your own subclass of SqlCTypeMetadataFactory. Return your subclass of SqlCTypeMetadataFactory.

Returns:
A TypeConversionInfo

Implements IConnection.

IWarningListener* GetWarningListener (  )  [protected, virtual]

Retrieves the warning listener associated with the DSIConnection.

Returns:
The warning listener associated with the DSIConnection. (NOT OWN)

Implements IWarningSource.

bool IsBeingReset (  )  const [inline, protected]

True iff currently in a call to DSIConnection::Reset().

virtual bool IsCustomProperty ( simba_int32  in_key  )  [virtual]

Determine if the property associated with the key is custom.

This default implementation always returns false because custom connection properties are not supported by default. Sub-classes should override this function if custom properties are needed.

Parameters:
in_key Connection property key to test.
Returns:
True if in_key is associated with a custom connection property recognized by the DSII; false otherwise.

Implements IConnection.

virtual bool IsDialogAllowed (  )  [inline, protected, virtual]

Check if the driver may display a dialog to request information necessary to establish a successful connection.

See SetAppDialogInfo() function.

Returns:
true if opening a dialog is allowed, else false.
virtual bool IsSensitiveAttribute ( const simba_wstring in_attribute  )  [virtual]

Determine if a connection attribute is sensitive to Log.

NOTE: The default implementation treats UID and PWD as sensitive attributes,

Parameters:
in_attribute Connection attribute to Log.
Returns:
True if in_attribute should not be logged in plain text recognized by the DSII; default value is false

Implements IConnection.

virtual bool IsValidCatalog ( const simba_wstring in_catalog  )  [protected, virtual]

Determine if the specified catalog is valid or not.

This function should be overridden to correctly verify the specified catalog. It will be called from SetProperty() when in_key is DSI_CONN_CURRENT_CATALOG to verify if the catalog is valid.

This default implementation always returns true.

Returns:
True if the catalog is valid; false otherwise.
virtual void OnCancel (  )  [virtual]

Notify that a cancel of the current operation was requested by the application.

The SEN calls this function when the SQLCancelHandle ODBC function is called on a connection handle corresponding to this connection object. The objective for the DSII is then to set flags or any other mean to notify the operation that it was canceled.

This implementation does actually nothing. A DSII can override it if it is able to handle a cancel.

Implements IConnection.

virtual bool PromptDialog ( DSIConnSettingResponseMap io_connResponseMap,
DSIConnSettingRequestMap io_connectionSettings,
HWND  in_parentWindow,
PromptType  in_promptType 
) [pure virtual]

Displays a dialog box that prompts the user for settings for this connection.

The connection settings from io_connectionSettings are presented as key-value string pairs. The input connection settings map is the initial state of the dialog box. The input connection settings map will be modified to reflect the user's input to the dialog box. All the key-value pairs returned in io_connectionSettings will be put into the output connection string (when the called connection function was either SQLDriverConnect or SQLBrowseConnect)

io_connResponseMap contains values that are still needed and were not supplied by the user. This map is returned from DSII layer of the driver when UpdateConnectionSettings function of an IConnection object is called. The driver may use this map, for example, to indicate that some setting is missing or optional.

The return value for this method indicates if the user completed the process by clicking OK on the dialog box (return true), or if the user aborts the process by clicking CANCEL on the dialog box (return false).

The function will be called multiple times if the user clicked OK button but the setting user input are incomplete. Before each time the function is called, UpdateConnectionSettings function mentioned above will be called to check whether there are still required settings not being set, and the response map will be updated accordingly to reflect such information.

Parameters:
io_connResponseMap The connection settings map updated with settings that are still needed and were not supplied.
io_connectionSettings The connection settings map updated to reflect the user's input.
in_parentWindow Handle to the parent window to which this dialog belongs
in_promptType Indicates what type of connection settings to request - either both required and optional settings or just required settings.
Returns:
True if the user clicks OK on the dialog box; false if the user clicks CANCEL.

Implements IConnection.

virtual void RegisterTransactionStateListener ( Simba::DSI::ITransactionStateListener in_transactionStateListener  )  [virtual]

Registers an ITransactionStateListener* with this connection.

Will be called right after construction of the IConnection. Default implementation stores the pointer in m_transactionStateListener.

Parameters:
in_transactionStateListener A listener which may be used to transaction state changes. (NOT OWN)

Implements IConnection.

virtual void RegisterWarningListener ( IWarningListener in_warningListener  )  [virtual]

Registers an IWarningListener*, which may be retrieved using GetWarningListener().

Should be called right after construction of the DSIConnection. If this is overridden by a derived class, that implementation MUST call up to the base DSIConnection::RegisterWarningListener.

Parameters:
in_warningListener A listener which may be used to post warnings. (NOT OWN)

Implements IConnection.

virtual void Reset (  )  [virtual]

Reset this connection to a clean state (w.r.t. connection properties).

Reset this connection's connection properties to their default state. If the connection was currently connected, it stays that way.

Implements IConnection.

virtual void Rollback (  )  [virtual]

Through this call, the DSII rolls back the transaction within this connection.

NOTE: This is a default implementation, which simply throws an exception if this function is called. Sub-classes should override this function if transactions are to be supported.

Exceptions:
DSIException indicating this function is not supported.

Implements IConnection.

virtual void SetAppDialogInfo ( bool  in_isAllowed,
SQLHWND  in_windowHandle = 0 
) [inline, virtual]

Indicate if the driver may display a dialog during connection based on what is defined by the application.

A dialog can for example be useful if a driver would like to request a refresh of the password in case the one provided in the connection string has expired.

Allowing the opening of a dialog depends on the application API (e.g. in ODBC a dialog can be opened only if the DriverCompletion parameter of SQLDriverConnect() is different from SQL_DRIVER_NOPROMPT).

Parameters:
in_isAllowed true if opening a dialog is allowed, else false.
in_windowHandle The handle of the parent window in which to open a dialog or 0 if the parent window is unknown.

Implements IConnection.

virtual void SetCustomProperty ( simba_int32  in_key,
AttributeData in_value 
) [virtual]

Sets the custom connection property with the given ODBC attribute key to the given value.

This default implementation simply throws a 'CustomPropNotFound' error if this function is called. Sub-classes should override this function if custom properties are needed.

If the value is modified before saving it, an OPT_VAL_CHANGED warning should be posted. This method should post an OPT_VAL_CHANGE warning if a value is substituted with another value before storage (like substituting a timeout value for the maximum if it's too high). For properties which accept more than just a discrete set of values, this method should throw an INVALID_ATTR_VAL error if an illegal value is given which can't be substituted with another value.

Parameters:
in_key ODBC attribute key.
in_value The value to be set. (OWN)
Exceptions:
DSIException because custom properties are not supported by default.

Implements IConnection.

virtual void SetProperty ( Simba::DSI::DSIConnPropertyKey  in_key,
AttributeData in_value 
) [virtual]

Sets the connection property with the given key to the given value.

If the value is modified before saving it, an OPT_VAL_CHANGED warning should be posted. Please refer to the DSI Design and Implementation Guide for detailed information on the supported properties.

The default implementation saves property values in the map m_propertiesFromEngine.

This method should post an OPT_VAL_CHANGE warning if a value is substituted with another value before storage (like substituting a timeout value for the maximum if it's too high). For properties which accept more than just a discrete set of values, this method should throw an INVALID_ATTR_VAL error if an illegal value is given which can't be substituted with another value.

Parameters:
in_key Connection property key supported by DSI.
in_value Connection property value to be set for in_key. (OWN)
Exceptions:
InvalidCatalogException if in_key is DSI_CONN_CURRENT_CATALOG and in_value is an invalid catalog.

Implements IConnection.

virtual void ToNativeSQL ( const simba_wstring in_string,
simba_wstring out_string 
) [virtual]

Takes in an ODBC-formatted SQL query and returns it customized and optimized for the data source.

This default implementation simply copies in_string to out_string, without modifying it. Sub-classes should override this function if the input SQL string needs to be translated into a database-specific string.

Parameters:
in_string ODBC-formatted SQL query.
out_string Gets filled in with return value.

Implements IConnection.

virtual void UpdateConnectionSettings ( const DSIConnSettingRequestMap in_connectionSettings,
DSIConnSettingResponseMap out_connectionSettings 
) [pure virtual]

Updates the connection settings by checking if required settings are present.

When connecting to a data source, SimbaODBC calls this function to check and update settings for the connection. The in_connectionSettings parameter includes the settings specified in the connection string presented as key-value string pairs. This method should return any modified and additional requested connection settings in out_connectionSettings.

If any connection settings have been modified, then an OPT_VAL_CHANGED warning must be posted. If a key in the map is unrecognized or does not belong in this stage of connection, then an INVALID_CONN_STR_ATTR warning must be posted in this method.

Parameters:
in_connectionSettings The Connection Settings map containing the connection settings that were passed into the connection string.
out_connectionSettings Gets filled in with connection settings that are still needed and were not supplied in the connection string.

Implements IConnection.

static void VerifyOptionalSetting ( const simba_wstring in_settingName,
const Simba::DSI::DSIConnSettingRequestMap in_connectionSettings,
const std::vector< Variant > &  in_possibleValues,
Simba::DSI::DSIConnSettingResponseMap out_connectionSettings,
bool  in_allowEmpty = true 
) [static]

Verify that an optional setting is present. Adds information to the response map if the setting is not present.

NOTE: in_settingName is case-insensitive.

Parameters:
in_settingName The setting to verify that is present.
in_connectionSettings Connection settings provided in a call to UpdateConnectionSettings().
in_possibleValues A list of the possible values that the optional setting can hold.
out_connectionSettings Gets filled in with connection settings that are still needed and were not supplied in the connection string.
in_allowEmpty Whether to consider an empty value as a missing value. True if empty values should not be considered missing, false if they should.
static void VerifyOptionalSetting ( const simba_wstring in_settingName,
const Simba::DSI::DSIConnSettingRequestMap in_connectionSettings,
Simba::DSI::DSIConnSettingResponseMap out_connectionSettings,
bool  in_allowEmpty = true 
) [static]

Verify that an optional setting is present. Adds information to the response map if the setting is not present.

NOTE: in_settingName is case-insensitive.

Parameters:
in_settingName The setting to verify that is present.
in_connectionSettings Connection settings provided in a call to UpdateConnectionSettings().
out_connectionSettings Gets filled in with connection settings that are still needed and were not supplied in the connection string.
in_allowEmpty Whether to consider an empty value as a missing value. True if empty values should not be considered missing, false if they should.
static void VerifyRequiredSetting ( const simba_wstring in_settingName,
const Simba::DSI::DSIConnSettingRequestMap in_connectionSettings,
const std::vector< Variant > &  in_possibleValues,
Simba::DSI::DSIConnSettingResponseMap out_connectionSettings,
bool  in_allowEmpty = true 
) [static]

Verify that a required setting is present. Adds information to the response map if the setting is not present.

NOTE: in_settingName is case-insensitive.

Parameters:
in_settingName The setting to verify that is present.
in_connectionSettings Connection settings provided in a call to UpdateConnectionSettings().
in_possibleValues A list of the possible values that the required setting can hold.
out_connectionSettings Gets filled in with connection settings that are still needed and were not supplied in the connection string.
in_allowEmpty Whether to consider an empty value as a missing value. True if empty values should not be considered missing, false if they should.
static void VerifyRequiredSetting ( const simba_wstring in_settingName,
const Simba::DSI::DSIConnSettingRequestMap in_connectionSettings,
Simba::DSI::DSIConnSettingResponseMap out_connectionSettings,
bool  in_allowEmpty = true 
) [static]

Verify that a required setting is present. Adds information to the response map if the setting is not present.

NOTE: in_settingName is case-insensitive.

Parameters:
in_settingName The setting to verify that is present.
in_connectionSettings Connection settings provided in a call to UpdateConnectionSettings().
out_connectionSettings Gets filled in with connection settings that are still needed and were not supplied in the connection string.
in_allowEmpty Whether to consider an empty value as a missing value. True if empty values should not be considered missing, false if they should.

Member Data Documentation

bool m_isDialogAllowed [protected]

Flag indicating if the connection may open a dialog to prompt for further information during connect. By default, set to false as opening a dialog is not allowed for most connection functions. Set consistently based on application request by the Application communication layer (e.g. ODBC) before the Connect() call is made.

bool m_isLocaleSet [protected]
simba_string m_locale [protected]

Connection setting info returned by GetConnectionSettingInfo;.

This connection's SQL -> C bulk converter factory. Lazily-initialized.

SQLHWND m_windowHandle [protected]

Handle of the parent window. Can be 0 if no parent window was provided.


The documentation for this class was generated from the following file:

Generated on Wed May 17 14:21:15 2017 for SimbaEngine 10.1.3.1011 by simba