nanodbc::statement Class Reference

Represents a statement on the database. More...

#include <nanodbc.h>

Public Types
enum	param_direction { PARAM_IN , PARAM_OUT , PARAM_INOUT , PARAM_RETURN }
	Provides support for retrieving output/return parameters. More...

Public Member Functions
	statement ()
	Creates a new un-prepared statement.
	statement (class connection &conn)
	Constructs a statement object and associates it to the given connection.
	statement (class connection &conn, std::list< attribute > const &attributes)
	Constructs a statement object and associates it to the given connection, applying the given ODBC statement attributes.
	statement (class connection &conn, string const &query, long timeout=0)
	Constructs and prepares a statement using the given connection and query.
	statement (const statement &rhs) noexcept
	Copy constructor.
	statement (statement &&rhs) noexcept
	Move constructor.
statement &	operator= (statement rhs) noexcept
	Assignment.
void	swap (statement &rhs) noexcept
	Member swap.
	~statement () noexcept
	Closes the statement.
void	open (class connection &conn)
	Creates a statement for the given connection.
bool	open () const noexcept
	Returns true if connection is open.
bool	connected () const noexcept
	Returns true if connected to the database.
class connection &	connection () noexcept
	Returns the associated connection object if any.
const class connection &	connection () const noexcept
	Returns the associated connection object if any.
void *	native_statement_handle () const noexcept
	Returns the native ODBC statement handle.
void	close ()
	Closes the statement and frees all associated resources.
void	cancel ()
	Cancels execution of the statement.
void	prepare (class connection &conn, string const &query, long timeout=0)
	Opens and prepares the given statement to execute on the given connection.
void	prepare (string const &query, long timeout=0)
	Prepares the given statement to execute its associated connection.
void	timeout (long timeout=0)
	Sets the number in seconds before query timeout.
class result	execute_direct (class connection &conn, string const &query, long batch_operations=1, long timeout=0)
	Opens, prepares, and executes the given query directly on the given connection.
class result	execute_direct (class connection &conn, string const &query, batch_ops const &array_sizes, long timeout=0)
	Opens, prepares, and executes the given query directly on the given connection.
bool	async_prepare (string const &query, void *event_handle, long timeout=0)
	Prepare the given statement, in asynchronous mode.
void	complete_prepare ()
	Completes a previously initiated asynchronous query preparation.
bool	async_execute_direct (class connection &conn, void *event_handle, string const &query, long batch_operations=1, long timeout=0)
	Opens, prepares, and executes query directly on the given connection, in async mode.
bool	async_execute (void *event_handle, long batch_operations=1, long timeout=0)
	Execute the previously prepared query now, in asynchronous mode.
class result	complete_execute (long batch_operations=1)
	Completes a previously initiated asynchronous query execution, returning the result.
void	enable_async (void *event_handle)
	undocumented - for internal use only (used from result_impl)
void	disable_async () const
	undocumented - for internal use only (used from result_impl)
void	just_execute_direct (class connection &conn, string const &query, long batch_operations=1, long timeout=0)
	Execute the previously prepared query now without constructing result object.
class result	execute (long batch_operations=1, long timeout=0)
	Execute the previously prepared query now.
void	just_execute (long batch_operations=1, long timeout=0)
	Execute the previously prepared query now without constructing result object.
class result	procedure_columns (string const &catalog, string const &schema, string const &procedure, string const &column)
	Returns the input and output paramters of the specified stored procedure.
long	affected_rows () const
	Returns rows affected by the request or -1 if affected rows is not available.
short	columns () const
	Returns the number of columns in a result set.
void	reset_parameters () noexcept
	Resets all currently bound parameters.
short	parameters () const
	Returns the number of parameters in the statement.
unsigned long	parameter_size (short param_index) const
	Returns parameter size for indicated parameter placeholder in a prepared statement.
short	parameter_scale (short param_index) const
	Returns parameter scale for indicated parameter placeholder in a prepared statement.
short	parameter_type (short param_index) const
	Returns parameter type for indicated parameter placeholder in a prepared statement.
template<class T >
void	bind (short param_index, T const *value, param_direction direction=PARAM_IN)
	Binds given value to given parameter placeholder number in the prepared statement.
template<class T >
void	bind (short param_index, T const *values, std::size_t batch_size, param_direction direction=PARAM_IN)
	Binds multiple values.
template<class T >
void	bind (short param_index, T const *values, std::size_t batch_size, T const *null_sentry, param_direction direction=PARAM_IN)
	Binds multiple values.
template<class T >
void	bind (short param_index, T const *values, std::size_t batch_size, bool const *nulls, param_direction direction=PARAM_IN)
	Binds multiple values.
void	bind (short param_index, std::vector< std::vector< uint8_t > > const &values, param_direction direction=PARAM_IN)
	Binds multiple values.
void	bind (short param_index, std::vector< std::vector< uint8_t > > const &values, bool const *nulls, param_direction direction=PARAM_IN)
	Binds multiple values.
void	bind (short param_index, std::vector< std::vector< uint8_t > > const &values, uint8_t const *null_sentry, param_direction direction=PARAM_IN)
	Binds multiple values.
template<class T , typename = enable_if_character<T>>
void	bind_strings (short param_index, T const *values, std::size_t value_size, std::size_t batch_size, param_direction direction=PARAM_IN)
	Binds multiple string values.
template<class T , typename = enable_if_string<T>>
void	bind_strings (short param_index, std::vector< T > const &values, param_direction direction=PARAM_IN)
	Binds multiple string values.
template<std::size_t BatchSize, std::size_t ValueSize, class T , typename = enable_if_character<T>>
void	bind_strings (short param_index, T const (&values)[BatchSize][ValueSize], param_direction direction=PARAM_IN)
	Binds multiple string values.
template<class T , typename = enable_if_character<T>>
void	bind_strings (short param_index, T const *values, std::size_t value_size, std::size_t batch_size, T const *null_sentry, param_direction direction=PARAM_IN)
	Binds multiple string values.
template<class T , typename = enable_if_string<T>>
void	bind_strings (short param_index, std::vector< T > const &values, typename T::value_type const *null_sentry, param_direction direction=PARAM_IN)
	Binds multiple string values.
template<std::size_t BatchSize, std::size_t ValueSize, class T , typename = enable_if_character<T>>
void	bind_strings (short param_index, T const (&values)[BatchSize][ValueSize], T const *null_sentry, param_direction direction=PARAM_IN)
	Binds multiple string values.
template<class T , typename = enable_if_character<T>>
void	bind_strings (short param_index, T const *values, std::size_t value_size, std::size_t batch_size, bool const *nulls, param_direction direction=PARAM_IN)
	Binds multiple string values.
template<class T , typename = enable_if_string<T>>
void	bind_strings (short param_index, std::vector< T > const &values, bool const *nulls, param_direction direction=PARAM_IN)
	Binds multiple string values.
template<std::size_t BatchSize, std::size_t ValueSize, class T , typename = enable_if_character<T>>
void	bind_strings (short param_index, T const (&values)[BatchSize][ValueSize], bool const *nulls, param_direction direction=PARAM_IN)
	Binds multiple string values.
void	bind_null (short param_index, std::size_t batch_size=1)
	Binds null values to the parameter placeholder number in the prepared statement.
void	describe_parameters (const std::vector< short > &idx, const std::vector< short > &type, const std::vector< unsigned long > &size, const std::vector< short > &scale)
	Sets descriptions for parameters in the prepared statement.

Detailed Description

Represents a statement on the database.

Member Enumeration Documentation

param_direction

enum nanodbc::statement::param_direction

Provides support for retrieving output/return parameters.

See also

Binding parameters

Enumerator
PARAM_IN	Binding an input parameter.
PARAM_OUT	Binding an output parameter.
PARAM_INOUT	Binding an input/output parameter.
PARAM_RETURN	Binding a procedure's return value, at parameter zero of a { ? = CALL proc(?) } escape sequence.

Constructor & Destructor Documentation

statement() [1/4]

nanodbc::statement::statement

(

)

Creates a new un-prepared statement.

See also

execute(), just_execute(), execute_direct(), just_execute_direct(), open(), prepare()

statement() [2/4]

nanodbc::statement::statement ( class connection &  conn )

explicit

Constructs a statement object and associates it to the given connection.

Parameters

conn	The connection to use.

See also

open(), prepare()

statement() [3/4]

nanodbc::statement::statement ( class connection &  conn, std::list< attribute > const &  attributes  )

explicit

Constructs a statement object and associates it to the given connection, applying the given ODBC statement attributes.

Parameters

conn	The connection to use.
attributes	Statement attributes to set before the statement is used.

See also

open(), prepare()

statement() [4/4]

nanodbc::statement::statement	(	class connection &	conn,
		string const &	query,
		long	timeout = 0
	)

Constructs and prepares a statement using the given connection and query.

Parameters

conn	The connection to use.
query	The SQL query statement.
timeout	The number in seconds before query timeout. Default: 0 meaning no timeout.

See also

execute(), just_execute(), execute_direct(), just_execute_direct(), open(), prepare()

~statement()

nanodbc::statement::~statement ( )

noexcept

Closes the statement.

See also

close()

Member Function Documentation

open()

void nanodbc::statement::open

(

class connection &

conn

)

Creates a statement for the given connection.

Parameters

conn	The connection where the statement will be executed.

Exceptions

database_error

cancel()

void nanodbc::statement::cancel

(

)

Cancels execution of the statement.

Exceptions

database_error

prepare() [1/2]

void nanodbc::statement::prepare	(	class connection &	conn,
		string const &	query,
		long	timeout = 0
	)

Opens and prepares the given statement to execute on the given connection.

Parameters

conn	The connection where the statement will be executed.
query	The SQL query that will be executed.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

See also

open()

Exceptions

database_error

prepare() [2/2]

void nanodbc::statement::prepare	(	string const &	query,
		long	timeout = 0
	)

Prepares the given statement to execute its associated connection.

Note

If the statement is not open throws programming_error.

Parameters

query	The SQL query that will be executed.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

See also

open()

Exceptions

database_error
programming_error

timeout()

void nanodbc::statement::timeout

(

long

timeout = 0

)

Sets the number in seconds before query timeout.

Default is 0 indicating no timeout.

Exceptions

database_error

execute_direct() [1/2]

class result nanodbc::statement::execute_direct	(	class connection &	conn,
		string const &	query,
		long	batch_operations = 1,
		long	timeout = 0
	)

Opens, prepares, and executes the given query directly on the given connection.

Parameters

conn	The connection where the statement will be executed.
query	The SQL query that will be executed.
batch_operations	Numbers of rows to fetch per rowset, or the number of batch parameters to process.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

Returns

A result set object.

Attention

You will want to use transactions if you are doing batch operations because it will prevent auto commits occurring after each individual operation is executed.

See also

open(), prepare(), execute(), result, transaction

execute_direct() [2/2]

class result nanodbc::statement::execute_direct	(	class connection &	conn,
		string const &	query,
		batch_ops const &	array_sizes,
		long	timeout = 0
	)

Opens, prepares, and executes the given query directly on the given connection.

Parameters

conn	The connection where the statement will be executed.
query	The SQL query that will be executed.
array_sizes	More granular control of rows to fetch per rowset, and the number of batch parameters to process.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

Returns

A result set object.

Attention

You will want to use transactions if you are doing batch operations because it will prevent auto commits occurring after each individual operation is executed.

See also

open(), prepare(), execute(), result, transaction

async_prepare()

bool nanodbc::statement::async_prepare	(	string const &	query,
		void *	event_handle,
		long	timeout = 0
	)

Prepare the given statement, in asynchronous mode.

Note

If the statement is not open throws programming_error.

This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. Such that the identifiers SQL_ATTR_ASYNC_STMT_EVENT and SQLCompleteAsync are extant. Otherwise this method will be defined, but not implemented.

Asynchronous features can be disabled entirely by defining NANODBC_DISABLE_ASYNC when building nanodbc.

Parameters

event_handle	The event handle the caller will wait before calling complete_prepare.
query	The SQL query that will be prepared.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

Exceptions

database_error

Returns

Boolean: true if the event handle needs to be awaited, false is result is ready now.

See also

complete_prepare()

complete_prepare()

void nanodbc::statement::complete_prepare

(

)

Completes a previously initiated asynchronous query preparation.

This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. Such that the identifiers SQL_ATTR_ASYNC_STMT_EVENT and SQLCompleteAsync are extant. Otherwise this method will be defined, but not implemented.

Asynchronous features can be disabled entirely by defining NANODBC_DISABLE_ASYNC when building nanodbc.

Exceptions

database_error

See also

async_prepare()

async_execute_direct()

bool nanodbc::statement::async_execute_direct	(	class connection &	conn,
		void *	event_handle,
		string const &	query,
		long	batch_operations = 1,
		long	timeout = 0
	)

Opens, prepares, and executes query directly on the given connection, in async mode.

This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. Such that the identifiers SQL_ATTR_ASYNC_STMT_EVENT and SQLCompleteAsync are extant. Otherwise this method will be defined, but not implemented.

Asynchronous features can be disabled entirely by defining NANODBC_DISABLE_ASYNC when building nanodbc.

Parameters

conn	The connection where the statement will be executed.
event_handle	The event handle the caller will wait before calling complete_execute.
query	The SQL query that will be executed.
batch_operations	Rows to fetch per rowset or number of batch parameters to process.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

Exceptions

database_error

Returns

Boolean: true if event handle needs to be awaited, false if result ready now.

Attention

You will want to use transactions if you are doing batch operations because it will prevent auto commits after each individual operation is executed.

See also

complete_execute(), open(), prepare(), execute(), result, transaction

async_execute()

bool nanodbc::statement::async_execute	(	void *	event_handle,
		long	batch_operations = 1,
		long	timeout = 0
	)

Execute the previously prepared query now, in asynchronous mode.

This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. Such that the identifiers SQL_ATTR_ASYNC_STMT_EVENT and SQLCompleteAsync are extant. Otherwise this method will be defined, but not implemented.

Asynchronous features can be disabled entirely by defining NANODBC_DISABLE_ASYNC when building nanodbc.

Parameters

event_handle	The event handle the caller will wait before calling complete_execute.
batch_operations	Rows to fetch per rowset or number of batch parameters to process.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

Exceptions

database_error

Returns

Boolean: true if event handle needs to be awaited, false if result is ready now.

Attention

You will want to use transactions if you are doing batch operations because it will prevent auto commits after each individual operation is executed.

See also

complete_execute(), open(), prepare(), result, transaction

complete_execute()

class result nanodbc::statement::complete_execute

(

long

batch_operations = 1

)

Completes a previously initiated asynchronous query execution, returning the result.

This method will only be available if nanodbc is built against ODBC headers and library that supports asynchronous mode. Such that the identifiers SQL_ATTR_ASYNC_STMT_EVENT and SQLCompleteAsync are extant. Otherwise this method will be defined, but not implemented.

Asynchronous features can be disabled entirely by defining NANODBC_DISABLE_ASYNC when building nanodbc.

Exceptions

database_error

Returns

A result set object.

Parameters

batch_operations

Rows to fetch per rowset or number of batch parameters to process.

See also

async_execute(), async_execute_direct()

just_execute_direct()

void nanodbc::statement::just_execute_direct	(	class connection &	conn,
		string const &	query,
		long	batch_operations = 1,
		long	timeout = 0
	)

Execute the previously prepared query now without constructing result object.

Parameters

conn	The connection where the statement will be executed.
query	The SQL query that will be executed.
batch_operations	Rows to fetch per rowset, or number of batch parameters to process.
timeout	Seconds before query timeout. Default is 0 indicating no timeout.

Exceptions

database_error

Attention

You will want to use transactions if you are doing batch operations because it will prevent auto commits after each individual operation is executed.

See also

open(), prepare(), execute(), execute_direct(), result, transaction

execute()

class result nanodbc::statement::execute	(	long	batch_operations = 1,
		long	timeout = 0
	)

Execute the previously prepared query now.

Parameters

batch_operations	Rows to fetch per rowset, or number of batch parameters to process.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

Exceptions

database_error

Returns

A result set object.

Attention

You will want to use transactions if you are doing batch operations because it will prevent auto commits after each individual operation is executed.

See also

open(), prepare(), result, transaction

just_execute()

void nanodbc::statement::just_execute	(	long	batch_operations = 1,
		long	timeout = 0
	)

Execute the previously prepared query now without constructing result object.

Parameters

batch_operations	Rows to fetch per rowset, or number of batch parameters to process.
timeout	The number in seconds before query timeout. Default 0 meaning no timeout.

Exceptions

database_error

Attention

You will want to use transactions if you are doing batch operations because it will prevent auto commits after each individual operation is executed.

See also

open(), prepare(), execute(), result, transaction

procedure_columns()

class result nanodbc::statement::procedure_columns	(	string const &	catalog,
		string const &	schema,
		string const &	procedure,
		string const &	column
	)

Returns the input and output paramters of the specified stored procedure.

Parameters

catalog	The catalog name of the procedure.
schema	Pattern to use for schema names.
procedure	The name of the procedure.
column	Pattern to use for column names.

Exceptions

database_error

Returns

A result set object.

affected_rows()

long nanodbc::statement::affected_rows

(

)

const

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

Exceptions

database_error

columns()

short nanodbc::statement::columns

(

)

const

Returns the number of columns in a result set.

Exceptions

database_error

parameters()

short nanodbc::statement::parameters

(

)

const

Returns the number of parameters in the statement.

Exceptions

database_error

describe_parameters()

void nanodbc::statement::describe_parameters	(	const std::vector< short > &	idx,
		const std::vector< short > &	type,
		const std::vector< unsigned long > &	size,
		const std::vector< short > &	scale
	)

Sets descriptions for parameters in the prepared statement.

If your prepared SQL query has any parameter markers, ? (question mark) placeholders this is how you can describe the SQL type, size and scale for some or all of the parameters, prior to binding any data to the parameters. Calling this method is optional: if a parameter is not described using a call to this method, then during a bind an attempt is made to identify it using a call to the ODBC SQLDescribeParam API handle. Once set, description is re-used for possibly repeated binds execution and only cleared when the statement is cleared / destroyed. Parameter markers are numbered using Zero-based index from left to right.

Parameters

idx	Vector of zero-based indices of parameters we are describing.
type	Vector of (short integer) types.
size	Vector of (unsigned long) sizes.
scale	Vector of (short integer) decimal precision / scale.

Exceptions

programming_error

---

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

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