DSIStatement Class Reference

This class is to expose an interface to interact with the customer DSII for statement details. More...

Inherits Simba::DSI::IStatement.

List of all members.

Public Member Functions

virtual void ClearCancel ()
 Clear any previous cancel notification requested by the application.
virtual void ClonePropertyMap (DSIStmtPropertyKeyValueMap &io_propertyMap)
 Retrieves a clone of the property map for the statement.
virtual Simba::DSI::IDataEngineCreateDataEngine ()=0
 Constructs a new data engine instance.
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 ILoggerGetLog ()
 Gets the ILogger for the connection.
virtual SharedPtr< IMessageSourceGetMessageSource ()
 Retrieves the message source.
virtual AttributeDataGetNewSimilarValue (Simba::DSI::DSIStmtPropertyKey in_attribute, AttributeData *in_value)
 Tries to get a similar value to replace a non supported attribute value.
Simba::DSI::IConnectionGetParentConnection ()
 Returns the parent IConnection instance.
virtual const AttributeDataGetProperty (Simba::DSI::DSIStmtPropertyKey in_key)
 Returns a statement property corresponding to the in_key.
virtual IWarningListenerGetWarningListener ()
 Retrieves the warning listener associated with the DSIStatement.
virtual bool IsCustomProperty (simba_int32 in_key)
 Should return true if the given ODBC attribute key is associated with a custom statement property recognized by the DSII.
virtual bool IsValueSupported (Simba::DSI::DSIStmtPropertyKey in_attribute, AttributeData *in_value)
 Checks to see if the given attribute value is supported and within limits.
virtual void NotifyCursorNameChange (const simba_wstring &in_cursorName)
 Notifies that the cursor name associated with this statement has been changed.
virtual void OnCancel ()
 Notify that a cancel of the current operation was requested by the application.
void RegisterWarningListener (IWarningListener *in_warningListener)
 Registers an IWarningListener*, which may be retrieved using GetWarningListener().
virtual void SetCustomProperty (simba_int32 in_key, AttributeData *in_value)
 Sets the custom statement property with the given ODBC attribute key to the given value.
virtual void SetProperty (Simba::DSI::DSIStmtPropertyKey in_key, AttributeData *in_value)
 Sets the statement property with the given key to the given value.
virtual ~DSIStatement ()
 Destructor.

Protected Member Functions

 DSIStatement (IConnection *in_connection, bool in_initializeDefaults=true)
 Constructor.

Protected Attributes

DSIStmtPropertyKeyValueMap m_statementProperties

Detailed Description

This class is to expose an interface to interact with the customer DSII for statement details.


Constructor & Destructor Documentation

virtual ~DSIStatement (  )  [virtual]

Destructor.

DSIStatement ( IConnection in_connection,
bool  in_initializeDefaults = true 
) [protected]

Constructor.

If statement properties are defined in DSIConnProperties, then those values will be brought over as default property values for properties used by the engine. Therefore, DSIStatement MUST be created before DSIStmtProperties. Default values and limits for DSI statement properties are defined here, but clients can override the default values and limits by deriving DSIStatement and setting new default values and limits in the child class constructor.

Parameters:
in_connection IConnection that is associated with this DSIStatement. (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 statement property.

Member Function Documentation

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 IStatement.

virtual void ClonePropertyMap ( DSIStmtPropertyKeyValueMap io_propertyMap  )  [virtual]

Retrieves a clone of the property map for the statement.

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

Implements IStatement.

virtual Simba::DSI::IDataEngine* CreateDataEngine (  )  [pure virtual]

Constructs a new data engine instance.

Returns:
A new IDataEngine instance. (OWN)

Implements IStatement.

virtual AttributeData* GetCustomProperty ( simba_int32  in_key  )  [virtual]

Retrieves a custom property value.

Parameters:
in_key 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.

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

Implements IStatement.

virtual AttributeType GetCustomPropertyType ( simba_int32  in_key  )  [virtual]

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

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.

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:
Type associated with the custom property.
Exceptions:
DSIException because custom properties are not supported by default.

Implements IStatement.

virtual ILogger* GetLog (  )  [virtual]

Gets the ILogger for the connection.

Returns:
The log that logs messages about the DSIStatement. (NOT OWN)

Implements IStatement.

virtual SharedPtr<IMessageSource> GetMessageSource (  )  [virtual]

Retrieves the message source.

Returns:
The message source associated with the DSIStatement. (NOT OWN)

Implements IStatement.

virtual AttributeData* GetNewSimilarValue ( Simba::DSI::DSIStmtPropertyKey  in_attribute,
AttributeData in_value 
) [virtual]

Tries to get a similar value to replace a non supported attribute value.

Returns a new AttributeData if a similar value is found as a substitute, returns NULL if a similar value cannot be obtained. A similar value may be returned according to the following rules: 1) If the max and min limits are the same (if any), then DSI only supports one value and no similar value will be given. 2) If the max and min limits are not the same (if any), then this method will give back the closest max/min limit value will be given as the similar value.

Parameters:
in_attribute DSI Statement property key.
in_value Non-supported attribute value. (NOT OWN)
Returns:
Similar attribute value to replace in_value. (OWN)

Implements IStatement.

Simba::DSI::IConnection* GetParentConnection (  )  [virtual]

Returns the parent IConnection instance.

Returns:
The parent IConnection instance. (NOT OWN)

Implements IStatement.

virtual const AttributeData* GetProperty ( Simba::DSI::DSIStmtPropertyKey  in_key  )  [virtual]

Returns a statement 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 Statement property key supported by DSI.
Returns:
The statement property corresponding to the in_key. (NOT OWN)

Implements IStatement.

virtual IWarningListener* GetWarningListener (  )  [virtual]

Retrieves the warning listener associated with the DSIStatement.

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

Implements IStatement.

virtual bool IsCustomProperty ( simba_int32  in_key  )  [virtual]

Should return true if the given ODBC attribute key is associated with a custom statement property recognized by the DSII.

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

Parameters:
in_key Statement property key supported by DSI.
Returns:
True if the in_key is associated with a custom statement property recognized by the DSII; false otherwise.

Implements IStatement.

virtual bool IsValueSupported ( Simba::DSI::DSIStmtPropertyKey  in_attribute,
AttributeData in_value 
) [virtual]

Checks to see if the given attribute value is supported and within limits.

Parameters:
in_attribute DSI statement property key
in_value Statement property value. (NOT OWN)
Returns:
True if the given attribute value is supported and within limits; false otherwise.

Implements IStatement.

virtual void NotifyCursorNameChange ( const simba_wstring in_cursorName  )  [virtual]

Notifies that the cursor name associated with this statement has been changed.

Will be called right after construction of the DSIStatement or when the name changes. The default implementation does nothing.

Parameters:
in_cursorName Cursor name generated by the driver or calling SQLSetCursorName.

Implements IStatement.

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 or SQLCancel ODBC function is called on a statement handle corresponding to this statement 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 IStatement.

void RegisterWarningListener ( IWarningListener in_warningListener  )  [virtual]

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

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

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

Implements IStatement.

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

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

If the value is modified before saving it, an OPT_VAL_CHANGED warning should be posted. This method should post an OPT_VAL_CHANGED warning if a value is substituted with another value before storage. 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. For values that cannot take effect immediately but will take effect at a later time, this method should also post an OPT_VAL_CHANGED warning.

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.
in_value Custom statement property value to be set for in_key. (OWN)
Exceptions:
DSIException because custom properties are not supported by default.

Implements IStatement.

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

Sets the statement 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_CHANGED 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. For values that cannot take effect immediately but will take effect at a later time, this method should also post an OPT_VAL_CHANGED warning.

Parameters:
in_key Statement property key supported by DSI.
in_value Statement property value to be set for in_key. (OWN)

Implements IStatement.


Member Data Documentation


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