View on GitHub API Documentation
A small C++ wrapper for the native C ODBC API.
Public Types | Public Member Functions | Friends | List of all members
nanodbc::statement Class Reference

Represents a statement on the database.

#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. More...
 
 statement (class connection &conn)
 Constructs a statement object and associates it to the given connection. More...
 
 statement (class connection &conn, const string &query, long timeout=0)
 Constructs and prepares a statement using the given connection and query. More...
 
 statement (const statement &rhs)
 Copy constructor.
 
 statement (statement &&rhs) NANODBC_NOEXCEPT
 Move constructor.
 
statementoperator= (statement rhs)
 Assignment.
 
void swap (statement &rhs) NANODBC_NOEXCEPT
 Member swap.
 
 ~statement () NANODBC_NOEXCEPT
 Closes the statement. More...
 
void open (class connection &conn)
 Creates a statement for the given connection. More...
 
bool open () const
 Returns true if connection is open.
 
bool connected () const
 Returns true if connected to the database.
 
class connectionconnection ()
 Returns the associated connection object if any.
 
const class connectionconnection () const
 Returns the associated connection object if any.
 
void * native_statement_handle () const
 Returns the native ODBC statement handle.
 
void close ()
 Closes the statement and frees all associated resources.
 
void cancel ()
 Cancels execution of the statement. More...
 
void prepare (class connection &conn, const string &query, long timeout=0)
 Opens and prepares the given statement to execute on the given connection. More...
 
void prepare (const string &query, long timeout=0)
 Prepares the given statement to execute its associated connection. More...
 
void timeout (long timeout=0)
 Sets the number in seconds before query timeout. Default is 0 indicating no timeout. More...
 
class result execute_direct (class connection &conn, const string &query, long batch_operations=1, long timeout=0)
 Opens, prepares, and executes the given query directly on the given connection. More...
 
bool async_prepare (const string &query, void *event_handle, long timeout=0)
 Prepare the given statement, in asynchronous mode. More...
 
void complete_prepare ()
 Completes a previously initiated asynchronous query preparation. More...
 
bool async_execute_direct (class connection &conn, void *event_handle, const string &query, long batch_operations=1, long timeout=0)
 Opens, prepares, and executes query directly on the given connection, in async mode. More...
 
bool async_execute (void *event_handle, long batch_operations=1, long timeout=0)
 Execute the previously prepared query now, in asynchronous mode. More...
 
class result complete_execute (long batch_operations=1)
 Completes a previously initiated asynchronous query execution, returning the result. More...
 
NANODBC_DEPRECATED class result async_complete (long batch_operations=1)
 Completes a previously initiated asynchronous query execution, returning the result. More...
 
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, const string &query, long batch_operations=1, long timeout=0)
 Execute the previously prepared query now without constructing result object. More...
 
class result execute (long batch_operations=1, long timeout=0)
 Execute the previously prepared query now. More...
 
void just_execute (long batch_operations=1, long timeout=0)
 Execute the previously prepared query now without constructing result object. More...
 
class result procedure_columns (const string &catalog, const string &schema, const string &procedure, const string &column)
 Returns the input and output paramters of the specified stored procedure. More...
 
long affected_rows () const
 Returns rows affected by the request or -1 if affected rows is not available. More...
 
short columns () const
 Returns the number of columns in a result set. More...
 
void reset_parameters () NANODBC_NOEXCEPT
 Resets all currently bound parameters.
 
short parameters () const
 Returns the number of parameters in the statement. More...
 
unsigned long parameter_size (short param_index) const
 Returns parameter size 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. More...
 
template<class T >
void bind (short param_index, T const *values, std::size_t batch_size, param_direction direction=PARAM_IN)
 Binds multiple values. More...
 
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. More...
 
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. More...
 
void bind (short param_index, std::vector< std::vector< uint8_t >> const &values, param_direction direction=PARAM_IN)
 Binds multiple values. More...
 
void bind (short param_index, std::vector< std::vector< uint8_t >> const &values, bool const *nulls, param_direction direction=PARAM_IN)
 Binds multiple values. More...
 
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. More...
 
void bind_strings (short param_index, string::value_type const *values, std::size_t value_size, std::size_t batch_size, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
void bind_strings (short param_index, std::vector< string > const &values, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
template<std::size_t BatchSize, std::size_t ValueSize>
void bind_strings (short param_index, string::value_type const (&values)[BatchSize][ValueSize], param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
void bind_strings (short param_index, string::value_type const *values, std::size_t value_size, std::size_t batch_size, string::value_type const *null_sentry, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
void bind_strings (short param_index, std::vector< string > const &values, string::value_type const *null_sentry, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
template<std::size_t BatchSize, std::size_t ValueSize>
void bind_strings (short param_index, string::value_type const (&values)[BatchSize][ValueSize], string::value_type const *null_sentry, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
void bind_strings (short param_index, string::value_type const *values, std::size_t value_size, std::size_t batch_size, bool const *nulls, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
void bind_strings (short param_index, std::vector< string > const &values, bool const *nulls, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
template<std::size_t BatchSize, std::size_t ValueSize>
void bind_strings (short param_index, string::value_type const (&values)[BatchSize][ValueSize], bool const *nulls, param_direction direction=PARAM_IN)
 Binds multiple string values. More...
 
void bind_null (short param_index, std::size_t batch_size=1)
 Binds null values to the parameter placeholder number in the prepared statement. More...
 

Friends

class nanodbc::result
 

Member Enumeration Documentation

◆ param_direction

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 return parameter.

Constructor & Destructor Documentation

◆ statement() [1/3]

nanodbc::statement::statement ( )

◆ statement() [2/3]

nanodbc::statement::statement ( class connection conn)
explicit
Parameters
connThe connection to use.
See also
open(), prepare()

◆ statement() [3/3]

nanodbc::statement::statement ( class connection conn,
const string query,
long  timeout = 0 
)
Parameters
connThe connection to use.
queryThe SQL query statement.
timeoutThe 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 ( )
See also
close()

Member Function Documentation

◆ affected_rows()

long nanodbc::statement::affected_rows ( ) const
Exceptions
database_error

◆ async_complete()

NANODBC_DEPRECATED class result nanodbc::statement::async_complete ( long  batch_operations = 1)
Deprecated:
Use complete_execute instead.

◆ async_execute()

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

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_handleThe event handle the caller will wait before calling complete_execute.
batch_operationsRows to fetch per rowset or number of batch parameters to process.
timeoutThe 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

◆ async_execute_direct()

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

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
connThe connection where the statement will be executed.
event_handleThe event handle the caller will wait before calling complete_execute.
queryThe SQL query that will be executed.
batch_operationsRows to fetch per rowset or number of batch parameters to process.
timeoutThe 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_prepare()

bool nanodbc::statement::async_prepare ( const string query,
void *  event_handle,
long  timeout = 0 
)
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_handleThe event handle the caller will wait before calling complete_prepare.
queryThe SQL query that will be prepared.
timeoutThe 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()

◆ cancel()

void nanodbc::statement::cancel ( )
Exceptions
database_error

◆ columns()

short nanodbc::statement::columns ( ) const
Exceptions
database_error

◆ complete_execute()

class result nanodbc::statement::complete_execute ( long  batch_operations = 1)

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_operationsRows to fetch per rowset or number of batch parameters to process.
See also
async_execute(), async_execute_direct()

◆ complete_prepare()

void nanodbc::statement::complete_prepare ( )

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()

◆ execute()

class result nanodbc::statement::execute ( long  batch_operations = 1,
long  timeout = 0 
)
Parameters
batch_operationsRows to fetch per rowset, or number of batch parameters to process.
timeoutThe 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

◆ execute_direct()

class result nanodbc::statement::execute_direct ( class connection conn,
const string query,
long  batch_operations = 1,
long  timeout = 0 
)
Parameters
connThe connection where the statement will be executed.
queryThe SQL query that will be executed.
batch_operationsNumbers of rows to fetch per rowset, or the number of batch parameters to process.
timeoutThe 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

◆ just_execute()

void nanodbc::statement::just_execute ( long  batch_operations = 1,
long  timeout = 0 
)
Parameters
batch_operationsRows to fetch per rowset, or number of batch parameters to process.
timeoutThe 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(), execute(), result, transaction

◆ just_execute_direct()

void nanodbc::statement::just_execute_direct ( class connection conn,
const string query,
long  batch_operations = 1,
long  timeout = 0 
)
Parameters
connThe connection where the statement will be executed.
queryThe SQL query that will be executed.
batch_operationsRows to fetch per rowset, or number of batch parameters to process.
timeoutSeconds before query timeout. Default is 0 indicating 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(), execute(), execute_direct(), result, transaction

◆ open()

void nanodbc::statement::open ( class connection conn)
Parameters
connThe connection where the statement will be executed.
Exceptions
database_error

◆ parameters()

short nanodbc::statement::parameters ( ) const
Exceptions
database_error

◆ prepare() [1/2]

void nanodbc::statement::prepare ( class connection conn,
const string query,
long  timeout = 0 
)
Parameters
connThe connection where the statement will be executed.
queryThe SQL query that will be executed.
timeoutThe number in seconds before query timeout. Default 0 meaning no timeout.
See also
open()
Exceptions
database_error

◆ prepare() [2/2]

void nanodbc::statement::prepare ( const string query,
long  timeout = 0 
)
Note
If the statement is not open throws programming_error.
Parameters
queryThe SQL query that will be executed.
timeoutThe number in seconds before query timeout. Default 0 meaning no timeout.
See also
open()
Exceptions
database_error,programming_error

◆ procedure_columns()

class result nanodbc::statement::procedure_columns ( const string catalog,
const string schema,
const string procedure,
const string column 
)
Parameters
catalogThe catalog name of the procedure.
schemaPattern to use for schema names.
procedureThe name of the procedure.
columnPattern to use for column names.
Exceptions
database_error
Returns
A result set object.

◆ timeout()

void nanodbc::statement::timeout ( long  timeout = 0)
Exceptions
database_error

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