IResult Class Reference

Exposes query result functionality to the ODBC layer. More...

Inherited by DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, ITemporaryTable, DSIExtResultSet, and DSIExtSortedResultSet.

List of all members.

Public Member Functions

virtual simba_unsigned_native BulkFetch (simba_unsigned_native in_rowsetSize, const std::vector< Simba::DSI::IBulkProcessor * > &in_bulkProcessors)=0
 Request fetching and processing of the next batch of rows.
virtual void CloseCursor ()=0
 Closes the DSI's internal result cursor and clears associated memory.
virtual bool GetDataNeeded (simba_uint16 in_column)=0
 Gets the data needed status of a column as set by SetDataNeeded.
virtual const ExecutedSQLInfoGetExecutedSQLInfo () const
 Return information on the executed SQL statement that created this IResult.
virtual Simba::DSI::ResultType GetResultType ()=0
 Returns the type of the result.
virtual bool GetRowCount (simba_uint64 &out_rowCount)
 Get the rowcount for this IResult.
virtual simba_unsigned_native GetRowCount ()
 Returns the row count.
virtual Simba::DSI::IColumnsGetSelectColumns ()=0
 Retrieves an IColumns* which can provide access to column metadata for each columns in the result. (NOT OWN).
virtual bool HasRowCount ()=0
 Determine if the number of rows in the result set is known.
virtual bool IsBulkFetchSupported (std::set< simba_uint32 > &in_boundColumnIndexes)=0
 Determine if the DSII can support bulk fetching for the current query and the given list of bound columns.
virtual Simba::DSI::ICellmarkMarkCell (simba_uint16 in_column)=0
 Returns a cellmark to the column of the row at which the cursor is positioned.
virtual bool Move (Simba::DSI::DSIDirection in_direction, simba_signed_native in_offset)=0
 Traverses the result set.
virtual bool RetrieveData (simba_uint16 in_column, SqlData *in_data, simba_signed_native in_offset, simba_signed_native in_maxSize)=0
 Fills in in_data with a chunk of data for the given column in the current row.
virtual void SetCursorType (Simba::DSI::DSICursorType in_cursorType)=0
 Sets the type of cursor to be used for traversing over the result set.
virtual void SetDataNeeded (simba_uint16 in_column, bool in_dataNeeded)=0
 Indicates whether RetrieveData() might be called on the given column after the next call to Move().
virtual void SetFetchRowsetSize (simba_unsigned_native in_rowsetSize)=0
 Sets the number of rows that are to be fetched to the client application.
virtual ~IResult ()
 Destructor.

Protected Member Functions

 IResult ()
 Constructor.

Detailed Description

Exposes query result functionality to the ODBC layer.

Instances of IResult should normally be created at the end of SQLPrepare (but before SQLExecute). Although the data will not be available at this point, it is assumed that enough knowledge about the metadata for the result will be made available, such that it is possible to get the columns of the result via GetSelectColumns().


Constructor & Destructor Documentation

virtual ~IResult (  )  [inline, virtual]

Destructor.

IResult (  )  [inline, protected]

Constructor.


Member Function Documentation

virtual simba_unsigned_native BulkFetch ( simba_unsigned_native  in_rowsetSize,
const std::vector< Simba::DSI::IBulkProcessor * > &  in_bulkProcessors 
) [pure virtual]

Request fetching and processing of the next batch of rows.

The DSII needs to fetch and process at least one row per call unless the end of the rowset is reached. The returned value indicates the actual number of rows that were fetched and processed. The SDK interprets a return value of 0 as if the end of the result set was reached and no more rows are available.

The SDK provides one bulk processor per column that needs to be processed. The index of the column is NOT equal to the index of the bulk processor in the given array, but is accessible through the bulk processor interface. The context necessary for bulk processing needs to be accessible from the class that implements the bulk processor interface.

Parameters:
in_rowsetSize Number of rows to fetch and process.
in_bulkProcessors Vector of pointers to bulk processors. (NOT OWN)
Returns:
Number of rows fetched and converted. 0 indicates no more rows are available.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, and TemporaryTable.

virtual void CloseCursor (  )  [pure virtual]

Closes the DSI's internal result cursor and clears associated memory.

Exceptions:
DSIException in the event that an error occurred.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtSimpleResultSet, and DSIExtSortedResultSet.

virtual bool GetDataNeeded ( simba_uint16  in_column  )  [pure virtual]

Gets the data needed status of a column as set by SetDataNeeded.

If SetDataNeeded was not called, the value is assumed to be false.

Parameters:
in_column A column index. The first column uses index 0.
Exceptions:
DSIException if an error occurs.
Returns:
The data needed status of in_column.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtSimpleResultSet, and DSIExtSortedResultSet.

virtual const ExecutedSQLInfo& GetExecutedSQLInfo (  )  const [virtual]

Return information on the executed SQL statement that created this IResult.

By default, this function returns an unknown SQL statement information. A DSII that can determine which kind of SQL statement has been executed to create this IResult can override this function and return a meaningful ExecutedSQLInfo instance.

Returns:
The executed SQL information linked to this statement.
virtual Simba::DSI::ResultType GetResultType (  )  [pure virtual]

Returns the type of the result.

Returns:
Result type.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtResultSet, and DSIExtSortedResultSet.

virtual bool GetRowCount ( simba_uint64 &  out_rowCount  )  [virtual]

Get the rowcount for this IResult.

Parameters:
out_rowCount If the rowcount is know, it will be put into here.
Returns:
Whether the rowcount is known (and thus whether out_rowCount is valid)

Reimplemented in DSISimpleRowCountResult, FilteredMetadataResult, TemporaryTable, and DSIExtSortedResultSet.

virtual simba_unsigned_native GetRowCount (  )  [virtual]

Returns the row count.

Returns:
The row count, or Simba::DSI::IResult::ROW_COUNT_UNKNOWN if the row count is unknown.
virtual Simba::DSI::IColumns* GetSelectColumns (  )  [pure virtual]

Retrieves an IColumns* which can provide access to column metadata for each columns in the result. (NOT OWN).

May return NULL if there are no columns associated with the result.

This method may be called after query preparation and before execution. If the implementation is unable to return column metadata at this time, it may return an IColumns holding no columns. This method will be called again after execution to properly populate the IRD. Note that if implemented this way, ODBC functionality related to columns (eg. the IRD descriptor, SQLDescribeCol(), SQLColAttribute()) will not work properly between calling SQLPrepare() and SQLExecute().

Returns:
IColumns reference that provides access to column metadata. (NOT OWN)

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, and DSIExtSortedResultSet.

virtual bool HasRowCount (  )  [pure virtual]

Determine if the number of rows in the result set is known.

Returns:
True if the number of rows in the result set is known; false otherwise.

Implemented in DSIRowCountResult, DSISimpleResultSet, DSISimpleRowCountResult, FilteredMetadataResult, TemporaryTable, DSIExtResultSet, and DSIExtSortedResultSet.

virtual bool IsBulkFetchSupported ( std::set< simba_uint32 > &  in_boundColumnIndexes  )  [pure virtual]

Determine if the DSII can support bulk fetching for the current query and the given list of bound columns.

Parameters:
in_boundColumnIndexes Set containing the indexes of all bound columns (meaning the column values are 0-based).
Returns:
true if the DSII supports bulk fetch; false otherwise.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtResultSet, and DSIExtSortedResultSet.

virtual Simba::DSI::ICellmark* MarkCell ( simba_uint16  in_column  )  [pure virtual]

Returns a cellmark to the column of the row at which the cursor is positioned.

Marking a cell tells the DSII that the column being marked will require data, but not at this point, at a later time (likely after the cursor has moved past this column and/or past this row and/or past this result set). For DSI implementations that only support forward-only cursors, the DSII might cache this data for later access. For DSI implementations that support bidirectional cursors, the DSII might cache details of the result set, result set's row and result set row's column so it can reposition the cursor and retrieve the data.

DSI implementations that do not support cellmarking should throw an exception.

This data may/may not persist after a cursor has been closed.

Parameters:
in_column A column index for this cellmark. The first column uses index 0.
Exceptions:
DSIException if cellmarks aren't supported.
Returns:
Returns a cellmark to mark the column of the row. (OWN)

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtResultSet, DSIExtSimpleResultSet, and DSIExtSortedResultSet.

virtual bool Move ( Simba::DSI::DSIDirection  in_direction,
simba_signed_native  in_offset 
) [pure virtual]

Traverses the result set.

Different CursorTypes correspond to support for different sets of values of in_direction.

It is expected that the IResult's internal cursor is positioned before the start of the result set before the first Move().

Parameters:
in_direction Direction to traverse the result set
in_offset Used for certain directions to indicate an offset from a relative position.
Exceptions:
DSIException if the direction is not supported.
Returns:
True if there are more rows left; false otherwise.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtSimpleResultSet, and DSIExtSortedResultSet.

virtual bool RetrieveData ( simba_uint16  in_column,
SqlData in_data,
simba_signed_native  in_offset,
simba_signed_native  in_maxSize 
) [pure virtual]

Fills in in_data with a chunk of data for the given column in the current row.

The SqlTypeMetadata* used by in_data is the same SqlTypeMetadata* exposed by the IColumn describing the column.

The following procedure should be implemented by this method:

  • if the data is null, call in_data->SetNull(true). in_offset and in_maxSize can be ignored
  • if the data is not of a character or binary type, then the value should be copied into the pointer returned by in_data->GetBuffer(). in_offset and in_maxSize can be ignored
  • if the data is of a character or binary type:
    • in_offset specifies the starting point to copy data from, in # of bytes from the start of that piece of data
      • in_offset must be aligned properly to the start of a data element
    • in_maxSize indicates the maximum number of bytes to copy
      • if in_maxSize is RETRIEVE_ALL_DATA, it means that the whole piece of data should be copied
    • the size of the data chunk being copied should be set with in_data->SetLength()
      • this length is the number of bytes copied
      • if there's only room for a partial element at the end, it does not need to be copied, and should not be included in the SetLength() length
      • calling SetLength() must be done before copying data in, because it modifies the size of the data buffer
    • the chunk of data starting at in_offset which is at a maximum in_size bytes long should be copied into the pointer returned by in_data->GetBuffer().
      • null termination is not necessary
Parameters:
in_column A column index. The first column uses index 0.
in_data Holds a buffer to store the requested data. (NOT OWN)
in_offset Number of bytes in the data to skip before copying into in_data.
in_maxSize Maximum number of bytes of data to return in in_data.
Exceptions:
DSIException if an error occurs.
Returns:
True if there is more data; false otherwise.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, LongDataCacheTable, TemporaryTable, DSIExtSimpleResultSet, and DSIExtSortedResultSet.

virtual void SetCursorType ( Simba::DSI::DSICursorType  in_cursorType  )  [pure virtual]

Sets the type of cursor to be used for traversing over the result set.

This method must be called before calling Move(). Otherwise the cursor type used is undefined.

Parameters:
in_cursorType Type of cursor used by the DSI to traverse the result set.
Exceptions:
DSIException if the cursor type is not supported.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtSimpleResultSet, and DSIExtSortedResultSet.

virtual void SetDataNeeded ( simba_uint16  in_column,
bool  in_dataNeeded 
) [pure virtual]

Indicates whether RetrieveData() might be called on the given column after the next call to Move().

The value given here applies for any subsequent Move() calls.

Parameters:
in_column A column index. The first column uses index 0.
in_dataNeeded Indicates whether data may be retrieved from the given column by the ODBC layer or not.
Exceptions:
DSIException if an error occurs.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtSimpleResultSet, and DSIExtSortedResultSet.

virtual void SetFetchRowsetSize ( simba_unsigned_native  in_rowsetSize  )  [pure virtual]

Sets the number of rows that are to be fetched to the client application.

This value is to be used as an optimization hint by the DSII to possibly implement pre-fetching of data. It should not affect the number of rows the Move() function moves by.

Eg. If SetFetchRowsetSize(10) is called. The next call to Move() may choose to use this information to fetch and cache 10 or more rows of data. The following 9 calls to Move() do not necessarily need to fetch more data and can just use cached data.

Note that the DSII is not limited to only pre-fetching in_rowsetSize number of rows.

This method should be called before calling Move() and may be called again if the application changes this value. If it is not called, the default rowset size should be assumed to be 1.

This method should not throw an exception. If pre-fetching is not supported, the value can simply be ignored.

Parameters:
in_rowsetSize The number of rows the application is requesting per fetch.

Implemented in DSIRowCountResult, DSISimpleResultSet, FilteredMetadataResult, TemporaryTable, DSIExtResultSet, and DSIExtSortedResultSet.


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

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