A resource for managing result sets from statement execution. More...

#include <nanodbc.h>

Public Member Functions
	result () noexcept
	Empty result set.

	~result () noexcept
	Free result set.

	result (const result &rhs) noexcept
	Copy constructor.

	result (result &&rhs) noexcept
	Move constructor.

result &	operator= (result rhs) noexcept
	Assignment.

void	swap (result &rhs) noexcept
	Member swap.

void *	native_statement_handle () const noexcept
	Returns the native ODBC statement handle.

long	rowset_size () const noexcept
	The rowset size for this result set.

long	affected_rows () const
	Number of affected rows by the request or -1 if the affected rows is not available.

bool	has_affected_rows () const
	Reports if number of affected rows is available.

long	rows () const noexcept
	Rows in the current rowset or 0 if the number of rows is not available.

short	columns () const
	Returns the number of columns in a result set.

bool	first ()
	Fetches the first row in the current result set.

bool	last ()
	Fetches the last row in the current result set.

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

bool	async_next (void *event_handle)
	Initiates an asynchronous fetch of the next row in the current result set.

bool	complete_next ()
	Completes a previously-initiated async fetch for next row in the current result set.

bool	prior ()
	Fetches the prior row in the current result set.

bool	move (long row)
	Moves to and fetches the specified row in the current result set.

bool	skip (long rows)
	Skips a number of rows and then fetches the resulting row in the current result set.

unsigned long	position () const
	Returns the row position in the current result set.

bool	at_end () const noexcept
	Returns true if there are no more results in the current result set.

void	unbind ()
	Unbind data buffers for all columns in the result set.

void	unbind (string const &column_name)
	Unbind data buffers for specific columns in the result set.

void	unbind (short column)
	Unbind data buffers for specific columns in the result set.

template<class T >
void	get_ref (short column, T &result) const
	Gets data from the given column of the current rowset.

template<class T >
void	get_ref (short column, T const &fallback, T &result) const
	Gets data from the given column of the current rowset.

template<class T >
void	get_ref (string const &column_name, T &result) const
	Gets data from the given column by name of the current rowset.

template<class T >
void	get_ref (string const &column_name, T const &fallback, T &result) const
	Gets data from the given column by name of the current rowset.

template<class T >
T	get (short column) const
	Gets data from the given column of the current rowset.

template<class T >
T	get (short column, T const &fallback) const
	Gets data from the given column of the current rowset.

template<class T >
T	get (string const &column_name) const
	Gets data from the given column by name of the current rowset.

template<class T >
T	get (string const &column_name, T const &fallback) const
	Gets data from the given column by name of the current rowset.

bool	is_null (short column) const
	Returns true if and only if the given column of the current rowset is null.

bool	is_null (string const &column_name) const
	Returns true if and only if the given column by name of the current rowset is null.

bool	is_bound (short column) const
	Returns true if we have bound a buffer to the given column.

bool	is_bound (string const &column_name) const
	Returns true if we have bound a buffer to the given column.

short	column (string const &column_name) const
	Returns the column number of the specified column name.

string	column_name (short column) const
	Returns the name of the specified column.

long	column_size (short column) const
	Returns the size of the specified column.

long	column_size (string const &column_name) const
	Returns the size of the specified column by name.

int	column_decimal_digits (short column) const
	Returns the number of decimal digits of the specified column.

int	column_decimal_digits (string const &column_name) const
	Returns the number of decimal digits of the specified column by name.

int	column_datatype (short column) const
	Returns a identifying integer value representing the SQL type of this column.

int	column_datatype (string const &column_name) const
	Returns a identifying integer value representing the SQL type of this column by name.

string	column_datatype_name (short column) const
	Returns data source dependent data type name of this column.

string	column_datatype_name (string const &column_name) const
	Returns data source dependent data type name of this column by name.

int	column_c_datatype (short column) const
	Returns a identifying integer value representing the C type of this column.

int	column_c_datatype (string const &column_name) const
	Returns a identifying integer value representing the C type of this column by name.

bool	column_unsigned (short column) const
	SQL_TRUE if the column is unsigned (or not numeric).

bool	column_unsigned (string const &column_name) const
	SQL_TRUE if the column is unsigned (or not numeric).

bool	next_result ()
	Returns the next result, e.g. when stored procedure returns multiple result sets.

	operator bool () const noexcept
	If and only if result object is valid, returns true.

Detailed Description

A resource for managing result sets from statement execution.

See also: statement::execute(), statement::execute_direct()

Note: result objects may be copied, however all copies will refer to the same result set.

Member Function Documentation

◆ affected_rows()

long nanodbc::result::affected_rows ( ) const

Number of affected rows by the request or -1 if the affected rows is not available.

Exceptions

database_error

◆ has_affected_rows()

bool nanodbc::result::has_affected_rows ( ) const

Reports if number of affected rows is available.

Returns: true if number of affected rows is known, regardless of the value; false if the number is not available.

Exceptions

database_error

{

assert(r.has_affected_rows() == (r.affected_rows() >= 0));

}

◆ columns()

short nanodbc::result::columns ( ) const

Returns the number of columns in a result set.

Exceptions

database_error

◆ first()

bool nanodbc::result::first ( )

Fetches the first row in the current result set.

Returns: true if there are more results or false otherwise.

Exceptions

database_error

◆ last()

bool nanodbc::result::last ( )

Fetches the last row in the current result set.

Returns: true if there are more results or false otherwise.

Exceptions

database_error

◆ next()

bool nanodbc::result::next ( )

Fetches the next row in the current result set.

Returns: true if there are more results or false otherwise.

Exceptions

database_error

◆ async_next()

bool nanodbc::result::async_next ( void * event_handle )

Initiates an asynchronous fetch of the next row in the current result set.

Returns: true if the caller needs to wait for the event to be signalled, false if complete_next() can be called immediately.

Exceptions

database_error

◆ complete_next()

bool nanodbc::result::complete_next ( )

Completes a previously-initiated async fetch for next row in the current result set.

Returns: true if there are more results or false otherwise.

Exceptions

database_error

◆ prior()

bool nanodbc::result::prior ( )

Fetches the prior row in the current result set.

Returns: true if there are more results or false otherwise.

Exceptions

database_error

◆ move()

bool nanodbc::result::move ( long row )

Moves to and fetches the specified row in the current result set.

Returns: true if there are results or false otherwise.

Exceptions

database_error

◆ skip()

bool nanodbc::result::skip ( long rows )

Skips a number of rows and then fetches the resulting row in the current result set.

Returns: true if there are results or false otherwise.

Exceptions

database_error

◆ unbind() [1/3]

void nanodbc::result::unbind ( )

Unbind data buffers for all columns in the result set.

Wraps unbind(short column)

Exceptions

index_range_error
database_error

◆ unbind() [2/3]

void nanodbc::result::unbind ( string const & column_name )

Unbind data buffers for specific columns in the result set.

Wraps unbind(short column)

Parameters

column_name string Name of column we wish to unbind.

Exceptions

index_range_error
database_error

◆ unbind() [3/3]

void nanodbc::result::unbind ( short column )

Unbind data buffers for specific columns in the result set.

When a result is constructed, in order to optimize data retrieval, we automatically try to bind buffers, except for columns that contain long/blob data types. This method gives the caller the option to unbind a specific buffer. Subsequently, during calls to get(), if there is no bound data buffer, we will attempt to retrieve the data using a call SQLGetData; this is similar to the route taken for columns hosting long or bloby data types. This is suboptimal from efficiency perspective, however may be necessary of the driver we are communicating with does not support out-of-order retrieval of long data.

Parameters

column short Zero-based index of column we wish to unbind.

Exceptions

index_range_error
database_error

◆ is_null() [1/2]

bool nanodbc::result::is_null ( short column ) const

Returns true if and only if the given column of the current rowset is null.

A long column is not bound to a buffer, and most drivers leave its length/indicator unwritten at fetch even where the ODBC specification says binding the indicator alone is enough. A binary one is asked of the driver instead, which costs a call to SQLGetData asking for none of the data: the value is left where it is, so a get() or get_ref() afterwards still returns the whole of it, but it counts as visiting the column, and SQL Server requires unbound columns be visited in ascending order and refuses an earlier one afterwards with SQLSTATE 07009. Ask in the order you intend to read.

A character or fixed size column cannot be asked without spending the only read there is, so for those this reports whatever the fetch knew until a get() or get_ref() settles it. Where the driver declines to answer at all, the same applies rather than raising.

Columns are numbered from left to right and 0-indexed.

See also: get(), get_ref()

Parameters

column position.

Exceptions

database_error
index_range_error

◆ is_null() [2/2]

bool nanodbc::result::is_null ( string const & column_name ) const

Returns true if and only if the given column by name of the current rowset is null.

See is_null(short column) for details on a bug/limitation of some ODBC drivers.

See also: is_null()

Parameters

column_name column's name.

Exceptions

database_error
index_range_error

◆ is_bound() [1/2]

bool nanodbc::result::is_bound ( short column ) const

Returns true if we have bound a buffer to the given column.

Generically, nanodbc will greedily bind buffers to columns in the result set. However, we have also given the user the ability to unbind buffers via unbind() forcing nanodbc to retrieve data via SQLGetData. This method returns true if there is a buffer bound to the column.

Columns are numbered from left to right and 0-indexed.

Parameters

column short position.

Exceptions

index_range_error

◆ is_bound() [2/2]

bool nanodbc::result::is_bound ( string const & column_name ) const

Returns true if we have bound a buffer to the given column.

See is_bound(short column) for details.

See also: is_bound()

Parameters

column_name column's name.

Exceptions

index_range_error

◆ column()

short nanodbc::result::column ( string const & column_name ) const

Returns the column number of the specified column name.

Columns are numbered from left to right and 0-indexed.

Parameters

column_name column's name.

Exceptions

index_range_error

◆ column_name()

string nanodbc::result::column_name ( short column ) const

Returns the name of the specified column.

Columns are numbered from left to right and 0-indexed.

Parameters

column position.

Exceptions

index_range_error

◆ column_size()

long nanodbc::result::column_size ( short column ) const

Returns the size of the specified column.

Columns are numbered from left to right and 0-indexed.

Parameters

column position.

Exceptions

index_range_error

◆ column_decimal_digits()

int nanodbc::result::column_decimal_digits ( short column ) const

Returns the number of decimal digits of the specified column.

Applies to exact numeric types (scale), datetime and interval types (prcision). If the number cannot be determined or is not applicable, drivers typically return 0.

Columns are numbered from left to right and 0-indexed.

Parameters

column position.

Exceptions

index_range_error

◆ column_datatype_name() [1/2]

string nanodbc::result::column_datatype_name ( short column ) const

Returns data source dependent data type name of this column.

The function calls SQLCoLAttribute with the field attribute SQL_DESC_TYPE_NAME to obtain the data type name. If the type is unknown, an empty string is returned.

Note: Unlike other column metadata functions (eg. column_datatype()), this function cost is an extra ODBC API call.

◆ column_datatype_name() [2/2]

string nanodbc::result::column_datatype_name ( string const & column_name ) const

Returns data source dependent data type name of this column by name.

The function calls SQLCoLAttribute with the field attribute SQL_DESC_TYPE_NAME to obtain the data type name. If the type is unknown, an empty string is returned.

Note: Unlike other column metadata functions (eg. column_datatype()), this function cost is an extra ODBC API call.

◆ column_unsigned() [1/2]

bool nanodbc::result::column_unsigned ( short column ) const

SQL_TRUE if the column is unsigned (or not numeric).

SQL_FALSE if the column is signed.

Signedness of some of numeric types like SQL_TINYINT depends on backend or driver. For example, if nmot unsigned, the MySQL TINYINT datatype can range from -127 to 127; whereas the SQL Server TINYINT type always ranges 0 to 255. So, unless it is an unsigned TINYINT, a MySQL TINYINT datatype should be converted to the SQL Server SMALLINT datatype.

◆ column_unsigned() [2/2]

bool nanodbc::result::column_unsigned ( string const & column_name ) const

SQL_TRUE if the column is unsigned (or not numeric).

SQL_FALSE if the column is signed.

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

/home/runner/work/nanodbc/nanodbc/nanodbc/nanodbc.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ affected_rows()

◆ has_affected_rows()

◆ columns()

◆ first()

◆ last()

◆ next()

◆ async_next()

◆ complete_next()

◆ prior()

◆ move()

◆ skip()

◆ unbind() [1/3]

◆ unbind() [2/3]

◆ unbind() [3/3]

◆ is_null() [1/2]

◆ is_null() [2/2]

◆ is_bound() [1/2]

◆ is_bound() [2/2]

◆ column()

◆ column_name()

◆ column_size()

◆ column_decimal_digits()

◆ column_datatype_name() [1/2]

◆ column_datatype_name() [2/2]

◆ column_unsigned() [1/2]

◆ column_unsigned() [2/2]