Prepares, executes, and fetches SQL statements against a Firebird attachment. More...

#include <Statement.h>

Inheritance diagram for fbcpp::Statement:

Collaboration diagram for fbcpp::Statement:

Public Member Functions
	Statement (Attachment &attachment, Transaction &transaction, std::string_view sql, const StatementOptions &options={})
	Prepares an SQL statement.

	Statement (Statement &&o) noexcept
	Transfers ownership of an existing prepared statement.

Statement &	operator= (Statement &&o) noexcept
	Transfers ownership of another prepared statement into this one.

	Statement (const Statement &)=delete

Statement &	operator= (const Statement &)=delete

	~Statement () noexcept
	Releases resources; ignores failures to keep destructor noexcept.

void	free ()
	Releases the prepared handle and any associated result set.

std::string	getLegacyPlan ()
	Retrieves the textual legacy plan if the server produced one.

std::string	getPlan ()
	Retrieves the structured textual plan if the server produced one.

bool	execute (Transaction &transaction)
	Executes a prepared statement using the supplied transaction.

template<typename T >
T	get (unsigned index)
	Retrieves a column using the most appropriate typed accessor specialization.

template<Aggregate T>
T	get ()
	Retrieves all output columns into a user-defined aggregate struct.

template<TupleLike T>
T	get ()
	Retrieves all output columns into a tuple-like type.

template<VariantLike V>
V	get (unsigned index)
	Retrieves a column value as a user-defined variant type.

Handle accessors
Reports whether the statement currently owns a prepared handle.
Attachment &	getAttachment () noexcept
	Returns the Attachment object reference used to create this Statement.

bool	isValid () noexcept
	Returns whether the Statement object is valid.

bool	hasCurrentRow () const noexcept
	Returns whether the statement is positioned on a current output row.

FbRef< fb::IStatement >	getStatementHandle () noexcept
	Provides direct access to the underlying Firebird statement handle.

FbRef< fb::IResultSet >	getResultSetHandle () noexcept
	Provides access to the underlying Firebird currently open result set handle, if any.

FbRef< fb::IMessageMetadata >	getInputMetadata () noexcept
	Returns the metadata describing prepared input parameters.

std::vector< std::byte > &	getInputMessage () noexcept
	Provides direct access to the raw input message buffer.

FbRef< fb::IMessageMetadata >	getOutputMetadata () noexcept
	Returns the metadata describing columns produced by the statement.

std::vector< std::byte > &	getOutputMessage () noexcept
	Provides direct access to the raw output message buffer.

StatementType	getType () noexcept
	Returns the type classification reported by the server.

Descriptor accessors
Provides cached descriptors for each input parameter.
const std::vector< Descriptor > &	getInputDescriptors () noexcept
	Provides cached descriptors for each input column.

const std::vector< Descriptor > &	getOutputDescriptors () noexcept
	Provides cached descriptors for each output column.

Cursor movement
bool	fetchNext ()
	Fetches the next row in the current result set.

bool	fetchPrior ()
	Fetches the previous row in the current result set.

bool	fetchFirst ()
	Positions the cursor on the first row.

bool	fetchLast ()
	Positions the cursor on the last row.

bool	fetchAbsolute (unsigned position)
	Positions the cursor on the given absolute row number.

bool	fetchRelative (int offset)
	Moves the cursor by the requested relative offset.

Result reading
bool	isNull (unsigned index)
	Reports whether the most recently fetched row has a null at the given column.

std::optional< bool >	getBool (unsigned index)
	Reads a boolean column from the current row.

std::optional< std::int16_t >	getInt16 (unsigned index)
	Reads a 16-bit signed integer column.

std::optional< ScaledInt16 >	getScaledInt16 (unsigned index)
	Reads a scaled 16-bit signed integer column.

std::optional< std::int32_t >	getInt32 (unsigned index)
	Reads a 32-bit signed integer column.

std::optional< ScaledInt32 >	getScaledInt32 (unsigned index)
	Reads a scaled 32-bit signed integer column.

std::optional< std::int64_t >	getInt64 (unsigned index)
	Reads a 64-bit signed integer column.

std::optional< ScaledInt64 >	getScaledInt64 (unsigned index)
	Reads a scaled 64-bit signed integer column.

std::optional< ScaledOpaqueInt128 >	getScaledOpaqueInt128 (unsigned index)
	Reads a Firebird scaled 128-bit integer column.

std::optional< BoostInt128 >	getBoostInt128 (unsigned index)
	Reads a Boost 128-bit integer column.

std::optional< ScaledBoostInt128 >	getScaledBoostInt128 (unsigned index)
	Reads a scaled Boost 128-bit integer column.

std::optional< float >	getFloat (unsigned index)
	Reads a single precision floating-point column.

std::optional< double >	getDouble (unsigned index)
	Reads a double precision floating-point column.

std::optional< OpaqueDecFloat16 >	getOpaqueDecFloat16 (unsigned index)
	Reads a Firebird 16-digit decimal floating-point column.

std::optional< BoostDecFloat16 >	getBoostDecFloat16 (unsigned index)
	Reads a Boost-based 16-digit decimal floating-point column.

std::optional< BoostDecimal32 >	getBoostDecimal32 (unsigned index)
	Reads a Boost.Decimal 7-digit decimal floating-point column.

std::optional< BoostDecimal64 >	getBoostDecimal64 (unsigned index)
	Reads a Boost.Decimal 16-digit decimal floating-point column.

std::optional< OpaqueDecFloat34 >	getOpaqueDecFloat34 (unsigned index)
	Reads a Firebird 34-digit decimal floating-point column.

std::optional< BoostDecFloat34 >	getBoostDecFloat34 (unsigned index)
	Reads a Boost-based 34-digit decimal floating-point column.

std::optional< BoostDecimal128 >	getBoostDecimal128 (unsigned index)
	Reads a Boost.Decimal 34-digit decimal floating-point column.

std::optional< Date >	getDate (unsigned index)
	Reads a date column.

std::optional< OpaqueDate >	getOpaqueDate (unsigned index)
	Reads a raw date column in Firebird's representation.

std::optional< Time >	getTime (unsigned index)
	Reads a time-of-day column without timezone.

std::optional< OpaqueTime >	getOpaqueTime (unsigned index)
	Reads a raw time-of-day column in Firebird's representation.

std::optional< Timestamp >	getTimestamp (unsigned index)
	Reads a timestamp column without timezone.

std::optional< OpaqueTimestamp >	getOpaqueTimestamp (unsigned index)
	Reads a raw timestamp column in Firebird's representation.

std::optional< TimeTz >	getTimeTz (unsigned index)
	Reads a time-of-day column with timezone.

std::optional< OpaqueTimeTz >	getOpaqueTimeTz (unsigned index)
	Reads a raw time-of-day column with timezone in Firebird's representation.

std::optional< TimestampTz >	getTimestampTz (unsigned index)
	Reads a timestamp-with-time-zone column.

std::optional< OpaqueTimestampTz >	getOpaqueTimestampTz (unsigned index)
	Reads a raw timestamp-with-time-zone column in Firebird's representation.

std::optional< BlobId >	getBlobId (unsigned index)
	Reads a blob identifier column.

std::optional< ArrayId >	getArrayId (unsigned index)
	Reads an array identifier column.

std::optional< std::string >	getString (unsigned index)
	Reads a textual column, applying number-to-string conversions when needed.

std::optional< std::vector< std::byte > >	getBytes (unsigned index)
	Reads a text or varying column as its raw bytes.

Friends
class	RowSet

class	impl::ParameterSetter< Statement, false >

Detailed Description

Prepares, executes, and fetches SQL statements against a Firebird attachment.

Definition at line 145 of file Statement.h.

Constructor & Destructor Documentation

◆ Statement() [1/2]

Statement::Statement	(	Attachment &	attachment,
		Transaction &	transaction,
		std::string_view	sql,
		const StatementOptions &	options = `{}`
	)

explicit

Prepares an SQL statement.

attachment supplies the database connection. transaction is used for statement preparation. sql is the text to prepare. options provides fine-grained prepare controls.

Definition at line 34 of file Statement.cpp.

◆ Statement() [2/2]

Statement::Statement ( Statement && o )

noexcept

Transfers ownership of an existing prepared statement.

Definition at line 184 of file Statement.cpp.

◆ ~Statement()

fbcpp::Statement::~Statement ( )

inlinenoexcept

Releases resources; ignores failures to keep destructor noexcept.

Definition at line 180 of file Statement.h.

Member Function Documentation

◆ execute()

bool Statement::execute ( Transaction & transaction )

Executes a prepared statement using the supplied transaction.

Parameters

transaction Transaction that will own the execution context.

Returns: true when execution yields a record.

Definition at line 263 of file Statement.cpp.

◆ fetchAbsolute()

bool Statement::fetchAbsolute ( unsigned position )

Positions the cursor on the given absolute row number.

Definition at line 342 of file Statement.cpp.

◆ fetchFirst()

bool Statement::fetchFirst ( )

Positions the cursor on the first row.

Definition at line 324 of file Statement.cpp.

◆ fetchLast()

bool Statement::fetchLast ( )

Positions the cursor on the last row.

Definition at line 333 of file Statement.cpp.

◆ fetchNext()

bool Statement::fetchNext ( )

Fetches the next row in the current result set.

Definition at line 306 of file Statement.cpp.

◆ fetchPrior()

bool Statement::fetchPrior ( )

Fetches the previous row in the current result set.

Definition at line 315 of file Statement.cpp.

◆ fetchRelative()

bool Statement::fetchRelative ( int offset )

Moves the cursor by the requested relative offset.

Definition at line 352 of file Statement.cpp.

◆ free()

void Statement::free ( )

Releases the prepared handle and any associated result set.

Definition at line 234 of file Statement.cpp.

◆ get() [1/4]

template<Aggregate T>

T fbcpp::Statement::get ( )

inline

Retrieves all output columns into a user-defined aggregate struct.

Template Parameters

T	An aggregate type whose fields match the output column count and types.

Returns: The populated struct with values from the current row.

Exceptions

FbCppException	if field count mismatches output column count.
FbCppException	if a NULL value is encountered for a non-optional field.

Definition at line 770 of file Statement.h.

◆ get() [2/4]

template<TupleLike T>

T fbcpp::Statement::get ( )

inline

Retrieves all output columns into a tuple-like type.

Template Parameters

T	A tuple-like type (std::tuple, std::pair) whose elements match the output column count and types.

Returns: The populated tuple with values from the current row.

Exceptions

FbCppException	if element count mismatches output column count.
FbCppException	if a NULL value is encountered for a non-optional element.

Definition at line 784 of file Statement.h.

◆ get() [3/4]

template<typename T >

T fbcpp::Statement::get ( unsigned index )

inline

Retrieves a column using the most appropriate typed accessor specialization.

Definition at line 756 of file Statement.h.

◆ get() [4/4]

template<VariantLike V>

V fbcpp::Statement::get ( unsigned index )

inline

Retrieves a column value as a user-defined variant type.

Template Parameters

V	A std::variant type with possible C++ types. Use std::monostate for NULL.

Parameters

index Zero-based column index.

Returns: The variant with column value, or std::monostate if NULL.

Exceptions

FbCppException	if NULL but variant lacks std::monostate.
FbCppException	if SQL type cannot convert to any alternative.

Definition at line 799 of file Statement.h.

◆ getArrayId()

std::optional< ArrayId > fbcpp::Statement::getArrayId ( unsigned index )

inline

Reads an array identifier column.

Definition at line 724 of file Statement.h.

◆ getAttachment()

Attachment & fbcpp::Statement::getAttachment ( )

inlinenoexcept

Returns the Attachment object reference used to create this Statement.

Definition at line 205 of file Statement.h.

◆ getBlobId()

std::optional< BlobId > fbcpp::Statement::getBlobId ( unsigned index )

inline

Reads a blob identifier column.

Definition at line 715 of file Statement.h.

◆ getBool()

std::optional< bool > fbcpp::Statement::getBool ( unsigned index )

inline

Reads a boolean column from the current row.

Definition at line 444 of file Statement.h.

◆ getBoostDecFloat16()

std::optional< BoostDecFloat16 > fbcpp::Statement::getBoostDecFloat16 ( unsigned index )

inline

Reads a Boost-based 16-digit decimal floating-point column.

Definition at line 564 of file Statement.h.

◆ getBoostDecFloat34()

std::optional< BoostDecFloat34 > fbcpp::Statement::getBoostDecFloat34 ( unsigned index )

inline

Reads a Boost-based 34-digit decimal floating-point column.

Definition at line 604 of file Statement.h.

◆ getBoostDecimal128()

std::optional< BoostDecimal128 > fbcpp::Statement::getBoostDecimal128 ( unsigned index )

inline

Reads a Boost.Decimal 34-digit decimal floating-point column.

Definition at line 615 of file Statement.h.

◆ getBoostDecimal32()

std::optional< BoostDecimal32 > fbcpp::Statement::getBoostDecimal32 ( unsigned index )

inline

Reads a Boost.Decimal 7-digit decimal floating-point column.

Definition at line 575 of file Statement.h.

◆ getBoostDecimal64()

std::optional< BoostDecimal64 > fbcpp::Statement::getBoostDecimal64 ( unsigned index )

inline

Reads a Boost.Decimal 16-digit decimal floating-point column.

Definition at line 584 of file Statement.h.

◆ getBoostInt128()

std::optional< BoostInt128 > fbcpp::Statement::getBoostInt128 ( unsigned index )

inline

Reads a Boost 128-bit integer column.

Definition at line 517 of file Statement.h.

◆ getBytes()

std::optional< std::vector< std::byte > > fbcpp::Statement::getBytes ( unsigned index )

inline

Reads a text or varying column as its raw bytes.

Definition at line 742 of file Statement.h.

◆ getDate()

std::optional< Date > fbcpp::Statement::getDate ( unsigned index )

inline

Reads a date column.

Definition at line 625 of file Statement.h.

◆ getDouble()

std::optional< double > fbcpp::Statement::getDouble ( unsigned index )

inline

Reads a double precision floating-point column.

Definition at line 545 of file Statement.h.

◆ getFloat()

std::optional< float > fbcpp::Statement::getFloat ( unsigned index )

inline

Reads a single precision floating-point column.

Definition at line 536 of file Statement.h.

◆ getInputDescriptors()

const std::vector< Descriptor > & fbcpp::Statement::getInputDescriptors ( )

inlinenoexcept

Provides cached descriptors for each input column.

Definition at line 300 of file Statement.h.

◆ getInputMessage()

std::vector< std::byte > & fbcpp::Statement::getInputMessage ( )

inlinenoexcept

Provides direct access to the raw input message buffer.

Definition at line 258 of file Statement.h.

◆ getInputMetadata()

FbRef< fb::IMessageMetadata > fbcpp::Statement::getInputMetadata ( )

inlinenoexcept

Returns the metadata describing prepared input parameters.

Definition at line 250 of file Statement.h.

◆ getInt16()

std::optional< std::int16_t > fbcpp::Statement::getInt16 ( unsigned index )

inline

Reads a 16-bit signed integer column.

Definition at line 453 of file Statement.h.

◆ getInt32()

std::optional< std::int32_t > fbcpp::Statement::getInt32 ( unsigned index )

inline

Reads a 32-bit signed integer column.

Definition at line 471 of file Statement.h.

◆ getInt64()

std::optional< std::int64_t > fbcpp::Statement::getInt64 ( unsigned index )

inline

Reads a 64-bit signed integer column.

Definition at line 489 of file Statement.h.

◆ getLegacyPlan()

std::string Statement::getLegacyPlan ( )

Retrieves the textual legacy plan if the server produced one.

Definition at line 249 of file Statement.cpp.

◆ getOpaqueDate()

std::optional< OpaqueDate > fbcpp::Statement::getOpaqueDate ( unsigned index )

inline

Reads a raw date column in Firebird's representation.

Definition at line 634 of file Statement.h.

◆ getOpaqueDecFloat16()

std::optional< OpaqueDecFloat16 > fbcpp::Statement::getOpaqueDecFloat16 ( unsigned index )

inline

Reads a Firebird 16-digit decimal floating-point column.

Definition at line 554 of file Statement.h.

◆ getOpaqueDecFloat34()

std::optional< OpaqueDecFloat34 > fbcpp::Statement::getOpaqueDecFloat34 ( unsigned index )

inline

Reads a Firebird 34-digit decimal floating-point column.

Definition at line 594 of file Statement.h.

◆ getOpaqueTime()

std::optional< OpaqueTime > fbcpp::Statement::getOpaqueTime ( unsigned index )

inline

Reads a raw time-of-day column in Firebird's representation.

Definition at line 652 of file Statement.h.

◆ getOpaqueTimestamp()

std::optional< OpaqueTimestamp > fbcpp::Statement::getOpaqueTimestamp ( unsigned index )

inline

Reads a raw timestamp column in Firebird's representation.

Definition at line 670 of file Statement.h.

◆ getOpaqueTimestampTz()

std::optional< OpaqueTimestampTz > fbcpp::Statement::getOpaqueTimestampTz ( unsigned index )

inline

Reads a raw timestamp-with-time-zone column in Firebird's representation.

Definition at line 706 of file Statement.h.

◆ getOpaqueTimeTz()

std::optional< OpaqueTimeTz > fbcpp::Statement::getOpaqueTimeTz ( unsigned index )

inline

Reads a raw time-of-day column with timezone in Firebird's representation.

Definition at line 688 of file Statement.h.

◆ getOutputDescriptors()

const std::vector< Descriptor > & fbcpp::Statement::getOutputDescriptors ( )

inlinenoexcept

Provides cached descriptors for each output column.

Definition at line 308 of file Statement.h.

◆ getOutputMessage()

std::vector< std::byte > & fbcpp::Statement::getOutputMessage ( )

inlinenoexcept

Provides direct access to the raw output message buffer.

Definition at line 274 of file Statement.h.

◆ getOutputMetadata()

FbRef< fb::IMessageMetadata > fbcpp::Statement::getOutputMetadata ( )

inlinenoexcept

Returns the metadata describing columns produced by the statement.

Definition at line 266 of file Statement.h.

◆ getPlan()

std::string Statement::getPlan ( )

Retrieves the structured textual plan if the server produced one.

Definition at line 256 of file Statement.cpp.

◆ getResultSetHandle()

FbRef< fb::IResultSet > fbcpp::Statement::getResultSetHandle ( )

inlinenoexcept

Provides access to the underlying Firebird currently open result set handle, if any.

Returns: Smart pointer to the active result set interface.

Definition at line 242 of file Statement.h.

◆ getScaledBoostInt128()

std::optional< ScaledBoostInt128 > fbcpp::Statement::getScaledBoostInt128 ( unsigned index )

inline

Reads a scaled Boost 128-bit integer column.

Definition at line 526 of file Statement.h.

◆ getScaledInt16()

std::optional< ScaledInt16 > fbcpp::Statement::getScaledInt16 ( unsigned index )

inline

Reads a scaled 16-bit signed integer column.

Definition at line 462 of file Statement.h.

◆ getScaledInt32()

std::optional< ScaledInt32 > fbcpp::Statement::getScaledInt32 ( unsigned index )

inline

Reads a scaled 32-bit signed integer column.

Definition at line 480 of file Statement.h.

◆ getScaledInt64()

std::optional< ScaledInt64 > fbcpp::Statement::getScaledInt64 ( unsigned index )

inline

Reads a scaled 64-bit signed integer column.

Definition at line 498 of file Statement.h.

◆ getScaledOpaqueInt128()

std::optional< ScaledOpaqueInt128 > fbcpp::Statement::getScaledOpaqueInt128 ( unsigned index )

inline

Reads a Firebird scaled 128-bit integer column.

Definition at line 507 of file Statement.h.

◆ getStatementHandle()

FbRef< fb::IStatement > fbcpp::Statement::getStatementHandle ( )

inlinenoexcept

Provides direct access to the underlying Firebird statement handle.

Returns: Smart pointer to the low-level fb::IStatement interface.

Definition at line 233 of file Statement.h.

◆ getString()

std::optional< std::string > fbcpp::Statement::getString ( unsigned index )

inline

Reads a textual column, applying number-to-string conversions when needed.

Definition at line 733 of file Statement.h.

◆ getTime()

std::optional< Time > fbcpp::Statement::getTime ( unsigned index )

inline

Reads a time-of-day column without timezone.

Definition at line 643 of file Statement.h.

◆ getTimestamp()

std::optional< Timestamp > fbcpp::Statement::getTimestamp ( unsigned index )

inline

Reads a timestamp column without timezone.

Definition at line 661 of file Statement.h.

◆ getTimestampTz()

std::optional< TimestampTz > fbcpp::Statement::getTimestampTz ( unsigned index )

inline

Reads a timestamp-with-time-zone column.

Definition at line 697 of file Statement.h.

◆ getTimeTz()

std::optional< TimeTz > fbcpp::Statement::getTimeTz ( unsigned index )

inline

Reads a time-of-day column with timezone.

Definition at line 679 of file Statement.h.

◆ getType()

StatementType fbcpp::Statement::getType ( )

inlinenoexcept

Returns the type classification reported by the server.

Definition at line 282 of file Statement.h.

◆ hasCurrentRow()

bool fbcpp::Statement::hasCurrentRow ( ) const

inlinenoexcept

Returns whether the statement is positioned on a current output row.

A current row is present after a successful execute() or fetch that produced output, until the row is consumed by RowSet or replaced by a later fetch.

Definition at line 224 of file Statement.h.

◆ isNull()

bool fbcpp::Statement::isNull ( unsigned index )

inline

Reports whether the most recently fetched row has a null at the given column.

Definition at line 435 of file Statement.h.

◆ isValid()

bool fbcpp::Statement::isValid ( )

inlinenoexcept

Returns whether the Statement object is valid.

Definition at line 213 of file Statement.h.

◆ operator=()

Statement & Statement::operator= ( Statement && o )

noexcept

Transfers ownership of another prepared statement into this one.

The old handles are released via FbRef::operator=(FbRef&&). After the assignment, this is valid (with o's state) and o is invalid.

Definition at line 206 of file Statement.cpp.

Friends And Related Symbol Documentation

◆ impl::ParameterSetter< Statement, false >

friend class impl::ParameterSetter< Statement, false >

friend

Definition at line 147 of file Statement.h.

◆ RowSet

friend class RowSet

friend

Definition at line 147 of file Statement.h.

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

src/fb-cpp/Statement.h
src/fb-cpp/Statement.cpp

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Statement() [1/2]

◆ Statement() [2/2]

◆ ~Statement()

Member Function Documentation

◆ execute()

◆ fetchAbsolute()

◆ fetchFirst()

◆ fetchLast()

◆ fetchNext()

◆ fetchPrior()

◆ fetchRelative()

◆ free()

◆ get() [1/4]

◆ get() [2/4]

◆ get() [3/4]

◆ get() [4/4]

◆ getArrayId()

◆ getAttachment()

◆ getBlobId()

◆ getBool()

◆ getBoostDecFloat16()

◆ getBoostDecFloat34()

◆ getBoostDecimal128()

◆ getBoostDecimal32()

◆ getBoostDecimal64()

◆ getBoostInt128()

◆ getBytes()

◆ getDate()

◆ getDouble()

◆ getFloat()

◆ getInputDescriptors()

◆ getInputMessage()

◆ getInputMetadata()

◆ getInt16()

◆ getInt32()

◆ getInt64()

◆ getLegacyPlan()

◆ getOpaqueDate()

◆ getOpaqueDecFloat16()

◆ getOpaqueDecFloat34()

◆ getOpaqueTime()

◆ getOpaqueTimestamp()

◆ getOpaqueTimestampTz()

◆ getOpaqueTimeTz()

◆ getOutputDescriptors()

◆ getOutputMessage()

◆ getOutputMetadata()

◆ getPlan()

◆ getResultSetHandle()

◆ getScaledBoostInt128()

◆ getScaledInt16()

◆ getScaledInt32()

◆ getScaledInt64()

◆ getScaledOpaqueInt128()

◆ getStatementHandle()

◆ getString()

◆ getTime()

◆ getTimestamp()

◆ getTimestampTz()

◆ getTimeTz()

◆ getType()

◆ hasCurrentRow()

◆ isNull()

◆ isValid()

◆ operator=()

Friends And Related Symbol Documentation

◆ impl::ParameterSetter< Statement, false >

◆ RowSet