DSISimpleResultSet Class Reference

Simple partial implementation of IResult which facilitates forward-only cursors. More...

Inherits Simba::DSI::IResult.

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)
 Request fetching and processing of the next batch of rows.
void CloseCursor ()
 Closes the DSI's internal result cursor and clears associated memory.
virtual bool GetDataNeeded (simba_uint16 in_column)
 Gets the data needed status of a column as set by SetDataNeeded.
Simba::DSI::ResultType GetResultType ()
 Returns the type of the result.
virtual Simba::DSI::IColumnsGetSelectColumns ()=0
 Retrieves an IColumns* which can provide access to column metadata for each columns in the result.
virtual bool HasRowCount ()=0
 Determine if the number of rows is known.
virtual bool IsBulkFetchSupported (std::set< simba_uint32 > &in_boundColumnIndex)
 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)
 Returns a cellmark to the column of the row at which the cursor is positioned.
bool Move (Simba::DSI::DSIDirection in_direction, simba_signed_native in_offset)
 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.
void SetCursorType (Simba::DSI::DSICursorType in_cursorType)
 Sets the type of cursor to be used for traversing over the result set.
virtual void SetDataNeeded (simba_uint16 in_column, bool in_dataNeeded)
 Indicates whether RetrieveData() might be called on the given column after the next call to Move().
virtual void SetFetchRowsetSize (simba_unsigned_native in_rowsetSize)
 Sets the number of rows that are to be fetched to the client application.
virtual ~DSISimpleResultSet ()
 Destructor.

Protected Member Functions

virtual simba_unsigned_native DoBulkFetch (simba_unsigned_native in_maxRows, const std::vector< Simba::DSI::IBulkProcessor * > &in_bulkProcessors)
virtual void DoCloseCursor ()=0
 Clean up memory by closing the cursor.
 DSISimpleResultSet ()
 Constructor.
simba_unsigned_native GetCurrentRow () const
 Returns the current row index.
virtual bool MoveToNextRow ()=0
 Move to the next row.

Detailed Description

Simple partial implementation of IResult which facilitates forward-only cursors.

Implementers choosing to subclass DSISimpleResultSet need only cache the the current row in memory.


Constructor & Destructor Documentation

virtual ~DSISimpleResultSet (  )  [virtual]

Destructor.

DSISimpleResultSet (  )  [protected]

Constructor.


Member Function Documentation

virtual simba_unsigned_native BulkFetch ( simba_unsigned_native  in_rowsetSize,
const std::vector< Simba::DSI::IBulkProcessor * > &  in_bulkProcessors 
) [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.

Implements IResult.

void CloseCursor (  )  [virtual]

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

Implements IResult.

virtual simba_unsigned_native DoBulkFetch ( simba_unsigned_native  in_maxRows,
const std::vector< Simba::DSI::IBulkProcessor * > &  in_bulkProcessors 
) [protected, virtual]
Parameters:
in_maxRows Maximum # of rows to fetch.
in_bulkProcessors Vector of pointers to bulk processors. (NOT OWN)
virtual void DoCloseCursor (  )  [protected, pure virtual]

Clean up memory by closing the cursor.

Called from CloseCursor() to ensure that the ResultSet performs any special handling and that it clears associated memory.

simba_unsigned_native GetCurrentRow (  )  const [inline, protected]

Returns the current row index.

Returns:
The current row index.
virtual bool GetDataNeeded ( simba_uint16  in_column  )  [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.

This method may throw a DSIException in the event that an error occurred.

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.

Implements IResult.

Simba::DSI::ResultType GetResultType (  )  [virtual]

Returns the type of the result.

DSISimpleResultSet is of type RESULT_SET.

Returns:
Result type -- RESULT_SET

Implements IResult.

virtual Simba::DSI::IColumns* GetSelectColumns (  )  [pure virtual]

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

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

Implements IResult.

virtual bool HasRowCount (  )  [pure virtual]

Determine if the number of rows is known.

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

Implements IResult.

virtual bool IsBulkFetchSupported ( std::set< simba_uint32 > &  in_boundColumnIndexes  )  [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.

Implements IResult.

virtual Simba::DSI::ICellmark* MarkCell ( simba_uint16  in_column  )  [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 would return a NULL pointer and/or 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.
Returns:
Returns a cellmark to mark the column of the row. (OWN)

Implements IResult.

bool Move ( Simba::DSI::DSIDirection  in_direction,
simba_signed_native  in_offset 
) [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.

Implements IResult.

virtual bool MoveToNextRow (  )  [protected, pure virtual]

Move to the next row.

Called from Move() to indicate that the cursor should now be moved to the next row.

Returns:
True if there are more rows in the ResultSet; false otherwise.
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 full elements 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, though for character data the buffer has extra room available at the end for a null terminator
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 returning in in_data.
Returns:
True if there is more data; false otherwise.

Implements IResult.

void SetCursorType ( Simba::DSI::DSICursorType  in_cursorType  )  [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.

DSISimpleResultSet only supports DSI_FORWARD_ONLY. All other types of cursor types will result in an exception.

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

Implements IResult.

virtual void SetDataNeeded ( simba_uint16  in_column,
bool  in_dataNeeded 
) [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.

This implementation stores all columns whose data is needed in m_dataNeededColumns.

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.

Implements IResult.

virtual void SetFetchRowsetSize ( simba_unsigned_native  in_rowsetSize  )  [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.

The default implementation in DSISimpleResultSet ignores this value and does not do any pre-fetching of data.

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

Implements IResult.


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