#include <cursor.h>

Inheritance diagram for KexiDB::Cursor:

Public Types
enum	Options { NoOptions = 0 , Buffered = 1 }

Public Member Functions
Connection *	connection () const

bool	open ()

bool	reopen ()

virtual bool	close ()

QuerySchema *	query () const

TQValueList< TQVariant >	queryParameters () const

void	setQueryParameters (const TQValueList< TQVariant > &params)

TQString	rawStatement () const

uint	options () const

bool	isOpened () const

bool	isBuffered () const

void	setBuffered (bool buffered)

bool	moveFirst ()

virtual bool	moveLast ()

virtual bool	moveNext ()

virtual bool	movePrev ()

bool	eof () const

bool	bof () const

TQ_LLONG	at () const

uint	fieldCount () const

bool	containsROWIDInfo () const

virtual TQVariant	value (uint i)=0

virtual const char **	rowData () const =0

void	setOrderByColumnList (const TQStringList &columnNames)

void	setOrderByColumnList (const TQString &column1, const TQString &column2=TQString(), const TQString &column3=TQString(), const TQString &column4=TQString(), const TQString &column5=TQString())

QueryColumnInfo::Vector	orderByColumnList () const

virtual void	storeCurrentRow (RowData &data) const =0

bool	updateRow (RowData &data, RowEditBuffer &buf, bool useROWID=false)

bool	insertRow (RowData &data, RowEditBuffer &buf, bool getROWID=false)

bool	deleteRow (RowData &data, bool useROWID=false)

bool	deleteAllRows ()

virtual int	serverResult ()

virtual TQString	serverResultName ()

virtual TQString	serverErrorMsg ()

TQString	debugString () const

void	debug () const

Public Member Functions inherited from KexiDB::Object
bool	error () const

const TQString &	errorMsg () const

int	errorNum () const

int	previousServerResult () const

TQString	previousServerResultName () const

void	debugError ()

virtual void	clearError ()

TQString	msgTitle () const

const TQString	recentSQLString () const

Protected Types
enum	FetchResult { FetchError =0 , FetchOK =1 , FetchEnd =2 }

Protected Member Functions
	Cursor (Connection *conn, const TQString &statement, uint options=NoOptions)

	Cursor (Connection *conn, QuerySchema &query, uint options=NoOptions)

void	init ()

bool	getNextRecord ()

virtual bool	drv_open ()=0

virtual bool	drv_close ()=0

virtual void	drv_getNextRecord ()=0

virtual void	drv_appendCurrentRecordToBuffer ()=0

virtual void	drv_bufferMovePointerNext ()=0

virtual void	drv_bufferMovePointerPrev ()=0

virtual void	drv_bufferMovePointerTo (TQ_LLONG at)=0

virtual void	drv_clearBuffer ()

void	clearBuffer ()

virtual void	drv_clearServerResult ()=0

Protected Member Functions inherited from KexiDB::Object
	Object (MessageHandler *handler=0)

virtual void	setError (int code=ERR_OTHER, const TQString &msg=TQString())

virtual void	setError (const TQString &msg)

virtual void	setError (const TQString &title, const TQString &msg)

void	setError (KexiDB::Object *obj, const TQString &prependMessage=TQString())

virtual void	setError (KexiDB::Object *obj, int code, const TQString &prependMessage=TQString())

virtual int	askQuestion (const TQString &message, KMessageBox::DialogType dlgType, KMessageBox::ButtonCode defaultResult, const KGuiItem &buttonYes=KStdGuiItem::yes(), const KGuiItem &buttonNo=KStdGuiItem::no(), const TQString &dontShowAskAgainName=TQString(), int options=KMessageBox::Notify, MessageHandler *msgHandler=0)

Protected Attributes
TQGuardedPtr< Connection >	m_conn

QuerySchema *	m_query

TQString	m_rawStatement

bool	m_opened: 1

bool	m_atLast: 1

bool	m_afterLast: 1

bool	m_validRecord: 1

bool	m_containsROWIDInfo: 1

TQ_LLONG	m_at

uint	m_fieldCount

uint	m_logicalFieldCount

uint	m_options

char	m_result

int	m_records_in_buf

bool	m_buffering_completed: 1

QueryColumnInfo::Vector *	m_fieldsExpanded

QueryColumnInfo::Vector *	m_orderByColumnList

TQValueList< TQVariant > *	m_queryParameters

Protected Attributes inherited from KexiDB::Object
TQString	m_sql

TQString	m_errorSql

int	m_serverResult

TQString	m_serverResultName

TQString	m_serverErrorMsg

TQString	m_errMsg

Detailed Description

Provides database cursor functionality.

Cursor can be defined in two ways:

by passing QuerySchema object to Connection::executeQuery() or Connection::prepareQuery(); then query is defined for in engine-independent way – this is recommended usage
by passing raw query statement string to Connection::executeQuery() or Connection::prepareQuery(); then query may be defined for in engine-dependent way – this is not recommended usage, but convenient when we can't or do not want to allocate QuerySchema object, while we know that the query statement is syntactically and logically ok in our context.

You can move cursor to next record with moveNext() and move back with movePrev(). The cursor is always positioned on record, not between records, with exception that ofter open() it is positioned before first record (if any) – then bof() equals true, and can be positioned after the last record (if any) with moveNext() – then eof() equals true, For example, if you have four records 1, 2, 3, 4, then after calling moveNext(), moveNext(), moveNext(), movePrev() you are going through records: 1, 2, 3, 2.

Cursor can be buffered or unbuferred. Buffering in this class is not related to any SQL engine capatibilities for server-side cursors (eg. like 'DECLARE CURSOR' statement) - buffered data is at client (application) side. Any record retrieved in buffered cursor will be stored inside an internal buffer and reused when needed. Unbuffered cursor always requires one record fetching from db connection at every step done with moveNext(), movePrev(), etc.

Notes:

Do not use delete operator for Cursor objects - this will fail; use Connection::deleteCursor() instead.
QuerySchema object is not owned by Cursor object that uses it.

Definition at line 66 of file cursor.h.

Member Enumeration Documentation

◆ FetchResult

enum KexiDB::Cursor::FetchResult

protected

possible results of row fetching, used for m_result

Definition at line 257 of file cursor.h.

◆ Options

enum KexiDB::Cursor::Options

Cursor options that describes its behaviour.

Definition at line 73 of file cursor.h.

Constructor & Destructor Documentation

◆ ~Cursor()

Cursor::~Cursor ( )

virtual

Definition at line 107 of file cursor.cpp.

◆ Cursor() [1/2]

Cursor::Cursor	(	Connection *	conn,
		const TQString &	statement,
		uint	options = `NoOptions`
	)

protected

Cursor will operate on conn, raw statement will be used to execute query.

Definition at line 40 of file cursor.cpp.

◆ Cursor() [2/2]

Cursor::Cursor	(	Connection *	conn,
		QuerySchema &	query,
		uint	options = `NoOptions`
	)

protected

Cursor will operate on conn, query schema will be used to execute query.

Definition at line 53 of file cursor.cpp.

Member Function Documentation

◆ at()

TQ_LLONG Cursor::at ( ) const

Returns: current internal position of the cursor's query. We are counting records from 0. Value -1 means that cursor does not point to any valid record (this happens eg. after open(), close(), and after moving after last record or before first one.

Definition at line 349 of file cursor.cpp.

◆ bof()

bool Cursor::bof ( ) const

Returns: true if current position is before first record.

Definition at line 344 of file cursor.cpp.

◆ clearBuffer()

void Cursor::clearBuffer ( )

protected

Definition at line 370 of file cursor.cpp.

◆ close()

bool Cursor::close ( )

virtual

Opens the cursor using statement. Omit statement if cursor is already initialized with statement at creation time. If statement is not empty, existing statement (if any) is overwritten. *‍/ bool open( const TQString& statement = TQString() );

    /*! Closes previously opened cursor. 
        If the cursor is closed, nothing happens.

Definition at line 178 of file cursor.cpp.

◆ connection()

Connection * KexiDB::Cursor::connection ( ) const

inline

Returns: connection used for the cursor

Definition at line 81 of file cursor.h.

◆ containsROWIDInfo()

bool KexiDB::Cursor::containsROWIDInfo ( ) const

inline

Returns: true if ROWID information is appended with every row. ROWID information is available if DriverBehaviour::ROW_ID_FIELD_RETURNS_LAST_AUTOINCREMENTED_VALUE == false for a KexiDB database driver and the master table has no primary key defined. Phisically, ROWID value is returned after last returned field, so data vector's length is expanded by one.

Definition at line 173 of file cursor.h.

◆ debug()

void Cursor::debug ( ) const

Outputs debug information.

Definition at line 524 of file cursor.cpp.

◆ debugString()

TQString Cursor::debugString ( ) const

Returns: Debug information.

Definition at line 497 of file cursor.cpp.

◆ deleteAllRows()

bool Cursor::deleteAllRows ( )

Todo:: doesn't update cursor's buffer YET!

Definition at line 488 of file cursor.cpp.

◆ deleteRow()

bool Cursor::deleteRow	(	RowData &	data,
		bool	useROWID = `false`
	)

Todo:: doesn't update cursor's buffer YET!

Definition at line 479 of file cursor.cpp.

◆ drv_appendCurrentRecordToBuffer()

virtual void KexiDB::Cursor::drv_appendCurrentRecordToBuffer ( )

protectedpure virtual

Stores currently fetched record's values in appropriate place of the buffer. Note for driver developers: This place can be computed using m_at. Do not change value of m_at or any other Cursor members, only change your internal structures like pointer to current row, etc. If your database engine's API function (for record fetching) do not allocates such a space, you want to allocate a space for current record. Otherwise, reuse existing structure, what could be more efficient. All functions like drv_appendCurrentRecordToBuffer() operates on the buffer, i.e. array of stored rows. You are not forced to have any particular fixed structure for buffer item or buffer itself - the structure is internal and only methods like storeCurrentRecord() visible to public.

◆ drv_bufferMovePointerNext()

virtual void KexiDB::Cursor::drv_bufferMovePointerNext ( )

protectedpure virtual

Moves pointer (that points to the buffer) – to next item in this buffer. Note for driver developers: probably just execute "your_pointer++" is enough.

◆ drv_bufferMovePointerPrev()

virtual void KexiDB::Cursor::drv_bufferMovePointerPrev ( )

protectedpure virtual

Like drv_bufferMovePointerNext() but execute "your_pointer--".

◆ drv_bufferMovePointerTo()

virtual void KexiDB::Cursor::drv_bufferMovePointerTo ( TQ_LLONG at )

protectedpure virtual

Moves pointer (that points to the buffer) to a new place: at.

◆ drv_clearBuffer()

virtual void KexiDB::Cursor::drv_clearBuffer ( )

inlineprotectedvirtual

Clears cursor's buffer if this was allocated (only for buffered cursor type). Otherwise do nothing. For reimplementing. Default implementation does nothing.

Definition at line 313 of file cursor.h.

◆ drv_clearServerResult()

virtual void KexiDB::Cursor::drv_clearServerResult ( )

protectedpure virtual

Clears an internal member that is used to storing last result code, the same that is returend by serverResult().

Reimplemented from KexiDB::Object.

◆ eof()

bool Cursor::eof ( ) const

Returns: true if current position is after last record.

Definition at line 339 of file cursor.cpp.

◆ fieldCount()

uint KexiDB::Cursor::fieldCount ( ) const

inline

Returns: number of fields available for this cursor. This never includes ROWID column or other internal coluns (e.g. lookup).

Definition at line 165 of file cursor.h.

◆ getNextRecord()

bool Cursor::getNextRecord ( )

protected

Internal: cares about proper flag setting depending on result of drv_getNextRecord() and depending on wherher a cursor is buffered.

if (m_at < (m_records_in_buf-1)) {//we have next record already buffered:

Definition at line 381 of file cursor.cpp.

◆ init()

void Cursor::init ( )

protected

Definition at line 65 of file cursor.cpp.

◆ insertRow()

bool Cursor::insertRow	(	RowData &	data,
		RowEditBuffer &	buf,
		bool	getROWID = `false`
	)

Todo:: doesn't update cursor's buffer YET!

Definition at line 470 of file cursor.cpp.

◆ isBuffered()

bool Cursor::isBuffered ( ) const

Returns: true if the cursor is buffered.

Definition at line 356 of file cursor.cpp.

◆ isOpened()

bool KexiDB::Cursor::isOpened ( ) const

inline

Returns: true if the cursor is opened.

Definition at line 121 of file cursor.h.

◆ moveFirst()

bool Cursor::moveFirst ( )

Moves current position to the first record and retrieves it.

Returns: true if the first record was retrieved. False could mean that there was an error or there is no record available.

Definition at line 205 of file cursor.cpp.

◆ moveLast()

bool Cursor::moveLast ( )

virtual

Moves current position to the last record and retrieves it.

Returns: true if the last record was retrieved. False could mean that there was an error or there is no record available.

Definition at line 254 of file cursor.cpp.

◆ moveNext()

bool Cursor::moveNext ( )

virtual

Moves current position to the next record and retrieves it.

Definition at line 292 of file cursor.cpp.

◆ movePrev()

bool Cursor::movePrev ( )

virtual

Moves current position to the next record and retrieves it. Currently it's only supported for buffered cursors.

Definition at line 303 of file cursor.cpp.

◆ open()

bool Cursor::open ( )

Opens the cursor using data provided on creation. The data might be either QuerySchema or raw sql statement.

Definition at line 131 of file cursor.cpp.

◆ options()

uint KexiDB::Cursor::options ( ) const

inline

Returns: logically or'd cursor's options, selected from Cursor::Options enum.

Definition at line 118 of file cursor.h.

◆ orderByColumnList()

QueryColumnInfo::Vector Cursor::orderByColumnList ( ) const

Returns: a list of fields contained in ORDER BY section of the query.

See also: setOrderBy(const TQStringList&)

Definition at line 553 of file cursor.cpp.

◆ query()

QuerySchema * KexiDB::Cursor::query ( ) const

inline

Returns: query schema used to define this cursor or NULL if the cursor is not defined by a query schema but by a raw statement.

Definition at line 104 of file cursor.h.

◆ queryParameters()

TQValueList< TQVariant > Cursor::queryParameters ( ) const

Returns: query parameters assigned to this cursor

Definition at line 558 of file cursor.cpp.

◆ rawStatement()

TQString KexiDB::Cursor::rawStatement ( ) const

inline

Returns: raw query statement used to define this cursor or null string if raw statement instead (but QuerySchema is defined instead).

Definition at line 114 of file cursor.h.

◆ reopen()

bool Cursor::reopen ( )

Closes and then opens again the same cursor. If the cursor is not opened it is just opened and result of this open is returned. Otherwise, true is returned if cursor is successfully closed and then opened.

Definition at line 198 of file cursor.cpp.

◆ rowData()

virtual const char ** KexiDB::Cursor::rowData ( ) const

pure virtual

[PROTOTYPE]

Returns: current record data or NULL if there is no current records.

◆ serverErrorMsg()

virtual TQString KexiDB::Cursor::serverErrorMsg ( )

inlinevirtual

Returns: (not i18n'd) description text (message) of last operation's error/result. In most cases engines do return such a messages, any user can then use this to refer a documentation. Note for driver developers: Leave the default implementation (null string is returned ) if your engine has no such capability.

Reimplemented from KexiDB::Object.

Definition at line 247 of file cursor.h.

◆ serverResult()

virtual int KexiDB::Cursor::serverResult ( )

inlinevirtual

Returns: a code of last executed operation's result at the server side. This code is engine dependent and may be even engine-version dependent. It can be visible in applications mainly after clicking a "Details>>" button or something like that – this just can be useful for advanced users and for testing. Note for driver developers: Return here the value you usually store as result of most lower-level operations. By default this method returns 0.

Reimplemented from KexiDB::Object.

Definition at line 233 of file cursor.h.

◆ serverResultName()

virtual TQString KexiDB::Cursor::serverResultName ( )

inlinevirtual

Returns: (not i18n'd) name of last executed operation's result at the server side. Sometimes engines have predefined its result names that can be used e.g. to refer a documentation. SQLite is one of such engines. Note for driver developers: Leave the default implementation (null string is returned ) if your engine has no such capability.

Reimplemented from KexiDB::Object.

Definition at line 240 of file cursor.h.

◆ setBuffered()

void Cursor::setBuffered ( bool buffered )

Sets this cursor to buffered type or not. See description of buffered and nonbuffered cursors in class description. This method only works if cursor is not opened (isOpened()==false). You can close already opened cursor and then switch this option on/off.

Definition at line 361 of file cursor.cpp.

◆ setOrderByColumnList() [1/2]

void Cursor::setOrderByColumnList	(	const TQString &	column1,
		const TQString &	column2 = `TQString()`,
		const TQString &	column3 = `TQString()`,
		const TQString &	column4 = `TQString()`,
		const TQString &	column5 = `TQString()`
	)

Convenience method, similar to setOrderByColumnList(const TQStringList&).

Convenience method, similar to setOrderBy(const TQStringList&).

Todo:: implement this, like above

Todo:

Todo:: add ORDER BY info to debugString()

Definition at line 541 of file cursor.cpp.

◆ setOrderByColumnList() [2/2]

void Cursor::setOrderByColumnList ( const TQStringList & columnNames )

Sets a list of columns for ORDER BY section of the query. Only works when the cursor has been created using QuerySchema object (i.e. when query()!=0; does not work with raw statements). Each name on the list must be a field or alias present within the query and must not be covered by aliases. If one or more names cannot be found within the query, the method will have no effect. Any previous ORDER BY settings will be removed.

The order list provided here has priority over a list defined in the QuerySchema object itseld (using QuerySchema::setOrderByColumnList()). The QuerySchema object itself is not modifed by this method: only order of records retrieved by this cursor is affected.

Use this method before calling open(). You can also call reopen() after calling this method to see effects of applying records order.

Todo:: implement this:

Definition at line 529 of file cursor.cpp.

◆ setQueryParameters()

void Cursor::setQueryParameters ( const TQValueList< TQVariant > & params )

Sets query parameters params for this cursor.

Definition at line 563 of file cursor.cpp.

◆ storeCurrentRow()

virtual void KexiDB::Cursor::storeCurrentRow ( RowData & data ) const

pure virtual

Puts current record's data into data (makes a deep copy). This have unspecified behaviour if the cursor is not at valid record. Note: For reimplementation in driver's code. Shortly, this method translates a row data from internal representation (probably also used in buffer) to simple public RecordData representation.

◆ updateRow()

bool Cursor::updateRow	(	RowData &	data,
		RowEditBuffer &	buf,
		bool	useROWID = `false`
	)

Todo:: doesn't update cursor's buffer YET!

Definition at line 461 of file cursor.cpp.

◆ value()

virtual TQVariant KexiDB::Cursor::value ( uint i )

pure virtual

Returns: a value stored in column number i (counting from 0). Is has unspecified behaviour if the cursor is not at valid record. Note for driver developers: If i is >= than m_fieldCount, null TQVariant value should be returned. To return a value typically you can use a pointer to internal structure that contain current row data (buffered or unbuffered).

Member Data Documentation

◆ m_afterLast

bool KexiDB::Cursor::m_afterLast

protected

Definition at line 329 of file cursor.h.

◆ m_at

TQ_LLONG KexiDB::Cursor::m_at

protected

Definition at line 333 of file cursor.h.

◆ m_atLast

bool KexiDB::Cursor::m_atLast

protected

Definition at line 328 of file cursor.h.

◆ m_buffering_completed

bool KexiDB::Cursor::m_buffering_completed

protected

true if we already have all records stored in the buffer

Definition at line 341 of file cursor.h.

◆ m_conn

TQGuardedPtr<Connection> KexiDB::Cursor::m_conn

protected

Definition at line 322 of file cursor.h.

◆ m_containsROWIDInfo

bool KexiDB::Cursor::m_containsROWIDInfo

protected

Definition at line 332 of file cursor.h.

◆ m_fieldCount

uint KexiDB::Cursor::m_fieldCount

protected

cached field count information

Definition at line 334 of file cursor.h.

◆ m_fieldsExpanded

QueryColumnInfo::Vector* KexiDB::Cursor::m_fieldsExpanded

protected

Useful e.g. for value(int) method when we need access to schema def.

Definition at line 345 of file cursor.h.

◆ m_logicalFieldCount

uint KexiDB::Cursor::m_logicalFieldCount

protected

logical field count, i.e. without intrernal values like ROWID or lookup

Definition at line 335 of file cursor.h.

◆ m_opened

bool KexiDB::Cursor::m_opened

protected

Definition at line 326 of file cursor.h.

◆ m_options

uint KexiDB::Cursor::m_options

protected

cursor options that describes its behaviour

Definition at line 336 of file cursor.h.

◆ m_orderByColumnList

QueryColumnInfo::Vector* KexiDB::Cursor::m_orderByColumnList

protected

Used by setOrderByColumnList()

Definition at line 348 of file cursor.h.

◆ m_query

QuerySchema* KexiDB::Cursor::m_query

protected

Definition at line 323 of file cursor.h.

◆ m_queryParameters

TQValueList<TQVariant>* KexiDB::Cursor::m_queryParameters

protected

Definition at line 350 of file cursor.h.

◆ m_rawStatement

TQString KexiDB::Cursor::m_rawStatement

protected

Definition at line 325 of file cursor.h.

◆ m_records_in_buf

int KexiDB::Cursor::m_records_in_buf

protected

number of records currently stored in the buffer

Definition at line 340 of file cursor.h.

◆ m_result

char KexiDB::Cursor::m_result

protected

result of a row fetching

Definition at line 337 of file cursor.h.

◆ m_validRecord

bool KexiDB::Cursor::m_validRecord

protected

true if valid record is currently retrieved @ current position

Definition at line 331 of file cursor.h.

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

kexi

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ FetchResult

◆ Options

Constructor & Destructor Documentation

◆ ~Cursor()

◆ Cursor() [1/2]

◆ Cursor() [2/2]

Member Function Documentation

◆ at()

◆ bof()

◆ clearBuffer()

◆ close()

◆ connection()

◆ containsROWIDInfo()

◆ debug()

◆ debugString()

◆ deleteAllRows()

◆ deleteRow()

◆ drv_appendCurrentRecordToBuffer()

◆ drv_bufferMovePointerNext()

◆ drv_bufferMovePointerPrev()

◆ drv_bufferMovePointerTo()

◆ drv_clearBuffer()

◆ drv_clearServerResult()

◆ eof()

◆ fieldCount()

◆ getNextRecord()

◆ init()

◆ insertRow()

◆ isBuffered()

◆ isOpened()

◆ moveFirst()

◆ moveLast()

◆ moveNext()

◆ movePrev()

◆ open()

◆ options()

◆ orderByColumnList()

◆ query()

◆ queryParameters()

◆ rawStatement()

◆ reopen()

◆ rowData()

◆ serverErrorMsg()

◆ serverResult()

◆ serverResultName()

◆ setBuffered()

◆ setOrderByColumnList() [1/2]

◆ setOrderByColumnList() [2/2]

◆ setQueryParameters()

◆ storeCurrentRow()

◆ updateRow()

◆ value()

Member Data Documentation

◆ m_afterLast

◆ m_at

◆ m_atLast

◆ m_buffering_completed

◆ m_conn

◆ m_containsROWIDInfo

◆ m_fieldCount

◆ m_fieldsExpanded

◆ m_logicalFieldCount

◆ m_opened

◆ m_options

◆ m_orderByColumnList

◆ m_query

◆ m_queryParameters

◆ m_rawStatement

◆ m_records_in_buf

◆ m_result

◆ m_validRecord

kexi