TemporaryTable Class Reference

This class represents a table that can have data written to and read from without worry of running out of memory, but will cease to exist when the object is destroyed. More...

Inherits Simba::DSI::ITemporaryTable.

Inherited by LongDataCacheTable.

List of all members.

Public Member Functions

virtual void AppendRow ()
 Append an empty row to the end of the temporary table for writing data to.
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.
virtual void CloseCursor ()
 Closes the DSI's internal result cursor and clears associated memory.
simba_unsigned_native GetCurrentRow ()
 Gets the current row within the table.
virtual bool GetDataNeeded (simba_uint16 in_column)
 Gets the data needed status of a column as set by SetDataNeeded.
virtual Simba::DSI::ResultType GetResultType ()
 Returns the type of the result.
virtual bool GetRowCount (simba_uint64 &out_rowCount)
 Get the rowcount for this IResult.
virtual Simba::DSI::IColumnsGetSelectColumns ()
 Retrieves an IColumns* which can provide access to column metadata for each columns in the result. (NOT OWN).
virtual bool HasRowCount ()
 Determine if the IResult has a row count.
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 bool LastAppendFilledBlock ()
 Check if the last call to Append() filled the current block.
virtual Simba::DSI::ICellmarkMarkCell (simba_uint16 in_column)
 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)
 Traverses the result set.
virtual bool RetrieveData (simba_uint16 in_column, SqlData *io_data, simba_signed_native in_offset, simba_signed_native in_maxSize)
 Fills in io_data with a chunk of data for the given column in the current row.
virtual 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.
simba_uint64 Size ()
 Get the number of rows in this table.
virtual bool WriteData (simba_uint16 in_column, SqlData *in_sqlData, simba_unsigned_native in_offset)
 Write data to a column in the current row.
virtual ~TemporaryTable ()
 Destructor.

Static Public Member Functions

static simba_uint32 GetMaxCachedLOBSize ()
 Get the maximum length in bytes of the partial data for long data types stored in the temporary table.

Protected Member Functions

virtual bool RetrieveDataFromSource (simba_uint16 in_column, SqlData *io_data, simba_signed_native in_offset, simba_signed_native in_maxSize)
 Retrieve long column data from source expression/table.
 TemporaryTable (const IMemoryContext &in_memoryContext, AutoPtr< TemporaryTableInfo > in_ttInfo, simba_uint32 in_maxCachedLOBSize, simba_size_t in_hintBlockSize, simba_size_t in_minimumNumberOwnedBlocks, ISwapAssistant *in_swapAssistant, bool in_useCompression)
 Constructor.
virtual void WriteDataToCacheFromSource (simba_uint16 in_column, simba_uint16 in_srcColumn, SqlData *in_sqlData, simba_unsigned_native in_offset)
 Write long column data from source expression/table to long data cache if source doesn't support bookmarking and record bookmark from the long data cache or from the source expression/table.

Protected Attributes

Simba::DSI::RowBlockm_curBlock
 The RowBlock that contains the current row. (NOT OWN).
simba_uint64 m_currentRow
 The current row in the table.
bool m_lastAppendFilledBlock
 Flag to indicate that the last append row caused the last block to be filled.
simba_size_t m_mrBookmarkedRow
 The most recent row for which bookmark has been recorded.
AutoPtr< Simba::DSI::SwapManagerm_swapManager
 The SwapManager that controls memory allocation for the rows in the table. (OWN).
AutoPtr< TemporaryTableInfom_ttInfo
 Prepared temporary table information.

Static Protected Attributes

static simba_uint32 s_maxCachedLOBSize
 Maximum length of the partial data stored in the table for long data types.

Friends

class Simba::DSI::TemporaryTableFactory

Detailed Description

This class represents a table that can have data written to and read from without worry of running out of memory, but will cease to exist when the object is destroyed.

It makes use of a SwapManager to ensure that memory is correctly swapped to disk, read from disk, and interpreted while in memory.

The TemporaryTable does no checking against the passed in types vs the IColumns used to set up the table, and assumes that the data passed in is correct. Be warned that behaviour is undefined if incorrect data is passed in for writing to or reading from a column.


Constructor & Destructor Documentation

virtual ~TemporaryTable (  )  [virtual]

Destructor.

TemporaryTable ( const IMemoryContext in_memoryContext,
AutoPtr< TemporaryTableInfo in_ttInfo,
simba_uint32  in_maxCachedLOBSize,
simba_size_t  in_hintBlockSize,
simba_size_t  in_minimumNumberOwnedBlocks,
ISwapAssistant in_swapAssistant,
bool  in_useCompression 
) [protected]

Constructor.

Parameters:
in_memoryContext The memory context for this temporary table
in_ttInfo The columns and bookmark column of the Temporary Table. (OWN)
in_maxCachedLOBSize The maximum length for Large Object (LOB).
in_hintBlockSize The suggested size for a block. See SwapManager for more detailed explanation.
in_minimumNumberOwnedBlocks The minimum number of blocks this TemporaryTable needs to own at all time, so the processing it is involved in can be successful even if the MemoryManager has run out of free memory.
in_swapAssistant The swap assistant that will be used to cooperate with the SwapManager. See SwapManager and ISwapAssitant for more detailed documentation. Cannot be NULL. (OWN)
in_useCompression If this table should compress data.

Member Function Documentation

virtual void AppendRow (  )  [virtual]

Append an empty row to the end of the temporary table for writing data to.

Implements ITemporaryTable.

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.

virtual void CloseCursor (  )  [virtual]

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

Exceptions:
DSIException in the event that an error occurred.

Implements IResult.

simba_unsigned_native GetCurrentRow (  ) 

Gets the current row within the table.

Returns:
the current row within the table.
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.
Returns:
the data needed status of in_column.

Implements IResult.

static simba_uint32 GetMaxCachedLOBSize (  )  [static]

Get the maximum length in bytes of the partial data for long data types stored in the temporary table.

Returns:
the maximum length in bytes of the partial data stored in the temporary table.
virtual Simba::DSI::ResultType GetResultType (  )  [virtual]

Returns the type of the result.

Returns:
RESULT_SET always.

Implements IResult.

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 from IResult.

virtual Simba::DSI::IColumns* GetSelectColumns (  )  [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().

Implements IResult.

virtual bool HasRowCount (  )  [virtual]

Determine if the IResult has a row count.

Returns:
true if the row count 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 bool LastAppendFilledBlock (  )  [virtual]

Check if the last call to Append() filled the current block.

Call this method if the usage for this class is to write some rows, read what was written and then write more rows. Filling an entire block before reading is the most efficient way to use this table with data compression on.

Returns:
true if the last call to Append() filled the current block; false otherwise.
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.

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:
A cellmark to mark the column of the row if supported and is a success, NULL otherwise. (OWN)

Implements IResult.

virtual 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. If an unsupported Direction is provided, an exception may be thrown. Returns true if the move is successful, or false if there are no more rows left.

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 in the event that an error occurred.
Returns:
true if the move was successful; false otherwise.

Implements IResult.

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

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

The SqlTypeMetadata* used by io_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 io_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 io_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 io_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 io_data->GetBuffer().
      • null termination is not necessary
Parameters:
in_column A column index. The first column uses index 0.
io_data Holds a buffer to store the requested data. (NOT OWN)
in_offset Number of bytes in the data to skip before copying into io_data.
in_maxSize Maximum number of bytes of data to return in in io_data.
Exceptions:
DSIException in the event that an error occurred.
Returns:
true if there is more data left after the retrieved chunk; false otherwise.

Implements IResult.

Reimplemented in LongDataCacheTable.

virtual bool RetrieveDataFromSource ( simba_uint16  in_column,
SqlData io_data,
simba_signed_native  in_offset,
simba_signed_native  in_maxSize 
) [protected, virtual]

Retrieve long column data from source expression/table.

Parameters:
in_column A column index. The first column uses index 0.
io_data Holds a buffer to store the requested data. (NOT OWN)
in_offset Number of bytes in the data to skip before copying into io_data.
in_maxSize Maximum number of bytes of data to return in in io_data.
Exceptions:
DSIException in the event that an error occurred.
Returns:
true if there is more data left after the retrieved chunk; false otherwise.
virtual 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. If the given cursor type is not supported, an exception may be thrown.

Parameters:
in_cursorType Type of cursor used by the DSI to traverse the result set.

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.

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 in the event that an error occurred.

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

simba_uint64 Size (  ) 

Get the number of rows in this table.

virtual bool WriteData ( simba_uint16  in_column,
SqlData in_sqlData,
simba_unsigned_native  in_offset 
) [virtual]

Write data to a column in the current row.

Variable length data must be written in one chunk except long data. Long data is specified by the column metadata the input column - TypeMetadata::IsLOBType() and can be written in multiple chunks.

If the data should be written in chunks, it is optimal to write the data in chunks the size of the result returned from GetMaxCachedLOBSize(). The first write into a column will cache the data in memory, up to the max cache size. Any subsequent writes for the same column will be stored on disk.

Parameters:
in_column The column to write data to.
in_sqlData The container for the data to write to the column. (NOT OWN)
in_offset The offset into the column to start writing data at.
Exceptions:
DSIException if the column is invalid, or if the offset is invalid for the column, or it will result in the given data overflowing the boundaries of the column.
Returns:
true if data is truncated, false otherwise.

Implements ITemporaryTable.

virtual void WriteDataToCacheFromSource ( simba_uint16  in_column,
simba_uint16  in_srcColumn,
SqlData in_sqlData,
simba_unsigned_native  in_offset 
) [protected, virtual]

Write long column data from source expression/table to long data cache if source doesn't support bookmarking and record bookmark from the long data cache or from the source expression/table.

Parameters:
in_column The column to write data to.
in_srcColumn The source column to read data from.
in_sqlData The container for the data to write to the column. (NOT OWN)
in_offset The offset into the column to start writing data at.
Exceptions:
DSIException if the column is invalid, or if the offset is invalid for the column, or it will result in the given data overflowing the boundaries of the column.

Friends And Related Function Documentation

friend class Simba::DSI::TemporaryTableFactory [friend]

Member Data Documentation

The RowBlock that contains the current row. (NOT OWN).

simba_uint64 m_currentRow [protected]

The current row in the table.

bool m_lastAppendFilledBlock [protected]

Flag to indicate that the last append row caused the last block to be filled.

simba_size_t m_mrBookmarkedRow [protected]

The most recent row for which bookmark has been recorded.

The SwapManager that controls memory allocation for the rows in the table. (OWN).

Prepared temporary table information.

simba_uint32 s_maxCachedLOBSize [static, protected]

Maximum length of the partial data stored in the table for long data types.


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