DSIExtQueryExecutor Class Reference

Simba SQLEngine's implementation of IQueryExecutor. More...

Inherits Simba::DSI::IQueryExecutor.

List of all members.

Public Member Functions

void CancelExecute ()
 Cancels the current execution.
virtual void ClearCancel ()
 Clears any cancellation flags set if CancelExecute was called.
virtual AutoPtr
< Simba::SQLEngine::ETMaterializer
CreateMaterializer ()
 Create a materializer to translate an AET to an ET.
 DSIExtQueryExecutor (AutoPtr< AEStatements > in_aeStatements, SharedPtr< DSIExtDataEngineContext > in_dataEngineCtx, ILogger *in_log)
 Constructor.
void Execute (IWarningListener *in_warningListener, Simba::DSI::IParameterSetIter *in_inputParamSetIter, Simba::DSI::IParameterSetIter *in_outputParamSetIter, Simba::DSI::IParameterSetStatusSet *in_paramSetStatusSet)
 Executes the query, using the given input and output IParameterSetIter.
void FinalizePushedParamData ()
 Finalize the parameter pushing.
Simba::SQLEngine::DSIExtExecutorContextGetContext ()
 Get a pointer reference to the executor context.
virtual simba_uint16 GetNumParams ()
 Get the total number of parameters in all SQL statements.
Simba::DSI::IResultsGetResults ()
 Get a pointer reference to the results of the execution.
void PopulateParameters (Simba::DSI::IParameterManager *in_paramManager)
 Provide the ODBC layer with metadata about parameters found in a query prepared using Prepare().
void PrepareResults ()
 Prepare the results for the current batch of SQL statements.
void PushParamData (simba_unsigned_native in_paramSet, Simba::DSI::IParameterSource *in_paramSrc)
 Push part of an input parameter value before executing in an IParameterSource*.
virtual ~DSIExtQueryExecutor ()
 Destructor.

Protected Member Functions

simba_wstring GetExecutionTreeLog ()
 Get a string which represents the execution tree of the executed statement.

Protected Attributes

AutoPtr< AEStatementsm_aeStatements
CriticalSection m_criticalSection
ILoggerm_log

Detailed Description

Simba SQLEngine's implementation of IQueryExecutor.

Note: If you subclass DSIExtQueryExecutor, or override DSIExtSqlDataEngine::CreateQueryExecutor(), and your DSII uses the ETree (Uses the SQLEngine for query execution), then you must call PrepareResults() immediately after the DSIExtQueryExecutor constructor, either in the subclass's constructor, or your override of DSIExtSqlDataEngine::CreateQueryExecutor().


Constructor & Destructor Documentation

DSIExtQueryExecutor ( AutoPtr< AEStatements in_aeStatements,
SharedPtr< DSIExtDataEngineContext in_dataEngineCtx,
ILogger in_log 
)

Constructor.

Parameters:
in_aeStatements The current batch of SQL statements in the form of AE Tree. Cannot be NULL.
in_dataEngineCtx The context for this batch of queries. Cannot be NULL.
in_log Reference to a log object. (NOT OWN)
virtual ~DSIExtQueryExecutor (  )  [virtual]

Destructor.


Member Function Documentation

void CancelExecute (  )  [virtual]

Cancels the current execution.

Implements IQueryExecutor.

virtual void ClearCancel (  )  [virtual]

Clears any cancellation flags set if CancelExecute was called.

Implements IQueryExecutor.

virtual AutoPtr<Simba::SQLEngine::ETMaterializer> CreateMaterializer (  )  [virtual]

Create a materializer to translate an AET to an ET.

This implementation creates an ETSimbaMaterializer object. A customer can override this method to create a specialized materializer.

Returns:
A materializer to "materialize" an AET to an ET.
void Execute ( IWarningListener in_warningListener,
Simba::DSI::IParameterSetIter in_inputParamSetIter,
Simba::DSI::IParameterSetIter in_outputParamSetIter,
Simba::DSI::IParameterSetStatusSet in_paramSetStatusSet 
) [virtual]

Executes the query, using the given input and output IParameterSetIter.

Definitions: IParameterSetIter - A forward-only iterator through an input or output parameter set. IParameterSet - A parameter set. This can be obtained via the IParameterSetIter. IParameterSource - A single parameter in a parameter set. This can be obtained via the IParameterSet.

Rules for using IParameterSetIter: 1) IParameterSetIter is positioned just before the first parameter set upon construction. 2) Before operating on the IParameterSetIter, the data source may check the IParameterSetIter to see if it is empty (no parameter sets available). 3) Next(), which positions the iterator at the first parameter set (if calling Next() for the first time) or at the next parameter set, must be called before using the IParameterSet* obtained through IParameterSetIter. Otherwise, the IParameterSet* is in an undefined state. 4) The IParameterSet* obtained from the IParameterSetIter will not change thoughout the lifetime of the IParameterSetIter. This means that it is sufficient to get the IParameterSet* only once, and asking the IParameterSetIter for the IParameterSet* at any time will give you the same IParameterSet*. There will always be an IParameterSet* associated with an IParameterSetIter. Please see IParameterSet for more details. 5) Next() will position the iterator to the next parameter set. This affects the IParameterSet* obtained through the IParameterSetIter. The contents and attributes on the IParameterSet* will change upon a call to Next() on the IParameterSetIter. However, the IParameterSet* itself will not change. 6) For input IParameterSetIter, Next() must be called to position the iterator at the parameter set of interest, before trying to obtain the data buffer to process the inputs. 7) For output IParameterSetIter, Next() must be called after setting the output value on the IParameterSource*. Next() will commit the output value set on the IParameterSource* and transfer the output value to the application. If Next() is not called on an output IParameterSetIter, the output value set on the IParameterSource* will not be committed nor transferred to the application. 8) The parameter set index maybe obtained from the IParameterSetIter.

Rules for using IParameterSet: 1) The state of the IParameterSet and its contents are dependent on the position of the parent IParameterSetIter. Please see IParameterSetIter for details. 2) A list of IParameterSource* can be obtained from the IParameterSet. The list of IParameterSource* may be empty. This may happen when: a) no input parameters in the SQL statement for input IParameterSet, or b) no output parameters in the SQL statement for output IParameterSet. 3) The data source may set the status of the current parameter set execution, whether the execute was successful, if there were warnings (success with info), etc. Setting the status is recommended, and this status information is reflected on the application side. The status codes can be found in IParameterSet.h. 4) The parameter set index maybe obtained from the IParameterSet.

Rules for using IParameterSource: 1) Please see IParameterSource.h for details on what methods are allowed during executing. 2) Data source is only allowed to get the data buffer (thus the input data) for IParameterSource obtained through the input IParameterSetIter and IParameterSet. 3) Data source is only allowed to set output value on IParameterSource obtained through the output IParameterSetIter and IParameterSet. If the data source does not set an output value on the IParameterSource, then IParameterSource defaults the output value to null.

This method should do the following: 1) Get the input IParameterSet* from the input IParameterSetIter*. This can be done at any time. Call Next() on the input IParameterSetIter* to position the iterator at the first parameter set (if calling Next() for the first time), or at the next parameter set. Next() must be called on the input IParameterSetIter* before using the input IParameterSet*. Get input data from the list of IParameterSource* (if not empty) obtained from the input IParameterSet*. Input parameters may represent NULL, or default parameters for stored procedures. Set the status of the current parameter set. 2) Process data from the input iterator. 3) Get the output IParameterSet* from the output IParameterSetIter*. This can be done at any time. Call Next() on the output IParameterSetIter* to position the iterator at the first parameter set (if calling Next() for the first time), or at the next parameter set. Next() must be called on the output IParameterSetIter* before using the output IParameterSet*. Set output value on the list of IParameterSource* (if not empty) obtained from the output IParameterSet*. Either a valid buffer with appropriate length or a null buffer is required. If the contents of the input buffer is longer than the size of the IParameterSource* buffer, the contents will be truncated without throwing any exceptions. Set the status of the current parameter set.

If there are any warnings that need to be posted for the application, those can be posted through the in_warningListener.

Parameters:
in_warningListener Warning listener to post warnings against. (NOT OWN)
in_inputParamSetIter Iterator over input parameter sets. (NOT OWN)
in_outputParamSetIter Iterator over output parameter sets. (NOT OWN)
in_paramSetStatusSet Parameter set status set. (NOT OWN)

Implements IQueryExecutor.

void FinalizePushedParamData (  )  [virtual]

Finalize the parameter pushing.

This informs the query executor that all parameter values have been pushed prior to query execution. After the next Execute() call has finished with this data, it may be cleared from memory even if the Execute() call results in an exception being thrown. The first subsequent call to PushParamData() should behave as if the executor has a clear cache of pushed parameter values.

Implements IQueryExecutor.

Get a pointer reference to the executor context.

Returns:
A pointer reference to the executor context. (NOT OWN)
simba_wstring GetExecutionTreeLog (  )  [protected]

Get a string which represents the execution tree of the executed statement.

Note: This method is for debugging purposes only, and its output/format may change at any time.

Exceptions:
SEInvalidOperationException if Execute() has not yet been called.
Returns:
A string representation of the execution tree from the last call to Execute().
virtual simba_uint16 GetNumParams (  )  [virtual]

Get the total number of parameters in all SQL statements.

Note that the number of parameters should be available even if auto-IPD is disabled.

For example, the following SQL statement string would have 2 parameters,

SELECT * FROM T WHERE C1 > ? AND SELECT * FROM T WHERE C2 > ?

USAGE NOTE: Do not override this method unless you are absolutely sure.

Returns:
The total number of parameters in all SQL statements.

Implements IQueryExecutor.

Simba::DSI::IResults* GetResults (  )  [virtual]

Get a pointer reference to the results of the execution.

This function will be called after query preparation and before execution to retrieve metadata about the results that will be returned for this stored procedure. If accurate metadata cannot be supplied, returning at least a single result of the correct type with no metadata will suffice as long as correct metadata is supplied after Execute(). Be aware that some applications may have problems if metadata is not available at prepare time.

Returns:
The results of the execution. (NOT OWN)

Implements IQueryExecutor.

void PopulateParameters ( Simba::DSI::IParameterManager in_paramManager  )  [virtual]

Provide the ODBC layer with metadata about parameters found in a query prepared using Prepare().

From the perspective of ODBC, this method implements IPD auto-population during a call to SQLPrepare(). This function is called during SQLPrepare() if the statement property DSI_CONN_AUTO_IPD is set to DSI_PROP_AUTO_IPD_ON.

The implementation of this method should register each parameter found in a query by calling in_parameterManager->RegisterParameter(uint16)

After registering a parameter, the implementation of this method should set metadata information about the parameter using the IParameterSource* returned by IParameterManager::RegisterParameter(). IParameterSource*s accessed in this way are deleted when PopulateParameters() is finished, so they should not be cached and accessed outside of this method.

An attempt to cache an IParameterManager* and register parameters outside of a call to SQLPrepare() will throw a CallbackException.

If parameters are to be registered, they must contain all integers from 1 to the highest parameter index. For example, if the highest parameter index is 5, the parameters {1, 2, 3, 4, 5} must be registered. They can be registered in any order and any parameter can be registered multiple times. Parameter index 0 cannot be used. If the query in question has no parameters, then no parameters should be registered.

IParameterSource->SetSQLType() should be called before setting the precision, length, interval length, and scale fields. Setting the SQLType implicitly sets those fields to default values, so they should only be set afterwards.

Parameters:
in_paramManager Manager to register parameters with. (NOT OWN)
Exceptions:
CallbackException if an IParameterManager* is cached and the DSII attempts to register parameters outside of a call to SQLPrepare().

Implements IQueryExecutor.

void PrepareResults (  ) 

Prepare the results for the current batch of SQL statements.

This may create ETResult objects and can be omitted for DSIExtQueryExecutors that do not need to use the ETree. For DSIExtQueryExecutors that do use the ETree, this should be called immediately after construction.

This will create the results if necessary.

void PushParamData ( simba_unsigned_native  in_paramSet,
Simba::DSI::IParameterSource in_paramSrc 
) [virtual]

Push part of an input parameter value before executing in an IParameterSource*.

This value will be stored for use later during query execution.

This function will be called, at the most, only once for any parameter set or parameter combination where the parameter has a non-character or binary data type.

For parameters with character or binary data types, this method may be called multiple times for the same parameter set or parameter combination. The multiple parts should be concatenated together to get the complete value.

Calling SetOutputValue() on in_paramSrc will trigger a BadStateException, even if the parameter is an input/output parameter. Output values should only be set during IQueryExecutor::Execute().

This method should throw a BadDefaultParamException if a "default" parameter value is passed in for a parameter where "default" has no meaning.

NOTE: For character or binary data types the maximum size of each part is determined by the DSI_MAXIMUM_PUSH_PARAM_DATA_CHUNK_SIZE driver property.

Parameters:
in_paramSet The parameter set or parameter combination to push into the parameter source.
in_paramSrc The IParameterSource* into which the parameter set or parameter combination will be pushed.

Implements IQueryExecutor.


Member Data Documentation

ILogger* m_log [protected]

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

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