Search Toolkit Book for CSQLITE_Statement

SQL statement executing on SQLite database. More...

#include <db/sqlite/sqlitewrapp.hpp>

Collaboration diagram for CSQLITE_Statement:

Public Member Functions
	CSQLITE_Statement (CSQLITE_Connection *conn, CTempString sql=kEmptyStr)
	Create and prepare statement for given database connection. More...

	CSQLITE_Statement (sqlite3 *conn_handle, CTempString sql=kEmptyStr)
	Create and prepare statement for particular low-level connection. More...

	~CSQLITE_Statement ()

void	SetSql (CTempString sql)
	Change sql text for the object and prepare new statement. More...

void	Bind (int index, int val)
	Bind integer value to parameter index. More...

void	Bind (int index, unsigned int val)
	Bind unsigned integer value to parameter index. More...

void	Bind (int index, long val)
	Bind integer value to parameter index. More...

void	Bind (int index, unsigned long val)
	Bind unsigned integer value to parameter index. More...

void	Bind (int index, Int8 val)
	Bind 64-bit integer value to parameter index. More...

void	Bind (int index, Uint8 val)
	Bind unsigned 64-bit integer value to parameter index. More...

void	Bind (int index, double val)
	Bind double value to parameter index. More...

void	Bind (int index, CTempString val)
	Bind text value to parameter index. More...

void	Bind (int index, const char *data, size_t size)
	Bind text value to parameter index. More...

void	Bind (int index, const void *data, size_t size)
	Bind blob value to parameter index. More...

void	BindZeroedBlob (int index, size_t size)
	Bind blob value of given size containing only zeros to parameter index. More...

void	BindNull (int index)
	Bind null value to parameter index. More...

void	Execute (void)
	Execute statement without returning any result. More...

bool	Step (void)
	Step through results of the statement. More...

void	Reset (void)
	Reset the statement to release all locks and to be ready to execute again. More...

void	ClearBindings (void)
	Reset all bindings to the statement to their initial NULL values. More...

int	GetColumnsCount (void) const
	Get number of columns in result set. More...

CStringUTF8	GetColumnName (int col_ind) const
	Get name of column at index col_ind in result set. More...

int	GetInt (int col_ind) const
	Get integer value from column col_ind in current row. More...

Int8	GetInt8 (int col_ind) const
	Get 64-bit integer value from column col_ind in current row. More...

double	GetDouble (int col_ind) const
	Get double value from column col_ind in current row. More...

string	GetString (int col_ind) const
	Get text value from column col_ind in current row. More...

size_t	GetBlobSize (int col_ind) const
	Get size of blob value from column col_ind in current row. More...

size_t	GetBlob (int col_ind, void *buffer, size_t size) const
	Read blob value from column col_ind in current row. More...

Int8	GetLastInsertedRowid (void) const
	Get rowid of the row inserted in last statement execution. More...

int	GetChangedRowsCount (void) const
	Get number of rows changed during last insert, delete or update statement. More...

Private Member Functions
	CSQLITE_Statement (const CSQLITE_Statement &)

CSQLITE_Statement &	operator= (const CSQLITE_Statement &)

void	x_Prepare (CTempString sql)
	Prepare new statement if it's not empty. More...

void	x_Finalize (void)
	Finalize current statement. More...

Private Attributes
CSQLITE_Connection *	m_Conn
	Connection this statement belongs to. More...

sqlite3 *	m_ConnHandle
	Low-level connection handle provided for this statement. More...

sqlite3_stmt *	m_StmtHandle
	Low-level statement handle. More...

Detailed Description

SQL statement executing on SQLite database.

Definition at line 360 of file sqlitewrapp.hpp.

Constructor & Destructor Documentation

◆ CSQLITE_Statement() [1/3]

CSQLITE_Statement::CSQLITE_Statement	(	CSQLITE_Connection *	conn,
		CTempString	sql = `kEmptyStr`
	)

inline

Create and prepare statement for given database connection.

If sql is empty nothing is prepared in the constructor.

Definition at line 700 of file sqlitewrapp.hpp.

References sql, and x_Prepare().

◆ CSQLITE_Statement() [2/3]

CSQLITE_Statement::CSQLITE_Statement	(	sqlite3 *	conn_handle,
		CTempString	sql = `kEmptyStr`
	)

inline

Create and prepare statement for particular low-level connection.

If sql is empty nothing is prepared in the constructor.

Definition at line 710 of file sqlitewrapp.hpp.

References sql, and x_Prepare().

◆ ~CSQLITE_Statement()

CSQLITE_Statement::~CSQLITE_Statement ( void )

Definition at line 649 of file sqlitewrapp.cpp.

References m_Conn, m_ConnHandle, STD_CATCH_ALL_X, CSQLITE_Connection::UnlockHandle(), and x_Finalize().

◆ CSQLITE_Statement() [3/3]

CSQLITE_Statement::CSQLITE_Statement ( const CSQLITE_Statement & )

private

Member Function Documentation

◆ Bind() [1/10]

void CSQLITE_Statement::Bind	(	int	index,
		const char *	data,
		size_t	size
	)

Bind text value to parameter index.

Parameters' numbers start from 1. Value of parameter is not copied, pointer is remembered instead. So given value should exist until statement is executed.

Definition at line 735 of file sqlitewrapp.cpp.

References data, ncbi::grid::netcache::search::fields::size, STMT_BIND3, and text().

◆ Bind() [2/10]

void CSQLITE_Statement::Bind	(	int	index,
		const void *	data,
		size_t	size
	)

Bind blob value to parameter index.

Parameters' numbers start from 1. Value of parameter is not copied, pointer is remembered instead. So given value should exist until statement is executed.

Definition at line 741 of file sqlitewrapp.cpp.

References data, ncbi::grid::netcache::search::fields::size, and STMT_BIND3.

◆ Bind() [3/10]

void CSQLITE_Statement::Bind	(	int	index,
		CTempString	val
	)

Bind text value to parameter index.

Parameters' numbers start from 1. Value of parameter is copied inside the method so it may disappear after call.

Definition at line 728 of file sqlitewrapp.cpp.

References STMT_BIND3, text(), and val.

◆ Bind() [4/10]

void CSQLITE_Statement::Bind	(	int	index,
		double	val
	)

Bind double value to parameter index.

Parameters' numbers start from 1.

Definition at line 722 of file sqlitewrapp.cpp.

References STMT_BIND, and val.

◆ Bind() [5/10]

void CSQLITE_Statement::Bind	(	int	index,
		int	val
	)

inline

Bind integer value to parameter index.

Parameters' numbers start from 1.

Definition at line 757 of file sqlitewrapp.hpp.

References val.

Referenced by CLDS2_Database::AddAnnot(), CLDS2_Database::AddBioseq(), Bind(), CGenomicCollectionsService::GetAssembly(), CSQLITE_Blob::Write(), and CLocalTaxon::x_Cache().

◆ Bind() [6/10]

void CSQLITE_Statement::Bind	(	int	index,
		Int8	val
	)

Bind 64-bit integer value to parameter index.

Parameters' numbers start from 1.

Definition at line 716 of file sqlitewrapp.cpp.

References STMT_BIND, and val.

◆ Bind() [7/10]

void CSQLITE_Statement::Bind	(	int	index,
		long	val
	)

inline

Bind integer value to parameter index.

Parameters' numbers start from 1.

Definition at line 743 of file sqlitewrapp.hpp.

References Bind(), and val.

◆ Bind() [8/10]

void CSQLITE_Statement::Bind	(	int	index,
		Uint8	val
	)

inline

Bind unsigned 64-bit integer value to parameter index.

Parameters' numbers start from 1.

Definition at line 734 of file sqlitewrapp.hpp.

References Bind(), and val.

◆ Bind() [9/10]

void CSQLITE_Statement::Bind	(	int	index,
		unsigned int	val
	)

inline

Bind unsigned integer value to parameter index.

Parameters' numbers start from 1.

Definition at line 763 of file sqlitewrapp.hpp.

References Bind(), and val.

◆ Bind() [10/10]

void CSQLITE_Statement::Bind	(	int	index,
		unsigned long	val
	)

inline

Bind unsigned integer value to parameter index.

Parameters' numbers start from 1.

Definition at line 749 of file sqlitewrapp.hpp.

References Bind(), and val.

◆ BindNull()

void CSQLITE_Statement::BindNull ( int index )

Bind null value to parameter index.

Definition at line 753 of file sqlitewrapp.cpp.

References NULL, and STMT_BIND_NO_VAL.

Referenced by CLDS2_Database::AddAnnot().

◆ BindZeroedBlob()

void CSQLITE_Statement::BindZeroedBlob	(	int	index,
		size_t	size
	)

Bind blob value of given size containing only zeros to parameter index.

Parameters' numbers start from 1.

Definition at line 747 of file sqlitewrapp.cpp.

References ncbi::grid::netcache::search::fields::size, and STMT_BIND.

◆ ClearBindings()

void CSQLITE_Statement::ClearBindings ( void )

Reset all bindings to the statement to their initial NULL values.

Definition at line 784 of file sqlitewrapp.cpp.

References _ASSERT, m_ConnHandle, m_StmtHandle, and SQLITE_SAFE_CALL.

◆ Execute()

void CSQLITE_Statement::Execute ( void )

inline

Execute statement without returning any result.

Definition at line 727 of file sqlitewrapp.hpp.

References Step().

Referenced by CLDS2_Database::AddAnnot(), CLDS2_Database::AddBioseq(), CSQLITE_Blob::Write(), and CLocalTaxon::x_Cache().

◆ GetBlob()

size_t CSQLITE_Statement::GetBlob	(	int	col_ind,
		void *	buffer,
		size_t	size
	)		const

Read blob value from column col_ind in current row.

The leftmost column of result set has the index 0. Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Parameters

col_ind	Index of column to read (left-most is 0)
buffer	Pointer to buffer where to write the data
size	Size of buffer available for writing

Returns: Number of bytes read from result set and put into buffer

Definition at line 827 of file sqlitewrapp.cpp.

References _ASSERT, buf, buffer, m_StmtHandle, min(), and ncbi::grid::netcache::search::fields::size.

◆ GetBlobSize()

size_t CSQLITE_Statement::GetBlobSize ( int col_ind ) const

Get size of blob value from column col_ind in current row.

The leftmost column of result set has the index 0. Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Definition at line 821 of file sqlitewrapp.cpp.

References m_StmtHandle.

◆ GetChangedRowsCount()

int CSQLITE_Statement::GetChangedRowsCount ( void ) const

inline

Get number of rows changed during last insert, delete or update statement.

Number does not include rows changed by triggers or by any other indirect means. If called when no insert, update or delete statement was executed result is undefined.

Definition at line 804 of file sqlitewrapp.hpp.

References _ASSERT, and m_ConnHandle.

◆ GetColumnName()

CStringUTF8 CSQLITE_Statement::GetColumnName ( int col_ind ) const

Get name of column at index col_ind in result set.

The leftmost column of result set has the index 0. Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Definition at line 797 of file sqlitewrapp.cpp.

References _ASSERT, CUtf8::AsUTF8(), eEncoding_UTF8, CSQLITE_Exception::eUnknown, m_ConnHandle, m_StmtHandle, result, and SQLITE_THROW.

◆ GetColumnsCount()

int CSQLITE_Statement::GetColumnsCount ( void ) const

inline

Get number of columns in result set.

Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Definition at line 769 of file sqlitewrapp.hpp.

References _ASSERT, and m_StmtHandle.

◆ GetDouble()

double CSQLITE_Statement::GetDouble ( int col_ind ) const

inline

Get double value from column col_ind in current row.

The leftmost column of result set has the index 0. Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Definition at line 790 of file sqlitewrapp.hpp.

References _ASSERT, and m_StmtHandle.

◆ GetInt()

int CSQLITE_Statement::GetInt ( int col_ind ) const

inline

Get integer value from column col_ind in current row.

The leftmost column of result set has index 0. Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Definition at line 776 of file sqlitewrapp.hpp.

References _ASSERT, and m_StmtHandle.

◆ GetInt8()

Int8 CSQLITE_Statement::GetInt8 ( int col_ind ) const

inline

Get 64-bit integer value from column col_ind in current row.

The leftmost column of result set has the index 0. Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Definition at line 783 of file sqlitewrapp.hpp.

References _ASSERT, and m_StmtHandle.

◆ GetLastInsertedRowid()

Int8 CSQLITE_Statement::GetLastInsertedRowid ( void ) const

inline

Get rowid of the row inserted in last statement execution.

If connection is working in eExternalMT mode then method should be called after statement execution and before execution of any other statement in the same connection. If last executed statement was not insert then 0 is returned.

Definition at line 797 of file sqlitewrapp.hpp.

References _ASSERT, and m_ConnHandle.

Referenced by CLDS2_Database::AddAnnot(), and CLDS2_Database::AddBioseq().

◆ GetString()

string CSQLITE_Statement::GetString ( int col_ind ) const

Get text value from column col_ind in current row.

The leftmost column of result set has the index 0. Method should be executed only after Step() returned TRUE, otherwise returned value is undefined.

Definition at line 809 of file sqlitewrapp.cpp.

References _ASSERT, buf, m_StmtHandle, result, and ncbi::grid::netcache::search::fields::size.

Referenced by CGenomicCollectionsService::GetAssembly(), and CLocalTaxon::x_Cache().

◆ operator=()

CSQLITE_Statement& CSQLITE_Statement::operator= ( const CSQLITE_Statement & )

private

◆ Reset()

void CSQLITE_Statement::Reset ( void )

Reset the statement to release all locks and to be ready to execute again.

Definition at line 771 of file sqlitewrapp.cpp.

References _ASSERT, m_ConnHandle, m_StmtHandle, and SQLITE_SAFE_CALL.

Referenced by CLDS2_Database::AddAnnot(), CLDS2_Database::AddBioseq(), SLDS2_File::SLDS2_File(), CSQLITE_Blob::Write(), CLDS2_Database::x_GetStatement(), and CSQLITE_StatementLock::~CSQLITE_StatementLock().

◆ SetSql()

void CSQLITE_Statement::SetSql ( CTempString sql )

inline

Change sql text for the object and prepare new statement.

Definition at line 720 of file sqlitewrapp.hpp.

References sql, x_Finalize(), and x_Prepare().

◆ Step()

bool CSQLITE_Statement::Step ( void )

Step through results of the statement.

If statement wasn't executed yet it starts executing. If statement already returned some rows then it moves to the next row. Be aware that when statement begins executing until it returns all rows or is reseted the database is locked so that nobody else can write to it. So it's recommended to step through all results as quick as possible.

Returns: TRUE if new row is available in the result. FALSE if no more rows are available and thus statement finished executing and released all locks held.

Definition at line 759 of file sqlitewrapp.cpp.

References _ASSERT, m_ConnHandle, m_StmtHandle, and SQLITE_SAFE_CALL_EX.

Referenced by Execute(), CGenomicCollectionsService::GetAssembly(), and CLocalTaxon::x_Cache().

◆ x_Finalize()

void CSQLITE_Statement::x_Finalize ( void )

private

Finalize current statement.

Definition at line 681 of file sqlitewrapp.cpp.

References m_ConnHandle, m_StmtHandle, and SQLITE_SAFE_CALL.

Referenced by SetSql(), and ~CSQLITE_Statement().

◆ x_Prepare()

void CSQLITE_Statement::x_Prepare ( CTempString sql )

private

Prepare new statement if it's not empty.

Definition at line 662 of file sqlitewrapp.cpp.

References _ASSERT, CSQLITE_Connection::LockHandle(), m_Conn, m_ConnHandle, m_StmtHandle, NULL, sql, and SQLITE_SAFE_CALL.

Referenced by CSQLITE_Statement(), and SetSql().

Member Data Documentation

◆ m_Conn

CSQLITE_Connection* CSQLITE_Statement::m_Conn

private

Connection this statement belongs to.

Definition at line 503 of file sqlitewrapp.hpp.

Referenced by x_Prepare(), and ~CSQLITE_Statement().

◆ m_ConnHandle

sqlite3* CSQLITE_Statement::m_ConnHandle

private

Low-level connection handle provided for this statement.

Definition at line 505 of file sqlitewrapp.hpp.

Referenced by ClearBindings(), GetChangedRowsCount(), GetColumnName(), GetLastInsertedRowid(), Reset(), Step(), x_Finalize(), x_Prepare(), and ~CSQLITE_Statement().

◆ m_StmtHandle

sqlite3_stmt* CSQLITE_Statement::m_StmtHandle

private

Low-level statement handle.

Definition at line 507 of file sqlitewrapp.hpp.

Referenced by ClearBindings(), GetBlob(), GetBlobSize(), GetColumnName(), GetColumnsCount(), GetDouble(), GetInt(), GetInt8(), GetString(), Reset(), Step(), x_Finalize(), and x_Prepare().

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

include/db/sqlite/sqlitewrapp.hpp
src/db/sqlite/sqlitewrapp.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CSQLITE_Statement() [1/3]

◆ CSQLITE_Statement() [2/3]

◆ ~CSQLITE_Statement()

◆ CSQLITE_Statement() [3/3]

Member Function Documentation

◆ Bind() [1/10]

◆ Bind() [2/10]

◆ Bind() [3/10]

◆ Bind() [4/10]

◆ Bind() [5/10]

◆ Bind() [6/10]

◆ Bind() [7/10]

◆ Bind() [8/10]

◆ Bind() [9/10]

◆ Bind() [10/10]

◆ BindNull()

◆ BindZeroedBlob()

◆ ClearBindings()

◆ Execute()

◆ GetBlob()

◆ GetBlobSize()

◆ GetChangedRowsCount()

◆ GetColumnName()

◆ GetColumnsCount()

◆ GetDouble()

◆ GetInt()

◆ GetInt8()

◆ GetLastInsertedRowid()

◆ GetString()

◆ operator=()

◆ Reset()

◆ SetSql()

◆ Step()

◆ x_Finalize()

◆ x_Prepare()

Member Data Documentation

◆ m_Conn

◆ m_ConnHandle

◆ m_StmtHandle